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

package/docs/SPIKE-MONOREPO.md

@@ -0,0 +1,322 @@
+# Spike: consolidating core, auth, admin, ui (and the two pending extractions) into one repo
+
+Status: proposal, nothing implemented, no repo touched. Drafted at the requester's
+explicit direction to produce a plan document only — see "What this is not"
+below. Treat this the same way as the other `SPIKE-*.md` documents in this
+directory: a recorded decision trail for the maintainer to accept, amend or
+reject, not committed scope.
+
+## What this is not
+
+This is not a recommendation to touch any of `urlcode`, `urlcode-auth`,
+`urlcode-admin` or `urlcode-ui` tonight. No git history has been merged, no
+package has been moved, no CI has been reconfigured. Everything below is a
+sequenced plan to review, not a changelog of what happened.
+
+## The problem this is answering
+
+Four repos (`urlcode`, `urlcode-auth`, `urlcode-admin`, `urlcode-ui`) already
+coordinate tightly — `auth`/`admin`/`ui` each pin an exact core revision in
+their own `peers.json`, and `docs/FRAMEWORK.md` describes them as one
+composed product, not four independent ones. Concretely observed cost of that
+coordination happening across four repos, from an evening spent reading all
+four:
+
+- **Observed and since fixed, which is the point rather than a counterpoint.**
+  When core landed trusted-by-default execution (`b3bde4e`), `urlcode-auth`
+  and `urlcode-admin` were both still pinning core at `50790d3a`
+  (`0.4.0-alpha.1`), predating it, and `urlcode-auth/SECURITY.md` still
+  carried a sentence ("sandboxed guest code") that assumed the old model.
+  Both have since been corrected — both repos now pin `d5e86017`, and that
+  sentence is gone. Nothing was ever broken in production by either.
+  The cost this plan is describing is not "drift goes unnoticed forever"; it
+  is that catching and fixing it took a manual pass across three separate
+  repositories, with nothing structural to catch it automatically — no
+  mechanism flags a downstream repo's prose or pin as stale when an upstream
+  contract changes underneath it. That pass has to be repeated by hand on
+  every future contract change, for every downstream repo, indefinitely.
+  Consolidation removes the class of work, not just this instance of it.
+- Two more repos, planned in `docs/SPIKE-CORE-LAYERING.md` and originally
+  drafted here as "not yet created," turned out to already exist by the time
+  this doc was reviewed: `urlcode-dynamic-link` (7 commits, Phase 2 already
+  implemented, `v0.1.0-alpha.1` released) and `urlcode-middleware` (5 commits,
+  implemented, `v0.1.0-alpha.1` released), each with its own real commit
+  history, release workflow and open issues. That raises the
+  actively-coordinated repo count from four to six today, not hypothetically
+  — before this plan even accounts for `urlcode-template`, `urlcode-short`,
+  `urlcode-docs`, `urlcode-cloud` and `homebrew-urlcode`. It also means
+  "create them directly in the monorepo" (this doc's original framing) is no
+  longer available for these two — they now need the same history-preserving
+  migration as `auth`/`admin`/`ui`, covered in "Migration mechanics" below.
+
+None of this is a defect in any one repo. It's the accumulating tax of
+coordinating tightly-coupled, independently-versioned packages across
+separate git histories, issue trackers and CI pipelines by hand.
+
+## Scope: what moves, what doesn't
+
+Decided (see conversation this spike is drafted from):
+
+**In scope — six existing repos, all with real history, folded into one
+repo as workspace packages:**
+
+| Repo today | Becomes |
+|---|---|
+| `urlcode` (core) | `packages/core` (or repo root stays core-shaped, TBD in "Layout options" below) |
+| `urlcode-auth` | `packages/auth` |
+| `urlcode-admin` | `packages/admin` |
+| `urlcode-ui` | `packages/ui` |
+| `urlcode-dynamic-link` (real repo, `v0.1.0-alpha.1` released) | `packages/dynamic-link` |
+| `urlcode-middleware` (real repo, `v0.1.0-alpha.1` released) | `packages/middleware` |
+
+**Explicitly out of scope, each for a distinct, real reason — not just "left
+for later":**
+
+- **`homebrew-urlcode`** — cannot move. Homebrew tap conventions require a
+  repo literally named `homebrew-<name>`; this is an external platform
+  constraint, not a project choice.
+- **`urlcode-docs`** — `AGENTS.md` is explicit that public documentation is
+  "authored there directly," deliberately separate from code, "no longer
+  generated from this repository." Folding it in would reverse a stated,
+  recent decision, not follow one.
+- **`urlcode-cloud`** — a separately-lifecycled hosted product (private
+  repo); its release cadence and access model have no reason to match a
+  library monorepo's.
+- **`urlcode-template` / `urlcode-short`** — these are example/starter
+  projects, not library packages. Mixing "things you `npm install`" with
+  "things you `git clone` as a starting point" in one workspace is a
+  different kind of repo than what this spike is solving for.
+
+## Why six, and not four
+
+`link` and `middleware` were extracted *out* of core specifically so core
+stays "the smallest thing that is still a complete product on its own"
+(`docs/SPIKE-CORE-LAYERING.md`). Both are now real, shipped repos: they
+already paid the coordination cost this spike is trying to remove —
+`urlcode-dynamic-link`'s and `urlcode-middleware`'s own `peers.json`-style
+pins against core, their own CI, their own docs that can drift the same way
+`urlcode-auth/SECURITY.md` already did. Folding them into this consolidation
+alongside `auth`/`admin`/`ui` stops that from compounding further, rather
+than leaving two more repos outside the fix.
+
+## Layout: decided — option A
+
+**A. Root repo is core, extensions live under `packages/`.**
+```
+urlcode/
+  src/            # core, unchanged in place
+  packages/
+    auth/
+    admin/
+    ui/
+    dynamic-link/
+    middleware/
+```
+Lowest-friction for core's own history (nothing moves), but makes "core" and
+"the monorepo" the same name, which may read as core absorbing the
+extensions rather than the extensions and core coexisting as peers — worth a
+naming discussion given `AGENTS.md`'s "Core never imports them" independence
+framing.
+
+**B. Everything moves under `packages/`, including core — considered, not
+chosen.** Would have been symmetric and avoided the naming overlap noted
+above, at real cost: core's own history would need to move too, and every
+external reference to `urlcode`'s current repo path (`docs/`, READMEs
+elsewhere, the `@jimhoyd/urlcode` package's repository field, CI badges,
+this evening's own `peer-camera`/`peer-eyes` citations) would need updating.
+Decided against for exactly that reason.
+
+**Decided: (A).** Core's repo and history stay exactly where they are; the
+six packages move to it (five extensions plus core itself now living in the
+same repo as a `packages/*` sibling). The one open item this still leaves,
+worth a short naming discussion rather than blocking anything: "core" and
+"the consolidated repo" now share a name, which could read as core absorbing
+the extensions rather than the two coexisting as independent packages
+(`AGENTS.md`'s "Core never imports them" framing still holds in code either
+way — this is a naming-perception question, not a contract question).
+
+## Migration mechanics, per repo
+
+For each of `urlcode-auth`, `urlcode-admin`, `urlcode-ui`,
+`urlcode-dynamic-link` and `urlcode-middleware` — all six now real repos
+with real history:
+
+0. **Drain open pull requests first — a hard precondition, not a courtesy.**
+   Before a repo is migrated, it must have zero open PRs (and no unmerged
+   release branch). A PR open against the source repo at the moment its code
+   moves is stranded: its branch targets a `main` that no longer receives
+   code, its diff is written against paths (`src/…`) that no longer exist at
+   that location, and re-creating it against the consolidated repo means
+   rebasing onto a different repository and a new path prefix
+   (`packages/<name>/src/…`) by hand. GitHub cannot retarget a PR across
+   repositories. So for each repo, in order: stop merging new work, merge or
+   close what is open, confirm `gh pr list`/the API reports none, then
+   migrate. Any PR that cannot be merged in time should be closed with its
+   branch preserved and re-opened against the consolidated repo afterwards —
+   a deliberate choice recorded on the PR, not an accident discovered later.
+   This is also the real reason to pick a quiet window for the migration
+   rather than a busy one: the cost of this step scales with how much is
+   in flight.
+1. **Preserve history with `git subtree add` or `git filter-repo` +
+   merge**, not a fresh copy — so `git log`/`git blame` on
+   `packages/auth/src/auth.ts` still resolves to the real authorship history
+   from `urlcode-auth`, and so a future "actually, let's give this its own
+   repo back" is a clean `git filter-repo` extraction, not archaeology.
+   `git subtree` is the lower-risk default (reversible, no force-push
+   required on the source repos); `git filter-repo` gives cleaner resulting
+   history at the cost of being a one-way rewrite of the joining repo's
+   local copy (the original `urlcode-auth` GitHub repo is untouched either
+   way — this only rewrites what gets pulled in).
+2. **npm workspace restructuring**: `package.json` at the monorepo root gets
+   `"workspaces": ["packages/*"]` (the same shape `peer-camera` already
+   uses); each `packages/<name>/package.json` keeps its own name/version,
+   independently publishable — this is what preserves "independently
+   versioned packages" as a property, not something this migration gives up.
+   **Decided: [Changesets](https://github.com/changesets/changesets) for the
+   release flow, not Nx or Turborepo.** A changeset is a small, bounded,
+   git-diffable markdown file (package name + semver bump + description) —
+   cheap and low-risk for an agent or a human to generate correctly, easy
+   for CI to verify mechanically ("does every touched package have one"),
+   and it's the deliberate checkpoint that stops local workspace-linked
+   development (testing against a sibling package's unreleased state, which
+   is now the default once auth/admin/ui/dynamic-link/middleware sit next to
+   core) from silently becoming a real release. Nx/Turborepo were considered
+   and set aside: both add a much larger, more inference-heavy configuration
+   surface (task graphs, remote caching semantics) that's a bigger, more
+   opaque thing to get wrong than this repo's six packages currently need —
+   plain `npm test -w packages/auth`-style workspace scoping already covers
+   what this size of repo actually requires. Revisit only if the package
+   count grows enough that rebuild/retest time becomes a real problem.
+3. **`peers.json` becomes unnecessary for the six that moved** — a
+   workspace package can depend on a sibling workspace package directly
+   (`"@jimhoyd/urlcode": "workspace:*"` or npm's equivalent), which is
+   inherently always in sync, no separate pin file, no drift possible by
+   construction. `peers.json`-the-mechanism might still matter if any
+   *external* consumer needs a reviewed-revision pin story — worth deciding
+   explicitly rather than silently dropping the safeguard.
+4. **CI consolidation**: one `verify.yml` (or similar) with
+   path-filtered jobs per package, replacing four separate workflow files.
+   `CODEOWNERS` can still express per-package ownership within one repo
+   (path-scoped rules), so "who reviews auth changes" doesn't have to
+   become "everyone reviews everything."
+5. **Docs cross-references**: every `[EXTENSIONS.md](../urlcode/docs/...)`-
+   style cross-repo link in `auth`/`admin`/`ui`'s current docs becomes a
+   same-repo relative link once consolidated — this is a real cleanup
+   opportunity, not just migration overhead, since it directly targets the
+   "docs silently drifted apart" problem this spike opened with.
+6. **Re-register npm Trusted Publishing per package.** All six repos'
+   release workflows publish via OIDC trusted publishing, no long-lived npm
+   token (`docs/SPIKE-CORE-LAYERING.md`'s governance section, confirmed by
+   `urlcode-dynamic-link`'s and `urlcode-middleware`'s own "Add
+   trusted-publishing release workflow" commits). That trust is registered
+   on npmjs.com per package, pinned to an exact GitHub repo + workflow
+   filename (+ optional environment) — it does not follow the code when the
+   repo path changes. Each of `@jimhoyd/urlcode-auth`, `-admin`, `-ui`,
+   `-dynamic-link`, `-middleware` needs its npmjs.com trusted-publisher entry
+   updated to the new repo and new workflow path *before* that package's
+   first release from the consolidated location, or the publish step fails
+   closed (correctly — not a security gap, just an ordering dependency this
+   plan needs to carry explicitly rather than discover at release time).
+7. **Issue migration — decided: recreate open issues in the consolidated
+   repo, not leave-and-link.** GitHub doesn't move issues across repos
+   natively, so this means bulk-recreating each open issue at the new
+   location with a back-link to the original (closed with a pointer) rather
+   than leaving it where it is. Concrete scope as of this doc: `auth`,
+   `admin` and `ui`'s own open-issue counts weren't re-audited here, but
+   `urlcode-dynamic-link` and `urlcode-middleware` were, since they're the
+   two repos whose "does this even apply" status changed mid-conversation:
+   - `urlcode-dynamic-link`: 0 open issues — nothing to migrate.
+   - `urlcode-middleware`: 2 open issues to recreate —
+     [`#1`](https://github.com/jimhoyd-com/urlcode-middleware/issues/1)
+     ("`sandbox: true` is not supported — needs its own QuickJS/WASM worker
+     pool") and
+     [`#3`](https://github.com/jimhoyd-com/urlcode-middleware/issues/3)
+     ("Remove vendored core tarball once `@jimhoyd/urlcode` 0.4.0-alpha.2+ is
+     published to npm"). Both should move to the consolidated repo's tracker
+     when the merge actually happens, each closed in its original location
+     with a link to the new issue.
+
+## What this preserves, unchanged
+
+- **The trust/extension model itself.** `packages/auth` published from the
+  monorepo is exactly as separate a package, with exactly the same
+  `RuntimeExtension` contract, revision-pinning and operator-registration
+  requirements, as `urlcode-auth` published from its own repo today. This
+  spike changes where the source lives, not what the extension mechanism
+  guarantees.
+- **Independent versioning and release cadence per package** — a monorepo
+  with workspaces is not "one version number for everything."
+
+## What this gives up, honestly
+
+- **Per-repo maturity gating.** `docs/SPIKE-CORE-LAYERING.md` records that
+  `auth`/`admin`/`ui` used a "`private: true` until reviewed" pattern before
+  their first public release, and that the two new repos are deliberately
+  *not* following that pattern ("published public from the start"). A
+  monorepo can't easily make one folder private and another public — the
+  repo-level visibility setting is all-or-nothing on GitHub. Once
+  consolidated, "private until reviewed" stops being available as a pattern
+  for whatever the next extension after `middleware`/`dynamic-link` turns
+  out to be, unless it's built in yet another separate private repo first
+  and merged in later — which reintroduces a version of the coordination
+  cost this spike is trying to remove, just for pre-release work instead of
+  ongoing maintenance.
+- **"Fork just one piece" stops being a plain `git clone` — but scoped to a
+  narrow audience, not every auth user.** `SPIKE-AUTH.md` names forkability
+  as a deliberate design goal specifically for `auth`. It's important not to
+  overstate who this actually affects: a developer customizing auth's look
+  or copy (theme, relabeling, `extra.css`, a shadowed template) works
+  entirely inside *their own* project repo via the `ui` extension's layering
+  system (`ui/copy`, `ui/extra.css`, `ui/templates`) — they never clone or
+  fork `urlcode-auth` at all, install it from npm like any dependency, and
+  this migration changes nothing for them. The friction increase applies
+  only to the much narrower case of someone changing auth's actual *logic*
+  (a new sign-in method, different session semantics) — something the
+  layering system can't express because it's behavior, not presentation.
+  For that persona, forking just the auth package post-consolidation means a
+  `git filter-repo`-style history extraction instead of `git clone
+  jimhoyd-com/urlcode-auth` — solvable, but a real step up in friction, for
+  a small population, not the common path.
+- **Blast radius of a bad CI run.** One consolidated CI means a
+  misconfigured job can, in principle, block merges across all six
+  packages at once, where today a broken `urlcode-ui` pipeline can't stop an
+  unrelated `urlcode-auth` merge. Path-filtered jobs mitigate this but don't
+  eliminate it the way full repo separation does.
+
+## Sequencing, if this is accepted
+
+1. Decide layout (A vs. B above) and confirm the out-of-scope list.
+2. **Check open pull requests across all six repos before starting, and again
+   per repo immediately before its own migration** (mechanics #0). A repo with
+   anything open is not ready to move. Doing this as a survey first also sizes
+   the whole migration honestly: the number of in-flight PRs is the real
+   scheduling constraint, not the git mechanics.
+3. Migrate `urlcode-ui` first (fewest inbound dependents — `auth`/`admin`
+   both depend on it, nothing depends on them), proving the subtree +
+   workspace mechanics on the lowest-risk package. Re-register its npm
+   trusted publisher (mechanics #6) before cutting its first release from
+   the new location — treat this as part of "done," not a follow-up.
+4. Migrate `urlcode-auth`, then `urlcode-admin` — same re-registration step
+   each time.
+5. Migrate `urlcode-dynamic-link`, then `urlcode-middleware` — same
+   subtree/filter-repo mechanics and trusted-publisher re-registration as
+   the other three, now that both are real repos with real history rather
+   than something created fresh in place. Recreate their open issues (see
+   "Migration mechanics" #7 above: 0 from `dynamic-link`, `#1` and `#3` from
+   `middleware`) in the consolidated tracker as part of each repo's
+   migration step, not as a separate pass.
+6. Retire (archive, don't delete — GitHub redirects an archived repo's clone
+   URL) all six now-empty source repos, with their READMEs pointing at the
+   new location.
+
+## Open questions for the maintainer, not answered here
+
+- Does `peers.json`'s reviewed-pin discipline need an equivalent for any
+  external (non-workspace) consumer, or does workspace-linking fully replace
+  its purpose?
+- `git subtree` vs. `git filter-repo` for history preservation — a real
+  tradeoff between migration safety and final history cleanliness, worth a
+  deliberate call rather than defaulting.
+- The naming-perception question from "Layout: decided — option A" above
+  (core's repo and the consolidated repo sharing a name) — worth a short
+  discussion, not blocking.

package/docs/STARTERS.md

@@ -44,7 +44,7 @@ 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.1` prereleases) in the directory you run from and pass their names: `urlcode init ../my-site --with
+`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
 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).

package/docs/STATIC.md

@@ -0,0 +1,94 @@
+# Deploying to static hosting (S3 + CloudFront)
+
+The `static` target is the bottom rung of the [capability
+ladder](SPIKE-CORE-LAYERING.md#the-full-ladder-one-contract-one-vocabulary-per-level):
+the same `urlcode.yaml` a self-hosted server or a serverless adapter runs, with
+no server process at all. `urlcode build --target static` compiles a project
+ahead of time into plain files and two small JSON manifests meant for an S3
+bucket served through CloudFront — nothing here executes a request.
+
+```sh
+urlcode build --target static --project . --out dist --origin https://links.example
+```
+
+## Declarative routes only, and less than that
+
+This target serves **redirects**, **declared responses** (`respond:`) and
+static files (`page`, `static`, `download`) — no path parameters, no query
+passthrough or mapping, GET/HEAD only, and no `enabled: false` or `expires`
+(there is no server to answer a disabled or expired route with 404/410, so the
+build refuses one instead of silently serving it forever). Everything else is
+refused **at build time**, with the route pattern and the reason named:
+
+| Handler / feature | Why it is refused |
+| --- | --- |
+| `function`, `middleware` | no server, so no dynamic or sandboxed execution |
+| `extension`, `policies.extensions` | no server, so no operator extension registry |
+| `proxy`, `signals` | no server, so no bounded or fire-and-forget egress |
+| `conditional`, `match` (`conditions`) | no server, so no request-time condition matching |
+| `parameters`, `request.body` | no server, so no request-time validation |
+| `response.headers` | no server, so no per-request headers; set them as S3 object metadata or a CloudFront response headers policy instead |
+| `env`, `secrets` (`bindings`) | no server, so no per-request binding resolution |
+| every `policies.*` | no server, so no runtime policy enforcement |
+| a redirect with a `{parameter}` in its path | S3's per-object redirect is keyed to one exact object, not a pattern |
+| a redirect with `query.pass`/`query.map` | S3's per-object redirect cannot compute a target per request |
+| a redirect with a `status` other than 301 | S3's per-object website redirect always answers 301 |
+| a route declaring methods other than GET/HEAD | static hosting only ever answers GET/HEAD |
+| a route with `enabled: false` or `expires` | no server to answer a disabled/expired route; remove the route instead |
+
+Run `urlcode capabilities --target static` for the full catalog.
+
+## What the build emits
+
+`--out` (default `dist/static`) receives:
+
+- `objects/<key>` — the actual files to upload, one per served route. A `page`
+  or `download` route becomes one file; a `static` mount becomes one file per
+  entry in its directory. Object keys match the S3 convention: the route
+  pattern with its leading `/` stripped, and `/` itself becomes `index.html`
+  (matching a bucket's own "Index document" setting). A redirect route also
+  gets a zero-byte placeholder object at its key, so it exists to carry
+  metadata.
+- `objects.json` — `{ format, objects: [{ key, contentType, cacheControl?,
+  contentDisposition? }] }`. Plain file upload loses this metadata (S3 does not
+  reliably infer content type or cache headers from an extension-less key), so
+  a deploy step reads this file and sets each object's own `Content-Type`,
+  `Cache-Control` and `Content-Disposition` from it, for example with
+  `aws s3 cp --content-type ... --cache-control ...` per entry, or an
+  equivalent `aws s3 sync` post-processing step.
+- `redirects.json` — `{ format, redirects: [{ key, location, status: 301 }] }`.
+  Each entry is applied as the S3 object's
+  [website redirect location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-page-redirect.html)
+  metadata (`x-amz-website-redirect-location`), for example
+  `aws s3api put-object --website-redirect-location <location> --bucket ... --key <key>`.
+  S3 always answers a request for that key with a 301 to `location`
+  regardless of the object's own content — this is why a declared `status`
+  other than 301 is refused rather than silently downgraded.
+- `manifest.json` — the same project-level semantic manifest every target
+  writes (see [tooling](TOOLING.md)).
+
+None of these are edited by hand, and `dist/` belongs in `.gitignore`. This
+target ships no runtime import (there is nothing to run), so there is no
+`@jimhoyd/urlcode/static` entry point — the build output is the deployment.
+
+## What this is not: GitHub Pages
+
+**This target's claimed support is S3 + CloudFront, not GitHub Pages.**
+GitHub Pages has no per-object redirect metadata and no server-side rewrite
+layer, so a `redirect` route compiled the way this target compiles it (S3
+object metadata) has no equivalent there — the only options are a
+meta-refresh/JavaScript page (visibly a redirect, not an HTTP one: search
+engines, curl and anything that does not run JavaScript sees the source page,
+not a 3xx) or a static 404-page trick, both lower fidelity than what every
+other target in this project does for the same route. Rather than claim a
+portability promise this platform cannot keep, GitHub Pages is out of scope
+for this target. If you need Pages, treat it as a distinct target with its own
+explicit fidelity caveat, not a rename of this one.
+
+## Verification status
+
+This target has local build tests only (`test/static.test.ts`): the compiled
+object layout, the redirect manifest, and every refusal above. **It has not
+been deployed to S3 or fronted by CloudFront.** Bucket policy, CloudFront
+caching behavior, TLS/domain setup and the exact `aws s3` invocations above are
+unverified until a real deployment exercises them.

package/docs/TOOLING.md

@@ -76,7 +76,7 @@ network. Keys always appear in this order:
 - `urlcode` (package version) and `schema` (`"1"`).
 - `project`: entry file, route count, handlers used with counts, extensions
   declared, policies in effect at the top level and the number of routes each
-  policy applies to, requested env and secret binding names, `dynamicLinks`,
+  policy applies to, requested env and secret binding names,
   `site` keys, and `files` (include, function and middleware paths). With
   `--host-file`, `host` counts the operator module's extensions and plugins
   without activating them.
@@ -113,13 +113,17 @@ checks. Build output remains an explicit separate build API/CLI operation.
 
 The package root also exports existing operator-invoked workflow APIs:
 `buildCloudflare(project, options)` compiles and writes a Cloudflare artifact;
-`runProjectTests(project, options)` starts the local runtime, executes request
-fixtures and closes it; `scaffoldProject(project, {dryRun})` creates missing
-placeholders while preserving existing files; `initProject(destination)` creates
-the standard starter; and `addRedirect(project, destination, alias?)` updates
-project YAML under the authoring lock. `CloudflareBuildOptions`,
-`CloudflareBuildReport`, `ProjectTestOptions`, `ProjectTestResult`, `ScaffoldReport`
-and `ScaffoldUnresolved` describe these existing operations.
+`buildStatic(project, options)` compiles redirects and static files into plain
+objects and redirect metadata for S3 + CloudFront (see [static
+hosting](STATIC.md)); `runProjectTests(project, options)` starts the local
+runtime, executes request fixtures and closes it; `scaffoldProject(project,
+{dryRun})` creates missing placeholders while preserving existing files;
+`initProject(destination)` creates the standard starter; and
+`addRedirect(project, destination, alias?)` updates project YAML under the
+authoring lock. `CloudflareBuildOptions`, `CloudflareBuildReport`,
+`StaticBuildOptions`, `StaticBuildReport`, `ProjectTestOptions`,
+`ProjectTestResult`, `ScaffoldReport` and `ScaffoldUnresolved` describe these
+existing operations.
 
 These SDK functions have explicit write or execution effects and are available
 to trusted callers only. Project tests use normal runtime activation, grants and
@@ -150,7 +154,7 @@ per-target support), the union of capabilities used, extension declarations
 (version, configuration keys, mounts and protected routes), recipe provenance
 (from a `recipe.yaml` beside the entry file when one exists), external
 requirements (environment and secret names, proxy and signal origins,
-extensions, link-store collections, dynamic links), the function and middleware
+extensions), the function and middleware
 modules with the routes that use them, and per-target compatibility. Without
 `--json` a short summary prints. The manifest is deterministic: the same
 project produces the same bytes. `urlcode build` writes the same document as

package/docs/TUNNELS.md

@@ -65,9 +65,6 @@ scanners that find it within minutes.
 - The runtime has **no authentication and no rate limiting**. Put access control
   in the tunnel: ngrok's OAuth, OIDC or basic auth; Cloudflare Access; a
   Tailscale ACL.
-- **Never tunnel the link-management API.** It is a separate listener bound to
-  loopback on purpose, holding credentials that can rewrite live links. Tunnel
-  the application port only.
 - Prefer `serve` with a fixed snapshot, a project containing no real secrets,
   and a tunnel you shut down when finished.
 

package/docs/TYPESCRIPT-AUTHORING.md

@@ -1,8 +1,16 @@
 # Build-time TypeScript guests
 
 TypeScript guest authoring is a separate build step. Serving still accepts only
-JavaScript ES modules and executes them exclusively in QuickJS/WebAssembly.
-The build never imports application modules into Node or runs application code.
+JavaScript ES modules. The build never imports application modules into Node
+or runs application code, and it is `sandbox`-aware per route
+(docs/SPIKE-DEFAULT-TRUST-MODEL.md): a route that declares `sandbox: true` is
+transpiled under the sandbox's own module rules (relative imports only, no
+dynamic import/bare specifiers, the module/size limits below), exactly as
+before; a trusted (non-`sandbox: true`) route is transpiled without those
+import/size restrictions, since it will run with full Node access — bare/npm
+imports, dynamic `import()`, `import.meta` — once served. Both modes still
+diagnose only syntax, not semantics, and neither imports application code into
+the build process in a way that executes it.
 
 ```sh
 urlcode recipes add typescript --out ./hello-source
@@ -29,17 +37,24 @@ The trusted pinned TypeScript compiler transpiles ES2022/ES modules with fixed
 settings. It does not read `tsconfig.json`, package scripts, plugins, compiler
 transformers, dependency packages, Node declarations or ambient environment
 files. It diagnoses syntax errors, but does **not** perform semantic type
-checking. Type-only relative imports are erased without reading their targets.
-Bare/npm imports (including static type-only imports), CommonJS import/export
-syntax, dynamic runtime imports, `import.meta`, import attributes and imports
-outside the project are refused. No import extension inference occurs.
+checking, in either mode. CommonJS import/export syntax and imports outside
+the project are always refused. Type-only relative imports are erased without
+reading their targets.
 
-The source graph is limited to 128 modules, 1 MiB per source and 4 MiB aggregate.
-The emitted graph must pass the runtime's own source parser and byte limits
-before publication. This does not execute the modules or replace normal route,
-policy, binding or sandbox validation at activation. Unsupported host/browser
-APIs remain unavailable in QuickJS, even if TypeScript accepts their names.
-Run `urlcode validate --local` and project tests on the output.
+For a `sandbox: true` route, bare/npm imports (including static type-only
+imports), dynamic runtime imports, `import.meta` and import attributes are
+refused, and the source graph is limited to 128 modules, 1 MiB per source and
+4 MiB aggregate; the emitted graph must also pass the runtime's own sandboxed
+source parser and byte limits before publication. For a trusted route, none of
+that applies: bare/npm specifiers, dynamic `import()`, `import.meta` and
+import attributes pass through unchanged (resolved by Node at serve time, not
+by this build), and there is no module-count or size ceiling. In both modes,
+no import extension inference occurs — relative imports of project modules
+still need an explicit `.ts`/`.js`/`.mjs` extension to be rewritten and
+followed. This does not execute the modules or replace normal route, policy,
+binding or sandbox validation at activation. Unsupported host/browser APIs
+remain unavailable in QuickJS, even if TypeScript accepts their names. Run
+`urlcode validate --local` and project tests on the output.
 
 Includes are flattened into a duplicate-checked entry document. Only referenced
 modules, page/download assets, static trees, site favicon/llms files and the

package/docs/TYPESCRIPT.md

@@ -16,7 +16,7 @@ beside them, and `dist/BUILD-MANIFEST.json` with a SHA-256 per emitted file.
 | Import | Runtime | Declarations |
 |---|---|---|
 | `urlcode` | `dist/index.js` | `dist/types/index.d.ts` |
-| `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/extensions` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
+| `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/extensions`, `@jimhoyd/urlcode/sandbox` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
 | `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare` | `dist/<name>.js` | `dist/types/<name>.d.ts` |
 | `@jimhoyd/urlcode/schema` | `schemas/urlcode.schema.json` | — |
 
@@ -36,9 +36,7 @@ release cannot ship a declaration that does not resolve.
 ## The main exported types
 
 - `urlcode`: `Runtime`, `RuntimeOptions`, `RuntimeRequest`, `RequestTrace`,
-  `Server`, `ServerOptions`, `HostPlugin`, `Observer`, `TestPlan`, `LinkStore`,
-  `LinkRow`, `LinkStoreOptions`, `LinkReader`, `LinkStoreBinding`, `LinkApi`,
-  `LinkApiOptions`, `LinkEvent`, `LinkObserverOptions`.
+  `Server`, `ServerOptions`, `HostPlugin`, `Observer`, `TestPlan`.
 - `@jimhoyd/urlcode/plugins`: `Plugin`, `PluginRuntime`, `PolicyRequest`,
   `HandlerResult`, `HeaderPair`, `TargetName`. See [plugins](PLUGINS.md).
 - `@jimhoyd/urlcode/policies`: `PolicyModule`, `PolicyRegistry`, `PolicyRequest`,
@@ -54,6 +52,29 @@ release cannot ship a declaration that does not resolve.
 - `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare`: `LambdaEvent`,
   `LambdaHandler`, `LambdaHandlerOptions`; `VercelHandler`,
   `VercelHandlerOptions`; `Artifact`, `WorkerRoute`, `Validators`.
+- `@jimhoyd/urlcode/sandbox`: `SandboxPool`, `SandboxEntry`, `SandboxTarget`,
+  `SandboxInvocation`, `SandboxPoolOptions`, `functionFile`. The public
+  sandboxed-execution primitive: the same QuickJS/worker-thread engine that
+  already backs a `sandbox: true` `function`/`middleware` route
+  (`FunctionPool`, internally), generalized to an explicit list of
+  `{source, export}` entries instead of anything route/YAML-shaped, for an
+  extension package that needs to run a project-supplied hook through real
+  isolation when the project's own config declares `sandbox: true` on it
+  (see [EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks) and
+  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)). There is no trusted-mode
+  export here: a hook that does not declare `sandbox: true` is ordinary
+  project code the extension `import()`s directly via
+  `ExtensionActivation.root`, no primitive required.
+
+  ```ts
+  import { SandboxPool, functionFile } from '@jimhoyd/urlcode/sandbox';
+
+  const source = await functionFile(root, hookConfig.source); // root: ExtensionActivation.root
+  const entries = [{ source, export: hookConfig.export ?? 'default' }];
+  const pool = await new SandboxPool(entries, { root, workers: 1 }).start();
+  const result = await pool.execute({ entry: entries[0] }, request, context, undefined);
+  await pool.close();
+  ```
 
 ```ts
 import { startServer, type ServerOptions, type Observer } from '@jimhoyd/urlcode';

package/docs/USABILITY-REVIEW.md

@@ -6,6 +6,12 @@ benchmark. Its purpose is to name the friction a first-time user or an AI
 agent meets, compare it with what competing tools do, and rank the changes
 that would matter most. It does not change any contract by itself.
 
+> **Update:** written the day before `0.4.0-alpha.2` reversed the default
+> execution mode. Where the table below credits functions and middleware with
+> isolation, that now describes a route declaring `sandbox: true`; the default
+> is trusted, in-process execution with full Node, npm and filesystem access.
+> See [SPIKE-DEFAULT-TRUST-MODEL.md](SPIKE-DEFAULT-TRUST-MODEL.md).
+
 ## 1. Who the competitors are, by rung
 
 URLCode is not one product; it competes with a different tool on each rung
@@ -81,7 +87,7 @@ whether it touches a contract.
    "add accounts" row except the revision pin existed because they were
    unpublished. This was a decision, not code; the repositories already had
    the release checks. No contract change. Done 2026-09-18: all three are on
-   npm as `0.1.0-alpha.1` (review still pending, issue 58).
+   npm as `0.1.0-alpha.x` (review still pending, issue 58).
 2. **`urlcode init --with auth,admin,ui`.** Delegate to each installed
    package's existing scaffold; write one host file and one README. No contract
    change; a CLI addition in core that calls into optional peers.

package/docs/VERCEL.md

@@ -5,8 +5,8 @@ The Vercel adapter runs a URLCode project as a Node function. The same
 that is the point of the project format.
 
 **This adapter serves native handlers only:** redirects, validated responses,
-pages, static assets and downloads. Isolated functions, middleware and stored
-live links are refused at activation, not per request, so a deployment cannot
+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).
 
 A working project is in [`examples/vercel/`](../examples/vercel/).
@@ -71,9 +71,8 @@ and want it in generated URLs.
 
 | Not supported | Why |
 |---|---|
-| Isolated functions | Every cold start would spawn worker threads and load the WASM engine. Correctness is not the issue; predictable latency is, and it is unmeasured. |
-| Middleware | Runs in the same sandbox as functions. |
-| Stored live links | SQLite needs a durable writable file. A serverless filesystem is ephemeral and per-instance, so records would silently diverge between instances. |
+| `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. |
+| 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