Practice review runtime

The practices module owns reviews, assignments, results and feedback history. The runtime owns job claims, attempts, preparation, scripts and transient evidence. A review can outlive every execution job that produced it.

Execution ownership

The server selects and persists a review before runtime execution. The review's sandbox claims its job through the PostgreSQL queue (Agent runs § A review in its sandbox). The servers share no other channel. Only a server with the agent runtime owns sandbox access.

An ITEM review executes its assigned item. A SCAN review can own many bounded file jobs, with one active job at a time. Each job has an independent UUID and a workspace-scoped review reference. A database index also permits only one active scan per workspace.

Claims carry an attempt fence. A requeue after preparation always moves the job to the next attempt number. Thus, no evidence folder is used twice.

An attempt that ended a practice and then ran out of time spends no retry. It counts in progressed_attempts, and its next attempt starts at once and skips the ended practices. A slow provider can thus take many attempts to finish a review. The practices of the review bound these attempts, because each one must end a new practice. An attempt that ends no practice spends a retry.

ReviewJob.spentAttempts() subtracts all three, and every retry-budget check reads it.

Admission locks the review before its job and assignment rows. Cancellation follows the same order and prevents later admission from publishing through the old attempt. Classified preparation reasons describe work, source access, pinned versions and capture failures without raw exception text.

Scripts and models

Each assigned practice runs its custom script or the built-in script. The host stages one <slug>.inputs.json file under the script input directory. The script returns one candidate result. A custom child process has no provider credential. It calls host capabilities through typed IPC.

The host owns the attempt credential, governed model requests, deadline and usage limits. Its model assignment follows account-wide AI choice and source-person authorization. The method snapshot retains all model slots and an epoch after job cleanup. No second runtime serializer computes the method digest.

The script runner owns the executable contract. The AI provider guide owns model assignment, prices and ceilings.

Admission and composition

The server submits candidates and trusted receipts for its owned attempt. The server returns allocated result and problem identities with verified citations. Composition can refer only to those admitted records. An ids-only admission response cannot authorize an invented problem reference.

The workspace ABI owns the exact result and history paths. A history refusal is not an empty result list. Source custody is checked before confirmed historical words enter the sandbox.

Preparation commits exact feedback and physical copy records before egress. Runtime completion and feedback delivery have separate states. A stopped private composition does not erase admitted results or a prepared public proposal. The pipeline owns these stage boundaries.

Recovery

A failed attempt cannot overwrite its original admitted results. A retry runs under a new fence and reuses durable assignment state.

Each review job points to one agent run (agent_run), which holds the job's lease. Agent runs owns the run model: the claim, the epoch fence and the reaper. The sandbox that claims the run is the only writer of its lease, and its driver renews the lease while the run works. The job's attempt number is the run's claim epoch less one (ReviewRunKind.attempt). Every fenced write of the attempt names the run and the attempt.

AgentRunReaper takes back a run whose lease expired, on every server replica. ReviewRunKind moves the job in the same transaction, before the run is written. It bills the lost attempt, and it queues the job again or fails it at the retry limit. The database refuses a commit where a job and its run disagree: queued with queued, running with leased, ended with ended.

Delivery recovery reads persisted copies rather than re-running a writer from raw result text. Unknown visibility permits readback, not automatic reposting.

An upgrade to a different runtime contract cancels retained queued or running work with CONTRACT_CHANGED. The migration keeps prior proof and physical write receipts. A fresh review has new identity and current practice versions. No decoder for the previous runtime contract remains.

Retention

Transient job payloads expire after 14 days by default. Terminal jobs expire after 90 days independently of reviews, results and feedback. Evidence-copy receipts keep pending sandbox cleanup identities after job deletion. Usage keeps a durable review reference after job deletion.

The operations reference owns configurable limits and metrics. The data map owns personal-data retention and erasure.