@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/types/policy.d.ts

@@ -1,13 +1,19 @@
 import type { FunctionSources } from './function-sources.ts';
 import type { LoadedDocument } from './types.ts';
+export interface EgressGrants {
+    proxy?: string[];
+    signals?: string[];
+}
+export interface RouteGrant {
+    env?: string[];
+    secrets?: string[];
+    egress?: EgressGrants;
+}
 /** The operator's binding grants: which env and secret names each route may read, pinned to a project hash. */
 export interface OperatorPolicy {
     version: 1;
     projectSha256: string;
-    routes: Record<string, {
-        env?: string[];
-        secrets?: string[];
-    }>;
+    routes: Record<string, RouteGrant>;
 }
 /** The function snapshot plus the hash operator grants are pinned to. */
 export interface FunctionSnapshot extends FunctionSources {
@@ -19,3 +25,8 @@ export declare function loadOperatorPolicy(file: string | undefined, project: st
 export declare function requestedPermissions(loaded: LoadedDocument, snapshot: {
     projectSha256: string;
 }): OperatorPolicy;
+/** Called before resources or credentials are activated. Grants never come from YAML. */
+export declare function authorizeEgress(loaded: LoadedDocument, projectSha256: string, policy: OperatorPolicy | undefined): {
+    proxy: string[];
+    signals: string[];
+};

package/dist/types/project-tests.d.ts

@@ -1,6 +1,8 @@
 import type { ServerOptions } from './server.ts';
 import type { LogFn } from './types.ts';
 export interface ProjectTestOptions {
+    extensions?: ServerOptions['extensions'];
+    plugins?: ServerOptions['plugins'];
     log?: LogFn | undefined;
     permissions?: ServerOptions['permissions'];
     linkStore?: ServerOptions['linkStore'];
@@ -10,4 +12,4 @@ export interface ProjectTestResult {
     total: number;
     failed: number;
 }
-export declare function runProjectTests(project: string, { log, permissions, linkStore, origin }?: ProjectTestOptions): Promise<ProjectTestResult>;
+export declare function runProjectTests(project: string, { log, permissions, linkStore, origin, extensions, plugins }?: ProjectTestOptions): Promise<ProjectTestResult>;

package/dist/types/provider-verification.d.ts

@@ -0,0 +1,53 @@
+export type VerificationTarget = 'self-hosted' | 'aws' | 'vercel' | 'cloudflare';
+export interface ProviderProbe {
+    id: string;
+    path: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    expected: {
+        status: number;
+        headers?: Record<string, string>;
+        body?: string;
+    };
+}
+export interface ProviderAnswer {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export type ProviderTransport = (probe: ProviderProbe, signal: AbortSignal) => Promise<ProviderAnswer>;
+export interface ProviderVerificationOptions {
+    timeoutMs?: number;
+    release?: string;
+    gitCommit?: string;
+}
+export interface ProviderFinding {
+    case: string;
+    pass: boolean;
+    expectedStatus: number;
+    observedStatus: number | null;
+    failures: string[];
+}
+export interface ProviderVerificationReport {
+    schemaVersion: 1;
+    fixtureVersion: 1;
+    target: VerificationTarget;
+    origin: string | null;
+    evidence: 'local-adapter' | 'deployment-http';
+    providerVerification: 'unverified' | 'observed';
+    timestamp: string;
+    release: string | null;
+    gitCommit: string | null;
+    fixtureSha256: string;
+    pass: boolean;
+    requests: number;
+    findings: ProviderFinding[];
+    notes: string[];
+}
+/** Synthetic read-only routes, except a POST to a declared constant response. */
+export declare function providerConformanceCases(): ProviderProbe[];
+/** Replay against a caller-supplied local adapter; never label this a provider deployment. */
+export declare function runProviderConformance(target: VerificationTarget, transport: ProviderTransport, options?: ProviderVerificationOptions): Promise<ProviderVerificationReport>;
+/** Probe only an explicitly supplied, operator-owned deployment of the fixture. Redirects are never followed. */
+export declare function verifyProviderDeployment(target: VerificationTarget, origin: string, options?: ProviderVerificationOptions): Promise<ProviderVerificationReport>;

package/dist/types/proxy.d.ts

@@ -0,0 +1,21 @@
+import type { EgressRequest, EgressResponse } from './egress.ts';
+export interface ProxyDefinition {
+    url: string;
+    query?: string[];
+    requestHeaders?: string[];
+    responseHeaders?: string[];
+    headers?: Record<string, string>;
+}
+export interface ProxyInput {
+    method: string;
+    url: string | URL;
+    params: Record<string, unknown>;
+    headers: Record<string, string | undefined>;
+    body?: Uint8Array;
+    signal?: AbortSignal;
+}
+export interface EgressTransport {
+    request(input: EgressRequest): Promise<EgressResponse>;
+}
+export declare function validateProxy(definition: ProxyDefinition): void;
+export declare function executeProxy(client: EgressTransport, definition: ProxyDefinition, input: ProxyInput): Promise<EgressResponse>;

package/dist/types/readiness.d.ts

@@ -4,7 +4,7 @@ import type { CompiledRedirect, CompiledRoute, LogFn, PlanInventoryEntry, Policy
 import type { ComplianceOptions, ComplianceReport } from './compliance.ts';
 import type { CompiledRoutes } from './match.ts';
 export type { RouteState } from './types.ts';
-export type HandlerName = 'redirect' | 'function' | 'page' | 'static' | 'download' | 'respond' | 'link';
+export type HandlerName = 'extension' | 'proxy' | 'conditional' | 'redirect' | 'function' | 'page' | 'static' | 'download' | 'respond' | 'link';
 /** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
 export interface RouteInventory extends PlanInventoryEntry {
     handler: HandlerName | undefined;

package/dist/types/recipes.d.ts

@@ -0,0 +1,30 @@
+import type { CatalogMetadata } from './catalog.ts';
+/** recipe.yaml, validated against schemas/recipe.schema.json; `name` repeats `id` and `files` is the copy list. */
+export interface RecipeSummary extends CatalogMetadata {
+    name: string;
+}
+export interface Recipe extends RecipeSummary {
+    content: Record<string, string>;
+}
+export interface RecipeAddReport {
+    name: string;
+    output: string;
+    dryRun: boolean;
+    files: string[];
+}
+export interface RecipeSearchResult {
+    query: string;
+    count: number;
+    results: (RecipeSummary & {
+        score: number;
+        matched: string[];
+    })[];
+}
+export declare const recipeNames: readonly ["redirect", "json-api", "typescript", "middleware", "health-page", "static-plus-api", "cors-api", "webhook-receiver", "contact-form", "authenticated-json-api", "protected-download"];
+export declare function listRecipes(): Promise<RecipeSummary[]>;
+/** Matches id, description, tags and capabilities locally; no service is consulted. */
+export declare function searchRecipes(text: string): Promise<RecipeSearchResult>;
+export declare function showRecipe(name: string): Promise<Recipe>;
+export declare function addRecipe(name: string, output: string, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<RecipeAddReport>;

package/dist/types/route-diff.d.ts

@@ -0,0 +1,27 @@
+import type { PlanInventoryEntry } from './types.ts';
+/** One route as the diff sees it: the inventory entry plus its policy description from the `policies` map. */
+export interface RouteRecord extends PlanInventoryEntry {
+    policy?: Record<string, unknown>;
+}
+/** The parts of a `urlcode routes` report the diff reads. */
+export interface RouteSnapshot {
+    inventory: PlanInventoryEntry[];
+    policies?: Record<string, Record<string, unknown>> | undefined;
+}
+export interface RouteChange {
+    path: string;
+    before: RouteRecord;
+    after: RouteRecord;
+}
+export interface RouteDiff {
+    added: RouteRecord[];
+    removed: RouteRecord[];
+    changed: RouteChange[];
+}
+/** Validates a parsed `urlcode routes` JSON report (a child-process or file boundary) into a snapshot. */
+export declare function parseRouteSnapshot(value: unknown): RouteSnapshot;
+/** Compares two route reports. Paths are sorted; an entry changes when any inventory field or its policy description differs. */
+export declare function diffRoutes(before: RouteSnapshot, after: RouteSnapshot): RouteDiff;
+export declare const hasRouteChanges: (diff: RouteDiff) => boolean;
+/** Renders a diff as Markdown: one table per nonempty section, or "No route changes". */
+export declare function renderRouteDiff(diff: RouteDiff): string;

package/dist/types/runtime.d.ts

@@ -1,3 +1,5 @@
+import type { RuntimeExtension } from './extensions.ts';
+import type { EgressDependencies } from './egress.ts';
 import type { ProjectPlan } from './readiness.ts';
 import type { OperatorPolicy } from './policy.ts';
 import type { LinkStoreOptions } from './link-store.ts';
@@ -31,6 +33,9 @@ export interface TestPlan extends ProjectPlan {
     policies: Record<string, PolicyInventory>;
 }
 export interface RuntimeOptions {
+    extensions?: RuntimeExtension[] | undefined;
+    /** Trusted host transport injection; never supplied by project YAML or guest code. */
+    egressDependencies?: EgressDependencies;
     observers?: Observer[] | undefined;
     log?: LogFn | undefined;
     origin?: string | undefined;
@@ -44,6 +49,12 @@ export interface RuntimeOptions {
     workers?: number | undefined;
     timeoutMs?: number | undefined;
     maxBytes?: number | undefined;
+    /** Build tooling only: compile just these route patterns, after site conventions
+     * have been expanded. It can only remove routes, never add or alter one, and the
+     * smaller route set changes the project hash, so an operator policy pinned to the
+     * whole project denies every binding it grants. Prerendering uses it to render a
+     * project too large for one function snapshot in passes (docs/PRERENDER.md). */
+    only?: readonly string[] | undefined;
 }
 /** Per-request facts the host may read after handle() settles; never request text. */
 export interface LinkTrace {

package/dist/types/schema-query.d.ts

@@ -0,0 +1,12 @@
+type Json = Record<string, unknown>;
+export interface SchemaFragment {
+    format: 1;
+    path: string;
+    pointer: string;
+    schema: Json;
+}
+/** Top-level document keys first, then `route` itself and every route property (`redirect`, `function`, `middleware`, ...). */
+export declare function schemaPathNames(): string[];
+/** Only the fragment for a dotted path, with references resolved inline. No validation, defaults or authority. */
+export declare function getSchemaFragment(path: string): SchemaFragment;
+export {};

package/dist/types/signals.d.ts

@@ -0,0 +1,25 @@
+import type { EgressTransport } from './proxy.ts';
+export interface SignalDefinition {
+    url: string;
+    headers?: Record<string, string>;
+}
+export interface SignalEvent {
+    route: string;
+    status: number;
+    method: string;
+}
+export interface SignalStats {
+    accepted: number;
+    delivered: number;
+    failed: number;
+    dropped: number;
+}
+export declare function validateSignal(definition: SignalDefinition): void;
+/** No queue, retries, ordering promise, or durable delivery. Counters contain no URL/header data. */
+export declare class SignalBroker {
+    #private;
+    constructor(client: EgressTransport, concurrency?: number, onStats?: (stats: SignalStats) => void);
+    get stats(): SignalStats;
+    emit(definition: SignalDefinition, event: SignalEvent): boolean;
+    close(): Promise<void>;
+}

package/dist/types/site.d.ts

@@ -6,7 +6,6 @@ export interface SiteOptions {
 }
 type SiteKey = keyof SiteConfig;
 export declare const generatedPaths: Readonly<Record<SiteKey, string>>;
-export declare const MAX_SITEMAP_URLS = 50000;
 export declare function expandSite(document: ProjectDocument, root: string, { origin, log, routes }?: SiteOptions): Promise<Record<string, RouteConfig>>;
 export declare function applySite(loaded: LoadedDocument, options?: SiteOptions): Promise<Record<string, RouteConfig>>;
 export {};

package/dist/types/tooling.d.ts

@@ -0,0 +1,115 @@
+import type { ImportRoutesOptions, InterchangeFormat } from './interchange.ts';
+import { listRecipes, showRecipe, searchRecipes } from './recipes.ts';
+import { listExamples, searchExamples } from './examples.ts';
+import type { CompiledRoute, PolicyChain } from './types.ts';
+import type { RuntimeExtension } from './extensions.ts';
+import type { RouteExplanation } from './explain.ts';
+export { getCapabilities } from './capabilities.ts';
+export { getCapability } from './capability-query.ts';
+export type { CapabilityEntry, CapabilityUsage } from './capability-query.ts';
+export { getSchemaFragment, schemaPathNames } from './schema-query.ts';
+export type { SchemaFragment } from './schema-query.ts';
+export { listRecipes, showRecipe, searchRecipes, listExamples, searchExamples };
+export { buildContext, renderContext, estimateTokens, documentationTokens } from './context.ts';
+export type { ContextOptions, ProjectContext, ContextSection } from './context.ts';
+export type { RouteExplanation, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport } from './explain.ts';
+/** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
+export interface InspectOptions {
+    origin?: string;
+    target?: string;
+    offset?: number;
+    limit?: number;
+    extensions?: RuntimeExtension[] | undefined;
+}
+export declare function prepare(project: string, options?: InspectOptions): Promise<{
+    loaded: import("./types.ts").LoadedDocument;
+    compiled: import("./types.ts").CompiledRouteTable;
+    routes: CompiledRoute[];
+    chains: Map<string, PolicyChain>;
+    projectSha256: string;
+}>;
+/** Semantic authoring inspection; no binding reads, sandbox execution or runtime activation. */
+export declare function inspectProject(project: string, options?: InspectOptions): Promise<{
+    format: number;
+    projectSha256: string;
+    routeCount: number;
+    offset: number;
+    limit: number;
+    routes: {
+        path: string;
+        methods: string[];
+        enabled: boolean;
+        capabilities: ("function" | "link" | "expires" | "middleware" | "extension" | "proxy" | "signals" | "conditional" | "methods" | "enabled" | "parameters" | "redirect" | "page" | "download" | "static" | "respond" | "dynamicLinks" | "policies.extensions" | "conditions" | "request.body" | "response.headers" | "bindings" | "policies.agents" | "policies.security" | "policies.cache" | "policies.compression" | "policies.throttle")[];
+    }[];
+    compatibility: {
+        offset: number;
+        limit: number;
+        hasMore: boolean;
+        issues: import("./capabilities.ts").CapabilityRequirement[];
+        target: "vercel" | "aws" | "cloudflare" | "self-hosted";
+        compatible: boolean;
+        deployment: "local-runtime" | "unverified";
+        requirementCount: number;
+        issueCount: number;
+    };
+}>;
+export declare function validateProject(project: string, options?: InspectOptions): Promise<{
+    valid: boolean;
+    projectSha256: string;
+    routeCount: number;
+    compatibility: {
+        target: "vercel" | "aws" | "cloudflare" | "self-hosted";
+        compatible: boolean;
+        deployment: "local-runtime" | "unverified";
+        requirementCount: number;
+        issueCount: number;
+        firstIssue: import("./capabilities.ts").CapabilityRequirement | null;
+    };
+}>;
+export interface RouteMiss {
+    matched: false;
+    nearest: string[];
+    note: string;
+}
+/** Explain the route a path selects from the compiled IR: effective methods, handler, middleware, inputs, policies, cache outcome, bindings and target support. Nothing executes and no binding is read. */
+export declare function explainRoute(project: string, target: string, options?: InspectOptions): Promise<RouteExplanation | RouteMiss>;
+/** Every route's explanation, in the router's precedence order. */
+export declare function explainProject(project: string, options?: InspectOptions): Promise<{
+    projectSha256: string;
+    routeCount: number;
+    routes: RouteExplanation[];
+}>;
+export declare function previewImport(options: ImportRoutesOptions): Promise<import("./interchange.ts").ConversionReport>;
+export declare function previewExport(project: string, format: InterchangeFormat, acceptProviderDifferences?: boolean): Promise<import("./interchange.ts").ConversionReport>;
+export interface ExtensionInspection {
+    format: 1;
+    projectSha256: string;
+    hostLoaded: boolean;
+    note: string;
+    extensions: {
+        name: string;
+        version: string;
+        targets: string[];
+        credentialHeaders: string[];
+        schema: object;
+        policySchema: object | null;
+        declared: boolean;
+        revisionPinned: boolean;
+        mounts: string[];
+        policyRoutes: string[];
+    }[];
+    declared: {
+        name: string;
+        version: string;
+        registered: boolean;
+        mounts: string[];
+        policyRoutes: string[];
+    }[];
+}
+/** Reports registered extension contracts against the project's declarations. Never activates an extension. */
+export declare function describeExtensions(project: string, registrations: RuntimeExtension[] | undefined): Promise<ExtensionInspection>;
+/** Executes the trusted operator host file to read its registrations, then releases it. */
+export declare function inspectExtensions(options: {
+    project: string;
+    hostFile?: string;
+}): Promise<ExtensionInspection>;

package/dist/types/types.d.ts

@@ -1,3 +1,7 @@
+import type { ExtensionDeclaration, ExtensionPolicies } from './extensions.ts';
+import type { ProxyDefinition } from './proxy.ts';
+import type { SignalDefinition } from './signals.ts';
+import type { RouteMatch } from './conditions.ts';
 import type { HandlerResult, HeaderPair } from './http-response.ts';
 import type { CompiledParameter, MatchableRoute, ParameterLocation, ParameterSchema, RedirectSpec, Scalar, ValueRef } from './match.ts';
 import type { HttpRoute, Reply, RequestBodyPolicy, RespondSpec } from './http-policy.ts';
@@ -33,6 +37,11 @@ export interface MiddlewareConfig {
     source: string;
     export?: string;
 }
+/** A route as YAML may spell it before normalization: `function` and middleware entries may be short-form module paths. */
+export type AuthoredRouteConfig = Omit<RouteConfig, 'function' | 'middleware'> & {
+    function?: string | FunctionConfig;
+    middleware?: (string | MiddlewareConfig)[];
+};
 export interface LinkConfig {
     collection: string;
     code: ValueRef;
@@ -73,6 +82,8 @@ export interface PolicyConfigs {
 /** One layer of policy configuration (profile, project or route); a layer may declare part of a policy, the merge supplies the rest. */
 export type PolicyLayer = {
     [K in PolicyName]?: Partial<PolicyConfigs[K]> | false;
+} & {
+    extensions?: ExtensionPolicies | false;
 };
 export interface PoliciesConfig extends PolicyLayer {
     profile?: string;
@@ -108,7 +119,42 @@ export interface SiteConfig {
     llms?: string;
 }
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
+export interface ConditionalReply {
+    redirect?: RedirectConfig;
+    respond?: RespondSpec;
+}
+export interface ConditionalConfig {
+    cases: (ConditionalReply & {
+        match: RouteMatch;
+    })[];
+    fallback?: ConditionalReply;
+}
+export type EgressHeaders = Record<string, string | {
+    secret: string;
+}>;
+export interface ProxyConfig extends Omit<ProxyDefinition, 'headers'> {
+    headers?: EgressHeaders;
+}
+export interface SignalConfig {
+    url: string;
+    headers?: EgressHeaders;
+}
+/** Route-level `auth` short form. Keys other than `required` mirror the auth extension's policy schema and expand to `policies.extensions.auth`. */
+export interface RouteAuthConfig {
+    required?: boolean;
+    role?: string;
+    permission?: string;
+    verified?: boolean;
+    freshWithinSeconds?: number;
+    onDeny?: 401 | 403 | 404 | 'sign-in';
+}
 export interface RouteConfig {
+    extension?: string;
+    auth?: true | RouteAuthConfig;
+    proxy?: ProxyConfig;
+    signals?: SignalConfig[];
+    match?: RouteMatch;
+    conditional?: ConditionalConfig;
     methods?: string[];
     enabled?: boolean;
     expires?: string;
@@ -136,6 +182,7 @@ export interface RouteConfig {
 }
 export interface ProjectDocument {
     version: '1';
+    extensions?: Record<string, ExtensionDeclaration>;
     routes: Record<string, RouteConfig>;
     includes?: string[];
     dynamicLinks?: boolean;
@@ -210,6 +257,16 @@ export interface CompiledRoute extends Omit<RouteConfig, 'methods' | 'parameters
     policy?: PolicyChain | null;
     /** Attached by build-cloudflare: the compiled policy states shipped in the Worker artifact. */
     compiledPolicies?: Record<string, unknown>;
+    extensionPolicyNames?: string[];
+    compiledProxy?: ProxyDefinition;
+    compiledSignals?: SignalDefinition[];
+    conditionalRoutes?: {
+        cases: {
+            match: RouteMatch;
+            route: CompiledRoute;
+        }[];
+        fallback?: CompiledRoute;
+    };
 }
 export interface CompiledRouteTable {
     exact: Map<string, CompiledRoute>;

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

@@ -0,0 +1,12 @@
+export interface TypeScriptBuildReport {
+    output: string;
+    dryRun: boolean;
+    modules: string[];
+    files: string[];
+    typeChecked: false;
+}
+/** Transpile a project snapshot ahead of runtime. No project compiler settings,
+ * plugins, package resolution, subprocesses or guest code execution are used. */
+export declare function buildTypeScriptProject(project: string, output: string, { dryRun }?: {
+    dryRun?: boolean | undefined;
+}): Promise<TypeScriptBuildReport>;

package/dist/types/vercel.d.ts

@@ -1,3 +1,4 @@
+import type { RuntimeExtension } from './extensions.ts';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Environment } from './adapters.ts';
 import type { HostPlugin } from './runtime.ts';
@@ -7,6 +8,7 @@ export interface VercelHandlerOptions {
     environment?: Environment | undefined;
     maxBodyBytes?: number | undefined;
     plugins?: HostPlugin[] | undefined;
+    extensions?: RuntimeExtension[] | undefined;
 }
 export type VercelHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
-export declare function createVercelHandler({ project, origin, environment, maxBodyBytes, plugins }?: VercelHandlerOptions): VercelHandler;
+export declare function createVercelHandler({ project, origin, environment, maxBodyBytes, plugins, extensions }?: VercelHandlerOptions): VercelHandler;

package/dist/types/verify-deployment.d.ts

@@ -0,0 +1,47 @@
+import type { RuntimeOptions } from './runtime.ts';
+import type { ComplianceOptions, ComplianceReport, Severity } from './compliance.ts';
+import type { LogFn } from './types.ts';
+export type { Severity } from './compliance.ts';
+export type FailOn = Severity | 'none';
+export type CheckName = 'probes' | 'fixtures' | 'security' | 'cache' | 'compression' | 'agents' | 'throttle' | 'site' | 'methods' | 'errors' | 'head' | 'transport';
+export interface VerifyFinding {
+    check: CheckName;
+    severity: Severity;
+    route?: string;
+    message: string;
+    expected?: string;
+    observed?: string;
+}
+export interface VerifyOptions extends Pick<RuntimeOptions, 'permissions' | 'linkStore'> {
+    target: string;
+    origin?: string | undefined;
+    expectRoutes?: number | undefined;
+    timeoutMs?: number | undefined;
+    expectMetrics?: boolean | undefined;
+    failOn?: FailOn | undefined;
+    compliance?: ComplianceOptions | undefined;
+    complianceWarn?: boolean | undefined;
+    log?: LogFn | undefined;
+}
+export interface VerifyReport {
+    target: string;
+    version: {
+        local: string;
+        observed: string | null;
+    };
+    routes: {
+        local: number;
+        observed: number | null;
+        expected: number | null;
+    };
+    requests: number;
+    checks: number;
+    findings: VerifyFinding[];
+    counts: Record<Severity, number>;
+    notes: string[];
+    failOn: FailOn;
+    pass: boolean;
+    compliance: ComplianceReport | null;
+}
+export declare const failLevels: readonly FailOn[];
+export declare function verifyDeployment(project: string, { target, origin, expectRoutes, timeoutMs, expectMetrics, failOn, compliance, complianceWarn, log, permissions, linkStore }: VerifyOptions): Promise<VerifyReport>;

package/dist/types.js

@@ -1,3 +1,7 @@
+                                                                               
+                                                  
+                                                     
+                                                  
 // Types shared across modules: the validated YAML document, the compiled
 // route the router produces from it, and the host-side policy contract.
 // This file is type-only (nothing here exists at run time) and append-only:
@@ -28,6 +32,8 @@
                                                  
                                                                                                              
                                                                      
+/** A route as YAML may spell it before normalization: `function` and middleware entries may be short-form module paths. */
+                                                                                                                                                                    
                                                                   
                                                                                          
                                                                         
@@ -39,7 +45,7 @@
                                                                                                                                                                
 /** One `policies` block or profile layer: every policy optional, `false` disables it. */
 /** One layer of policy configuration (profile, project or route); a layer may declare part of a policy, the merge supplies the rest. */
-                                                                                    
+                                                                                                                                 
                                                                         
 /** The result of layering profiles and route keys: what compiles, per policy. */
                                                        
@@ -52,7 +58,17 @@
  
                                                                                                                                                        
 /** One route as declared in YAML (plus `generated`, which site.ts stamps on the routes it adds). */
+                                                                                      
+                                                                                                                       
+                                                                  
+                                                                                                
+                                                                    
+/** Route-level `auth` short form. Keys other than `required` mirror the auth extension's policy schema and expand to `policies.extensions.auth`. */
+                                                                                                                                                                                  
                               
+                                                   
+                                              
+                                                      
                                                                                 
                                                                                        
                                                                             
@@ -63,7 +79,7 @@
                      
  
                                   
-                                                                                                 
+                                                                                                                                                  
                                                                                        
  
 /** What config.ts returns: the entry document, the merged route table and the files it came from. */
@@ -101,6 +117,9 @@
                               
                                                                                                  
                                              
+                                 
+                                                                      
+