Graph Modeling And Mutation

Graph modeling and mutation

Translate a domain change into canonical types, validate it, and apply the smallest governed mutation with a verification and rollback plan.

Action reference

Reversible derivations (truth maintenance)

A derived/computed node (a mined finding, a computed capability-index entry, a materialized view) registered as a live materialization auto-marks Stale the moment a committed change touches something it depends on — dependency-directed, paraconsistent (a contradiction elsewhere never cascades into unrelated stale-ing). Requires the opt-in epistemic-tms engine feature (both actions below degrade to {"error": ...} without it).

1. Write the derivation with its provenance intact: the node itself (graph_write(action="add_node", ...)) plus explicit DERIVED_FROM/ GENERATED_BY edges to every fact it actually depends on (graph_write(action="add_edge", ..., rel_type="DERIVED_FROM")). The engine reads exactly these edges — not a caller-supplied list — to build the dependency set, so get them right.
2. Register once: engine_query(action="register_materialization", params_json='{"derived_id": "<id>"}') → {"id", "depends_on", ...} — treat a shorter-than-expected depends_on list as a sign the dependency edges weren't written correctly.
3. Check freshness later: engine_query(action="materialization_status", params_json='{"id": "<id>"}') → "Fresh" / "Stale" / "Retracted" / null (never registered). On Stale, re-run whatever produced the derivation and re-register — there is no automatic recompute (see limits below).

Honest limits: the live CDC hook that marks dependents Stale fires on exactly two mutation shapes — RemoveNode/RemoveEdge (→ Deleted) and CompareAndSetNodeFields (→ Updated). A plain AddNode on a dependency is not mapped (no pre-image capture on that path), so adding a brand-new fact never staleness-marks a materialization that would logically depend on it — only removing or CAS-updating an existing dependency does. Nothing currently consumes staleness automatically — the engine computes the staled-id set on every qualifying mutation but drops it after logging; there is no scheduler, watcher, or Loop stage that reacts to a Stale materialization and recomputes it (a tracked, open gap, not something to paper over). The truth-maintenance index is in-memory, process-global, and resets on restart — re-register after a restart if you need continued tracking.

Workflow

1. Model before mutating

• Search the existing ontology and object model for an equivalent type or property.
• Extend the canonical model instead of creating a parallel vocabulary.
• Specify identity, required properties, relationship direction, cardinality, tenant scope, and lifecycle.
• Distinguish asserted facts from derived facts and memories.

Use graph_ontology, ontology_property_types, ontology_value_types, and ontology_interface to inspect or define the model. Use ontology_sampling_profile to ground a proposed type in representative data.

2. Select the mutation surface

Keep a simple, reversible update direct. Delegate a schema migration or multi-stage derivation through graph_workflows with explicit preconditions, postconditions, and approval boundaries.

3. Validate and preview

• Validate ontology connectivity and constraints before the data write.
• Confirm referenced nodes exist and identifiers are stable.
• Preview affected object counts with a bounded read.
• Define rollback or compensating operations before a high-impact change.

4. Apply atomically

For a design, review, or preview-only request, return the proposed model, affected counts, verification, and rollback plan, then stop before this stage.

• Use a transaction or compare-and-set operation when concurrent writers can race.
• Attach provenance, actor, observed time, and evidence to material changes.
• Keep derived artifacts linked to their inputs so they can be recomputed or retracted.
• Never broaden permissions as an incidental side effect.

5. Verify

• Read the changed objects through the normal query surface.
• Re-run constraints and check that unrelated objects did not change.
• Confirm retries are idempotent.
• Record the mutation outcome and any remaining manual action.

Use an economy model for inventory and deterministic conformance checks. Use a stronger reasoning model for ontology tradeoffs, migrations, and blast-radius judgment.

Guardrails

• Do not bypass policy, approval, or tenant boundaries.
• Do not use unbounded object sets for mutations.
• Do not embed credentials or private source data in ontology definitions.
• Do not claim success from an accepted job alone; verify the resulting state.