causal-memory-layer 0.4.0__tar.gz

causal_memory_layer-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aleksey Safonov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

causal_memory_layer-0.4.0/LICENSE_COMMERCIAL.md

@@ -0,0 +1,74 @@
+# CML Commercial License
+
+> **DRAFT** — Commercial licensing terms are not yet finalised.
+> The MIT-licensed SDK is available today. Pro/Enterprise terms will be
+> published at v0.8 general availability.
+
+## Open Core Model
+
+The Causal Memory Layer project operates under a dual-license model:
+
+---
+
+### 1. MIT License (Community)
+
+All code in the following paths is licensed under the **MIT License**
+(see `LICENSE`):
+
+```
+cml/              — Core Python SDK
+cli/              — CLI tool
+api/              — REST API server
+vcml/             — Reference implementation and specifications
+examples/         — Example logs and configurations
+tests/            — Test suite
+```
+
+You may use, copy, modify, distribute, and sublicense this code freely,
+including in commercial products, subject to the MIT License terms.
+
+---
+
+### 2. Commercial License (Pro / Enterprise)
+
+The following components are available under a **commercial license** for
+Pro and Enterprise customers:
+
+| Component | Description |
+|-----------|-------------|
+| `enterprise/compliance/` | SOC 2 / GDPR / PCI-DSS report generators |
+| `enterprise/multi_tenant/` | Multi-tenant log isolation and cross-domain audit |
+| `enterprise/integrations/` | SIEM, Splunk, Datadog, Elastic connectors |
+| `enterprise/pdf_reports/` | PDF compliance report rendering |
+| Hosted API infrastructure | Managed service, persistent storage, SLA |
+
+To obtain a commercial license, contact: **enterprise@causal-memory.dev**
+
+---
+
+### 3. Attribution
+
+If you use CML in a published product, paper, or service, we ask (but do not
+require) that you include the following attribution:
+
+> "Causal provenance powered by Causal Memory Layer (CML)"
+> https://github.com/safal207/Causal-Memory-Layer
+
+---
+
+### 4. Patent Notice
+
+No patent rights are granted or implied by the MIT License.
+If you build a product based on CML semantics, we encourage contribution
+back to the specification and community.
+
+---
+
+### 5. Trademark
+
+"Causal Memory Layer", "CML", and "vCML" are project identifiers.
+You may not use them to imply official endorsement without permission.
+
+---
+
+For licensing questions: **legal@causal-memory.dev**

causal_memory_layer-0.4.0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: causal-memory-layer
+Version: 0.4.0
+Summary: Causal Memory Layer — SDK for recording, auditing, and analyzing causal chains in systems
+Author-email: CML Project <dev@causal-memory.dev>
+License: MIT License
+        
+        Copyright (c) 2025 Aleksey Safonov
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/safal207/Causal-Memory-Layer
+Project-URL: Repository, https://github.com/safal207/Causal-Memory-Layer
+Project-URL: Issues, https://github.com/safal207/Causal-Memory-Layer/issues
+Project-URL: Changelog, https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md
+Keywords: causal,audit,provenance,security,compliance,ebpf,tracing,causal-memory,ai-governance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE_COMMERCIAL.md
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: httpx>=0.27; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.29; extra == "api"
+Requires-Dist: python-multipart>=0.0.9; extra == "api"
+Requires-Dist: slowapi>=0.1.9; extra == "api"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: uvicorn[standard]>=0.29; extra == "dev"
+Requires-Dist: python-multipart>=0.0.9; extra == "dev"
+Requires-Dist: slowapi>=0.1.9; extra == "dev"
+Dynamic: license-file
+
+# Causal Memory Layer (CML)
+
+[![CI](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/ci.yml/badge.svg)](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/ci.yml)
+[![Package Validation](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/python-package-validation.yml/badge.svg)](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/python-package-validation.yml)
+![Status](https://img.shields.io/badge/status-active-brightgreen)
+![Audit](https://img.shields.io/badge/audit-causal%20lineage-blue)
+![License](https://img.shields.io/badge/license-MIT-orange)
+[![Safety Eval](https://img.shields.io/badge/safety--eval-6%2F6%20matched-purple)](docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md)
+
+![CML before-after causal audit visual](docs/assets/cml-before-after.svg)
+
+## Why CML?
+
+**Logs show what happened. CML checks why it was allowed.**
+
+A workflow can pass every functional test and still be causally invalid: the action succeeded, but the approval, intent, or responsibility lineage is missing, ambiguous, or broken.
+
+```text
+ordinary log:  action completed -> OK
+CML audit:     parent_cause=approval-42 -> MISSING_PARENT
+```
+
+CML is an open-source causal audit layer for structured action traces, AI-agent workflows, high-trust automation, and reviewable safety infrastructure.
+
+> A system may be functionally correct while being causally invalid.
+
+**Star this repo if you care about auditable AI agents, deterministic oversight, causal traces, and open-source AI safety infrastructure.**
+
+## 30-second demo
+
+Run the local API:
+
+```bash
+docker compose up --build
+```
+
+Then follow the Docker walkthrough:
+
+```text
+docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md
+```
+
+Expected example finding:
+
+```text
+CML-AUDIT-R1-MISSING_PARENT
+```
+
+The action may look operationally valid, but CML asks whether its causal parent exists.
+
+## Use CML when you need to audit
+
+- AI-agent tool calls and action chains.
+- Human approval handoffs.
+- Automation workflows with high-trust actions.
+- Fintech or review-heavy decision paths.
+- Structured traces where responsibility lineage matters.
+- Research benchmarks for causal validity in agentic systems.
+
+## Agent-audit MCP integration
+
+CML can also run as an experimental MCP tool server for AI-agent audit workflows.
+
+```bash
+pip install -e ".[mcp]"
+cml-mcp
+```
+
+See [`docs/integrations/MCP_AGENT_AUDIT.md`](docs/integrations/MCP_AGENT_AUDIT.md) for local MCP client setup and available tools.
+
+For a short coding-assistant setup path, see [`docs/integrations/CURSOR_MCP_QUICKSTART.md`](docs/integrations/CURSOR_MCP_QUICKSTART.md).
+
+## How CML differs
+
+| System type | Usually answers | CML adds |
+| :--- | :--- | :--- |
+| Logs | What happened? | Was the action causally permitted? |
+| Tracing | Where did execution go? | Did responsibility lineage survive the workflow? |
+| Observability | What failed operationally? | What succeeded but had broken causal lineage? |
+| Policy checks | Is this allowed now? | Why was this specific action allowed in this trace? |
+| CML | Why was this action allowed? | Narrow audit primitive, not a full runtime safety stack. |
+
+## Fast validation
+
+```bash
+pip install -e ".[dev]"
+pytest
+python scripts/run_safety_eval.py
+```
+
+Dashboard:
+
+```text
+https://safal207.github.io/Causal-Memory-Layer/
+```
+
+## Review links
+
+- Start here: [`docs/START_HERE.md`](docs/START_HERE.md)
+- Reviewer path: [`docs/REVIEWER_PATH.md`](docs/REVIEWER_PATH.md)
+- Research map: [`docs/research/CML_RESEARCH_MAP.md`](docs/research/CML_RESEARCH_MAP.md)
+- Non-claims: [`docs/NON_CLAIMS.md`](docs/NON_CLAIMS.md)
+- Portfolio relationship: [`docs/PORTFOLIO_RELATIONSHIP.md`](docs/PORTFOLIO_RELATIONSHIP.md)
+- Benchmark evidence: [`docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md`](docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md)
+- External validation protocol: [`docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md`](docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md)
+- Technical report outline: [`docs/research/TECHNICAL_REPORT_OUTLINE.md`](docs/research/TECHNICAL_REPORT_OUTLINE.md)
+- Funding / research evidence: [`docs/GRANT_EVIDENCE.md`](docs/GRANT_EVIDENCE.md)
+- Docker walkthrough: [`docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md`](docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md)
+- MCP agent-audit integration: [`docs/integrations/MCP_AGENT_AUDIT.md`](docs/integrations/MCP_AGENT_AUDIT.md)
+- Cursor MCP quickstart: [`docs/integrations/CURSOR_MCP_QUICKSTART.md`](docs/integrations/CURSOR_MCP_QUICKSTART.md)
+- Cause Band concept: [`docs/research/CAUSE_BAND.md`](docs/research/CAUSE_BAND.md)
+- Cause Band trajectory walkthrough: [`docs/demo/CAUSE_BAND_TRAJECTORY_WALKTHROUGH.md`](docs/demo/CAUSE_BAND_TRAJECTORY_WALKTHROUGH.md)
+- Agent intent drift example: [`docs/demo/AGENT_INTENT_DRIFT_CAUSE_BAND_EXAMPLE.md`](docs/demo/AGENT_INTENT_DRIFT_CAUSE_BAND_EXAMPLE.md)
+- Dormant Causal Patterns: [`docs/research/DORMANT_CAUSAL_PATTERNS.md`](docs/research/DORMANT_CAUSAL_PATTERNS.md)
+- Temporal Causal Watchpoints: [`docs/research/TEMPORAL_CAUSAL_WATCHPOINTS.md`](docs/research/TEMPORAL_CAUSAL_WATCHPOINTS.md)
+- Experimental Cause Band audit flag: [`docs/experimental/CAUSE_BAND_AUDIT_FLAG.md`](docs/experimental/CAUSE_BAND_AUDIT_FLAG.md)
+- Quantum causal audit future direction: [`docs/research/QUANTUM_CAUSAL_AUDIT_FUTURE_DIRECTION.md`](docs/research/QUANTUM_CAUSAL_AUDIT_FUTURE_DIRECTION.md)
+- Causal invalidity patterns: [`docs/research/CAUSAL_INVALIDITY_PATTERNS.md`](docs/research/CAUSAL_INVALIDITY_PATTERNS.md)
+- Audit findings glossary: [`docs/audit/FINDINGS_GLOSSARY.md`](docs/audit/FINDINGS_GLOSSARY.md)
+- LTP / CML bridge: [`docs/LTP_CML_BRIDGE.md`](docs/LTP_CML_BRIDGE.md)
+- Roadmap: [`ROADMAP.md`](ROADMAP.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+- License: [`LICENSE`](LICENSE)
+
+## Current artifact
+
+This repository already contains a working technical artifact, not only a concept.
+
+Current components include:
+
+- Python causal validation and audit engine;
+- causal chain reconstruction utilities;
+- CLI commands for lineage validation and chain inspection;
+- API layer and store interface;
+- example logs and audit outputs;
+- tests for chain logic, audit rules, and CTAG behavior;
+- API smoke tests for health, audit, and CTAG decode;
+- deterministic safety-eval benchmark with fixtures and tracked results;
+- documentation for vCML semantics and audit rules.
+
+Key implementation entry points:
+
+- `cml/audit.py`
+- `cml/chain.py`
+- `cli/main.py`
+- `api/server.py`
+- `tests/test_audit.py`
+- `tests/test_api_smoke.py`
+
+## Problem
+
+Many systems record events, outputs, traces, and metrics, but do not validate the causal structure behind authorization and action.
+
+That creates blind spots such as:
+
+- actions that appear valid but have no grounded parent cause;
+- ambiguous or malformed root authority;
+- actions that succeed operationally while losing approval lineage;
+- state transitions that cannot be tied back to intent, permission, and responsibility.
+
+For agentic systems, this matters because output review alone can miss causally invalid action chains.
+
+## What CML does
+
+CML checks whether a high-trust action or state transition was causally valid, not only whether it occurred.
+
+It focuses on:
+
+- validating causal links between actions and prior authorization;
+- preserving responsibility lineage across multi-step workflows;
+- checking intent and permission continuity across transitions;
+- detecting suspicious or invalid lineage such as missing parents, malformed roots, or broken handoffs;
+- validating causal coherence from structured logs and traces.
+
+## Evidence snapshot
+
+- Deterministic benchmark fixtures with expected audit findings: `benchmarks/fixtures/`
+- Current tracked benchmark result: `6/6 matched`
+- Benchmark runner: `python scripts/run_safety_eval.py`
+- Tracked report: `benchmarks/RESULTS.md`
+- Reviewer-friendly benchmark interpretation: `docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md`
+- Larger-grant expansion path: `docs/evidence/BENCHMARK_EXPANSION_PLAN_50K_100K.md`
+- External validation protocol: `docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md`
+
+## External reproducibility evidence
+
+External validation notes will be listed here as they are contributed.
+
+Current external validation tasks:
+
+- Full local validation path: [`#77`](https://github.com/safal207/Causal-Memory-Layer/issues/77)
+- MCP demo runner validation: [`#123`](https://github.com/safal207/Causal-Memory-Layer/issues/123)
+
+Validation note template:
+
+```text
+docs/evidence/external_validation/TEMPLATE_MCP_DEMO_RUNNER.md
+```
+
+This section is intentionally evidence-first: it should only list external notes after they are contributed. It does not claim production safety, compliance readiness, enforcement behavior, or stable Cause Band semantics.
+
+## Repository map
+
+- `cml/`: core Python implementation
+- `cli/`: command-line tooling
+- `api/`: API and store layer
+- `vcml/`: vCML semantics, format, audit, and boundary docs
+- `examples/`: sample logs and reports
+- `benchmarks/`: deterministic benchmark fixtures and results
+- `tests/`: regression coverage
+- `docs/`: supporting docs for review, research, and deployment
+
+## Scope
+
+CML does not claim to solve all AI safety, security, or compliance problems.
+
+It contributes one focused primitive:
+
+```text
+causal-validity checking for structured action traces
+```
+
+See [`docs/NON_CLAIMS.md`](docs/NON_CLAIMS.md) for the full scope boundary.
+
+## Research direction
+
+The strongest research direction for CML is causal validity checking for agentic oversight.
+
+A useful framing is:
+
+> How can we detect actions that appear valid at the surface level but are causally invalid because authorization, approval, or responsibility lineage is missing, ambiguous, or broken?
+
+## Bottom line
+
+A system may be functionally correct while being causally invalid.
+
+CML exists to make that distinction inspectable.

causal_memory_layer-0.4.0/README.md

@@ -0,0 +1,237 @@
+# Causal Memory Layer (CML)
+
+[![CI](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/ci.yml/badge.svg)](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/ci.yml)
+[![Package Validation](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/python-package-validation.yml/badge.svg)](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/python-package-validation.yml)
+![Status](https://img.shields.io/badge/status-active-brightgreen)
+![Audit](https://img.shields.io/badge/audit-causal%20lineage-blue)
+![License](https://img.shields.io/badge/license-MIT-orange)
+[![Safety Eval](https://img.shields.io/badge/safety--eval-6%2F6%20matched-purple)](docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md)
+
+![CML before-after causal audit visual](docs/assets/cml-before-after.svg)
+
+## Why CML?
+
+**Logs show what happened. CML checks why it was allowed.**
+
+A workflow can pass every functional test and still be causally invalid: the action succeeded, but the approval, intent, or responsibility lineage is missing, ambiguous, or broken.
+
+```text
+ordinary log:  action completed -> OK
+CML audit:     parent_cause=approval-42 -> MISSING_PARENT
+```
+
+CML is an open-source causal audit layer for structured action traces, AI-agent workflows, high-trust automation, and reviewable safety infrastructure.
+
+> A system may be functionally correct while being causally invalid.
+
+**Star this repo if you care about auditable AI agents, deterministic oversight, causal traces, and open-source AI safety infrastructure.**
+
+## 30-second demo
+
+Run the local API:
+
+```bash
+docker compose up --build
+```
+
+Then follow the Docker walkthrough:
+
+```text
+docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md
+```
+
+Expected example finding:
+
+```text
+CML-AUDIT-R1-MISSING_PARENT
+```
+
+The action may look operationally valid, but CML asks whether its causal parent exists.
+
+## Use CML when you need to audit
+
+- AI-agent tool calls and action chains.
+- Human approval handoffs.
+- Automation workflows with high-trust actions.
+- Fintech or review-heavy decision paths.
+- Structured traces where responsibility lineage matters.
+- Research benchmarks for causal validity in agentic systems.
+
+## Agent-audit MCP integration
+
+CML can also run as an experimental MCP tool server for AI-agent audit workflows.
+
+```bash
+pip install -e ".[mcp]"
+cml-mcp
+```
+
+See [`docs/integrations/MCP_AGENT_AUDIT.md`](docs/integrations/MCP_AGENT_AUDIT.md) for local MCP client setup and available tools.
+
+For a short coding-assistant setup path, see [`docs/integrations/CURSOR_MCP_QUICKSTART.md`](docs/integrations/CURSOR_MCP_QUICKSTART.md).
+
+## How CML differs
+
+| System type | Usually answers | CML adds |
+| :--- | :--- | :--- |
+| Logs | What happened? | Was the action causally permitted? |
+| Tracing | Where did execution go? | Did responsibility lineage survive the workflow? |
+| Observability | What failed operationally? | What succeeded but had broken causal lineage? |
+| Policy checks | Is this allowed now? | Why was this specific action allowed in this trace? |
+| CML | Why was this action allowed? | Narrow audit primitive, not a full runtime safety stack. |
+
+## Fast validation
+
+```bash
+pip install -e ".[dev]"
+pytest
+python scripts/run_safety_eval.py
+```
+
+Dashboard:
+
+```text
+https://safal207.github.io/Causal-Memory-Layer/
+```
+
+## Review links
+
+- Start here: [`docs/START_HERE.md`](docs/START_HERE.md)
+- Reviewer path: [`docs/REVIEWER_PATH.md`](docs/REVIEWER_PATH.md)
+- Research map: [`docs/research/CML_RESEARCH_MAP.md`](docs/research/CML_RESEARCH_MAP.md)
+- Non-claims: [`docs/NON_CLAIMS.md`](docs/NON_CLAIMS.md)
+- Portfolio relationship: [`docs/PORTFOLIO_RELATIONSHIP.md`](docs/PORTFOLIO_RELATIONSHIP.md)
+- Benchmark evidence: [`docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md`](docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md)
+- External validation protocol: [`docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md`](docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md)
+- Technical report outline: [`docs/research/TECHNICAL_REPORT_OUTLINE.md`](docs/research/TECHNICAL_REPORT_OUTLINE.md)
+- Funding / research evidence: [`docs/GRANT_EVIDENCE.md`](docs/GRANT_EVIDENCE.md)
+- Docker walkthrough: [`docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md`](docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md)
+- MCP agent-audit integration: [`docs/integrations/MCP_AGENT_AUDIT.md`](docs/integrations/MCP_AGENT_AUDIT.md)
+- Cursor MCP quickstart: [`docs/integrations/CURSOR_MCP_QUICKSTART.md`](docs/integrations/CURSOR_MCP_QUICKSTART.md)
+- Cause Band concept: [`docs/research/CAUSE_BAND.md`](docs/research/CAUSE_BAND.md)
+- Cause Band trajectory walkthrough: [`docs/demo/CAUSE_BAND_TRAJECTORY_WALKTHROUGH.md`](docs/demo/CAUSE_BAND_TRAJECTORY_WALKTHROUGH.md)
+- Agent intent drift example: [`docs/demo/AGENT_INTENT_DRIFT_CAUSE_BAND_EXAMPLE.md`](docs/demo/AGENT_INTENT_DRIFT_CAUSE_BAND_EXAMPLE.md)
+- Dormant Causal Patterns: [`docs/research/DORMANT_CAUSAL_PATTERNS.md`](docs/research/DORMANT_CAUSAL_PATTERNS.md)
+- Temporal Causal Watchpoints: [`docs/research/TEMPORAL_CAUSAL_WATCHPOINTS.md`](docs/research/TEMPORAL_CAUSAL_WATCHPOINTS.md)
+- Experimental Cause Band audit flag: [`docs/experimental/CAUSE_BAND_AUDIT_FLAG.md`](docs/experimental/CAUSE_BAND_AUDIT_FLAG.md)
+- Quantum causal audit future direction: [`docs/research/QUANTUM_CAUSAL_AUDIT_FUTURE_DIRECTION.md`](docs/research/QUANTUM_CAUSAL_AUDIT_FUTURE_DIRECTION.md)
+- Causal invalidity patterns: [`docs/research/CAUSAL_INVALIDITY_PATTERNS.md`](docs/research/CAUSAL_INVALIDITY_PATTERNS.md)
+- Audit findings glossary: [`docs/audit/FINDINGS_GLOSSARY.md`](docs/audit/FINDINGS_GLOSSARY.md)
+- LTP / CML bridge: [`docs/LTP_CML_BRIDGE.md`](docs/LTP_CML_BRIDGE.md)
+- Roadmap: [`ROADMAP.md`](ROADMAP.md)
+- Security: [`SECURITY.md`](SECURITY.md)
+- License: [`LICENSE`](LICENSE)
+
+## Current artifact
+
+This repository already contains a working technical artifact, not only a concept.
+
+Current components include:
+
+- Python causal validation and audit engine;
+- causal chain reconstruction utilities;
+- CLI commands for lineage validation and chain inspection;
+- API layer and store interface;
+- example logs and audit outputs;
+- tests for chain logic, audit rules, and CTAG behavior;
+- API smoke tests for health, audit, and CTAG decode;
+- deterministic safety-eval benchmark with fixtures and tracked results;
+- documentation for vCML semantics and audit rules.
+
+Key implementation entry points:
+
+- `cml/audit.py`
+- `cml/chain.py`
+- `cli/main.py`
+- `api/server.py`
+- `tests/test_audit.py`
+- `tests/test_api_smoke.py`
+
+## Problem
+
+Many systems record events, outputs, traces, and metrics, but do not validate the causal structure behind authorization and action.
+
+That creates blind spots such as:
+
+- actions that appear valid but have no grounded parent cause;
+- ambiguous or malformed root authority;
+- actions that succeed operationally while losing approval lineage;
+- state transitions that cannot be tied back to intent, permission, and responsibility.
+
+For agentic systems, this matters because output review alone can miss causally invalid action chains.
+
+## What CML does
+
+CML checks whether a high-trust action or state transition was causally valid, not only whether it occurred.
+
+It focuses on:
+
+- validating causal links between actions and prior authorization;
+- preserving responsibility lineage across multi-step workflows;
+- checking intent and permission continuity across transitions;
+- detecting suspicious or invalid lineage such as missing parents, malformed roots, or broken handoffs;
+- validating causal coherence from structured logs and traces.
+
+## Evidence snapshot
+
+- Deterministic benchmark fixtures with expected audit findings: `benchmarks/fixtures/`
+- Current tracked benchmark result: `6/6 matched`
+- Benchmark runner: `python scripts/run_safety_eval.py`
+- Tracked report: `benchmarks/RESULTS.md`
+- Reviewer-friendly benchmark interpretation: `docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md`
+- Larger-grant expansion path: `docs/evidence/BENCHMARK_EXPANSION_PLAN_50K_100K.md`
+- External validation protocol: `docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md`
+
+## External reproducibility evidence
+
+External validation notes will be listed here as they are contributed.
+
+Current external validation tasks:
+
+- Full local validation path: [`#77`](https://github.com/safal207/Causal-Memory-Layer/issues/77)
+- MCP demo runner validation: [`#123`](https://github.com/safal207/Causal-Memory-Layer/issues/123)
+
+Validation note template:
+
+```text
+docs/evidence/external_validation/TEMPLATE_MCP_DEMO_RUNNER.md
+```
+
+This section is intentionally evidence-first: it should only list external notes after they are contributed. It does not claim production safety, compliance readiness, enforcement behavior, or stable Cause Band semantics.
+
+## Repository map
+
+- `cml/`: core Python implementation
+- `cli/`: command-line tooling
+- `api/`: API and store layer
+- `vcml/`: vCML semantics, format, audit, and boundary docs
+- `examples/`: sample logs and reports
+- `benchmarks/`: deterministic benchmark fixtures and results
+- `tests/`: regression coverage
+- `docs/`: supporting docs for review, research, and deployment
+
+## Scope
+
+CML does not claim to solve all AI safety, security, or compliance problems.
+
+It contributes one focused primitive:
+
+```text
+causal-validity checking for structured action traces
+```
+
+See [`docs/NON_CLAIMS.md`](docs/NON_CLAIMS.md) for the full scope boundary.
+
+## Research direction
+
+The strongest research direction for CML is causal validity checking for agentic oversight.
+
+A useful framing is:
+
+> How can we detect actions that appear valid at the surface level but are causally invalid because authorization, approval, or responsibility lineage is missing, ambiguous, or broken?
+
+## Bottom line
+
+A system may be functionally correct while being causally invalid.
+
+CML exists to make that distinction inspectable.

causal_memory_layer-0.4.0/api/__init__.py

@@ -0,0 +1 @@
+# api package