<!-- normative -->

# Executor Selection

Every operation should use the lowest-cost reliable executor.

## Execution precedence

1. Deterministic function
2. Existing verified tool or script
3. Small or local specialised model
4. General inexpensive model
5. Strong specialist model
6. Human or external decision authority

Independent multi-model evaluation is an evidence strategy governed by
[Independent evaluation](validation.md#independent-evaluation) and
[Validation and Acceptance](validation.md#validation-and-acceptance). It is not an executor level.

Escalate only when a lower level cannot satisfy the node contract and evidence policy.

## Deterministic responsibilities

Use deterministic components for:

- graph storage and traversal;
- cycle detection;
- dependency readiness;
- state reduction;
- scheduling;
- locks and isolation;
- version checks;
- schema validation;
- builds and tests;
- content hashing;
- caching;
- budget enforcement;
- retry counters;
- permission checks;
- contract compatibility;
- metrics;
- audit records;
- status reports compiled from structured state.

## Reasoning responsibilities

Potential reasoning tasks include:

- interpreting an incomplete project idea;
- proposing decompositions;
- evaluating semantic coverage;
- identifying hidden coupling;
- drafting contracts;
- detecting ambiguity;
- planning a useful increment;
- producing non-routine code;
- diagnosing unfamiliar failures;
- comparing architecture choices;
- performing semantic review;
- interpreting stakeholder feedback.

Reasoning components do not acquire authority merely because a task is semantic.

## Trust Boundary

Reasoning outputs are untrusted. They may be typed as:

- PROPOSAL
- ARTEFACT
- OBSERVATION
- EVIDENCE
- SEMANTIC_EVALUATION

Before affecting authoritative state, validate:

- schema;
- provenance;
- producer authority;
- delegated scope;
- referential integrity;
- input versions;
- freshness;
- consistency;
- security;
- policy compatibility;
- assumptions;
- required evidence;
- content or artefact hash.

A model assertion that a command passed is not command evidence. The recorded result from the authorised command
executor is evidence.

## Executor protocol

An executor request is immutable and contains:

```yaml
executor_request:
  run_id: RUN-001
  action_id: ACTION-091
  attempt_id: ATTEMPT-002
  attempt_token: "opaque-single-use-token"
  node_id: NODE-042
  node_contract_version: 3
  action_type: EXECUTE
  resolved_inputs:
    - reference: ARTEFACT-017
      version: 4
      content_hash: "..."
  owned_scope:
    include:
      - "src/component/**"
      - "tests/component/**"
    exclude:
      - ".git/**"
      - ".orchestrator/**"
      - "hidden-tests/**"
  base_commit: "..."
  worktree_id: WORKTREE-091
  command_allowlist: []
  environment_version: "experiment-image-v1"
  timeout_seconds: 900
  cancellation_token: "..."
  budget_commitment:
    dimension: MODEL_COST
    hard_limit: "..."
  output_schema_version: 1
  policy_version: 1
```

An executor response is an untrusted observation and contains:

```yaml
executor_response:
  run_id: RUN-001
  action_id: ACTION-091
  attempt_id: ATTEMPT-002
  attempt_token: "opaque-single-use-token"
  self_reported_status: COMPLETED
  artefacts:
    - type: GIT_CANDIDATE
      reference: "..."
      content_hash: "..."
  observations:
    - type: COMMAND_RESULT
      command_id: BUILD
      exit_code: 0
      stdout_hash: "..."
      stderr_hash: "..."
  changed_paths: []
  cost_report:
    committed: "..."
    actual: "..."
    units: "..."
  started_at: "..."
  finished_at: "..."
  executor_version: "..."
  response_schema_version: 1
```

`self_reported_status` is never acceptance evidence. Its value is an [executor response
status](glossary.md#executor-response-statuses), mapped to an authoritative attempt state on admission. Each
`artefacts` entry `type` is an [executor artefact type](glossary.md#executor-artefact-types); each `observations`
entry `type` is an [executor observation type](glossary.md#executor-observation-types).

For repository actions, `base_commit` identifies the immutable published integration-tree version that satisfies the
action's dependency bindings. For an undecomposed root or an action with no integrated predecessor, it may identify the
frozen initial repository commit.

### Executor sandbox

A Git worktree is a candidate-production mechanism, not a security boundary.

Every executor and every executor-controlled build or test subprocess runs in an operating-system-enforced sandbox with:

- a dedicated unprivileged identity;
- a private mount namespace or equivalent isolation boundary;
- the candidate worktree mounted read-write;
- required toolchains and dependencies mounted read-only;
- controller state, event storage, artefact storage, credentials, sockets, and host paths absent from the namespace;
- Git objects and metadata unavailable for direct mutation;
- a controller-owned Git service or copy-in/copy-out boundary for obtaining the base tree and returning a candidate
  bundle;
- hidden tests absent from executor-visible mounts and environment variables;
- no inherited credentials except explicitly scoped short-lived credentials;
- network access denied by default;
- an allowlist for any network endpoint required by the fixed model adapter;
- process, memory, CPU, file-size, descriptor, and wall-clock limits;
- syscall and device restrictions appropriate to the operating system;
- captured command, exit-code, stdout, stderr, and resource observations.

The executor receives a materialised base tree without writable access to the authoritative repository's `.git`
directory or shared refs. Returned candidate commits or bundles are imported and verified by the controller in a
separate trusted integration environment.

The sandbox prevents unauthorised side effects. The post-return diff check is an additional publication gate that
verifies contractual `owned_scope`; it is not the sandbox itself.

A sandbox violation emits `SANDBOX_VIOLATION_RECORDED`, terminates the attempt as `FAILED`, retains forensic evidence,
charges actual or conservatively settled cost, and permanently rejects every output produced by that attempt.