@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.1

package/docs/STARTERS.md

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

package/docs/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

@@ -81,10 +81,12 @@ network. Keys always appear in this order:
   `--host-file`, `host` counts the operator module's extensions and plugins
   without activating them.
 - `routes`: path, methods and handler per route, sorted by path.
-- `constraints`: a fixed list that holds for every project (no guest network,
-  no Node APIs, no regex routes, one handler per route, exact or `{param}`
-  path segments, subtree mounts only for static and extension routes, no YAML
-  interpolation, secrets by operator grant only), each with a value and a note.
+- `constraints`: a fixed list that holds for every project (network and Node
+  built-ins available to trusted code and withdrawn by `sandbox: true`, no
+  regex routes, one handler per route, exact or `{param}` path segments,
+  subtree mounts only for static and extension routes, no YAML interpolation,
+  injected `env`/`secrets` by operator grant only), each with a value and a
+  note spelling out how it differs between the two trust modes.
 - `targets`: for each capability target (or the one `--target`), which of this
   project's used features are supported, conditional, refused or unknown.
 - `commands`: the exact `validate`, `test`, `audit --expect-routes N` (N is
@@ -137,8 +139,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 +150,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/VERCEL.md

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

package/docs/VERSION-ALIGNMENT.md

@@ -1,205 +1,80 @@
-# 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:
+# 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.
+
+The `0.4.1` release is an explicit stable release decision for core, UI, auth
+and admin. Publication moves each package's npm `latest` channel to `0.4.1`, in
+core → UI → auth → admin order, after its release checks pass. A prepared
+manifest or merged release PR does not prove registry publication: use
+`npm run release:status` to inspect the live result before installing the set.
+This alignment does not permanently couple package versions; subsequent
+releases can still select only the packages that changed.
+
+Alpha releases publish under `alpha`; they never automatically move npm
+`latest`. Stable publication does not move `alpha`, so the two channels can
+legitimately show different versions. Test the install combination you recommend
+against peer ranges. `release:status` reports each declared peer floor and
+whether its current `latest` and `alpha` satisfy the range.
+
+After all four `0.4.1` versions are published, install the aligned set with:
 
 ```sh
-npm dist-tag add @jimhoyd/urlcode-auth@0.1.0-alpha.2 latest
+npm install --save-exact @jimhoyd/urlcode@0.4.1 @jimhoyd/urlcode-ui@0.4.1 @jimhoyd/urlcode-auth@0.4.1 @jimhoyd/urlcode-admin@0.4.1
 ```
 
-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.
+Bare package names resolve npm's current `latest`; exact application pins and a
+committed lockfile keep an existing application from changing on a new release.
+
+## Generated applications
+
+A generated application records its own versions. `urlcode init --with` writes a
+`package.json` pinning the running runtime, the named extensions and their
+declared peers at the exact versions resolved at generation time, after checking
+that set against every declared peer range; `urlcode init --manifest` does the
+same for a route-only project with the runtime alone; `urlcode-auth init` pins
+this package and its peers. Plain `urlcode init` stays route-only and writes no
+manifest, for projects whose runtime is managed elsewhere. Generation never runs
+a package manager: `package-lock.json` exists only after the operator runs
+`npm install` in the generated directory, and a pin taken from a local path or
+tarball reproduces only where that path exists.
+
+No upgrade command exists. A generated project moves to new versions by an
+operator editing its manifest and re-installing. The issue that asked for this
+(#212) describes a future command that would choose a tested compatible set,
+show the changes and require explicit alpha selection; nothing here implements
+that, and the pins above are only the groundwork it would need.
+
+The standalone `urlcode-template` is an external exact-version consumer: after a
+runtime release, update its dependency and starter through its own reviewed PR.
+The coordinator prepares and checks that PR after registry installation succeeds;
+the template is a consumer update, not a fifth npm package. The retired
+`urlcode-docs`, `urlcode-middleware`, `urlcode-dynamic-link` and `urlcode-short`
+repositories are not release targets.
+
+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.