@astrasyncai/verification-gateway 5.17.2 → 5.18.1

package/CHANGELOG.md

@@ -0,0 +1,1878 @@
+# Changelog
+
+All notable changes to `@astrasyncai/verification-gateway` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Full architectural context for each release lives in the platform spec at
+`docs/research/adapter-architecture-technical-requirements.md`.
+
+## [5.18.1] — 2026-10-17 — guard browse --open; proxy help page; browser command printed
+
+### Added
+
+- **`astrasync guard browse --open`** starts Chrome, Edge or Chromium through
+  the device proxy (its own profile, and
+  `--ignore-certificate-errors-spki-list` pinned to the proxy's local
+  certificate, so every other site is checked as usual; Chrome still shows an
+  "unsupported command-line flag" bar, which the output says to close) on the one-time sign-in link as soon as the code
+  arrives. On WSL a native Linux Chromium (on `PATH` or Playwright's) is
+  preferred over the Windows browser, which may not reach the WSL loopback
+  proxy. With no browser found it prints the command to start one.
+
+### Changed
+
+- **`guard browse` prints a ready-to-paste browser command** (PowerShell on
+  Windows and WSL, a shell line elsewhere) before the Playwright hint, with a
+  tip to re-run with `--open`.
+- **The proxy address explains itself.** Opening `http://127.0.0.1:<port>`
+  directly now shows a short page — it only works as a browser proxy, and how
+  to open the sign-in link — instead of `400 absolute URL required`.
+
+### Fixed
+
+- **Ctrl-C stops `guard browse` while a browser is still open.** Stopping waited
+  for the browser to close its proxy connections, which it never does. The
+  proxy now ends them, and a second Ctrl-C (or a stop taking over 2 s) exits
+  anyway.
+
+## [5.18.0] — 2026-10-16 — checkout kit fixes, orders, Express mounting, MPP interop
+
+### Fixed
+
+- **A held purchase never settles (UCP + ACP kits).** The kits only treated a
+  `requires_approval` outcome or a `stepUpApproval` with `status: 'pending'`
+  as a hold, but verify-access step-up results carry `requiresStepUp`,
+  `requiresApproval`, `recommendation: 'step_up_required'` and
+  `policyAllowed: true` — so a held purchase reached `settle` and `fulfil`.
+  Any of those signals, or a `stepUpApproval` that isn't `consumed`, now holds:
+  UCP `requires_escalation` with `continue_url` = the approval page, ACP
+  `pending_approval`. A just-redeemed approval (`status: 'consumed'`) proceeds.
+  `StepUpApprovalInfo.status?: 'pending' | 'consumed'` is typed.
+- **`settle` → `pending` no longer creates an order.** The session stays
+  `complete_in_progress` with no order until your processor confirms; see
+  `resolvePending` below.
+- **Concurrent completes can't both charge.** `complete` claims
+  `complete_in_progress` before verifying (new optional
+  `CheckoutStore.claim(id, from, to)`, an atomic compare-and-set; the memory
+  stores implement it). The loser gets the session unchanged plus a
+  recoverable `checkout_in_progress` message (UCP) or `409
+checkout_in_progress` (ACP). A store without `claim` logs a one-time warning.
+- **Caller scoping.** Sessions and idempotency keys were scoped to the raw
+  `Authorization` header (ACP, `''` when absent — shared by every
+  unauthenticated caller) or to the `UCP-Agent` profile (UCP — shared by every
+  agent on a platform). They're now scoped to the verified ASTRA-id
+  (`kit.handle(req, { callerId })` / `resolveCallerId`), else `Authorization`,
+  else `X-Astra-Id`; UCP falls back to the platform profile, ACP refuses a
+  request with none (401). Scopes are stored hashed — no bearer token is
+  written to your store. Sessions created before the upgrade aren't found
+  afterwards. `beginIdempotent` has no shared `anon` scope any more: a request
+  with no caller isn't deduplicated, or gets `401 idempotency_caller_required`
+  when `required`; `idempotencyMiddleware` / `withIdempotency` also accept
+  `X-Astra-Id` as the caller.
+- **UCP `complete` needs exactly one payment instrument** whose `handler_id`
+  is one of the profile's `payment_handlers` (handler `id` or name); anything
+  else is `payment_failed` and nothing is verified.
+- **UCP `UCP-Agent` is bound to the verified agent.** `checkUcpAgentBinding`
+  was exported but unused: after `verifyPurchase` the kit now checks the
+  profile against `result.agent.protocolIdentities` (or
+  `resolveIdentities(req, result)`); a mismatch is `ucp_agent_mismatch` and
+  never settles. `ucpAgentBinding: 'registered'` (default) passes agents with
+  no registered profile (bridge-relayed calls); `'strict'` refuses them;
+  `'off'` skips it.
+- **UCP GETs don't re-sign.** `render()` signed `ap2.merchant_authorization`
+  and wrote the session on every response, including GETs. A GET now returns
+  the stored authorization when it signs the same view.
+- **Canceling a completed or canceled checkout is `405`** (UCP and ACP).
+- **Express: credentialed callers on unmatched routes.** The no-match
+  pass-through ran before credentials were read, so
+  `evaluateAlwaysIfCredentialed` never applied to unmatched routes. Credentials
+  are read first; with the flag and an `X-Astra-Id` the request is evaluated in
+  observe mode (never vetoes, sets `req.agentVerification`).
+- **`detectCommerce`: signed UCP requests are UCP.** The RFC 9421 branch ran
+  first, so a signed UCP call was labelled plain `rfc9421`. UCP is checked
+  first and carries the signature as its `rfc9421` artifact.
+- **MPP challenge ids match mppx.** `buildMppChallenge` / `verifyMppChallenge`
+  bound a newline-joined `key=value` list; mppx binds pipe-joined positional
+  slots `realm|method|intent|request|expires|digest|opaque`. Ids now
+  interoperate both ways (ids issued by 5.15.0–5.17.2 no longer verify).
+  `buildMppChallenge` takes `meta` (encoded as `opaque`).
+
+### Added
+
+- **`kit.resolvePending(sessionId, { status: 'settled' | 'failed', processorRef?, txHash?, chainId?, failureCode? })`**
+  (UCP + ACP): call it from your processor's webhook. Settled → reports the
+  settlement, runs `fulfil`, completes the session (and sends the UCP order
+  webhook); failed → reports it and returns the session to
+  `ready_for_complete` / `ready_for_payment`. A second call is a no-op. The
+  stored result excludes the settlement token, voucher, mandates and KYAPay
+  token. Type `PendingResolution`.
+- **UCP `links`** (`{ type: 'terms_of_service' | 'privacy_policy' |
+'refund_policy' | 'shipping_policy' | 'faq', url, title? }[]`), returned on
+  every checkout and covered by the merchant authorization.
+- **UCP order capability:** `profile.orders: true` adds
+  `dev.ucp.shopping.order` (`UCP_ORDER_CAPABILITY`); `GET /orders/{id}`;
+  `buildUcpOrder(session)` (type `UcpOrder`); `webhook: { url?, privateKey?,
+keyId?, businessProfileUrl?, attempts?, fetch?, onResult? }` sends the signed
+  order entity via `sendUcpWebhook` when an order is created (URL defaults to
+  the platform profile's order `config.webhook_url`, key to `signingKey`);
+  `kit.sendOrderWebhook(sessionId)` re-sends after an update. Optional
+  `CheckoutStore.findByOrderId(orderId)`.
+- **`permalinkBase`** (UCP + ACP): `permalink_url` when `fulfil` returns none.
+  ACP `order.line_items` now mirrors the session's line items, plus
+  `checkout_session_id`.
+- **ACP:** `API-Version` values are checked (`400 unsupported_api_version` with
+  `supported_versions`; `ACP_SUPPORTED_API_VERSIONS`); `Idempotency-Key` and
+  `Request-Id` are echoed on responses; `buildAcpWellKnown({ endpoint,
+paymentHandlers, apiVersions?, links? })` and `acpPaymentHandlers()`;
+  `AcpCheckoutStore` type.
+- **`expressHandler(kit, { callerId? })`** (root and
+  `@astrasyncai/verification-gateway/kit-express`): mounts a fetch-style kit on
+  Express and keeps the raw body (`express.raw()` or `req.rawBody`) for
+  signature checks; passes `req.agentVerification`'s verified ASTRA-id as the
+  caller.
+- **`kit.handle(req, ctx?: KitRequestContext)`** and the `resolveCallerId`
+  option (UCP + ACP).
+- **Express `defaultRoutePolicy: 'pass' | 'observe'`** (default `'pass'`):
+  `'observe'` evaluates unmatched routes in observe mode for any caller with
+  AstraSync credentials.
+- **In-memory store warning:** the kits warn when they run on their in-memory
+  stores outside `NODE_ENV=test`.
+- **MPP:** `buildMpp402Response(challenges, problem?)` (402, one
+  `WWW-Authenticate` per method, `Cache-Control: no-store`,
+  `application/problem+json`); `verifyMppChallenge(challenge, secret, { now?,
+body?, store? })` → `Promise<MppVerifyResult>` checks the body against the
+  challenge `digest` and, with a `MppChallengeStore` (`MemoryMppChallengeStore`),
+  accepts each challenge once; `mppBodyDigest()`. The `(challenge, secret,
+now?)` boolean form is unchanged.
+- `CHANGELOG.md` ships in the package.
+
+### Notes
+
+- mppx stays pinned at 0.8.2. 0.13.x has the same challenge-id binding, but
+  installing it raises the monorepo's `viem` (peer `>=2.57.1`) and
+  `@x402/core`, and its `eventsource-parser` dependency needs Node 22.12+.
+
+## [5.17.2] — 2026-10-15 — guard browse says where to approve
+
+### Changed
+
+- **`astrasync guard browse` prints the approval link** while it waits for the
+  owner's passkey (`Approve it at: https://…/activity/pending/<id>`), from the
+  sign-in route's new `approvalUrl`. There is no push notification: the owner
+  approves in the dashboard while signed in, and the link takes them there.
+- **Fleet enrolment commands** in the docs name the binary:
+  `npx -y -p @astrasyncai/verification-gateway astrasync guard …`. The package
+  installs several commands, so `npx @astrasyncai/verification-gateway guard …`
+  fails with "could not determine executable to run".
+
+## [5.17.1] — 2026-10-13 — one approval for a route that holds its own
+
+### Added
+
+- **`approvalHeldByRoute` (Express).** A function that returns true for
+  requests whose route asks the owner for approval itself — it creates its own
+  hold and answers `202` while it waits, as AstraSync's agent dashboard sign-in
+  does. For those requests a result that only needs the owner's approval is
+  passed to the route (`req.agentVerification` carries `requiresStepUp` and the
+  `failures` naming what needs approving) instead of refused, and verify-access
+  is told so it creates no approval of its own. The owner approves once. Any
+  deny is still refused, and so is a result that already carries a
+  `stepUpApproval`.
+
+```ts
+createMiddleware({
+  // …
+  approvalHeldByRoute: (req) => req.method === 'POST' && req.path === '/signin',
+});
+```
+
+### Fixed
+
+- **A hold on purpose, duration, scope or sub-agents is no longer described as
+  a spending limit.** The refusal now reads "The agent's owner asked to approve
+  this kind of request" and lists the server's `pdlss.<dimension>.approval_required`
+  entries; `commerce.intent.approval_required` and "Transaction is above the
+  autonomous limit" are kept for spending holds only.
+- **Step-up results carry the server's `failures`.** An allowed-but-escalate
+  result now includes what needs approving, as a deny always has.
+- **`astrasync guard browse` says why a sign-in was refused.** It read the
+  route error shape only, so a gateway refusal printed "no detail". A refused
+  status check (wrong device, unknown sign-in) now stops at once instead of
+  waiting 10 minutes for an approval that can't arrive.
+
+## [5.17.0] — 2026-10-12 — `astrasync guard browse` (agent dashboard sign-in)
+
+### Added
+
+- **`astrasync guard browse`.** Signs an agent in to its owner's AstraSync
+  dashboard from this machine (round 28.5). It starts a local device proxy
+  for the AstraSync host, asks to sign in through the agent's Workforce Guard
+  checkpoint with this machine's Local Guard device credential, waits for the
+  owner's passkey approval when the agent's policy asks for it, and prints
+  the one-time sign-in URL to open through the proxy. The session is bound to
+  this machine: a copied cookie without the device is refused.
+- The proxy carries WebSockets and tunnelled plain HTTP, and serves the
+  AstraSync host with a locally generated certificate.
+
+```bash
+astrasync guard browse --checkpoint <checkpoint-url> --slug <agent-slug> \
+  [--upstream astrasync-api] [--port <n>] [--host <extra-host>]
+```
+
+- **Flags.** `--checkpoint` (required): the Workforce Guard checkpoint's base
+  URL. `--slug` (required): the agent's checkpoint slug. `--upstream`: the
+  checkpoint's upstream for the AstraSync API (default `astrasync-api`); the
+  sign-in goes to `<checkpoint>/a/<slug>/h/<upstream>/agent-sessions`.
+  `--port`: the local proxy port (default: any free port; it listens on
+  `127.0.0.1` only). `--host`: one extra hostname that also gets the device
+  credential (for example a separate app host); the enrolled AstraSync API
+  host always does.
+- **Prerequisites.** The machine is enrolled in the organisation's fleet with
+  `astrasync guard enroll <token>` (user scope by default; `--system` enrols
+  the whole machine and needs administrator rights). The agent is linked to
+  a Workforce Guard checkpoint whose upstream for the AstraSync API forwards
+  the device credential, and the agent's policy allows the `dashboard.signin`
+  action (off for every agent until the owner allows it; put it on the
+  approval list to require the owner's passkey for each sign-in). The site's
+  route policy must allow the sign-in route, and the platform requires a
+  passed runtime challenge, which the checkpoint answers.
+- **Certificate.** The proxy terminates TLS only for the AstraSync hosts,
+  with a self-signed ECDSA P-256 certificate generated in memory at start
+  (valid 30 days, never written to disk or added to a trust store). Point the
+  automation browser at the proxy and let it ignore certificate errors, e.g.
+  Playwright `chromium.launch({ proxy: { server: 'http://127.0.0.1:<port>' } })`
+  with `newContext({ ignoreHTTPSErrors: true })`. The proxy re-originates to
+  the real host over verified TLS. Every other host is a blind tunnel that
+  the proxy never inspects.
+- **One-time code.** Once signed in (or once the owner approves), the command
+  prints `<site>/agent-session#code=…`. Open it once, through the proxy,
+  within 2 minutes: the code is single use, bound to this machine, and rides
+  in the URL fragment so it never reaches a server log or a Referer. The page
+  exchanges it for the session cookie and drops it from the address bar.
+- **Session gate.** Every request in an agent session must carry the
+  machine's device credential (the proxy adds it; the browser never holds
+  it). A request without it, or from another device, ends the session. Each
+  request is checked against the agent's policy as `dashboard.read` or
+  `dashboard.change`. When the policy asks, or the area is admin, the owner
+  approves that exact request with a passkey (202 `OWNER_APPROVAL_REQUIRED`).
+  Ctrl-C stops the proxy.
+
+## [5.16.0] — 2026-10-07 — Per-route owners + runtime challenge, governed git
+
+### Fixed
+
+- **UCP detection needs the `UCP-Agent` header.** A request to any
+  `/checkout-sessions` path was treated as a UCP checkout and verify-access
+  replaced the route's purpose with `commerce.unknown` — an ordinary API with
+  such a route was denied. UCP platforms always send `UCP-Agent`, so detection
+  now requires it.
+
+### Changed (security — breaking for hand-rolled challenge responders)
+
+- **`ChallengeHandler` no longer auto-includes.** Since 3.7.1, a handler with
+  nothing registered as pending answered with whatever counterparty the
+  challenge asked about. That made the runtime challenge prove only that the
+  agent's server was up: anyone presenting the agent's ASTRA-id passed. It
+  now answers only for counterparties registered with `registerPending()`
+  (counted, so concurrent calls to one counterparty don't clear each other).
+- **`AgentClient` does the registering for you:** pass `challengeHandler` to
+  the client and each `fetch()` registers its destination (by origin, and by
+  `counterpartyId` when you pass the ASTRAE-id) for exactly as long as the
+  call is in flight.
+- **Migration:** if you call counterparties without `AgentClient`, wrap each
+  call in `registerPending(id)` / `removePending(id)`. Endpoints that require
+  the challenge deny calls that aren't pending.
+
+### Added
+
+- **Per-route policy fields** (set on the endpoint's routes in the dashboard):
+  `allowedOwners` (only agents owned by the listed ASTRAO-/ASTRAD-/ASTRAI-ids
+  pass the route) and `requiresRuntimeChallenge` (the runtime challenge on
+  this route only). The Express and Next.js middleware forward the matched
+  route's values to verify-access as `routePolicy`, which enforces them — the
+  agent's owner is resolved by AstraSync and never disclosed to you. Routes
+  without them behave exactly as before. `routePolicyOf(route)` and the
+  `RoutePolicy` type are exported.
+- **`astrasync guard git-route`**: routes this machine's `git fetch` / `git
+push` to github.com through your organisation's Workforce Guard checkpoint
+  (`--checkpoint <url> --slug <connector> --agent <ASTRA-id>`, `--undo`).
+  `git commit` and its local hooks are unchanged. The checkpoint checks each
+  push against the agent's mandate (protected branches, deletions, repository
+  allow-list) and attaches the git host token from the AstraSync vault; the
+  machine authenticates with its Local Guard device credential via the new
+  `astrasync guard git-credential` helper. No git host token is stored on the
+  machine.
+
+## [5.15.0] — 2026-10-06 — Agentic commerce protocols: AP2 mandates, UCP/ACP kits, KYAPay, signing
+
+### Added
+
+- **`reportSettlement()` errors:** throws `SettlementReportError` (`statusCode`,
+  `code`, `issues`). `isRetryableSettlementError(err)` is true for network
+  failures (`statusCode: 0`), 429 and 5xx; every other error is final.
+- **Agent protocol identities:** `result.agent.protocolIdentities` (agent
+  signing key, UCP profile, Web Bot Auth key directory, A2A card, x402 wallet,
+  network agent ids, and which AstraSync verified).
+- **`checkUcpAgentBinding(header, identities)`** / `parseUcpAgentHeader()`:
+  reject a `UCP-Agent` profile that isn't the agent's registered one
+  (`ucp_agent_mismatch`, `invalid_ucp_agent`).
+- **Idempotency:** `idempotencyMiddleware()` (Express) and `withIdempotency()`
+  (fetch / Next.js) with `MemoryIdempotencyStore` / `RedisIdempotencyStore`.
+  Same key + same request replays the stored response
+  (`Idempotent-Replayed: true`); store down → 503 `idempotency_unavailable`;
+  5xx responses aren't stored. 24 h.
+- **RFC 9421 signing:** `signHttpRequest()` (ES256 / Ed25519, `tag`, `nonce`,
+  RFC 9530 `Content-Digest`). Verification now also checks that a covered
+  `Content-Digest` matches the body.
+- **Route patterns:** `:name` matches one path segment; `routePatternToRegExp()`
+  / `matchRoutePattern()` are shared by the Express, Next.js and edge
+  matchers. Literal characters such as `.` are now escaped (previously `.`
+  matched any character).
+- **`StepUpApprovalInfo.approvalUrl`:** the buyer-facing approval page. Return
+  it as UCP `continue_url` with `requires_escalation`.
+- **`EdgeConfig.minTls`** (`'1.2' | '1.3'`): agent requests below it get 426 in
+  enforce mode and are logged in observe mode; browsers are never gated.
+- **Express / Next.js adapters forward protocol artifacts** (VI, AP2, ACP, UCP,
+  MPP, x402 payloads; Visa TAP / Mastercard Agent Pay / Web Bot Auth
+  signatures) to verify-access, as the edge already did. Keep `req.rawBody` for
+  exact body-signature verification.
+
+- **AP2 v0.2 mandates** (delegate SD-JWT, `~~` chains, exact `vct`s):
+  `verifyAp2Mandate()` (root signer by kid, KB hops against `cnf`,
+  `sd_hash` / `issuer_jwt_hash` binding, expiry, unknown constraints fail,
+  `checkout_hash` = SHA-256 of `checkout_jwt`), builders
+  (`closedCheckoutMandate`, `closedPaymentMandate`, `openCheckoutMandate`,
+  `openPaymentMandate`), `signRootMandate()`, and `createKbHop()` for agents
+  closing an open mandate.
+- **`result.mandates`**: AP2 mandates AstraSync issued (merchant lane).
+  Pass your signed checkout as `checkoutJwt` (verify / `confirmCheckout`).
+- **`result.kyaToken`**: a KYAPay `kya+jwt` for the agent at your endpoint
+  (`hid.email` = where to send the receipt). `verifyKyaPayTokens()` verifies
+  `KYAPay-Token` headers (identity tokens only unless you opt in to pay).
+- **UCP 2026-08-25**: `createUcpCheckoutKit()` (create / get / update /
+  complete / cancel; negotiation, idempotency, optional signature checks,
+  AP2 merchant authorization + mandate checks, escalation →
+  `requires_escalation` with the approval URL), `buildUcpProfile()`,
+  `fetchUcpProfile()` (SSRF-guarded), `negotiateUcp()`, `signUcpRequest()` /
+  `verifyUcpRequest()` / `signUcpResponse()`, `sendUcpWebhook()`, message
+  builders.
+- **ACP 2026-04-17**: `createAcpCheckoutKit()` (step-up → `pending_approval`
+  with the approval URL; API-Version and Idempotency-Key required).
+- **A-Comm Evidence Protocol (AEP v1.0.3-rc.2):** `AepChain`,
+  `aepCanonicalJson`, `aepHash`, `aepSign`, `verifyAepChain`,
+  `aepPublicKeyDocument` — reproduces the published conformance vectors
+  byte for byte. `result.aep` (when your endpoint lists `aep`): AstraSync's
+  policy, delegation and platform-countersigned intent payloads to append to
+  your chain.
+- **x402 v2 / MPP helpers** (`buildX402Challenge`, `parseX402Payment`,
+  `x402PaymentMatchesOffer`, `buildMppChallenge`, `verifyMppChallenge`,
+  `encodeMppReceipt`, …). The merchant's facilitator / processor settles.
+
+### Changed
+
+- **Idempotency** follows the spec of your protocol: `profile: 'ucp'`
+  (default; raw body, 409) or `'acp'` (canonical JSON, 422
+  `idempotency_conflict`; 409 `idempotency_in_flight` with `Retry-After`).
+  The key is echoed on responses.
+- **x402 v2 is read from `PAYMENT-SIGNATURE` / `PAYMENT-REQUIRED`** (was the
+  body); v1 headers still work. MPP `Payment-Authorization` is detected.
+  ACP 2026-04-17 `payment_data.instrument.credential.token` is read.
+- Requests carrying protocol artifacts are never served from or written to
+  the verify cache.
+- `RegistryName` gains `'astrasync'` (the platform's composite resolver).
+
+## [5.14.1] — 2026-10-05 — AstraSync never charges; runtime challenge is opt-in
+
+### Changed
+
+- **Every purchase is settled by the merchant.** The platform no longer
+  charges any card itself. A purchase grant records an order and returns
+  `settlementOutcome: { status: 'pending_merchant', orderId }` together with
+  the artifact the merchant settles: `settlementToken` for a card on the
+  first-party Stripe tenant, or the `settlement` voucher (stablecoin) for any
+  merchant. Redeem the voucher, then call `reportSettlement()`.
+- **`reportSettlement()`** accepts `orderId` instead of `sessionId`, and a
+  stablecoin `txHash` (+ `chainId`) instead of a card `processorRef`. Every
+  merchant may report, not only first-party ones.
+- **The voucher redeem response** no longer carries a `settlement` block (no
+  charge happens at redeem). It carries `order: { status: 'redeemed' }` when
+  the voucher funded a recorded order.
+- **A voucher is minted only on a purchase leg**: the confirm leg, or an
+  unphased call that carries a value. Browse and quote calls no longer mint.
+  When the request's commerce protocol already carries the payment
+  credential (ACP / MPP token, x402 payment payload, AP2 payment mandate),
+  nothing is minted and the order settles by report-back.
+- **Runtime challenge is opt-in.** `enableRuntimeChallenge` defaults to false
+  (backend and the Next.js adapter). Ask for it explicitly, or set the
+  endpoint's `requiresRuntimeChallenge`.
+
+### Fixed
+
+- **A dead agent callback no longer stalls verify.** A callback that times
+  out or can't be reached gives the same outcome for 60 seconds without being
+  called again, and at most 5 challenges are in flight to one host — the rest
+  resolve at once as `timeout`.
+
+### Migration
+
+- Merchants that relied on the platform charging first-party cards must now
+  charge the `settlementToken` and report back (the 5.5.0 self-settle flow).
+
+## [5.14.0] — 2026-10-03 — edge beacons are no longer stranded in a reclaimed container
+
+### Fixed
+
+- **Repeat beacons are no longer held for 60 seconds.** The edge buffer used
+  to collect repeats of the same request (same caller, user agent and path)
+  into an aggregate that waited until its 60-second window closed. Lambda@Edge
+  has no `waitUntil`, so that aggregate was only sent if the same container
+  was invoked again after the window. When AWS reclaimed the container first,
+  the beacons were lost. On staging on 3 Oct, only ~68% of agent and script
+  requests were beaconed. Repeats now merge only into an item that is still
+  queued. Otherwise the repeat is a new item, sent on the same flush. Under
+  load, repeats still merge while a batch is in flight.
+
+### Added
+
+- **Batch metadata identifies the container.** Each batch's `meta` now
+  carries `containerId` (one per cold start) and the container's cumulative
+  `enqueuedTotal`, `deliveredTotal` and `droppedTotal`. The backend uses them
+  to count items left queued in a container that stops reporting, which the
+  container's own drop counter can't report.
+
+## [5.13.0] — 2026-10-02 — a key that can't verify for its endpoint fails at deploy
+
+### Added
+
+- **The startup self-check names the endpoint.** When `counterpartyId` (or
+  `counterpartyUrl`) is configured, the one-time init check sends it to
+  `GET /agents/verify-access/self-check`. The backend answers whether this API
+  key may verify for that endpoint: verify-access now only accepts a key whose
+  account owns the endpoint, or an active member of the organisation that owns
+  it. A key from another account, or an unknown endpoint, is logged loudly at
+  startup (`strictInit: true` throws) instead of every inbound agent being
+  refused with `COUNTERPARTY_KEY_MISMATCH`.
+
+- **A refused route-policy read is no longer silent.** When the Express or
+  Next.js middleware can't read its endpoint's route policy (HTTP 401/403/404:
+  a key from another account, or a wrong `counterpartyId`), it now logs one
+  loud error per endpoint saying the gateway is in pass-through mode and no
+  agent is being verified. It used to fall through quietly. Transient 5xx
+  failures stay quiet and are retried on refresh.
+
+### Changed
+
+- **A 403 `COUNTERPARTY_KEY_MISMATCH` is merchant misconfiguration**, like a
+  rejected key: `misconfigured: true`, `misconfigCode:
+'counterparty_key_mismatch'`, failure dimension
+  `verify_access.merchant_misconfigured`, and the agent is told to contact the
+  site operator. It was previously a retryable `api_error` ("temporarily
+  unavailable — retry"), which retrying can never fix.
+
+### Fixed
+
+- **`viem` is a declared dependency.** `mppx` 0.8.2 imports `viem` when the
+  package loads but only lists it as a peer, so an install that skips peers
+  (`legacy-peer-deps`) failed at import with `Cannot find package 'viem'`.
+
+### Notes
+
+- Older backends ignore the query and return no `counterparty` block: silent,
+  as before.
+
+## [5.12.0] — 2026-10-01 — verification outages are retryable, never an identity deny
+
+### Changed
+
+- **Outage posture in the Express, Next.js and MCP adapters and `quickVerify`.**
+  When verify-access is unreachable or rate-limited, an observe route or an
+  anonymous read (GET/HEAD; for MCP, anything other than `tools/call`) is
+  served and tagged `X-Astra-Verification: unavailable`. An enforced route
+  returns **503** with `Retry-After` (the backend's value, else 30 s) and
+  `VERIFICATION_UNAVAILABLE`. For MCP that is JSON-RPC `-32003`,
+  `recommendation: 'error'`, retryable. Previously an outage — including a
+  429 — produced **401 UNAUTHORIZED**, so anonymous catalog reads failed
+  closed.
+- `failOnError: 'closed'` now fails with the same retryable 503 instead of an
+  identity-shaped 401.
+- **Identity status mapping.** Missing credentials still get 401. A presented
+  identifier that is malformed or unknown now gets **403**
+  `AGENT_IDENTITY_REJECTED` with registration guidance. A 404 from
+  verify-access (unknown agent) is an identity deny, not an `api_error`.
+- `VerificationResult` gains `httpStatus` and `retryAfterMs`. Non-JSON error
+  bodies (e.g. a proxy 429) keep their status and `Retry-After`.
+- `reportAttempt(config, report, { onFailure })` checks the response status
+  and retries once on 429/5xx, honouring `Retry-After` (capped at 2 s). It
+  never throws. `AttemptReport.servedFrom` (`'bridge_cache' | 'merchant'`) is
+  new.
+- **Edge beacons are buffered and batched.** The edge core queues beacons in
+  memory (up to 1,000 items, dropping the oldest first) and sends batches of
+  up to 100 to `/verification-activity/edge-events` with the endpoint's API
+  key. An in-flight send carries over to the next invocation. Failed batches
+  are retried up to 3 times, and a 429 is honoured. Identical requests within
+  60 s are collapsed into `repeatCount`. Each batch reports `droppedSinceLast`
+  and `queueDepth`. This fixes the ~60% beacon loss on Lambda@Edge, where a
+  300 ms budget used to drop single beacons.
+- `reportUnregisteredAttempt` and the Express/Next anonymous beacon send the
+  API key when one is configured, so rows are attributed as verified.
+- `confirmCheckout()` accepts `attemptId`.
+- The ChatGPT platform signature now matches `GPTBot` and `OAI-SearchBot`.
+- **A recognised but unregistered agent's read is served.** An allowed
+  verify-access response that says `step_up_required` for a caller with no
+  verified identity is treated as a grant. Step-up is for a registered
+  agent's owner to approve a valued action; an unregistered caller has no
+  owner. Older backends sent that verdict for recognised platform agents
+  (Claude-User, the AstraSync bridge) on plain reads, and every adapter
+  answered **401** "requires human approval" to an anonymous catalog GET
+  (since 5.0.0). A registered agent's valued step-up still fails closed.
+- **An unknown agent id is an identity rejection.** The backend's 200
+  `agent.lookup` deny (a well-formed id that matches no registered agent) now
+  gets **403** `AGENT_IDENTITY_REJECTED` with registration guidance, like the
+  404 mapping, instead of a policy deny. It is never `identityVerified`.
+- **`observe` never vetoes.** With `evaluateAlwaysIfCredentialed`, a
+  credentialed call to an `observe` tool (MCP) or route (Express) now passes
+  through whatever the verdict, as documented. It used to be denied (MCP:
+  403 / `-32001`, or 400 `PDLSS_PURPOSE_REQUIRED` with no purpose). Enforced
+  tools and routes are unchanged.
+
+### Added
+
+- `failure-posture` helpers: `isVerificationUnavailable`,
+  `unavailableRetryAfterSeconds`, `buildVerificationUnavailableBody`,
+  `denyStatusFor`, `isRejectedIdentityClaim`, `VERIFICATION_STATUS_HEADER`.
+- `BeaconBuffer`, `getBeaconBuffer`, `resetBeaconBuffer` (edge core).
+
+### Migration
+
+- If you have a custom `onDenied` handler, branch on
+  `isVerificationUnavailable(result)` and return 503 + `Retry-After` rather
+  than 401.
+- If your MCP host sits behind a proxy, set Express `trust proxy` so the
+  caller IP is correct.
+
+## [5.11.0] — 2026-09-29 — Local Guard fleet mode (organisation-managed policy)
+
+### Added
+
+- **Fleet mode for Local Guard** (Workforce Guard / Enterprise Governance
+  orgs). `astrasync guard enroll <token> [--api-base-url <url>] [--system]`
+  enrols the machine with an org-minted token; from then on the Claude Code
+  hook, the Codex hook and the Cursor extension enforce the org's **central
+  signed policy** (ES256 JWS, `typ fleet-policy+jwt`, `aud
+astrasync:fleet-policy`, verified against the org's own key, pinned at
+  enrolment).
+  - **Key rotation without re-enrolment.** When the org rotates its key, the
+    platform returns a signed rotation chain (`typ fleet-keys+jwt`, each new
+    key signed by the one it replaces). The guard follows the chain from its
+    pinned key, stops trusting the retired key, and caches the chain in
+    `~/.astrasync/fleet/keychain.json` (re-verified from the pin on every
+    load). A heartbeat reporting a new `activeKid` triggers the refresh.
+  - Enrolled machines **ignore** every local `policy.yaml` / `guard.json`,
+    `ASTRASYNC_GUARD_DISABLE`, `ASTRASYNC_GUARD_FAIL_OPEN`, guard.json
+    `failOpen` and the passive default — posture, failOpen, governMcp and
+    skipTools come only from the signed settings.
+  - Fail closed: a bad signature, wrong `aud`/`typ`/`iss`/`sub`, a policy hash
+    mismatch, a version rollback or an unreadable enrolment denies. A revoked
+    device keeps enforcing its last good policy.
+  - `ASTRASYNC_FLEET_REQUIRED=1` (set by managed settings) makes an
+    unenrolled machine deny with the enrol instruction.
+  - Heartbeat after each decision, at most once per interval with a 1.5 s
+    budget (never delays a decision); a changed active policy is fetched,
+    verified and swapped in for the next call.
+  - Machine-scope enrolment (`--system`: `/etc/astrasync`,
+    `/Library/Application Support/AstraSync`, `%ProgramData%\AstraSync`) wins
+    over user scope (`~/.astrasync/fleet/`, 0600).
+- `astrasync guard fleet-status` and fleet lines in `astrasync guard status`.
+- `astrasync guard managed-settings [--claude] [--codex] [--out <dir>]`: MDM
+  templates — Claude Code `managed-settings.json` (managed PreToolUse hook,
+  `allowManagedHooksOnly`, `env.ASTRASYNC_FLEET_REQUIRED`, guard-file deny
+  rules) and Codex `requirements.toml` (`allow_managed_hooks_only`,
+  `[[hooks.PreToolUse]]`), per OS.
+- Root exports `parseLocalPolicyYaml` / `validateLocalPolicy` (+ result
+  types) so the platform validates fleet YAML with the guard's own parser.
+- `resolveGuard()` / `resolveFleet()` (fleet-first resolution);
+  `resolveGuardConfig()` keeps its 5.10.0 signature.
+- Claude Code permission deny rules now also cover the fleet enrolment paths
+  (`~/.astrasync/fleet/**` and the machine-scope directories).
+
+### Removed
+
+- `astrasync guard upgrade` no longer uploads the local policy to
+  `POST /api/v1/agents/policies/upload` — that route never existed, so the
+  upgrade always failed at that step. The flow now asks for the ASTRA- id of
+  an agent registered in the dashboard (optional) instead.
+
+Unenrolled machines behave exactly as in 5.10.0.
+
+## [5.10.0] — 2026-09-26 — only an ASTRA id is an agent claim at the edge
+
+### Fixed
+
+- **Edge classification: a bare `Authorization: Bearer` JWT (or a non-`kya_`
+  `x-api-key`) is no longer tiered `verified`.** verify-access is sent the ASTRA
+  id only, so such a request could never verify — under enforce it was always
+  denied ("Endpoint policy denies unverified agents"). That self-DoS'd any
+  property whose signed-in users call its own API with Bearer tokens (found on
+  AstraSync's own staging: first-party chat/OAuth sessions on `/api/*`). These
+  requests now classify on their other signals (UA / commerce protocol /
+  fingerprint) — a made-up token neither verifies nor bypasses the edge. An
+  `X-Astra-Id` (with or without a bearer) is still an agent claim.
+- **A malformed agent id is a deny, not an outage.** A non-canonical id
+  (e.g. `ASTRA-bogus123`) makes verify-access answer `400 INVALID_AGENT_ID`;
+  the SDK treated that as a transient `verify_access.api_error`, so the edge
+  returned 503 "verification unavailable — retry" under enforce. It is now an
+  identity deny (`identity.invalid_agent_id`, backend message + guidance) →
+  the edge's 403 with registration guidance. Other 400s are unchanged.
+
+## [5.9.0] — 2026-09-25 — `blockchainAnchored` (breaking rename)
+
+### Changed (breaking)
+
+- **`VerificationResult.agent.blockchainVerified` → `blockchainAnchored`.** The
+  server's `agent.blockchainStatus` values were renamed `verified` → `anchored`
+  and `unverified` → `not_anchored` (`pending` / `failed` unchanged). The flag
+  only ever meant "this agent's identity record is on-chain" — never an
+  identity-verification claim — and "verified" collided with the WHO axis
+  (`identityVerified`). Migration: replace `result.agent.blockchainVerified`
+  with `result.agent.blockchainAnchored`; direct-API consumers comparing
+  `blockchainStatus === 'verified'` compare against `'anchored'`.
+
+## [5.8.0] — 2026-08-20 — attempt-chain redemption (X-Astra-Attempt-Id)
+
+### Added
+
+- **Express + Next.js middleware read `X-Astra-Attempt-Id`** (the bridge
+  stamps it on every delivered venue call; the edge pipeline already read it)
+  and thread the id into the verify-access body. Server-side, a step-up
+  approval the owner already granted for the same attempt chain now passes
+  every later hop carrying the id — bridge pre-verify, the venue middleware's
+  re-verify, and post-failure re-drives — instead of minting a fresh approval
+  each time (the Meridian two-hop approval-loop fix). Values not matching
+  `att_<32 hex>` are dropped, never forwarded.
+- **README: bridge-fronted hold budgets** — documented the bridge's 30 s
+  default / 60 s max response budget (per-route `responseBudgetMs` override)
+  and the recommended venue `stepUpMaxWaitMs` posture behind the bridge, plus
+  the `X-Astra-Attempt-Id` wire contract for venue-side idempotency.
+
+## [5.7.0] — 2026-08-20 — first-party account keys at the edge + runtimeChallenge not_configured
+
+### Fixed
+
+- **Edge classifier: account API keys are first-party, never an agent claim.**
+  `classify()` previously tiered ANY `Authorization: Bearer` / `x-api-key`
+  credential as a `verified` agent claim, so plain API clients (curl, Postman,
+  non-SDK backends) presenting a VALID `kya_…` account key were sent through
+  verify-access — which can never verify an account key as an agent — and
+  enforce mode 403'd them ("Endpoint policy denies unverified agents"),
+  masking key validity and creating a self-DoS vector. A bare account-key
+  credential now classifies `self` (pass-through, zero beacons; origin auth
+  stays authoritative). An explicit `X-Astra-Id` alongside still classifies
+  as an agent claim.
+
+### Changed
+
+- **`runtimeChallenge.status`: `not_supported` → `not_configured`** (contract
+  correction, matches the backend): the value means THIS agent registered
+  without a callback endpoint, not that the capability is unsupported.
+
+## [5.6.0] — 2026-08-11 — fulfilment email: account default + agent override
+
+Additive, non-breaking.
+
+- **`fulfilment` on `VerificationResult`** (first-party confirm legs that
+  progressed — settled, pending_merchant, held, requires_action):
+  `{ email, emailSource }`. The platform now ALWAYS resolves a fulfilment
+  email for first-party orders: the agent-supplied `buyerEmail` when present
+  (`emailSource: 'agent_provided'`), else the buyer's account email
+  (`emailSource: 'account'`). Emails arrive canonicalized (trimmed,
+  lower-cased). Store it with the pending order; fulfil against it only once
+  the order is settled / pending_merchant. Merchant-only lane like
+  `settlementToken` — the bridge strips it from the agent plane.
+  `emailSource` is an open union: treat unknown sources like
+  `'agent_provided'`.
+- **`buyerEmail` on `VerificationRequest`** + a `buyerEmail` option on
+  `confirmCheckout()`: transit-only forward of an alternate receipt/delivery
+  contact. You no longer need to require agents to collect an email — omit
+  it and `fulfilment.email` carries the account default. Precedence when
+  both exist: an explicit `buyerEmail` (bridge handoff body or your
+  `confirmCheckout` call) wins over the account default.
+- Never emitted on quote legs or for non-first-party counterparties.
+
+## [5.5.0] — 2026-08-09 — merchant self-settlement (interim), open outcome union, fulfilment PII lanes
+
+Additive, non-breaking (one behavioral rule tightened — see the open union).
+
+- **`settlementToken`** on `VerificationResult` (confirm leg, firstParty
+  merchants opted into `settlement_mode='self_settle'`): agent-blind
+  `{ stripeCustomerId, stripePaymentMethodId, amountMinor, currency,
+sessionId, orderId, jti, statementSuffix, expiresAt }`. YOUR server charges
+  (Stripe idempotency key `voucher:<jti>` + `metadata.jti`) and reports back.
+  Merchant-only lane — never expose to the agent plane; the bridge strips it
+  defensively.
+- **`client.reportSettlement({ sessionId, status, amountMinor, currency,
+processorRef?, failureCode? })`** — reconciles the buyer dashboard,
+  /orders, and the agent's poll surface. Amounts must match the order
+  EXACTLY; replays of the same terminal state are safe.
+- **`SettlementOutcomeInfo.status` is now an OPEN union** (`… | (string &
+{})`). Contract rule, effective immediately: treat any status you do not
+  recognize (`pending_merchant` is the first) as **pending, never failed** —
+  the 5.4.1-era fail-close on an unknown status is what produced phantom
+  failed orders in the field.
+- **`no_instrument` on a held/approved session is NON-terminal**: the
+  human's approval is NOT consumed; once a card is on file, a re-drive with
+  the same `checkoutSessionId` redeems the original approval and settles.
+- **Fulfilment PII lanes** (bridge contract): optional `buyerEmail` rides
+  the checkout handoff transit-only (receipts / digital delivery — never
+  stored by AstraSync); shipping addresses go agent ↔ merchant DIRECT,
+  correlated by `sessionId`, never via AstraSync.
+- `SDK_VERSION` constant re-lockstepped with package.json (had drifted at
+  5.4.1 through the 5.4.2 type-only release).
+
+## [5.4.2] — 2026-08-08 — `requires_approval` settlement outcome (type-only)
+
+Type-only, non-breaking at runtime. Held confirm legs now carry an explicit
+`settlementOutcome: { status: 'requires_approval' }` alongside the pending
+`stepUpApproval` — merchants must record the order as _pending approval_ and
+expect a re-drive with the same `checkoutSessionId` (one order row per
+session is normative). Platforms emitted this status ahead of some deployed
+SDKs; if you are on 5.4.1, treat "absent outcome + pending stepUpApproval" —
+and any unknown non-terminal status — identically to `requires_approval`.
+
+## [5.4.1] — 2026-08-06 — confirm-leg cache correctness (UAT2 Bug B)
+
+Bugfix, non-breaking. Staging UAT found an under-limit confirm could return
+`unsettled_placeholder` non-deterministically: the verify cache key omitted
+`commercePhase`/`checkoutSessionId`, so a confirm issued within the cache TTL
+of its `start_checkout` quote was served the cached quote-leg grant (which
+carries no `settlementOutcome`) and never reached the backend — settlement
+silently did not run.
+
+- **Cache key** now includes `commercePhase` and `checkoutSessionId` (same
+  F-A1-07 bug class as the earlier duration/counterparty omissions): a quote
+  and a confirm for the same cart can never collide, nor can two carts.
+- **`confirmCheckout()` passes `bypassCache: true`** — belt-and-braces: the
+  confirm leg is the only leg that can settle, so it must always reach the
+  backend regardless of cache state.
+- **`VerificationGatewayClient` now honors `counterpartyId`** — the
+  constructor silently dropped this typed, documented option, so a
+  client-driven confirm could only identify its endpoint by URL; with
+  multiple endpoints on one origin the first-party resolution was
+  non-deterministic and settlement could silently not run.
+
+## [5.4.0] — 2026-08-05 — `confirmCheckout()` client method
+
+Additive, non-breaking. Exposes the 5.3.0 confirm leg through the high-level
+client so a first-party merchant no longer has to hand-roll `verify(config,
+request)` or raw `POST /api/agents/verify-access` to drive charge-at-redeem.
+
+- **`VerificationGatewayClient.confirmCheckout(options)`** — sends
+  `commercePhase: 'confirm'` with `checkoutSessionId` (per-cart idempotency),
+  `checkoutItems` (order/receipt plane), `transactionValue`/`currency`, and the
+  `counterpartyUrl`/`counterpartyType` that make the grant merchant-mediated.
+  `purpose`/`action` default to `shopping` / `shopping.purchase`. Returns the
+  full `VerificationResult`; read `.settlementOutcome`
+  (`settled` | `failed` | `requires_action` | `no_instrument`, + `orderId`).
+  Settlement fires only on this leg — `verify()` still cannot trigger it.
+- **`SettlementOutcomeInfo`** is now exported so consumers can type the outcome.
+
+No wire change: `commercePhase`/`checkoutSessionId`/`checkoutItems` were already
+forwarded and `settlementOutcome` already read back in 5.3.0 — this is purely the
+client convenience surface over them.
+
+## [5.3.0] — 2026-08-05 — first-party checkout phase + charge-at-redeem settlement outcome
+
+astra-pay card rail (PR #563). Additive, non-breaking: all new fields are
+optional and older backends/agents that never send or read them are unaffected.
+Builds on 5.2.0 (round-11, #564).
+
+### Added
+
+- **`VerificationRequest.commercePhase`** `'quote' | 'confirm'` — checkout-leg
+  discriminator. First-party settlement (charge-at-redeem on the owner's saved
+  instrument) fires ONLY on the `'confirm'` leg; quote/browse legs omit it (or
+  send `'quote'`) and never move money.
+- **`VerificationRequest.checkoutSessionId`** — per-cart idempotency key
+  forwarded on the confirm leg, so two concurrent confirms for one cart charge
+  the owner's card at most once.
+- **`VerificationRequest.checkoutItems`** — the checkout's authoritative line
+  items, forwarded on the confirm leg for the order plane (dashboard order
+  audit). Informational only — never the money authority (that remains
+  `transactionValue` bound into the settlement voucher).
+- **`VerificationResult.settlementOutcome`** + **`SettlementOutcomeInfo`**
+  `{ status: 'settled' | 'failed' | 'requires_action' | 'no_instrument',
+orderId?, failureCode? }` — sanitized first-party settlement result, present
+  INSTEAD of `settlement` when the counterparty is an AstraSync-operated
+  storefront and the backend redeemed the voucher + charged server-side. Carries
+  no voucher/instrument material — the settlement channel stays merchant-only.
+
+## [5.1.0] — 2026-08-04 — MCP-connector steering in agent-facing guidance
+
+Round-7 "kickstarting" fix: an anonymous agent reading a deny body was steered
+to the human dashboard ("register the agent") even when it was running inside
+an MCP host with the AstraSync connector installed. Guidance now offers the
+connector as the agent-actionable path wherever the backend advertises a
+hosted bridge.
+
+### Added
+
+- **`WellKnownAgenticCommerce.mcpEndpoint` / `.mcpDiscoveryUrl`** — optional
+  fields the backend's `/.well-known/agentic-commerce` doc emits on
+  astrasync.ai hosts (absent on self-hosted backends; validation unchanged, so
+  older backends keep working).
+- **`GuidanceInfo.mcp`** `{ endpoint, discoveryUrl?, message? }` — attached to
+  registration-shaped guidance (server-denied and no-credentials templates)
+  when the well-known cache carries `mcpEndpoint`. The copy states that
+  registration through the connector is keyless and human-approved (in-chat
+  approval card; the agent never handles credentials). `merchant_misconfig` /
+  `api_error` guidance deliberately does NOT steer to the connector —
+  registration is not the remedy there — and the in-connector registration
+  envelope (`registration/guidance.ts`) is unchanged.
+- **Edge deny body `error.guidance.mcp`** — threaded from `verify()` when the
+  well-known cache is warm, with a cold-cache fallback deriving
+  `https://mcp.<apex>/mcp` from `apiBaseUrl`, gated to astrasync.ai hosts so a
+  self-hosted deployment never advertises a dead endpoint.
+
+## [5.0.0] — 2026-08-02 — remove the `accessLevel` band (breaking)
+
+The access-level band (`none` / `restricted` / `read-only` / `standard` / `full`
+/ `internal`) is removed entirely. It never gated the access **decision** — the
+server does, resting on a **verified ID + runtime challenge + PDLSS match + trust
+score**. The band had been inert in the adapters since 3.2.0; this release drops
+it from the types, the result, the adapters, the edge core, and the UI so nothing
+consumes or advertises an arbitrary tier.
+
+### Removed (breaking)
+
+- **`AccessLevel` type** and all band helpers (`ACCESS_LEVEL_HIERARCHY`,
+  `ACCESS_LEVEL_DESCRIPTIONS`, `DEFAULT_TRUST_THRESHOLDS`, `hasMinimumAccess`,
+  `getAccessLevelForScore`, `determineAccessLevel`, `getCapabilities`,
+  `AccessCapabilities`). `getTrustLevel` / `TRUST_LEVEL_RANGES` survive (moved to
+  `trust-levels`; the old `access-levels` module is gone).
+- **`VerificationResult.accessLevel`** and `quickVerify().accessLevel`. Gate on
+  `identityVerified` + `policyAllowed` (+ `recommendation` / `stepUpApproval`).
+- **`GatewayConfig.defaultAccessLevel`**, `RouteAccessConfig.minAccessLevel`,
+  `commerceShield.guestAccessLevel`.
+- **`VerificationGatewayClient.hasAccess()` / `.getCapabilities()`** (the last
+  live band consumers).
+- **`AccessLevelIndicator`** UI component + props.
+- The `X-AstraSync-Access-Level` (Next.js) and `X-AstraSync-Permissions` (edge
+  ASAT) response headers.
+
+### Changed (breaking)
+
+- **MCP `toolGates` / `methodGates`** values are now `ToolGateConfig | 'observe'`
+  (`ToolGateConfig` drops `minAccessLevel`). A gate object is **enforced**; the
+  literal `'observe'` passes the tool through unenforced (still evaluated when
+  `evaluateAlwaysIfCredentialed`). Replaces the old band value / `'none'` sentinel
+  and the bare-string shorthand.
+- **`mcpRiskTier(parsed): AccessLevel`** → **`mcpDefaultEnforced(parsed): boolean`**.
+- **HTTP route gating.** `RouteAccessConfig` gains **`observe?: boolean`** to
+  replace the `minAccessLevel: 'none'` observe sentinel. A matched route with no
+  `observe` flag is enforced (server decision). Endpoint-level
+  `unverifiedAgentPolicy: audit` remains the endpoint-wide observe mechanism.
+
+### Migration
+
+- Delete any `accessLevel` / `minAccessLevel` / `defaultAccessLevel` reads — they
+  no longer exist. Gate on `identityVerified && policyAllowed`.
+- MCP: `toolGates: { t: 'standard' }` → `{ t: { purpose: '…', action: '…' } }`;
+  `toolGates: { t: 'none' }` → `{ t: 'observe' }`.
+- HTTP: a route previously `minAccessLevel: 'none'` → `observe: true`; any other
+  band value → drop it (tighten with `minTrustScore`).
+
+## [4.6.0] — 2026-08-02 — canonical two-limit model in the LocalEvaluator
+
+Aligns the offline `LocalEvaluator` spend-limit ladder with the backend
+`checkWithinLimits` so a local policy pre-check and the cloud verdict agree.
+
+### Changed (behaviour — review your local policies)
+
+- **Two-limit ladder with fallback.** `limits` now has exactly two spend
+  thresholds — `autonomousThreshold` (Autonomous Limit) and the existing
+  `maxTransactionAmount` (now the **Hard Limit**). Evaluation:
+  - `value <= Autonomous Limit` → `ALLOW`
+  - `Autonomous Limit < value < Hard Limit` → `MANUAL_REVIEW` (human approval)
+  - `value >= Hard Limit` → `DENY`
+    The Hard Limit **falls back to the Autonomous Limit** when only the Autonomous
+    Limit is declared, and both default to `0`.
+- **Hard-limit boundary is now inclusive (`>=`, was `>`).** A transaction
+  exactly at `maxTransactionAmount` is now denied, matching the backend.
+- **A Hard-limit-only policy now steps up sub-cap spend.** Previously a policy
+  with only `maxTransactionAmount` allowed everything below it; now (Autonomous
+  Limit defaulting to `0`) any positive spend below the Hard Limit returns
+  `MANUAL_REVIEW`. **If you want the old auto-allow band, declare an
+  `autonomousThreshold`.**
+
+### Added
+
+- Optional `limits.autonomousThreshold` on the local policy schema, validated as
+  a number and required to be `<= maxTransactionAmount`.
+- `retryable?: boolean` on the verification result — set `true` on a transient
+  `verify_access.api_error` (5xx / timeout / CSRF-403). Lets a consumer surface
+  an infra outage as error-and-retry instead of a policy denial. Not set on a
+  deterministic merchant misconfig (retrying won't help).
+
+### Removed
+
+- The enforcement-dead `stepUpThreshold` field is gone from the registration
+  `PDLSSLimits` type and the transport formatter (it never carried behaviour).
+
+## [4.3.0] — 2026-07-16 — CloudFront fingerprints, verified-hop everywhere, capture-matrix truth
+
+Partner-feedback round: maximal connection metadata on every adapter, the
+cross-hop dedupe marker made real outside MCP, and the capture story
+documented per who-operates-the-CDN. Additive connection keys throughout —
+`schemaVersion` remains 1 per the frozen-capture doctrine.
+
+### Added
+
+- **CloudFront fingerprint + geo sources in the SDK derivation**
+  (`deriveConnectionFromHeaders`): `cloudfront-viewer-ja3-fingerprint` →
+  `tlsFingerprint`, `cloudfront-viewer-ja4-fingerprint` → `ja4`, plus
+  `headerOrder`/`headerCount` (header-structure fingerprint), `timeZone`,
+  `metroCode`, `countryRegionName`, and `cloudfront-viewer-address` as an
+  ip fallback (port-stripped, IPv6-safe). Connection values are truncated
+  to the new exported `MAX_CONNECTION_VALUE_CHARS` (256 — the platform's
+  hard zod bound; headerOrder routinely exceeds it).
+- **Edge gateway emits `X-Astra-Verified-Hop` toward the origin** whenever
+  its verify-access call produced identity (authenticate/authorize depth) —
+  SDK-middleware origins behind the TAG no longer double-verify. Helpers
+  moved to a shared `verified-hop` module (transport re-exports unchanged).
+- **`trustVerifiedHop` + `verifiedHopMaxAgeMs` on express AND nextjs
+  middleware options** (previously documented on express but implemented
+  only on MCP): a fresh marker matching the presented X-Astra-Id skips the
+  duplicate verify-access. Default off; unsigned dedupe advisory — enable
+  only behind a stripping gateway/trusted boundary (README trust-model note).
+
+### Fixed / hardened
+
+- Evaluated edge passes now strip an inbound spoofed `X-Astra-Verified-Hop`
+  (previously only `x-astrasync-*` was stripped — a spoofed marker could
+  reach an origin that trusted it).
+- `x-astra-verified-hop` added to the metadata sanitiser's secret set: the
+  short-lived dedupe token never persists in stored metadata.
+- Canonical capture matrix rewritten (README): edge adapter / SDK behind
+  own CDN / SDK behind **platform-managed** CDN (IP only — Railway, Render,
+  Fly, Heroku don't forward provider geo/TLS headers to customer origins) /
+  SDK no CDN, with a fingerprint-availability column.
+
+## [4.2.1] — 2026-07-15 — dependency hygiene: @sd-jwt consolidation
+
+### Changed
+
+- Migrated `@sd-jwt/decode` + `@sd-jwt/utils` (both deprecated upstream —
+  merged into `@sd-jwt/core` ≥ 0.20.0; the decode deprecation notice cites
+  security reference GHSA-f9j6-8p6x-r9j6) to a single `@sd-jwt/core@^0.20.0`
+  dependency. Same two functions consumed (`decodeSdJwtSync`, `splitSdJwt`),
+  now imported from core; no behavior change (308 transport tests unchanged).
+
+## [4.2.0] — 2026-07-15 — Local Guard: native permissions.deny self-protection
+
+Closes the settings self-protection gap: Claude Code rejects schema-invalid
+edits of its own `settings.json` without invoking PreToolUse hooks, and the
+hook only blocks in active posture — so the hook alone cannot fully protect
+the settings file it is registered in. The installer now also writes Claude
+Code's native `permissions.deny` rules, which are evaluated before hooks,
+apply regardless of guard posture, and cannot be removed by a governed agent
+(the removal edit is itself denied — runtime-verified on Claude Code 2.1.210).
+
+### Added
+
+- `astrasync guard install-claude-code` now installs `permissions.deny`
+  self-protection rules (Edit rules for `.claude/settings.json`,
+  `.claude/settings.local.json`, and `.astrasync/**` in both `~/` and `**/`
+  anchored forms) alongside the PreToolUse hook; uninstall removes them.
+  Rules are Edit()-only — Claude Code's file permission checks match
+  `Edit(path)` rules against every file-editing tool and never match
+  `Write(path)` rules.
+- New exports from the Claude Code settings installer:
+  `installClaudePermissionRules`, `uninstallClaudePermissionRules`,
+  `GUARD_PERMISSION_DENY_RULES`, `LEGACY_GUARD_PERMISSION_DENY_RULES`.
+  Claude-Code-only — the Codex installer intentionally does not write a
+  `permissions` block (hooks.json has no permissions concept).
+- Rule ownership is exact-string match (deny entries carry no marker), so
+  uninstall also removes an identical rule the user added independently;
+  the CLI prints every removed rule so users can re-add their own.
+
+## [4.1.0] — 2026-07-15 — Trusted Agent Gateway naming, edge core, published-docs fix
+
+Naming split (an external product owns "Commerce Shield"): the edge product is
+now the **Trusted Agent Gateway (TAG)**, the dashboard analytics product is
+**Visit Intelligence**, and the unverified-agent overlay is the
+**verification interstitial**. No breaking changes — deprecated aliases keep
+every 4.0.0 import working.
+
+### Added
+
+- **`./edge-core` subpath**: the portable Trusted Agent Gateway pipeline
+  (request normalization contract, three-tier classification, protocol
+  detection, verify orchestration, observe/enforce outcome application) that
+  platform adapters compose — `@astrasyncai/adapter-lambda` (CloudFront) and
+  the new `@astrasyncai/adapter-edge` (Vercel Edge / Cloudflare Workers /
+  Fastly Compute) are thin request/response translators over it.
+- **MCP adapter metadata capture**: `createMcpMiddleware` now captures
+  header-level ObservedMetadata automatically on every verify, matching the
+  Express and Next.js adapters (it previously captured none).
+- `VerificationInterstitial` / `useVerificationInterstitial` /
+  `VerificationInterstitialProps` and the `showInterstitial` middleware
+  option — renamed from the Commerce Shield names, which remain as
+  `@deprecated` aliases until the next major.
+- `check:dts-leaks` publish gate: built declaration files are scanned for
+  internal references before publishing.
+- **CDN-header connection derivation** (`deriveConnectionFromHeaders` +
+  shared `buildSdkObservedMetadata`): the Express/Next.js/MCP adapters now
+  promote CDN-provided signals (Cloudflare, Fastly, Vercel, CloudFront —
+  client IP, geo, ASN, TLS/HTTP version, and Cloudflare JA3/JA4 TLS
+  fingerprints) into `ObservedMetadata.connection`. Merchants behind a CDN
+  get the connection layer without an edge worker; edge adapters' native
+  collectors remain authoritative where deployed.
+- **Dashboard-driven anonymous beacon** (Express + Next.js): pass-through
+  traffic (unmatched routes / `none` routes) from non-browser callers is now
+  beaconed fire-and-forget, sampled at the endpoint's dashboard EdgeConfig
+  rate (platform-fingerprinted agents unsampled; humans and static assets
+  never). Zero request-path latency; disable with `anonymousBeacon: false`.
+- **`ObservedMetadata.schemaVersion`** (`CAPTURE_SCHEMA_VERSION = 1`),
+  stamped by every emitter: capture semantics are frozen within a major and
+  the version travels with the payload, so mixed 4.x deployments cannot
+  drift silently.
+
+### Fixed
+
+- **MCP tool names no longer travel as PDLSS actions**: a bare-string
+  toolGate caused the raw MCP tool name to be sent as the PDLSS `action`,
+  guaranteeing a policy denial. `tools/call` with no configured or declared
+  action now evaluates purpose-only, and `createMcpMiddleware` warns at
+  construction time about bare-string gates (use the object form with
+  `purpose`/`action`).
+- **Stale `routes: [...]` example removed** from the Express adapter docs
+  (per-route policy moved to the dashboard in v2.9.7); passing `routes` in
+  middleware options now logs a one-time warning instead of being silently
+  ignored.
+
+### Changed
+
+- README overhauled: Trusted Agent Gateway section with the capture-split
+  matrix (edge = headers + connection layer; Express/Next.js = header-level
+  automatic; MCP = header-level from 4.1.0), and documentation for the
+  `./metadata-capture`, `./platform-signatures`, `./edge-config` exports.
+- Published doc comments rewritten to self-contained public language
+  (internal spec/workstream/audit references removed from all declaration
+  files).
+
+## [4.0.0] — 2026-07-13 — Merchant-misconfig honesty + verify timeout
+
+A rejected integration API key (revoked/expired/rotated) is now classified
+as **merchant misconfig**, not a transient `api_error`: inbound agents get
+an honest 503 instead of a misleading 401 blaming their own identity. Found
+live: a partner property silently 401'd every credentialed agent for six
+days on a rotated key.
+
+### Breaking
+
+- **Adapter deny contract for the dead-key class**: when the backend rejects
+  the integration's OWN API key, express/nextjs(API-route)/mcp adapters now
+  respond **503** with `error.code: 'MERCHANT_VERIFICATION_MISCONFIGURED'`
+  (mcp: JSON-RPC code `-32002`) instead of 401 `UNAUTHORIZED`. Integrations
+  matching on the old envelope must adapt. nextjs web pages keep the shield
+  flow.
+- **`verify()` outbound call now has a hard timeout** (default 10s,
+  `GatewayConfig.verifyTimeoutMs`). Previously a hanging backend hung the
+  merchant's middleware (and every inbound agent behind it) indefinitely;
+  timeouts now surface as the fail-closed `verify_access.api_error` result.
+
+### Added
+
+- **`VerificationResult.misconfigured`** typed marker + guidance source
+  `merchant_misconfig` + failure dimension
+  `verify_access.merchant_misconfigured` (guidance: "your identity and the
+  AstraSync platform are fine — contact the site operator; retrying will not
+  help"). Classified from the backend 401 (`code: api_key_*` when present —
+  a verify-access 401 can only ever mean the caller's own key).
+- **Init self-check**: with an `apiKey` configured, the one-time init probe
+  also calls `GET /agents/verify-access/self-check` — a dead key logs a loud
+  `console.error` at startup (throws under `strictInit`); a key expiring
+  within 7 days logs a rotation warning. 404 (older backend) is silent.
+
+## [3.12.0] — 2026-07-11 — Trust Record capture (§33.5 #3)
+
+Trust Record capture: attemptId chain correlation (request/response
+pass-through, excluded from the verdict cache key), considerationSet on
+verify, `reportAttempt()` for post-hoc consideration/outcome reporting. All
+fields optional; no behavioural change for existing callers.
+
+### Added
+
+- **`VerificationRequest.attemptId`** (`att_` + 32 lowercase hex): attempt-chain
+  handle correlating the catalog → intent → settlement funnel into one attempt.
+  Forwarded skip-when-undefined; the server mints one when absent and echoes it
+  top-level on every response branch. **`VerificationResult.attemptId`** carries
+  the echo (disjoint from `correlationId`/`sessionId` — an attempt CONTAINS
+  events). On a cache hit the SDK rewrites the cached result's attemptId to the
+  current request's own (or drops it) so a cached verdict never leaks a prior
+  attempt's id.
+- **`VerificationRequest.considerationSet`** (`ConsiderationSet` /
+  `ConsiderationItem` types): first-party observational data — the offers the
+  agent evaluated at this checkpoint. Items capped at 50 server-side; order
+  chosen-first so purchased counts survive truncation. Excluded from the
+  verdict cache key alongside attemptId (observedMetadata precedent).
+- **`reportAttempt(config, report)`** → `POST /agents/verify-access/attempt-report`:
+  post-hoc consideration/outcome reporting (`AttemptReport` / `AttemptOutcome`
+  types) for signals that never reached verify-access (cache-served catalogs,
+  transport-side denials, settled/blocked outcomes). Fire-and-forget — never
+  throws; same credentials as verify().
+
+## [3.10.0] — 2026-07-08 — Maximal metadata capture (Workstream D)
+
+Total metadata capture folded into the Commerce Shield console round: every
+header and connection signal an inbound agent presents is captured (secrets
+stripped, credential headers reduced to a safe format prefix), forwarded, and
+used for platform attribution — without adding verify-access decision latency.
+
+### Added
+
+- **`./metadata-capture` module** (subpath + flat root re-exports):
+  `sanitizeHeaders` (deny-lists genuine secrets — `Cookie`, `X-CSRF-Token`,
+  our own `x-astrasync-*`/`kya` credentials, raw signatures; reduces
+  `Authorization`/`X-Api-Key`/`X-Goog-Api-Key` to a NON-secret format prefix
+  like `sk-ant-api03`; keeps everything else verbatim) with size caps (≤64
+  headers, ≤1KB/value, ≤16KB total) that bound jsonb growth. Plus
+  `extractPlatformHeaders`, `extractApiKeyFormat`, and the `ObservedMetadata`
+  type. Pure/edge-safe (no Node built-ins).
+- **`CallerMetadata.observedMetadata`**: the express + nextjs adapters now
+  forward the full sanitised header map on every verify-access call (local
+  string work; kept OUT of the verify cache key so it doesn't defeat verdict
+  caching). SDK-only merchants (no edge) get the same capture.
+- **Detection widened**: `PlatformDetectionInput` gains `apiKeyFormat` +
+  `platformHeaders`; `PlatformSignatureDef` gains `apiKeyFormatPatterns` +
+  `headerPatterns`; the seed signatures map `sk-ant`→claude, `sk-proj`→chatgpt,
+  `aiza`/`x-goog-user-project`→gemini, `openai-organization`→chatgpt,
+  `pplx-`→perplexity. A credential format / platform header is a stronger,
+  less-spoofable signal than the User-Agent.
+
+### Notes
+
+Backward-compatible and additive: `observedMetadata` is optional everywhere and
+absent on pre-3.10.0 callers. `@astrasyncai/adapter-lambda` consumes the new
+surface to capture CloudFront-Viewer connection signals (IP/ASN/TLS/country).
+
+## [3.9.0] — 2026-07-08 — Edge verification config + shared platform signatures (Commerce Shield edge adapter)
+
+Foundation release for `@astrasyncai/adapter-lambda` (the Commerce Shield
+pathway-A edge shell, spec §7.4/§33.5 #1).
+
+### Added
+
+- **`EdgeConfig` + `edge-config` module** (`./edge-config` subpath and flat
+  root re-exports): the per-endpoint policy the edge adapter fetches from the
+  dashboard — `mode` (`observe`/`enforce`), `depth`
+  (`classify`/`authenticate`/`authorize`), ordered first-match-wins `pathRules`
+  (case-insensitive `*` globs, regex metachars escaped), anonymous-beacon
+  sampling, and a v1 `failurePosture` locked to `'open'`.
+  `fetchEdgeConfig()` (ETag/If-None-Match aware), `getEdgeConfig()` (60s TTL,
+  stale-while-revalidate, never throws; enforce degrades to observe when the
+  last successful fetch is older than 24h — a dead backend can never keep a
+  site enforcing), `matchEdgePathRule()`, `DEFAULT_EDGE_CONFIG`.
+- **`platform-signatures` module** (`./platform-signatures` subpath + root
+  re-exports): `PLATFORM_AGENT_SIGNATURES` + `detectPlatformFingerprint()`
+  lifted from the backend's platform-agent detector so backend and edge
+  classify identically (single source of truth).
+- **`./verify` subpath export** — `verify`, `extractCredentials`,
+  `reportUnregisteredAttempt`, `fetchRoutes` etc. importable without the root
+  barrel (whose `./registration` re-export drags `ethers`); this is the
+  ethers-free surface the edge adapter bundles. `reportUnregisteredAttempt`
+  and `fetchRoutes` also join the root barrel.
+
+### Fixed
+
+- **Version-constant drift**: `SDK_VERSION` (stamped on every verify call) was
+  left at `3.7.1` by the 3.8.0 release, and the root barrel's `VERSION` had
+  been frozen at `3.4.0`. Both now track the package version — `VERSION`
+  re-exports `SDK_VERSION` instead of carrying its own literal.
+
+## [3.8.0] — 2026-07-07 — Settlement voucher v2 (port to main)
+
+_(Backfilled — this release shipped without a changelog entry.)_
+
+### Changed
+
+- **`SettlementArtifact.binding` becomes the v2 union**
+  (`StablecoinSettlementBinding` — integer minor-units, asset-pinned — |
+  `FiatSettlementBinding`). README Settlement Artifacts section rewritten with
+  the voucher lifecycle and guarantee boundary (verify proves authenticity;
+  redeem proves the authorization is live and single-use — it does not check
+  or move funds).
+
+## [3.7.1] — 2026-07-05 — ChallengeHandler auto-include (sandbox port)
+
+### Changed
+
+- **`ChallengeHandler` auto-includes the incoming counterparty.** When no
+  counterparties have been pre-registered via `registerPending()`, a challenge
+  response now echoes back the challenge payload's own `counterpartyId`/
+  `counterpartyUrl` instead of an empty list — the correct default for agents
+  that never call `registerPending()`. Pre-registered whitelists behave exactly
+  as before. (Ported from the LMAX POC branch, where the empty default caused
+  spurious challenge failures for agents without explicit pending lists.)
+- Runtime-challenge docs page: auto-include default documented, plus a warning
+  for the double-appended challenge-path misconfiguration
+  (`…/astrasync/astrasync/challenge`), pre-registration examples, and a raw-HTTP
+  (no-SDK) example.
+
+## [3.7.0] — 2026-07-04 — AstraSync Local Guard for Claude Code
+
+### Added
+
+- **`@astrasyncai/adapter-claude-code`** (subpath export `./claude-code`) — Layer 4
+  Local Guard adapter for Anthropic's Claude Code CLI, intercepting tool calls via
+  Claude Code's native PreToolUse hook. Strictly tightening decision mapping:
+  DENY → hook `deny`, MANUAL_REVIEW → hook `ask` (Claude Code's own permission
+  prompt is the human-in-the-loop), ALLOW → no hook output (the guard never emits
+  `allow`, so it cannot bypass Claude Code's native permission system). MCP tools
+  map `mcp__{server}__{tool}` → purpose `{server}.{tool}`, gated by `governMcp`.
+- **`astrasync-claude-hook` binary** — stateless per-tool-call hook entry.
+  Policy resolution `$CLAUDE_PROJECT_DIR/.astrasync/policy.yaml` → payload cwd →
+  `~/.astrasync/policy.yaml`; `guard.json` (`posture`, `failOpen`, `skipTools`,
+  `governMcp`) beside the policy; JSONL traces beside the policy. Fail-closed on
+  malformed payloads / invalid policy with `ASTRASYNC_GUARD_FAIL_OPEN=1` and
+  `guard.json failOpen` opt-outs; `ASTRASYNC_GUARD_DISABLE=1` kill switch; missing
+  policy anywhere = silent no-op.
+- **`astrasync guard install-claude-code` / `uninstall-claude-code`** — user-scope
+  (`~/.claude/settings.json`, default) or `--project` install; merge-never-clobber
+  settings editing (idempotent, preserves foreign hooks); generates a default
+  coding-agent policy (permissive risk preset; recommended blocked commands and
+  credential paths; guard self-protection patterns on `file.write`) and a passive
+  `guard.json` for observe-then-enforce rollout. `astrasync guard status` reports
+  Claude Code hook state.
+
+### Fixed
+
+- **Guard CLI was never shipped** — `cli/guard.ts` (`astrasync guard setup/start/…`,
+  Phase A) was missing from tsup entries and the package `bin` map. It now ships as
+  the `astrasync-guard` binary, and the main `astrasync` bin delegates
+  `astrasync guard <cmd>`. Direct-bin argv parsing fixed so flags after the
+  subcommand are not misread as the command.
+
+## [3.6.0] — 2026-07-04 — step-up hold-and-poll + LMAX port alignment
+
+### Added
+
+- **Step-up hold-and-poll (opt-in)** — `stepUpMaxWaitMs` / `stepUpPollIntervalMs` on
+  `GatewayConfig`. When enabled, the express/mcp/nextjs middleware holds a
+  `step_up_required` request, polls the approval (`{success, data:{status}}` envelope,
+  flat fallback), and on `approved` re-verifies once cache-bypassed so the backend
+  redeems the single-use approval (server: approved → consumed). Non-approved outcomes
+  fall into the existing fail-closed deny with a new `stepUpOutcome` field
+  (`denied | expired | consumed | timeout`) and an `X-Astra-Step-Up` response header.
+  OFF by default — existing integrations keep the instant-403 contract. Next.js edge
+  runtimes: set a small `stepUpMaxWaitMs` (≤20s) or gate in a Node route handler.
+- **`verify(config, request, { bypassCache })`** — per-call cache-read bypass (Java
+  SDK parity); also threaded through `verifyAndRecord`.
+- **Exports**: `awaitStepUpApproval`, `pollStepUpStatus`, `StepUpApprovalStatus`,
+  `StepUpOutcome`, `VerifyOptions`.
+
+### Changed
+
+- **Step-up verdicts are never cached** (was: 300s TTL). A cached `step_up_required`
+  result kept denying retries the owner had already approved and carried a stale
+  pollUrl — the Java SDK 1.1.0 bug, now fixed here too. Not overridable via `cacheTtl`.
+  Autonomous grants keep the 60s default.
+- **`denialReasons` server precedence** — the backend now emits top-level
+  `denialReasons` on every deny path; the SDK prefers it verbatim and only falls back
+  to client-side reconstruction (failures / recommendationReasons) for older backends.
+- **`reportUnregisteredAttempt`** — sends the configured `counterpartyId` and omits a
+  null/undefined `counterpartyUrl` (backend attributes id-first and requires at least
+  one of the two).
+
+## [3.5.0] — 2026-06-30 — partner feedback round
+
+### Added
+
+- **`extractTransactionValue`** option on `ExpressMiddlewareOptions` — opt-in upfront value
+  extraction so PDLSS limit evaluation runs at middleware time. Must return major units
+  (dollars, not cents). `authorizeSettlement()` remains the required fail-closed settlement gate.
+
+### Changed
+
+- **Settlement architecture** — merchant-mediated grants now enforce voucher-primary: only
+  crypto wallets (`stablecoin_voucher`) mint settlement artifacts; fiat instruments log a
+  diagnostic and do not mint (fiat rails coming soon). Direct-charge adapters (Stripe
+  PaymentIntent, PayPal Order) are never called on merchant-mediated paths.
+- **Owner-wallet fallback** — when agent's `individualUuid` is null (company-owned agents),
+  settlement resolves wallets via the owner's individuals. Currency/asset hard filter prevents
+  cross-asset-class funding.
+- **x402 decimal conversion** — `extractX402TransactionValue` converts known tokens (USDC/6,
+  USDT/6, DAI/18, ETH/18, WETH/18) from atomic units to major units. Unknown tokens return
+  `rawUnits: true` which the limit engine rejects fail-closed.
+- **Currency-formatted denial messages** — hard-limit and step-up messages now show formatted
+  amounts (`$1,800.00 USD` instead of `1800`).
+- **Purpose dotted-token hint** — when a dotted action is sent as purpose (e.g.
+  `shopping.purchase`), the denial message explains the canonical two-axis contract.
+- **Limits cross-validation** — `approvalThreshold` must be >= `autonomousThreshold` at
+  registration. Equal values are valid (no HITL band).
+
+### Fixed
+
+- `SDK_VERSION` constant (was `3.3.0`, now `3.5.0`) — fixes drift from `package.json`.
+
+### Docs
+
+- Agent docs: field names corrected (`autonomousLimit` → `autonomousThreshold`, etc.),
+  units/currency callout, settlement statement, registration guidance, purpose/action contract.
+- Fiat instrument UI (onboarding, profiles): replaced with "Fiat (coming soon)" label.
+
+## [3.3.0] — 2026-06-16 — direct-path value enforcement (`authorizeSettlement`)
+
+### Added
+
+- **`authorizeSettlement(config, { agentId, value, currency, purpose?, action? })`** — the
+  value-aware, FAIL-CLOSED gate a direct merchant MUST call before settling a priced cart.
+  The request middleware verifies identity + access but never sends the transaction VALUE to
+  verify-access, so a compliant merchant could settle past the agent's PDLSS spend limits.
+  `authorizeSettlement` wraps `verify()` with the **merchant's authoritative priced total**
+  (never an agent-supplied/spoofable amount) and returns `SettlementDecision { authorized, ... }`.
+  `authorized` is true ONLY on a clean grant — a step-up/approval-band value, a value at/above the
+  Hard Limit, a missing value, or a verify-access error all return `authorized: false`. Settle only
+  when `authorized === true`. See `/docs/merchants#direct-path-settlement`.
+
+> The request middleware's `requiresHumanApproval` fail-closed (3.2.1) only fires when verify-access
+> returns a step-up — which never happens without a value. Direct merchants MUST adopt
+> `authorizeSettlement`. A value-required-route tripwire (deny on missing value) follows as a
+> hard gate before broad direct-path GA.
+
+## [3.2.1] — 2026-06-15 — direct-path step-up fail-closed; F5 guidance
+
+### Fixed
+
+- **Direct-path step-up fail-closed (F2).** The express / nextjs / mcp adapters
+  gated on `identityVerified && policyAllowed` alone. A spending step-up is
+  "allowed-but-escalate" (`policyAllowed: true` + `requiresApproval` /
+  `requiresStepUp`), so the adapter would ADMIT a `[autonomous, hard)`-band
+  purchase the bridge blocks — letting a direct merchant settle it via its own
+  processor. The adapters now also deny when the outcome requires human approval
+  (the approval mechanism is not yet wired), surfacing the
+  `commerce.intent.approval_required` dimension. New shared `approval-gate.ts`;
+  nextjs `/api/*` denials now include `failures[]`.
+- **Action-mismatch denial guidance (F5).** On the direct path the PDLSS action
+  can resolve to the raw tool name; the guidance now points at configuring a
+  `toolGates` tool→semantic-action mapping instead of telling operators to
+  enumerate transport tool names in the agent's (immutable) PDLSS — which would
+  pollute the semantic vocabulary (the retired-`mcp_invoke` class).
+
+> Sequencing: direct merchants should adopt **3.2.1 before the backend
+> promotes**, or a 3.2.0 adapter still admits the step-up — a real-money bypass
+> window. See the platform spec's promotion gate.
+
+## [3.2.0] — 2026-06-12 — access-level band no longer gates; step-up label-truth
+
+Post-3.1.0 prod-feedback release. Non-breaking minor: the `AccessLevel` band,
+`RouteAccessConfig.minAccessLevel`, and `hasMinimumAccess` are **retained as
+informational/deprecated** — but the band **no longer gates** in any adapter.
+
+### Changed — the access-level band is informational, not a gate
+
+- **express / nextjs / mcp adapters:** removed the
+  `hasMinimumAccess(result.accessLevel, route/tool minAccessLevel)` veto from
+  the deny path. Gating is now purely the server-side decision
+  (`identityVerified && policyAllowed`, which already encodes the endpoint
+  trust-floor + PDLSS). The band mapped a trust score into an opaque tier and
+  the per-route comparison duplicated the endpoint policy — and it manufactured
+  the "read-only can't elevate to write" settlement wall. Per-route tightening
+  now uses `route.minTrustScore` (express); explicit per-route/tool
+  condition→constraint rules are the Phase-2 successor.
+- **MCP toolGate/methodGate:** these still decide _whether_ a tool is gated
+  (any non-`none` tier → verify-access enforced) but **no longer differentiate
+  tiers** — a tool gated above an agent's band is no longer denied on the band.
+- **`verify.ts` step-up label-truth:** a `step_up_required` recommendation no
+  longer overwrites `accessLevel` to `'read-only'`. That masquerade made a
+  step-up signal look like a low-trust band cap (it caused a downstream
+  misdiagnosis). The real band is preserved; `requiresStepUp` carries the
+  signal.
+- **Trust score redaction (#2):** agent-visible denial messages are now
+  qualitative — the numeric trust score and the threshold are never embedded
+  in a message returned toward the agent.
+- **`AstraSyncSDK.hasAccess()`** marked `@deprecated` — explicit opt-in band
+  queries still work, but prefer the server-side policy decision /
+  `minTrustScore`.
+- **MCP adapter — clear "purpose required" error.** A gated MCP tool call with
+  no resolvable PDLSS purpose (none on the toolGate, no `X-Astra-Purpose`
+  header, none in the body) now fails fast with a `400 PDLSS_PURPOSE_REQUIRED`
+  (dimension `pdlss.purpose`) instead of forwarding an empty purpose to
+  verify-access and surfacing an opaque `verify_access.api_error`. Post-3.2.0,
+  prefer the object toolGate form (`{ purpose, action }`) over the deprecated
+  band string — the band no longer gates and carries no vocabulary.
+
+### Fixed — cross-merchant verification cache leak (security)
+
+- **`verify()` result cache now keys on the merchant `counterpartyId`.** The
+  cache key (`getCacheKey`) was built from the request only; the merchant
+  identity travels via `config.counterpartyId`, so it was absent from the key.
+  Two verifies for the SAME agent/purpose/action/value but DIFFERENT merchants
+  collided — a grant cached at a permissive merchant (low/no trust floor) was
+  served for a stricter merchant, bypassing its trust floor / per-route policy
+  in any long-running consumer (the bridge). Same bug class as the earlier
+  duration-omission fix (F-A1-07). `counterpartyId` now keys the cache.
+  Surfaced by a cross-merchant live probe (a floor-0 grant leaking to a
+  floor-50 merchant). Pre-existing; amplified by the 3.2.0 verify-before-act
+  ordering (which adds a per-merchant `shopping.search` verify).
+
+### Migration
+
+No code change required to upgrade. If you relied on `route.minAccessLevel`
+to tighten a route, switch to `route.minTrustScore` (a number). Merchants on
+3.1.0 keep their band wall until they upgrade — upgrading removes it.
+
+## [3.1.0] — 2026-06-11 — canonical PDLSS vocabulary (Bug 14)
+
+The vocabulary-unification release. Partner prod testing proved **no agent
+registration shape could transact at an SDK-gated merchant**: the express/
+nextjs middleware sent `purpose: 'read_data'` (method inference) and
+`action: 'GET'` (the raw transport verb, with no override surface), while the
+platform evaluator and docs contract is two-axis — `purpose` = bare category
+noun (`shopping`), `action` = dotted verb (`shopping.search`). 3.1.0 pins
+every sender to that contract.
+
+Retroactive context: 3.0.0's identity-forwarded catalog fetch (#437 B3/B5)
+moved merchant-side gating onto the bridge checkout critical path — the change
+that exposed this misalignment and motivates this release.
+
+### Changed — middleware emits canonical vocabulary
+
+- Express/Next.js adapters now resolve a canonical `{purpose, action}` pair.
+  The **pinned method→action table** replaces both gen-1 inferences:
+  GET/HEAD/OPTIONS → `data.read`; POST/PUT/PATCH → `data.write`; DELETE →
+  `data.delete`; unknown → `data.write`. The transport verb is **never** sent
+  as the PDLSS action, and `read_data`/`write_data`/`delete_data`/`general`
+  are no longer emitted as purposes (unmapped fallback purpose is `data`).
+- A dotted `X-Astra-Purpose` (e.g. `shopping.purchase` — the shape older docs
+  taught) is now normalized: category prefix → `purpose`, whole token →
+  `action` candidate. The colon form (`category:action`) keeps its
+  take-the-prefix behavior; the free-text remainder is still discarded.
+
+### Added — config surfaces (both axes, finally symmetric)
+
+- **Dashboard route send-mapping (the direct-path mechanism):**
+  `RouteAccessConfig` gains optional `purpose` / `action` — the tokens the
+  middleware STAMPS on verify-access calls for a matched route, fetched from
+  `GET /endpoints/:id/routes` like the rest of route policy. Authoritative
+  over agent headers (as MCP toolGates are). Domain merchants (e.g. a trading
+  exchange mapping `/api/orders` → `trading`/`trading.execute`) configure this
+  in the dashboard routes editor — an unmapped route falls to the generic
+  `data`/`data.*` pair, which DENIES domain agents by design.
+- `X-Astra-Action` header: extracted by express/nextjs (parity with the MCP
+  adapter) and emitted by `setHttpHeaders` alongside the back-compat colon
+  form. `extractAction` middleware option added, symmetric with
+  `extractPurpose`. `ToolGateConfig.action` override added for MCP.
+- Resolution telemetry: express/nextjs emit `purpose_source`/`action_source`
+  debug lines (same shape as MCP) when `debug: true`.
+
+### Breaking-by-policy (platform, not this package's code)
+
+- **Gen-1 tokens are RETIRED, not aliased**: platform registration now
+  rejects `read_data`/`write_data`/`execute_action`/`delete_data`/`general`
+  with a pointed 400. Existing agents carrying them must retire +
+  re-register (pre-launch posture: no production cohort to migrate).
+- Registration is now **action-primary**: `allowedActions` required (min 1 —
+  the evaluator is fail-closed on actions), `categories` derived from
+  dotted-action prefixes (explicit entries validated as a bare-noun
+  superset). Dashboard `allowedPurposes` lists must hold bare nouns.
+
+### Migration table
+
+| You were sending/storing                | Send/store instead                                              |
+| --------------------------------------- | --------------------------------------------------------------- |
+| `purpose: 'read_data'`, `action: 'GET'` | `purpose: 'data'`, `action: 'data.read'` (automatic on upgrade) |
+| `purpose: 'shopping.purchase'`          | `purpose: 'shopping'`, `action: 'shopping.purchase'`            |
+| `categories: ['read_data', ...]`        | `allowedActions: ['data.read', ...]` (categories derived)       |
+| `allowedActions: ['GET', 'POST']`       | `allowedActions: ['data.read', 'data.write']` or domain verbs   |
+| route `allowedPurposes: ['read_data']`  | `allowedPurposes: ['data']` (bare nouns)                        |
+
+### Deprecated (removal in 4.0.0)
+
+- `x-purpose` header and `?purpose` query param (express) — still resolved,
+  scheduled for removal.
+- Colon-form `X-Astra-Purpose` (`category:action`) as an action channel — use
+  the dedicated `X-Astra-Action` header.
+
+## [3.0.0] — 2026-06-09 — migration guide (2.5 → 3.0)
+
+Major bump consolidating the consumer-facing breaking changes accumulated across
+the PR #430 re-test, #437, and this follow-up. **No action is required to keep
+running 2.5.1** — these only matter when you upgrade or when you read responses
+from the hosted bridge. Read each item below.
+
+### Breaking (SDK) — `buildGuidance` envelope: `registrationUrl` is now an action endpoint
+
+The no-creds guidance `registrationUrl` was the human dashboard page
+(`/agents/register`), which an agent cannot use. It is now the **keyless action
+endpoint** an agent can POST to. The companion `documentationUrl` (the
+machine-readable contract) is unchanged.
+
+```
+Before (2.5.x): { registrationUrl: ".../agents/register",
+                  documentationUrl: ".../docs/agent-access", steps: [...] }
+After  (3.0.0): { registrationUrl: ".../api/agents/request-registration",
+                  documentationUrl: ".../docs/agent-access", steps: [...] }
+```
+
+Migration:
+
+- **POSTed to `registrationUrl` to register?** Keep doing that — it now points at
+  the correct keyless action endpoint instead of an auth-walled HTML page.
+- **Displayed `registrationUrl` to a user as "where to learn"?** Switch to
+  `documentationUrl`.
+- `/agents/register` is no longer surfaced by the SDK — it's a human-auth route.
+
+### Breaking (hosted bridge, `mcp.astrasync.ai`) — affects callers, not this package's code
+
+- **`lookup_agent` and `list_agents` removed** (tool count 11 → 9). The backend
+  `GET /agents` and `GET /agents/:id` reject API-key auth (correct security — no
+  cross-account or sibling-agent enumeration), so over the bridge's x-api-key
+  credential these tools could only ever return a 403 deny envelope. Look up your
+  own agent's public metadata via the dashboard or your known ASTRA-id.
+- **`verify_agent` now requires/defaults a `purpose`.** Pass a PDLSS purpose token
+  (e.g. `shopping.purchase`); it defaults to `identity.verify`. (Previously the
+  bridge omitted it and the backend rejected the call with 400.)
+- **Upstream failures are classified by status.** A reachable-but-rejecting
+  platform now returns `upstream.validation_failed` (400/422),
+  `upstream.auth_failed` (401), `upstream.access_denied` (403), or
+  `upstream.unexpected_status` (other 4xx). `system.platform_unreachable` is now
+  reserved for genuine reachability failures (5xx/network) — agents that retried
+  on `platform_unreachable` should branch on the new dimensions (fix-input vs
+  re-auth vs escalate).
+- **`request_registration` rejects secret-shaped fields** (`apiKey`/`privateKey`/
+  `secret`/`token`/…) with a `-32602` validation error instead of silently
+  stripping them.
+- **Per-email registration rate-limit** returns a structured `429`
+  (`rate_limited` + `retryAfter`) instead of a `202` with a missing `requestId`.
+- **KYD is enforced at agent approval, per registration path.** API-key
+  registrations on a no-KYD account now create a pending request (approved in the
+  dashboard once KYD is complete) rather than failing at registration; an
+  unapprovable backlog older than 24h returns `owner_kyd_required`.
+
+## [2.5.0] — 2026-06-03
+
+### Breaking — REST + MCP purpose default
+
+The SDK no longer injects `'general'` as a default purpose when verify-access
+requests arrive without an explicit purpose. Undefined purpose now propagates
+to the backend evaluator, which applies skip-when-undefined per the round-18.6
+architectural posture.
+
+Merchants with `allowedPurposes: ['general']` in endpoint policy: the entry
+continues to match callers that explicitly send `'general'`, but no longer
+matches callers who send nothing. If you relied on the auto-stamp as a
+catch-all, declare your intent explicitly or rely on skip-when-undefined.
+
+### Breaking — MCP `mcp_invoke` purpose and `mcp:tool/` resource prefix removed
+
+The MCP middleware no longer stamps transport-coupled defaults on the purpose
+and resource axes. `mcp_invoke` is removed; `mcp:tool/<name>` is replaced by
+the HTTP request path (e.g. `/mcp`).
+
+Use the new `toolGates` object shape to declare per-tool purpose and resource:
+
+```typescript
+toolGates: {
+  list_products: { minAccessLevel: 'none', purpose: 'shopping.search', resource: '/api/catalog' },
+  start_checkout: { minAccessLevel: 'standard', purpose: 'shopping.purchase', resource: '/api/checkout/*' },
+  browse_catalog: 'read-only',  // shorthand still works
+}
+```
+
+See `docs/migration/2.5.0.md` for full before/after behaviour.
+
+### Added — `ToolGateConfig` type for per-tool PDLSS mapping
+
+`toolGates` now accepts both the existing `AccessLevel` shorthand and a new
+`ToolGateConfig` object with optional `purpose` and `resource` fields. When
+`purpose` is set on a tool gate, it is authoritative — the agent's
+`X-Astra-Purpose` header is ignored for that tool.
+
+### Added — `/.well-known/agentic-commerce` URL discovery
+
+The SDK now fetches canonical platform URLs from `/.well-known/agentic-commerce`
+at initialization (fire-and-forget pre-fetch, lazy await on first verify call).
+All guidance URLs in denial responses come from this endpoint instead of the
+previous `apiBaseUrl.replace('/api', '')` string manipulation.
+
+Cache TTL is 60 minutes with stale-while-revalidate background refresh.
+
+### Added — Non-tools/call methods default to `discovery_default` access level
+
+`resolveMinAccessLevel()` now has an explicit branch for non-tools/call MCP
+methods (`initialize`, `tools/list`, etc.) returning `'none'` with source
+`'discovery_default'`. Use `methodGates` to override.
+
+### Fixed — `result.guidance` populated on all adapter deny paths
+
+Adapter-level deny paths (insufficient access level, insufficient trust score,
+middleware internal error) now backfill `result.guidance` with well-known URLs
+when the verify-access response didn't include guidance (e.g. success-path
+results that fail the local access-level gate).
+
+### Fixed — `denialReasons` deduplication
+
+`dedupeFailures()` now deduplicates the legacy `denialReasons` string array
+alongside the structured `failures` array.
+
+## [2.4.0] — 2026-05-11
+
+### Added — Agent registration absorbed into the gateway package
+
+The previously separate agent-side SDK is now part of `@astrasyncai/verification-gateway`. One package, one version, one set of release notes. DevOps brief: stop maintaining two npm releases for what is effectively one platform SDK.
+
+- **New `/registration` subpath** — `import { AstraSync } from '@astrasyncai/verification-gateway/registration'` exposes the registration client (`register()`, `verify()`, `health()`), config (`AstraSyncConfig`, `RegisterOptions`), error classes (`AstraSyncError`, `KYDRequiredError`, `AuthenticationError`), and the PDLSS declaration types. Class API and shapes are unchanged from the absorbed package — the only change for migrating callers is the import path.
+- **New `astrasync` CLI binary** — `npx astrasync register --name foo --pdlss ...`, `npx astrasync verify <id>`, `npx astrasync health`. Ships from this package's new `bin` field; no separate install.
+- **`ethers ^6.13.0` added as a direct dependency.** Powers secp256k1 request signing inside `/registration`. The lazy `await import('ethers')` in the signer is preserved; making ethers a hard dep makes it visible to `npm audit`, dependabot, and SBOM tooling rather than failing at runtime with a missing-module error.
+- **Subpath-by-role map** lives in `README.md` and `docs/research/adapter-architecture-technical-requirements.md` Appendix C round-8 entry. The round-3/round-7 two-package mnemonic ("verification-gateway = answers, agent-registration = asks") is retired.
+
+### Added — `PDLSSConfig` type co-exists across subpaths by design
+
+`/registration` exports a `PDLSSConfig` for the boundary declaration submitted at register time; `/agent` exports a different-shaped `PDLSSConfig` for the per-request runtime credential injection. Same name, different concept. The root export does not re-export either to keep the umbrella surface unambiguous. Disambiguate via subpath in imports.
+
+### Rolled in from round-7 partner feedback (was PR #384 scope)
+
+All 20 non-rename items from the 6 May onboarding test ship with this release. The package rename to `@astrasyncai/agent-registration` is superseded by the merge — that name was never published to npm.
+
+- **Backend: typed errors replace opaque 500s.**
+  - `POST /api/agents/register` is now `.strict()` on top-level fields: unknown keys return `400 unsupported_field` with the offending key list (B2). `metadata{}` stays passthrough.
+  - `PUT /api/agents/{id}` detects mutation attempts on `pdlss`, `model`, `framework`, `agentType`, `apiEndpoint` and returns `409 pdlss_immutable` with `immutableFields[]` (B6). `apiEndpoint` removed from `updateAgentSchema`.
+  - `GET /api/agents/{id}/chain-of-custody` resolves ASTRA-id ↔ UUID before querying (root cause of the 500: routes were passing ASTRA-id strings into UUID columns), checks ownership, returns `404`/`403`/typed envelopes (B7). New `agentsService.resolveAgentId()` helper covers both routes.
+- **Backend: new endpoints + first-class fields.**
+  - `GET /api/agents/request-registration/{requestId}` polling endpoint (Doc5). Persistence reuses `platform_events.eventData` JSONB — no schema migration.
+  - `protocols[]` promoted from `metadata.protocols[]` to a first-class field on `CreateAgentRequest` (Doc4). Backend mirrors top-level → `metadata.protocols` for back-compat.
+- **Hostname fix.** SDK default `baseUrl` changed from `https://api.kya.astrasync.ai` (NXDOMAIN since the rebrand) → `https://astrasync.ai`. Backend `kydUrl` in 403 responses changed from `https://app.kya.astrasync.ai/developer-profile` → `https://astrasync.ai/developer-profile`. Mechanical sweep across docs, KB articles, frontend doc routes, and the mcp-server agent resources.
+- **B5 audit confirmed there is NO register-time runtime challenge** — the tester's failure was at first verify-access, not at register. Documented explicitly in `/docs/agent-access`.
+- **Email template branching (B3).** `agent-outreach` template branches on `recipientHasAccount` — existing accounts get "Sign In to Accept" (links to `/dashboard/agents/pending`); new users get "Create Your Account" (links to `/auth/register`). Subject line, headline, body intro, and CTA all branch.
+- **Dashboard parity with the registration SDK (Doc8).** Agent-creation form at `/dashboard/agents/register` now exposes `model{}` and `framework{}` field groups in step 2, matching `RegisterOptions` from `/registration`. Dashboard-registered agents now hit the same trust-score baseline as SDK-registered ones.
+- **Trust score tooltip (D4).** `registration-success-dialog.tsx` adds a tooltip clarifying the score is recomputed at runtime on every request, improves with metadata completeness, and is intentionally opaque (anti-gaming).
+- **Customer-facing docs.** Six items (D1–D6) added across `/docs/pdlss` and the new `/docs/agent-access` section: anti-drift rationale, PDLSS immutability up-front, trust-score dynamics, self-instantiation clarification, step-up rules table, runtime-challenge timing callout. Plus Doc1 worked register-call example and Doc2 cross-links.
+
+### Captured follow-ups (deferred to a separate feature-PR)
+
+- B1 + B4 (paired): async owner-approval flow on API-key registrations + pending-approval inbox/banner. Needs a persistent approval-request table, magic-link handler, and dashboard inbox.
+- MFA implementation for API-key step-up.
+- `app.kya.astrasync.ai` references in env configs / Stripe webhooks / other places the in-repo grep doesn't catch.
+- Round-6 leftovers: `ENTERPRISE_ADMIN_EMAIL` env on staging, local-override row icon colour, `GET /api/version` endpoint.
+
+### Post-merge actions (manual, not done by this PR)
+
+- Push tag `@astrasyncai/verification-gateway@2.4.0` from `main` at the merge commit → existing `publish-gateway.yml` workflow validates and publishes via Trusted Publishing OIDC.
+- `npm deprecate "@astrasyncai/sdk@>=0.0.0" "Renamed to @astrasyncai/verification-gateway. See https://www.npmjs.com/package/@astrasyncai/verification-gateway"` — the legacy package on npm from before round-7.
+- `@astrasyncai/agent-registration` does NOT need deprecation; it was never published.
+
+## [2.2.3] — 2026-05-05
+
+### Changed — Server is the single source of truth for access decisions
+
+This is the branch-validation release for the partner-feedback fixes. The same code ships as `2.3.0` on tag-publish once the verification matrix passes against UAT.
+
+- **`apiBaseUrl` default corrected** (`src/verify.ts`) — was `https://api.astrasync.ai` which matched neither prod nor staging OpenAPI servers. Now `https://astrasync.ai/api`. Always include the `/api` path prefix when overriding; SDK derives registration / docs URLs by stripping it.
+- **Init self-test on first `verify()` call** — fires a HEAD probe to `${apiBaseUrl}/agents/verify-access` and warns once if the response content-type is `text/html` (the marketing-404 trap). Behind `disableInitChecks?: boolean` for tests.
+- **`access.accessLevel` read verbatim from server** (`src/verify.ts:418-425`) — the local `determineAccessLevel(...)` call is removed. The server's PDLSS engine resolves the level from endpoint policy + agent's live trust score using canonical thresholds; the SDK no longer diverges. Closes partner feedback #20.
+- **`minTrustScore` / `minTrustScoreForFull` config fields deprecated** (`src/types.ts`) — setting them no longer affects access decisions. A one-shot `console.warn` fires if either is set on a `verify()` call. To gate access, configure `trust_score_requirement` server-side via the endpoint registration.
+
+### Added — Anonymous traffic + canonical-flow contract
+
+- **Anonymous `verify()` calls forward to the server** — the SDK no longer short-circuits when credentials are missing. The server applies the endpoint's `unverifiedAgentPolicy` (deny / allow_partial / allow_full) and returns `{access, advisory, recommendation}`. Closes partner feedback #1 and #1b.
+- **`counterpartyId` config field** — your ASTRAE-id, issued at endpoint registration. Forwarded on every `verify-access` call so the server attributes traffic directly by endpoint rather than URL resolution. Closes partner feedback #3.
+- **Header aliases on `extractCredentials`** (`src/verify.ts:99`) — accepts `X-Astra-Id`, `X-Astra-AgentId`, `x-astra-agent-id`, plus their casing permutations. Closes partner feedback #9a.
+- **`AccessLevel` docstring rewritten** — references the canonical-flow §21 in the platform spec and lays out semantics for both anonymous (Branch A/B/C) and verified (Branch D) callers.
+
+### Added — Webhook signature contract
+
+- **`@astrasyncai/verification-gateway/webhooks`** (`src/webhooks.ts`) — new module with `verifyAstraSyncWebhook(rawBody, headers, secret, options?)` and `signAstraSyncWebhook(rawBody, secret, nowMs?)`. HMAC-SHA256 over `${unix_timestamp}.${rawBody}`, header format `X-AstraSync-Signature: t=<unix>,v1=<hex>`. Constant-time comparison; 5-minute replay window (configurable via `toleranceSeconds`).
+- 7/7 unit tests cover round-trip, wrong secret, tampered body, replay window, missing/malformed header, and header-case variants.
+- Closes partner feedback #4 (signature contract). Outbound webhook delivery system from AstraSync to merchant URLs is a separate engineering effort tracked in the platform spec §22 / §23.
+
+### Fixed — Response field-name alignment
+
+- **`agent.id` → `agent.astraId`, `agent.status` → `agent.agentStatus`, added `agent.blockchainStatus`** — read verbatim from the API response. The SDK type definitions and the OpenAPI schema both already declared the new names; the backend response is now in line. Closes partner feedback #21.
+
+### Notes
+
+- This release is paired with backend v2.9. The dual-perspective activity feed, orphan-identity tracking, Enterprise admin org pattern, and always-emit invariant on verification events all ship server-side; this SDK release is the corresponding client-side contract correction.
+- Activity-dashboard polish (per-row Step-up display, summary↔detail count consistency) is a NOT BUILT row in the platform spec — cosmetic only; does not affect the SDK contract.
+
+## [2.2.0] — 2026-05-03
+
+### Added — Ownership-bound agent client + caller metadata
+
+- **`AgentClient.create()` async factory** (`src/agent/client.ts`) — validates
+  the configured API key's account owns the supplied ASTRA-id by calling
+  `GET /api/agents/:astraId/ownership` before returning a usable client. A
+  stolen ASTRA-id paired with a different valid API key now fails closed at
+  initialisation. Bypass in test environments with
+  `ASTRASYNC_SKIP_OWNERSHIP_CHECK=true`.
+- **`OwnershipMismatchError`** (`src/agent/errors.ts`, exported from
+  `src/agent/index.ts`) — typed error surfaced when ownership binding fails
+  or no API key is configured. Extends a new base `AstraSyncSdkError` with a
+  stable `code` field for downstream handling.
+- **`callerMetadata` on `verify()` requests** (`src/verify.ts`) — structured
+  bag for `sourceIp`, `userAgent`, `referer`, `host`, `forwardedFor`, and
+  `agentCardUrl`. Express + Next.js adapters now populate it from request
+  headers (X-Forwarded-For first-hop resolution, `x-astrasync-agent-card`).
+  Legacy top-level `clientIp` / `userAgent` fields continue to work.
+
+### Changed
+
+- Express + Next.js adapters forward the original client IP (first entry of
+  `X-Forwarded-For`, falling back to `req.ip`) instead of the immediate
+  proxy hop.
+- Internal formatting pass (Prettier) across adapters and `verify.ts` — no
+  behavioural changes.
+
+### Tests
+
+- New `src/agent/__tests__/ownership.test.ts` covering the ownership-binding
+  factory: success, `owned=false`, non-2xx, missing API key, and the
+  `ASTRASYNC_SKIP_OWNERSHIP_CHECK` bypass.
+
+## [2.1.0] — 2026-04-18
+
+### Added — Commerce Transport Verification Engine (spec v2.7)
+
+Runtime verification layer covering all 10 registered commerce/agent protocols.
+Library-first design; no hand-rolled cryptography.
+
+**New `src/transport/` modules (21 source files):**
+
+- **Extractors** — `vi.ts` (VI SD-JWT via `@sd-jwt/decode`), `ap2.ts` (AP2 mandate
+  triple), `ucp.ts` (checkout session + AJV manifest), `acp.ts` (multi-header parse
+  - payment-token prefix detection), `rfc9421.ts` (`structured-headers`), `mpp.ts`
+    (Challenge/Credential/Receipt via `mppx`), `x402.ts` (v1 + v2 via `@x402/core`).
+- **Verifiers** — `vi-verify.ts` (3-layer SD-JWT chain + RFC 7638 JWK thumbprint
+  bindings + VI constraint type 8 hash binding), `ap2-verify.ts` (mandate chain
+  cross-ref + totals monotonicity), `acp-verify.ts` (detached JSON sig, Ed25519 +
+  ES256 candidates, Timestamp freshness), `rfc9421-verify.ts` (wraps
+  `http-message-signatures` + `RegistryResolver`), `mpp-verify.ts`
+  (expiry + BodyDigest + source extraction), `stripe-webhook.ts` (inline
+  HMAC-SHA256 via `node:crypto`).
+- **Registry resolvers** — `registry/visa.ts` (JWKS at `mcp.visa.com/.well-known/
+jwks` via `jose.createRemoteJWKSet`), `registry/mastercard.ts` (partnership-gated
+  stub), `registry/web-bot-auth.ts` (IETF `draft-meunier-web-bot-auth-architecture-05`
+  directory fetch, Ed25519).
+- **Orchestration** — `commerce-pipeline.ts` (extract→verify→identity-bind→
+  constraint-eval→CommerceContext with hard-deny/trust-signal policy +
+  per-phase timings), `identity-binding.ts` (cross-protocol agent identity
+  mapping), `constraint-eval.ts` (VI types 1/2/3/4 + MPP/x402 payment-method
+  allowlist + spending-limit), `extractor-registry.ts`
+  (`registerTransportExtractor()` SDK hook for Lambda adapters),
+  `purpose-mapping.ts` (20 commerce purpose mappings), `transaction-value.ts`
+  (per-protocol amount normalization).
+
+**New peer-dep-compatible runtime dependencies:**
+
+- `@sd-jwt/core` ^0.19.0 + `@sd-jwt/decode` + `@sd-jwt/utils` (Apache-2.0)
+- `http-message-signatures` ^1.0.5 (ISC)
+- `mppx` 0.5.13 pinned (MIT, pre-1.0 API churn expected — wrapped in adapter)
+- `@x402/core` ^2.10.0 (Apache-2.0)
+- `web-bot-auth` ^0.1.3 (Apache-2.0)
+- `jose` ^5.9.6 (MIT)
+- `ajv` ^8.17.1 (MIT)
+- `structured-headers` ^2.0.1 (MIT)
+
+**Exports added** — import from `@astrasyncai/verification-gateway`:
+
+```ts
+import {
+  transport, // namespace containing all new modules
+} from '@astrasyncai/verification-gateway';
+
+// Or from the transport subpath:
+import {
+  // Extractors
+  extractVIClaims,
+  extractAP2Mandates,
+  extractUCPContext,
+  extractACPContext,
+  parseRFC9421,
+  extractMPPContext,
+  extractX402Context,
+  // Verifiers
+  verifyVIChain,
+  verifyAP2Chain,
+  verifyACPSignature,
+  verifyRFC9421,
+  verifyMPP,
+  verifyStripeWebhook,
+  // Registry resolvers
+  createVisaRegistry,
+  createMastercardRegistry,
+  createWebBotAuthRegistry,
+  // Orchestration
+  runCommercePipeline,
+  evaluateVIConstraints,
+  evaluatePaymentMethodAllowlist,
+  evaluateSpendingLimit,
+  bindIdentity,
+  registerTransportExtractor,
+  // Types
+  type CommerceContext,
+  type CommercePipelineInput,
+  type VIExtractedClaims,
+  type AP2MandateTriple,
+  type ACPRequestContext,
+  type MPPRequestContext,
+  type X402RequestContext,
+  type UCPCheckoutContext,
+  type RegistryResolver,
+  type IdentityClaim,
+  type TransactionValueContext,
+} from '@astrasyncai/verification-gateway/transport';
+```
+
+**Tests** — 545 unit tests across 42 test files in this package. 13 additional
+integration tests in the backend exercise the full pipeline end-to-end via
+`POST /agents/verify-access` with a `commerceArtifacts` payload.
+
+### Added — Publishing hygiene
+
+- `prepublishOnly` script runs `clean` + `typecheck` + `build` before any
+  `npm publish`, so no one can publish from a stale dist or without a
+  passing typecheck.
+
+### Notes
+
+- Nothing is removed or renamed from the `2.0.x` API surface. Existing
+  middleware (`createMiddleware` on Express / Next.js), the agent-side client
+  (`AgentClient`), `verify()`, `quickVerify()`, `extractCredentials()`, and
+  all adapter registries continue to work unchanged.
+- The orphaned `2.0.1` publish (2026-03-09) was a snapshot published directly
+  from a local working copy without a matching git commit. Its code surface
+  is a strict subset of `2.0.0`'s source-with-fixes and has since been
+  superseded by content in `main`. All runtime behaviour from `2.0.1` is
+  preserved in `2.1.0`.
+
+## [2.0.1] — 2026-03-09 (orphaned)
+
+Published directly from a local working copy. No matching git commit or
+tag. Code surface is a strict subset of `2.1.0`. Included early SDK fixes
+(`durationRequired` forwarding, unregistered-attempt + counterparty
+pre-check activity reporting) plus `browser/background` and `cursor/extension`
+dist chunks; all of these are now in `2.1.0`.
+
+## [2.0.0] — 2026-03-08
+
+Universal Verification Gateway launch:
+
+- SDK handshake + PDLSS pre-check
+- Agent-side SDK: `AgentClient`, transport adapters (HTTP / A2A / MCP),
+  challenge handler
+- Counterparty-side SDK: `verify()`, `quickVerify()`, `verifyAndRecord()`,
+  `recordDecision()`
+- Adapter exports: `/express`, `/nextjs`, `/sdk`, `/agent`, `/transport`,
+  `/gateway`, `/local-evaluator`, `/adapter-interface`, `/cli`, `/cursor`,
+  `/browser`, `/git-trigger`
+- Local PDLSS evaluator (YAML + constraint checker)
+- AstraSyncGateway class (online / local / hybrid modes)
+- Hybrid sync queue (disk-backed, retry, status visibility)
+- Layer-4 adapters: OpenClaw CLI, Cursor, Browser
+
+## [1.1.0] — 2026-03-02
+
+## [1.0.0] — 2026-03-02
+
+Initial release.