@telorun/analyzer 0.72.0 → 0.74.0

package/src/reference-field-map.ts

@@ -1,4 +1,6 @@
+import { resolveLocalRef } from "./manifest-navigation.js";
 import { type RefSlot, type RefUse, type RefUseCases, readRefSlot } from "./ref-slot.js";
+import { readStepSlot, type StepSlot } from "./step-slot.js";
 
 export { readRefSlot, isRefSlot, hasDeclaredUse } from "./ref-slot.js";
 export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
@@ -38,6 +40,53 @@ export interface RefFieldEntry {
    *  an unconditional opt-in would rewrite the value into a valid shape before
    *  the schema ever saw it. */
   inline?: boolean;
+  /** See {@link RefSlot.throwsThrough}. */
+  throwsThrough?: boolean;
+}
+
+/** The slot an entry records, as `readRefSlot` read it. */
+export function refSlotOfEntry(entry: RefFieldEntry): RefSlot {
+  const slot: RefSlot = {
+    kinds: entry.refs,
+    uses: entry.uses,
+    inline: entry.inline === true,
+    valueBranches: entry.valueBranches ?? [],
+  };
+  if (entry.useCases) slot.useCases = entry.useCases;
+  if (entry.inputs !== undefined) slot.inputs = entry.inputs;
+  if (entry.throwsThrough) slot.throwsThrough = true;
+  return slot;
+}
+
+/** Everything a driven-slot map records at one field path. */
+export interface DrivenPath {
+  /** Every reference slot declared here, by any branch. Kept apart rather than
+   *  merged into one slot and read as a union: a branch that does not apply to a
+   *  resource can only ADD what counts — more coverage demanded, never less — and
+   *  one merged slot could not hold two case-map selectors or a branch that
+   *  declares no use. */
+  refs: RefFieldEntry[];
+  /** Every step body declared here, by any branch. */
+  steps: StepSlot[];
+  /** Back-edges of a recursive schema: the schema here is also the one entered
+   *  at each of these paths, so everything below them applies again below this
+   *  one, as deep as a resource's data goes. Recorded BESIDE `refs`, never in
+   *  place of them — a `!ref` here resolves as a reference, an inline object
+   *  recurses. */
+  recurse: string[];
+}
+
+/** See {@link buildDrivenSlotMap}. */
+export interface DrivenSlots {
+  paths: Map<string, DrivenPath>;
+  /** Per `{}` field path, the keys JSON Schema does NOT apply that
+   *  `additionalProperties` to: those the same schema declares under
+   *  `properties`, plus the resource envelope at the root. Where several schemas
+   *  meet at one `{}` path, only keys every one of them declares are skipped. */
+  declaredKeys: Map<string, Set<string>>;
+  /** True when some path holds a step or reference slot. A map of back-edges
+   *  alone drives nothing, so a walk over it is skipped. */
+  drives: boolean;
 }
 
 /** An entry for a field that declares an execution scope (x-telo-scope). */
@@ -207,9 +256,10 @@ export function resolveFieldValues(obj: unknown, path: string): unknown[] {
  */
 export function buildReferenceFieldMap(schema: Record<string, any>): ReferenceFieldMap {
   const map: ReferenceFieldMap = new Map();
+  const sink = injectionSink(map);
   if (schema.properties) {
     for (const [key, propSchema] of Object.entries(schema.properties)) {
-      traverseNode(propSchema as Record<string, any>, key, map, schema);
+      traverseNode(propSchema as Record<string, any>, key, sink, schema);
     }
   }
   return map;
@@ -231,40 +281,207 @@ export function buildFieldMapAtPath(
   pathPrefix: string,
 ): ReferenceFieldMap {
   const map: ReferenceFieldMap = new Map();
-  traverseNode(schema, pathPrefix, map, schema);
+  traverseNode(schema, pathPrefix, injectionSink(map), schema);
   return map;
 }
 
+const drivenSlotMaps = new WeakMap<object, DrivenSlots>();
+
+/** The resource envelope: present on every resource document, and never
+ *  configuration a kind's root `additionalProperties` describes. */
+const RESOURCE_ENVELOPE_KEYS = ["kind", "metadata"];
+
+/**
+ * Every slot through which a resource of this schema DRIVES another — the
+ * reference field map's own traversal, plus what a dispatch analysis needs and
+ * the injection surface must not have:
+ *
+ * - local `$ref` is followed, resolved against the root. The injection map
+ *   stops there so a step's `invoke` never becomes an injection site; this map
+ *   stops AT a step body instead, which removes that reason. A reference back
+ *   to a node already on the descent is recorded as a back-edge rather than
+ *   unrolled, so a recursive shape stays finite here and is followed as deep as
+ *   the data goes by `forEachDrivenSlot`;
+ * - a step body is recorded and not descended — the step traversal owns
+ *   everything below it;
+ * - the root's own variant branches and `additionalProperties` are walked, not
+ *   only its `properties`;
+ * - a path keeps EVERY slot any branch declares there, where the injection map
+ *   keeps the last one written (see {@link DrivenPath.refs});
+ * - each `{}` path records the keys its `additionalProperties` does not cover.
+ *
+ * Shared by every throws question (a kind's `inherit` union, a scope list's
+ * denominator, catch-scope enclosure, and whether `inherit` is legal at all),
+ * so none can reach a slot another cannot. Memoized per schema object.
+ */
+export function buildDrivenSlotMap(schema: Record<string, any>): DrivenSlots {
+  const cached = drivenSlotMaps.get(schema);
+  if (cached) return cached;
+  const slots: DrivenSlots = { paths: new Map(), declaredKeys: new Map(), drives: false };
+  traverseNode(schema, "", drivenSink(slots), schema);
+  drivenSlotMaps.set(schema, slots);
+  return slots;
+}
+
+const joinPath = (path: string, key: string): string => (path ? `${path}.${key}` : key);
+
+/** Where a traversal records what it finds. */
+interface FieldMapSink {
+  readonly driven: boolean;
+  ref(path: string, entry: RefFieldEntry, node: Record<string, any>): void;
+  stop(path: string, entry: ScopeFieldEntry | SchemaFromFieldEntry): void;
+  step(path: string, step: StepSlot, node: Record<string, any>): void;
+  recurse(path: string, to: string): void;
+  mapValue(mapPath: string, declared: string[]): void;
+}
+
+/** The injection map: one entry per path, the last one written. Step bodies,
+ *  back-edges and map-value keys are the driven map's alone. */
+function injectionSink(map: ReferenceFieldMap): FieldMapSink {
+  return {
+    driven: false,
+    ref: (path, entry) => {
+      map.set(path, entry);
+    },
+    stop: (path, entry) => {
+      map.set(path, entry);
+    },
+    step: () => {},
+    recurse: () => {},
+    mapValue: () => {},
+  };
+}
+
+function drivenSink(slots: DrivenSlots): FieldMapSink {
+  const recorded = new Map<string, Set<object>>();
+  const at = (path: string): DrivenPath => {
+    let entry = slots.paths.get(path);
+    if (!entry) {
+      entry = { refs: [], steps: [], recurse: [] };
+      slots.paths.set(path, entry);
+    }
+    return entry;
+  };
+  // One schema node reached twice at one path (two branches `$ref`-ing one
+  // definition) is one slot.
+  const firstTime = (path: string, node: object): boolean => {
+    let nodes = recorded.get(path);
+    if (!nodes) recorded.set(path, (nodes = new Set()));
+    if (nodes.has(node)) return false;
+    nodes.add(node);
+    return true;
+  };
+  return {
+    driven: true,
+    ref: (path, entry, node) => {
+      if (!firstTime(path, node)) return;
+      at(path).refs.push(entry);
+      slots.drives = true;
+    },
+    stop: () => {},
+    step: (path, step, node) => {
+      if (!firstTime(path, node)) return;
+      at(path).steps.push(step);
+      slots.drives = true;
+    },
+    recurse: (path, to) => {
+      const entry = at(path);
+      if (!entry.recurse.includes(to)) entry.recurse.push(to);
+    },
+    mapValue: (mapPath, declared) => {
+      const previous = slots.declaredKeys.get(mapPath);
+      slots.declaredKeys.set(
+        mapPath,
+        new Set(previous ? declared.filter((key) => previous.has(key)) : declared),
+      );
+    },
+  };
+}
+
+/** Follow a local `$ref` in driven mode. `onStack` maps each node on the
+ *  current descent to the path it was entered at: re-entering one records a
+ *  back-edge to that path, and a cycle that made no structural progress (same
+ *  path) records nothing, since its body is already recorded there. */
+function followLocalRef(
+  node: Record<string, any>,
+  path: string,
+  sink: FieldMapSink,
+  root: Record<string, any> | undefined,
+  onStack: Map<Record<string, any>, string>,
+): void {
+  if (!root) return;
+  const target = resolveLocalRef(node, root);
+  if (!target || target === node) return;
+  const entered = onStack.get(target);
+  if (entered !== undefined) {
+    if (entered !== path) sink.recurse(path, entered);
+    return;
+  }
+  onStack.set(target, path);
+  try {
+    traverseNode(target, path, sink, root, onStack);
+  } finally {
+    onStack.delete(target);
+  }
+}
+
+/** `owner.additionalProperties`, the schema of every value in an open-keyed
+ *  object. JSON Schema applies it only to keys `owner` does not declare, which
+ *  the driven map records so a walk skips them. */
+function traverseMapValue(
+  owner: Record<string, any>,
+  path: string,
+  sink: FieldMapSink,
+  root: Record<string, any> | undefined,
+  onStack: Map<Record<string, any>, string>,
+): void {
+  const valueSchema = owner.additionalProperties;
+  if (!valueSchema || typeof valueSchema !== "object" || Array.isArray(valueSchema)) return;
+  const mapPath = joinPath(path, "{}");
+  const declared =
+    owner.properties && typeof owner.properties === "object" ? Object.keys(owner.properties) : [];
+  sink.mapValue(mapPath, path === "" ? [...declared, ...RESOURCE_ENVELOPE_KEYS] : declared);
+  traverseNode(valueSchema as Record<string, any>, mapPath, sink, root, onStack);
+}
+
 function traverseNode(
   node: Record<string, any>,
   path: string,
-  map: ReferenceFieldMap,
+  sink: FieldMapSink,
   root?: Record<string, any>,
-  visitedRefs: Set<string> = new Set(),
+  onStack: Map<Record<string, any>, string> = new Map(),
 ): void {
-  // Local `$ref` is intentionally NOT followed. This map is the kernel's
+  const driven = sink.driven;
+  // Local `$ref` is intentionally NOT followed here. This map is the kernel's
   // Phase-5 injection surface: descending into shared `$defs` (notably
   // `Run.Sequence`'s `step` definition) would make every step's `invoke` an
   // injection site, and step slots resolve at dispatch — injecting there is
   // unwanted regardless of tracing (the original dispatcher-bypass blocker
   // has since shipped via the `REF_IDENTITY` stamp). Static analysis is NOT
   // limited by this stop: the call graph (`call-graph.ts`) reads step slots
-  // from the item schema itself and scans the value tree, so it sees what
-  // this map deliberately hides. `visitedRefs` stays as a parameter so the
-  // recursive calls below thread the right signature.
-  if (typeof node?.$ref === "string") return;
+  // from the item schema itself and scans the value tree, and the driven-slot
+  // mode (`buildDrivenSlotMap`) follows the reference.
+  if (typeof node?.$ref === "string" && !driven) return;
   // Scope slot — record and stop; do not recurse into scope contents
   if ("x-telo-scope" in node) {
-    map.set(path, { scope: node["x-telo-scope"] });
+    sink.stop(path, { scope: node["x-telo-scope"] });
     return;
   }
 
   // Schema-from slot — record and stop; no further traversal needed
   if ("x-telo-schema-from" in node) {
-    map.set(path, { schemaFrom: node["x-telo-schema-from"] });
+    sink.stop(path, { schemaFrom: node["x-telo-schema-from"] });
     return;
   }
 
+  if (driven) {
+    const step = readStepSlot(node);
+    if (step) {
+      sink.step(path, step, node);
+      return;
+    }
+  }
+
   // Reference slot (direct, via a `kind:` list, or via anyOf)
   const slot = readRefSlot(node);
   if (slot && slot.kinds.length > 0) {
@@ -278,7 +495,8 @@ function traverseNode(
     if (slot.valueBranches.length > 0) entry.valueBranches = slot.valueBranches;
     if (node["x-telo-context"]) entry.context = node["x-telo-context"] as Record<string, any>;
     if (slot.inline) entry.inline = true;
-    map.set(path, entry);
+    if (slot.throwsThrough) entry.throwsThrough = true;
+    sink.ref(path, entry, node);
     // A node can mix item-level ref branches (a bare string / `{kind, name}`)
     // with object branches that carry their OWN nested refs — e.g. Application
     // `targets`: a bare ref vs inline `{ invoke }` vs gated `{ ref }`. Descend
@@ -290,22 +508,26 @@ function traverseNode(
       if (!Array.isArray(variants)) continue;
       for (const variant of variants) {
         if (!variant || typeof variant !== "object") continue;
-        traverseVariant(variant as Record<string, any>, path, map, root, visitedRefs);
+        traverseVariant(variant as Record<string, any>, path, sink, root, onStack);
       }
     }
     return;
   }
-  if (typeof node?.$ref === "string") return;
+  // Reached only in driven mode — the injection map stopped at the top.
+  if (typeof node?.$ref === "string") {
+    followLocalRef(node, path, sink, root, onStack);
+    return;
+  }
 
   // Array — recurse into items
   if (node.type === "array" && node.items) {
-    traverseNode(node.items as Record<string, any>, path + "[]", map, root, visitedRefs);
+    traverseNode(node.items as Record<string, any>, path + "[]", sink, root, onStack);
   }
 
   // Object — recurse into properties
   if (node.properties) {
     for (const [key, propSchema] of Object.entries(node.properties)) {
-      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map, root, visitedRefs);
+      traverseNode(propSchema as Record<string, any>, joinPath(path, key), sink, root, onStack);
     }
   }
 
@@ -315,67 +537,50 @@ function traverseNode(
   // slots inside the branch. Walking each branch surfaces those slots into
   // the field map so downstream passes (ref validation, sentinel
   // resolution, dependency graph) cover them without a runtime fallback.
-  // The same field path may be added by multiple branches; the later
-  // assignment wins, which is fine — branches with the same field path
-  // share the same ref/context configuration (any divergence is already
-  // a schema bug).
+  // The same field path may be added by multiple branches. The injection map
+  // keeps the later assignment, which is fine for injection — branches with
+  // the same field path share the same ref/context configuration. The driven
+  // map keeps every one, because which branch applies decides what a
+  // dispatch can throw.
   for (const variantKey of ["oneOf", "anyOf", "allOf"] as const) {
     const variants = node[variantKey];
     if (!Array.isArray(variants)) continue;
     for (const variant of variants) {
       if (!variant || typeof variant !== "object") continue;
-      traverseVariant(variant as Record<string, any>, path, map, root, visitedRefs);
+      traverseVariant(variant as Record<string, any>, path, sink, root, onStack);
     }
   }
 
   // Map — `additionalProperties: { ... }` describes every value in an
   // open-keyed object. Encoder refs nested inside `content[mime]` map
   // entries reach Phase 5 through this branch.
-  if (
-    node.additionalProperties &&
-    typeof node.additionalProperties === "object" &&
-    !Array.isArray(node.additionalProperties)
-  ) {
-    traverseNode(
-      node.additionalProperties as Record<string, any>,
-      `${path}.{}`,
-      map,
-      root,
-      visitedRefs,
-    );
-  }
+  traverseMapValue(node, path, sink, root, onStack);
 }
 
 /** Walk a single variant of a `oneOf` / `anyOf` / `allOf` branch. Only
  *  the properties / items / map slots are followed — collectRefs at the
  *  variant root is handled by the parent's `collectRefs(node)` already
- *  (anyOf of x-telo-ref branches is the canonical multi-ref shape). */
+ *  (anyOf of x-telo-ref branches is the canonical multi-ref shape). In
+ *  driven mode a `$ref` branch is followed as a node in its own right, since
+ *  `readRefSlot` does not look through one. */
 function traverseVariant(
   variant: Record<string, any>,
   path: string,
-  map: ReferenceFieldMap,
+  sink: FieldMapSink,
   root?: Record<string, any>,
-  visitedRefs: Set<string> = new Set(),
+  onStack: Map<Record<string, any>, string> = new Map(),
 ): void {
+  if (sink.driven && typeof variant.$ref === "string") {
+    followLocalRef(variant, path, sink, root, onStack);
+    return;
+  }
   if (variant.properties) {
     for (const [key, propSchema] of Object.entries(variant.properties)) {
-      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map, root, visitedRefs);
+      traverseNode(propSchema as Record<string, any>, joinPath(path, key), sink, root, onStack);
     }
   }
   if (variant.type === "array" && variant.items) {
-    traverseNode(variant.items as Record<string, any>, path + "[]", map, root, visitedRefs);
-  }
-  if (
-    variant.additionalProperties &&
-    typeof variant.additionalProperties === "object" &&
-    !Array.isArray(variant.additionalProperties)
-  ) {
-    traverseNode(
-      variant.additionalProperties as Record<string, any>,
-      `${path}.{}`,
-      map,
-      root,
-      visitedRefs,
-    );
+    traverseNode(variant.items as Record<string, any>, path + "[]", sink, root, onStack);
   }
+  traverseMapValue(variant, path, sink, root, onStack);
 }

package/src/release/CLAUDE.md

@@ -0,0 +1,32 @@
+# Release model — guide
+
+Loaded when working under `analyzer/nodejs/src/release/`. The release RULES every change follows (changesets for published packages, `telo release add` fragments for modules, pre-1.0 minors) are in the root `CLAUDE.md`; publishing (payload builder, pins, the publication split) is in `cli/nodejs/CLAUDE.md`. Guide: `docs/extend/releasing-modules.md`.
+
+**The release system exists because a module's artifact EMBEDS its dependencies** — esbuild inlines a sibling library's source into the controller bundle, and publish pins each relative import to a hash of the sibling's manifest — so bumping the dependents is a correctness requirement, not a courtesy. No general-purpose changelog tool can see that — a per-project ledger has no dependency graph at all, and changesets' stops at the npm boundary, where a module's inlined sibling is invisible.
+
+**Three questions, three mechanisms.** The **payload digest** (exact, from the bytes; `computeFilesIntegrity` over the layers publish builds, or over an image module's `.dockerignore`-defined file set) decides *whether* a module bumps, so it fires for an inlined sibling, a shared-library fix and a lockfile-only transitive bump alike. The **edge graph** decides *at what level*: edges come from the controller build's own **metafile** (a declared-deps graph cannot see `--external`, so `@telorun/sdk` — declared by 54 modules, inlined by none — would bump the whole stdlib on every SDK change) plus in-repo relative `imports:`; a dependent mirrors its dependency's level, joined as the maximum over paths. An **import edge bumps unconditionally** (publishing rewrites the sibling's version into the manifest, so the layer provably changes) while an **inline edge only explains drift that already showed up**. A digest that moved with nothing to attribute it to takes a **patch** and is reported as *unattributed*, never silently. The path-scoped **changed-files rule** survives but is demoted to deciding only *whether a changelog line is requested* — it used to decide the version, which is why its guesswork (`docs/` vs `tests/` vs `nodejs/`, `bundlesAController`) had to be sound and was not; now a false positive costs one sentence.
+
+**The ledger is a cache; the registry is the authority.** `.changes/ledger.yaml` records per module its version, its per-layer integrity **as published**, and the **registry base** those digests were taken against — per ENTRY, since a workspace may publish its subtrees to different bases (canonicalization writes the destination into every relative import, so digests against another base are digests of different bytes). 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. That is the load-bearing property: **the PR gate and the publish gate compute the same number**, and the PR gate needs no merge base and no credentials, so a fork runs the identical computation. A *missing* entry is not drift — nothing is published, the right reading for a new module. `telo publish` still reads the registry, and `telo release verify [--write]` reconciles.
+
+**`telo release check` does NOT fail because a payload moved.** Under a toolchain bump every digest moves; demanding sixty fragments for that is a tax on nobody's behalf, and those ship as unattributed patches. It fails when no consistent plan can be formed: a fragment naming an unknown module, a major-inducing kind (`Changed`/`Removed`), a manifest version disagreeing with its ledger entry, or a registry-base mismatch. It *warns* (`CHANGELOG_ENTRY_REQUESTED`) when a module's own files changed with no fragment naming it.
+
+## The workspace marker
+
+**The workspace anchor.** `telo-workspace.yaml` at the repo root. **Its location is the anchor** for every module key, ledger entry, fragment path and the `.telo` cache; **every FIELD lives in a block scoped to what it governs**, which is the file's one rule. `release:` carries `registry:` (the publish base), `ignore:` (module-relative gitignore-style paths whose changes ask for no changelog fragment) and `modules:` (the subtrees that may hold modules — not derivable, since hundreds of manifests elsewhere carry a `metadata.version`). `env:` carries `roots:` (how far up `telo run` walks collecting env files) and `files:` (which filenames, later winning within one directory). Reader + shape as data: `analyzer/nodejs/src/release/workspace-{config,schema}.ts`; guide `docs/guides/workspaces.md`.
+
+**`modules:` moved under `release:` and no second spelling is kept** — top-level is a recognized-and-moved key naming the move. It is a release INVENTORY, not an inventory of manifests, and leaving it at the top level made it read as a fact about the tree: the runner seeded `modules: ["*"]` into every session workspace purely because an empty list was a parse error, shipping release scope a session never reads. **The file and every block in it are optional**, so a marker whose whole content is comments is valid — which is what the runner seeds now.
+
+**The reader is lenient and the strict half is diagnostics; which are FATAL is the caller's policy.** `readWorkspaceConfig` returns config + diagnostics anchored at key paths (`WORKSPACE_MODULES_MOVED`, `WORKSPACE_UNKNOWN_KEY`, `WORKSPACE_INVALID_VALUE`, plus the repo-shaped `WORKSPACE_ENTRY_MATCHES_NOTHING` / `_SHADOWED` / `WORKSPACE_MARKER_SHADOWED` the editor adds). `telo release` refuses on any error; **`telo run` consumes `env:` alone** — a typo under `release.modules` is printed and the run proceeds, while one INSIDE `env:` fails the run, because degrading to the marker-wide bound would WIDEN the walk and a block that opted into a boundary and got nothing is a defect, not a default. An unknown top-level BLOCK is a warning (so the next block ships without breaking today's runs); a near-miss of a known one is an error. Gitignore matching is **injected** (`PatternMatch`), because the grammar is `@telorun/glob`'s and the analyzer is browser-safe; `lastMatchIndex` is what makes a decision attributable to the entry that made it.
+
+**Settings cascade key-wise and each value REPLACES whole**: built-in → `release:`'s own key → the matching entry's. A `modules:` entry is a bare pattern string or `{path, registry?, ignore?}`, evaluated **last-match-wins** — the rule the list already had — so a later, more specific entry overrides one module and a `!` entry is an exclusion that supplies nothing. A list is never unioned across levels, so the set in force is always exactly one authored list.
+
+**A destination is the resolved base plus the module's own directory name, and both ways that can be inconsistent are checked at plan time, before any payload is built**: `DESTINATION_COLLISION` (two modules on one ref — the payload builder is keyed by manifest, so it catches one module claimed twice and never the reverse, while the ledger keys by module and both entries would record digests for one artifact) and `IMPORT_DESTINATION_CONFLICT` (a relative import whose derived ref is not where the target publishes; equal registries are necessary and not sufficient, since two modules under one base at different depths derive differently). **The registry cascade is entry → block → `--registry` → `TELO_OCI_REGISTRY` → the base that module's own ledger entry recorded** — the ledger is LAST, a change: a workspace that authors its destination has said where it publishes, and a cache of a past answer must not outrank it. A disagreement is a per-module `LEDGER_REGISTRY_MISMATCH` in a plan that is still produced, rather than an abort. **`telo release order` emits `{key, destination}`** and the module publisher reads the destination from it: deriving `$TELO_OCI_REGISTRY/<directory name>` for itself was the last fact that script still answered, and a multi-destination workspace would have planned several bases and pushed them all to one.
+
+Modules are **discovered, not registered**: a module is a directory under a named subtree holding a `telo.yaml` whose **module doc** carries a `metadata.version`, and its key is its workspace-relative path (never a bare name — two subtrees can share one). Selection and attribution are ONE decision, since the entry that decides whether a directory is a module is the entry whose settings it resolves. Changed-file attribution is to the **nearest** enclosing module, matching how build inputs are attributed. A `Dockerfile` beside the manifest makes it an **image module**; that decides only which file set is digested. An image module's base image is deliberately outside its digest — the every-push `:latest` + `:sha-<short>` policy already carries a kernel change to the deployed app.
+
+The model splits on the browser-safety line: `analyzer/nodejs/src/release/` holds module identity, fragment parsing, the ledger, the edge graph, propagation and version planning (pure data in, plan out, so the editor can answer "what does changing this library bump?"); `cli/nodejs/src/release/` holds evidence collection (driving the kernel's builder, workspace and git reads, file writing) and the commands. Version rewriting reuses `yaml-source-edit.ts`, so a bump is a one-line diff rather than a re-serialized file.
+
+## Where to look
+
+- "will this change bump anything, and why?" → `analyzer/nodejs/src/release/` (`release-plan.ts` the planner, `payload-digest.ts` the digest keys, `ledger.ts`, `fragment.ts`, `version-stamp.ts`), `cli/nodejs/src/release/` (`workspace.ts` discovery, `evidence.ts` collection, `targets.ts` the registry cascade + the import graph), `cli/nodejs/src/bundle/module-payload.ts` (the one payload builder publish and release share), `docs/extend/releasing-modules.md`
+- "what may the workspace marker say, and who reads which half?" → `analyzer/nodejs/src/release/workspace-schema.ts` (the shape, as data), `workspace-config.ts` (the lenient reader + the cascade), `destinations.ts` (the two plan-time checks), `cli/nodejs/src/env-files.ts` (the `env:` half and the run path's policy), `packages/ide-support/src/workspace/` (diagnostics + completion), `docs/guides/workspaces.md`

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";