@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/observability.js

@@ -12,16 +12,13 @@ import { assert } from './errors.js';
 // URL, query string, header, body, client address, User-Agent string, binding
 // or secret; `route` is always the configured pattern.
 export const events = Object.freeze({
+  signal: Object.freeze(['event','outcome','count']),
   request: Object.freeze(['event', 'requestId', 'status', 'durationMs', 'method', 'route']),
   reload: Object.freeze(['event', 'status', 'version', 'routes']),
   watch: Object.freeze(['event', 'status']),
   function_worker: Object.freeze(['event', 'status', 'slot', 'attempt', 'delayMs']),
-  link_store_worker: Object.freeze(['event', 'status', 'readOnly', 'attempt', 'delayMs']),
-  link_request: Object.freeze(['event', 'requestId', 'collection', 'route', 'code', 'method', 'status', 'outcome', 'durationMs']),
-  link_observer: Object.freeze(['event', 'status', 'reason', 'dropped', 'queued', 'delivered', 'failed', 'timedOut', 'closed']),
   logs_dropped: Object.freeze(['event', 'count']),
   observer: Object.freeze(['event', 'status', 'name']),
-  management_request: Object.freeze(['event', 'timestamp', 'requestId', 'collection', 'action', 'authenticated', 'principal', 'status', 'outcome', 'durationMs']),
   throttle: Object.freeze(['event', 'route', 'outcome', 'remaining']),
   agents: Object.freeze(['event', 'route', 'list', 'outcome']),
   cache: Object.freeze(['event', 'route', 'outcome']),
@@ -46,9 +43,8 @@ export const events = Object.freeze({
                                                                        
                                                                                                                    
                                                                                               
-                                                          
                                                                       
-                                                                            
+                    
                                                      
                            
  
@@ -83,14 +79,13 @@ export function validateObservers(observers          = [])             {
   return observers              ; // every entry was just checked
 }
 
-export const SNAPSHOT_VERSION = 1;
+export const SNAPSHOT_VERSION = 2;
 const statusClasses = ['2xx', '3xx', '4xx', '5xx'];
 const MAX_ROUTES = 10000;
 const outcomes = {
   throttle: ['allowed', 'exceeded'],
   agents: ['denied', 'reported'],
   cache: ['hit', 'stale', 'miss', 'store'],
-  link_request: ['completed', 'aborted', 'missing', 'disabled', 'expired', 'invalid_code', 'invalid_record', 'unavailable'],
 };
 const zeroed = (keys          )           => Object.fromEntries(keys.map(key => [key, 0]));
 
@@ -106,10 +101,8 @@ export function createMetrics()          {
   const reloads = { ok: 0, rejected: 0 };
   const watch = { failed: 0 };
   const functionWorkers = { started: 0, restarts: 0 };
-  const linkStoreWorkers = { started: 0, restarts: 0 };
   const policies = { throttle: zeroed(outcomes.throttle), agents: zeroed(outcomes.agents), cache: zeroed(outcomes.cache) };
-  const linkRequests = zeroed(outcomes.link_request);
-  const linkObserver = { failed: 0, dropped: 0 };
+  const signals = zeroed(['accepted','delivered','failed','dropped']);
   let logsDropped = 0, observerErrors = 0;
   const count = (table          , key         )       => { if (typeof key === 'string' && Object.hasOwn(table, key)) table[key] ++; };
   function countRequest(target                 , status         , route         )       {
@@ -129,14 +122,12 @@ export function createMetrics()          {
       if (!event || typeof event !== 'object') return;
       const record = event                 ; // any object is read as a record; unknown keys are ignored
       switch (record.event) {
+        case 'signal': if(typeof record.outcome==='string'&&Object.hasOwn(signals,record.outcome)&&Number.isSafeInteger(record.count)&&Number(record.count)>0)signals[record.outcome] +=Number(record.count);break;
         case 'request': countRequest(context.probe ? health : requests, record.status, context.probe ? null : (record.route ?? context.route)); break;
         case 'reload': count(reloads, record.status); break;
         case 'watch': if (record.status === 'failed') watch.failed++; break;
         case 'function_worker': if (record.status === 'restarting') functionWorkers.restarts++; else if (record.status === 'started') functionWorkers.started++; break;
-        case 'link_store_worker': if (record.status === 'restarting') linkStoreWorkers.restarts++; else if (record.status === 'started') linkStoreWorkers.started++; break;
         case 'throttle': case 'agents': case 'cache': count(policies[record.event], record.outcome); break;
-        case 'link_request': count(linkRequests, record.outcome); break;
-        case 'link_observer': if (record.status === 'failed') linkObserver.failed++; else if (record.status === 'dropped' || record.status === 'closed') linkObserver.dropped = Math.max(linkObserver.dropped, Number(record.dropped) || 0); break;
         case 'logs_dropped': logsDropped += Number(record.count) || 0; break;
         case 'observer': if (record.status === 'failed') observerErrors++; break;
         default: break;
@@ -156,10 +147,8 @@ export function createMetrics()          {
         reloads: { ...reloads },
         watch: { ...watch },
         functionWorkers: { ...functionWorkers, healthySlots: 0, slots: 0 },
-        linkStoreWorkers: { ...linkStoreWorkers },
         policies: { throttle: { ...policies.throttle }, agents: { ...policies.agents }, cache: { ...policies.cache } },
-        linkRequests: { ...linkRequests },
-        linkObserver: { ...linkObserver },
+        signals: {...signals},
         logsDropped,
         observers: { errors: observerErrors },
         ...extra,
@@ -226,13 +215,10 @@ export function renderPrometheus(snapshot                          )         {
   metric('function_worker_restarts_total', 'counter', 'Function worker replacements scheduled.', [[{}, snapshot.functionWorkers?.restarts]]);
   metric('function_worker_healthy_slots', 'gauge', 'Function worker slots ready to serve.', [[{}, snapshot.functionWorkers?.healthySlots]]);
   metric('function_worker_slots', 'gauge', 'Function worker slots configured.', [[{}, snapshot.functionWorkers?.slots]]);
-  metric('link_store_worker_restarts_total', 'counter', 'Link-store worker replacements scheduled.', [[{}, snapshot.linkStoreWorkers?.restarts]]);
   metric('throttle_total', 'counter', 'Throttle policy decisions.', byKey(snapshot.policies?.throttle, 'outcome'));
   metric('agents_total', 'counter', 'Agents policy decisions.', byKey(snapshot.policies?.agents, 'outcome'));
   metric('cache_total', 'counter', 'Cache policy outcomes.', byKey(snapshot.policies?.cache, 'outcome'));
-  metric('link_requests_total', 'counter', 'Dynamic link requests by outcome.', byKey(snapshot.linkRequests, 'outcome'));
-  metric('link_observer_failures_total', 'counter', 'Link event collector failures.', [[{}, snapshot.linkObserver?.failed]]);
-  metric('link_observer_dropped_total', 'counter', 'Link events dropped under overload.', [[{}, snapshot.linkObserver?.dropped]]);
+  metric('signals_total','counter','Best-effort webhook outcomes.',Object.entries(snapshot.signals||{}).map(([outcome,value])=>[{outcome},value]));
   metric('logs_dropped_total', 'counter', 'Log records the JSON logger shed.', [[{}, snapshot.logsDropped]]);
   metric('observer_errors_total', 'counter', 'Observer hooks that threw or rejected.', [[{}, snapshot.observers?.errors]]);
   metric('uptime_seconds', 'gauge', 'Seconds since the process started serving.', [[{}, snapshot.uptimeSeconds]]);

package/dist/operator-host.js

@@ -0,0 +1,29 @@
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute, relative, sep, extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assert } from './errors.js';
+                                                   
+
+/** Explicitly loaded operator code. Never discovered in application directories. */
+                               
+                                            
+                                      
+                                 
+ 
+export async function loadOperatorHost(file                    , project        )                        {
+  if (file === undefined) return {};
+  assert(isAbsolute(file) && ['.mjs', '.js'].includes(extname(file)), 'Host file must be an absolute ES module path (.mjs or .js)');
+  const root = await realpath(project), path = await realpath(file), rel = relative(root, path);
+  assert(isAbsolute(rel) || rel === '..' || rel.startsWith('..' + sep), 'Host file must be outside the application project');
+  const info = await stat(path);
+  assert(info.isFile() && info.size <= 1048576, 'Host file must be a regular file of at most 1 MiB');
+  const module = await import(pathToFileURL(path).href)                           ;
+  const host          = module.default;
+  assert(host !== null && typeof host === 'object' && !Array.isArray(host), 'Host file must default-export an operator configuration object');
+  assert(Object.keys(host).every(key => ['extensions', 'plugins', 'close'].includes(key)), 'Unknown operator host setting');
+  const result = host                ;
+  assert(result.extensions === undefined || Array.isArray(result.extensions), 'Host extensions must be an array');
+  assert(result.plugins === undefined || Array.isArray(result.plugins), 'Host plugins must be an array');
+  assert(result.close === undefined || typeof result.close === 'function', 'Host close must be a function');
+  return result;
+}

package/dist/plugins.js

@@ -1,3 +1,4 @@
+import { validateHeaderName } from './header-validation.js';
 import { assert, ConfigError } from './errors.js';
 import { targets as knownTargets } from './policies.js';
                                                         
@@ -21,6 +22,8 @@ import { targets as knownTargets } from './policies.js';
                                                                                                       
                          
                                                        
+                                                                                         
+                               
                                                             
                                                                                                                    
                                                                                                                                            
@@ -41,6 +44,15 @@ export function validatePlugins(plugins          = [], target         = 'node')
     assert(typeof plugin.version === 'string' && plugin.version.length <= 64, `Plugin "${plugin.name}" needs a version string`);
     assert(Array.isArray(plugin.targets) && plugin.targets.every(t => (knownTargets                     ).includes(t)), `Plugin "${plugin.name}" must list its supported targets`);
     if (!(plugin.targets            ).includes(target)) throw new ConfigError(`Plugin "${plugin.name}" does not support the ${target} target`);
+    if(plugin.credentialHeaders!==undefined){
+      assert(Array.isArray(plugin.credentialHeaders)&&plugin.credentialHeaders.length<=64,'Plugin credentialHeaders must contain at most 64 header names');
+      const headers=new Set        ();
+      for(const name of plugin.credentialHeaders){
+        assert(typeof name==='string'&&name.length<=128,'Invalid plugin credential header name');
+        validateHeaderName(name);
+        assert(!headers.has(name.toLowerCase()),'Duplicate plugin credential header name');headers.add(name.toLowerCase());
+      }
+    }
     for (const hook of hookNames) assert(plugin[hook] === undefined || typeof plugin[hook] === 'function', `Plugin "${plugin.name}" hook ${hook} must be a function`);
     assert(hookNames.some(hook => plugin[hook]), `Plugin "${plugin.name}" declares no hooks`);
   }

package/dist/policies/agents.js

@@ -35,8 +35,8 @@ export function targets()                                        { return { node
                              
 
 export const bundledLists = Object.freeze(Object.keys(bundled));
-export const MAX_PATTERN_BYTES = 256;
-export const MAX_REPEAT = 64;
+const MAX_PATTERN_BYTES = 256;
+const MAX_REPEAT = 64;
 
 // The pattern subset: anchors, literals, `.`, escapes, character classes,
 // groups, alternation, and quantifiers on a single atom only. Nothing here

package/dist/policies/cache.js

@@ -202,9 +202,14 @@ function revalidate(state            , req               , result
   if (result.status !== 200 || (req.method !== 'GET' && req.method !== 'HEAD')) return result;
   let headers = result.headers, etag = header(headers, 'etag');
   if (!etag) {
-    // A strong validator over the representation. A HEAD answer without a
-    // body (a function's) has nothing to hash and gets no validator, rather
-    // than one that would disagree with GET.
+    // A strong validator over the representation. A trusted function's HEAD
+    // answer is now measured the same way its GET answer is (the body is
+    // read to determine its real length even though HEAD never puts it on
+    // the wire — see #139), so it has real bytes to hash here and gets a
+    // validator that agrees with GET's. Only a HEAD answer that genuinely
+    // has no body to measure (e.g. one carrying a native reply with no
+    // body) skips computing one, rather than hashing zero bytes and
+    // asserting a validator for a representation it never measured.
     const body = bodyOf(result);
     if (req.method === 'HEAD' && !body.length) return result;
     etag = '"' + createHash('sha256').update(body).digest('hex') + '"'; headers = [...headers, ['etag', etag]];

package/dist/policies/compression.js

@@ -26,7 +26,8 @@ export const phases                    = ['response'];
 
 const DYNAMIC_LIMIT = 1048576;              // bytes; above this a body is never compressed on the request path
 const PRECOMPRESSED_BUDGET = 64 * 1024 * 1024; // aggregate bytes of asset variants per runtime
-const DEFAULT_TYPES = ['text/*','application/json','application/javascript','application/xml','image/svg+xml','application/manifest+json','application/ld+json'];
+/** The media types compressed when `types` is not declared; exported so the deployment verifier reads the same table. */
+export const DEFAULT_TYPES = ['text/*','application/json','application/javascript','application/xml','image/svg+xml','application/manifest+json','application/ld+json'];
 const SUFFIX                         = { br:'-br', gzip:'-gz', deflate:'-df', zstd:'-zs' };
 const BODYLESS = new Set([204,205,304]);
 

package/dist/policies.js

@@ -72,7 +72,7 @@ export function effectivePolicies(document                 , routeConfig
   layers.push(route);
   const effective                         = {};
   for (const layer of layers) for (const [key, value] of Object.entries(layer)) {
-    if (key === 'profile') continue;
+    if (key === 'profile' || key === 'extensions') continue;
     if (value === false) { delete effective[key]; continue; }
     effective[key] = { ...(effective[key] || {}), ...value };
   }

package/dist/policy.js

@@ -1,28 +1,52 @@
+import { egressUrl } from './egress.js';
 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 { collectFunctionSources, collectTrustedSources, 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));
+  // Only `sandbox: true` routes are bundled into the QuickJS module snapshot
+  // FunctionPool loads (docs/SPIKE-DEFAULT-TRUST-MODEL.md): a trusted route's
+  // module never needs to satisfy the sandbox's relative-static-import-only
+  // rule or its per-module/total byte budgets, since it runs through Node's
+  // own module resolution, not the WASM guest.
+  const sandboxed                                                      = [];
+  const trusted                  = [];
+  const resolveOne = async (definition                                     )                              =>
+    ({source:await functionFile(loaded.root,definition.source),export:definition.export || 'default'});
+  for (const [pattern,route] of Object.entries(loaded.routes)) {
+    if (!routeFunctions(route).length) continue;
+    const middleware = await Promise.all((route.middleware || []).map(resolveOne));
+    const fn = route.function ? await resolveOne(route.function) : undefined;
+    if (route.sandbox) { for (const definition of [...middleware, ...(fn ? [fn] : [])]) sandboxed.push({pattern,function:definition}); }
+    else trusted.push({middleware, function: fn});
+  }
+  const collected = await collectFunctionSources(sandboxed,loaded.root);
+  const trustedSources = await collectTrustedSources(trusted,loaded.root);
+  // The hash operator grants pin to still covers trusted routes' own source, so
+  // an env/secret grant is invalidated when the trusted code that could use it
+  // changes, even though that code never enters collectFunctionSources's
+  // sandbox-shaped snapshot (see collectTrustedSources for what this does not
+  // catch: changes to a helper module a trusted entry imports but does not
+  // itself change).
+  const sources = Object.fromEntries(Object.entries({...collected.sources,...trustedSources}).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.
+  // stay out of the hash that operator grants are pinned to. Declared site and
+  // inherited policy/profile behavior are included: changing a pre-egress
+  // restriction must require a fresh operator review even if routes are unchanged.
   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') };
+  const snapshot                   = { ...collected, projectSha256: createHash('sha256').update(JSON.stringify({...(loaded.document.extensions?{extensions:loaded.document.extensions}:{}),routes:declared,...(loaded.document.policies?{policies:loaded.document.policies}:{}),...(loaded.document.profiles?{profiles:loaded.document.profiles}:{}),...(loaded.document.site?{site:loaded.document.site}:{}),sources})).digest('hex') };
   return snapshot;
 }
 export function validatePolicy(value         )                 {
@@ -33,8 +57,13 @@ export function validatePolicy(value         )                 {
   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');
+    assert(Object.keys(grant).every(k=>['env','secrets','egress'].includes(k)), 'Unsupported policy capability');
+    const record=grant              ;
+    if(record.egress!==undefined) {
+      assert(record.egress&&typeof record.egress==='object'&&!Array.isArray(record.egress)&&Object.keys(record.egress).every(key=>['proxy','signals'].includes(key)),'Invalid egress grant');
+      for(const origins of Object.values(record.egress)){assert(Array.isArray(origins)&&origins.length<=64,'Invalid egress origins');for(const origin of origins){const url=egressUrl(origin);assert(url.origin===origin,'Egress grants must be exact HTTPS origins');}}
+    }
+    for (const list of [record.env,record.secrets].filter(value=>value!==undefined)) 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
 }
@@ -47,9 +76,21 @@ export async function loadOperatorPolicy(file                    , project
   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])                                                   => {
+  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)]}]] : [];
+    const egress             ={...(route.proxy?{proxy:[egressUrl(route.proxy.url).origin]}:{}),...(route.signals?.length?{signals:[...new Set(route.signals.map(signal=>egressUrl(signal.url).origin))]}:{})};
+    return env.length || secrets.length || Object.keys(egress).length ? [[path,{env:[...new Set(env)],secrets:[...new Set(secrets)],...(Object.keys(egress).length?{egress}:{})}]] : [];
   }))};
 }
+
+/** Called before resources or credentials are activated. Grants never come from YAML. */
+export function authorizeEgress(loaded               ,projectSha256       ,policy                         )                                   {
+ const proxy=new Set        (),signals=new Set        ();
+ for(const [path,route] of Object.entries(loaded.routes))for(const [purpose,urls]of [['proxy',route.proxy?[route.proxy.url]:[]],['signals',route.signals?.map(signal=>signal.url)||[]]]         )for(const destination of urls){
+  const origin=egressUrl(destination).origin;
+  assert(policy?.projectSha256===projectSha256&&policy.routes[path]?.egress?.[purpose]?.includes(origin),'Egress denied by revision-pinned operator policy');
+  (purpose==='proxy'?proxy:signals).add(origin);
+ }
+ assert(proxy.size<=64&&signals.size<=64,'Runtime egress origins exceed limit');return {proxy:[...proxy],signals:[...signals]};
+}

package/dist/prerender.js

@@ -1,6 +1,9 @@
 import {mkdir, writeFile} from 'node:fs/promises';
 import {resolve, relative, isAbsolute, join, dirname, sep} from 'node:path';
 import {createRuntime} from './runtime.js';
+import {loadDocument, functionFile} from './config.js';
+import {applySite} from './site.js';
+import {collectFunctionSources, routeFunctions, MODULE_LIMIT, TOTAL_BYTE_LIMIT} from './function-sources.js';
 import {ConfigError, assert} from './errors.js';
                                                                 
                                       
@@ -80,6 +83,55 @@ export async function assertNativeProject(project        , {allow = ['page', 'st
   } finally { await runtime.close(); }
 }
 
+// Which routes can share one function snapshot. A guest snapshot is bounded in
+// module count and source bytes (docs/FUNCTION-SECURITY.md), and those bounds
+// are not relaxed for build-time content: a site whose pages each compile to
+// their own module therefore cannot be rendered in a single pass past 127
+// modules, whatever their size. Rather than making that the caller's problem,
+// the helper measures each route's module closure up front — reading sources
+// only, never building a snapshot — and packs routes greedily into passes that
+// stay inside the budgets. Shared modules (a template middleware) are counted
+// once per pass, so they are paid for in every pass that needs them.
+async function planPasses(source        )                      {
+  const loaded = await loadDocument(source);
+  // Site conventions become routes before compilation, so they must be named
+  // here too: `only` is matched against the expanded route set.
+  await applySite(loaded, {log: () => {}});
+  const patterns = Object.keys(loaded.routes);
+  assert(patterns.length, 'Source project declares no routes');
+  const cost = new Map                            ();
+  for (const pattern of patterns) {
+    const route = loaded.routes[pattern] ;
+    const definitions = [];
+    for (const definition of routeFunctions(route))
+      definitions.push({function: {source: await functionFile(loaded.root, definition.source), export: definition.export || 'default'}});
+    // One route at a time: the same collector the snapshot uses, so a route
+    // whose own closure cannot fit fails here with the collector's message.
+    const collected = await collectFunctionSources(definitions, loaded.root);
+    cost.set(pattern, Object.entries(collected.sources).map(([name, code]) => [name, Buffer.byteLength(code)]));
+  }
+  const passes             = [];
+  let current           = [], modules = new Map                (), bytes = 0;
+  for (const pattern of patterns) {
+    const own = cost.get(pattern) ;
+    const fits = () => {
+      const added = own.filter(([name]) => !modules.has(name));
+      // `collect` admits a module only while the count is below the limit, so a
+      // pass holds at most MODULE_LIMIT - 1 modules.
+      return modules.size + added.length <= MODULE_LIMIT - 1 && bytes + added.reduce((total, [, size]) => total + size, 0) <= TOTAL_BYTE_LIMIT;
+    };
+    if (current.length && !fits()) {
+      passes.push(current);
+      current = []; modules = new Map(); bytes = 0;
+    }
+    assert(fits(), `Route ${pattern} needs ${own.length} modules and ${own.reduce((total, [, size]) => total + size, 0)} bytes of source, more than one snapshot can hold`);
+    for (const [name, size] of own) if (!modules.has(name)) { modules.set(name, size); bytes += size; }
+    current.push(pattern);
+  }
+  if (current.length) passes.push(current);
+  return passes;
+}
+
 export async function prerenderPages(project        , output        , {
   origin = 'http://localhost', fileName = pageFileName, ignoreUnrenderable = false,
   maxPages = 500, maxPageBytes = 512 * 1024, maxTotalBytes = 32 * 1024 * 1024, log = () => {},
@@ -97,49 +149,56 @@ export async function prerenderPages(project        , output        , {
   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});
+  let bytes = 0, targetCount = 0;
+  const renderable = (route                ) => route.handler === 'function' && route.state === 'active' && route.methods.includes('GET');
+  // Case-insensitive, and shared across passes: 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                ();
+  const passes = await planPasses(source);
+  if (passes.length > 1) log({event: 'prerender-passes', passes: passes.length});
+  for (const only of passes) {
+    // One runtime per pass, each holding only its own pass's function snapshot.
+    const runtime = await createRuntime(source, {log: () => {}, only});
+    try {
+      const inventory = runtime.testPlan().inventory;
+      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`);
+      }
+      targetCount += targets.length;
+      assert(targetCount <= maxPages, `Source project page count ${targetCount} exceeds maxPages ${maxPages}`);
+      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();
     }
-  } 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();
   }
+  assert(targetCount, 'Source project has no active GET function routes to prerender');
 
   // 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.

package/dist/project-tests.js

@@ -5,12 +5,12 @@ import { startServer } from './server.js';
 import { readCases, hit } from './readiness.js';
                                         
 
-                                                                                                                                                                                
+                                                                                                                                                                                                                      
                                                                     
 
-export async function runProjectTests(project        , { log = () => {}, permissions, linkStore, origin }                     = {})                             {
+export async function runProjectTests(project        , { log = () => {}, permissions, origin, extensions, plugins }                     = {})                             {
   const root = await realpath(project), cases = await readCases(root);
-  const app = await startServer({ project, port: 0, local: true, log, permissions, linkStore, origin });
+  const app = await startServer({ project, port: 0, local: true, log, permissions, origin, extensions, plugins });
   const agent = new Agent({keepAlive:true,maxSockets:1}); let failed = 0;
   try {
     for (const [i,test] of cases.entries()) {

package/dist/provider-verification.js

@@ -0,0 +1,92 @@
+import { request } from 'node:https';
+import { createHash } from 'node:crypto';
+
+                                                                                 
+                                                                                                                                                                                           
+                                                                                             
+                                                                                                   
+                                                                                                      
+                                                                                                                                    
+                                             
+                                                                                   
+                                                                                           
+                                                                                     
+                                                                            
+ 
+const MAX_BYTES=64*1024;
+const prefix='/urlcode-conformance';
+/** Synthetic read-only routes, except a POST to a declared constant response. */
+export function providerConformanceCases()                 {
+  return [
+    {id:'redirect-query-drop',path:`${prefix}/redirect?ignored=secret`,method:'GET',headers:{},expected:{status:302,headers:{location:'https://example.test/destination'},body:''}},
+    {id:'redirect-head',path:`${prefix}/redirect`,method:'HEAD',headers:{},expected:{status:302,headers:{location:'https://example.test/destination'},body:''}},
+    {id:'path-component',path:`${prefix}/people/A%20B`,method:'GET',headers:{},expected:{status:307,headers:{location:'https://example.test/people/A%20B'},body:''}},
+    {id:'query-validation',path:`${prefix}/query?n=7&ignored=yes`,method:'GET',headers:{},expected:{status:302,headers:{location:'https://example.test/query?n=7'},body:''}},
+    {id:'query-invalid',path:`${prefix}/query?n=not-a-number`,method:'GET',headers:{},expected:{status:400}},
+    {id:'query-duplicate',path:`${prefix}/query?n=1&n=2`,method:'GET',headers:{},expected:{status:400}},
+    {id:'constant-response',path:`${prefix}/hello`,method:'GET',headers:{},expected:{status:200,headers:{'content-type':'text/plain; charset=utf-8','x-conformance':'v1'},body:'provider conformance v1'}},
+    {id:'response-head',path:`${prefix}/hello`,method:'HEAD',headers:{},expected:{status:200,body:''}},
+    {id:'method-refusal',path:`${prefix}/hello`,method:'POST',headers:{},body:'',expected:{status:405,headers:{allow:'GET, HEAD'}}},
+    {id:'body-accepted',path:`${prefix}/body`,method:'POST',headers:{'content-type':'text/plain'},body:'small',expected:{status:200,body:'accepted'}},
+    {id:'body-limit',path:`${prefix}/body`,method:'POST',headers:{'content-type':'text/plain'},body:'x'.repeat(33),expected:{status:413}},
+    {id:'missing-route',path:`${prefix}/missing`,method:'GET',headers:{},expected:{status:404}},
+  ];
+}
+function optionsChecked(target                   ,options                            )        {
+  if(!['self-hosted','aws','vercel','cloudflare'].includes(target))throw new Error('Unknown verification target');
+  const timeout=options.timeoutMs??3000;
+  if(!Number.isInteger(timeout)||timeout<50||timeout>10000)throw new Error('Timeout must be 50–10000 ms');
+  for(const value of [options.release,options.gitCommit])if(value!==undefined&&(typeof value!=='string'||value.length>256||/[\u0000-\u001f\u007f]/u.test(value)))throw new Error('Release identity must be at most 256 printable characters');
+  return timeout;
+}
+async function run(target                   ,transport                  ,options                            ,origin            )                                     {
+  const timeout=optionsChecked(target,options),cases=providerConformanceCases(),findings                  =[];
+  const deadline=performance.now()+60000;let requests=0;
+  for(const probe of cases){
+    const failures         =[];let status            =null;
+    const controller=new AbortController();let timer                                        ;
+    try{
+      const remaining=deadline-performance.now();if(remaining<=0)throw new Error('suite deadline');
+      requests++;
+      const answer=await Promise.race([transport(probe,controller.signal),new Promise       ((_,reject)=>{timer=setTimeout(()=>{reject(new Error('request deadline'));controller.abort();},Math.min(timeout,remaining));})]);
+      status=answer.status;
+      if(Buffer.byteLength(answer.body)>MAX_BYTES)throw new Error('response limit');
+      if(answer.status!==probe.expected.status)failures.push('status differs');
+      const headers=Object.fromEntries(Object.entries(answer.headers).map(([name,value])=>[name.toLowerCase(),value]));
+      for(const [name,value]of Object.entries(probe.expected.headers??{}))if(headers[name]!==value)failures.push(`header ${name} differs`);
+      if(probe.expected.body!==undefined&&answer.body!==probe.expected.body)failures.push('body differs');
+    }catch{failures.push('transport, deadline or response-limit failure');}
+    finally{clearTimeout(timer);controller.abort();}
+    findings.push({case:probe.id,pass:failures.length===0,expectedStatus:probe.expected.status,observedStatus:status,failures});
+  }
+  return {schemaVersion:1,fixtureVersion:1,target,origin,evidence:origin===null?'local-adapter':'deployment-http',providerVerification:origin===null?'unverified':'observed',timestamp:new Date().toISOString(),release:options.release??null,gitCommit:options.gitCommit??null,fixtureSha256:createHash('sha256').update(JSON.stringify(cases)).digest('hex'),pass:findings.every(f=>f.pass),requests,findings,notes:[
+    origin===null?'Local adapter replay is not evidence of a deployed provider.':'HTTP observations apply only to the supplied origin and timestamp; provider identity and ownership are asserted by the caller, not attested.',
+    'Release and Git identities are caller-supplied labels, not independently verified deployment identity.',
+    'No provisioning, credentials, policy guarantees, soak, recovery or independent security assessment is included.',
+    'Duplicate raw header counts and malformed-path normalization can differ at provider ingress; this common suite does not prove those transports equivalent.'
+  ]};
+}
+/** Replay against a caller-supplied local adapter; never label this a provider deployment. */
+export async function runProviderConformance(target                   ,transport                  ,options                            ={})                                     {
+  return run(target,transport,options,null);
+}
+function httpsTransport(origin    )                   {
+  return (probe,signal)=>new Promise((resolve,reject)=>{
+    let settled=false;
+    const fail=()=>{if(!settled){settled=true;reject(new Error('HTTPS probe failed'));}};
+    const req=request(new URL(probe.path,origin),{method:probe.method,headers:{'user-agent':'URLCode-provider-conformance/1','accept-encoding':'identity',...probe.headers},agent:false,maxHeaderSize:16384,signal},res=>{
+      const chunks         =[];let size=0;
+      res.on('error',fail);res.on('aborted',fail);
+      res.on('data',(chunk       )=>{size+=chunk.length;if(size>MAX_BYTES){fail();res.destroy();req.destroy();}else chunks.push(chunk);});
+      res.on('end',()=>{if(settled)return;settled=true;const headers                      ={};for(const [name,value]of Object.entries(res.headers))if(value!==undefined)headers[name]=Array.isArray(value)?value.join(', '):value;resolve({status:res.statusCode??0,headers,body:Buffer.concat(chunks).toString('utf8')});});
+    });
+    req.on('error',fail);req.end(probe.body);
+  });
+}
+/** Probe only an explicitly supplied, operator-owned deployment of the fixture. Redirects are never followed. */
+export async function verifyProviderDeployment(target                   ,origin       ,options                            ={})                                     {
+  optionsChecked(target,options);
+  const url=new URL(origin);
+  if(url.protocol!=='https:'||url.username||url.password||url.pathname!=='/'||url.search||url.hash||url.origin!==origin.replace(/\/$/,''))throw new Error('Provide an explicit HTTPS origin without credentials, path, query or fragment');
+  return run(target,httpsTransport(url),options,url.origin);
+}