feat: add causal-temporal transition graph

[safal207]

Structure

This is a stacked draft PR on top of #169 (agent/ots-temporal-anchor-profile). It keeps the OTS adapter reviewable on its own while offering a separate causal-transition layer that maintainers can accept, revise, combine, or omit independently.

What changed

Adds an executable causal-temporal model around the provenance and OpenTimestamps chain:

• a three-axis product state for origin, freshness, and temporal facts;
• an explicit machine-readable transition graph;
• append-only causal events with seq, parent_event_id, state_before, state_after, evidence, observation time, immutable subject hash, and recomputable event_id;
• a terminal trace seal that commits to subject_hash + total_events + terminal_event_id + sealed_at;
• Mermaid views of the full chain and each state axis;
• 12 transition vectors and 6 sealed-completeness vectors;
• a read-only CI gate.

Why product state instead of one status

Freshness and temporal anchoring are independent. A live source can become STALE while the historical snapshot remains REPRODUCIBLE and ANCHORED. A scalar state would incorrectly erase one fact when another changes.

The temporal axis is monotonic for the same exact subject bytes: after ANCHORED, no transition may silently return the trace to PENDING, UNAVAILABLE, or INVALID. A later contradiction is recorded as a separate observation rather than rewriting history.

Deviations detected

The transition corpus detects:

• sequence gaps or duplicates;
• broken parent links;
• modified event bytes;
• subject-hash drift;
• local observation-time regression;
• undeclared event types;
• forbidden transitions;
• mutation of an unrelated state axis;
• missing evidence;
• OTS success without block/time bounds;
• attempted ANCHORED → PENDING regression.

The sealed corpus additionally detects:

• silently dropped suffixes;
• missing or tampered seals;
• wrong terminal event;
• seal-time regression.

Validation

Causal-temporal graph conformance passed: 12
Causal-temporal graph conformance passed: 6

Run with:

python3 scripts/check_causal_temporal_graph.py \
  conformance/guardrail-decision-v1/causal-temporal/graph.json \
  conformance/guardrail-decision-v1/causal-temporal/vectors.json

python3 scripts/check_causal_temporal_graph.py \
  conformance/guardrail-decision-v1/causal-temporal/graph.json \
  conformance/guardrail-decision-v1/causal-temporal/sealed-vectors.json

Scope boundary

This proves consistency and bounded completeness of recorded events. It does not prove that a producer chose the correct real-world seal boundary or that every external event was observed. Boundary authority and external witnessing remain separate governance layers.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f82b760c-1bd7-4ffe-888e-31f8ab5d9a2a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/causal-temporal-transition-graph

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}