@sixb/pg 0.1.21 → 0.1.22

package/src/objects/conditional-reader.ts

@@ -0,0 +1,44 @@
+import type { ObjectQuery } from "@sixb/core"
+import { hasVectorProfile } from "@sixb/core/internal/query"
+import type {
+  CompiledConditionalObjectReadScope,
+  ObjectQueryCapabilities,
+  ObjectReadStorage,
+} from "@sixb/core/storage"
+import { type PgStoreClient, runPgRepeatableReadTransaction } from "../transactions"
+import type { PgAggregateAdmission } from "./aggregate-admission"
+import { compilePgConditionalObjectReadSource } from "./read-scope"
+import { PgObjectReader } from "./reader"
+import { createPgScopedReader } from "./scoped-reader"
+
+/**
+ * Read objects and links through relations that apply the scope's conditions as they are read.
+ *
+ * Reads run as unscoped ones do, under the same aggregate admission: on the pool, and a vector
+ * query on one repeatable-read snapshot for its candidate probe and its rows.
+ */
+export function createPgConditionalReader(
+  sql: PgStoreClient,
+  params: {
+    projectId: string
+    scope: CompiledConditionalObjectReadScope
+  },
+  options: {
+    aggregateAdmission?: PgAggregateAdmission
+    queryCapabilities: () => ObjectQueryCapabilities
+  }
+): ObjectReadStorage {
+  const source = compilePgConditionalObjectReadSource(params.projectId, params.scope)
+  const reader = new PgObjectReader(sql, source, options.aggregateAdmission)
+
+  return createPgScopedReader(
+    {
+      projectId: params.projectId,
+      read: (run, query?: ObjectQuery) =>
+        query && hasVectorProfile(query)
+          ? runPgRepeatableReadTransaction(sql, (tx) => run(new PgObjectReader(tx, source)))
+          : run(reader),
+    },
+    options.queryCapabilities
+  )
+}

package/src/objects/prepare-queries.ts

@@ -59,7 +59,7 @@ function preparationFingerprint(plan: ObjectQueryPreparationPlan): string {
     .sort((a, b) => a.objectTypeId.localeCompare(b.objectTypeId))
 
   // Bump the version when physical generation changes, even if the ontology stays the same.
-  const definition = { version: 1, projectId: plan.projectId, objectTypes }
+  const definition = { version: 2, projectId: plan.projectId, objectTypes }
   return createHash("sha256").update(JSON.stringify(definition)).digest("hex")
 }
 

package/src/objects/query-compiler.ts

@@ -181,6 +181,12 @@ export interface PgObjectQuerySource {
   readonly objectsTable: string
   readonly linksTable: string
   readonly objectPropertyPermissionsTable?: string
+  /**
+   * Where to read one concrete type's objects, when the source can say it more precisely than
+   * `objectsTable`: a table and that type's own filter over its `properties`. A statement that
+   * reads a single type then holds the filter as a top-level condition, which an index can serve.
+   */
+  objectsOfType?(objectTypeId: string): PgTypedObjects
   /** Wrap a terminal SELECT without its own WITH clause; the selected source owns the only WITH. */
   wrapStatement(
     sql: string,
@@ -192,6 +198,26 @@ export interface PgObjectQuerySource {
   wrapQuery(query: CompiledPgObjectQuery): CompiledPgObjectQuery
 }
 
+export interface PgTypedObjects {
+  readonly table: string
+  readonly filter?: { readonly sql: string; readonly args: readonly unknown[] }
+}
+
+/** The table and `AND ...` filter a statement reads one type's objects with. */
+export function pgObjectsOfType(
+  source: PgObjectQuerySource,
+  objectTypeId: string
+): { table: string; filter: string; args: readonly unknown[] } {
+  const typed = source.objectsOfType?.(objectTypeId)
+  if (!typed) return { table: source.objectsTable, filter: "", args: [] }
+
+  return {
+    table: typed.table,
+    filter: typed.filter ? `AND (${typed.filter.sql})` : "",
+    args: typed.filter?.args ?? [],
+  }
+}
+
 /** Prefix an optional query source, then assign PostgreSQL positional placeholders. */
 export function compilePgObjectStatement(
   sql: string,
@@ -462,10 +488,11 @@ function compileStart(
   }
 
   const order = compileOrder(identityOrderFields())
+  const objects = pgObjectsOfType(ctx.source, query.objectTypeId)
   const sql = `
     SELECT *, properties AS _cursor_properties
-    FROM ${ctx.source.objectsTable}
-    WHERE project_id = ? AND object_type_id = ?
+    FROM ${objects.table}
+    WHERE project_id = ? AND object_type_id = ? ${objects.filter}
     ${ctx.startPredicate ? `AND (${ctx.startPredicate})` : ""}
     ${ctx.unordered ? "" : `ORDER BY ${order.sql}`}
     ${ctx.isolateSortOverflow ? "OFFSET 0" : ""}
@@ -473,9 +500,9 @@ function compileStart(
 
   return {
     sql,
-    args: [projectId, query.objectTypeId, ...(ctx.unordered ? [] : order.args)],
-    totalSql: `SELECT COUNT(*)::bigint AS total FROM ${ctx.source.objectsTable} WHERE project_id = ? AND object_type_id = ?`,
-    totalArgs: [projectId, query.objectTypeId],
+    args: [projectId, query.objectTypeId, ...objects.args, ...(ctx.unordered ? [] : order.args)],
+    totalSql: `SELECT COUNT(*)::bigint AS total FROM ${objects.table} WHERE project_id = ? AND object_type_id = ? ${objects.filter}`,
+    totalArgs: [projectId, query.objectTypeId, ...objects.args],
     order,
     hasMore: () => false,
     trimRows: identityRows,
@@ -1070,11 +1097,7 @@ function compileExpansionOrder(
     const direction = field.direction === "desc" ? "DESC" : "ASC"
     clauses.push(
       `CASE WHEN ${jsonTypeExpression(propertyColumn)} IS NULL OR ${jsonTypeExpression(propertyColumn)} = 'null' THEN 1 ELSE 0 END ASC`,
-      `${
-        field.scalarKind === "decimal"
-          ? `(${jsonTextExpression(propertyColumn)})::numeric`
-          : `NULLIF(${jsonValueExpression(propertyColumn)}, 'null'::jsonb)`
-      } ${direction}`
+      `${orderedValueExpression(field.scalarKind, propertyColumn)} ${direction}`
     )
     args.push(field.propertyId, field.propertyId, field.propertyId)
   }
@@ -1239,13 +1262,14 @@ function compileAggregateStart(
     throw new Error("[SixbPg] PostgreSQL object storage does not support start.includeSubtypes")
   }
 
+  const objects = pgObjectsOfType(source, query.objectTypeId)
   return {
     sql: `
       SELECT project_id, object_type_id, primary_id, properties
-      FROM ${source.objectsTable}
-      WHERE project_id = ? AND object_type_id = ?
+      FROM ${objects.table}
+      WHERE project_id = ? AND object_type_id = ? ${objects.filter}
     `,
-    args: [projectId, query.objectTypeId],
+    args: [projectId, query.objectTypeId, ...objects.args],
   }
 }
 
@@ -1452,7 +1476,8 @@ function compileProjectionExpression(properties: readonly string[]): CompiledPre
   }
 }
 
-function compilePredicate(predicate: ObjectQueryPredicate): CompiledPredicate {
+/** Compile a predicate over the unqualified `properties` column of the relation it filters. */
+export function compilePredicate(predicate: ObjectQueryPredicate): CompiledPredicate {
   switch (predicate.op) {
     case "and":
     case "or": {
@@ -1467,6 +1492,8 @@ function compilePredicate(predicate: ObjectQueryPredicate): CompiledPredicate {
       const item = compilePredicate(predicate.item)
       return negatePredicate(item)
     }
+    case "constant":
+      return { sql: predicate.value ? "true" : "false", args: [] }
     case "eq":
       return predicate.scalarKind === "decimal"
         ? compileDecimalEqualityPredicate(predicate.propertyId, "eq", predicate.value)
@@ -1486,6 +1513,14 @@ function compilePredicate(predicate: ObjectQueryPredicate): CompiledPredicate {
           args: [predicate.propertyId, predicate.propertyId, predicate.value],
         }
       }
+      if (isTextScalarKind(predicate.scalarKind)) {
+        // The null rank makes the range a prefix of the property's sort index keys.
+        return {
+          sql: `(${nullRankExpression()} = 0 AND ${orderedValueExpression(predicate.scalarKind)} ${op} ?::text)`,
+          args: [predicate.propertyId, predicate.propertyId, predicate.propertyId, predicate.value],
+        }
+      }
+
       return {
         sql: `${jsonValueExpression()} ${op} ?::text::jsonb`,
         args: [predicate.propertyId, jsonbValue(predicate.value)],
@@ -1809,13 +1844,13 @@ function compileKeysetRanges(
     })
     if (value.nullish) return
     const expression = compiledPropertyValueExpression(field, propertyColumn)
-    const parameter = field.scalarKind === "decimal" ? "?::numeric" : "?::text::jsonb"
-    const args = [
-      field.propertyId,
-      field.scalarKind === "decimal" ? value.value : jsonbValue(value.value),
-    ]
-    addRange({ sql: `${expression} ${field.direction === "desc" ? "<" : ">"} ${parameter}`, args })
-    prefix.push({ sql: `${expression} = ${parameter}`, args })
+    const parameter = compiledPropertyParameter(field, value.value)
+    const args = [field.propertyId, parameter.value]
+    addRange({
+      sql: `${expression} ${field.direction === "desc" ? "<" : ">"} ${parameter.sql}`,
+      args,
+    })
+    prefix.push({ sql: `${expression} = ${parameter.sql}`, args })
   })
   return ranges
 }
@@ -1884,14 +1919,11 @@ function compileFieldEquality(
     }
   }
 
+  const parameter = compiledPropertyParameter(field, cursor.value)
+
   return {
-    sql: `(${jsonTypeExpression(propertyColumn)} IS NOT NULL AND ${jsonTypeExpression(propertyColumn)} != 'null' AND ${compiledPropertyValueExpression(field, propertyColumn)} = ${field.scalarKind === "decimal" ? "?::numeric" : "?::text::jsonb"})`,
-    args: [
-      field.propertyId,
-      field.propertyId,
-      field.propertyId,
-      field.scalarKind === "decimal" ? cursor.value : jsonbValue(cursor.value),
-    ],
+    sql: `(${jsonTypeExpression(propertyColumn)} IS NOT NULL AND ${jsonTypeExpression(propertyColumn)} != 'null' AND ${compiledPropertyValueExpression(field, propertyColumn)} = ${parameter.sql})`,
+    args: [field.propertyId, field.propertyId, field.propertyId, parameter.value],
   }
 }
 
@@ -1911,16 +1943,17 @@ function compileFieldAfter(
 
   const rankSql = `CASE WHEN ${jsonTypeExpression(propertyColumn)} IS NULL OR ${jsonTypeExpression(propertyColumn)} = 'null' THEN 1 ELSE 0 END`
   const valueOperator = field.direction === "desc" ? "<" : ">"
+  const parameter = compiledPropertyParameter(field, cursor.value)
 
   return {
-    sql: `(${rankSql} > 0 OR (${rankSql} = 0 AND ${compiledPropertyValueExpression(field, propertyColumn)} ${valueOperator} ${field.scalarKind === "decimal" ? "?::numeric" : "?::text::jsonb"}))`,
+    sql: `(${rankSql} > 0 OR (${rankSql} = 0 AND ${compiledPropertyValueExpression(field, propertyColumn)} ${valueOperator} ${parameter.sql}))`,
     args: [
       field.propertyId,
       field.propertyId,
       field.propertyId,
       field.propertyId,
       field.propertyId,
-      field.scalarKind === "decimal" ? cursor.value : jsonbValue(cursor.value),
+      parameter.value,
     ],
   }
 }
@@ -2010,9 +2043,39 @@ function compiledPropertyValueExpression(
   field: Extract<CompiledOrderField, { kind: "property" }>,
   propertyColumn = "properties"
 ): string {
-  return field.scalarKind === "decimal"
-    ? `(${jsonTextExpression(propertyColumn)})::numeric`
-    : `NULLIF(${jsonValueExpression(propertyColumn)}, 'null'::jsonb)`
+  return orderedValueExpression(field.scalarKind, propertyColumn)
+}
+
+/** The parameter a cursor value binds to, typed like `compiledPropertyValueExpression`. */
+function compiledPropertyParameter(
+  field: Extract<CompiledOrderField, { kind: "property" }>,
+  value: unknown
+): { sql: string; value: unknown } {
+  if (field.scalarKind === "decimal") return { sql: "?::numeric", value }
+  if (isTextScalarKind(field.scalarKind)) return { sql: "?::text", value }
+  return { sql: "?::text::jsonb", value: jsonbValue(value) }
+}
+
+/**
+ * The expression a property sorts and range-compares by. Strings compare by code point, as
+ * SQLite and the in-memory store do: JSONB and the database's own collation would order case and
+ * accents linguistically. Sort indexes repeat this expression, collation included.
+ */
+function orderedValueExpression(
+  scalarKind: QueryScalarKind | undefined,
+  propertyColumn = "properties"
+): string {
+  if (scalarKind === "decimal") return `(${jsonTextExpression(propertyColumn)})::numeric`
+  if (isTextScalarKind(scalarKind)) return `((${jsonTextExpression(propertyColumn)}) COLLATE "C")`
+  return `NULLIF(${jsonValueExpression(propertyColumn)}, 'null'::jsonb)`
+}
+
+export function isTextScalarKind(scalarKind: QueryScalarKind | undefined): boolean {
+  return scalarKind === "string" || scalarKind === "uuid"
+}
+
+function nullRankExpression(propertyColumn = "properties"): string {
+  return `CASE WHEN ${jsonTypeExpression(propertyColumn)} IS NULL OR ${jsonTypeExpression(propertyColumn)} = 'null' THEN 1 ELSE 0 END`
 }
 
 function columnExpression(

package/src/objects/query-indexes.ts

@@ -4,6 +4,7 @@ import type { ReservedSQL, SQL, SQLClient } from "../pg-client"
 import { isConnectionLost } from "../storage-errors"
 import { withReservedPgConnection } from "../transactions"
 import { lockPgPreparation } from "./preparation-lock"
+import { isTextScalarKind } from "./query-compiler"
 
 export interface PgObjectQueryIndexScope {
   readonly projectId: string
@@ -110,6 +111,22 @@ async function createQueryIndex(
     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)})`
     )
+
+    // The same definition under another name is an earlier generation of this index, built
+    // with an expression queries no longer use. Writes would keep maintaining it.
+    const superseded = await connection<{ name: string }[]>`
+      SELECT c.relname AS name 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 LIKE 'sixb_query_%' AND c.relname <> ${name}
+        AND obj_description(c.oid, 'pg_class') = ${JSON.stringify(definition.index)}`
+    for (const previous of superseded) {
+      for (const index of [previous.name, `${previous.name}_overflow`]) {
+        await connection.unsafe(
+          `DROP INDEX CONCURRENTLY IF EXISTS ${identifier(schema)}.${identifier(index)}`
+        )
+      }
+    }
   }
   return name
 }
@@ -150,14 +167,7 @@ function statisticsExpressions(index: PgObjectQueryIndex): string[] {
   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))`
-      )
-    }
+  if (index.kind === "sort") for (const field of index.fields) expressions.push(sortValue(field))
   return expressions
 }
 
@@ -220,7 +230,7 @@ function compileIndex(index: PgObjectQueryIndex): string {
       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"}`
+        `${sortValue(field)} ${field.direction === "desc" ? "DESC" : "ASC"}`
       )
     }
     fields.push("primary_id")
@@ -228,6 +238,14 @@ function compileIndex(index: PgObjectQueryIndex): string {
   return `(${fields.join(", ")}) WHERE ${predicate.join(" AND ")}`
 }
 
+/** The query compiler's ordered value expression; an index serves a sort only when they match. */
+function sortValue(field: Extract<PgObjectQueryIndex, { kind: "sort" }>["fields"][number]): string {
+  const text = `(properties ->> ${literal(field.propertyId)})`
+  if (field.scalarKind === "decimal") return `(${text}::numeric)`
+  if (isTextScalarKind(field.scalarKind)) return `(${text} COLLATE "C")`
+  return `(NULLIF(properties -> ${literal(field.propertyId)}, 'null'::jsonb))`
+}
+
 function literal(value: string): string {
   if (value.includes("\0"))
     throw new Error("[SixbPg] Query index names and values cannot contain NUL")
@@ -337,7 +355,8 @@ export async function findPgSortIndexBound(
           fields[i]?.kind === "property" &&
           fields[i].propertyId === field.propertyId &&
           (field.direction ?? "asc") === (fields[i].direction ?? "asc") &&
-          (field.scalarKind === "decimal") === (fields[i].scalarKind === "decimal")
+          (field.scalarKind === "decimal") === (fields[i].scalarKind === "decimal") &&
+          isTextScalarKind(field.scalarKind) === isTextScalarKind(fields[i].scalarKind)
       )
     )
       continue

package/src/objects/read-scope.ts

@@ -1,7 +1,11 @@
-import type { CompiledSelectedObjectReadScope } from "@sixb/core/storage"
+import type {
+  CompiledConditionalObjectReadScope,
+  CompiledSelectedObjectReadScope,
+} from "@sixb/core/storage"
 import {
   type CompiledPgObjectQuery,
   compilePgObjectStatement,
+  compilePredicate,
   type PgObjectQuerySource,
 } from "./query-compiler"
 
@@ -30,16 +34,78 @@ export function compilePgSelectedObjectReadSource(
     objects: scope.objects,
     steps: scope.steps,
   })
-  const compiled = compileSelectedReadScopeCte(scopeJson, projectId)
+  const source: PgSelectedObjectReadSource = {
+    ...scopedQuerySource(compileSelectedReadScopeCte(scopeJson, projectId)),
+    objectPropertyPermissionsTable: "_sixb_scope_object_permissions",
+    traversalProbe: { sql: "", args: [] },
+  }
+
+  const traversalProbe = compilePgObjectStatement(
+    `
+      SELECT COUNT(*)::bigint AS total
+      FROM (
+        SELECT 1 AS traversal_fact
+        FROM _sixb_scope_root_facts
+
+        UNION ALL
+
+        SELECT 1 AS traversal_fact
+        FROM _sixb_scope_reached_links
+
+        LIMIT ?
+      ) AS bounded_traversal_facts
+    `,
+    [BigInt(maxTraversalFacts) + 1n],
+    source
+  )
+
+  return Object.freeze({ ...source, traversalProbe })
+}
+
+/**
+ * Prepare a conditional scope as PostgreSQL relations that filter stored rows as they are read.
+ *
+ * Both relations are NOT MATERIALIZED, so PostgreSQL inlines them into each statement: its
+ * filters, index scans and LIMIT reach the stored tables, and the conditions become one more
+ * filter. An object of a conditioned type is visible while its condition matches; a link while
+ * each of its conditioned endpoints is a visible object.
+ */
+export function compilePgConditionalObjectReadSource(
+  projectId: string,
+  scope: CompiledConditionalObjectReadScope
+): PgObjectQuerySource {
+  const filters = new Map(
+    scope.conditions.map((condition) => [
+      condition.objectTypeId,
+      compilePredicate(condition.predicate),
+    ])
+  )
+
+  return Object.freeze({
+    ...scopedQuerySource(compileConditionalReadScopeCte(projectId, filters)),
+    // One type's visible objects are the stored ones its own condition matches.
+    objectsOfType: (objectTypeId: string) => {
+      const filter = filters.get(objectTypeId)
+      return filter ? { table: "objects", filter } : { table: "objects" }
+    },
+  })
+}
+
+interface CompiledReadScopeCte {
+  readonly sql: string
+  readonly args: readonly unknown[]
+}
+
+/** Prefix every statement of a query with the scope's relations, ahead of its own arguments. */
+function scopedQuerySource(compiled: CompiledReadScopeCte): PgObjectQuerySource {
   const wrapStatement = (sql: string, args: readonly unknown[] = []) => ({
     sql: `${compiled.sql}\n${sql}`,
     args: [...compiled.args, ...args],
   })
 
-  const source: PgSelectedObjectReadSource = {
+  return {
     objectsTable: "_sixb_scope_objects",
     linksTable: "_sixb_scope_links",
-    objectPropertyPermissionsTable: "_sixb_scope_object_permissions",
     wrapStatement,
     wrapQuery: (query: CompiledPgObjectQuery): CompiledPgObjectQuery => ({
       ...query,
@@ -58,34 +124,83 @@ export function compilePgSelectedObjectReadSource(
           }
         : {}),
     }),
-    traversalProbe: { sql: "", args: [] },
   }
+}
 
-  const traversalProbe = compilePgObjectStatement(
-    `
-      SELECT COUNT(*)::bigint AS total
-      FROM (
-        SELECT 1 AS traversal_fact
-        FROM _sixb_scope_root_facts
+/** Conditions keyed by their concrete type, each compiled over that type's `properties`. */
+type ConditionFilters = ReadonlyMap<
+  string,
+  { readonly sql: string; readonly args: readonly unknown[] }
+>
 
-        UNION ALL
+function compileConditionalReadScopeCte(
+  projectId: string,
+  filters: ConditionFilters
+): CompiledReadScopeCte {
+  if (filters.size === 0) {
+    return {
+      sql: `
+        WITH
+        _sixb_scope_objects AS NOT MATERIALIZED (
+          SELECT * FROM objects WHERE project_id = ?
+        ),
+        _sixb_scope_links AS NOT MATERIALIZED (
+          SELECT * FROM links WHERE project_id = ?
+        )
+      `,
+      args: [projectId, projectId],
+    }
+  }
 
-        SELECT 1 AS traversal_fact
-        FROM _sixb_scope_reached_links
+  const conditionedTypeArgs = [...filters.keys()]
+  const conditionedTypes = conditionedTypeArgs.map(() => "?::text").join(", ")
 
-        LIMIT ?
-      ) AS bounded_traversal_facts
-    `,
-    [BigInt(maxTraversalFacts) + 1n],
-    source
-  )
+  const matches: string[] = []
+  const matchArgs: unknown[] = []
+  for (const [objectTypeId, filter] of filters) {
+    matches.push(`(object_type_id = ?::text AND ${filter.sql})`)
+    matchArgs.push(objectTypeId, ...filter.args)
+  }
 
-  return Object.freeze({ ...source, traversalProbe })
-}
+  const visibleEndpoint = (end: "source" | "target") => `
+    (
+      stored.${end}_type_id NOT IN (${conditionedTypes})
+      OR EXISTS (
+        SELECT 1
+        FROM _sixb_scope_objects AS endpoint
+        WHERE endpoint.project_id = stored.project_id
+          AND endpoint.object_type_id = stored.${end}_type_id
+          AND endpoint.primary_id = stored.${end}_id
+      )
+    )
+  `
 
-interface CompiledReadScopeCte {
-  readonly sql: string
-  readonly args: readonly unknown[]
+  return {
+    sql: `
+      WITH
+      _sixb_scope_objects AS NOT MATERIALIZED (
+        SELECT *
+        FROM objects
+        WHERE project_id = ?
+          AND (object_type_id NOT IN (${conditionedTypes}) OR ${matches.join(" OR ")})
+      ),
+      _sixb_scope_links AS NOT MATERIALIZED (
+        SELECT stored.*
+        FROM links AS stored
+        WHERE stored.project_id = ?
+          AND ${visibleEndpoint("source")}
+          AND ${visibleEndpoint("target")}
+      )
+    `,
+    args: [
+      projectId,
+      ...conditionedTypeArgs,
+      ...matchArgs,
+      projectId,
+      ...conditionedTypeArgs,
+      ...conditionedTypeArgs,
+    ],
+  }
 }
 
 function compileSelectedReadScopeCte(scopeJson: string, projectId: string): CompiledReadScopeCte {

package/src/objects/reader.ts

@@ -30,6 +30,7 @@ import {
   compilePgObjectStatement,
   DEFAULT_OBJECT_QUERY_SOURCE,
   type PgObjectQuerySource,
+  pgObjectsOfType,
 } from "./query-compiler"
 import { findPgSortIndexBound } from "./query-indexes"
 import type { PgSelectedObjectReadSource } from "./read-scope"
@@ -258,13 +259,14 @@ export class PgObjectReader {
   }): Promise<ObjectRow | null> {
     const sql = this.sql
     const source = this.source
+    const objects = pgObjectsOfType(source, params.objectTypeId)
     const statement = compilePgObjectStatement(
       `
         SELECT *
-        FROM ${source.objectsTable}
-        WHERE project_id = ? AND object_type_id = ? AND primary_id = ?
+        FROM ${objects.table}
+        WHERE project_id = ? AND object_type_id = ? AND primary_id = ? ${objects.filter}
       `,
-      [params.projectId, params.objectTypeId, params.primaryId],
+      [params.projectId, params.objectTypeId, params.primaryId, ...objects.args],
       source
     )
     const [row] = await sql.unsafe<ObjectDatabaseRow[]>(
@@ -275,6 +277,44 @@ export class PgObjectReader {
     return row ? rowToObject(row) : null
   }
 
+  /** On a selected source, the holder must be in scope and selected for the property. */
+  async getByUniqueValue(
+    params: Parameters<ObjectReadStorage["getByUniqueValue"]>[0]
+  ): Promise<ObjectRow | null> {
+    const source = this.source
+    const selected = "objectPropertyPermissionsTable" in source
+    const permitted = selected
+      ? `AND EXISTS (
+           SELECT 1 FROM ${source.objectPropertyPermissionsTable} AS permitted
+           WHERE permitted.project_id = objects.project_id
+             AND permitted.object_type_id = objects.object_type_id
+             AND permitted.primary_id = objects.primary_id
+             AND permitted.property_id = held.property_id
+         )`
+      : ""
+    const statement = compilePgObjectStatement(
+      `
+        SELECT objects.*
+        FROM object_unique_values AS held
+        JOIN ${source.objectsTable} AS objects
+          ON objects.project_id = held.project_id
+         AND objects.object_type_id = held.object_type_id
+         AND objects.primary_id = held.primary_id
+        WHERE held.project_id = ? AND held.object_type_id = ? AND held.property_id = ?
+          AND held.value_hash = sha256(convert_to(?, 'UTF8')) AND held.value_key = ?
+          ${permitted}
+      `,
+      [params.projectId, params.objectTypeId, params.propertyId, params.valueKey, params.valueKey],
+      source
+    )
+    const [row] = await this.sql.unsafe<ObjectDatabaseRow[]>(
+      statement.sql,
+      statement.args as SqlParameter[]
+    )
+
+    return row ? rowToObject(row) : null
+  }
+
   async selectsObjectProperties(
     params: Parameters<ObjectReadStorage["selectsObjectProperties"]>[0]
   ): Promise<readonly boolean[]> {
@@ -592,11 +632,15 @@ export class PgObjectReader {
     const order = params.order ?? "desc"
     const orderColumn =
       orderBy === "primaryId" ? "primary_id" : orderBy === "createdAt" ? "created_at" : "updated_at"
+    const typed =
+      typeof params.objectTypeId === "string"
+        ? pgObjectsOfType(source, params.objectTypeId)
+        : { table: source.objectsTable, filter: "", args: [] }
     const filters = ["project_id = ?"]
     const args: unknown[] = [params.projectId]
     if (typeof params.objectTypeId === "string") {
-      filters.push("object_type_id = ?")
-      args.push(params.objectTypeId)
+      filters.push(`object_type_id = ? ${typed.filter}`)
+      args.push(params.objectTypeId, ...typed.args)
     } else if (params.objectTypeId !== undefined) {
       filters.push("object_type_id IN (SELECT jsonb_array_elements_text(?::text::jsonb))")
       args.push(JSON.stringify(params.objectTypeId))
@@ -626,7 +670,7 @@ export class PgObjectReader {
       args.push(params.createdBefore)
     }
 
-    const objectsTable = source.objectsTable
+    const objectsTable = typed.table
     const whereSql = filters.join(" AND ")
     const countStatement = compilePgObjectStatement(
       `SELECT COUNT(*)::int AS total FROM ${objectsTable} WHERE ${whereSql}`,