@telorun/analyzer 0.31.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/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA2hB/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAwiB/C,CAAC"}

package/dist/builtins.js

@@ -225,6 +225,7 @@ export const KERNEL_BUILTINS = [
                     additionalProperties: true,
                 },
                 source: { type: "string" },
+                integrity: { type: "string" },
                 variables: { type: "object" },
                 secrets: { type: "object" },
                 runtime: {
@@ -359,6 +360,11 @@ export const KERNEL_BUILTINS = [
                     type: "array",
                     items: { type: "string" },
                 },
+                // Integrity hash of the decompressed payload tar (`module.tar.gz`,
+                // telo.yaml excluded), written by `telo publish`. Pinned transitively
+                // by the importer's `#sha256-...` hash over this telo.yaml; verified at
+                // extract time. See plans/federated-registries.md.
+                filesIntegrity: { type: "string" },
                 // Inline imports — name-keyed map sugar for separate `Telo.Import`
                 // documents. The key is the PascalCase alias (the import's
                 // `metadata.name`). Each value is either a bare source string
@@ -376,6 +382,7 @@ export const KERNEL_BUILTINS = [
                                 required: ["source"],
                                 properties: {
                                     source: { type: "string" },
+                                    integrity: { type: "string" },
                                     variables: { type: "object" },
                                     secrets: { type: "object" },
                                     runtime: {
@@ -490,6 +497,11 @@ export const KERNEL_BUILTINS = [
                     type: "array",
                     items: { type: "string" },
                 },
+                // Integrity hash of the decompressed payload tar (`module.tar.gz`,
+                // telo.yaml excluded), written by `telo publish`. Pinned transitively
+                // by the importer's `#sha256-...` hash over this telo.yaml; verified at
+                // extract time. See plans/federated-registries.md.
+                filesIntegrity: { type: "string" },
                 // Inline imports — same name-keyed map sugar as Telo.Application; the
                 // loader desugars each entry into a synthetic Telo.Import. See the
                 // Application schema above and analyzer/nodejs/src/inline-imports.ts.
@@ -503,6 +515,7 @@ export const KERNEL_BUILTINS = [
                                 required: ["source"],
                                 properties: {
                                     source: { type: "string" },
+                                    integrity: { type: "string" },
                                     variables: { type: "object" },
                                     secrets: { type: "object" },
                                     runtime: {

package/dist/index.d.ts

@@ -21,6 +21,9 @@ 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, 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";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type { AnalysisDiagnostic, AnalysisOptions, LoaderInitOptions, LoadOptions, ManifestSource, Position, PositionIndex, Range } from "./types.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,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,5 +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, 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/inline-imports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inline-imports.d.ts","sourceRoot":"","sources":["../src/inline-imports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D;;6CAE6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,gBAAgB,EAChC,cAAc,EAAE,gBAAgB,GAAG,SAAS,GAC3C,eAAe,EAAE,CA0BnB;AAED;;;;;;;iFAOiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAmB9D"}
+{"version":3,"file":"inline-imports.d.ts","sourceRoot":"","sources":["../src/inline-imports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D;;6CAE6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,gBAAgB,EAChC,cAAc,EAAE,gBAAgB,GAAG,SAAS,GAC3C,eAAe,EAAE,CA+BnB;AAED;;;;;;;iFAOiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAmB9D"}

package/dist/inline-imports.js

@@ -1,3 +1,4 @@
+import { foldIntegrity } from "./sources/integrity.js";
 import { isModuleKind } from "./module-kinds.js";
 /**
  * Desugar a module document's inline `imports:` map into synthetic
@@ -26,10 +27,14 @@ export function inlineImportManifests(moduleManifest, modulePosition) {
                 : undefined;
         if (!entry || typeof entry.source !== "string")
             continue;
+        // The object form carries integrity as a sibling `integrity:` field; fold it
+        // into the source string as a `#sha256-...` fragment so every downstream
+        // consumer sees a single representation (the scalar form already inlines it).
+        const source = foldIntegrity(entry.source, entry.integrity);
         const manifest = {
             kind: "Telo.Import",
             metadata: { name: alias },
-            source: entry.source,
+            source,
             ...(entry.variables !== undefined ? { variables: entry.variables } : {}),
             ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
             ...(entry.runtime !== undefined ? { runtime: entry.runtime } : {}),

package/dist/sources/http-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-source.d.ts","sourceRoot":"","sources":["../../src/sources/http-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7E,qBAAa,UAAW,YAAW,cAAc;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAWlE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;CAIxD"}
+{"version":3,"file":"http-source.d.ts","sourceRoot":"","sources":["../../src/sources/http-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7E,qBAAa,UAAW,YAAW,cAAc;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAOlE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;CAIxD"}

package/dist/sources/http-source.js

@@ -1,15 +1,14 @@
 import { DEFAULT_MANIFEST_FILENAME } from "../types.js";
+import { splitIntegrity, verifiedFetch } from "./integrity.js";
 export class HttpSource {
     supports(url) {
         return url.startsWith("http://") || url.startsWith("https://");
     }
     async read(url) {
-        const fetchUrl = url.includes(".yaml") ? url : `${url}/${DEFAULT_MANIFEST_FILENAME}`;
-        const response = await fetch(fetchUrl);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch manifest from ${fetchUrl}: ${response.status} ${response.statusText}`);
-        }
-        return { text: await response.text(), source: fetchUrl };
+        const { base, integrity } = splitIntegrity(url);
+        const fetchUrl = base.includes(".yaml") ? base : `${base}/${DEFAULT_MANIFEST_FILENAME}`;
+        const { text } = await verifiedFetch(fetchUrl, integrity, fetchUrl);
+        return { text, source: fetchUrl };
     }
     resolveRelative(base, relative) {
         const baseDir = base.endsWith("/") ? base : base.slice(0, base.lastIndexOf("/") + 1);

package/dist/sources/integrity.d.ts

@@ -0,0 +1,42 @@
+/** Inline module integrity — the `#sha256-<base64url>` fragment carried on a
+ *  remote import ref. Browser-safe: uses Web Crypto (`crypto.subtle`) and
+ *  `btoa`, both globals in Node and the browser. No Node built-ins.
+ *
+ *  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. */
+export declare function splitIntegrity(ref: string): {
+    base: string;
+    integrity?: string;
+};
+/** Attach an integrity hash to a ref as a `#<alg>-...` fragment. No-op when the
+ *  hash is absent/non-string or the ref already carries a fragment (an
+ *  author-authored pin is never overwritten). Inverse of `splitIntegrity`;
+ *  used to fold the object form's `integrity:` sibling into the source string. */
+export declare function foldIntegrity(source: string, integrity: unknown): string;
+/** SHA-256 of `bytes` as unpadded base64url — the canonical inline-hash form. */
+export declare function sha256Base64Url(bytes: Uint8Array): Promise<string>;
+/** Hash `bytes` and compare against `integrity` (`<alg>-<digest>`). Throws a
+ *  terminal error on mismatch or an unsupported algorithm. `describe` names the
+ *  artifact in the error (e.g. the module ref) so the failure is actionable. */
+export declare function verifyIntegrity(bytes: Uint8Array, integrity: string, describe: string): Promise<void>;
+/** The single verified network read for remote manifests: fetch `fetchUrl`,
+ *  verify the raw bytes against `integrity` (when pinned), and return both the
+ *  bytes and the decoded text. The one choke point every network `ManifestSource`
+ *  routes through, so verification cannot drift between them. `describe` names
+ *  the artifact in error messages. */
+export declare function verifiedFetch(fetchUrl: string, integrity: string | undefined, describe: string): Promise<{
+    bytes: Uint8Array;
+    text: string;
+}>;
+//# sourceMappingURL=integrity.d.ts.map

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

@@ -0,0 +1 @@
+{"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"}