@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.1

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/README.md

@@ -19,6 +19,7 @@ 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 |
 
 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
 

package/docs/yaml/middleware.md

@@ -23,7 +23,9 @@ export async function decorate(request, context, next) {
 
 Entries run in declared order before the handler and reverse order afterward.
 Return a Response early to skip downstream code; call `next()` at most once.
-Up to 16 middleware entries share one sandbox/deadline and approved route
-bindings. Native bodies are opaque; preserving them requires retaining original
-status/headers. Return a new Response to replace native content or destination.
+Up to 16 middleware entries share the route's execution mode, one deadline and
+one set of approved route bindings; the mode is the route's `sandbox` field, not
+a per-entry choice. On a `sandbox: true` route native bodies are opaque;
+preserving them requires retaining original status/headers. Return a new
+Response to replace native content or destination.
 YAML response headers apply last. See [middleware](../MIDDLEWARE.md) for details.

package/examples/cookbook/middleware/envelope.mjs

@@ -1,5 +1,7 @@
-// Wrap successful JSON function responses in a stable envelope. Native bodies are
-// opaque and pass through untouched; only readable JSON is rewritten.
+// Wrap successful JSON function responses in a stable envelope. Only a JSON body
+// this chain can actually read is rewritten; everything else passes through
+// untouched -- on a `sandbox: true` route that includes every native body, which
+// the guest cannot read at all.
 export default async function envelope(request, context, next) {
   const response = await next();
   if (!response.ok || !(response.headers.get('content-type') || '').startsWith('application/json')) return response;