@davidorex/pi-context 0.26.0 → 0.28.1

package/dist/block-api.js

@@ -16,12 +16,16 @@
  *
  * Future extraction seam for pi-project extension.
  */
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import _lockfile from "proper-lockfile";
-import { assertSubstrateName, resolveContextDir, schemaPath, tryResolveContextDir } from "./context-dir.js";
+import { canonicalJson, computeContentHash, sha256Hex } from "./content-hash.js";
+import { assertSubstrateName, resolveContextDir, schemaPathForDir, substrateIdForDir, tryResolveContextDir, } from "./context-dir.js";
 import { stampItem } from "./dispatch-context.js";
-import { validateFromFile } from "./schema-validator.js";
+import { getProjectMigrationRegistryForDir } from "./migration-registry-loader.js";
+import { hasObject, putObject } from "./object-store.js";
+import { validateBlockWithMigrationForDir, validateFromFile } from "./schema-validator.js";
 // Node16 module resolution + CJS interop: default import may be wrapped
 const lockfile = _lockfile.default ?? _lockfile;
 /**
@@ -41,12 +45,12 @@ function withBlockLock(filePath, fn) {
         lockfile.unlockSync(filePath);
     }
 }
-function blockFilePath(cwd, blockName) {
+function blockFilePathForDir(substrateDir, blockName) {
     assertSubstrateName(blockName);
-    return path.join(resolveContextDir(cwd), `${blockName}.json`);
+    return path.join(substrateDir, `${blockName}.json`);
 }
-function blockSchemaPath(cwd, blockName) {
-    return schemaPath(cwd, blockName);
+function blockSchemaPathForDir(substrateDir, blockName) {
+    return schemaPathForDir(substrateDir, blockName);
 }
 // ── Schema introspection cache (DispatchContext support, FGAP-004) ───────────
 /**
@@ -57,6 +61,54 @@ function blockSchemaPath(cwd, blockName) {
  * validation on injected fields.
  */
 const AUTHOR_FIELDS = ["created_by", "created_at", "modified_by", "modified_at"];
+/**
+ * The MANDATORY content/metadata floor (content-addressed substrate identity,
+ * Cycle 3 / carried item 1; v3 spec §A2). The identity/addressing fields
+ * `id`, `oid`, `content_hash`, `content_parent` are ALWAYS metadata —
+ * EXCLUDED from the content hash — and a schema's `x-identity.metadata_fields`
+ * override can NEVER pull them into the content. This is the floor that makes
+ * the content hash a faithful identity for content rather than for addressing:
+ * a refname rename (`id`), a freshly-minted `oid`, or a recomputed
+ * `content_hash` / advanced `content_parent` must never move the hash, or the
+ * object store would fork on pure addressing churn. `metadataFieldsForSchema`
+ * unions this floor into whatever partition an override declares so the floor
+ * is non-overridable by construction.
+ */
+export const MANDATORY_METADATA_FIELDS = new Set([
+    "id",
+    "oid",
+    "content_hash",
+    "content_parent",
+]);
+/**
+ * The DISCRETIONARY metadata fields (v3 spec §A2): the four author/attestation
+ * fields (`AUTHOR_FIELDS`) plus the lifecycle-closure fields (`closed_by`,
+ * `closed_at`). These are the fields a schema MAY redefine via an
+ * `x-identity.metadata_fields` override — when an override is declared it
+ * REPLACES this discretionary set (the floor is still unioned back in); when
+ * absent these are the discretionary defaults. Built from `AUTHOR_FIELDS` so
+ * the four author strings keep a single source of truth and cannot drift from
+ * the stamping path.
+ */
+export const DISCRETIONARY_METADATA_FIELDS = new Set([
+    ...AUTHOR_FIELDS,
+    "closed_by",
+    "closed_at",
+]);
+/**
+ * The default content/metadata partition when no `x-identity.metadata_fields`
+ * override is declared: `MANDATORY ∪ DISCRETIONARY` — the same 10 fields the
+ * Cycle-2 surface enumerated (`id`, `oid`, `content_hash`, `content_parent`,
+ * the four author fields, `closed_by`, `closed_at`). Retained as the
+ * no-override default so the membership is identical to the pre-Cycle-3 set;
+ * `metadataFieldsForSchema` now composes it from the two named subsets rather
+ * than a flat literal so the mandatory floor is provably a subset of every
+ * resolved partition (see that function).
+ */
+export const DEFAULT_METADATA_FIELDS = new Set([
+    ...MANDATORY_METADATA_FIELDS,
+    ...DISCRETIONARY_METADATA_FIELDS,
+]);
 const schemaCache = new Map();
 function safeStat(p) {
     try {
@@ -150,6 +202,222 @@ function collectArrayItemAuthorDecisions(schema, into) {
         }
     }
 }
+/**
+ * Read the `x-identity.metadata_fields` override from an item subschema, if
+ * present. `x-identity` follows the established `x-prompt-budget` /
+ * `x-lifecycle` extension-keyword convention; `metadata_fields` is an array of
+ * field names to treat as metadata (excluded from the content hash) for items
+ * of this kind. Returns the array as a `Set` when validly declared, else
+ * `null` (caller falls back to `DEFAULT_METADATA_FIELDS`). Non-string entries
+ * are ignored defensively; a non-array `metadata_fields` yields `null`.
+ */
+function readItemMetadataFieldsOverride(itemSchema) {
+    if (!itemSchema || typeof itemSchema !== "object")
+        return null;
+    const xIdentity = itemSchema["x-identity"];
+    if (!xIdentity || typeof xIdentity !== "object")
+        return null;
+    const fields = xIdentity.metadata_fields;
+    if (!Array.isArray(fields))
+        return null;
+    const out = new Set();
+    for (const f of fields) {
+        if (typeof f === "string")
+            out.add(f);
+    }
+    return out;
+}
+/**
+ * Walk every `items` subschema reachable from a schema (same traversal shape
+ * as `collectArrayItemAuthorDecisions`) and record, per array property name,
+ * the RAW `x-identity.metadata_fields` override for that array's items — ONLY
+ * when one is declared. A key with no declared override is left ABSENT from
+ * `into` (no default is written) so `metadataFieldsForSchema` can distinguish
+ * "override declared" from "no override" and apply the mandatory-floor union
+ * over the discretionary default at the read site. Mutates `into` in place.
+ * Nested arrays appear under their own key. When the same key appears at
+ * multiple depths, the first explicitly-declared override encountered is
+ * retained (a later declaration does not clobber it).
+ */
+function collectArrayItemMetadataOverrides(schema, into) {
+    if (!schema || typeof schema !== "object")
+        return;
+    const s = schema;
+    const props = s.properties;
+    if (!props)
+        return;
+    for (const [propKey, propSpecRaw] of Object.entries(props)) {
+        if (!propSpecRaw || typeof propSpecRaw !== "object")
+            continue;
+        const spec = propSpecRaw;
+        if (spec.type === "array") {
+            const items = spec.items;
+            if (items && typeof items === "object") {
+                const itemProps = items.properties;
+                if (itemProps) {
+                    const override = readItemMetadataFieldsOverride(items);
+                    // Record only an explicit override; absence means "no
+                    // override" so the read site applies the discretionary
+                    // default. First explicit declaration wins.
+                    if (override && !into.has(propKey)) {
+                        into.set(propKey, override);
+                    }
+                    collectArrayItemMetadataOverrides(items, into);
+                }
+            }
+        }
+        else {
+            collectArrayItemMetadataOverrides(spec, into);
+        }
+    }
+}
+/**
+ * The three item fields whose presence (ALL THREE) in an array item's
+ * `properties` arms the Cycle-3 identity-stamping path for that array (locked
+ * decision 1). Distinct from `MANDATORY_METADATA_FIELDS` (which additionally
+ * carries `id`, present on every block item regardless of identity): these are
+ * the net-new fields a Cycle-3 schema edit adds, so their joint presence is the
+ * signal that a schema opted into identity stamping.
+ */
+const IDENTITY_DECLARATION_FIELDS = ["oid", "content_hash", "content_parent"];
+/**
+ * Walk every `items` subschema reachable from a schema (same traversal shape as
+ * `collectArrayItemMetadataOverrides`) and record, per array property name,
+ * whether the item subschema's `properties` declares ALL THREE
+ * `IDENTITY_DECLARATION_FIELDS`. This is the schema-gate cataloguer for
+ * `prepareItemIdentityForWrite` (locked decision 1) — mirrors
+ * `collectArrayItemAuthorDecisions` for the author-stamp gate. A key absent
+ * from `into` (or recorded `false`) means "this array does not stamp identity".
+ * `true` is recorded once and never downgraded (first positive declaration
+ * across reachable shapes wins, paralleling the author cataloguer's union).
+ */
+function collectArrayItemIdentityDecisions(schema, into) {
+    if (!schema || typeof schema !== "object")
+        return;
+    const s = schema;
+    const props = s.properties;
+    if (!props)
+        return;
+    for (const [propKey, propSpecRaw] of Object.entries(props)) {
+        if (!propSpecRaw || typeof propSpecRaw !== "object")
+            continue;
+        const spec = propSpecRaw;
+        if (spec.type === "array") {
+            const items = spec.items;
+            if (items && typeof items === "object") {
+                const itemProps = items.properties;
+                if (itemProps) {
+                    const declaresAll = IDENTITY_DECLARATION_FIELDS.every((f) => Object.hasOwn(itemProps, f));
+                    if (declaresAll) {
+                        into.set(propKey, true);
+                    }
+                    else if (!into.has(propKey)) {
+                        into.set(propKey, false);
+                    }
+                    collectArrayItemIdentityDecisions(items, into);
+                }
+            }
+        }
+        else {
+            collectArrayItemIdentityDecisions(spec, into);
+        }
+    }
+}
+/**
+ * The content/metadata partition for items of array `arrayKey` under `schema`:
+ * `MANDATORY_METADATA_FIELDS ∪ (override ?? DISCRETIONARY_METADATA_FIELDS)`
+ * (carried item 1 / v3 spec §A2). The item subschema's
+ * `x-identity.metadata_fields` override, when declared, REPLACES the
+ * discretionary set; the mandatory floor (`id`/`oid`/`content_hash`/
+ * `content_parent`) is then unioned back in so an override can never pull a
+ * floor field into the content — even an override that omits `id` still
+ * excludes the floor, so two items differing only in `id` hash equal under
+ * that override. When no override is declared the result equals
+ * `DEFAULT_METADATA_FIELDS` (floor ∪ discretionary) byte-for-byte.
+ *
+ * Single reader — both the cache populate site (`getSchemaCacheEntry` via
+ * `collectArrayItemMetadataOverrides`) and `contentProjection` route through
+ * this so there is exactly one resolution path and no parallel default.
+ * Resolves the item subschema by the same array-key traversal used for
+ * author-field decisions, reading the RAW override (not the already-defaulted
+ * collected value) so the union is over the override itself.
+ */
+export function metadataFieldsForSchema(schema, arrayKey) {
+    const overrides = new Map();
+    collectArrayItemMetadataOverrides(schema, overrides);
+    const override = overrides.get(arrayKey);
+    const discretionary = override ?? DISCRETIONARY_METADATA_FIELDS;
+    return new Set([...MANDATORY_METADATA_FIELDS, ...discretionary]);
+}
+/**
+ * Human-readable description of how a schema's `x-identity.metadata_fields`
+ * override changes the discretionary metadata partition relative to the
+ * default — or `null` when NO array item subschema declares an override
+ * (carried item 2 / informed-authorization confirm). Pure function: no
+ * filesystem, no cache; takes a parsed schema object and inspects every
+ * reachable array item subschema for an `x-identity.metadata_fields`
+ * declaration.
+ *
+ * When at least one override is present, returns a one-line-per-array summary
+ * naming, per array key, which DISCRETIONARY fields the override DROPS
+ * (present in `DISCRETIONARY_METADATA_FIELDS` but absent from the override)
+ * and which non-floor fields it ADDS (present in the override, not a floor
+ * field, not a default discretionary field). The mandatory floor
+ * (`id`/`oid`/`content_hash`/`content_parent`) is never reported as
+ * add/drop — it is structurally unaffected by an override — so the caller
+ * (auth-gate) can append a standing "floor remains excluded" affirmation.
+ *
+ * Used by `authGateHandler` to enrich the `write-schema` confirm message; the
+ * exact wording is the affordance, not a parse contract.
+ */
+export function describeIdentityOverride(schema) {
+    const overrides = new Map();
+    collectArrayItemMetadataOverrides(schema, overrides);
+    if (overrides.size === 0)
+        return null;
+    const lines = [];
+    for (const [arrayKey, override] of overrides) {
+        const dropped = [];
+        for (const f of DISCRETIONARY_METADATA_FIELDS) {
+            if (!override.has(f))
+                dropped.push(f);
+        }
+        const added = [];
+        for (const f of override) {
+            if (!MANDATORY_METADATA_FIELDS.has(f) && !DISCRETIONARY_METADATA_FIELDS.has(f))
+                added.push(f);
+        }
+        const parts = [];
+        if (added.length > 0)
+            parts.push(`treats as metadata (excluded from hash): ${added.join(", ")}`);
+        if (dropped.length > 0)
+            parts.push(`now hashed (no longer metadata): ${dropped.join(", ")}`);
+        if (parts.length === 0)
+            parts.push("redefines the discretionary metadata set with no net field-level change");
+        lines.push(`array '${arrayKey}': ${parts.join("; ")}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Project an item to its hashable content: a SHALLOW COPY of `item` with the
+ * metadata keys (`metadataFieldsForSchema(schema, arrayKey)`) deleted. Does
+ * NOT mutate `item`. The result is what Cycle 3 will feed to
+ * `computeContentHash`, so a metadata-only mutation (refreshed author stamp,
+ * freshly-assigned `oid`, etc.) leaves the projection — and therefore the
+ * content hash — unchanged.
+ *
+ * `schema` is the parsed schema object (not a path), so this is usable both
+ * from the cache populate path and from ad-hoc callers / tests holding an
+ * inline schema.
+ */
+export function contentProjection(schema, arrayKey, item) {
+    const metadataFields = metadataFieldsForSchema(schema, arrayKey);
+    const projection = { ...item };
+    for (const f of metadataFields) {
+        delete projection[f];
+    }
+    return projection;
+}
 /**
  * Load the cached schema-introspection answer for a schema file, refreshing
  * the cache when the file's mtime changes (or it appears / disappears).
@@ -188,12 +456,26 @@ function getSchemaCacheEntry(schemaPath) {
             hasAuthorFields: false,
             envelopeDeclares: new Set(),
             perArrayKey: new Map(),
+            metadataFieldsByArrayKey: new Map(),
+            identityFieldsByArrayKey: new Map(),
         };
         schemaCache.set(key, entry);
         return entry;
     }
     const perArrayKey = new Map();
     collectArrayItemAuthorDecisions(schema, perArrayKey);
+    // Resolved content/metadata partition per array key (carried item 1).
+    // Collect the declared override keys, then resolve each through
+    // `metadataFieldsForSchema` so the cached value already carries the
+    // mandatory-floor union; identical resolution path as the read site.
+    const overrides = new Map();
+    collectArrayItemMetadataOverrides(schema, overrides);
+    const metadataFieldsByArrayKey = new Map();
+    for (const arrayKey of overrides.keys()) {
+        metadataFieldsByArrayKey.set(arrayKey, metadataFieldsForSchema(schema, arrayKey));
+    }
+    const identityFieldsByArrayKey = new Map();
+    collectArrayItemIdentityDecisions(schema, identityFieldsByArrayKey);
     const envelopeDeclares = schemaTopLevelDeclaredAuthorFields(schema);
     let anyArrayItemDeclares = false;
     for (const v of perArrayKey.values()) {
@@ -207,10 +489,26 @@ function getSchemaCacheEntry(schemaPath) {
         hasAuthorFields: envelopeDeclares.size > 0 || anyArrayItemDeclares,
         envelopeDeclares,
         perArrayKey,
+        metadataFieldsByArrayKey,
+        identityFieldsByArrayKey,
     };
     schemaCache.set(key, entry);
     return entry;
 }
+/**
+ * Does the item subschema for `arrayKey` under the schema at `schemaPath`
+ * declare all three identity fields (`oid`/`content_hash`/`content_parent`)?
+ * The Cycle-3 stamping gate (locked decision 1) — `false` (incl. for a missing
+ * schema or an uncatalogued key) means `prepareItemIdentityForWrite` is a
+ * no-op for this array. Mirrors `declaredAuthorFieldsForArray`'s
+ * cache-backed lookup shape.
+ */
+function arrayDeclaresIdentityFields(schemaPath, arrayKey) {
+    const entry = getSchemaCacheEntry(schemaPath);
+    if (!entry)
+        return false;
+    return entry.identityFieldsByArrayKey.get(arrayKey) ?? false;
+}
 /**
  * Subset of `AUTHOR_FIELDS` declared at the schema's top-level envelope.
  * Used by `writeTypedFile` to decide which envelope fields to stamp on a
@@ -252,6 +550,134 @@ function maybeStampItem(schemaPath, arrayKey, item, ctx, mode) {
         return item;
     return stampItem(item, ctx, mode, declared);
 }
+// ── Content-addressed identity stamping (Cycle 3 / Phase C) ──────────────────
+/**
+ * Mint a fresh OID for an item being born in `substrateId`. An OID is the
+ * substrate-stable, content-INDEPENDENT identity of an item across all its
+ * content versions (vs. `content_hash`, which moves with content; vs. `id`,
+ * the human refname). Derived as the first 32 hex chars of
+ * `sha256Hex(canonicalJson([substrateId, nonce ?? randomUUID()]))`:
+ *   - salting with `substrateId` makes two substrates that mint with the same
+ *     nonce produce distinct OIDs (cross-substrate uniqueness — the reason
+ *     Cycle 3 needs the substrate_id core);
+ *   - `nonce` is optional and exists for deterministic tests; production calls
+ *     pass none and get a fresh `randomUUID()` so each birth is unique even
+ *     within one substrate.
+ * 128 bits (32 hex) of digest is collision-free in the item-count regime.
+ *
+ * RETURN SHAPE: a bare 32-character lowercase-hex digest — no substrate prefix,
+ * no colon separator. `substrateId` salts the hash and does NOT appear in the
+ * returned value. (The `<substrate_id>:<oid>` colon-form seen elsewhere is the
+ * edge dedup key in `endpointIdentity`, not the oid itself.)
+ */
+export function mintOid(substrateId, nonce) {
+    const seed = nonce ?? randomUUID();
+    return sha256Hex(canonicalJson([substrateId, seed])).slice(0, 32);
+}
+/**
+ * Compute the content/identity fields for an item about to be written, per the
+ * content-addressed substrate identity model (Cycle 3 / Phase C). Returns the
+ * item with `oid` / `content_hash` / `content_parent` set; the input is never
+ * mutated (a shallow copy is returned). Also persists the content projection to
+ * the object store as a side effect on every stamping write.
+ *
+ * NO-OP GATE (locked decision 1): when the item's array subschema does not
+ * declare all three identity fields, the original `item` is returned unchanged
+ * (no oid mint, no hash, no object write, no substrate_id read). This scopes
+ * the behavior change to exactly the schemas Cycle 3 edits — bespoke test
+ * schemas without the fields are untouched — mirroring `maybeStampItem`'s
+ * author-field gate. The gate is NOT ctx-gated: content hash / oid are
+ * integrity, not attestation.
+ *
+ * Ordering vs author-stamp: call AFTER `maybeStampItem`/`maybeStampTypedItem`.
+ * Author fields are in the metadata partition (excluded from the projection),
+ * so the content hash is invariant to whether author-stamping ran first — but
+ * `content_hash` itself is a metadata field, so it must be assigned AFTER the
+ * projection is computed from the (already author-stamped) item.
+ *
+ * `mode`:
+ *   - `"create"`: mint a fresh `oid` (via `substrateIdForDir(substrateDir)`),
+ *     compute `content_hash`, set NO `content_parent` (a v1 item has no prior).
+ *   - `"update"`: preserve `prior.oid` — and THROW if the incoming item carries
+ *     a different `oid` (locked decision 3: oid is immutable). Recompute
+ *     `content_hash`. When the content changed (new hash !== prior.content_hash)
+ *     set `content_parent = prior.content_hash`; when content is unchanged
+ *     (no-op write) leave `content_parent` at the prior value (not advanced).
+ *
+ * `prior` is the on-disk item being replaced (required for `"update"`); for
+ * `"create"` it is ignored.
+ */
+export function prepareItemIdentityForWrite(substrateDir, blockName, item, schemaPath, arrayKey, mode, prior) {
+    // Schema-gate: no-op unless the array's items declare all three identity
+    // fields. Cheap cache-backed check; runs before any substrate_id read or
+    // hashing so non-identity schemas pay nothing.
+    if (!arrayDeclaresIdentityFields(schemaPath, arrayKey)) {
+        return item;
+    }
+    const out = { ...item };
+    // `content_hash` is itself a metadata field; project (which drops it +
+    // the rest of the floor + discretionary metadata) BEFORE assigning the
+    // fresh hash. The schema must be parseable here — the gate passed, so the
+    // file exists and is valid JSON (getSchemaCacheEntry already parsed it).
+    const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
+    if (mode === "create") {
+        const substrateId = substrateIdForDir(substrateDir);
+        out.oid = mintOid(substrateId);
+        // content_parent intentionally absent on a v1 item.
+        const projection = contentProjection(schema, arrayKey, out);
+        const hash = computeContentHash(projection);
+        out.content_hash = hash;
+        // Object persistence is deferred to writeTypedFile's post-validation walk
+        // (Cycle 9.1 P6): stamping must not write to objects/ before the whole
+        // block clears AJV, else an AJV-fail leaves an orphan content object.
+        return out;
+    }
+    // mode === "update"
+    const priorOid = prior && typeof prior.oid === "string" ? prior.oid : undefined;
+    const incomingOid = typeof out.oid === "string" ? out.oid : undefined;
+    if (priorOid !== undefined && incomingOid !== undefined && incomingOid !== priorOid) {
+        throw new Error(`prepareItemIdentityForWrite: oid is immutable — update to block '${blockName}' (array '${arrayKey}') would change oid '${priorOid}' to '${incomingOid}'`);
+    }
+    // Preserve the prior oid (the canonical, content-independent identity).
+    // When there is no prior oid (e.g. an update against an item that predates
+    // identity stamping / was never stamped) the path ALWAYS mints — a
+    // caller-supplied oid is never honored on first stamp, upholding the
+    // "OIDs are system-minted, never caller-asserted" invariant identically to
+    // create-mode. (`incomingOid` is still consulted by the immutability throw
+    // guard above when a prior oid exists.)
+    if (priorOid !== undefined) {
+        out.oid = priorOid;
+    }
+    else {
+        out.oid = mintOid(substrateIdForDir(substrateDir));
+    }
+    const priorHash = prior && typeof prior.content_hash === "string" ? prior.content_hash : undefined;
+    const priorParent = prior && typeof prior.content_parent === "string" ? prior.content_parent : undefined;
+    const projection = contentProjection(schema, arrayKey, out);
+    const hash = computeContentHash(projection);
+    out.content_hash = hash;
+    // Object persistence deferred to writeTypedFile's post-validation walk
+    // (Cycle 9.1 P6); see create-mode note above.
+    // content_parent advances to the prior content_hash ONLY when content
+    // actually changed. On an unchanged-content write (no-op / author-only
+    // re-stamp) it is NOT advanced — instead the prior version's own
+    // content_parent is PRESERVED (carried forward) so the version chain is not
+    // truncated by a metadata-only write. When there is neither a prior hash
+    // (first stamping write on a pre-existing item) nor a prior parent, it is
+    // left absent.
+    if (priorHash !== undefined && priorHash !== hash) {
+        out.content_parent = priorHash;
+    }
+    else if (priorParent !== undefined) {
+        out.content_parent = priorParent;
+    }
+    else {
+        // No-op write whose prior had no parent (e.g. re-stamp of a v1 item):
+        // ensure a stale content_parent does not linger on the carried item.
+        delete out.content_parent;
+    }
+    return out;
+}
 /**
  * Read and parse a .project/{blockName}.json file.
  * Throws if the file does not exist or contains invalid JSON.
@@ -260,14 +686,14 @@ function maybeStampItem(schemaPath, arrayKey, item, ctx, mode) {
  * matching items in the specified array key. Non-array or missing keys return the
  * block unchanged. The filter is applied after parsing, before returning.
  */
-export function readBlock(cwd, blockName, filter) {
-    const filePath = blockFilePath(cwd, blockName);
+export function readBlockForDir(substrateDir, blockName, filter) {
+    const filePath = blockFilePathForDir(substrateDir, blockName);
     let content;
     try {
         content = fs.readFileSync(filePath, "utf-8");
     }
     catch {
-        throw new Error(`Block file not found: .project/${blockName}.json`);
+        throw new Error(`Block file not found: ${filePath}`);
     }
     let data;
     try {
@@ -275,7 +701,24 @@ export function readBlock(cwd, blockName, filter) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`Invalid JSON in block file: .project/${blockName}.json: ${msg}`);
+        throw new Error(`Invalid JSON in block file: ${filePath}: ${msg}`);
+    }
+    // Version-aware validation hook (FGAP-136 plan step 4). When the block has
+    // an existing schema AND the parsed data carries a schema_version field,
+    // route through validateBlockWithMigration with the substrate-loaded
+    // project MigrationRegistry. The hook is conditional on schema_version
+    // presence so pre-versioned blocks (no schema_version field on items)
+    // pass through unchanged — the migration boundary only fires when there
+    // IS a version assertion to compare against. Whole-block validation
+    // uses the parsed `data` as-is; per-array-item migration is out of
+    // scope today (the block envelope is what carries schema_version, not
+    // each item).
+    if (existingBlockSchemaPathForDir(substrateDir, blockName) !== null) {
+        const envelope = data;
+        if (envelope && typeof envelope === "object" && typeof envelope.schema_version === "string") {
+            const registry = getProjectMigrationRegistryForDir(substrateDir);
+            data = validateBlockWithMigrationForDir(substrateDir, blockName, envelope, registry);
+        }
     }
     if (filter) {
         const record = data;
@@ -286,13 +729,20 @@ export function readBlock(cwd, blockName, filter) {
     }
     return data;
 }
+export function readBlock(cwd, blockName, filter) {
+    // Assert the name BEFORE resolving the substrate dir so the FGAP-079
+    // path-traversal guard fires ahead of BootstrapNotFoundError (preserves the
+    // pre-Phase-0 ordering: name-guard precedes pointer resolution).
+    assertSubstrateName(blockName);
+    return readBlockForDir(resolveContextDir(cwd), blockName, filter);
+}
 /**
  * Resolve the existing schema path for a block (or null when no schema
  * file is present at the conventional location). Used by every wrapper
  * that delegates to the typed-file primitives.
  */
-function existingBlockSchemaPath(cwd, blockName) {
-    const schemaFile = blockSchemaPath(cwd, blockName);
+function existingBlockSchemaPathForDir(substrateDir, blockName) {
+    const schemaFile = blockSchemaPathForDir(substrateDir, blockName);
     return fs.existsSync(schemaFile) ? schemaFile : null;
 }
 /**
@@ -358,6 +808,28 @@ export function writeTypedFile(filePath, schemaPath, data, ctx, errorLabel) {
     if (schemaPath) {
         validateFromFile(schemaPath, toWrite, label);
     }
+    // Post-validation object persistence (Cycle 9.1 P6). Content objects are
+    // written to objects/ ONLY after the whole block clears AJV and BEFORE the
+    // tmp+rename — so an AJV-fail leaves no orphan object, and a committed block
+    // never references a missing object. Stamping (prepareItemIdentityForWrite)
+    // computed each item's content_hash but no longer persists; we persist here.
+    // Gated on schemaPath: a schema-less write carries no identity items, and
+    // the per-item content_hash check protects the non-stamping config/registry/
+    // relations/migrations writers (their items carry no content_hash).
+    if (schemaPath) {
+        const substrateDir = path.dirname(filePath);
+        const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
+        forEachBlockArray(toWrite, (arrayKey, arr) => {
+            for (const item of arr) {
+                if (item && typeof item === "object" && !Array.isArray(item)) {
+                    const rec = item;
+                    if (typeof rec.content_hash === "string" && !hasObject(substrateDir, rec.content_hash)) {
+                        putObject(substrateDir, rec.content_hash, contentProjection(schema, arrayKey, rec));
+                    }
+                }
+            }
+        });
+    }
     // Ensure directory exists
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     // Atomic write: tmp + rename. Callers needing read-modify-write atomicity
@@ -396,6 +868,77 @@ export function writeTypedFile(filePath, schemaPath, data, ctx, errorLabel) {
  * intentionally a no-op until a schema actually declares author fields
  * on a top-level array shape (no current consumer does so).
  */
+/**
+ * Atomic id-uniqueness guard for the append path. Reads the `id` off the
+ * incoming item (when it carries one) and rejects the append if any element
+ * already present in `arr` shares that id. Items genuinely lacking an `id`
+ * property are skipped (NOT fabricated) — mirrors the `"id" in item` gate the
+ * tool layer used. The check runs inside the caller's `withBlockLock` critical
+ * section against the array already in hand, so it is atomic (unlike a racy
+ * `readBlock`-then-`append` at the tool layer). `labelForArray` is the
+ * `<label>.<arrayKey>` context the message names.
+ */
+function assertAppendIdUnique(arr, item, labelForArray) {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+        return;
+    const rec = item;
+    if (!("id" in rec))
+        return;
+    const id = rec.id;
+    for (const existing of arr) {
+        if (existing && typeof existing === "object" && existing.id === id) {
+            throw new Error(`Item '${String(id)}' already exists in ${labelForArray}`);
+        }
+    }
+}
+/**
+ * Atomic whole-file id-uniqueness guard: rejects a whole-array write that
+ * itself carries two elements sharing an `id`. Only elements that HAVE an `id`
+ * property participate (mirrors `assertAppendIdUnique`'s gate); id-less
+ * elements are skipped. `labelForArray` is the `<label>.<arrayKey>` context the
+ * message names.
+ */
+function assertNoDuplicateIdsInArray(arr, labelForArray) {
+    const seen = new Set();
+    for (const el of arr) {
+        if (!el || typeof el !== "object" || Array.isArray(el))
+            continue;
+        const rec = el;
+        if (!("id" in rec))
+            continue;
+        const id = rec.id;
+        if (seen.has(id)) {
+            throw new Error(`Item '${String(id)}' already exists in ${labelForArray}`);
+        }
+        seen.add(id);
+    }
+}
+/**
+ * Pure-data recursive walk over every array-valued property at any depth.
+ * For a plain (non-array) object `data`, each `[key, value]` pair whose `value`
+ * is an array is reported via `visit(key, value)`, then each element of that
+ * array that is itself a plain (non-array) object is recursed into (so an
+ * item's own nested id-bearing arrays — e.g. `layer-plans` items'
+ * `layers` / `migration_phases` — are visited under their item-local key).
+ * No schema is consulted; this matches the block shapes the schemas use
+ * (top-level arrays of items, items carrying nested arrays of items). Non-array
+ * object-valued properties that are NOT array elements are not descended into —
+ * block items live in arrays, so only array elements are recursion frontiers.
+ */
+function forEachBlockArray(data, visit) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    for (const [key, value] of Object.entries(data)) {
+        if (!Array.isArray(value))
+            continue;
+        visit(key, value);
+        for (const el of value) {
+            if (el && typeof el === "object" && !Array.isArray(el)) {
+                forEachBlockArray(el, visit);
+            }
+        }
+    }
+}
 export function appendToTypedFile(filePath, schemaPath, arrayPath, item, ctx, errorLabel) {
     const label = errorLabel ?? filePath;
     withBlockLock(filePath, () => {
@@ -405,9 +948,14 @@ export function appendToTypedFile(filePath, schemaPath, arrayPath, item, ctx, er
             if (!Array.isArray(data)) {
                 throw new Error(`${label}: expected top-level array, got ${typeof data}`);
             }
-            const itemToAppend = ctx && item && typeof item === "object" && !Array.isArray(item)
+            // Atomic id-uniqueness guard (reads the in-hand array under the lock).
+            assertAppendIdUnique(data, item, `${label}.__top__`);
+            const authored = ctx && item && typeof item === "object" && !Array.isArray(item)
                 ? maybeStampItem(schemaPath, "__top__", item, ctx, "create")
                 : item;
+            // Identity-stamp AFTER author-stamp (ordering is hash-neutral; see
+            // prepareItemIdentityForWrite). Flat-array shape never identity-stamps.
+            const itemToAppend = maybeIdentityStampTypedItem(filePath, schemaPath, null, authored, "create");
             const next = [...data, itemToAppend];
             // Validate the WHOLE array against schemaPath, then write.
             writeTypedFile(filePath, schemaPath, next, undefined, label);
@@ -424,9 +972,12 @@ export function appendToTypedFile(filePath, schemaPath, arrayPath, item, ctx, er
         if (!Array.isArray(record[arrayPath])) {
             throw new Error(`${label} key '${arrayPath}' is not an array`);
         }
-        const itemToAppend = ctx && item && typeof item === "object" && !Array.isArray(item)
+        // Atomic id-uniqueness guard (reads the in-hand array under the lock).
+        assertAppendIdUnique(record[arrayPath], item, `${label}.${arrayPath}`);
+        const authored = ctx && item && typeof item === "object" && !Array.isArray(item)
             ? maybeStampItem(schemaPath, arrayPath, item, ctx, "create")
             : item;
+        const itemToAppend = maybeIdentityStampTypedItem(filePath, schemaPath, arrayPath, authored, "create");
         record[arrayPath] = [...record[arrayPath], itemToAppend];
         writeTypedFile(filePath, schemaPath, record, undefined, label);
     });
@@ -511,7 +1062,10 @@ export function appendManyToTypedFileIfAbsent(filePath, schemaPath, arrayPath, i
                 continue;
             }
             seen.add(key);
-            arr.push(candidate);
+            // Identity-stamp each newly-appended candidate (create mode; an
+            // append-if-absent candidate is always a fresh item). No-op unless
+            // the schema declares identity fields.
+            arr.push(maybeIdentityStampTypedItem(filePath, schemaPath, arrayPath, candidate, "create"));
             appended++;
         }
         if (appended > 0) {
@@ -581,6 +1135,27 @@ function maybeStampTypedItem(schemaPath, arrayPath, item, ctx, mode) {
     const key = arrayPath ?? "__top__";
     return maybeStampItem(schemaPath, key, item, ctx, mode);
 }
+/**
+ * Per-item identity stamping (Cycle 3) for the typed-file mutation primitives.
+ * Thin wrapper over `prepareItemIdentityForWrite` that derives
+ * `substrateDir` / `blockName` from `filePath` (block files live at
+ * `<substrateDir>/<block>.json`) and skips non-object items (a scalar / array
+ * item cannot carry identity fields). The flat-array key (`arrayPath === null`)
+ * maps to the `__top__` sentinel which `collectArrayItemIdentityDecisions`
+ * never populates, so flat-array shapes never identity-stamp — same
+ * intentional no-op as author stamping. NOT ctx-gated: identity is integrity,
+ * not attestation, so this runs whether or not a DispatchContext was supplied;
+ * the schema-gate inside `prepareItemIdentityForWrite` is the only fire/no-op
+ * decision.
+ */
+function maybeIdentityStampTypedItem(filePath, schemaPath, arrayPath, item, mode, prior) {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+        return item;
+    const substrateDir = path.dirname(filePath);
+    const blockName = path.basename(filePath, ".json");
+    const key = arrayPath ?? "__top__";
+    return prepareItemIdentityForWrite(substrateDir, blockName, item, schemaPath, key, mode, prior);
+}
 /**
  * Validated atomic find-by-predicate update of one item inside an array
  * reachable from `(filePath, schemaPath, arrayPath)`. Generalises
@@ -615,8 +1190,12 @@ export function updateItemInTypedFile(filePath, schemaPath, arrayPath, predicate
         if (matchCount > 1) {
             console.error(`[block-api] updateItemInBlock: ${matchCount} items matched predicate, only first updated`);
         }
-        const merged = { ...arr[idx], ...updates };
-        const updated = ctx ? maybeStampTypedItem(schemaPath, arrayPath, merged, ctx, "update") : merged;
+        const prior = arr[idx];
+        const merged = { ...prior, ...updates };
+        const authored = ctx ? maybeStampTypedItem(schemaPath, arrayPath, merged, ctx, "update") : merged;
+        // Identity-stamp in update mode: preserve prior oid (throw on change),
+        // recompute hash, advance content_parent on content change.
+        const updated = maybeIdentityStampTypedItem(filePath, schemaPath, arrayPath, authored, "update", prior);
         const patched = [...arr];
         patched[idx] = updated;
         writeTypedFile(filePath, schemaPath, rewriteParent(patched), undefined, label);
@@ -677,7 +1256,14 @@ export function upsertItemInTypedFile(filePath, schemaPath, arrayPath, item, idF
                 itemForStamp = { ...carriedFields, ...item };
             }
         }
-        const stamped = ctx ? maybeStampTypedItem(schemaPath, arrayPath, itemForStamp, ctx, stampMode) : itemForStamp;
+        const authored = ctx ? maybeStampTypedItem(schemaPath, arrayPath, itemForStamp, ctx, stampMode) : itemForStamp;
+        // Identity-stamp: append branch is create (no prior); replace branch is
+        // update with the on-disk item as prior, so prepareItemIdentityForWrite
+        // preserves the prior oid even though upsert REPLACES (the supplied item
+        // carries no oid) and advances content_parent on content change. This is
+        // the identity analogue of the FGAP-018 created_* carry-forward above.
+        const priorForIdentity = idx === -1 ? undefined : arr[idx];
+        const stamped = maybeIdentityStampTypedItem(filePath, schemaPath, arrayPath, authored, stampMode, priorForIdentity);
         const patched = [...arr];
         if (idx === -1) {
             patched.push(stamped);
@@ -753,9 +1339,15 @@ export function appendToNestedTypedFile(filePath, schemaPath, parentArrayKey, pr
         if (!Array.isArray(parent[nestedArrayKey])) {
             throw new Error(`Matched item in ${label} key '${parentArrayKey}' nested key '${nestedArrayKey}' is not an array`);
         }
-        const itemToAppend = ctx && item && typeof item === "object" && !Array.isArray(item)
+        // Atomic id-uniqueness guard on the nested array (Cycle 9.1 P4): reads the
+        // in-hand nested array under the lock. Label names the full parent.nested path.
+        assertAppendIdUnique(parent[nestedArrayKey], item, `${label}.${parentArrayKey}.${nestedArrayKey}`);
+        const authored = ctx && item && typeof item === "object" && !Array.isArray(item)
             ? maybeStampItem(schemaPath, nestedArrayKey, item, ctx, "create")
             : item;
+        // Identity-stamp the appended nested item (create mode), keyed on the
+        // nested array key so the gate consults the nested item subschema.
+        const itemToAppend = maybeIdentityStampTypedItem(filePath, schemaPath, nestedArrayKey, authored, "create");
         const updatedParent = {
             ...parent,
             [nestedArrayKey]: [...parent[nestedArrayKey], itemToAppend],
@@ -813,8 +1405,12 @@ export function updateNestedItemInTypedFile(filePath, schemaPath, parentArrayKey
         if (nestedMatchCount > 1) {
             console.error(`[block-api] updateNestedArrayItem: ${nestedMatchCount} nested items matched predicate, only first updated`);
         }
-        const mergedNested = { ...nestedArr[nestedIdx], ...updates };
-        const updatedNested = ctx ? maybeStampItem(schemaPath, nestedArrayKey, mergedNested, ctx, "update") : mergedNested;
+        const priorNested = nestedArr[nestedIdx];
+        const mergedNested = { ...priorNested, ...updates };
+        const authoredNested = ctx ? maybeStampItem(schemaPath, nestedArrayKey, mergedNested, ctx, "update") : mergedNested;
+        // Identity-stamp the updated nested item (update mode; prior = on-disk
+        // nested item) so oid is preserved/immutable and content_parent advances.
+        const updatedNested = maybeIdentityStampTypedItem(filePath, schemaPath, nestedArrayKey, authoredNested, "update", priorNested);
         const patchedNested = [...nestedArr];
         patchedNested[nestedIdx] = updatedNested;
         const updatedParent = { ...parent, [nestedArrayKey]: patchedNested };
@@ -883,10 +1479,110 @@ export function removeFromNestedTypedFile(filePath, schemaPath, parentArrayKey,
  * stamping; callers wanting per-item attribution should prefer the
  * array-grained writers.
  */
+export function writeBlockForDir(substrateDir, blockName, data, ctx) {
+    const filePath = blockFilePathForDir(substrateDir, blockName);
+    const schemaPath = existingBlockSchemaPathForDir(substrateDir, blockName);
+    // Whole-block identity stamping (Cycle 3): for every top-level array whose
+    // item subschema declares the identity fields, stamp each item — mint-or-
+    // preserve oid, recompute content_hash, advance content_parent on change.
+    // Prior item state is read from the on-disk block and matched by oid (then
+    // id) so a re-written item preserves its oid and only advances its parent
+    // when its content actually changed. A no-op for non-identity schemas /
+    // non-object data (the gate inside prepareItemIdentityForWrite short-
+    // circuits). Author-only re-stamping is hash-neutral, so a whole-block
+    // re-write that merely refreshes attestation leaves content hashes stable.
+    // Whole-file id-uniqueness guard: a whole-block write carrying two items
+    // sharing an `id` within one array is rejected before stamping/validation.
+    // Recurses through nested id-bearing arrays (Cycle 9.1 P4) so a duplicate id
+    // inside e.g. a `layer-plans` item's `layers` is rejected too.
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+        forEachBlockArray(data, (arrayKey, arr) => assertNoDuplicateIdsInArray(arr, `${blockName}.${arrayKey}`));
+    }
+    let identityStamped = data;
+    if (schemaPath !== null && data && typeof data === "object" && !Array.isArray(data)) {
+        identityStamped = stampWholeBlockIdentity(substrateDir, blockName, filePath, schemaPath, data);
+    }
+    // Version-aware pre-write validation (FGAP-136 plan step 4). When a
+    // schema is present AND the data envelope carries a schema_version,
+    // run validateBlockWithMigration with the substrate-loaded
+    // MigrationRegistry. A version-mismatch with no declared migration
+    // throws upstream of writeTypedFile so the file never lands; a
+    // declared migration walks the data forward before AJV runs. The
+    // migrated form is what writeTypedFile receives. The ForDir registry +
+    // validation read the TARGET substrate's schema + migrations.json, never
+    // the active dir's.
+    let toWrite = identityStamped;
+    if (schemaPath !== null &&
+        identityStamped &&
+        typeof identityStamped === "object" &&
+        typeof identityStamped.schema_version === "string") {
+        const registry = getProjectMigrationRegistryForDir(substrateDir);
+        toWrite = validateBlockWithMigrationForDir(substrateDir, blockName, identityStamped, registry);
+    }
+    writeTypedFile(filePath, schemaPath, toWrite, ctx, `block file '${blockName}.json'`);
+}
+/**
+ * Identity-stamp every item of every top-level array in a whole-block write
+ * (Cycle 3 / locked decision: writeBlockForDir stamps each array item). Reads
+ * the on-disk block (if present) to build a prior-item index keyed by `oid`
+ * (primary) then `id` (fallback), so each re-written item:
+ *   - reuses its prior `oid` (immutable; `prepareItemIdentityForWrite` throws
+ *     if the incoming item carries a DIFFERENT non-empty oid),
+ *   - recomputes its `content_hash`,
+ *   - advances `content_parent` to the prior hash only when content changed.
+ * An item with no on-disk match is treated as a fresh create (mints an oid).
+ * Returns a shallow-cloned block; the input is not mutated. Arrays whose item
+ * subschema does not declare the identity fields pass through untouched (the
+ * gate inside `prepareItemIdentityForWrite` short-circuits per item).
+ */
+function stampWholeBlockIdentity(substrateDir, blockName, filePath, schemaPath, data) {
+    // Read prior on-disk block directly (no migration hook, no lock — caller
+    // holds the lock when one is needed; a fresh read here just supplies the
+    // prior-item index). Absent file → no priors → every item is a create.
+    let priorData = null;
+    if (fs.existsSync(filePath)) {
+        try {
+            priorData = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            priorData = null;
+        }
+    }
+    const out = { ...data };
+    for (const [arrayKey, value] of Object.entries(data)) {
+        if (!Array.isArray(value))
+            continue;
+        if (!arrayDeclaresIdentityFields(schemaPath, arrayKey))
+            continue;
+        // Build prior index for this array, keyed by oid then id.
+        const priorByOid = new Map();
+        const priorById = new Map();
+        const priorArr = priorData && Array.isArray(priorData[arrayKey]) ? priorData[arrayKey] : [];
+        for (const p of priorArr) {
+            if (!p || typeof p !== "object")
+                continue;
+            const rec = p;
+            if (typeof rec.oid === "string")
+                priorByOid.set(rec.oid, rec);
+            if (typeof rec.id === "string")
+                priorById.set(rec.id, rec);
+        }
+        out[arrayKey] = value.map((item) => {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                return item;
+            const rec = item;
+            const prior = (typeof rec.oid === "string" ? priorByOid.get(rec.oid) : undefined) ??
+                (typeof rec.id === "string" ? priorById.get(rec.id) : undefined);
+            const mode = prior ? "update" : "create";
+            return prepareItemIdentityForWrite(substrateDir, blockName, rec, schemaPath, arrayKey, mode, prior);
+        });
+    }
+    return out;
+}
 export function writeBlock(cwd, blockName, data, ctx) {
-    const filePath = blockFilePath(cwd, blockName);
-    const schemaPath = existingBlockSchemaPath(cwd, blockName);
-    writeTypedFile(filePath, schemaPath, data, ctx, `block file '${blockName}.json'`);
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    writeBlockForDir(resolveContextDir(cwd), blockName, data, ctx);
 }
 /**
  * Read current file, push item onto data[arrayKey], validate whole file
@@ -900,9 +1596,9 @@ export function writeBlock(cwd, blockName, data, ctx) {
  * `additionalProperties: false` AJV failures on blocks whose item shape
  * doesn't carry author markers yet.
  */
-export function appendToBlock(cwd, blockName, arrayKey, item, ctx) {
-    withBlockLock(blockFilePath(cwd, blockName), () => {
-        const data = readBlock(cwd, blockName);
+export function appendToBlockForDir(substrateDir, blockName, arrayKey, item, ctx) {
+    withBlockLock(blockFilePathForDir(substrateDir, blockName), () => {
+        const data = readBlockForDir(substrateDir, blockName);
         if (!data || typeof data !== "object") {
             throw new Error(`Block '${blockName}' is not an object`);
         }
@@ -913,17 +1609,26 @@ export function appendToBlock(cwd, blockName, arrayKey, item, ctx) {
         if (!Array.isArray(record[arrayKey])) {
             throw new Error(`Block '${blockName}' key '${arrayKey}' is not an array`);
         }
+        // Atomic id-uniqueness guard (reads the in-hand array under the lock).
+        // This primitive writes inline (does NOT route through appendToTypedFile),
+        // so the guard is applied here separately.
+        assertAppendIdUnique(record[arrayKey], item, `${blockName}.${arrayKey}`);
         // Optional ctx-stamping for object-shaped items (skipped silently for
         // scalar items even when the schema technically permits author fields —
         // stamping a string / number is meaningless).
-        const schemaPath = existingBlockSchemaPath(cwd, blockName);
+        const schemaPath = existingBlockSchemaPathForDir(substrateDir, blockName);
         const itemToAppend = ctx && item && typeof item === "object" && !Array.isArray(item)
             ? maybeStampItem(schemaPath, arrayKey, item, ctx, "create")
             : item;
         record[arrayKey] = [...record[arrayKey], itemToAppend];
-        writeBlock(cwd, blockName, record);
+        writeBlockForDir(substrateDir, blockName, record);
     });
 }
+export function appendToBlock(cwd, blockName, arrayKey, item, ctx) {
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    appendToBlockForDir(resolveContextDir(cwd), blockName, arrayKey, item, ctx);
+}
 /**
  * Find an item in data[arrayKey] by predicate, shallow-merge updates onto it,
  * validate whole file against schema, write atomically. Throws if no item
@@ -934,11 +1639,16 @@ export function appendToBlock(cwd, blockName, arrayKey, item, ctx) {
  * update-mode after the shallow merge — `created_by` / `created_at` are
  * preserved, `modified_by` / `modified_at` refresh.
  */
-export function updateItemInBlock(cwd, blockName, arrayKey, predicate, updates, ctx) {
-    const filePath = blockFilePath(cwd, blockName);
-    const schemaPath = existingBlockSchemaPath(cwd, blockName);
+export function updateItemInBlockForDir(substrateDir, blockName, arrayKey, predicate, updates, ctx) {
+    const filePath = blockFilePathForDir(substrateDir, blockName);
+    const schemaPath = existingBlockSchemaPathForDir(substrateDir, blockName);
     updateItemInTypedFile(filePath, schemaPath, arrayKey, predicate, updates, ctx, `block file '${blockName}.json'`);
 }
+export function updateItemInBlock(cwd, blockName, arrayKey, predicate, updates, ctx) {
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    updateItemInBlockForDir(resolveContextDir(cwd), blockName, arrayKey, predicate, updates, ctx);
+}
 /**
  * Atomically find-or-append a single item in `data[arrayKey]` keyed by
  * `idField`. Acquires the block lock; reads the array; locates the first
@@ -965,11 +1675,16 @@ export function updateItemInBlock(cwd, blockName, arrayKey, predicate, updates,
  * to merge against. Callers that need merge-on-update should continue to
  * use `updateItemInBlock`.
  */
-export function upsertItemInBlock(cwd, blockName, arrayKey, item, idField, ctx) {
-    const filePath = blockFilePath(cwd, blockName);
-    const schemaPath = existingBlockSchemaPath(cwd, blockName);
+export function upsertItemInBlockForDir(substrateDir, blockName, arrayKey, item, idField, ctx) {
+    const filePath = blockFilePathForDir(substrateDir, blockName);
+    const schemaPath = existingBlockSchemaPathForDir(substrateDir, blockName);
     return upsertItemInTypedFile(filePath, schemaPath, arrayKey, item, idField, ctx, `block file '${blockName}.json'`);
 }
+export function upsertItemInBlock(cwd, blockName, arrayKey, item, idField, ctx) {
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    return upsertItemInBlockForDir(resolveContextDir(cwd), blockName, arrayKey, item, idField, ctx);
+}
 /**
  * Atomically append an item to a nested array inside a parent-array item.
  *
@@ -982,11 +1697,16 @@ export function upsertItemInBlock(cwd, blockName, arrayKey, item, idField, ctx)
  * file lock, predicate findIndex, multi-match warning, clone-before-write so
  * the original array remains unmodified if writeBlock throws.
  */
-export function appendToNestedArray(cwd, blockName, parentArrayKey, predicate, nestedArrayKey, item, ctx) {
-    const filePath = blockFilePath(cwd, blockName);
-    const schemaPath = existingBlockSchemaPath(cwd, blockName);
+export function appendToNestedArrayForDir(substrateDir, blockName, parentArrayKey, predicate, nestedArrayKey, item, ctx) {
+    const filePath = blockFilePathForDir(substrateDir, blockName);
+    const schemaPath = existingBlockSchemaPathForDir(substrateDir, blockName);
     appendToNestedTypedFile(filePath, schemaPath, parentArrayKey, predicate, nestedArrayKey, item, ctx, `block file '${blockName}.json'`);
 }
+export function appendToNestedArray(cwd, blockName, parentArrayKey, predicate, nestedArrayKey, item, ctx) {
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    appendToNestedArrayForDir(resolveContextDir(cwd), blockName, parentArrayKey, predicate, nestedArrayKey, item, ctx);
+}
 /**
  * Atomically update a single item inside a nested array on a parent-array
  * item: locate parent by parentPredicate, locate nested by nestedPredicate,
@@ -999,11 +1719,16 @@ export function appendToNestedArray(cwd, blockName, parentArrayKey, predicate, n
  * updateItemInBlock convention). Clone-then-write keeps the original arrays
  * unmodified if writeBlock throws.
  */
-export function updateNestedArrayItem(cwd, blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, updates, ctx) {
-    const filePath = blockFilePath(cwd, blockName);
-    const schemaPath = existingBlockSchemaPath(cwd, blockName);
+export function updateNestedArrayItemForDir(substrateDir, blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, updates, ctx) {
+    const filePath = blockFilePathForDir(substrateDir, blockName);
+    const schemaPath = existingBlockSchemaPathForDir(substrateDir, blockName);
     updateNestedItemInTypedFile(filePath, schemaPath, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, updates, ctx, `block file '${blockName}.json'`);
 }
+export function updateNestedArrayItem(cwd, blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, updates, ctx) {
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    updateNestedArrayItemForDir(resolveContextDir(cwd), blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, updates, ctx);
+}
 /**
  * Atomically remove all items matching `predicate` from a top-level array
  * inside `data[arrayKey]`, validate the whole file against schema, write
@@ -1013,11 +1738,16 @@ export function updateNestedArrayItem(cwd, blockName, parentArrayKey, parentPred
  * without throwing — removal of a non-existent item is treated as an
  * idempotent successful no-op, distinct from update which throws on miss.
  */
-export function removeFromBlock(cwd, blockName, arrayKey, predicate, ctx) {
-    const filePath = blockFilePath(cwd, blockName);
-    const schemaPath = existingBlockSchemaPath(cwd, blockName);
+export function removeFromBlockForDir(substrateDir, blockName, arrayKey, predicate, ctx) {
+    const filePath = blockFilePathForDir(substrateDir, blockName);
+    const schemaPath = existingBlockSchemaPathForDir(substrateDir, blockName);
     return removeFromTypedFile(filePath, schemaPath, arrayKey, predicate, ctx, `block file '${blockName}.json'`);
 }
+export function removeFromBlock(cwd, blockName, arrayKey, predicate, ctx) {
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    return removeFromBlockForDir(resolveContextDir(cwd), blockName, arrayKey, predicate, ctx);
+}
 /**
  * Atomically remove all items matching `nestedPredicate` from a nested array
  * inside the parent-array item matched by `parentPredicate`. Validates and
@@ -1028,11 +1758,16 @@ export function removeFromBlock(cwd, blockName, arrayKey, predicate, ctx) {
  * mirrors removeFromBlock semantics). Multi-match warning at parent level
  * via console.error.
  */
-export function removeFromNestedArray(cwd, blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, ctx) {
-    const filePath = blockFilePath(cwd, blockName);
-    const schemaPath = existingBlockSchemaPath(cwd, blockName);
+export function removeFromNestedArrayForDir(substrateDir, blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, ctx) {
+    const filePath = blockFilePathForDir(substrateDir, blockName);
+    const schemaPath = existingBlockSchemaPathForDir(substrateDir, blockName);
     return removeFromNestedTypedFile(filePath, schemaPath, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, ctx, `block file '${blockName}.json'`);
 }
+export function removeFromNestedArray(cwd, blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, ctx) {
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    return removeFromNestedArrayForDir(resolveContextDir(cwd), blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, ctx);
+}
 /**
  * Read all `.json` files in a `.project/<subdir>/` directory and return the
  * parsed contents as a sorted array. Sort order is filesystem-name ascending
@@ -1044,11 +1779,8 @@ export function removeFromNestedArray(cwd, blockName, parentArrayKey, parentPred
  * byte-identically; both pi-workflows and the `read-block-dir` registered
  * tool consume this single export.
  */
-export function readBlockDir(cwd, subdir) {
-    const root = tryResolveContextDir(cwd);
-    if (root === null)
-        return []; // no .pi-context.json pointer → no items (consistent with missing-dir → [])
-    const dirPath = path.join(root, subdir);
+export function readBlockDirForDir(substrateDir, subdir) {
+    const dirPath = path.join(substrateDir, subdir);
     let entries;
     try {
         entries = fs
@@ -1068,17 +1800,23 @@ export function readBlockDir(cwd, subdir) {
             content = fs.readFileSync(filePath, "utf-8");
         }
         catch {
-            throw new Error(`Cannot read file: .project/${subdir}/${filename}`);
+            throw new Error(`Cannot read file: ${filePath}`);
         }
         try {
             results.push(JSON.parse(content));
         }
         catch {
-            throw new Error(`Invalid JSON in: .project/${subdir}/${filename}`);
+            throw new Error(`Invalid JSON in: ${filePath}`);
         }
     }
     return results;
 }
+export function readBlockDir(cwd, subdir) {
+    const root = tryResolveContextDir(cwd);
+    if (root === null)
+        return []; // no .pi-context.json pointer → no items (consistent with missing-dir → [])
+    return readBlockDirForDir(root, subdir);
+}
 // ── Item-schema resolution + id allocation (FGAP-083 / FGAP-084) ──────────────
 /**
  * Resolve the item subschema for a block schema: find the first array property
@@ -1131,8 +1869,8 @@ export function resolveBlockItemSchema(schema) {
  * prefix+width parseable. Orchestrator CLIs + the in-pi append tool route
  * through this instead of re-implementing allocation.
  */
-export function nextId(cwd, blockName) {
-    const schemaFile = blockSchemaPath(cwd, blockName);
+export function nextIdForDir(substrateDir, blockName) {
+    const schemaFile = blockSchemaPathForDir(substrateDir, blockName);
     if (!fs.existsSync(schemaFile)) {
         throw new Error(`nextId: schema not found for block '${blockName}' at ${schemaFile}`);
     }
@@ -1149,7 +1887,7 @@ export function nextId(cwd, blockName) {
     }
     const prefix = m[1];
     const width = Number.parseInt(m[2], 10);
-    const data = readBlock(cwd, blockName);
+    const data = readBlockForDir(substrateDir, blockName);
     const items = (data[arrayKey] ?? []);
     const re = new RegExp(`^${prefix}(\\d+)$`);
     let maxN = 0;
@@ -1164,4 +1902,9 @@ export function nextId(cwd, blockName) {
     }
     return `${prefix}${String(maxN + 1).padStart(width, "0")}`;
 }
+export function nextId(cwd, blockName) {
+    // Name-guard before pointer resolution (FGAP-079 ordering; see readBlock).
+    assertSubstrateName(blockName);
+    return nextIdForDir(resolveContextDir(cwd), blockName);
+}
 //# sourceMappingURL=block-api.js.map