@jimhoyd/urlcode 0.4.0-alpha.1 → 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/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/extensions.d.ts

@@ -6,11 +6,23 @@ export interface ExtensionDeclaration {
     config: Record<string, unknown>;
 }
 export type ExtensionPolicies = Record<string, Record<string, unknown> | false>;
+/**
+ * `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()`.
+ */
 export interface ExtensionActivation {
     origin: string;
     target: TargetName;
     projectSha256: string;
     mounts: readonly string[];
+    root: string;
 }
 export interface ExtensionRequest {
     method: string;
@@ -28,6 +40,20 @@ export interface ExtensionRequest {
 export interface ExtensionInstance {
     handle(request: ExtensionRequest): HandlerResult | Promise<HandlerResult>;
     authorize?(requirement: Readonly<Record<string, unknown>>, request: ExtensionRequest): HandlerResult | undefined | Promise<HandlerResult | undefined>;
+    /**
+     * Wrap semantics, not gate semantics: attached the same way as `authorize`
+     * (policies.extensions.<name> on a route, `config` the same validated
+     * per-route value `authorize`'s `requirement` receives), but given `next`,
+     * a callable invoking the rest of the pipeline for this route (any other
+     * declared extension `middleware()` after this one, then the route's own
+     * native `middleware:` chain and handler) at most once. Calling it lets
+     * this hook run code before and after the rest of the pipeline, inspecting
+     * or mutating the `HandlerResult` it resolves to; skipping it short-circuits
+     * the rest of the pipeline entirely, the same way `authorize` can. Never
+     * touches the native `middleware:` array or its own sandboxed/trusted
+     * dispatch, and never runs before `authorize` on the same route.
+     */
+    middleware?(config: Readonly<Record<string, unknown>>, request: ExtensionRequest, next: () => Promise<HandlerResult>): HandlerResult | Promise<HandlerResult>;
     close?(): void | Promise<void>;
 }
 /** Trusted operator code only. YAML declares names/configuration, never modules. */
@@ -49,6 +75,23 @@ export interface RuntimeExtension {
     policySchema?: object;
     credentialHeaders?: string[];
     immutableAssets?: ExtensionImmutableAssets;
+    /**
+     * Reviewed, operator-declared cache sensitivity for `policies.extensions.<name>`
+     * routes (never for an `extension:` mount, which is always treated as
+     * sensitive). Omitted or `true`: the current, safe default — the runtime
+     * forces `Cache-Control: no-store`, disables compression and applies the
+     * extension response's header/size caps, exactly like `authorize`-gating
+     * auth/admin extensions. `false` is an explicit, reviewed opt-in a generic,
+     * cache-transparent extension (pure request/response middleware with no
+     * gating semantics of its own, like `urlcode-middleware`) makes to say its
+     * `middleware()` hook never depends on withholding the response from
+     * shared caches: the wrapped route's own declared cache headers pass
+     * through unchanged, exactly as the native `middleware:` array already
+     * does. A route naming more than one extension is treated as sensitive if
+     * any of them is (or leaves this unset) — this can only relax the no-store
+     * floor, never weaken it, and it never changes whether `authorize()` runs.
+     */
+    cacheSensitive?: boolean;
     activate(config: Readonly<Record<string, unknown>>, context: ExtensionActivation): ExtensionInstance | Promise<ExtensionInstance>;
 }
 /** `urlcode init --with <name>` contract: what core hands `@jimhoyd/urlcode-<name>`'s `scaffold` export. Nothing is written by `scaffold`. */
@@ -107,6 +150,18 @@ export declare const immutableCacheControl = "public, max-age=31536000, immutabl
 export declare function inspectExtensionRevision(project: string): Promise<string>;
 export declare function effectiveExtensionPolicies(document: ProjectDocument, route: Pick<RouteConfig, 'policies'>): Record<string, Record<string, unknown>>;
 export declare function hasExtensionPolicy(document: ProjectDocument, route: Pick<RouteConfig, 'policies'>): boolean;
+/**
+ * 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 declare function isSensitiveExtensionPolicy(names: readonly string[], registrations?: readonly Pick<RuntimeExtension, 'name' | 'cacheSensitive'>[]): boolean;
 export declare function prepareExtensions(document: ProjectDocument, routes: Record<string, RouteConfig>, registrations: RuntimeExtension[] | undefined, context: Omit<ExtensionActivation, 'mounts'>): {
     activate(): Promise<ExtensionRegistry>;
 };

package/dist/types/function-sources.d.ts

@@ -23,4 +23,8 @@ export declare const MODULE_LIMIT = 128;
 export declare const MODULE_BYTE_LIMIT = 1048576;
 export declare const TOTAL_BYTE_LIMIT = 4194304;
 export declare function routeFunctions<D>(route: FunctionRoute<D>): D[];
+export declare function collectTrustedSources(routes: FunctionRoute[], root: string): Promise<Record<string, string>>;
+export declare function collectSourcesFor(definitions: FunctionDefinition[], root: string): Promise<FunctionSources>;
+/** Route-shaped convenience over `collectSourcesFor`: every existing caller (policy.ts,
+ * prerender.ts, typescript-authoring.ts) keeps working unchanged from `FunctionRoute[]`. */
 export declare function collectFunctionSources(routes: FunctionRoute[], root: string): Promise<FunctionSources>;