Cordis Runtime v0.4

Cordis Runtime is the minimal host bridge for Cordis Core. It does not call a model and it does not split tasks.

The semantic boundary is explicit:

user language
    -> host/main model interprets intent
    -> structured Task Contract
    -> Cordis Runtime + Core
    -> difficulty policy + model context
    -> optional Planner proposes PlanIR
    -> Runtime admits plan, advances steps, then closes Core feedback

For an agent with tool calling, the host/main model fills the task contract as part of its normal turn. The optional cordis-planner can use a model callable to propose a PlanIR. Neither Runtime nor Planner executes a tool: Runtime owns the deterministic workflow state and the host remains the executor.

Minimal use

from cordis_core import CordisRuntime
from cordis_runtime import CordisHostRuntime

runtime = CordisHostRuntime(CordisRuntime("cordis-state.json"))

turn = runtime.begin({
    "task": {
        "goal": "Fix the login integration test",
        "domain": "software",
        "project_id": "my-app",
        "strategy_id": "inspect_logs_first",
        "stakes": "medium",
    },
    "complexity": 0.4,
    "current_step": "Inspect the failing test and logs",
    "constraints": ["Do not change the database schema"],
    "acceptance_evidence": ["login integration test passes"],
})

# Send turn["model_context"] to the host's existing planner or main model.

The host calls check_action(...) before an action, observe(...) for any plan/tool/artifact/test/error event, and finish(...) with observable evidence after execution. When constructed with a CognitiveStore, Runtime retrieves a small project-safe snapshot on begin, supports deduplicated query(...), and persists the final episode through finish(...).

Managed host lifecycle

Hosts should normally use CordisManagedSession instead of asking a model to construct separate begin, observe, and finish calls. The host creates the task once, translates its own tool/test telemetry into a small typed event set, then closes from accumulated evidence:

from cordis_runtime import CordisManagedSession

session = CordisManagedSession(runtime)
turn = session.start(task_payload)

# The host, not the model, emits this after its test runner returns.
session.record({
    "type": "test_passed",
    "summary": "pytest tests/test_login.py passed",
    "acceptance_id": "criterion-1",
    "tool": "pytest",
})
result = session.complete(lesson="The login integration test now passes.")

tool_succeeded, tool_failed, test_passed, test_failed, verification_passed, verification_failed, and note are supported. The session rejects malformed, unknown, and out-of-order events; it derives the final result from declared acceptance evidence rather than trusting a model to claim success.

Workflow boundary

Runtime provides:

• structured Task Contract validation through Core;
• task-local Focus State;
• deterministic control modes;
• compact model context;
• an experimental lexical drift heuristic, never a safety or attention guarantee;
• evidence-bound feedback delegation.
• optional CognitiveStore retrieval, event capture, and episode write-back.
• a durable workflow controller for task contracts, six-axis difficulty, PlanIR admission, active steps, results, explicit replan, and feedback closure.

Runtime does not provide natural-language interpretation, model selection, provider SDKs, tool execution, parallel scheduling, durable conversation memory, or an HTTP service. The optional planner can propose plans but cannot approve or execute them.

check_action is deliberately conservative metadata: it reports lexical overlap and obvious destructive terms. Hosts must not treat it as semantic understanding, an authorization decision, or a complete attention-drift guard.