@sixb/pg 0.1.16 → 0.1.17

package/src/objects/query-indexes.ts

@@ -0,0 +1,348 @@
+import { createHash } from "node:crypto"
+import type { ObjectQuery, QueryScalarKind } from "@sixb/core"
+import type { ReservedSQL, SQL, SQLClient } from "../pg-client"
+import { isConnectionLost } from "../storage-errors"
+import { withReservedPgConnection } from "../transactions"
+import { lockPgPreparation } from "./preparation-lock"
+
+export interface PgObjectQueryIndexScope {
+  readonly projectId: string
+  readonly objectTypeId: string
+  /** Optional equality conditions. Partial indexes also accelerate exact counts of these views. */
+  readonly where?: Readonly<Record<string, string | number | boolean | null>>
+}
+
+export type PgObjectQueryIndex = PgObjectQueryIndexScope &
+  (
+    | {
+        readonly kind: "sort"
+        /** Leading string equality filters, in query order. */
+        readonly equality?: readonly string[]
+        readonly fields: readonly {
+          readonly propertyId: string
+          readonly direction?: "asc" | "desc"
+          readonly scalarKind?: QueryScalarKind
+        }[]
+      }
+    | { readonly kind: "incomingLinks"; readonly where?: never }
+    | { readonly kind: "text"; readonly propertyId: string }
+    | { readonly kind: "value"; readonly propertyId: string }
+    | { readonly kind: "count" }
+    | { readonly kind: "filter"; readonly properties: readonly string[] }
+  )
+
+/** Explicit maintenance operation: never creates indexes in the request path or a transaction. */
+export async function ensurePgObjectQueryIndexes(
+  sql: SQL | ReservedSQL,
+  schema: string,
+  indexes: readonly PgObjectQueryIndex[]
+): Promise<readonly string[]> {
+  const definitions = indexes.map((index) => ({
+    table: index.kind === "incomingLinks" ? "links" : "objects",
+    expression: compileIndex(index),
+    index,
+  }))
+  if (indexes.some((index) => index.kind === "text")) {
+    const [extension] = await sql<{ ready: boolean }[]>`
+      SELECT EXISTS (
+        SELECT 1 FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace
+        WHERE e.extname = 'pg_trgm' AND n.nspname = 'public'
+      ) AS ready`
+    if (!extension?.ready) {
+      throw new Error(
+        "[SixbPg] Text query indexes require pg_trgm in schema public. Run CREATE EXTENSION pg_trgm WITH SCHEMA public before ensuring indexes."
+      )
+    }
+  }
+
+  const names: string[] = []
+  await withReservedPgConnection(sql, async (connection) => {
+    let connected = true
+    try {
+      // One concurrent build per table, across definitions and across processes.
+      await lockPgPreparation(connection, `${schema}.objects.query-indexes`)
+      for (const definition of definitions) {
+        names.push(await createQueryIndex(connection, schema, definition))
+      }
+
+      await ensureExpressionStatistics(connection, schema, indexes)
+    } catch (error) {
+      connected = !isConnectionLost(error)
+      throw error
+    } finally {
+      if (connected)
+        await connection`SELECT pg_advisory_unlock(hashtextextended(${`${schema}.objects.query-indexes`}, 0))`
+    }
+  })
+  return names
+}
+
+async function createQueryIndex(
+  connection: ReservedSQL,
+  schema: string,
+  definition: { table: string; expression: string; index: PgObjectQueryIndex }
+): Promise<string> {
+  const name = `sixb_query_${createHash("sha256")
+    .update(
+      definition.table === "objects"
+        ? definition.expression
+        : `${definition.table}:${definition.expression}`
+    )
+    .digest("hex")
+    .slice(0, 32)}`
+  await connection.unsafe(
+    `CREATE INDEX CONCURRENTLY IF NOT EXISTS ${identifier(name)} ON ${identifier(schema)}.${identifier(definition.table)} ${definition.expression}`
+  )
+  const [index] = await connection<{ valid: boolean }[]>`
+    SELECT i.indisvalid AS valid FROM pg_index i
+    JOIN pg_class c ON c.oid = i.indexrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = ${schema} AND c.relname = ${name}`
+  if (!index?.valid)
+    throw new Error(
+      `[SixbPg] Query index ${schema}.${name} is invalid after an interrupted build. Drop that index concurrently and retry ensureObjectQueryIndexes().`
+    )
+  if (definition.index.kind === "sort") {
+    await connection.unsafe(
+      `COMMENT ON INDEX ${identifier(schema)}.${identifier(name)} IS ${literal(JSON.stringify(definition.index))}`
+    )
+    const scope = `project_id = ${literal(definition.index.projectId)} AND object_type_id = ${literal(definition.index.objectTypeId)}`
+    await connection.unsafe(
+      `CREATE INDEX CONCURRENTLY IF NOT EXISTS ${identifier(`${name}_overflow`)} ON ${identifier(schema)}.objects (primary_id) WHERE ${scope} AND NOT (${sortIndexBound(definition.index)})`
+    )
+  }
+  return name
+}
+
+async function ensureExpressionStatistics(
+  connection: ReservedSQL,
+  schema: string,
+  indexes: readonly PgObjectQueryIndex[]
+): Promise<void> {
+  let statisticsChanged = false
+  // Partial-index statistics do not describe expressions for the whole table. Without
+  // expression statistics JSON's default selectivity can turn a 4M-row view into an
+  // estimated 125-row sort, even when the right ordered index exists.
+  const expressions = new Set(indexes.flatMap(statisticsExpressions))
+  for (const expression of expressions) {
+    const name = `sixb_query_stats_${createHash("sha256").update(expression).digest("hex").slice(0, 24)}`
+    const [existing] = await connection`
+      SELECT 1 FROM pg_statistic_ext s JOIN pg_namespace n ON n.oid = s.stxnamespace
+      WHERE n.nspname = ${schema} AND s.stxname = ${name}`
+    if (existing) continue
+    await connection.unsafe(
+      `CREATE STATISTICS ${identifier(schema)}.${identifier(name)} ON project_id, object_type_id, ${expression} FROM ${identifier(schema)}.objects`
+    )
+    statisticsChanged = true
+  }
+  if (statisticsChanged) await connection.unsafe(`ANALYZE ${identifier(schema)}.objects`)
+}
+
+function statisticsExpressions(index: PgObjectQueryIndex): string[] {
+  if (index.kind === "incomingLinks") return []
+  const equality = new Set(Object.keys(index.where ?? {}))
+  if (index.kind === "filter") for (const property of index.properties) equality.add(property)
+  if (index.kind === "sort") for (const property of index.equality ?? []) equality.add(property)
+  const expressions = [...equality].map(
+    (property) =>
+      `jsonb_typeof(properties -> ${literal(property)}), (properties ->> ${literal(property)}), (md5(properties ->> ${literal(property)}))`
+  )
+  if (index.kind === "value") expressions.push(`(properties -> ${literal(index.propertyId)})`)
+  if (index.kind === "text")
+    expressions.push(`lower(coalesce(properties ->> ${literal(index.propertyId)}, ''))`)
+  if (index.kind === "sort")
+    for (const field of index.fields) {
+      expressions.push(
+        field.scalarKind === "decimal"
+          ? `((properties ->> ${literal(field.propertyId)})::numeric)`
+          : `(NULLIF(properties -> ${literal(field.propertyId)}, 'null'::jsonb))`
+      )
+    }
+  return expressions
+}
+
+function compileIndex(index: PgObjectQueryIndex): string {
+  if (index.kind === "incomingLinks") {
+    if (index.where)
+      throw new Error("[SixbPg] Incoming link indexes do not accept object property conditions")
+    return `(target_id, link_id, source_type_id, source_id) INCLUDE (project_id, target_type_id) WHERE project_id = ${literal(index.projectId)} AND target_type_id = ${literal(index.objectTypeId)}`
+  }
+  const predicate = [
+    `project_id = ${literal(index.projectId)}`,
+    `object_type_id = ${literal(index.objectTypeId)}`,
+  ]
+  for (const [propertyId, value] of Object.entries(index.where ?? {}).sort(([a], [b]) =>
+    a.localeCompare(b)
+  )) {
+    const property = `properties -> ${literal(propertyId)}`
+    if (value === null) predicate.push(`jsonb_typeof(${property}) = 'null'`)
+    else if (typeof value === "string") {
+      predicate.push(
+        `jsonb_typeof(${property}) = 'string'`,
+        `properties ->> ${literal(propertyId)} = ${literal(value)}`,
+        `md5(properties ->> ${literal(propertyId)}) = md5(${literal(value)})`
+      )
+    } else {
+      if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new Error("[SixbPg] Query index conditions require finite numbers")
+      }
+      predicate.push(`${property} = ${literal(JSON.stringify(value))}::jsonb`)
+    }
+  }
+  if (index.kind === "text") {
+    return `USING gin (lower(coalesce(properties ->> ${literal(index.propertyId)}, '')) public.gin_trgm_ops) WHERE ${predicate.join(" AND ")}`
+  }
+
+  // The partial predicate fixes the scope. Repeating those columns as leading keys
+  // makes PostgreSQL scan past them when it removes their redundant conditions.
+  const fields: string[] = []
+  if (index.kind === "count") {
+    fields.push("project_id", "object_type_id")
+  } else if (index.kind === "value") {
+    fields.push(`(properties -> ${literal(index.propertyId)})`)
+  }
+
+  if (index.kind === "filter") {
+    if (!index.properties.length || index.properties.length > 8)
+      throw new Error("[SixbPg] A filter index requires one to eight string properties")
+    for (const propertyId of index.properties)
+      fields.push(`(md5(properties ->> ${literal(propertyId)}))`)
+  }
+  if (index.kind === "sort") {
+    predicate.push(sortIndexBound(index))
+    if (index.fields.length === 0 || index.fields.length + (index.equality?.length ?? 0) > 8) {
+      throw new Error("[SixbPg] A sort query index requires between one and eight fields")
+    }
+    for (const propertyId of index.equality ?? []) {
+      fields.push(`(properties ->> ${literal(propertyId)})`)
+    }
+    for (const field of index.fields) {
+      const property = `properties -> ${literal(field.propertyId)}`
+      fields.push(
+        `(CASE WHEN jsonb_typeof(${property}) IS NULL OR jsonb_typeof(${property}) = 'null' THEN 1 ELSE 0 END)`,
+        `${field.scalarKind === "decimal" ? `((properties ->> ${literal(field.propertyId)})::numeric)` : `(NULLIF(${property}, 'null'::jsonb))`} ${field.direction === "desc" ? "DESC" : "ASC"}`
+      )
+    }
+    fields.push("primary_id")
+  }
+  return `(${fields.join(", ")}) WHERE ${predicate.join(" AND ")}`
+}
+
+function literal(value: string): string {
+  if (value.includes("\0"))
+    throw new Error("[SixbPg] Query index names and values cannot contain NUL")
+  return `E'${value.replace(/\\/g, "\\\\").replace(/'/g, "''")}'`
+}
+
+function identifier(value: string): string {
+  return `"${value.replace(/"/g, '""')}"`
+}
+
+/** Keep complete B-tree entries below PostgreSQL's page limit, without constraining valid data.
+ * Ordered reads merge a small indexed page with the exact overflow page. */
+export function sortIndexBound(index: Extract<PgObjectQueryIndex, { kind: "sort" }>): string {
+  const sizes = [
+    "octet_length(primary_id)",
+    ...index.fields.map(
+      (field) => `coalesce(octet_length((properties -> ${literal(field.propertyId)})::text), 0)`
+    ),
+    ...(index.equality ?? []).map(
+      (property) => `coalesce(octet_length(properties ->> ${literal(property)}), 0)`
+    ),
+  ]
+  return `(${sizes.join(" + ")}) <= 1800`
+}
+
+/** Only split a flat, bounded ordered read; joins, nested limits and projections keep the
+ * general compiler. Its unrestricted fallback always preserves semantics. */
+export async function findPgSortIndexBound(
+  sql: SQLClient,
+  projectId: string,
+  query: ObjectQuery
+): Promise<string | undefined> {
+  while (query.kind === "expand") query = query.input
+  if (query.kind !== "page" && query.kind !== "limit") return undefined
+  let input = query.input
+  let fields: Extract<ObjectQuery, { kind: "sort" }>["fields"] | undefined
+  const equality = new Set<string>()
+  while (input.kind === "sort" || input.kind === "filter" || input.kind === "text") {
+    if (input.kind === "sort") {
+      if (fields) return undefined
+      fields = input.fields
+    }
+    if (input.kind === "filter") {
+      const inspect = (predicate: Extract<ObjectQuery, { kind: "filter" }>["predicate"]): void => {
+        if (predicate.op === "and") predicate.items.forEach(inspect)
+        else if (predicate.op === "eq" && typeof predicate.value === "string")
+          equality.add(predicate.propertyId)
+        else if (
+          predicate.op === "in" &&
+          predicate.values.length === 1 &&
+          typeof predicate.values[0] === "string"
+        )
+          equality.add(predicate.propertyId)
+      }
+      inspect(input.predicate)
+    }
+    input = input.input
+  }
+  let objectTypeId: string | undefined
+  if (input.kind === "start" && !input.includeSubtypes) {
+    objectTypeId = input.objectTypeId
+  } else if (input.kind === "traverse" && input.direction === "incoming") {
+    objectTypeId = input.sourceObjectTypeId
+  }
+
+  if (!objectTypeId || !fields?.length || fields.some((field) => field.kind !== "property"))
+    return undefined
+
+  const rows = await sql<{ definition: string }[]>`
+    SELECT obj_description(c.oid, 'pg_class') AS definition
+    FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid
+    WHERE i.indrelid = 'objects'::regclass AND i.indisvalid
+      AND c.relname LIKE 'sixb_query_%'
+      AND obj_description(c.oid, 'pg_class') IS NOT NULL
+  `
+  const matches: Extract<PgObjectQueryIndex, { kind: "sort" }>[] = []
+  for (const row of rows) {
+    let candidate: unknown
+    try {
+      candidate = JSON.parse(row.definition)
+    } catch {
+      continue
+    }
+    if (!candidate || typeof candidate !== "object") continue
+    // Metadata is generated by this module. Verify all SQL-interpolated members before using it.
+    const index = candidate as Partial<Extract<PgObjectQueryIndex, { kind: "sort" }>>
+    if (
+      index.kind !== "sort" ||
+      index.projectId !== projectId ||
+      index.objectTypeId !== objectTypeId ||
+      index.where ||
+      !Array.isArray(index.fields) ||
+      index.fields.length !== fields.length
+    )
+      continue
+    if (
+      index.equality !== undefined &&
+      (!Array.isArray(index.equality) ||
+        !index.equality.every((property) => typeof property === "string" && equality.has(property)))
+    )
+      continue
+    if (
+      !index.fields.every(
+        (field, i) =>
+          field &&
+          typeof field.propertyId === "string" &&
+          fields[i]?.kind === "property" &&
+          fields[i].propertyId === field.propertyId &&
+          (field.direction ?? "asc") === (fields[i].direction ?? "asc") &&
+          (field.scalarKind === "decimal") === (fields[i].scalarKind === "decimal")
+      )
+    )
+      continue
+    matches.push(index as Extract<PgObjectQueryIndex, { kind: "sort" }>)
+  }
+  matches.sort((a, b) => (b.equality?.length ?? 0) - (a.equality?.length ?? 0))
+  return matches[0] ? sortIndexBound(matches[0]) : undefined
+}

package/src/objects/reader.ts

@@ -10,7 +10,6 @@ import type {
   LinkBatchKey,
   LinkDirection,
   ObjectBatchKey,
-  ObjectFacetResult,
   ObjectLinkRow,
   ObjectReadStorage,
   ObjectRow,
@@ -21,17 +20,19 @@ import type {
 } from "@sixb/core/storage"
 import { linkBatchKey, objectBatchKey } from "@sixb/core/storage"
 import type { SQLClient, SqlParameter } from "../pg-client"
+import type { PgAggregateAdmission } from "./aggregate-admission"
 import {
   type CompiledPgObjectQuery,
   compilePgObjectCountQuery,
   compilePgObjectExistsQuery,
-  compilePgObjectFacetQuery,
+  compilePgObjectFacetsQuery,
   compilePgObjectQuery,
   compilePgObjectStatement,
+  DEFAULT_OBJECT_QUERY_SOURCE,
   type PgObjectQuerySource,
 } from "./query-compiler"
+import { findPgSortIndexBound } from "./query-indexes"
 import type { PgSelectedObjectReadSource } from "./read-scope"
-
 import {
   type FacetDatabaseRow,
   type LinkBatchDatabaseRow,
@@ -45,11 +46,14 @@ import {
   rowToLink,
   rowToObject,
 } from "./rows"
+import { compilePgIndexedTextCount, compilePgIndexedTextFacets } from "./text-count-index"
 
+/** Execute object and link reads, using prepared access paths when the query shape allows it. */
 export class PgObjectReader {
   constructor(
     private readonly sql: SQLClient,
-    private readonly source: PgObjectQuerySource | PgSelectedObjectReadSource
+    private readonly source: PgObjectQuerySource | PgSelectedObjectReadSource,
+    private readonly aggregateAdmission?: PgAggregateAdmission
   ) {}
 
   private async assertVectorSearch(
@@ -82,28 +86,20 @@ export class PgObjectReader {
   async queryObjects(params: QueryObjectsInput): Promise<QueryObjectsResult> {
     await this.assertVectorSearch(params)
     const sql = this.sql
-    const source = this.source
-    const compiled = compilePgObjectQuery(params.projectId, params.query, {
-      includeTotal: params.includeTotal,
-      source,
-    })
-    const total = params.includeTotal === false ? undefined : await readTotal(sql, compiled)
+    const compiled = await this.compilePageQuery(params)
+    const total = await this.readQueryTotal(params, compiled)
+
     const rawRows = await sql.unsafe<ObjectQueryDatabaseRow[]>(
       compiled.sql,
       compiled.args as SqlParameter[]
     )
     const rows = compiled.trimRows(rawRows) as readonly ObjectQueryDatabaseRow[]
-    const hasMore =
-      total === undefined && compiled.hasMoreProbe
-        ? compiled.hasMoreProbe.hasMore(
-            (
-              await sql.unsafe(
-                compiled.hasMoreProbe.sql,
-                compiled.hasMoreProbe.args as SqlParameter[]
-              )
-            ).length
-          )
-        : compiled.hasMore(rawRows.length, total)
+    let hasMore = compiled.hasMore(rawRows.length, total)
+    if (total === undefined && compiled.hasMoreProbe) {
+      const probe = compiled.hasMoreProbe
+      const candidates = await sql.unsafe(probe.sql, probe.args as SqlParameter[])
+      hasMore = probe.hasMore(candidates.length)
+    }
 
     return {
       objects: rows.map((row) => queryRowToObject(row)),
@@ -113,13 +109,78 @@ export class PgObjectReader {
     }
   }
 
-  async countObjects(params: CountObjectsInput): Promise<CountObjectsResult> {
-    await this.assertVectorSearch(params)
+  /** Use the ordered traversal path only when its bounded probe finds a broad fanout. */
+  private async compilePageQuery(params: QueryObjectsInput): Promise<CompiledPgObjectQuery> {
     const sql = this.sql
     const source = this.source
-    const compiled = compilePgObjectCountQuery(params.projectId, stripOuterRowShape(params.query), {
+    const sortIndexBound =
+      source === DEFAULT_OBJECT_QUERY_SOURCE
+        ? await findPgSortIndexBound(sql, params.projectId, params.query)
+        : undefined
+    let compiled = compilePgObjectQuery(params.projectId, params.query, {
+      sortIndexBound,
+      includeTotal: params.includeTotal,
       source,
     })
+    if (compiled.traversalProbe) {
+      const probe = compiled.traversalProbe
+      const candidates = await sql.unsafe(probe.sql, probe.args as SqlParameter[])
+      if (candidates.length > probe.limit) {
+        compiled = compilePgObjectQuery(params.projectId, params.query, {
+          includeTotal: params.includeTotal,
+          source,
+          correlatedTraversal: true,
+          sortIndexBound,
+        })
+      }
+    }
+    return compiled
+  }
+
+  private async readQueryTotal(
+    params: QueryObjectsInput,
+    compiled: CompiledPgObjectQuery
+  ): Promise<number | undefined> {
+    if (params.includeTotal === false) return undefined
+
+    const computeTotal = async () => {
+      if (this.source === DEFAULT_OBJECT_QUERY_SOURCE) {
+        const indexed = await compilePgIndexedTextCount(
+          this.sql,
+          params.projectId,
+          totalCountInput(params.query)
+        )
+        if (indexed) {
+          const [row] = await this.sql.unsafe(indexed.sql, indexed.args as SqlParameter[])
+          return Number(row?.count ?? 0)
+        }
+      }
+      return readTotal(this.sql, compiled)
+    }
+
+    if (this.aggregateAdmission) return this.aggregateAdmission.run(computeTotal)
+    return computeTotal()
+  }
+
+  async countObjects(params: CountObjectsInput): Promise<CountObjectsResult> {
+    if (this.aggregateAdmission) {
+      return this.aggregateAdmission.run(() =>
+        new PgObjectReader(this.sql, this.source).countObjects(params)
+      )
+    }
+
+    await this.assertVectorSearch(params)
+    const sql = this.sql
+    const source = this.source
+    const indexed =
+      source === DEFAULT_OBJECT_QUERY_SOURCE
+        ? await compilePgIndexedTextCount(sql, params.projectId, stripOuterRowShape(params.query))
+        : undefined
+    const compiled =
+      indexed ??
+      compilePgObjectCountQuery(params.projectId, stripOuterRowShape(params.query), {
+        source,
+      })
     const [row] = await sql.unsafe<{ count: string | number | bigint }[]>(
       compiled.sql,
       compiled.args as SqlParameter[]
@@ -141,26 +202,53 @@ export class PgObjectReader {
   }
 
   async facetObjects(params: FacetObjectsInput): Promise<FacetObjectsResult> {
+    if (this.aggregateAdmission) {
+      return this.aggregateAdmission.run(() =>
+        new PgObjectReader(this.sql, this.source).facetObjects(params)
+      )
+    }
+
     await this.assertVectorSearch(params)
     const sql = this.sql
     const source = this.source
-    const facets: ObjectFacetResult[] = []
-    for (const facet of params.facets) {
-      facets.push({
-        propertyId: facet.propertyId,
-        buckets: await readFacetBuckets(
-          sql,
-          compilePgObjectFacetQuery(
+    const indexed =
+      source === DEFAULT_OBJECT_QUERY_SOURCE
+        ? await compilePgIndexedTextFacets(
+            sql,
             params.projectId,
             stripOuterRowShape(params.query),
-            facet.propertyId,
-            facet.limit,
-            { source }
+            params.facets
           )
-        ),
-      })
+        : undefined
+    const compiled =
+      indexed ??
+      compilePgObjectFacetsQuery(
+        params.projectId,
+        stripOuterRowShape(params.query),
+        params.facets,
+        { source }
+      )
+    const rows = await sql.unsafe<(FacetDatabaseRow & { facet_index: number })[]>(
+      compiled.sql,
+      compiled.args as SqlParameter[]
+    )
+    const facets = params.facets.map((facet) => ({
+      propertyId: facet.propertyId,
+      buckets: [] as { value: unknown; count: number }[],
+    }))
+    let total = 0
+    for (const row of rows) {
+      if (row.facet_index === -1) {
+        total = Number(row.count)
+      } else {
+        facets[row.facet_index]?.buckets.push({
+          value: pgFacetValue(row.value_type, row.value_text),
+          count: Number(row.count),
+        })
+      }
     }
-    return { facets }
+
+    return { total, facets }
   }
 
   async getByPrimaryId(params: {
@@ -585,20 +673,6 @@ async function readTotal(sql: SQLClient, compiled: CompiledPgObjectQuery): Promi
   return Number(row?.total ?? 0)
 }
 
-async function readFacetBuckets(
-  sql: SQLClient,
-  compiled: { sql: string; args: readonly unknown[] }
-): Promise<{ value: unknown; count: number }[]> {
-  const rows = await sql.unsafe<FacetDatabaseRow[]>(compiled.sql, [
-    ...compiled.args,
-  ] as SqlParameter[])
-
-  return rows.map((row) => ({
-    value: pgFacetValue(row.value_type, row.value_text),
-    count: Number(row.count),
-  }))
-}
-
 function pgFacetValue(valueType: string | null, valueText: string | null): unknown {
   switch (valueType) {
     case "string":
@@ -617,6 +691,21 @@ function pgFacetValue(valueType: string | null, valueText: string | null): unkno
   }
 }
 
+// A page's total counts its input, including any inner limit/page. Do not strip those bounds.
+function totalCountInput(query: ObjectQuery): ObjectQuery {
+  switch (query.kind) {
+    case "sort":
+    case "project":
+    case "expand":
+      return totalCountInput(query.input)
+    case "limit":
+    case "page":
+      return query.input
+    default:
+      return query
+  }
+}
+
 function stripOuterRowShape(query: ObjectQuery): ObjectQuery {
   switch (query.kind) {
     case "limit":

package/src/objects/storage.ts

@@ -22,7 +22,12 @@ import type {
   QueryObjectsResult,
 } from "@sixb/core/storage"
 import type { SQLClient, SqlParameter } from "../pg-client"
-import { type PgStoreClient, runPgRepeatableReadTransaction } from "../transactions"
+import {
+  canStartPgTransaction,
+  type PgStoreClient,
+  runPgRepeatableReadTransaction,
+} from "../transactions"
+import { PgAggregateAdmission } from "./aggregate-admission"
 import { DEFAULT_OBJECT_QUERY_SOURCE } from "./query-compiler"
 import { assertLinkQueryLimit, PgObjectReader } from "./reader"
 import {
@@ -107,8 +112,15 @@ const PG_OBJECT_QUERY_CAPABILITIES: ObjectQueryCapabilities = {
 export class PgObjectStorage implements ObjectStorage {
   private readonly reader: PgObjectReader
 
-  constructor(private readonly sql: PgStoreClient) {
-    this.reader = new PgObjectReader(sql, DEFAULT_OBJECT_QUERY_SOURCE)
+  constructor(
+    private readonly sql: PgStoreClient,
+    maxConcurrentAggregates = 1
+  ) {
+    this.reader = new PgObjectReader(
+      sql,
+      DEFAULT_OBJECT_QUERY_SOURCE,
+      canStartPgTransaction(sql) ? new PgAggregateAdmission(maxConcurrentAggregates) : undefined
+    )
   }
 
   queryCapabilities(): ObjectQueryCapabilities {