validate sidecar generation promotion

[TheGreenCedar]

Context

Generation fingerprinting and manifest-rooted retention were already transactional, but reuse and rebuild paths did not share one mandatory pre-promotion gate proving that every retrieval component belonged to the same usable candidate.

Closes #1023
Refs #914

What Changed

• Added one shared candidate-generation validation gate before the short SQLite input/pointer transaction.
• Bound SQLite lexical input, SCIP revision/graph artifacts, exact Qdrant collection count (including zero) plus semantic smoke, configured embedding profile/model/runtime contract, native launch identity, stable persisted/running Docker identity, and fresh device-policy evidence to the candidate.
• Re-ran a fresh bounded embedding request after semantic smoke; accelerator-required candidates need timed proof bound to the exact requested provider/device and unchanged live native or Docker identity, while external endpoints cannot borrow local logs and explicit CPU policy remains supported.
• Bumped the sidecar input fingerprint contract to v6 to include model/profile/pooling/normalization and launch configuration without binding per-run endpoint ports.
• Scoped observed native launch state to owner/namespace/profile/run/port and exact-matched canonical launch mode, endpoint, executable/arguments fingerprint, model, and device.
• Added a production-gate component failure matrix plus pre-promotion crash proof that compares the actual current manifest and real verified rollback marker.
• Documented the invariant and failure behavior in the architecture guide and changelog.

How To Review

1. Start at persist_finalized_manifest and confirm all reuse/rebuild paths reach validate_candidate_generation before promote_retrieval_manifest.
2. Confirm external probes remain outside the short SQLite write transaction while the outer generation/GC locks fence CodeStory publication and cleanup.
3. Review the v6 fingerprint fields, the fresh timed accelerator smoke, native PID/launch identity, and Docker identity checks before and after the final probes.
4. Inspect the table-driven failures and crash case for unchanged current and rollback state.

Verification

• Focused exact-Qdrant-count, persisted Docker identity, fresh timed accelerator smoke, external proof-boundary, native PID identity, and promotion failure/crash regressions passed
• cargo test -p codestory-retrieval --locked: 339 passed, 2 ignored; integration suites 2/2 bootstrap, 2/2 degraded, 4/4 holdout
• cargo clippy -p codestory-retrieval --all-targets --all-features --locked -- -D warnings
• cargo fmt --all --check, documentation links, and git diff --check
• Independent review: pending after the final stack repair onto qualify managed lifecycle on every platform #1031 head 3056c1d2 and the accelerator-proof blocker fixes

Risk

The fingerprint contract bump intentionally rebuilds existing sidecar generations. Native promotion now fails closed when persisted launch identity is stale, replaced, dead, or foreign, and accelerator promotion requires a fresh timed embedding request bound to the exact requested provider/device. Docker promotion also fails if the persisted/running container identity is missing or changes across final probes, and Qdrant supersets are rejected. Explicit CPU policy remains accepted; accelerator inventory/manual assertions alone do not qualify.