@sixb/core 0.1.3 → 0.1.4

package/src/objects/query/explain.ts

@@ -18,6 +18,7 @@ export interface ObjectQueryExplainOptions {
   normalize?: boolean
   maxLimit?: number
   maxPageSize?: number
+  maxRefs?: number
 }
 
 export interface ObjectQueryExplanation {
@@ -47,6 +48,7 @@ export function explainObjectQuery(
         ontology: options.ontology,
         maxLimit: options.maxLimit,
         maxPageSize: options.maxPageSize,
+        maxRefs: options.maxRefs,
         normalize: false,
       })
     : []
@@ -57,6 +59,7 @@ export function explainObjectQuery(
           ontology: options.ontology,
           maxLimit: options.maxLimit,
           maxPageSize: options.maxPageSize,
+          maxRefs: options.maxRefs,
           normalize: false,
         }).result
       : undefined
@@ -84,6 +87,14 @@ function buildExplainNode(query: ObjectQuery, path: string): ObjectQueryExplainN
         },
         children: [],
       }
+    case "refs":
+      return {
+        path,
+        kind: query.kind,
+        summary: `refs ${query.refs.length}`,
+        details: { refs: query.refs },
+        children: [],
+      }
     case "filter":
       return {
         path,

package/src/objects/query/index.ts

@@ -44,6 +44,7 @@ export type {
   ObjectQueryPredicateIn,
   ObjectQueryPredicateNot,
   ObjectQueryProject,
+  ObjectQueryRefs,
   ObjectQueryResultShape,
   ObjectQuerySet,
   ObjectQuerySetOperation,
@@ -56,6 +57,11 @@ export type {
   ObjectQueryVector,
   QueryScalarKind,
 } from "./ir"
+export type {
+  ExecuteObjectQueryLinksInput,
+  ExecuteObjectQueryLinksResult,
+} from "./links"
+export { executeObjectQueryLinks } from "./links"
 export { normalizeObjectQuery, normalizeObjectQueryPredicate } from "./normalize"
 export type {
   ObjectQueryPlan,

package/src/objects/query/ir.ts

@@ -5,6 +5,8 @@
  * storage backend. Providers can push down the subset they support, while the
  * core planner decides whether a bounded fallback is acceptable.
  */
+import type { ObjectRef } from "../../ontology/refs"
+
 export type ObjectQueryDirection = "outgoing" | "incoming"
 export type ObjectQuerySetOperation = "union" | "intersect" | "subtract"
 export type ObjectQuerySortDirection = "asc" | "desc"
@@ -21,6 +23,7 @@ export type QueryScalarKind =
 
 export type ObjectQuery =
   | ObjectQueryStart
+  | ObjectQueryRefs
   | ObjectQueryFilter
   | ObjectQueryText
   | ObjectQueryVector
@@ -38,6 +41,19 @@ export interface ObjectQueryStart {
   includeSubtypes?: boolean
 }
 
+/**
+ * Starts a query from an explicit, heterogeneous set of object identities.
+ *
+ * Unlike `start`, this source is intrinsically bounded. Providers can compile
+ * it natively for composition with the rest of the IR; core resolves it through
+ * `getByPrimaryIdBatch` when pushdown is unavailable. Normalization removes
+ * duplicate identities and orders the set canonically by type and primary id.
+ */
+export interface ObjectQueryRefs {
+  kind: "refs"
+  refs: readonly ObjectRef[]
+}
+
 export interface ObjectQueryFilter {
   kind: "filter"
   input: ObjectQuery

package/src/objects/query/links.ts

@@ -0,0 +1,308 @@
+import { createHash } from "node:crypto"
+import { isAllowed } from "../../authorization"
+import { stableJsonStringify } from "../../json"
+import {
+  type LinkDirection,
+  type ObjectBatchKey,
+  type ObjectLinkCursor,
+  type ObjectLinkRow,
+  type ObjectRow,
+  type ObjectStorage,
+  objectBatchKey,
+  objectLinkCursor,
+} from "../../storage"
+import { ObjectQueryExecutionError } from "./errors"
+import { executeObjectQuery, type QueryExecutorOptions } from "./executor"
+import type { ObjectQuery } from "./ir"
+import { normalizeObjectQuery } from "./normalize"
+import { validateObjectQuery } from "./validate"
+
+export interface ExecuteObjectQueryLinksInput {
+  projectId: string
+  query: ObjectQuery
+  direction?: LinkDirection
+  linkId?: string
+  includeObjects?: boolean
+  pageSize?: number
+  pageToken?: string
+}
+
+export interface ExecuteObjectQueryLinksResult {
+  objects: readonly ObjectRow[]
+  links: readonly ObjectLinkRow[]
+  hasMore: boolean
+  nextPageToken?: string
+}
+
+const MAX_LINK_QUERY_OBJECTS = 1_000
+const MAX_LINK_PAGE_SIZE = 1_000
+const DEFAULT_LINK_PAGE_SIZE = 100
+const LINK_PAGE_TOKEN_PREFIX = "link:v1:"
+
+/**
+ * Select a bounded object set with the query IR, then return physical links
+ * incident to that set. This is a separate terminal because edge rows and edge
+ * pagination are a different response contract from object-set queries.
+ */
+export async function executeObjectQueryLinks(
+  input: ExecuteObjectQueryLinksInput,
+  options: QueryExecutorOptions
+): Promise<ExecuteObjectQueryLinksResult> {
+  const direction = input.direction ?? "both"
+  if (direction !== "outgoing" && direction !== "incoming" && direction !== "both") {
+    throw new ObjectQueryExecutionError(
+      "invalid_link_direction",
+      "direction must be 'outgoing', 'incoming', or 'both'",
+      "$.direction"
+    )
+  }
+  if (input.linkId !== undefined && input.linkId.length === 0) {
+    throw new ObjectQueryExecutionError("invalid_link_id", "linkId must not be empty", "$.linkId")
+  }
+
+  const pageSize = input.pageSize ?? DEFAULT_LINK_PAGE_SIZE
+  if (!Number.isInteger(pageSize) || pageSize <= 0 || pageSize > MAX_LINK_PAGE_SIZE) {
+    throw new ObjectQueryExecutionError(
+      "invalid_link_page_size",
+      `pageSize must be an integer between 1 and ${MAX_LINK_PAGE_SIZE}`,
+      "$.pageSize"
+    )
+  }
+  const validated = validateObjectQuery(normalizeObjectQuery(input.query), {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
+    normalize: false,
+  })
+  assertLinkSelectorShape(validated.query)
+  const selectorQuery = validated.query
+  const pageScope = linkPageScope(input.projectId, selectorQuery, direction, input.linkId)
+  const cursor = decodeLinkPageToken(input.pageToken, pageScope)
+
+  // A root page already has an explicit result bound and must execute directly: nesting it under a
+  // probe limit would expose the provider's internal pageSize+1 row. All other selector shapes are
+  // capped here before the provider receives the selected identities.
+  const boundedSelector =
+    selectorQuery.kind === "page"
+      ? selectorQuery
+      : { kind: "limit" as const, limit: MAX_LINK_QUERY_OBJECTS + 1, input: selectorQuery }
+  const selection = await executeObjectQuery(
+    {
+      projectId: input.projectId,
+      query: boundedSelector,
+      includeTotal: false,
+    },
+    {
+      ...options,
+      maxLimit: Math.max(options.maxLimit ?? 1_000, MAX_LINK_QUERY_OBJECTS + 1),
+    }
+  )
+  if (selection.objects.length > MAX_LINK_QUERY_OBJECTS) {
+    throw new ObjectQueryExecutionError(
+      "link_query_object_limit_exceeded",
+      `Link query selected more than ${MAX_LINK_QUERY_OBJECTS} objects; add a limit or page node`,
+      "$.query"
+    )
+  }
+
+  const selected = selection.objects
+  if (selected.length === 0) {
+    return { objects: [], links: [], hasMore: false }
+  }
+
+  const endpointObjectTypeIds = visibleEndpointTypeIds(options)
+  const page = await options.storage.queryLinks({
+    projectId: input.projectId,
+    objectRefs: selected.map((row) => ({
+      objectTypeId: row.objectTypeId,
+      primaryId: row.primaryId,
+    })),
+    direction,
+    ...(input.linkId === undefined ? {} : { linkId: input.linkId }),
+    ...(endpointObjectTypeIds === undefined ? {} : { endpointObjectTypeIds }),
+    ...(cursor === undefined ? {} : { after: cursor }),
+    limit: pageSize,
+  })
+  const lastLink = page.links.at(-1)
+  let nextPageToken: string | undefined
+  if (page.hasMore) {
+    if (!lastLink) {
+      throw new Error("[Sixb] Object storage returned hasMore for an empty link page.")
+    }
+    nextPageToken = encodeLinkPageToken(objectLinkCursor(lastLink), pageScope)
+  }
+  const objects = input.includeObjects
+    ? await hydrateLinkQueryObjects(input.projectId, selected, page.links, options.storage)
+    : []
+
+  return {
+    objects,
+    links: page.links,
+    hasMore: page.hasMore,
+    ...(nextPageToken ? { nextPageToken } : {}),
+  }
+}
+
+interface EncodedLinkPageToken {
+  version: 1
+  scope: string
+  cursor: ObjectLinkCursor
+}
+
+function assertLinkSelectorShape(query: ObjectQuery, path = "$.query", root = true): void {
+  switch (query.kind) {
+    case "project":
+    case "expand":
+      throw new ObjectQueryExecutionError(
+        "link_selector_output_shape_not_supported",
+        `Link selectors do not support '${query.kind}' nodes; remove output shaping from the selector`,
+        path
+      )
+    case "page":
+      if (!root) {
+        throw new ObjectQueryExecutionError(
+          "link_selector_page_must_be_root",
+          "A page node in a link selector must be the outermost node",
+          path
+        )
+      }
+      assertLinkSelectorShape(query.input, `${path}.input`, false)
+      return
+    case "start":
+    case "refs":
+      return
+    case "set": {
+      for (const [index, input] of query.inputs.entries()) {
+        assertLinkSelectorShape(input, `${path}.inputs[${index}]`, false)
+      }
+      return
+    }
+    case "filter":
+    case "text":
+    case "vector":
+    case "traverse":
+    case "sort":
+    case "limit":
+      assertLinkSelectorShape(query.input, `${path}.input`, false)
+      return
+  }
+}
+
+function visibleEndpointTypeIds(options: QueryExecutorOptions): readonly string[] | undefined {
+  if (!options.authorization) return undefined
+  return options.ontology
+    .listObjectTypes()
+    .filter((objectType) =>
+      isAllowed(options.authorization, { kind: "object.view", objectTypeId: objectType.id })
+    )
+    .map((objectType) => objectType.id)
+}
+
+function objectIdentity(objectTypeId: string, primaryId: string): ObjectBatchKey {
+  return objectBatchKey(objectTypeId, primaryId)
+}
+
+function linkPageScope(
+  projectId: string,
+  query: ObjectQuery,
+  direction: LinkDirection,
+  linkId: string | undefined
+): string {
+  return createHash("sha256")
+    .update(
+      stableJsonStringify({
+        projectId,
+        query,
+        direction,
+        linkId: linkId ?? null,
+      })
+    )
+    .digest("base64url")
+}
+
+function encodeLinkPageToken(cursor: ObjectLinkCursor, scope: string): string {
+  const payload: EncodedLinkPageToken = { version: 1, scope, cursor }
+  return `${LINK_PAGE_TOKEN_PREFIX}${Buffer.from(JSON.stringify(payload)).toString("base64url")}`
+}
+
+function decodeLinkPageToken(
+  token: string | undefined,
+  expectedScope: string
+): ObjectLinkCursor | undefined {
+  if (token === undefined) return undefined
+  try {
+    if (!token.startsWith(LINK_PAGE_TOKEN_PREFIX)) throw new Error("invalid prefix")
+    const value = JSON.parse(
+      Buffer.from(token.slice(LINK_PAGE_TOKEN_PREFIX.length), "base64url").toString("utf8")
+    ) as unknown
+    if (
+      !isPlainObject(value) ||
+      value.version !== 1 ||
+      typeof value.scope !== "string" ||
+      !isObjectLinkCursor(value.cursor)
+    ) {
+      throw new Error("invalid cursor")
+    }
+    if (value.scope !== expectedScope) {
+      throw new Error("cursor scope mismatch")
+    }
+    return value.cursor
+  } catch {
+    throw new ObjectQueryExecutionError(
+      "invalid_link_page_token",
+      "pageToken is not a valid object-links cursor",
+      "$.pageToken"
+    )
+  }
+}
+
+function isObjectLinkCursor(value: unknown): value is ObjectLinkCursor {
+  return (
+    Array.isArray(value) && value.length === 5 && value.every((part) => typeof part === "string")
+  )
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+async function hydrateLinkQueryObjects(
+  projectId: string,
+  selected: readonly ObjectRow[],
+  links: readonly ObjectLinkRow[],
+  storage: ObjectStorage
+): Promise<ObjectRow[]> {
+  const byIdentity = new Map(
+    selected.map((row) => [objectIdentity(row.objectTypeId, row.primaryId), row])
+  )
+  const orderedIdentities = selected.map((row) => objectIdentity(row.objectTypeId, row.primaryId))
+  const seenIdentities = new Set(orderedIdentities)
+  const missingRefs: { objectTypeId: string; primaryId: string }[] = []
+
+  for (const link of links) {
+    for (const ref of [
+      { objectTypeId: link.sourceTypeId, primaryId: link.sourceId },
+      { objectTypeId: link.targetTypeId, primaryId: link.targetId },
+    ]) {
+      const identity = objectIdentity(ref.objectTypeId, ref.primaryId)
+      if (seenIdentities.has(identity)) continue
+      seenIdentities.add(identity)
+      orderedIdentities.push(identity)
+      missingRefs.push(ref)
+    }
+  }
+
+  if (missingRefs.length > 0) {
+    const hydrated = await storage.getByPrimaryIdBatch({ projectId, items: missingRefs })
+    for (const ref of missingRefs) {
+      const row = hydrated.get(objectBatchKey(ref.objectTypeId, ref.primaryId))
+      if (row) byIdentity.set(objectIdentity(ref.objectTypeId, ref.primaryId), row)
+    }
+  }
+
+  return orderedIdentities.flatMap((identity) => {
+    const row = byIdentity.get(identity)
+    return row ? [row] : []
+  })
+}

package/src/objects/query/normalize.ts

@@ -22,6 +22,11 @@ function normalizeNode(query: ObjectQuery): ObjectQuery {
   switch (query.kind) {
     case "start":
       return { ...query }
+    case "refs":
+      return {
+        kind: "refs",
+        refs: uniqueRefs(query.refs),
+      }
     case "filter":
       return normalizeFilter(query.input, query.predicate)
     case "text":
@@ -63,7 +68,14 @@ function normalizeNode(query: ObjectQuery): ObjectQuery {
  * lands above another `expand` is merged into one.
  */
 function hoistExpand(query: ObjectQuery): ObjectQuery {
-  if (query.kind === "start" || query.kind === "set" || query.kind === "expand") return query
+  if (
+    query.kind === "start" ||
+    query.kind === "refs" ||
+    query.kind === "set" ||
+    query.kind === "expand"
+  ) {
+    return query
+  }
   if (query.input.kind !== "expand") return query
 
   const inner = query.input
@@ -236,6 +248,33 @@ function uniqueStrings(values: readonly string[]): string[] {
   return [...new Set(values)]
 }
 
+function uniqueRefs(
+  refs: readonly { objectTypeId: string; primaryId: string }[]
+): { objectTypeId: string; primaryId: string }[] {
+  const seen = new Set<string>()
+  const unique = refs.flatMap((ref) => {
+    const key = JSON.stringify([ref.objectTypeId, ref.primaryId])
+    if (seen.has(key)) return []
+    seen.add(key)
+    return [{ ...ref }]
+  })
+
+  // `refs` is an object-set source, not a positional batch response. Canonical
+  // identity order makes equivalent sets normalize identically and matches the
+  // default ordering used by provider query sources.
+  return unique.sort(
+    (left, right) =>
+      compareStrings(left.objectTypeId, right.objectTypeId) ||
+      compareStrings(left.primaryId, right.primaryId)
+  )
+}
+
+function compareStrings(left: string, right: string): number {
+  if (left < right) return -1
+  if (left > right) return 1
+  return 0
+}
+
 function uniqueStringRecord(
   record: Readonly<Record<string, readonly string[]>>
 ): Record<string, string[]> {

package/src/objects/query/planner.ts

@@ -40,6 +40,7 @@ const DEFAULT_MAX_FALLBACK_ROWS = 1_000
 // accidental full scans.
 const fallbackNodeKinds = new Set<ObjectQuery["kind"]>([
   "start",
+  "refs",
   "filter",
   "sort",
   "limit",
@@ -195,6 +196,8 @@ function collectNodeProviderIssues(
         )
       }
       return
+    case "refs":
+      return
     case "filter":
       collectPredicateProviderIssues(query.predicate, `${path}.predicate`, capabilities, issues)
       collectNodeProviderIssues(query.input, `${path}.input`, capabilities, issues)
@@ -474,6 +477,7 @@ function collectFallbackNodeIssues(
 
   switch (query.kind) {
     case "start":
+    case "refs":
       return
     case "filter":
     case "limit":
@@ -512,6 +516,7 @@ function hasExplicitResultBound(query: ObjectQuery): boolean {
   switch (query.kind) {
     case "limit":
     case "page":
+    case "refs":
       return true
     case "start":
       return false

package/src/objects/query/validate.ts

@@ -1,4 +1,11 @@
-import type { ObjectType, OntologyRegistry, Property, Schema, ValueType } from "../../ontology"
+import type {
+  ObjectRef,
+  ObjectType,
+  OntologyRegistry,
+  Property,
+  Schema,
+  ValueType,
+} from "../../ontology"
 import { normalizeDecimalValue } from "../../ontology"
 import { formatUnknownObjectTypeMessage } from "../../ontology/errors"
 import { validatePropertyValue, validateSchemaValue } from "../../ontology/validation"
@@ -30,11 +37,12 @@ export interface ObjectQueryValidationOptions {
   ontology: OntologyRegistry
   maxLimit?: number
   maxPageSize?: number
+  maxRefs?: number
   normalize?: boolean
 }
 
 type QueryValidationContext = Required<
-  Pick<ObjectQueryValidationOptions, "maxLimit" | "maxPageSize">
+  Pick<ObjectQueryValidationOptions, "maxLimit" | "maxPageSize" | "maxRefs">
 > & {
   ontology: OntologyRegistry
   valueTypesById: ReadonlyMap<string, ValueType>
@@ -53,6 +61,7 @@ interface TextFieldResolution {
 
 const DEFAULT_MAX_LIMIT = 1_000
 const DEFAULT_MAX_PAGE_SIZE = 1_000
+const DEFAULT_MAX_REFS = 1_000
 
 export function validateObjectQuery(
   query: ObjectQuery,
@@ -96,6 +105,7 @@ function createValidationContext(options: ObjectQueryValidationOptions): QueryVa
     valueTypesById: options.ontology.getValueTypesById(),
     maxLimit: options.maxLimit ?? DEFAULT_MAX_LIMIT,
     maxPageSize: options.maxPageSize ?? DEFAULT_MAX_PAGE_SIZE,
+    maxRefs: options.maxRefs ?? DEFAULT_MAX_REFS,
     issues: [],
     touchedObjectTypeIds: new Set<string>(),
   }
@@ -125,6 +135,8 @@ function dispatchQueryNode(
   switch (query.kind) {
     case "start":
       return validateStart(query.objectTypeId, query.includeSubtypes, path, ctx)
+    case "refs":
+      return validateRefs(query.refs, path, ctx)
     case "filter": {
       const input = validateQueryNode(query.input, `${path}.input`, ctx)
       const predicate = validatePredicate(query.predicate, input.result, `${path}.predicate`, ctx)
@@ -199,6 +211,50 @@ function dispatchQueryNode(
   }
 }
 
+function validateRefs(
+  refs: readonly ObjectRef[],
+  path: string,
+  ctx: QueryValidationContext
+): QueryValidationResult {
+  if (refs.length === 0) {
+    addIssue(ctx, `${path}.refs`, "empty_refs", "refs must include at least one object reference")
+  }
+  if (refs.length > ctx.maxRefs) {
+    addIssue(
+      ctx,
+      `${path}.refs`,
+      "too_many_refs",
+      `refs must include at most ${ctx.maxRefs} object references`
+    )
+  }
+
+  const objectTypeIds = new Set<string>()
+  refs.forEach((ref, index) => {
+    const refPath = `${path}.refs[${index}]`
+    if (!ref.objectTypeId) {
+      addIssue(ctx, `${refPath}.objectTypeId`, "missing_object_type", "objectTypeId is required")
+    } else if (!ctx.ontology.getObjectTypeById(ref.objectTypeId)) {
+      addIssue(
+        ctx,
+        `${refPath}.objectTypeId`,
+        "unknown_object_type",
+        formatUnknownObjectTypeMessage(ref.objectTypeId)
+      )
+    } else {
+      objectTypeIds.add(ref.objectTypeId)
+    }
+
+    if (!ref.primaryId) {
+      addIssue(ctx, `${refPath}.primaryId`, "missing_primary_id", "primaryId is required")
+    }
+  })
+
+  return {
+    result: { objectTypeIds: [...objectTypeIds] },
+    query: { kind: "refs", refs: refs.map((ref) => ({ ...ref })) },
+  }
+}
+
 function validateStart(
   objectTypeId: string,
   includeSubtypes: boolean | undefined,