sysprom 1.0.7 → 1.2.0

package/dist/src/operations/state-at.d.ts

@@ -1,10 +1,13 @@
 import * as z from "zod";
+/** Zod schema for a node's active lifecycle states at a point in time. */
 export declare const NodeState: z.ZodObject<{
     nodeId: z.ZodString;
     nodeName: z.ZodString;
     activeStates: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
+/** A node's active lifecycle states at a given point in time. */
 export type NodeState = z.infer<typeof NodeState>;
+/** Determine the active lifecycle states of all nodes at a specific point in time. Boolean lifecycle values are always included; ISO date values are included if they precede the query timestamp. */
 export declare const stateAtOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

package/dist/src/operations/state-at.js

@@ -1,11 +1,13 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
+/** Zod schema for a node's active lifecycle states at a point in time. */
 export const NodeState = z.object({
     nodeId: z.string(),
     nodeName: z.string(),
     activeStates: z.array(z.string()),
 });
+/** Determine the active lifecycle states of all nodes at a specific point in time. Boolean lifecycle values are always included; ISO date values are included if they precede the query timestamp. */
 export const stateAtOp = defineOperation({
     name: "state-at",
     description: "Determine the active states of all nodes at a specific point in time",

package/dist/src/operations/stats.d.ts

@@ -1,4 +1,5 @@
 import * as z from "zod";
+/** Zod schema for document statistics — node/relationship counts, subsystem depth, lifecycle breakdown. */
 export declare const DocumentStats: z.ZodObject<{
     title: z.ZodString;
     nodesByType: z.ZodRecord<z.ZodString, z.ZodNumber>;
@@ -12,7 +13,9 @@ export declare const DocumentStats: z.ZodObject<{
     decisionLifecycle: z.ZodRecord<z.ZodString, z.ZodNumber>;
     changeLifecycle: z.ZodRecord<z.ZodString, z.ZodNumber>;
 }, z.core.$strip>;
+/** Computed statistics about a SysProM document. */
 export type DocumentStats = z.infer<typeof DocumentStats>;
+/** Compute statistics about a SysProM document — node and relationship counts by type, subsystem depth, lifecycle breakdowns, and more. */
 export declare const statsOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

package/dist/src/operations/stats.js

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
+/** Zod schema for document statistics — node/relationship counts, subsystem depth, lifecycle breakdown. */
 export const DocumentStats = z.object({
     title: z.string(),
     nodesByType: z.record(z.string(), z.number()),
@@ -14,6 +15,7 @@ export const DocumentStats = z.object({
     decisionLifecycle: z.record(z.string(), z.number()),
     changeLifecycle: z.record(z.string(), z.number()),
 });
+/** Compute statistics about a SysProM document — node and relationship counts by type, subsystem depth, lifecycle breakdowns, and more. */
 export const statsOp = defineOperation({
     name: "stats",
     description: "Compute statistics about a SysProM document",

package/dist/src/operations/task-list.d.ts

@@ -1,4 +1,10 @@
 import * as z from "zod";
+/**
+ * List tasks across change nodes, optionally filtered by change ID and/or
+ * pending status. Returns a flat array of task rows tagged with their parent change node.
+ *
+ * @throws If a specific changeId is provided but not found.
+ */
 export declare const taskListOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

package/dist/src/operations/task-list.js

@@ -8,6 +8,12 @@ const TaskRow = z.object({
     description: z.string(),
     done: z.boolean(),
 });
+/**
+ * List tasks across change nodes, optionally filtered by change ID and/or
+ * pending status. Returns a flat array of task rows tagged with their parent change node.
+ *
+ * @throws If a specific changeId is provided but not found.
+ */
 export const taskListOp = defineOperation({
     name: "taskList",
     description: "List tasks across change nodes. Optionally filter by change ID and/or pending status.",

package/dist/src/operations/timeline.d.ts

@@ -1,4 +1,5 @@
 import * as z from "zod";
+/** Zod schema for a timestamped lifecycle event extracted from a node. */
 export declare const TimelineEvent: z.ZodObject<{
     nodeId: z.ZodString;
     nodeName: z.ZodString;
@@ -6,7 +7,9 @@ export declare const TimelineEvent: z.ZodObject<{
     state: z.ZodString;
     timestamp: z.ZodString;
 }, z.core.$strip>;
+/** A timestamped lifecycle event — when a node entered a particular state. */
 export type TimelineEvent = z.infer<typeof TimelineEvent>;
+/** Extract all timestamped lifecycle events from a document, sorted chronologically. Recursively includes subsystem events. */
 export declare const timelineOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

package/dist/src/operations/timeline.js

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
+/** Zod schema for a timestamped lifecycle event extracted from a node. */
 export const TimelineEvent = z.object({
     nodeId: z.string(),
     nodeName: z.string(),
@@ -8,6 +9,7 @@ export const TimelineEvent = z.object({
     state: z.string(),
     timestamp: z.string(),
 });
+/** Extract all timestamped lifecycle events from a document, sorted chronologically. Recursively includes subsystem events. */
 export const timelineOp = defineOperation({
     name: "timeline",
     description: "Extract all timestamped lifecycle events from a document, sorted chronologically",

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

@@ -298,6 +298,7 @@ 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<{
@@ -597,7 +598,9 @@ export declare const TraceNode: z.ZodObject<{
     }>;
     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. */
 export declare const traceFromNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

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

@@ -9,7 +9,9 @@ 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",
     description: "Trace refinement chain from a node (follows refines, realises, implements)",

package/dist/src/operations/update-metadata.d.ts

@@ -1,4 +1,5 @@
 import * as z from "zod";
+/** Update document-level metadata fields, merging the provided fields into the existing metadata. */
 export declare const updateMetadataOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

package/dist/src/operations/update-metadata.js

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
+/** Update document-level metadata fields, merging the provided fields into the existing metadata. */
 export const updateMetadataOp = defineOperation({
     name: "updateMetadata",
     description: "Update metadata fields. Returns a new document.",

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

@@ -1,4 +1,9 @@
 import * as z from "zod";
+/**
+ * Update specified fields on a node, merging the provided fields into the existing node.
+ *
+ * @throws If the node ID is not found.
+ */
 export declare const updateNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

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

@@ -1,6 +1,11 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Node } from "../schema.js";
+/**
+ * Update specified fields on a node, merging the provided fields into the existing node.
+ *
+ * @throws If the node ID is not found.
+ */
 export const updateNodeOp = defineOperation({
     name: "updateNode",
     description: "Update specified fields on a node. Throws if the node is not found.",

package/dist/src/operations/update-plan-task.d.ts

@@ -1,4 +1,9 @@
 import * as z from "zod";
+/**
+ * Set the done status of a task in a change node's plan array. Returns a new document.
+ *
+ * @throws If the change node is not found or the task index is out of range.
+ */
 export declare const updatePlanTaskOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

package/dist/src/operations/update-plan-task.js

@@ -1,6 +1,11 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
+/**
+ * Set the done status of a task in a change node's plan array. Returns a new document.
+ *
+ * @throws If the change node is not found or the task index is out of range.
+ */
 export const updatePlanTaskOp = defineOperation({
     name: "updatePlanTask",
     description: "Set the done status of a task in a change node's plan array. Returns a new document.",

package/dist/src/operations/validate.d.ts

@@ -1,11 +1,21 @@
 import * as z from "zod";
+/** Zod schema for the result of validating a SysProM document. */
 export declare const ValidationResult: z.ZodObject<{
     valid: z.ZodBoolean;
     issues: z.ZodArray<z.ZodString>;
     nodeCount: z.ZodNumber;
     relationshipCount: z.ZodNumber;
 }, z.core.$strip>;
+/** Result of document validation: validity flag, issues list, and counts. */
 export type ValidationResult = z.infer<typeof ValidationResult>;
+/**
+ * Validate a SysProM document for structural and semantic correctness.
+ *
+ * Checks for duplicate node IDs, dangling relationship endpoints, and
+ * invariant violations (INV2: changes must reference decisions, INV3:
+ * decisions affecting domain nodes must have must_preserve, INV13:
+ * decisions must have options and selected).
+ */
 export declare const validateOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

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";
+/** Zod schema for the result of validating a SysProM document. */
 export const ValidationResult = z.object({
     valid: z.boolean(),
     issues: z.array(z.string()),
@@ -14,6 +15,14 @@ const DOMAIN_TYPES = new Set([
     "element",
     "invariant",
 ]);
+/**
+ * Validate a SysProM document for structural and semantic correctness.
+ *
+ * Checks for duplicate node IDs, dangling relationship endpoints, and
+ * invariant violations (INV2: changes must reference decisions, INV3:
+ * decisions affecting domain nodes must have must_preserve, INV13:
+ * decisions must have options and selected).
+ */
 export const validateOp = defineOperation({
     name: "validate",
     description: "Validate a SysProM document for structural and semantic correctness",

package/dist/src/schema.d.ts

@@ -1,8 +1,14 @@
 import * as z from "zod";
+/**
+ * Zod schema for flexible text content — accepts either a single string or an
+ * array of lines. Includes a `.is()` type guard for runtime checks.
+ */
 export declare const Text: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
     is(value: unknown): value is string | string[];
 };
+/** A text value: either a single string or an array of lines. */
 export type Text = z.infer<typeof Text>;
+/** Zod schema for the set of valid node types (e.g. `"intent"`, `"decision"`, `"change"`). */
 export declare const NodeType: z.ZodEnum<{
     intent: "intent";
     concept: "concept";
@@ -27,7 +33,9 @@ export declare const NodeType: z.ZodEnum<{
 }> & {
     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";
 };
+/** A valid node type string. */
 export type NodeType = z.infer<typeof NodeType>;
+/** Map from node type key to its human-readable label (e.g. `intent` → `"Intent"`). */
 export declare const NODE_TYPE_LABELS: {
     readonly intent: "Intent";
     readonly concept: "Concepts";
@@ -50,8 +58,11 @@ export declare const NODE_TYPE_LABELS: {
     readonly milestone: "Milestones";
     readonly version: "Versions";
 };
+/** Reverse map from human-readable label to node type key (e.g. `"Intent"` → `"intent"`). */
 export declare const NODE_LABEL_TO_TYPE: Record<string, "intent" | "concept" | "capability" | "element" | "realisation" | "invariant" | "principle" | "policy" | "protocol" | "stage" | "role" | "gate" | "mode" | "artefact" | "artefact_flow" | "decision" | "change" | "view" | "milestone" | "version">;
+/** All valid node status values, ordered by typical lifecycle progression. */
 export declare const NODE_STATUSES: readonly ["proposed", "accepted", "active", "implemented", "adopted", "defined", "introduced", "in_progress", "complete", "consolidated", "experimental", "deprecated", "retired", "superseded", "abandoned", "deferred"];
+/** Zod schema for the set of valid node statuses (e.g. `"proposed"`, `"active"`, `"deprecated"`). */
 export declare const NodeStatus: z.ZodEnum<{
     deprecated: "deprecated";
     proposed: "proposed";
@@ -72,7 +83,9 @@ export declare const NodeStatus: z.ZodEnum<{
 }> & {
     is(value: unknown): value is "deprecated" | "proposed" | "accepted" | "active" | "implemented" | "adopted" | "defined" | "introduced" | "in_progress" | "complete" | "consolidated" | "experimental" | "retired" | "superseded" | "abandoned" | "deferred";
 };
+/** A valid node status string. */
 export type NodeStatus = z.infer<typeof NodeStatus>;
+/** Zod schema for the set of valid relationship types (e.g. `"refines"`, `"depends_on"`, `"affects"`). */
 export declare const RelationshipType: z.ZodEnum<{
     refines: "refines";
     realises: "realises";
@@ -101,7 +114,9 @@ export declare const RelationshipType: z.ZodEnum<{
 }> & {
     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";
 };
+/** A valid relationship type string. */
 export type RelationshipType = z.infer<typeof RelationshipType>;
+/** Map from relationship type key to its human-readable label (e.g. `refines` → `"Refines"`). */
 export declare const RELATIONSHIP_TYPE_LABELS: {
     readonly refines: "Refines";
     readonly realises: "Realises";
@@ -128,7 +143,9 @@ export declare const RELATIONSHIP_TYPE_LABELS: {
     readonly requires: "Requires";
     readonly disables: "Disables";
 };
+/** Reverse map from human-readable label to relationship type key (e.g. `"Refines"` → `"refines"`). */
 export declare const RELATIONSHIP_LABEL_TO_TYPE: Record<string, "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">;
+/** Zod schema for external reference roles (e.g. `"input"`, `"output"`, `"evidence"`). */
 export declare const ExternalReferenceRole: z.ZodEnum<{
     output: "output";
     input: "input";
@@ -140,7 +157,9 @@ export declare const ExternalReferenceRole: z.ZodEnum<{
 }> & {
     is(value: unknown): value is "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
 };
+/** A valid external reference role string. */
 export type ExternalReferenceRole = z.infer<typeof ExternalReferenceRole>;
+/** Map from external reference role key to its human-readable label. */
 export declare const EXTERNAL_REFERENCE_ROLE_LABELS: {
     readonly input: "Input";
     readonly output: "Output";
@@ -150,7 +169,9 @@ export declare const EXTERNAL_REFERENCE_ROLE_LABELS: {
     readonly standard: "Standard";
     readonly prior_art: "Prior art";
 };
+/** Reverse map from human-readable label to external reference role key. */
 export declare const EXTERNAL_REFERENCE_LABEL_TO_ROLE: Record<string, "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art">;
+/** Zod schema for a decision option — an alternative considered during a decision. */
 export declare const Option: z.ZodObject<{
     id: z.ZodString;
     description: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
@@ -163,7 +184,9 @@ export declare const Option: z.ZodObject<{
         description: string | string[];
     };
 };
+/** An alternative considered as part of a decision, with an ID and description. */
 export type Option = z.infer<typeof Option>;
+/** Zod schema for an atomic operation within a change (add, update, remove, or link). */
 export declare const Operation: z.ZodObject<{
     type: z.ZodEnum<{
         link: "link";
@@ -183,7 +206,9 @@ export declare const Operation: z.ZodObject<{
         description?: string | string[] | undefined;
     };
 };
+/** An atomic operation within a change, targeting a specific node. */
 export type Operation = z.infer<typeof Operation>;
+/** Zod schema for a task within a change's execution plan. */
 export declare const Task: z.ZodObject<{
     description: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
         is(value: unknown): value is string | string[];
@@ -196,7 +221,9 @@ export declare const Task: z.ZodObject<{
         done?: boolean | undefined;
     };
 };
+/** A single task within a change's execution plan, with a description and done flag. */
 export type Task = z.infer<typeof Task>;
+/** Zod schema for an external reference — a link to a resource outside the SysProM graph. */
 export declare const ExternalReference: z.ZodObject<{
     role: z.ZodEnum<{
         output: "output";
@@ -226,7 +253,9 @@ export declare const ExternalReference: z.ZodObject<{
         internalised?: string | string[] | undefined;
     };
 };
+/** A reference to a resource outside the SysProM graph (URI, file path, DOI, etc.). */
 export type ExternalReference = z.infer<typeof ExternalReference>;
+/** Zod schema for document-level metadata (title, scope, status, version). */
 export declare const Metadata: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     doc_type: z.ZodOptional<z.ZodString>;
@@ -243,7 +272,9 @@ export declare const Metadata: z.ZodObject<{
         version?: string | number | undefined;
     };
 };
+/** Document-level metadata — title, scope, status, and version. */
 export type Metadata = z.infer<typeof Metadata>;
+/** Zod schema for a typed, directed relationship between two nodes. */
 export declare const Relationship: z.ZodObject<{
     from: z.ZodString;
     to: z.ZodString;
@@ -287,6 +318,7 @@ export declare const Relationship: z.ZodObject<{
         description?: string | string[] | undefined;
     };
 };
+/** A typed, directed connection between two nodes, with from/to IDs and a relationship type. */
 export type Relationship = z.infer<typeof Relationship>;
 declare const SysProMDocumentSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
@@ -517,6 +549,11 @@ declare const NodeSchema: z.ZodObject<{
     }>>;
     readonly subsystem: z.ZodOptional<typeof SysProMDocumentSchema>;
 }, z.core.$loose>;
+/**
+ * Zod schema for a complete SysProM document — the root container holding
+ * nodes, relationships, external references, and metadata. Includes a `.is()`
+ * type guard for runtime validation.
+ */
 export declare const SysProMDocument: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodObject<{
@@ -676,7 +713,13 @@ export declare const SysProMDocument: z.ZodObject<{
         }[] | undefined;
     };
 };
+/** A complete SysProM document with metadata, nodes, relationships, and external references. */
 export type SysProMDocument = z.infer<typeof SysProMDocument>;
+/**
+ * Zod schema for a single node in the SysProM graph. Nodes are typed entities
+ * with optional lifecycle, decisions, operations, and recursive subsystems.
+ * Includes a `.is()` type guard for runtime validation.
+ */
 export declare const Node: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
@@ -881,6 +924,7 @@ export declare const Node: z.ZodObject<{
         } | undefined;
     };
 };
+/** A uniquely identifiable entity within the SysProM graph. */
 export type Node = z.infer<typeof Node>;
 /** Which node types belong in which document file. */
 export declare const NODE_FILE_MAP: Record<string, string[]>;

package/dist/src/schema.js

@@ -12,6 +12,10 @@ function defineSchema(schema) {
 // ---------------------------------------------------------------------------
 // Text type — allows a string or an array of lines
 // ---------------------------------------------------------------------------
+/**
+ * Zod schema for flexible text content — accepts either a single string or an
+ * array of lines. Includes a `.is()` type guard for runtime checks.
+ */
 export const Text = defineSchema(z.union([z.string(), z.array(z.string())]));
 // ---------------------------------------------------------------------------
 // Extensible string types
@@ -70,12 +74,16 @@ const nodeTypeDef = labelledEnum({
     milestone: "Milestones",
     version: "Versions",
 });
+/** Zod schema for the set of valid node types (e.g. `"intent"`, `"decision"`, `"change"`). */
 export const NodeType = nodeTypeDef.schema;
+/** Map from node type key to its human-readable label (e.g. `intent` → `"Intent"`). */
 export const NODE_TYPE_LABELS = nodeTypeDef.labels;
+/** Reverse map from human-readable label to node type key (e.g. `"Intent"` → `"intent"`). */
 export const NODE_LABEL_TO_TYPE = nodeTypeDef.reverse;
 // ---------------------------------------------------------------------------
 // Node statuses
 // ---------------------------------------------------------------------------
+/** All valid node status values, ordered by typical lifecycle progression. */
 export const NODE_STATUSES = [
     "proposed",
     "accepted",
@@ -94,6 +102,7 @@ export const NODE_STATUSES = [
     "abandoned",
     "deferred",
 ];
+/** Zod schema for the set of valid node statuses (e.g. `"proposed"`, `"active"`, `"deprecated"`). */
 export const NodeStatus = defineSchema(z.enum(NODE_STATUSES));
 // ---------------------------------------------------------------------------
 // Relationship types
@@ -124,8 +133,11 @@ const relationshipTypeDef = labelledEnum({
     requires: "Requires",
     disables: "Disables",
 });
+/** Zod schema for the set of valid relationship types (e.g. `"refines"`, `"depends_on"`, `"affects"`). */
 export const RelationshipType = relationshipTypeDef.schema;
+/** Map from relationship type key to its human-readable label (e.g. `refines` → `"Refines"`). */
 export const RELATIONSHIP_TYPE_LABELS = relationshipTypeDef.labels;
+/** Reverse map from human-readable label to relationship type key (e.g. `"Refines"` → `"refines"`). */
 export const RELATIONSHIP_LABEL_TO_TYPE = relationshipTypeDef.reverse;
 // ---------------------------------------------------------------------------
 // External reference roles
@@ -139,18 +151,23 @@ const externalReferenceRoleDef = labelledEnum({
     standard: "Standard",
     prior_art: "Prior art",
 });
+/** Zod schema for external reference roles (e.g. `"input"`, `"output"`, `"evidence"`). */
 export const ExternalReferenceRole = externalReferenceRoleDef.schema;
+/** Map from external reference role key to its human-readable label. */
 export const EXTERNAL_REFERENCE_ROLE_LABELS = externalReferenceRoleDef.labels;
+/** Reverse map from human-readable label to external reference role key. */
 export const EXTERNAL_REFERENCE_LABEL_TO_ROLE = externalReferenceRoleDef.reverse;
 // ---------------------------------------------------------------------------
 // Leaf schemas
 // ---------------------------------------------------------------------------
+/** Zod schema for a decision option — an alternative considered during a decision. */
 export const Option = defineSchema(z
     .looseObject({
     id: z.string(),
     description: Text,
 })
     .describe("An alternative considered as part of a decision."));
+/** Zod schema for an atomic operation within a change (add, update, remove, or link). */
 export const Operation = defineSchema(z
     .looseObject({
     type: z.enum(["add", "update", "remove", "link"]),
@@ -158,12 +175,14 @@ export const Operation = defineSchema(z
     description: Text.optional(),
 })
     .describe("An atomic operation within a change."));
+/** Zod schema for a task within a change's execution plan. */
 export const Task = defineSchema(z
     .looseObject({
     description: Text,
     done: z.boolean().default(false).optional(),
 })
     .describe("A single task within a change's execution plan."));
+/** Zod schema for an external reference — a link to a resource outside the SysProM graph. */
 export const ExternalReference = defineSchema(z
     .object({
     role: ExternalReferenceRole,
@@ -178,6 +197,7 @@ export const ExternalReference = defineSchema(z
     internalised: Text.describe("Inline content captured from the external resource. When present, the node is self-contained and does not depend on the external identifier being resolvable.").optional(),
 })
     .describe("A reference to a resource outside the SysProM graph."));
+/** Zod schema for document-level metadata (title, scope, status, version). */
 export const Metadata = defineSchema(z
     .looseObject({
     title: z.string().optional(),
@@ -193,6 +213,7 @@ export const Metadata = defineSchema(z
     version: z.union([z.string(), z.int()]).optional(),
 })
     .describe("Document-level metadata. Analogous to front matter in Markdown."));
+/** Zod schema for a typed, directed relationship between two nodes. */
 export const Relationship = defineSchema(z
     .looseObject({
     from: z.string().describe("Source node ID."),
@@ -288,7 +309,17 @@ const NodeSchema = z
 })
     .describe("A uniquely identifiable entity within the system.");
 // Attach .is() type guards after both schemas are declared
+/**
+ * Zod schema for a complete SysProM document — the root container holding
+ * nodes, relationships, external references, and metadata. Includes a `.is()`
+ * type guard for runtime validation.
+ */
 export const SysProMDocument = defineSchema(SysProMDocumentSchema);
+/**
+ * Zod schema for a single node in the SysProM graph. Nodes are typed entities
+ * with optional lifecycle, decisions, operations, and recursive subsystems.
+ * Includes a `.is()` type guard for runtime validation.
+ */
 export const Node = defineSchema(NodeSchema);
 // ---------------------------------------------------------------------------
 // Domain constants

package/dist/src/speckit/generate.d.ts

@@ -1,7 +1,13 @@
 import type { SysProMDocument } from "../schema.js";
+/** Generate a Spec-Kit constitution file from a SysProM document's principles and invariants. */
 export declare function generateConstitution(doc: SysProMDocument, prefix: string): string;
+/** Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria. */
 export declare function generateSpec(doc: SysProMDocument, prefix: string): string;
+/** Generate a Spec-Kit plan file from a SysProM document's phases and milestones. */
 export declare function generatePlan(doc: SysProMDocument, prefix: string): string;
+/** Generate a Spec-Kit tasks file from a SysProM document's change nodes. */
 export declare function generateTasks(doc: SysProMDocument, prefix: string): string;
+/** Generate a Spec-Kit checklist file from a SysProM document's gate nodes. */
 export declare function generateChecklist(doc: SysProMDocument, prefix: string): string;
+/** Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files. */
 export declare function generateSpecKitProject(doc: SysProMDocument, outputDir: string, prefix: string): void;

package/dist/src/speckit/generate.js

@@ -87,6 +87,7 @@ function formatStatus(status) {
 // ============================================================================
 // generate Constitution
 // ============================================================================
+/** Generate a Spec-Kit constitution file from a SysProM document's principles and invariants. */
 export function generateConstitution(doc, prefix) {
     const protocolId = `${prefix}-CONST`;
     const protocol = findNode(doc, protocolId);
@@ -159,6 +160,7 @@ export function generateConstitution(doc, prefix) {
 // ============================================================================
 // generateSpec
 // ============================================================================
+/** Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria. */
 export function generateSpec(doc, prefix) {
     const specId = `${prefix}-SPEC`;
     const spec = findNode(doc, specId);
@@ -272,6 +274,7 @@ export function generateSpec(doc, prefix) {
 // ============================================================================
 // generatePlan
 // ============================================================================
+/** Generate a Spec-Kit plan file from a SysProM document's phases and milestones. */
 export function generatePlan(doc, prefix) {
     const implProtocolId = `${prefix}-PROT-IMPL`;
     const protocol = findNode(doc, implProtocolId);
@@ -322,6 +325,7 @@ export function generatePlan(doc, prefix) {
 // ============================================================================
 // generateTasks
 // ============================================================================
+/** Generate a Spec-Kit tasks file from a SysProM document's change nodes. */
 export function generateTasks(doc, prefix) {
     const implProtocolId = `${prefix}-PROT-IMPL`;
     const protocol = findNode(doc, implProtocolId);
@@ -461,6 +465,7 @@ export function generateTasks(doc, prefix) {
 // ============================================================================
 // generateChecklist
 // ============================================================================
+/** Generate a Spec-Kit checklist file from a SysProM document's gate nodes. */
 export function generateChecklist(doc, prefix) {
     const gateId = `${prefix}-CHK`;
     const gate = findNode(doc, gateId);
@@ -515,6 +520,7 @@ export function generateChecklist(doc, prefix) {
 // ============================================================================
 // generateSpecKitProject
 // ============================================================================
+/** Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files. */
 export function generateSpecKitProject(doc, outputDir, prefix) {
     // Create output directory if it doesn't exist
     mkdirSync(outputDir, { recursive: true });

package/dist/src/speckit/parse.d.ts

@@ -1,11 +1,20 @@
 import type { SysProMDocument, Node, Relationship } from "../schema.js";
+/** Result of parsing a Spec-Kit file — extracted nodes and relationships. */
 export interface ParseResult {
+    /** Nodes extracted from the parsed content. */
     nodes: Node[];
+    /** Relationships extracted from the parsed content. */
     relationships: Relationship[];
 }
+/** Parse a Spec-Kit constitution file into SysProM nodes (principles and invariants) and relationships. */
 export declare function parseConstitution(content: string, idPrefix: string): ParseResult;
+/** Parse a Spec-Kit specification file into SysProM nodes (user stories, functional requirements, acceptance criteria). */
 export declare function parseSpec(content: string, idPrefix: string): ParseResult;
+/** Parse a Spec-Kit plan file into SysProM nodes (phases, milestones) and relationships. */
 export declare function parsePlan(content: string, idPrefix: string): ParseResult;
+/** Parse a Spec-Kit tasks file into SysProM change nodes with task plans. */
 export declare function parseTasks(content: string, idPrefix: string): ParseResult;
+/** Parse a Spec-Kit checklist file into SysProM gate nodes with task plans. */
 export declare function parseChecklist(content: string, idPrefix: string): ParseResult;
+/** Parse an entire Spec-Kit feature directory into a SysProM document, combining constitution, spec, plan, tasks, and checklist. */
 export declare function parseSpecKitFeature(featureDir: string, idPrefix: string, constitutionPath?: string): SysProMDocument;