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

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 Layer from "effect/Layer"
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient"
+
+/** 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.

package/docs/installation.md

@@ -0,0 +1,98 @@
+---
+title: "Installation"
+description: "Install @smthrs/artifacts, the runtime it requires, the Effect services each tier needs in scope, and the public import forms."
+sidebar:
+  order: 1
+---
+
+## Install the package
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+The package requires Node.js 26.4.0 or later and ships as both ESM and
+CommonJS with TypeScript declarations. It has exactly two runtime dependencies,
+[`effect`](https://effect.website) and [`@smthrs/crypto`](/api/crypto), and both
+install with it.
+
+## What each tier needs in scope
+
+Nothing in this package opens a file or a socket by itself. Every host effect
+goes through an Effect service, which is what lets the same code run in Node,
+in Bun, in a browser tab, and inside a sandbox:
+
+| Service                                                        | Needed by                                         | Node layer              |
+| -------------------------------------------------------------- | ------------------------------------------------- | ----------------------- |
+| `Crypto.Crypto` from `effect/Crypto`                           | `put` and `get` on every store                    | `NodeCrypto.layer`      |
+| `FileSystem.FileSystem` from `effect/FileSystem`               | the filesystem store, the sweep, the backup lease | `NodeFileSystem.layer`  |
+| `Path.Path` from `effect/Path`                                 | the filesystem store                              | `NodePath.layer`        |
+| `HttpClient.HttpClient` from `effect/unstable/http/HttpClient` | `RemoteArtifacts`                                 | `FetchHttpClient.layer` |
+
+`has` and `findMissing` never hash anything, so they do not require `Crypto`.
+The memory and no-op stores require no `FileSystem` or `Path` at all, which is what makes
+them usable in a browser and in a test with no temporary directory.
+
+The Node implementations live in `@effect/platform-node`:
+
+```bash
+pnpm add @effect/platform-node@4.0.0-rc.115 @effect/platform-node-shared@4.0.0-rc.115
+```
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
+import * as NodePath from "@effect/platform-node/NodePath"
+import * as Layer from "effect/Layer"
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient"
+
+/** Everything every tier in this package can ask for. */
+export const host = Layer.mergeAll(NodeCrypto.layer, NodeFileSystem.layer, NodePath.layer, FetchHttpClient.layer)
+```
+
+`FetchHttpClient` ships inside `effect`, so the shared tier adds no dependency
+of its own.
+
+## Import forms
+
+The root entry point re-exports every module as a namespace:
+
+```ts
+import {
+  ArtifactBackupLease,
+  ArtifactStore,
+  ArtifactStoreMetrics,
+  ArtifactSweep,
+  CombinedArtifacts,
+  RemoteArtifacts
+} from "@smthrs/artifacts"
+```
+
+Each module is also importable from its own subpath, which is the form the
+guides and the [API reference](./api.md) use:
+
+```ts
+import * as ArtifactStore from "@smthrs/artifacts/ArtifactStore"
+import * as ArtifactSweep from "@smthrs/artifacts/ArtifactSweep"
+```
+
+Two subpath forms are blocked in the export map and are not public API:
+`@smthrs/artifacts/internal/*` and `@smthrs/artifacts/*/index`.
+`@smthrs/artifacts/package.json` is exported.
+
+## What a full composition adds
+
+A host that spills step outputs into this store composes it with the engine
+packages.
+
+- [`@smthrs/engine-store`](/api/engine-store) owns `StepBoundary`, which decides
+  when a step output is inline and when it is spilled here by digest. It also
+  owns `ArtifactGc`, the mark half of collection that drives `ArtifactSweep`,
+  and `ArtifactSync`, which honors the download policy on replay.
+- [`@smthrs/step-cache`](/api/step-cache) maps a step key to the recorded result
+  that references those digests.
+
+The end-to-end composition, from a flow to a shared cache, is on smithers.sh in
+[Share results with artifacts and the step cache](/docs/guides/artifacts-cache/).
+
+## Next step
+
+Publish and read your first artifact in the [Quickstart](./quickstart.md).