Publish and serve versioned ANN snapshot artifacts¶

Status: Default-off lifecycle implemented with a control-database artifact; production resource and cross-platform qualification remain open.

Problem Statement¶

Existing Recommendation Snapshot publication atomically exposes precomputed sets, but it does not own a native vector index, vector transform or index-to-Product-ID mapping. Adding online retrieval without a lifecycle contract risks partial publication, stale mappings, unsafe loads and unbounded resident memory.

Solution¶

Treat the retrieval artifacts as a versioned, scoped part of a complete published snapshot generation. Build and verify them off the serving path, publish atomically with their Recommendation Snapshot, and serve through bounded lifecycle ownership.

User Stories¶

As a operator, I want ANN artifacts built during a Training Run, so that serving never builds indexes synchronously.
As a consumer, I want index, vectors, transforms and Product ID mappings bound to one snapshot, so that results cannot mix generations.
As a Commerce Property, I want artifact identities scoped by the complete Commerce Scope, so that identical Product IDs in other Catalogs remain isolated.
As a operator, I want failed build or validation to leave the prior serving head unchanged, so that a working snapshot remains available.
As a operator, I want all required artifacts validated before publication, so that a successful snapshot is complete.
As a consumer, I want one coherent snapshot generation pinned for a request, so that concurrent publication cannot mix candidate and feature versions.
As a Shopper, I want profile query updates independent of index mutation, so that acknowledged interactions can affect retrieval safely.
As a operator, I want bounded resident scopes, generations and concurrent loads, so that memory use remains governable.
As a operator, I want explicit ownership of native threads and resources, so that request concurrency cannot silently oversubscribe the host.
As a operator, I want safe artifact reload after restart, so that availability does not depend on process-local training state.
As a security maintainer, I want trusted-origin and integrity validation before native deserialization, so that untrusted or corrupt bytes cannot be accepted as a valid index.
As a operator, I want incompatible artifacts rejected with classified diagnostics, so that library upgrades cannot silently corrupt retrieval.
As a operator, I want retention to respect in-flight readers and publication, so that cleanup cannot remove a generation still in use.
As a security maintainer, I want no raw interaction rows or sensitive identities in index diagnostics, so that new artifacts preserve privacy invariants.
As a tester, I want failure injection at artifact and publication stages, so that rollback and atomicity can be verified through observable serving behavior.

Implementation Decisions¶

Confirmed: Item vectors and indexes refresh only with successful Training Run publication. No incremental serving-side index mutation; authorized Shopper query changes do not modify the index.
Bind representation version, vector dimension and metric, library/index format, Product ID mapping, Commerce Scope and snapshot identity in a verifiable artifact contract. Migration 20260925_0007 adds one optional SHA3-512-checksummed recommendation_ann_artifact row keyed by Snapshot ID. The Snapshot row supplies the complete Commerce Scope and available-state check.
Preserve complete atomic publication. A native index serialization function is not a publication transaction. Artifact availability and verification must be included in the publication success condition.
API serving schedules at most one cold artifact load per process off the request path and serves the ordinary Snapshot fallback while it warms. The cache holds at most two loaded generations. An artifact above 1 GB of vector/index bytes is rejected; full process RSS and multi-scope residency remain qualification gates.
Validate origin, integrity, size and version compatibility before native loading. Do not promise checksums alone make hostile serialized artifacts safe. Persisted artifacts must be generated and controlled by the service.
Keep the last successful serving head on training/publication failure. A serving-time missing, corrupt or warming artifact uses the old candidates from the same snapshot; it never mixes candidate generations.
Define portable rebuild or format compatibility policy across Apple Silicon and actual Linux deployment architectures. Byte portability is not assumed from package compatibility.
Integrate new artifact retention with existing snapshot retention. A request holds its loaded native index by reference while searching even if the bounded cache evicts it; the database deletes the artifact with its retained Snapshot. No raw source interaction staging is introduced.
Preserve reusable serving_limits independence and the existing telemetry adapter boundary. Diagnostics must be bounded and omit bearer material and Shopper, Order and Browsing Session identifiers.

Testing Decisions¶

Use the existing end-to-end Training Run and snapshot-store lifecycle contracts as the primary seam. Assert serving-head identity and observable API results before and after publication and injected failures.
Exercise failed build, missing mapping, mismatched scope/generation, incompatible dimensions/metric, corrupt bytes, native-load failure and restart. Assert no partial head replacement and no source access from serving.
Exercise concurrent readers/publication and cleanup, bounded concurrent loads, multiple scopes and worker processes, and peak resident memory while two generations overlap.
Retain SQLite/non-PostgreSQL integration checks; add disposable PostgreSQL atomic-publication tests if the chosen persistence implementation requires them. Run migration checks only when a migration is introduced.
Verify serialization round trips and cross-platform behavior for the exact selected library/version/index. A docs-only compatibility claim is not a passing artifact test.

Out of Scope¶

Custom ANN algorithms, a separate vector-search service, cross-Commerce-Scope discovery, incremental live index mutation, merchant-source reads during serving, deployment and hosted-setting changes. The later user request adds versioned two-tower query weights to the same atomic artifact contract.

Further Notes¶

Physical storage and publication mechanics are implemented for the default-off candidate. Relevance, recall, Linux production packaging and full resource evidence still gate broad enablement.

The Embedded ANN decision map retains qualification gates. The ready-for-agent label does not waive those gates or assert broad deployment approval.