podman/docs/graph-discovery/spec.md

Graph Discovery Spec

Status: draft
Scope: how PodMan discovers graph nodes, edges, risk paths, and learning paths from MongoDB
Owner: graph discovery / Team memory observatory

Purpose

Graph discovery turns MongoDB memory into a legible Team memory graph. It is not only layout. It decides which relationships matter, which path is highlighted, and which evidence explains the graph.

The graph must answer:

1. Who is working?
2. Which files or symbols overlap?
3. Where is the risk?
4. What did PodMan do?
5. What outcome changed memory?

Source Data

Graph discovery reads:

• pods
• engineer_states
• observations
• collisions
• interventions
• outcomes
• team_model
• graph_nodes
• graph_edges
• optional memory_vectors
• optional agent_runs
• optional strategy_versions

UI Graph Contract

PodGraph
  podId
  generatedAt
  nodes
  edges
  metrics
  loop?
  activity?

Node kinds:

engineer, feature, file, collision, intervention

Edge kinds:

owns, editing, touches, collides, warns, learned_from

Discovery Rules

Engineer nodes

Create from pod roster, recent observations, git state, or collision membership.

File nodes

Create only from normalized real file paths. Reject noise such as URLs, env values, scratch names, and non-file strings.

Collision nodes

Create from distinct collision signatures. Collapse repeats. Prioritize collisions referenced by accepted outcomes.

Intervention nodes

Create one visible intervention per surviving collision unless whole-graph mode explicitly expands history.

Learned paths

Create learned_from only when an accepted real outcome links an intervention to a durable memory update.

Path Modes

Risk path

Default mode. Highlight the clearest current chain:

engineer -> file -> collision -> intervention -> learned owner

Dim unrelated graph material.

Learning edges

Highlight learned_from, owns, and the outcomes that produced them.

Whole graph

Show all materialized nodes and edges with de-emphasized non-critical edges.

MongoDB Traversal

Use graph_edges for reachability:

source -> target -> next target

Primary traversal questions:

• What risks does this engineer reach?
• Which files feed this collision?
• Which intervention came from this collision?
• Which learned owner came from this intervention?

Metrics

Minimum metrics:

• Learned owners.
• Open risk paths.
• Accept rate.

Optional metrics:

• Observations.
• Interventions.
• Memory vectors.
• Strategy versions.

Acceptance Criteria

• Default graph is not a hairball.
• Every visible learned edge has outcome evidence.
• Every selected node can explain why it matters.
• Activity stream matches graph events.
• Graph can be rebuilt from MongoDB source records.