@telorun/analyzer 0.32.0 → 0.33.0

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAmB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAwjB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAkyBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAmBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAmB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA2wB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA0yBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAmBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -1,5 +1,5 @@
 import { canonicalTypeSchemaId } from "@telorun/sdk";
-import { defaultRegistry, isTaggedSentinel } from "@telorun/templating";
+import { defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import { AliasResolver, scopeResolverForModule } from "./alias-resolver.js";
 import { buildCelEnvironment, buildImportInputCelEnvironment, buildTypedCelEnvironment, } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
@@ -20,6 +20,7 @@ import { extractCelRegionScopes, extractContextsFromSchema, getManifestItem, pat
 import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
+import { validateKindDescriptions } from "./validate-kind-descriptions.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
 import { validateReferenceForms } from "./validate-reference-forms.js";
@@ -186,6 +187,59 @@ function gatherPropertySchemas(schema) {
     }
     return out;
 }
+/**
+ * Generic, role-driven walk over an `x-telo-step-context` step array. Calls
+ * `visit(step, stepPath)` for every step — top-level and nested through the
+ * `x-telo-topology-role` forms (`branch`, `branch-list`, `case-map`). This is
+ * the single definition of how steps nest, shared by `buildStepContextSchema`
+ * (which types `steps.<name>.result`) and `validateStepInvokeReferences` (which
+ * checks invoke refs), so the topology contract lives in one place — adding a
+ * role or nesting form updates both consumers at once. No resource kind is
+ * hardcoded; recursion is driven entirely by the schema annotations.
+ */
+function walkStepArray(steps, stepItemSchema, rootSchema, basePath, visit) {
+    const dispatchRole = (data, role, itemsSchema, path) => {
+        if (role === "branch" && Array.isArray(data)) {
+            walkStepArray(data, stepItemSchema, rootSchema, path, visit);
+        }
+        else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
+            for (const [caseKey, arr] of Object.entries(data)) {
+                if (Array.isArray(arr))
+                    walkStepArray(arr, stepItemSchema, rootSchema, `${path}.${caseKey}`, visit);
+            }
+        }
+        else if (role === "branch-list" && Array.isArray(data)) {
+            const entrySchema = resolveLocalRef(itemsSchema, rootSchema);
+            if (!entrySchema)
+                return;
+            data.forEach((entry, i) => {
+                if (!entry || typeof entry !== "object")
+                    return;
+                for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
+                    const subRole = subSchema["x-telo-topology-role"];
+                    if (typeof subRole !== "string")
+                        continue;
+                    dispatchRole(entry[subKey], subRole, subSchema.items, `${path}[${i}].${subKey}`);
+                }
+            });
+        }
+    };
+    steps.forEach((step, i) => {
+        if (!step || typeof step !== "object")
+            return;
+        const s = step;
+        const stepPath = `${basePath}[${i}]`;
+        visit(s, stepPath);
+        if (!stepItemSchema)
+            return;
+        for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
+            const role = propSchema["x-telo-topology-role"];
+            if (typeof role !== "string")
+                continue;
+            dispatchRole(s[propKey], role, propSchema.items, `${stepPath}.${propKey}`);
+        }
+    });
+}
 /**
  * Build a `steps` context schema from `x-telo-step-context` annotation.
  * Walks each step in the manifest array, resolves the invoked resource's outputType,
@@ -229,80 +283,40 @@ function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases
             continue;
         const stepItemSchema = resolveLocalRef(fieldSchema.items, defSchema);
         const stepProperties = {};
-        const dispatchRole = (data, role, itemsSchema) => {
-            if (role === "branch" && Array.isArray(data)) {
-                collectSteps(data);
-            }
-            else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
-                for (const arr of Object.values(data)) {
-                    if (Array.isArray(arr))
-                        collectSteps(arr);
+        walkStepArray(steps, stepItemSchema, defSchema, fieldName, (s) => {
+            const name = s.name;
+            const invoke = s[invokeField];
+            // Only invoke steps register a `steps.<name>.result` entry — control-flow
+            // wrappers (try/if/while/switch/throw) don't produce a result and must
+            // not shadow real entries with a permissive `additionalProperties: true`,
+            // or unknown step references slip through chain validation.
+            if (typeof name !== "string" || !invoke || typeof invoke !== "object")
+                return;
+            let outputSchema;
+            const invokedKind = invoke.kind;
+            const invokedName = invoke.name;
+            if (invokedName) {
+                const invokedManifest = allManifests.find((m) => m.metadata?.name === invokedName &&
+                    (!invokedKind || m.kind === invokedKind));
+                if (invokedManifest) {
+                    outputSchema = resolveTypeFieldToSchema(invokedManifest[outputTypeField], allManifests);
                 }
             }
-            else if (role === "branch-list" && Array.isArray(data)) {
-                const entrySchema = resolveLocalRef(itemsSchema, defSchema);
-                if (!entrySchema)
-                    return;
-                for (const entry of data) {
-                    if (!entry || typeof entry !== "object")
-                        continue;
-                    for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
-                        const subRole = subSchema["x-telo-topology-role"];
-                        if (typeof subRole !== "string")
-                            continue;
-                        dispatchRole(entry[subKey], subRole, subSchema.items);
-                    }
-                }
+            else {
+                outputSchema = resolveTypeFieldToSchema(invoke[outputTypeField], allManifests);
             }
-        };
-        function collectSteps(items) {
-            for (const step of items) {
-                if (!step || typeof step !== "object")
-                    continue;
-                const s = step;
-                const name = s.name;
-                const invoke = s[invokeField];
-                // Only invoke steps register a `steps.<name>.result` entry — control-flow
-                // wrappers (try/if/while/switch/throw) don't produce a result and must
-                // not shadow real entries with a permissive `additionalProperties: true`,
-                // or unknown step references slip through chain validation.
-                if (typeof name === "string" && invoke && typeof invoke === "object") {
-                    let outputSchema;
-                    const invokedKind = invoke.kind;
-                    const invokedName = invoke.name;
-                    if (invokedName) {
-                        const invokedManifest = allManifests.find((m) => m.metadata?.name === invokedName &&
-                            (!invokedKind || m.kind === invokedKind));
-                        if (invokedManifest) {
-                            outputSchema = resolveTypeFieldToSchema(invokedManifest[outputTypeField], allManifests);
-                        }
-                    }
-                    else {
-                        outputSchema = resolveTypeFieldToSchema(invoke[outputTypeField], allManifests);
-                    }
-                    // Fallback: pull outputType from the kind's Telo.Definition. The
-                    // resource manifest typically doesn't carry outputType; the def does.
-                    if (!outputSchema && invokedKind) {
-                        outputSchema = lookupDefinitionTypeField(invokedKind, outputTypeField, defs, aliases, allManifests);
-                    }
-                    stepProperties[name] = {
-                        type: "object",
-                        properties: {
-                            result: outputSchema ?? { type: "object", additionalProperties: true },
-                        },
-                    };
-                }
-                if (stepItemSchema) {
-                    for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
-                        const role = propSchema["x-telo-topology-role"];
-                        if (typeof role !== "string")
-                            continue;
-                        dispatchRole(s[propKey], role, propSchema.items);
-                    }
-                }
+            // Fallback: pull outputType from the kind's Telo.Definition. The
+            // resource manifest typically doesn't carry outputType; the def does.
+            if (!outputSchema && invokedKind) {
+                outputSchema = lookupDefinitionTypeField(invokedKind, outputTypeField, defs, aliases, allManifests);
             }
-        }
-        collectSteps(steps);
+            stepProperties[name] = {
+                type: "object",
+                properties: {
+                    result: outputSchema ?? { type: "object", additionalProperties: true },
+                },
+            };
+        });
         if (Object.keys(stepProperties).length > 0) {
             return {
                 type: "object",
@@ -312,6 +326,178 @@ function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases
     }
     return undefined;
 }
+/**
+ * Capabilities whose instances structurally expose no `invoke`/`run` method, so
+ * a step `invoke` of one always fails at runtime with ERR_RESOURCE_NOT_INVOKABLE
+ * (kernel dispatch checks method presence, not capability — evaluation-context.ts).
+ * `Telo.Service` is intentionally absent: some services are invocable (a function
+ * handler dispatched directly, e.g. `Lambda.Function`), so it can't be rejected
+ * statically without false positives. This is the sound subset of the runtime rule.
+ */
+const NON_INVOKABLE_CAPABILITIES = new Set([
+    "Telo.Provider",
+    "Telo.Mount",
+    "Telo.Type",
+    "Telo.Template",
+]);
+/**
+ * Validate `x-telo-step-context` step `invoke` references (e.g. `Run.Sequence`
+ * steps).
+ *
+ * The reference field map deliberately does NOT descend into step `invoke`
+ * slots — they sit behind a local `$ref` to the shared step definition, and
+ * turning the descent on would make Phase 5 inject live instances there,
+ * breaking the invoke dispatch path (see `reference-field-map.ts`). A
+ * consequence is that `validateReferences` never sees these slots, so a bad
+ * step invoke passes `telo check` and only fails at runtime. This pass covers
+ * exactly those slots, in two dimensions:
+ *   - Existence: an `invoke: !ref <name>` that names a missing instance — or a
+ *     *kind* instead of an exported instance (`!ref Stream.Of`) — is a still-a-
+ *     sentinel after Phase 2.5 resolution → `UNRESOLVED_REFERENCE` (runtime
+ *     `ERR_RESOURCE_NOT_FOUND`).
+ *   - Invokability: a resolved instance whose capability structurally has no
+ *     invoke/run method (`NON_INVOKABLE_CAPABILITIES`) → `REFERENCE_KIND_MISMATCH`
+ *     (runtime `ERR_RESOURCE_NOT_INVOKABLE`).
+ *
+ * Generic and topology-driven — it walks steps via the same `x-telo-step-context`
+ * / `x-telo-topology-role` annotations `buildStepContextSchema` uses (through the
+ * shared `walkStepArray`), so nested branches (then/else/do/catch/cases) are
+ * covered and no `Run.Sequence` field name is hardcoded. The cross-module
+ * partial-analysis guard mirrors `validateReferences`, so a reference into an
+ * unloaded import is skipped rather than false-flagged.
+ */
+function validateStepInvokeReferences(allManifests, defs, aliases) {
+    const diagnostics = [];
+    // Local instance names + loaded-module set — same construction as
+    // validateReferences, so the cross-module guard behaves identically.
+    const localNames = new Set();
+    const loadedModules = new Set();
+    // Also collect names of resources nested inside a manifest tree — notably
+    // `with:`-scoped resources (an `x-telo-scope` region the field map does not
+    // extract to a top-level manifest). A step can invoke one by bare name, so
+    // omitting them would false-flag a valid `!ref`. Conservative: any nested
+    // object carrying both a `kind` and a `metadata.name` is a resource
+    // definition; scope visibility is left to the runtime.
+    const collectNestedNames = (value) => {
+        if (!value || typeof value !== "object" || isTaggedSentinel(value))
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                collectNestedNames(item);
+            return;
+        }
+        const obj = value;
+        const name = obj.metadata?.name;
+        if (typeof obj.kind === "string" && typeof name === "string")
+            localNames.add(name);
+        for (const v of Object.values(obj))
+            collectNestedNames(v);
+    };
+    for (const r of allManifests) {
+        if (r.kind === "Telo.Import") {
+            const m = r.metadata?.resolvedModuleName;
+            if (typeof m === "string")
+                loadedModules.add(m);
+            continue;
+        }
+        const meta = r.metadata;
+        if (typeof meta?.name !== "string" || REF_VALIDATION_SKIP_KINDS.has(r.kind))
+            continue;
+        if (meta.forwardedExport === true) {
+            if (typeof meta.module === "string")
+                loadedModules.add(meta.module);
+            continue;
+        }
+        localNames.add(meta.name);
+        collectNestedNames(r);
+    }
+    const validateInvoke = (value, resource, filePath, path) => {
+        if (isRefSentinel(value)) {
+            // An unresolved `!ref` is a miss: a real instance would have resolved to
+            // `{kind, name}` in Phase 2.5.
+            const refName = value.source;
+            const dot = refName.indexOf(".");
+            const aliasPrefix = dot > 0 ? refName.slice(0, dot) : undefined;
+            if (aliasPrefix && aliasPrefix !== "Self" && aliases.hasAlias(aliasPrefix)) {
+                const module = aliases.moduleForAlias(aliasPrefix);
+                // Partial single-file analysis (import not loaded) — skip to avoid a false miss.
+                if (module && !loadedModules.has(module))
+                    return;
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "UNRESOLVED_REFERENCE",
+                    source: SOURCE,
+                    message: `${resource.kind}/${resource.name}: step invoke at '${path}' → '${refName}' is not an exported instance of module '${module ?? aliasPrefix}' (reference a declared instance, not a kind)`,
+                    data: { resource, filePath, path },
+                });
+                return;
+            }
+            const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
+            if (localNames.has(localName))
+                return;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "UNRESOLVED_REFERENCE",
+                source: SOURCE,
+                message: `${resource.kind}/${resource.name}: step invoke at '${path}' → resource '${localName}' not found`,
+                data: { resource, filePath, path },
+            });
+            return;
+        }
+        // Resolved `{kind, name}` (or an inline `{kind, …}` definition) — the
+        // instance exists. Mirror the kernel's ERR_RESOURCE_NOT_INVOKABLE, which
+        // fires when the instance has neither an `invoke` nor a `run` method
+        // (evaluation-context.ts). That is a per-instance property, not a pure
+        // capability, so only capabilities that STRUCTURALLY expose no such method
+        // are rejected statically — Service is intentionally excluded, since some
+        // services are invocable (e.g. a function handler dispatched directly).
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return;
+        const kind = value.kind;
+        if (typeof kind !== "string")
+            return;
+        const capability = defs.resolve(aliases.resolveKind(kind) ?? kind)?.capability;
+        if (typeof capability === "string" && NON_INVOKABLE_CAPABILITIES.has(capability)) {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "REFERENCE_KIND_MISMATCH",
+                source: SOURCE,
+                message: `${resource.kind}/${resource.name}: step invoke at '${path}' → '${kind}' is a ${capability} and cannot be invoked in a step — it has no invoke or run method (runtime ERR_RESOURCE_NOT_INVOKABLE)`,
+                data: { resource, filePath, path },
+            });
+        }
+    };
+    for (const m of allManifests) {
+        const meta = m.metadata;
+        if (typeof meta?.name !== "string" ||
+            REF_VALIDATION_SKIP_KINDS.has(m.kind) ||
+            meta.forwardedExport === true)
+            continue;
+        const def = defs.resolve(aliases.resolveKind(m.kind) ?? m.kind);
+        const defSchema = def?.schema;
+        if (!defSchema?.properties)
+            continue;
+        const resource = { kind: m.kind, name: meta.name };
+        const filePath = typeof meta.source === "string" ? meta.source : undefined;
+        for (const [fieldName, fieldSchema] of Object.entries(defSchema.properties)) {
+            const stepCtx = fieldSchema["x-telo-step-context"];
+            const invokeField = stepCtx?.invoke;
+            if (!invokeField)
+                continue;
+            const steps = m[fieldName];
+            if (!Array.isArray(steps))
+                continue;
+            const stepItemSchema = resolveLocalRef(fieldSchema.items, defSchema);
+            walkStepArray(steps, stepItemSchema, defSchema, fieldName, (s, stepPath) => {
+                const invoke = s[invokeField];
+                if (invoke === undefined || invoke === null)
+                    return;
+                validateInvoke(invoke, resource, filePath, `${stepPath}.${invokeField}`);
+            });
+        }
+    }
+    return diagnostics;
+}
 /**
  * Collect every field annotated with `x-telo-error-context` anywhere in a
  * definition schema (resolving local `$ref`s into `$defs`, cycle-safe), mapping
@@ -1177,10 +1363,16 @@ export class StaticAnalyzer {
         }, { aliases });
         // Validate resource references (Phase 3)
         diagnostics.push(...validateReferences(allManifests, { aliases, definitions: defs, aliasesByModule }));
+        // Validate step `invoke` references — the slots the reference field map
+        // deliberately skips (behind the step `$ref`), so a missing instance or a
+        // kind-instead-of-instance ref there is caught statically, not at runtime.
+        diagnostics.push(...validateStepInvokeReferences(allManifests, defs, aliases));
         // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
         diagnostics.push(...validateExtends(allManifests, defs, aliases));
         // Validate provider coherence rules for `provide:` template-target definitions.
         diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
+        // Warn about exported kinds lacking a metadata.description (semantic-search input).
+        diagnostics.push(...validateKindDescriptions(allManifests));
         // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
         diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv, aliasesByModule, rootModules));
         // Warn about declared variables / secrets / ports that no CEL references.

package/dist/index.d.ts

@@ -21,7 +21,7 @@ export type { DocumentPosition } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
 export { defaultSources } from "./sources/default-sources.js";
-export { splitIntegrity, foldIntegrity, verifyIntegrity, verifiedFetch, sha256Base64Url, } from "./sources/integrity.js";
+export { splitIntegrity, foldIntegrity, verifyIntegrity, verifiedFetch, sha256Base64Url, IntegrityError, } from "./sources/integrity.js";
 export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export type { ParsedModuleRef } from "./sources/module-ref.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACH,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,gCAAgC,EAChC,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,YAAY,EACR,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EACH,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,aAAa,EACb,KAAK,EACR,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACH,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,gCAAgC,EAChC,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,YAAY,EACR,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EACH,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,aAAa,EACb,KAAK,EACR,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -13,7 +13,7 @@ export { buildDocumentPositions, buildLineOffsets, buildPositionIndex, documentL
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
 export { defaultSources } from "./sources/default-sources.js";
-export { splitIntegrity, foldIntegrity, verifyIntegrity, verifiedFetch, sha256Base64Url, } from "./sources/integrity.js";
+export { splitIntegrity, foldIntegrity, verifyIntegrity, verifiedFetch, sha256Base64Url, IntegrityError, } from "./sources/integrity.js";
 export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";

package/dist/sources/integrity.d.ts

@@ -5,6 +5,13 @@
  *  The fragment is authoritative across every transport: a source's `read()`
  *  hashes the fetched bytes and compares against it before the manifest is
  *  parsed or cached. A mismatch is a terminal error — never a cache miss. */
+/** A failed integrity/tamper check — always terminal, never best-effort. A
+ *  distinct type so a caller doing best-effort network handling (e.g. the
+ *  bundle extractor warning-and-skipping on a fetch blip) can still let a
+ *  tamper error propagate rather than swallow it. */
+export declare class IntegrityError extends Error {
+    constructor(message: string);
+}
 /** Split a trailing integrity fragment off a ref/URL. Returns the bare ref in
  *  `base` (safe to build fetch URLs and cache paths from) and the fragment in
  *  `integrity` (e.g. `sha256-<base64url>`), or `undefined` when absent. */

package/dist/sources/integrity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../../src/sources/integrity.ts"],"names":[],"mappings":"AAAA;;;;;;6EAM6E;AAO7E;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAIhF;AAED;;;kFAGkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAIxE;AAcD,iFAAiF;AACjF,wBAAsB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAOxE;AAED;;gFAEgF;AAChF,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;sCAIsC;AACtC,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAU9C"}
+{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../../src/sources/integrity.ts"],"names":[],"mappings":"AAAA;;;;;;6EAM6E;AAO7E;;;qDAGqD;AACrD,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAIhF;AAED;;;kFAGkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAIxE;AAcD,iFAAiF;AACjF,wBAAsB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAOxE;AAED;;gFAEgF;AAChF,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;sCAIsC;AACtC,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAU9C"}

package/dist/sources/integrity.js

@@ -9,6 +9,16 @@
  *  fragments (rare in module refs) pass through untouched. `sha256` is the
  *  only algorithm accepted today; the prefix leaves room to migrate. */
 const INTEGRITY_FRAGMENT = /#(sha256-[A-Za-z0-9_+/=-]+)$/;
+/** A failed integrity/tamper check — always terminal, never best-effort. A
+ *  distinct type so a caller doing best-effort network handling (e.g. the
+ *  bundle extractor warning-and-skipping on a fetch blip) can still let a
+ *  tamper error propagate rather than swallow it. */
+export class IntegrityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IntegrityError";
+    }
+}
 /** Split a trailing integrity fragment off a ref/URL. Returns the bare ref in
  *  `base` (safe to build fetch URLs and cache paths from) and the fragment in
  *  `integrity` (e.g. `sha256-<base64url>`), or `undefined` when absent. */
@@ -55,12 +65,12 @@ export async function verifyIntegrity(bytes, integrity, describe) {
     const algorithm = dash > 0 ? integrity.slice(0, dash) : "";
     const expected = dash > 0 ? integrity.slice(dash + 1) : "";
     if (algorithm !== "sha256") {
-        throw new Error(`Unsupported integrity algorithm '${algorithm || integrity}' for ${describe}. ` +
+        throw new IntegrityError(`Unsupported integrity algorithm '${algorithm || integrity}' for ${describe}. ` +
             `Only sha256 is supported (sha256-<base64url>).`);
     }
     const actual = await sha256Base64Url(bytes);
     if (actual !== normalizeDigest(expected)) {
-        throw new Error(`Integrity check failed for ${describe}: expected sha256-${normalizeDigest(expected)}, ` +
+        throw new IntegrityError(`Integrity check failed for ${describe}: expected sha256-${normalizeDigest(expected)}, ` +
             `got sha256-${actual}. The fetched bytes do not match the recorded hash — ` +
             `the module may have been tampered with or republished.`);
     }

package/dist/sources/module-ref.d.ts

@@ -7,8 +7,12 @@ export interface ParsedModuleRef {
     integrity?: string;
 }
 /** True when `url` has the bare registry-ref shape `namespace/name@version`
- *  (no scheme, no leading `/` or `.`, contains both `@` and `/`). The integrity
- *  fragment, if any, does not affect the classification. */
+ *  (no scheme of any kind, no leading `/` or `.`, contains both `@` and `/`).
+ *  The integrity fragment, if any, does not affect the classification.
+ *
+ *  A registry ref never carries a `scheme://` — that guard is what keeps an
+ *  `oci://…@ver` (or future `s3://…`) ref from being misrouted here, so a
+ *  scheme-owning transport claims it instead. */
 export declare function isRegistryRef(url: string): boolean;
 /** Canonical parser for `namespace/name@version[#sha256-...]` refs. The single
  *  source of truth shared by the registry source, the kernel manifest cache,

package/dist/sources/module-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-ref.d.ts","sourceRoot":"","sources":["../../src/sources/module-ref.ts"],"names":[],"mappings":"AAEA;;yDAEyD;AACzD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;4DAE4D;AAC5D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAYlD;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAgB3D"}
+{"version":3,"file":"module-ref.d.ts","sourceRoot":"","sources":["../../src/sources/module-ref.ts"],"names":[],"mappings":"AAEA;;yDAEyD;AACzD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASlD;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAgB3D"}

package/dist/sources/module-ref.js

@@ -1,15 +1,16 @@
 import { splitIntegrity } from "./integrity.js";
 /** True when `url` has the bare registry-ref shape `namespace/name@version`
- *  (no scheme, no leading `/` or `.`, contains both `@` and `/`). The integrity
- *  fragment, if any, does not affect the classification. */
+ *  (no scheme of any kind, no leading `/` or `.`, contains both `@` and `/`).
+ *  The integrity fragment, if any, does not affect the classification.
+ *
+ *  A registry ref never carries a `scheme://` — that guard is what keeps an
+ *  `oci://…@ver` (or future `s3://…`) ref from being misrouted here, so a
+ *  scheme-owning transport claims it instead. */
 export function isRegistryRef(url) {
     const { base } = splitIntegrity(url);
-    return (!base.startsWith("http://") &&
-        !base.startsWith("https://") &&
+    return (!base.includes("://") &&
         !base.startsWith("/") &&
         !base.startsWith(".") &&
-        !base.startsWith("file://") &&
-        !base.startsWith("memory://") &&
         base.includes("@") &&
         base.includes("/"));
 }

package/dist/validate-kind-descriptions.d.ts

@@ -0,0 +1,20 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * Warns when a library exports a kind (via `exports.kinds`) whose local
+ * `Telo.Definition` carries no `metadata.description`.
+ *
+ * The description is the primary human text the federated-discovery hub embeds
+ * for semantic search (`search_resources`), so an exported kind without one is
+ * undiscoverable by meaning. A warning (not an error) so the stdlib backfill is
+ * incremental and CI isn't blocked mid-migration.
+ *
+ * Scope: only kinds a library *exports* and *defines locally* are checked.
+ * Re-exported kinds (`exports.kinds: [Alias.Kind]`) belong to their owning
+ * module and are skipped; an exported name that isn't a local Telo.Definition
+ * (e.g. a Telo.Abstract) is skipped too. The check keys off the root library's
+ * own module doc, which is only present when that library is analyzed directly
+ * — so importing an under-described library never leaks warnings to its consumer.
+ */
+export declare function validateKindDescriptions(manifests: ResourceManifest[]): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-kind-descriptions.d.ts.map

package/dist/validate-kind-descriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-kind-descriptions.d.ts","sourceRoot":"","sources":["../src/validate-kind-descriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,EAAE,CA2C5F"}

package/dist/validate-kind-descriptions.js

@@ -0,0 +1,65 @@
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Warns when a library exports a kind (via `exports.kinds`) whose local
+ * `Telo.Definition` carries no `metadata.description`.
+ *
+ * The description is the primary human text the federated-discovery hub embeds
+ * for semantic search (`search_resources`), so an exported kind without one is
+ * undiscoverable by meaning. A warning (not an error) so the stdlib backfill is
+ * incremental and CI isn't blocked mid-migration.
+ *
+ * Scope: only kinds a library *exports* and *defines locally* are checked.
+ * Re-exported kinds (`exports.kinds: [Alias.Kind]`) belong to their owning
+ * module and are skipped; an exported name that isn't a local Telo.Definition
+ * (e.g. a Telo.Abstract) is skipped too. The check keys off the root library's
+ * own module doc, which is only present when that library is analyzed directly
+ * — so importing an under-described library never leaks warnings to its consumer.
+ */
+export function validateKindDescriptions(manifests) {
+    const diagnostics = [];
+    // Local Telo.Definition docs keyed by `<module>/<name>`.
+    const definitions = new Map();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Definition")
+            continue;
+        const name = m.metadata?.name;
+        const mod = m.metadata?.module;
+        if (name && mod)
+            definitions.set(`${mod}/${name}`, m);
+    }
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Library")
+            continue;
+        const moduleName = m.metadata?.name;
+        if (!moduleName)
+            continue;
+        const exportedKinds = m.exports?.kinds;
+        if (!Array.isArray(exportedKinds))
+            continue;
+        for (const entry of exportedKinds) {
+            // Re-export (`Alias.Kind`) — the owning module owns its description.
+            if (typeof entry !== "string" || entry.includes("."))
+                continue;
+            const def = definitions.get(`${moduleName}/${entry}`);
+            if (!def)
+                continue; // not a local Telo.Definition (e.g. an abstract)
+            const description = def.metadata?.description;
+            if (typeof description === "string" && description.trim() !== "")
+                continue;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Warning,
+                code: "KIND_MISSING_DESCRIPTION",
+                source: SOURCE,
+                message: `${moduleName}.${entry}: exported kind has no 'metadata.description'. Add a one-line ` +
+                    `description — it is the primary text indexed for semantic discovery (search_resources).`,
+                data: {
+                    resource: { kind: "Telo.Definition", name: entry },
+                    filePath: def.metadata?.source,
+                    path: "metadata.description",
+                },
+            });
+        }
+    }
+    return diagnostics;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,7 +42,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.10.0"
+    "@telorun/templating": "0.10.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/analyzer.ts

@@ -1,7 +1,7 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
-import { defaultRegistry, isTaggedSentinel } from "@telorun/templating";
+import { defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import { AliasResolver, scopeResolverForModule } from "./alias-resolver.js";
 import { AnalysisRegistry } from "./analysis-registry.js";
 import {
@@ -40,6 +40,7 @@ import {
 import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
+import { validateKindDescriptions } from "./validate-kind-descriptions.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
 import { validateReferenceForms } from "./validate-reference-forms.js";
@@ -236,6 +237,73 @@ function gatherPropertySchemas(schema: Record<string, any>): Array<[string, Reco
   return out;
 }
 
+/**
+ * Generic, role-driven walk over an `x-telo-step-context` step array. Calls
+ * `visit(step, stepPath)` for every step — top-level and nested through the
+ * `x-telo-topology-role` forms (`branch`, `branch-list`, `case-map`). This is
+ * the single definition of how steps nest, shared by `buildStepContextSchema`
+ * (which types `steps.<name>.result`) and `validateStepInvokeReferences` (which
+ * checks invoke refs), so the topology contract lives in one place — adding a
+ * role or nesting form updates both consumers at once. No resource kind is
+ * hardcoded; recursion is driven entirely by the schema annotations.
+ */
+function walkStepArray(
+  steps: unknown[],
+  stepItemSchema: Record<string, any> | undefined,
+  rootSchema: Record<string, any>,
+  basePath: string,
+  visit: (step: Record<string, any>, stepPath: string) => void,
+): void {
+  const dispatchRole = (
+    data: unknown,
+    role: string,
+    itemsSchema: Record<string, any> | undefined,
+    path: string,
+  ): void => {
+    if (role === "branch" && Array.isArray(data)) {
+      walkStepArray(data, stepItemSchema, rootSchema, path, visit);
+    } else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
+      for (const [caseKey, arr] of Object.entries(data as Record<string, unknown>)) {
+        if (Array.isArray(arr)) walkStepArray(arr, stepItemSchema, rootSchema, `${path}.${caseKey}`, visit);
+      }
+    } else if (role === "branch-list" && Array.isArray(data)) {
+      const entrySchema = resolveLocalRef(itemsSchema, rootSchema);
+      if (!entrySchema) return;
+      data.forEach((entry, i) => {
+        if (!entry || typeof entry !== "object") return;
+        for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
+          const subRole = subSchema["x-telo-topology-role"];
+          if (typeof subRole !== "string") continue;
+          dispatchRole(
+            (entry as Record<string, any>)[subKey],
+            subRole,
+            subSchema.items as Record<string, any> | undefined,
+            `${path}[${i}].${subKey}`,
+          );
+        }
+      });
+    }
+  };
+
+  steps.forEach((step, i) => {
+    if (!step || typeof step !== "object") return;
+    const s = step as Record<string, any>;
+    const stepPath = `${basePath}[${i}]`;
+    visit(s, stepPath);
+    if (!stepItemSchema) return;
+    for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
+      const role = propSchema["x-telo-topology-role"];
+      if (typeof role !== "string") continue;
+      dispatchRole(
+        s[propKey],
+        role,
+        propSchema.items as Record<string, any> | undefined,
+        `${stepPath}.${propKey}`,
+      );
+    }
+  });
+}
+
 /**
  * Build a `steps` context schema from `x-telo-step-context` annotation.
  * Walks each step in the manifest array, resolves the invoked resource's outputType,
@@ -290,90 +358,47 @@ function buildStepContextSchema(
 
     const stepProperties: Record<string, any> = {};
 
-    const dispatchRole = (
-      data: unknown,
-      role: string,
-      itemsSchema: Record<string, any> | undefined,
-    ): void => {
-      if (role === "branch" && Array.isArray(data)) {
-        collectSteps(data);
-      } else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
-        for (const arr of Object.values(data as Record<string, unknown>)) {
-          if (Array.isArray(arr)) collectSteps(arr);
-        }
-      } else if (role === "branch-list" && Array.isArray(data)) {
-        const entrySchema = resolveLocalRef(itemsSchema, defSchema);
-        if (!entrySchema) return;
-        for (const entry of data) {
-          if (!entry || typeof entry !== "object") continue;
-          for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
-            const subRole = subSchema["x-telo-topology-role"];
-            if (typeof subRole !== "string") continue;
-            dispatchRole(
-              (entry as Record<string, any>)[subKey],
-              subRole,
-              subSchema.items as Record<string, any> | undefined,
-            );
-          }
+    walkStepArray(steps, stepItemSchema, defSchema, fieldName, (s) => {
+      const name = s.name;
+      const invoke = s[invokeField] as Record<string, any> | undefined;
+      // Only invoke steps register a `steps.<name>.result` entry — control-flow
+      // wrappers (try/if/while/switch/throw) don't produce a result and must
+      // not shadow real entries with a permissive `additionalProperties: true`,
+      // or unknown step references slip through chain validation.
+      if (typeof name !== "string" || !invoke || typeof invoke !== "object") return;
+      let outputSchema: Record<string, any> | undefined;
+      const invokedKind = invoke.kind as string | undefined;
+      const invokedName = invoke.name as string | undefined;
+      if (invokedName) {
+        const invokedManifest = allManifests.find(
+          (m) =>
+            (m.metadata as any)?.name === invokedName &&
+            (!invokedKind || m.kind === invokedKind),
+        ) as Record<string, any> | undefined;
+        if (invokedManifest) {
+          outputSchema = resolveTypeFieldToSchema(invokedManifest[outputTypeField], allManifests);
         }
+      } else {
+        outputSchema = resolveTypeFieldToSchema(invoke[outputTypeField], allManifests);
       }
-    };
-
-    function collectSteps(items: unknown[]): void {
-      for (const step of items) {
-        if (!step || typeof step !== "object") continue;
-        const s = step as Record<string, any>;
-        const name = s.name;
-        const invoke = s[invokeField] as Record<string, any> | undefined;
-        // Only invoke steps register a `steps.<name>.result` entry — control-flow
-        // wrappers (try/if/while/switch/throw) don't produce a result and must
-        // not shadow real entries with a permissive `additionalProperties: true`,
-        // or unknown step references slip through chain validation.
-        if (typeof name === "string" && invoke && typeof invoke === "object") {
-          let outputSchema: Record<string, any> | undefined;
-          const invokedKind = invoke.kind as string | undefined;
-          const invokedName = invoke.name as string | undefined;
-          if (invokedName) {
-            const invokedManifest = allManifests.find(
-              (m) =>
-                (m.metadata as any)?.name === invokedName &&
-                (!invokedKind || m.kind === invokedKind),
-            ) as Record<string, any> | undefined;
-            if (invokedManifest) {
-              outputSchema = resolveTypeFieldToSchema(invokedManifest[outputTypeField], allManifests);
-            }
-          } else {
-            outputSchema = resolveTypeFieldToSchema(invoke[outputTypeField], allManifests);
-          }
-          // Fallback: pull outputType from the kind's Telo.Definition. The
-          // resource manifest typically doesn't carry outputType; the def does.
-          if (!outputSchema && invokedKind) {
-            outputSchema = lookupDefinitionTypeField(
-              invokedKind,
-              outputTypeField,
-              defs,
-              aliases,
-              allManifests,
-            );
-          }
-          stepProperties[name] = {
-            type: "object",
-            properties: {
-              result: outputSchema ?? { type: "object", additionalProperties: true },
-            },
-          };
-        }
-        if (stepItemSchema) {
-          for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
-            const role = propSchema["x-telo-topology-role"];
-            if (typeof role !== "string") continue;
-            dispatchRole(s[propKey], role, propSchema.items as Record<string, any> | undefined);
-          }
-        }
+      // Fallback: pull outputType from the kind's Telo.Definition. The
+      // resource manifest typically doesn't carry outputType; the def does.
+      if (!outputSchema && invokedKind) {
+        outputSchema = lookupDefinitionTypeField(
+          invokedKind,
+          outputTypeField,
+          defs,
+          aliases,
+          allManifests,
+        );
       }
-    }
-
-    collectSteps(steps);
+      stepProperties[name] = {
+        type: "object",
+        properties: {
+          result: outputSchema ?? { type: "object", additionalProperties: true },
+        },
+      };
+    });
 
     if (Object.keys(stepProperties).length > 0) {
       return {
@@ -386,6 +411,192 @@ function buildStepContextSchema(
   return undefined;
 }
 
+/**
+ * Capabilities whose instances structurally expose no `invoke`/`run` method, so
+ * a step `invoke` of one always fails at runtime with ERR_RESOURCE_NOT_INVOKABLE
+ * (kernel dispatch checks method presence, not capability — evaluation-context.ts).
+ * `Telo.Service` is intentionally absent: some services are invocable (a function
+ * handler dispatched directly, e.g. `Lambda.Function`), so it can't be rejected
+ * statically without false positives. This is the sound subset of the runtime rule.
+ */
+const NON_INVOKABLE_CAPABILITIES = new Set([
+  "Telo.Provider",
+  "Telo.Mount",
+  "Telo.Type",
+  "Telo.Template",
+]);
+
+/**
+ * Validate `x-telo-step-context` step `invoke` references (e.g. `Run.Sequence`
+ * steps).
+ *
+ * The reference field map deliberately does NOT descend into step `invoke`
+ * slots — they sit behind a local `$ref` to the shared step definition, and
+ * turning the descent on would make Phase 5 inject live instances there,
+ * breaking the invoke dispatch path (see `reference-field-map.ts`). A
+ * consequence is that `validateReferences` never sees these slots, so a bad
+ * step invoke passes `telo check` and only fails at runtime. This pass covers
+ * exactly those slots, in two dimensions:
+ *   - Existence: an `invoke: !ref <name>` that names a missing instance — or a
+ *     *kind* instead of an exported instance (`!ref Stream.Of`) — is a still-a-
+ *     sentinel after Phase 2.5 resolution → `UNRESOLVED_REFERENCE` (runtime
+ *     `ERR_RESOURCE_NOT_FOUND`).
+ *   - Invokability: a resolved instance whose capability structurally has no
+ *     invoke/run method (`NON_INVOKABLE_CAPABILITIES`) → `REFERENCE_KIND_MISMATCH`
+ *     (runtime `ERR_RESOURCE_NOT_INVOKABLE`).
+ *
+ * Generic and topology-driven — it walks steps via the same `x-telo-step-context`
+ * / `x-telo-topology-role` annotations `buildStepContextSchema` uses (through the
+ * shared `walkStepArray`), so nested branches (then/else/do/catch/cases) are
+ * covered and no `Run.Sequence` field name is hardcoded. The cross-module
+ * partial-analysis guard mirrors `validateReferences`, so a reference into an
+ * unloaded import is skipped rather than false-flagged.
+ */
+function validateStepInvokeReferences(
+  allManifests: Record<string, any>[],
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  // Local instance names + loaded-module set — same construction as
+  // validateReferences, so the cross-module guard behaves identically.
+  const localNames = new Set<string>();
+  const loadedModules = new Set<string>();
+
+  // Also collect names of resources nested inside a manifest tree — notably
+  // `with:`-scoped resources (an `x-telo-scope` region the field map does not
+  // extract to a top-level manifest). A step can invoke one by bare name, so
+  // omitting them would false-flag a valid `!ref`. Conservative: any nested
+  // object carrying both a `kind` and a `metadata.name` is a resource
+  // definition; scope visibility is left to the runtime.
+  const collectNestedNames = (value: unknown): void => {
+    if (!value || typeof value !== "object" || isTaggedSentinel(value)) return;
+    if (Array.isArray(value)) {
+      for (const item of value) collectNestedNames(item);
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    const name = (obj.metadata as { name?: unknown } | undefined)?.name;
+    if (typeof obj.kind === "string" && typeof name === "string") localNames.add(name);
+    for (const v of Object.values(obj)) collectNestedNames(v);
+  };
+
+  for (const r of allManifests) {
+    if (r.kind === "Telo.Import") {
+      const m = (r.metadata as { resolvedModuleName?: unknown } | undefined)?.resolvedModuleName;
+      if (typeof m === "string") loadedModules.add(m);
+      continue;
+    }
+    const meta = r.metadata as { name?: unknown; module?: unknown; forwardedExport?: unknown };
+    if (typeof meta?.name !== "string" || REF_VALIDATION_SKIP_KINDS.has(r.kind)) continue;
+    if (meta.forwardedExport === true) {
+      if (typeof meta.module === "string") loadedModules.add(meta.module);
+      continue;
+    }
+    localNames.add(meta.name);
+    collectNestedNames(r);
+  }
+
+  const validateInvoke = (
+    value: unknown,
+    resource: { kind: string; name: string },
+    filePath: string | undefined,
+    path: string,
+  ): void => {
+    if (isRefSentinel(value)) {
+      // An unresolved `!ref` is a miss: a real instance would have resolved to
+      // `{kind, name}` in Phase 2.5.
+      const refName = value.source;
+      const dot = refName.indexOf(".");
+      const aliasPrefix = dot > 0 ? refName.slice(0, dot) : undefined;
+
+      if (aliasPrefix && aliasPrefix !== "Self" && aliases.hasAlias(aliasPrefix)) {
+        const module = aliases.moduleForAlias(aliasPrefix);
+        // Partial single-file analysis (import not loaded) — skip to avoid a false miss.
+        if (module && !loadedModules.has(module)) return;
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "UNRESOLVED_REFERENCE",
+          source: SOURCE,
+          message: `${resource.kind}/${resource.name}: step invoke at '${path}' → '${refName}' is not an exported instance of module '${module ?? aliasPrefix}' (reference a declared instance, not a kind)`,
+          data: { resource, filePath, path },
+        });
+        return;
+      }
+
+      const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
+      if (localNames.has(localName)) return;
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "UNRESOLVED_REFERENCE",
+        source: SOURCE,
+        message: `${resource.kind}/${resource.name}: step invoke at '${path}' → resource '${localName}' not found`,
+        data: { resource, filePath, path },
+      });
+      return;
+    }
+
+    // Resolved `{kind, name}` (or an inline `{kind, …}` definition) — the
+    // instance exists. Mirror the kernel's ERR_RESOURCE_NOT_INVOKABLE, which
+    // fires when the instance has neither an `invoke` nor a `run` method
+    // (evaluation-context.ts). That is a per-instance property, not a pure
+    // capability, so only capabilities that STRUCTURALLY expose no such method
+    // are rejected statically — Service is intentionally excluded, since some
+    // services are invocable (e.g. a function handler dispatched directly).
+    if (!value || typeof value !== "object" || Array.isArray(value)) return;
+    const kind = (value as Record<string, unknown>).kind;
+    if (typeof kind !== "string") return;
+    const capability = defs.resolve(aliases.resolveKind(kind) ?? kind)?.capability;
+    if (typeof capability === "string" && NON_INVOKABLE_CAPABILITIES.has(capability)) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "REFERENCE_KIND_MISMATCH",
+        source: SOURCE,
+        message: `${resource.kind}/${resource.name}: step invoke at '${path}' → '${kind}' is a ${capability} and cannot be invoked in a step — it has no invoke or run method (runtime ERR_RESOURCE_NOT_INVOKABLE)`,
+        data: { resource, filePath, path },
+      });
+    }
+  };
+
+  for (const m of allManifests) {
+    const meta = m.metadata as { name?: unknown; source?: unknown; forwardedExport?: unknown };
+    if (
+      typeof meta?.name !== "string" ||
+      REF_VALIDATION_SKIP_KINDS.has(m.kind) ||
+      meta.forwardedExport === true
+    )
+      continue;
+    const def = defs.resolve(aliases.resolveKind(m.kind) ?? m.kind);
+    const defSchema = def?.schema as Record<string, any> | undefined;
+    if (!defSchema?.properties) continue;
+    const resource = { kind: m.kind, name: meta.name };
+    const filePath = typeof meta.source === "string" ? meta.source : undefined;
+
+    for (const [fieldName, fieldSchema] of Object.entries(
+      defSchema.properties as Record<string, any>,
+    )) {
+      const stepCtx = fieldSchema["x-telo-step-context"] as Record<string, string> | undefined;
+      const invokeField = stepCtx?.invoke;
+      if (!invokeField) continue;
+      const steps = m[fieldName];
+      if (!Array.isArray(steps)) continue;
+      const stepItemSchema = resolveLocalRef(
+        fieldSchema.items as Record<string, any> | undefined,
+        defSchema,
+      );
+
+      walkStepArray(steps, stepItemSchema, defSchema, fieldName, (s, stepPath) => {
+        const invoke = s[invokeField];
+        if (invoke === undefined || invoke === null) return;
+        validateInvoke(invoke, resource, filePath, `${stepPath}.${invokeField}`);
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
 /**
  * Collect every field annotated with `x-telo-error-context` anywhere in a
  * definition schema (resolving local `$ref`s into `$defs`, cycle-safe), mapping
@@ -1409,12 +1620,20 @@ export class StaticAnalyzer {
       ...validateReferences(allManifests, { aliases, definitions: defs, aliasesByModule }),
     );
 
+    // Validate step `invoke` references — the slots the reference field map
+    // deliberately skips (behind the step `$ref`), so a missing instance or a
+    // kind-instead-of-instance ref there is caught statically, not at runtime.
+    diagnostics.push(...validateStepInvokeReferences(allManifests, defs, aliases));
+
     // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
     diagnostics.push(...validateExtends(allManifests, defs, aliases));
 
     // Validate provider coherence rules for `provide:` template-target definitions.
     diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
 
+    // Warn about exported kinds lacking a metadata.description (semantic-search input).
+    diagnostics.push(...validateKindDescriptions(allManifests));
+
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(
       ...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv, aliasesByModule, rootModules),

package/src/index.ts

@@ -59,6 +59,7 @@ export {
   verifyIntegrity,
   verifiedFetch,
   sha256Base64Url,
+  IntegrityError,
 } from "./sources/integrity.js";
 export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export type { ParsedModuleRef } from "./sources/module-ref.js";

package/src/sources/integrity.ts

@@ -11,6 +11,17 @@
  *  only algorithm accepted today; the prefix leaves room to migrate. */
 const INTEGRITY_FRAGMENT = /#(sha256-[A-Za-z0-9_+/=-]+)$/;
 
+/** A failed integrity/tamper check — always terminal, never best-effort. A
+ *  distinct type so a caller doing best-effort network handling (e.g. the
+ *  bundle extractor warning-and-skipping on a fetch blip) can still let a
+ *  tamper error propagate rather than swallow it. */
+export class IntegrityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IntegrityError";
+  }
+}
+
 /** Split a trailing integrity fragment off a ref/URL. Returns the bare ref in
  *  `base` (safe to build fetch URLs and cache paths from) and the fragment in
  *  `integrity` (e.g. `sha256-<base64url>`), or `undefined` when absent. */
@@ -64,14 +75,14 @@ export async function verifyIntegrity(
   const algorithm = dash > 0 ? integrity.slice(0, dash) : "";
   const expected = dash > 0 ? integrity.slice(dash + 1) : "";
   if (algorithm !== "sha256") {
-    throw new Error(
+    throw new IntegrityError(
       `Unsupported integrity algorithm '${algorithm || integrity}' for ${describe}. ` +
         `Only sha256 is supported (sha256-<base64url>).`,
     );
   }
   const actual = await sha256Base64Url(bytes);
   if (actual !== normalizeDigest(expected)) {
-    throw new Error(
+    throw new IntegrityError(
       `Integrity check failed for ${describe}: expected sha256-${normalizeDigest(expected)}, ` +
         `got sha256-${actual}. The fetched bytes do not match the recorded hash — ` +
         `the module may have been tampered with or republished.`,

package/src/sources/module-ref.ts

@@ -10,17 +10,18 @@ export interface ParsedModuleRef {
 }
 
 /** True when `url` has the bare registry-ref shape `namespace/name@version`
- *  (no scheme, no leading `/` or `.`, contains both `@` and `/`). The integrity
- *  fragment, if any, does not affect the classification. */
+ *  (no scheme of any kind, no leading `/` or `.`, contains both `@` and `/`).
+ *  The integrity fragment, if any, does not affect the classification.
+ *
+ *  A registry ref never carries a `scheme://` — that guard is what keeps an
+ *  `oci://…@ver` (or future `s3://…`) ref from being misrouted here, so a
+ *  scheme-owning transport claims it instead. */
 export function isRegistryRef(url: string): boolean {
   const { base } = splitIntegrity(url);
   return (
-    !base.startsWith("http://") &&
-    !base.startsWith("https://") &&
+    !base.includes("://") &&
     !base.startsWith("/") &&
     !base.startsWith(".") &&
-    !base.startsWith("file://") &&
-    !base.startsWith("memory://") &&
     base.includes("@") &&
     base.includes("/")
   );

package/src/validate-kind-descriptions.ts

@@ -0,0 +1,65 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Warns when a library exports a kind (via `exports.kinds`) whose local
+ * `Telo.Definition` carries no `metadata.description`.
+ *
+ * The description is the primary human text the federated-discovery hub embeds
+ * for semantic search (`search_resources`), so an exported kind without one is
+ * undiscoverable by meaning. A warning (not an error) so the stdlib backfill is
+ * incremental and CI isn't blocked mid-migration.
+ *
+ * Scope: only kinds a library *exports* and *defines locally* are checked.
+ * Re-exported kinds (`exports.kinds: [Alias.Kind]`) belong to their owning
+ * module and are skipped; an exported name that isn't a local Telo.Definition
+ * (e.g. a Telo.Abstract) is skipped too. The check keys off the root library's
+ * own module doc, which is only present when that library is analyzed directly
+ * — so importing an under-described library never leaks warnings to its consumer.
+ */
+export function validateKindDescriptions(manifests: ResourceManifest[]): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  // Local Telo.Definition docs keyed by `<module>/<name>`.
+  const definitions = new Map<string, ResourceManifest>();
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Definition") continue;
+    const name = m.metadata?.name as string | undefined;
+    const mod = (m.metadata as { module?: string } | undefined)?.module;
+    if (name && mod) definitions.set(`${mod}/${name}`, m);
+  }
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Library") continue;
+    const moduleName = m.metadata?.name as string | undefined;
+    if (!moduleName) continue;
+    const exportedKinds = (m as { exports?: { kinds?: unknown } }).exports?.kinds;
+    if (!Array.isArray(exportedKinds)) continue;
+
+    for (const entry of exportedKinds) {
+      // Re-export (`Alias.Kind`) — the owning module owns its description.
+      if (typeof entry !== "string" || entry.includes(".")) continue;
+      const def = definitions.get(`${moduleName}/${entry}`);
+      if (!def) continue; // not a local Telo.Definition (e.g. an abstract)
+      const description = (def.metadata as { description?: unknown } | undefined)?.description;
+      if (typeof description === "string" && description.trim() !== "") continue;
+      diagnostics.push({
+        severity: DiagnosticSeverity.Warning,
+        code: "KIND_MISSING_DESCRIPTION",
+        source: SOURCE,
+        message:
+          `${moduleName}.${entry}: exported kind has no 'metadata.description'. Add a one-line ` +
+          `description — it is the primary text indexed for semantic discovery (search_resources).`,
+        data: {
+          resource: { kind: "Telo.Definition", name: entry },
+          filePath: (def.metadata as { source?: string } | undefined)?.source,
+          path: "metadata.description",
+        },
+      });
+    }
+  }
+
+  return diagnostics;
+}