@sixb/core 0.1.17 → 0.1.18

package/src/objects/query/executor.ts

@@ -39,10 +39,13 @@ import { rerankObjectCandidates } from "./reranking-executor"
 import { findQueryReranking } from "./reranking-query"
 import { compareQueryScalarValues, queryScalarValuesEqual } from "./scalar-values"
 import {
+  type AdmittedObjectQuery,
+  type ObjectQuerySemanticAdmission,
   type ObjectQueryValidationIssue,
   resolveObjectQueryResultShape,
   type ValidatedObjectQuery,
   validateObjectQuery,
+  validateObjectQueryWithAdmission,
 } from "./validate"
 
 export interface QueryExecutorOptions
@@ -73,6 +76,8 @@ export interface QueryExecutorOptions
   authorization?: AuthorizationContext
   /** Registered execution capability for queries reached through a bound Sixb SDK. */
   runtimeAuthorization?: RuntimeAuthorization
+  /** Reader-specific admission applied after grants, such as marking clearances. */
+  admission?: ObjectQuerySemanticAdmission
 }
 
 export interface ExecuteObjectQueryInput {
@@ -138,15 +143,7 @@ export async function executeObjectQuery(
   input: ExecuteObjectQueryInput,
   options: QueryExecutorOptions
 ): Promise<ExecuteObjectQueryResult> {
-  const normalized = normalizeObjectQuery(input.query)
-  const validated = validateObjectQuery(normalized, {
-    ontology: options.ontology,
-    maxLimit: options.maxLimit,
-    maxPageSize: options.maxPageSize,
-    maxRefs: options.maxRefs,
-    normalize: false,
-  })
-  assertQueryViewable(input.projectId, validated, options)
+  const validated = validateExecutableQuery(input, options)
   const capabilities = options.storage.queryCapabilities()
   const hasQueryObjects = typeof options.storage.queryObjects === "function"
   const hasCountObjects = typeof options.storage.countObjects === "function"
@@ -242,15 +239,7 @@ export async function countObjects(
   input: ExecuteObjectCountInput,
   options: QueryExecutorOptions
 ): Promise<ExecuteObjectCountResult> {
-  const normalized = normalizeObjectQuery(input.query)
-  const validated = validateObjectQuery(normalized, {
-    ontology: options.ontology,
-    maxLimit: options.maxLimit,
-    maxPageSize: options.maxPageSize,
-    maxRefs: options.maxRefs,
-    normalize: false,
-  })
-  assertQueryViewable(input.projectId, validated, options)
+  const validated = validateExecutableQuery(input, options)
   const capabilities = options.storage.queryCapabilities()
   const hasQueryObjects = typeof options.storage.queryObjects === "function"
   const hasCountObjects = typeof options.storage.countObjects === "function"
@@ -303,15 +292,7 @@ export async function existsObjects(
   input: ExecuteObjectExistsInput,
   options: QueryExecutorOptions
 ): Promise<ExecuteObjectExistsResult> {
-  const normalized = normalizeObjectQuery(input.query)
-  const validated = validateObjectQuery(normalized, {
-    ontology: options.ontology,
-    maxLimit: options.maxLimit,
-    maxPageSize: options.maxPageSize,
-    maxRefs: options.maxRefs,
-    normalize: false,
-  })
-  assertQueryViewable(input.projectId, validated, options)
+  const validated = validateExecutableQuery(input, options)
   const capabilities = options.storage.queryCapabilities()
   const hasQueryObjects = typeof options.storage.queryObjects === "function"
   const hasCountObjects = typeof options.storage.countObjects === "function"
@@ -364,16 +345,17 @@ export async function facetObjects(
   input: ExecuteObjectFacetsInput,
   options: QueryExecutorOptions
 ): Promise<ExecuteObjectFacetsResult> {
-  const normalized = normalizeObjectQuery(input.query)
-  const validated = validateObjectQuery(normalized, {
-    ontology: options.ontology,
-    maxLimit: options.maxLimit,
-    maxPageSize: options.maxPageSize,
-    maxRefs: options.maxRefs,
-    normalize: false,
-  })
-  assertQueryViewable(input.projectId, validated, options)
+  const validated = validateExecutableQuery(input, options)
   const facets = validateObjectFacetRequests(input.facets, validated.result.objectTypeIds, options)
+  facets.forEach((facet, index) => {
+    const denial = options.admission?.property({
+      state: validated.admissionState,
+      propertyId: facet.propertyId,
+      use: "facet",
+      path: `$.facets[${index}].propertyId`,
+    })
+    if (denial) throw denial
+  })
   const aggregateQuery = stripOuterRowShape(validated.query)
   const capabilities = options.storage.queryCapabilities()
   const hasQueryObjects = typeof options.storage.queryObjects === "function"
@@ -430,6 +412,31 @@ export async function facetObjects(
   }
 }
 
+/**
+ * Validate, authorize the touched types, then admit the query for the reader.
+ *
+ * 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.
+ */
+function validateExecutableQuery(
+  input: { readonly projectId: string; readonly query: ObjectQuery },
+  options: QueryExecutorOptions
+): AdmittedObjectQuery {
+  const validationOptions = {
+    ontology: options.ontology,
+    maxLimit: options.maxLimit,
+    maxPageSize: options.maxPageSize,
+    maxRefs: options.maxRefs,
+    normalize: false,
+  }
+  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)
+}
+
 // Authorization happens at planning time: a scoped query must hold a view
 // grant for every object type it touches, before any storage call runs.
 function assertQueryViewable(

package/src/objects/query/validate.ts

@@ -42,7 +42,10 @@ export interface ObjectQueryValidationIssue {
 export interface ValidatedObjectQuery {
   query: ObjectQuery
   result: ObjectQueryResultShape
-  /** Every object type the query touches, including intermediate traversal types. */
+  /**
+   * Every object type the query touches, including intermediate traversal types and the subtypes
+   * an outgoing link can reach.
+   */
   touchedObjectTypeIds: readonly string[]
 }
 
@@ -159,6 +162,67 @@ const NOOP_QUERY_ADMISSION: ObjectQuerySemanticAdmission = Object.freeze({
     input.states[0] ?? NOOP_ADMISSION_STATE,
 })
 
+/**
+ * Admit a query only when both admissions admit it, each reducing its own state.
+ *
+ * The first denial wins, in order, so composing keeps each admission's messages unchanged.
+ */
+export function composeObjectQueryAdmissions(
+  first: ObjectQuerySemanticAdmission,
+  second: ObjectQuerySemanticAdmission
+): ObjectQuerySemanticAdmission {
+  const parts = new WeakMap<
+    ObjectQueryAdmissionState,
+    readonly [ObjectQueryAdmissionState, ObjectQueryAdmissionState]
+  >()
+  const join = (
+    left: ObjectQueryAdmissionState,
+    right: ObjectQueryAdmissionState
+  ): ObjectQueryAdmissionState => {
+    const state = Object.freeze({})
+    parts.set(state, [left, right])
+    return state
+  }
+  const split = (state: ObjectQueryAdmissionState) => {
+    const pair = parts.get(state)
+    if (!pair) throw new Error("[Sixb] Composed query admission received a foreign state.")
+    return pair
+  }
+  const transition = (
+    left: ObjectQueryAdmissionTransition,
+    right: ObjectQueryAdmissionTransition
+  ): ObjectQueryAdmissionTransition => {
+    const denial = left.denial ?? right.denial
+    return { state: join(left.state, right.state), ...(denial ? { denial } : {}) }
+  }
+
+  const admission: ObjectQuerySemanticAdmission = {
+    empty: () => join(first.empty(), second.empty()),
+    source: (input) => transition(first.source(input), second.source(input)),
+    edge: (input) => {
+      const [left, right] = split(input.state)
+      return transition(
+        first.edge({ ...input, state: left }),
+        second.edge({ ...input, state: right })
+      )
+    },
+    property: (input) => {
+      const [left, right] = split(input.state)
+      return (
+        first.property({ ...input, state: left }) ?? second.property({ ...input, state: right })
+      )
+    },
+    set: (input) => {
+      const pairs = input.states.map(split)
+      return join(
+        first.set({ ...input, states: pairs.map(([left]) => left) }),
+        second.set({ ...input, states: pairs.map(([, right]) => right) })
+      )
+    },
+  }
+  return Object.freeze(admission)
+}
+
 export function validateObjectQuery(
   query: ObjectQuery,
   options: ObjectQueryValidationOptions
@@ -530,9 +594,7 @@ function validateStart(
     return { result: { objectTypeIds: [] }, query: { kind: "start", objectTypeId } }
   }
 
-  const objectTypeIds = includeSubtypes
-    ? uniqueStrings([objectTypeId, ...ctx.ontology.listSubTypes(objectTypeId)])
-    : [objectTypeId]
+  const objectTypeIds = includeSubtypes ? withSubtypes([objectTypeId], ctx) : [objectTypeId]
 
   return { result: { objectTypeIds }, query: { kind: "start", objectTypeId, includeSubtypes } }
 }
@@ -895,16 +957,15 @@ function validateTextQuery(
       continue
     }
 
-    if (fieldsByObjectType) fieldsByObjectType[objectType.id] = uniqueStrings(fieldIds)
+    const admitted = admitTextFields(fieldIds, fields === undefined, {
+      state: admissionState,
+      objectTypeId: objectType.id,
+      path: `${path}.fields`,
+      ctx,
+    })
+    if (fieldsByObjectType) fieldsByObjectType[objectType.id] = uniqueStrings(admitted)
 
     for (const fieldId of fieldIds) {
-      admitProperty(ctx, {
-        state: admissionState,
-        propertyId: fieldId,
-        objectTypeId: objectType.id,
-        use: "text",
-        path: `${path}.fields`,
-      })
       const property = getProperty(objectType, fieldId)
       if (!property) {
         addIssue(
@@ -933,6 +994,43 @@ function validateTextQuery(
   return fieldsByObjectType ? { fieldsByObjectType } : {}
 }
 
+/**
+ * Admit the fields a text query searches. Every explicit field must be admitted. Default fields
+ * come from the type's search profile, so a reader that cannot use one searches the others
+ * instead; only a type left with no usable default field is denied.
+ */
+function admitTextFields(
+  fieldIds: readonly string[],
+  defaults: boolean,
+  input: {
+    readonly state: ObjectQueryAdmissionState
+    readonly objectTypeId: string
+    readonly path: string
+    readonly ctx: QueryValidationContext
+  }
+): readonly string[] {
+  const admitted: string[] = []
+  let firstDenial: Error | undefined
+  for (const fieldId of fieldIds) {
+    const denial = input.ctx.admission.property({
+      state: input.state,
+      propertyId: fieldId,
+      objectTypeId: input.objectTypeId,
+      use: "text",
+      path: input.path,
+    })
+    if (!denial) {
+      admitted.push(fieldId)
+    } else if (!defaults) {
+      recordAdmissionDenial(input.ctx, denial)
+    } else {
+      firstDenial ??= denial
+    }
+  }
+  if (admitted.length === 0 && firstDenial) recordAdmissionDenial(input.ctx, firstDenial)
+  return admitted
+}
+
 function validateVectorProfileQuery(
   query: ObjectQueryVector,
   shape: ObjectQueryResultShape,
@@ -1060,7 +1158,9 @@ function validateOutgoingTraverse(
     }
   }
 
-  return { objectTypeIds: uniqueStrings(targetTypeIds) }
+  const objectTypeIds = uniqueStrings(targetTypeIds)
+  touchLinkTargets(objectTypeIds, ctx)
+  return { objectTypeIds }
 }
 
 function validateIncomingTraverse(
@@ -1261,7 +1361,22 @@ function resolveOutgoingExpansionTargets(
     )
   }
 
-  return { objectTypeIds: uniqueStrings(targetTypeIds) }
+  const objectTypeIds = uniqueStrings(targetTypeIds)
+  touchLinkTargets(objectTypeIds, ctx)
+  return { objectTypeIds }
+}
+
+/**
+ * Following a link outgoing reads every subtype of its declared targets: links accept subtype
+ * targets and storage follows them by link id alone. Authorize those reads like a `start` that
+ * includes subtypes; the result shape keeps the declared targets that later nodes validate against.
+ * Incoming edges already name every source type they can return: storage matches a pinned
+ * `sourceObjectTypeId` exactly, and otherwise subtypes inherit the link.
+ */
+function touchLinkTargets(objectTypeIds: readonly string[], ctx: QueryValidationContext): void {
+  for (const objectTypeId of withSubtypes(objectTypeIds, ctx)) {
+    ctx.touchedObjectTypeIds.add(objectTypeId)
+  }
 }
 
 function resolveIncomingExpansionTargets(
@@ -1657,6 +1772,10 @@ function uniqueStrings(values: readonly string[]): string[] {
   return [...new Set(values)]
 }
 
+function withSubtypes(objectTypeIds: readonly string[], ctx: QueryValidationContext): string[] {
+  return uniqueStrings(objectTypeIds.flatMap((id) => [id, ...ctx.ontology.listSubTypes(id)]))
+}
+
 function admitTransition(
   ctx: QueryValidationContext,
   transition: ObjectQueryAdmissionTransition

package/src/objects/sdk/file-handle.ts

@@ -0,0 +1,77 @@
+/**
+ * File handle factory for ObjectReadByIdHandle.
+ *
+ * Opens a `fileRef` property through the object that holds it, the way the object file content
+ * route does: the object is read again with the caller's permissions, the FileRef is resolved in
+ * that authorized row, then checked against the stored blob before it is opened.
+ */
+import { AuthorizationError } from "../../authorization/errors"
+import { jsonPointerSegment, openFileRef, resolveFileRefAtPath } from "../../blob-storage/internal"
+import type { Property } from "../../ontology"
+import { OntologyValidationError } from "../../ontology/errors"
+import type { PropertyToken } from "../../ontology/tokens"
+import { assertPropertyTokenBelongsToObjectType } from "../../ontology/validation"
+import type { ObjectFileHandle } from "../../runtime/types"
+import type { ObjectSetContext } from "../context"
+
+export function createObjectFileHandle(
+  ctx: ObjectSetContext,
+  primaryId: string,
+  property: PropertyToken<string, string, Property>,
+  index?: number
+): ObjectFileHandle {
+  const { objectType } = ctx
+  assertPropertyTokenBelongsToObjectType(objectType, property)
+  const registered = ctx.ontology
+    .resolveObjectType(objectType.id)
+    .properties.find((candidate) => candidate.id === property.id)
+  if (!registered) {
+    throw new OntologyValidationError(
+      `[Sixb] Unknown property '${property.id}' for object type '${objectType.id}'`
+    )
+  }
+  const path = filePropertyPath(objectType.id, registered, index)
+
+  return {
+    async open() {
+      const row = await ctx.objectReader.getByPrimaryId({ objectTypeId: objectType.id, primaryId })
+      if (!row) return null
+      if (row.redactions?.[property.id]) {
+        // Redacted, so the registered property has a marking the caller is not cleared for.
+        const markings = registered.markings ?? []
+        const marking =
+          markings.find((markingId) => !ctx.authorization?.clearances?.has(markingId)) ??
+          markings[0]
+        throw new AuthorizationError(
+          `clearance:marking:${marking}`,
+          `[Sixb] Cannot open file '${objectType.id}.${property.id}': it requires clearance for marking '${marking}'.`
+        )
+      }
+      const fileRef = resolveFileRefAtPath(row, path)
+      return fileRef ? openFileRef(ctx.blobStorage, fileRef) : null
+    },
+  }
+}
+
+/** JSON Pointer to the file in an object row, validated against the property's schema. */
+function filePropertyPath(objectTypeId: string, property: Property, index: number | undefined) {
+  const { schema } = property
+  const name = `${objectTypeId}.${property.id}`
+  if (schema === "fileRef") {
+    if (index !== undefined) {
+      throw new OntologyValidationError(`[Sixb] Property ${name} holds one file; omit the index.`)
+    }
+    return `/properties/${jsonPointerSegment(property.id)}`
+  }
+  if (typeof schema === "object" && schema.type === "array" && schema.items === "fileRef") {
+    if (index === undefined || !Number.isSafeInteger(index) || index < 0) {
+      throw new OntologyValidationError(
+        `[Sixb] Property ${name} holds a list of files; pass the index of the file to open.`
+      )
+    }
+    return `/properties/${jsonPointerSegment(property.id)}/${index}`
+  }
+  throw new OntologyValidationError(
+    `[Sixb] Property ${name} is not a file: file() takes a "fileRef" property or a list of them.`
+  )
+}

package/src/objects/sdk/object-handle.ts

@@ -5,26 +5,27 @@
  */
 
 import type { ActionDefinition } from "../../actions"
-import type { ObjectLink, ObjectRef } from "../../ontology"
+import type { ObjectLink, ObjectRef, Property } from "../../ontology"
 import { OntologyValidationError } from "../../ontology/errors"
-import type { LinkToken, ObjectTypeWithPropertyTokens } from "../../ontology/tokens"
+import type { LinkToken, ObjectTypeWithPropertyTokens, PropertyToken } from "../../ontology/tokens"
 import { assertLinkTokenBelongsToObjectType } from "../../ontology/validation"
 import type { ObjectByIdHandle, TwinObject } from "../../runtime/types"
 import {
   requestActionAndWait as requestActionAndWaitLeaf,
   requestAction as requestActionLeaf,
 } from "../action"
-import type { ExecutionObjectContext, ResolvedLinkContext } from "../context"
+import type { ObjectSetContext, ResolvedLinkContext } from "../context"
 import { removeLink as removeLinkLeaf, upsertLink as upsertLinkLeaf } from "../link"
 import { deleteObject, restoreObject } from "../object"
 import { createObjectVectorHandle } from "../vectors/handle"
+import { createObjectFileHandle } from "./file-handle"
 import { createTelemetryChannel } from "./telemetry-channel"
 
 type ObjectRefInput = ObjectRef
 type AnyLinkToken = LinkToken<string, string, string | readonly string[], ObjectLink>
 
 export function createObjectByIdHandle<TObjectType extends ObjectTypeWithPropertyTokens>(
-  ctx: ExecutionObjectContext,
+  ctx: ObjectSetContext,
   primaryId: string
 ): ObjectByIdHandle<TObjectType> {
   const objectHandle = {
@@ -130,6 +131,9 @@ export function createObjectByIdHandle<TObjectType extends ObjectTypeWithPropert
     },
 
     telemetry: createTelemetryChannel<TObjectType>(ctx, primaryId),
+
+    file: (property: PropertyToken<string, string, Property>, index?: number) =>
+      createObjectFileHandle(ctx, primaryId, property, index),
   }
 
   return objectHandle as unknown as ObjectByIdHandle<TObjectType>

package/src/objects/sdk/object-set.ts

@@ -6,6 +6,7 @@
 
 import type { ActionDefinition } from "../../actions"
 import type { AuthorizationContext } from "../../authorization"
+import type { BlobStorage } from "../../blob-storage"
 import { shareSixbErrorReporter } from "../../error-reporting/capability"
 import type { ExecutionContext } from "../../execution"
 import { assertAuthorizedObjectReaderBinding } from "../../execution/authorized-object-reader"
@@ -22,7 +23,7 @@ import {
   requestActionAndWait as requestActionAndWaitLeaf,
   requestAction as requestActionLeaf,
 } from "../action"
-import type { ExecutionObjectContext, ResolvedLinkContext } from "../context"
+import type { ObjectSetContext, ResolvedLinkContext } from "../context"
 import { requireLinkDefinition } from "../context"
 import { removeLink as removeLinkLeaf, upsertLink as upsertLinkLeaf } from "../link"
 import { upsertObject as upsertObjectLeaf } from "../object"
@@ -36,6 +37,7 @@ export function createObjectSet<TObjectType extends ObjectTypeWithPropertyTokens
     readonly execution: ExecutionContext
     readonly objectType: TObjectType
     readonly authorization?: AuthorizationContext
+    readonly blobStorage: Pick<BlobStorage, "stat" | "open">
   }
 ): ObjectSet<TObjectType> {
   assertAuthorizedObjectReaderBinding({
@@ -67,7 +69,7 @@ export function createObjectSet<TObjectType extends ObjectTypeWithPropertyTokens
     objectReader,
   })
 
-  const resolvedCtx: ExecutionObjectContext = {
+  const resolvedCtx: ObjectSetContext = {
     embeddingModels: params.embeddingModels,
     projectId,
     broker,
@@ -80,6 +82,7 @@ export function createObjectSet<TObjectType extends ObjectTypeWithPropertyTokens
     runtimeAuthorization,
     authorization,
     execution,
+    blobStorage: params.blobStorage,
     objectType,
     primaryPropertyId,
   }

package/src/ontology/builders.ts

@@ -26,6 +26,8 @@
  * ```
  */
 
+import { markingIdsFrom } from "../security/builders"
+import type { MarkingDefinition } from "../security/types"
 import type { ObjectTypeWithPropertyTokens, ObjectTypeWithTokens } from "./tokens"
 import { createLinkTokenMap, createPropertyTokenMap } from "./tokens"
 import type {
@@ -353,8 +355,17 @@ type PropertyOptions = {
   mode?: PropertyMode
   semanticType?: QuantitativeTypeId
   query?: PropertyQueryMetadata
+  /** Readers need a clearance for every marking to receive this property's value. */
+  markings?: readonly MarkingDefinition[]
 }
 
+/** The property records marking ids; only a declared, non-empty list marks it. */
+type MarkingsFromOptions<TOptions> = TOptions extends {
+  markings: readonly [MarkingDefinition, ...MarkingDefinition[]]
+}
+  ? { markings: readonly string[] }
+  : { markings?: readonly string[] }
+
 type PropertyResult<
   TId extends string,
   TSchema extends Schema,
@@ -369,7 +380,8 @@ type PropertyResult<
   FieldFromOptions<TOptions, "primary", true> &
   FieldFromOptions<TOptions, "mode", PropertyMode> &
   FieldFromOptions<TOptions, "semanticType", QuantitativeTypeId> &
-  FieldFromOptions<TOptions, "query", PropertyQueryMetadata>
+  FieldFromOptions<TOptions, "query", PropertyQueryMetadata> &
+  MarkingsFromOptions<TOptions>
 
 /**
  * Shorthand for creating a {@link Property}.
@@ -396,11 +408,15 @@ export function prop<
   const TOptions extends PropertyOptions,
 >(id: TId, schema: TSchema, options: TOptions): PropertyResult<TId, TSchema, TOptions>
 export function prop(id: string, schema: Schema, options?: PropertyOptions): Property {
+  const { markings, ...rest } = options ?? {}
   return {
     id,
     name: options?.name ?? id,
     schema,
-    ...options,
+    ...rest,
+    ...(markings && markings.length > 0
+      ? { markings: markingIdsFrom(markings, `Property '${id}' markings`) }
+      : {}),
   }
 }