@telorun/analyzer 0.71.0 → 0.73.0

package/src/deprecation.ts

@@ -0,0 +1,36 @@
+/**
+ * `metadata.deprecated` — the annotation's single reader.
+ *
+ * Structural validity belongs to `validate-module-metadata.ts` (the strict half,
+ * the `ref-slot.ts` split). This side is deliberately lenient: it reads a
+ * well-formed block and treats everything else as absent, so a malformed
+ * declaration in a published dependency never becomes a warning at a consumer's
+ * use site. The consumer can fix neither one, and reporting the second blames
+ * the wrong author.
+ */
+
+/** A deprecation as declared: why, and optionally what to use instead. */
+export interface Deprecation {
+  /** What a consumer reads to know what to do instead. Always non-empty. */
+  reason: string;
+  /** Alias-qualified kind (kind docs) or module ref (module docs), **as written
+   *  in the declaring file's own scope** — `Self.Thing` means nothing to a
+   *  consumer, so a use site resolves it before quoting it. */
+  replacedBy?: string;
+}
+
+export function readDeprecation(metadata: unknown): Deprecation | undefined {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) return undefined;
+  const block = (metadata as Record<string, unknown>).deprecated;
+  if (block === null || typeof block !== "object" || Array.isArray(block)) return undefined;
+
+  const { reason, replacedBy } = block as Record<string, unknown>;
+  if (typeof reason !== "string" || reason.trim() === "") return undefined;
+
+  return {
+    reason: reason.trim(),
+    ...(typeof replacedBy === "string" && replacedBy.trim() !== ""
+      ? { replacedBy: replacedBy.trim() }
+      : {}),
+  };
+}

package/src/eval-paths.ts

@@ -186,6 +186,36 @@ export function celEvalSites(schema: Record<string, any> | undefined): CelEvalSi
   return { compile, runtime, regions: extractCelRegionScopes(schema) };
 }
 
+/**
+ * A BASE-FORM CHILD'S OWN FIELDS ARE COMPILE-EVAL WITHOUT ANNOTATION.
+ *
+ * A definition with `base:` has no controller of its own: the kernel evaluates
+ * the mapping once, at `create()`, against `self` — the instance's config — and
+ * hands the result to the inherited controller as the parent's config. The
+ * child's own schema fields never reach a controller; they exist to be read by
+ * `base:`, and the mapping expands whatever compiled value it reads. So every
+ * own field is evaluated exactly once at creation against the startup scope,
+ * which is what compile-eval IS. Declared here as the rule rather than left as a
+ * property of the mapping walk — the `Telo.Provider` posture, where a
+ * construction-time-only surface declares compile-eval once for all its fields
+ * rather than per field. Without it the rule was off for every inheritance kind
+ * (its capability is inherited, so the gate read `undefined`) and the
+ * expressions were never typed either: a `!cel "variables.whoo"` passed `telo
+ * check` and failed at boot.
+ *
+ * Read by the kernel's instance production and the analyzer's coverage decision,
+ * so the two cannot disagree about which fields a base child evaluates. An
+ * explicitly `runtime` own field still wins, through the same overlap rule a
+ * root `x-telo-eval: compile` follows.
+ */
+export const IMPLICIT_COMPILE_SITES: CelEvalSites = { compile: ["**"], runtime: [], regions: [] };
+
+export function implicitEvalSites(
+  definition: { base?: unknown } | undefined,
+): CelEvalSites {
+  return definition?.base != null ? IMPLICIT_COMPILE_SITES : NO_CEL_EVAL_SITES;
+}
+
 /** The union of several schemas' sites — a kind's own and its capability
  *  abstract's, which is how a `Telo.Provider`'s implicit compile-eval reaches
  *  fields the provider never annotated. */
@@ -201,11 +231,16 @@ export function mergeCelEvalSites(...sites: CelEvalSites[]): CelEvalSites {
  * Whether the value at `path` is evaluated, and when — null for a field whose
  * value is read as a literal.
  *
- * `compile` wins over `runtime`, and both win over a region: a field's own
- * annotation is more specific than the region it sits in, which is the same
- * precedence a nested annotation has over an enclosing one. A region resolves to
- * `runtime` because that is what a region IS — a per-invocation scope naming
- * what its expressions can read.
+ * An annotated field wins over the region it sits in — a field's own annotation
+ * is more specific than an enclosing one, and a region resolves to `runtime`
+ * because that is what a region IS, a per-invocation scope naming what its
+ * expressions can read. Between the two annotations, `runtime` wins wherever
+ * they OVERLAP and `compile` answers everywhere else.
+ *
+ * That overlap rule is the kernel's, read back: its compile expansion skips any
+ * compile path a runtime path contains or is contained by, and under a root
+ * `**` it skips per top-level key — so a runtime-annotated field under an
+ * implicit compile root stays runtime, here as at dispatch.
  *
  * `path` is the `walkCelExpressions` spelling (`routes[0].returns[1].when`).
  */
@@ -213,8 +248,20 @@ export function celEvalModeAt(
   sites: CelEvalSites,
   path: string,
 ): "compile" | "runtime" | null {
-  if (evalPathsCover(sites.compile, path)) return "compile";
+  const compiled = sites.compile.some((p) => {
+    if (!evalPathCovers(p, path)) return false;
+    const effective = p === "**" ? topLevelKey(path) : p;
+    return !sites.runtime.some(
+      (rp) => evalPathCovers(rp, effective) || evalPathCovers(effective, rp),
+    );
+  });
+  if (compiled) return "compile";
   if (evalPathsCover(sites.runtime, path)) return "runtime";
   if (sites.regions.some((scope) => pathMatchesScope(path, scope))) return "runtime";
   return null;
 }
+
+function topLevelKey(path: string): string {
+  const end = path.search(/[.[]/);
+  return end === -1 ? path : path.slice(0, end);
+}

package/src/extends-resolution.ts

@@ -137,6 +137,30 @@ export function effectiveAuthorSchema(
   return mergeTypeSchemas([parentSchema, own]) as Record<string, any>;
 }
 
+/**
+ * The parent's required fields that a merge-form child leaves on its OWN author
+ * surface — inherited by the rule above, and not redeclared by the child.
+ *
+ * The one fact behind a confusing diagnostic: a kind written to wire a field
+ * internally still demands it from its consumer, because without `base:` the
+ * child is authored against merge(parent, own) and the parent's `required` comes
+ * along. Empty for a child with `base:` (its surface is its own schema) and for
+ * a kind that extends nothing, so a caller can use a non-empty result as the
+ * condition itself.
+ */
+export function inheritedRequiredFields(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): string[] {
+  if (!body(def).extends || body(def).base) return [];
+  const parent = resolveParent(def, resolve);
+  if (!parent) return [];
+  const required = effectiveAuthorSchema(parent, resolve).required;
+  if (!Array.isArray(required)) return [];
+  const own = ((body(def).schema ?? {}).properties ?? {}) as Record<string, unknown>;
+  return required.filter((f): f is string => typeof f === "string" && !(f in own));
+}
+
 /**
  * The fields a merge-form inheriting child publishes over its parent's reading.
  *

package/src/index.ts

@@ -33,6 +33,7 @@ export {
   celEvalSites,
   declaresCelRegion,
   evalPathCovers,
+  implicitEvalSites,
   mergeCelEvalSites,
   pathMatchesScope,
   NO_CEL_EVAL_SITES,
@@ -185,6 +186,8 @@ export {
 export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
 export { isStepSlot, readStepSlot, STEP_FRAGMENT } from "./step-slot.js";
 export type { StepSlot } from "./step-slot.js";
+export { readDeprecation } from "./deprecation.js";
+export type { Deprecation } from "./deprecation.js";
 export {
   ANNOTATION_KEYWORDS,
   registerTeloKeywords,
@@ -489,7 +492,12 @@ export type { CelScopeQueryContext, ContextDeclarationSite } from "./cel-scope-q
 export { navigateConcretePath } from "./manifest-path.js";
 export { ManifestAnalysis } from "./manifest-analysis.js";
 export type { ManifestRef } from "./manifest-analysis.js";
-export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
+export {
+  DEFAULT_MANIFEST_FILENAME,
+  DiagnosticSeverity,
+  DiagnosticTag,
+  diagnosticFix,
+} from "./types.js";
 export type {
     AnalysisDiagnostic,
     AnalysisOptions,

package/src/manifest-visitor.ts

@@ -66,8 +66,21 @@ export interface ScopeBoundaryEvent {
   source: ResourceManifest;
   /** Dot-form prefixes of every `x-telo-scope` field on this resource. */
   scopePrefixes: string[];
-  /** Scope-field JSON Pointer → manifests declared within that scope. */
+  /** VISIBILITY pointer (an `x-telo-scope` entry, e.g. `/steps`) → the manifests
+   *  visible there. Keyed by where scoped names may be REFERENCED, which is not
+   *  where they are DECLARED: `Run.Sequence` declares `x-telo-scope:
+   *  ["/steps", "/targets"]` on its `with:` field, so one declaration appears
+   *  under two keys and neither names `with`. Use {@link declarations} for the
+   *  declaration site. */
   manifestsByPointer: Map<string, ResourceManifest[]>;
+  /** Every inline declaration inside this resource's scopes, ONCE each, with the
+   *  concrete path it is written at in the owner's document (`with[0]`).
+   *
+   *  A diagnostic about a scoped resource has to anchor there: the resource is
+   *  not a top-level document, so position lookup finds the OWNER and then walks
+   *  this path into it. Deriving one from a visibility pointer instead names a
+   *  region the declaration is not in (`steps[0]`). */
+  declarations: { manifest: ResourceManifest; path: string }[];
   /** Names of every resource declared inside this resource's scopes. Used by
    *  the dependency graph to drop boot edges to scoped (on-demand) targets. */
   enclosedNames: Set<string>;
@@ -271,6 +284,7 @@ export function visitManifest(
       if (refScopeMap && (wantsRefs || wantsScope)) {
         const manifestsByPointer = new Map<string, ResourceManifest[]>();
         const scopeRefEntries: { path: string; refName: string }[] = [];
+        const declarations: { manifest: ResourceManifest; path: string }[] = [];
         for (const [fieldPath, entry] of refScopeMap) {
           if (!isScopeEntry(entry)) continue;
           const raw: ResourceManifest[] = [];
@@ -278,6 +292,7 @@ export function visitManifest(
             const items = Array.isArray(fe.value) ? fe.value : [fe.value];
             items.forEach((v, i) => {
               if (!v || typeof v !== "object") return;
+              const declarationPath = Array.isArray(fe.value) ? `${fe.path}[${i}]` : fe.path;
               // A scope entry must be an inline resource definition; a `!ref`
               // (tagged sentinel or resolved `{kind, name}`) is not — record it
               // so a static diagnostic flags it instead of registering a
@@ -288,12 +303,13 @@ export function visitManifest(
                 (typeof rec.kind === "string" && typeof rec.name === "string")
               ) {
                 scopeRefEntries.push({
-                  path: Array.isArray(fe.value) ? `${fe.path}[${i}]` : fe.path,
+                  path: declarationPath,
                   refName: isRefSentinel(v) ? v.source : String(rec.name),
                 });
                 return;
               }
               raw.push(v as ResourceManifest);
+              declarations.push({ manifest: v as ResourceManifest, path: declarationPath });
             });
           }
           const pointers = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
@@ -313,6 +329,7 @@ export function visitManifest(
             source: r,
             scopePrefixes,
             manifestsByPointer,
+            declarations,
             enclosedNames,
             scopeRefEntries,
           });

package/src/migrations/report.ts

@@ -21,7 +21,7 @@ import type {
   MigrationPath,
   MigrationRewrite,
 } from "./types.js";
-import type { AnalysisDiagnostic, DiagnosticFix } from "../types.js";
+import { DiagnosticTag, type AnalysisDiagnostic, type DiagnosticFix } from "../types.js";
 
 /** One patch that applied, as the reporting side needs to see it. */
 export interface AppliedPatch {
@@ -63,6 +63,10 @@ export function toDiagnostic(
     severity: applied.entry.severity,
     code: applied.entry.code,
     source: "telo-analyzer",
+    // A migration IS a deprecation — a legacy spelling still read, and the one
+    // an author is being asked to stop writing — so the range carries the tag
+    // whatever severity the entry chose for itself.
+    tags: [DiagnosticTag.Deprecated],
     message: `${rewrite.summary}\n${applied.entry.reason}\n${closing}`,
     data: {
       filePath: source,

package/src/nearest-name.ts

@@ -0,0 +1,47 @@
+import { distance } from "./levenshtein.js";
+
+/**
+ * THE closest candidate to a misspelled name, or undefined.
+ *
+ * One rule, because a suggestion here is emitted as a `DiagnosticFix` — a
+ * whole-value replacement an editor applies in one click — so "closest" has to
+ * mean the same thing wherever it is offered. Two properties carry that:
+ *
+ *  - **A TIE returns undefined.** Two candidates at equal distance make the pick
+ *    arbitrary, and an arbitrary pick that is one click from being applied is
+ *    worse than no suggestion: it resolves by whatever order the candidate set
+ *    happened to be built in, which is a `Set`'s insertion order.
+ *  - **The threshold scales but is CAPPED** (`min(3, len/3)`, and nothing under
+ *    1). Without the cap a long name accepts a distant match; without the floor
+ *    a two-character name gets a "correction" sharing nothing with it.
+ *
+ * Both are `computeSuggestKind`'s rule, lifted here so the kind-suggestion, the
+ * template-body and the export checks cannot drift into three answers — which
+ * they had, two of them byte-identical copies differing from this one in both
+ * properties.
+ */
+export function nearestName(
+  target: string,
+  candidates: Iterable<string>,
+): string | undefined {
+  if (!target) return undefined;
+  const threshold = Math.min(3, Math.floor(target.length / 3));
+  if (threshold < 1) return undefined;
+
+  let best: string | undefined;
+  let bestDist = threshold + 1;
+  let tied = false;
+
+  for (const candidate of candidates) {
+    const d = distance(target, candidate);
+    if (d < bestDist) {
+      best = candidate;
+      bestDist = d;
+      tied = false;
+    } else if (d === bestDist) {
+      tied = true;
+    }
+  }
+
+  return !best || bestDist > threshold || tied ? undefined : best;
+}

package/src/ref-slot.ts

@@ -94,6 +94,21 @@ export interface RefSlot {
    *  that carries this call's arguments. Replaces
    *  `x-telo-topology-role: inputs`. */
   inputs?: string;
+  /** Throws raised by the target — or by anything the target drives — surface
+   *  through the DECLARING resource, so its own throws union includes the
+   *  target's and its catch scope encloses the target's.
+   *
+   *  It exists because the relation is real where `use` correctly says nothing:
+   *  `Http.Server.mounts[].mount` is a `dependency` (the server holds the mount
+   *  and calls a convention method on it — control reaches a route through the
+   *  MOUNT's own `trigger.inbound` slot, not through this one), yet a throw from
+   *  that route is exactly what the server renders. Following every `dependency`
+   *  edge instead would drag a connection's throws into a router's denominator.
+   *
+   *  Declared by the kind that HOLDS, because only it knows the throws surface
+   *  through it, and it is the same fact its runtime establishes by rethrowing —
+   *  so the annotation and the behaviour cannot disagree. */
+  throwsThrough?: boolean;
   /** `x-telo-inline: true` on the slot or any `anyOf` branch — accepts an inline
    *  `{kind, ...config}` definition, not only a `!ref`. */
   inline: boolean;
@@ -228,6 +243,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
   const uses = new Set<RefUse>();
   let useCases: RefUseCases | undefined;
   let inputs: string | undefined;
+  let throwsThrough = false;
 
   for (const carrier of nodes) {
     const annotation = carrier["x-telo-ref"];
@@ -239,6 +255,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
     for (const use of normalizeUses(obj.use)) uses.add(use);
     useCases ??= readUseCases(obj.use);
     if (typeof obj.inputs === "string") inputs ??= obj.inputs;
+    if (obj.throwsThrough === true) throwsThrough = true;
   }
 
   const slot: RefSlot = {
@@ -249,6 +266,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
   };
   if (useCases) slot.useCases = useCases;
   if (inputs !== undefined) slot.inputs = inputs;
+  if (throwsThrough) slot.throwsThrough = true;
   return slot;
 }
 
@@ -274,6 +292,7 @@ export function refSlotAnnotation(slot: RefSlot): Record<string, unknown> {
   else if (slot.uses.length === 1) annotation.use = slot.uses[0];
   else if (slot.uses.length > 1) annotation.use = slot.uses;
   if (slot.inputs !== undefined) annotation.inputs = slot.inputs;
+  if (slot.throwsThrough) annotation.throwsThrough = true;
   return annotation;
 }
 

package/src/release/destinations.ts

@@ -0,0 +1,105 @@
+/**
+ * Where each module publishes, and the two ways a set of destinations can be
+ * inconsistent.
+ *
+ * A destination is the module's resolved registry base plus its own directory
+ * name. That rule held silently for as long as every module sat at one depth
+ * under one base with a unique directory name; per-subtree bases remove that
+ * coincidence, so both failures it was hiding become reachable and are checked
+ * here — **at plan time, before any payload is built**, because the payload
+ * builder's own refusal speaks about a manifest published to two places rather
+ * than about the workspace file that said so.
+ *
+ * Pure data in, diagnostics out: the destinations are already computed for
+ * `telo release order`, so one derivation feeds that payload and both checks.
+ */
+
+import type { ModuleKey } from "./fragment.js";
+import type { ReleaseDiagnostic } from "./release-plan.js";
+
+export interface ModuleDestination {
+  readonly key: ModuleKey;
+  /** `<registry>/<the module's own directory name>`. */
+  readonly destination: string;
+}
+
+/**
+ * A relative import between two workspace modules, with both answers about
+ * where the target publishes.
+ *
+ * `derived` is what the importer's own destination yields when the import path
+ * is applied to it — the transport's rule, and what ref canonicalization writes
+ * into the published manifest. `assigned` is what discovery independently gives
+ * that module.
+ */
+export interface ImportDestination {
+  readonly from: ModuleKey;
+  readonly to: ModuleKey;
+  readonly derived: string;
+  readonly assigned: string;
+}
+
+/**
+ * Two modules must not resolve to one ref.
+ *
+ * Nothing else catches it: the payload builder is keyed by manifest, so it sees
+ * one module claimed by two destinations and never two modules claiming one,
+ * while the ledger keys by module — both entries would record digests for a
+ * single published artifact and reconciliation could never settle.
+ */
+export function checkDestinationCollisions(
+  destinations: readonly ModuleDestination[],
+): ReleaseDiagnostic[] {
+  const byDestination = new Map<string, ModuleKey[]>();
+  for (const { key, destination } of destinations) {
+    const sharing = byDestination.get(destination);
+    if (sharing) sharing.push(key);
+    else byDestination.set(destination, [key]);
+  }
+
+  const diagnostics: ReleaseDiagnostic[] = [];
+  for (const [destination, keys] of byDestination) {
+    if (keys.length < 2) continue;
+    diagnostics.push({
+      severity: "error",
+      code: "DESTINATION_COLLISION",
+      message:
+        `${keys.sort().join(" and ")} both publish to '${destination}'. A module's ref is its ` +
+        `registry base plus its own directory name, so they would overwrite one artifact and ` +
+        `their ledger entries could never reconcile. Rename one directory, or give one of the ` +
+        `subtrees its own 'registry:' in telo-workspace.yaml.`,
+    });
+  }
+  return diagnostics;
+}
+
+/**
+ * A relative import is valid only where the importer's derived ref for its
+ * target equals the destination that module is independently assigned.
+ *
+ * Equal registries are necessary and not sufficient — two modules under one base
+ * at different directory depths derive differently too. Making the builder take
+ * the assigned destination instead is not the fix: it would put a ref in the
+ * artifact that the transport's resolution rule does not produce, so the
+ * manifest would say one thing and every consumer resolving relatively would
+ * compute another.
+ */
+export function checkImportDestinations(
+  edges: readonly ImportDestination[],
+): ReleaseDiagnostic[] {
+  const diagnostics: ReleaseDiagnostic[] = [];
+  for (const edge of edges) {
+    if (edge.derived === edge.assigned) continue;
+    diagnostics.push({
+      severity: "error",
+      code: "IMPORT_DESTINATION_CONFLICT",
+      message:
+        `${edge.from} imports ${edge.to} by relative path, which canonicalizes to ` +
+        `'${edge.derived}' — but ${edge.to} publishes to '${edge.assigned}'. Publishing rewrites ` +
+        `the import to the ref its own path yields, so the artifact would name a module nobody ` +
+        `pushes. Give the two the same registry base and the same directory depth, or make it a ` +
+        `pinned remote import, which is what a dependency across a publish boundary is.`,
+    });
+  }
+  return diagnostics;
+}

package/src/release/index.ts

@@ -63,5 +63,36 @@ export {
   stampPackageVersion,
 } from "./version-stamp.js";
 
-export { WORKSPACE_FILENAME, WorkspaceConfigError, parseWorkspaceConfig } from "./workspace-config.js";
-export type { WorkspaceConfig } from "./workspace-config.js";
+export { checkDestinationCollisions, checkImportDestinations } from "./destinations.js";
+export type { ImportDestination, ModuleDestination } from "./destinations.js";
+
+export {
+  DEFAULT_ENV_FILES,
+  DEFAULT_RELEASE_IGNORE,
+  WORKSPACE_FILENAME,
+  WorkspaceConfigError,
+  diagnosticsFor,
+  hasError,
+  matchesPatterns,
+  readWorkspaceConfig,
+  requireReleaseSettings,
+  settingsForModule,
+} from "./workspace-config.js";
+export type {
+  EnvSettings,
+  ModuleEntry,
+  ModuleSettings,
+  PatternMatch,
+  ReleaseSettings,
+  WorkspaceConfig,
+  WorkspaceDiagnostic,
+  WorkspaceDiagnosticCode,
+  WorkspaceRead,
+} from "./workspace-config.js";
+
+export {
+  MODULE_ENTRY_KEYS,
+  WORKSPACE_BLOCKS,
+  WORKSPACE_SCHEMA,
+} from "./workspace-schema.js";
+export type { WorkspaceBlockSchema, WorkspaceKeySchema } from "./workspace-schema.js";

package/src/release/ledger.ts

@@ -14,10 +14,22 @@
  * 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.
+ * **Every entry records its own registry base**, because canonicalizing a
+ * relative `imports:` source writes the destination into the manifest layer — so
+ * each digest is a digest *against that base*, and comparing it to one taken
+ * against another would be comparing two different artifacts.
+ *
+ * Per entry rather than one top-level base with per-entry deltas: a workspace
+ * whose `release.modules` entries each author a destination has no meaningful
+ * top-level base, an absent one already means *nothing has been published yet*,
+ * and the agreement check returns early on that — so the multi-destination
+ * workspace would be the one whose bases are never compared. The file is
+ * generated and never hand-maintained, so the redundancy costs nothing and it
+ * removes the "differs from what?" question and the absent-versus-unknown
+ * conflation together. A **top-level `registry:` is a legacy form the reader
+ * accepts and never writes**, applied to every entry: the credential-free PR
+ * gate reads whatever ledger is committed on the branch, and that stays in the
+ * old shape until a release regenerates it.
  */
 
 import { Document, parseDocument } from "yaml";
@@ -31,17 +43,14 @@ export interface LedgerEntry {
   /** The version these digests were taken at — the tag the artifact published
    *  under. */
   readonly version: string;
+  /** The publish destination base these digests were taken against
+   *  (`oci://ghcr.io/telorun`). Absent only in a ledger written before the base
+   *  was recorded at all. */
+  readonly registry?: 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>;
 }
 
@@ -72,13 +81,14 @@ export function parseLedger(text: string, where: string): Ledger {
     }
   }
 
-  const registry = record.registry;
-  if (registry !== undefined && typeof registry !== "string") {
+  // The legacy top-level base: read and applied to every entry, never written.
+  const inherited = record.registry;
+  if (inherited !== undefined && typeof inherited !== "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 (rawModules === undefined || rawModules === null) return { modules: new Map() };
   if (typeof rawModules !== "object" || Array.isArray(rawModules)) {
     throw new LedgerError(`${where}: 'modules' must be a mapping of module path to entry.`);
   }
@@ -89,6 +99,20 @@ export function parseLedger(text: string, where: string): Ledger {
       throw new LedgerError(`${where}: entry '${key}' must be a mapping.`);
     }
     const entry = raw as Record<string, unknown>;
+    for (const field of Object.keys(entry)) {
+      if (field !== "version" && field !== "registry" && field !== "layers") {
+        throw new LedgerError(
+          `${where}: entry '${key}' has unknown field '${field}'. An entry carries 'version:', ` +
+            `'registry:' and 'layers:'.`,
+        );
+      }
+    }
+    if (entry.registry !== undefined && typeof entry.registry !== "string") {
+      throw new LedgerError(
+        `${where}: entry '${key}' has a non-string 'registry'. It is the publish destination base ` +
+          `the digests beside it were taken against.`,
+      );
+    }
     if (!isReleaseVersion(entry.version)) {
       throw new LedgerError(
         `${where}: entry '${key}' has no major.minor.patch 'version'. The ledger records the ` +
@@ -108,10 +132,15 @@ export function parseLedger(text: string, where: string): Ledger {
         layers[layer] = digest;
       }
     }
-    modules.set(normalizeModuleKey(key), { version: entry.version, layers });
+    const registry = (entry.registry as string | undefined) ?? inherited;
+    modules.set(normalizeModuleKey(key), {
+      version: entry.version,
+      ...(registry ? { registry } : {}),
+      layers,
+    });
   }
 
-  return { ...(registry ? { registry } : {}), modules };
+  return { modules };
 }
 
 /**
@@ -127,12 +156,13 @@ export function serializeLedger(ledger: Ledger): string {
     const entry = ledger.modules.get(key)!;
     const layers: Record<string, string> = {};
     for (const layer of Object.keys(entry.layers).sort()) layers[layer] = entry.layers[layer];
-    modules[key] = { version: entry.version, layers };
+    modules[key] = {
+      version: entry.version,
+      ...(entry.registry ? { registry: entry.registry } : {}),
+      layers,
+    };
   }
-  const doc = new Document({
-    ...(ledger.registry ? { registry: ledger.registry } : {}),
-    modules,
-  });
+  const doc = new Document({ 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" +