@uppercut-labs/agent-native 0.0.0-stage → 1.1.0

package/docs/doctor-and-troubleshooting.md

@@ -0,0 +1,58 @@
+# Doctor, inspect, and authorized list
+
+To wrap a working site’s existing operation, follow [adopt an existing site](adopt-existing-site.md).
+
+The experimental `@uppercut-labs/agent-native/doctor` entrypoint provides read-only diagnostic building blocks. Applications supply checks and observations; the package does not discover credentials, probe a host, modify project files, or invoke capability handlers on its own. It is published in `1.0.0` and remains experimental; the stable core and surface entry points are listed in [stability](stability.md).
+
+## Machine report and exits
+
+`runDoctor(checks, { profile })` returns a `uan.doctor-report/v1` report. `DOCTOR_REPORT_JSON_SCHEMA` describes its closed JSON shape. Every finding has a stable `checkId`, target, status, severity, timestamp, evidence kind and source, a location and references, an explanation, and a concrete next action. A profile names the selected and required check IDs, so a local-only pass cannot be confused with network or host verification.
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | Selected checks have no failures or required unknown/skipped findings. |
+| `1` | At least one selected check failed. |
+| `2` | Invalid check or profile configuration (`DoctorUsageError`). |
+| `3` | No selected check failed, but a required check is unknown or skipped. |
+
+An observer exception produces an `unknown` finding without copying its error text into the report. The caller should log private diagnostics through its own protected channel if needed. Evidence source distinguishes `fixture`, `mock`, and `real-host`; a configured value or loopback fixture is not real-host behavior evidence.
+
+## Inspect and list
+
+`inspectCapabilityRegistry(registry)` returns the effective definitions and bindings without running handlers. `listAuthorizedCapabilities(registry, { surface, exposure, authorize })` filters by the requested surface, compatible binding, discovery policy, and authorization. It does not grant access to protected capabilities or bypass execution-time authorization.
+
+## Reproduce the local fault lab
+
+From the repository root, run `npm run example:e11` for a fresh tarball install and eight fault/repair scenarios. In the exported E11 project, `node src/cli.mjs doctor missing-binding --repaired --profile local` selects six configuration and artifact checks, makes no network request, and exits `0`. The default `full` profile requires two more network checks. Without `--probe-loopback`, those checks are skipped and a repaired fixture exits `3`; no endpoint is `unknown` and also exits `3`. The example README explains the optional loopback health fixture and its exact commands. No default check calls the destructive canary.
+
+A real deployment needs its own check implementations, trusted identity provider, endpoint, and evidence collection. E11 does not certify a browser, commercial MCP host, or production credential.
+
+See [permissions and discovery](permissions-and-discovery.md), [fixture compatibility](compatibility.md), and the [E11 example README](https://github.com/uppercut-labs/agent-native/blob/main/examples/e11-diagnostics-fault-lab/project/README.md).
+
+## Source-backed profile selection
+
+With Node.js 22 or newer, run `npm ci` and `npm run example:e11` from the package root.
+The fixture defines its local and full required-check profiles in source:
+
+<!-- source:examples/e11-diagnostics-fault-lab/project/src/doctor.mjs#doctor-profiles -->
+~~~js
+export const E11_DOCTOR_PROFILES = Object.freeze({
+  local: Object.freeze({
+    id: 'local',
+    selectedCheckIds: Object.freeze(LOCAL_CHECK_IDS),
+    requiredCheckIds: Object.freeze([...LOCAL_CHECK_IDS]),
+  }),
+  full: Object.freeze({
+    id: 'full',
+    selectedCheckIds: Object.freeze(FULL_CHECK_IDS),
+    requiredCheckIds: Object.freeze([...FULL_CHECK_IDS]),
+  }),
+});
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e11-diagnostics-fault-lab/project/src/doctor.mjs#L30)
+<!-- /source -->
+
+A repaired fixture under `--profile local` exits 0; the same fixture under the default
+full profile exits 3 until the optional loopback endpoint checks are actually run. An unknown
+scenario fails before creating a sandbox. See [E11 commands and sandbox cleanup](https://github.com/uppercut-labs/agent-native/blob/main/examples/e11-diagnostics-fault-lab/project/README.md).

package/docs/evidence/GHSA-ch52-4w7c-c8xp-2026-10-03.md

@@ -0,0 +1,17 @@
+# Astro cache advisory review (2026-10-03)
+
+Source snapshot: public `main` at `79f7e4ea8324ed616d83c04715a1eaf4dd175144`. Review ran in an isolated macOS clone with Node.js 25.9.0 and npm; this is a dependency/source review, not a deployed attack test. No release dependency was changed.
+
+## Dependency and affected surface
+
+`npm explain http-cache-semantics` resolves `astro@7.3.5 -> http-cache-semantics@4.2.0`. The root lockfile marks this path `dev: true`; the package declares Astro as an optional peer, not a hard runtime dependency. E02's `site-before` lockfile and generated project's package template explicitly use Astro 7.3.5. In the isolated clone, `npm audit --omit=dev --json` found zero root production vulnerabilities, while the full root audit reported two high findings and the E02 baseline audit reported three high findings, including this advisory. The other findings were outside this review.
+
+The [reviewed GitHub advisory](https://github.com/advisories/GHSA-ch52-4w7c-c8xp) covers versions through 4.2.0 and lists no patched version. It describes an attacker-controlled `Cache-Control: max-stale` request causing a shared cache to reuse a security-restricted response through `satisfiesWithoutRevalidation()`, potentially exposing another user's cached response or cookie. `npm view http-cache-semantics version` returned 4.2.0 on the review date. [Upstream fix PR #58](https://github.com/kornelski/http-cache-semantics/pull/58) was open. npm audit suggested Astro 2.10.9 as a semver-major change; it is not a compatible fix for the Astro 7 example or integration.
+
+Inspection of the installed Astro 7.3.5 distribution found one import of this library, in `dist/assets/build/remote.js`. That code calls `storable()` and `timeToLive()` to calculate remote-image expiry; it does not call `satisfiesWithoutRevalidation()`. A search of Astro's installed `dist` found no call to the vulnerable method. E02's checked-in source uses no Astro remote-image API. These observations do not prove that other applications, caches, or future Astro versions cannot reach the vulnerable behavior.
+
+## Release decision and recheck
+
+This advisory is recorded as an Astro development/example dependency warning. On the inspected source path it is not a demonstrated core package exploit and does not by itself block a core npm release candidate. Do not override the dependency with an unreleased PR or downgrade the example to Astro 2. Recheck the upstream advisory and installed Astro call sites before publishing the example as a production deployment guide, and update the lockfiles when a supported patched release exists. Applications using their own shared cache must assess that cache separately.
+
+Evidence commands: `npm explain http-cache-semantics`, `npm audit --omit=dev --json`, `npm audit --json` in the root and E02 baseline, `npm view http-cache-semantics version`, and a source search for `http-cache-semantics` and `satisfiesWithoutRevalidation` under installed `node_modules/astro/dist`.

package/docs/evidence/GHSA-ch52-4w7c-c8xp-2026-10-10.md

@@ -0,0 +1,30 @@
+# Astro cache advisory recheck (2026-10-10)
+
+This page rechecks the [2026-10-03 review](GHSA-ch52-4w7c-c8xp-2026-10-03.md). It is a dependency and source review, not a test against a deployed cache.
+
+## Upstream state
+
+- `gh api /advisories/GHSA-ch52-4w7c-c8xp` still lists `http-cache-semantics <= 4.2.0` as vulnerable and gives no patched version. The advisory was last updated 2026-10-02.
+- Upstream fix [PR #58](https://github.com/kornelski/http-cache-semantics/pull/58) was closed without merging on 2026-10-04. The maintainer's comment disputes the report: data private to one user should use `Cache-Control: private`.
+- `http-cache-semantics@4.3.0` was published on 2026-10-04. Comparing the published 4.2.0 and 4.3.0 `index.js` files shows changes only to `Vary` matching, inherited-property checks and a new response `status()` accessor. The `max-stale` branch in `evaluateRequest()` is unchanged. Because 4.3.0 falls outside the advisory's version range, `npm audit` would stop reporting it, but the behavior the advisory describes is unchanged.
+- `astro@7.3.8` is current and depends on `http-cache-semantics@^4.2.0`. In its published `dist`, the library is imported only by `assets/build/remote.js`. That file calls only `storable()` and `timeToLive()` to compute remote-image expiry. It does not call `satisfiesWithoutRevalidation()` or `evaluateRequest()`.
+
+## Decision
+
+The repository and example lockfiles stay on `astro@7.3.5` and `http-cache-semantics@4.2.0`. Moving to 4.3.0 would silence the audit finding without changing the reported behavior, which would be a misleading green check. Agent Native and its Astro examples never let `http-cache-semantics` answer requests from a shared cache. Astro, the only consumer, uses the library to compute how long remote images may be cached, not to decide whether a cached response may be reused.
+
+This closes the Astro advisory gate for the `0.1.1` preview, with the following limits:
+
+- The core and browser package has no dependency on `http-cache-semantics`.
+- The Astro integration and examples use only build-time image expiry, which is outside the reported path.
+- An application that runs its own shared HTTP cache on `http-cache-semantics` must evaluate the `max-stale` behavior itself and mark per-user responses `Cache-Control: private`.
+
+Recheck when the advisory changes its range, when Astro changes its use of the library, or before a provider launch guide is published.
+
+Evidence commands:
+
+- `gh api /advisories/GHSA-ch52-4w7c-c8xp`
+- `gh api repos/kornelski/http-cache-semantics/pulls/58` and its comments
+- `npm view http-cache-semantics versions` and `npm view astro@7.3.8 dependencies.http-cache-semantics`
+- `npm pack` of both `http-cache-semantics` versions, followed by a `diff` of `index.js`
+- `npm pack astro@7.3.8`, followed by `grep` for `http-cache-semantics`, `satisfiesWithoutRevalidation` and `evaluateRequest` under `dist`

package/docs/evidence/GHSA-ch52-4w7c-c8xp-2026-10-12.md

@@ -0,0 +1,10 @@
+# Astro cache advisory recheck for 1.0.0 (2026-10-12)
+
+This page rechecks the [2026-10-10 review](GHSA-ch52-4w7c-c8xp-2026-10-10.md) for the 1.0.0 candidate.
+
+- `gh api advisories/GHSA-ch52-4w7c-c8xp`: still severity high, vulnerable range `<= 4.2.0`, no patched version, not withdrawn, last updated 2026-10-02. Nothing changed since the previous review.
+- `npm view http-cache-semantics version`: 4.3.0, published 2026-10-04, the same release the previous review compared.
+- `npm view astro version`: 7.3.8, with `http-cache-semantics@^4.2.0`. In `npm pack astro@7.3.8`, only `dist/assets/build/remote.js` uses the library, through `storable()` and `timeToLive()` for build-time remote-image expiry. Nothing calls `satisfiesWithoutRevalidation` or `evaluateRequest`.
+- `npm audit --omit=dev` on the package: zero vulnerabilities. The package has no runtime dependencies. The full tree reports only this advisory, through the `astro@7.3.5` development and example dependency.
+
+**Decision:** the previous decision holds for 1.0.0. Agent Native and its Astro examples never let `http-cache-semantics` answer requests from a shared cache. An application that runs its own shared HTTP cache on that library must evaluate `max-stale` itself and mark per-user responses `Cache-Control: private`.

package/docs/evidence/UAN-002-house-style-review.md

@@ -0,0 +1,29 @@
+# UAN-002 house TypeScript style review
+
+Reviewed 2026-10-10 against the owner's [TypeScript house guide](https://starter.devthomas.site/style/TypeScript) (version 1.0.0, updated 2026-09-23). The scope was all owned TypeScript in `src/` (about 6,900 lines). The examples contain no `.ts`/`.tsx` sources: their callbacks are `.mjs` with JSDoc types, which this TypeScript-only guide does not cover. The emitted Astro `export default defineConfig(...)` template in `src/init.ts` is third-party framework output and stays as Astro requires.
+
+## Deviations found and changed
+
+| Guide rule | Before | After |
+| --- | --- | --- |
+| Maximum practical compiler strictness | `noImplicitReturns` missing from the baseline | Added to `tsconfig.json`; no errors resulted |
+| Avoid lint rules that rewrite intentional `let` | Biome `recommended` enabled `style/useConst` | `style/useConst` is off. `complexity/useLiteralKeys` is also off, because it contradicts `noPropertyAccessFromIndexSignature` bracket access. The rest of `recommended` remains |
+| `const` means immutable; `let` means mutable | Collections were held in `const` bindings and then pushed to or set | Mutated bindings use `let`. Never-mutated ones keep `const` with `readonly T[]`, `ReadonlySet`, `ReadonlyMap` or `Readonly<Record<…>>` |
+| No non-null assertions | 10 postfix `!` in `src/init.ts` | Replaced with visible `requireAt`/`requireValue` helpers. Each value was already established, so behavior is unchanged |
+| Shared `assertNever` | Owned-union switches over execution failures and harness events had no compile-time exhaustiveness | `src/core/assert-never.ts` (internal) closes the switches in `http.ts`, `mcp.ts` and `browser.ts`. `harness.ts` uses a local `never` guard that keeps its `HarnessError` for untrusted input |
+| Explicit types by default; explicit callback types | Locals, callbacks, default-valued parameters and some helpers relied on inference | About 460 locals were annotated with the types tsc inferred, plus callback parameters and returns, default-valued parameters and class fields. Async functions declare `Promise<T>`, and `runTurn` declares its `AsyncGenerator` type. A few internal aliases name repeated shapes |
+| `interface` for implementation contracts | `HarnessMcpBridge`, `BrowserCapabilityAdapter`, `WebMcpModelContext`, `NextBrowserBootstrap` and `McpAppRegistration` were object `type`s | Now interfaces. This is structural and source-compatible for consumers |
+
+The emitted declaration files were compared with a build of the previous source. Exported names, signatures and value types are unchanged apart from equivalent spellings.
+
+## Deliberate exceptions
+
+- `PACKAGE_VERSION` stays unannotated because `scripts/check-package-version.mjs` matches that exact line.
+- `DOCTOR_REPORT_SCHEMA_VERSION` and `DOCTOR_REPORT_JSON_SCHEMA` keep their inferred types. Annotating them would change exported literal types.
+- `as const`/`satisfies` precision sites stay as they are, which the guide allows.
+- `HarnessEvent` is a released public union discriminated by `type` rather than `kind`. Renaming it would break the 0.1.1 API, so it is left for a future major version.
+- Remaining `void promise.catch(handler)` calls use handlers that cannot throw, which the guide accepts.
+
+## Verification
+
+`npm run format:check`, `npm run lint`, `npm run typecheck` (all three tsconfig projects), `npm run build:browser-proof` and the full unit suite pass. That includes 124 non-harness tests and 6/6 Codex harness tests. The full `npm run check` and the isolated-export check repeat these on the committed source.

package/docs/evidence/UAN-007-astro.md

@@ -0,0 +1,43 @@
+# UAN-007 Astro static integration evidence
+
+## Fixture and before-state
+
+The tracked pre-integration site at `examples/e01-album-catalog/site-before` is an Astro 7.3.5
+static project with home, albums, and about pages; shared site layout and navigation; public album
+data; CSS; and SVG mark. `baseline-manifest.json` contains SHA-256 hashes for its project config,
+pages, data, and assets. The E01 check rebuilds that fixture before packaging and confirms the
+integrated project retained byte-identical layout, home/about pages, data, CSS, and SVG. The album
+page adds the human search form and browser capability bootstrap.
+
+## Verification
+
+Run `npm run example:e01` from the package root. It builds the baseline static project from a
+temporary copy, builds/packs the package, installs the package into the standalone fixture, executes
+the example tests, then builds and verifies the integrated static output. The checks cover:
+
+- Static `index.html`, `albums/index.html`, and `about/index.html`, preserved navigation,
+  public album content, CSS, and SVG.
+- Astro static output diagnostics and rejection of server output; no adapter is installed.
+- Shared album lookup through local execution, the browser registry, and the page fixture.
+- Astro ClientRouter page-load resync, before-swap revocation, repeat-install deduplication,
+  unsupported-WebMCP human search, Window pagehide, and back-forward cache pageshow re-entry.
+- Browser bundle exclusion checks for the HTTP and official MCP server adapters.
+
+The WebMCP API and Astro lifecycle are simulated in Node tests. Astro's production static build is
+real. No graphical browser, real WebMCP implementation, agent host, deployment provider, or
+lilgohan.com site was tested or changed. This fixture makes no production-hosting assumption.
+
+## Dependency audit limit
+
+The fixture pins `astro@7.3.5`, which resolves `http-cache-semantics@4.2.0`. On 2026-10-02,
+`npm audit` reports GHSA-ch52-4w7c-c8xp as high severity for that transitive package. The root
+development tree reports two high findings (Astro and the transitive cache package); the standalone
+Astro fixture reports three because Agent Native's optional Astro peer is also associated with the
+same Astro finding. `npm audit --omit=dev` on the package root reports zero vulnerabilities, and
+the package tarball does not bundle Astro. However, Astro consumers install Astro as their own
+dependency and may encounter the affected transitive package.
+
+The registry has no patched `http-cache-semantics` release above 4.2.0 at this check; npm's
+suggested Astro 2.10.9 downgrade is a breaking major rollback and was not applied. No override was
+added without a patched version to target. Release remains gated on resolving the upstream advisory
+or an explicit risk decision.

package/docs/evidence/UAN-008-worker-sidecar.md

@@ -0,0 +1,56 @@
+# UAN-008 Cloudflare Worker sidecar evidence
+
+## Scope
+
+E04 is a separate Worker sidecar for E01's static Astro catalog. The exporter copies E01's
+canonical public album data, shared capability contract, and sidecar diagnostics into an isolated
+Worker fixture. Browser and Worker bind the same definition, schema, lookup function, and data;
+parity tests verify contract identity and input/output schemas. A SHA-256 revision is derived from
+JSON-serialized ordered album records, and the E01 test recomputes it. Wrangler configuration is
+checked against the shared revision.
+
+The Worker delegates HTTP/OpenAPI and MCP to package adapters. It uses Web Request/Response APIs,
+bounded adapter bodies/deadlines, explicit SIDECAR_HOST and ALLOWED_ORIGIN configuration, Host and
+browser-Origin checks, and exact ACAO for the configured origin for browser health/HTTP diagnostics. Cross-origin browser MCP is not claimed; the official MCP client fixture sends no browser Origin. It exposes only the public-read
+album capability.
+
+## Verification
+
+Run npm run example:e04 from the repository root. The exporter installs the standalone fixture,
+runs 9 diagnostic/config/contract tests, then runs Wrangler locally on workerd. Local requests
+exercise matching catalog health, OpenAPI, an HTTP invocation, exact-origin ACAO/preflight, denied
+Origin and Host, and an official MCP SDK client discovery/call. The client records negotiated MCP
+protocol 2025-11-25. The HTTP and MCP success paths are real local workerd exchanges; the sidecar
+origin, missing same-origin route, missing binding, and revision mismatch classifier cases are
+simulated/unit requests.
+
+The same command runs Wrangler deploy --dry-run --outdir .worker-bundle. It scans all emitted JS
+files for Node builtin import/require specifiers and verifies the Wrangler config does not enable
+nodejs_compat. The dry-run builds and inspects only; it does not deploy. Operators can start local workerd with npx wrangler dev --local. A later, separately approved release would use npx wrangler deploy only after setting the actual host/origin/revision values and Cloudflare account; no live deployment was performed.
+
+E01's before-state fixture and integrated site both build as Astro static output with no server
+adapter. Its generated album page carries the shared revision. Browser sidecar diagnostics refresh
+after Astro ClientRouter navigation and Window pageshow, deduplicate installation, and probe the
+same-origin /mcp path only when same-origin routing is explicitly configured.
+
+## Limits
+
+Evidence is local workerd execution. No Cloudflare production deploy, account provisioning, paid
+resource, DNS change, custom host, real browser, or production CORS behavior was performed or
+verified. The fixture's SIDECAR_HOST, ALLOWED_ORIGIN, and public Astro environment values are local
+examples and must be replaced for an operator's hosts. A sidecar URL does not create a same-origin
+/mcp route. Cross-origin browser MCP is not claimed; the official MCP SDK fixture is server-side
+and sends no browser Origin.
+
+The SHA-256 revision is exposed in the static page and Worker health response. It is checked from
+ordered public album JSON in tests rather than computed dynamically in browser runtime. These
+diagnostic tests are simulated; the HTTP and MCP exchange against local workerd is real.
+
+The Astro 7.3.5 transitive http-cache-semantics@4.2.0 advisory and release gate documented in
+UAN-007 evidence remain unresolved. Astro is not bundled in the core tarball, but Astro consumers
+may install the affected dependency.
+
+## References
+
+- Cloudflare Wrangler configuration: https://developers.cloudflare.com/workers/wrangler/configuration/
+- Cloudflare local development: https://developers.cloudflare.com/workers/wrangler/commands/#dev

package/docs/evidence/UAN-009-init.md

@@ -0,0 +1,43 @@
+# UAN-009 existing-project init evidence
+
+The programmatic `@uppercut-labs/agent-native/init` entrypoint was implemented in
+[`638d79f`](https://github.com/uppercut-labs/agent-native/commit/638d79f76c40a94ed728010e689db69b86e21ae4)
+and its cross-version fixture check was corrected in
+[`19e108f`](https://github.com/uppercut-labs/agent-native/commit/19e108f3e4fcd8fffade0295a964d1cc99f78d02).
+Builds and fixture runs used `research` over SSH, with Node 25.9.0 and npm
+11.12.1. [GitHub CI run 37092885820](https://github.com/uppercut-labs/agent-native/actions/runs/37092885820)
+passed the package check and pack dry run on Node 22 and 24.
+
+## Verified behavior
+
+- `npm run check` passed format, lint, typecheck, browser bundle proof, 59 root
+  tests (including nine init tests), and the E01/E12/E05/E06/E04 example checks.
+- `npm run example:e01` copied an existing Astro static site into a path with
+  spaces, installed a fresh local tarball, applied an approved plan, and built
+  three static pages. The emitted browser JavaScript included the init ready
+  event and selected sidecar origin. Existing page data, navigation, CSS, SVG,
+  and non-server output remained intact. The fixture snapshots the lockfile
+  after tarball installation and confirms init leaves it byte-identical.
+- Init tests cover ambiguous app roots, competing lockfiles, dynamic config,
+  unsupported hosting, an existing `/mcp` route, path and symlink refusal,
+  stale plans, interruption before and after the Astro config write, rerun
+  no-op, manifest tampering, and conflict-aware restoration.
+- `npm pack --dry-run --json` included `dist/init.js` in a 73-file package.
+  The package remains `private: true` at version `0.0.0`.
+
+## Boundaries
+
+Automatic config rewriting supports only the exact literal Astro static
+template tested by E01. The exported flow is a JavaScript API, not a package
+`init` executable. It records a selected sidecar origin and injects a browser
+entry that signals readiness; it does not infer or register business
+capabilities, install dependencies, create `/mcp`, deploy a Worker, or verify
+an actual browser-agent host. E10 and E11 full standalone examples remain
+future slices; this ticket tests their init failure cases with disposable
+fixtures.
+
+File checks guard normal edits and interruptions, but a concurrent external
+writer can still change a target in the instant between its final hash check
+and rename or removal. Pause other writers while applying or restoring. Astro
+fixture installation still reports high severity transitive advisories;
+dependency review remains a public release gate. No npm publication occurred.

package/docs/evidence/UAN-010-auth.md

@@ -0,0 +1,17 @@
+# UAN-010: Trusted authentication and durable grants
+
+## Scope
+
+This slice adds `TrustedPrincipal`, `GrantStorePort`, `createGrantAuthorization`, `hasGrantForScopes` and `executionCallerForPrincipal` to the portable root API. The MCP adapter uses the official server SDK bearer gate when configured, maps verifier-owned identity through a host callback, and permits protected discovery only through an explicit callback. The E07 disposable playlist fixture supplies a local JSON grant store and static test verifier. It is not a production identity provider or grant database.
+
+## Local evidence
+
+On `research` with Node 25.9.0 and npm 11.12.1, `npm run check` completed successfully. That command includes format, lint, TypeScript checks, browser import boundary, root tests and standalone E01/E12/E05/E06/E04/E07 checks. `npm run example:e07` built and packed the package, installed a standalone project from the local tarball, ran its official SDK client/server tests, and printed the public sample playlist from its runnable demo.
+
+Auth tests deny reduced token scopes, mismatched caller, expired principal or grant, revoked grant, wrong audience and cross-tenant record access before a binding runs. E07 tests anonymous public discovery, hidden protected tools before a grant, repeated edit calls, grant reuse after process restart, separate delete scope, two tenants, wrong issuer/audience/expiry, and a stale previously visible tool name after revocation. An independent review identified a protected-read object-policy gap and a concurrent fixture write race; both were corrected before completion.
+
+## Boundaries
+
+The fixture's static test tokens, principal mapper and JSON file store reject production mode. The JSON store supports a single process with serialized writes; it is not a cross-process database. E07 reads grant state for each protected call and checks revocation at the next sequential lookup. A production provider must define its own store consistency, revocation latency, identity verification, resource ownership and safe grant issuance. The library does not issue OAuth tokens, implement token cryptography, refresh host sessions, or suppress host confirmation prompts.
+
+No external identity provider, provider deployment, native WebMCP browser, commercial MCP host, or real user consent flow was verified here. Astro's transitive `http-cache-semantics` advisory remains a release gate. The package is still `private: true` at `0.0.0` and is not published to npmjs.com.

package/docs/evidence/UAN-011-discovery.md

@@ -0,0 +1,18 @@
+# UAN-011 discovery policy evidence
+
+This bounded slice adds a shared `evaluateCapabilityDiscovery` decision and exact destructive surface exposure checks. It is applied to browser registration, MCP tool listing, and CLI help. Public reads remain the default visible catalog. Protected MCP discovery requires current token scopes and a matching live grant; the application's `discoverProtected` callback can only narrow the result. Destructive exposure additionally requires the canonical identity in the app's per-surface allowlist. The capability definition's risk metadata is unchanged.
+
+Adapter enforcement includes the call boundary: a stale browser callback rechecks exposure, MCP rebuilds stateless tools for each request and rejects hidden direct names before a binding, and local CLI destructive invocation fails before input parsing or handler execution unless explicitly exposed. The CLI help list filters by usable local bindings or public remote routes. MCP and OpenAPI omit definitions without exactly one compatible server binding. HTTP/OpenAPI remains public-read-only.
+
+The E07 fixture uses the official MCP client/server and its test-only verifier/store. It demonstrates edit grant discovery, Alice/Bob tenant-isolated catalogs, a delete grant that remains invisible until explicit MCP destructive exposure, refresh after revocation, and a stale direct call denied before the binding. The CLI fixture verifies generic hidden/unknown help, default public-only help, explicit protected read help, explicit destructive help, unbound filtering, and fail-closed direct destructive invocation.
+
+## Verification
+
+- Environment: research SSH, Node.js `v25.9.0`, npm `11.12.1`; SDK versions are pinned by package and fixture lockfiles.
+- `npm run build`: passed.
+- `node --test test/discovery.test.mjs test/cli.test.mjs test/browser.test.mjs test/mcp.test.mjs test/http.test.mjs`: 34 passed.
+- `npm run example:e07`: 3 tests passed, standalone demo returned the public sample playlist.
+- `npm run check`: passed after all code and fixture changes, including format, lint, typecheck, browser proof, root tests, and E01/E12/E05/E06/E04/E07 example checks.
+- `git diff --check`: passed.
+
+Known limits: this does not implement the E11 full runnable lab, OAuth/provider integration, production grant storage, protected HTTP routes, or deployment. The E07 JSON store is only single-process test storage. Browser host prompt behavior is not verified. Astro fixture dependency audits continue to report the previously documented advisories. E11 diagnostic-lab scope remains mapped to UAN-019/020.

package/docs/evidence/UAN-012-mcp-apps.md

@@ -0,0 +1,14 @@
+# UAN-012 MCP Apps adapter evidence
+
+The implementation was pushed as `47d089e072023504d66b32dabc7b9c4950111654`. [Node 22/24 CI](https://github.com/uppercut-labs/agent-native/actions/runs/37097823731) passed the root check and package dry-run on both versions. Local work and tests ran on `research` over SSH with Node 25.9.0 and npm 11.12.1, without foreground desktop use.
+
+## Verified behavior
+
+- An opt-in `./mcp-apps` subpath uses the official `@modelcontextprotocol/ext-apps@2.0.3` server helpers. Core and browser imports do not load the optional UI SDK. A resource attaches only to a capability visible through ordinary MCP discovery; tool calls and `App.callServerTool` follow-ups use the existing MCP handler, shared executor, schema validation, and authorization path.
+- E09 is a standalone album explorer built from E01's shared public catalog definition and data. The official `App` and `AppBridge` fixture receives a real MCP tool result over a local SDK client/server connection, then makes a host-mediated follow-up lookup. It also checks found, missing, denied, unavailable, malformed host input, and text-only result fallback. The denied lookup does not run its binding.
+- The resource uses the official `text/html;profile=mcp-app` MIME type. Validation requires a declared canonical capability, unique bounded `ui://` resource mapping, HTML under 1 MiB, and no external element/CSS origins, including protocol-relative network paths. Resource metadata has empty connect, resource, frame, and base-URI CSP allowlists. The view bundles its UI assets and carries no credentials.
+- `npm test`, `npm run example:e09` (three E09 tests), `npm run typecheck`, scoped Biome checks, `git diff --check`, and `npm pack --dry-run` passed on `research`. The test handshake has a three-second deadline and closes the view, bridge, MCP client, and server in cleanup.
+
+## Limits
+
+The view/host channel is a deterministic in-memory fixture paired with a real local MCP HTTP client/server connection. No commercial MCP Apps host, browser iframe sandbox, host confirmation prompt, deployment, or production identity provider was tested. Host implementations must enforce the declared CSP and their own trust and consent boundary. The package remains `private: true` at version `0.0.0`; no npm release was made. The existing Astro development/example transitive advisory remains a release gate.

package/docs/evidence/UAN-013-astro-on-demand.md

@@ -0,0 +1,47 @@
+# UAN-013 Astro on-demand evidence draft
+
+## Reproducible local checks
+
+Run `npm run example:e02`. The exporter builds and packs the current package, copies the E02
+after-state plus immutable before-state assets into `.exported`, generates `package-lock.json`,
+installs with `npm ci`, runs tests, builds Astro, and starts the Node standalone production server.
+
+The live check requests `/`, `/albums/`, and `/about/`; verifies that anonymous HTTP OpenAPI and
+MCP tool discovery expose the same public capability metadata; invokes the authenticated Agent Native
+HTTP route; connects with the official MCP 2.3.0 client and invokes the same sample capability; checks
+that anonymous invocation is denied and invalid input is rejected through both transports; and proves
+a protocol-shaped POST to the static negative file produces only its inert content. Build inspection
+requires all three unrelated human pages under `dist/client` while the protocol routes stay on demand.
+
+## Authentication and discovery boundary
+
+The sample album capability is intentionally marked `access: public`. Its description, input/output
+schemas, HTTP OpenAPI operation, and MCP tool listing are therefore public metadata. For this local
+fixture only, the shared execution-context resolver requires `Bearer e02-local-fixture`; both HTTP
+and MCP reject anonymous invocation. This tests invocation authorization parity without claiming
+protected discovery or production identity. The bearer value is public fixture data.
+
+Root checks are `npm run build`, `npm run build:test-fixtures`, `node --test test/init.test.mjs`, and
+`npm run check`. Init coverage detects the committed on-demand fixture and official adapter, then
+uses a disposable project to diagnose a missing adapter and reject `public/mcp.json` as a static
+protocol impostor.
+
+In the latest focused rerun after documenting the public-metadata/authenticated-invocation
+boundary, `npm run format:check`, `npm run typecheck`, and `npm run example:e02` all passed. The E02
+standalone command built, installed its fresh fixture dependencies, and passed its HTTP/OpenAPI/MCP
+smoke assertions. The earlier draft run also had 11 focused init tests pass. The full
+`npm run check` attempt reached the root socket tests, where the sandbox began rejecting every new
+loopback listener with `listen EPERM: operation not permitted 127.0.0.1`; a direct retry had the
+same environmental failure. Earlier in the same run, the root 73-test suite and E02 live server had
+both completed successfully before that restriction appeared.
+
+## Precise limits
+
+This is local evidence for Astro 7.3.5, `@astrojs/node` 11.1.6 standalone mode, Node 22.12 or newer,
+and the official MCP client/server packages at 2.3.0. It does not prove another Astro release,
+adapter, provider, TLS termination, external host, commercial MCP client, production identity,
+rate limiting, or deployment. The checked bearer value is public fixture data. The Astro
+integration does not install an adapter or generate endpoints. Existing-project init detects these
+conditions but deliberately leaves complex/on-demand config changes to reviewed application code.
+The standalone install reported four high-severity transitive audit findings; no unsafe automatic
+or breaking dependency rewrite was applied, so dependency review remains a release gate.

package/docs/evidence/UAN-014-next.md

@@ -0,0 +1,57 @@
+# UAN-014 Next.js integration evidence
+
+Local fixture record from October 2, 2026; deployed-host support is not established by this record.
+
+## Scope
+
+The preserved baseline is `examples/e03-next-reading-list/site-before`. The generated after-state
+comes from `examples/e03-next-reading-list/project` through `npm run example:e03`; the exporter packs
+the local package, pins the tarball in the generated manifest, creates a lockfile, installs with
+`npm ci`, tests, and builds Next 16.3.8 for the Node runtime.
+
+The isolated `@uppercut-labs/agent-native/next` entrypoint exposes App Router-compatible method
+handlers around the existing HTTP and official MCP adapters. `next/browser` is separate and imports
+only the browser adapter and core registry types. Neither core nor the Astro entrypoint imports Next.
+The route modules explicitly select `runtime = 'nodejs'`.
+
+## Acceptance evidence
+
+- `reading:catalog.list@1` is defined once and registered with separate server and browser bindings.
+  HTTP and MCP use the same server registry and shared executor; supported WebMCP uses the same
+  definition through the browser registry.
+- The official MCP 2.3.0 client connects over a real local HTTP socket, lists the catalog tool, and
+  calls it. The Next HTTP route invokes the same catalog and returns four public fake records.
+- The original `/api/catalog`, `/api/saved-list`, layout content, and fixture identity boundary are
+  retained. Tests keep the cross-user saved-list mutation denial and forged-identity denial.
+- Production browser source maps are enabled. The boundary script requires the fake server sentinel
+  in emitted server JavaScript and rejects it in every browser JavaScript and source-map artifact.
+- The browser bootstrap is feature-detected and resynced from a client component on pathname changes.
+  Package tests simulate two syncs and prove stale registrations are aborted. Ordinary page content
+  remains usable when WebMCP is absent.
+- Next init detection reads package/config/directory evidence without importing application code.
+  An existing App Router `/mcp` route yields a same-origin plan conflict with an empty proposed-file
+  list; the test verifies existing auth and layout bytes are unchanged.
+
+## Verification record
+
+Local verification on 2026-10-02 produced:
+
+- `npm run format:check`: passed after generated export/build output was removed.
+- `npm run lint`: passed with repository-existing informational diagnostics and warnings; no errors.
+- `npm run typecheck`: passed all three TypeScript projects.
+- `npm run build:browser-proof && npm test`: passed 76 tests after creating the browser-proof
+  output required by the existing sentinel test.
+- `npm run example:e03`: passed two saved-list authorization tests, HTTP route invocation, an
+  official MCP client exchange, Next 16.3.8 production build, and artifact inspection. The sentinel
+  occurred in one server artifact and no browser artifacts among 20 JavaScript/maps, including nine
+  source maps.
+- `npm_config_cache=/private/tmp/uan014-npm-cache npm pack --dry-run --json`: passed with 96 files;
+  the first attempt using the user cache was blocked by root-owned cache entries.
+
+## Limits
+
+Evidence is local to Node.js, Next 16.3.8, the production compiler, a loopback HTTP socket, the
+official MCP client, and a simulated WebMCP API. No provider deployment, Edge runtime, OAuth flow,
+durable multi-process store, commercial MCP host, physical browser, or native browser agent was
+tested. The fixture's sessions, catalog, and sentinel are public fake data. Generated `.next`,
+export, tarball, and installed dependency output are ignored and are not source evidence.

package/docs/evidence/UAN-015-node-hono.md

@@ -0,0 +1,69 @@
+# UAN-015 Node/Hono evidence
+
+This slice extends E05 into a standalone Node/Hono lab. One immutable capability registry provides
+the local CLI binding and the server binding used by both generated protocol handlers. A single
+Hono application mounts `createHttpHandler` under `/agent-native/v1` and `createMcpHandler` at
+`/mcp`; `runCapabilityCli` continues to provide local and remote CLI execution.
+
+The shared server auth boundary derives its caller only from the request and the server-owned
+`E05_TOKEN`. HTTP requires the local demo bearer scope. MCP is deliberately anonymous public/read
+only, with discovery and invocation still enforced by the core adapter and executor. MCP
+`clientInfo` is not consulted for identity. Socket and CLI diagnostics go to stderr and never emit
+credential values; successful CLI envelopes remain isolated on stdout.
+
+## Pinned environment and upstream check
+
+- Repository baseline: `eb7ef4f`.
+- Project requirement: Node.js 22 or newer. The original Codex sandbox used Node.js v26.9.0 and
+  npm 11.19.1; the independent plain-SSH rerun used Node.js v24.18.0 and npm 11.16.0.
+- Fixture runtime: `hono` 4.13.12 and `@hono/node-server` 2.1.3.
+- Protocol client: `@modelcontextprotocol/client` 2.3.0; the packaged MCP server dependency is 2.3.0.
+- The versions were checked against npm registry metadata on 2026-10-02. The implementation follows
+  Hono's [official Node.js guide](https://hono.dev/docs/getting-started/nodejs), which documents
+  `serve({ fetch, port })`, the returned Node server, and explicit graceful shutdown.
+
+The export harness generated `examples/e05-node-cli/.exported/package-lock.json`; its root entries
+pin the Hono framework, Node adapter, official MCP client, Zod, and the local package tarball. The
+export directory is generated evidence and remains gitignored.
+
+## Commands and outcomes
+
+- `npm ci --offline --ignore-scripts`: passed at the repository root; 212 packages installed and 0
+  vulnerabilities reported.
+- `node_modules/.bin/biome format --write <UAN-015 files>`: passed.
+- Scoped Biome lint for the three changed JavaScript files: passed with no diagnostics.
+- `npm run lint`: passed, with pre-existing informational/warning diagnostics outside UAN-015.
+- `npm run typecheck`: passed.
+- `npm run build:browser-proof && npm test`: passed, 72 tests.
+- `git diff --check`: passed.
+- `npm run format:check`: blocked by pre-existing formatting differences in the E02 baseline CSS and
+  baseline test; the UAN-015 files were formatted independently and those unrelated files were not
+  modified.
+- Original Codex sandbox: `npm_config_cache=/tmp/uan015-cache-seeded npm_config_offline=true npm run example:e05`:
+  package build, pack, standalone lock generation, and `npm ci` passed with 0 vulnerabilities. Five
+  non-socket CLI/security tests passed. Seven socket tests were blocked because this execution
+  sandbox rejects every `listen(127.0.0.1)` with `EPERM`; this is an environment limit, not an
+  assertion failure. The harness correctly stopped before `npm start` after the test failure.
+- In-process `app.request` checks returned HTTP 200 with the expected First Light value and MCP 400
+  for malformed JSON, confirming the Hono mount paths without opening a socket.
+- Independent plain-SSH verification on the same clone: `npm run example:e05` passed the standalone
+  build and pack, lockfile install with 0 vulnerabilities, all 12 fixture tests, and the local CLI
+  start. The passing tests included real loopback HTTP with the official MCP client, bounded
+  shutdown, SIGTERM, and port-conflict coverage. `npm run lint`, `npm run typecheck`,
+  `npm run build:browser-proof && npm test` (72 tests), and `git diff --check` also passed there.
+  `npm run format:check` failed only on the same pre-existing E02 baseline CSS and test formatting.
+
+The checked-in socket tests cover matching HTTP and official MCP-client lookup values, unauthorized
+HTTP, malformed MCP, bounded-operation shutdown without unhandled rejection, SIGTERM, and sanitized
+port-conflict reporting. Existing E05 tests retain local/remote CLI parity, authorization, missing
+profiles, unknown versions, malformed input, shell metacharacters, timeouts, and redaction.
+
+## Limitations
+
+No service was deployed and no npm package was published. The fixture does not prove compatibility
+with a commercial MCP host, a provider runtime, or Hono releases other than the pinned versions.
+The original Codex sandbox could not execute real loopback round trips, but the independent
+plain-SSH rerun executed them successfully on the same clone. The token and environment-backed
+profile are synthetic local examples, not production credential storage. Production use still
+needs TLS, trusted identity verification, secret management, rate limiting, observability, and
+process supervision.

package/docs/evidence/UAN-016-composition.md

@@ -0,0 +1,52 @@
+# UAN-016 composition evidence
+
+## Scope
+
+The implementation adds contract-only capability packs, explicit alias policy, stable
+authority/namespace composition, source-located conflict diagnostics, and shared deterministic
+HTTP/CLI/MCP/OpenAPI name mapping. Runtime execution still uses `executeCapability` and the existing
+registry/binding types.
+
+The exported E08 fixture contains a separately versioned `@example/e08-distance-contracts` package.
+Two consumer modules bind its single imported definition. Its tests cover distinct provider results,
+an authorization denial where the handler is not selected, a deliberately duplicated full identity,
+and an ESM load trace that rejects executor, registry, HTTP, MCP, Zod, or provider loading during a
+contract-only import.
+
+## Reproduction
+
+Use the required Node release from the repository root:
+
+```sh
+export PATH=/Users/research/.nvm/versions/node/v24.18.0/bin:$PATH
+npm run typecheck
+npm run lint
+npm run format:check
+node --test test/composition.test.mjs test/executor.test.mjs test/public-exports.test.mjs
+node --test --test-name-pattern='operation identifiers|tool naming' test/http.test.mjs test/mcp.test.mjs
+npm run example:e08
+npm run example:e12
+```
+
+Observed in the Codex CLI sandbox with Node 24.18.0: typecheck, focused lint/format, browser proof,
+and build passed; the two focused root test commands passed 16/16 and 2/2; E12's direct project
+tests passed 5/5. E08's tests passed 3/3 in an equivalent local package-link staging directory and
+its demo returned `30.48 cm` from `precise-consumer`. The CLI sandbox blocked the standalone
+`npm run example:e08` install because package network access was unavailable.
+
+An independent plain-SSH run on the same isolated clone completed `npm run example:e08`: the SDK and
+contract were packed separately, both tarballs installed in `.exported`, all four E08 tests passed,
+and the demo returned `30.48 cm` from `precise-consumer`. The standalone install reported zero
+vulnerabilities. The tests check matching conversion values from both consumer bindings and invoke
+each consumer entrypoint in an independent process. E12's established canonical ID remained
+unchanged. `npm run typecheck` and a scoped Biome check also passed after this review.
+
+## Limits
+
+- Pack metadata is local application data; there is no remote registry, signature verification, or
+  package provenance attestation.
+- FNV-1a is a deterministic name qualifier, not a security primitive. Composition and adapter setup
+  still check generated names for collisions rather than assuming the digest is unique.
+- Aliases are local lookup conveniences and do not change canonical IDs or transport routes.
+- Composition neither elevates permissions nor establishes transaction semantics.
+- This work does not implement v2 migration or compatibility negotiation; that is UAN-017 scope.