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

package/dist/cjs/CacheSync.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The shared step-result tier's publication seam: the remote half of a cache
+ * `put`, run *after* the transaction that made the local row durable.
+ *
+ * `ArtifactSync` is the same idea for the artifact tier, and the two together
+ * are the REAPI ordering constraint
+ * (`reference/bazel/.../remote/UploadManifest.java:630-633`): blobs first, the
+ * entry that references them last.
+ *
+ * This tag exists because of *where* the local row is written.
+ * `ActionPersistence` commits the cache row and the journal record that
+ * explains it in one `DurableWriter` transaction, and nothing that is not
+ * storage work may be held across one — the action body, the Jj snapshot, and
+ * the boundary prepare/settle all already stay outside. A `CacheStore` whose
+ * `put` also writes a shared HTTP tier would put a network round trip inside
+ * that transaction, blocking every other writer for its duration and rolling
+ * the local row back when a *shared cache* is unreachable. So the local put
+ * stays inside and the shared put becomes this service, invoked once the
+ * transaction has committed. Compose it with
+ * `CombinedCacheStore` in `"deferred"` publication mode, which is the mode that
+ * leaves the shared write to this seam.
+ *
+ * Publication is **best-effort by construction**. A shared cache is an
+ * accelerator, and the work it would have shared is already durably recorded on
+ * this host: failing a completed run because an optional tier is unreachable
+ * trades a real result for an unavailable one. A refused publication is
+ * journaled by the caller instead, which is the same treatment an unverified
+ * read set gets — visible, not silent.
+ *
+ * Governing design: `packages/smithers/flows/step-cache/docs/api.md`.
+ *
+ * @since 0.1.0
+ */
+import type { CacheStore } from "@smthrs/step-cache";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+/**
+ * The one operation the shared-cache publication seam exposes.
+ *
+ * It is a single method rather than a store interface on purpose: everything
+ * about reading, keying, and invalidating a cache entry belongs to
+ * `CacheStore`, and all this seam does is take an already-durable local entry
+ * and try to share it.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export interface Service {
+    /**
+     * Publishes a cache entry to the shared tier, reporting the refusal rather
+     * than failing: `Option.none()` means the entry is now shared, and
+     * `Option.some(error)` means it is not and why.
+     *
+     * Callers must only reach here once every artifact the entry references is
+     * durable in the shared artifact tier — that is `ArtifactSync.publish`'s job,
+     * and it runs first.
+     */
+    readonly publishEntry: (entry: CacheStore.CacheEntry) => Effect.Effect<Option.Option<CacheStore.CacheStoreError>>;
+}
+declare const CacheSync_base: Context.ServiceClass<CacheSync, "@smthrs/engine-store/CacheSync", Service>;
+/**
+ * Service tag for the shared step-result publication seam.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export declare class CacheSync extends CacheSync_base {
+}
+/**
+ * The single-tier implementation: there is no shared step-result tier, so a
+ * recorded entry is already everywhere it will ever be.
+ *
+ * This is the default `ActionPersistence` falls back to when the tag is
+ * absent, which is what keeps a purely local composition free of any
+ * remote-cache machinery.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const makeLocal: () => Service;
+/**
+ * Provides the single-tier (no shared step-result store) publication seam.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layerLocal: Layer.Layer<CacheSync>;
+/**
+ * Builds the publication seam over a shared step-result store — typically
+ * `RemoteCacheStore`.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const make: (options: {
+    readonly remote: CacheStore.Service;
+}) => Service;
+/**
+ * Provides the publication seam over the supplied shared store.
+ *
+ * The shared store arrives as an *effect* rather than a layer because it
+ * inhabits the same `CacheStore` tag as the local one: composing both as layers
+ * would shadow one with the other.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layer: <E, R>(remote: Effect.Effect<CacheStore.Service, E, R>) => Layer.Layer<CacheSync, E, R>;
+export {};
+//# sourceMappingURL=CacheSync.d.ts.map

package/dist/cjs/CacheSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheSync.d.ts","sourceRoot":"","sources":["../../src/CacheSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,CACrB,KAAK,EAAE,UAAU,CAAC,UAAU,KACzB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAA;CAC9D;;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,cAAuE;CAAG;AAEzG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,QAAO,OAE3B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAyC,CAAA;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAA;CAAE,KAAG,OAYtE,CAAA;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,EACxB,QAAQ,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAC9C,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,CAAsF,CAAA"}

package/dist/cjs/CacheSync.js

@@ -0,0 +1,64 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var CacheSync_exports = {};
+__export(CacheSync_exports, {
+  CacheSync: () => CacheSync,
+  layer: () => layer,
+  layerLocal: () => layerLocal,
+  make: () => make,
+  makeLocal: () => makeLocal
+});
+module.exports = __toCommonJS(CacheSync_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+class CacheSync extends Context.Service()("@smthrs/engine-store/CacheSync") {
+}
+const makeLocal = () => ({
+  publishEntry: Effect.fn("CacheSync.publishEntry")(() => Effect.succeed(Option.none()))
+});
+const layerLocal = Layer.succeed(CacheSync)(makeLocal());
+const make = (options) => ({
+  publishEntry: Effect.fn("CacheSync.publishEntry")(
+    (entry) => (
+      // A `Conflict` from the shared tier is not a refusal to report: it means
+      // another machine recorded the key first, which is exactly the
+      // first-writer-wins outcome the shared tier exists to arbitrate. Only a
+      // genuine failure — the tier is down, refused the body, answered with a
+      // status this client cannot classify — is worth journaling.
+      options.remote.put(entry).pipe(
+        Effect.as(Option.none()),
+        Effect.catch((error) => Effect.succeed(Option.some(error)))
+      )
+    )
+  )
+});
+const layer = (remote) => Layer.effect(CacheSync)(Effect.map(remote, (shared) => make({ remote: shared })));
+//# sourceMappingURL=CacheSync.js.map

package/dist/cjs/CacheSync.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/CacheSync.ts"],
+  "sourcesContent": ["/**\n * The shared step-result tier's publication seam: the remote half of a cache\n * `put`, run *after* the transaction that made the local row durable.\n *\n * `ArtifactSync` is the same idea for the artifact tier, and the two together\n * are the REAPI ordering constraint\n * (`reference/bazel/.../remote/UploadManifest.java:630-633`): blobs first, the\n * entry that references them last.\n *\n * This tag exists because of *where* the local row is written.\n * `ActionPersistence` commits the cache row and the journal record that\n * explains it in one `DurableWriter` transaction, and nothing that is not\n * storage work may be held across one \u2014 the action body, the Jj snapshot, and\n * the boundary prepare/settle all already stay outside. A `CacheStore` whose\n * `put` also writes a shared HTTP tier would put a network round trip inside\n * that transaction, blocking every other writer for its duration and rolling\n * the local row back when a *shared cache* is unreachable. So the local put\n * stays inside and the shared put becomes this service, invoked once the\n * transaction has committed. Compose it with\n * `CombinedCacheStore` in `\"deferred\"` publication mode, which is the mode that\n * leaves the shared write to this seam.\n *\n * Publication is **best-effort by construction**. A shared cache is an\n * accelerator, and the work it would have shared is already durably recorded on\n * this host: failing a completed run because an optional tier is unreachable\n * trades a real result for an unavailable one. A refused publication is\n * journaled by the caller instead, which is the same treatment an unverified\n * read set gets \u2014 visible, not silent.\n *\n * Governing design: `packages/smithers/flows/step-cache/docs/api.md`.\n *\n * @since 0.1.0\n */\n\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 Option from \"effect/Option\"\n\n/**\n * The one operation the shared-cache publication seam exposes.\n *\n * It is a single method rather than a store interface on purpose: everything\n * about reading, keying, and invalidating a cache entry belongs to\n * `CacheStore`, and all this seam does is take an already-durable local entry\n * and try to share it.\n *\n * @since 0.1.0\n * @category services\n */\nexport interface Service {\n  /**\n   * Publishes a cache entry to the shared tier, reporting the refusal rather\n   * than failing: `Option.none()` means the entry is now shared, and\n   * `Option.some(error)` means it is not and why.\n   *\n   * Callers must only reach here once every artifact the entry references is\n   * durable in the shared artifact tier \u2014 that is `ArtifactSync.publish`'s job,\n   * and it runs first.\n   */\n  readonly publishEntry: (\n    entry: CacheStore.CacheEntry\n  ) => Effect.Effect<Option.Option<CacheStore.CacheStoreError>>\n}\n\n/**\n * Service tag for the shared step-result publication seam.\n *\n * @since 0.1.0\n * @category services\n */\nexport class CacheSync extends Context.Service<CacheSync, Service>()(\"@smthrs/engine-store/CacheSync\") {}\n\n/**\n * The single-tier implementation: there is no shared step-result tier, so a\n * recorded entry is already everywhere it will ever be.\n *\n * This is the default `ActionPersistence` falls back to when the tag is\n * absent, which is what keeps a purely local composition free of any\n * remote-cache machinery.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const makeLocal = (): Service => ({\n  publishEntry: Effect.fn(\"CacheSync.publishEntry\")(() => Effect.succeed(Option.none()))\n})\n\n/**\n * Provides the single-tier (no shared step-result store) publication seam.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layerLocal: Layer.Layer<CacheSync> = Layer.succeed(CacheSync)(makeLocal())\n\n/**\n * Builds the publication seam over a shared step-result store \u2014 typically\n * `RemoteCacheStore`.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const make = (options: { readonly remote: CacheStore.Service }): Service => ({\n  publishEntry: Effect.fn(\"CacheSync.publishEntry\")((entry: CacheStore.CacheEntry) =>\n    // A `Conflict` from the shared tier is not a refusal to report: it means\n    // another machine recorded the key first, which is exactly the\n    // first-writer-wins outcome the shared tier exists to arbitrate. Only a\n    // genuine failure \u2014 the tier is down, refused the body, answered with a\n    // status this client cannot classify \u2014 is worth journaling.\n    options.remote.put(entry).pipe(\n      Effect.as(Option.none<CacheStore.CacheStoreError>()),\n      Effect.catch((error) => Effect.succeed(Option.some(error)))\n    )\n  )\n})\n\n/**\n * Provides the publication seam over the supplied shared store.\n *\n * The shared store arrives as an *effect* rather than a layer because it\n * inhabits the same `CacheStore` tag as the local one: composing both as layers\n * would shadow one with the other.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layer = <E, R>(\n  remote: Effect.Effect<CacheStore.Service, E, R>\n): Layer.Layer<CacheSync, E, R> => Layer.effect(CacheSync)(Effect.map(remote, (shared) => make({ remote: shared })))\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmCA,cAAyB;AACzB,aAAwB;AACxB,YAAuB;AACvB,aAAwB;AAkCjB,MAAM,kBAAkB,QAAQ,QAA4B,EAAE,gCAAgC,EAAE;AAAC;AAajG,MAAM,YAAY,OAAgB;AAAA,EACvC,cAAc,OAAO,GAAG,wBAAwB,EAAE,MAAM,OAAO,QAAQ,OAAO,KAAK,CAAC,CAAC;AACvF;AAQO,MAAM,aAAqC,MAAM,QAAQ,SAAS,EAAE,UAAU,CAAC;AAS/E,MAAM,OAAO,CAAC,aAA+D;AAAA,EAClF,cAAc,OAAO,GAAG,wBAAwB;AAAA,IAAE,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAMjD,QAAQ,OAAO,IAAI,KAAK,EAAE;AAAA,QACxB,OAAO,GAAG,OAAO,KAAiC,CAAC;AAAA,QACnD,OAAO,MAAM,CAAC,UAAU,OAAO,QAAQ,OAAO,KAAK,KAAK,CAAC,CAAC;AAAA,MAC5D;AAAA;AAAA,EACF;AACF;AAYO,MAAM,QAAQ,CACnB,WACiC,MAAM,OAAO,SAAS,EAAE,OAAO,IAAI,QAAQ,CAAC,WAAW,KAAK,EAAE,QAAQ,OAAO,CAAC,CAAC,CAAC;",
+  "names": []
+}

package/dist/cjs/DeferredClockFold.d.ts

@@ -0,0 +1,354 @@
+/**
+ * The deferred/clock fold: `flows_clock_deadlines` and the mutable half of
+ * `flows_deferred_completions` rebuilt from the journal.
+ *
+ * Every change to either table is journalled on the run's own stream in the
+ * transaction that makes it:
+ *
+ * - `flows.engine.clock-scheduled` when a clock row is inserted;
+ * - `flows.engine.clock-completed` when a clock fires or its run settles
+ *   first (`completeClock`, `completeRunClocks`);
+ * - `flows.engine.deferred-completed` when the first completion wins, naming
+ *   the row and the {@link JournalEvent.contentDigest} of its encoded `exit`
+ *   and `metadata`;
+ * - `flows.engine.deferred-consumed` when a run first observes a result.
+ *
+ * The journal is redacted and replayed to sync subscribers, so it never
+ * carries a completion's value (issue #72). A clock row holds no value at
+ * all, so the fold rebuilds it whole. A completion row's value stays in the
+ * row: the fold rebuilds its `completed_at_ms` and `consumed_at_ms`, and a
+ * rebuild checks the stored text against the recorded digests. A completion
+ * the journal names but no row holds, or holds with other bytes, is a typed
+ * {@link FoldIncomplete}, never a silent gap.
+ *
+ * Compaction deletes a run's entries below its floor, so the fold's state at
+ * the floor has to survive in the floor's checkpoint: {@link checkpointState}
+ * adds it under {@link checkpointKey}, and a rebuild of a compacted run whose
+ * floor checkpoint lacks it fails {@link FoldIncomplete} with reason
+ * `checkpoint_missing`. A rewind archives the suffix and removes the rows it
+ * explains (`@smthrs/time-travel`), so the remaining journal still explains
+ * the remaining rows.
+ *
+ * @since 1.0.0
+ */
+import { DurableWriter } from "@smthrs/database/DurableWriter";
+import { Journal, JournalEvent, Projection } from "@smthrs/journal";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * The journal event types the fold reads.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const eventTypes: ReadonlyArray<string>;
+/**
+ * The key a checkpoint's state keeps the fold under.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const checkpointKey = "flows.engine.deferred-clock";
+/**
+ * A clock as the journal records it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Clock: Schema.Struct<{
+    readonly flowName: Schema.NonEmptyString;
+    readonly executionId: Schema.NonEmptyString;
+    readonly clockName: Schema.NonEmptyString;
+    readonly deferredName: Schema.NonEmptyString;
+    readonly dueAtMs: Schema.Int;
+    readonly completedAtMs: Schema.NullOr<Schema.Int>;
+}>;
+/**
+ * A clock as the journal records it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Clock = typeof Clock.Type;
+/**
+ * A deferred completion as the journal records it. A completion journalled
+ * before the fold existed carried its (redacted) value instead of digests and
+ * no completion time: `exitDigest` and `metadataDigest` are then absent and
+ * `completedAtMs` is `null`, and a rebuild keeps the row's own stamp.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Deferred: Schema.Struct<{
+    readonly flowName: Schema.NonEmptyString;
+    readonly executionId: Schema.NonEmptyString;
+    readonly deferredName: Schema.NonEmptyString;
+    readonly completedAtMs: Schema.NullOr<Schema.Int>;
+    readonly exitDigest: Schema.optionalKey<Schema.String>;
+    readonly metadataDigest: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly consumedAtMs: Schema.NullOr<Schema.Int>;
+}>;
+/**
+ * A deferred completion as the journal records it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Deferred = typeof Deferred.Type;
+/**
+ * The folded clocks and completions, keyed by their row address.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface State {
+    readonly clocks: ReadonlyMap<string, Clock>;
+    readonly deferreds: ReadonlyMap<string, Deferred>;
+}
+/**
+ * The empty fold.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const initial: State;
+/**
+ * The key of a clock row.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const clockKey: (address: {
+    readonly flowName: string;
+    readonly executionId: string;
+    readonly clockName: string;
+}) => string;
+/**
+ * The key of a completion row.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const deferredKey: (address: {
+    readonly flowName: string;
+    readonly executionId: string;
+    readonly deferredName: string;
+}) => string;
+/**
+ * Folds one committed journal entry. First writes win: a clock keeps its first
+ * schedule and first completion, and a completion its first recording and
+ * first consumption, exactly as the rows do. An entry of another type, or one
+ * whose payload names no row, leaves the state unchanged.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export declare const reduce: (state: State, entry: JournalEvent.Entry) => State;
+/**
+ * The fold as a journal projection, for `Journal.project` over one run.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export declare const projection: Projection.Projection<State>;
+/**
+ * The checkpoint encoding of the fold.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Encoded: Schema.Struct<{
+    readonly clocks: Schema.$Array<Schema.Struct<{
+        readonly flowName: Schema.NonEmptyString;
+        readonly executionId: Schema.NonEmptyString;
+        readonly clockName: Schema.NonEmptyString;
+        readonly deferredName: Schema.NonEmptyString;
+        readonly dueAtMs: Schema.Int;
+        readonly completedAtMs: Schema.NullOr<Schema.Int>;
+    }>>;
+    readonly deferreds: Schema.$Array<Schema.Struct<{
+        readonly flowName: Schema.NonEmptyString;
+        readonly executionId: Schema.NonEmptyString;
+        readonly deferredName: Schema.NonEmptyString;
+        readonly completedAtMs: Schema.NullOr<Schema.Int>;
+        readonly exitDigest: Schema.optionalKey<Schema.String>;
+        readonly metadataDigest: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly consumedAtMs: Schema.NullOr<Schema.Int>;
+    }>>;
+}>;
+/**
+ * The checkpoint encoding of the fold.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Encoded = typeof Encoded.Type;
+/**
+ * Encodes the fold for a checkpoint.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export declare const encode: (state: State) => Encoded;
+/**
+ * Decodes the fold a checkpoint kept, or `None` when the checkpoint state
+ * holds none under {@link checkpointKey}.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export declare const fromCheckpoint: (checkpointState: unknown) => Option.Option<State>;
+/**
+ * Why a rebuild could not reconstruct the tables.
+ *
+ * - `row_missing`: the journal names a completion no row holds.
+ * - `digest_mismatch`: the row holds other bytes than the journal recorded.
+ * - `run_missing`: a clock's run has no `flows_runs` row to hang it on.
+ * - `checkpoint_missing`: a compacted run's floor checkpoint keeps no fold.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const FoldIncompleteReason: Schema.Literals<readonly ["row_missing", "digest_mismatch", "run_missing", "checkpoint_missing"]>;
+/**
+ * One reference a rebuild could not join.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare const Unjoined: Schema.Struct<{
+    readonly reason: Schema.Literals<readonly ["row_missing", "digest_mismatch", "run_missing", "checkpoint_missing"]>;
+    readonly executionId: Schema.String;
+    readonly flowName: Schema.optionalKey<Schema.String>;
+    readonly name: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * One reference a rebuild could not join.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export type Unjoined = typeof Unjoined.Type;
+declare const FoldIncomplete_base: Schema.Class<FoldIncomplete, Schema.TaggedStruct<"@smthrs/engine-store/DeferredClockFold/FoldIncomplete", {
+    readonly code: Schema.Literal<"fold_incomplete">;
+    readonly message: Schema.String;
+    readonly unjoined: Schema.$Array<Schema.Struct<{
+        readonly reason: Schema.Literals<readonly ["row_missing", "digest_mismatch", "run_missing", "checkpoint_missing"]>;
+        readonly executionId: Schema.String;
+        readonly flowName: Schema.optionalKey<Schema.String>;
+        readonly name: Schema.optionalKey<Schema.String>;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The journal references state the store no longer holds. The rebuild wrote
+ * nothing.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class FoldIncomplete extends FoldIncomplete_base {
+}
+/**
+ * The fold of one run's entries up to and including `upTo`, for the state of
+ * a checkpoint at `upTo`. It starts from the run's floor checkpoint when the
+ * run was compacted before.
+ *
+ * @category operations
+ * @since 1.0.0
+ */
+export declare const capture: (runId: string, upTo: number) => Effect.Effect<{
+    readonly clocks: readonly {
+        readonly flowName: string;
+        readonly executionId: string;
+        readonly clockName: string;
+        readonly deferredName: string;
+        readonly dueAtMs: number;
+        readonly completedAtMs: number | null;
+    }[];
+    readonly deferreds: readonly {
+        readonly executionId: string;
+        readonly flowName: string;
+        readonly completedAtMs: number | null;
+        readonly deferredName: string;
+        readonly consumedAtMs: number | null;
+        readonly exitDigest?: string;
+        readonly metadataDigest?: string | null;
+    }[];
+}, import("effect/unstable/sql/SqlError").SqlError | Journal.JournalError | FoldIncomplete, SqlClient.SqlClient | Journal.Journal>;
+/**
+ * A checkpoint state that keeps the fold: `base` (an object, or nothing) with
+ * the run's fold up to `upTo` under {@link checkpointKey}. A composition that
+ * compacts runs writes its checkpoints through this, so compaction cannot
+ * lose the deferred/clock history.
+ *
+ * @category operations
+ * @since 1.0.0
+ */
+export declare const checkpointState: (runId: string, upTo: number, base?: Readonly<Record<string, unknown>> | undefined) => Effect.Effect<{
+    "flows.engine.deferred-clock": {
+        readonly clocks: readonly {
+            readonly flowName: string;
+            readonly executionId: string;
+            readonly clockName: string;
+            readonly deferredName: string;
+            readonly dueAtMs: number;
+            readonly completedAtMs: number | null;
+        }[];
+        readonly deferreds: readonly {
+            readonly executionId: string;
+            readonly flowName: string;
+            readonly completedAtMs: number | null;
+            readonly deferredName: string;
+            readonly consumedAtMs: number | null;
+            readonly exitDigest?: string;
+            readonly metadataDigest?: string | null;
+        }[];
+    };
+}, import("effect/unstable/sql/SqlError").SqlError | Journal.JournalError | FoldIncomplete, SqlClient.SqlClient | Journal.Journal>;
+/**
+ * What a {@link rebuild} read and wrote.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Rebuilt {
+    /** Runs with deferred or clock entries, or with a compaction floor. */
+    readonly runs: number;
+    /** Clock rows written. */
+    readonly clocks: number;
+    /** Completion rows whose completion and consumption were rewritten. */
+    readonly deferreds: number;
+    /** Completion rows no journal entry explains, left as they are. */
+    readonly unexplained: number;
+}
+/**
+ * Rebuilds `flows_clock_deadlines` and the completion and consumption stamps
+ * of `flows_deferred_completions` from the journal.
+ *
+ * Every run with deferred or clock entries, and every compacted run, is
+ * folded in sequence order, from its floor checkpoint when it was compacted;
+ * a compacted run whose floor keeps no fold fails, even one that never had a
+ * clock, because the journal can no longer say. Every reference is joined
+ * before anything is written: a completion with no row or with other bytes,
+ * a clock whose run is gone, or a compacted run whose floor keeps no fold
+ * fails {@link FoldIncomplete} listing each one, and nothing is written.
+ * Otherwise, in one writer transaction, the clock table is replaced by the
+ * fold's clocks and each folded completion row gets the fold's
+ * `completed_at_ms` and `consumed_at_ms`. A completion row the journal does
+ * not explain is left alone and counted.
+ *
+ * Run it on a quiescent store, as a restore does.
+ *
+ * @category operations
+ * @since 1.0.0
+ */
+export declare const rebuild: () => Effect.Effect<{
+    runs: number;
+    clocks: number;
+    deferreds: number;
+    unexplained: number;
+}, import("effect/unstable/sql/SqlError").SqlError | import("@smthrs/database/DurableWriter").DatabaseError | Journal.JournalError | FoldIncomplete, SqlClient.SqlClient | DurableWriter | Journal.Journal>;
+export {};
+//# sourceMappingURL=DeferredClockFold.d.ts.map

package/dist/cjs/DeferredClockFold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeferredClockFold.d.ts","sourceRoot":"","sources":["../../src/DeferredClockFold.ts"],"names":[],"mappings":"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"}