sysprom 1.10.2 → 1.12.0

package/dist/src/cli/commands/add.d.ts

@@ -16,6 +16,9 @@ declare const optsSchema: z.ZodObject<{
     rationale: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodArray<z.ZodString>>;
     selected: z.ZodOptional<z.ZodString>;
+    decision: z.ZodOptional<z.ZodString>;
+    element: z.ZodOptional<z.ZodString>;
+    governedBy: z.ZodOptional<z.ZodString>;
     option: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export declare const addCommand: CommandDef<typeof argsSchema, typeof optsSchema>;

package/dist/src/cli/commands/add.js

@@ -14,6 +14,18 @@ const optsSchema = mutationOpts.extend({
     rationale: z.string().optional().describe("Decision rationale"),
     scope: z.array(z.string()).optional().describe("Change scope (repeatable)"),
     selected: z.string().optional().describe("Selected option ID"),
+    decision: z
+        .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()
@@ -77,7 +89,13 @@ export const addCommand = {
             });
         }
         try {
-            const newDoc = addNodeOp({ doc, node });
+            const newDoc = addNodeOp({
+                doc,
+                node,
+                decisionId: opts.decision,
+                elementId: opts.element,
+                governedById: opts.governedBy,
+            });
             persistDoc(newDoc, loaded, opts);
             if (opts.json) {
                 console.log(JSON.stringify(node, null, 2));

package/dist/src/endpoint-types.js

@@ -224,6 +224,7 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
             "element",
             "realisation",
             "stage",
+            "gate",
             "change",
             "policy",
         ],

package/dist/src/operations/add-node.d.ts

@@ -1,7 +1,13 @@
 import * as z from "zod";
 /**
  * Add a node to a SysProM document. Returns a new document with the node appended.
+ *
+ * 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 a required relationship target is missing or has the wrong type.
  */
 export declare const addNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
@@ -594,6 +600,9 @@ export declare const addNodeOp: import("./define-operation.js").DefinedOperation
             } | undefined;
         };
     };
+    decisionId: z.ZodOptional<z.ZodString>;
+    elementId: z.ZodOptional<z.ZodString>;
+    governedById: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodObject<{

package/dist/src/operations/add-node.js

@@ -1,25 +1,90 @@
 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, id, expectedTypes, label) {
+    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.
+ *
+ * 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 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.",
+    description: "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 }) {
+    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.`);
         }
-        return {
-            ...doc,
-            nodes: [...doc.nodes, node],
-        };
+        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.`);
+            }
+            resolveTarget(doc, decisionId, ["decision"], "Decision");
+            newRels.push({
+                from: node.id,
+                to: decisionId,
+                type: "implements",
+            });
+        }
+        if (node.type === "realisation") {
+            if (!elementId) {
+                throw new Error(`Adding a realisation requires an elementId. Use --element <ID> to link this realisation to its element.`);
+            }
+            resolveTarget(doc, elementId, ["element"], "Element");
+            newRels.push({
+                from: node.id,
+                to: elementId,
+                type: "implements",
+            });
+        }
+        if (node.type === "gate") {
+            if (!governedById) {
+                throw new Error(`Adding a gate requires a governedById. Use --governed-by <ID> to link this gate to the invariant or policy it enforces.`);
+            }
+            resolveTarget(doc, governedById, ["invariant", "policy"], "Invariant/policy");
+            newRels.push({
+                from: node.id,
+                to: governedById,
+                type: "governed_by",
+            });
+        }
+        return { ...doc, nodes: newNodes, relationships: newRels };
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sysprom",
-  "version": "1.10.2",
+  "version": "1.12.0",
   "description": "SysProM — System Provenance Model CLI and library",
   "author": "ExaDev",
   "homepage": "https://exadev.github.io/SysProM",