Q&A — Phase 17.1 TemporalGraph

[web3guru888]

Q&A — Phase 17.1 TemporalGraph

Q1: Why timestamp_ns: int instead of float for timestamps?

time.time_ns() returns an int with nanosecond precision and no floating-point rounding error. float has 53-bit mantissa precision (~15 decimal digits), which at nanosecond scale (18 digits) loses precision after ~10^4 seconds (~2.8 hours). Using int also enables exact equality checks and safe hash/freeze in the frozen=True dataclass.

---

Q2: How is AllenRelation enforced on add_edge()? Is it validated against actual timestamps?

In Phase 17.1, AllenRelation is a label supplied by the caller — it is stored and exposed to downstream components but not re-derived from timestamps. The DAG constraint is enforced by cycle detection, not Allen semantics. A future improvement (17.5 TemporalOrchestrator) can add a consistency check: e.g. if relation=BEFORE then from_node.timestamp_ns < to_node.timestamp_ns must hold. This two-phase approach keeps 17.1 simple while leaving room for stricter validation.

---

Q3: What is the time complexity of cycle detection? Is it acceptable at scale?

DFS cycle detection is O(V + E) per add_edge() call. For max_nodes=10_000 and a sparse graph this is typically <1 ms in CPython. The check runs synchronously inside asyncio.Lock, so it blocks the event loop briefly. For very dense graphs (>100K nodes), consider: (a) raising max_nodes limit only after profiling, or (b) switching to an incremental topological sort algorithm (O(log V) amortised per edge) in a future iteration.

---

Q4: How does pruning interact with causal chains? Can we lose important history?

Wall-clock pruning (timestamp_ns < horizon_ns) removes nodes regardless of whether they have successors. This is safe for recent-history use cases (EventSequencer, PredictiveEngine typically look back <1 hour). For longer-horizon causal tracing, two mitigations:

1. Increase prune_horizon_s (default 3600 s) in TemporalGraphConfig.
2. Mark important nodes with a special tag (e.g. tags=frozenset({"anchor"})) and extend prune() to skip anchored nodes.

---

Q5: What is the concurrency model? Can multiple coroutines call add_node() safely?

Yes. Every mutating method (add_node, add_edge, prune) acquires asyncio.Lock before touching shared state. Because asyncio is single-threaded, there is no true parallelism — Lock prevents interleaving between coroutines at await boundaries. Read methods (get_successors, get_predecessors) also hold the lock to avoid torn reads during concurrent mutations.

---

Q6: How does TemporalGraph integrate with WorldModel.update() from Phase 13?

The recommended wiring:

# Inside CognitiveCycle._perception_step()
new_state = await world_model.update(observation)
node = TemporalNode(
    node_id=str(uuid.uuid4()),
    timestamp_ns=time.time_ns(),
    state_snapshot=new_state.to_dict(),
    tags=frozenset({"percept"}),
)
await temporal_graph.add_node(node)
# Connect to previous node
if prev_node_id:
    edge = TemporalEdge(prev_node_id, node.node_id, AllenRelation.BEFORE,
                        node.timestamp_ns - prev_timestamp_ns)
    await temporal_graph.add_edge(edge)

This creates a linear causal chain through perception steps; branching edges are added when goals split or parallel paths emerge.

---

Q7: How do I build a Grafana timeline panel showing TemporalGraph events?

# Grafana panel config (Timeline visualization)
panelType: timeline
title: TemporalGraph Events
targets:
  - expr: asi_temporal_graph_size
    legendFormat: live_nodes
  - expr: rate(asi_temporal_graph_nodes_total[30s]) * 30
    legendFormat: nodes_per_30s
  - expr: rate(asi_temporal_graph_cycle_rejections_total[5m])
    legendFormat: cycle_rejections_rate
fieldConfig:
  defaults:
    color:
      mode: palette-classic
options:
  mergeValues: false
  showValue: auto

For a true timeline (event-by-event), export nodes to a time-series data source (e.g. InfluxDB or Loki) tagged by node_id and tags.

---

Full spec: Issue #434 · Show & Tell: Discussion #435 · Phase 17 Planning: Discussion #433