joulehook: the joule budget survives the process, so it can be exceeded #310

Merged

dcharlot merged 2 commits from fix/joulehook-budget-survives-the-process into main 2026-10-18 13:45:34 -04:00

Conversation 0 Commits 2 Files changed 2 +229 -5

2026-10-18

Transaction Science

jcp-bridge: cite §8.1, the rule this standard actually states ...

`check-spec-refs` caught a dangling citation in the previous commit:
`LocalToolGate::resume` cited "SPEC §3.3's 'over budget is deny'", but
§3.3 is JouleHook's section. A citation in a jcp crate resolves against
`jcp/SPEC.md`, which defines no §3.3 — that binding rule is exactly what
the check exists to enforce, and it fired on its author.

The rule this method implements is jcp's own: §8.1, "The receipt stream
is the write-ahead log (REQUIRED)" — an enforcement point that crashes
rebuilds its budget state by replaying its own verified receipt stream.
That is what `resume` does, and it is the same section `Bridge::restore`,
`Runtime::restore` and `Gateway::resume` already cite.

The JouleHook consequence is still described, without a bare §-citation
that would bind to the wrong standard; the rule is cited where it lives,
in `joulehook-hook`.

Co-Authored-By: Claude Opus 5 <[email protected]>

a63d788046

• View at this point in history

2026-10-18 07:49:53 -04:00

Transaction Science

joulehook: the joule budget survives the process, so it can be exceeded ...

SPEC §3.3 is normative: "If the action carries an estimable cost, the
grant's joule budget MUST be ≥ the estimate; over budget is `deny`. On
`allow`, the spent amount is debited."

The debit lived in the `LocalToolGate` that `gate()` constructs, and
`gate()` runs once per process — this binary is a PreToolUse command the
host spawns per action. So the spend total died with the process on every
single call and the next action started again at the full
`JOULEHOOK_BUDGET_UJ`. **There was no sequence of actions that could
exhaust the budget**, so the deny branch could never be taken, and
`conformance/v1/receipt.json` records the symptom: `budget_remaining_uj:
1000000000`, the untouched ceiling.

Worse, the deny branch that *was* reachable reported the wrong thing: a
single message, "is not in the granted capability set", covered every
denial — so a budget denial would have been recorded as a capability
denial if one could ever have happened.

The hook already wrote the evidence and never read it: sealed receipts
are appended to `JOULEHOOK_RECEIPT_LOG`, hex per line.

- `LocalToolGate::resume` replays a sealed stream into the gate's spend
  ledger via `jcp_receipt::replay_spend`, so only verified allow-receipts
  of this gate's own steward contribute debits. `Bridge` gains
  `steward()`, `steward_pubkey()` and `restore()` to make that possible.
  The grants are deterministic (fixed issuer key, `nonce: [0; 16]`,
  `expiry: 0`), which is exactly why a later process rebuilds
  byte-identical grant ids for the debits to land on — and exactly why
  the budget refilled without them.
- `gate()` replays the stream before deciding, and the allow reason now
  records the spend and how many receipts it replayed.
- A budget denial says it is a budget denial.
- **No stream configured** ⇒ the ceiling covers one call only. That is
  now disclosed in the allow reason rather than asserted: §3.3 states
  the budget MUST hold, and per-call it cannot. The crate's env doc
  previously carried the disclosure ("Cross-call budget accounting needs
  a persistent gate") while the SPEC's MUST did not; the doc is updated
  to point at the stream that now provides it.
- **A stream that does not decode denies.** The prior spend is then
  unknown, the budget cannot be asserted, and allowing anyway is the
  refill the replay exists to prevent — fail closed, as SPEC §8 has this
  binary do for an unparseable payload and an unrecognised shape.
  A missing file is simply the first call.

The headline test runs three separate `run()` calls — each a fresh gate,
which is what a per-action process is — persisting between them as
`main` does: 2 mJ, 2 mJ, 2 mJ against a 5 mJ ceiling gives allow, allow,
**deny**, with the denial naming the budget. Previously that third call
allowed, and so would the three-hundredth.

Co-Authored-By: Claude Opus 5 <[email protected]>

449172c36e

• View at this point in history

2026-10-18 01:38:36 -04:00