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

package/dist/extensions.js

@@ -8,7 +8,18 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                                                         
                                                                                     
                                                                             
-                                                                                                                         
+/**
+ * `root` is the project's resolved absolute directory (the same value
+ * `loadDocument()` computes and `functionFile()`/router.ts resolves
+ * `function`/`middleware` `source` entries against). It is not the process's
+ * `cwd()`: `--project`/`--host-file` are independent paths, a server can be
+ * started from any working directory, and the JS API can load a project
+ * programmatically with no relationship to `cwd()` at all. An extension that
+ * resolves project-relative paths of its own (for example, an alternative
+ * middleware source it loads by convention rather than through core's native
+ * `middleware:` array) must resolve them against this field, never `cwd()`.
+ */
+                                                                                                                                      
                                    
                                                                                     
                                                                                    
@@ -17,6 +28,20 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                                     
                                                                         
                                                                                                                                              
+     
+                                                                             
+                                                                        
+                                                                             
+                                                                           
+                                                                           
+                                                                          
+                                                                             
+                                                                               
+                                                                           
+                                                                        
+                                                                   
+     
+                                                                                                                                                     
                               
  
 /** Trusted operator code only. YAML declares names/configuration, never modules. */
@@ -30,6 +55,23 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.js'
                                    
                                                                        
                                                                                                               
+     
+                                                                                   
+                                                                        
+                                                                           
+                                                                           
+                                                                           
+                                                                              
+                                                                          
+                                                  
+                                                                       
+                                                                       
+                                                                         
+                                                                            
+                                                                             
+                                                                             
+     
+                          
                                                                                                                              
  
 /** `urlcode init --with <name>` contract: what core hands `@jimhoyd/urlcode-<name>`'s `scaffold` export. Nothing is written by `scaffold`. */
@@ -85,6 +127,23 @@ export function effectiveExtensionPolicies(document                ,route
   return result;
 }
 export function hasExtensionPolicy(document                ,route                             )         {return Object.keys(effectiveExtensionPolicies(document,route)).length>0;}
+/**
+ * Whether a route naming these `policies.extensions` names must be treated as
+ * confidential (forced no-store, no compression, extension response caps).
+ * `names` with no entries is never confidential. Without a `registrations`
+ * list to consult (a build path with no operator host loaded), every name is
+ * treated as sensitive: the safe default this can only relax, never weaken.
+ * A name whose registration is missing, or declares no `cacheSensitive` (or
+ * `true`), counts as sensitive; only an explicit `cacheSensitive: false`
+ * excuses it, and one sensitive name among several makes the whole route
+ * confidential.
+ */
+export function isSensitiveExtensionPolicy(names                  ,registrations                                                           )         {
+  if(!names.length)return false;
+  if(!registrations)return true;
+  const byName=new Map(registrations.map(registration=>[registration.name,registration.cacheSensitive]));
+  return names.some(name=>byName.get(name)!==false);
+}
 export function prepareExtensions(document                ,routes                           ,registrations                             ,context                                   )                                          {
   assert(registrations===undefined||Array.isArray(registrations)&&registrations.length<=16,'Extensions must be an array of at most 16 operator registrations');
   const provided=new Map                         (),entries=new Map                        (),credentialHeaders=new Set        ();
@@ -127,7 +186,7 @@ export function prepareExtensions(document                ,routes
     try{for(const {name,registration,config,policies,mounts,assetPrefixes}of preparations){
       const instance=await registration.activate(config,frozen({...context,mounts}));
       if(instance&&typeof instance==='object')entries.set(name,{instance,policies,assetPrefixes});
-      assert(instance&&typeof instance.handle==='function'&&(!policies.size||typeof instance.authorize==='function'),`Extension ${name} lacks a required handler or authorization hook`);
+      assert(instance&&typeof instance.handle==='function'&&(!policies.size||typeof instance.authorize==='function'||typeof instance.middleware==='function'),`Extension ${name} lacks a required handler, authorization hook or middleware hook`);
       entries.set(name,{instance,policies,assetPrefixes});
     }}catch(error){for(const entry of [...entries.values()].reverse())try{await entry.instance.close?.();}catch{/* Keep the activation failure. */}throw error;}
     return {entries,credentialHeaders:[...credentialHeaders],async close(){for(const entry of [...entries.values()].reverse())try{await entry.instance.close?.();}catch{/* Operators own extension lifecycle diagnostics. */}}};

package/dist/function-sources.js

@@ -25,8 +25,35 @@ export const TOTAL_BYTE_LIMIT = 4194304;
 
 export function routeFunctions   (route                  )      { return [...(route.middleware || []), ...(route.function ? [route.function] : [])]; }
 
+// Trusted (unsandboxed) routes are never bundled into a QuickJS module snapshot:
+// they run through Node's own module resolution, with no restriction on bare
+// specifiers, dynamic import or dependency count/size. For revision pinning
+// (docs/SPIKE-DEFAULT-TRUST-MODEL.md, "trust-declaration integrity"), the
+// project hash must still change when a trusted function/middleware's own
+// source changes, so an operator's env/secret grant is invalidated the moment
+// the code that could use it is edited. This only hashes each entry file's own
+// bytes, not its transitive import graph the way the sandboxed collector does:
+// a change to a helper module a trusted entry imports, without touching the
+// entry file itself, does not by itself change the project hash. Documented as
+// a known limitation in docs/FUNCTION-SECURITY.md.
+export async function collectTrustedSources(routes                 , root        )                                  {
+  const sources                         = Object.create(null);
+  for (const definition of routes.flatMap(routeFunctions)) {
+    const name = '/' + relative(root, definition.source).split(sep).join('/');
+    if (Object.hasOwn(sources, name)) continue;
+    sources[name] = await readFile(definition.source, 'utf8');
+  }
+  return sources;
+}
+
 // Parse and snapshot source without ever importing project code into Node.
-export async function collectFunctionSources(routes                 , root        )                           {
+// Route-shaped callers go through `collectFunctionSources` below; a
+// route-independent caller (the public sandbox primitive, src/sandbox.ts)
+// calls this directly with its own explicit `{source, export}` list, so the
+// module-allowlist walk and per-module/total byte budgets apply identically
+// either way — there is exactly one collector, not a route-shaped one and a
+// second generic one.
+export async function collectSourcesFor(definitions                      , root        )                           {
   await init;
   const sources                         = Object.create(null), dependencies                           = Object.create(null);
   const entries                     = [], names = new Map                (), seenEntries = new Set        ();
@@ -56,7 +83,7 @@ export async function collectFunctionSources(routes                 , root
     }
     return name;
   }
-  for (const definition of routes.flatMap(routeFunctions)) {
+  for (const definition of definitions) {
     const name = await collect(definition.source);
     names.set(definition.source,name);
     const key = name + ":" + definition.export;
@@ -64,3 +91,8 @@ export async function collectFunctionSources(routes                 , root
   }
   return { sources,dependencies,entries,names };
 }
+/** Route-shaped convenience over `collectSourcesFor`: every existing caller (policy.ts,
+ * prerender.ts, typescript-authoring.ts) keeps working unchanged from `FunctionRoute[]`. */
+export async function collectFunctionSources(routes                 , root        )                           {
+  return collectSourcesFor(routes.flatMap(routeFunctions), root);
+}

package/dist/function-worker.js

@@ -83,6 +83,7 @@ port.on('message', async ({id,source,name,request,context,maxBytes,timeoutMs,cha
     if (output === undefined || Buffer.byteLength(output) > maxBytes * 6 + 65536) throw new Error('Output limit');
     const value = JSON.parse(output)                               ; // trust boundary: guest JSON, checked below
     if (!value || !Number.isInteger(value.status) || value.status < 200 || value.status > 599 || typeof value.body !== 'string' || !Array.isArray(value.headers) || value.headers.length > 256) throw new Error('Invalid response');
+    if (value.contentLength !== undefined && (!Number.isInteger(value.contentLength) || value.contentLength < 0)) throw new Error('Invalid response');
     if (value.nativeBody) {
       if (!native || value.status !== native.status || value.body !== '') throw new Error('Invalid native response');
       // Preserve native status and metadata (validators, ranges, redirect Location).
@@ -100,6 +101,7 @@ port.on('message', async ({id,source,name,request,context,maxBytes,timeoutMs,cha
       bytes += Buffer.byteLength(pair[0]) + Buffer.byteLength(pair[1]) + 4;
     }
     if (bytes > 16384) throw new Error('Header limit');
-    post({id,status:value.status,headers:value.headers,body,nativeBody:value.nativeBody === true});
+    post({id,status:value.status,headers:value.headers,body,nativeBody:value.nativeBody === true,
+      ...(typeof value.contentLength === 'number' ? {contentLength:value.contentLength} : {})});
   } catch { post({id,error:true}); }
 });

package/dist/functions.js

@@ -1,7 +1,7 @@
 import { Worker } from 'node:worker_threads';
 import { randomUUID } from 'node:crypto';
-import { collectFunctionSources, routeFunctions } from './function-sources.js';
-                                                                            
+import { collectSourcesFor, routeFunctions } from './function-sources.js';
+                                                                                                
 import { assert, ConfigError, HttpError } from './errors.js';
                                                                     
                                                                  
@@ -9,10 +9,24 @@ import { assert, ConfigError, HttpError } from './errors.js';
                                                           
                                                                                
                                                                                 
-                                      
+/** A module entry point the sandbox must load: an absolute source file path
+ * (already resolved and validated, e.g. via `functionFile()`) plus which
+ * export of it needs to be reachable. The same shape a `FunctionDefinition`
+ * already uses for `function`/`middleware` routes. */
+                                              
+/** What one `SandboxPool.execute()` call invokes: the same `{source, export}`
+ * shape as a `SandboxEntry`, naming one of the pool's declared entries. */
+                                               
+/** `entry` runs last (the route's `function`/handler); `chain` runs first, in
+ * order, each with `(request, context, next)` — the same wrap/middleware
+ * semantics `__invokePipeline` already gives sandboxed routes. Neither is
+ * required: an empty invocation with a `native` reply just returns it. */
+                                                                                                             
+                                     
                                                                                                   
                                                                                          
  
+                                                     
 
 // The worker protocol. Only JSON-shaped data and byte buffers cross it.
                                                                                                                                             
@@ -26,27 +40,43 @@ import { assert, ConfigError, HttpError } from './errors.js';
                                                                               
                                    
                                             
-                                                                                                
+                                                                                                                        
                                 
 
                                                                                                                                    
                                                                           
 
-export class FunctionPool {
-  root                    ; routes                 ; preparedSnapshot                             ; snapshot                             ;
+// The generalized sandbox primitive: the pool of worker threads, each running
+// the same function-worker.ts (QuickJS engine setup, dependency-closure module
+// allowlisting, memory/stack limits, deadline enforcement via both the
+// interrupt handler and outer worker termination, response-shape validation),
+// driven by an explicit list of `{source, export}` entries rather than
+// anything route/YAML-shaped. This is the ONE place that owns worker
+// spawning/QuickJS setup/deadline enforcement; `FunctionPool` below is a thin
+// route-shaped wrapper over it, not a second copy of the mechanics. Exported
+// publicly (as `@jimhoyd/urlcode/sandbox`, see src/sandbox.ts) for an
+// extension package that needs to run PROJECT code — a hook a project's own
+// config names — through the same trusted/sandboxed dispatch selection route
+// dispatch gets, when that hook declares `sandbox: true`
+// (docs/EXTENSIONS.md#project-level-lifecycle-hooks). There is no "trusted"
+// mode here: an extension wanting trusted execution just calls the project's
+// function directly via `import()` (already possible via
+// `ExtensionActivation.root`); this primitive is only ever the sandboxed path.
+export class SandboxPool {
+  root                    ; entries                ; preparedSnapshot                             ; snapshot                             ;
   restarts                     ; restartTimers                     ; log       ; timeoutMs        ; maxBytes        ;
   modules                      ; size        ; slots                      ; closed         ;
-  constructor(routes                 , { root, snapshot, workers = 2, timeoutMs = 5000, maxBytes = 1048576, log = () => {} }                      = {}) {
+  constructor(entries                , { root, snapshot, workers = 2, timeoutMs = 5000, maxBytes = 1048576, log = () => {} }                     = {}) {
     assert(Number.isInteger(workers) && workers >= 1 && workers <= 32, 'Workers must be 1–32');
     assert(Number.isInteger(timeoutMs) && timeoutMs >= 10 && timeoutMs <= 60000, 'Function timeout must be 10–60000 ms');
     assert(Number.isInteger(maxBytes) && maxBytes >= 1 && maxBytes <= 16777216, 'Response limit must be 1–16777216 bytes');
-    this.root = root; this.routes = routes; this.preparedSnapshot = snapshot;
+    this.root = root; this.entries = entries; this.preparedSnapshot = snapshot;
     // Consecutive replacement attempts per slot; cleared by a completed invocation.
     this.restarts = new Map(); this.restartTimers = new Set();
     this.log = log;
     this.timeoutMs = timeoutMs; this.maxBytes = maxBytes;
     const modules = new Map                     ();
-    for (const definition of routes.flatMap(routeFunctions)) {
+    for (const definition of entries) {
       const { source, export: name } = definition;
       let names = modules.get(source);
       if (!names) { names = new Set(); modules.set(source, names); }
@@ -58,7 +88,7 @@ export class FunctionPool {
   }
   async start()                {
     let snapshot = this.preparedSnapshot;
-    if (!snapshot && this.size) { assert(this.root !== undefined, 'Function pool requires a project root'); snapshot = await collectFunctionSources(this.routes,this.root); }
+    if (!snapshot && this.size) { assert(this.root !== undefined, 'Function pool requires a project root'); snapshot = await collectSourcesFor(this.entries,this.root); }
     snapshot ??= {sources:{},dependencies:{},entries:[],names:new Map()};
     this.snapshot = snapshot;
     try { await Promise.all(Array.from({ length: this.size }, (_, i) => this.spawn(i))); }
@@ -138,11 +168,18 @@ export class FunctionPool {
     timer.unref(); this.restartTimers.add(timer);
   }
   get healthy()          { return !this.closed && this.slots.length === this.size && this.slots.every(slot => slot?.ready); }
-  execute(route               , request                     , context                 , native                           )                          {
+  /** `invocation.entry` runs last (chain-wrapped), `invocation.chain` first, in
+   * declared order — the same `__invokePipeline` wrap/middleware discipline
+   * (`next()` callable at most once) the sandboxed route path already
+   * enforces; there is no second dispatch mechanism for this. Every entry and
+   * chain source named here must already be one of this pool's declared
+   * `entries` (constructor), or the worker's own module allowlist denies it. */
+  execute(invocation                   , request                     , context                 , native                           )                          {
     const slot = this.slots.find(s => s?.ready && !s.pending);
     const snapshot = this.snapshot;
     if (this.closed || !slot || !snapshot) return Promise.reject(new HttpError(503, 'Function capacity unavailable'));
     const id = randomUUID();
+    const { entry, chain = [] } = invocation;
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         slot.pending = null; slot.ready = false;
@@ -154,8 +191,8 @@ export class FunctionPool {
         if (message.nativeBody && native) resolve({...message,body:native.body,...(native.contentLength === undefined ? {} : {contentLength:native.contentLength})});
         else resolve(message);
       }, reject };
-      const message                        = { id, source: route.function ? snapshot.names.get(route.function.source) : undefined, name: route.function?.export,
-        chain: (route.middleware || []).map(item => ({source:snapshot.names.get(item.source),name:item.export})),
+      const message                        = { id, source: entry ? snapshot.names.get(entry.source) : undefined, name: entry?.export,
+        chain: chain.map(item => ({source:snapshot.names.get(item.source),name:item.export})),
         native: native ? {status:native.status,headers:native.headers} : undefined,
         request, context, maxBytes: this.maxBytes, timeoutMs:this.timeoutMs + 100 };
       slot.worker.postMessage(message);
@@ -172,3 +209,37 @@ export class FunctionPool {
     await Promise.all(this.slots.map(s => s?.worker.terminate()));
   }
 }
+// Thin, route-shaped wrapper over `SandboxPool`: every existing internal
+// caller (route-level `function`/`middleware` dispatch, `src/runtime.ts`)
+// keeps working exactly as before, translating `FunctionRoute[]`/`FunctionRoute`
+// into the generalized `{source, export}` entries/target shape at the edge,
+// never duplicating worker spawning, module allowlisting or deadline
+// enforcement — that all still lives in the wrapped `SandboxPool`. Composition
+// rather than inheritance because `execute()`'s route-shaped and
+// entries-shaped parameters are genuinely different, incompatible types; the
+// fields/methods below the constructor exist only so the (unchanged) test
+// suite and `src/runtime.ts` keep reaching the wrapped pool's own state
+// exactly as they did before this file had two classes.
+export class FunctionPool {
+  routes                 ;         pool             ;
+  constructor(routes                 , options                      = {}) {
+    this.routes = routes;
+    this.pool = new SandboxPool(routes.flatMap(routeFunctions), options);
+  }
+  async start()                { await this.pool.start(); return this; }
+  execute(route               , request                     , context                 , native                           )                          {
+    return this.pool.execute({ entry: route.function, chain: route.middleware }, request, context, native);
+  }
+  scheduleRespawn(index        )       { this.pool.scheduleRespawn(index); }
+  close()                { return this.pool.close(); }
+  get healthy()          { return this.pool.healthy; }
+  get restarts()                      { return this.pool.restarts; }
+  get restartTimers()                      { return this.pool.restartTimers; }
+  get slots()                       { return this.pool.slots; }
+  get size()         { return this.pool.size; }
+  get closed()          { return this.pool.closed; }
+  get snapshot()                              { return this.pool.snapshot; }
+  get log()        { return this.pool.log; }
+  get timeoutMs()         { return this.pool.timeoutMs; }
+  get maxBytes()         { return this.pool.maxBytes; }
+}

package/dist/guest-api.js

@@ -5,7 +5,7 @@
 /** The request the guest receives (stringified as JSON in the worker). */
                                                                                                                           
 /** What the guest returns as JSON text; the worker enforces this shape before trusting it. */
-                                                                                                                   
+                                                                                                                                           
 // Runs only inside QuickJS/WASM. No native host functions or objects are exposed.
 // This is the documented text/JSON subset, not a complete Fetch implementation.
 export const guestBootstrap = String.raw`
@@ -13,6 +13,24 @@ export const guestBootstrap = String.raw`
   const NativeJSON = JSON;
   const stringify = JSON.stringify.bind(JSON);
   const now = Date.now.bind(Date);
+  // The guest has no TextEncoder/Buffer; this counts the UTF-8 bytes a
+  // Response's text would occupy on the wire (matching Buffer.byteLength on
+  // the host side, including its handling of lone surrogates as U+FFFD),
+  // without pulling any Node capability into the sandbox (#144).
+  function byteLength(text) {
+    let bytes = 0;
+    for (let i = 0; i < text.length; i++) {
+      const code = text.charCodeAt(i);
+      if (code >= 0xd800 && code <= 0xdbff) {
+        const next = text.charCodeAt(i + 1);
+        if (next >= 0xdc00 && next <= 0xdfff) { bytes += 4; i++; continue; }
+        bytes += 3; continue;
+      }
+      if (code >= 0xdc00 && code <= 0xdfff) { bytes += 3; continue; }
+      bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : 3;
+    }
+    return bytes;
+  }
   const timers = new Map(); let next = 1;
   globalThis.setTimeout = (fn, delay = 0) => {
     if (typeof fn !== 'function' || timers.size >= 128) throw new Error('Timer limit');
@@ -94,8 +112,14 @@ export const guestBootstrap = String.raw`
       const response = await dispatch(0);
       if (violated || !(response instanceof Response)) throw new TypeError('Invalid middleware response');
       const nativeBody = response === nativeResponse;
+      const isHead = input.request.method === 'HEAD';
+      // The real length is already known "for free": _text is a fully
+      // materialized string at construction time, no stream read needed
+      // (#144, mirroring #139's fix for the trusted path). Only the
+      // transmitted bytes are suppressed for HEAD, never the length.
       globalThis.__output = stringify({status:response.status,headers:response.headers._pairs,
-        body:nativeBody || input.request.method === 'HEAD' ? '' : response._text,nativeBody});
+        body:nativeBody || isHead ? '' : response._text,nativeBody,
+        ...(isHead && !nativeBody ? {contentLength:byteLength(response._text)} : {})});
       globalThis.__state = 'done';
     } catch { globalThis.__state = 'failed'; }
   };
@@ -106,7 +130,9 @@ export const guestBootstrap = String.raw`
       const response = await handler(new Request(input.request.url, input.request), input.context);
       if (!(response instanceof Response)) throw new TypeError('Return a Response');
       const headers = response.headers._pairs;
-      globalThis.__output = stringify({status:response.status,headers,body: input.request.method === 'HEAD' ? '' : response._text});
+      const isHead = input.request.method === 'HEAD';
+      globalThis.__output = stringify({status:response.status,headers,body: isHead ? '' : response._text,
+        ...(isHead ? {contentLength:byteLength(response._text)} : {})});
       globalThis.__state = 'done';
     } catch { globalThis.__state = 'failed'; }
   };

package/dist/index.js

@@ -1,13 +1,8 @@
 export { createRuntime } from './runtime.js';
-                                                                                                                                                        
+                                                                                                                          
 export { startServer } from './server.js';
                                                          
 export { loadDocument, validateDocument, parseYaml } from './config.js';
-export {openLinkStore} from './link-store.js';
-                                                                          
-export {startLinkApi} from './link-api.js';
-                                                           
-                                                                                        
 export { events as observabilityEvents, validateObservers, createObserverSink, createMetrics, renderPrometheus } from './observability.js';
 
 export { getCapabilities, routeCapabilities, analyzeProjectCapabilities, analyzeCompiledCapabilities, assertTargetCompatibility, normalizeCapabilityTarget } from './capabilities.js';
@@ -39,6 +34,8 @@ export {normalizeMatch, assertDisjointMatches, matchesRoute} from './conditions.
 
 export {buildCloudflare} from './build-cloudflare.js';
                                                                                                                         
+export {buildStatic} from './build-static.js';
+                                                                                                                                                                            
 export {runProjectTests} from './project-tests.js';
                                                                               
 export {scaffoldProject} from './scaffold.js';

package/dist/manifest.js

@@ -15,9 +15,14 @@ import {explainCompiledRoute} from './explain.js';
 // checked in as a source of truth, and it is deterministic: the same project
 // yields the same bytes. Nothing in it is a binding value or source text.
 
-export const MANIFEST_SCHEMA_VERSION=1;
+// Bumped to 3 when `sandbox`/`sandboxReason` moved from the `function` handler
+// record to the route, so a middleware-only route reports its execution mode too.
+export const MANIFEST_SCHEMA_VERSION=3;
                                 
                                                                                                                                                
+                                                                                        
+                                                                  
+                                         
                                                                                                                                             
                                                                                                        
                                                                                                              
@@ -30,7 +35,7 @@ export const MANIFEST_SCHEMA_VERSION=1;
                                                                            
                                                                                                           
                              
-                                                                                                                                                 
+                                                                                                        
                                                           
                                                                       
  
@@ -61,14 +66,13 @@ export async function buildManifest(project       ,options               ={})
   const explanations=routes.map(route=>explainCompiledRoute(loaded,route,chains.get(route.pattern),{projectSha256,now:0})).sort((a,b)=>compare(a.path,b.path));
   const functions=new Map                       (),middleware=new Map                       ();
   const register=(table                           ,source       ,name       ,path       )=>{const key=`${source}#${name}`;const entry=table.get(key)??{source,export:name,routes:[]};entry.routes.push(path);table.set(key,entry);};
-  const env=new Set        (),secrets=new Set        (),proxy=new Set        (),signals=new Set        (),linkStores=new Set        ();
+  const env=new Set        (),secrets=new Set        (),proxy=new Set        (),signals=new Set        ();
   const manifestRoutes                =[];
   for(const explanation of explanations){
     const declared=loaded.routes[explanation.path];
     const routeEnv=sorted(Object.values(declared?.env??{}).flatMap(ref=>ref.env?[ref.env]:[])),routeSecrets=sorted(Object.values(declared?.secrets??{}).map(ref=>ref.secret));
     for(const name of routeEnv)env.add(name);for(const name of routeSecrets)secrets.add(name);
     if(declared?.proxy)proxy.add(origin(declared.proxy.url));for(const signal of declared?.signals??[])signals.add(origin(signal.url));
-    if(declared?.link)linkStores.add(declared.link.collection);
     if(explanation.handler.kind==='function')register(functions,explanation.handler.source          ,explanation.handler.export          ,explanation.path);
     for(const item of explanation.middleware)register(middleware,item.source,item.export,explanation.path);
     const extensions                                      ={};
@@ -78,6 +82,7 @@ export async function buildManifest(project       ,options               ={})
     manifestRoutes.push({
       path:explanation.path,methods:explanation.methods,handler:explanation.handler,enabled:explanation.enabled,
       ...(explanation.expires?{expires:explanation.expires}:{}),...(explanation.generated?{generated:explanation.generated}:{}),...(explanation.description?{description:explanation.description}:{}),
+      sandbox:explanation.sandbox,...(explanation.sandboxReason?{sandboxReason:explanation.sandboxReason}:{}),
       middleware:explanation.middleware,parameters:explanation.inputs.parameters,...(explanation.inputs.body?{body:explanation.inputs.body}:{}),
       policies:explanation.policies.names,extensions,cache:explanation.cache,bindings:{env:routeEnv,secrets:routeSecrets},egress:explanation.egress,
       capabilities:explanation.capabilities,targets,
@@ -91,17 +96,16 @@ export async function buildManifest(project       ,options               ={})
       protectedRoutes:sorted(Object.entries(loaded.routes).filter(([,route])=>Object.hasOwn(effectiveExtensionPolicies(loaded.document,route),name)).map(([path])=>path))};
   }
   const targets={}                       ;
-  for(const target of capabilityTargets){const report=analyzeCompiledCapabilities(loaded.document,compiled,target);targets[target]={compatible:report.compatible,issues:report.issues.length};}
+  for(const target of capabilityTargets){const report=analyzeCompiledCapabilities(loaded.document,compiled,target,options.extensions);targets[target]={compatible:report.compatible,issues:report.issues.length};}
   const capabilities=new Set                ();
   for(const route of routes)for(const capability of routeCapabilities(route,loaded.document))capabilities.add(capability);
-  if(loaded.document.dynamicLinks)capabilities.add('dynamicLinks');
   const modules=(table                           )=>[...table.values()].map(entry=>({...entry,routes:sorted(entry.routes)})).sort((a,b)=>compare(a.source,b.source)||compare(a.export,b.export));
   return {
     schemaVersion:MANIFEST_SCHEMA_VERSION,urlcode:packageVersion,entry:'urlcode.yaml',
     files:loaded.files.map(file=>relative(loaded.root,file).split('\\').join('/')),
     revision:projectSha256,configVersion:loaded.version,routeCount:manifestRoutes.length,routes:manifestRoutes,
     capabilities:[...capabilities].sort(compare),extensions:extensionDeclarations,recipes:await recipeProvenance(loaded.root),
-    external:{env:sorted(env),secrets:sorted(secrets),egress:{proxy:sorted(proxy),signals:sorted(signals)},extensions:Object.keys(extensionDeclarations),linkStores:sorted(linkStores),dynamicLinks:loaded.document.dynamicLinks===true},
+    external:{env:sorted(env),secrets:sorted(secrets),egress:{proxy:sorted(proxy),signals:sorted(signals)},extensions:Object.keys(extensionDeclarations)},
     functions:modules(functions),middleware:modules(middleware),targets,
   };
 }

package/dist/mcp-authoring.js

@@ -17,8 +17,8 @@ import {assert} from './errors.js';
  * Authoring tools for `urlcode mcp --allow-authoring`. Every write lands inside
  * the operator-selected project root (after realpath), through the existing
  * authoring, recipe and scaffold paths. Nothing here reads bindings, creates
- * grants, deploys, or touches operator policy, compliance rules, host files or
- * link stores. The runners spawn the CLI against the same root only.
+ * grants, deploys, or touches operator policy, compliance rules or host files.
+ * The runners spawn the CLI against the same root only.
  */
 const text={type:'string',maxLength:1024};
 const handler={anyOf:[{type:'string',maxLength:2048},{type:'object'}]};

package/dist/mcp.js

@@ -78,7 +78,7 @@ export async function serveMcp(options           )               {
   if(message.method==='initialize') {
    if(initialized){await error(id,-32600,'Already initialized');return;}
    if(typeof params.protocolVersion!=='string'||!object(params.capabilities)||!object(params.clientInfo)||typeof params.clientInfo.name!=='string'||typeof params.clientInfo.version!=='string'){await error(id,-32602,'Invalid initialize params');return;}
-   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.0-alpha.1'}}});return;
+   initialized=true;await send({jsonrpc:'2.0',id,result:{protocolVersion,capabilities:{tools:{}},serverInfo:{name:'urlcode',version:'0.4.0-alpha.3'}}});return;
   }
   if(message.method==='ping'){await send({jsonrpc:'2.0',id,result:{}});return;}
   if(!ready){await error(id,-32002,'Initialize first');return;}

package/dist/observability.js

@@ -17,12 +17,8 @@ export const events = Object.freeze({
   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']),
@@ -47,10 +43,8 @@ export const events = Object.freeze({
                                                                        
                                                                                                                    
                                                                                               
-                                                          
                                                                       
                     
-                                                                            
                                                      
                            
  
@@ -85,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]));
 
@@ -108,11 +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 signals = zeroed(['accepted','delivered','failed','dropped']);
-  const linkObserver = { failed: 0, dropped: 0 };
   let logsDropped = 0, observerErrors = 0;
   const count = (table          , key         )       => { if (typeof key === 'string' && Object.hasOwn(table, key)) table[key] ++; };
   function countRequest(target                 , status         , route         )       {
@@ -137,10 +127,7 @@ export function createMetrics()          {
         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;
@@ -160,11 +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 } },
         signals: {...signals},
-        linkRequests: { ...linkRequests },
-        linkObserver: { ...linkObserver },
         logsDropped,
         observers: { errors: observerErrors },
         ...extra,
@@ -231,14 +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('signals_total','counter','Best-effort webhook outcomes.',Object.entries(snapshot.signals||{}).map(([outcome,value])=>[{outcome},value]));
-  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('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/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]];