@multiagency/sdk 0.3.1

package/CHANGES.md

@@ -0,0 +1,21 @@
+# @multiagency/sdk changes
+
+Every SDK change appends a note under the next version's heading when it is made: what changed for the apps, and any
+wire change all apps must update for together. The first change after a release moves `package-version.ts` to the next
+version, so a package staged or packed from changed sources never carries a released version's number. The release
+candidate dates the heading. Under 0.x, any public-interface change bumps at least the minor version.
+
+## 0.3.1 (2026-10-31)
+
+No code, type or wire change.
+
+- **License: MIT** (copyright MultiAgency LLC).
+- **README:** "What the platform does for your product": what the provider does, what the platform guarantees to an
+  app and what the app still does, and what has run where for each client's routes.
+- **app-server skill:** the platform's host serves only `/apps/v1` and the confirm page (no sign-in or owner page), and
+  setup there is for Payables agents only. A vote the platform can't verify is refused before anything reaches the
+  provider (`refused`, code `local_authorization_held`).
+
+## Earlier versions
+
+0.0.1 to 0.3.0: see the [changelog at sdk-v0.3.0](https://github.com/MultiAgency/platform/blob/sdk-v0.3.0/docs/sdk-changes.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MultiAgency LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# MultiAgency SDK
+
+Build a product interface or an external agent that uses the MultiAgency platform's existing agreements, contribution reports, payments and Treasury workflows. The SDK supplies clients, response schemas and recovery outcomes. The platform keeps identity, authorization, authoritative records and guarded execution.
+
+Start with one supported workflow. A product may provide its own screens, navigation, drafts and preferences while calling the same platform. A new server-side domain or authority model needs a platform extension; importing this package does not create one.
+
+## Install the package
+
+The SDK is MIT-licensed. Install it with:
+
+```text
+pnpm add @multiagency/sdk zod@^4.6.5
+```
+
+Each package carries `provenance.json`: the source commit it was packed from, any uncommitted paths in that tree, and a digest for every file it was built from. One version number identifies one package: npm does not let a published version be republished with different contents (per npm's documented policy). The package's own README, skills and `CHANGES.md` describe that exact version.
+
+Zod is the one peer: a product's schemas and the SDK's share one Zod. The owner entry (`@multiagency/sdk`) bundles its own `@orpc/client` 2.0.0-beta.47 (licenses in `THIRD-PARTY-NOTICES`) and loads no other oRPC package, so a product on another oRPC version, or a host that shares its own as a Module Federation singleton, keeps it; its bundle then carries both oRPC clients. `@multiagency/sdk/contract` (`ownerContract`, for an app implementing a server from the contract) loads `@orpc/contract` 2.0.0-beta.47, a dependency, as does nothing else. The owner entry also depends on `@ag-ui/core` 1.0.3. The contributor entry loads none of them. The installed package's dependencies and peerDependencies are authoritative for that package. The supported Node target is Node 24. TypeScript consumers use ESM with NodeNext resolution and the ES2023 and DOM libraries for the clients' web request types. The Node-only release-server entry also needs Node typings.
+
+For development against unreleased SDK source, install an SDK repository checkout's dependencies and run `pnpm sdk:dev --once` there, then link your product to its generated `packages/sdk` directory. Use `pnpm sdk:dev` to watch changes. The generated directory is not source and is intentionally absent from Git. A linked checkout can differ from the published package of the same version, so record which one a release was built with, and keep local paths out of portable release inputs.
+
+## Choose the client and supported access
+
+| Product or caller | Client | Required access |
+| --- | --- | --- |
+| Owner-facing browser product | `ownerClient` from `@multiagency/sdk` | A host-local owner/member session and access to the configured agent |
+| Contributor-facing browser product | `payeeClient` from `@multiagency/sdk/payee` | The contributor's session on that contributor entry |
+| Contributor's external agent | `payeeClient({ base, token })` | An expiring, revocable report connection started by the contributor |
+| Treasury external agent | `ownerClient` with an absolute machine base and a `fetch` that adds the bearer | An existing wallet-owner-issued Treasury credential with the required scopes; see owner-workflows |
+| An app's server (for example the MultiAgency dashboard) | `appClient({ base, credential })` from `@multiagency/sdk` | The deployment's operator-issued service credential, plus a live owner consent per Organization and agent |
+
+The platform operator configures a browser product's host, reachable agents and frontend release. Browser products use that host's gateway and session. A custom frontend does not receive a provider key or grant, and cannot choose another host's agents.
+
+An app's server reaches agents under `/apps/v1` and never from a browser: the service credential is a server secret. The
+owner signs `consentMessage(...)` (or `setupMessage(...)` for a hosted agent) with NEP-413 in the app; the server submits
+it. A consent reaches the listed reads (`APP_READS`) and owner actions (`APP_OWNER`) and, for `owner/prepare`, only
+actions the owner can read when signing or that platform code builds entirely (`AppOwnerAction`); everything else is
+refused. The app never asks an owner to sign the platform's sign-in text. See the platform's `docs/agent-access.md`,
+"App access". No production MultiAgency host serves the `/apps/v1` routes yet; the operator runs them on a staging host
+for its own tests. Build against the SDK repository's local stack (`pnpm test:e2e:stack --app <deployment>`), with a
+simulated provider, chain and wallet.
+
+An agent connection permits its contributor's reports and compensation reads only. It cannot file invoices, approve payments, sign owner actions or manage connections. Treasury machine access is a separate existing route and credential; Payables owner delegation and DAO machine delegation are unavailable.
+
+## What the platform does for your product
+
+The NEAR Intents Agent API provider holds the funds, enforces the policy the owner signed (payees, caps, budget, held approvals), prepares the owner actions a wallet or DAO signs, and executes money actions. The platform does the rest of what a product would otherwise build around the provider, and no client of this SDK receives a provider key or grant.
+
+What your product can rely on, and what it still does:
+
+- **Each money action is sent at most once.** One executor per agent sends every action from one place, after a write-ahead record, so a crash, restart or lost reply never sends it again, and an app's `requestId` is honored once. An outcome the platform can't prove stays unresolved and blocks new money actions on that agent. Your product never resends after `unknown`; it reads `activity` and `unresolved` (see Handle outcomes explicitly).
+- **What the provider can't check is refused before sending.** The provider enforces the signed policy; the platform also checks that the policy is still the one in force, the grant fits the action, a swap buys an asset the policy lists, a held payout isn't duplicated and a saved plan runs as it was quoted. A recipient that doesn't exist on NEAR is refused before anything is recorded. Your product branches on the refusal's `kind` and code, never its text.
+- **Owners approve what they read.** Owner actions are prepared on the platform and completed only by the owner's own signature or a DAO's vote. A vote on a held payout is checked against the provider's own record of that payout, so the approval releases exactly the terms shown. Your product shows what the owner is signing; it never signs for them.
+- **Callers are bound to their host, owner and agent.** Sessions are host-local; machine credentials and app consents name one host, agent and owner, expire, and can be revoked. Your product keeps credentials server-side and out of logs and URLs.
+
+What has run where, by the routes each client calls:
+
+| Client | Status |
+| --- | --- |
+| `ownerClient`, in the owner's session | Mainnet-observed on the hosted platform: reads, owner actions, held-payout votes, and plan execution through the Treasury autopilot |
+| `ownerClient` with a machine credential | Offline- and stack-tested; not observed on mainnet |
+| `appClient` | Mainnet-observed on platform staging (2026-10-28, 2026-10-30); not in production; wallet-owned agents only |
+| `payeeClient`, in the contributor's session | Mainnet-observed on the hosted invoice entry: invoices and agreement requests (2026-10-12, 2026-10-14) |
+| `payeeClient` with a report connection | Offline- and stack-tested; not deployed |
+
+Crash recovery and the refusals above are tested offline, not observed on mainnet. The platform's [mainnet log](https://github.com/MultiAgency/platform/blob/main/docs/mainnet-log.md) records what has run on mainnet, and [enforcement](https://github.com/MultiAgency/platform/blob/main/docs/enforcement.md) what the signed policy guarantees.
+
+## First read from a browser product
+
+After signing in on the product's configured host, use the configured agent key:
+
+```ts
+import { ownerClient } from "@multiagency/sdk";
+
+const owner = ownerClient({ base: "/a/payout" });
+const overview = await owner.call("overview");
+
+if (overview.ok) {
+  console.dir(overview.value);
+} else {
+  console.log(overview.kind);
+}
+```
+
+Replace `payout` with the key configured for your host. Use the typed response to render your screen. A `session` result needs sign-in; `forbidden` means this identity lacks access. Capability and permission helpers can guide what to display; the server authorizes every request.
+
+The SDK repository's `examples/minimal-prototype` is the browser reference: a page bundled with rsbuild that imports `@multiagency/sdk`, signs in through the gateway, reads its agent and takes one wallet-signed owner action, keeping the prepared action's `correlationId` across a lost reply and a reload. Its end-to-end test runs it on the isolated stack with a simulated provider. Use the public clients rather than reproducing the RPC wire format.
+
+## First read from a contributor agent
+
+Have the contributor start a report connection from their signed-in application. Give the agent the connection token and the API entry base: the origin, or the origin plus `/i/<instance>`. Do not use a page URL ending in `/submit` or `/report` as the API base.
+
+```ts
+import { payeeClient } from "@multiagency/sdk/payee";
+
+const entry = process.env.MULTIAGENCY_ENTRY;
+const token = process.env.MULTIAGENCY_REPORT_TOKEN;
+if (!entry || !token) throw new Error("Provide the contributor API entry and report token.");
+if (new URL(entry).protocol !== "https:") throw new Error("Use the HTTPS contributor entry.");
+
+const contributor = payeeClient({ base: entry.replace(/\/$/, ""), token });
+const session = await contributor.compensationSession();
+if (!session.ok) throw new Error(`Contributor access: ${session.kind}`);
+
+const records = await contributor.compensation();
+if (records.ok) {
+  console.log(records.value.agreements.map(a => ({
+    id: a.id, title: a.terms.title, remainingAtomicUsdc: a.remaining,
+  })));
+} else {
+  console.log(records.kind);
+}
+```
+
+The token is sent as a bearer without browser cookies. Keep it out of source, URLs and logs. An agent never needs the contributor's wallet key or an exported browser cookie.
+
+## Build the report workflow
+
+1. Read and select the intended agreement. Its scope, period and remaining allowance bound the work; allowance is not an earned amount.
+2. Construct the complete report command using the payee-workflows example. Save its request ID, command ID and exact contents before sending.
+3. Use `expectedVersion: 0` for a new request. For a revision, keep the request ID and use its current returned version with a new command ID for the new intended change.
+4. `submit: false` saves a server draft; `submit: true` sends the report to owner review. Only a draft or a request returned for changes can be revised.
+5. An optional report amount is a proposal in atomic USDC: `"12000000"` is 12 USDC. The owner chooses a separate approved amount.
+6. After `unknown`, keep the exact command and read the original request by its ID. Recovery is a read. Do not create a replacement or resend automatically. The entry records each `commandId` with its content: sending the identical command again returns the original record, and a different payload under the same `commandId` is refused with `command_conflict`. A missing request after `unknown` does not prove that nothing was recorded.
+7. Match the returned payment by request ID. An approved report is not a paid payment: only a payment whose status is `paid` reports recorded settlement. Display the last recorded status as read.
+
+Refusals carry a `code`, for example `stale_request` (the version moved; read it again), `request_locked` (already submitted, approved or declined), `outside_period` (the report period must fit the agreement), `agreement_changed` (a request keeps its first agreement), `not_found`, `intake_full`, `identity_conflict` (the request's `id` is already used), `command_conflict` and `rate_limited`.
+
+Validate fields with `reportCommand.safeParse` before sending. Invalid structured input throws a Zod validation error locally and sends nothing.
+
+## Handle outcomes explicitly
+
+Reads may be repeated after `unavailable`. `session` and `forbidden` require different user actions. A typed refusal says the action did not proceed; correct the stated cause before another intended action. An `unknown` action may have taken effect. Preserve its available identity and follow the documented reads.
+
+The SDK never automatically resubmits an action. Some owner procedures have no caller-held lookup identity; the owner-workflows skill describes their limits. Diagnostic provider request IDs are not verified operation links. An unresolved payment may continue blocking its agent until a supported resolution exists.
+
+## Continue with the bundled guidance
+
+The package contains `skills/getting-started/SKILL.md`, `skills/payee-workflows/SKILL.md`, `skills/owner-workflows/SKILL.md` and `skills/app-server/SKILL.md`. These files describe the clients in the installed package and can be read directly or through TanStack Intent. `CHANGES.md` records consumer-impacting changes.
+
+Use `@multiagency/sdk/schemas/*` for the published JSON schemas. The Node-only `@multiagency/sdk/release-server` serves immutable frontend artifacts; it does not authenticate callers or run a financial executor.
+
+For a local rehearsal, the SDK repository's existing simulated stack supplies the gateway and provider fixtures. Keep simulated sign-in, approvals, funding and settlement visibly separate from the product's SDK calls. A successful simulation does not authorize a hosted deployment or financial action.

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,127 @@
+@orpc/client@2.0.0-beta.47 (MIT), bundled in dist/contract/orpc-client.js
+
+MIT License
+
+Copyright (c) 2023 oRPC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+------------------------------------------------------------------------------
+
+@orpc/shared@2.0.0-beta.47 (MIT), bundled in dist/contract/orpc-client.js
+
+MIT License
+
+Copyright (c) 2023 oRPC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+------------------------------------------------------------------------------
+
+@standard-server/core@0.13.0 (MIT), bundled in dist/contract/orpc-client.js
+
+MIT License
+
+Copyright (c) 2025 Standard Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+------------------------------------------------------------------------------
+
+@standard-server/fetch@0.13.0 (MIT), bundled in dist/contract/orpc-client.js
+
+MIT License
+
+Copyright (c) 2025 Standard Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+------------------------------------------------------------------------------
+
+@standard-server/shared@0.13.0 (MIT), bundled in dist/contract/orpc-client.js
+
+MIT License
+
+Copyright (c) 2025 Standard Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/release-server.d.mts

@@ -0,0 +1,29 @@
+// Types for release-server.mjs (shipped as `@multiagency/sdk/release-server` and the `multiagency-release-server` bin).
+import type { Server } from "node:http";
+
+/** A release's `contract.json`, as the server reads it. Unknown keys are kept. */
+export type ReleaseContract = {
+  version: 1;
+  product: string;
+  required: string[];
+  optional?: string[];
+  /** Logical path → file in the release, for example `{ "/": "index.html", "/skill.md": "skill.md" }`. */
+  entries: Record<string, string>;
+  fallback?: string;
+  strip?: string;
+  assetPrefix?: string;
+  [key: string]: unknown;
+};
+/** A complete release on disk: its id (the directory digest), directory and contract. */
+export type Release = { id: string; dir: string; contract: ReleaseContract };
+
+/** The release id of a directory: sha256 over its sorted relative names and bytes. */
+export function digest(dir: string): string;
+/** The complete release `id` under `root`. Throws when the id, contract or any declared entry is invalid. */
+export function readRelease(root: string, id: string): Release;
+/** Copies a complete build under `root` as its digest and returns that id; an interrupted stage never appears. */
+export function stage(root: string, built: string): string;
+/** Verifies release `id` (bytes and retained hashed assets) and switches `ACTIVE` to it atomically. */
+export function activate(root: string, id: string): Release;
+/** An HTTP server for the active release under `root`: GET/HEAD only, presentation only. Not yet listening. */
+export function releaseServer(root: string): Server;

package/bin/release-server.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// One release asset server for app frontends behind the platform gateway (P2 D5). Presentation only:
+// GET/HEAD, no API, no outbound calls, no platform configuration. Environment: HOST, PORT, RELEASES_ROOT.
+//   serve                     (default) serve RELEASES_ROOT/<ACTIVE>/
+//   stage <built-dir>         copy a complete build to RELEASES_ROOT/<digest>/ and print the id
+//   activate <id>             verify that release, then switch ACTIVE atomically
+// A release is a directory whose contract.json declares { version, product, required, optional?, entries,
+// fallback?, strip?, assetPrefix? }. Its id is the digest of the directory (the platform E2E runner's digest()).
+import { createServer } from 'node:http';
+import { createHash } from 'node:crypto';
+import { chmodSync, cpSync, existsSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { extname, join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const ID = /^[a-f0-9]{64}$/;
+const HASHED = /^\/static\/[a-zA-Z0-9_./-]*\.[a-f0-9]{8,}\.[a-z0-9]+$/;
+const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json', '.md': 'text/markdown; charset=utf-8', '.woff2': 'font/woff2', '.woff': 'font/woff', '.svg': 'image/svg+xml', '.png': 'image/png', '.ico': 'image/x-icon' };
+
+/** Same algorithm as test/e2e/run.mjs digest(): sorted relative names and bytes. */
+export function digest(dir) {
+  const hash = createHash('sha256');
+  const scan = (path, prefix = '') => {
+    for (const file of readdirSync(path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const name = prefix + file.name;
+      if (file.isDirectory()) scan(join(path, file.name), name + '/');
+      else if (file.isFile()) hash.update(name).update('\0').update(readFileSync(join(path, file.name))).update('\0');
+    }
+  };
+  scan(dir); return hash.digest('hex');
+}
+
+/** Real path inside the root, or null: no `..`, no symlink escape. */
+function inside(root, ...parts) {
+  if (parts.some(p => p.split('/').includes('..'))) return null;
+  try {
+    const real = realpathSync(join(root, ...parts)), base = realpathSync(root);
+    return real === base || real.startsWith(base + sep) ? real : null;
+  } catch { return null; }
+}
+
+/** A complete release: valid id, parsable contract, every declared entry present. Throws otherwise. */
+export function readRelease(root, id) {
+  if (!ID.test(id)) throw new Error('Invalid release id');
+  const dir = inside(root, id);
+  if (!dir || !statSync(dir).isDirectory()) throw new Error('Release missing');
+  const contract = JSON.parse(readFileSync(join(dir, 'contract.json'), 'utf8'));
+  if (contract.version !== 1 || typeof contract.product !== 'string' || !contract.entries || typeof contract.entries !== 'object') throw new Error('Invalid contract');
+  for (const file of [...Object.values(contract.entries), ...(contract.fallback ? [contract.fallback] : [])])
+    if (typeof file !== 'string' || !inside(dir, file) || !statSync(inside(dir, file)).isFile()) throw new Error(`Release incomplete: ${file}`);
+  return { id, dir, contract };
+}
+/** Releases that were activated, oldest first. Only these may supply retained assets; staged or partial ones never do. */
+const history = root => { try { return readFileSync(join(root, 'HISTORY'), 'utf8').split('\n').filter(id => ID.test(id)); } catch { return []; } };
+const activeId = root => { try { return readFileSync(join(root, 'ACTIVE'), 'utf8').trim(); } catch { return null; } };
+
+/** Copy into a temporary directory, verify, then rename into place: an interrupted stage never appears as a release. */
+/** A copy keeps the build's modes. A frozen build is read-only, and a read-only directory can be neither renamed nor
+ * emptied, so the staged copy's directories are made owner-writable. File contents and the release id are unchanged. */
+function ownerWritable(dir) {
+  if (!existsSync(dir)) return;
+  chmodSync(dir, statSync(dir).mode | 0o700);
+  for (const entry of readdirSync(dir, { withFileTypes: true })) if (entry.isDirectory()) ownerWritable(join(dir, entry.name));
+}
+
+export function stage(root, built) {
+  const id = digest(built), target = join(root, id);
+  if (existsSync(target)) { if (digest(target) !== id) throw new Error('An existing release does not match its id'); readRelease(root, id); return id; }
+  const temporary = join(root, `.staging-${process.pid}-${Date.now()}`);
+  try {
+    cpSync(built, temporary, { recursive: true });
+    ownerWritable(temporary);
+    if (digest(temporary) !== id) throw new Error('Staged copy does not match its build');
+    renameSync(temporary, target);
+  } finally { ownerWritable(temporary); rmSync(temporary, { recursive: true, force: true }); }
+  try { readRelease(root, id); } catch (error) { rmSync(target, { recursive: true, force: true }); throw error; }
+  return id;
+}
+
+/** Verify completeness, identity and that no retained hashed file differs under the same name; then switch. */
+export function activate(root, id) {
+  const release = readRelease(root, id);
+  if (digest(release.dir) !== id) throw new Error('Release bytes do not match its id');
+  const files = dir => { const out = []; const scan = (p, prefix) => { for (const e of readdirSync(p, { withFileTypes: true })) e.isDirectory() ? scan(join(p, e.name), `${prefix}${e.name}/`) : out.push(`${prefix}${e.name}`); }; if (existsSync(dir)) scan(dir, '/static/'); return out; };
+  for (const other of history(root).filter(name => name !== id))
+    for (const name of files(join(root, id, 'static')).filter(n => HASHED.test(n))) {
+      const theirs = join(root, other, name);
+      if (existsSync(theirs) && !readFileSync(theirs).equals(readFileSync(join(root, id, name)))) throw new Error(`Conflicting retained asset ${name} in ${other}`);
+    }
+  const activated = [...history(root).filter(name => name !== id), id];
+  writeFileSync(join(root, 'HISTORY.next'), activated.join('\n') + '\n'); renameSync(join(root, 'HISTORY.next'), join(root, 'HISTORY'));
+  writeFileSync(join(root, 'ACTIVE.next'), id + '\n'); renameSync(join(root, 'ACTIVE.next'), join(root, 'ACTIVE'));
+  return release;
+}
+
+export function releaseServer(root) {
+  return createServer((req, res) => {
+    res.setHeader('x-content-type-options', 'nosniff');
+    res.setHeader('referrer-policy', 'no-referrer');
+    res.setHeader('x-frame-options', 'DENY');
+    res.setHeader('cache-control', 'no-store');
+    if (!['GET', 'HEAD'].includes(req.method)) return res.writeHead(405).end();
+    let release;
+    try { release = readRelease(root, activeId(root) ?? ''); }
+    catch { return res.writeHead(503, { 'content-type': 'application/json' }).end('{"error":"No complete active release"}'); }
+    res.setHeader('x-release-id', release.id);
+    const { contract } = release;
+    let path = new URL(req.url, 'http://release').pathname;
+    if (contract.strip) path = path.replace(new RegExp(`^(?:${contract.strip})(?=/|$)`), '') || '/';
+    if (contract.assetPrefix && path.startsWith(`${contract.assetPrefix}/static/`)) path = path.slice(contract.assetPrefix.length);
+    const send = (file, cache) => {
+      const bytes = readFileSync(file);
+      res.writeHead(200, { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream', ...(cache && { 'cache-control': cache }) }).end(req.method === 'HEAD' ? undefined : bytes);
+    };
+    if (path === '/health') return res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ok: true, product: contract.product, release: release.id }));
+    if (path === '/contract.json') return send(join(release.dir, 'contract.json'));
+    const entry = contract.entries[path] ?? contract.entries[path.replace(/\/$/, '')];
+    if (entry) return send(inside(release.dir, entry));
+    if (HASHED.test(path)) {
+      // Hashed names are immutable: the active release first, then retained ones for pages already open.
+      for (const id of [release.id, ...history(root).filter(name => name !== release.id).reverse()]) {
+        const file = inside(root, id, path.slice(1));
+        if (file && statSync(file).isFile()) return send(file, 'public, max-age=31536000, immutable');
+      }
+      return res.writeHead(404).end('Not found');
+    }
+    // A declared SPA fallback answers client routes only: never an API-like, static or extension path.
+    if (contract.fallback && !extname(path) && !/^\/(api|internal|static|gw|machine)(\/|$)/.test(path)) return send(inside(release.dir, contract.fallback));
+    res.writeHead(404).end('Not found');
+  });
+}
+
+// The real path: npm's bin link is a symlink, and import.meta.url names its target.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  const root = process.env.RELEASES_ROOT, [command = 'serve', argument] = process.argv.slice(2);
+  if (!root) throw new Error('RELEASES_ROOT is required');
+  if (command === 'stage') console.log(stage(root, resolve(argument)));
+  else if (command === 'activate') console.log(`Active release ${activate(root, argument).id}`);
+  else {
+    const host = process.env.HOST || '127.0.0.1', server = releaseServer(root);
+    server.listen(Number(process.env.PORT || 0), host, () => console.log(`Release asset server ready on http://${host}:${server.address().port}`));
+  }
+}