Interface Engine

Admin override — hard-stop an in-flight instance where it stands.

The actions firable on the instance's current stage, each flagged allowed/disabled, plus the evaluation they came from.

Spawned children of a parent instance, optionally filtered by the spawning activity. Sorted by startedAt asc.

Engine-scoped bindings — exposed for the few advanced consumers (e.g. test bench, drain workers) that need them; the verbs already thread them through internally.

Commit mid-dispatch field state from a running effect handler — the verb behind ctx.commitOps. Gated on the dispatch's exact claim token; a successful commit renews the claim's lease.

The startable half of Engine.instancesForDocument: the latest deployed version of every definition that applies to the LOADED candidate document — startable, the subject-kind entry accepts its _type, and start.filter (browse-time-pure — $fields never binds) passes. All matches, name ascending; advisory — a start picker's filter, never enforcement.

Admin override — remove a deployed definition (instances are only ever aborted, never deleted).

Diagnose why an instance is or isn't progressing — a classified DiagnoseResult plus the evaluation it was derived from.

Dispatch unclaimed effects through registered handlers — including entries whose claim's lease expired, which are taken over (audit row) and redispatched. The drainer's identity is the engine client's token — a drain runtime supplies its own token-bearing client and declares itself via executionContext. Release-without-dispatch housekeeping is the standalone sweepStaleClaims export, deliberately off the engine surface.

Edit a declared-editable field directly (the generic edit seam): reassign / reschedule / claim-by-hand / append-to-log, then cascade.

Project the instance from an actor's perspective — per-action verdicts with structured disabled reasons. Pure read.

Pre-flight startInstance's gates for a definition + the initialFields gathered so far: structurally invalid rows, every requirement's ordered descriptor/outcome/insight, and still-missing required inputs. allowed is the overall startability signal; outcome aggregates the requirements. Bindability-aware — a requirement reading a not-yet-supplied entry (including singleSubject's implicit subject read) reports 'unevaluable' with the entries named in unboundReads, never a collapsed verdict. Pure read; the enforcement moment is startInstance itself.

Filter pending effects by claimed status and/or effect names.

Fetch a workflow instance by id.

Every lake mutation guard a workflow deployed (any version), across the datasources its guards statically name — the workflow resource plus any literal-GDR field entries, unioned over all deployed versions. Needs no live instance. Guards whose resource is only known per-instance (input/runtime-sourced entries) are not reachable here — use Engine.guardsForInstance. For housekeeping. Takes the definition's name.

Every lake mutation guard this instance registered, unioned across the instance's own resource and the resource of each doc.ref/subject/doc.refs GDR it holds in state. For coherency refresh and housekeeping.

The reverse of Engine.subscriptionDocumentsForInstance: every in-flight instance whose watch-set includes document (a resource-qualified GDR URI). For a non-reactive, content-change-driven runtime deciding which instances a changed doc should tick. Matches the same ref set the forward watch-set uses (self, ancestors, current-stage doc.ref/subject/doc.refs/release.ref) via the shared collectWatchRefs. Sorted by startedAt asc.

List every pending effect on an instance.

GROQ query against the engine's workflow resource. $tag is bound for tag-scoped filtering.

Snapshot-aware GROQ — runs against the same in-memory view the engine's filters see for the supplied instance. The caller-free rendered scope cascade gates evaluate in is bound — the instance-derived vars (FILTER_SCOPE_VARS) with the open stage's overlay merged into $fields, $assigned at its caller-free false, plus the author's pre-evaluated $<predicate> booleans — ids in GDR URI form to match the snapshot's keying.

Admin override — reset a failed/terminal activity in the current stage back to active (re-run) or skipped (bypass), then cascade.

Resolve durable actor provenance through this engine's project client.

Opt into reactivity: bind the engine to an instance doc and get a stateful InstanceSession. Push the docs it lists in subscriptionDocuments via update, then evaluate/tick/fireAction against the held state — pushed content is never refetched. The session never observes or ticks on its own; the consumer drives it.

Admin override — bypass filters/transitions and force the stage.

Starts an instance. start.filter is never a gate here — applicability belongs to definitionsForDocument, and an inapplicable definition starts without complaint. instanceId is the idempotency key: reusing it for the same start resumes; a different start throws.

The reactive WatchSet for an instance — every document whose change should re-evaluate it (the instance, its ancestors, and the docs named by doc.ref/subject/doc.refs/release.ref field entries on the workflow scope

• current stage) as exploded SubscriptionDocuments, plus the instance's read perspective. Fetches the instance, then derives. A reactive adapter that already holds the live instance calls the pure subscriptionDocumentsForInstance directly instead, to avoid the re-fetch.

The resolved telemetry logger (noopTelemetry unless injected) — exposed so adapters built on the engine log through the same seam.

Inspect every deployed definition in the engine's tag and apply the configured effects.missingHandler policy at phase: "deploy" for any effect name without a registered handler. Catches "definition shipped, handler removed" misconfigurations at startup instead of three days later when the effect fires.

Returns the list of (definitionId, name, locations) tuples it saw. Throws if effects.missingHandler resolved as "fail" for any of them.