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_keys, 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.