Architecture: define RunContract-centered learning runtime boundaries

[devkade]

Architecture: define RunContract-centered learning runtime boundaries

Parent: #167
Related: #114, #120, #121, #148

Summary

Design the architecture that connects existing Kapi/Ilchul RunContract and WorkflowState concepts to a new RunState-based execution runtime.

The architecture should make Ilchul a portable harness where RunContract defines run meaning, ObjectiveFunction defines evaluation intent, PolicySelection records strategy choice, TaskGraph drives execution, WorkerRuntimeState tracks execution substrates, and RewardLedger stores learning data.

Proposed structure

RunContract Core
  -> Objective Engine
  -> Policy Selector
  -> Workflow Engine
  -> DAG Runtime
  -> Worker Runtime
  -> Evidence / Evaluation
  -> Integration / Repair
  -> Reward Ledger / Policy Update

Core model candidates

interface RunState {
  schemaVersion: number;
  runId: string;
  goal: string;
  status: RunStatus;
  workflow: WorkflowState;
  runContract: RunContractView;
  objective: ObjectiveFunction;
  policySelection: PolicySelection;
  selectedPolicy: ExecutionPolicy;
  taskGraph: TaskGraph;
  workers: WorkerRuntimeState[];
  claims: TaskClaim[];
  leases: WorkerLease[];
  evidence: EvidenceRef[];
  evaluations: EvaluationResult[];
  integration?: IntegrationState;
  learning?: LearningState;
  events: RuntimeEvent[];
}

Boundary rules

• WorkflowState remains the existing workflow source of truth.
• RunContract remains a projection/contract boundary, not a GitHub/Ragna-specific model.
• RunState owns execution runtime state: tasks, workers, claims, leases, attempts, events, evaluations, and learning.
• ObjectiveFunction and EvaluationResult provide advisory score/verdict signals until stronger authority is explicitly designed.
• RewardLedger records learning data; it must not silently change runtime behavior without PolicySelection recording the decision.

Non-goals

• No broad kapi -> ilchul rename.
• No .kapi deletion or storage migration.
• No runtime plugin framework.
• No GitHub/PR/Ragna/kapi-agent semantics in core.
• No hard-blocking score authority in this slice.

Acceptance criteria

• Architecture document defines RunState, ObjectiveFunction, PolicySelection, TaskGraph, WorkerRuntimeState, EvidenceRef, EvaluationResult, and RewardLedger boundaries.
• Existing WorkflowState and RunContract responsibilities remain explicit.
• Completion authority, runtime readiness authority, and advisory evaluation authority are separated.
• Architecture includes an event model for replay/recovery.
• Architecture references worker retention lifecycle from design: define completed worker tmux session lifecycle cleanup #148.

Verification

• Design review against README RunContract boundary.
• Design review against docs/runcontract-harness-evaluator.md.
• No code behavior change required for this issue unless split into implementation follow-ups.