@mplp/sdk-ts 1.0.2 → 1.0.4

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"
+  }
+}

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

@@ -0,0 +1,153 @@
+{
+  "$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-map-event.schema.json",
+  "title": "MPLP MAP Event v1.0",
+  "description": "Events emitted by Multi-Agent Profile (MAP) collaboration sessions in MPLP v1.0 protocol",
+  "type": "object",
+  "properties": {
+    "event_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for this event"
+    },
+    "event_type": {
+      "type": "string",
+      "enum": [
+        "MAPSessionStarted",
+        "MAPRolesAssigned",
+        "MAPTurnDispatched",
+        "MAPTurnCompleted",
+        "MAPBroadcastSent",
+        "MAPBroadcastReceived",
+        "MAPConflictDetected",
+        "MAPConflictResolved",
+        "MAPSessionCompleted"
+      ],
+      "description": "Type of MAP session lifecycle event"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when event occurred"
+    },
+    "session_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Collaboration session ID (corresponds to Collab.collab_id)"
+    },
+    "initiator_role": {
+      "type": "string",
+      "description": "Role ID of the initiating agent (optional, depends on event type)"
+    },
+    "target_roles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Array of target role IDs for this event (e.g., broadcast targets)"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific data payload",
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "event_id",
+    "event_type",
+    "timestamp",
+    "session_id"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "turn_dispatched_payload": {
+      "type": "object",
+      "properties": {
+        "role_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Role receiving execution token"
+        },
+        "turn_number": {
+          "type": "integer",
+          "description": "Sequential turn number"
+        },
+        "token_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Execution token identifier"
+        }
+      },
+      "required": [
+        "role_id",
+        "turn_number"
+      ]
+    },
+    "turn_completed_payload": {
+      "type": "object",
+      "properties": {
+        "role_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Role that completed the turn"
+        },
+        "turn_number": {
+          "type": "integer",
+          "description": "Sequential turn number"
+        },
+        "result": {
+          "type": "object",
+          "description": "Turn execution result"
+        }
+      },
+      "required": [
+        "role_id",
+        "turn_number"
+      ]
+    },
+    "broadcast_sent_payload": {
+      "type": "object",
+      "properties": {
+        "broadcaster_role_id": {
+          "type": "string",
+          "description": "Role sending broadcast"
+        },
+        "target_count": {
+          "type": "integer",
+          "description": "Number of target agents"
+        },
+        "message": {
+          "type": "object",
+          "description": "Broadcast message content"
+        }
+      },
+      "required": [
+        "broadcaster_role_id",
+        "target_count"
+      ]
+    },
+    "broadcast_received_payload": {
+      "type": "object",
+      "properties": {
+        "receiver_role_id": {
+          "type": "string",
+          "description": "Role that received broadcast"
+        },
+        "response": {
+          "type": "object",
+          "description": "Agent response to broadcast"
+        }
+      },
+      "required": [
+        "receiver_role_id"
+      ]
+    }
+  },
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}