MVP retained qualification resolution binding for deterministic repeat

[mark-e-deyoung]

Purpose

Implement the smallest retained-known-path mechanism required by Foundry #18's determinization ratchet and the frozen GO/NARROW/KILL gate.

We now have:

• canonical first-consumer request identity (issue MVP request/result contract for first ui-grounding consumer #35 / PR Add first-consumer model request and result contract #36);
• qualification subject/record identity (issue MVP qualification receipt: bind exact candidate, target, workload, and validation evidence #31 / PR Add deterministic qualification receipt binding #32);
• a decision gate that requires an equivalent repeat to resolve without research (issue Freeze first-consumer GO / NARROW / KILL evidence and authority gate #33 / PR Freeze first-consumer GO NARROW KILL gate #34).

What is still missing is the deterministic retained association:

for this exact request and concrete target environment, this previously qualified subject is the known resolution.

Do not solve this with a database, catalog service, model recommender, or generalized planner.

Core design

After a successful qualification, retain a small resolution binding.

Stable resolution input:

• canonical request_digest;
• opaque target_profile_id;
• exact semantic environment_digest.

Compute:

resolution_key = sha256(canonical {
  request_digest,
  target_profile_id,
  environment_digest
})

The binding points that stable known context to:

• qualified subject_key;
• qualification record_digest;
• exact selected artifact observation digest/revision;
• representation/variant/quantization;
• runtime ID;
• evidence/ref metadata as needed.

Wall clock, storage path, and evidence location must not affect resolution_key.

Retention authority

A binding may be created only from a qualified receipt whose:

• subject request digest matches the request;
• target profile/environment match the resolution context;
• selected artifact/runtime/representation facts are copied from the qualified subject rather than supplied independently.

A rejected receipt cannot create a known-qualified resolution.

Deterministic lookup

Given the same canonical request + target profile + environment digest:

• exact binding present and valid -> return a qualified model-plan result referencing the retained subject/record;
• binding absent -> unknown with explicit no_retained_qualified_resolution reason;
• malformed/tampered binding -> fail closed; do not silently fall through to unknown as if evidence never existed.

This is a retained fast path, not candidate generation.

Changed envelope behavior

Changing any one of:

• request digest (including any material envelope constraint);
• target profile ID;
• environment digest;

must change resolution_key.

Therefore the old binding cannot be reused for the changed-envelope experiment. A separate existing binding for the changed key may produce a known qualified alternative; otherwise deterministic disposition is unknown.

Storage posture

For MVP, use ordinary files/directories:

<resolution-store>/<resolution_key>.json

No daemon, database, lock service, web API, global catalog, or cloud storage.

Use atomic file replacement for retention. Re-retaining the exact same binding is idempotent. Refuse conflicting content for an existing key unless an explicit future lifecycle/versioning policy is introduced.

The public repo contains only schemas/tools/fixtures. Real first-consumer bindings may remain private/local; public Foundry does not need to publish private target evidence.

Tests

Prove offline:

• equivalent request/environment -> identical resolution key;
• evidence ordering/time/ref changes do not affect key;
• changed request -> different key;
• changed environment -> different key;
• changed target profile -> different key;
• qualified receipt can create a binding;
• rejected receipt cannot;
• exact retained binding -> qualified result;
• missing binding -> explicit unknown;
• tampered/conflicting binding -> fail closed;
• repeated identical retain is byte/idempotent;
• no provider/network/model access.

Stack placement

Stack after reconciled qualification receipt PR #32 and before decision-gate PR #34.

After verification, ancestry-reconcile PR #34 onto this binding branch so the actual public critical path becomes:

PR #30 materialization -> PR #36 request/result -> PR #32 qualification receipt -> retained resolution binding -> PR #34 decision gate

Non-goals

• no ranking among multiple new candidates;
• no Generator–Validator implementation;
• no provider/model discovery;
• no global/shared database;
• no automatic invalidation/expiry/requalification policy yet;
• no fleet target inventory;
• no private evidence publication;
• no merge/release/deploy authorization.

R4

• reproducible: canonical key/binding schemas;
• repeatable: same request/environment resolves the same retained binding;
• reversible: file-backed layer can be removed without changing model/runtime/provider state;
• idempotent: identical retain produces identical bytes and does not create duplicate state.

Exit

Leave a verified public draft PR. Real proof remains downstream of first real qualification: retain one actual binding, rerun the equivalent request/environment and show a deterministic hit with no provider research or candidate generation, then change exactly one envelope/target fact and demonstrate a different key/known-alternative-or-unknown disposition.

Related: #18, #31, #33, #35; draft PRs #36/#32/#34; SemperSupra/desktop-ui-cv#40.

[mark-e-deyoung]

Windows-portable storage refinement

The canonical resolution_key remains sha256:<64-hex>, but the on-disk MVP filename must be:

<64-hex>.json

not the literal sha256:<64-hex>.json, because : is invalid in Windows filenames.

The full prefixed key remains inside the binding and is what participates in evidence/result identity. Filename encoding is storage mechanics only and must not change semantic identity.

[mark-e-deyoung]

Red-team correction: retained lookup must bind concrete runtime identity

Cross-contract review found a first-consumer falsifiability gap in draft PR #38 at verified head aa27b0686e39596089d525c7b4609edc05fd7c08.

The qualification subject correctly binds:

• runtime.id;
• runtime.toolchain_digest;
• runtime.config_digest.

But the retained resolution key currently binds only:

request_digest + target_profile_id + environment_digest.

That is insufficient because the request binds only an allowed runtime family ID, while desktop-ui-cv#40 deliberately keeps Python/Torch/Transformers and loader configuration out of the semantic target environment_digest. A materially changed runtime toolchain/config can therefore leave the resolution key unchanged and produce a deterministic HIT for a qualification subject that was never actually qualified under the new runtime.

This is distinct from deferred expiry/requalification policy. It is immediate subject-equivalence correctness for the MVP repeat experiment.

Bounded correction

Update PR #38 v1 before merge so the resolution context/key also binds the concrete current runtime identity:

runtime.id
+ runtime.toolchain_digest
+ runtime.config_digest

Retention must require that runtime identity to match the qualified receipt subject. Lookup must receive the current concrete runtime identity and use it in the key. Changing either runtime digest must yield a different key / deterministic UNKNOWN unless that exact runtime context already has its own retained qualified binding.

No catalog, discovery, expiry policy, runtime inventory service, or automatic requalification is authorized by this correction.

[mark-e-deyoung]

2026-09-04 dependency correction from provider-identity red-team

Issue #31 now records a pre-first-receipt equivalence defect: the current qualification subject binds artifact.observation_digest, while the normalized HF observation includes event-local observed_at and evidence refs. Recapturing the same immutable artifact can therefore change the qualification subject_key without a material artifact/runtime/request/target change.

This issue's resolution_key design is still sound because it intentionally excludes wall clock/evidence location. However, the retained binding points to a qualification subject_key; if that upstream subject identity is unstable across equivalent observations, the advertised equivalent-repeat proof can become spuriously different even though the resolution context did not change.

Disposition:

• do not redesign the resolution key;
• do not add lifecycle/database machinery;
• treat MVP qualification receipt: bind exact candidate, target, workload, and validation evidence #31's stable-artifact-identity correction as an upstream prerequisite to the first real retained binding/equivalent-repeat experiment;
• after MVP qualification receipt: bind exact candidate, target, workload, and validation evidence #31 is corrected, add/retain one cross-contract test proving a recaptured identical artifact observation (different event time/ref only) remains equivalent through qualification subject -> retained resolution;
• material artifact/source/runtime/request/target changes must continue to invalidate/rekey as designed.

No current real binding exists, so this can be corrected before empirical state is polluted.

[mark-e-deyoung]

2026-09-04 corrected retained-resolution head

The provider-identity correction is now carried through the retained-known path.

Current PR #38 head: 7a36acb6fda204089060457f52fa66e3a03e068f, directly based on corrected qualification head edb562f4ef9bd657149662dd9f52f70dcbbc7f29.

Key correction: retained selection.artifact is now the stable tuple provider + repository + immutable source_revision; normalized provider-observation digest/ref is event evidence, not selection identity. A regression test proves recapturing provider metadata for the same immutable revision leaves subject_key, resolution_key, and stable selection unchanged while the qualification event/record remains separately distinguishable.

Runtime-equivalence protection remains unchanged: resolution_key still binds request digest, target profile, environment digest, runtime ID, toolchain digest, and config digest. Tamper fail-closed, idempotent retain, explicit same-slot conflict, and missing->UNKNOWN semantics remain.

Public exact-head run 33845487953: PASS. PR #38 is draft, mergeable, and exactly five #37-specific files over its corrected base. No merge/release/deploy authorized.