@telorun/analyzer 0.71.0 → 0.72.0

package/dist/validate-ref-slots.js

@@ -83,8 +83,42 @@ function checkAnnotation(annotation, manifest, path, issues) {
             }
         }
     }
+    // `throwsThrough` is read as `=== true`, so anything else is silently absent —
+    // and absent means the declaring resource's catch scope stops enclosing what
+    // it holds, so every route under it starts reporting UNCOVERED_THROW_CODE with
+    // nothing naming the cause. The same failure `X_TELO_REF_INVALID_USE` exists
+    // to prevent, one key over.
+    if (obj.throwsThrough !== undefined && typeof obj.throwsThrough !== "boolean") {
+        issues.push({
+            code: "X_TELO_REF_INVALID_THROWS_THROUGH",
+            manifest,
+            path,
+            message: `x-telo-ref at '${path}' declares 'throwsThrough: ${JSON.stringify(obj.throwsThrough)}', ` +
+                `which is not a boolean. Only 'true' declares that throws from this slot's target ` +
+                `surface through the declaring resource; anything else reads as absent, which ` +
+                `silently stops its catch list from enclosing what it holds.`,
+        });
+    }
+    // Closed, for the reason the token sets are: a misspelled key is indexed by
+    // nothing and read by nothing, so it validates, ships, and does exactly what
+    // omitting it would.
+    for (const key of Object.keys(obj)) {
+        if (REF_ANNOTATION_KEYS.has(key))
+            continue;
+        issues.push({
+            code: "X_TELO_REF_UNKNOWN_KEY",
+            manifest,
+            path,
+            message: `x-telo-ref at '${path}' declares unrecognized key '${key}'. Known keys: ` +
+                `${[...REF_ANNOTATION_KEYS].sort().join(", ")}. An unrecognized key is read by nothing, ` +
+                `so it has exactly the effect of leaving it out.`,
+        });
+    }
     return declaredUses(use);
 }
+/** Every key the structured `x-telo-ref` form accepts — the write side of
+ *  `readRefSlot`'s read side. Adding one belongs in both. */
+const REF_ANNOTATION_KEYS = new Set(["kind", "use", "inputs", "throwsThrough"]);
 /** True when a node is a reference slot: it carries `x-telo-ref` directly or on
  *  an `anyOf`/`oneOf` branch. */
 function carriesRefAnnotation(obj) {

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAarD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAMnE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,kBAAkB;AAC5B;8EAC8E;AAC9E,aAAa,UAAQ,GACpB,OAAO,CAwBT;AAgED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA0hBtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAarD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAMnE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,kBAAkB;AAC5B;8EAC8E;AAC9E,aAAa,UAAQ,GACpB,OAAO,CAwBT;AAgED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAwjBtB"}

package/dist/validate-references.js

@@ -509,14 +509,38 @@ export function validateReferences(resources, context) {
                 for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                     if (fieldValue == null)
                         continue;
-                    const issues = registry.validateWithRefs(fieldValue, subSchema);
+                    // CEL leaves become schema-shaped placeholders first, exactly as the
+                    // sibling-ref branch below does and for the same reason: a slot
+                    // anchored at a shared value-shape is overwhelmingly written as
+                    // expressions, so validating it raw reports every one of them as a
+                    // type error and the check fires only on the literal case nobody
+                    // writes. Omitting it here made one annotation mean two different
+                    // things depending on which branch resolved it — a `when:` typed
+                    // `boolean` accepted a `!cel` at a route's inline slot and rejected
+                    // the identical expression at a slot anchored on the carrier that
+                    // declares that very shape.
+                    const substituted = substituteCelFields(fieldValue, subSchema);
+                    // Anchored at the offending node INSIDE the value, not at the slot:
+                    // a `returns:` list is an array of entries, and reporting every one
+                    // of its issues on the `returns:` line puts three diagnostics on one
+                    // line and none on the entry that is wrong.
+                    const issues = registry.validateResourceConfig(substituted, subSchema);
                     for (const issue of issues) {
                         diagnostics.push({
                             severity: DiagnosticSeverity.Error,
                             code: "DEPENDENT_SCHEMA_MISMATCH",
                             source: SOURCE,
-                            message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
-                            data: { resource: resourceData, filePath, path: concretePath },
+                            message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue.message}`,
+                            data: {
+                                resource: resourceData,
+                                filePath,
+                                // An index-first sub-path (`[0].content`) joins with no dot.
+                                path: !issue.path
+                                    ? concretePath
+                                    : issue.path.startsWith("[")
+                                        ? `${concretePath}${issue.path}`
+                                        : `${concretePath}.${issue.path}`,
+                            },
                         });
                     }
                 }

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,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;AAsfzE,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;AACpC;;+BAE+B;AAC/B,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAa,GAC3D,kBAAkB,EAAE,CAyDtB"}
+{"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,EAIL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAenE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA4kBzE,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;AACpC;;+BAE+B;AAC/B,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAa,GAC3D,kBAAkB,EAAE,CAsLtB"}

package/dist/validate-throws-coverage.js

@@ -1,7 +1,8 @@
 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 { createResolveCtx, resolveScopeUnion, resolveThrowsUnion, } from "./resolve-throws-union.js";
+import { buildEnclosers, collectScopedManifests, enclosingCoverage, } from "./catch-scope.js";
 import { DiagnosticSeverity } from "./types.js";
 import { extractAccessChains, validateChainAgainstSchema } from "./validate-cel-context.js";
 import { isStepSlot } from "./step-slot.js";
@@ -49,7 +50,11 @@ function walkSchemaData(schema, data, path, ctx) {
                 }
                 else {
                     const catchesFor = propSchema["x-telo-catches-for"];
-                    if (catchesFor) {
+                    // The EMPTY pointer names the resource the list is written on, the
+                    // spelling `x-telo-schema-projection-from` already uses for the same
+                    // "this declaration, not one it references" meaning — so the test is
+                    // presence, never truthiness.
+                    if (catchesFor !== undefined) {
                         // Fire even when absent so the coverage check can flag handlers
                         // whose declared union is non-empty but the list is missing.
                         ctx.onCatches(entries, nextPath, dataObj, catchesFor);
@@ -152,7 +157,7 @@ function isErrorCodeRef(node) {
     return obj.op === "id" && obj.args === "error";
 }
 /** Rule 7: within an outcome list, a no-`when:` entry must be the last entry. */
-function checkCatchAllPlacement(entries, resource, channel, filePath, arrayPath) {
+function checkCatchAllPlacement(entries, resource, channel, filePath, arrayPath, routing = resource) {
     const diagnostics = [];
     for (let i = 0; i < entries.length - 1; i++) {
         const e = entries[i];
@@ -162,80 +167,103 @@ function checkCatchAllPlacement(entries, resource, channel, filePath, arrayPath)
                 code: "CATCHALL_NOT_LAST",
                 source: SOURCE,
                 message: `${channel}: catch-all entry (no \`when:\`) at index ${i} must be last — entries after it are unreachable.`,
-                data: { resource, filePath, path: `${arrayPath}[${i}]` },
+                data: { resource: routing, filePath, path: `${arrayPath}[${i}]` },
             });
         }
     }
     return diagnostics;
 }
-/** Rule 1 + Rule 4: check declared-union coverage and reject undeclared codes
- *  in coverage-proving `when:` clauses. Phase 2 accepts inherit/passthrough
- *  handler unions too — when the resolved union is unbounded, a catch-all is
- *  required (rule 4 extension). */
-function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env, handler) {
-    const diagnostics = [];
-    const declaredCodes = new Set(union.codes.keys());
-    const covered = new Set();
+/** Read one list's {@link ProvenCoverage} — the codes its coverage-proving
+ *  `when:` clauses name, and whether it ends in a catch-all. */
+function provenCoverage(entries, env) {
+    const codes = new Set();
     let hasCatchAll = false;
-    for (let i = 0; i < entries.length; i++) {
-        const e = entries[i];
+    for (const e of entries) {
         if (!e)
             continue;
         if (!e.when) {
             hasCatchAll = true;
             continue;
         }
+        const { proven, codes: entryCodes } = extractCoveredCodes(e.when, env);
+        if (!proven)
+            continue;
+        for (const c of entryCodes)
+            codes.add(c);
+    }
+    return { codes, hasCatchAll };
+}
+/** Rule 4: a coverage-proving `when:` may only name a code the list's own
+ *  denominator can produce. Runs for EVERY list, scope lists included — the
+ *  denominator differs (a handler's union, or the enclosing resource's own), the
+ *  typo check does not. */
+function checkUndeclaredCodes(entries, union, resource, filePath, arrayPath, env, denominator, routing = resource) {
+    const diagnostics = [];
+    const declaredCodes = new Set(union.codes.keys());
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        if (!e?.when)
+            continue;
         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(", ") || "∅"}} (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` },
-                    });
-                }
-                else {
-                    covered.add(c);
-                }
-            }
+        if (!proven)
+            continue;
+        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))
+                continue;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "UNDECLARED_THROW_CODE",
+                source: SOURCE,
+                message: `catches[${i}] references code '${c}' which is not in ${denominator} {${[...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: routing, filePath, path: `${arrayPath}[${i}].when` },
+            });
         }
     }
+    return diagnostics;
+}
+/** Rule 1 + the unbounded-union rule, asked ONCE per dispatch site over every
+ *  list that can render its throws — the site's own, its resource's scope list,
+ *  and every scope enclosing that resource.
+ *
+ *  Asking it per list is what would make this a false check rather than a
+ *  missing one: a route that declares no `catches:` under a router that renders
+ *  everything is completely covered, and reporting it fires on precisely the
+ *  manifests scope lists exist to enable. */
+function checkCoverage(union, resource, filePath, arrayPath, handler, covered, routing = resource) {
+    const diagnostics = [];
+    if (covered.hasCatchAll)
+        return diagnostics;
     // Unbounded union (passthrough or transitive): authors can't enumerate the
-    // codes, so a catch-all is mandatory.
-    if (union.unbounded && !hasCatchAll) {
+    // codes, so a catch-all is mandatory — at this list or any enclosing scope.
+    if (union.unbounded) {
         diagnostics.push({
             severity: DiagnosticSeverity.Error,
             code: "UNBOUNDED_UNION_NEEDS_CATCHALL",
             source: SOURCE,
-            message: `The handler's throw union is unbounded (inherit/passthrough resolution couldn't enumerate all codes). The catches: list must include a catch-all entry (no \`when:\`).`,
-            data: { resource, filePath, path: arrayPath },
+            message: `The handler's throw union is unbounded (inherit/passthrough resolution couldn't enumerate all codes). A catch-all entry (no \`when:\`) is required — on this catches: list or on an enclosing one.`,
+            data: { resource: routing, filePath, path: arrayPath },
         });
     }
-    if (!hasCatchAll) {
-        // One diagnostic per block, not per code: every uncovered code sits at the
-        // same `catches:` array, and one catch-all answers all of them at once. A
-        // diagnostic each repeated the same location and the same fix N times.
-        const uncovered = [...declaredCodes].filter((c) => !covered.has(c)).sort();
-        if (uncovered.length > 0) {
-            diagnostics.push({
-                severity: DiagnosticSeverity.Error,
-                code: "UNCOVERED_THROW_CODE",
-                source: SOURCE,
-                message: `handler ${handler?.name ? `\`!ref ${handler.name}\`` : `\`${handler?.kind ?? "?"}\``} can throw ${uncovered.length} code${uncovered.length === 1 ? "" : "s"} that no catches: entry handles: ${uncovered.map((c) => `'${c}'`).join(", ")}. ` +
-                    `Give each a matching \`when:\` (e.g. \`when: !cel "error.code == '${uncovered[0]}'"\`), or add a catch-all entry — one with no \`when:\`, placed last.`,
-                data: { resource, filePath, path: arrayPath, uncovered },
-            });
-        }
+    // One diagnostic per site, not per code: every uncovered code sits at the
+    // same dispatch site, and one catch-all answers all of them at once. A
+    // diagnostic each repeated the same location and the same fix N times.
+    const uncovered = [...union.codes.keys()].filter((c) => !covered.codes.has(c)).sort();
+    if (uncovered.length > 0) {
+        diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "UNCOVERED_THROW_CODE",
+            source: SOURCE,
+            message: `handler ${handler?.name ? `\`!ref ${handler.name}\`` : `\`${handler?.kind ?? "?"}\``} can throw ${uncovered.length} code${uncovered.length === 1 ? "" : "s"} that no catches: entry handles — at this list or any enclosing scope: ${uncovered.map((c) => `'${c}'`).join(", ")}. ` +
+                `Give each a matching \`when:\` (e.g. \`when: !cel "error.code == '${uncovered[0]}'"\`), or add a catch-all entry — one with no \`when:\`, placed last.`,
+            data: { resource: routing, filePath, path: arrayPath, uncovered },
+        });
     }
     return diagnostics;
 }
@@ -243,7 +271,7 @@ function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env
  *  type-check against the data schema declared for the matched code(s). When the
  *  matching `when:` disjunctively covers multiple codes, use the intersection
  *  of their data schemas so only fields present on every code narrow through. */
-function checkTypedErrorData(entries, union, resource, filePath, arrayPath, env) {
+function checkTypedErrorData(entries, union, resource, filePath, arrayPath, env, routing = resource) {
     const diagnostics = [];
     // If the union is unbounded we can't narrow data schemas reliably — skip
     // typed-data checks for those entries. The catch-all path still provides
@@ -274,16 +302,14 @@ function checkTypedErrorData(entries, union, resource, filePath, arrayPath, env)
         if (schemas.length === 0)
             continue;
         const dataSchema = intersectDataSchemas(schemas);
-        // Walk CEL expressions inside this entry's body / headers — only
-        // string-valued fields can contain CEL templates.
-        collectCelStrings(e.body, `${arrayPath}[${i}].body`).forEach((entry) => {
-            diagnostics.push(...checkCelChainAgainstDataSchema(entry, dataSchema, resource, filePath, env));
+        // The WHOLE entry, not an enumerated `body` / `headers` pair. An HTTP catch
+        // entry keeps its body at `content[<mime>].body`, so reading `e.body` walked
+        // a field that shape never has and this check was inert for every catch list
+        // in the standard library. Walking the entry also covers `when:` and the
+        // per-MIME header overrides, which are equally places `error.data` is read.
+        collectCelStrings(e, `${arrayPath}[${i}]`).forEach((entry) => {
+            diagnostics.push(...checkCelChainAgainstDataSchema(entry, dataSchema, resource, filePath, env, routing));
         });
-        if (e.headers) {
-            collectCelStrings(e.headers, `${arrayPath}[${i}].headers`).forEach((entry) => {
-                diagnostics.push(...checkCelChainAgainstDataSchema(entry, dataSchema, resource, filePath, env));
-            });
-        }
     }
     return diagnostics;
 }
@@ -319,6 +345,15 @@ function intersectPropertySchemas(schemas) {
 }
 function collectCelStrings(value, path) {
     const out = [];
+    // A `!cel` sentinel and a `${{ … }}` string are load-equivalent, and the
+    // formatter normalizes to the tag — so recognising only the string form left
+    // this check answering about a spelling no manifest in the repository uses,
+    // while walking the sentinel as a plain object found nothing.
+    if (isTaggedSentinel(value)) {
+        if (value.engine === "cel")
+            out.push({ expr: value.source.trim(), path });
+        return out;
+    }
     if (typeof value === "string") {
         for (const m of value.matchAll(TEMPLATE_REGEX)) {
             out.push({ expr: m[1].trim(), path });
@@ -338,7 +373,7 @@ function collectCelStrings(value, path) {
     }
     return out;
 }
-function checkCelChainAgainstDataSchema(entry, dataSchema, resource, filePath, env) {
+function checkCelChainAgainstDataSchema(entry, dataSchema, resource, filePath, env, routing = resource) {
     let ast;
     try {
         ast = env.parse(entry.expr).ast;
@@ -360,7 +395,7 @@ function checkCelChainAgainstDataSchema(entry, dataSchema, resource, filePath, e
                 code: "CEL_UNKNOWN_FIELD",
                 source: SOURCE,
                 message: `${resource.kind}/${resource.name}: CEL at '${entry.path}': error.data.${err}`,
-                data: { resource, filePath, path: entry.path },
+                data: { resource: routing, filePath, path: entry.path },
             });
         }
     }
@@ -372,6 +407,30 @@ function checkCelChainAgainstDataSchema(entry, dataSchema, resource, filePath, e
  *  carrying the legacy `x-telo-step-context` annotation. That is what drives the
  *  resolver's generic step traversal; a definition with `inherit: true` and no
  *  such array has no invocables to inherit from. */
+/** The capabilities whose lifecycle includes a dispatch a caller can catch. On
+ *  every other one a thrown error is a boot-time failure, not a structured
+ *  runtime error for a downstream caller — a provider resolves configuration, a
+ *  type has no instance, a sink is written to directly, and a service or mount
+ *  is STARTED rather than called (what a router renders is not what a router
+ *  throws).
+ *
+ *  The strict half of the kernel's `ResourceDefinitionSchema` rule 8, and it has
+ *  to exist here for the reason every `x-telo-*` accessor has a strict half: the
+ *  kernel refuses at `create()`, which is a boot failure on a manifest that
+ *  passed `telo check` — the static/runtime disagreement this repository treats
+ *  as a defect. The two must agree; a change to either belongs in both.
+ *
+ *  **Reported for a DEPENDENCY's definition too**, unlike `X_TELO_REF_UNRESOLVED`
+ *  and `DEPRECATED_KIND`, which are entry-module-scoped. Those report something a
+ *  consumer can live with — a slot that cannot be checked, a kind that still
+ *  works — so silence costs them nothing and the noise is not theirs to fix.
+ *  This one reports a definition the kernel REFUSES, so the manifest importing it
+ *  cannot start at all: withholding that would replace a `telo check` error with
+ *  an identical boot failure and no earlier warning. The action is a consumer's
+ *  to take (pin another version, report upstream) even though the edit is not.
+ *  Matches the neighbouring `INHERIT_WITHOUT_STEP_CONTEXT`, which is fatal the
+ *  same way. */
+const THROWS_CAPABLE_CAPABILITIES = new Set(["Telo.Invocable", "Telo.Runnable"]);
 function validateThrowsDeclarations(manifests) {
     const diagnostics = [];
     for (const m of manifests) {
@@ -382,9 +441,27 @@ function validateThrowsDeclarations(manifests) {
             continue;
         const name = m.metadata?.name ?? "<unnamed>";
         const filePath = m.metadata?.source;
+        // Only a DECLARED capability is judged. One inherited through `extends` is
+        // resolved elsewhere, and an unknown one is third-party extensibility the
+        // kernel's schema deliberately leaves open.
+        const capability = m.capability;
+        if (typeof capability === "string" && !THROWS_CAPABLE_CAPABILITIES.has(capability)) {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "THROWS_ON_NON_DISPATCH_CAPABILITY",
+                source: SOURCE,
+                message: `Telo.Definition '${name}' declares throws: but its capability is '${capability}'. ` +
+                    `A throw union describes what a CALLER can catch, so it is only meaningful on ` +
+                    `${[...THROWS_CAPABLE_CAPABILITIES].join(" or ")}; on '${capability}' a thrown error is a ` +
+                    `boot-time failure with no caller to render it. The kernel refuses this definition at ` +
+                    `create(), so a manifest carrying it cannot start.`,
+                data: { resource: { kind: m.kind, name }, filePath, path: "throws" },
+            });
+            continue;
+        }
         if (throws.inherit === true) {
             const schema = m.schema;
-            if (!schemaHasStepContext(schema)) {
+            if (!schemaDrivesInvocables(schema)) {
                 diagnostics.push({
                     severity: DiagnosticSeverity.Error,
                     code: "INHERIT_WITHOUT_STEP_CONTEXT",
@@ -400,7 +477,7 @@ function validateThrowsDeclarations(manifests) {
     }
     return diagnostics;
 }
-function schemaHasStepContext(schema) {
+function schemaDrivesInvocables(schema) {
     if (!schema || typeof schema !== "object")
         return false;
     if (isStepSlot(schema))
@@ -408,23 +485,23 @@ function schemaHasStepContext(schema) {
     const props = schema.properties;
     if (props && typeof props === "object") {
         for (const v of Object.values(props)) {
-            if (schemaHasStepContext(v))
+            if (schemaDrivesInvocables(v))
                 return true;
         }
     }
-    if (schema.items && schemaHasStepContext(schema.items))
+    if (schema.items && schemaDrivesInvocables(schema.items))
         return true;
     for (const key of ["oneOf", "anyOf", "allOf"]) {
         const arr = schema[key];
         if (Array.isArray(arr)) {
             for (const sub of arr)
-                if (schemaHasStepContext(sub))
+                if (schemaDrivesInvocables(sub))
                     return true;
         }
     }
     if (schema.$defs && typeof schema.$defs === "object") {
         for (const v of Object.values(schema.$defs)) {
-            if (schemaHasStepContext(v))
+            if (schemaDrivesInvocables(v))
                 return true;
         }
     }
@@ -438,32 +515,106 @@ export function validateThrowsCoverage(manifests, defs, aliases, env, aliasesByM
 moduleManifests = new Map()) {
     const diagnostics = [];
     diagnostics.push(...validateThrowsDeclarations(manifests));
-    const resolveCtx = createResolveCtx(manifests, defs, aliases, aliasesByModule, rootModules, moduleManifests);
+    // A `with:`-scoped declaration is a resource like any other — it has a kind, a
+    // name, and, for a scoped `Http.Server`, a catch list that renders what its
+    // mounts throw. It is simply not in the flat set, so every check here used to
+    // skip it: its own entries went unchecked AND its coverage reached nothing it
+    // encloses. Standing a server up around a test is exactly that shape, so the
+    // sanctioned pattern was the one the pass could not see.
+    //
+    // Discovered through the shared visitor rather than a second scope walk, and
+    // folded into the pool every name is resolved against — a scoped mount whose
+    // target the resolver cannot find reads as an empty union, which reports every
+    // entry of that server's list as naming a code nothing throws.
+    const scoped = collectScopedManifests(manifests, defs, aliases, aliasesByModule, rootModules);
+    const allManifests = [...manifests, ...scoped.map((s) => s.manifest)];
+    const resolveCtx = createResolveCtx(allManifests, defs, aliases, aliasesByModule, rootModules, moduleManifests);
     // The alias resolver for a manifest's own lexical scope — an imported library's
     // resolver when it owns the manifest, else undefined (fall back to root aliases).
     const scopeResolverFor = (m) => scopeResolverForModule(m.metadata?.module, rootModules, aliasesByModule);
-    for (const manifest of manifests) {
+    // Pass 1 — read every outcome list, and record which resources each scope
+    // list encloses. A scope list has to be known before any site it covers is
+    // judged, so collection and judgement cannot be one loop.
+    const sites = [];
+    const scopeOf = new Map();
+    const scopedBy = new Map();
+    for (const s of scoped)
+        scopedBy.set(s.manifest, s);
+    const definitionFor = (manifest) => {
+        // A scoped declaration's kind is written in the alias scope of the module
+        // that declared the ENCLOSING resource; it carries no `metadata.module` of
+        // its own to find one by.
+        const anchor = scopedBy.get(manifest)?.owner ?? manifest;
+        const scopeResolver = scopeResolverFor(anchor);
+        const resolvedKind = scopeResolver?.resolveKind(manifest.kind) ?? aliases.resolveKind(manifest.kind);
+        return defs.resolve(manifest.kind) ?? (resolvedKind ? defs.resolve(resolvedKind) : undefined);
+    };
+    const enclosers = buildEnclosers(allManifests, definitionFor, (m) => (scopedBy.get(m)?.owner ?? m).metadata?.module, resolveCtx);
+    for (const manifest of allManifests) {
         if (!manifest.kind || !manifest.metadata?.name)
             continue;
         if (manifest.kind === "Telo.Definition" || manifest.kind === "Telo.Abstract")
             continue;
-        const scopeResolver = scopeResolverFor(manifest);
-        const resolvedKind = scopeResolver?.resolveKind(manifest.kind) ?? aliases.resolveKind(manifest.kind);
-        const definition = defs.resolve(manifest.kind) ?? (resolvedKind ? defs.resolve(resolvedKind) : undefined);
+        // A scoped declaration is reported against the document it is WRITTEN in —
+        // its owner's — at its own position inside that owner's scope array, because
+        // position lookup finds a TOP-LEVEL doc by (kind, name) and a scoped
+        // resource is not one. The message still names the scoped resource, so the
+        // reader is not sent to a resource that has no `catches:` at all.
+        const enclosing = scopedBy.get(manifest);
+        const anchor = enclosing?.owner ?? manifest;
+        const pathPrefix = enclosing ? `${enclosing.path}.` : "";
+        const scopeResolver = scopeResolverFor(anchor);
+        const definition = definitionFor(manifest);
         if (!definition?.schema)
             continue;
         const resource = { kind: manifest.kind, name: manifest.metadata.name };
-        const filePath = manifest.metadata?.source;
+        const routing = enclosing
+            ? { kind: anchor.kind, name: anchor.metadata.name }
+            : resource;
+        const filePath = anchor.metadata?.source;
         collectOutcomeLists(manifest, definition.schema, (ret) => {
-            diagnostics.push(...checkCatchAllPlacement(ret.entries, resource, "returns", filePath, ret.arrayPath));
+            diagnostics.push(...checkCatchAllPlacement(ret.entries, resource, "returns", filePath, `${pathPrefix}${ret.arrayPath}`, routing));
         }, (entries, arrayPath, siblingData, catchesFor) => {
-            diagnostics.push(...checkCatchAllPlacement(entries, resource, "catches", filePath, arrayPath));
-            const handlerRef = resolveHandlerRef(siblingData[catchesFor]);
-            const union = handlerRefUnion(handlerRef, manifests, resolveCtx, scopeResolver);
-            diagnostics.push(...checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env, handlerRef));
-            diagnostics.push(...checkTypedErrorData(entries, union, resource, filePath, arrayPath, env));
+            const site = {
+                manifest,
+                definition,
+                resource,
+                routing,
+                filePath,
+                entries,
+                arrayPath: `${pathPrefix}${arrayPath}`,
+                scopeResolver,
+                handlerRef: catchesFor === "" ? null : resolveHandlerRef(siblingData[catchesFor]),
+                isScope: catchesFor === "",
+            };
+            sites.push(site);
+            if (site.isScope)
+                scopeOf.set(manifest, provenCoverage(entries, env));
         });
     }
+    const coverageMemo = new Map();
+    const scopeCoverageFor = (manifest) => enclosingCoverage(manifest, scopeOf, enclosers, coverageMemo);
+    // Pass 2 — judge each list against its own denominator, and each dispatch site
+    // against everything that can render its throws.
+    for (const site of sites) {
+        diagnostics.push(...checkCatchAllPlacement(site.entries, site.resource, "catches", site.filePath, site.arrayPath, site.routing));
+        const union = site.isScope
+            ? resolveScopeUnion(site.manifest, site.definition, resolveCtx)
+            : handlerRefUnion(site.handlerRef, allManifests, resolveCtx, site.scopeResolver);
+        diagnostics.push(...checkUndeclaredCodes(site.entries, union, site.resource, site.filePath, site.arrayPath, env, site.isScope
+            ? "the throw union of everything this resource drives"
+            : "the handler's declared throw union", site.routing));
+        diagnostics.push(...checkTypedErrorData(site.entries, union, site.resource, site.filePath, site.arrayPath, env, site.routing));
+        if (site.isScope)
+            continue;
+        const own = provenCoverage(site.entries, env);
+        const scope = scopeCoverageFor(site.manifest);
+        const covered = {
+            codes: new Set([...own.codes, ...scope.codes]),
+            hasCatchAll: own.hasCatchAll || scope.hasCatchAll,
+        };
+        diagnostics.push(...checkCoverage(union, site.resource, site.filePath, site.arrayPath, site.handlerRef, covered, site.routing));
+    }
     return diagnostics;
 }
 /** Resolve a handler ref's effective throw union. Prefers the named manifest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,7 +43,7 @@
     "jsonpath-plus": "^10.3.0",
     "packageurl-js": "^2.0.1",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.18.0"
+    "@telorun/templating": "0.19.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",