glirastes 0.4.0 → 0.5.1

package/dist/cjs/codegen/execution-inventory.js

@@ -0,0 +1,312 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FoundationExecutionInventorySchema = void 0;
+exports.discoverFoundationExecutions = discoverFoundationExecutions;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const zod_1 = require("zod");
+const typescript_1 = __importDefault(require("typescript"));
+const openapi_document_js_1 = require("./openapi-document.js");
+const route_fingerprint_js_1 = require("./route-fingerprint.js");
+const route_exports_js_1 = require("./route-exports.js");
+const nest_decorators_js_1 = require("./tools/sources/nest-decorators.js");
+const uuid = zod_1.z.uuid();
+const identifier = zod_1.z.string().trim().min(1).max(200);
+const digest = zod_1.z.string().regex(/^sha256:(?:[A-Za-z0-9_-]{43}|[A-Za-z0-9+/]{43}=)$/);
+const executionBase = zod_1.z.object({
+    toolId: uuid,
+    definitionId: identifier,
+    stableKey: zod_1.z.string().trim().min(1).max(2_100),
+    sourceFingerprint: digest,
+    inputSchemaDigest: digest,
+    outputSchemaDigest: digest,
+});
+const endpointExecution = executionBase.extend({
+    executionKind: zod_1.z.literal('endpoint'),
+    /**
+     * The deterministic source that enumerated the endpoint. Absent on
+     * inventories written before the tools generator; treated as next-app.
+     */
+    sourceKind: zod_1.z.enum(['next-app', 'nest', 'openapi']).optional(),
+    sourceFile: zod_1.z.string().trim().min(1).max(2_048),
+    method: zod_1.z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']),
+    path: zod_1.z.string().startsWith('/').max(2_048),
+}).strict();
+const uiExecution = executionBase.extend({
+    executionKind: zod_1.z.literal('ui'),
+    actionBindingRef: identifier,
+    /**
+     * The identifier the client handler registers with. It differs from the
+     * definition id, and it is the only way to find the code that actually runs
+     * an action, so an assessment can read it instead of guessing from a name.
+     */
+    actionId: identifier.optional(),
+}).strict();
+exports.FoundationExecutionInventorySchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(2),
+    targetAppKey: identifier,
+    executions: zod_1.z.array(zod_1.z.discriminatedUnion('executionKind', [
+        endpointExecution,
+        uiExecution,
+    ])).max(5_000),
+}).strict();
+function canonicalValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalValue(child)]));
+}
+function canonicalInventory(inventory) {
+    return {
+        ...inventory,
+        executions: [...inventory.executions]
+            .sort((left, right) => left.toolId.localeCompare(right.toolId)),
+    };
+}
+function assertUniqueInventory(inventory) {
+    const toolIds = new Set();
+    const stableKeys = new Set();
+    const fingerprints = new Map();
+    for (const execution of inventory.executions) {
+        if (toolIds.has(execution.toolId)) {
+            throw new Error('Foundation inventory contains a duplicate tool UUID');
+        }
+        if (stableKeys.has(execution.stableKey)) {
+            throw new Error('Foundation inventory contains a duplicate stable key');
+        }
+        const fingerprintOwner = fingerprints.get(execution.sourceFingerprint);
+        if (fingerprintOwner && fingerprintOwner !== execution.stableKey) {
+            throw new Error('Foundation inventory contains a conflicting source fingerprint');
+        }
+        toolIds.add(execution.toolId);
+        stableKeys.add(execution.stableKey);
+        fingerprints.set(execution.sourceFingerprint, execution.stableKey);
+    }
+}
+async function verifyNextEndpoint(rootDir, execution) {
+    let source;
+    try {
+        source = await (0, promises_1.readFile)((0, node_path_1.resolve)(rootDir, execution.sourceFile), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Foundation inventory references a missing route: ${execution.stableKey}`);
+        }
+        throw error;
+    }
+    // A wrapper export (`export const GET = withAuth(…)`) exists even though the
+    // reader cannot resolve its body; the fingerprint below still pins the file.
+    const routeExports = (0, route_exports_js_1.readRouteExports)(source, execution.sourceFile);
+    const declared = routeExports.exports.some(({ method }) => method === execution.method)
+        || routeExports.findings.some((finding) => (finding.code === 'route-export-unresolved' && finding.exportName === execution.method));
+    if (!declared) {
+        throw new Error(`Foundation inventory references a missing route export: ${execution.stableKey}`);
+    }
+    const expectedStableKey = `${execution.method} ${execution.path}`;
+    if (execution.stableKey !== expectedStableKey) {
+        throw new Error(`Foundation inventory stable key mismatch: ${execution.stableKey}`);
+    }
+    const currentFingerprint = (0, route_fingerprint_js_1.createRouteSourceFingerprint)(source, execution.method, execution.path);
+    if (currentFingerprint !== execution.sourceFingerprint) {
+        throw new Error(`Foundation route fingerprint mismatch: ${execution.stableKey}`);
+    }
+    return {
+        ...execution,
+        sourceLocator: {
+            sourceFile: execution.sourceFile,
+            exportName: execution.method,
+        },
+    };
+}
+/**
+ * Whether a `@Controller` class of the file declares a handler of this HTTP
+ * method. It reads decorators exactly as the Nest source does, through a named
+ * or a namespace import of `@nestjs/common`. The full path joins the global
+ * prefix of another file, so the fingerprint, not this check, pins the path.
+ */
+function declaresNestMethod(source, fileName, method) {
+    const file = typescript_1.default.createSourceFile(fileName, source, typescript_1.default.ScriptTarget.Latest, true);
+    const imports = (0, nest_decorators_js_1.readImports)(file);
+    const names = (node) => (0, nest_decorators_js_1.decoratorsOf)(node, imports).map(({ name }) => name);
+    return file.statements.some((statement) => (typescript_1.default.isClassDeclaration(statement) && names(statement).includes('Controller')
+        && statement.members.some((member) => (typescript_1.default.isMethodDeclaration(member) && names(member).some((name) => nest_decorators_js_1.NEST_METHOD_DECORATORS[name] === method)))));
+}
+async function verifyNestEndpoint(rootDir, execution) {
+    let source;
+    try {
+        source = await (0, promises_1.readFile)((0, node_path_1.resolve)(rootDir, execution.sourceFile), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Foundation inventory references a missing controller: ${execution.stableKey}`);
+        }
+        throw error;
+    }
+    if (!declaresNestMethod(source, execution.sourceFile, execution.method)) {
+        throw new Error(`Foundation inventory references a missing controller method: ${execution.stableKey}`);
+    }
+    if (execution.stableKey !== `${execution.method} ${execution.path}`) {
+        throw new Error(`Foundation inventory stable key mismatch: ${execution.stableKey}`);
+    }
+    if ((0, route_fingerprint_js_1.createRouteSourceFingerprint)(source, execution.method, execution.path) !== execution.sourceFingerprint) {
+        throw new Error(`Foundation route fingerprint mismatch: ${execution.stableKey}`);
+    }
+    return { ...execution, sourceLocator: { sourceFile: execution.sourceFile, exportName: execution.method } };
+}
+async function verifyOpenapiEndpoint(rootDir, execution) {
+    let text;
+    try {
+        text = await (0, promises_1.readFile)((0, node_path_1.resolve)(rootDir, execution.sourceFile), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Foundation inventory references a missing OpenAPI document: ${execution.stableKey}`);
+        }
+        throw error;
+    }
+    const parsed = (0, openapi_document_js_1.parseOpenapiDocument)(text);
+    const operation = parsed.ok
+        ? (0, openapi_document_js_1.operationsOf)(parsed.document).find((candidate) => (candidate.path === execution.path && candidate.operationKey === execution.method.toLowerCase()))
+        : undefined;
+    if (!parsed.ok || !operation) {
+        throw new Error(`Foundation inventory references a missing OpenAPI operation: ${execution.stableKey}`);
+    }
+    if (execution.stableKey !== `${execution.method} ${execution.path}`) {
+        throw new Error(`Foundation inventory stable key mismatch: ${execution.stableKey}`);
+    }
+    if ((0, openapi_document_js_1.operationFingerprint)(parsed.document, operation, execution.method, execution.path) !== execution.sourceFingerprint) {
+        throw new Error(`Foundation route fingerprint mismatch: ${execution.stableKey}`);
+    }
+    return { ...execution, sourceLocator: { sourceFile: execution.sourceFile, exportName: execution.method } };
+}
+async function verifyEndpoint(rootDir, execution) {
+    const kind = execution.sourceKind ?? 'next-app';
+    if (kind === 'next-app')
+        return verifyNextEndpoint(rootDir, execution);
+    if (kind === 'nest')
+        return verifyNestEndpoint(rootDir, execution);
+    if (kind === 'openapi')
+        return verifyOpenapiEndpoint(rootDir, execution);
+    throw new Error(`Unsupported endpoint source kind: ${String(kind)}`);
+}
+/**
+ * Read literal registrations from syntax, never comments or example strings.
+ * This is source evidence, not proof that the component mounts at runtime.
+ */
+function registeredActionIds(source, fileName) {
+    const file = typescript_1.default.createSourceFile(fileName, source, typescript_1.default.ScriptTarget.Latest, true);
+    const hooks = new Map([['useAiClientAction', 0], ['useAiClientActionById', 1]]);
+    const aliases = new Map(hooks);
+    const namespaces = new Set();
+    for (const node of file.statements) {
+        if (!typescript_1.default.isImportDeclaration(node) || !typescript_1.default.isStringLiteral(node.moduleSpecifier)
+            || node.moduleSpecifier.text !== 'glirastes/react' || node.importClause?.isTypeOnly)
+            continue;
+        const bindings = node.importClause?.namedBindings;
+        if (bindings && typescript_1.default.isNamespaceImport(bindings))
+            namespaces.add(bindings.name.text);
+        if (bindings && typescript_1.default.isNamedImports(bindings)) {
+            for (const entry of bindings.elements) {
+                const argument = hooks.get((entry.propertyName ?? entry.name).text);
+                if (!entry.isTypeOnly && argument !== undefined)
+                    aliases.set(entry.name.text, argument);
+            }
+        }
+    }
+    const ids = new Set();
+    const visit = (node) => {
+        if (typescript_1.default.isCallExpression(node)) {
+            const callee = node.expression;
+            const argument = typescript_1.default.isIdentifier(callee) ? aliases.get(callee.text)
+                : typescript_1.default.isPropertyAccessExpression(callee) && typescript_1.default.isIdentifier(callee.expression)
+                    && namespaces.has(callee.expression.text) ? hooks.get(callee.name.text) : undefined;
+            const value = argument === undefined ? undefined : node.arguments[argument];
+            if (value && typescript_1.default.isStringLiteralLike(value))
+                ids.add(value.text);
+        }
+        typescript_1.default.forEachChild(node, visit);
+    };
+    visit(file);
+    return ids;
+}
+/** Index once per discovery, not once per UI tool. Generated files are mirrors. */
+async function findActionHandlers(rootDir) {
+    const matches = new Map();
+    const walk = async (relative) => {
+        const entries = await (0, promises_1.readdir)((0, node_path_1.resolve)(rootDir, relative), {
+            withFileTypes: true,
+        }).catch(() => []);
+        for (const entry of entries) {
+            const next = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+                    continue;
+                if (entry.name === 'generated')
+                    continue;
+                await walk(next);
+                continue;
+            }
+            if (!/\.(tsx?|jsx?)$/.test(entry.name))
+                continue;
+            const source = await (0, promises_1.readFile)((0, node_path_1.resolve)(rootDir, next), 'utf8')
+                .catch(() => '');
+            if (!source.includes('useAiClientAction'))
+                continue;
+            for (const actionId of registeredActionIds(source, next)) {
+                const previous = matches.get(actionId);
+                if (!previous || next < previous)
+                    matches.set(actionId, next);
+            }
+        }
+    };
+    await walk('');
+    return matches;
+}
+async function discoverFoundationExecutions(options) {
+    const parsed = exports.FoundationExecutionInventorySchema.parse(options.inventory);
+    assertUniqueInventory(parsed);
+    const inventory = canonicalInventory(parsed);
+    const executions = [];
+    const handlers = inventory.executions.some((execution) => execution.executionKind === 'ui' && execution.actionId)
+        ? await findActionHandlers(options.rootDir) : new Map();
+    const findings = [];
+    for (const execution of inventory.executions) {
+        if (execution.executionKind === 'endpoint') {
+            executions.push(await verifyEndpoint(options.rootDir, execution));
+            continue;
+        }
+        const sourceFile = execution.actionId
+            ? handlers.get(execution.actionId)
+            : null;
+        if (execution.actionId && !sourceFile) {
+            findings.push({
+                code: 'ui-action-handler-not-found',
+                subjectRef: execution.definitionId,
+            });
+        }
+        executions.push({
+            ...execution,
+            sourceLocator: {
+                actionBindingRef: execution.actionBindingRef,
+                ...(sourceFile ? { sourceFile } : {}),
+            },
+        });
+    }
+    const canonicalJson = JSON.stringify(canonicalValue(inventory));
+    return {
+        schemaVersion: 2,
+        targetAppKey: inventory.targetAppKey,
+        inventoryDigest: `sha256:${(0, node_crypto_1.createHash)('sha256')
+            .update(canonicalJson)
+            .digest('base64url')}`,
+        executions,
+        findings,
+    };
+}

package/dist/cjs/codegen/index.d.ts

@@ -1,13 +1,4 @@
-export { scanEndpointTools, generateEndpointRegistry } from './endpoint-scanner.js';
-export { scanUiTools, generateUiRegistry, generateActionIdRegistry } from './ui-scanner.js';
-export { generateModuleRegistry } from './module-generator.js';
-export { validateAiTools, formatValidationReport, type ValidationResult, type ValidationIssue } from './validator.js';
-export { checkAiCoverage, formatCoverageReport, type CoverageReport } from './coverage.js';
-export { scaffoldAiTool, formatScaffoldResult, type ScaffoldResult } from './scaffolder.js';
-export { colors } from './format.js';
-export { generateAgentSkills, type GenerateSkillsOptions, type GenerateSkillsResult } from './skill-generator.js';
-export { generateMcpServer, type GenerateMcpOptions, type GenerateMcpResult } from './mcp-generator.js';
-export { recommendOutputFormat, type OutputFormat, type RecommendationInput } from './output-recommender.js';
-export { syncAssetToGlirastes, type AssetSyncOptions, type AssetSyncResult } from './asset-sync.js';
-export { scanNestControllers, type DiscoveredNestTool, type NestScanResult } from './nestjs-scanner.js';
-export type { ScanResult, GenerateOptions } from './types.js';
+export { createRouteSourceFingerprint, scanNextAppRoutes, writeNextAppRouteScan, type NextAppRouteScanResult, type ScannedRouteCandidate, type ScanNextAppRoutesOptions, type WriteNextAppRouteScanOptions, } from './route-scanner.js';
+export { discoverFoundationExecutions, FoundationExecutionInventorySchema, type DiscoveredFoundationExecution, type FoundationExecutionDiscovery, type FoundationExecutionInventory, } from './execution-inventory.js';
+export { reconcileExecutionInventory, ExecutionGenerationStateSchema, type ExecutionGenerationState, type ExecutionGenerationResult, type ObservedExecution, } from './inventory-generation.js';
+export { collectNextEndpointExecutions, type ResolvedEndpointContract } from './next-source-generation.js';

package/dist/cjs/codegen/index.js

@@ -1,33 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scanNestControllers = exports.syncAssetToGlirastes = exports.recommendOutputFormat = exports.generateMcpServer = exports.generateAgentSkills = exports.colors = exports.formatScaffoldResult = exports.scaffoldAiTool = exports.formatCoverageReport = exports.checkAiCoverage = exports.formatValidationReport = exports.validateAiTools = exports.generateModuleRegistry = exports.generateActionIdRegistry = exports.generateUiRegistry = exports.scanUiTools = exports.generateEndpointRegistry = exports.scanEndpointTools = void 0;
-var endpoint_scanner_js_1 = require("./endpoint-scanner.js");
-Object.defineProperty(exports, "scanEndpointTools", { enumerable: true, get: function () { return endpoint_scanner_js_1.scanEndpointTools; } });
-Object.defineProperty(exports, "generateEndpointRegistry", { enumerable: true, get: function () { return endpoint_scanner_js_1.generateEndpointRegistry; } });
-var ui_scanner_js_1 = require("./ui-scanner.js");
-Object.defineProperty(exports, "scanUiTools", { enumerable: true, get: function () { return ui_scanner_js_1.scanUiTools; } });
-Object.defineProperty(exports, "generateUiRegistry", { enumerable: true, get: function () { return ui_scanner_js_1.generateUiRegistry; } });
-Object.defineProperty(exports, "generateActionIdRegistry", { enumerable: true, get: function () { return ui_scanner_js_1.generateActionIdRegistry; } });
-var module_generator_js_1 = require("./module-generator.js");
-Object.defineProperty(exports, "generateModuleRegistry", { enumerable: true, get: function () { return module_generator_js_1.generateModuleRegistry; } });
-var validator_js_1 = require("./validator.js");
-Object.defineProperty(exports, "validateAiTools", { enumerable: true, get: function () { return validator_js_1.validateAiTools; } });
-Object.defineProperty(exports, "formatValidationReport", { enumerable: true, get: function () { return validator_js_1.formatValidationReport; } });
-var coverage_js_1 = require("./coverage.js");
-Object.defineProperty(exports, "checkAiCoverage", { enumerable: true, get: function () { return coverage_js_1.checkAiCoverage; } });
-Object.defineProperty(exports, "formatCoverageReport", { enumerable: true, get: function () { return coverage_js_1.formatCoverageReport; } });
-var scaffolder_js_1 = require("./scaffolder.js");
-Object.defineProperty(exports, "scaffoldAiTool", { enumerable: true, get: function () { return scaffolder_js_1.scaffoldAiTool; } });
-Object.defineProperty(exports, "formatScaffoldResult", { enumerable: true, get: function () { return scaffolder_js_1.formatScaffoldResult; } });
-var format_js_1 = require("./format.js");
-Object.defineProperty(exports, "colors", { enumerable: true, get: function () { return format_js_1.colors; } });
-var skill_generator_js_1 = require("./skill-generator.js");
-Object.defineProperty(exports, "generateAgentSkills", { enumerable: true, get: function () { return skill_generator_js_1.generateAgentSkills; } });
-var mcp_generator_js_1 = require("./mcp-generator.js");
-Object.defineProperty(exports, "generateMcpServer", { enumerable: true, get: function () { return mcp_generator_js_1.generateMcpServer; } });
-var output_recommender_js_1 = require("./output-recommender.js");
-Object.defineProperty(exports, "recommendOutputFormat", { enumerable: true, get: function () { return output_recommender_js_1.recommendOutputFormat; } });
-var asset_sync_js_1 = require("./asset-sync.js");
-Object.defineProperty(exports, "syncAssetToGlirastes", { enumerable: true, get: function () { return asset_sync_js_1.syncAssetToGlirastes; } });
-var nestjs_scanner_js_1 = require("./nestjs-scanner.js");
-Object.defineProperty(exports, "scanNestControllers", { enumerable: true, get: function () { return nestjs_scanner_js_1.scanNestControllers; } });
+exports.collectNextEndpointExecutions = exports.ExecutionGenerationStateSchema = exports.reconcileExecutionInventory = exports.FoundationExecutionInventorySchema = exports.discoverFoundationExecutions = exports.writeNextAppRouteScan = exports.scanNextAppRoutes = exports.createRouteSourceFingerprint = void 0;
+var route_scanner_js_1 = require("./route-scanner.js");
+Object.defineProperty(exports, "createRouteSourceFingerprint", { enumerable: true, get: function () { return route_scanner_js_1.createRouteSourceFingerprint; } });
+Object.defineProperty(exports, "scanNextAppRoutes", { enumerable: true, get: function () { return route_scanner_js_1.scanNextAppRoutes; } });
+Object.defineProperty(exports, "writeNextAppRouteScan", { enumerable: true, get: function () { return route_scanner_js_1.writeNextAppRouteScan; } });
+var execution_inventory_js_1 = require("./execution-inventory.js");
+Object.defineProperty(exports, "discoverFoundationExecutions", { enumerable: true, get: function () { return execution_inventory_js_1.discoverFoundationExecutions; } });
+Object.defineProperty(exports, "FoundationExecutionInventorySchema", { enumerable: true, get: function () { return execution_inventory_js_1.FoundationExecutionInventorySchema; } });
+var inventory_generation_js_1 = require("./inventory-generation.js");
+Object.defineProperty(exports, "reconcileExecutionInventory", { enumerable: true, get: function () { return inventory_generation_js_1.reconcileExecutionInventory; } });
+Object.defineProperty(exports, "ExecutionGenerationStateSchema", { enumerable: true, get: function () { return inventory_generation_js_1.ExecutionGenerationStateSchema; } });
+var next_source_generation_js_1 = require("./next-source-generation.js");
+Object.defineProperty(exports, "collectNextEndpointExecutions", { enumerable: true, get: function () { return next_source_generation_js_1.collectNextEndpointExecutions; } });

package/dist/cjs/codegen/inventory-generation.d.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+declare const ObservationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    path: z.ZodString;
+    method: z.ZodEnum<{
+        GET: "GET";
+        HEAD: "HEAD";
+        POST: "POST";
+        PATCH: "PATCH";
+        PUT: "PUT";
+        DELETE: "DELETE";
+    }>;
+    sourceFingerprint: z.ZodString;
+    inputSchemaDigest: z.ZodString;
+    outputSchemaDigest: z.ZodString;
+    executionKind: z.ZodLiteral<"endpoint">;
+    stableKey: z.ZodString;
+    definitionId: z.ZodString;
+    sourceKind: z.ZodOptional<z.ZodEnum<{
+        openapi: "openapi";
+        "next-app": "next-app";
+        nest: "nest";
+    }>>;
+    sourceFile: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    actionId: z.ZodOptional<z.ZodString>;
+    sourceFingerprint: z.ZodString;
+    inputSchemaDigest: z.ZodString;
+    outputSchemaDigest: z.ZodString;
+    executionKind: z.ZodLiteral<"ui">;
+    actionBindingRef: z.ZodString;
+    stableKey: z.ZodString;
+    definitionId: z.ZodString;
+}, z.core.$strict>], "executionKind">;
+/** App-local generation state; never upload this source-bearing object. */
+export declare const ExecutionGenerationStateSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    appId: z.ZodUUID;
+    inventory: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<2>;
+        targetAppKey: z.ZodString;
+        executions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            toolId: z.ZodUUID;
+            definitionId: z.ZodString;
+            stableKey: z.ZodString;
+            sourceFingerprint: z.ZodString;
+            inputSchemaDigest: z.ZodString;
+            outputSchemaDigest: z.ZodString;
+            executionKind: z.ZodLiteral<"endpoint">;
+            sourceKind: z.ZodOptional<z.ZodEnum<{
+                openapi: "openapi";
+                "next-app": "next-app";
+                nest: "nest";
+            }>>;
+            sourceFile: z.ZodString;
+            method: z.ZodEnum<{
+                GET: "GET";
+                HEAD: "HEAD";
+                POST: "POST";
+                PATCH: "PATCH";
+                PUT: "PUT";
+                DELETE: "DELETE";
+            }>;
+            path: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            toolId: z.ZodUUID;
+            definitionId: z.ZodString;
+            stableKey: z.ZodString;
+            sourceFingerprint: z.ZodString;
+            inputSchemaDigest: z.ZodString;
+            outputSchemaDigest: z.ZodString;
+            executionKind: z.ZodLiteral<"ui">;
+            actionBindingRef: z.ZodString;
+            actionId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "executionKind">>;
+    }, z.core.$strict>;
+    tombstones: z.ZodArray<z.ZodObject<{
+        toolId: z.ZodUUID;
+        stableKey: z.ZodString;
+        definitionId: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ExecutionGenerationState = z.infer<typeof ExecutionGenerationStateSchema>;
+export type ObservedExecution = z.infer<typeof ObservationSchema>;
+export interface ExecutionGenerationResult {
+    state: ExecutionGenerationState;
+    changes: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+        unchanged: string[];
+    };
+}
+/**
+ * Reconcile a complete source-adapter snapshot. Does not assess semantics,
+ * grant permissions, write files, sync, or claim executable-source verification.
+ * Callers must persist state (including tombstones) and validate real sources.
+ */
+export declare function reconcileExecutionInventory(options: {
+    appId: string;
+    targetAppKey: string;
+    observed: unknown;
+    previous?: unknown;
+}): ExecutionGenerationResult;
+export {};

package/dist/cjs/codegen/inventory-generation.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionGenerationStateSchema = void 0;
+exports.reconcileExecutionInventory = reconcileExecutionInventory;
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+const index_js_1 = require("../diagnostics/index.js");
+const execution_inventory_js_1 = require("./execution-inventory.js");
+const [endpoint, ui] = execution_inventory_js_1.FoundationExecutionInventorySchema.shape.executions.element.options;
+const ObservationSchema = zod_1.z.discriminatedUnion('executionKind', [
+    endpoint.omit({ toolId: true }), ui.omit({ toolId: true }),
+]);
+const SnapshotSchema = zod_1.z.object({
+    complete: zod_1.z.boolean(), executions: zod_1.z.array(ObservationSchema).max(5_000),
+}).strict();
+const TombstoneSchema = zod_1.z.object({
+    toolId: zod_1.z.uuid(), stableKey: zod_1.z.string().min(1).max(2_100),
+    definitionId: zod_1.z.string().min(1).max(200),
+}).strict();
+/** App-local generation state; never upload this source-bearing object. */
+exports.ExecutionGenerationStateSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1), appId: zod_1.z.uuid(),
+    inventory: execution_inventory_js_1.FoundationExecutionInventorySchema,
+    tombstones: zod_1.z.array(TombstoneSchema).max(100_000),
+}).strict();
+function fail(message, remediation) {
+    throw new index_js_1.FoundationDiagnosticError({
+        code: 'E-INVENTORY-010', operation: 'generate.inventory', message, remediation,
+    });
+}
+function canonical(value) {
+    const sort = (item) => Array.isArray(item) ? item.map(sort)
+        : item && typeof item === 'object'
+            ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+                .map(([key, child]) => [key, sort(child)])) : item;
+    return JSON.stringify(sort(value));
+}
+// UUIDv5 scoped to app + target + stable key + removal generation. Reappearance
+// is a new identity, not revival of an old authorization/approval reference.
+function newIdentity(appId, target, key, generation) {
+    const bytes = (0, node_crypto_1.createHash)('sha1').update(Buffer.from(appId.replaceAll('-', ''), 'hex'))
+        .update(JSON.stringify(['glirastes.execution.v1', target, key, generation])).digest().subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function assertUnique(entries) {
+    const keys = new Set();
+    const names = new Set();
+    const fingerprints = new Set();
+    for (const entry of entries) {
+        if (keys.has(entry.stableKey) || names.has(entry.definitionId)) {
+            fail('Duplicate execution keys or definition names.', 'repair-source-observations');
+        }
+        if (fingerprints.has(entry.sourceFingerprint)) {
+            fail('Conflicting source fingerprint.', 'repair-source-observations');
+        }
+        if (entry.executionKind === 'endpoint' && entry.stableKey !== `${entry.method} ${entry.path}`) {
+            fail('Endpoint stable key does not match its method and path.', 'repair-source-observations');
+        }
+        keys.add(entry.stableKey);
+        names.add(entry.definitionId);
+        fingerprints.add(entry.sourceFingerprint);
+    }
+}
+/**
+ * Reconcile a complete source-adapter snapshot. Does not assess semantics,
+ * grant permissions, write files, sync, or claim executable-source verification.
+ * Callers must persist state (including tombstones) and validate real sources.
+ */
+function reconcileExecutionInventory(options) {
+    const scope = zod_1.z.object({ appId: zod_1.z.uuid(), targetAppKey: zod_1.z.string().trim().min(1).max(200) }).safeParse(options);
+    const snapshot = SnapshotSchema.safeParse(options.observed);
+    if (!scope.success || !snapshot.success)
+        fail('Invalid generation scope or source observations.', 'repair-source-observations');
+    if (!snapshot.data.complete)
+        fail('Source discovery is incomplete; prior inventory was not replaced.', 'complete-source-discovery');
+    const parsed = options.previous === undefined ? undefined : exports.ExecutionGenerationStateSchema.safeParse(options.previous);
+    if (parsed && !parsed.success)
+        fail('Invalid previous generation state.', 'restore-generation-state');
+    const previous = parsed?.data;
+    if (previous && (previous.appId !== scope.data.appId || previous.inventory.targetAppKey !== scope.data.targetAppKey)) {
+        fail('Previous generation state belongs to a different app.', 'align-generation-scope');
+    }
+    assertUnique(snapshot.data.executions);
+    assertUnique(previous?.inventory.executions ?? []);
+    const occupied = new Set();
+    for (const entry of [...previous?.inventory.executions ?? [], ...previous?.tombstones ?? []]) {
+        if (occupied.has(entry.toolId))
+            fail('Duplicate identities in previous generation state.', 'restore-generation-state');
+        occupied.add(entry.toolId);
+    }
+    const previousByKey = new Map(previous?.inventory.executions.map((entry) => [entry.stableKey, entry]));
+    const currentKeys = new Set(snapshot.data.executions.map(({ stableKey }) => stableKey));
+    const tombstones = [...previous?.tombstones ?? []];
+    const changes = { added: [], changed: [], removed: [], unchanged: [] };
+    for (const old of previous?.inventory.executions ?? []) {
+        if (currentKeys.has(old.stableKey))
+            continue;
+        changes.removed.push(old.toolId);
+        tombstones.push({ toolId: old.toolId, stableKey: old.stableKey, definitionId: old.definitionId });
+    }
+    const executions = snapshot.data.executions.map((observation) => {
+        const old = previousByKey.get(observation.stableKey);
+        const toolId = old?.toolId ?? newIdentity(scope.data.appId, scope.data.targetAppKey, observation.stableKey, tombstones.filter(({ stableKey }) => stableKey === observation.stableKey).length);
+        if (!old && occupied.has(toolId))
+            fail('Generated execution identity conflicts with previous state.', 'restore-generation-state');
+        occupied.add(toolId);
+        const execution = { ...observation, toolId };
+        changes[!old ? 'added' : canonical(old) === canonical(execution) ? 'unchanged' : 'changed'].push(toolId);
+        return execution;
+    }).sort((a, b) => a.toolId < b.toolId ? -1 : a.toolId > b.toolId ? 1 : 0);
+    for (const list of Object.values(changes))
+        list.sort();
+    tombstones.sort((a, b) => a.toolId < b.toolId ? -1 : a.toolId > b.toolId ? 1 : 0);
+    return {
+        state: exports.ExecutionGenerationStateSchema.parse({ schemaVersion: 1, appId: scope.data.appId,
+            inventory: { schemaVersion: 2, targetAppKey: scope.data.targetAppKey, executions }, tombstones }),
+        changes,
+    };
+}

package/dist/cjs/codegen/next-source-generation.d.ts

@@ -0,0 +1,17 @@
+import { type ObservedExecution } from './inventory-generation.js';
+import { type ScannedRouteCandidate } from './route-scanner.js';
+export interface ResolvedEndpointContract {
+    definitionId: string;
+    inputSchemaDigest: string;
+    outputSchemaDigest: string;
+}
+/**
+ * Enumerate actual routes before resolving their local schema contracts. The
+ * setup agent supplies a thin source-schema adapter, not a static tool list.
+ * This stage does not grant exposure, infer authorization or upload sources.
+ */
+export declare function collectNextEndpointExecutions(options: {
+    rootDir: string;
+    apiDir?: string;
+    resolveContract: (candidate: ScannedRouteCandidate) => ResolvedEndpointContract | undefined | Promise<ResolvedEndpointContract | undefined>;
+}): Promise<ObservedExecution[]>;