@telorun/analyzer 0.47.0 → 0.48.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.47.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.59.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";
@@ -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);
 

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),
+  );
+}

package/src/artifact-selector.ts

@@ -0,0 +1,171 @@
+/**
+ * The **selector** of `kernel/specs/module-artifact.md` — the tuple a bundled
+ * controller candidate is chosen by, and the key a controller layer of a module
+ * artifact is stored under.
+ *
+ * A selector is `format` plus the optional platform axes `os` / `arch` / `libc`.
+ * Matching is one rule, applied per axis: an axis the selector omits accepts
+ * anything, an axis it states must be equal. That is what lets a `js` controller
+ * be platform-neutral and a `napi` controller be pinned to one triple, with no
+ * special case for either.
+ *
+ * Browser-safe and dependency-free by construction. Three consumers must agree
+ * on this grammar or a published artifact stops loading: `telo publish`
+ * (partitioning files into layers), `telo install --platform` (deciding which
+ * layers to pre-fetch), and the kernel's bundle controller loader (matching a
+ * candidate against the host). Keeping it here — beside the redaction path
+ * parser, for the same reason — means one implementation rather than three that
+ * drift.
+ *
+ * PURL *syntax* is deliberately not parsed here. Callers hand in the format and
+ * an already-decoded qualifier map, so this module owns selector semantics while
+ * the caller owns its own package-URL library. The Node vocabulary is likewise
+ * not known here: `process.platform` / `process.arch` are mapped to the
+ * canonical OCI/GOOS names at the kernel boundary, since these values are
+ * published into OCI descriptors.
+ */
+
+/** The role a layer plays in a module artifact. `controller` layers carry a
+ *  selector; `assets` and `common` are singletons and carry none. */
+export type LayerRole = "controller" | "assets" | "common";
+
+export const LAYER_ROLES: readonly LayerRole[] = ["controller", "assets", "common"];
+
+export function isLayerRole(value: unknown): value is LayerRole {
+  return typeof value === "string" && (LAYER_ROLES as readonly string[]).includes(value);
+}
+
+/** The platform axes, in canonical order. Not a closed vocabulary of *values* —
+ *  new architectures appear without a Telo release — only of axis names. */
+export const PLATFORM_AXES = ["os", "arch", "libc"] as const;
+
+export type PlatformAxis = (typeof PLATFORM_AXES)[number];
+
+export interface ArtifactSelector {
+  /** Bundled controller format: the PURL name segment (`js`, `napi`, `wasm`, …). */
+  format: string;
+  os?: string;
+  arch?: string;
+  libc?: string;
+}
+
+/** What a selector is matched against: the host the kernel runs on, or the
+ *  target `telo install --platform` is warming a cache for. An axis left
+ *  undetermined (a host whose libc cannot be detected) matches no selector that
+ *  constrains it — refusing to load is the safe direction for a native binary. */
+export interface PlatformTarget {
+  format?: string;
+  os?: string;
+  arch?: string;
+  libc?: string;
+}
+
+export class ArtifactSelectorError extends Error {
+  readonly code = "INVALID_ARTIFACT_SELECTOR";
+
+  constructor(detail: string) {
+    super(detail);
+    this.name = "ArtifactSelectorError";
+  }
+}
+
+/** Canonical token shape for every selector value. Lowercase, so the same
+ *  platform written two ways is one layer rather than two. */
+const TOKEN = /^[a-z0-9][a-z0-9_.-]*$/;
+
+function normalizeToken(axis: string, raw: unknown, describe: string): string {
+  if (typeof raw !== "string") {
+    throw new ArtifactSelectorError(
+      `${describe}: ${axis} must be a string, got ${raw === null ? "null" : typeof raw}.`,
+    );
+  }
+  const value = raw.trim().toLowerCase();
+  if (!TOKEN.test(value)) {
+    throw new ArtifactSelectorError(
+      `${describe}: ${axis} value '${raw}' is not a canonical token. ` +
+        `Use lowercase letters, digits, '.', '-' or '_', starting with a letter or digit.`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Build a selector from a controller candidate's format and qualifier map.
+ * Qualifier keys other than the platform axes are ignored — `path` and the
+ * sibling list live in the same map and are not part of the selector.
+ */
+export function selectorFromQualifiers(
+  format: unknown,
+  qualifiers: Readonly<Record<string, unknown>> | undefined,
+  describe = "controller selector",
+): ArtifactSelector {
+  const selector: ArtifactSelector = {
+    format: normalizeToken("format", format, describe),
+  };
+  for (const axis of PLATFORM_AXES) {
+    const raw = qualifiers?.[axis];
+    if (raw === undefined || raw === "") continue;
+    selector[axis] = normalizeToken(axis, raw, describe);
+  }
+  return selector;
+}
+
+/** Validate and normalize a selector read off a published layer index. */
+export function normalizeSelector(
+  value: unknown,
+  describe = "layer selector",
+): ArtifactSelector {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ArtifactSelectorError(`${describe}: expected an object of selector axes.`);
+  }
+  const record = value as Record<string, unknown>;
+  const unknown = Object.keys(record).filter(
+    (k) => k !== "format" && !(PLATFORM_AXES as readonly string[]).includes(k),
+  );
+  if (unknown.length > 0) {
+    throw new ArtifactSelectorError(
+      `${describe}: unknown selector ${unknown.length === 1 ? "axis" : "axes"} ` +
+        `${unknown.map((k) => `'${k}'`).join(", ")}. Known axes: format, ${PLATFORM_AXES.join(", ")}.`,
+    );
+  }
+  return selectorFromQualifiers(record.format, record, describe);
+}
+
+/**
+ * The canonical stable key for a selector: sorted `axis=value` pairs joined by
+ * `;`. Used to group entry points into layers at publish time and to detect two
+ * layers claiming the same selector. Sorted and fully qualified so no two
+ * distinct selectors can collide and no one selector has two spellings.
+ */
+export function selectorKey(selector: ArtifactSelector): string {
+  const pairs: string[] = [`format=${selector.format}`];
+  for (const axis of PLATFORM_AXES) {
+    const value = selector[axis];
+    if (value !== undefined) pairs.push(`${axis}=${value}`);
+  }
+  return pairs.sort().join(";");
+}
+
+/** Human-facing rendering for diagnostics and the publish partition printout. */
+export function describeSelector(selector: ArtifactSelector): string {
+  const platform = PLATFORM_AXES.map((axis) => selector[axis]).filter(
+    (v): v is string => v !== undefined,
+  );
+  return platform.length === 0 ? selector.format : `${selector.format} (${platform.join("/")})`;
+}
+
+/**
+ * The matching rule: every axis the selector states must equal the target's;
+ * every axis it omits accepts anything. A target axis left undetermined matches
+ * only a selector that does not constrain it — a host whose libc is unknown must
+ * not be handed a `libc=gnu` binary on the assumption it will run.
+ */
+export function selectorMatches(selector: ArtifactSelector, target: PlatformTarget): boolean {
+  if (target.format !== undefined && selector.format !== target.format) return false;
+  for (const axis of PLATFORM_AXES) {
+    const constraint = selector[axis];
+    if (constraint === undefined) continue;
+    if (target[axis] !== constraint) return false;
+  }
+  return true;
+}

package/src/builtins.ts

@@ -23,6 +23,53 @@ const PROVENANCE_METADATA = {
   documentation: { type: "string" },
 };
 
+/** Author-declared subset of `files:` that ships in the artifact's lazily
+ *  materialized `assets` layer. Optional: an unclaimed file joins the `common`
+ *  layer, which is pulled alongside any controller layer, so omitting this costs
+ *  laziness rather than correctness. See kernel/specs/module-artifact.md. */
+const ASSETS_FILES_SCHEMA = {
+  type: "array",
+  items: { type: "string" },
+};
+
+/** The published layer index, written by `telo publish` (never hand-authored).
+ *  One entry per layer except the manifest layer, which cannot list its own hash
+ *  inside itself and is pinned by the importer's `#sha256-...` instead. Shape and
+ *  matching rules are normative in kernel/specs/module-artifact.md; the parser
+ *  that enforces them is `artifact-layer-index.ts`. */
+const LAYER_INDEX_SCHEMA = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["role", "blob", "integrity"],
+    properties: {
+      role: { type: "string", enum: ["controller", "assets", "common"] },
+      selector: {
+        type: "object",
+        required: ["format"],
+        properties: {
+          format: { type: "string" },
+          os: { type: "string" },
+          arch: { type: "string" },
+          libc: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+      blob: { type: "string", pattern: "^sha256:[0-9a-f]{64}$" },
+      integrity: { type: "string", pattern: "^sha256-[A-Za-z0-9_-]{43}$" },
+    },
+    additionalProperties: false,
+  },
+};
+
+/** The pre-layers payload digest, superseded by the per-layer `integrity` values
+ *  in `layers:`. Accepted and ignored, for one reason only: a module published in
+ *  the old single-blob shape must reach the *actionable* failure — the controller
+ *  loader's "republish the module" error — instead of dying earlier on
+ *  `must NOT have additional properties`, which tells an author nothing. Nothing
+ *  reads this field. */
+const LEGACY_FILES_INTEGRITY_SCHEMA = { type: "string" };
+
 /** The six named levels of `kernel/specs/logging.md` §5.1. The full 1–24 OTel
  *  range stays valid on the wire; only these are nameable in a manifest. */
 const LOG_LEVEL_ENUM = ["trace", "debug", "info", "warn", "error", "fatal"];
@@ -529,21 +576,18 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
-        // Files bundled alongside `telo.yaml` into the module's registry
-        // artifact (`module.tar.gz`) — static assets served by Http.Static,
-        // templates, etc. Ordered `.gitignore`-style patterns resolved against
-        // the manifest dir at publish time. Analyzer-only role: accept the
-        // field (the schema is additionalProperties:false); the analyzer never
-        // reads the assets. See kernel/nodejs/plans/bundle-controllers.md.
+        // Files bundled alongside `telo.yaml` into the module's artifact —
+        // controller bundles, static assets served by Http.Static, templates,
+        // etc. Ordered `.gitignore`-style patterns resolved against the manifest
+        // dir at publish time. Analyzer-only role: accept the field (the schema
+        // is additionalProperties:false); the analyzer never reads the payload.
         files: {
           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" },
+        assets: ASSETS_FILES_SCHEMA,
+        layers: LAYER_INDEX_SCHEMA,
+        filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // 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
@@ -680,18 +724,16 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
-        // Files bundled into the module's registry artifact — same semantics as
-        // the Telo.Application `files` field above (a library may ship bundled
-        // templates, migrations, seed data).
+        // Files bundled into the module's artifact — same semantics as the
+        // Telo.Application `files` field above (a library may ship bundled
+        // controllers, templates, migrations, seed data).
         files: {
           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" },
+        assets: ASSETS_FILES_SCHEMA,
+        layers: LAYER_INDEX_SCHEMA,
+        filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // 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.

package/src/index.ts

@@ -120,6 +120,31 @@ export {
   urlManifestCacheCoords,
 } from "./sources/manifest-cache.js";
 export type { ManifestCacheCoords } from "./sources/manifest-cache.js";
+export {
+  LAYER_ROLES,
+  PLATFORM_AXES,
+  ArtifactSelectorError,
+  describeSelector,
+  isLayerRole,
+  normalizeSelector,
+  selectorFromQualifiers,
+  selectorKey,
+  selectorMatches,
+} from "./artifact-selector.js";
+export type {
+  ArtifactSelector,
+  LayerRole,
+  PlatformAxis,
+  PlatformTarget,
+} from "./artifact-selector.js";
+export {
+  LayerIndexError,
+  matchControllerLayers,
+  parseLayerIndex,
+  singletonLayer,
+} from "./artifact-layer-index.js";
+export type { ArtifactLayer } from "./artifact-layer-index.js";
+export { validateModuleArtifact } from "./validate-module-artifact.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";