@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/dist/types/observability.d.ts

@@ -1,14 +1,11 @@
 export declare const events: Readonly<{
+    signal: readonly string[];
     request: readonly string[];
     reload: readonly string[];
     watch: readonly string[];
     function_worker: readonly string[];
-    link_store_worker: readonly string[];
-    link_request: readonly string[];
-    link_observer: readonly string[];
     logs_dropped: readonly string[];
     observer: readonly string[];
-    management_request: readonly string[];
     throttle: readonly string[];
     agents: readonly string[];
     cache: readonly string[];
@@ -61,20 +58,12 @@ export interface MetricsSnapshot {
         healthySlots: number;
         slots: number;
     };
-    linkStoreWorkers: {
-        started: number;
-        restarts: number;
-    };
     policies: {
         throttle: Counters;
         agents: Counters;
         cache: Counters;
     };
-    linkRequests: Counters;
-    linkObserver: {
-        failed: number;
-        dropped: number;
-    };
+    signals: Counters;
     logsDropped: number;
     observers: {
         errors: number;
@@ -97,7 +86,7 @@ export type ObserverSink = ((event: ObserverEvent, context?: RecordContext) => v
     close(): Promise<void>;
 };
 export declare function validateObservers(observers?: unknown): Observer[];
-export declare const SNAPSHOT_VERSION = 1;
+export declare const SNAPSHOT_VERSION = 2;
 export declare function createMetrics(): Metrics;
 export declare function createObserverSink(observers?: unknown, fallbackLog?: (event: ObserverEvent) => void, metrics?: Metrics): ObserverSink;
 export declare function renderPrometheus(snapshot: Partial<MetricsSnapshot>): string;

package/dist/types/operator-host.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeOptions } from './runtime.ts';
+/** Explicitly loaded operator code. Never discovered in application directories. */
+export interface OperatorHost {
+    extensions?: RuntimeOptions['extensions'];
+    plugins?: RuntimeOptions['plugins'];
+    close?(): void | Promise<void>;
+}
+export declare function loadOperatorHost(file: string | undefined, project: string): Promise<OperatorHost>;

package/dist/types/plugins.d.ts

@@ -13,6 +13,8 @@ export interface Plugin {
     name: string;
     version: string;
     targets: TargetName[];
+    /** Operator-owned header names withheld from every guest Request and input context. */
+    credentialHeaders?: string[];
     onActivate?(runtime: PluginRuntime): void | Promise<void>;
     onRequest?(request: PolicyRequest): HandlerResult | undefined | void | Promise<HandlerResult | undefined | void>;
     onResponse?(request: PolicyRequest, result: HandlerResult): HandlerResult | undefined | void | Promise<HandlerResult | undefined | void>;

package/dist/types/policies/agents.d.ts

@@ -70,8 +70,6 @@ export interface AgentsDescription {
     };
 }
 export declare const bundledLists: readonly string[];
-export declare const MAX_PATTERN_BYTES = 256;
-export declare const MAX_REPEAT = 64;
 export declare function validatePattern(pattern: unknown): string | undefined;
 export declare function isBundled(reference: string): boolean;
 export declare function isListFile(reference: unknown): reference is string;

package/dist/types/policies/compression.d.ts

@@ -31,6 +31,8 @@ export interface CompressionDescription {
     level: number | null;
     precompressed: number;
 }
+/** The media types compressed when `types` is not declared; exported so the deployment verifier reads the same table. */
+export declare const DEFAULT_TYPES: string[];
 export declare const zstdAvailable: boolean;
 export declare function targets(): Record<TargetName, PolicySupport>;
 export declare function compile(config: CompressionConfig, { route, shared }: PolicyContext): Promise<CompressionState>;

package/dist/types/policies/security.d.ts

@@ -21,7 +21,6 @@ export interface SecurityDescription {
 }
 export declare const name = "security";
 export declare const phases: readonly string[];
-export declare const oshpRevision = "OSHP 2024 best practices";
 export declare const profiles: Readonly<Record<string, readonly (readonly [string, string])[]>>;
 export declare const reservedHeaders: Readonly<Set<string>>;
 export declare function targets(): Record<string, 'native' | 'compiled'>;

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,13 +1,14 @@
 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'];
     origin?: string | undefined;
 }
 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, 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,10 +4,13 @@ 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';
 /** One configured route as the inventory reports it: a PlanInventoryEntry with the handler kind named. */
 export interface RouteInventory extends PlanInventoryEntry {
     handler: HandlerName | undefined;
+    /** Non-blocking `audit` observations about this route (e.g. a webhook-shaped
+     * route with no declared `sandbox`/`sandboxReason`); never affects `ready`. */
+    advisories?: string[];
 }
 /** One request case: a generated probe or a `tests/requests.json` fixture. */
 export interface RequestCase {
@@ -40,7 +43,6 @@ export interface AuditableApp {
     address: AddressInfo;
     root: string;
     testPlan(): ProjectPlan & {
-        dynamicLinks?: boolean;
         policies?: Record<string, PolicyInventory>;
     };
 }
@@ -51,7 +53,6 @@ export interface AuditOptions {
     compliance?: ComplianceOptions | undefined;
 }
 export interface AuditReport {
-    dynamicLinks: boolean | undefined;
     elapsedMs: number;
     ready: boolean;
     counts: {
@@ -74,6 +75,12 @@ export interface AuditReport {
     }[];
     policies: Record<string, PolicyInventory>;
     compliance: ComplianceReport | null;
+    /** Non-blocking `audit` observations, e.g. a route that looks webhook-shaped
+     * but declares neither `sandbox: true` nor `sandboxReason`. Never affects `ready`. */
+    advisories: {
+        route: string;
+        message: string;
+    }[];
 }
 export interface BenchmarkOptions {
     requests?: number | 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/router.d.ts

@@ -1,3 +1,4 @@
+import type { RuntimeExtension } from './extensions.ts';
 import type { CompiledRouteTable, LoadedDocument } from './types.ts';
 export { parseTarget, matchRoute, contextFor, resolveValue, redirectLocation } from './match.ts';
 /** The grants compileRoutes consults: a validated OperatorPolicy (policy.ts) or nothing, which denies every binding. */
@@ -8,4 +9,4 @@ export interface BindingPermissions {
         secrets?: string[];
     }>;
 }
-export declare function compileRoutes(loaded: LoadedDocument, bindings: Record<string, string | undefined>, permissions?: BindingPermissions, projectSha256?: string): Promise<CompiledRouteTable>;
+export declare function compileRoutes(loaded: LoadedDocument, bindings: Record<string, string | undefined>, permissions?: BindingPermissions, projectSha256?: string, extensions?: readonly Pick<RuntimeExtension, 'name' | 'cacheSensitive'>[]): Promise<CompiledRouteTable>;

package/dist/types/runtime.d.ts

@@ -1,61 +1,45 @@
+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';
 import type { Plugin } from './plugins.ts';
 import type { MetricsSnapshot, Observer } from './observability.ts';
 import type { HandlerResult, HeaderPair } from './http-response.ts';
 import type { LogFn, PolicyInventory, TargetName } from './types.ts';
-/** A stored link as a link store returns it; the runtime validates the fields it uses. */
-export interface LinkLookup {
-    url?: unknown;
-    status?: unknown;
-    enabled?: unknown;
-    expires?: unknown;
-}
-/** What a `linkStores` binding must provide: a reader and, optionally, its health. */
-export interface LinkReader {
-    get(collection: string, code: string): Promise<LinkLookup | null | undefined>;
-    readonly readHealthy?: boolean;
-    readonly healthy?: boolean;
-}
-/** An operator-owned SQLite link store the runtime opens read-only for one collection. */
-export interface LinkStoreBinding extends LinkStoreOptions {
-    collection: string;
-}
 export type { OperatorPolicy } from './policy.ts';
 /** An operator plugin (src/plugins.ts). */
 export type HostPlugin = Plugin;
 export type { Observer, MetricsSnapshot } from './observability.ts';
 export interface TestPlan extends ProjectPlan {
-    dynamicLinks: boolean;
     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;
     local?: boolean | undefined;
     environment?: NodeJS.ProcessEnv | undefined;
     permissions?: OperatorPolicy | undefined;
-    linkStore?: LinkStoreBinding | undefined;
-    linkStores?: Record<string, LinkReader> | undefined;
     target?: TargetName | undefined;
     plugins?: HostPlugin[] | undefined;
     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 {
-    collection: string;
-    code: string | null;
-    result: string;
-}
 export interface RequestTrace {
     route?: string;
     probe?: boolean;
     client?: string | null;
-    link?: LinkTrace;
 }
 export interface RuntimeRequest {
     target: string;

package/dist/types/sandbox.d.ts

@@ -0,0 +1,12 @@
+export { SandboxPool } from './functions.ts';
+export type { SandboxEntry, SandboxTarget, SandboxInvocation, SandboxPoolOptions, FunctionContext, FunctionResult, } from './functions.ts';
+export type { GuestRequestPayload, GuestResponsePayload } from './guest-api.ts';
+export type { HandlerResult, HeaderPair } from './http-response.ts';
+/**
+ * Resolves a project-relative hook source string the same way a native
+ * `function`/`middleware` route's `source` is resolved (`.mjs`/`.js` only, no
+ * path traversal outside the project root) into the absolute path
+ * `SandboxPool`'s entries and `execute()` targets expect. `root` must be the
+ * project's resolved directory (`ExtensionActivation.root`, never `cwd()`).
+ */
+export { functionFile } from './config.ts';

package/dist/types/scaffold.d.ts

@@ -1,11 +1,9 @@
 export interface Unresolved {
     path?: string;
     reason: string;
-    collection?: string;
 }
 export interface ScaffoldReport {
     dryRun: boolean;
-    dynamicLinks: boolean;
     created: string[];
     preserved: string[];
     unresolved: Unresolved[];

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

@@ -1,7 +1,6 @@
 import http from 'node:http';
 import type { AddressInfo } from 'node:net';
 import type { RuntimeOptions, TestPlan } from './runtime.ts';
-import type { LinkObserverStats } from './link-events.ts';
 import type { MetricsSnapshot, Observer } from './observability.ts';
 export interface ServerOptions extends Omit<RuntimeOptions, 'observers'> {
     project?: string | undefined;
@@ -13,7 +12,6 @@ export interface ServerOptions extends Omit<RuntimeOptions, 'observers'> {
     maxInFlightHealthRequests?: number | undefined;
     requestLog?: string | undefined;
     trustRequestId?: boolean | undefined;
-    linkEvents?: unknown;
     trustedProxies?: string | string[] | undefined;
     observers?: Observer[] | undefined;
     metrics?: boolean | undefined;
@@ -25,7 +23,6 @@ export interface Server {
     address: AddressInfo;
     root: string;
     testPlan(): TestPlan;
-    linkEventStats(): LinkObserverStats | undefined;
     metrics(): MetricsSnapshot;
     readonly observers: {
         name: string;
@@ -34,4 +31,4 @@ export interface Server {
     origin: string;
     close(): Promise<void>;
 }
-export declare function startServer({ project, host, port, watch, local, log, maxBodyBytes, maxInFlightRequests, maxInFlightHealthRequests, requestLog, trustRequestId, origin, linkEvents, trustedProxies, observers, metrics, metricsIntervalMs, ...runtimeOptions }?: ServerOptions): Promise<Server>;
+export declare function startServer({ project, host, port, watch, local, log, maxBodyBytes, maxInFlightRequests, maxInFlightHealthRequests, requestLog, trustRequestId, origin, trustedProxies, observers, metrics, metricsIntervalMs, ...runtimeOptions }?: ServerOptions): Promise<Server>;

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" | "expires" | "middleware" | "extension" | "proxy" | "signals" | "conditional" | "methods" | "enabled" | "parameters" | "redirect" | "page" | "download" | "static" | "respond" | "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" | "static" | "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" | "static" | "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>;