@sixb/core 0.1.20 → 0.1.22

package/src/objects/query/executor.ts

@@ -2,6 +2,7 @@ import { type AuthorizationContext, assertAuthorized } from "../../authorization
 import type { RuntimeAuthorization } from "../../execution/types"
 import type { EmbeddingModelCatalog, RerankingModelCatalog } from "../../models/catalog"
 import type { OntologyRegistry } from "../../ontology"
+import type { UserRef } from "../../ontology/user-ref"
 import type {
   CountObjectsResult,
   ExistsObjectsResult,
@@ -19,6 +20,7 @@ import type {
 } from "../../storage"
 import { linkBatchKey, MAX_OBJECT_READ_FACETS, objectBatchKey } from "../../storage"
 import { resolveVectorSearchText } from "../vectors/resolve-query"
+import { bindCurrentUser } from "./current-user"
 import {
   ObjectQueryExecutionError,
   ObjectQueryPlanningError,
@@ -27,17 +29,17 @@ import {
 import type {
   ObjectExpansion,
   ObjectQuery,
-  ObjectQueryPredicate,
   ObjectQueryResultShape,
   ObjectQuerySortField,
-  QueryScalarKind,
 } from "./ir"
+import { matchesPredicate } from "./matches-predicate"
 import { normalizeObjectQuery } from "./normalize"
 import { type ObjectQueryPlan, type ObjectQueryPlanningOptions, planObjectQuery } from "./planner"
 import { usePrimaryIdLookups } from "./primary-id"
 import { rerankObjectCandidates } from "./reranking-executor"
 import { findQueryReranking } from "./reranking-query"
-import { compareQueryScalarValues, queryScalarValuesEqual } from "./scalar-values"
+import { compareQueryScalarValues } from "./scalar-values"
+import { withoutUserExpansions } from "./user-expansions"
 import {
   type AdmittedObjectQuery,
   type ObjectQuerySemanticAdmission,
@@ -76,8 +78,22 @@ export interface QueryExecutorOptions
   authorization?: AuthorizationContext
   /** Registered execution capability for queries reached through a bound Sixb SDK. */
   runtimeAuthorization?: RuntimeAuthorization
+  /**
+   * The object types the reader reads, decided by the reader itself. The authorized object reader
+   * passes its own, which hold the types its storage reads through a condition. When present, it
+   * decides in place of the grants of `authorization` and `runtimeAuthorization`.
+   */
+  readableObjectTypes?: ReadableObjectTypes
   /** Reader-specific admission applied after grants, such as marking clearances. */
   admission?: ObjectQuerySemanticAdmission
+  /** The user `currentUser()` stands for; absent when the reader is not a user. */
+  requestingUser?: UserRef
+}
+
+export interface ReadableObjectTypes {
+  /** Throw unless the reader reads every one of these object types. */
+  assert(objectTypeIds: readonly string[]): void
+  has(objectTypeId: string): boolean
 }
 
 export interface ExecuteObjectQueryInput {
@@ -413,11 +429,13 @@ export async function facetObjects(
 }
 
 /**
- * Validate, authorize the touched types, then admit the query for the reader.
+ * Validate, authorize the touched types, admit the query for the reader, then bind
+ * `currentUser()` to the reader's user.
  *
  * Grants are checked first so a denial never describes properties of a type the caller cannot
  * view. The admitted query is the one executed: an admission may narrow it, as markings narrow
- * default text fields.
+ * default text fields. Its user expansions are removed: storage never resolves profiles. Binding
+ * comes last, so storage and the fallback never see the placeholder.
  */
 function validateExecutableQuery(
   input: { readonly projectId: string; readonly query: ObjectQuery },
@@ -433,8 +451,13 @@ function validateExecutableQuery(
   const normalized = normalizeObjectQuery(input.query)
   const validated = validateObjectQuery(normalized, validationOptions)
   assertQueryViewable(input.projectId, validated, options)
-  if (!options.admission) return { ...validated, admissionState: {} }
-  return validateObjectQueryWithAdmission(normalized, validationOptions, options.admission)
+
+  const admitted = options.admission
+    ? validateObjectQueryWithAdmission(normalized, validationOptions, options.admission)
+    : { ...validated, admissionState: {} }
+
+  const executable = withoutUserExpansions(admitted.query)
+  return { ...admitted, query: bindCurrentUser(executable, options.requestingUser) }
 }
 
 // Authorization happens at planning time: a scoped query must hold a view
@@ -442,8 +465,16 @@ function validateExecutableQuery(
 function assertQueryViewable(
   projectId: string,
   validated: ValidatedObjectQuery,
-  authorization: Pick<QueryExecutorOptions, "authorization" | "runtimeAuthorization">
+  authorization: Pick<
+    QueryExecutorOptions,
+    "authorization" | "runtimeAuthorization" | "readableObjectTypes"
+  >
 ): void {
+  if (authorization.readableObjectTypes) {
+    authorization.readableObjectTypes.assert(validated.touchedObjectTypeIds)
+    return
+  }
+
   // The query engine is also a storage-level utility. Authorization is activated by a runtime
   // context; execution SDKs always provide a registered capability, including auth-disabled ones.
   if (!authorization.runtimeAuthorization && !authorization.authorization) return
@@ -1088,97 +1119,6 @@ function completeFallbackEvaluation(entries: FallbackEntry[]): FallbackEvaluatio
   }
 }
 
-function matchesPredicate(row: ObjectRow, predicate: ObjectQueryPredicate): boolean {
-  switch (predicate.op) {
-    case "and":
-      return predicate.items.every((item) => matchesPredicate(row, item))
-    case "or":
-      return predicate.items.some((item) => matchesPredicate(row, item))
-    case "not":
-      return !matchesPredicate(row, predicate.item)
-    case "eq":
-      return queryScalarValuesEqual(
-        row.properties[predicate.propertyId],
-        predicate.value,
-        predicate.scalarKind
-      )
-    case "neq":
-      return !queryScalarValuesEqual(
-        row.properties[predicate.propertyId],
-        predicate.value,
-        predicate.scalarKind
-      )
-    case "lt":
-      return (
-        compareQueryScalarValues(
-          row.properties[predicate.propertyId],
-          predicate.value,
-          predicate.scalarKind
-        ) < 0
-      )
-    case "lte":
-      return (
-        compareQueryScalarValues(
-          row.properties[predicate.propertyId],
-          predicate.value,
-          predicate.scalarKind
-        ) <= 0
-      )
-    case "gt":
-      return (
-        compareQueryScalarValues(
-          row.properties[predicate.propertyId],
-          predicate.value,
-          predicate.scalarKind
-        ) > 0
-      )
-    case "gte":
-      return (
-        compareQueryScalarValues(
-          row.properties[predicate.propertyId],
-          predicate.value,
-          predicate.scalarKind
-        ) >= 0
-      )
-    case "in":
-      return predicate.values.some((value) =>
-        queryScalarValuesEqual(row.properties[predicate.propertyId], value, predicate.scalarKind)
-      )
-    case "exists": {
-      const exists =
-        Object.hasOwn(row.properties, predicate.propertyId) &&
-        row.properties[predicate.propertyId] !== undefined
-      return predicate.value ? exists : !exists
-    }
-    case "contains":
-      return containsValue(
-        row.properties[predicate.propertyId],
-        predicate.value,
-        predicate.scalarKind
-      )
-  }
-}
-
-function containsValue(
-  actual: unknown,
-  expected: unknown,
-  itemScalarKind: QueryScalarKind | undefined
-): boolean {
-  if (typeof actual === "string" && typeof expected === "string") {
-    return actual.includes(expected)
-  }
-
-  if (Array.isArray(actual)) {
-    return actual.some((item) => queryScalarValuesEqual(item, expected, itemScalarKind))
-  }
-
-  if (isPlainObject(actual) && typeof expected === "string") {
-    return Object.hasOwn(actual, expected)
-  }
-
-  return false
-}
-
 function sortEntries(
   entries: readonly FallbackEntry[],
   fields: readonly ObjectQuerySortField[]
@@ -1432,7 +1372,3 @@ function decodePageOffset(token: string | undefined): number {
   }
   return offset
 }
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}

package/src/objects/query/explain.ts

@@ -199,20 +199,31 @@ function buildExplainNode(query: ObjectQuery, path: string): ObjectQueryExplainN
       return {
         path,
         kind: query.kind,
-        summary: `expand ${query.expansions.map(summarizeExpansion).join(", ")}`,
-        details: { expansions: query.expansions },
+        summary: `expand ${summarizeExpanded(query.expansions, query.users).join(", ")}`,
+        details: {
+          expansions: query.expansions,
+          ...(query.users === undefined ? {} : { users: query.users }),
+        },
         children: [buildExplainNode(query.input, `${path}.input`)],
       }
   }
 }
 
+// Links by id, then user properties as `@property`.
+function summarizeExpanded(
+  expansions: readonly ObjectExpansion[],
+  users: readonly string[] | undefined
+): string[] {
+  return [
+    ...expansions.map(summarizeExpansion),
+    ...(users ?? []).map((propertyId) => `@${propertyId}`),
+  ]
+}
+
 function summarizeExpansion(expansion: ObjectExpansion): string {
   const head = expansion.direction === "incoming" ? `<-${expansion.linkId}` : expansion.linkId
-  const nested =
-    expansion.expand && expansion.expand.length > 0
-      ? `(${expansion.expand.map(summarizeExpansion).join(", ")})`
-      : ""
-  return `${head}${nested}`
+  const nested = summarizeExpanded(expansion.expand ?? [], expansion.users)
+  return nested.length > 0 ? `${head}(${nested.join(", ")})` : head
 }
 
 function summarizePredicate(predicate: ObjectQueryPredicate): string {
@@ -228,6 +239,8 @@ function summarizePredicate(predicate: ObjectQueryPredicate): string {
       return `${predicate.propertyId} exists=${predicate.value}`
     case "contains":
       return `${predicate.propertyId} contains`
+    case "constant":
+      return String(predicate.value)
     default:
       return `${predicate.propertyId} ${predicate.op}`
   }

package/src/objects/query/index.ts

@@ -16,6 +16,7 @@ export type {
   ExecuteObjectQueryInput,
   ExecuteObjectQueryResult,
   QueryExecutorOptions,
+  ReadableObjectTypes,
 } from "./executor"
 export {
   countObjects,
@@ -40,6 +41,7 @@ export type {
   ObjectQueryPage,
   ObjectQueryPredicate,
   ObjectQueryPredicateComparison,
+  ObjectQueryPredicateConstant,
   ObjectQueryPredicateContains,
   ObjectQueryPredicateExists,
   ObjectQueryPredicateGroup,

package/src/objects/query/ir.ts

@@ -155,6 +155,12 @@ export interface ObjectQueryExpand {
   kind: "expand"
   input: ObjectQuery
   expansions: readonly ObjectExpansion[]
+  /**
+   * `ref.user()` properties whose members' profiles attach under each row's `users`, keyed by
+   * property id. Profiles come from the member directory, not object storage: the core executor
+   * removes this field before planning, so storage providers never receive it.
+   */
+  users?: readonly string[]
 }
 
 export interface ObjectExpansion {
@@ -169,6 +175,8 @@ export interface ObjectExpansion {
   orderBy?: readonly ObjectQuerySortField[]
   /** Nested expansions, hydrated from the target objects of this expansion. */
   expand?: readonly ObjectExpansion[]
+  /** `ref.user()` properties of the target objects whose profiles attach under their `users`. */
+  users?: readonly string[]
   /**
    * Resolved link cardinality, driving the attached value shape: `"one"` yields a
    * single object (or `null`), `"many"` yields an array.
@@ -189,6 +197,7 @@ export type ObjectQueryPredicate =
   | ObjectQueryPredicateIn
   | ObjectQueryPredicateExists
   | ObjectQueryPredicateContains
+  | ObjectQueryPredicateConstant
 
 export interface ObjectQueryPredicateGroup {
   op: "and" | "or"
@@ -233,6 +242,17 @@ export interface ObjectQueryPredicateContains {
   scalarKind?: QueryScalarKind
 }
 
+/**
+ * Matches every row or none, reading no property.
+ *
+ * Core-produced, never authored: binding a query can settle a predicate before storage runs it,
+ * and a literal lets the database planner skip the scan. The HTTP schema does not accept it.
+ */
+export interface ObjectQueryPredicateConstant {
+  op: "constant"
+  value: boolean
+}
+
 export type ObjectQuerySortField =
   | {
       kind: "property"

package/src/objects/query/link-query-clearance.ts

@@ -0,0 +1,73 @@
+import type { OntologyRegistry } from "../../ontology"
+import { type PropertyClearance, unreadableError } from "../property-clearance"
+import type { ObjectQuery } from "./ir"
+import { type ExecuteObjectQueryLinksInput, preflightObjectQueryLinks } from "./links"
+
+/**
+ * Refuse a link query that could return a link, or an endpoint, the reader cannot read.
+ *
+ * A link query returns every link incident to the objects it selects, a page at a time. The page
+ * cannot be filtered afterward without breaking its cursor, so what the reader cannot read is
+ * refused before the page is read, from the definitions: a link that is unreadable, or that leads
+ * to an unreadable object type, whether or not such a link exists.
+ */
+export function assertLinkQueryReadable(input: {
+  readonly ontology: OntologyRegistry
+  readonly clearance: PropertyClearance
+  readonly query: ObjectQuery
+  readonly request: Omit<ExecuteObjectQueryLinksInput, "query">
+  /** Whether grants alone let the reader view the type: storage already leaves out the others. */
+  readonly viewableByGrants: (objectTypeId: string) => boolean
+}): void {
+  const { ontology, clearance } = input
+  const { types, links } = clearance.unreadable()
+  if (types.size === 0 && links.length === 0) return
+
+  const preflight = preflightObjectQueryLinks(
+    { ...input.request, query: input.query },
+    { ontology }
+  )
+
+  const selected = preflight.validated.result.objectTypeIds
+  const outgoing = preflight.direction !== "incoming"
+  const incoming = preflight.direction !== "outgoing"
+
+  const named = (linkId: string) => preflight.linkId === undefined || preflight.linkId === linkId
+  const targets = (expected: string | readonly string[], objectTypeId: string) =>
+    (typeof expected === "string" ? [expected] : expected).some((target) =>
+      ontology.isValidLinkTarget(target, objectTypeId)
+    )
+
+  for (const link of links) {
+    if (!named(link.linkId)) continue
+    if (
+      (outgoing && selected.includes(link.objectTypeId)) ||
+      (incoming && selected.some((id) => targets(link.targetObjectTypeId, id)))
+    ) {
+      throw unreadableError(link)
+    }
+  }
+
+  const sealed = [...types].filter(([id]) => input.viewableByGrants(id))
+  if (sealed.length === 0) return
+
+  for (const objectType of ontology.listObjectTypes()) {
+    for (const link of objectType.links) {
+      if (!named(link.id)) continue
+      if (outgoing && selected.includes(objectType.id)) {
+        const other = sealed.find(([id]) => targets(link.targetObjectTypeId, id))
+        if (other) throw unreadableError(other[1])
+      }
+
+      const source = types.get(objectType.id)
+      if (
+        incoming &&
+        source &&
+        input.viewableByGrants(objectType.id) &&
+        selected.some((id) => targets(link.targetObjectTypeId, id))
+      ) {
+        throw unreadableError(source)
+      }
+    }
+  }
+}

package/src/objects/query/links.ts

@@ -249,6 +249,14 @@ function assertLinkSelectorShape(query: ObjectQuery, path = "$.query", root = tr
 }
 
 function visibleEndpointTypeIds(options: QueryExecutorOptions): readonly string[] | undefined {
+  const readable = options.readableObjectTypes
+  if (readable) {
+    return options.ontology
+      .listObjectTypes()
+      .map((objectType) => objectType.id)
+      .filter((objectTypeId) => readable.has(objectTypeId))
+  }
+
   if (!options.authorization) return undefined
   return options.ontology
     .listObjectTypes()

package/src/objects/query/matches-predicate.ts

@@ -0,0 +1,108 @@
+import type { ObjectRow } from "../../storage"
+import type { ObjectQueryPredicate, QueryScalarKind } from "./ir"
+import { compareQueryScalarValues, queryScalarValuesEqual } from "./scalar-values"
+
+/**
+ * Whether an object's properties match a validated predicate, with the semantics every object
+ * storage implements: the in-memory store and the query executor's fallback evaluate it here, and
+ * so does anything that decides on an object's state without reading it.
+ */
+export function matchesPredicate(
+  row: Pick<ObjectRow, "properties">,
+  predicate: ObjectQueryPredicate
+): boolean {
+  switch (predicate.op) {
+    case "and":
+      return predicate.items.every((item) => matchesPredicate(row, item))
+    case "or":
+      return predicate.items.some((item) => matchesPredicate(row, item))
+    case "not":
+      return !matchesPredicate(row, predicate.item)
+    case "constant":
+      return predicate.value
+    case "eq":
+      return queryScalarValuesEqual(
+        row.properties[predicate.propertyId],
+        predicate.value,
+        predicate.scalarKind
+      )
+    case "neq":
+      return !queryScalarValuesEqual(
+        row.properties[predicate.propertyId],
+        predicate.value,
+        predicate.scalarKind
+      )
+    case "lt":
+      return (
+        compareQueryScalarValues(
+          row.properties[predicate.propertyId],
+          predicate.value,
+          predicate.scalarKind
+        ) < 0
+      )
+    case "lte":
+      return (
+        compareQueryScalarValues(
+          row.properties[predicate.propertyId],
+          predicate.value,
+          predicate.scalarKind
+        ) <= 0
+      )
+    case "gt":
+      return (
+        compareQueryScalarValues(
+          row.properties[predicate.propertyId],
+          predicate.value,
+          predicate.scalarKind
+        ) > 0
+      )
+    case "gte":
+      return (
+        compareQueryScalarValues(
+          row.properties[predicate.propertyId],
+          predicate.value,
+          predicate.scalarKind
+        ) >= 0
+      )
+    case "in":
+      return predicate.values.some((value) =>
+        queryScalarValuesEqual(row.properties[predicate.propertyId], value, predicate.scalarKind)
+      )
+    case "exists": {
+      const exists =
+        Object.hasOwn(row.properties, predicate.propertyId) &&
+        row.properties[predicate.propertyId] !== undefined
+      return predicate.value ? exists : !exists
+    }
+    case "contains":
+      return containsValue(
+        row.properties[predicate.propertyId],
+        predicate.value,
+        predicate.scalarKind
+      )
+  }
+}
+
+function containsValue(
+  actual: unknown,
+  expected: unknown,
+  itemScalarKind: QueryScalarKind | undefined
+): boolean {
+  if (typeof actual === "string" && typeof expected === "string") {
+    return actual.includes(expected)
+  }
+
+  if (Array.isArray(actual)) {
+    return actual.some((item) => queryScalarValuesEqual(item, expected, itemScalarKind))
+  }
+
+  if (isPlainObject(actual) && typeof expected === "string") {
+    return Object.hasOwn(actual, expected)
+  }
+
+  return false
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/objects/query/normalize.ts

@@ -1,6 +1,7 @@
 import type {
   ObjectExpansion,
   ObjectQuery,
+  ObjectQueryExpand,
   ObjectQueryPredicate,
   ObjectQuerySet,
   ObjectQuerySortField,
@@ -63,7 +64,7 @@ function normalizeNode(query: ObjectQuery): ObjectQuery {
         properties: query.properties ? uniqueStrings(query.properties) : undefined,
       }
     case "expand":
-      return normalizeExpand(query.input, query.expansions)
+      return normalizeExpand(query)
   }
 }
 
@@ -87,30 +88,45 @@ function hoistExpand(query: ObjectQuery): ObjectQuery {
   const inner = query.input
   const rebuilt = normalizeObjectQuery({ ...query, input: inner.input })
   if (rebuilt.kind === "expand") {
-    return {
-      kind: "expand",
-      input: rebuilt.input,
-      expansions: normalizeExpansions([...inner.expansions, ...rebuilt.expansions]),
-    }
+    return expandNode(
+      rebuilt.input,
+      normalizeExpansions([...inner.expansions, ...rebuilt.expansions]),
+      uniqueSortedStrings([...(inner.users ?? []), ...(rebuilt.users ?? [])])
+    )
   }
-  return { kind: "expand", input: rebuilt, expansions: inner.expansions }
+  return expandNode(rebuilt, inner.expansions, inner.users ?? [])
 }
 
-function normalizeExpand(input: ObjectQuery, expansions: readonly ObjectExpansion[]): ObjectQuery {
-  const normalizedInput = normalizeObjectQuery(input)
-  const normalizedExpansions = normalizeExpansions(expansions)
+function normalizeExpand(query: ObjectQueryExpand): ObjectQuery {
+  const normalizedInput = normalizeObjectQuery(query.input)
+  const normalizedExpansions = normalizeExpansions(query.expansions)
+  const users = uniqueSortedStrings(query.users ?? [])
 
   // A directly-nested expand (`a.expand(X).expand(Y)` builds
   // `expand(expand(start, [X]), [Y])`) collapses into one outermost expand.
   if (normalizedInput.kind === "expand") {
-    return {
-      kind: "expand",
-      input: normalizedInput.input,
-      expansions: normalizeExpansions([...normalizedInput.expansions, ...normalizedExpansions]),
-    }
+    return expandNode(
+      normalizedInput.input,
+      normalizeExpansions([...normalizedInput.expansions, ...normalizedExpansions]),
+      uniqueSortedStrings([...(normalizedInput.users ?? []), ...users])
+    )
   }
 
-  return { kind: "expand", input: normalizedInput, expansions: normalizedExpansions }
+  return expandNode(normalizedInput, normalizedExpansions, users)
+}
+
+// `users` is left out when empty, so a query that expands no user property keeps its usual shape.
+function expandNode(
+  input: ObjectQuery,
+  expansions: readonly ObjectExpansion[],
+  users: readonly string[]
+): ObjectQueryExpand {
+  return {
+    kind: "expand",
+    input,
+    expansions,
+    ...(users.length > 0 ? { users } : {}),
+  }
 }
 
 function normalizeExpansions(expansions: readonly ObjectExpansion[]): ObjectExpansion[] {
@@ -129,8 +145,11 @@ function normalizeExpansions(expansions: readonly ObjectExpansion[]): ObjectExpa
   })
 }
 
+// Every field is copied by name: a new `ObjectExpansion` field must be added here, or
+// normalization drops it.
 function normalizeExpansion(expansion: ObjectExpansion): ObjectExpansion {
   const nested = expansion.expand ? normalizeExpansions(expansion.expand) : []
+  const users = uniqueSortedStrings(expansion.users ?? [])
   return {
     linkId: expansion.linkId,
     direction: expansion.direction,
@@ -140,15 +159,22 @@ function normalizeExpansion(expansion: ObjectExpansion): ObjectExpansion {
     ...(expansion.limit !== undefined ? { limit: expansion.limit } : {}),
     ...(expansion.orderBy ? { orderBy: expansion.orderBy.map((field) => ({ ...field })) } : {}),
     ...(nested.length > 0 ? { expand: nested } : {}),
+    ...(users.length > 0 ? { users } : {}),
   }
 }
 
 // Two expansions of the same link in the same direction are one hydration; their
-// nested expansions merge so the normalized tree never double-hydrates a link.
+// nested expansions and user properties merge so the normalized tree never
+// double-hydrates a link.
 function mergeExpansion(a: ObjectExpansion, b: ObjectExpansion): ObjectExpansion {
   const nested = normalizeExpansions([...(a.expand ?? []), ...(b.expand ?? [])])
-  const { expand: _existing, ...base } = a
-  return nested.length > 0 ? { ...base, expand: nested } : base
+  const users = uniqueSortedStrings([...(a.users ?? []), ...(b.users ?? [])])
+  const { expand: _expand, users: _users, ...base } = a
+  return {
+    ...base,
+    ...(nested.length > 0 ? { expand: nested } : {}),
+    ...(users.length > 0 ? { users } : {}),
+  }
 }
 
 function expansionKey(expansion: ObjectExpansion): string {
@@ -254,6 +280,11 @@ function uniqueStrings(values: readonly string[]): string[] {
   return [...new Set(values)]
 }
 
+// Expanded user properties are a set: sorting them gives equivalent queries one cache key.
+function uniqueSortedStrings(values: readonly string[]): string[] {
+  return uniqueStrings(values).sort(compareStrings)
+}
+
 function uniqueRefs(
   refs: readonly { objectTypeId: string; primaryId: string }[]
 ): { objectTypeId: string; primaryId: string }[] {

package/src/objects/query/scalar-values.ts

@@ -112,8 +112,24 @@ function dateTime(value: unknown): number | null {
   return null
 }
 
+/**
+ * Code-point order, as SQLite's BINARY and PostgreSQL's "C" collation compare UTF-8 bytes.
+ * JavaScript's `<` compares UTF-16 code units, which puts a surrogate pair (U+10000 and above)
+ * before U+E000–U+FFFF; only that range needs its units remapped.
+ */
 function compareStrings(left: string, right: string): number {
-  if (left < right) return -1
-  if (left > right) return 1
-  return 0
+  if (left === right) return 0
+
+  const length = Math.min(left.length, right.length)
+  let index = 0
+  while (index < length && left.charCodeAt(index) === right.charCodeAt(index)) index++
+  if (index === length) return left.length - right.length
+
+  return codePointRank(left.charCodeAt(index)) - codePointRank(right.charCodeAt(index))
+}
+
+function codePointRank(unit: number): number {
+  if (unit >= 0xe000) return unit - 0x800
+  if (unit >= 0xd800) return unit + 0x2000
+  return unit
 }