@davidorex/pi-context 0.32.0 → 0.33.0

package/dist/ops-registry.js

@@ -16,12 +16,13 @@
  * phase (the auth-gate at the pi-agent-dispatch layer remains the enforcement
  * point, unchanged by this relocation).
  */
+import fs from "node:fs";
 import path from "node:path";
 import { Type } from "typebox";
 import { appendToBlock, appendToNestedArray, nextId, readBlock, readBlockDir, removeFromBlock, removeFromNestedArray, updateItemInBlock, updateNestedArrayItem, upsertItemInBlock, writeBlock, } from "./block-api.js";
-import { adoptConception, amendConfigEntry, loadConfig } from "./context.js";
+import { adoptConception, amendConfigEntry, loadConfig, loadRelations } from "./context.js";
 import { BootstrapNotFoundError, schemaPath, tryResolveContextDir } from "./context-dir.js";
-import { appendRelationByRef, appendRelationsByRef, completeTask, contextState, currentState, deriveBootstrapState, endpointKey, filterBlockItems, joinBlocks, readBlockItem, readBlockPage, removeRelationByRef, replaceRelationByRef, resolveItemById, resolveItemsByIds, validateContext, } from "./context-sdk.js";
+import { appendRelationByRef, appendRelationsByRef, buildIdIndex, completeTask, contextState, currentState, deriveBootstrapState, endpointKey, evaluateConfigInvariants, filterBlockItems, joinBlocks, orientAppendInput, 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
@@ -29,7 +30,7 @@ import { gatherExecutionContext } from "./execution-context.js";
 // registerAll runs at extension-load time, after both modules' top-level
 // function bindings exist, and the helpers are only referenced inside op `run`
 // closures (lazy), never at this module's top level.
-import { archiveSubstrate, checkStatus, initProject, installContext, listSubstrates, readCatalogSchemaText, resolveBlocked, resolveConflict, switchAndCreate, switchToExisting, switchToPrevious, updateContext, validateBlockItemsAgainstCatalog, } from "./index.js";
+import { archiveSubstrate, checkStatus, convergeDerivedStatusAfterWrite, initProject, installContext, listSubstrates, readCatalogSchemaText, reconcileContext, resolveBlocked, resolveConflict, switchAndCreate, switchToExisting, switchToPrevious, updateContext, validateBlockItemsAgainstCatalog, } from "./index.js";
 import { edgesForLensByName, findReferencesInRepo, loadLensView, validateContextRelations, walkAncestorsByLens, walkLensDescendants, } from "./lens-view.js";
 import { promoteItem } from "./promote-item.js";
 import { addressInto, pageArray, renderReadText, structureForRead } from "./read-element.js";
@@ -115,14 +116,133 @@ export function boundedJsonOutput(r) {
     const { over, totalBytes } = overReadCap(s);
     return over ? { data: null, truncated: true, totalBytes, complete: false } : r.json;
 }
+/**
+ * Coerce a filing op's optional `relations` param (may arrive as a JSON string
+ * from the CLI, like Type.Unknown item payloads) and shape-check each entry
+ * before any write happens — a malformed entry must refuse the filing BEFORE
+ * the item lands, not mid-edge-loop. Enforces the direction/role mutual
+ * exclusion (exactly one per entry), mirroring the standalone porcelain's
+ * parent/child vs primary/counter pair exclusion.
+ */
+function coerceBirthRelations(raw) {
+    let value = raw;
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            throw new Error("relations parameter must be a JSON array, got unparseable string");
+        }
+    }
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("relations parameter must be a JSON array");
+    return value.map((entry, i) => {
+        const e = entry;
+        const shapeError = () => new Error(`relations[${i}] must be {relation_type: string, other: string, ordinal?: integer} plus EXACTLY ONE of direction: "as_parent"|"as_child" (raw form) or role: "primary"|"counter" (role-typed form)`);
+        if (e === null || typeof e !== "object" || typeof e.relation_type !== "string" || typeof e.other !== "string") {
+            throw shapeError();
+        }
+        const hasDirection = e.direction !== undefined;
+        const hasRole = e.role !== undefined;
+        if (hasDirection === hasRole)
+            throw shapeError(); // both or neither
+        if (hasDirection && e.direction !== "as_parent" && e.direction !== "as_child")
+            throw shapeError();
+        if (hasRole && e.role !== "primary" && e.role !== "counter")
+            throw shapeError();
+        return {
+            relation_type: e.relation_type,
+            other: e.other,
+            ...(hasDirection ? { direction: e.direction } : {}),
+            ...(hasRole ? { role: e.role } : {}),
+            ...(e.ordinal !== undefined ? { ordinal: e.ordinal } : {}),
+        };
+    });
+}
+/**
+ * Map one coerced birth entry to the {@link appendRelationByRef} input, with
+ * the new item at the entry's endpoint: the raw form fills parent/child, the
+ * role form fills primary/counter (the SAME role-typed pair the standalone
+ * append-relation flags fill), so orientAppendInput applies its mapping and
+ * guards verbatim — no orientation logic lives here.
+ */
+function birthRelationToAppendInput(itemId, rel) {
+    const ordinalPart = rel.ordinal !== undefined ? { ordinal: rel.ordinal } : {};
+    if (rel.role !== undefined) {
+        return {
+            relation_type: rel.relation_type,
+            ...(rel.role === "primary" ? { primary: itemId, counter: rel.other } : { primary: rel.other, counter: itemId }),
+            ...ordinalPart,
+        };
+    }
+    return {
+        relation_type: rel.relation_type,
+        parent: rel.direction === "as_parent" ? itemId : rel.other,
+        child: rel.direction === "as_parent" ? rel.other : itemId,
+        ...ordinalPart,
+    };
+}
+/**
+ * File a new item's birth edges through the same validated porcelain a
+ * standalone append-relation uses (registered-type + endpoint-kind gate,
+ * role-direction mapping + orientation-ambiguity guard, atomic write,
+ * exact-duplicate no-op), with the new item at each entry's endpoint. Runs
+ * AFTER the item write (its id must resolve as an endpoint) inside the same
+ * op run, so the write-time invariant gate judges item + edges as one
+ * transition atom; a throw here is byte-restored by the pipeline wrapper
+ * (all-or-nothing).
+ */
+function appendBirthRelations(cwd, itemId, relations, ctx) {
+    for (const rel of relations) {
+        appendRelationByRef(cwd, birthRelationToAppendInput(itemId, rel), ctx);
+    }
+}
+/**
+ * Preview-parity orientation check for dryRun filings: run the SAME
+ * role-mapping + ambiguity guard the live edge write applies
+ * (orientAppendInput), against the registry only — endpoint resolution stays
+ * out because the item is unwritten under a preview. A preview thereby
+ * refuses exactly the entries the live run would orientation-refuse.
+ */
+function assertBirthRelationsOrientable(cwd, itemId, relations) {
+    if (relations.length === 0)
+        return;
+    const config = loadConfig(cwd);
+    for (const rel of relations) {
+        orientAppendInput(config, birthRelationToAppendInput(itemId, rel));
+    }
+}
+/** Shared birth-relations entry schema for the filing ops (append + upsert). */
+const BIRTH_RELATION_ENTRY = Type.Object({
+    relation_type: Type.String({ description: "Registered relation_type canonical_id" }),
+    direction: Type.Optional(Type.Union([Type.Literal("as_parent"), Type.Literal("as_child")], {
+        description: "RAW orientation — which edge endpoint the NEW item occupies. Exactly one of direction/role per entry.",
+    })),
+    role: Type.Optional(Type.Union([Type.Literal("primary"), Type.Literal("counter")], {
+        description: "ROLE-TYPED orientation — the semantic role the NEW item holds, mapped to parent/child via the relation's declared role_direction (same mapping as append-relation --primary/--counter). REQUIRED for role-bearing orientation-ambiguous relation_types (same-kind or wildcard endpoints), where the raw form is rejected. Exactly one of direction/role per entry.",
+    })),
+    other: Type.String({ description: "Selector of the other endpoint (canonical id / <alias>:<refname>)" }),
+    ordinal: Type.Optional(Type.Integer({ description: "Optional sibling-ordering within (parent, relation_type)" })),
+});
 export const ops = [
     {
         name: "append-block-item",
         label: "Append Block Item",
-        description: "Append an item to an array in a project block file. Schema validation is automatic. Set autoId:true to allocate the next id from the block's id pattern when the item has no id.",
-        promptSnippet: "Append items to project blocks (issues, decisions, or any user-defined block)",
+        description: "Append an item to an array in a project block file. Schema validation is automatic. Set autoId:true to allocate " +
+            "the next id from the block's id pattern when the item has no id. Optional relations file the item's BIRTH edges " +
+            "in the same op run, after id allocation — each entry names the relation_type, the other endpoint's selector, and " +
+            "EXACTLY ONE orientation: direction (as_parent | as_child — the raw endpoint the new item occupies) or role " +
+            "(primary | counter — the semantic role the new item holds, mapped via the relation's declared role_direction; " +
+            "required for role-bearing orientation-ambiguous relation_types such as the gated-by / derived-from / supersedes " +
+            "/ depends families, where the raw form is rejected). Filing item + edges as one atom lets a new item satisfy " +
+            "error-severity birth-edge invariants (e.g. a decision must cite a forcing artifact) that would refuse the bare " +
+            "item under the write-time gate.",
+        promptSnippet: "Append items to project blocks (issues, decisions, or any user-defined block), with optional atomic birth edges",
         examples: [
             `pi-context append-block-item --block framework-gaps --arrayKey gaps --autoId true --item @/tmp/fgap.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+            `pi-context append-block-item --block decisions --arrayKey decisions --autoId true --item @/tmp/dec.json --relations '[{"relation_type":"decision_addresses_gap","direction":"as_parent","other":"FGAP-001"},{"relation_type":"decision_derived_from_item","role":"counter","other":"TASK-001"}]' --writer '{"kind":"human","user":"you@example.com"}' --json`,
         ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'issues', 'decisions')" }),
@@ -131,6 +251,9 @@ export const ops = [
             autoId: Type.Optional(Type.Boolean({
                 description: "When true and the item has no id, allocate the next id from the block's id pattern",
             })),
+            relations: Type.Optional(Type.Array(BIRTH_RELATION_ENTRY, {
+                description: "Birth edges filed atomically with the item, after id allocation, via the same validated append-relation porcelain (each entry oriented by direction OR role)",
+            })),
         }),
         surface: "use",
         run(cwd, params, ctx) {
@@ -143,17 +266,27 @@ export const ops = [
                     throw new Error(`item parameter must be a JSON object, got unparseable string`);
                 }
             }
+            const relations = coerceBirthRelations(params.relations);
             // Auto-id allocation (FGAP-084 dual-surface twin of file-block-item --auto-id)
             if (params.autoId && params.item && typeof params.item === "object" && !params.item.id) {
                 params.item.id = nextId(cwd, params.block);
             }
+            if (relations.length > 0 && (typeof params.item?.id !== "string" || params.item.id.length === 0)) {
+                throw new Error("relations requires the appended item to carry an id (supply item.id or set autoId:true) — birth edges need the new item's endpoint selector");
+            }
             // Id-uniqueness is enforced atomically inside appendToBlock's
             // 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, ctx);
+            // Birth edges AFTER the item lands (its id must resolve as an endpoint),
+            // inside the same op run so the write-time gate judges item + edges as
+            // one transition atom; a failed edge throws and the pipeline wrapper
+            // byte-restores the whole write (all-or-nothing).
+            appendBirthRelations(cwd, String(params.item.id), relations, ctx);
             const id = params.item?.id ? ` '${params.item.id}'` : "";
-            return `Appended item${id} to ${params.block}.${params.arrayKey}`;
+            const edges = relations.length > 0 ? ` with ${relations.length} birth relation(s)` : "";
+            return `Appended item${id} to ${params.block}.${params.arrayKey}${edges}`;
         },
     },
     {
@@ -401,8 +534,16 @@ export const ops = [
         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)",
+            "appended. Schema validation is automatic. idField defaults to 'id'. Optional relations file BIRTH edges in the " +
+            "same op run when the upsert resolves to an APPEND — each entry names the relation_type, the other endpoint's " +
+            "selector, and EXACTLY ONE orientation: direction (as_parent | as_child, raw) or role (primary | counter, mapped " +
+            "via the relation's declared role_direction; required for role-bearing orientation-ambiguous relation_types) — " +
+            "one atom under the write-time gate, so a new filing can satisfy error-severity birth-edge invariants. dryRun " +
+            "previews the upsert AND runs the same orientation guard over the entries (a preview refuses what the live run " +
+            "would orientation-refuse; endpoint resolution stays out — the item is unwritten). When the upsert resolves to a " +
+            "REPLACE, supplying relations refuses the write (birth edges are for new items; file edges on an existing item " +
+            "via append-relation).",
+        promptSnippet: "Append-or-replace a full block item by id (replacement, not merge), with optional atomic birth edges",
         examples: [
             `pi-context upsert-block-item --block tasks --arrayKey tasks --item @/tmp/task.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
         ],
@@ -412,6 +553,9 @@ export const ops = [
             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" })),
+            relations: Type.Optional(Type.Array(BIRTH_RELATION_ENTRY, {
+                description: "Birth edges filed atomically with an APPEND-mode upsert, each entry oriented by direction OR role (refused on replace mode — use append-relation for existing items)",
+            })),
         }),
         surface: "use",
         run(cwd, params, ctx) {
@@ -424,17 +568,36 @@ export const ops = [
                     throw new Error(`item parameter must be a JSON object, got unparseable string`);
                 }
             }
+            const relations = coerceBirthRelations(params.relations);
             const idField = params.idField ?? "id";
+            const idVal = params.item?.[idField];
+            if (relations.length > 0 && (typeof idVal !== "string" || idVal.length === 0)) {
+                throw new Error(`relations requires the upserted item to carry a string '${idField}' — birth edges need the new item's endpoint selector`);
+            }
             // 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];
+            if (relations.length > 0 && mode === "updated") {
+                // Birth edges are a NEW-item affordance. Throwing here (post-write) is
+                // safe: the pipeline wrapper byte-restores the substrate on inner-op
+                // throw, so the replacement never persists (all-or-nothing).
+                throw new Error(`relations was supplied but the upsert resolved to REPLACE for '${idVal}' — birth edges are for new items; file edges on an existing item via append-relation`);
+            }
             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}`;
+            if (params.dryRun) {
+                // Preview parity: run the SAME role-mapping + orientation-ambiguity
+                // guard the live edge write applies, against the registry only — the
+                // item is unwritten, so endpoint resolution stays out. A preview
+                // refuses exactly the entries the live run would orientation-refuse.
+                assertBirthRelationsOrientable(cwd, String(idVal), relations);
+                const edgePreview = relations.length > 0 ? `; would file ${relations.length} birth relation(s)` : "";
+                return `would upsert item${idDesc} (${mode}) in ${params.block}.${params.arrayKey}${edgePreview}`;
+            }
+            appendBirthRelations(cwd, String(idVal), relations, ctx);
+            const edges = relations.length > 0 ? ` with ${relations.length} birth relation(s)` : "";
+            return `Upserted item${idDesc} (${mode}) to ${params.block}.${params.arrayKey}${edges}`;
         },
     },
     {
@@ -871,7 +1034,7 @@ export const ops = [
     {
         name: "context-current-state",
         label: "Context Current State",
-        description: "Derive 'where are we + what's next' purely from the substrate — focus, in-flight items, ranked atomic-next actions, blocked items, and milestone rollups. Every facet derives from the config-declared `state_derivation` registry: which block kinds + status bucket count as in-flight, the focus fallback kind + bucket, the ordered cross-kind next-actions push order with per-entry ranking (a named field + ordered value list, e.g. gap priority P0..P3) or topo ordering over the blocking-relation graph, the relation_types whose edges contribute blockers (the stock set being `task_depends_on_task` dependencies + `task_gated_by_item` gates), the membership rollups (e.g. milestones over `phase_positioned_in_milestone`) with their complete/incomplete status strings, and the next-actions head-size cap. A blocked item's dependency/gate target that has not reached the complete bucket is reported in blockedBy and held out of nextActions; a target reaching its complete status releases it. A substrate whose config declares no `state_derivation` reports focus 'state-derivation not configured' with empty arrays. No writes; nothing hand-stored.",
+        description: "Derive 'where are we + what's next' purely from the substrate — focus, in-flight items, ranked atomic-next actions, blocked items, and milestone rollups. Every facet derives from the config-declared `state_derivation` registry: which block kinds + status bucket count as in-flight, the focus fallback kind + bucket, the ordered cross-kind next-actions push order with per-entry ranking (a named field + ordered value list, e.g. gap priority P0..P3) or topo ordering over the blocking-relation graph, the relation_types whose edges contribute blockers (the stock set being `task_depends_on_task` dependencies + `task_gated_by_item` gates), the membership rollups (e.g. milestones over `phase_positioned_in_milestone`) with their complete/incomplete status strings, and the next-actions head-size cap. A blocked item's dependency/gate target that is not complete is reported in blockedBy and held out of nextActions; completeness follows the target kind's truth model — a rollup-declared kind (state_derivation.rollups, e.g. milestone) completes by its DERIVED membership rollup, the same verdict the milestones facet reports, so one read never self-contradicts and a derived-status kind's stored status field is never consulted; every other kind completes by its status bucketing to complete. A substrate whose config declares no `state_derivation` reports focus 'state-derivation not configured' with empty arrays. No writes; nothing hand-stored.",
         promptSnippet: "Derive current project state from the config-declared state_derivation registry — focus, in-flight, ranked next actions, blocked, milestone rollups",
         examples: [`pi-context context-current-state --json`],
         parameters: Type.Object({}),
@@ -1193,6 +1356,24 @@ export const ops = [
             return { json: result };
         },
     },
+    {
+        name: "context-reconcile",
+        label: "Context Reconcile",
+        description: "Converge stored substrate state with its derivation (the repair half of the derived-status invariant class). For every block kind a derived-status invariant declares (paired with its state_derivation.rollups entry), computes each item's stored-vs-derived status delta using the SAME completeness helper the state derivation's gate satisfaction and context-validate use — the preview, the detector, and the repair cannot disagree. The sweep also includes declared-baseline STALENESS: every stale_conditions-bearing item whose status buckets complete and whose typed condition fired (item-status / file-changed / revision-moved) or whose citation content pin drifted transitions to stale — the same evaluateStalenessCandidates verdict context-validate flags with; flag-only anchor-drift items never transition. --dryRun returns the exact delta + transition sets a live run would apply (deltas: id, block, from stored value, to derived value, declaring invariant; stalenessTransitions: id, block, from, to stale, firing reasons), writing nothing. A live run applies exactly those sets through the standard validated write path — identity-stamped, envelope-stamped, attested to the invoking writer — and reports the applied counts; a converge-write is not authoring, the written value IS the derivation, and the stale transition applies a condition the item itself declared. Scope: derived-status deltas + declared-staleness transitions ONLY — the op never writes an authored-status kind (feature/gap/issue/task buckets are human judgment) and never touches prose; those classes are flagged for review by context-validate, not auto-repaired. Ceremony discipline: seeds the catalog config migration declarations at entry, and a live run on a substrate with no substrate_id establishes the identity first (reported under substrateIdEstablished). A converged substrate is a clean no-op both ways.",
+        promptSnippet: "Converge stored rollup-kind statuses with their derivation and apply declared complete-to-stale transitions (--dryRun previews the exact sets; live applies through the validated write path; never touches authored statuses or prose)",
+        examples: [`pi-context context-reconcile --dryRun true --json`],
+        parameters: Type.Object({
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview the exact delta set without writing anything." })),
+        }),
+        surface: "use",
+        authGated: true,
+        run(cwd, params, ctx) {
+            const result = reconcileContext(cwd, { dryRun: params.dryRun === true }, ctx);
+            if (result.error)
+                return result.error;
+            return { json: result };
+        },
+    },
     {
         name: "validate-block-items",
         label: "Validate Block Items",
@@ -1470,21 +1651,26 @@ export const ops = [
     {
         name: "complete-task",
         label: "Complete Task",
-        description: "Complete a task with verification gate — requires a passing verification entry targeting the task.",
-        promptSnippet: "Complete a task — gates on passing verification before updating status",
+        description: "Complete a task with verification gate — the closure ATOM. Requires a passing verification entry, then FILES " +
+            "the verification_verifies_item edge itself (idempotent — a pre-existing exact edge is a no-op) and flips the " +
+            "task status to completed in one op run, so the write-time invariant gate judges the joint end-state. No prior " +
+            "append-relation step is needed (a standalone edge or status write would be refused by error-severity closure " +
+            "invariants; this op IS the legal transition).",
+        promptSnippet: "Complete a task — gates on passing verification, files the verification edge itself, then flips status (one atom)",
         examples: [
             `pi-context complete-task --taskId TASK-001 --verificationId VER-001 --writer '{"kind":"human","user":"you@example.com"}' --json`,
         ],
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ID to complete" }),
             verificationId: Type.String({
-                description: "Verification entry ID (must target this task with status 'passed')",
+                description: "Verification entry ID (must have status 'passed'; the op files the linking edge itself)",
             }),
         }),
         surface: "use",
         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})`;
+            const edge = result.edgeAppended ? "edge filed" : "edge pre-existing";
+            return `Task '${result.taskId}' completed (was '${result.previousStatus}'). Verification: ${result.verificationId} (${result.verificationStatus}, ${edge})`;
         },
     },
     {
@@ -1708,6 +1894,10 @@ export const gatedTools = ops.filter((o) => o.authGated).map((o) => o.name);
  * covered when its cwd-form sibling is covered.
  */
 export const INTENTIONALLY_UNEXPOSED_WRITERS = [
+    {
+        libraryFn: "convergeDerivedStatusAfterWrite",
+        reason: "post-write convergence hook, invoked by the CONVERGE_AFTER_OPS module-init wrapper around every rollup-input-mutating op's run() — op-backed transitively at runtime, but the static classifier cannot see a wrapper-installed call; its explicit ceremony surface is context-reconcile",
+    },
     { 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" },
@@ -1853,6 +2043,187 @@ export function buildDispatchContextFromExecute(params, extCtx) {
     const modelId = extCtx.model?.id;
     return { writer: { kind: "agent", agent_id: modelId && modelId.length > 0 ? modelId : "pi-agent" } };
 }
+/**
+ * Converge-on-write (FEAT-011 criterion 2 — FGAP-116): the sanctioned mutating
+ * ops that can change a rollup INPUT (a member item's status; a membership
+ * edge; an id every edge keys on) run the derived-status convergence hook
+ * AFTER their own write lands — so every op-surface write leaves rollup-kind
+ * stored statuses equal to their derivation. The hook is config-driven
+ * opt-in (no derived-status invariant → empty set → no writes) and
+ * best-effort (its failure never fails the landed write; the invariant +
+ * context-reconcile remain the net — see convergeDerivedStatusAfterWrite).
+ * Nested-item ops are excluded: item statuses are top-level fields, so a
+ * nested write cannot change a rollup input. Wrapping happens ONCE here at
+ * module init, over the ops DATA — no per-op body edits, no dispatch-path
+ * fork; both consumers (registerAll pi tools + the reflecting CLI) execute
+ * the wrapped run.
+ */
+const CONVERGE_AFTER_OPS = new Set([
+    "append-block-item",
+    "upsert-block-item",
+    "update-block-item",
+    "remove-block-item",
+    "write-block",
+    "complete-task",
+    "append-relation",
+    "append-relations",
+    "remove-relation",
+    "replace-relation",
+    "rename-canonical-id",
+    "promote-item",
+]);
+/**
+ * Evaluate every config invariant against the substrate's current state,
+ * keyed per violation instance (`code|field`) for delta comparison. Returns
+ * null when the substrate is unreadable or declares no invariants — the gate
+ * is config-driven opt-in and NEVER breaks a write on legacy/undeclared
+ * substrates. Uses the SAME evaluateConfigInvariants path validateContext
+ * runs, so write-side and validate-side verdicts are identical (TASK-062
+ * lift pattern).
+ */
+function invariantSnapshot(cwd) {
+    try {
+        const config = loadConfig(cwd);
+        if (!config || (config.invariants ?? []).length === 0)
+            return null;
+        const index = buildIdIndex(cwd);
+        const relations = loadRelations(cwd);
+        const issues = evaluateConfigInvariants(cwd, config, index, relations);
+        return new Map(issues.map((i) => [`${i.code}|${i.field ?? ""}`, { severity: i.severity, message: i.message }]));
+    }
+    catch {
+        return null;
+    }
+}
+/** Snapshot every top-level substrate *.json for a byte-exact refusal restore. */
+function substrateJsonSnapshot(cwd) {
+    try {
+        const dir = tryResolveContextDir(cwd);
+        if (dir === null)
+            return null;
+        const files = new Map();
+        for (const name of fs.readdirSync(dir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            files.set(name, fs.readFileSync(path.join(dir, name)));
+        }
+        return { dir, files };
+    }
+    catch {
+        return null;
+    }
+}
+function restoreSubstrateJson(snapshot) {
+    for (const name of fs.readdirSync(snapshot.dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        if (!snapshot.files.has(name))
+            fs.unlinkSync(path.join(snapshot.dir, name));
+    }
+    for (const [name, bytes] of snapshot.files) {
+        fs.writeFileSync(path.join(snapshot.dir, name), bytes);
+    }
+}
+/** Attach write-side warnings to an op result without disturbing its shape class. */
+function attachWriteWarnings(result, warnings) {
+    if (typeof result === "string") {
+        return `${result}\n${warnings.map((w) => `write-warning: ${w}`).join("\n")}`;
+    }
+    if (result !== null && typeof result === "object" && "json" in result) {
+        const jsonValue = result.json;
+        if (jsonValue !== null && typeof jsonValue === "object" && !Array.isArray(jsonValue)) {
+            return { ...result, json: { ...jsonValue, writeWarnings: warnings } };
+        }
+    }
+    return result;
+}
+/**
+ * The write pipeline (FEAT-011 criteria 2 + 5 — one module-init pass over the
+ * ops DATA; both consumers — registerAll pi tools and the reflecting CLI —
+ * execute the wrapped run):
+ *
+ *  1. CONVERGE-ON-WRITE: after the op's write lands, rollup-kind stored
+ *     statuses are converged with their derivation (config-driven opt-in;
+ *     best-effort — see convergeDerivedStatusAfterWrite). Runs BEFORE the
+ *     gate evaluation so the gate judges the final converged state and a
+ *     divergence the convergence itself repairs is never flagged.
+ *  2. DELTA-SCOPED WRITE-TIME INVARIANT GATE: the config invariants are
+ *     evaluated before and after the write through the SAME helper
+ *     validateContext uses. Only violations ABSENT before and PRESENT after
+ *     (newly introduced by this write) act: error severity REFUSES the write
+ *     — every top-level substrate *.json is byte-restored from the pre-write
+ *     snapshot and the op throws naming the violations; warning severity is
+ *     surfaced on the op result (appended `write-warning:` lines on string
+ *     results; a `writeWarnings` array inside {json} object payloads).
+ *     Pre-existing violations never block or warn — legacy substrates stay
+ *     fully writable (the delta scope IS the expand-contract analogue).
+ *
+ *  3. ALL-OR-NOTHING ON THROW: an inner-op throw mid-composite (a birth edge
+ *     failing after the item landed; complete-task's status flip failing
+ *     after its edge landed) byte-restores the substrate from the same
+ *     pre-write snapshot before rethrowing, so a composite op never persists
+ *     a partial write the gate did not judge.
+ *
+ * dryRun invocations (append-relations --dryRun) preview without writing and
+ * bypass the pipeline entirely. Ops THROW on failure and return success
+ * strings / {json} on success, so any settled return means the write landed;
+ * sync/async contracts are preserved per op. Nested-item ops are excluded
+ * (item statuses are top-level fields).
+ */
+for (const op of ops) {
+    if (!CONVERGE_AFTER_OPS.has(op.name))
+        continue;
+    const inner = op.run.bind(op);
+    op.run = (cwd, params, ctx) => {
+        const isDryRun = params.dryRun === true;
+        const pre = isDryRun ? null : invariantSnapshot(cwd);
+        const snapshot = pre === null ? null : substrateJsonSnapshot(cwd);
+        const finish = (settled) => {
+            if (isDryRun)
+                return settled;
+            convergeDerivedStatusAfterWrite(cwd, ctx);
+            if (pre === null)
+                return settled;
+            const post = invariantSnapshot(cwd);
+            if (post === null)
+                return settled;
+            const fresh = [...post].filter(([key]) => !pre.has(key));
+            if (fresh.length === 0)
+                return settled;
+            const freshErrors = fresh.filter(([, v]) => v.severity === "error");
+            if (freshErrors.length > 0 && snapshot !== null) {
+                restoreSubstrateJson(snapshot);
+                throw new Error(`${op.name} refused — the write would introduce ${freshErrors.length} invariant violation(s) (substrate restored byte-exact): ${freshErrors
+                    .map(([, v]) => v.message)
+                    .join("; ")}`);
+            }
+            const freshWarnings = fresh.filter(([, v]) => v.severity !== "error").map(([, v]) => v.message);
+            return freshWarnings.length > 0 ? attachWriteWarnings(settled, freshWarnings) : settled;
+        };
+        // Op-level all-or-nothing: an inner-op throw MID-COMPOSITE (e.g. a birth
+        // edge or the complete-task status flip failing after an earlier write in
+        // the same run landed) byte-restores the whole substrate before
+        // rethrowing — without this, partial writes persist in states the gate
+        // never judged. Restore is snapshot-gated like the refusal path (null on
+        // dryRun / no-invariant substrates) and idempotent if finish() already
+        // restored on a gate refusal.
+        const restoreAndRethrow = (err) => {
+            if (snapshot !== null)
+                restoreSubstrateJson(snapshot);
+            throw err;
+        };
+        let result;
+        try {
+            result = inner(cwd, params, ctx);
+        }
+        catch (err) {
+            return restoreAndRethrow(err);
+        }
+        return result instanceof Promise ? result.then(finish, restoreAndRethrow) : finish(result);
+    };
+    op.description +=
+        " Write pipeline: after this op's write, rollup-kind stored statuses converge with their derivation, and the config invariants are re-evaluated delta-scoped — a violation newly introduced by this write refuses it at error severity (substrate byte-restored) or is surfaced on the result at warning severity (write-warning lines / writeWarnings); pre-existing violations never block.";
+}
 /**
  * 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, build the attestation