Define the CP2 authorization-result surface and registered public reason codes

[samovers]

Parent: #10. Required adjacent-contract predecessor of #21 under approved PR #11 section 24, step 3.

Problem and outcome

The approved authorization design requires caller-facing results to distinguish denied authority, required review, required human action, invalid requests, and withheld details without disclosing protected basis information. Current CP2 result qualification has no explicit authorization-result surface. Its reason-code registry is extensible, but the five proposed public codes in PR #11 are not established by the current inspected CP2 contracts and registry example.

Define the smallest compatible CP2 authorization-result qualification and public reason-code contract. A consumer must be able to tell what action is permitted next without treating a denied or redacted result as absent data, inventing a durable decision, or exposing the internal authorization trace.

This is a canonical public-result semantics prerequisite, not an authorization evaluator, API endpoint, transaction implementation, or request to reopen the twenty-row action matrix.

Primary trust boundary and authority map

Primary trust boundary: public authorization-result qualification and diagnostic information disclosure.

Responsibility	Owner and limit
Public qualification, registered reason meanings and safe response content	This CP2 contract; truthful user/agent-facing explanation without protected basis leakage
Authorization outcomes, canonical reason ranking, action eligibility and approval requirements	Approved PR #11; consume these meanings without a second evaluator or private reason registry
Permission to inspect full traces, targets or retained bytes	Separately authorized governed-read path; a response or trace reference grants no new access
Durability, refusal evidence, single use, retry eligibility and reconciliation	Owning transaction contracts, including PR #20 and PR #26 where applicable; public messages cannot confer retry or effect authority
Retained-byte versus digest-only claims and later availability	Approved PR #29; qualify those claims without redefining retention, deletion or custody
Machine materialization, acceptance, current/default selection and extraction	Separately governed stages under PR #11 section 24 and #21

The first deliverable is one non-authoritative Phase A candidate in the existing phase-report lane, with review and semantic approval before later contract edits. It must not edit approved candidate PRs or active contracts. If a mapping requires changing another owner's meaning, stop before that change and identify a separate prerequisite or amendment.

Exact inputs and observed gap

Inspected canonical main: 71ca724a8b6ec23f1655b086a6f549496d10a47f.

• PR RFC candidate: executable authorization evidence v0.2 #11 at 03a21f669ee04f96d444e14f00ae7212cab04803, particularly sections 7.8, 18.5, 18.7 and 24, supplies the approved public mapping and separate CP2 prerequisite.
• PR RFC: authorization evidence retention and proof strength (Phase A) #29 at 8e0994cae5610ac9c0d2652e02c8a8a2dd7b45c5 supplies the approved retention/proof-strength semantics. Its schedule-resolution carrier clarification remains later retention-contract work, not an addition to this public-surface scope.
• 02_accepted_rfcs/OFARM_AI_Facing_Result_Qualification_and_Trace_Surface_RFC_v0_1.md and 02_accepted_rfcs/OFARM_RuntimeProblem_Reason_Code_Registry_RFC_v0_1.md remain the existing CP2 owners.
• Current/default 03_machine_contracts/schemas/runtime_surface/OFARM_ResultQualificationEnvelope_schema_v0_1.json has six surface classes: query result, materialization read, public read model, passport preview, document preview and output result. It has no authorization-result class. Raw-file SHA-256: a6fa2ac6029b01aa5536d563dab099e8adc224e696bfd468e9bd0ab90b5eeb52.
• Current/default 03_machine_contracts/schemas/runtime_surface/OFARM_RuntimeProblemReasonCodeRegistry_schema_v0_1.json defines code metadata, including retryability, human review, sensitivity and safe UI behavior. Raw-file SHA-256: 62191e9a983b5cb60468404c4c26b0e4ad7ec6298902f2c497caeea6850b57c3.
• Current/default 03_machine_contracts/schemas/core/OFARM_RuntimeProblem_schema_v0_1.json permits syntactically valid open-ended reason strings. Raw-file SHA-256: 873dbeda2932d48a54e5d08d22f4031c6a86b44712a3cec85f1c1008f4d6e95b. Schema validity alone does not register a reason code or make its text safe.

The currentness map reports no non-default variants for these three families. Its linked CP2 core registry example contains EVIDENCE_INSUFFICIENT, MATERIALIZATION_STALE and PERMISSION_REDACTED; an example's ACTIVE field does not itself grant canonical registration authority. The accepted reason-code RFC also names broader example codes such as AUTHORITY_DENIED and HUMAN_APPROVAL_REQUIRED. Inventory those meanings before proposing new entries; do not silently rename them, treat near-synonyms as interchangeable, or create an authorization-private registry.

Acceptance criteria

1. Inventory the current CP2 schemas, governing reason-code process, examples and public-surface consumers. Identify the smallest required surface/profile extension and the exact existing carriers that can remain unchanged. Do not force authorization output into an unrelated query/output surface or invent a new top-level family without proving the existing carriers cannot express the truth claim.
2. Preserve PR RFC candidate: executable authorization evidence v0.2 #11 section 18.7's public categories: DENY maps to proposed AUTHORIZATION_DENIED; REQUIRE_REVIEW to AUTHORIZATION_REVIEW_REQUIRED; REQUIRE_HUMAN_APPROVAL to HUMAN_ACTION_REQUIRED; ingress rejection to REQUEST_INVALID; and suppressed details to DETAILS_REDACTED alongside the truthful primary category. These remain proposed until the governed CP2 registration stage. A necessary change to this approved mapping returns to the authorization owner rather than becoming a local alias or new outcome.
3. Define the authorization-result qualification bindings and compatible fields for permission/redaction posture, data-absence reason, blocked uses, trace availability and safe display/next-action hints. Distinguish prepared evidence, committed refusal, runtime/persistence failure and later receipt lookup without inventing a durable decision when none committed. Do not add a synthetic positive authorization code or change governed-read qualification merely to fill the schema.
4. Supply a complete proposed registry entry for each needed public code using the existing registration process: family, severity, retryability meaning, human-review requirement, sensitivity, safe message, developer meaning, remediation, relevant trace types and safe UI behavior. Public retry guidance must respect the owning operation's state and cannot authorize automatic re-execution, revive an approval, or override a terminal/unknown outcome. Human action and human review must remain distinguishable.
5. Define the safe projection and forbidden disclosures. Internal basis IDs, hidden resource existence, grants/revocations, validation locations, policy internals and canonical reason rankings do not leak through messages, pointers, trace links, counts, metadata or remediation. Full trace retrieval still needs its separate governed-read authorization. Redaction must not conceal the primary safe category.
6. Preserve PR RFC: authorization evidence retention and proof strength (Phase A) #29's proof limits when they are exposed through an authorized surface: missing bytes, denied access, an integrity failure, a redacted derivative and digest-only evidence are different facts. Neither possession of a receipt/hash nor a public explanation becomes a read or hash-comparison credential. This contract does not implement a verifier or retention store.
7. Specify production-reachable positive and hostile cases for all public categories; invalid ingress without an authorization decision; failed persistence without a durable-refusal claim; denied/foreign/hidden targets with non-leaking responses; unauthorized trace access; redacted diagnostics preserving the primary category; unknown/unregistered codes; unsafe interpolated text; invalid qualification combinations; and forbidden retries during terminal or unknown operation state. Include issue-criterion-to-invariant-to-case traceability. The Phase A cases are specifications, not executed runtime evidence.
8. Identify exact future non-default schema/profile, registry, example and conformance units; their registration/versioning owner; required cross-binding review; and later acceptance/currentness/extraction gates. No placeholder digest, active-looking example or approved design can stand in for the required materialized and admitted bytes.
9. Keep the PR within this public-result/diagnostic-disclosure boundary. Preserve PR RFC candidate: executable authorization evidence v0.2 #11 authorization semantics, existing CP2 safe-result rules, the transaction protocols and PR RFC: authorization evidence retention and proof strength (Phase A) #29 retention law. Record any genuine conflict for its separate owner before editing that boundary.

Dependencies and non-dependencies

Consume the exact approved authorization and retention semantics and the existing CP2 authority/registration process. Inspect the transaction contracts for compatible public meaning; do not implement or reclassify their states here.

The first semantic candidate can be reviewed without inventing the twelve remaining domain-effect contracts, a storage provider, a key issuer, a transaction producer or a public endpoint. Exact later machine bindings still require their real inputs. This work does not close the remaining #12 families or allow #21 promotion to skip its other predecessors.

OFARM2 #353 needs the admitted contract bindings for its complete authorization evidence; actual public response delivery remains with the applicable runtime/transaction/read consumer. No endpoint is activated by this canonical work.

Non-goals

• No authorization-rule, principal, grant/delegation, CP3, human-eligibility or source-record change.
• No protected-effect contract or Event Grammar amendment.
• No transaction, idempotency, retry/reconciliation engine, receipt writer or durable-result change.
• No storage, encryption, deletion, key custody or evidence-inspection implementation.
• No API/UI/SDK implementation, public route activation, new data access or transport release.
• No change to current/default schemas, accepted law or indexes in the Phase A candidate.
• No merge, promotion, extraction, deployment, production-readiness claim or OFARM2 implementation approval.

Verification and handoff

For the Phase A candidate, verify exact source pins, inventory/currentness claims, every public-category mapping, hostile-case traceability, one-file scope, Markdown structure and diff hygiene. Run the existing cheap canonical hygiene/currentness/cross-reference/steward checks, stating that several exclude the historical candidate lane. Do not present them as executed privacy/runtime tests.

Later materialization must validate positive and negative schema/registry fixtures and cross-bindings in its authorized contract stage. Runtime conformance remains a later independently scoped capability.

What is next: inventory the current CP2 carriers and registration process, then prepare the one-file non-authoritative Phase A candidate for review. Issue creation alone is not approval to edit active contracts or implement runtime behavior.