Rulvar API reference / @rulvar/rulvar / Engine
Interface: Engine
Defined in: packages/core/dist/index.d.ts
Extended by
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
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). | 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>
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>
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[]; }>
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
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<number>
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? | | CompiledWorkflow | Workflow<A, R> |
options? | ResumeOptions |
Returns
ResumeHandle<R>
run()
run<A, R>(
wf,
args,
opts?): RunHandle<R>;Defined in: packages/core/dist/index.d.ts
Type Parameters
| Type Parameter |
|---|
A |
R |
Parameters
| Parameter | Type |
|---|---|
wf | | CompiledWorkflow | Workflow<A, R> |
args | A |
opts? | RunOptions |
Returns
RunHandle<R>