Draft: docs(qa-review): NF-9a/b documentation accuracy sweep + arc42 chapter 11 - #51
Draft
noVaSon wants to merge 7 commits into
Draft
Conversation
Curated conceptual inventory of known risks and accepted technical debt: trust posture, credential migration, ontology evolution, graph-store operations, and themed technical-debt clusters. Scope decisions are referenced to chapter 9 instead of duplicated.
ADR 9 claimed Tagus-era credentials are rejected at upload. Verified against the code: unrecognised VC 1.1 payloads route to the non-credential ingestion path and are silently downgraded to unverified generic RDF data with no signal to the uploader. Reword the migration impact accordingly, scope the Linked Data proof rejection to payloads that match a credential format, and fix the stale FormatDetector class name.
… claim
ADR 9 (09_architecture_decisions.adoc):
- ClaimValidator.getSubjectType() no longer exists; replaced with the
actual SPARQL subclass-walk method, ClaimValidator.resolveSubjectBaseClass().
- Regeneration output path and bundle-contents table pointed at
defaultschema/ontology/gx-2511.ttl, which does not exist; corrected to
the real production path, trustframeworks/gaia-x-2511/{ontology,shapes}.ttl.
Chapter 5 (05_building_block_view.adoc):
- The Asset Store paragraph (and the same claim repeated at lines 60-61,
88, 90, 147-148, 200) said RDF credentials are stored in the File Store.
Contradicted by AssetStoreImpl: storeCredentialInternal() never touches
fileStore, and getFileByHash/getFileById read straight from the DB
raw-content column. Only non-RDF assets and Schemas use the File Store.
Register: design-documents/02-insights/planning/2026-08-20-stale-docs-and-code-drift-register.md,
findings A3/A4.
…AT-FR-AU-01) Building-block table claimed the service "checks live connectivity per framework on list" — a leftover from an earlier connectivity-badge design that was never shipped. getTrustFrameworks() just maps the persisted family state; verified against TrustFrameworkAdminService.java. Replaced with the actual endpoint set: family-level enable toggle, per-bundle external client identifier overrides, and per-base-class enablement — all via PATCH + application/merge-patch+json.
… status Chapter 5's Validation Result Storage building block was stale against CAT-FR-CO-03's audit-trail work: no failureCategory field on the ValidationResult diagram, no mention that failed/unreachable compliance attempts are stored at all, and the rebuild paragraph wrongly claimed every row is re-projected to the graph. Fixed to match the code: added failureCategory to the diagram and bullet list, documented the EXCLUDED graph-sync status as a third, permanent terminal state, and corrected the rebuild description (EXCLUDED rows are skipped, not re-projected). Chapter 11's tamper-evidence-seal entries reworded from "blind spot" to "narrower blind spot" — the infrastructure-failure/non-conformance discriminator is now sealed; the free-text report stays unsealed. That entry referenced a mechanism chapter 5 didn't define, hence this pass covering both. Written ahead of the code landing on main: PR #156 (the base audit-trail work) and PR #163 (the failureCategory seal fix) are both open against upstream and unmerged as of this commit. Docs describe the target state of this fork; verify against #156/#163 before treating chapter 5/11 as authoritative for a build that doesn't yet include them.
Chapter 11 is written against the assumed post-merge state of open PRs, as the preceding chapter-11 commits already were. Two technical-debt bullets lose their referent once the dead-code and test-hygiene cleanup merges, and a third turns out to have been mis-sized from the start: - "A deprecated loading method is retained alongside its replacement and awaits removal" - removed. The method is deleted, and no other deprecated member remains anywhere in the main sources. - "An exploratory test slated for deletion" - removed. The class is deleted, and no other class carries an exploratory/throwaway marker. - "One layering slip / a one-file cleanup" - reworded to the plural. The file the bullet named is cleaned, but two other files inside the same verification domain layer independently declare wire-format media-type constants, so the theme survives while the "one file" sizing does not. Those two sites predate the cleanup; nothing multiplied, the count was simply too narrow. Deliberately NOT changed: the disabled-tests bullet keeps its "some commented out entirely, which does not even show up as skipped" clause. The cleanup converted the two classes in its scope, but three commented-out test methods survive elsewhere (one in a schema-store test whose siblings run, two in an auxiliary signing tool), so the clause is narrowed in practice, not false. The class-level disable that silences a whole group is still exactly one. The dated marker behind the missing positive-path coverage bullet was preserved on purpose, so that bullet stands unchanged. The peripheral-debt summary keeps the word "cleanup": retiring the two auxiliary signing tools is cleanup, so the word was never anchored to the deleted bullet alone.
|
Contributor
Author
|
Pushed This assumes two merges, in this order:
Same convention as the earlier chapter-11 commits on this branch, which were written against the assumed post-merge state of PRs #153–#159. This PR should merge after both. What changed — three edits, each verified against the actual post-change tree
On the third: the file the bullet named is cleaned by #169, but two other files inside the same verification domain layer independently declare wire-format media types ( What was deliberately left alone
No other line in the chapter is touched, and the counts still hold after the edits ("Three themes", "a handful", "Two of", "Three items"). The chapter's level of detail remains the open question for QA/PMO — nothing here pre-empts that. |
noVaSon
changed the title
noVaSon
marked this pull request as draft
August 26, 2026 22:44
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.
🚀 Summary
QA-driven documentation-accuracy sweep (NF-9a, NF-9b) plus a new arc42 chapter:
gx-2511.ttl/gx-2511-shapes.ttl→ontology.ttl/shapes.ttl; dead--outputpath corrected to the real bundle location).ClaimValidator.getSubjectType()→resolveSubjectBaseClass();TrustFrameworkAdminServicedescription updated to the current merge-patch based API).✅ What's Changed
🧪 How to Test
docker build -t xfsc-asciidoctor tools/asciidoctor/include::/xref errors):federated-cataloguesource:AssetStoreImpl/ValidationResultHasher(Metadata-Store-holds-RDF-content claim,failureCategory/EXCLUDEDgraph-sync status),CredentialFormatDetector(silent-downgrade migration behaviour),ClaimValidator.resolveSubjectBaseClass(),RoutingGraphStore/GraphStoreProbe(backend-switch fallback behaviour).git grep -n "ADR.12" federated-catalogue/src/docs/architecture/.🔍 Related Issues
Closes #
Related to #
📸 Screenshots (if applicable)
📋 Checklist