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

package/dist/cjs/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/cjs/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/cjs/ArtifactStore.js

@@ -0,0 +1,73 @@
+"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 ArtifactStore_exports = {};
+__export(ArtifactStore_exports, {
+  ArtifactCorruption: () => import_ArtifactStoreError.ArtifactCorruption,
+  ArtifactMissing: () => import_ArtifactStoreError.ArtifactMissing,
+  ArtifactStore: () => ArtifactStore,
+  ArtifactStoreError: () => import_ArtifactStoreError.ArtifactStoreError,
+  ArtifactStoreErrorCode: () => import_ArtifactStoreError.ArtifactStoreErrorCode,
+  Digest: () => Digest,
+  defaultDirectory: () => import_FileSystemArtifactStore2.defaultDirectory,
+  layerFileSystem: () => layerFileSystem,
+  layerMemory: () => layerMemory,
+  layerNoop: () => layerNoop,
+  makeFileSystem: () => import_FileSystemArtifactStore2.makeFileSystem,
+  makeMemory: () => import_MemoryArtifactStore2.makeMemory,
+  makeNoop: () => import_NoopArtifactStore2.makeNoop,
+  measureBytes: () => import_measureBytes.measureBytes,
+  snapshotBytes: () => import_snapshotBytes.snapshotBytes,
+  validateDigest: () => import_validateDigest.validateDigest
+});
+module.exports = __toCommonJS(ArtifactStore_exports);
+var import_crypto = require("@smthrs/crypto");
+var Context = __toESM(require("effect/Context"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var FileSystem = __toESM(require("effect/FileSystem"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var Path = __toESM(require("effect/Path"), 1);
+var import_FileSystemArtifactStore = require("./FileSystemArtifactStore.js");
+var import_MemoryArtifactStore = require("./MemoryArtifactStore.js");
+var import_NoopArtifactStore = require("./NoopArtifactStore.js");
+var import_ArtifactStoreError = require("./ArtifactStoreError.js");
+var import_FileSystemArtifactStore2 = require("./FileSystemArtifactStore.js");
+var import_measureBytes = require("./measureBytes.js");
+var import_MemoryArtifactStore2 = require("./MemoryArtifactStore.js");
+var import_NoopArtifactStore2 = require("./NoopArtifactStore.js");
+var import_snapshotBytes = require("./snapshotBytes.js");
+var import_validateDigest = require("./validateDigest.js");
+const Digest = import_crypto.Sha256.Digest;
+class ArtifactStore extends Context.Service()("@smthrs/artifacts/ArtifactStore") {
+}
+const layerFileSystem = (options = {}) => Layer.effect(ArtifactStore)(Effect.gen(function* () {
+  return (0, import_FileSystemArtifactStore.makeFileSystem)(yield* FileSystem.FileSystem, yield* Path.Path, options);
+}));
+const layerMemory = Layer.effect(ArtifactStore)(Effect.sync(import_MemoryArtifactStore.makeMemory));
+const layerNoop = (overrides = {}) => Layer.succeed(ArtifactStore)((0, import_NoopArtifactStore.makeNoop)(overrides));
+//# sourceMappingURL=ArtifactStore.js.map

package/dist/cjs/ArtifactStore.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ArtifactStore.ts"],
+  "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` \u2014 one batched round trip\n * whose result is guaranteed to be a subset of its input \u2014 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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmBA,oBAAuB;AACvB,cAAyB;AAEzB,aAAwB;AACxB,iBAA4B;AAC5B,YAAuB;AACvB,WAAsB;AAEtB,qCAAuD;AACvD,iCAA2B;AAC3B,+BAAyB;AAEzB,gCAKO;AACP,IAAAA,kCAAyE;AACzE,0BAA6B;AAC7B,IAAAC,8BAA2B;AAC3B,IAAAC,4BAAyB;AACzB,2BAA8B;AAC9B,4BAA+B;AAWxB,MAAM,SAAS,qBAAO;AAiEtB,MAAM,sBAAsB,QAAQ,QAAgC,EAAE,iCAAiC,EAAE;AAAC;AAS1G,MAAM,kBAAkB,CAC7B,UAA6B,CAAC,MAE9B,MAAM,OAAO,aAAa,EAAE,OAAO,IAAI,aAAY;AACjD,aAAO,+CAAe,OAAO,WAAW,YAAY,OAAO,KAAK,MAAM,OAAO;AAC/E,CAAC,CAAC;AASG,MAAM,cAA0C,MAAM,OAAO,aAAa,EAAE,OAAO,KAAK,qCAAU,CAAC;AASnG,MAAM,YAAY,CAAC,YAA8B,CAAC,MACvD,MAAM,QAAQ,aAAa,MAAE,mCAAS,SAAS,CAAC;",
+  "names": ["import_FileSystemArtifactStore", "import_MemoryArtifactStore", "import_NoopArtifactStore"]
+}

package/dist/cjs/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/cjs/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/cjs/ArtifactStoreError.js

@@ -0,0 +1,72 @@
+"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 ArtifactStoreError_exports = {};
+__export(ArtifactStoreError_exports, {
+  ArtifactCorruption: () => ArtifactCorruption,
+  ArtifactMissing: () => ArtifactMissing,
+  ArtifactStoreError: () => ArtifactStoreError,
+  ArtifactStoreErrorCode: () => ArtifactStoreErrorCode
+});
+module.exports = __toCommonJS(ArtifactStoreError_exports);
+var import_crypto = require("@smthrs/crypto");
+var Schema = __toESM(require("effect/Schema"), 1);
+const ArtifactStoreErrorCode = Schema.Literals([
+  "digest_failed",
+  "invalid_configuration",
+  "invalid_digest",
+  "unavailable",
+  "transport_failed"
+]);
+class ArtifactStoreError extends Schema.TaggedError()(
+  "@smthrs/artifacts/ArtifactStoreError",
+  {
+    code: ArtifactStoreErrorCode,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown)
+  }
+) {
+}
+class ArtifactMissing extends Schema.TaggedError()(
+  "@smthrs/artifacts/ArtifactMissing",
+  {
+    code: Schema.Literal("artifact_missing"),
+    digest: import_crypto.Sha256.Digest
+  }
+) {
+}
+class ArtifactCorruption extends Schema.TaggedError()(
+  "@smthrs/artifacts/ArtifactCorruption",
+  {
+    code: Schema.Literal("artifact_corruption"),
+    recordedDigest: import_crypto.Sha256.Digest,
+    measuredDigest: import_crypto.Sha256.Digest
+  }
+) {
+}
+//# sourceMappingURL=ArtifactStoreError.js.map

package/dist/cjs/ArtifactStoreError.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ArtifactStoreError.ts"],
+  "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 \u2014 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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,oBAAuB;AACvB,aAAwB;AASjB,MAAM,yBAAyB,OAAO,SAAS;AAAA,EACpD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AA0BM,MAAM,2BAA2B,OAAO,YAAgC;AAAA,EAC7E;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,SAAS,OAAO;AAAA,IAChB,OAAO,OAAO,SAAS,OAAO,OAAO;AAAA,EACvC;AACF,EAAE;AAAC;AAaI,MAAM,wBAAwB,OAAO,YAA6B;AAAA,EACvE;AAAA,EACA;AAAA,IACE,MAAM,OAAO,QAAQ,kBAAkB;AAAA,IACvC,QAAQ,qBAAO;AAAA,EACjB;AACF,EAAE;AAAC;AAaI,MAAM,2BAA2B,OAAO,YAAgC;AAAA,EAC7E;AAAA,EACA;AAAA,IACE,MAAM,OAAO,QAAQ,qBAAqB;AAAA,IAC1C,gBAAgB,qBAAO;AAAA,IACvB,gBAAgB,qBAAO;AAAA,EACzB;AACF,EAAE;AAAC;",
+  "names": []
+}

package/dist/cjs/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/cjs/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/cjs/ArtifactStoreMetrics.js

@@ -0,0 +1,51 @@
+"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 ArtifactStoreMetrics_exports = {};
+__export(ArtifactStoreMetrics_exports, {
+  gets: () => gets,
+  puts: () => puts,
+  remoteFailure: () => remoteFailure,
+  remoteFailures: () => remoteFailures
+});
+module.exports = __toCommonJS(ArtifactStoreMetrics_exports);
+var Metric = __toESM(require("effect/Metric"), 1);
+const puts = Metric.counter("flows_artifact_puts", {
+  description: "Successful artifact puts, including deduplicated ones"
+});
+const gets = Metric.counter("flows_artifact_gets", {
+  description: "Successful artifact gets"
+});
+const remoteFailures = Metric.counter("flows_artifact_remote_failures", {
+  description: "Dropped combined-artifact transfers by operation"
+});
+const remoteFailure = {
+  put: Metric.withAttributes(remoteFailures, { operation: "put" }),
+  write_back: Metric.withAttributes(remoteFailures, { operation: "write_back" })
+};
+//# sourceMappingURL=ArtifactStoreMetrics.js.map

package/dist/cjs/ArtifactStoreMetrics.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ArtifactStoreMetrics.ts"],
+  "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 \u2014 for\n * example `@smthrs/observability` \u2014 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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BA,aAAwB;AAWjB,MAAM,OAAO,OAAO,QAAQ,uBAAuB;AAAA,EACxD,aAAa;AACf,CAAC;AAWM,MAAM,OAAO,OAAO,QAAQ,uBAAuB;AAAA,EACxD,aAAa;AACf,CAAC;AAcM,MAAM,iBAAiB,OAAO,QAAQ,kCAAkC;AAAA,EAC7E,aAAa;AACf,CAAC;AAQM,MAAM,gBAET;AAAA,EACF,KAAK,OAAO,eAAe,gBAAgB,EAAE,WAAW,MAAM,CAAC;AAAA,EAC/D,YAAY,OAAO,eAAe,gBAAgB,EAAE,WAAW,aAAa,CAAC;AAC/E;",
+  "names": []
+}