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

package/dist/esm/ArtifactSync.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The two-tier artifact protocol the step cache rides on: publish before the
+ * entry, fetch on demand after it.
+ *
+ * This is the seam that makes a shared cache safe. A cache entry references
+ * its large outputs by digest, so an entry that becomes observable while one
+ * of those artifacts is still missing hands the next machine a hit it cannot
+ * materialize. Bazel states the constraint at
+ * `reference/bazel/.../remote/UploadManifest.java:630-633` — "action results
+ * may fail to validate server-side if they are accessed before all blobs they
+ * refer to are present" — and enforces it by ordering:
+ * `findMissingDigests` → upload the missing → upload the `ActionResult` LAST.
+ * {@link Service.publish} is that ordering, and `ActionPersistence` calls it
+ * before `CacheStore.put`.
+ *
+ * The read direction is the same protocol in reverse, and how eagerly it runs
+ * is the {@link DownloadPolicy}, declared on the shared tier itself
+ * (`RemoteArtifacts.Options.downloadPolicy`) and split across two seams.
+ * `all` fetches every referenced artifact into this host's store while
+ * admitting the replay. `toplevel` and `minimal` fetch nothing here: one
+ * batched probe establishes that the shared tier can serve them and the
+ * transfer is left to the first read through `CombinedArtifacts`, which then
+ * writes the blob back under `toplevel` and does not under `minimal`. This is
+ * Bazel's `RemoteOutputChecker` dial
+ * (`--remote_download_{all,toplevel,minimal}`) split the way our two seams
+ * split: what a replay prefetches is this module's decision, what a read
+ * materializes is the combined store's.
+ *
+ * Governing design: `packages/smithers/flows/artifacts/docs/api.md`.
+ *
+ * @since 0.1.0
+ */
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore";
+import * as RemoteArtifacts from "@smthrs/artifacts/RemoteArtifacts";
+import * as Context from "effect/Context";
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+declare const ArtifactPublicationFailed_base: Schema.Class<ArtifactPublicationFailed, Schema.TaggedStruct<"@smthrs/engine-store/ArtifactPublicationFailed", {
+    readonly code: Schema.Literal<"artifact_publication_failed">;
+    readonly digests: Schema.$Array<Schema.String>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Union<readonly [typeof ArtifactStore.ArtifactStoreError, typeof ArtifactStore.ArtifactMissing, typeof ArtifactStore.ArtifactCorruption]>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A referenced artifact could not be made durable in the shared tier, so the
+ * cache entry that references it must not be published.
+ *
+ * Failing here is the point: silently publishing the entry anyway is exactly
+ * the state the REAPI ordering constraint exists to prevent.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export declare class ArtifactPublicationFailed extends ArtifactPublicationFailed_base {
+}
+/**
+ * How eagerly a replay materializes the artifacts it references.
+ *
+ * `all` downloads every referenced artifact into this host's local store while
+ * the replay is admitted, so every later read is local and a shared tier that
+ * goes down afterwards costs nothing. `minimal` downloads none of them: it
+ * establishes that each digest is resolvable — locally, or from the shared tier
+ * — and lets the first actual read fetch the bytes.
+ *
+ * `minimal` is only sound when the store the replay reads through can reach the
+ * shared tier, which means `CombinedArtifacts` with the same remote tier. Under
+ * a purely local `ArtifactStore` an admitted `minimal` replay would later read
+ * an artifact this host never fetched.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type DownloadPolicy = RemoteArtifacts.DownloadPolicy;
+/**
+ * The two directions of the artifact protocol: {@link Service.publish} before a
+ * cache entry becomes observable, {@link Service.hydrate} when a replay needs
+ * bytes this host does not have.
+ *
+ * The asymmetry in their error types is the design: publishing may fail,
+ * because publishing an entry whose artifacts are missing is the unsafe state;
+ * hydrating never fails, because a shared tier that is down should cost a run
+ * a cache hit, not the run itself.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export interface Service {
+    /**
+     * Makes every digest durable in the shared tier, in REAPI order:
+     * `findMissing`, upload what is missing, then confirm nothing is missing
+     * any more. Returns only once the shared tier can serve all of them.
+     */
+    readonly publish: (digests: ReadonlyArray<string>) => Effect.Effect<void, ArtifactPublicationFailed, Crypto.Crypto>;
+    /**
+     * Fetches the digests this host is missing from the shared tier and writes
+     * them into the local store, reporting whether every digest is now locally
+     * resolvable.
+     *
+     * Best-effort by construction: `false` means "replay still cannot be
+     * satisfied", which the caller turns into a real execution. A shared tier
+     * that is down must never fail a run that can simply do the work.
+     */
+    readonly hydrate: (digests: ReadonlyArray<string>) => Effect.Effect<boolean, never, Crypto.Crypto>;
+}
+declare const ArtifactSync_base: Context.ServiceClass<ArtifactSync, "@smthrs/engine-store/ArtifactSync", Service>;
+/**
+ * Service tag for the two-tier artifact protocol.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export declare class ArtifactSync extends ArtifactSync_base {
+}
+/**
+ * The single-tier implementation: there is no shared artifact store, so there
+ * is nothing to publish and nothing to fetch.
+ *
+ * This is the default `ActionPersistence` falls back to when the tag is
+ * absent, which is what keeps a purely local composition free of any
+ * remote-cache machinery.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const makeLocal: () => Service;
+/**
+ * Provides the single-tier (no shared artifact store) protocol.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layerLocal: Layer.Layer<ArtifactSync>;
+/**
+ * Builds the two-tier protocol over a local and a shared artifact store.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const make: (options: {
+    readonly local: ArtifactStore.Service;
+    readonly remote: ArtifactStore.Service;
+    /**
+     * Defaults to the policy the shared tier declares, and to `all` for a tier
+     * that declares none: every referenced artifact is fetched at hydrate.
+     */
+    readonly downloadPolicy?: DownloadPolicy | undefined;
+}) => Service;
+/**
+ * Provides the two-tier protocol, taking the local store from the
+ * `ArtifactStore` tag and the shared store from the supplied effect.
+ *
+ * The two tiers cannot both be layers: they inhabit the same tag, so composing
+ * them would shadow one with the other.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layer: <E, R>(remote: Effect.Effect<ArtifactStore.Service, E, R>, options?: {
+    readonly downloadPolicy?: DownloadPolicy | undefined;
+} | undefined) => Layer.Layer<ArtifactSync, E, ArtifactStore.ArtifactStore | R>;
+export {};
+//# sourceMappingURL=ArtifactSync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactSync.d.ts","sourceRoot":"","sources":["../../src/ArtifactSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,aAAa,MAAM,iCAAiC,CAAA;AAChE,OAAO,KAAK,eAAe,MAAM,mCAAmC,CAAA;AACpE,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;;;AAEvC;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,SAAQ,8BAc9C;CAAG;AAEJ;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC,cAAc,CAAA;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAChB,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,yBAAyB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IAClE;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,CAChB,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;CAClD;;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,iBAA6E;CAAG;AAElH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,QAAO,OAG3B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY,CAA4C,CAAA;AAE7F;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAA;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAA;IACtC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;CACrD,KAAG,OAmFH,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,EACxB,QAAQ,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAClD,UAAU;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,KAC7E,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,EAAE,aAAa,CAAC,aAAa,GAAG,CAAC,CAW5D,CAAA"}

package/dist/esm/ArtifactSync.js

@@ -0,0 +1,176 @@
+/**
+ * The two-tier artifact protocol the step cache rides on: publish before the
+ * entry, fetch on demand after it.
+ *
+ * This is the seam that makes a shared cache safe. A cache entry references
+ * its large outputs by digest, so an entry that becomes observable while one
+ * of those artifacts is still missing hands the next machine a hit it cannot
+ * materialize. Bazel states the constraint at
+ * `reference/bazel/.../remote/UploadManifest.java:630-633` — "action results
+ * may fail to validate server-side if they are accessed before all blobs they
+ * refer to are present" — and enforces it by ordering:
+ * `findMissingDigests` → upload the missing → upload the `ActionResult` LAST.
+ * {@link Service.publish} is that ordering, and `ActionPersistence` calls it
+ * before `CacheStore.put`.
+ *
+ * The read direction is the same protocol in reverse, and how eagerly it runs
+ * is the {@link DownloadPolicy}, declared on the shared tier itself
+ * (`RemoteArtifacts.Options.downloadPolicy`) and split across two seams.
+ * `all` fetches every referenced artifact into this host's store while
+ * admitting the replay. `toplevel` and `minimal` fetch nothing here: one
+ * batched probe establishes that the shared tier can serve them and the
+ * transfer is left to the first read through `CombinedArtifacts`, which then
+ * writes the blob back under `toplevel` and does not under `minimal`. This is
+ * Bazel's `RemoteOutputChecker` dial
+ * (`--remote_download_{all,toplevel,minimal}`) split the way our two seams
+ * split: what a replay prefetches is this module's decision, what a read
+ * materializes is the combined store's.
+ *
+ * Governing design: `packages/smithers/flows/artifacts/docs/api.md`.
+ *
+ * @since 0.1.0
+ */
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore";
+import * as RemoteArtifacts from "@smthrs/artifacts/RemoteArtifacts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+/**
+ * A referenced artifact could not be made durable in the shared tier, so the
+ * cache entry that references it must not be published.
+ *
+ * Failing here is the point: silently publishing the entry anyway is exactly
+ * the state the REAPI ordering constraint exists to prevent.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class ArtifactPublicationFailed extends Schema.TaggedError()("@smthrs/engine-store/ArtifactPublicationFailed", {
+    code: Schema.Literal("artifact_publication_failed"),
+    digests: Schema.Array(Schema.String),
+    message: Schema.String,
+    cause: Schema.optional(Schema.Union([
+        ArtifactStore.ArtifactStoreError,
+        ArtifactStore.ArtifactMissing,
+        ArtifactStore.ArtifactCorruption
+    ]))
+}) {
+}
+/**
+ * Service tag for the two-tier artifact protocol.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export class ArtifactSync extends Context.Service()("@smthrs/engine-store/ArtifactSync") {
+}
+/**
+ * The single-tier implementation: there is no shared artifact store, so there
+ * is nothing to publish and nothing to fetch.
+ *
+ * This is the default `ActionPersistence` falls back to when the tag is
+ * absent, which is what keeps a purely local composition free of any
+ * remote-cache machinery.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const makeLocal = () => ({
+    publish: Effect.fn("ArtifactSync.publish")(() => Effect.void),
+    hydrate: Effect.fn("ArtifactSync.hydrate")((digests) => Effect.succeed(digests.length === 0))
+});
+/**
+ * Provides the single-tier (no shared artifact store) protocol.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerLocal = Layer.succeed(ArtifactSync)(makeLocal());
+/**
+ * Builds the two-tier protocol over a local and a shared artifact store.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = (options) => {
+    const { local, remote } = options;
+    const downloadPolicy = options.downloadPolicy ?? RemoteArtifacts.downloadPolicyOf(remote) ?? "all";
+    const publicationFailed = (digests, message, cause) => new ArtifactPublicationFailed({ code: "artifact_publication_failed", digests, message, cause });
+    return {
+        publish: Effect.fn("ArtifactSync.publish")(function* (digests) {
+            if (digests.length === 0)
+                return;
+            const missing = yield* remote.findMissing(digests).pipe(Effect.mapError((cause) => publicationFailed(digests, "the shared tier refused a probe", cause)));
+            for (const digest of missing) {
+                const bytes = yield* local.get(digest).pipe(Effect.mapError((cause) => 
+                // The blob is referenced by evidence this host just produced, so
+                // it should be in this host's own store. If it is not, the
+                // evidence is not publishable — and saying so is far better than
+                // publishing an entry nobody can replay.
+                publicationFailed([digest], "this host cannot read the artifact it recorded", cause)));
+                yield* remote.put(bytes).pipe(Effect.mapError((cause) => publicationFailed([digest], "the shared tier refused an upload", cause)));
+            }
+            if (missing.length === 0)
+                return;
+            // The confirming re-probe is not paranoia: a tier that accepted the
+            // upload but did not durably store it is exactly the state that makes a
+            // published entry unreplayable, and it is cheap to rule out — one
+            // batched round trip over the set we just wrote.
+            const stillMissing = yield* remote.findMissing(missing).pipe(Effect.mapError((cause) => publicationFailed(missing, "the shared tier refused a probe", cause)));
+            if (stillMissing.length > 0) {
+                return yield* Effect.fail(publicationFailed(stillMissing, "the shared tier did not retain the uploaded artifacts"));
+            }
+        }),
+        hydrate: Effect.fn("ArtifactSync.hydrate")(function* (digests) {
+            // Every refusal below falls back to re-executing the step, which is
+            // correct and silent. The warning is the operator's only signal that a
+            // tier stopped serving replays.
+            const fallBack = (message, digests) => (cause) => Effect.logWarning(`artifact hydration falls back to re-execution: ${message}: ${digests.join(", ")}`).pipe(Effect.annotateLogs({ reason: cause.message }));
+            const missing = yield* local.findMissing(digests).pipe(Effect.tapError(fallBack("the local tier refused a probe", digests)), Effect.option);
+            if (missing._tag === "None")
+                return false;
+            if (downloadPolicy !== "all") {
+                if (missing.value.length === 0)
+                    return true;
+                // One batched probe, no body transfer: the answer these policies owe
+                // the caller is "can this replay be satisfied", and `findMissing`
+                // answers exactly that. A tier that refuses the probe is
+                // indistinguishable from one that holds nothing, so the replay is
+                // refused either way.
+                const elsewhere = yield* remote.findMissing(missing.value).pipe(Effect.tapError(fallBack("the shared tier refused a probe", missing.value)), Effect.option);
+                return elsewhere._tag === "Some" && elsewhere.value.length === 0;
+            }
+            for (const digest of missing.value) {
+                // Read-through, one artifact at a time and only on demand: the remote
+                // read is digest-verified by `RemoteArtifacts`, and the local `put`
+                // re-addresses the bytes, so a tier serving wrong content cannot get
+                // them written into this workspace.
+                const written = yield* remote.get(digest).pipe(Effect.flatMap((bytes) => local.put(bytes)), Effect.tapError(fallBack("the artifact could not be fetched", [digest])), Effect.option);
+                if (written._tag === "None")
+                    return false;
+            }
+            return true;
+        })
+    };
+};
+/**
+ * Provides the two-tier protocol, taking the local store from the
+ * `ArtifactStore` tag and the shared store from the supplied effect.
+ *
+ * The two tiers cannot both be layers: they inhabit the same tag, so composing
+ * them would shadow one with the other.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layer = (remote, options) => Layer.effect(ArtifactSync)(Effect.gen(function* () {
+    const local = yield* ArtifactStore.ArtifactStore;
+    const shared = yield* remote;
+    return make({
+        local,
+        remote: shared,
+        ...(options?.downloadPolicy === undefined ? {} : { downloadPolicy: options.downloadPolicy })
+    });
+}));
+//# sourceMappingURL=ArtifactSync.js.map

package/dist/esm/ArtifactSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactSync.js","sourceRoot":"","sources":["../../src/ArtifactSync.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The two-tier artifact protocol the step cache rides on: publish before the\n * entry, fetch on demand after it.\n *\n * This is the seam that makes a shared cache safe. A cache entry references\n * its large outputs by digest, so an entry that becomes observable while one\n * of those artifacts is still missing hands the next machine a hit it cannot\n * materialize. Bazel states the constraint at\n * `reference/bazel/.../remote/UploadManifest.java:630-633` — \"action results\n * may fail to validate server-side if they are accessed before all blobs they\n * refer to are present\" — and enforces it by ordering:\n * `findMissingDigests` → upload the missing → upload the `ActionResult` LAST.\n * {@link Service.publish} is that ordering, and `ActionPersistence` calls it\n * before `CacheStore.put`.\n *\n * The read direction is the same protocol in reverse, and how eagerly it runs\n * is the {@link DownloadPolicy}, declared on the shared tier itself\n * (`RemoteArtifacts.Options.downloadPolicy`) and split across two seams.\n * `all` fetches every referenced artifact into this host's store while\n * admitting the replay. `toplevel` and `minimal` fetch nothing here: one\n * batched probe establishes that the shared tier can serve them and the\n * transfer is left to the first read through `CombinedArtifacts`, which then\n * writes the blob back under `toplevel` and does not under `minimal`. This is\n * Bazel's `RemoteOutputChecker` dial\n * (`--remote_download_{all,toplevel,minimal}`) split the way our two seams\n * split: what a replay prefetches is this module's decision, what a read\n * materializes is the combined store's.\n *\n * Governing design: `packages/smithers/flows/artifacts/docs/api.md`.\n *\n * @since 0.1.0\n */\n\nimport * as ArtifactStore from \"@smthrs/artifacts/ArtifactStore\"\nimport * as RemoteArtifacts from \"@smthrs/artifacts/RemoteArtifacts\"\nimport * as Context from \"effect/Context\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * A referenced artifact could not be made durable in the shared tier, so the\n * cache entry that references it must not be published.\n *\n * Failing here is the point: silently publishing the entry anyway is exactly\n * the state the REAPI ordering constraint exists to prevent.\n *\n * @since 0.1.0\n * @category errors\n */\nexport class ArtifactPublicationFailed extends Schema.TaggedError<ArtifactPublicationFailed>()(\n  \"@smthrs/engine-store/ArtifactPublicationFailed\",\n  {\n    code: Schema.Literal(\"artifact_publication_failed\"),\n    digests: Schema.Array(Schema.String),\n    message: Schema.String,\n    cause: Schema.optional(\n      Schema.Union([\n        ArtifactStore.ArtifactStoreError,\n        ArtifactStore.ArtifactMissing,\n        ArtifactStore.ArtifactCorruption\n      ])\n    )\n  }\n) {}\n\n/**\n * How eagerly a replay materializes the artifacts it references.\n *\n * `all` downloads every referenced artifact into this host's local store while\n * the replay is admitted, so every later read is local and a shared tier that\n * goes down afterwards costs nothing. `minimal` downloads none of them: it\n * establishes that each digest is resolvable — locally, or from the shared tier\n * — and lets the first actual read fetch the bytes.\n *\n * `minimal` is only sound when the store the replay reads through can reach the\n * shared tier, which means `CombinedArtifacts` with the same remote tier. Under\n * a purely local `ArtifactStore` an admitted `minimal` replay would later read\n * an artifact this host never fetched.\n *\n * @since 0.1.0\n * @category models\n */\nexport type DownloadPolicy = RemoteArtifacts.DownloadPolicy\n\n/**\n * The two directions of the artifact protocol: {@link Service.publish} before a\n * cache entry becomes observable, {@link Service.hydrate} when a replay needs\n * bytes this host does not have.\n *\n * The asymmetry in their error types is the design: publishing may fail,\n * because publishing an entry whose artifacts are missing is the unsafe state;\n * hydrating never fails, because a shared tier that is down should cost a run\n * a cache hit, not the run itself.\n *\n * @since 0.1.0\n * @category services\n */\nexport interface Service {\n  /**\n   * Makes every digest durable in the shared tier, in REAPI order:\n   * `findMissing`, upload what is missing, then confirm nothing is missing\n   * any more. Returns only once the shared tier can serve all of them.\n   */\n  readonly publish: (\n    digests: ReadonlyArray<string>\n  ) => Effect.Effect<void, ArtifactPublicationFailed, Crypto.Crypto>\n  /**\n   * Fetches the digests this host is missing from the shared tier and writes\n   * them into the local store, reporting whether every digest is now locally\n   * resolvable.\n   *\n   * Best-effort by construction: `false` means \"replay still cannot be\n   * satisfied\", which the caller turns into a real execution. A shared tier\n   * that is down must never fail a run that can simply do the work.\n   */\n  readonly hydrate: (\n    digests: ReadonlyArray<string>\n  ) => Effect.Effect<boolean, never, Crypto.Crypto>\n}\n\n/**\n * Service tag for the two-tier artifact protocol.\n *\n * @since 0.1.0\n * @category services\n */\nexport class ArtifactSync extends Context.Service<ArtifactSync, Service>()(\"@smthrs/engine-store/ArtifactSync\") {}\n\n/**\n * The single-tier implementation: there is no shared artifact store, so there\n * is nothing to publish and nothing to fetch.\n *\n * This is the default `ActionPersistence` falls back to when the tag is\n * absent, which is what keeps a purely local composition free of any\n * remote-cache machinery.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const makeLocal = (): Service => ({\n  publish: Effect.fn(\"ArtifactSync.publish\")(() => Effect.void),\n  hydrate: Effect.fn(\"ArtifactSync.hydrate\")((digests) => Effect.succeed(digests.length === 0))\n})\n\n/**\n * Provides the single-tier (no shared artifact store) protocol.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layerLocal: Layer.Layer<ArtifactSync> = Layer.succeed(ArtifactSync)(makeLocal())\n\n/**\n * Builds the two-tier protocol over a local and a shared artifact store.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const make = (options: {\n  readonly local: ArtifactStore.Service\n  readonly remote: ArtifactStore.Service\n  /**\n   * Defaults to the policy the shared tier declares, and to `all` for a tier\n   * that declares none: every referenced artifact is fetched at hydrate.\n   */\n  readonly downloadPolicy?: DownloadPolicy | undefined\n}): Service => {\n  const { local, remote } = options\n  const downloadPolicy = options.downloadPolicy ?? RemoteArtifacts.downloadPolicyOf(remote) ?? \"all\"\n  const publicationFailed = (\n    digests: ReadonlyArray<string>,\n    message: string,\n    cause?: ArtifactStore.ArtifactStoreError | ArtifactStore.ArtifactMissing | ArtifactStore.ArtifactCorruption\n  ) => new ArtifactPublicationFailed({ code: \"artifact_publication_failed\", digests, message, cause })\n  return {\n    publish: Effect.fn(\"ArtifactSync.publish\")(function*(digests) {\n      if (digests.length === 0) return\n      const missing = yield* remote.findMissing(digests).pipe(\n        Effect.mapError((cause) => publicationFailed(digests, \"the shared tier refused a probe\", cause))\n      )\n      for (const digest of missing) {\n        const bytes = yield* local.get(digest).pipe(\n          Effect.mapError((cause) =>\n            // The blob is referenced by evidence this host just produced, so\n            // it should be in this host's own store. If it is not, the\n            // evidence is not publishable — and saying so is far better than\n            // publishing an entry nobody can replay.\n            publicationFailed([digest], \"this host cannot read the artifact it recorded\", cause)\n          )\n        )\n        yield* remote.put(bytes).pipe(\n          Effect.mapError((cause) => publicationFailed([digest], \"the shared tier refused an upload\", cause))\n        )\n      }\n      if (missing.length === 0) return\n      // The confirming re-probe is not paranoia: a tier that accepted the\n      // upload but did not durably store it is exactly the state that makes a\n      // published entry unreplayable, and it is cheap to rule out — one\n      // batched round trip over the set we just wrote.\n      const stillMissing = yield* remote.findMissing(missing).pipe(\n        Effect.mapError((cause) => publicationFailed(missing, \"the shared tier refused a probe\", cause))\n      )\n      if (stillMissing.length > 0) {\n        return yield* Effect.fail(\n          publicationFailed(stillMissing, \"the shared tier did not retain the uploaded artifacts\")\n        )\n      }\n    }),\n    hydrate: Effect.fn(\"ArtifactSync.hydrate\")(function*(digests) {\n      // Every refusal below falls back to re-executing the step, which is\n      // correct and silent. The warning is the operator's only signal that a\n      // tier stopped serving replays.\n      const fallBack = (message: string, digests: ReadonlyArray<string>) => (cause: { readonly message: string }) =>\n        Effect.logWarning(`artifact hydration falls back to re-execution: ${message}: ${digests.join(\", \")}`).pipe(\n          Effect.annotateLogs({ reason: cause.message })\n        )\n      const missing = yield* local.findMissing(digests).pipe(\n        Effect.tapError(fallBack(\"the local tier refused a probe\", digests)),\n        Effect.option\n      )\n      if (missing._tag === \"None\") return false\n      if (downloadPolicy !== \"all\") {\n        if (missing.value.length === 0) return true\n        // One batched probe, no body transfer: the answer these policies owe\n        // the caller is \"can this replay be satisfied\", and `findMissing`\n        // answers exactly that. A tier that refuses the probe is\n        // indistinguishable from one that holds nothing, so the replay is\n        // refused either way.\n        const elsewhere = yield* remote.findMissing(missing.value).pipe(\n          Effect.tapError(fallBack(\"the shared tier refused a probe\", missing.value)),\n          Effect.option\n        )\n        return elsewhere._tag === \"Some\" && elsewhere.value.length === 0\n      }\n      for (const digest of missing.value) {\n        // Read-through, one artifact at a time and only on demand: the remote\n        // read is digest-verified by `RemoteArtifacts`, and the local `put`\n        // re-addresses the bytes, so a tier serving wrong content cannot get\n        // them written into this workspace.\n        const written = yield* remote.get(digest).pipe(\n          Effect.flatMap((bytes) => local.put(bytes)),\n          Effect.tapError(fallBack(\"the artifact could not be fetched\", [digest])),\n          Effect.option\n        )\n        if (written._tag === \"None\") return false\n      }\n      return true\n    })\n  }\n}\n\n/**\n * Provides the two-tier protocol, taking the local store from the\n * `ArtifactStore` tag and the shared store from the supplied effect.\n *\n * The two tiers cannot both be layers: they inhabit the same tag, so composing\n * them would shadow one with the other.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layer = <E, R>(\n  remote: Effect.Effect<ArtifactStore.Service, E, R>,\n  options?: { readonly downloadPolicy?: DownloadPolicy | undefined } | undefined\n): Layer.Layer<ArtifactSync, E, ArtifactStore.ArtifactStore | R> =>\n  Layer.effect(ArtifactSync)(\n    Effect.gen(function*() {\n      const local = yield* ArtifactStore.ArtifactStore\n      const shared = yield* remote\n      return make({\n        local,\n        remote: shared,\n        ...(options?.downloadPolicy === undefined ? {} : { downloadPolicy: options.downloadPolicy })\n      })\n    })\n  )\n"]}

package/dist/esm/CacheSync.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The shared step-result tier's publication seam: the remote half of a cache
+ * `put`, run *after* the transaction that made the local row durable.
+ *
+ * `ArtifactSync` is the same idea for the artifact tier, and the two together
+ * are the REAPI ordering constraint
+ * (`reference/bazel/.../remote/UploadManifest.java:630-633`): blobs first, the
+ * entry that references them last.
+ *
+ * This tag exists because of *where* the local row is written.
+ * `ActionPersistence` commits the cache row and the journal record that
+ * explains it in one `DurableWriter` transaction, and nothing that is not
+ * storage work may be held across one — the action body, the Jj snapshot, and
+ * the boundary prepare/settle all already stay outside. A `CacheStore` whose
+ * `put` also writes a shared HTTP tier would put a network round trip inside
+ * that transaction, blocking every other writer for its duration and rolling
+ * the local row back when a *shared cache* is unreachable. So the local put
+ * stays inside and the shared put becomes this service, invoked once the
+ * transaction has committed. Compose it with
+ * `CombinedCacheStore` in `"deferred"` publication mode, which is the mode that
+ * leaves the shared write to this seam.
+ *
+ * Publication is **best-effort by construction**. A shared cache is an
+ * accelerator, and the work it would have shared is already durably recorded on
+ * this host: failing a completed run because an optional tier is unreachable
+ * trades a real result for an unavailable one. A refused publication is
+ * journaled by the caller instead, which is the same treatment an unverified
+ * read set gets — visible, not silent.
+ *
+ * Governing design: `packages/smithers/flows/step-cache/docs/api.md`.
+ *
+ * @since 0.1.0
+ */
+import type { CacheStore } from "@smthrs/step-cache";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+/**
+ * The one operation the shared-cache publication seam exposes.
+ *
+ * It is a single method rather than a store interface on purpose: everything
+ * about reading, keying, and invalidating a cache entry belongs to
+ * `CacheStore`, and all this seam does is take an already-durable local entry
+ * and try to share it.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export interface Service {
+    /**
+     * Publishes a cache entry to the shared tier, reporting the refusal rather
+     * than failing: `Option.none()` means the entry is now shared, and
+     * `Option.some(error)` means it is not and why.
+     *
+     * Callers must only reach here once every artifact the entry references is
+     * durable in the shared artifact tier — that is `ArtifactSync.publish`'s job,
+     * and it runs first.
+     */
+    readonly publishEntry: (entry: CacheStore.CacheEntry) => Effect.Effect<Option.Option<CacheStore.CacheStoreError>>;
+}
+declare const CacheSync_base: Context.ServiceClass<CacheSync, "@smthrs/engine-store/CacheSync", Service>;
+/**
+ * Service tag for the shared step-result publication seam.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export declare class CacheSync extends CacheSync_base {
+}
+/**
+ * The single-tier implementation: there is no shared step-result tier, so a
+ * recorded entry is already everywhere it will ever be.
+ *
+ * This is the default `ActionPersistence` falls back to when the tag is
+ * absent, which is what keeps a purely local composition free of any
+ * remote-cache machinery.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const makeLocal: () => Service;
+/**
+ * Provides the single-tier (no shared step-result store) publication seam.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layerLocal: Layer.Layer<CacheSync>;
+/**
+ * Builds the publication seam over a shared step-result store — typically
+ * `RemoteCacheStore`.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const make: (options: {
+    readonly remote: CacheStore.Service;
+}) => Service;
+/**
+ * Provides the publication seam over the supplied shared store.
+ *
+ * The shared store arrives as an *effect* rather than a layer because it
+ * inhabits the same `CacheStore` tag as the local one: composing both as layers
+ * would shadow one with the other.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layer: <E, R>(remote: Effect.Effect<CacheStore.Service, E, R>) => Layer.Layer<CacheSync, E, R>;
+export {};
+//# sourceMappingURL=CacheSync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CacheSync.d.ts","sourceRoot":"","sources":["../../src/CacheSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,CACrB,KAAK,EAAE,UAAU,CAAC,UAAU,KACzB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAA;CAC9D;;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,cAAuE;CAAG;AAEzG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,QAAO,OAE3B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,CAAyC,CAAA;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAA;CAAE,KAAG,OAYtE,CAAA;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,EACxB,QAAQ,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAC9C,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,CAAsF,CAAA"}

package/dist/esm/CacheSync.js

@@ -0,0 +1,94 @@
+/**
+ * The shared step-result tier's publication seam: the remote half of a cache
+ * `put`, run *after* the transaction that made the local row durable.
+ *
+ * `ArtifactSync` is the same idea for the artifact tier, and the two together
+ * are the REAPI ordering constraint
+ * (`reference/bazel/.../remote/UploadManifest.java:630-633`): blobs first, the
+ * entry that references them last.
+ *
+ * This tag exists because of *where* the local row is written.
+ * `ActionPersistence` commits the cache row and the journal record that
+ * explains it in one `DurableWriter` transaction, and nothing that is not
+ * storage work may be held across one — the action body, the Jj snapshot, and
+ * the boundary prepare/settle all already stay outside. A `CacheStore` whose
+ * `put` also writes a shared HTTP tier would put a network round trip inside
+ * that transaction, blocking every other writer for its duration and rolling
+ * the local row back when a *shared cache* is unreachable. So the local put
+ * stays inside and the shared put becomes this service, invoked once the
+ * transaction has committed. Compose it with
+ * `CombinedCacheStore` in `"deferred"` publication mode, which is the mode that
+ * leaves the shared write to this seam.
+ *
+ * Publication is **best-effort by construction**. A shared cache is an
+ * accelerator, and the work it would have shared is already durably recorded on
+ * this host: failing a completed run because an optional tier is unreachable
+ * trades a real result for an unavailable one. A refused publication is
+ * journaled by the caller instead, which is the same treatment an unverified
+ * read set gets — visible, not silent.
+ *
+ * Governing design: `packages/smithers/flows/step-cache/docs/api.md`.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+/**
+ * Service tag for the shared step-result publication seam.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export class CacheSync extends Context.Service()("@smthrs/engine-store/CacheSync") {
+}
+/**
+ * The single-tier implementation: there is no shared step-result tier, so a
+ * recorded entry is already everywhere it will ever be.
+ *
+ * This is the default `ActionPersistence` falls back to when the tag is
+ * absent, which is what keeps a purely local composition free of any
+ * remote-cache machinery.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const makeLocal = () => ({
+    publishEntry: Effect.fn("CacheSync.publishEntry")(() => Effect.succeed(Option.none()))
+});
+/**
+ * Provides the single-tier (no shared step-result store) publication seam.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerLocal = Layer.succeed(CacheSync)(makeLocal());
+/**
+ * Builds the publication seam over a shared step-result store — typically
+ * `RemoteCacheStore`.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = (options) => ({
+    publishEntry: Effect.fn("CacheSync.publishEntry")((entry) => 
+    // A `Conflict` from the shared tier is not a refusal to report: it means
+    // another machine recorded the key first, which is exactly the
+    // first-writer-wins outcome the shared tier exists to arbitrate. Only a
+    // genuine failure — the tier is down, refused the body, answered with a
+    // status this client cannot classify — is worth journaling.
+    options.remote.put(entry).pipe(Effect.as(Option.none()), Effect.catch((error) => Effect.succeed(Option.some(error)))))
+});
+/**
+ * Provides the publication seam over the supplied shared store.
+ *
+ * The shared store arrives as an *effect* rather than a layer because it
+ * inhabits the same `CacheStore` tag as the local one: composing both as layers
+ * would shadow one with the other.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layer = (remote) => Layer.effect(CacheSync)(Effect.map(remote, (shared) => make({ remote: shared })));
+//# sourceMappingURL=CacheSync.js.map

package/dist/esm/CacheSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheSync.js","sourceRoot":"","sources":["../../src/CacheSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AA4BvC;;;;;GAKG;AACH,MAAM,OAAO,SAAU,SAAQ,OAAO,CAAC,OAAO,EAAsB,CAAC,gCAAgC,CAAC;CAAG;AAEzG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAY,EAAE,CAAC,CAAC;IACvC,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC,wBAAwB,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;CACvF,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAA2B,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC,CAAA;AAEvF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAgD,EAAW,EAAE,CAAC,CAAC;IAClF,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC,wBAAwB,CAAC,CAAC,CAAC,KAA4B,EAAE,EAAE;IACjF,yEAAyE;IACzE,+DAA+D;IAC/D,wEAAwE;IACxE,wEAAwE;IACxE,4DAA4D;IAC5D,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAC5B,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,EAA8B,CAAC,EACpD,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAC5D,CACF;CACF,CAAC,CAAA;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,MAA+C,EACjB,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAA","sourcesContent":["/**\n * The shared step-result tier's publication seam: the remote half of a cache\n * `put`, run *after* the transaction that made the local row durable.\n *\n * `ArtifactSync` is the same idea for the artifact tier, and the two together\n * are the REAPI ordering constraint\n * (`reference/bazel/.../remote/UploadManifest.java:630-633`): blobs first, the\n * entry that references them last.\n *\n * This tag exists because of *where* the local row is written.\n * `ActionPersistence` commits the cache row and the journal record that\n * explains it in one `DurableWriter` transaction, and nothing that is not\n * storage work may be held across one — the action body, the Jj snapshot, and\n * the boundary prepare/settle all already stay outside. A `CacheStore` whose\n * `put` also writes a shared HTTP tier would put a network round trip inside\n * that transaction, blocking every other writer for its duration and rolling\n * the local row back when a *shared cache* is unreachable. So the local put\n * stays inside and the shared put becomes this service, invoked once the\n * transaction has committed. Compose it with\n * `CombinedCacheStore` in `\"deferred\"` publication mode, which is the mode that\n * leaves the shared write to this seam.\n *\n * Publication is **best-effort by construction**. A shared cache is an\n * accelerator, and the work it would have shared is already durably recorded on\n * this host: failing a completed run because an optional tier is unreachable\n * trades a real result for an unavailable one. A refused publication is\n * journaled by the caller instead, which is the same treatment an unverified\n * read set gets — visible, not silent.\n *\n * Governing design: `packages/smithers/flows/step-cache/docs/api.md`.\n *\n * @since 0.1.0\n */\n\nimport type { CacheStore } from \"@smthrs/step-cache\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Option from \"effect/Option\"\n\n/**\n * The one operation the shared-cache publication seam exposes.\n *\n * It is a single method rather than a store interface on purpose: everything\n * about reading, keying, and invalidating a cache entry belongs to\n * `CacheStore`, and all this seam does is take an already-durable local entry\n * and try to share it.\n *\n * @since 0.1.0\n * @category services\n */\nexport interface Service {\n  /**\n   * Publishes a cache entry to the shared tier, reporting the refusal rather\n   * than failing: `Option.none()` means the entry is now shared, and\n   * `Option.some(error)` means it is not and why.\n   *\n   * Callers must only reach here once every artifact the entry references is\n   * durable in the shared artifact tier — that is `ArtifactSync.publish`'s job,\n   * and it runs first.\n   */\n  readonly publishEntry: (\n    entry: CacheStore.CacheEntry\n  ) => Effect.Effect<Option.Option<CacheStore.CacheStoreError>>\n}\n\n/**\n * Service tag for the shared step-result publication seam.\n *\n * @since 0.1.0\n * @category services\n */\nexport class CacheSync extends Context.Service<CacheSync, Service>()(\"@smthrs/engine-store/CacheSync\") {}\n\n/**\n * The single-tier implementation: there is no shared step-result tier, so a\n * recorded entry is already everywhere it will ever be.\n *\n * This is the default `ActionPersistence` falls back to when the tag is\n * absent, which is what keeps a purely local composition free of any\n * remote-cache machinery.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const makeLocal = (): Service => ({\n  publishEntry: Effect.fn(\"CacheSync.publishEntry\")(() => Effect.succeed(Option.none()))\n})\n\n/**\n * Provides the single-tier (no shared step-result store) publication seam.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layerLocal: Layer.Layer<CacheSync> = Layer.succeed(CacheSync)(makeLocal())\n\n/**\n * Builds the publication seam over a shared step-result store — typically\n * `RemoteCacheStore`.\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const make = (options: { readonly remote: CacheStore.Service }): Service => ({\n  publishEntry: Effect.fn(\"CacheSync.publishEntry\")((entry: CacheStore.CacheEntry) =>\n    // A `Conflict` from the shared tier is not a refusal to report: it means\n    // another machine recorded the key first, which is exactly the\n    // first-writer-wins outcome the shared tier exists to arbitrate. Only a\n    // genuine failure — the tier is down, refused the body, answered with a\n    // status this client cannot classify — is worth journaling.\n    options.remote.put(entry).pipe(\n      Effect.as(Option.none<CacheStore.CacheStoreError>()),\n      Effect.catch((error) => Effect.succeed(Option.some(error)))\n    )\n  )\n})\n\n/**\n * Provides the publication seam over the supplied shared store.\n *\n * The shared store arrives as an *effect* rather than a layer because it\n * inhabits the same `CacheStore` tag as the local one: composing both as layers\n * would shadow one with the other.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layer = <E, R>(\n  remote: Effect.Effect<CacheStore.Service, E, R>\n): Layer.Layer<CacheSync, E, R> => Layer.effect(CacheSync)(Effect.map(remote, (shared) => make({ remote: shared })))\n"]}