@jimhoyd/urlcode 0.3.0

package/dist/policies.js

@@ -0,0 +1,142 @@
+import * as agents from './policies/agents.js';
+import * as throttle from './policies/throttle.js';
+import * as cache from './policies/cache.js';
+import * as security from './policies/security.js';
+import * as compression from './policies/compression.js';
+import { assert, ConfigError } from './errors.js';
+                                                     
+                                                            
+                                                                                                                                                                                                                                                               
+                                                                                                        
+
+// Host-side behavior declared in YAML and enforced outside the sandbox. Every
+// module here follows one contract so a first-party policy and an operator
+// plugin share a code path (PolicyModule in src/types.ts):
+//
+//   name          the YAML key under `policies`
+//   phases        'request' | 'response' | both; fixed order below
+//   targets(cfg)  {node, vercel, aws, cloudflare} → 'native' | 'compiled' | 'delegated' | 'refused'
+//                 delegated: the platform already provides it, so the policy is
+//                 accepted and dropped rather than refusing the deployment
+//   compile(cfg, {route, shared, target, document, root}) → state, or throws ConfigError
+//   onRequest(state, req)          → result to short-circuit, or undefined
+//   onResponse(state, req, result) → result (same or replaced)
+//   onError(state, req, error)     → result to answer with instead, or undefined
+//   describe(state)                → JSON summary for audit/inventory
+//   close(shared)                  → release cross-request state
+//
+// Request order: agents (cheapest denial first), throttle, cache lookup.
+// Response order: cache store, throttle headers (after the store, so a cached
+// copy is never stamped with one client's remaining budget), security headers,
+// compression last so every header it depends on is already final. YAML response.headers are applied by
+// the runtime before this phase, so explicit headers beat profile defaults.
+/** The registry, typed per policy so `registry.cache.compile` returns a CacheState; erased to PolicyModule where iterated. */
+                                                                                                                           
+export const registry                 = { agents, throttle, cache, security, compression };
+export const requestOrder                        = ['agents','throttle','cache'];
+export const responseOrder                        = ['cache','throttle','security','compression'];
+export const targets                        = ['node','vercel','aws','cloudflare'];
+const isPolicyName = (name        )                     => Object.hasOwn(registry, name);
+
+// What a profile is: a policies object without `profile`. The built-in one is
+// a starting point that reads in one place, not a claim about any workload.
+export const builtinProfiles                                        = Object.freeze({
+  hardened: Object.freeze             ({
+    security: { headers: 'oshp' },
+    agents: { deny: ['ai-crawlers'], status: 403 },
+    throttle: { quota: 120, window: 60, partition: 'client', status: 429 },
+    compression: { encodings: ['br','gzip'], minBytes: 1024 },
+    cache: { strategy: 'revalidate' },
+  }),
+});
+
+function resolveProfile(name                    , document                 )              {
+  if (!name) return {};
+  const custom = document.profiles?.[name];
+  if (custom) return custom;
+  const builtin = builtinProfiles[name];
+  assert(builtin, `Unknown policy profile "${name}"`);
+  return builtin;
+}
+
+// Effective configuration for one route: profile ← project keys ← route
+// profile ← route keys. `false` disables a policy at any level; an object
+// merges shallowly over what is below it, so a route can tighten one number
+// without restating the rest.
+export function effectivePolicies(document                 , routeConfig                                           )                    {
+  const layers                   = [];
+  const project = document.policies || {};
+  layers.push(resolveProfile(project.profile, document), project);
+  const route = routeConfig?.policies || {};
+  if (route.profile) layers.push(resolveProfile(route.profile, document));
+  layers.push(route);
+  const effective                         = {};
+  for (const layer of layers) for (const [key, value] of Object.entries(layer)) {
+    if (key === 'profile') continue;
+    if (value === false) { delete effective[key]; continue; }
+    effective[key] = { ...(effective[key] || {}), ...value };
+  }
+  return effective                     ; // the schema admits only the five policy keys in a layer
+}
+
+// Compiles every declared policy for a route into ordered request/response
+// chains. A target that cannot honour a policy refuses the whole activation
+// with the route and policy named, the same rule adapters apply to handlers.
+export async function compilePolicies(document                 , routeConfig                                           , { route, shared, target = 'node', root }               )                       {
+  const effective = effectivePolicies(document, routeConfig);
+  const chain              = { request: [], response: [], error: [], describe: {} };
+  const states                        = chain;
+  // Generic over the name so the module, its config and its state stay correlated.
+  async function compileOne                      (name   , config                  )                {
+    const module = registry[name];
+    const support = module.targets(config)[target];
+    if (support === 'refused') throw new ConfigError(`${route.pattern} declares policies.${name}, which the ${target} target cannot enforce`);
+    if (support === 'delegated') { chain.describe[name] = { target: support }; return; }
+    const state = await module.compile(config, { route, shared, target, document, ...(root === undefined ? {} : { root }) });
+    const described                                 = module.describe?.(state) ?? {};
+    chain.describe[name] = { ...described, target: support };
+    states[name] = state;
+  }
+  for (const name of Object.keys(effective)) {
+    assert(isPolicyName(name), `Unknown policy "${name}"`);
+    await compileOne(name, effective[name] );
+  }
+  const entry = (name            )                          => [registry[name], chain[name]];
+  for (const name of requestOrder) if (chain[name] && registry[name].onRequest) chain.request.push(entry(name));
+  for (const name of responseOrder) if (chain[name] && registry[name].onResponse) chain.response.push(entry(name));
+  for (const name of Object.keys(effective)) if (isPolicyName(name) && registry[name].onError) chain.error.push(entry(name));
+  return chain;
+}
+
+// The security headers an error response gets. A thrown error has no route
+// result to decorate, so the host asks for the header list instead: the
+// matched route's own security state when there is one, otherwise the
+// project-level policy compiled once here. Nothing else applies to errors:
+// their bodies are fixed text and nothing may cache or count them twice.
+export function compileErrorPolicy(document                 , { target = 'node' }                          = {})                       {
+  const effective = effectivePolicies(document, {});
+  const config = effective.security;
+  if (!config || registry.security.targets(config)[target] === 'refused') return null;
+  return security.compile(config, { route: { pattern: '(project)' } });
+}
+export function errorHeaders(state                                  , origin                    )               {
+  if (!state) return [];
+  return security.onResponse(state, { origin }, { status: 200, headers: [] }).headers;
+}
+
+export async function closePolicies(shared              )                {
+  for (const module of Object.values(registry)                  ) await module.close?.(shared);
+}
+
+// The request a policy sees. Nothing here is parsed twice: headers and target
+// are the runtime's own objects, the client identity is what the host resolved
+// through its trusted-proxy setting (never a raw forwarded header) and the
+// route is the configured pattern, not request text.
+                                     
+                                                                                                        
+                                                                                                                                                        
+                                                               
+ 
+export function policyRequest({ method, target, path, params = {}, query, headers, headerCounts, client, origin, route }                    )                {
+  return { method, target, path, params, query, headers, headerCounts, client: client ?? null, origin, route: route.pattern, secrets: Object.keys(route.secrets || {}).length > 0 };
+}

package/dist/policy.js

@@ -0,0 +1,55 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { relative, isAbsolute, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { functionFile } from './config.js';
+import { collectFunctionSources, routeFunctions } from './function-sources.js';
+                                                                                 
+import { assert } from './errors.js';
+                                                 
+
+/** The operator's binding grants: which env and secret names each route may read, pinned to a project hash. */
+                                                                                                                                     
+/** The function snapshot plus the hash operator grants are pinned to. */
+                                                                                   
+
+export async function prepareFunctionSnapshot(loaded                )                            {
+  const definitions                                                      = [];
+  for (const [pattern,route] of Object.entries(loaded.routes)) for (const definition of routeFunctions(route)) definitions.push({pattern,function:{
+    source:await functionFile(loaded.root,definition.source),export:definition.export || 'default',
+  }});
+  const collected = await collectFunctionSources(definitions,loaded.root);
+  const sources = Object.fromEntries(Object.entries(collected.sources).sort(([a],[b])=>a < b ? -1 : a > b ? 1 : 0));
+  // Generated site routes carry no bindings and depend on the origin, so they
+  // stay out of the hash that operator grants are pinned to.
+  const declared = Object.fromEntries(Object.entries(loaded.routes).filter(([,route])=>!route.generated));
+  const snapshot                   = { ...collected, projectSha256: createHash('sha256').update(JSON.stringify({routes:declared,...(loaded.document.dynamicLinks===true?{dynamicLinks:true}:{}),sources})).digest('hex') };
+  return snapshot;
+}
+export function validatePolicy(value         )                 {
+  assert(value && typeof value === 'object' && !Array.isArray(value), 'Invalid operator policy');
+  const policy = value                           ; // trust boundary: operator JSON, checked field by field below
+  assert(Object.keys(policy).every(k=>['version','projectSha256','routes'].includes(k)) && policy.version === 1 && typeof policy.projectSha256 === 'string' && /^[a-f0-9]{64}$/.test(policy.projectSha256), 'Policy requires version 1 and projectSha256');
+  const routes = policy.routes;
+  assert(routes && typeof routes === 'object' && !Array.isArray(routes), 'Policy requires route grants');
+  for (const [path,grant] of Object.entries(routes)) {
+    assert(path.startsWith('/') && grant && typeof grant === 'object' && !Array.isArray(grant), 'Invalid route grant');
+    assert(Object.keys(grant).every(k=>['env','secrets'].includes(k)), 'Unsupported policy capability');
+    for (const list of Object.values(grant)) assert(Array.isArray(list) && list.length <= 64 && list.every(n=>typeof n === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(n)), 'Invalid binding grant');
+  }
+  return value                  ; // every field was just checked
+}
+export async function loadOperatorPolicy(file                    , project        )                                      {
+  if (!file) return undefined;
+  const root = await realpath(project), path = await realpath(file);
+  const rel = relative(root,path);
+  assert(isAbsolute(rel) || rel === '..' || rel.startsWith('..' + sep), 'Operator policy must be outside the application project');
+  assert((await stat(path)).size <= 65536, 'Policy exceeds 64 KiB');
+  return validatePolicy(JSON.parse(await readFile(path,'utf8')));
+}
+export function requestedPermissions(loaded                , snapshot                           )                 {
+  return {version:1,projectSha256:snapshot.projectSha256,routes:Object.fromEntries(Object.entries(loaded.routes).flatMap(([path,route])                                                   => {
+    const env = Object.values(route.env || {}).flatMap(ref=>ref.env ? [ref.env] : []);
+    const secrets = Object.values(route.secrets || {}).map(ref=>ref.secret);
+    return env.length || secrets.length ? [[path,{env:[...new Set(env)],secrets:[...new Set(secrets)]}]] : [];
+  }))};
+}

package/dist/prerender.js

@@ -0,0 +1,165 @@
+import {mkdir, writeFile} from 'node:fs/promises';
+import {resolve, relative, isAbsolute, join, dirname, sep} from 'node:path';
+import {createRuntime} from './runtime.js';
+import {ConfigError, assert} from './errors.js';
+                                                                
+                                      
+
+// Operator-side build tooling for rendering a project's function and middleware
+// routes once, ahead of serving, into HTML files that native page routes can
+// publish with no guest execution on the request path.
+//
+// This is trusted build code, not runtime code: it runs in Node, it is never
+// reachable from route YAML, and it gives the sandbox nothing. It owns the
+// orchestration that is easy to get wrong — runtime lifecycle, response
+// validation, budgets, byte fidelity and output-path safety — and deliberately
+// owns nothing site-specific. Callers assemble their own project or generated
+// include from the metadata it returns. See docs/PRERENDER.md.
+
+                                                                                               
+                                   
+                                                                                                                           
+                                                                                                                                
+ 
+                                                                              
+                                                                                                                                       
+
+// Names a static tree refuses to publish, rejected here so a bad route path
+// fails the build instead of the deployment.
+const PROTECTED = new Set(['urlcode.yaml', 'urlcode.yml', 'package.json', 'package-lock.json']);
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+// A published page name: no path separator, and no leading dot, which a static
+// tree skips as a hidden entry.
+const FILE = /^[A-Za-z0-9][A-Za-z0-9._~-]*\.html$/;
+const overlaps = (first        , second        )          => {
+  const rel = relative(first, second);
+  return rel === '' || !(isAbsolute(rel) || rel === '..' || rel.startsWith('..' + sep));
+};
+const isCode = (error         , code        )          => error instanceof Error && 'code' in error && error.code === code;
+
+// One route path to one flat filename, deterministically. `~` cannot occur in a
+// route segment, so it separates segments unambiguously: `/a/b` and `/a-b` are
+// distinct names rather than a silent collision. The root becomes `index`, and a
+// literal `/index` route takes the otherwise unreachable `index~`, so the
+// mapping stays injective for every accepted path. A flat name contains no path
+// separator and no leading dot, so no output can escape its directory.
+// A path that can become a file at all: absolute, literal, no parameter,
+// wildcard, dot segment or empty segment. Checked for every rendered route
+// whatever `fileName` does with it, so a custom hook cannot accept a route the
+// default scheme would refuse.
+export function assertLiteralRoutePath(path        )           {
+  assert(typeof path === 'string' && path.startsWith('/'), 'Route path must be absolute');
+  const segments = path === '/' ? [] : path.slice(1).split('/');
+  assert(segments.every(segment => SEGMENT.test(segment) && segment !== '.' && segment !== '..'),
+    `Cannot derive a filename from nonliteral route ${path}; prerender literal paths only`);
+  return segments;
+}
+
+export function pageFileName(path        )         {
+  const segments = assertLiteralRoutePath(path);
+  const name = segments.length === 1 && segments[0] === 'index' ? 'index~'
+    : segments.length ? segments.join('~') : 'index';
+  return `${name}.html`;
+}
+
+// Prove a project cannot execute guest code to answer a request: every route is
+// one of the allowed native handlers and none carries middleware. Callers run it
+// on a final assembled site, which normally also serves static files and
+// downloads, not only on a page-only artifact.
+export async function assertNativeProject(project        , {allow = ['page', 'static', 'download'], log = () => {}}                       = {})                            {
+  assert(Array.isArray(allow) && allow.length && allow.every(handler => typeof handler === 'string'), 'Allowed handlers must be a nonempty string array');
+  const runtime = await createRuntime(project, {log: () => {}});
+  try {
+    const inventory = runtime.testPlan().inventory;
+    assert(inventory.length, 'Project declares no routes');
+    const executable = inventory.filter(route => route.handler === undefined || !allow.includes(route.handler) || route.middleware);
+    assert(!executable.length,
+      `Project must contain only native ${allow.join('/')} routes without middleware: ${executable.map(route => `${route.path} (${route.handler}${route.middleware ? ' + middleware' : ''})`).join(', ')}`);
+    log({event: 'native-project', routes: inventory.length, handlers: allow});
+    return inventory;
+  } finally { await runtime.close(); }
+}
+
+export async function prerenderPages(project        , output        , {
+  origin = 'http://localhost', fileName = pageFileName, ignoreUnrenderable = false,
+  maxPages = 500, maxPageBytes = 512 * 1024, maxTotalBytes = 32 * 1024 * 1024, log = () => {},
+}                   = {})                           {
+  for (const [value, name] of [[maxPages, 'maxPages'], [maxPageBytes, 'maxPageBytes'], [maxTotalBytes, 'maxTotalBytes']]         )
+    assert(Number.isSafeInteger(value) && value > 0, `Build budget ${name} must be a positive integer`);
+  assert(typeof fileName === 'function', 'fileName must be a function');
+  assert(typeof ignoreUnrenderable === 'boolean', 'ignoreUnrenderable must be a boolean');
+  let parsed     ;
+  try { parsed = new URL(origin); } catch { assert(false, 'Invalid render origin'); }
+  assert(['http:', 'https:'].includes(parsed.protocol) && parsed.origin === origin, 'Render origin must be HTTP(S) without path or credentials');
+  const source = resolve(project), directory = resolve(output);
+  // Rendering into the reviewed source, or reading a source nested in the
+  // output, lets a build consume or overwrite what it just produced.
+  assert(!overlaps(source, directory) && !overlaps(directory, source), 'Source and output directories must not overlap');
+
+  const pages                                       = [];
+  let bytes = 0;
+  const runtime = await createRuntime(source, {log: () => {}});
+  try {
+    const inventory = runtime.testPlan().inventory;
+    const renderable = (route                ) => route.handler === 'function' && route.state === 'active' && route.methods.includes('GET');
+    const targets = inventory.filter(renderable);
+    // Silently skipping a route publishes an incomplete site that looks whole.
+    if (!ignoreUnrenderable) {
+      const skipped = inventory.filter(route => !renderable(route));
+      assert(!skipped.length,
+        `Source project has routes this build would not render: ${skipped.map(route => `${route.path} (${route.handler}, ${route.state})`).join(', ')}. Pass ignoreUnrenderable to allow it`);
+    }
+    assert(targets.length, 'Source project has no active GET function routes to prerender');
+    assert(targets.length <= maxPages, `Source project page count ${targets.length} exceeds maxPages ${maxPages}`);
+    // Case-insensitive: on macOS and Windows two names differing only in case
+    // are one file, so the second render would silently replace the first.
+    const taken = new Map                ();
+    for (const route of targets) {
+      assertLiteralRoutePath(route.path);
+      const file          = fileName(route.path);
+      assert(typeof file === 'string' && FILE.test(file) && !PROTECTED.has(file), `Unsafe output filename ${file} for route ${route.path}`);
+      const key = file.toLowerCase();
+      assert(!taken.has(key), `Routes ${taken.get(key)} and ${route.path} both render ${file}`);
+      taken.set(key, route.path);
+      const result = await runtime.handle({target: route.path, method: 'GET', origin});
+      assert(result.status === 200, `${route.path} rendered ${result.status}; expected 200`);
+      const type = result.headers.find(([name]) => name.toLowerCase() === 'content-type')?.[1] ?? '';
+      assert(/^text\/html\s*(?:;|$)/i.test(type), `${route.path} rendered ${type || 'no content type'}; expected text/html`);
+      // The response body is bytes. Keeping it as a Buffer is what preserves a
+      // multi-byte character exactly, through the file and its fixture alike.
+      const body = typeof result.body === 'string' ? Buffer.from(result.body) : Buffer.from(result.body ?? []);
+      assert(body.length > 0 && body.length <= maxPageBytes,
+        `${route.path} rendered ${body.length} bytes; expected 1..${maxPageBytes} (maxPageBytes)`);
+      bytes += body.length;
+      assert(bytes <= maxTotalBytes, `Rendered pages exceed the total budget of ${maxTotalBytes} bytes (maxTotalBytes)`);
+      pages.push({path: route.path, file, bytes: body.length, body});
+      log({event: 'prerendered', path: route.path, file, bytes: body.length});
+    }
+  } finally {
+    // The runtime owns worker threads. Close it whether or not the render
+    // succeeded, so a failing build exits instead of hanging.
+    await runtime.close();
+  }
+
+  // Nothing is written until every page has rendered, and the directory itself
+  // must be new: a failed or partial build never damages an existing artifact.
+  // Parents are created; only the leaf carries that guarantee.
+  await mkdir(dirname(directory), {recursive: true});
+  try { await mkdir(directory); }
+  catch (error) {
+    if (!isCode(error, 'EEXIST')) throw error;
+    // Keep the code so a caller can branch on it, with a message that says why.
+    throw Object.assign(new ConfigError(`Output directory ${directory} already exists; remove it before prerendering`), {code: 'EEXIST'});
+  }
+  for (const page of pages) await writeFile(join(directory, page.file), page.body);
+  return {
+    count: pages.length, bytes, directory,
+    pages: pages.map(({path, file, bytes: size}) => ({path, file, bytes: size})),
+    // Byte-for-byte GET plus empty HEAD, ready to concatenate with a caller's
+    // own fixtures. `.html` is served as text/html; charset=utf-8.
+    fixtures: pages.flatMap(page => [
+      {path: page.path, status: 200, expectHeaders: {'content-type': 'text/html; charset=utf-8'}, expectBody: page.body.toString('utf8')},
+      {path: page.path, method: 'HEAD', status: 200, expectBody: ''},
+    ]),
+  };
+}

package/dist/project-tests.js

@@ -0,0 +1,23 @@
+import { realpath } from 'node:fs/promises';
+import { Agent } from 'node:http';
+import { startServer } from './server.js';
+                                                 
+import { readCases, hit } from './readiness.js';
+                                        
+
+                                                                                                                                                                                
+                                                                    
+
+export async function runProjectTests(project        , { log = () => {}, permissions, linkStore, origin }                     = {})                             {
+  const root = await realpath(project), cases = await readCases(root);
+  const app = await startServer({ project, port: 0, local: true, log, permissions, linkStore, origin });
+  const agent = new Agent({keepAlive:true,maxSockets:1}); let failed = 0;
+  try {
+    for (const [i,test] of cases.entries()) {
+      const result=await hit(app,test,agent);
+      if(!result.pass)failed++;
+      log({event:'test',case:i+1,pass:result.pass,status:result.status});
+    }
+  } finally {agent.destroy();await app.close();}
+  return {total:cases.length,failed};
+}

package/dist/readiness.js

@@ -0,0 +1,216 @@
+import { request, Agent } from 'node:http';
+                                                                                
+import { request as secureRequest, Agent as SecureAgent } from 'node:https';
+                                            
+import { join } from 'node:path';
+import { readFile, lstat } from 'node:fs/promises';
+import { safeFile } from './config.js';
+import { assert } from './errors.js';
+import { parseTarget, matchRoute, contextFor, redirectLocation } from './router.js';
+import { runCompliance } from './compliance.js';
+                                                                                                              
+                                                                           
+                                                                 
+
+                                             
+                                                                                                        
+/** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
+                                                                                               
+/** One request case: a generated probe or a `tests/requests.json` fixture. */
+                              
+                                                                                                                                     
+                                                                                      
+ 
+                                                                                                                                 
+                                                                                                
+                                                                                              
+/** A started server as the audit and benchmark see it. structural: the real type is startServer's result in src/server.ts. */
+                                                                                                                                                                      
+                                                                           
+                                                                                                                                        
+                              
+                                                                       
+                                                                                                                       
+                                                                                                                                    
+                                                                                                                                                            
+ 
+                                                                                                                                                                                                                            
+                                  
+                                                                                                                                                              
+                                                                                                                                                                       
+                                                                                                                                                                                     
+ 
+
+const handlers = ['redirect','function','page','static','download','respond','link']                                          ;
+/** Narrows a compiled route to one that redirects, so redirectLocation can read its spec. */
+export const hasRedirect = (route               )                                                          => Boolean(route.redirect);
+const isRecord = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
+// Probes identify themselves so an agents policy that denies an empty
+// User-Agent does not fail every generated case; fixtures may override it.
+export const probeAgent = 'Mozilla/5.0 (compatible; RouteProbe/0.1)';
+export function projectPlan(compiled                               )              {
+  const routes = [...compiled.exact.values(), ...[...compiled.byLength.values()].flat(), ...compiled.mounts];
+  const now = Date.now();
+  const inventory                   = routes.map(route => ({ path:route.pattern, handler:handlers.find(key => route[key]), methods:route.methods, middleware:route.middleware?.length || 0,
+    policies:route.policy ? Object.keys(route.policy.describe) : [],
+    ...(route.generated ? { generated:route.generated } : {}),
+    state:route.enabled === false ? 'disabled' : route.expiresAt && now >= route.expiresAt ? 'expired' : 'active' }));
+  const cases                = [];
+  for (const [i,route] of routes.entries()) {
+    const entry = inventory[i];
+    if (!entry) continue;
+    if (entry.state !== 'active') {
+      if(!route.names.length && !route.static) cases.push({path:route.pattern,method:'GET',status:entry.state==='disabled'?404:410});
+      continue;
+    }
+    if (route.function || route.link || route.middleware?.length || route.names.length) continue;
+    // Required inputs need intentional fixtures; never invent business data.
+    let context                ;
+    try { context = contextFor(route,{},new URLSearchParams(),new Headers()); } catch { continue; }
+    if (route.request?.body?.required) continue;
+    const files = route.asset instanceof Map ? route.asset : undefined;
+    const prefix = route.prefix ?? '';
+    const paths = route.static && files ? [...files.keys()].map(key => prefix + key.split('/').map(encodeURIComponent).join('/')) : [route.pattern];
+    for (const path of paths) for (const method of route.methods) {
+      if (!['GET','HEAD'].includes(method)) continue;
+      const test              = {path,method,status:(route.redirect ? route.redirect.status || 302 : route.reply?.status || 200)};
+      if (hasRedirect(route)) test.expectHeaders = {location:redirectLocation(route,context,new URLSearchParams())};
+      const asset=route.static ? files?.get(decodeURIComponent(path.slice(prefix.length))) : route.asset instanceof Map ? undefined : route.asset;
+      if(asset) test.expectHeaders={'content-type':asset.type,etag:asset.etag,'content-length':String(asset.body.length)};
+      if (route.reply && method !== 'HEAD') test.expectBody = Buffer.from(route.reply.body).toString('utf8');
+      if (method === 'HEAD') test.expectBody = '';
+      cases.push(test);
+    }
+  }
+  return {inventory,cases,resolve:path => matchRoute(compiled,parseTarget(path))?.route.pattern};
+}
+export async function readCases(root        , optional = false)                         {
+  if(optional) {
+    try {await lstat(join(root,'tests/requests.json'));}
+    catch(error){if(error instanceof Error && 'code' in error && error.code==='ENOENT')return [];throw error;}
+  }
+  const file=await safeFile(root,'tests/requests.json');
+  const bytes = await readFile(file);
+  assert(bytes.length <= 16*1024*1024, 'Request fixture file exceeds 16 MiB');
+  const cases          = JSON.parse(bytes.toString('utf8'));
+  assert(Array.isArray(cases) && cases.length <= 10000 && (optional || cases.length), 'Request tests must be an array (maximum 10000)');
+  for (const test of cases             ) {
+    assert(isRecord(test), 'Invalid request test');
+    assert(typeof test.path === 'string' && test.path.startsWith('/') && !test.path.startsWith('//') && !/[\r\n]/.test(test.path), 'Test path must be local');
+    assert(Number.isInteger(test.status) && typeof test.status === 'number' && test.status >= 200 && test.status <= 599, 'Test must declare an HTTP status');
+    assert(!test.method || (typeof test.method === 'string' && ['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'].includes(test.method)), 'Invalid test method');
+    assert(test.body === undefined || typeof test.body === 'string', 'Test body must be text');
+    assert(test.expectBody === undefined || typeof test.expectBody === 'string', 'Expected body must be text');
+    for (const headers of [test.headers,test.expectHeaders]) assert(headers === undefined || (isRecord(headers) && Object.values(headers).every(v => typeof v === 'string')), 'Test headers must be string mappings');
+  }
+  return cases                 ; // trust boundary: fixture JSON, validated field by field above
+}
+export function benchmarkTarget(value        )                  {
+  let url     ;
+  try { url=new URL(value); } catch { assert(false,'Target must be an absolute HTTP(S) origin'); }
+  assert(['http:','https:'].includes(url.protocol) && url.origin===value.replace(/\/$/,'') && !url.username && !url.password,
+    'Target must be a bare HTTP(S) origin without path or credentials');
+  return {protocol:url.protocol,hostname:url.hostname,port:url.port || (url.protocol==='https:'?443:80)};
+}
+export function hit(app              ,test             ,agent       ,target                  )                     {
+  return new Promise(resolve => {
+    const began=performance.now();
+    const fail=()=>resolve({pass:false,status:0,durationMs:performance.now()-began,error:'transport'});
+    let req                         ;
+    try {
+      const send=target?.protocol==='https:' ? secureRequest : request;
+      const options                =target
+        ? {host:target.hostname,port:target.port,path:test.path,method:test.method || 'GET',headers:{host:target.hostname,'user-agent':probeAgent,...(test.headers || {})},agent,timeout:10000}
+        : {host:'127.0.0.1',port:app.address.port,path:test.path,method:test.method || 'GET',headers:{'user-agent':probeAgent,...(test.headers || {})},agent,timeout:10000};
+      req=send(options,(res                 )=>{
+        let size=0;const chunks          =[];
+        res.on('data',(chunk        )=>{size+=chunk.length;if(size>16*1024*1024)res.destroy(new Error('Response limit'));else if(test.expectBody!==undefined)chunks.push(chunk);});
+        res.on('error',fail);
+        res.on('end',()=>resolve({status:res.statusCode ?? 0,durationMs:performance.now()-began,
+          pass:res.statusCode===test.status && Object.entries(test.expectHeaders || {}).every(([k,v])=>res.headers[k.toLowerCase()]===v) && (test.expectBody===undefined || Buffer.concat(chunks).toString()===test.expectBody)}));
+      });
+      req.on('error',fail);req.on('timeout',()=>req?.destroy(new Error('Timeout')));req.end(test.body);
+    } catch { req?.destroy();fail(); }
+  });
+}
+// `compliance` is the option object for runCompliance (profile, rules, ignore,
+// origin, host); absent, the report carries `compliance: null` and readiness
+// is unchanged. A compliance verdict is reported beside readiness, never
+// folded into it: the exit code decision belongs to the caller.
+export async function auditProject(app              , {expectRoutes,log=()=>{},compliance}               = {})                       {
+  const began=performance.now();
+  const plan=app.testPlan(), fixtures=await readCases(app.root,true);
+  const metadata=new Map(plan.inventory.map(r=>[r.path,r]));
+  const cases=[...plan.cases,...fixtures], covered=new Set        (), unassertedCases          =[];let passed=0,failed=0;
+  const agent=new Agent({keepAlive:true,maxSockets:1});
+  try {
+    for (const [i,test] of cases.entries()) {
+      const result=await hit(app,test,agent);const method=test.method || 'GET';
+      let route                  ;try {route=plan.resolve(test.path);} catch { /* Invalid-path negative fixture. */ }
+      const meta=route===undefined?undefined:metadata.get(route);
+      // Error-only fixtures cannot prove a function's normal path works.
+      const assertsResponse=test.expectBody!==undefined || Object.keys(test.expectHeaders || {}).length>0;
+      if(result.pass && meta?.state==='active' && result.status<400 && !assertsResponse)unassertedCases.push(i+1);
+      if(result.pass && assertsResponse && meta?.state==='active' && (result.status<400 || (meta.handler==='respond' && i<plan.cases.length)))covered.add(JSON.stringify([route,method]));
+      if(result.pass)passed++;else failed++;
+      log({event:'check',case:i+1,source:i<plan.cases.length?'generated':'fixture',pass:result.pass,status:result.status,expectedStatus:test.status});
+    }
+  } finally {agent.destroy();}
+  const uncovered=plan.inventory.filter(r=>r.state==='active').flatMap(r=>r.methods.filter(m=>!covered.has(JSON.stringify([r.path,m]))).map(method=>({route:r.path,method})));
+  const counts                       ={configured:plan.inventory.length,active:0,disabled:0,expired:0,byHandler:{}};
+  for(const route of plan.inventory){counts[route.state]++;const handler=String(route.handler);counts.byHandler[handler]=(counts.byHandler[handler]||0)+1;}
+  const countMatches=expectRoutes===undefined || counts.configured===expectRoutes;
+  // The per-route capability table: which policies apply and whether this
+  // host enforces, compiles or delegates each one. Refusals never get here.
+  return {dynamicLinks:plan.dynamicLinks,elapsedMs:performance.now()-began,ready:countMatches && !failed && !uncovered.length && counts.active>0,counts,expectedRoutes:expectRoutes ?? null,countMatches,checks:cases.length,passed,failed,coveredRouteMethods:covered.size,unassertedCases,uncovered,policies:plan.policies ?? {},compliance:compliance?await runCompliance(app,compliance):null};
+}
+export async function benchmarkProject(app              ,{requests=1000,concurrency=2,maxP95Ms,seconds=30,warmup=0,target}                  ={})                           {
+  assert(Number.isInteger(requests)&&requests>=1&&requests<=100000,'Requests must be 1–100000');
+  assert(Number.isInteger(concurrency)&&concurrency>=1&&concurrency<=32,'Concurrency must be 1–32');
+  assert(Number.isInteger(seconds)&&seconds>=1&&seconds<=300,'Seconds must be 1–300');
+  assert(Number.isInteger(warmup)&&warmup>=0&&warmup<=10000,'Warmup must be 0–10000 requests');
+  assert(maxP95Ms===undefined || (Number.isFinite(maxP95Ms)&&maxP95Ms>0),'Latency budget must be positive');
+  const destination=target?benchmarkTarget(target):undefined;
+  const plan=app.testPlan();const fixtures=await readCases(app.root,true);
+  const cases=[...plan.cases,...fixtures].filter(c=>['GET','HEAD'].includes(c.method||'GET')&&c.status<400);
+  assert(cases.length>0,'No GET/HEAD workload: add representative successful request fixtures');
+  const workload=(index        )             =>{const found=cases[index%cases.length];assert(found,'Empty workload');return found;};
+  // A deployment behind TLS or a proxy is a different system from a local
+  // snapshot; the workload is the same, the measurement is not interchangeable.
+  const agent=destination?.protocol==='https:'
+    ? new SecureAgent({keepAlive:true,maxSockets:concurrency})
+    : new Agent({keepAlive:true,maxSockets:concurrency});
+  const times          =[],statuses                       ={};
+  let next=0,failed=0,transportErrors=0,elapsedMs        ;
+  try {
+    // Warm-up requests are sent and discarded: a cold snapshot, an empty
+    // connection pool and a just-started worker are not what a budget is about.
+    let warmed=0;
+    await Promise.all(Array.from({length:Math.min(concurrency,Math.max(warmup,1))},async()=>{
+      while(warmed<warmup){const index=warmed++;await hit(app,workload(index),agent,destination);}
+    }));
+    const began=performance.now();
+    await Promise.all(Array.from({length:concurrency},async()=>{
+      while(next<requests && performance.now()-began<seconds*1000){
+        const index=next++;const result=await hit(app,workload(index),agent,destination);
+        times.push(result.durationMs);
+        if(!result.pass){failed++;if(result.status===0)transportErrors++;}
+        statuses[result.status]=(statuses[result.status]||0)+1;
+      }
+    }));
+    elapsedMs=performance.now()-began;
+  } finally {agent.destroy();}
+  times.sort((a,b)=>a-b);
+  const percentile=(q        )=>times[Math.max(0,Math.ceil(times.length*q)-1)] ?? null;
+  const p95Ms=percentile(.95), complete=times.length===requests;
+  const shed=Object.entries(statuses).filter(([status])=>['503','504'].includes(status)).reduce((n,[,count])=>n+count,0);
+  return {pass:complete&&!failed&&(maxP95Ms===undefined||(p95Ms!==null&&p95Ms<=maxP95Ms)),requested:requests,completed:times.length,complete,failed,transportErrors,shedResponses:shed,concurrency,
+    workloadCases:cases.length,exercisedWorkloadCases:Math.min(times.length,cases.length),
+    workload:`${destination?'remote':'local'} GET/HEAD only; redirects not followed`,
+    target:destination?`${destination.protocol}//${destination.hostname}:${destination.port}`:null,
+    warmupRequests:warmup,elapsedMs,requestsPerSecond:times.length/elapsedMs*1000,
+    p50Ms:percentile(.5),p95Ms,p99Ms:percentile(.99),maxP95Ms:maxP95Ms??null,statuses,
+    // In target mode this process is the load generator, not the server: its
+    // memory says nothing about the deployment under test.
+    rssMiB:destination?null:process.memoryUsage().rss/2**20,node:process.version,platform:process.platform};
+}