@smthrs/engine-store 0.0.0-stage → 1.0.0-rc.3

package/docs/guides/drive-a-plan.md

@@ -0,0 +1,314 @@
+---
+title: "Drive a plan to completion"
+description: "Record a plan, supply a node executor, run the graph, and read every node's outcome: admission caps, rebase budgets, conflict strategies, and reconciliation verdicts."
+sidebar:
+  order: 3
+---
+
+`PlanScheduler` drives a persisted [`@smthrs/plan`](/api/plan) plan. It owns
+identity, admission, caching, and journaling, and deliberately owns nothing
+about what a node means: turning a node into work is the one seam you supply.
+
+## Supply an executor
+
+`NodeExecutor` is that seam. It receives a `NodeInput` and returns whatever the
+node produces:
+
+```ts
+import { PlanScheduler } from "@smthrs/engine-store"
+import * as Effect from "effect/Effect"
+
+const executor = PlanScheduler.layerExecutor({
+  execute: (input) =>
+    Effect.succeed({
+      node: input.node.id,
+      attempt: input.attempt,
+      inputs: input.inputs.map((resolved) => resolved.value)
+    })
+})
+```
+
+`NodeInput` carries the `PlanNode`, the `attempt` number, the `boundary` this
+dispatch was keyed under, and the node's material `Ref` inputs already resolved
+through the same projection the key digests. Ordering dependencies and
+unprojected sibling fields are deliberately absent: an executor may only see
+data the key folds, or a cached settlement could be served for an execution that
+consumed something else.
+
+## Build the scheduler and run the plan
+
+```ts
+const scheduler = PlanScheduler.layer({
+  runId: "plan-1",
+  owner,
+  sourceId: "planner",
+  concurrency: { steps: 8, agents: 2 },
+  rebaseLimit: 3
+})
+```
+
+`concurrency.steps` caps leaf execution and `concurrency.agents` caps the agent
+subset within it. Both default to unbounded and both reject zero, because a cap
+of zero admits nothing and a round that admits nothing settles nothing. Invalid
+bounds are rejected at construction: both must be positive safe integers, and
+`rebaseLimit` a non-negative one.
+
+The service has three members:
+
+```ts
+interface Service {
+  readonly record: (plan: Plan) => Effect<RecordResult, SchedulerError, PlanStore | Journal | Crypto>
+  readonly append: (plan: Plan) => Effect<void, SchedulerError, PlanStore | Journal | Crypto>
+  readonly run: (plan: Plan) => Effect<Report, SchedulerError, Requirements>
+}
+```
+
+`record` persists generation 0 and journals `plan-recorded`. `append` persists
+the newest generation and journals `subgraph-appended`. `run` walks the graph
+and returns a `Report`.
+
+Both plan records carry the graph itself under `graph.nodes`, beside the node
+count `nodes` has always been, and each node names the tag it dispatches. They
+carry no edges: a plan names its edges through each node's `dependsOn`, and the
+reason for an edge is something only an interpreted graph knows.
+
+The runtime requirements include `PlanInputStore.layer` and `PlanMergeStore.layer`. Compose them over the
+same database and durable writer as the other stores, with `Crypto`, after
+`Migrations.layer` has installed the schema. `TestStores.layer` and `layerAt`
+already provide both. There is no volatile fallback: missing durable observations
+must not authorize fresh execution of an old action.
+
+## Read the report
+
+`Report` carries the `planId`, its `digest`, one `Settlement` per node, the
+`results` by node id, the reconciliation `verdicts`, and the ids of any merge
+nodes a `stop-merge` conflict appended.
+
+Each `Settlement` names the `planKey` (a pure function of declarations), the
+`dispatchKey` actually dispatched under, the `attempts` and `rebases` spent,
+and one of five outcomes:
+
+| Outcome    | Meaning                                                                           |
+| ---------- | --------------------------------------------------------------------------------- |
+| `built`    | The node executed and succeeded.                                                  |
+| `clean`    | A durable attempt replay or eligible shared-cache hit served it; no executor ran. |
+| `failed`   | The node executed and failed, or reconciliation failed it.                        |
+| `skipped`  | A dependency prevented dispatch, or `stop-merge` stopped a dispatched attempt.    |
+| `deferred` | A selection guess postponed it. It never dispatched and wrote no cache row.       |
+
+Every settlement is journaled as `node-settled`. A `stop-merge` decision writes
+one `skipped` settlement for the stopped node. Reopening the run preserves that
+record; recovery writes it only if it was missing. A `deferred` node is never
+reported as passed, and is a debt a later guess-free pass repays.
+
+## Why the dispatch key is not the plan key
+
+All effect tiers can be planned. Sealed work uses the content-derived dispatch
+key described below. Compensable and irreversible work instead uses a run-local
+key scoped by the plan, structural node address, and declaration fingerprint.
+Its successful attempt can replay after a restart in that run; it cannot serve
+a different invocation or publish to the shared cache. Repeated identical
+non-sealed nodes are distinct invocations.
+
+Compensable attempts use the supplied `Jj` pre-image and restore it before a
+retry. That promise covers only state the snapshot actually captures. The
+generic node executor does not supply an irreversible idempotency contract, so
+uncertain recovery and retries of irreversible work are refused, including
+automatic conflict rebases or merge elaboration. No tier turns approval into authority or makes an
+unenforced boundary hermetic.
+
+The sealed dispatch key folds the node's own declaration with measured file
+digests and the projected values of its material `Ref` inputs. It does not fold
+upstream plan keys: unchanged consumed content can reuse a result even when an
+upstream declaration changed. Ordering dependencies do not expose their values
+to the executor. Two runs whose input files differ can declare the same graph,
+so a plan key alone cannot establish reuse.
+
+Source inputs have no writer preceding their reader. They include reads before
+an explicitly later writer and reads of a node's own future writes. Their bytes
+and glob membership are pinned before the first dispatch; new generations are
+observed at append time. Produced inputs are measured after preceding writers
+settle. A rebase re-observes those outputs, never source inputs.
+
+`PlanInputStore` persists these observations before any affected dispatch.
+Reopening the same run recovers them without measuring source files or expanding
+source globs again. Each generation keeps earlier pins and records only new
+sources. The same run cannot silently switch plan IDs or approved base graphs;
+start a new run for changed work. A new run observes the current inputs.
+
+The scheduler copies `Options.environment` at construction and persists its
+normalized fingerprint with the first input generation. Same-run recovery
+refuses changed identity before execution, for sealed, compensable, and
+irreversible work. Equivalent capability-pattern sets recover normally; layer
+order matters. Omission is a distinct identity, not a wildcard. Use the original
+runtime to recover, or reconcile unfinished effects before starting a new run.
+This cannot detect behavior changes a host omits from its declared identity.
+
+Upgrade boundary: runs with attempts predating migration `3003` have no reliable
+source snapshot and are refused by this scheduler. Finish them on the prior
+runtime before upgrading, or explicitly decide how to recover their effects
+before starting new work. Deleting the compatibility marker is not recovery.
+Migration `3004` likewise refuses existing input heads with no recorded
+environment. It preserves their unknown state instead of guessing a binding.
+
+## Readiness, ordering and recovery
+
+Each run or resume builds a private `RuntimeGraph` from the verified plan and
+recovered merge settlements. Stable plan positions, forward and reverse edges,
+unresolved and blocking dependency counts, and an explicit remaining count
+replace repeated whole-plan readiness scans. State and admission membership use
+maps and sets. The indexes are not persisted or included in any key.
+
+A dispatch result stays provisional while the coordinator drains and reconciles
+its durable deviations. Only the reconciled settlement updates affected
+dependents. Retry attempts and rebases hold the same node in flight; they do not
+decrement its dependents' counts again. Skips propagate in dependency order
+before more work is admitted. A failed cone does not stop unrelated work. A
+selected sink becomes deferred only if its dependencies succeeded; a failed
+cone produces skipped work rather than selection debt.
+
+Ready work is ordered by declared `priority` plus one point for each admission
+pass in which capacity left it waiting. Ties retain compiled plan order, and
+priority arithmetic stays exact even at the safe-integer boundary. Every
+admission re-ranks the current frontier, accounting for its updated ages. A
+blocked agent does not prevent ordinary steps from using spare step permits.
+This preserves fairness; a wide frontier can still cost proportional to its
+size, plus sorting, on each admission.
+
+An appended generation enters the indexes synchronously after the plan, input
+observations and merge completion commit together. Earlier positions, states
+and observations remain intact. Discovered reconciliation edges change only
+readiness; declared predecessors still determine file versions. Ancestor
+queries visit each reachable predecessor once per reader and release their
+temporary set, rather than retaining a transitive-closure matrix.
+
+Reverse indexes govern readiness and propagation of settled outcomes only.
+Content addressing and the existing cache-admission checks still govern reuse.
+There is no separate dirty-bit propagation or cache-invalidation visitor.
+
+The scheduler's differential tests retain the pre-index coordinator in
+`test/PlanSchedulerReference.ts`. Generated DAGs compare complete reports,
+dispatch and settlement records, input projections, plan generations and cache
+keys. Separate cases control concurrent completions, reopen real SQLite
+connections, and compare exact, tree and glob file scopes against independently
+specified source and producer measurements. `RuntimeGraph.test.ts` also compares
+each frontier with an exhaustive state model.
+
+Private work counters separate index updates, settlements, frontier snapshots,
+admission preparation and ancestor queries. Allocation counts cover explicit
+graph containers and records, not VM backing storage, closures, the shared
+admission policy, or persistence and filesystem work. Chain and wide-frontier
+tests assert operation counts instead of elapsed time. The optional
+`node test/RuntimeGraphBenchmark.ts` measures only graph mechanics locally,
+checks equal admission order before timing, and is not an end-to-end scheduler
+throughput claim.
+
+## Handle a conflict
+
+The runtime conflict strategies ride the plan's pair annotations:
+
+- **delay and rebase** holds the dependents and re-executes against the newly
+  recorded base. The re-measure re-keys, so it is a new attempt rather than a
+  retry of one identity. It is journaled as `node-invalidated` and bounded by
+  `rebaseLimit`, because an unbounded rebase loop is a livelock with good
+  manners.
+- **stop and merge** stops the loser and appends a merge node to the same plan
+  as an ordinary elaboration, with no rebase budget of its own: a lane that
+  loses a landing race restarts or fails rather than rebasing.
+
+A conflict neither strategy absorbs goes to `Reconciliation`.
+
+The scheduler persists the stopped-attempt decision independently of the
+action's failure and redacted journal. Recovery preserves that node as `skipped`
+and reuses completed work instead of re-executing it. It accepts either the
+original approved base or a loaded grown plan, but validates the recorded
+parent digest, generated node identity and intervening approved generations.
+Missing or inconsistent recovery data is an error, not permission to invent
+an extension.
+
+Generated display IDs start at `${nodeId}+merge` and use a free numeric suffix
+when user-defined nodes occupy that name. A name or merge-shaped body alone
+does not establish generated ownership: the durable decision does. The input
+generation, plan append, journal publication and merge completion commit
+together. A failed append leaves a recoverable intent, not a partial extension.
+
+Generated merges count toward `Plan.maximumPlanNodes`. If an extension would
+exceed that limit, the scheduler returns `elaboration_failed` without committing
+a new generation. Leave capacity for possible merge nodes in very large plans.
+
+Migration `3005` preserves unknown merge state for pre-existing input heads;
+the scheduler refuses them rather than guessing which failures were absorbed.
+Recover those runs with their original runtime, or reconcile their effects
+before starting new work. These scheduler guarantees do not establish native
+filesystem merge correctness or make arbitrary external effects reversible.
+
+## Install a reconciler
+
+`Reconciliation` answers a `Deviation` or a `Conflict` with a `Verdict`:
+
+```ts
+import { Reconciliation } from "@smthrs/engine-store"
+
+const reconciler = Reconciliation.layerDefault
+```
+
+`layerDefault` is deterministic, in this order of preference:
+
+- `Reorder` when every undeclared path is one another plan node declares it
+  writes. That is a real dependency the declaration missed, made explicit.
+- `FactorOut` when another node in the same run deviated on exactly the same
+  paths. Content addressing collapses two identical extracted steps to one key
+  by itself, so the verdict is a record and a hint.
+- `Fail` otherwise, because a deviation nothing explains is genuinely wrong. A
+  conflict the runtime strategy could not absorb always fails here: choosing a
+  winner between two landings is a semantic judgement this default does not
+  have the material to make.
+
+The scheduler attributes every deviation on a journal page before judging any of
+it, so two steps that produced the same undeclared paths both see each other.
+Deviating identically is a symmetric fact, and which of the pair the journal
+happened to list first must not decide the verdict.
+
+`Reconciliation.layer(service)` installs your own. Pluggability here is
+dependency injection at the owning seam; there is no hook kernel. A model-backed
+reconciler is a different `Layer` and lives in the agent packages, because this
+package carries no model dependency.
+
+## What a SchedulerError is, and is not
+
+`SchedulerError` is a refusal the scheduler itself raises, with a `code` of
+`invalid_plan`, `boundary_unavailable`, `key_uncomputable`, `elaboration_failed`, or
+`store_failed`. A node's own failure is not one of these: the run continues and
+the report says `failed`.
+
+## Related
+
+- [Defer work with selection](./defer-work-with-selection.md): what a
+  `deferred` outcome means and how the debt is repaid.
+- [Cache admission](../concepts/cache-admission.md): why a node settles `clean`.
+
+### Plan admission and filesystem failure cleanup
+
+`record`, `append`, and `run` verify the complete plan before using it. They
+recompute keys, graph annotations and approval digests through `Plan.verify`,
+then use its immutable snapshot. Each operation requires `Crypto`; invalid
+input fails with `invalid_plan` before store calls, journal writes, filesystem
+measurement or dispatch. Caller mutation cannot change an admitted plan.
+
+A source or produced-file enumeration failure carries `boundary_unavailable`
+and its original cause. Consumers whose inputs cannot be measured never get
+an attempt or cache entry. A typed scheduler failure interrupts siblings and
+atomically marks their still-owned running attempts failed with matching
+`attempt-finished` journal records. Completed producer evidence remains valid.
+A terminal row or lost owner fence is never overwritten.
+
+If cleanup itself cannot commit, the original scheduler error remains primary
+and its `cleanupErrors` records those failures. Journal failure rolls back the
+attempt transition. Such an unresolved attempt needs recovery; the scheduler
+does not claim that failed persistence succeeded. Ordinary parking, external
+interruption and ownership-loss semantics are unchanged.
+
+The run driver owns the RunStore lifecycle transition when `run` fails; this
+scheduler does not terminalize the run itself. Missing glob roots and absent
+exact producer paths intentionally mean zero matches (including removals);
+disappearance of a subtree that enumeration already discovered is an error.

package/docs/guides/observe-engine-metrics.md

@@ -0,0 +1,98 @@
+---
+title: "Observe engine metrics"
+description: "The counters and timers this package records on its hot paths, the outcome dimension every counter carries, and how to instrument your own effect with the same shape."
+sidebar:
+  order: 10
+---
+
+`EngineStoreMetrics` exposes the metric handles the engine updates and the
+combinator it updates them with. It exports no exporter: wiring metrics to a
+backend is the host's job, and belongs to
+[`@smthrs/observability`](/api/observability).
+
+## What is recorded
+
+Every counter is dimensioned by an `outcome` attribute, and every hot path has a
+matching duration timer.
+
+| Metric                                          | What it counts or times                                                                                                                    |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `flows_engine_dispatches`                       | Durable action dispatches. A cache-served replay and a fresh execution both count: the dispatch is the unit the engine retries and fences. |
+| `flows_engine_dispatch_duration`                | One dispatch, from admission through settlement, including cache verification, execution, copy-back, and the terminal row.                 |
+| `flows_engine_scheduler_admissions`             | Plan-scheduler admissions.                                                                                                                 |
+| `flows_engine_scheduler_dispatch_duration`      | One scheduler node dispatch.                                                                                                               |
+| `flows_engine_scheduler_nodes`                  | Node settlements, dimensioned by outcome.                                                                                                  |
+| `flows_engine_sandbox_executions`               | Workspace transaction executions.                                                                                                          |
+| `flows_engine_sandbox_execution_duration`       | One workspace transaction.                                                                                                                 |
+| `flows_engine_sandbox_materializations`         | Copy-back attempts.                                                                                                                        |
+| `flows_engine_sandbox_materialization_duration` | One copy-back.                                                                                                                             |
+| `flows_engine_sandbox_conflicts`                | Materialization conflicts, the refusals a rebase answers.                                                                                  |
+| `flows_engine_boundary_settlements`             | Step boundary settlements.                                                                                                                 |
+| `flows_engine_step_cache_decisions`             | What a dispatch actually did with a cache row, after read-set verification and output materialization.                                     |
+| `flows_engine_claims`                           | The run driver's claim-and-activate decisions.                                                                                             |
+
+Each counter also has a tag-keyed record of attributed views, so a caller
+updates the right dimension by name rather than by re-attributing:
+
+| View                 | Keys                                                                                               |
+| -------------------- | -------------------------------------------------------------------------------------------------- |
+| `dispatch`           | `Success`, `Failure`, `Interrupt`                                                                  |
+| `sandboxExecution`   | `Success`, `Failure`, `Interrupt`                                                                  |
+| `materialization`    | `Success`, `Failure`, `Interrupt`                                                                  |
+| `node`               | `built`, `clean`, `failed`, `skipped`, `deferred`                                                  |
+| `boundarySettlement` | `Clean`, `Deviation`, `Violation`, `Refused`                                                       |
+| `stepCacheDecision`  | `VerifiedHit`, `Miss`, `UnverifiableEvidence`, `Unmeasurable`, `StaleReadSet`, `ReplayFailed`      |
+| `claim`              | `Activated`, `Terminal`, `HeartbeatFresh`, `StealRefusedOwnerAlive`, `ClaimLost`, `ActivationLost` |
+
+`stepCacheDecisions` is the series to read when you are asking why a step ran.
+`VerifiedHit` served the cached result; every other value fell through to a real
+execution. `Miss` is no row at all, `UnverifiableEvidence` a row whose recorded
+evidence cannot justify reuse, `Unmeasurable` a host that could not re-measure
+the read set, `StaleReadSet` a measured mismatch, and `ReplayFailed` verified
+evidence the host could not re-materialize. At most one decision is counted per
+cache-consulting dispatch, so a dispatch that fails or is fenced out
+mid-decision records none and shows up in `flows_engine_dispatches` instead.
+
+An `Invalidated` workspace verdict counts as a `Success` exit on
+`sandboxExecution`: the transaction ran and answered, and the verdict itself is
+journaled.
+
+## Classify an exit
+
+`ExitTag` is `"Success"`, `"Failure"` (any non-interrupt cause), or
+`"Interrupt"` (an interrupt-only cause, which in this store covers the fencing
+self-interruption as well as caller cancellation).
+
+```ts
+import { EngineStoreMetrics } from "@smthrs/engine-store"
+import * as Effect from "effect/Effect"
+
+const tag = Effect.map(Effect.exit(someEffect), EngineStoreMetrics.exitTag)
+```
+
+Outcome tags are rewritten as snake case attribute values, so `HeartbeatFresh`
+is recorded as `heartbeat_fresh`.
+
+## Instrument your own effect the same way
+
+`observe` composes a duration timer with an exit-outcome counter and a span
+annotation, and propagates the instrumented effect's exit byte-identically,
+value, cause, and interruption alike:
+
+```ts
+const instrumented = someEffect.pipe(
+  EngineStoreMetrics.observe({
+    timer: EngineStoreMetrics.dispatchDuration,
+    counter: EngineStoreMetrics.dispatch
+  })
+)
+```
+
+It is built on Effect's own `Effect.trackDuration`, which uses the monotonic
+clock and records on success, failure, and interruption alike.
+
+## Export them
+
+Provide an exporter from your host composition. See
+[Observability](/docs/guides/observability/) on smithers.sh for the OTLP wiring
+the CLI uses.

package/docs/guides/observe-executions.md

@@ -0,0 +1,187 @@
+---
+title: "Observe executions and page runs"
+description: "Coherent engine snapshots, bounded filtered pages, revisioned catch-up, cancellation acknowledgement and durable child catalogs."
+---
+
+`ExecutionSnapshot`, `RunChangeFeed`, and `RunCatalogRead` read the engine's
+database. Each has a `layer` requiring `SqlClient`; apply `Migrations.layer`
+before constructing it. They start no polling fibers and read no control tables.
+
+## Observe one execution or a batch
+
+```ts
+import { ExecutionSnapshot } from "@smthrs/engine-store"
+import * as Effect from "effect/Effect"
+
+const observe = Effect.gen(function*() {
+  const executions = yield* ExecutionSnapshot.ExecutionSnapshot
+  return yield* executions.read(["build-42", "build-42/round-1"])
+})
+```
+
+`read` accepts at most 200 IDs and returns observations in request order,
+including duplicates. An empty batch still reads the source and watermark.
+Every batch carries the database `source` and the global `revision` observed by
+one read transaction. Each `Observed` entry carries its own run revision,
+lifecycle, flow, creation/start/finish timestamps, effective parent, lineage and
+round ordinal, structured wait, cancellation intent, and acknowledgement.
+
+Observations describe the requested execution row. A completed predecessor
+remains completed after a trampoline handoff. `related({ runId, kind: "rounds" })`
+enumerates that logical job's rounds from any member; a consumer implementing
+latest-round job status must select that round explicitly. The requested root's
+identity and parent do not become the successor's identity and parent.
+
+`Missing` is a separate variant. `deleted: true` means the database retains a
+tombstone; `false` means no tracked row or deletion was observed. Neither is a
+pending, running or terminal lifecycle. Absence without a tombstone carries the
+batch watermark, so a later creation has a greater revision.
+
+Waiting conditions have `kind` equal to `timer`, `signal`, `approval`, `quota`,
+`human`, or `other`, and preserve `reason` and `wakeAtMs`. The opaque wake
+token resolves the wait, so snapshots and run listings carry only
+`tokenDigest`, its SHA-256, the same digest `ExecutionFacts` records. The
+durable `event` reason maps to `signal`. Unknown plugin reasons remain `other`;
+they never imply approval. Nullable fields preserve old records that did not
+supply a deadline or token. Opaque wait reasons and tokens keep the engine
+writer's existing non-empty string contract; observing them does not impose
+the run-ID length limit.
+
+The effective parent is `parent_run_id` when present, otherwise the durable
+spawn edge with lowest sequence, breaking sequence ties by parent ID. Fork
+parents and trampoline predecessors do not themselves create spawn ownership
+edges. An old root with null lineage columns is round zero of its own lineage.
+
+Malformed stored lifecycle, wait, identity, ancestry or revision data fails
+closed with `RunStoreError`; schema failures use `decode_failed`. SQL failures
+and defects use `persistence_failed` with the original cause. Interruption
+remains interruption and releases the reserved connection and transaction.
+
+The read uses a deferred SQLite transaction, allowing a WAL writer to commit
+while it reads. All fields still describe the same database snapshot. A read
+inside an existing transaction joins that transaction and can see its writes;
+publish such observations only after that transaction commits.
+
+## Cancellation intent and acknowledgement
+
+`cancellation.requestedAtMs` is the recorded request. Its separate
+`acknowledgement` contains the first observing owner's `{ hostId, pid, nonce }`
+and `observedAtMs`. The owning driver records it under its running fence before
+the cancel poll interrupts the body, and in its cancellation settlement path.
+Other processes can record intent but cannot acknowledge as that owner.
+
+Acknowledgement means the driver observed intent. It does not prove user
+cleanup finished or that an external effect was undone. Cancellation terminality
+comes from lifecycle status. Old rows have an unknown, null acknowledgement;
+migration does not invent an observation or change control receipt shapes.
+
+## Filter before pagination
+
+`RunCatalogRead.listRuns({ filters, cursor, limit })` returns `runs`, an optional
+next `cursor` (null at exhaustion), and the transaction's `source` and `revision`.
+The default page is 100 and the allowed limit is 1 through 200. It computes no
+total count. All filters apply in SQL before the limit:
+
+| Filter            | Meaning                                                     |
+| ----------------- | ----------------------------------------------------------- |
+| `status`          | One engine lifecycle status.                                |
+| `flowName`        | Exact engine flow name.                                     |
+| `parentRunId`     | Exact effective parent; null selects rows without a parent. |
+| `lineageId`       | Exact trampoline lineage, including its original root.      |
+| `waitingReason`   | Exact durable reason; null selects no stored wait.          |
+| `createdAfterMs`  | Inclusive minimum creation time.                            |
+| `createdBeforeMs` | Inclusive maximum creation time.                            |
+
+Omitted filters are unconstrained. Pages order ascending by immutable
+`(created_at_ms, run_id)`, using SQLite's binary string order for ties. The
+version-1 cursor binds that last key to the canonical filter tuple and source
+identity. Changing the limit is allowed; changing filters or source is not.
+Malformed cursors fail with `invalid_cursor`, foreign sources with
+`source_changed`, and unsupported options with `invalid_options`. Numeric
+offsets are not accepted or reinterpreted. Cursors are opaque continuation
+values, not authorization tokens.
+
+Run IDs and text equality-filter inputs use durable, non-empty text of at most
+1,024 UTF-16 code units, without NUL or lone surrogates. Cursor input is bounded
+at 65,536 UTF-16 code units, including JSON escaping. This admits every generated
+cursor even when all maximum-length filter values need escaping. Observations
+preserve longer existing flow names and opaque waits; the filter input bound is
+an explicit admission limit of this new query API.
+
+Each page is coherent at its own revision. Successive pages are live reads:
+an insert after the last key can appear, an insert before it is not revisited,
+and a deletion or status change can remove a later match. Equal creation times
+are safe because the run ID breaks ties. Exhaustion is exact for an unchanged
+query result; it does not freeze future history. Use change-feed reconciliation
+when a consumer must account for changes behind an issued cursor.
+
+Migration 0006 creates creation-order indexes for all 32 subsets of the five
+equality predicates. This trades index storage and write work for ordered
+bounded queries, including rare combined filters. Reads decode only the page
+plus one lookahead. Earliest-parent subqueries are indexed and scoped to those
+rows. No whole-history ancillary map or temporary page sort is required.
+
+`listRunIds` retains its existing sync-polling behavior: newest rows by physical
+row order, returned oldest first, default bound 10,000, with zero returning an
+empty set. Its ordering and numeric limit contract have not changed.
+
+## Enumerate engine-created children and rounds
+
+`ExecutionSnapshot.related({ runId, kind, cursor, limit })` returns the requested
+`anchor` (including explicit Missing), a batch of related snapshots, and a
+continuation cursor, all in the same engine read transaction. `kind: "children"`
+walks durable spawn edges in `(seq, child_id)` order. `kind: "rounds"` reads
+lineage columns in `(round_ordinal, run_id)` order, including legacy round zero.
+Both use a default limit of 100 and maximum of 200. Cursors are bound to source,
+anchor ID and relation kind. Missing child rows remain explicit observations.
+
+This catalog includes children with no control admission row. It reads direct
+children, not a recursive descendant tree, and does not treat a fork as a spawn.
+
+## Catch up without losing deletions
+
+`RunChangeFeed.current` returns the source and current revision.
+`changesSince({ source, revision, limit })` returns changes in revision order,
+the current source watermark, `nextRevision`, and `hasMore`. Limits are 1 through
+1,000. Each change carries `runId`, `source`, its latest `revision`, and `deleted`.
+Use `nextRevision` for the next page, including when coalescing creates gaps.
+
+This is a coalesced state feed, not a lifecycle event log. Several writes to one
+run may become one newer entry. Revisions are global per database, durable,
+monotonic integers; timestamps and journal sequence numbers are not substitutes.
+Every run-row mutation, including heartbeat and wait updates, advances the
+revision in the same transaction. Spawn-edge changes refresh the affected
+existing child's parent and revision. A mutation can advance multiple times;
+consumers must not expect contiguous per-run revisions.
+
+Tombstones are retained indefinitely, one entry per deleted run ID. Ordinary
+run retention, journal compaction, and acknowledgement do not remove them.
+There is no consumer-expiration or compaction API, so even an indefinitely
+offline registered consumer cannot lose required deletion evidence. Recreating
+the same ID replaces absence with a strictly newer live revision. Storage grows
+with distinct run IDs, including deleted IDs. Any future tombstone compaction
+requires a separate registered-consumer retention and rebuild protocol.
+
+A consumer can start at revision zero and exhaust bounded feed pages. Apply each
+live snapshot or tombstone only if `ExecutionSnapshot.isNewer(incoming, stored)`
+returns true. Advance its durable applied watermark in the same local transaction
+as projection updates. A delayed pre-terminal observation then cannot overwrite
+a newer terminal observation. A snapshot fetched after a feed entry can be newer
+than that entry; retain its actual revision and ignore older replays.
+
+## Source replacement and cross-database limits
+
+Migration assigns a random durable database identity, preserved across normal
+reopens. A different source or a feed checkpoint ahead of the source revision requires an
+explicit projection rebuild. A copied backup carries the original identity:
+do not independently write divergent copies or resume a rewound source against
+an existing projection. Source rotation and restore/rebuild orchestration remain
+host responsibilities; this port does not silently reset a consumer.
+
+The engine's transaction is not a transaction across `control.db` and
+`engine.db`. Control still owns admission, actors and approval decisions.
+An engine-only page cannot include control admissions that have no execution
+yet. The control projection consumer and public control list routing are a
+separate integration step. They must expose their durable applied revision and
+the source revision observed during catch-up to represent lag. These ports
+provide that information but do not claim the control projection is current.