Incomex AI Portal
KB-28F6

Orchestrator O2 · 02 Phase Body Implementation Summary

11 min read Revision 1
dot-iu-cutterv0.6orchestrator-o2-phase-body-e2e-authoringphase-body-implementationg2-pass11-phases-filleddieu442026-05-20

Orchestrator O2 · 02 Phase Body Implementation Summary

doc 2 of 7 · 2026-05-20 · G2 gate

phase                : G2 — phase body implementation against in-memory simulator
outcome              : G2 PASS — 11 phase bodies filled; 0 production calls
production_mutation  : NONE
live_db_connect      : 0

1. Surface added vs O1

files_modified:
  cutter_agent/orchestrator/__init__.py          : milestone tag O1 → O2;
                                                    kill-switch banner refreshed
  cutter_agent/orchestrator/discover.py          : +233 LOC — 4 dataclasses
                                                    + 8 simulator methods on
                                                    InMemoryDiscoverer
  cutter_agent/orchestrator/run_context.py       : +4 LOC — consumed_approval_ids
  cutter_agent/orchestrator/state_store.py       : +12 LOC — enum-aware restore
  cutter_agent/orchestrator/runner.py            : +130 LOC — resume() invokes
                                                    post-sovereign phase body
                                                    + drift recheck + generic-
                                                    exception trap
  cutter_agent/orchestrator/phases/source_pin.py : unchanged (already filled in O1)
  cutter_agent/orchestrator/phases/mark.py       : +75 LOC — region_sha derivation,
                                                    candidate_count cap (≤1000),
                                                    drift refusal
  cutter_agent/orchestrator/phases/cutplan.py    : +94 LOC — two-pass writer_digest
                                                    determinism, vocab coverage,
                                                    idempotency-key uniqueness
  cutter_agent/orchestrator/phases/backup.py     : +48 LOC — DRYRUN marker,
                                                    LIVE refusal while killswitch off
  cutter_agent/orchestrator/phases/grant_probe.py: +34 LOC — 4-bit matrix check
                                                    → StopGrantDelta on any drift
  cutter_agent/orchestrator/phases/cut_leg_a.py  : +82 LOC — SG_1 evidence assertion,
                                                    deterministic change_set_id mint,
                                                    fan-out simulator → N row count
  cutter_agent/orchestrator/phases/structural_verify.py
                                                  : +44 LOC — 11-bool probe call
                                                    + 6 boolean invariants
  cutter_agent/orchestrator/phases/leg_b_record.py
                                                  : +57 LOC — deterministic
                                                    manifest_envelope_id +
                                                    executor_signature_id
  cutter_agent/orchestrator/phases/write_verify.py
                                                  : +61 LOC — G-VERIFY-ONCE
                                                    enforcement against
                                                    discoverer counter
  cutter_agent/orchestrator/phases/lifecycle_enact.py
                                                  : +86 LOC — SG_2 evidence,
                                                    fan-out fn_iu_enact simulator,
                                                    trigger-enabled post-check
  cutter_agent/orchestrator/phases/closeout.py   : +45 LOC — pre-req phase pass
                                                    audit, summary_sha pin,
                                                    runs-index append

LOC_delta_orchestrator_package : +1226 LOC (1741 → 2967 — incl. tests harness)
new_test_files                  : 3 (+ 1 shared harness)

2. Per-phase body — design + safety claim

2.1 source_pin

  • Unchanged from O1. Pure read-only via Discoverer.find_source_document + Discoverer.latest_source_version. Pins manifest_digest, region_sha, source_version_string.

2.2 mark

  • Calls discoverer.mark_region(ctx.source_version_id).
  • Re-derives region_sha as sha256 over (canonical_address|content_hash|sort_order) per row.
  • Asserts 0 < count ≤ MAX_CANDIDATES_PER_DOC (=1000) — refuses zero rows and oversized rowsets fail-closed.
  • If source_pin already pinned a region_sha and the derived value differs → StopInvariantFailed (drift detection).
  • Pins region_sha, candidate_count, mark_rowset_sha.

2.3 cutplan

  • Two-pass determinism: runs discoverer.cutplan_rebuild(mark_rows, salt=0) and cutplan_rebuild(reversed(mark_rows), salt=1). Computes _writer_digest() over each. Mismatch → StopInvariantFailed.
  • Vocab coverage: every row's unit_kind and section_type MUST appear in discoverer.vocab_snapshot().
  • Idempotency uniqueness: len(set(idempotency_keys)) == len(rows).
  • Pins writer_digest, candidate_count_confirmed, cutplan_payload_sha, cutplan_rows (opaque JSON-safe row payload for cut_leg_a).

2.4 pre_write_backup

  • Mode.LIVE + killswitch off → ProductionExecutionNotAuthorized (live pg_dump + GPG envelope deferred to O4).
  • Mode.DRYRUN: builds a deterministic backup-marker payload (run_id, document_id, source_version_id, writer_digest), computes sha256, pins backup_sha, backup_size_bytes, backup_gpg_fpr (placeholder SIMULATED-DRYRUN-GPG-FPR-NOT-A-REAL-KEY).
  • KB reporter writes a phase doc capturing the simulator artifact.

2.5 grant_probe

  • Reads discoverer.grant_matrix() (4 booleans + snapshot_sha).
  • ANY false bit → StopGrantDelta with explicit listing (cutter_exec/cutter_verify/directus/PUBLIC).
  • Pins grant_probe_sha.

2.6 cut_leg_a — POST sovereign gate

  • Mode.LIVE + killswitch off → ProductionExecutionNotAuthorized.
  • Mandatory: SG_1 approval record must already exist on ctx.sovereign_approvals (runner.resume records it before invoking).
  • Mandatory pins: writer_digest, candidate_count_confirmed, cutplan_rows.
  • Mints change_set_id deterministically as UUID(sha256(run_id|writer_digest)[:16], version=4) — replay-safe across crashes.
  • Fan-out via discoverer.simulate_iu_creates(change_set_id, rows) → returns N IUCreateResults. Refuses if cardinality drifts or any status ≠ created.
  • Pins change_set_id, cut_leg_a_simulated=True, cut_leg_a_committed=True, cut_leg_a_row_count, lifecycle_status_uniform_draft=True.

2.7 structural_verify

  • Calls discoverer.structural_probe(doc_prefix, expected_count) — returns 6 booleans + probe_payload_sha.
  • Refuses if ANY of lifecycle_status_uniform_draft, section_type_cardinality_matches, forbidden_id_intrusion_zero, anchored_exact, body_hash_match, candidate_count_matches_expected is False.
  • Pins structural_verify_payload_sha, structural_verify_passed=True.

2.8 leg_b_record

  • Mode.LIVE + killswitch off → ProductionExecutionNotAuthorized.
  • DRYRUN: derives manifest_envelope_id and executor_signature_id as deterministic UUIDs from (change_set_id, role) — same change_set always produces the same governance IDs (G-LEG-B-ONCE precondition).
  • Records bookkeeping on discoverer._record_manifest_envelope(change_set_id) so write_verify can audit the count.
  • Pins manifest_envelope_id, executor_signature_id, leg_b_committed=True, leg_b_payload_sha.

2.9 write_verify

  • Mode.LIVE + killswitch off → ProductionExecutionNotAuthorized.
  • G-VERIFY-ONCE: refuses if discoverer.verify_result_count_for(change_set_id) ≥ 1 before this call (StopInvariantFailed).
  • DRYRUN: derives verify_result_id and verifier_signature_id as deterministic UUIDs from (change_set_id, role).
  • Records counter on discoverer; pins verifier_principal='cutter_verify', verify_result_id, verifier_signature_id, write_verify_passed=True.

2.10 lifecycle_enact — POST sovereign gate (MVP draft→enacted only)

  • Mode.LIVE + killswitch off → ProductionExecutionNotAuthorized.
  • Mandatory: SG_2 approval record with non-null review_decision_id on ctx.sovereign_approvals (runner.resume injects it).
  • Mandatory pins: change_set_id, candidate_count_confirmed, cutplan_rows.
  • Pins review_decision_id (mirrors design doc 03 §7 — fresh per phase).
  • Fan-out via discoverer.simulate_fn_iu_enact(addresses, review_decision_id, change_set_id). Refuses cardinality drift / any status ≠ enacted.
  • Post-check: discoverer.lifecycle_triggers_enabled() == True and discoverer.iu_lifecycle_log_count_for(change_set_id) == N. Failure → StopInvariantFailed.
  • Pins lifecycle_enacted_count, lifecycle_enacted=True, immut_triggers_enabled_o=True.

2.11 closeout

  • Asserts every prior phase's PhaseRecord.result == 'passed'. Missing/failed → StopInvariantFailed.
  • Computes closeout_summary_sha over (run_id, document_id, change_set_id, writer_digest, lifecycle_enacted_count).
  • Uploads phase doc + appends a one-line entry to runs-index.md via KB reporter.
  • Pins closeout_summary_sha, all_phase_docs_uploaded=True, sidecar_state_final='success', runs_index_appended=True.

3. Runner / handshake — design changes

runner.cut() :
  unchanged_contract  : refuses Mode.LIVE while __execution_enabled__ False
  unchanged           : creates RunContext, acquires fcntl lock, drives forward
  new                 : drive-loop now wraps any non-OrchestratorError as
                        StopInvariantFailed (no raw traceback leak)
                        AND uploads a STOP KB doc on every stop

runner.resume() :
  unchanged           : refuses if at AWAITING_* and approval_kb_id None
  new                 : approval validation now active:
                         1) refuse replay (consumed_approval_ids list)
                         2) validate via validate_sovereign_approval
                            (correct gate, TTL, run_id match, SG_2
                             review_decision_id presence)
                         3) record ApprovalRecord on ctx
                         4) drift-revalidate (live source_version vs pins)
                         5) invoke post-sovereign phase body
                         6) advance state via ctx.finish_phase + ctx.state=…
                         7) re-enter drive loop
  idempotency         : resume on closed-out run returns immediately (no-op)
  stop_doc_upload     : every stop uploads a KB STOP doc via DryRunReporter

4. Verdict

g2_outcome              : PASS
phase_bodies_filled     : 11/11
mutating_phases_guarded : 4/4   (cut_leg_a, leg_b_record, write_verify, lifecycle_enact)
live_db_calls           : 0
live_subprocess_calls   : 0
live_network_calls      : 0
secrets_in_code         : 0
production_mutation     : NONE

LOC budget: the orchestrator package grew 1741 → 2967 LOC (+71%). The growth is concentrated in the phase bodies (1226 LOC across 11 files) and is dominated by docstrings + invariant assertions. No design refactor was needed.

Back to Knowledge Hub knowledge/dev/laws/dieu44-trien-khai/v0.6-orchestrator-o2-phase-body-e2e-authoring/02-phase-body-implementation-summary-2026-05-20.md