Conversation
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 RDF export section documented entities, facts and documents but not the serialized rule, version, chunk and evidence families, the reference-resolution guarantees, or the single-snapshot and fail-closed semantics the route now provides — and nothing about the ledger surfaces newer migrations added. Document the whole emitted contract: open statements and their qualifier/time-mention nodes, typed-fact fromStatement provenance, validity grades, evidence origin/offsets, chunk producer metadata, document reading context, vocabulary updatedAt, and the explicit non-claims. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
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 documented RDF export contract describes entities, facts and documents — but not the serialized rule, version, chunk and evidence families, the reference-resolution guarantees, or the single-snapshot and fail-closed semantics the route now provides. It also says nothing about the ledger surfaces newer migrations added.
WHY THIS IS A GENERIC UTOPIA BUG OR CONTRACT GAP
The public contract documentation lagged the implementation: consumers cannot rely on guarantees that were never written down, and the documented subset understates what an export actually contains.
FIX
Document the whole emitted contract in
web/src/docs/mcp.md: open statements and their qualifier/time-mention nodes, typed-factfromStatementprovenance, validity grades, evidence origin/offsets, chunk producer metadata, document reading context, vocabularyupdatedAt, the single-snapshot read and fail-closed semantics, and the explicit non-claims.REGRESSION EVIDENCE
Documentation only; the documented behavior is covered by the tests in the underlying PRs.
COMPATIBILITY RISK
None — docs only. The doc declares the export a compatibility boundary: new predicates are additive, while omission or renaming becomes contract-sensitive.
Stacked on #832 → #833 → #834 — this PR's diff includes those commits until they merge.