Orchestrator O1 · 03 Contracts & Skeleton Summary

doc 3 of 6 · 2026-05-20 · G2 gate

phase                : G2 — skeleton authoring + contracts
outcome              : G2 PASS — 24 .py files, 1741 LOC orchestrator + 515 LOC tests
production_mutation  : NONE

1. Authored contracts (load-bearing surfaces)

1.1 State machine (enums.py)

• OrchestratorState enum — 14 states, plus 3 terminal categories (FAILED, STOPPED, VOIDED).
• FORWARD_EDGES: dict[OrchestratorState, OrchestratorState] — one allowed next state per non-terminal state. Tests assert the chain is acyclic and reaches CLOSEOUT_REPORTED in exactly 13 steps.
• SOVEREIGN_PAUSE_STATES — exactly two: AWAITING_CUT_AUTHORIZATION, AWAITING_LIFECYCLE_AUTHORIZATION.
• PhaseName × 11, with PHASE_ORDER tuple in canonical traversal order.
• InternalGate × 11 + SovereignGate × 3 (= 14 total gates).
• PHASE_INTERNAL_GATE mapping; PHASE_SOFT_CAP_MINUTES map; RUN_HARD_CAP_MINUTES = 60.
• BatchState × 9 + FailurePolicy × 3.

1.2 RunContext (run_context.py)

• Dataclass owning the per-run lifecycle: run_id, document_id, source_document_id, source_version_id, mode, actor, state, context_pins, phases, sovereign_approvals, idempotency_keys, last_error.
• pin(key, value) raises if key.lower() contains any token in SECRET_KEY_DENYLIST = {pgpassword, password, secret, token, bearer, dsn, database_url, pg_dsn, api_key, api_token, private_key, gpg_secret, kms_key}.
• to_jsonable() strips secret-shaped keys at serialization time (belt-and-braces — even if a future refactor pokes raw context_pins, secrets do not leave the process).
• new() mints a sortable run_id = ictr-<YYYYMMDDTHHMMSSZ>-<uuid4[:8]>.

1.3 Errors (errors.py)

17 exception classes, each carrying a canonical stop_code string. Codes mirror design doc 03 §6 verbatim:

STOP_DOCUMENT_UNKNOWN, STOP_APPROVAL_REQUIRED, STOP_DRIFT,
STOP_REPLAY_CONFLICT, STOP_REFUSED_INPUT, STOP_NOT_IMPLEMENTED,
STOP_OVER_SOFT_CAP, STOP_OVER_HARD_CAP, STOP_INVARIANT_FAILED,
STOP_LOCK_BUSY, STOP_BACKUP_GPG_PUBKEY_MISSING, STOP_GRANT_DELTA,
STOP_KB_UPLOAD_FAILED, STOP_APPROVAL_INVALID,
STOP_APPROVAL_CONSUMED_ALREADY, STOP_O1_PRODUCTION_NOT_AUTHORIZED

The ProductionExecutionNotAuthorized class is the structural killswitch for the four mutating phases in O1.

1.4 Policy hooks (policy.py)

• USER_REFUSED_ARGS frozenset of 20 CLI argument names — covers secret-shaped (dsn, pgpassword, api_key, …), runtime-id-shaped (manifest_digest, region_sha, writer_digest, change_set_id, review_decision_id, manifest_envelope_id, executor_signature_id, verify_result_id, verifier_signature_id, candidate_count) and bypass-shaped (force, skip_verify, no_backup, no_drift_check).
• assert_no_user_artifact(argv) raises StopRefusedInput listing offenders (without echoing values, in case a value is secret).
• assert_discover_first(found, *, what) is a one-line search seam.
• assert_no_module_level_pins(module) returns offending PIN_* attribute names; tests use it to assert the orchestrator package introduces no per-document module-level constants.

1.5 Gates (gates.py)

• gate_kind(name) classifies an enum value as INTERNAL or SOVEREIGN.
• GATE_INVARIANTS: dict[InternalGate, list[(name, predicate)]] with 3–5 named invariants per gate (design doc 02 §4 verbatim).
• evaluate_internal(gate, ctx, allow_skeleton_pass=False). In O1 the runner does not invoke this; phase bodies own their own assertions. The registry shape exists for O2 to fill predicate bodies one by one. Each _todo_o2 predicate raises NotImplementedError, and the evaluator surfaces this as StopInvariantFailed rather than silently skipping (no-silent-retry doctrine).

1.6 State store (state_store.py)

• StateStore.create / update / read write state.json atomically (tempfile.NamedTemporaryFile + os.replace).
• acquire(run_id) is a context manager holding state.lock with fcntl.LOCK_EX | LOCK_NB. Releases on exit (success or exception).
• Tests cover roundtrip + repeated acquire-release.

1.7 Approval (approval.py)

• validate_sovereign_approval(...) reads a Markdown approval doc, parses gate:, run_id:, allowance:, signed_utc:, (SG_2) review_decision_id:. Refuses on missing fields, wrong values, stale timestamps. TTLs: SG_1 = 24h, SG_2 = 12h (per design doc 03/05).
• Six refusal paths exercised by tests.

1.8 KB reporter (kb_reporter.py)

• KBReporter Protocol with 4 methods.
• DryRunReporter writes each phase doc to the per-run sidecar directory (<sidecar_root>/<run_id>/kb/). Failures raise StopKbUploadFailed.
• payload_sha256(*chunks) for stable payload hashing across phases.

1.9 Discoverer (discover.py)

• Discoverer Protocol — 7 read-only methods.
• InMemoryDiscoverer — seedable fake; raises on un-seeded queries to make tests deterministic.
• Dataclasses: SourceVersion, GrantMatrix, VocabSnapshot.

1.10 Runner (runner.py)

• OrchestratorRunner with cut, resume public methods.
• _drive loops on FORWARD_EDGES until CLOSEOUT_REPORTED or a sovereign-pause state.
• _handle_sovereign_pause uploads the SG-request KB doc and raises StopApprovalRequired. The exception is NOT classified as a failure — the run is "stopped, resumable".
• Mode.LIVE refuses unconditionally while cutter_agent.orchestrator.__execution_enabled__ == False.

1.11 Batch (batch.py)

• Queue + QueueItem dataclasses with from_mapping validator. Refuses: missing fields, empty items, duplicate document_id, schema_version ≠ 1, > 100 items.
• BatchRunner.plan() returns a BatchResult in BatchState.PENDING. Lane scheduling deferred to O5.

1.12 Phases (phases/*)

Phase	LOC	Body
source_pin	40	functional read-only (uses Discoverer + pins)
mark	12	StopNotImplemented (cites cutter_agent.dryrun reuse)
cutplan	13	StopNotImplemented
backup	13	StopNotImplemented
grant_probe	13	StopNotImplemented
cut_leg_a	29	ProductionExecutionNotAuthorized guard
structural_verify	13	StopNotImplemented
leg_b_record	19	ProductionExecutionNotAuthorized guard
write_verify	19	ProductionExecutionNotAuthorized guard
lifecycle_enact	22	ProductionExecutionNotAuthorized guard
closeout	12	StopNotImplemented

2. Cross-cutting invariants enforced by O1 (not just designed)

no_user_artifact:
  enforced_at : cli arg dict → policy.assert_no_user_artifact
  tested_by   : test_orchestrator_o1_runner.TestNoUserArtifactPolicy
no_hardcoded_runtime_ids:
  enforced_at : RunContext.pin() (SECRET_KEY_DENYLIST)
                + to_jsonable() (output strip)
                + tests assert no PIN_* in any orchestrator module
  tested_by   : test_orchestrator_o1_run_context.TestPerRunContextPins
                + TestNoModuleLevelPins (11 modules scanned)
no_live_execution:
  enforced_at : __execution_enabled__ flag at package scope
                + 4 phase bodies guard on it
                + runner.cut() refuses Mode.LIVE on the flag
  tested_by   : test_orchestrator_o1_runner.TestLiveModeRefused
no_silent_retry:
  enforced_at : evaluate_internal converts NotImplementedError →
                StopInvariantFailed (refuses to skip)
sovereign_authority_preservation:
  enforced_at : SG_2 requires fresh review_decision_id in the
                approval doc; validate_sovereign_approval refuses
                if missing
  tested_by   : TestApprovalValidation.test_sg2_requires_review_decision_id

3. LOC budget vs design

design_budget_orchestrator : ≤ 1500 LOC (doc 06 §10)
actual                     : 1741 LOC (~ +16%)
delta_explanation          : richer test-foundation (gates registry +
                             discoverer Protocol + queue loader fully
                             implemented) was chosen over deferring
                             contracts. O2 will not need additional
                             contract authoring; it just fills bodies.

design_budget_tests        : ≤ 500 LOC (doc 06 §5)
actual                     : 515 LOC (~ +3%)

4. Verdict

g2_outcome                  : PASS
modules_authored            : 24 .py files
contracts_authored          : 11 named contracts (above §1)
cross_cutting_invariants    : 5 (table §2)
production_mutation         : NONE
existing_v0_5_modules_touched: 0