CSuite — Agent Loop v1 (Official Specification)

Status

• Version: v1.0
• State: Stable / Production
• Last updated: 2026-01-01

1. Purpose

This document defines the canonical Agent Loop adopted by the CSuite ecosystem.

The Agent Loop standardizes how the platform:
- Observes reality (Signals)
- Freezes context
- Makes decisions
- Executes actions
- Observes outcomes
- Learns from results

This is a decision-centric, causal, and auditable loop, designed for:
- Governance
- Risk control
- Progressive autonomy
- Institutional memory

2. Core Principles (Non-Negotiable)

1. Decision-First Architecture
   Every loop is anchored by decision_log_id.

2. Context Immutability
   Context used for a decision must be frozen and auditable.

3. Separation of Concerns
   Decision ≠ Execution ≠ Outcome.

4. Outcome Closure
   Every executed action must eventually produce an observed outcome.

5. Explicit Causality
   All links (Decision → Action → Outcome) must be explainable.

6. Memory is Derived, Not Written
   Memory is generated from observed outcomes, never manually curated.

3. Canonical Loop

Signal → Context → Decision → Execution → Outcome → Memory

This loop may execute continuously and asynchronously.

4. Canonical Entities

4.1 Signal

A raw event that triggers evaluation.

Examples:
- Customer interaction
- Stock change
- SLA breach
- Policy drift

4.2 Decision

Formal evaluation result produced by the Policy Engine.

Source of truth:
- csuite_executive.pg_decision_log

Key attributes:
- decision_log_id (anchor)
- decision_code
- subject_type / subject_ref
- outcome (ALLOW / RECOMMEND / ESCALATE / DENY)
- reasons_json
- latency_ms

4.3 Context Snapshot

Frozen representation of the world at decision time.

Source of truth:
- csuite_context.ctx_decision_context_snapshot

Rules:
- Exactly one snapshot per decision
- Immutable by default
- Versioned by schema_version

4.4 Execution Action

Concrete action derived from a decision.

Source of truth:
- csuite_execution.execution_action_ledger

Rules:
- One decision → zero or many actions
- Must reference decision_log_id
- Generates action_id for strong linking

4.5 Outcome

Observed result of an execution.

Source of truth:
- csuite_context.ctx_policy_outcomes

Rules:
- Must reference decision_log_id (preferred)
- May reference action_id
- Always records before/after metrics

4.6 Memory (Precedent)

Institutional learning derived from outcomes.

Source of truth:
- csuite_memory.mm_item (layer: PRECEDENTS)

Rules:
- Generated only from closed outcomes
- Weighted by confidence and impact
- Never manually edited

5. Data Contracts

5.1 Loop Anchor

decision_log_id is the universal join key.

All entities MUST be linkable to it.

5.2 Outcome Matching (Hardening v1)

Matching hierarchy:
1. Action ID (score = 100)
2. Entity + Policy + Temporal window (score ≥ threshold)
3. No match (do not guess)

Matching metadata is mandatory:
- match_method
- match_score
- matched_at
- matched_by
- match_debug_json

6. Runtime Flow (Canonical)

1. Signal is ingested
2. Policy Engine evaluates → decision recorded
3. Context snapshot is frozen
4. Execution actions are dispatched
5. Outcome is observed and recorded
6. Memory is generated asynchronously

7. Backfill Strategy

Backfill exists only for historical data.

Rules:
- Uses scoring
- Is auditable
- Is reversible
- Never overrides real-time links

Primary procedure:
- sp_ctx_backfill_outcome_decision_log_id_v2

8. Memory Feeding

Memory is generated from the Decision Timeline view.

Procedure:
- csuite_memory.sp_ctx_feed_memory_from_timeline

Rules:
- Only outcomes with sufficient confidence
- One precedent per decision
- Structured, causal content

9. Autonomy Levels

Promotion requires:
- High outcome success
- Low reversal rate
- Strong matching confidence
- Stable policy behavior

10. Observability & SLOs

• Snapshot Coverage ≥ 99%
• Outcome Closure ≥ 95%
• Average Match Score ≥ 90

11. Non-Goals

• This spec does NOT define UI layout
• This spec does NOT mandate LLM usage
• This spec does NOT prescribe business logic

12. Status

This specification is authoritative for all CSuite agentic workflows.

Any new agent, policy, or automation MUST conform to Agent Loop v1.