Conversation
added 4 commits
September 20, 2026 21:46
Install a schema-level invariant: every reference an export can resolve must join rows that live in the same knowledge base. A column foreign key proves the target exists, not that it is the same KB's — the exporter would otherwise mint local IRIs naming foreign rows, or silently drop vocabulary references that resolve to nothing. Three layers: a precondition scan that refuses the migration on a dirty ledger, row triggers on every edge (deferred constraint triggers on same-table self-references so COPY and multi-row inserts are judged at commit), and kb-ownership immutability on every owned table.
The export read model moves from "open a pool connection per page" to a caller-provided transaction: a route can now pin one REPEATABLE READ snapshot across the preflight check, the vocabulary reads, and every page. A mid-stream commit can no longer leak half a rule or a dangling wasGeneratedBy into a finished file. Integrity is checked on the rows that survive, not on a second look. Every page query selects the referenced row's kb atomically with the row itself; a foreign, dangling, or merged-out reference refuses the whole export rather than minting a local IRI that names another KB's row or silently dropping a vocabulary link. The scan covers the provenance chain, derivation premises, edge qualifiers, vocabulary references, and the open-statement / time-mention / binding edges the schema has grown since — the same families migration 0070 guards on the write side. Read-model additions carried by the same pages: statement qualifiers, time mentions, typed-fact sources, fact layer/phrase/validity grade, evidence quote offsets, chunk origin metadata, entity descriptions, document reader/time-context fields, and vocabulary updated_at.
Rules, attribute rules, document versions, chunks and evidence were read from the same snapshot but never serialized; their facts' prov:wasGeneratedBy, prov:wasDerivedFrom and locator references dangled in the file. Serialize them in snapshot order so every emitted reference resolves. New upstream ledger surfaces serialize too: class/relation updatedAt, entity descriptions, document reader/time-context, chunk origin metadata, evidence quote offsets, open-statement layer/phrase/ qualifiers/time mentions, typed-fact fromStatement provenance, validFromGrade, and evidenceOrigin.
The serializer's unit tests assert individual triples; nothing checks the output as a set. Add an in-repo oracle that independently derives the expected quad set from a synthetic fixture — without calling any emit_* function — and requires exact equality in both formats, all in the default graph, with no duplicates. A declared predicate matrix lists every predicate each node kind may emit, including conditional cells; a coverage test asserts every declared cell is exercised by the fixture in both its present and absent states, and a mutation test asserts unaccounted terms fail. New ledger surfaces added by later migrations must register their predicates in the matrix, keeping the accounting complete as the contract grows.
Author
|
Closing pending author's final review of the PR set — will reopen once the series is finalized. |
ansonnmm
changed the title
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.
PROBLEM
The export serializer's unit tests assert individual triples. Nothing verifies the output as a complete set — a silently dropped family, a duplicated quad, or a triple landing in a named graph would pass every existing test.
WHY THIS IS A GENERIC UTOPIA BUG OR CONTRACT GAP
Per-triple assertions cannot catch absence or duplication. A serializer contract that claims "the whole ledger" needs set-level accounting, not sampling.
FIX
Test-only change (
#[cfg(test)]). An in-repo oracle independently derives the expected quad set from a synthetic fixture — without calling anyemit_*function, including its own literal/leaf construction — and requires exact equality in both Turtle and JSON-LD, all in the default graph, withemitted == distinct. A declared predicate matrix registers every conditional cell per node kind (including cells only reachable through synthetic rows), a coverage test requires every declared cell exercised in both its present and absent branches, and a mutation test requires unaccounted / moved / dropped / named-graph terms to break the accounting. New ledger surfaces must register their predicates in the matrix, so the accounting stays complete as the contract grows.REGRESSION EVIDENCE
This change is the regression capability:
the_whole_export_is_accounted_for,the_accounting_rejects_unaccounted_terms, andthe_fixture_exercises_every_declared_conditional_cellall pass — 35/35rdf::tests on the branch.COMPATIBILITY RISK
None at runtime —
cfg(test)only. The cost is maintenance: ~2.4k lines of test code that must be updated when the serializer contract grows; the declared matrix makes that required update explicit rather than silent.Stacked on #832 → #833 → #834 — this PR's diff includes those commits until they merge.