feat(add-node): require elementId for realisations (INV10) and governedById for gates (INV8)

addNodeOp now enforces three invariants at creation time:
- change → decision via implements (INV2, existing)
- realisation → element via implements (INV10)
- gate → invariant/policy via governed_by (INV8)

CLI gains --element and --governed-by flags. Also adds gate to the
governed_by.from endpoint types, which was previously missing.

Author: Mearman

src/cli/commands/add.ts

@@ -21,6 +21,18 @@ const optsSchema = mutationOpts.extend({
 		.string()
 		.optional()
 		.describe("Decision ID this change implements (required for change nodes)"),
+	element: z
+		.string()
+		.optional()
+		.describe(
+			"Element ID this realisation implements (required for realisation nodes)",
+		),
+	governedBy: z
+		.string()
+		.optional()
+		.describe(
+			"Invariant or policy ID this gate enforces (required for gate nodes)",
+		),
 	option: z
 		.array(z.string())
 		.optional()
@@ -100,7 +112,13 @@ export const addCommand: CommandDef<typeof argsSchema, typeof optsSchema> = {
 		}
 
 		try {
-			const newDoc = addNodeOp({ doc, node, decisionId: opts.decision });
+			const newDoc = addNodeOp({
+				doc,
+				node,
+				decisionId: opts.decision,
+				elementId: opts.element,
+				governedById: opts.governedBy,
+			});
 
 			persistDoc(newDoc, loaded, opts);
 

src/endpoint-types.ts

@@ -244,6 +244,7 @@ export const RELATIONSHIP_ENDPOINT_TYPES: Record<
 			"element",
 			"realisation",
 			"stage",
+			"gate",
 			"change",
 			"policy",
 		],

src/operations/add-node.ts

@@ -2,61 +2,117 @@ import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Node } from "../schema.js";
 
+/**
+ * Validate that a referenced node exists and has the expected type.
+ * @param doc - Document to search for the target node.
+ * @param doc.nodes - Array of nodes in the document.
+ * @param id - ID of the target node to resolve.
+ * @param expectedTypes - Allowed node types for the target.
+ * @param label - Human-readable label for error messages (e.g. "Decision").
+ * @returns The resolved node.
+ * @throws {Error} If the node does not exist or has an unexpected type.
+ * @example
+ * resolveTarget(doc, "D1", ["decision"], "Decision");
+ */
+function resolveTarget(
+	doc: { nodes: readonly { id: string; type: string }[] },
+	id: string,
+	expectedTypes: readonly string[],
+	label: string,
+): { id: string; type: string } {
+	const target = doc.nodes.find((n) => n.id === id);
+	if (!target) {
+		throw new Error(
+			`${label} not found: ${id}. The referenced node must exist before adding this node.`,
+		);
+	}
+	if (!expectedTypes.includes(target.type)) {
+		const typeList = expectedTypes.join(" or ");
+		const article = /^[aeiou]/i.test(typeList) ? "an" : "a";
+		throw new Error(
+			`Node ${id} is not ${article} ${typeList} (type: ${target.type}).`,
+		);
+	}
+	return target;
+}
+
 /**
  * Add a node to a SysProM document. Returns a new document with the node appended.
  *
- * When adding a `change` node, `decisionId` is required. The operation validates
- * that the referenced node exists and is a decision, then automatically creates
- * an `implements` relationship from the change to the decision (INV2).
+ * Certain node types require a companion relationship at creation time:
+ * - `change` requires `decisionId` → creates `implements` relationship (INV2)
+ * - `realisation` requires `elementId` → creates `implements` relationship (INV10)
+ * - `gate` requires `governedById` → creates `governed_by` relationship (INV8)
  * @throws {Error} If a node with the same ID already exists.
- * @throws {Error} If adding a change without a decisionId.
- * @throws {Error} If decisionId references a missing or non-decision node.
+ * @throws {Error} If a required relationship target is missing or has the wrong type.
  */
 export const addNodeOp = defineOperation({
 	name: "addNode",
 	description:
-		"Add a node to the document. Throws if the ID already exists. Change nodes require a decisionId.",
+		"Add a node to the document. Throws if the ID already exists. Change, realisation, and gate nodes require companion relationship targets.",
 	input: z.object({
 		doc: SysProMDocument,
 		node: Node,
 		decisionId: z.string().optional(),
+		elementId: z.string().optional(),
+		governedById: z.string().optional(),
 	}),
 	output: SysProMDocument,
-	fn({ doc, node, decisionId }) {
+	fn({ doc, node, decisionId, elementId, governedById }) {
 		if (doc.nodes.some((n) => n.id === node.id)) {
 			throw new Error(`Node with ID '${node.id}' already exists.`);
 		}
 
+		const newNodes = [...doc.nodes, node];
+		const newRels = [...(doc.relationships ?? [])];
+
 		if (node.type === "change") {
 			if (!decisionId) {
 				throw new Error(
 					`Adding a change requires a decisionId. Use --decision <ID> to link this change to its decision.`,
 				);
 			}
-			const target = doc.nodes.find((n) => n.id === decisionId);
-			if (!target) {
+			resolveTarget(doc, decisionId, ["decision"], "Decision");
+			newRels.push({
+				from: node.id,
+				to: decisionId,
+				type: "implements" as const,
+			});
+		}
+
+		if (node.type === "realisation") {
+			if (!elementId) {
 				throw new Error(
-					`Decision not found: ${decisionId}. The referenced decision must exist before adding a change.`,
+					`Adding a realisation requires an elementId. Use --element <ID> to link this realisation to its element.`,
 				);
 			}
-			if (target.type !== "decision") {
+			resolveTarget(doc, elementId, ["element"], "Element");
+			newRels.push({
+				from: node.id,
+				to: elementId,
+				type: "implements" as const,
+			});
+		}
+
+		if (node.type === "gate") {
+			if (!governedById) {
 				throw new Error(
-					`Node ${decisionId} is not a decision (type: ${target.type}). Changes must reference a decision node.`,
+					`Adding a gate requires a governedById. Use --governed-by <ID> to link this gate to the invariant or policy it enforces.`,
 				);
 			}
-			return {
-				...doc,
-				nodes: [...doc.nodes, node],
-				relationships: [
-					...(doc.relationships ?? []),
-					{ from: node.id, to: decisionId, type: "implements" as const },
-				],
-			};
+			resolveTarget(
+				doc,
+				governedById,
+				["invariant", "policy"],
+				"Invariant/policy",
+			);
+			newRels.push({
+				from: node.id,
+				to: governedById,
+				type: "governed_by" as const,
+			});
 		}
 
-		return {
-			...doc,
-			nodes: [...doc.nodes, node],
-		};
+		return { ...doc, nodes: newNodes, relationships: newRels };
 	},
 });

tests/add-cli.unit.test.ts

@@ -8,20 +8,23 @@ function makeDoc(): SysProMDocument {
 		nodes: [
 			{ id: "D1", type: "decision", name: "Existing Decision" },
 			{ id: "I1", type: "intent", name: "Some Intent" },
+			{ id: "EL1", type: "element", name: "Some Element" },
+			{ id: "INV1", type: "invariant", name: "Some Invariant" },
+			{ id: "POL1", type: "policy", name: "Some Policy" },
 		],
 		relationships: [],
 	};
 }
 
-describe("addNode change-decision guard", () => {
+describe("addNode change-decision guard (INV2)", () => {
 	it("adds change node with implements relationship when decisionId provided", () => {
 		const doc = makeDoc();
 		const result = addNodeOp({
 			doc,
 			node: { id: "CH1", type: "change", name: "My Change" },
 			decisionId: "D1",
 		});
-		assert.equal(result.nodes.length, 3);
+		assert.equal(result.nodes.length, 6);
 		assert.ok(result.nodes.find((n) => n.id === "CH1"));
 		const rel = result.relationships?.find(
 			(r) => r.from === "CH1" && r.to === "D1" && r.type === "implements",
@@ -73,7 +76,7 @@ describe("addNode change-decision guard", () => {
 			doc,
 			node: { id: "CN1", type: "concept", name: "My Concept" },
 		});
-		assert.equal(result.nodes.length, 3);
+		assert.equal(result.nodes.length, 6);
 		assert.ok(result.nodes.find((n) => n.id === "CN1"));
 	});
 
@@ -84,11 +87,135 @@ describe("addNode change-decision guard", () => {
 			node: { id: "CN1", type: "concept", name: "My Concept" },
 			decisionId: "D1",
 		});
-		assert.equal(result.nodes.length, 3);
-		// Should not create a relationship for non-change nodes
+		assert.equal(result.nodes.length, 6);
 		assert.equal(
 			result.relationships?.filter((r) => r.from === "CN1").length ?? 0,
 			0,
 		);
 	});
 });
+
+describe("addNode realisation-element guard (INV10)", () => {
+	it("adds realisation with implements relationship when elementId provided", () => {
+		const doc = makeDoc();
+		const result = addNodeOp({
+			doc,
+			node: { id: "R1", type: "realisation", name: "My Realisation" },
+			elementId: "EL1",
+		});
+		assert.equal(result.nodes.length, 6);
+		assert.ok(result.nodes.find((n) => n.id === "R1"));
+		const rel = result.relationships?.find(
+			(r) => r.from === "R1" && r.to === "EL1" && r.type === "implements",
+		);
+		assert.ok(rel, "implements relationship should be created");
+	});
+
+	it("throws when realisation added without elementId", () => {
+		const doc = makeDoc();
+		assert.throws(
+			() =>
+				addNodeOp({
+					doc,
+					node: { id: "R1", type: "realisation", name: "My Realisation" },
+				}),
+			/realisation.*requires.*elementId/i,
+		);
+	});
+
+	it("throws when elementId does not exist", () => {
+		const doc = makeDoc();
+		assert.throws(
+			() =>
+				addNodeOp({
+					doc,
+					node: { id: "R1", type: "realisation", name: "My Realisation" },
+					elementId: "EL999",
+				}),
+			/not found.*EL999/i,
+		);
+	});
+
+	it("throws when elementId references a non-element node", () => {
+		const doc = makeDoc();
+		assert.throws(
+			() =>
+				addNodeOp({
+					doc,
+					node: { id: "R1", type: "realisation", name: "My Realisation" },
+					elementId: "D1",
+				}),
+			/not an element/i,
+		);
+	});
+});
+
+describe("addNode gate-invariant guard (INV8)", () => {
+	it("adds gate with governed_by relationship when governedById provided with invariant", () => {
+		const doc = makeDoc();
+		const result = addNodeOp({
+			doc,
+			node: { id: "G1", type: "gate", name: "My Gate" },
+			governedById: "INV1",
+		});
+		assert.equal(result.nodes.length, 6);
+		assert.ok(result.nodes.find((n) => n.id === "G1"));
+		const rel = result.relationships?.find(
+			(r) =>
+				r.from === "G1" && r.to === "INV1" && r.type === "governed_by",
+		);
+		assert.ok(rel, "governed_by relationship should be created");
+	});
+
+	it("adds gate with governed_by relationship when governedById provided with policy", () => {
+		const doc = makeDoc();
+		const result = addNodeOp({
+			doc,
+			node: { id: "G1", type: "gate", name: "My Gate" },
+			governedById: "POL1",
+		});
+		const rel = result.relationships?.find(
+			(r) =>
+				r.from === "G1" && r.to === "POL1" && r.type === "governed_by",
+		);
+		assert.ok(rel, "governed_by relationship should be created for policy");
+	});
+
+	it("throws when gate added without governedById", () => {
+		const doc = makeDoc();
+		assert.throws(
+			() =>
+				addNodeOp({
+					doc,
+					node: { id: "G1", type: "gate", name: "My Gate" },
+				}),
+			/gate.*requires.*governedById/i,
+		);
+	});
+
+	it("throws when governedById does not exist", () => {
+		const doc = makeDoc();
+		assert.throws(
+			() =>
+				addNodeOp({
+					doc,
+					node: { id: "G1", type: "gate", name: "My Gate" },
+					governedById: "INV999",
+				}),
+			/not found.*INV999/i,
+		);
+	});
+
+	it("throws when governedById references neither invariant nor policy", () => {
+		const doc = makeDoc();
+		assert.throws(
+			() =>
+				addNodeOp({
+					doc,
+					node: { id: "G1", type: "gate", name: "My Gate" },
+					governedById: "D1",
+				}),
+			/not an invariant or policy/i,
+		);
+	});
+});