ADR 0029 — Bounded Structure And Format Debt Transition For UUID Candidates¶
- Status: proposed (not approved)
- Written: 2026-09-27
- Decision owner: Product architecture reviewer
- Implementation consumer: the exact integration delivery candidate of NS1-009
- Related decisions: ADR 0015, architecture change method
Background And Acceptance Scope¶
The per-table functional evidence of NS1-009 is maintained separately. As of 2026-09-27, in the
shared worktree at qa HEAD 2b81fbb0b, pnpm verify:foundation ended with unit checks 156/156
PASS and then 7 architecture FAIL: source inventory digest 1, five registered oversized owner
paths, and one ignored importer not included in the delivery candidate. A separate
pnpm format:check fails on 1,292 files; against the 10:34 UTC snapshot 1,149 files are
outside the dirty range and 143 are dirty. These numbers are a shared-worktree measurement and
are not yet the result for the exact Git delivery tree.
Regenerating the current baseline against new sources, or relaxing the format check, can make the check pass, but that alone does not accept the growth of oversized owners or the existing format debt. Under ADR 0015, implementation work does not change its own structural validation rules or exceptions; the architecture reviewer approves the option first and an independent verifier checks the exact candidate. This document does not mean an approval or a change to verification criteria.
29 further rows with missing required relation UUIDs in T100, T101 and T103 were found and corrected in the live DB against active parents of the same tenant, and a re-read found 0 missing or mismatched active required relations in the three tables on a separate connection. The three PHP writers currently serving production are an earlier version that does not write those UUID relation values, so they differ from the local fix candidate. The call that produced the 29 rows could not be identified, but because the source now serving can produce the same defect again, data monitoring and further correction may be needed while delivery is held. The per-row basis, the backup and the recovery boundary are in T100/T101/T103.
Actual Size Of The Oversized Owners¶
The five remaining growth paths in the current structural error are below. The numbers are in
bytes and include generated files. Even if B is approved, the right-hand figure is only a candidate
ceiling to review, not a currently approved exception. packing.ts and the two Wiki generated
files are at the current HEAD; TransloadExperience.tsx and inventory-write.ts are part of the
shared worktree change. The ignored legacy-operational-import.mjs is a non-delivered file of
another piece of work. The digest is measured once the source inventory of the exact Git candidate
is settled.
| Path | Baseline | Current | Growth |
|---|---|---|---|
apps/web/src/composition/pages/transload/TransloadExperience.tsx |
63,362 | 64,581 | +1,219 |
packages/db-mysql/src/packing.ts |
27,600 | 27,722 | +122 |
packages/db-mysql/src/trade/inventory-write.ts |
60,575 | 61,879 | +1,304 |
packages/user-wiki/src/development-specifications-index.generated.ts |
747,367 | 785,971 | +38,604 |
packages/user-wiki/src/development-specifications.generated.ts |
4,203,276 | 4,316,776 | +113,500 |
The 143 dirty files with format errors also contain changes from other sessions. Option B's changed-file gate needs an explicit criterion that covers both the scope of the exact delivery candidate and the format debt of the existing files.
The 23 growth paths from the first measurement and the phased repairs are preserved in the NS1-009 common history.
Options To Review¶
A. Keep The Current Baseline And Clean Everything¶
Actually split and shrink the five remaining oversized owners inside their semantic owner, clear all 1,292 format errors, and have an independent verifier check the new digest and structural metrics. The advantage is that the existing no-growth rule and the whole-format gate are preserved as they are. The disadvantage is a large change that includes 1,149 clean files beyond the UUID transition scope, and it can conflict with other work in the shared checkout. File moves and extractions each have to verify their existing consumers and their public boundary.
B. Time-Bounded Debt Exception Plus Changed-File Format Verification¶
First separate the real duplicated responsibility among the current oversized owners, then review only the remaining paths as a temporary exception with an exact candidate, a ceiling, an owner and a removal criterion. Manage the format debt of the existing clean files as a frozen list, and check that this candidate and every later changed file passes formatting. The advantage is that mechanical reformatting unrelated to the UUID transition is separated out while new debt growth is blocked. The disadvantage is that it is a policy change to both the structural exception and the format gate, temporarily replacing the existing debt-reduction principle of ADR 0015, so it needs independent approval, implementation, verification and a removal plan. Merely updating the baseline, or unconditionally exempting every failing file, is not part of this option.
C. Hold The Delivery And Finish Structure And Format Cleanup As Separate Work¶
Preserve the current functional result but do not promote NS1-009 to deployment-ready DONE. After
a separate cleanup of the structural owners and the whole format debt, re-verify the exact
integration candidate. The advantage is that policy and product change scope are not mixed. The
disadvantage is a longer period in which the code serving production trails the UUID transition
candidate.
Pre-Decision Checks And Application Conditions¶
- The architecture reviewer explicitly picks one of A/B/C with its cost, operational impact and removal timing. If B is picked, approve the ceiling and removal responsibility per oversized owner, the handling of new changes to frozen format files, and the condition for returning to the next strict gate.
- Until the option is chosen, do not change the validator, the baseline or the format gate. After approval, implement the governance change and the Product source repair as separate review units, and have the independent verifier re-run structure, format, quality and build on the same exact delivery tree.
- The ignored importer is not included in the delivery candidate, and files belonging to other sessions are not deleted. Distinguish the staged and unstaged hunks that actually belong in a real release candidate.
- No option automatically approves MySQL relation verification, real role or browser acceptance, production migration readback, Git promotion, or any Production runtime effect.
Source:
new-system/docs/decisions/0029-bounded-structure-and-format-debt-transition.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.