shadowgraph_record_decision

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."

Added value: +"Options considered and rejected. Alternatives belong to the decision and have no separate write API; they are what shadowgraph_review reconsiders."

Added value: +"Name of the rejected option. Required in practice: an alternative without a non-empty label is rejected."

Added value: +"Accepted as an alias of reasonRejected for older callers."

Added value: +"Why it was rejected. Searchable content."

Added value: +"Rules that make this alternative worth reconsidering. Each is either a fact key as a plain string, matched only against changedFacts, or an object { key, operator, value } evaluated against stored facts so it still fires after a restart. operator defaults to equals."

Added value: +"What the decision takes for granted. Record each as a fact too if it should be able to reopen the decision."

Added value: +"The option actually chosen. Required, non-empty, and searchable content."

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

Added value: +"Starting confidence, 0-1. Defaults to 0.5. Later outcomes and evidence move it from this baseline; it is a degree of belief, never a verification status."

Added value: +"Supporting evidence. Counted as declared evidence in the confidence basis, but never re-checked."

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "additionalProperties": true,
-    "properties": {
-      "confidence": {
-        "maximum": 1,
-        "minimum": 0,
-        "type": "number"
-      },
-      "detail": {
-        "type": "string"
-      },
-      "observedAt": {
-        "type": "string"
-      },
-      "source": {
-        "type": "string"
-      },
-      "sourceClass": {
-        "enum": [
-          "agent_claimed",
-          "tool_observed",
-          "human_confirmed",
-          "production_verified"
-        ],
-        "type": "string"
-      },
-      "type": {
-        "type": "string"
-      }
-    },
-    "type": "object"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "additionalProperties": true,
+    "properties": {
+      "confidence": {
+        "description": "How much weight the caller places on this item, 0-1. Defaults to 0.5.",
+        "maximum": 1,
+        "minimum": 0,
+        "type": "number"
+      },
+      "detail": {
+        "description": "Free-text detail. Searchable content.",
+        "type": "string"
+      },
+      "observedAt": {
+        "description": "ISO 8601 timestamp of the observation. Defaults to the time of the write.",
+        "type": "string"
+      },
+      "source": {
+        "description": "Where the evidence came from, such as a document, ticket, or command. Searchable content.",
+        "type": "string"
+      },
+      "sourceClass": {
+        "description": "Claimed origin class for this item; an unrecognised value downgrades to agent_claimed.",
+        "enum": [
+          "agent_claimed",
+          "tool_observed",
+          "human_confirmed",
+          "production_verified"
+        ],
+        "type": "string"
+      },
+      "type": {
+        "description": "Free-form evidence kind, such as benchmark, incident, or review.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  }
+]

Added value: +"One piece of supporting evidence. A plain string is stored as its source; an object carries structured provenance. Nothing here is checked or re-verified: it records what the caller claimed."

Added value: +"What the decision is meant to achieve. Searchable content."

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: +"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: -"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."

Added value: +"Short name of the decision. Required, non-empty, and searchable content."

Previous value: -nullNew value: +{
+  "description": "A stored decision, including its alternatives and auditable confidence basis.",
+  "properties": {
+    "actor": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Who performed the write."
+    },
+    "alternatives": {
+      "description": "Rejected alternatives, each with id, label, reasonRejected, status, and the reopenWhen rules that make it reconsiderable.",
+      "type": "array"
+    },
+    "assumptions": {
+      "description": "Assumptions the decision rests on. Searchable content.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "chosen": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The option that was chosen."
+    },
+    "client": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Which client performed the write."
+    },
+    "confidence": {
+      "description": "Auditable confidence: initial, current (0-1), policy, a history entry per move, and a basis summarising the contributions it was folded from. Legacy records may lack basis.",
+      "type": "object"
+    },
+    "createdAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 creation time."
+    },
+    "evidence": {
+      "description": "Normalised evidence entries: source, type, sourceClass, confidence, observedAt, detail.",
+      "type": "array"
+    },
+    "failedAttempts": {
+      "description": "Attempt identifiers or notes attached to this decision.",
+      "type": "array"
+    },
+    "goal": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "What the decision was trying to achieve."
+    },
+    "id": {
+      "description": "Stable entity identifier.",
+      "type": "string"
+    },
+    "kind": {
+      "description": "Entity kind: decision, attempt, memory, fact, relation, review, or alternative.",
+      "type": "string"
+    },
+    "migration": {
+      "description": "Present only on migrated records; records the legacy value a field was mapped from.",
+      "type": "object"
+    },
+    "outcome": {
+      "anyOf": [
+        {
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The recorded outcome, or null until one is recorded."
+    },
+    "project": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Project namespace; records imported from a schema that predates projects may carry null."
+    },
+    "reviewAfter": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 instant after which shadowgraph_maintain marks this decision stale."
+    },
+    "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."
+    },
+    "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": "Lifecycle state. Legacy records may carry a value this build does not recognise; shadowgraph_validate reports those."
+    },
+    "supersededBy": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Identifier of the decision that replaced this one."
+    },
+    "supersedes": {
+      "description": "Identifiers of decisions this one replaced.",
+      "type": "array"
+    },
+    "title": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Short name of the decision."
+    },
+    "updatedAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ISO 8601 time of the last change."
+    }
+  },
+  "required": [
+    "id",
+    "kind"
+  ],
+  "type": "object"
+}