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

package/src/internal/SandboxedExecution.ts

@@ -0,0 +1,165 @@
+/**
+ * The isolated half of an attempt: run the body in a workspace transaction,
+ * copy its diff bundle back, and rebase a bounded number of times when the
+ * host moved underneath it.
+ *
+ * Copy-back has no human review gate.
+ *
+ * @since 0.1.0
+ */
+
+import type { FileBoundary } from "@smthrs/flow/FileBoundary"
+import { DerivedKey } from "@smthrs/keys"
+import * as Cause from "effect/Cause"
+import type * as Crypto from "effect/Crypto"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import type * as FileSystem from "effect/FileSystem"
+import * as Schema from "effect/Schema"
+import * as StepBoundary from "../StepBoundary.ts"
+import * as StepSandbox from "../StepSandbox.ts"
+import * as WorkspaceSandbox from "../WorkspaceSandbox.ts"
+
+/**
+ * An isolated execution whose diff bundle is now on the host.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Settlement {
+  readonly result: unknown
+  /**
+   * The content address of the applied bundle: a digest over every
+   * `(path, beforeDigest, afterDigest)` triple. It is the journal's handle on
+   * the copy-back, and the `diffIdentity` a deviation carries.
+   */
+  readonly bundleIdentity: string
+  readonly files: ReadonlyArray<WorkspaceSandbox.FileChange>
+  readonly effects: ReadonlyArray<WorkspaceSandbox.QueuedEffect>
+  /**
+   * Paths the body wrote outside its declared write set. Non-empty only in
+   * expected mode — hard mode fails instead — and the whole tree is in view,
+   * not just the declared read set `StepBoundary` can re-measure.
+   */
+  readonly deviations: ReadonlyArray<string>
+  /** How many times copy-back lost a race and the attempt re-ran from a fresh base. */
+  readonly rebases: number
+}
+
+/**
+ * How many times a losing copy-back re-runs the body from a fresh base.
+ *
+ * Bounded on purpose: an unbounded rebase against a workspace under sustained
+ * concurrent modification never converges. This retry budget does not
+ * recreate the removed worktree-lane surface.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const defaultMaxRebases = 3
+
+const bundleIdentity = (
+  entries: ReadonlyArray<readonly [string, string | undefined, string | undefined]>
+): Effect.Effect<string, never, Crypto.Crypto> =>
+  Schema.decodeUnknownEffect(DerivedKey)({
+    kind: "bundle-identity",
+    // Canonicalization substitutes undefined array slots with null. Name and
+    // normalize each member first so absence is explicit in this durable key.
+    entries: entries.map(([path, before, after]) => ({
+      path,
+      before: before ?? null,
+      after: after ?? null
+    }))
+  }).pipe(Effect.orDie)
+
+const conflicted = (cause: Cause.Cause<unknown>): boolean =>
+  cause.reasons.some((reason) =>
+    Cause.isFailReason(reason) && reason.error instanceof WorkspaceSandbox.MaterializationConflict
+  )
+
+/**
+ * Runs one action body inside a workspace transaction and copies its result
+ * back.
+ *
+ * The host is untouched until copy-back, so every refusal below leaves the
+ * tree exactly as it found it:
+ *
+ * - a body failure propagates unchanged, because it is the action's own
+ *   declared error and the retry policy must still match on it;
+ * - an execution the declaration did not predict fails with the boundary's own
+ *   {@link StepBoundary.UndeclaredWrite}, which routes it through the caller's
+ *   existing hard-violation classification instead of inventing a second one;
+ * - a lost copy-back race re-runs the body from a fresh base up to
+ *   `maxRebases` times before surfacing the conflict.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const execute = (options: {
+  readonly sandbox: WorkspaceSandbox.Service
+  readonly descriptor: FileBoundary
+  /**
+   * The action body. The engine's encoded effect erases its requirements, so
+   * the sandbox's own surfaces are named here: they are what `execute` seeds,
+   * and naming them keeps a caller from having to launder the type.
+   */
+  readonly workflow: Effect.Effect<unknown, unknown, WorkspaceSandbox.Workspace | FileSystem.FileSystem>
+  readonly maxRebases?: number | undefined
+}): Effect.Effect<Settlement, unknown, Crypto.Crypto> => {
+  const maxRebases = options.maxRebases ?? defaultMaxRebases
+  const attempt = (rebases: number): Effect.Effect<Settlement, unknown, Crypto.Crypto> =>
+    Effect.gen(function*() {
+      const executed = yield* options.sandbox.execute({
+        descriptor: options.descriptor,
+        workflow: options.workflow
+      })
+      if (executed._tag === "Invalidated") {
+        // NOTHING IS RETURNED FROM AN INVALIDATED EXECUTION. The candidate
+        // output, its files, and its queued effects are not on the shape at
+        // all; only the violations and the provenance identifying them are.
+        const paths = executed.violations.map((violation) => violation.resource.id)
+        const identity = yield* bundleIdentity(
+          executed.provenance.outputs.map((output) => [output.resource.id, undefined, output.digest])
+        )
+        if (executed.violations.some((violation) => violation.kind === "undeclared-read")) {
+          return yield* Effect.fail(
+            new StepSandbox.UndeclaredRead({
+              code: "undeclared_read",
+              paths: executed.violations
+                .filter((violation) => violation.kind === "undeclared-read")
+                .map((violation) => violation.resource.id),
+              diffIdentity: identity
+            })
+          )
+        }
+        return yield* Effect.fail(
+          new StepBoundary.UndeclaredWrite({
+            code: "undeclared_write",
+            paths,
+            diffIdentity: identity
+          })
+        )
+      }
+      const identity = yield* bundleIdentity(
+        executed.result.files.map((change) => [change.path, change.beforeDigest, change.afterDigest])
+      )
+      const applied = yield* options.sandbox.materialize(executed).pipe(Effect.exit)
+      if (Exit.isFailure(applied)) {
+        // Only a conflict is rebaseable: it says the base moved, which a fresh
+        // execution answers. A host or artifact refusal says the copy-back
+        // itself cannot be performed, and re-running the body would not help.
+        return conflicted(applied.cause) && rebases < maxRebases
+          ? yield* attempt(rebases + 1)
+          : yield* Effect.failCause(applied.cause)
+      }
+      return {
+        result: executed.result.output,
+        bundleIdentity: identity,
+        files: executed.result.files,
+        effects: executed.result.effects,
+        deviations: executed.violations.map((violation) => violation.resource.id),
+        rebases
+      }
+    })
+  return attempt(0)
+}

package/src/internal/StateTransaction.ts

@@ -0,0 +1,71 @@
+/**
+ * The engine store's one lock order for engine state and the journal.
+ *
+ * @since 0.1.0
+ */
+
+import type { DatabaseError } from "@smthrs/database/DurableWriter"
+import type { Journal } from "@smthrs/journal"
+import * as Effect from "effect/Effect"
+import type * as DurableEngineState from "../DurableEngineState.ts"
+
+/**
+ * Binds one ordered transaction boundary to a pair of stores.
+ *
+ * **The order is part of the package's contract.** Every fiber that needs
+ * both boundaries takes `DurableEngineState.transaction` FIRST and opens the
+ * journal's write transaction inside it. Never the other way around. The SQL
+ * engine state cannot tell the difference, because its transaction and the
+ * journal's are the same `DurableWriter` transaction and one of them nests as
+ * a savepoint of the other either way. The memory engine state has a gate of
+ * its own, and the contract requires the two implementations to be
+ * semantically equal. Taking the journal transaction first leaves a fiber
+ * holding the writer while it waits for that gate, which deadlocks against
+ * any fiber holding the gate while it waits for the writer. Both waits keep the
+ * caller's interruptibility: the state gate is taken first, then DurableWriter
+ * queues for its own permit before entering Effect SQL's masked connection
+ * acquisition. A journal-only writer never takes the state gate, so the
+ * writer's permit is what keeps a caller waiting behind it cancellable.
+ *
+ * Within that order the boundary is atomic in both directions: a failure
+ * before COMMIT rolls the SQL transaction back AND restores the memory
+ * snapshot, and the memory snapshot is accepted exactly at SQL COMMIT,
+ * through the `onCommit` callback registered before the body can queue any
+ * publication. The gate is therefore already released when the journal runs
+ * its post-commit work: compaction capture runs in a CHILD fiber and must see
+ * a released gate, just as it sees a committed SQL transaction. Publication
+ * failures happen after both commits and cannot undo either.
+ *
+ * `transact` defaults to the journal's own transaction. A caller passes its
+ * own only to change how the writer's Exit is read, never to change the order.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (
+  state: Pick<DurableEngineState.Service, "transaction">,
+  journal: Journal.Service
+) =>
+<A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  transact: <B, F, S>(
+    write: Effect.Effect<B, F, S>
+  ) => Effect.Effect<B, F | Journal.JournalError | DatabaseError, S> = journal.transact
+): Effect.Effect<A, E | Journal.JournalError | DatabaseError, R> =>
+  Effect.suspend(() => {
+    let commit = Effect.void
+    let bodyCompleted = false
+    return state.transaction(
+      transact(Effect.gen(function*() {
+        yield* journal.whenCommitted(Effect.suspend(() => bodyCompleted ? commit : Effect.void))
+        const value = yield* effect
+        bodyCompleted = true
+        return value
+      })),
+      {
+        onCommit: (accept) => {
+          commit = accept
+        }
+      }
+    )
+  })

package/src/internal/StepFacts.ts

@@ -0,0 +1,36 @@
+/** Projects only the saved outcome of an annotated trace checkpoint.
+ * @since 1.0.0
+ */
+
+import { JournalEvent, StepFact } from "@smthrs/journal"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+
+/** Builds the storage-only projector for one action.
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (action: unknown, runId: string) => {
+  const annotations = typeof action === "object" && action !== null && "annotations" in action
+    ? action.annotations as Context.Context<never>
+    : undefined
+  const annotated = annotations !== undefined && Option.isSome(Context.getOption(annotations, StepFact.Annotation))
+  return {
+    annotated,
+    settled: (outcome: unknown) =>
+      Effect.gen(function*() {
+        if (!annotated) return undefined
+        const fact = yield* Schema.decodeUnknownEffect(StepFact.Fact)(outcome).pipe(Effect.orDie)
+        const step = fact.step
+        return new JournalEvent.Input({
+          runId: JournalEvent.RunId.make(runId),
+          sourceId: JournalEvent.SourceId.make(`step-fact-v1:${step.stepId}:${step.attempt}:${step.ask}:${step.retry}`),
+          sourceSeq: JournalEvent.SourceSeq.make(fact.sourceSequence),
+          eventType: StepFact.eventType,
+          payload: fact
+        })
+      })
+  }
+}

package/src/internal/TypedEvents.ts

@@ -0,0 +1,29 @@
+/**
+ * Additive v2 constructors. Existing JournalRecords writers retain their bytes
+ * until a versioned writer cutover can supply complete lifecycle evidence.
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * Additive typed engine event constructors and decoders.
+ *
+ * @category events
+ * @since 1.0.0
+ */
+export {
+  attempt,
+  attemptEventType,
+  AttemptPayload,
+  type Consumer,
+  CurrentAttempt,
+  decodeCurrentAttempt,
+  decodeEntry,
+  EventError,
+  ExecutionLifecycle,
+  Lineage,
+  stateEvent,
+  stateEventType,
+  StatePayload,
+  Wait
+} from "@smthrs/journal/EngineEvent"

package/src/migrations/0001_initial.ts

@@ -0,0 +1,51 @@
+/**
+ * Initial durable deferred-completion and clock-deadline schema.
+ *
+ * Schema boundary: `packages/smithers/flows/engine-store/docs/concepts/durable-waits.md`.
+ *
+ * @since 0.1.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Creates the `flows_deferred_completions` and `flows_clock_deadlines` tables.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const initial: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+
+  yield* sql`CREATE TABLE flows_deferred_completions (
+    flow_name TEXT NOT NULL CHECK (length(flow_name) > 0),
+    execution_id TEXT NOT NULL CHECK (length(execution_id) > 0),
+    deferred_name TEXT NOT NULL CHECK (length(deferred_name) > 0),
+    exit_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`exit_json`)}),
+    metadata_json TEXT CHECK (metadata_json IS NULL OR ${Dialect.jsonValid(sql, sql`metadata_json`)}),
+    completed_at_ms ${Dialect.integer(sql)} NOT NULL CHECK (${
+    Dialect.isInteger(sql, sql`completed_at_ms`)
+  } AND completed_at_ms >= 0 AND completed_at_ms <= 9007199254740991),
+    PRIMARY KEY (flow_name, execution_id, deferred_name),
+    FOREIGN KEY (execution_id) REFERENCES flows_runs (run_id)
+  )`
+
+  yield* sql`CREATE TABLE flows_clock_deadlines (
+    flow_name TEXT NOT NULL CHECK (length(flow_name) > 0),
+    execution_id TEXT NOT NULL CHECK (length(execution_id) > 0),
+    clock_name TEXT NOT NULL CHECK (length(clock_name) > 0),
+    deferred_name TEXT NOT NULL CHECK (length(deferred_name) > 0),
+    due_at_ms ${Dialect.integer(sql)} NOT NULL CHECK (${
+    Dialect.isInteger(sql, sql`due_at_ms`)
+  } AND due_at_ms >= 0 AND due_at_ms <= 9007199254740991),
+    completed_at_ms ${Dialect.integer(sql)} CHECK (completed_at_ms IS NULL OR (${
+    Dialect.isInteger(sql, sql`completed_at_ms`)
+  } AND completed_at_ms >= 0 AND completed_at_ms <= 9007199254740991)),
+    PRIMARY KEY (flow_name, execution_id, clock_name),
+    FOREIGN KEY (execution_id) REFERENCES flows_runs (run_id)
+  )`
+
+  yield* sql`CREATE INDEX flows_clock_deadlines_pending_idx ON flows_clock_deadlines (completed_at_ms, due_at_ms)`
+})

package/src/migrations/0002_selection_store.ts

@@ -0,0 +1,38 @@
+/**
+ * Durable suspected-edge storage for probabilistic selection.
+ *
+ * @since 0.1.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Creates the `flows_selection_suspected_edges` table.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const selectionStore: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+
+  yield* sql`CREATE TABLE flows_selection_suspected_edges (
+    scope TEXT NOT NULL CHECK (length(scope) > 0),
+    affects TEXT NOT NULL CHECK (length(affects) > 0),
+    confidence DOUBLE PRECISION NOT NULL CHECK (
+      ${
+    sql.literal(Dialect.isPostgres(sql) ? "TRUE" : "(typeof(confidence) = 'real' OR typeof(confidence) = 'integer')")
+  } AND
+      confidence >= 0 AND
+      confidence <= 1
+    ),
+    valid_from_ms ${Dialect.integer(sql)} NOT NULL CHECK (
+      ${Dialect.isInteger(sql, sql`valid_from_ms`)} AND
+      valid_from_ms >= 0 AND
+      valid_from_ms <= 9007199254740991
+    ),
+    evidence_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`evidence_json`)}),
+    PRIMARY KEY (scope, affects)
+  )`
+})

package/src/migrations/0003_plan_inputs.ts

@@ -0,0 +1,75 @@
+/**
+ * Durable, append-only source observations for compiled plan execution.
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Creates input generations and marks pre-observation executions as non-recoverable.
+ * @since 1.0.0
+ * @category migrations
+ */
+export const planInputs: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql`CREATE TABLE flows_plan_input_legacy_runs (
+    run_id TEXT PRIMARY KEY NOT NULL REFERENCES flows_runs(run_id) ON DELETE CASCADE
+  )`
+  // A past source snapshot cannot be reconstructed from the files a completed
+  // action may already have changed. Preserve that uncertainty on upgrade.
+  yield* sql`INSERT INTO flows_plan_input_legacy_runs (run_id)
+    SELECT DISTINCT run_id FROM flows_attempts`
+  yield* Dialect.trigger(sql, {
+    name: `flows_plan_input_legacy_runs_no_update`,
+    table: `flows_plan_input_legacy_runs`,
+    event: "BEFORE UPDATE",
+    reject: "legacy plan input uncertainty is immutable"
+  })
+  yield* sql`CREATE TABLE flows_plan_input_heads (
+    run_id TEXT NOT NULL REFERENCES flows_runs(run_id) ON DELETE CASCADE,
+    plan_id TEXT NOT NULL CHECK (length(plan_id) > 0),
+    base_digest TEXT NOT NULL CHECK (length(base_digest) > 0),
+    generation ${Dialect.integer(sql)} NOT NULL CHECK (${
+    Dialect.isInteger(sql, sql`generation`)
+  } AND generation >= 0 AND generation <= 9007199254740991),
+    PRIMARY KEY (run_id, plan_id)
+  )`
+  yield* sql`CREATE UNIQUE INDEX flows_plan_input_heads_run_idx ON flows_plan_input_heads (run_id)`
+  yield* sql`CREATE TABLE flows_plan_input_generations (
+    run_id TEXT NOT NULL REFERENCES flows_runs(run_id) ON DELETE CASCADE,
+    plan_id TEXT NOT NULL CHECK (length(plan_id) > 0),
+    generation ${Dialect.integer(sql)} NOT NULL CHECK (${
+    Dialect.isInteger(sql, sql`generation`)
+  } AND generation >= 0 AND generation <= 9007199254740991),
+    snapshot_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`snapshot_json`)}),
+    checksum TEXT NOT NULL CHECK (length(checksum) = 64),
+    PRIMARY KEY (run_id, plan_id, generation)
+  )`
+  yield* Dialect.trigger(sql, {
+    name: `flows_plan_input_generations_no_update`,
+    table: `flows_plan_input_generations`,
+    event: "BEFORE UPDATE",
+    reject: "plan input generations are immutable"
+  })
+  yield* Dialect.trigger(sql, {
+    name: `flows_plan_input_heads_forward_only`,
+    table: `flows_plan_input_heads`,
+    event: "BEFORE UPDATE",
+    when: `NEW.run_id <> OLD.run_id OR NEW.plan_id <> OLD.plan_id OR
+      NEW.base_digest <> OLD.base_digest OR NEW.generation <> OLD.generation + 1`,
+    reject: "plan input heads only advance one generation"
+  })
+  for (const table of ["flows_plan_input_legacy_runs", "flows_plan_input_heads", "flows_plan_input_generations"]) {
+    // Cascade on run collection is allowed; direct deletion of replay state
+    // while its owning run exists is not.
+    yield* Dialect.trigger(sql, {
+      name: `${table}_no_delete`,
+      table: `${table}`,
+      event: "BEFORE DELETE",
+      when: `EXISTS (SELECT 1 FROM flows_runs WHERE run_id = OLD.run_id)`,
+      reject: "plan inputs belong to their run"
+    })
+  }
+})

package/src/migrations/0004_plan_environment.ts

@@ -0,0 +1,34 @@
+/**
+ * Bind source observations to the runtime identity that admitted them.
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Older heads retain NULL: their original runtime environment is unknowable.
+ * New heads require an environment fingerprint, immutable for their lifetime.
+ * @since 1.0.0
+ * @category migrations
+ */
+export const planEnvironment: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql`ALTER TABLE flows_plan_input_heads ADD COLUMN environment_digest TEXT
+    CHECK (environment_digest IS NULL OR length(environment_digest) > 0)`
+  yield* Dialect.trigger(sql, {
+    name: `flows_plan_input_heads_environment_required`,
+    table: `flows_plan_input_heads`,
+    event: "BEFORE INSERT",
+    when: `NEW.environment_digest IS NULL`,
+    reject: "new plan input heads require an environment identity"
+  })
+  yield* Dialect.trigger(sql, {
+    name: `flows_plan_input_heads_environment_immutable`,
+    table: `flows_plan_input_heads`,
+    event: "BEFORE UPDATE",
+    when: `NEW.environment_digest IS DISTINCT FROM OLD.environment_digest`,
+    reject: "plan input environment identity is immutable"
+  })
+})

package/src/migrations/0005_plan_merges.ts

@@ -0,0 +1,60 @@
+/**
+ * Durable scheduler merge intentions and their committed plan extensions.
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Existing heads retain an unknown merge-state version; a later runtime must
+ * not infer its missing control decisions from arbitrary plan-node bodies.
+ * @since 1.0.0
+ * @category migrations
+ */
+export const planMerges: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql`ALTER TABLE flows_plan_input_heads ADD COLUMN merge_state_version ${Dialect.integer(sql)}
+    CHECK (merge_state_version IS NULL OR merge_state_version = 1)`
+  yield* Dialect.trigger(sql, {
+    name: `flows_plan_input_heads_merge_version_immutable`,
+    table: `flows_plan_input_heads`,
+    event: "BEFORE UPDATE",
+    when: `NEW.merge_state_version IS DISTINCT FROM OLD.merge_state_version`,
+    reject: "plan merge state version is immutable"
+  })
+  yield* sql`CREATE TABLE flows_plan_merge_intents (
+    run_id TEXT NOT NULL REFERENCES flows_runs(run_id) ON DELETE CASCADE,
+    stopped_node_id TEXT NOT NULL CHECK (length(stopped_node_id) > 0),
+    intent_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`intent_json`)}),
+    checksum TEXT NOT NULL CHECK (length(checksum) = 64),
+    PRIMARY KEY (run_id, stopped_node_id)
+  )`
+  yield* sql`CREATE TABLE flows_plan_merge_completions (
+    run_id TEXT NOT NULL REFERENCES flows_runs(run_id) ON DELETE CASCADE,
+    stopped_node_id TEXT NOT NULL CHECK (length(stopped_node_id) > 0),
+    generation ${Dialect.integer(sql)} NOT NULL CHECK (${Dialect.isInteger(sql, sql`generation`)} AND generation > 0),
+    merge_node_id TEXT NOT NULL CHECK (length(merge_node_id) > 0),
+    completion_json TEXT NOT NULL CHECK (${Dialect.jsonValid(sql, sql`completion_json`)}),
+    checksum TEXT NOT NULL CHECK (length(checksum) = 64),
+    PRIMARY KEY (run_id, stopped_node_id),
+    UNIQUE (run_id, generation), UNIQUE (run_id, merge_node_id),
+    FOREIGN KEY (run_id, stopped_node_id) REFERENCES flows_plan_merge_intents(run_id, stopped_node_id) ON DELETE CASCADE
+  )`
+  for (const table of ["flows_plan_merge_intents", "flows_plan_merge_completions"]) {
+    yield* Dialect.trigger(sql, {
+      name: `${table}_no_update`,
+      table: `${table}`,
+      event: "BEFORE UPDATE",
+      reject: "plan merge decisions are immutable"
+    })
+    yield* Dialect.trigger(sql, {
+      name: `${table}_no_delete`,
+      table: `${table}`,
+      event: "BEFORE DELETE",
+      when: `EXISTS (SELECT 1 FROM flows_runs WHERE run_id = OLD.run_id)`,
+      reject: "plan merge decisions belong to their run"
+    })
+  }
+})

package/src/migrations/0006_execution_listing.ts

@@ -0,0 +1,86 @@
+/**
+ * Indexed engine execution observation and ordering.
+ *
+ * @since 1.0.0
+ */
+
+import * as Dialect from "@smthrs/database/Dialect"
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Brings existing spawn edges into the migration ladder and binds changes to
+ * their child's run revision. Run-store owns the shared revision triggers.
+ * @category migrations
+ * @since 1.0.0
+ */
+export const executionListing: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql`CREATE TABLE IF NOT EXISTS flows_run_parents (
+    child_id TEXT NOT NULL CHECK (length(child_id) > 0),
+    parent_id TEXT NOT NULL CHECK (length(parent_id) > 0),
+    seq ${Dialect.integer(sql)} NOT NULL CHECK (${
+    Dialect.isInteger(sql, sql`seq`)
+  } AND seq >= 0 AND seq <= 9007199254740991),
+    PRIMARY KEY (child_id, parent_id)
+  )`
+  yield* sql`CREATE INDEX IF NOT EXISTS flows_run_parents_parent_idx ON flows_run_parents (parent_id)`
+  yield* sql`CREATE INDEX flows_run_parents_first_idx ON flows_run_parents (child_id, seq, parent_id)`
+  yield* sql`CREATE INDEX flows_run_parents_children_idx ON flows_run_parents (parent_id, seq, child_id)`
+  yield* Dialect.trigger(sql, {
+    name: "flows_run_parents_gc",
+    table: "flows_runs",
+    event: "AFTER DELETE",
+    body: "DELETE FROM flows_run_parents WHERE child_id = OLD.run_id OR parent_id = OLD.run_id;"
+  })
+  yield* sql`ALTER TABLE flows_runs ADD COLUMN execution_parent_id TEXT`
+  yield* sql`ALTER TABLE flows_runs ADD COLUMN execution_flow TEXT
+    GENERATED ALWAYS AS (${Dialect.jsonText(sql, sql`state_json`, "$.flowName")}) ${
+    sql.literal(Dialect.isPostgres(sql) ? "STORED" : "VIRTUAL")
+  }`
+  yield* sql`ALTER TABLE flows_runs ADD COLUMN execution_lineage TEXT
+    GENERATED ALWAYS AS (COALESCE(lineage_id, run_id)) ${sql.literal(Dialect.isPostgres(sql) ? "STORED" : "VIRTUAL")}`
+  yield* sql`CREATE INDEX flows_runs_round_page_idx ON flows_runs (execution_lineage, COALESCE(round_ordinal, 0), run_id)`
+  yield* Dialect.trigger(sql, {
+    name: `flows_runs_creation_immutable`,
+    table: `flows_runs`,
+    event: "BEFORE UPDATE OF created_at_ms",
+    when: `NEW.created_at_ms <> OLD.created_at_ms`,
+    reject: "execution creation key is immutable"
+  })
+  yield* sql`UPDATE flows_runs SET execution_parent_id = COALESCE(parent_run_id,
+    (SELECT parent_id FROM flows_run_parents WHERE child_id = run_id ORDER BY seq, parent_id LIMIT 1))`
+  for (const operation of ["INSERT", "UPDATE OF parent_run_id"] as const) {
+    yield* Dialect.trigger(sql, {
+      name: `flows_runs_effective_parent_${operation === "INSERT" ? "insert" : "update"}`,
+      table: "flows_runs",
+      event: `AFTER ${operation}`,
+      body: `
+        UPDATE flows_runs SET execution_parent_id = COALESCE(NEW.parent_run_id,
+          (SELECT parent_id FROM flows_run_parents WHERE child_id = NEW.run_id ORDER BY seq, parent_id LIMIT 1))
+        WHERE run_id = NEW.run_id;
+      `
+    })
+  }
+  for (const operation of ["INSERT", "UPDATE", "DELETE"] as const) {
+    const row = operation === "DELETE" ? "OLD" : "NEW"
+    yield* Dialect.trigger(sql, {
+      name: `flows_run_parents_revision_${operation.toLowerCase()}`,
+      table: "flows_run_parents",
+      event: `AFTER ${operation}`,
+      body: `
+        UPDATE flows_runs SET execution_parent_id = COALESCE(parent_run_id,
+          (SELECT parent_id FROM flows_run_parents WHERE child_id = run_id ORDER BY seq, parent_id LIMIT 1))
+        WHERE run_id = ${row}.child_id ${operation === "UPDATE" ? "OR run_id = OLD.child_id" : ""};
+      `
+    })
+  }
+  // Every subset of the five equality filters has its creation-order suffix.
+  // This avoids rare combined predicates degrading to whole-history scans.
+  const fields = ["status", "execution_flow", "execution_parent_id", "execution_lineage", "waiting_reason"]
+  for (let mask = 0; mask < 32; mask++) {
+    const columns = fields.filter((_, index) => (mask & (1 << index)) !== 0)
+    yield* sql.unsafe(`CREATE INDEX flows_runs_listing_${mask} ON flows_runs
+      (${[...columns, "created_at_ms", "run_id"].join(", ")})`)
+  }
+})

package/src/migrations/0007_run_parent_sequence.ts

@@ -0,0 +1,19 @@
+/**
+ * Indexed allocation of the global run-parent sequence.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+/**
+ * Supports MAX(seq) without scanning retained edges from unrelated runs.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export const runParentSequence: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {
+  const sql = yield* SqlClient.SqlClient
+  yield* sql`CREATE INDEX flows_run_parents_seq_idx ON flows_run_parents (seq)`
+})