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

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactStoreError.d.ts","sourceRoot":"","sources":["../../src/ArtifactStoreError.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,2HAMjC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;;;;;;AAEvE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,kBAAmB,SAAQ,uBAOvC;CAAG;;;;;AAEJ;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,oBAMpC;CAAG;;;;;;AAEJ;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,SAAQ,uBAOvC;CAAG"}

package/dist/esm/ArtifactStoreError.js

@@ -0,0 +1,77 @@
+/**
+ * The artifact store's typed failures: a refusal of the store itself, the
+ * typed miss, and a digest mismatch, with the stable codes a refusal carries.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { Sha256 } from "@smthrs/crypto";
+import * as Schema from "effect/Schema";
+/**
+ * Stable error codes returned by artifact store operations.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const ArtifactStoreErrorCode = Schema.Literals([
+    "digest_failed",
+    "invalid_configuration",
+    "invalid_digest",
+    "unavailable",
+    "transport_failed"
+]);
+/**
+ * A typed failure of the store itself: the host or crypto provider refused an
+ * operation, the remote tier refused a request, or the caller supplied invalid
+ * configuration or an invalid content address.
+ *
+ * Distinct from {@link ArtifactMissing} and {@link ArtifactCorruption} on
+ * purpose. A miss is an ordinary, expected outcome that a second tier may
+ * still satisfy; corruption is an integrity violation of the store's strongest
+ * invariant. `invalid_configuration` and `invalid_digest` are permanent;
+ * retryability of host, crypto, and transport failures depends on the cause.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export class ArtifactStoreError extends Schema.TaggedError()("@smthrs/artifacts/ArtifactStoreError", {
+    code: ArtifactStoreErrorCode,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown)
+}) {
+}
+/**
+ * The typed miss: this tier holds no bytes at the requested address.
+ *
+ * A miss is not a failure of the store — it is the answer a read-through
+ * composition is built to act on, so it is a distinct tag rather than an
+ * `unavailable` code that a caller would have to string-match.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export class ArtifactMissing extends Schema.TaggedError()("@smthrs/artifacts/ArtifactMissing", {
+    code: Schema.Literal("artifact_missing"),
+    digest: Sha256.Digest
+}) {
+}
+/**
+ * Bytes stored at a content address no longer hash to it.
+ *
+ * Every read is digest-verified, so a truncated blob left by a crashing writer
+ * or by disk corruption is refused rather than handed back as if it were the
+ * recorded artifact.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export class ArtifactCorruption extends Schema.TaggedError()("@smthrs/artifacts/ArtifactCorruption", {
+    code: Schema.Literal("artifact_corruption"),
+    recordedDigest: Sha256.Digest,
+    measuredDigest: Sha256.Digest
+}) {
+}
+//# sourceMappingURL=ArtifactStoreError.js.map

package/dist/esm/ArtifactStoreError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactStoreError.js","sourceRoot":"","sources":["../../src/ArtifactStoreError.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,QAAQ,CAAC;IACpD,eAAe;IACf,uBAAuB;IACvB,gBAAgB;IAChB,aAAa;IACb,kBAAkB;CACnB,CAAC,CAAA;AAWF;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,kBAAmB,SAAQ,MAAM,CAAC,WAAW,EAAsB,CAC9E,sCAAsC,EACtC;IACE,IAAI,EAAE,sBAAsB;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;CACvC,CACF;CAAG;AAEJ;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAgB,SAAQ,MAAM,CAAC,WAAW,EAAmB,CACxE,mCAAmC,EACnC;IACE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC,MAAM;CACtB,CACF;CAAG;AAEJ;;;;;;;;;;GAUG;AACH,MAAM,OAAO,kBAAmB,SAAQ,MAAM,CAAC,WAAW,EAAsB,CAC9E,sCAAsC,EACtC;IACE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC;IAC3C,cAAc,EAAE,MAAM,CAAC,MAAM;IAC7B,cAAc,EAAE,MAAM,CAAC,MAAM;CAC9B,CACF;CAAG","sourcesContent":["/**\n * The artifact store's typed failures: a refusal of the store itself, the\n * typed miss, and a digest mismatch, with the stable codes a refusal carries.\n *\n * @since 1.0.0-rc.0\n */\n\nimport { Sha256 } from \"@smthrs/crypto\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Stable error codes returned by artifact store operations.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const ArtifactStoreErrorCode = Schema.Literals([\n  \"digest_failed\",\n  \"invalid_configuration\",\n  \"invalid_digest\",\n  \"unavailable\",\n  \"transport_failed\"\n])\n\n/**\n * Stable error codes returned by artifact store operations.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport type ArtifactStoreErrorCode = typeof ArtifactStoreErrorCode.Type\n\n/**\n * A typed failure of the store itself: the host or crypto provider refused an\n * operation, the remote tier refused a request, or the caller supplied invalid\n * configuration or an invalid content address.\n *\n * Distinct from {@link ArtifactMissing} and {@link ArtifactCorruption} on\n * purpose. A miss is an ordinary, expected outcome that a second tier may\n * still satisfy; corruption is an integrity violation of the store's strongest\n * invariant. `invalid_configuration` and `invalid_digest` are permanent;\n * retryability of host, crypto, and transport failures depends on the cause.\n *\n * @category errors\n * @since 1.0.0-rc.0\n * @slop\n */\nexport class ArtifactStoreError extends Schema.TaggedError<ArtifactStoreError>()(\n  \"@smthrs/artifacts/ArtifactStoreError\",\n  {\n    code: ArtifactStoreErrorCode,\n    message: Schema.String,\n    cause: Schema.optional(Schema.Unknown)\n  }\n) {}\n\n/**\n * The typed miss: this tier holds no bytes at the requested address.\n *\n * A miss is not a failure of the store — it is the answer a read-through\n * composition is built to act on, so it is a distinct tag rather than an\n * `unavailable` code that a caller would have to string-match.\n *\n * @category errors\n * @since 1.0.0-rc.0\n * @slop\n */\nexport class ArtifactMissing extends Schema.TaggedError<ArtifactMissing>()(\n  \"@smthrs/artifacts/ArtifactMissing\",\n  {\n    code: Schema.Literal(\"artifact_missing\"),\n    digest: Sha256.Digest\n  }\n) {}\n\n/**\n * Bytes stored at a content address no longer hash to it.\n *\n * Every read is digest-verified, so a truncated blob left by a crashing writer\n * or by disk corruption is refused rather than handed back as if it were the\n * recorded artifact.\n *\n * @category errors\n * @since 1.0.0-rc.0\n * @slop\n */\nexport class ArtifactCorruption extends Schema.TaggedError<ArtifactCorruption>()(\n  \"@smthrs/artifacts/ArtifactCorruption\",\n  {\n    code: Schema.Literal(\"artifact_corruption\"),\n    recordedDigest: Sha256.Digest,\n    measuredDigest: Sha256.Digest\n  }\n) {}\n"]}

package/dist/esm/ArtifactStoreMetrics.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Standard metric definitions for content-addressed artifact storage.
+ *
+ * This module only defines the metric handles, following the shape of Effect's
+ * `ClusterMetrics`. No exporter ships in this package; provide one — for
+ * example `@smthrs/observability` — and these counters appear in it.
+ *
+ * Only the local `ArtifactStore` implementations, filesystem and memory, update
+ * them. `RemoteArtifacts` is deliberately uninstrumented, and the counters carry
+ * no tier attribute, so read them as *local artifact store traffic* rather than
+ * as artifact operations:
+ *
+ * - a `CombinedArtifacts` read the local tier serves counts one get;
+ * - a read the shared tier serves counts NO get, because no local store
+ *   answered it;
+ * - the write-back that materializes such a read counts a put, indistinguishable
+ *   from a producer publishing new bytes.
+ *
+ * Attributing operations per tier needs the tier in the metric, which would
+ * change the published counter shape; until then this is what the numbers mean.
+ *
+ * The one shared-tier signal is {@link remoteFailure}: a `CombinedArtifacts`
+ * upload or write-back that was refused, or abandoned at its deadline.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Metric from "effect/Metric";
+/**
+ * Counter over successful artifact puts. A put that deduplicated against an
+ * existing verified blob still counts: the caller stored bytes and received
+ * an address either way.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const puts: Metric.Counter<number>;
+/**
+ * Counter over successful artifact gets. Missing and corrupt reads fail with
+ * their typed errors and are deliberately not counted here; they are error
+ * evidence, not throughput.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const gets: Metric.Counter<number>;
+/**
+ * Counter over opportunistic `CombinedArtifacts` transfers that failed or hit
+ * their deadline and were dropped: `put`'s upload to the shared tier and
+ * `get`'s write-back into the local tier.
+ *
+ * Read the attributed views on {@link remoteFailure}: every update carries an
+ * `operation` attribute, so this bare handle aggregates nothing and always
+ * reads zero.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export declare const remoteFailures: Metric.Counter<number>;
+/**
+ * `remoteFailures` views keyed by the dropped transfer.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export declare const remoteFailure: {
+    readonly [Operation in "put" | "write_back"]: Metric.Metric<number, Metric.CounterState<number>>;
+};
+//# sourceMappingURL=ArtifactStoreMetrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactStoreMetrics.d.ts","sourceRoot":"","sources":["../../src/ArtifactStoreMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,wBAEf,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,wBAEf,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,wBAEzB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE;IAC1B,QAAQ,EAAE,SAAS,IAAI,KAAK,GAAG,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;CAIjG,CAAA"}

package/dist/esm/ArtifactStoreMetrics.js

@@ -0,0 +1,77 @@
+/**
+ * Standard metric definitions for content-addressed artifact storage.
+ *
+ * This module only defines the metric handles, following the shape of Effect's
+ * `ClusterMetrics`. No exporter ships in this package; provide one — for
+ * example `@smthrs/observability` — and these counters appear in it.
+ *
+ * Only the local `ArtifactStore` implementations, filesystem and memory, update
+ * them. `RemoteArtifacts` is deliberately uninstrumented, and the counters carry
+ * no tier attribute, so read them as *local artifact store traffic* rather than
+ * as artifact operations:
+ *
+ * - a `CombinedArtifacts` read the local tier serves counts one get;
+ * - a read the shared tier serves counts NO get, because no local store
+ *   answered it;
+ * - the write-back that materializes such a read counts a put, indistinguishable
+ *   from a producer publishing new bytes.
+ *
+ * Attributing operations per tier needs the tier in the metric, which would
+ * change the published counter shape; until then this is what the numbers mean.
+ *
+ * The one shared-tier signal is {@link remoteFailure}: a `CombinedArtifacts`
+ * upload or write-back that was refused, or abandoned at its deadline.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Metric from "effect/Metric";
+/**
+ * Counter over successful artifact puts. A put that deduplicated against an
+ * existing verified blob still counts: the caller stored bytes and received
+ * an address either way.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const puts = Metric.counter("flows_artifact_puts", {
+    description: "Successful artifact puts, including deduplicated ones"
+});
+/**
+ * Counter over successful artifact gets. Missing and corrupt reads fail with
+ * their typed errors and are deliberately not counted here; they are error
+ * evidence, not throughput.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const gets = Metric.counter("flows_artifact_gets", {
+    description: "Successful artifact gets"
+});
+/**
+ * Counter over opportunistic `CombinedArtifacts` transfers that failed or hit
+ * their deadline and were dropped: `put`'s upload to the shared tier and
+ * `get`'s write-back into the local tier.
+ *
+ * Read the attributed views on {@link remoteFailure}: every update carries an
+ * `operation` attribute, so this bare handle aggregates nothing and always
+ * reads zero.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export const remoteFailures = Metric.counter("flows_artifact_remote_failures", {
+    description: "Dropped combined-artifact transfers by operation"
+});
+/**
+ * `remoteFailures` views keyed by the dropped transfer.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export const remoteFailure = {
+    put: Metric.withAttributes(remoteFailures, { operation: "put" }),
+    write_back: Metric.withAttributes(remoteFailures, { operation: "write_back" })
+};
+//# sourceMappingURL=ArtifactStoreMetrics.js.map

package/dist/esm/ArtifactStoreMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactStoreMetrics.js","sourceRoot":"","sources":["../../src/ArtifactStoreMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE;IACxD,WAAW,EAAE,uDAAuD;CACrE,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE;IACxD,WAAW,EAAE,0BAA0B;CACxC,CAAC,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,gCAAgC,EAAE;IAC7E,WAAW,EAAE,kDAAkD;CAChE,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAEtB;IACF,GAAG,EAAE,MAAM,CAAC,cAAc,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAChE,UAAU,EAAE,MAAM,CAAC,cAAc,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;CAC/E,CAAA","sourcesContent":["/**\n * Standard metric definitions for content-addressed artifact storage.\n *\n * This module only defines the metric handles, following the shape of Effect's\n * `ClusterMetrics`. No exporter ships in this package; provide one — for\n * example `@smthrs/observability` — and these counters appear in it.\n *\n * Only the local `ArtifactStore` implementations, filesystem and memory, update\n * them. `RemoteArtifacts` is deliberately uninstrumented, and the counters carry\n * no tier attribute, so read them as *local artifact store traffic* rather than\n * as artifact operations:\n *\n * - a `CombinedArtifacts` read the local tier serves counts one get;\n * - a read the shared tier serves counts NO get, because no local store\n *   answered it;\n * - the write-back that materializes such a read counts a put, indistinguishable\n *   from a producer publishing new bytes.\n *\n * Attributing operations per tier needs the tier in the metric, which would\n * change the published counter shape; until then this is what the numbers mean.\n *\n * The one shared-tier signal is {@link remoteFailure}: a `CombinedArtifacts`\n * upload or write-back that was refused, or abandoned at its deadline.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Metric from \"effect/Metric\"\n\n/**\n * Counter over successful artifact puts. A put that deduplicated against an\n * existing verified blob still counts: the caller stored bytes and received\n * an address either way.\n *\n * @category metrics\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const puts = Metric.counter(\"flows_artifact_puts\", {\n  description: \"Successful artifact puts, including deduplicated ones\"\n})\n\n/**\n * Counter over successful artifact gets. Missing and corrupt reads fail with\n * their typed errors and are deliberately not counted here; they are error\n * evidence, not throughput.\n *\n * @category metrics\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const gets = Metric.counter(\"flows_artifact_gets\", {\n  description: \"Successful artifact gets\"\n})\n\n/**\n * Counter over opportunistic `CombinedArtifacts` transfers that failed or hit\n * their deadline and were dropped: `put`'s upload to the shared tier and\n * `get`'s write-back into the local tier.\n *\n * Read the attributed views on {@link remoteFailure}: every update carries an\n * `operation` attribute, so this bare handle aggregates nothing and always\n * reads zero.\n *\n * @category metrics\n * @since 1.0.0-rc.1\n */\nexport const remoteFailures = Metric.counter(\"flows_artifact_remote_failures\", {\n  description: \"Dropped combined-artifact transfers by operation\"\n})\n\n/**\n * `remoteFailures` views keyed by the dropped transfer.\n *\n * @category metrics\n * @since 1.0.0-rc.1\n */\nexport const remoteFailure: {\n  readonly [Operation in \"put\" | \"write_back\"]: Metric.Metric<number, Metric.CounterState<number>>\n} = {\n  put: Metric.withAttributes(remoteFailures, { operation: \"put\" }),\n  write_back: Metric.withAttributes(remoteFailures, { operation: \"write_back\" })\n}\n"]}

package/dist/esm/ArtifactSweep.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The sweep half of artifact garbage collection: enumerate this host's blobs
+ * and delete one, fenced by its age.
+ *
+ * This surface is deliberately NOT part of `ArtifactStore.Service`. The store
+ * contract is shared by memory, filesystem, and network tiers, and a remote
+ * tier can neither enumerate its address space nor accept a delete — Bazel
+ * draws the same line: its disk-cache collector
+ * (class `DiskCacheGarbageCollector` in
+ * `com.google.devtools.build.lib.remote.disk`) walks the local directory, while
+ * the remote tier owns its own retention. Only the
+ * host-local filesystem store implements this.
+ *
+ * The *policy* — which digests are live, how old a dead blob must be before it
+ * goes — belongs to the engine composition, which is the only place the
+ * durable roots (attempt rows, cache entries) are visible. This module ships
+ * mechanics alone; `@smthrs/engine-store` owns the mark policy and grace
+ * period.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as ArtifactStore from "./ArtifactStore.ts";
+/**
+ * One enumerated blob: its content address, when it was last written or
+ * freshened, and its size.
+ *
+ * `modifiedAtMs` is the age evidence a sweep fences on — the same signal git
+ * (`git prune --expire`) and Bazel's disk-cache collector read, because it is
+ * the one timestamp a filesystem maintains without any bookkeeping of ours.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export interface BlobStat {
+    readonly digest: string;
+    readonly modifiedAtMs: number;
+    readonly sizeBytes: number;
+}
+/**
+ * Fencing predicate for a sweep deletion.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export interface RemoveOptions {
+    /**
+     * Deletes the blob only while its mtime is still at or before this bound.
+     * A blob freshened after the caller computed its live set — a concurrent
+     * `put` re-referencing the same bytes — fails the fence and survives, the
+     * same shape as `CacheStore.evict`'s `ifRecordedBy`: the guard rides in the
+     * delete, never in a prior read alone.
+     */
+    readonly ifUnmodifiedSinceMs?: number | undefined;
+}
+/**
+ * Host-local blob enumeration and fenced deletion.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export interface Service {
+    /**
+     * Every content-addressed blob this host's store currently holds. In-flight
+     * `.tmp-*` scratch files, foreign files, and blobs whose age cannot be
+     * measured are excluded — what the sweep cannot judge it must not touch.
+     */
+    readonly inventory: Effect.Effect<Array<BlobStat>, ArtifactStore.ArtifactStoreError>;
+    /**
+     * Deletes the blob at `digest`, returning whether bytes were removed. A
+     * missing blob reports `false` rather than failing, so a crashed and
+     * re-run sweep converges instead of erroring on its own progress.
+     *
+     * `false` covers three outcomes a caller cannot tell apart, all of which mean
+     * "nothing was reclaimed, and retrying later is safe": the blob was already
+     * gone, it failed the `ifUnmodifiedSinceMs` fence, or a live backup lease
+     * fenced the deletion (see `ArtifactBackupLease`). The last one is not
+     * progress — the blob is still there — so a collector that counts reclaimed
+     * bytes must not count it, and the next pass after the backup finishes
+     * removes it.
+     */
+    readonly remove: (digest: string, options?: RemoveOptions) => Effect.Effect<boolean, ArtifactStore.ArtifactStoreError>;
+}
+declare const ArtifactSweep_base: Context.ServiceClass<ArtifactSweep, "@smthrs/artifacts/ArtifactSweep", Service>;
+/**
+ * Service tag for host-local artifact sweeping.
+ *
+ * The identity string equals this module's package path, per the house rule
+ * that a new identity is the defining module path.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare class ArtifactSweep extends ArtifactSweep_base {
+}
+/**
+ * How the sweep reaches the objects directory.
+ *
+ * Deliberately not `ArtifactStore.FileSystemOptions`: the sweep never writes a
+ * blob, so `durability` would be an accepted argument it ignores. Both fields
+ * must match the store built over the same directory — see `coordination`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface SweepOptions {
+    /**
+     * The objects directory to enumerate, the one the paired
+     * `ArtifactStore.makeFileSystem` publishes into. Defaults to
+     * `ArtifactStore.defaultDirectory`.
+     */
+    readonly directory?: string | undefined;
+    /**
+     * `required` takes the same per-digest lock file a publishing writer takes,
+     * and consults the backup lease, before deleting. It fences nothing unless
+     * the paired store was built with `required` too: a store on `process` never
+     * takes the lock this sweep waits on, so the fence would read as armed while
+     * protecting nothing. `process` is the explicit weaker browser/test mode.
+     */
+    readonly coordination?: "required" | "process" | undefined;
+}
+/**
+ * Builds the filesystem-backed sweep surface over the same objects directory
+ * an `ArtifactStore.makeFileSystem` publishes into.
+ *
+ * Enumeration is conservative by construction. Only paths in the store's
+ * canonical fanout shape — `xx/<digest>` with `xx` equal to the digest's
+ * two-hex prefix — are blobs; anything else in the directory (a temp file, a
+ * lock file, a foreign file, a fanout directory itself) is skipped, never
+ * deleted. A blob that vanishes between listing and stat was removed by someone
+ * else and is likewise skipped.
+ *
+ * Pair it with the store over the SAME `directory` and the SAME `coordination`.
+ * Nothing checks the pairing, and a mismatch is silent: a sweep on `required`
+ * beside a store on `process` deletes blobs no writer is fenced against.
+ *
+ * Under `required`, one deletion costs two lock acquisitions — the per-digest
+ * lock, then the workspace-global backup-lease gate — which is roughly ten
+ * filesystem operations and two forked heartbeat fibers per blob. The gate is
+ * one file for the whole workspace, so concurrent deletions serialize through
+ * it. That is the price of never deleting a blob a running backup already
+ * recorded; size a collection window with it in mind.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const makeFileSystem: (fs: FileSystem.FileSystem, options?: SweepOptions) => Service;
+/**
+ * Provides the filesystem-backed sweep surface.
+ *
+ * Give it the same `directory` and `coordination` as the `ArtifactStore` layer
+ * it sweeps behind; see {@link makeFileSystem}.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const layerFileSystem: (options?: SweepOptions) => Layer.Layer<ArtifactSweep, never, FileSystem.FileSystem>;
+/**
+ * Builds a sweep surface whose every operation fails as unavailable, with
+ * per-method overrides.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides a no-op sweep surface.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<ArtifactSweep>;
+export {};
+//# sourceMappingURL=ArtifactSweep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactSweep.d.ts","sourceRoot":"","sources":["../../src/ArtifactSweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAIrC,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAInD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAClD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;IACpF;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,MAAM,EAAE,CACf,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,aAAa,KACpB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;CAC9D;;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,kBAA4E;CAAG;AAelH;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,CAAA;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,cAAc,GACzB,IAAI,UAAU,CAAC,UAAU,EACzB,UAAS,YAAiB,KACzB,OAiHF,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAS,YAAiB,KACzB,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAC2C,CAAA;AAErG;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,YAAW,OAAO,CAAC,OAAO,CAAM,KAAG,OAI1D,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,YAAW,OAAO,CAAC,OAAO,CAAM,KAAG,KAAK,CAAC,KAAK,CAAC,aAAa,CACnC,CAAA"}

package/dist/esm/ArtifactSweep.js

@@ -0,0 +1,202 @@
+/**
+ * The sweep half of artifact garbage collection: enumerate this host's blobs
+ * and delete one, fenced by its age.
+ *
+ * This surface is deliberately NOT part of `ArtifactStore.Service`. The store
+ * contract is shared by memory, filesystem, and network tiers, and a remote
+ * tier can neither enumerate its address space nor accept a delete — Bazel
+ * draws the same line: its disk-cache collector
+ * (class `DiskCacheGarbageCollector` in
+ * `com.google.devtools.build.lib.remote.disk`) walks the local directory, while
+ * the remote tier owns its own retention. Only the
+ * host-local filesystem store implements this.
+ *
+ * The *policy* — which digests are live, how old a dead blob must be before it
+ * goes — belongs to the engine composition, which is the only place the
+ * durable roots (attempt rows, cache entries) are visible. This module ships
+ * mechanics alone; `@smthrs/engine-store` owns the mark policy and grace
+ * period.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
+import * as ArtifactBackupLease from "./ArtifactBackupLease.js";
+import * as ArtifactStore from "./ArtifactStore.js";
+import * as ArtifactLocks from "./internal/ArtifactLocks.js";
+import * as ArtifactPath from "./internal/ArtifactPath.js";
+/**
+ * Service tag for host-local artifact sweeping.
+ *
+ * The identity string equals this module's package path, per the house rule
+ * that a new identity is the defining module path.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export class ArtifactSweep extends Context.Service()("@smthrs/artifacts/ArtifactSweep") {
+}
+const error = (message, cause) => new ArtifactStore.ArtifactStoreError({
+    code: "unavailable",
+    message,
+    ...(cause === undefined ? {} : { cause })
+});
+const hostFailure = (cause) => error(`the host filesystem refused a sweep operation: ${String(cause)}`, cause);
+const isNotFound = (cause) => cause instanceof PlatformError.PlatformError && cause.reason._tag === "NotFound";
+/**
+ * Builds the filesystem-backed sweep surface over the same objects directory
+ * an `ArtifactStore.makeFileSystem` publishes into.
+ *
+ * Enumeration is conservative by construction. Only paths in the store's
+ * canonical fanout shape — `xx/<digest>` with `xx` equal to the digest's
+ * two-hex prefix — are blobs; anything else in the directory (a temp file, a
+ * lock file, a foreign file, a fanout directory itself) is skipped, never
+ * deleted. A blob that vanishes between listing and stat was removed by someone
+ * else and is likewise skipped.
+ *
+ * Pair it with the store over the SAME `directory` and the SAME `coordination`.
+ * Nothing checks the pairing, and a mismatch is silent: a sweep on `required`
+ * beside a store on `process` deletes blobs no writer is fenced against.
+ *
+ * Under `required`, one deletion costs two lock acquisitions — the per-digest
+ * lock, then the workspace-global backup-lease gate — which is roughly ten
+ * filesystem operations and two forked heartbeat fibers per blob. The gate is
+ * one file for the whole workspace, so concurrent deletions serialize through
+ * it. That is the price of never deleting a blob a running backup already
+ * recorded; size a collection window with it in mind.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const makeFileSystem = (fs, options = {}) => {
+    const directory = (options.directory ?? ArtifactStore.defaultDirectory).replace(/([^/])\/+$/, "$1");
+    const coordination = options.coordination ?? "required";
+    const blobPath = (digest) => `${directory}/${digest.slice(0, 2)}/${digest}`;
+    const inventory = Effect.gen(function* () {
+        // A store that never published anything has no directory; that is an
+        // empty inventory, not a failure.
+        const checkRoot = yield* ArtifactPath.guard(fs, directory).pipe(Effect.mapError(hostFailure));
+        const parents = yield* fs.readDirectory(directory).pipe(Effect.catch((cause) => isNotFound(cause) ? Effect.succeed([]) : Effect.fail(hostFailure(cause))));
+        const entries = [];
+        for (const parent of parents) {
+            if (!/^[0-9a-f]{2}$/.test(parent))
+                continue;
+            yield* checkRoot.pipe(Effect.mapError(hostFailure));
+            const safe = yield* ArtifactPath.guard(fs, `${directory}/${parent}`).pipe(Effect.option);
+            if (Option.isNone(safe))
+                continue;
+            const children = yield* fs.readDirectory(`${directory}/${parent}`).pipe(Effect.orElseSucceed(() => []));
+            for (const child of children)
+                entries.push(`${parent}/${child}`);
+        }
+        const candidates = entries.filter((entry) => {
+            if (entry.includes(".tmp-"))
+                return false;
+            const separator = entry.indexOf("/");
+            const fan = entry.slice(0, separator);
+            const digest = entry.slice(separator + 1);
+            return /^[0-9a-f]{64}$/.test(digest) && fan === digest.slice(0, 2);
+        });
+        const blobs = yield* Effect.forEach(candidates, (entry) => Effect.gen(function* () {
+            const separator = entry.indexOf("/");
+            const fan = entry.slice(0, separator);
+            const digest = entry.slice(separator + 1);
+            // The stat is per-candidate and tolerant: a blob another process
+            // removed between the listing and here simply is not in the
+            // inventory, and one whose mtime the host cannot report offers no
+            // age evidence, so the sweep must never judge it.
+            const info = yield* Effect.gen(function* () {
+                yield* checkRoot;
+                yield* ArtifactPath.guard(fs, `${directory}/${fan}`);
+                yield* ArtifactPath.guard(fs, `${directory}/${entry}`, "File");
+                return yield* fs.stat(`${directory}/${entry}`);
+            }).pipe(Effect.option);
+            if (Option.isNone(info) || info.value.type !== "File")
+                return undefined;
+            const mtime = Option.getOrUndefined(info.value.mtime);
+            if (mtime === undefined)
+                return undefined;
+            return {
+                digest,
+                modifiedAtMs: mtime.getTime(),
+                sizeBytes: Number(info.value.size)
+            };
+        }), { concurrency: 16 });
+        return blobs.filter((blob) => blob !== undefined);
+    });
+    const remove = Effect.fn("ArtifactSweep.remove")((digest, removeOptions) => Effect.gen(function* () {
+        const validated = yield* ArtifactStore.validateDigest(digest);
+        yield* Effect.annotateCurrentSpan({ digest: validated });
+        const checkRoot = yield* ArtifactPath.guard(fs, directory).pipe(Effect.mapError(hostFailure));
+        const checkParent = yield* ArtifactPath.guard(fs, `${directory}/${validated.slice(0, 2)}`).pipe(Effect.mapError(hostFailure));
+        return yield* ArtifactLocks.withDigest(fs, directory, validated, coordination === "process"
+            ? removeBlob()
+            : ArtifactBackupLease.unlessActive(fs, directory, removeBlob(), hostFailure).pipe(Effect.map(Option.getOrElse(() => false))), hostFailure, coordination);
+        function removeBlob() {
+            return Effect.gen(function* () {
+                const path = blobPath(validated);
+                yield* checkRoot.pipe(Effect.mapError(hostFailure));
+                yield* checkParent.pipe(Effect.mapError(hostFailure));
+                const checkBlob = yield* ArtifactPath.guard(fs, path, "File").pipe(Effect.mapError(hostFailure));
+                const bound = removeOptions?.ifUnmodifiedSinceMs;
+                if (bound !== undefined) {
+                    const info = yield* fs.stat(path).pipe(Effect.option);
+                    // Already gone is a completed deletion, and an unmeasurable mtime is
+                    // no proof of age: both refuse rather than delete.
+                    if (Option.isNone(info))
+                        return false;
+                    const mtime = Option.getOrUndefined(info.value.mtime);
+                    if (mtime === undefined || mtime.getTime() > bound)
+                        return false;
+                }
+                yield* checkRoot.pipe(Effect.mapError(hostFailure));
+                yield* checkParent.pipe(Effect.mapError(hostFailure));
+                yield* checkBlob.pipe(Effect.mapError(hostFailure));
+                return yield* fs.remove(path).pipe(Effect.as(true), 
+                // The blob may have been removed between the fence and here; only a
+                // refusal over bytes that still exist is a host failure.
+                Effect.catch((cause) => fs.exists(path).pipe(Effect.mapError((probeCause) => hostFailure({ remove: cause, existenceProbe: probeCause })), Effect.flatMap((present) => present ? Effect.fail(hostFailure(cause)) : Effect.succeed(false)))));
+            });
+        }
+    }));
+    return { inventory, remove };
+};
+/**
+ * Provides the filesystem-backed sweep surface.
+ *
+ * Give it the same `directory` and `coordination` as the `ArtifactStore` layer
+ * it sweeps behind; see {@link makeFileSystem}.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const layerFileSystem = (options = {}) => Layer.effect(ArtifactSweep)(Effect.map(FileSystem.FileSystem, (fs) => makeFileSystem(fs, options)));
+/**
+ * Builds a sweep surface whose every operation fails as unavailable, with
+ * per-method overrides.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const makeNoop = (overrides = {}) => ({
+    inventory: Effect.fail(error("inventory is unavailable")),
+    remove: Effect.fn("ArtifactSweep.remove")(() => Effect.fail(error("remove is unavailable"))),
+    ...overrides
+});
+/**
+ * Provides a no-op sweep surface.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const layerNoop = (overrides = {}) => Layer.succeed(ArtifactSweep)(makeNoop(overrides));
+//# sourceMappingURL=ArtifactSweep.js.map