@smthrs/journal 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/migrations/0006_consensus.js

@@ -0,0 +1,69 @@
+/**
+ * The `SqlConsensus` lease table.
+ *
+ * This is the private schema of the default consensus strategy: the owner
+ * tuple, the two-phase claim columns, and the grant timestamp relocated from
+ * `flows_runs`. Lease rows are strategy evidence, never history: heartbeats
+ * and lease state never enter the journal.
+ *
+ * @since 1.0.0
+ */
+import * as Dialect from "@smthrs/database/Dialect";
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Creates the `flows_consensus_leases` table and backfills a lease for every
+ * running or claimed run when `flows_runs` is already present, so an owner
+ * that was driving a run before this migration keeps its fence afterwards.
+ *
+ * @category migrations
+ * @since 1.0.0
+ */
+export const consensus = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql `CREATE TABLE flows_consensus_leases (
+    run_id TEXT PRIMARY KEY CHECK (length(run_id) > 0),
+    owner_host_id TEXT,
+    owner_pid ${Dialect.integer(sql)} CHECK (owner_pid IS NULL OR (${Dialect.isInteger(sql, sql `owner_pid`)} AND owner_pid >= 0)),
+    owner_nonce TEXT,
+    granted_at_ms ${Dialect.integer(sql)} CHECK (granted_at_ms IS NULL OR (${Dialect.isInteger(sql, sql `granted_at_ms`)} AND granted_at_ms >= 0)),
+    heartbeat_at_ms ${Dialect.integer(sql)} CHECK (heartbeat_at_ms IS NULL OR (${Dialect.isInteger(sql, sql `heartbeat_at_ms`)} AND heartbeat_at_ms >= 0)),
+    claim_host_id TEXT,
+    claim_pid ${Dialect.integer(sql)} CHECK (claim_pid IS NULL OR (${Dialect.isInteger(sql, sql `claim_pid`)} AND claim_pid >= 0)),
+    claim_nonce TEXT,
+    claimed_at_ms ${Dialect.integer(sql)} CHECK (claimed_at_ms IS NULL OR (${Dialect.isInteger(sql, sql `claimed_at_ms`)} AND claimed_at_ms >= 0))
+  )`;
+    const tables = yield* Dialect.tables(sql);
+    if (!tables.some((table) => table.name === "flows_runs")) {
+        return;
+    }
+    yield* sql `
+    INSERT INTO flows_consensus_leases (
+      run_id,
+      owner_host_id,
+      owner_pid,
+      owner_nonce,
+      granted_at_ms,
+      heartbeat_at_ms,
+      claim_host_id,
+      claim_pid,
+      claim_nonce,
+      claimed_at_ms
+    )
+    SELECT
+      run_id,
+      owner_host_id,
+      owner_pid,
+      owner_nonce,
+      CASE WHEN status = 'running' THEN heartbeat_at_ms ELSE NULL END,
+      CASE WHEN status = 'running' THEN heartbeat_at_ms ELSE NULL END,
+      claim_host_id,
+      claim_pid,
+      claim_nonce,
+      claimed_at_ms
+    FROM flows_runs
+    WHERE status = 'running' OR claim_host_id IS NOT NULL
+    ON CONFLICT (run_id) DO NOTHING
+  `;
+});
+//# sourceMappingURL=0006_consensus.js.map

package/dist/esm/migrations/0006_consensus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0006_consensus.js","sourceRoot":"","sources":["../../../src/migrations/0006_consensus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,OAAO,MAAM,0BAA0B,CAAA;AACnD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAE1D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAsD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC9F,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAA;IAEtC,KAAK,CAAC,CAAC,GAAG,CAAA;;;gBAGI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,iCAChC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,WAAW,CACvC;;oBAEkB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,qCACpC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,eAAe,CAC3C;sBACoB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,uCACtC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,iBAAiB,CAC7C;;gBAEc,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,iCAChC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,WAAW,CACvC;;oBAEkB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,qCACpC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAA,eAAe,CAC3C;IACE,CAAA;IAEF,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACzC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;QACzD,OAAM;IACR,CAAC;IAED,KAAK,CAAC,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BT,CAAA;AACH,CAAC,CAAC,CAAA","sourcesContent":["/**\n * The `SqlConsensus` lease table.\n *\n * This is the private schema of the default consensus strategy: the owner\n * tuple, the two-phase claim columns, and the grant timestamp relocated from\n * `flows_runs`. Lease rows are strategy evidence, never history: heartbeats\n * and lease state never enter the journal.\n *\n * @since 1.0.0\n */\n\nimport * as Dialect from \"@smthrs/database/Dialect\"\nimport * as Effect from \"effect/Effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\n\n/**\n * Creates the `flows_consensus_leases` table and backfills a lease for every\n * running or claimed run when `flows_runs` is already present, so an owner\n * that was driving a run before this migration keeps its fence afterwards.\n *\n * @category migrations\n * @since 1.0.0\n */\nexport const consensus: Effect.Effect<void, unknown, SqlClient.SqlClient> = Effect.gen(function*() {\n  const sql = yield* SqlClient.SqlClient\n\n  yield* sql`CREATE TABLE flows_consensus_leases (\n    run_id TEXT PRIMARY KEY CHECK (length(run_id) > 0),\n    owner_host_id TEXT,\n    owner_pid ${Dialect.integer(sql)} CHECK (owner_pid IS NULL OR (${\n    Dialect.isInteger(sql, sql`owner_pid`)\n  } AND owner_pid >= 0)),\n    owner_nonce TEXT,\n    granted_at_ms ${Dialect.integer(sql)} CHECK (granted_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`granted_at_ms`)\n  } AND granted_at_ms >= 0)),\n    heartbeat_at_ms ${Dialect.integer(sql)} CHECK (heartbeat_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`heartbeat_at_ms`)\n  } AND heartbeat_at_ms >= 0)),\n    claim_host_id TEXT,\n    claim_pid ${Dialect.integer(sql)} CHECK (claim_pid IS NULL OR (${\n    Dialect.isInteger(sql, sql`claim_pid`)\n  } AND claim_pid >= 0)),\n    claim_nonce TEXT,\n    claimed_at_ms ${Dialect.integer(sql)} CHECK (claimed_at_ms IS NULL OR (${\n    Dialect.isInteger(sql, sql`claimed_at_ms`)\n  } AND claimed_at_ms >= 0))\n  )`\n\n  const tables = yield* Dialect.tables(sql)\n  if (!tables.some((table) => table.name === \"flows_runs\")) {\n    return\n  }\n\n  yield* sql`\n    INSERT INTO flows_consensus_leases (\n      run_id,\n      owner_host_id,\n      owner_pid,\n      owner_nonce,\n      granted_at_ms,\n      heartbeat_at_ms,\n      claim_host_id,\n      claim_pid,\n      claim_nonce,\n      claimed_at_ms\n    )\n    SELECT\n      run_id,\n      owner_host_id,\n      owner_pid,\n      owner_nonce,\n      CASE WHEN status = 'running' THEN heartbeat_at_ms ELSE NULL END,\n      CASE WHEN status = 'running' THEN heartbeat_at_ms ELSE NULL END,\n      claim_host_id,\n      claim_pid,\n      claim_nonce,\n      claimed_at_ms\n    FROM flows_runs\n    WHERE status = 'running' OR claim_host_id IS NOT NULL\n    ON CONFLICT (run_id) DO NOTHING\n  `\n})\n"]}

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

@@ -0,0 +1,65 @@
+/**
+ * Effect-native analogue of Bazel Skyframe's `NotifyingHelper` and
+ * `NotifyingInMemoryGraph`: wrap a record-of-Effect-methods service so a listener hook fires around
+ * every operation. The hook runs in the calling fiber, so a hook that dies,
+ * interrupts, or awaits a `Latch` injects crashes, fence loss, and exact
+ * sequencing at any durable transition point, the mechanism that makes
+ * interstitial interleaving bugs testable at all.
+ *
+ * Deliberately NOT ported from Skyframe: `DeterministicHelper`'s
+ * deterministic-scheduler machinery, `ChainedFunction`, and `TrackingAwaiter`.
+ * Effect already gives us deterministic fibers, `TestClock`, `Latch`, and
+ * failure propagation across fiber joins, so those helpers have no residue
+ * here.
+ *
+ * @since 0.1.0
+ */
+import type * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+/**
+ * Whether the hook is firing before or after the delegated operation.
+ * Skyframe's `NotifyingHelper.Order`, minus its `BEFORE_AND_AFTER` (pass the
+ * same hook body for both firings instead).
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Order = "before" | "after";
+/**
+ * Listener invoked around every delegated operation. `op` is the service
+ * method name (Skyframe's `EventType`, but open-world), `args` the call
+ * arguments. Express crash injection as `Effect.die` or `Effect.interrupt`
+ * inside the hook, the hook's type stays `Effect<void>` so the wrapped
+ * service is structurally identical to the real one.
+ *
+ * The `after` firing only happens when the operation succeeds; a failed
+ * operation already is the interesting event.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Hook = (op: string, order: Order, args: ReadonlyArray<unknown>) => Effect.Effect<void>;
+/**
+ * Wraps a service so `hook(op, "before" | "after", args)` fires around every
+ * Effect-valued operation, delegating to the real implementation in between.
+ *
+ * Generic over any record-of-Effect-methods service (`Journal`, `CacheStore`,
+ * `AttemptStore`, `RunStore`, ...): Effect-returning methods and plain Effect
+ * properties are hooked; non-Effect members (e.g. `Stream`-returning methods)
+ * delegate untouched.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const wrap: <S extends object>(service: S, hook: Hook) => S;
+/**
+ * Layer form of {@link wrap}: reads the real service from the environment and
+ * re-provides the notifying wrapper under the same key, so an existing stack
+ * gains a listener without touching its construction.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: <Id, S extends object>(tag: Context.Key<Id, S>, hook: Hook) => Layer.Layer<Id, never, Id>;
+//# sourceMappingURL=Notifying.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Notifying.d.ts","sourceRoot":"","sources":["../../../src/test/Notifying.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,IAAI,GAAG,CACjB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,KACzB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;AAExB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,IAAI,KAAG,CAyB/D,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAAI,EAAE,EAAE,CAAC,SAAS,MAAM,EACxC,KAAK,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EACvB,MAAM,IAAI,KACT,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAyE,CAAA"}

package/dist/esm/test/Notifying.js

@@ -0,0 +1,62 @@
+/**
+ * Effect-native analogue of Bazel Skyframe's `NotifyingHelper` and
+ * `NotifyingInMemoryGraph`: wrap a record-of-Effect-methods service so a listener hook fires around
+ * every operation. The hook runs in the calling fiber, so a hook that dies,
+ * interrupts, or awaits a `Latch` injects crashes, fence loss, and exact
+ * sequencing at any durable transition point, the mechanism that makes
+ * interstitial interleaving bugs testable at all.
+ *
+ * Deliberately NOT ported from Skyframe: `DeterministicHelper`'s
+ * deterministic-scheduler machinery, `ChainedFunction`, and `TrackingAwaiter`.
+ * Effect already gives us deterministic fibers, `TestClock`, `Latch`, and
+ * failure propagation across fiber joins, so those helpers have no residue
+ * here.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+/**
+ * Wraps a service so `hook(op, "before" | "after", args)` fires around every
+ * Effect-valued operation, delegating to the real implementation in between.
+ *
+ * Generic over any record-of-Effect-methods service (`Journal`, `CacheStore`,
+ * `AttemptStore`, `RunStore`, ...): Effect-returning methods and plain Effect
+ * properties are hooked; non-Effect members (e.g. `Stream`-returning methods)
+ * delegate untouched.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const wrap = (service, hook) => {
+    const wrapped = {};
+    for (const key of Object.keys(service)) {
+        const value = service[key];
+        if (Effect.isEffect(value)) {
+            wrapped[key] = hook(key, "before", []).pipe(Effect.andThen(value), Effect.tap(() => hook(key, "after", [])));
+        }
+        else if (typeof value === "function") {
+            const method = value;
+            wrapped[key] = (...args) => {
+                const result = method.apply(service, args);
+                return Effect.isEffect(result)
+                    ? hook(key, "before", args).pipe(Effect.andThen(result), Effect.tap(() => hook(key, "after", args)))
+                    : result;
+            };
+        }
+        else {
+            wrapped[key] = value;
+        }
+    }
+    return wrapped;
+};
+/**
+ * Layer form of {@link wrap}: reads the real service from the environment and
+ * re-provides the notifying wrapper under the same key, so an existing stack
+ * gains a listener without touching its construction.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (tag, hook) => Layer.effect(tag)(Effect.map(tag, (service) => wrap(service, hook)));
+//# sourceMappingURL=Notifying.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Notifying.js","sourceRoot":"","sources":["../../../src/test/Notifying.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AA+BrC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAmB,OAAU,EAAE,IAAU,EAAK,EAAE;IAClE,MAAM,OAAO,GAA4B,EAAE,CAAA;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,KAAK,GAAI,OAAmC,CAAC,GAAG,CAAC,CAAA;QACvD,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,CACzC,MAAM,CAAC,OAAO,CAAC,KAAiD,CAAC,EACjE,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,CACzC,CAAA;QACH,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,KAA6C,CAAA;YAC5D,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAoB,EAAE,EAAE;gBACzC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;gBAC1C,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;oBAC5B,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,IAAI,CAC9B,MAAM,CAAC,OAAO,CAAC,MAAkD,CAAC,EAClE,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAC3C;oBACD,CAAC,CAAC,MAAM,CAAA;YACZ,CAAC,CAAA;QACH,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QACtB,CAAC;IACH,CAAC;IACD,OAAO,OAAY,CAAA;AACrB,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,GAAuB,EACvB,IAAU,EACkB,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA","sourcesContent":["/**\n * Effect-native analogue of Bazel Skyframe's `NotifyingHelper` and\n * `NotifyingInMemoryGraph`: wrap a record-of-Effect-methods service so a listener hook fires around\n * every operation. The hook runs in the calling fiber, so a hook that dies,\n * interrupts, or awaits a `Latch` injects crashes, fence loss, and exact\n * sequencing at any durable transition point, the mechanism that makes\n * interstitial interleaving bugs testable at all.\n *\n * Deliberately NOT ported from Skyframe: `DeterministicHelper`'s\n * deterministic-scheduler machinery, `ChainedFunction`, and `TrackingAwaiter`.\n * Effect already gives us deterministic fibers, `TestClock`, `Latch`, and\n * failure propagation across fiber joins, so those helpers have no residue\n * here.\n *\n * @since 0.1.0\n */\n\nimport type * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\n\n/**\n * Whether the hook is firing before or after the delegated operation.\n * Skyframe's `NotifyingHelper.Order`, minus its `BEFORE_AND_AFTER` (pass the\n * same hook body for both firings instead).\n *\n * @category models\n * @since 0.1.0\n */\nexport type Order = \"before\" | \"after\"\n\n/**\n * Listener invoked around every delegated operation. `op` is the service\n * method name (Skyframe's `EventType`, but open-world), `args` the call\n * arguments. Express crash injection as `Effect.die` or `Effect.interrupt`\n * inside the hook, the hook's type stays `Effect<void>` so the wrapped\n * service is structurally identical to the real one.\n *\n * The `after` firing only happens when the operation succeeds; a failed\n * operation already is the interesting event.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Hook = (\n  op: string,\n  order: Order,\n  args: ReadonlyArray<unknown>\n) => Effect.Effect<void>\n\n/**\n * Wraps a service so `hook(op, \"before\" | \"after\", args)` fires around every\n * Effect-valued operation, delegating to the real implementation in between.\n *\n * Generic over any record-of-Effect-methods service (`Journal`, `CacheStore`,\n * `AttemptStore`, `RunStore`, ...): Effect-returning methods and plain Effect\n * properties are hooked; non-Effect members (e.g. `Stream`-returning methods)\n * delegate untouched.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const wrap = <S extends object>(service: S, hook: Hook): S => {\n  const wrapped: Record<string, unknown> = {}\n  for (const key of Object.keys(service)) {\n    const value = (service as Record<string, unknown>)[key]\n    if (Effect.isEffect(value)) {\n      wrapped[key] = hook(key, \"before\", []).pipe(\n        Effect.andThen(value as Effect.Effect<unknown, unknown, unknown>),\n        Effect.tap(() => hook(key, \"after\", []))\n      )\n    } else if (typeof value === \"function\") {\n      const method = value as (...args: Array<unknown>) => unknown\n      wrapped[key] = (...args: Array<unknown>) => {\n        const result = method.apply(service, args)\n        return Effect.isEffect(result)\n          ? hook(key, \"before\", args).pipe(\n            Effect.andThen(result as Effect.Effect<unknown, unknown, unknown>),\n            Effect.tap(() => hook(key, \"after\", args))\n          )\n          : result\n      }\n    } else {\n      wrapped[key] = value\n    }\n  }\n  return wrapped as S\n}\n\n/**\n * Layer form of {@link wrap}: reads the real service from the environment and\n * re-provides the notifying wrapper under the same key, so an existing stack\n * gains a listener without touching its construction.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer = <Id, S extends object>(\n  tag: Context.Key<Id, S>,\n  hook: Hook\n): Layer.Layer<Id, never, Id> => Layer.effect(tag)(Effect.map(tag, (service) => wrap(service, hook)))\n"]}

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

@@ -0,0 +1,43 @@
+/**
+ * Deterministic bundle of the production journal service.
+ *
+ * This provides the journal and nothing else. A consumer that also needs run
+ * state or the step cache composes `@smthrs/run-store/test/TestRunStore` and
+ * `@smthrs/step-cache/test/TestCacheStore` over the same database, or takes
+ * the whole engine bundle from `@smthrs/engine-store/test/TestStores`.
+ *
+ * @since 0.1.0
+ */
+import * as Layer from "effect/Layer";
+import * as SqlJournal from "../SqlJournal.ts";
+/**
+ * Options for the deterministic journal bundle.
+ *
+ * The production options with `capacity` and `overflow` made optional. Every
+ * field forwards to {@link SqlJournal.layer} unchanged, so a suite can exercise
+ * index-bound eviction, the entry byte bound, a custom or noop redactor, and
+ * the compaction policy through the bundle instead of hand-assembling the layer
+ * stack the bundle exists to hide.
+ *
+ * The type is derived rather than mirrored because a mirror silently falls
+ * behind: the hand-copied list had already lost `maxEntryBytes`, so the one
+ * production bound a hostile-payload suite needs was unreachable here.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface TestJournalOptions extends Omit<SqlJournal.SqlJournalOptions, "capacity" | "overflow"> {
+    /** Admission-queue bound and `changes` buffer size. Defaults to 1024. */
+    readonly capacity?: number | undefined;
+    /** Policy applied when the admission queue is full. Defaults to `reject`. */
+    readonly overflow?: SqlJournal.SqlJournalOptions["overflow"] | undefined;
+}
+/**
+ * Provides the production SQLite journal over an in-memory database.
+ * Migrations run before the journal is exposed.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options?: TestJournalOptions) => Layer.Layer<import("../Journal.ts").Journal, import("effect/unstable/sql/SqlError").SqlError | import("../Journal.ts").JournalError | import("effect/unstable/sql/Migrator").MigrationError, never>;
+//# sourceMappingURL=TestJournal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TestJournal.d.ts","sourceRoot":"","sources":["../../../src/test/TestJournal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,UAAU,CAAC,iBAAiB,EAAE,UAAU,GAAG,UAAU,CAAC;IACrG,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,UAAU,CAAC,GAAG,SAAS,CAAA;CACzE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,UAAU,kBAAkB,wMAKgC,CAAA"}

package/dist/esm/test/TestJournal.js

@@ -0,0 +1,27 @@
+/**
+ * Deterministic bundle of the production journal service.
+ *
+ * This provides the journal and nothing else. A consumer that also needs run
+ * state or the step cache composes `@smthrs/run-store/test/TestRunStore` and
+ * `@smthrs/step-cache/test/TestCacheStore` over the same database, or takes
+ * the whole engine bundle from `@smthrs/engine-store/test/TestStores`.
+ *
+ * @since 0.1.0
+ */
+import * as TestDatabase from "@smthrs/database/test/TestDatabase";
+import * as Layer from "effect/Layer";
+import * as Migrations from "../Migrations.js";
+import * as SqlJournal from "../SqlJournal.js";
+/**
+ * Provides the production SQLite journal over an in-memory database.
+ * Migrations run before the journal is exposed.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (options) => SqlJournal.layer({
+    ...options,
+    capacity: options?.capacity ?? 1024,
+    overflow: options?.overflow ?? "reject"
+}).pipe(Layer.provide(Layer.provideMerge(Migrations.layer, TestDatabase.layer)));
+//# sourceMappingURL=TestJournal.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TestJournal.js","sourceRoot":"","sources":["../../../src/test/TestJournal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,YAAY,MAAM,oCAAoC,CAAA;AAClE,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAA;AAyB9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,OAA4B,EAAE,EAAE,CACpD,UAAU,CAAC,KAAK,CAAC;IACf,GAAG,OAAO;IACV,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,IAAI;IACnC,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,QAAQ;CACxC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA","sourcesContent":["/**\n * Deterministic bundle of the production journal service.\n *\n * This provides the journal and nothing else. A consumer that also needs run\n * state or the step cache composes `@smthrs/run-store/test/TestRunStore` and\n * `@smthrs/step-cache/test/TestCacheStore` over the same database, or takes\n * the whole engine bundle from `@smthrs/engine-store/test/TestStores`.\n *\n * @since 0.1.0\n */\n\nimport * as TestDatabase from \"@smthrs/database/test/TestDatabase\"\nimport * as Layer from \"effect/Layer\"\nimport * as Migrations from \"../Migrations.ts\"\nimport * as SqlJournal from \"../SqlJournal.ts\"\n\n/**\n * Options for the deterministic journal bundle.\n *\n * The production options with `capacity` and `overflow` made optional. Every\n * field forwards to {@link SqlJournal.layer} unchanged, so a suite can exercise\n * index-bound eviction, the entry byte bound, a custom or noop redactor, and\n * the compaction policy through the bundle instead of hand-assembling the layer\n * stack the bundle exists to hide.\n *\n * The type is derived rather than mirrored because a mirror silently falls\n * behind: the hand-copied list had already lost `maxEntryBytes`, so the one\n * production bound a hostile-payload suite needs was unreachable here.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface TestJournalOptions extends Omit<SqlJournal.SqlJournalOptions, \"capacity\" | \"overflow\"> {\n  /** Admission-queue bound and `changes` buffer size. Defaults to 1024. */\n  readonly capacity?: number | undefined\n  /** Policy applied when the admission queue is full. Defaults to `reject`. */\n  readonly overflow?: SqlJournal.SqlJournalOptions[\"overflow\"] | undefined\n}\n\n/**\n * Provides the production SQLite journal over an in-memory database.\n * Migrations run before the journal is exposed.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer = (options?: TestJournalOptions) =>\n  SqlJournal.layer({\n    ...options,\n    capacity: options?.capacity ?? 1024,\n    overflow: options?.overflow ?? \"reject\"\n  }).pipe(Layer.provide(Layer.provideMerge(Migrations.layer, TestDatabase.layer)))\n"]}

package/docs/README.md

@@ -0,0 +1,164 @@
+---
+title: "@smthrs/journal"
+description: "An append-only event history for Effect applications: a lossless lifecycle channel beside a lossy telemetry channel, credentials scrubbed before anything is persisted, and an owner fence that refuses a write from a process that lost the run."
+---
+
+`@smthrs/journal` records what a long-running piece of work did, in order, in
+SQLite. Rows are appended and never updated, so the history reads the same on
+the tenth pass as on the first, and a process that dies halfway through leaves
+behind everything it had already committed.
+
+It is a set of [Effect](https://effect.website) services: every write returns a
+typed receipt or a typed failure, and the database arrives as a layer you
+compose. It belongs to the Smithers durable flow engine, but it runs on its
+own: no other Smithers package is required.
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+`effect` is a peer dependency at exactly `4.0.0-rc.115`. Two copies of `effect`
+in one program are two sets of service tags, so a journal layer built against
+one copy cannot be provided to a program holding the other.
+
+## What it solves
+
+Application logs are the usual answer to "what happened here", and they stop
+being an answer the moment another program has to read them. A journal entry is
+a typed record with a sequence number, so a supervisor, a resumed run, or a UI
+can replay the history instead of parsing it.
+
+- **Two channels, one order.** A lifecycle event ("the run finished") is on
+  disk before its call returns. A telemetry event ("40 percent compiled") goes
+  through a bounded queue that drops under pressure rather than stalling the
+  writer. Both land in one per-run sequence, so the cheap channel cannot
+  reorder the expensive one.
+- **Every write gets an answer.** An emission returns `Accepted`, `Duplicate`,
+  or `Dropped`, and every failure carries one of fourteen stable codes. A
+  caller never has to guess whether an entry survived.
+- **A retry is not a second event.** Producer identity is
+  `(runId, sourceId, sourceSeq)`, unique in the database, so a producer that
+  replays after a crash gets `Duplicate` back rather than doubling its history.
+- **Credentials never reach the file.** Payloads are scrubbed on the write
+  path, before encoding, because a row is permanent and gets replayed verbatim
+  to every later reader.
+- **A stale process cannot append.** The durable channel takes an owner token
+  and commits only while the database still records that owner as the run's
+  owner. A process that was replaced fails with `fence_lost` instead of writing
+  into a history it no longer owns.
+- **State and its entry commit together.** `transact` puts your own writes and
+  the entry that describes them in one transaction, so the two can never
+  disagree about what happened.
+- **A long run stops growing.** A checkpoint pins replay state to a sequence,
+  and compaction deletes the entries below it.
+
+## One run, both channels
+
+This program writes a lifecycle event and a telemetry event to the same run,
+then reads the run back. It needs Node.js 26.4.0 or later, where the built-in
+SQLite module lives, and it writes a real `history.db` in the working
+directory:
+
+```ts
+import * as DurableWriter from "@smthrs/database/DurableWriter"
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase"
+import { Journal, JournalEvent, Migrations, SqlJournal } from "@smthrs/journal"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+const database = Layer.provideMerge(
+  DurableWriter.layer(),
+  NodeDatabase.layer({ filename: "history.db" })
+)
+
+const journalLayer = SqlJournal.layer({ capacity: 1024, overflow: "reject" }).pipe(
+  Layer.provide(Layer.provideMerge(Migrations.layer, database))
+)
+
+const runId = "run-1" as JournalEvent.RunId
+const sourceId = "engine" as JournalEvent.SourceId
+
+const program = Effect.gen(function*() {
+  const journal = yield* Journal.Journal
+
+  const created = yield* journal.emitDurableUnfenced({
+    runId,
+    sourceId,
+    eventType: "run.created",
+    payload: { flow: "build", token: "ghp_0123456789abcdefghijklmnopqrstuvwxyz" }
+  })
+  console.log("durable:", created._tag, "seq", created.seq)
+
+  yield* journal.emitLossy({
+    runId,
+    sourceId,
+    eventType: "step.progress",
+    payload: { step: "compile", percent: 40 }
+  })
+  yield* journal.flush
+
+  const page = yield* journal.entries({ runId, limit: 100 })
+  for (const entry of page.entries) {
+    console.log(entry.seq, entry.eventType, JSON.stringify(entry.payload))
+  }
+})
+
+await Effect.runPromise(program.pipe(Effect.provide(journalLayer), Effect.orDie))
+```
+
+```text
+durable: Accepted seq 0
+0 run.created {"flow":"build","token":"[REDACTED]"}
+1 step.progress {"percent":40,"step":"compile"}
+```
+
+The token came back as `[REDACTED]` because it was scrubbed before the row was
+encoded, so the credential is not in `history.db` and never was. The two
+entries share one `seq` line because both channels write one history. The
+`flush` is the barrier for the lossy channel only: the durable entry was
+already committed when its receipt arrived.
+
+## Where this sits
+
+The journal owns exactly the history and nothing else.
+[`@smthrs/flows`](/api/flows) is the engine's barrel: it re-exports this
+package as a namespace next to the flow language, the stores, and the runtime
+that wires them over one SQLite file, so
+`import { Journal } from "@smthrs/flows"` reaches the same code as
+`import * as Journal from "@smthrs/journal"`. Depend on the barrel when you
+want a working engine, and on this package when the event history is the part
+you need: an audit trail, a live feed for a UI, or the replay log of a system
+you are building yourself.
+
+The neighboring stores hold what the journal deliberately does not.
+Run and attempt state live in [`@smthrs/run-store`](/api/run-store), sealed
+step results in [`@smthrs/step-cache`](/api/step-cache), and the durable
+deferred and clock tables in [`@smthrs/engine-store`](/api/engine-store), which
+composes all of them. Underneath every one of them,
+[`@smthrs/database`](/api/database) is the single write boundary they share,
+which is what makes `transact` possible.
+
+Above the whole engine sits the
+[`smithers` command-line interface](/api/cli), which runs flows out of a
+project directory without your composing any of this by hand.
+
+One name collides. [`@smthrs/chain`](/api/chain) also has a journal: an
+in-process event array that is a single chain's only state. It is a different
+object with a different contract, described in
+[the chain journal](/pkg/chain/concepts/journal).
+
+## Next steps
+
+- [Installation](./installation.md): the database layer, the migration sets a
+  journal needs, and which extra table the fenced write path reads.
+- [Quickstart](./quickstart.md): the program above built one step at a time,
+  with what each line of output proves.
+- [The two channels](./concepts/two-channels.md): which write to reach for,
+  what each receipt means, and why sequence gaps are valid.
+- [The owner fence](./concepts/owner-fence.md): why the durable channel takes
+  an owner, and when the unfenced one is correct.
+- [Read and follow a run](./guides/read-a-run.md): paging, the lossless
+  follower, and the buffer that drops for a slow subscriber.
+- [Test against a real journal](./guides/testing.md): the production layer over
+  an in-memory database, and injecting a crash at an exact transition.
+- [API reference](./api.md): every public export, grouped by namespace.
+- [Troubleshooting](./troubleshooting.md): every error code, what causes it,
+  and what to change.