@sixb/pg 0.1.3 → 0.1.5

package/dist/pg-ai-usage-storage.d.ts

@@ -1,4 +1,4 @@
-import { type AiUsageExecutionSummary, type AiUsageStorage, type RecordAiModelCallInput, type RecordAiModelCallResult, type SummarizeAiUsageExecutionInput, type SummarizeAiUsageExecutionsInput } from "@sixb/core/storage";
+import { type AiModelCallUsageRecord, type AiUsageExecutionSummary, type AiUsageStorage, type GetLatestAiModelCallForExecutionInput, type RecordAiModelCallInput, type RecordAiModelCallResult, type SummarizeAiUsageExecutionInput, type SummarizeAiUsageExecutionsInput } from "@sixb/core/storage";
 import { type PgStoreClient } from "./transactions";
 /** PostgreSQL-backed append-only model-call usage ledger. */
 export declare class PgAiUsageStorage implements AiUsageStorage {
@@ -6,6 +6,7 @@ export declare class PgAiUsageStorage implements AiUsageStorage {
     constructor(sql: PgStoreClient);
     recordModelCall(input: RecordAiModelCallInput): Promise<RecordAiModelCallResult>;
     summarizeExecution(input: SummarizeAiUsageExecutionInput): Promise<AiUsageExecutionSummary>;
+    getLatestForExecution(input: GetLatestAiModelCallForExecutionInput): Promise<AiModelCallUsageRecord | null>;
     summarizeExecutions(input: SummarizeAiUsageExecutionsInput): Promise<readonly AiUsageExecutionSummary[]>;
     private findByIdempotencyKey;
     private requireById;

package/dist/pg-ai-usage-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pg-ai-usage-storage.d.ts","sourceRoot":"","sources":["../src/pg-ai-usage-storage.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EAKnB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACnC,KAAK,+BAA+B,EACrC,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,KAAK,aAAa,EAAoB,MAAM,gBAAgB,CAAA;AAErE,6DAA6D;AAC7D,qBAAa,gBAAiB,YAAW,cAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEzC,eAAe,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAgFhF,kBAAkB,CACtB,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,uBAAuB,CAAC;IAQ7B,mBAAmB,CACvB,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC;YAShC,oBAAoB;YAkBpB,WAAW;YAYX,WAAW;IA6BzB,OAAO,CAAC,aAAa;YAiBP,qBAAqB;CAgBpC"}
+{"version":3,"file":"pg-ai-usage-storage.d.ts","sourceRoot":"","sources":["../src/pg-ai-usage-storage.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EAInB,KAAK,qCAAqC,EAE1C,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACnC,KAAK,+BAA+B,EACrC,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,KAAK,aAAa,EAAoB,MAAM,gBAAgB,CAAA;AAErE,6DAA6D;AAC7D,qBAAa,gBAAiB,YAAW,cAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEzC,eAAe,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAgFhF,kBAAkB,CACtB,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,uBAAuB,CAAC;IAQ7B,qBAAqB,CACzB,KAAK,EAAE,qCAAqC,GAC3C,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAYnC,mBAAmB,CACvB,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC;YAShC,oBAAoB;YAkBpB,WAAW;YAYX,WAAW;IA6BzB,OAAO,CAAC,aAAa;YAiBP,qBAAqB;CAgBpC"}

package/dist/pg-object-storage.d.ts

@@ -1,4 +1,4 @@
-import type { CountObjectsInput, CountObjectsResult, ExistsObjectsInput, ExistsObjectsResult, FacetObjectsInput, FacetObjectsResult, LinkDirection, ObjectLinkRow, ObjectQueryCapabilities, ObjectRow, ObjectStorage, QueryObjectsInput, QueryObjectsResult } from "@sixb/core/storage";
+import type { CountObjectsInput, CountObjectsResult, ExistsObjectsInput, ExistsObjectsResult, FacetObjectsInput, FacetObjectsResult, LinkBatchKey, LinkDirection, ObjectBatchKey, ObjectLinkRow, ObjectQueryCapabilities, ObjectRow, ObjectStorage, QueryObjectLinksInput, QueryObjectLinksResult, QueryObjectsInput, QueryObjectsResult } from "@sixb/core/storage";
 import type { PgStoreClient } from "./transactions";
 /**
  * PostgreSQL-based ObjectStorage implementation.
@@ -43,7 +43,7 @@ export declare class PgObjectStorage implements ObjectStorage {
             objectTypeId: string;
             primaryId: string;
         }[];
-    }): Promise<Map<string, ObjectRow>>;
+    }): Promise<Map<ObjectBatchKey, ObjectRow>>;
     listLinksBatch(params: {
         projectId: string;
         items: readonly {
@@ -51,7 +51,8 @@ export declare class PgObjectStorage implements ObjectStorage {
             objectId: string;
             linkId: string;
         }[];
-    }): Promise<Map<string, ObjectLinkRow[]>>;
+    }): Promise<Map<LinkBatchKey, ObjectLinkRow[]>>;
+    queryLinks(params: QueryObjectLinksInput): Promise<QueryObjectLinksResult>;
     listIncidentLinksBatch(params: {
         projectId: string;
         items: readonly {

package/dist/pg-object-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pg-object-storage.d.ts","sourceRoot":"","sources":["../src/pg-object-storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pg-object-storage.d.ts","sourceRoot":"","sources":["../src/pg-object-storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixb/pg",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "PostgreSQL storage provider for Sixb",
   "keywords": [
     "sixb",
@@ -40,10 +40,10 @@
     "postgres": "^3.4.5"
   },
   "peerDependencies": {
-    "@sixb/core": "0.1.3"
+    "@sixb/core": "0.1.4"
   },
   "devDependencies": {
-    "@sixb/core": "0.1.3",
+    "@sixb/core": "0.1.4",
     "@types/bun": "latest",
     "typescript": "^5.7.0"
   },

package/src/agents/checkpoints.ts

@@ -24,6 +24,8 @@ import {
   rowToThreadRecord,
 } from "./rows"
 
+const PG_CHECKPOINT_RUN_ID_BATCH_SIZE = 10_000
+
 export class PgAgentContextCheckpointStore implements AgentContextCheckpointStore {
   constructor(private readonly sql: PgStoreClient) {}
 
@@ -172,4 +174,31 @@ export class PgAgentContextCheckpointStore implements AgentContextCheckpointStor
     `
     return row ? rowToContextCheckpointRecord(row) : null
   }
+
+  async getByRunIds(input: {
+    readonly projectId: string
+    readonly runIds: readonly string[]
+  }): Promise<readonly AgentContextCheckpointRecord[]> {
+    const runIds = [...new Set(input.runIds)]
+    if (runIds.length === 0) return []
+
+    const rows: AgentContextCheckpointRow[] = []
+    for (let offset = 0; offset < runIds.length; offset += PG_CHECKPOINT_RUN_ID_BATCH_SIZE) {
+      const batch = runIds.slice(offset, offset + PG_CHECKPOINT_RUN_ID_BATCH_SIZE)
+      const placeholders = batch.map((_, index) => `$${index + 2}`).join(", ")
+      rows.push(
+        ...(await this.sql.unsafe<AgentContextCheckpointRow[]>(
+          `SELECT * FROM agent_context_checkpoints WHERE project_id = $1 AND created_by_run_id IN (${placeholders})`,
+          [input.projectId, ...batch]
+        ))
+      )
+    }
+    const byRunId = new Map(
+      rows.map((row) => [row.created_by_run_id, rowToContextCheckpointRecord(row)] as const)
+    )
+    return runIds.flatMap((runId) => {
+      const checkpoint = byRunId.get(runId)
+      return checkpoint ? [checkpoint] : []
+    })
+  }
 }

package/src/pg-ai-usage-storage.ts

@@ -7,6 +7,7 @@ import {
   AiUsageStorageError,
   aggregateAiModelCallUsage,
   assertAiUsageExecutionId,
+  type GetLatestAiModelCallForExecutionInput,
   normalizeAiModelCallRecord,
   type RecordAiModelCallInput,
   type RecordAiModelCallResult,
@@ -110,6 +111,20 @@ export class PgAiUsageStorage implements AiUsageStorage {
     return summary!
   }
 
+  async getLatestForExecution(
+    input: GetLatestAiModelCallForExecutionInput
+  ): Promise<AiModelCallUsageRecord | null> {
+    assertNonBlankProjectId(input.projectId)
+    assertAiUsageExecutionId(input.executionId)
+    const [row] = await this.sql<AiUsageRow[]>`
+      SELECT * FROM ai_model_call_usage
+      WHERE project_id = ${input.projectId} AND execution_id = ${input.executionId}
+      ORDER BY occurred_at DESC, id DESC
+      LIMIT 1
+    `
+    return row ? this.rowToRecord(this.sql, row) : null
+  }
+
   async summarizeExecutions(
     input: SummarizeAiUsageExecutionsInput
   ): Promise<readonly AiUsageExecutionSummary[]> {

package/src/pg-object-query-compiler.ts

@@ -177,6 +177,8 @@ function compileObjectQueryInternal(
   switch (query.kind) {
     case "start":
       return compileStart(projectId, query)
+    case "refs":
+      return compileRefs(projectId, query)
     case "filter":
       return compileFilter(projectId, query.input, query.predicate)
     case "sort":
@@ -243,6 +245,54 @@ function compileStart(
   }
 }
 
+function compileRefs(
+  projectId: string,
+  query: Extract<ObjectQuery, { kind: "refs" }>
+): CompiledPgObjectQuery {
+  if (query.refs.length === 0) {
+    throw new Error("[SixbPg] PostgreSQL object storage requires at least one ref")
+  }
+
+  const order = compileOrder(identityOrderFields())
+  const selectedOrder = compileOrder(identityOrderFields(), "selected")
+  const refsJson = JSON.stringify(query.refs)
+  const requested = `
+    SELECT DISTINCT
+      ref.value ->> 'objectTypeId' AS object_type_id,
+      ref.value ->> 'primaryId' AS primary_id
+    FROM jsonb_array_elements(?::text::jsonb) AS ref(value)
+  `
+  const sql = `
+    WITH requested AS (${requested})
+    SELECT selected.*, selected.properties AS _cursor_properties
+    FROM requested
+    JOIN objects AS selected
+      ON selected.project_id = ?
+     AND selected.object_type_id = requested.object_type_id
+     AND selected.primary_id = requested.primary_id
+    ORDER BY ${selectedOrder.sql}
+  `
+
+  return {
+    sql,
+    args: [refsJson, projectId, ...selectedOrder.args],
+    totalSql: `
+      WITH requested AS (${requested})
+      SELECT COUNT(*)::bigint AS total
+      FROM requested
+      JOIN objects AS selected
+        ON selected.project_id = ?
+       AND selected.object_type_id = requested.object_type_id
+       AND selected.primary_id = requested.primary_id
+    `,
+    totalArgs: [refsJson, projectId],
+    order,
+    hasMore: () => false,
+    trimRows: identityRows,
+    nextPageToken: () => undefined,
+  }
+}
+
 function compileFilter(
   projectId: string,
   inputQuery: ObjectQuery,
@@ -753,6 +803,8 @@ function compileAggregateSource(projectId: string, query: ObjectQuery): Compiled
   switch (query.kind) {
     case "start":
       return compileAggregateStart(projectId, query)
+    case "refs":
+      return compileAggregateRefs(projectId, query)
     case "filter":
       return compileAggregateWhere(projectId, query.input, compilePredicate(query.predicate))
     case "text": {
@@ -781,7 +833,9 @@ function compileAggregateSource(projectId: string, query: ObjectQuery): Compiled
     case "page":
       return compileRowQueryAggregateSource(projectId, query)
     case "vector":
-      throw new Error(`[SixbPg] PostgreSQL object storage does not support query node 'vector'`)
+      throw new Error(
+        `[SixbPg] PostgreSQL object storage does not support query node '${query.kind}'`
+      )
   }
 }
 
@@ -803,6 +857,32 @@ function compileAggregateStart(
   }
 }
 
+function compileAggregateRefs(
+  projectId: string,
+  query: Extract<ObjectQuery, { kind: "refs" }>
+): CompiledAggregateSource {
+  if (query.refs.length === 0) {
+    throw new Error("[SixbPg] PostgreSQL object storage requires at least one ref")
+  }
+
+  return {
+    sql: `
+      SELECT selected.project_id, selected.object_type_id, selected.primary_id, selected.properties
+      FROM (
+        SELECT DISTINCT
+          ref.value ->> 'objectTypeId' AS object_type_id,
+          ref.value ->> 'primaryId' AS primary_id
+        FROM jsonb_array_elements(?::text::jsonb) AS ref(value)
+      ) AS requested
+      JOIN objects AS selected
+        ON selected.project_id = ?
+       AND selected.object_type_id = requested.object_type_id
+       AND selected.primary_id = requested.primary_id
+    `,
+    args: [JSON.stringify(query.refs), projectId],
+  }
+}
+
 function compileAggregateWhere(
   projectId: string,
   inputQuery: ObjectQuery,

package/src/pg-object-storage.ts

@@ -8,15 +8,20 @@ import type {
   ExpandedObjectRow,
   FacetObjectsInput,
   FacetObjectsResult,
+  LinkBatchKey,
   LinkDirection,
+  ObjectBatchKey,
   ObjectLinkRow,
   ObjectQueryCapabilities,
   ObjectRow,
   ObjectRowLinks,
   ObjectStorage,
+  QueryObjectLinksInput,
+  QueryObjectLinksResult,
   QueryObjectsInput,
   QueryObjectsResult,
 } from "@sixb/core/storage"
+import { linkBatchKey, objectBatchKey } from "@sixb/core/storage"
 import type { SQLClient, SqlParameter } from "./pg-client"
 import {
   type CompiledPgObjectQuery,
@@ -34,6 +39,7 @@ const PG_OBJECT_QUERY_CAPABILITIES: ObjectQueryCapabilities = {
   facetObjects: true,
   nodes: {
     start: true,
+    refs: true,
     filter: true,
     text: true,
     sort: true,
@@ -85,7 +91,7 @@ const PG_OBJECT_QUERY_CAPABILITIES: ObjectQueryCapabilities = {
     stablePageTokens: true,
   },
   notes: [
-    "PostgreSQL object query pushdown supports start/filter/text/sort/limit/page/traverse/set/project/expand over JSONB properties and object links.",
+    "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.",
@@ -263,8 +269,8 @@ export class PgObjectStorage implements ObjectStorage {
   async getByPrimaryIdBatch(params: {
     projectId: string
     items: readonly { objectTypeId: string; primaryId: string }[]
-  }): Promise<Map<string, ObjectRow>> {
-    const result = new Map<string, ObjectRow>()
+  }): Promise<Map<ObjectBatchKey, ObjectRow>> {
+    const result = new Map<ObjectBatchKey, ObjectRow>()
     if (params.items.length === 0) return result
     const rows = await valuesJoin<ObjectDatabaseRow>(
       this.sql,
@@ -276,7 +282,7 @@ export class PgObjectStorage implements ObjectStorage {
     )
 
     for (const row of rows) {
-      result.set(`${row.object_type_id}:${row.primary_id}`, rowToObject(row))
+      result.set(objectBatchKey(row.object_type_id, row.primary_id), rowToObject(row))
     }
     return result
   }
@@ -284,8 +290,8 @@ export class PgObjectStorage implements ObjectStorage {
   async listLinksBatch(params: {
     projectId: string
     items: readonly { objectTypeId: string; objectId: string; linkId: string }[]
-  }): Promise<Map<string, ObjectLinkRow[]>> {
-    const result = new Map<string, ObjectLinkRow[]>()
+  }): Promise<Map<LinkBatchKey, ObjectLinkRow[]>> {
+    const result = new Map<LinkBatchKey, ObjectLinkRow[]>()
     if (params.items.length === 0) return result
     const rows = await valuesJoin<LinkDatabaseRow>(
       this.sql,
@@ -297,7 +303,7 @@ export class PgObjectStorage implements ObjectStorage {
     )
 
     for (const row of rows) {
-      const key = `${row.source_type_id}:${row.source_id}:${row.link_id}`
+      const key = linkBatchKey(row.source_type_id, row.source_id, row.link_id)
       const existing = result.get(key) ?? []
       existing.push(rowToLink(row))
       result.set(key, existing)
@@ -305,6 +311,83 @@ export class PgObjectStorage implements ObjectStorage {
     return result
   }
 
+  async queryLinks(params: QueryObjectLinksInput): Promise<QueryObjectLinksResult> {
+    assertLinkQueryLimit(params.limit)
+    if (params.objectRefs.length === 0 || params.endpointObjectTypeIds?.length === 0) {
+      return { links: [], hasMore: false }
+    }
+
+    const args: SqlParameter[] = [JSON.stringify(params.objectRefs), params.projectId]
+    const addArg = (value: SqlParameter): string => {
+      args.push(value)
+      return `$${args.length}`
+    }
+    const sourceJoin = `
+      SELECT link.*
+      FROM links AS link
+      JOIN requested
+        ON requested.object_type_id = link.source_type_id
+       AND requested.object_id = link.source_id
+      WHERE link.project_id = $2
+    `
+    const targetJoin = `
+      SELECT link.*
+      FROM links AS link
+      JOIN requested
+        ON requested.object_type_id = link.target_type_id
+       AND requested.object_id = link.target_id
+      WHERE link.project_id = $2
+    `
+    const incidentSql =
+      params.direction === "outgoing"
+        ? sourceJoin
+        : params.direction === "incoming"
+          ? targetJoin
+          : `${sourceJoin} UNION ${targetJoin}`
+
+    const predicates: string[] = []
+    if (params.linkId !== undefined) {
+      predicates.push(`link_id = ${addArg(params.linkId)}::text`)
+    }
+    if (params.endpointObjectTypeIds !== undefined) {
+      const allowedTypes = addArg(JSON.stringify([...new Set(params.endpointObjectTypeIds)]))
+      predicates.push(
+        `source_type_id IN (SELECT jsonb_array_elements_text(${allowedTypes}::text::jsonb))`,
+        `target_type_id IN (SELECT jsonb_array_elements_text(${allowedTypes}::text::jsonb))`
+      )
+    }
+    if (params.after) {
+      const cursor = params.after.map((value) => `${addArg(value)}::text`)
+      predicates.push(
+        `(source_type_id, source_id, link_id, target_type_id, target_id) > (${cursor.join(", ")})`
+      )
+    }
+    const limit = addArg(params.limit + 1)
+    const whereSql = predicates.length > 0 ? `WHERE ${predicates.join(" AND ")}` : ""
+    const rows = await this.sql.unsafe<LinkDatabaseRow[]>(
+      `
+        WITH requested AS (
+          SELECT DISTINCT
+            requested."objectTypeId" AS object_type_id,
+            requested."primaryId" AS object_id
+          FROM jsonb_to_recordset($1::text::jsonb)
+            AS requested("objectTypeId" text, "primaryId" text)
+        ), incident AS (${incidentSql})
+        SELECT *
+        FROM incident
+        ${whereSql}
+        ORDER BY source_type_id, source_id, link_id, target_type_id, target_id
+        LIMIT ${limit}
+      `,
+      args
+    )
+
+    return {
+      links: rows.slice(0, params.limit).map((row) => rowToLink(row)),
+      hasMore: rows.length > params.limit,
+    }
+  }
+
   async listIncidentLinksBatch(params: {
     projectId: string
     items: readonly { objectTypeId: string; objectId: string }[]
@@ -314,8 +397,8 @@ export class PgObjectStorage implements ObjectStorage {
 
     // 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 how many objects are deleted — issued sequentially because
-    // these reads run on the serializable commit transaction's single connection. A link incident to
+    // 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,
@@ -337,10 +420,7 @@ export class PgObjectStorage implements ObjectStorage {
     const deduped = new Map<string, ObjectLinkRow>()
     for (const row of [...sourceRows, ...targetRows]) {
       const link = rowToLink(row)
-      deduped.set(
-        `${link.sourceTypeId}:${link.sourceId}:${link.linkId}:${link.targetTypeId}:${link.targetId}`,
-        link
-      )
+      deduped.set(linkIdentity(link), link)
     }
     return [...deduped.values()]
   }
@@ -601,6 +681,22 @@ function rowToLink(row: LinkDatabaseRow): ObjectLinkRow {
   }
 }
 
+function linkIdentity(link: ObjectLinkRow): string {
+  return JSON.stringify([
+    link.sourceTypeId,
+    link.sourceId,
+    link.linkId,
+    link.targetTypeId,
+    link.targetId,
+  ])
+}
+
+function assertLinkQueryLimit(limit: number): void {
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new Error("Object link query limit must be a positive safe integer.")
+  }
+}
+
 interface ObjectDatabaseRow {
   project_id: string
   object_type_id: string