KB-28B5 rev 21

FIX7 Refactor Blueprint - Implementation Package Split

16 min read Revision 21
fix7architecturerefactor-blueprintpackage-split

07 - Implementation Package Split

Future work is split into dependency-safe packages. Each has scope, rollback, tests, a single runner class, and a no-go condition. Packages are sequenced; a later package may not start until its predecessor passes and (where marked) a fresh Codex re-audit. No package secretly enters Stage 2.6B; the production-mutation packages remain OPERATOR_GATED.

Terminology - operator_authorization vs the blocked permit (Codex BLOCKER 7 / CHECK_J)

The earlier blueprint used "permit" ambiguously for two unrelated things. They are now separated; the word "permit" is reserved for the blocked admission/backfill concept only. (Note: the governing law does not use the word "permit" at all - it expresses package-execution authority via OPERATOR_HANDOFF_MODE / the §3.4 Authority Pack / §4J Operator Surface Rule; operator_authorization below maps to those.)

term meaning state under FIX7
operator_authorization (artifact: operator_authorization_artifact) permission for an OPERATOR to execute a migration/cutover package (PKG-E..H). Carries approved_package_sha256, reviewer/owner identity, authorization_scope, expiry/epoch, both-EXCEPT/read-back proof. It is NOT the blocked permit; it does NOT open QT001 apply, admission, REAL_RUN, or Stage 2.6B; it creates NO readiness gate. required per package; the only thing a fresh Codex re-audit + operator grants
qt001_backfill_permit (= the birth/admission permit) permission to run QT001 backfill/apply BLOCKED (unchanged)
REAL_RUN_authority permission to run real scale/capability execution BLOCKED (unchanged)
QT001 apply authority fn_dot_birth_qt001_apply / sp_dot_birth_qt001_apply apply path BLOCKED since Codex NOT_SAFE (unchanged)

Every PKG-E/F/G precondition says operator_authorization, never "permit". Guard G-NO-QT001-PERMIT-DURING-FIX7 fails any package that opens/consumes a qt001_backfill_permit, REAL_RUN authority, or QT001 apply authority, or that conflates operator_authorization with any of them.

Package types used

  1. author-only (T1 authors artifacts; nothing applied)
  2. local/rehearsal (BEGIN..ROLLBACK on a non-production rehearsal target)
  3. read-only validation (live read-only guards)
  4. operator-gated production (operator applies under explicit authority)
  5. post-cutover verification

Packages

PKG-A - Foundation + 27 surfaces + runtime-evidence DDL (author-only)

  • package_id: PKG-A; type: author-only.
  • scope: S01-S08 DDL artifacts (roles/schema/domains/catalog/anchors/27 contracts/registries/11 runtime-evidence/deferred constraints) as reviewable SQL. Not applied.
  • included steps: S01-S08. excluded: any seal/activate/repoint/cutover/freeze.
  • preconditions: this blueprint passes Codex critical review; implementation-authoring authorized.
  • output artifacts: byte-level SQL files + per-contract negative-test specs.
  • validation: static review vs approved doc 02 byte DDL; T1 stop on any conflict.
  • rollback: n/a (nothing applied).
  • who can run: T1 (author). next: PKG-B.
  • no-go: any DDL diverges from approved design; any UNKNOWN_REQUIRES_REVIEW remains.

PKG-B - Sealed DATA authoring (author-only)

  • package_id: PKG-B; type: author-only.
  • scope: S09-S10 DATA artifacts: catalog rows, 27-manifest item rows, #20 authority-scope rows + expected-constraint set, #21 Directus read-contract rows (== enumerated existing SELECT), 14 readiness-gate rows, 7 hash contracts (H04_SCOPE_V1, H02/H05 total orders), #05 retention, #06 thresholds, #23 workload profiles. Not applied.
  • preconditions: PKG-A artifacts complete; S00 read-only Directus SELECT grant-set capture available (MX-1 - the read-only capture runs ahead of PKG-B; PKG-D later re-validates it). #21 authoring is blocked until the captured set exists.
  • output: seed-data files + hash fixtures + exact-set manifests.
  • validation: G-GATES-14, G-HASH-7, G-HASHDET, G-EXACTSET-20 run as static fixtures.
  • rollback: n/a. who: T1. next: PKG-C. no-go: count drift (27/11/14/7) or non-deterministic hash.

PKG-C - Rehearsal apply + exact-set + seal (local/rehearsal)

  • package_id: PKG-C; type: local/rehearsal.
  • scope: apply PKG-A+PKG-B on a rehearsal target inside BEGIN..ROLLBACK; run S11 exact-set both- EXCEPT, CP-06 fixtures, full 27-contract negative suite, dropped-deferred-FK -> OBJECT_AUTHORITY_IMMUTABLE; rehearse S12 seal.
  • excluded: production apply; activation; repoint; cutover.
  • preconditions: PKG-B complete.
  • output: rehearsal evidence (real rejections, recomputed hashes), reversal-order proof.
  • validation: every guard in doc 06 marked S11/S08; no literal PASS rows.
  • rollback: ROLLBACK (rehearsal). who: T1 (rehearsal) + operator approves rehearsal target.
  • next: PKG-D. no-go: any EXCEPT non-empty; any negative test green-by-literal; reversal fails.

PKG-D - Read-only repoint proof authoring (read-only validation + author-only)

  • package_id: PKG-D; type: read-only validation.
  • scope: S00 re-baseline + S13 authoring: dump live writer/gateway sources, bind #26/#27 source_sha256 + rollback stub + STUB_FAIL_CLOSED body bindings; pin the #26 gateway identity; author dependency_manifest #11 closure + the sealed legacy-disposition set (#20); run G-NOLEGACY-PRE (structural closure + sealed-set completeness; does NOT require EXECUTE revoked), G-LEGACY-TARGET-SEALED, G-WRITER-GATEWAY-IDENTITY, G-REPOINT-SRC, G-UNKNOWN-ZERO read-only against live.
  • excluded: any live repoint/seal/activate. PKG-D runs only G-NOLEGACY-PRE, never the post-state guard - so it does not falsely require EXECUTE already revoked while every legacy routine is still PUBLIC-executable (Codex BLOCKER 2 / CHECK_G).
  • preconditions: PKG-C passes; fresh Codex re-audit of PKG-A..C.
  • output: repoint manifest rows + #11 reachability proof (legacy_reached=0) + sealed legacy-disposition set + captured Directus SELECT grant set artifact (MX-1) for PKG-B #21 authoring.
  • validation: G-NOLEGACY-PRE, G-LEGACY-TARGET-SEALED, G-WRITER-GATEWAY-IDENTITY, G-REPOINT-SRC, G-DOT-FROZEN, G-BIRTH-NEUTRAL (baseline).
  • rollback: n/a (read-only). who: T1 (read-only). next: PKG-E.
  • no-go: any legacy object reachable; any unknown object; source hash mismatch.

PKG-E - Production apply: create + seal + activate (operator-gated production)

  • package_id: PKG-E; type: operator-gated production.
  • scope: S01-S12 apply + S14 activation on production, under explicit operator authority and quorum. Creates the qt001_cp control plane and activates the sealed manifest.
  • excluded: owner/ACL cutover; legacy freeze; live writer repoint cutover; REAL_RUN; QT001 apply.
  • preconditions: PKG-D passes + fresh Codex re-audit + a valid operator_authorization (see §Terminology - package-execution authority ONLY; it is not a qt001_backfill_permit, opens no admission/QT001-apply/REAL_RUN, and creates no readiness gate).
  • output: live qt001_cp schema (active manifest), activation evidence.
  • validation: G-EXACTSET-20, G-EPOCH-TOCTOU, G-AUTH-27, G-RUNTIME-NONAUTH, G-BIRTH-NEUTRAL, G-NO-QT001-PERMIT-DURING-FIX7, G-DOT-NOOVERWRITE (qt001_cp owner-isolated at creation) live.
  • rollback: pre-activation reverse-order drop; post-activation new-candidate prior payload.
  • who: OPERATOR. next: PKG-F. no-go: any seal/activation check fails; birth row delta.

PKG-F - Authoritative live repoint cutover (operator-gated production)

  • package_id: PKG-F; type: operator-gated production.
  • scope: S15 - in one atomic operator transaction: repoint the live writer to the manifest-active path via the #26-pinned gateway, REVOKE EXECUTE (from PUBLIC, directus, every role except qt001_cp_owner) over the COMPLETE sealed legacy-disposition set (doc 02 §H - NOT a name pattern), then replace ONLY the STUB_FAIL_CLOSED-classified apply/writer/planner entrypoints with a fail-closed stub; every REVOKE_ONLY member keeps its body unchanged (Codex BLOCKER 3 - this removes the prior "replace each with a stub" wording that contradicted "stub only apply/writer" and made body-rollback impossible for the rest). Legacy neutralization is bundled here, not deferred to PKG-G.
  • excluded: owner/ACL cutover; legacy freeze.
  • preconditions: PKG-E active; a fresh independent Codex re-audit of the live repoint + neutralization (the authoritative repoint is a governance_change, which law §4G lists as a stop_without_asking_if hard-stop and explicitly excludes from the surgical-drift allowance - it must NOT be carried as a mechanical continuation of PKG-E) + a valid operator_authorization (§Terminology - not a qt001_backfill_permit); the sealed legacy-disposition set + per-object privilege_acl_hash snapshot read-back-verified; rollback artifacts (pinned #27 bodies, captured ACL) staged; G-NOLEGACY-PRE green live.
  • output: live authoritative path on qt001_cp; STUB_FAIL_CLOSED entrypoints fail-closed, REVOKE_ONLY entrypoints EXECUTE-revoked (body intact); rollback stub staged.
  • validation: G-NOLEGACY-POST (non-owner-effective-EXECUTE=0 over the sealed set; STUB members fail-closed), G-NOMIXED-AUTHORITY, G-WRITER-GATEWAY-IDENTITY, G-LEGACY-TARGET-SEALED, G-BIRTH-NEUTRAL, G-NO-QT001-PERMIT-DURING-FIX7, gateway fail-closed.
  • rollback: the atomic deactivation-first sequence (doc 05 note 5): supersede new path → verify readiness BLOCKED → verify gateway cannot route new path → restore per disposition (STUB: pinned #27 body + ACL; REVOKE_ONLY: ACL only) → verify G-NOMIXED-AUTHORITY + G-BIRTH-NEUTRAL.
  • who: OPERATOR. next: PKG-G. no-go: any legacy effective-executable by non-owner OR reachable; mixed old+new authority; birth delta; gateway not fail-closed; target set not the sealed set.

PKG-G - Owner/ACL cutover (operator-gated production)

  • package_id: PKG-G; type: operator-gated production.
  • scope: S16 - capture the complete effective-privilege ACL snapshot (per doc 05 invariant 3: owner + full relacl SELECT/INSERT/UPDATE/DELETE/TRUNCATE/REFERENCES/TRIGGER + proacl EXECUTE + sequence ACLs + pg_attribute.attacl column ACL + schema nspacl + pg_default_acl default privileges + role-membership/effective privilege via pg_auth_members + enumerated PUBLIC/Directus/qt001_cp_* grants + snapshot_sha256; mandatory rollback artifact); transfer ownership of only qt001_cp control objects + the sealed legacy-disposition set (doc 02 §H, never a name-pattern scan) to qt001_cp_owner; REVOKE directus/PUBLIC authority on those control objects only; re-grant exact #21 SELECT. The #26 gateway has no owner transition (born qt001_cp_owner). Directus retains full authority over its own directus_* application tables and the business base tables it legitimately owns (XH-4).
  • excluded: legacy freeze/deprecate; any change to directus_* app tables or business-table ACL.
  • preconditions: PKG-F stable; a fresh independent Codex re-audit of the owner/ACL cutover (the most destructive governance_change - it strips the directus authority that holds readiness BLOCKED; law §4G stop_without_asking_if, never mechanical) + a valid operator_authorization (§Terminology - not a qt001_backfill_permit); G-DIRECTUS-READ preflight green; the complete effective-privilege ACL snapshot above captured, hash-bound, read-back-verified, and restore-rehearsed before any REVOKE (MX-3 + Max-E + Codex BLOCKER 5).
  • output: cutover evidence + verified hash-bound prior-ACL snapshot.
  • validation: G-OWNER-CUTOVER (effective-privilege, role-membership-aware, column-ACL-inclusive), G-DIRECTUS-READ (SELECT preserved), G-DIRECTUS-APP-INTACT, G-NO-QT001-PERMIT-DURING-FIX7, PUBLIC EXECUTE on control objects gone.
  • rollback: restore prior ownership + full effective-privilege ACL from the verified snapshot; verify both-direction effective-privilege match.
  • who: OPERATOR. next: PKG-H. no-go: Directus loses required SELECT OR its directus_*/business-table authority; unverified/unhashed ACL snapshot; column-ACL or role-membership leak; readiness false-unblock.

PKG-H - Legacy freeze + deprecate (operator-gated production)

  • package_id: PKG-H; type: operator-gated production.
  • scope: S17-S18 - freeze then deprecate the 20 tables/46 fns/196 legacy views; never DROP live.
  • preconditions: PKG-G stable; #11 proves no birth/QT-002 dependence on frozen targets.
  • output: legacy frozen+deprecated, retained as read-only history.
  • validation: G-LEGACY-FROZEN, G-BIRTH-NEUTRAL, QT-002 path intact.
  • rollback: un-freeze / clear deprecation flag. who: OPERATOR. next: PKG-I.
  • no-go: any live-required object depends on a frozen target.

PKG-I - Post-cutover verification (post-cutover verification)

  • package_id: PKG-I; type: post-cutover verification.
  • scope: S19 - full guard suite; readiness gate facts; bypass-vector facts; scale runs (REAL_RUN is a SEPARATE later gate, not in this package).
  • preconditions: PKG-H complete.
  • output: final guard report.
  • validation: every doc 06 guard green.
  • rollback: n/a (read). who: T1 + operator. next: REAL_RUN / QT001 apply remain separately gated.
  • no-go: any guard red.

Package sequencing and gates

PKG-A -> PKG-B -> PKG-C --[Codex re-audit]--> PKG-D --[Codex re-audit + operator_authorization]-->
PKG-E --[fresh Codex re-audit + operator_authorization]--> PKG-F --[fresh Codex re-audit + operator_authorization]--> PKG-G -> PKG-H -> PKG-I
  ==> (REAL_RUN / QT001 apply / qt001_backfill_permit / Stage 2.6B: separate future gates, all BLOCKED)
  • PKG-A..D are authorable/rehearsal/read-only and contain no production mutation.
  • PKG-E..H are OPERATOR_GATED production and require explicit operator_authorization each (NOT a qt001_backfill_permit; see §Terminology).
  • The two governance-change packages - PKG-F (authoritative repoint + legacy EXECUTE revoke) and PKG-G (owner/ACL cutover) - additionally require a fresh independent Codex re-audit before they run, not only the one before PKG-E. Law §4G ("Surgical Drift Patch Allowance") lists governance_change as a stop_without_asking_if hard-stop and explicitly states the allowance "does not permit governance change" - so an authoritative repoint / authority-ownership cutover must STOP and be explicitly re-authorized, never carried as a mechanical continuation of PKG-E (Max-G; citation corrected this pass to the law's actual §4G text - the prior wording "must be independently re-reviewed" was a paraphrase, but the conclusion - an explicit stop + fresh re-audit gate - is exactly what §4G requires).
  • Machine-checkable package-transition evidence (Codex MG-01 / CHECK_C). A prose statement that a re-audit occurred is not sufficient. Each PKG-E/F/G transition consumes an operator_authorization artifact carrying: approved_package_sha256 (the exact reviewed package), reviewer/owner identity, authorization_scope (which package + which objects), expiry/epoch, and a both-EXCEPT/read-back proof that the live package == the approved hash. G-NO-QT001-PERMIT-DURING-FIX7 verifies the artifact grants package execution ONLY and never QT001 apply / admission / REAL_RUN.
  • No package mixes layers (DDL vs DATA vs repoint vs cutover vs freeze are separate).
  • Stage 2.6B is NOT a package here; it remains a separate blocked program (doc 08). The repoint / cutover / freeze packages are FIX7-refactor steps, not the 2.6B permit/run/keyset program.
Back to Knowledge Hub knowledge/dev/reports/architecture/t1-fix7-existing-system-refactor-execution-blueprint-2026-06-08/07-implementation-package-split.md