@sixb/pg 0.1.7 → 0.1.8

package/src/objects/rows.ts

@@ -0,0 +1,146 @@
+import type {
+  ExpandedLinkValue,
+  ExpandedObjectRow,
+  ObjectLinkRow,
+  ObjectRow,
+  ObjectRowLinks,
+} from "@sixb/core/storage"
+
+export function rowToObject(row: ObjectDatabaseRow): ObjectRow {
+  return {
+    projectId: row.project_id,
+    objectTypeId: row.object_type_id,
+    primaryId: row.primary_id,
+    properties: row.properties as Record<string, unknown>,
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at),
+    version: row.version,
+    lastCommitId: row.last_commit_id,
+  }
+}
+
+// Map a query row, attaching `links` when an `expand` pushdown produced them. The
+// base columns map as usual; `_expand` (a `jsonb_build_object`) is revived into
+// the runtime link shape the core executor's fallback also produces.
+export function queryRowToObject(row: ObjectQueryDatabaseRow): ObjectRow {
+  const base = rowToObject(row)
+  const links = reviveExpandedLinks(row._expand)
+  return links ? { ...base, links } : base
+}
+
+function reviveExpandedLinks(value: unknown): ObjectRowLinks | undefined {
+  if (!isPlainRecord(value)) return undefined
+  const links: ObjectRowLinks = {}
+  for (const [linkId, raw] of Object.entries(value)) {
+    links[linkId] = reviveExpandedLinkValue(raw)
+  }
+  return links
+}
+
+// A "one" expansion arrives as a single object or null; a "many" expansion as an
+// array (already ordered and trimmed in the database).
+function reviveExpandedLinkValue(value: unknown): ExpandedLinkValue {
+  if (value === null || value === undefined) return null
+  if (Array.isArray(value)) return value.map(reviveExpandedRow)
+  return reviveExpandedRow(value)
+}
+
+// Revive one hydrated neighbour from `compileExpansionChildJson`: JSONB timestamp
+// strings back to `Date`, empty link properties dropped (matching the fallback),
+// and nested links recursed.
+function reviveExpandedRow(value: unknown): ExpandedObjectRow {
+  const row = isPlainRecord(value) ? value : {}
+  const expanded: ExpandedObjectRow = {
+    projectId: String(row.projectId),
+    objectTypeId: String(row.objectTypeId),
+    primaryId: String(row.primaryId),
+    properties: isPlainRecord(row.properties) ? row.properties : {},
+    createdAt: new Date(row.createdAt as string),
+    updatedAt: new Date(row.updatedAt as string),
+    version: Number(row.version),
+    lastCommitId: String(row.lastCommitId),
+  }
+  if (isPlainRecord(row.linkProperties) && Object.keys(row.linkProperties).length > 0) {
+    expanded.linkProperties = row.linkProperties
+  }
+  const links = reviveExpandedLinks(row.links)
+  if (links) expanded.links = links
+  return expanded
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export function rowToLink(row: LinkDatabaseRow): ObjectLinkRow {
+  return {
+    projectId: row.project_id,
+    sourceTypeId: row.source_type_id,
+    sourceId: row.source_id,
+    linkId: row.link_id,
+    targetTypeId: row.target_type_id,
+    targetId: row.target_id,
+    ...(row.properties === null ? {} : { properties: row.properties as Record<string, unknown> }),
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at),
+    lastCommitId: row.last_commit_id,
+  }
+}
+
+export function linkIdentity(link: ObjectLinkRow): string {
+  return JSON.stringify([
+    link.sourceTypeId,
+    link.sourceId,
+    link.linkId,
+    link.targetTypeId,
+    link.targetId,
+  ])
+}
+
+export interface ObjectDatabaseRow {
+  project_id: string
+  object_type_id: string
+  primary_id: string
+  properties: unknown
+  created_at: Date | string
+  updated_at: Date | string
+  version: number
+  last_commit_id: string
+}
+
+export interface ObjectQueryDatabaseRow extends ObjectDatabaseRow {
+  _cursor_properties?: unknown
+  /** `jsonb_build_object(linkId, value, ...)` from an `expand` pushdown; absent otherwise. */
+  _expand?: unknown
+}
+
+export interface ObjectBatchDatabaseRow extends ObjectDatabaseRow {
+  _batch_index: number
+}
+
+export interface PropertyPermissionBatchDatabaseRow {
+  _batch_index: number
+}
+
+export interface FacetDatabaseRow {
+  value_type: string | null
+  value_text: string | null
+  count: string | number | bigint
+}
+
+export interface LinkDatabaseRow {
+  project_id: string
+  source_type_id: string
+  source_id: string
+  link_id: string
+  target_type_id: string
+  target_id: string
+  properties: unknown | null
+  created_at: Date | string
+  updated_at: Date | string
+  last_commit_id: string
+}
+
+export interface LinkBatchDatabaseRow extends LinkDatabaseRow {
+  _batch_index: number
+}

package/src/objects/selected-reader.ts

@@ -0,0 +1,118 @@
+import type {
+  CompiledSelectedObjectReadScope,
+  ObjectQueryCapabilities,
+  ObjectReadExecutionLimits,
+  ObjectReadStorage,
+} from "@sixb/core/storage"
+import {
+  assertObjectReaderProject,
+  assertObjectReadFacetCount,
+  assertObjectReadOutputWithinLimit,
+  ObjectReadLimitExceededError,
+  snapshotObjectReadExecutionLimits,
+} from "@sixb/core/storage"
+import type { SQLClient, SqlParameter } from "../pg-client"
+import { type PgStoreClient, runPgRepeatableReadTransaction } from "../transactions"
+import { compilePgSelectedObjectReadSource, type PgSelectedObjectReadSource } from "./read-scope"
+
+import { assertLinkQueryLimit, PgObjectReader } from "./reader"
+
+export function createPgSelectedReader(
+  sql: PgStoreClient,
+  params: {
+    projectId: string
+    scope: CompiledSelectedObjectReadScope
+    limits: ObjectReadExecutionLimits
+  },
+  queryCapabilities: () => ObjectQueryCapabilities
+): ObjectReadStorage {
+  const projectId = params.projectId
+  const limits = snapshotObjectReadExecutionLimits(params.limits)
+  const source = compilePgSelectedObjectReadSource(
+    projectId,
+    params.scope,
+    limits.maxTraversalFacts
+  )
+  const assertProject = (actualProjectId: string): void =>
+    assertObjectReaderProject(projectId, actualProjectId)
+  const read = <T>(run: (reader: PgObjectReader) => Promise<T>): Promise<T> =>
+    runPgRepeatableReadTransaction(sql, async (tx) => {
+      await assertTraversalBudget(tx, source, limits.maxTraversalFacts)
+      const value = await run(new PgObjectReader(tx, source))
+      assertObjectReadOutputWithinLimit(value, limits)
+      return value
+    })
+  const readMap = <TKey, TValue>(
+    run: (reader: PgObjectReader) => Promise<Map<TKey, TValue>>
+  ): Promise<Map<TKey, TValue>> =>
+    runPgRepeatableReadTransaction(sql, async (tx) => {
+      await assertTraversalBudget(tx, source, limits.maxTraversalFacts)
+      const value = await run(new PgObjectReader(tx, source))
+      assertObjectReadOutputWithinLimit([...value.entries()], limits)
+      return value
+    })
+
+  return Object.freeze({
+    queryCapabilities,
+    queryObjects: async (input) => {
+      assertProject(input.projectId)
+      return read((reader) => reader.queryObjects(input))
+    },
+    countObjects: async (input) => {
+      assertProject(input.projectId)
+      return read((reader) => reader.countObjects(input))
+    },
+    existsObjects: async (input) => {
+      assertProject(input.projectId)
+      return read((reader) => reader.existsObjects(input))
+    },
+    facetObjects: async (input) => {
+      assertProject(input.projectId)
+      assertObjectReadFacetCount(input.facets.length)
+      return read((reader) => reader.facetObjects(input))
+    },
+    getByPrimaryId: async (input) => {
+      assertProject(input.projectId)
+      return read((reader) => reader.getByPrimaryId(input))
+    },
+    selectsObjectProperties: async (input) => {
+      assertProject(input.projectId)
+      return read((reader) => reader.selectsObjectProperties(input))
+    },
+    listLinks: async (input) => {
+      assertProject(input.projectId)
+      return read((reader) => reader.listLinks(input))
+    },
+    getByPrimaryIdBatch: async (input) => {
+      assertProject(input.projectId)
+      return readMap((reader) => reader.getByPrimaryIdBatch(input))
+    },
+    listLinksBatch: async (input) => {
+      assertProject(input.projectId)
+      return readMap((reader) => reader.listLinksBatch(input))
+    },
+    queryLinks: async (input) => {
+      assertProject(input.projectId)
+      assertLinkQueryLimit(input.limit)
+      return read((reader) => reader.queryLinks(input))
+    },
+    list: async (input) => {
+      assertProject(input.projectId)
+      return read((reader) => reader.list(input))
+    },
+  } satisfies ObjectReadStorage)
+}
+
+async function assertTraversalBudget(
+  sql: SQLClient,
+  source: PgSelectedObjectReadSource,
+  maxTraversalFacts: number
+): Promise<void> {
+  const [row] = await sql.unsafe<{ total: string | number | bigint }[]>(
+    source.traversalProbe.sql,
+    source.traversalProbe.args as SqlParameter[]
+  )
+  if (BigInt(row?.total ?? 0) > BigInt(maxTraversalFacts)) {
+    throw new ObjectReadLimitExceededError("traversalFacts", maxTraversalFacts)
+  }
+}

package/src/objects/storage.ts

@@ -0,0 +1,305 @@
+import type {
+  CompiledSelectedObjectReadScope,
+  CountObjectsInput,
+  CountObjectsResult,
+  ExistsObjectsInput,
+  ExistsObjectsResult,
+  FacetObjectsInput,
+  FacetObjectsResult,
+  LinkBatchKey,
+  LinkDirection,
+  ObjectBatchKey,
+  ObjectLinkRow,
+  ObjectQueryCapabilities,
+  ObjectReadExecutionLimits,
+  ObjectReadStorage,
+  ObjectRow,
+  ObjectStorage,
+  QueryObjectLinksInput,
+  QueryObjectLinksResult,
+  QueryObjectsInput,
+  QueryObjectsResult,
+} from "@sixb/core/storage"
+import type { SQLClient, SqlParameter } from "../pg-client"
+import type { PgStoreClient } from "../transactions"
+import { DEFAULT_OBJECT_QUERY_SOURCE } from "./query-compiler"
+import { assertLinkQueryLimit, PgObjectReader } from "./reader"
+import {
+  type LinkDatabaseRow,
+  linkIdentity,
+  type ObjectDatabaseRow,
+  rowToLink,
+  rowToObject,
+} from "./rows"
+import { createPgSelectedReader } from "./selected-reader"
+
+const PG_OBJECT_QUERY_CAPABILITIES: ObjectQueryCapabilities = {
+  queryObjects: true,
+  countObjects: true,
+  existsObjects: true,
+  facetObjects: true,
+  nodes: {
+    start: true,
+    refs: true,
+    filter: true,
+    text: true,
+    sort: true,
+    limit: true,
+    page: true,
+    traverse: true,
+    set: true,
+    project: true,
+    expand: true,
+  },
+  predicateOps: {
+    and: true,
+    or: true,
+    not: true,
+    eq: true,
+    neq: true,
+    lt: true,
+    lte: true,
+    gt: true,
+    gte: true,
+    in: true,
+    exists: true,
+    contains: true,
+  },
+  sortKinds: {
+    property: true,
+  },
+  traversalDirections: {
+    outgoing: true,
+    incoming: true,
+  },
+  setOps: {
+    union: true,
+    intersect: true,
+    subtract: true,
+  },
+  scalarOperations: {
+    string: { equality: true, ordering: true },
+    uuid: { equality: true, ordering: true },
+    boolean: { equality: true },
+    integer: { equality: true, ordering: true },
+    double: { equality: true, ordering: true },
+    decimal: { equality: true, ordering: true },
+    date: { equality: true, ordering: true },
+    timestamp: { equality: true, ordering: true },
+  },
+  limits: {
+    totalCount: true,
+    stablePageTokens: true,
+  },
+  notes: [
+    "PostgreSQL object query pushdown supports start/refs/filter/text/sort/limit/page/traverse/set/project/expand over JSONB properties and object links.",
+    "expand hydrates linked objects in-database (top-N per parent via LATERAL + jsonb_agg); core resolves each expansion's cardinality before pushdown, and a mixed/unresolved one stays on the fallback.",
+    "Exact decimal predicates, ordering, and keyset pagination use PostgreSQL numeric casts.",
+    "Relevance sorting, vector search, and unresolved start.includeSubtypes remain planner fallback or rejection cases.",
+  ],
+}
+
+/** PostgreSQL object provider; interactive reads share one source-aware reader. */
+export class PgObjectStorage implements ObjectStorage {
+  private readonly reader: PgObjectReader
+
+  constructor(private readonly sql: PgStoreClient) {
+    this.reader = new PgObjectReader(sql, DEFAULT_OBJECT_QUERY_SOURCE)
+  }
+
+  queryCapabilities(): ObjectQueryCapabilities {
+    return PG_OBJECT_QUERY_CAPABILITIES
+  }
+
+  createSelectedReadScope(params: {
+    projectId: string
+    scope: CompiledSelectedObjectReadScope
+    limits: ObjectReadExecutionLimits
+  }): ObjectReadStorage {
+    return createPgSelectedReader(this.sql, params, () => this.queryCapabilities())
+  }
+
+  async queryObjects(params: QueryObjectsInput): Promise<QueryObjectsResult> {
+    return this.reader.queryObjects(params)
+  }
+
+  async countObjects(params: CountObjectsInput): Promise<CountObjectsResult> {
+    return this.reader.countObjects(params)
+  }
+
+  async existsObjects(params: ExistsObjectsInput): Promise<ExistsObjectsResult> {
+    return this.reader.existsObjects(params)
+  }
+
+  async facetObjects(params: FacetObjectsInput): Promise<FacetObjectsResult> {
+    return this.reader.facetObjects(params)
+  }
+
+  async getByPrimaryId(params: {
+    projectId: string
+    objectTypeId: string
+    primaryId: string
+  }): Promise<ObjectRow | null> {
+    return this.reader.getByPrimaryId(params)
+  }
+
+  async selectsObjectProperties(
+    params: Parameters<ObjectReadStorage["selectsObjectProperties"]>[0]
+  ): Promise<readonly boolean[]> {
+    return this.reader.selectsObjectProperties(params)
+  }
+
+  async listLinks(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    linkId?: string
+    direction?: LinkDirection
+  }): Promise<readonly ObjectLinkRow[]> {
+    return this.reader.listLinks(params)
+  }
+
+  async getByPrimaryIdBatch(params: {
+    projectId: string
+    items: readonly { objectTypeId: string; primaryId: string }[]
+  }): Promise<Map<ObjectBatchKey, ObjectRow>> {
+    return this.reader.getByPrimaryIdBatch(params)
+  }
+
+  async listLinksBatch(params: {
+    projectId: string
+    direction?: LinkDirection
+    items: readonly { objectTypeId: string; objectId: string; linkId: string }[]
+  }): Promise<Map<LinkBatchKey, ObjectLinkRow[]>> {
+    return this.reader.listLinksBatch(params)
+  }
+
+  async queryLinks(params: QueryObjectLinksInput): Promise<QueryObjectLinksResult> {
+    assertLinkQueryLimit(params.limit)
+    return this.reader.queryLinks(params)
+  }
+
+  async listIncidentLinksBatch(params: {
+    projectId: string
+    items: readonly { objectTypeId: string; objectId: string }[]
+  }): Promise<readonly ObjectLinkRow[]> {
+    if (params.items.length === 0) return []
+    const tuples = params.items.map((item) => [item.objectTypeId, item.objectId])
+
+    // Cover both link directions with two index-friendly equality joins (source-side, then
+    // target-side) rather than a single OR-join, which would defeat index usage. This is a constant
+    // number of round trips regardless of the requested object count. They are issued sequentially
+    // because callers may run on a serializable transaction's single connection. A link incident to
+    // two listed objects matches both halves and is de-duplicated below.
+    const sourceRows = await valuesJoin<LinkDatabaseRow>(
+      this.sql,
+      "SELECT l.* FROM links l",
+      ["source_type_id", "source_id"],
+      tuples,
+      "WHERE l.project_id = $1",
+      [params.projectId]
+    )
+    const targetRows = await valuesJoin<LinkDatabaseRow>(
+      this.sql,
+      "SELECT l.* FROM links l",
+      ["target_type_id", "target_id"],
+      tuples,
+      "WHERE l.project_id = $1",
+      [params.projectId]
+    )
+
+    const deduped = new Map<string, ObjectLinkRow>()
+    for (const row of [...sourceRows, ...targetRows]) {
+      const link = rowToLink(row)
+      deduped.set(linkIdentity(link), link)
+    }
+    return [...deduped.values()]
+  }
+
+  async listByPrimaryIdPage(params: {
+    projectId: string
+    objectTypeId: string
+    afterPrimaryId?: string
+    limit: number
+  }): Promise<{ objects: readonly ObjectRow[]; nextPrimaryId?: string }> {
+    assertReconciliationPageLimit(params.limit)
+    const rows = await this.sql<ObjectDatabaseRow[]>`
+      SELECT * FROM objects
+      WHERE project_id = ${params.projectId}
+        AND object_type_id = ${params.objectTypeId}
+        ${params.afterPrimaryId ? this.sql`AND primary_id > ${params.afterPrimaryId}` : this.sql``}
+      ORDER BY primary_id ASC
+      LIMIT ${params.limit + 1}
+    `
+    const hasMore = rows.length > params.limit
+    const objects = rows.slice(0, params.limit).map((row) => rowToObject(row))
+    const last = objects.at(-1)
+    return {
+      objects,
+      ...(hasMore && last ? { nextPrimaryId: last.primaryId } : {}),
+    }
+  }
+
+  async list(params: {
+    projectId: string
+    objectTypeId?: string | readonly string[]
+    primaryIdPrefix?: string
+    primaryIdSuffix?: string
+    updatedAfter?: Date
+    updatedBefore?: Date
+    createdAfter?: Date
+    createdBefore?: Date
+    limit?: number
+    offset?: number
+    orderBy?: "createdAt" | "updatedAt" | "primaryId"
+    order?: "asc" | "desc"
+  }): Promise<{ objects: readonly ObjectRow[]; hasMore: boolean; total: number }> {
+    return this.reader.list(params)
+  }
+}
+
+/**
+ * Build a `SELECT ... JOIN (VALUES ...) AS t(...) ON ... WHERE ...` query
+ * with positional parameters.  Bun SQL's tagged-template helpers don't
+ * support VALUES inside SELECT/JOIN, so we construct the query string
+ * manually while keeping all user data in the parameter array.
+ */
+function valuesJoin<Row = unknown>(
+  sql: SQLClient,
+  select: string,
+  columns: string[],
+  tuples: unknown[][],
+  where: string,
+  whereParams: unknown[]
+): Promise<Row[]> {
+  const alias = "t"
+  const colWidth = columns.length
+
+  // $1 … $N are reserved for the WHERE params that come first.
+  const base = whereParams.length
+  const valuePlaceholders = tuples
+    .map((_, i) => {
+      const cols = columns.map((_, j) => `$${base + i * colWidth + j + 1}`)
+      return `(${cols.join(",")})`
+    })
+    .join(",")
+
+  const onClause = columns
+    .map((c) => {
+      // Infer the table alias from the SELECT clause (first word after SELECT ... FROM)
+      const srcAlias = select.match(/FROM\s+\w+\s+(\w+)/i)?.[1] ?? select.split(" ").pop()
+      return `${srcAlias}.${c} = ${alias}.${c}`
+    })
+    .join(" AND ")
+
+  const query = `${select} JOIN (VALUES ${valuePlaceholders}) AS ${alias}(${columns.join(",")}) ON ${onClause} ${where}`
+  const params = [...whereParams, ...tuples.flat()]
+
+  return sql.unsafe(query, params as SqlParameter[]) as unknown as Promise<Row[]>
+}
+
+function assertReconciliationPageLimit(limit: number): void {
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new Error("Object reconciliation page limit must be a positive safe integer.")
+  }
+}

package/src/pg-execution-storage.ts

@@ -5,7 +5,12 @@ import {
   normalizeExecutionRecord,
   validateExecutionRecordReferences,
 } from "@sixb/core/internal/execution-storage"
-import type { CreateExecutionInput, ExecutionRecord, ExecutionStorage } from "@sixb/core/storage"
+import type {
+  CreateExecutionInput,
+  ExecutionRecord,
+  ExecutionStorage,
+  ShareSessionStorage,
+} from "@sixb/core/storage"
 import { ExecutionStorageError } from "@sixb/core/storage"
 import type { PgAuthStorage } from "./auth-storage"
 import { isUniqueViolation } from "./storage-errors"
@@ -14,7 +19,8 @@ import type { PgStoreClient } from "./transactions"
 export class PgExecutionStorage implements ExecutionStorage {
   constructor(
     private readonly sql: PgStoreClient,
-    private readonly auth: PgAuthStorage
+    private readonly auth: PgAuthStorage,
+    private readonly shareSessions: Pick<ShareSessionStorage, "getById">
   ) {}
 
   async create(input: CreateExecutionInput): Promise<ExecutionRecord> {
@@ -22,6 +28,7 @@ export class PgExecutionStorage implements ExecutionStorage {
     await validateExecutionRecordReferences(record, {
       auth: this.auth,
       getExecution: (params) => this.getById(params),
+      getShareSession: (params) => this.shareSessions.getById(params),
     })
     const row = executionRecordToStorageRow(record)
 
@@ -46,6 +53,9 @@ export class PgExecutionStorage implements ExecutionStorage {
           authority_primitive_kind,
           authority_primitive_id,
           authority_kernel_operation,
+          authority_delegation_kind,
+          authority_delegation_id,
+          authority_delegation_session_id,
           created_at
         ) VALUES (
           ${row.projectId},
@@ -66,6 +76,9 @@ export class PgExecutionStorage implements ExecutionStorage {
           ${row.authorityPrimitiveKind},
           ${row.authorityPrimitiveId},
           ${row.authorityKernelOperation},
+          ${row.authorityDelegationKind},
+          ${row.authorityDelegationId},
+          ${row.authorityDelegationSessionId},
           ${row.createdAt}
         )
         RETURNING *
@@ -120,6 +133,9 @@ function toStorageRow(row: PgExecutionRow): ExecutionStorageRow {
     authorityPrimitiveKind: row.authority_primitive_kind,
     authorityPrimitiveId: row.authority_primitive_id,
     authorityKernelOperation: row.authority_kernel_operation,
+    authorityDelegationKind: row.authority_delegation_kind,
+    authorityDelegationId: row.authority_delegation_id,
+    authorityDelegationSessionId: row.authority_delegation_session_id,
     createdAt: new Date(row.created_at),
   }
 }
@@ -143,5 +159,8 @@ interface PgExecutionRow {
   readonly authority_primitive_kind: ExecutionStorageRow["authorityPrimitiveKind"]
   readonly authority_primitive_id: string | null
   readonly authority_kernel_operation: ExecutionStorageRow["authorityKernelOperation"]
+  readonly authority_delegation_kind: ExecutionStorageRow["authorityDelegationKind"]
+  readonly authority_delegation_id: string | null
+  readonly authority_delegation_session_id: string | null
   readonly created_at: Date | string
 }