refund-connected/v1 · the input_pic layer as an external contract

corpora/vectors-refund-connected retains a multi-party run, and the packaged reader re-derives six verdicts per case from its bytes. refund-connected-input-aps.md states the second layer, input_aps, as a contract an outside reader can implement alone. This document does the same for the first layer, input_pic. It is written from the retained bytes and the packaged reader's behaviour; where the two disagree, the bytes win and this document is wrong.

What the layer decides

Whether the PIC proposal the caller is about to act on carries one valid, trusted merchant attestation, and whether that attestation's three digests cover exactly the arguments, the claims and the intent text the proposal carries. It then checks that the runner's own PIC result file is about these same bytes and says allow.

It answers one question: did a trusted merchant key sign exactly these refund arguments, this claim and this intent, and did the runner record that it allowed them?

It does not decide whether the APS approval exists, is unexpired or matches the payload, whether the admission record committed, or whether anything was executed. Those are later layers. Unlike input_aps, this layer takes no values from a caller: it is the first layer and reads only the case directory.

Inputs

Paths are relative to source/<run>/cases/<case>/ inside the corpus.

Step 0 covers these eleven files and no others: the three above plus the eight in the last row.

Canonical forms

Two digests are taken over JSON values (JCS), and one over a plain string's UTF-8 bytes. Keep them apart:

args digest   : sha_hex(JCS(proposal.action.args))
claims digest : sha_hex(JCS(proposal.claims))
intent digest : sha_hex(UTF-8 bytes of proposal.intent)
signature     : Ed25519 over JCS(att), where att is the parsed attestation object

The signature message is JCS of the parsed attestation, not the raw payload string. In the corpus the two are byte-identical, because the payload is written in JCS form; a reader that verifies over the raw string agrees on every retained vector but is not following this contract.

Procedure

Let prop be the parsed proposal, keys the parsed keyring and result the parsed runner result. Steps run in this order and the first failing one decides the layer. Where a step reads a member of a value that is not an object, or a member that is absent, the step fails.

If every step holds the layer is ESTABLISHED.

The runner-allowed rule

Steps 0b to 13 refuse. One rule rewrites a refusal after the fact: when a step from 0b to 13 refuses with code X, and inputs/pic-verification.json strict-parsed to an object whose result member is the string "allow", the verdict is CONTRADICTED:runner-allowed-X instead of REFUSED:X (for example CONTRADICTED:runner-allowed-PIC_ARGS_DIGEST). The proposal is bad, and the runner's own record says it let the proposal through; that is a contradiction between two parties' bytes, not a clean refusal. When the runner's result says block, or is missing, or did not parse, the refusal stands. The rule does not apply to input-files-missing, which is not a refusal.

So the layer produces four kinds of verdict: ESTABLISHED, REFUSED:<code> (steps 0b to 13), CONTRADICTED:<code> (steps 14 to 20, and the runner-allowed rule) and NOT_ESTABLISHED:input-files-missing (step 0a). It never produces NOT_REACHED, because nothing runs before it.

What the layer hands to the next one

An ESTABLISHED verdict also yields the values the input_aps contract takes from its caller:

A caller that chains the two contracts runs input_aps only when this layer is ESTABLISHED; otherwise input_aps is NOT_REACHED, assigned by the caller.

Coverage in the corpus

The manifest carries one expected verdict per vector per layer. For this layer all twelve vectors are scored, and they split into two observed outcomes:

• established: j01, n1b-aps-payload, n3-reissue, n3b-old-pic and n4-lost-ack, in both runs (ten vectors). n1b and n3b are bad at the APS layer, not here: their PIC proposals are sound.
• REFUSED:PIC_ARGS_DIGEST: n1a-pic-args, in both runs (two vectors).

Every other code in the procedure is unexercised by these bytes. That is a property of the corpus, not of the contract: an implementation that returns ESTABLISHED for the ten and REFUSED:PIC_ARGS_DIGEST for the two is consistent with every vector, and one that returns anything else for any of them is not.

Running an independent verifier

The layer needs only the case directory:

<cmd> source/<run>/cases/<case> --json

The last nonempty stdout line is one JSON object on one line, for example {"verdict": "ESTABLISHED"} or {"verdict": "REFUSED:PIC_ARGS_DIGEST"}. The exit status is 0 for ESTABLISHED and nonzero otherwise. Score it against the input_pic value in each vector's expected.steps. A one-shot run is not a conformance claim; pin the corpus at a release or a commit and say which run and which case each verdict came from, as docs/VERIFIERS.md asks.

Worked example: r1 / n1a-pic-args

The merchant signed an attestation over a refund of 4000 minor units of EUR on pay_C; the proposal then carries amount_minor: 4100. Steps 1 to 8 hold: the signature is valid, because the attestation itself was not touched, and the arguments still have the refund shape. Step 9 is where it shows:

sha_hex(JCS({"amount_minor":4100,"currency":"EUR","payment_id":"pay_C"}))
  = 3de849c198291237785735b7a1d013fd13e9f164f80e4d296ea08aac8e1393c5
att.args_digest
  = 6a0df2560801d3e76a4b8052fca7e84790bcfc7c5773bbefd353ba73fd53dede
  = sha_hex(JCS({"amount_minor":4000,"currency":"EUR","payment_id":"pay_C"}))

They differ, so the layer refuses with PIC_ARGS_DIGEST. The runner's result for this case says "result": "block" with "error_code": "PIC_EVIDENCE_FAILED", so the runner-allowed rule does not apply and the verdict stays REFUSED:PIC_ARGS_DIGEST. Nothing downstream is read for this case.

What this contract does not do

• It does not judge the run. A verdict from it is a verdict for input_pic only.
• It does not check the PIC attestation's own expires_at; input_aps compares it with the consumption instant (its step 25).
• It does not cover input_aps (see refund-connected-input-aps.md), admission, signature_trust, execution or observed_effect.
• The manifest's verifierContract names the input_aps layer. This document is the interface for input_pic in the same shape; a verifier built from it answers for that layer alone.