@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/docs/README.md

@@ -1,58 +1,109 @@
 # URLCode documentation
 
-Start with [project direction](PROJECT-DIRECTION.md) for what URLCode is, what it
-is not, how application projects fit, and the license.
+> **Public documentation has moved to
+> [urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs).** That repository
+> is the documentation home and is authored directly — this tree is no longer
+> mirrored into it. New reader-facing pages belong in urlcode-docs; `docs/` here
+> keeps contributor and maintainer material (local development, CI, release
+> process, reviews, spikes, plans and the generated field reference). The
+> reader-facing pages still listed below are being migrated.
 
-For runtime 0.2.0. Use documentation pinned to your runtime revision.
+Start with [the framework](FRAMEWORK.md): the four packages, the ladder from
+redirects to a full application, the composition contract and the rules an AI
+agent must follow. [Project direction](PROJECT-DIRECTION.md) states the
+boundary and the license. Use documentation pinned to your runtime revision;
 `version: "1"` is the stable project-format contract for this release line.
 
+## Author a project
+
 | Goal | Start here |
 |---|---|
 | Install the CLI | [Installation](INSTALL.md) |
-| Generate placeholders from YAML | [Scaffolding](SCAFFOLDING.md) |
 | Write YAML with examples | [YAML guide and recipes](YAML-GUIDE.md) |
 | Look up every accepted field | [Generated field reference](YAML-REFERENCE.md), [JSON Schema](../schemas/urlcode.schema.json) |
 | Let an AI build routes | [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt) |
+| Load authoring/operations rules into an agent | [Authoring skill](../.claude/skills/urlcode-authoring/SKILL.md), [operations skill](../.claude/skills/urlcode-operations/SKILL.md), [how they are distributed](AI-AUTHORING.md#agent-skills) |
 | Run examples | [25-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
 | Explore a standalone application | [URLCode Shortener demo](https://github.com/jimhoyd-com/urlcode-shortener), [build retrospective](https://github.com/jimhoyd-com/urlcode-shortener/blob/main/docs/BUILD-RETROSPECTIVE.md) |
 | Explore a static docs-site integration | [URLCode Docs project](https://github.com/jimhoyd-com/urlcode-docs), [build retrospective](https://github.com/jimhoyd-com/urlcode-docs/blob/main/docs/BUILD-RETROSPECTIVE.md) — synced from this repository, which remains the source of truth |
 | Create/update short links live | [Dynamic links, storage and management API](DYNAMIC-LINKS.md) |
 | Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
-| Reuse code around routes | [Middleware](MIDDLEWARE.md) |
-| Throttle, block agents, set security headers, compress or cache from YAML | [Policies](POLICIES.md): [throttle](policies/throttle.md), [agents](policies/agents.md), [security](policies/security.md), [compression](policies/compression.md), [cache](policies/cache.md) |
+| Run examples | [40-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
+| Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [SDK and read-only MCP](TOOLING.md) |
+| Reuse code around routes | [Middleware](MIDDLEWARE.md), [middleware examples](MIDDLEWARE-EXAMPLES.md) |
+| Handle secrets and untrusted code | [Function security](FUNCTION-SECURITY.md) |
+| Author guest functions in TypeScript | [Build-time guest transpilation](TYPESCRIPT-AUTHORING.md) |
+| Serve pages, files and downloads | [Assets](ASSETS.md) |
+| Publish a site with no request-time guest code | [Prerendering helper and recipe](PRERENDER.md) |
+| Create and update short links live | [Dynamic links, storage and management API](DYNAMIC-LINKS.md) |
+| Select response branches | [Exact conditions](CONDITIONS.md) |
+| Proxy an API or emit a webhook | [Bounded egress and operator grants](EGRESS.md) |
+| Throttle, block agents, set security headers, compress or cache | [Policies](POLICIES.md): [throttle](policies/throttle.md), [agents](policies/agents.md), [security](policies/security.md), [compression](policies/compression.md), [cache](policies/cache.md) |
+| Generate robots.txt, sitemap.xml, favicon, security.txt and llms.txt | [Site conventions](SITE.md) |
+| Organize YAML across folders | [Organization](ORGANIZATION.md), [readability practices](BEST-PRACTICES.md) |
+| Generate placeholders from YAML | [Scaffolding](SCAFFOLDING.md) |
+| Convert provider redirect files | [Strict interchange and conversion reports](INTERCHANGE.md) |
+| Import thousands of redirects | [Bulk import and scale evidence](BULK.md) |
+| Reuse local project recipes | [Recipe catalog](RECIPES.md) |
+| Check declared configuration against standards-referenced rules | [Compliance](COMPLIANCE.md) |
+
+## Extend the runtime
+
+| Goal | Start here |
+|---|---|
+| Add accounts, sign-in and protected routes | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth#readme) |
+| Manage users, sessions, roles and audit | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin#readme) |
+| Restyle every extension page and translate copy | [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/CONTRACT.md) |
+| Write or install a versioned extension | [Extensions](EXTENSIONS.md), [example fixture](../examples/extensions/README.md) |
 | Add host behavior in operator code | [Plugins](PLUGINS.md) |
 | Use the API from TypeScript | [TypeScript: shipped declarations, exports, build and fidelity](TYPESCRIPT.md) |
-| Check declared configuration against standards-referenced rules | [Compliance](COMPLIANCE.md) |
-| See how the runtime conforms to the standards it uses | [Standards audit](STANDARDS.md) |
-| Serve pages/files/downloads | [Assets](ASSETS.md) |
-| Generate robots.txt, sitemap.xml, favicon, security.txt and llms.txt | [Site conventions](SITE.md) |
-| Publish a site with no request-time guest code | [Prerendering helper and recipe](PRERENDER.md) |
-| Keep code and YAML readable | [Organization and readability practices](BEST-PRACTICES.md) |
-| Organize YAML across folders | [Organization](ORGANIZATION.md) |
-| Work locally | [Local development](LOCAL-DEVELOPMENT.md) |
-| Share a local project publicly | [Tunnels](TUNNELS.md) |
-| Watch a deployment | [Monitoring](MONITORING.md) |
-| Wire your own monitoring or scrape metrics | [Observability](OBSERVABILITY.md) |
-| Load test a deployment | [Load testing](LOAD-TESTING.md) |
-| Deploy to Vercel | [Vercel adapter](VERCEL.md) |
-| Deploy to AWS Lambda | [AWS adapter](AWS.md) |
-| Deploy to Cloudflare Workers | [Cloudflare target](CLOUDFLARE.md) |
-| Handle secrets/untrusted code | [Function security](FUNCTION-SECURITY.md) |
+
+## Operate and deploy
+
+| Goal | Start here |
+|---|---|
+| Work locally | [Local development](LOCAL-DEVELOPMENT.md), [tunnels](TUNNELS.md) |
 | Prove responses and counts | [Readiness](READINESS.md) |
-| Estimate concurrency/memory | [Capacity and limits](CAPACITY.md), [measurements](PERFORMANCE.md) |
-| Prepare for overload/DDoS/recovery | [Resilience playbook](RESILIENCE.md) |
+| Check pull requests of a project on GitHub | [CI action, route diffs and the starter workflow](CI.md) |
 | Deploy and roll back | [Operations](OPERATIONS.md) |
 | Review security findings and gaps | [Internal security audit](SECURITY-AUDIT.md) |
 | Assess release readiness | [Evidence and open gates](RELEASE-READINESS.md) |
 | See unfinished work | [Roadmap](../ROADMAP.md) |
 | Read the design behind policies, plugins and templates | [Extensions spike](SPIKE-EXTENSIONS.md) |
+| Read the design for an authentication and authorization plugin | [Auth spike](SPIKE-AUTH.md) |
+| Read the design for the administration extension that manages users | [Admin spike](SPIKE-ADMIN.md) |
+| Read the design for the shared template kit every extension renders with | [UI kit spike](SPIKE-UI.md) |
+| Read the review of the extension model, its precedents and alignment | [Extension model review](SPIKE-EXTENSION-MODEL.md) |
+| Read the design for compiling function routes into per-route Lambdas | [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) |
+| Verify a running deployment matches the project | [Deployment checks](DEPLOYMENT-CHECKS.md) |
+| Inspect target support | [Capabilities and normalized representation](CAPABILITIES.md) |
+| Deploy to Vercel, AWS Lambda or Cloudflare Workers | [Vercel](VERCEL.md), [AWS](AWS.md), [Cloudflare](CLOUDFLARE.md), [provider verification evidence](PROVIDER-VERIFICATION.md) |
+| Watch a deployment | [Monitoring](MONITORING.md), [observability](OBSERVABILITY.md) |
+| Estimate concurrency and memory | [Capacity and limits](CAPACITY.md), [measurements](PERFORMANCE.md), [load testing](LOAD-TESTING.md) |
+| Prepare for overload, DDoS and recovery | [Resilience playbook](RESILIENCE.md) |
+| Manage private credentials and audit | [Management security](MANAGEMENT-SECURITY.md) |
 
-Examples are educational unless backed by the runnable cookbook/fixtures.
-Infrastructure limits are deployment settings, not fields to invent in route YAML.
+## Evidence, reviews and design records
 
-## Security and acceptance
+These are dated records, not guides. They say what has been checked and what
+has not, and why the design is the way it is.
 
-- [Independent sandbox review package](SANDBOX-REVIEW.md)
-- [Private management credentials and atomic audit](MANAGEMENT-SECURITY.md)
-- [Operational drills and deployment acceptance](OPERATIONAL-PROOF.md)
-- [Candidate signing and release security](RELEASE-SECURITY.md)
+| Record | What it is |
+|---|---|
+| [Release readiness](RELEASE-READINESS.md) | Verified safeguards, open gates, supported scope |
+| [Usability review](USABILITY-REVIEW.md) | Where the framework is easier or harder than the tools it replaces, and ranked changes |
+| [Next steps](NEXT-STEPS.md) | The phased plan: agent discovery, context compression, retrieval, the ladder, benchmarks and the remaining proof gaps |
+| [Next-phase implementation status](NEXT-PHASE-PLAN.md) | Source additions after 0.3.0 shipped in 0.4.0-alpha.1, and their evidence limits |
+| [Security review](SECURITY-AUDIT.md) | Internal findings and fixes; not an independent test |
+| [Standards audit](STANDARDS.md) | How the runtime conforms to the RFCs it touches |
+| [Sandbox review package](SANDBOX-REVIEW.md) | What an independent reviewer needs; assessment not yet performed |
+| [Operational drills](OPERATIONAL-PROOF.md) | Deployment acceptance drills CI runs |
+| [Release security](RELEASE-SECURITY.md) | Candidate signing and publication process |
+| [Extension model review](SPIKE-EXTENSION-MODEL.md) | Why extensions are shaped this way, with framework precedents |
+| [Extensions spike](SPIKE-EXTENSIONS.md) | The design behind policies and plugins; implemented |
+| [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) | Proposal: per-route Lambdas for functions; not implemented |
+| Auth, admin and UI spikes | Live in their repositories: [auth](https://github.com/jimhoyd-com/urlcode-auth/blob/main/docs/SPIKE-AUTH.md), [admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/docs/SPIKE-ADMIN.md), [ui](https://github.com/jimhoyd-com/urlcode-ui/blob/main/docs/SPIKE-UI.md) |
+| [Roadmap](../ROADMAP.md) | Implemented versus planned |
+
+Examples are educational unless backed by the runnable cookbook and fixtures.
+Infrastructure limits are deployment settings, not fields to invent in route YAML.

package/docs/RECIPES.md

@@ -0,0 +1,99 @@
+# Local recipes
+
+Recipes are ordinary version-controlled URLCode projects shipped with the
+runtime. There is no network registry, install script, provider account or
+project-code execution during authoring. Search them before writing a common
+route by hand: the catalog is the vocabulary of behavior the runtime already
+supports, and every recipe validates, tests and audits.
+
+```sh
+urlcode recipes list
+urlcode recipes search "webhook json"        # id, description, tags, capabilities
+urlcode recipes search webhook --json
+urlcode recipes show webhook-receiver        # metadata first, then every file
+urlcode recipes add webhook-receiver --out ./orders-hook --dry-run
+urlcode recipes add webhook-receiver --out ./orders-hook
+urlcode validate --local --project ./orders-hook
+```
+
+## The catalog
+
+| Recipe | Complexity | What it shows | Needs |
+|---|---|---|---|
+| `redirect` | starter | Permanent redirect forwarding one allowlisted query key | nothing |
+| `health-page` | starter | Native `/health` text and `/status` JSON, no-store | nothing |
+| `json-api` | starter | Bounded JSON body echoed by a sandboxed function | self-hosted runtime |
+| `webhook-receiver` | starter | JSON event with a type header, shape-checked, `202` | self-hosted runtime |
+| `typescript` | intermediate | Typed guest transpiled by `build-typescript` | build step |
+| `static-plus-api` | intermediate | Page, static directory and one JSON function | self-hosted runtime |
+| `cors-api` | intermediate | Preflight and CORS headers from route middleware | self-hosted runtime |
+| `contact-form` | intermediate | Validated message, fixed signal to a hook after the response | signal grant (`--policy`) |
+| `middleware` | advanced | Fourteen reusable middleware patterns ([described here](MIDDLEWARE-EXAMPLES.md)) | self-hosted runtime |
+| `authenticated-json-api` | advanced | Function behind `auth: true` | operator auth extension, `--host-file`, `--origin` |
+| `protected-download` | advanced | Native attachment behind `auth: true` | operator auth extension, `--host-file`, `--origin` |
+
+Each recipe contains a README, `tests/requests.json` and editable files.
+Replace example destinations and review the resulting files before use. The
+authenticated recipes declare `extensions.auth` and protect their route with
+the short form described in [extensions](EXTENSIONS.md); their README shows the
+minimal host-file fixture that reproduces the bundled tests. Nothing in the
+catalog verifies webhook signatures: the sandbox has no crypto or network API,
+so signed webhooks belong behind an operator extension or a trusted host.
+
+## `recipe.yaml`
+
+Every recipe carries `recipe.yaml`, validated against
+[`schemas/recipe.schema.json`](../schemas/recipe.schema.json) by `npm run check`:
+
+- `id`, `description`, `tags`, `complexity` (`starter`, `intermediate`,
+  `advanced`): written by hand; `search` matches id, description, tags and
+  capabilities, every word must match, and whole-tag or id hits rank first.
+- `capabilities`, `targets`, `routes`: derived from the capability preflight
+  (`analyzeProjectCapabilities` per target after site expansion). The check
+  refuses a hand-edited value that differs, so a recipe cannot claim a target
+  it does not activate on. `targets` is `compatible`, or the strongest issue
+  (`conditional`, `unknown`, `refused`); `routes` is the `--expect-routes` value.
+- `services` (external services), `grants` (operator grants, never from project
+  files), `inputs` (what to edit), `files` (the copy list), `tests` (fixtures
+  and the exact commands) and `behavior` (one observable statement per line).
+
+`show` prints this metadata before the file contents so a reader sees what a
+recipe needs before its files scroll past; `--json` returns the same object with
+a `content` map. `list` prints one line per recipe, or the metadata with `--json`.
+
+## Examples
+
+`examples/*/example.yaml` uses the same schema, and `urlcode examples search
+<text> [--json]` returns the smallest matching runnable example first with the
+file to read. The cookbook's forty routes are indexed per route in the generated
+[`examples/cookbook/route-index.json`](../examples/cookbook/route-index.json)
+(handler, methods, capabilities, policies and middleware module names as tags;
+`npm run docs:cookbook-index` regenerates it and `npm run check` refuses a stale
+copy), so a search for `etag` answers the cookbook and its `/versioned` route.
+Entries without a `urlcode.yaml` (operator rules, monitoring configuration,
+scripts) are `runnable: false` and carry no derived fields.
+
+## Adding a recipe
+
+`add` creates a new standalone directory. It refuses an existing destination,
+even an empty directory; it never merges or overwrites existing project routes.
+Review or copy selected declarations manually when combining projects. Dry-run
+reads and validates the packaged recipe and checks the destination, but writes
+nothing. The output parent must already exist and be owned by the caller.
+Dependencies are written first and the complete `urlcode.yaml` is published by
+rename last. A failed write removes the new directory. This is atomic project
+activation, not an atomic directory replacement or a guarantee against a local
+attacker concurrently replacing the caller's output directories.
+
+## SDK and MCP
+
+The SDK provides `listRecipes()`, `searchRecipes(text)`, `showRecipe(name)`,
+`addRecipe(name, output, {dryRun})`, `listExamples()` and `searchExamples(text)`.
+Catalog names are a fixed list in code; metadata and file lists come from each
+schema-checked `recipe.yaml` and are returned as copies. Unknown names and
+arbitrary paths/URLs fail closed. The stdio MCP server adds `search_recipes` and
+`search_examples` beside `recipes_list` and `recipes_show`
+([tooling](TOOLING.md)). Integration tests run every recipe through the real
+runtime with its fixtures and audit it with its declared route count (after
+building the TypeScript recipe, with a fixture registry for the authenticated
+ones and the generated policy for the contact form).

package/docs/RELEASE-READINESS.md

@@ -1,13 +1,14 @@
 # Release readiness
 
-Status: stable 0.1 self-hosted release. Production approval remains specific to
+Status: `0.4.0-alpha.1` alpha of the extension contract and agent tooling on
+top of the `0.3.0` self-hosted release. Production approval remains specific to
 the workload and deployment environment.
 This register describes the current public runtime, not future promises.
 Use the contract and docs from the same pinned commit as your installed runtime.
 
 ## What is aligned
 
-- One portable YAML project, explicit includes, seven mutually exclusive handlers,
+- One portable YAML project, explicit includes, one handler per route (redirect, respond, page, static, download, function, link, proxy, conditional or extension),
   per-route middleware and consistent request/response validation.
 - One starter with a function route first and an ordinary redirect second.
   Clone urlcode-template or use `urlcode init`; neither requires a database.
@@ -72,12 +73,13 @@ License selection is resolved: URLCode is released under the Apache License 2.0,
 `package.json` declares it, and the repository carries the full license text.
 The remaining gates above are engineering and operational, not legal.
 
-The full free-product roadmap additionally includes bulk interchange tooling,
-installers/Homebrew, provider adapters and reusable templates/signals. Those
-features are not implemented merely because
-YAML has a portable design. Node process/container hosting is the supported
-execution target today; AWS/Vercel/Cloudflare adapters and guest network/realtime
-capabilities remain future work. See [roadmap](../ROADMAP.md).
+The unreleased next-phase source now includes strict bulk/provider interchange,
+local recipes, TypeScript authoring, bounded self-hosted proxy/signals and read-only
+MCP. Local AWS/Vercel/Cloudflare adapter tests and deployment probe tooling exist,
+but actual provider deployments remain unverified. Node process/container hosting
+remains the reference execution target. Guest networking, durable signals and
+realtime capabilities are not provided. See [implementation status](NEXT-PHASE-PLAN.md)
+and [roadmap](../ROADMAP.md); these additions do not close the operational gates above.
 
 The [internal security audit](SECURITY-AUDIT.md) records reproduced findings, fixes
 and prioritized gaps. Its regressions supplement these gates; they do not replace
@@ -91,5 +93,5 @@ credentials, atomic SQLite mutation audits, executable local/CI operational dril
 and a main-only candidate signing/SBOM workflow.
 
 Still required: [independent review](SANDBOX-REVIEW.md), [actual deployment proof](OPERATIONAL-PROOF.md),
-and publication/support arrangements. The Apache-2.0 license and the 0.2.0 self-hosted
+and publication/support arrangements. The Apache-2.0 license and the 0.3.0 self-hosted
 release do not close the security and deployment gates. See [release process](RELEASE-SECURITY.md).

package/docs/RELEASE-SECURITY.md

@@ -1,6 +1,6 @@
 # Candidate and release security process
 
-URLCode 0.2.0 is the Apache-2.0 self-hosted baseline; licensing is defined
+URLCode 0.3.0 is the Apache-2.0 self-hosted baseline; licensing is defined
 in [LICENSE](../LICENSE). Two workflows share one audited build path and differ
 only in what they do with its output:
 
@@ -14,6 +14,16 @@ only in what they do with its output:
 Neither workflow is a statement that a release is production-ready; see
 [release readiness](RELEASE-READINESS.md).
 
+## Publishing an alpha
+
+An alpha such as `0.4.0-alpha.1` follows the same path: tag `v0.4.0-alpha.1`
+on a commit that is already on main. The release workflow publishes to npm
+only when the repository variable `PUBLISH_NPM` is `true` and the npm trusted
+publisher for this repository and `release.yml` exists; otherwise the run is
+artifacts-only (a GitHub release with the signed tarball). Publish order is
+core → ui → auth → admin, because the extension packages declare
+`@jimhoyd/urlcode >=0.4.0-alpha.1 <0.5.0` and must resolve the core alpha.
+
 1. Report vulnerabilities privately through [GitHub advisories](https://github.com/jimhoyd-com/urlcode/security/advisories/new).
    The maintainer triages impact, confirms affected exact revisions, coordinates a
    fix/retest privately, and publishes an advisory with upgrade guidance when safe.
@@ -47,10 +57,23 @@ Neither workflow is a statement that a release is production-ready; see
    signing key is stored. Signing permissions exist only in this manual job; build
    commands run in a container without passing GitHub tokens. Candidate files are
    retained as GitHub Actions artifacts for 30 days. A release additionally attaches
-   them to the GitHub release, and publishes to npm with `--provenance` and to GHCR
-   when those repository variables are enabled.
+   them to the GitHub release, and publishes to npm and to GHCR when those
+   repository variables are enabled.
+
+   **npm publication holds no credential.** The registry is configured with a
+   trusted publisher naming this repository and `release.yml`, so the publish
+   step exchanges the job's OIDC identity for a credential that lives for the
+   length of one publish. There is no npm token in the repository's secrets to
+   leak, revoke or rotate, and a fork or another workflow cannot publish under
+   this package's name. Provenance is generated on that same identity, so
+   `--provenance` is not passed and its absence is not a downgrade.
+
+   A bearer token would silently take precedence over this exchange, so the
+   publish step must reference none; `test/release.test.ts` fails if one
+   reappears in it, and checks the npm and Node floors below which the exchange
+   is not attempted at all.
 5. Download the candidate for the intended commit and verify **each file**, e.g.
-   `gh attestation verify urlcode-0.2.0.tgz --repo jimhoyd-com/urlcode --signer-workflow jimhoyd-com/urlcode/.github/workflows/candidate.yml --source-ref refs/heads/main --source-digest APPROVED_COMMIT_SHA`
+   `gh attestation verify jimhoyd-urlcode-0.3.0.tgz --repo jimhoyd-com/urlcode --signer-workflow jimhoyd-com/urlcode/.github/workflows/candidate.yml --source-ref refs/heads/main --source-digest APPROVED_COMMIT_SHA`
    (use `release.yml` as the signer workflow for a tagged release).
    Check the verified provenance's source commit against the approved commit, and
    compare package/SBOM hashes with the signed manifest. A signature establishes

package/docs/SECURITY-AUDIT.md

@@ -100,7 +100,7 @@ repository-governance follow-up pins them and enables dependency maintenance,
 secret protection, CodeQL and private reporting; see [governance](../GOVERNANCE.md).
 CI now also gates runtime advisories with `npm audit --omit=dev`. A manual main-only
 signed candidate/SBOM workflow is now defined; see
-[release security](RELEASE-SECURITY.md). It does not publish to registries. The 0.1.0 release is licensed under
+[release security](RELEASE-SECURITY.md). A tagged release publishes to npm with provenance. The 0.1.0 release is licensed under
 Apache-2.0; the license does not close the independent-review gates.
 
 **Application responsibility:** HTML/JS assets are active browser content; choose

package/docs/SPECIFICATION.md

@@ -1,8 +1,9 @@
-# Implemented 0.1 contract
+# Implemented project contract
 
 This document and [JSON Schema](../schemas/urlcode.schema.json) describe
-0.2.0. `version: "1"` is the stable project-format contract for the 0.1 release
-line. Later planned features are rejected until implemented.
+the source contract, including unreleased additions after 0.3.0.
+`version: "1"` remains the project-format contract. Unsupported fields
+are rejected rather than interpreted as future behavior.
 
 ## Files and validation
 
@@ -29,12 +30,12 @@ deadline; individual synchronous operations are not preempted. At most 1,000 par
 Keys are absolute case-sensitive paths. Trailing slashes are significant.
 Parameters occupy whole segments, e.g. `/p/{id}`, with distinct identifier names.
 Each parameter matches exactly one nonempty segment, never across `/`; it is not
-greedy. No regex paths, host matching or dot segments. Only static directory mounts
+greedy. No regex paths, client-controlled host dispatch or dot segments. Only static directory mounts
 support a terminal `/*` wildcard with an otherwise literal path. Route keys cannot contain
 percent encoding, spaces, backslashes or query strings. Path length is limited
 to 2,048 characters and 32 segments. `/_urlcode` is reserved.
 
-One handler per route: `function`, `redirect`, `page`, `static`, `download`, `respond` or `link`.
+One handler per route: `function`, `redirect`, `page`, `static`, `download`, `respond`, `link`, `conditional` or `proxy`.
 See [asset configuration](ASSETS.md) for file handlers. Optional properties:
 
 - `methods`: unique HTTP methods; default GET and HEAD. Explicit lists are exact;
@@ -67,6 +68,37 @@ path wins and the generated one is logged as shadowed. Absolute URLs come from
 the operator's `--origin`; `sitemap` refuses activation without one. See
 [site conventions](SITE.md).
 
+## Exact conditions and duplicate-path alternatives
+
+Optional route `match` conjunctively compares exact query/header/cookie strings,
+an uppercase method and the canonical authority of the operator-configured
+public origin. Host/forwarded headers never select the trusted host. A guard
+mismatch returns 404 without trying a less-specific path; route method admission
+still applies after the guard. Conditions are not authentication or authorization.
+
+The `conditional` handler puts alternatives under one existing route key:
+`cases` contains 1–16 `{match, redirect}` or `{match, respond}` entries; optional
+`fallback` contains exactly one redirect/respond handler. Duplicate YAML paths
+remain invalid. Cases must be provably disjoint: each pair needs a shared
+predicate with different required values. Cases run before fallback; no matching
+case and no fallback returns 404. Nested cases and branch-local bindings,
+middleware or policy are unsupported. Shared inputs, methods, headers,
+middleware and policies stay at route level.
+
+Each query/header/cookie map has 1–16 comparisons; names have at most 128
+characters and values 1,024. Query comparisons use decoded raw strings without
+parameter defaults/coercion. Cookies use unquoted wire values and an 8 KiB input
+limit. Missing and empty are different. Duplicate examined scalar inputs return
+400 when the transport exposes their counts. Header names normalize to lowercase;
+authentication and transport headers cannot be predicates. No regex, geo/device
+inference, wildcard or arbitrary-code conditions are supported.
+
+Conditional routing requires cache disabled or no-store and forces downstream
+no-store responses. Explicit fixtures are required for branch coverage.
+Self-hosted, AWS and Vercel use the shared matcher; Cloudflare refuses conditions
+until its artifact compiler supports them. See [conditions](CONDITIONS.md) and
+the [executable example](../examples/conditions).
+
 ## HTTP request/response configuration
 
 Routes accept `request.body` validation and `response.headers` overrides. The
@@ -161,8 +193,25 @@ export default function hello(request, { args, env }) {
 }
 ```
 
+`function` also accepts a string: `function: functions/hello.mjs`. Document
+validation normalizes it to the long form above before routing, auditing,
+explaining or hashing the project: `source` is the string, `args` maps every
+`{param}` segment of the path to `{from: path, name: param}`, and each such
+parameter the route does not already declare under `parameters` (by name, with
+`in: path`) is appended as `{in: path, required: true, schema: {type: string,
+minLength: 1, maxLength: 128}}`. Declared parameters keep their own schema and
+order. The string must be a project-relative `.mjs` or `.js` path without `..`
+segments; anything else is refused with the route path named. A `middleware`
+entry may likewise be a string, normalized to `{source: <string>}`. Only the
+long form exists after loading, so `routes`, `audit`, `explain`, revision hashes
+and the field reference describe the expansion.
+
 ES modules only (`.mjs` or `.js`, independent of Node package settings).
-TypeScript is not included. `export` defaults to `default`. Functions execute
+[Build-time TypeScript authoring](TYPESCRIPT-AUTHORING.md) can produce these
+JavaScript modules in a separate output project; serving does not transpile them.
+The build never imports application code into Node, uses fixed compiler settings,
+and does not perform semantic type checking. Grants must target the built
+configuration/source revision. `export` defaults to `default`. Functions execute
 inside QuickJS/WASM, never through Node imports. Only relative `.js`/`.mjs`
 project imports are supported, with a snapshotted dependency graph. No bare/npm,
 Node built-in, remote, dynamic source imports or `import.meta`. Runtime-created
@@ -206,8 +255,9 @@ not arbitrary Host/forwarded headers. Request/response bodies default to 1 MiB;
 response headers 16 KiB, maximum 256 pairs. Hop-by-hop headers are stripped;
 cookies are preserved individually. Default response cache policy is `no-store`.
 
-No unrestricted host execution option exists. Network integrations and persistent
-state need future explicit, tested capability brokers. Approved secrets can be
+No unrestricted host execution option exists. Declarative proxy and webhook
+signals use the separately granted host broker described in [egress](EGRESS.md);
+guests still have no fetch API or general persistent state capability. Approved secrets can be
 returned by code that receives them; isolation does not automatically enforce
 information-flow rules on authorized inputs. Keep grants narrow and review the
 exact pinned revision. The sandbox still needs independent security review before hostile multi-tenant use.
@@ -230,3 +280,40 @@ The health `version` combines route-definition and asset-representation digests,
 not a full artifact digest
 or secret fingerprint. Production release identity should be the Git commit and
 container image digest. See [operations](OPERATIONS.md).
+
+See [capabilities and normalized route representation](CAPABILITIES.md) for the target catalog,
+programmatic compatibility analysis and provider verification limits.
+
+## Authoring, conversion and verification tools
+
+[Interchange](INTERCHANGE.md) imports and exports a strict literal redirect
+subset with source diagnostics and dry-run reports. Provider conversions refuse
+semantic differences by default; explicit acknowledgment retains warnings and
+never reports lossless behavior. [Bulk import](BULK.md) shards CSV/JSON/YAML rows
+into ordinary includes while retaining runtime resource limits. [Recipes](RECIPES.md)
+are local Git-owned examples; they grant no capabilities. [Build-time TypeScript](TYPESCRIPT-AUTHORING.md)
+is separate from runtime execution.
+
+The [tooling SDK and optional local MCP](TOOLING.md) inspect and validate without
+executing handlers or reading binding values. [Provider conformance](PROVIDER-VERIFICATION.md)
+distinguishes local adapter replay from actual deployment observations; no real
+provider deployment is implied by CI. [Proxy and signal egress](EGRESS.md) requires
+external revision-pinned operator grants and bounded host-owned transport;
+project declarations cannot grant network authority to themselves or guests.
+
+## Bounded outbound behavior
+
+The proxy handler and webhook signals require external revision-pinned origin
+grants. [Egress](EGRESS.md) specifies request and response semantics, DNS pinning,
+header filtering, size/time/concurrency limits, secret binding, signal guarantees
+and shutdown. Project declarations cannot grant network authority to themselves.
+All non-self-hosted targets refuse these capabilities.
+
+## Operator-installed extension handlers
+
+The optional `extensions` map declares version-1 extension configuration.
+`extension: name` handlers require exclusive literal `/prefix/*` mounts and
+explicit operator registration pinned to the project revision. Optional
+`policies.extensions` requirements are validated by the named extension and
+authorized before cache access. See [extension contracts](EXTENSIONS.md) for
+configuration, trust boundaries, lifecycle and target restrictions.