@jimhoyd/urlcode 0.4.0-alpha.1 → 0.4.0-alpha.2

package/docs/LOAD-TESTING.md

@@ -75,8 +75,8 @@ largest one that makes a number go green.
 
 ## What a passing run does not prove
 
-- **GET and HEAD only.** Function routes with request bodies, live-link writes
-  and the management API are not exercised. `workload` states this in every report.
+- **GET and HEAD only.** Function routes with request bodies are not exercised.
+  `workload` states this in every report.
 - **Redirects are not followed**, so a redirect's destination is never loaded.
 - **One client, one host, no slow peers.** Tail latency under adversarial
   clients, connection churn or packet loss is not measured.
@@ -87,5 +87,5 @@ largest one that makes a number go green.
   runtime and application revisions, host, and command with any figure you keep.
 
 `scripts/operational-drills.ts` covers the adjacent ground — mixed
-native/function/live-link load, an invalid reload, rollback and a quiesced
-backup/restore — as a local proof, never a statement about production.
+native/function load, an invalid reload and rollback — as a local proof,
+never a statement about production.

package/docs/MIDDLEWARE.md

@@ -2,7 +2,10 @@
 
 Middleware is reusable JavaScript around any route handler. It is optional and
 route-local; plain redirects and assets retain their native fast path when no
-middleware is attached. Adding middleware requires sandbox execution.
+middleware is attached. Middleware runs trusted and unsandboxed by default,
+in-process with full Node access, the same as a `function` route; add
+`sandbox: true` on the route to run the whole chain isolated instead (see
+[trust model and sandbox opt-in](FUNCTION-SECURITY.md)).
 
 ```yaml
 version: "1"
@@ -49,37 +52,45 @@ reading one consumes it for downstream code. There is no `clone()` or streaming
 API; pass parsed data through `context.state` when needed.
 
 Function responses support the existing text/JSON guest API. To transform their
-body, read it and return a new `Response`. Native redirect/respond/link/page/static/
+body, read it and return a new `Response`. Native redirect/respond/page/static/
 download bodies are opaque and cannot be read through `text()` or `json()`.
 Returning the same native response preserves original bytes, including binary
 files, ranges and HEAD lengths. You may add headers, but cannot change its
 original status or existing native headers while preserving that body. To replace
 status, destination or content, return a new `Response` instead. Replacement
-responses follow the normal sandbox text/JSON and size limits. To wrap a shared
+responses follow the normal response size limits, and (on a `sandbox: true`
+route) the guest's text/JSON constraints. To wrap a shared
 template around file content, render it through a function at build time and
 publish the result: see [prerendering](PRERENDER.md).
 
 Route selection, enabled/expiry checks, methods and input/body validation run
 before middleware. Their errors do not pass through the chain. A missing file
-inside a selected static mount is a downstream 404 response. Stored-link lookup
-errors (missing, disabled, expired or unavailable store) precede middleware. YAML
+inside a selected static mount is a downstream 404 response. YAML
 `response.headers` apply last and override matching middleware headers. Runtime
 framing and asset metadata protections still apply.
 
-## Isolation and testing
+## Trust, isolation and testing
 
-The whole chain and handler run in one fresh QuickJS/WASM guest with one memory
-budget and one deadline. No Node, filesystem, shell, fetch or ambient environment
-is exposed. Modules can only access this route's declared dependency graphs.
-All middleware receive that route's approved bindings, so review the whole chain;
-source changes invalidate grants. See [security](FUNCTION-SECURITY.md).
+The whole chain and handler run as one unit, in one execution mode, chosen by
+the route's `sandbox` field — not a per-middleware-entry choice. By default
+(`sandbox` false/absent) that means trusted, in-process execution with full
+Node access and no fixed worker-pool ceiling. With `sandbox: true` it means
+one fresh QuickJS/WASM guest with one memory budget and one deadline: no
+Node, filesystem, shell, fetch or ambient environment, and modules limited to
+this route's declared dependency graph. Either way, all middleware on a route
+receive that route's approved bindings, so review the whole chain; source
+changes invalidate grants. See [trust model and sandbox opt-in](FUNCTION-SECURITY.md).
 
-Invalid responses and repeated `next()` calls fail with 502, exhausted capacity
-returns 503, and the shared deadline returns 504. Middleware cannot extend the
-deadline or catch the outer worker termination. Forgotten downstream work is
-still drained within that deadline.
+Invalid responses and repeated `next()` calls fail with 502, and the deadline
+returns 504 either way. A `sandbox: true` chain also sheds load with 503 when
+the shared worker pool is exhausted, and cannot extend the deadline or catch
+the outer worker termination; forgotten downstream work is still drained
+within it. A trusted chain has no worker pool to exhaust (see
+[capacity](CAPACITY.md)), but its deadline is a race against the call's own
+promise rather than a forced kill — it cannot preempt code that blocks the
+event loop synchronously.
 
 Include explicit request fixtures for middleware-wrapped routes: test success,
 early responses, validation failures and every configured method. Audit will
 report missing coverage instead of assuming native handler behavior. Benchmark
-with middleware enabled to measure its actual sandbox overhead.
+with middleware enabled to measure its actual overhead, sandboxed or trusted.

package/docs/MONITORING.md

@@ -19,7 +19,7 @@ analytics from these logs, and adding it would mean logging user data. See
 | Endpoint | Meaning | Alert when |
 |---|---|---|
 | `GET /_urlcode/health` | The process is alive and not shutting down. | It fails at all (`UrlcodeDown`). |
-| `GET /_urlcode/ready` | The active snapshot, every function worker and every configured link-store reader are available. | It fails for longer than replacement takes (`UrlcodeNotReady`). |
+| `GET /_urlcode/ready` | The active snapshot and every function worker are available. | It fails for longer than replacement takes (`UrlcodeNotReady`). |
 
 Both return `{status, version, routes}`. A third endpoint,
 `GET /_urlcode/metrics`, exists only with `startServer({ metrics: true })` and
@@ -38,27 +38,10 @@ configuration digest and route count, so keep them internal.
 | `reload` | `status` (`ok`/`rejected`); `version` and `routes` on `ok` | A `rejected` reload means the last-good snapshot is still serving and a deploy did not take effect. |
 | `watch` | `status` | Development watcher failure; not used by `serve`. |
 | `function_worker` | `status` (`started`/`restarting`), `slot`; `attempt` and `delayMs` on `restarting` | Sustained `restarting` means a function is failing on real traffic. |
-| `link_store_worker` | `status`, `readOnly`, `attempt`, `delayMs` | The same signal for link-store connections. `status: "restarting"` reports an automatic replacement with its backoff; sustained restarts mean the underlying fault is not recoverable. |
-| `link_observer` | `status` (`failed`/`dropped`/`closed`); `reason` on `failed`; `dropped` on `dropped`; the delivery totals on `closed` | Only when an operator enables `linkEvents`. The link event channel below could not keep up or its collector failed. `dropped` means click records were discarded; like `logs_dropped`, anything built on that channel is incomplete while it fires. |
 | `logs_dropped` | `count` | The logger shed records because the collector fell behind. Every other signal is unreliable while this fires. |
 | `observer` | `status` (`failed`), `name` | An in-process observer threw; the request was unaffected. Written to the log only, never to observers. Sustained failures mean the observer's own sink is broken. |
 | `throttle`, `agents`, `cache` | `route`, `outcome`; `remaining` or `list` | Policy decisions; see [policies](POLICIES.md). `throttle` logs `allowed` only in report mode. |
 | `site` | `key`, `path`, `status` (`generated`/`shadowed`); or `severity` (`info`/`warning`) and `message` | Activation records for [site conventions](SITE.md). `shadowed` means a declared route took the path; an `info`/`warning` line reports an omitted `Sitemap:` line (no `--origin`), skipped list names or a far-future `security.txt` expiry. |
-| `management_request` | `timestamp`, `requestId`, `collection`, `action`, `authenticated`, `principal`, `status`, `outcome`, `durationMs` | Operator activity on the link-management API. `status` 0 means no response headers were sent before the peer disconnected; such a request may still have committed a mutation. |
-
-### The link event channel
-
-`link_request` is **not** a stdout record. It is delivered to an `observe()`
-function the embedding operator process supplies, after the response is over, so
-it can never change, delay or fail a redirect. It carries `requestId`,
-`collection`, `route`, `method`, `status`, `outcome`
-(`completed`/`aborted`/`missing`/`disabled`/`expired`/`invalid_code`/`invalid_record`/`unavailable`)
-and `durationMs`. The short code is redacted unless `includeCode` is set, because
-a code identifies the link somebody followed.
-
-The queue is bounded: under overload it drops events and reports the count
-through `link_observer` rather than growing memory. Alert on those drops if you
-count clicks — a quiet channel and a dropping channel look identical downstream.
 
 Startup prints `listening` with the effective `origin`, which is what functions
 and absolute URLs see. Behind a proxy or tunnel this must be your public origin;
@@ -69,7 +52,7 @@ forwarded headers are deliberately not trusted. See [tunnels](TUNNELS.md).
 `startServer({ metrics: true })` serves `GET /_urlcode/metrics` in Prometheus
 text format: requests by status class and by configured route, in-flight
 gauges, shed 503s, reloads, worker restarts and healthy slots, policy
-outcomes, link outcomes, dropped logs and observer errors, all prefixed
+outcomes, dropped logs and observer errors, all prefixed
 `urlcode_`. The same numbers are available in process as `app.metrics()`. The
 endpoint shares the probes' admission budget and bind host and is off by
 default; it discloses route patterns and traffic shape, so keep it internal

package/docs/NEXT-PHASE-PLAN.md

@@ -5,6 +5,13 @@ the capability catalog; the subsequent source work implements the bounded
 Phase B–D features below. This describes the source additions after `0.3.0` that ship in
 `0.4.0-alpha.1`, not a claim that provider deployments have been verified.
 
+> **Update:** this document describes the `0.4.0-alpha.1` source work as it
+> stood on 2026-09-17, when every `function`/`middleware` route was sandboxed.
+> The default changed in `0.4.0-alpha.2`: those routes now run trusted and
+> unsandboxed in the host process unless the route declares `sandbox: true`,
+> which gives it exactly the QuickJS/WASM execution described below. See
+> [SPIKE-DEFAULT-TRUST-MODEL.md](SPIKE-DEFAULT-TRUST-MODEL.md).
+
 ## Implementation and evidence
 
 | Phase | Implemented source | Evidence and remaining limits |
@@ -36,10 +43,11 @@ binding resolution and activation and distinguishes implementation support from
 actual deployment evidence. Unknown or unsupported targets fail closed.
 
 Project YAML describes route behavior. Provider infrastructure and outbound
-origin grants stay in operator configuration. Functions remain untrusted
-QuickJS/WASM guests with no host-code fallback. Existing explicit external
-bindings and new egress grants remain pinned to the exact configuration/source
-revision. Compilation and conversion do not resolve credentials or manufacture
+origin grants stay in operator configuration. Through `0.4.0-alpha.1`,
+functions remained untrusted QuickJS/WASM guests with no host-code fallback
+(see the update note above). <!-- trust-model-prose: historical -->
+Existing explicit external bindings and new egress grants remain pinned to the
+exact configuration/source revision. Compilation and conversion do not resolve credentials or manufacture
 grants. File authors publish new projects without overwriting unrelated work.
 
 The five policy modules remain the authority for their target-sensitive

package/docs/NEXT-STEPS.md

@@ -24,14 +24,41 @@ maintain?) and the evidence test (measured repetition, not a feature list).
 The order below follows from that. **Prove the thesis before building on
 it.** Phase 0 is the benchmark; if it shows a large saving, the rest is worth
 the work, and if it shows a small one, the abstraction is not doing enough yet
-and the next phases change. Nothing here weakens the security model: guest
-code stays untrusted, grants stay operator-owned, agents cannot self-authorize,
-unsupported behavior fails with the route named, and inspection tooling never
-becomes a privilege escalation path.
+and the next phases change. Nothing here weakens the security model: a
+`sandbox: true` route's isolation stays exactly as strict, grants stay
+operator-owned regardless of a route's trust setting, agents cannot
+self-authorize, unsupported behavior fails with the route named, and
+inspection tooling never becomes a privilege escalation path.
+
+**Status 2026-09-19 (sequence).** Most of Phases 1, 3 and 4 landed before the
+Phase 0 benchmark produced a single model-backed run. The instrument is built
+and tested (`benchmarks/agent/harness.ts`, `benchmarks/agent/count-lines.ts`,
+`benchmarks/agent/adapters/anthropic.ts`), but `benchmarks/agent/runs/` holds
+only `baseline.json`, a stub record, so the application-specific code ratio is
+still unmeasured and the re-prioritization 0.1 describes has never been
+exercised. This is an observation about the order the work happened in, not a
+change of priorities: Phase 0 still owns the evidence, and Phase 5 is still how
+each shipped phase gets measured. Items below are marked from the source at this
+revision.
 
 ## Phase 0: prove the thesis (M, core `benchmarks/agent/`, before anything else)
 
-### 0.1 The agent benchmark
+### 0.1 The agent benchmark — partly done
+
+Done 2026-09-19, the instrument only: the runner, the counting rule, the tasks
+and the storage format exist and are tested — `benchmarks/agent/harness.ts`
+(`runArm`, `summarize`, `securityChecklist`, `writeRun`),
+`benchmarks/agent/count-lines.ts` (`classify`, `codeRatio`),
+`benchmarks/agent/adapters.ts` (`selectAdapter`, `stubAdapter`) with
+`benchmarks/agent/adapters/anthropic.ts`, ten task directories under
+`benchmarks/agent/tasks/`, both arm preambles under `benchmarks/agent/prompts/`,
+`npm run benchmark:agent`, and `test/agent-benchmark.test.ts` ("the counting
+rule: functions and declared modules are the idea, everything else is
+plumbing"). The measurement is not done: `benchmarks/agent/runs/` holds only
+`baseline.json`, whose `model` is `stub`, and `benchmarks/agent/README.md`
+states that no number there is evidence until a stored run with a real model
+adapter backs it. Running the tasks in both arms against a real model, storing
+the runs and publishing only what they support remains the work below.
 
 Fixes: there is no evidence that URLCode saves agent effort, and the whole
 plan depends on it.
@@ -61,7 +88,16 @@ plan depends on it.
   too small or too hard to discover, and Phases 1, 3 and 4 are re-prioritized
   from what the runs show the agent still had to write.
 
-### 0.2 Authoring regression evals (S, once 0.1 exists)
+### 0.2 Authoring regression evals (S, once 0.1 exists) — done
+
+Done 2026-09-19: the five prompts are `benchmarks/agent/evals/*.yaml`
+(`add-redirect`, `add-authenticated-endpoint`, `serve-directory`,
+`add-middleware`, `create-webhook-endpoint`), scored against the eight criteria
+by `scoreEval` and `summarizeEvals` in `benchmarks/agent/harness.ts`, gated
+against `benchmarks/agent/runs/baseline.json` by `benchmarks/agent/gate.ts`, and
+run weekly by `.github/workflows/evals.yml`. Caveat: the committed baseline is a
+stub record and the scheduled job skips cleanly when no model key is configured,
+so the recorded pass rate proves the pipeline, not a model's behavior.
 
 Prompts for common requests ("add a redirect", "add an authenticated
 endpoint", "serve this directory", "add middleware", "create a webhook
@@ -80,7 +116,17 @@ read-side tools (`inspectProject`, `validateProject`, `explainRoute`,
 Keep all of it. The gap is that an agent still has to read documents to find
 facts the runtime already knows.
 
-### 1.1 Application-level `AGENTS.md` from `urlcode init` (S, core)
+### 1.1 Application-level `AGENTS.md` from `urlcode init` (S, core) — done
+
+Done 2026-09-19: `renderAgentsGuide` in `src/agents-guide.ts` generates the file
+from the installed capability catalog, `initProject` in `src/authoring.ts`
+writes it, and `initProjectWith` in `src/init-with.ts` calls `initProject`, so
+`init --with` writes it into the project directory too; `renderMcpConfig` writes
+`.mcp.json` beside it. `test/cli.test.ts` asserts the commands, the packaged
+skill path and the MCP tool names the file lists, its length bound, and that the
+committed `starters/default/AGENTS.md` equals what `init` generates from this
+runtime. Caveat: the public `urlcode-template` copy is outside this repository
+and is not checked here; `npm run check:downstream-skills` stays advisory.
 
 Fixes: a project made with URLCode is not self-describing to Claude Code,
 Codex or any repository-aware agent. Today's `AGENTS.md` explains how to work
@@ -97,14 +143,22 @@ on the runtime, not on an application.
 - Proof: starter test asserts the file exists and lists the commands; the
   public `urlcode-template` gets the same file.
 
-### 1.2 `llms-full.txt` and clean Markdown for the docs site (S, core; S, urlcode-docs)
+### 1.2 `llms-full.txt` and clean Markdown for the docs site (S, core; S, urlcode-docs) — partly done
+
+Done 2026-09-19, the core side: `scripts/build-llms-full.ts` generates
+`llms-full.txt` from 15 authoring documents in reading order with a table of
+contents and a token estimate in the file header, `npm run check` runs it with
+`--check`, and `test/llms-full.test.ts` covers determinism, rejection of a stale
+copy and the conservative link rewriting. The docs-site half is not done here:
+serving `/docs/<page>.md` beside `/docs/<page>` belongs to `urlcode-docs` and is
+not verifiable from this repository.
 
 Fixes: `llms.txt` must stay a compact index, but an agent that wants complete
 context has to fetch forty files.
 
 - Work: `scripts/build-llms-full.ts` concatenates the authoring documents
   (framework, AI authoring, YAML guide, field reference, specification,
-  routing, HTTP, middleware, assets, dynamic links, policies, extensions) in
+  routing, HTTP, middleware, assets, policies, extensions) in
   reading order with a table of contents; checked in `npm run check` for
   staleness like the field reference. The docs site serves `/docs/<page>.md`
   beside `/docs/<page>` so agents never parse HTML. Do not adopt `agents.txt`
@@ -112,7 +166,16 @@ context has to fetch forty files.
 - Proof: `npm run check` fails on a stale `llms-full.txt`; token estimate
   recorded in the file header.
 
-### 1.3 `urlcode context` with a token budget (M, core)
+### 1.3 `urlcode context` with a token budget (M, core) — done
+
+Done 2026-09-19: `urlcode context [--project] [--budget] [--json] [--stats]` in
+`src/cli.ts` over `buildContext`, `renderContext`, `estimateTokens` and
+`documentationTokens` in `src/context.ts`, derived from the compiled project and
+the capability catalog; `--stats` writes the estimate to stderr so stdout stays
+parseable. `test/context.test.ts` covers the cookbook and starter summaries,
+byte-identical output across runs, the fixed budget drop order with the estimate
+never exceeded, the CLI's YAML and JSON forms, and MCP `get_context`
+(`src/mcp.ts`) returning the same data read-only.
 
 Fixes: the central gap. An agent needs a handful of facts about this project
 and this runtime and spends tens of thousands of tokens reading documentation
@@ -136,7 +199,17 @@ to get them.
   same project yields byte-identical output twice; budget test that output
   never exceeds the estimate; MCP tool `get_context` returns the same data.
 
-### 1.4 Capability and schema fragment queries (M, core)
+### 1.4 Capability and schema fragment queries (M, core) — done
+
+Done 2026-09-19: `urlcode capabilities <name>` and `urlcode schema <path>` in
+`src/cli.ts` over `getCapability` in `src/capability-query.ts` and
+`getSchemaFragment`/`schemaPathNames` in `src/schema-query.ts`, both re-exported
+from `src/tooling.ts` and served as MCP `get_capability` and `get_schema`
+(`src/mcp.ts`). `test/capability-query.test.ts` asserts that every catalog name
+resolves with a valid, size-bounded fragment, that every schema path yields a
+valid inline fragment and an unknown path lists the valid names, that entries
+report bundled usage, grants and refusals from existing data, and that the CLI
+fails closed on unknown names.
 
 Fixes: `urlcode capabilities` reports target support per handler; an agent
 cannot ask "what does `throttle` accept, where does it run, which recipe
@@ -152,7 +225,15 @@ shows it" or "give me only the schema for `redirect`".
 - Proof: a test that every capability name resolves and every fragment is
   valid JSON Schema; a size test that no fragment exceeds a fixed byte cap.
 
-### 1.5 The URLCode agent skill (S, core `skills/urlcode/`)
+### 1.5 The URLCode agent skill (S, core `skills/urlcode/`) — done
+
+Done 2026-09-19: `skills/urlcode/SKILL.md` is 104 lines, ships in the package,
+and is named by the generated `AGENTS.md` through `skillPath` in
+`src/agents-guide.ts`; `test/cli.test.ts` asserts the reference and
+`test/release.test.ts` asserts the packaged starter copy. Caveat: the
+with-and-without comparison in the proof line waits on 0.1 — the URLCode arm
+preamble (`benchmarks/agent/prompts/urlcode.md`) assumes the skill, and no model
+run has been stored to compare against.
 
 Fixes: agents that support skills have no packaged instruction for URLCode.
 
@@ -170,7 +251,7 @@ Fixes: agents that support skills have no packaged instruction for URLCode.
 ### 2.1 Publish the three extension packages (decision, S) — done
 
 Done 2026-09-18: `@jimhoyd/urlcode-ui`, `-auth` and `-admin` are on npm as
-`0.1.0-alpha.1` against core `0.4.0-alpha.1`. The alpha caveat stays: source
+`0.1.0-alpha.x` against core `0.4.0-alpha.1`. The alpha caveat stays: source
 complete, independent review, deployment evidence and accessibility
 assessment pending ([issue 58](https://github.com/jimhoyd-com/urlcode/issues/58)).
 
@@ -198,9 +279,22 @@ Fixes: three disagreeing lists of verified peer commits (the CI workflows,
 - Work: `peers.json` in auth and admin; the workflows read it; the pack
   script defaults from it; `ACCEPTANCE.md` links to it. 2.1 has shipped, so
   the published versions (`@jimhoyd/urlcode@0.4.0-alpha.1`,
-  `@jimhoyd/urlcode-ui@0.1.0-alpha.1`) replace the SHAs and the file can go.
-
-### 2.3 `urlcode init --with auth,admin,ui` (M, core plus each extension)
+  `@jimhoyd/urlcode-ui@0.1.0-alpha.4`) replace the SHAs and the file can go.
+
+### 2.3 `urlcode init --with auth,admin,ui` (M, core plus each extension) — done
+
+Done 2026-09-19: `--with` is parsed in `src/cli.ts` and implemented by
+`parseWithNames`, `loadScaffold` and `initProjectWith` in `src/init-with.ts`,
+which resolves `@jimhoyd/urlcode-<name>` from the invoking directory, refuses a
+missing package or one without a `scaffold` export before writing anything,
+merges the fragments into the starter through a last include, and writes one
+`host.mjs` (`renderHost`), one `README.md` (`renderReadme`), `.mcp.json` and the
+`AGENTS.md` from 1.1, printing the `inspectExtensionRevision` digest for
+pinning. `test/init-with.test.ts` uses a fake `@jimhoyd/urlcode-<name>` package
+in a temporary `node_modules` and, when companion checkouts are present,
+composes the real auth and admin scaffolds. Caveat: each extension's own
+`scaffold` export and admin's clean-project acceptance live in those
+repositories and are not verified here.
 
 Fixes: three initializers with three directory conventions; no single command
 produces the layered project the framework page describes.
@@ -217,7 +311,20 @@ produces the layered project the framework page describes.
   `node_modules`; each extension tests that its `scaffold` output validates
   with core; admin's clean-project acceptance uses the new command.
 
-### 2.4 Print extension schemas: `urlcode extensions` (M, core)
+### 2.4 Print extension schemas: `urlcode extensions` (M, core) — partly done
+
+Done 2026-09-19, the command and the MCP tool: `urlcode extensions
+[--host-file] [--json]` in `src/cli.ts` over `describeExtensions` in
+`src/tooling.ts` prints each registration's name, version, targets,
+configuration schema, policy schema, mounts, policy routes and revision-pin
+verdict, and without a host file names the declared extensions and says schemas
+need one. The same function is exported from `src/index.ts` and served as MCP
+`get_extensions`, offered only when the operator started the server with a host
+file, which `test/extensions.test.ts` asserts against the
+`examples/extensions` registry. Not done: the fold-in. `urlcode context
+--host-file` reports host extension names and a plugin count rather than their
+schemas (`buildContext` in `src/context.ts`), and `urlcode capabilities auth`
+takes no host file, so registered contracts are not part of either view.
 
 Fixes: an agent cannot discover what `extensions.auth.config` accepts without
 reading auth's source; `urlcode mcp` cannot serve it.
@@ -231,7 +338,21 @@ reading auth's source; `urlcode mcp` cannot serve it.
 
 ## Phase 3: retrieval instead of reading (M each, core)
 
-### 3.1 Recipes as the vocabulary of common behavior
+### 3.1 Recipes as the vocabulary of common behavior — done
+
+Done 2026-09-19: every bundled recipe carries `recipe.yaml`, and the catalog is
+now ten — `authenticated-json-api`, `contact-form`, `cors-api`, `health-page`,
+`json-api`, `middleware`, `protected-download`, `static-plus-api`, `typescript`
+and `webhook-receiver` — which covers the seven this item names.
+`urlcode recipes search|show|add` runs through `src/ecosystem-cli.ts` over
+`searchRecipes` and `showRecipe` in `src/recipes.ts`, matching id, description,
+tags and capabilities locally with no service, and MCP gained `search_recipes`.
+`npm run check` validates the metadata and requires its derived fields to equal
+the capability preflight (`checkCatalog` and `derivedDifferences` in
+`scripts/check.ts`), and `test/recipes.test.ts` asserts a search hit per recipe
+and that every recipe validates, passes its fixtures and audits with its
+declared route count. Growing the catalog from the Phase 6 repetition log has
+not started; the current ten are the seed list above.
 
 Fixes: four bundled recipes with a README each and no metadata; an agent
 cannot search them, and nothing tells it to look before generating.
@@ -248,14 +369,33 @@ cannot search them, and nothing tells it to look before generating.
 - Proof: schema for `recipe.yaml` checked in `npm run check`; a search test
   per recipe; every recipe still validates, tests and audits.
 
-### 3.2 Examples become searchable the same way
+### 3.2 Examples become searchable the same way — done
+
+Done 2026-09-19: each example carries `example.yaml` in the recipe metadata
+shape, `urlcode examples search <text>` runs through `src/ecosystem-cli.ts` over
+`searchExamples` in `src/examples.ts` and names the smallest runnable match with
+its route, and the cookbook's per-route tags are generated into
+`examples/cookbook/route-index.json` by `scripts/build-cookbook-index.ts`,
+checked by `npm run check`. `scripts/check.ts` holds example metadata to the
+same preflight as recipes, and `test/recipes.test.ts` ("examples carry the same
+metadata shape and search returns the smallest runnable match with its route")
+is the search test.
 
 - Work: `examples/*/example.yaml` with the same metadata shape; `urlcode
   examples search <text>` returns the smallest matching runnable example and
   its route. The cookbook's forty routes get per-route tags in one index file.
 - Proof: search test; count audit unchanged.
 
-### 3.3 `urlcode explain` from compiled semantics
+### 3.3 `urlcode explain` from compiled semantics — done
+
+Done 2026-09-19: `urlcode explain [/route] [--json]` in `src/cli.ts` over
+`runExplainCommand` in `src/explain-cli.ts` and `explainRoute`/`explainProject`
+in `src/explain.ts`, derived from the compiled IR, including extension policy
+requirements when a host file is supplied. `test/explain.test.ts` covers the
+project table and route detail through the CLI, the sandbox boolean, the
+extension-protected route with a host registry, the nearest-route miss that
+never carries binding values, and that explain agrees with the runtime on
+methods and policies for every route.
 
 Fixes: `explainRoute` exists in the SDK and MCP; there is no CLI, and the
 output repeats matching rather than effective behavior.
@@ -268,7 +408,15 @@ output repeats matching rather than effective behavior.
 - Proof: snapshot tests on the cookbook; a test that `explain` and the
   runtime agree on methods and policies for every route.
 
-### 3.4 A generated semantic manifest
+### 3.4 A generated semantic manifest — done
+
+Done 2026-09-19: `urlcode manifest [--json]` shares the `src/explain-cli.ts`
+entry and runs `buildManifest` in `src/manifest.ts`; `build` writes
+`manifest.json` beside the artifact and MCP offers `get_manifest`.
+`test/manifest.test.ts` asserts determinism, that the revision equals the
+extension revision digest, that external requirements and recipe provenance are
+listed by name and never by value, and that the CLI prints the bytes the build
+writes.
 
 - Work: `urlcode manifest [--json]` (also written by `build` and offered by
   MCP as `get_manifest`) emits routes, capabilities, recipe provenance,
@@ -278,7 +426,17 @@ output repeats matching rather than effective behavior.
 - Proof: manifest equals `inspectProject` output for the same project;
   digest equals `inspectExtensionRevision`.
 
-### 3.5 MCP authoring layer, separately authorized (M, core)
+### 3.5 MCP authoring layer, separately authorized (M, core) — done
+
+Done 2026-09-19: `src/mcp-authoring.ts` adds `create_route`, `add_recipe` and
+`scaffold_feature` plus the `run_validate`, `run_test` and `run_audit` runners,
+enabled only by `--allow-authoring` on the operator's command line, which
+`src/cli.ts` refuses for any other command and which no tool argument or
+environment variable can set (`src/mcp.ts`). Every write is validated before it
+lands and returns the verdict. `test/mcp-authoring.test.ts` asserts the tools
+are absent without the flag, that absolute, parent, symlinked, dotenv, git and
+operator paths are refused, and that a create is followed by validation in one
+call.
 
 Fixes: MCP is read-only by design; an agent that wants to add a recipe or a
 route still has to write files by hand.
@@ -297,7 +455,20 @@ route still has to write files by hand.
 
 ## Phase 4: fewer lines for the common case (schema additions, `version: "1"` stays valid)
 
-### 4.1 Short form for function routes (M, core)
+### 4.1 Short form for function routes (M, core) — done
+
+Done 2026-09-19: `normalizeRoute` in `src/config.ts` expands
+`function: functions/x.mjs` into `{source, args}` with an argument per `{param}`
+and a required bounded path parameter for any the route does not declare itself
+(`SHORT_FORM_PATH_SCHEMA`), and a string `middleware` entry into `{source}`; the
+long form stays the IR. Both shapes are in
+`schemas/urlcode.schema.json` (`$defs.route.properties.function` and
+`.middleware`) and the generated field reference lists them as options.
+`test/config.test.ts` ("function and middleware short forms normalize to the
+long form the long form compiles to") asserts identical output, that a declared
+parameter keeps its schema, and that a bad short-form string is refused with the
+route named; the cookbook uses the short form in
+`examples/cookbook/routes/middleware.yaml`.
 
 Fixes: the smallest function route is ten lines.
 
@@ -308,7 +479,21 @@ Fixes: the smallest function route is ten lines.
 - Proof: generated reference updated; cookbook gains a short-form route with
   fixtures; a test that short and long forms compile to identical IR.
 
-### 4.2 Route-level `auth` as the semantic form (M, core plus auth)
+### 4.2 Route-level `auth` as the semantic form (M, core plus auth) — done
+
+Done 2026-09-19: the route-level `auth` key is in the schema
+(`$defs.route.properties.auth` over `$defs.routeAuth` in
+`schemas/urlcode.schema.json`) and expanded by `normalizeRouteAuth` in
+`src/config.ts`, which refuses a route that declares `auth` without an
+`extensions.auth` declaration, alongside `policies.extensions.auth`, or with
+`policies.extensions: false`; `required: false` documents intent and emits
+nothing. The type is documented in `src/types.ts`, and `test/recipes.test.ts`
+("the authenticated recipes use the auth short form and never let credentials
+reach the guest") covers both `auth: true` and a role requirement. The `cache`
+short form this item defers to later shipped with it:
+`$defs.route.properties.cache` and the cache branch of `normalizeRoute`, refused
+alongside `policies.cache`. Caveat: the auth repository's HTTP tests are outside
+this repository and were not run here.
 
 Fixes: protecting a route today is `policies: { extensions: { auth: {} } }`,
 which is the mechanism, not the intent. The form an agent should write is
@@ -365,7 +550,15 @@ whether links become a collection. Decide after review; build nothing first.
 `hiddenField`, `postForm`, `withDeadline` in the ui main entry; auth and
 admin drop their copies (`admin-markup.ts`, `admin-deadline.ts`).
 
-### 7.2 Auth and admin render through the kit (L)
+### 7.2 Auth and admin render through the kit (L) — partly done
+
+Done 2026-09-19, the core prerequisite only: the immutable-cache exception for
+hashed extension assets shipped. `ExtensionImmutableAssets` and
+`validateAssetPrefix` in `src/extensions.ts` bound a declared prefix to literal
+segments under the extension's mounts, and `immutableAssetResponse` is what
+lets such a response carry an asset cache-control instead of `no-store`. The
+rendering work itself is in the auth, admin and ui repositories and is not
+verified from here.
 
 Auth exports its catalogue and templates with view models, takes an optional
 `ui` from the host, and renders with `ui.kit.page` when present; admin the
@@ -388,28 +581,54 @@ walkthrough. Retire the `presentation` option one minor version later.
 ## Phase 9: hardening left from the audit (core, S each)
 
 - Direct tests for the sandbox pool, worker crash recovery and timeout kill
-  path (`src/functions.ts`, `src/function-worker.ts`, `src/guest-api.ts`).
-- Tests for `src/link-store-worker.ts` behind the WAL gate.
-- Re-verify the remaining line-number rows in `STANDARDS.md`; cite symbols.
-- Split the three longest reference documents (YAML guide, policies, dynamic
-  links) into task pages under 200 lines, so retrieval returns one page.
+  path (`src/functions.ts`, `src/function-worker.ts`, `src/guest-api.ts`) —
+  done 2026-09-19: `test/sandbox-pool.test.ts` covers load shedding with slot
+  reuse, parallel workers with per-slot heaps, the 250 ms-to-30 s respawn
+  backoff, the deadline kill with slot replacement, an abrupt worker exit
+  failing the in-flight invocation, startup failure and close, and the guest
+  `Request`/`Response`/context surface.
+- Re-verify the remaining line-number rows in `STANDARDS.md`; cite symbols —
+  done 2026-09-19: `docs/STANDARDS.md` records that every row was re-verified
+  at `8d7dd01` and now cites the implementing function or constant rather than
+  a line number, names the test that proves it, and says "unverified at
+  8d7dd01" where a row could not be re-checked; no line-number citation
+  remains in the file.
+- Split the longest reference documents (YAML guide, policies) into task pages
+  under 200 lines, so retrieval returns one page — done 2026-09-19:
+  `docs/yaml/` holds nine pages (largest `functions.md`, 160 lines) and
+  `docs/policies/` nine (largest `agents.md`, 182 lines), with
+  `docs/YAML-GUIDE.md` down to 57 lines. Caveat: `docs/POLICIES.md` is still
+  203 lines as the index page.
 - A pre-test check in the extension repos that fails fast with the SQLite
-  requirement named.
+  requirement named. Not verifiable from this repository.
 
 ## Sequence at a glance
 
+What remains, as of 2026-09-19:
+
 ```
-Phase 0  agent benchmark + code-ratio metric        (decides everything after it)
-Phase 1  AGENTS.md from init → llms-full → urlcode context → capability/schema queries → skill
-Phase 2  publish alphas → peers.json → init --with → extensions --schema
-Phase 3  recipe metadata + search → examples search → explain → manifest → MCP authoring
-Phase 4  short-form function route → route-level auth
-Phase 5  re-run the benchmark after each phase
-Phase 6  repetition log → collections spike, then decide
-Phase 7  shared helpers → kit adoption
+Phase 0  instrument built and tested; no model-backed run stored, so the
+         code-ratio evidence is still missing. Evals (0.2) run weekly.
+Phase 1  done: AGENTS.md from init, llms-full, urlcode context,
+         capability/schema queries, the skill
+         left: the docs site's /docs/<page>.md (urlcode-docs)
+Phase 2  done: published alphas, init --with, urlcode extensions + get_extensions
+         left: peers.json (auth, admin); extension schemas folded into
+         urlcode context and capabilities <name>
+Phase 3  done: recipe metadata + search, examples search, explain, manifest,
+         MCP authoring behind --allow-authoring
+Phase 4  done: short-form function and middleware routes, route-level auth,
+         the cache short form; 4.3 stays a standing rule for new fields
+Phase 5  waits on a Phase 0 run with a real model
+Phase 6  not started: no docs/REPETITION-LOG.md, no docs/SPIKE-COLLECTIONS.md
+Phase 7  extension repos; the core immutable-asset exception 7.2 needs is done
 Phase 8  proof gaps, in parallel, as people and environments allow
-Phase 9  hardening, in any gap
+Phase 9  done: sandbox pool tests, STANDARDS symbol citations, split reference
+         pages; left: the extension repos' SQLite pre-test check
 ```
 
 Phase 0 decides whether the rest is worth doing and in what order. Phases 1
 and 3 are what an agent meets first; the rest makes that cheaper or proves it.
+Because Phases 1, 3 and 4 landed ahead of the first model-backed run, that run
+now measures what shipped rather than choosing it; Phase 5's re-runs are where
+the choosing role returns.