shadowgraph_record_fact

Previous value: -"Who performed this write, e.g. an agent name."New value: +"Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust."

Previous value: -"Which client performed this write."New value: +"Which client software performed this write, such as the host application name."

Added value: +"How much the caller trusts this observation, 0-1. Defaults to 0.5. It does not verify anything."

Added value: +"ISO 8601 instant after which shadowgraph_maintain expires this fact. Combined with validTo, the earlier boundary wins."

Previous value: -"Retry key scoped by project and operation; reuse only for the same logical write."New value: +"Retry key scoped by project and operation: reuse it so a retry returns the first result instead of writing a duplicate. Without it every call creates a new entity."

Added value: +"Fact name, unique per project among active facts. Required and non-empty. Use the same key that a decision’s reopenWhen rules refer to."

Added value: +"Project namespace. Defaults to \"default\"; an empty string is rejected."

Previous value: -"Session identifier for this write."New value: +"Caller-owned identifier that groups related writes in the audit trail."

Previous value: -"Legacy alias for sourceClass. Unknown labels downgrade to agent_claimed with the raw label kept in sourceRaw."New value: +"Legacy alias for sourceClass. An unknown label downgrades to agent_claimed with the raw label kept in sourceRaw."

Previous value: -"Claimed origin class. A claim, not proof: no value here can make a fact verified."New value: +"Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw."

Previous value: -"Only `contradicted` may be set by a caller; `verified` and `expired` are rejected."New value: +"Only \"contradicted\" may be set by a caller, because it lowers trust. \"verified\" and \"expired\" are rejected: verification is not self-assertable and expiry is owned by shadowgraph_maintain."

Previous value: -nullNew value: +{
+  "description": "A stored fact with its provenance claim and validity window.",
+  "properties": {
+    "actor": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Who performed the write."
+    },
+    "client": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Which client performed the write."
+    },
+    "confidence": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Caller-declared confidence in the observation, 0-1."
+    },
+    "createdAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 creation time."
+    },
+    "expiresAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Caller-declared expiry instant, or null."
+    },
+    "id": {
+      "description": "Stable entity identifier.",
+      "type": "string"
+    },
+    "key": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Fact name, unique per project among active facts."
+    },
+    "kind": {
+      "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+      "type": "string"
+    },
+    "observedAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 time the fact was observed."
+    },
+    "project": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Project namespace; records imported from a schema that predates projects may carry null."
+    },
+    "schemaVersion": {
+      "description": "Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded.",
+      "type": "integer"
+    },
+    "sessionId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Session identifier recorded with the write."
+    },
+    "source": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Legacy alias of sourceClass, retained for compatibility."
+    },
+    "sourceClass": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Claimed origin class recorded with the write. A claim, never proof."
+    },
+    "sourceRaw": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The original origin label when it differed from sourceClass. Audit only; never evidence."
+    },
+    "status": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "active, superseded, or expired."
+    },
+    "temporal": {
+      "description": "Bi-temporal window: validFrom, validTo, recordedAt, invalidatedAt.",
+      "type": "object"
+    },
+    "updatedAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 time of the last change."
+    },
+    "validityPolicy": {
+      "description": "Declared expiry inputs and the effective expiration boundary derived from them.",
+      "type": "object"
+    },
+    "value": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        },
+        {
+          "type": "array"
+        },
+        {
+          "type": "object"
+        }
+      ],
+      "description": "The observed value, any lossless JSON value."
+    },
+    "verification": {
+      "description": "Present only on a signed verification: the attestation this build checked.",
+      "type": "object"
+    },
+    "verificationStatus": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "unverified, contradicted, expired, or verified. Only the separately configured signed-evidence verifier can produce verified."
+    }
+  },
+  "required": [
+    "key"
+  ],
+  "type": "object"
+}