Cognitive Core

The Cognitive Core spans the Context plane (the Compiler) and the Decision plane (the cognitive loop). It is the runtime that compiles a bounded Context Pack and then drives the layered loop that produces a Decision Record.

Definition

A two-half runtime: (a) the Context Pack Compiler turns intent + Run Context + pack references into a CompiledContext envelope; (b) the cognitive loop advances a turn through perception, attention, identity, goals, judgment, policy gate, action, consolidation, and reflection under a Run Context with explicit budgets and loop guards.

This is the runtime architecture contract. The repository implements the deterministic compiler and additive execution validators, with synthetic useful/failure cases; it does not supply the production loop, identity provider, sandbox or durable store. The Execution Contract connects exact profile admission to current authority, active boundaries, data movement, operations and aggregate budgets. Conformance separates those reference checks from demonstrated deployment enforcement.

Why it exists

LLMs are non-deterministic and context-hungry. Without a compiler, every team rolls its own prompt assembly and drifts. Without a layered loop, the runtime cannot be inspected step-by-step or recovered from failure. The Cognitive Core gives the spec a single, layered, replayable boundary between the model and everything else.

How it works

1. Compile: the Context Pack Compiler labels, admits, and budgets intelligence + memory + policy + tools into a bounded CompiledContext.
2. Loop: the cognitive loop advances one turn at a time, with each layer reading and writing the Run Context.
3. Decide: the Planner / Executor / Critic triad inside the loop produces a typed Decision Record.
4. Govern: every layer is policy-aware; effects route through the Tool Gateway under native action risk, explicit authority, and v1 compatibility controls.
5. Observe: every layer emits OTEL spans tied to the run’s trace_id.

Cognitive loop (turn-level layers)

Each turn decomposes into a layered loop. Deterministic state transformations can be pure; model calls, tool effects, persistence and heartbeat delivery are external operations with explicit observations. The table describes logical runtime state alongside the serialized RunContext, not extra fields to inject into its closed v1 envelope. Layers carry its correlation and control inputs without bypassing the execution boundary.

The Run Context (run_id, trace_id, session_id, tenant_id, safety_mode, run_budget) flows through every layer so each step is independently traceable. read_only excludes mutating capabilities; permitted read tools still execute through the Action-plane gateway with authority, data and budget checks. Replay uses recorded observations rather than repeating live effects.

Context Pack Compiler

The compiler is a pure pipeline:

1. Intent classification — resolve raw input to an intent in the Intent-Task Catalog.
2. Policy resolution — evaluate applicable JsonLogic rules against the Run Context; produce must_refuse, must_escalate, requires_approval_gate, prohibited_capabilities. An applicable predicate exception throws a sanitized ContextCompileError and stops compilation; ordinary false predicates keep their false/else behavior.
3. Tool surfacing — intersect Registry ∩ Permissions − Prohibitions, apply native-risk policy, and enforce the v1 RunContext.safety_mode ceiling.
4. Evidence normalization — accept caller-retrieved candidates and conflict markers, verify content hashes, and label source, integrity, freshness, and covered requirements.
5. Memory recall — pull promoted memory only (never raw capture), preserving its source lineage and freshness.
6. Token budget allocation — distribute the run budget across context buckets (business, policy, tool, evidence, memory, session).
7. Bucket admission and assembly — assign control or data_only, reject ineligible evidence, pack each bucket, and record every budget omission.
8. Manifests + runtime controls — evaluate sufficiency, then emit the admitted evidence_manifest, context_admission, and conflict-aware per-decision evidence_gates with the rest of CompiledContext.

Two non-model gates

The Cognitive Core places two deterministic checks around model reasoning:

1. Context admission, before reasoning. Every block receives provenance, integrity, freshness, and instruction treatment. Pack, policy, and tool-registry material may be control; retrieval and memory remain data_only, even when verified.
2. Evidence gating, before commit. A DecisionSpec.required_evidence item is satisfied only by admitted, current, verified, conflict-free evidence or by explicit structured request context. Untrusted, stale, unknown-freshness, budget-omitted, unresolved-conflict, and resolution-superseded evidence is listed in rejected_evidence. A known unresolved conflict marks the view insufficient and keeps commit_allowed: false even when each source is individually verified.

The model may reason about rejected or untrusted material as data when policy permits, but it cannot promote that material into authority. For an effect, the Tool Gateway must also re-check the actual arguments and their provenance immediately before execution.

Triple-check governance

Before any action, the runtime enforces three checks in order:

1. Permission level — is the tool generally allowed for this agent role?
2. Rule level — is the tool allowed for this specific intent?
3. Situational level — is the action safe given admitted, current, verified evidence (e.g., order.age_days > 30)?

Known compile-time prohibitions remove a capability from the surfaced manifest. Fresh external state, exact proposed arguments and current authority may only be available later; their dispatch-time checks still block the action even if the tool was surfaced earlier. An evidence gate’s commit_allowed is a sufficiency result, not authenticated execution authority. Caller-supplied request/evidence labels need trusted admission before they can stand for verified external facts.

Turn budgets and loop guards

Each turn declares a budget envelope; the runtime enforces it deterministically rather than trusting the model.

• Token budget per Context Pack bucket.
• Tool-call budget per turn and per workflow.
• Wall-clock budget with heartbeat for long-running sessions.
• Loop guard: repeated identical tool calls or no-progress reflection cycles short-circuit with a structured loop_detected reason returned to the planner.
• Re-plan budget: capped re-planning attempts to prevent infinite loops.

Production budget updates must be atomic so parallel lanes cannot race. The additive BudgetLedger reference reserves root/child/retry/replan capacity against original ceilings and a shared absolute deadline, with exact declared cost units. It returns intended revision/fence transitions; a deployment store must actually enforce them. Resume cannot restore spent capacity, and uncertain usage retains its reservation.

Functional state and pressure signals

Beyond the deterministic Run Budget, the runtime carries a functional state snapshot per turn — a typed, bounded scalar set that captures the current pressure on the loop. Functional state is observable by the Critic (informs accept / escalate verdicts) and never mutates the policy boundary or model behavior directly.

{
  "functional_state": {
    "captured_at": "2026-05-04T09:31:18Z",
    "budget_pressure": 0.62,
    "loop_pressure": 0.10,
    "evidence_pressure": 0.00,
    "gate_pressure": 0.34,
    "conflict_pressure": 0.00,
    "escalation_propensity": 0.41
  }
}

Properties

• Captured at every turn boundary; persisted on the Decision Record’s lineage block.
• Read-only for Judgment and Action layers; the model never sees raw scalars.
• The Critic may use elevated escalation_propensity to prefer escalate over replan when otherwise tied.
• The Improvement Loop treats sustained high-pressure runs as candidate insights.

Implementation mapping

These components and contracts implement the Cognitive Core at runtime:

• Conversation Manager, Intent/Risk Classifier, Intent-Task Catalog
• Context Pack Compiler, Policy Engine, Orchestrator, Tool Manager
• Decision Catalog, Knowledge Substrate, Memory Fabric
• Evaluation Engine, Observability

Implementation references

• Context Pack
• API Contracts
• Agentic Context Engineering
• Decision Catalog
• Workflow Examples

Interfaces

Inputs

• invokeAgent request envelope
• Run Context (run_id, trace_id, session_id, tenant_id, safety_mode, run_budget, user, agent)
• Pinned Context Pack version(s)
• Knowledge Graph snapshot
• Memory state (working / episodic / semantic / durable)

Outputs

• CompiledContext (prompt, manifests, runtime_controls, budget_report)
• Decision Record (decision_id, evidence_refs, approvals, controls_active)
• Tool transcripts and evidence manifest
• Memory write proposals
• Trace bundle

Failure modes

• Context overpacked — silent truncation hides evidence; mitigated by always-explicit truncated flag.
• Retrieved instructions gain control authority — prevented by instruction_treatment: "data_only" on evidence and memory.
• Stale, untrusted, or unknown-freshness evidence closes a decision gate — compiler defect; only admitted current verified evidence may satisfy it.
• A required evidence block loses the budget race — recorded as an omission and rejected for the gate, never silently treated as covered.
• Caller-provided content and hash disagree — compile fails visibly.
• Policy resolution caches stale rules; mitigated by version pinning and pack hash check.
• An applicable enforcing predicate throws; compilation stops with structured policy_eval_error, never a successful context from a silently false result.
• Loop guard tripped without informative reason returned to the planner.
• Subagent lane mutates parent Run Context (must be isolated copy).
• Reflection layer recommends actions that bypass the policy gate on next turn.

Operational concerns

• Latency budget per stage; budget-exceeded converts to a Critic escalate verdict.
• Pack version pinning per environment; promotion is deliberate.
• Tool timeout and retry budgets enforced by the Run Context, not the adapter.
• Trace retention by data classification; long-running session checkpoints.
• Replay conformance: pin snapshot, pack, and recorded transcripts; compare deterministic artifacts exactly and model-dependent stages through declared properties or scorecards.

Evaluation metrics

• Plan-verification pass rate per intent.
• Tool-success rate and recovery rate.
• Evidence-backed output rate (decisions with all required_evidence resolved).
• Evidence-gate closure rate and unresolved-requirement distribution.
• Untrusted-evidence gate-satisfaction rate (target: zero).
• Structured omission rate for required evidence.
• Policy-compliance rate.
• Mean time to safe completion.
• Loop-guard trip rate (should trend toward zero with autotune).

Example

A condensed end-to-end trace of one turn (one cell per layer):

{
  "run_id": "run_a1b2c3d4e5f60718",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "request": "Issue refund for order ord_881",
  "perception":   { "events": [ "user_message", "session_resumed" ] },
  "attention":    { "focus": ["order:ord_881", "policy:returns_v4"], "salience_top": 0.91 },
  "identity":     { "agent_role": "support_agent", "voice": "neutral_concise" },
  "intent":       { "name": "support.refund", "task_template": "refund_with_eligibility" },
  "judgment":     { "candidate_plan_id": "plan_refund_01" },
  "policy_gate":  { "verdict": "require_approval", "approval_gate": "GATE_FINANCE_APPROVAL" },
  "action":       [ { "tool": "orders.lookup", "result": "ok" }, { "tool": "policy.eval", "result": "ok" } ],
  "consolidation":{ "memory_proposals": ["customer_prefers_email_updates"] },
  "reflection":   { "goal_met": false, "next_action": "request_exact_approval", "budget_remaining": "78%" }
}

Common misconceptions

• The Cognitive Core is not a single model. It is a layered runtime with a deterministic compiler, a layered loop, and explicit budgets.
• The compiler is not optional. Without it, every team rolls its own prompt assembly and drifts.
• Reflection is not introspection theater. It writes a structured record that the Improvement Loop consumes.