@davidorex/pi-context 0.26.0 → 0.28.1

package/dist/context-sdk.js

@@ -6,14 +6,18 @@
 import { execSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { readBlock, updateItemInBlock } from "./block-api.js";
-import { findUnmaterializedAssets, loadConfig, loadRelations, validateRelations, } from "./context.js";
+import { readBlock, readBlockForDir, updateItemInBlock } from "./block-api.js";
+import { appendRelation, endpointKey, findUnmaterializedAssets, loadConfig, loadRelations, validateRelations, } from "./context.js";
 import { resolveContextDir, SCHEMAS_DIR, schemaPath, schemasDir, tryResolveContextDir } from "./context-dir.js";
+import { loadRegistry, resolveAlias, resolveSubstrateDir } from "./context-registry.js";
+import { cleanGitEnv } from "./git-env.js";
 import { getLensValidators } from "./lens-validator.js";
+import { addressInto, discoverArrayKey, pageArray } from "./read-element.js";
+import { findNestedIdBearingArrays } from "./schema-write.js";
 import { resolveStatusVocabulary } from "./status-vocab.js";
 import { topoSort } from "./topo.js";
 // Re-export substrate SDK so consumers can keep importing through context-sdk.
-export { displayName, edgesForLens, groupByLens, listUncategorized, loadConfig, loadContext, loadRelations, synthesizeFromField, validateRelations, walkDescendants, } from "./context.js";
+export { displayName, edgesForLens, endpointBin, endpointIdentity, endpointKey, groupByLens, listUncategorized, loadConfig, loadContext, loadRelations, normalizeEndpoint, synthesizeFromField, validateRelations, walkDescendants, } from "./context.js";
 export function availableBlocks(cwd) {
     const workflowDir = tryResolveContextDir(cwd);
     if (workflowDir === null)
@@ -265,8 +269,8 @@ export function contextState(cwd) {
     let lastCommit = "unknown";
     let lastCommitMessage = "";
     try {
-        lastCommit = execSync("git log -1 --format=%h", { cwd, encoding: "utf-8" }).trim();
-        lastCommitMessage = execSync("git log -1 --format=%s", { cwd, encoding: "utf-8" }).trim();
+        lastCommit = execSync("git log -1 --format=%h", { cwd, encoding: "utf-8", env: cleanGitEnv() }).trim();
+        lastCommitMessage = execSync("git log -1 --format=%s", { cwd, encoding: "utf-8", env: cleanGitEnv() }).trim();
     }
     catch {
         /* not a git repo or no commits */
@@ -274,7 +278,7 @@ export function contextState(cwd) {
     // Recent commits
     let recentCommits = [];
     try {
-        const log = execSync("git log --oneline -5", { cwd, encoding: "utf-8" }).trim();
+        const log = execSync("git log --oneline -5", { cwd, encoding: "utf-8", env: cleanGitEnv() }).trim();
         if (log)
             recentCommits = log.split("\n");
     }
@@ -525,12 +529,12 @@ export function contextState(cwd) {
 export function currentState(cwd) {
     // Tolerate any substrate-read failure (no .project, malformed config, etc.)
     // by collapsing to the empty state — this is a pure read surface.
-    let idIndex;
+    let index;
     try {
-        idIndex = buildIdIndex(cwd);
+        index = buildIdIndex(cwd);
     }
     catch {
-        idIndex = new Map();
+        index = { dir: cwd, byRefname: new Map(), byOid: new Map(), items: [] };
     }
     let edges;
     try {
@@ -548,13 +552,13 @@ export function currentState(cwd) {
     const bucket = (item) => vocab[String(item.status)] ?? "unknown";
     // ── inFlight: tasks-block items bucketing to in_progress ───────────────────
     const inFlight = [];
-    for (const [id, loc] of idIndex) {
+    for (const loc of index.byRefname.values()) {
         if (loc.block !== "tasks")
             continue;
         if (bucket(loc.item) !== "in_progress")
             continue;
         inFlight.push({
-            id,
+            id: loc.id,
             block: loc.block,
             description: typeof loc.item.description === "string" ? loc.item.description : "",
         });
@@ -565,18 +569,20 @@ export function currentState(cwd) {
     // at unknown ids are treated as satisfied — a dangling edge is a relations
     // integrity concern surfaced by validateRelations, not a blocker here).
     const isCompleted = (taskId) => {
-        const loc = idIndex.get(taskId);
+        const loc = index.byRefname.get(taskId);
         return loc !== undefined && bucket(loc.item) === "complete";
     };
-    const depParentsOf = (taskId) => edges.filter((e) => e.relation_type === "task_depends_on_task" && e.child === taskId).map((e) => e.parent);
-    const incompleteDeps = (taskId) => depParentsOf(taskId).filter((dep) => idIndex.has(dep) && !isCompleted(dep));
+    const depParentsOf = (taskId) => edges
+        .filter((e) => e.relation_type === "task_depends_on_task" && endpointKey(e.child) === taskId)
+        .map((e) => endpointKey(e.parent));
+    const incompleteDeps = (taskId) => depParentsOf(taskId).filter((dep) => index.byRefname.has(dep) && !isCompleted(dep));
     // Collect all to-do (ready/queued) tasks once — drives both blocked + ready
     // derivations. "todo" bucket = planned/queued work (raw status "planned"
     // buckets to todo under STATUS_VOCABULARY_DEFAULTS).
     const plannedTasks = [];
-    for (const [id, loc] of idIndex) {
+    for (const loc of index.byRefname.values()) {
         if (loc.block === "tasks" && bucket(loc.item) === "todo")
-            plannedTasks.push({ id, loc });
+            plannedTasks.push({ id: loc.id, loc });
     }
     // ── blocked: planned tasks with at least one incomplete dep parent ─────────
     const blocked = [];
@@ -595,12 +601,12 @@ export function currentState(cwd) {
     //    P0 > P1 > P2 > P3 (missing priority sorts last) then by id.
     const priorityRank = { P0: 0, P1: 1, P2: 2, P3: 3 };
     const openGaps = [];
-    for (const [id, loc] of idIndex) {
+    for (const loc of index.byRefname.values()) {
         if (loc.block !== "framework-gaps")
             continue;
         if (bucket(loc.item) !== "todo")
             continue;
-        openGaps.push({ id, priority: typeof loc.item.priority === "string" ? loc.item.priority : undefined });
+        openGaps.push({ id: loc.id, priority: typeof loc.item.priority === "string" ? loc.item.priority : undefined });
     }
     openGaps.sort((a, b) => {
         const ra = a.priority !== undefined ? (priorityRank[a.priority] ?? 99) : 99;
@@ -642,12 +648,12 @@ export function currentState(cwd) {
         // Fall back to a phase bucketing to in_progress (phase.json phases[]
         // array-block).
         let inProgressPhase = null;
-        for (const [id, loc] of idIndex) {
+        for (const loc of index.byRefname.values()) {
             if (loc.block !== "phase")
                 continue;
             if (bucket(loc.item) !== "in_progress")
                 continue;
-            inProgressPhase = { id, name: typeof loc.item.name === "string" ? loc.item.name : undefined };
+            inProgressPhase = { id: loc.id, name: typeof loc.item.name === "string" ? loc.item.name : undefined };
             break;
         }
         if (inProgressPhase !== null) {
@@ -660,24 +666,10 @@ export function currentState(cwd) {
     }
     return { focus, inFlight, nextActions: cappedNextActions, blocked };
 }
-/**
- * Discover the single top-level array key in a block payload. Returns null
- * when the block has zero array properties; throws when ambiguous (two or
- * more array properties), since callers cannot proceed without an explicit
- * disambiguation policy. Mirrors the heuristic in
- * scripts/orchestrator/inject-context-items.ts:85-95 — both consumers share
- * the same single-array-key assumption used across .project/ block writes.
- */
-function discoverArrayKey(blockData) {
-    const arrayKeys = Object.entries(blockData).filter(([, v]) => Array.isArray(v));
-    if (arrayKeys.length === 0)
-        return null;
-    if (arrayKeys.length === 1)
-        return arrayKeys[0][0];
-    throw new Error(`filterBlockItems: block has multiple top-level array properties (${arrayKeys
-        .map(([k]) => k)
-        .join(", ")}); array_key per block is not declared in any registry — single-array assumption violated`);
-}
+// discoverArrayKey lives in read-element.ts (the lowest pure layer) and is
+// imported above — ONE copy of the single-top-level-array heuristic shared by
+// filterBlockItems / readBlockPage / serializeForRead. Mirrors the assumption
+// in scripts/orchestrator/inject-context-items.ts used across .project/ writes.
 /**
  * Filter the array items of a block by a predicate. Reads the block via the
  * canonical block-api `readBlock`, discovers the single top-level array key,
@@ -728,28 +720,34 @@ export function filterBlockItems(cwd, blockName, predicate) {
 /**
  * Read a single item from ONE named block by its id, or null if absent.
  * Block-scoped (no cross-substrate idIndex, no prefix-vs-block invariant — that is resolveItemById).
- * Reuses filterBlockItems(id eq) so it inherits readBlock + discoverArrayKey + edge semantics
- * (missing block / multiple top-level arrays THROW; no-array block or id-not-found → null). FGAP-045.
+ * Reads the block then routes id-resolution through the shared addressInto primitive
+ * (id matches `.id` or `.canonical_id`), so block-item lookup uses the same element
+ * addressing as every other read surface. Missing block / multiple top-level arrays
+ * THROW (readBlock + discoverArrayKey via addressInto); no-array block or id-not-found → null. FGAP-045.
  */
 export function readBlockItem(cwd, blockName, id) {
-    const matches = filterBlockItems(cwd, blockName, { field: "id", op: "eq", value: id });
-    return matches.length > 0 ? matches[0] : null;
+    const data = readBlock(cwd, blockName);
+    // A block with multiple top-level arrays must throw (single-array assumption);
+    // addressInto tolerates ambiguity, so probe discoverArrayKey directly first to
+    // preserve the documented throw, then address into the resolved array.
+    discoverArrayKey(data);
+    const hit = addressInto(data, { id });
+    return hit.found ? hit.value : null;
 }
 /**
- * Paginate a block's items. Reuses readBlock + discoverArrayKey. Returns the FULL count as `total`
- * (not the page length) and `hasMore = offset + limit < total`. No-array block → {items:[],total:0,
- * hasMore:false}; offset ≥ total → empty items with correct total. Missing block / multiple top-level
- * arrays propagate the throw (consistent with filterBlockItems). FGAP-045.
+ * Paginate a block's items. Reads the block, discovers its single top-level array,
+ * then routes the slice/total/hasMore math through the shared `pageArray` primitive
+ * (ONE pagination implementation — serializeForRead uses the same). Returns the FULL
+ * count as `total` (not the page length) and `hasMore = offset + limit < total`.
+ * No-array block → {items:[],total:0,hasMore:false}; offset ≥ total → empty items
+ * with correct total. Missing block / multiple top-level arrays propagate the throw
+ * (consistent with filterBlockItems). FGAP-045.
  */
 export function readBlockPage(cwd, blockName, opts = {}) {
-    const offset = opts.offset ?? 0;
-    const limit = opts.limit ?? 50;
     const data = readBlock(cwd, blockName);
     const arrayKey = discoverArrayKey(data);
     const arr = arrayKey ? data[arrayKey] : [];
-    const total = arr.length;
-    const items = arr.slice(offset, offset + limit);
-    return { items, total, hasMore: offset + limit < total };
+    return pageArray(arr, opts);
 }
 /**
  * Read a block and return its single top-level array of items, or [] when the
@@ -768,9 +766,11 @@ function readBlockArray(cwd, blockName) {
 /**
  * Cross-block join (FGAP-043, HYBRID). Mode = exactly one of relationType (edge) XOR
  * leftField+rightField (field). Returns one JoinResult per left item (after leftPredicate),
- * right always an array. Edge mode is DEC-0013-native (relations.json); field mode joins on a
- * shared field value (legacy inline-FK + arbitrary shared fields). Reuses filterBlockItems /
- * readBlock / discoverArrayKey / loadRelations / buildIdIndex.
+ * right always an array. Edge mode is DEC-0013-native (relations.json); field mode is a
+ * DEPRECATED backward-compat path that joins on a shared field value (formerly inline-FK,
+ * now arbitrary shared fields). NO validation uses field mode — cross-block validation is
+ * edge-only since DEC-0036; field mode here is a query convenience, not a reference surface.
+ * Reuses filterBlockItems / readBlock / discoverArrayKey / loadRelations / buildIdIndex.
  */
 export function joinBlocks(cwd, spec) {
     const isEdge = spec.relationType !== undefined;
@@ -803,17 +803,17 @@ export function joinBlocks(cwd, spec) {
     const relationType = spec.relationType;
     const leftEndpoint = spec.leftEndpoint ?? "parent";
     const edges = loadRelations(cwd).filter((e) => e.relation_type === relationType);
-    const idIndex = buildIdIndex(cwd);
+    const index = buildIdIndex(cwd);
     return leftItems.map((left) => {
         const leftId = left.id;
         const right = [];
         if (typeof leftId === "string") {
             for (const e of edges) {
-                const here = leftEndpoint === "parent" ? e.parent : e.child;
+                const here = leftEndpoint === "parent" ? endpointKey(e.parent) : endpointKey(e.child);
                 if (here !== leftId)
                     continue;
-                const otherId = leftEndpoint === "parent" ? e.child : e.parent;
-                const loc = idIndex.get(otherId);
+                const otherId = leftEndpoint === "parent" ? endpointKey(e.child) : endpointKey(e.parent);
+                const loc = index.byRefname.get(otherId);
                 if (loc && loc.block === spec.rightBlock)
                     right.push(loc.item);
             }
@@ -882,29 +882,54 @@ export function expectedBlockForId(id, cfg) {
  * the resolver deterministic without allocating warning channels here.
  */
 export function buildIdIndex(cwd) {
-    const index = new Map();
     const blockDir = tryResolveContextDir(cwd);
-    if (blockDir === null)
+    if (blockDir === null) {
+        // No active pointer — return an empty SubstrateIndex (dir set to cwd so
+        // the surface is still well-formed; substrate_id undefined). Mirrors the
+        // prior empty-Map return.
+        return { dir: cwd, byRefname: new Map(), byOid: new Map(), items: [] };
+    }
+    return buildIdIndexForDir(blockDir, cwd, loadConfig(cwd));
+}
+/**
+ * Build the item-id → location index for an ARBITRARY substrate directory
+ * (the dir-targeted twin of `buildIdIndex`, which resolves the active pointer
+ * dir). Used by the relation porcelain to index a FOREIGN substrate (resolved
+ * via the registry from a `<alias>:` selector) as well as the active substrate.
+ *
+ * `substrateDir` is the absolute substrate directory to scan; `cfg` is that
+ * dir's config (drives the prefix-vs-block invariant via `expectedBlockForId`),
+ * passed by the caller so this function performs no pointer resolution. Reads
+ * each block file via `readBlockForDir` so the version-aware validation hook
+ * fires identically to the active-dir path. Same first-writer-wins collision
+ * semantics + prefix-invariant throw as `buildIdIndex`.
+ */
+export function buildIdIndexForDir(substrateDir, _cwd, cfg) {
+    // `_cwd` is part of the locked F1 signature (the active-dir caller threads its
+    // cwd; the foreign-substrate caller threads the foreign dir) so F2 can resolve
+    // registry-relative concerns from it. F1's body reads config explicitly via
+    // `cfg`, so `_cwd` is currently unused — retained for the forward-compatible
+    // surface rather than dropped and re-added next cycle.
+    const byRefname = new Map();
+    const byOid = new Map();
+    const items = [];
+    const index = {
+        substrate_id: cfg?.substrate_id,
+        dir: substrateDir,
+        byRefname,
+        byOid,
+        items,
+    };
+    if (!fs.existsSync(substrateDir))
         return index;
-    const cfg = loadConfig(cwd);
-    // Phases are an ordinary array-block since DEC-0028: each phase carries a
-    // PHASE-NNN top-level `id` and lives in `phase.json` under the plural
-    // `phases` array key (singular file basename matches phase.schema.json +
-    // the verification.json precedent). The generic block-file scan below
-    // indexes them by id like any other block. When `PHASE-` is registered in
-    // config.block_kinds (canonical_id "phase"), expectedBlockForId resolves
-    // PHASE-NNN ids to block "phase" — matching the file they are found in, so
-    // the prefix-vs-block invariant passes without a dedicated branch.
     // Top-level block files — scan every array property for items with `id`.
-    if (!fs.existsSync(blockDir))
-        return index;
-    for (const file of fs.readdirSync(blockDir)) {
+    for (const file of fs.readdirSync(substrateDir)) {
         if (!file.endsWith(".json"))
             continue;
         const blockName = file.replace(".json", "");
         let data;
         try {
-            data = readBlock(cwd, blockName);
+            data = readBlockForDir(substrateDir, blockName);
         }
         catch {
             continue; // unreadable / malformed block — skip
@@ -924,8 +949,23 @@ export function buildIdIndex(cwd) {
                     throw new Error(`buildIdIndex: ID '${idVal}' found in block '${blockName}' but its prefix maps to block '${expected}'. ` +
                         `Prefix-vs-block-kind invariant violated — this indicates a direct-fs write that bypassed schema validation, or a prefix collision needing explicit resolution.`);
                 }
-                if (!index.has(idVal)) {
-                    index.set(idVal, { block: blockName, arrayKey, item });
+                // `items` carries ONE entry per id-bearing item in scan order (the
+                // iteration surface). `byRefname` is first-writer-wins on refname
+                // collision (one entry per distinct refname) — exactly the prior
+                // single-Map semantics. The locator that lands in `items` is the
+                // same object reference stored under the maps when this is the first
+                // writer for its refname, so iteration and lookup share identity.
+                const loc = { id: idVal, block: blockName, arrayKey, item };
+                items.push(loc);
+                if (!byRefname.has(idVal)) {
+                    byRefname.set(idVal, loc);
+                }
+                // `byOid` — populated for items carrying a string `oid` (DORMANT this
+                // cycle: no F1 consumer reads it). First-writer-wins on oid collision,
+                // mirroring `byRefname`.
+                const oidVal = item.oid;
+                if (typeof oidVal === "string" && oidVal.length > 0 && !byOid.has(oidVal)) {
+                    byOid.set(oidVal, loc);
                 }
             }
         }
@@ -938,7 +978,7 @@ export function buildIdIndex(cwd) {
  * `buildIdIndex` once and reuse the returned map.
  */
 export function resolveItemById(cwd, id) {
-    return buildIdIndex(cwd).get(id) ?? null;
+    return buildIdIndex(cwd).byRefname.get(id) ?? null;
 }
 /**
  * Bulk variant of `resolveItemById` — resolve N ids against a single
@@ -979,10 +1019,275 @@ export function resolveItemsByIds(cwd, ids) {
     for (const id of ids) {
         if (out.has(id))
             continue; // duplicate input — Map dedup semantics
-        out.set(id, index.get(id) ?? null);
+        out.set(id, index.byRefname.get(id) ?? null);
     }
     return out;
 }
+// ── Relation porcelain (selector → structured EdgeEndpoint → raw append) ─────
+/**
+ * Load + JSON-parse a foreign substrate dir's config.json WITHOUT pointer
+ * resolution or AJV validation — best-effort, returns null on absence/parse
+ * failure. Used only to feed `expectedBlockForId`'s prefix invariant when
+ * indexing a foreign substrate in the porcelain; the foreign substrate's own
+ * write path already AJV-validated its config, so a re-validate here would only
+ * add a failure mode to a read.
+ */
+function loadConfigForDirBestEffort(substrateDir) {
+    const p = path.join(substrateDir, "config.json");
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is `selector` a declared lens bin in the active config? Scans every
+ * `config.lenses[].bins[]`. Disambiguates a bare selector that names a bin
+ * (→ `{kind:"lens_bin"}`) from one that names an item refname (→ `{kind:"item"}`).
+ */
+function selectorIsLensBin(cwd, selector) {
+    const cfg = loadConfig(cwd);
+    if (!cfg)
+        return false;
+    for (const lens of cfg.lenses ?? []) {
+        if (lens.bins.includes(selector))
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve one friendly relation selector to a structured `EdgeEndpoint`:
+ *  - `<alias>:<refname>` (alias is a registered substrate alias) → FOREIGN item
+ *    `{kind:"item", substrate_id, oid, refname}` (oid from the foreign index;
+ *    when the foreign refname does not resolve, oid is left as the refname so the
+ *    endpoint round-trips — Cycle 8 resolves foreign endpoints, this cycle only
+ *    forms them; an unresolved foreign endpoint validates as a sentinel).
+ *  - a selector matching a declared lens bin → `{kind:"lens_bin", bin}`.
+ *  - a bare `refname` → SAME-substrate item `{kind:"item", oid, refname}` (oid
+ *    from the active index; falls back to refname when unresolved so an
+ *    edge to a not-yet-filed item is still expressible).
+ *
+ * NOTE: the `<alias>:` branch is tried first so an alias-prefixed selector is
+ * never misread as a bare refname containing a colon.
+ */
+export function resolveRelationSelector(cwd, selector) {
+    // `<alias>:<refname>` — only when the prefix is a REGISTERED alias (a bare
+    // refname that happens to contain a colon is not an alias selector).
+    const colon = selector.indexOf(":");
+    if (colon > 0) {
+        const alias = selector.slice(0, colon);
+        const refname = selector.slice(colon + 1);
+        const substrate_id = resolveAlias(cwd, alias);
+        if (substrate_id !== null) {
+            const dir = resolveSubstrateDir(cwd, substrate_id);
+            let oid = refname;
+            if (dir !== null) {
+                const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+                const foreignIndex = buildIdIndexForDir(abs, abs, loadConfigForDirBestEffort(abs));
+                const loc = foreignIndex.byRefname.get(refname);
+                if (loc && typeof loc.item.oid === "string")
+                    oid = loc.item.oid;
+            }
+            return { kind: "item", substrate_id, oid, refname };
+        }
+    }
+    // A declared lens bin → lens_bin endpoint (never an item).
+    if (selectorIsLensBin(cwd, selector)) {
+        return { kind: "lens_bin", bin: selector };
+    }
+    // Bare refname → same-substrate item. oid from the active index; falls back
+    // to the refname itself when the item is not yet filed.
+    const index = buildIdIndex(cwd);
+    const loc = index.byRefname.get(selector);
+    const oid = loc && typeof loc.item.oid === "string" ? loc.item.oid : selector;
+    return { kind: "item", oid, refname: selector };
+}
+/**
+ * Friendly-selector relation append (Cycle 5 porcelain). Resolves `parent` /
+ * `child` STRING selectors to structured `EdgeEndpoint`s via
+ * `resolveRelationSelector`, then delegates to the raw `appendRelation` plumbing
+ * (atomic, AJV-validated, exact-duplicate no-op — same deferred-integrity
+ * semantics). Keeps the string param surface its callers (the append-relation
+ * Pi tool + the orchestrator CLI) already expose.
+ *
+ * Returns `{ appended, edge }` where `edge` is the RESOLVED structured edge
+ * actually written (so callers can report / dry-run-validate the structured
+ * form).
+ */
+export function appendRelationByRef(cwd, rel, ctx) {
+    const edge = {
+        parent: resolveRelationSelector(cwd, rel.parent),
+        child: resolveRelationSelector(cwd, rel.child),
+        relation_type: rel.relation_type,
+        ...(rel.ordinal !== undefined ? { ordinal: rel.ordinal } : {}),
+    };
+    const { appended } = appendRelation(cwd, edge, ctx);
+    return { appended, edge };
+}
+/**
+ * Build (or fetch from the per-pass cache) the {@link SubstrateIndex} for a
+ * REGISTERED foreign substrate. Resolves the substrate dir from the registry,
+ * absolutizes it against `cwd`, and builds the index once per substrate_id within
+ * a validation pass (the `foreignCache` is keyed by substrate_id). A build that
+ * THROWS (malformed foreign block / prefix-invariant violation) is caught and
+ * returns null — the caller resolves the ref `dangling` rather than crashing the
+ * whole validation pass on one bad foreign substrate.
+ *
+ * Returns null when the substrate_id is not registered (→ caller `unregistered`)
+ * or when the foreign-index build throws (→ caller `dangling`). A registered
+ * substrate whose dir is missing on disk builds an empty index (not null) via
+ * `buildIdIndexForDir`'s existsSync guard, so its endpoints resolve `dangling`.
+ */
+function foreignIndexFor(cwd, substrate_id, foreignCache) {
+    const cached = foreignCache.get(substrate_id);
+    if (cached)
+        return cached;
+    const dir = resolveSubstrateDir(cwd, substrate_id);
+    if (dir === null)
+        return null; // not registered → unregistered (caller)
+    const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+    try {
+        const index = buildIdIndexForDir(abs, abs, loadConfigForDirBestEffort(abs));
+        foreignCache.set(substrate_id, index);
+        return index;
+    }
+    catch {
+        // Malformed foreign block / prefix-invariant throw — degrade to dangling.
+        // Do NOT cache the failure (a transient read could differ); the per-pass
+        // cost of a re-throw is bounded by the edge count into this substrate.
+        return null;
+    }
+}
+/**
+ * Classify a single edge endpoint (legacy string OR structured) into one of the
+ * four {@link ResolveStatus} values — the load-bearing F2 resolver wired into
+ * `validateContext`'s edge loop + the `validateRelations` `resolve?` hook.
+ *
+ * Algorithm (the locked Cycle-8 design):
+ *  1. A structured `{kind:"lens_bin"}` endpoint → `{status:"active",
+ *     endpointKind:"lens_bin"}` with NO item lookup (a lens_bin never routes
+ *     through item resolution — the corruption-risk surface, Constraint 4).
+ *  2. An item endpoint WITH A LOCATOR — a structured `substrate_id`, OR a STRING
+ *     of the form `<alias>:<refname>` whose `<alias>` prefix is a REGISTERED
+ *     alias — resolves against the named FOREIGN substrate: substrate_id/alias
+ *     NOT in the registry → `unregistered`; registered → build (cached) the
+ *     foreign index → look up by `oid` (structured locator carrying an oid) else
+ *     by `refname` in `byOid`/`byRefname` → found `foreign` / absent `dangling`.
+ *     A foreign-index build that throws → `dangling` (never a crash).
+ *  3. An item endpoint with NO locator — a bare oid or a bare refname (a string
+ *     with no `:` alias-prefix) — resolves against the ACTIVE index ONLY → found
+ *     `active` / absent `dangling`.
+ *
+ * The alias-string parse is ATTEMPTED FIRST on any string containing a `:`
+ * (mirroring `resolveRelationSelector`): the `<x>` in `<x>:<y>` is treated as an
+ * alias candidate, so such a string is an aliased-item locator (step 2), NOT a
+ * bare refname (step 3). If `<x>` is NOT a registered alias → `unregistered`. So
+ * today's `project:FGAP-153` (the `project` alias is not registered until Phase H)
+ * → `unregistered`. The real 30 are therefore `unregistered` pre-H and flip to
+ * `foreign` once Phase H registers the `project` alias (the count/total stay
+ * unchanged at reclassification — see the note in `validateContext`).
+ *
+ * `opts.activeIndex` lets the caller pass a pre-built active index (built once per
+ * validation pass); `opts.foreignCache` memoizes foreign indices per substrate_id
+ * within the pass (so N edges into one foreign substrate build its index ONCE).
+ */
+export function resolveRef(cwd, ref, opts) {
+    const foreignCache = opts?.foreignCache ?? new Map();
+    const activeIndex = opts?.activeIndex ?? buildIdIndex(cwd);
+    // (1) lens_bin endpoint — no item lookup.
+    if (typeof ref !== "string" && ref.kind === "lens_bin") {
+        return { status: "active", endpointKind: "lens_bin" };
+    }
+    // Derive the locator + lookup keys.
+    //  - structured item: substrate_id (locator), oid, refname.
+    //  - string: attempt `<alias>:<refname>` parse — a `:` whose prefix is a
+    //    REGISTERED alias yields a foreign locator; otherwise no locator (step 3
+    //    looks up the whole string in the active index).
+    let substrate_id;
+    let oid;
+    let refname;
+    // A string carrying a `:` is treated as a `<alias>:<refname>` LOCATOR
+    // candidate (the alias parse is ATTEMPTED): the prefix is an alias that
+    // either resolves (→ foreign locator) or does NOT (→ `unregistered` — the
+    // pre-Phase-H state of the 30 `project:` strings, whose `project` alias is
+    // not yet registered). A registered alias yields a foreign `substrate_id`
+    // locator + the post-colon refname; an UNregistered alias is flagged with the
+    // `aliasUnregistered` sentinel so step (2)/(3) below routes it to
+    // `unregistered` rather than the active index. A string with NO `:` is a bare
+    // active refname (step 3).
+    let aliasUnregistered = false;
+    if (typeof ref === "string") {
+        const colon = ref.indexOf(":");
+        if (colon > 0) {
+            const alias = ref.slice(0, colon);
+            const aliasSubId = resolveAlias(cwd, alias);
+            if (aliasSubId !== null) {
+                // Registered alias → foreign locator; refname is the post-colon part.
+                substrate_id = aliasSubId;
+                refname = ref.slice(colon + 1);
+            }
+            else {
+                // `:`-prefix is an alias CANDIDATE but the alias is NOT registered →
+                // `unregistered` (NOT active-dangling). The whole string is retained as
+                // the refname for diagnostics; no active-index lookup is performed.
+                aliasUnregistered = true;
+                refname = ref;
+            }
+        }
+        else {
+            // No colon — bare active refname.
+            refname = ref;
+        }
+    }
+    else {
+        // Structured item endpoint.
+        substrate_id = ref.substrate_id;
+        oid = ref.oid;
+        refname = ref.refname;
+    }
+    // A `<alias>:<refname>` string whose alias is NOT registered → unregistered
+    // (locked decision 1: the alias parse is attempted; a missing alias is the
+    // pre-Phase-H state of the 30, NOT an active-substrate dangling lookup).
+    if (aliasUnregistered) {
+        return { status: "unregistered", endpointKind: "item", refname };
+    }
+    // (2) item endpoint WITH a foreign locator (structured substrate_id OR an
+    // alias that resolved to one).
+    if (substrate_id !== undefined) {
+        const index = foreignIndexFor(cwd, substrate_id, foreignCache);
+        if (index === null) {
+            // substrate_id not registered → unregistered (a build-throw also returns
+            // null, but foreignIndexFor only returns null on UNREGISTERED when the
+            // registry lacks the id; the throw path returns null too — disambiguate
+            // by re-checking the registry to keep the two outcomes distinct).
+            const dir = resolveSubstrateDir(cwd, substrate_id);
+            return dir === null
+                ? { status: "unregistered", endpointKind: "item", substrate_id, oid, refname }
+                : { status: "dangling", endpointKind: "item", substrate_id, oid, refname };
+        }
+        // Look up by oid first (structured locator carrying an oid), else by refname.
+        let loc;
+        if (typeof oid === "string" && oid.length > 0)
+            loc = index.byOid.get(oid);
+        if (!loc && typeof refname === "string" && refname.length > 0)
+            loc = index.byRefname.get(refname);
+        return loc
+            ? { status: "foreign", endpointKind: "item", substrate_id, oid, refname, loc }
+            : { status: "dangling", endpointKind: "item", substrate_id, oid, refname };
+    }
+    // (3) item endpoint with NO locator → ACTIVE index only.
+    let loc;
+    if (typeof oid === "string" && oid.length > 0)
+        loc = activeIndex.byOid.get(oid);
+    if (!loc && typeof refname === "string" && refname.length > 0)
+        loc = activeIndex.byRefname.get(refname);
+    return loc
+        ? { status: "active", endpointKind: "item", oid, refname, loc }
+        : { status: "dangling", endpointKind: "item", oid, refname };
+}
 /**
  * Field-equality predicate for config-declared invariants. Mirrors the
  * composition-lens `where` semantics (context.ts:773-778): the item
@@ -1023,13 +1328,55 @@ export function validateContext(cwd) {
     // Note: buildIdIndex enforces the prefix-vs-block invariant and may throw
     // on corrupted state; that surfaces as a hard failure to validateContext
     // callers (intended — corrupted IDs are not recoverable cross-ref issues).
-    const idIndex = buildIdIndex(cwd);
+    const index = buildIdIndex(cwd);
     // ── Edge integrity (DEC-0013 closure-table reference surface) ─────────────
     // Load config + relations; both absent in a pre-bootstrap project, in which
     // case edge checks (and the relocated invariants, which depend on edges)
     // are skipped gracefully — there is no edge model to validate yet.
     const config = loadConfig(cwd);
     const relations = config ? loadRelations(cwd) : [];
+    // ── SoT-drift invariant (content-addressed substrate identity, Cycle 4) ───
+    // When the active config declares a `substrate_id`, the project-root
+    // registry (.pi-context-registry.json) MUST carry an entry for that id whose
+    // `dir` resolves to the active substrate dir. A missing entry or a dir
+    // mismatch means the registry has drifted from the active substrate's sole
+    // SoT (config.substrate_id) and is an ERROR. When `config.substrate_id` is
+    // ABSENT (a pre-identity / pre-Phase-H substrate), the check SKIPS — read
+    // the field directly off the config rather than via substrateIdFor (which
+    // THROWS on absence) so an un-migrated substrate still validates cleanly.
+    if (config) {
+        const substrateId = config.substrate_id;
+        if (typeof substrateId === "string" && substrateId.length > 0) {
+            const registry = loadRegistry(cwd);
+            const entry = registry?.substrates?.[substrateId];
+            if (!entry) {
+                issues.push({
+                    severity: "error",
+                    message: `config.substrate_id '${substrateId}' is not registered in the project-root .pi-context-registry.json — register the active substrate (registerSubstrate) so foreign-locator resolution can find it`,
+                    block: "config",
+                    field: "substrate_id",
+                    code: "substrate_id_unregistered",
+                });
+            }
+            else {
+                const registeredAbs = path.resolve(cwd, entry.dir);
+                // resolveContextDir returns path.join(cwd, contextDir), which is
+                // RELATIVE when cwd is relative (e.g. '.'). Absolutize it so the
+                // comparison is absolute-vs-absolute and a relative cwd can't
+                // produce a false-positive drift error.
+                const activeAbs = path.resolve(resolveContextDir(cwd));
+                if (registeredAbs !== activeAbs) {
+                    issues.push({
+                        severity: "error",
+                        message: `config.substrate_id '${substrateId}' registry entry dir '${entry.dir}' (resolved ${registeredAbs}) does not match the active substrate dir ${activeAbs} — the registry has drifted from the active substrate's SoT`,
+                        block: "config",
+                        field: "substrate_id",
+                        code: "substrate_id_registry_mismatch",
+                    });
+                }
+            }
+        }
+    }
     // `config` present → run edge-integrity + the relocated invariants. The
     // invariants detect MISSING edges (completed task without a verification
     // edge; decision without a forcing-artifact edge), so they must run even
@@ -1038,21 +1385,57 @@ export function validateContext(cwd) {
     // no-op on empty relations, so it needs no separate guard.
     if (config) {
         const registeredRelTypes = new Set((config.relation_types ?? []).map((rt) => rt.canonical_id));
+        // Per-pass foreign-index cache (Constraint 3): N foreign edges into the same
+        // registered substrate build that substrate's index ONCE within this pass.
+        const foreignCache = new Map();
+        // Resolver bound to this pass's cwd + active index + foreign cache; supplied
+        // to validateRelations so its lens/hierarchy resolution can see foreign items.
+        const resolve = (ref) => resolveRef(cwd, ref, { activeIndex: index, foreignCache });
         for (const edge of relations) {
-            if (!idIndex.has(edge.parent)) {
+            // F2 severity split (DEC §F2): every endpoint is classified by resolveRef
+            // into active | foreign | dangling | unregistered. active/foreign/lens_bin
+            // → no issue; unregistered → ERROR (`edge_endpoint_unregistered`); dangling
+            // → ERROR (`edge_endpoint_dangling`). The two new codes REPLACE the prior
+            // inline "does not resolve" message — the intended reclassification of the
+            // cross-substrate (`<alias>:`) strings (their alias is unregistered pre-H).
+            const parentKey = endpointKey(edge.parent);
+            const childKey = endpointKey(edge.child);
+            const parentRes = resolve(edge.parent);
+            const childRes = resolve(edge.child);
+            if (parentRes.status === "unregistered") {
                 issues.push({
                     severity: "error",
-                    message: `Edge parent '${edge.parent}' (relation_type '${edge.relation_type}') does not resolve to any item`,
+                    message: `Edge parent '${parentKey}' (relation_type '${edge.relation_type}') names an unregistered substrate alias/id`,
                     block: "relations",
-                    field: `${edge.parent}->${edge.child}`,
+                    field: `${parentKey}->${childKey}`,
+                    code: "edge_endpoint_unregistered",
                 });
             }
-            if (!idIndex.has(edge.child)) {
+            else if (parentRes.status === "dangling") {
                 issues.push({
                     severity: "error",
-                    message: `Edge child '${edge.child}' (relation_type '${edge.relation_type}') does not resolve to any item`,
+                    message: `Edge parent '${parentKey}' (relation_type '${edge.relation_type}') does not resolve to any item`,
                     block: "relations",
-                    field: `${edge.parent}->${edge.child}`,
+                    field: `${parentKey}->${childKey}`,
+                    code: "edge_endpoint_dangling",
+                });
+            }
+            if (childRes.status === "unregistered") {
+                issues.push({
+                    severity: "error",
+                    message: `Edge child '${childKey}' (relation_type '${edge.relation_type}') names an unregistered substrate alias/id`,
+                    block: "relations",
+                    field: `${parentKey}->${childKey}`,
+                    code: "edge_endpoint_unregistered",
+                });
+            }
+            else if (childRes.status === "dangling") {
+                issues.push({
+                    severity: "error",
+                    message: `Edge child '${childKey}' (relation_type '${edge.relation_type}') does not resolve to any item`,
+                    block: "relations",
+                    field: `${parentKey}->${childKey}`,
+                    code: "edge_endpoint_dangling",
                 });
             }
             if (!registeredRelTypes.has(edge.relation_type)) {
@@ -1060,7 +1443,7 @@ export function validateContext(cwd) {
                     severity: "error",
                     message: `Edge relation_type '${edge.relation_type}' is not registered in config.relation_types`,
                     block: "relations",
-                    field: `${edge.parent}->${edge.child}`,
+                    field: `${parentKey}->${childKey}`,
                 });
             }
         }
@@ -1080,24 +1463,32 @@ export function validateContext(cwd) {
                 continue; // unregistered relation_type already reported above
             if (!rt.source_kinds && !rt.target_kinds)
                 continue; // metadata absent → unchecked
-            const parentLoc = idIndex.get(edge.parent);
-            const childLoc = idIndex.get(edge.child);
+            const parentKey = endpointKey(edge.parent);
+            const childKey = endpointKey(edge.child);
+            // Use the resolved location for item endpoints (active OR foreign), so a
+            // foreign item's block is kind-checked against source/target_kinds too. A
+            // lens_bin endpoint (endpointKind:"lens_bin") carries no loc and is skipped
+            // — it never routes through item-block resolution.
+            const parentRes = resolve(edge.parent);
+            const childRes = resolve(edge.child);
+            const parentLoc = parentRes.loc;
+            const childLoc = childRes.loc;
             if (parentLoc &&
                 rt.source_kinds &&
                 !(rt.source_kinds.includes("*") || rt.source_kinds.includes(parentLoc.block))) {
                 issues.push({
                     severity: "error",
-                    message: `Edge ${edge.parent} -> ${edge.child}: source kind '${parentLoc.block}' not in source_kinds [${rt.source_kinds.join(", ")}] for relation_type '${edge.relation_type}'`,
+                    message: `Edge ${parentKey} -> ${childKey}: source kind '${parentLoc.block}' not in source_kinds [${rt.source_kinds.join(", ")}] for relation_type '${edge.relation_type}'`,
                     block: "relations",
-                    field: `${edge.parent}->${edge.child}`,
+                    field: `${parentKey}->${childKey}`,
                 });
             }
             if (childLoc && rt.target_kinds && !(rt.target_kinds.includes("*") || rt.target_kinds.includes(childLoc.block))) {
                 issues.push({
                     severity: "error",
-                    message: `Edge ${edge.parent} -> ${edge.child}: target kind '${childLoc.block}' not in target_kinds [${rt.target_kinds.join(", ")}] for relation_type '${edge.relation_type}'`,
+                    message: `Edge ${parentKey} -> ${childKey}: target kind '${childLoc.block}' not in target_kinds [${rt.target_kinds.join(", ")}] for relation_type '${edge.relation_type}'`,
                     block: "relations",
-                    field: `${edge.parent}->${edge.child}`,
+                    field: `${parentKey}->${childKey}`,
                 });
             }
         }
@@ -1107,11 +1498,11 @@ export function validateContext(cwd) {
         // resolution above is the authoritative reference-integrity surface, so
         // merging validateRelations' resolution codes too would double-report).
         const itemsByBlock = {};
-        for (const [id, loc] of idIndex) {
-            (itemsByBlock[loc.block] ??= []).push({ id, ...loc.item });
+        for (const loc of index.byRefname.values()) {
+            (itemsByBlock[loc.block] ??= []).push({ id: loc.id, ...loc.item });
         }
         try {
-            const relResult = validateRelations(config, relations, itemsByBlock);
+            const relResult = validateRelations(config, relations, itemsByBlock, resolve);
             for (const ri of relResult.issues) {
                 if (ri.code !== "edge_cycle_detected")
                     continue;
@@ -1142,9 +1533,10 @@ export function validateContext(cwd) {
             for (const edge of relations) {
                 if (!relTypeSet.has(edge.relation_type))
                     continue;
-                satisfied.add(inv.direction === "as_parent" ? edge.parent : edge.child);
+                satisfied.add(inv.direction === "as_parent" ? endpointKey(edge.parent) : endpointKey(edge.child));
             }
-            for (const [id, loc] of idIndex) {
+            for (const loc of index.byRefname.values()) {
+                const id = loc.id;
                 if (loc.block !== inv.block)
                     continue;
                 if (!matchesWhere(loc.item, inv.where))
@@ -1177,7 +1569,8 @@ export function validateContext(cwd) {
             if (inv.class !== "status-consistency")
                 continue;
             const relSet = new Set(inv.relation_types);
-            for (const [id, loc] of idIndex) {
+            for (const loc of index.byRefname.values()) {
+                const id = loc.id;
                 if (loc.block !== inv.block)
                     continue;
                 if (inv.when_bucket && bucketOf(loc.item) !== inv.when_bucket)
@@ -1186,10 +1579,10 @@ export function validateContext(cwd) {
                     if (!relSet.has(edge.relation_type))
                         continue;
                     const selfIsParent = inv.direction === "as_parent";
-                    if ((selfIsParent ? edge.parent : edge.child) !== id)
+                    if ((selfIsParent ? endpointKey(edge.parent) : endpointKey(edge.child)) !== id)
                         continue;
-                    const otherId = selfIsParent ? edge.child : edge.parent;
-                    const otherLoc = idIndex.get(otherId);
+                    const otherId = selfIsParent ? endpointKey(edge.child) : endpointKey(edge.parent);
+                    const otherLoc = index.byRefname.get(otherId);
                     if (!otherLoc)
                         continue; // dangling endpoint handled by edge-integrity above
                     const otherBucket = bucketOf(otherLoc.item);
@@ -1218,7 +1611,8 @@ export function validateContext(cwd) {
     // key (recognized) and is NOT flagged; only a value with NO key is. Warning-only.
     {
         const statusVocab = resolveStatusVocabulary(cwd);
-        for (const [sid, sloc] of idIndex) {
+        for (const sloc of index.byRefname.values()) {
+            const sid = sloc.id;
             const sval = sloc.item.status;
             if (sval === undefined || sval === null)
                 continue;
@@ -1233,6 +1627,47 @@ export function validateContext(cwd) {
             }
         }
     }
+    // ── Nested id-bearing array warning (content-addressed substrate identity,
+    // Cycle 9.2) ─────────────────────────────────────────────────────────────
+    // Schema-level, independent of block DATA + config: enumerate the active
+    // substrate's installed schemas and flag every array property at nesting
+    // depth ≥ 1 whose item shape carries an `id` — a relationship-as-embedding
+    // that should be promoted to a top-level entity + membership edge (Phase H).
+    // Non-fatal (warning), so it raises the warning count only and never flips
+    // status to "invalid" by itself. Runs whether or not config is present;
+    // skips cleanly when the schemas dir is absent (pre-bootstrap substrate) and
+    // is best-effort per-file (an unparseable / unreadable schema is skipped
+    // rather than failing the whole project validate).
+    {
+        // Resolve the substrate dir via tryResolveContextDir (returns null when no
+        // pointer exists) rather than schemasDir, whose resolveContextDir THROWS on a
+        // pointer-less cwd — validateContext must degrade cleanly there, not throw.
+        const ctxRoot = tryResolveContextDir(cwd);
+        const schemasDirPath = ctxRoot === null ? null : path.join(ctxRoot, SCHEMAS_DIR);
+        if (schemasDirPath !== null && fs.existsSync(schemasDirPath)) {
+            for (const file of fs.readdirSync(schemasDirPath).sort()) {
+                if (!file.endsWith(".schema.json"))
+                    continue;
+                const schemaName = file.slice(0, -".schema.json".length);
+                let parsed;
+                try {
+                    parsed = JSON.parse(fs.readFileSync(path.join(schemasDirPath, file), "utf-8"));
+                }
+                catch {
+                    continue; // unreadable / non-JSON schema — not this pass's concern
+                }
+                for (const fieldPath of findNestedIdBearingArrays(parsed)) {
+                    issues.push({
+                        severity: "warning",
+                        message: `nested id-bearing array '${fieldPath}' — promote to a top-level entity + membership edge (Phase H)`,
+                        block: schemaName,
+                        field: fieldPath,
+                        code: "nested_id_bearing_array",
+                    });
+                }
+            }
+        }
+    }
     // Lens-validator dispatch (Step 7 / pi-context Divergence 3): iterate every
     // validator registered via registerLensValidator and merge its issues into
     // the project-validation result. Validators are guarded individually so a