@davidorex/pi-context 0.31.0 → 0.32.0

package/dist/index.js

@@ -9,17 +9,18 @@ import { fileURLToPath } from "node:url";
 import { forEachBlockArray, readBlock, readBlockForDir, writeBlockForDir } from "./block-api.js";
 import { computeContentHash, computeFileContentHash } from "./content-hash.js";
 import { adoptConception, installedBlockDestPath, installedSchemaDestPath, loadConfig, loadContext, mergeCatalogRegistries, reconcileActiveSubstrateRegistration, writeConfig, writeSkeletonConfig, } from "./context.js";
-import { BootstrapNotFoundError, flipBootstrapPointer, migrationsPathForDir, resolveContextDir, SCHEMAS_DIR, schemasDir, tryResolveContextDir, writeBootstrapPointer, } from "./context-dir.js";
+import { BootstrapNotFoundError, flipBootstrapPointer, migrationsPathForDir, mintSubstrateId, pendingBlockedPathForDir, resolveContextDir, SCHEMAS_DIR, schemasDir, tryResolveContextDir, writeBootstrapPointer, } from "./context-dir.js";
+import { registerSubstrate } from "./context-registry.js";
 import { contextState, findAppendableBlocks, validateContext } from "./context-sdk.js";
 import { cleanGitEnv } from "./git-env.js";
 import { buildCurationSuggestions, loadLensView, renderLensView } from "./lens-view.js";
 import { buildFreshRegistryWithChain, getProjectMigrationRegistryForDir, invalidateMigrationRegistryForDir, } from "./migration-registry-loader.js";
-import { appendMigrationDeclForDir, loadMigrationsFileForDir } from "./migrations-store.js";
+import { appendMigrationDeclForDir, loadMigrationsFileForDir, seedCatalogConfigMigrationDecls, } from "./migrations-store.js";
 import { getObject, putObject } from "./object-store.js";
 import { registerAll } from "./ops-registry.js";
 import { buildOrientationBlock, skillsDir } from "./orientation.js";
 import { loadPendingBlockedForDir, reconcilePendingBlockedForDir, } from "./pending-blocked-store.js";
-import { listRoadmaps, loadRoadmap, renderRoadmap, validateRoadmaps } from "./roadmap-plan.js";
+import { loadRoadmap, renderRoadmap, validateRoadmap } from "./roadmap-plan.js";
 import { mergeSchema } from "./schema-merge.js";
 import { runMigrations } from "./schema-migrations.js";
 import { ValidationError, validate, validateBlockWithMigrationForDir } from "./schema-validator.js";
@@ -647,8 +648,42 @@ function simulateResyncOutcome(destRoot, samplesRoot, sourceFile, destFile, name
     const catalogVersion = readDeclaredVersion(sourceFile);
     const installedVersion = readDeclaredVersion(destFile);
     // Arm 1 — same version (or either unreadable / non-versioned): no transition
-    // to migrate across, the live path overwrites verbatim → resynced, no decls.
+    // to migrate across. Mirrors the live path 1:1 — a populated block is
+    // re-validated in memory against the incoming catalog body, and a failure
+    // predicts blocked (validation-failed, per-item failures); otherwise the
+    // live path overwrites verbatim → resynced, no decls.
     if (installedVersion === catalogVersion || catalogVersion === undefined || installedVersion === undefined) {
+        const sameVersionBlockFile = installedBlockDestPath(destRoot, name);
+        if (fs.existsSync(sameVersionBlockFile)) {
+            let sameVersionBlockData;
+            let sameVersionHasItems = false;
+            try {
+                sameVersionBlockData = JSON.parse(fs.readFileSync(sameVersionBlockFile, "utf-8"));
+                forEachBlockArray(sameVersionBlockData, (_arrayKey, arr) => {
+                    if (arr.length > 0)
+                        sameVersionHasItems = true;
+                });
+            }
+            catch {
+                sameVersionHasItems = true; // unreadable — same safety default as the live path
+            }
+            if (sameVersionHasItems) {
+                try {
+                    const catalogSchema = JSON.parse(fs.readFileSync(sourceFile, "utf-8"));
+                    validate(catalogSchema, sameVersionBlockData, name);
+                }
+                catch (err) {
+                    const failures = err instanceof ValidationError
+                        ? mapValidationFailures(err.errors, sameVersionBlockData)
+                        : [{ instancePath: "", keyword: "error", message: String(err) }];
+                    return {
+                        outcome: "blocked",
+                        wouldRegister: [],
+                        detail: { reason: "validation-failed", from: installedVersion, to: catalogVersion, failures },
+                    };
+                }
+            }
+        }
         return { outcome: "resynced", wouldRegister: [] };
     }
     // Arm 2 — version bump with NO shipped chain reaching the catalog version: the
@@ -876,11 +911,67 @@ function resyncSchema(destRoot, samplesRoot, sourceFile, destFile, name) {
         return entry;
     };
     // (A) Same version (or either version unreadable / non-versioned): there is no
-    // version transition to migrate across, so the drift is description-only —
-    // safe to overwrite the schema verbatim. Items are unaffected by a same-
-    // version schema body change (the version is the migration contract). No
+    // version transition to migrate across. A verbatim overwrite is safe only
+    // when the existing block items still conform to the INCOMING catalog body —
+    // a same-version change that narrows validity (a dropped property under
+    // additionalProperties:false, an added required, a narrowed enum) would
+    // otherwise silently invalidate the block. Populated blocks are therefore
+    // re-validated against the incoming body IN MEMORY before any write, and a
+    // failure refuses the resync (blocked, per-item failures, pending-blocked
+    // recorded) — mirroring the version-bump path's validate-or-refuse
+    // discipline. Nothing has been written when the refusal fires, so the
+    // schema file, block file, and migrations.json are all byte-unchanged. No
     // migration is registered on this arm, so it reports an empty decl list.
     if (installedVersion === catalogVersion || catalogVersion === undefined || installedVersion === undefined) {
+        const sameVersionBlockFile = installedBlockDestPath(destRoot, name);
+        if (fs.existsSync(sameVersionBlockFile)) {
+            let sameVersionBlockData;
+            let sameVersionHasItems = false;
+            try {
+                sameVersionBlockData = JSON.parse(fs.readFileSync(sameVersionBlockFile, "utf-8"));
+                forEachBlockArray(sameVersionBlockData, (_arrayKey, arr) => {
+                    if (arr.length > 0)
+                        sameVersionHasItems = true;
+                });
+            }
+            catch {
+                // Unreadable block — safety default: treat as populated and route it
+                // through the validate path (which throws → blocked).
+                sameVersionHasItems = true;
+            }
+            if (sameVersionHasItems) {
+                try {
+                    const catalogSchema = JSON.parse(fs.readFileSync(sourceFile, "utf-8"));
+                    validate(catalogSchema, sameVersionBlockData, name);
+                }
+                catch (err) {
+                    // Classify the refusal (FGAP-115): only an AJV ValidationError is an
+                    // item-validation failure; any other throw (unreadable catalog body,
+                    // a write-boundary precondition) is `write-failed` — no pending entry,
+                    // so the marker/pending pipeline (validation-only consequences) never
+                    // fires for it.
+                    if (err instanceof ValidationError) {
+                        const failures = mapValidationFailures(err.errors, sameVersionBlockData);
+                        return {
+                            status: "blocked",
+                            registeredMigrations: [],
+                            blockedDetail: { reason: "validation-failed", from: installedVersion, to: catalogVersion, failures },
+                            pendingEntry: buildPendingEntry("validation-failed", [], failures),
+                        };
+                    }
+                    return {
+                        status: "blocked",
+                        registeredMigrations: [],
+                        blockedDetail: {
+                            reason: "write-failed",
+                            from: installedVersion,
+                            to: catalogVersion,
+                            failures: [{ instancePath: "", keyword: "error", message: String(err) }],
+                        },
+                    };
+                }
+            }
+        }
         fs.copyFileSync(sourceFile, destFile);
         return { status: "resynced", registeredMigrations: [] };
     }
@@ -910,14 +1001,14 @@ function resyncSchema(destRoot, samplesRoot, sourceFile, destFile, name) {
     // throws on collision). Registration is required BEFORE the validate+migrate
     // call so the loaded registry carries the forward edge.
     const existing = loadMigrationsFileForDir(destRoot);
-    const present = new Set((existing?.migrations ?? []).map((m) => `${m.schemaName}${m.fromVersion}`));
+    const present = new Set((existing?.migrations ?? []).map((m) => `${m.schemaName}\u0000${m.fromVersion}`));
     // Accumulate the decls THIS call actually appends (the not-already-present
     // subset), reported as the { schema, from, to } shape for the caller to
     // surface (FGAP-050). On the blocked rollback path below this list is
     // discarded and [] is returned (post-rollback truth: nothing stuck).
     const registeredMigrations = [];
     for (const decl of chain) {
-        const key = `${decl.schemaName}${decl.fromVersion}`;
+        const key = `${decl.schemaName}\u0000${decl.fromVersion}`;
         if (present.has(key))
             continue;
         appendMigrationDeclForDir(destRoot, decl);
@@ -998,14 +1089,30 @@ function resyncSchema(destRoot, samplesRoot, sourceFile, destFile, name) {
         // blocked detail records the validation-failed reason + the version pair + the
         // per-item failures (a single synthetic failure for a non-AJV throw) so the
         // caller surfaces WHY the resync refused (TASK-048).
-        const failures = err instanceof ValidationError
-            ? mapValidationFailures(err.errors, blockData)
-            : [{ instancePath: "", keyword: "error", message: String(err) }];
+        // Classify the refusal (FGAP-115): only an AJV ValidationError means the
+        // migrated items fail the catalog schema. Any other throw — the mandatory
+        // identity stamp refusing a substrate with no substrate_id, an I/O failure —
+        // is `write-failed`: the items were never flagged invalid, so no pending
+        // entry is built and the marker/pending pipeline (validation-only
+        // consequences) never fires.
+        if (err instanceof ValidationError) {
+            const failures = mapValidationFailures(err.errors, blockData);
+            return {
+                status: "blocked",
+                registeredMigrations: [],
+                blockedDetail: { reason: "validation-failed", from: installedVersion, to: catalogVersion, failures },
+                pendingEntry: buildPendingEntry("validation-failed", chain, failures),
+            };
+        }
         return {
             status: "blocked",
             registeredMigrations: [],
-            blockedDetail: { reason: "validation-failed", from: installedVersion, to: catalogVersion, failures },
-            pendingEntry: buildPendingEntry("validation-failed", chain, failures),
+            blockedDetail: {
+                reason: "write-failed",
+                from: installedVersion,
+                to: catalogVersion,
+                failures: [{ instancePath: "", keyword: "error", message: String(err) }],
+            },
         };
     }
 }
@@ -1020,6 +1127,43 @@ function resyncSchema(destRoot, samplesRoot, sourceFile, destFile, name) {
  *   - Sources missing from the samples catalog are reported as "notFound".
  *   - Empty install lists are not an error — the result is a clean no-op.
  */
+/**
+ * Ceremony-entry identity establishment (DEC-0020 — FGAP-033). When the
+ * substrate's config.json lacks a `substrate_id`, mint one (the SAME
+ * `mintSubstrateId` init uses), persist it through the sanctioned config write
+ * path, and register it in the project registry (the SAME `registerSubstrate`
+ * call init/accept-all make) — BEFORE the ceremony's first write that stamps
+ * identity, so a pre-identity substrate HEALS on the sanctioned ceremony
+ * instead of refusing at the stamping guard. Called at the entry of every
+ * substrate-lifecycle ceremony that can reach an identity-stamping write
+ * (update, install, resolve-blocked), at the same seam as the config-migration
+ * seeding. Returns the minted id when establishment happened (the ceremony
+ * reports it in its result), undefined when identity was already established
+ * (never re-mints — the on-disk id is immutable) or no config is loadable (the
+ * ceremony's own config handling reports that). This is explicit
+ * ceremony-boundary provisioning, not a lazy mint inside a block write —
+ * `substrateIdForDir`'s loud guard stays load-bearing for any write reaching
+ * it without identity (defense in depth, DEC-0012 preserved).
+ */
+function establishSubstrateIdentityAtEntry(cwd, destRoot) {
+    let config;
+    try {
+        config = loadConfig(cwd);
+    }
+    catch {
+        return undefined; // unloadable config — the ceremony's own path surfaces it
+    }
+    if (!config)
+        return undefined;
+    const existing = config.substrate_id;
+    if (typeof existing === "string" && /^sub-[0-9a-f]{16}$/.test(existing))
+        return undefined;
+    const substrate_id = mintSubstrateId();
+    config.substrate_id = substrate_id;
+    writeConfig(cwd, config);
+    registerSubstrate(cwd, substrate_id, path.relative(cwd, destRoot) || ".", []);
+    return substrate_id;
+}
 export function installContext(cwd, options = {}) {
     const result = {
         installed: [],
@@ -1038,6 +1182,16 @@ export function installContext(cwd, options = {}) {
             "No .pi-context.json bootstrap pointer found. Run /context init <substrate-dir> first to bootstrap the substrate.";
         return result;
     }
+    // Seed the catalog's `config` migration chain (idempotent) before the config
+    // read below, and before resyncSchema's pre-call migrations.json byte capture
+    // — so a blocked-resync rollback restores to the seeded state, preserving the
+    // seed.
+    seedCatalogConfigMigrationDecls(destRoot);
+    // Ceremony-entry identity establishment (DEC-0020) — before any write that
+    // stamps identity (the --update resync path's writeBlockForDir).
+    const establishedId = establishSubstrateIdentityAtEntry(cwd, destRoot);
+    if (establishedId)
+        result.substrateIdEstablished = establishedId;
     const config = loadConfig(cwd);
     if (!config) {
         result.error = "No config.json found in substrate dir — run /context init <substrate-dir> first.";
@@ -1228,7 +1382,11 @@ export function installContext(cwd, options = {}) {
  * re-sync, slice S3). Compares, per installed schema, the S2 install baseline
  * against the catalog's current schema file and the currently-installed schema
  * file, classifies the drift, and RETURNS the report. Writes NOTHING anywhere —
- * no config write, no file copy, no mkdir; only reads.
+ * no config write, no file copy, no mkdir; only reads. One designed exception:
+ * like every ceremony entry point it seeds the catalog's `config` migration
+ * chain into `migrations.json` (idempotent) before its first config read — the
+ * heal semantic, consistent with idempotent re-init healing — so a
+ * version-lagging legacy substrate is diagnosable instead of throwing.
  *
  * For each `config.installed_schemas` entry:
  *   - baseline      = config.installed_from?.assets?.[name]?.content_hash
@@ -1260,6 +1418,9 @@ export function checkStatus(cwd) {
     if (destRoot === null) {
         return { perAsset, summary: emptySummary() };
     }
+    // Ceremony seed (idempotent) before the config read below — the one
+    // sanctioned write in this otherwise pure-read detector (see docstring).
+    seedCatalogConfigMigrationDecls(destRoot);
     const config = loadConfig(cwd);
     if (!config) {
         return { perAsset, summary: emptySummary() };
@@ -1470,6 +1631,23 @@ export function updateContext(cwd, { dryRun = false } = {}) {
             "No .pi-context.json bootstrap pointer found. Run /context init <substrate-dir> first to bootstrap the substrate.";
         return result;
     }
+    // Seed the catalog's `config` migration chain (idempotent) before the config
+    // read below — every ceremony entry point seeds before its first config read,
+    // so a version-lagging legacy substrate heals on update instead of throwing.
+    seedCatalogConfigMigrationDecls(destRoot);
+    // Ceremony-entry identity establishment (DEC-0020) — before any write that
+    // stamps identity (the version-bump resync's writeBlockForDir), so a
+    // pre-identity substrate heals here instead of refusing at the stamping
+    // guard. LIVE runs only: a dryRun performs no stamping write, so there is
+    // nothing to establish ahead of — the preview keeps its writes-nothing
+    // contract (beyond the idempotent ceremony seed), and its predicted
+    // per-schema plan already matches the healed live outcome (the in-memory
+    // simulation never consults the stamping precondition).
+    if (!dryRun) {
+        const establishedId = establishSubstrateIdentityAtEntry(cwd, destRoot);
+        if (establishedId)
+            result.substrateIdEstablished = establishedId;
+    }
     const config = loadConfig(cwd);
     if (!config) {
         result.error = "No config.json found in substrate dir — run /context init <substrate-dir> first.";
@@ -1774,6 +1952,65 @@ export function updateContext(cwd, { dryRun = false } = {}) {
         // Catalog read / parse / config-load failure: leave registryAdditions empty
         // (its initialized value) and return the schema-update result unchanged.
     }
+    // Partial-application legibility (FGAP-076): computed LAST, after every
+    // channel above is final (the registry propagation just ran), so the field is
+    // a pure derivation of the finished result. Populated exactly when the run
+    // both refused something and applied something; a blocked run whose registry
+    // additions (or other-schema resyncs) landed must never read as a no-op.
+    // dryRun runs derive the same shape from the predicted plan.
+    const ra = result.registryAdditions;
+    const registryAdditionCount = ra.relation_types.length + ra.invariants.length + ra.block_kinds.length + ra.lenses.length;
+    const refusedSomething = result.blocked.length > 0 || result.refused.length > 0 || result.conflicts.length > 0;
+    const appliedSomething = result.resynced.length > 0 ||
+        result.migrated.length > 0 ||
+        result.merged.length > 0 ||
+        result.migrationsRegistered.length > 0 ||
+        registryAdditionCount > 0;
+    if (refusedSomething && appliedSomething) {
+        const appliedParts = [];
+        if (registryAdditionCount > 0) {
+            const perRegistry = ["relation_types", "invariants", "block_kinds", "lenses"]
+                .filter((k) => ra[k].length > 0)
+                .map((k) => `${ra[k].length} ${k}`)
+                .join(", ");
+            appliedParts.push(`registry additions (${perRegistry})`);
+        }
+        if (result.resynced.length > 0)
+            appliedParts.push(`resynced: ${result.resynced.join(", ")}`);
+        if (result.migrated.length > 0)
+            appliedParts.push(`migrated: ${result.migrated.join(", ")}`);
+        if (result.merged.length > 0)
+            appliedParts.push(`merged: ${result.merged.join(", ")}`);
+        if (result.migrationsRegistered.length > 0)
+            appliedParts.push(`migration declarations registered: ${result.migrationsRegistered.map((m) => `${m.schema} ${m.from}->${m.to}`).join(", ")}`);
+        const notAppliedParts = [];
+        if (result.blocked.length > 0)
+            notAppliedParts.push(`blocked: ${result.blocked
+                .map((name) => {
+                const detail = result.blockedDetail.find((d) => d.name === name);
+                return detail ? `'${name}' (${detail.reason})` : `'${name}'`;
+            })
+                .join(", ")}`);
+        if (result.refused.length > 0)
+            notAppliedParts.push(`refused (local modifications preserved): ${result.refused.map((n) => `'${n}'`).join(", ")}`);
+        if (result.conflicts.length > 0)
+            notAppliedParts.push(`merge conflicts: ${result.conflicts.map((c) => `'${c.name}'`).join(", ")}`);
+        result.partialApplication = {
+            applied: {
+                resynced: [...result.resynced],
+                migrated: [...result.migrated],
+                merged: [...result.merged],
+                registryAdditions: ra,
+                migrationsRegistered: [...result.migrationsRegistered],
+            },
+            notApplied: {
+                blocked: [...result.blocked],
+                refused: [...result.refused],
+                conflicts: result.conflicts.map((c) => c.name),
+            },
+            summary: `PARTIAL APPLICATION${dryRun ? " (dryRun preview)" : ""}: applied — ${appliedParts.join("; ")}. Not applied — ${notAppliedParts.join("; ")}. The applied portion ${dryRun ? "WOULD change" : "changed"} the substrate even though schemas were refused${dryRun ? " (nothing written in this preview)" : ""}.`,
+        };
+    }
     return result;
 }
 /**
@@ -1881,6 +2118,10 @@ export function resolveConflict(cwd, name, schema, ctx) {
     if (destRoot === null) {
         throw new Error(`resolve-conflict: no active substrate resolved for '${cwd}'`);
     }
+    // Ceremony seed (idempotent) — update-family class rule: every ceremony
+    // entry point seeds the catalog's `config` migration chain before its first
+    // config read (here reached via stampBaselineFromBody's loadConfig).
+    seedCatalogConfigMigrationDecls(destRoot);
     const { samplesRoot, byId } = resolveCatalog();
     const kind = byId.get(name);
     if (!kind) {
@@ -1957,6 +2198,15 @@ export function resolveBlocked(cwd, name, ctx) {
     if (destRoot === null) {
         throw new Error(`resolve-blocked: no active substrate resolved for '${cwd}'`);
     }
+    // Ceremony seed (idempotent) — update-family class rule: every ceremony
+    // entry point seeds the catalog's `config` migration chain before its first
+    // config read (here reached via stampBaselineFromBody's loadConfig on the
+    // pass path).
+    seedCatalogConfigMigrationDecls(destRoot);
+    // Ceremony-entry identity establishment (DEC-0020) — before the commit's
+    // writeBlockForDir stamping write, so a pre-identity substrate's resolution
+    // heals identity instead of refusing mid-commit.
+    const establishedId = establishSubstrateIdentityAtEntry(cwd, destRoot);
     const pending = loadPendingBlockedForDir(destRoot);
     const entry = pending?.entries.find((e) => e.name === name);
     if (!entry) {
@@ -2001,6 +2251,7 @@ export function resolveBlocked(cwd, name, ctx) {
             schemaName: name,
             resolved: false,
             failures: [{ instancePath: "", keyword: "error", message: String(err) }],
+            ...(establishedId ? { substrateIdEstablished: establishedId } : {}),
         };
     }
     const blockVersion = blockData && typeof blockData === "object" && "schema_version" in blockData
@@ -2034,54 +2285,106 @@ export function resolveBlocked(cwd, name, ctx) {
         const failures = err instanceof ValidationError
             ? mapValidationFailures(err.errors, blockData)
             : [{ instancePath: "", keyword: "error", message: String(err) }];
-        return { schemaName: name, resolved: false, failures };
+        return {
+            schemaName: name,
+            resolved: false,
+            failures,
+            ...(establishedId ? { substrateIdEstablished: establishedId } : {}),
+        };
     }
-    // PASS — commit the resolution. (1) Register the chain decls not already on
-    // disk (the resyncSchema dedup), collecting the registered set.
-    const existing = loadMigrationsFileForDir(destRoot);
-    const present = new Set((existing?.migrations ?? []).map((m) => `${m.schemaName} ${m.fromVersion}`));
-    const registeredMigrations = [];
-    for (const decl of entry.chain) {
-        const key = `${decl.schemaName} ${decl.fromVersion}`;
-        if (present.has(key))
-            continue;
-        appendMigrationDeclForDir(destRoot, decl, ctx);
-        present.add(key);
-        registeredMigrations.push({ schema: decl.schemaName, from: decl.fromVersion, to: decl.toVersion });
+    // PASS — commit the resolution, ALL-OR-NOTHING (FGAP-115). The commit touches
+    // up to five files; a throw partway (e.g. the mandatory identity stamp inside
+    // writeBlockForDir refusing a substrate with no substrate_id) previously
+    // stranded a partial commit — schema advanced, markers stripped, block
+    // unwritten, pending entry stale. Capture the raw pre-commit bytes of every
+    // touched file up front; on any commit-phase throw restore them byte-exact
+    // (per-component byte-exact refuse discipline, DEC-0017/DEC-0018), invalidate
+    // the migration-registry cache warmed by the reverted decl appends, and
+    // return resolved:false carrying the truthful failure. Object-store putObject
+    // entries are content-addressed and harmless to leave behind.
+    const commitFiles = [
+        migrationsPathForDir(destRoot),
+        installedSchemaDestPath(destRoot, name),
+        blockFile,
+        path.join(destRoot, "config.json"),
+        pendingBlockedPathForDir(destRoot),
+    ];
+    const preCommitBytes = new Map();
+    for (const f of commitFiles) {
+        preCommitBytes.set(f, fs.existsSync(f) ? fs.readFileSync(f) : null);
     }
-    // (2) Write the target schema (replace — meta-validated, nested-id-guarded, atomic).
-    writeSchemaCheckedForDir(destRoot, name, targetBody, "replace", ctx);
-    // (3) Advance the migrated block's schema_version envelope to the target + persist
-    // it (skip when the block had no items — schema still written, base still advanced,
-    // mirroring the live no-items handling). Identity stamping re-runs on the write.
-    if (hasItems) {
-        // TASK-052 / FGAP-081 (oid stability): when the on-disk block carried markers,
-        // raw-write the STRIPPED text to the block file (tmp+rename) BEFORE
-        // writeBlockForDir, so the identity-stamp prior-read parses the marker-free
-        // on-disk file and preserves each item's oid (no re-mint; content_parent advances
-        // only on genuinely changed items).
-        if (wasMarked && strippedText !== undefined) {
-            const tmpPath = `${blockFile}.unmark-${process.pid}.tmp`;
-            fs.writeFileSync(tmpPath, strippedText);
-            fs.renameSync(tmpPath, blockFile);
+    try {
+        // (1) Register the chain decls not already on disk (the resyncSchema dedup),
+        // collecting the registered set.
+        const existing = loadMigrationsFileForDir(destRoot);
+        const present = new Set((existing?.migrations ?? []).map((m) => `${m.schemaName} ${m.fromVersion}`));
+        const registeredMigrations = [];
+        for (const decl of entry.chain) {
+            const key = `${decl.schemaName} ${decl.fromVersion}`;
+            if (present.has(key))
+                continue;
+            appendMigrationDeclForDir(destRoot, decl, ctx);
+            present.add(key);
+            registeredMigrations.push({ schema: decl.schemaName, from: decl.fromVersion, to: decl.toVersion });
         }
-        if (migrated &&
-            typeof migrated === "object" &&
-            !Array.isArray(migrated) &&
-            typeof migrated.schema_version === "string" &&
-            typeof targetVersion === "string") {
-            migrated.schema_version = targetVersion;
+        // (2) Write the target schema (replace — meta-validated, nested-id-guarded, atomic).
+        writeSchemaCheckedForDir(destRoot, name, targetBody, "replace", ctx);
+        // (3) Advance the migrated block's schema_version envelope to the target + persist
+        // it (skip when the block had no items — schema still written, base still advanced,
+        // mirroring the live no-items handling). Identity stamping re-runs on the write.
+        if (hasItems) {
+            // TASK-052 / FGAP-081 (oid stability): when the on-disk block carried markers,
+            // raw-write the STRIPPED text to the block file (tmp+rename) BEFORE
+            // writeBlockForDir, so the identity-stamp prior-read parses the marker-free
+            // on-disk file and preserves each item's oid (no re-mint; content_parent advances
+            // only on genuinely changed items).
+            if (wasMarked && strippedText !== undefined) {
+                const tmpPath = `${blockFile}.unmark-${process.pid}.tmp`;
+                fs.writeFileSync(tmpPath, strippedText);
+                fs.renameSync(tmpPath, blockFile);
+            }
+            if (migrated &&
+                typeof migrated === "object" &&
+                !Array.isArray(migrated) &&
+                typeof migrated.schema_version === "string" &&
+                typeof targetVersion === "string") {
+                migrated.schema_version = targetVersion;
+            }
+            writeBlockForDir(destRoot, name, migrated);
         }
-        writeBlockForDir(destRoot, name, migrated);
+        // (4) Advance the merge base to the target body so a subsequent update converges
+        // (base === catalog) instead of re-deriving drift.
+        const baseAdvancedTo = stampBaselineFromBody(cwd, name, targetBody, targetVersion ?? "");
+        // (5) Clear the resolved entry from pending-blocked.json (remove the file when
+        // it becomes empty — no stale empty sidecar).
+        const remaining = (pending?.entries ?? []).filter((e) => e.name !== name);
+        reconcilePendingBlockedForDir(destRoot, remaining, ctx);
+        return {
+            schemaName: name,
+            resolved: true,
+            registeredMigrations,
+            baseAdvancedTo,
+            ...(establishedId ? { substrateIdEstablished: establishedId } : {}),
+        };
+    }
+    catch (err) {
+        for (const [f, bytes] of preCommitBytes) {
+            if (bytes === null) {
+                if (fs.existsSync(f))
+                    fs.unlinkSync(f);
+            }
+            else {
+                fs.writeFileSync(f, bytes);
+            }
+        }
+        invalidateMigrationRegistryForDir(destRoot);
+        return {
+            schemaName: name,
+            resolved: false,
+            failures: [{ instancePath: "", keyword: "error", message: String(err) }],
+            ...(establishedId ? { substrateIdEstablished: establishedId } : {}),
+        };
     }
-    // (4) Advance the merge base to the target body so a subsequent update converges
-    // (base === catalog) instead of re-deriving drift.
-    const baseAdvancedTo = stampBaselineFromBody(cwd, name, targetBody, targetVersion ?? "");
-    // (5) Clear the resolved entry from pending-blocked.json (remove the file when
-    // it becomes empty — no stale empty sidecar).
-    const remaining = (pending?.entries ?? []).filter((e) => e.name !== name);
-    reconcilePendingBlockedForDir(destRoot, remaining, ctx);
-    return { schemaName: name, resolved: true, registeredMigrations, baseAdvancedTo };
 }
 /**
  * Render an `UpdateResult["conflicts"]` set as a readable conflict report
@@ -2155,6 +2458,15 @@ export function renderBlocked(blockedDetail) {
             lines.push(`    no migration chain reaches ${to} from ${from}`);
             continue;
         }
+        if (d.reason === "write-failed") {
+            // FGAP-115: a non-validation refusal at the write boundary. The items were
+            // NOT flagged invalid — do not direct the operator at them.
+            for (const f of d.failures ?? []) {
+                lines.push(`    ${f.message}`);
+            }
+            lines.push("    write refused (not an item-validation failure) — the block's items were not flagged invalid; do not edit items. Address the named precondition, then re-run update.");
+            continue;
+        }
         // validation-failed
         for (const f of d.failures ?? []) {
             const subject = f.itemId ?? f.instancePath ?? "(item)";
@@ -2171,7 +2483,12 @@ export function renderBlocked(blockedDetail) {
     if (anyMarked) {
         lines.push("Git-style failure markers were written INTO the block file(s): open each block file, fix the items between the `<<<<<<< BLOCKED …` / `>>>>>>> target: …` markers, then resolve-blocked --schemaName <name> --yes — it strips the markers, re-validates the corrected block against the pinned target, writes the target schema, advances the merge base, and clears the block so update converges.");
     }
-    else {
+    else if (blockedDetail.some((d) => d.reason !== "write-failed")) {
+        // The fix-items-then-resolve-blocked flow applies only to entries that
+        // persist a pending record (validation-failed / no-migration-chain). A
+        // report whose entries are ALL write-failed carries its own per-entry
+        // guidance (address the precondition, re-run update) — appending the
+        // item-fixing flow here would contradict it (FGAP-115).
         lines.push("No markers were written (preview, or no migration chain to mark against). Resolve a validation-failed block by correcting the offending items in the block file, then resolve-blocked --schemaName <name> --yes — it re-validates the corrected block against the pinned target, writes the target schema, advances the merge base, and clears the block so update converges.");
     }
     return lines.join("\n");
@@ -2373,6 +2690,11 @@ export function switchToExisting(cwd, targetDir, writerIdentity) {
         throw new Error(`/context switch: target dir '${targetDir}' has no config.json at ${targetConfigPath} — refusing to flip the bootstrap pointer to a non-substrate dir. Use '/context switch -c ${targetDir}' to bootstrap a fresh substrate at that dir AND flip the pointer.`);
     }
     flipBootstrapPointer(cwd, targetDir, writerIdentity);
+    // Seed the TARGET substrate's catalog `config` migration chain (idempotent)
+    // right after the flip — every ceremony entry point seeds before its first
+    // config read, so the first read on the now-active substrate (reconcile's
+    // below, or any later one) cannot throw on a version-lagging legacy config.
+    seedCatalogConfigMigrationDecls(resolveContextDir(cwd));
     // Register the now-active substrate's identity if the target carried a
     // config-bearing-but-unregistered substrate_id, so the SoT-drift invariant
     // does not raise a false substrate_id_unregistered after the flip.
@@ -2402,6 +2724,11 @@ export function switchToPrevious(cwd, writerIdentity) {
         throw new Error(`/context switch -: existing pointer at ${bootstrapPath} lacks a string contextDir; refuses to flip an unreadable pointer`);
     }
     flipBootstrapPointer(cwd, previous, writerIdentity);
+    // Seed the flipped-back-to substrate's catalog `config` migration chain
+    // (idempotent) right after the flip — same switch-family ceremony rule as
+    // switchToExisting: the first config read on the now-active substrate must
+    // not throw on a version-lagging legacy config.
+    seedCatalogConfigMigrationDecls(resolveContextDir(cwd));
     // Register the now-active substrate's identity if flipping back landed on a
     // config-bearing-but-unregistered substrate_id, so the SoT-drift invariant
     // does not raise a false substrate_id_unregistered after the flip. Mirrors
@@ -2720,49 +3047,30 @@ const extension = (pi) => {
                 });
             },
         },
-        "roadmap-list": {
-            description: "List every roadmap in <config.root>/roadmap.json with id, title, status, and phase count",
-            handler: (_args, ctx) => {
-                const list = listRoadmaps(ctx.cwd);
-                if (list.length === 0) {
-                    ctx.ui.notify("No roadmaps found. Install the roadmap block via the substrate dir's config.json installed_blocks, then author roadmap.json.", "info");
-                    return;
-                }
-                const lines = list.map((r) => `${r.id} [${r.status ?? "(unspecified)"}] ${r.title} (${r.phaseCount} phase${r.phaseCount === 1 ? "" : "s"})`);
-                ctx.ui.notify(lines.join("\n"), "info");
-            },
-        },
         "roadmap-view": {
-            description: "Render a roadmap as pure-textual markdown (phase order, per-phase adjacency from authored phase_depends_on edges, status rollup, milestone resolution). NO mermaid.",
-            handler: (args, ctx) => {
-                const roadmapId = args.trim().split(/\s+/)[0];
-                if (!roadmapId) {
-                    ctx.ui.notify("Usage: /context roadmap-view <ROADMAP-id>", "error");
-                    return;
-                }
-                const view = loadRoadmap(ctx.cwd, roadmapId);
+            description: "Render the derived roadmap as pure-textual markdown (milestone order over authored milestone_precedes_milestone edges, per-milestone phase/task rollups, adjacency strictly from edges). NO mermaid.",
+            handler: (_args, ctx) => {
+                const view = loadRoadmap(ctx.cwd);
                 if ("error" in view) {
                     ctx.ui.notify(view.error, "error");
                     return;
                 }
-                const naming = loadContext(ctx.cwd).config?.naming;
-                ctx.ui.notify(renderRoadmap(view, naming), "info");
+                ctx.ui.notify(renderRoadmap(view), "info");
             },
         },
         "roadmap-validate": {
-            description: "Validate every roadmap (or a single one when ROADMAP-id supplied) — surfaces structured issues",
-            handler: (args, ctx) => {
-                const roadmapId = args.trim().split(/\s+/)[0] || undefined;
-                const result = validateRoadmaps(ctx.cwd);
-                const filtered = roadmapId
-                    ? result.issues.filter((i) => !i.roadmap_id || i.roadmap_id === roadmapId)
-                    : result.issues;
-                if (filtered.length === 0) {
-                    ctx.ui.notify(`✓ Roadmap validation passed${roadmapId ? ` for ${roadmapId}` : ""}.`, "info");
+            description: "Validate the derived milestone roadmap — surfaces structured issues (error/warning/info codes)",
+            handler: (_args, ctx) => {
+                const result = validateRoadmap(ctx.cwd);
+                if (result.issues.length === 0) {
+                    ctx.ui.notify("✓ Roadmap validation passed.", "info");
                     return;
                 }
-                const lines = filtered.map((i) => `✗ [${i.code}] ${i.roadmap_id ?? ""}/${i.phase_id ?? ""}: ${i.message}`);
-                const level = result.status === "invalid" ? "error" : "warning";
+                const lines = result.issues.map((i) => {
+                    const where = `${i.milestone_id ? ` ${i.milestone_id}` : ""}${i.phase_id ? ` ${i.phase_id}` : ""}`;
+                    return `✗ [${i.code}]${where}: ${i.message}`;
+                });
+                const level = result.status === "invalid" ? "error" : result.status === "warnings" ? "warning" : "info";
                 ctx.ui.notify(lines.join("\n"), level);
             },
         },
@@ -2855,10 +3163,13 @@ export default extension;
 // Re-export the config-registry-propagation surface (TASK-038 — FEAT-006 T5) so
 // consumers can type `UpdateResult.registryAdditions` and call the pure merge
 // helper against the public `@davidorex/pi-context` surface.
-export { mergeCatalogRegistries } from "./context.js";
+// mergeCatalogRegistries + the FGAP-113 edge-orientation helpers
+// (counterEndpoint / primaryEndpoint — the single source of truth for reading a
+// relation's primary/counter endpoint under its config-declared role_direction).
+export { counterEndpoint, mergeCatalogRegistries, primaryEndpoint } from "./context.js";
 export { contextRegistryPath, invalidateRegistry, loadRegistry, REGISTRY_FILE_VERSION, registerSubstrate, resolveAlias, resolveSubstrateDir, writeRegistry, } from "./context-registry.js";
 // Re-export for consumers
 export { blockStructure, buildIdIndex, CONTEXT_BLOCK_TYPES, completeTask, findAppendableBlocks, resolveItemById, resolveRef, schemaInfo, schemaVocabulary, } from "./context-sdk.js";
 export { renameCanonicalId } from "./rename-canonical-id.js";
-export { listRoadmaps, loadRoadmap, renderRoadmap, resolveStatusVocabulary, rollupPhaseStatus, topoSort, validateRoadmaps, } from "./roadmap-plan.js";
+export { loadRoadmap, renderRoadmap, resolveStatusVocabulary, rollupPhaseStatus, topoSort, validateRoadmap, } from "./roadmap-plan.js";
 //# sourceMappingURL=index.js.map