@dashai/sdk 0.7.0

package/dist/query/index.d.cts

@@ -0,0 +1,800 @@
+import { b as BaseRow, P as Page, W as Where, a as Client } from '../types-BLNQ1S1C.cjs';
+
+/**
+ * Wire-format Query AST — the JSON shape the SDK serializes and the
+ * backend's query plane consumes.
+ *
+ * The AST is a **public, versioned** contract. Bumping its shape in a
+ * way that can't be transparently re-mapped on the backend is a
+ * SemVer-significant change for `@dashai/sdk`. The `v` field at the
+ * root is the single discriminator the backend uses to decide whether
+ * it can handle a given query.
+ *
+ * Coverage by phase (per `dashwise-devops-docs/plans/modules-sdk-query-v1.md`):
+ *
+ *   - **Phase 2** (this file, today): `v: 1`, `from: { kind: 'owned' }`.
+ *     Bare table reads. Subsequent slices add `where`, `select`,
+ *     `orderBy`, `limit`, `offset`, `count`, then aggregations.
+ *   - **Phase 3**: `joins[]`, `from: { kind: 'view' }`.
+ *   - **Phase 4**: `from: { kind: 'dep' }` for cross-module reads,
+ *     `joins[].to` for cross-module joins via the planner.
+ *
+ * The shape below carries all the optional fields the v1 plan promises
+ * (commented per-field with the phase they activate in). Today's
+ * translator only honors `v` + `from`; everything else is parsed +
+ * rejected with `QUERY_TOO_COMPLEX` until the corresponding phase
+ * lands. Pre-declaring the shape lets the SDK builder stub out the
+ * fluent API today without forcing an AST version bump every time we
+ * activate a field.
+ */
+/**
+ * Schema version. Bumped only on breaking changes. The backend
+ * supports `v` and `v+1` during deprecation windows so consumers can
+ * upgrade independently of the server. Add new optional fields under
+ * the current `v`; that's additive and non-breaking.
+ */
+type QueryAstVersion = 1;
+/**
+ * The root AST node. Carries the version discriminator + the table
+ * reference + every optional clause.
+ *
+ * Designed so the backend can switch on `v` first, then validate the
+ * rest. Unknown root keys are NOT silently dropped — the validator
+ * rejects with `VALIDATION_FAILED` so typos surface loudly.
+ */
+interface QueryAst {
+    /** Schema discriminator. See {@link QueryAstVersion}. */
+    v: QueryAstVersion;
+    /** The primary table for this query. */
+    from: TableRef;
+    /**
+     * Optional joins (Phase 3+). When present + the planner can't handle
+     * the join (e.g. multi-module before Phase 4), the backend rejects
+     * with `QUERY_TOO_COMPLEX`.
+     */
+    joins?: JoinNode[];
+    /**
+     * Where clause (Phase 2 slice 2). Mirrors the existing `Where<Row>`
+     * shape from `@dashai/sdk` (`./data/types.ts`) — recursive AND/OR
+     * groups + per-field operator objects. Field references inside `where`
+     * can be either bare (`'done'`, resolved against `from`) or qualified
+     * (`'tasks.done'`) when joins are present.
+     */
+    where?: WhereClause;
+    /**
+     * Group-by fields for aggregation queries (Phase 3). Field refs follow
+     * the same bare-or-qualified rule as `where`.
+     */
+    groupBy?: FieldRef[];
+    /**
+     * Aggregations keyed by output column name. Phase 3.
+     *
+     *   { totalDone: { count: '*' }, oldest: { min: 'created_at' } }
+     */
+    agg?: Record<string, AggExpr>;
+    /**
+     * Columns to select. Default = all fields of `from`. Supports `'*'`
+     * shorthand + `'as'` aliases (`'users.email as assignee_email'`).
+     * Phase 2 slice 2.
+     */
+    select?: SelectExpr[];
+    /** Order-by clauses (Phase 2 slice 2). */
+    orderBy?: OrderClause[];
+    /** Max rows to return. Default 50 (matches owned-table CRUD). */
+    limit?: number;
+    /** Row offset for pagination. Default 0. */
+    offset?: number;
+    /**
+     * Phase 3 slice 3.5 — when joins are present, return rows in
+     * SQL-style flat shape (`{ 'users.email': value }`) instead of
+     * the nested default (`row.users.email`). Ignored without joins.
+     *
+     * SDK ships the flag in slice 3.3 so authors can write
+     * `.flatten()` today; backend wiring lands in slice 3.5. Until
+     * then the backend silently ignores it (defaults to nested).
+     */
+    flatten?: boolean;
+}
+/**
+ * Discriminated union of every table source. Adding a new kind is
+ * additive (consumers using `switch (ref.kind)` must `default` to
+ * reject — covered by lint).
+ *
+ * - `owned`: a table from this module's manifest `owns.tables[]`.
+ * - `dep`:   a table from another module borrowed via `dependencies[]`
+ *            (Phase 4 — not yet routable, validator rejects).
+ * - `view`:  a manifest-declared view (Phase 5 — not yet routable).
+ */
+type TableRef = {
+    kind: 'owned';
+    slug: string;
+} | {
+    kind: 'dep';
+    module: string;
+    slug: string;
+} | {
+    kind: 'view';
+    slug: string;
+};
+/**
+ * Join node — Phase 3+. Includes `on` as an explicit field-pair map
+ * because link-field-derived defaults can't be inferred from the AST
+ * alone (they live on the manifest). The SDK builder may compute `on`
+ * from a link field at compile time and inline it here.
+ */
+interface JoinNode {
+    kind: 'inner' | 'left';
+    to: TableRef;
+    /**
+     * Map of left-side qualified field ref → right-side qualified field
+     * ref. E.g. `{ 'tasks.assignee_id': 'users.id' }`.
+     */
+    on: Record<string, string>;
+    /**
+     * Alias on result rows. Defaults to `to.slug` (or the link-field
+     * slug when the SDK's `.join('<link-slug>')` resolves through a
+     * link field). Reserved for multi-join-to-same-target (out of
+     * scope for slice 3.2; field is parsed but unused today).
+     */
+    as?: string;
+}
+/**
+ * Where clause — same shape as the existing `Where<Row>` type but
+ * untyped here (the AST is the wire format; the typed builder layer
+ * provides per-field narrowing). Top-level keys AND together; `AND`
+ * and `OR` arrays group explicitly.
+ *
+ * Examples:
+ *   { done: false }                         // shorthand for { equal: false }
+ *   { title: { contains: 'urgent' } }       // operator object
+ *   { AND: [{ done: false }, { ... }] }     // explicit AND group
+ *   { OR: [{ priority: 'high' }, ...] }     // OR group
+ *   { 'tasks.done': false }                 // qualified field ref (after joins)
+ */
+interface WhereClause {
+    AND?: WhereClause[];
+    OR?: WhereClause[];
+    [field: string]: any;
+}
+/**
+ * Field reference — either bare (`'done'`) or qualified
+ * (`'tasks.done'`). Qualified refs are only valid when the AST has
+ * joins; the validator enforces this.
+ */
+type FieldRef = string;
+/**
+ * Select expression — a field ref, the `'*'` shorthand, or a string
+ * with an `'as'` alias.
+ *
+ *   'id'
+ *   '*'
+ *   'tasks.title'
+ *   'users.email as assignee_email'
+ *
+ * Strict mode (Phase 2 OD2 from the plan): `'*'` selects all fields
+ * from `from`, NOT all fields from every joined table. Authors must
+ * explicitly opt into joined fields with `'<table>.<field>'`.
+ */
+type SelectExpr = string;
+interface OrderClause {
+    field: FieldRef;
+    dir: 'asc' | 'desc';
+}
+/**
+ * Aggregation expression. Each function takes either `'*'` (count
+ * only) or a specific field ref.
+ *
+ *   { count: '*' }
+ *   { sum: 'amount' }
+ *   { avg: 'amount' }
+ *   { min: 'created_at' }
+ *   { max: 'updated_at' }
+ */
+type AggExpr = {
+    count: '*' | FieldRef;
+} | {
+    sum: FieldRef;
+} | {
+    avg: FieldRef;
+} | {
+    min: FieldRef;
+} | {
+    max: FieldRef;
+};
+/**
+ * Runtime check that an unknown value matches the AST shape at the
+ * structural level (not field-level — that's the backend validator's
+ * job). Useful for SDK-side fail-fast checks before serializing.
+ *
+ * Intentionally permissive about optional fields: the AST grew over
+ * phases, and older consumers might lack `joins` / `agg` / etc.
+ * Strict checks happen at the backend.
+ */
+declare function isQueryAst(v: unknown): v is QueryAst;
+/**
+ * Convenience: the current schema version as a literal. Useful when
+ * constructing ASTs programmatically — keeps the magic number out of
+ * the call site.
+ */
+declare const CURRENT_QUERY_AST_VERSION: QueryAstVersion;
+
+/**
+ * Typed query builder — fluent API that compiles to a {@link QueryAst}
+ * and posts it to `POST /api/modules/<installation>/query`.
+ *
+ * Phase 2 slice 1 (this file): the minimum E2E proof — `qb.from(slug).execute()`
+ * round-trips through the backend. Future slices extend with
+ * `.where`, `.select`, `.orderBy`, `.limit`, `.offset`, `.count`, then
+ * aggregations + joins. The builder's shape is designed to fit those
+ * additions without renaming or breaking anything we ship today.
+ *
+ * Composability: every chainable method returns a new immutable
+ * `Query<Row>` — never mutates `this`. That lets authors derive
+ * sub-queries from a base:
+ *
+ * ```ts
+ * const base = qb.from('tasks');
+ * const all = await base.execute();
+ * // (future: const overdue = await base.where({ done: false }).execute())
+ * ```
+ *
+ * The factory accepts a {@link Client} (not the raw transport) so the
+ * public surface stays small + the same builder works whether the
+ * client was constructed with `createClient` or a test stub that
+ * implements the {@link Client} interface.
+ *
+ * Spec: `dashwise-devops-docs/plans/modules-sdk-query-v1.md` §6.3.
+ */
+
+/**
+ * Options passed to {@link Query.join} / {@link Query.leftJoin}.
+ *
+ * `on` is REQUIRED in slice 3.3 — link-field-derived inference lands
+ * in a follow-up. Both sides of each pair must be qualified
+ * (`<table>.<field>`) so the SDK + backend can disambiguate after
+ * joins.
+ *
+ * `as` is reserved for explicit aliasing when joining the same
+ * target multiple times (rare; not in v1).
+ */
+interface JoinOpts<K extends 'inner' | 'left'> {
+    on: Record<string, string>;
+    /** Default 'inner' for `.join()`; `.leftJoin()` hardcodes 'left'. */
+    kind?: K;
+    as?: string;
+}
+/**
+ * Result envelope for aggregation queries — distinct from
+ * {@link Page} because aggregation rows have a different shape (one
+ * row per group, with output keys matching the `agg` map keys + the
+ * `groupBy` field names) and don't carry pagination metadata in the
+ * same way.
+ *
+ * `rows` shape: `Record<string, unknown>` because the keys are
+ * dynamic (mix of group-by field names + aggregation output keys);
+ * codegen will later emit a per-query typed shape, but the runtime
+ * client stays untyped at the value level.
+ *
+ * `total` = number of result rows (one per group).
+ */
+interface QueryResult {
+    rows: Array<Record<string, unknown>>;
+    total: number;
+}
+/**
+ * Result envelope for `.explain()` (Phase 5, 2026-05-19). Returned by
+ * `POST /api/modules/:installationId/query/explain`. The backend runs
+ * Postgres `EXPLAIN (FORMAT JSON)` against the SQL it would emit —
+ * WITHOUT executing it (no `ANALYZE`, no rows materialized).
+ *
+ * Fields:
+ *   - `plan` — the full Postgres plan JSON tree (opaque object;
+ *     `plan.Plan` is the root node, `plan.Plan.Plans[]` its children).
+ *     Useful for visualization tools that want the original tree
+ *     structure preserved.
+ *   - `nodes` — depth-first flattened array of plan nodes. Each entry
+ *     carries `Node Type`, `Total Cost`, `Plan Rows`, and a `depth`
+ *     annotation (root is depth 0; children depth 1; etc.). Easier to
+ *     render in a flat table than the recursive tree.
+ *   - `estimatedCost` — `Total Cost` of the root plan node. Postgres'
+ *     planner-side cost estimate (not actual runtime). Sum of startup +
+ *     execution cost in arbitrary cost units.
+ *   - `estimatedRows` — `Plan Rows` of the root plan node. Planner's
+ *     estimate of rows the query would produce. May differ from actual
+ *     once table stats are stale (run `ANALYZE` on the underlying
+ *     tables to refresh).
+ *   - `sql` — the generated SQL string the query plane would execute.
+ *     Surfaced for debugging — useful when the plan doesn't match what
+ *     you expected and you want to see what was actually compiled.
+ *   - `paramsCount` — number of bound parameters in the SQL. Cross-check
+ *     against the WHERE / ON clauses in your AST.
+ *
+ * MVP support (backend slice 5 `.explain()` MVP):
+ *   - ✅ Joined queries (any `.join()` / `.leftJoin()` call)
+ *   - ✅ Joined aggregations (joins + `.agg()` / `.groupBy()`)
+ *   - ⏳ Bare own-table / bare cross-module dep / views / own-table agg
+ *     — reject with `EXPLAIN_NOT_SUPPORTED_YET` (typed code; the
+ *     thrown error carries `context: { fromKind, hasJoins, hasAgg }`
+ *     so callers can detect + fall back to `.execute()` for the
+ *     unsupported shapes).
+ */
+interface ExplainResult {
+    plan: unknown;
+    nodes: Array<{
+        ['Node Type']: string;
+        ['Total Cost']?: number;
+        ['Plan Rows']?: number;
+        depth: number;
+        [key: string]: unknown;
+    }>;
+    estimatedCost: number;
+    estimatedRows: number;
+    sql: string;
+    paramsCount: number;
+}
+/**
+ * Reference to a dependency module's table. Lands with Phase 4 slice
+ * 4.1b (the SDK side of the cross-module query plane). The backend
+ * routes these through {@link DepsRuntimeService.listRowsForSdk} which
+ * enforces the consumer's declared-dep contract + field projection
+ * server-side.
+ *
+ * Authors typically reach this through the codegen-emitted
+ * `qb.from(deps.crm.contacts)` shape, but the literal form
+ * `qb.from({ kind: 'dep', module: 'crm', slug: 'contacts' })` is also
+ * supported for tests + AI-builder authoring.
+ */
+interface QbDepRef {
+    kind: 'dep';
+    module: string;
+    slug: string;
+}
+/**
+ * Reference to a view declared in the module's `manifest.owns.views[]`.
+ * Lands with Phase 5 slice 5.4b (the SDK side of view querying). The
+ * backend's `executeView` resolves the view at runtime — AND-merges
+ * the view's static WHERE with the caller's, applies the view's
+ * default orderBy when caller omits one, and recurses through
+ * `execute()` with a rewritten own-table AST.
+ *
+ * Authors typically reach this through the codegen-emitted
+ * `qb.from(qbViews.active_tasks.ref)` shape (or the more ergonomic
+ * `qbViews.active_tasks.where(...).execute()` directly), but the
+ * literal form `qb.from({ kind: 'view', slug: 'active_tasks' })`
+ * is also supported for tests + AI-builder authoring.
+ */
+interface QbViewRef {
+    kind: 'view';
+    slug: string;
+}
+/**
+ * The factory's return value. Wraps a {@link Client} + exposes a
+ * `.from()` method that binds a table source.
+ *
+ * `from()` accepts three shapes:
+ *   - a string — own-table slug (default, since Phase 2 slice 1)
+ *   - a {@link QbDepRef} — cross-module dep ref (Phase 4 slice 4.1b)
+ *   - a {@link QbViewRef} — view ref (Phase 5 slice 5.4b)
+ *
+ * A `.raw()` escape hatch is intentionally NOT in v1 per the plan.
+ */
+interface Qb {
+    /** Bind an owned-table source. Returns a chainable {@link Query}. */
+    from<Row extends BaseRow = BaseRow>(tableSlug: string): Query<Row>;
+    /** Bind a cross-module dep table source. Returns a chainable {@link Query}. */
+    from<Row extends BaseRow = BaseRow>(ref: QbDepRef): Query<Row>;
+    /** Bind a view source (declared in `manifest.owns.views[]`). */
+    from<Row extends BaseRow = BaseRow>(ref: QbViewRef): Query<Row>;
+}
+/**
+ * Chainable per-query builder. Each instance is **immutable** — every
+ * modifier returns a fresh `Query<Row>` with the updated AST.
+ *
+ * Today's slice exposes `.toAst()` (introspection), `.execute()`
+ * (run + return rows), plus four chainable modifiers (`.where`,
+ * `.orderBy`, `.limit`, `.offset`). Subsequent slices add `.select`,
+ * `.count`, `.groupBy()`/`.agg()`, then `.join()` / `.leftJoin()`.
+ *
+ * Each chainable method returns a new `Query<Row>` rather than `this`
+ * so authors can derive sub-queries from a common base:
+ *
+ * ```ts
+ * const base = qb.from<TaskRow>('tasks');
+ * const open = await base.where({ done: false }).execute();
+ * const overdue = await base
+ *   .where({ done: false, due_date: { date_before: today } })
+ *   .execute();
+ * ```
+ *
+ * The first `base.execute()` returns ALL tasks (no filter); the
+ * `where()` calls produce fresh builders that don't mutate `base`.
+ */
+interface Query<Row extends BaseRow = BaseRow> {
+    /**
+     * Return the underlying AST. Useful for tests, debugging, future
+     * `.explain()` integration. The returned object is a fresh copy —
+     * mutating it does NOT affect the builder.
+     */
+    toAst(): QueryAst;
+    /**
+     * Execute the query. Posts the AST to the backend's
+     * `POST /api/modules/<installation>/query` endpoint and resolves
+     * with the standard {@link Page} envelope. Rejects with a
+     * {@link DashwiseError} on backend errors (`QUERY_AST_VERSION`,
+     * `QUERY_TOO_COMPLEX`, etc.).
+     */
+    execute(): Promise<Page<Row>>;
+    /**
+     * Phase 6 streaming (2026-05-19): stream query results row-by-row
+     * via Server-Sent Events. Returns an `AsyncIterable<Row>` — use
+     * `for await (const row of q.stream())` to consume.
+     *
+     * Backend endpoint: `POST /api/modules/<installation>/query/stream`.
+     * Each row arrives as one SSE `data:` event; a terminal `complete`
+     * event closes the iterator cleanly. Execution-phase backend
+     * errors (RBAC, RESULT_TOO_LARGE, etc.) arrive as in-band `error`
+     * events and are rethrown as `DashwiseError` from the iterator.
+     * Validation-phase errors (malformed AST) come back as standard
+     * HTTP 400 BEFORE the stream opens, so they throw immediately
+     * when you start iterating (before the first row).
+     *
+     * **AbortSignal**: pass `opts.signal` to cancel the stream. When
+     * the signal fires:
+     *   - The underlying `fetch()` is cancelled (network read aborts)
+     *   - The iterator throws an `AbortError` on the next `next()` call
+     *   - The backend's SSE writer eventually notices the broken
+     *     pipe and stops emitting events (no leak)
+     *
+     * **Backpressure**: the iterator is pull-based. Rows are buffered
+     * in the SSE chunk decoder until the consumer requests them via
+     * the for-await loop. Slow consumers naturally backpressure the
+     * network read.
+     *
+     * **MVP limitation**: in v1 the BACKEND buffers the full result
+     * before streaming (true row-by-row Postgres cursoring is a future
+     * perf slice). The SDK consumer still gets the streaming UX — rows
+     * arrive incrementally on the wire. Once the backend perf slice
+     * lands, both ends become streaming end-to-end with no SDK change.
+     *
+     * @example Basic iteration
+     *   for await (const task of qb.from<TaskRow>('tasks').stream()) {
+     *     process(task);
+     *   }
+     *
+     * @example Abort midway via AbortController
+     *   const controller = new AbortController();
+     *   setTimeout(() => controller.abort(), 5000);
+     *   try {
+     *     for await (const row of qb.from('tasks').stream({ signal: controller.signal })) {
+     *       // ... rows arrive until 5s timeout
+     *     }
+     *   } catch (e) {
+     *     if (e.name === 'AbortError') console.log('Cancelled');
+     *   }
+     */
+    stream(opts?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Row>;
+    /**
+     * Return the Postgres execution plan for this query — WITHOUT
+     * executing it (Phase 5, 2026-05-19). Posts the AST to
+     * `POST /api/modules/<installation>/query/explain`; backend wraps the
+     * SQL in `EXPLAIN (FORMAT JSON)` and returns the parsed plan tree.
+     *
+     * **MVP support matrix** (backend slice 5):
+     *   - ✅ Joined queries — works (`.join()` / `.leftJoin()`)
+     *   - ✅ Joined aggregations — works (`.join()...agg()`)
+     *   - ⏳ Bare own-table / bare dep / view / bare-agg → rejects with
+     *     `EXPLAIN_NOT_SUPPORTED_YET` (typed code; the error's `context`
+     *     payload lets you fall back to `.execute()` for unsupported
+     *     shapes)
+     *
+     * @example Joined query EXPLAIN (works today)
+     *   const plan = await qb.from<TaskRow>('tasks')
+     *     .leftJoin<UserRow>('users', { on: { 'tasks.assignee_id': 'users.id' } })
+     *     .where({ done: false })
+     *     .explain();
+     *   console.log('Cost:', plan.estimatedCost);
+     *   for (const node of plan.nodes) {
+     *     console.log('  '.repeat(node.depth) + node['Node Type']);
+     *   }
+     *
+     * @example Bare query EXPLAIN (currently throws)
+     *   try {
+     *     await qb.from<TaskRow>('tasks').explain();
+     *   } catch (e) {
+     *     // e.code === 'EXPLAIN_NOT_SUPPORTED_YET'
+     *     // Fall back to .execute() — bare-path support lands in a follow-up
+     *   }
+     */
+    explain(): Promise<ExplainResult>;
+    /**
+     * Add or replace the where clause. Same recursive `Where<Row>`
+     * shape as `client.db().list({ filter })` — top-level keys AND
+     * together; explicit `AND` / `OR` arrays group:
+     *
+     * ```ts
+     * qb.from<TaskRow>('tasks').where({ done: false })
+     * qb.from<TaskRow>('tasks').where({ title: { contains: 'urgent' } })
+     * qb.from<TaskRow>('tasks').where({
+     *   OR: [{ priority: 'high' }, { due_date: { date_before: today } }]
+     * })
+     * ```
+     *
+     * Calling `.where()` twice REPLACES the prior clause (not merge) —
+     * authors who want incremental composition should build their
+     * where-clause object explicitly. Replace-vs-merge is the same
+     * semantic as `client.db().list({ filter: ... })`.
+     */
+    where(clause: Where<Row>): Query<Row>;
+    /**
+     * Add or replace the order-by clauses. Array of `{ field, dir }`
+     * entries; sorts apply in array order (primary first).
+     *
+     * ```ts
+     * qb.from<TaskRow>('tasks').orderBy([
+     *   { field: 'priority', dir: 'desc' },
+     *   { field: 'due_date', dir: 'asc' },
+     * ])
+     * ```
+     */
+    orderBy(clauses: ReadonlyArray<OrderClause>): Query<Row>;
+    /**
+     * Set the maximum number of rows to return. Server defaults to 50
+     * when omitted; max 1000 (`RESULT_TOO_LARGE` for higher values).
+     */
+    limit(n: number): Query<Row>;
+    /**
+     * Set the row offset for pagination. Defaults to 0.
+     */
+    offset(n: number): Query<Row>;
+    /**
+     * Convenience: execute the query and return only the total row
+     * count (after `where`, before `limit`/`offset`).
+     *
+     * Equivalent to `(await this.limit(1).execute()).total` but with
+     * a clearer call site. The backend's existing list endpoint
+     * already computes `total` regardless of `limit`, so this hits
+     * the same path as `.execute()` and just extracts the number —
+     * no separate `COUNT(*)` round-trip.
+     *
+     * @example
+     *   const open = await qb.from<TaskRow>('tasks')
+     *     .where({ done: false })
+     *     .count();
+     */
+    count(): Promise<number>;
+    /**
+     * Add a same-module join (Phase 3 slice 3.3, 2026-05-19). Either
+     * INNER (when `opts.kind` is omitted or 'inner') or LEFT (use
+     * `.leftJoin()` for the read-friendly alias).
+     *
+     * `opts.on` is REQUIRED in this slice — link-field-derived `on`
+     * inference lands in a follow-up. Pass qualified refs on both
+     * sides: `{ 'tasks.assignee_id': 'users.id' }`.
+     *
+     * Returns a {@link JoinedQuery} — the surface omits write methods
+     * (`.create / .update / .delete`) + `.count` / `.agg` / `.groupBy`
+     * since the query plane's join path is read-only and not yet
+     * aggregation-aware (slice 3.2b-1 limits).
+     *
+     * Today the validator gates joins+filters+ordering as `QUERY_TOO_COMPLEX`
+     * pending slices 3.2b-2 / b-3. The SDK lets you write the call
+     * anyway so author muscle memory transfers; the backend will
+     * surface a clear "lands in slice X" error if combined too early.
+     *
+     * @example Own-table join
+     *   await qb.tasks
+     *     .join<UsersRow>('users', { on: { 'tasks.assignee_id': 'users.id' } })
+     *     .execute();
+     *
+     * @example Cross-module join (Phase 4 slice 4.2)
+     *   await qb.tasks
+     *     .leftJoin<ContactRow>(
+     *       { kind: 'dep', module: 'crm', slug: 'contacts' },
+     *       { on: { 'tasks.contact_id': 'contacts.id' } },
+     *     )
+     *     .execute();
+     */
+    join<T = unknown>(target: string | QbDepRef, opts: JoinOpts<'inner' | 'left'>): JoinedQuery<Row & Record<string, T>>;
+    /**
+     * Add a LEFT JOIN. Convenience for `.join(target, { kind: 'left', on })`.
+     * The joined object on result rows is `T | null` (matches LEFT JOIN's
+     * unmatched-row semantics).
+     *
+     * Phase 4 slice 4.2: accepts {@link QbDepRef} as the target for
+     * cross-module joins. The provider's `exposes[].operations.list`
+     * must be enabled and the consumer must declare the dep table in
+     * `dependencies[].reads[]` — same contract enforcement as the bare
+     * dep list path.
+     *
+     * @example
+     *   await qb.tasks
+     *     .leftJoin<UsersRow>('users', { on: { 'tasks.assignee_id': 'users.id' } })
+     *     .execute();
+     */
+    leftJoin<T = unknown>(target: string | QbDepRef, opts: JoinOpts<'left'>): JoinedQuery<Row & Record<string, T | null>>;
+    /**
+     * Narrow the response to only the listed field slugs. The manifest's
+     * policy projection is the security floor — `.select()` can narrow
+     * further but never widens. Slugs not in the projection (because the
+     * manifest hides them, or the slug is a typo) reject server-side with
+     * `FIELD_NOT_READABLE`.
+     *
+     * Pass `['*']` (or omit `.select()` entirely) for the full projection.
+     *
+     * **Type narrowing not yet implemented:** the returned Query is still
+     * typed as `Query<Row>` (full row type). Authors who want narrowed
+     * types cast at the call site:
+     * ```ts
+     * const result = await qb.tasks
+     *   .select(['id', 'title'])
+     *   .execute() as unknown as Page<Pick<TasksRow, 'id' | 'title'>>;
+     * ```
+     * A future TS exercise (Pick-based variadic narrowing) lights up
+     * inferred types without the cast.
+     *
+     * @example
+     *   await qb.tasks.where({ done: false }).select(['id', 'title']).execute();
+     */
+    select(fields: ReadonlyArray<string>): Query<Row>;
+    /**
+     * Group rows by one or more fields. Required precursor to `.agg()`
+     * when aggregating per-group; without `.groupBy()` the aggregation
+     * runs against the whole filtered set and returns one row.
+     *
+     * Transitions the builder to {@link AggQuery} so subsequent calls
+     * have access to `.agg()` + the aggregation-shaped `.execute()`.
+     *
+     * @example
+     *   qb.from<TaskRow>('tasks')
+     *     .where({ done: false })
+     *     .groupBy(['priority', 'assignee_id'])
+     *     .agg({ total: { count: '*' } })
+     *     .execute()
+     */
+    groupBy(fields: ReadonlyArray<FieldRef>): AggQuery;
+    /**
+     * Set the aggregation expressions. Keys are output column names in
+     * the result rows; values are aggregation function specs
+     * (`{ count: '*' }`, `{ sum: 'amount' }`, etc.). At least one
+     * expression is required; calling `.agg({})` rejects.
+     *
+     * Without a preceding `.groupBy()`, returns a single row with the
+     * aggregations applied to the entire filtered set. With `.groupBy()`,
+     * returns one row per group.
+     *
+     * Transitions the builder to {@link AggQuery} — `.execute()` on
+     * the returned builder yields {@link QueryResult} (not `Page<Row>`).
+     *
+     * @example
+     *   const stats = await qb.from<TaskRow>('tasks')
+     *     .where({ done: false })
+     *     .agg({ total: { count: '*' }, oldest: { min: 'created_at' } })
+     *     .execute();
+     *   // stats.rows[0] = { total: 7, oldest: '2026-01-15' }
+     */
+    agg(expressions: Record<string, AggExpr>): AggQuery;
+}
+/**
+ * Chainable per-query builder after `.join()` / `.leftJoin()` has
+ * been called. Same kind of immutable shape as {@link Query} —
+ * every modifier returns a fresh instance.
+ *
+ * Surface intentionally NARROWER than Query<Row>:
+ *   - Omits `.create / .update / .delete` — joined queries are
+ *     read-only (writes always go through `client.db()`).
+ *   - Omits `.count / .agg / .groupBy` — slice 3.2b-1 doesn't yet
+ *     handle aggregation over joined tables (Phase 5+ work).
+ *
+ * Today's available surface:
+ *   - `.where` — bare-ref + qualified-ref WHERE both work as of
+ *     Phase 3 slice 3.2b-2-full (SQL-side alias-aware WHERE)
+ *   - `.orderBy` — bare + qualified-ref sort (slice 3.2b-3)
+ *   - `.limit`, `.offset` — in-memory pagination over post-WHERE
+ *     rows, capped at 10k (slice 3.2b-3)
+ *   - `.join`, `.leftJoin` — stack additional joins up to 2 total
+ *     in v1 (Phase 4 slice 4.3; validator rejects 3+ with a clear
+ *     QUERY_TOO_COMPLEX). Cross-module dep refs accepted as targets
+ *     since slice 4.2.
+ *   - `.flatten()` — switches to SQL-style flat result rows (slice
+ *     3.5; backend wired since slice 3.5)
+ *   - `.toAst()`, `.execute()` — same as Query<Row>.
+ */
+interface JoinedQuery<Row extends BaseRow = BaseRow> {
+    toAst(): QueryAst;
+    /** Resolves with `Page<Row>` shape — rows carry the nested joined data. */
+    execute(): Promise<Page<Row>>;
+    /**
+     * Phase 6 streaming (2026-05-19): stream joined-row results
+     * row-by-row via SSE. Same contract as {@link Query.stream} — see
+     * its JSDoc for the full doc. Joined queries stream their nested-
+     * row shape (each yielded row has the joined object under the
+     * alias key, same as `.execute()` returns).
+     */
+    stream(opts?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Row>;
+    /**
+     * Return Postgres EXPLAIN (FORMAT JSON) for this joined query —
+     * WITHOUT executing it. The joined path is the canonical supported
+     * shape for `.explain()` in MVP (Phase 5, 2026-05-19) because the
+     * join translator emits clean parameterized SQL the backend can wrap
+     * with EXPLAIN directly.
+     *
+     * Returns the same {@link ExplainResult} shape as `Query.explain`.
+     * See `Query.explain` JSDoc for the full call shape + examples.
+     */
+    explain(): Promise<ExplainResult>;
+    where(clause: Where<Row>): JoinedQuery<Row>;
+    orderBy(clauses: ReadonlyArray<OrderClause>): JoinedQuery<Row>;
+    limit(n: number): JoinedQuery<Row>;
+    offset(n: number): JoinedQuery<Row>;
+    /**
+     * Add another join. Capped at 2 total in v1 (validator).
+     * Phase 4 slice 4.2: accepts {@link QbDepRef} as the target for
+     * cross-module joins (same overload semantics as the entry join).
+     */
+    join<T = unknown>(target: string | QbDepRef, opts: JoinOpts<'inner' | 'left'>): JoinedQuery<Row & Record<string, T>>;
+    leftJoin<T = unknown>(target: string | QbDepRef, opts: JoinOpts<'left'>): JoinedQuery<Row & Record<string, T | null>>;
+    /**
+     * Switch to flat-row result shape (`{ 'users.email': ... }`)
+     * instead of the nested default. Slice 3.5 wires the backend; the
+     * SDK exposes it today + sends the AST flag.
+     */
+    flatten(): JoinedQuery<Record<string, unknown> & BaseRow>;
+}
+/**
+ * Aggregation-mode query. Reachable from {@link Query.agg} or
+ * {@link Query.groupBy}. Exposes the same `where` / `limit` / `offset`
+ * surface as the non-agg `Query` (you can still filter + limit groups)
+ * but `.execute()` returns {@link QueryResult} instead of `Page<Row>`.
+ *
+ * Doesn't expose `.create` / `.update` / `.delete` (aggregations are
+ * read-only by definition) or `.count()` (use `.agg({ n: { count: '*' } })`
+ * directly + read `result.rows[0].n`).
+ */
+interface AggQuery {
+    toAst(): QueryAst;
+    execute(): Promise<QueryResult>;
+    /**
+     * Return Postgres EXPLAIN (FORMAT JSON) for the underlying SELECT
+     * this aggregation builds. Joined aggregations (where the builder
+     * arrived here via `.join().agg()`) work in MVP — the source SELECT
+     * dominates cost; the in-memory GROUP BY post-runs above it. Bare
+     * own-table aggregations currently reject with `EXPLAIN_NOT_SUPPORTED_YET`
+     * (lifts when bare-path support lands; see {@link Query.explain}).
+     */
+    explain(): Promise<ExplainResult>;
+    where(clause: Record<string, unknown>): AggQuery;
+    /** Refine the group-by fields (replace, not merge). */
+    groupBy(fields: ReadonlyArray<FieldRef>): AggQuery;
+    /** Refine the aggregation expressions (replace, not merge). */
+    agg(expressions: Record<string, AggExpr>): AggQuery;
+    limit(n: number): AggQuery;
+    offset(n: number): AggQuery;
+}
+/**
+ * Build a {@link Qb} bound to `client`. The same `qb` instance can
+ * be reused across concurrent calls — every call constructs a fresh
+ * Query, and the underlying client is already thread-safe.
+ *
+ * @example
+ *   import { createClient } from '@dashai/sdk';
+ *   import { makeQb } from '@dashai/sdk/query';
+ *
+ *   const client = createClient({ baseUrl, installationId, getToken });
+ *   const qb = makeQb(client);
+ *
+ *   const page = await qb.from<TaskRow>('tasks').execute();
+ *   console.log(page.rows);
+ *
+ * The generated SDK (`@dashai/generated/qb`) will eventually export
+ * a typed singleton wrapping the default client — `import { qb } from
+ * '@dashai/generated'; qb.tasks.execute()`. That layer lands once
+ * codegen is updated; until then, `makeQb(client).from('tasks')` is
+ * the path.
+ */
+declare function makeQb(client: Client): Qb;
+
+export { type AggExpr, type AggQuery, CURRENT_QUERY_AST_VERSION, type ExplainResult, type FieldRef, type JoinNode, type JoinOpts, type JoinedQuery, type OrderClause, type Qb, type QbDepRef, type QbViewRef, type Query, type QueryAst, type QueryAstVersion, type QueryResult, type SelectExpr, type TableRef, type WhereClause, isQueryAst, makeQb };