@defrex/autobuild 0.8.0 → 0.10.0

package/docs/hosted-dispatcher.md

@@ -1,19 +1,24 @@
 # The hosted dispatcher
 
-The optional [hosted service](../packages/hosted-store-service/README.md) can
-own the dispatch kernel. One authenticated HTTP endpoint — `GET /api/dispatch`
-— runs, for each configured repository, one bounded origin-mode dispatcher
+The optional [`@defrex/autobuild-hosted-dispatcher`](../packages/hosted-dispatcher/README.md)
+package lets a deployment own the dispatch kernel. Installing it and mounting
+its route — `GET /api/dispatch`, backed by the package's
+`dispatcherEndpoint()` singleton — makes the hosted deployment the kernel
+owner. One authenticated HTTP invocation runs, for each configured
+repository, one bounded origin-mode dispatcher
 tick: the kernel claims ready tickets, provisions and launches sandboxes,
 observes running builds, settles publications, opens and merges PRs, and runs
 the janitor, exactly as a local `ab dispatch --once --repository <origin>`
 pass does. The schedule is what you attach to that endpoint (Vercel Cron calls
 it once a minute by default), so builds no longer depend on a maintainer's
-machine.
+machine. A deployment that does not install the package serves the hosted
+store, ticket, operator, and web endpoints and never attempts a dispatch tick.
 
 ## Enabling the schedule
 
-1. Deploy the hosted service with the dispatcher variables from
-   [its README](../packages/hosted-store-service/README.md#hosted-dispatcher)
+1. Deploy the hosted service with the dispatcher package installed and the
+   dispatcher variables from
+   [its README](../packages/hosted-dispatcher/README.md)
    — `AB_DISPATCHER_ORIGIN`, the repository set, `CRON_SECRET`, and the forge
    credentials the kernel needs (`GITHUB_TOKEN` or `GH_TOKEN`, plus any
    guest-forwarded variables such as `AI_GATEWAY_API_KEY`). A deployment
@@ -44,26 +49,77 @@ Every sandbox installs the Autobuild distribution the launching dispatcher
 runs. A local dispatcher packs it from its source checkout with `bun pm pack`;
 a bundled deployment has neither `bun` nor a source tree at runtime, so it
 must pack the archive while both exist — in its build step — and carry it into
-the function bundle:
+the function bundle. The script lives in the hosted store service package
+(`packages/hosted-store-service/package.json`), whose directory is the Next.js
+project directory and the deployment build's working directory:
 
 ```json
-{ "scripts": { "deploy:build": "bun packages/hosted-store-service/src/bin.ts pack-distribution && bun run postgres:migrate && bun run build && bun tools/ship-packed-distribution.ts" } }
+{ "scripts": { "deploy:build": "bun ../../packages/hosted-dispatcher/src/bin.ts pack-distribution --root . && bun ../../packages/postgres-store/src/bin.ts migrate && bun run build && bun ../../packages/hosted-dispatcher/src/ship-packed-distribution.ts && bun ../../packages/hosted-dispatcher/src/ship-provider-plugin.ts" } }
 ```
 
-`pack-distribution` writes `.autobuild-dist/autobuild-<version>.tgz` under the
-distribution root (`--root DIR` overrides). The Next.js config's
+`pack-distribution` (the `ab-hosted-dispatcher` bin) writes
+`.autobuild-dist/autobuild-<version>.tgz` under the
+distribution root (`--root DIR` overrides) — this deployment passes
+`--root .`, because the packer's default root is the repository's distribution
+root while the trace step below and the Next config's
 `outputFileTracingIncludes: { '/api/dispatch': ['./.autobuild-dist/**'] }`
-records the intent to include that directory in the cron route's bundle, but
+resolve against the deployment build's working directory, where the archive
+must land beside the built output. The Next.js config's
+`outputFileTracingIncludes` records the intent to include that directory in the cron route's bundle, but
 Next 16's default Turbopack builds never apply `outputFileTracingIncludes`
 (only webpack builds do), so a deployment cannot rely on the config alone. The
 autobuild-api pipeline therefore ends `deploy:build` with a post-build trace
-step (`bun tools/ship-packed-distribution.ts`) that appends the archive to the
+step (`bun ../../packages/hosted-dispatcher/src/ship-packed-distribution.ts`) that appends the archive to the
 dispatch route's `route.js.nft.json` — the trace file Vercel's Next builder
 consumes when assembling the function bundle — and fails the deploy loudly if
-nothing was packed or the trace file is missing. A deployment using this
+nothing was packed or the trace file is missing. The same step appends the
+distribution root's `package.json`, which provisioning reads for the running
+version and which no import traces once the Next.js project directory sits
+below the repository root. A deployment using this
 pipeline cannot ship without the archive; deployments that skip both packing
 and the trace step still fail at runtime.
 
+A second post-build trace step ships the provider plugin package (AUT-517):
+`bun ../../packages/hosted-dispatcher/src/ship-provider-plugin.ts` locates the
+plugin's source through the repository root's `workspaces` tree (never through
+`node_modules`, so a previous run's staged directory cannot shadow the source),
+bundles its entrypoint with `bun build --target=bun --format=esm` into a
+single self-contained module (the plugin-sdk closure inlines — the
+deployment's repository-root `node_modules` carries no `@defrex/autobuild`
+either — while node builtins stay external), stages it into
+`<repoRoot>/node_modules/@defrex/autobuild-vercel-sandbox/` (replacing the
+workspace symlink a local `bun install` leaves there — or a previous run's
+staged directory, which `bun install` does not relink; the deployment never
+runs `bun install` again), and appends the staged files to the dispatch
+route's trace at the same repository-root depth as the existing
+`node_modules/.bun/**` entries. A bare plugin specifier resolves only
+through a `node_modules/` path, and the compiled dispatcher's
+`distributionRoot()` is the repository root, so only this staging makes
+`plugins = ["@defrex/autobuild-vercel-sandbox"]` loadable inside the
+deployed function. The step is idempotent across runs — including in a
+fresh process after an earlier run consumed the workspace link — and fails
+the deploy loudly when the package, its entrypoint, or the trace file is
+missing. The npm published package remains the real `src` — only the
+deployment stages the bundle.
+
+What the staged directory does afterwards depends on the build environment.
+Inside a Vercel deployment build (which always sets `VERCEL`, including a
+local `vercel build` run) the staged directory stays: the deployment never
+runs `bun install` again and the function bundle's runtime resolution needs
+it — a deployment building outside Vercel must set `VERCEL=1` in its build
+environment to keep the staged bundle. A plain local `bun run deploy:build`
+(no `VERCEL` environment) removes the staged directory afterwards and
+restores the workspace symlink, so a local run leaves the checkout exactly
+as `bun install` had it and local test runs keep resolving the workspace
+source (the capability parity test's reference equality holds). On checkouts
+of older versions the staged directory stayed behind and survived `bun
+install` — it reports "no changes" because the staged package satisfies the
+manifest — so later local runs resolved the plugin to the self-contained
+bundle and the parity test failed on its reference-equality assertion; the
+recovery is `rm -rf node_modules/@defrex/autobuild-vercel-sandbox && bun
+install`, or simply re-run `deploy:build` locally on a version with this
+fix, which restores the symlink itself.
+
 At runtime the kernel takes, in order: `AB_DISTRIBUTION_ARCHIVE` (an explicit
 archive path), the single archive under `.autobuild-dist/` of the
 distribution root or working directory, a source checkout packed on the spot,

package/docs/operator-api.md

@@ -1,9 +1,9 @@
 # Operator API v1
 
 The hosted service exposes the polling-oriented operator surface at
-`/operator/v1/repos/{repo}`. It is versioned with remote store protocol **2**.
+`/operator/v1/repos/{repo}`. It is versioned with remote store protocol **3**.
 Every request must send `X-Autobuild-Version`,
-`X-Autobuild-Protocol-Version: 2`, and `Authorization: Bearer …`. Identity is
+`X-Autobuild-Protocol-Version: 3`, and `Authorization: Bearer …`. Identity is
 checked before authentication or resource lookup.
 
 Mint a token offline; the signed user is used as the human actor on every write:

package/docs/remote-store-protocol.md

@@ -20,7 +20,7 @@ document and the package's executable contracts together.
   `AB_STORE`; the shipped client appends the routes below.
 - Every `/builds`, `/repos`, and `/sessions` request sends
   `X-Autobuild-Version` with the exact client package version and
-  `X-Autobuild-Protocol-Version` with the remote protocol version (`2` in this
+  `X-Autobuild-Protocol-Version` with the remote protocol version (`3` in this
   distribution). Before authentication,
   body parsing, or resource lookup, the server compares both exact strings.
   Missing or different values receive `409 {"kind":"conflict","error":"…"}`;
@@ -290,13 +290,15 @@ it to exist. An unknown build returns `404 not-found`.
 
 | BuildStore operation | HTTP route | Request | Success |
 |---|---|---|---|
-| `createBuild` | `POST /builds` | `{slug: string, repo: string, repoOrigin?: string, ticket?: TicketRef, branch?: string}`; `slug`, `repo`, and a supplied `branch` are nonempty | `201` + `BuildRecord`; duplicate slug is `409 conflict` |
+| `createBuild` | `POST /builds` | `{slug: string, repo: string, repoOrigin?: string, ticket?: TicketRef, branch?: string, created?: event write}`; `slug`, `repo`, and a supplied `branch` are nonempty. `created`, when present, must be a valid `build.created` write; the server appends it as seq 1 atomically with the record (both exist or neither), and an invalid one is `422` with nothing created | `201` + `BuildRecord`; duplicate slug is `409 conflict` |
 | `listBuilds` | `GET /builds` | none | `200` + `BuildRecord[]`; list order is unspecified |
 | `getBuild` | `GET /builds/{slug}` | none | `200` + `BuildRecord`; absent is `404` (the shipped client maps this to `null`) |
 | `append` | `POST /builds/{slug}/events` | event write | `201` + build event envelope |
 | `appendIfCurrent` | `POST /builds/{slug}/events/conditional` | `{"expectedSeq": nonnegative integer, "event": event write}` | appended: `201` + build event envelope; stream advanced: `200 null` |
 | `getEvents` | `GET /builds/{slug}/events?since={n}&wait={s}` | optional `since` query value, parsed below; absence defaults to `0`. Optional `wait` in whole seconds, parsed per the event-wait rules below | `200` + envelopes whose `seq` is strictly greater than parsed `since`, in increasing sequence order |
 | `appendWithArtifacts` | `POST /builds/{slug}/deposits` | atomic deposit request | `201` + `{event, artifacts}` |
+| `getReducerSnapshot` | `GET /builds/{slug}/snapshots/{reducer}?version={n}` | required `version` query value, a positive integer; `reducer` is a registry name (`^[A-Za-z][A-Za-z0-9._-]{0,63}$`) | `200` + `{"version", "cursor", "state"}` or `200 null` when absent, written by another reducer version, or ahead of the build log's tail; an unknown build is `404`, which the shipped client also maps to `null` |
+| `putReducerSnapshot` | `PUT /builds/{slug}/snapshots/{reducer}` | `{"version": int >= 1, "cursor": int >= 0, "state": JSON}`, at most 16 MiB (`413` above) | `200 {"written": boolean}`; the stored cursor never decreases, so a write at an equal or lower cursor (or an equal cursor at an equal or lower version) and one past the log's tail answer `written: false` |
 | `putArtifact` | `POST /builds/{slug}/artifacts` | artifact input | `201` + build artifact metadata |
 | `getArtifact` | `GET /builds/{slug}/artifacts?kind={kind}&rev={n}` | `kind` is required and nonempty; optional `rev` is parsed below | `200` + artifact read; an absent `rev` parameter selects the latest revision; a missing kind/revision is `200 null` |
 | `listArtifacts` | `GET /builds/{slug}/artifact-list?kind={kind}` | optional `kind`; absence means all kinds | `200` + metadata ordered by kind and then increasing revision |
@@ -336,6 +338,32 @@ part of this protocol. Retention is enforced server-side inside the store at
 deposit time (bounded pruning of dispatcher run/config artifact revisions),
 not through any endpoint.
 
+### Reducer snapshots
+
+A reducer snapshot is one registered reducer's serialized state as of a log
+cursor, kept per scope (one build log or one repository journal) and reducer
+name. It is a cache the log regenerates, never an authority: a process with no
+hot memory loads it, reads only the events newer than its cursor, advances the
+reducer, and writes the advanced state back, and deleting every snapshot changes
+no observable output. The routes above and in section 4 are additive and carry
+no protocol-version bump. The store, not the client, enforces the invariants:
+
+- the stored cursor never decreases, whatever the versions of the competing
+  writers; a write succeeds only when no row exists, when its cursor is above the
+  stored one, or when its cursor equals the stored one and its version is higher
+  (an upgraded reducer replacing the old shape at an unchanged tail);
+- a read answers `null` for a row whose version differs from the requested one,
+  and for one whose cursor is beyond the scope's log tail; a write beyond the
+  tail is refused;
+- an unknown build or repository answers `null` (read) or `written: false`
+  (write) and never creates the scope.
+
+A client treats `404` and `405` from either route as "no snapshot", so a client
+newer than its store replays the log with no error, and a client older than its
+store never calls the routes. Authentication and transport failures still
+surface normally. A build token may touch only its own build's snapshots and a
+repository token only its own repository's, exactly as for events.
+
 ### The event-read bounded wait
 
 Both event reads (`getEvents` and, symmetrically, the `getRepoEvents` read of
@@ -357,7 +385,8 @@ requires. A held request's authentication, token scope, and version-skew rules
 are identical to the immediate form: a `401`, `403`, or `409` identity failure
 is answered immediately, never held.
 
-The parameter is purely additive, so the protocol version stays `2`: a server
+The parameter is purely additive in the version it landed in (protocol `2`,
+where the event-wait rules were introduced): a server
 that ignores `wait` remains conforming — its immediate empty answers only raise
 the client's request rate — and a client that sends `wait` to such a server
 observes no other difference. This is the same reasoning the stream and session
@@ -368,7 +397,11 @@ waits apply. There is no push transport; a held request is the whole mechanism.
 Repository journals are separate resources with independent event sequences,
 artifacts, and leases. `{repo}` is one percent-encoded repository id; encode
 embedded `/` characters. All resource routes authorize and require the
-repository to exist. An unknown repository returns `404 not-found`.
+repository to exist. An unknown repository returns `404 not-found` — with one
+carve-out: the build-digest batch read of this section is keyed to build
+records, not the repository journal record, so it authorizes the repo token
+but answers `200` (possibly empty) even for an unknown repository, a repository
+without a journal record, or a repository without builds.
 
 | BuildStore operation | HTTP route | Request | Success |
 |---|---|---|---|
@@ -376,10 +409,14 @@ repository to exist. An unknown repository returns `404 not-found`.
 | `getRepo` | `GET /repos/{repo}` | none | `200` + `RepositoryRecord`; absent is `404` (the shipped client maps this to `null`) |
 | `appendRepo` | `POST /repos/{repo}/events` | event write | `201` + repository event envelope |
 | `getRepoEvents` | `GET /repos/{repo}/events?since={n}&wait={s}` | optional `since` query value, parsed as in section 3; absence defaults to `0`. Optional `wait` in whole seconds, per the event-wait rules of section 3 | `200` + envelopes with `seq >` parsed `since`, in increasing sequence order |
+| `getRepoStateEvents` | `GET /repos/{repo}/state-events` | none | `200` + the bounded repository-journal subset (AUT-489): every durable event type (`harvest.*`, `orchestrator.sandbox.*`, the three dispatcher setting types) plus, when the journal has one, the tail from the latest `dispatcher.run-started`, in increasing sequence order; served inside the repository-existence gate like `GET events`, so an unknown repository is `404` |
+| `getReducerSnapshot` (repo scope) | `GET /repos/{repo}/snapshots/{reducer}?version={n}` | required `version` query value, a positive integer; `reducer` is a registry name (`^[A-Za-z][A-Za-z0-9._-]{0,63}$`) | `200` + `{"version", "cursor", "state"}` or `200 null` when absent, written by another reducer version, ahead of the journal's tail, or the repository has no journal record; an unknown repository is `404`, which the shipped client also maps to `null` |
+| `putReducerSnapshot` (repo scope) | `PUT /repos/{repo}/snapshots/{reducer}` | `{"version": int >= 1, "cursor": int >= 0, "state": JSON}`, at most 16 MiB (`413` above) | `200 {"written": boolean}`; the stored cursor never decreases, so a write at an equal or lower cursor (or an equal cursor at an equal or lower version) and one past the journal's tail answer `written: false` |
 | `appendRepoWithArtifacts` | `POST /repos/{repo}/deposits` | atomic deposit request | `201` + `{event, artifacts}` using repository shapes |
 | `putRepoArtifact` | `POST /repos/{repo}/artifacts` | artifact input | `201` + repository artifact metadata |
 | `getRepoArtifact` | `GET /repos/{repo}/artifacts?kind={kind}&rev={n}` | required nonempty `kind`; optional `rev` is parsed as in section 3 | `200` + artifact read; latest only when the `rev` parameter is absent; missing kind/revision is `200 null` |
 | `listRepoArtifacts` | `GET /repos/{repo}/artifact-list?kind={kind}` | optional `kind`; absence means all kinds | `200` + metadata ordered by kind and then increasing revision |
+| `getRepoBuildDigests` | `GET /repos/{repo}/build-digests` | none | `200` + `BuildDigest[]`, one entry per build record of the repository (possibly empty), ordered by slug; handled before the repository-existence gate, so an unknown or journal-less repository answers `200 []` |
 | `claimRepoLease` | `POST /repos/{repo}/lease/claim` | claim request | `200 {"ok": boolean}` |
 | `heartbeatRepo` | `POST /repos/{repo}/lease/heartbeat` | holder request | `200 {"ok": boolean}` |
 | `releaseRepoLease` | `POST /repos/{repo}/lease/release` | holder request | `200 {"ok": true}`; a wrong holder is a successful no-op |
@@ -389,10 +426,153 @@ creation operation and must not reset timestamps, events, artifacts, or lease
 state when the repository already exists. Event sequence numbering starts at 1
 for each repository independently of every build and other repository.
 
+A `BuildDigest` is the projection of one build's log onto its terminal fact
+and its `observation.recorded` occurrences:
+
+```jsonc
+// BuildDigest
+{
+  "slug": "ab-fix-login-3",
+  "terminal": "done",               // optional: "done" | "aborted", omitted while the log has neither
+  "observations": [                 // ascending-seq pairs for the log's observation.recorded events
+    { "seq": 1, "ts": "2026-07-15T12:00:01.000Z" },
+    { "seq": 4, "ts": "2026-07-15T12:00:04.000Z" }
+  ],
+  "merged": "2026-07-15T12:00:06.000Z" // optional: ts of the log's latest pr.merged, omitted when none
+}
+```
+
+The digest is derived from the event log on every call — the server persists
+nothing and there is no refresh step. Protocol version `3` reshaped the
+digest's `observations` from bare sequence numbers to `{seq, ts}` pairs and
+added the optional `merged` fact, so the harvest pressure gate can evaluate
+launch decisions from digests and the repository journal alone instead of
+reading every build's full history per evaluation. That is a breaking wire
+change, not an additive one: a server that predates it returns the old shape
+and would fail the client's schema parse mid-request, which is why the version
+moved — a stale peer is now rejected at the handshake (`409 conflict`) instead.
+This is the same discipline the transport's exact-match version rules promise:
+wire shapes that independently implemented servers must reproduce update this
+document and the protocol version together.
+
 The build-stream query, artifact, ordering, timestamp, and validation rules
 apply symmetrically to repository journals, including the event-read bounded
 wait of section 3.
 
+### Ticket assets
+
+A ticket asset is a named, versioned bundle of files attached to
+a ticket, keyed by `(repo, ticketId, kind, name)`. These routes live under the
+repository but, unlike the journal routes, **do not require a repository
+record**: assets can precede any journal row, so the repository-existence gate
+does not apply. `{repo}` and `{id}` are percent-encoded path segments. Token
+authorization follows the one-matching-repo column of the matrix (a repo token
+for its own repository, or admin); build and session tokens receive `403 auth`.
+The family is additive, so `REMOTE_STORE_PROTOCOL_VERSION` did not change.
+
+A build also reads the assets it froze at its claim through its own build-scoped
+routes, which a build token may use (no ticket-asset authority needed). The
+server reduces the build's events to find the pinned revision, then returns that
+exact revision, so a later replace or removal never changes the answer and a
+finished build still answers:
+
+| BuildStore operation | HTTP route | Request | Success |
+|---|---|---|---|
+| `getPinnedTicketAsset` (manifest) | `GET /builds/{slug}/ticket-assets?kind=&name=[&rev=]` | required `kind` and `name`; optional `rev` | `200` + `TicketAssetMeta` for the latest pinned revision (or the named pinned `rev`), or `200 null` when the build never pinned it |
+| `getPinnedTicketAsset` (one file) | `GET /builds/{slug}/ticket-assets/file?kind=&name=&rev=&path=` | required `kind`, `name`, `path`; optional `rev` | `200` + `{"contentBase64": string}`, or `200 null` when not pinned; `404` when the revision has no such file |
+
+| BuildStore operation | HTTP route | Request | Success |
+|---|---|---|---|
+| `ticketAssetLimits` | `GET /repos/{repo}/ticket-asset-limits` | none | `200` + `{maxBytes, maxEntries, maxRequestBytes?}` — the effective per-revision ceilings and, when the deployment has one, the largest request or response body it can carry. A server without this route answers `404`; clients treat that as the defaults |
+| `putTicketAsset` | `POST /repos/{repo}/tickets/{id}/assets` | `{kind, name, layout, entries}` | `201` + `TicketAssetMeta` (with its manifest) |
+| `getTicketAsset` (manifest) | `GET /repos/{repo}/tickets/{id}/assets?kind=&name=[&rev=]` | required `kind` and `name`; optional `rev` | `200` + `TicketAssetMeta` — **the manifest only, no bytes** — or `200 null` when the asset is absent or removed (latest) or the revision does not exist |
+| `getTicketAsset` (one file) | `GET /repos/{repo}/tickets/{id}/assets/file?kind=&name=&rev=&path=` | required `kind`, `name`, `path`; optional `rev` | `200` + `{"contentBase64": string}`, or `200 null` when the asset is absent; `404` when the revision has no such file |
+| `listTicketAssets` | `GET /repos/{repo}/tickets/{id}/assets/list[?revisions=1]` | optional `revisions=1` | `200` + `TicketAssetSummary[]` ordered by kind, name, revision: the latest live revision per kind and name, or with `revisions=1` every real revision (no tombstones). Summaries carry no manifest |
+| `removeTicketAsset` | `POST /repos/{repo}/tickets/{id}/assets/remove` | `{kind, name}` | `200` + the removed `TicketAssetMeta`, or `200 null` when no live asset exists |
+
+Wire types:
+
+```jsonc
+// put request: entries are files (content as base64) or explicit directories
+{ "kind": "design", "name": "home", "layout": "tree",   // layout: "file" | "tree"
+  "entries": [
+    { "type": "file", "path": "index.html", "contentBase64": "PGgxPg==" },
+    { "type": "dir",  "path": "img/empty" }
+  ] }
+
+// TicketAssetMeta: dir entries carry no size or blobRef
+{ "repo": "…", "ticketId": "AUT-1", "kind": "design", "name": "home",
+  "revision": 0, "layout": "tree", "size": 1234,         // size = total file bytes
+  "entries": [
+    { "type": "file", "path": "index.html", "size": 1234, "blobRef": "<sha256 hex>" },
+    { "type": "dir",  "path": "img/empty" }
+  ],
+  "createdAt": "2026-10-01T12:00:00.000Z" }
+
+// TicketAssetSummary (list): the same without entries
+{ "repo": "…", "ticketId": "AUT-1", "kind": "design", "name": "home",
+  "revision": 0, "layout": "tree", "size": 1234,
+  "fileCount": 1, "dirCount": 1, "createdAt": "…" }
+```
+
+Semantics every server must reproduce:
+
+- **Revisions** are 0-based per `(repo, ticketId, kind, name)`. Putting the same
+  kind and name again creates the next revision; earlier revisions stay readable
+  by explicit `rev`.
+- **Removal is a tombstone** that takes the next revision number with an empty
+  manifest. The latest row decides liveness: a read without `rev` and the
+  default list skip a removed asset, while an explicit earlier `rev` keeps
+  working (a build that pinned that revision still retrieves it). Re-attaching
+  takes the next revision, so numbers may skip the tombstone. `revisions=1`
+  lists real revisions only.
+- **Validation** (`422 validation`, nothing stored). `kind` and `name` match
+  `[A-Za-z0-9._-]+`, at most 64 characters. Paths are relative and
+  `/`-separated, with no empty, `.`, or `..` segment and no NUL, at most 256
+  UTF-8 bytes (128 per segment); paths are unique across files and directories
+  and no file is the ancestor of another entry. `layout: "file"` has exactly one
+  top-level `file` entry and no directory; `layout: "tree"` may hold any number
+  of entries, including zero (an empty folder; its root is implicit). A revision
+  holds at most 1000 entries (files plus directories) and **26214400 bytes (25
+  MiB)** of file bytes; the error names the limit, for example `ticket asset
+  exceeds the 26214400-byte (25 MiB) limit`.
+- File bytes are content-addressed (`blobRef` is the sha256 hex) in the same
+  blob store as artifacts; the database holds only the manifest.
+
+**Deployment ceilings.** A platform may reject oversized request or response
+bodies before any application code runs (Vercel's functions cap them at 4.5
+MB), so validating on the server alone cannot enforce a limit. A server that
+has such a ceiling advertises it as `maxRequestBytes` on the limits route
+together with the effective `maxBytes`, computed from it as follows. Paths and
+entry counts are bounded, so the worst-case wire overhead is a constant:
+`overhead = 1024 + 1000 × 320 = 321024` bytes, and
+`maxBytes = min(26214400, max(0, floor((maxRequestBytes − overhead) × 3 / 4)))`
+(base64 inflates content by 4/3); `maxEntries` stays 1000. The hosted service
+sets `maxRequestBytes` to 4 MiB, giving an effective per-asset limit of 2904960
+bytes (about 2.8 MiB). The formula is a safe lower bound, not the final
+authority:
+
+- The shipped **client** reads the limits once per store handle and, before any
+  upload, validates against `maxBytes` and `maxEntries` and then compares the
+  exact UTF-8 length of the serialized request with `maxRequestBytes`. A bundle
+  that does not fit is refused locally with `ticket asset exceeds this store's
+  N-byte limit (deployment request ceiling M bytes)` and **no upload request is
+  made**.
+- The **server** re-validates every put against its effective limits and checks
+  every ticket-asset body against `maxRequestBytes` itself, answering `413` (a
+  request) or `422` with a limit-naming message where the platform lets the
+  request through.
+- **Downloads never need a bundle-sized response**: the client reads the
+  manifest and then each file by its own request. The manifest, file, and list
+  routes check the exact serialized length of their response against
+  `maxRequestBytes` and fail with a `413 validation` error naming the asset (or
+  the file, its size, and the ceiling) rather than letting the platform reject
+  it. This matters for a revision stored under an older or higher ceiling:
+  its manifest and smaller files remain retrievable; a file that cannot fit can
+  only be fetched from a store with a higher ceiling. Chunked or ranged transfer
+  is not part of the protocol, so a deployment's effective per-asset limit is
+  its advertised `maxBytes`.
+
 ## 5. Operator-session operations
 
 Operator sessions are a third resource kind: durable orchestrator-conversation
@@ -430,6 +610,7 @@ identity is already the actor.
 | `listSessions` | `GET /repos/{repo}/sessions` | none | `200` + `SessionRecord[]`, creation order (`createdAt`, then the store's creation counter for same-millisecond ties) |
 | `getSession` | `GET /sessions/{id}` | none | `200` + `SessionRecord`; absent is `404` (the shipped client maps this to `null`) |
 | `appendSessionEvent` | `POST /sessions/{id}/events` | event write | `201` + session event envelope (same envelope shape with `"session"` in place of `"build"`) |
+| `appendSessionEventIfCurrent` | `POST /sessions/{id}/events/conditional` | `{"expectedSeq": nonnegative integer, "event": event write}` | appended: `201` + session event envelope; session advanced: `200 null` (mirroring section 3's build compare-and-append) |
 | `getSessionEvents` | `GET /sessions/{id}/events?since={n}&wait={s}` | optional `since` query value, parsed as in section 3; absence defaults to `0`. Optional `wait` in whole seconds, per the event-wait rules of section 3 | `200` + session event envelopes with `seq >` parsed `since`, in increasing sequence order |
 | `appendSessionWithArtifacts` | `POST /sessions/{id}/deposits` | atomic deposit request | `201` + `{event, artifacts}` using session shapes; the substitution algorithm of section 8 applies unchanged |
 | `putSessionArtifact` | `POST /sessions/{id}/artifacts` | artifact input | `201` + session artifact metadata |
@@ -599,7 +780,8 @@ by this rule (their retention belongs to the open archival thread), and open
 streams are never pruned. A read of a stream whose chunks were pruned returns
 no chunks, `status: "closed"`, and the artifact reference.
 
-These additions are purely additive: the protocol version stays `2`, and a
+These additions were purely additive in the version they landed in (protocol
+`2`, where the stream routes were introduced), and a
 conforming server implements the stream routes together with this document's
 rules exactly as it does for the event and artifact routes.
 
@@ -675,12 +857,17 @@ resource access; an explicit resource whose id is `"*"` is not admin.
 
 ### Resource authorization matrix
 
-| Token resource | `/builds` create/list | one matching build | `/repos` ensure | one matching repo | `/repos/{repo}/sessions` create/list | one matching session |
-|---|---:|---:|---:|---:|---:|---:|
-| admin (`build: "*"`) | yes | any | yes | any | yes | any |
-| build | no | exact id only | no | no | no | no |
-| repo | no | no | no | exact id only | yes | no |
-| session | no | no | no | no | no | exact id only |
+| Token resource | `/builds` create/list | one matching build | `/repos` ensure | one matching repo | `/repos/{repo}/sessions` create/list | `/repos/{repo}/build-digests` | `/repos/{repo}/state-events` | `/repos/{repo}/tickets/{id}/assets` and `/repos/{repo}/ticket-asset-limits` | one matching session |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| admin (`build: "*"`) | yes | any | yes | any | yes | any | any | any | any |
+| build | no | exact id only | no | no | no | no | no | no | no |
+| repo | no | no | no | exact id only | yes | exact id only | exact id only | exact repo only | no |
+| session | no | no | no | no | no | no | no | no | exact id only |
+
+The snapshot routes (`/builds/{slug}/snapshots/{reducer}` and
+`/repos/{repo}/snapshots/{reducer}`) follow the one-matching-build and
+one-matching-repo columns: a build token reads and writes only its own build's
+snapshots, a repo token only its own repository's.
 
 A valid token used for the wrong resource receives `403 auth`. Resource scope
 gates all operations, including reads, artifact operations, and leases. A
@@ -793,8 +980,8 @@ The shipped server maps failures as follows:
 | `403` | `auth` | Valid token with the wrong resource scope or event-session attribution |
 | `404` | `not-found` | Unknown route, unsupported method, unknown build, unknown repository, unknown session, or an unknown or foreign-scoped stream |
 | `409` | `conflict` | Missing/mismatched package or protocol identity, duplicate build creation, appending to a closed stream (`stream "…" is closed`), or a backing conflict reported as already existing |
-| `413` | `validation` | Decoded artifact or serialized stream batch exceeds the configured ceiling; the message names the ceiling |
-| `422` | `validation` | `EventValidationError` from build, repository, or session catalog validation; its message is preserved verbatim |
+| `413` | `validation` | Decoded artifact or serialized stream batch exceeds the configured ceiling; a ticket-asset request or response exceeds the deployment's request ceiling; the message names the ceiling |
+| `422` | `validation` | `EventValidationError` from build, repository, or session catalog validation, or a ticket-asset validation failure (including the 25 MiB limit); its message is preserved verbatim |
 | `500` | `internal` | Any other unexpected backing or server failure; the thrown error message is returned |
 
 Authentication runs before resource lookup, and session authorization runs
@@ -916,11 +1103,12 @@ Four shipped behaviors do not add `BuildStore` routes:
   store lifecycle; there is no close endpoint.
 - `GET /health` is outside the `BuildStore` interface. It is always open and
   returns exactly `200 {"ok":true,"autobuildVersion":"<package>",
-  "protocolVersion":"2"}`. It reports HTTP-process availability and identity,
+  "protocolVersion":"3"}`. It reports HTTP-process availability and identity,
   not a deeper backing-store transaction or migration check.
 
-There is no push/WebSocket subscription protocol, batch-read route,
-repository listing, artifact deletion, or server deployment API.
+There is no push/WebSocket subscription protocol, repository listing, artifact
+deletion, or server deployment API. The one repo-scoped batch read is the
+build-digest route of section 4; no other batch-read route exists.
 
 ## 12. Conformance
 

package/docs/remote-ticket-protocol.md

@@ -3,7 +3,7 @@
 The hosted ticket protocol exposes the complete `TicketSource` port without
 exposing backend credentials. It shares the Autobuild and remote protocol
 version headers with the remote BuildStore. Both must exactly match the service;
-this release uses remote protocol version `2`.
+this release uses remote protocol version `3`.
 
 ## Authentication and context
 

package/docs/setup.md

@@ -59,7 +59,7 @@ DEBIAN_FRONTEND=noninteractive apt-get install -y chromium""" },
 
 [workspace.config.runtimeProvisioning.pi]
 install = "npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.84.4"
-preflight = "test \"$(pi --version)\" = \"0.84.4\""
+preflight = "test \"$(pi --version)\" = \"0.84.4\" && pi update --models"
 ```
 
 Use a `vercel-ai-gateway/...` Pi model with `AI_GATEWAY_API_KEY` in the
@@ -220,14 +220,17 @@ same lockstep window. If the release is cut but the store upgrade lags, guests
 carrying the new distribution fail loudly against the old store (409) rather
 than running silently stale.
 
-Provisioning records the installed distribution's version in the guest's
-`/opt/autobuild/.distribution-version` marker. A reused persistent sandbox
-whose marker disagrees with the version the current system would deliver —
-which includes every guest provisioned before the marker existed — is
-refreshed in place (archive re-fetched, extracted, and production-installed)
-before being reused, so an upgraded dispatcher retrofits its existing guests
-instead of resuming a stale distribution. A refresh failure deletes the
-sandbox so the next provisioning pass rematerializes it from scratch.
+Provisioning records the installed distribution's identity — package version
+and remote-store protocol version — in the guest's
+`/opt/autobuild/.distribution-version` marker. Every path that launches guest
+code in an existing sandbox — provisioning reuse, harvest reuse, the operator
+sandbox, and build execution restart after a lease sweep — compares the marker
+against the identity the current system would deliver and, when they disagree
+(which includes every guest provisioned before the marker existed), refreshes
+it in place (archive re-fetched, extracted, and production-installed) first,
+so an upgraded dispatcher retrofits its existing guests instead of resuming a
+stale distribution the hosted store would reject. A refresh failure deletes
+the sandbox so the next provisioning pass rematerializes it from scratch.
 
 After a lockstep upgrade, confirm a fix-bearing guest from the guest
 perspective:

package/docs/website.md

@@ -0,0 +1,14 @@
+# Website
+
+The marketing site is one static page in `packages/website`, reproduced from the approved design in `design/website/`. The package is private and never published to npm.
+
+- `bun run website:dev` serves it on port 3300 (`PORT` overrides), rebuilding on every request.
+- `bun run website:build` writes `packages/website/dist/` (`index.html`, `site.css`, `site.js`).
+
+The hero is the real `ab dispatch` dashboard: `packages/website/src/hero-frame.txt` holds the exact colored lines the terminal dashboard painted for the scripted `website-hero` capture, and the page renders them as preformatted HTML with each terminal color mapped to its design token. `bun run capture:website-hero` regenerates the file from the capture, and `bun run check` fails when it is stale.
+
+Shared links preview through Open Graph and Twitter card tags in the page head, pointing at `og.png`, a 1200×630 card drawn from the same frame in the site's own styles. `bun run capture:website-og` screenshots it with a local Chromium into `packages/website/src/og.png`; rerun it after changing the headline, the hero frame, or the styles, and look at the result, since font rasterization differs between machines and nothing checks the bytes. The canonical origin every absolute URL is built from is `SITE_URL` in `packages/website/src/constants.ts`.
+
+`dist/` is plain static files: any static host can serve it with no server runtime, credentials, or environment variables. On Vercel, set the root directory to `packages/website`, the build command to `bun run build`, and the output directory to `dist`.
+
+The page loads one webfont from Google Fonts and makes no other third-party requests.