Execution Contract

ContextOS keeps its five planes and existing runtime envelopes. Profile-aware workflows attach an ExecutionContractEnvelope to the existing run, trace and tenant. Exact profiles declare obligations for the workflow; they do not grant permission or establish that a runtime enforces them.

Implementation status, 2026-10-16: published schemas and deterministic TypeScript validators are available in this repository. The reference has synthetic useful and failure cases. Identity verification, credential brokers, isolation, transactional stores, schedulers and external providers remain deployment responsibilities. A mission-critical claim requires the workflow-specific evidence described in Conformance.

Compatible attachment and admission

The execution-contract v1 schema is additive. RunContext, invokeAgent, AgentDelegationEnvelope, ContextPack v2, CompiledContext, ToolEnvelope, DecisionRecord and ReplayPacket retain their current version names and required fields. The v1 ApprovalMode values remain read_only, local_write, network, delegated and destructive; the independent native ActionRisk dimensions retain their meanings.

This structural example selects the personal/proactive profile. Its identifiers and release digest are synthetic, so the example establishes no publisher trust or deployed release:

{
  "envelope_version": "contextos.execution_contract.v1",
  "contract_id": "contract_calendar",
  "run_id": "run_calendar",
  "trace_id": "trace_calendar",
  "tenant_id": "tenant_personal",
  "profiles": [{ "profile_id": "contextos.personal-proactive", "profile_version": "1" }],
  "required_controls": [],
  "optional_controls": [],
  "release_refs": [{
    "artifact_type": "release",
    "artifact_id": "synthetic_calendar_release",
    "version": "1",
    "sha256": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
  }]
}

A trusted admission store binds this attachment to the authenticated base run and immutable release. Merely repeating a matching tenant_id or digest in model output does not establish that binding. Admission derives all eight feature booleans from the admitted capabilities, workflow and actual runtime configuration: arbitrary_code, external_network, persistent_memory, external_effects, delegation, checkpoint_resume, proactive_triggers and sensitive_data. An unknown feature state blocks dependent admission. A caller cannot hide an enabled feature by setting it to false.

negotiateExecutionContract verifies content-addressed registry definitions, expands selected profiles as a union, adds applicable conditional controls and checks exact runtime support. Its accepted result establishes compatibility only. Mandatory controls cannot become optional; unsupported optional controls remain visible. See the exact control and profile registry.

Processing and enforcement owners

Each allowed dispatch needs the conjunction of current authority, applicable policy, required approval, independent constraints, active boundary, data permissions and reserved budget. A high-priority business allow cannot override a revoked grant, egress restriction or stale approval. A support declaration and a serialized verified label cannot authenticate themselves.

Policy errors and precedence

The compiler stops on an exception from an applicable policy predicate by throwing ContextCompileError; it does not return a successful compiled context. The safe serialized error has six fields:

{
  "code": "policy_eval_error",
  "stage": "policy_resolution",
  "bundle_id": "support_policy",
  "rule_id": "refund_limit",
  "expression_path": "if",
  "message": "An applicable policy predicate could not be evaluated."
}

The response excludes the predicate, request payload, stack and cause. Ordinary false predicates keep their existing false/else behavior, and inapplicable rules remain inapplicable.

Normalized business outcomes use the highest applicable priority; deny wins an equal-priority tie. All applicable obligations remain. Independent guardrail deny, escalation and approval requirements are composed separately. The existing compiler tool filter continues to accumulate prohibitions across applicable rules. Do not substitute business-priority resolution for that cumulative filtering algorithm; Policy Engine describes the distinction.

Exact action and approval binding

ActionBinding covers the contract, run, operation, proposal, tenant, actor, authority refs, purpose, exact capability revision, complete nested arguments, resource/destination IDs, evidence/policy/profile/release refs, native risk and any business amount with explicit currency/minor units. digestActionBinding hashes the full binding with RFC 8785 canonical JSON and the contextos.action_binding.v1 domain.

Approval binds the immutable bytes of that action and the stored request interval. It does not freeze the external world. Recheck current authority, entitlements, external preconditions, boundary, data policy and budget at dispatch. A stored request’s expiry cannot be extended by a later decision object. Required approvers must be currently entitled, distinct where quorum requires it, and independent when policy prohibits self-approval.

transitionApprovalRedemption returns an intended compare-and-swap transition. The store must persist it atomically with revision checks and operation ownership. The returned permits_new_effect: false is deliberate: redemption recovery does not authorize dispatching another effect. Standing grants can permit bounded actions without a fresh click when policy allows; approval-bound control semantics still apply whenever approval is required.

Containment, credentials and data

Boundary modes distinguish broker-only tools, sandboxed code and separately administered execution domains. A broker-only workflow can have a valid restricted execution boundary without claiming VM isolation. Arbitrary code needs active filesystem/process/resource restrictions appropriate to its threat model. Credential and network controls need actual runtime evidence, including deny-all egress when no destination is granted. A configuration file, SDK option or reference validator alone proves no containment.

Credentials stay outside model-visible state and are scoped to the authenticated actor, capability, destination and lifetime. Network mediation must cover DNS resolution, redirects and rebinding at the actual egress boundary; an approved API purpose does not permit arbitrary network destinations.

Data policy covers collection, inference, tool input/output, telemetry, cache, memory, export and delegation. Verified source labels cannot be replaced by caller-supplied lower labels. A release transformation binds source/result artifacts, purpose, recipient, processor, stage, operation and action digest. Residency depends on the actual processor route and configuration, including logs and caches; a provider name is insufficient evidence.

Memory changes remain lifecycle operations. Keep personal/work namespaces and readers separate, minimize capture, review durable promotion, enforce retention and track derived copies. A correction/deletion request records pending, failed and external-unknown propagation. The initial record supports up to 128 known derived copies and 129 propagation receipts, including the source memory. Claim completion only for the verified inventory and target-specific receipts; no general promise of erasing copies held by another party follows from a local record.

Durable work, cancellation and recovery

Run states are explicit: created, running, waiting_approval, waiting_external, suspended, cancel_requested, completed, failed, cancelled and expired. Cancellation first stops new dispatch, fences old ownership and propagates to children. A confirmed stop can coexist with an unknown in-flight effect. It cannot rewrite that effect to “not applied.” Successful completion requires every declared required effect to be confirmed and active children to be settled.

An operation has stable identity across attempts. Effects are not_dispatched, confirmed, not_applied, partial or unknown. A timeout after possible provider commit is unknown. Retry requires either definitive non-application or the exact provider-specific idempotency contract, key, payload scope and retention evidence. Manual/query reconciliation and explicit compensation preserve the original history. Compensation is a new governed operation, not automatic proof that an effect is reversible.

ExecutionCheckpoint pins contract, pack, policies, tool/profile registries, release artifacts, pending approvals/tasks, operation identity and current budget state. Resume verifies bytes, current ownership, executor generation, authority, approval, external preconditions, boundary and budget. Policy changes require explicit migration and reauthorization. Restoring a historical checkpoint cannot restore spent capacity. Target fencing is an external requirement; unsupported fencing must block when required and remain a visible limitation otherwise.

Aggregate limits and exact accounting

Reserve before root or child work with reserveBudget or the child-scoped reserveChildBudget. Root model calls, retries and replans draw from the same original token/tool/replan/cost ceilings as delegated work. Children inherit an absolute deadline; concurrent elapsed times are not summed into another deadline allowance.

New counters use non-negative safe integers. A declared cost_unit supplies a currency and a positive power-of-ten units_per_cent. Existing RunBudget.max_cost_cents, cost_cents_used and DecisionRecord.budget_usage.cost_usd_cents retain their fractional-cent number semantics. convertLegacyCostToUnits interprets the number’s canonical decimal representation exactly: 0.91 cents at 100 units per cent becomes 91 units; 0.911 cents is rejected at that quantum. No rounding, implicit FX or default currency creates spending permission.

Settlements are cumulative and monotonic. Only verified known terminal usage releases unused capacity. Cancelled work with unknown usage retains its reservation until reconciliation. Stable mutation IDs recover the original receipt in the current ledger; recovering an old receipt never rewinds later spending. Revision and executor checks require an atomic store in a real deployment.

The initial ledger stores at most 128 mutation receipts. Admission and nonterminal updates preserve one receipt slot and one revision increment per open reservation for its eventual verified terminal settlement. An empty ledger therefore admits at most 64 concurrent reservations; cumulative updates can reach counter_exhausted earlier. This bound rejects additional work without stranding reservations admitted under these rules. Identical mutation recovery remains read-only even at capacity. Deployments needing longer histories require an explicit versioned archival/migration design that retains recovery receipts and accounting continuity.

Versioning, migration and limits

Adopt one workflow in the existing runtime: preserve its base envelopes, select exact profiles from actual features, bind the new attachments in trusted admission, connect current observations, run useful and denial cases, then collect real enforcement/recovery evidence. A legacy workflow without profile attachments remains a legacy workflow; absence is never evidence that a new mandatory control passed.

Initial bounds are 16 selected profiles, 128 required controls, 128 optional controls and 128 artifact refs per applicable array; identifiers/revisions are at most 256 Unicode characters. Profile expansion is acyclic, at most eight levels and 128 effective controls; delegation is bounded to 16 grants. Version 1 uses finite exact scopes, without wildcard/range grants. New canonical JSON bindings reject non-JSON values, accessors, malformed Unicode, cycles and excess depth/value/byte limits. Byte parsers must reject duplicate keys before constructing objects. Existing compiler/replay hashes are unchanged.

Contract timestamps are explicit UTC calendar strings ending in Z, with exact fractional ordering and half-open validity intervals. Leap-second labels need a separate time-scale adapter. Reference decisions never consult an ambient clock, randomness or network state.

Profile revisions are immutable. Adding mandatory requirements needs a new revision and migration evidence. This public specification does not grant new reuse rights: the repository’s current all-rights-reserved license remains in force. Independent interoperability, deployment certification and domain-specific safety require their own evidence and rights decisions. Continue with Control Profiles, Conformance and the base API contracts.