[Draft] Concept reference-reconciliation worklist — split (1→N) + merge (N→1) - #704
Draft
mvkonchits-db wants to merge 5 commits into
Draft
[Draft] Concept reference-reconciliation worklist — split (1→N) + merge (N→1)#704mvkonchits-db wants to merge 5 commits into
mvkonchits-db wants to merge 5 commits into
Conversation
…models Pydantic shapes for the split(1->N)/merge(N->1) worklist per API contract section 5b: references (itemized retire-gate set), repoint, and merge. Co-authored-by: Isaac
list_references (itemized retire-gate set; count == reference_count), repoint_reference (remove+add via links manager so graph side-effects fire), merge_concepts (N->1 convenience composing repoint + deprecate_concept). Co-authored-by: Isaac
GET /semantic-models/concepts/references (READ_ONLY), POST .../references/repoint and POST .../concepts/merge (READ_WRITE + editable-scheme gate on the target collection). Registered above the catch-all concepts path route. Co-authored-by: Isaac
Covers API contract 5b Accept bullets: references itemizes asset/concept refs + successors with count == reference_count; repoint drops a ref so retire then succeeds; merge 2->1 deprecates both sources with isReplacedBy->target and repoints their refs; no ref silently dropped. Also fix repoint_reference to pass the UUID object (not str) to the links manager remove path so the GUID column binds under SQLite in-harness. Co-authored-by: Isaac
…orphaned ref) repoint_reference is remove-then-add across two ops with no single txn. For a feature whose whole promise is 'never silently drop a reference', wrap the add: on failure, re-add the original link (at from_iri) and re-raise, so a repoint either fully moves or fully rolls back. New test forces a mid-repoint add failure and asserts the reference is restored to the source. Co-authored-by: Isaac
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.
DRAFT — not for review yet. Stacked on the concept-versioning engine (#703); must merge AFTER it. Held from review-ready until the full stack passes E2E.
What this is (P1-6)
The human migration surface that turns "retirement is blocked, N things still point here" into "here is exactly what to move." Backend only. Built ON TOP of the P0-6 primitives (reference-count, deprecate-with-successors, retire gate) — no new schema, no migration. General over BOTH split (1→N) and merge (N→1), per the product call: the engine's
replaced_bywas already a list, so split works; merge is the same repoint, many sources → one target.Endpoints (API contract §5b)
GET /semantic-models/concepts/references?iri=→ itemized retire-gate set:{iri, label, count, asset_refs[], concept_refs[], successors[]}.countequals the P0-6reference-count(same set, asserted in a test). READ_ONLY.POST /semantic-models/concepts/references/repoint{link_id, from_iri, to_iri}→ moves ONE reference via the links manager (remove+add, so graph side-effects fire). Validates the link points at from_iri (404 otherwise); no-op if from==to. Rolls back (restores the original link) if the add fails — never orphans a reference. READ_WRITE + editable-scheme gate.POST /semantic-models/concepts/merge{source_iris[], target_iri, repoint_refs}→ N→1 convenience composing repoint +deprecate_concept(source, replaced_by=[target]). No new lineage predicates. READ_WRITE.Tests
src/tests/integration/test_concept_reconciliation.py— 7 tests, all green: references itemization + count-parity, repoint drops-ref-then-retire-succeeds, from_iri validation (404), no-op, merge 2→1 (both sources deprecated w/ isReplacedBy→target, refs repointed), and the repoint rollback safety case.Not included
m4_rdf_triple_version_uq); no migration.This pull request and its description were written by Isaac.