@telorun/analyzer 0.48.0 → 0.49.0

package/dist/validate-invocation-contract.js

@@ -0,0 +1,394 @@
+import { effectiveContractField, mappingFieldFor, needsContractMapping, } from "./extends-resolution.js";
+import { buildReferenceFieldMap, isRefEntry } from "./reference-field-map.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Phase 3 — static checks on declared invocation contracts.
+ *
+ * The runtime binds a contract to every instance and enforces it at dispatch;
+ * these are the failures worth catching before anything runs, and the ones the
+ * runtime cannot see at all (a declaration that is inert, an input nobody can
+ * supply).
+ *
+ * Diagnostics:
+ *  - CONTRACT_MISSING_MAPPING: a definition that inherits its controller declares
+ *    its own `inputType` / `outputType` without the `inputs:` / `result:` mapping
+ *    that bridges it back to the inherited controller.
+ *  - CONTRACT_INPUTS_SCHEMA_FORM: a leftover `inputs:` property map on a kind
+ *    whose input contract is now `inputType:`.
+ *  - CONTRACT_TYPE_NOT_FOUND: a contract names a type that is not declared in
+ *    scope, so every call through it would fail at dispatch.
+ *
+ * Deliberately NOT diagnosed: an input that is neither `required:` nor
+ * defaulted. It is indistinguishable from a genuinely optional one — `Ai.Text`
+ * takes `prompt` OR `messages`, and `system` is optional on purpose — so the
+ * check fired ~40 times across the standard library on correct manifests with no
+ * way for an author to record the intent. A warning that cannot be silenced on
+ * correct code teaches people to ignore warnings.
+ */
+export function validateInvocationContract(manifests, registry, aliases, aliasesByModule = new Map()) {
+    const diagnostics = [];
+    const resolveDef = (kind, from) => {
+        const module = from?.metadata?.module;
+        const scope = (module ? aliasesByModule.get(module) : undefined) ?? aliases;
+        return registry.resolve(kind) ?? registry.resolve(scope.resolveKind(kind) ?? kind);
+    };
+    // A published dependency's declarations are not the consumer's to fix.
+    const importedModules = new Set();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Import")
+            continue;
+        const resolved = m.metadata?.resolvedModuleName;
+        if (resolved)
+            importedModules.add(resolved);
+    }
+    const isOwn = (m) => {
+        const ownModule = m.metadata?.module;
+        return !ownModule || !importedModules.has(ownModule);
+    };
+    for (const m of manifests) {
+        if (!isOwn(m))
+            continue;
+        const name = m.metadata?.name;
+        if (!name)
+            continue;
+        const filePath = m.metadata?.source;
+        const resource = { kind: m.kind, name };
+        const md = m;
+        if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") {
+            checkMappingRequired(m, resource, filePath, resolveDef, diagnostics);
+            checkContractResolves(m, md, manifests, resource, filePath, diagnostics);
+            continue;
+        }
+        // A RESOURCE (an instance of some kind) — a leftover `inputs:` map is only
+        // meaningful against a kind whose schema no longer declares one.
+        const definition = resolveDef(m.kind, m);
+        if (!definition)
+            continue;
+        checkContractResolves(m, md, manifests, resource, filePath, diagnostics);
+        checkLeftoverInputsSchema(m, definition, md, resource, filePath, diagnostics);
+        checkRefSlotWiring(m, definition, manifests, resolveDef, resource, filePath, diagnostics);
+    }
+    return diagnostics;
+}
+/**
+ * The wiring rule: whether a ref slot may hold a resource whose input contract
+ * differs from the slot's declared kind.
+ *
+ * `extends` decides which resources a slot ACCEPTS; it never carried the
+ * dispatch contract. What matters per slot is whether the caller can supply the
+ * target's arguments at all:
+ *
+ *  - the slot's declared kind declares no `inputType` and is not a run site →
+ *    nothing to violate, accept;
+ *  - the wiring site takes a paired author `inputs:` → the author supplies the
+ *    arguments and can see both sides, so the call site check covers it;
+ *  - the consumer's controller builds the arguments and knows only the slot's
+ *    kind → the wired resource must not require anything that kind does not
+ *    declare, because nothing could ever supply it.
+ *
+ * The run-site case is the same rule with an empty argument set: a `run()`
+ * dispatch passes nothing at all, so a target requiring any input can never be
+ * satisfied there. Both are keyed on declared capability and declared contracts,
+ * never on a kind's name.
+ */
+function checkRefSlotWiring(m, definition, manifests, resolveDef, resource, filePath, diagnostics) {
+    const schema = definition.schema;
+    if (!schema)
+        return;
+    for (const [path, entry] of buildReferenceFieldMap(schema)) {
+        if (!isRefEntry(entry))
+            continue;
+        // A slot that takes a paired `inputs:` is the author's to fill; its values
+        // are checked at the call site instead, against the target's own contract.
+        if (slotTakesPairedInputs(schema, path))
+            continue;
+        const slotDeclares = slotDeclaredInputs(entry.refs, resolveDef, manifests);
+        const runSite = isRunOnlySlot(entry.refs, resolveDef);
+        if (!runSite && slotDeclares === undefined)
+            continue;
+        const ownModule = m.metadata?.module;
+        for (const name of refValuesAt(m, path)) {
+            // Scoped to the declaring module: a resource of the same name in another
+            // module is a different resource, and checking against its contract would
+            // report on something the author never wired.
+            const target = findInModule(manifests, name, ownModule);
+            if (!target)
+                continue;
+            const targetDef = resolveDef(target.kind, target);
+            const targetRequired = requiredInputsOf(contractSchemaFor(target, targetDef, resolveDef, manifests));
+            if (!targetRequired || targetRequired.length === 0)
+                continue;
+            const unsatisfiable = runSite
+                ? targetRequired
+                : targetRequired.filter((key) => !(slotDeclares ?? []).includes(key));
+            if (unsatisfiable.length === 0)
+                continue;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: runSite ? "CONTRACT_INPUTS_AT_RUN_SITE" : "CONTRACT_SLOT_INPUTS_UNSATISFIABLE",
+                source: SOURCE,
+                message: runSite
+                    ? `${m.kind}/${resource.name}: '${name}' is wired at '${path}', which starts it with \`run()\` — ` +
+                        `a dispatch that passes no arguments — but its contract requires ${list(unsatisfiable)}. ` +
+                        `Nothing can supply them there. Invoke it from a step instead, or drop the requirement.`
+                    : `${m.kind}/${resource.name}: '${name}' is wired at '${path}', where the consumer builds the ` +
+                        `arguments from the slot's declared kind alone, but its contract requires ${list(unsatisfiable)} ` +
+                        `which that kind does not declare. Nothing could supply them.`,
+                data: { resource, filePath, path },
+            });
+        }
+    }
+}
+const list = (keys) => keys.map((k) => `'${k}'`).join(", ");
+/** The inputs a consumer can supply knowing only the slot — the UNION of every
+ *  accepted kind's declared inputs.
+ *
+ *  Union rather than the first match: a slot accepting several kinds may see any
+ *  of them, and a name any accepted kind declares is one a consumer could
+ *  plausibly supply. Taking the first kind's contract would make the check
+ *  depend on the order `anyOf` branches happen to be written in. Undefined when
+ *  no accepted kind declares a contract at all — the "nothing to violate" case. */
+function slotDeclaredInputs(refs, resolveDef, manifests) {
+    let seen;
+    for (const ref of refs) {
+        const def = resolveDef(ref);
+        if (!def)
+            continue;
+        const schema = contractSchemaFor(undefined, def, resolveDef, manifests);
+        if (!schema)
+            continue;
+        seen ??= new Set();
+        for (const key of Object.keys((schema.properties ?? {}))) {
+            seen.add(key);
+        }
+    }
+    return seen ? [...seen] : undefined;
+}
+/** True when every kind a slot accepts is started rather than invoked — the
+ *  capabilities whose dispatch verb is `run()`, which passes no arguments.
+ *  Keyed on the declared capability, so a user-defined abstract resolves the
+ *  same way a built-in does. */
+function isRunOnlySlot(refs, resolveDef) {
+    if (refs.length === 0)
+        return false;
+    return refs.every((ref) => {
+        const def = resolveDef(ref);
+        const capability = def?.capability ?? ref;
+        return capability === "Telo.Runnable" || capability === "Telo.Service";
+    });
+}
+/** The resolved contract schema for a target: its own declaration first, then
+ *  the nearest along `extends`. Inline schemas only — a named reference resolves
+ *  through machinery this pass does not carry, and half-resolving would be worse
+ *  than not reporting. */
+function contractSchemaFor(manifest, definition, resolveDef, manifests, direction = "inputType") {
+    const declaringModule = (manifest ?? definition)?.metadata
+        ?.module;
+    const own = manifest ? manifest[direction] : undefined;
+    const declared = own !== undefined && own !== null
+        ? own
+        : effectiveContractField(definition, resolveDef, direction);
+    const inline = inlineSchemaOf(declared);
+    if (inline)
+        return inline;
+    // A `!ref` / bare name: resolve it to the named type resource in scope.
+    const named = typeof declared === "string"
+        ? declared
+        : declared && typeof declared === "object" && typeof declared.name === "string"
+            ? declared.name
+            : undefined;
+    if (!named)
+        return undefined;
+    const typeManifest = findInModule(manifests, named, declaringModule);
+    return typeManifest ? inlineSchemaOf(typeManifest) : undefined;
+}
+/** The input names a contract makes mandatory. Undefined means "no contract
+ *  declared" — distinct from an empty list, which means "declared, requires
+ *  nothing". */
+function requiredInputsOf(schema) {
+    if (!schema)
+        return undefined;
+    return Array.isArray(schema.required) ? schema.required : [];
+}
+/** Whether the object containing this ref slot also declares an inputs field —
+ *  the `invoke`/`inputs` pairing, recognised through the topology role rather
+ *  than a field name, so a composer spelling it differently still counts. */
+function slotTakesPairedInputs(schema, path) {
+    const parentPath = path.slice(0, Math.max(0, path.lastIndexOf(".")));
+    const parent = parentPath ? navigateSchema(schema, parentPath) : schema;
+    const properties = (parent?.properties ?? {});
+    return Object.values(properties).some((p) => p?.["x-telo-topology-role"] === "inputs");
+}
+/** Follow a field-map path (`a.b[].c`) through a schema's properties/items. */
+function navigateSchema(schema, path) {
+    let node = schema;
+    for (const raw of path.split(".")) {
+        if (!node)
+            return undefined;
+        const key = raw.replace(/\[\]|\{\}/g, "");
+        let next = (node.properties ?? {})[key];
+        if (!next)
+            return undefined;
+        if (raw.includes("[]"))
+            next = (next.items ?? {});
+        node = next;
+    }
+    return node;
+}
+/** The `{kind, name}` references actually written at a field-map path. */
+function refValuesAt(manifest, path) {
+    const out = [];
+    const walk = (node, segments) => {
+        if (node == null)
+            return;
+        if (segments.length === 0) {
+            const items = Array.isArray(node) ? node : [node];
+            for (const item of items) {
+                // A reference is `{kind, name}` — BOTH fields. Requiring only `name`
+                // would read an inline invoke step (`{ name, invoke, inputs }`) as a
+                // reference to a resource called after the step, which it is not: that
+                // `name` labels the step, and the step is an invoke site anyway.
+                if (item &&
+                    typeof item === "object" &&
+                    typeof item.name === "string" &&
+                    typeof item.kind === "string") {
+                    out.push(item.name);
+                }
+            }
+            return;
+        }
+        const [head, ...rest] = segments;
+        const key = head.replace(/\[\]|\{\}/g, "");
+        const value = node[key];
+        if (head.includes("[]") && Array.isArray(value)) {
+            for (const item of value)
+                walk(item, rest);
+        }
+        else if (head.includes("{}") && value && typeof value === "object") {
+            for (const item of Object.values(value))
+                walk(item, rest);
+        }
+        else {
+            walk(value, rest);
+        }
+    };
+    walk(manifest, path.split("."));
+    return out;
+}
+/**
+ * A named contract must name a type that exists.
+ *
+ * The runtime raises `ERR_CONTRACT_UNRESOLVABLE` on the first dispatch through
+ * an unresolvable contract, which is exactly the failure a checker should have
+ * caught: nothing about it depends on runtime values. Instance-level slots were
+ * already covered, because a module kind declares its `inputType` property with
+ * `x-telo-ref: Telo.Type`; the KIND-level fields are on `Telo.Definition`, which
+ * is deliberately excluded from reference validation, so they had no check at
+ * all and the same typo behaved differently depending on where it was written.
+ */
+function checkContractResolves(m, md, manifests, resource, filePath, diagnostics) {
+    const declaringModule = m.metadata?.module;
+    for (const direction of ["inputType", "outputType"]) {
+        const named = namedTypeReference(md[direction]);
+        if (!named)
+            continue;
+        if (findInModule(manifests, named, declaringModule))
+            continue;
+        diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "CONTRACT_TYPE_NOT_FOUND",
+            source: SOURCE,
+            message: `${m.kind}/${resource.name}: \`${direction}\` names the type '${named}', which is not declared ` +
+                `in scope. The contract cannot be enforced, so every call through it would fail at dispatch. ` +
+                `Declare a \`Telo.JsonSchema\` with that name, or inline the shape.`,
+            data: { resource, filePath, path: direction },
+        });
+    }
+}
+/** The name a contract field references, when it is a reference at all. An
+ *  inline shape or a raw schema names nothing and resolves on its own. */
+function namedTypeReference(value) {
+    if (typeof value === "string")
+        return value;
+    if (!value || typeof value !== "object")
+        return undefined;
+    const ref = value;
+    if (ref.schema && typeof ref.schema === "object")
+        return undefined;
+    return typeof ref.name === "string" ? ref.name : undefined;
+}
+/** A child that inherits its controller and REPLACES a contract must bridge it:
+ *  contracts resolve to the nearest declaration and never merge, so the
+ *  inherited controller only understands its own shape. Without the mapping the
+ *  declaration is inert — precisely the silent no-op this rule exists to end. */
+function checkMappingRequired(m, resource, filePath, resolveDef, diagnostics) {
+    const def = m;
+    const body = m;
+    for (const direction of ["inputType", "outputType"]) {
+        if (!needsContractMapping(def, resolveDef, direction))
+            continue;
+        const mappingField = mappingFieldFor(direction);
+        if (body[mappingField] != null)
+            continue;
+        diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "CONTRACT_MISSING_MAPPING",
+            source: SOURCE,
+            message: `${m.kind}/${resource.name}: declares its own \`${direction}\` but inherits its controller, ` +
+                `and no \`${mappingField}:\` mapping bridges the two. The inherited controller only understands ` +
+                `the kind it came from, so without a mapping the declaration would never be applied. Add a ` +
+                `\`${mappingField}:\` mapping, or drop \`${direction}\` to inherit the contract unchanged.`,
+            data: { resource, filePath, path: direction },
+        });
+    }
+}
+/** `inputs:` on a resource once meant "a JSON Schema property map" on the run
+ *  kinds. It is values everywhere else, and now means values everywhere — so a
+ *  leftover map against a kind that declares no `inputs` property is a migration
+ *  the author has not finished, not an unknown field. */
+function checkLeftoverInputsSchema(m, definition, md, resource, filePath, diagnostics) {
+    const value = md.inputs;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    const properties = (definition.schema?.properties ?? {});
+    if ("inputs" in properties)
+        return;
+    if (!("inputType" in properties))
+        return;
+    diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "CONTRACT_INPUTS_SCHEMA_FORM",
+        source: SOURCE,
+        message: `${m.kind}/${resource.name}: \`inputs:\` no longer declares an input contract — it always means ` +
+            `values now. Move the property map to \`inputType:\` (a \`Telo.JsonSchema\` shape, a named type ` +
+            `reference, or an inline schema).`,
+        data: { resource, filePath, path: "inputs" },
+    });
+}
+/** The schema behind an INLINE type declaration, which is all this pass can read
+ *  without a manifest lookup. A named reference resolves elsewhere; skipping it
+ *  here keeps the check total rather than half-informed. */
+function inlineSchemaOf(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const obj = value;
+    if (obj.schema && typeof obj.schema === "object")
+        return obj.schema;
+    if (obj.properties && typeof obj.properties === "object")
+        return obj;
+    return undefined;
+}
+/** Find a manifest by name within a module, falling back to a unique global
+ *  match. Names are unique per module, not per flattened graph, so an unscoped
+ *  `find` can silently return another module's resource; an ambiguous global
+ *  match resolves to nothing rather than to a guess. */
+function findInModule(manifests, name, module) {
+    const byName = manifests.filter((t) => t.metadata?.name === name);
+    if (byName.length === 0)
+        return undefined;
+    const scoped = byName.filter((t) => t.metadata?.module === module);
+    if (scoped.length === 1)
+        return scoped[0];
+    return byName.length === 1 ? byName[0] : undefined;
+}

package/dist/validate-step-inputs.d.ts

@@ -0,0 +1,24 @@
+import type { AliasResolver, ModuleScopes } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+export interface StepInputIssue {
+    path: string;
+    targetLabel: string;
+    message: string;
+}
+/**
+ * Validate every step's `inputs:` against the invoked target's declared input
+ * contract — the static half of what the kernel enforces at dispatch.
+ *
+ * Worth doing statically because a call site is where the mistake is made and
+ * where the author can see both sides: a misspelled key or a wrong-shaped value
+ * would otherwise surface at runtime inside the callee, several steps from its
+ * cause, naming a resource the author may not have written.
+ *
+ * CEL leaves are replaced by schema-shaped placeholders first (`substituteCelFields`),
+ * so an expression is never a false positive — only structural disagreement is
+ * reported. Nothing is hardcoded about `Run.Sequence`: the invoke field comes
+ * from `x-telo-step-context`, and the paired inputs field from whichever sibling
+ * property carries `x-telo-topology-role: inputs`.
+ */
+export declare function collectStepInputIssues(manifest: Record<string, any>, defSchema: Record<string, any>, allManifests: Record<string, any>[], defs: DefinitionRegistry, aliases: AliasResolver, scopes: ModuleScopes): StepInputIssue[];
+//# sourceMappingURL=validate-step-inputs.d.ts.map

package/dist/validate-step-inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-step-inputs.d.ts","sourceRoot":"","sources":["../src/validate-step-inputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAanE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY,GACnB,cAAc,EAAE,CAyElB"}

package/dist/validate-step-inputs.js

@@ -0,0 +1,87 @@
+import { resolveContract } from "./invocation-contract.js";
+import { substituteCelFields, validateAgainstSchema } from "./schema-compat.js";
+import { analyzerContractScope, containerOf, gatherPropertySchemas, missingRequired, resolveLocalRef, walkStepArray, } from "./analyzer.js";
+/**
+ * Validate every step's `inputs:` against the invoked target's declared input
+ * contract — the static half of what the kernel enforces at dispatch.
+ *
+ * Worth doing statically because a call site is where the mistake is made and
+ * where the author can see both sides: a misspelled key or a wrong-shaped value
+ * would otherwise surface at runtime inside the callee, several steps from its
+ * cause, naming a resource the author may not have written.
+ *
+ * CEL leaves are replaced by schema-shaped placeholders first (`substituteCelFields`),
+ * so an expression is never a false positive — only structural disagreement is
+ * reported. Nothing is hardcoded about `Run.Sequence`: the invoke field comes
+ * from `x-telo-step-context`, and the paired inputs field from whichever sibling
+ * property carries `x-telo-topology-role: inputs`.
+ */
+export function collectStepInputIssues(manifest, defSchema, allManifests, defs, aliases, scopes) {
+    const out = [];
+    const props = defSchema.properties;
+    if (!props)
+        return out;
+    const contractScope = analyzerContractScope(defs, aliases, scopes, allManifests);
+    const readingModule = manifest.metadata?.module;
+    for (const [fieldName, fieldSchema] of Object.entries(props)) {
+        const stepCtx = fieldSchema["x-telo-step-context"];
+        if (!stepCtx?.invoke)
+            continue;
+        const steps = manifest[fieldName];
+        if (!Array.isArray(steps))
+            continue;
+        const stepItemSchema = resolveLocalRef(fieldSchema.items, defSchema);
+        if (!stepItemSchema)
+            continue;
+        // The inputs field is whichever sibling declares the role — never the literal
+        // name, so a composer that spells it differently still gets checked.
+        let inputsField;
+        for (const [key, sub] of gatherPropertySchemas(stepItemSchema)) {
+            if (sub?.["x-telo-topology-role"] === "inputs")
+                inputsField = key;
+        }
+        if (!inputsField)
+            continue;
+        walkStepArray(steps, stepItemSchema, defSchema, fieldName, (step, stepPath) => {
+            const invoke = step[stepCtx.invoke];
+            const values = step[inputsField];
+            if (!invoke || typeof invoke !== "object")
+                return;
+            if (!values || typeof values !== "object" || Array.isArray(values))
+                return;
+            const invokedKind = invoke.kind;
+            const invokedName = invoke.name;
+            const invokedManifest = invokedName
+                ? allManifests.find((m) => m.metadata?.name === invokedName && (!invokedKind || m.kind === invokedKind))
+                : invoke;
+            const invokedDef = invokedKind
+                ? contractScope.resolveIn(invokedKind, readingModule)
+                : undefined;
+            const contract = resolveContract("inputType", invokedManifest, invokedDef, contractScope);
+            if (!contract)
+                return;
+            // Findings AT a substituted path are about a placeholder, not about
+            // anything the author wrote — a `pattern`-constrained string or a `oneOf`
+            // of unrelated shapes cannot be satisfied by any stand-in. Structural
+            // findings (missing required, unknown property) are located at the
+            // container and survive the filter.
+            const celPaths = new Set();
+            const substituted = substituteCelFields(values, contract.schema, undefined, (p) => celPaths.add(p));
+            for (const issue of validateAgainstSchema(substituted, contract.schema)) {
+                if (celPaths.has(issue.path))
+                    continue;
+                // A missing-required issue names the property that ISN'T there, so
+                // anchoring on it finds no node and the diagnostic degrades to 1:1 —
+                // losing the location of the most common contract mistake. Anchor on the
+                // container that should have held it, which does exist.
+                const anchor = missingRequired(issue) ? containerOf(issue.path) : issue.path;
+                out.push({
+                    path: anchor ? `${stepPath}.${inputsField}.${anchor}` : `${stepPath}.${inputsField}`,
+                    targetLabel: invokedName ?? invokedKind ?? "the invoked resource",
+                    message: issue.message,
+                });
+            }
+        });
+    }
+    return out;
+}

package/dist/validate-throws-coverage.d.ts

@@ -1,5 +1,5 @@
 import type { Environment } from "@marcbachmann/cel-js";
-import type { ResourceManifest } from "@telorun/sdk";
+import { type ResourceManifest } from "@telorun/sdk";
 import { type AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { type AnalysisDiagnostic } from "./types.js";

package/dist/validate-throws-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-throws-coverage.d.ts","sourceRoot":"","sources":["../src/validate-throws-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAOnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAoezE,oDAAoD;AACpD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,WAAW,EAChB,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAa,EACvD,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,GACnC,kBAAkB,EAAE,CAkDtB"}
+{"version":3,"file":"validate-throws-coverage.d.ts","sourceRoot":"","sources":["../src/validate-throws-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAOnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA0ezE,oDAAoD;AACpD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,WAAW,EAChB,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAa,EACvD,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,GACnC,kBAAkB,EAAE,CAkDtB"}

package/dist/validate-throws-coverage.js

@@ -1,4 +1,5 @@
 import { isTaggedSentinel } from "@telorun/templating";
+import { AMBIENT_CONTRACT_ERROR_CODES, isAmbientContractErrorCode, } from "@telorun/sdk";
 import { scopeResolverForModule } from "./alias-resolver.js";
 import { createResolveCtx, resolveThrowsUnion, } from "./resolve-throws-union.js";
 import { DiagnosticSeverity } from "./types.js";
@@ -186,12 +187,19 @@ function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env
         const { proven, codes } = extractCoveredCodes(e.when, env);
         if (proven) {
             for (const c of codes) {
+                // An ambient kernel code (contract violations) is raised by the kernel,
+                // not declared by the kind, so naming it is legal and still typo-checked
+                // — but it is NOT part of the declared union, so it never counts toward
+                // coverage. Folding these into every union would make every bounded
+                // catches: block in the standard library incomplete overnight.
+                if (isAmbientContractErrorCode(c))
+                    continue;
                 if (!declaredCodes.has(c)) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
                         code: "UNDECLARED_THROW_CODE",
                         source: SOURCE,
-                        message: `catches[${i}] references code '${c}' which is not in the handler's declared throw union {${[...declaredCodes].sort().join(", ") || "∅"}}${union.unbounded ? " (union is unbounded — a catch-all is required)" : ""}.`,
+                        message: `catches[${i}] references code '${c}' which is not in the handler's declared throw union {${[...declaredCodes].sort().join(", ") || "∅"}} (ambient kernel codes ${AMBIENT_CONTRACT_ERROR_CODES.join(", ")} may also be named)${union.unbounded ? "; the union is unbounded, so a catch-all is required" : ""}.`,
                         data: { resource, filePath, path: `${arrayPath}[${i}].when` },
                     });
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -48,7 +48,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.60.0"
+    "@telorun/sdk": "0.61.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"