vouchington-tooling 0.21.0 → 0.22.0

package/README.md

@@ -2,6 +2,12 @@
 
 Libraries and the `vouchington` CLI.
 
+The [workflow and compiler primitives](docs/workflow-and-compiler.md) provide consumer supplied
+GitHub Actions policy checks and compiler host freshness with bounded build settlement.
+
+[`config-inventory`](../../docs/config-inventory.md) collects environment, dynamic-configuration,
+and package-manager evidence using caller-owned file roles and policies.
+
 ```bash
 npm install vouchington-tooling
 # optional, only if you import vouchington-tooling/sql-ast
@@ -9,6 +15,8 @@ npm install @libpg-query/parser
 # optional, only if you import vouchington-tooling/contract-schema
 # (classic compiler API; typescript@7's package root is version-only)
 npm install @typescript/typescript6
+# optional, only if you use the Vitest reporter export
+npm install vitest
 # optional, only for vouchington-tooling/agent-blackboard and agent-blackboard CLI commands
 npm install agent-blackboard@^0.6.0
 ```
@@ -227,6 +235,7 @@ import {
   validateFixtureContracts,
   writeGeneratedFiles,
 } from 'vouchington-tooling/api-fixtures'
+import { discoverAppRouteCtxContractsV1 } from 'vouchington-tooling/api-contract-discovery'
 import { decide, deriveRetryAttempt } from 'vouchington-tooling/transient-retry'
 import { parseCsvRows, streamCsvRows } from 'vouchington-tooling/csv'
 import {
@@ -268,20 +277,40 @@ import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
 import { parseUniqueSwiftBinaryTargetChecksum } from 'vouchington-tooling/swift-source-offset'
 import { validateResolvedPinDelta } from 'vouchington-tooling/swift-resolved-pin-delta'
 import {
+  createForkLeakDetector,
+  createVitestWorkerExitDiagnosticsReporter,
   formatDiagnosticReportSummaries,
   readDiagnosticReportSummaries,
+  registerForkExitSentinel,
 } from 'vouchington-tooling/vitest-diagnostics'
 import { runRetrospectiveTranscript } from 'vouchington-tooling/retrospective-transcript'
 import { appendJournal, probeBlackboard } from 'vouchington-tooling/agent-blackboard'
 import { buildSessionFrictionReport, recordFriction } from 'vouchington-tooling/session-friction'
 import { GITHUB_BODY_MAX_CHARACTERS, validateGitHubBodyLength } from 'vouchington-tooling'
-import { createPullRequest, getDiffAgainstBase, runGh, runGit } from 'vouchington-tooling/gh-cli'
+import { createPullRequest, processDiffCommand, runGh, runGit } from 'vouchington-tooling/gh-cli'
 import {
   shellScriptViolations,
   workflowYamlViolations,
 } from 'vouchington-tooling/gh-api-shell-quoting'
 ```
 
+`processDiffCommand` runs a caller-supplied `git diff` or `gh pr diff` executable and argv without
+a shell, emitting complete unified-diff file blocks without accumulating the whole patch. It keeps
+at most one file block (which can itself be large), preserves preambles and line content, and drains
+a bounded stderr tail for typed command failures. Blocks are provisional until the returned promise
+resolves: callers must discard accumulated results if the command later exits nonzero or is signaled.
+
+```ts
+let changedFileCount = 0
+await processDiffCommand({ executable: 'git', args: ['diff', 'origin/main...HEAD'] }, async () => {
+  changedFileCount += 1
+})
+// Use changedFileCount only after processDiffCommand resolves.
+```
+
+This breaking minor removes `getDiffAgainstBase`; migrate callers to `processDiffCommand` and pass
+the command they need to run.
+
 `checkSccComplexity` keeps its single repository-wide scan when `scopes` is omitted. Consumers
 that need separately ratcheted areas may provide named scopes with positional `includePaths`; SCC
 runs once per scope and reports the scope in each diagnostic. Parse a consumer-owned JSON baseline
@@ -383,6 +412,35 @@ token-source router remains deprecated for one release line.
 filenames, tolerates partial files, returns only a bounded field allowlist, and never emits raw
 native frame symbols. Both structured reads and text rendering have hard report-count limits.
 
+`api-contract-discovery` is the version-one adapter for `app.route('/path').get/post/...` and
+`ctx` response conventions. Pass a classic TypeScript `program` and its route `sourceFiles` to
+`discoverAppRouteCtxContractsV1`. The result contains registered routes and response, request,
+query, and header contracts. The caller owns program construction, route-file selection, and
+generation. Pass `options.formatAliases` and `options.boundedArrayAlias` for application type
+aliases; `options.onRouteError` enables lenient response and request extraction. The adapter
+does not cache programs or depend on the caller's repository layout. OpenAPI document assembly
+remains a separate `openapi-document` call.
+
+Version one recognizes literal-key `apiResponse`, `apiNoContent`, `apiOpenApiRawResponse`,
+`apiRequest`, `apiRequestContract`, `apiNoRequestBody`, `apiQuery`, and `apiHeaders` markers inside
+`app.route(...).get/post/put/patch/delete(...)` handlers. It also inspects unmarked `ctx.json`,
+`ctx.pipeline`, `ctx.response.empty/buffer/xml`, `ctx.request.json/buffer`, `parseJsonBody`,
+`ctx.setStatus`, and static `Content-Type` setters. The input source files and TypeScript checker
+are the source representation; the adapter does not parse or discover a repository on its own.
+
+Fork diagnostics use a caller-selected `recordDirectory` in both the worker setup file and the
+main-process reporter. Call `registerForkExitSentinel({ recordDirectory })` once per fork, then
+update `setCurrentForkExitModule` and `setCurrentForkExitProject` around tests. Construct
+`createVitestWorkerExitDiagnosticsReporter({ recordDirectory })` in the Vitest reporter list
+before workers start. The reporter clears stale records at construction, preserves them across
+watch reruns, and prints an attribution summary only for abnormal worker exits. The worker writes
+a synchronous stderr line and one JSONL file per PID; a start record without an exit record
+identifies a fork killed before its handler could run. `createForkLeakDetector` accepts tracked
+resource names and warmup, threshold, and sustained-growth settings; the caller supplies each
+checkpoint's resource counts. Use a caller-owned run directory: the reporter clears only regular
+numeric PID `.jsonl` files there at construction and leaves the directory and other files alone.
+Application metrics and CI artifact handling stay with the caller.
+
 `browser-session-runner` supervises caller-created browser-test processes. Callers supply command
 construction, line classification, retry/outcome policy, and budgets; the library owns process-group
 termination, output line buffering, shared deadlines, progress watchdogs, diagnostics, and parent signals.

package/dist/agent-blackboard/snapshot-partition-format.mjs

@@ -1,76 +1,6 @@
 import { assertSessionId } from './session-id.mjs';
-function isObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function isTimestamp(value) {
-    return typeof value === 'string' && Number.isFinite(Date.parse(value));
-}
-function isCount(value) {
-    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
-}
-function isSelection(value) {
-    if (!isObject(value) || value.archived !== false)
-        return false;
-    if (value.agent !== undefined && typeof value.agent !== 'string')
-        return false;
-    if (value.version !== undefined && typeof value.version !== 'string')
-        return false;
-    if (value.parentSessionId !== undefined &&
-        value.parentSessionId !== null &&
-        typeof value.parentSessionId !== 'string')
-        return false;
-    if (value.data !== undefined && !isObject(value.data))
-        return false;
-    if (value.dataArrayContains !== undefined &&
-        (!isObject(value.dataArrayContains) ||
-            Object.keys(value.dataArrayContains).length === 0 ||
-            Object.entries(value.dataArrayContains).some(([key, member]) => key.length === 0 || typeof member !== 'string' || member.length === 0)))
-        return false;
-    return (value.inactiveForHours === undefined ||
-        (typeof value.inactiveForHours === 'number' &&
-            Number.isFinite(value.inactiveForHours) &&
-            value.inactiveForHours > 0));
-}
-function isManifest(value) {
-    if (!isObject(value) || value.schemaVersion !== 1 || value.status !== 'complete')
-        return false;
-    if (!isTimestamp(value.createdAt) ||
-        !isTimestamp(value.completedAt) ||
-        !isSelection(value.selection))
-        return false;
-    if (!isObject(value.counts) ||
-        !isCount(value.counts.sessions) ||
-        !isCount(value.counts.entries) ||
-        !isCount(value.counts.records))
-        return false;
-    return (isObject(value.ordering) &&
-        value.ordering.sessions === 'createdAt ascending' &&
-        value.ordering.entries === 'createdAt ascending within session' &&
-        value.consistency === 'best-effort');
-}
-function isSession(value) {
-    if (isObject(value) &&
-        typeof value.id === 'string' &&
-        value.id.length > 0 &&
-        (value.parentSessionId === null || typeof value.parentSessionId === 'string') &&
-        typeof value.agent === 'string' &&
-        typeof value.version === 'string' &&
-        isTimestamp(value.createdAt) &&
-        (value.lastEntryAt === null || isTimestamp(value.lastEntryAt)) &&
-        value.archivedAt === null &&
-        isObject(value.data)) {
-        try {
-            assertSessionId(value.id);
-            if (value.parentSessionId !== null)
-                assertSessionId(value.parentSessionId, 'parent session id');
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    return false;
-}
+import { isManifest, isSession } from './snapshot-partition-predicates.mjs';
+import { isObject, isTimestamp } from './snapshot-partition-guards.mjs';
 function isEntry(value) {
     if (isObject(value) &&
         typeof value.sessionId === 'string' &&

package/dist/agent-blackboard/snapshot-partition-guards.d.mts

@@ -0,0 +1,3 @@
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function isTimestamp(value: unknown): value is string;
+export declare function isCount(value: unknown): value is number;

package/dist/agent-blackboard/snapshot-partition-guards.mjs

@@ -0,0 +1,9 @@
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isTimestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+export function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}

package/dist/agent-blackboard/snapshot-partition-predicates.d.mts

@@ -0,0 +1,3 @@
+import type { SnapshotManifest } from './snapshot-types.mts';
+export declare function isManifest(value: unknown): value is SnapshotManifest;
+export declare function isSession(value: unknown): value is Record<string, unknown>;

package/dist/agent-blackboard/snapshot-partition-predicates.mjs

@@ -0,0 +1,65 @@
+import { assertSessionId } from './session-id.mjs';
+import { isCount, isObject, isTimestamp } from './snapshot-partition-guards.mjs';
+function isSelection(value) {
+    if (!isObject(value) || value.archived !== false)
+        return false;
+    if (value.agent !== undefined && typeof value.agent !== 'string')
+        return false;
+    if (value.version !== undefined && typeof value.version !== 'string')
+        return false;
+    if (value.parentSessionId !== undefined &&
+        value.parentSessionId !== null &&
+        typeof value.parentSessionId !== 'string')
+        return false;
+    if (value.data !== undefined && !isObject(value.data))
+        return false;
+    if (value.dataArrayContains !== undefined &&
+        (!isObject(value.dataArrayContains) ||
+            Object.keys(value.dataArrayContains).length === 0 ||
+            Object.entries(value.dataArrayContains).some(([key, member]) => key.length === 0 || typeof member !== 'string' || member.length === 0)))
+        return false;
+    return (value.inactiveForHours === undefined ||
+        (typeof value.inactiveForHours === 'number' &&
+            Number.isFinite(value.inactiveForHours) &&
+            value.inactiveForHours > 0));
+}
+export function isManifest(value) {
+    if (!isObject(value) || value.schemaVersion !== 1 || value.status !== 'complete')
+        return false;
+    if (!isTimestamp(value.createdAt) ||
+        !isTimestamp(value.completedAt) ||
+        !isSelection(value.selection))
+        return false;
+    if (!isObject(value.counts) ||
+        !isCount(value.counts.sessions) ||
+        !isCount(value.counts.entries) ||
+        !isCount(value.counts.records))
+        return false;
+    return (isObject(value.ordering) &&
+        value.ordering.sessions === 'createdAt ascending' &&
+        value.ordering.entries === 'createdAt ascending within session' &&
+        value.consistency === 'best-effort');
+}
+export function isSession(value) {
+    if (isObject(value) &&
+        typeof value.id === 'string' &&
+        value.id.length > 0 &&
+        (value.parentSessionId === null || typeof value.parentSessionId === 'string') &&
+        typeof value.agent === 'string' &&
+        typeof value.version === 'string' &&
+        isTimestamp(value.createdAt) &&
+        (value.lastEntryAt === null || isTimestamp(value.lastEntryAt)) &&
+        value.archivedAt === null &&
+        isObject(value.data)) {
+        try {
+            assertSessionId(value.id);
+            if (value.parentSessionId !== null)
+                assertSessionId(value.parentSessionId, 'parent session id');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}

package/dist/api-contract-discovery/header-contract-parser.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { HeaderContract } from './header-contract-types.mts';
+export declare function parseHeaderContract(sourceFile: ts.SourceFile, node: ts.ObjectLiteralExpression): HeaderContract;

package/dist/api-contract-discovery/header-contract-parser.mjs

@@ -0,0 +1,93 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { contractError } from './response-contract-registration.mjs';
+export function parseHeaderContract(sourceFile, node) {
+    const request = propertyObject(sourceFile, node, 'request');
+    const responses = propertyObject(sourceFile, node, 'responses');
+    return {
+        requestHeaders: request ? parseHeaders(sourceFile, request) : {},
+        responseHeaders: responses ? parseResponses(sourceFile, responses) : {},
+    };
+}
+function parseResponses(sourceFile, node) {
+    const result = {};
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property) ||
+            !ts.isNumericLiteral(property.name) ||
+            !ts.isObjectLiteralExpression(property.initializer))
+            throw contractError(sourceFile, property, 'apiHeaders response status must be a numeric object property');
+        const status = Number(property.name.text);
+        const errors = property.initializer.properties.find((item) => ts.isPropertyAssignment(item) && item.name.getText(sourceFile) === 'errors');
+        const headers = propertyObject(sourceFile, property.initializer, 'headers');
+        const description = stringProperty(property.initializer, 'description');
+        result[status] = {
+            ...(description ? { description } : {}),
+            ...(errors ? { errors: parseErrors(sourceFile, property.initializer) } : {}),
+            headers: headers ? parseHeaders(sourceFile, headers) : {},
+        };
+    }
+    return result;
+}
+function parseErrors(sourceFile, node) {
+    const property = findProperty(node, 'errors', sourceFile);
+    if (!property || !ts.isArrayLiteralExpression(property.initializer))
+        throw contractError(sourceFile, node, 'apiHeaders errors must be an array');
+    return property.initializer.elements.map((element) => {
+        if (!ts.isObjectLiteralExpression(element))
+            throw contractError(sourceFile, element, 'apiHeaders errors entries must be objects');
+        return {
+            code: requiredString(sourceFile, element, 'code'),
+            message: requiredString(sourceFile, element, 'message'),
+        };
+    });
+}
+function parseHeaders(sourceFile, node) {
+    const result = Object.create(null);
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property) ||
+            !ts.isStringLiteral(property.name) ||
+            !ts.isObjectLiteralExpression(property.initializer))
+            throw contractError(sourceFile, property, 'apiHeaders header must be a string-keyed object property');
+        const description = stringProperty(property.initializer, 'description');
+        const format = stringProperty(property.initializer, 'format');
+        result[property.name.text] = {
+            type: requiredString(sourceFile, property.initializer, 'type'),
+            required: booleanProperty(property.initializer, 'required') ?? false,
+            ...(format ? { format: format } : {}),
+            ...(description ? { description } : {}),
+        };
+    }
+    return result;
+}
+function propertyObject(sourceFile, node, name) {
+    const property = findProperty(node, name, sourceFile);
+    if (!property)
+        return undefined;
+    if (!ts.isObjectLiteralExpression(property.initializer))
+        throw contractError(sourceFile, property, `apiHeaders ${name} must be an object`);
+    return property.initializer;
+}
+function stringProperty(node, name) {
+    const property = findProperty(node, name);
+    return property && ts.isStringLiteral(property.initializer)
+        ? property.initializer.text
+        : undefined;
+}
+function requiredString(sourceFile, node, name) {
+    const value = stringProperty(node, name);
+    if (!value)
+        throw contractError(sourceFile, node, `apiHeaders requires string ${name}`);
+    return value;
+}
+function booleanProperty(node, name) {
+    const property = findProperty(node, name);
+    if (!property)
+        return undefined;
+    if (property.initializer.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (property.initializer.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
+function findProperty(node, name, sourceFile) {
+    return node.properties.find((item) => ts.isPropertyAssignment(item) && item.name.getText(sourceFile) === name);
+}

package/dist/api-contract-discovery/header-contract-registry.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { HeaderContractRegistry } from './header-contract-types.mts';
+export declare function discoverApiHeaderContracts(program: ts.Program, sourceFiles: readonly ts.SourceFile[], knownResponseRoutes: ReadonlySet<string>): HeaderContractRegistry;

package/dist/api-contract-discovery/header-contract-registry.mjs

@@ -0,0 +1,38 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { contractError } from './response-contract-registration.mjs';
+import { parseHeaderContract } from './header-contract-parser.mjs';
+import { collectHandlerBindings, enclosingRouteBinding, visit, } from './response-contract-route-analysis.mjs';
+export function discoverApiHeaderContracts(program, sourceFiles, knownResponseRoutes) {
+    const checker = program.getTypeChecker();
+    const bindings = collectHandlerBindings(sourceFiles, checker);
+    const contracts = new Map();
+    const knownOperations = new Set([...knownResponseRoutes].map((key) => key.split('#')[0]));
+    for (const sourceFile of sourceFiles) {
+        visit(sourceFile, (node) => {
+            if (!ts.isCallExpression(node) || !isMarker(node.expression))
+                return;
+            const [keyNode, contractNode] = node.arguments;
+            if (!keyNode ||
+                !ts.isStringLiteral(keyNode) ||
+                !contractNode ||
+                !ts.isObjectLiteralExpression(contractNode)) {
+                throw contractError(sourceFile, node, 'apiHeaders requires a literal operation key and object contract');
+            }
+            const binding = enclosingRouteBinding(node, checker, bindings);
+            if (!binding)
+                throw contractError(sourceFile, node, 'apiHeaders must be inside an app.route handler');
+            const key = `${binding.method}:${binding.routeTemplate}`;
+            if (keyNode.text !== key)
+                throw contractError(sourceFile, keyNode, `Header operation key "${keyNode.text}" does not match enclosing route ${key}`);
+            if (!knownOperations.has(key))
+                throw contractError(sourceFile, keyNode, `apiHeaders references unknown response route ${key}`);
+            if (contracts.has(key))
+                throw contractError(sourceFile, keyNode, `Duplicate apiHeaders marker for ${key}`);
+            contracts.set(key, parseHeaderContract(sourceFile, contractNode));
+        });
+    }
+    return Object.fromEntries([...contracts.entries()].toSorted(([a], [b]) => a.localeCompare(b)));
+}
+function isMarker(expression) {
+    return ts.isIdentifier(expression) && expression.text === 'apiHeaders';
+}

package/dist/api-contract-discovery/header-contract-types.d.mts

@@ -0,0 +1,19 @@
+export type HeaderContract = {
+    requestHeaders: Readonly<Record<string, HeaderDescriptor>>;
+    responseHeaders: Readonly<Record<number, ResponseHeaderDescriptor>>;
+};
+export type HeaderDescriptor = {
+    description?: string;
+    format?: 'uuid';
+    required: boolean;
+    type: 'integer' | 'string';
+};
+export type ResponseHeaderDescriptor = {
+    description?: string;
+    errors?: readonly {
+        code: string;
+        message: string;
+    }[];
+    headers: Readonly<Record<string, HeaderDescriptor>>;
+};
+export type HeaderContractRegistry = Readonly<Record<string, HeaderContract>>;

package/dist/api-contract-discovery/header-contract-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/api-contract-discovery/index.d.mts

@@ -0,0 +1,31 @@
+import type ts from '../contract-schema/typescript-api.mts';
+import type { DiscoverApiResponseContractsOptions } from './response-contract-lenient.mts';
+export declare const APP_ROUTE_CTX_ADAPTER_VERSION: 1;
+export type AppRouteCtxDiscoveryInput = {
+    program: ts.Program;
+    sourceFiles: readonly ts.SourceFile[];
+    requestedKeys?: ReadonlySet<string>;
+    options?: DiscoverApiResponseContractsOptions;
+};
+/** Discovers the version-one `app.route(...).method(handler)` and `ctx` convention. */
+export declare function discoverAppRouteCtxContractsV1(input: AppRouteCtxDiscoveryInput): {
+    adapterVersion: 1;
+    routes: import("./registered-route-catalog.mts").RegisteredRoute[];
+    responses: Record<string, import("./response-contract-types.mts").BackendResponseContract>;
+    requests: Record<string, import("./request-contract-types.mts").BackendRequestContract>;
+    queries: Readonly<Record<string, import("./query-contract-types.mts").BackendQueryContract>>;
+    headers: Readonly<Record<string, import("./header-contract-types.mts").HeaderContract>>;
+};
+export { discoverApiResponseContracts } from './response-contract-registry.mts';
+export { discoverApiRequestContracts } from './request-contract-registry.mts';
+export { discoverApiQueryContracts } from './query-contract-registry.mts';
+export { discoverApiHeaderContracts } from './header-contract-registry.mts';
+export { discoverRegisteredRoutes, routeShape } from './registered-route-catalog.mts';
+export { responseStatusCodesForContract } from './response-contract-status.mts';
+export type { BackendResponseContract } from './response-contract-types.mts';
+export type { BackendRequestContract } from './request-contract-types.mts';
+export type { BackendQueryContract, BackendQueryContractRegistry } from './query-contract-types.mts';
+export type { HeaderContract, HeaderContractRegistry } from './header-contract-types.mts';
+export type { RegisteredRoute } from './registered-route-catalog.mts';
+export type { RouteDiscoveryError, DiscoverApiResponseContractsOptions, } from './response-contract-lenient.mts';
+export type { DiscoverApiRequestContractsOptions } from './request-contract-lenient.mts';

package/dist/api-contract-discovery/index.mjs

@@ -0,0 +1,26 @@
+import { discoverApiHeaderContracts } from './header-contract-registry.mjs';
+import { discoverApiQueryContracts } from './query-contract-registry.mjs';
+import { discoverRegisteredRoutes } from './registered-route-catalog.mjs';
+import { discoverApiRequestContracts } from './request-contract-registry.mjs';
+import { discoverApiResponseContracts } from './response-contract-registry.mjs';
+export const APP_ROUTE_CTX_ADAPTER_VERSION = 1;
+/** Discovers the version-one `app.route(...).method(handler)` and `ctx` convention. */
+export function discoverAppRouteCtxContractsV1(input) {
+    const { program, sourceFiles, requestedKeys, options } = input;
+    const responses = discoverApiResponseContracts(program, sourceFiles, requestedKeys, options);
+    const knownResponseRoutes = new Set(Object.keys(responses));
+    return {
+        adapterVersion: APP_ROUTE_CTX_ADAPTER_VERSION,
+        routes: discoverRegisteredRoutes(program, sourceFiles),
+        responses,
+        requests: discoverApiRequestContracts(program, sourceFiles, requestedKeys, options),
+        queries: discoverApiQueryContracts(program, sourceFiles, knownResponseRoutes),
+        headers: discoverApiHeaderContracts(program, sourceFiles, knownResponseRoutes),
+    };
+}
+export { discoverApiResponseContracts } from './response-contract-registry.mjs';
+export { discoverApiRequestContracts } from './request-contract-registry.mjs';
+export { discoverApiQueryContracts } from './query-contract-registry.mjs';
+export { discoverApiHeaderContracts } from './header-contract-registry.mjs';
+export { discoverRegisteredRoutes, routeShape } from './registered-route-catalog.mjs';
+export { responseStatusCodesForContract } from './response-contract-status.mjs';

package/dist/api-contract-discovery/query-contract-extraction.d.mts

@@ -0,0 +1,3 @@
+import type { QueryParameterContract } from './query-contract-types.mts';
+import ts from '../contract-schema/typescript-api.mts';
+export declare function extractQueryParameterDescriptor(type: ts.Type, checker: ts.TypeChecker, sourceFile: ts.SourceFile, node: ts.Node, parameterName: string): QueryParameterContract;

package/dist/api-contract-discovery/query-contract-extraction.mjs

@@ -0,0 +1,65 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { contractError } from './response-contract-registration.mjs';
+import { optionalNumberLiteral, optionalStringLiteral, requiredBooleanLiteral, requiredNumberLiteral, requiredPropertyType, requiredStringLiteral, stringTuple, } from './query-contract-literals.mjs';
+export function extractQueryParameterDescriptor(type, checker, sourceFile, node, parameterName) {
+    const fail = (detail) => {
+        throw contractError(sourceFile, node, `Malformed query parameter "${parameterName}": ${detail}`);
+    };
+    const kind = requiredStringLiteral(type, 'kind', checker, fail);
+    const description = optionalStringLiteral(type, 'description', checker, node, fail);
+    const options = description === undefined ? {} : { description };
+    if (kind === 'string') {
+        const format = optionalStringLiteral(type, 'format', checker, node, fail);
+        if (format === 'uuid')
+            return { kind, format, ...options };
+        if (format === 'uri')
+            return { kind, format, ...options };
+        if (format !== undefined)
+            fail('unsupported format');
+        return { kind, ...options };
+    }
+    if (kind === 'uuid-or-uri' ||
+        kind === 'boolean' ||
+        kind === 'nullable-boolean' ||
+        kind === 'number') {
+        return { kind, ...options };
+    }
+    if (kind === 'integer') {
+        const minimum = requiredNumberLiteral(type, 'minimum', checker, fail);
+        const maximum = requiredNumberLiteral(type, 'maximum', checker, fail);
+        const defaultValue = optionalNumberLiteral(type, 'default', checker, node, fail);
+        return {
+            kind,
+            minimum,
+            maximum,
+            ...(defaultValue === undefined ? {} : { default: defaultValue }),
+            ...options,
+        };
+    }
+    if (kind === 'enum') {
+        const values = stringTuple(type, 'values', checker, fail);
+        const defaultValue = optionalStringLiteral(type, 'default', checker, node, fail);
+        if (defaultValue !== undefined && !values.includes(defaultValue)) {
+            fail('default must be one of values');
+        }
+        return {
+            kind,
+            values,
+            ...(defaultValue === undefined ? {} : { default: defaultValue }),
+            ...options,
+        };
+    }
+    if (kind === 'csv-array') {
+        if (requiredStringLiteral(type, 'style', checker, fail) !== 'form')
+            fail('style must be form');
+        if (requiredBooleanLiteral(type, 'explode', checker, fail) !== false)
+            fail('explode must be false');
+        const itemType = requiredPropertyType(type, 'items', checker, fail);
+        const items = extractQueryParameterDescriptor(itemType, checker, sourceFile, node, `${parameterName}[]`);
+        if (items.kind === 'string' || items.kind === 'enum') {
+            return { kind, items, style: 'form', explode: false, ...options };
+        }
+        return fail('array items must be string or enum');
+    }
+    return fail(`unsupported kind "${kind}"`);
+}

package/dist/api-contract-discovery/query-contract-literals.d.mts

@@ -0,0 +1,8 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function requiredPropertyType(type: ts.Type, name: string, checker: ts.TypeChecker, fail: (detail: string) => never): ts.Type;
+export declare function requiredStringLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, fail: (detail: string) => never): string;
+export declare function requiredNumberLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, fail: (detail: string) => never): number;
+export declare function requiredBooleanLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, fail: (detail: string) => never): boolean;
+export declare function optionalStringLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, node: ts.Node, fail: (detail: string) => never): string | undefined;
+export declare function optionalNumberLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, node: ts.Node, fail: (detail: string) => never): number | undefined;
+export declare function stringTuple(type: ts.Type, name: string, checker: ts.TypeChecker, fail: (detail: string) => never): readonly string[];

package/dist/api-contract-discovery/query-contract-literals.mjs

@@ -0,0 +1,54 @@
+import ts from '../contract-schema/typescript-api.mjs';
+export function requiredPropertyType(type, name, checker, fail) {
+    const property = type.getProperty(name);
+    if (!property || property.flags & ts.SymbolFlags.Optional)
+        return fail(`requires literal ${name}`);
+    const location = property.valueDeclaration ?? property.declarations?.[0];
+    if (!location)
+        return fail(`requires declared ${name}`);
+    return checker.getTypeOfSymbolAtLocation(property, location);
+}
+export function requiredStringLiteral(type, name, checker, fail) {
+    const value = requiredPropertyType(type, name, checker, fail);
+    return value.isStringLiteral() ? value.value : fail(`requires literal ${name}`);
+}
+export function requiredNumberLiteral(type, name, checker, fail) {
+    const value = requiredPropertyType(type, name, checker, fail);
+    return value.isNumberLiteral() ? value.value : fail(`requires literal ${name}`);
+}
+export function requiredBooleanLiteral(type, name, checker, fail) {
+    const value = requiredPropertyType(type, name, checker, fail);
+    if (value.flags & ts.TypeFlags.BooleanLiteral)
+        return checker.typeToString(value) === 'true';
+    return fail(`requires literal ${name}`);
+}
+export function optionalStringLiteral(type, name, checker, node, fail) {
+    const property = type.getProperty(name);
+    if (!property)
+        return undefined;
+    if (property.flags & ts.SymbolFlags.Optional)
+        return fail(`${name} must be literal when present`);
+    const location = property.valueDeclaration ?? property.declarations?.[0] ?? node;
+    const value = checker.getTypeOfSymbolAtLocation(property, location);
+    return value.isStringLiteral() ? value.value : fail(`requires literal ${name}`);
+}
+export function optionalNumberLiteral(type, name, checker, node, fail) {
+    const property = type.getProperty(name);
+    if (!property)
+        return undefined;
+    if (property.flags & ts.SymbolFlags.Optional)
+        return fail(`${name} must be literal when present`);
+    const location = property.valueDeclaration ?? property.declarations?.[0] ?? node;
+    const value = checker.getTypeOfSymbolAtLocation(property, location);
+    return value.isNumberLiteral() ? value.value : fail(`requires literal ${name}`);
+}
+export function stringTuple(type, name, checker, fail) {
+    const value = requiredPropertyType(type, name, checker, fail);
+    if (!checker.isTupleType(value))
+        return fail(`${name} must be a literal tuple`);
+    const values = checker.getTypeArguments(value);
+    if (values.length === 0 || values.some((item) => !item.isStringLiteral())) {
+        return fail(`${name} must contain string literals`);
+    }
+    return values.map((item) => item.value);
+}

package/dist/api-contract-discovery/query-contract-registry.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { BackendQueryContractRegistry } from './query-contract-types.mts';
+export declare function discoverApiQueryContracts(program: ts.Program, sourceFiles: readonly ts.SourceFile[], knownResponseRoutes: ReadonlySet<string>): BackendQueryContractRegistry;