Publish curated ITWorx-ModelForge source from 990401737f96c8d46a9f7b0d84994516cadcb6a0

docs/architecture/adr/0056-selected-model-comparison-intents.md

@@ -0,0 +1,84 @@
+# ADR 0056: Durable selected-model comparison intents
+
+Status: accepted for the persisted operator/consumer protocol. Consumer execution integration and
+release qualification remain open.
+
+Migration note: the original canonical 0030 implementation below is retained as
+design history. [ADR 0057](0057-deployed-lineage-convergence.md) integrates these
+tables through additive 0033 while preserving the separately deployed lineage.
+
+## Context
+
+[ADR 0055](0055-selected-model-update-inbox.md) separates an upstream notice from model quality and
+replacement. [ADR 0054](0054-lab-preflight-before-persistent-execution.md) separates admission from durable execution.
+The selected-project hub needs one current-versus-candidate comparison with attributable evidence,
+without introducing a model tournament, another retrieval engine or another promotion engine.
+
+## Decision
+
+Schema `20260909_0030`, after canonical `20260909_0029`, adds `selected_model_comparisons`.
+An operator creates an intent for one stable project binding, one designated service client,
+one immutable project suite and two distinct exact capability deployments. The current leg must
+be a production `stable` ModelForge deployment; the candidate must be a nonproduction `candidate`
+with an active experiment route for the same `rag.embedding@1` contract. Distinct index references
+prevent silent reuse of the current vector collection. Different embedding spaces are allowed;
+this does not authorize reindex, cutover or replacement.
+
+Creation records immutable revision, artifact-set, runtime-profile, embedding-space, configuration,
+suite, corpus and index identities. Every reviewed case must name the requested corpus digest.
+The retrieval configuration digest must match the immutable suite settings. Claim and result
+publication revalidate the selected identities and route. A suite contains 1–100 reviewed cases.
+One active intent per project binding and a unique binding/idempotency key bound admission.
+Identical retries return the existing intent; changing its payload conflicts.
+
+The operator designates an existing active project-bound `rag.embedding@1` client. Consumer
+endpoints authenticate its service credential and require that exact client and binding on every
+operation. A claim token alone grants no authority. Operator credentials are not converted into
+service credentials. Assigned discovery is bounded and scoped to the designated client. Suite
+case definitions accompany its successful claim; this protocol adds no general consumer suite API.
+
+There is one claim, with a 120-second renewable lease and a fixed one-hour deadline from claim.
+No automatic reclaim or replay occurs. Progress counts are bounded and monotonic. Expired claims
+become `interrupted`; history, assignment reads and subsequent creation reconcile expiration.
+Admission retains its database locks until the decision commits. An explicit new intent is required
+for another attempt, and does not prove an earlier external process stopped.
+
+Pending cancellation becomes `cancelled`. Running cancellation becomes `cancel_requested` until
+the designated consumer acknowledges it. Results cannot publish after cancellation, expiry or
+loss of the claim. Expiry and interruption describe coordination state, not GPU reclamation.
+
+The consumer submits both legs together with ranked per-case results, its implementation digest
+and mappings from suite case IDs to public gateway `request_id` values. Successful cases require
+unique completed gateway requests for the designated client, exact leg deployment, capability and
+unchanged single-case query hash. Server-owned request timestamps must lie within this claim and
+deadline. Failed cases may omit a request, but cannot make the comparison eligible. Request evidence
+proves the matching embedding invocation; retrieval rankings remain explicitly attributed to the
+designated consumer rather than represented as independently observed hub retrieval.
+
+`EvaluationService(commit=False)` creates and completes the existing two evaluation runs and
+comparison inside the locked intent transaction. The server recomputes metrics and eligibility;
+caller aggregate scores are not accepted. Any publication failure rolls back the pair and links.
+An identical result retry returns the existing result, while a changed retry conflicts. The
+response derives a compact outcome from the linked comparison and fails closed on missing evidence.
+Eligibility is evaluation evidence, never production authorization or a promotion operation.
+
+## Recovery and boundaries
+
+Following [ADR 0041](0041-authoritative-versus-rebuildable-recovery-state.md), pins, operation history
+and linked results are authoritative. Claim hashes and expiry are transient. Restore clears these
+claims and transforms `pending`, `running` and `cancel_requested` intents to `interrupted` with
+`COMPARISON_RESTORE_INTERRUPTED`; it does not replay work. A deterministic fingerprint projection
+permits precisely that transformation while retaining the other provenance. An older schema can
+gain the new table only in its exact empty initial state. The readiness gate refuses residual
+restored claims or active intents. Populated comparison history blocks downgrade.
+
+The API does not launch a background consumer, run the ExampleRAG CLI, invoke a provider, claim GPU
+capacity or promote a model. The current ExampleRAG CLI dynamically selects its legacy CURRENT profile
+and does not yet implement this claim/result protocol. Its historical evaluation cannot satisfy a
+fresh intent. A consumer adapter must first validate the actual stable/candidate collection and
+profile identities, execute through the existing retrieval engine, and retain matching public
+gateway request IDs. Real inference, managed PostgreSQL concurrency, upgrade/restore and the frozen
+release artifact set remain qualification gates; this ADR does not assert those gates passed.
+
+The actionable protocol is documented in
+[Selected model comparisons](../../operations/SELECTED_MODEL_COMPARISONS.md).