@sixb/core 0.1.6 → 0.1.8

package/src/objects/query/links.ts

@@ -6,8 +6,8 @@ import {
   type ObjectBatchKey,
   type ObjectLinkCursor,
   type ObjectLinkRow,
+  type ObjectReadStorage,
   type ObjectRow,
-  type ObjectStorage,
   objectBatchKey,
   objectLinkCursor,
 } from "../../storage"
@@ -15,7 +15,7 @@ import { ObjectQueryExecutionError } from "./errors"
 import { executeObjectQuery, type QueryExecutorOptions } from "./executor"
 import type { ObjectQuery } from "./ir"
 import { normalizeObjectQuery } from "./normalize"
-import { validateObjectQuery } from "./validate"
+import { type ValidatedObjectQuery, validateObjectQuery } from "./validate"
 
 export interface ExecuteObjectQueryLinksInput {
   projectId: string
@@ -34,21 +34,46 @@ export interface ExecuteObjectQueryLinksResult {
   nextPageToken?: string
 }
 
+export interface PreflightObjectQueryLinksResult {
+  projectId: string
+  validated: ValidatedObjectQuery
+  direction: LinkDirection
+  linkId?: string
+  includeObjects: boolean
+  pageSize: number
+  cursor?: ObjectLinkCursor
+  pageScope: 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.
+ * Canonicalize and validate a physical-link query without reading storage.
+ *
+ * This direct-file-only boundary lets higher-level readers complete ordinary request validation
+ * before applying terminal-specific authorization, while the executor consumes the exact same
+ * preflight contract.
+ *
+ * @internal Intentionally absent from query barrels.
  */
-export async function executeObjectQueryLinks(
+export function preflightObjectQueryLinks(
   input: ExecuteObjectQueryLinksInput,
-  options: QueryExecutorOptions
-): Promise<ExecuteObjectQueryLinksResult> {
-  const direction = input.direction ?? "both"
+  options: Pick<QueryExecutorOptions, "ontology" | "maxLimit" | "maxPageSize" | "maxRefs">
+): PreflightObjectQueryLinksResult {
+  // Capture caller-owned scalar fields once so validation, token scoping, and execution agree on
+  // one request even when this internal API is reached without an AuthorizedObjectReader snapshot.
+  const projectId = input.projectId
+  const query = input.query
+  const requestedDirection = input.direction
+  const linkId = input.linkId
+  const requestedIncludeObjects = input.includeObjects
+  const requestedPageSize = input.pageSize
+  const pageToken = input.pageToken
+
+  const direction = requestedDirection ?? "both"
   if (direction !== "outgoing" && direction !== "incoming" && direction !== "both") {
     throw new ObjectQueryExecutionError(
       "invalid_link_direction",
@@ -56,11 +81,21 @@ export async function executeObjectQueryLinks(
       "$.direction"
     )
   }
-  if (input.linkId !== undefined && input.linkId.length === 0) {
+  if (linkId !== undefined && typeof linkId !== "string") {
+    throw new ObjectQueryExecutionError("invalid_link_id", "linkId must be a string", "$.linkId")
+  }
+  if (linkId !== undefined && linkId.length === 0) {
     throw new ObjectQueryExecutionError("invalid_link_id", "linkId must not be empty", "$.linkId")
   }
+  if (requestedIncludeObjects !== undefined && typeof requestedIncludeObjects !== "boolean") {
+    throw new ObjectQueryExecutionError(
+      "invalid_link_include_objects",
+      "includeObjects must be a boolean",
+      "$.includeObjects"
+    )
+  }
 
-  const pageSize = input.pageSize ?? DEFAULT_LINK_PAGE_SIZE
+  const pageSize = requestedPageSize ?? DEFAULT_LINK_PAGE_SIZE
   if (!Number.isInteger(pageSize) || pageSize <= 0 || pageSize > MAX_LINK_PAGE_SIZE) {
     throw new ObjectQueryExecutionError(
       "invalid_link_page_size",
@@ -68,7 +103,8 @@ export async function executeObjectQueryLinks(
       "$.pageSize"
     )
   }
-  const validated = validateObjectQuery(normalizeObjectQuery(input.query), {
+
+  const validated = validateObjectQuery(normalizeObjectQuery(query), {
     ontology: options.ontology,
     maxLimit: options.maxLimit,
     maxPageSize: options.maxPageSize,
@@ -76,9 +112,32 @@ export async function executeObjectQueryLinks(
     normalize: false,
   })
   assertLinkSelectorShape(validated.query)
-  const selectorQuery = validated.query
-  const pageScope = linkPageScope(input.projectId, selectorQuery, direction, input.linkId)
-  const cursor = decodeLinkPageToken(input.pageToken, pageScope)
+  const pageScope = linkPageScope(projectId, validated.query, direction, linkId)
+  const cursor = decodeLinkPageToken(pageToken, pageScope)
+
+  return {
+    projectId,
+    validated,
+    direction,
+    ...(linkId === undefined ? {} : { linkId }),
+    includeObjects: requestedIncludeObjects ?? false,
+    pageSize,
+    ...(cursor === undefined ? {} : { cursor }),
+    pageScope,
+  }
+}
+
+/**
+ * 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 preflight = preflightObjectQueryLinks(input, options)
+  const selectorQuery = preflight.validated.query
 
   // 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
@@ -89,7 +148,7 @@ export async function executeObjectQueryLinks(
       : { kind: "limit" as const, limit: MAX_LINK_QUERY_OBJECTS + 1, input: selectorQuery }
   const selection = await executeObjectQuery(
     {
-      projectId: input.projectId,
+      projectId: preflight.projectId,
       query: boundedSelector,
       includeTotal: false,
     },
@@ -113,16 +172,16 @@ export async function executeObjectQueryLinks(
 
   const endpointObjectTypeIds = visibleEndpointTypeIds(options)
   const page = await options.storage.queryLinks({
-    projectId: input.projectId,
+    projectId: preflight.projectId,
     objectRefs: selected.map((row) => ({
       objectTypeId: row.objectTypeId,
       primaryId: row.primaryId,
     })),
-    direction,
-    ...(input.linkId === undefined ? {} : { linkId: input.linkId }),
+    direction: preflight.direction,
+    ...(preflight.linkId === undefined ? {} : { linkId: preflight.linkId }),
     ...(endpointObjectTypeIds === undefined ? {} : { endpointObjectTypeIds }),
-    ...(cursor === undefined ? {} : { after: cursor }),
-    limit: pageSize,
+    ...(preflight.cursor === undefined ? {} : { after: preflight.cursor }),
+    limit: preflight.pageSize,
   })
   const lastLink = page.links.at(-1)
   let nextPageToken: string | undefined
@@ -130,10 +189,10 @@ export async function executeObjectQueryLinks(
     if (!lastLink) {
       throw new Error("[Sixb] Object storage returned hasMore for an empty link page.")
     }
-    nextPageToken = encodeLinkPageToken(objectLinkCursor(lastLink), pageScope)
+    nextPageToken = encodeLinkPageToken(objectLinkCursor(lastLink), preflight.pageScope)
   }
-  const objects = input.includeObjects
-    ? await hydrateLinkQueryObjects(input.projectId, selected, page.links, options.storage)
+  const objects = preflight.includeObjects
+    ? await hydrateLinkQueryObjects(preflight.projectId, selected, page.links, options.storage)
     : []
 
   return {
@@ -271,7 +330,7 @@ async function hydrateLinkQueryObjects(
   projectId: string,
   selected: readonly ObjectRow[],
   links: readonly ObjectLinkRow[],
-  storage: ObjectStorage
+  storage: ObjectReadStorage
 ): Promise<ObjectRow[]> {
   const byIdentity = new Map(
     selected.map((row) => [objectIdentity(row.objectTypeId, row.primaryId), row])

package/src/objects/query/selected-read-admission.ts

@@ -0,0 +1,310 @@
+import { AuthorizationError } from "../../authorization/errors"
+import type {
+  CompiledObjectReadObjectSelection,
+  CompiledObjectReadStep,
+  CompiledSelectedObjectReadScope,
+} from "../../storage/objects/types"
+import type {
+  ObjectQueryAdmissionState,
+  ObjectQueryAdmissionTransition,
+  ObjectQueryEdgeUse,
+  ObjectQueryPropertyUse,
+  ObjectQuerySemanticAdmission,
+} from "./validate"
+
+const selectedStateBrand = Symbol("sixb.selected-object-query-admission-state")
+
+interface SelectedObjectQueryState extends ObjectQueryAdmissionState {
+  readonly [selectedStateBrand]: true
+  readonly selections: readonly CompiledObjectReadObjectSelection[]
+}
+
+export interface SelectedObjectQueryAdmission extends ObjectQuerySemanticAdmission {
+  /** Terminal hook for property-bearing operations outside the query IR, such as facets. */
+  assertPropertySelected(input: {
+    readonly state: ObjectQueryAdmissionState
+    readonly propertyId: string
+    readonly objectTypeId?: string
+    readonly use: ObjectQueryPropertyUse
+    readonly path: string
+  }): void
+  /** Terminal hook for the physical-link selector that sits outside `queryLinks.query`. */
+  assertIncidentEdgeSelected(input: {
+    readonly state: ObjectQueryAdmissionState
+    readonly linkId?: string
+    readonly direction: "outgoing" | "incoming" | "both"
+    readonly path: string
+  }): void
+}
+
+/**
+ * Build an immutable semantic admission over one already-compiled selected reader scope.
+ *
+ * Object identities remain provider-owned: query admission follows exact path occurrences while
+ * the selected storage relation decides which live roots and linked instances exist.
+ */
+export function createSelectedObjectQueryAdmission(
+  scope: CompiledSelectedObjectReadScope
+): SelectedObjectQueryAdmission {
+  const selectionByKey = new Map<string, CompiledObjectReadObjectSelection>()
+  const selectionsByType = new Map<string, CompiledObjectReadObjectSelection[]>()
+  const propertiesBySelection = new Map<string, ReadonlySet<string>>()
+
+  for (const selection of scope.objects) {
+    const key = selectionKey(selection.nodeId, selection.objectTypeId)
+    selectionByKey.set(key, selection)
+    propertiesBySelection.set(key, new Set(selection.propertyIds))
+    const byType = selectionsByType.get(selection.objectTypeId) ?? []
+    byType.push(selection)
+    selectionsByType.set(selection.objectTypeId, byType)
+  }
+
+  const outgoing = indexSteps(scope.steps, "outgoing", selectionByKey)
+  const incoming = indexSteps(scope.steps, "incoming", selectionByKey)
+  const emptyState = selectedState([])
+
+  const admission: SelectedObjectQueryAdmission = {
+    empty: () => emptyState,
+    source: (input) => {
+      const selections = input.result.objectTypeIds.flatMap(
+        (objectTypeId) => selectionsByType.get(objectTypeId) ?? []
+      )
+      const state = selectedState(selections)
+
+      if (input.kind === "refs") {
+        const missingType = [...new Set(input.refs?.map((ref) => ref.objectTypeId) ?? [])]
+          .sort()
+          .find((objectTypeId) => !selectionsByType.has(objectTypeId))
+        if (missingType) {
+          return denied(
+            state,
+            new AuthorizationError(
+              `view:object:${missingType}`,
+              `[Sixb] Delegated query cannot reference object type '${missingType}' at '${input.path}': the selected object scope does not contain that type.`
+            )
+          )
+        }
+      }
+
+      if (state.selections.length > 0) return { state }
+      const objectTypeId = input.objectTypeId ?? input.result.objectTypeIds[0] ?? "unknown"
+      return denied(
+        state,
+        new AuthorizationError(
+          `view:object:${objectTypeId}`,
+          `[Sixb] Delegated query cannot start from object type '${objectTypeId}' at '${input.path}': the selected object scope does not contain that type.`
+        )
+      )
+    },
+    property: (input) =>
+      propertyDenial(
+        asSelectedState(input.state),
+        input.propertyId,
+        input.objectTypeId,
+        input.use,
+        input.path,
+        propertiesBySelection
+      ),
+    edge: (input) => {
+      const state = asSelectedState(input.state)
+      const next = followEdge(
+        state,
+        input.linkId,
+        input.direction,
+        input.sourceObjectTypeId,
+        outgoing,
+        incoming,
+        input.result.objectTypeIds
+      )
+      if (next.selections.length > 0 || state.selections.length === 0) return { state: next }
+      return denied(
+        next,
+        edgeDenial(
+          state,
+          input.linkId,
+          input.direction,
+          input.sourceObjectTypeId,
+          input.use,
+          input.path
+        )
+      )
+    },
+    set: ({ op, states }) => {
+      if (op === "subtract") return asSelectedState(states[0] ?? emptyState)
+      return selectedState(states.flatMap((state) => asSelectedState(state).selections))
+    },
+    assertPropertySelected: (input) => {
+      const denial = propertyDenial(
+        asSelectedState(input.state),
+        input.propertyId,
+        input.objectTypeId,
+        input.use,
+        input.path,
+        propertiesBySelection
+      )
+      if (denial) throw denial
+    },
+    assertIncidentEdgeSelected: (input) => {
+      if (input.linkId === undefined) return
+      const state = asSelectedState(input.state)
+      const directions: readonly ("outgoing" | "incoming")[] =
+        input.direction === "both" ? ["outgoing", "incoming"] : [input.direction]
+      const next = selectedState(
+        directions.flatMap(
+          (direction) =>
+            followEdge(state, input.linkId!, direction, undefined, outgoing, incoming).selections
+        )
+      )
+      if (next.selections.length > 0 || state.selections.length === 0) return
+      throw edgeDenial(state, input.linkId, input.direction, undefined, "queryLinks", input.path)
+    },
+  }
+
+  return Object.freeze(admission)
+}
+
+function indexSteps(
+  steps: readonly CompiledObjectReadStep[],
+  direction: "outgoing" | "incoming",
+  selectionByKey: ReadonlyMap<string, CompiledObjectReadObjectSelection>
+): ReadonlyMap<string, readonly CompiledObjectReadObjectSelection[]> {
+  const index = new Map<string, CompiledObjectReadObjectSelection[]>()
+  for (const step of steps) {
+    const fromKey =
+      direction === "outgoing"
+        ? selectionKey(step.parentNodeId, step.sourceObjectTypeId)
+        : selectionKey(step.nodeId, step.targetObjectTypeId)
+    const toKey =
+      direction === "outgoing"
+        ? selectionKey(step.nodeId, step.targetObjectTypeId)
+        : selectionKey(step.parentNodeId, step.sourceObjectTypeId)
+    const target = selectionByKey.get(toKey)
+    if (!selectionByKey.has(fromKey) || !target) {
+      throw new Error("[Sixb] Compiled selected object scope contains an invalid query path step.")
+    }
+    const key = edgeKey(
+      direction === "outgoing" ? step.parentNodeId : step.nodeId,
+      direction === "outgoing" ? step.sourceObjectTypeId : step.targetObjectTypeId,
+      step.linkId
+    )
+    const targets = index.get(key) ?? []
+    targets.push(target)
+    index.set(key, targets)
+  }
+  return index
+}
+
+function followEdge(
+  state: SelectedObjectQueryState,
+  linkId: string,
+  direction: "outgoing" | "incoming",
+  sourceObjectTypeId: string | undefined,
+  outgoing: ReadonlyMap<string, readonly CompiledObjectReadObjectSelection[]>,
+  incoming: ReadonlyMap<string, readonly CompiledObjectReadObjectSelection[]>,
+  resultObjectTypeIds?: readonly string[]
+): SelectedObjectQueryState {
+  const index = direction === "outgoing" ? outgoing : incoming
+  const resultTypes = resultObjectTypeIds ? new Set(resultObjectTypeIds) : undefined
+  const selections = state.selections.flatMap((selection) => {
+    const candidates = index.get(edgeKey(selection.nodeId, selection.objectTypeId, linkId)) ?? []
+    return candidates.filter(
+      (candidate) =>
+        (resultTypes === undefined || resultTypes.has(candidate.objectTypeId)) &&
+        (direction === "outgoing" ||
+          sourceObjectTypeId === undefined ||
+          candidate.objectTypeId === sourceObjectTypeId)
+    )
+  })
+  return selectedState(selections)
+}
+
+function propertyDenial(
+  state: SelectedObjectQueryState,
+  propertyId: string,
+  objectTypeId: string | undefined,
+  use: ObjectQueryPropertyUse,
+  path: string,
+  propertiesBySelection: ReadonlyMap<string, ReadonlySet<string>>
+): AuthorizationError | undefined {
+  const candidates = objectTypeId
+    ? state.selections.filter((selection) => selection.objectTypeId === objectTypeId)
+    : state.selections
+  // A selected reader has no rows for result types absent from this provenance. Those empty
+  // branches cannot observe a property and must not make includeSubtypes queries fail closed.
+  if (candidates.length === 0) return undefined
+
+  const missing = candidates.find(
+    (selection) =>
+      !propertiesBySelection
+        .get(selectionKey(selection.nodeId, selection.objectTypeId))
+        ?.has(propertyId)
+  )
+  if (!missing) return undefined
+
+  const objectTypeIds = [...new Set(candidates.map((selection) => selection.objectTypeId))].sort()
+  return new AuthorizationError(
+    `view:object:${objectTypeIds.join(",")}:property:${propertyId}`,
+    `[Sixb] Delegated query cannot use property '${propertyId}' for ${use} at '${path}': it is not selected on every matching read-scope path (missing on ${formatSelection(missing)}).`
+  )
+}
+
+function edgeDenial(
+  state: SelectedObjectQueryState,
+  linkId: string,
+  direction: "outgoing" | "incoming" | "both",
+  sourceObjectTypeId: string | undefined,
+  use: ObjectQueryEdgeUse,
+  path: string
+): AuthorizationError {
+  const source = sourceObjectTypeId ? `:${sourceObjectTypeId}` : ""
+  return new AuthorizationError(
+    `view:link:${direction}${source}:${linkId}`,
+    `[Sixb] Delegated query cannot use ${direction} link '${linkId}' for ${use} from ${formatState(state)} at '${path}': that exact read-scope path is not selected.`
+  )
+}
+
+function formatState(state: SelectedObjectQueryState): string {
+  if (state.selections.length === 0) return "an empty read-scope provenance"
+  return `read-scope provenance ${state.selections.map(formatSelection).join(", ")}`
+}
+
+function formatSelection(selection: CompiledObjectReadObjectSelection): string {
+  return `'${selection.objectTypeId}'@node ${selection.nodeId}`
+}
+
+function selectedState(
+  selections: readonly CompiledObjectReadObjectSelection[]
+): SelectedObjectQueryState {
+  const unique = new Map<string, CompiledObjectReadObjectSelection>()
+  for (const selection of selections) {
+    unique.set(selectionKey(selection.nodeId, selection.objectTypeId), selection)
+  }
+  return Object.freeze({
+    [selectedStateBrand]: true as const,
+    selections: Object.freeze(
+      [...unique.values()].sort(
+        (left, right) =>
+          left.nodeId - right.nodeId || left.objectTypeId.localeCompare(right.objectTypeId)
+      )
+    ),
+  })
+}
+
+function asSelectedState(state: ObjectQueryAdmissionState): SelectedObjectQueryState {
+  if ((state as Partial<SelectedObjectQueryState>)[selectedStateBrand] !== true) {
+    throw new Error("[Sixb] Object query admission state belongs to another semantic admission.")
+  }
+  return state as SelectedObjectQueryState
+}
+
+function denied(state: SelectedObjectQueryState, denial: Error): ObjectQueryAdmissionTransition {
+  return { state, denial }
+}
+
+function selectionKey(nodeId: number, objectTypeId: string): string {
+  return JSON.stringify([nodeId, objectTypeId])
+}
+
+function edgeKey(nodeId: number, objectTypeId: string, linkId: string): string {
+  return JSON.stringify([nodeId, objectTypeId, linkId])
+}