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

package/dist/scripts/operational-drills.js

@@ -1,75 +1,33 @@
 // Disposable local proof, never a claim about the production deployment.
 import assert from 'node:assert/strict';
-import {mkdtemp,mkdir,writeFile,copyFile,rm,statfs} from 'node:fs/promises';
+import {mkdtemp,mkdir,writeFile,rm} from 'node:fs/promises';
 import {tmpdir} from 'node:os';
-import {join,resolve} from 'node:path';
-import {DatabaseSync} from 'node:sqlite';
-import {openLinkStore} from '../link-store.js';
+import {join} from 'node:path';
 import {startServer} from '../server.js';
-                                                    
                                              
-import {HttpError} from '../errors.js';
-// The SQLite rows the drills inspect; node:sqlite returns untyped records.
-                                                                         
-                                                
-                                        
-                              
-// node:sqlite boundary: a single-row query, typed by the caller's expectation.
-const row=   (db              ,sql        )   =>{const r=db.prepare(sql).get();assert.ok(r,`${sql} returned no row`);return r                ;};
+
 const seconds=Number(process.env.URLCODE_SOAK_SECONDS||5);
 assert(Number.isInteger(seconds)&&seconds>=1&&seconds<=3600,'Soak must be 1–3600 seconds');
 const directory=await mkdtemp(join(tmpdir(),'urlcode-drills-')),project=join(directory,'app');
-let store                     ,app                  ;
+let app                  ;
 try {
  await mkdir(project);
- const config='version: "1"\ndynamicLinks: true\nroutes:\n  /go:\n    redirect: {url: "https://example.com/v1"}\n  /function:\n    function: {source: f.mjs}\n  /live/{code}:\n    parameters:\n      - {name: code, in: path, required: true, schema: {type: string}}\n    link: {collection: links, code: {from: path, name: code}}\n';
+ const config='version: "1"\nroutes:\n  /go:\n    redirect: {url: "https://example.com/v1"}\n  /function:\n    function: {source: f.mjs}\n';
  await writeFile(join(project,'urlcode.yaml'),config);
  await writeFile(join(project,'f.mjs'),'export default () => new Response("isolated");');
- const file=join(directory,'links.sqlite');
- store=await openLinkStore({file,project});let link=await store.create('links',{url:'https://example.com/live'},'demo');
- app=await startServer({project,port:0,linkStore:{collection:'links',file},log:()=>{}});
+ app=await startServer({project,port:0,log:()=>{}});
  const server=app;
  const get=async(path        )=>{const r=await fetch(`http://127.0.0.1:${server.address.port}${path}`,{redirect:'manual'});const body=await r.text();return {status:r.status,location:r.headers.get('location'),body};};
  const start=performance.now(),samples          =[];let requests=0;
  while(performance.now()-start<seconds*1000){
-   const before=performance.now();const responses=await Promise.all(['/go','/function','/live/demo'].map(get));
-   assert.deepEqual(responses.map(r=>r.status),[302,200,302]);assert.equal(responses[1]?.body,'isolated');
-   assert.equal(responses[2]?.location,link.url);samples.push(performance.now()-before);requests+=3;
-   if(requests%30===0)link=await store.update('links','demo',{url:`https://example.com/live-${requests}`},link.version);
+   const before=performance.now();const responses=await Promise.all(['/go','/function'].map(get));
+   assert.deepEqual(responses.map(r=>r.status),[302,200]);assert.equal(responses[1]?.body,'isolated');
+   samples.push(performance.now()-before);requests+=2;
  }
  await writeFile(join(project,'urlcode.yaml'),'invalid: configuration');assert.equal(await app.reload(),false);assert.equal((await get('/go')).location,'https://example.com/v1');
  await writeFile(join(project,'urlcode.yaml'),config.replace('/v1','/v2'));assert.equal(await app.reload(),true);assert.equal((await get('/go')).location,'https://example.com/v2');
  await writeFile(join(project,'urlcode.yaml'),config);assert.equal(await app.reload(),true);assert.equal((await get('/go')).location,'https://example.com/v1');
- await app.close();app=undefined;await store.close();store=undefined;
- // A read-only connection may have been the last to close, leaving WAL frames.
- // Quiesce all users, explicitly checkpoint, then close before copying.
- const checkpointDb=new DatabaseSync(file);
- try{const result=row               (checkpointDb,'PRAGMA wal_checkpoint(TRUNCATE)');assert.equal(result.busy,0);assert.equal(result.log,0);assert.equal(result.checkpointed,0);}finally{checkpointDb.close();}
- const restoreStart=performance.now(),backup=join(directory,'restored.sqlite');await copyFile(file,backup);
- store=await openLinkStore({file:backup,project,readOnly:true});assert.deepEqual(await store.get('links','demo'),link);
- const db=new DatabaseSync(backup,{readOnly:true});assert.equal(row              (db,'PRAGMA integrity_check').integrity_check,'ok');assert.equal(row             (db,'SELECT max(revision) AS revision FROM urlcode_link_audit').revision,link.version);db.close();
+ await app.close();app=undefined;
  samples.sort((a,b)=>a-b);
- console.log(JSON.stringify({event:'local-operational-proof',seconds,requests,batchP99Ms:samples[Math.floor(samples.length*.99)],rssBytes:process.memoryUsage().rss,restoreMs:performance.now()-restoreStart,checks:['mixed HTTP load','invalid reload preserves last-good','configuration rollback','quiesced backup/restore including audit'],deploymentProof:false}));
- await store.close();store=undefined;
- // Only enable inside a disposable, size-limited mount (CI uses 16 MiB tmpfs).
- if(process.argv[2]==='--disk-full-dir'){
-   const volume=resolve(process.argv[3] ?? '');const isolated=await mkdtemp(join(volume,'urlcode-full-'));
-   try {
-     const reserve=join(isolated,'reserve');await writeFile(reserve,Buffer.alloc(4*1024*1024));
-     const fullFile=join(isolated,'full.sqlite');store=await openLinkStore({file:fullFile,project});let full=false,committed=0;
-     for(let i=0;i<12000;i++){
-       try{await store.create('links',{url:'https://example.com/'+ 'x'.repeat(7000)},'code-'+i);committed++;}
-       catch(error){assert.ok(error instanceof HttpError,'store failure must be an HttpError');assert.equal(error.status,503);full=true;break;}
-     }
-     assert(full,'Disposable volume did not fill within the 84 MiB write budget');
-     const space=await statfs(isolated);assert(space.bavail*space.bsize<1024*1024,'Expected actual volume exhaustion');
-     await rm(reserve);await store.create('links',{url:'https://example.com/recovered'},'recovered');committed++;
-     await store.close();store=undefined;
-     const check=new DatabaseSync(fullFile,{readOnly:true});
-     assert.equal(row              (check,'PRAGMA integrity_check').integrity_check,'ok');
-     assert.equal(row          (check,'SELECT count(*) AS n FROM urlcode_links').n,committed);
-     assert.equal(row          (check,'SELECT count(*) AS n FROM urlcode_link_audit').n,committed);check.close();
-     console.log(JSON.stringify({event:'disposable-volume-exhaustion',committed,integrity:'ok',auditAtomic:true}));
-   }finally{await store?.close();store=undefined;await rm(isolated,{recursive:true,force:true});}
- }
-} finally {await app?.close();await store?.close();await rm(directory,{recursive:true,force:true});}
+ console.log(JSON.stringify({event:'local-operational-proof',seconds,requests,batchP99Ms:samples[Math.floor(samples.length*.99)],rssBytes:process.memoryUsage().rss,checks:['mixed HTTP load','invalid reload preserves last-good','configuration rollback'],deploymentProof:false}));
+} finally {await app?.close();await rm(directory,{recursive:true,force:true});}

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/tooling.js

@@ -44,7 +44,7 @@ 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');
+ 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               ={}) {

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/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/capabilities.d.ts

@@ -1,9 +1,12 @@
+import type { RuntimeExtension } from './extensions.ts';
 import type { CompiledRoute, CompiledRouteTable, LoadedDocument, PolicySupport, ProjectDocument, RouteConfig } from './types.ts';
-export declare const capabilityTargets: readonly ["self-hosted", "cloudflare", "aws", "vercel"];
+export declare const capabilityTargets: readonly ["self-hosted", "cloudflare", "aws", "vercel", "static"];
 export type CapabilityTarget = typeof capabilityTargets[number];
 export type CapabilitySupport = PolicySupport | 'conditional' | 'unknown';
-export declare const capabilityNames: readonly ["extension", "policies.extensions", "proxy", "signals", "conditional", "conditions", "redirect", "respond", "page", "static", "download", "function", "middleware", "link", "dynamicLinks", "parameters", "methods", "enabled", "expires", "request.body", "response.headers", "bindings", "policies.agents", "policies.security", "policies.cache", "policies.compression", "policies.throttle"];
+export declare const capabilityNames: readonly ["extension", "policies.extensions", "proxy", "signals", "conditional", "conditions", "redirect", "respond", "page", "static", "download", "function", "middleware", "parameters", "methods", "enabled", "expires", "request.body", "response.headers", "bindings", "policies.agents", "policies.security", "policies.cache", "policies.compression", "policies.throttle"];
 export type CapabilityName = typeof capabilityNames[number];
+/** The resolved operator registration set, when known (loaded via --host-file, same as `inspectExtensions`). Keyed by extension name. */
+export type ExtensionRegistry = ReadonlyMap<string, RuntimeExtension>;
 export interface CapabilityDecision {
     support: CapabilitySupport;
     reason: string;
@@ -35,10 +38,16 @@ export declare function normalizeCapabilityTarget(target: string): CapabilityTar
 export declare function getCapabilities(target?: string): CapabilityCatalog;
 /** A safe projection shared by declaration preflight and the existing compiled IR. No values escape. */
 export declare function routeCapabilities(route: RouteConfig | CompiledRoute, document: ProjectDocument): CapabilityName[];
-/** Preflight only: call after schema validation/site expansion, before resolving bindings. */
-export declare function analyzeProjectCapabilities(loaded: LoadedDocument, target: string): CompatibilityReport;
+/**
+ * Preflight only: call after schema validation/site expansion, before resolving bindings.
+ * `registrations` is the resolved operator extension set, when known (the same
+ * shape --host-file loads for `inspectExtensions`); without it, `extension`/
+ * `policies.extensions` requirements report `conditional`/`unknown` rather
+ * than a blanket `native` that ignores the specific extension's own targets.
+ */
+export declare function analyzeProjectCapabilities(loaded: LoadedDocument, target: string, registrations?: readonly RuntimeExtension[]): CompatibilityReport;
 /** Analyze normalized route semantics without exporting validators, resources or resolved secrets. */
-export declare function analyzeCompiledCapabilities(document: ProjectDocument, compiled: CompiledRouteTable, target: string): CompatibilityReport;
+export declare function analyzeCompiledCapabilities(document: ProjectDocument, compiled: CompiledRouteTable, target: string, registrations?: readonly RuntimeExtension[]): CompatibilityReport;
 export declare function assertTargetCompatibility(report: CompatibilityReport): void;
 export declare function formatCapabilities(catalog: CapabilityCatalog): string;
 export type CapabilityKind = 'handler' | 'policy' | 'routing' | 'request' | 'binding' | 'egress' | 'middleware' | 'project';

package/dist/types/compliance-rules/shared.d.ts

@@ -7,8 +7,6 @@ export declare const rfc6585: Standard;
 export declare const rfc9309: Standard;
 export declare const breach: Standard;
 export declare const monitoring: Standard;
-export declare const linkChannel: Standard;
-export declare const management: Standard;
 export declare const agentLists: Standard;
 export declare const active: (route: PlanInventoryEntry) => boolean;
 export declare const functionLike: (route: PlanInventoryEntry) => boolean;

package/dist/types/compliance.d.ts

@@ -27,8 +27,6 @@ export type RuleResult = RawFinding[] | RawFinding | null | undefined | false;
 /** The host settings under review, null where the operator declared nothing. */
 export interface HostSettings {
     requestLog: 'minimal' | 'detailed' | null;
-    linkEvents: boolean | null;
-    includeCode: boolean | null;
 }
 export interface ProjectContext {
     document: ProjectDocument;
@@ -92,7 +90,6 @@ export interface ComplianceReport {
     evidence: {
         routes: number;
         active: number;
-        dynamicLinks: boolean;
         policies: string[];
         files: string[];
         origin: string | null;

package/dist/types/config.d.ts

@@ -20,7 +20,8 @@ export declare const SHORT_FORM_PATH_SCHEMA: {
 /**
  * Expands the YAML short forms into the canonical long form. `function: functions/x.mjs`
  * becomes `{source, args}` with an argument per `{param}` in the path, declaring any
- * parameter the route does not declare itself; a string middleware entry becomes `{source}`.
+ * parameter the route does not declare itself; a string middleware entry becomes `{source}`;
+ * a route-level `cache` becomes `policies.cache` (refused alongside a direct `policies.cache`).
  * Everything downstream (routes, audit, the compiled table) sees only the long form.
  */
 export declare function normalizeRoute(pattern: string, route: AuthoredRouteConfig | RouteConfig): RouteConfig;

package/dist/types/context.d.ts

@@ -25,7 +25,6 @@ export interface ProjectContext {
             env: string[];
             secrets: string[];
         };
-        dynamicLinks: boolean;
         site: string[];
         files?: {
             includes: string[];
@@ -41,6 +40,8 @@ export interface ProjectContext {
         path: string;
         methods: string[];
         handler: string;
+        sandbox: boolean;
+        sandboxReason?: string;
     }[];
     constraints: Record<string, boolean | string | {
         value: boolean | string;

package/dist/types/examples.d.ts

@@ -31,7 +31,7 @@ export interface ExampleSearchResult {
         matchedRoutes: RouteIndexEntry[];
     })[];
 }
-export declare const exampleNames: readonly ["assets", "aws", "cloudflare", "compliance", "conditions", "cookbook", "egress", "extensions", "live-links", "monitoring", "prerender", "provider-conformance", "tunnel", "vercel"];
+export declare const exampleNames: readonly ["assets", "aws", "cloudflare", "compliance", "conditions", "cookbook", "egress", "extensions", "monitoring", "prerender", "provider-conformance", "tunnel", "vercel"];
 export declare const routeIndexFile = "route-index.json";
 export declare function listExamples(): Promise<ExampleSummary[]>;
 /**

package/dist/types/explain.d.ts

@@ -55,6 +55,12 @@ export interface RouteExplanation {
         source: string;
         export: string;
     }[];
+    /** Execution mode for this route's whole `function`/`middleware` chain: `true` for the
+     * QuickJS sandbox, `false` for trusted in-process execution. Route-level, not handler-level:
+     * a native handler with `middleware` runs project code too, and its mode has to be reviewable.
+     * Reported for every route, including those that run no project code at all. */
+    sandbox: boolean;
+    sandboxReason?: string;
     inputs: {
         parameters: ExplainedParameter[];
         body?: RequestBodyPolicy;