Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0103

ADR-0103: The byte-faithful LIFT is the parity oracle, not the deliverable; the clean target is the deliverable

← ADR-0102 · ADR-0104 →

The record

• Status: Accepted (probationary) — 2026-10-15, Mohamed: "RATIFY … BUT ON PROBATIONARY BASIS UNTIL PROVEN WITH POC". Lifts to full Accepted when the POC gate below passes; reverts (Superseded by AD-7's byte-faithful method) if it fails.
• Date: 2026-10-15
• Spec: components refactor (plans/orchestrata-components-design-2026-10-14.md); supersedes AD-7, amends RULES-15; builds on ADR-0008

Context

The components refactor ports ~122K LOC from the frozen monolith (orchestrata-frozen @ e57782ea4) into nine packages. The running method (AD-7, RULES-15) makes a byte-faithful LIFT the deliverable: "the executor copies the body into the region and applies only the listed changes; it never rewrites from scratch."

Two measurements on 2026-10-15 break that method:

1. The LIFT is deterministic, not an LLM task. A ~150-line pure-stdlib script (/tmp/opencode/lift-proof/fill.py) reproduces 25 of 34 committed contracts wave-1 files byte-identically from the increment brief alone (skeleton header + the brief's pre-computed import block + @traces line + ORIGINALS body). The other 9 differ only in three mechanical assembly cases — from __future__ import annotations placement, module-level residue (TypeVar, _TYPE_PARSERS, helper functions), and import-block detection in multi-module briefs. Zero of the 34 required LLM judgment. The brief's ORIGINALS are themselves a verbatim copy of frozen (orchestrata-frozen/src/orchestrata_ultimate/core/base/error.py lines 7–66 == C-02's ORIGINALS, confirmed). So the byte-faithful LIFT is a script, and the night-swarm's executor tier was a copy-paste machine.

2. Byte-faithful ships the mess. A verbatim LIFT carries frozen's debt into nine new packages: the dead contracts protocols ISessionManager/ICarryoverManager/IPortfolioManager (measured: zero implementers anywhere in frozen), the 4,131-LOC claude/tools/session fork (79 divergent body_hashs), the frozen sync_context_md ContextManager import defect, and the cross-package duplication (EscalationResult ×4). The stated goal is a cleaner design and codebase — a byte-faithful LIFT delivers a repackaged mess with nicer folder boundaries.

The night of 2026-10-14/15 measured the cost of the byte-faithful-deliverable method: ~9 hours, 7 designers, 61 authority rulings, 53 lessons, and ~32 landed classes — judging/review/re-loop overhead 10–50× the executor work (lessons.md L39, L24), with executor deception (L34), a fabricated executable (L35), quota exhaustion (L29) and a 3-hour commit freeze on a 0-byte index.lock. ADR-0008 already established the deeper point: gates check transcription, not intent — a byte-faithful port certifies only that the copy matches, never that the original was right.

Decision (proposed)

Keep two separate copies, and make the clean one the deliverable:

• Copy 1 — the ORACLE (byte-faithful LIFT). Regenerated on demand from frozen by the deterministic filler (serialize_codebase_ast source <qname> + --residue + the import re-point map + realize's @traces id + realize's skeleton header). Never committed; ephemeral; equals design/current.mmd ("what IS"). It carries frozen's mess on purpose — it is the parity baseline, not shipped code.
• Copy 2 — the GOAL (clean target). packages/<c>/src/, designed to design/target.mmd (the 6-layer model of architecture/modular-monolith.md, contracts-first, debt removed). This is the deliverable.

Copy 2 is gated by two checks:

1. Behavioural parity vs the oracle — deep-compare Copy 2 against the regenerated Copy 1, and the generated parity tests pass against both. Proves no behaviour was lost while cleaning.
2. Conformance to target.mmd — diff_design_vs_code: the clean shape is achieved (no dead protocols, no duplication, no outbound edge outside the §2 DAG).

The oracle is the safety net that licenses aggressive cleaning: any dropped behaviour fails parity, so the reshape is proven, not hoped. A deliberate behaviour change vs frozen (e.g. fixing a frozen bug) is a ruled, recorded deviation — it surfaces as a parity diff that is explicitly dispositioned, never a silent regression.

This supersedes AD-7 (byte-faithful LIFT as deliverable) and amends RULES-15 (ORIGINALS remain REQUIRED, but as the oracle's input, not the shipped bytes).

Alternatives rejected

• Byte-faithful LIFT as the deliverable (current AD-7 / RULES-15). Safe (provably no behaviour change) but ships frozen's mess; contradicts the goal. Loses.
• Clean redesign from scratch, no oracle. Reaches the clean goal but has no baseline to prove behaviour preservation — silent regressions. Loses on safety.
• LIFT-then-tweak-in-place (the swarm's FULL-gate exceptions). Conflates oracle and deliverable: parity has no clean baseline, and the mess persists wherever a tweak didn't reach. This is what the night-swarm did; it produced ~32 classes and 61 rulings. Loses.

Consequences

• The model allocation flips. The deterministic filler produces the oracle for free; LLM/agents move to the reshape (oracle → clean target), the genuine design work. The cheap-model executor tier is unnecessary for the mechanical ~90%.
• Parity becomes script-vs-script (mechanical), so human/AD rulings move from "is this byte-faithful?" to "is this the right clean shape?" — far fewer one-way-door rulings, and the design tar pit (AD-51/54/55 import-order/ruff-config/free-names) collapses into generator config.
• The 6-layer model becomes the target.mmd prior, so component boundaries stop being re-litigated per census (AD-40's boundary moves become layer assignments).
• New tooling owed: (a) finish the filler's 3 mechanical cases → 34/34, then drive it off frozen + the re-point map (generalizes to the 4 un-briefed components: volks, gateway, plugin, integration); (b) a parity-vs-oracle gate (deep-compare clean vs regenerated LIFT) wired into realize --verify; (c) the A1 boundary verb (§2 DAG as data). The filler is the missing verb between realize (skeleton+regions+tests) and realize --verify (gate).
• Risk: cleaning is where bugs enter — mitigated by the parity oracle, which is the entire point of keeping a separate byte-faithful copy.
• Frozen-bug cleanup becomes a first-class, safe activity: the historical @traces corpus is ~55% fully-correct and frozen carries known defects; under parity-vs-oracle, fixing one is a ruled deviation, not a guess.

Probation — POC gate (Mohamed: "ON PROBATIONARY BASIS UNTIL PROVEN WITH POC")

The decision is Accepted but probationary. It becomes the standing method for all nine components only when a proof-of-concept demonstrates the two-copy loop end-to-end on one real increment, with every criterion measured (no criterion is "looks right"). DONE-WHEN, all five:

1. Oracle is complete and brief-independent. The filler, driven off frozen (serialize_codebase_ast source <qname> + --residue) + the import re-point map — not the brief prose — reproduces 34/34 committed contracts wave-1 files byte-identically (cmp exit 0 on all 34; today it is 25/34, the 9 residuals being __future__, residue, and multi-module import detection).
2. Oracle generalizes. The same frozen-driven filler produces a byte-faithful oracle for one un-briefed component module (volks/gateway/plugin/integration) with no brief at all — ast.parse clean, its parity-test scaffold generated.
3. Clean reshape preserves behaviour. For one module, produce Copy 2 (the clean target) that removes a measured piece of frozen debt (e.g. delete a zero-implementer protocol, or collapse a duplicated DTO) and passes behavioural parity vs the oracle: deep-compare shows every public member of the oracle present with a compatible signature, and the module's parity tests are green against both copies.
4. The parity gate is deterministic and can FAIL. The parity-vs-oracle check runs as a script/verb (no LLM), exits 0 on the conforming clean copy, and exits non-zero on a deliberately-introduced behaviour-dropping mutation (a hand mutant is caught). A gate that cannot fail proves nothing (ADR-0008; lessons L31/L38).
5. Conformance to target. diff_design_vs_code shows Copy 2 conforms to target.mmd with no new outbound edge outside the §2 DAG.

Pass → probation lifts, ADR-0103 is fully Accepted, the method replaces AD-7 across all components, and the owed tooling (filler 34/34 + frozen-driven, the parity-vs-oracle verb in realize --verify, the A1 boundary verb) is scheduled. Fail → this ADR is marked Superseded (byte-faithful AD-7 stands) and the failing criterion is recorded with its measurement. Either outcome is committed, never left in chat.

Provenance

Mohamed, 2026-10-15, verbatim: "the goal is cleaner design and codebase not mess" and "i need a separate copy." Driven by the LIFT-fill proof (/tmp/opencode/lift-proof/fill.py: 25/34 byte-identical from the brief; frozen core/base/error.py:7–66 == C-02 ORIGINALS) and the night-swarm throughput collapse (plans/tracking/lessons.md L39, L24, L29, L34, L35). Supersedes AD-7; amends RULES-15; builds on ADR-0008 (transcription ≠ correctness) and the §4.5 current.mmd/target.mmd conformance loop of the components design. Ratified by Mohamed 2026-10-15, verbatim: "RATIFY" then "BUT ON PROBATIONARY BASIS UNTIL PROVEN WITH POC" — Accepted, probationary, lifting only when the five-criterion POC gate above passes; status flipped Proposed → Accepted (probationary) the same turn; AD-63 records it in the components log.

Related ADRs

• Also mentioned: ADR-0008

Rulings cited

None.

Specs cited

None (or no spec page exists for the ones named).