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

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. Stored short links are moving to a future `urlcode-dynamic-link`
+extension package (mount-based, like `auth`/`admin`), not yet published. A
+project needing them declares an `extension` mount once that package exists;
+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
 

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

@@ -0,0 +1,287 @@
+# 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](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, public documentation
+in `urlcode-docs`, 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 belongs
+in `urlcode-docs`; contributor records and spikes remain here. 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

@@ -5,6 +5,14 @@ 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 the
+> separate [`urlcode-dynamic-link`](https://github.com/jimhoyd-com/urlcode-dynamic-link)
+> package. 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, not current core.
+
 ## Recommendation
 
 Build seven independently released Apache-2.0 applications on URLCode: