@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.2

package/docs/SPIKE-DEFAULT-TRUST-MODEL.md

@@ -174,19 +174,15 @@ with `add_repo` before treating it as settled.
   settles this explicitly: a hook a project names in an extension's own YAML
   config (`urlcode-auth`'s `onSignUp`/`beforeRegister`/`onDelete` and the
   like) is first-party project code in the same category as any
-  `function`/`middleware` route, trusted and in-process by default, with the
-  same per-hook `sandbox: true` opt-in. No hardwired always-sandboxed case
-  for lifecycle hooks specifically. Trusted execution of such a hook needs no
-  core primitive — an extension's own `activate()` already has
-  `ExtensionActivation.root` and can `import()` the project's module
-  directly. The isolated half of that opt-in previously had no equivalent:
-  core's trusted/sandboxed dispatch was wired to route dispatch only, not
-  exposed to extensions. `@jimhoyd/urlcode/sandbox`'s `SandboxPool` (see
-  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md), [TYPESCRIPT.md](TYPESCRIPT.md))
-  closes that: the same worker/QuickJS engine `FunctionPool` already used for
-  route dispatch, generalized to explicit `{source, export}` entries/targets
-  instead of `FunctionRoute`, with no second engine and no "trusted" mode
-  exported alongside it.
+  `function`/`middleware` route and runs trusted and in-process. Core now owns
+  the shared extension-hook primitive: it validates hook references, imports
+  them during activation, enforces the extension-published input/output JSON
+  Schemas, reports those contracts to authoring tools, and includes hook entry
+  files in the project revision. Hook sandboxing is not part of this first
+  contract; `sandbox: true` is rejected during activation instead of silently
+  running trusted. A later sandbox contract must define its serialization and
+  capability boundary before it can reuse the worker/QuickJS path described in
+  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md).
 
 ## Recommended sequencing
 

package/docs/STARTERS.md

@@ -36,18 +36,30 @@ on every push and pull request once the project is on GitHub.
 See [organization](ORGANIZATION.md) for choosing your own layout. Defaults allow
 GET/HEAD and use redirect 302; add configuration only when changing behavior.
 
+`urlcode init` writes no `package.json`: the route project is route-only, and its
+runtime may be installed globally, in a parent workspace or in a container. Add
+`--manifest` to also write one pinning the runtime at exactly the version that
+generated the project, then run `npm install` in it yourself to install that
+version and produce a lockfile. The CLI never runs a package manager, and no
+upgrade command exists — a pinned version changes when you edit the manifest.
+
 Initialization refuses an existing destination. Own the app in your own repository,
 keep secrets out of Git, and upgrade the runtime separately without regenerating
 application files. Add pages, downloads, more functions and business-specific
 features to this same project. Update tests and the expected route count as it grows.
 See [readiness](READINESS.md) and [security](FUNCTION-SECURITY.md).
 
-To start an extended site instead, install the extension packages from npm
-(`npm install @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin`, published as
-`0.1.0-alpha.x` prereleases) in the directory you run from and pass their names: `urlcode init ../my-site --with
-auth,admin` writes the same starter under `my-site/app/`, merges each package's
+To start an extended site instead, install the compatible core, UI, auth and
+admin set from npm in the directory you run from; the
+[framework guide](FRAMEWORK.md#the-composition-contract) provides the exact
+`0.4.1` command to use after publication. Pass UI first so its kit activates
+before auth: `urlcode init ../my-site --with ui,auth,admin` writes the same starter under `my-site/app/`, merges each package's
 routes and declarations into it, and generates one `host.mjs` and README beside
-it. The contract each package fulfils is in [extensions](EXTENSIONS.md#scaffolding-with-init---with).
+it, plus a `package.json` pinning the runtime, those packages and their declared
+peers at the versions it just resolved, validated together against every declared
+peer range. Installing them is your explicit `npm install` in that directory.
+The contract each package fulfils is in [extensions](EXTENSIONS.md#scaffolding-with-init---with),
+with `--no-manifest` and `--pin` in [recorded versions](EXTENSIONS.md#recorded-versions).
 
 Both paths carry an `AGENTS.md` for repository-aware assistants. `urlcode init`
 generates it from the installed runtime's capability catalog (the same source as

package/docs/TOOLING.md

@@ -52,7 +52,7 @@ The tooling API consolidates authoring operations without starting a runtime:
 - `listRecipes()` and `showRecipe(name)` expose the fixed bundled recipe catalog.
 - `inspectExtensions({project, hostFile?})` reports each operator-registered
   extension's name, contract version, targets, credential headers, configuration
-  and policy JSON Schemas, whether the project declares it, whether its revision
+  and policy JSON Schemas, machine-readable project hook contracts, whether the project declares it, whether its revision
   pin matches and where routes mount or require it, plus the project's declared
   names. With `hostFile` it executes that trusted operator module under the
   `--host-file` rules (absolute path, outside the project) and releases it
@@ -81,10 +81,12 @@ network. Keys always appear in this order:
   `--host-file`, `host` counts the operator module's extensions and plugins
   without activating them.
 - `routes`: path, methods and handler per route, sorted by path.
-- `constraints`: a fixed list that holds for every project (no guest network,
-  no Node APIs, no regex routes, one handler per route, exact or `{param}`
-  path segments, subtree mounts only for static and extension routes, no YAML
-  interpolation, secrets by operator grant only), each with a value and a note.
+- `constraints`: a fixed list that holds for every project (network and Node
+  built-ins available to trusted code and withdrawn by `sandbox: true`, no
+  regex routes, one handler per route, exact or `{param}` path segments,
+  subtree mounts only for static and extension routes, no YAML interpolation,
+  injected `env`/`secrets` by operator grant only), each with a value and a
+  note spelling out how it differs between the two trust modes.
 - `targets`: for each capability target (or the one `--target`), which of this
   project's used features are supported, conditional, refused or unknown.
 - `commands`: the exact `validate`, `test`, `audit --expect-routes N` (N is

package/docs/VERCEL.md

@@ -7,7 +7,8 @@ that is the point of the project format.
 **This adapter serves native handlers only:** redirects, validated responses,
 pages, static assets and downloads. `function` and `middleware` routes are
 refused at activation, trusted or sandboxed alike, not per request, so a deployment cannot
-half-work. See [what is not supported](#what-this-adapter-does-not-do).
+half-work, and that is a settled position rather than a pending limitation. See
+[what is not supported](#what-this-adapter-does-not-do).
 
 A working project is in [`examples/vercel/`](../examples/vercel/).
 
@@ -71,13 +72,20 @@ and want it in generated URLs.
 
 | Not supported | Why |
 |---|---|
-| `function` routes | They need the self-hosted Node lifecycle; a `sandbox: true` route would additionally spawn worker threads and load the WASM engine on every cold start. Correctness is not the issue; predictable latency is, and it is unmeasured. |
+| `function` routes | They need the self-hosted Node lifecycle; a `sandbox: true` route would additionally spawn worker threads and load the WASM engine on every cold start. Correctness is not the issue; the execution model is — per-route compilation was considered and declined. |
 | Middleware | Runs in the same execution mode as the route's function, and is refused with it. |
 | `urlcode serve` operational endpoints | `/_urlcode/health` and `/_urlcode/ready` describe a long-lived process. Use Vercel's own observability. |
 
 Each refusal happens at activation with a message naming the route, so you find
 out on deploy rather than on a request.
 
+`function` and `middleware` are not coming to this adapter. The supported answer
+is to deploy the project as one trusted Node process — a container or a VM
+running the project as it runs locally — which supports every route type today,
+on any host you like including AWS (ECS, EC2, App Runner). See
+[the decision](OPEN-DECISIONS.md#accepted-one-node-deployment-per-project) and
+[the analysis behind it](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md).
+
 ## Operating it
 
 Every instance activates the project independently: parsing YAML, snapshotting

package/docs/VERSION-ALIGNMENT.md

@@ -26,18 +26,60 @@ must match its manifest. `npm run release:check` rejects stale lockfile versions
 Unreleased source changes do not require moving a published tag or pretending a
 new package has already shipped.
 
+Manual GitHub Actions releases can select `core`, `ui`, `auth`, `admin`, or
+`all`. A single-package release updates only that package's manifest, lock entry,
+changelog and relevant Changesets; core also owns its duplicated CLI/MCP/plugin
+version metadata and downstream starter update. The all-packages action aligns
+every manifest and advances internal peer floors together. Changesets that name
+packages across the selected boundary must be released together rather than
+partially consumed.
+
+The `0.4.1` release is an explicit stable release decision for core, UI, auth
+and admin. Publication moves each package's npm `latest` channel to `0.4.1`, in
+core → UI → auth → admin order, after its release checks pass. A prepared
+manifest or merged release PR does not prove registry publication: use
+`npm run release:status` to inspect the live result before installing the set.
+This alignment does not permanently couple package versions; subsequent
+releases can still select only the packages that changed.
+
 Alpha releases publish under `alpha`; they never automatically move npm
-`latest`. Core's historical `latest` remains the stable 0.3.0 baseline until an
-explicit stable release decision. Extensions have historical alpha versions on
-`latest`; subsequent alpha publication does not keep that channel in lockstep.
-Different channel values alone are not drift. Test the install combination you
-recommend against peer ranges; a bare install may select an older channel.
-`release:status` reports each declared peer floor and whether its current
-`latest` and `alpha` satisfy the range.
+`latest`. Stable publication does not move `alpha`, so the two channels can
+legitimately show different versions. Test the install combination you recommend
+against peer ranges. `release:status` reports each declared peer floor and
+whether its current `latest` and `alpha` satisfy the range.
+
+After all four `0.4.1` versions are published, install the aligned set with:
+
+```sh
+npm install --save-exact @jimhoyd/urlcode@0.4.1 @jimhoyd/urlcode-ui@0.4.1 @jimhoyd/urlcode-auth@0.4.1 @jimhoyd/urlcode-admin@0.4.1
+```
+
+Bare package names resolve npm's current `latest`; exact application pins and a
+committed lockfile keep an existing application from changing on a new release.
+
+## Generated applications
+
+A generated application records its own versions. `urlcode init --with` writes a
+`package.json` pinning the running runtime, the named extensions and their
+declared peers at the exact versions resolved at generation time, after checking
+that set against every declared peer range; `urlcode init --manifest` does the
+same for a route-only project with the runtime alone; `urlcode-auth init` pins
+this package and its peers. Plain `urlcode init` stays route-only and writes no
+manifest, for projects whose runtime is managed elsewhere. Generation never runs
+a package manager: `package-lock.json` exists only after the operator runs
+`npm install` in the generated directory, and a pin taken from a local path or
+tarball reproduces only where that path exists.
+
+No upgrade command exists. A generated project moves to new versions by an
+operator editing its manifest and re-installing. The issue that asked for this
+(#212) describes a future command that would choose a tested compatible set,
+show the changes and require explicit alpha selection; nothing here implements
+that, and the pins above are only the groundwork it would need.
 
 The standalone `urlcode-template` is an external exact-version consumer: after a
 runtime release, update its dependency and starter through its own reviewed PR.
-It is not automatically released by the monorepo coordinator. The retired
+The coordinator prepares and checks that PR after registry installation succeeds;
+the template is a consumer update, not a fifth npm package. The retired
 `urlcode-docs`, `urlcode-middleware`, `urlcode-dynamic-link` and `urlcode-short`
 repositories are not release targets.
 

package/docs/archive/2026-09-19/ROADMAP.md

@@ -6,6 +6,7 @@ current instructions. See the [current roadmap](../../../ROADMAP.md),
 Remaining acceptance work is not declared complete by archiving this record.
 
 <!-- trust-model-prose: historical-file -->
+<!-- local-links: historical-file -->
 <!-- guidance-claims: ignore-file -->
 
 # Public roadmap

package/docs/archive/2026-09-19/SPIKE-EXTENSION-MODEL.md

@@ -6,6 +6,7 @@ current instructions. See the [current roadmap](../../../ROADMAP.md),
 Remaining acceptance work is not declared complete by archiving this record.
 
 <!-- trust-model-prose: historical-file -->
+<!-- local-links: historical-file -->
 <!-- guidance-claims: ignore-file -->
 
 # Review: the extension model, its precedents and its alignment

package/docs/{SPIKE-LAMBDA-COMPILE.md → archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md}

@@ -1,19 +1,39 @@
+# Historical record
+
+Archived 2026-09-19, when the proposal was **declined**. This records an earlier
+proposal, not current instructions. The decision it lost to is
+[one Node deployment per project](../../OPEN-DECISIONS.md#accepted-one-node-deployment-per-project);
+see also the [current roadmap](../../../ROADMAP.md) and
+[current contract](../../SPECIFICATION.md). Remaining acceptance work is not
+declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
 # Spike: compiling `function` routes into their own Lambdas
 
 > Review update, 2026-09-19: Current baseline: trusted Node execution is the default, so fresh invocation
 > state is a guarantee of `sandbox: true` only. AWS/Vercel still reject functions
 > and middleware in `src/capabilities.ts`; changing the default did not implement
-> a provider adapter for them. Re-evaluate the proposed per-route lowering against
-> a single trusted Node deployment per project before choosing either. Removed
-> link APIs in the analysis below are historical.
+> a provider adapter for them. The per-route lowering was weighed against a
+> single trusted Node deployment per project, and **the Node deployment was
+> chosen** (2026-09-19). Removed link APIs in the analysis below are historical.
 
 
-Status: proposal, nothing implemented. No code in this repository does any of
-this, and nothing here is committed scope.
+Status: **declined 2026-09-19 — kept as the analysis behind that decision, not
+as a plan.** Nothing here is implemented and nothing here is committed scope.
+The maintainer chose the alternative this document weighs itself against: a
+project that uses `function` or `middleware` deploys as **one trusted Node
+process**, and AWS/Vercel keep refusing those routes at activation as a
+deliberate position rather than a gap awaiting an adapter. See
+[open decisions](../../OPEN-DECISIONS.md#accepted-one-node-deployment-per-project).
+
+Read on for why, and for what a first attempt would look like if real demand for
+`function` routes on AWS serverless ever appears and reopens the question.
 
 AWS already deploys today. `createLambdaHandler` (`src/aws.ts`) runs a project
 as **one** Lambda behind a Function URL or an API Gateway HTTP API, reading the
-same `urlcode.yaml` that runs locally — see [AWS](AWS.md). What it cannot serve
+same `urlcode.yaml` that runs locally — see [AWS](../../AWS.md). What it cannot serve
 is `function`, `middleware` and `link`, which
 `activateNativeOnly` (`src/adapters.ts`) refuses for the whole deployment at
 activation rather than letting individual routes fail per request.
@@ -22,6 +42,120 @@ This spike asks one question: **is the refusal of `function` a fact about
 Lambda, or a fact about the adapter?** It argues the second, sketches the
 lowering that follows, and is deliberate about what that lowering costs.
 
+Section 0 says all of that again without the jargon; sections 1 onward are the
+argument in full.
+
+## 0. In plain terms
+
+This section is the whole spike in ordinary language. Everything after it is the
+same argument stated precisely; if the two ever disagree, the precise version
+wins.
+
+### What a `function` route is
+
+Most of a URLCode project is description, not code: "this URL redirects there",
+"this URL returns that page", "this URL serves that file". You write those in
+YAML and never write a program. A **`function` route** is the escape hatch for
+the cases YAML cannot describe — you write a small piece of JavaScript, and the
+runtime calls it when a request arrives. `middleware` is the same idea, except
+it runs on the way *to* other routes rather than answering by itself.
+
+### Where that code runs today
+
+Two ways, and the project picks per route:
+
+- **Trusted (the default).** The code runs directly in the same Node process as
+  everything else, at full speed, with the same access the process has. This is
+  the default because the person writing the route is usually the same person
+  deploying it. See [the decision](../../SPIKE-DEFAULT-TRUST-MODEL.md).
+- **Sandboxed (`sandbox: true`, opt in per route).** The code runs inside a
+  small, separate JavaScript engine (QuickJS, compiled to WebAssembly) on a
+  worker thread. Inside there it has no filesystem, no network, no environment
+  variables and a completely fresh memory space on every single call. It can
+  only reach the outside world through *bindings* an operator granted by name.
+  See [function security](../../FUNCTION-SECURITY.md).
+
+Think of the sandbox as a sealed room inside your own house. Nothing gets in or
+out except through a hatch you deliberately opened, and the room is wiped clean
+between visitors.
+
+### What happens on AWS today
+
+Nothing, for these routes. If a project contains any `function` or `middleware`
+route, the AWS adapter refuses **the entire deployment at startup** and names
+what it cannot serve. Everything else — redirects, pages, static files,
+downloads — deploys fine as a single Lambda.
+
+That refusal is not a bug or an oversight. It is the runtime declining to
+pretend. The alternative would be accepting the deployment and then failing
+individual requests in production, which is worse.
+
+### Why it refuses
+
+The sealed room is expensive to build. Every time AWS starts a fresh copy of
+your Lambda (a "cold start"), that copy would have to spin up worker threads and
+boot a WebAssembly engine *before* it could answer the first request. One
+process trying to serve every route in a project, rebuilding all that machinery
+on every cold start, is a bad trade.
+
+The key observation of this spike: that reasoning is about **one process serving
+every route**. It is not actually about AWS. Change the unit of deployment and
+the objection evaporates.
+
+### The idea
+
+Stop shipping one Lambda for the whole project. Instead, at build time, emit
+**one Lambda per `function` route** — plus the existing single Lambda for all
+the ordinary declarative routes.
+
+Then you do not need the sealed room at all, because each piece of code already
+has an entire AWS process to itself. The process *is* the wall. This is the same
+move URLCode already makes for Cloudflare: when a platform will not run what the
+adapter needs, compile the project ahead of time instead of adapting at runtime.
+
+### The catch — three of them
+
+1. **It is a different kind of safety, not more of the same safety.** A Lambda
+   is a genuinely separate box, which is good. But out of the box that box has
+   working network access, a writable temp disk, ambient environment variables,
+   and an AWS identity (an "IAM role") that can reach real infrastructure. The
+   sealed room had none of that. So swapping one for the other is a **trade**,
+   not an upgrade — and the documentation would have to say exactly which
+   guarantee changed rather than announcing "functions work on AWS now". One
+   guarantee is simply lost: the sandbox promises fresh memory on every call,
+   and AWS reuses warm containers.
+2. **URLCode would start generating security-critical infrastructure.** To keep
+   each route's permissions tight, the build would have to write out an IAM role
+   per route. A generated permissions file is not an implementation detail you
+   can wave away with "don't rely on this" — if it is too generous, it is a
+   security hole the project authored.
+3. **It would be an unverified claim wearing a capability's clothes.** Right now
+   the project's position on AWS is honest: it reports `deployment: 'unverified'`
+   and tells you to deploy the example yourself. Shipping a compiler that emits
+   cloud infrastructure nobody on the project has ever actually deployed would
+   trade an honest refusal for a bigger unproven promise.
+
+### The alternative already sitting on the table — and now chosen
+
+Run the project as **one ordinary Node deployment** — a container or a VM. That
+supports `function` and `middleware` today, with no compiler, no generated
+infrastructure and no new security surface. It costs you the serverless
+operating model: something is always running, and you scale it yourself.
+
+So the real decision is not "can this be built" — it probably can. It is:
+
+> Is there enough demand for running URLCode `function` routes specifically on
+> AWS serverless to justify this project owning an infrastructure compiler and a
+> second, weaker isolation story?
+
+**That question was answered on 2026-09-19: no.** Nobody has produced the demand
+evidence, and the plain Node deployment does the job today, so the Node
+deployment is the supported model and the compiler is not being built. The
+refusal on AWS and Vercel stays, and is now a position rather than a gap. See
+[open decisions](../../OPEN-DECISIONS.md#accepted-one-node-deployment-per-project).
+If that demand ever shows up, §6 below already scopes what a first attempt
+would be.
+
 ## 1. Where the refusal actually comes from
 
 `src/capabilities.ts` gives the reason:
@@ -32,7 +166,7 @@ capability === 'function' ? 'isolated functions need worker threads and the WASM
 
 That is true of the runtime's *own* mechanism. Isolation for guest code is
 QuickJS inside WebAssembly, driven from worker threads, with the boundaries
-[function security](FUNCTION-SECURITY.md) lists: no `process`, no filesystem,
+[function security](../../FUNCTION-SECURITY.md) lists: no `process`, no filesystem,
 no sockets, no `fetch`, a fresh guest heap per invocation, and bindings denied
 unless an operator granted them by exact name.
 
@@ -49,7 +183,7 @@ Cloudflare already establishes the pattern: where a platform forbids what the
 adapter needs, URLCode **compiles ahead of time** instead of adapting at
 runtime. `urlcode build --target cloudflare` (`src/build-cloudflare.ts`) emits
 an artifact the Worker reads, and refuses at build time anything it cannot
-serve, with the route named — see [Cloudflare](CLOUDFLARE.md).
+serve, with the route named — see [Cloudflare](../../CLOUDFLARE.md).
 
 The same move for AWS: a build step emits **one Lambda per `function` route**,
 plus the existing native-handler Lambda for everything else.
@@ -75,6 +209,9 @@ This is not a smaller change than it looks. Three things follow from it.
 
 This is the claim most likely to be made too early, so it goes first.
 
+> **Plainly:** both are real walls, but they are different walls, and neither
+> one is strictly stronger. Read the table as a trade, not a scorecard.
+
 QuickJS-WASM and a Lambda are both real isolation. They are **not the same
 isolation**, and neither strictly contains the other:
 
@@ -101,6 +238,12 @@ this project should not make.
 
 ### 3.2 `middleware` is the hard part, not `function`
 
+> **Plainly:** a `function` is a dead end — it answers and the request stops
+> there, so giving it its own Lambda is easy. Middleware is a queue of steps
+> every request walks through on its way somewhere else, and a queue split
+> across separate Lambdas has to be either copied into each one or wired up as
+> a chain of calls. Both hurt, so this spike does not attempt middleware.
+
 `function` lowers cleanly because it is a leaf. `middleware` is a per-request
 chain, and there are only two ways to lower it, both with a real cost:
 
@@ -124,6 +267,11 @@ section describes was later removed from core; see
 
 ## 4. Emitting infrastructure is a new kind of output
 
+> **Plainly:** up to now URLCode has only ever produced things that run *inside*
+> a server it was given. Emitting a CloudFormation stack means it starts
+> producing the cloud account's own configuration — including permissions — and
+> becomes responsible for that being correct as AWS changes underneath it.
+
 `examples/aws/template.yaml` is hand-written today. Generating a stack means
 this project starts owning a surface it has never owned:
 
@@ -139,7 +287,7 @@ this project starts owning a surface it has never owned:
 
 That last point is the one worth holding onto. The project's current position on
 AWS is **honest**: the capability catalog reports `deployment: 'unverified'` for
-every target that is not self-hosted, and [AWS](AWS.md) tells a reader to treat
+every target that is not self-hosted, and [AWS](../../AWS.md) tells a reader to treat
 the limits as unverified until they deploy the example themselves. A compiler
 that emits infrastructure nobody has deployed would be a larger unverified claim
 wearing the clothes of a capability.
@@ -161,7 +309,9 @@ lowering without anything else in the model changing, and `urlcode capabilities
 
 ## 6. Proposed scope for a first spike
 
-Narrow, so that the isolation story stays clean and the win is real:
+Narrow, so that the isolation story stays clean and the win is real.
+**Plainly: build the smallest version that proves the idea, and resist every
+tempting extra.**
 
 **In:** `function` routes, Function URL only, one Lambda per function route,
 a generated role per route carrying exactly that route's granted bindings,
@@ -190,13 +340,19 @@ having run it on AWS, and the spike should say so rather than imply otherwise.
 
 ## 8. Open questions
 
+These are the things a reviewer should press on. In plain terms: *is losing the
+fresh-state guarantee acceptable at all; should URLCode write the permissions or
+merely describe them; does splitting into many Lambdas quietly weaken the
+policies a project already declares; and is one Lambda per route even the right
+size of piece?*
+
 - Is warm-container reuse acceptable at all, given the runtime currently
   *guarantees* fresh per-invocation state? If not, this lowering is wrong for
   any route that relies on that guarantee, and there is no build-time way to
   tell which ones do.
 - Does the generated IAM role belong in URLCode's output, or should the build
   emit a *description* of the permissions each route needs and leave the role to
-  the operator — closer to how [function security](FUNCTION-SECURITY.md) already
+  the operator — closer to how [function security](../../FUNCTION-SECURITY.md) already
   keeps grants operator-controlled and outside the checkout?
 - Does a per-route Lambda change what `policies` can promise? `throttle` on AWS
   is already `conditional` — "counters are per instance" — and more instances
@@ -204,6 +360,6 @@ having run it on AWS, and the spike should say so rather than imply otherwise.
 - Is one Lambda per route the right granularity, or one per *project* with a
   route parameter, which keeps deployment small but reintroduces a shared
   process?
-- What happens to the 6 MB Lambda response limit ([AWS](AWS.md)) for a function
+- What happens to the 6 MB Lambda response limit ([AWS](../../AWS.md)) for a function
   route that returns a large body — refuse at build time, as the Cloudflare
   target refuses what it cannot serve?

package/docs/archive/2026-09-19/SPIKE-MONOREPO.md

@@ -1,5 +1,7 @@
 # Spike: consolidating core, auth, admin and ui into one repo
 
+<!-- local-links: historical-file -->
+
 > **Closed 2026-09-19: the migration is done, and this document is history.**
 >
 > `urlcode-ui`, `urlcode-auth` and `urlcode-admin` are workspace packages under

package/docs/archive/2026-09-20/OPEN-DECISIONS-COMPLETED.md

@@ -0,0 +1,116 @@
+# Historical record
+
+Archived 2026-09-20 from [open decisions](../../OPEN-DECISIONS.md), which was
+reconciled against its issues that day (#242). These sections record completed
+work and dated observations exactly as they stood on 2026-09-19 (core `db375bf`
+and the package sources of that date); they are not current instructions and
+their version numbers, dist-tags, commits and pins are not current. Versions
+and channels: [version alignment](../../VERSION-ALIGNMENT.md) and
+`npm run release:status`. Archiving does not declare any security, deployment,
+recovery or provider check performed. The live middleware decision remains in
+open decisions.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+<!-- local-links: historical-file -->
+
+## Closed questions removed from the active list
+
+- Publishing convention is recorded in [version alignment](../../VERSION-ALIGNMENT.md):
+  publishable manifests on main, releases through reviewed tags/workflows.
+- Core `0.4.0-alpha.2` and current extension releases exist; publishing that
+  already-shipped version is not a next step.
+- Auth/admin kit adoption and shared form helpers are implemented in their code.
+- The UI primitive fallback is retired, which settles the question this table
+  carried. Auth and admin now render every screen through the kit and refuse
+  activation without it (`packages/auth/src/auth.ts`: "there is no
+  shared-primitive fallback"), so "keep both" no longer describes the code.
+- The template pins `0.4.0-alpha.2`. Its skill differences were read against that
+  pin: omitted handlers and advice about the removed management API are stale,
+  not intentional older-version behavior.
+- The guidance checks run through `npm run check` inside `verify`; a regex check
+  is not a schema validator for every example. Extending its coverage is tracked
+  separately, not a reason to weaken review or bypass required checks.
+
+## Done: the monorepo migration is complete
+
+**Closed 2026-09-19.** `urlcode-ui`, `urlcode-auth` and `urlcode-admin` are
+workspace packages under `packages/`, and all three have been released from
+this repository — `@jimhoyd/urlcode-ui@0.1.0-alpha.6`,
+`@jimhoyd/urlcode-auth@0.1.0-alpha.6`, `@jimhoyd/urlcode-admin@0.1.0-alpha.4`,
+each on `alpha` with `latest` deliberately held behind. Core's dist-tags are
+unchanged. The three source repositories are gone; their history survives only
+as verified `git bundle`s, because the repository allows squash merges only and
+the imported commits did not survive onto `main`.
+
+The operational runbook is [DEVELOPMENT-PIPELINE.md](../../DEVELOPMENT-PIPELINE.md)
+and [RELEASE-SECURITY.md](../../RELEASE-SECURITY.md). The plan itself is archived at
+[archive/2026-09-19/SPIKE-MONOREPO.md](../2026-09-19/SPIKE-MONOREPO.md),
+whose closing note records what the plan got wrong — chiefly that its
+strongest argument, the reach of the enforcing checks, only became true after
+both checkers were changed to discover workspace packages.
+
+The section below is kept for the middleware decision it records, which is
+still the reason there is no `packages/middleware`.
+
+## Accepted: monorepo first — middleware withdrawn rather than consolidated
+
+The maintainer confirmed that monorepo work is starting now. The earlier
+recommendation to keep repositories separate for now is superseded.
+
+**Reversed 2026-09-19: the middleware half of this decision no longer applies.**
+This section used to say "move middleware into the monorepo as its own package
+first, preserving its existing API and behavior," and explicitly: "do not
+unpublish or retire the middleware package as part of the initial move."
+That instruction was overtaken. `@jimhoyd/urlcode-middleware` has been
+**unpublished** from npm at `0.1.0-alpha.2` and `jimhoyd-com/urlcode-middleware`
+**deleted** — the package was withdrawn outright instead of migrated, so there
+is no `packages/middleware` to create and no subsequent fold-into-core step.
+The reversal is recorded here rather than deleted because the instruction it
+replaces was explicit, and a reader who remembers it should be able to see that
+it was changed deliberately and not simply forgotten.
+
+Nothing was lost in capability terms: per-route middleware is **native to
+core** via the `middleware:` array ([MIDDLEWARE.md](../../MIDDLEWARE.md)), and the
+deleted package only ever offered the same behavior through the extension
+seam. Trust remains the default and explicit sandbox choices keep their
+meaning. The generic extension wrapping hook (`ExtensionInstance.middleware`,
+`RuntimeExtension.cacheSensitive`) stays in core's contract for other
+extensions — it is no longer exercised by any shipped package, which is worth
+knowing before it is assumed to be covered. Static targets continue rejecting
+request-time middleware because there is no server to run it.
+
+Migration scope is therefore **core, auth, admin and UI**. Template and the
+distribution tap stay outside that package move. The observed stale peer pins
+and checkout-limited guidance checks strengthen the case for shared
+verification: carry those checks across the new package paths, since merely
+moving files does not prove every generated skill is covered. The cleanup PRs
+that superseded the earlier zero-open-PR survey have since merged, and a fresh
+survey again reports zero open pull requests across all four in-scope
+repositories — re-run it per repository immediately before that repository
+moves rather than trusting this line.
+
+The [archived monorepo plan](../2026-09-19/SPIKE-MONOREPO.md) records
+migration context.
+[Issue 172](https://github.com/jimhoyd-com/urlcode/issues/172), which tracked
+"consolidate middleware into core after moving it into the monorepo," was
+**closed on 2026-09-19** as moot — there was nothing left to consolidate.
+Migration starting is not a claim that it has landed.
+
+## Source review baseline
+
+| Repository | Reviewed commit | Code checked |
+|---|---|---|
+| core | `db375bf` | Runtime dispatch, schema normalization, capabilities, static compiler, prerender, MCP and resource generators |
+| auth | `71957dd` | Lifecycle hooks, UI rendering and shared helper imports |
+| admin | `f3b4882` | UI rendering, auth-service integration and shared helper imports |
+| UI | `0e96f7f` | Shared forms, kit/host exports and copied core contract |
+| ~~middleware~~ | `f201f4b` | Extension wrapping, per-entry sandbox dispatch and scaffolding — **repository deleted 2026-09-19; this baseline is unreachable except through the local `urlcode-middleware.bundle`** |
+| template | `4e09e50` | Exact core pin, generated guide and both vendored skills |
+
+The Homebrew tap (`73eaaef`) still selects stable core `0.3.0`; its old trust
+behavior belongs to that pin and must not be rewritten as alpha.2 behavior.
+The other organization tap and Scoop bucket contain Gitroll, not URLCode.
+The deleted documentation repository is historical context, not a second source
+of current contracts; its former GitHub links no longer resolve. This review is targeted source inspection, not an audit of
+every execution path or an independent security assessment.

package/docs/archive/README.md

@@ -19,6 +19,8 @@ Archived on 2026-09-19 after checking the current code:
 | [Extension model review](2026-09-19/SPIKE-EXTENSION-MODEL.md) | Historical design rationale | Current extension contract |
 | [Usability review](2026-09-19/USABILITY-REVIEW.md) | Predates trusted execution and retired packages | New benchmark observations |
 | [Management security](2026-09-19/MANAGEMENT-SECURITY.md) | Describes the removed core link-management API | No current core replacement |
+| [Lambda compile spike](2026-09-19/SPIKE-LAMBDA-COMPILE.md) | Proposal declined 2026-09-19 in favour of one Node deployment per project | Open decisions; AWS and Vercel guides |
+| [Completed decisions (2026-09-20)](2026-09-20/OPEN-DECISIONS-COMPLETED.md) | Closed questions, the completed monorepo migration and the 2026-09-19 source baseline, moved out of open decisions (#242) | Current open decisions and release readiness |
 
 Open proposals stay outside the archive with their status stated at the top.
 The accepted trust-by-default decision remains directly linked from the current

package/docs/yaml/functions.md

@@ -53,8 +53,16 @@ short form: `middleware: [middleware/headers.mjs]` means
 `middleware: [{source: middleware/headers.mjs}]`. The path must be
 project-relative, end in `.mjs` or `.js` and contain no `..` segment.
 Methods default to GET and HEAD. Function paths resolve from the project root,
-not the YAML file's directory. `.js` and `.mjs` ES modules work; TypeScript, Node
-APIs, npm imports, network access and filesystem access do not.
+not the YAML file's directory. Modules are ES modules either way: `.mjs` always
+works, while a trusted `.js` module is loaded by Node and therefore needs the
+nearest `package.json` to say `"type": "module"` (a `sandbox: true` route reads
+`.js` as ESM regardless). Serving never transpiles TypeScript; build it first
+with [TypeScript authoring](../TYPESCRIPT-AUTHORING.md). The route above
+declares no `sandbox`, so it runs trusted and in-process: Node APIs, npm
+imports, network and filesystem access are all available to it, exactly as they
+are to any other Node code in the host. Add `sandbox: true` to trade them away
+for isolation -- inside the guest none of them exist. See
+[trust model and sandbox opt-in](../FUNCTION-SECURITY.md).
 
 ## 4. Input types and constraints