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

package/dist/cjs/snapshotBytes.js

@@ -0,0 +1,41 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var snapshotBytes_exports = {};
+__export(snapshotBytes_exports, {
+  snapshotBytes: () => snapshotBytes
+});
+module.exports = __toCommonJS(snapshotBytes_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var import_ArtifactStoreError = require("./ArtifactStoreError.js");
+const snapshotFailure = (cause) => new import_ArtifactStoreError.ArtifactStoreError({ code: "unavailable", message: "the host could not copy the artifact bytes", cause });
+const snapshotBytes = (bytes) => Effect.try({
+  try: () => new Uint8Array(bytes),
+  catch: (cause) => snapshotFailure(cause)
+});
+//# sourceMappingURL=snapshotBytes.js.map

package/dist/cjs/snapshotBytes.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/snapshotBytes.ts"],
+  "sourcesContent": ["/**\n * Snapshotting caller-owned artifact bytes, so a caller that reuses its buffer\n * cannot change what is measured or stored.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport { ArtifactStoreError } from \"./ArtifactStoreError.ts\"\n\n/**\n * A refused byte copy is the host declining an allocation, not a crypto\n * failure: the Crypto service has not been consulted when this fires, so\n * reporting `digest_failed` would point an operator diagnosing memory pressure\n * at the wrong subsystem. The message is constant, and the buffer is never\n * attached.\n */\nconst snapshotFailure = (cause: unknown): ArtifactStoreError =>\n  new ArtifactStoreError({ code: \"unavailable\", message: \"the host could not copy the artifact bytes\", cause })\n\n/**\n * Copies a caller-owned buffer when the returned Effect begins.\n *\n * A host that refuses the copy \u2014 a detached buffer, an allocation past what the\n * runtime will give \u2014 fails as `unavailable`, the code for a host refusal.\n *\n * @category utilities\n * @since 1.0.0-rc.0\n */\nexport const snapshotBytes = (bytes: Uint8Array): Effect.Effect<Uint8Array, ArtifactStoreError> =>\n  Effect.try({\n    try: () => new Uint8Array(bytes),\n    catch: (cause) => snapshotFailure(cause)\n  })\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,aAAwB;AACxB,gCAAmC;AASnC,MAAM,kBAAkB,CAAC,UACvB,IAAI,6CAAmB,EAAE,MAAM,eAAe,SAAS,8CAA8C,MAAM,CAAC;AAWvG,MAAM,gBAAgB,CAAC,UAC5B,OAAO,IAAI;AAAA,EACT,KAAK,MAAM,IAAI,WAAW,KAAK;AAAA,EAC/B,OAAO,CAAC,UAAU,gBAAgB,KAAK;AACzC,CAAC;",
+  "names": []
+}

package/dist/cjs/validateDigest.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validating a content address before any implementation logs it or
+ * interpolates it into a path or URL.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import type { Digest } from "./ArtifactStore.ts";
+import { ArtifactStoreError } from "./ArtifactStoreError.ts";
+/**
+ * Refuses anything other than the canonical SHA-256 address representation.
+ *
+ * Every implementation validates before logging or interpolating an untrusted
+ * value into a path or URL. The failure text is constant and bounded, so even a
+ * hostile multi-megabyte value cannot be copied into logs or durable errors.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const validateDigest: (digest: string) => Effect.Effect<Digest, ArtifactStoreError>;
+//# sourceMappingURL=validateDigest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validateDigest.d.ts","sourceRoot":"","sources":["../../src/validateDigest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAQnF,CAAA"}

package/dist/cjs/validateDigest.js

@@ -0,0 +1,42 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var validateDigest_exports = {};
+__export(validateDigest_exports, {
+  validateDigest: () => validateDigest
+});
+module.exports = __toCommonJS(validateDigest_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var import_ArtifactStoreError = require("./ArtifactStoreError.js");
+const validateDigest = (digest) => typeof digest === "string" && /^[0-9a-f]{64}$/.test(digest) ? Effect.succeed(digest) : Effect.fail(
+  new import_ArtifactStoreError.ArtifactStoreError({
+    code: "invalid_digest",
+    message: "artifact digest must be exactly 64 lowercase hexadecimal characters"
+  })
+);
+//# sourceMappingURL=validateDigest.js.map

package/dist/cjs/validateDigest.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/validateDigest.ts"],
+  "sourcesContent": ["/**\n * Validating a content address before any implementation logs it or\n * interpolates it into a path or URL.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport type { Digest } from \"./ArtifactStore.ts\"\nimport { ArtifactStoreError } from \"./ArtifactStoreError.ts\"\n\n/**\n * Refuses anything other than the canonical SHA-256 address representation.\n *\n * Every implementation validates before logging or interpolating an untrusted\n * value into a path or URL. The failure text is constant and bounded, so even a\n * hostile multi-megabyte value cannot be copied into logs or durable errors.\n *\n * @category predicates\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const validateDigest = (digest: string): Effect.Effect<Digest, ArtifactStoreError> =>\n  typeof digest === \"string\" && /^[0-9a-f]{64}$/.test(digest)\n    ? Effect.succeed(digest as Digest)\n    : Effect.fail(\n      new ArtifactStoreError({\n        code: \"invalid_digest\",\n        message: \"artifact digest must be exactly 64 lowercase hexadecimal characters\"\n      })\n    )\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,aAAwB;AAExB,gCAAmC;AAa5B,MAAM,iBAAiB,CAAC,WAC7B,OAAO,WAAW,YAAY,iBAAiB,KAAK,MAAM,IACtD,OAAO,QAAQ,MAAgB,IAC/B,OAAO;AAAA,EACP,IAAI,6CAAmB;AAAA,IACrB,MAAM;AAAA,IACN,SAAS;AAAA,EACX,CAAC;AACH;",
+  "names": []
+}

package/dist/esm/ArtifactBackupLease.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cross-process exclusion between a filesystem artifact backup and garbage
+ * collection.
+ *
+ * A backup holds one heartbeat-backed marker for the duration of its database
+ * snapshot and blob copy. Sweep deletion checks that marker while holding the
+ * same short-lived global gate. Publication remains unconstrained: new blobs
+ * may appear during a backup, but a blob already referenced by the frozen
+ * database cannot disappear underneath it.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+/**
+ * Runs `effect` while sweep deletion is fenced across every process using
+ * this objects directory. A crashed holder is recovered after its heartbeat
+ * becomes stale.
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export declare const withLease: <A, E, R, E2>(fs: FileSystem.FileSystem, directory: string, effect: Effect.Effect<A, E, R>, failure: (cause: unknown) => E2) => Effect.Effect<A, E | E2, R>;
+/**
+ * Runs one sweep deletion only when no live backup lease exists. The marker
+ * check and `effect` share the global gate, closing the check/delete race.
+ * `None` means a backup deliberately fenced the operation.
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export declare const unlessActive: <A, E, R, E2>(fs: FileSystem.FileSystem, directory: string, effect: Effect.Effect<A, E, R>, failure: (cause: unknown) => E2) => Effect.Effect<Option.Option<A>, E | E2, R>;
+//# sourceMappingURL=ArtifactBackupLease.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactBackupLease.d.ts","sourceRoot":"","sources":["../../src/ArtifactBackupLease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAqDvC;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EACnC,IAAI,UAAU,CAAC,UAAU,EACzB,WAAW,MAAM,EACjB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,SAAS,CAAC,KAAK,EAAE,OAAO,KAAK,EAAE,KAC9B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAoHzB,CAAA;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EACtC,IAAI,UAAU,CAAC,UAAU,EACzB,WAAW,MAAM,EACjB,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC9B,SAAS,CAAC,KAAK,EAAE,OAAO,KAAK,EAAE,KAC9B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CASzC,CAAA"}

package/dist/esm/ArtifactBackupLease.js

@@ -0,0 +1,126 @@
+/**
+ * Cross-process exclusion between a filesystem artifact backup and garbage
+ * collection.
+ *
+ * A backup holds one heartbeat-backed marker for the duration of its database
+ * snapshot and blob copy. Sweep deletion checks that marker while holding the
+ * same short-lived global gate. Publication remains unconstrained: new blobs
+ * may appear during a backup, but a blob already referenced by the frozen
+ * database cannot disappear underneath it.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
+import * as Random from "effect/Random";
+import * as ArtifactLocks from "./internal/ArtifactLocks.js";
+const markerName = ".backup-lease";
+const gateName = ".backup-lease-gate";
+const heartbeatEvery = "10 seconds";
+const staleAfterMs = 60_000;
+const acquireWithin = "2 minutes";
+const retryEvery = "25 millis";
+const isReason = (cause, tag) => cause instanceof PlatformError.PlatformError && cause.reason._tag === tag;
+const token = Effect.gen(function* () {
+    const first = yield* Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true });
+    const second = yield* Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true });
+    return `${first.toString(36)}-${second.toString(36)}-${yield* Clock.currentTimeMillis}`;
+});
+const gate = (fs, directory, effect, failure) => ArtifactLocks.withDigest(fs, directory, gateName, effect, failure);
+const activeMarker = (fs, directory, failure) => Effect.gen(function* () {
+    const path = `${directory}/${markerName}`;
+    const info = yield* fs.stat(path).pipe(Effect.map(Option.some), Effect.catch((cause) => isReason(cause, "NotFound") ? Effect.succeed(Option.none()) : Effect.fail(failure(cause))));
+    if (Option.isNone(info))
+        return false;
+    const modified = Option.getOrUndefined(info.value.mtime);
+    const now = yield* Clock.currentTimeMillis;
+    if (modified === undefined || now - modified.getTime() <= staleAfterMs)
+        return true;
+    yield* fs.remove(path).pipe(Effect.catch((cause) => isReason(cause, "NotFound") ? Effect.void : Effect.fail(failure(cause))));
+    return false;
+});
+/**
+ * Runs `effect` while sweep deletion is fenced across every process using
+ * this objects directory. A crashed holder is recovered after its heartbeat
+ * becomes stale.
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export const withLease = (fs, directory, effect, failure) => Effect.gen(function* () {
+    const owner = yield* token;
+    const marker = `${directory}/${markerName}`;
+    yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError(failure));
+    let ownsMarker = false;
+    const acquire = Effect.gen(function* () {
+        while (true) {
+            const acquired = yield* gate(fs, directory, Effect.gen(function* () {
+                if (yield* activeMarker(fs, directory, failure))
+                    return false;
+                return yield* Effect.uninterruptible(fs.writeFileString(marker, owner, { flag: "wx", mode: 0o600 }).pipe(Effect.andThen(Effect.sync(() => {
+                    ownsMarker = true;
+                    return true;
+                })), Effect.catch((cause) => isReason(cause, "AlreadyExists") ? Effect.succeed(false) : Effect.fail(failure(cause)))));
+            }), failure);
+            if (acquired)
+                return;
+            yield* Effect.sleep(retryEvery);
+        }
+    }).pipe(Effect.timeout(acquireWithin), Effect.catchTag("TimeoutError", (cause) => Effect.fail(failure(cause))));
+    // Install marker cleanup before acquisition, including gate release. The
+    // marker write and ownership bookkeeping complete in one interruption mask.
+    return yield* Effect.acquireUseRelease(Effect.void, () => acquire.pipe(Effect.andThen(Effect.scoped(Effect.gen(function* () {
+        yield* Effect.forkScoped(Effect.gen(function* () {
+            while (true) {
+                yield* Effect.sleep(heartbeatEvery);
+                const reclaimed = yield* gate(fs, directory, fs.readFileString(marker).pipe(Effect.map(Option.some), Effect.catch((cause) => isReason(cause, "NotFound") ? Effect.succeed(Option.none()) : Effect.fail(cause)), Effect.flatMap((found) => {
+                    // A missing or foreign marker means a sweep judged this
+                    // lease stale and reaped it: deletion is no longer
+                    // fenced while the backup still copies. The sibling
+                    // `internal/ArtifactLocks.ts` heartbeat reports the same
+                    // loss the same way. A reaped marker is never handed
+                    // back, so the loss is reported once and the heartbeat
+                    // ends instead of repeating it every tick.
+                    if (Option.getOrUndefined(found) !== owner) {
+                        return Effect.as(Effect.logWarning("Artifact backup lease was reclaimed while its backup was still running"), true);
+                    }
+                    return Effect.flatMap(Clock.currentTimeMillis, (now) => {
+                        const timestamp = new Date(now);
+                        return Effect.as(fs.utimes(marker, timestamp, timestamp), false);
+                    });
+                }), Effect.mapError(failure)), failure).pipe(
+                // A failed heartbeat is retried on the next tick, but a
+                // minute of them lets the marker go stale, so each one is
+                // reported rather than dropped.
+                Effect.catch((cause) => Effect.as(Effect.logWarning("Artifact backup lease heartbeat failed", cause), false)));
+                if (reclaimed)
+                    return;
+            }
+        }));
+        return yield* effect;
+    })))), () => ownsMarker
+        ? gate(fs, directory, fs.readFileString(marker).pipe(Effect.flatMap((found) => found === owner ? fs.remove(marker) : Effect.void), 
+        // A backup whose heartbeat lapsed has its marker reaped by whoever
+        // noticed, so `NotFound` is the ordinary end of a slow lease, not a
+        // fault: there is nothing left to release and nothing left to leak.
+        // The sibling release in `internal/ArtifactLocks.ts` classifies the
+        // same cause the same way.
+        Effect.catch((cause) => isReason(cause, "NotFound") ? Effect.void : Effect.fail(cause))), failure).pipe(Effect.catch((cause) => Effect.logWarning("Artifact backup lease release failed", cause)))
+        : Effect.void);
+});
+/**
+ * Runs one sweep deletion only when no live backup lease exists. The marker
+ * check and `effect` share the global gate, closing the check/delete race.
+ * `None` means a backup deliberately fenced the operation.
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export const unlessActive = (fs, directory, effect, failure) => gate(fs, directory, Effect.gen(function* () {
+    if (yield* activeMarker(fs, directory, failure))
+        return Option.none();
+    return Option.some(yield* effect);
+}), failure);
+//# sourceMappingURL=ArtifactBackupLease.js.map

package/dist/esm/ArtifactBackupLease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactBackupLease.js","sourceRoot":"","sources":["../../src/ArtifactBackupLease.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cross-process exclusion between a filesystem artifact backup and garbage\n * collection.\n *\n * A backup holds one heartbeat-backed marker for the duration of its database\n * snapshot and blob copy. Sweep deletion checks that marker while holding the\n * same short-lived global gate. Publication remains unconstrained: new blobs\n * may appear during a backup, but a blob already referenced by the frozen\n * database cannot disappear underneath it.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport * as Effect from \"effect/Effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport * as Option from \"effect/Option\"\nimport * as PlatformError from \"effect/PlatformError\"\nimport * as Random from \"effect/Random\"\nimport * as ArtifactLocks from \"./internal/ArtifactLocks.ts\"\n\nconst markerName = \".backup-lease\"\nconst gateName = \".backup-lease-gate\"\nconst heartbeatEvery = \"10 seconds\"\nconst staleAfterMs = 60_000\nconst acquireWithin = \"2 minutes\"\nconst retryEvery = \"25 millis\"\n\nconst isReason = (cause: unknown, tag: PlatformError.SystemErrorTag): boolean =>\n  cause instanceof PlatformError.PlatformError && cause.reason._tag === tag\n\nconst token = Effect.gen(function*() {\n  const first = yield* Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true })\n  const second = yield* Random.nextIntBetween(0, Number.MAX_SAFE_INTEGER, { halfOpen: true })\n  return `${first.toString(36)}-${second.toString(36)}-${yield* Clock.currentTimeMillis}`\n})\n\nconst gate = <A, E, R, E2>(\n  fs: FileSystem.FileSystem,\n  directory: string,\n  effect: Effect.Effect<A, E, R>,\n  failure: (cause: unknown) => E2\n): Effect.Effect<A, E | E2, R> => ArtifactLocks.withDigest(fs, directory, gateName, effect, failure)\n\nconst activeMarker = <E>(\n  fs: FileSystem.FileSystem,\n  directory: string,\n  failure: (cause: unknown) => E\n): Effect.Effect<boolean, E> =>\n  Effect.gen(function*() {\n    const path = `${directory}/${markerName}`\n    const info = yield* fs.stat(path).pipe(\n      Effect.map(Option.some),\n      Effect.catch((cause): Effect.Effect<Option.Option<FileSystem.File.Info>, E> =>\n        isReason(cause, \"NotFound\") ? Effect.succeed(Option.none()) : Effect.fail(failure(cause))\n      )\n    )\n    if (Option.isNone(info)) return false\n    const modified = Option.getOrUndefined(info.value.mtime)\n    const now = yield* Clock.currentTimeMillis\n    if (modified === undefined || now - modified.getTime() <= staleAfterMs) return true\n    yield* fs.remove(path).pipe(\n      Effect.catch((cause): Effect.Effect<void, E> =>\n        isReason(cause, \"NotFound\") ? Effect.void : Effect.fail(failure(cause))\n      )\n    )\n    return false\n  })\n\n/**\n * Runs `effect` while sweep deletion is fenced across every process using\n * this objects directory. A crashed holder is recovered after its heartbeat\n * becomes stale.\n *\n * @category combinators\n * @since 1.0.0-rc.0\n */\nexport const withLease = <A, E, R, E2>(\n  fs: FileSystem.FileSystem,\n  directory: string,\n  effect: Effect.Effect<A, E, R>,\n  failure: (cause: unknown) => E2\n): Effect.Effect<A, E | E2, R> =>\n  Effect.gen(function*() {\n    const owner = yield* token\n    const marker = `${directory}/${markerName}`\n    yield* fs.makeDirectory(directory, { recursive: true }).pipe(Effect.mapError(failure))\n\n    let ownsMarker = false\n    const acquire = Effect.gen(function*() {\n      while (true) {\n        const acquired = yield* gate(\n          fs,\n          directory,\n          Effect.gen(function*() {\n            if (yield* activeMarker(fs, directory, failure)) return false\n            return yield* Effect.uninterruptible(\n              fs.writeFileString(marker, owner, { flag: \"wx\", mode: 0o600 }).pipe(\n                Effect.andThen(Effect.sync(() => {\n                  ownsMarker = true\n                  return true\n                })),\n                Effect.catch((cause): Effect.Effect<boolean, E2> =>\n                  isReason(cause, \"AlreadyExists\") ? Effect.succeed(false) : Effect.fail(failure(cause))\n                )\n              )\n            )\n          }),\n          failure\n        )\n        if (acquired) return\n        yield* Effect.sleep(retryEvery)\n      }\n    }).pipe(\n      Effect.timeout(acquireWithin),\n      Effect.catchTag(\"TimeoutError\", (cause) => Effect.fail(failure(cause)))\n    )\n\n    // Install marker cleanup before acquisition, including gate release. The\n    // marker write and ownership bookkeeping complete in one interruption mask.\n    return yield* Effect.acquireUseRelease(\n      Effect.void,\n      () =>\n        acquire.pipe(Effect.andThen(\n          Effect.scoped(Effect.gen(function*() {\n            yield* Effect.forkScoped(\n              Effect.gen(function*() {\n                while (true) {\n                  yield* Effect.sleep(heartbeatEvery)\n                  const reclaimed = yield* gate(\n                    fs,\n                    directory,\n                    fs.readFileString(marker).pipe(\n                      Effect.map(Option.some),\n                      Effect.catch((cause) =>\n                        isReason(cause, \"NotFound\") ? Effect.succeed(Option.none<string>()) : Effect.fail(cause)\n                      ),\n                      Effect.flatMap((found) => {\n                        // A missing or foreign marker means a sweep judged this\n                        // lease stale and reaped it: deletion is no longer\n                        // fenced while the backup still copies. The sibling\n                        // `internal/ArtifactLocks.ts` heartbeat reports the same\n                        // loss the same way. A reaped marker is never handed\n                        // back, so the loss is reported once and the heartbeat\n                        // ends instead of repeating it every tick.\n                        if (Option.getOrUndefined(found) !== owner) {\n                          return Effect.as(\n                            Effect.logWarning(\n                              \"Artifact backup lease was reclaimed while its backup was still running\"\n                            ),\n                            true\n                          )\n                        }\n                        return Effect.flatMap(Clock.currentTimeMillis, (now) => {\n                          const timestamp = new Date(now)\n                          return Effect.as(fs.utimes(marker, timestamp, timestamp), false)\n                        })\n                      }),\n                      Effect.mapError(failure)\n                    ),\n                    failure\n                  ).pipe(\n                    // A failed heartbeat is retried on the next tick, but a\n                    // minute of them lets the marker go stale, so each one is\n                    // reported rather than dropped.\n                    Effect.catch((cause) =>\n                      Effect.as(Effect.logWarning(\"Artifact backup lease heartbeat failed\", cause), false)\n                    )\n                  )\n                  if (reclaimed) return\n                }\n              })\n            )\n            return yield* effect\n          }))\n        )),\n      () =>\n        ownsMarker\n          ? gate(\n            fs,\n            directory,\n            fs.readFileString(marker).pipe(\n              Effect.flatMap((found) => found === owner ? fs.remove(marker) : Effect.void),\n              // A backup whose heartbeat lapsed has its marker reaped by whoever\n              // noticed, so `NotFound` is the ordinary end of a slow lease, not a\n              // fault: there is nothing left to release and nothing left to leak.\n              // The sibling release in `internal/ArtifactLocks.ts` classifies the\n              // same cause the same way.\n              Effect.catch((cause): Effect.Effect<void, PlatformError.PlatformError> =>\n                isReason(cause, \"NotFound\") ? Effect.void : Effect.fail(cause)\n              )\n            ),\n            failure\n          ).pipe(\n            Effect.catch((cause) => Effect.logWarning(\"Artifact backup lease release failed\", cause))\n          )\n          : Effect.void\n    )\n  })\n\n/**\n * Runs one sweep deletion only when no live backup lease exists. The marker\n * check and `effect` share the global gate, closing the check/delete race.\n * `None` means a backup deliberately fenced the operation.\n *\n * @category combinators\n * @since 1.0.0-rc.0\n */\nexport const unlessActive = <A, E, R, E2>(\n  fs: FileSystem.FileSystem,\n  directory: string,\n  effect: Effect.Effect<A, E, R>,\n  failure: (cause: unknown) => E2\n): Effect.Effect<Option.Option<A>, E | E2, R> =>\n  gate(\n    fs,\n    directory,\n    Effect.gen(function*() {\n      if (yield* activeMarker(fs, directory, failure)) return Option.none<A>()\n      return Option.some(yield* effect)\n    }),\n    failure\n  )\n"]}

package/dist/esm/ArtifactStore.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The content-addressed artifact store: bytes addressed by their own SHA-256
+ * digest.
+ *
+ * It is deliberately *not* the step cache: the step cache maps a step key to a
+ * recorded result, while large result bytes live here under their digest. The
+ * two tiers remain separate because artifacts must be published before a cache
+ * record may reference them. See the package README and
+ * {@link https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md | step-key documentation}.
+ *
+ * This module defines the contract: the address schema, the service interface
+ * and tag, and one layer per local implementation. The errors, byte helpers,
+ * and implementations are defined in the modules named for them and re-exported
+ * here unchanged, so this subpath and the root `ArtifactStore` namespace keep
+ * their whole surface.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { Sha256 } from "@smthrs/crypto";
+import * as Context from "effect/Context";
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import type { ArtifactCorruption, ArtifactMissing, ArtifactStoreError } from "./ArtifactStoreError.ts";
+import { type FileSystemOptions } from "./FileSystemArtifactStore.ts";
+export { ArtifactCorruption, ArtifactMissing, ArtifactStoreError, ArtifactStoreErrorCode } from "./ArtifactStoreError.ts";
+export { defaultDirectory, type FileSystemOptions, makeFileSystem } from "./FileSystemArtifactStore.ts";
+export { measureBytes } from "./measureBytes.ts";
+export { makeMemory } from "./MemoryArtifactStore.ts";
+export { makeNoop } from "./NoopArtifactStore.ts";
+export { snapshotBytes } from "./snapshotBytes.ts";
+export { validateDigest } from "./validateDigest.ts";
+/**
+ * Schema for a content address: exactly 64 lowercase hexadecimal SHA-256
+ * characters, branded by `@smthrs/crypto`. Re-exported so a consumer never has
+ * to reach past this package for the address type it stores under.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const Digest: import("effect/Schema").brand<import("effect/Schema").String, "@smthrs/crypto/Sha256/Digest">;
+/**
+ * A content address produced by this store.
+ *
+ * Read operations accept a plain `string` rather than this brand on purpose: a
+ * digest read back out of a durable row is untrusted input, so the store
+ * validates it (see {@link ArtifactStoreError}'s `invalid_digest` code) instead
+ * of asking every caller to re-brand a persisted column. `put` returns the
+ * brand, because it measured the bytes itself.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export type Digest = typeof Sha256.Digest.Type;
+/**
+ * Content-addressed blob storage.
+ *
+ * The contract's ergonomics follow Effect's own `KeyValueStore`
+ * (`effect/persistence/KeyValueStore`): a small set of total
+ * operations over one address space, with a single typed error family, so a
+ * memory, filesystem, or network implementation is the same shape.
+ * `findMissing` is Bazel's `MissingDigestsFinder` — one batched round trip
+ * whose result is guaranteed to be a subset of its input — because a
+ * per-digest existence probe over a network tier is the wrong shape entirely.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export interface Service {
+    /**
+     * Stores `bytes` under their own SHA-256 digest and returns that address.
+     * Storing the same bytes twice is idempotent.
+     */
+    readonly put: (bytes: Uint8Array) => Effect.Effect<Digest, ArtifactStoreError, Crypto.Crypto>;
+    /**
+     * Reads the bytes stored at `digest`, verifying that they still hash to it.
+     */
+    readonly get: (digest: string) => Effect.Effect<Uint8Array, ArtifactMissing | ArtifactCorruption | ArtifactStoreError, Crypto.Crypto>;
+    /** Whether this tier holds an artifact at `digest`. */
+    readonly has: (digest: string) => Effect.Effect<boolean, ArtifactStoreError>;
+    /**
+     * Which of `digests` this tier does not hold. The returned array is
+     * guaranteed to be a subset of the input and free of duplicates.
+     */
+    readonly findMissing: (digests: Iterable<string>) => Effect.Effect<Array<string>, ArtifactStoreError>;
+}
+declare const ArtifactStore_base: Context.ServiceClass<ArtifactStore, "@smthrs/artifacts/ArtifactStore", Service>;
+/**
+ * Service tag for the content-addressed artifact store.
+ *
+ * The identity string equals this module's package path, per the house rule
+ * that an identity is the defining module path.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare class ArtifactStore extends ArtifactStore_base {
+}
+/**
+ * Provides the filesystem-backed artifact store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const layerFileSystem: (options?: FileSystemOptions) => Layer.Layer<ArtifactStore, never, FileSystem.FileSystem | Path.Path>;
+/**
+ * Provides an in-memory artifact store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const layerMemory: Layer.Layer<ArtifactStore>;
+/**
+ * Provides a no-op artifact store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<ArtifactStore>;
+//# sourceMappingURL=ArtifactStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactStore.d.ts","sourceRoot":"","sources":["../../src/ArtifactStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AACnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AACtG,OAAO,EAAE,KAAK,iBAAiB,EAAkB,MAAM,8BAA8B,CAAA;AAIrF,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AACvG,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,+FAAgB,CAAA;AAEnC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAA;AAE9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IAC7F;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,CACZ,MAAM,EAAE,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,GAAG,kBAAkB,GAAG,kBAAkB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACxG,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAA;IAC5E;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CACpB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,KACtB,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAC,CAAA;CACtD;;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,kBAA4E;CAAG;AAElH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAS,iBAAsB,KAC9B,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAGjE,CAAA;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,aAAa,CAAwD,CAAA;AAE3G;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,YAAW,OAAO,CAAC,OAAO,CAAM,KAAG,KAAK,CAAC,KAAK,CAAC,aAAa,CACnC,CAAA"}

package/dist/esm/ArtifactStore.js

@@ -0,0 +1,83 @@
+/**
+ * The content-addressed artifact store: bytes addressed by their own SHA-256
+ * digest.
+ *
+ * It is deliberately *not* the step cache: the step cache maps a step key to a
+ * recorded result, while large result bytes live here under their digest. The
+ * two tiers remain separate because artifacts must be published before a cache
+ * record may reference them. See the package README and
+ * {@link https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md | step-key documentation}.
+ *
+ * This module defines the contract: the address schema, the service interface
+ * and tag, and one layer per local implementation. The errors, byte helpers,
+ * and implementations are defined in the modules named for them and re-exported
+ * here unchanged, so this subpath and the root `ArtifactStore` namespace keep
+ * their whole surface.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { Sha256 } from "@smthrs/crypto";
+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 Path from "effect/Path";
+import { makeFileSystem } from "./FileSystemArtifactStore.js";
+import { makeMemory } from "./MemoryArtifactStore.js";
+import { makeNoop } from "./NoopArtifactStore.js";
+export { ArtifactCorruption, ArtifactMissing, ArtifactStoreError, ArtifactStoreErrorCode } from "./ArtifactStoreError.js";
+export { defaultDirectory, makeFileSystem } from "./FileSystemArtifactStore.js";
+export { measureBytes } from "./measureBytes.js";
+export { makeMemory } from "./MemoryArtifactStore.js";
+export { makeNoop } from "./NoopArtifactStore.js";
+export { snapshotBytes } from "./snapshotBytes.js";
+export { validateDigest } from "./validateDigest.js";
+/**
+ * Schema for a content address: exactly 64 lowercase hexadecimal SHA-256
+ * characters, branded by `@smthrs/crypto`. Re-exported so a consumer never has
+ * to reach past this package for the address type it stores under.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const Digest = Sha256.Digest;
+/**
+ * Service tag for the content-addressed artifact store.
+ *
+ * The identity string equals this module's package path, per the house rule
+ * that an identity is the defining module path.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export class ArtifactStore extends Context.Service()("@smthrs/artifacts/ArtifactStore") {
+}
+/**
+ * Provides the filesystem-backed artifact store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const layerFileSystem = (options = {}) => Layer.effect(ArtifactStore)(Effect.gen(function* () {
+    return makeFileSystem(yield* FileSystem.FileSystem, yield* Path.Path, options);
+}));
+/**
+ * Provides an in-memory artifact store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const layerMemory = Layer.effect(ArtifactStore)(Effect.sync(makeMemory));
+/**
+ * Provides a no-op artifact store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export const layerNoop = (overrides = {}) => Layer.succeed(ArtifactStore)(makeNoop(overrides));
+//# sourceMappingURL=ArtifactStore.js.map

package/dist/esm/ArtifactStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactStore.js","sourceRoot":"","sources":["../../src/ArtifactStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AAEnC,OAAO,EAA0B,cAAc,EAAE,MAAM,8BAA8B,CAAA;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEjD,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,gBAAgB,EAA0B,cAAc,EAAE,MAAM,8BAA8B,CAAA;AACvG,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;AAuDnC;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAc,SAAQ,OAAO,CAAC,OAAO,EAA0B,CAAC,iCAAiC,CAAC;CAAG;AAElH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,UAA6B,EAAE,EACuC,EAAE,CACxE,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC9C,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AAChF,CAAC,CAAC,CAAC,CAAA;AAEL;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAA+B,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAA;AAE3G;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,YAA8B,EAAE,EAA8B,EAAE,CACxF,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAA","sourcesContent":["/**\n * The content-addressed artifact store: bytes addressed by their own SHA-256\n * digest.\n *\n * It is deliberately *not* the step cache: the step cache maps a step key to a\n * recorded result, while large result bytes live here under their digest. The\n * two tiers remain separate because artifacts must be published before a cache\n * record may reference them. See the package README and\n * {@link https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md | step-key documentation}.\n *\n * This module defines the contract: the address schema, the service interface\n * and tag, and one layer per local implementation. The errors, byte helpers,\n * and implementations are defined in the modules named for them and re-exported\n * here unchanged, so this subpath and the root `ArtifactStore` namespace keep\n * their whole surface.\n *\n * @since 1.0.0-rc.0\n */\n\nimport { Sha256 } from \"@smthrs/crypto\"\nimport * as Context from \"effect/Context\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport * as FileSystem from \"effect/FileSystem\"\nimport * as Layer from \"effect/Layer\"\nimport * as Path from \"effect/Path\"\nimport type { ArtifactCorruption, ArtifactMissing, ArtifactStoreError } from \"./ArtifactStoreError.ts\"\nimport { type FileSystemOptions, makeFileSystem } from \"./FileSystemArtifactStore.ts\"\nimport { makeMemory } from \"./MemoryArtifactStore.ts\"\nimport { makeNoop } from \"./NoopArtifactStore.ts\"\n\nexport {\n  ArtifactCorruption,\n  ArtifactMissing,\n  ArtifactStoreError,\n  ArtifactStoreErrorCode\n} from \"./ArtifactStoreError.ts\"\nexport { defaultDirectory, type FileSystemOptions, makeFileSystem } from \"./FileSystemArtifactStore.ts\"\nexport { measureBytes } from \"./measureBytes.ts\"\nexport { makeMemory } from \"./MemoryArtifactStore.ts\"\nexport { makeNoop } from \"./NoopArtifactStore.ts\"\nexport { snapshotBytes } from \"./snapshotBytes.ts\"\nexport { validateDigest } from \"./validateDigest.ts\"\n\n/**\n * Schema for a content address: exactly 64 lowercase hexadecimal SHA-256\n * characters, branded by `@smthrs/crypto`. Re-exported so a consumer never has\n * to reach past this package for the address type it stores under.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const Digest = Sha256.Digest\n\n/**\n * A content address produced by this store.\n *\n * Read operations accept a plain `string` rather than this brand on purpose: a\n * digest read back out of a durable row is untrusted input, so the store\n * validates it (see {@link ArtifactStoreError}'s `invalid_digest` code) instead\n * of asking every caller to re-brand a persisted column. `put` returns the\n * brand, because it measured the bytes itself.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport type Digest = typeof Sha256.Digest.Type\n\n/**\n * Content-addressed blob storage.\n *\n * The contract's ergonomics follow Effect's own `KeyValueStore`\n * (`effect/persistence/KeyValueStore`): a small set of total\n * operations over one address space, with a single typed error family, so a\n * memory, filesystem, or network implementation is the same shape.\n * `findMissing` is Bazel's `MissingDigestsFinder` — one batched round trip\n * whose result is guaranteed to be a subset of its input — because a\n * per-digest existence probe over a network tier is the wrong shape entirely.\n *\n * @category models\n * @since 1.0.0-rc.0\n * @slop\n */\nexport interface Service {\n  /**\n   * Stores `bytes` under their own SHA-256 digest and returns that address.\n   * Storing the same bytes twice is idempotent.\n   */\n  readonly put: (bytes: Uint8Array) => Effect.Effect<Digest, ArtifactStoreError, Crypto.Crypto>\n  /**\n   * Reads the bytes stored at `digest`, verifying that they still hash to it.\n   */\n  readonly get: (\n    digest: string\n  ) => Effect.Effect<Uint8Array, ArtifactMissing | ArtifactCorruption | ArtifactStoreError, Crypto.Crypto>\n  /** Whether this tier holds an artifact at `digest`. */\n  readonly has: (digest: string) => Effect.Effect<boolean, ArtifactStoreError>\n  /**\n   * Which of `digests` this tier does not hold. The returned array is\n   * guaranteed to be a subset of the input and free of duplicates.\n   */\n  readonly findMissing: (\n    digests: Iterable<string>\n  ) => Effect.Effect<Array<string>, ArtifactStoreError>\n}\n\n/**\n * Service tag for the content-addressed artifact store.\n *\n * The identity string equals this module's package path, per the house rule\n * that an identity is the defining module path.\n *\n * @category services\n * @since 1.0.0-rc.0\n * @slop\n */\nexport class ArtifactStore extends Context.Service<ArtifactStore, Service>()(\"@smthrs/artifacts/ArtifactStore\") {}\n\n/**\n * Provides the filesystem-backed artifact store.\n *\n * @category layers\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const layerFileSystem = (\n  options: FileSystemOptions = {}\n): Layer.Layer<ArtifactStore, never, FileSystem.FileSystem | Path.Path> =>\n  Layer.effect(ArtifactStore)(Effect.gen(function*() {\n    return makeFileSystem(yield* FileSystem.FileSystem, yield* Path.Path, options)\n  }))\n\n/**\n * Provides an in-memory artifact store.\n *\n * @category layers\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const layerMemory: Layer.Layer<ArtifactStore> = Layer.effect(ArtifactStore)(Effect.sync(makeMemory))\n\n/**\n * Provides a no-op artifact store.\n *\n * @category layers\n * @since 1.0.0-rc.0\n * @slop\n */\nexport const layerNoop = (overrides: Partial<Service> = {}): Layer.Layer<ArtifactStore> =>\n  Layer.succeed(ArtifactStore)(makeNoop(overrides))\n"]}