feat: add lightweight MCP replay context layer

artifacts/mcp_context_layer_example.json

@@ -0,0 +1,86 @@
+{
+  "artifact_id": "mcp_context_layer_example_v1",
+  "evaluation_mode": "deterministic",
+  "example": {
+    "fixture_id": "mcp_trace_replay_v1",
+    "prompt_context": "task: mcp_trace_replay_v1\nadmissible: true\nconstraints:\n- execute_external_action:requires_human_approval\n- execute_external_action:requires_validation_passed\nrequired_order:\n- user_request_received\n- capability_scope_checked\n- tool_schema_validated\n- read_context\n- validate_external_action\n- execute_external_action\n- verify_result\n- recovery_path_registered\ndependencies:\n- capability_scope_checked -> execute_external_action\n- capability_scope_checked -> tool_schema_validated\n- capability_scope_checked -> validate_external_action\n- execute_external_action -> recovery_path_registered\n- execute_external_action -> verify_result\n- read_context -> validate_external_action\n- tool_schema_validated -> read_context\n- user_request_received -> capability_scope_checked\n- validate_external_action -> execute_external_action\nblockers:\n- capability_scope_checked -> execute_external_action\nrecovery:\n- execute_external_action -> recovery_path_registered",
+    "replay_payload": {
+      "blockers": [
+        [
+          "capability_scope_checked",
+          "execute_external_action"
+        ]
+      ],
+      "constraints": [
+        "execute_external_action:requires_human_approval",
+        "execute_external_action:requires_validation_passed"
+      ],
+      "dependency_chains": [
+        [
+          "capability_scope_checked",
+          "execute_external_action"
+        ],
+        [
+          "capability_scope_checked",
+          "tool_schema_validated"
+        ],
+        [
+          "capability_scope_checked",
+          "validate_external_action"
+        ],
+        [
+          "execute_external_action",
+          "recovery_path_registered"
+        ],
+        [
+          "execute_external_action",
+          "verify_result"
+        ],
+        [
+          "read_context",
+          "validate_external_action"
+        ],
+        [
+          "tool_schema_validated",
+          "read_context"
+        ],
+        [
+          "user_request_received",
+          "capability_scope_checked"
+        ],
+        [
+          "validate_external_action",
+          "execute_external_action"
+        ]
+      ],
+      "recovery": [
+        [
+          "execute_external_action",
+          "recovery_path_registered"
+        ]
+      ],
+      "required_order": [
+        "user_request_received",
+        "capability_scope_checked",
+        "tool_schema_validated",
+        "read_context",
+        "validate_external_action",
+        "execute_external_action",
+        "verify_result",
+        "recovery_path_registered"
+      ],
+      "task": "mcp_trace_replay_v1"
+    },
+    "source_fixture_path": "fixtures/mcp_trace_replay_v1/original",
+    "validation": {
+      "admissible": true,
+      "failure_labels": [],
+      "issues": []
+    }
+  },
+  "external_apis": "none",
+  "generated_by": "McpContextLayerExampleArtifactGenerator",
+  "llm_judges": "none",
+  "schema_version": "mcp_context_layer_example.v1",
+  "version": "1.0"
+}

docs/mcp_context_layer.md

@@ -0,0 +1,93 @@
+# MCP Context Layer
+
+CompText V7 includes a lightweight replay-aware context layer for MCP-style
+runtime systems. The layer preserves compact operational context for
+deterministic replay validation; it does not execute tools, orchestrate agents,
+call external APIs, or judge semantic quality.
+
+## Scope
+
+The context layer is additive to the existing replay fixtures and contracts. It
+builds a compact payload from explicit trace, state, and dependency-graph fields:
+
+```json
+{
+  "task": "mcp_trace_replay_v1",
+  "constraints": [
+    "execute_external_action:requires_human_approval",
+    "execute_external_action:requires_validation_passed"
+  ],
+  "required_order": [
+    "capability_scope_checked",
+    "tool_schema_validated",
+    "read_context",
+    "validate_external_action",
+    "execute_external_action"
+  ],
+  "blockers": [
+    ["capability_scope_checked", "execute_external_action"]
+  ],
+  "dependency_chains": [
+    ["validate_external_action", "execute_external_action"]
+  ],
+  "recovery": [
+    ["execute_external_action", "recovery_path_registered"]
+  ]
+}
+```
+
+## Public API
+
+- `build_replay_payload(trace)` extracts compact deterministic commitments.
+- `render_prompt_context(payload)` renders a compact prompt-safe text view.
+- `validate_replay_payload(payload)` validates replay admissibility from explicit
+  payload fields.
+- `ContextStore(root).save_context(trace)` writes a stable JSON payload.
+- `ContextStore(root).load_context(task_id)` restores the compact payload.
+- `save_context(trace, store_dir=...)` and `load_context(task_id, store_dir=...)`
+  provide module-level convenience wrappers.
+
+## Deterministic checks
+
+`validate_replay_payload` detects:
+
+- missing preserved constraints as `CONSTRAINT_DRIFT`
+- dependency-order drift as `TOOL_ORDER_VIOLATION`
+- dependency collapse as `DEPENDENCY_CHAIN_BREAK`
+- missing recovery paths as `RECOVERY_PATH_LOSS`
+
+The validator uses exact strings, ordered lists, and explicit dependency edges.
+It performs no embedding lookup, fuzzy scoring, probabilistic reasoning, LLM
+judging, runtime blocking, or policy enforcement.
+
+## Prompt context rendering
+
+`render_prompt_context(payload)` produces a token-light text form without dumping
+raw trace, state, or dependency-graph documents:
+
+```text
+task: mcp_trace_replay_v1
+admissible: true
+constraints:
+- execute_external_action:requires_validation_passed
+required_order:
+- validate_external_action
+- execute_external_action
+dependencies:
+- validate_external_action -> execute_external_action
+recovery:
+- execute_external_action -> recovery_path_registered
+```
+
+## Example artifact
+
+`artifacts/mcp_context_layer_example.json` is a fixture-bound deterministic
+example generated from `fixtures/mcp_trace_replay_v1/original`. It contains the
+compact replay payload, prompt-context rendering, and validation result for the
+baseline MCP trace replay fixture.
+
+## Relationship to MCP
+
+This layer augments context integrity for MCP-compatible systems. It is not an
+MCP implementation and does not replace MCP transport, runtime execution, or
+tool semantics.

scripts/generate_mcp_context_layer_example_artifact.py

@@ -0,0 +1,72 @@
+"""Generate a deterministic MCP context-layer example artifact."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from src.comptext_v7.mcp import build_replay_payload, render_prompt_context, validate_replay_payload
+
+ARTIFACT_ID = "mcp_context_layer_example_v1"
+EXAMPLE_FIXTURE_ID = "mcp_trace_replay_v1"
+EXAMPLE_FIXTURE_PATH = REPO_ROOT / "fixtures" / EXAMPLE_FIXTURE_ID / "original"
+OUTPUT_PATH = REPO_ROOT / "artifacts" / "mcp_context_layer_example.json"
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _load_fixture_context() -> dict[str, Any]:
+    return {
+        "task": EXAMPLE_FIXTURE_ID,
+        "trace": _load_json(EXAMPLE_FIXTURE_PATH / "trace.json"),
+        "state": _load_json(EXAMPLE_FIXTURE_PATH / "state.json"),
+        "dependency_graph": _load_json(EXAMPLE_FIXTURE_PATH / "dependency_graph.json"),
+    }
+
+
+def build_mcp_context_layer_example_artifact() -> dict[str, Any]:
+    replay_payload = build_replay_payload(_load_fixture_context())
+    validation = validate_replay_payload(replay_payload)
+    prompt_context = render_prompt_context({**replay_payload, "validation": validation})
+
+    return {
+        "artifact_id": ARTIFACT_ID,
+        "evaluation_mode": "deterministic",
+        "example": {
+            "fixture_id": EXAMPLE_FIXTURE_ID,
+            "prompt_context": prompt_context,
+            "replay_payload": replay_payload,
+            "source_fixture_path": f"fixtures/{EXAMPLE_FIXTURE_ID}/original",
+            "validation": validation,
+        },
+        "external_apis": "none",
+        "generated_by": "McpContextLayerExampleArtifactGenerator",
+        "llm_judges": "none",
+        "schema_version": "mcp_context_layer_example.v1",
+        "version": "1.0",
+    }
+
+
+def generate_mcp_context_layer_example_artifact(output_path: Path = OUTPUT_PATH) -> Path:
+    artifact = build_mcp_context_layer_example_artifact()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(artifact, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return output_path
+
+
+def main() -> int:
+    output_path = generate_mcp_context_layer_example_artifact()
+    print(output_path.relative_to(REPO_ROOT).as_posix())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/comptext_v7/mcp/__init__.py

@@ -0,0 +1,14 @@
+"""Replay-aware context layer for MCP-style runtime systems."""
+
+from .context_store import ContextStore, load_context, save_context
+from .replay_payload import build_replay_payload, render_prompt_context
+from .validator import validate_replay_payload
+
+__all__ = [
+    "ContextStore",
+    "build_replay_payload",
+    "load_context",
+    "render_prompt_context",
+    "save_context",
+    "validate_replay_payload",
+]