oro-env-runtime

Portable sealed-pack execution and verification for ORO environments.

The package owns the public runtime contract used by environment generators and validators:

• sealed-pack schemas, versions, integrity checks, and portable validation;
• pack-pinned, index-backed catalog and local-search access;
• TaskSession, environment execution, replay, and user simulation;
• deterministic verification, rewards, and runtime family behavior.

It deliberately excludes private catalogs and task packs, seed search, task-family generation, catalog profiling, compiler orchestration, model configuration, and deterministic recompilation.

Requires Python 3.11 or newer and is distributed under the MIT License.

Policy boundary and state visibility

TaskSession.policy_view() returns the task query, local tool schemas, and contract versions. TaskSession.step() and step_parallel() return only observation, done, and error. The complete immutable ledger stays inside the session for replay and verification.

State has these visibility classes:

• Public: the goal, budget, frozen catalog facts, cart, tool schemas, policy errors, and terminal status.
• Private: gold_set, acceptance, admission evidence, verifier checks and rewards, the complete ledger, verifier signals, and true-state hashes.
• Conditionally revealed: the market-event kind and delta. The environment applies the event to the first product that the cart accepts. The solver already supplied this product. The environment reveals the event only in the response to that successful add_to_cart call.

Before and after the trigger, a change to a private field must not change any policy-visible value when public state, seed, and actions are equal. The event target comes from the public action, not from acceptance, gold, admission, or verifier state. Acceptance, gold, admission, verifier, ledger, and true-state hash data stay private. A task without an event has no conditionally revealed state. The sealed-pack validator records its event noninterference check as not_applicable.

For an event task, the first successful add is also the family-owned public commitment used by the reward contract. Exploratory adds remain valid environment actions, but an add before the intended commitment makes the event construct unsuccessful.

Shopper interaction protocol (oro_task_tools_v3)

The message tool is the only pull mechanism. It may be called once or alongside other tools in an ordered solver turn. After the group finishes, a non-terminal session returns at most one simulator reply in user_message; the reply is also appended to the authoritative ledger as a user_message entry. A group containing multiple message calls still produces one reply to the complete turn.

The harness may push one unsolicited reply after a visible market event. It deliberately waits for one unaided solver turn after the event fires, then returns the reply in that turn's user_message field if the session remains active and the task is not state-blind. It does not push for arbitrary policy actions. A terminal action during the unaided turn ends the episode without simulator rescue.

Every call response includes user_message, either a {content} object or null. An adapter MUST append non-null content to policy context before the next solver turn and MUST NOT infer a message from null. Calls are strictly ordered by positive turn number. Retrying an identical call with the same idempotency key replays the cached response without another simulator call or ledger entry; reusing a call ID or idempotency key for different input, or sending an out-of-order turn, is an error. Replies are synchronous: there is no late-message channel.

The simulator has dialogue authority only. It cannot mutate commerce state or assign reward. Provider timeout, unavailability, or invalid output is an environment failure and quarantines the session; it is never classified as miner failure. Episode evidence records each delivered message and the simulator model, prompt, configuration, normalized response, latency, and sanitized failure type. Credentials, provider exception detail, hidden task fields, verifier state, and reward remain private.

Releasing

Bump project.version in this package's pyproject.toml as part of a reviewed pull request. When that change reaches main, GitHub Actions creates the matching runtime-vMAJOR.MINOR.PATCH tag and dispatches the protected publish workflow at that tag. The publish workflow reruns the generator tests and lint, builds and audits the public wheel, verifies it in a clean Python 3.11 environment, and publishes it to PyPI through Trusted Publishing.

PyPI releases are immutable. Fix a bad release with a new version rather than reusing a tag or overwriting an existing artifact.