Local storage and billing audit
Reviewer: Codex billing/audit agent, separate write ownership from the account/quota implementation coordinator. Date: 2026-10-11. Outcome: focused local verification passed; production approval remains unsigned. The storage/HTTP integration was independently reviewed against the coordinator's implementation; the Polar module was authored and self-reviewed by this agent. This review is not a human approval, live provider verification, or large-load deployment certification. The requested independent model review, if unavailable in the coordinator's environment, must be recorded separately in DEVLOG.md.
Scope: the portable Polar integration, durable account quota/reservations, SQLite inbox/object catalogs, Node message/object transaction boundaries, and HTTP billing authorization. Billing remains disabled and no live payment/API operation was performed.
Findings reconciled with implementation
| Finding | Final behavior | Local evidence |
|---|---|---|
| Paid grants must belong to the recipient UUID | The quota transaction checks billing/state.owner against the account owner before resolving paid capacity. |
A grant for another UUID resolves to Free even with a future paid deadline. |
| A subscription can expire while upload is pending | Commit resolves entitlement again after authoritative usage is updated, excluding its own pending growth; a positive-growth upload fails and rolls back if the deadline was crossed. | Paid deadline crossed during upload, with metadata/usage rollback and orphan deletion. |
| Network effects must follow a durable quota reservation | Both message and hosted object uploads reserve capacity before blob upload. The blob effect occurs outside the metadata transaction. | Actual Node AccountController and SQLite transaction inspection during blob upload. |
| Metadata, index and quota release must commit together | Content pointer, SQL catalog, usage and reservation removal share the same metadata/SQLite transaction. | Injected failure after index update and reservation removal rolls all local state back; the uncommitted blob is deleted. |
| Orphan deletion failure must not free unaccounted capacity | The reservation stays charged until cleanup succeeds. Expired leases retry through account alarms. | Failed bucket delete retains reserved bytes; recovery cleans the orphan. |
| A failed first cleanup page can starve later records | Cleanup persists a cursor and rotates through bounded pages. | Thirty-two permanently failing early keys do not block eight healthy later orphans. |
| Stale reservations must not commit indefinitely | A twenty-minute lease must still be valid at commit. | Commit at its exact expiration fails with rollback. |
| Downgrade must preserve access to committed data | Over-limit storage blocks growth, while reads, smaller replacements and deletion remain available. | Actual hosted-object read/shrink/delete tests with a simulated full shared inbox. |
| Paging cursors must encode Unicode correctly | Cursors encode JSON as UTF-8 before base64url and bind their owner/resource/filter scope. | Emoji/CJK object keys and a 450-row inbox with equal timestamps page without duplicates; changed owner/filter/resource cursors fail. |
| Sparse quarantine views need a useful SQL index | A quarantine/time index accompanies owner, collection and unread indexes. | Source review; combined-filter cost remains a load-test consideration. |
| Unauthenticated webhook payloads must not allocate account state | Bounded raw-body signature verification precedes identity lookup and account shard access. Only active recipients proceed. | Actual SDK signatures through the portable HTTP adapter; changed body causes no directory or account lookup. |
| Browser fields must not choose the billed identity | Checkout/portal require the owner session, exact origin and CSRF. The server supplies the authenticated UUID. | Actual Node HTTP routes reject missing session, foreign origin, wrong CSRF and wrong method; forged owner metadata cannot change the chosen UUID. |
| A failed local atomic rename must not leak temporary data | FileBucket removes its untracked temporary file when writing, syncing or renaming fails. | Actual filesystem rename conflict leaves no temporary file. |
| Cold-account alarms must not scan or serialize all account records | Alarm reads bounded message/resource pages. Accounts beyond the legacy snapshot bound retain durable SQLite metadata in an explicit indexed mode. | A 2005-message account performs only bounded prefix reads, retains its usage/content catalog, and reschedules maintenance. |
| Deferred garbage must not delete a current replacement | Garbage records own the superseded immutable blob reference and survive failed deletion. Cleanup rotates through bounded pages. | A replaced hosted object keeps its current bytes while the old reference retries and is removed. |
| Removing a hosted resource must not orphan charged content | Nonempty hosted resources reject removal until their objects are deleted. | Actual hosted resource remains accessible after a rejected disconnect and can be removed once emptied. |
Provider authority
The integration verifies the installed maintained @polar-sh/sdk 1.0.2 API directly and uses 2026-10 snake_case request/response fields. Its offline tests sign with standardwebhooks 1.1.1 and verify with the actual SDK. Catalog validation requires two distinct, non-archived annual USD fixed-price products in the same organization: Plus 500 cents and Pro 3000 cents. The explicit verifyBillingCatalog operator preflight reads both products before app enablement and does not write account state or create a checkout; the offline test verifies this separation. Free is 500,000,000 decimal bytes; Plus and Pro are 5,000,000,000 and 100,000,000,000 bytes.
Notifications trigger fresh provider customer/subscription reads. Payload plans, redirect parameters, email and metadata do not grant capacity. Customer external ID, organization and subscription ownership are checked again during reconciliation. Durable event IDs/hashes prevent duplicate delivery effects; an out-of-order notification cannot restore a historical payload grant. A per-account reconciliation revision guards against overlapping fetches applying an older result.
Local cases cover active, period-end cancellation, revocation/termination, expiry, incomplete, paused, trialing, unpaid and past-due subscriptions. Past due retains only a previously verified paid deadline and never extends failed renewal. Provider errors preserve that deadline and remain retryable. No test establishes actual refund/dispute behavior, checkout settlement, renewal delivery or production provider conformance; these remain operator gates in billing deployment.
Verification record and outstanding limits
node --test tests/billing.test.mjs tests/scaling-audit.test.mjs passed 32 tests: 14 billing tests and 18 storage/HTTP audit tests after the findings above were reconciled. The subsequent full npm test run executed 172 tests: 169 passed and three search-integration tests failed. It exposed an undefined HTTP execution-context identifier after committed message ingress, stale derived item catalogs being treated as current search authority after source deletion, and a shelved-account alarm consuming an upsert whose authoritative source was unavailable. These findings were sent to the coordinator for correction; this report does not record a final full-suite pass yet. The coordinator must record the final full-suite, Worker and browser results after all changes settle.
Coordinator follow-up: those integration findings were corrected and the subsequent full suite passed 176/176 tests; actual Worker integration passed16/16, UI state checks7/7, DOM smoke and the rebuilt stable-assets Chrome suite21/21 passed. The Worker dry run passed. These are local verification results, not live Polar conformance or production scaling evidence. Node's built-in SQLite emitted its normal experimental-feature warning.
Final source review confirmed default Node environment forwarding for BILLING_ENABLED, POLAR_SERVER, both product IDs, the access token and webhook secret, with billing disabled and sandbox selected by default. The Node package requires Node 24 or later to match the maintained SDK. No secret is returned by the billing status route.
Remaining production limits include live sandbox/provider lifecycle checks, Worker transaction/SQL behavior under the final bundle, browser meter/paging verification, load and storage-operation cost measurements, shared-worker/Node capacity, filtered-query worst cases, existing-account index migration throughput, long-term receipt/journal retention, large-account cold archival policy, notification/lifecycle policy and actual release approvals. SQL keyset pages and bounded per-account work improve local behavior; they do not prove million-account deployment capacity.