feat(sdk): build bounded, typed store reads for ctx.db

[nickruigrok]

First of five stacked PRs for GRA-243 (bounded typed queries over business stores).

What

The reading half of ctx.db (spec 9.2), as SDK types and a pure builder, exported on the new subpath @grasp-os/sdk/database (databaseReader, DatabaseReader, Doc, QueryDefinitionError):

• Reads: get(table, id, { expectedRevision? }) and query(table), typed by the App's schema (Doc, Id, index names and their field tuples).
• Modifiers: withIndex(name, range?) (initializer only), filter (repeatable; chained filters sit side by side under one and) and order (once, enforced in types and at runtime).
• Terminals: take(0..100), first, unique, count, collect, paginate({ pageSize, cursor }) (cursor at most 4,096 characters) and aggregate (sum/min/max over declared numeric fields only).
• Index ranges: equality on an index prefix, then a lower and/or upper bound on the next field. Checked by the types and at runtime; a range belongs to the index it was built for.
• Filters: Baseflare's structured grammar (eq, neq, gt, gte, lt, lte, in, exists, AND, OR, NOT), turned into one tree. in lists are copied. Empty conditions and empty AND/OR are refused, and so is null on fields that can't hold it.
• Page contract: paginationOptionsValidator and paginationResultValidator on the SDK root. The two strict page shapes keep the cursor and hasMore consistent.

A query is an immutable value. Nothing is read until a terminal is called, and the builder only produces a versioned descriptor (descriptorVersion: 1) for an executor the trusted host supplies. A descriptor never carries SQL, physical IDs, owners or roles.

The descriptor's shapes and structural checks are in @grasp-os/shared/store-reads, which has no Zod, so App bundles don't carry it. The host's Zod schema is @grasp-os/shared/store-queries (queryRequestSchema, getRequestSchema, readRequestSchema, with the TS types tied by satisfies).

• It checks a filter's depth (8), nodes (64) and in lists (100) iteratively, before any recursive parse, so deep or wide input is refused without overflowing the stack or the clock.
• It caps the values a query binds at 64 across range and filter (queryMaxBoundValues; an in counts once, and null and exists bind nothing). That keeps a store's statement, with the owner and a cursor's seek, under the Durable Object SQLite limit of 100 parameters.
• It checks a range's length before reading its bounds, then its shape: equalities first, each on a field of its own, then at most a lower and an upper bound on one more field, nothing after an upper bound, and at most 17 bounds (from the shared indexMaxFields).

Semantics (D3 as completed on GRA-243)

Conditions are two-valued:

• comparisons and neq match values only, and neq: null matches any value;
• eq: null and in containing null match an explicit null only;
• exists: false matches a field left out only;
• NOT is plain negation, so it keeps records whose field is left out;
• range bounds match values only.

These are documented on FilterNode, RangeBound, FieldCondition and IndexRangeBuilder, with examples. The host emitter is in #388.

Boundaries

• GRA-244 builds ctx.db from databaseReader(schema, execute) and the host-side reader in PR 5.
• The store executes descriptors in PR 3.

Tests

• packages/sdk/test/database.test.ts (workerd): descriptors are built at the terminal, are immutable, and pass the host schema; 12 chained filters stay flat; in is copied; every refusal happens before anything is read (unknown table or index, range order or shape, a range from another index, null on non-nullable fields, empty conditions, ordering twice including order → filter → order, out-of-bounds terminals and cursors, count with a field, managed aggregate fields, malformed get options); the page contract.
• packages/shared/test/store-queries.test.ts: unknown keys and versions, non-identifier names, malformed ranges, oversized and empty filter parts, a 100,000-deep filter refused without throwing, a 262,144-wide filter refused in under a second, out-of-bounds terminals, the read request union, a 1,000,000-bound range refused by length, and the 64-value budget.
• packages/sdk/test/database.test-d.ts: type fixtures reject wrong tables, IDs from another table, wrong indexes and range order, bounds after an upper bound, null bounds, wrong field types, non-scalar filter fields, predicates, take(101), pageSize: 500, all and iteration, ordering twice, and managed or non-numeric aggregate fields.
• Results: vp check is clean; vp test on these suites plus the schema and manifest suites passes 145 tests (the ids and audit-log suites included).

[nickruigrok]

@greptileai review

[greptile-apps]

Confidence Score: 5/5

[High impact] The PR appears safe to merge; no new blocking issue was found.

Summary

Adds bounded, schema-typed reads through @grasp-os/sdk/database, shared request checks, and page validators.

• Typed database reads send bounded requests to the host.
• The host checks bounded, versioned read descriptors.
• Page requests and results share one strict contract.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[App code] --> B[Build immutable query]
  B --> C[Call bounded terminal]
  C --> D[Copy descriptor]
  D --> E[Host-supplied executor]
  E --> F[Host checks request and access]

Loading

_{Reviews (2) · Last reviewed commit: "fix(sdk): bind ranges to their reader's ..." · Reviewed by Greptile}

[nickruigrok]

@greptileai review