@telorun/analyzer 0.59.0 → 0.61.0

package/dist/release/fragment.js

@@ -0,0 +1,84 @@
+/**
+ * A release fragment — one pending change, written by an author.
+ *
+ * The shape is changesets' (one file, several modules, one body) carrying
+ * changie's kind vocabulary, which is what lets one cross-cutting change be one
+ * file while the kind still drives both the level and the changelog section a
+ * line lands under. Changie's own file is the other arrangement — one module per
+ * file — so a change touching five modules meant five files repeating one
+ * sentence, and its key was the module's bare directory NAME, which two
+ * directories in different subtrees can share.
+ *
+ * A fragment names modules by **workspace-relative path**, the same key the
+ * ledger and every diagnostic use.
+ *
+ * They are plain YAML validated here, not a `Telo.*` kind: build-time repo state
+ * with no controller and no capability, which the runtime never loads.
+ */
+import { Document, parseDocument } from "yaml";
+import { isFragmentKind } from "./bump-level.js";
+export class FragmentError extends Error {
+    source;
+    constructor(source, message) {
+        super(message);
+        this.source = source;
+    }
+}
+export function parseFragment(text, source) {
+    let value;
+    try {
+        value = parseDocument(text).toJSON();
+    }
+    catch (err) {
+        throw new FragmentError(source, `${source} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new FragmentError(source, `${source} must be a YAML mapping.`);
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (key !== "modules" && key !== "body") {
+            throw new FragmentError(source, `${source}: unknown field '${key}'. A fragment carries 'modules:' and 'body:'.`);
+        }
+    }
+    const rawModules = record.modules;
+    if (rawModules === null || typeof rawModules !== "object" || Array.isArray(rawModules)) {
+        throw new FragmentError(source, `${source}: 'modules' must be a mapping of module path to kind, ` +
+            `e.g. { modules/sql: Fixed }.`);
+    }
+    const modules = new Map();
+    for (const [key, kind] of Object.entries(rawModules)) {
+        if (!isFragmentKind(kind)) {
+            throw new FragmentError(source, `${source}: '${key}' declares kind '${String(kind)}', which is not a release kind. ` +
+                `Use Added, Changed, Deprecated, Removed, Fixed or Security.`);
+        }
+        modules.set(normalizeModuleKey(key), kind);
+    }
+    if (modules.size === 0) {
+        throw new FragmentError(source, `${source}: 'modules' is empty, so this fragment releases nothing. ` +
+            `Name at least one module by its workspace-relative path.`);
+    }
+    const body = record.body;
+    if (typeof body !== "string" || body.trim() === "") {
+        throw new FragmentError(source, `${source}: 'body' must be the changelog line for this change.`);
+    }
+    return { source, modules, body: body.trim() };
+}
+/**
+ * Render a fragment, for `telo release add`.
+ *
+ * Serialized rather than templated so a long body folds the way the YAML writer
+ * folds it, and so a module path needing quotes gets them.
+ */
+export function serializeFragment(modules, body) {
+    const doc = new Document({
+        modules: Object.fromEntries([...modules].map(([key, kind]) => [key, kind])),
+        body,
+    });
+    return doc.toString({ lineWidth: 88 });
+}
+/** Module keys are POSIX-separated and carry no leading `./` or trailing slash,
+ *  so the same directory written three ways is one key. */
+export function normalizeModuleKey(key) {
+    return key.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}

package/dist/release/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The release model: module identity, fragments, the ledger, the edge graph,
+ * level propagation and version planning.
+ *
+ * Browser-safe by construction — pure data in, plan out — so the telo editor can
+ * answer "what does changing this library bump?" from the same model the CLI
+ * releases from. Everything Node-shaped (finding the workspace, running the
+ * controller builder, building payloads, reading git, writing files) is
+ * `cli/nodejs/src/release/`.
+ */
+export { FRAGMENT_KINDS, FRAGMENT_KIND_ORDER, applyBump, compareVersions, isFragmentKind, isReleaseVersion, levelOfKind, maxLevel, } from "./bump-level.js";
+export type { BumpLevel, FragmentKind } from "./bump-level.js";
+export { CHANGELOG_HEADER, prependChangelogRelease, renderChangelogRelease, } from "./changelog.js";
+export type { ChangelogRelease } from "./changelog.js";
+export { FragmentError, normalizeModuleKey, parseFragment, serializeFragment } from "./fragment.js";
+export type { ModuleKey, ReleaseFragment } from "./fragment.js";
+export { EMPTY_LEDGER, LEDGER_PATH, LedgerError, parseLedger, serializeLedger } from "./ledger.js";
+export type { Ledger, LedgerEntry } from "./ledger.js";
+export { LOCALLY_DERIVED_LAYERS, MANIFEST_LAYER, diffLayerDigests, layerDigestKey, } from "./payload-digest.js";
+export type { LayerChange, LayerDigests } from "./payload-digest.js";
+export { orderByImports, planRelease } from "./release-plan.js";
+export type { ArtifactKind, BumpReason, ChangelogEntry, ModuleEvidence, PlannedModule, ReleaseDiagnostic, ReleaseEvidence, ReleasePlan, } from "./release-plan.js";
+export { VersionStampError, readManifestVersion, stampCrateVersion, stampManifestVersion, stampPackageVersion, } from "./version-stamp.js";
+export { WORKSPACE_FILENAME, WorkspaceConfigError, parseWorkspaceConfig } from "./workspace-config.js";
+export type { WorkspaceConfig } from "./workspace-config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/release/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/release/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,QAAQ,GACT,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/D,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACpG,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnG,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACvG,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/release/index.js

@@ -0,0 +1,18 @@
+/**
+ * The release model: module identity, fragments, the ledger, the edge graph,
+ * level propagation and version planning.
+ *
+ * Browser-safe by construction — pure data in, plan out — so the telo editor can
+ * answer "what does changing this library bump?" from the same model the CLI
+ * releases from. Everything Node-shaped (finding the workspace, running the
+ * controller builder, building payloads, reading git, writing files) is
+ * `cli/nodejs/src/release/`.
+ */
+export { FRAGMENT_KINDS, FRAGMENT_KIND_ORDER, applyBump, compareVersions, isFragmentKind, isReleaseVersion, levelOfKind, maxLevel, } from "./bump-level.js";
+export { CHANGELOG_HEADER, prependChangelogRelease, renderChangelogRelease, } from "./changelog.js";
+export { FragmentError, normalizeModuleKey, parseFragment, serializeFragment } from "./fragment.js";
+export { EMPTY_LEDGER, LEDGER_PATH, LedgerError, parseLedger, serializeLedger } from "./ledger.js";
+export { LOCALLY_DERIVED_LAYERS, MANIFEST_LAYER, diffLayerDigests, layerDigestKey, } from "./payload-digest.js";
+export { orderByImports, planRelease } from "./release-plan.js";
+export { VersionStampError, readManifestVersion, stampCrateVersion, stampManifestVersion, stampPackageVersion, } from "./version-stamp.js";
+export { WORKSPACE_FILENAME, WorkspaceConfigError, parseWorkspaceConfig } from "./workspace-config.js";

package/dist/release/ledger.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `.changes/ledger.yaml` — what each module looks like **as published**.
+ *
+ * It exists so a gate can answer "does my payload differ from what is published
+ * at my current version?" with no network call, no merge base and no
+ * credentials: a fork's PR runs the identical computation the release job runs.
+ * That is the load-bearing property — the PR gate and the publish gate compute
+ * the same number.
+ *
+ * **It is a cache, never the authority.** A committed digest can disagree with
+ * the registry — a hand edit, an `apply` whose publish then failed, a push made
+ * outside the pipeline — so `telo publish` still reads the registry, and
+ * `telo release verify` reconciles the two on demand. A *missing* entry is not
+ * drift: it means nothing is published, which is the correct reading for a
+ * module that has never shipped.
+ *
+ * **It records the registry base**, because canonicalizing a relative `imports:`
+ * source writes the destination into the manifest layer — so the digests below
+ * are digests *against that base*, and comparing them to digests taken against
+ * another one would be comparing two different artifacts.
+ */
+import { type ModuleKey } from "./fragment.js";
+import type { LayerDigests } from "./payload-digest.js";
+export declare const LEDGER_PATH = ".changes/ledger.yaml";
+export interface LedgerEntry {
+    /** The version these digests were taken at — the tag the artifact published
+     *  under. */
+    readonly version: string;
+    readonly layers: LayerDigests;
+}
+export interface Ledger {
+    /**
+     * The publish destination base the digests were taken against
+     * (`oci://ghcr.io/telorun`). Absent in a workspace that has published nothing
+     * yet, which is why it is optional rather than required — but a `check` that
+     * has entries and no base cannot reproduce them, and says so.
+     */
+    readonly registry?: string;
+    readonly modules: ReadonlyMap<ModuleKey, LedgerEntry>;
+}
+export declare class LedgerError extends Error {
+}
+export declare const EMPTY_LEDGER: Ledger;
+export declare function parseLedger(text: string, where: string): Ledger;
+/**
+ * Render the ledger.
+ *
+ * Keys are sorted so a release's ledger diff shows only the modules that moved
+ * — the file is committed and reviewed, and a map whose order followed insertion
+ * would reorder wholesale on every run.
+ */
+export declare function serializeLedger(ledger: Ledger): string;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/release/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/release/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,eAAO,MAAM,WAAW,yBAAyB,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B;iBACa;IACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,WAAW,MAAM;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;CACvD;AAED,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,eAAO,MAAM,YAAY,EAAE,MAA+B,CAAC;AAE3D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA+D/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAkBtD"}

package/dist/release/ledger.js

@@ -0,0 +1,109 @@
+/**
+ * `.changes/ledger.yaml` — what each module looks like **as published**.
+ *
+ * It exists so a gate can answer "does my payload differ from what is published
+ * at my current version?" with no network call, no merge base and no
+ * credentials: a fork's PR runs the identical computation the release job runs.
+ * That is the load-bearing property — the PR gate and the publish gate compute
+ * the same number.
+ *
+ * **It is a cache, never the authority.** A committed digest can disagree with
+ * the registry — a hand edit, an `apply` whose publish then failed, a push made
+ * outside the pipeline — so `telo publish` still reads the registry, and
+ * `telo release verify` reconciles the two on demand. A *missing* entry is not
+ * drift: it means nothing is published, which is the correct reading for a
+ * module that has never shipped.
+ *
+ * **It records the registry base**, because canonicalizing a relative `imports:`
+ * source writes the destination into the manifest layer — so the digests below
+ * are digests *against that base*, and comparing them to digests taken against
+ * another one would be comparing two different artifacts.
+ */
+import { Document, parseDocument } from "yaml";
+import { isReleaseVersion } from "./bump-level.js";
+import { normalizeModuleKey } from "./fragment.js";
+export const LEDGER_PATH = ".changes/ledger.yaml";
+export class LedgerError extends Error {
+}
+export const EMPTY_LEDGER = { modules: new Map() };
+export function parseLedger(text, where) {
+    let value;
+    try {
+        value = parseDocument(text).toJSON();
+    }
+    catch (err) {
+        throw new LedgerError(`${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (value === null)
+        return EMPTY_LEDGER;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new LedgerError(`${where} must be a YAML mapping.`);
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (key !== "registry" && key !== "modules") {
+            throw new LedgerError(`${where}: unknown field '${key}'. The ledger carries 'registry:' and 'modules:'.`);
+        }
+    }
+    const registry = record.registry;
+    if (registry !== undefined && typeof registry !== "string") {
+        throw new LedgerError(`${where}: 'registry' must be the publish destination base, as a string.`);
+    }
+    const rawModules = record.modules;
+    if (rawModules === undefined || rawModules === null)
+        return { ...(registry ? { registry } : {}), modules: new Map() };
+    if (typeof rawModules !== "object" || Array.isArray(rawModules)) {
+        throw new LedgerError(`${where}: 'modules' must be a mapping of module path to entry.`);
+    }
+    const modules = new Map();
+    for (const [key, raw] of Object.entries(rawModules)) {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new LedgerError(`${where}: entry '${key}' must be a mapping.`);
+        }
+        const entry = raw;
+        if (!isReleaseVersion(entry.version)) {
+            throw new LedgerError(`${where}: entry '${key}' has no major.minor.patch 'version'. The ledger records the ` +
+                `version each digest was taken at; without it the digest says nothing.`);
+        }
+        const layers = {};
+        const rawLayers = entry.layers;
+        if (rawLayers !== undefined && rawLayers !== null) {
+            if (typeof rawLayers !== "object" || Array.isArray(rawLayers)) {
+                throw new LedgerError(`${where}: entry '${key}' has a non-mapping 'layers'.`);
+            }
+            for (const [layer, digest] of Object.entries(rawLayers)) {
+                if (typeof digest !== "string") {
+                    throw new LedgerError(`${where}: entry '${key}' layer '${layer}' is not a digest string.`);
+                }
+                layers[layer] = digest;
+            }
+        }
+        modules.set(normalizeModuleKey(key), { version: entry.version, layers });
+    }
+    return { ...(registry ? { registry } : {}), modules };
+}
+/**
+ * Render the ledger.
+ *
+ * Keys are sorted so a release's ledger diff shows only the modules that moved
+ * — the file is committed and reviewed, and a map whose order followed insertion
+ * would reorder wholesale on every run.
+ */
+export function serializeLedger(ledger) {
+    const modules = {};
+    for (const key of [...ledger.modules.keys()].sort()) {
+        const entry = ledger.modules.get(key);
+        const layers = {};
+        for (const layer of Object.keys(entry.layers).sort())
+            layers[layer] = entry.layers[layer];
+        modules[key] = { version: entry.version, layers };
+    }
+    const doc = new Document({
+        ...(ledger.registry ? { registry: ledger.registry } : {}),
+        modules,
+    });
+    return ("# Generated by `telo release apply` — what each module looks like as published.\n" +
+        "# A cache of the registry's answer, so a PR gate needs no credentials.\n" +
+        "# `telo release verify` reconciles it against the registry.\n" +
+        doc.toString({ lineWidth: 0 }));
+}

package/dist/release/payload-digest.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A module's payload, reduced to one digest per layer — the exact answer to
+ * "did this module's artifact change?".
+ *
+ * It is exact because it is taken from the bytes: it fires for an inlined
+ * sibling's edit, for a shared-library fix, and for a transitive bump the
+ * lockfile alone moved, none of which touch a file under the module's own
+ * directory. No path-scoped rule and no declared-dependency graph can see any of
+ * them.
+ *
+ * The digest itself is `computeFilesIntegrity`, the same framing-independent
+ * content digest the published `layers:` index carries — which is what makes the
+ * ledger's recorded number and the registry's the same number, comparable
+ * without fetching a blob.
+ */
+import { type ArtifactSelector, type LayerRole } from "../artifact-selector.js";
+/** Per-layer integrity, keyed by `layerDigestKey`. */
+export type LayerDigests = Readonly<Record<string, string>>;
+/** The ledger key for the module's `telo.yaml` layer. */
+export declare const MANIFEST_LAYER = "manifest";
+/**
+ * Ledger keys the registry cannot answer for, and so the ones `telo release
+ * verify` reconciles nothing about and must preserve.
+ *
+ * Exactly one today, and for a structural reason rather than an omission: the
+ * published `layers:` index lives *inside* `telo.yaml`, so it cannot carry that
+ * file's own digest — the entry would have to be computed over bytes containing
+ * it. Nor can the digest be recovered by hashing what the registry serves, since
+ * the transport injects the index at push time and the published text is
+ * therefore not the text the payload builder produced.
+ *
+ * It stays in the ledger regardless, because it is the only thing that sees a
+ * **manifest-only change**: a schema edit, a new kind, a description, a
+ * dependency's version moving into a pin. None of those touch a controller byte,
+ * so without this key such a module would report no drift and its fix would ship
+ * to nobody — the exact failure the digest exists to prevent.
+ */
+export declare const LOCALLY_DERIVED_LAYERS: ReadonlySet<string>;
+/**
+ * A layer's identity within an artifact, as a stable, readable, YAML-plain key.
+ *
+ * A role alone is not the identity — there is one controller layer per selector
+ * — so a selector's axes join the key. Rendered as `controller/js` and
+ * `controller/napi+linux+amd64+gnu` rather than through `selectorKey`'s
+ * `axis=value;…` form, because this string is read by a human in a ledger diff
+ * and written into a plain YAML key; the axis order is `PLATFORM_AXES`, so the
+ * rendering is deterministic rather than dependent on how the selector was
+ * built.
+ */
+export declare function layerDigestKey(role: LayerRole | string, selector?: ArtifactSelector): string;
+/** A layer whose digest differs between two readings, or that exists in only
+ *  one of them. `before` / `after` are absent when the layer is absent there —
+ *  a payload that gained or lost a layer changed just as much as one whose
+ *  bytes moved. */
+export interface LayerChange {
+    readonly layer: string;
+    readonly before?: string;
+    readonly after?: string;
+}
+/** Every layer on which two readings disagree, in key order. Empty means the
+ *  payloads are byte-identical. */
+export declare function diffLayerDigests(before: LayerDigests, after: LayerDigests): LayerChange[];
+//# sourceMappingURL=payload-digest.d.ts.map

package/dist/release/payload-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-digest.d.ts","sourceRoot":"","sources":["../../src/release/payload-digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAiB,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE/F,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE5D,yDAAyD;AACzD,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAA6B,CAAC;AAErF;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAM5F;AAED;;;mBAGmB;AACnB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;mCACmC;AACnC,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,WAAW,EAAE,CAQzF"}

package/dist/release/payload-digest.js

@@ -0,0 +1,65 @@
+/**
+ * A module's payload, reduced to one digest per layer — the exact answer to
+ * "did this module's artifact change?".
+ *
+ * It is exact because it is taken from the bytes: it fires for an inlined
+ * sibling's edit, for a shared-library fix, and for a transitive bump the
+ * lockfile alone moved, none of which touch a file under the module's own
+ * directory. No path-scoped rule and no declared-dependency graph can see any of
+ * them.
+ *
+ * The digest itself is `computeFilesIntegrity`, the same framing-independent
+ * content digest the published `layers:` index carries — which is what makes the
+ * ledger's recorded number and the registry's the same number, comparable
+ * without fetching a blob.
+ */
+import { PLATFORM_AXES } from "../artifact-selector.js";
+/** The ledger key for the module's `telo.yaml` layer. */
+export const MANIFEST_LAYER = "manifest";
+/**
+ * Ledger keys the registry cannot answer for, and so the ones `telo release
+ * verify` reconciles nothing about and must preserve.
+ *
+ * Exactly one today, and for a structural reason rather than an omission: the
+ * published `layers:` index lives *inside* `telo.yaml`, so it cannot carry that
+ * file's own digest — the entry would have to be computed over bytes containing
+ * it. Nor can the digest be recovered by hashing what the registry serves, since
+ * the transport injects the index at push time and the published text is
+ * therefore not the text the payload builder produced.
+ *
+ * It stays in the ledger regardless, because it is the only thing that sees a
+ * **manifest-only change**: a schema edit, a new kind, a description, a
+ * dependency's version moving into a pin. None of those touch a controller byte,
+ * so without this key such a module would report no drift and its fix would ship
+ * to nobody — the exact failure the digest exists to prevent.
+ */
+export const LOCALLY_DERIVED_LAYERS = new Set([MANIFEST_LAYER]);
+/**
+ * A layer's identity within an artifact, as a stable, readable, YAML-plain key.
+ *
+ * A role alone is not the identity — there is one controller layer per selector
+ * — so a selector's axes join the key. Rendered as `controller/js` and
+ * `controller/napi+linux+amd64+gnu` rather than through `selectorKey`'s
+ * `axis=value;…` form, because this string is read by a human in a ledger diff
+ * and written into a plain YAML key; the axis order is `PLATFORM_AXES`, so the
+ * rendering is deterministic rather than dependent on how the selector was
+ * built.
+ */
+export function layerDigestKey(role, selector) {
+    if (!selector)
+        return role;
+    const parts = [selector.format, ...PLATFORM_AXES.map((axis) => selector[axis])].filter((value) => value !== undefined);
+    return `${role}/${parts.join("+")}`;
+}
+/** Every layer on which two readings disagree, in key order. Empty means the
+ *  payloads are byte-identical. */
+export function diffLayerDigests(before, after) {
+    const changes = [];
+    for (const layer of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+        const a = before[layer];
+        const b = after[layer];
+        if (a !== b)
+            changes.push({ layer, ...(a ? { before: a } : {}), ...(b ? { after: b } : {}) });
+    }
+    return changes;
+}

package/dist/release/release-plan.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Turning evidence into a release plan: which modules bump, to what, and why.
+ *
+ * Three questions, three mechanisms, and keeping them apart is the whole design:
+ *
+ * - **Whether** a module bumps is decided by the **payload digest** — exact,
+ *   from the bytes, so it sees an inlined sibling and a lockfile-only transitive
+ *   bump that no path-scoped rule can.
+ * - **At what level** is decided by the **edge graph** — a declared fragment is a
+ *   root, and a dependent mirrors its dependency's level, joined as the maximum
+ *   over paths, because a module that inlines a breaking change is breaking for
+ *   its own consumers.
+ * - **Whether a changelog line is requested** is decided by the path-scoped
+ *   changed-files rule, which used to decide the version. Demoted, its guesswork
+ *   costs one sentence rather than a spurious republish.
+ *
+ * The seam between digest and graph is *reported*, never papered over: a payload
+ * that moved with nothing to attribute it to — a third-party dependency, a
+ * changesets-owned package inlined into a module, a toolchain bump — resolves to
+ * `patch` and says so.
+ *
+ * Pure data in, plan out. Everything Node-shaped — building payloads, running
+ * the controller builder, reading git — is the CLI's half, so the editor can
+ * answer "what does changing this library bump?" from the same model.
+ */
+import { type BumpLevel, type FragmentKind } from "./bump-level.js";
+import type { ModuleKey, ReleaseFragment } from "./fragment.js";
+import type { Ledger } from "./ledger.js";
+import { type LayerChange, type LayerDigests } from "./payload-digest.js";
+/** What a module ships. A `Dockerfile` beside the manifest makes it an image
+ *  module; its absence, a registry artifact module. Derived rather than
+ *  declared, so discovery stays configuration-free. */
+export type ArtifactKind = "registry" | "image";
+export interface ModuleEvidence {
+    /** Workspace-relative directory path — the module's key everywhere. */
+    readonly key: ModuleKey;
+    /** `metadata.name`, for display only. */
+    readonly name: string;
+    /** `metadata.version` as it stands in the working copy. */
+    readonly version: string;
+    readonly artifactKind: ArtifactKind;
+    /** Per-layer integrity of the payload built from the working copy. */
+    readonly layers: LayerDigests;
+    /**
+     * Files this module's build inlined that belong to ANOTHER workspace module,
+     * grouped by owner. From the build's own metafile: a declared-dependency graph
+     * cannot see `--external`, so `@telorun/sdk` — declared by 54 modules, inlined
+     * by none — would otherwise bump the whole standard library on every SDK
+     * change.
+     */
+    readonly inlines: ReadonlyMap<ModuleKey, readonly string[]>;
+    /**
+     * Modules reached by an in-repo **relative** `imports:` source. A pinned
+     * registry ref is deliberately not an edge: pinning is the statement "I am not
+     * affected until I choose to be", and moving it is `telo upgrade`'s job.
+     */
+    readonly imports: readonly ModuleKey[];
+    /** Whether a file under this module's own directory that reaches the artifact
+     *  changed. Decides only whether a changelog line is requested. */
+    readonly ownFilesChanged: boolean;
+}
+export interface ReleaseEvidence {
+    readonly modules: readonly ModuleEvidence[];
+    readonly ledger: Ledger;
+    readonly fragments: readonly ReleaseFragment[];
+    /** The publish destination base the digests above were built against. */
+    readonly registry?: string;
+}
+/** Why a module is in the plan. A module usually carries several. */
+export type BumpReason = {
+    readonly kind: "declared";
+    readonly fragment: string;
+    readonly as: FragmentKind;
+} | {
+    readonly kind: "inlines";
+    readonly module: ModuleKey;
+    readonly files: readonly string[];
+} | {
+    readonly kind: "imports";
+    readonly module: ModuleKey;
+} | {
+    readonly kind: "unattributed";
+};
+export interface ChangelogEntry {
+    readonly kind: FragmentKind;
+    readonly body: string;
+    /** The fragment this line came from, so `apply` can report what it consumed. */
+    readonly fragment: string;
+}
+export interface PlannedModule {
+    readonly key: ModuleKey;
+    readonly name: string;
+    readonly from: string;
+    readonly to: string;
+    readonly level: BumpLevel;
+    readonly reasons: readonly BumpReason[];
+    /** Layers whose digest differs from the ledger's reading. Empty for a module
+     *  bumping purely because a dependency's version moves into its manifest. */
+    readonly changed: readonly LayerChange[];
+    readonly entries: readonly ChangelogEntry[];
+}
+export interface ReleaseDiagnostic {
+    readonly severity: "error" | "warning";
+    readonly code: string;
+    readonly message: string;
+}
+export interface ReleasePlan {
+    /** Bumping modules in dependency order — a dependency precedes its
+     *  dependents, which is also the order `telo publish` must push them. */
+    readonly modules: readonly PlannedModule[];
+    /** Fragments this plan consumes, for `apply` to delete. */
+    readonly fragments: readonly string[];
+    readonly diagnostics: readonly ReleaseDiagnostic[];
+}
+export declare function planRelease(evidence: ReleaseEvidence): ReleasePlan;
+/**
+ * Dependency order over in-repo imports — a dependency before its dependents.
+ *
+ * This is also the publish order, and it is not optional there: publishing
+ * canonicalizes a relative import and then hard-fails when the derived ref does
+ * not already resolve, so a sibling has to be pushed first.
+ *
+ * A cycle keeps its members in key order rather than throwing. A module graph
+ * should not have one, but a release is the wrong moment to discover it, and the
+ * ordering degrades to "arbitrary among the cycle" rather than to nothing.
+ */
+export declare function orderByImports(modules: readonly ModuleEvidence[]): ModuleEvidence[];
+//# sourceMappingURL=release-plan.d.ts.map

package/dist/release/release-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-plan.d.ts","sourceRoot":"","sources":["../../src/release/release-plan.ts"],"names":[],"mappings":"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"}