@davidorex/pi-context 0.29.0 → 0.30.0

package/dist/context-sdk.d.ts

@@ -473,9 +473,100 @@ export declare function appendRelationByRef(cwd: string, rel: {
     child: string;
     relation_type: string;
     ordinal?: number;
-}, ctx?: DispatchContext): {
+}, ctx?: DispatchContext, opts?: {
+    dryRun?: boolean;
+}): {
     appended: boolean;
     edge: Edge;
+    dryRun?: boolean;
+};
+/**
+ * Friendly-selector relation removal — the porcelain twin of
+ * {@link appendRelationByRef}. Resolves `parent` / `child` STRING selectors to
+ * structured `EdgeEndpoint`s via the SAME `resolveRelationSelector` the append
+ * porcelain uses, then delegates to the raw `removeRelation` plumbing, which
+ * matches on the `identityKey` dedup identity (so a `removeRelationByRef` of the
+ * selectors an `appendRelationByRef` wrote removes exactly that edge — the
+ * porcelain layers stay symmetric). Returns `{ removed, edge }` where `edge` is
+ * the RESOLVED structured edge that was matched against (so callers can report /
+ * dry-run-validate the structured form), and `removed` is false on the
+ * idempotent no-match no-op.
+ */
+export declare function removeRelationByRef(cwd: string, rel: {
+    parent: string;
+    child: string;
+    relation_type: string;
+}, ctx?: DispatchContext, opts?: {
+    dryRun?: boolean;
+}): {
+    removed: boolean;
+    edge: Edge;
+    dryRun?: boolean;
+};
+/**
+ * Friendly-selector ATOMIC relation replace — a single load → filter-out-old →
+ * push-new → write cycle (no half-state: the old edge and the new edge never
+ * coexist on disk, and the file is rewritten exactly ONCE). Resolves the `old`
+ * and `new` selector triples via the SAME `resolveRelationSelector` the append /
+ * remove porcelain use. The old edge is matched on the `identityKey` dedup
+ * identity (parent, child, relation_type — `ordinal`-insensitive, symmetric with
+ * append-dedup / remove); the new edge is pushed verbatim (carrying its optional
+ * `ordinal`). If the resolved new edge collides on identity with a surviving edge
+ * it is de-duplicated against the post-filter set so the write stays
+ * exact-duplicate-free, matching `appendRelations` semantics.
+ *
+ * Returns `{ replaced, removed, oldEdge, newEdge }`: `removed` reflects whether
+ * the old edge was actually present (false → the old edge was absent, so this is
+ * effectively an append of `newEdge`); `replaced` is true when the resolved new
+ * edge was written (false only when it collided with an already-present surviving
+ * edge → a no-op add). `ctx` threads to `writeRelations` for attestation parity.
+ */
+export declare function replaceRelationByRef(cwd: string, rels: {
+    old: {
+        parent: string;
+        child: string;
+        relation_type: string;
+    };
+    new: {
+        parent: string;
+        child: string;
+        relation_type: string;
+        ordinal?: number;
+    };
+}, ctx?: DispatchContext, opts?: {
+    dryRun?: boolean;
+}): {
+    replaced: boolean;
+    removed: boolean;
+    oldEdge: Edge;
+    newEdge: Edge;
+    dryRun?: boolean;
+};
+/**
+ * Friendly-selector BULK relation append over the raw {@link appendRelations}
+ * (whole-file additive write with per-(parent, child, relation_type) dedup,
+ * skipping edges already on disk OR earlier in the same batch). Resolves each
+ * `edges[]` selector triple via the SAME `resolveRelationSelector` the
+ * single-edge porcelain uses, then hands the resolved `Edge[]` to
+ * `appendRelations`. Returns `{ appended, skipped, edges }` — `edges` being the
+ * resolved structured edges handed to the raw layer (so callers can report /
+ * dry-run-validate the structured form). Same deferred-integrity semantics as
+ * `appendRelations` (AJV-shape + duplicate-no-op only; relation_type
+ * registration / endpoint resolution / cycle checks deferred to
+ * `validateContext`).
+ */
+export declare function appendRelationsByRef(cwd: string, edges: {
+    parent: string;
+    child: string;
+    relation_type: string;
+    ordinal?: number;
+}[], ctx?: DispatchContext, opts?: {
+    dryRun?: boolean;
+}): {
+    appended: number;
+    skipped: number;
+    edges: Edge[];
+    dryRun?: boolean;
 };
 /**
  * Classification of an endpoint by {@link resolveRef}:
@@ -596,8 +687,12 @@ export interface CompleteTaskResult {
 }
 /**
  * Gate task completion on verification. Reads the verification block to confirm
- * a passing verification entry exists targeting this task, then atomically
- * updates the task status to "completed" with the verification cross-reference.
+ * a passing verification entry exists, asserts a `verification_verifies_item`
+ * closure-table edge links that verification (parent) to this task (child), then
+ * atomically updates the task status to "completed". The edge IS the linkage —
+ * no `verification` field is embedded on the task (the verification → task
+ * `verification.target`/`target_type` fields were removed from the verification
+ * schema in favor of the edge; this gate reads the edge, not the removed fields).
  */
-export declare function completeTask(cwd: string, taskId: string, verificationId: string): CompleteTaskResult;
+export declare function completeTask(cwd: string, taskId: string, verificationId: string, ctx?: DispatchContext): CompleteTaskResult;
 //# sourceMappingURL=context-sdk.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"context-sdk.d.ts","sourceRoot":"","sources":["../src/context-sdk.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context-sdk.d.ts","sourceRoot":"","sources":["../src/context-sdk.ts"],"names":[],"mappings":"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"}

package/dist/context-sdk.js

@@ -6,13 +6,16 @@
 import { execSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { readBlock, readBlockForDir, updateItemInBlock } from "./block-api.js";
-import { appendRelation, endpointKey, findUnmaterializedAssets, isSkeletonConfig, loadConfig, loadRelations, validateRelations, } from "./context.js";
+import { appendRelation, appendRelations, endpointIdentity, endpointKey, findUnmaterializedAssets, isSkeletonConfig, loadConfig, loadRelations, removeRelation, validateRelations, writeRelations, } from "./context.js";
 import { resolveContextDir, SCHEMAS_DIR, schemaPath, schemasDir, tryResolveContextDir } from "./context-dir.js";
 import { loadRegistry, resolveAlias, resolveSubstrateDir } from "./context-registry.js";
 import { cleanGitEnv } from "./git-env.js";
 import { getLensValidators } from "./lens-validator.js";
+import { findReferencesInRepo } from "./lens-view.js";
 import { addressInto, discoverArrayKey, pageArray } from "./read-element.js";
+import { validateFromFile } from "./schema-validator.js";
 import { findNestedIdBearingArrays } from "./schema-write.js";
 import { resolveStatusVocabulary } from "./status-vocab.js";
 import { topoSort } from "./topo.js";
@@ -1111,6 +1114,25 @@ export function resolveRelationSelector(cwd, selector) {
     const oid = loc && typeof loc.item.oid === "string" ? loc.item.oid : selector;
     return { kind: "item", oid, refname: selector };
 }
+/**
+ * Resolve the bundled relations schema file (top-level `Edge[]` array schema)
+ * — the SAME schema `loadRelations` / `writeRelations` validate against (see
+ * `context.ts` `bundledSchemaPath("relations")`). Resolved relative to this
+ * module so it works from both `src/` (tsx --test) and `dist/` (after tsc) —
+ * the `schemas/` dir lives one directory up in either case. Used by the
+ * `dryRun` preview branch of the relation porcelain to apply the write path's
+ * validation WITHOUT writing (TASK-010: the shared library preview the
+ * orchestrator scripts and the `--dryRun` ops both call).
+ */
+function relationsSchemaPath() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "schemas", "relations.schema.json");
+}
+/** Dedup identity key for an edge — the SAME (parent, child, relation_type)
+ * identity the raw append/remove plumbing matches on (ordinal-insensitive). */
+function edgeIdentityKey(edge) {
+    return `${endpointIdentity(edge.parent)} ${endpointIdentity(edge.child)} ${edge.relation_type}`;
+}
 /**
  * Friendly-selector relation append (Cycle 5 porcelain). Resolves `parent` /
  * `child` STRING selectors to structured `EdgeEndpoint`s via
@@ -1123,16 +1145,157 @@ export function resolveRelationSelector(cwd, selector) {
  * actually written (so callers can report / dry-run-validate the structured
  * form).
  */
-export function appendRelationByRef(cwd, rel, ctx) {
+export function appendRelationByRef(cwd, rel, ctx, opts) {
     const edge = {
         parent: resolveRelationSelector(cwd, rel.parent),
         child: resolveRelationSelector(cwd, rel.child),
         relation_type: rel.relation_type,
         ...(rel.ordinal !== undefined ? { ordinal: rel.ordinal } : {}),
     };
+    if (opts?.dryRun) {
+        // Preview parity: run the SAME validation the write path applies (the
+        // prospective Edge[] against the whole relations schema — what
+        // loadRelations/writeRelations validate) but write nothing. The
+        // would-decision uses the SAME dedup identity the raw append matches on.
+        const existing = loadRelations(cwd);
+        const prospective = [...existing, edge];
+        validateFromFile(relationsSchemaPath(), prospective, "relations[edge]");
+        const newId = edgeIdentityKey(edge);
+        const duplicate = existing.some((e) => edgeIdentityKey(e) === newId);
+        return { appended: !duplicate, edge, dryRun: true };
+    }
     const { appended } = appendRelation(cwd, edge, ctx);
     return { appended, edge };
 }
+/**
+ * Friendly-selector relation removal — the porcelain twin of
+ * {@link appendRelationByRef}. Resolves `parent` / `child` STRING selectors to
+ * structured `EdgeEndpoint`s via the SAME `resolveRelationSelector` the append
+ * porcelain uses, then delegates to the raw `removeRelation` plumbing, which
+ * matches on the `identityKey` dedup identity (so a `removeRelationByRef` of the
+ * selectors an `appendRelationByRef` wrote removes exactly that edge — the
+ * porcelain layers stay symmetric). Returns `{ removed, edge }` where `edge` is
+ * the RESOLVED structured edge that was matched against (so callers can report /
+ * dry-run-validate the structured form), and `removed` is false on the
+ * idempotent no-match no-op.
+ */
+export function removeRelationByRef(cwd, rel, ctx, opts) {
+    const edge = {
+        parent: resolveRelationSelector(cwd, rel.parent),
+        child: resolveRelationSelector(cwd, rel.child),
+        relation_type: rel.relation_type,
+    };
+    if (opts?.dryRun) {
+        // Preview parity: compute the prospective post-removal Edge[] and validate
+        // it against the whole relations schema (write-path validation), write
+        // nothing. `removed` reflects whether a matching edge is present on the
+        // SAME dedup identity the raw remove matches on.
+        const existing = loadRelations(cwd);
+        const targetId = edgeIdentityKey(edge);
+        const matches = existing.some((e) => edgeIdentityKey(e) === targetId);
+        const prospective = existing.filter((e) => edgeIdentityKey(e) !== targetId);
+        validateFromFile(relationsSchemaPath(), prospective, "relations[edge]");
+        return { removed: matches, edge, dryRun: true };
+    }
+    const { removed } = removeRelation(cwd, edge, ctx);
+    return { removed, edge };
+}
+/**
+ * Friendly-selector ATOMIC relation replace — a single load → filter-out-old →
+ * push-new → write cycle (no half-state: the old edge and the new edge never
+ * coexist on disk, and the file is rewritten exactly ONCE). Resolves the `old`
+ * and `new` selector triples via the SAME `resolveRelationSelector` the append /
+ * remove porcelain use. The old edge is matched on the `identityKey` dedup
+ * identity (parent, child, relation_type — `ordinal`-insensitive, symmetric with
+ * append-dedup / remove); the new edge is pushed verbatim (carrying its optional
+ * `ordinal`). If the resolved new edge collides on identity with a surviving edge
+ * it is de-duplicated against the post-filter set so the write stays
+ * exact-duplicate-free, matching `appendRelations` semantics.
+ *
+ * Returns `{ replaced, removed, oldEdge, newEdge }`: `removed` reflects whether
+ * the old edge was actually present (false → the old edge was absent, so this is
+ * effectively an append of `newEdge`); `replaced` is true when the resolved new
+ * edge was written (false only when it collided with an already-present surviving
+ * edge → a no-op add). `ctx` threads to `writeRelations` for attestation parity.
+ */
+export function replaceRelationByRef(cwd, rels, ctx, opts) {
+    const oldEdge = {
+        parent: resolveRelationSelector(cwd, rels.old.parent),
+        child: resolveRelationSelector(cwd, rels.old.child),
+        relation_type: rels.old.relation_type,
+    };
+    const newEdge = {
+        parent: resolveRelationSelector(cwd, rels.new.parent),
+        child: resolveRelationSelector(cwd, rels.new.child),
+        relation_type: rels.new.relation_type,
+        ...(rels.new.ordinal !== undefined ? { ordinal: rels.new.ordinal } : {}),
+    };
+    const existing = loadRelations(cwd);
+    const oldKey = edgeIdentityKey(oldEdge);
+    const newKey = edgeIdentityKey(newEdge);
+    const filtered = existing.filter((e) => edgeIdentityKey(e) !== oldKey);
+    const removed = filtered.length !== existing.length;
+    const collides = filtered.some((e) => edgeIdentityKey(e) === newKey);
+    const next = collides ? filtered : [...filtered, newEdge];
+    if (opts?.dryRun) {
+        // Preview parity: validate the prospective post-replace Edge[] against the
+        // whole relations schema (write-path validation), write nothing. The
+        // would-decisions (`removed`/`replaced`) are the SAME values the write
+        // path computes.
+        validateFromFile(relationsSchemaPath(), next, "relations[edge]");
+        return { replaced: !collides, removed, oldEdge, newEdge, dryRun: true };
+    }
+    writeRelations(cwd, next, ctx);
+    return { replaced: !collides, removed, oldEdge, newEdge };
+}
+/**
+ * Friendly-selector BULK relation append over the raw {@link appendRelations}
+ * (whole-file additive write with per-(parent, child, relation_type) dedup,
+ * skipping edges already on disk OR earlier in the same batch). Resolves each
+ * `edges[]` selector triple via the SAME `resolveRelationSelector` the
+ * single-edge porcelain uses, then hands the resolved `Edge[]` to
+ * `appendRelations`. Returns `{ appended, skipped, edges }` — `edges` being the
+ * resolved structured edges handed to the raw layer (so callers can report /
+ * dry-run-validate the structured form). Same deferred-integrity semantics as
+ * `appendRelations` (AJV-shape + duplicate-no-op only; relation_type
+ * registration / endpoint resolution / cycle checks deferred to
+ * `validateContext`).
+ */
+export function appendRelationsByRef(cwd, edges, ctx, opts) {
+    const resolved = edges.map((rel) => ({
+        parent: resolveRelationSelector(cwd, rel.parent),
+        child: resolveRelationSelector(cwd, rel.child),
+        relation_type: rel.relation_type,
+        ...(rel.ordinal !== undefined ? { ordinal: rel.ordinal } : {}),
+    }));
+    if (opts?.dryRun) {
+        // Preview parity: replay the bulk dedup the raw appendRelations applies —
+        // skip an edge whose identity is already on disk OR earlier in THIS batch
+        // (a `seen` Set seeded from the existing on-disk identities) — accumulate
+        // the non-dup prospective Edge[], validate it against the whole relations
+        // schema (write-path validation), write nothing.
+        const existing = loadRelations(cwd);
+        const seen = new Set(existing.map((e) => edgeIdentityKey(e)));
+        let appended = 0;
+        let skipped = 0;
+        const prospective = [...existing];
+        for (const edge of resolved) {
+            const key = edgeIdentityKey(edge);
+            if (seen.has(key)) {
+                skipped++;
+            }
+            else {
+                seen.add(key);
+                prospective.push(edge);
+                appended++;
+            }
+        }
+        validateFromFile(relationsSchemaPath(), prospective, "relations[edge]");
+        return { appended, skipped, edges: resolved, dryRun: true };
+    }
+    const { appended, skipped } = appendRelations(cwd, resolved, ctx);
+    return { appended, skipped, edges: resolved };
+}
 /**
  * Build (or fetch from the per-pass cache) the {@link SubstrateIndex} for a
  * REGISTERED foreign substrate. Resolves the substrate dir from the registry,
@@ -1710,10 +1873,14 @@ export function validateContext(cwd) {
 }
 /**
  * Gate task completion on verification. Reads the verification block to confirm
- * a passing verification entry exists targeting this task, then atomically
- * updates the task status to "completed" with the verification cross-reference.
+ * a passing verification entry exists, asserts a `verification_verifies_item`
+ * closure-table edge links that verification (parent) to this task (child), then
+ * atomically updates the task status to "completed". The edge IS the linkage —
+ * no `verification` field is embedded on the task (the verification → task
+ * `verification.target`/`target_type` fields were removed from the verification
+ * schema in favor of the edge; this gate reads the edge, not the removed fields).
  */
-export function completeTask(cwd, taskId, verificationId) {
+export function completeTask(cwd, taskId, verificationId, ctx) {
     // 1. Read and validate verification entry
     let verData;
     try {
@@ -1727,9 +1894,6 @@ export function completeTask(cwd, taskId, verificationId) {
     if (!verification) {
         throw new Error(`Verification '${verificationId}' not found in verification block`);
     }
-    if (verification.target !== taskId || verification.target_type !== "task") {
-        throw new Error(`Verification '${verificationId}' targets '${verification.target}' (${verification.target_type}), not task '${taskId}'`);
-    }
     if (verification.status !== "passed") {
         throw new Error(`Verification '${verificationId}' status is '${verification.status}', not 'passed' — cannot complete task`);
     }
@@ -1753,11 +1917,17 @@ export function completeTask(cwd, taskId, verificationId) {
     if (currentStatus === "cancelled") {
         throw new Error(`Task '${taskId}' is already cancelled`);
     }
-    // 3. Update task status with verification cross-reference
-    updateItemInBlock(cwd, "tasks", "tasks", (t) => t.id === taskId, {
-        status: "completed",
-        verification: verificationId,
-    });
+    // 3. Assert the verification_verifies_item edge: verification (parent) →
+    // task (child). The closure-table edge — not a verification field — is the
+    // canonical linkage. Inbound edges point AT the task; compare the parent
+    // endpoint via endpointKey (the codebase's endpoint-comparison idiom).
+    const verifiesEdge = findReferencesInRepo(cwd, taskId, "inbound").find((e) => e.relation_type === "verification_verifies_item" && endpointKey(e.parent) === verificationId);
+    if (!verifiesEdge) {
+        throw new Error(`verification '${verificationId}' does not verify task '${taskId}' — no verification_verifies_item edge; file the link (append-relation parent=${verificationId} child=${taskId} relation_type=verification_verifies_item) before completing`);
+    }
+    // 4. Update task status. The edge is the linkage — no `verification` field is
+    // embedded (a populated additionalProperties:false tasks schema would reject it).
+    updateItemInBlock(cwd, "tasks", "tasks", (t) => t.id === taskId, { status: "completed" }, ctx);
     return {
         taskId,
         verificationId,