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

package/docs/SANDBOX-REVIEW.md

@@ -1,9 +1,19 @@
 # Independent sandbox review gate
 
+Scope: this gate is about the `sandbox: true` execution path only —
+`function`/`middleware` routes run trusted and unsandboxed by default
+(docs/SPIKE-DEFAULT-TRUST-MODEL.md), and a trusted route's full Node access is
+by design, not a gap this review closes. Nothing here claims to review
+arbitrary trusted project code; that trust is the project's own call, made
+per route.
+
 Status: **external assessment not performed**. Internal source review, CI, CodeQL
 and adversarial regressions are useful evidence, not an independent sign-off.
-Do not host anonymous hostile multi-tenant code before this gate is closed.
-No unrestricted Node execution fallback is permitted.
+Do not host anonymous hostile multi-tenant code in a `sandbox: true` route
+before this gate is closed, and do not run untrusted/unreviewed code in a
+trusted (non-`sandbox`) route at all — that path was never sandboxed and this
+gate does not apply to it. No unrestricted Node execution fallback is
+permitted *within a route that declared `sandbox: true`*.
 
 ## Review package
 
@@ -15,14 +25,17 @@ resource settings. Give a reviewer independent of the implementation access to:
   module graph, import denial, export validation, binding grants and message bridge.
 - `src/config.ts`, `src/config-worker.ts`, router and assets: parser/schema limits,
   file containment, activation, memory amplification and host-side compilation.
-- HTTP server, management API/policy and link-store worker: request smuggling,
-  admission, body/response framing, authorization, revocation and atomic audit.
-- `test/sandbox.test.ts`, middleware/config/links/logging/reload tests, Dockerfile,
+- HTTP server and policy: request smuggling, admission, body/response framing.
+- `test/sandbox.test.ts`, middleware/config/logging/reload tests, Dockerfile,
   protected workflows and `docs/FUNCTION-SECURITY.md`.
+- `src/runtime.ts`'s dispatch decision (`route.sandbox ? pool : trusted`) and
+  `src/trusted-functions.ts`: confirm a route that declares `sandbox: true`
+  can never be dispatched through the trusted, in-process path by any code
+  path, and that `sandbox: false`/absent never reaches `FunctionPool`.
 
 Run `npm ci --ignore-scripts`, `npm run verify`, `npm run test:package`, and
 `node scripts/operational-drills.ts`. Record the exact commands and result files.
-CI adds constrained-container and real disposable-volume exhaustion tests.
+CI adds a constrained-container test.
 Use only disposable local/staging systems with synthetic data.
 
 ## Threat model and required probes

package/docs/SCAFFOLDING.md

@@ -68,5 +68,3 @@ Scaffolding does not recursively invent dependencies imported by existing code,
 crawl HTML/CSS links, generate binary content, or implement your business logic.
 See [readiness checks](READINESS.md) and [asset behavior](ASSETS.md).
 
-Scaffolding enforces the entry-level `dynamicLinks` opt-in for `link` handlers
-and reports the effective boolean. It never enables this capability for you.

package/docs/SECURITY-AUDIT.md

@@ -1,3 +1,38 @@
+# Security review — 2026-09-18
+
+Scope: trust-model change (docs/SPIKE-DEFAULT-TRUST-MODEL.md). `function`/
+`middleware` routes now run trusted and unsandboxed by default, with
+`sandbox: true` as an explicit per-route opt-in to the isolation this document's
+earlier entries describe. This is a maintainer-decided policy reversal, not a
+finding; it is recorded here because it changes what every earlier entry's
+"guest"/"sandbox" language means going forward.
+
+**What did not change:** the `sandbox: true` execution path — QuickJS/WASM
+isolation, module-graph restriction, fresh heap per call, worker deadline —
+is byte-for-byte the same as every earlier entry describes; nothing in this
+change touched `src/functions.ts`, `src/function-worker.ts` or `src/guest-api.ts`.
+Binding grants are unaffected either way: `env`/`secrets` still reach only a
+route that explicitly declared them and an operator policy pinned to the
+project revision explicitly granted, whether that route is trusted or
+sandboxed.
+
+**What did change, and the resulting residual risk:** a `function`/
+`middleware` route with no `sandbox` field (the common case going forward, and
+every existing project's routes after an upgrade with no YAML change) now runs
+in the host process with full Node access — the isolation earlier entries'
+"remaining gaps" language assumed for *all* guest code no longer applies to
+it. The residual-risk framing in earlier entries ("before exposing hostile
+multi-tenant workloads, obtain independent review of WASM/host boundaries")
+is scoped to `sandbox: true` routes specifically; it was never a claim that
+covered a route that opts out of the sandbox, and after this change most
+routes do exactly that by default. Whether a given project's own function/
+middleware code is safe to trust with full host access is now the project's
+judgment call, not something this runtime's isolation reviews (past or
+future) can speak to. New source review of the dispatch decision itself
+(`src/runtime.ts`, `src/trusted-functions.ts`, `src/policy.ts`'s split
+grant-hashing) accompanies the change; see the pull request that introduced
+`sandbox` for its own description of what was and was not verified.
+
 # Security review — 2026-09-17
 
 Scope: follow-up source review of worker/connection replacement, probe admission,
@@ -5,6 +40,11 @@ request correlation, operational logging, dependency/release supply chain and th
 live-link Node requirement. Regression tests accompany the fixes. Internal review,
 not an independent penetration test.
 
+This is a dated record, not current guidance. The `link` handler, its SQLite
+store and the link-store/management findings below were removed from core in
+a later change; they describe the runtime as it existed on this date, not the
+current one.
+
 ## Findings fixed in this revision
 
 | Finding | Impact and evidence | Fix / regression |
@@ -45,7 +85,7 @@ Management event status 0 means no response headers were sent before disconnect.
 An aborted request may have committed a mutation: reconcile record/version before
 retrying. These logs are best effort, may be dropped under pressure, identify a configured credential ID (or a legacy shared token), and are not a
 tamper-evident journal. Successful store mutations now have separate transactional
-audit records; see [management security](MANAGEMENT-SECURITY.md). A failed sink needs collector/operator recovery;
+audit records; see [management security](archive/2026-09-19/MANAGEMENT-SECURITY.md). A failed sink needs collector/operator recovery;
 URLCode cannot report failures reliably through the same broken output stream.
 
 ## Boundaries checked
@@ -82,7 +122,7 @@ limits. No anonymous code/config upload service is approved by these changes.
 collection/action scopes, expiry and hot revocation, plus atomic SQLite mutation
 audits are implemented. Legacy shared tokens remain for compatibility. There is
 no public user-account system, MFA/SSO, built-in rate limiter, credential issuance
-service or external tamper-evident archive. See [management security](MANAGEMENT-SECURITY.md).
+service or external tamper-evident archive. See [management security](archive/2026-09-19/MANAGEMENT-SECURITY.md).
 
 **Before claiming operational readiness:** execute sustained mixed-workload soak,
 backup restoration, disk-full, process-kill, proxy timeout and rollback drills on

package/docs/SPECIFICATION.md

@@ -35,7 +35,7 @@ support a terminal `/*` wildcard with an otherwise literal path. Route keys cann
 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`, `link`, `conditional` or `proxy`.
+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;
@@ -56,8 +56,8 @@ Requests decode the path once; invalid UTF-8/percent encoding, encoded slashes o
 backslashes, control characters and dot segments return 400. Query values decode
 once. Incoming query data is not automatically forwarded.
 
-See [route matching and new links](ROUTING.md) for examples, precedence, wildcard
-limits, reload behavior and the distinction between YAML routes and live link data.
+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`,
@@ -157,15 +157,11 @@ keys preserve repeated values. Headers are forwarded only through explicit maps.
 
 ## Stored links
 
-The entry `urlcode.yaml` must opt in with `dynamicLinks: true` (default false).
-Included files cannot set this project-level flag. Parameterized redirects and
-functions do not require it.
-
-`link: {collection: links, code: {from: path, name: code}}` resolves a declared
-path input against an operator-bound store. GET/HEAD only. The logical collection
-is portable; file paths and store credentials are external deployment bindings.
-No general storage capability is exposed to guest code. See [dynamic links](DYNAMIC-LINKS.md)
-for validation, persistence, mutation, expiry and read-after-write behavior.
+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
 
@@ -211,8 +207,34 @@ ES modules only (`.mjs` or `.js`, independent of Node package settings).
 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`
+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.
@@ -225,7 +247,8 @@ delete/get/has/entries/getSetCookie; Response constructor with string/null body,
 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.
+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}`.
@@ -241,12 +264,17 @@ 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.
 
-Every invocation has a fresh guest heap and module state. 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 `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.
@@ -255,12 +283,18 @@ 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. 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
+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 still needs independent security review before hostile multi-tenant use.
+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
 
@@ -295,7 +329,9 @@ are local Git-owned examples; they grant no capabilities. [Build-time TypeScript
 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)
+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;

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

@@ -0,0 +1,288 @@
+# 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.

package/docs/SPIKE-BUSINESS-SUITE.md

@@ -1,10 +1,26 @@
 # URLCode business suite spike
 
+> Review update, 2026-09-19: Current status: an unapproved candidate list, gated on observed repetition
+> and benchmark evidence under PROJECT-DIRECTION.md. The short-link products
+> are retired; the seven-product recommendation below is historical, not agreed
+> current scope. No business-suite implementation is implied.
+
+
 Date: 2026-09-18. Status: proposal, not an implemented contract or production claim.
 Core inspected at `50790d3` (0.4.0-alpha.1), plus local auth, admin, UI and
 shortener source/status files. Competitor research below is a documentation
 review, not hands-on benchmarking. Features and commercial packaging can change.
 
+> **Update:** this proposal was written when `link`/`LinkStore` was still a
+> native core feature. Core no longer has that API — it was extracted to a
+> separate `urlcode-dynamic-link` package, which has since been retired,
+> unpublished and deleted (September 2026), along with the `urlcode-short`
+> shortener this document proposes. Those two products are no longer planned.
+> References below to core owning link storage (e.g. "Reuse core's LinkStore",
+> "Retain core link semantics", the `core LinkStore -> short` dependency line)
+> describe the pre-extraction state this spike was proposing against, and the
+> `urlcode-short` migration sections record an abandoned plan.
+
 ## Recommendation
 
 Build seven independently released Apache-2.0 applications on URLCode: