Rulvar API reference

---

Rulvar API reference / @rulvar/testing / TestEngine

Interface: TestEngine

Defined in: packages/testing/src/test-engine.ts:27

Extends

• Engine

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
fake	public	FakeAdapter	The adapter instance, for call-level assertions.	-	packages/testing/src/test-engine.ts:30
store	public	InMemoryStore	The backing journal store (journal capture for replay-strict tests).	-	packages/testing/src/test-engine.ts:32
stores	readonly	{ journal: JournalStore; transcripts: TranscriptStore; }	The engine's configured stores, exposed for shells and hosts (M8 entry amendment: the journal store comes from the engine). Exactly the instances createEngine received, or the defaults it built; no store contract widens through this accessor. With a serialization hook configured these are the HOOKED wrappers, so every reader passes the one policy point (M8-T04).	Engine.stores	packages/core/dist/index.d.ts
stores.journal	public	JournalStore	-	-	packages/core/dist/index.d.ts
stores.transcripts	public	TranscriptStore	-	-	packages/core/dist/index.d.ts

Methods

deleteRun()

deleteRun(runId, opts?): Promise<void>;

Defined in: packages/core/dist/index.d.ts

Retention (OQ-20 executed at M8-T04): deletes every blob transcripts.list(runId) returns, then the journal; no orphan blobs survive. The caller owns the decision that the run is done. A caller holding the run's lease passes it via opts.lease (the queue worker's retention path does), so a fencedWrites store refuses the cascade from a superseded holder; without a lease the deletes assert the single-writer precondition as before.

Parameters

Parameter	Type
runId	string
opts?	{ lease?: Lease; }
opts.lease?	Lease

Returns

Promise<void>

Inherited from

Engine.deleteRun

---

exportRun()

exportRun(runId): Promise<RunExport>;

Defined in: packages/core/dist/index.d.ts

Portable run export (RV-217): the meta record, every journal entry, and every transcript blob, read through Engine.stores (the one policy point), so an encrypted deployment exports PLAINTEXT for a subject-access request or a store migration, without raw store spelunking. Blobs are materialized in memory; export runs one at a time, not catalogs.

Parameters

Parameter	Type
runId	string

Returns

Promise<RunExport>

Inherited from

Engine.exportRun

---

importRun()

importRun(bundle, options?): Promise<{
  unresolvedRefs: string[];
}>;

Defined in: packages/core/dist/index.d.ts

Imports an exportRun bundle into this engine's stores. Returns the closure report (RV1511): every transcript, checkpoint, artifact, and workflow-source ref the ENTRIES (and meta) reference that no bundle blob carries. The default import stays permissive (the historical shape: retention and pruning legitimately drop blobs their entries still name) and the report makes the gap visible; requireClosure: true refuses typed BEFORE any write instead. A duplicate blob ref in the bundle always refuses: last-write-wins is not an import.

Parameters

Parameter	Type
bundle	RunExport
options?	{ requireClosure?: boolean; }
options.requireClosure?	boolean

Returns

Promise<{ unresolvedRefs: string[]; }>

Inherited from

Engine.importRun

---

profileCard()

profileCard(names?): string;

Defined in: packages/core/dist/index.d.ts

Renders the registered agent profiles into the shared vocabulary card, optionally filtered to names; the registry itself stays private to the engine (M6-T05 amendment). Unknown names are ignored.

Parameters

Parameter	Type
names?	readonly string[]

Returns

string

Inherited from

Engine.profileCard

---

pruneRun()

pruneRun(runId, opts?): Promise<number>;

Defined in: packages/core/dist/index.d.ts

Checkpoint pruning (OQ-20 executed at M8-T04): deletes checkpoint blobs of ok-terminal attempts that no other entry references; returns the count. Parked, cancelled, escalated, and hanging attempts keep theirs (park/unpark, DEF-5 retention, and dangling redispatch boot from them). opts.lease rides each blob delete exactly like the deleteRun cascade.

Parameters

Parameter	Type
runId	string
opts?	{ lease?: Lease; }
opts.lease?	Lease

Returns

Promise&lt;number&gt;

Inherited from

Engine.pruneRun

---

resume()

resume<A, R>(
   runId, 
   wf?, 
options?): ResumeHandle<R>;

Defined in: packages/core/dist/index.d.ts

Rebinds a journal to a workflow definition and resumes. Requires wf for in-process workflows; a name mismatch is a typed ConfigError; a body-hash mismatch warns loudly and proceeds (the journal decides replay per content keys), unless ResumeOptions.bodyHash is 'refuse', which makes it a typed ConfigError before any durable mutation (RV3001). A compiled run resumes WITHOUT wf: the engine rehydrates the persisted source pinned by workflowHash; supplying a compiled wf whose source hash differs from the recorded one is a typed ConfigError (M6-T02). ResumeOptions.run (RV2208) overrides the recorded budget ceilings for the run's remaining life, with a journaled decision and a typed floor at the settled spend; under a recorded budgetPolicy 'immutable-lifetime' (RV3902) any applying override refuses typed before ownership instead.

Type Parameters

Type Parameter
A
R

Parameters

Parameter	Type
runId	string
wf?	| Workflow<A, R> | CompiledWorkflow
options?	ResumeOptions

Returns

ResumeHandle&lt;R&gt;

Inherited from

Engine.resume

---

run()

run<A, R>(
   wf, 
   args, 
opts?): TestRunHandle<R>;

Defined in: packages/testing/src/test-engine.ts:28

Type Parameters

Type Parameter
A
R

Parameters

Parameter	Type
wf	Workflow<A, R>
args	A
opts?	RunOptions

Returns

TestRunHandle&lt;R&gt;

Overrides

Engine.run