@telorun/analyzer 0.46.0 → 0.48.0

package/dist/resolve-ref-sentinels.js

@@ -1,4 +1,5 @@
 import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import { isScopeEntry, resolveFieldEntries, } from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 /**
  * Rewrites every `!ref <name>` sentinel in each non-system resource's value tree
@@ -41,7 +42,11 @@ export function resolveRefSentinels(resources, aliases, aliasesByModule,
 // walked as sources). The kernel passes the analyzer-flattened set here so the runtime
 // pass — which loads the entry module only — can still resolve `!ref Alias.name` against
 // imported libraries' exported instances.
-crossModuleTargets = []) {
+crossModuleTargets = [], 
+/** Supplies each kind's `x-telo-scope` slots. Without it a scoped name cannot be
+ *  told from a module-level one, and a shadowed `!ref` resolves to the resource
+ *  it shadows — so both call sites pass it. */
+defs) {
     const moduleOf = (r) => r.metadata?.module;
     // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
     // cross-module resolution targets only — never walked as local ref sources here.
@@ -96,11 +101,50 @@ crossModuleTargets = []) {
         }
         return undefined;
     };
+    /** Names a resource declares in its own execution scopes, read from the kind's
+     *  `x-telo-scope` slots — the analyzer's single definition of "scope", shared
+     *  with `manifest-visitor`. Inferring it structurally instead (any array of
+     *  named inline manifests) would give scope-local shadowing to the first kind
+     *  that happens to carry such an array without asking for it, and this pass is
+     *  shared with the kernel, so the guess would be baked into the runtime tree
+     *  rather than merely reported. */
+    const declaredInScopes = (resource) => {
+        const fieldMap = defs?.getFieldMapForKind(resource.kind, aliases);
+        if (!fieldMap)
+            return undefined;
+        let declared;
+        for (const [fieldPath, entry] of fieldMap) {
+            if (!isScopeEntry(entry))
+                continue;
+            for (const { value } of resolveFieldEntries(resource, fieldPath)) {
+                for (const element of Array.isArray(value) ? value : [value]) {
+                    if (!element || typeof element !== "object" || Array.isArray(element))
+                        continue;
+                    const manifest = element;
+                    const name = manifest.metadata?.name;
+                    if (typeof manifest.kind === "string" && typeof name === "string") {
+                        (declared ??= new Map()).set(name, manifest);
+                    }
+                }
+            }
+        }
+        return declared;
+    };
     // Resolve every `!ref` sentinel in the tree; leave opaque tagged / precompiled
     // nodes (e.g. `!cel`) untouched and don't descend into them.
-    const walk = (value) => {
+    //
+    // `scoped` carries the names the enclosing resource declares in its `x-telo-scope`
+    // slots, and they SHADOW the module-level ones — the order the runtime resolves
+    // in. Baking the module-level kind into a shadowed reference would label traces
+    // and `getRefIdentity` with a resource that never runs.
+    const walk = (value, scoped) => {
         if (isRefSentinel(value)) {
-            return resolveTarget(value.source) ?? value;
+            const source = value.source;
+            const bare = source.indexOf(".") === -1;
+            const shadow = bare ? scoped?.get(source) : undefined;
+            if (shadow)
+                return { kind: shadow.kind, name: source };
+            return resolveTarget(source) ?? value;
         }
         if (value === null || typeof value !== "object")
             return value;
@@ -110,12 +154,19 @@ crossModuleTargets = []) {
             return value;
         if (Array.isArray(value)) {
             for (let i = 0; i < value.length; i++)
-                value[i] = walk(value[i]);
+                value[i] = walk(value[i], scoped);
             return value;
         }
         const obj = value;
+        // A nested inline resource may declare scopes of its own (a `Run.Sequence`
+        // inside another sequence's `with:`). Collected before descending, so the
+        // declarations are visible to every region of the resource that declares
+        // them — a sequence's `with:` names resolve in its `targets:` and `steps:`
+        // alike, not only inside `with:` itself.
+        const declared = typeof obj.kind === "string" ? declaredInScopes(obj) : undefined;
+        const inner = declared ? new Map([...(scoped ?? new Map()), ...declared]) : scoped;
         for (const key of Object.keys(obj))
-            obj[key] = walk(obj[key]);
+            obj[key] = walk(obj[key], inner);
         return value;
     };
     for (const r of resources) {

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA0CjC;AAuFD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAgHrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD;AAUD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,SAAM,GAAG,MAAM,EAAE,CAqBxF"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA0CjC;AAuFD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAmIrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD;AAUD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,SAAM,GAAG,MAAM,EAAE,CAqBxF"}

package/dist/validate-cel-context.js

@@ -276,13 +276,29 @@ export function resolveContextAnnotations(schema, manifestItem, opts) {
             typeof ref.kind === "string" &&
             typeof ref.name === "string" &&
             subpath) {
+            const segments = subpath.split("/");
             const refManifest = allManifests.find((m) => m.kind === ref.kind && m.metadata?.name === ref.name);
             if (refManifest) {
-                const resolved = resolveTypeFieldToSchema(navigatePath(refManifest, subpath.split("/")), allManifests);
+                const resolved = resolveTypeFieldToSchema(navigatePath(refManifest, segments), allManifests);
                 if (resolved && typeof resolved === "object") {
                     return resolved;
                 }
             }
+            // The instance declares nothing, so fall back to its KIND's declaration —
+            // the same layering `buildStepContextSchema` applies to `steps.<name>.result`,
+            // so a kind with one fixed output shape (declared once on its Telo.Definition)
+            // types the context, while a kind that exposes the field for per-instance
+            // narrowing keeps winning above.
+            if (defs) {
+                const canonical = aliases?.resolveKind(ref.kind) ?? ref.kind;
+                const def = defs.resolve(canonical);
+                if (def) {
+                    const resolved = resolveTypeFieldToSchema(navigatePath(def, segments), allManifests);
+                    if (resolved && typeof resolved === "object") {
+                        return resolved;
+                    }
+                }
+            }
         }
         // Fallback: open schema (no false errors when outputType is not declared)
         return { ...schema, additionalProperties: true };

package/dist/validate-module-artifact.d.ts

@@ -0,0 +1,27 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * Static validation of the module-artifact surface — `kernel/specs/module-artifact.md`.
+ *
+ * Everything here is decidable from the manifest text alone, and every case would
+ * otherwise surface on a *consumer's* machine at controller-resolve time (or, worse,
+ * not at all). That is the whole argument: an author who mistypes a platform axis
+ * gets a platform-neutral candidate, publish emits one layer, and every host
+ * happily loads a binary built for one architecture — silently, forever.
+ *
+ * Two checks. Note that several candidates *sharing* one selector is not among
+ * them: a controller layer holds the entry points of every candidate with that
+ * selector (spec §1), which is what every module with two `js` controllers relies
+ * on.
+ *
+ * 1. **Controller selector qualifiers.** `os` / `arch` / `libc` / `siblings` are
+ *    authored surface. An unknown qualifier is reported rather than ignored, since
+ *    ignoring is what makes a typo invisible; an invalid value is reported here
+ *    instead of throwing from the loader later.
+ * 2. **The published layer index.** The owner doc's JSON Schema covers shape; the
+ *    semantic rules — controller-requires-selector, singletons carry none, no
+ *    duplicate selector, the token grammar (`os: Linux` passes the schema and
+ *    throws at runtime) — live in the parser, so run it.
+ */
+export declare function validateModuleArtifact(manifests: ResourceManifest[]): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-module-artifact.d.ts.map

package/dist/validate-module-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-module-artifact.d.ts","sourceRoot":"","sources":["../src/validate-module-artifact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,EAAE,CAO1F"}

package/dist/validate-module-artifact.js

@@ -0,0 +1,131 @@
+import { parseLayerIndex, LayerIndexError } from "./artifact-layer-index.js";
+import { ArtifactSelectorError, PLATFORM_AXES, selectorFromQualifiers, } from "./artifact-selector.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Static validation of the module-artifact surface — `kernel/specs/module-artifact.md`.
+ *
+ * Everything here is decidable from the manifest text alone, and every case would
+ * otherwise surface on a *consumer's* machine at controller-resolve time (or, worse,
+ * not at all). That is the whole argument: an author who mistypes a platform axis
+ * gets a platform-neutral candidate, publish emits one layer, and every host
+ * happily loads a binary built for one architecture — silently, forever.
+ *
+ * Two checks. Note that several candidates *sharing* one selector is not among
+ * them: a controller layer holds the entry points of every candidate with that
+ * selector (spec §1), which is what every module with two `js` controllers relies
+ * on.
+ *
+ * 1. **Controller selector qualifiers.** `os` / `arch` / `libc` / `siblings` are
+ *    authored surface. An unknown qualifier is reported rather than ignored, since
+ *    ignoring is what makes a typo invisible; an invalid value is reported here
+ *    instead of throwing from the loader later.
+ * 2. **The published layer index.** The owner doc's JSON Schema covers shape; the
+ *    semantic rules — controller-requires-selector, singletons carry none, no
+ *    duplicate selector, the token grammar (`os: Linux` passes the schema and
+ *    throws at runtime) — live in the parser, so run it.
+ */
+export function validateModuleArtifact(manifests) {
+    const out = [];
+    for (const manifest of manifests) {
+        validateLayerIndex(manifest, out);
+        validateControllerSelectors(manifest, out);
+    }
+    return out;
+}
+const KNOWN_QUALIFIERS = new Set(["path", "siblings", ...PLATFORM_AXES]);
+/** `pkg:telo/local/<format>?…` — the bundled-controller delivery mode. Parsed by
+ *  hand rather than with a PURL library: the analyzer must stay browser-safe and
+ *  dependency-light, and the only thing needed here is the qualifier map. */
+function parseBundledPurl(purl) {
+    if (!purl.startsWith("pkg:telo/local/"))
+        return null;
+    const withoutFragment = purl.split("#")[0];
+    const [head, query = ""] = withoutFragment.split("?");
+    const format = head.slice("pkg:telo/local/".length);
+    if (format === "")
+        return null;
+    const qualifiers = {};
+    for (const pair of query.split("&")) {
+        if (pair === "")
+            continue;
+        const eq = pair.indexOf("=");
+        if (eq < 0)
+            continue;
+        qualifiers[decodeURIComponent(pair.slice(0, eq))] = decodeURIComponent(pair.slice(eq + 1));
+    }
+    return { format, qualifiers };
+}
+function validateControllerSelectors(manifest, out) {
+    const controllers = manifest.controllers;
+    if (!Array.isArray(controllers))
+        return;
+    const metadata = manifest.metadata;
+    const name = metadata?.name;
+    const filePath = metadata?.source;
+    const resource = { kind: manifest.kind, name };
+    controllers.forEach((candidate, index) => {
+        if (typeof candidate !== "string")
+            return;
+        const parsed = parseBundledPurl(candidate);
+        if (!parsed)
+            return;
+        const at = `controllers[${index}]`;
+        const unknown = Object.keys(parsed.qualifiers).filter((k) => !KNOWN_QUALIFIERS.has(k));
+        for (const key of unknown) {
+            out.push({
+                severity: DiagnosticSeverity.Error,
+                code: "CONTROLLER_UNKNOWN_QUALIFIER",
+                source: SOURCE,
+                message: `${manifest.kind}/${name ?? "(unnamed)"}: bundled controller qualifier '${key}' is not ` +
+                    `recognized. Known qualifiers: ${[...KNOWN_QUALIFIERS].sort().join(", ")}. An ` +
+                    `unrecognized platform axis is ignored, which would make this candidate ` +
+                    `platform-neutral and offer a single-platform binary to every host.`,
+                data: { resource, filePath, path: `${at}?${key}` },
+            });
+        }
+        // Validate the selector; the value is not otherwise needed here, since
+        // candidates sharing a selector legitimately share a layer.
+        try {
+            selectorFromQualifiers(parsed.format, parsed.qualifiers, candidate);
+        }
+        catch (err) {
+            if (!(err instanceof ArtifactSelectorError))
+                throw err;
+            out.push({
+                severity: DiagnosticSeverity.Error,
+                code: "CONTROLLER_INVALID_SELECTOR",
+                source: SOURCE,
+                message: `${manifest.kind}/${name ?? "(unnamed)"}: ${err.message}`,
+                data: { resource, filePath, path: at },
+            });
+        }
+    });
+}
+function validateLayerIndex(manifest, out) {
+    if (manifest.kind !== "Telo.Application" && manifest.kind !== "Telo.Library")
+        return;
+    const layers = manifest.layers;
+    if (layers === undefined)
+        return;
+    const metadata = manifest.metadata;
+    const name = metadata?.name;
+    try {
+        parseLayerIndex(layers);
+    }
+    catch (err) {
+        if (!(err instanceof LayerIndexError) && !(err instanceof ArtifactSelectorError))
+            throw err;
+        out.push({
+            severity: DiagnosticSeverity.Error,
+            code: "INVALID_LAYER_INDEX",
+            source: SOURCE,
+            message: `${manifest.kind}/${name ?? "(unnamed)"}: ${err.message}`,
+            data: {
+                resource: { kind: manifest.kind, name },
+                filePath: metadata?.source,
+                path: "layers",
+            },
+        });
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAgD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA6dtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAgD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAmetB"}

package/dist/validate-references.js

@@ -254,8 +254,14 @@ export function validateReferences(resources, context) {
                 }
                 // Local reference (bare name or explicit `Self.`-qualified).
                 const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
-                const target = byName.get(localName) ??
-                    visibleScopeManifests.find((m) => m.metadata?.name === localName);
+                // Scope-local FIRST, enclosing module as the fallback — the order the
+                // runtime uses at every name-resolution site (`ScopeContext.getInstance`,
+                // `ResourceContext.resolveRef`, and the CEL `resources` layering). Module-first
+                // here would validate a shadowed name against the resource the kernel will
+                // never bind: a false pass when the outer kind fits and the scoped one does
+                // not, a false REFERENCE_KIND_MISMATCH when it is the other way round.
+                const target = visibleScopeManifests.find((m) => m.metadata?.name === localName) ??
+                    byName.get(localName);
                 if (!target) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,

package/package.json

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

package/src/analyzer.ts

@@ -51,6 +51,7 @@ import {
 import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateLogging } from "./validate-logging.js";
+import { validateModuleArtifact } from "./validate-module-artifact.js";
 import { validateBaseMapping } from "./validate-base-mapping.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
@@ -1153,7 +1154,7 @@ export class StaticAnalyzer {
     // {kind, name} objects so downstream phases (validation, dependency graph,
     // kernel controllers) see a uniform shape. Runs after normalize so both
     // original and inline-extracted manifests have their sentinels resolved.
-    resolveRefSentinels(allManifests, aliases, aliasesByModule);
+    resolveRefSentinels(allManifests, aliases, aliasesByModule, [], defs);
 
     // Phase 2.6: register each named `Telo.Type` resource's schema under its
     // canonical module-scoped id (`telo://<module>/<name>`), validate
@@ -1202,6 +1203,11 @@ export class StaticAnalyzer {
       // §14.1 / §10.3: redaction paths and `on_full: block` are statically
       // detectable, so they fail `telo check` rather than only at boot.
       diagnostics.push(...validateLogging(allManifests, defs, aliases, aliasesByModule));
+      // Module-artifact surface: bundled-controller selector qualifiers and the
+      // published `layers:` index. Every case is decidable from the manifest and
+      // would otherwise fail on a consumer's machine — or, for a mistyped platform
+      // axis, silently offer one platform's binary to every host.
+      diagnostics.push(...validateModuleArtifact(allManifests));
     }
     resolveSchemaTypeRefs(allManifests, aliases, aliasesByModule);
 
@@ -1957,7 +1963,13 @@ export class StaticAnalyzer {
     // Resolve !ref sentinels after normalize so both the original and
     // inline-extracted manifests get their refs canonicalized to
     // {kind, name} for the kernel that consumes this output.
-    resolveRefSentinels(normalized, ctx.aliases, ctx.aliasesByModule, crossModuleTargets ?? []);
+    resolveRefSentinels(
+      normalized,
+      ctx.aliases,
+      ctx.aliasesByModule,
+      crossModuleTargets ?? [],
+      ctx.definitions!,
+    );
     // Canonicalize import-scoped schema `$ref`s (`telo://Self|Alias/Type`) so the
     // kernel that executes this output compiles inputs/outputs against the same
     // ids the type controllers register their schemas under.

package/src/artifact-layer-index.ts

@@ -0,0 +1,162 @@
+/**
+ * The **layer index** of `kernel/specs/module-artifact.md` — the `layers:` block
+ * a published `telo.yaml` carries, listing every layer of the module artifact
+ * except the manifest layer itself.
+ *
+ * Why it lives in `telo.yaml` rather than in the OCI manifest, which has layers
+ * natively: a Telo import is pinned to a hash of `telo.yaml` and nothing else.
+ * The OCI manifest sits one level up, is fetched by a reference that is usually
+ * a mutable tag, and is never hashed by Telo — so digests held only there would
+ * leave the pin proving nothing about the payload. Pinning the OCI manifest
+ * instead is circular: `telo.yaml` is one of its layers.
+ *
+ * The manifest layer therefore has no entry — a hash of `telo.yaml` cannot sit
+ * inside `telo.yaml`. It is pinned by the importer's `#sha256-...` instead, so
+ * the chain reads `import pin -> telo.yaml -> blob digest -> layer contents`.
+ *
+ * Each entry carries two digests, answering different questions:
+ *  - `blob` — the OCI blob digest over the pushed bytes. It *addresses* the
+ *    layer, so a client pulls by digest and never reads the OCI layer list, and
+ *    it verifies the transfer. Publish pushes payload blobs first and injects
+ *    their digests here, then pushes the manifest blob, so nothing is circular.
+ *  - `integrity` — the content digest (`computeFilesIntegrity`) over that
+ *    layer's own files, independent of tar/gzip framing. It verifies what is
+ *    already extracted on disk and can be re-derived from it without re-tarring,
+ *    which is what makes a per-layer cache marker checkable.
+ *
+ * Browser-safe: `telo check`, the editor and the hub validate an index through
+ * this module; only the kernel fetches and extracts.
+ */
+
+import {
+  isLayerRole,
+  normalizeSelector,
+  selectorKey,
+  selectorMatches,
+  type ArtifactSelector,
+  type LayerRole,
+  type PlatformTarget,
+} from "./artifact-selector.js";
+
+/** OCI content digest: `sha256:` + 64 lowercase hex. */
+const BLOB_DIGEST = /^sha256:[0-9a-f]{64}$/;
+
+/** Telo content digest: `sha256-` + unpadded base64url of 32 bytes. */
+const CONTENT_DIGEST = /^sha256-[A-Za-z0-9_-]{43}$/;
+
+export interface ArtifactLayer {
+  role: LayerRole;
+  /** Present on `controller` layers only. */
+  selector?: ArtifactSelector;
+  /** OCI blob digest — addresses the layer and verifies the transfer. */
+  blob: string;
+  /** Content digest over the layer's files — verifies what is on disk. */
+  integrity: string;
+}
+
+export class LayerIndexError extends Error {
+  readonly code = "INVALID_LAYER_INDEX";
+
+  constructor(detail: string) {
+    super(detail);
+    this.name = "LayerIndexError";
+  }
+}
+
+function digest(field: "blob" | "integrity", raw: unknown, describe: string): string {
+  if (typeof raw !== "string" || raw === "") {
+    throw new LayerIndexError(`${describe}: ${field} is required and must be a string.`);
+  }
+  const pattern = field === "blob" ? BLOB_DIGEST : CONTENT_DIGEST;
+  if (!pattern.test(raw)) {
+    throw new LayerIndexError(
+      field === "blob"
+        ? `${describe}: blob '${raw}' is not an OCI digest (expected 'sha256:' + 64 hex characters).`
+        : `${describe}: integrity '${raw}' is not a content digest (expected 'sha256-' + 43 base64url characters).`,
+    );
+  }
+  return raw;
+}
+
+/**
+ * Parse and validate a `layers:` value off an owner document. Order is
+ * preserved — when several controller layers match a target, precedence is
+ * declaration order, so the author controls it.
+ */
+export function parseLayerIndex(value: unknown, describe = "layers"): ArtifactLayer[] {
+  if (!Array.isArray(value)) {
+    throw new LayerIndexError(`${describe}: expected an array of layer entries.`);
+  }
+  const layers: ArtifactLayer[] = [];
+  const seenSelectors = new Set<string>();
+  const seenSingletons = new Set<LayerRole>();
+
+  value.forEach((raw, index) => {
+    const where = `${describe}[${index}]`;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      throw new LayerIndexError(`${where}: expected an object.`);
+    }
+    const entry = raw as Record<string, unknown>;
+    if (!isLayerRole(entry.role)) {
+      throw new LayerIndexError(
+        `${where}: role must be one of 'controller', 'assets', 'common'; got ` +
+          `${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`,
+      );
+    }
+    const role = entry.role;
+
+    let selector: ArtifactSelector | undefined;
+    if (role === "controller") {
+      if (entry.selector === undefined) {
+        throw new LayerIndexError(`${where}: a controller layer must declare a selector.`);
+      }
+      selector = normalizeSelector(entry.selector, where);
+      const key = selectorKey(selector);
+      if (seenSelectors.has(key)) {
+        throw new LayerIndexError(
+          `${where}: a second controller layer claims the selector ${key}. ` +
+            `Each selector addresses exactly one layer.`,
+        );
+      }
+      seenSelectors.add(key);
+    } else {
+      if (entry.selector !== undefined) {
+        throw new LayerIndexError(
+          `${where}: a '${role}' layer must not declare a selector — it is a singleton.`,
+        );
+      }
+      if (seenSingletons.has(role)) {
+        throw new LayerIndexError(`${where}: a second '${role}' layer is declared.`);
+      }
+      seenSingletons.add(role);
+    }
+
+    layers.push({
+      role,
+      ...(selector ? { selector } : {}),
+      blob: digest("blob", entry.blob, where),
+      integrity: digest("integrity", entry.integrity, where),
+    });
+  });
+
+  return layers;
+}
+
+/** The singleton layer for a role, or undefined when the artifact has none. */
+export function singletonLayer(
+  layers: readonly ArtifactLayer[],
+  role: Exclude<LayerRole, "controller">,
+): ArtifactLayer | undefined {
+  return layers.find((l) => l.role === role);
+}
+
+/** Every controller layer matching `target`, in declaration order. Used by
+ *  `telo install` to warm a cache for one platform. */
+export function matchControllerLayers(
+  layers: readonly ArtifactLayer[],
+  target: PlatformTarget,
+): ArtifactLayer[] {
+  return layers.filter(
+    (l) => l.role === "controller" && l.selector !== undefined && selectorMatches(l.selector, target),
+  );
+}