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

package/dist/esm/Reconciliation.js

@@ -0,0 +1,175 @@
+/**
+ * The reconciliation seam: what happens when the world disagrees with the
+ * declaration.
+ *
+ * `docs/guides/drive-a-plan.md` ("Install a reconciler") describes expected sets as the soft
+ * mode: going outside them is allowed, journaled, and "triggers a
+ * **reconciliation flow** — pluggable, a flow like everything else". The
+ * deviation events have been emitted since the isolated-execution lane landed
+ * (`internal/ActionPersistence.ts`, both `expectedSetDeviation` sites) and
+ * had **no consumer at all**. This is the consumer, and
+ * `PlanScheduler` is what feeds it.
+ *
+ * Pluggability is dependency injection at the owning seam, per the repository's
+ * extension doctrine — there is no hook kernel. {@link layerDefault} installs a
+ * deterministic verdict function; a model-backed reconciler is a different
+ * `Layer` and lives in the agent packages. This package has no model
+ * dependency and must not grow one.
+ *
+ * The three verdicts are exactly the vault's: **fail** the step where the
+ * deviation is genuinely wrong, **reorder** — re-plan with the discovered
+ * dependency made explicit — and **factor out** a shared step, where content
+ * addressing does the heavy lifting because identical extracted steps collapse
+ * to one key automatically.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+/**
+ * A journaled `flows.engine.expected-set-deviation`, resolved against the plan
+ * the scheduler is driving.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const Deviation = Schema.Struct({
+    nodeId: Schema.NonEmptyString,
+    keyDigest: Schema.NonEmptyString,
+    attempt: Schema.Int,
+    /** Paths the execution touched that its declaration did not predict. */
+    paths: Schema.Array(Schema.String),
+    diffIdentity: Schema.String,
+    /**
+     * For each undeclared path, the OTHER plan node that declares it as a write
+     * — the discovered dependency, resolved by the scheduler because only it
+     * holds the plan.
+     */
+    declaredBy: Schema.Record(Schema.String, Schema.NonEmptyString),
+    /** Other nodes in this run whose deviation named exactly the same paths. */
+    alsoDeviatedBy: Schema.Array(Schema.NonEmptyString)
+});
+/**
+ * A `WorkspaceSandbox.MaterializationConflict` the runtime strategy could not
+ * absorb: the delay/rebase budget is spent, or the merge itself conflicted.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const Conflict = Schema.Struct({
+    nodeId: Schema.NonEmptyString,
+    keyDigest: Schema.NonEmptyString,
+    attempt: Schema.Int,
+    /** How many times the scheduler rebased before giving up. */
+    rebases: Schema.Int,
+    strategy: Schema.Literals(["delay-rebase", "stop-merge"]),
+    /** The plan nodes this one was annotated as conflicting with. */
+    conflictsWith: Schema.Array(Schema.NonEmptyString)
+});
+/**
+ * What reconciliation decided.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const Verdict = Schema.Union([
+    Schema.TaggedStruct("Fail", { reason: Schema.String }),
+    Schema.TaggedStruct("Reorder", { dependsOn: Schema.Array(Schema.NonEmptyString), reason: Schema.String }),
+    Schema.TaggedStruct("FactorOut", { paths: Schema.Array(Schema.String), reason: Schema.String })
+]);
+/**
+ * Service tag for the reconciliation seam.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export class Reconciliation extends Context.Service()("@smthrs/engine-store/Reconciliation") {
+}
+/**
+ * Names a {@link Service} implementation as a reconciler.
+ *
+ * It is the identity function: the value is checked against the interface at
+ * its definition site, which is where a wrong-shaped reconciler should be
+ * reported rather than at whichever layer eventually provides it.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = (service) => service;
+/**
+ * Provides a {@link Service} as the {@link Reconciliation} seam, replacing the
+ * deterministic default.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layer = (service) => Layer.succeed(Reconciliation, service);
+/**
+ * The deterministic default, in the vault's order of preference.
+ *
+ * 1. **Reorder** when every undeclared path is a path some *other* plan node
+ *    declares it writes. That is a real dependency the declaration missed, and
+ *    making it explicit is strictly better than failing.
+ * 2. **Factor out** when another node in the same run deviated on exactly the
+ *    same paths — two parallel steps that both ran `npm install`. No graph
+ *    surgery follows: content addressing collapses two identical extracted
+ *    steps to one key by itself, so the verdict is a record and a hint.
+ * 3. **Fail** otherwise. The default is deliberately conservative — a
+ *    deviation nobody can explain is the case the vault says is "genuinely
+ *    wrong", and guessing is what the model-backed reconciler is for.
+ *
+ * A conflict the runtime strategy could not absorb always fails here: choosing
+ * a winner between two landings is a semantic judgement this default does not
+ * have the material to make.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const makeDefault = () => ({
+    onDeviation: Effect.fn("Reconciliation.onDeviation")((deviation) => {
+        const paths = [...new Set(deviation.paths)];
+        // Own keys only: a path named `toString` must not resolve to Object.prototype.
+        const ownerOf = (path) => Object.hasOwn(deviation.declaredBy, path) ? deviation.declaredBy[path] : undefined;
+        const discovered = [
+            ...new Set(paths
+                .map(ownerOf)
+                .filter((owner) => owner !== undefined && owner !== deviation.nodeId))
+        ];
+        if (discovered.length > 0 &&
+            paths.every((path) => {
+                const owner = ownerOf(path);
+                return owner !== undefined && owner !== deviation.nodeId;
+            })) {
+            return Effect.succeed({
+                _tag: "Reorder",
+                dependsOn: discovered,
+                reason: `${deviation.nodeId} wrote paths declared by ${discovered.join(", ")}`
+            });
+        }
+        if (deviation.alsoDeviatedBy.length > 0) {
+            return Effect.succeed({
+                _tag: "FactorOut",
+                paths: deviation.paths,
+                reason: `${deviation.nodeId} and ${deviation.alsoDeviatedBy.join(", ")} produced the same undeclared paths`
+            });
+        }
+        return Effect.succeed({
+            _tag: "Fail",
+            reason: `${deviation.nodeId} wrote ${deviation.paths.join(", ")}, which no declaration explains`
+        });
+    }),
+    onConflict: Effect.fn("Reconciliation.onConflict")((conflict) => Effect.succeed({
+        _tag: "Fail",
+        reason: `${conflict.nodeId} could not land after ${conflict.rebases} rebases under ${conflict.strategy}`
+    }))
+});
+/**
+ * Installs the deterministic default reconciler.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerDefault = Layer.sync(Reconciliation, makeDefault);
+//# sourceMappingURL=Reconciliation.js.map

package/dist/esm/Reconciliation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Reconciliation.js","sourceRoot":"","sources":["../../src/Reconciliation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The reconciliation seam: what happens when the world disagrees with the\n * declaration.\n *\n * `docs/guides/drive-a-plan.md` (\"Install a reconciler\") describes expected sets as the soft\n * mode: going outside them is allowed, journaled, and \"triggers a\n * **reconciliation flow** — pluggable, a flow like everything else\". The\n * deviation events have been emitted since the isolated-execution lane landed\n * (`internal/ActionPersistence.ts`, both `expectedSetDeviation` sites) and\n * had **no consumer at all**. This is the consumer, and\n * `PlanScheduler` is what feeds it.\n *\n * Pluggability is dependency injection at the owning seam, per the repository's\n * extension doctrine — there is no hook kernel. {@link layerDefault} installs a\n * deterministic verdict function; a model-backed reconciler is a different\n * `Layer` and lives in the agent packages. This package has no model\n * dependency and must not grow one.\n *\n * The three verdicts are exactly the vault's: **fail** the step where the\n * deviation is genuinely wrong, **reorder** — re-plan with the discovered\n * dependency made explicit — and **factor out** a shared step, where content\n * addressing does the heavy lifting because identical extracted steps collapse\n * to one key automatically.\n *\n * @since 0.1.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * A journaled `flows.engine.expected-set-deviation`, resolved against the plan\n * the scheduler is driving.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const Deviation = Schema.Struct({\n  nodeId: Schema.NonEmptyString,\n  keyDigest: Schema.NonEmptyString,\n  attempt: Schema.Int,\n  /** Paths the execution touched that its declaration did not predict. */\n  paths: Schema.Array(Schema.String),\n  diffIdentity: Schema.String,\n  /**\n   * For each undeclared path, the OTHER plan node that declares it as a write\n   * — the discovered dependency, resolved by the scheduler because only it\n   * holds the plan.\n   */\n  declaredBy: Schema.Record(Schema.String, Schema.NonEmptyString),\n  /** Other nodes in this run whose deviation named exactly the same paths. */\n  alsoDeviatedBy: Schema.Array(Schema.NonEmptyString)\n})\n\n/**\n * The value form of {@link Deviation}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type Deviation = typeof Deviation.Type\n\n/**\n * A `WorkspaceSandbox.MaterializationConflict` the runtime strategy could not\n * absorb: the delay/rebase budget is spent, or the merge itself conflicted.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const Conflict = Schema.Struct({\n  nodeId: Schema.NonEmptyString,\n  keyDigest: Schema.NonEmptyString,\n  attempt: Schema.Int,\n  /** How many times the scheduler rebased before giving up. */\n  rebases: Schema.Int,\n  strategy: Schema.Literals([\"delay-rebase\", \"stop-merge\"]),\n  /** The plan nodes this one was annotated as conflicting with. */\n  conflictsWith: Schema.Array(Schema.NonEmptyString)\n})\n\n/**\n * The value form of {@link Conflict}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type Conflict = typeof Conflict.Type\n\n/**\n * What reconciliation decided.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const Verdict = Schema.Union([\n  Schema.TaggedStruct(\"Fail\", { reason: Schema.String }),\n  Schema.TaggedStruct(\"Reorder\", { dependsOn: Schema.Array(Schema.NonEmptyString), reason: Schema.String }),\n  Schema.TaggedStruct(\"FactorOut\", { paths: Schema.Array(Schema.String), reason: Schema.String })\n])\n\n/**\n * The value form of {@link Verdict}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type Verdict = typeof Verdict.Type\n\n/**\n * The pluggable reconciler.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface Service {\n  readonly onDeviation: (deviation: Deviation) => Effect.Effect<Verdict>\n  readonly onConflict: (conflict: Conflict) => Effect.Effect<Verdict>\n}\n\n/**\n * Service tag for the reconciliation seam.\n *\n * @since 0.1.0\n * @category services\n */\nexport class Reconciliation extends Context.Service<Reconciliation, Service>()(\"@smthrs/engine-store/Reconciliation\") {}\n\n/**\n * Names a {@link Service} implementation as a reconciler.\n *\n * It is the identity function: the value is checked against the interface at\n * its definition site, which is where a wrong-shaped reconciler should be\n * reported rather than at whichever layer eventually provides it.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const make = (service: Service): Service => service\n\n/**\n * Provides a {@link Service} as the {@link Reconciliation} seam, replacing the\n * deterministic default.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layer = (service: Service): Layer.Layer<Reconciliation> => Layer.succeed(Reconciliation, service)\n\n/**\n * The deterministic default, in the vault's order of preference.\n *\n * 1. **Reorder** when every undeclared path is a path some *other* plan node\n *    declares it writes. That is a real dependency the declaration missed, and\n *    making it explicit is strictly better than failing.\n * 2. **Factor out** when another node in the same run deviated on exactly the\n *    same paths — two parallel steps that both ran `npm install`. No graph\n *    surgery follows: content addressing collapses two identical extracted\n *    steps to one key by itself, so the verdict is a record and a hint.\n * 3. **Fail** otherwise. The default is deliberately conservative — a\n *    deviation nobody can explain is the case the vault says is \"genuinely\n *    wrong\", and guessing is what the model-backed reconciler is for.\n *\n * A conflict the runtime strategy could not absorb always fails here: choosing\n * a winner between two landings is a semantic judgement this default does not\n * have the material to make.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const makeDefault = (): Service => ({\n  onDeviation: Effect.fn(\"Reconciliation.onDeviation\")((deviation) => {\n    const paths = [...new Set(deviation.paths)]\n    // Own keys only: a path named `toString` must not resolve to Object.prototype.\n    const ownerOf = (path: string): string | undefined =>\n      Object.hasOwn(deviation.declaredBy, path) ? deviation.declaredBy[path] : undefined\n    const discovered = [\n      ...new Set(\n        paths\n          .map(ownerOf)\n          .filter((owner): owner is string => owner !== undefined && owner !== deviation.nodeId)\n      )\n    ]\n    if (\n      discovered.length > 0 &&\n      paths.every((path) => {\n        const owner = ownerOf(path)\n        return owner !== undefined && owner !== deviation.nodeId\n      })\n    ) {\n      return Effect.succeed<Verdict>({\n        _tag: \"Reorder\",\n        dependsOn: discovered,\n        reason: `${deviation.nodeId} wrote paths declared by ${discovered.join(\", \")}`\n      })\n    }\n    if (deviation.alsoDeviatedBy.length > 0) {\n      return Effect.succeed<Verdict>({\n        _tag: \"FactorOut\",\n        paths: deviation.paths,\n        reason: `${deviation.nodeId} and ${deviation.alsoDeviatedBy.join(\", \")} produced the same undeclared paths`\n      })\n    }\n    return Effect.succeed<Verdict>({\n      _tag: \"Fail\",\n      reason: `${deviation.nodeId} wrote ${deviation.paths.join(\", \")}, which no declaration explains`\n    })\n  }),\n  onConflict: Effect.fn(\"Reconciliation.onConflict\")((conflict) =>\n    Effect.succeed<Verdict>({\n      _tag: \"Fail\",\n      reason: `${conflict.nodeId} could not land after ${conflict.rebases} rebases under ${conflict.strategy}`\n    })\n  )\n})\n\n/**\n * Installs the deterministic default reconciler.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layerDefault: Layer.Layer<Reconciliation> = Layer.sync(Reconciliation, makeDefault)\n"]}

package/dist/esm/ReplayOnly.d.ts

@@ -0,0 +1,91 @@
+/**
+ * An engine that replays recorded work and executes none.
+ *
+ * `smthrs runs verify` asks what a resume under the current code would do
+ * before anything runs: which recorded steps it would serve from their
+ * durable records, and which step it would execute again because its key no
+ * longer matches one. The engine is the only thing that can answer, because a
+ * step key is derived at dispatch from the running flow's own declaration,
+ * ordinal and scope. This service turns a durable engine into that question:
+ * a dispatch served from a durable record reports `replayed`, and the first
+ * dispatch that would run an action body dies with {@link WouldExecute} before
+ * any attempt row, snapshot, boundary or body. It reports `resumes` when it
+ * would re-enter a recorded attempt that never finished (a step parked inside
+ * its body), and `would-execute` when no record matches its key at all.
+ *
+ * The death is a defect on purpose. A typed failure would enter the action's
+ * retry policy, and the default policy never gives up; a defect is never
+ * retried, so the run settles with the verdict instead of spinning on it.
+ *
+ * Run it against a copy of the store. A replay still converges the journal
+ * rows a resume would write, and the run settles `failed` on the copy.
+ *
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+/**
+ * One dispatch a replay-only engine saw.
+ *
+ * `stepKeyDigest` is the identity `flows_attempts` rows are keyed on, so a
+ * reader joins it to the recorded attempts directly. `action` is the declared
+ * action name. `outcome` is `replayed` for a dispatch served from a durable
+ * record (a recorded failure included), `resumes` for one that would re-enter
+ * a recorded attempt that never finished, and `would-execute` for one no
+ * record matches.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Dispatch {
+    readonly runId: string;
+    readonly stepKeyDigest: string;
+    readonly attempt: number;
+    readonly action: string;
+    readonly tier: "sealed" | "compensable" | "irreversible";
+    readonly outcome: "replayed" | "resumes" | "would-execute";
+}
+/**
+ * Receives every dispatch a replay-only engine settles, in settlement order.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Service {
+    readonly observe: (dispatch: Dispatch) => Effect.Effect<void>;
+}
+declare const ReplayOnly_base: Context.ServiceClass<ReplayOnly, "@smthrs/engine-store/ReplayOnly", Service>;
+/**
+ * Service tag. An engine composed with it in context executes no action body.
+ *
+ * @since 1.0.0
+ * @category services
+ */
+export declare class ReplayOnly extends ReplayOnly_base {
+}
+declare const WouldExecute_base: Schema.Class<WouldExecute, Schema.TaggedStruct<"@smthrs/engine-store/WouldExecute", {
+    readonly runId: Schema.String;
+    readonly stepKeyDigest: Schema.String;
+    readonly attempt: Schema.Number;
+    readonly action: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The defect a replay-only dispatch dies with instead of executing.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export declare class WouldExecute extends WouldExecute_base {
+    get message(): string;
+}
+/**
+ * Provides a replay-only engine context that reports to `observe`.
+ *
+ * @since 1.0.0
+ * @category layers
+ */
+export declare const layer: (observe: Service["observe"]) => Layer.Layer<ReplayOnly>;
+export {};
+//# sourceMappingURL=ReplayOnly.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReplayOnly.d.ts","sourceRoot":"","sources":["../../src/ReplayOnly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,GAAG,cAAc,CAAA;IACxD,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,eAAe,CAAA;CAC3D;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CAC9D;;AAED;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,eAAyE;CAAG;;;;;;;AAE5G;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,iBAKhC;IACA,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,SAAS,OAAO,CAAC,SAAS,CAAC,KAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CACnB,CAAA"}

package/dist/esm/ReplayOnly.js

@@ -0,0 +1,59 @@
+/**
+ * An engine that replays recorded work and executes none.
+ *
+ * `smthrs runs verify` asks what a resume under the current code would do
+ * before anything runs: which recorded steps it would serve from their
+ * durable records, and which step it would execute again because its key no
+ * longer matches one. The engine is the only thing that can answer, because a
+ * step key is derived at dispatch from the running flow's own declaration,
+ * ordinal and scope. This service turns a durable engine into that question:
+ * a dispatch served from a durable record reports `replayed`, and the first
+ * dispatch that would run an action body dies with {@link WouldExecute} before
+ * any attempt row, snapshot, boundary or body. It reports `resumes` when it
+ * would re-enter a recorded attempt that never finished (a step parked inside
+ * its body), and `would-execute` when no record matches its key at all.
+ *
+ * The death is a defect on purpose. A typed failure would enter the action's
+ * retry policy, and the default policy never gives up; a defect is never
+ * retried, so the run settles with the verdict instead of spinning on it.
+ *
+ * Run it against a copy of the store. A replay still converges the journal
+ * rows a resume would write, and the run settles `failed` on the copy.
+ *
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+/**
+ * Service tag. An engine composed with it in context executes no action body.
+ *
+ * @since 1.0.0
+ * @category services
+ */
+export class ReplayOnly extends Context.Service()("@smthrs/engine-store/ReplayOnly") {
+}
+/**
+ * The defect a replay-only dispatch dies with instead of executing.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export class WouldExecute extends Schema.TaggedError()("@smthrs/engine-store/WouldExecute", {
+    runId: Schema.String,
+    stepKeyDigest: Schema.String,
+    attempt: Schema.Number,
+    action: Schema.String
+}) {
+    get message() {
+        return `Action ${this.action} (step ${this.stepKeyDigest}, attempt ${this.attempt}) would execute`;
+    }
+}
+/**
+ * Provides a replay-only engine context that reports to `observe`.
+ *
+ * @since 1.0.0
+ * @category layers
+ */
+export const layer = (observe) => Layer.succeed(ReplayOnly, ReplayOnly.of({ observe }));
+//# sourceMappingURL=ReplayOnly.js.map

package/dist/esm/ReplayOnly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplayOnly.js","sourceRoot":"","sources":["../../src/ReplayOnly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAkCvC;;;;;GAKG;AACH,MAAM,OAAO,UAAW,SAAQ,OAAO,CAAC,OAAO,EAAuB,CAAC,iCAAiC,CAAC;CAAG;AAE5G;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,MAAM,CAAC,WAAW,EAAgB,CAAC,mCAAmC,EAAE;IACxG,KAAK,EAAE,MAAM,CAAC,MAAM;IACpB,aAAa,EAAE,MAAM,CAAC,MAAM;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM;CACtB,CAAC;IACA,IAAa,OAAO;QAClB,OAAO,UAAU,IAAI,CAAC,MAAM,UAAU,IAAI,CAAC,aAAa,aAAa,IAAI,CAAC,OAAO,iBAAiB,CAAA;IACpG,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,OAA2B,EAA2B,EAAE,CAC5E,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA","sourcesContent":["/**\n * An engine that replays recorded work and executes none.\n *\n * `smthrs runs verify` asks what a resume under the current code would do\n * before anything runs: which recorded steps it would serve from their\n * durable records, and which step it would execute again because its key no\n * longer matches one. The engine is the only thing that can answer, because a\n * step key is derived at dispatch from the running flow's own declaration,\n * ordinal and scope. This service turns a durable engine into that question:\n * a dispatch served from a durable record reports `replayed`, and the first\n * dispatch that would run an action body dies with {@link WouldExecute} before\n * any attempt row, snapshot, boundary or body. It reports `resumes` when it\n * would re-enter a recorded attempt that never finished (a step parked inside\n * its body), and `would-execute` when no record matches its key at all.\n *\n * The death is a defect on purpose. A typed failure would enter the action's\n * retry policy, and the default policy never gives up; a defect is never\n * retried, so the run settles with the verdict instead of spinning on it.\n *\n * Run it against a copy of the store. A replay still converges the journal\n * rows a resume would write, and the run settles `failed` on the copy.\n *\n * @since 1.0.0\n */\n\nimport * as Context from \"effect/Context\"\nimport type * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * One dispatch a replay-only engine saw.\n *\n * `stepKeyDigest` is the identity `flows_attempts` rows are keyed on, so a\n * reader joins it to the recorded attempts directly. `action` is the declared\n * action name. `outcome` is `replayed` for a dispatch served from a durable\n * record (a recorded failure included), `resumes` for one that would re-enter\n * a recorded attempt that never finished, and `would-execute` for one no\n * record matches.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface Dispatch {\n  readonly runId: string\n  readonly stepKeyDigest: string\n  readonly attempt: number\n  readonly action: string\n  readonly tier: \"sealed\" | \"compensable\" | \"irreversible\"\n  readonly outcome: \"replayed\" | \"resumes\" | \"would-execute\"\n}\n\n/**\n * Receives every dispatch a replay-only engine settles, in settlement order.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface Service {\n  readonly observe: (dispatch: Dispatch) => Effect.Effect<void>\n}\n\n/**\n * Service tag. An engine composed with it in context executes no action body.\n *\n * @since 1.0.0\n * @category services\n */\nexport class ReplayOnly extends Context.Service<ReplayOnly, Service>()(\"@smthrs/engine-store/ReplayOnly\") {}\n\n/**\n * The defect a replay-only dispatch dies with instead of executing.\n *\n * @since 1.0.0\n * @category errors\n */\nexport class WouldExecute extends Schema.TaggedError<WouldExecute>()(\"@smthrs/engine-store/WouldExecute\", {\n  runId: Schema.String,\n  stepKeyDigest: Schema.String,\n  attempt: Schema.Number,\n  action: Schema.String\n}) {\n  override get message(): string {\n    return `Action ${this.action} (step ${this.stepKeyDigest}, attempt ${this.attempt}) would execute`\n  }\n}\n\n/**\n * Provides a replay-only engine context that reports to `observe`.\n *\n * @since 1.0.0\n * @category layers\n */\nexport const layer = (observe: Service[\"observe\"]): Layer.Layer<ReplayOnly> =>\n  Layer.succeed(ReplayOnly, ReplayOnly.of({ observe }))\n"]}

package/dist/esm/Retention.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Deleting run history that has outlived its usefulness.
+ *
+ * Nothing in the durable stores forgets on its own: a finished run keeps its
+ * row, every attempt, every journal event, and every archived frame forever.
+ * That is the right default — a run's history is the only account of what an
+ * agent did to a repository — and it is why `smithers gc` exists rather than a
+ * background sweeper. Retention is an operator decision, taken explicitly,
+ * with a dry run available before anything is deleted.
+ *
+ * This module is the public surface. The operation lives in
+ * `internal/RetentionOps.ts` beside the other modules that read this package's
+ * own tables, so `internal/` is never imported by a consumer — the same split
+ * `Errors.ts` uses. {@link retain} and {@link layer} are that operation: one
+ * bounded pass over the engine ladder, inside one `journal.transact`.
+ *
+ * {@link collect} is the host-facing pass `smithers gc` runs, and it is a
+ * facade over the same guard. A project keeps its history in two files — the
+ * control plane's database and the engine's — and a sweep of one without the
+ * other leaves half of a deleted run behind, so the pass takes the database as
+ * a service and runs once per file. Which runs it may delete is
+ * {@link RetentionOps.lineagePrelude}'s answer, not a second guard written
+ * here: a run stays whenever a live run stands above or below it, over BOTH
+ * relations that make one run the parent of another — the `flows_run_parents`
+ * edge a spawned child records, and the `parent_run_id` column a trampoline
+ * lineage is chained through.
+ *
+ * Only terminal runs are ever considered. A `pending`, `running`, or
+ * `suspended` row belongs to work that can still resume.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import * as RetentionOps from "./internal/RetentionOps.ts";
+export { defaultLimit, layer, make, type RetainOptions, type RetainReport, Retention, RetentionError, RetentionErrorCode, type RunScopedTable, 
+/**
+ * Every table a deleted run leaves rows in. One inventory serves this pass
+ * and {@link Service.retain}, so neither can leak what the other deletes.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+runScopedTables, type Service, terminalStatuses } from "./internal/RetentionOps.ts";
+/**
+ * What one retention pass would delete, or did.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Report {
+    readonly database: string;
+    /** The threshold, as an epoch millisecond value. */
+    readonly olderThanMs: number;
+    readonly runs: ReadonlyArray<string>;
+    /** Rows deleted per table; empty under a dry run. */
+    readonly deleted: Readonly<Record<string, number>>;
+    readonly dryRun: boolean;
+}
+/**
+ * Arguments accepted by {@link collect}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Options {
+    /** Delete terminal runs that finished strictly before this epoch millisecond. */
+    readonly olderThanMs: number;
+    readonly dryRun?: boolean | undefined;
+    /** A label for the report; the host's database path. */
+    readonly database?: string | undefined;
+    /** Largest number of runs considered by this pass. Defaults to 1,000. */
+    readonly limit?: number | undefined;
+    /** Runs retained by a host's cross-store ancestry, in addition to local live roots. */
+    readonly pins?: ReadonlyArray<string> | undefined;
+}
+/**
+ * The terminal runs one pass would delete, oldest first.
+ *
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const eligible: (olderThanMs: number, limit?: number) => Effect.Effect<ReadonlyArray<string>, SqlError, SqlClient.SqlClient>;
+/**
+ * Runs one retention pass.
+ *
+ * The deletion itself is {@link RetentionOps.deleteRuns}, the same one
+ * {@link Service.retain} runs, so this pass cannot hold a shorter table list
+ * than that one and cannot delete run rows in an order the self-referential
+ * `parent_run_id` foreign key refuses. A handoff parent always sorts before
+ * its successor, so deleting in age order broke as soon as one lineage
+ * straddled a chunk boundary, and it broke AFTER the dependent rows of every
+ * eligible run were already gone. `assumeLadder: false` because this pass also
+ * runs against the control plane's database, which composed fewer stores.
+ *
+ * Eligibility and deletion share one retryable transaction: another writer
+ * cannot attach a live parent between the lineage scan and deletion. A busy
+ * retry recomputes eligibility rather than replaying an old candidate list.
+ * One transaction, for the reason `retain` opens one: a pass that removed a
+ * run's history and then refused on its row would have destroyed what it could
+ * not put back, and a workspace whose next pass refuses the same way can never
+ * be collected again.
+ *
+ * Under `dryRun` nothing is written and `deleted` is empty: the report names
+ * exactly the runs a real pass would remove, which is what makes
+ * `smithers gc --dry-run` worth trusting.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const collect: (options: Options) => Effect.Effect<Report, SqlError | RetentionOps.RetentionError, SqlClient.SqlClient>;
+//# sourceMappingURL=Retention.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Retention.d.ts","sourceRoot":"","sources":["../../src/Retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,KAAK,YAAY,MAAM,4BAA4B,CAAA;AAE1D,OAAO,EACL,YAAY,EACZ,KAAK,EACL,IAAI,EACJ,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,KAAK,cAAc;AACnB;;;;;;GAMG;AACH,eAAe,EACf,KAAK,OAAO,EACZ,gBAAgB,EACjB,MAAM,4BAA4B,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,uFAAuF;IACvF,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;CAClD;AA4CD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GACnB,aAAa,MAAM,EACnB,cAAiC,KAChC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,SAAS,CAIlE,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,OAAO,GAClB,SAAS,OAAO,KACf,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAC,cAAc,EAAE,SAAS,CAAC,SAAS,CA+BhF,CAAA"}

package/dist/esm/Retention.js

@@ -0,0 +1,139 @@
+/**
+ * Deleting run history that has outlived its usefulness.
+ *
+ * Nothing in the durable stores forgets on its own: a finished run keeps its
+ * row, every attempt, every journal event, and every archived frame forever.
+ * That is the right default — a run's history is the only account of what an
+ * agent did to a repository — and it is why `smithers gc` exists rather than a
+ * background sweeper. Retention is an operator decision, taken explicitly,
+ * with a dry run available before anything is deleted.
+ *
+ * This module is the public surface. The operation lives in
+ * `internal/RetentionOps.ts` beside the other modules that read this package's
+ * own tables, so `internal/` is never imported by a consumer — the same split
+ * `Errors.ts` uses. {@link retain} and {@link layer} are that operation: one
+ * bounded pass over the engine ladder, inside one `journal.transact`.
+ *
+ * {@link collect} is the host-facing pass `smithers gc` runs, and it is a
+ * facade over the same guard. A project keeps its history in two files — the
+ * control plane's database and the engine's — and a sweep of one without the
+ * other leaves half of a deleted run behind, so the pass takes the database as
+ * a service and runs once per file. Which runs it may delete is
+ * {@link RetentionOps.lineagePrelude}'s answer, not a second guard written
+ * here: a run stays whenever a live run stands above or below it, over BOTH
+ * relations that make one run the parent of another — the `flows_run_parents`
+ * edge a spawned child records, and the `parent_run_id` column a trampoline
+ * lineage is chained through.
+ *
+ * Only terminal runs are ever considered. A `pending`, `running`, or
+ * `suspended` row belongs to work that can still resume.
+ *
+ * @since 1.0.0
+ */
+import * as Dialect from "@smthrs/database/Dialect";
+import * as DurableWriter from "@smthrs/database/DurableWriter";
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as RetentionOps from "./internal/RetentionOps.js";
+export { defaultLimit, layer, make, Retention, RetentionError, RetentionErrorCode, 
+/**
+ * Every table a deleted run leaves rows in. One inventory serves this pass
+ * and {@link Service.retain}, so neither can leak what the other deletes.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+runScopedTables, terminalStatuses } from "./internal/RetentionOps.js";
+/** Whether a table exists in the connected database. */
+const hasTable = (table) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const rows = yield* Dialect.tables(sql).pipe(Effect.map((rows) => rows.filter((row) => row.name === table)));
+    return rows.length > 0;
+});
+/**
+ * The runs one pass would delete, oldest first, each with the run it names as
+ * its parent.
+ *
+ * The same candidate query `retain` runs: children before parents, so a
+ * trampoline lineage longer than the bound still loses a run every pass, and
+ * a run is excluded whenever a live run stands above or below it. Downward,
+ * deleting a parent whose child is still running would break the
+ * `parent_run_id` foreign key and drop the live child's edges with the
+ * `flows_run_parents_gc` trigger. Upward, a parked parent still reads a
+ * settled child's result out of its run row through `agent/await`, and it can
+ * be parked for longer than the threshold before it ever asks.
+ */
+const eligibleCandidates = (olderThanMs, limit, pins) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    if (!(yield* hasTable("flows_runs")))
+        return [];
+    // The engine's edge table is absent from the control-plane database, which
+    // migrates the run store and the journal and nothing else. The prelude
+    // drops that half of the walk there and keeps the `parent_run_id` half, so
+    // one guard covers both files.
+    return yield* RetentionOps.candidatesOf(sql, {
+        cutoffMs: olderThanMs,
+        inclusive: false,
+        parentEdges: yield* hasTable("flows_run_parents"),
+        pins,
+        limit: RetentionOps.normalizeLimit(limit)
+    });
+});
+/**
+ * The terminal runs one pass would delete, oldest first.
+ *
+ * @category getters
+ * @since 1.0.0
+ */
+export const eligible = (olderThanMs, limit = RetentionOps.defaultLimit) => Effect.map(eligibleCandidates(olderThanMs, limit), (candidates) => candidates.map((candidate) => candidate.runId));
+/**
+ * Runs one retention pass.
+ *
+ * The deletion itself is {@link RetentionOps.deleteRuns}, the same one
+ * {@link Service.retain} runs, so this pass cannot hold a shorter table list
+ * than that one and cannot delete run rows in an order the self-referential
+ * `parent_run_id` foreign key refuses. A handoff parent always sorts before
+ * its successor, so deleting in age order broke as soon as one lineage
+ * straddled a chunk boundary, and it broke AFTER the dependent rows of every
+ * eligible run were already gone. `assumeLadder: false` because this pass also
+ * runs against the control plane's database, which composed fewer stores.
+ *
+ * Eligibility and deletion share one retryable transaction: another writer
+ * cannot attach a live parent between the lineage scan and deletion. A busy
+ * retry recomputes eligibility rather than replaying an old candidate list.
+ * One transaction, for the reason `retain` opens one: a pass that removed a
+ * run's history and then refused on its row would have destroyed what it could
+ * not put back, and a workspace whose next pass refuses the same way can never
+ * be collected again.
+ *
+ * Under `dryRun` nothing is written and `deleted` is empty: the report names
+ * exactly the runs a real pass would remove, which is what makes
+ * `smithers gc --dry-run` worth trusting.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const collect = (options) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const dryRun = options.dryRun === true;
+    const pass = Effect.gen(function* () {
+        const candidates = yield* eligibleCandidates(options.olderThanMs, options.limit, options.pins);
+        return yield* RetentionOps.deleteRuns(sql, candidates, {
+            dryRun,
+            assumeLadder: false
+        });
+    });
+    const removed = yield* (dryRun ? sql.withTransaction(pass) : DurableWriter.make(sql).write(pass).pipe(Effect.catchIf((cause) => cause instanceof DurableWriter.DatabaseError, (cause) => Effect.fail(new RetentionOps.RetentionError({
+        code: "delete_failed",
+        message: "retention transaction failed; no history was deleted",
+        cause
+    })))));
+    return {
+        database: options.database ?? "",
+        olderThanMs: options.olderThanMs,
+        runs: removed.runIds,
+        deleted: dryRun ? {} : removed.deleted,
+        dryRun
+    };
+});
+//# sourceMappingURL=Retention.js.map

package/dist/esm/Retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Retention.js","sourceRoot":"","sources":["../../src/Retention.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Deleting run history that has outlived its usefulness.\n *\n * Nothing in the durable stores forgets on its own: a finished run keeps its\n * row, every attempt, every journal event, and every archived frame forever.\n * That is the right default — a run's history is the only account of what an\n * agent did to a repository — and it is why `smithers gc` exists rather than a\n * background sweeper. Retention is an operator decision, taken explicitly,\n * with a dry run available before anything is deleted.\n *\n * This module is the public surface. The operation lives in\n * `internal/RetentionOps.ts` beside the other modules that read this package's\n * own tables, so `internal/` is never imported by a consumer — the same split\n * `Errors.ts` uses. {@link retain} and {@link layer} are that operation: one\n * bounded pass over the engine ladder, inside one `journal.transact`.\n *\n * {@link collect} is the host-facing pass `smithers gc` runs, and it is a\n * facade over the same guard. A project keeps its history in two files — the\n * control plane's database and the engine's — and a sweep of one without the\n * other leaves half of a deleted run behind, so the pass takes the database as\n * a service and runs once per file. Which runs it may delete is\n * {@link RetentionOps.lineagePrelude}'s answer, not a second guard written\n * here: a run stays whenever a live run stands above or below it, over BOTH\n * relations that make one run the parent of another — the `flows_run_parents`\n * edge a spawned child records, and the `parent_run_id` column a trampoline\n * lineage is chained through.\n *\n * Only terminal runs are ever considered. A `pending`, `running`, or\n * `suspended` row belongs to work that can still resume.\n *\n * @since 1.0.0\n */\n\nimport * as Dialect from \"@smthrs/database/Dialect\"\nimport * as DurableWriter from \"@smthrs/database/DurableWriter\"\nimport * as Effect from \"effect/Effect\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\nimport type { SqlError } from \"effect/unstable/sql/SqlError\"\nimport * as RetentionOps from \"./internal/RetentionOps.ts\"\n\nexport {\n  defaultLimit,\n  layer,\n  make,\n  type RetainOptions,\n  type RetainReport,\n  Retention,\n  RetentionError,\n  RetentionErrorCode,\n  type RunScopedTable,\n  /**\n   * Every table a deleted run leaves rows in. One inventory serves this pass\n   * and {@link Service.retain}, so neither can leak what the other deletes.\n   *\n   * @category constants\n   * @since 1.0.0\n   */\n  runScopedTables,\n  type Service,\n  terminalStatuses\n} from \"./internal/RetentionOps.ts\"\n\n/**\n * What one retention pass would delete, or did.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Report {\n  readonly database: string\n  /** The threshold, as an epoch millisecond value. */\n  readonly olderThanMs: number\n  readonly runs: ReadonlyArray<string>\n  /** Rows deleted per table; empty under a dry run. */\n  readonly deleted: Readonly<Record<string, number>>\n  readonly dryRun: boolean\n}\n\n/**\n * Arguments accepted by {@link collect}.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Options {\n  /** Delete terminal runs that finished strictly before this epoch millisecond. */\n  readonly olderThanMs: number\n  readonly dryRun?: boolean | undefined\n  /** A label for the report; the host's database path. */\n  readonly database?: string | undefined\n  /** Largest number of runs considered by this pass. Defaults to 1,000. */\n  readonly limit?: number | undefined\n  /** Runs retained by a host's cross-store ancestry, in addition to local live roots. */\n  readonly pins?: ReadonlyArray<string> | undefined\n}\n\n/** Whether a table exists in the connected database. */\nconst hasTable = (table: string): Effect.Effect<boolean, SqlError, SqlClient.SqlClient> =>\n  Effect.gen(function*() {\n    const sql = yield* SqlClient.SqlClient\n    const rows = yield* Dialect.tables(sql).pipe(Effect.map((rows) => rows.filter((row) => row.name === table)))\n    return rows.length > 0\n  })\n\n/**\n * The runs one pass would delete, oldest first, each with the run it names as\n * its parent.\n *\n * The same candidate query `retain` runs: children before parents, so a\n * trampoline lineage longer than the bound still loses a run every pass, and\n * a run is excluded whenever a live run stands above or below it. Downward,\n * deleting a parent whose child is still running would break the\n * `parent_run_id` foreign key and drop the live child's edges with the\n * `flows_run_parents_gc` trigger. Upward, a parked parent still reads a\n * settled child's result out of its run row through `agent/await`, and it can\n * be parked for longer than the threshold before it ever asks.\n */\nconst eligibleCandidates = (\n  olderThanMs: number,\n  limit: number | undefined,\n  pins?: ReadonlyArray<string>\n): Effect.Effect<ReadonlyArray<RetentionOps.Candidate>, SqlError, SqlClient.SqlClient> =>\n  Effect.gen(function*() {\n    const sql = yield* SqlClient.SqlClient\n    if (!(yield* hasTable(\"flows_runs\"))) return []\n    // The engine's edge table is absent from the control-plane database, which\n    // migrates the run store and the journal and nothing else. The prelude\n    // drops that half of the walk there and keeps the `parent_run_id` half, so\n    // one guard covers both files.\n    return yield* RetentionOps.candidatesOf(sql, {\n      cutoffMs: olderThanMs,\n      inclusive: false,\n      parentEdges: yield* hasTable(\"flows_run_parents\"),\n      pins,\n      limit: RetentionOps.normalizeLimit(limit)\n    })\n  })\n\n/**\n * The terminal runs one pass would delete, oldest first.\n *\n * @category getters\n * @since 1.0.0\n */\nexport const eligible = (\n  olderThanMs: number,\n  limit = RetentionOps.defaultLimit\n): Effect.Effect<ReadonlyArray<string>, SqlError, SqlClient.SqlClient> =>\n  Effect.map(\n    eligibleCandidates(olderThanMs, limit),\n    (candidates) => candidates.map((candidate) => candidate.runId)\n  )\n\n/**\n * Runs one retention pass.\n *\n * The deletion itself is {@link RetentionOps.deleteRuns}, the same one\n * {@link Service.retain} runs, so this pass cannot hold a shorter table list\n * than that one and cannot delete run rows in an order the self-referential\n * `parent_run_id` foreign key refuses. A handoff parent always sorts before\n * its successor, so deleting in age order broke as soon as one lineage\n * straddled a chunk boundary, and it broke AFTER the dependent rows of every\n * eligible run were already gone. `assumeLadder: false` because this pass also\n * runs against the control plane's database, which composed fewer stores.\n *\n * Eligibility and deletion share one retryable transaction: another writer\n * cannot attach a live parent between the lineage scan and deletion. A busy\n * retry recomputes eligibility rather than replaying an old candidate list.\n * One transaction, for the reason `retain` opens one: a pass that removed a\n * run's history and then refused on its row would have destroyed what it could\n * not put back, and a workspace whose next pass refuses the same way can never\n * be collected again.\n *\n * Under `dryRun` nothing is written and `deleted` is empty: the report names\n * exactly the runs a real pass would remove, which is what makes\n * `smithers gc --dry-run` worth trusting.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const collect = (\n  options: Options\n): Effect.Effect<Report, SqlError | RetentionOps.RetentionError, SqlClient.SqlClient> =>\n  Effect.gen(function*() {\n    const sql = yield* SqlClient.SqlClient\n    const dryRun = options.dryRun === true\n    const pass = Effect.gen(function*() {\n      const candidates = yield* eligibleCandidates(options.olderThanMs, options.limit, options.pins)\n      return yield* RetentionOps.deleteRuns(sql, candidates, {\n        dryRun,\n        assumeLadder: false\n      })\n    })\n    const removed = yield* (dryRun ? sql.withTransaction(pass) : DurableWriter.make(sql).write(pass).pipe(\n      Effect.catchIf(\n        (cause): cause is DurableWriter.DatabaseError => cause instanceof DurableWriter.DatabaseError,\n        (cause) =>\n          Effect.fail(\n            new RetentionOps.RetentionError({\n              code: \"delete_failed\",\n              message: \"retention transaction failed; no history was deleted\",\n              cause\n            })\n          )\n      )\n    ))\n    return {\n      database: options.database ?? \"\",\n      olderThanMs: options.olderThanMs,\n      runs: removed.runIds,\n      deleted: dryRun ? {} : removed.deleted,\n      dryRun\n    }\n  })\n"]}