@telorun/analyzer 0.47.0 → 0.49.0

package/dist/artifact-layer-index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { type ArtifactSelector, type LayerRole, type PlatformTarget } from "./artifact-selector.js";
+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 declare class LayerIndexError extends Error {
+    readonly code = "INVALID_LAYER_INDEX";
+    constructor(detail: string);
+}
+/**
+ * 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 declare function parseLayerIndex(value: unknown, describe?: string): ArtifactLayer[];
+/** The singleton layer for a role, or undefined when the artifact has none. */
+export declare function singletonLayer(layers: readonly ArtifactLayer[], role: Exclude<LayerRole, "controller">): ArtifactLayer | undefined;
+/** Every controller layer matching `target`, in declaration order. Used by
+ *  `telo install` to warm a cache for one platform. */
+export declare function matchControllerLayers(layers: readonly ArtifactLayer[], target: PlatformTarget): ArtifactLayer[];
+//# sourceMappingURL=artifact-layer-index.d.ts.map

package/dist/artifact-layer-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-layer-index.d.ts","sourceRoot":"","sources":["../src/artifact-layer-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAKL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAQhC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,yBAAyB;gBAE1B,MAAM,EAAE,MAAM;CAI3B;AAiBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAW,GAAG,aAAa,EAAE,CAyDpF;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,GACrC,aAAa,GAAG,SAAS,CAE3B;AAED;uDACuD;AACvD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,MAAM,EAAE,cAAc,GACrB,aAAa,EAAE,CAIjB"}

package/dist/artifact-layer-index.js

@@ -0,0 +1,116 @@
+/**
+ * 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, } 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 class LayerIndexError extends Error {
+    code = "INVALID_LAYER_INDEX";
+    constructor(detail) {
+        super(detail);
+        this.name = "LayerIndexError";
+    }
+}
+function digest(field, raw, describe) {
+    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, describe = "layers") {
+    if (!Array.isArray(value)) {
+        throw new LayerIndexError(`${describe}: expected an array of layer entries.`);
+    }
+    const layers = [];
+    const seenSelectors = new Set();
+    const seenSingletons = new Set();
+    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;
+        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;
+        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, role) {
+    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, target) {
+    return layers.filter((l) => l.role === "controller" && l.selector !== undefined && selectorMatches(l.selector, target));
+}

package/dist/artifact-selector.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 declare const LAYER_ROLES: readonly LayerRole[];
+export declare function isLayerRole(value: unknown): value is LayerRole;
+/** The platform axes, in canonical order. Not a closed vocabulary of *values* —
+ *  new architectures appear without a Telo release — only of axis names. */
+export declare const PLATFORM_AXES: readonly ["os", "arch", "libc"];
+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 declare class ArtifactSelectorError extends Error {
+    readonly code = "INVALID_ARTIFACT_SELECTOR";
+    constructor(detail: string);
+}
+/**
+ * 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 declare function selectorFromQualifiers(format: unknown, qualifiers: Readonly<Record<string, unknown>> | undefined, describe?: string): ArtifactSelector;
+/** Validate and normalize a selector read off a published layer index. */
+export declare function normalizeSelector(value: unknown, describe?: string): ArtifactSelector;
+/**
+ * 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 declare function selectorKey(selector: ArtifactSelector): string;
+/** Human-facing rendering for diagnostics and the publish partition printout. */
+export declare function describeSelector(selector: ArtifactSelector): string;
+/**
+ * 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 declare function selectorMatches(selector: ArtifactSelector, target: PlatformTarget): boolean;
+//# sourceMappingURL=artifact-selector.d.ts.map

package/dist/artifact-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-selector.d.ts","sourceRoot":"","sources":["../src/artifact-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;qEACqE;AACrE,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAAuC,CAAC;AAEpF,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;4EAC4E;AAC5E,eAAO,MAAM,aAAa,iCAAkC,CAAC;AAE7D,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;kFAGkF;AAClF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,+BAA+B;gBAEhC,MAAM,EAAE,MAAM;CAI3B;AAsBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EACzD,QAAQ,SAAwB,GAC/B,gBAAgB,CAUlB;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,SAAmB,GAC1B,gBAAgB,CAelB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAO9D;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAKnE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAQ3F"}

package/dist/artifact-selector.js

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ */
+export const LAYER_ROLES = ["controller", "assets", "common"];
+export function isLayerRole(value) {
+    return typeof value === "string" && LAYER_ROLES.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"];
+export class ArtifactSelectorError extends Error {
+    code = "INVALID_ARTIFACT_SELECTOR";
+    constructor(detail) {
+        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, raw, describe) {
+    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, qualifiers, describe = "controller selector") {
+    const selector = {
+        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, describe = "layer selector") {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ArtifactSelectorError(`${describe}: expected an object of selector axes.`);
+    }
+    const record = value;
+    const unknown = Object.keys(record).filter((k) => k !== "format" && !PLATFORM_AXES.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) {
+    const pairs = [`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) {
+    const platform = PLATFORM_AXES.map((axis) => selector[axis]).filter((v) => 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, target) {
+    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/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;AA4GvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA+nB/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AA2JvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAmsB/C,CAAC"}

package/dist/builtins.js

@@ -20,6 +20,50 @@ const PROVENANCE_METADATA = {
     license: { type: "string" },
     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"];
@@ -162,6 +206,64 @@ export const KERNEL_BUILTINS = [
             additionalProperties: false,
         },
     },
+    {
+        // Telo.JsonSchema — the concrete data-shape kind, in the kernel rather than
+        // in an installable module for the same reason the mandatory sinks are:
+        // declaring a shape is not optional. Every kind with an invocation contract
+        // needs one, so requiring an import to write `inputType:` would put a tax on
+        // the one thing the contract wants authors to do more of — and a library
+        // declaring a contract would have to import a module purely to describe
+        // itself. `type.JsonSchema` remains as a deprecated alias of this kind.
+        kind: "Telo.Definition",
+        metadata: { name: "JsonSchema", module: "Telo" },
+        capability: "Telo.Type",
+        // Declared so the kind reads as controller-BEARING, which is what lets
+        // another definition inherit it by delegation (`extends: Telo.JsonSchema`
+        // with no controller of its own). The entry is never loaded from — the
+        // kernel registers this controller directly at boot, before any lazy
+        // resolution — it states truthfully who provides it.
+        controllers: [{ runtime: "kernel", entry: "Telo.JsonSchema" }],
+        schema: {
+            type: "object",
+            properties: {
+                schema: {
+                    title: "Schema",
+                    description: "JSON Schema definition for the declared data type.",
+                    type: "object",
+                },
+                extends: {
+                    title: "Extends",
+                    description: "Parent type name or list of parent type names to inherit from.",
+                    oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+                },
+                rules: {
+                    title: "Rules",
+                    description: "CEL-based business invariant rules. Each rule's condition must return true for valid data.",
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            condition: {
+                                type: "string",
+                                description: "CEL expression evaluated with 'this' bound to the data. Must return true for valid data.",
+                            },
+                            code: {
+                                type: "string",
+                                description: "Machine-readable error code surfaced on validation failure.",
+                            },
+                            message: {
+                                type: "string",
+                                description: "Optional human-readable hint for the validation failure.",
+                            },
+                        },
+                        required: ["condition", "code"],
+                    },
+                },
+            },
+            required: ["schema"],
+            additionalProperties: false,
+        },
+    },
     {
         kind: "Telo.Definition",
         metadata: { name: "Abstract", module: "Telo" },
@@ -435,6 +537,11 @@ export const KERNEL_BUILTINS = [
                     default: "shared",
                 },
                 targets: {
+                    // Boot targets form a step list: a later target reads an earlier one's
+                    // result as `steps.<name>.result`, exactly as a sequence step does, so
+                    // the same annotation types that context and drives the call-site
+                    // contract check.
+                    "x-telo-step-context": { invoke: "invoke", outputType: "outputType" },
                     type: "array",
                     items: {
                         anyOf: [
@@ -508,7 +615,15 @@ export const KERNEL_BUILTINS = [
                                             { "x-telo-ref": "Telo.Runnable" },
                                         ],
                                     },
-                                    inputs: { type: "object", additionalProperties: true },
+                                    inputs: {
+                                        // Same annotation Run.Sequence steps carry: it is what makes
+                                        // a boot target's inputs visible to the call-site contract
+                                        // check and to the wiring rule. Without it the kernel would
+                                        // validate these at dispatch and nothing before it.
+                                        "x-telo-topology-role": "inputs",
+                                        type: "object",
+                                        additionalProperties: true,
+                                    },
                                     when: { type: "string" },
                                 },
                                 additionalProperties: false,
@@ -520,21 +635,18 @@ export const KERNEL_BUILTINS = [
                     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
@@ -671,18 +783,16 @@ export const KERNEL_BUILTINS = [
                     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/dist/extends-resolution.d.ts

@@ -36,6 +36,47 @@ export declare function inheritedCapability(def: ResourceDefinition | undefined,
  *    `mergeTypeSchemas` that `Type.JsonSchema.extends` uses.
  *  - no `extends` → the own schema unchanged. */
 export declare function effectiveAuthorSchema(def: ResourceDefinition | undefined, resolve: DefResolver): Record<string, any>;
+/** The two directions of a kind's invocation contract. `inputType` is what a
+ *  caller sends to `invoke()`; `outputType` is what `invoke()` / `provide()`
+ *  returns. */
+export type ContractDirection = "inputType" | "outputType";
+/**
+ * The **nearest declaration** of an invocation contract along the `extends`
+ * chain, self first — the raw type-field value, still to be resolved to a schema
+ * by the caller (which is what keeps this module free of manifest lookup).
+ *
+ * Contracts RESOLVE, they never merge. A definition that declares one fully
+ * replaces its ancestor's; one that declares none inherits its ancestor's
+ * verbatim, at any depth. This is deliberately unlike {@link
+ * effectiveAuthorSchema} and {@link effectiveStatusSchema}: construction config
+ * and observed state are additive, a call signature is not. Folding a child's
+ * required fields into its parent's yields a union no caller can satisfy, and it
+ * would reject the very remapping `base:` + `inputs:` exists for — the point of
+ * a child declaring a signature is that it accepts something *different*.
+ *
+ * Substitutability is not weakened by that, because `extends` never carried the
+ * dispatch contract: it decides which slots accept a resource. Whether a
+ * particular slot may hold a resource whose contract differs from the slot's
+ * declared kind is a wiring question, answered per slot by
+ * `validate-invocation-contract`'s wiring rule.
+ */
+export declare function effectiveContractField(def: ResourceDefinition | undefined, resolve: DefResolver, direction: ContractDirection): unknown;
+/** The definition in the `extends` chain (self first) that actually DECLARES the
+ *  contract for `direction` — the one whose scope its `telo#Type` references
+ *  resolve in, and the one a diagnostic should name. Undefined when nothing in
+ *  the chain declares it. */
+export declare function contractDeclarer(def: ResourceDefinition | undefined, resolve: DefResolver, direction: ContractDirection): ResourceDefinition | undefined;
+/** True when this definition declares its own contract for `direction` while
+ *  inheriting the controller that will execute it — the case that REQUIRES a
+ *  bridging mapping (`inputs:` for inputs, `result:` for outputs), because the
+ *  inherited controller only understands the ancestor's shape. A definition with
+ *  its own controller or template body is exempt: its controller *is* the
+ *  implementation of whatever it declares. */
+export declare function needsContractMapping(def: ResourceDefinition | undefined, resolve: DefResolver, direction: ContractDirection): boolean;
+/** The mapping field that bridges a replaced contract back to the inherited
+ *  controller: `inputs:` maps the child's signature onto the parent's call,
+ *  `result:` maps the parent's result back to the child's declared output. */
+export declare function mappingFieldFor(direction: ContractDirection): "inputs" | "result";
 /** The observed state a kind reports (`status:`), folded through `extends`:
  *  - with `base:` present → the **parent's** effective status unchanged; the
  *    child delegates to the parent's controller and *is* a parent instance, so

package/dist/extends-resolution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extends-resolution.d.ts","sourceRoot":"","sources":["../src/extends-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD;;;;;;;2DAO2D;AAC3D,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,kBAAkB,KACtB,kBAAkB,GAAG,SAAS,CAAC;AAsBpC;sDACsD;AACtD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAIhC;AAED;6EAC6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,EAAE,CAUtB;AAED;iFACiF;AACjF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAUvF;AAED;;mFAEmF;AACnF,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAMhC;AAED;;sCAEsC;AACtC,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,OAAO,CAGT;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOrB;AAED;;;;;;;;;gDASgD;AAChD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CASjC"}
+{"version":3,"file":"extends-resolution.d.ts","sourceRoot":"","sources":["../src/extends-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD;;;;;;;2DAO2D;AAC3D,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,kBAAkB,KACtB,kBAAkB,GAAG,SAAS,CAAC;AA0BpC;sDACsD;AACtD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAIhC;AAED;6EAC6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,EAAE,CAUtB;AAED;iFACiF;AACjF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAUvF;AAED;;mFAEmF;AACnF,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAMhC;AAED;;sCAEsC;AACtC,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,OAAO,CAGT;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOrB;AAED;;eAEe;AACf,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,iBAAiB,GAC3B,OAAO,CAQT;AAED;;;6BAG6B;AAC7B,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,iBAAiB,GAC3B,kBAAkB,GAAG,SAAS,CAShC;AAED;;;;;8CAK8C;AAC9C,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,iBAAiB,GAC3B,OAAO,CAKT;AAED;;8EAE8E;AAC9E,wBAAgB,eAAe,CAAC,SAAS,EAAE,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,CAEjF;AAED;;;;;;;;;gDASgD;AAChD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CASjC"}