y-graph-codex

Purpose

Read SummaryRoot JSON and emit a minimal graph representation focused on user messages, decisions, files, artifacts, and objective/outcome. Attach the graph JSON as a git note under namespace y-codex-session-graph.

Inputs

• •SummaryRoot JSON path (absolute or relative).
• •Output directory for graph.json.

Required Output

• •graph.json: GraphRoot JSON.
• •Git note: write full graph.json body under namespace y-codex-session-graph for the commit.

Graph Schema (GraphRoot)

{
  "schema_version": "1",
  "nodes": [
    { "id": "...", "type": "...", "data": { "label": "...", "detail": "...", "timestamp": "...", "evidence_refs": ["..."] } }
  ],
  "edges": [
    { "id": "...", "source": "...", "target": "...", "type": "...", "label": "..." }
  ],
  "meta": { "commit": "..." }
}

• •This structure is React Flow-ready (nodes/edges only, no positions).

Determinism Rules

• •Use stable ordering: by timestamp when present, then by original index.
• •Use deterministic IDs, e.g. sha256("<kind>|<timestamp>|<label>|<index>").
• •Do not use random values.

Nodes to Create

• •message nodes from user_message_ledger.messages.
• •decision nodes from decisions_and_tradeoffs.decisions.
• •file nodes from files_edited_and_why.files.
• •artifact nodes from structured_output_artifacts.artifacts plus JSON/markdown summary pointers.
• •objective and outcome nodes from executive_summary.

Edges to Create

• •message_sequence: message[i] -> message[i+1].
• •message_to_decision: if decision rationale evidence references a user evidence record that matches message timestamp or snippet overlap.
• •decision_to_file: if decision rationale evidence and file.why share any evidence id.
• •decision_to_artifact: if decision rationale mentions artifact location in text.
• •objective_to_decision and decision_to_outcome for overall flow.

Validation

• •Ensure unique IDs.
• •Ensure all edges reference existing node IDs.
• •Ensure at least one node exists; otherwise fail with an actionable error.

Notes

• •Include evidence refs in node data.evidence_refs where they exist.
• •Keep node label short and readable; put long text in detail.