@telorun/analyzer 0.73.0 → 0.74.0

package/dist/source-entries.d.ts

@@ -0,0 +1,119 @@
+/**
+ * A module's **sources** — the `sources:` block on a `Telo.Library` or
+ * `Telo.Application` doc, saying where every staged file comes from: a pinned
+ * upstream archive, fetched by `telo release stage`.
+ *
+ * ```yaml
+ * sources:
+ *   better-sqlite3:
+ *     version: 12.8.0
+ *     url: https://github.com/WiseLibs/better-sqlite3/releases/download/v{version}/better-sqlite3-v{version}-{upstream}.tar.gz
+ *     archive: tar.gz
+ *     notices: [./notices/better-sqlite3.LICENSE]
+ *     entries:
+ *       ./native/linux-amd64-gnu-node-137/better_sqlite3.node:
+ *         upstream: node-v137-linux-x64
+ *         member: build/Release/better_sqlite3.node
+ *         sha256: 4c9e…
+ *         executable: false
+ *       ./native/linux-amd64-gnu/libvips.so:
+ *         target: libvips.so.42
+ * ```
+ *
+ * Keyed by the module-relative path an entry produces, because the manifest
+ * already names every staged file — a `native:` entry's path or a
+ * platform-qualified controller candidate's `path=`.
+ *
+ * The single reader: every rule decidable from the block alone is a problem
+ * here, so `telo check` (`validate-source-entries.ts`), the stager and the
+ * kernels refuse the same blocks. Browser-safe: string work only.
+ */
+/** The archive formats an upstream may be. */
+export declare const SOURCE_ARCHIVE_FORMATS: readonly ["tar.gz"];
+export type SourceArchiveFormat = (typeof SOURCE_ARCHIVE_FORMATS)[number];
+export interface SourcePin {
+    /** Lowercase hex digest of the file's bytes. */
+    readonly sha256: string;
+    readonly executable: boolean;
+}
+interface SourceEntryBase {
+    /** The key as written, for diagnostic paths. */
+    readonly key: string;
+    /** Module-root-relative POSIX path, normalized. */
+    readonly path: string;
+}
+export type SourceEntry = (SourceEntryBase & {
+    readonly kind: "file";
+    readonly upstream: string;
+    /** Path of the file inside the archive. */
+    readonly member: string;
+    /** Absent until `telo release stage --pin` writes it. */
+    readonly pin?: SourcePin;
+}) | (SourceEntryBase & {
+    readonly kind: "link";
+    /** The link target, exactly as the link stores it. */
+    readonly target: string;
+    /** The module-relative path the target resolves to. */
+    readonly resolved: string;
+});
+/** How a source's files are built in this repository, keyed by build system. */
+export interface SourceBuild {
+    /** Module-root-relative directory of the Cargo crate the files are built
+     *  from, normalized (`""` for the module root). */
+    readonly cargo: string;
+    /** Digest of that crate's build inputs, `sha256-<base64url>`; absent until
+     *  `telo release stage --pin` records it. */
+    readonly inputs?: string;
+}
+export interface ModuleSource {
+    readonly name: string;
+    readonly version: string;
+    /** The URL template, as written. */
+    readonly url: string;
+    readonly archive: SourceArchiveFormat;
+    /** Module-root-relative notice paths, normalized. */
+    readonly notices: readonly string[];
+    readonly entries: readonly SourceEntry[];
+    readonly build?: SourceBuild;
+}
+/**
+ * Why part of the block could not be read.
+ *
+ * `SHAPE` is a missing, mistyped or unknown key the owner doc's JSON Schema
+ * reports in the same pass; every other code is a rule `telo check` reports.
+ */
+export type SourceProblemCode = "SHAPE" | "SOURCE_INVALID" | "SOURCE_URL_PLACEHOLDER_UNKNOWN" | "SOURCE_URL_INSECURE" | "SOURCE_ENTRY_INVALID" | "SOURCE_LINK_TARGET_UNRESOLVED" | "SOURCE_LINK_CYCLE" | "SOURCE_ENTRY_DUPLICATE" | "SOURCE_ENTRY_NESTED";
+export interface SourceProblem {
+    readonly code: SourceProblemCode;
+    /** Dotted path from the module doc root, for `data.path`. */
+    readonly path: string;
+    readonly message: string;
+}
+export interface ModuleSources {
+    readonly sources: ModuleSource[];
+    readonly problems: SourceProblem[];
+}
+/** The URL an entry is fetched from: substitution only. */
+export declare function resolveSourceUrl(source: ModuleSource, upstream: string): string;
+/** Why a url — a template, or the URL a fetch ended at after redirects — may not
+ *  be fetched from, or undefined when it may: https, or plain http to a loopback
+ *  host. */
+export declare function sourceUrlProblem(url: string): {
+    code: SourceProblemCode;
+    detail: string;
+} | undefined;
+/**
+ * Read the `sources:` block off an owner document's JSON projection.
+ *
+ * A source or entry with any problem is left out, never read partially: a
+ * half-read entry would stage a file the author did not declare.
+ *
+ * `ignorePins` reads a file entry's `sha256` / `executable` and a build's
+ * `inputs` as absent — for the one writer of pins, which replaces them whatever
+ * they held.
+ */
+export declare function readModuleSources(ownerJson: unknown, options?: {
+    ignorePins?: boolean;
+}): ModuleSources;
+export {};
+//# sourceMappingURL=source-entries.d.ts.map

package/dist/source-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-entries.d.ts","sourceRoot":"","sources":["../src/source-entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAcH,8CAA8C;AAC9C,eAAO,MAAM,sBAAsB,qBAAsB,CAAC;AAC1D,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,UAAU,eAAe;IACvB,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,WAAW,GACnB,CAAC,eAAe,GAAG;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC;CAC1B,CAAC,GACF,CAAC,eAAe,GAAG;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CAAC,CAAC;AAEP,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B;uDACmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;iDAC6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,gBAAgB,GAChB,gCAAgC,GAChC,qBAAqB,GACrB,sBAAsB,GACtB,+BAA+B,GAC/B,mBAAmB,GACnB,wBAAwB,GACxB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC;CACpC;AAKD,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE/E;AAUD;;YAEY;AACZ,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAsBrG;AAOD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,OAAO,EAClB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,aAAa,CAwTf"}

package/dist/source-entries.js

@@ -0,0 +1,349 @@
+/**
+ * A module's **sources** — the `sources:` block on a `Telo.Library` or
+ * `Telo.Application` doc, saying where every staged file comes from: a pinned
+ * upstream archive, fetched by `telo release stage`.
+ *
+ * ```yaml
+ * sources:
+ *   better-sqlite3:
+ *     version: 12.8.0
+ *     url: https://github.com/WiseLibs/better-sqlite3/releases/download/v{version}/better-sqlite3-v{version}-{upstream}.tar.gz
+ *     archive: tar.gz
+ *     notices: [./notices/better-sqlite3.LICENSE]
+ *     entries:
+ *       ./native/linux-amd64-gnu-node-137/better_sqlite3.node:
+ *         upstream: node-v137-linux-x64
+ *         member: build/Release/better_sqlite3.node
+ *         sha256: 4c9e…
+ *         executable: false
+ *       ./native/linux-amd64-gnu/libvips.so:
+ *         target: libvips.so.42
+ * ```
+ *
+ * Keyed by the module-relative path an entry produces, because the manifest
+ * already names every staged file — a `native:` entry's path or a
+ * platform-qualified controller candidate's `path=`.
+ *
+ * The single reader: every rule decidable from the block alone is a problem
+ * here, so `telo check` (`validate-source-entries.ts`), the stager and the
+ * kernels refuse the same blocks. Browser-safe: string work only.
+ */
+import { normalizeNativePath } from "./native-entries.js";
+const SOURCE_NAME_TOKEN = /^[a-z0-9][a-z0-9_.-]*$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const INPUTS_DIGEST = /^sha256-[A-Za-z0-9_-]{43}$/;
+const SOURCE_KEYS = ["version", "url", "archive", "notices", "entries", "build"];
+const BUILD_KEYS = ["cargo", "inputs"];
+const URL_PLACEHOLDERS = new Set(["version", "upstream"]);
+const FILE_KEYS = ["upstream", "member", "sha256", "executable"];
+const URL_ORIGIN = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i;
+const LOOPBACK_HOST = /^(localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[::1\])$/i;
+/** The archive formats an upstream may be. */
+export const SOURCE_ARCHIVE_FORMATS = ["tar.gz"];
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The URL an entry is fetched from: substitution only. */
+export function resolveSourceUrl(source, upstream) {
+    return source.url.replaceAll("{version}", source.version).replaceAll("{upstream}", upstream);
+}
+/** Resolve a link target against the link's own directory, confined to the module. */
+function resolveLinkTarget(linkPath, target) {
+    const dir = linkPath.includes("/") ? linkPath.slice(0, linkPath.lastIndexOf("/")) : "";
+    if (target.startsWith("/") || target.startsWith("\\"))
+        return undefined;
+    const verdict = normalizeNativePath(dir === "" ? target : `${dir}/${target}`);
+    return "path" in verdict ? verdict.path : undefined;
+}
+/** Why a url — a template, or the URL a fetch ended at after redirects — may not
+ *  be fetched from, or undefined when it may: https, or plain http to a loopback
+ *  host. */
+export function sourceUrlProblem(url) {
+    const origin = URL_ORIGIN.exec(url);
+    if (!origin) {
+        return {
+            code: "SOURCE_INVALID",
+            detail: `url '${url}' is not an absolute URL. Write an https:// URL template.`,
+        };
+    }
+    const scheme = origin[1].toLowerCase();
+    if (scheme === "https")
+        return undefined;
+    const authority = origin[2];
+    const hostPort = authority.slice(authority.lastIndexOf("@") + 1);
+    const host = hostPort.startsWith("[")
+        ? hostPort.slice(0, hostPort.indexOf("]") + 1)
+        : hostPort.split(":")[0];
+    if (scheme === "http" && LOOPBACK_HOST.test(host))
+        return undefined;
+    return {
+        code: "SOURCE_URL_INSECURE",
+        detail: `url '${url}' is fetched over ${scheme}, where the archive could be altered on the way. ` +
+            `Use https; plain http is accepted only for a loopback host (localhost, 127.0.0.0/8, [::1]).`,
+    };
+}
+/** Whether one normalized module-relative path is a directory the other runs through. */
+function runsThrough(path, parent) {
+    return path.startsWith(`${parent}/`);
+}
+/**
+ * Read the `sources:` block off an owner document's JSON projection.
+ *
+ * A source or entry with any problem is left out, never read partially: a
+ * half-read entry would stage a file the author did not declare.
+ *
+ * `ignorePins` reads a file entry's `sha256` / `executable` and a build's
+ * `inputs` as absent — for the one writer of pins, which replaces them whatever
+ * they held.
+ */
+export function readModuleSources(ownerJson, options = {}) {
+    const ignorePins = options.ignorePins === true;
+    const declared = ownerJson?.sources;
+    const sources = [];
+    const problems = [];
+    if (declared === undefined)
+        return { sources, problems };
+    const problem = (code, path, message) => problems.push({ code, path, message });
+    if (!isObject(declared)) {
+        problem("SHAPE", "sources", "sources: expected a map of source name to source.");
+        return { sources, problems };
+    }
+    const producers = new Map();
+    for (const [name, raw] of Object.entries(declared)) {
+        const at = `sources.${name}`;
+        const label = `source '${name}'`;
+        if (!isObject(raw)) {
+            problem("SHAPE", at, `${label}: expected an object.`);
+            continue;
+        }
+        const build = raw.build;
+        if (typeof raw.version !== "string" ||
+            typeof raw.url !== "string" ||
+            !SOURCE_ARCHIVE_FORMATS.includes(raw.archive) ||
+            !Array.isArray(raw.notices) ||
+            raw.notices.length === 0 ||
+            raw.notices.some((notice) => typeof notice !== "string") ||
+            !isObject(raw.entries) ||
+            (build !== undefined &&
+                (!isObject(build) ||
+                    typeof build.cargo !== "string" ||
+                    (!ignorePins && "inputs" in build && typeof build.inputs !== "string") ||
+                    Object.keys(build).some((key) => !BUILD_KEYS.includes(key)))) ||
+            Object.keys(raw).some((key) => !SOURCE_KEYS.includes(key))) {
+            problem("SHAPE", at, `${label}: a source is { version, url, archive (${SOURCE_ARCHIVE_FORMATS.join(" | ")}), ` +
+                `notices (non-empty list), entries, build? { cargo, inputs? } } and nothing else.`);
+            continue;
+        }
+        let valid = true;
+        if (!SOURCE_NAME_TOKEN.test(name)) {
+            problem("SOURCE_INVALID", `${at}`, `${label}: the name is not a canonical token. Use lowercase letters, digits, '.', '-' or ` +
+                `'_', starting with a letter or digit.`);
+            valid = false;
+        }
+        for (const key of ["version", "url"]) {
+            if (raw[key].trim() === "") {
+                problem("SOURCE_INVALID", `${at}.${key}`, `${label}: '${key}' must not be empty.`);
+                valid = false;
+            }
+        }
+        const url = raw.url;
+        for (const match of url.matchAll(/\{([^{}]*)\}/g)) {
+            if (URL_PLACEHOLDERS.has(match[1]))
+                continue;
+            problem("SOURCE_URL_PLACEHOLDER_UNKNOWN", `${at}.url`, `${label}: the url placeholder '{${match[1]}}' is not recognized. A url template may use ` +
+                `only {version} (the source's version) and {upstream} (each entry's upstream).`);
+            valid = false;
+        }
+        const insecure = url.trim() === "" ? undefined : sourceUrlProblem(url);
+        if (insecure) {
+            problem(insecure.code, `${at}.url`, `${label}: ${insecure.detail}`);
+            valid = false;
+        }
+        const notices = [];
+        raw.notices.forEach((notice, index) => {
+            const verdict = normalizeNativePath(notice.trim());
+            if ("path" in verdict) {
+                notices.push(verdict.path);
+                return;
+            }
+            problem("SOURCE_INVALID", `${at}.notices[${index}]`, `${label}: notice ${verdict.detail}`);
+            valid = false;
+        });
+        let readBuild;
+        if (isObject(build)) {
+            const written = build.cargo.trim();
+            const verdict = /^\.?\/?$/.test(written) ? { path: "" } : normalizeNativePath(written);
+            const inputs = ignorePins ? undefined : build.inputs;
+            if (!("path" in verdict)) {
+                problem("SOURCE_INVALID", `${at}.build.cargo`, verdict.kind === "escape"
+                    ? `${label}: build.cargo '${written}' is not a directory inside the module. Name the ` +
+                        `crate relative to the directory holding telo.yaml; code outside the module reaches ` +
+                        `its digest as a path dependency of that crate.`
+                    : `${label}: build.cargo '${written}' does not name one module-relative directory.`);
+                valid = false;
+            }
+            else if (inputs !== undefined && !INPUTS_DIGEST.test(inputs)) {
+                problem("SOURCE_INVALID", `${at}.build.inputs`, `${label}: build.inputs must be a digest of the form sha256-<43 base64url characters> — ` +
+                    `run \`telo release stage --pin\` to write it.`);
+                valid = false;
+            }
+            else {
+                readBuild = { cargo: verdict.path, ...(inputs !== undefined ? { inputs } : {}) };
+            }
+        }
+        const entries = [];
+        const rawEntries = raw.entries;
+        const entryPaths = new Map();
+        const links = [];
+        // Paths first, from every key, so a link to an entry with an unrelated
+        // problem is not also reported as unresolved.
+        const pathOfKey = new Map();
+        for (const key of Object.keys(rawEntries)) {
+            const entryAt = `${at}.entries.${key}`;
+            const verdict = normalizeNativePath(key.trim());
+            if (!("path" in verdict)) {
+                problem("SOURCE_ENTRY_INVALID", entryAt, `${label} entry '${key}': ${verdict.detail}`);
+                valid = false;
+                continue;
+            }
+            if (entryPaths.has(verdict.path)) {
+                problem("SOURCE_ENTRY_DUPLICATE", entryAt, `${label} entry '${key}': path '${verdict.path}' is also produced by entry ` +
+                    `'${entryPaths.get(verdict.path)}'.`);
+                valid = false;
+                continue;
+            }
+            entryPaths.set(verdict.path, key);
+            pathOfKey.set(key, verdict.path);
+        }
+        for (const [key, value] of Object.entries(rawEntries)) {
+            const entryAt = `${at}.entries.${key}`;
+            const entryLabel = `${label} entry '${key}'`;
+            const path = pathOfKey.get(key);
+            if (path === undefined)
+                continue;
+            if (!isObject(value)) {
+                problem("SHAPE", entryAt, `${entryLabel}: expected an object.`);
+                valid = false;
+                continue;
+            }
+            const fileKeys = FILE_KEYS.filter((k) => k in value);
+            const isLink = "target" in value;
+            if (isLink && fileKeys.length > 0) {
+                problem("SOURCE_ENTRY_INVALID", entryAt, `${entryLabel}: an entry is either a link (target) or a file (upstream, member, ` +
+                    `sha256, executable) — remove ${fileKeys.map((k) => `'${k}'`).join(", ")} or 'target'.`);
+                valid = false;
+                continue;
+            }
+            const strings = isLink ? ["target"] : ["upstream", "member"];
+            if (strings.some((k) => typeof value[k] !== "string") ||
+                (!ignorePins && "sha256" in value && typeof value.sha256 !== "string") ||
+                (!ignorePins && "executable" in value && typeof value.executable !== "boolean")) {
+                problem("SHAPE", entryAt, `${entryLabel}: expected a file or a link entry.`);
+                valid = false;
+                continue;
+            }
+            const blank = strings.filter((k) => value[k].trim() === "");
+            if (blank.length > 0) {
+                for (const k of blank) {
+                    problem("SOURCE_ENTRY_INVALID", `${entryAt}.${k}`, `${entryLabel}: '${k}' must not be empty.`);
+                }
+                valid = false;
+                continue;
+            }
+            if (isLink) {
+                links.push({ key, path, target: value.target });
+                continue;
+            }
+            const sha256 = ignorePins ? undefined : value.sha256;
+            const executable = ignorePins ? undefined : value.executable;
+            if (sha256 !== undefined && !SHA256_HEX.test(sha256)) {
+                problem("SOURCE_ENTRY_INVALID", `${entryAt}.sha256`, `${entryLabel}: sha256 must be 64 lowercase hex characters — run ` +
+                    `\`telo release stage --pin\` to write it.`);
+                valid = false;
+                continue;
+            }
+            if ((sha256 === undefined) !== (executable === undefined)) {
+                problem("SOURCE_ENTRY_INVALID", entryAt, `${entryLabel}: a pin is sha256 and executable together — run ` +
+                    `\`telo release stage --pin\` to write both.`);
+                valid = false;
+                continue;
+            }
+            entries.push({
+                kind: "file",
+                key,
+                path,
+                upstream: value.upstream,
+                member: value.member,
+                ...(sha256 !== undefined ? { pin: { sha256, executable: executable } } : {}),
+            });
+        }
+        const linkTargets = new Map();
+        for (const link of links) {
+            const resolved = resolveLinkTarget(link.path, link.target);
+            const targetAt = `${at}.entries.${link.key}.target`;
+            if (resolved === link.path) {
+                problem("SOURCE_LINK_CYCLE", targetAt, `${label} entry '${link.key}': link target '${link.target}' resolves to the link itself.`);
+                valid = false;
+                continue;
+            }
+            if (resolved === undefined || !entryPaths.has(resolved)) {
+                problem("SOURCE_LINK_TARGET_UNRESOLVED", targetAt, `${label} entry '${link.key}': link target '${link.target}' resolves, relative to the ` +
+                    `link's directory, to ${resolved === undefined ? "a path outside the module" : `'${resolved}'`}, ` +
+                    `which is not another entry of this source.`);
+                valid = false;
+                continue;
+            }
+            linkTargets.set(link.path, resolved);
+            entries.push({ kind: "link", key: link.key, path: link.path, target: link.target, resolved });
+        }
+        for (const link of links) {
+            if (!linkTargets.has(link.path))
+                continue;
+            const chain = [link.path];
+            for (let next = linkTargets.get(link.path); next !== undefined; next = linkTargets.get(next)) {
+                if (!chain.includes(next)) {
+                    chain.push(next);
+                    continue;
+                }
+                problem("SOURCE_LINK_CYCLE", `${at}.entries.${link.key}.target`, `${label} entry '${link.key}': the link never reaches a file — it cycles through ` +
+                    `${chain.map((p) => `'${p}'`).join(" → ")} → '${next}'. A link chain must end at a file entry.`);
+                valid = false;
+                break;
+            }
+        }
+        for (const entry of entries) {
+            const other = producers.get(entry.path);
+            if (other !== undefined) {
+                problem("SOURCE_ENTRY_DUPLICATE", `${at}.entries.${entry.key}`, `${label} entry '${entry.key}': path '${entry.path}' is also produced by source ` +
+                    `'${other.source}'. Each staged file has exactly one source.`);
+                valid = false;
+                continue;
+            }
+            for (const [path, producer] of producers) {
+                const relation = runsThrough(entry.path, path)
+                    ? `runs through '${path}' as a directory`
+                    : runsThrough(path, entry.path)
+                        ? `is a directory that '${path}' runs through`
+                        : undefined;
+                if (relation === undefined)
+                    continue;
+                problem("SOURCE_ENTRY_NESTED", `${at}.entries.${entry.key}`, `${label} entry '${entry.key}': path '${entry.path}' ${relation}, and source ` +
+                    `'${producer.source}' entry '${producer.key}' produces '${path}'. A staged path cannot ` +
+                    `be both a file and a directory — give each entry its own path.`);
+                valid = false;
+                break;
+            }
+            producers.set(entry.path, { source: name, key: entry.key });
+        }
+        if (!valid)
+            continue;
+        sources.push({
+            name,
+            version: raw.version,
+            url,
+            archive: raw.archive,
+            notices,
+            entries,
+            ...(readBuild !== undefined ? { build: readBuild } : {}),
+        });
+    }
+    return { sources, problems };
+}

package/dist/step-bodies.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A declaration's step bodies, found through its kind's step-body slots — the
+ * ONLY way a value is read as a step, never its shape. Shared by inline
+ * extraction and the scope-reach check, which must agree about where a step's
+ * dispatch target is.
+ *
+ * Browser-safe.
+ */
+/** One step body of one declaration. */
+export interface StepBody {
+    /** The field holding it (`steps`). */
+    field: string;
+    /** The field on each step naming what it dispatches (`invoke`). */
+    invokeField: string;
+    steps: unknown[];
+    /** The step item schema, local `$ref` resolved, which says how steps nest. */
+    itemSchema: Record<string, any> | undefined;
+}
+/** Every step body `declaration` holds, per its kind's author-facing `schema`. */
+export declare function stepBodiesOf(declaration: Record<string, unknown>, schema: Record<string, any>): StepBody[];
+/** Visit every step of a body at every nesting depth, with its concrete path
+ *  (`steps[1].then[0]`). */
+export declare function forEachStep(body: StepBody, schema: Record<string, any>, visit: (step: Record<string, any>, stepPath: string) => void): void;
+//# sourceMappingURL=step-bodies.d.ts.map

package/dist/step-bodies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-bodies.d.ts","sourceRoot":"","sources":["../src/step-bodies.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,wCAAwC;AACxC,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,QAAQ,EAAE,CAiBZ;AAED;4BAC4B;AAC5B,wBAAgB,WAAW,CACzB,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAC3D,IAAI,CAEN"}

package/dist/step-bodies.js

@@ -0,0 +1,28 @@
+import { gatherPropertySchemas, resolveLocalRef, walkStepArray } from "./schema-walk.js";
+import { readStepSlot } from "./step-slot.js";
+/** Every step body `declaration` holds, per its kind's author-facing `schema`. */
+export function stepBodiesOf(declaration, schema) {
+    const out = [];
+    const seen = new Set();
+    for (const [field, fieldSchema] of gatherPropertySchemas(schema)) {
+        const slot = readStepSlot(fieldSchema);
+        if (!slot || seen.has(field))
+            continue;
+        const steps = declaration[field];
+        if (!Array.isArray(steps))
+            continue;
+        seen.add(field);
+        out.push({
+            field,
+            invokeField: slot.invoke,
+            steps,
+            itemSchema: resolveLocalRef(fieldSchema.items, schema),
+        });
+    }
+    return out;
+}
+/** Visit every step of a body at every nesting depth, with its concrete path
+ *  (`steps[1].then[0]`). */
+export function forEachStep(body, schema, visit) {
+    walkStepArray(body.steps, body.itemSchema, schema, body.field, visit);
+}

package/dist/telo-version.d.ts

@@ -1,3 +1,3 @@
 /** The surface generation this analyzer implements. */
-export declare const TELO_SURFACE_VERSION = "0.89.0";
+export declare const TELO_SURFACE_VERSION = "0.90.0";
 //# sourceMappingURL=telo-version.d.ts.map

package/dist/telo-version.js

@@ -5,4 +5,4 @@
 // its release identity, this is the scale a module's `requires.telo` range is
 // written against, and every kernel in every language reports the same scale.
 /** The surface generation this analyzer implements. */
-export const TELO_SURFACE_VERSION = "0.89.0";
+export const TELO_SURFACE_VERSION = "0.90.0";

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;AAetF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AA2B3E,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;2DACuD;IACvD,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AA4CD,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,CA0EjC;AAyID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;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,CAgMrB;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,CAuBrB;AAqBD;;;sCAGsC;AACtC,wBAAgB,UAAU,CACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,OAAO,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAAG,SAAS,CAa3D;AAED;;;;;;;;;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"}
+{"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;AAetF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AA2B3E,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;2DACuD;IACvD,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AA4CD,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,CA0EjC;AAyID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;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,CAiMrB;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,CAuBrB;AAqBD;;;sCAGsC;AACtC,wBAAgB,UAAU,CACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,OAAO,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GAAG,SAAS,CAa3D;AAED;;;;;;;;;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"}

package/dist/validate-cel-context.js

@@ -423,8 +423,9 @@ export function resolveContextAnnotations(schema, manifestItem, opts) {
                 }
             }
         }
-        // Open fallback so unresolved types never produce false-positive CEL diagnostics.
-        return { type: "object", additionalProperties: true };
+        // Untyped (`dyn`) so an unresolved type never produces a false-positive CEL
+        // diagnostic; an open object would still type as `map` and refuse `acc + x`.
+        return {};
     }
     const refFrom = schema["x-telo-context-ref-from"];
     if (refFrom && allManifests) {

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

@@ -14,10 +14,12 @@ import { type AnalysisDiagnostic } from "./types.js";
  * selector (spec §1), which is what every module with two `js` controllers relies
  * on.
  *
- * 1. **Controller selector qualifiers.** `os` / `arch` / `libc` / `siblings` are
+ * 1. **Controller selector qualifiers.** The platform axes and `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.
+ *    instead of throwing from the loader later, and so is a combination no host
+ *    can match (`selectorContradictions`, shared with `native:` and
+ *    `exports.code:`).
  * 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

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

@@ -1 +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;AAUrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,EAAE,CAQ1F"}
+{"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;AAWrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,EAAE,CAQ1F"}