<!-- normative -->

# Run Entry Point

An operator starts, observes, and stops an orchestrator run against an arbitrary repository without importing the
experiment harness. The run-spec is the operator's whole input; the CLI (`scripts/orchestrate.py`) is the operator's
whole interface.

## Run-spec

A run-spec is a YAML document that names the repository and base commit to freeze and everything the run owns. Loading
is fail-closed: a loader-refusable malformed spec is refused as a named `RunSpecError` before any store is opened or
any event is admitted. A freeze-boundary refusal — a DECLARED divergence or an unfreezable repository — is also a
named `RunSpecError` that admits zero events, but it is detected at the freeze boundary, so the store file may already
have been created by the time it is raised.

| Field | Required | Meaning |
|---|---|---|
| `run_id` | yes | The run identifier; the root node is `{run_id}-root`. |
| `repository` | yes | Path to the repository to freeze; it must exist and contain the base commit. |
| `base_commit` | yes | The commit the target is frozen at; it must resolve in the repository. |
| `snapshot_id` | yes | The frozen target's identity. |
| `task_statement` | yes | What the root of the run must satisfy. |
| `project_kernel` | yes | The project kernel mapping (non-empty) describing the target. |
| `visible_commands` | yes | The commands the run's root execute runs, in order. |
| `components` | yes | `(name, scope)` pairs the obligations are derived from. |
| `owned_scope` | yes | The globs the run may write. |
| `acceptance_criteria` | yes | The criteria the run must satisfy. |
| `budgets` | yes | Per-[budget dimension](glossary.md#budget-dimensions) limits; keys must be catalogued and values positive. |
| `limits` | no | Frozen per-run stopping limits (the `RUN_LIMIT_KEYS` set), each a finite non-negative number. |
| `policy_version` | yes | The control-policy version; it must equal the running version. |
| `evidence_policy` | yes | A `{level, version}` pair: `level` is one of [Evidence policy levels](glossary.md#evidence-policy-levels) and `version` is a positive integer. |
| `executor_profile` | yes | A required executor label: the `RunConfiguration` schema validates it, but it is not recorded on the run and executor selection is separate work. |
| `obligations` | no | Hand-declared obligations; when present, `non_derivable_axes` and `non_derivable_reason` must also be supplied. |

The evidence policy binds the run: its level and version are recorded beside the control-policy version in the frozen
`run_specification` binding on the admitted root contract, and `inspect` reads them back. An unknown level or a
non-positive version is a load-time refusal.

```yaml
run_id: RUN-DEMO
repository: /srv/project
base_commit: 0123456789abcdef0123456789abcdef01234567
snapshot_id: TARGET-DEMO
task_statement: Make the visible checks pass.
project_kernel:
  kernel_id: KERNEL-DEMO
  purpose: A demonstration target.
  target_users: Operators.
  desired_outcomes:
    - A passing candidate
  current_scope:
    - src/**
  current_non_goals:
    - Publishing
visible_commands:
  - python3 tests/visible.py
components:
  - [core, src/core/**]
owned_scope:
  - src/**
acceptance_criteria:
  - AC-CORE
budgets:
  MODEL_COST: 10.0
limits:
  wall_clock_seconds: 120
  actions: 4
policy_version: 1
evidence_policy:
  level: MEDIUM
  version: 1
executor_profile: command-executor-v1
```

## Workflow

`start` freezes the target through `experiment_target.build_target`, builds a `RunConfiguration` that
`Controller.submit_run` admits, and drives the root node's ready `EXECUTE` over the visible commands through a
deterministic `CommandExecutor`. Acceptance is bound to the node's own produced result: `VisibleAcceptanceChecker`
evidence is admitted through `Controller.admit_evidence` and bound through `Controller.authorise_acceptance`. A
failing visible command is a recorded refusal — the failing checks are recorded and acceptance is never authorised —
and the node is driven to a recorded terminal [run outcome](glossary.md#run-outcomes).

`start` exits zero only when its JSON's `outcome` is `ACCEPTANCE_CLAIMED` — the run's durable settled outcome, re-read from the log after this
process's last admission — and non-zero for every non-accepted class, including a recorded refusal, a cancelled run, or a
timed-out attempt. Its JSON output names the run, the root node, the settled attempt, the evidence id, and that durable
outcome.

`inspect` prints the run's status, outcome, candidate reference, evidence, costs, current policy version, evidence
policy, and event history read from the store alone. It admits no events and is safe against a run another process
started.

`stop` settles every live attempt and admits the run's cancellation on the root. A run that already reached a
terminal outcome is not rewritten by `stop`: the cancellation is a late event against a terminal root.

## Commands

```text
python3 scripts/orchestrate.py start   --spec RUN_SPEC.yaml --workdir DIR --store STORE.db
python3 scripts/orchestrate.py inspect --run-id RUN_ID --store STORE.db
python3 scripts/orchestrate.py stop    --run-id RUN_ID --store STORE.db
```

Each documented head names its interpreter explicitly: the delivered `scripts/orchestrate.py` is not executable
(mode 100644), so no bare `scripts/orchestrate.py …` head is documented as runnable. The `python3` named here is
the system interpreter, and it must be able to import `yaml` (the CLI's one third-party dependency) for these forms
to start; on a host whose system `python3` cannot, run the same head with an interpreter that can.

The CLI and the run-entry module import no experiment-harness module; `orchestrator.experiment_target` is the one
allowed seam for freezing a target.
