@mplp/schema 1.0.0

package/schemas/invariants/observability-invariants.yaml

@@ -0,0 +1,102 @@
+# MPLP Protocol v1.0.0 — Frozen Specification
+# Freeze Date: 2025-12-03
+# Status: FROZEN (no breaking changes permitted)
+# Governance: MPLP Protocol Governance Committee (MPGC)
+# © 2025 邦士（北京）网络科技有限公司
+# License: Apache-2.0
+# Any normative change requires a new protocol version.
+
+# MPLP Protocol 1.0.0 — Frozen Specification
+# Status: Frozen as of 2025-11-30
+# Copyright: © 2025 邦士（北京）网络科技有限公司
+# License: Apache-2.0 (see LICENSE at repository root)
+# Any normative change requires a new protocol version.
+
+invariants:
+  # Core Event Structure Invariants
+  - id: obs_event_id_is_uuid
+    scope: event
+    path: event_id
+    rule: uuid-v4
+    description: "All events must have UUID v4 event_id"
+
+  - id: obs_event_type_non_empty
+    scope: event
+    path: event_type
+    rule: non-empty-string
+    description: "All events must have non-empty event_type"
+
+  - id: obs_event_family_valid
+    scope: event
+    path: event_family
+    rule: 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 must be valid enum value"
+
+  - id: obs_timestamp_iso_format
+    scope: event
+    path: timestamp
+    rule: iso-datetime
+    description: "All events must have ISO 8601 timestamp"
+
+  # PipelineStageEvent Specific Invariants
+  - id: obs_pipeline_event_has_pipeline_id
+    scope: event
+    path: pipeline_id
+    rule: uuid-v4
+    description: "PipelineStageEvent must have valid pipeline_id"
+    note: "Apply when event_family == pipeline_stage"
+
+  - id: obs_pipeline_stage_id_non_empty
+    scope: event
+    path: stage_id
+    rule: non-empty-string
+    description: "PipelineStageEvent must have non-empty stage_id"
+    note: "Apply when event_family == pipeline_stage"
+
+  - id: obs_pipeline_stage_status_valid
+    scope: event
+    path: stage_status
+    rule: enum(pending,running,completed,failed,skipped)
+    description: "PipelineStageEvent stage_status must be valid enum"
+    note: "Apply when event_family == pipeline_stage"
+
+  # GraphUpdateEvent Specific Invariants
+  - id: obs_graph_event_has_graph_id
+    scope: event
+    path: graph_id
+    rule: uuid-v4
+    description: "GraphUpdateEvent must have valid graph_id"
+    note: "Apply when event_family == graph_update"
+
+  - id: obs_graph_update_kind_valid
+    scope: event
+    path: update_kind
+    rule: enum(node_add,node_update,node_delete,edge_add,edge_update,edge_delete,bulk)
+    description: "GraphUpdateEvent update_kind must be valid enum"
+    note: "Apply when event_family == graph_update"
+
+  # RuntimeExecutionEvent Specific Invariants
+  - id: obs_runtime_event_has_execution_id
+    scope: event
+    path: execution_id
+    rule: uuid-v4
+    description: "RuntimeExecutionEvent must have valid execution_id"
+    note: "Apply when event_family == runtime_execution"
+
+  - id: obs_runtime_executor_kind_valid
+    scope: event
+    path: executor_kind
+    rule: enum(agent,tool,llm,worker,external)
+    description: "RuntimeExecutionEvent executor_kind must be valid enum"
+    note: "Apply when event_family == runtime_execution"
+
+  - id: obs_runtime_status_valid
+    scope: event
+    path: status
+    rule: enum(pending,running,completed,failed,cancelled)
+    description: "RuntimeExecutionEvent status must be valid enum"
+    note: "Apply when event_family == runtime_execution"
+# Note: The "note" fields indicate conditional application based on event_family.
+# If the invariant engine does not support conditional rules, these should be
+# validated at the schema level (which is already done in the event schemas).
+# These invariants provide additional layer of validation for runtime enforcement.

package/schemas/invariants/sa-invariants.yaml

@@ -0,0 +1,68 @@
+# MPLP Protocol v1.0.0 — Frozen Specification
+# Freeze Date: 2025-12-03
+# Status: FROZEN (no breaking changes permitted)
+# Governance: MPLP Protocol Governance Committee (MPGC)
+# © 2025 邦士（北京）网络科技有限公司
+# License: Apache-2.0
+# Any normative change requires a new protocol version.
+
+# MPLP Protocol 1.0.0 — Frozen Specification
+# Status: Frozen as of 2025-11-30
+# Copyright: © 2025 邦士（北京）网络科技有限公司
+# License: Apache-2.0 (see LICENSE at repository root)
+# Any normative change requires a new protocol version.
+
+invariants:
+  - id: sa_requires_context
+    scope: context
+    path: context_id
+    rule: uuid-v4
+    description: "SA execution requires a valid Context with UUID v4 identifier"
+
+  - id: sa_context_must_be_active
+    scope: context
+    path: status
+    rule: enum(active)
+    description: "SA can only execute when Context status is 'active'"
+
+  - id: sa_plan_context_binding
+    scope: plan
+    path: context_id
+    rule: eq(context.context_id)
+    description: "Plan's context_id must match SA's loaded Context"
+
+  - id: sa_plan_has_steps
+    scope: plan
+    path: steps
+    rule: min-length(1)
+    description: "Plan must contain at least one executable step"
+
+  - id: sa_steps_have_valid_ids
+    scope: plan
+    path: steps[*].step_id
+    rule: uuid-v4
+    description: "All plan steps must have valid UUID v4 identifiers"
+
+  - id: sa_steps_have_agent_role
+    scope: plan
+    path: steps[*].agent_role
+    rule: non-empty-string
+    description: "All steps must specify an agent_role for executor selection"
+
+  - id: sa_trace_not_empty
+    scope: trace
+    path: events
+    rule: min-length(1)
+    description: "SA must emit at least one trace event before completion"
+
+  - id: sa_trace_context_binding
+    scope: trace
+    path: context_id
+    rule: eq(context.context_id)
+    description: "Trace context_id must match SA's Context"
+
+  - id: sa_trace_plan_binding
+    scope: trace
+    path: plan_id
+    rule: eq(plan.plan_id)
+    description: "Trace plan_id must match SA's Plan"

package/schemas/learning/mplp-learning-sample-core.schema.json

@@ -0,0 +1,94 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/learning/mplp-learning-sample-core.schema.json",
+  "title": "MPLP LearningSample Core v1.0",
+  "description": "Core structure for MPLP LearningSample entities - defines the universal format for learning samples generated from execution history",
+  "type": "object",
+  "properties": {
+    "sample_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier of the learning sample (UUID v4)"
+    },
+    "sample_family": {
+      "type": "string",
+      "description": "LearningSample family identifier - determines expected input/output structure",
+      "examples": [
+        "intent_resolution",
+        "delta_impact",
+        "pipeline_outcome",
+        "confirm_decision",
+        "graph_evolution",
+        "multi_agent_coordination"
+      ]
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when sample was generated"
+    },
+    "input": {
+      "type": "object",
+      "description": "Abstracted representation of input conditions, intent, context at sample creation time",
+      "additionalProperties": true
+    },
+    "state": {
+      "type": "object",
+      "description": "Snapshot of relevant system state before execution (PSG summary, config, roles, etc.)",
+      "additionalProperties": true
+    },
+    "output": {
+      "type": "object",
+      "description": "Abstracted representation of actual outcomes, decisions, changes, results",
+      "additionalProperties": true
+    },
+    "meta": {
+      "type": "object",
+      "description": "Metadata, labels, quality signals, provenance IDs, human feedback annotations",
+      "properties": {
+        "source_flow_id": {
+          "type": "string",
+          "description": "Optional: Flow ID that generated this sample (e.g., FLOW-01, SA-01, MAP-01)"
+        },
+        "source_event_ids": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "description": "Optional: Observability event IDs referenced by this sample"
+        },
+        "project_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Optional: Project context identifier"
+        },
+        "human_feedback_label": {
+          "type": "string",
+          "enum": [
+            "approved",
+            "rejected",
+            "not_reviewed"
+          ],
+          "description": "Optional: Human quality assessment"
+        },
+        "quality_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Optional: Automated quality score (0.0-1.0)"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "sample_id",
+    "sample_family",
+    "created_at",
+    "input",
+    "output"
+  ],
+  "additionalProperties": true
+}

package/schemas/learning/mplp-learning-sample-delta.schema.json

@@ -0,0 +1,137 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/learning/mplp-learning-sample-delta.schema.json",
+  "title": "MPLP LearningSample – Delta Impact v1.0",
+  "description": "Specialized schema for delta_impact samples capturing change effect analysis and compensation planning",
+  "allOf": [
+    {
+      "$ref": "mplp-learning-sample-core.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "sample_family": {
+          "const": "delta_impact",
+          "description": "Must be 'delta_impact' for this sample type"
+        },
+        "input": {
+          "type": "object",
+          "properties": {
+            "delta_id": {
+              "type": "string",
+              "description": "Delta Intent identifier"
+            },
+            "intent_id": {
+              "type": "string",
+              "description": "Original intent being modified"
+            },
+            "delta_type": {
+              "type": "string",
+              "enum": [
+                "refinement",
+                "correction",
+                "expansion",
+                "reduction",
+                "pivot"
+              ],
+              "description": "Type of delta change"
+            },
+            "change_summary": {
+              "type": "string",
+              "description": "Abstracted summary of requested change"
+            }
+          },
+          "required": [
+            "delta_id",
+            "intent_id",
+            "change_summary"
+          ],
+          "additionalProperties": true
+        },
+        "state": {
+          "type": "object",
+          "properties": {
+            "affected_artifact_count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Optional: Number of artifacts potentially affected"
+            },
+            "risk_level": {
+              "type": "string",
+              "enum": [
+                "low",
+                "medium",
+                "high",
+                "critical"
+              ],
+              "description": "Assessed risk level before change"
+            },
+            "psg_complexity_score": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Optional: PSG complexity metric before change"
+            }
+          },
+          "additionalProperties": true
+        },
+        "output": {
+          "type": "object",
+          "properties": {
+            "actual_impact_summary": {
+              "type": "string",
+              "description": "Summary of actual impact after analysis"
+            },
+            "impact_scope": {
+              "type": "string",
+              "enum": [
+                "local",
+                "module",
+                "system",
+                "global"
+              ],
+              "description": "Scope of detected impact"
+            },
+            "comp_plan_required": {
+              "type": "boolean",
+              "description": "Whether compensation plan was needed"
+            },
+            "comp_plan_applied": {
+              "type": "boolean",
+              "description": "Optional: Whether compensation was actually applied"
+            },
+            "rollback_used": {
+              "type": "boolean",
+              "description": "Optional: Whether rollback mechanism was triggered"
+            }
+          },
+          "required": [
+            "actual_impact_summary",
+            "impact_scope"
+          ],
+          "additionalProperties": true
+        },
+        "meta": {
+          "type": "object",
+          "properties": {
+            "impact_analysis_duration_ms": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Optional: Time spent on impact analysis"
+            },
+            "predicted_vs_actual_accuracy": {
+              "type": "string",
+              "enum": [
+                "accurate",
+                "underestimated",
+                "overestimated"
+              ],
+              "description": "Optional: Accuracy of impact prediction"
+            }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}

package/schemas/learning/mplp-learning-sample-intent.schema.json

@@ -0,0 +1,119 @@
+{
+  "$comment": "MPLP Protocol v1.0.0 — Frozen Specification\nFreeze Date: 2025-12-03\nStatus: FROZEN (no breaking changes permitted)\nGovernance: MPLP Protocol Governance Committee (MPGC)\nCopyright: © 2025 邦士（北京）网络科技有限公司\nLicense: Apache-2.0\nAny normative change requires a new protocol version.",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mplp.dev/schemas/v1.0/learning/mplp-learning-sample-intent.schema.json",
+  "title": "MPLP LearningSample – Intent Resolution v1.0",
+  "description": "Specialized schema for intent_resolution samples capturing user intent clarification and plan generation",
+  "allOf": [
+    {
+      "$ref": "mplp-learning-sample-core.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "sample_family": {
+          "const": "intent_resolution",
+          "description": "Must be 'intent_resolution' for this sample type"
+        },
+        "input": {
+          "type": "object",
+          "properties": {
+            "intent_id": {
+              "type": "string",
+              "description": "Intent identifier from IntentEvent or Plan.intent_model"
+            },
+            "raw_request_summary": {
+              "type": "string",
+              "description": "Abstracted summary of original user request (PII-scrubbed if needed)"
+            },
+            "constraints_summary": {
+              "type": "string",
+              "description": "Optional: Key constraints mentioned (timeline, budget, resources, etc.)"
+            },
+            "dialog_turns_count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Optional: Number of dialog exchanges before intent resolution"
+            }
+          },
+          "required": [
+            "intent_id",
+            "raw_request_summary"
+          ],
+          "additionalProperties": true
+        },
+        "state": {
+          "type": "object",
+          "properties": {
+            "project_phase": {
+              "type": "string",
+              "description": "Optional: Project state (greenfield, brownfield, maintenance, etc.)"
+            },
+            "psg_node_count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Optional: PSG size before intent application"
+            },
+            "existing_plan_count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Optional: Number of existing plans in context"
+            }
+          },
+          "additionalProperties": true
+        },
+        "output": {
+          "type": "object",
+          "properties": {
+            "final_intent_summary": {
+              "type": "string",
+              "description": "Refined/clarified intent after resolution process"
+            },
+            "plan_id": {
+              "type": "string",
+              "format": "uuid",
+              "description": "Optional: Generated Plan identifier (if plan created)"
+            },
+            "plan_step_count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Optional: Number of steps in generated plan"
+            },
+            "resolution_quality_label": {
+              "type": "string",
+              "enum": [
+                "good",
+                "acceptable",
+                "bad",
+                "unknown"
+              ],
+              "description": "Assessment of intent resolution quality"
+            }
+          },
+          "required": [
+            "final_intent_summary"
+          ],
+          "additionalProperties": true
+        },
+        "meta": {
+          "type": "object",
+          "properties": {
+            "clarification_rounds": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Optional: Clarification rounds needed before resolution"
+            },
+            "ambiguity_flags": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Optional: Detected ambiguity types (vague_scope, missing_constraints, etc.)"
+            }
+          },
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}