Validate embedding compatibility before restore mutation

Context

The premise review of PR #15643 established that normal restore preserves stored vectors; it does not need an embedding-provider write canary. That correction exposes the actual restore precondition: the bundle's vectors must be complete and compatible with the destination collection before any destructive mutation.

Source inspection on dev shows that bundle-meta.json currently records bundle version, subsystem receipts, integrity, topology, and Neo version (ai/scripts/maintenance/backup.mjs:243-251) but no embedding contract. Both vector importers could truncate in replace mode before every row had been parsed and validated.

Truth-fold (post-review, two cycles): the original "hard model/strategy fingerprint incompatibility" premise is retired. No persisted write-time record of which provider/model embedded the stored rows exists in the substrate, so a backup-time config snapshot can never be presented as producer provenance, and a config-vs-config comparison must never hard-refuse a restore. Hard gates bind only to evidence the bundle itself proves; semantic-space provenance is classified as structured advisory residue for the orchestrator.

The Problem

A syntactically valid bundle can still contain a missing, non-finite, or wrong-dimension vector. Before this work, the restore driver could not compare the bundle's row-verifiable facts with the destination before mutation, and a late-row parse/vector failure could arrive after a replace-mode truncate. Provider readiness is not a substitute: a healthy provider neither proves that preserved vectors are compatible nor authorizes re-embedding.

The Architectural Reality

• Backup metadata is owned by ai/scripts/maintenance/backup.mjs.
• Bundle admission is owned by ai/scripts/maintenance/restore.mjs plus the importing DatabaseService boundaries.
• Row-verifiable facts (parseability, required IDs, vector presence/finiteness/dimension, exported counts) are the only hard-gate evidence a bundle carries.
• Semantic provenance (which provider/model produced the stored vectors) is unknown by construction until write-time provenance exists; restore admission classifies it, never asserts it.
• ADR 0025 keeps probes as evidence, never authority. ADR 0027 keeps re-embedding as an orchestrator-selected data-recovery action; restore admission must not trigger it implicitly.

The Fix

1. Extend bundle-meta.json with a versioned embedding block: schema version, vector dimension, per-actual-vector-collection exported counts (KB chunks, Memory Core memories, summaries — never null, never aggregate), and an explicitly advisory expectedConsumer (the backup host's active provider/model at backup time — expectation context, not producer evidence).
2. A provider-free restore preflight streaming-validates every JSONL row (parseability, required ID, vector presence, finite values, expected dimension) and every declared count against the streamed totals, in both directions.
3. Complete that preflight — and a full-source proof on every direct DatabaseService replace path — before any truncate or live collection write. Replace is all-or-nothing.
4. Classify semantic provenance as structured advisories (semantic-provenance-unverified always; consumer-expectation-mismatch additive on divergence) attached to the validation receipt and carried through the self-diagnostic probe. Never a hard refusal from config comparison, never a provider call.
5. Keep re-embedding outside restore admission. If recovery needs new vectors, diagnostics/classification must select the ADR-0027 re-embed action.

Contract Ledger Matrix

Decision Record impact

Aligned-with ADR 0025 and ADR 0027. This adds evidence and admission checks; it does not grant probes action authority or move re-embedding out of orchestrator control.

Acceptance Criteria

• New bundles declare the versioned embedding block: dimension, per-collection non-null counts, advisory expectedConsumer, schema version
• Restore validates every JSONL row, required IDs, and declared-vs-streamed counts before any replace-mode truncate or write
• Missing, malformed, non-finite, or wrong-dimension vectors fail with a collection/file/line-specific receipt
• Provider-unreachable + compatible preserved-vector bundle passes admission without any embedding request
• Semantic provenance classifies as semantic-provenance-unverified in all cases (match included); mismatch adds consumer-expectation-mismatch; advisories ride the validation receipt and the self-diagnostic probe result
• Direct KB and MC replace imports prove the full source before any truncate (corrupt-final-row zero-truncate/zero-write witnesses)
• Legacy-bundle behavior is explicit and structured; it never triggers implicit re-embedding
• Unit/integration specs include corruption on the final row so first-row sampling cannot satisfy the gate

Out of Scope

• Performing or scheduling re-embedding
• Choosing an autonomous recovery action
• Off-host bundle transport
• Write-time producer-provenance persistence (a separate future substrate; until it exists, provenance stays classified-unknown)

Avoided Traps

• Provider canary as compatibility proof — it proves neither vector completeness nor embedding-space identity.
• Validate while mutating — a late error after truncate is already data loss.
• Config snapshot as producer provenance — current config names the expected consumer, never which model embedded the stored rows.

Related

• #15639
• #15689
• PR #15690
• #11150 (closed production-scale restore hardening; did not add this contract)
• #15692 (bounded streaming importer), #15693 (orchestrator recovery receipt — the advisory consumer) Live latest-open sweep: checked the latest 20 open issues at 2026-07-22T09:43:14Z; no equivalent found. A2A in-flight claim sweep: checked the latest 30 messages across all read states immediately before creation; no overlapping lane claim found.

Origin Session ID: cb60301d-74a4-4024-b80d-2f7efdbf9cd1

Retrieval Hint: "restore bundle embedding compatibility metadata preflight before truncate preserved vectors"