@davidorex/pi-context 0.28.1 → 0.30.0

package/dist/ops-registry.js

@@ -18,10 +18,10 @@
  */
 import path from "node:path";
 import { Type } from "typebox";
-import { appendToBlock, appendToNestedArray, nextId, readBlock, readBlockDir, removeFromBlock, removeFromNestedArray, updateItemInBlock, updateNestedArrayItem, writeBlock, } from "./block-api.js";
+import { appendToBlock, appendToNestedArray, nextId, readBlock, readBlockDir, removeFromBlock, removeFromNestedArray, updateItemInBlock, updateNestedArrayItem, upsertItemInBlock, writeBlock, } from "./block-api.js";
 import { adoptConception, amendConfigEntry, loadConfig, loadContext } from "./context.js";
 import { BootstrapNotFoundError, schemaPath, tryResolveContextDir } from "./context-dir.js";
-import { appendRelationByRef, completeTask, contextState, currentState, deriveBootstrapState, filterBlockItems, joinBlocks, readBlockItem, readBlockPage, resolveItemById, resolveItemsByIds, validateContext, } from "./context-sdk.js";
+import { appendRelationByRef, appendRelationsByRef, completeTask, contextState, currentState, deriveBootstrapState, filterBlockItems, joinBlocks, readBlockItem, readBlockPage, removeRelationByRef, replaceRelationByRef, resolveItemById, resolveItemsByIds, validateContext, } from "./context-sdk.js";
 import { gatherExecutionContext } from "./execution-context.js";
 // initProject + the switch/list/archive helpers are defined in index.ts (shared
 // with the /context command handlers + the context-* tools). This is a cyclic
@@ -32,12 +32,89 @@ import { gatherExecutionContext } from "./execution-context.js";
 import { archiveSubstrate, initProject, listSubstrates, switchAndCreate, switchToExisting, switchToPrevious, } from "./index.js";
 import { edgesForLensByName, findReferencesInRepo, validateContextRelations, walkAncestorsByLens, walkLensDescendants, } from "./lens-view.js";
 import { promoteItem } from "./promote-item.js";
-import { addressInto, serializeForRead } from "./read-element.js";
+import { addressInto, renderReadText, structureForRead } from "./read-element.js";
 import { renameCanonicalId } from "./rename-canonical-id.js";
 import { listRoadmaps, loadRoadmap, renderRoadmap, validateRoadmaps } from "./roadmap-plan.js";
 import { samplesCatalog } from "./samples-catalog.js";
 import { readSchema, writeSchemaChecked } from "./schema-write.js";
+import { truncateHead } from "./truncate.js";
 import { writeSchemaMigrationExecute } from "./write-schema-migration-tool.js";
+/**
+ * Collapse an {@link OpResult} to the text the default CLI surface + the in-pi
+ * Pi-tool surface emit. This reproduces, byte-for-byte, what each op's `run`
+ * returned before the TASK-012 split: prose → itself; `{json}` →
+ * `JSON.stringify(x, null, 2)`; `{read}` → `renderReadText` (== the old
+ * `serializeForRead().content`).
+ */
+/**
+ * The unbypassable output-boundary cap (TASK-013 / FGAP-015). The 50KB read cap
+ * (`DEFAULT_MAX_BYTES` + `truncateHead`) previously lived ONLY in the `{read}`
+ * channel (structureForRead / renderReadText); the prose `string` and `{json}`
+ * channels emitted unbounded. A `{json}` op embedding substrate content (e.g.
+ * resolve-item-by-id, promote-item) therefore leaked that content uncapped on
+ * BOTH surfaces — the CLI `--json` `output` and the shared text renderer used by
+ * the default CLI surface AND the in-pi Pi-tool surface. These two helpers move
+ * the cap to the emission boundary so it fires for EVERY channel regardless of
+ * which op shape produced the value.
+ *
+ * `{read}` is already fail-closed at structureForRead (over-cap → data null +
+ * tiny metadata / refusal text), so both helpers pass it through untouched — it
+ * is never double-handled here.
+ */
+/** True when `s` exceeds the 50KB read cap (shared byte-count/threshold logic). */
+function overReadCap(s) {
+    const totalBytes = Buffer.byteLength(s, "utf-8");
+    return { over: truncateHead(s).truncated, totalBytes };
+}
+/**
+ * REFUSAL prose for an over-cap `{json}` or prose `string` result — no narrowing
+ * tool/addressing is available at this boundary (unlike `{read}`'s
+ * overCapDirective), so this mirrors renderReadText's REFUSAL wording without a
+ * tool name and returns NO payload body.
+ */
+function overCapRefusalText(totalBytes) {
+    return (`⚠️ OUTPUT REFUSED — this result is ${totalBytes} bytes, over the 50KB read cap. ` +
+        `Nothing was returned (a partial read would mislead). Narrow your read.`);
+}
+/**
+ * Collapse an {@link OpResult} to the text the default CLI surface + the in-pi
+ * Pi-tool surface emit, NOW BOUNDED at the 50KB read cap (TASK-013 / FGAP-015).
+ * `{read}` → renderReadText (already capped); prose `string` → itself when under
+ * cap, else the REFUSAL prose; `{json}` → `JSON.stringify(x, null, 2)` when under
+ * cap, else the REFUSAL prose (no partial body).
+ */
+export function renderOpResultText(r) {
+    if (typeof r === "string") {
+        const { over, totalBytes } = overReadCap(r);
+        return over ? overCapRefusalText(totalBytes) : r;
+    }
+    if ("read" in r)
+        return renderReadText(r.read);
+    const s = JSON.stringify(r.json, null, 2);
+    const { over, totalBytes } = overReadCap(s);
+    return over ? overCapRefusalText(totalBytes) : s;
+}
+/**
+ * The JSON VALUE for the CLI `--json` envelope `output` field, NOW BOUNDED at the
+ * 50KB read cap (TASK-013 / FGAP-015). Prose `string` → itself when under cap,
+ * else the REFUSAL string; `{read}` → its ReadStructured (already fail-closed —
+ * serializes tiny on over-cap); `{json}` → the raw value when under cap, else a
+ * fail-closed envelope that MIRRORS {@link ReadStructured}'s over-cap shape
+ * (`{ data: null, truncated: true, totalBytes, complete: false }`) so `--json`
+ * consumers see one uniform fail-closed envelope across `{read}` and bounded
+ * `{json}`. No partial payload is ever emitted past the cap.
+ */
+export function boundedJsonOutput(r) {
+    if (typeof r === "string") {
+        const { over, totalBytes } = overReadCap(r);
+        return over ? overCapRefusalText(totalBytes) : r;
+    }
+    if ("read" in r)
+        return r.read;
+    const s = JSON.stringify(r.json, null, 2);
+    const { over, totalBytes } = overReadCap(s);
+    return over ? { data: null, truncated: true, totalBytes, complete: false } : r.json;
+}
 // ── serializeRoadmapView ────────────────────────────────────────────────────
 // Strip non-serializable fields (suggestionTemplate fn, grouped Map) from the
 // embedded LoadedLensView records before tool serialization. Relocated verbatim
@@ -78,7 +155,7 @@ export const ops = [
             })),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             // Type.Unknown() params may arrive as JSON strings — parse if needed
             if (typeof params.item === "string") {
                 try {
@@ -96,7 +173,7 @@ export const ops = [
             // withBlockLock critical section (block-api assertAppendIdUnique) —
             // the single enforcement point. The prior racy readBlock-then-append
             // tool-layer check was removed in favour of that library guard.
-            appendToBlock(cwd, params.block, params.arrayKey, params.item);
+            appendToBlock(cwd, params.block, params.arrayKey, params.item, ctx);
             const id = params.item?.id ? ` '${params.item.id}'` : "";
             return `Appended item${id} to ${params.block}.${params.arrayKey}`;
         },
@@ -115,12 +192,12 @@ export const ops = [
             }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             if (Object.keys(params.updates).length === 0) {
                 throw new Error("No fields to update — updates parameter is empty");
             }
             const matchEntries = Object.entries(params.match);
-            updateItemInBlock(cwd, params.block, params.arrayKey, (item) => matchEntries.every(([k, v]) => item[k] === v), params.updates);
+            updateItemInBlock(cwd, params.block, params.arrayKey, (item) => matchEntries.every(([k, v]) => item[k] === v), params.updates, ctx);
             const matchDesc = matchEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             return `Updated item (${matchDesc}) in ${params.block}.${params.arrayKey}: ${Object.keys(params.updates).join(", ")}`;
         },
@@ -140,25 +217,202 @@ export const ops = [
                 description: "Registered relation_type canonical_id / hierarchy edge type / lens id",
             }),
             ordinal: Type.Optional(Type.Integer({ description: "Optional sibling-ordering within (parent, relation_type)" })),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             // Cycle-5 porcelain: STRING selectors (bare refname / <alias>:<refname> /
             // lens-bin) are resolved to structured EdgeEndpoints and written via the
             // raw plumbing. The param surface stays string-typed; messaging uses the
-            // raw selectors (params.*), not the resolved structured endpoints.
+            // raw selectors (params.*), not the resolved structured endpoints. Under
+            // dryRun the byRef fn validates the prospective relations + dedup-checks
+            // without writing (TASK-010 shared preview path).
             const { appended } = appendRelationByRef(cwd, {
                 parent: params.parent,
                 child: params.child,
                 relation_type: params.relation_type,
                 ...(params.ordinal !== undefined ? { ordinal: params.ordinal } : {}),
-            });
+            }, ctx, { dryRun: params.dryRun });
             const ordinalNote = params.ordinal !== undefined ? ` (ordinal ${params.ordinal})` : "";
+            if (params.dryRun) {
+                return appended
+                    ? `would append relation ${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`
+                    : `would no-op (duplicate): relation ${params.parent} -[${params.relation_type}]-> ${params.child}`;
+            }
             return appended
                 ? `Appended relation ${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`
                 : `Relation ${params.parent} -[${params.relation_type}]-> ${params.child} already exists — no-op`;
         },
     },
+    {
+        name: "remove-relation",
+        label: "Remove Relation",
+        description: "Remove the single closure-table relation (edge) matching parent+child+relation_type from relations.json. " +
+            "Matches on the SAME (parent, child, relation_type) dedup identity append-relation uses, so it is the symmetric " +
+            "inverse of append-relation (ordinal is NOT part of identity). An absent edge is an idempotent no-op. " +
+            "Reference integrity is NOT checked here — run context-validate after if the removal changes resolvability.",
+        promptSnippet: "Remove a relation/edge between two items (the inverse of append-relation)",
+        parameters: Type.Object({
+            parent: Type.String({ description: "Canonical id (or lens bin name) of the parent endpoint" }),
+            child: Type.String({ description: "Canonical id of the child endpoint" }),
+            relation_type: Type.String({
+                description: "Registered relation_type canonical_id / hierarchy edge type / lens id",
+            }),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
+        }),
+        surface: "use",
+        run(cwd, params, ctx) {
+            // Cycle-5 porcelain: STRING selectors are resolved to structured
+            // EdgeEndpoints, then matched on the identityKey dedup identity. Messaging
+            // uses the raw selectors (params.*), not the resolved structured endpoints.
+            // Under dryRun the byRef fn validates the prospective post-removal
+            // relations + match-checks without writing (TASK-010 shared preview path).
+            const { removed } = removeRelationByRef(cwd, { parent: params.parent, child: params.child, relation_type: params.relation_type }, ctx, { dryRun: params.dryRun });
+            if (params.dryRun) {
+                return removed
+                    ? `would remove relation ${params.parent} -[${params.relation_type}]-> ${params.child}`
+                    : `would no-op (no matching relation): ${params.parent} -[${params.relation_type}]-> ${params.child}`;
+            }
+            return removed
+                ? `Removed relation ${params.parent} -[${params.relation_type}]-> ${params.child}`
+                : `Relation ${params.parent} -[${params.relation_type}]-> ${params.child} — no matching relation — no-op`;
+        },
+    },
+    {
+        name: "replace-relation",
+        label: "Replace Relation",
+        description: "Atomically replace one closure-table relation with another in a SINGLE write (no half-state: the old edge and " +
+            "the new edge never coexist on disk). The old edge is matched on the (parent, child, relation_type) dedup identity; " +
+            "the new edge is written with its optional ordinal. If the old edge is absent the call is effectively an append of " +
+            "the new edge. Reference integrity is NOT checked here — run context-validate after.",
+        promptSnippet: "Atomically swap one relation/edge for another in a single write",
+        parameters: Type.Object({
+            old_parent: Type.String({ description: "Parent endpoint selector of the edge to remove" }),
+            old_child: Type.String({ description: "Child endpoint selector of the edge to remove" }),
+            old_relation_type: Type.String({ description: "relation_type of the edge to remove" }),
+            parent: Type.String({ description: "Parent endpoint selector of the replacement edge" }),
+            child: Type.String({ description: "Child endpoint selector of the replacement edge" }),
+            relation_type: Type.String({ description: "relation_type of the replacement edge" }),
+            ordinal: Type.Optional(Type.Integer({ description: "Optional sibling-ordering within (parent, relation_type) for the new edge" })),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
+        }),
+        surface: "use",
+        run(cwd, params, ctx) {
+            // Under dryRun the byRef fn validates the prospective post-replace
+            // relations and computes the same removed/replaced would-decisions
+            // without writing (TASK-010 shared preview path).
+            const { replaced, removed } = replaceRelationByRef(cwd, {
+                old: { parent: params.old_parent, child: params.old_child, relation_type: params.old_relation_type },
+                new: {
+                    parent: params.parent,
+                    child: params.child,
+                    relation_type: params.relation_type,
+                    ...(params.ordinal !== undefined ? { ordinal: params.ordinal } : {}),
+                },
+            }, ctx, { dryRun: params.dryRun });
+            const ordinalNote = params.ordinal !== undefined ? ` (ordinal ${params.ordinal})` : "";
+            const oldDesc = `${params.old_parent} -[${params.old_relation_type}]-> ${params.old_child}`;
+            const newDesc = `${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`;
+            if (params.dryRun) {
+                if (!removed && !replaced) {
+                    return `would no-op — old edge ${oldDesc} absent and new edge ${newDesc} already present`;
+                }
+                if (!removed) {
+                    return `would append new relation ${newDesc} (old ${oldDesc} absent)`;
+                }
+                if (!replaced) {
+                    return `would remove relation ${oldDesc}; new relation ${newDesc} already present (no duplicate written)`;
+                }
+                return `would replace relation ${oldDesc} with ${newDesc}`;
+            }
+            if (!removed && !replaced) {
+                return `Replace relation no-op — old edge ${oldDesc} absent and new edge ${newDesc} already present`;
+            }
+            if (!removed) {
+                return `Old relation ${oldDesc} absent — appended new relation ${newDesc}`;
+            }
+            if (!replaced) {
+                return `Removed relation ${oldDesc}; new relation ${newDesc} already present (no duplicate written)`;
+            }
+            return `Replaced relation ${oldDesc} with ${newDesc}`;
+        },
+    },
+    {
+        name: "append-relations",
+        label: "Append Relations (bulk)",
+        description: "Append MANY closure-table relations to relations.json in a single write. Each edge is an object " +
+            "{ parent, child, relation_type, ordinal? }. Per-(parent, child, relation_type) duplicates are skipped (against " +
+            "on-disk edges AND earlier edges in the same batch). Returns appended/skipped counts. Reference integrity is NOT " +
+            "checked here — run context-validate after. Creates relations.json if absent.",
+        promptSnippet: "Create many relations/edges between items in one write",
+        parameters: Type.Object({
+            edges: Type.Unknown({
+                description: "JSON array of { parent, child, relation_type, ordinal? } selector objects (parent/child are id/lens-bin selectors)",
+            }),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
+        }),
+        surface: "use",
+        run(cwd, params, ctx) {
+            // Type.Unknown() params may arrive as JSON strings — parse if needed.
+            let edges = params.edges;
+            if (typeof edges === "string") {
+                try {
+                    edges = JSON.parse(edges);
+                }
+                catch {
+                    throw new Error(`edges parameter must be a JSON array, got unparseable string`);
+                }
+            }
+            if (!Array.isArray(edges)) {
+                throw new Error(`edges parameter must be a JSON array of { parent, child, relation_type, ordinal? } objects`);
+            }
+            // Under dryRun the byRef fn replays the on-disk + in-batch dedup and
+            // validates the prospective relations without writing (TASK-010 shared
+            // preview path).
+            const { appended, skipped } = appendRelationsByRef(cwd, edges, ctx, { dryRun: params.dryRun });
+            return params.dryRun
+                ? `would append ${appended}, skip ${skipped} (duplicates)`
+                : `appended ${appended}, skipped ${skipped} (duplicates)`;
+        },
+    },
+    {
+        name: "upsert-block-item",
+        label: "Upsert Block Item",
+        description: "Append-or-replace an item in a project block array by id: if an item with the same idField value exists it is " +
+            "REPLACED (full-shape replacement, not shallow-merge — use update-block-item for merge); otherwise the item is " +
+            "appended. Schema validation is automatic. idField defaults to 'id'.",
+        promptSnippet: "Append-or-replace a full block item by id (replacement, not merge)",
+        parameters: Type.Object({
+            block: Type.String({ description: "Block name (e.g., 'issues', 'decisions')" }),
+            arrayKey: Type.String({ description: "Array key in the block (e.g., 'issues', 'decisions')" }),
+            item: Type.Unknown({ description: "Full item object to upsert — must conform to block schema" }),
+            idField: Type.Optional(Type.String({ description: "Field used as the upsert key (default 'id')" })),
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview the upsert without writing" })),
+        }),
+        surface: "use",
+        run(cwd, params, ctx) {
+            // Type.Unknown() params may arrive as JSON strings — parse if needed.
+            if (typeof params.item === "string") {
+                try {
+                    params.item = JSON.parse(params.item);
+                }
+                catch {
+                    throw new Error(`item parameter must be a JSON object, got unparseable string`);
+                }
+            }
+            const idField = params.idField ?? "id";
+            // Under dryRun upsertItemInBlock computes mode + builds + validates the prospective
+            // whole block, writing nothing (TASK-011 shared preview path).
+            const { mode } = upsertItemInBlock(cwd, params.block, params.arrayKey, params.item, idField, ctx, {
+                dryRun: params.dryRun,
+            });
+            const idVal = params.item?.[idField];
+            const idDesc = idVal !== undefined ? ` '${idVal}'` : "";
+            return params.dryRun
+                ? `would upsert item${idDesc} (${mode}) in ${params.block}.${params.arrayKey}`
+                : `Upserted item${idDesc} (${mode}) to ${params.block}.${params.arrayKey}`;
+        },
+    },
     {
         name: "promote-item",
         label: "Promote Item",
@@ -180,17 +434,26 @@ export const ops = [
             }, { description: "DispatchContext.writer per pi-context/src/dispatch-context.ts." }),
         }),
         surface: "use",
-        run(cwd, params) {
-            if (!params.writer?.user) {
-                throw new Error("promote-item: writer.user is required.");
+        run(cwd, params, ctx) {
+            // The DispatchContext now arrives via the op contract — registerAll
+            // (in-pi) builds it from the auth-gate-stamped `params.writer`, and the
+            // CLI builds it from its resolved identity. The schema `writer` field is
+            // retained (the in-pi auth-gate stamps it), but lineage attestation reads
+            // the contract ctx, not params.writer.
+            if (!ctx?.writer) {
+                throw new Error("promote-item: a DispatchContext writer is required.");
             }
             const result = promoteItem(cwd, {
                 source: params.source,
                 destinationSubstrate: params.destinationSubstrate,
                 ...(params.newRefname !== undefined ? { newRefname: params.newRefname } : {}),
                 ...(params.dryRun !== undefined ? { dryRun: params.dryRun } : {}),
-            }, { writer: { kind: "human", user: params.writer.user } });
-            return JSON.stringify(result, null, 2);
+            }, ctx);
+            // TASK-013 / FGAP-015: route through {read} so the embedded
+            // ResolvedRef.loc.item is bounded at the 50KB cap; over-cap fails closed
+            // with metadata. Under-cap text stays the same JSON (renderReadText
+            // under-cap returns JSON.stringify(serialized, null, 2) with no footer).
+            return { read: structureForRead(result, { whole: true, label: "promote-item result" }) };
         },
     },
     {
@@ -208,7 +471,7 @@ export const ops = [
             item: Type.Unknown({ description: "Item object to append to the nested array — must conform to schema" }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             if (typeof params.item === "string") {
                 try {
                     params.item = JSON.parse(params.item);
@@ -219,7 +482,7 @@ export const ops = [
             }
             const matchEntries = Object.entries(params.match);
             const predicate = (i) => matchEntries.every(([k, v]) => i[k] === v);
-            appendToNestedArray(cwd, params.block, params.arrayKey, predicate, params.nestedKey, params.item);
+            appendToNestedArray(cwd, params.block, params.arrayKey, predicate, params.nestedKey, params.item, ctx);
             const matchDesc = matchEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             const id = params.item?.id ? ` '${params.item.id}'` : "";
             return `Appended item${id} to ${params.block}.${params.arrayKey}[${matchDesc}].${params.nestedKey}`;
@@ -245,7 +508,7 @@ export const ops = [
             }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             if (Object.keys(params.updates).length === 0) {
                 throw new Error("No fields to update — updates parameter is empty");
             }
@@ -253,7 +516,7 @@ export const ops = [
             const nestedEntries = Object.entries(params.nestedMatch);
             const parentPred = (i) => parentEntries.every(([k, v]) => i[k] === v);
             const nestedPred = (i) => nestedEntries.every(([k, v]) => i[k] === v);
-            updateNestedArrayItem(cwd, params.block, params.arrayKey, parentPred, params.nestedKey, nestedPred, params.updates);
+            updateNestedArrayItem(cwd, params.block, params.arrayKey, parentPred, params.nestedKey, nestedPred, params.updates, ctx);
             const parentDesc = parentEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             const nestedDesc = nestedEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             return `Updated nested item (${nestedDesc}) in ${params.block}.${params.arrayKey}[${parentDesc}].${params.nestedKey}: ${Object.keys(params.updates).join(", ")}`;
@@ -270,10 +533,10 @@ export const ops = [
             match: Type.Record(Type.String(), Type.Unknown(), { description: "Fields to match (e.g., { id: 'ISSUE-NNN' })" }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             const matchEntries = Object.entries(params.match);
             const predicate = (i) => matchEntries.every(([k, v]) => i[k] === v);
-            const result = removeFromBlock(cwd, params.block, params.arrayKey, predicate);
+            const result = removeFromBlock(cwd, params.block, params.arrayKey, predicate, ctx);
             const matchDesc = matchEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             return `Removed ${result.removed} item(s) matching (${matchDesc}) from ${params.block}.${params.arrayKey}`;
         },
@@ -295,12 +558,12 @@ export const ops = [
             }),
         }),
         surface: "use",
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             const parentEntries = Object.entries(params.match);
             const nestedEntries = Object.entries(params.nestedMatch);
             const parentPred = (i) => parentEntries.every(([k, v]) => i[k] === v);
             const nestedPred = (i) => nestedEntries.every(([k, v]) => i[k] === v);
-            const result = removeFromNestedArray(cwd, params.block, params.arrayKey, parentPred, params.nestedKey, nestedPred);
+            const result = removeFromNestedArray(cwd, params.block, params.arrayKey, parentPred, params.nestedKey, nestedPred, ctx);
             const parentDesc = parentEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             const nestedDesc = nestedEntries.map(([k, v]) => `${k}=${v}`).join(", ");
             return `Removed ${result.removed} nested item(s) matching (${nestedDesc}) from ${params.block}.${params.arrayKey}[${parentDesc}].${params.nestedKey}`;
@@ -317,8 +580,8 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = readBlockDir(cwd, params.subdir);
-            const envelope = serializeForRead(result, { label: `<substrate-dir>/${params.subdir}/` });
-            return envelope.content;
+            const read = structureForRead(result, { label: `<substrate-dir>/${params.subdir}/` });
+            return { read };
         },
     },
     {
@@ -332,7 +595,7 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = readBlock(cwd, params.block);
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: `<substrate-dir>/${params.block}.json`,
                 overCapDirective: {
                     tool: "read-block-page",
@@ -340,7 +603,7 @@ export const ops = [
                     hint: "or read-block-item with id=<id>",
                 },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -354,9 +617,9 @@ export const ops = [
         }),
         surface: "use",
         authGated: true,
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             const data = typeof params.data === "string" ? JSON.parse(params.data) : params.data;
-            writeBlock(cwd, params.block, data);
+            writeBlock(cwd, params.block, data, ctx);
             return `Wrote block '${params.block}' successfully`;
         },
     },
@@ -369,7 +632,7 @@ export const ops = [
         surface: "use",
         run(cwd, _params) {
             const result = contextState(cwd);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
@@ -381,7 +644,7 @@ export const ops = [
         surface: "use",
         run(cwd, _params) {
             const result = validateContext(cwd);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
@@ -410,10 +673,10 @@ export const ops = [
                     if (!entry.found) {
                         return `read-config: entry not found in ${params.registry} — ${entry.resolved}`;
                     }
-                    const envEntry = serializeForRead(entry.value, { label: `config.${params.registry}.${params.id}` });
-                    return envEntry.content;
+                    const read = structureForRead(entry.value, { label: `config.${params.registry}.${params.id}` });
+                    return { read };
                 }
-                const envReg = serializeForRead(reg.value, {
+                const read = structureForRead(reg.value, {
                     label: `config.${params.registry}`,
                     overCapDirective: {
                         tool: "read-config",
@@ -421,17 +684,17 @@ export const ops = [
                         hint: "add id=<entry canonical_id>",
                     },
                 });
-                return envReg.content;
+                return { read };
             }
             const result = { config, configPath };
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: configPath ?? "config.json",
                 overCapDirective: {
                     tool: "read-config",
                     hint: "registry=<name> (block_kinds|relation_types|lenses|invariants|…)",
                 },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -467,8 +730,8 @@ export const ops = [
                 if (tool === undefined) {
                     return `list-tools: tool not found — name=${params.name}`;
                 }
-                const envOne = serializeForRead(tool, { label: `tool ${params.name}` });
-                return envOne.content;
+                const read = structureForRead(tool, { label: `tool ${params.name}` });
+                return { read };
             }
             // Default: compact index (FGAP-101) — name + param count + one-line description.
             const index = all.map((t) => {
@@ -482,11 +745,11 @@ export const ops = [
             // The compact index is one line per tool — small enough to serialize whole
             // (no paging); keep the wrapper fields (active/total) on the result object.
             const result = { tools: index, active, total: all.length, activeCount: active.length };
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: "tool index — pass name= for detail",
                 overCapDirective: { tool: "list-tools", hint: "name=<tool>" },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -502,13 +765,13 @@ export const ops = [
             // Package-intrinsic: the catalog reads the extension's bundled samples
             // directory, not the project substrate — cwd is unused.
             const catalog = samplesCatalog(params.kind ? { kind: params.kind } : undefined);
-            const envelope = serializeForRead(catalog, {
+            const read = structureForRead(catalog, {
                 label: params.kind ? `samples kind=${params.kind}` : "samples catalog",
                 // Whole catalog → narrow by kind; a single kind has no finer
                 // addressing (edge → head-leading marker, no directive).
                 ...(params.kind ? {} : { overCapDirective: { tool: "read-samples-catalog", hint: "kind=<canonical_id>" } }),
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -520,19 +783,19 @@ export const ops = [
         surface: "use",
         run(cwd, _params) {
             const state = currentState(cwd);
-            return JSON.stringify(state, null, 2);
+            return { json: state };
         },
     },
     {
         name: "context-bootstrap-state",
         label: "Context Bootstrap State",
-        description: "Derive the substrate bootstrap state for the cwd, purely from the filesystem: 'no-pointer' | 'no-config' | 'not-installed' | 'ready', plus the resolved contextDir and any declared-but-unmaterialized installed assets. Unlike every other tool, this NEVER throws on an un-bootstrapped substrate — it returns 'no-pointer' so you can detect a fresh substrate and tell the user to run /context init <substrate-dir> → /context accept-all → /context install (bootstrap requires user authorization via interactive confirmation). No writes.",
-        promptSnippet: "Derive substrate bootstrap state — no-pointer | no-config | not-installed | ready (never throws pre-bootstrap)",
+        description: "Derive the substrate bootstrap state for the cwd, purely from the filesystem: 'no-pointer' | 'no-config' | 'skeleton' | 'not-installed' | 'ready', plus the resolved contextDir and any declared-but-unmaterialized installed assets. Bootstrap (/context init or /context switch -c <new-dir>) now writes a minimal schema-valid config empty of vocabulary, so a freshly-bootstrapped substrate lands at 'skeleton' — onward via /context accept-all (adopt the packaged catalog, then /context install) OR amend-config / edit (build a custom vocabulary). Unlike every other tool, this NEVER throws on an un-bootstrapped substrate — it returns 'no-pointer' so you can detect a fresh substrate and tell the user to run /context init <substrate-dir> → /context accept-all → /context install (bootstrap requires user authorization via interactive confirmation). No writes.",
+        promptSnippet: "Derive substrate bootstrap state — no-pointer | no-config | skeleton | not-installed | ready (never throws pre-bootstrap)",
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
             const status = deriveBootstrapState(cwd);
-            return JSON.stringify(status, null, 2);
+            return { json: status };
         },
     },
     {
@@ -550,7 +813,7 @@ export const ops = [
         authGated: true,
         run(cwd, params) {
             const report = renameCanonicalId(cwd, params.kind, params.oldId, params.newId, { dryRun: params.dryRun });
-            return JSON.stringify(report, null, 2);
+            return { json: report };
         },
     },
     {
@@ -580,7 +843,7 @@ export const ops = [
         }),
         surface: "use",
         authGated: true,
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             // Type.Unknown() params may arrive as JSON strings. Parse if possible; on
             // failure KEEP the raw string (valid for map-value registries whose value
             // is a bare string, e.g. naming/display_strings/status_buckets).
@@ -593,10 +856,11 @@ export const ops = [
                     /* keep raw string — valid for map-value registries */
                 }
             }
-            const result = amendConfigEntry(cwd, params.registry, params.operation, params.key, entry, undefined, {
+            const result = amendConfigEntry(cwd, params.registry, params.operation, params.key, entry, ctx, {
                 dryRun: params.dryRun,
             });
-            const verb = result.modified ? (params.dryRun ? `would ${result.operation}` : `${result.operation}d`) : "no-op";
+            const pastTense = result.operation === "add" ? "added" : `${result.operation}d`;
+            const verb = result.modified ? (params.dryRun ? `would ${result.operation}` : pastTense) : "no-op";
             return `amend-config: ${verb} ${result.registry}[${result.key}]`;
         },
     },
@@ -622,11 +886,11 @@ export const ops = [
                 if (!addr.found) {
                     return `read-schema: property not found — ${addr.resolved}`;
                 }
-                const envProp = serializeForRead(addr.value, { label: `${params.schemaName} ${addr.resolved}` });
-                return envProp.content;
+                const read = structureForRead(addr.value, { label: `${params.schemaName} ${addr.resolved}` });
+                return { read };
             }
             const result = { schema, schemaPath: schemaPathStr };
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: schemaPathStr,
                 overCapDirective: {
                     tool: "read-schema",
@@ -634,7 +898,7 @@ export const ops = [
                     hint: "path=<dotted json-path>",
                 },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -656,7 +920,7 @@ export const ops = [
         }),
         surface: "use",
         authGated: true,
-        run(cwd, params) {
+        run(cwd, params, ctx) {
             // Type.Unknown() params may arrive as JSON strings. Parse if possible; on
             // failure KEEP the raw value (meta-validation rejects a non-object body).
             let schema = params.schema;
@@ -668,7 +932,7 @@ export const ops = [
                     /* keep raw string — meta-validation will reject a non-object */
                 }
             }
-            const result = writeSchemaChecked(cwd, params.schemaName, schema, params.operation, undefined, { dryRun: params.dryRun });
+            const result = writeSchemaChecked(cwd, params.schemaName, schema, params.operation, ctx, { dryRun: params.dryRun });
             const verb = result.written ? `${result.operation}d` : `would ${result.operation}`;
             return `write-schema: ${verb} schema '${params.schemaName}' at ${result.schemaPath}`;
         },
@@ -698,8 +962,8 @@ export const ops = [
         }),
         surface: "use",
         authGated: true,
-        async run(cwd, params) {
-            const result = await writeSchemaMigrationExecute(cwd, params);
+        async run(cwd, params, ctx) {
+            const result = await writeSchemaMigrationExecute(cwd, params, ctx);
             // writeSchemaMigrationExecute returns the uniform AgentToolResult; the
             // op contract is the text payload, which registerAll re-wraps identically.
             const part = result.content[0];
@@ -709,8 +973,8 @@ export const ops = [
     {
         name: "context-init",
         label: "Context Init",
-        description: "Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + install to populate).",
-        promptSnippet: "Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + install to populate)",
+        description: "Initialize the substrate dir: bootstrap pointer + dirs + a minimal schema-valid SKELETON config empty of vocabulary. Lands at the 'skeleton' bootstrap state — onward via accept-all (adopt the packaged catalog, then install) OR amend-config / edit (build a custom vocabulary).",
+        promptSnippet: "Initialize the substrate dir (bootstrap pointer + dirs + skeleton config; onward via accept-all OR amend-config/edit)",
         parameters: Type.Object({
             contextDir: Type.String({
                 description: "Substrate dir name (e.g. .context). Required — no default.",
@@ -720,13 +984,13 @@ export const ops = [
         authGated: true,
         run(cwd, params) {
             const result = initProject(cwd, params.contextDir);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
         name: "context-accept-all",
         label: "Accept-All Conception",
-        description: "Adopt the canonical packaged conception (samples/conception.json) as this substrate's config.json (accept-all). Writes config only — run install after. Idempotent: never overwrites an existing config.",
+        description: "Adopt the canonical packaged conception (samples/conception.json) as this substrate's config.json (accept-all). Writes config only — run install after. Skeleton-aware: overwrites a SKELETON config (the empty-of-vocabulary config init / switch -c writes) but never a POPULATED one.",
         promptSnippet: "Adopt the canonical conception as config (accept-all)",
         parameters: Type.Object({}),
         surface: "use",
@@ -742,7 +1006,7 @@ export const ops = [
                 }
                 throw err;
             }
-            return JSON.stringify(result);
+            return { json: result };
         },
     },
     {
@@ -755,7 +1019,7 @@ export const ops = [
                 description: "Substrate dir name to switch to (e.g. '.context'). Required for default + create_new modes; ignored for to_previous mode.",
             }),
             create_new: Type.Optional(Type.Boolean({
-                description: "When true, bootstrap target_dir as a fresh substrate AND flip the pointer in one operation (parallel to 'git switch -c <branch>'). Default false (flip to existing substrate; fails if target_dir lacks config.json).",
+                description: "When true, bootstrap target_dir as a fresh substrate (dirs + a minimal schema-valid SKELETON config empty of vocabulary — onward via accept-all OR amend/edit) AND flip the pointer in one operation (parallel to 'git switch -c <branch>'). Default false (flip to existing substrate; fails if target_dir lacks config.json).",
             })),
             to_previous: Type.Optional(Type.Boolean({
                 description: "When true, flip the pointer back to its previous_contextDir (parallel to 'git switch -'). Requires the pointer to carry a previous_contextDir (a prior switch must have populated it). When true, target_dir is ignored.",
@@ -784,14 +1048,14 @@ export const ops = [
             try {
                 if (params.to_previous === true) {
                     const { from, to } = switchToPrevious(cwd, writerIdentity);
-                    return JSON.stringify({ mode: "to_previous", from, to }, null, 2);
+                    return { json: { mode: "to_previous", from, to } };
                 }
                 if (params.create_new === true) {
                     const { created } = switchAndCreate(cwd, params.target_dir, writerIdentity);
-                    return JSON.stringify({ mode: "create_new", target_dir: params.target_dir, created }, null, 2);
+                    return { json: { mode: "create_new", target_dir: params.target_dir, created } };
                 }
                 switchToExisting(cwd, params.target_dir, writerIdentity);
-                return JSON.stringify({ mode: "existing", target_dir: params.target_dir }, null, 2);
+                return { json: { mode: "existing", target_dir: params.target_dir } };
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -808,7 +1072,7 @@ export const ops = [
         surface: "use",
         run(cwd, _params) {
             const subs = listSubstrates(cwd);
-            return JSON.stringify(subs, null, 2);
+            return { json: subs };
         },
     },
     {
@@ -820,21 +1084,13 @@ export const ops = [
             target_dir: Type.String({
                 description: "Substrate dir name to archive (e.g. '.project'). Refused if it is the active substrate.",
             }),
-            writer: Type.Optional(Type.Object({
-                kind: Type.String({
-                    description: "Writer kind discriminator — overwritten by auth-gate to 'human' on confirm.",
-                }),
-                user: Type.String({
-                    description: "Writer user — overwritten by auth-gate to the verified terminal-operator identity on confirm.",
-                }),
-            }, { description: "DispatchContext.writer — stamped by auth-gate on operator confirm." })),
         }),
         surface: "use",
         authGated: true,
         run(cwd, params) {
             try {
                 const { from, to } = archiveSubstrate(cwd, params.target_dir);
-                return JSON.stringify({ from, to }, null, 2);
+                return { json: { from, to } };
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -866,11 +1122,11 @@ export const ops = [
                 op: params.op,
                 value: params.value,
             });
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: `${params.block} filtered`,
                 overCapDirective: { tool: "read-block-page", hint: "or refine the predicate" },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -884,7 +1140,17 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = resolveItemById(cwd, params.id);
-            return JSON.stringify(result, null, 2);
+            // TASK-013 / FGAP-015: route through {read} so the embedded full
+            // ItemLocation is bounded at the 50KB cap and over-cap fails closed with
+            // a narrowing directive (mirrors read-block-item). `result` is
+            // ItemLocation | null — structureForRead handles both.
+            return {
+                read: structureForRead(result, {
+                    whole: true,
+                    label: `resolve ${params.id}`,
+                    overCapDirective: { tool: "read-block-item", hint: "narrow to one block" },
+                }),
+            };
         },
     },
     {
@@ -901,8 +1167,8 @@ export const ops = [
             const result = readBlockItem(cwd, params.block, params.id);
             // whole: the item is already the addressed element — don't re-page its
             // intrinsic arrays; preserve the single-item|null output contract.
-            const envelope = serializeForRead(result, { whole: true, label: `${params.block} ${params.id}` });
-            return envelope.content;
+            const read = structureForRead(result, { whole: true, label: `${params.block} ${params.id}` });
+            return { read };
         },
     },
     {
@@ -920,8 +1186,8 @@ export const ops = [
             const result = readBlockPage(cwd, params.block, { offset: params.offset, limit: params.limit });
             // whole: readBlockPage ALREADY paged — preserve the {items,total,hasMore}
             // output contract; do not let serializeForRead re-page the items array.
-            const envelope = serializeForRead(result, { whole: true, label: `${params.block} page` });
-            return envelope.content;
+            const read = structureForRead(result, { whole: true, label: `${params.block} page` });
+            return { read };
         },
     },
     {
@@ -956,14 +1222,14 @@ export const ops = [
                 leftEndpoint: params.leftEndpoint,
                 leftPredicate,
             });
-            const envelope = serializeForRead(result, {
+            const read = structureForRead(result, {
                 label: `${params.leftBlock} ⋈ ${params.rightBlock}`,
                 overCapDirective: {
                     tool: "join-blocks",
                     hint: "refine the relation/field or pre-filter the left block",
                 },
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -984,8 +1250,8 @@ export const ops = [
                 obj[id] = loc;
             // whole: an id→location map keyed by arbitrary ids — not a pageable
             // collection; serialize the map verbatim.
-            const envelope = serializeForRead(obj, { whole: true, label: "resolved ids" });
-            return envelope.content;
+            const read = structureForRead(obj, { whole: true, label: "resolved ids" });
+            return { read };
         },
     },
     {
@@ -1000,8 +1266,8 @@ export const ops = [
             }),
         }),
         surface: "use",
-        run(cwd, params) {
-            const result = completeTask(cwd, params.taskId, params.verificationId);
+        run(cwd, params, ctx) {
+            const result = completeTask(cwd, params.taskId, params.verificationId, ctx);
             return `Task '${result.taskId}' completed (was '${result.previousStatus}'). Verification: ${result.verificationId} (${result.verificationStatus})`;
         },
     },
@@ -1014,7 +1280,7 @@ export const ops = [
         surface: "use",
         run(cwd, _params) {
             const result = validateContextRelations(cwd);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
@@ -1028,8 +1294,8 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = edgesForLensByName(cwd, params.lensId);
-            const envelope = serializeForRead(result, { label: `edges for lens ${params.lensId}` });
-            return envelope.content;
+            const read = structureForRead(result, { label: `edges for lens ${params.lensId}` });
+            return { read };
         },
     },
     {
@@ -1044,7 +1310,7 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = walkLensDescendants(cwd, params.parentId, params.relationType);
-            return JSON.stringify(result, null, 2);
+            return { json: result };
         },
     },
     {
@@ -1059,8 +1325,8 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = walkAncestorsByLens(cwd, params.itemId, params.relationType);
-            const envelope = serializeForRead(result, { label: `ancestors of ${params.itemId}` });
-            return envelope.content;
+            const read = structureForRead(result, { label: `ancestors of ${params.itemId}` });
+            return { read };
         },
     },
     {
@@ -1077,8 +1343,8 @@ export const ops = [
         surface: "use",
         run(cwd, params) {
             const result = findReferencesInRepo(cwd, params.itemId, params.direction);
-            const envelope = serializeForRead(result, { label: `edges on ${params.itemId}` });
-            return envelope.content;
+            const read = structureForRead(result, { label: `edges on ${params.itemId}` });
+            return { read };
         },
     },
     {
@@ -1101,8 +1367,8 @@ export const ops = [
             const result = gatherExecutionContext(cwd, params);
             // whole: a structured ContextBundle (unit + perRelationType buckets) —
             // preserve the bundle shape rather than paging any single inner array.
-            const envelope = serializeForRead(result, { whole: true, label: `bundle ${params.unitId}` });
-            return envelope.content;
+            const read = structureForRead(result, { whole: true, label: `bundle ${params.unitId}` });
+            return { read };
         },
     },
     {
@@ -1117,16 +1383,16 @@ export const ops = [
         run(cwd, params) {
             const view = loadRoadmap(cwd, params.roadmapId);
             if ("error" in view) {
-                const envErr = serializeForRead(view, { whole: true, label: `roadmap ${params.roadmapId} (error)` });
-                return envErr.content;
+                const read = structureForRead(view, { whole: true, label: `roadmap ${params.roadmapId} (error)` });
+                return { read };
             }
             // whole: a structured RoadmapView (phases + lens-views + rollups) — keep
             // the view shape intact rather than paging an inner array.
-            const envelope = serializeForRead(serializeRoadmapView(view), {
+            const read = structureForRead(serializeRoadmapView(view), {
                 whole: true,
                 label: `roadmap ${params.roadmapId}`,
             });
-            return envelope.content;
+            return { read };
         },
     },
     {
@@ -1141,7 +1407,7 @@ export const ops = [
         run(cwd, params) {
             const view = loadRoadmap(cwd, params.roadmapId);
             if ("error" in view) {
-                return JSON.stringify(view, null, 2);
+                return { json: view };
             }
             const naming = loadContext(cwd).config?.naming;
             return renderRoadmap(view, naming);
@@ -1161,7 +1427,7 @@ export const ops = [
             const filtered = params.roadmapId
                 ? result.issues.filter((i) => !i.roadmap_id || i.roadmap_id === params.roadmapId)
                 : result.issues;
-            return JSON.stringify({ status: result.status, issues: filtered }, null, 2);
+            return { json: { status: result.status, issues: filtered } };
         },
     },
     {
@@ -1172,7 +1438,7 @@ export const ops = [
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
-            return JSON.stringify(listRoadmaps(cwd), null, 2);
+            return { json: listRoadmaps(cwd) };
         },
     },
 ];
@@ -1187,6 +1453,137 @@ export const ops = [
  * point; this list is the source of pi-context's contribution to it.
  */
 export const gatedTools = ops.filter((o) => o.authGated).map((o) => o.name);
+/**
+ * The FGAP-009 non-exposure allowlist: every library write function that is
+ * deliberately NOT op-backed, with the reason it is withheld. This is the
+ * closure contract γ (TASK-008) WILL consume: γ's parity test — not yet written
+ * (no executable parity test exists in β; β defines the contract, γ implements
+ * the test against it) — WILL assert that EVERY library writer is either op-backed
+ * (appears in {@link ops}, directly or transitively) OR named here, so a
+ * newly-added library writer with neither an op nor an allowlist entry will fail
+ * that test, keeping the op surface and the library write surface in lockstep.
+ *
+ * The `*ForDir` twins of op-backed writers (e.g. `appendRelationForDir`,
+ * `writeRelationsForDir`, `upsertItemInBlockForDir`, `appendToBlockForDir`, …)
+ * are NOT enumerated individually: each is the dir-targeted internal twin of a
+ * cwd-form writer that IS op-backed, and is covered by that cwd-form op (the op
+ * resolves the active substrate dir then delegates to the same shared
+ * typed-file primitive the `*ForDir` twin calls). The contract is that γ's
+ * parity test (TASK-008, not yet written) WILL treat a `*ForDir` writer as
+ * covered when its cwd-form sibling is covered.
+ */
+export const INTENTIONALLY_UNEXPOSED_WRITERS = [
+    { libraryFn: "writeConfig", safeOp: "amend-config", reason: "scoped guarded config mutation" },
+    { libraryFn: "writeSchema", safeOp: "write-schema", reason: "raw bypasses the create/replace + migration check" },
+    { libraryFn: "updateSchema", safeOp: "write-schema", reason: "no mutator-scripting surface" },
+    { libraryFn: "writeBootstrapPointer", safeOp: "context-init", reason: "raw bypasses target validation" },
+    { libraryFn: "flipBootstrapPointer", safeOp: "context-switch", reason: "raw splits the safe switch" },
+    { libraryFn: "writeRegistry", reason: "internal; registry writes flow through registerSubstrate callers" },
+    {
+        libraryFn: "registerSubstrate",
+        reason: "manual/foreign registration is the clone arc (DEC-0002); normal paths auto-register",
+    },
+    {
+        libraryFn: "rollbackBlockFiles",
+        reason: "workflow-executor transactional rollback (graduated-failure undo); internal recovery path with no operator-facing op by design",
+    },
+];
+/**
+ * The five mutually-exhaustive ways a library write function is COVERED by the
+ * FGAP-009 op-surface ↔ library-write-surface parity contract. A writer that
+ * matches NONE of these is a silent gap that γ's (TASK-008) parity test — once
+ * written — MUST fail on. Coverage is the DISJUNCTION over these classes — a
+ * writer needs ANY one, not all.
+ */
+export var CoverageClass;
+(function (CoverageClass) {
+    /** An op's `run` calls the writer directly (e.g. `append-block-item` → `appendToBlock`). */
+    CoverageClass["OpBackedDirect"] = "op-backed-direct";
+    /**
+     * An op's `run` reaches the writer TRANSITIVELY — through any helper / wrapper
+     * chain, not just a direct call. Two sub-shapes both land here:
+     *   - `*ByRef` / SDK relation porcelain: the `remove-relation` / `replace-relation`
+     *     / `append-relations` ops call `removeRelationByRef` / `replaceRelationByRef`
+     *     / `appendRelationsByRef`, which call `writeRelations`.
+     *   - init / switch → internal-helper chains: `context-init` → `initProject` →
+     *     `writeSkeletonConfig`; `context-switch` → `switchToExisting` /
+     *     `switchAndCreate` → `reconcileActiveSubstrateRegistration`. The writer is
+     *     not a `*ByRef` porcelain and is not allowlisted, but it IS reachable from an
+     *     op's `run` via a helper the op calls.
+     * Coverage condition: reachable from some op's `run` via any helper/wrapper chain.
+     */
+    CoverageClass["OpBackedTransitive"] = "op-backed-transitive";
+    /**
+     * A `*ForDir` dir-targeted twin of a covered cwd-form writer (e.g.
+     * `appendToBlockForDir` is the twin of the op-backed `appendToBlock`). Covered
+     * by its cwd-form sibling — both delegate to the same shared typed-file
+     * primitive; the cwd-form op resolves the active dir then calls it.
+     */
+    CoverageClass["ForDirTwin"] = "for-dir-twin";
+    /**
+     * On {@link INTENTIONALLY_UNEXPOSED_WRITERS}: a raw write deliberately given NO
+     * direct op (a scoped op supersedes it, or it is internal/foreign-only).
+     */
+    CoverageClass["IntentionallyUnexposed"] = "intentionally-unexposed";
+    /**
+     * A block-api internal primitive below the op layer — the `*TypedFile` read/
+     * write layer (`readTypedFile` / `writeTypedFile`), `prepareItemIdentityForWrite`,
+     * and the identity / content-hash helpers. Never op-backed by design; the ops
+     * compose over these.
+     */
+    CoverageClass["InternalPrimitive"] = "internal-primitive";
+})(CoverageClass || (CoverageClass = {}));
+/**
+ * The FGAP-009 coverage RULE, made explicit so γ (TASK-008) will import the
+ * contract rather than re-derive it. A library write function is COVERED iff it
+ * matches ANY clause below (the disjunction); a writer matching none is a silent
+ * gap that γ's parity test — when written — MUST fail on. β fixes the contract
+ * here; no executable parity test exists yet (that is γ).
+ *
+ * Why `writeConfig` is allowlisted but `writeRelations` is NOT — the distinction
+ * a strict name-parity reading mis-saw as inconsistent:
+ *   - `writeConfig` has NO direct wholesale-config op. The scoped surface is
+ *     `amend-config` (one-entry-in-one-registry add/replace/remove, AJV-validated),
+ *     which deliberately does NOT expose a raw whole-config overwrite. So
+ *     `writeConfig` is `intentionally-unexposed` (the scoped op supersedes the raw
+ *     writer; a raw wholesale overwrite is withheld by design).
+ *   - `writeRelations` IS reached — transitively — by the relation ops:
+ *     `remove-relation` / `replace-relation` / `append-relations` call
+ *     `removeRelationByRef` / `replaceRelationByRef` / `appendRelationsByRef`, each
+ *     of which calls `writeRelations`. It is therefore `op-backed-transitive`
+ *     and needs NO allowlist entry. The asymmetry is real and correct: one writer
+ *     has an op path (via a helper/wrapper chain), the other does not.
+ *
+ * The `op-backed-transitive` clause covers BOTH the `*ByRef` relation porcelain
+ * AND the init/switch → internal-helper chains: `writeSkeletonConfig` (reached
+ * via `context-init` → `initProject`) and `reconcileActiveSubstrateRegistration`
+ * (reached via `context-switch` → `switchToExisting` / `switchAndCreate`) are
+ * neither `*ByRef` porcelain nor allowlisted, yet each is reachable from an op's
+ * `run` through a helper that op calls — so each classifies cleanly as
+ * `op-backed-transitive`, not as a gap.
+ */
+export const OP_COVERAGE_RULE = [
+    {
+        coverageClass: CoverageClass.OpBackedDirect,
+        test: "an op's run() calls the writer directly",
+    },
+    {
+        coverageClass: CoverageClass.OpBackedTransitive,
+        test: "reachable from some op's run() via any helper/wrapper chain — the *ByRef / SDK relation porcelain (writeRelations via removeRelationByRef / replaceRelationByRef / appendRelationsByRef) OR an init/switch → internal-helper chain (writeSkeletonConfig via context-init → initProject; reconcileActiveSubstrateRegistration via context-switch → switchToExisting / switchAndCreate)",
+    },
+    {
+        coverageClass: CoverageClass.ForDirTwin,
+        test: "a *ForDir twin of a covered cwd-form writer (covered by its cwd-form sibling)",
+    },
+    {
+        coverageClass: CoverageClass.IntentionallyUnexposed,
+        test: "named on INTENTIONALLY_UNEXPOSED_WRITERS — a raw bypass with no direct op",
+    },
+    {
+        coverageClass: CoverageClass.InternalPrimitive,
+        test: "a block-api internal primitive below the op layer (the *TypedFile layer, prepareItemIdentityForWrite, identity / content-hash helpers)",
+    },
+];
 /**
  * The factory PI handle captured at registerAll time. The list-tools op needs
  * the introspection surface (getAllTools / getActiveTools) which lives on
@@ -1196,11 +1593,36 @@ export const gatedTools = ops.filter((o) => o.authGated).map((o) => o.name);
  * threading the handle through every signature.
  */
 let boundPi = null;
+/**
+ * Build the DispatchContext threaded into an op's `run` from the in-pi tool
+ * execute boundary (registerAll). Two derivation branches:
+ *
+ *   - When `params.writer.user` is a non-empty string — the shape the
+ *     pi-agent-dispatch auth-gate stamps onto authGated op params on operator
+ *     confirm — the writer is a human identity. (The smuggle-ops promote-item /
+ *     write-schema-migration / context-switch carry a `writer` schema field
+ *     precisely so the gate has somewhere to stamp; this converts that field
+ *     into the contract ctx the op now consumes via its 3rd `run` arg.)
+ *   - Otherwise the writer is the running agent, identified by the active
+ *     model's id (`ExtensionContext.model.id`); falls back to "pi-agent" when
+ *     no model (or no id) is resolvable.
+ *
+ * Exported for unit testing — the two branches are asserted directly against
+ * synthetic params + a minimal ExtensionContext-shaped object.
+ */
+export function buildDispatchContextFromExecute(params, extCtx) {
+    const writerUser = params?.writer?.user;
+    if (typeof writerUser === "string" && writerUser.length > 0) {
+        return { writer: { kind: "human", user: writerUser } };
+    }
+    const modelId = extCtx.model?.id;
+    return { writer: { kind: "agent", agent_id: modelId && modelId.length > 0 ? modelId : "pi-agent" } };
+}
 /**
  * Register every op in `ops` as a pi tool. Each tool's execute body is the
- * uniform wrapper around the op's run(): coerce params, await run, place the
- * returned string at content[0].text. Behavior-identical to the prior inline
- * registrations.
+ * uniform wrapper around the op's run(): coerce params, build the attestation
+ * DispatchContext from the auth-gate-stamped writer (human) or the running
+ * model (agent), await run, place the returned string at content[0].text.
  */
 export function registerAll(pi) {
     boundPi = pi;
@@ -1212,9 +1634,10 @@ export function registerAll(pi) {
             promptSnippet: op.promptSnippet,
             parameters: op.parameters,
             async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+                const dctx = buildDispatchContextFromExecute(params, ctx);
                 return {
                     details: undefined,
-                    content: [{ type: "text", text: await op.run(ctx.cwd, params) }],
+                    content: [{ type: "text", text: renderOpResultText(await op.run(ctx.cwd, params, dctx)) }],
                 };
             },
         });