@defrex/autobuild 0.11.0 → 0.12.0

package/skills/guide/references/remote-store-protocol.md

@@ -9,21 +9,38 @@ and the implementation passes the shared `BuildStore` contract exported by
 
 The transport, wire shapes, validation order, atomicity, lease behavior,
 persistence requirements, and conformance bar for the protocol shipped in this
-distribution are all defined here. A protocol implementation must target the
-same Autobuild package version used by its clients; protocol changes update this
-document and the package's executable contracts together.
+distribution are all defined here. Protocol implementations must retain contracts for every supported client line;
+protocol changes update this document and executable contracts together.
+
+A service accepts stable clients from its own `major.minor` release line and
+the two preceding minor lines in the same major. A major starts a new family:
+X.0 accepts only X.0, X.1 accepts X.0/X.1, and X.2 onward accepts three lines.
+Patch versions are interchangeable in both directions and must never change
+the protocol. Upgrade the service first, then projects independently within
+its window. Supported release lines retain their wire handlers and known
+protocol identities; an unknown protocol is refused independently of version.
+Malformed, missing, and prerelease identities are refused with HTTP 409.
+A newer client is told to upgrade the service; a client below the window is
+told to upgrade the project's Autobuild. Diagnostics name the service version
+and supported range.
+
+Unauthenticated `GET /health` publishes `ok`, `autobuildVersion`,
+`protocolVersion`, and `supportedClientRange: { minVersion, maxVersionExclusive }`.
+The range is inclusive at the minimum and exclusive at the maximum; a 0.11.x
+service publishes `>=0.9.0 <0.12.0`. Health needs no credentials, version
+headers, or available backend.
 
 ## 1. Transport and conventions
 
 - The transport is JSON over HTTP or HTTPS. There is no API version prefix.
-  Point Autobuild at the server's base URL with `--store`, or set that URL in
-  `AB_STORE`; the shipped client appends the routes below.
+  Point Autobuild at the server's base URL with `--store`, `AB_STORE`, or
+  `[store] url` (in that precedence order, before the local default); 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 (`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":"…"}`;
+  body parsing, or resource lookup, the server validates the release-line window and known protocol identity.
+  Unsupported or missing values receive `409 {"kind":"conflict","error":"…"}`;
   the diagnostic names the client and server package and protocol versions.
 - Clients send `Content-Type: application/json` for requests with bodies. Every
   response, including errors and `null` artifact results, has
@@ -184,7 +201,7 @@ and section 7).
 
 Those event catalogs evolve with Autobuild's build lifecycle rather than with
 the storage transport. A server therefore must use or faithfully implement the
-catalog from the same Autobuild package version as its client. The public
+catalog behavior required by every supported client release line. The public
 `BuildStore` type (including its typed write methods), representative valid
 writes, and unchanged contract suite exported by `@defrex/autobuild/plugin-sdk` are the
 package-versioned compatibility surface. Wire validation remains mandatory even
@@ -290,8 +307,8 @@ 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, 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 |
+| `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` + authoritative `BuildRecord`; project credentials receive a fresh random-suffixed slug and matching branch. Owner admin/open mode keeps exact-slug semantics with `409 conflict` for duplicates |
+| `listBuilds` | `GET /builds` | none | `200` + `BuildRecord[]`, filtered by the server to the credential project; owner admin may list all projects. 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` |
@@ -361,8 +378,7 @@ no protocol-version bump. The store, not the client, enforces the invariants:
 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.
+surface normally. Snapshot authorization follows the owning project, exactly as for events.
 
 ### The event-read bounded wait
 
@@ -399,7 +415,7 @@ 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` — 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
+records, not the repository journal record, so it authorizes the project credential
 but answers `200` (possibly empty) even for an unknown repository, a repository
 without a journal record, or a repository without builds.
 
@@ -451,7 +467,7 @@ 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:
+This is the same discipline the transport's supported-window rules promise:
 wire shapes that independently implemented servers must reproduce update this
 document and the protocol version together.
 
@@ -466,12 +482,11 @@ 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`.
+authorization requires a credential for that registered project, or owner admin.
 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
+routes, authorized against the build's actual project. 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:
@@ -785,140 +800,148 @@ These additions were purely additive in the version they landed in (protocol
 conforming server implements the stream routes together with this document's
 rules exactly as it does for the event and artifact routes.
 
-## 7. Authentication and token scope
+## 7. Authentication and project authority
 
-### Open and authenticated modes
+Project credentials are opaque `abp_1_<id>_<secret>` bearer values bound to one
+registered normalized repository. The service stores only a SHA-256 digest of
+the random secret, plus project, creator, creation time, last use, expiry and
+revocation metadata. It checks credential status and project registration on
+every request. Revocation takes effect on the next request without affecting
+other credentials. Unknown, expired or revoked credentials receive `401 auth`;
+removed projects receive `403 auth` with `project not registered`.
 
-A server configured without a signing secret is in open mode: no route checks
-a token or event session attribution. This is intended for local development
-and the open contract harness.
+The deployment owner runs these commands locally with database access:
 
-A server configured with a secret requires this header on every `/builds`,
-`/repos`, and `/sessions` route:
-
-```http
-Authorization: Bearer <token>
+```sh
+ab-hosted-store credentials issue https://github.com/acme/app --user owner@example.com
+ab-hosted-store credentials list https://github.com/acme/app
+ab-hosted-store credentials revoke https://github.com/acme/app --id ID --user owner@example.com
 ```
 
-`GET /health` is always unauthenticated. Package/protocol identity validation
-occurs first on machine routes. Authorization then occurs before request body
-processing on collection routes and before resource lookup on resource routes.
-A caller with the wrong scope therefore cannot use existence or validation
-differences to inspect another resource.
-
-### Token encoding
+Issue prints the secret once; list contains metadata only. Issue optionally
+accepts `--ttl-seconds N` or `--expires-at ISO-8601`. For administrative/non-interactive issuance, set the returned token as
+`AB_TOKEN`. Interactive project onboarding uses `ab connect <service-url>`;
+it saves the credential outside the repository and commits no secret. Previous `AB_TOKEN` values and `mint operator` / `mint build` are
+retired: the service responds that the credential format changed and points
+to `credentials issue`. Supported old protocol shapes still work with a new
+credential; protocol compatibility does not restore retired authentication.
 
-A token has two dot-separated base64url segments:
-
-```text
-base64url(UTF-8 JSON scope) + "." + base64url(HMAC-SHA256(secret, payloadSegment))
-```
+`mint admin --ttl-seconds N` creates an explicit versioned, attributed owner
+break-glass credential. It can cross project boundaries. Keep it owner-only:
+never give it or `AB_STORE_SECRET` to a dispatcher or build agent.
 
-The HMAC input is the first token segment exactly as encoded, not the decoded
-JSON bytes. The signature is compared in constant time. The scope JSON must
-match exactly one of these shapes; unknown keys are invalid:
+Service-owned signatures use `base64url(JSON scope) + "." +
+base64url(HMAC-SHA256(AB_STORE_SECRET, payloadSegment))`. Signatures are checked
+in constant time. Current strict scope shapes are:
 
 ```jsonc
-// Legacy build scope, retained for wire compatibility
-{ "build": "build-slug", "session": "s_123", "exp": 1784116800000 }
-
-// Explicit resource scope
-{
-  "resource": { "kind": "build", "id": "build-slug" },
-  "session": "s_123",
-  "exp": 1784116800000
-}
-
-{
-  "resource": { "kind": "repo", "id": "acme/autobuild" },
-  "session": "hs_123",
-  "exp": 1784116800000
-}
-
-{
-  "resource": { "kind": "session", "id": "os_123" },
-  "session": "*",
-  "exp": 1784116800000
-}
+{ "version": 1, "ownerAdmin": { "user": "owner identity" }, "exp": 1800000000000 }
+{ "version": 1, "internalOperator": { "user": "owner identity", "repo": "https://github.com/acme/app" }, "exp": 1800000000000 }
 ```
 
-`build`, resource `id`, and `session` are nonempty strings. A resource or
-operator scope may carry an optional `via` claim (the same shape as the
-actor's `via` marker). `exp` is an integer
-Unix epoch in **milliseconds**. A token is expired when `exp <=` the server's
-current epoch milliseconds. A malformed token, malformed scope, bad signature,
-or expired token is invalid and receives `401 auth` without a more specific
-verification diagnostic.
-
-The legacy scope `{"build":"*", ...}` is the admin resource scope. The
-normal runner/admin form also uses `"session":"*"`, allowing event writes on
-behalf of any valid actor. Only the legacy `build: "*"` spelling grants admin
-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 | `/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
-session resource token's authority is exactly its one session — it cannot
-create or list sessions, and it cannot touch another session's events,
-artifacts, or streams. A repo token owns its repository's session collection
-routes but not any session resource. Session resource and repo/build tokens
-never cross.
-
-The token's session dimension adds a second gate only to event-bearing writes:
-`POST .../events`, `POST .../events/conditional`, and `POST .../deposits`.
-
-- `session: "*"` may submit any actor that the event catalog itself allows.
-- Any other session may submit only an actor with `kind: "agent"` and a
-  `session` exactly equal to the token session.
-- Another agent session or a kernel, human, dispatcher, or ingester actor
-  receives `403 auth` before catalog validation.
-- Reads, standalone artifact puts, and lease operations do not apply session
-  attribution beyond the resource-scope check.
-
-### Delegated-write attribution (`via`)
-
-On every event-bearing write (`POST .../events`, `POST .../events/conditional`,
-and `POST .../deposits` on build, repository, and session resources), a server
-in authenticated mode enforces `via` attribution after token verification and
-before catalog validation:
-
-- A human actor claiming a `via` the token does not carry is `403 auth` — the
-  caller must be able to distinguish "not your delegate" from "malformed
-  event", which is why this is authority (403) and not validation (422).
-- A token carrying a `via` claim stamps that `via` onto every human actor in
-  the write: the token is authoritative, and a matching claim or no claim both
-  end with the token's `via` on the stored event.
-- A non-human actor carrying a `via` key is not an authority question; it falls
-  through to catalog validation, which rejects it with the rule message.
-- An unscoped operator token carries no `via` and never authorizes raw store
-  routes at all.
-
-In open mode there is no token to be authoritative and writes pass through
-unchanged. Events without a `via` member are stored, replayed, and read
-byte-identically to before.
-
-Build and repository scopes never cross: a harvest repository token cannot
-read a build stream, and a build token cannot read a repository journal.
-Attributed human-operator scopes have
-`{ "operator": { "user": "nonblank identity" }, "exp": … }`. They are accepted
-only by the [operator API](operator-api.md), never by raw store or ticket routes;
-conversely, deployment/admin/build/repository scopes are refused there.
-Deployment scopes have `{ "operator": true, "session": "*", "exp": … }` and
-cover raw store and [hosted ticket](remote-ticket-protocol.md) routes without
-granting attributed operator controls.
+Internal operator scopes may also carry `via`, using the actor's existing
+shape. Unknown fields are invalid. `exp` is epoch milliseconds and expiry is
+inclusive (`exp <= now` is refused). These signatures are separate from opaque
+project credentials and are never project onboarding credentials.
+
+Every machine route requires Bearer authentication after version negotiation;
+`GET /health` stays public. Explicitly unauthenticated local test servers may
+remain open. Internal owner operator signatures cannot use raw store routes.
+
+A project credential may read and write its repository journal, artifacts,
+snapshots, leases, ticket assets, builds, sessions and streams. Explicit repo
+paths and create bodies must match its project (`403 auth: wrong project`).
+Indirect build/session/stream IDs are resolved internally and checked against
+the resource's actual repository. Missing and foreign IDs both return the same
+`404 not-found` error: `resource unavailable: unknown resource or wrong project`.
+Remote clients continue mapping addressed GET 404 responses to null. Nested
+streams must also belong to the addressed parent.
+
+`GET /builds` is filtered by the server to the credential's project. Project
+`POST /builds` always allocates a fresh random-suffixed slug from the requested
+base and a matching `ab/<slug>` branch, even when the base is unused. The
+returned BuildRecord slug and branch are authoritative for all subsequent
+work. A foreign or missing base returns null on GET; it neither reveals
+collisions nor blocks creation. Owner admin retains exact-slug creation and
+all-project listing. Local BuildStore adapters retain exact-slug semantics.
+
+Project credentials retain runner-style actor/session attribution within the
+project; phase CLI scoped handles still constrain build and session access.
+Authenticated raw writes cannot claim a delegated `via`. Owner-project
+credentials also use their recorded creator for operator writes. Dispatcher
+credentials have an immutable server-side purpose: raw store and tickets only,
+never human operator controls. The hosted dispatcher issues one per project
+invocation, expiring at its configured TTL, and does not revoke at tick return
+for dispatcher plumbing. Spawned builds receive independent delegated grants. Shared content-addressed blobs
+remain deduplicated; this is resource authorization, not blob partitioning.
+
+
+### Delegated build and harvest credentials
+
+`POST /credentials/delegate` uses the standard identity headers and Bearer
+machine authentication. Its strict target is one of:
+
+- `{kind: "build-runner", id}` for an existing build;
+- `{kind: "build-phase", id, session}` after its `session.started` fact;
+- `{kind: "harvest-runner", repo, id, execution, leaseHolder}` after trusted
+  preparation has atomically claimed the scan and recorded
+  `harvest.execution.authorized` for that run/execution and adopted holder;
+- `{kind: "harvest-phase", repo, id, session}` from its runner, after the
+  matching `harvest.session.started` fact.
+
+The response is `{token}` only. Project credentials can issue only within their
+registered project. A runner grant may issue only an exact phase grant within
+its own lifecycle binding; phase grants cannot delegate. Unknown targets are
+refused. Tokens and parent secrets never become artifacts, launch envelopes or
+execution facts. Local-store execution requires no exchange; remote execution
+fails closed when issuance fails.
+
+The signed strict shape is `{version: 2, delegation: {repo, kind, id, anchor,
+session?, execution?, leaseHolder?}}`. `anchor` is the authoritative event
+sequence; harvest grants additionally bind the authorized execution. Session
+claims exist only on phase grants. No fixed `exp` applies to this shape:
+signature/schema verification precedes registered-project and lifecycle checks
+on every request, with no authorization cache. Failure to read lifecycle state
+fails closed. Parent credential expiry does not expire an already-issued grant.
+Project removal refuses all its grants immediately.
+
+Build grants live until 60 seconds after durable build termination. Phase grants
+also retire 60 seconds after their own session ends, whichever comes first.
+Harvest grants retire 60 seconds after their run stops or their authorized
+execution ends/releases; harvest phases additionally retire on session end.
+The boundary is exclusive: at `end + 60_000ms` the credential is refused. This
+window permits final transcripts, diagnostics, deposits and stream closure.
+Pause/escalation of a build and lease expiry do not end authority. Active grants
+survive hours-long turns, parent expiry and dispatcher/service reconstruction.
+A durable ending never resurrects: recovered harvest work gets a new
+`harvest.execution.authorized` identity and token.
+
+Delegated same-project reads remain available, including journals, artifacts,
+digests, bounded state, pinned assets and collections. Writes by a build grant
+are confined to its build's events/deposits/artifacts, snapshots, leases and
+streams. Phase grants also reject agent actors naming another session, while
+preserving the CLI's trusted kernel terminals. Delegated credentials cannot
+create builds/operator sessions, change ticket assets or repository controls,
+or invoke operator APIs. Harvest writes require the exact run in event payloads
+and artifact metadata; artifacts use the harvest kinds. Every artifact in an
+atomic deposit is checked before writing. Harvest streams have an immutable
+`harvest:<run>:<execution>:` label namespace. Addressed streams resolve their actual owner;
+a guessed ID cannot bypass the boundary. Only the runner can heartbeat or re-acquire its exact
+adopted repository lease holder; another current holder still fences it. Recovery acknowledgements remain dispatcher-side.
+
+Hosted ticket access is gated by grant kind. Build-runner and build-phase grants
+cannot call ticket routes. Harvest-phase grants may call only list-ready, get
+and dependency-states; harvest-runner grants may additionally create proposals.
+Other ticket mutations require project or admin authority. A denied operation
+returns 403 naming the grant kind and operation before parsing or source construction.
+Ticket admission and repository-keyed assets use the authenticated project;
+delegated harvest grants retain that same project boundary.
+
+Workspace plugin factories receive a host-only `delegateCredential` callback
+instead of a project token; their environment excludes `AB_TOKEN`. Provisioning
+and launch must obtain per-resource authority before running guest code and pass
+launch tokens separately from durable execution identity. Remote providers must
+not serialize parent credentials or fall back to forwarding them.
 
 ## 8. Atomic deposits
 
@@ -977,7 +1000,7 @@ The shipped server maps failures as follows:
 |---:|---|---|
 | `400` | `validation` | Invalid JSON, request body schema, malformed percent-encoding, missing/empty required `kind`, a `since`/`rev` value whose JavaScript `Number` conversion is not an integer, or a `wait` value that is not one or more ASCII digits |
 | `401` | `auth` | Missing bearer credentials or an invalid, malformed, badly signed, or expired token |
-| `403` | `auth` | Valid token with the wrong resource scope or event-session attribution |
+| `403` | `auth` | Wrong project, project not registered, or disallowed credential purpose |
 | `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; a ticket-asset request or response exceeds the deployment's request ceiling; the message names the ceiling |
@@ -1103,7 +1126,8 @@ 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":"3"}`. It reports HTTP-process availability and identity,
+  "protocolVersion":"3", "supportedClientRange":{"minVersion":"0.9.0",
+  "maxVersionExclusive":"0.12.0"}}`. It reports HTTP-process availability and identity,
   not a deeper backing-store transaction or migration check.
 
 There is no push/WebSocket subscription protocol, repository listing, artifact
@@ -1151,10 +1175,31 @@ Add protocol-specific tests alongside the shared contract for token encoding
 and resource isolation, session-attributed writes, exact validation feedback,
 atomic placeholder substitution, event paging, unauthenticated health, and
 continuity across server restarts. The session family (section 5), the
-session-scoped token's authority matrix, and the `via` stamp/reject order
-(section 7) are part of the contract suite and of the protocol-specific cases. Exercise all routes through HTTP, not by
+project credential boundary, revocation, and delegated-write attribution are part of the contract suite and of the protocol-specific cases. Exercise all routes through HTTP, not by
 calling the backing store directly.
 
 Passing only route smoke tests is not conformance. The complete shared contract
 driven through an HTTP-backed client, plus the protocol-specific cases above,
 is the required compatibility test.
+
+## 13. Project connection protocol
+
+`ab connect <url>` uses `POST /connect/v1/requests` with the normalized origin,
+a random credential id and SHA-256 digest of a CLI-held secret. The response
+contains a ten-minute request id, separate private polling capability, short
+browser code, verification URL and five-second interval. `POST /connect/v1/poll`
+and `/cancel` require id and capability in JSON; the browser code cannot poll.
+Poll returns pending, approved, denied or expired plus immutable repository
+and credential id, never the secret. Cancel denies pending work or revokes
+only that request's already approved credential. Polling and authenticated
+browser code lookup have durable limits; 429 includes Retry-After.
+
+The web-enabled origin serves `/connect` and cookie-authenticated JSON
+`POST /connect/v1/browser/lookup` and `/decide`. Decisions read the saved
+proposal, require an allowed live Better Auth session and exact Origin, and
+atomically register the project, install the digest and record the outcome.
+GET cannot approve. `GET /connect/v1/status` and `POST /connect/v1/revoke`
+require a project credential and operate only on its own identity; admin and
+internal operator credentials cannot impersonate self-service. All protocol
+responses are no-store/no-referrer. Connection commands are unavailable in
+build/harvest sessions.

package/skills/guide/references/remote-ticket-protocol.md

@@ -2,22 +2,71 @@
 
 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 `3`.
+version headers with the remote BuildStore. The version must be in the
+published service window and the protocol must
+match its known release-line identity (`3` for 0.9, 0.10, and 0.11).
+
+A service accepts stable clients from its own `major.minor` release line and
+the two preceding minor lines in the same major. A major starts a new family:
+X.0 accepts only X.0, X.1 accepts X.0/X.1, and X.2 onward accepts three lines.
+Patch versions are interchangeable in both directions and must never change
+the protocol. Upgrade the service first, then projects independently within
+its window. Supported release lines retain their wire handlers and known
+protocol identities; an unknown protocol is refused independently of version.
+Malformed, missing, and prerelease identities are refused with HTTP 409.
+A newer client is told to upgrade the service; a client below the window is
+told to upgrade the project's Autobuild. Diagnostics name the service version
+and supported range.
+
+Unauthenticated `GET /health` publishes `ok`, `autobuildVersion`,
+`protocolVersion`, and `supportedClientRange: { minVersion, maxVersionExclusive }`.
+The range is inclusive at the minimum and exclusive at the maximum; a 0.11.x
+service publishes `>=0.9.0 <0.12.0`. Health needs no credentials, version
+headers, or available backend.
 
 ## Authentication and context
 
-Every request is `POST /tickets/<operation>`, has `Content-Type:
-application/json`, and requires `Authorization: Bearer <token>`. Only a signed,
-unexpired **deployment operator** token (`{ "operator": true, … }`) is accepted.
-Attributed human-operator, legacy admin, build, repository, and session tokens
-remain valid for their own routes but are denied on `/tickets`. Mint a deployment
-operator token offline with:
+Every request is `POST /tickets/<operation>`, has `Content-Type: application/json`,
+and requires `Authorization: Bearer <project credential>`. Authentication and
+registration checks precede body parsing and source construction. Owner admin
+is the explicit cross-project exception; internal operator signatures have no
+ticket authority.
+
+Project credentials are opaque `abp_1_<id>_<secret>` bearer values bound to one
+registered normalized repository. The service stores only a SHA-256 digest of
+the random secret, plus project, creator, creation time, last use, expiry and
+revocation metadata. It checks credential status and project registration on
+every request. Revocation takes effect on the next request without affecting
+other credentials. Unknown, expired or revoked credentials receive `401 auth`;
+removed projects receive `403 auth` with `project not registered`.
+
+The deployment owner runs these commands locally with database access:
 
 ```sh
-AB_STORE_SECRET='…' ab-hosted-store mint operator --ttl-seconds 3600
+ab-hosted-store credentials issue https://github.com/acme/app --user owner@example.com
+ab-hosted-store credentials list https://github.com/acme/app
+ab-hosted-store credentials revoke https://github.com/acme/app --id ID --user owner@example.com
 ```
 
+Issue prints the secret once; list contains metadata only. Issue optionally
+accepts `--ttl-seconds N` or `--expires-at ISO-8601`. For administrative/non-interactive issuance, set the returned token as
+`AB_TOKEN`. Interactive project onboarding uses `ab connect <service-url>`;
+it saves the credential outside the repository and commits no secret. Previous `AB_TOKEN` values and `mint operator` / `mint build` are
+retired: the service responds that the credential format changed and points
+to `credentials issue`. Supported old protocol shapes still work with a new
+credential; protocol compatibility does not restore retired authentication.
+
+`mint admin --ttl-seconds N` creates an explicit versioned, attributed owner
+break-glass credential. It can cross project boundaries. Keep it owner-only:
+never give it or `AB_STORE_SECRET` to a dispatcher or build agent.
+
+Hosted tickets, comments, blockers, creation-key deduplication and assets belong
+to exactly one registered project, even when projects use the same team key.
+Project credentials select that repository. An optional `context.repo` selector
+must match the credential's project; mismatches are 403. Owner admin requests
+require this selector and registration is checked before configuration is read.
+Internal operator credentials remain forbidden on machine ticket routes.
+
 The strict request envelope is:
 
 ```json
@@ -31,12 +80,30 @@ The strict request envelope is:
 }
 ```
 
-`teamKey` is required. The state overrides are optional. They come from the
-requesting repository's `[tickets]` configuration and are applied only to that
-request; the service does not cache a team-bound adapter. `list-ready` also
-receives that repository's exact ready state and label criteria in `input`.
-Backend credentials, including `LINEAR_API_KEY`, are service environment only
-and never occur in this envelope or any response.
+`teamKey` remains required for older client compatibility. It and the optional
+`claimedState` / `createState` fields are ignored as policy inputs. The service
+loads the project's latest effective configuration from its repository journal
+and artifact bytes for every operation. Missing or invalid configuration returns
+an actionable 409; run the project's dispatcher to publish its configuration.
+There is no deployment-wide lifecycle fallback.
+
+Hosted lifecycle defaults are triage `Backlog`, claimed `Doing`, done `Done`,
+and create/proposal equal to triage. `readyState` is required. The allowed states
+are the distinct union of these configured roles, including custom create and
+proposal states; roles may overlap. Historical states remain readable unchanged.
+`tickets.doneState` controls completion and the dispatcher's merged transition.
+
+The service never contacts Linear or relays external trackers. If the project's
+source is Linear, file or another non-hosted source, machine HTTP, operator and
+MCP ticket surfaces refuse with a message naming that project and source: its
+tickets live in its own source, accessed directly by its dispatcher. This is a
+409 conflict, not an empty queue. The dispatcher's direct adapters are unchanged.
+
+`AB_TICKET_BACKEND` and `LINEAR_API_KEY` are removed service settings. Their
+presence (even blank or unknown values) is ignored and emits one startup removal
+message. `AB_TICKET_TRIAGE_STATE`, `AB_TICKET_READY_STATE`,
+`AB_TICKET_DOING_STATE` and `AB_TICKET_DONE_STATE` are removed and ignored,
+including malformed values. These retired settings do not prevent startup.
 
 ## Operations
 
@@ -74,6 +141,32 @@ environment values, or credentials. Client 401/403 responses become
 `AuthError`; other backend messages remain actionable.
 
 The shared `TicketSource` contract is normative for the database adapter and
-the hosted client/server pair. External pass-through is tested with a fake
-source behind HTTP. The existing opt-in live Linear contract remains the proof
-of Linear's GraphQL behavior; the hosted service uses that adapter unchanged.
+the hosted client/server pair. PostgreSQL migration and isolation tests prove
+project partitions. The direct Linear client retains its separate opt-in
+GraphQL contract; no Linear adapter ships through the hosted ticket entry point.
+
+Every ticket returned by list, get, or create requires a boolean `resolved`,
+with the same source-native completion semantics as `DependencyState.resolved`.
+The client preserves it when remapping ticket references. Missing or non-boolean
+values fail wire validation. Client and service follow the published compatibility window.
+
+Legacy 0.9.x and 0.10.x ticket responses omit `resolved` and `blockersResolved`
+because those clients use strict decoders without these fields. This projection
+applies to list-ready, get, and create responses. Current clients retain the
+current required resolution fields; domain and storage types are unchanged.
+
+## Delegated execution credentials
+
+Build and harvest runners exchange project authority for signed, project-bound
+execution and phase credentials through `/credentials/delegate` (see the remote
+store protocol). Build-runner and build-phase credentials cannot call any ticket
+operation. Harvest-phase credentials permit only list-ready, get and
+dependency-states. Harvest-runner credentials permit those reads plus create
+for filing proposals. Claim, comment, transition, update, add-blocker and
+remove-blocker require project or admin authority; their access is unchanged.
+Denied delegated calls return 403 with an error naming the grant kind and
+operation before body parsing or source construction. Lifecycle retirement and
+project removal are also checked before parsing or source construction.
+
+Ticket admission and assets use the authenticated project, including for
+delegated harvest grants.