The operating record and control plane for governed decisions.

Why it exists

Generation and advice tools produce text. Decisions produce structured intent: typed, confidence-scored, and routable. The Decision is the first-class record of what the system chose and why — the object other primitives thread from.

Execution semantics

A Decision does not execute on creation. It is evaluated against Policy and enqueued as a Workflow. Execution writes Mutation Log entries. A Decision with auto_executable=true and a passing Policy evaluation may execute without human approval; otherwise it pauses for approval.

Example

{
  "id": "dec_01HXA7M4B8N3RXQK9VPYZW2QF4",
  "type": "adjust_budget",
  "priority": "high",
  "confidence": 0.82,
  "summary": "Raise Meta Search Demand budget to $720/day",
  "reasoning": "Qualified-quote signal rose 18% week-over-week on category 'replacement-parts-heavy-equipment'. Current budget is capped at last week's lower demand band.",
  "auto_executable": false,
  "action": {
    "type": "adjust_budget",
    "campaign_id": "cmp_meta_4921",
    "channel": "meta",
    "target_budget": 720,
    "reason": "rising_qualified_demand"
  },
  "campaign_id": "cmp_meta_4921",
  "computed_at": "2026-04-22T14:02:18Z",
  "policy_version": "policy-2026-04-15"
}

Why it exists

A dashboard helps a person follow a process. A Policy enforces one. Budget caps, approved-claim libraries, distributor contracts, daily spend ceilings, and risk thresholds are encoded as named, versioned rules. Every Decision carries the Policy version it was evaluated against.

Execution semantics

Policy evaluation returns one of three results: allow, require_approval, or deny. Allow proceeds to Workflow. Require_approval pauses the Workflow and surfaces an approval request. Deny halts execution and writes a refusal event. Policy versions are immutable; a change creates a new version and old evaluations keep their citation.

Example

{
  "evaluation_id": "eval_01HXA7M4C2K9RXQK9VPYZW2QF4",
  "decision_id": "dec_01HXA7M4B8N3RXQK9VPYZW2QF4",
  "decision": "require_approval",
  "requires_approval": true,
  "triggered_policies": [
    {
      "policy_id": "budget_daily_cap",
      "decision": "require_approval",
      "reason": "Target budget $720/day exceeds auto-executable cap of $500/day.",
      "requires_approval": true,
      "constraint": "daily_cap_micros=500000000"
    }
  ],
  "bypassed_policies": [],
  "evaluated_at": "2026-04-22T14:02:18Z"
}

Why it exists

Ad operations are rarely one-shot. A budget change may pause for approval, run across multiple platform APIs, and write several log entries. Workflows make the full path durable: pausable, resumable, idempotent, and compensatable on failure — properties an agency spreadsheet or ad-platform UI cannot provide.

Execution semantics

Workflows carry an idempotency_key so retries do not double-execute. Steps may compensate on failure (e.g. roll back a partial budget write). Runs progress through queued, running, paused_for_approval, completed, failed, timed_out, or compensated states. Only completed and compensated are terminal success/failure states in the public contract.

Example

{
  "run_id": "wf_01HXA7M4D3L0RXQK9VPYZW2QF4",
  "workflow_id": "execute_budget_adjustment",
  "status": "paused_for_approval",
  "idempotency_key": "dec_01HXA7M4B8N3RXQK9VPYZW2QF4-attempt-1",
  "current_step_id": "await_approval",
  "requested_by": "agent:claude-desktop",
  "org_id": "org_01HW3T9P2Q8YXZ3N5B7C9DFA2V",
  "retry_count": 0,
  "awaiting_approval": true,
  "created_at": "2026-04-22T14:02:19Z",
  "updated_at": "2026-04-22T14:02:20Z"
}

Why it exists

Every change across Google, Meta, Amazon, Pinterest, and X is logged against a decision_id. That makes advertising operations queryable: 'what changed on this campaign, under which decision, caused by which signal, approved by whom' is one query, not a forensic exercise.

Execution semantics

Entries are append-only. Status progresses through pending, success, failed, or rolled_back. A rolled_back entry is written by a compensation step, not deleted. The decision_id is the stable join back to Decision, Policy evaluation, and Workflow run.

Example

{
  "mutation_id": "mut_01HXA7M4E4M1RXQK9VPYZW2QF4",
  "decision_id": "dec_01HXA7M4B8N3RXQK9VPYZW2QF4",
  "org_id": "org_01HW3T9P2Q8YXZ3N5B7C9DFA2V",
  "campaign_id": "cmp_meta_4921",
  "platform": "meta",
  "platform_campaign_id": "23854192...",
  "mutation_type": "update_budget",
  "payload": { "daily_budget_micros": 720000000 },
  "result": { "applied_at": "2026-04-22T14:04:02Z" },
  "status": "success",
  "actor_type": "agent:claude-desktop",
  "error_message": null
}