fix(grants): serialize concurrent same-key spends + price in integer cents (#104)

[dzuluaga]

Follow-up to #112 (the merged grants feature). Fixes two correctness bugs found by the comparison in issue #104 — see the comparison comment.

In plain terms

The "spending grant" feature that just merged (#112 — a shopper approves a dollar limit once, and an AI agent spends within it while they're away) had two bugs. Both were found by comparing the merged code against the other, closed implementation of the same feature (#106), which had already solved them; this pulls those fixes forward.

1. A safe retry could be wrongly told the grant was cancelled. If the agent asked to buy the same thing twice at almost the same moment (a double-click, or a retry fired before the first answer came back), one of the two was told "this grant was revoked — stop," even though nothing was revoked and the purchase had actually gone through once. That's the opposite of what a retry is supposed to do.
2. A purchase that exactly fit the budget could be wrongly refused. Because amounts were tracked as decimal dollars, three $4.90 coffees against a $14.70 limit added up to $14.70000000001 inside the computer and tripped the "over budget" check. Anything priced in odd cents (a $4.99 item) could hit this.

What you're approving

• What changes: internal only. Grant spends are now handled one-at-a-time per grant (so racing retries line up instead of colliding), and money is counted in whole cents internally instead of decimal dollars (so exact-budget math is exact). No public API change — you still pass and read plain dollar numbers exactly as before.
• Worst case if it's wrong: a spend is refused (the safe direction) rather than a wrong charge. Money was never double-charged by either bug — the underlying ledger was already safe; these were a misleading error message and a false refusal.
• What stays safe: the plain-dollar API, every existing behavior, and the age/limit/allowed-items rules are all unchanged. This is a pure correctness + tests change.

How to test

npm install
npm run -w @openmobilehub/credentagent-gate build
npm run -w @openmobilehub/credentagent-gate test    # 364 pass, incl. the new "#104 port-forward" block
npm run -w @openmobilehub/credentagent-storefront test
npm run lint

The new tests deliberately fire two purchases at once and confirm they collapse to a single charge with a clean retry (not a false "revoked"), and spend three $4.90 items to a $14.70 limit and confirm the third is accepted. Each safety check was also verified by reverting the fix and watching the test fail.

---

For reviewers — the detail

Both fixes live in packages/credentagent-gate/src/grants.ts; the engine (delegated.ts) is intentionally untouched.

Fix 1 — per-grant serialization (KeyedMutex). The merged spend reads a per-key idempotency cache, then awaits the engine draw; two concurrent same-key calls both miss the cache and reach the engine, and the loser hits the atomic single-use ledger's consumed result, which the door's CODE_MAP turns into revoked (terminal). Ported #106's tiny per-key async mutex and now wrap spend, _authorize, _deny, and revoke in this.locks.run(id, …), so the losing same-key retry finds the populated cache and replays the original outcome (ok, replayed: true), and a revoke landing while an authorize is in flight can't be overwritten back to a spendable state. Distinct-key spends serialize too and each still commits atomically. In-process only (see the known follow-up below).

Fix 2 — integer cents internally, plain-dollar API unchanged. grants.ts now feeds the engine a cents-priced catalog (centsCatalog) and cents caps (toCents), and converts each spend's amount/remaining back to dollars for the door. The engine does integer math on whatever unit it's handed, so this is confined to grants.ts and needs no engine or public-type change. Fixes the 4.9 + 4.9 + 4.9 > 14.7 float-drift false refusal.

Tests (grants.test.ts). A new #104 port-forward block: three bypass tests — concurrent same-key collapse, revoke-racing-authorize, and the $4.90×3 boundary — each verified to go red when its control is reverted (neuter the mutex → the two concurrency tests fail; feed the engine dollars → the boundary test fails), then restored. Plus two regressions (distinct-key no-overspend; double-approve seals one grant, cap holds). The merged suite had zero concurrency or money-boundary coverage, which is why these two shipped.

Known follow-up — NOT in this PR (deliberately scoped out): grants are stored in in-memory maps, so grants.retrieve(id) in a different process (a restart, or a second serverless instance — the human-away worker spec-009 FR-007 describes) finds nothing. Making grants durable across processes needs an injected store plus a compare-and-set for the cross-instance version of the same concurrency guard; that is the next step, tracked via the issue #104 comparison comment.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y5Y1aX9ffAF26hP4fgQFi7

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
credentagent-demo	Ready	Preview, Comment	Jul 28, 2026 2:25am

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ec2ac4aa83

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Let revocation interrupt an in-flight spend

Do not hold the per-grant mutex across rec.engine.spend(): when revoke() is called while that asynchronous operation is in flight, it queues behind the spend and cannot update the revocation ledger until after the draw commits. This directly breaks the revoke-wins requirement in specs/009-ap2-mandate-chain-dx/spec.md:136-140, which requires a spend that settles after revocation to be refused; serialize the idempotency-cache transition without preventing revocation from reaching the engine concurrently.

Useful? React with 👍 / 👎.

[dzuluaga]

Fixed in 4bd6e47. The engine ledger revoke now runs immediately, outside the per-grant mutex, so a spend already in flight hits it at its atomic settle-time re-check and is refused (revoke-wins, spec §136–140). The status flip + the authorize-race re-revoke stay serialized in the mutex, and #135's same-key serialization is unchanged. New bypass test: start a spend, revoke mid-flight, assert it is refused (code: revoked) — verified RED when the ledger revoke is moved back inside the mutex, then restored.

[chatgpt-codex-connector]

Keep cents pricing synchronized with the configured catalog

Preserve live catalog repricing when constructing the cents-priced gate. centsCatalog() creates a detached snapshot and this.gate retains it forever, whereas DelegatedGate.buildCatalog() previously read the original catalog record on every order. If the host changes an in-memory price after the first grant is created—for example, coffee rises from $10 to $100—a later spend is still priced at $10 and can pass a sealed $30 cap even though the configured price source now says $100; additions to the catalog similarly continue throwing as unknown items.

Useful? React with 👍 / 👎.

[dzuluaga]

Fixed in 4bd6e47. Replaced the centsCatalog() snapshot with a live cents view (a Proxy the engine reads per spend), restoring the pre-#135 per-read behaviour — an in-memory re-price, or a newly-added item, is honoured at the next spend, and the sealed cap is enforced against the live price. New bypass test re-prices coffee $18→$25 (next spend prices $25), then →$50 (now refused per-spend-exceeded against the $40 cap) — verified RED with a snapshot, then restored.

[chatgpt-codex-connector]

Reject dollar values that cannot be represented in cents

Validate unrepresentable dollar inputs instead of silently changing their value. The public catalog and grant options still accept arbitrary numbers, so a configured price of 0.006 is now returned and enforced as $0.01, while 0.004 becomes zero and is refused as invalid-amount; binary rounding also turns values such as 1.005 into $1.00. Either reject amounts with sub-cent precision at creation/configuration time or use a conversion that preserves the documented input semantics.

Useful? React with 👍 / 👎.

[dzuluaga]

Decision: reject (per the DX rubric — fail fast, never silently change a configured value; matches the closed #106's precedent). toCents() now throws on sub-cent precision at the earliest point — grant caps at create(), catalog prices when they are priced — instead of rounding. Fixed in 4bd6e47 with a bypass test (a perSpend: 0.006 cap rejects at create; a $0.006 catalog price rejects when spent) — verified RED with silent rounding, then restored.