@jimhoyd/urlcode 0.4.1 → 0.4.6

package/docs/AWS.md

@@ -1,86 +0,0 @@
-# Deploying to AWS Lambda
-
-The AWS adapter runs a URLCode project as a Lambda function behind a **Function
-URL** or an **API Gateway HTTP API**. The same `urlcode.yaml` that runs locally
-or in a container serves the deployment.
-
-**This adapter serves native handlers only** — redirects, validated responses,
-pages, static assets and downloads — for the same reasons as
-[the Vercel adapter](VERCEL.md): `function` and `middleware` routes need the
-self-hosted Node lifecycle, and a `sandbox: true` route would pay worker and
-WASM startup on every cold start. Both are refused at activation with the route
-named, never per request, trusted or sandboxed alike.
-
-That refusal is a settled position, not a gap awaiting an adapter: per-route
-Lambda compilation was considered and declined
-([the decision](OPEN-DECISIONS.md#accepted-one-node-deployment-per-project),
-[the analysis behind it](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md)). A project that uses
-`function` or `middleware` deploys instead as one trusted Node process — a
-container or a VM running the project as it runs locally — which supports every
-route type today. That process can run on AWS: ECS, EC2 and App Runner all
-serve it. The decision is about the execution model, not about avoiding AWS.
-
-A working project is in [`examples/aws/`](../examples/aws/).
-
-## Set it up
-
-```js
-// handler.mjs
-import { createLambdaHandler } from '@jimhoyd/urlcode/aws';
-
-export const handler = createLambdaHandler({ project: process.env.LAMBDA_TASK_ROOT });
-```
-
-The deployment package must contain every file the project reads: the entry
-YAML, any `includes`, and every page, download and static directory. They are
-read at activation, so a missing one fails the deployment rather than one route.
-Node 22.13 or newer.
-
-## Payload format 2.0 only
-
-Function URLs and API Gateway **HTTP APIs** send payload format 2.0, which
-carries `rawPath` and `rawQueryString` — the request as it arrived.
-
-A **REST API** sends format 1.0, which supplies the path and query already
-decoded. The original bytes cannot be recovered from them, and this runtime
-rejects ambiguous encoding deliberately: rebuilding a target from decoded parts
-would either re-encode differently than the client sent or quietly accept what
-the runtime refuses. Rather than guess, the adapter refuses a 1.0 event and says
-why. Front the function with an HTTP API, or run the container image with
-`urlcode serve`.
-
-## Bindings and origin
-
-`URLCODE_POLICY` carries the same grant document the operator policy file holds,
-validated identically including the `projectSha256` pin — see
-[the Vercel guide](VERCEL.md#bindings), which describes the same mechanism.
-Store it in the function's environment, or fetch it from Secrets Manager and set
-it before the handler is created.
-
-`URLCODE_PUBLIC_HOST` sets the public hostname for generated URLs. Lambda has no
-platform variable naming your domain, so unlike Vercel there is nothing to infer
-from: set it when a custom domain or an API Gateway stage prefix is in play.
-Forwarded headers stay untrusted.
-
-## Limits worth knowing before you deploy
-
-| Limit | Consequence |
-|---|---|
-| Lambda response payload is 6 MB | A larger asset cannot be returned. The runtime allows 16 MB per asset, so a project valid self-hosted can exceed what Lambda can send. Keep large files in object storage and redirect to them. |
-| Response bodies are base64-encoded | Guessing whether a body is text is how binary assets get corrupted, so every response is encoded. Base64 inflates by about a third, against that 6 MB ceiling. |
-| Each execution environment activates independently | Parsing, asset snapshotting and route compilation happen per cold start, and the [capacity limits](CAPACITY.md) apply per instance: a 64 MiB snapshot is 64 MiB in every concurrent one. |
-| No reload | A deployment serves the revision it was packaged from. Ship a change by deploying. |
-| No `/_urlcode/health` or `/_urlcode/ready` | Those describe a long-lived process. Use Lambda's own metrics; the [monitoring recipes](MONITORING.md) that parse stdout records need adapting for CloudWatch, though the record fields are the same. |
-
-## Verification status
-
-The adapter is tested against the self-hosted runtime for identical status, body
-and headers across redirects, parameters, responses, pages, static files and
-misses; for format 1.0 and malformed events being refused; for base64 request
-bodies and route body policy; for cookies arriving and leaving through the
-format 2.0 array; and for the policy pin.
-
-**It has not been deployed to AWS.** The tests drive the real handler with real
-payload format 2.0 events, but no invocation on Lambda has happened. Treat
-package contents, cold-start latency, API Gateway's own header handling and the
-6 MB ceiling as unverified until you deploy the example and see it work.

package/docs/BEST-PRACTICES.md

@@ -1,276 +0,0 @@
-# Organization and readability
-
-These are conventions for URLCode applications, not extra schema requirements.
-Choose the smallest structure that makes a route easy to find, understand and
-test. Preserve an existing project's conventions unless there is a clear reason
-to change them. See [file composition](ORGANIZATION.md) for enforced rules and
-[the YAML guide](YAML-GUIDE.md) for supported features.
-
-## Start small, split by responsibility
-
-The default starter's two routes do not need a framework or many abstraction
-layers. A small project can keep all definitions in `urlcode.yaml`:
-
-```text
-my-links/
-  urlcode.yaml
-  functions/
-    welcome.mjs
-  middleware/
-    response-headers.mjs
-  public/
-    guide.txt
-  tests/
-    requests.json
-  README.md
-```
-
-Create only the folders you use. When navigation or ownership becomes difficult,
-group by feature, audience or campaign, rather than creating one YAML file per
-short link. There is no universal file-size threshold; split when a reviewer can
-no longer follow the changes comfortably. Thousands of redirects usually belong
-in a few meaningful collections, not thousands of include entries.
-
-For a growing application, colocating feature-specific code is often clearer:
-
-```text
-my-links/
-  urlcode.yaml
-  features/
-    welcome/
-      routes.yaml
-      welcome.mjs
-      greeting.mjs
-    campaigns/
-      routes.yaml
-  middleware/
-    response-headers.mjs
-  public/
-    guide.txt
-  tests/
-    requests.json
-  README.md
-```
-
-The root remains a short explicit table of contents:
-
-```yaml
-version: "1"
-includes:
-  - features/welcome/routes.yaml
-  - features/campaigns/routes.yaml
-routes: {}
-```
-
-Each included file has its own `version: "1"` and `routes`. Do not add recursive
-includes, glob patterns or inherited defaults. Folder names never change public
-URLs. Keep the two styles available: folders by file type for small apps, or by
-feature when it improves ownership. Neither requires forking the runtime.
-
-## Make a route readable from top to bottom
-
-Use two spaces, no tabs, and one consistent key order. A useful order is:
-`description`, lifecycle (`enabled`/`expires`), `methods`, `parameters`,
-`request`, bindings (`env`/`secrets`), `middleware`, the handler, then `response`.
-This is visual organization, not an execution-order declaration.
-
-Use block style for nested behavior. Short scalar lists such as `[GET, HEAD]`
-and small leaf schemas such as `{type: string}` can stay inline. Omit ordinary
-defaults unless making them explicit clarifies a decision. Quote timestamps and
-numeric-looking header values. Avoid unrelated reformatting when changing a route.
-
-Example `features/welcome/routes.yaml`:
-
-```yaml
-version: "1"
-routes:
-  /welcome/{name}:
-    description: A personalized welcome message with a consistent response header
-    parameters:
-      - name: name
-        in: path
-        required: true
-        schema:
-          type: string
-          minLength: 1
-          maxLength: 80
-    middleware:
-      - source: middleware/response-headers.mjs
-    function:
-      source: features/welcome/welcome.mjs
-      args:
-        name: {from: path, name: name}
-    response:
-      headers:
-        Cache-Control: no-store
-```
-
-Example `features/campaigns/routes.yaml`:
-
-```yaml
-version: "1"
-routes:
-  /guide:
-    # Keep this temporary so a campaign destination can change later.
-    redirect:
-      url: https://example.com/guide
-```
-
-Use comments for the reason behind a choice, migration notes or a business rule.
-Do not narrate obvious syntax or include secrets, private customer details or
-stale deployment instructions. `description` is useful authoring metadata; do
-not invent `owner`, `tags` or other unsupported YAML fields. Record ownership in
-the README or repository tooling instead.
-
-Order routes consistently within each collection, such as alphabetically or by
-business flow. Do not rely on file order for precedence: exact routes win before
-parameter routes, then static mounts. Avoid ambiguous overlaps; see [routing](ROUTING.md).
-
-## Keep handlers short and name their job
-
-Name files for behavior (`welcome.mjs`, `select-destination.mjs`) rather than
-`utils2.mjs` or `handler-final.mjs`. Name exports clearly even when using a default
-export. Use descriptive variables and early returns for error cases. Separate
-business transformations from Request/Response handling when that improves clarity.
-Do not extract a one-line helper merely to create more files.
-
-`features/welcome/welcome.mjs`:
-
-```js
-import {formatGreeting} from './greeting.mjs';
-
-export default function welcome(request, {args}) {
-  return Response.json({message: formatGreeting(args.name)});
-}
-```
-
-`features/welcome/greeting.mjs`:
-
-```js
-export function formatGreeting(name) {
-  return `Hello, ${name}!`;
-}
-```
-
-YAML `source` paths are project-root relative. JavaScript imports are relative to
-the importing module. Explicit `.mjs` filenames make that distinction clear.
-Only relative project JavaScript imports are supported; do not introduce npm,
-Node, remote imports or a transpilation requirement accidentally. There is a
-project-wide module/source budget; excessive fragmentation has a real limit.
-
-Use validated `args` and `inputs` instead of parsing query strings again. Return
-JSON through `Response.json`; escape user data explicitly when producing HTML.
-For dynamic redirects, map a validated enum to known destinations rather than
-accepting any user-controlled URL. Keep modules free of top-level work other than
-simple definitions: initialization runs during validation and fresh invocations.
-
-Prefer pure helpers with explicit inputs and outputs. Module globals are not a
-cache, database, session store or rate limiter: guest state resets per request
-regardless of trust mode. If a route declares `sandbox: true`, review
-[sandbox constraints](FUNCTION-SECURITY.md) before choosing dependencies —
-trusted (default) routes have ordinary Node module access instead.
-
-## Middleware should have one clear responsibility
-
-`middleware/response-headers.mjs`:
-
-```js
-export default async function responseHeaders(request, context, next) {
-  const response = await next();
-  response.headers.set('x-app', 'my-links');
-  return response;
-}
-```
-
-Use middleware for reusable behavior around a handler, not to conceal the entire
-application flow. Prefer YAML headers for fixed route-specific headers; this
-example demonstrates a shared wrapper, but native YAML avoids any
-function/middleware invocation overhead when no custom code is needed —
-including the extra cost of `sandbox: true` where that is declared. Keep
-middleware order explicit in each route.
-
-Always return a Response. Call `await next()` once when continuing, or return
-an early Response when intentionally stopping. Do not launch unawaited work or
-assume background tasks will survive. A body read consumes the request body;
-if downstream code needs parsed data, agree on a documented `context.state` field.
-Use specific field names to avoid collisions among middleware.
-
-Catch only errors you can handle meaningfully. Do not turn every failure into a
-200 response or include secrets in errors. Keep native body/status/header
-preservation rules visible in code review. All middleware share the route's
-bindings and execution budget; splitting modules does not create privilege
-separation. See [middleware semantics](MIDDLEWARE.md).
-
-## Organize tests around observable behavior
-
-Keep runnable HTTP assertions in `tests/requests.json`, currently the single file
-read by the CLI. Group adjacent cases by route: ordinary success, HEAD, boundary
-inputs, invalid input, wrong method and relevant early responses. Add meaningful
-body/header checks instead of relying only on status codes.
-
-For the two-route feature layout above:
-
-```json
-[
-  {"path":"/welcome/Ada","status":200,"expectBody":"{\"message\":\"Hello, Ada!\"}","expectHeaders":{"x-app":"my-links"}},
-  {"path":"/welcome/Ada","method":"HEAD","status":200,"expectBody":"","expectHeaders":{"x-app":"my-links"}},
-  {"path":"/welcome/Ada","method":"POST","status":405,"expectHeaders":{"allow":"GET, HEAD"}},
-  {"path":"/guide","status":302,"expectHeaders":{"location":"https://example.com/guide"}},
-  {"path":"/guide","method":"HEAD","status":302,"expectBody":"","expectHeaders":{"location":"https://example.com/guide"}}
-]
-```
-
-Additional ordinary JavaScript unit tests for pure helpers are your project's
-choice. Unit tests alone do not verify runtime compatibility — including the
-guest API restrictions of a route declaring `sandbox: true` — or HTTP framing:
-always exercise HTTP behavior through URLCode too. Keep large fixture generation explicit and
-deterministic if you add your own tooling; nested test directories and JSON
-fragments are not automatically discovered or merged by URLCode.
-
-Assert observable contracts, not incidental timings or internal variable names.
-Avoid checking generated request IDs, current Date values or performance numbers
-as fixed functional outputs. Test cache/range semantics with controlled assets.
-Update expected route counts deliberately when adding or removing a route.
-
-## Keep configuration, code, assets and operations separate
-
-- Git owns behavior and reviewed code. Keep the runtime as a pinned dependency;
-  upgrading it should not regenerate or overwrite application files.
-- Publish only intentionally public files in `public/`. File filters cannot
-  recognize every secret. A harmless filename is not proof of public content.
-- Put local secrets in ignored `.env.local`; production values come from the
-  operator. Keep operator grants outside the application checkout. Never use
-  YAML anchors, shell expansion or generated credentials for convenience.
-- Deployment limits, TLS, DNS, DDoS filters and worker tuning belong to operations,
-  not invented route fields. Document them separately from portable behavior.
-- Live short-code records need durable storage core does not have. The
-  `urlcode-dynamic-link` extension provided it and has been retired; its
-  published `0.1.0-alpha.1` pins core `0.4.0-alpha.1` exactly and so cannot be
-  installed beside `0.4.0-alpha.2`. Treat stored short links as unsupported
-  until that work lands somewhere else. General session/application storage
-  remains future work.
-
-## Refactor without changing the public contract
-
-Move one feature at a time. Update explicit includes and project-root source/asset
-paths, then check relative JavaScript imports. Keep public route paths, methods,
-headers and bodies stable unless the change is intentional. Avoid mixing URL
-renames, dependency upgrades and folder rearrangement in one review.
-
-Run validate, HTTP tests and the expected-count audit before and after moving
-files. Re-review operator grants: code/config changes invalidate the digest even
-when intended behavior is unchanged. A successful dev reload is not a production
-deployment. Record activation/rollback steps in the project README.
-
-## A useful project README
-
-Document how to install the pinned runtime, start locally, run tests/audit, and
-activate a release. Include a small folder map, the owner of each major feature,
-public route behavior and required external binding names (never values). State
-supported Node/runtime versions and link to matching URLCode docs. Explain any
-middleware ordering or surprising defaults that a new maintainer might miss.
-
-For AI-generated changes, require the assistant to follow existing conventions,
-keep diffs focused, add response assertions and report checks actually run. Reject
-invented YAML keys, hidden side effects and unnecessary abstractions. The
-[AI authoring guide](AI-AUTHORING.md) provides a reusable prompt and capability list.

package/docs/BULK.md

@@ -1,79 +0,0 @@
-# Bulk redirect projects
-
-Bulk import converts CSV, JSON or YAML redirect rows into an ordinary Git-owned
-URLCode project. It delegates semantics and row diagnostics to the strict
-[redirect interchange](INTERCHANGE.md) converter. Only literal paths and
-absolute HTTP(S) redirect destinations are accepted; unsupported behavior and
-duplicate paths fail rather than being discarded or overwritten.
-
-```sh
-urlcode bulk-import csv redirects.csv --out ./imported --dry-run
-urlcode bulk-import csv redirects.csv --out ./imported
-urlcode validate --local --project ./imported
-```
-
-CSV requires the header `path,url,status`; status can be empty for 302. JSON and
-YAML are arrays of `{path, url, status?}` rows. Input is limited to 32 MiB and
-100,000 routes. This command is for data import, not arbitrary provider config.
-Use explicit provider interchange commands when migrating provider files.
-
-The SDK provides
-`importBulkProject(text, format, output, {dryRun, source})`. `format` is `csv`,
-`json` or `yaml`. The report includes `ok`, `routeCount`, source/row diagnostics,
-a SHA-256 fingerprint of the exact input text, and a bounded output-file plan.
-Invalid input returns `ok: false` without writing files. Filesystem/output
-refusals throw. `source` is a caller-supplied provenance label, not a file to read.
-
-Routes are sorted by literal path and divided into include files with at most
-1,000 routes each. At 100,000 routes this produces 100 include files. The entry
-`urlcode.yaml` holds the include list and empty `routes`. `provenance.json`
-records the source label, input fingerprint, counts and each shard's first/last
-path. It does not embed the original input or claim exact source line mappings
-for successful output rows; retain the original file in version control if that
-traceability is needed. Invalid row diagnostics preserve their source positions.
-
-Dry-run performs conversion and output planning without writing the requested
-destination. Import requires a new output directory under an existing parent;
-there is no implicit merge or overwrite mode. As with recipes, dependencies are
-written first and a rename publishes the completed entry YAML last. Failed
-writes clean up the directory created by that invocation. Source data is never
-interpreted as shell code. The caller must control the output parent while
-publishing.
-
-## Local scale evidence
-
-Run each dataset in a fresh process, sequentially, without concurrent builds:
-
-```sh
-node benchmarks/bulk.ts 1000
-node benchmarks/bulk.ts 10000
-node benchmarks/bulk.ts 100000
-```
-
-Observed on 2026-09-17 against the final integrated next-phase working tree,
-with the merged TypeScript 6.0.3 dependency lock, Node v26.8.2, macOS arm64,
-Apple M4 Pro and 48 GiB system memory. These measurements include the final
-capability, revision-pin and egress activation paths. Synthetic routes redirect `/rN` to `https://example.com/items/N`.
-Conversion includes input validation, semantic compilation and sharded output
-publication; activation uses the normal `createRuntime` loader and compiler.
-Lookup measures 5,000 `Runtime.handle` requests at concurrency one after 100
-warm-up requests, validating each status and Location. It excludes socket/TLS
-transport. Memory is sampled process RSS/heap after phases, not peak memory or
-an isolated worker measurement.
-
-| Routes | Includes | Conversion ms | Activation ms | RSS after activation MiB | Heap MiB | Lookup p95 ms |
-| ---: | ---: | ---: | ---: | ---: | ---: | ---: |
-| 1,000 | 1 | 56 | 139 | 180 | 27 | 0.002292 |
-| 10,000 | 10 | 272 | 373 | 288 | 46 | 0.002916 |
-| 100,000 | 100 | 5,530 | 8,838 | 537 | 214 | 0.003791 |
-
-All three sequential fresh-process datasets activated and returned the expected
-redirects. These are single observations, not a repeated-run statistical study;
-background host load can change startup and memory measurements. Unlike the
-previous single-document 100,000-route routing benchmark, the sharded project
-fits the existing configuration worker's 256 MiB heap and 10-second deadline.
-No loader, route-count, compiler deadline or runtime safety limit was increased.
-This local result does not establish cross-platform capacity, provider
-performance, peak-memory bounds, concurrency/soak behavior or production SLOs.
-The benchmark reports failure phase and error if a limit is reached on another
-machine; it does not retry with relaxed limits.

package/docs/CAPABILITIES.md

@@ -1,192 +0,0 @@
-# Capabilities and normalized route representation
-
-URLCode is a portable runtime for programmable URL behavior: **URL behavior as
-code**. YAML describes behavior; operators supply infrastructure and authority.
-
-## Inspect target support
-
-```sh
-urlcode capabilities
-urlcode capabilities --target self-hosted
-urlcode capabilities --target cloudflare --json
-urlcode capabilities --target aws
-urlcode capabilities --target vercel
-urlcode capabilities --target static
-```
-
-This command needs no project or credentials. `node` is an alias for
-`self-hosted`, matching the existing embedding API. Unknown target names fail.
-JSON has `format: 1`, target deployment evidence and capability rows.
-`doctor` also reports `capabilityTargets`; its `providers` list remains empty
-because no provider deployment has been verified. Canonical
-names follow the schema (`respond`, `extension`, `policies.security`), not
-marketing synonyms. `proxy` and `signals` are self-hosted capabilities requiring
-external revision-pinned origin grants. `conditions` (`match`) and `conditional`
-(disjoint cases) are supported by self-hosted/AWS/Vercel and refused by
-Cloudflare (no artifact lowering yet) and by `static` (no server to match a
-request against). `extension`/`policies.extensions` report per-extension
-support from the registered extension's own declared `targets` when a
-`--host-file` is supplied; without one they report `conditional`/`unknown`
-rather than a blanket answer. See [egress](EGRESS.md) and
-[conditions](CONDITIONS.md).
-
-| Support | Meaning |
-| --- | --- |
-| native | Implemented by the local runtime or Node adapter |
-| compiled | Implemented by the Cloudflare or static-hosting compiler and its runtime/build output |
-| conditional | Depends on configuration; inspect the actual project |
-| delegated | Existing policy contract relies on provider behavior |
-| refused | No implementation that this target can activate |
-| unknown | No support evidence; fail closed during project analysis |
-
-`native` and `compiled` describe local implementation tests. AWS, Vercel,
-Cloudflare and static deployment evidence remains **unverified**. This is not a
-blanket exact-portability promise. Cloudflare coalesces duplicate headers and
-receives a normalized Request target; AWS accepts payload v2 only; `static` has
-no server at all, so it refuses every capability that needs one (parameters,
-request bodies, response headers, bindings, every `policies.*`) in addition to
-`function`/`middleware`. See [Cloudflare](CLOUDFLARE.md), [AWS](AWS.md),
-[Vercel](VERCEL.md) and [static hosting](STATIC.md) for transport and fidelity
-limits. Compression is explicitly delegated, not verified equivalent to
-operator-selected settings. Route throttle counters and caches remain per
-instance. No supported entry bypasses semantic validation, required operator
-grants or deployment prerequisites.
-
-## One capability or one schema fragment
-
-```sh
-urlcode capabilities redirect
-urlcode capabilities policies.throttle --json
-urlcode schema route
-urlcode schema policies.cache --json
-urlcode schema site.sitemap --yaml
-```
-
-`urlcode capabilities <name>` prints one catalog entry: its kind (handler,
-policy, routing, request, binding, egress, middleware or project), a summary,
-the resolved schema fragment(s), constraints, the operator grants the capability
-needs at activation, support per target, the targets that refuse it, and the
-bundled recipes and cookbook routes that use it. Names are the catalog names
-(`redirect`, `bindings`, `policies.cache`); an unknown name fails with exit 1
-and lists the valid names. `--target` applies to the full catalog only.
-
-`urlcode schema <path>` prints only that fragment of
-`schemas/urlcode.schema.json` with local `$ref`s resolved inline. Paths are
-top-level document keys (`routes`, `policies`, `site`, `extensions`), `route`,
-or a route property (`redirect`, `middleware`, `match`, `env`), optionally
-followed by nested property names (`policies.cache`, `request.body`,
-`site.sitemap`). Resolution is bounded and cycle-safe; where a nested object is
-its own path (`route` inside `routes`, `policies` inside `route`) it is
-summarized with a `$comment` naming that path so every fragment stays under
-16 KiB. Fragments describe shape only: they carry no defaults, validation
-result or operator authority, and the full schema remains the contract.
-
-Both commands read bundled package data and need no project, credentials or
-network. The SDK exposes them as `getCapability(name)` and
-`getSchemaFragment(path)`; the MCP server as `get_capability` and `get_schema`
-(see [tooling](TOOLING.md)). Grant descriptions name the operator flag or policy
-involved, never binding values.
-
-## Programmatic analysis
-
-The main package exports `getCapabilities`, `routeCapabilities`,
-`analyzeProjectCapabilities`, `analyzeCompiledCapabilities`,
-`assertTargetCompatibility`, `normalizeCapabilityTarget` and their report types.
-
-```js
-import { loadDocument, analyzeProjectCapabilities,
-  assertTargetCompatibility } from '@jimhoyd/urlcode';
-
-const loaded = await loadDocument('./project');
-const report = analyzeProjectCapabilities(loaded, 'cloudflare');
-console.log(report.issues); // path, capability, support, reason; never binding values
-assertTargetCompatibility(report);
-```
-
-This low-level example examines declared routes. Runtime activation and builds
-first expand `site` conventions using the operator origin, then analyze all
-routes including generated ones. A report is a compatibility preflight, **not**
-a substitute for compilation/validation. Disabled and expired routes are still
-checked. `analyzeProjectCapabilities`/`analyzeCompiledCapabilities` take an
-optional resolved extension registration set (the same shape `--host-file`
-loads); pass it to get per-extension `refused`/`native` from that extension's
-own `targets` instead of the generic `conditional`/`unknown` answer.
-`compatible` means there are no refused, unknown or unresolved conditional
-requirements. Explicit delegation and transport limitations still apply.
-
-Requirements include effective inherited/profile policies after route overrides
-and `false` removals. Policy modules' existing `targets(config)` functions remain
-the source of policy decisions. The catalog says serverless throttle is
-conditional; a project report resolves `partition: route` to native and the
-client partitions to refused. Reports contain paths and capability facts, not
-sources, destinations, binding names/values, code, validator closures or assets.
-
-Build/activation refusals aggregate all incompatible requirements and name each
-route, capability, target and reason before any artifact files are written.
-Unsupported bindings on Cloudflare fail before credentials are resolved.
-
-## Existing IR, formalized
-
-The implementation already has a useful internal representation:
-
-```text
-strict YAML + schema validation + includes
-  → site expansion
-  → shared capability preflight (declarations, no credentials)
-  → semantic route compilation
-  → CompiledRouteTable / CompiledRoute
-  → capability analysis / target lowering
-  → host assets + policy chains + trusted or isolated function dispatch, or Worker artifact
-```
-
-`CompiledRoute` in `src/types.ts` extends shared `MatchableRoute` with validated
-parameters, normalized HTTP replies/headers, resolved bindings and source
-references. `CompiledRouteTable` indexes literal paths, parameter buckets and
-static mounts. `router.ts` owns precedence, collision checks, default methods,
-input/reference validation and normalization. `match.ts` supplies portable
-request-time matching to both runtime and Worker. No second parser or competing
-route IR is introduced.
-
-`routeCapabilities` is a value-free projection used for both declaration
-preflight and compiled analysis. Preflight deliberately precedes full semantic
-validation to report unsupported features before reading missing assets or
-resolving secrets; it cannot authorize or validate a project. Normal compilation
-and policy validation still run. AWS/Vercel consume the shared runtime IR;
-Cloudflare additionally analyzes the compiled table before serializing its
-allowlisted artifact fields and standalone validators.
-
-The compiled table is internal, mutable during activation and **not serializable
-as an interchange contract**: bindings contain resolved secrets, validators are
-functions, assets contain bytes and policy chains own host state. The existing
-Cloudflare artifact is a separate versioned lowering, not a replacement IR.
-[Interchange](INTERCHANGE.md) projects a validated literal-redirect subset and
-explicitly reports unsupported semantics; it never dumps compiled routes.
-The next-phase schema extends this same IR with normalized condition cases,
-proxy headers and signal definitions. Resolved egress headers are private runtime
-state and must never be serialized. Capability analysis itself adds no authority
-and does not run in the request path.
-
-See the [repository review and incremental plan](archive/2026-09-19/NEXT-PHASE-PLAN.md) for the
-implementation status. Provider deployment tests, independent security review and
-operational soak/recovery proof are separate work.
-
-## Local performance check
-
-2026-09-17, Node 26.8.2, macOS arm64, Apple M4 Pro, 48 GiB RAM.
-`npm run benchmark -- <count>` runs 5,000 loopback requests at concurrency 16.
-Single runs against baseline `1a00294` and this change, not a statistical study:
-
-| Routes | Startup ms before / after | RSS MiB before / after | Heap MiB before / after | Requests/s before / after | p95 ms before / after |
-| --- | --- | --- | --- | --- | --- |
-| 1,000 | 135 / 138 | 183 / 182 | 29 / 34 | 24,645 / 24,701 | 1.18 / 1.23 |
-| 10,000 | 312 / 303 | 211 / 207 | 55 / 63 | 6,762 / 6,829 | 4.08 / 4.09 |
-
-Both baseline and updated 100,000-route runs failed with `Configuration worker
-resource limit or failure` before route compilation. The worker's existing
-resource bounds are unchanged; the configured 100k route ceiling is not evidence
-that every 100k YAML document fits those bounds. Bulk-scale remediation and
-repeatable memory profiling were subsequent work at Phase A. The new
-[bulk sharding benchmark](BULK.md) successfully activates 100,000 routes within
-the unchanged worker limits. Capability analysis adds
-linear activation work and temporary report allocations; no request-time checks
-were added. These measurements are not provider, soak or capacity certification.