govern_fact

Category: intel
Access: write
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Applies truth maintenance to a canonical fact: supersede, contradict, invalidate, or revalidate. Call it when knowledge changes rather than editing facts in place.

Arguments

Required: fact_id, action.

Optional: effective_at, rationale, target_fact_id.

fact_id.
action. Note: One of supersede, contradict, invalidate, revalidate.
effective_at. Note: ISO timestamp; defaults to now. Empty string behaves as absent.
rationale. Note: Recorded in the decision artifact and history; empty string behaves as absent.
target_fact_id. Note: Required for supersede and contradict; must differ from fact_id and exist. Empty string behaves as absent.

Result

Object with fact_id, action, target_fact_id (null unless supersede/contradict), effective_at, and changed (always true on success).

Boundaries

Operates inside the selected profile boundary. Truth maintenance only; entries are never physically removed.

Lifecycle / side effects

Applies the lifecycle change (supersede stamps validity end and successor links; contradict links both directions; invalidate ends validity; revalidate clears validity end and successor links), refreshes contradiction counts, records a fact history event, and persists a decision artifact. Always reports changed true on success; all-or-nothing.

Errors

Unsupported action, missing target, self-target, or unknown fact/target return normal error payloads. Validation rejects missing fact_id/action and unknown arguments.

Example

{
  "action": "invalidate",
  "fact_id": "<uuid>",
  "rationale": "superseded by field trial"
}

Result shape:

{
  "action": "invalidate",
  "changed": true,
  "effective_at": "<iso-8601>",
  "fact_id": "<uuid>",
  "target_fact_id": null
}