@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/server.js

@@ -7,8 +7,6 @@ import { join } from 'node:path';
 import { createRuntime } from './runtime.js';
                                                                                     
 import { createJsonLogger } from './logging.js';
-import { createLinkObserver } from './link-events.js';
-                                                          
 import { createObserverSink, renderPrometheus } from './observability.js';
                                                                                                  
 import { assert, HttpError } from './errors.js';
@@ -19,12 +17,12 @@ import { compileTrustedProxies, resolveClient } from './client-address.js';
                                                                           
                                                                                                                   
                                                                                                                               
-                                                                                              
+                                                                        
                                                                                                                                                             
  
                          
                                                                                                             
-                                                                              
+                             
                                                                                                   
  
 
@@ -83,7 +81,7 @@ function originForm(target        )         {
 export async function startServer({ project = '.', host = '127.0.0.1', port = 3000, watch = false,
   local = false, log = createJsonLogger(),
   maxBodyBytes = 1048576, maxInFlightRequests = 64, maxInFlightHealthRequests = 16,
-  requestLog = 'minimal', trustRequestId = false, origin, linkEvents, trustedProxies = [],
+  requestLog = 'minimal', trustRequestId = false, origin, trustedProxies = [],
   observers = [], metrics = false, metricsIntervalMs = 0, ...runtimeOptions }                = {})                  {
   // Which peers may set X-Forwarded-For. Empty means the socket peer is the
   // client for every policy; a forwarded header from anyone else is ignored.
@@ -105,9 +103,6 @@ export async function startServer({ project = '.', host = '127.0.0.1', port = 30
   const sink               = createObserverSink(observers, log);
   const counters = sink.metrics;
   const emit = (event                         , context                )       => { try { sink(event, context); } catch { /* Logging cannot fail requests. */ } };
-  // Operator-supplied and explicitly enabled; route YAML cannot reach it and no
-  // callback is ever loaded from the project. Undefined leaves it off.
-  const observer = createLinkObserver(linkEvents, emit);
   let current          = await createRuntime(project, { local, log: emit, origin, ...runtimeOptions });
   let shuttingDown = false, reloading = false, watching = false, interval                            , lastFingerprint                    , inFlight = 0, healthInFlight = 0;
   const retired = new Set               ();
@@ -128,24 +123,6 @@ export async function startServer({ project = '.', host = '127.0.0.1', port = 30
     let status = 500;
     res.on('error', () => {});
     req.on('error', () => {});
-    {
-      // Enqueued after the response is over, so an observer can neither delay a
-      // redirect nor turn its own failure into one. A response that never
-      // finished is reported as aborted rather than counted as a click. The
-      // outcome is counted whether or not an operator collects link events.
-      let observed = false;
-      const settle = () => {
-        if (observed || !trace.link) return;
-        observed = true;
-        const event = { event: 'link_request', requestId, collection: trace.link.collection, route: trace.route ?? null,
-          code: trace.link.code, method, status,
-          outcome: trace.link.result === 'redirect' ? (res.writableFinished ? 'completed' : 'aborted') : trace.link.result,
-          durationMs: Math.round((performance.now() - started) * 100) / 100 };
-        counters.record(event);
-        if (observer) observer.emit(event);
-      };
-      res.once('finish', settle); res.once('close', settle);
-    }
     try {
       if (shuttingDown) throw new HttpError(503, 'Runtime shutting down');
       let result               ;
@@ -246,7 +223,6 @@ export async function startServer({ project = '.', host = '127.0.0.1', port = 30
   }
   return {
     server, reload, address, root: current.root, testPlan: () => current.testPlan(),
-    linkEventStats: () => observer?.stats(),
     metrics: snapshot,
     get observers() { return observers.map(observer => ({ name: observer.name, version: observer.version })); },
     // What a request sees as its own origin: behind a tunnel or proxy this is
@@ -260,8 +236,6 @@ export async function startServer({ project = '.', host = '127.0.0.1', port = 30
       clearTimeout(deadline);
       while (reloading) await new Promise(resolve => setTimeout(resolve,10));
       await current.close(); await Promise.all(retired);
-      // Observers drain after the connections they describe are gone.
-      if (observer) emit({ event: 'link_observer', status: 'closed', ...await observer.close() });
       // A final snapshot, then observers release in reverse order.
       sink.publish(snapshot());
       await sink.close();

package/dist/signals.js

@@ -0,0 +1,24 @@
+import { egressUrl, safeEgressHeaders } from './egress.js';
+                                                  
+                                                                                
+                                                                           
+                                                                                                 
+export function validateSignal(definition                 )      {if(!definition||typeof definition!=='object'||Object.keys(definition).some(key=>!['url','headers'].includes(key))) throw new Error('Invalid signal');egressUrl(definition.url);safeEgressHeaders(definition.headers||{});}
+/** No queue, retries, ordering promise, or durable delivery. Counters contain no URL/header data. */
+export class SignalBroker {
+           #onStats                                      ;          #client                ;          #concurrency       ;          #pending=new Set               ();          #controller=new AbortController();
+           #stats            ={accepted:0,delivered:0,failed:0,dropped:0}; #closed=false;
+  constructor(client                ,concurrency=8,onStats                            ) {if(!Number.isSafeInteger(concurrency)||concurrency<1||concurrency>128) throw new Error('Invalid signal concurrency');this.#onStats=onStats;this.#client=client;this.#concurrency=concurrency;}
+  get stats()             {return {...this.#stats};}
+  emit(definition                 ,event            )         {
+    if(this.#closed||this.#pending.size>=this.#concurrency) {this.#stats.dropped++;this.#notify();return false;}
+    try {validateSignal(definition);} catch {this.#stats.dropped++;this.#notify();return false;}
+    if(!event.route.startsWith('/')||event.route.length>2048||!/^[A-Z]{1,16}$/.test(event.method)||!Number.isInteger(event.status)||event.status<100||event.status>599) {this.#stats.dropped++;this.#notify();return false;}
+    this.#stats.accepted++;this.#notify();
+    const body=Buffer.from(JSON.stringify({version:1,route:event.route,status:event.status,method:event.method}));
+    const pending=Promise.resolve().then(()=>this.#client.request({url:definition.url,method:'POST',headers:{...definition.headers,'content-type':'application/json'},body,signal:this.#controller.signal})).then(result=>{if(result.status>=200&&result.status<300)this.#stats.delivered++;else this.#stats.failed++;},()=>{this.#stats.failed++;}).finally(()=>{this.#pending.delete(pending);this.#notify();});
+    this.#pending.add(pending);return true;
+  }
+  #notify()      {try {this.#onStats?.(this.stats);} catch { /* Observers cannot alter delivery. */ }}
+  async close()               {this.#closed=true;this.#controller.abort();await Promise.allSettled([...this.#pending]);}
+}

package/dist/tooling.js

@@ -0,0 +1,96 @@
+import {loadDocument} from './config.js';
+import {applySite} from './site.js';
+import {prepareFunctionSnapshot,requestedPermissions} from './policy.js';
+import {compileRoutes,matchRoute,parseTarget} from './router.js';
+import {compilePolicies,closePolicies} from './policies.js';
+import {analyzeCompiledCapabilities,routeCapabilities} from './capabilities.js';
+                                                           
+import {importRoutes,exportRoutes} from './interchange.js';
+                                                                            
+import {listRecipes,showRecipe,searchRecipes} from './recipes.js';
+import {listExamples,searchExamples} from './examples.js';
+                                                                       
+import {effectiveExtensionPolicies} from './extensions.js';
+                                                      
+import {loadOperatorHost} from './operator-host.js';
+import {explainCompiledRoute,nearestRoutes} from './explain.js';
+                                                   
+export {getCapabilities} from './capabilities.js';
+export {getCapability} from './capability-query.js';
+                                                                           
+export {getSchemaFragment,schemaPathNames} from './schema-query.js';
+                                                      
+export {listRecipes,showRecipe,searchRecipes,listExamples,searchExamples};
+export {buildContext,renderContext,estimateTokens,documentationTokens} from './context.js';
+                                                                               
+                                                                                                                                                 
+/** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
+                                                                                                                                     
+function routesOf(table                                          )                 {return [...table.exact.values(),...[...table.byLength.values()].flat(),...table.mounts];}
+export async function prepare(project       ,options               ={}) {
+ const loaded=await loadDocument(project);await applySite(loaded,{...(options.origin?{origin:options.origin}:{})});
+ const snapshot=await prepareFunctionSnapshot(loaded),bindings                      =Object.create(null);
+ for(const route of Object.values(loaded.routes)) {for(const ref of Object.values(route.env||{}))if(ref.env)bindings[ref.env]='validation-only';for(const ref of Object.values(route.secrets||{}))bindings[ref.secret]='validation-only';}
+ const compiled=await compileRoutes(loaded,bindings,requestedPermissions(loaded,snapshot),snapshot.projectSha256),routes=routesOf(compiled);
+ const shared             ={target:'node',routes:routes.length,log:()=>{}};
+ // The same policy inventory the runtime attaches (src/runtime.ts): compiled for every route when the project declares any.
+ const anyPolicy=Boolean(loaded.document.policies)||routes.some(route=>route.policies),chains=new Map                    ();
+ try {for(const route of routes){const chain=await compilePolicies(loaded.document,route,{route,shared,target:'node',root:loaded.root});if(anyPolicy)chains.set(route.pattern,chain);}}finally{await closePolicies(shared);}
+ return {loaded,compiled,routes,chains,projectSha256:snapshot.projectSha256};
+}
+function compatibilitySummary(report                    ) {return {target:report.target,compatible:report.compatible,deployment:report.deployment,requirementCount:report.requirements.length,issueCount:report.issues.length};}
+/** Semantic authoring inspection; no binding reads, sandbox execution or runtime activation. */
+export async function inspectProject(project       ,options               ={}) {
+ const offset=options.offset??0,limit=options.limit??100;
+ if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(limit)||limit<1||limit>1000)throw new Error('Invalid inspection page');
+ const {loaded,compiled,routes,projectSha256}=await prepare(project,options);
+ const report=analyzeCompiledCapabilities(loaded.document,compiled,options.target??'self-hosted',options.extensions);
+ return {format:1,projectSha256,routeCount:compiled.count,offset,limit,routes:routes.slice(offset,offset+limit).map(route=>({path:route.pattern,methods:route.methods,enabled:route.enabled!==false,capabilities:routeCapabilities(route,loaded.document)})),compatibility:{...compatibilitySummary(report),offset,limit,hasMore:offset+limit<report.issues.length,issues:report.issues.slice(offset,offset+limit)}};
+}
+export async function validateProject(project       ,options               ={}) {
+ const result=await inspectProject(project,{...options,offset:0,limit:1});
+ const {target,compatible,deployment,requirementCount,issueCount,issues}=result.compatibility;
+ return {valid:true,projectSha256:result.projectSha256,routeCount:result.routeCount,compatibility:{target,compatible,deployment,requirementCount,issueCount,firstIssue:issues[0]??null}};
+}
+                                                                       
+/** Explain the route a path selects from the compiled IR: effective methods, handler, middleware, inputs, policies, cache outcome, bindings and target support. Nothing executes and no binding is read. */
+export async function explainRoute(project       ,target       ,options               ={})                                     {
+ const {loaded,compiled,chains,projectSha256}=await prepare(project,options),match=matchRoute(compiled,parseTarget(target));
+ if(!match)return {matched:false,nearest:nearestRoutes(target,routesOf(compiled).map(route=>route.pattern)),note:'No route selects this path.'};
+ return explainCompiledRoute(loaded,match.route,chains.get(match.route.pattern),{extensions:options.extensions,projectSha256});
+}
+/** Every route's explanation, in the router's precedence order. */
+export async function explainProject(project       ,options               ={})                                                                             {
+ const {loaded,routes,chains,projectSha256}=await prepare(project,options);
+ return {projectSha256,routeCount:routes.length,routes:routes.map(route=>explainCompiledRoute(loaded,route,chains.get(route.pattern),{extensions:options.extensions,projectSha256}))};
+}
+export async function previewImport(options                    ) {return importRoutes(options);}
+export async function previewExport(project       ,format                  ,acceptProviderDifferences=false) {const loaded=await loadDocument(project);const {includes:_includes,...document}=loaded.document;return exportRoutes({format,document:{...document,routes:loaded.routes},acceptProviderDifferences});}
+                                      
+                                                              
+                                                                                                                                                                                                            
+                                                                                                  
+ 
+/** Reports registered extension contracts against the project's declarations. Never activates an extension. */
+export async function describeExtensions(project       ,registrations                             )                              {
+ const loaded=await loadDocument(project),{projectSha256}=await prepareFunctionSnapshot(loaded),routes=Object.entries(loaded.routes);
+ const declarations=Object.entries(loaded.document.extensions??{});
+ const mountsOf=(name       )=>routes.filter(([,route])=>route.extension===name).map(([path])=>path.endsWith('/*')?path.slice(0,-2):path);
+ const policyRoutesOf=(name       )=>routes.filter(([,route])=>Object.hasOwn(effectiveExtensionPolicies(loaded.document,route),name)).map(([path])=>path);
+ const registered=new Set((registrations??[]).map(registration=>registration.name));
+ const declared=declarations.map(([name,declaration])=>({name,version:String(declaration.version),registered:registered.has(name),mounts:mountsOf(name),policyRoutes:policyRoutesOf(name)}));
+ if(registrations===undefined)return {format:1,projectSha256,hostLoaded:false,note:'Configuration and policy schemas come from the operator host file; supply --host-file to print them.',extensions:[],declared};
+ const extensions=registrations.map(registration=>({
+  name:String(registration.name),version:String(registration.version),targets:Array.isArray(registration.targets)?registration.targets.map(String):[],
+  credentialHeaders:Array.isArray(registration.credentialHeaders)?registration.credentialHeaders.map(String):[],
+  schema:structuredClone(registration.schema??{}),policySchema:registration.policySchema?structuredClone(registration.policySchema):null,
+  declared:Object.hasOwn(loaded.document.extensions??{},registration.name),revisionPinned:registration.projectSha256===projectSha256,
+  mounts:mountsOf(registration.name),policyRoutes:policyRoutesOf(registration.name),
+ }));
+ return {format:1,projectSha256,hostLoaded:true,note:'Schemas describe operator-installed contracts; inspection activates nothing and grants no revision.',extensions,declared};
+}
+/** Executes the trusted operator host file to read its registrations, then releases it. */
+export async function inspectExtensions(options                                  )                              {
+ const host=await loadOperatorHost(options.hostFile,options.project);
+ try{return await describeExtensions(options.project,options.hostFile===undefined?undefined:host.extensions??[]);}finally{await host.close?.();}
+}

package/dist/trusted-functions.js

@@ -0,0 +1,210 @@
+// Trusted (unsandboxed) execution for `function`/`middleware` routes that do
+// not declare `sandbox: true` (docs/SPIKE-DEFAULT-TRUST-MODEL.md). This is the
+// new default: an ordinary dynamic `import()` of the project's own module,
+// called in the host process with full Node access — no worker thread, no
+// QuickJS/WASM, no fresh-heap-per-call, no module-graph allowlist. The
+// sandboxed path (FunctionPool, function-worker.ts) is untouched by this file
+// and keeps its own guarantees exactly as before for any route that opts in
+// with `sandbox: true`.
+//
+// The request/response contract mirrors the sandboxed path (guest-api.ts) as
+// closely as an in-process call can: a `Request` and a `context` in, a
+// `Response` out, the same middleware `(request, context, next)` chain with
+// `next()` callable at most once and no arguments, and the same native-reply
+// passthrough (a middleware chain wrapping a native reply — redirect, asset,
+// static reply — can return that exact Response unchanged to avoid
+// re-encoding its body). Node's own `Request`/`Response`/`Headers` are used
+// instead of guest-api.ts's restricted classes, so a trusted function can
+// return richer bodies (e.g. binary) than a sandboxed one can; that is a
+// documented, intentional capability difference, not a contract violation.
+//
+// Deadline: unlike the sandboxed path, there is no interrupt mechanism that
+// can stop trusted code running in the host's own event loop. `timeoutMs`
+// here is an advisory race against the handler's promise settling — it
+// rejects the *call* once the deadline passes, but cannot preempt trusted
+// code that is blocking the event loop synchronously (a WASM interrupt has no
+// equivalent in-process). This is a documented difference from the
+// sandboxed path's forced worker termination; see docs/CAPACITY.md.
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { ConfigError, HttpError } from './errors.js';
+import { routeFunctions } from './function-sources.js';
+                                                           
+                                                                      
+                                                          
+                                                                    
+                                        
+
+                                                                                                                                   
+                                                              
+                                                            
+                                                                                                   
+                                                                                                                                     
+
+export class TrustedFunctions {
+  timeoutMs        ; maxBytes        ; log       ;
+  // Node's ESM loader caches a resolved module forever by URL, unlike a
+  // sandboxed worker, which gets a genuinely fresh module registry on every
+  // reload/restart. A snapshot reload constructs a brand-new TrustedFunctions
+  // (createRuntime runs again), so each instance gets its own cache-busting
+  // query string: reloaded code is re-imported and re-executed, matching the
+  // sandboxed pool's "new workers, new snapshot" reload contract, while a
+  // single instance still only imports each module once per process.
+                   epoch = randomUUID();
+  constructor({ timeoutMs = 5000, maxBytes = 1048576, log = () => {} }                          = {}) {
+    this.timeoutMs = timeoutMs; this.maxBytes = maxBytes; this.log = log;
+  }
+  // Eagerly imports and validates every declared export exists as a function,
+  // the same guarantee FunctionPool.start() gives the sandboxed path: a
+  // broken function/middleware module fails runtime activation up front
+  // rather than the first request that happens to hit it.
+  async start(routes                )                {
+    try { await Promise.all(routes.flatMap(routeFunctions).map(definition => this.loadExport(definition))); }
+    catch { throw new ConfigError('Function initialization failed (check module syntax, imports and exports)'); }
+    return this;
+  }
+  // No dependency allowlist, no relative-static-import-only rule and no
+  // per-module byte budget apply here — those are sandbox-snapshot
+  // constraints (function-sources.ts), not trusted-path ones. A trusted
+  // module may use bare specifiers, Node builtins, npm packages and dynamic
+  // import exactly like any other project code.
+          async loadExport(definition                   )                   {
+    let mod                         ;
+    try { mod = await import(pathToFileURL(definition.source).href + '?urlcode-trusted-epoch=' + this.epoch)                           ; }
+    catch { throw new HttpError(502, 'Function execution failed'); }
+    const value = mod[definition.export];
+    if (typeof value !== 'function') throw new HttpError(502, 'Function execution failed');
+    return value;
+  }
+  async execute(route              , request                     , context                 , native                           )                          {
+    // The timer backing the deadline race must be cleared on every path —
+    // success or failure — or a completed call leaves a live Timeout behind
+    // for the full timeoutMs (see #138: 100 sequential calls, 100 leaked
+    // timers). `finally` covers both outcomes of the race in one place.
+    // The AbortController lets a fired deadline reach into `invoke`'s body
+    // read and cancel it immediately (#137), instead of letting a losing
+    // racer keep consuming an oversized or slow stream after this call has
+    // already rejected with 504.
+    const controller = new AbortController();
+    let timer                            ;
+    const timeout = new Promise       ((_, reject) => {
+      timer = setTimeout(() => { controller.abort(); reject(new HttpError(504, 'Function deadline exceeded')); }, this.timeoutMs);
+      timer.unref?.();
+    });
+    const invocation = this.invoke(route, request, context, native, controller.signal);
+    try { return await Promise.race([invocation, timeout]); }
+    catch (error) { throw error instanceof HttpError ? error : new HttpError(502, 'Function execution failed'); }
+    finally {
+      clearTimeout(timer);
+      // `invocation` may still be running (e.g. blocked on a cancelled
+      // reader settling) after the race above has already returned; a later
+      // rejection from it must not surface as an unhandled rejection.
+      invocation.catch(() => {});
+    }
+  }
+  // Reads a Response body incrementally, rejecting/cancelling as soon as
+  // `maxBytes` is exceeded instead of buffering the whole stream first
+  // (#137: a single `.arrayBuffer()` call reads everything unconditionally,
+  // so a configured limit only ever rejects *after* the oversized body has
+  // already been fully read into memory). Also cancels the reader as soon as
+  // `signal` aborts (the call's deadline firing), rather than letting a slow
+  // stream keep being pulled after the request has already timed out.
+  // Applies on every path that has a real body to measure, GET or HEAD alike
+  // (#139): the caller decides whether to transmit the bytes, this only
+  // decides how many there are, matching the convention the native/asset
+  // path already uses (the full body and its length are always determined
+  // up front; only `prepareResponse` in http-response.ts drops the body for
+  // HEAD at write time).
+          async readBody(response          , signal             )                  {
+    if (response.body === null) return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const cancel = ()       => { reader.cancel().catch(() => {}); };
+    if (signal.aborted) { cancel(); throw new HttpError(504, 'Function deadline exceeded'); }
+    signal.addEventListener('abort', cancel, { once: true });
+    try {
+      const chunks           = [];
+      let total = 0;
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > this.maxBytes) { cancel(); throw new HttpError(502, 'Function execution failed'); }
+        chunks.push(Buffer.from(value));
+      }
+      return Buffer.concat(chunks, total);
+    } catch (error) {
+      if (signal.aborted) throw new HttpError(504, 'Function deadline exceeded');
+      throw error instanceof HttpError ? error : new HttpError(502, 'Function execution failed');
+    } finally { signal.removeEventListener('abort', cancel); }
+  }
+          async invoke(route              , request                     , requestContext                 , native                           , signal             )                          {
+    // Matches guest-api.ts's __invokePipeline/__invoke: a fresh `state` object
+    // per invocation, shared across the whole middleware+handler chain for
+    // this one call only, never carried between requests.
+    const context = requestContext                                                        ;
+    context.state = {};
+    const hasBody = request.body !== undefined && request.body.length > 0 && !['GET','HEAD'].includes(request.method);
+    const req = new Request(request.url, {
+      method: request.method, headers: request.headers,
+      ...(hasBody ? { body: request.body                           , duplex: 'half'          } : {}),
+    });
+    let nativeResponse                      ;
+    if (native) {
+      const nativeBytes = native.body                                       ;
+      const bodyless = [204,205,304].includes(native.status) || !nativeBytes || nativeBytes.length === 0;
+      nativeResponse = new Response(bodyless ? null : nativeBytes, { status: native.status, headers: native.headers });
+    }
+    const middleware = route.middleware || [];
+    const handlers = await Promise.all(middleware.map(definition => this.loadExport(definition)))                       ;
+    const entry = route.function ? (await this.loadExport(route.function)                  ) : undefined;
+    const dispatch = async (index        )                    => {
+      if (index === handlers.length) {
+        if (entry) return await entry(req, context);
+        if (nativeResponse) return nativeResponse;
+        throw new HttpError(502, 'Function execution failed');
+      }
+      let called = false, open = true, pending                               ;
+      const next = async (...args           )                    => {
+        if (args.length || called || !open) throw new TypeError('next may be called once during middleware');
+        called = true; pending = dispatch(index + 1); return pending;
+      };
+      let response          ;
+      try { response = await handlers[index] (req, context, next); if (pending) await pending.catch(() => {}); }
+      finally { open = false; }
+      if (!(response instanceof Response)) throw new HttpError(502, 'Function execution failed');
+      return response;
+    };
+    const response = await dispatch(0);
+    if (!(response instanceof Response) || !Number.isInteger(response.status) || response.status < 200 || response.status > 599) throw new HttpError(502, 'Function execution failed');
+    const nativeBody = response === nativeResponse;
+    const headers               = [...response.headers.entries()];
+    if (nativeBody && native) {
+      // The route returned the untouched native reply (possibly with extra
+      // headers a middleware added, e.g. `x-seen` above `location`): reject
+      // only if native's *own* metadata was changed, the same contract the
+      // sandboxed path enforces (function-worker.ts's "Native metadata
+      // changed" check) — an added header is fine, a changed one is not.
+      for (const key of new Set(native.headers.map(([k]) => k.toLowerCase()))) {
+        const originals = native.headers.filter(([k]) => k.toLowerCase() === key).map(([,v]) => v);
+        const current = headers.filter(([k]) => k.toLowerCase() === key).map(([,v]) => v);
+        if (JSON.stringify(originals) !== JSON.stringify(current)) throw new HttpError(502, 'Function execution failed');
+      }
+    }
+    // Header count/byte limits apply either way, matching function-worker.ts.
+    { let bytes = 0; for (const [k,v] of headers) bytes += Buffer.byteLength(k) + Buffer.byteLength(v) + 4;
+      if (headers.length > 256 || bytes > 16384) throw new HttpError(502, 'Function execution failed'); }
+    // Measured on HEAD too, not skipped: prepareResponse (http-response.ts)
+    // is what decides not to put the bytes on the wire for HEAD, but it
+    // still needs the real length rather than the 0 a skipped read leaves it
+    // to assume (#139).
+    const body             = nativeBody && native
+      ? ((native.body                          ) ?? Buffer.alloc(0))
+      : await this.readBody(response, signal);
+    return { status: response.status, headers, body, nativeBody,
+      ...(nativeBody && native?.contentLength !== undefined ? { contentLength: native.contentLength } : {}) };
+  }
+  // Symmetry with FunctionPool.close(): nothing to release for the trusted
+  // path (no workers, no pending requests it owns), but the runtime can call
+  // either executor's close() uniformly during shutdown.
+  async close()                { /* no owned resources */ }
+}

package/dist/types/adapters.d.ts

@@ -1,12 +1,15 @@
+import type { RuntimeExtension } from './extensions.ts';
 import type { HostPlugin, OperatorPolicy, Runtime } from './runtime.ts';
-import type { TargetName } from './types.ts';
 /** The subset of process.env a hosted adapter reads. */
 export type Environment = Record<string, string | undefined>;
-export interface NativeOnlyOptions {
-    target?: TargetName | undefined;
+interface NativeOnlyOptions {
+    target: 'aws' | 'vercel';
     plugins?: HostPlugin[] | undefined;
+    extensions?: RuntimeExtension[] | undefined;
+    origin?: string | undefined;
 }
 export declare function readPolicyFromEnvironment(environment: Environment): OperatorPolicy | undefined;
-export declare function activateNativeOnly(project: string, environment: Environment, { target, plugins }?: NativeOnlyOptions): Promise<Runtime>;
+export declare function activateNativeOnly(project: string, environment: Environment, { target, plugins, extensions, origin }: NativeOnlyOptions): Promise<Runtime>;
 export declare function lazyRuntime<T>(activate: () => Promise<T>): () => Promise<T>;
 export declare function resolveOrigin(origin: string | undefined, environment: Environment, platformVariables: string[]): string | undefined;
+export {};

package/dist/types/agent-lists.d.ts

@@ -1,5 +1,4 @@
 import type { AgentEntry, AgentsConfig } from './policies/agents.ts';
-export declare const MAX_LIST_ENTRIES = 4096;
 export declare function loadListFile(root: string, reference: string, routePattern?: string): Promise<AgentEntry[]>;
 export declare function loadListFiles(references: string[], root: string | undefined, routePattern: string): Promise<Record<string, AgentEntry[]>>;
 export declare function resolveLists(config: AgentsConfig | undefined, root: string, routePattern?: string): Promise<AgentsConfig | undefined>;

package/dist/types/agents-guide.d.ts

@@ -0,0 +1,17 @@
+/** Where the packaged agent skill lives, relative to the installed @jimhoyd/urlcode package. */
+export declare const skillPath = "skills/urlcode/SKILL.md";
+/** The MCP registration file `urlcode init` writes beside the project (Claude Code and Codex read this shape). */
+export declare const mcpConfigFile = ".mcp.json";
+/**
+ * Renders `.mcp.json` registering the read-only `urlcode mcp` server for the project at `project`, relative
+ * to the file. `--allow-authoring` is deliberately absent: the operator adds it by hand when they want it.
+ */
+export declare function renderMcpConfig(project?: string): string;
+/**
+ * The application-level AGENTS.md written by `urlcode init`. Built from the
+ * installed runtime's capability catalog, so it names only the handlers,
+ * policies and site keys this version implements. Under 80 lines by design.
+ */
+export declare function renderAgentsGuide({ routes }: {
+    routes: number;
+}): string;

package/dist/types/authoring-files.d.ts

@@ -0,0 +1,10 @@
+/** Authoring output never copies hidden state, package hooks, or credential files. */
+export declare function authoringPath(path: string): string;
+export declare function authoringFile(root: string, path: string, directory?: boolean): Promise<string>;
+export declare function readAuthoringFile(root: string, path: string, limit: number): Promise<Buffer>;
+/** Reserve a fresh directory exclusively, then publish the entry config last.
+ * Failed writes remove only the directory created by this invocation. No existing
+ * directory (even an empty one) is accepted; consumers see no activatable project
+ * until every dependency has been written. Callers must own the output parent.
+ */
+export declare function publishAuthoringProject(output: string, files: ReadonlyMap<string, Buffer | string>, dryRun?: boolean): Promise<string>;

package/dist/types/aws.d.ts

@@ -1,3 +1,4 @@
+import type { RuntimeExtension } from './extensions.ts';
 import type { Environment } from './adapters.ts';
 import type { HostPlugin } from './runtime.ts';
 export interface LambdaHandlerOptions {
@@ -6,6 +7,7 @@ export interface LambdaHandlerOptions {
     environment?: Environment | undefined;
     maxBodyBytes?: number | undefined;
     plugins?: HostPlugin[] | undefined;
+    extensions?: RuntimeExtension[] | undefined;
 }
 /** A Lambda payload format 2.0 event, as far as this adapter reads it. */
 export interface LambdaEvent {
@@ -32,4 +34,4 @@ export interface LambdaResponse {
     isBase64Encoded: true;
 }
 export type LambdaHandler = (event: unknown) => Promise<LambdaResponse>;
-export declare function createLambdaHandler({ project, origin, environment, maxBodyBytes, plugins }?: LambdaHandlerOptions): LambdaHandler;
+export declare function createLambdaHandler({ project, origin, environment, maxBodyBytes, plugins, extensions }?: LambdaHandlerOptions): LambdaHandler;

package/dist/types/build-cloudflare.d.ts

@@ -10,5 +10,6 @@ export interface BuildReport {
     version: string;
     routes: number;
     validators: number;
+    manifest: string;
 }
 export declare function buildCloudflare(project: string, { out, origin, log }?: BuildOptions): Promise<BuildReport>;

package/dist/types/build-static.d.ts

@@ -0,0 +1,43 @@
+import type { LogFn } from './types.ts';
+export interface BuildOptions {
+    out?: string | undefined;
+    origin?: string | undefined;
+    log?: LogFn | undefined;
+}
+export interface BuildReport {
+    out: string;
+    format: number;
+    version: string;
+    routes: number;
+    redirects: number;
+    files: number;
+    manifest: string;
+}
+/** One S3 per-object website redirect: a zero-byte object at `key` carrying
+ * `x-amz-website-redirect-location: location`, which S3 always answers with a
+ * 301 regardless of the object's own metadata. */
+export interface StaticRedirect {
+    key: string;
+    location: string;
+    status: 301;
+}
+/** One served file: the bytes are written under `out/objects/<key>`; the
+ * metadata here is what a deploy step sets as the S3 object's own headers. */
+export interface StaticObject {
+    key: string;
+    contentType: string;
+    cacheControl?: string;
+    contentDisposition?: string;
+}
+export interface RedirectManifest {
+    format: number;
+    redirects: StaticRedirect[];
+}
+export interface ObjectManifest {
+    format: number;
+    objects: StaticObject[];
+}
+declare function objectKey(pattern: string): string;
+export declare function buildStatic(project: string, { out, origin, log }?: BuildOptions): Promise<BuildReport>;
+export declare const staticObjectKey: typeof objectKey;
+export {};

package/dist/types/bulk.d.ts

@@ -0,0 +1,27 @@
+import type { ConversionDiagnostic } from './interchange.ts';
+export type BulkFormat = 'csv' | 'json' | 'yaml';
+export interface BulkFilePlan {
+    path: string;
+    routeCount: number;
+    firstPath?: string;
+    lastPath?: string;
+}
+export interface BulkImportReport {
+    ok: boolean;
+    dryRun: boolean;
+    output?: string;
+    routeCount: number;
+    diagnostics: ConversionDiagnostic[];
+    files: BulkFilePlan[];
+    source: {
+        name: string;
+        format: BulkFormat;
+        sha256: string;
+    };
+}
+/** Import ordinary redirect rows into small, portable include files. There is no
+ * merge mode: duplicate rules and existing output directories are refused. */
+export declare function importBulkProject(text: string, format: BulkFormat, output: string, { dryRun, source }?: {
+    dryRun?: boolean | undefined;
+    source?: string | undefined;
+}): Promise<BulkImportReport>;