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

package/dist/explain.js

@@ -29,6 +29,11 @@ const handlerNames=['extension','proxy','conditional','redirect','function','pag
                                    
                                                                                                                         
                                                                                                               
+                                                                                         
+                                                                                               
+                                                                                                 
+                                                                                  
+                                         
                                                                    
                                                                                                               
                        
@@ -52,7 +57,7 @@ function handlerOf(route              ,root       )                  {
       return {kind,cases:(route.conditionalRoutes?.cases??[]).map(item=>({match:item.match,...branch(item.route)})),...(route.conditionalRoutes?.fallback?{fallback:branch(route.conditionalRoutes.fallback)}:{})};
     }
     case 'redirect':return {kind,url:route.redirect .url,status:route.redirect .status??302,...(route.redirect .query?{query:route.redirect .query}:{})};
-    case 'function':return {kind,source:relativeSource(root,route.function .source),export:route.function .export,...(route.function .args?{args:route.function .args}:{}),sandbox:route.sandbox===true,...(route.sandboxReason?{sandboxReason:route.sandboxReason}:{})};
+    case 'function':return {kind,source:relativeSource(root,route.function .source),export:route.function .export,...(route.function .args?{args:route.function .args}:{})};
     case 'page':return {kind,file:route.page .file,...(route.page .contentType?{contentType:route.page .contentType}:{})};
     case 'static':return {kind,directory:route.static .directory,...(route.static .index?{index:route.static .index}:{})};
     case 'download':return {kind,file:route.download .file,...(route.download .filename?{filename:route.download .filename}:{}),...(route.download .contentType?{contentType:route.download .contentType}:{})};
@@ -110,6 +115,7 @@ export function explainCompiledRoute(loaded               ,route              ,c
     state:routeState(route,options.now??Date.now()),enabled:route.enabled!==false,...(route.expires?{expires:route.expires}:{}),
     methods:[...route.methods],conditional:Boolean(route.match||route.conditional),handler,
     middleware:route.middleware.map(item=>({source:relativeSource(root,item.source),export:item.export})),
+    sandbox:route.sandbox===true,...(route.sandboxReason?{sandboxReason:route.sandboxReason}:{}),
     inputs:{parameters:route.parameters.map(({name,in:location,required,schema})=>({name,in:location,required,schema})),...(route.request?.body?{body:route.request.body}:{})},
     policies:{names,inventory,extensions},
     cache:cacheOf(route,chain,extensionNames),

package/dist/extensions.js

@@ -63,7 +63,7 @@ import { validateHeaderName, validateHeaderValue } from './header-validation.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=2;
+// 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;
                                 
                                                                                                                                                
+                                                                                        
+                                                                  
+                                         
                                                                                                                                             
                                                                                                        
                                                                                                              
@@ -77,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,

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.2'}}});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/policies.js

@@ -9,7 +9,9 @@ import { assert, ConfigError } from './errors.js';
                                                                                                                                                                                                                                                                
                                                                                                         
 
-// Host-side behavior declared in YAML and enforced outside the sandbox. Every
+// Host-side behavior declared in YAML and enforced in the host process, outside
+// function/middleware execution entirely -- trusted routes and sandbox: true
+// routes alike. Every
 // module here follows one contract so a first-party policy and an operator
 // plugin share a code path (PolicyModule in src/types.ts):
 //

package/dist/prerender.js

@@ -102,6 +102,10 @@ async function planPasses(source        )                      {
   const cost = new Map                            ();
   for (const pattern of patterns) {
     const route = loaded.routes[pattern] ;
+    // Trusted routes use Node resolution, not the sandbox module collector.
+    // Applying guest import/size limits here would reject valid build-time Node
+    // code before the runtime can dispatch it through its declared trust mode.
+    if (route.sandbox !== true) { cost.set(pattern, []); continue; }
     const definitions = [];
     for (const definition of routeFunctions(route))
       definitions.push({function: {source: await functionFile(loaded.root, definition.source), export: definition.export || 'default'}});

package/dist/readiness.js

@@ -17,6 +17,8 @@ import { runCompliance } from './compliance.js';
 /** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
                                                             
                                    
+                                                                                     
+                   
                                                                                
                                                                                  
                         
@@ -74,6 +76,7 @@ export function projectPlan(compiled                               )
   const now = Date.now();
   const inventory                   = routes.map(route => { const advisories = routeAdvisories(route); return { path:route.pattern, handler:handlers.find(key => route[key]), methods:route.methods, middleware:route.middleware?.length || 0,
     policies:[...(route.policy ? Object.keys(route.policy.describe) : []),...(route.extensionPolicyNames??[]).map(name=>`extensions.${name}`)],
+    sandbox:route.sandbox === true, ...(route.sandboxReason ? { sandboxReason:route.sandboxReason } : {}),
     ...(route.generated ? { generated:route.generated } : {}),
     ...(advisories.length ? { advisories } : {}),
     state:route.enabled === false ? 'disabled' : route.expiresAt && now >= route.expiresAt ? 'expired' : 'active' }; });

package/dist/route-diff.js

@@ -17,7 +17,7 @@ const isStrings = (value         )                    => Array.isArray(value) &&
 function entry(value         , index        )                     {
   const fail = (what        )        => { throw new ConfigError(`Route report inventory[${index}] ${what}`); };
   if (!isRecord(value)) return fail('is not an object');
-  const { path, handler, methods, middleware, policies, generated, state } = value;
+  const { path, handler, methods, middleware, policies, generated, state, sandbox, sandboxReason } = value;
   if (typeof path !== 'string' || !path) return fail('needs a path');
   if (handler !== undefined && typeof handler !== 'string') return fail('has an invalid handler');
   if (!isStrings(methods)) return fail('needs methods');
@@ -25,7 +25,13 @@ function entry(value         , index        )                     {
   if (!isStrings(policies)) return fail('needs policies');
   if (generated !== undefined && typeof generated !== 'string') return fail('has an invalid generated marker');
   if (typeof state !== 'string' || !states.includes(state              )) return fail('needs a state');
-  return { path, handler, methods, middleware, policies, ...(generated !== undefined ? { generated } : {}), state:state               };
+  // `sandbox`/`sandboxReason` postdate the report format, so an older report
+  // omits them: absent is carried through as absent rather than defaulted to
+  // `false`, which would read as a trust change that never happened.
+  if (sandbox !== undefined && typeof sandbox !== 'boolean') return fail('has an invalid sandbox flag');
+  if (sandboxReason !== undefined && typeof sandboxReason !== 'string') return fail('has an invalid sandboxReason');
+  return { path, handler, methods, middleware, policies, ...(generated !== undefined ? { generated } : {}), state:state              ,
+    ...(sandbox !== undefined ? { sandbox } : {}), ...(sandboxReason !== undefined ? { sandboxReason } : {}) };
 }
 /** Validates a parsed `urlcode routes` JSON report (a child-process or file boundary) into a snapshot. */
 export function parseRouteSnapshot(value         )                {
@@ -71,7 +77,7 @@ export function diffRoutes(before               , after               )
 }
 export const hasRouteChanges = (diff           )          => diff.added.length + diff.removed.length + diff.changed.length > 0;
 
-const fields = ['handler','methods','state','middleware','policies','generated','policy']         ;
+const fields = ['handler','methods','state','sandbox','sandboxReason','middleware','policies','generated','policy']         ;
                                    
 const cell = (value         )         => {
   const text = value === undefined ? '' : Array.isArray(value) && value.every(item => typeof item === 'string') ? value.join(', ') : typeof value === 'string' ? value : canonical(value);
@@ -82,12 +88,13 @@ const code = (value        )         => `\`${value.replace(/\\/g, '\\\\').replac
 function table(headers          , rows            )           {
   return [`| ${headers.join(' | ')} |`, `|${headers.map(() => '---').join('|')}|`, ...rows.map(row => `| ${row.join(' | ')} |`)];
 }
-const routeRow = (record             )           => [code(record.path), cell(record.handler), cell(record.methods), cell(record.state), String(record.middleware), cell(record.policies), cell(record.generated)];
+const routeRow = (record             )           => [code(record.path), cell(record.handler), cell(record.methods), cell(record.state),
+  cell(record.sandbox), cell(record.sandboxReason), String(record.middleware), cell(record.policies), cell(record.generated)];
 /** Renders a diff as Markdown: one table per nonempty section, or "No route changes". */
 export function renderRouteDiff(diff           )         {
   if (!hasRouteChanges(diff)) return 'No route changes\n';
   const lines           = [];
-  const routeHeaders = ['Route','Handler','Methods','State','Middleware','Policies','Generated'];
+  const routeHeaders = ['Route','Handler','Methods','State','Sandbox','Sandbox reason','Middleware','Policies','Generated'];
   const section = (title        , list               ) => {
     if (!list.length) return;
     lines.push(`### ${title} (${list.length})`, '', ...table(routeHeaders, list.map(routeRow)), '');

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;

package/dist/types/extensions.d.ts

@@ -83,7 +83,7 @@ export interface RuntimeExtension {
      * 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
+     * gating semantics of its own) 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

package/dist/types/manifest.d.ts

@@ -1,7 +1,7 @@
 import type { CapabilityName, CapabilityTarget } from './capabilities.ts';
 import type { InspectOptions } from './tooling.ts';
 import type { RouteExplanation } from './explain.ts';
-export declare const MANIFEST_SCHEMA_VERSION = 2;
+export declare const MANIFEST_SCHEMA_VERSION = 3;
 export interface ManifestRoute {
     path: string;
     methods: string[];
@@ -10,6 +10,10 @@ export interface ManifestRoute {
     expires?: string;
     generated?: string;
     description?: string;
+    /** Execution mode for the route's whole `function`/`middleware` chain: `true` for the
+     * QuickJS sandbox, `false` for trusted in-process execution. */
+    sandbox: boolean;
+    sandboxReason?: string;
     middleware: {
         source: string;
         export: string;

package/dist/types/readiness.d.ts

@@ -8,6 +8,8 @@ export type HandlerName = 'extension' | 'proxy' | 'conditional' | 'redirect' | '
 /** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
 export interface RouteInventory extends PlanInventoryEntry {
     handler: HandlerName | undefined;
+    /** Always reported here, so a trust change is visible in `routes` and its diff. */
+    sandbox: boolean;
     /** Non-blocking `audit` observations about this route (e.g. a webhook-shaped
      * route with no declared `sandbox`/`sandboxReason`); never affects `ready`. */
     advisories?: string[];

package/dist/types/types.d.ts

@@ -378,7 +378,7 @@ export type PolicyChain = {
     describe: PolicyInventory;
 } & Partial<PolicyStates>;
 export type RouteState = 'active' | 'disabled' | 'expired';
-/** One route in the audit inventory: its handler kind, methods and lifecycle state. */
+/** One route in the audit inventory: its handler kind, methods, execution mode and lifecycle state. */
 export interface PlanInventoryEntry {
     path: string;
     handler: string | undefined;
@@ -387,6 +387,13 @@ export interface PlanInventoryEntry {
     policies: string[];
     generated?: string;
     state: RouteState;
+    /** The route's execution mode: `true` when its `function`/`middleware` chain runs in the
+     * QuickJS sandbox, `false` when it runs trusted in-process. Route-level, because the mode
+     * applies to the whole chain — a native handler with `middleware` has one too. Optional
+     * only at the report-parsing boundary: reports written before it existed omit it. */
+    sandbox?: boolean;
+    /** The route's declared `sandboxReason`, when it has one. */
+    sandboxReason?: string;
 }
 export interface TestPlan {
     inventory: PlanInventoryEntry[];

package/dist/types.js

@@ -199,9 +199,16 @@
 // consume it need not import the host module that produces it.
 
                                                            
-/** One route in the audit inventory: its handler kind, methods and lifecycle state. */
+/** One route in the audit inventory: its handler kind, methods, execution mode and lifecycle state. */
                                      
                                                                                                                                               
+                                                                                           
+                                                                                            
+                                                                                          
+                                                                                       
+                    
+                                                               
+                         
  
                            
                                                                                                 

package/dist/typescript-authoring.js

@@ -23,16 +23,20 @@ const SANDBOX_MODULE_LIMIT=128,SANDBOX_MODULE_BYTE_LIMIT=1048576,SANDBOX_TOTAL_B
 export async function buildTypeScriptProject(project        ,output        ,{dryRun=false}                              ={})                                 {
   const root=await realpath(project),loaded=await loadDocument(root),files=new Map                      (),modules=new Map               ();
   const {default:ts}=await import('typescript');
-  // Per-path trust, so a module visited once (recursively, from its importer)
-  // is never reprocessed under a different trust level.
-  const moduleTrust=new Map                ();
+  // Which trust levels a module has already been visited under, so a graph
+  // reachable from both a sandboxed and a trusted route is validated under each
+  // route's own rules exactly once instead of being refused outright. The
+  // module is still emitted once; `emittedBy` keeps target-name collisions
+  // between *different* sources refused.
+  const moduleTrust=new Map                     (),emittedBy=new Map               ();
   let sandboxedSourceBytes=0,sandboxedModuleCount=0,assetBytes=0;
   await init;
   async function collect(path        ,sandboxed         )                {
     authoringPath(path);assert(/\.(?:ts|js|mjs)$/.test(path) && !path.endsWith('.d.ts'),'Guest source must be .ts, .js or .mjs');
-    const seen=moduleTrust.get(path);
-    if(seen!==undefined){assert(seen===sandboxed,'Module is imported by both a sandboxed and a trusted route');return;}
-    moduleTrust.set(path,sandboxed);
+    let visited=moduleTrust.get(path);
+    if(!visited){visited=new Set();moduleTrust.set(path,visited);}
+    if(visited.has(sandboxed))return;
+    visited.add(sandboxed);
     let bytes        ;
     if(sandboxed){
       assert(sandboxedModuleCount<SANDBOX_MODULE_LIMIT,'Function module limit exceeded');sandboxedModuleCount++;
@@ -93,7 +97,14 @@ export async function buildTypeScriptProject(project        ,output        ,{dry
       }
     }
     for(const edit of edits.sort((a,b)=>b.start-a.start))code=code.slice(0,edit.start)+edit.value+code.slice(edit.end);
-    const target=emitted(path);assert(!files.has(target),'Guest output module collision');files.set(target,code);
+    // A module reachable from both trust levels is transpiled twice (once per
+    // rule set) but emitted once. The two results agree: the sandbox rules are
+    // strictly stricter, so anything the trusted pass would leave alone —
+    // bare/dynamic specifiers, `import.meta` — fails the sandboxed pass and
+    // aborts the whole build before either emission is published.
+    const target=emitted(path),previous=emittedBy.get(target);
+    assert(previous===undefined||previous===path,'Guest output module collision');
+    emittedBy.set(target,path);files.set(target,code);
   }
   for(const route of Object.values(loaded.routes))for(const definition of routeFunctions(route)){
     await collect(definition.source,!!route.sandbox);definition.source=emitted(definition.source);

package/docs/AI-AUTHORING.md

@@ -106,7 +106,7 @@ The benchmark operates locally; it is not a load test of an external deployment.
 | Parameter validation and JSON body syntax checks | Full OpenAPI or JSON Schema validation of request bodies |
 | Local test/audit/benchmark | Route-local YAML tests, managed monitoring, production load certification |
 | Local/self-hosted runtime; limited AWS/Vercel/Cloudflare implementations with local tests | Verified provider deployments or full cross-provider parity |
-| File authoring and snapshot reload | General guest storage broker; stored short links (moving to a future `urlcode-dynamic-link` extension package, not yet published) |
+| File authoring and snapshot reload | General guest storage broker; stored short links (no supported package; the `urlcode-dynamic-link` extension was retired) |
 | Optional host `policies` (`throttle`, `agents`, `security`, `compression`, `cache`) and reusable `profiles` | Plugins named in YAML, shared multi-instance counters, CORS, verified-bot checks |
 | Optional top-level `site` (`robots`, `sitemap`, `favicon`, `securityTxt`, `llms`) generating native routes | Per-route `noindex` field, sitemap index files, `humans.txt`, signed `security.txt` |
 
@@ -240,9 +240,12 @@ Put that justification where tooling can see it, not only in a source
 comment: an optional `sandboxReason` string on the route (up to 500
 characters, `schemas/urlcode.schema.json`) records why a route needs
 isolation, or why it is safe to trust, regardless of whether `sandbox` is
-`true` or `false`. `urlcode explain`/`context` surface it next to the
-route's `sandbox` boolean, so the trust decision has a reviewable trail
-without reading every route's source file:
+`true` or `false`. `urlcode explain`/`context`, the manifest and the
+`routes` inventory all surface it next to the route's `sandbox` boolean —
+per route, not per handler, so a native handler that runs `middleware`
+reports its execution mode too, and `routes --compare` shows a flip between
+trusted and sandboxed execution as a changed route. The trust decision has a
+reviewable trail without reading every route's source file:
 
 ```yaml
 routes:
@@ -323,8 +326,9 @@ trust (adding `sandbox: true` without saying why, or relying on the trusted
 default for code that plainly needed isolation) to work around them.
 
 There is no native `link` handler or `dynamicLinks` project flag; both were
-removed. Report a request for live stored links as a gap pending the future
-`urlcode-dynamic-link` extension package rather than inventing a `link` field.
+removed. The `urlcode-dynamic-link` extension package that briefly owned them
+has been retired and unpublished, so there is no supported replacement. Report a
+request for live stored links as a gap rather than inventing a `link` field.
 
 See [capabilities and normalized route representation](CAPABILITIES.md) for the target catalog,
 programmatic compatibility analysis and provider verification limits.

package/docs/ASSETS.md

@@ -2,7 +2,8 @@
 
 Native file handlers are implemented in 0.1.0-alpha.3. They work in the local
 Node runtime and self-hosted process/container. Provider adapters remain planned.
-They do not run user functions or expose filesystem APIs to sandboxed code.
+They do not run user functions or expose filesystem APIs to guest code, trusted
+or sandboxed.
 
 ```yaml
 version: "1"

package/docs/AUTH-BACKUP.md

@@ -0,0 +1,32 @@
+# Auth backup and restore platform guarantees
+
+`createBackup({database,destination,projectRoot})` and
+`restoreBackup({backup,destination,projectRoot})` use SQLite's online backup API
+in a bounded worker. They include committed WAL pages, validate integrity and
+foreign keys, and publish to a new path without overwriting an existing file.
+Both source and destination must remain outside the served project. See the
+[auth operator commands](../packages/auth/README.md#operations-and-recovery).
+
+The completed snapshot is flushed through a writable file handle before it is
+linked into its destination. Windows requires write access for this flush;
+opening the snapshot read-only fails with `EPERM`. File flush errors fail the
+operation rather than being ignored.
+
+On POSIX systems the containing directory is also flushed after publication.
+Node's filesystem API does not provide the equivalent directory-handle flush
+used here on Windows, so Windows does not receive that extra directory-entry
+crash-durability guarantee. A successful Windows backup verifies and flushes
+file contents; it is not proof that the new filename survives abrupt power
+loss. Verify the backup exists and perform an isolated restore rehearsal before
+depending on it. CI does not simulate power loss.
+
+POSIX directory/file modes are checked where supported. Windows operators must
+restrict the operator data and backup directories with filesystem ACLs; POSIX
+mode bits cannot establish Windows privacy. Keep encryption and CSRF keys and
+reviewed configuration separately backed up. Restore to an isolated new path,
+and review restored sessions and revocation state before reopening traffic.
+
+A failed auth service initialization waits for its SQLite worker to terminate
+before rejecting. After a configuration rejection, callers can retry or clean up
+the database without racing that failed opener's file handle. Configuration
+identity checks and their error codes are unchanged.

package/docs/BEST-PRACTICES.md

@@ -165,8 +165,10 @@ accepting any user-controlled URL. Keep modules free of top-level work other tha
 simple definitions: initialization runs during validation and fresh invocations.
 
 Prefer pure helpers with explicit inputs and outputs. Module globals are not a
-cache, database, session store or rate limiter: guest state resets per request.
-Review [sandbox constraints](FUNCTION-SECURITY.md) before choosing dependencies.
+cache, database, session store or rate limiter: guest state resets per request
+regardless of trust mode. If a route declares `sandbox: true`, review
+[sandbox constraints](FUNCTION-SECURITY.md) before choosing dependencies —
+trusted (default) routes have ordinary Node module access instead.
 
 ## Middleware should have one clear responsibility
 
@@ -182,8 +184,10 @@ export default async function responseHeaders(request, context, next) {
 
 Use middleware for reusable behavior around a handler, not to conceal the entire
 application flow. Prefer YAML headers for fixed route-specific headers; this
-example demonstrates a shared wrapper, but native YAML avoids sandbox overhead
-when no custom code is needed. Keep middleware order explicit in each route.
+example demonstrates a shared wrapper, but native YAML avoids any
+function/middleware invocation overhead when no custom code is needed —
+including the extra cost of `sandbox: true` where that is declared. Keep
+middleware order explicit in each route.
 
 Always return a Response. Call `await next()` once when continuing, or return
 an early Response when intentionally stopping. Do not launch unawaited work or
@@ -217,8 +221,9 @@ For the two-route feature layout above:
 ```
 
 Additional ordinary JavaScript unit tests for pure helpers are your project's
-choice. Unit tests alone do not verify sandbox compatibility: always exercise
-HTTP behavior through URLCode too. Keep large fixture generation explicit and
+choice. Unit tests alone do not verify runtime compatibility — including the
+guest API restrictions of a route declaring `sandbox: true` — or HTTP framing:
+always exercise HTTP behavior through URLCode too. Keep large fixture generation explicit and
 deterministic if you add your own tooling; nested test directories and JSON
 fragments are not automatically discovered or merged by URLCode.
 
@@ -238,9 +243,12 @@ Update expected route counts deliberately when adding or removing a route.
   YAML anchors, shell expansion or generated credentials for convenience.
 - Deployment limits, TLS, DNS, DDoS filters and worker tuning belong to operations,
   not invented route fields. Document them separately from portable behavior.
-- Live short-code records need durable storage core does not have; that is
-  moving to a future `urlcode-dynamic-link` extension package, not yet
-  published. General session/application storage remains future work.
+- Live short-code records need durable storage core does not have. The
+  `urlcode-dynamic-link` extension provided it and has been retired; its
+  published `0.1.0-alpha.1` pins core `0.4.0-alpha.1` exactly and so cannot be
+  installed beside `0.4.0-alpha.2`. Treat stored short links as unsupported
+  until that work lands somewhere else. General session/application storage
+  remains future work.
 
 ## Refactor without changing the public contract
 

package/docs/CAPABILITIES.md

@@ -166,7 +166,7 @@ proxy headers and signal definitions. Resolved egress headers are private runtim
 state and must never be serialized. Capability analysis itself adds no authority
 and does not run in the request path.
 
-See the [repository review and incremental plan](NEXT-PHASE-PLAN.md) for the
+See the [repository review and incremental plan](archive/2026-09-19/NEXT-PHASE-PLAN.md) for the
 implementation status. Provider deployment tests, independent security review and
 operational soak/recovery proof are separate work.
 

package/docs/CI-FOLLOWUP-2026-09-19.md

@@ -0,0 +1,97 @@
+# CI and release follow-up, September 19, 2026
+
+This is the evidence and disposition for [#185](https://github.com/jimhoyd-com/urlcode/issues/185),
+after the Windows fixes (#190) and matrix change (#192). It does not authorize
+publication or change required checks.
+
+## Reproducible measurements
+
+```sh
+npm run ci:history -- 100 2026-09-19 > /tmp/ci-history.json
+npm run ci:report -- 35482828280
+```
+
+The history helper reads GitHub through `gh`, with four concurrent requests at
+most. It does not dispatch new runs. Increase the limit (maximum 1,000) as more
+history accumulates. Use a date cutoff after the rollout when comparing the
+same workflow generation. It groups by event, inferred lane and exact matrix,
+reports counts and nearest-rank p50/p95, and flags groups with fewer than 20
+successful first attempts. Failures/cancellations remain visible but are excluded
+from successful-run percentiles. Reruns are excluded because run creation time
+includes the human delay before retrying. Earlier attempts are not a complete
+usage ledger. Raw job/step durations and run URLs remain in the output.
+
+Workflow elapsed time ends at the last active job's completion. Runner-minutes
+sum overlapping job execution durations: they are neither wall time nor billed
+minutes. Job-creation-to-start is an observed scheduling interval, not a guarantee
+of pure runner queue time. Workflow-creation-to-start also includes dependencies.
+Missing timestamps remain missing; they are never treated as zero.
+
+The initial 100-run sample spans September 19 04:59 UTC through September 20
+02:00 UTC. Successful first-attempt results:
+
+| Configuration | Samples | Wall p50 / p95 | Runner-minute p50 / p95 |
+| --- | ---: | --- | --- |
+| Historical combined main, 9 jobs | 20 | 8m27s / 9m04s | 49.82 / 53.62 |
+| Historical combined PR, 3 jobs | 40 | 6m12s / 8m52s | 17.28 / 24.57 |
+| Split full main, 18 jobs | 1 | 7m36s / 7m36s | 74.30 / 74.30 |
+| Split compact main, 10 jobs | 1 | 6m48s / 6m48s | 43.20 / 43.20 |
+| Split compact PR, 10 jobs | 2 | 6m38s / 7m15s | 40.23 / 43.58 |
+
+Historical groups contain changing code and workflow revisions; they are context,
+not a controlled experiment. The sample includes no classified docs-only runs.
+It cannot satisfy the 20-run acceptance criterion for the new lanes. Do not
+manufacture 20 redundant workflow runs to fill the sample.
+
+The [compact main run](https://github.com/jimhoyd-com/urlcode/actions/runs/35482828280)
+used 31.1 fewer runner-minutes than the preceding
+[full matrix main run](https://github.com/jimhoyd-com/urlcode/actions/runs/35482515877),
+an observed 41.9% reduction between two runs, not an established long-term rate.
+Its Windows core job took 377 seconds: 258 in `npm test`, 58 in package smoke,
+13 in installation. Linux Node 22 spent 300 of its 355 seconds in `npm test`.
+The next useful optimization target is the runtime suite, not removing static,
+container, audit or provenance checks. CLI subcommands are separate steps in the
+raw report. File-level profiling is still needed before choosing balanced shards;
+extra shards would add setup and runner pressure.
+
+## Changes delivered in this follow-up
+
+- A Windows validation failure exposed rejected auth initialization returning
+  before its worker terminated. The caller now awaits termination before receiving
+  the original error; a deterministic regression test proves the ordering.
+- `ci:history` makes the remaining baseline measurable without new CI jobs.
+- Auth/admin release instructions now use scoped monorepo tags and the correct
+  trusted-publisher workflow filenames. Package agent guides file issues here
+  and point documentation at root `docs/`.
+- Optional evals checks its credential before checkout/setup/install, and retains
+  artifacts for 14 days. This avoids unused setup; it does not remove the weekly
+  quality check or claim measured savings from a workflow with no prior runs.
+- The manual signed candidate builds all four tarballs and installs them together
+  in a temporary consumer outside the workspace. It verifies the peer dependency
+  tree, installed versions, public imports, and `init --with auth,admin,ui`.
+  `train.json` records package SHA-512 integrity and the source commit; the
+  candidate manifest/checksums and provenance include the extension archives.
+  Failure stops the candidate before attestation/upload. Nothing is published.
+
+The candidate validates the proposed package set, not live-provider behavior or
+registry OIDC. Per-package release workflows still prepare their own archives
+and retain their original bytes for retries; candidate archives are not silently
+substituted for published release bytes. Before a release, dispatch the candidate
+at the selected main commit, then the full verification workflow, and inspect
+both results before using the authorized coordinator.
+
+## Remaining decisions and external validation
+
+| Item | Disposition |
+| --- | --- |
+| Windows packaging/process coverage | Delivered in #190/#192; Node 24 on relevant PRs/main, all supported versions nightly/manually. |
+| 20-run baseline per new lane | Wait for organic runs, then rerun the helper with a rollout cutoff. |
+| Dependency-aware package selection | Keep conservative coverage for now. UI feeds auth/admin; auth feeds admin; core extension/CLI/scaffold changes affect the full composition. A package map must include integration, generated styles, peers and tooling, not just changed directory names. |
+| Changeset/no-release enforcement | Still open. Define explicit core release intent as well as workspace Changesets; require reviewed reasons for no-release cases before implementing a gate. Blanket source-path rules would misclassify tests/tooling and root core is not versioned by Changesets. |
+| Move core into `packages/core` | Separate migration, not a prerequisite for fast CI. Root-relative build, package files, CLI, Docker and starter paths make this higher risk than keeping the explicit root inventory. |
+| OIDC and retained-artifact retry | Needs the next explicitly authorized release. No synthetic run proves npm's trust configuration or partial publication recovery. |
+| Historical GHCR image labels/digests | Blocked on read access: anonymous registry lookup returned 403; organization package API explicitly requires `read:packages`. No labels/digests were verified and no images or publication settings changed. The repository has no `PUBLISH_CONTAINER` variable; inherited organization variables could not be inspected with this credential. |
+| Dependabot grouping / unchanged nightly reuse | No change yet. Measure update PR fanout before grouping; unchanged source can still acquire new advisory findings, so reusing old verification indiscriminately would hide them. |
+
+Keep #185 open for these acceptance items. The remaining items are not evidence
+that a publish or recovery rehearsal has already succeeded.