@cavelang/query 0.27.14 → 0.29.0

package/Authors.md

@@ -0,0 +1,5 @@
+# Authors
+
+By adding their name to this file, all listed authors confirm they have copyright over their contributions to this project and are waiving these rights, placing their work in the public domain in accordance with the CC0 1.0 Universal Public Domain Dedication.
+
+- Mirek Rusin (Switzerland)

package/License.md

@@ -0,0 +1,6 @@
+# CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+
+To the extent possible under law, the authors listed in [Authors.md](./Authors.md) have waived all copyright and related or neighboring rights to this software and associated documentation files (the "Software").
+
+For more information, please see:
+https://creativecommons.org/publicdomain/zero/1.0/

package/README.md

@@ -3,9 +3,28 @@
 CAVE-Q — the graph-pattern query layer (spec §12), compiled to SQL over an
 open `@cavelang/store`.
 
+Current-belief selection, transaction boundaries, and alias closure come from
+the store's public `QuerySql` primitives; CAVE-Q adds pattern joins, filters,
+resolution, transitive traversal, and result binding without redefining those
+shared semantics.
+
+`query()`/`match()` expose storage rows for in-process reasoning engines. For
+public JSON and durable integrations, use `queryRecords()`: every result is a
+`cave.query-match/v1` carrying bindings plus optional `cave.claim/v1` claim or
+transitive support records. `Record.decode` verifies the version and all
+nested claim records.
+
+For interactive or remote reads, `page()` returns a bounded
+`cave.query-page/v1` envelope. The first request freezes the maximum visible
+transaction; pass its opaque `next` cursor back with the same pattern,
+options, and limit to continue. Appends made between pages are therefore
+excluded, while a new first page sees them. The default page size is 100 and
+the maximum is 1,000. `query()` and `queryRecords()` remain unbounded for
+in-process callers that explicitly want the complete result.
+
 ```ts
 import { open } from '@cavelang/store'
-import { query } from '@cavelang/query'
+import { page, query } from '@cavelang/query'
 
 const store = open('knowledge.db')
 query(store, '?x USES jwt')
@@ -19,7 +38,12 @@ query(store, 'terrier EXTENDS+ animal') // transitive
 
 query(store, '?x USES postgres', { aliases: true }) // + rows about aliased names (§13.6)
 query(store, 'server IS compromised', { asOf: '2026-01-15' }) // belief state at a past moment (§12.3)
+query(store, 'mill/wage IS', { at: '1962' }) // valid-time filtering + trajectory interpolation (§32.4)
 query(store, 'service HAS owner: ?who', { resolve: true }) // §26 winners only — one row per contested fact
+
+const first = page(store, '?x USES jwt', { limit: 50 })
+const second = first.next === undefined ? undefined :
+  page(store, '?x USES jwt', { limit: 50, cursor: first.next })
 ```
 
 ## Pattern language (§12.1)
@@ -35,8 +59,18 @@ query(store, 'service HAS owner: ?who', { resolve: true }) // §26 winners only
 - **Inverse verbs** are valid: `?x PART-OF monorepo` compiles to
   `verb = 'CONTAINS' AND subject = 'monorepo'` with `?x` binding on the
   object side — the same physical query as the forward pattern.
+- **Lifecycle spellings** are interchangeable after their declaration:
+  with `WORKS-AT RENAMED-TO EMPLOYED-BY`, patterns using either name compile
+  to the stable `WORKS-AT` storage verb. `asOf` reconstructs the registry at
+  the same boundary, so the replacement is unknown before its declaration.
 - `VERB+` is transitive (one or more hops), compiled to a recursive CTE
-  over current, positive, non-retracted edges, depth-capped at 32.
+  over current, positive, non-retracted edges. Reachable endpoint pairs are
+  deduplicated as the recursion runs, so cycles terminate at a finite fixed
+  point and paths are not silently truncated at a hop limit.
+  A concrete subject seeds forward recursion; when only the object is
+  concrete, recursion runs backwards from it. Fully unbound patterns retain
+  the complete all-pairs closure. Supporting edge ids propagate through the
+  same seeded direction when `{ support: true }` is requested.
   Transitive works through inverses too (`packages/api PART-OF+ ?c` walks
   `CONTAINS` upward from the object side).
 
@@ -47,13 +81,15 @@ WHERE conf >= 0.8        (also accepts 80%)
 WHERE tag = security     (bare key matches any value; topic:auth is exact)
 WHERE context = production
 WHERE value > 1000 req/s (numeric column; unit equality when given)
-WHERE tx > 2026-01-01    (dates are whole-day UTC intervals)
+WHERE tx > 2026-01-01    (date-like values are whole UTC periods)
+WHERE tx <= 2026-01-01T12:00:00 (offset-less timestamps mean UTC)
 ```
 
-`tx` filters compile a date to the interval `[day-start, next-day-start)`
-in UUIDv7 space: `=` means "recorded that day", `<=` includes the boundary
-day that `<` excludes, and `>` starts the day after. A timestamp value
-covers one second.
+`tx` filters compile a date-like value to its UTC period in UUIDv7 space:
+`=` means "recorded in that period", `<=` includes the boundary period that
+`<` excludes, and `>` starts after it. A timestamp value covers one second.
+An explicit `Z` or numeric offset is honored; a timestamp without either is
+UTC, so `2026-01-01T12:00:00` equals `2026-01-01T12:00:00Z` on every host.
 
 ## Semantics
 
@@ -67,6 +103,11 @@ covers one second.
   (`latency IS 30ms` the pattern finds `latency IS 30ms` the claim).
 - A repeated variable forces equality in transitive patterns too:
   `?x EXTENDS+ ?x` finds nodes on cycles, not every reachable pair.
+- Transitive recursion has no CAVE hop limit and never returns a silently
+  partial closure. It reaches a fixed point after at most the finite set of
+  endpoint pairs (quadratic in the number of participating entities); if the
+  SQLite runtime cannot complete that work, the query fails instead of
+  presenting a truncated result as complete.
 - Transitive patterns support endpoint slots only; tag/context/WHERE
   filters on them are rejected rather than silently ignored.
 - **`{ support: true }` attaches supporting edge rows to transitive
@@ -82,15 +123,21 @@ covers one second.
   alias-equal, transitive hops cross alias links — while bindings and rows
   keep stored names untouched (union-of-rows, never silent merging). The
   closure always reads current beliefs, even under `{ all: true }`.
-  Values, attribute names and verbs are not entities and never resolve.
+  Values, attribute names and verbs are not entities. Verbs resolve through
+  their separate `RENAMED-TO` lifecycle registry (§5.8).
 - **`{ asOf }` resolves beliefs as of a past moment** (§12.3): only rows
   recorded up to the boundary participate, then resolution proceeds as
   usual — so a claim retracted later is still believed at the boundary,
-  and one first recorded later is unknown. The boundary is a date (whole
-  UTC day included), a timestamp (whole second included), or a
+  and one first recorded later is unknown. The boundary is a date-like value
+  (whole UTC period included), a timestamp (whole second included), or a
   transaction id (that append included). The alias closure and transitive
   hops reconstruct at the same instant; `{ all: true }` composes as
   full-history-up-to-the-boundary.
+- **`{ at }` anchors valid time** (§32.4): timeless claims always remain
+  visible; date-like contexts and ranges must cover the selected instant; and
+  a trajectory value such as `200 -> 900 PLN/mo @1950..1974` is returned with
+  its exact interpolated value. It composes with `asOf`: transaction time
+  selects what was believed, while valid time selects when that belief applies.
 - **`{ resolve: true }` matches resolved winners only** (§26): coexisting
   series about one fact — §9.5 actor stamps, content sources, opposite
   polarity — collapse to the row the resolution policy picks (precedence
@@ -100,19 +147,37 @@ covers one second.
   through the closure) and `asOf` (candidates and the in-band policy
   declarations reconstruct at the boundary); incompatible with
   `{ all: true }`, which asks for the unresolved history.
+- **Pagination is deterministic and transaction-snapshot stable.** SQL applies
+  `LIMIT`/`OFFSET` after the query's stable transaction or endpoint ordering,
+  and every continuation pins `asOf` to the first page's maximum transaction.
+  Cursors are scoped to the exact pattern, options, and page size. Valid-time
+  coverage and exact numeric approximation checks run after row selection, so
+  those pages consume bounded one-row SQL windows to advance past rejected
+  rows without skipping the next match. A heavily filtered page can therefore
+  contain fewer than its requested limit (including zero) while still carrying
+  `next`; following it continues from the bounded scan frontier.
 
 ## Tests
 
 ```
 pnpm --filter @cavelang/query test
+pnpm --filter @cavelang/query bench:transitive
 ```
 
 Every §12.1 example pattern and every §12.2 filter runs against a live
 in-memory store, including inverse and transitive-inverse cases,
-current-vs-history semantics, negated patterns, the §13.6 alias
+current-vs-history semantics, negated patterns, long paths across the former
+32-hop boundary, cycle-safe closure, the §13.6 alias
 closure (term widening, transitive hops across aliases, unmerge by
 retraction, value/attribute exemption), §12.3 as-of resolution
 (tx/date/timestamp boundaries, later retraction, as-of alias closure
 and transitive edges) and §26 winners-only matching (ingest re-runs vs
 human corrections, polarity suppression, reliability steering,
 resolved transitive paths, composition with aliases and as-of).
+Valid-time coverage, bitemporal composition, and trajectory interpolation are
+covered by the temporal query tests.
+
+The deterministic transitive benchmark emits NDJSON timings and result counts
+for a chain, a branching tree, and a cycle, comparing a source-seeded query
+with the corresponding unbound all-pairs workload. Plan tests additionally
+assert forward/reverse seed shape and SQLite object-index use.

package/bench/transitive.ts

@@ -0,0 +1,42 @@
+/** Deterministic chain/branch/cycle benchmark for seeded transitive plans. */
+
+import { performance } from 'node:perf_hooks'
+import { open } from '@cavelang/store'
+import { query } from '../src/compile.ts'
+
+type Case = { readonly name: string, readonly edges: readonly string[], readonly seed: string }
+
+const cases: readonly Case[] = [
+  {
+    name: 'chain',
+    edges: Array.from({ length: 120 }, (_, index) => `n/${index} REACHES n/${index + 1}`),
+    seed: 'n/0'
+  },
+  {
+    name: 'branches',
+    edges: Array.from({ length: 127 }, (_, index) => [
+      `tree/${index} REACHES tree/${index * 2 + 1}`,
+      `tree/${index} REACHES tree/${index * 2 + 2}`
+    ]).flat(),
+    seed: 'tree/0'
+  },
+  {
+    name: 'cycle',
+    edges: Array.from({ length: 120 }, (_, index) => `ring/${index} REACHES ring/${(index + 1) % 120}`),
+    seed: 'ring/0'
+  }
+]
+
+for (const entry of cases) {
+  const store = open()
+  store.ingest(entry.edges.join('\n'))
+  const run = (input: string): { readonly ms: number, readonly matches: number } => {
+    const start = performance.now()
+    const matches = query(store, input).length
+    return { ms: Number((performance.now() - start).toFixed(3)), matches }
+  }
+  const bound = run(`${entry.seed} REACHES+ ?destination`)
+  const unbound = run('?source REACHES+ ?destination')
+  process.stdout.write(`${JSON.stringify({ scenario: entry.name, edges: entry.edges.length, bound, unbound })}\n`)
+  store.close()
+}

package/dist/bench/transitive.d.ts

@@ -0,0 +1,3 @@
+/** Deterministic chain/branch/cycle benchmark for seeded transitive plans. */
+export {};
+//# sourceMappingURL=transitive.d.ts.map

package/dist/bench/transitive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitive.d.ts","sourceRoot":"","sources":["../../bench/transitive.ts"],"names":[],"mappings":"AAAA,8EAA8E"}

package/dist/bench/transitive.js

@@ -0,0 +1,38 @@
+/** Deterministic chain/branch/cycle benchmark for seeded transitive plans. */
+import { performance } from 'node:perf_hooks';
+import { open } from '@cavelang/store';
+import { query } from "../src/compile.js";
+const cases = [
+    {
+        name: 'chain',
+        edges: Array.from({ length: 120 }, (_, index) => `n/${index} REACHES n/${index + 1}`),
+        seed: 'n/0'
+    },
+    {
+        name: 'branches',
+        edges: Array.from({ length: 127 }, (_, index) => [
+            `tree/${index} REACHES tree/${index * 2 + 1}`,
+            `tree/${index} REACHES tree/${index * 2 + 2}`
+        ]).flat(),
+        seed: 'tree/0'
+    },
+    {
+        name: 'cycle',
+        edges: Array.from({ length: 120 }, (_, index) => `ring/${index} REACHES ring/${(index + 1) % 120}`),
+        seed: 'ring/0'
+    }
+];
+for (const entry of cases) {
+    const store = open();
+    store.ingest(entry.edges.join('\n'));
+    const run = (input) => {
+        const start = performance.now();
+        const matches = query(store, input).length;
+        return { ms: Number((performance.now() - start).toFixed(3)), matches };
+    };
+    const bound = run(`${entry.seed} REACHES+ ?destination`);
+    const unbound = run('?source REACHES+ ?destination');
+    process.stdout.write(`${JSON.stringify({ scenario: entry.name, edges: entry.edges.length, bound, unbound })}\n`);
+    store.close();
+}
+//# sourceMappingURL=transitive.js.map

package/dist/bench/transitive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitive.js","sourceRoot":"","sources":["../../bench/transitive.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAIzC,MAAM,KAAK,GAAoB;IAC7B;QACE,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,cAAc,KAAK,GAAG,CAAC,EAAE,CAAC;QACrF,IAAI,EAAE,KAAK;KACZ;IACD;QACE,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;YAC/C,QAAQ,KAAK,iBAAiB,KAAK,GAAG,CAAC,GAAG,CAAC,EAAE;YAC7C,QAAQ,KAAK,iBAAiB,KAAK,GAAG,CAAC,GAAG,CAAC,EAAE;SAC9C,CAAC,CAAC,IAAI,EAAE;QACT,IAAI,EAAE,QAAQ;KACf;IACD;QACE,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,QAAQ,KAAK,iBAAiB,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC;QACnG,IAAI,EAAE,QAAQ;KACf;CACF,CAAA;AAED,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,IAAI,EAAE,CAAA;IACpB,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IACpC,MAAM,GAAG,GAAG,CAAC,KAAa,EAAqD,EAAE;QAC/E,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;QAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,CAAA;QAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAA;IACxE,CAAC,CAAA;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,wBAAwB,CAAC,CAAA;IACxD,MAAM,OAAO,GAAG,GAAG,CAAC,+BAA+B,CAAC,CAAA;IACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAA;IAChH,KAAK,CAAC,KAAK,EAAE,CAAA;AACf,CAAC"}

package/dist/src/bounded.d.ts

@@ -1,14 +1,9 @@
-import type { Store } from '@cavelang/store';
+import type { Store } from '@cavelang/store/adapter';
 import * as Compile from './compile.ts';
 import * as Pattern from './pattern.ts';
 export type { Match, Options } from './compile.ts';
-/**
- * Exact numeric attribute values are matched through normalized storage
- * columns, not their as-written spelling: `0.9B users/wk` and
- * `900M users/wk` denote the same number/unit pair. The compiler's existing
- * value filter pushes the normalized comparison into SQL; the final check
- * preserves exact unit and approximation semantics.
- */
+export type { Window } from './compile.ts';
+export declare const window: (store: Store, pattern: Pattern.t, options?: Compile.Options) => Compile.Window;
 export declare const match: (store: Store, pattern: Pattern.t, options?: Compile.Options) => Compile.Match[];
 export declare const query: (store: Store, input: string, options?: Compile.Options) => Compile.Match[];
 //# sourceMappingURL=bounded.d.ts.map

package/dist/src/bounded.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bounded.d.ts","sourceRoot":"","sources":["../../src/bounded.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAelD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAChB,OAAO,KAAK,EACZ,SAAS,OAAO,CAAC,CAAC,EAClB,UAAS,OAAO,CAAC,OAAY,KAC5B,OAAO,CAAC,KAAK,EAgCf,CAAA;AAED,eAAO,MAAM,KAAK,GAChB,OAAO,KAAK,EACZ,OAAO,MAAM,EACb,UAAS,OAAO,CAAC,OAAY,KAC5B,OAAO,CAAC,KAAK,EAC6B,CAAA"}
+{"version":3,"file":"bounded.d.ts","sourceRoot":"","sources":["../../src/bounded.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AACpD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AA4D1C,eAAO,MAAM,MAAM,GACjB,OAAO,KAAK,EACZ,SAAS,OAAO,CAAC,CAAC,EAClB,UAAS,OAAO,CAAC,OAAY,KAC5B,OAAO,CAAC,MAA0C,CAAA;AAErD,eAAO,MAAM,KAAK,GAChB,OAAO,KAAK,EACZ,SAAS,OAAO,CAAC,CAAC,EAClB,UAAS,OAAO,CAAC,OAAY,KAC5B,OAAO,CAAC,KAAK,EAA8C,CAAA;AAE9D,eAAO,MAAM,KAAK,GAChB,OAAO,KAAK,EACZ,OAAO,MAAM,EACb,UAAS,OAAO,CAAC,OAAY,KAC5B,OAAO,CAAC,KAAK,EAC6B,CAAA"}

package/dist/src/bounded.js

@@ -20,13 +20,13 @@ const storeAtBoundary = (store, options) => {
  * value filter pushes the normalized comparison into SQL; the final check
  * preserves exact unit and approximation semantics.
  */
-export const match = (store, pattern, options = {}) => {
+const execute = (store, pattern, options = {}) => {
     if (pattern.payload.kind !== 'attribute' || pattern.payload.value.kind !== 'term') {
-        return Compile.match(storeAtBoundary(store, options), pattern, options);
+        return Compile.window(storeAtBoundary(store, options), pattern, options);
     }
     const value = Value.parse(pattern.payload.value.text);
     if (value.kind !== 'number' || value.num === undefined) {
-        return Compile.match(storeAtBoundary(store, options), pattern, options);
+        return Compile.window(storeAtBoundary(store, options), pattern, options);
     }
     const expectedNum = value.num;
     const filter = {
@@ -44,14 +44,16 @@ export const match = (store, pattern, options = {}) => {
     };
     const expectedUnit = value.unit ?? null;
     const expectedApprox = value.approx ? 1 : 0;
-    return Compile.match(storeAtBoundary(store, options), normalized, options)
-        .filter(result => {
-        const row = result.row;
-        return row !== undefined &&
-            row.value_num === expectedNum &&
-            row.value_unit === expectedUnit &&
-            row.value_approx === expectedApprox;
-    });
+    const result = Compile.window(storeAtBoundary(store, options), normalized, options);
+    return { ...result, matches: result.matches.filter(match => {
+            const row = match.row;
+            return row !== undefined &&
+                row.value_num === expectedNum &&
+                row.value_unit === expectedUnit &&
+                row.value_approx === expectedApprox;
+        }) };
 };
+export const window = (store, pattern, options = {}) => execute(store, pattern, options);
+export const match = (store, pattern, options = {}) => execute(store, pattern, options).matches;
 export const query = (store, input, options = {}) => match(store, Pattern.parse(input), options);
 //# sourceMappingURL=bounded.js.map

package/dist/src/bounded.js.map

@@ -1 +1 @@
-{"version":3,"file":"bounded.js","sourceRoot":"","sources":["../../src/bounded.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bounded.js","sourceRoot":"","sources":["../../src/bounded.ts"],"names":[],"mappings":"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"}

package/dist/src/compile.d.ts

@@ -14,12 +14,19 @@
  * on the object side.
  *
  * Transitive patterns (`terrier EXTENDS+ animal`) compile to a recursive
- * CTE over current, positive, non-retracted edges (depth-capped at 32).
+ * CTE over current, positive, non-retracted edges. Recursive state is the
+ * reachable endpoint pair itself, so SQL `UNION` deduplication terminates
+ * cycles without an arbitrary semantic depth cap.
  */
-import { Row } from '@cavelang/store';
-import type { Store } from '@cavelang/store';
+import { Registry } from '@cavelang/canonical';
+import { Resolve, Row } from '@cavelang/store/adapter';
+import type { Store } from '@cavelang/store/adapter';
 import * as Pattern from './pattern.ts';
-/** One query solution: variable bindings plus the matched row (absent for transitive hops). */
+/**
+ * One storage-oriented query solution. `row`/`rows` expose SQLite-shaped
+ * data for in-process reasoning engines; use `queryRecords()` for versioned
+ * public JSON and cross-process integrations.
+ */
 export type Match = {
     readonly bindings: Readonly<Record<string, string>>;
     readonly row?: Row.t;
@@ -42,6 +49,10 @@ export type Match = {
     };
 };
 export type Options = {
+    /** Maximum rows SQLite may return. Prefer the snapshot-aware page API for continuations. */
+    readonly limit?: number;
+    /** Internal SQL offset used by the snapshot-aware page API. */
+    readonly offset?: number;
     /** Match all appended rows, not only current beliefs. */
     readonly all?: boolean;
     /**
@@ -97,6 +108,15 @@ export type Options = {
      */
     readonly support?: boolean;
 };
+type Compiled = {
+    readonly sql: string;
+    readonly params: (string | number)[];
+    readonly bind: (row: Record<string, unknown>) => Record<string, string>;
+    readonly transitive: boolean;
+    /** Variables bound to the value slot — interpolation substitutes these (spec §32.4). */
+    readonly valueVars: readonly string[];
+};
+export declare const compile: (pattern: Pattern.t, registry: Registry.t, options: Options, policy?: readonly Resolve.Entry[]) => Compiled;
 /**
  * Runs a CAVE-Q query against a store.
  *
@@ -114,5 +134,14 @@ export declare const query: (store: Store, input: string, options?: Options) =>
  * (the §24 rules engine substitutes bindings into premise patterns
  * between joins) rather than as text.
  */
+export type Window = {
+    /** Matches remaining after any valid-time evaluation. */
+    readonly matches: Match[];
+    /** Rows returned by SQLite before valid-time evaluation. */
+    readonly scanned: number;
+};
+/** Execute one SQL window and report how many pre-filter rows it consumed. */
+export declare const window: (store: Store, pattern: Pattern.t, options?: Options) => Window;
 export declare const match: (store: Store, pattern: Pattern.t, options?: Options) => Match[];
+export {};
 //# sourceMappingURL=compile.d.ts.map

package/dist/src/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAW,GAAG,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,+FAA+F;AAC/F,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IACpB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,EAAE,CAAA;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CACtF,CAAA;AAED,MAAM,MAAM,OAAO,GAAG;IACpB,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AA6XD;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,KAAK,EAAE,OAAO,MAAM,EAAE,UAAS,OAAY,KAAG,KAAK,EACnC,CAAA;AAiC7C;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,KAAK,EAAE,SAAS,OAAO,CAAC,CAAC,EAAE,UAAS,OAAY,KAAG,KAAK,EA+EpF,CAAA"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/compile.ts"],"names":[],"mappings":"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"}