decision_log — a 30-minute primer.

The decision_log is the spine under every move an agent makes. Thirty minutes here will make every other part of Magistry legible, because everything resolves to a row in this table.

The shape of a row

{
  "id": 84193,
  "agent": "catalog.specialist",
  "action": "ARCHIVE",
  "from_state": "winding_down",
  "to_state": "archived",
  "trigger": "no_sales_180d",
  "evidence": ["metrics_window#9m2"],
  "reverse_op": "RESTORE sku_4471 winding_down",
  "applied_at": "2026-05-18T07:42:11Z"
}

The signature chain

Each row is HMAC-signed and chained to its predecessor. A silent edit breaks the chain and is detectable, not invisible — which is what makes the log admissible as evidence rather than just a record.

The five first-week queries

• What did the agents do today? (action counts by agent)
• What did they want to do but couldn't? (rejected rows + blocking gate)
• What did we reverse, and why?
• Which gate blocks the most decisions?
• Which evidence rows recur across decisions?

Rollback as a row

To reverse an action you read its row and run the stored reverse_op — which creates a new row referencing the original. Nothing is edited in place. Finance loves this because 'undo' is itself an auditable fact, not a deletion.