Foundations
The operating model for ContextOS: five planes, cross-cutting primitives, and the contracts that make agent runs governable.
ContextOS foundations define portable engineering boundaries around production agents. They specify what an implementation knows, what it gives the model, how decisions are made, which actions are allowed, and how every run becomes auditable evidence.
These boundaries support the open contract for reliable agent harnesses. Use Adopt a Harness Contract to begin with one workflow and measurable acceptance cases. The five planes assign ownership; they do not require five services. Add knowledge graphs, reusable memory, or delegated agents when the workflow demonstrates a need.
The 2026 framework revision keeps these planes and strengthens their cross-cutting contracts for model routing, durable execution, multimodal evidence, computer use, and scoped agent delegation.
The compatible Execution Contract now makes exact Control Profiles explicit for personal/proactive, enterprise, durable/delegated and high-assurance workflows. Feature-derived obligations compose around existing base envelopes. Conformance separates declared support, deterministic reference checks and real workflow/release/environment evidence. Public specification availability does not change the current all-rights-reserved license.
The foundation rule
An agent run is acceptable only when it can answer five questions:
| Question | Foundation owner | Runtime artifact |
|---|---|---|
| What did the system know? | Intelligence plane | ontology version, CEIDs, graph evidence, promoted memory |
| What did the model actually see? | Context plane | ContextPack, CompiledContext, source manifests, budget report |
| Why did it choose that path? | Decision plane | plan, critic verdicts, decision spec binding |
| What external effects happened or remain uncertain? | Action plane | ToolEnvelope, stable operation identity, native action risk, provider-specific recovery and postcondition evidence |
| Whose authority and controls permitted the work? | Trust plane | current grant/approval evidence, policy decision, evaluator result, trace id, DecisionRecord, replay handle |
An implementation cannot claim a governed outcome without the evidence required for that workflow. A missing artifact narrows the conformance claim; simply answering these questions in prose is not a production acceptance test.
The five planes
Intelligence
The substrate of meaning: canonical schema, identity, evidence, memory, and retrieval.
Context
The compiler that turns request state, evidence, policy, tools, and memory into bounded model input.
Decision
The bounded loop that plans, critiques, executes, consolidates, and emits typed decision state.
Action
The governed integration boundary for tools, MCP, A2A, OpenAPI, internal functions, and custom adapters.
Trust
The control plane over the other four: policy, approvals, evaluation, tracing, replay, and improvement.
The planes compose in one direction: Intelligence feeds Context, Context feeds Decision, Decision drives Action, and Trust wraps every boundary.
How improvement crosses the planes
The latest ContextOS improvement-loop rule is: the harness may be searched, but it must not silently mutate. Autotune, reviewer agents, and human operators can propose changes to any plane, but each proposal must name its target metric, replay set, guardrails, owner, and rollback target.
| Plane | What can improve | What must stay invariant |
|---|---|---|
| Intelligence | ontology additions, source-priority hints, graph retrieval constraints, memory promotion proposals | CEID stability, source provenance, data classification, snapshot pinning |
| Context | bucket budgets, retrieval top_k, source priority, compression, prompt fragments | required evidence coverage, redaction, policy manifest, tool manifest |
| Decision | planner templates, tool ordering, re-plan budgets, Critic scoring rubrics, subagent lane limits | DecisionSpec binding, approval gates, loop guards, replayable plan and verdict |
| Action | adapter retries, circuit breakers, cached read-only aliases, version routing for compatible adapters | schema validation, ActionRisk ceiling, conservative v1 projection, credential exchange, stable operations and declared provider retry/reconciliation guarantees |
| Trust | evaluator thresholds, sampling strategy, replay-set composition, rollout gates, proposal ranking | safety and policy floors, human approval for promotion, append-only audit |
Every improvement candidate is an artifact, not an edit in place. It enters the same lifecycle as packs, policies, tools, and evaluator suites: proposed -> reviewed -> approved -> released, with rejected and superseded recorded when the proposal does not survive review.
One run through the foundations
| Step | What happens | Contract produced | Primary docs |
|---|---|---|---|
| 1. Capture | The request is wrapped with tenant, actor, agent, session, budget, safety mode, and trace identity. | RunContext | Governance, Identity Layer |
| 2. Ground | The runtime resolves entities, retrieves evidence, and selects eligible memory. | CEIDs, graph evidence, memory candidates | Ontology, Knowledge Graph, Memory Model |
| 3. Compile | The context compiler selects, ranks, redacts, budgets, and assembles the model input. | CompiledContext | Cognitive Core, Agentic Context Engineering |
| 4. Decide | Planner, executor, and critic move inside bounded plan and verdict contracts. | plan, critic verdicts, decision binding | Orchestration, Decision Catalog |
| 5. Act | Every external effect goes through the Tool Gateway with policy, approval, identity, and idempotency. | ToolEnvelope | Adapter Mesh, Governance |
| 6. Record | The final answer, effects, evidence, approvals, controls, trace, and replay handle are persisted. | DecisionRecord | Evaluation and Observability, API Contracts |
| 7. Improve | Failures and corrections become proposals that must pass replay and approval gates before promotion. | scorecard, strategy proposal, pack version | Improvement Loop, Harness Engineering |
Cross-cutting primitives
These primitives are deliberately boring: they appear everywhere so every subsystem can be audited the same way.
| Primitive | What it carries | Why it matters |
|---|---|---|
RunContext | run_id, trace_id, session_id, tenant_id, user delegation, agent workload identity, safety mode, run budget | Establishes who is acting, under which authority, with which limits. |
ActionRisk | effect, authority, reversibility, interaction, data scope, optional decision TTL | Native risk contract; each dimension is evaluated independently. |
ApprovalMode | read_only, local_write, network, delegated, destructive | Required v1 compatibility projection and RunContext.safety_mode ceiling; not a complete risk model. |
ContextPack | Versioned, immutable input contract with evidence, policy, tools, memory, and decision layers; signatures are an optional supply-chain profile | Stops prompt stuffing from becoming an undocumented runtime dependency. |
CompiledContext | Compiled prompt, manifests, omitted context, runtime controls, and budget report | Shows exactly what the model saw and what the compiler excluded. |
ToolEnvelope | Tool request/result, policy decision, principal chain, native risk where available, v1 projection, idempotency, evidence, and trace identity | Turns side effects into governed operations. |
DecisionRecord | Outcome, evidence refs, approvals, controls active, policy decisions, confidence, trace id, replay handle | Makes a run comparable, searchable, reviewable, and replayable. |
ExecutionContractEnvelope | Exact profiles, required/optional controls and release refs bound by trusted admission | Keeps compatible base serialization separate from actual workflow obligations. |
ActionBinding and authority/approval attachments | Complete nested action, current bounded mandates and exact stored approval | An identifier, hash, confidence score or model claim cannot grant permission. |
| Boundary, data-flow and memory lifecycle attachments | Actual mode/configuration, recipient/processor, source labels, owned namespace, retention and propagation | Required runtime observations remain independent of business-policy allow. |
Run/operation/checkpoint and BudgetLedger attachments | Fenced state transitions, effect uncertainty, pinned resume and shared root/child capacity | Recovery cannot reset spending, widen authority or infer that an unknown effect never happened. |
ConformanceReport / ReferenceValidationReport | Scoped actual-deployment evidence versus synthetic deterministic checks | A reference pass cannot become runtime certification. |
The end-to-end contract
invokeAgent(request_envelope, RunContext)
-> Context plane: compile packs, evidence, tools, policy, memory
-> Decision plane: plan, verify, execute, score, consolidate
-> Action plane: route every effect through the Tool Gateway
-> Trust plane: enforce policy, approvals, evaluation, trace, replay
-> DecisionRecord(evidence_refs, approvals, controls_active, trace_id, replay_id)The Intelligence plane feeds the compile step. Consolidation writes memory proposals back through governed promotion, not direct durable writes.
What to read first
If you are evaluating adoption
- Invest Early - the business case and late-retrofit failure modes.
- Harness Engineering - controls, environment design, and measured simplification.
- Reference Architecture - the full five-plane blueprint.
If you are building the runtime
- Cognitive Core - compiler plus bounded execution loop.
- Adapter Mesh - governed tool execution.
- Governance - policy, native action risk, approvals, audit contract.
If you are grounding an agent
- Ontology - canonical types and relationship rules.
- Identity Layer - CEIDs, SIDs, actor identity.
- Knowledge Graph and Memory Model - evidence plus promotion-aware recall.
If you own safety, audit, or release gates
- Evaluation and Observability - scorecards, traces, replay.
- Improvement Loop - governed change from failures and corrections.
- Security and Compliance - sandboxing, identity propagation, compliance map.
Foundation docs by plane
| Plane | Foundation docs | Use them when you need to decide |
|---|---|---|
| Intelligence | Ontology, Identity Layer, Knowledge Graph, Memory Model | What the system knows, how entities resolve, what evidence is trusted, and what can be remembered. |
| Context | Cognitive Core, Agentic Context Engineering | What should enter the model input, under which budget, provenance, and runtime controls. |
| Decision | Orchestration, Cognitive Core | How plans are proposed, verified, executed, scored, retried, or escalated. |
| Action | Adapter Mesh | Which external capabilities are discoverable, callable, idempotent, and approval-bound. |
| Trust | Governance, Evaluation and Observability, Improvement Loop, Harness Engineering, Security and Compliance | Which policies apply, how approvals work, what gets evaluated, how replay works, and how the harness improves. |
Adoption checklist
Use this before calling a workflow production-ready.
| Check | Minimum acceptable answer | Source |
|---|---|---|
| Entity model | The workflow’s core entities have ontology types, stable CEIDs, and relationship rules. | Ontology, Identity Layer |
| Context boundary | The workflow has a versioned ContextPack; the compiler emits manifests, omissions, controls, and budgets. | Agentic Context Engineering, Context Pack |
| Tool boundary | Every external capability is behind the Tool Gateway with schemas, native risk, current scoped authority, active boundaries, safe operation recovery and trace lineage. | Adapter Mesh |
| Decision boundary | Outputs bind to a decision spec and produce a typed DecisionRecord. | Orchestration, Decision Record, Decision Catalog |
| Policy boundary | Policy lives outside agent code; ActionRisk is native and ApprovalMode is the v1 compatibility projection. | Governance |
| Evidence boundary | The record contains evidence refs for material claims and tool results. | Knowledge Graph, Evaluation and Observability |
| Replay boundary | The run can be replayed against pinned context, policy, tools, and evaluator versions. | Evaluation and Observability, Improvement Loop |
| Improvement boundary | Failures and corrections become proposals, not silent prompt edits. | Harness Engineering, Improvement Loop |
| Autotune boundary | Any optimizer run declares target metric, guardrails, tunable surfaces, disjoint search/test sets, and rollback target before producing a proposal. | Improvement Loop, Evaluation and Observability |
| Profile/evidence boundary | Trusted feature admission selects exact obligations; every mandatory control/case and useful outcome has current verified runtime evidence for the release/environment. | Control Profiles, Conformance |
Where the concrete contracts live
The foundations define the operating model. The implementation section defines the concrete contracts:
- API Contracts -
invokeAgent,ToolCallEnvelope,ToolResultEnvelope,DecisionRecord - Execution Contract - compatible profile admission, exact authorization, active boundaries, durable effects and aggregate budgets
- Context Pack - pack schema, layers, lifecycle, caching
- Decision Catalog -
DecisionSpec,DecisionRecord, decision binding - Intent-Task Catalog - intent taxonomy, task templates, risk classification
- Memory Fabric - concrete memory storage, promotion, consent, contradiction handling
- Workflow Examples - neutral end-to-end runs through the canonical contract
- High-Risk Workflow - multi-approver, irreversible, cross-tenant workflow