@davidorex/pi-context 0.26.0 → 0.28.1

package/dist/context.js

@@ -22,8 +22,64 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { appendManyToTypedFileIfAbsent, writeTypedFile } from "./block-api.js";
-import { assertSubstrateName, resolveContextDir, SCHEMAS_DIR, tryResolveContextDir } from "./context-dir.js";
+import { assertSubstrateName, mintSubstrateId, resolveContextDir, SCHEMAS_DIR, tryResolveContextDir, } from "./context-dir.js";
+import { registerSubstrate } from "./context-registry.js";
 import { ValidationError, validateFromFile } from "./schema-validator.js";
+export function normalizeEndpoint(e) {
+    if (typeof e === "string") {
+        return { kind: "item", key: e, foreign: false };
+    }
+    if (e.kind === "lens_bin") {
+        return { kind: "lens_bin", key: e.bin, bin: e.bin };
+    }
+    return { kind: "item", key: e.refname ?? e.oid, foreign: !!e.substrate_id };
+}
+/**
+ * The consumer-layer node key for an endpoint — the string that joins against
+ * `idIndex` (keyed by item refname) or is compared to `lens.bins` labels. This
+ * is the normalize-to-string shim every walker / validator / grouping site reads
+ * in place of the bare `edge.parent`/`edge.child`. Returns byte-identical results
+ * for legacy string endpoints.
+ */
+export function endpointKey(e) {
+    return normalizeEndpoint(e).key;
+}
+/**
+ * The bin label for a `{kind:"lens_bin"}` endpoint; `null` for any item endpoint
+ * (string or structured). Lens sites test this so a lens_bin endpoint can never
+ * reach an `idIndex.get` path (Constraint 4). A legacy STRING parent is `null`
+ * here too — it stays bin-or-item ambiguous and is resolved by
+ * `lens.bins.includes(endpointKey(e))` exactly as before this cycle.
+ */
+export function endpointBin(e) {
+    const n = normalizeEndpoint(e);
+    return n.kind === "lens_bin" ? n.bin : null;
+}
+/**
+ * The DEDUP identity of an endpoint (the deliberate asymmetry vs the consumer
+ * node key): string → the string; structured item → `${substrate_id ?? ""}:${oid}`;
+ * lens_bin → `bin:${bin}`. This is what `identityKey` keys on for the
+ * append-if-absent no-op.
+ *
+ * The `${substrate_id ?? ""}:${oid}` colon-form is the EDGE DEDUP KEY ONLY — it is
+ * NOT the oid's own format. The oid is a bare 32-hex digest (see `mintOid`, which
+ * returns the digest with no substrate prefix and no colon). The `substrate_id`
+ * prefix is prepended here solely so two items that happen to share an oid across
+ * DIFFERENT substrates dedup as distinct edges; within one substrate the oid alone
+ * is content-addressed, so two items with the same oid but different refnames dedup
+ * together.
+ *
+ * A bare-refname STRING and a structured same-item with the SAME refname do NOT
+ * dedup-merge here (string key `"FGAP-1"` vs item key `":<oid>"`) — the documented,
+ * probed asymmetry.
+ */
+export function endpointIdentity(e) {
+    if (typeof e === "string")
+        return e;
+    if (e.kind === "lens_bin")
+        return `bin:${e.bin}`;
+    return `${e.substrate_id ?? ""}:${e.oid}`;
+}
 // ── Schema paths (bundled with the package) ──────────────────────────────────
 /**
  * Resolve the bundled config / relations schema files. Resolved relative to
@@ -43,12 +99,25 @@ function bundledSchemaPath(name) {
 function configPath(cwd) {
     return path.join(resolveContextDir(cwd), "config.json");
 }
+/** `<substrateDir>/config.json` — the dir-targeted twin of `configPath`. Takes
+ * the ALREADY-RESOLVED substrate dir directly (no pointer resolution), mirroring
+ * the Cycle-1 `*ForDir` pattern (cf. `relationsPathForDir`). The Cycle-10
+ * canonicalizer targets a non-active work-dupe substrate via this path. */
+function configPathForDir(substrateDir) {
+    return path.join(substrateDir, "config.json");
+}
 /** `<resolveContextDir(cwd)>/relations.json` — same substrate-dir-relative
  * resolution as configPath; previous `.project/`-fixed exemption removed for
  * DEC-0015 compliance. */
 function relationsPath(cwd) {
     return path.join(resolveContextDir(cwd), "relations.json");
 }
+/** `<substrateDir>/relations.json` — the dir-targeted twin of `relationsPath`.
+ * Takes the ALREADY-RESOLVED substrate dir directly (no pointer resolution),
+ * mirroring the Cycle-1 `*ForDir` pattern. */
+function relationsPathForDir(substrateDir) {
+    return path.join(substrateDir, "relations.json");
+}
 // ── Loaders ─────────────────────────────────────────────────────────────────
 /**
  * Resolve the substrate root for `cwd` — pointer-canonical (DEC-0045 / FGAP-079).
@@ -80,7 +149,19 @@ export function loadConfig(cwd) {
     const root = tryResolveContextDir(cwd);
     if (root === null)
         return null;
-    const p = path.join(root, "config.json");
+    return loadConfigForDir(root);
+}
+/**
+ * Dir-targeted twin of {@link loadConfig} (Cycle-1 `*ForDir` pattern). Reads +
+ * AJV-validates `<substrateDir>/config.json` against the bundled config schema
+ * for the ALREADY-RESOLVED substrate dir — no `.pi-context.json` pointer
+ * resolution. Returns `null` when the file is absent (a normal pre-write state).
+ * `loadConfig` is a thin wrapper resolving the active pointer dir; behaviour is
+ * byte-identical when called via cwd. Used by the Cycle-10 canonicalizer to read
+ * a NON-active (work-dupe) substrate's config in place.
+ */
+export function loadConfigForDir(substrateDir) {
+    const p = path.join(substrateDir, "config.json");
     if (!fs.existsSync(p))
         return null;
     let raw;
@@ -88,14 +169,14 @@ export function loadConfig(cwd) {
         raw = fs.readFileSync(p, "utf-8");
     }
     catch (err) {
-        throw new Error(`loadConfig: failed to read ${p}: ${err instanceof Error ? err.message : String(err)}`);
+        throw new Error(`loadConfigForDir: failed to read ${p}: ${err instanceof Error ? err.message : String(err)}`);
     }
     let data;
     try {
         data = JSON.parse(raw);
     }
     catch (err) {
-        throw new Error(`loadConfig: invalid JSON in ${p}: ${err instanceof Error ? err.message : String(err)}`);
+        throw new Error(`loadConfigForDir: invalid JSON in ${p}: ${err instanceof Error ? err.message : String(err)}`);
     }
     validateFromFile(bundledSchemaPath("config"), data, `config.json (${p})`);
     return data;
@@ -142,7 +223,19 @@ export function loadRelations(cwd) {
     const root = tryResolveContextDir(cwd);
     if (root === null)
         return [];
-    const p = path.join(root, "relations.json");
+    return loadRelationsForDir(root);
+}
+/**
+ * Dir-targeted twin of {@link loadRelations} (Cycle-1 `*ForDir` pattern). Reads
+ * `<substrateDir>/relations.json` against the ALREADY-RESOLVED substrate dir —
+ * no `.pi-context.json` pointer resolution. Returns `[]` when the file is absent;
+ * AJV-validates the top-level `Edge[]` array against the bundled relations schema
+ * exactly as the cwd form does. `loadRelations` is a thin wrapper resolving the
+ * active pointer dir; behaviour is byte-identical when called via cwd. Used by
+ * the Phase-H migration to read a NON-active substrate's edges in place.
+ */
+export function loadRelationsForDir(substrateDir) {
+    const p = relationsPathForDir(substrateDir);
     if (!fs.existsSync(p))
         return [];
     let raw;
@@ -177,7 +270,18 @@ export function loadRelations(cwd) {
  * top-level-array stamping semantics documented in block-api).
  */
 export function writeRelations(cwd, edges, ctx) {
-    writeTypedFile(relationsPath(cwd), bundledSchemaPath("relations"), edges, ctx, "relations.json");
+    writeRelationsForDir(resolveContextDir(cwd), edges, ctx);
+}
+/**
+ * Dir-targeted twin of `writeRelations` (Cycle-1 `*ForDir` pattern). Operates
+ * on `<substrateDir>/relations.json` against the ALREADY-RESOLVED substrate dir
+ * — no `.pi-context.json` pointer resolution. `writeRelations` is a thin
+ * wrapper resolving the active dir; behaviour is byte-identical when called via
+ * cwd. AJV-shape validation comes from `writeTypedFile`; same attestation-parity
+ * no-op semantics as the cwd form.
+ */
+export function writeRelationsForDir(substrateDir, edges, ctx) {
+    writeTypedFile(relationsPathForDir(substrateDir), bundledSchemaPath("relations"), edges, ctx, "relations.json");
 }
 /**
  * Composite identity of an edge for append-if-absent dedup: the
@@ -189,7 +293,7 @@ export function writeRelations(cwd, edges, ctx) {
  */
 const identityKey = (e) => {
     const r = e;
-    return `${r.parent} ${r.child} ${r.relation_type}`;
+    return `${endpointIdentity(r.parent)} ${endpointIdentity(r.child)} ${r.relation_type}`;
 };
 /**
  * Append closure-table edges to `<resolveContextDir(cwd)>/relations.json`,
@@ -214,7 +318,19 @@ const identityKey = (e) => {
  * semantics documented in block-api).
  */
 export function appendRelations(cwd, edges, ctx) {
-    return appendManyToTypedFileIfAbsent(relationsPath(cwd), bundledSchemaPath("relations"), null, edges, identityKey, ctx, "relations.json");
+    return appendRelationsForDir(resolveContextDir(cwd), edges, ctx);
+}
+/**
+ * Dir-targeted twin of `appendRelations` (Cycle-1 `*ForDir` pattern). Operates
+ * on `<substrateDir>/relations.json` against the ALREADY-RESOLVED substrate dir
+ * — no pointer resolution. `appendRelations` is a thin wrapper resolving the
+ * active dir; behaviour is byte-identical when called via cwd. Same deferred-
+ * guard semantics: only AJV-shape validation + the (parent, child,
+ * relation_type) exact-duplicate-no-op; relation_type registration / endpoint
+ * resolution / cycle checks remain deferred to `validateContext`.
+ */
+export function appendRelationsForDir(substrateDir, edges, ctx) {
+    return appendManyToTypedFileIfAbsent(relationsPathForDir(substrateDir), bundledSchemaPath("relations"), null, edges, identityKey, ctx, "relations.json");
 }
 /**
  * Append a single closure-table edge. Convenience over `appendRelations`:
@@ -223,7 +339,17 @@ export function appendRelations(cwd, edges, ctx) {
  * no-op). Same deferred-guard semantics as `appendRelations`.
  */
 export function appendRelation(cwd, edge, ctx) {
-    const r = appendRelations(cwd, [edge], ctx);
+    return appendRelationForDir(resolveContextDir(cwd), edge, ctx);
+}
+/**
+ * Dir-targeted twin of `appendRelation` (Cycle-1 `*ForDir` pattern). Operates
+ * on `<substrateDir>/relations.json` against the ALREADY-RESOLVED substrate dir.
+ * `appendRelation` is a thin wrapper resolving the active dir; behaviour is
+ * byte-identical when called via cwd. Same `{ appended }` semantics + deferred
+ * guards as `appendRelationsForDir`.
+ */
+export function appendRelationForDir(substrateDir, edge, ctx) {
+    const r = appendRelationsForDir(substrateDir, [edge], ctx);
     return { appended: r.appended > 0 };
 }
 /**
@@ -232,7 +358,18 @@ export function appendRelation(cwd, edge, ctx) {
  * Same cycle-safety reasoning as `writeRelations`.
  */
 export function writeConfig(cwd, config, ctx) {
-    writeTypedFile(configPath(cwd), bundledSchemaPath("config"), config, ctx, "config.json");
+    writeConfigForDir(resolveContextDir(cwd), config, ctx);
+}
+/**
+ * Dir-targeted twin of `writeConfig` (Cycle-1 `*ForDir` pattern). Atomic,
+ * AJV-validated write of `<substrateDir>/config.json` against the bundled config
+ * schema for the ALREADY-RESOLVED substrate dir — no pointer resolution.
+ * `writeConfig` is a thin wrapper resolving the active dir; behaviour is
+ * byte-identical when called via cwd. Same attestation-parity no-op semantics as
+ * the cwd form (the config schema declares no envelope author fields).
+ */
+export function writeConfigForDir(substrateDir, config, ctx) {
+    writeTypedFile(configPathForDir(substrateDir), bundledSchemaPath("config"), config, ctx, "config.json");
 }
 /**
  * accept-all: adopt the package's canonical packaged conception
@@ -262,7 +399,21 @@ export function adoptConception(cwd) {
     const samplesRoot = path.resolve(here, "..", "samples");
     const conception = JSON.parse(fs.readFileSync(path.join(samplesRoot, "conception.json"), "utf-8"));
     conception.root = root; // SET root from the resolved substrate dir — the conception template ships none (DEC-0041)
+    // Mint + register the per-substrate content-addressed substrate_id (Cycle 4).
+    // config.json is the sole SoT for substrate_id and first exists here at
+    // adopt-time (init only scaffolds the pointer + dirs), so minting wires into
+    // this path rather than bare init. Idempotent: skip the mint if the
+    // conception already carries a valid substrate_id (it ships none, so this
+    // mints on a fresh accept-all; a second accept-all returns early above on the
+    // existing-config branch, so this block never re-mints). registerSubstrate
+    // upserts the active substrate into the project-root registry under `root`
+    // (the project-root-relative substrate dir) with empty aliases — the
+    // SoT-drift invariant in validateContext then passes for this substrate.
+    if (typeof conception.substrate_id !== "string" || conception.substrate_id.length === 0) {
+        conception.substrate_id = mintSubstrateId();
+    }
     writeConfig(cwd, conception);
+    registerSubstrate(cwd, conception.substrate_id, root, []);
     return {
         adopted: true,
         configPath: path.relative(cwd, cfgPath),
@@ -287,6 +438,8 @@ const REGISTRY_DESCRIPTORS = {
     installed_schemas: { kind: "string-array" },
     installed_blocks: { kind: "string-array" },
     hierarchy: { kind: "value-array" },
+    tool_operations: { kind: "keyed-array", idField: "canonical_id" },
+    tool_operations_forbidden: { kind: "string-array" },
 };
 /** Canonical identity join for a hierarchy triple (the `value-array` kind). */
 function hierarchyKey(h) {
@@ -336,6 +489,20 @@ function hierarchyKey(h) {
  * @throws ValidationError (from `writeConfig`) on a SHAPE violation.
  */
 export function amendConfigEntry(cwd, registry, operation, key, entry, ctx, opts) {
+    return amendConfigEntryForDir(resolveContextDir(cwd), registry, operation, key, entry, ctx, opts);
+}
+/**
+ * Dir-targeted twin of `amendConfigEntry` (Cycle-1 `*ForDir` pattern). Carries
+ * the FULL scoped add / replace / remove body; `amendConfigEntry` delegates here
+ * via `resolveContextDir(cwd)`, so a cwd call is byte-identical to a ForDir call
+ * on the resolved active dir. Targets `<substrateDir>/config.json` directly via
+ * `loadConfigForDir` / `writeConfigForDir` (NO pointer resolution) so the
+ * Cycle-10 canonicalizer can register block_kinds / relation_types into a
+ * non-active work-dupe substrate in place. Both guard tiers
+ * (OP-CORRECTNESS + SHAPE-via-AJV) and the deep-clone-then-write-once discipline
+ * are identical to the documented `amendConfigEntry` contract above.
+ */
+export function amendConfigEntryForDir(substrateDir, registry, operation, key, entry, ctx, opts) {
     // (1) Discriminator validation.
     const descriptor = REGISTRY_DESCRIPTORS[registry];
     if (!descriptor) {
@@ -353,7 +520,7 @@ export function amendConfigEntry(cwd, registry, operation, key, entry, ctx, opts
         throw new Error(`amendConfigEntry: operation '${op}' requires an entry payload`);
     }
     // (2) Load + (3) deep clone (mutate the clone, write once at the end).
-    const config = loadConfig(cwd);
+    const config = loadConfigForDir(substrateDir);
     if (!config) {
         throw new Error("amendConfigEntry: no config.json");
     }
@@ -495,7 +662,7 @@ export function amendConfigEntry(cwd, registry, operation, key, entry, ctx, opts
             validateFromFile(bundledSchemaPath("config"), nextConfig, "config.json (dry-run)");
         }
         else {
-            writeConfig(cwd, nextConfig, ctx);
+            writeConfigForDir(substrateDir, nextConfig, ctx);
         }
     }
     // (6) Outcome.
@@ -615,9 +782,10 @@ export function walkDescendants(parentId, relationType, edges) {
             continue;
         visited.add(node);
         for (const e of edges) {
-            if (e.parent === node && e.relation_type === relationType) {
-                out.push(e.child);
-                stack.push(e.child);
+            if (endpointKey(e.parent) === node && e.relation_type === relationType) {
+                const childKey = endpointKey(e.child);
+                out.push(childKey);
+                stack.push(childKey);
             }
         }
     }
@@ -649,9 +817,10 @@ export function walkAncestors(itemId, relationType, edges) {
             continue;
         visited.add(node);
         for (const e of edges) {
-            if (e.child === node && e.relation_type === relationType) {
-                out.push(e.parent);
-                stack.push(e.parent);
+            if (endpointKey(e.child) === node && e.relation_type === relationType) {
+                const parentKey = endpointKey(e.parent);
+                out.push(parentKey);
+                stack.push(parentKey);
             }
         }
     }
@@ -687,13 +856,13 @@ export function walkAncestors(itemId, relationType, edges) {
  */
 export function findReferences(itemId, edges, direction = "both") {
     if (direction === "inbound") {
-        return edges.filter((e) => e.child === itemId);
+        return edges.filter((e) => endpointKey(e.child) === itemId);
     }
     if (direction === "outbound") {
-        return edges.filter((e) => e.parent === itemId);
+        return edges.filter((e) => endpointKey(e.parent) === itemId);
     }
     // "both": single-pass predicate; self-loop matches once via the OR.
-    return edges.filter((e) => e.child === itemId || e.parent === itemId);
+    return edges.filter((e) => endpointKey(e.child) === itemId || endpointKey(e.parent) === itemId);
 }
 /**
  * Project items into bins under a lens. Items reachable through `lensEdges`
@@ -709,9 +878,15 @@ export function groupByLens(items, lens, lensEdges) {
     const itemById = new Map(items.map((i) => [i.id, i]));
     const placedIds = new Set();
     for (const e of lensEdges) {
-        const item = itemById.get(e.child);
-        if (item && lens.bins.includes(e.parent)) {
-            grouped.get(e.parent)?.push(item);
+        const item = itemById.get(endpointKey(e.child));
+        // Parent bin label: a structured {kind:"lens_bin"} contributes its bin; a
+        // legacy string parent stays bin-or-item-ambiguous and is resolved by
+        // `lens.bins.includes` (endpointBin is null for strings → fall back to the
+        // string key). A structured ITEM parent (endpointBin null, non-bin key)
+        // simply fails the includes test and is left for the (uncategorized) pass.
+        const binLabel = endpointBin(e.parent) ?? endpointKey(e.parent);
+        if (item && lens.bins.includes(binLabel)) {
+            grouped.get(binLabel)?.push(item);
             placedIds.add(item.id);
         }
     }
@@ -755,23 +930,7 @@ export function listUncategorized(lens, grouped) {
     });
     return { uncategorized, suggestionTemplate };
 }
-// ── validateRelations ────────────────────────────────────────────────────────
-/**
- * Validate authored edges against `config` registries (lenses + hierarchy +
- * relation_types) and the cross-block id index supplied by the caller.
- * Emits seven structured issue codes:
- *   - edge_unknown_relation_type
- *   - edge_parent_not_in_bins (lens edges)
- *   - edge_unresolved_parent / edge_parent_wrong_block (hierarchy edges)
- *   - edge_unresolved_child / edge_child_wrong_block (lens or hierarchy)
- *   - edge_cycle_detected (DFS recursion-stack on hierarchy relation_types)
- *
- * `itemsByBlock` is indexed by `BlockKindDecl.canonical_id` for hierarchy
- * checks (parent / child must reside in the declared block) and by
- * `LensSpec.target` for lens checks. Callers supply the index — this
- * module does not read blocks itself, keeping it independent of block-api.
- */
-export function validateRelations(config, relations, itemsByBlock) {
+export function validateRelations(config, relations, itemsByBlock, resolve) {
     const issues = [];
     const lensesByRelType = new Map();
     for (const l of config.lenses ?? []) {
@@ -796,6 +955,26 @@ export function validateRelations(config, relations, itemsByBlock) {
     for (const edge of relations) {
         const lens = lensesByRelType.get(edge.relation_type);
         const hier = hierarchyByRelType.get(edge.relation_type);
+        // Consumer-layer node keys (the load-bearing pivot): string-typed for
+        // byte-identical diagnostics. A structured same-substrate item normalizes
+        // to its refname; a foreign item / project: string keys on its foreign
+        // string → idIndex miss → unresolved, exactly as today's sentinels.
+        const parentKey = endpointKey(edge.parent);
+        const childKey = endpointKey(edge.child);
+        // Block-resolution for the parent/child item endpoints. When a `resolve`
+        // hook is supplied (validateContext's F2 resolver), a resolved active OR
+        // foreign item contributes its `loc.block` — so a cross-substrate child
+        // under a lens/hierarchy relation_type resolves to its foreign block rather
+        // than missing the active-only `idIndex`. When OMITTED (test callers /
+        // standalone use), this falls back to the inline `idIndex.get(key)` —
+        // byte-identical to the pre-F2 behavior. (`undefined` from either path means
+        // "not found in any loaded block", exactly as before.)
+        const resolveBlock = (endpoint, key) => {
+            if (!resolve)
+                return idIndex.get(key);
+            const r = resolve(endpoint);
+            return r.status === "active" || r.status === "foreign" ? r.loc?.block : undefined;
+        };
         if (!declaredRelTypes.has(edge.relation_type)) {
             issues.push({
                 code: "edge_unknown_relation_type",
@@ -806,57 +985,62 @@ export function validateRelations(config, relations, itemsByBlock) {
             continue;
         }
         if (lens) {
-            if (!lens.bins.includes(edge.parent)) {
+            // Bin label: a structured {kind:"lens_bin"} parent contributes its bin;
+            // a legacy string parent is bin-or-item ambiguous, resolved by includes.
+            // A structured ITEM parent (endpointBin null) keys on its refname/oid and
+            // fails the includes test → edge_parent_not_in_bins (never an idIndex.get).
+            const parentBin = endpointBin(edge.parent) ?? parentKey;
+            if (!lens.bins.includes(parentBin)) {
                 issues.push({
                     code: "edge_parent_not_in_bins",
-                    message: `lens-edge parent '${edge.parent}' is not in lens '${lens.id}' bins`,
+                    message: `lens-edge parent '${parentBin}' is not in lens '${lens.id}' bins`,
                     edge,
                 });
             }
-            const childBlock = idIndex.get(edge.child);
+            const childBlock = resolveBlock(edge.child, childKey);
             if (!childBlock) {
                 issues.push({
                     code: "edge_unresolved_child",
-                    message: `lens-edge child '${edge.child}' not found in any loaded block`,
+                    message: `lens-edge child '${childKey}' not found in any loaded block`,
                     edge,
                 });
             }
             else if (lens.target && childBlock !== lens.target) {
                 issues.push({
                     code: "edge_child_wrong_block",
-                    message: `lens-edge child '${edge.child}' in block '${childBlock}', expected lens.target '${lens.target}'`,
+                    message: `lens-edge child '${childKey}' in block '${childBlock}', expected lens.target '${lens.target}'`,
                     edge,
                 });
             }
         }
         if (hier) {
-            const parentBlock = idIndex.get(edge.parent);
+            const parentBlock = resolveBlock(edge.parent, parentKey);
             if (!parentBlock) {
                 issues.push({
                     code: "edge_unresolved_parent",
-                    message: `hierarchy-edge parent '${edge.parent}' not found in any loaded block`,
+                    message: `hierarchy-edge parent '${parentKey}' not found in any loaded block`,
                     edge,
                 });
             }
             else if (parentBlock !== hier.parent_block) {
                 issues.push({
                     code: "edge_parent_wrong_block",
-                    message: `hierarchy-edge parent '${edge.parent}' in block '${parentBlock}', expected '${hier.parent_block}'`,
+                    message: `hierarchy-edge parent '${parentKey}' in block '${parentBlock}', expected '${hier.parent_block}'`,
                     edge,
                 });
             }
-            const childBlock = idIndex.get(edge.child);
+            const childBlock = resolveBlock(edge.child, childKey);
             if (!childBlock) {
                 issues.push({
                     code: "edge_unresolved_child",
-                    message: `hierarchy-edge child '${edge.child}' not found in any loaded block`,
+                    message: `hierarchy-edge child '${childKey}' not found in any loaded block`,
                     edge,
                 });
             }
             else if (childBlock !== hier.child_block) {
                 issues.push({
                     code: "edge_child_wrong_block",
-                    message: `hierarchy-edge child '${edge.child}' in block '${childBlock}', expected '${hier.child_block}'`,
+                    message: `hierarchy-edge child '${childKey}' in block '${childBlock}', expected '${hier.child_block}'`,
                     edge,
                 });
             }
@@ -884,9 +1068,13 @@ export function validateRelations(config, relations, itemsByBlock) {
         for (const e of relations) {
             if (e.relation_type !== rt)
                 continue;
-            const arr = adj.get(e.parent) ?? [];
-            arr.push(e.child);
-            adj.set(e.parent, arr);
+            // Cycle adjacency is keyed on the consumer node key (refname for items)
+            // so a structured item and a legacy same-refname string collapse to one
+            // graph node — byte-identical cycle diagnostics on string data.
+            const pk = endpointKey(e.parent);
+            const arr = adj.get(pk) ?? [];
+            arr.push(endpointKey(e.child));
+            adj.set(pk, arr);
         }
         const visited = new Set();
         const onStack = new Set();
@@ -962,7 +1150,7 @@ export function resolveComposition(cwd, lens) {
     }
     const ctx = loadContext(cwd);
     if (!ctx.config) {
-        throw new Error("resolveComposition: no .project/config.json");
+        throw new Error("resolveComposition: no <substrate-dir>/config.json");
     }
     return resolveCompositionInternal(cwd, lens, ctx.config, new Set());
 }