Public recommendation contract: expose catalog reasoning_effort on serialized CandidateEvaluation #148

New issue

Closed

opened 2026-09-27 23:33:56 +00:00 by kilo · 1 comment

kilo commented

2026-09-27 23:33:56 +00:00

Member

Goal

Expose the reasoning effort belonging to every serialized recommendation candidate through the stable public recommendation contract, so independent consumers (e.g. Creatidy Kernel) can execute the exact recommended configuration without parsing opaque identifiers.

This closes the contract gap discovered by Creatidy Kernel K8 (Kernel issue #11): the Kernel public-contract gate failed because /v1/select could not convey the exact execution configuration without forbidden inference. This is an upstream Scarcity Router contract correction, not a Kernel-specific compatibility hack.

Required semantics

Extend the public CandidateEvaluation serialization with:

reasoning_effort: string | null

The member MUST always be present in serialized candidate evaluations.
A non-null string is the exact normalized reasoning effort configured for that candidate (the frozen REASONING_EFFORTS vocabulary).
null means the candidate has no configured reasoning effort.
null is distinct from the real configured effort value "none".
Consumers must never derive reasoning effort from variant, model name, resource id, source id, display name or other opaque identity; no new mapping or inference rule is introduced.

Because SelectionDecision reuses CandidateEvaluation, the same field and semantics must appear consistently in selected, alternatives, excluded, closest_candidates and recoverable_candidates. No special selected.reasoning_effort representation.

Public surfaces (one-core parity)

The field must propagate consistently through all existing recommendation surfaces that serialize SelectionDecision:

CLI JSON output
loopback REST /v1/select
MCP scarcity_select
authenticated machine/control /v1/select
remote bridge envelope validation/tests where relevant

No selection logic in any transport adapter.

Versioning

Verified: docs/machine-interfaces.md (Versioning section) states additive backwards-compatible domain fields may flow through machine-interface v1 as long as existing v1 clients remain valid (the D-039 eligibility precedent). This change keeps envelope/schema version 1 and is documented as an additive-compatible extension. No version bump, no compatibility serializer.

Provenance and source of truth

reasoning_effort must come from the same catalog entry that participates in the authoritative selector ranking (the ranking already consumes the catalog effort as the D-032 effort tie-break). It must NOT be reconstructed after selection from ModelIdentity.variant. The serialized field reflects the exact candidate catalog configuration used by that decision.

Required regressions

Discriminating tests proving at minimum:

selected candidate serializes its configured reasoning effort;
alternatives serialize their own effort independently;
excluded / closest / recoverable candidates preserve the same field semantics where present;
unconfigured effort serializes as explicit null (key present);
configured "none" serializes as "none", not null;
a candidate whose opaque variant differs from its reasoning effort still serializes the catalog reasoning effort (no inference from variant);
REST, MCP and authenticated control surfaces preserve parity;
remote bridge accepts the additive field without inventing or stripping semantics;
existing selection/ranking behavior is unchanged.

Scope constraints (do NOT)

change selector ranking, capability ratings or model identity semantics;
make variant equal effort;
expose internal resource/source ids;
change execution routing or execution gateway behavior;
add Kernel-specific code or account/access-mode/business-model fields;
broaden into the Upwork/business-model redesign;
alter provider telemetry;
modify main, release or deployment.

This issue only makes an already-existing authoritative selection input visible in the public decision output. Documentation updates: docs/machine-interfaces.md (additive v1 note), docs/selection-policy.md (records the D-032 deferral of public explicit effort output — superseded by this change), docs/architecture.md, and a decision record in docs/decisions.md (serialized public contract change requires an explicit decision per repository policy).

Cross-project evidence

Motivating external-consumer proof: Creatidy Kernel K8 issue #11 — public-contract gate failed because /v1/select could not convey the exact execution configuration without forbidden inference. Recorded as evidence only; the repositories are not coupled operationally.

Workflow

Branch from develop, PR targets develop, PR left open (unmerged) for human review.

## Goal Expose the reasoning effort belonging to every serialized recommendation candidate through the stable public recommendation contract, so independent consumers (e.g. Creatidy Kernel) can execute the exact recommended configuration without parsing opaque identifiers. This closes the contract gap discovered by Creatidy Kernel K8 (Kernel issue #11): the Kernel public-contract gate failed because `/v1/select` could not convey the exact execution configuration without forbidden inference. This is an upstream Scarcity Router contract correction, not a Kernel-specific compatibility hack. ## Required semantics Extend the public `CandidateEvaluation` serialization with: ``` reasoning_effort: string | null ``` - The member MUST always be present in serialized candidate evaluations. - A non-null string is the exact normalized reasoning effort configured for that candidate (the frozen `REASONING_EFFORTS` vocabulary). - `null` means the candidate has no configured reasoning effort. - `null` is distinct from the real configured effort value `"none"`. - Consumers must never derive reasoning effort from `variant`, model name, resource id, source id, display name or other opaque identity; no new mapping or inference rule is introduced. Because `SelectionDecision` reuses `CandidateEvaluation`, the same field and semantics must appear consistently in `selected`, `alternatives`, `excluded`, `closest_candidates` and `recoverable_candidates`. No special `selected.reasoning_effort` representation. ## Public surfaces (one-core parity) The field must propagate consistently through all existing recommendation surfaces that serialize `SelectionDecision`: - CLI JSON output - loopback REST `/v1/select` - MCP `scarcity_select` - authenticated machine/control `/v1/select` - remote bridge envelope validation/tests where relevant No selection logic in any transport adapter. ## Versioning Verified: `docs/machine-interfaces.md` (Versioning section) states additive backwards-compatible domain fields may flow through machine-interface v1 as long as existing v1 clients remain valid (the D-039 `eligibility` precedent). This change keeps envelope/schema version 1 and is documented as an additive-compatible extension. No version bump, no compatibility serializer. ## Provenance and source of truth `reasoning_effort` must come from the same catalog entry that participates in the authoritative selector ranking (the ranking already consumes the catalog effort as the D-032 effort tie-break). It must NOT be reconstructed after selection from `ModelIdentity.variant`. The serialized field reflects the exact candidate catalog configuration used by that decision. ## Required regressions Discriminating tests proving at minimum: 1. selected candidate serializes its configured reasoning effort; 2. alternatives serialize their own effort independently; 3. excluded / closest / recoverable candidates preserve the same field semantics where present; 4. unconfigured effort serializes as explicit `null` (key present); 5. configured `"none"` serializes as `"none"`, not `null`; 6. a candidate whose opaque `variant` differs from its reasoning effort still serializes the catalog reasoning effort (no inference from variant); 7. REST, MCP and authenticated control surfaces preserve parity; 8. remote bridge accepts the additive field without inventing or stripping semantics; 9. existing selection/ranking behavior is unchanged. ## Scope constraints (do NOT) - change selector ranking, capability ratings or model identity semantics; - make variant equal effort; - expose internal resource/source ids; - change execution routing or execution gateway behavior; - add Kernel-specific code or account/access-mode/business-model fields; - broaden into the Upwork/business-model redesign; - alter provider telemetry; - modify `main`, release or deployment. This issue only makes an already-existing authoritative selection input visible in the public decision output. Documentation updates: `docs/machine-interfaces.md` (additive v1 note), `docs/selection-policy.md` (records the D-032 deferral of public explicit effort output — superseded by this change), `docs/architecture.md`, and a decision record in `docs/decisions.md` (serialized public contract change requires an explicit decision per repository policy). ## Cross-project evidence Motivating external-consumer proof: Creatidy Kernel K8 issue #11 — public-contract gate failed because `/v1/select` could not convey the exact execution configuration without forbidden inference. Recorded as evidence only; the repositories are not coupled operationally. ## Workflow Branch from `develop`, PR targets `develop`, PR left open (unmerged) for human review.