docs(adr-102): document the intentional two-validator layering (P6c)#490
Merged
Merged
Conversation
Chunk C evaluated whether to consolidate the two kg-backup/2 validators. Verify-in- code showed they are NOT drifting duplicates — they validate different layers for different consumers, so they are intentionally kept separate: - scripts/development/lint/lint_backup.py — the independent verification tool: a deliberately standalone spec oracle (NO api-package dependency) that doubles as a CI/test/build gate and an outside check on the serializer. Validates the RAW interned on-disk structure (dictionary index resolution, interning integrity, §6 exclusions, format negotiation). It does NOT use KgBackupV2Reader on purpose — the reader de-interns, which would mask the interning bugs this oracle exists to catch. - api/app/lib/backup_integrity.py — the runtime gate: validates the DE-INTERNED logical graph via KgBackupV2Reader (referential integrity + external deps + stats) before a backup is streamed/archived/restored. A shared core would force one layer's representation onto the other and couple the standalone oracle to the api package, sacrificing its Track-D independence; the narrow overlap doesn't justify it. Decision (with maintainer): document the split, don't merge. Adds cross-reference docstrings to both files so the layering is explicit and a future maintainer won't 'consolidate' them by mistake. Supersedes the old backup_integrity note that said consolidation 'is tracked for ADR-102 P6'. No behavior change. Restamps lint_backup @verified cffa180 -> b832d59.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ADR-102 P6c — chunk C resolved as document-don't-merge
Chunk C was scoped to "consolidate the two drifting kg-backup/2 validators." Verify-in-code
inverted that premise: they are not duplicates — they validate different layers for
different consumers, and merging them would do harm. So this PR documents the intentional
separation rather than forcing a shared core.
The finding
scripts/development/lint/lint_backup.pyapi/app/lib/backup_integrity.pyKgBackupV2Reader(referential integrity, external deps, stats)lint_backupdeliberately does not useKgBackupV2Reader— the reader de-interns, whichwould hide the very interning bugs the oracle exists to catch. A shared core would force one
layer's representation onto the other and couple the standalone oracle to the api package,
sacrificing the independence that makes it a useful CI/build check. The real overlap
(reference/external-dep checks) is narrow and expressed on incompatible layers.
What changed
Docs only, no behavior change:
against a future mistaken merge.
backup_integrity.pynote that said consolidation "is tracked for ADR-102 P6".lint_backup@verified cffa180b → b832d59d(docstring touched).Tests
lint_backup --selftest→ PASStest_backup_integrity.py+test_kg_backup_v2.py→ 22 passed🤖 Generated with Claude Code