glirastes 0.4.0 → 0.5.1

package/dist/codegen/tools/prose.js

@@ -0,0 +1,211 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { findSensitiveStringPath } from '../../contracts/content-boundary.js';
+import { ToolPresentationSchema } from '../../contracts/index.js';
+import { compareCodeUnits } from './canonical.js';
+import { TOOLS_PATHS } from './config.js';
+import { toolFinding } from './findings.js';
+import { isAgenticSemantics, SEMANTICS_LANGUAGES, SemanticsEntrySchema } from './semantics.js';
+const MAX_DESCRIPTION = 1_000;
+const MAX_HINT = 500;
+const MAX_LABEL = 200;
+const SemanticsFileSchema = z.object({
+    schemaVersion: z.literal(1),
+    tools: z.array(z.unknown()).max(5_000),
+}).passthrough();
+export const EMPTY_SEMANTICS = { byStableKey: new Map(), byName: new Map() };
+/**
+ * The names a schema issue path may show: entry fields, the languages and the
+ * members of an example call and of the agent block. Any other segment is a
+ * key of `origin` or `locked` taken from the file, which an agent controls.
+ */
+const SCHEMA_PATH_NAMES = new Set([
+    ...Object.keys(SemanticsEntrySchema.shape),
+    ...SEMANTICS_LANGUAGES,
+    'sentence', 'input', 'model', 'interfaceDigest',
+]);
+/** The first issue path with schema names and array indices only; file-controlled keys become `<key>`. */
+function schemaIssuePath(path) {
+    return path
+        .map((segment) => typeof segment === 'number' || (typeof segment === 'string' && SCHEMA_PATH_NAMES.has(segment))
+        ? String(segment)
+        : '<key>')
+        .join('.');
+}
+export function loadToolSemantics(root) {
+    let raw;
+    try {
+        raw = readFileSync(resolve(root, TOOLS_PATHS.semantics), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { semantics: EMPTY_SEMANTICS, findings: [] };
+        throw error;
+    }
+    const invalid = (message) => ({
+        semantics: EMPTY_SEMANTICS,
+        findings: [toolFinding('tool-semantics-invalid', 'warning', TOOLS_PATHS.semantics, message)],
+    });
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return invalid('tool-semantics.json is not valid JSON and is ignored.');
+    }
+    const file = SemanticsFileSchema.safeParse(json);
+    if (!file.success)
+        return invalid('tool-semantics.json does not match its schema and is ignored.');
+    const byStableKey = new Map();
+    const byName = new Map();
+    const findings = [];
+    file.data.tools.forEach((value, index) => {
+        const entry = SemanticsEntrySchema.safeParse(value);
+        if (!entry.success || (!entry.data.stableKey && !entry.data.name)) {
+            // An agent entry that does not even parse is a rejected agentic entry (spec 4.6).
+            const agentic = isAgenticSemantics(value);
+            const path = entry.success ? '' : schemaIssuePath(entry.error.issues[0]?.path ?? []);
+            findings.push(toolFinding(agentic ? 'resolution-rejected' : 'tool-semantics-invalid', 'warning', `${TOOLS_PATHS.semantics}#${index}`, `Entry ${index} of tool-semantics.json is invalid${path ? ` at ${path}` : ''} and is ignored.`));
+            return;
+        }
+        if (entry.data.stableKey)
+            byStableKey.set(entry.data.stableKey, entry.data);
+        if (entry.data.name)
+            byName.set(entry.data.name, entry.data);
+    });
+    return { semantics: { byStableKey, byName }, findings };
+}
+/** Cut to at most `max` UTF-16 units, the unit the schema bounds count, without splitting a surrogate pair. */
+function clamp(text, max) {
+    if (text.length <= max)
+        return text;
+    const end = /[\ud800-\udbff]/.test(text.charAt(max - 1)) ? max - 1 : max;
+    return text.slice(0, Math.max(0, end)).trimEnd();
+}
+function bounded(value, max) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.replace(/\s+/g, ' ').trim();
+    if (!text || findSensitiveStringPath(text))
+        return undefined;
+    return clamp(text, max);
+}
+function identifier(value) {
+    const text = value?.trim();
+    return text && text.length <= 200 ? text : undefined;
+}
+function capitalized(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/** The resource of an endpoint tool; everything after `ui.` for a UI tool. */
+function resourceWords(definitionId, operation) {
+    const resource = operation === 'ui'
+        ? definitionId.split('.').slice(1).join(' ')
+        : definitionId.split('.')[0] ?? definitionId;
+    return resource
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .toLowerCase()
+        .trim() || 'item';
+}
+const LABELS = {
+    en: {
+        list: (words) => `List ${words}`,
+        get: (words) => `Show ${words}`,
+        create: (words) => `Create ${words}`,
+        update: (words) => `Update ${words}`,
+        delete: (words) => `Delete ${words}`,
+        ui: (words) => `Run ${words}`,
+    },
+    de: {
+        list: (words) => `${capitalized(words)} auflisten`,
+        get: (words) => `${capitalized(words)} anzeigen`,
+        create: (words) => `${capitalized(words)} anlegen`,
+        update: (words) => `${capitalized(words)} ändern`,
+        delete: (words) => `${capitalized(words)} löschen`,
+        ui: (words) => `${capitalized(words)} ausführen`,
+    },
+};
+/** The verb stays intact: only the resource words give way when the label would exceed the presentation bound. */
+function labelOf(language, operation, words) {
+    const build = LABELS[language][operation];
+    return clamp(build(clamp(words, MAX_LABEL - build('').length)), MAX_LABEL);
+}
+function operationOf(group, path) {
+    if (group === 'read')
+        return path && /\/:[^/]+$/.test(path) ? 'get' : 'list';
+    return group;
+}
+function presentationOf(value) {
+    const parsed = ToolPresentationSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+/** The semantics entry of a tool: by stable key first, then by definition id. */
+export function lookupSemantics(semantics, stableKey, definitionId) {
+    return semantics.byStableKey.get(stableKey) ?? semantics.byName.get(definitionId);
+}
+/** Prose without a model; templates are the visible floor, never a blocker. */
+export function resolveToolProse(input) {
+    const entry = input.entry === undefined
+        ? lookupSemantics(input.semantics, input.stableKey, input.definitionId)
+        : input.entry ?? undefined;
+    const entryOrigin = entry?.origin?.description === 'agent'
+        ? 'agent'
+        : entry?.origin?.description === 'code' ? 'code' : 'human';
+    const language = input.locale.toLowerCase().startsWith('de') ? 'de' : 'en';
+    const operation = operationOf(input.operationGroup, input.path);
+    const label = labelOf(language, operation, resourceWords(input.definitionId, operation));
+    const candidates = [
+        [input.policyDescription, 'human'],
+        [input.jsDoc, 'code'],
+        [input.hints?.contractDescription, 'code'],
+        [input.hints?.schemaDescription, 'code'],
+        [entry?.description, entryOrigin],
+    ];
+    const findings = [];
+    let description;
+    let descriptionOrigin = 'template';
+    for (const [value, origin] of candidates) {
+        const text = bounded(value, MAX_DESCRIPTION);
+        if (text) {
+            description = text;
+            descriptionOrigin = origin;
+            break;
+        }
+    }
+    if (!description) {
+        description = clamp(input.method && input.path ? `${label} (${input.method} ${input.path}).` : `${label}.`, MAX_DESCRIPTION);
+        findings.push(toolFinding('description-templated', 'warning', input.stableKey, 'Only a template description is available; the model may pick this tool less reliably.'));
+    }
+    const module = identifier(input.hints?.module)
+        ?? identifier(entry?.module)
+        ?? (input.definitionId.split('.')[0] || 'tools');
+    const sharedWith = [...new Set((entry?.sharedWith ?? [])
+            .map(identifier)
+            .filter((value) => value !== undefined && value !== module))]
+        .sort(compareCodeUnits)
+        .slice(0, 50);
+    const hintSource = input.hints?.usageHints?.length
+        ? input.hints.usageHints
+        : entry?.usageHints?.length || entry?.approvalHint
+            ? [...entry.usageHints ?? [], ...entry.approvalHint ? [entry.approvalHint] : []]
+            : [description];
+    const usageHints = hintSource
+        .map((hint) => bounded(hint, MAX_HINT))
+        .filter((hint) => hint !== undefined)
+        .slice(0, 20);
+    const presentation = input.hints?.presentation
+        ?? presentationOf(entry?.presentation)
+        ?? { locale: input.locale, singular: label, plural: label, approval: label };
+    return {
+        description,
+        descriptionOrigin,
+        module,
+        sharedWith,
+        usageHints: usageHints.length > 0 ? usageHints : [description.slice(0, MAX_HINT)],
+        presentation,
+        findings,
+    };
+}
+//# sourceMappingURL=prose.js.map

package/dist/codegen/tools/prose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prose.js","sourceRoot":"","sources":["../../../src/codegen/tools/prose.ts"],"names":[],"mappings":"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"}

package/dist/codegen/tools/resolutions.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import type { ToolRiskClass } from '../../contracts/index.js';
+import type { HandlerConventions } from './handler-analysis.js';
+import type { ToolFinding } from './types.js';
+export declare const MAX_RESOLUTION_SCHEMA_BYTES: number;
+export declare const HandlerWrapperConventionSchema: z.ZodObject<{
+    module: z.ZodString;
+    export: z.ZodString;
+    inputArg: z.ZodOptional<z.ZodNumber>;
+    queryArg: z.ZodOptional<z.ZodNumber>;
+    outputArg: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const ToolConventionsSchema: z.ZodObject<{
+    handlerWrappers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        module: z.ZodString;
+        export: z.ZodString;
+        inputArg: z.ZodOptional<z.ZodNumber>;
+        queryArg: z.ZodOptional<z.ZodNumber>;
+        outputArg: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    bodyReaders: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        module: z.ZodString;
+        export: z.ZodString;
+    }, z.core.$strict>>>;
+    authHelpers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    filterValues: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+export declare const SchemaRefSchema: z.ZodObject<{
+    module: z.ZodString;
+    export: z.ZodString;
+    property: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * One `tool-resolutions.json` entry (spec 4.3, 4.6): a contract for one
+ * stableKey, bound to the handler interface it was written for. Strict: an
+ * unknown field rejects the entry. An agent entry names who wrote it
+ * (`model`); `glirastes tools verify` turns a reviewed entry into a human one
+ * and pins it with `locked`, the digest of the entry without that field.
+ */
+export declare const ResolutionEntrySchema: z.ZodObject<{
+    origin: z.ZodDefault<z.ZodEnum<{
+        agent: "agent";
+        human: "human";
+    }>>;
+    interfaceDigest: z.ZodString;
+    input: z.ZodOptional<z.ZodObject<{
+        schemaRef: z.ZodOptional<z.ZodObject<{
+            module: z.ZodString;
+            export: z.ZodString;
+            property: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        jsonSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>;
+    output: z.ZodOptional<z.ZodObject<{
+        schemaRef: z.ZodOptional<z.ZodObject<{
+            module: z.ZodString;
+            export: z.ZodString;
+            property: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        jsonSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>;
+    effect: z.ZodOptional<z.ZodEnum<{
+        write: "write";
+        financial: "financial";
+        external: "external";
+        read: "read";
+        destructive: "destructive";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+    locked: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ToolConventions = z.infer<typeof ToolConventionsSchema>;
+export type ResolutionEntry = z.infer<typeof ResolutionEntrySchema>;
+export interface ToolResolutions {
+    conventions: ToolConventions;
+    entries: ReadonlyMap<string, unknown>;
+}
+export declare const EMPTY_CONVENTIONS: ToolConventions;
+/** Compile-time proof that parsed conventions satisfy the handler analyzer. */
+export declare function toHandlerConventions(conventions: ToolConventions): HandlerConventions;
+export declare function loadToolResolutions(root: string): {
+    resolutions: ToolResolutions;
+    findings: ToolFinding[];
+};
+export interface ResolutionEvidence {
+    pathParams: ReadonlyArray<string>;
+    queryKeys: ReadonlyArray<string>;
+    bodyKeys: ReadonlyArray<string> | 'opaque';
+}
+/**
+ * Keys an input schema may name and must keep: every name needs code
+ * evidence (path, query or a closed body), and no evidenced query or body
+ * key may be dropped. An opaque body admits any body key, because the code
+ * cannot show which ones the handler passes on.
+ */
+export declare function inputEvidenceProblem(schema: Record<string, unknown>, evidence: ResolutionEvidence): string | undefined;
+/** The digest `glirastes tools verify` pins: the entry as parsed, without `locked`. */
+export declare function resolutionLockDigest(entry: ResolutionEntry): string;
+/**
+ * The unified check of one entry (spec 4.6) on what the entry says by itself:
+ * strict parse, content limits, an intact lock, effects that only raise the
+ * risk and strict JSON Schema of at most 32 KB. An invalid entry is ignored
+ * with `resolution-rejected`; the tool keeps its fallback. The input keys are
+ * checked against the code evidence later (`assessResolution` in
+ * contract-tiers.ts), once `interfaceDigest` shows the entry is current: an
+ * entry written for an earlier interface is stale, not rejected (spec 4.4).
+ */
+export declare function validateResolutionEntry(input: {
+    stableKey: string;
+    raw: unknown;
+    /** The risk class the code alone derives; an effect below it is refused. */
+    codeRiskClass?: ToolRiskClass;
+}): {
+    entry?: ResolutionEntry;
+    findings: ToolFinding[];
+};
+export declare function resolutionOrigin(resolutions: ToolResolutions, stableKey: string): 'human' | 'agent' | undefined;

package/dist/codegen/tools/resolutions.js

@@ -0,0 +1,195 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { declaredEffectRiskClass, riskTier } from '../../contracts/tool-policy.js';
+import { AGENT_MODEL_PATTERN, agenticContentProblem, lockDigest, MAX_AGENTIC_SCHEMA_BYTES, schemaPropertyNames, strictSchemaProblem, withoutMetaSchema, } from './agentic.js';
+import { compareCodeUnits } from './canonical.js';
+import { TOOLS_PATHS } from './config.js';
+import { toolFinding } from './findings.js';
+export const MAX_RESOLUTION_SCHEMA_BYTES = MAX_AGENTIC_SCHEMA_BYTES;
+const appModule = z.string().trim().min(1).max(512)
+    .refine((value) => !value.startsWith('/') && !value.split(/[\\/]/).includes('..'), 'Path must stay inside the app');
+const exportName = z.string().trim().min(1).max(200);
+const argumentIndex = z.number().int().min(0).max(15);
+export const HandlerWrapperConventionSchema = z.object({
+    module: appModule,
+    export: exportName,
+    inputArg: argumentIndex.optional(),
+    queryArg: argumentIndex.optional(),
+    outputArg: argumentIndex.optional(),
+}).strict();
+export const ToolConventionsSchema = z.object({
+    handlerWrappers: z.array(HandlerWrapperConventionSchema).max(50).default([]),
+    bodyReaders: z.array(z.object({ module: appModule, export: exportName }).strict()).max(50).default([]),
+    authHelpers: z.array(z.string().regex(/^[A-Za-z_$][\w$]*$/)).max(100).default([]),
+    /** Accepted now; used by the filter sources in P04. */
+    filterValues: z.record(z.string(), z.array(z.string().max(200)).max(200)).default({}),
+}).strict();
+export const SchemaRefSchema = z.object({
+    module: appModule,
+    export: exportName,
+    property: z.array(exportName).max(8).default([]),
+}).strict();
+const SchemaSpecSchema = z.object({
+    schemaRef: SchemaRefSchema.optional(),
+    jsonSchema: z.record(z.string(), z.unknown()).optional(),
+}).strict().refine((spec) => Boolean(spec.schemaRef) !== Boolean(spec.jsonSchema), 'Provide exactly one of schemaRef or jsonSchema');
+const digest = z.string().regex(/^sha256:[A-Za-z0-9_-]{43}$/);
+/**
+ * One `tool-resolutions.json` entry (spec 4.3, 4.6): a contract for one
+ * stableKey, bound to the handler interface it was written for. Strict: an
+ * unknown field rejects the entry. An agent entry names who wrote it
+ * (`model`); `glirastes tools verify` turns a reviewed entry into a human one
+ * and pins it with `locked`, the digest of the entry without that field.
+ */
+export const ResolutionEntrySchema = z.object({
+    origin: z.enum(['human', 'agent']).default('human'),
+    interfaceDigest: digest,
+    input: SchemaSpecSchema.optional(),
+    output: SchemaSpecSchema.optional(),
+    effect: z.enum(['read', 'write', 'destructive', 'external', 'financial']).optional(),
+    model: z.string().regex(AGENT_MODEL_PATTERN).optional(),
+    locked: digest.optional(),
+}).strict().superRefine((entry, context) => {
+    if (entry.origin === 'agent' && entry.model === undefined) {
+        context.addIssue({ code: 'custom', path: ['model'], message: 'An agent entry names the model or coding agent that wrote it' });
+    }
+    if (entry.origin === 'agent' && entry.locked !== undefined) {
+        context.addIssue({ code: 'custom', path: ['locked'], message: 'A locked entry was reviewed and is no agent entry' });
+    }
+});
+const ResolutionsFileSchema = z.object({
+    schemaVersion: z.literal(1),
+    conventions: z.unknown().optional(),
+    tools: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+export const EMPTY_CONVENTIONS = {
+    handlerWrappers: [],
+    bodyReaders: [],
+    authHelpers: [],
+    filterValues: {},
+};
+/** Compile-time proof that parsed conventions satisfy the handler analyzer. */
+export function toHandlerConventions(conventions) {
+    return conventions;
+}
+function rejected(subjectRef, message) {
+    return toolFinding('resolution-rejected', 'warning', subjectRef, message);
+}
+export function loadToolResolutions(root) {
+    const empty = { conventions: EMPTY_CONVENTIONS, entries: new Map() };
+    let raw;
+    try {
+        raw = readFileSync(resolve(root, TOOLS_PATHS.resolutions), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { resolutions: empty, findings: [] };
+        throw error;
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return { resolutions: empty, findings: [rejected(TOOLS_PATHS.resolutions, 'tool-resolutions.json is not valid JSON and is ignored.')] };
+    }
+    const file = ResolutionsFileSchema.safeParse(json);
+    if (!file.success) {
+        return { resolutions: empty, findings: [rejected(TOOLS_PATHS.resolutions, 'tool-resolutions.json does not match its schema and is ignored.')] };
+    }
+    const findings = [];
+    const conventions = ToolConventionsSchema.safeParse(file.data.conventions ?? {});
+    if (!conventions.success) {
+        findings.push(rejected('conventions', 'The conventions in tool-resolutions.json are invalid and are ignored.'));
+    }
+    const entries = new Map(Object.entries(file.data.tools ?? {})
+        .sort(([left], [right]) => compareCodeUnits(left, right)));
+    return {
+        resolutions: { conventions: conventions.success ? conventions.data : EMPTY_CONVENTIONS, entries },
+        findings,
+    };
+}
+/**
+ * Keys an input schema may name and must keep: every name needs code
+ * evidence (path, query or a closed body), and no evidenced query or body
+ * key may be dropped. An opaque body admits any body key, because the code
+ * cannot show which ones the handler passes on.
+ */
+export function inputEvidenceProblem(schema, evidence) {
+    const keys = schemaPropertyNames(schema);
+    if (evidence.bodyKeys !== 'opaque') {
+        const allowed = new Set([...evidence.pathParams, ...evidence.queryKeys, ...evidence.bodyKeys]);
+        const unbacked = keys.filter((key) => !allowed.has(key));
+        if (unbacked.length > 0)
+            return `input keys without code evidence: ${unbacked.join(', ')}`;
+    }
+    const present = new Set(keys);
+    const lost = [...evidence.queryKeys, ...(evidence.bodyKeys === 'opaque' ? [] : evidence.bodyKeys)]
+        .filter((key) => !present.has(key))
+        .sort(compareCodeUnits);
+    if (lost.length > 0)
+        return `the input schema drops parameters the handler reads: ${[...new Set(lost)].join(', ')}`;
+    return undefined;
+}
+/** The digest `glirastes tools verify` pins: the entry as parsed, without `locked`. */
+export function resolutionLockDigest(entry) {
+    const { locked: _locked, ...content } = entry;
+    return lockDigest(content);
+}
+function normalizeSpec(spec) {
+    return spec?.jsonSchema ? { ...spec, jsonSchema: withoutMetaSchema(spec.jsonSchema) } : spec;
+}
+function firstIssuePath(error) {
+    const path = error.issues[0]?.path.map(String).join('.') ?? '';
+    return path ? ` at ${path}` : '';
+}
+/**
+ * The unified check of one entry (spec 4.6) on what the entry says by itself:
+ * strict parse, content limits, an intact lock, effects that only raise the
+ * risk and strict JSON Schema of at most 32 KB. An invalid entry is ignored
+ * with `resolution-rejected`; the tool keeps its fallback. The input keys are
+ * checked against the code evidence later (`assessResolution` in
+ * contract-tiers.ts), once `interfaceDigest` shows the entry is current: an
+ * entry written for an earlier interface is stale, not rejected (spec 4.4).
+ */
+export function validateResolutionEntry(input) {
+    const reject = (reason) => ({
+        findings: [rejected(input.stableKey, `The tool-resolutions.json entry was rejected: ${reason}.`)],
+    });
+    const parsed = ResolutionEntrySchema.safeParse(input.raw);
+    if (!parsed.success)
+        return reject(`it does not match the entry schema${firstIssuePath(parsed.error)}`);
+    const entry = parsed.data;
+    const content = agenticContentProblem(entry);
+    if (content)
+        return reject(`it contains ${content}`);
+    if (entry.locked !== undefined && resolutionLockDigest(entry) !== entry.locked) {
+        return reject('it was changed after review; restore it from git, or review it and run glirastes tools verify');
+    }
+    if (entry.effect && input.codeRiskClass
+        && riskTier(declaredEffectRiskClass(entry.effect)) < riskTier(input.codeRiskClass)) {
+        return reject(`its effect ${entry.effect} would lower the risk below ${input.codeRiskClass}; effects may only raise it`);
+    }
+    const specs = [['input', entry.input], ['output', entry.output]];
+    for (const [role, spec] of specs) {
+        if (!spec?.jsonSchema)
+            continue;
+        const problem = strictSchemaProblem(withoutMetaSchema(spec.jsonSchema), role);
+        if (problem)
+            return reject(problem);
+    }
+    return {
+        entry: {
+            ...entry,
+            ...(entry.input ? { input: normalizeSpec(entry.input) } : {}),
+            ...(entry.output ? { output: normalizeSpec(entry.output) } : {}),
+        },
+        findings: [],
+    };
+}
+export function resolutionOrigin(resolutions, stableKey) {
+    const parsed = ResolutionEntrySchema.safeParse(resolutions.entries.get(stableKey));
+    return parsed.success ? parsed.data.origin : undefined;
+}
+//# sourceMappingURL=resolutions.js.map

package/dist/codegen/tools/resolutions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolutions.js","sourceRoot":"","sources":["../../../src/codegen/tools/resolutions.ts"],"names":[],"mappings":"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"}

package/dist/codegen/tools/routing-eval.d.ts

@@ -0,0 +1,50 @@
+import type { AppSetupArtifact } from '../../contracts/index.js';
+import type { ToolContractsEntry } from './types.js';
+/** A sentence passes when its tool is among this many `find_tools` hits. */
+export declare const DEFAULT_ROUTING_TOP = 3;
+export interface RoutingSentenceFailure {
+    sentence: string;
+    /** 1-based rank of the expected tool, or null when the search does not return it. */
+    rank: number | null;
+    /** The tools that `find_tools` ranks above it (by name), at most `top`. */
+    competitors: string[];
+    /** The first hit belongs to another module, so module routing would go astray. */
+    moduleMismatch: boolean;
+}
+export interface RoutingToolResult {
+    tool: string;
+    stableKey: string;
+    module: string;
+    sentences: number;
+    failures: RoutingSentenceFailure[];
+}
+export interface RoutingEvaluation {
+    schemaVersion: 1;
+    top: number;
+    summary: {
+        /** Enabled tools the chat can find. */
+        tools: number;
+        /** Tools with example sentences. */
+        evaluated: number;
+        sentences: number;
+        passed: number;
+        failed: number;
+        /** Enabled tools without example sentences, by name. */
+        withoutExamples: string[];
+    };
+    /** Evaluated tools, by name; `failures` lists each sentence that does not find its tool. */
+    tools: RoutingToolResult[];
+}
+/**
+ * Deterministic routing check (spec 4.7 "Qualitätsschleife"): every example
+ * sentence of a tool must find that tool among the first `find_tools` hits,
+ * built exactly like the runtime index (name, description, module, shared
+ * modules, usage hints, synonyms), and the first hit must lie in the tool's
+ * module. No model, no network, no clock: the same outputs give the same
+ * bytes, so CI can run it as the FR-3 regression corpus.
+ */
+export declare function evaluateRouting(input: {
+    artifact: AppSetupArtifact;
+    contracts: ReadonlyArray<Pick<ToolContractsEntry, 'toolId' | 'stableKey' | 'search'>>;
+    top?: number;
+}): RoutingEvaluation;