Skip to content

fix(shard-engine): string gt() under-invalidation + close transaction-meter gaps - #243

Merged
prisis merged 5 commits into
alphafrom
advisor/206-207-shardcore
Aug 1, 2026
Merged

prisis merged 5 commits into
alphafrom
advisor/206-207-shardcore

Conversation

@prisis

@prisis prisis commented Aug 1, 2026 •

Copy link
Copy Markdown
Member

Range-precise invalidation had a correctness bug: an exclusive lower bound (q.gt(field, value)) on a string index column excluded rows whose value extends the bound as a prefix ("Alice" for bound "Al"), so a write to such a row never re-ran the live query — the subscriber went permanently stale. Fixed the key encoding (at + KEY_SEPARATOR + KEY_HIGH), wired the ranges thunk into runCachedQuery (the range-index machinery was dead in production), and pre-grouped the touch check.

Also closed two transaction-meter gaps: deleteAll (the erasure primitive) was truncated by the per-tx write meter → meter-exempt via a scoped runUnmetered seam; alarm-driven writes (external-source ingest, TTL sweep) were unmetered → mint a fresh tracker per work item, treating a limit hit as batch-full (park cursor + re-arm); and the dispatch-race on the shared headroom field fixed by value-threading. Incidentally metered a pre-existing unmetered runShardBulkDelete.

Verified: shard-engine 843, do 505, codegen 975 (goldens byte-identical except the intended headroom lines) + lint:types/eslint clean; full build:packages green.

⚠ Touches codegen/emit.ts + a golden — sequence at merge vs #(208/232/225/226 codegen touches).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes

    • Improved reactive cache invalidation for range-based queries.
    • Fixed range matching for exclusive boundaries and prefix keys.
    • External data polling now resumes safely after transaction-limit warnings without losing progress.
    • TTL cleanup continues across scheduled cycles when transaction limits are reached.
  • Performance & Reliability

    • Improved handling of large delete-all operations.
    • Enhanced transaction budgeting across reads, writes, RPCs, and background tasks.
    • Added tracing support to improve operational visibility.

prisis and others added 3 commits July 31, 2026 23:25
…ound

An exclusive lower bound (gt) on a string index column excluded rows whose
value extended the bound as a prefix (e.g. "Alice" against bound "Al"),
because the naive at+KEY_HIGH encoding sorted above every such extension.
A write to one of those rows never invalidated the query that read it,
leaving the subscriber permanently stale. Encode the exclusive lower bound
as at+KEY_SEPARATOR+KEY_HIGH instead, which excludes only keys equal to (or
a compound-trailing extension of) the bound while admitting prefix
extensions.

Also wires the range-precise invalidation machinery into the reactive
query cache: runCachedQuery now collects a ReadFootprint alongside the
dependency tracker and passes its ranges to ReactiveCache.run, so a cached
query narrowed to one index slice survives writes to a disjoint slice on
the same table instead of degrading to a whole-table dependency. And
keysTouchRanges groups write-side index keys by index once per call
instead of re-filtering per range.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
ctx.db.deleteAll(table) is documented as the deliberately-uncapped erasure
primitive, but every row it deletes routed through the same metered
onWrite hook as an ordinary mutation — so a table over 50k rows threw
TRANSACTION_LIMIT_EXCEEDED partway through, leaving the "table is now
empty" guarantee (the GDPR/tenant-erasure use case) broken.

Add a closure-scoped meterExempt flag and runUnmetered() helper, private to
createShardCtxDb and not exported, so user code can never reach it — only
deleteAll's own implementation calls it. Scoped to the writer instance
(fresh per dispatch) rather than a bare top-level flag, so it can't leak
across a concurrent dispatch on a different writer. Every headroom charge
site (onRead/onWrite hooks, findMany's full-scan charge, the .global()
write branches, and the fluent query() reader's row meter) now respects
the flag, since deleteAll's per-row delete pipeline shares those hooks
with whatever triggers fire as a side effect of erasing that row.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Two more per-transaction-meter gaps, closing the codegen/emit.ts coupling
found while implementing this: alarm-driven writes had no meter at all, and
concurrent /rpc dispatches raced a shared instance field for the one they did
have.

External-source ingest (pollExternalSources) and TTL sweeps
(deleteRowThroughWriter, used by pollTtlSweeps) run from the alarm handler,
with no /rpc dispatch in flight and therefore no active
TransactionHeadroomTracker — an unbounded write path that bypassed the
meter's own reason for existing. Both now mint a fresh tracker per alarm work
item (per sourced table's tick; per TTL sweep pass) via a new
ShardDO#alarmHeadroom(), threaded by value into the writer. Hitting the limit
mid-batch is treated as "batch full", not a genuine failure: it's logged at
warn (not recordExternalSourceError/recordShapeError, which would surface as
one), and the table/sweep is left "due" so the shared poll alarm re-arms
promptly through its existing due-now floor rather than a fresh setAlarm(now)
or the normal multi-second/TTL_SWEEP_INTERVAL_MS cadence. Neither ingest mode
gets an invented resumable cursor for the case that has none (full-pull mode,
and an incremental source's own occasional full-pull/reconcile sweep) — a
retry just redoes the whole pull, safe (idempotent upsert) if wasteful; the
incremental steady-state case already has one (the durable watermark) and
needed no change.

Separately: this.currentTransactionHeadroom is a single instance field set
at the top of a /rpc dispatch and cleared, unconditionally, in its finally.
Two overlapping dispatches on one DO could race it — one dispatch's finally
clearing the field while a sibling, still mid-handler, later builds ctx.db
off the (by-then-cleared) shared field and runs unmetered. handleRpc now
takes an optional by-value headroom parameter; the /rpc dispatch captures its
tracker in a local and passes it straight through to buildCtx, so a
dispatch's own metering never depends on the shared field still holding the
right value later in its execution. The field's finally-clear is also
identity-guarded (only clear it if it still points at the tracker THIS
dispatch set) as a second layer, protecting the two callers that dispatch
without minting their own tracker (dispatchLifecycle, handleRunAs) from a
sibling dispatch's clear.

Regenerated the codegen golden fixture (packages/codegen/__tests__/fixtures/simple)
via capture-expected.ts — the diff is exactly the new headroom parameters and
their threading, byte-identical otherwise.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
@netlify

netlify Bot commented Aug 1, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for lunorash ready!

Name Link
🔨 Latest commit 49f668f
🔍 Latest deploy log https://app.netlify.com/projects/lunorash/deploys/6a6daec3d8ef7f0008c55522
😎 Deploy Preview https://deploy-preview-243--lunorash.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions

github-actions Bot commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Thank you for following the naming conventions! 🙏

@coderabbitai

coderabbitai Bot commented Aug 1, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 65637727-36ba-4c56-ac22-a0a4c52d7fbc

📥 Commits

Reviewing files that changed from the base of the PR and between ca89afb and 49f668f.

⛔ Files ignored due to path filters (1)
  • packages/do/__tests__/reactive-cache.integration.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
📒 Files selected for processing (2)
  • packages/do/src/shard-do.ts
  • packages/shard-engine/src/ctx-db.ts
🚧 Files skipped from review as they are similar to previous changes (2)
  • packages/shard-engine/src/ctx-db.ts
  • packages/do/src/shard-do.ts

Walkthrough

The PR adds transaction-headroom propagation and resumable alarm work, supports unmetered deleteAll, and adds read-range tracking for reactive-cache invalidation with corrected range matching.

Changes

Transaction headroom and bounded work

Layer / File(s) Summary
Dispatch headroom propagation
packages/codegen/src/emit.ts, packages/do/src/shard-do.ts
RPC and writer deletion paths accept explicit transaction-headroom trackers. Dispatch cleanup preserves tracker identity.
Alarm polling and TTL budgets
packages/codegen/src/emit.ts, packages/do/src/shard-do.ts
External-source polls and TTL sweeps use scoped budgets. Transaction-limit errors preserve state and schedule resumable retries.
Unmetered delete-all execution
packages/shard-engine/src/ctx-db.ts
deleteAll suppresses read and write headroom charges during its chunked deletion scope. Normal write reporting remains active.

Range-aware reactive-cache invalidation

Layer / File(s) Summary
Cached-query read footprint capture
packages/do/src/shard-do.ts
Cached queries capture database read ranges, restore nested footprint state, and pass flattened ranges to ReactiveCache.
Range matching and cache traversal
packages/shard-engine/src/read-write-set.ts, packages/shard-engine/src/reactive-cache.ts
Exclusive lower bounds preserve prefix extensions. Row keys are grouped by index, and live range-map iteration handles removed entries.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Alarm
  participant ShardDO
  participant Writer
  Alarm->>ShardDO: start source poll or TTL sweep
  ShardDO->>Writer: execute work with transaction headroom
  Writer-->>ShardDO: complete or report TRANSACTION_LIMIT_EXCEEDED
  ShardDO-->>Alarm: preserve state and schedule retry
Loading
sequenceDiagram
  participant Query
  participant CtxDbHooks
  participant ReactiveCache
  Query->>CtxDbHooks: capture read and index ranges
  CtxDbHooks-->>Query: update current read footprint
  Query->>ReactiveCache: run with flattened ranges
  ReactiveCache-->>Query: return cached or computed result
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description provides a strong summary and verification details but omits most required template sections, including linked issues, checklist, and the CLA statement. Add the required template sections, complete the checklist and linked issues fields, and include the exact Contributor License Agreement statement when applicable.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the string range invalidation fix and transaction-meter gap closures.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch advisor/206-207-shardcore

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Thank you for confirming the Contributor License Agreement! 🙏

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
packages/do/src/shard-do.ts (1)

3244-3271: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Keep range reads off currentReadFootprint.onRead.

query() uses buildReader(...) and reports a range only through onReadRange, while predicated findMany() still reports via onRead(tableName) before row stamps. Calling getCtxDbReadHook() as onRead adds normal query ranges to unnarrowable, deleting them from footprint.ranges(). That makes cached query invalidation non-range-precise again. Wire onReadRange through getCtxDbReadRangeHook() only, and keep this onRead path scoped to scan/full-table reads.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/do/src/shard-do.ts` around lines 3244 - 3271, Update
getCtxDbReadHook so it no longer calls currentReadFootprint.onRead for ordinary
reads, preserving that hook only for scan/full-table reads as identified by
SCAN_DEP. Route range-read reporting exclusively through getCtxDbReadRangeHook
and its onReadRange wiring, while retaining currentTracker recording and
existing scan attribution behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/shard-engine/src/ctx-db.ts`:
- Around line 1708-1719: Replace the writer-wide mutable meterExempt state and
runUnmetered wrapper with an internal metering context propagated through the
deleteAll read, delete, and trigger chain. Ensure only the deleteAll operation’s
own charges are suppressed, while sibling operations started during awaited
findMany or delete calls retain normal headroom metering.

---

Outside diff comments:
In `@packages/do/src/shard-do.ts`:
- Around line 3244-3271: Update getCtxDbReadHook so it no longer calls
currentReadFootprint.onRead for ordinary reads, preserving that hook only for
scan/full-table reads as identified by SCAN_DEP. Route range-read reporting
exclusively through getCtxDbReadRangeHook and its onReadRange wiring, while
retaining currentTracker recording and existing scan attribution behavior.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: feff1ef6-8bd0-4a07-ada6-8b4ad50a76c5

📥 Commits

Reviewing files that changed from the base of the PR and between 36421ad and ca89afb.

⛔ Files ignored due to path filters (8)
  • packages/codegen/__tests__/emit-alarm-headroom.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/codegen/__tests__/emit-external-source.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/codegen/__tests__/fixtures/simple/expected/_generated/shard.ts is excluded by !**/_generated/**, !**/__tests__/** and included by packages/**
  • packages/do/__tests__/dispatch-headroom-race.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/do/__tests__/reactive-cache.integration.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/do/__tests__/ttl-sweep.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/shard-engine/__tests__/ctx-db.erase.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
  • packages/shard-engine/__tests__/read-write-set.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
📒 Files selected for processing (5)
  • packages/codegen/src/emit.ts
  • packages/do/src/shard-do.ts
  • packages/shard-engine/src/ctx-db.ts
  • packages/shard-engine/src/reactive-cache.ts
  • packages/shard-engine/src/read-write-set.ts

Comment thread packages/shard-engine/src/ctx-db.ts Resolved
@codspeed

codspeed Bot commented Aug 1, 2026 •

Copy link
Copy Markdown

Merging this PR will degrade performance by 3.79%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
❌ 2 regressed benchmarks
✅ 149 untouched benchmarks
⏩ 109 skipped benchmarks1

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ flat 3 primitives (the notify.send attribute shape) 55.7 µs 62.5 µs -10.95%
❌ 1 after-insert no-op trigger 394.5 µs 439.3 µs -10.2%
⚡ count, no attributes 64.2 µs 57.6 µs +11.37%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing advisor/206-207-shardcore (49f668f) with alpha (a540991)2

Open in CodSpeed

Footnotes

  1. 109 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

  2. No successful run was found on alpha (d9791ea) during the generation of this report, so a540991 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

…range read with get(id)

runCachedQuery derived cache deps from the dependency tracker alone, while
ranges came from the read footprint. A table read via a provable range
AND a by-id get() ended up with deps `{table:id}` and an empty range set
(the footprint marks a by-id read unnarrowable, so ranges() drops the
table entirely) — an insert of a new row into that range then matched
neither the id dep nor any range, and the stale cache entry survived.

Mirror executeSubscription's whole-table fallback (footprint.tables minus
what ranges() narrowed): after run() resolves, stamp a whole-table
SCAN_DEP for every footprint table ranges() did not narrow, unioned into
the same tracker deps set the cache indexes by. A table narrowed by
ranges() alone is left untouched, so range-precise invalidation for the
range-only case is unaffected.

Also correct an inaccurate ctx-db.ts comment: the deleteAll meter
exemption is writer-wide for its whole await chain, not scoped to that
writer's own sequential work — a concurrently-awaited sibling write on
the same writer is exempted too. Documented as a known, low-severity
limitation; no behavior change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@prisis
prisis merged commit 55c5323 into alpha Aug 1, 2026
43 of 46 checks passed
@prisis
prisis deleted the advisor/206-207-shardcore branch August 1, 2026 10:56
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using our GitHub Discussions tab for questions.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Sep 8, 2026

This branch was previously deployed

1 inactive deployment
benchmarks — 49f668fe Deployed Aug 1, 2026 by prisis via Benchmarks #1302
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant