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

package/src/PlanInputStore.ts

@@ -0,0 +1,292 @@
+/**
+ * Authoritative source observations for one durable plan execution. These are
+ * replay state, not approval data, journal projections, or evictable cache rows.
+ * @since 1.0.0
+ */
+
+import { Sha256 } from "@smthrs/crypto"
+import { DurableWriter } from "@smthrs/database/DurableWriter"
+import { FileSet, Plan } from "@smthrs/plan"
+import { OwnerId } from "@smthrs/run-store/Ownership"
+import { Context, Effect, Layer, Option, Schema } from "effect"
+import type * as Crypto from "effect/Crypto"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+const Natural = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+
+/**
+ * Address of an append-only observation generation. `environmentDigest` comes
+ * from `StepKey.environmentIdentity` and binds every generation of the run.
+ * @since 1.0.0
+ * @category schemas
+ */
+export const Address = Schema.Struct({
+  runId: Schema.NonEmptyString,
+  planId: Schema.NonEmptyString,
+  baseDigest: Schema.NonEmptyString,
+  environmentDigest: Schema.NonEmptyString,
+  generation: Natural
+})
+/**
+ * Address of an append-only observation generation.
+ * @since 1.0.0
+ * @category models
+ */
+export type Address = typeof Address.Type
+
+/**
+ * Maximum encoded snapshot size, in JavaScript string code units.
+ * @since 1.0.0
+ * @category constants
+ */
+export const maximumSnapshotCharacters = 16 * 1024 * 1024
+
+/**
+ * Frozen membership and newly pinned source digests for one generation.
+ * @since 1.0.0
+ * @category schemas
+ */
+export const Snapshot = Schema.Struct({
+  version: Schema.Literal(1),
+  generation: Natural,
+  nodes: Schema.Array(Schema.Struct({
+    id: Schema.NonEmptyString,
+    key: Schema.NonEmptyString,
+    reads: Schema.Array(Schema.Struct({
+      entry: FileSet.ReadEntry,
+      sourcePaths: Schema.Array(FileSet.Pattern)
+    }))
+  })).check(Schema.isMaxLength(Plan.maximumPlanNodes)),
+  pins: Schema.Array(Schema.Struct({ path: FileSet.Pattern, digest: Schema.NonEmptyString }))
+})
+/**
+ * Frozen membership and newly pinned source digests for one generation.
+ * @since 1.0.0
+ * @category models
+ */
+export type Snapshot = typeof Snapshot.Type
+
+/**
+ * A durable observation cannot be read or safely admitted.
+ * @since 1.0.0
+ * @category errors
+ */
+export class PlanInputError extends Schema.TaggedError<PlanInputError>()("@smthrs/engine-store/PlanInputError", {
+  code: Schema.Literals([
+    "invalid_input",
+    "corrupt_state",
+    "incompatible_state",
+    "fence_lost",
+    "transaction_open",
+    "persistence_failed"
+  ]),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Unknown)
+}) {}
+
+/**
+ * `get` is a committed-state admission gate and refuses an enclosing SQL
+ * transaction. `record` is first-writer-wins and may join a write transaction;
+ * callers must wait for its outer commit before executing affected actions.
+ * @since 1.0.0
+ * @category models
+ */
+export interface Service {
+  readonly get: (address: Address, owner: OwnerId) => Effect.Effect<Option.Option<Snapshot>, PlanInputError>
+  readonly record: (address: Address, snapshot: Snapshot, owner: OwnerId) => Effect.Effect<Snapshot, PlanInputError>
+}
+
+/**
+ * Durable plan-input service.
+ * @since 1.0.0
+ * @category services
+ */
+export class PlanInputStore extends Context.Service<PlanInputStore, Service>()("@smthrs/engine-store/PlanInputStore") {}
+
+const failure = (code: PlanInputError["code"], message: string, cause?: unknown) =>
+  new PlanInputError({ code, message, ...(cause === undefined ? {} : { cause }) })
+const persistError = (cause: unknown) =>
+  cause instanceof PlanInputError ?
+    cause :
+    failure("persistence_failed", "could not access durable plan inputs", cause)
+
+const decode = <S extends Schema.Top & { readonly DecodingServices: never }>(
+  schema: S,
+  value: unknown,
+  code: "invalid_input" | "corrupt_state"
+) =>
+  Effect.try({
+    try: () => Schema.decodeUnknownSync(schema)(value, { onExcessProperty: "error" }),
+    catch: (cause) => failure(code, "invalid plan input observation", cause)
+  })
+
+const validateSnapshot = (snapshot: Snapshot, generation: number, code: "invalid_input" | "corrupt_state") => {
+  if (
+    snapshot.generation !== generation ||
+    new Set(snapshot.nodes.map((node) => node.id)).size !== snapshot.nodes.length ||
+    new Set(snapshot.pins.map((pin) => pin.path)).size !== snapshot.pins.length ||
+    snapshot.nodes.some((node) =>
+      node.reads.some((read) =>
+        new Set(read.sourcePaths).size !== read.sourcePaths.length ||
+        read.sourcePaths.some((path) =>
+          typeof read.entry === "string" ? path !== read.entry : !FileSet.matchesGlob(read.entry, path)
+        )
+      )
+    )
+  ) {
+    return Effect.fail(failure(code, "plan input observation has inconsistent membership or generation"))
+  }
+  return Effect.void
+}
+
+/**
+ * Builds the SQL-backed, owner-fenced store.
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make: Effect.Effect<Service, never, SqlClient.SqlClient | DurableWriter | Crypto.Crypto> = Effect.gen(
+  function*() {
+    const sql = yield* SqlClient.SqlClient
+    const writer = yield* DurableWriter
+    const crypto = yield* Effect.context<Crypto.Crypto>()
+    const checksum = (value: string) => Schema.decodeUnknownEffect(Sha256)(value).pipe(Effect.provide(crypto))
+
+    const fence = (address: Address, owner: OwnerId) =>
+      Effect.gen(function*() {
+        const owned = yield* sql`SELECT run_id FROM flows_runs WHERE run_id = ${address.runId}
+      AND status = 'running' AND cancel_requested_at_ms IS NULL
+      AND owner_host_id = ${owner.hostId} AND owner_pid = ${owner.pid} AND owner_nonce = ${owner.nonce}`
+        if (owned.length !== 1) {
+          return yield* Effect.fail(failure("fence_lost", "plan input owner no longer owns the run"))
+        }
+        const legacy = yield* sql`SELECT run_id FROM flows_plan_input_legacy_runs WHERE run_id = ${address.runId}`
+        if (legacy.length > 0) {
+          return yield* Effect.fail(
+            failure(
+              "incompatible_state",
+              "this run executed before durable plan inputs were recorded; its original sources cannot be reconstructed"
+            )
+          )
+        }
+      })
+
+    const load = (address: Address) =>
+      Effect.gen(function*() {
+        const heads = yield* sql<
+          { planId: string; baseDigest: string; environmentDigest: string | null; generation: number }
+        >`SELECT plan_id AS "planId", base_digest AS "baseDigest", environment_digest AS "environmentDigest", generation
+      FROM flows_plan_input_heads WHERE run_id = ${address.runId}`
+        const head = heads[0]
+        if (head === undefined) {
+          const orphan = yield* sql`SELECT 1 FROM flows_plan_input_generations
+        WHERE run_id = ${address.runId} AND plan_id = ${address.planId} LIMIT 1`
+          if (address.generation !== 0 || orphan.length > 0) {
+            return yield* Effect.fail(failure("corrupt_state", "plan input history has no initial generation"))
+          }
+          return Option.none<Snapshot>()
+        }
+        yield* decode(
+          Schema.Struct({
+            planId: Schema.NonEmptyString,
+            baseDigest: Schema.NonEmptyString,
+            environmentDigest: Schema.NullOr(Schema.NonEmptyString),
+            generation: Natural
+          }),
+          head,
+          "corrupt_state"
+        )
+        if (head.planId !== address.planId || head.baseDigest !== address.baseDigest) {
+          return yield* Effect.fail(
+            failure("incompatible_state", "this run already observed a different approved plan")
+          )
+        }
+        if (head.environmentDigest === null || head.environmentDigest !== address.environmentDigest) {
+          return yield* Effect.fail(failure(
+            "incompatible_state",
+            "this run has a different or unrecorded execution environment; recover with its original runtime or explicitly reconcile before starting a new run"
+          ))
+        }
+        const counts = yield* sql<{ count: number; first: number; last: number }>`SELECT COUNT(*) AS count,
+      MIN(generation) AS first, MAX(generation) AS last FROM flows_plan_input_generations
+      WHERE run_id = ${address.runId} AND plan_id = ${address.planId}`
+        if (
+          counts[0]!.count !== head.generation + 1 || counts[0]!.first !== 0 || counts[0]!.last !== head.generation ||
+          address.generation > head.generation + 1
+        ) {
+          return yield* Effect.fail(failure("corrupt_state", "plan input history has a missing generation"))
+        }
+        if (address.generation > head.generation) return Option.none<Snapshot>()
+        const rows = yield* sql<
+          { snapshotJson: string; checksum: string }
+        >`SELECT snapshot_json AS "snapshotJson", checksum
+      FROM flows_plan_input_generations WHERE run_id = ${address.runId} AND plan_id = ${address.planId}
+      AND generation = ${address.generation}`
+        const row = rows[0]!
+        if (
+          row.snapshotJson.length > maximumSnapshotCharacters || (yield* checksum(row.snapshotJson)) !== row.checksum
+        ) {
+          return yield* Effect.fail(failure("corrupt_state", "plan input snapshot failed its size or integrity check"))
+        }
+        const snapshot = yield* decode(Schema.fromJsonString(Snapshot), row.snapshotJson, "corrupt_state")
+        yield* validateSnapshot(snapshot, address.generation, "corrupt_state")
+        return Option.some(snapshot)
+      })
+
+    const get: Service["get"] = Effect.fn("PlanInputStore.get")((input, ownerInput) =>
+      Effect.gen(function*() {
+        const address = yield* decode(Address, input, "invalid_input")
+        const owner = yield* decode(OwnerId, ownerInput, "invalid_input")
+        if (Option.isSome(yield* Effect.serviceOption(sql.transactionService))) {
+          return yield* Effect.fail(
+            failure("transaction_open", "plan execution requires committed source observations")
+          )
+        }
+        return yield* writer.write(Effect.gen(function*() {
+          yield* fence(address, owner)
+          return yield* load(address)
+        }))
+      }).pipe(Effect.mapError(persistError))
+    )
+
+    const record: Service["record"] = Effect.fn("PlanInputStore.record")((input, value, ownerInput) =>
+      Effect.gen(function*() {
+        const address = yield* decode(Address, input, "invalid_input")
+        const owner = yield* decode(OwnerId, ownerInput, "invalid_input")
+        const snapshot = yield* decode(Snapshot, value, "invalid_input")
+        yield* validateSnapshot(snapshot, address.generation, "invalid_input")
+        const encoded = JSON.stringify(snapshot)
+        if (encoded.length > maximumSnapshotCharacters) {
+          return yield* Effect.fail(failure("invalid_input", "plan input snapshot exceeds the durable size limit"))
+        }
+        const hash = yield* checksum(encoded)
+        return yield* writer.write(Effect.gen(function*() {
+          yield* fence(address, owner)
+          const existing = yield* load(address)
+          if (Option.isSome(existing)) return existing.value
+          if (address.generation === 0) {
+            yield* sql`INSERT INTO flows_plan_input_heads (run_id, plan_id, base_digest, environment_digest, merge_state_version, generation)
+          VALUES (${address.runId}, ${address.planId}, ${address.baseDigest}, ${address.environmentDigest}, 1, 0)`
+          } else {
+            yield* sql`UPDATE flows_plan_input_heads SET generation = ${address.generation}
+          WHERE run_id = ${address.runId} AND plan_id = ${address.planId}`
+          }
+          yield* sql`INSERT INTO flows_plan_input_generations (run_id, plan_id, generation, snapshot_json, checksum)
+        VALUES (${address.runId}, ${address.planId}, ${address.generation}, ${encoded}, ${hash})`
+          return snapshot
+        }))
+      }).pipe(Effect.mapError(persistError))
+    )
+
+    return { get, record }
+  }
+)
+
+/**
+ * Provides the SQL-backed input store over the same database as the run/attempt stores.
+ * @since 1.0.0
+ * @category layers
+ */
+export const layer: Layer.Layer<PlanInputStore, never, SqlClient.SqlClient | DurableWriter | Crypto.Crypto> = Layer
+  .effect(
+    PlanInputStore
+  )(make)

package/src/PlanMergeStore.ts

@@ -0,0 +1,330 @@
+/**
+ * Owner-fenced scheduler decisions, distinct from action failure evidence and
+ * redacted journal projections. Intent survives before a merge is appended.
+ * @since 1.0.0
+ */
+
+import { Sha256 } from "@smthrs/crypto"
+import { DurableWriter } from "@smthrs/database/DurableWriter"
+import { Plan } from "@smthrs/plan"
+import { OwnerId } from "@smthrs/run-store/Ownership"
+import { Context, Effect, Layer, Option, Schema } from "effect"
+import type * as Crypto from "effect/Crypto"
+import * as SqlClient from "effect/unstable/sql/SqlClient"
+
+const Natural = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+const Positive = Schema.Int.check(Schema.isGreaterThan(0))
+const Names = Schema.Array(Schema.NonEmptyString).check(Schema.isMaxLength(Plan.maximumPlanNodes))
+
+/** Execution binding shared by every decision of one plan run.
+ * @since 1.0.0
+ * @category schemas
+ */
+export const Identity = Schema.Struct({
+  runId: Schema.NonEmptyString,
+  planId: Schema.NonEmptyString,
+  baseDigest: Schema.NonEmptyString,
+  environmentDigest: Schema.NonEmptyString
+})
+/** Execution binding.
+ * @since 1.0.0
+ * @category models
+ */
+export type Identity = typeof Identity.Type
+/** A stopped attempt and the exact cohort eligible to supply merge winners.
+ * @since 1.0.0
+ * @category schemas
+ */
+export const Intent = Schema.Struct({
+  version: Schema.Literal(1),
+  nodeId: Schema.NonEmptyString,
+  nodeKey: Schema.NonEmptyString,
+  dispatchKey: Schema.NonEmptyString,
+  attempts: Positive,
+  rebases: Natural,
+  peers: Names
+})
+/** Durable stopped-attempt decision.
+ * @since 1.0.0
+ * @category models
+ */
+export type Intent = typeof Intent.Type
+/** The plan extension committed for an intent.
+ * @since 1.0.0
+ * @category schemas
+ */
+export const Completion = Schema.Struct({
+  version: Schema.Literal(1),
+  generation: Positive,
+  parentDigest: Schema.NonEmptyString,
+  planDigest: Schema.NonEmptyString,
+  mergeId: Schema.NonEmptyString,
+  mergeKey: Schema.NonEmptyString,
+  winners: Names
+})
+/** Committed merge extension.
+ * @since 1.0.0
+ * @category models
+ */
+export type Completion = typeof Completion.Type
+/** Intent with its optional committed extension.
+ * @since 1.0.0
+ * @category models
+ */
+export interface Decision {
+  readonly intent: Intent
+  readonly completion?: Completion
+}
+/** Typed admission/storage refusal.
+ * @since 1.0.0
+ * @category errors
+ */
+export class PlanMergeError extends Schema.TaggedError<PlanMergeError>()("@smthrs/engine-store/PlanMergeError", {
+  code: Schema.Literals([
+    "invalid_input",
+    "corrupt_state",
+    "incompatible_state",
+    "fence_lost",
+    "transaction_open",
+    "transaction_required",
+    "persistence_failed"
+  ]),
+  message: Schema.String,
+  cause: Schema.optional(Schema.Unknown)
+}) {}
+/** Store operations; writes may join the owning transaction, reads require committed state.
+ * @since 1.0.0
+ * @category models
+ */
+export interface Service {
+  readonly list: (identity: Identity, owner: OwnerId) => Effect.Effect<ReadonlyArray<Decision>, PlanMergeError>
+  readonly intend: (identity: Identity, intent: Intent, owner: OwnerId) => Effect.Effect<Intent, PlanMergeError>
+  readonly complete: (
+    identity: Identity,
+    nodeId: string,
+    completion: Completion,
+    owner: OwnerId
+  ) => Effect.Effect<Completion, PlanMergeError>
+}
+/** Durable merge decision service.
+ * @since 1.0.0
+ * @category services
+ */
+export class PlanMergeStore extends Context.Service<PlanMergeStore, Service>()("@smthrs/engine-store/PlanMergeStore") {}
+/** Encoded decision limit, in JavaScript code units.
+ * @since 1.0.0
+ * @category constants
+ */
+export const maximumDecisionCharacters = 16 * 1024 * 1024
+const error = (code: PlanMergeError["code"], message: string, cause?: unknown) =>
+  new PlanMergeError({ code, message, ...(cause === undefined ? {} : { cause }) })
+const storageError = (cause: unknown) =>
+  cause instanceof PlanMergeError ? cause : error("persistence_failed", "could not access plan merge decisions", cause)
+const decode = <S extends Schema.Top & { readonly DecodingServices: never }>(
+  schema: S,
+  value: unknown,
+  code: "invalid_input" | "corrupt_state"
+) =>
+  Effect.try({
+    try: () => Schema.decodeUnknownSync(schema)(value, { onExcessProperty: "error" }),
+    catch: (cause) => error(code, "invalid plan merge decision", cause)
+  })
+const unique = (names: ReadonlyArray<string>, code: "invalid_input" | "corrupt_state") =>
+  new Set(names).size === names.length ? Effect.void : Effect.fail(error(code, "duplicate merge peer identity"))
+
+/** SQL constructor; all collaborating stores must use the same database/writer.
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make: Effect.Effect<Service, never, SqlClient.SqlClient | DurableWriter | Crypto.Crypto> = Effect.gen(
+  function*() {
+    const sql = yield* SqlClient.SqlClient
+    const writer = yield* DurableWriter
+    const crypto = yield* Effect.context<Crypto.Crypto>()
+    const hash = (value: string) => Schema.decodeUnknownEffect(Sha256)(value).pipe(Effect.provide(crypto))
+    const fence = (identity: Identity, owner: OwnerId, requireHead: boolean) =>
+      Effect.gen(function*() {
+        const owned = yield* sql`SELECT run_id FROM flows_runs WHERE run_id = ${identity.runId}
+      AND status = 'running' AND cancel_requested_at_ms IS NULL
+      AND owner_host_id = ${owner.hostId} AND owner_pid = ${owner.pid} AND owner_nonce = ${owner.nonce}`
+        if (owned.length !== 1) {
+          return yield* Effect.fail(error("fence_lost", "merge decision owner no longer owns the run"))
+        }
+        const heads = yield* sql<
+          { planId: string; baseDigest: string; environmentDigest: string | null; version: number | null }
+        >`SELECT
+      plan_id AS "planId", base_digest AS "baseDigest", environment_digest AS "environmentDigest", merge_state_version AS version
+      FROM flows_plan_input_heads WHERE run_id = ${identity.runId}`
+        const head = heads[0]
+        if (head === undefined) {
+          const orphan = yield* sql`SELECT 1 FROM flows_plan_merge_intents WHERE run_id = ${identity.runId} LIMIT 1`
+          if (requireHead || orphan.length > 0) {
+            return yield* Effect.fail(error("corrupt_state", "merge intent has no admitted input generation"))
+          }
+          return
+        }
+        if (
+          head.version !== 1 || head.planId !== identity.planId || head.baseDigest !== identity.baseDigest ||
+          head.environmentDigest !== identity.environmentDigest
+        ) {
+          return yield* Effect.fail(
+            error(
+              "incompatible_state",
+              "this run has different or unrecorded merge execution state; recover with its original runtime or reconcile before starting a new run"
+            )
+          )
+        }
+      })
+    const encoded = <A>(value: A) =>
+      Effect.gen(function*() {
+        const json = JSON.stringify(value)
+        if (json.length > maximumDecisionCharacters) {
+          return yield* Effect.fail(error("invalid_input", "merge decision exceeds its durable size limit"))
+        }
+        return { json, checksum: yield* hash(json) }
+      })
+    const stored = <S extends Schema.Top & { readonly DecodingServices: never }>(
+      schema: S,
+      row: { json: string; checksum: string }
+    ) =>
+      Effect.gen(function*() {
+        if (row.json.length > maximumDecisionCharacters || (yield* hash(row.json)) !== row.checksum) {
+          return yield* Effect.fail(error("corrupt_state", "merge decision failed its size or integrity check"))
+        }
+        return yield* decode(Schema.fromJsonString(schema), row.json, "corrupt_state")
+      })
+    const load = (identity: Identity, nodeId?: string) =>
+      Effect.gen(function*() {
+        const rows = yield* sql<
+          {
+            nodeId: string
+            json: string
+            checksum: string
+            generation: number | null
+            mergeId: string | null
+            completionJson: string | null
+            completionChecksum: string | null
+          }
+        >`SELECT i.stopped_node_id AS "nodeId", i.intent_json AS json, i.checksum,
+        c.generation, c.merge_node_id AS "mergeId", c.completion_json AS "completionJson",
+        c.checksum AS "completionChecksum"
+      FROM flows_plan_merge_intents i LEFT JOIN flows_plan_merge_completions c
+        ON c.run_id = i.run_id AND c.stopped_node_id = i.stopped_node_id
+      WHERE i.run_id = ${identity.runId} ${nodeId === undefined ? sql`` : sql`AND i.stopped_node_id = ${nodeId}`}
+      ORDER BY i.stopped_node_id LIMIT ${Plan.maximumPlanNodes + 1}`
+        if (rows.length > Plan.maximumPlanNodes) {
+          return yield* Effect.fail(error("corrupt_state", "too many merge decisions for one plan"))
+        }
+        return yield* Effect.forEach(rows, (row) =>
+          Effect.gen(function*() {
+            const intent = yield* stored(Intent, row)
+            yield* unique(intent.peers, "corrupt_state")
+            if (intent.nodeId !== row.nodeId || intent.peers.includes(intent.nodeId)) {
+              return yield* Effect.fail(error("corrupt_state", "merge intent identity is inconsistent"))
+            }
+            if (row.completionJson === null) return { intent } satisfies Decision
+            const completion = yield* stored(Completion, {
+              json: row.completionJson,
+              checksum: row.completionChecksum!
+            })
+            yield* unique(completion.winners, "corrupt_state")
+            if (
+              completion.generation !== row.generation || completion.mergeId !== row.mergeId ||
+              completion.winners.some((id) => !intent.peers.includes(id))
+            ) {
+              return yield* Effect.fail(error("corrupt_state", "merge completion does not match its intent"))
+            }
+            return { intent, completion } satisfies Decision
+          }))
+      })
+    const list: Service["list"] = (input, ownerInput) =>
+      Effect.gen(function*() {
+        const identity = yield* decode(Identity, input, "invalid_input")
+        const owner = yield* decode(OwnerId, ownerInput, "invalid_input")
+        if (Option.isSome(yield* Effect.serviceOption(sql.transactionService))) {
+          return yield* Effect.fail(error("transaction_open", "merge recovery requires committed decisions"))
+        }
+        return yield* writer.write(Effect.gen(function*() {
+          yield* fence(identity, owner, false)
+          return yield* load(identity)
+        }))
+      }).pipe(Effect.mapError(storageError))
+    const intend: Service["intend"] = (input, value, ownerInput) =>
+      Effect.gen(function*() {
+        const identity = yield* decode(Identity, input, "invalid_input")
+        const owner = yield* decode(OwnerId, ownerInput, "invalid_input")
+        const intent = yield* decode(Intent, value, "invalid_input")
+        yield* unique(intent.peers, "invalid_input")
+        if (intent.peers.includes(intent.nodeId)) {
+          return yield* Effect.fail(error("invalid_input", "a merge cannot stop its own peer"))
+        }
+        const data = yield* encoded(intent)
+        return yield* writer.write(Effect.gen(function*() {
+          yield* fence(identity, owner, true)
+          const [existing] = yield* load(identity, intent.nodeId)
+          if (existing !== undefined) return existing.intent
+          const [count] = yield* sql<{ count: number }>`SELECT count(*) AS count
+        FROM flows_plan_merge_intents WHERE run_id = ${identity.runId}`
+          if (count!.count >= Plan.maximumPlanNodes) {
+            return yield* Effect.fail(error("invalid_input", "too many merge intents for one plan"))
+          }
+          yield* sql`INSERT INTO flows_plan_merge_intents (run_id, stopped_node_id, intent_json, checksum)
+        VALUES (${identity.runId}, ${intent.nodeId}, ${data.json}, ${data.checksum})`
+          return intent
+        }))
+      }).pipe(Effect.mapError(storageError))
+    const complete: Service["complete"] = (input, nodeIdInput, value, ownerInput) =>
+      Effect.gen(function*() {
+        if (Option.isNone(yield* Effect.serviceOption(sql.transactionService))) {
+          return yield* Effect.fail(
+            error("transaction_required", "merge completion must join the plan/input append transaction")
+          )
+        }
+        const identity = yield* decode(Identity, input, "invalid_input")
+        const owner = yield* decode(OwnerId, ownerInput, "invalid_input")
+        const nodeId = yield* decode(Schema.NonEmptyString, nodeIdInput, "invalid_input")
+        const completion = yield* decode(Completion, value, "invalid_input")
+        yield* unique(completion.winners, "invalid_input")
+        const data = yield* encoded(completion)
+        return yield* writer.write(Effect.gen(function*() {
+          yield* fence(identity, owner, true)
+          const [decision] = yield* load(identity, nodeId)
+          if (decision === undefined) {
+            return yield* Effect.fail(error("corrupt_state", "merge completion has no intent"))
+          }
+          if (decision.completion !== undefined) {
+            if (JSON.stringify(decision.completion) !== JSON.stringify(completion)) {
+              return yield* Effect.fail(
+                error("incompatible_state", "a merge intent already committed a different extension")
+              )
+            }
+            return decision.completion
+          }
+          if (completion.winners.some((id) => !decision.intent.peers.includes(id))) {
+            return yield* Effect.fail(error("invalid_input", "merge winner was not an admitted peer"))
+          }
+          const appended =
+            yield* sql`SELECT p.plan_id FROM flows_plans p JOIN flows_plan_input_generations i ON i.plan_id = p.plan_id
+        JOIN flows_plan_nodes n ON n.plan_id = p.plan_id AND n.generation = p.generation
+        WHERE p.plan_id = ${identity.planId} AND p.digest = ${completion.planDigest} AND p.generation = ${completion.generation}
+        AND i.run_id = ${identity.runId} AND i.generation = ${completion.generation}
+        AND n.node_id = ${completion.mergeId} AND n.key_digest = ${completion.mergeKey} AND n.kind = 'merge'`
+          if (appended.length !== 1) {
+            return yield* Effect.fail(
+              error("corrupt_state", "merge completion requires its plan and input generation in the same transaction")
+            )
+          }
+          yield* sql`INSERT INTO flows_plan_merge_completions (run_id, stopped_node_id, generation, merge_node_id, completion_json, checksum)
+        VALUES (${identity.runId}, ${nodeId}, ${completion.generation}, ${completion.mergeId}, ${data.json}, ${data.checksum})`
+          return completion
+        }))
+      }).pipe(Effect.mapError(storageError))
+    return { list, intend, complete }
+  }
+)
+/** SQL-backed merge decisions; migrations must run first.
+ * @since 1.0.0
+ * @category layers
+ */
+export const layer: Layer.Layer<PlanMergeStore, never, SqlClient.SqlClient | DurableWriter | Crypto.Crypto> = Layer
+  .effect(PlanMergeStore)(make)