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

package/docs/SPIKE-CORE-LAYERING.md

@@ -1,17 +1,34 @@
 # Spike: layering `link` and `middleware` out of core
 
+> Review update, 2026-09-19: Current baseline: **both extractions this spike
+> proposes are over, and neither ended in a shipped separate package.** Link
+> extraction completed and the resulting package was then retired. Middleware
+> extraction never completed: core still implements native middleware, and the
+> separate middleware extension — which added a different API with per-entry
+> sandboxing — has itself been unpublished at `0.1.0-alpha.2` and its
+> repository deleted. The extraction direction below is superseded, and it is
+> not an instruction to remove core middleware: core's native `middleware:`
+> array is now the only implementation of per-route middleware there is.
+>
+> An earlier version of this note said "monorepo work is starting now:
+> middleware moves in as a separate package first, and folds into core
+> afterward." Monorepo work is still starting, for core, auth, admin and UI —
+> but the middleware clause is void. There is no package to move in and
+> nothing to fold in afterward.
+
+
 Status: proposal, nothing implemented. No code in this repository does any of
 this, and nothing here is committed scope. This combines two extraction ideas
 into one spike because they share a mechanism and a sequence, not because
 either is blocked on the other.
 
-> **Update:** this spike's `link` extraction (Phase 1 below) has since been
-> implemented — core no longer has a native `link`/`LinkStore`/`dynamicLinks`
-> API; it now lives in the separate
-> [`urlcode-dynamic-link`](https://github.com/jimhoyd-com/urlcode-dynamic-link)
-> package. Present-tense references to `link` as a core feature elsewhere in
-> this document describe the pre-extraction state this spike was analyzing,
-> not current core.
+> **Update:** this spike's `link` extraction (Phase 1 below) was implemented —
+> core no longer has a native `link`/`LinkStore`/`dynamicLinks` API — and the
+> separate `urlcode-dynamic-link` package that received it has since been
+> retired, unpublished from npm and its repository deleted (September 2026).
+> Nothing owns stored links today. Present-tense references to `link` as a core
+> feature elsewhere in this document describe the pre-extraction state this
+> spike was analyzing, not current core.
 
 ## The shape this is aiming at
 
@@ -41,7 +58,8 @@ honest instead of inventing two different shapes:
 - **Mount ownership** (`route.extension`, `RuntimeExtension.activate` →
   `ExtensionInstance.handle`): an extension owns an exclusive `/prefix/*` and
   answers every request under it. This is the shape `link` needs — it already
-  behaves like a self-contained mount (`docs/DYNAMIC-LINKS.md`), and
+  behaves like a self-contained mount (documented in the since-retired
+  `urlcode-dynamic-link` package), and
   `auth`/`admin` already use it for `/account/*` and `/admin/*`
   (`docs/FRAMEWORK.md:10-15`).
 - **Wrap without owning** (`ExtensionInstance.authorize`, called when a route
@@ -161,7 +179,15 @@ before anything here is treated as settled.
   need to exist or be attached before their Phase 2 work can be written or
   verified, matching the constraint already flagged for `link`.
 
-## Repo governance for the two new repos (decided)
+## Repo governance for the two new repos (decided — both repos since deleted)
+
+> **Historical, 2026-09-19.** Both repositories this section governs were
+> created, released once, and then deleted; both packages are unpublished. The
+> decisions below were applied while they existed and are kept as the recorded
+> template for any future extension repository — not as a description of
+> anything live. Note in particular that the "published public from the start"
+> departure recorded below is the one whose consequences are worth reading
+> back: both repos that took it are gone within days of their first release.
 
 Both `urlcode-dynamic-link` and `urlcode-middleware` follow `GOVERNANCE.md`
 and `AGENTS.md` as written, with one explicit decision recorded here per
@@ -176,7 +202,8 @@ AGENTS.md's "do not publish packages without an explicit decision":
   admins or automation, CODEOWNERS recording ownership. CI/release workflow
   shape copied from core's `release.yml` (candidate build → audit → pack →
   attest → publish via trusted publisher, no long-lived npm token), per the
-  pattern `docs/NEXT-STEPS.md` §2.1 already used for `auth`/`admin`/`ui`.
+  pattern §2.1 of the archived plan (`docs/archive/2026-09-19/NEXT-STEPS.md`)
+  already used for `auth`/`admin`/`ui`.
   CodeQL required on main, secret scanning and push protection on, same as
   core.
 - **Published public from the start** — both the GitHub repo and the npm
@@ -225,9 +252,10 @@ system tax." The real costs are narrower and different for each:
   cost described above still applies, in full, to whichever specific
   `middleware:` wrap a developer explicitly opts into `sandbox: true` — and
   the same mitigation still matters there: native declarative primitives
-  (`docs/NEXT-STEPS.md`'s Phase 4.2 `auth: { required: true, roles: [...] }`
-  direction) reduce how much logic ever needs to reach for the sandboxed
-  opt-in at all, for the cases where a developer does judge it warranted.
+  (the Phase 4.2 `auth: { required: true, role: ... }` direction in the
+  archived plan, `docs/archive/2026-09-19/NEXT-STEPS.md`) reduce how much logic
+  ever needs to reach for the sandboxed opt-in at all, for the cases where a
+  developer does judge it warranted.
 
 ## Other core pieces considered and set aside
 
@@ -253,14 +281,17 @@ part of the smallest complete product:
   them would shrink core below the "complete product on its own" bar rather
   than trim it.
 - **Management API / operator grants / credential policy** — foundation that
-  extensions themselves depend on (`docs/MANAGEMENT-SECURITY.md`,
+  extensions themselves depend on (`docs/archive/2026-09-19/MANAGEMENT-SECURITY.md`,
   `docs/FUNCTION-SECURITY.md`); moving it out would mean extracting the thing
   the extraction pattern relies on.
 
 Nothing else in core matches the `link`/`middleware` shape today. If a third
-candidate is going to be found, `docs/REPETITION-LOG.md`'s discipline (`docs/NEXT-STEPS.md`
-Phase 6 — extract from observed repetition, not speculation) is the more
-defensible way to find it than continuing to eyeball the handler list.
+candidate is going to be found, the repetition-log discipline of Phase 6 in the
+archived plan (`docs/archive/2026-09-19/NEXT-STEPS.md`) — extract from observed
+repetition, not speculation — is the more defensible way to find it than
+continuing to eyeball the handler list. That plan records Phase 6 as never
+started, and no `docs/REPETITION-LOG.md` was ever written, so the log itself
+would have to be started before it could inform the decision.
 
 Recommendation: before either Phase 2 begins, attach `urlcode-auth`,
 `urlcode-admin` and `urlcode-ui` to a session and confirm (a) their actual

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

@@ -3,8 +3,7 @@
 Status: **decided by the maintainer and implemented in `0.4.0-alpha.2`**
 (`sandbox`/`sandboxReason` in `schemas/urlcode.schema.json`; see the
 `0.4.0-alpha.2` entry in [the roadmap](../ROADMAP.md) and the resulting contract
-in [function security](FUNCTION-SECURITY.md)). `0.4.0-alpha.2` is not yet
-published to npm. This overturns an
+in [function security](FUNCTION-SECURITY.md)). The release is published; this file retains the decision rationale. This overturns an
 explicit, previously-stated project rule — see "What this reverses" below —
 so treat it as a deliberate, recorded policy change, not a code cleanup. The
 body below is preserved as written at decision time; where it calls downstream
@@ -153,11 +152,14 @@ with `add_repo` before treating it as settled.
   and `peers.json` in `auth`/`admin`/`ui` (`docs/SPIKE-CORE-LAYERING.md`'s
   §2.2 reference) should pin deliberately to a core version that includes
   this change, not inherit it silently on a routine bump.
-- **`urlcode-dynamic-link` (built and published since; was planned when this was written): unaffected.** It's a
+- **`urlcode-dynamic-link` (built and published after this was written, then retired, unpublished and deleted in September 2026): moot.** It was a
   mount-based extension like `auth`, not a `function`/`middleware` consumer —
   nothing here changes its design.
-- **`urlcode-middleware` (built and published since; was planned when this
-  was written): same rule applies — decided.** First-party middleware is trusted by default, exactly like
+- **`urlcode-middleware` (built and published since, then retired, unpublished
+  and deleted in September 2026): the rule outlived the package — decided.**
+  The decision below was made for that package but is not about it: it governs
+  core's own native `middleware:` array, which is where per-route middleware
+  lives now that the extension package is gone. First-party middleware is trusted by default, exactly like
   `function`; `sandbox: true` is the same opt-in a developer reaches for
   when a specific `middleware:` wrap genuinely warrants it (e.g. it's
   processing input from a source the developer doesn't fully trust). This

package/docs/SPIKE-LAMBDA-COMPILE.md

@@ -1,5 +1,13 @@
 # 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.
+
+
 Status: proposal, nothing implemented. No code in this repository does any of
 this, and nothing here is committed scope.
 

package/docs/STATIC.md

@@ -1,7 +1,7 @@
 # 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):
+ladder](FRAMEWORK.md#the-ladder):
 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
@@ -15,7 +15,7 @@ urlcode build --target static --project . --out dist --origin https://links.exam
 
 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`
+passthrough or mapping, both GET and HEAD required, `respond.status: 200` 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:
@@ -33,7 +33,8 @@ refused **at build time**, with the route pattern and the reason named:
 | 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 not admitting both GET and HEAD, or admitting other methods | the output cannot enforce a different method set |
+| `respond.status` other than 200 | an uploaded response object cannot preserve a custom HTTP status |
 | 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.
@@ -92,3 +93,13 @@ 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.
+
+
+## Building pages with middleware
+
+Use [prerendering](PRERENDER.md) to execute functions and native middleware at
+build time, then export the generated native page routes with this target.
+Trusted Node execution is the build default; `sandbox: true` retains its
+restricted imports and resource limits. Neither mode adds a request-time server
+to the static output. Authentication, request-dependent headers and other
+per-request middleware cannot be baked into a public file safely.

package/docs/TOOLING.md

@@ -137,8 +137,8 @@ assistant file-write, guest-execution, deployment or network authority.
 
 `urlcode explain [/route] [--project DIR] [--target T] [--host-file F] [--json]`
 prints what `explainRoute` returns: one route in detail, or without a path a
-one-line-per-route table (methods, handler, state, middleware count, policies,
-cache outcome and target support). `--target` narrows the support columns to
+one-line-per-route table (methods, handler, state, execution mode, middleware
+count, policies, cache outcome and target support). `--target` narrows the support columns to
 one deployment target; `--host-file` supplies the operator registry so
 extension requirements show their provider. An unknown route exits 1 and names
 the nearest patterns. Everything comes from the compiled configuration: no
@@ -148,7 +148,8 @@ request is evaluated, no function runs and no binding is read.
 `schemaVersion`, the `urlcode` version, the entry file and its includes, the
 `revision` (the same digest `inspectExtensionRevision` returns, so an operator
 pin can be checked against it), the config `configVersion`, every route (path,
-methods, handler, state, middleware, inputs, policy names, extension
+methods, handler, state, execution mode (`sandbox`, with `sandboxReason` when
+the route declares one), middleware, inputs, policy names, extension
 requirements, cache outcome, binding names, egress origins, capabilities and
 per-target support), the union of capabilities used, extension declarations
 (version, configuration keys, mounts and protected routes), recipe provenance

package/docs/TYPESCRIPT-AUTHORING.md

@@ -48,7 +48,12 @@ refused, and the source graph is limited to 128 modules, 1 MiB per source and
 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,
+by this build), and there is no module-count or aggregate-size ceiling — only
+a generous 16 MiB per-source read cap that bounds authoring-time memory. A
+module may be shared by trusted and sandboxed routes: it is emitted once, and
+every module reachable from a `sandbox: true` route is still validated under
+the sandbox rules and budgets above, which does not disqualify the trusted
+route that also imports it. 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,

package/docs/VERSION-ALIGNMENT.md

@@ -1,205 +1,46 @@
-# Core version alignment across repositories
-
-Which core version each downstream package supports, how it says so, and the
-order in which a core behavior change reaches downstream repositories. This
-page is a mechanism and an invariant, not a schedule: it states no release
-cadence, no LTS line and no support window. Those are not decided.
-
-It exists because "the current core" had come to mean five different things at
-once, and one of them did not resolve. The `0.4.0-alpha.2` release closes that;
-the table below is where every repository lands, and it is the register to
-change whenever a version changes anywhere.
-
-| Repository | How it names core | Value (read from its own `package.json`/`peers.json`) |
-|---|---|---|
-| `urlcode` | source version | `0.4.0-alpha.2` |
-| `urlcode-auth`, `urlcode-admin` | peer range plus a reviewed SHA | `>=0.4.0-alpha.1 <0.5.0`; `peers.json` `urlcode` = `d5e86017e93b96ec24bfdbf840692b95fc323151` in both |
-| `urlcode-dynamic-link` | peer range | `>=0.4.0-alpha.1 <0.5.0` |
-| `urlcode-middleware` | peer range | `>=0.4.0-alpha.2 <0.5.0` |
-| `urlcode-short`, `urlcode-template`, `urlcode-docs` | exact dependency pin | `0.4.0-alpha.2` |
-
-Only `urlcode-middleware` requires `0.4.0-alpha.2` specifically: it uses the
-`middleware()` extension hook, `ExtensionActivation.root` and
-`RuntimeExtension.cacheSensitive`, none of which exist in `0.4.0-alpha.1`. The
-other extension packages work against either alpha and keep the wider floor,
-which is what the supported-floor definition below requires of them.
-
-The npm dist-tags for `@jimhoyd/urlcode` are `latest` = `0.3.0` and `alpha` =
-`0.4.0-alpha.2`. `latest` deliberately stays on the `0.3.0` Apache-2.0
-self-hosted baseline: the `0.4.0` line is a prerelease and must not become the
-default install. Every release workflow derives its dist-tag from the version
-rather than defaulting, so a prerelease can only publish under `alpha`.
-
-The sibling packages are `@jimhoyd/urlcode-ui` `0.1.0-alpha.5`,
-`@jimhoyd/urlcode-auth` and `@jimhoyd/urlcode-admin` `0.1.0-alpha.3`, and
-`@jimhoyd/urlcode-dynamic-link`, `@jimhoyd/urlcode-middleware` and
-`@jimhoyd/urlcode-short` `0.1.0-alpha.2`. For the extension line, `latest` and
-`alpha` point at the same version — see the second invariant below.
-
-Every one of those is a new version in this release. Each package's previous
-release sat at the same version number as a source tree that had moved well
-past it — 43 merged commits in `urlcode-auth`, 40 in `urlcode-ui`, 28 in
-`urlcode-admin` — so the published version number identified nothing. A
-version number that does not change when the source does is the same class of
-defect as a peer range that cannot resolve, and the rule is the same: change
-the version in the pull request that changes the source.
-
-## The supported floor
-
-The supported core floor for an extension package is the **lowest core version
-published to npm that contains every core API the extension calls**. It is a
-property of the code, not of a calendar: raise it when the extension starts
-using a core API that older published cores do not have, and not otherwise.
-
-Everything below follows from that one definition.
-
-## How a package expresses its core requirement
-
-Three forms are in use. They are not interchangeable.
-
-**Peer range (`peerDependencies`), for an extension package.** An extension is
-installed alongside core by the operator, so it must not carry its own copy;
-`peerDependencies` is the correct field. Write it as a floor plus the next
-breaking bound — `">=<floor> <0.5.0"` — where the floor is the supported floor
-above. `urlcode-auth` and `urlcode-admin` use this form.
-
-**Exact pin (`dependencies`), for an application or a starter.** A project that
-is deployed or cloned rather than composed — `urlcode-short`, `urlcode-template`,
-`urlcode-docs` — depends on one core version and pins it exactly. This is the
-right form when the repository's tests, generated files and documentation were
-all produced against one runtime and are only claimed to hold for that runtime.
-
-**Reviewed SHA (`peers.json`), for source CI on top of a range.** A reviewed
-commit is not a substitute for the peer range; it is an addition to it, used
-where the repository must build and test against an exact reviewed core
-checkout rather than whatever the registry resolves. `urlcode-auth` and
-`urlcode-admin` each keep one `peers.json` naming the reviewed core commit;
-each file states in its own `$comment` that published releases do not use those
-SHAs and resolve peers from the registry by the `package.json` range instead.
-Use a reviewed SHA when source CI needs reproducibility; do not use it to
-express what an installing operator will get.
-
-## The invariant: a published peer range must be satisfiable
-
-**A package published to npm must never declare a peer range that no published
-core version satisfies.** At publish time, at least one version on the registry
-must fall inside the range. A range that points at an unpublished core is not a
-forward-looking declaration — it is an install failure for everyone who takes
-the package from the registry.
-
-The worked example came from this project. `@jimhoyd/urlcode-middleware`
-`0.1.0-alpha.1` was published declaring `peerDependencies`
-`{"@jimhoyd/urlcode": ">=0.4.0-alpha.2"}` at a time when the registry held only
-`0.3.0` and `0.4.0-alpha.1`, so nothing satisfied it. The range was correct —
-the package genuinely needs APIs that first appear in `0.4.0-alpha.2` — so the
-fix was never to widen the range. The publication order was wrong: the package
-was published before the core it requires, and it could be installed only from
-source against a vendored core tarball carried for exactly that reason.
-
-Publishing core `0.4.0-alpha.2` resolves it without any change to the already
-published package: the range becomes satisfiable the moment core is on the
-registry. The vendored tarball and the source-only install path go away with
-it.
-
-That is what the invariant prevents, and it is the only ordering rule that
-cannot be relaxed.
-
-## The second invariant: `latest` must not fall below a sibling's floor
-
-**Where a package line publishes under a prerelease dist-tag, `latest` must
-still resolve to a version that satisfies every peer floor its siblings
-declare.** `latest` is what a plain `npm install <package>` resolves, so a
-`latest` left behind hands the installing operator a build that another
-package in the same install refuses.
-
-The worked example, again live in this project: `@jimhoyd/urlcode-auth`
-published `alpha` = `0.1.0-alpha.2` while leaving `latest` = `0.1.0-alpha.1`.
-`@jimhoyd/urlcode-admin` declares a peer floor of `>=0.1.0-alpha.2` on auth, so
-`npm install @jimhoyd/urlcode-auth` resolved a build below the floor admin
-requires. Nothing in the source is wrong; the dist-tag is.
-
-The fix is a registry operation rather than a source change:
-
-```sh
-npm dist-tag add @jimhoyd/urlcode-auth@0.1.0-alpha.2 latest
-```
-
-Core is the deliberate exception. Its `latest` stays on `0.3.0` because no
-sibling declares a floor above it — the extension packages name core through
-`peerDependencies`, which resolve by range and never by dist-tag.
-
-## A deliberate older pin is a position, not drift
-
-`urlcode-template`, `urlcode-docs` and `urlcode-short` now all pin
-`0.4.0-alpha.2`, so no downstream repository is currently behind. An older pin
-remains a legitimate position, and the rule for it does not change: it is
-recorded where a reader will meet it. The repository's README says which core
-version it pins, and every statement about runtime behavior in that repository
-is read against that version. Where a statement is only true for the pinned version, it
-says so and names the version, rather than being silently corrected to match
-core's unreleased `main`.
-
-This matters most for the trust model. Core `0.4.0-alpha.2` runs `function` and
-`middleware` routes trusted and unsandboxed by default, with `sandbox: true` as
-a per-route opt-in ([decision record](SPIKE-DEFAULT-TRUST-MODEL.md)).
-`0.4.0-alpha.1` and earlier sandbox all such code unconditionally and have no
-`sandbox` field in the schema. This is why moving a pin to `0.4.0-alpha.2` is
-a behavior change even when no YAML changes: every `function`/`middleware`
-route that does not declare `sandbox` becomes trusted on upgrade. Review those
-routes before raising a pin, and add `sandbox: true` to the ones that handle
-input or code you would not trust with full Node/filesystem/network access.
-A repository still pinned to `0.4.0-alpha.1` or `0.3.0` that documents
-sandbox-by-default is **describing its pin correctly**. Its
-generated files — field references, schemas, scaffolding output, vendored agent
-skills — are likewise correct for that pin. Divergence from core's current
-`main` is not by itself staleness, and it is not a defect to be "fixed" by
-importing behavior the pinned runtime does not have. The same point is made
-about the advisory `npm run check:downstream-skills` report in
-[release readiness](RELEASE-READINESS.md).
-
-What is a defect: a repository that does not say which core version it pins, or
-that states pin-dependent behavior as an unconditional property of URLCode.
-
-## Order of operations when core changes behavior
-
-A core behavior change reaches downstream repositories in this order. Each step
-depends on the one before it; skipping ahead is what produced the
-`urlcode-middleware` breakage above.
-
-1. **Publish core.** The version carrying the change goes to npm first. Until it
-   is on the registry, no downstream peer range may reference it (the invariant
-   above).
-2. **Raise downstream floors.** Extension packages move their peer range floor
-   to the published version; applications and starters move their exact pin.
-   A repository that chooses to stay on the older core does nothing here — that
-   is a valid outcome, and step 3 does not apply to it.
-3. **Regenerate downstream generated files.** Field references, schemas,
-   scaffolding output and vendored agent skills are regenerated *after* the
-   floor moves, against the version now pinned — never before, or they describe
-   a runtime the repository does not depend on.
-
-Reviewed-SHA repositories take the same three steps, and additionally update
-`peers.json` to the reviewed commit for the new core when source CI is expected
-to build against it. The SHA and the published floor answer different questions
-and are updated independently.
-
-## Open: two publishing conventions
-
-The repositories publish under two different conventions, and the maintainer has
-not settled which one the project uses. Both are recorded here neutrally; this
-page does not pick one.
-
-- **Private until release.** `urlcode-dynamic-link` and `urlcode-middleware`
-  keep `"private": true` in their `package.json` on `main` and drop it in the
-  release commit. Publication is an explicit, visible act in the release diff,
-  and an accidental `npm publish` from `main` fails closed. Both packages are
-  nonetheless published on npm, so the convention has been exercised.
-- **Publishable on main.** `urlcode-auth`, `urlcode-admin` and `urlcode-ui`
-  carry no `private` field and declare `publishConfig.access = "public"`
-  instead. The committed manifest is
-  the manifest that publishes, so what is on the registry can be diffed against
-  `main` without accounting for a release-only edit.
-
-The split is currently by repository, not by package kind, and nothing records
-why. Settling it is a maintainer decision; no `package.json` is changed on the
-strength of this page.
+# Package and channel alignment
+
+The package manifests and root lockfile are the version authority. Read live
+registry and Git tag state with `npm run release:status`; do not maintain a
+second table of changing version numbers in documentation.
+
+| Package | Manifest | Version owner | Release tag |
+| --- | --- | --- | --- |
+| `@jimhoyd/urlcode` | `package.json` | Explicit core release PR | `v<version>` |
+| `@jimhoyd/urlcode-ui` | `packages/ui/package.json` | Changesets | `@jimhoyd/urlcode-ui@<version>` |
+| `@jimhoyd/urlcode-auth` | `packages/auth/package.json` | Changesets | `@jimhoyd/urlcode-auth@<version>` |
+| `@jimhoyd/urlcode-admin` | `packages/admin/package.json` | Changesets | `@jimhoyd/urlcode-admin@<version>` |
+
+Development uses workspace source. Auth and admin's `file:../..` development
+links resolve core to this checkout, enforced by `check-workspace-links.ts`.
+Core never imports extension packages. Release verification instead installs the
+published lower bound of each declared peer range and checks resolution. A peer
+floor rises when code requires a newly introduced API, not just because a sibling
+published another version. Preserve the declared upper bound during Changesets
+versioning; `.changeset/config.json` limits unnecessary peer rewrites.
+
+Publishable workspace changes carry Changesets; the release PR applies them and
+updates versions, changelogs and the lockfile together. Core stays an explicit
+entry in that PR until a separately reviewed workspace migration. Its CLI banner
+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.
+
+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.
+
+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
+`urlcode-docs`, `urlcode-middleware`, `urlcode-dynamic-link` and `urlcode-short`
+repositories are not release targets.
+
+See [the development pipeline](DEVELOPMENT-PIPELINE.md) for preparation,
+publication order, immutable retries and credential scope, and
+[release security](RELEASE-SECURITY.md) for provenance and limitations.

package/docs/archive/2026-09-19/EXTENSION-IMPLEMENTATION.md

@@ -0,0 +1,68 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
+# Extension implementation sequence
+
+PR #54 records the auth, admin, UI and extension direction. Implementation is
+incremental; the spikes are proposals, not the implemented project schema.
+The implemented specification remains authoritative. This sequence incorporates
+the architectural review rather than treating contradictory spike examples as
+requirements.
+
+## Invariants
+
+- Operators explicitly install trusted host extensions; project YAML never loads
+  host modules or chooses packages. Application code remains isolated in WASM.
+- Authentication credentials stay in host processing. Guest Request headers and
+  header-derived parameters must not expose operator-declared credential headers,
+  including on public routes receiving a session cookie.
+- Session and one-time-token changes have explicit concurrency semantics. Define
+  atomic operations before selecting a database abstraction; multi-record
+  operations cannot rely on a same-collection transaction promise.
+- Passwords and bearer credentials use appropriate hashes. TOTP requires protected
+  recoverable key material and an operator key rotation/backup contract.
+- Authentication forms and submission destinations belong to trusted extension
+  code. Project styling does not imply permission to replace security controls.
+- Administrative authorization is enforced by the API, including subject-level
+  restrictions, self-promotion and last-administrator protections.
+- Unsupported target capabilities fail explicitly. Live provider deployment
+  testing remains deferred and non-blocking; local tests do not prove deployment.
+
+## Delivery order
+
+1. **Credential boundary:** add an explicit host-plugin declaration for headers
+   withheld from guest requests and parameter resolution. Preserve originals for
+   host authentication, cache decisions and policy processing. Test functions,
+   middleware and routes without an authentication requirement.
+2. **Extension registration:** explicit operator registry, versioned configuration
+   validation, route ownership/collision rules and capability reporting. No
+   automatic project host-file execution. Define policy ordering before adding
+   an auth policy.
+3. **Session slice:** one supported login method, trusted login/logout forms,
+   protected page and JSON routes, session lookup/revocation, CSRF and no-store
+   behavior. Evaluate a maintained authentication implementation behind an
+   adapter before writing protocol engines. Define durable atomic store methods
+   and test concurrent redemption, expiry and interrupted operations.
+4. **Administrative API and CLI:** user lookup and session revocation first;
+   audit records and narrowly scoped permissions. Add role/recovery operations
+   only with object-level rules and concurrency tests.
+5. **UI and console:** extract components from real auth/admin flows; choose a
+   constrained renderer and asset ownership model; verify keyboard and assistive
+   technology behavior as well as automated accessibility checks.
+6. **Additional methods and targets:** passkeys, OIDC, MFA, recovery and imports
+   each receive state-machine, abuse-budget and portability tests. Preserve
+   verification of existing credential formats across target migrations.
+
+## Status
+
+PR #54 is merged. The first implementation adds the operator-only
+`Plugin.credentialHeaders` boundary, documented in [Plugins](../../PLUGINS.md).
+The remaining items are pending; none of this document declares end-user auth,
+admin routes, extension YAML, or a generic project store available today.