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

package/docs/guides/reclaim-disk-space.md

@@ -0,0 +1,143 @@
+---
+title: "Reclaim disk space"
+description: "Enumerate an objects directory with ArtifactSweep, delete a blob behind the mtime fence, count only what you actually reclaimed, and hand the policy to the engine collector that owns it."
+sidebar:
+  order: 3
+---
+
+An objects directory grows forever unless something removes from it. This
+package ships the mechanics: enumerate what is there, and delete one blob
+safely. It ships no policy, because deciding which digests are still live needs
+the durable roots, and only the engine composition can see those.
+
+Most projects never call this API directly.
+[`@smthrs/engine-store`](/api/engine-store)'s `ArtifactGc` is the collector
+built on it: its mark phase walks the durable roots, and `gc()` is an explicit
+call that nothing schedules, because deletion is the irreversible direction.
+Note that [`smthrs gc`](/cli/gc) collects terminal runs and does not touch the
+artifact tier at all.
+[Retention and cleanup](/docs/guides/retention/#4-sweep-unreferenced-artifacts)
+is the operator's version of this page. Read on if you are writing a collector
+of your own.
+
+## Before you start
+
+- The objects directory the store publishes into. Get it wrong and you
+  enumerate somewhere nothing was ever written.
+- A live set: the digests something still references. Producing one is your
+  collector's job, not this package's.
+
+## 1. Provide the sweep beside the store
+
+Build both with the same `directory` and the same `coordination`. Nothing
+checks the pairing, and a mismatch is silent:
+
+```ts
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as ArtifactSweep from "@smthrs/artifacts/ArtifactSweep"
+import * as Layer from "effect/Layer"
+
+const directory = ".flows/objects"
+
+export const artifacts = Layer.merge(
+  ArtifactStore.layerFileSystem({ directory, coordination: "required" }),
+  ArtifactSweep.layerFileSystem({ directory, coordination: "required" })
+)
+```
+
+`SweepOptions` has no `durability` field, deliberately: a sweep never writes a
+blob, so accepting the option and ignoring it would be a lie.
+
+## 2. Enumerate what is on disk
+
+`inventory` returns a `BlobStat` for each canonical blob: its digest, its
+modification time in milliseconds, and its size in bytes.
+
+It is conservative by construction. Only paths in the store's canonical fanout
+shape are blobs, so temp files, lock files, foreign files, nested paths, and a
+directory sitting at a blob address are all skipped rather than deleted. A blob
+that vanishes between the listing and the stat was removed by someone else and
+is skipped too. So is one whose modification time the host cannot report: what
+the sweep cannot judge, it must not touch.
+
+A store that never published anything has no directory at all. That is an empty
+inventory, not a failure.
+
+## 3. Delete behind the fence
+
+`RemoveOptions.ifUnmodifiedSinceMs` rides inside the deletion rather than in a
+prior read. A blob freshened after you computed your live set, by a concurrent
+put re-referencing the same bytes, fails the fence and survives:
+
+```ts
+import * as ArtifactSweep from "@smthrs/artifacts/ArtifactSweep"
+import * as Effect from "effect/Effect"
+
+/** Removes every blob outside `live` that has not been touched since `keepAfterMs`. */
+export const collect = (live: ReadonlySet<string>, keepAfterMs: number) =>
+  Effect.gen(function*() {
+    const sweep = yield* ArtifactSweep.ArtifactSweep
+    let reclaimedBytes = 0
+    for (const blob of yield* sweep.inventory) {
+      if (live.has(blob.digest) || blob.modifiedAtMs > keepAfterMs) continue
+      const removed = yield* sweep.remove(blob.digest, { ifUnmodifiedSinceMs: keepAfterMs })
+      if (removed) reclaimedBytes += blob.sizeBytes
+    }
+    return reclaimedBytes
+  })
+```
+
+The inventory check is the cheap filter; the fence in `remove` is the one that
+actually holds, because the world can change between the two.
+
+`keepAfterMs` is where a grace period lives. Pick an instant far enough in the
+past that a blob published or freshened while your mark phase was running
+survives this pass: `ArtifactGc` defaults to two weeks.
+
+## 4. Read the boolean correctly
+
+`remove` reports whether bytes were removed. A missing blob reports `false`
+rather than failing, so a crashed and re-run sweep converges instead of erroring
+on its own progress.
+
+`false` covers three outcomes a caller cannot tell apart:
+
+- The blob was already gone.
+- It failed the `ifUnmodifiedSinceMs` fence.
+- A live backup lease fenced the deletion.
+
+All three mean nothing was reclaimed and retrying later is safe. The third is
+not progress: the blob is still there, so a collector counting reclaimed bytes
+must not count it, and the next pass after the backup finishes removes it. The
+loop above already gets this right by adding `blob.sizeBytes` only on `true`.
+
+## 5. Budget for the coordination cost
+
+Under `coordination: "required"`, one deletion takes the per-digest lock and
+then the workspace-global backup-lease gate: roughly ten filesystem operations
+and two forked heartbeat fibers per blob. The gate is one file for the whole
+workspace, so concurrent deletions serialize through it.
+
+That is the price of never deleting a blob a running backup already recorded.
+Size a collection window with it in mind rather than assuming one unlink per
+blob.
+
+## Verify it worked
+
+Count the blobs before and after:
+
+```bash
+find .flows/objects -type f -name '????????????????????????????????????????????????????????????????' | wc -l
+```
+
+The name pattern matches a 64-character digest, so temp and lock files stay out
+of the count.
+
+## Related
+
+- [Fence a backup against the sweep](./fence-a-backup.md): the other side of
+  the lease this sweep consults.
+- [Coordination between processes](../concepts/coordination.md): the lock
+  protocol, its bounds, and what still holds when the lock does not.
+- [Retention and cleanup](/docs/guides/retention/): the operator's runbook on
+  smithers.sh.

package/docs/guides/serve-the-artifact-protocol.md

@@ -0,0 +1,140 @@
+---
+title: "Serve the artifact protocol"
+description: "The HTTP surface a shared artifact tier owes RemoteArtifacts: four requests, the status codes that mean hit, miss, and failure, the body bounds, and the optional resumable upload sequence."
+sidebar:
+  order: 2
+---
+
+`RemoteArtifacts` speaks a dumb-HTTP content-addressed cache protocol, the one
+Bazel's `HttpCacheClient` documents, with two additions. If you are writing the
+service on the other end, this page is the contract.
+
+Every digest in a path or a body is 64 lowercase hexadecimal characters. The
+client validates that before a request leaves, so a malformed address never
+reaches your service.
+
+## The four requests
+
+All paths are resolved beneath the configured endpoint. A trailing slash on the
+endpoint is ignored.
+
+| Request                 | Conforming answer                                    | Anything else                          |
+| ----------------------- | ---------------------------------------------------- | -------------------------------------- |
+| `GET /cas/{digest}`     | `2xx` with the blob bytes, or `404` for a miss       | Fails the read as `transport_failed`   |
+| `PUT /cas/{digest}`     | Any `2xx` once the blob is durable                   | Fails the upload as `transport_failed` |
+| `HEAD /cas/{digest}`    | `2xx` when the blob is present, `404` when it is not | Fails the probe as `transport_failed`  |
+| `POST /cas/findMissing` | `200` with `{"missing":[...]}`                       | Fails the batch as `transport_failed`  |
+
+`404` is the only status that means "miss". Every other non-2xx is a failure of
+the tier, which is the only classification a dumb-HTTP cache can support,
+because there is no richer error envelope on the wire.
+
+## What the client does with your answers
+
+Knowing this saves you from defending against problems the client already
+handles, and from assuming defenses it does not have.
+
+- **Every download is digest verified.** A `GET` body that does not hash to the
+  requested address is rejected with `ArtifactCorruption`, never returned. Your
+  service cannot substitute content, and it does not need to prove it did not.
+- **An absent body is zero bytes, not an error.** The digest check decides
+  whether empty content is the requested artifact.
+- **`Content-Length` is read strictly.** It must be plain decimal digits naming
+  a safe integer. A malformed one fails the read before the body is buffered.
+- **Downloads are bounded.** A declared length past `maxDownloadBytes`, 256 MiB
+  by default, is refused before a body byte is read, and an incremental read
+  stops one chunk past the bound.
+- **`findMissing` answers are filtered.** The client keeps only digests it
+  asked about, in request order. A digest you return that nobody asked for
+  makes the client upload nothing.
+
+## The findMissing body
+
+Request, sent as `application/json`:
+
+```json
+{ "digests": ["077303668cf56af8d162bb5ccccd7127f2e8baff448bf5b649530a98e9c943da"] }
+```
+
+Response, also JSON:
+
+```json
+{ "missing": ["077303668cf56af8d162bb5ccccd7127f2e8baff448bf5b649530a98e9c943da"] }
+```
+
+The client enforces three bounds on its side, and a conforming service can rely
+on them:
+
+| Bound               | Value                                                                                                         |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Digests per request | At most 1,000. A larger input is split into several batches.                                                  |
+| Request body        | At most 256 KiB, which the 1,000-digest cap already guarantees.                                               |
+| Response body       | At most `maxFindMissingResponseBytes`, 256 KiB by default, and that option may only lower the protocol bound. |
+
+An empty input never leaves the process, so your service never sees a
+zero-digest batch.
+
+## The optional resumable upload
+
+A client with `RemoteArtifacts.Options.chunkBytes` set sends a large blob as a
+sequence of ranged `PUT` requests. Supporting this is optional, and refusing it
+correctly costs the client one round trip.
+
+The sequence is:
+
+1. `HEAD /cas/{digest}`. Answer `2xx` with a `Content-Length` equal to the
+   whole blob if you already hold it, and the client sends nothing more.
+2. `PUT /cas/{digest}` with `Content-Range: bytes */{total}` and an empty body.
+   Answer `308` with `Range: bytes=0-{last}` naming the prefix you hold, or
+   omit the header if you hold none.
+3. `PUT /cas/{digest}` with `Content-Range: bytes {a}-{b}/{total}` per chunk.
+   Answer `308` to continue, and a `2xx` on the chunk that completes the blob.
+4. `HEAD /cas/{digest}` again. The client confirms the stored length before it
+   reports the digest as published.
+
+Only `308` continues the sequence. A `2xx` to the empty probe, or to a chunk
+that does not complete the blob, reads as a tier that ignored `Content-Range`
+and stored the body it was handed, which is what plain WebDAV `PUT` does.
+
+**To refuse ranged uploads,** answer `400`, `411`, or `416`. `400` is RFC 9110
+section 14.5's answer from a resource that does not support partial `PUT`, and
+it is what the [reference implementation](#the-reference-implementation) below
+sends. The client then sends one whole-blob `PUT`, which overwrites any partial
+body the sequence left behind, so the blob always lands whole.
+
+Falling back on `400` cannot mask a genuine `400` from your service: the
+whole-blob `PUT` that follows presents the same URL, digest, and credential, so
+a real refusal comes straight back on that request.
+
+## The reference implementation
+
+Smithers ships a conforming service, deployed as a Cloudflare Worker over R2
+and D1, and a self-hosted build of the same protocol. Its behavior is a useful
+default when you are deciding what your own should do:
+
+| Request                 | What it does                                                                             |
+| ----------------------- | ---------------------------------------------------------------------------------------- |
+| `GET /cas/{digest}`     | Streams the object as `application/octet-stream`; missing objects return `404`           |
+| `PUT /cas/{digest}`     | Hashes the complete upload before an atomic publication; a digest mismatch returns `400` |
+| `HEAD /cas/{digest}`    | Checks for the object without returning a body; missing objects return `404`             |
+| `POST /cas/findMissing` | Accepts `{"digests":[...]}` and returns unique missing digests in request order          |
+
+Its bounds: a `/cas` upload is capped at 16 MiB and must be
+`application/octet-stream`; a `findMissing` request is capped at 256 KiB, 1,000
+digests, and `application/json`. Reads accept either credential; `PUT` and
+`DELETE` require the write credential and answer `403` to the read one, before
+the request body is read.
+
+Because it caps a request body at 16 MiB and refuses ranged `PUT` with `400`, a
+blob larger than 16 MiB is refused with `413` whether or not `chunkBytes` is
+set. See [`@smthrs/build`](https://github.com/smithersai/smithers/tree/main/packages/smithers/build) for how that service is
+deployed and configured.
+
+## Related
+
+- [Share artifacts across machines](./share-artifacts-across-machines.md): the
+  client side of this protocol.
+- [The three tiers](../concepts/tiers.md): what the combined store does with a
+  miss, a failure, and a corrupt address.
+- [Troubleshooting](../troubleshooting.md): the transport failures a
+  nonconforming answer produces.

package/docs/guides/share-artifacts-across-machines.md

@@ -0,0 +1,180 @@
+---
+title: "Share artifacts across machines"
+description: "Compose a local filesystem store behind an HTTP cache with CombinedArtifacts, choose a download policy, and set the deadlines and chunk size the shared tier needs."
+sidebar:
+  order: 1
+---
+
+A machine that reads an artifact another machine produced needs two tiers: the
+fast local one it owns, and a shared HTTP one it does not. `CombinedArtifacts`
+composes them so a read tries local first and a write is durable locally before
+the network is involved at all.
+
+## Before you start
+
+- A shared cache endpoint that speaks the artifact protocol. It must be HTTPS,
+  unless its host is loopback, and it may carry no userinfo, query, or fragment. If you are standing one up,
+  see [Serve the artifact protocol](./serve-the-artifact-protocol.md).
+- The credential the endpoint expects, as a header value.
+- An `HttpClient` in scope. `FetchHttpClient.layer` from `effect` is enough.
+
+## 1. Build the shared tier
+
+`RemoteArtifacts.make` validates its options and returns a store. The endpoint
+and its headers are construction options, never step inputs: a credential that
+arrived as an input would be hashed into a step key and persisted everywhere
+the journal goes.
+
+```ts
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as CombinedArtifacts from "@smthrs/artifacts/CombinedArtifacts"
+import * as RemoteArtifacts from "@smthrs/artifacts/RemoteArtifacts"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Path from "effect/Path"
+
+declare const token: string
+
+const combined = Effect.gen(function*() {
+  const fileSystem = yield* FileSystem.FileSystem
+  const local = ArtifactStore.makeFileSystem(fileSystem, yield* Path.Path)
+  const remote = yield* RemoteArtifacts.make({
+    endpoint: "https://cas.example.com",
+    headers: { authorization: `Bearer ${token}` }
+  })
+  return yield* CombinedArtifacts.make({ local, remote })
+})
+```
+
+Construction fails with `invalid_configuration` for a value that is not a
+string, one no `URL` parser accepts, a scheme other than `https:`, and an
+endpoint carrying userinfo, a query, or a fragment. The refusal names only the
+violated rule and never echoes the endpoint, so a rejected
+`https://user:secret@host` cannot leak its credential into a log line.
+
+Your own headers are applied first and the protocol's are applied after, so no
+configuration can strip the `content-type`, `content-length`, or
+`content-range` the tier needs to interpret the body.
+
+## 2. Provide the composition as a layer
+
+`CombinedArtifacts.layer` takes both tiers as effects rather than layers,
+because both inhabit the `ArtifactStore` tag and merging two layers of one tag
+would shadow one with the other:
+
+```ts
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as CombinedArtifacts from "@smthrs/artifacts/CombinedArtifacts"
+import * as RemoteArtifacts from "@smthrs/artifacts/RemoteArtifacts"
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Path from "effect/Path"
+
+declare const token: string
+
+export const sharedArtifacts = CombinedArtifacts.layer({
+  local: Effect.map(
+    Effect.all([FileSystem.FileSystem, Path.Path]),
+    ([fs, path]) => ArtifactStore.makeFileSystem(fs, path, { directory: ".flows/objects" })
+  ),
+  remote: RemoteArtifacts.make({
+    endpoint: "https://cas.example.com",
+    headers: { authorization: `Bearer ${token}` },
+    downloadPolicy: "toplevel",
+    chunkBytes: 8 * 1024 * 1024
+  })
+})
+```
+
+The layer requires whatever its two effects require, here a `FileSystem`, a
+`Path`, and an `HttpClient`, and it provides `ArtifactStore` to everything above it.
+
+## 3. Choose a download policy
+
+The policy answers one question: how eagerly does this machine copy other
+machines' artifacts onto its own disk?
+
+| Choose     | When                                                                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `all`      | The default. A long-lived machine that will read most of what it fetches, and wants replay to read local bytes.                                   |
+| `toplevel` | A machine that should not prefetch a whole run's artifacts, but should keep the ones it actually reads.                                           |
+| `minimal`  | An ephemeral or disk-constrained host: a CI container, a sandbox. Reads are served straight from the shared tier and the local store never grows. |
+
+Declare it once on the shared tier, as above, and every composition reading
+through that tier inherits it. `CombinedArtifacts.Options.downloadPolicy`
+overrides it for one composition when a single host needs to differ.
+
+`minimal` still writes back after local corruption. That is repair of an
+address the local tier already claims, not growth.
+
+## 4. Set the deadlines
+
+Every remote exchange is bounded, and every bound defaults to 60 seconds,
+Bazel's `--remote_timeout` default for the same protocol:
+
+| Option                                    | Covers                                                                            |
+| ----------------------------------------- | --------------------------------------------------------------------------------- |
+| `RemoteArtifacts.Options.downloadTimeout` | One download, including the complete response body                                |
+| `RemoteArtifacts.Options.uploadTimeout`   | One upload, including every resume probe and chunk                                |
+| `RemoteArtifacts.Options.requestTimeout`  | One `HEAD` probe, or one `findMissing` batch and its response                     |
+| `CombinedArtifacts.Options.uploadTimeout` | How long a combined `put` waits for its opportunistic upload before abandoning it |
+
+Two more bounds protect this process from a mis-serving tier.
+`maxDownloadBytes` defaults to 256 MiB: a `Content-Length` past the bound is
+refused before a body byte is read, and an incremental read stops the moment it
+crosses. `maxFindMissingResponseBytes` defaults to the protocol's 256 KiB and
+may only lower that bound.
+
+## 5. Turn on chunked uploads, if your tier supports them
+
+With `chunkBytes` set, a blob past that size travels as a sequence of
+`Content-Range` `PUT` requests, preceded by a `HEAD` existence probe and an
+empty `bytes */{total}` probe that asks what prefix the tier already holds.
+
+| Tier's answer                 | Client action                                              |
+| ----------------------------- | ---------------------------------------------------------- |
+| `308`                         | Continue after the reported `Range: bytes=0-{last}` prefix |
+| `2xx` on the completing chunk | Confirm the stored length with `HEAD`                      |
+| `2xx` before completion       | Treat the tier as range-unaware and send the whole blob    |
+| `400`, `411`, or `416`        | Send the whole blob                                        |
+| Anything else                 | Fail the upload as a transport error                       |
+
+The offset never moves backward, and a tier that ignores ranges, omits a
+confirming length, or keeps only part of the body gets one whole-blob `PUT`
+that overwrites whatever the sequence left behind. So the cost of turning the
+dial on against a server that never learned about it is round trips, never a
+digest published over bytes the server does not hold.
+
+Set it when a proxy caps request bodies, or when artifacts are large enough
+that losing a transfer partway is expensive. It is absent by default.
+
+The hosted and self-hosted Smithers cache services do not implement the
+resumable sequence: both answer a ranged `PUT` with `400` and cap one request
+body at 16 MiB. Against them `chunkBytes` costs the probe round trip
+and the blob travels whole, and a blob past 16 MiB is refused with `413` in
+either mode.
+
+## What you get
+
+A read that misses locally reaches the shared tier, and the fetched bytes are
+digest verified before they are returned, because the shared tier is the least
+trusted store there is: it is written by machines this one has never met. A
+mis-serving or compromised cache can waste a round trip; it can never
+substitute content.
+
+A write is durable locally before the upload starts, and the upload's failure
+is dropped rather than propagated. Ordering between the artifact tier and the
+step cache is not this package's job:
+[`@smthrs/engine-store`](/api/engine-store)'s `ArtifactSync` enforces that a
+cache entry is never observable in the shared tier while an artifact it
+references is missing from the shared artifact tier.
+
+## Related
+
+- [The three tiers](../concepts/tiers.md): what falls through, what does not,
+  and why.
+- [Serve the artifact protocol](./serve-the-artifact-protocol.md): the HTTP
+  surface a conforming shared tier owes.
+- [Share results with artifacts and the step cache](/docs/guides/artifacts-cache/):
+  the end-to-end composition on smithers.sh, including the step cache's own
+  shared tier.

package/docs/guides/test-against-an-artifact-store.md

@@ -0,0 +1,158 @@
+---
+title: "Test against an artifact store"
+description: "Use the in-memory store as the default test tier, the no-op stores with per-method overrides to script a refusing host, and a real loopback server to exercise the HTTP tier."
+sidebar:
+  order: 5
+---
+
+Every tier in this package is a value you construct, so a test swaps the tier
+rather than mocking a module. Three substitutions cover almost everything:
+memory for a real directory, a no-op with overrides for a refusing host, and a
+loopback server for the shared tier.
+
+## Use the memory store as the default
+
+`ArtifactStore.makeMemory()` needs no directory, no temporary files, and no
+cleanup, and it computes real digests through the same `Crypto` service the
+filesystem store uses:
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as Effect from "effect/Effect"
+
+const payload = new TextEncoder().encode("a step's output")
+
+const roundTrip = Effect.gen(function*() {
+  const store = ArtifactStore.makeMemory()
+  const digest = yield* store.put(payload)
+  return new TextDecoder().decode(yield* store.get(digest))
+})
+
+const result = await Effect.runPromise(roundTrip.pipe(Effect.provide(NodeCrypto.layer)))
+```
+
+It copies on both boundaries, so a test that mutates the array it put still
+reads the original bytes back. What it does not do is verify a read, because
+its address space is private and cannot disagree with itself. A test that needs
+a corrupt address needs the filesystem store and a directory to tamper with, as
+in the [Quickstart](../quickstart.md#corrupt-a-blob-then-heal-it).
+
+To assert on the address without hard-coding a digest, measure it the same way
+the store does:
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as Effect from "effect/Effect"
+
+const expectedAddress = await Effect.runPromise(
+  ArtifactStore.measureBytes(new TextEncoder().encode("payload")).pipe(Effect.provide(NodeCrypto.layer))
+)
+```
+
+## Script a refusing host with the no-op stores
+
+`makeNoop` fails every operation with an `unavailable` `ArtifactStoreError`,
+and takes per-method overrides, so a test states exactly the one behavior it
+cares about:
+
+```ts
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as Effect from "effect/Effect"
+
+/** A store whose reads always refuse, to prove a caller does not fall through. */
+export const offline = ArtifactStore.makeNoop({
+  get: () =>
+    Effect.fail(
+      new ArtifactStore.ArtifactStoreError({ code: "unavailable", message: "the host filesystem is offline" })
+    )
+})
+```
+
+`ArtifactSweep.makeNoop` and `ArtifactSweep.layerNoop` work the same way:
+
+```ts
+import * as ArtifactSweep from "@smthrs/artifacts/ArtifactSweep"
+import * as Effect from "effect/Effect"
+
+/** A sweep that enumerates nothing, so a collector's empty path is exercised. */
+export const sweepless = ArtifactSweep.layerNoop({
+  inventory: Effect.succeed([])
+})
+```
+
+Use these to pin the distinctions the combined store makes. A local tier whose
+`get` fails with `ArtifactStoreError` must not fall through to the shared tier;
+one that fails with `ArtifactMissing` must.
+
+## Compose two memory tiers
+
+`CombinedArtifacts` does not care what its tiers are, so the whole read-through
+and write-back contract is testable with two maps:
+
+```ts
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as CombinedArtifacts from "@smthrs/artifacts/CombinedArtifacts"
+import * as Effect from "effect/Effect"
+
+const shared = Effect.gen(function*() {
+  const local = ArtifactStore.makeMemory()
+  const remote = ArtifactStore.makeMemory()
+  return yield* CombinedArtifacts.make({ local, remote })
+})
+```
+
+Seed the remote tier, read through the combination, and then probe the local
+tier's `has` to prove whether the download policy wrote back.
+
+## Exercise the HTTP tier over a real socket
+
+`RemoteArtifacts` accepts plain HTTP only for a loopback host. To exercise the
+HTTPS authority a deployment declares, run a loopback HTTP server and rewrite
+that authority onto its port, so the request, body, status code, and
+connection are all real and only TLS termination is missing:
+
+```ts
+import * as FetchHttpClient from "effect/http/FetchHttpClient"
+import * as Layer from "effect/Layer"
+
+/** The real fetch transport, with a declared HTTPS authority mapped to `port`. */
+const transport = (port: number) =>
+  Layer.provide(
+    FetchHttpClient.layer,
+    Layer.succeed(
+      FetchHttpClient.Fetch,
+      ((input, init) => {
+        const href = input instanceof URL ? input.href : typeof input === "string" ? input : (input as Request).url
+        const url = new URL(href)
+        url.protocol = "http:"
+        url.host = `127.0.0.1:${port}`
+        return globalThis.fetch(url, init)
+      }) as typeof globalThis.fetch
+    )
+  )
+```
+
+Then build the store against `https://cas.test` and provide `transport(port)`.
+A stub `HttpClient` is the right tool for header-by-header assertions about a
+single request; a real socket is the only way to assert that an interrupted
+transfer resumes from the prefix a real server kept.
+
+## What not to stub
+
+Do not replace the digest check. It is the invariant the whole package exists
+to hold, and a test that stubs it proves nothing about the code that ships. To
+test the corruption path, corrupt a real blob and let the real `get` refuse it.
+
+Do not stub the `Crypto` service to return a constant either. Real digests are
+cheap, and a constant digest makes deduplication, `findMissing`, and the
+corruption check all indistinguishable from each other.
+
+## Related
+
+- [Quickstart](../quickstart.md): the corruption and repair path against a real
+  directory.
+- [The three tiers](../concepts/tiers.md): the distinctions your assertions
+  should pin.
+- [API reference](../api.md): every constructor and its overrides.