@jimhoyd/urlcode 0.4.2 → 0.4.6

package/docs/SPECIFICATION.md

@@ -1,359 +0,0 @@
-# Implemented project contract
-
-This document and [JSON Schema](../schemas/urlcode.schema.json) describe
-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
-
-`urlcode.yaml` contains `version`, `routes`, and optional `includes` (an explicit
-list of project-relative YAML files). Included files have the same version/routes
-shape and cannot recursively include files. Duplicate paths across files fail.
-See [organization examples](ORGANIZATION.md) for one-file, multi-file and mixed
-layouts. All references resolve from the project root, not the including file.
-File references resolve inside the project; escaping symlinks fail. No glob,
-remote config or arbitrary infrastructure configuration.
-
-YAML 1.2 JSON-compatible values only: string mapping keys, finite numbers,
-booleans and null. No duplicate keys, aliases, anchors, tags, merge keys,
-multiple documents, reserved prototype keys or nesting of 40+ levels. Unknown
-schema fields fail. Files are limited to 32 MiB each, 256 includes and 100,000
-routes total, with a 64 MiB aggregate YAML source cap. Loading runs in a worker
-with a 256 MiB old-generation heap, a 10-second wall deadline and at most two
-concurrent loads per Node isolate. These are not a total process RSS bound.
-Route compilation yields every 64 routes and checks a 10-second cooperative
-deadline; individual synchronous operations are not preempted. At most 1,000 parameterized routes and 1,024 distinct input schemas.
-
-## Routes
-
-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, 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`, `conditional`, `proxy` or an `extension` mount.
-See [asset configuration](ASSETS.md) for file handlers. Optional properties:
-
-- `methods`: unique HTTP methods; default GET and HEAD. Explicit lists are exact;
-  adding GET does not implicitly add HEAD. Wrong method returns 405 plus Allow.
-- `enabled`: false returns 404, the same as unknown paths.
-- `expires`: UTC ISO timestamp (`...ssZ` or `...ss.sssZ`); expired routes return 410.
-- `description`: optional authoring metadata.
-- `middleware`: ordered list of up to 16 `{source, export?}` modules wrapping any
-  handler. See [middleware](MIDDLEWARE.md) for the portable contract.
-- `parameters`, `env`, `secrets`: inputs and explicit binding references.
-
-Literal paths win; parameter routes with more literal segments win next;
-static mounts follow, longest prefix first. A missing file in the selected mount
-returns 404 without falling back to a shorter mount.
-Equally specific overlapping patterns fail even if methods differ. Match a route
-before checking its methods; do not fall back to a less specific route for 405.
-Requests decode the path once; invalid UTF-8/percent encoding, encoded slashes or
-backslashes, control characters and dot segments return 400. Query values decode
-once. Incoming query data is not automatically forwarded.
-
-See [route matching](ROUTING.md) for examples, precedence, wildcard
-limits and reload behavior.
-
-The optional top-level `site` block (entry file only) generates native routes
-for site conventions: `robots` → `/robots.txt`, `sitemap` → `/sitemap.xml`,
-`favicon` → `/favicon.ico`, `securityTxt` → `/.well-known/security.txt` and
-`llms` → `/llms.txt`. Each is an ordinary `respond` or `page` route merged in
-before compilation and counted by `routes`/`audit`; a declared route at the same
-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
-`respond` handler serves declared text/JSON with a status without running code.
-See [HTTP configuration](HTTP.md) for the exact supported fields, precedence,
-security restrictions and examples.
-
-## Policies
-
-Optional top-level `policies` and `profiles` keys, and `routes.<path>.policies`,
-declare host-enforced behavior around a route: `throttle`, `agents`, `security`,
-`compression` and `cache`. All are off unless declared; a route's keys merge
-over the project's, `false` disables one, and a target that cannot enforce a
-policy refuses activation naming the route. The five policies are implemented
-for the self-hosted server; Vercel and AWS accept `agents`, `security`, `cache`
-and route-partitioned `throttle`; the Cloudflare build compiles `agents` and
-`security` only. See [policies](POLICIES.md) for the pipeline position, merge
-rules and the per-target table, and [plugins](PLUGINS.md) for the host hook API
-operators pass in code.
-
-## Inputs
-
-Declare each path placeholder as a required string. Query/header inputs may be
-string, integer, number or boolean. Query arrays declare scalar `items`; repeated
-keys retain order (maximum 100 values). Header names are case-insensitive.
-Duplicate scalar query/header inputs return 400. Required missing inputs return
-400; defaults apply only to absent inputs. Empty strings are present values.
-
-Supported validation: `type`, scalar `enum`, `default`, string `minLength`/
-`maxLength`, numeric `minimum`/`maximum`, query array `items` and `maxItems`.
-Regular-expression patterns, structured bodies, cookies, nested inputs and
-OpenAPI `style`/`explode` fields are not implemented. This uses a documented
-OpenAPI-like input subset; it is not an OpenAPI document or full JSON Schema
-input vocabulary. String limits are at most 8,192 characters.
-
-Integers use `-?(0|[1-9][0-9]*)` and must be safe JavaScript integers. Numbers
-allow the same grammar plus a fractional suffix; no exponent, plus sign, leading
-zeros, whitespace, NaN or infinity. Booleans are exactly `true` or `false`.
-Unknown query keys are ignored unless explicitly passed by a redirect.
-
-## Redirects
-
-`redirect.url` is an absolute HTTP(S) URL with literal scheme/host and no embedded
-credentials or whitespace/control characters. `{pathInput}` placeholders are
-allowed only in the destination pathname and encoded as single components.
-No environment/secret interpolation. Status defaults to 302; allowed values are
-301, 302, 303, 307 and 308.
-
-`redirect.query.map` maps output keys to `{from: path|query|header, name: input}`
-references to declared inputs. Typed/defaulted values are used. Arrays produce
-repeated output keys. Absent optional inputs are omitted.
-`redirect.query.pass` is false or an explicit allowlist; unrestricted `true` is
-not supported. Conflicts between destination keys, maps and passthrough fail.
-Declared passthrough inputs use validated/defaulted values; undeclared allowlisted
-keys preserve repeated values. Headers are forwarded only through explicit maps.
-
-## Stored links
-
-Core has no native `link` handler or `dynamicLinks` project flag; both were
-removed. The `urlcode-dynamic-link` extension package that replaced them has
-been retired and unpublished, so a project needing stored short links owns that
-storage itself; there is no in-core replacement or deprecation shim for
-`link`/`dynamicLinks`.
-
-## Functions
-
-```yaml
-version: "1"
-routes:
-  /hello/{name}:
-    parameters:
-      - name: name
-        in: path
-        required: true
-        schema: {type: string, minLength: 1}
-    function:
-      source: functions/hello.mjs
-      export: default
-      args:
-        name: {from: path, name: name}
-    env:
-      GREETING: {value: Hello}
-```
-
-```js
-export default function hello(request, { args, env }) {
-  return Response.json({ message: `${env.GREETING}, ${args.name}!` });
-}
-```
-
-`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` is loaded as ESM in both modes. A `sandbox: true` route
-also reads `.js` as ESM independently of Node package settings, but a trusted
-route imports `.js` through Node's own loader, so an ESM `.js` module needs the
-nearest `package.json` to declare `"type": "module"`; under `"type": "commonjs"`
-it fails activation. Prefer `.mjs` for modules that must work in either mode.
-[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`.
-
-### Trust: unsandboxed by default, `sandbox: true` opt-in
-
-A route's `function`/`middleware` chain runs one of two ways, chosen by the
-route's `sandbox` field (false or absent — the default — versus `true`; see
-[docs/SPIKE-DEFAULT-TRUST-MODEL.md](SPIKE-DEFAULT-TRUST-MODEL.md)):
-
-- **`sandbox` false/absent (trusted, the default):** the module is imported
-  directly into the host process with ordinary Node module resolution — bare
-  specifiers, `node:` builtins, npm packages and dynamic `import()` all work,
-  none of the module-graph/source-size limits below apply, and there is no
-  fresh-heap-per-call reset (module-level state persists across requests like
-  any other Node server). The handler/middleware signature and `context`
-  shape are unchanged from the sandboxed contract below; a trusted function
-  additionally has the full Fetch API, Node built-ins and the filesystem
-  available to it, not just the guest text/JSON subset. `args`/`env`/
-  `secrets` are exactly what the route declares and an operator grants,
-  identically to the sandboxed path.
-- **`sandbox: true`:** the rest of this section, unchanged from every earlier
-  release. A sandboxed route's functions and middleware execute inside
-  QuickJS/WASM, never through Node imports.
-
-The remainder of this section (module restrictions, the guest API subset,
-guest limits and deadlines) describes the `sandbox: true` path specifically,
-unless stated otherwise.
-
-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
-imports remain restricted to the route's middleware and handler dependency graphs; there is no fallback.
-Source limits: 128 modules, 1 MiB per module, 4 MiB total.
-
-The current guest API is a **text/JSON subset**, not the complete native Fetch
-API: Request `url`, `method`, `headers`, `text()`, `json()`; Headers append/set/
-delete/get/has/entries/getSetCookie; Response constructor with string/null body,
-`status`, `headers`, `ok`, `text()`, `json()`, static `json()` and `redirect()`.
-Requests decode body bytes as UTF-8. Binary/streaming bodies, URL helpers,
-fetch/WebSocket, crypto and filesystem are not exposed. Promise/async and
-bounded timers (128 pending per invocation) work inside the guest. Unsupported
-APIs fail; they never execute on the host. Do not claim full browser/Node API
-parity for a `sandbox: true` route; a trusted route has no such restriction.
-
-Context contains `inputs.path/query/header`, `args`, `env`, `secrets`. Arguments
-may be scalar literals, input references, `{env: alias}` or `{secret: alias}`.
-Bindings use `{value: "literal"}`, `{env: EXTERNAL_NAME}` or `{secret: logical_name}`.
-Literal non-secret values need no grant. Every external environment or secret
-binding is denied unless an operator policy grants that exact name to the route
-and matches the SHA-256 of the current configuration/source snapshot.
-A project cannot grant itself capabilities. See [policy setup](FUNCTION-SECURITY.md).
-Missing bindings also reject activation. Inspection parses source without running it.
-
-Development may read `.env.local`; process values win. Serving never reads it.
-Dotenv supports single-line NAME=value, paired single/double quotes, blank lines
-and full-line comments, without expansion/escapes/shell execution. Loading a
-value does not authorize exposing it to a function; the policy still applies.
-
-A `sandbox: true` invocation has a fresh guest heap and module state every
-time. No cross-request counters, cached secrets or prototype mutation. QuickJS
-heap limit is 32 MiB, stack limit 512 KiB; outer worker and deployment limits
-are additional defenses, not a claim that total process RSS is capped at 32
-MiB. Two workers, no queue; saturation returns 503. The independent 5-second
-deadline terminates a worker and returns 504. Generic failures return 502;
-worker replacement is bounded. A trusted route has none of this: no fresh
-heap/module reset, no fixed worker-pool ceiling (bounded instead by ordinary
-Node concurrency and the HTTP admission cap), and its deadline races the
-call's promise rather than force-terminating a worker — see
-[capacity](CAPACITY.md) for both models side by side.
-
-HEAD invokes the handler as HEAD and suppresses body output. Code must guard
-its own application side effects when future brokered integrations are enabled.
-Guest console output is discarded. Functions see the configured public origin,
-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`.
-
-A trusted (non-`sandbox`) route already has unrestricted host execution by
-design — that is the point of the default described above. For a `sandbox:
-true` route, there is no unrestricted host-execution fallback: declarative
-proxy and webhook signals use the separately granted host broker described in
-[egress](EGRESS.md), and that route's guests still have no fetch API or
-general persistent state capability. Approved secrets can be returned by code
-that receives them, in either mode; isolation does not automatically enforce
-information-flow rules on authorized inputs. Keep grants narrow and review the
-exact pinned revision. The `sandbox: true` path still needs independent
-security review before hostile multi-tenant use of that specific mode; that
-review's scope was never a claim about a route that opts out of the sandbox
-(see [docs/SANDBOX-REVIEW.md](SANDBOX-REVIEW.md)).
-
-## Reload and status
-
-`dev` polls project YAML/JSON/JS and `.env.local` every 500 ms, plus declared
-asset files/directories (including binary assets and explicit build directories).
-Asset polling uses file metadata; production assets stay fixed until restart.
-The general source scan excludes common
-build/dependency directories and hidden files. Includes and source dependencies
-must be normal watched files; changes in symlink targets or `node_modules`
-require restart. A candidate fully validates and initializes its functions
-and snapshots its assets before activation. Invalid candidates leave the old snapshot serving. In-flight
-function calls finish on their original snapshot; new requests use the new one.
-Production `serve` is a fixed snapshot; restart/redeploy for code, secret or
-operator-policy changes. Config/code edits invalidate old binding grants.
-
-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. MCP defaults to inspection; the
-explicit `--allow-authoring` option enables bounded project writes, separately
-from host-file loading and grants. [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.

package/docs/SPIKE-AI-FRAMEWORK-BENCHMARK.md

@@ -1,288 +0,0 @@
-# Spike: AI-first URLCode framework benchmark
-
-Status: proposed research and execution plan. This document adds no benchmark
-implementation or measured results. It preserves the agreed independent-agent
-experiment and improvement loop; executing the phases below is follow-up work.
-
-## Objective and core principle
-
-Measure whether autonomous agents can build a correct, realistic application
-with URLCode, how much application intent its abstractions express, how easily
-agents discover those abstractions, and how the resulting application performs.
-Report AI effectiveness, framework expressiveness, AI discoverability and runtime
-performance separately. Do not collapse them into a single score or assume that
-URLCode will outperform another framework.
-
-The canonical implementation rule for the explicitly guided run is:
-
-> Use URLCode's highest-level declarative features whenever possible. Generate custom JavaScript only when the framework cannot express the requirement.
-
-Before implementing functionality manually, check for a declarative primitive,
-YAML configuration, built-in capability, extension, reusable template or documented
-pattern. Custom JavaScript is an escape hatch. The experiment must also establish
-whether an unfamiliar agent discovers this approach without explicit coaching.
-
-## Phase 0 — Research existing work first
-
-Before building the application or a new harness, investigate:
-
-- RealWorld / Conduit and its reusable application and acceptance specification.
-- TechEmpower Framework Benchmarks and their runtime methodology.
-- SWE-bench and other coding-agent benchmarks.
-- Agent productivity studies, framework comparison applications and standard
-  CRUD/full-stack benchmark applications.
-- URLCode's existing [agent harness](../benchmarks/agent/README.md), authoring
-  evals, [next-steps plan](archive/2026-09-19/NEXT-STEPS.md), and runtime benchmarks in
-  `benchmarks/routing.ts`, `benchmarks/bulk.ts` and
-  `benchmarks/sandbox-vs-trusted.ts`.
-
-Write a dated research report with primary-source links, versions/revisions,
-what each candidate measures, what can be reused, what is missing, and the
-reuse/adapt/build decision. Verify current maintenance status during research;
-do not assume this proposal is novel or that an additional suite is necessary.
-
-The existing agent harness already records shared acceptance results, generated
-lines, prompts and provider-reported usage. Its README explicitly limits claims:
-its tasks do not test persistence or runtime performance, its URLCode arm receives
-curated guidance, and stub records are pipeline tests rather than model evidence.
-Reuse suitable accounting and acceptance infrastructure after auditing it against
-the current runtime. Do not treat its guided arm as the unprompted baseline or
-silently reinterpret historical measurements under a new counting rule.
-
-Exit criterion: record the selected specification and harness approach before
-implementation begins, including the evidence for any departure from existing work.
-
-## Phase 1 — Freeze a realistic, framework-neutral specification
-
-Prefer RealWorld when practical. Otherwise justify a smaller RealWorld-inspired
-application, such as TaskFlow: users own projects, projects contain tasks, and
-users cannot access another user's private records. A basic Todo application alone
-is insufficient. Freeze observable API behavior and shared acceptance tests before
-agent runs; use exactly the same requirements for URLCode and Fastify.
-
-Exercise routing, CRUD, authentication, authorization, persistent relational data,
-relationships, validation, structured errors, filtering, sorting, pagination,
-environment configuration, secrets, middleware, logging and automated tests.
-Include registration/login, current-user lookup, ownership checks, restart
-persistence, invalid inputs and unauthenticated/unauthorized requests in acceptance
-coverage. Define logout semantics if applicable to the selected authentication
-model. Specify a health endpoint and reproducible schema/migrations and seed data.
-
-Also define isolated plaintext, JSON serialization, single-record database read
-and database write endpoints, borrowing established runtime benchmark semantics
-where practical. Freeze response bodies, status codes, headers, data size, database
-work and cache behavior; database reads must actually hit the database, and writes
-must persist. Keep these separate from realistic application workloads.
-
-Use the same database engine/version and equivalent data in all comparable runs.
-Choose it before implementation, not separately for each framework. Use synthetic
-data and environment-supplied secrets. Keep benchmark applications isolated from
-production runtime source. Record permitted extension packages and versions;
-extension functionality must not be presented as built into core.
-
-Correctness is the first gate: report passed/total acceptance cases, incomplete
-requirements and failures. Do not compare an incomplete application's apparent
-code savings or throughput as if it delivered the same functionality.
-
-## Phase 2 — Reproducible harness and measurement
-
-Capture exact prompts, model identifiers, agent/version, framework and extension
-commits, lockfiles, documentation snapshots, harness version, runtime, OS, hardware,
-database, tools and configuration. Record the initial workspace and available
-instructions/tools. Fix time, turn and token budgets, stopping rules and permitted
-human assistance before running; log interventions and failed or capped runs.
-
-| Area | Measurements |
-|---|---|
-| Agent work | Input/output/cached/total tokens, elapsed time, turns, tool calls, shell commands, documentation searches, test/fix cycles, completion rate |
-| Implementation | Total/source/configuration/JS/TS files, application LOC, configuration LOC, test LOC, direct/transitive dependencies, custom handlers and custom JavaScript |
-| URLCode expression | Declarative routes, routes needing custom code, declarative versus imperative LOC, required extensions, JavaScript escape hatches, functionality manually duplicated despite an existing capability |
-| Runtime | Startup time, idle memory, CPU, memory under load, requests/sec, p50/p95/p99 latency, response errors and timeouts |
-
-Never estimate unavailable measurements: mark them unavailable and explain why.
-Preserve provider usage fields and document whether cached tokens are included in
-input totals so totals do not double-count them. Separate measured values from
-derived calculations. Define LOC counting and exclusions in advance; separately
-report configuration, tests, generated output, dependencies and copied templates.
-Existing code-ratio metrics are not automatically declarative-coverage metrics.
-
-For runtime comparisons hold hardware/resource limits, runtime, database, data,
-concurrency, warm-up, duration and load generator constant. Specify startup start/
-ready events and memory/CPU sampling. Record trust/sandbox mode, worker counts,
-policies and extension overhead; compare equivalent behavior and disclose any
-unavoidable differences. Do not disable correctness or security requirements to
-improve scores. Reset data between trials and verify benchmark response semantics.
-
-Predeclare repeated fresh-agent runs and repeated runtime trials, retain every
-trial and report variability, sample counts and failures rather than selecting
-best runs. Keep the load generator from becoming the bottleneck. Version changed
-prompts, fixtures and counting rules so incompatible results are not pooled.
-
-## Phase 3 — Independent URLCode agents
-
-Each run starts with a fresh context and isolated worktree/environment. Agents
-must not see another agent's implementation, logs or findings. The coordinator
-collects evidence after each run; shared prompts contain the neutral specification
-and operational rules, not the hypothesis or a desired token/LOC outcome.
-
-### Protect the discovery baseline
-
-This spike itself contains the instruction being tested. Do not expose it, its
-index entry, benchmark prompts, prepared answers or prior findings to Agent A.
-Use a pinned source/documentation snapshot preceding this spike, or a documented
-filtered workspace with no access to excluded artifacts or repository history.
-Apply the same underlying snapshot and access controls to the comparison runs,
-with only the intended prompt treatment different. Record the exact manifest and
-restrictions; if an agent reads excluded material, mark the run contaminated and
-repeat it with a fresh agent rather than counting it as unprompted evidence.
-
-Existing product documentation, skills and ordinary repository instructions are
-part of what Agent A may discover; do not remove existing declarative guidance to
-manufacture a worse baseline. Preserve the baseline before changing those sources.
-
-### Agent A — Unprompted discovery
-
-Supply the application specification, URLCode source and existing documentation.
-The framework-specific instruction is only:
-
-> Build this application using URLCode following the framework's documented conventions and recommended practices.
-
-Do not supply the declarative-first rule or curated hints about where to find it.
-Record whether the agent independently finds and uses it, including evidence of
-unnecessary JavaScript, duplicated capabilities, missed primitives, misunderstood
-abstractions, repeated searches, incorrect assumptions, unclear errors and stalls.
-Treat these as potential framework/documentation problems, not automatically as
-agent failures.
-
-### Agent B — Explicitly URLCode-native
-
-Run the identical application from scratch with a fresh independent agent. Add:
-
-> Use URLCode's highest-level declarative features whenever possible. Generate custom JavaScript only when the framework cannot express the requirement.
-
-> Before implementing functionality manually, determine whether URLCode already provides a declarative primitive, YAML configuration, built-in capability, extension, reusable template, or documented pattern.
-
-Compare A and B on correctness, tokens, custom JavaScript, YAML, files, LOC,
-implementation time, debugging cycles and documentation searches. A repeatable
-advantage for B is evidence to investigate discoverability, not proof that every
-individual mistake is a documentation defect.
-
-### Agent C — Gap finder
-
-Use another fresh agent, independent of A/B implementations and findings during
-its attempt. Give it the same requirements and this instruction:
-
-> Attempt to implement every requirement using URLCode's intended abstractions. Whenever URLCode cannot express something cleanly, document the limitation rather than hiding it behind substantial custom code.
-
-Classify findings as missing capability, documentation gap, AI discoverability
-problem, confusing API/schema, poor error message, unnecessary boilerplate,
-extension-system limitation, performance problem, possible framework bug or agent
-misunderstanding. Record the attempted declaration, missing requirement, relevant
-documentation and any necessary workaround. A requirement that cannot be expressed
-stays visibly incomplete; substantial custom code must not hide the gap.
-
-## Phase 4 — Verify findings and prepare/file GitHub issues
-
-After independent attempts are preserved, reproduce each candidate problem against
-the pinned revision, inspect the supported contract and search existing issues and
-PRs. Distinguish missing functionality from functionality the agent failed to find.
-Do not file an issue merely because one agent made a mistake. Note corroborating
-encounters by multiple fresh agents, while avoiding unsupported causal claims.
-
-For each verified, actionable issue include:
-
-- Problem and benchmark scenario, affected repository/revision and environment.
-- Expected versus actual behavior and minimal synthetic reproduction.
-- Relevant YAML/code, commands, errors and links to run evidence.
-- Classification, proposed improvement and impact on human developers and agents.
-- Acceptance criteria and related/duplicate issue links.
-
-Use the owning repository's issue template and the ownership map in
-[AGENTS.md](../AGENTS.md): core/runtime issues belong here, documentation
-included -- `urlcode-docs` is deleted and cannot accept issues -- and extension
-defects in the corresponding extension repository.
-Update existing issues with new evidence rather than duplicating them. Track
-prepared, filed, duplicate and unverified dispositions in the findings report;
-file verified issues and retain unresolved hypotheses as explicitly unverified
-observations. Follow [SECURITY.md](../SECURITY.md) for private vulnerability reports.
-
-## Phase 5 — Audit AI discoverability
-
-Audit README, documentation, examples, schemas, CLI help, package metadata,
-`llms.txt`, agent instructions/skills, scaffolding and errors. Determine whether an
-unfamiliar agent can find the framework's purpose, declarative-first philosophy,
-YAML capabilities, built-in primitives, extensions, authentication, database access,
-validation, errors, custom functionality, testing and debugging guidance.
-
-Specifically search for guidance equivalent to the canonical rule above; record
-exact locations, prominence and the navigation/search path used to discover it.
-Do not assume it is absent just because the exact sentence is missing. Check the
-current contract when documents and historical benchmark assumptions differ.
-
-Preserve Agent A's baseline before editing guidance. Then propose the smallest
-authoritative set of changes that makes the principle clear to people and agents,
-including when custom JavaScript is appropriate. Public authoring guidance and
-contributor records both belong here, now that `urlcode-docs` is deleted. Do not copy the rule
-everywhere or expose the experimental prompt as product guidance by accident.
-
-## Phase 6 — Fastify comparison
-
-Once the URLCode methodology works, give a fresh independent agent the same frozen
-specification, budgets, tool access and acceptance criteria, using:
-
-> Build this application using Fastify following the framework's documented conventions and recommended practices.
-
-Do not mention URLCode or expose its implementations/findings. Use Fastify
-idiomatically; do not force it to imitate URLCode's architecture. Compare correctness,
-agent work, files/LOC/dependencies, configuration, debugging/searches and runtime
-measurements separately. Document framework-specific dependencies and setup work.
-Later candidates include Hono, Express, NestJS and Elysia; they are not prerequisites
-for the first comparison.
-
-## Phase 7 — Findings and deliverables
-
-Publish the contributor findings in `docs/benchmarks/AI_FRAMEWORK_BENCHMARK.md` when
-runs exist. Keep implementation and raw evidence paths versioned and linked from
-that report; do not create a results document implying measurements already exist.
-Deliver:
-
-1. Dated benchmark research and reuse decision.
-2. Frozen application specification and shared acceptance suite.
-3. Reproducible harness, commands and independent agent prompts.
-4. URLCode A/B/C and Fastify implementations or explicit incomplete outcomes.
-5. Raw agent logs/usage, implementation counts and runtime trial data.
-6. Methodology, provenance, comparison tables, uncertainty and evidence limitations.
-7. Agent behavior/search/failure analysis and classified framework/discovery gaps.
-8. Verified issue ledger, proposed/filed issue links and prioritized improvements.
-9. Before/after findings following the fresh-agent regression phase.
-
-Remove secrets from published logs while retaining measurement provenance. Keep
-stub/harness validation records distinct from real-agent evidence. Report every
-failed attempt, not just successful applications, and avoid subjective scores or
-claims beyond the measured cases.
-
-## Phases 8–9 — Improve and rerun with fresh agents
-
-Prioritize demonstrated friction: missing declarative primitives, defaults, YAML,
-schemas, errors, examples, extension discovery, README/AI documentation, CLI and
-scaffolding. Make legitimate application-development improvements, not special
-cases that game the benchmark. Track each change to its verified issue/evidence.
-
-After improvements, rerun with entirely fresh agents and isolated environments.
-The new discovery agent must again receive no explicit declarative-first rule or
-prior findings; it may discover the improved ordinary documentation naturally.
-Keep this spike and benchmark answers excluded. Repeat B, C and the comparison
-where needed to distinguish framework changes from model/harness drift. Hold model,
-budgets, requirements and runtime conditions fixed where possible; disclose changes
-and do not attribute their effects solely to URLCode.
-
-Compare before/after correctness, tokens, elapsed time, generated JavaScript, YAML,
-LOC, files, dependencies, tool calls, searches, failed attempts, test/fix cycles and
-runtime performance. Keep dimensions separate and preserve the original baseline.
-
-The repeatable loop is: independent agent encounters friction → evidence captures
-it → verified issue → URLCode improvement → fresh-agent rerun → measured outcome.
-Use it for significant releases to detect regressions in AI usability, declarative
-coverage, documentation, capability and runtime performance. Completion means
-reproducible evidence and an actionable issue/improvement trail, not a claim that
-URLCode won the comparison.