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

package/dist/esm/migrations/0009_deferred_clock_facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0009_deferred_clock_facts.js","sourceRoot":"","sources":["../../../src/migrations/0009_deferred_clock_facts.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Backfills the journal records the deferred/clock fold reads.\n *\n * @since 1.0.0\n */\n\nimport { FlowEngine } from \"@smthrs/engine\"\nimport * as JournalEvent from \"@smthrs/journal/JournalEvent\"\nimport * as Effect from \"effect/Effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\nimport { EventTypes } from \"../EventTypes.ts\"\n\ninterface ClockRow {\n  readonly flow_name: string\n  readonly execution_id: string\n  readonly clock_name: string\n  readonly deferred_name: string\n  readonly due_at_ms: number | string\n  readonly completed_at_ms: number | string | null\n}\n\ninterface DeferredRow {\n  readonly flow_name: string\n  readonly execution_id: string\n  readonly deferred_name: string\n  readonly exit_json: string\n  readonly metadata_json: string | null\n  readonly completed_at_ms: number | string\n  readonly consumed_at_ms: number | string | null\n}\n\nconst optionalTime = (value: number | string | null): number | null => value === null ? null : Number(value)\n\n/**\n * Journals every deferred/clock change written before the fold's records\n * existed: a clock row with no `clock-scheduled` record, a completed clock\n * with no `clock-completed` record, a completion with no `deferred-completed`\n * record, and a consumed completion with no `deferred-consumed` record. Without\n * them a rebuild would drop the clock, or re-arm a completed one and wake a run\n * for a result it already observed (issue #2037).\n *\n * Each backfilled record is appended at the run's next sequence under a\n * `flows.engine.backfill:` producer whose identity names the row, with the\n * lineage meta every engine record carries.\n *\n * @category migrations\n * @since 1.0.0\n */\nexport const deferredClockFacts: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {\n  const sql = yield* SqlClient.SqlClient\n  const recorded = new Set<string>()\n  const events = yield* sql<{ readonly run_id: string; readonly event_type: string; readonly payload_json: string }>`\n    SELECT run_id, event_type, payload_json FROM flows_journal_events\n    WHERE ${\n    sql.in(\"event_type\", [\n      EventTypes.clockScheduled,\n      EventTypes.clockCompleted,\n      EventTypes.deferredCompleted,\n      EventTypes.deferredConsumed\n    ])\n  }\n  `\n  for (const event of events) {\n    const payload = JSON.parse(event.payload_json) as Record<string, unknown>\n    const name = event.event_type === EventTypes.clockScheduled || event.event_type === EventTypes.clockCompleted\n      ? payload.clockName\n      : payload.deferredName\n    recorded.add(JSON.stringify([event.event_type, payload.flowName, payload.executionId, name]))\n  }\n  const next = new Map<string, number>()\n  const append = (\n    eventType: string,\n    executionId: string,\n    name: string,\n    emittedAtMs: number,\n    payload: Readonly<Record<string, unknown>>\n  ) =>\n    Effect.gen(function*() {\n      const identity = JSON.stringify([eventType, payload.flowName, executionId, name])\n      if (recorded.has(identity)) return\n      recorded.add(identity)\n      let seq = next.get(executionId)\n      if (seq === undefined) {\n        const rows = yield* sql<{ readonly next: number | string | null }>`\n          SELECT MAX(seq) + 1 AS next FROM flows_journal_events WHERE run_id = ${executionId}\n        `\n        seq = Number(rows[0]?.next ?? 0)\n      }\n      next.set(executionId, seq + 1)\n      const sourceId = `flows.engine.backfill:${JournalEvent.contentDigest(identity)}`\n      yield* sql`\n        INSERT INTO flows_journal_events (\n          run_id, seq, event_id, source_id, source_seq, emitted_at_ms, event_type, payload_json, meta_json\n        ) VALUES (\n          ${executionId},\n          ${seq},\n          ${\n        JournalEvent.makeEventId(\n          executionId as JournalEvent.RunId,\n          sourceId as JournalEvent.SourceId,\n          0 as JournalEvent.SourceSeq\n        )\n      },\n          ${sourceId},\n          ${0},\n          ${emittedAtMs},\n          ${eventType},\n          ${JSON.stringify(payload)},\n          ${JSON.stringify({ lineageId: FlowEngine.Lineage.root(executionId) })}\n        )\n      `\n    })\n\n  const clocks = yield* sql<ClockRow>`\n    SELECT flow_name, execution_id, clock_name, deferred_name, due_at_ms, completed_at_ms\n    FROM flows_clock_deadlines\n    ORDER BY execution_id, flow_name, clock_name\n  `\n  for (const clock of clocks) {\n    const dueAtMs = Number(clock.due_at_ms)\n    const completedAtMs = optionalTime(clock.completed_at_ms)\n    yield* append(EventTypes.clockScheduled, clock.execution_id, clock.clock_name, completedAtMs ?? dueAtMs, {\n      flowName: clock.flow_name,\n      executionId: clock.execution_id,\n      clockName: clock.clock_name,\n      deferredName: clock.deferred_name,\n      dueAtMs\n    })\n    if (completedAtMs !== null) {\n      yield* append(EventTypes.clockCompleted, clock.execution_id, clock.clock_name, completedAtMs, {\n        flowName: clock.flow_name,\n        executionId: clock.execution_id,\n        clockName: clock.clock_name,\n        completedAtMs\n      })\n    }\n  }\n  const deferreds = yield* sql<DeferredRow>`\n    SELECT flow_name, execution_id, deferred_name, exit_json, metadata_json, completed_at_ms, consumed_at_ms\n    FROM flows_deferred_completions\n    ORDER BY execution_id, flow_name, deferred_name\n  `\n  for (const deferred of deferreds) {\n    const completedAtMs = Number(deferred.completed_at_ms)\n    const consumedAtMs = optionalTime(deferred.consumed_at_ms)\n    yield* append(EventTypes.deferredCompleted, deferred.execution_id, deferred.deferred_name, completedAtMs, {\n      flowName: deferred.flow_name,\n      executionId: deferred.execution_id,\n      deferredName: deferred.deferred_name,\n      completedAtMs,\n      exitDigest: JournalEvent.contentDigest(deferred.exit_json),\n      metadataDigest: deferred.metadata_json === null ? null : JournalEvent.contentDigest(deferred.metadata_json)\n    })\n    if (consumedAtMs !== null) {\n      yield* append(EventTypes.deferredConsumed, deferred.execution_id, deferred.deferred_name, consumedAtMs, {\n        flowName: deferred.flow_name,\n        executionId: deferred.execution_id,\n        deferredName: deferred.deferred_name,\n        consumedAtMs\n      })\n    }\n  }\n})\n"]}

package/dist/esm/migrations/0010_pending_cancellation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Indexed cancellation cleanup for admissions whose handler is unavailable.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Bounds cleanup reads to requested pending rows.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export declare const pendingCancellation: Effect.Effect<void, unknown, SqlClient.SqlClient>;
+//# sourceMappingURL=0010_pending_cancellation.d.ts.map

package/dist/esm/migrations/0010_pending_cancellation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0010_pending_cancellation.d.ts","sourceRoot":"","sources":["../../../src/migrations/0010_pending_cancellation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,SAAS,CAIhF,CAAA"}

package/dist/esm/migrations/0010_pending_cancellation.js

@@ -0,0 +1,19 @@
+/**
+ * Indexed cancellation cleanup for admissions whose handler is unavailable.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Bounds cleanup reads to requested pending rows.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export const pendingCancellation = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql `CREATE INDEX flows_runs_pending_cancel_idx ON flows_runs (created_at_ms, run_id)
+    WHERE status = 'pending' AND cancel_requested_at_ms IS NOT NULL`;
+});
+//# sourceMappingURL=0010_pending_cancellation.js.map

package/dist/esm/migrations/0010_pending_cancellation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0010_pending_cancellation.js","sourceRoot":"","sources":["../../../src/migrations/0010_pending_cancellation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IACxG,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAA;IACtC,KAAK,CAAC,CAAC,GAAG,CAAA;oEACwD,CAAA;AACpE,CAAC,CAAC,CAAA","sourcesContent":["/**\n * Indexed cancellation cleanup for admissions whose handler is unavailable.\n *\n * @since 1.0.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\n\n/**\n * Bounds cleanup reads to requested pending rows.\n *\n * @category migrations\n * @since 1.0.0\n */\nexport const pendingCancellation: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {\n  const sql = yield* SqlClient.SqlClient\n  yield* sql`CREATE INDEX flows_runs_pending_cancel_idx ON flows_runs (created_at_ms, run_id)\n    WHERE status = 'pending' AND cancel_requested_at_ms IS NOT NULL`\n})\n"]}

package/dist/esm/test/TestStores.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Deterministic bundle of every durable store a flow engine composes.
+ *
+ * The stores split into `@smthrs/journal`, `@smthrs/run-store`, and
+ * `@smthrs/step-cache`, each with its own in-memory test layer. An engine
+ * needs all of them over ONE database, which is what this layer builds:
+ * the composed migration sets from `../Migrations.ts` run first, then the four
+ * services bind to the same in-memory SQLite connection.
+ *
+ * Governing design: `packages/smithers/flows/journal/docs/README.md`.
+ *
+ * @since 0.1.0
+ */
+import * as DurableWriter from "@smthrs/database/DurableWriter";
+import * as PlanStore from "@smthrs/plan-store/PlanStore";
+import * as AttemptStore from "@smthrs/run-store/AttemptStore";
+import * as RunStore from "@smthrs/run-store/RunStore";
+import * as CacheStore from "@smthrs/step-cache/CacheStore";
+import * as Layer from "effect/Layer";
+import * as DurableEngineState from "../DurableEngineState.ts";
+import * as OwnerIdentity from "../OwnerIdentity.ts";
+import * as PlanInputStore from "../PlanInputStore.ts";
+import * as PlanMergeStore from "../PlanMergeStore.ts";
+/**
+ * Options for the deterministic store bundle.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface TestStoresOptions {
+    readonly capacity?: number;
+    readonly overflow?: "reject" | "drop-newest" | "drop-oldest";
+    readonly batchSize?: number;
+}
+/**
+ * An in-memory SQLite database with the complete durable engine schema
+ * installed, exposed as `SqlClient` and `DurableWriter`.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const database: Layer.Layer<import("effect/unstable/sql/SqlClient").SqlClient | DurableWriter.DurableWriter, import("effect/unstable/sql/SqlError").SqlError | import("effect/unstable/sql/Migrator").MigrationError, never>;
+/**
+ * Provides the production SQLite journal, run, attempt, and cache services
+ * over one in-memory database. Migrations run before any durable service is
+ * exposed. The shared writer remains exposed for the engine cancellation
+ * boundary, which must inspect its complete Exit before error normalization.
+ *
+ * `OwnerIdentity.layer` rides along: it is not a store, but it is the other
+ * service `EngineStore.make` requires and has no in-memory variant to choose
+ * between. The default is used rather than a pinned one so a test observes
+ * the same fresh-per-incarnation owner the production composition mints.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options?: TestStoresOptions) => Layer.Layer<DurableWriter.DurableWriter | CacheStore.CacheStore | import("@smthrs/journal/Journal").Journal | RunStore.RunStore | AttemptStore.AttemptStore | OwnerIdentity.OwnerIdentity | PlanInputStore.PlanInputStore | PlanMergeStore.PlanMergeStore | PlanStore.PlanStore, import("effect/unstable/sql/SqlError").SqlError | import("effect/unstable/sql/Migrator").MigrationError | import("@smthrs/journal/Journal").JournalError, import("effect/Crypto").Crypto>;
+/**
+ * The same schema over a named SQLite database or PostgreSQL URL, with the connection exposed.
+ *
+ * {@link database} hides `SqlClient` behind the stores it provisions, which is
+ * right for a case that only needs an engine. Two other shapes need the
+ * connection itself: a composition that adds another SQL-backed service over
+ * the same database (a control runtime, for one), and a case that has to prove
+ * cross-process durability, which needs a persistent identity rather than the private
+ * in-memory database each `:memory:` connection gets to itself.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const databaseAt: (filename: string) => Layer.Layer<import("effect/unstable/sql/SqlClient").SqlClient | DurableWriter.DurableWriter, import("effect/unstable/sql/SqlError").SqlError | import("effect/unstable/sql/Migrator").MigrationError, never>;
+/**
+ * Every durable engine service over one named database, connection included.
+ *
+ * `layer` builds the same stores over a private in-memory database and keeps
+ * `SqlClient` to itself. This one takes the database by name and re-exports
+ * the connection, so a case can point two independently constructed bundles at
+ * one file — two connections, two engines, no shared object graph — which is
+ * what a second process actually looks like. `DurableEngineState` rides along
+ * for the same reason: its in-memory variant is a map that a second bundle
+ * would not see.
+ *
+ * Pass `:memory:` for the cheap variant when the connection is still needed.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerAt: (filename: string, options?: TestStoresOptions) => Layer.Layer<import("effect/unstable/sql/SqlClient").SqlClient | DurableWriter.DurableWriter | CacheStore.CacheStore | import("@smthrs/journal/Journal").Journal | RunStore.RunStore | DurableEngineState.DurableEngineState | AttemptStore.AttemptStore | OwnerIdentity.OwnerIdentity | PlanInputStore.PlanInputStore | PlanMergeStore.PlanMergeStore | PlanStore.PlanStore, import("effect/unstable/sql/SqlError").SqlError | import("effect/unstable/sql/Migrator").MigrationError | import("@smthrs/journal/Journal").JournalError, import("effect/Crypto").Crypto>;
+//# sourceMappingURL=TestStores.d.ts.map

package/dist/esm/test/TestStores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestStores.d.ts","sourceRoot":"","sources":["../../../src/test/TestStores.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,aAAa,MAAM,gCAAgC,CAAA;AAI/D,OAAO,KAAK,SAAS,MAAM,8BAA8B,CAAA;AACzD,OAAO,KAAK,YAAY,MAAM,gCAAgC,CAAA;AAC9D,OAAO,KAAK,QAAQ,MAAM,4BAA4B,CAAA;AACtD,OAAO,KAAK,UAAU,MAAM,+BAA+B,CAAA;AAE3D,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,kBAAkB,MAAM,0BAA0B,CAAA;AAE9D,OAAO,KAAK,aAAa,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,cAAc,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,cAAc,MAAM,sBAAsB,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,aAAa,CAAA;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,8MAA2D,CAAA;AAEhF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,GAAI,UAAU,iBAAiB,+cAckB,CAAA;AAEnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,iNAkB1C,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,GAAI,UAAU,MAAM,EAAE,UAAU,iBAAiB,2iBAce,CAAA"}

package/dist/esm/test/TestStores.js

@@ -0,0 +1,103 @@
+/**
+ * Deterministic bundle of every durable store a flow engine composes.
+ *
+ * The stores split into `@smthrs/journal`, `@smthrs/run-store`, and
+ * `@smthrs/step-cache`, each with its own in-memory test layer. An engine
+ * needs all of them over ONE database, which is what this layer builds:
+ * the composed migration sets from `../Migrations.ts` run first, then the four
+ * services bind to the same in-memory SQLite connection.
+ *
+ * Governing design: `packages/smithers/flows/journal/docs/README.md`.
+ *
+ * @since 0.1.0
+ */
+import * as DurableWriter from "@smthrs/database/DurableWriter";
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase";
+import * as TestDatabase from "@smthrs/database/test/TestDatabase";
+import * as SqlJournal from "@smthrs/journal/SqlJournal";
+import * as PlanStore from "@smthrs/plan-store/PlanStore";
+import * as AttemptStore from "@smthrs/run-store/AttemptStore";
+import * as RunStore from "@smthrs/run-store/RunStore";
+import * as CacheStore from "@smthrs/step-cache/CacheStore";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as DurableEngineState from "../DurableEngineState.js";
+import * as Migrations from "../Migrations.js";
+import * as OwnerIdentity from "../OwnerIdentity.js";
+import * as PlanInputStore from "../PlanInputStore.js";
+import * as PlanMergeStore from "../PlanMergeStore.js";
+/**
+ * An in-memory SQLite database with the complete durable engine schema
+ * installed, exposed as `SqlClient` and `DurableWriter`.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const database = Layer.provideMerge(Migrations.layer, TestDatabase.layer);
+/**
+ * Provides the production SQLite journal, run, attempt, and cache services
+ * over one in-memory database. Migrations run before any durable service is
+ * exposed. The shared writer remains exposed for the engine cancellation
+ * boundary, which must inspect its complete Exit before error normalization.
+ *
+ * `OwnerIdentity.layer` rides along: it is not a store, but it is the other
+ * service `EngineStore.make` requires and has no in-memory variant to choose
+ * between. The default is used rather than a pinned one so a test observes
+ * the same fresh-per-incarnation owner the production composition mints.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (options) => Layer.mergeAll(SqlJournal.layer({
+    capacity: options?.capacity ?? 1024,
+    overflow: options?.overflow ?? "reject",
+    batchSize: options?.batchSize
+}), RunStore.layer, AttemptStore.layer, CacheStore.layer, PlanStore.layer, PlanInputStore.layer, PlanMergeStore.layer, Layer.effect(DurableWriter.DurableWriter, DurableWriter.DurableWriter)).pipe(Layer.provide(database), Layer.merge(OwnerIdentity.layer));
+/**
+ * The same schema over a named SQLite database or PostgreSQL URL, with the connection exposed.
+ *
+ * {@link database} hides `SqlClient` behind the stores it provisions, which is
+ * right for a case that only needs an engine. Two other shapes need the
+ * connection itself: a composition that adds another SQL-backed service over
+ * the same database (a control runtime, for one), and a case that has to prove
+ * cross-process durability, which needs a persistent identity rather than the private
+ * in-memory database each `:memory:` connection gets to itself.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const databaseAt = (filename) => {
+    const url = /^postgres(?:ql)?:/.test(filename) ? new URL(filename) : undefined;
+    const schema = url?.searchParams.get("schema") ?? undefined;
+    url?.searchParams.delete("schema");
+    const database = url === undefined ?
+        NodeDatabase.layer({ filename }) :
+        Layer.unwrap(Effect.promise(() => import("@smthrs/database/postgres/PostgresDatabase")).pipe(Effect.map((PostgresDatabase) => PostgresDatabase.layer({
+            url: url.toString(),
+            schema,
+            postgres: { connectTimeout: Infinity, idleTimeout: Infinity, connectionTTL: Infinity }
+        }))));
+    return Layer.provideMerge(Migrations.layer, Layer.provideMerge(DurableWriter.layer(), database));
+};
+/**
+ * Every durable engine service over one named database, connection included.
+ *
+ * `layer` builds the same stores over a private in-memory database and keeps
+ * `SqlClient` to itself. This one takes the database by name and re-exports
+ * the connection, so a case can point two independently constructed bundles at
+ * one file — two connections, two engines, no shared object graph — which is
+ * what a second process actually looks like. `DurableEngineState` rides along
+ * for the same reason: its in-memory variant is a map that a second bundle
+ * would not see.
+ *
+ * Pass `:memory:` for the cheap variant when the connection is still needed.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerAt = (filename, options) => Layer.mergeAll(SqlJournal.layer({
+    capacity: options?.capacity ?? 1024,
+    overflow: options?.overflow ?? "reject",
+    batchSize: options?.batchSize
+}), RunStore.layer, AttemptStore.layer, CacheStore.layer, PlanStore.layer, PlanInputStore.layer, PlanMergeStore.layer, DurableEngineState.layer).pipe(Layer.provideMerge(databaseAt(filename)), Layer.merge(OwnerIdentity.layer));
+//# sourceMappingURL=TestStores.js.map

package/dist/esm/test/TestStores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestStores.js","sourceRoot":"","sources":["../../../src/test/TestStores.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Deterministic bundle of every durable store a flow engine composes.\n *\n * The stores split into `@smthrs/journal`, `@smthrs/run-store`, and\n * `@smthrs/step-cache`, each with its own in-memory test layer. An engine\n * needs all of them over ONE database, which is what this layer builds:\n * the composed migration sets from `../Migrations.ts` run first, then the four\n * services bind to the same in-memory SQLite connection.\n *\n * Governing design: `packages/smithers/flows/journal/docs/README.md`.\n *\n * @since 0.1.0\n */\n\nimport * as DurableWriter from \"@smthrs/database/DurableWriter\"\nimport * as NodeDatabase from \"@smthrs/database/node/NodeDatabase\"\nimport * as TestDatabase from \"@smthrs/database/test/TestDatabase\"\nimport * as SqlJournal from \"@smthrs/journal/SqlJournal\"\nimport * as PlanStore from \"@smthrs/plan-store/PlanStore\"\nimport * as AttemptStore from \"@smthrs/run-store/AttemptStore\"\nimport * as RunStore from \"@smthrs/run-store/RunStore\"\nimport * as CacheStore from \"@smthrs/step-cache/CacheStore\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as DurableEngineState from \"../DurableEngineState.ts\"\nimport * as Migrations from \"../Migrations.ts\"\nimport * as OwnerIdentity from \"../OwnerIdentity.ts\"\nimport * as PlanInputStore from \"../PlanInputStore.ts\"\nimport * as PlanMergeStore from \"../PlanMergeStore.ts\"\n\n/**\n * Options for the deterministic store bundle.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface TestStoresOptions {\n  readonly capacity?: number\n  readonly overflow?: \"reject\" | \"drop-newest\" | \"drop-oldest\"\n  readonly batchSize?: number\n}\n\n/**\n * An in-memory SQLite database with the complete durable engine schema\n * installed, exposed as `SqlClient` and `DurableWriter`.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const database = Layer.provideMerge(Migrations.layer, TestDatabase.layer)\n\n/**\n * Provides the production SQLite journal, run, attempt, and cache services\n * over one in-memory database. Migrations run before any durable service is\n * exposed. The shared writer remains exposed for the engine cancellation\n * boundary, which must inspect its complete Exit before error normalization.\n *\n * `OwnerIdentity.layer` rides along: it is not a store, but it is the other\n * service `EngineStore.make` requires and has no in-memory variant to choose\n * between. The default is used rather than a pinned one so a test observes\n * the same fresh-per-incarnation owner the production composition mints.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer = (options?: TestStoresOptions) =>\n  Layer.mergeAll(\n    SqlJournal.layer({\n      capacity: options?.capacity ?? 1024,\n      overflow: options?.overflow ?? \"reject\",\n      batchSize: options?.batchSize\n    }),\n    RunStore.layer,\n    AttemptStore.layer,\n    CacheStore.layer,\n    PlanStore.layer,\n    PlanInputStore.layer,\n    PlanMergeStore.layer,\n    Layer.effect(DurableWriter.DurableWriter, DurableWriter.DurableWriter)\n  ).pipe(Layer.provide(database), Layer.merge(OwnerIdentity.layer))\n\n/**\n * The same schema over a named SQLite database or PostgreSQL URL, with the connection exposed.\n *\n * {@link database} hides `SqlClient` behind the stores it provisions, which is\n * right for a case that only needs an engine. Two other shapes need the\n * connection itself: a composition that adds another SQL-backed service over\n * the same database (a control runtime, for one), and a case that has to prove\n * cross-process durability, which needs a persistent identity rather than the private\n * in-memory database each `:memory:` connection gets to itself.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const databaseAt = (filename: string) => {\n  const url = /^postgres(?:ql)?:/.test(filename) ? new URL(filename) : undefined\n  const schema = url?.searchParams.get(\"schema\") ?? undefined\n  url?.searchParams.delete(\"schema\")\n  const database = url === undefined ?\n    NodeDatabase.layer({ filename }) :\n    Layer.unwrap(\n      Effect.promise(() => import(\"@smthrs/database/postgres/PostgresDatabase\")).pipe(\n        Effect.map((PostgresDatabase) =>\n          PostgresDatabase.layer({\n            url: url.toString(),\n            schema,\n            postgres: { connectTimeout: Infinity, idleTimeout: Infinity, connectionTTL: Infinity }\n          })\n        )\n      )\n    )\n  return Layer.provideMerge(Migrations.layer, Layer.provideMerge(DurableWriter.layer(), database))\n}\n\n/**\n * Every durable engine service over one named database, connection included.\n *\n * `layer` builds the same stores over a private in-memory database and keeps\n * `SqlClient` to itself. This one takes the database by name and re-exports\n * the connection, so a case can point two independently constructed bundles at\n * one file — two connections, two engines, no shared object graph — which is\n * what a second process actually looks like. `DurableEngineState` rides along\n * for the same reason: its in-memory variant is a map that a second bundle\n * would not see.\n *\n * Pass `:memory:` for the cheap variant when the connection is still needed.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerAt = (filename: string, options?: TestStoresOptions) =>\n  Layer.mergeAll(\n    SqlJournal.layer({\n      capacity: options?.capacity ?? 1024,\n      overflow: options?.overflow ?? \"reject\",\n      batchSize: options?.batchSize\n    }),\n    RunStore.layer,\n    AttemptStore.layer,\n    CacheStore.layer,\n    PlanStore.layer,\n    PlanInputStore.layer,\n    PlanMergeStore.layer,\n    DurableEngineState.layer\n  ).pipe(Layer.provideMerge(databaseAt(filename)), Layer.merge(OwnerIdentity.layer))\n"]}

package/docs/README.md

@@ -0,0 +1,113 @@
+---
+title: "@smthrs/engine-store"
+description: "The durable engine behind Smithers flows: it persists every step attempt to SQLite or PostgreSQL, fences writes to one owner, and replays a recorded result instead of running the step again."
+---
+
+`@smthrs/engine-store` is the durable half of the Smithers flow engine. It
+persists every step a flow takes to a SQLite or PostgreSQL database, so a flow that crashes,
+is killed, or waits for a week resumes where it stopped instead of starting
+over.
+
+It is an [Effect](https://effect.website) library: every surface below is a
+`Layer` you compose or an `Effect` you run.
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+## What it solves
+
+Long work made of model calls, shell commands, and file edits fails in the
+middle. Restarting from the top is usually the wrong answer: the expensive step
+already ran, the file was already written, the irreversible effect already
+reached the world. This package makes the restart cheap and safe.
+
+- **Attempts are durable.** A step opens a row before its body runs and settles
+  that row afterwards, so a restart replays the recorded result instead of
+  executing the body a second time.
+- **One owner drives a run.** An engine claims a run, and every durable write
+  is fenced against the claiming owner, so two processes over one database
+  cannot both drive it. A dead owner's runs are reclaimed under a liveness
+  check you choose.
+- **Waits outlive the process.** A parked run holds a durable deferred or clock
+  row, so a timer that outlives the process that set it still fires.
+- **Steps declare the files they touch.** The engine measures the real tree
+  against the declaration, refuses a step that wrote outside it, and admits
+  only whole-tree evidence into the cache that other runs read.
+- **Deletion is a pass you run.** Old run history and unreferenced artifacts go
+  away when you ask for it, never on a schedule you did not set.
+
+## Replay in one example
+
+Build the engine layer with an owner identity and a journal source:
+
+```ts
+import { EngineStore } from "@smthrs/engine-store"
+import { Ownership } from "@smthrs/run-store"
+
+const engine = EngineStore.layer({
+  owner: { hostId: "worker-a" },
+  journalSource: "worker-a",
+  isAlive: Ownership.sameHostPidProbe
+})
+```
+
+Provide that layer the journal, run, attempt, and cache stores over one
+migrated SQLite file and you have `workerA`. Build a second engine, `workerB`,
+over that same file, the way a second process would. `Analyse` is a flow with
+one sealed step. Execute it twice under the same execution id:
+
+```ts
+import * as Effect from "effect/Effect"
+
+const first = await Effect.runPromise(
+  Effect.scoped(Analyse.execute({}, { executionId: "analyse-1" }).pipe(Effect.provide(workerA)))
+)
+
+const second = await Effect.runPromise(
+  Effect.scoped(Analyse.execute({}, { executionId: "analyse-1" }).pipe(Effect.provide(workerB)))
+)
+```
+
+```text
+first: '42'   second: '42'   step bodies executed: 1
+```
+
+The second engine found the settled attempt row for that step key and replayed
+it, so the body ran once. Delete the database file and the count becomes 2,
+which is the falsifiable version of the claim. The
+[Quickstart](./quickstart.md) builds both engines end to end, in one file you
+can run.
+
+## Where this sits
+
+This package is one piece of the Smithers flow engine, not the whole of it.
+[`@smthrs/flows`](/api/flows) is the barrel over that engine: it re-exports
+this package next to the flow language, the journal, the run and cache stores,
+and the artifact tier, and it ships `NodeRuntime`, which wires all of them over
+one SQLite file so a program does not restate the composition by hand. Install
+`@smthrs/flows` when you want a runtime that already works. Reach for
+`@smthrs/engine-store` directly when you are building the host itself and need
+control over ownership, step boundaries, workspace sandboxing, retention, or a
+cache shared across machines.
+
+Above both sits the [`smithers` command-line interface](/api/cli), which runs
+flows out of a project directory without writing a composition at all.
+
+## Next steps
+
+- [Installation](./installation.md): runtime requirements, import forms, the
+  storage packages a runnable composition adds, and the browser boundary.
+- [Quickstart](./quickstart.md): compose an engine over one SQLite file and
+  watch a sealed step replay.
+- [Compose a durable engine](./guides/compose-a-durable-engine.md): every
+  service `EngineStore.layer` requires, and what each option changes.
+- [Ownership and fencing](./concepts/ownership-and-fencing.md): how a run is
+  claimed, fenced, and reclaimed.
+- [Attempts and replay](./concepts/attempts-and-replay.md): what is persisted
+  per attempt, and which admission checks refuse one.
+- [Share a step cache across machines](./guides/share-a-cache-across-machines.md):
+  turn one machine's sealed result into every machine's.
+- [Back up and restore the store](./guides/back-up-and-restore.md): hot backup,
+  verification, and the ownership fence a restored file needs.
+- [API reference](./api.md): every public export, grouped by namespace.
+- [Troubleshooting](./troubleshooting.md): the typed failures this package
+  reports, and what to change for each.