From 0fcc97af1c60266d26a34a1008756cfd92bc03e0 Mon Sep 17 00:00:00 2001 From: Aaron Bockelie Date: Mon, 1 Jun 2026 17:57:28 -0500 Subject: [PATCH] docs(adr-102): document the intentional two-validator layering (P6c) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 cffa180b -> b832d59d. --- api/app/lib/backup_integrity.py | 18 +++++++++++++++--- scripts/development/lint/lint_backup.py | 13 ++++++++++++- 2 files changed, 27 insertions(+), 4 deletions(-) diff --git a/api/app/lib/backup_integrity.py b/api/app/lib/backup_integrity.py index 00068d4ba..131f87c77 100644 --- a/api/app/lib/backup_integrity.py +++ b/api/app/lib/backup_integrity.py @@ -9,9 +9,21 @@ - External dependencies (concept references not contained in this backup — partial backups) - Statistics (record counts surfaced for logging) -This is the *runtime* checker. The exhaustive *offline* oracle is -``scripts/development/lint/lint_backup.py`` (used in tests/linting). Consolidating -the two v2 validators is tracked for ADR-102 P6. +This is the *runtime* checker, deliberately distinct from the offline oracle +``scripts/development/lint/lint_backup.py``. They validate DIFFERENT layers and are +intentionally NOT merged (evaluated and decided in ADR-102 P6 — do not "consolidate" +them): + - THIS module checks the DE-INTERNED logical graph via :class:`KgBackupV2Reader` + (referential integrity, external deps, statistics) — the cheap runtime gate run + before a backup is streamed / archived / restored. + - ``lint_backup`` checks the RAW interned on-disk structure (dictionary index + ranges, interning integrity, §6 derived-product exclusions, format negotiation) + and carries NO api-package dependency by design (ADR-102 Track D), so the + pytest oracle can load it standalone by file path. + +A shared core would force one layer's representation onto the other and couple the +standalone oracle to the api package; the narrow overlap (reference / external-dep +checks) does not justify the cost. """ from typing import Dict, List, Optional, Any, Set diff --git a/scripts/development/lint/lint_backup.py b/scripts/development/lint/lint_backup.py index e43ec1f22..042518ade 100644 --- a/scripts/development/lint/lint_backup.py +++ b/scripts/development/lint/lint_backup.py @@ -16,6 +16,17 @@ wrapper that reads a path, calls the core, prints issues, and exits non-zero if any ERROR was found (CI convention, matching the sibling lint tools). +Relationship to the runtime checker (ADR-102 P6 — intentionally NOT merged): +this is the *independent* verification tool — a deliberately standalone oracle +with NO api-package dependency, which is what makes it a convenient CI / test / +build gate and an outside check on the serializer. It validates the RAW interned +on-disk structure (dictionary index resolution, interning integrity, §6 exclusions, +format negotiation). Its runtime counterpart, ``api/app/lib/backup_integrity.py``, +validates the DE-INTERNED logical graph via :class:`KgBackupV2Reader` as the cheap +gate before stream/archive/restore. The two check different layers for different +consumers; consolidating them would couple this oracle to the api package and +strip its interning-layer coverage, so they are kept separate by design. + Checks implemented (see ``CHECK_CODES`` for the stable code registry): - HEADER presence / well-formedness and format_version family negotiation (§7) - kg-backup/2 required header fields (§3.1) @@ -34,7 +45,7 @@ python3 scripts/development/lint/lint_backup.py python3 scripts/development/lint/lint_backup.py --selftest -@verified cffa180b +@verified b832d59d """ import argparse