sb-iam
147 lines
2.8 KiB
Markdown
147 lines
2.8 KiB
Markdown
# 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
|
|
|
|
```text
|
|
PodGraph
|
|
podId
|
|
generatedAt
|
|
nodes
|
|
edges
|
|
metrics
|
|
loop?
|
|
activity?
|
|
```
|
|
|
|
Node kinds:
|
|
|
|
```text
|
|
engineer, feature, file, collision, intervention
|
|
```
|
|
|
|
Edge kinds:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|
|
|