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

package/dist/esm/ArtifactStoreError.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 * as Schema from "effect/Schema";
+/**
+ * Stable error codes returned by artifact store operations.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const ArtifactStoreErrorCode: Schema.Literals<readonly ["digest_failed", "invalid_configuration", "invalid_digest", "unavailable", "transport_failed"]>;
+/**
+ * Stable error codes returned by artifact store operations.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export type ArtifactStoreErrorCode = typeof ArtifactStoreErrorCode.Type;
+declare const ArtifactStoreError_base: Schema.Class<ArtifactStoreError, Schema.TaggedStruct<"@smthrs/artifacts/ArtifactStoreError", {
+    readonly code: Schema.Literals<readonly ["digest_failed", "invalid_configuration", "invalid_digest", "unavailable", "transport_failed"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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 declare class ArtifactStoreError extends ArtifactStoreError_base {
+}
+declare const ArtifactMissing_base: Schema.Class<ArtifactMissing, Schema.TaggedStruct<"@smthrs/artifacts/ArtifactMissing", {
+    readonly code: Schema.Literal<"artifact_missing">;
+    readonly digest: Schema.brand<Schema.String, "@smthrs/crypto/Sha256/Digest">;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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 declare class ArtifactMissing extends ArtifactMissing_base {
+}
+declare const ArtifactCorruption_base: Schema.Class<ArtifactCorruption, Schema.TaggedStruct<"@smthrs/artifacts/ArtifactCorruption", {
+    readonly code: Schema.Literal<"artifact_corruption">;
+    readonly recordedDigest: Schema.brand<Schema.String, "@smthrs/crypto/Sha256/Digest">;
+    readonly measuredDigest: Schema.brand<Schema.String, "@smthrs/crypto/Sha256/Digest">;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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 declare class ArtifactCorruption extends ArtifactCorruption_base {
+}
+export {};
+//# sourceMappingURL=ArtifactStoreError.d.ts.map

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,OA2HF,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"}