@mplp/sdk-ts 1.0.1 → 1.0.3

package/schemas/common/common-types.schema.json

@@ -0,0 +1,55 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$id": "https://schemas.mplp.dev/v1.0/common/common-types.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MPLP Common Types",
+  "description": "Common type definitions used across MPLP modules to ensure consistency and reduce duplication.",
+  "definitions": {
+    "MplpId": {
+      "$ref": "identifiers.schema.json"
+    },
+    "Ref": {
+      "type": "object",
+      "description": "A standard reference to another MPLP object.",
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/MplpId"
+        },
+        "module": {
+          "type": "string",
+          "enum": [
+            "context",
+            "plan",
+            "confirm",
+            "trace",
+            "role",
+            "extension",
+            "dialog",
+            "collab",
+            "core",
+            "network"
+          ],
+          "description": "The module name of the referenced object."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional description of the reference relationship."
+        }
+      },
+      "required": [
+        "id",
+        "module"
+      ],
+      "additionalProperties": false
+    },
+    "BaseMeta": {
+      "$ref": "metadata.schema.json"
+    }
+  },
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/common/events.schema.json

@@ -0,0 +1,72 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$id": "https://schemas.mplp.dev/v1.0/common/events.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MPLP Base Event",
+  "description": "Base model for all event structures in MPLP. Designed based on CloudEvents v1.0 core fields, providing unified event identification, type, source, and timestamp. ExecutionEvent, StateTransitionEvent, etc., are extensions of this.",
+  "type": "object",
+  "properties": {
+    "event_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Unique identifier for the event (UUID v4)."
+    },
+    "event_type": {
+      "type": "string",
+      "description": "Event type identifier, e.g., execution.started / vsl.transition.applied / plan.created. Uses dot-separated namespace format.",
+      "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)*$",
+      "examples": [
+        "execution.started",
+        "execution.completed",
+        "vsl.transition.applied",
+        "plan.created"
+      ]
+    },
+    "source": {
+      "type": "string",
+      "description": "Event source, typically a module or component identifier. Can be a module name (e.g., 'context') or component path (e.g., 'runtime.ael').",
+      "examples": [
+        "context",
+        "plan",
+        "runtime.ael",
+        "runtime.vsl"
+      ]
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Event occurrence time (ISO 8601 format).",
+      "examples": [
+        "2025-01-28T15:30:00.000Z"
+      ]
+    },
+    "trace_id": {
+      "description": "Optional trace ID to associate the event with a specific Trace.",
+      "$ref": "identifiers.schema.json"
+    },
+    "data": {
+      "anyOf": [
+        {
+          "type": "object",
+          "description": "Business data related to the event, constrained by upper-layer structures. Can be any JSON object or null."
+        },
+        {
+          "type": "null",
+          "description": "Business data related to the event, constrained by upper-layer structures. Can be any JSON object or null."
+        }
+      ]
+    }
+  },
+  "required": [
+    "event_id",
+    "event_type",
+    "source",
+    "timestamp"
+  ],
+  "additionalProperties": false,
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/common/identifiers.schema.json

@@ -0,0 +1,19 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$id": "https://schemas.mplp.dev/v1.0/common/identifiers.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MPLP Identifier",
+  "description": "Unified identifier type used for contextId/planId/traceId/eventId, etc. Uses UUID v4 standard to ensure global uniqueness and collision-free generation in distributed environments.",
+  "type": "string",
+  "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+  "examples": [
+    "123e4567-e89b-12d3-a456-426614174000",
+    "550e8400-e29b-41d4-a716-446655440000"
+  ],
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/common/learning-sample.schema.json

@@ -0,0 +1,200 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.mplp.dev/v1.0/common/learning-sample.schema.json",
+  "title": "MPLP Learning Sample – Schema v2.0",
+  "description": "Structured learning sample for MPLP v1.0 runtimes.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "sample_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Unique identifier for this learning sample."
+    },
+    "project_id": {
+      "type": "string",
+      "description": "Project identifier this sample belongs to."
+    },
+    "intent_before": {
+      "type": "object",
+      "description": "Structured representation of the original intent (can reference Context/Plan).",
+      "additionalProperties": true
+    },
+    "plan": {
+      "type": "object",
+      "description": "Structured representation of the plan used (can reference Plan module).",
+      "additionalProperties": true
+    },
+    "delta_intents": {
+      "type": "array",
+      "description": "Array of delta intents proposed/applied.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    },
+    "graph_before": {
+      "type": "object",
+      "description": "Optional snapshot or summary of the knowledge graph before the change.",
+      "additionalProperties": true
+    },
+    "graph_after": {
+      "type": "object",
+      "description": "Optional snapshot or summary of the knowledge graph after the change.",
+      "additionalProperties": true
+    },
+    "pipeline_path": {
+      "type": "array",
+      "description": "Sequence of pipeline stages traversed.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "success_flag": {
+      "type": "boolean",
+      "description": "Whether the action/intent succeeded."
+    },
+    "error_info": {
+      "type": "object",
+      "description": "Error details if action failed.",
+      "additionalProperties": false,
+      "properties": {
+        "error_code": {
+          "type": "string"
+        },
+        "error_message": {
+          "type": "string"
+        },
+        "stack_trace": {
+          "type": "string"
+        }
+      }
+    },
+    "token_usage": {
+      "type": "object",
+      "description": "LLM token consumption metrics.",
+      "additionalProperties": false,
+      "properties": {
+        "total_tokens": {
+          "type": "number",
+          "minimum": 0
+        },
+        "prompt_tokens": {
+          "type": "number",
+          "minimum": 0
+        },
+        "completion_tokens": {
+          "type": "number",
+          "minimum": 0
+        },
+        "by_agent": {
+          "type": "array",
+          "description": "Token usage breakdown by agent.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "agent_id": {
+                "type": "string"
+              },
+              "role": {
+                "type": "string"
+              },
+              "tokens": {
+                "type": "number",
+                "minimum": 0
+              }
+            },
+            "required": [
+              "agent_id",
+              "tokens"
+            ]
+          }
+        }
+      }
+    },
+    "execution_time_ms": {
+      "type": "number",
+      "description": "Execution time in milliseconds.",
+      "minimum": 0
+    },
+    "impact_score": {
+      "type": "number",
+      "description": "Impact score (0.0-1.0).",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "user_feedback": {
+      "type": "object",
+      "description": "Human feedback on the action/result.",
+      "additionalProperties": false,
+      "properties": {
+        "decision": {
+          "type": "string",
+          "enum": [
+            "approve",
+            "reject",
+            "override",
+            "unknown"
+          ]
+        },
+        "comment": {
+          "type": "string"
+        },
+        "rating": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 5
+        }
+      }
+    },
+    "governance_decisions": {
+      "type": "array",
+      "description": "Governance rules evaluated during execution.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    },
+    "timestamps": {
+      "type": "object",
+      "description": "Execution timeline.",
+      "additionalProperties": false,
+      "properties": {
+        "started_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "completed_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "required": [
+        "started_at"
+      ]
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional metadata (extensibility point).",
+      "additionalProperties": true
+    },
+    "vendor_extensions": {
+      "type": "object",
+      "description": "Optional vendor-specific extensions. Structure is implementation-defined and MUST NOT conflict with core protocol fields.",
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "sample_id",
+    "project_id",
+    "success_flag",
+    "timestamps"
+  ],
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/common/metadata.schema.json

@@ -0,0 +1,119 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$id": "https://schemas.mplp.dev/v1.0/common/metadata.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MPLP Metadata",
+  "description": "Common metadata structure for all MPLP objects. Provides version control, creation info, tags, and cross-cutting concern declarations. All top-level objects in L2/L3/L4 should include the meta field.",
+  "type": "object",
+  "properties": {
+    "protocol_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "MPLP protocol version, using Semantic Versioning.",
+      "examples": [
+        "1.0.0",
+        "1.1.0"
+      ]
+    },
+    "schema_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Schema version used by the current object, using Semantic Versioning.",
+      "examples": [
+        "2.0.0",
+        "2.1.0"
+      ]
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Object creation time (ISO 8601 format).",
+      "examples": [
+        "2025-01-28T15:30:00.000Z"
+      ]
+    },
+    "created_by": {
+      "type": "string",
+      "description": "Creator identifier (User ID / Agent Name / System ID).",
+      "examples": [
+        "user-123",
+        "agent-planner",
+        "system"
+      ]
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Object last update time (ISO 8601 format).",
+      "examples": [
+        "2025-01-28T16:45:00.000Z"
+      ]
+    },
+    "updated_by": {
+      "type": "string",
+      "description": "Last updater identifier.",
+      "examples": [
+        "user-456",
+        "agent-executor"
+      ]
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Set of tags for indexing/search. Supports custom classification and retrieval.",
+      "uniqueItems": true,
+      "examples": [
+        [
+          "production",
+          "high-priority"
+        ],
+        [
+          "development",
+          "experimental"
+        ]
+      ]
+    },
+    "cross_cutting": {
+      "type": "array",
+      "description": "Declares cross-cutting concerns enabled for the current object (one of the 9 concerns in Governance Plane).",
+      "items": {
+        "type": "string",
+        "enum": [
+          "coordination",
+          "error-handling",
+          "event-bus",
+          "orchestration",
+          "performance",
+          "protocol-version",
+          "security",
+          "state-sync",
+          "transaction"
+        ]
+      },
+      "uniqueItems": true,
+      "examples": [
+        [
+          "security",
+          "transaction"
+        ],
+        [
+          "performance",
+          "event-bus"
+        ]
+      ]
+    }
+  },
+  "required": [
+    "protocol_version",
+    "schema_version"
+  ],
+  "additionalProperties": false,
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/common/trace-base.schema.json

@@ -0,0 +1,49 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$id": "https://schemas.mplp.dev/v1.0/common/trace-base.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MPLP Trace Base",
+  "description": "Common base fields for Trace / Span structures. Designed based on W3C Trace Context standard, providing a unified tracing context for the MPLP execution chain. Supports distributed tracing and parent-child relationships of execution steps.",
+  "type": "object",
+  "properties": {
+    "trace_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Identifier for a complete execution chain. All related Spans share the same trace_id."
+    },
+    "span_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Identifier for the current step or operation. Each Span has a unique span_id."
+    },
+    "parent_span_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Identifier of the parent step's span_id. Can be omitted if it is a root span."
+    },
+    "context_id": {
+      "$ref": "identifiers.schema.json",
+      "description": "Identifier of the Context Root. Associates the Trace with a specific project context."
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Additional attributes (key-value pairs) to extend trace information. Can contain custom metadata, tags, etc.",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "module": "plan",
+          "operation": "create",
+          "user_id": "user-123"
+        }
+      ]
+    }
+  },
+  "required": [
+    "trace_id",
+    "span_id"
+  ],
+  "additionalProperties": false,
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/events/mplp-event-core.schema.json

@@ -0,0 +1,64 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/events/mplp-event-core.schema.json",
+  "title": "MPLP Core Event v1.0",
+  "description": "Base structure for MPLP observability events - provides common fields inherited by all event families",
+  "type": "object",
+  "properties": {
+    "event_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for this event (UUID v4)"
+    },
+    "event_type": {
+      "type": "string",
+      "description": "Specific event subtype (e.g., 'import_started', 'pipeline_stage_completed')"
+    },
+    "event_family": {
+      "type": "string",
+      "enum": [
+        "import_process",
+        "intent",
+        "delta_intent",
+        "impact_analysis",
+        "compensation_plan",
+        "methodology",
+        "reasoning_graph",
+        "pipeline_stage",
+        "graph_update",
+        "runtime_execution",
+        "cost_budget",
+        "external_integration"
+      ],
+      "description": "Event family classification - determines which minimal fields are required"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when event occurred"
+    },
+    "project_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Project context identifier (optional for system-level events)"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific payload data (schema varies by event_family)"
+    }
+  },
+  "required": [
+    "event_id",
+    "event_type",
+    "event_family",
+    "timestamp"
+  ],
+  "additionalProperties": true,
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/events/mplp-graph-update-event.schema.json

@@ -0,0 +1,64 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/events/mplp-graph-update-event.schema.json",
+  "title": "MPLP GraphUpdateEvent v1.0",
+  "description": "**REQUIRED** - PSG structural update events (MANDATORY for v1.0 compliance)",
+  "allOf": [
+    {
+      "$ref": "mplp-event-core.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "event_family": {
+          "const": "graph_update",
+          "description": "Must be 'graph_update' for this event type"
+        },
+        "graph_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "PSG identifier (typically project-level graph)"
+        },
+        "update_kind": {
+          "type": "string",
+          "enum": [
+            "node_add",
+            "node_update",
+            "node_delete",
+            "edge_add",
+            "edge_update",
+            "edge_delete",
+            "bulk"
+          ],
+          "description": "Type of graph mutation"
+        },
+        "node_delta": {
+          "type": "integer",
+          "description": "Node count delta (+/- or 0)"
+        },
+        "edge_delta": {
+          "type": "integer",
+          "description": "Edge count delta (+/- or 0)"
+        },
+        "source_module": {
+          "type": "string",
+          "description": "L2 module emitting this update (e.g., 'context', 'plan', 'collab')"
+        }
+      },
+      "required": [
+        "event_family",
+        "graph_id",
+        "update_kind",
+        "node_delta",
+        "edge_delta"
+      ]
+    }
+  ],
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}