YantrikDB

First-class record-to-record links — the deepest ask from the yantrikdb-agi gap analysis (Phase 1 XC1 / Phase 2 Proposal 2). Records can now express supersedes / advances / contradicts / supports / questions / derived_from relationships to each other, atomically with the write, and those links are visible to recall.

Implemented across #53 (substrate) + #55 (recall + Python bindings); design record in docs/record_link_model_rfc.md (#52).

Additive — no behavior change

Existing paths (record(), recall(), correct()) are byte-identical. The link surface is entirely new opt-in methods, so there is no behavior change and no feature flag — a deployment carries the link model dormant until something calls a *_with_links method.

New API (engine + Python)

• record_with_links(text, links=[{"target_rid": "...", "link_type": "supersedes"}], ...) — record a memory and attach links
• link(source_rid, target_rid, link_type) / unlink(...)
• linked_records(rid, direction="both", link_type=None) — traversal; contradicts is bidirectional
• recall_with_links(query, top_k, expand_links=N, ...) — link-aware recall: supersedes-demotion (a stale, superseded record is demoted) + budget-capped neighbor surfacing, via a relation-aware polarity map
• reify_supersedes_links() — one-shot conversion of the legacy metadata.supersedes = "<rid>" convention into real Supersedes links (upgrade step)

Link types: advances / supersedes / contradicts / supports / questions / derived_from / custom:<name>.

The headline correctness win

Before: A supersedes B, you query something close to B → the engine returned stale B and never surfaced A. Now: recall_with_links(query_near_B, expand_links=1) demotes B and surfaces A above it. contradicts surfaces the contradictor without an endorsing relevance halo; supports pulls in a linked supporter even when it's semantically far from the query.

Schema

Migration v30 → v31: adds the record_links table + two covering indexes. Additive, forward-only, no data transform. Runs automatically on first open.

Replication & lifecycle

• link / unlink op kinds; idempotent apply on followers (UNIQUE + INSERT OR IGNORE); leader HLC carried.
• forget() marks links broken_source_forgotten / broken_target_forgotten (audit-trail), never deletes.
• v0.7.20 correct() synergy: in-place correction preserves the rid, so a record's links survive a correction for free.

Design provenance

This release went through adversarial redteam (gpt-5.5, deepseek-chat) + three code-grounding investigations before implementation. The redteam reshaped the design materially — notably proving that recall integration is a correctness requirement (not a ranking nicety) and surfacing relation-aware scoring. The full A/B/C alternatives analysis, decisions, and changelog are in the design-record RFC.

Deferred to follow-ups

• relate() phantom-entity prerequisite (#56) — rid endpoints currently mint phantom unknown entities; independent hygiene, no correctness impact.
• Windowed orphan/leak audit helper — the trader postmortem proved the existing oplog-presence "orphan" metric is a compaction artifact, not a leak; the replacement windowed check is a small follow-up.

Upgrade notes

• Additive; safe to adopt. Schema v31 migration is automatic + forward-only.
• Existing correct() / recall() / record() callers need no changes.
• To change a record's embedding, continue using forget() + record() — correct() and the link model are text/metadata/relationship-level.
• Server-mediated deployments (yantrikdb-server) pick this up on their next engine pin bump; the MCP tool surface for the link methods lands with that bump.

Stats

1530/1530 lib tests pass. cargo fmt --check --all + cargo clippy --all-targets clean. Python bindings verified locally against a real interpreter.

🤖 Generated with Claude Code