sysprom 1.7.0 → 1.8.0

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

@@ -1,8 +1,3 @@
 import type { CommandDef } from "../define-command.js";
-import { noArgs } from "../shared.js";
-declare const optsSchema: import("zod").ZodObject<{
-    path: import("zod").ZodOptional<import("zod").ZodString>;
-    json: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodBoolean>>;
-}, import("zod/v4/core").$strip>;
-export declare const checkCommand: CommandDef<typeof noArgs, typeof optsSchema>;
-export {};
+import { noArgs, readOpts } from "../shared.js";
+export declare const checkCommand: CommandDef<typeof noArgs, typeof readOpts>;

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

@@ -1,11 +1,10 @@
 import { checkOp } from "../../operations/index.js";
 import { readOpts, loadDoc } from "../shared.js";
-const optsSchema = readOpts;
 export const checkCommand = {
     name: "check",
     description: checkOp.def.description,
     apiLink: checkOp.def.name,
-    opts: optsSchema,
+    opts: readOpts,
     action(_args, opts) {
         const { doc } = loadDoc(opts.path);
         const result = checkOp({ doc });

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

@@ -31,10 +31,8 @@ export const json2mdCommand = {
             throw new Error("Invalid args");
         if (!isOpts(opts))
             throw new Error("Invalid opts");
-        const typedArgs = args;
-        const typedOpts = opts;
-        const inputPath = resolve(typedArgs.input);
-        const outputPath = resolve(typedArgs.output);
+        const inputPath = resolve(args.input);
+        const outputPath = resolve(args.output);
         const raw = JSON.parse(readFileSync(inputPath, "utf8"));
         if (!SysProMDocument.is(raw)) {
             const result = SysProMDocument.safeParse(raw);
@@ -46,7 +44,7 @@ export const json2mdCommand = {
             }
             process.exit(1);
         }
-        const form = typedOpts.singleFile || outputPath.endsWith(".md")
+        const form = opts.singleFile || outputPath.endsWith(".md")
             ? "single-file"
             : "multi-doc";
         jsonToMarkdown(raw, outputPath, { form });

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

@@ -19,9 +19,8 @@ export const md2jsonCommand = {
     action(args) {
         if (!isArgs(args))
             throw new Error("Invalid args");
-        const typedArgs = args;
-        const inputPath = resolve(typedArgs.input);
-        const outputPath = resolve(typedArgs.output);
+        const inputPath = resolve(args.input);
+        const outputPath = resolve(args.output);
         const doc = markdownToJson(inputPath);
         writeFileSync(outputPath, canonicalise(doc, { indent: "\t" }) + "\n");
         console.log(`Written to ${outputPath}`);

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

@@ -72,7 +72,6 @@ const nodesOpts = readOpts.extend({
 const nodeArgs = z.object({
     id: z.string().describe("node ID to retrieve"),
 });
-const nodeOpts = readOpts;
 const relsOpts = readOpts.extend({
     from: z.string().optional().describe("filter relationships by source node"),
     to: z.string().optional().describe("filter relationships by target node"),
@@ -81,14 +80,12 @@ const relsOpts = readOpts.extend({
 const traceArgs = z.object({
     id: z.string().describe("node ID to start trace from"),
 });
-const traceOpts = readOpts;
 const timelineOpts = readOpts.extend({
     node: z.string().optional().describe("filter events to a specific node"),
 });
 const stateAtArgs = z.object({
     time: z.string().describe("ISO timestamp to query"),
 });
-const stateAtOpts = readOpts;
 // ---------------------------------------------------------------------------
 // Subcommands
 // ---------------------------------------------------------------------------
@@ -116,10 +113,10 @@ const nodeSubcommand = {
     description: queryNodeOp.def.description,
     apiLink: queryNodeOp.def.name,
     args: nodeArgs,
-    opts: nodeOpts,
+    opts: readOpts,
     action(rawArgs, rawOpts) {
         const args = nodeArgs.parse(rawArgs);
-        const opts = nodeOpts.parse(rawOpts);
+        const opts = readOpts.parse(rawOpts);
         const { doc } = loadDoc(opts.path);
         const result = queryNodeOp({ doc, id: args.id });
         if (!result) {
@@ -174,10 +171,10 @@ const traceSubcommand = {
     description: traceFromNodeOp.def.description,
     apiLink: traceFromNodeOp.def.name,
     args: traceArgs,
-    opts: traceOpts,
+    opts: readOpts,
     action(rawArgs, rawOpts) {
         const args = traceArgs.parse(rawArgs);
-        const opts = traceOpts.parse(rawOpts);
+        const opts = readOpts.parse(rawOpts);
         const { doc } = loadDoc(opts.path);
         const trace = traceFromNodeOp({ doc, startId: args.id });
         if (opts.json) {
@@ -219,10 +216,10 @@ const stateAtSubcommand = {
     description: stateAtOp.def.description,
     apiLink: stateAtOp.def.name,
     args: stateAtArgs,
-    opts: stateAtOpts,
+    opts: readOpts,
     action(rawArgs, rawOpts) {
         const args = stateAtArgs.parse(rawArgs);
-        const opts = stateAtOpts.parse(rawOpts);
+        const opts = readOpts.parse(rawOpts);
         const { doc } = loadDoc(opts.path);
         const result = stateAtOp({ doc, timestamp: args.time });
         if (opts.json) {

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

@@ -8,6 +8,9 @@ declare const optsSchema: z.ZodObject<{
     json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     sync: z.ZodOptional<z.ZodString>;
+    hard: z.ZodOptional<z.ZodBoolean>;
+    recursive: z.ZodOptional<z.ZodBoolean>;
+    repair: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const removeCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
 export {};

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

@@ -4,7 +4,11 @@ import { mutationOpts, loadDoc, persistDoc } from "../shared.js";
 const argsSchema = z.object({
     nodeId: z.string().describe("ID of the node to remove"),
 });
-const optsSchema = mutationOpts;
+const optsSchema = mutationOpts.extend({
+    hard: z.boolean().optional().describe("Hard delete (physical removal)"),
+    recursive: z.boolean().optional().describe("Allow subsystem removal"),
+    repair: z.boolean().optional().describe("Repair must_follow chains"),
+});
 export const removeCommand = {
     name: "remove",
     description: removeNodeOp.def.description,
@@ -17,7 +21,13 @@ export const removeCommand = {
         const targetId = args.nodeId;
         const removedNode = doc.nodes.find((n) => n.id === targetId);
         try {
-            const result = removeNodeOp({ doc, id: targetId });
+            const result = removeNodeOp({
+                doc,
+                id: targetId,
+                hard: opts.hard,
+                recursive: opts.recursive,
+                repair: opts.repair,
+            });
             // Count removed relationships
             const before = (doc.relationships ?? []).length;
             const after = (result.doc.relationships ?? []).length;

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

@@ -1,14 +1,9 @@
 import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
+import { mutationOpts } from "../shared.js";
 declare const argsSchema: z.ZodObject<{
     oldId: z.ZodString;
     newId: z.ZodString;
 }, z.core.$strip>;
-declare const optsSchema: z.ZodObject<{
-    path: z.ZodOptional<z.ZodString>;
-    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    sync: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare const renameCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+export declare const renameCommand: CommandDef<typeof argsSchema, typeof mutationOpts>;
 export {};

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

@@ -5,13 +5,12 @@ const argsSchema = z.object({
     oldId: z.string().describe("Current node ID"),
     newId: z.string().describe("New node ID"),
 });
-const optsSchema = mutationOpts;
 export const renameCommand = {
     name: "rename",
     description: renameOp.def.description,
     apiLink: renameOp.def.name,
     args: argsSchema,
-    opts: optsSchema,
+    opts: mutationOpts,
     action(args, opts) {
         try {
             const loaded = loadDoc(opts.path);

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

@@ -1,11 +1,8 @@
 import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
+import { readOpts } from "../shared.js";
 declare const argsSchema: z.ZodObject<{
     term: z.ZodString;
 }, z.core.$strip>;
-declare const optsSchema: z.ZodObject<{
-    path: z.ZodOptional<z.ZodString>;
-    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.core.$strip>;
-export declare const searchCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+export declare const searchCommand: CommandDef<typeof argsSchema, typeof readOpts>;
 export {};

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

@@ -5,13 +5,12 @@ import { textToString } from "../../text.js";
 const argsSchema = z.object({
     term: z.string().describe("Search term"),
 });
-const optsSchema = readOpts;
 export const searchCommand = {
     name: "search",
     description: searchOp.def.description,
     apiLink: searchOp.def.name,
     args: argsSchema,
-    opts: optsSchema,
+    opts: readOpts,
     action(args, opts) {
         const { doc } = loadDoc(opts.path);
         const matches = searchOp({ doc, term: args.term });

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

@@ -1,8 +1,3 @@
 import type { CommandDef } from "../define-command.js";
-import { noArgs } from "../shared.js";
-declare const optsSchema: import("zod").ZodObject<{
-    path: import("zod").ZodOptional<import("zod").ZodString>;
-    json: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodBoolean>>;
-}, import("zod/v4/core").$strip>;
-export declare const statsCommand: CommandDef<typeof noArgs, typeof optsSchema>;
-export {};
+import { noArgs, readOpts } from "../shared.js";
+export declare const statsCommand: CommandDef<typeof noArgs, typeof readOpts>;

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

@@ -1,12 +1,11 @@
 import pc from "picocolors";
 import { statsOp } from "../../operations/index.js";
 import { readOpts, loadDoc } from "../shared.js";
-const optsSchema = readOpts;
 export const statsCommand = {
     name: "stats",
     description: statsOp.def.description,
     apiLink: statsOp.def.name,
-    opts: optsSchema,
+    opts: readOpts,
     action(_args, opts) {
         const { doc } = loadDoc(opts.path);
         const s = statsOp({ doc });

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

@@ -42,13 +42,11 @@ const addRelArgs = z.object({
     type: RelationshipType.describe("relationship type"),
     to: z.string().describe("target node ID"),
 });
-const addRelOpts = mutationOpts;
 const removeRelArgs = z.object({
     from: z.string().describe("source node ID"),
     type: RelationshipType.describe("relationship type"),
     to: z.string().describe("target node ID"),
 });
-const removeRelOpts = mutationOpts;
 const metaOpts = mutationOpts.extend({
     fields: z
         .array(z.string())
@@ -116,10 +114,10 @@ const addRelSubcommand = {
     description: addRelationshipOp.def.description,
     apiLink: addRelationshipOp.def.name,
     args: addRelArgs,
-    opts: addRelOpts,
+    opts: mutationOpts,
     action(rawArgs, rawOpts) {
         const args = addRelArgs.parse(rawArgs);
-        const opts = addRelOpts.parse(rawOpts);
+        const opts = mutationOpts.parse(rawOpts);
         const loaded = loadDoc(opts.path);
         const { doc } = loaded;
         const newDoc = addRelationshipOp({
@@ -141,10 +139,10 @@ const removeRelSubcommand = {
     description: removeRelationshipOp.def.description,
     apiLink: removeRelationshipOp.def.name,
     args: removeRelArgs,
-    opts: removeRelOpts,
+    opts: mutationOpts,
     action(rawArgs, rawOpts) {
         const args = removeRelArgs.parse(rawArgs);
-        const opts = removeRelOpts.parse(rawOpts);
+        const opts = mutationOpts.parse(rawOpts);
         const loaded = loadDoc(opts.path);
         const { doc } = loaded;
         const result = removeRelationshipOp({

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

@@ -1,8 +1,3 @@
 import type { CommandDef } from "../define-command.js";
-import { noArgs } from "../shared.js";
-declare const optsSchema: import("zod").ZodObject<{
-    path: import("zod").ZodOptional<import("zod").ZodString>;
-    json: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodBoolean>>;
-}, import("zod/v4/core").$strip>;
-export declare const validateCommand: CommandDef<typeof noArgs, typeof optsSchema>;
-export {};
+import { noArgs, readOpts } from "../shared.js";
+export declare const validateCommand: CommandDef<typeof noArgs, typeof readOpts>;

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

@@ -1,12 +1,11 @@
 import pc from "picocolors";
 import { validateOp } from "../../operations/index.js";
 import { readOpts, loadDoc } from "../shared.js";
-const optsSchema = readOpts;
 export const validateCommand = {
     name: "validate",
     description: validateOp.def.description,
     apiLink: validateOp.def.name,
-    opts: optsSchema,
+    opts: readOpts,
     action(_args, opts) {
         const { doc } = loadDoc(opts.path);
         const result = validateOp({ doc });

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

@@ -12,9 +12,13 @@ export declare const RELATIONSHIP_ENDPOINT_TYPES: Record<RelationshipType, {
 }>;
 /**
  * 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
+ * @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
+ * @example
+ * ```ts
+ * isValidEndpointPair("refines", "intent", "concept") // true
+ * ```
  */
 export declare function isValidEndpointPair(relType: RelationshipType, fromType: NodeType, toType: NodeType): boolean;

package/dist/src/endpoint-types.js

@@ -288,16 +288,16 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
 };
 /**
  * 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
+ * @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
+ * @example
+ * ```ts
+ * isValidEndpointPair("refines", "intent", "concept") // true
+ * ```
  */
 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));
+    return endpoints.from.includes(fromType) && endpoints.to.includes(toType);
 }

package/dist/src/json-to-md.js

@@ -467,12 +467,11 @@ export function jsonToMarkdownMultiDoc(doc, outDir) {
             .replace(/[^a-z0-9]+/g, "-")
             .replace(/-$/, "")}`;
         // Auto-group when 2+ subsystems share the same type
-        let parentDir = outDir;
-        if ((typeCounts.get(n.type) ?? 0) >= 2 && NodeType.is(n.type)) {
-            const groupLabel = NODE_TYPE_LABELS[n.type]
-                .toLowerCase()
-                .replace(/ /g, "-");
-            parentDir = join(outDir, groupLabel);
+        const shouldGroup = (typeCounts.get(n.type) ?? 0) >= 2 && NodeType.is(n.type);
+        const parentDir = shouldGroup
+            ? join(outDir, NODE_TYPE_LABELS[n.type].toLowerCase().replace(/ /g, "-"))
+            : outDir;
+        if (shouldGroup) {
             mkdirSync(parentDir, { recursive: true });
         }
         if (fileCounts <= 1) {

package/dist/src/md-to-json.js

@@ -35,7 +35,15 @@ function parseText(raw) {
     const lines = raw.split("\n");
     return lines.length === 1 ? lines[0] : lines;
 }
-/** Separate $schema from front matter so it becomes a top-level document key. */
+/**
+ * Separate $schema from front matter so it becomes a top-level document key.
+ * @param front - The front matter object
+ * @returns An object with extracted schema and remaining metadata
+ * @example
+ * ```ts
+ * const { schema, metadata } = extractSchema({ $schema: "...", foo: "bar" });
+ * ```
+ */
 function extractSchema(front) {
     const schema = typeof front.$schema === "string" ? front.$schema : undefined;
     const metadata = { ...front };

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

@@ -83,35 +83,26 @@ export const removeNodeOp = defineOperation({
         }
         // Clean up all references to the removed node (both soft and hard)
         const cleanedNodes = newNodes.map((n) => {
-            let updated = n;
+            const updates = {};
             // Remove from view includes
             if (n.includes?.includes(id)) {
                 const newIncludes = n.includes.filter((i) => i !== id);
-                updated = {
-                    ...updated,
-                    includes: newIncludes.length > 0 ? newIncludes : undefined,
-                };
+                updates.includes = newIncludes.length > 0 ? newIncludes : undefined;
             }
             // 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,
-                };
+                updates.scope = newScope.length > 0 ? newScope : undefined;
             }
             // 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,
-                };
+                updates.operations = (newOps?.length ?? 0) > 0 ? newOps : undefined;
             }
-            return updated;
+            return Object.keys(updates).length > 0 ? { ...n, ...updates } : n;
         });
         // Remove from external references
         const newExternalRefs = (doc.external_references ?? []).filter((ref) => ref.node_id !== id);

package/dist/src/operations/trace-from-node.d.ts

@@ -298,306 +298,6 @@ declare const TraceNodeSchema: z.ZodObject<{
     }>;
     children: z.ZodArray<typeof TraceNodeSchema>;
 }, z.core.$strip>;
-/** Zod schema for a node in the refinement trace tree. */
-export declare const TraceNode: z.ZodObject<{
-    id: z.ZodString;
-    node: z.ZodOptional<z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodEnum<{
-            intent: "intent";
-            concept: "concept";
-            capability: "capability";
-            element: "element";
-            realisation: "realisation";
-            invariant: "invariant";
-            principle: "principle";
-            policy: "policy";
-            protocol: "protocol";
-            stage: "stage";
-            role: "role";
-            gate: "gate";
-            mode: "mode";
-            artefact: "artefact";
-            artefact_flow: "artefact_flow";
-            decision: "decision";
-            change: "change";
-            view: "view";
-            milestone: "milestone";
-            version: "version";
-        }> & {
-            is(value: unknown): value is "intent" | "concept" | "capability" | "element" | "realisation" | "invariant" | "principle" | "policy" | "protocol" | "stage" | "role" | "gate" | "mode" | "artefact" | "artefact_flow" | "decision" | "change" | "view" | "milestone" | "version";
-        };
-        name: z.ZodString;
-        description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-            is(value: unknown): value is string | string[];
-        }>;
-        status: z.ZodOptional<z.ZodEnum<{
-            deprecated: "deprecated";
-            proposed: "proposed";
-            accepted: "accepted";
-            active: "active";
-            implemented: "implemented";
-            adopted: "adopted";
-            defined: "defined";
-            introduced: "introduced";
-            in_progress: "in_progress";
-            complete: "complete";
-            consolidated: "consolidated";
-            experimental: "experimental";
-            retired: "retired";
-            superseded: "superseded";
-            abandoned: "abandoned";
-            deferred: "deferred";
-        }> & {
-            is(value: unknown): value is "deprecated" | "proposed" | "accepted" | "active" | "implemented" | "adopted" | "defined" | "introduced" | "in_progress" | "complete" | "consolidated" | "experimental" | "retired" | "superseded" | "abandoned" | "deferred";
-        }>;
-        lifecycle: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
-        context: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-            is(value: unknown): value is string | string[];
-        }>;
-        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            description: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-                is(value: unknown): value is string | string[];
-            };
-        }, z.core.$loose> & {
-            is(value: unknown): value is {
-                [x: string]: unknown;
-                id: string;
-                description: string | string[];
-            };
-        }>>;
-        selected: z.ZodOptional<z.ZodString>;
-        rationale: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-            is(value: unknown): value is string | string[];
-        }>;
-        scope: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        operations: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            type: z.ZodEnum<{
-                link: "link";
-                add: "add";
-                update: "update";
-                remove: "remove";
-            }>;
-            target: z.ZodOptional<z.ZodString>;
-            description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-                is(value: unknown): value is string | string[];
-            }>;
-        }, z.core.$loose> & {
-            is(value: unknown): value is {
-                [x: string]: unknown;
-                type: "link" | "add" | "update" | "remove";
-                target?: string | undefined;
-                description?: string | string[] | undefined;
-            };
-        }>>;
-        plan: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            description: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-                is(value: unknown): value is string | string[];
-            };
-            done: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        }, z.core.$loose> & {
-            is(value: unknown): value is {
-                [x: string]: unknown;
-                description: string | string[];
-                done?: boolean | undefined;
-            };
-        }>>;
-        propagation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
-        includes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        input: z.ZodOptional<z.ZodString>;
-        output: z.ZodOptional<z.ZodString>;
-        external_references: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            role: z.ZodEnum<{
-                output: "output";
-                input: "input";
-                context: "context";
-                evidence: "evidence";
-                source: "source";
-                standard: "standard";
-                prior_art: "prior_art";
-            }> & {
-                is(value: unknown): value is "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
-            };
-            identifier: z.ZodString;
-            description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-                is(value: unknown): value is string | string[];
-            }>;
-            node_id: z.ZodOptional<z.ZodString>;
-            internalised: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-                is(value: unknown): value is string | string[];
-            }>;
-        }, z.core.$strip> & {
-            is(value: unknown): value is {
-                role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
-                identifier: string;
-                description?: string | string[] | undefined;
-                node_id?: string | undefined;
-                internalised?: string | string[] | undefined;
-            };
-        }>>;
-        readonly subsystem: z.ZodOptional<z.ZodObject<{
-            $schema: z.ZodOptional<z.ZodString>;
-            metadata: z.ZodOptional<z.ZodObject<{
-                title: z.ZodOptional<z.ZodString>;
-                doc_type: z.ZodOptional<z.ZodString>;
-                scope: z.ZodOptional<z.ZodString>;
-                status: z.ZodOptional<z.ZodString>;
-                version: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
-            }, z.core.$loose> & {
-                is(value: unknown): value is {
-                    [x: string]: unknown;
-                    title?: string | undefined;
-                    doc_type?: string | undefined;
-                    scope?: string | undefined;
-                    status?: string | undefined;
-                    version?: string | number | undefined;
-                };
-            }>;
-            nodes: z.ZodArray<z.ZodObject</*elided*/ any, z.core.$loose>>;
-            relationships: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                from: z.ZodString;
-                to: z.ZodString;
-                type: z.ZodEnum<{
-                    refines: "refines";
-                    realises: "realises";
-                    implements: "implements";
-                    depends_on: "depends_on";
-                    constrained_by: "constrained_by";
-                    affects: "affects";
-                    supersedes: "supersedes";
-                    must_preserve: "must_preserve";
-                    performs: "performs";
-                    part_of: "part_of";
-                    precedes: "precedes";
-                    must_follow: "must_follow";
-                    blocks: "blocks";
-                    routes_to: "routes_to";
-                    governed_by: "governed_by";
-                    modifies: "modifies";
-                    triggered_by: "triggered_by";
-                    applies_to: "applies_to";
-                    produces: "produces";
-                    consumes: "consumes";
-                    transforms_into: "transforms_into";
-                    selects: "selects";
-                    requires: "requires";
-                    disables: "disables";
-                }> & {
-                    is(value: unknown): value is "refines" | "realises" | "implements" | "depends_on" | "constrained_by" | "affects" | "supersedes" | "must_preserve" | "performs" | "part_of" | "precedes" | "must_follow" | "blocks" | "routes_to" | "governed_by" | "modifies" | "triggered_by" | "applies_to" | "produces" | "consumes" | "transforms_into" | "selects" | "requires" | "disables";
-                };
-                description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-                    is(value: unknown): value is string | string[];
-                }>;
-            }, z.core.$loose> & {
-                is(value: unknown): value is {
-                    [x: string]: unknown;
-                    from: string;
-                    to: string;
-                    type: "refines" | "realises" | "implements" | "depends_on" | "constrained_by" | "affects" | "supersedes" | "must_preserve" | "performs" | "part_of" | "precedes" | "must_follow" | "blocks" | "routes_to" | "governed_by" | "modifies" | "triggered_by" | "applies_to" | "produces" | "consumes" | "transforms_into" | "selects" | "requires" | "disables";
-                    description?: string | string[] | undefined;
-                };
-            }>>;
-            external_references: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                role: z.ZodEnum<{
-                    output: "output";
-                    input: "input";
-                    context: "context";
-                    evidence: "evidence";
-                    source: "source";
-                    standard: "standard";
-                    prior_art: "prior_art";
-                }> & {
-                    is(value: unknown): value is "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
-                };
-                identifier: z.ZodString;
-                description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-                    is(value: unknown): value is string | string[];
-                }>;
-                node_id: z.ZodOptional<z.ZodString>;
-                internalised: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
-                    is(value: unknown): value is string | string[];
-                }>;
-            }, z.core.$strip> & {
-                is(value: unknown): value is {
-                    role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
-                    identifier: string;
-                    description?: string | string[] | undefined;
-                    node_id?: string | undefined;
-                    internalised?: string | string[] | undefined;
-                };
-            }>>;
-        }, z.core.$strip>>;
-    }, z.core.$loose> & {
-        is(value: unknown): value is {
-            [x: string]: unknown;
-            id: string;
-            type: "intent" | "concept" | "capability" | "element" | "realisation" | "invariant" | "principle" | "policy" | "protocol" | "stage" | "role" | "gate" | "mode" | "artefact" | "artefact_flow" | "decision" | "change" | "view" | "milestone" | "version";
-            name: string;
-            description?: string | string[] | undefined;
-            status?: "deprecated" | "proposed" | "accepted" | "active" | "implemented" | "adopted" | "defined" | "introduced" | "in_progress" | "complete" | "consolidated" | "experimental" | "retired" | "superseded" | "abandoned" | "deferred" | undefined;
-            lifecycle?: Record<string, string | boolean> | undefined;
-            context?: string | string[] | undefined;
-            options?: {
-                [x: string]: unknown;
-                id: string;
-                description: string | string[];
-            }[] | undefined;
-            selected?: string | undefined;
-            rationale?: string | string[] | undefined;
-            scope?: string[] | undefined;
-            operations?: {
-                [x: string]: unknown;
-                type: "link" | "add" | "update" | "remove";
-                target?: string | undefined;
-                description?: string | string[] | undefined;
-            }[] | undefined;
-            plan?: {
-                [x: string]: unknown;
-                description: string | string[];
-                done?: boolean | undefined;
-            }[] | undefined;
-            propagation?: Record<string, boolean> | undefined;
-            includes?: string[] | undefined;
-            input?: string | undefined;
-            output?: string | undefined;
-            external_references?: {
-                role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
-                identifier: string;
-                description?: string | string[] | undefined;
-                node_id?: string | undefined;
-                internalised?: string | string[] | undefined;
-            }[] | undefined;
-            subsystem?: {
-                nodes: /*elided*/ any[];
-                $schema?: string | undefined;
-                metadata?: {
-                    [x: string]: unknown;
-                    title?: string | undefined;
-                    doc_type?: string | undefined;
-                    scope?: string | undefined;
-                    status?: string | undefined;
-                    version?: string | number | undefined;
-                } | undefined;
-                relationships?: {
-                    [x: string]: unknown;
-                    from: string;
-                    to: string;
-                    type: "refines" | "realises" | "implements" | "depends_on" | "constrained_by" | "affects" | "supersedes" | "must_preserve" | "performs" | "part_of" | "precedes" | "must_follow" | "blocks" | "routes_to" | "governed_by" | "modifies" | "triggered_by" | "applies_to" | "produces" | "consumes" | "transforms_into" | "selects" | "requires" | "disables";
-                    description?: string | string[] | undefined;
-                }[] | undefined;
-                external_references?: {
-                    role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
-                    identifier: string;
-                    description?: string | string[] | undefined;
-                    node_id?: string | undefined;
-                    internalised?: string | string[] | undefined;
-                }[] | undefined;
-            } | undefined;
-        };
-    }>;
-    children: z.ZodArray<typeof TraceNodeSchema>;
-}, z.core.$strip>;
 /** A node in the refinement trace tree, with optional children that refine/realise/implement it. */
 export type TraceNode = z.infer<typeof TraceNodeSchema>;
 /** Trace the refinement chain from a node, following `refines`, `realises`, and `implements` relationships recursively. */

package/dist/src/operations/trace-from-node.js

@@ -9,8 +9,6 @@ const TraceNodeSchema = z.object({
         return z.array(TraceNodeSchema);
     },
 });
-/** Zod schema for a node in the refinement trace tree. */
-export const TraceNode = TraceNodeSchema;
 /** Trace the refinement chain from a node, following `refines`, `realises`, and `implements` relationships recursively. */
 export const traceFromNodeOp = defineOperation({
     name: "trace-from-node",
@@ -19,7 +17,7 @@ export const traceFromNodeOp = defineOperation({
         doc: SysProMDocument,
         startId: z.string(),
     }),
-    output: TraceNode,
+    output: TraceNodeSchema,
     fn: (input) => {
         const visited = new Set();
         function trace(id) {

package/dist/src/sync.d.ts

@@ -12,15 +12,18 @@ export interface DetectionResult {
 /**
  * Detect whether JSON and/or Markdown have changed.
  * Strategy:
- * 1. Parse both JSON and Markdown to document objects
- * 2. If documents are identical → no change
- * 3. If documents differ:
- *    - Use file modification times to determine which was edited more recently
- *    - The newer file is considered the "changed" one
- *    - If modification times are very close (< 100ms), treat as conflict
- *
- * @param jsonPath Path to JSON file
- * @param mdPath Path to Markdown file (single or multi-doc)
+ * 1. Parse both JSON and Markdown to document objects.
+ * 2. If documents are identical, no change.
+ * 3. If documents differ, use file modification times to determine which was
+ *    edited more recently. The newer file is considered the "changed" one.
+ *    If modification times are very close (< 100ms), treat as conflict.
+ * @param jsonPath - Path to JSON file
+ * @param mdPath - Path to Markdown file (single or multi-doc)
  * @returns Detection result with jsonChanged, mdChanged, and conflict flags
+ * @example
+ * ```ts
+ * const result = detectChanges("doc.spm.json", "doc.spm.md");
+ * if (result.conflict) throw new Error("Both files changed");
+ * ```
  */
 export declare function detectChanges(jsonPath: string, mdPath: string): DetectionResult;

package/dist/src/sync.js

@@ -5,31 +5,38 @@ import { SysProMDocument } from "./schema.js";
 /**
  * Compute a normalised hash of a document for comparison.
  * Uses canonical JSON representation.
- * @param doc The SysProM document
+ * @param doc - The SysProM document
  * @returns SHA256 hash of the canonicalised document
+ * @example
+ * ```ts
+ * const hash = normaliseHash({ nodes: [], relationships: [] });
+ * ```
  */
 function normaliseHash(doc) {
-    const sorted = JSON.stringify(doc, Object.keys(doc).sort());
+    const keys = doc && typeof doc === "object" ? Object.keys(doc).sort() : [];
+    const sorted = JSON.stringify(doc, keys);
     return createHash("sha256").update(sorted).digest("hex");
 }
 /**
  * Detect whether JSON and/or Markdown have changed.
  * Strategy:
- * 1. Parse both JSON and Markdown to document objects
- * 2. If documents are identical → no change
- * 3. If documents differ:
- *    - Use file modification times to determine which was edited more recently
- *    - The newer file is considered the "changed" one
- *    - If modification times are very close (< 100ms), treat as conflict
- *
- * @param jsonPath Path to JSON file
- * @param mdPath Path to Markdown file (single or multi-doc)
+ * 1. Parse both JSON and Markdown to document objects.
+ * 2. If documents are identical, no change.
+ * 3. If documents differ, use file modification times to determine which was
+ *    edited more recently. The newer file is considered the "changed" one.
+ *    If modification times are very close (< 100ms), treat as conflict.
+ * @param jsonPath - Path to JSON file
+ * @param mdPath - Path to Markdown file (single or multi-doc)
  * @returns Detection result with jsonChanged, mdChanged, and conflict flags
+ * @example
+ * ```ts
+ * const result = detectChanges("doc.spm.json", "doc.spm.md");
+ * if (result.conflict) throw new Error("Both files changed");
+ * ```
  */
 export function detectChanges(jsonPath, mdPath) {
     // Read files
     const jsonContent = readFileSync(jsonPath, "utf8");
-    const mdContent = readFileSync(mdPath, "utf8");
     // Parse JSON
     const jsonDoc = JSON.parse(jsonContent);
     if (!SysProMDocument.is(jsonDoc)) {

package/package.json

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