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

package/dist/esm/ArtifactGc.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Mark/sweep garbage collection for the content-addressed artifact store.
+ *
+ * The artifact tier is the one store in the composition with true *garbage*:
+ * every output over the inline bound is spilled to `.flows/objects` by digest
+ * (`StepBoundary`), nothing ever deletes a published blob, and a blob whose
+ * every referencing row is gone is unreachable forever. The step cache is
+ * deliberately NOT collected here — its rows are the *roots* of this graph,
+ * they never become unreachable, and removing one is the policy decision
+ * `CacheStore.evict` already serves.
+ *
+ * The design combines the two prior arts on the shelf:
+ *
+ * - **Reachability from durable roots** — git's `git gc` marks from refs;
+ *   Skyframe deletes what a keyed graph walk cannot reach. Here the roots are
+ *   every attempt row of every existing (never-deleted) run and every step
+ *   cache entry; each carries boundary evidence, and
+ *   `StepBoundary.referencedDigests` names the blobs that evidence needs.
+ *   Attempt checkpoints are roots too: they are opaque executable state, so
+ *   the mark keeps digest-shaped strings found in their JSON.
+ * - **A grace period over mtime** — git refuses to prune unreachable objects
+ *   younger than `gc.pruneExpire` (two weeks), jj keeps operations newer than
+ *   its keep bound, and Bazel's disk-cache collector
+ *   (`reference/bazel/.../remote/disk/DiskCacheGarbageCollector.java`) fences
+ *   on mtime. The cutoff is the collection start time minus the grace period,
+ *   sampled before resolving policy pins or scanning roots and held fixed
+ *   through inventory and deletion. Only mtimes strictly before it are
+ *   eligible: a blob published — or freshened by a dedupe `put` — at or after
+ *   collection start survives, including same-millisecond writes at zero
+ *   grace, no lock required.
+ *
+ * Collection NEVER runs automatically. `gc()` is an explicit verb because
+ * deletion is irreversible, and a human approving a plan must approve the
+ * deletions too. The opt-in {@link ArtifactGcPolicy} layer
+ * configures *how* an invocation collects (grace bound, pinned digests); it
+ * does not schedule anything.
+ *
+ * @since 0.1.0
+ */
+import * as ArtifactSweep from "@smthrs/artifacts/ArtifactSweep";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+/**
+ * Stable error codes returned by artifact garbage collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const ArtifactGcErrorCode: Schema.Literals<readonly ["invalid_options", "mark_failed", "sweep_failed"]>;
+/**
+ * Stable error codes returned by artifact garbage collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ArtifactGcErrorCode = typeof ArtifactGcErrorCode.Type;
+declare const ArtifactGcError_base: Schema.Class<ArtifactGcError, Schema.TaggedStruct<"@smthrs/engine-store/ArtifactGcError", {
+    readonly code: Schema.Literals<readonly ["invalid_options", "mark_failed", "sweep_failed"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A collection that could not complete. `mark_failed` means the live set
+ * could not be computed — nothing was deleted. `sweep_failed` means the live
+ * set held but a deletion refused; everything already swept was garbage, so a
+ * re-run converges from wherever the failure stopped it.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class ArtifactGcError extends ArtifactGcError_base {
+}
+/**
+ * The opt-in collection policy. Explicit {@link GcOptions} on a `gc()` call
+ * override the installed policy; the policy overrides the defaults.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Policy {
+    /** Grace bound applied when a `gc()` call does not name one. */
+    readonly graceMs?: number | undefined;
+    /**
+     * Digests held live regardless of reachability — the seam for references
+     * this composition's tables cannot see (an external index, an export a
+     * human wants kept). Resolved fresh on every collection.
+     */
+    readonly pins?: Effect.Effect<ReadonlyArray<string>> | undefined;
+}
+declare const ArtifactGcPolicy_base: Context.ServiceClass<ArtifactGcPolicy, "@smthrs/engine-store/ArtifactGcPolicy", Policy>;
+/**
+ * Service tag for the opt-in collection policy.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class ArtifactGcPolicy extends ArtifactGcPolicy_base {
+}
+/**
+ * Installs a collection policy.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerPolicy: (policy: Policy) => Layer.Layer<ArtifactGcPolicy>;
+/**
+ * Options for one explicit collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface GcOptions {
+    /**
+     * How recently a blob must have been written or freshened to survive
+     * unreferenced. Defaults to the installed {@link ArtifactGcPolicy}'s bound,
+     * then to {@link defaultGraceMs}.
+     */
+    readonly graceMs?: number | undefined;
+    /** Digests held live for this collection, unioned with the policy's pins. */
+    readonly pins?: ReadonlyArray<string> | undefined;
+    /** Compute and report without deleting anything. */
+    readonly dryRun?: boolean | undefined;
+}
+/**
+ * What one collection did.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface GcReport {
+    /** Blobs the inventory enumerated. */
+    readonly scannedBlobs: number;
+    /** Distinct digests the mark phase proved live, pins included. */
+    readonly liveDigests: number;
+    /** Digests deleted — or, under `dryRun`, the ones a real run would delete. */
+    readonly sweptDigests: ReadonlyArray<string>;
+    /** Bytes the swept blobs held. */
+    readonly reclaimedBytes: number;
+    /** Unreferenced blobs retained by the grace bound or a freshen race. */
+    readonly keptByGrace: number;
+    readonly dryRun: boolean;
+}
+/**
+ * Explicit artifact garbage collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    /**
+     * Marks the live set from the durable roots, then sweeps every blob that
+     * is both outside it and older than the grace bound. Explicit only —
+     * nothing in the engine composition ever calls this.
+     */
+    readonly gc: (options?: GcOptions) => Effect.Effect<GcReport, ArtifactGcError>;
+}
+declare const ArtifactGc_base: Context.ServiceClass<ArtifactGc, "@smthrs/engine-store/ArtifactGc", Service>;
+/**
+ * Service tag for artifact garbage collection.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class ArtifactGc extends ArtifactGc_base {
+}
+/**
+ * Two weeks, git's `gc.pruneExpire` default. The bound is deliberately far
+ * beyond any live attempt's duration: a blob spilled by a running step is
+ * unreferenced until its attempt row finishes, and the grace period is the
+ * only thing protecting it in that window.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultGraceMs: number;
+/**
+ * Construction options.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface MakeOptions {
+    /** Rows per mark-phase page. Defaults to 500. */
+    readonly pageSize?: number | undefined;
+}
+/**
+ * Builds the collector over the composition's own durable tables and the
+ * host-local sweep surface.
+ *
+ * The mark phase reads `flows_step_cache` and `flows_attempts` directly, the
+ * same way `DurableEngineState` range-scans `flows_runs`: this package
+ * composes every one of those migrations, so the schema is its own. Every run
+ * present in `flows_runs` is a live root — there is no deleted state, and the
+ * attempt table's foreign key guarantees each attempt's run exists — so the
+ * scan is simply *all* attempt rows plus *all* cache entries, paged by
+ * primary key so no page holds more than `pageSize` rows in memory.
+ *
+ * Ordering is the safety argument. The live set is computed BEFORE the
+ * inventory, so a root recorded during the sweep can only be missed, never
+ * half-seen — and the blob such a root references is protected anyway: a
+ * fresh publication carries a fresh mtime, a re-publication of existing bytes
+ * freshens the blob's mtime (`ArtifactStore.put`), and the sweep's deletion
+ * is fenced on that mtime (`ArtifactSweep.remove`'s `ifUnmodifiedSinceMs`).
+ * A crash mid-sweep deletes some garbage and no live blobs; re-running
+ * converges.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options?: MakeOptions) => Effect.Effect<Service, never, SqlClient.SqlClient | ArtifactSweep.ArtifactSweep>;
+/**
+ * Provides the artifact garbage collector. Install {@link layerPolicy} into
+ * this layer's inputs to configure collection; nothing schedules `gc()` —
+ * invoking it stays an explicit caller decision.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options?: MakeOptions) => Layer.Layer<ArtifactGc, never, SqlClient.SqlClient | ArtifactSweep.ArtifactSweep>;
+/**
+ * Provides the artifact garbage collector over a filesystem objects directory:
+ * {@link layer} with `ArtifactSweep.layerFileSystem` beneath it. Pass the same
+ * `directory` and `coordination` the paired `ArtifactStore.layerFileSystem`
+ * publishes with.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerFileSystem: (options?: MakeOptions & ArtifactSweep.SweepOptions) => Layer.Layer<ArtifactGc, never, SqlClient.SqlClient | FileSystem.FileSystem>;
+export {};
+//# sourceMappingURL=ArtifactGc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactGc.d.ts","sourceRoot":"","sources":["../../src/ArtifactGc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,aAAa,MAAM,iCAAiC,CAAA;AAEhE,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AAG1D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,8EAAsE,CAAA;AAEtG;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;;;;;;AAEjE;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,oBAOpC;CAAG;AAEJ;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;CACjE;;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,qBAErC;CAAG;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAG,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAA4C,CAAA;AAErH;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACjD,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5C,kCAAkC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAA;CAC/E;;AAED;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,eAAyE;CAAG;AAE5G;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,QAA2B,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACvC;AA4BD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,IAAI,GACf,UAAS,WAAgB,KACxB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,GAAG,aAAa,CAAC,aAAa,CAyH9E,CAAA;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAChB,UAAS,WAAgB,KACxB,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,GAAG,aAAa,CAAC,aAAa,CAC1C,CAAA;AAEzC;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAS,WAAW,GAAG,aAAa,CAAC,YAAiB,KACrD,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,GAAG,UAAU,CAAC,UAAU,CAG1E,CAAA"}

package/dist/esm/ArtifactGc.js

@@ -0,0 +1,268 @@
+/**
+ * Mark/sweep garbage collection for the content-addressed artifact store.
+ *
+ * The artifact tier is the one store in the composition with true *garbage*:
+ * every output over the inline bound is spilled to `.flows/objects` by digest
+ * (`StepBoundary`), nothing ever deletes a published blob, and a blob whose
+ * every referencing row is gone is unreachable forever. The step cache is
+ * deliberately NOT collected here — its rows are the *roots* of this graph,
+ * they never become unreachable, and removing one is the policy decision
+ * `CacheStore.evict` already serves.
+ *
+ * The design combines the two prior arts on the shelf:
+ *
+ * - **Reachability from durable roots** — git's `git gc` marks from refs;
+ *   Skyframe deletes what a keyed graph walk cannot reach. Here the roots are
+ *   every attempt row of every existing (never-deleted) run and every step
+ *   cache entry; each carries boundary evidence, and
+ *   `StepBoundary.referencedDigests` names the blobs that evidence needs.
+ *   Attempt checkpoints are roots too: they are opaque executable state, so
+ *   the mark keeps digest-shaped strings found in their JSON.
+ * - **A grace period over mtime** — git refuses to prune unreachable objects
+ *   younger than `gc.pruneExpire` (two weeks), jj keeps operations newer than
+ *   its keep bound, and Bazel's disk-cache collector
+ *   (`reference/bazel/.../remote/disk/DiskCacheGarbageCollector.java`) fences
+ *   on mtime. The cutoff is the collection start time minus the grace period,
+ *   sampled before resolving policy pins or scanning roots and held fixed
+ *   through inventory and deletion. Only mtimes strictly before it are
+ *   eligible: a blob published — or freshened by a dedupe `put` — at or after
+ *   collection start survives, including same-millisecond writes at zero
+ *   grace, no lock required.
+ *
+ * Collection NEVER runs automatically. `gc()` is an explicit verb because
+ * deletion is irreversible, and a human approving a plan must approve the
+ * deletions too. The opt-in {@link ArtifactGcPolicy} layer
+ * configures *how* an invocation collects (grace bound, pinned digests); it
+ * does not schedule anything.
+ *
+ * @since 0.1.0
+ */
+import * as ArtifactSweep from "@smthrs/artifacts/ArtifactSweep";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as ArtifactRoots from "./internal/ArtifactRoots.js";
+/**
+ * Stable error codes returned by artifact garbage collection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const ArtifactGcErrorCode = Schema.Literals(["invalid_options", "mark_failed", "sweep_failed"]);
+/**
+ * A collection that could not complete. `mark_failed` means the live set
+ * could not be computed — nothing was deleted. `sweep_failed` means the live
+ * set held but a deletion refused; everything already swept was garbage, so a
+ * re-run converges from wherever the failure stopped it.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class ArtifactGcError extends Schema.TaggedError()("@smthrs/engine-store/ArtifactGcError", {
+    code: ArtifactGcErrorCode,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown)
+}) {
+}
+/**
+ * Service tag for the opt-in collection policy.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class ArtifactGcPolicy extends Context.Service()("@smthrs/engine-store/ArtifactGcPolicy") {
+}
+/**
+ * Installs a collection policy.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerPolicy = (policy) => Layer.succeed(ArtifactGcPolicy)(policy);
+/**
+ * Service tag for artifact garbage collection.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class ArtifactGc extends Context.Service()("@smthrs/engine-store/ArtifactGc") {
+}
+/**
+ * Two weeks, git's `gc.pruneExpire` default. The bound is deliberately far
+ * beyond any live attempt's duration: a blob spilled by a running step is
+ * unreferenced until its attempt row finishes, and the grace period is the
+ * only thing protecting it in that window.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const defaultGraceMs = 14 * 24 * 60 * 60 * 1000;
+const markFailed = (message, cause) => new ArtifactGcError({ code: "mark_failed", message, cause });
+const sweepFailed = (message, cause) => new ArtifactGcError({ code: "sweep_failed", message, cause });
+const invalidOptions = (message) => new ArtifactGcError({ code: "invalid_options", message });
+/**
+ * Extracts the digests one root row keeps live, FAIL-SAFE: a row whose
+ * metadata carries a `boundary` this build cannot decode aborts the
+ * collection rather than contributing nothing. Silently reading such a row as
+ * "references no artifacts" is exactly how a live blob gets collected; a
+ * metadata shape with no `boundary` key at all is the ordinary
+ * foreign-evidence case `referencedDigests` already defines as empty.
+ */
+const rootDigests = (table, metaJson) => ArtifactRoots.rootDigests(table, metaJson).pipe(Effect.mapError((cause) => markFailed(cause.message, cause.cause)));
+const checkpointDigests = (checkpointJson) => ArtifactRoots.checkpointDigests(checkpointJson).pipe(Effect.mapError((cause) => markFailed(cause.message, cause.cause)));
+/**
+ * Builds the collector over the composition's own durable tables and the
+ * host-local sweep surface.
+ *
+ * The mark phase reads `flows_step_cache` and `flows_attempts` directly, the
+ * same way `DurableEngineState` range-scans `flows_runs`: this package
+ * composes every one of those migrations, so the schema is its own. Every run
+ * present in `flows_runs` is a live root — there is no deleted state, and the
+ * attempt table's foreign key guarantees each attempt's run exists — so the
+ * scan is simply *all* attempt rows plus *all* cache entries, paged by
+ * primary key so no page holds more than `pageSize` rows in memory.
+ *
+ * Ordering is the safety argument. The live set is computed BEFORE the
+ * inventory, so a root recorded during the sweep can only be missed, never
+ * half-seen — and the blob such a root references is protected anyway: a
+ * fresh publication carries a fresh mtime, a re-publication of existing bytes
+ * freshens the blob's mtime (`ArtifactStore.put`), and the sweep's deletion
+ * is fenced on that mtime (`ArtifactSweep.remove`'s `ifUnmodifiedSinceMs`).
+ * A crash mid-sweep deletes some garbage and no live blobs; re-running
+ * converges.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (options = {}) => Effect.gen(function* () {
+    const sql = yield* Effect.service(SqlClient.SqlClient);
+    const sweeper = yield* ArtifactSweep.ArtifactSweep;
+    const policy = yield* Effect.serviceOption(ArtifactGcPolicy);
+    const pageSize = options.pageSize ?? 500;
+    const markCacheEntries = (live) => Effect.gen(function* () {
+        let after = "";
+        for (;;) {
+            const rows = yield* sql `
+            SELECT key_digest, meta_json FROM flows_step_cache
+            WHERE key_digest > ${after}
+            ORDER BY key_digest
+            LIMIT ${pageSize}
+          `.pipe(Effect.mapError((cause) => markFailed("the step cache could not be scanned", cause)));
+            for (const row of rows) {
+                for (const digest of yield* rootDigests("flows_step_cache", row.meta_json)) {
+                    live.add(digest);
+                }
+            }
+            if (rows.length < pageSize)
+                return;
+            after = rows[rows.length - 1].key_digest;
+        }
+    });
+    const markAttempts = (live) => Effect.gen(function* () {
+        let after = { runId: "", stepKeyDigest: "", attempt: -1 };
+        for (;;) {
+            const rows = yield* sql `
+            SELECT run_id, step_key_digest, attempt, checkpoint_json, meta_json FROM flows_attempts
+            WHERE (run_id, step_key_digest, attempt) > (${after.runId}, ${after.stepKeyDigest}, ${after.attempt})
+            ORDER BY run_id, step_key_digest, attempt
+            LIMIT ${pageSize}
+          `.pipe(Effect.mapError((cause) => markFailed("the attempt table could not be scanned", cause)));
+            for (const row of rows) {
+                for (const digest of yield* rootDigests("flows_attempts", row.meta_json)) {
+                    live.add(digest);
+                }
+                for (const digest of yield* checkpointDigests(row.checkpoint_json)) {
+                    live.add(digest);
+                }
+            }
+            if (rows.length < pageSize)
+                return;
+            const last = rows[rows.length - 1];
+            after = { runId: last.run_id, stepKeyDigest: last.step_key_digest, attempt: last.attempt };
+        }
+    });
+    const gc = Effect.fn("ArtifactGc.gc")((gcOptions) => Effect.gen(function* () {
+        if (!Number.isSafeInteger(pageSize) || pageSize < 1) {
+            return yield* Effect.fail(invalidOptions("artifact GC pageSize must be a positive safe integer"));
+        }
+        const grace = gcOptions?.graceMs ??
+            (Option.isSome(policy) ? policy.value.graceMs : undefined) ??
+            defaultGraceMs;
+        if (!Number.isSafeInteger(grace) || grace < 0) {
+            return yield* Effect.fail(invalidOptions("artifact GC graceMs must be a non-negative safe integer"));
+        }
+        const startedAtMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor));
+        const bound = startedAtMs - grace;
+        const live = new Set(gcOptions?.pins ?? []);
+        if (Option.isSome(policy) && policy.value.pins !== undefined) {
+            for (const digest of yield* policy.value.pins)
+                live.add(digest);
+        }
+        yield* markCacheEntries(live);
+        yield* markAttempts(live);
+        const blobs = yield* sweeper.inventory.pipe(Effect.mapError((cause) => sweepFailed(`the blob inventory refused: ${cause.message}`, cause)));
+        const swept = [];
+        let reclaimedBytes = 0;
+        let keptByGrace = 0;
+        for (const blob of blobs) {
+            if (live.has(blob.digest))
+                continue;
+            if (blob.modifiedAtMs >= bound) {
+                keptByGrace++;
+                continue;
+            }
+            if (gcOptions?.dryRun === true) {
+                swept.push(blob.digest);
+                reclaimedBytes += blob.sizeBytes;
+                continue;
+            }
+            // The fence re-reads the blob's age inside the deletion: an
+            // unreferenced-at-mark blob a concurrent `put` freshened since the
+            // inventory fails the fence and is retained, exactly as a fresher
+            // cache row survives a laggard's fenced evict (issue #119).
+            // remove's fence is inclusive; mtimes have millisecond resolution,
+            // so exclude cutoff equality there just as in the inventory check.
+            const removed = yield* sweeper.remove(blob.digest, { ifUnmodifiedSinceMs: bound - 1 }).pipe(Effect.mapError((cause) => sweepFailed(`sweeping ${blob.digest} refused: ${cause.message}`, cause)));
+            if (removed) {
+                swept.push(blob.digest);
+                reclaimedBytes += blob.sizeBytes;
+            }
+            else {
+                keptByGrace++;
+            }
+        }
+        return {
+            scannedBlobs: blobs.length,
+            liveDigests: live.size,
+            sweptDigests: swept,
+            reclaimedBytes,
+            keptByGrace,
+            dryRun: gcOptions?.dryRun === true
+        };
+    }));
+    return { gc };
+});
+/**
+ * Provides the artifact garbage collector. Install {@link layerPolicy} into
+ * this layer's inputs to configure collection; nothing schedules `gc()` —
+ * invoking it stays an explicit caller decision.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (options = {}) => Layer.effect(ArtifactGc)(make(options));
+/**
+ * Provides the artifact garbage collector over a filesystem objects directory:
+ * {@link layer} with `ArtifactSweep.layerFileSystem` beneath it. Pass the same
+ * `directory` and `coordination` the paired `ArtifactStore.layerFileSystem`
+ * publishes with.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerFileSystem = (options = {}) => layer(options).pipe(Layer.provide(ArtifactSweep.layerFileSystem({ directory: options.directory, coordination: options.coordination })));
+//# sourceMappingURL=ArtifactGc.js.map

package/dist/esm/ArtifactGc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactGc.js","sourceRoot":"","sources":["../../src/ArtifactGc.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Mark/sweep garbage collection for the content-addressed artifact store.\n *\n * The artifact tier is the one store in the composition with true *garbage*:\n * every output over the inline bound is spilled to `.flows/objects` by digest\n * (`StepBoundary`), nothing ever deletes a published blob, and a blob whose\n * every referencing row is gone is unreachable forever. The step cache is\n * deliberately NOT collected here — its rows are the *roots* of this graph,\n * they never become unreachable, and removing one is the policy decision\n * `CacheStore.evict` already serves.\n *\n * The design combines the two prior arts on the shelf:\n *\n * - **Reachability from durable roots** — git's `git gc` marks from refs;\n *   Skyframe deletes what a keyed graph walk cannot reach. Here the roots are\n *   every attempt row of every existing (never-deleted) run and every step\n *   cache entry; each carries boundary evidence, and\n *   `StepBoundary.referencedDigests` names the blobs that evidence needs.\n *   Attempt checkpoints are roots too: they are opaque executable state, so\n *   the mark keeps digest-shaped strings found in their JSON.\n * - **A grace period over mtime** — git refuses to prune unreachable objects\n *   younger than `gc.pruneExpire` (two weeks), jj keeps operations newer than\n *   its keep bound, and Bazel's disk-cache collector\n *   (`reference/bazel/.../remote/disk/DiskCacheGarbageCollector.java`) fences\n *   on mtime. The cutoff is the collection start time minus the grace period,\n *   sampled before resolving policy pins or scanning roots and held fixed\n *   through inventory and deletion. Only mtimes strictly before it are\n *   eligible: a blob published — or freshened by a dedupe `put` — at or after\n *   collection start survives, including same-millisecond writes at zero\n *   grace, no lock required.\n *\n * Collection NEVER runs automatically. `gc()` is an explicit verb because\n * deletion is irreversible, and a human approving a plan must approve the\n * deletions too. The opt-in {@link ArtifactGcPolicy} layer\n * configures *how* an invocation collects (grace bound, pinned digests); it\n * does not schedule anything.\n *\n * @since 0.1.0\n */\n\nimport * as ArtifactSweep from \"@smthrs/artifacts/ArtifactSweep\"\nimport * as Clock from \"effect/Clock\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport * as Layer from \"effect/Layer\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport * as SqlClient from \"effect/unstable/sql/SqlClient\"\nimport * as ArtifactRoots from \"./internal/ArtifactRoots.ts\"\n\n/**\n * Stable error codes returned by artifact garbage collection.\n *\n * @category models\n * @since 0.1.0\n */\nexport const ArtifactGcErrorCode = Schema.Literals([\"invalid_options\", \"mark_failed\", \"sweep_failed\"])\n\n/**\n * Stable error codes returned by artifact garbage collection.\n *\n * @category models\n * @since 0.1.0\n */\nexport type ArtifactGcErrorCode = typeof ArtifactGcErrorCode.Type\n\n/**\n * A collection that could not complete. `mark_failed` means the live set\n * could not be computed — nothing was deleted. `sweep_failed` means the live\n * set held but a deletion refused; everything already swept was garbage, so a\n * re-run converges from wherever the failure stopped it.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class ArtifactGcError extends Schema.TaggedError<ArtifactGcError>()(\n  \"@smthrs/engine-store/ArtifactGcError\",\n  {\n    code: ArtifactGcErrorCode,\n    message: Schema.String,\n    cause: Schema.optional(Schema.Unknown)\n  }\n) {}\n\n/**\n * The opt-in collection policy. Explicit {@link GcOptions} on a `gc()` call\n * override the installed policy; the policy overrides the defaults.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Policy {\n  /** Grace bound applied when a `gc()` call does not name one. */\n  readonly graceMs?: number | undefined\n  /**\n   * Digests held live regardless of reachability — the seam for references\n   * this composition's tables cannot see (an external index, an export a\n   * human wants kept). Resolved fresh on every collection.\n   */\n  readonly pins?: Effect.Effect<ReadonlyArray<string>> | undefined\n}\n\n/**\n * Service tag for the opt-in collection policy.\n *\n * @category services\n * @since 0.1.0\n */\nexport class ArtifactGcPolicy extends Context.Service<ArtifactGcPolicy, Policy>()(\n  \"@smthrs/engine-store/ArtifactGcPolicy\"\n) {}\n\n/**\n * Installs a collection policy.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerPolicy = (policy: Policy): Layer.Layer<ArtifactGcPolicy> => Layer.succeed(ArtifactGcPolicy)(policy)\n\n/**\n * Options for one explicit collection.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface GcOptions {\n  /**\n   * How recently a blob must have been written or freshened to survive\n   * unreferenced. Defaults to the installed {@link ArtifactGcPolicy}'s bound,\n   * then to {@link defaultGraceMs}.\n   */\n  readonly graceMs?: number | undefined\n  /** Digests held live for this collection, unioned with the policy's pins. */\n  readonly pins?: ReadonlyArray<string> | undefined\n  /** Compute and report without deleting anything. */\n  readonly dryRun?: boolean | undefined\n}\n\n/**\n * What one collection did.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface GcReport {\n  /** Blobs the inventory enumerated. */\n  readonly scannedBlobs: number\n  /** Distinct digests the mark phase proved live, pins included. */\n  readonly liveDigests: number\n  /** Digests deleted — or, under `dryRun`, the ones a real run would delete. */\n  readonly sweptDigests: ReadonlyArray<string>\n  /** Bytes the swept blobs held. */\n  readonly reclaimedBytes: number\n  /** Unreferenced blobs retained by the grace bound or a freshen race. */\n  readonly keptByGrace: number\n  readonly dryRun: boolean\n}\n\n/**\n * Explicit artifact garbage collection.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  /**\n   * Marks the live set from the durable roots, then sweeps every blob that\n   * is both outside it and older than the grace bound. Explicit only —\n   * nothing in the engine composition ever calls this.\n   */\n  readonly gc: (options?: GcOptions) => Effect.Effect<GcReport, ArtifactGcError>\n}\n\n/**\n * Service tag for artifact garbage collection.\n *\n * @category services\n * @since 0.1.0\n */\nexport class ArtifactGc extends Context.Service<ArtifactGc, Service>()(\"@smthrs/engine-store/ArtifactGc\") {}\n\n/**\n * Two weeks, git's `gc.pruneExpire` default. The bound is deliberately far\n * beyond any live attempt's duration: a blob spilled by a running step is\n * unreferenced until its attempt row finishes, and the grace period is the\n * only thing protecting it in that window.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const defaultGraceMs = 14 * 24 * 60 * 60 * 1000\n\n/**\n * Construction options.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface MakeOptions {\n  /** Rows per mark-phase page. Defaults to 500. */\n  readonly pageSize?: number | undefined\n}\n\nconst markFailed = (message: string, cause: unknown): ArtifactGcError =>\n  new ArtifactGcError({ code: \"mark_failed\", message, cause })\n\nconst sweepFailed = (message: string, cause: unknown): ArtifactGcError =>\n  new ArtifactGcError({ code: \"sweep_failed\", message, cause })\n\nconst invalidOptions = (message: string): ArtifactGcError => new ArtifactGcError({ code: \"invalid_options\", message })\n\n/**\n * Extracts the digests one root row keeps live, FAIL-SAFE: a row whose\n * metadata carries a `boundary` this build cannot decode aborts the\n * collection rather than contributing nothing. Silently reading such a row as\n * \"references no artifacts\" is exactly how a live blob gets collected; a\n * metadata shape with no `boundary` key at all is the ordinary\n * foreign-evidence case `referencedDigests` already defines as empty.\n */\nconst rootDigests = (table: string, metaJson: string): Effect.Effect<ReadonlyArray<string>, ArtifactGcError> =>\n  ArtifactRoots.rootDigests(table, metaJson).pipe(\n    Effect.mapError((cause) => markFailed(cause.message, cause.cause))\n  )\n\nconst checkpointDigests = (checkpointJson: string | null): Effect.Effect<ReadonlyArray<string>, ArtifactGcError> =>\n  ArtifactRoots.checkpointDigests(checkpointJson).pipe(\n    Effect.mapError((cause) => markFailed(cause.message, cause.cause))\n  )\n\n/**\n * Builds the collector over the composition's own durable tables and the\n * host-local sweep surface.\n *\n * The mark phase reads `flows_step_cache` and `flows_attempts` directly, the\n * same way `DurableEngineState` range-scans `flows_runs`: this package\n * composes every one of those migrations, so the schema is its own. Every run\n * present in `flows_runs` is a live root — there is no deleted state, and the\n * attempt table's foreign key guarantees each attempt's run exists — so the\n * scan is simply *all* attempt rows plus *all* cache entries, paged by\n * primary key so no page holds more than `pageSize` rows in memory.\n *\n * Ordering is the safety argument. The live set is computed BEFORE the\n * inventory, so a root recorded during the sweep can only be missed, never\n * half-seen — and the blob such a root references is protected anyway: a\n * fresh publication carries a fresh mtime, a re-publication of existing bytes\n * freshens the blob's mtime (`ArtifactStore.put`), and the sweep's deletion\n * is fenced on that mtime (`ArtifactSweep.remove`'s `ifUnmodifiedSinceMs`).\n * A crash mid-sweep deletes some garbage and no live blobs; re-running\n * converges.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (\n  options: MakeOptions = {}\n): Effect.Effect<Service, never, SqlClient.SqlClient | ArtifactSweep.ArtifactSweep> =>\n  Effect.gen(function*() {\n    const sql = yield* Effect.service(SqlClient.SqlClient)\n    const sweeper = yield* ArtifactSweep.ArtifactSweep\n    const policy = yield* Effect.serviceOption(ArtifactGcPolicy)\n    const pageSize = options.pageSize ?? 500\n\n    const markCacheEntries = (live: Set<string>) =>\n      Effect.gen(function*() {\n        let after = \"\"\n        for (;;) {\n          const rows = yield* sql<{ readonly key_digest: string; readonly meta_json: string }>`\n            SELECT key_digest, meta_json FROM flows_step_cache\n            WHERE key_digest > ${after}\n            ORDER BY key_digest\n            LIMIT ${pageSize}\n          `.pipe(Effect.mapError((cause) => markFailed(\"the step cache could not be scanned\", cause)))\n          for (const row of rows) {\n            for (const digest of yield* rootDigests(\"flows_step_cache\", row.meta_json)) {\n              live.add(digest)\n            }\n          }\n          if (rows.length < pageSize) return\n          after = rows[rows.length - 1]!.key_digest\n        }\n      })\n\n    const markAttempts = (live: Set<string>) =>\n      Effect.gen(function*() {\n        let after = { runId: \"\", stepKeyDigest: \"\", attempt: -1 }\n        for (;;) {\n          const rows = yield* sql<{\n            readonly run_id: string\n            readonly step_key_digest: string\n            readonly attempt: number\n            readonly checkpoint_json: string | null\n            readonly meta_json: string\n          }>`\n            SELECT run_id, step_key_digest, attempt, checkpoint_json, meta_json FROM flows_attempts\n            WHERE (run_id, step_key_digest, attempt) > (${after.runId}, ${after.stepKeyDigest}, ${after.attempt})\n            ORDER BY run_id, step_key_digest, attempt\n            LIMIT ${pageSize}\n          `.pipe(Effect.mapError((cause) => markFailed(\"the attempt table could not be scanned\", cause)))\n          for (const row of rows) {\n            for (const digest of yield* rootDigests(\"flows_attempts\", row.meta_json)) {\n              live.add(digest)\n            }\n            for (const digest of yield* checkpointDigests(row.checkpoint_json)) {\n              live.add(digest)\n            }\n          }\n          if (rows.length < pageSize) return\n          const last = rows[rows.length - 1]!\n          after = { runId: last.run_id, stepKeyDigest: last.step_key_digest, attempt: last.attempt }\n        }\n      })\n\n    const gc: Service[\"gc\"] = Effect.fn(\"ArtifactGc.gc\")((gcOptions) =>\n      Effect.gen(function*() {\n        if (!Number.isSafeInteger(pageSize) || pageSize < 1) {\n          return yield* Effect.fail(invalidOptions(\"artifact GC pageSize must be a positive safe integer\"))\n        }\n        const grace = gcOptions?.graceMs ??\n          (Option.isSome(policy) ? policy.value.graceMs : undefined) ??\n          defaultGraceMs\n        if (!Number.isSafeInteger(grace) || grace < 0) {\n          return yield* Effect.fail(invalidOptions(\"artifact GC graceMs must be a non-negative safe integer\"))\n        }\n        const startedAtMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor))\n        const bound = startedAtMs - grace\n        const live = new Set<string>(gcOptions?.pins ?? [])\n        if (Option.isSome(policy) && policy.value.pins !== undefined) {\n          for (const digest of yield* policy.value.pins) live.add(digest)\n        }\n        yield* markCacheEntries(live)\n        yield* markAttempts(live)\n        const blobs = yield* sweeper.inventory.pipe(\n          Effect.mapError((cause) => sweepFailed(`the blob inventory refused: ${cause.message}`, cause))\n        )\n        const swept: Array<string> = []\n        let reclaimedBytes = 0\n        let keptByGrace = 0\n        for (const blob of blobs) {\n          if (live.has(blob.digest)) continue\n          if (blob.modifiedAtMs >= bound) {\n            keptByGrace++\n            continue\n          }\n          if (gcOptions?.dryRun === true) {\n            swept.push(blob.digest)\n            reclaimedBytes += blob.sizeBytes\n            continue\n          }\n          // The fence re-reads the blob's age inside the deletion: an\n          // unreferenced-at-mark blob a concurrent `put` freshened since the\n          // inventory fails the fence and is retained, exactly as a fresher\n          // cache row survives a laggard's fenced evict (issue #119).\n          // remove's fence is inclusive; mtimes have millisecond resolution,\n          // so exclude cutoff equality there just as in the inventory check.\n          const removed = yield* sweeper.remove(blob.digest, { ifUnmodifiedSinceMs: bound - 1 }).pipe(\n            Effect.mapError((cause) => sweepFailed(`sweeping ${blob.digest} refused: ${cause.message}`, cause))\n          )\n          if (removed) {\n            swept.push(blob.digest)\n            reclaimedBytes += blob.sizeBytes\n          } else {\n            keptByGrace++\n          }\n        }\n        return {\n          scannedBlobs: blobs.length,\n          liveDigests: live.size,\n          sweptDigests: swept,\n          reclaimedBytes,\n          keptByGrace,\n          dryRun: gcOptions?.dryRun === true\n        }\n      })\n    )\n\n    return { gc }\n  })\n\n/**\n * Provides the artifact garbage collector. Install {@link layerPolicy} into\n * this layer's inputs to configure collection; nothing schedules `gc()` —\n * invoking it stays an explicit caller decision.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer = (\n  options: MakeOptions = {}\n): Layer.Layer<ArtifactGc, never, SqlClient.SqlClient | ArtifactSweep.ArtifactSweep> =>\n  Layer.effect(ArtifactGc)(make(options))\n\n/**\n * Provides the artifact garbage collector over a filesystem objects directory:\n * {@link layer} with `ArtifactSweep.layerFileSystem` beneath it. Pass the same\n * `directory` and `coordination` the paired `ArtifactStore.layerFileSystem`\n * publishes with.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerFileSystem = (\n  options: MakeOptions & ArtifactSweep.SweepOptions = {}\n): Layer.Layer<ArtifactGc, never, SqlClient.SqlClient | FileSystem.FileSystem> =>\n  layer(options).pipe(\n    Layer.provide(ArtifactSweep.layerFileSystem({ directory: options.directory, coordination: options.coordination }))\n  )\n"]}