@davidorex/pi-context 0.26.0 → 0.28.1

package/dist/context-dir.d.ts

@@ -48,6 +48,27 @@ export declare function resolveContextDir(cwd: string): string;
  * boundaries under tsx/dist dual-load).
  */
 export declare function tryResolveContextDir(cwd: string): string | null;
+/**
+ * Optional pointer-history fields stamped onto the bootstrap pointer by
+ * `flipBootstrapPointer` (the /context switch family's mutation surface).
+ * Pre-fresh-init pointers carry NONE of these; switched pointers carry ALL
+ * three. The bootstrap schema declares each as optional so existing v1.0.0
+ * pointers remain valid against v1.1.0 — missing optional fields resolve to
+ * undefined in-process.
+ *
+ * `previous_contextDir` is the contextDir value the pointer held IMMEDIATELY
+ * BEFORE the most-recent flip; consumed by `/context switch -` to flip back.
+ *
+ * `switched_at` is the ISO 8601 timestamp of the most-recent flip.
+ *
+ * `switched_by` is the verified terminal-operator identity stamped by auth-gate
+ * on confirm; forensic attribution for the flip.
+ */
+export interface BootstrapPointerExtras {
+    previous_contextDir?: string;
+    switched_at?: string;
+    switched_by?: string;
+}
 /**
  * Atomically write a `.pi-context.json` bootstrap pointer at `<cwd>/.pi-context.json`.
  * `contextDir` is a required parameter chosen by the caller per DEC-0015 —
@@ -60,8 +81,48 @@ export declare function tryResolveContextDir(cwd: string): string | null;
  * `bootstrapCache` entry for this cwd so the next `resolveContextDir(cwd)`
  * call reads fresh data even if mtime granularity (1s on some filesystems)
  * would otherwise mask the change.
+ *
+ * Backwards-compatible signature evolution: the optional `extras` parameter
+ * carries the v1.1.0 pointer-history fields. When `extras` is omitted (default,
+ * existing call sites) the writer behaves identically to its v1.0.0 form —
+ * pointer carries only `{contextDir, version, created_at}` and `version` stays
+ * at "1.0.0". When `extras` is provided, the pointer-history fields are
+ * merged in and `version` bumps to "1.1.0" so the on-disk pointer self-declares
+ * the format it carries. `created_at` is FRESH on every call (this primitive
+ * does not preserve created_at across writes — see `flipBootstrapPointer` for
+ * the preservation contract).
  */
-export declare function writeBootstrapPointer(cwd: string, contextDir: string): void;
+export declare function writeBootstrapPointer(cwd: string, contextDir: string, extras?: BootstrapPointerExtras): void;
+/**
+ * Flip the bootstrap pointer to a new contextDir while preserving the original
+ * `created_at` timestamp and stamping pointer-history fields (previous_contextDir,
+ * switched_at, switched_by). The mutation surface for `/context switch` family
+ * + `context-switch` Pi tool.
+ *
+ * Behavior:
+ * 1. Reads the existing pointer (throws BootstrapNotFoundError when absent —
+ *    flipping a pointer that does not exist is a programming error; callers
+ *    bootstrapping a fresh substrate use `writeBootstrapPointer` directly).
+ * 2. Constructs the new pointer:
+ *    - contextDir: `newContextDir` (the flip target)
+ *    - version: "1.1.0" (pointer-history-bearing)
+ *    - created_at: PRESERVED from the existing pointer (or stamped fresh when
+ *      the existing pointer lacks created_at, which only happens for hand-
+ *      authored pointers that omit the field)
+ *    - previous_contextDir: the existing pointer's contextDir (so subsequent
+ *      `/context switch -` can flip back)
+ *    - switched_at: current ISO 8601 timestamp
+ *    - switched_by: caller-supplied `writerIdentity` (auth-gate-verified
+ *      terminal-operator identity at the Pi tool boundary)
+ * 3. AJV-validates against the URN-registered bootstrap schema.
+ * 4. Atomic tmp + rename write.
+ * 5. Invalidates `bootstrapCache` for the cwd.
+ *
+ * Does NOT validate that `newContextDir` exists / has a config.json — that is
+ * the caller's read-side check (slash command handler + Pi tool body each
+ * perform target-dir-shape validation appropriate to their mode).
+ */
+export declare function flipBootstrapPointer(cwd: string, newContextDir: string, writerIdentity: string): void;
 /**
  * Reject substrate names that are not bare path segments (FGAP-079 / DEC-0045).
  *
@@ -87,7 +148,71 @@ export declare function assertSubstrateName(name: string): void;
  * hardcoded.
  */
 export declare function schemasDir(cwd: string): string;
+/**
+ * Dir-targeted form of `schemaPath`: build the schema path against an
+ * explicit substrate directory rather than resolving one from `cwd`.
+ * `assertSubstrateName` still guards the block name (path-injection guard
+ * preserved). Cross-substrate consumers (Cycle F resolver / Cycle H
+ * migration) target a non-active substrate by passing its directory here.
+ */
+export declare function schemaPathForDir(substrateDir: string, blockName: string): string;
 export declare function schemaPath(cwd: string, blockName: string): string;
 export declare function agentsDir(cwd: string): string;
 export declare function contextTemplatesDir(cwd: string): string;
+/**
+ * `<resolveContextDir(cwd)>/migrations.json` — substrate-managed file holding
+ * operator-authored schema version migration declarations. Singleton file per
+ * cwd (no per-name guard); see `migrations-store.ts` for read / write helpers
+ * and `migration-registry-loader.ts` for the loader that converts declarations
+ * into a populated MigrationRegistry. Mirrors the relationsPath / configPath
+ * shape: pointer-resolved, substrate-dir-relative, no fallback default.
+ */
+/**
+ * Dir-targeted form of `migrationsPath`: build the `migrations.json` path
+ * against an explicit substrate directory rather than resolving one from
+ * `cwd`. Used by the ForDir migration-registry loader so a write into a
+ * non-active substrate validates/migrates against THAT substrate's
+ * declarations.
+ */
+export declare function migrationsPathForDir(substrateDir: string): string;
+export declare function migrationsPath(cwd: string): string;
+/**
+ * `^sub-[0-9a-f]{16}$` — the substrate_id shape. A substrate_id is the per-
+ * substrate root identity that `mintOid` (block-api.ts) salts an item OID with,
+ * so two substrates minting an item with the same birth nonce still produce
+ * distinct OIDs. Single source of truth for the on-disk `config.substrate_id`
+ * regex (mirrored as a literal `pattern` in config.schema.json — the two must
+ * not drift).
+ */
+export declare const SUBSTRATE_ID_PATTERN: RegExp;
+/**
+ * Mint a fresh substrate_id: `"sub-" + sha256Hex(canonicalJson([Date.now(),
+ * randomUUID()])).slice(0, 16)`. The `[epoch-ms, uuid]` tuple makes the pre-
+ * image collision-free in practice (the uuid alone suffices; the timestamp is
+ * a readability/ordering aid in the pre-image only, never surfaced). The
+ * 16-hex-char slice keeps the id compact while leaving 64 bits of entropy —
+ * far beyond the substrate-count regime. Minted ONCE per substrate (at
+ * /context init in Cycle 4; established by hand for the active substrate +
+ * packaged samples this cycle) and then immutable on disk; never re-minted on
+ * an item write.
+ */
+export declare function mintSubstrateId(): string;
+/**
+ * Read the `substrate_id` from `<substrateDir>/config.json`. Throws loudly when
+ * the config is absent / unreadable / lacks a `substrate_id` — there is NO
+ * degraded fallback and NO lazy mint-on-read (locked decision 2): a substrate
+ * that participates in identity stamping must carry an explicit substrate_id,
+ * established when its identity-declaring schemas were established. The
+ * schema-gate on `prepareItemIdentityForWrite` (block-api.ts) and this throw
+ * align by construction — stamping only fires for substrates whose schemas
+ * declare the identity fields, which are exactly the substrates given a
+ * substrate_id — so the throw is a loud guard against a mis-provisioned
+ * substrate, not an expected runtime branch.
+ */
+export declare function substrateIdForDir(substrateDir: string): string;
+/**
+ * `substrateIdForDir(resolveContextDir(cwd))` — the cwd-resolved form for
+ * callers holding a working directory rather than an explicit substrate dir.
+ */
+export declare function substrateIdFor(cwd: string): string;
 //# sourceMappingURL=context-dir.d.ts.map

package/dist/context-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-dir.d.ts","sourceRoot":"","sources":["../src/context-dir.ts"],"names":[],"mappings":"AA+BA,mFAAmF;AACnF,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBACnB,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAQ9C;AA6BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuCrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CA+B3E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMtD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGjE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"context-dir.d.ts","sourceRoot":"","sources":["../src/context-dir.ts"],"names":[],"mappings":"AAiCA,mFAAmF;AACnF,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBACnB,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAQ9C;AA6BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuCrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,sBAAsB;IACtC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAuC5G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CA2DrG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMtD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQjE;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;GAOG;AACH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAAuB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CA8B9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/context-dir.js

@@ -25,8 +25,10 @@
  * workflow-executor.ts still import it as a bare segment); Phase 7 of
  * FGAP-026 closure cascades those sites and removes the export.
  */
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { canonicalJson, sha256Hex } from "./content-hash.js";
 import { validate } from "./schema-validator.js";
 /** @deprecated Same status as the removed PROJECT_DIR — Phase 7 cascade target. */
 export const SCHEMAS_DIR = "schemas";
@@ -42,7 +44,7 @@ export class BootstrapNotFoundError extends Error {
     cwd;
     bootstrapPath;
     constructor(cwd, bootstrapPath) {
-        super(`pi-context: no .pi-context.json bootstrap pointer at ${bootstrapPath}; run /context init to declare substrate dir per DEC-0015`);
+        super(`pi-context: no .pi-context.json bootstrap pointer at ${bootstrapPath}; run /context init <substrate-dir> to declare substrate dir per DEC-0015`);
         this.name = "BootstrapNotFoundError";
         this.cwd = cwd;
         this.bootstrapPath = bootstrapPath;
@@ -149,13 +151,31 @@ export function tryResolveContextDir(cwd) {
  * `bootstrapCache` entry for this cwd so the next `resolveContextDir(cwd)`
  * call reads fresh data even if mtime granularity (1s on some filesystems)
  * would otherwise mask the change.
+ *
+ * Backwards-compatible signature evolution: the optional `extras` parameter
+ * carries the v1.1.0 pointer-history fields. When `extras` is omitted (default,
+ * existing call sites) the writer behaves identically to its v1.0.0 form —
+ * pointer carries only `{contextDir, version, created_at}` and `version` stays
+ * at "1.0.0". When `extras` is provided, the pointer-history fields are
+ * merged in and `version` bumps to "1.1.0" so the on-disk pointer self-declares
+ * the format it carries. `created_at` is FRESH on every call (this primitive
+ * does not preserve created_at across writes — see `flipBootstrapPointer` for
+ * the preservation contract).
  */
-export function writeBootstrapPointer(cwd, contextDir) {
+export function writeBootstrapPointer(cwd, contextDir, extras) {
+    const hasExtras = extras !== undefined &&
+        (extras.previous_contextDir !== undefined || extras.switched_at !== undefined || extras.switched_by !== undefined);
     const pointer = {
         contextDir,
-        version: "1.0.0",
+        version: hasExtras ? "1.1.0" : "1.0.0",
         created_at: new Date().toISOString(),
     };
+    if (extras?.previous_contextDir !== undefined)
+        pointer.previous_contextDir = extras.previous_contextDir;
+    if (extras?.switched_at !== undefined)
+        pointer.switched_at = extras.switched_at;
+    if (extras?.switched_by !== undefined)
+        pointer.switched_by = extras.switched_by;
     // Validate before write — AJV via canonical `validate()` against
     // pre-registered bootstrap schema URN.
     validate(BOOTSTRAP_REF_SCHEMA, pointer, `bootstrap pointer (writeBootstrapPointer for ${cwd})`);
@@ -180,6 +200,85 @@ export function writeBootstrapPointer(cwd, contextDir) {
     // fresh pointer regardless of mtime-granularity edge cases.
     bootstrapCache.delete(path.resolve(cwd));
 }
+/**
+ * Flip the bootstrap pointer to a new contextDir while preserving the original
+ * `created_at` timestamp and stamping pointer-history fields (previous_contextDir,
+ * switched_at, switched_by). The mutation surface for `/context switch` family
+ * + `context-switch` Pi tool.
+ *
+ * Behavior:
+ * 1. Reads the existing pointer (throws BootstrapNotFoundError when absent —
+ *    flipping a pointer that does not exist is a programming error; callers
+ *    bootstrapping a fresh substrate use `writeBootstrapPointer` directly).
+ * 2. Constructs the new pointer:
+ *    - contextDir: `newContextDir` (the flip target)
+ *    - version: "1.1.0" (pointer-history-bearing)
+ *    - created_at: PRESERVED from the existing pointer (or stamped fresh when
+ *      the existing pointer lacks created_at, which only happens for hand-
+ *      authored pointers that omit the field)
+ *    - previous_contextDir: the existing pointer's contextDir (so subsequent
+ *      `/context switch -` can flip back)
+ *    - switched_at: current ISO 8601 timestamp
+ *    - switched_by: caller-supplied `writerIdentity` (auth-gate-verified
+ *      terminal-operator identity at the Pi tool boundary)
+ * 3. AJV-validates against the URN-registered bootstrap schema.
+ * 4. Atomic tmp + rename write.
+ * 5. Invalidates `bootstrapCache` for the cwd.
+ *
+ * Does NOT validate that `newContextDir` exists / has a config.json — that is
+ * the caller's read-side check (slash command handler + Pi tool body each
+ * perform target-dir-shape validation appropriate to their mode).
+ */
+export function flipBootstrapPointer(cwd, newContextDir, writerIdentity) {
+    const bootstrapPath = path.join(cwd, ".pi-context.json");
+    if (!fs.existsSync(bootstrapPath)) {
+        throw new BootstrapNotFoundError(cwd, bootstrapPath);
+    }
+    let existingRaw;
+    try {
+        existingRaw = fs.readFileSync(bootstrapPath, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`flipBootstrapPointer: failed to read existing ${bootstrapPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let existing;
+    try {
+        existing = JSON.parse(existingRaw);
+    }
+    catch (err) {
+        throw new Error(`flipBootstrapPointer: invalid JSON in existing ${bootstrapPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const previousContextDir = existing.contextDir;
+    if (typeof previousContextDir !== "string") {
+        throw new Error(`flipBootstrapPointer: existing pointer at ${bootstrapPath} lacks a string contextDir; refuses to flip an unreadable pointer`);
+    }
+    const preservedCreatedAt = typeof existing.created_at === "string" ? existing.created_at : new Date().toISOString();
+    const pointer = {
+        contextDir: newContextDir,
+        version: "1.1.0",
+        created_at: preservedCreatedAt,
+        previous_contextDir: previousContextDir,
+        switched_at: new Date().toISOString(),
+        switched_by: writerIdentity,
+    };
+    validate(BOOTSTRAP_REF_SCHEMA, pointer, `bootstrap pointer (flipBootstrapPointer for ${cwd})`);
+    const tmpPath = `${bootstrapPath}.bootstrap-${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(pointer, null, 2), "utf-8");
+        fs.renameSync(tmpPath, bootstrapPath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`flipBootstrapPointer: failed to write ${bootstrapPath}: ${msg}`);
+    }
+    bootstrapCache.delete(path.resolve(cwd));
+}
 /**
  * Reject substrate names that are not bare path segments (FGAP-079 / DEC-0045).
  *
@@ -211,9 +310,25 @@ export function assertSubstrateName(name) {
 export function schemasDir(cwd) {
     return path.join(resolveContextDir(cwd), SCHEMAS_DIR);
 }
+/**
+ * Dir-targeted form of `schemaPath`: build the schema path against an
+ * explicit substrate directory rather than resolving one from `cwd`.
+ * `assertSubstrateName` still guards the block name (path-injection guard
+ * preserved). Cross-substrate consumers (Cycle F resolver / Cycle H
+ * migration) target a non-active substrate by passing its directory here.
+ */
+export function schemaPathForDir(substrateDir, blockName) {
+    assertSubstrateName(blockName);
+    return path.join(substrateDir, SCHEMAS_DIR, `${blockName}.schema.json`);
+}
 export function schemaPath(cwd, blockName) {
+    // Assert the name BEFORE resolving the substrate dir so the FGAP-079
+    // path-traversal guard fires ahead of BootstrapNotFoundError (a traversal
+    // name must reject even when no `.pi-context.json` pointer exists). The
+    // ForDir body asserts again — harmless double-assert; the boundary guard
+    // is the point.
     assertSubstrateName(blockName);
-    return path.join(resolveContextDir(cwd), SCHEMAS_DIR, `${blockName}.schema.json`);
+    return schemaPathForDir(resolveContextDir(cwd), blockName);
 }
 export function agentsDir(cwd) {
     return path.join(resolveContextDir(cwd), "agents");
@@ -221,4 +336,93 @@ export function agentsDir(cwd) {
 export function contextTemplatesDir(cwd) {
     return path.join(resolveContextDir(cwd), "templates");
 }
+/**
+ * `<resolveContextDir(cwd)>/migrations.json` — substrate-managed file holding
+ * operator-authored schema version migration declarations. Singleton file per
+ * cwd (no per-name guard); see `migrations-store.ts` for read / write helpers
+ * and `migration-registry-loader.ts` for the loader that converts declarations
+ * into a populated MigrationRegistry. Mirrors the relationsPath / configPath
+ * shape: pointer-resolved, substrate-dir-relative, no fallback default.
+ */
+/**
+ * Dir-targeted form of `migrationsPath`: build the `migrations.json` path
+ * against an explicit substrate directory rather than resolving one from
+ * `cwd`. Used by the ForDir migration-registry loader so a write into a
+ * non-active substrate validates/migrates against THAT substrate's
+ * declarations.
+ */
+export function migrationsPathForDir(substrateDir) {
+    return path.join(substrateDir, "migrations.json");
+}
+export function migrationsPath(cwd) {
+    return migrationsPathForDir(resolveContextDir(cwd));
+}
+// ── Substrate identity (content-addressed substrate identity, Cycle 3) ────────
+/**
+ * `^sub-[0-9a-f]{16}$` — the substrate_id shape. A substrate_id is the per-
+ * substrate root identity that `mintOid` (block-api.ts) salts an item OID with,
+ * so two substrates minting an item with the same birth nonce still produce
+ * distinct OIDs. Single source of truth for the on-disk `config.substrate_id`
+ * regex (mirrored as a literal `pattern` in config.schema.json — the two must
+ * not drift).
+ */
+export const SUBSTRATE_ID_PATTERN = /^sub-[0-9a-f]{16}$/;
+/**
+ * Mint a fresh substrate_id: `"sub-" + sha256Hex(canonicalJson([Date.now(),
+ * randomUUID()])).slice(0, 16)`. The `[epoch-ms, uuid]` tuple makes the pre-
+ * image collision-free in practice (the uuid alone suffices; the timestamp is
+ * a readability/ordering aid in the pre-image only, never surfaced). The
+ * 16-hex-char slice keeps the id compact while leaving 64 bits of entropy —
+ * far beyond the substrate-count regime. Minted ONCE per substrate (at
+ * /context init in Cycle 4; established by hand for the active substrate +
+ * packaged samples this cycle) and then immutable on disk; never re-minted on
+ * an item write.
+ */
+export function mintSubstrateId() {
+    return `sub-${sha256Hex(canonicalJson([Date.now(), randomUUID()])).slice(0, 16)}`;
+}
+/**
+ * Read the `substrate_id` from `<substrateDir>/config.json`. Throws loudly when
+ * the config is absent / unreadable / lacks a `substrate_id` — there is NO
+ * degraded fallback and NO lazy mint-on-read (locked decision 2): a substrate
+ * that participates in identity stamping must carry an explicit substrate_id,
+ * established when its identity-declaring schemas were established. The
+ * schema-gate on `prepareItemIdentityForWrite` (block-api.ts) and this throw
+ * align by construction — stamping only fires for substrates whose schemas
+ * declare the identity fields, which are exactly the substrates given a
+ * substrate_id — so the throw is a loud guard against a mis-provisioned
+ * substrate, not an expected runtime branch.
+ */
+export function substrateIdForDir(substrateDir) {
+    const configPath = path.join(substrateDir, "config.json");
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`substrateIdForDir: no config.json at ${configPath}; a substrate that stamps identity must carry an explicit substrate_id (no lazy mint on write)`);
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`substrateIdForDir: failed to read ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`substrateIdForDir: invalid JSON in ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const substrateId = data && typeof data === "object" ? data.substrate_id : undefined;
+    if (typeof substrateId !== "string" || !SUBSTRATE_ID_PATTERN.test(substrateId)) {
+        throw new Error(`substrateIdForDir: config.json at ${configPath} has no valid substrate_id (expected ^sub-[0-9a-f]{16}$, got ${JSON.stringify(substrateId)}); establish one before stamping identity`);
+    }
+    return substrateId;
+}
+/**
+ * `substrateIdForDir(resolveContextDir(cwd))` — the cwd-resolved form for
+ * callers holding a working directory rather than an explicit substrate dir.
+ */
+export function substrateIdFor(cwd) {
+    return substrateIdForDir(resolveContextDir(cwd));
+}
 //# sourceMappingURL=context-dir.js.map

package/dist/context-dir.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-dir.js","sourceRoot":"","sources":["../src/context-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,mFAAmF;AACnF,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACvC,GAAG,CAAS;IACZ,aAAa,CAAS;IAC/B,YAAY,GAAW,EAAE,aAAqB;QAC7C,KAAK,CACJ,wDAAwD,aAAa,2DAA2D,CAChI,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACpC,CAAC;CACD;AAeD,MAAM,cAAc,GAAG,IAAI,GAAG,EAA+B,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAA4B;IACrD,IAAI,EAAE,gCAAgC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC5C,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;IACzD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,sBAAsB,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,KAAK,GAAG,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,OAAO,CAAC;IACjD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,MAAM,IAAI,MAAM,CAAC,gBAAgB,KAAK,KAAK,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACJ,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACd,qCAAqC,aAAa,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACzG,CAAC;IACH,CAAC;IACD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACJ,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACd,sCAAsC,aAAa,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC1G,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,qEAAqE;IACrE,qEAAqE;IACrE,+CAA+C;IAC/C,QAAQ,CAAC,oBAAoB,EAAE,IAAI,EAAE,sBAAsB,aAAa,GAAG,CAAC,CAAC;IAE7E,MAAM,UAAU,GAAI,IAA+B,CAAC,UAAU,CAAC;IAC/D,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC/C,IAAI,CAAC;QACJ,OAAO,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,wBAAwB;YAAE,OAAO,IAAI,CAAC;QAC/E,MAAM,GAAG,CAAC;IACX,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW,EAAE,UAAkB;IACpE,MAAM,OAAO,GAAG;QACf,UAAU;QACV,OAAO,EAAE,OAAO;QAChB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,iEAAiE;IACjE,uCAAuC;IACvC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,EAAE,gDAAgD,GAAG,GAAG,CAAC,CAAC;IAEhG,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;IACzD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/D,MAAM,OAAO,GAAG,GAAG,aAAa,cAAc,OAAO,CAAC,GAAG,MAAM,CAAC;IAChE,IAAI,CAAC;QACJ,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAI,CAAC;YACJ,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACR,4BAA4B;QAC7B,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,0CAA0C,aAAa,KAAK,GAAG,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,uEAAuE;IACvE,4DAA4D;IAC5D,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC/C,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACd,2BAA2B,IAAI,6EAA6E,CAC5G,CAAC;IACH,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,SAAiB;IACxD,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,GAAG,SAAS,cAAc,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"context-dir.js","sourceRoot":"","sources":["../src/context-dir.ts"],"names":[],"mappings":"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"}

package/dist/context-registry.d.ts

@@ -0,0 +1,122 @@
+/**
+ * context-registry — project-root substrate registry read / write surface for
+ * `<cwd>/.pi-context-registry.json`.
+ *
+ * The registry is a PROJECT-ROOT file (tracked in git, like `.pi-context.json`),
+ * NOT substrate-relative: it enumerates EVERY known substrate by its immutable
+ * content-addressed `substrate_id` (`^sub-[0-9a-f]{16}$`), mapping each to its
+ * on-disk directory + alias list. This is the substrate-locator layer the
+ * Cycle-8 F2 resolver consumes to resolve a foreign `<substrate_id>:<oid>` /
+ * `<alias>:<refname>` locator to a directory, and the surface the Phase-H
+ * migration registers each legacy substrate into.
+ *
+ * Distinct from the `.pi-context.json` bootstrap pointer: the pointer names the
+ * single ACTIVE substrate dir; this registry enumerates all of them. The
+ * SoT-drift invariant in `validateContext` (context-sdk.ts) requires the active
+ * `config.substrate_id` to have an entry here whose `dir` resolves to the active
+ * substrate.
+ *
+ * Mirrors `migrations-store.ts` atomic discipline one-for-one:
+ *   - `loadRegistry` reads + JSON-parses + AJV-validates via `validateFromFile`
+ *     against the bundled `context-registry.schema.json`; returns null when the
+ *     file is absent (a pre-write project with no registry is a normal state,
+ *     NOT an error).
+ *   - `writeRegistry` delegates whole-file writes to block-api's atomic
+ *     `writeTypedFile` (tmp + rename + schema-validate), so a failed write
+ *     leaves the prior file byte-identical and a malformed registry never lands.
+ *   - `registerSubstrate` wraps a load-or-empty → JSON deep-clone → upsert →
+ *     write pattern (idempotent: re-registering the same substrate_id with the
+ *     same dir is a no-op rewrite; a changed dir/aliases overwrites the entry).
+ *
+ * A small per-cwd cache (keyed by absolute cwd, invalidated on mtime change and
+ * proactively on write) mirrors the migrations-store cache so read-after-write
+ * within a process is consistent without restart.
+ */
+import type { DispatchContext } from "./dispatch-context.js";
+/**
+ * Project-root path of the substrate registry. PROJECT-ROOT, not substrate-dir-
+ * relative (contrast `migrationsPath`, which resolves through the active
+ * substrate dir). The registry enumerates substrates above any single
+ * substrate, so it must live at a fixed root location independent of which
+ * substrate the bootstrap pointer currently names.
+ */
+export declare function contextRegistryPath(cwd: string): string;
+/**
+ * One registry entry — the directory + alias list for a substrate_id. Mirrors
+ * the `RegistryEntry` definition in context-registry.schema.json one-for-one.
+ * `dir` is resolved against the project root (`path.resolve(cwd, dir)`) when
+ * matched against the active substrate by the drift invariant.
+ */
+export interface RegistryEntry {
+    dir: string;
+    aliases: string[];
+}
+/**
+ * On-disk registry shape. `substrates` is keyed by substrate_id
+ * (`^sub-[0-9a-f]{16}$`, enforced by the schema's `propertyNames`).
+ */
+export interface RegistryFile {
+    version: string;
+    substrates: Record<string, RegistryEntry>;
+}
+/**
+ * Current `version` emitted into newly-created `.pi-context-registry.json`
+ * files. Tracks the `version` field of context-registry.schema.json itself.
+ */
+export declare const REGISTRY_FILE_VERSION = "1.0.0";
+/**
+ * Drop the cached registry for `cwd` so the next `loadRegistry(cwd)` re-reads
+ * from disk. Called internally by `writeRegistry`; exported for callers that
+ * mutate the file out-of-band (e.g. tests / the orchestrator seed).
+ */
+export declare function invalidateRegistry(cwd: string): void;
+/**
+ * Load + AJV-validate the project-root registry. Returns null when the file is
+ * absent (a project with no registry yet — a normal pre-write condition, NOT an
+ * error). Throws on read / parse / schema failure. Caches by absolute cwd keyed
+ * on file mtime.
+ */
+export declare function loadRegistry(cwd: string): RegistryFile | null;
+/**
+ * Atomic, AJV-validated whole-file write of `.pi-context-registry.json`.
+ * Delegates to block-api's `writeTypedFile` against the bundled registry schema
+ * (tmp + rename; a failed write leaves the prior file byte-identical). `ctx` is
+ * accepted for call-site parity with the rest of the substrate write surface;
+ * the registry schema declares no envelope author fields so stamping is a
+ * structural no-op today. Invalidates the per-cwd cache after the write so the
+ * next `loadRegistry(cwd)` reads the fresh file.
+ */
+export declare function writeRegistry(cwd: string, file: RegistryFile, ctx?: DispatchContext): void;
+/**
+ * Upsert a substrate's registry entry. Load-or-empty → clone → set
+ * `substrates[substrate_id] = { dir, aliases }` → atomic write. Idempotent:
+ * re-registering the same substrate_id with the same dir + aliases produces a
+ * byte-identical file; a changed dir (e.g. a renamed substrate directory) or a
+ * changed alias list overwrites the prior entry in place. `aliases` defaults to
+ * `[]` when omitted (Cycle 4 registers with empty aliases; the Phase-H
+ * migration populates the legacy `project:` alias).
+ *
+ * Does NOT validate that `substrate_id` matches `^sub-[0-9a-f]{16}$` here — the
+ * schema's `propertyNames` pattern enforces that at the write boundary (an
+ * out-of-shape key fails `writeTypedFile`'s AJV validation, leaving the prior
+ * file intact).
+ */
+export declare function registerSubstrate(cwd: string, substrate_id: string, dir: string, aliases?: string[], ctx?: DispatchContext): void;
+/**
+ * Resolve a substrate_id to its registered directory string (as stored — i.e.
+ * project-root-relative, the caller resolves against cwd when an absolute path
+ * is needed). Returns null on miss (substrate_id not registered, or no registry
+ * file at all) — never throws on a clean miss, mirroring the F2 resolver's
+ * expectation of a null-or-hit lookup.
+ */
+export declare function resolveSubstrateDir(cwd: string, substrate_id: string): string | null;
+/**
+ * Resolve an alias to the substrate_id that declares it. Scans every entry's
+ * `aliases[]` for an exact string match and returns the owning substrate_id.
+ * Returns null on miss (alias unregistered, or no registry file) — never throws
+ * on a clean miss. First-match wins if (by misconfiguration) two substrates
+ * claim the same alias; the registry does not enforce alias uniqueness this
+ * cycle.
+ */
+export declare function resolveAlias(cwd: string, alias: string): string | null;
+//# sourceMappingURL=context-registry.d.ts.map

package/dist/context-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-registry.d.ts","sourceRoot":"","sources":["../src/context-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAa7D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAgB7C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA2B7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,CAG1F;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAM,EAAO,EACtB,GAAG,CAAC,EAAE,eAAe,GACnB,IAAI,CAKN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKpF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOtE"}