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

package/dist/esm/Inconsistency.js

@@ -0,0 +1,133 @@
+/**
+ * Receiver for detected engine inconsistencies.
+ *
+ * Modeled on Skyframe's `GraphInconsistencyReceiver`: the store layer detects
+ * an invariant violation — today, a content-addressed cache key that produced
+ * a different result than the recorded row — and this service decides whether
+ * the run fails or tolerates it. Either way the conflict is journaled, so the
+ * detector is never wired to /dev/null.
+ *
+ * The `note` signature deliberately matches the plugin spec's
+ * `cacheInconsistency` hook (`(event) => Effect<InconsistencyVerdict>`); the
+ * strict layer is the future default plugin.
+ *
+ * The core default is strict so an invariant violation cannot pass silently.
+ *
+ * Governing designs: `docs/concepts/attempts-and-replay.md` and
+ * `apps/site/src/content/docs/docs/concepts/flows-actions-plans.mdx`.
+ *
+ * @since 0.1.0
+ */
+import { FlowEngine } from "@smthrs/engine";
+import { Journal } from "@smthrs/journal";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as JournalRecords from "./internal/JournalRecords.js";
+/**
+ * Service tag for the engine inconsistency receiver.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class Inconsistency extends Context.Service()("@smthrs/engine-store/Inconsistency") {
+}
+/**
+ * Builds a receiver that journals every conflict under the run that attempted
+ * the write and returns a fixed verdict.
+ *
+ * The record goes through the journal's durable channel: a cache conflict is
+ * hermeticity evidence, and a `tolerate` verdict that silently dropped its
+ * only record would wire the detector to /dev/null (issue #10).
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options) => ({
+    note: Effect.fn("Inconsistency.note")((event) => Effect.as(options.journal.emitDurable(JournalRecords.cacheConflict({
+        runId: event.attempted.recordedRunId,
+        sourceId: "flows/engine-store/inconsistency",
+        lineageId: FlowEngine.Lineage.root(event.attempted.recordedRunId)
+    }, {
+        // `@smthrs/journal` redacts the credential word `key`. A durable
+        // content identity must use the specific, non-credential name.
+        cacheKey: event.key,
+        verdict: options.verdict,
+        existing: event.existing === undefined ? null : {
+            recordedRunId: event.existing.recordedRunId,
+            recordedEventSeq: event.existing.recordedEventSeq,
+            createdAtMs: event.existing.createdAtMs
+        },
+        attempted: {
+            recordedRunId: event.attempted.recordedRunId,
+            recordedEventSeq: event.attempted.recordedEventSeq,
+            createdAtMs: event.attempted.createdAtMs
+        }
+    }), options.owner), options.verdict)),
+    noteCorruption: Effect.fn("Inconsistency.noteCorruption")((event) => Effect.as(options.journal.emitDurable(JournalRecords.cacheCorruption({
+        runId: event.runId,
+        lineageId: FlowEngine.Lineage.root(event.runId),
+        // The producer identity is the corruption evidence plus the
+        // recorded row generation (issues #156, #172): a caller
+        // re-observing the same corrupt row re-emits an exact producer
+        // duplicate the journal collapses, while an identically corrupt
+        // row recorded after eviction and healing has new provenance and
+        // lands as a distinct incident. Attempt-row evidence has no cache
+        // provenance, so its explicit local markers retain same-row
+        // convergence. A record already landed by another lineage under
+        // this identity surfaces as an idempotency conflict; either way
+        // evidence for that row generation exists exactly once.
+        sourceId: `flows/engine-store/inconsistency:corruption:${event.keyDigest}:${event.path}:${event.recordedDigest}:${event.measuredDigest}:${event.recordedRunId ?? "local"}:${event.recordedEventSeq ?? "local"}`,
+        sourceSeq: 0
+    }, {
+        keyDigest: event.keyDigest,
+        verdict: options.verdict,
+        path: event.path,
+        recordedDigest: event.recordedDigest,
+        measuredDigest: event.measuredDigest,
+        recordedRunId: event.recordedRunId ?? null,
+        recordedEventSeq: event.recordedEventSeq ?? null
+    }), options.owner).pipe(Effect.catch((error) => error.code === "idempotency_conflict" ? Effect.succeed(undefined) : Effect.fail(error))), options.verdict))
+});
+/**
+ * Builds a receiver from overrides. The default notes nothing and tolerates.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = (overrides = {}) => ({
+    note: Effect.fn("Inconsistency.note")(() => Effect.succeed("tolerate")),
+    noteCorruption: Effect.fn("Inconsistency.noteCorruption")(() => Effect.succeed("tolerate")),
+    ...overrides
+});
+/**
+ * Provides a receiver that never journals and always tolerates.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = (overrides = {}) => Layer.succeed(Inconsistency)(makeNoop(overrides));
+/**
+ * Journals every cache conflict and fails the run. This is the default
+ * receiver for engine wiring: a non-hermetic sealed hard-boundary action is
+ * a defect, not a condition to paper over.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerStrict = (owner) => Layer.effect(Inconsistency)(Effect.gen(function* () {
+    const journal = yield* Journal.Journal;
+    return make({ journal, verdict: "fail", owner });
+}));
+/**
+ * Journals every cache conflict and continues, preserving the first-recorded
+ * row (Skyframe's tolerant production configuration).
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerTolerant = (owner) => Layer.effect(Inconsistency)(Effect.gen(function* () {
+    const journal = yield* Journal.Journal;
+    return make({ journal, verdict: "tolerate", owner });
+}));
+//# sourceMappingURL=Inconsistency.js.map

package/dist/esm/Inconsistency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Inconsistency.js","sourceRoot":"","sources":["../../src/Inconsistency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAGzC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,cAAc,MAAM,8BAA8B,CAAA;AAgE9D;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,OAAO,CAAC,OAAO,EAA0B,CAAC,oCAAoC,CAAC;CAAG;AAmBrH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAoB,EAAW,EAAE,CAAC,CAAC;IACtD,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAC9C,MAAM,CAAC,EAAE,CACP,OAAO,CAAC,OAAO,CAAC,WAAW,CACzB,cAAc,CAAC,aAAa,CAC1B;QACE,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,aAAa;QACpC,QAAQ,EAAE,kCAAkC;QAC5C,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC;KAClE,EACD;QACE,iEAAiE;QACjE,+DAA+D;QAC/D,QAAQ,EAAE,KAAK,CAAC,GAAG;QACnB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC9C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,aAAa;YAC3C,gBAAgB,EAAE,KAAK,CAAC,QAAQ,CAAC,gBAAgB;YACjD,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,WAAW;SACxC;QACD,SAAS,EAAE;YACT,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,aAAa;YAC5C,gBAAgB,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB;YAClD,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW;SACzC;KACF,CACF,EACD,OAAO,CAAC,KAAK,CACd,EACD,OAAO,CAAC,OAAO,CAChB,CACF;IACD,cAAc,EAAE,MAAM,CAAC,EAAE,CAAC,8BAA8B,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAClE,MAAM,CAAC,EAAE,CACP,OAAO,CAAC,OAAO,CAAC,WAAW,CACzB,cAAc,CAAC,eAAe,CAC5B;QACE,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QAC/C,4DAA4D;QAC5D,wDAAwD;QACxD,+DAA+D;QAC/D,gEAAgE;QAChE,iEAAiE;QACjE,kEAAkE;QAClE,4DAA4D;QAC5D,gEAAgE;QAChE,gEAAgE;QAChE,wDAAwD;QACxD,QAAQ,EACN,+CAA+C,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,cAAc,IAC1H,KAAK,CAAC,aAAa,IAAI,OACzB,IAAI,KAAK,CAAC,gBAAgB,IAAI,OAAO,EAAE;QACzC,SAAS,EAAE,CAAC;KACb,EACD;QACE,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;QAC1C,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,IAAI,IAAI;KACjD,CACF,EACD,OAAO,CAAC,KAAK,CACd,CAAC,IAAI,CACJ,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,sBAAsB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAChH,EACD,OAAO,CAAC,OAAO,CAChB,CACF;CACF,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,YAA8B,EAAE,EAAW,EAAE,CAAC,CAAC;IACtE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,oBAAoB,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,UAAmB,CAAC,CAAC;IAChF,cAAc,EAAE,MAAM,CAAC,EAAE,CAAC,8BAA8B,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,UAAmB,CAAC,CAAC;IACpG,GAAG,SAAS;CACb,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,YAA8B,EAAE,EAA8B,EAAE,CACxF,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAA;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAwB,EAAsD,EAAE,CAC1G,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CACzB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,CAAA;IACtC,OAAO,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;AAClD,CAAC,CAAC,CACH,CAAA;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAwB,EAAsD,EAAE,CAC5G,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CACzB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,CAAA;IACtC,OAAO,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAA;AACtD,CAAC,CAAC,CACH,CAAA","sourcesContent":["/**\n * Receiver for detected engine inconsistencies.\n *\n * Modeled on Skyframe's `GraphInconsistencyReceiver`: the store layer detects\n * an invariant violation — today, a content-addressed cache key that produced\n * a different result than the recorded row — and this service decides whether\n * the run fails or tolerates it. Either way the conflict is journaled, so the\n * detector is never wired to /dev/null.\n *\n * The `note` signature deliberately matches the plugin spec's\n * `cacheInconsistency` hook (`(event) => Effect<InconsistencyVerdict>`); the\n * strict layer is the future default plugin.\n *\n * The core default is strict so an invariant violation cannot pass silently.\n *\n * Governing designs: `docs/concepts/attempts-and-replay.md` and\n * `apps/site/src/content/docs/docs/concepts/flows-actions-plans.mdx`.\n *\n * @since 0.1.0\n */\n\nimport { FlowEngine } from \"@smthrs/engine\"\nimport { Journal } from \"@smthrs/journal\"\nimport type { Ownership } from \"@smthrs/run-store\"\nimport type { CacheStore } from \"@smthrs/step-cache\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as JournalRecords from \"./internal/JournalRecords.ts\"\n\n/**\n * Decision returned by an inconsistency receiver.\n *\n * @category models\n * @since 0.1.0\n */\nexport type InconsistencyVerdict = \"fail\" | \"tolerate\"\n\n/**\n * A content-addressed cache key that produced a result different from the\n * recorded row — a hermeticity/determinism violation.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface CacheConflict {\n  readonly key: string\n  readonly existing: CacheStore.CacheEntry | undefined\n  readonly attempted: CacheStore.CacheEntry\n}\n\n/**\n * Recorded boundary evidence whose blob no longer hashes to its recorded\n * digest — on-disk corruption of the content-addressed store, detected while\n * replaying a verified cache hit or a succeeded attempt (issue #150).\n * Distinct from a transient host failure, which merely refuses the replay\n * and stays retryable.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface BlobCorruption {\n  /** The run that observed the corruption; the journaling target. */\n  readonly runId: string\n  readonly keyDigest: string\n  readonly path: string\n  readonly recordedDigest: string\n  readonly measuredDigest: string\n  /**\n   * Provenance of the corrupt evidence when it came from a shared cache row;\n   * absent when it came from this run's own succeeded attempt row.\n   */\n  readonly recordedRunId?: string | undefined\n  readonly recordedEventSeq?: number | undefined\n}\n\n/**\n * Inconsistency receiver operations.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  readonly note: (event: CacheConflict) => Effect.Effect<InconsistencyVerdict, Journal.JournalError>\n  /**\n   * Observes on-disk corruption of recorded boundary evidence (issue #150).\n   * `\"fail\"` fails the dispatch; `\"tolerate\"` lets it fall back to a real\n   * execution (which re-captures and heals the corrupt address).\n   */\n  readonly noteCorruption: (event: BlobCorruption) => Effect.Effect<InconsistencyVerdict, Journal.JournalError>\n}\n\n/**\n * Service tag for the engine inconsistency receiver.\n *\n * @category services\n * @since 0.1.0\n */\nexport class Inconsistency extends Context.Service<Inconsistency, Service>()(\"@smthrs/engine-store/Inconsistency\") {}\n\n/**\n * Options for constructing a journaling inconsistency receiver.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface MakeOptions {\n  readonly journal: Journal.Service\n  readonly verdict: InconsistencyVerdict\n  /**\n   * The owner the conflict record is fenced to: a reclaimed run cannot append\n   * hermeticity evidence it no longer owns. Required — every composer of this\n   * receiver is a run's owner.\n   */\n  readonly owner: Ownership.OwnerId\n}\n\n/**\n * Builds a receiver that journals every conflict under the run that attempted\n * the write and returns a fixed verdict.\n *\n * The record goes through the journal's durable channel: a cache conflict is\n * hermeticity evidence, and a `tolerate` verdict that silently dropped its\n * only record would wire the detector to /dev/null (issue #10).\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (options: MakeOptions): Service => ({\n  note: Effect.fn(\"Inconsistency.note\")((event) =>\n    Effect.as(\n      options.journal.emitDurable(\n        JournalRecords.cacheConflict(\n          {\n            runId: event.attempted.recordedRunId,\n            sourceId: \"flows/engine-store/inconsistency\",\n            lineageId: FlowEngine.Lineage.root(event.attempted.recordedRunId)\n          },\n          {\n            // `@smthrs/journal` redacts the credential word `key`. A durable\n            // content identity must use the specific, non-credential name.\n            cacheKey: event.key,\n            verdict: options.verdict,\n            existing: event.existing === undefined ? null : {\n              recordedRunId: event.existing.recordedRunId,\n              recordedEventSeq: event.existing.recordedEventSeq,\n              createdAtMs: event.existing.createdAtMs\n            },\n            attempted: {\n              recordedRunId: event.attempted.recordedRunId,\n              recordedEventSeq: event.attempted.recordedEventSeq,\n              createdAtMs: event.attempted.createdAtMs\n            }\n          }\n        ),\n        options.owner\n      ),\n      options.verdict\n    )\n  ),\n  noteCorruption: Effect.fn(\"Inconsistency.noteCorruption\")((event) =>\n    Effect.as(\n      options.journal.emitDurable(\n        JournalRecords.cacheCorruption(\n          {\n            runId: event.runId,\n            lineageId: FlowEngine.Lineage.root(event.runId),\n            // The producer identity is the corruption evidence plus the\n            // recorded row generation (issues #156, #172): a caller\n            // re-observing the same corrupt row re-emits an exact producer\n            // duplicate the journal collapses, while an identically corrupt\n            // row recorded after eviction and healing has new provenance and\n            // lands as a distinct incident. Attempt-row evidence has no cache\n            // provenance, so its explicit local markers retain same-row\n            // convergence. A record already landed by another lineage under\n            // this identity surfaces as an idempotency conflict; either way\n            // evidence for that row generation exists exactly once.\n            sourceId:\n              `flows/engine-store/inconsistency:corruption:${event.keyDigest}:${event.path}:${event.recordedDigest}:${event.measuredDigest}:${\n                event.recordedRunId ?? \"local\"\n              }:${event.recordedEventSeq ?? \"local\"}`,\n            sourceSeq: 0\n          },\n          {\n            keyDigest: event.keyDigest,\n            verdict: options.verdict,\n            path: event.path,\n            recordedDigest: event.recordedDigest,\n            measuredDigest: event.measuredDigest,\n            recordedRunId: event.recordedRunId ?? null,\n            recordedEventSeq: event.recordedEventSeq ?? null\n          }\n        ),\n        options.owner\n      ).pipe(\n        Effect.catch((error) => error.code === \"idempotency_conflict\" ? Effect.succeed(undefined) : Effect.fail(error))\n      ),\n      options.verdict\n    )\n  )\n})\n\n/**\n * Builds a receiver from overrides. The default notes nothing and tolerates.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeNoop = (overrides: Partial<Service> = {}): Service => ({\n  note: Effect.fn(\"Inconsistency.note\")(() => Effect.succeed(\"tolerate\" as const)),\n  noteCorruption: Effect.fn(\"Inconsistency.noteCorruption\")(() => Effect.succeed(\"tolerate\" as const)),\n  ...overrides\n})\n\n/**\n * Provides a receiver that never journals and always tolerates.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop = (overrides: Partial<Service> = {}): Layer.Layer<Inconsistency> =>\n  Layer.succeed(Inconsistency)(makeNoop(overrides))\n\n/**\n * Journals every cache conflict and fails the run. This is the default\n * receiver for engine wiring: a non-hermetic sealed hard-boundary action is\n * a defect, not a condition to paper over.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerStrict = (owner: Ownership.OwnerId): Layer.Layer<Inconsistency, never, Journal.Journal> =>\n  Layer.effect(Inconsistency)(\n    Effect.gen(function*() {\n      const journal = yield* Journal.Journal\n      return make({ journal, verdict: \"fail\", owner })\n    })\n  )\n\n/**\n * Journals every cache conflict and continues, preserving the first-recorded\n * row (Skyframe's tolerant production configuration).\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerTolerant = (owner: Ownership.OwnerId): Layer.Layer<Inconsistency, never, Journal.Journal> =>\n  Layer.effect(Inconsistency)(\n    Effect.gen(function*() {\n      const journal = yield* Journal.Journal\n      return make({ journal, verdict: \"tolerate\", owner })\n    })\n  )\n"]}

package/dist/esm/Migrations.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Durable engine schema migrations.
+ *
+ * Engine-store owns persisted deferred/clock state, execution selections,
+ * and append-only plan-input observations. These are authoritative execution
+ * records, distinct from journal projections and evictable step-cache rows.
+ * It reserves migration id block `3000`.
+ *
+ * Because engine-store composes the journal, the run store, and the step
+ * cache, {@link sets} is also the full durable schema an engine needs, and
+ * {@link layer} installs it in dependency order.
+ *
+ * Derived contracts: `docs/api.md` ("Migrations") and
+ * `packages/smithers/flows/journal/docs/api.md`.
+ *
+ * @since 0.1.0
+ */
+import * as DatabaseMigrations from "@smthrs/database/Migrations";
+import * as Layer from "effect/Layer";
+/**
+ * Engine-store's own namespaced migration set.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export declare const set: DatabaseMigrations.MigrationSet;
+/**
+ * Every migration set a durable engine needs, in dependency order: journal
+ * events, run and attempt state, the step cache, the engine's own deferred and
+ * clock, selection, and input tables, then the persisted plan.
+ *
+ * The plan set has the highest id block (`4000`). The database loader applies
+ * forward additions within already installed blocks transactionally before
+ * the ordinary migration pass (for example, engine-store `3003` after plan
+ * `4003`). Earlier holes and entirely new lower blocks remain refusals.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export declare const sets: ReadonlyArray<DatabaseMigrations.MigrationSet>;
+/**
+ * Creates the complete durable engine schema.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export declare const run: import("effect/Effect").Effect<readonly (readonly [id: number, name: string])[], import("effect/unstable/sql/SqlError").SqlError | import("effect/unstable/sql/Migrator").MigrationError, import("effect/unstable/sql/SqlClient").SqlClient>;
+/**
+ * Layer that installs the complete durable engine schema before exposing the
+ * database to any durable service.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<never, import("effect/unstable/sql/SqlError").SqlError | import("effect/unstable/sql/Migrator").MigrationError, import("effect/unstable/sql/SqlClient").SqlClient>;
+//# sourceMappingURL=Migrations.d.ts.map

package/dist/esm/Migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Migrations.d.ts","sourceRoot":"","sources":["../../src/Migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,kBAAkB,MAAM,6BAA6B,CAAA;AAKjE,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAYrC;;;;;GAKG;AACH,eAAO,MAAM,GAAG,EAAE,kBAAkB,CAAC,YAepC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI,EAAE,aAAa,CAAC,kBAAkB,CAAC,YAAY,CAM/D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,GAAG,8OAA+B,CAAA;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,gLAA2B,CAAA"}

package/dist/esm/Migrations.js

@@ -0,0 +1,91 @@
+/**
+ * Durable engine schema migrations.
+ *
+ * Engine-store owns persisted deferred/clock state, execution selections,
+ * and append-only plan-input observations. These are authoritative execution
+ * records, distinct from journal projections and evictable step-cache rows.
+ * It reserves migration id block `3000`.
+ *
+ * Because engine-store composes the journal, the run store, and the step
+ * cache, {@link sets} is also the full durable schema an engine needs, and
+ * {@link layer} installs it in dependency order.
+ *
+ * Derived contracts: `docs/api.md` ("Migrations") and
+ * `packages/smithers/flows/journal/docs/api.md`.
+ *
+ * @since 0.1.0
+ */
+import * as DatabaseMigrations from "@smthrs/database/Migrations";
+import * as JournalMigrations from "@smthrs/journal/Migrations";
+import * as PlanMigrations from "@smthrs/plan-store/Migrations";
+import * as RunStoreMigrations from "@smthrs/run-store/Migrations";
+import * as StepCacheMigrations from "@smthrs/step-cache/Migrations";
+import * as Layer from "effect/Layer";
+import { initial } from "./migrations/0001_initial.js";
+import { selectionStore } from "./migrations/0002_selection_store.js";
+import { planInputs } from "./migrations/0003_plan_inputs.js";
+import { planEnvironment } from "./migrations/0004_plan_environment.js";
+import { planMerges } from "./migrations/0005_plan_merges.js";
+import { executionListing } from "./migrations/0006_execution_listing.js";
+import { runParentSequence } from "./migrations/0007_run_parent_sequence.js";
+import { deferredConsumption } from "./migrations/0008_deferred_consumption.js";
+import { deferredClockFacts } from "./migrations/0009_deferred_clock_facts.js";
+import { pendingCancellation } from "./migrations/0010_pending_cancellation.js";
+/**
+ * Engine-store's own namespaced migration set.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const set = {
+    namespace: "engine-store",
+    idOffset: DatabaseMigrations.idBlock * 3,
+    migrations: {
+        "0001_initial": initial,
+        "0002_selection_store": selectionStore,
+        "0003_plan_inputs": planInputs,
+        "0004_plan_environment": planEnvironment,
+        "0005_plan_merges": planMerges,
+        "0006_execution_listing": executionListing,
+        "0007_run_parent_sequence": runParentSequence,
+        "0008_deferred_consumption": deferredConsumption,
+        "0009_deferred_clock_facts": deferredClockFacts,
+        "0010_pending_cancellation": pendingCancellation
+    }
+};
+/**
+ * Every migration set a durable engine needs, in dependency order: journal
+ * events, run and attempt state, the step cache, the engine's own deferred and
+ * clock, selection, and input tables, then the persisted plan.
+ *
+ * The plan set has the highest id block (`4000`). The database loader applies
+ * forward additions within already installed blocks transactionally before
+ * the ordinary migration pass (for example, engine-store `3003` after plan
+ * `4003`). Earlier holes and entirely new lower blocks remain refusals.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const sets = [
+    JournalMigrations.set,
+    RunStoreMigrations.set,
+    StepCacheMigrations.set,
+    set,
+    PlanMigrations.set
+];
+/**
+ * Creates the complete durable engine schema.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const run = DatabaseMigrations.run(sets);
+/**
+ * Layer that installs the complete durable engine schema before exposing the
+ * database to any durable service.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.effectDiscard(run);
+//# sourceMappingURL=Migrations.js.map

package/dist/esm/Migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Migrations.js","sourceRoot":"","sources":["../../src/Migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,kBAAkB,MAAM,6BAA6B,CAAA;AACjE,OAAO,KAAK,iBAAiB,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,cAAc,MAAM,+BAA+B,CAAA;AAC/D,OAAO,KAAK,kBAAkB,MAAM,8BAA8B,CAAA;AAClE,OAAO,KAAK,mBAAmB,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAA;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAA;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAA;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAA;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAA;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAA;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAA;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAA;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,GAAG,GAAoC;IAClD,SAAS,EAAE,cAAc;IACzB,QAAQ,EAAE,kBAAkB,CAAC,OAAO,GAAG,CAAC;IACxC,UAAU,EAAE;QACV,cAAc,EAAE,OAAO;QACvB,sBAAsB,EAAE,cAAc;QACtC,kBAAkB,EAAE,UAAU;QAC9B,uBAAuB,EAAE,eAAe;QACxC,kBAAkB,EAAE,UAAU;QAC9B,wBAAwB,EAAE,gBAAgB;QAC1C,0BAA0B,EAAE,iBAAiB;QAC7C,2BAA2B,EAAE,mBAAmB;QAChD,2BAA2B,EAAE,kBAAkB;QAC/C,2BAA2B,EAAE,mBAAmB;KACjD;CACF,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,IAAI,GAAmD;IAClE,iBAAiB,CAAC,GAAG;IACrB,kBAAkB,CAAC,GAAG;IACtB,mBAAmB,CAAC,GAAG;IACvB,GAAG;IACH,cAAc,CAAC,GAAG;CACnB,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,CAAA","sourcesContent":["/**\n * Durable engine schema migrations.\n *\n * Engine-store owns persisted deferred/clock state, execution selections,\n * and append-only plan-input observations. These are authoritative execution\n * records, distinct from journal projections and evictable step-cache rows.\n * It reserves migration id block `3000`.\n *\n * Because engine-store composes the journal, the run store, and the step\n * cache, {@link sets} is also the full durable schema an engine needs, and\n * {@link layer} installs it in dependency order.\n *\n * Derived contracts: `docs/api.md` (\"Migrations\") and\n * `packages/smithers/flows/journal/docs/api.md`.\n *\n * @since 0.1.0\n */\n\nimport * as DatabaseMigrations from \"@smthrs/database/Migrations\"\nimport * as JournalMigrations from \"@smthrs/journal/Migrations\"\nimport * as PlanMigrations from \"@smthrs/plan-store/Migrations\"\nimport * as RunStoreMigrations from \"@smthrs/run-store/Migrations\"\nimport * as StepCacheMigrations from \"@smthrs/step-cache/Migrations\"\nimport * as Layer from \"effect/Layer\"\nimport { initial } from \"./migrations/0001_initial.ts\"\nimport { selectionStore } from \"./migrations/0002_selection_store.ts\"\nimport { planInputs } from \"./migrations/0003_plan_inputs.ts\"\nimport { planEnvironment } from \"./migrations/0004_plan_environment.ts\"\nimport { planMerges } from \"./migrations/0005_plan_merges.ts\"\nimport { executionListing } from \"./migrations/0006_execution_listing.ts\"\nimport { runParentSequence } from \"./migrations/0007_run_parent_sequence.ts\"\nimport { deferredConsumption } from \"./migrations/0008_deferred_consumption.ts\"\nimport { deferredClockFacts } from \"./migrations/0009_deferred_clock_facts.ts\"\nimport { pendingCancellation } from \"./migrations/0010_pending_cancellation.ts\"\n\n/**\n * Engine-store's own namespaced migration set.\n *\n * @category migrations\n * @since 0.1.0\n */\nexport const set: DatabaseMigrations.MigrationSet = {\n  namespace: \"engine-store\",\n  idOffset: DatabaseMigrations.idBlock * 3,\n  migrations: {\n    \"0001_initial\": initial,\n    \"0002_selection_store\": selectionStore,\n    \"0003_plan_inputs\": planInputs,\n    \"0004_plan_environment\": planEnvironment,\n    \"0005_plan_merges\": planMerges,\n    \"0006_execution_listing\": executionListing,\n    \"0007_run_parent_sequence\": runParentSequence,\n    \"0008_deferred_consumption\": deferredConsumption,\n    \"0009_deferred_clock_facts\": deferredClockFacts,\n    \"0010_pending_cancellation\": pendingCancellation\n  }\n}\n\n/**\n * Every migration set a durable engine needs, in dependency order: journal\n * events, run and attempt state, the step cache, the engine's own deferred and\n * clock, selection, and input tables, then the persisted plan.\n *\n * The plan set has the highest id block (`4000`). The database loader applies\n * forward additions within already installed blocks transactionally before\n * the ordinary migration pass (for example, engine-store `3003` after plan\n * `4003`). Earlier holes and entirely new lower blocks remain refusals.\n *\n * @category migrations\n * @since 0.1.0\n */\nexport const sets: ReadonlyArray<DatabaseMigrations.MigrationSet> = [\n  JournalMigrations.set,\n  RunStoreMigrations.set,\n  StepCacheMigrations.set,\n  set,\n  PlanMigrations.set\n]\n\n/**\n * Creates the complete durable engine schema.\n *\n * @category migrations\n * @since 0.1.0\n */\nexport const run = DatabaseMigrations.run(sets)\n\n/**\n * Layer that installs the complete durable engine schema before exposing the\n * database to any durable service.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer = Layer.effectDiscard(run)\n"]}

package/dist/esm/OwnerIdentity.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The source of the fencing identity a store incarnation runs under.
+ *
+ * Minting an {@link OwnerId} is an act of nondeterminism against the host: it
+ * reads a process identifier and draws a fresh nonce. Both belong behind a
+ * port rather than in the composition itself — the closed-host doctrine in
+ * `@smthrs/kernel`'s `HostServices` admits no ambient `process` and no static
+ * `node:crypto` import, and browser support is a hard requirement, so a store
+ * that reached for either directly could not be composed in a tab at all.
+ *
+ * Governing design: `docs/concepts/ownership-and-fencing.md`.
+ *
+ * @since 0.1.0
+ */
+import type { OwnerId } from "@smthrs/journal/OwnerId";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+/**
+ * Owner identity operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    /**
+     * Mints the identity this incarnation fences its durable writes with. The
+     * host supplies the incarnation; the caller supplies the host id, because
+     * which host a store speaks for is a composition decision, not a host fact.
+     */
+    readonly ownerId: (hostId: string) => Effect.Effect<OwnerId>;
+}
+declare const OwnerIdentity_base: Context.ServiceClass<OwnerIdentity, "@smthrs/engine-store/OwnerIdentity", Service>;
+/**
+ * Service tag for the owner identity source.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class OwnerIdentity extends OwnerIdentity_base {
+}
+/**
+ * Constructs an owner identity source from an implementation.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (service: Service) => Service;
+/**
+ * Builds the standard identity source over an explicitly supplied process id
+ * and the injected `Crypto` service.
+ *
+ * On node and bun `pid` is the real process id, so the minted token is exactly
+ * what the store produced before this service existed. A browser tab has no
+ * process, and no stable per-tab integer that means the same thing, so
+ * `undefined` draws an incarnation number instead: the component's only job is
+ * to distinguish concurrent incarnations on one host, and `Random` is the
+ * sanctioned port for drawing one. Effect's own cluster storage does the same
+ * where a backend exposes no connection pid (`reference/effect`
+ * `unstable/cluster/SqlRunnerStorage.ts`).
+ *
+ * The nonce is a UUIDv4 drawn from the injected `effect/Crypto` service — the
+ * closed-host seam every composition already provides for digesting — so no
+ * ambient `crypto` global is reached from a hot path. A host whose crypto
+ * cannot mint a UUID cannot fence anything, so that refusal is a defect.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeIncarnation: (pid: number | undefined, crypto: Crypto.Crypto) => Service;
+/**
+ * Provides {@link makeIncarnation} over whatever process id the running
+ * platform reports and the composition's `Crypto` service. This is what
+ * engine composition supplies unless a host has a better answer.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<OwnerIdentity, never, Crypto.Crypto>;
+/**
+ * Provides a fixed identity. A test — or a host that derives ownership from
+ * something outside this process, such as a lease it already holds — pins the
+ * whole token instead of letting the default draw one.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerConstant: (owner: OwnerId) => Layer.Layer<OwnerIdentity>;
+export {};
+//# sourceMappingURL=OwnerIdentity.d.ts.map

package/dist/esm/OwnerIdentity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OwnerIdentity.d.ts","sourceRoot":"","sources":["../../src/OwnerIdentity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAGrC;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;CAC7D;;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,kBAA+E;CAAG;AAErH;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,OAAO,KAAG,OAAoC,CAAA;AAc5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,GAAG,SAAS,EAAE,QAAQ,MAAM,CAAC,MAAM,KAAG,OAchF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAGlE,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,CAAC,KAAK,CAAC,aAAa,CACM,CAAA"}

package/dist/esm/OwnerIdentity.js

@@ -0,0 +1,99 @@
+/**
+ * The source of the fencing identity a store incarnation runs under.
+ *
+ * Minting an {@link OwnerId} is an act of nondeterminism against the host: it
+ * reads a process identifier and draws a fresh nonce. Both belong behind a
+ * port rather than in the composition itself — the closed-host doctrine in
+ * `@smthrs/kernel`'s `HostServices` admits no ambient `process` and no static
+ * `node:crypto` import, and browser support is a hard requirement, so a store
+ * that reached for either directly could not be composed in a tab at all.
+ *
+ * Governing design: `docs/concepts/ownership-and-fencing.md`.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Random from "effect/Random";
+/**
+ * Service tag for the owner identity source.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class OwnerIdentity extends Context.Service()("@smthrs/engine-store/OwnerIdentity") {
+}
+/**
+ * Constructs an owner identity source from an implementation.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (service) => OwnerIdentity.of(service);
+/**
+ * The host's process identifier, when the platform has one.
+ *
+ * Read off `globalThis` rather than through a bare `process` reference so the
+ * module carries no Node binding at all: a browser bundle sees `undefined`
+ * here and falls through to a drawn incarnation number instead. The read
+ * happens at layer construction — {@link layer} — so importing the module
+ * touches nothing.
+ */
+const hostProcessId = () => globalThis.process?.pid;
+/**
+ * Builds the standard identity source over an explicitly supplied process id
+ * and the injected `Crypto` service.
+ *
+ * On node and bun `pid` is the real process id, so the minted token is exactly
+ * what the store produced before this service existed. A browser tab has no
+ * process, and no stable per-tab integer that means the same thing, so
+ * `undefined` draws an incarnation number instead: the component's only job is
+ * to distinguish concurrent incarnations on one host, and `Random` is the
+ * sanctioned port for drawing one. Effect's own cluster storage does the same
+ * where a backend exposes no connection pid (`reference/effect`
+ * `unstable/cluster/SqlRunnerStorage.ts`).
+ *
+ * The nonce is a UUIDv4 drawn from the injected `effect/Crypto` service — the
+ * closed-host seam every composition already provides for digesting — so no
+ * ambient `crypto` global is reached from a hot path. A host whose crypto
+ * cannot mint a UUID cannot fence anything, so that refusal is a defect.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeIncarnation = (pid, crypto) => {
+    const incarnationId = pid === undefined
+        ? Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true })
+        : Effect.succeed(pid);
+    return make({
+        ownerId: Effect.fn("OwnerIdentity.ownerId")(function* (hostId) {
+            yield* Effect.annotateCurrentSpan({ hostId });
+            return {
+                hostId,
+                pid: yield* incarnationId,
+                nonce: yield* crypto.randomUUIDv4.pipe(Effect.orDie)
+            };
+        })
+    });
+};
+/**
+ * Provides {@link makeIncarnation} over whatever process id the running
+ * platform reports and the composition's `Crypto` service. This is what
+ * engine composition supplies unless a host has a better answer.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.effect(OwnerIdentity, Effect.map(Crypto.Crypto, (crypto) => makeIncarnation(hostProcessId(), crypto)));
+/**
+ * Provides a fixed identity. A test — or a host that derives ownership from
+ * something outside this process, such as a lease it already holds — pins the
+ * whole token instead of letting the default draw one.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerConstant = (owner) => Layer.succeed(OwnerIdentity)(make({ ownerId: () => Effect.succeed(owner) }));
+//# sourceMappingURL=OwnerIdentity.js.map

package/dist/esm/OwnerIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OwnerIdentity.js","sourceRoot":"","sources":["../../src/OwnerIdentity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAiBvC;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,OAAO,CAAC,OAAO,EAA0B,CAAC,oCAAoC,CAAC;CAAG;AAErH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAgB,EAAW,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,CAAC,CAAA;AAE5E;;;;;;;;GAQG;AACH,MAAM,aAAa,GAAG,GAAuB,EAAE,CAC5C,UAA+D,CAAC,OAAO,EAAE,GAAG,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAuB,EAAE,MAAqB,EAAW,EAAE;IACzF,MAAM,aAAa,GAA0B,GAAG,KAAK,SAAS;QAC5D,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,EAAE,MAAM,CAAC,gBAAgB,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QACvE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACvB,OAAO,IAAI,CAAC;QACV,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,uBAAuB,CAAC,CAAC,QAAQ,CAAC,EAAC,MAAM;YAC1D,KAAK,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;YAC7C,OAAO;gBACL,MAAM;gBACN,GAAG,EAAE,KAAK,CAAC,CAAC,aAAa;gBACzB,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;aACnC,CAAA;QACrB,CAAC,CAAC;KACH,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAqD,KAAK,CAAC,MAAM,CACjF,aAAa,EACb,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,CAAC,aAAa,EAAE,EAAE,MAAM,CAAC,CAAC,CAChF,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAc,EAA8B,EAAE,CAC1E,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA","sourcesContent":["/**\n * The source of the fencing identity a store incarnation runs under.\n *\n * Minting an {@link OwnerId} is an act of nondeterminism against the host: it\n * reads a process identifier and draws a fresh nonce. Both belong behind a\n * port rather than in the composition itself — the closed-host doctrine in\n * `@smthrs/kernel`'s `HostServices` admits no ambient `process` and no static\n * `node:crypto` import, and browser support is a hard requirement, so a store\n * that reached for either directly could not be composed in a tab at all.\n *\n * Governing design: `docs/concepts/ownership-and-fencing.md`.\n *\n * @since 0.1.0\n */\n\nimport type { OwnerId } from \"@smthrs/journal/OwnerId\"\nimport * as Context from \"effect/Context\"\nimport * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Random from \"effect/Random\"\n\n/**\n * Owner identity operations.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  /**\n   * Mints the identity this incarnation fences its durable writes with. The\n   * host supplies the incarnation; the caller supplies the host id, because\n   * which host a store speaks for is a composition decision, not a host fact.\n   */\n  readonly ownerId: (hostId: string) => Effect.Effect<OwnerId>\n}\n\n/**\n * Service tag for the owner identity source.\n *\n * @category services\n * @since 0.1.0\n */\nexport class OwnerIdentity extends Context.Service<OwnerIdentity, Service>()(\"@smthrs/engine-store/OwnerIdentity\") {}\n\n/**\n * Constructs an owner identity source from an implementation.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (service: Service): Service => OwnerIdentity.of(service)\n\n/**\n * The host's process identifier, when the platform has one.\n *\n * Read off `globalThis` rather than through a bare `process` reference so the\n * module carries no Node binding at all: a browser bundle sees `undefined`\n * here and falls through to a drawn incarnation number instead. The read\n * happens at layer construction — {@link layer} — so importing the module\n * touches nothing.\n */\nconst hostProcessId = (): number | undefined =>\n  (globalThis as { readonly process?: { readonly pid?: number } }).process?.pid\n\n/**\n * Builds the standard identity source over an explicitly supplied process id\n * and the injected `Crypto` service.\n *\n * On node and bun `pid` is the real process id, so the minted token is exactly\n * what the store produced before this service existed. A browser tab has no\n * process, and no stable per-tab integer that means the same thing, so\n * `undefined` draws an incarnation number instead: the component's only job is\n * to distinguish concurrent incarnations on one host, and `Random` is the\n * sanctioned port for drawing one. Effect's own cluster storage does the same\n * where a backend exposes no connection pid (`reference/effect`\n * `unstable/cluster/SqlRunnerStorage.ts`).\n *\n * The nonce is a UUIDv4 drawn from the injected `effect/Crypto` service — the\n * closed-host seam every composition already provides for digesting — so no\n * ambient `crypto` global is reached from a hot path. A host whose crypto\n * cannot mint a UUID cannot fence anything, so that refusal is a defect.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeIncarnation = (pid: number | undefined, crypto: Crypto.Crypto): Service => {\n  const incarnationId: Effect.Effect<number> = pid === undefined\n    ? Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true })\n    : Effect.succeed(pid)\n  return make({\n    ownerId: Effect.fn(\"OwnerIdentity.ownerId\")(function*(hostId) {\n      yield* Effect.annotateCurrentSpan({ hostId })\n      return {\n        hostId,\n        pid: yield* incarnationId,\n        nonce: yield* crypto.randomUUIDv4.pipe(Effect.orDie)\n      } satisfies OwnerId\n    })\n  })\n}\n\n/**\n * Provides {@link makeIncarnation} over whatever process id the running\n * platform reports and the composition's `Crypto` service. This is what\n * engine composition supplies unless a host has a better answer.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<OwnerIdentity, never, Crypto.Crypto> = Layer.effect(\n  OwnerIdentity,\n  Effect.map(Crypto.Crypto, (crypto) => makeIncarnation(hostProcessId(), crypto))\n)\n\n/**\n * Provides a fixed identity. A test — or a host that derives ownership from\n * something outside this process, such as a lease it already holds — pins the\n * whole token instead of letting the default draw one.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerConstant = (owner: OwnerId): Layer.Layer<OwnerIdentity> =>\n  Layer.succeed(OwnerIdentity)(make({ ownerId: () => Effect.succeed(owner) }))\n"]}

package/dist/esm/PlanInputStore.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 { DurableWriter } from "@smthrs/database/DurableWriter";
+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";
+/**
+ * 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 declare const Address: Schema.Struct<{
+    readonly runId: Schema.NonEmptyString;
+    readonly planId: Schema.NonEmptyString;
+    readonly baseDigest: Schema.NonEmptyString;
+    readonly environmentDigest: Schema.NonEmptyString;
+    readonly generation: Schema.Int;
+}>;
+/**
+ * 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 declare const maximumSnapshotCharacters: number;
+/**
+ * Frozen membership and newly pinned source digests for one generation.
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const Snapshot: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly generation: Schema.Int;
+    readonly nodes: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.NonEmptyString;
+        readonly key: Schema.NonEmptyString;
+        readonly reads: Schema.$Array<Schema.Struct<{
+            readonly entry: Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+                readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+                readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+            }>]>;
+            readonly sourcePaths: Schema.$Array<Schema.NonEmptyString>;
+        }>>;
+    }>>;
+    readonly pins: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly 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;
+declare const PlanInputError_base: Schema.Class<PlanInputError, Schema.TaggedStruct<"@smthrs/engine-store/PlanInputError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "corrupt_state", "incompatible_state", "fence_lost", "transaction_open", "persistence_failed"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A durable observation cannot be read or safely admitted.
+ * @since 1.0.0
+ * @category errors
+ */
+export declare class PlanInputError extends PlanInputError_base {
+}
+/**
+ * `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>;
+}
+declare const PlanInputStore_base: Context.ServiceClass<PlanInputStore, "@smthrs/engine-store/PlanInputStore", Service>;
+/**
+ * Durable plan-input service.
+ * @since 1.0.0
+ * @category services
+ */
+export declare class PlanInputStore extends PlanInputStore_base {
+}
+/**
+ * Builds the SQL-backed, owner-fenced store.
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const make: Effect.Effect<Service, never, SqlClient.SqlClient | DurableWriter | Crypto.Crypto>;
+/**
+ * Provides the SQL-backed input store over the same database as the run/attempt stores.
+ * @since 1.0.0
+ * @category layers
+ */
+export declare const layer: Layer.Layer<PlanInputStore, never, SqlClient.SqlClient | DurableWriter | Crypto.Crypto>;
+export {};
+//# sourceMappingURL=PlanInputStore.d.ts.map

package/dist/esm/PlanInputStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlanInputStore.d.ts","sourceRoot":"","sources":["../../src/PlanInputStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAE9D,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAA;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/D,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAI1D;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;;;;EAMlB,CAAA;AACF;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAA;AAEzC;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAmB,CAAA;AAEzD;;;;GAIG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;EAYnB,CAAA;AACF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;;;;;;AAE3C;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,mBAWlC;CAAG;AAEL;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAA;IAC1G,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAA;CACnH;;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,mBAAiF;CAAG;AAsCxH;;;;GAIG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,GAAG,aAAa,GAAG,MAAM,CAAC,MAAM,CAuInG,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,GAAG,aAAa,GAAG,MAAM,CAAC,MAAM,CAGjG,CAAA"}