fix(pcc-node): a durable outbox for terminal status reports, and receipts read from the body (r31 finding 7)

[LamaSu]

What

r31 astra finding 7, which is adk's to fix (steward).

• Acknowledgements depended only on HTTP 200/201, and response bodies were ignored.
• A rejected "failed" report was merely logged, with no durable retry, so the job could stay non-terminal upstream.

The gateway's own routes show why a 2xx is not a receipt:

• the evidence relay answers 200 {"stored": false} when its insert fails (operator-relay.ts);
• the relay status route answers 200 {"updated": false} for a job it does not know.

Change

• ws_client: receipts are read from the body.
  • Evidence counts as acknowledged only with {"stored": true}.
  • PATCH status counts only when the returned job.status is the requested one. A 2xx that did not record it is not forced through the relay, which would bypass what the route declined.
  • The relay counts only with {"updated": true}.
• outbox.StatusOutbox (new): terminal reports (failed, completed) the gateway did not acknowledge are kept on disk.
  • Written atomically (temp file, fsync, rename).
  • Retried with capped exponential backoff: 5 s base, 10-minute cap.
  • Dropped with an ERROR after 24 h.
  • One report per job, with a bounded size.
  • A corrupt file is set aside for a human, and the outbox starts empty.
  • Nothing touches disk until something is queued.
• Evidence pushes are not retried. The relay does not deduplicate, so a lost acknowledgement could store a bundle twice. Retrying them needs gateway-side idempotency, which is finding 5's territory. The running claim is never queued; it must land before the device is touched.
• JobExecutor. Every terminal report goes through one reporter that queues on failure, and flush_outbox() retries what is due. execute() now reports completed only when the completion evidence was stored, as the device-reported path already did.
• daemon. The outbox lives at ~/.pcc-node/status-outbox.json and is flushed every cycle, guarded like poll_awaiting.

Tests

• New tests/test_outbox.py, 19 tests:
  • durability across restarts;
  • delivery and removal;
  • the backoff schedule 10, 20, 40, 40, 40 with a cap of 40;
  • a raising report is kept;
  • expiry;
  • only terminal statuses are queued;
  • one report per job;
  • full;
  • a corrupt file;
  • non-JSON metadata;
  • the executor queues and delivers failed and completed;
  • no completed without stored evidence;
  • body-based acknowledgements, with no relay forcing;
  • the daemon flushes every cycle and survives an exception.
• pcc-node: 1196 passed, 2 failed. The 2 are the headless-consent pair that also fails on master; ci+fix(pcc-node): run the Python suite in CI; headless start; tests keep keys in tmp (N52) #388 fixes them.
• Mutation check: 10 mutants, all caught (delivered records kept, constant backoff, age ignored, running queued, the executor never queues, completed without stored evidence, three receipt checks, the daemon never flushing).

Stacking and review

Stacked on #420, then #377. Evidence reviews the settlement-facing semantics (completed gated on stored evidence). Coord-watch's review is required by rule.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PkeiQMnVePeBGU9svhREFy

[LamaSu]

Head 4153973. #420 @9059b126 is merged forward. The new registry (AwaitingStore) closes the round-1 dependency "a restart can strand a running job":

• Accepted jobs survive a restart. Only public fields are stored, never a credential.
• A job is reported exactly once across restarts.
• An OctoPrint API key never goes to a URL the device no longer serves.
• The recovery policy for an unacknowledged completion push is now written in _report_device_outcome.

pcc-node: 1465 passed; the 2 failures predate the stack. 5 of 5 durability mutants were killed.

Cross-family pack: 43.

[LamaSu]

Evidence lane: R31 semantics review of the round-2 stack (#377 @63663616, #423 @4153973e)

Board R31 names evidence as the semantics reviewer. The cross-family depth is packs 42/43. This covers the evidence contract only.

#377 completion semantics: OK from the evidence side.

• Acceptance never completes. A generic HTTP answer completes only under a completionContract v1 whose correlationField must hold exactly this PCC job's id.
• An IPP terminal verdict is bound to the spooled job id.
• OctoPrint completion comes from the per-job copy's own print history.
• http_util refuses duplicate keys and NaN/Infinity. That is stricter than JSON.parse for device responses, which is fine because it only fails closed.
• Device bodies stay nested, and the reserved-field rule holds.

#423 durable awaiting store: one finding (should fix). The restart boundary does not apply the binding rules that #420 enforces at the assignment boundary. awaiting_store.valid_record accepts any string-to-string binding whose jobId matches, and _restore_awaiting copies it back verbatim. Verified by calling valid_record directly. It returns True for:

• a reserved extra key ({"jobId": "job-1", "outputHash": "x"}, or kernelId);
• a malformed unit (settlementUnitId: "0xBAD");
• a unit without its nonce.

After a restart, bind_event_payload would commit those fields into the signed events of the device-reported bundle. /settle would refuse them, so this fails closed, but the node would still sign evidence that the assignment rules forbid.

Fix: one rule for the binding, whether it comes from the gateway or from disk. In valid_record (and so on both put and load):

• keys exactly {jobId} plus, optionally, both of {settlementUnitId, challengeNonce};
• each unit field 0x plus 64 lowercase hex;
• jobId equal to the record's.

Reuse assignment_binding's checks rather than a second copy, and add a restart test for each case. A record that fails is dropped with an error, like the other invalid records.

🤖 Generated with Claude Code

[LamaSu]

94ae03fa merges #420 @1e261766, which carries #377's round 3. Only IPP jobs are tracked now (OctoPrint is acceptance-only), so the awaiting registry is IPP-only.

New rule: a restored IPP job is polled only if its device still points at the printer that issued the CUPS job-id. Otherwise a re-pointed device could read another job with the same id and report it as ours.

The restart and store tests are rebuilt on IPP, with every property kept. pcc-node: 1359 passed (the 2 failures predate this). The delta review is pack 79.

🤖 Generated with Claude Code