Skip to content

feat(storage): add complete embedding-space identity - #2017

Draft
ohdearquant wants to merge 1 commit into
codex/adr-160-phase-5-ranked-prefixfrom
codex/adr-160-phase-6-embedding-space-identity
Draft

feat(storage): add complete embedding-space identity#2017
ohdearquant wants to merge 1 commit into
codex/adr-160-phase-5-ranked-prefixfrom
codex/adr-160-phase-6-embedding-space-identity

Conversation

@ohdearquant

@ohdearquant ohdearquant commented Aug 17, 2026

Copy link
Copy Markdown
Owner

Stack and governance gate

What changed

  • Add a shared, closed EmbeddingSpaceIdentity / EmbeddingSpaceKey contract in khive-storage, derived from a complete protocol fingerprint plus dimensions rather than a display/model name.
  • Validate borrowed identity inputs and preflight the 128-byte derived-key envelope before allocation; keep the key field private and provide no unchecked constructor or deserializer.
  • Replace runtime's pack-local NamedVectorIdentity seam with vectors_for_embedding_space, binding the complete key to immutable SQLite vector-table geometry and rejecting conflicting first registration.
  • Migrate moodboard's descriptor path to the shared identity while preserving its existing canonical JSON, SHA-256 fingerprint, public response shape, and table key.
  • Capture the identity once alongside the loaded vision model and carry it through inference to storage, avoiding per-request descriptor reconstruction and hashing.
  • Add a cross-language Python descriptor golden to the repository smoke gate, plus exact Rust response/table and field-mutation goldens.
  • Document the intentional source break and the table-bound/default-namespace behavior accurately.

Resource and failure-safety properties

  • Protocol/model/key-prefix inputs are bounded; model revision input is capped at 4096 bytes.
  • Oversized prefixes fail from borrowed input before a second large allocation or derived-key formatting.
  • Dimensions are restricted to 1..=8192; derived table keys are restricted to 128 bytes.
  • Existing-table model/geometry conflicts fail closed; concurrent first registration has one immutable winner.
  • Production moodboard requests reuse the identity cached at model load.

Regression guards

  • Storage tests pin grammar/bounds, key derivation, exact ceiling behavior, a 1 MiB borrowed-prefix refusal, and the private-key compile-fail boundary.
  • Runtime tests pin model/geometry conflict refusal, planted-table mismatch, concurrent first-bind behavior, fingerprint isolation, namespace-scoped rows over a shared table, and persistent restart retrieval.
  • Moodboard tests pin canonical bytes/fingerprint/key, the complete 12-field response, exact physical table selection, and a mutation matrix covering every vector-affecting descriptor field.
  • The independent Python standard-library golden reconstructs the canonical descriptor and asserts byte-, SHA-, and key-level parity.

Validation

  • RUSTC_WRAPPER= cargo check --workspace -j4
  • RUSTC_WRAPPER= cargo clippy --workspace --all-targets -j4 -- -D warnings
  • RUSTC_WRAPPER= cargo test --workspace -j4
  • python3 tests/test_moodboard_descriptor_golden.py
  • cargo fmt --all -- --check
  • deno fmt --check on all eight modified Markdown files
  • bash -n scripts/ci.sh
  • git diff --check

Independent identity-contract, callsite/docs, registry-boundary, and resource reviews found no implementation Blocker/High/Medium issue.

Explicitly deferred to Phase 7

This PR does not migrate the text-provider registry, ANN/cache identities, or embedding-model schema. Accepted ADR-160 now fixes the configured lineage-slot and legacy-row mapping; Phase 7 implements that cutover and must also source a complete attested resolved-artifact identity covering provider/version, query/document transforms, pooling/execution semantics, and checkpoint digests. Those concerns remain outside this Phase 6 boundary.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant