Cortex Forensic Debugger (CFD) Architectural Spec

Tags: #C5-REAL #BehavioralCryptography #TemporalLattice

This document specifies the core abstractions, cryptographic verification rules, state reconstruction algorithms, and forensic backtracking protocols implemented in the Cortex Forensic Debugger (CFD).

1. Directed Acyclic Temporal Graph (DATG)

Instead of linear logs, CFD models multi-agent cognitive executions as a Directed Acyclic Temporal Graph (DATG) lattice. This allows for natural branching (divergent decisions), observation forks (perceptual divergence), and injection forks (external mutations).

1.1 Node Data Schema

Every node in the temporal lattice is defined as a TraceNode:

@dataclass
class TraceNode:
    node_id: str             # Unique identifier (Node Hash)
    agent_id: str            # Agent instance emitting the transition
    seq: int                 # Monotonically increasing sequence number within the agent's branch
    timestamp: float         # Clock epoch representing the state transition time
    event: dict              # Transition event containing action/reasoning details
    state_delta: dict        # State mutations applied at this node
    prev_hash: str           # Cryptographic link to previous node in the timeline
    hash: str                # Current node hash
    parents: list[str]       # Collection of ancestor node hashes (multi-agent causality / merges)
    fork_type: Optional[str] # Fork classification: "natural" | "observation" | "injection"

1.2 Cryptographic Hash Model

Node hashes are computed deterministically based on sequential dependencies and topological parent structures:

$$H_n = \text{SHA256}\left(\text{prev_hash} \mathbin{\Vert} \text{event_str} \mathbin{\Vert} \text{seq} \mathbin{\Vert} \text{agent_id} \mathbin{\Vert} \text{schema_version} \mathbin{\Vert} \text{bundle}(\text{parents})\right)$$

Where:

• $\text{event_str}$ is the canonical JSON representation of the transition event (whitespace minimized, keys sorted).
• $\text{bundle}(\text{parents})$ is the comma-separated sorted concatenation of parent node IDs.

2. Topological & Cryptographic Audit Rules

Verification of an execution branch is governed by three mathematical invariants:

1. Sequential Monotonicity: $$S_i = S_0 + i \quad \forall i \in [0, N]$$
2. Cryptographic Lineage: $$H_{prev, i} = H_{i-1} \quad \forall i \in [1, N]$$
3. Topological Predecessor Containment: $$\text{node}_{i-1} \in \text{parents}(\text{node}_i) \quad \forall i \in [1, N]$$

This third invariant guarantees that reordering attacks (e.g. event swapping) will topologically violate parent configurations, failing verification.

3. State Reconstruction & Merge Mechanics

The state of any agent at any arbitrary point in the lattice is reconstructed by executing the cumulative state delta functions along the causal path of the target node.

3.1 State Representation

@dataclass
class AgentState:
    memory: dict
    beliefs: dict
    goals: list
    context_stack: list

3.2 State Traversal Algorithm

To reconstruct the state at node $N$:

1. Compute the topological causal path from the genesis node(s) to $N$.
2. For each node in the path:
   • If the node has $1$ parent: retrieve parent state.
   • If the node has $>1$ parents (Merge node): resolve state merge.
   • Apply state_delta recursively.

def patch_state(old: AgentState, delta: dict) -> AgentState:
    return AgentState(
        memory=patch_dict(old.memory, delta.get("memory", {})),
        beliefs=patch_dict(old.beliefs, delta.get("beliefs", {})),
        goals=delta.get("goals", old.goals),
        context_stack=delta.get("context_stack", old.context_stack)
    )

3.3 Merge Resolution Strategies

When merging multiple divergent states ($S_A, S_B$) at a sync event node:

4. Forensic Audit Operations

4.1 Causal Backtracking

Traces backward along the chronological path to extract every instance of transition where a specific variable key changed in memory or beliefs. This isolates the exact sequence of reasoning/action steps that led to an execution outcome.

4.2 Divergence Heatmap

Calculates topological branching frequencies: $$D(n) = | \text{children}(n) | \quad \text{where } D(n) > 1$$ Nodes with high child counts indicate frequent decision divergence or environment branching.

4.3 Agent Comparative Diffing

Identifies the Lowest Common Ancestor (LCA) between two agent head nodes, returning the respective path extensions and evaluating the exact state variance between both final execution states.

5. Verification Execution

Verification tests demonstrate perfect compliance of the CFD engine against synthetic, branching, and corrupted traces.

# Verify branching CFD engine (v2.0.0)
PYTHONPATH=packages/cortex-persist-python uv run python asi-1-lab/experiments/verify_cfd.py

=== CORTEX FORENSIC DEBUGGER (CFD) v2.0.0 ===
Loaded 4 trace nodes from DATG.
  Branch 'system': VALID
  Branch 'agent_a': VALID
  Branch 'agent_b': VALID
[SUCCESS] All branches verified successfully.

--- COMPARING AGENTS: agent_a vs agent_b ---
Lowest Common Ancestor (LCA): n0
Agent agent_a sub-path extensions: ['n1_a', 'n2']
Agent agent_b sub-path extensions: ['n1_b']
[SUCCESS] Multi-Agent CFD Verification Complete. 100% congruent.

# Verify legacy corruption test-suite (v1.0 & v1.1)
PYTHONPATH=packages/cortex-persist-python uv run python asi-1-lab/experiments/run_corruption_test.py

--- RUNNING Valid Trace ---
[PASS] Replay CLI successfully verified the trace (Valid Trace).
--- RUNNING Payload Corruption ---
[PASS] Replay CLI correctly rejected the corrupted trace (Payload Corruption).
--- RUNNING Sequence Gap ---
[PASS] Replay CLI correctly rejected the corrupted trace (Sequence Gap).
--- RUNNING Event Swap ---
[PASS] Replay CLI correctly rejected the corrupted trace (Event Swap).
--- RUNNING Metadata Corruption ---
[PASS] Replay CLI correctly rejected the corrupted trace (Metadata Corruption).
--- ALL TESTS PASSED ---