sysprom 1.2.6 → 1.3.0

package/dist/src/endpoint-types.d.ts

@@ -0,0 +1,20 @@
+import { NodeType, RelationshipType } from "./schema.js";
+/**
+ * Defines which node types are valid for the source and target endpoints
+ * of each relationship type. Used for semantic validation of graph mutations.
+ *
+ * Note: Permissive by design to allow diverse relationship patterns while
+ * catching obvious semantic errors. The model is flexible across abstraction layers.
+ */
+export declare const RELATIONSHIP_ENDPOINT_TYPES: Record<RelationshipType, {
+    from: NodeType[];
+    to: NodeType[];
+}>;
+/**
+ * Check if a relationship type is valid for the given endpoint node types.
+ * @param relType The relationship type
+ * @param fromType The source node type
+ * @param toType The target node type
+ * @returns true if the endpoint types are valid for this relationship
+ */
+export declare function isValidEndpointPair(relType: RelationshipType, fromType: NodeType, toType: NodeType): boolean;

package/dist/src/endpoint-types.js

@@ -0,0 +1,303 @@
+/**
+ * Defines which node types are valid for the source and target endpoints
+ * of each relationship type. Used for semantic validation of graph mutations.
+ *
+ * Note: Permissive by design to allow diverse relationship patterns while
+ * catching obvious semantic errors. The model is flexible across abstraction layers.
+ */
+export const RELATIONSHIP_ENDPOINT_TYPES = {
+    // Refines — used across all node types, represents specification refinement
+    refines: {
+        from: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "principle",
+            "policy",
+        ],
+        to: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "principle",
+            "policy",
+        ],
+    },
+    // Realises — implementation hierarchy
+    realises: {
+        from: ["capability", "element", "realisation"],
+        to: ["capability", "element", "realisation"],
+    },
+    // Implements — operationalisation
+    implements: {
+        from: ["element", "realisation", "change", "stage"],
+        to: ["capability", "element", "realisation", "decision", "change"],
+    },
+    // Depends on — broad dependency across all node types
+    depends_on: {
+        from: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "invariant",
+            "principle",
+            "policy",
+            "protocol",
+            "stage",
+            "role",
+            "gate",
+            "mode",
+            "artefact",
+            "artefact_flow",
+            "decision",
+            "change",
+        ],
+        to: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "invariant",
+            "principle",
+            "policy",
+            "protocol",
+            "stage",
+            "role",
+            "gate",
+            "mode",
+            "artefact",
+            "artefact_flow",
+            "decision",
+            "change",
+        ],
+    },
+    // Constrained by — constraints and governance
+    constrained_by: {
+        from: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "decision",
+            "change",
+            "invariant",
+        ],
+        to: ["invariant", "principle", "policy", "protocol", "concept"],
+    },
+    // Requires — explicit requirements
+    requires: {
+        from: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "stage",
+            "change",
+        ],
+        to: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "artefact",
+        ],
+    },
+    // Affects — broad impact relationships
+    affects: {
+        from: ["decision", "change", "artefact", "stage"],
+        to: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "invariant",
+            "principle",
+            "policy",
+            "protocol",
+            "decision",
+            "change",
+            "artefact",
+        ],
+    },
+    // Must preserve — invariant protection
+    must_preserve: {
+        from: ["decision"],
+        to: ["invariant", "principle", "policy", "concept"],
+    },
+    // Supersedes — replacement and obsolescence
+    supersedes: {
+        from: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "decision",
+            "change",
+            "version",
+        ],
+        to: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "decision",
+            "change",
+            "version",
+        ],
+    },
+    // Performs — process enactment
+    performs: {
+        from: ["stage", "role"],
+        to: ["capability", "artefact", "artefact_flow"],
+    },
+    // Precedes — temporal ordering
+    precedes: {
+        from: ["stage", "gate", "milestone"],
+        to: ["stage", "gate", "milestone"],
+    },
+    // Must follow — strong sequential ordering
+    must_follow: {
+        from: ["stage", "gate"],
+        to: ["stage", "gate"],
+    },
+    // Part of — structural decomposition
+    part_of: {
+        from: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "artefact",
+            "stage",
+            "policy",
+            "principle",
+            "role",
+            "gate",
+            "mode",
+        ],
+        to: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "artefact",
+            "stage",
+            "policy",
+            "principle",
+            "protocol",
+            "role",
+            "gate",
+            "mode",
+        ],
+    },
+    // Blocks — impediments and constraints
+    blocks: {
+        from: ["invariant", "policy", "decision", "principle"],
+        to: ["decision", "change", "stage"],
+    },
+    // Routes to — data/process flow
+    routes_to: {
+        from: ["artefact_flow"],
+        to: ["artefact_flow", "stage", "artefact"],
+    },
+    // Governed by — governance relationships
+    governed_by: {
+        from: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "stage",
+            "change",
+            "policy",
+        ],
+        to: ["policy", "protocol", "role", "principle", "invariant", "concept"],
+    },
+    // Modifies — mutation and change
+    modifies: {
+        from: ["change", "artefact_flow", "stage"],
+        to: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "artefact",
+        ],
+    },
+    // Transforms into — metamorphosis
+    transforms_into: {
+        from: ["artefact"],
+        to: ["artefact"],
+    },
+    // Triggered by — causation
+    triggered_by: {
+        from: ["stage", "gate", "artefact_flow", "change"],
+        to: ["decision", "artefact", "gate", "stage"],
+    },
+    // Disables — negation/reversal
+    disables: {
+        from: ["decision", "change"],
+        to: ["capability", "realisation"],
+    },
+    // Applies to — applicability and scope
+    applies_to: {
+        from: ["policy", "principle", "mode", "protocol"],
+        to: [
+            "intent",
+            "concept",
+            "capability",
+            "element",
+            "realisation",
+            "stage",
+            "decision",
+            "change",
+        ],
+    },
+    // Produces — generation
+    produces: {
+        from: ["stage", "artefact_flow", "realisation"],
+        to: ["artefact"],
+    },
+    // Consumes — usage
+    consumes: {
+        from: ["stage", "artefact_flow", "realisation"],
+        to: ["artefact"],
+    },
+    // Selects — choice and instantiation
+    selects: {
+        from: ["decision", "mode"],
+        to: ["capability", "stage"],
+    },
+};
+/**
+ * Check if a relationship type is valid for the given endpoint node types.
+ * @param relType The relationship type
+ * @param fromType The source node type
+ * @param toType The target node type
+ * @returns true if the endpoint types are valid for this relationship
+ */
+export function isValidEndpointPair(relType, fromType, toType) {
+    const endpoints = RELATIONSHIP_ENDPOINT_TYPES[relType];
+    if (!endpoints) {
+        // Unknown relationship type — should be caught by schema validation
+        return false;
+    }
+    return (endpoints.from.includes(fromType) && endpoints.to.includes(toType));
+}

package/dist/src/index.d.ts

@@ -9,6 +9,7 @@ export { SysProMDocument, Node, Relationship, NodeType, NodeStatus, Relationship
 export { defineOperation, type OperationDef, type DefinedOperation, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, nextIdOp, initDocumentOp, addPlanTaskOp, updatePlanTaskOp, markTaskDoneOp, markTaskUndoneOp, taskListOp, planInitOp, planAddTaskOp, planStatusOp, planProgressOp, planGateOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, timelineOp, nodeHistoryOp, stateAtOp, validateOp, statsOp, searchOp, checkOp, graphOp, renameOp, jsonToMarkdownOp, markdownToJsonOp, speckitImportOp, speckitExportOp, speckitSyncOp, speckitDiffOp, type RemoveResult, type ValidationResult, type DocumentStats, type NodeDetail, type TraceNode, type TimelineEvent, type NodeState, type PlanStatusResult, type PhaseProgressResult, type GateResultOutput, type SyncResult, type DiffResult, } from "./operations/index.js";
 export { jsonToMarkdownSingle, jsonToMarkdownMultiDoc, jsonToMarkdown, type ConvertOptions, } from "./json-to-md.js";
 export { markdownSingleToJson, markdownMultiDocToJson, markdownToJson, } from "./md-to-json.js";
+export { RELATIONSHIP_ENDPOINT_TYPES, isValidEndpointPair, } from "./endpoint-types.js";
 export { canonicalise, type FormatOptions } from "./canonical-json.js";
 export { textToString, textToLines, textToMarkdown, markdownToText, } from "./text.js";
 export { loadDocument, saveDocument, type Format, type LoadedDocument, } from "./io.js";

package/dist/src/index.js

@@ -12,6 +12,8 @@ export { defineOperation, addNodeOp, removeNodeOp, updateNodeOp, addRelationship
 // Conversion
 export { jsonToMarkdownSingle, jsonToMarkdownMultiDoc, jsonToMarkdown, } from "./json-to-md.js";
 export { markdownSingleToJson, markdownMultiDocToJson, markdownToJson, } from "./md-to-json.js";
+// Validation
+export { RELATIONSHIP_ENDPOINT_TYPES, isValidEndpointPair, } from "./endpoint-types.js";
 // Utilities
 export { canonicalise } from "./canonical-json.js";
 export { textToString, textToLines, textToMarkdown, markdownToText, } from "./text.js";

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

@@ -1,7 +1,7 @@
 import * as z from "zod";
 /**
  * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
- * @throws {Error} If either endpoint node does not exist in the document.
+ * @throws {Error} If either endpoint node does not exist, endpoint types are invalid, or the relationship is a duplicate.
  */
 export declare const addRelationshipOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

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

@@ -1,26 +1,38 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Relationship } from "../schema.js";
+import { isValidEndpointPair } from "../endpoint-types.js";
 /**
  * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
- * @throws {Error} If either endpoint node does not exist in the document.
+ * @throws {Error} If either endpoint node does not exist, endpoint types are invalid, or the relationship is a duplicate.
  */
 export const addRelationshipOp = defineOperation({
     name: "addRelationship",
-    description: "Add a relationship to the document. Throws if either endpoint node does not exist.",
+    description: "Add a relationship to the document. Throws if either endpoint node does not exist, endpoint types are invalid, or the relationship is a duplicate.",
     input: z.object({
         doc: SysProMDocument,
         rel: Relationship,
     }),
     output: SysProMDocument,
     fn({ doc, rel }) {
-        const ids = new Set(doc.nodes.map((n) => n.id));
-        if (!ids.has(rel.from)) {
+        const nodeMap = new Map(doc.nodes.map((n) => [n.id, n]));
+        const fromNode = nodeMap.get(rel.from);
+        const toNode = nodeMap.get(rel.to);
+        if (!fromNode) {
             throw new Error(`Node not found: ${rel.from}`);
         }
-        if (!ids.has(rel.to)) {
+        if (!toNode) {
             throw new Error(`Node not found: ${rel.to}`);
         }
+        // Validate endpoint types for this relationship
+        if (!isValidEndpointPair(rel.type, fromNode.type, toNode.type)) {
+            throw new Error(`Invalid endpoint types for ${rel.type}: ${fromNode.type} → ${toNode.type}`);
+        }
+        // Check for duplicate relationship
+        const isDuplicate = (doc.relationships ?? []).some((r) => r.from === rel.from && r.to === rel.to && r.type === rel.type);
+        if (isDuplicate) {
+            throw new Error(`Duplicate relationship already exists: ${rel.from} --${rel.type}--> ${rel.to}`);
+        }
         return {
             ...doc,
             relationships: [...(doc.relationships ?? []), rel],

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

@@ -302,7 +302,7 @@ export declare const RemoveResult: z.ZodObject<{
 export type RemoveResult = z.infer<typeof RemoveResult>;
 /**
  * Remove a node and all relationships involving it. Also removes the node from
- * view includes and external references. Warns if scope or operation references remain.
+ * view includes and external references. Cleans up scope and operation references.
  * @throws {Error} If the node ID is not found.
  */
 export declare const removeNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{

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

@@ -8,12 +8,12 @@ export const RemoveResult = z.object({
 });
 /**
  * Remove a node and all relationships involving it. Also removes the node from
- * view includes and external references. Warns if scope or operation references remain.
+ * view includes and external references. Cleans up scope and operation references.
  * @throws {Error} If the node ID is not found.
  */
 export const removeNodeOp = defineOperation({
     name: "removeNode",
-    description: "Remove a node and all relationships involving it. Also removes the node from view includes and external references.",
+    description: "Remove a node and all relationships involving it. Cleans up all references in scopes, operations, views, and external references.",
     input: z.object({
         doc: SysProMDocument,
         id: z.string(),
@@ -27,34 +27,50 @@ export const removeNodeOp = defineOperation({
         const warnings = [];
         // Remove the node
         const newNodes = doc.nodes.filter((n) => n.id !== id);
-        // Update view includes
-        const nodesWithIncludes = newNodes.map((n) => {
+        // Clean up all references to the removed node
+        const cleanedNodes = newNodes.map((n) => {
+            let updated = n;
+            // Remove from view includes
             if (n.includes?.includes(id)) {
                 const newIncludes = n.includes.filter((i) => i !== id);
-                return {
-                    ...n,
+                updated = {
+                    ...updated,
                     includes: newIncludes.length > 0 ? newIncludes : undefined,
                 };
             }
-            return n;
-        });
-        // Remove relationships involving this node
-        const newRelationships = (doc.relationships ?? []).filter((r) => r.from !== id && r.to !== id);
-        // Check for scope and operation references
-        for (const n of nodesWithIncludes) {
+            // Remove from scope
             if (n.scope?.includes(id)) {
+                const newScope = n.scope.filter((s) => s !== id);
                 warnings.push(`${n.id} scope still references ${id}`);
+                updated = {
+                    ...updated,
+                    scope: newScope.length > 0 ? newScope : undefined,
+                };
             }
-            if (n.operations?.some((op) => op.target === id)) {
+            // Remove from operations
+            const opsWithTarget = n.operations?.some((op) => op.target === id);
+            if (opsWithTarget) {
+                const newOps = n.operations?.filter((op) => op.target !== id);
                 warnings.push(`${n.id} operations still reference ${id}`);
+                updated = {
+                    ...updated,
+                    operations: newOps && newOps.length > 0 ? newOps : undefined,
+                };
             }
+            return updated;
+        });
+        // Remove relationships involving this node
+        const oldRelCount = (doc.relationships ?? []).length;
+        const newRelationships = (doc.relationships ?? []).filter((r) => r.from !== id && r.to !== id);
+        if (newRelationships.length < oldRelCount) {
+            warnings.push(`Removed relationships involving ${id}`);
         }
         // Remove from external references
         const newExternalRefs = (doc.external_references ?? []).filter((ref) => ref.node_id !== id);
         return {
             doc: {
                 ...doc,
-                nodes: nodesWithIncludes,
+                nodes: cleanedNodes,
                 relationships: newRelationships.length > 0 ? newRelationships : undefined,
                 external_references: newExternalRefs.length > 0 ? newExternalRefs : undefined,
             },

package/dist/src/operations/validate.js

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
+import { isValidEndpointPair } from "../endpoint-types.js";
 /** Zod schema for the result of validating a SysProM document. */
 export const ValidationResult = z.object({
     valid: z.boolean(),
@@ -49,6 +50,48 @@ export const validateOp = defineOperation({
                 issues.push(`Relationship references unknown target: ${r.to}`);
             }
         }
+        // Duplicate relationships
+        const relSet = new Set();
+        for (const r of input.doc.relationships ?? []) {
+            const key = `${r.from}:${r.type}:${r.to}`;
+            if (relSet.has(key)) {
+                issues.push(`Duplicate relationship: ${r.from} --${r.type}--> ${r.to}`);
+            }
+            relSet.add(key);
+        }
+        // Endpoint type validation
+        const nodeMap = new Map(input.doc.nodes.map((n) => [n.id, n]));
+        for (const r of input.doc.relationships ?? []) {
+            const fromNode = nodeMap.get(r.from);
+            const toNode = nodeMap.get(r.to);
+            if (fromNode &&
+                toNode &&
+                !isValidEndpointPair(r.type, fromNode.type, toNode.type)) {
+                issues.push(`Invalid endpoint types for ${r.type}: ${fromNode.type} → ${toNode.type} (${r.from} → ${r.to})`);
+            }
+        }
+        // Operational relationships to retired nodes
+        const OPERATIONAL_REL_TYPES = new Set([
+            "depends_on",
+            "constrained_by",
+            "requires",
+            "affects",
+            "must_preserve",
+            "performs",
+            "must_follow",
+            "part_of",
+            "governed_by",
+            "modifies",
+            "applies_to",
+            "produces",
+            "consumes",
+        ]);
+        for (const r of input.doc.relationships ?? []) {
+            const toNode = nodeMap.get(r.to);
+            if (toNode?.status === "retired" && OPERATIONAL_REL_TYPES.has(r.type)) {
+                issues.push(`Operational relationship ${r.type} targets retired node ${r.to}`);
+            }
+        }
         // INV2: Changes must reference at least one decision
         const decisionIds = new Set(input.doc.nodes.filter((n) => n.type === "decision").map((n) => n.id));
         for (const n of input.doc.nodes.filter((n) => n.type === "change")) {

package/package.json

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