/graph-mutation-plan

name: graph-mutation-plan
description: Cookbook for composing an apply_graph_mutations plan — stable entity_key patterns, the canonical label/edge vocabulary, evidence/invalidation/confidence discipline, and a worked example. Load this when building a non-trivial mutation plan.
version: "1.0.0"
tags: [mutation, graph, ontology, reference]

Composing an `apply_graph_mutations` plan

Call `apply_graph_mutations(plan, event_id, summary)` once per logical group of mutations. The plan is idempotent on stable `entity_key`s, so a retried plan converges rather than duplicating. Every structural mutation must stay inside the given `pot_id` — never reference another pot.

Plan fields

• `summary`: one-line description of what this plan records.
• `episodes`: `{name, episode_body, source_description, reference_time?}` —

narrative/source text to retain (e.g. a PR body, a note).

• `entity_upserts`: `{entity_key, labels, properties}`.
• `edge_upserts`: `{edge_type, from_entity_key, to_entity_key, properties}`.
• `edge_deletes`: `{edge_type, from_entity_key, to_entity_key}`.
• `invalidations`: `{reason, target_entity_key?, edge_type?, from_entity_key?,

to_entity_key?}`.

• `evidence`: `{kind, ref, metadata?}` — what grounds this plan.
• `confidence`: float | null.
• `warnings`: list[str] — anything you could not confirm.

Stable entity_key cookbook

Use these so re-ingestion (and a later live webhook for a backfilled artifact) upserts the same node:

| Artifact | Key pattern | |---|---| | Repository | `github:repo:<owner>/<repo>` | | Pull request | `github:pr:<owner>/<repo>:<n>` | | Issue | `github:issue:<owner>/<repo>:<n>` | | Module / package | `module:<repo>:<dotted.path>` | | Feature | `feature:<repo>:<slug>` | | External ticket / issue | `ticket:<source>:<identifier>` | | Activity (timeline) | `timeline:activity:<verb>:<short_hex>` | | Period bucket | `timeline:period:daily:<pot_id>:<YYYY-MM-DD>` |

When no pattern fits, mint a deterministic key from stable identifiers in the source (never a random id, never a timestamp), so the same fact re-keys the same way.

Canonical vocabulary

Always give an entity at least one canonical label — never only generic `Entity`. Labels/edges outside the canonical vocabulary are downgraded automatically (entities → `Document` / `Observation`, edges → `RELATED_TO`), so prefer a canonical type when one fits.

**Entity labels** (topology — source of truth is `domain/ontology.py`): Repository, Service, Environment, DataStore, Cluster, Team, Person. Plus the work/knowledge types the playbooks reference: Activity, Feature, Decision, Fix, BugPattern, Incident, DiagnosticSignal, Module, Document.

**Edge types**: DEFINED_IN (Service→Repository), DEPLOYED_TO (Service→Environment), DEPENDS_ON (Service→Service), USES (Service→DataStore), HOSTED_ON (Environment→Cluster), OWNED_BY (Service/Repository→Team/Person), MEMBER_OF (Person→Team). For completed work, an Activity carries PERFORMED (→ the actor), TOUCHED (→ the modules/features it changed), and IN_PERIOD (→ the period bucket). Use RELATED_TO only when nothing canonical fits.

Discipline

• **Justify every mutation** from the event payload or a tool-observed fact. If

unsure, add a `warning` and keep the plan minimal — don't invent.

• **Supersession → invalidation.** When this event makes a prior fact untrue,

add an `invalidation` referencing the prior entity/edge rather than silently overwriting.

• **Evidence, not vibes.** Link the PR/issue/commit/url that grounds the plan

under `evidence`; set `confidence` lower when the inference is indirect.

Worked example — a merged PR that fixes a bug

{
  "summary": "PR #482 fixes the retry-storm in the billing worker",
  "episodes": [{
    "name": "PR #482 body",
    "episode_body": "<the PR description text>",
    "source_description": "github pull_request merged"
  }],
  "entity_upserts": [
    {"entity_key": "timeline:activity:merged:9f3a1c",
     "labels": ["Activity"],
     "properties": {"verb": "merged", "verb_class": "code", "title": "Merge PR #482"}},
    {"entity_key": "fix:billing:retry-storm",
     "labels": ["Fix"], "properties": {"title": "Bound billing retry backoff"}}
  ],
  "edge_upserts": [
    {"edge_type": "PERFORMED", "from_entity_key": "person:github:alice",
     "to_entity_key": "timeline:activity:merged:9f3a1c"},
    {"edge_type": "TOUCHED", "from_entity_key": "timeline:activity:merged:9f3a1c",
     "to_entity_key": "module:o/r:billing.worker"},
    {"edge_type": "RESOLVED", "from_entity_key": "fix:billing:retry-storm",
     "to_entity_key": "bug:billing:retry-storm"}
  ],
  "evidence": [{"kind": "pull_request", "ref": "github:pr:o/r:482"}],
  "confidence": 0.9,
  "warnings": []
}

Trivial PRs (typo/lint) need only the Activity — no Fix or Decision. Don't invent design decisions the PR body doesn't state.