@sixb/core 0.1.16 → 0.1.18

package/src/runtime/types.ts

@@ -12,11 +12,12 @@ import type {
   RequestActionResult,
 } from "../actions"
 import type { AuthorizationContext } from "../authorization"
+import type { OpenedFileRef } from "../blob-storage"
 import type { Broker } from "../broker"
 import type { DomainEventLog } from "../events"
 import type { RuntimeAuthorization } from "../execution"
 import type { AuthorizedObjectReader } from "../execution/authorized-object-reader"
-import type { EmbeddingModelCatalog } from "../models"
+import type { EmbeddingModelCatalog, RerankingModelCatalog, RerankingModelRef } from "../models"
 import type { ModelExecutionSession } from "../models/execution/session"
 import type {
   ObjectQuery,
@@ -43,11 +44,12 @@ import type { OntologyDocumentInput, OntologyRegistry, OntologySource } from "..
 import type {
   LinkToken,
   ObjectTypeProperties,
+  ObjectTypeReadProperties,
   ObjectTypeWithPropertyTokens,
   PropertyToken,
 } from "../ontology/tokens"
 import type { Queues } from "../queues"
-import type { ActionRunRecord, ObjectLinkRow, Storage } from "../storage"
+import type { ActionRunRecord, ObjectLinkRow, Redactions, Storage } from "../storage"
 // ── Shared runtime context ──────────────────────────────────
 
 /**
@@ -58,6 +60,7 @@ import type { ActionRunRecord, ObjectLinkRow, Storage } from "../storage"
  */
 export interface SixbHostContext {
   readonly embeddingModels?: EmbeddingModelCatalog
+  readonly rerankingModels?: RerankingModelCatalog
   readonly projectId: string
   readonly broker: Broker
   readonly ontology: OntologyRegistry
@@ -99,7 +102,7 @@ export type { OntologyDocumentInput, OntologySource }
 // ── Rows ────────────────────────────────────────────────────
 //
 // Rows read `properties` from the type inferred where the object type is defined
-// (`ObjectTypeProperties`), never from the schema, so relating two rows — or anything returning
+// (`ObjectTypeReadProperties`), never from the schema, so relating two rows — or anything returning
 // them — costs no schema inference. Rows and query builders also declare their variance, so
 // TypeScript never measures it: a measurement that overflows (TS2589) caches the variance it gave
 // up on, under which a plain query once passed for an expanded one.
@@ -108,7 +111,10 @@ export type { OntologyDocumentInput, OntologySource }
 export type TwinObject<out TObjectType extends ObjectTypeWithPropertyTokens> = {
   primaryId: string
   objectTypeId: TObjectType["id"]
-  properties: ObjectTypeProperties<TObjectType>
+  /** A marked property is absent when the reader lacks its clearance; see `redactions`. */
+  properties: ObjectTypeReadProperties<TObjectType>
+  /** Properties omitted because the reader lacks a clearance, keyed by property id. */
+  redactions?: Redactions
   createdAt: Date
   updatedAt: Date
 }
@@ -312,6 +318,32 @@ export type ObjectWhereBuilder<TObjectType extends ObjectTypeWithPropertyTokens>
 export type TelemetryPropertyToken<TObjectType extends ObjectTypeWithPropertyTokens> =
   TObjectType["p"][InferTelemetryPropertyIds<TObjectType>]
 
+type FilePropertyId<TObjectType extends ObjectTypeWithPropertyTokens, TSchema> = Extract<
+  TObjectType["properties"][number],
+  { readonly schema: TSchema }
+>["id"]
+
+/** A property token holding one file: its schema is `"fileRef"`. */
+export type FilePropertyToken<TObjectType extends ObjectTypeWithPropertyTokens> =
+  TObjectType["p"][FilePropertyId<TObjectType, "fileRef">]
+
+/** A property token holding a list of files: an array of `"fileRef"`. */
+export type FileListPropertyToken<TObjectType extends ObjectTypeWithPropertyTokens> =
+  TObjectType["p"][FilePropertyId<
+    TObjectType,
+    { readonly type: "array"; readonly items: "fileRef" }
+  >]
+
+/** One file property value of one object, read through that object. */
+export interface ObjectFileHandle {
+  /**
+   * Re-read the object with the caller's permissions and open the file it references. Returns
+   * null when the object, the value or its stored blob is absent; throws `AuthorizationError`
+   * when the caller cannot view the object type or is not cleared for the property's markings.
+   */
+  open(): Promise<OpenedFileRef | null>
+}
+
 type AnyPropertyToken = PropertyToken<string, string, Property>
 
 type ObjectSetPropertyId<TObjectType extends ObjectTypeWithPropertyTokens> =
@@ -414,6 +446,12 @@ export type ObjectQueryFacetBucket = {
   count: number
 }
 
+/** Total and facet buckets are calculated from the same matching set. */
+export type ObjectQueryFacetsResult = {
+  total: number
+  facets: ObjectQueryFacetResult[]
+}
+
 export type ObjectQueryFacetResult = {
   propertyId: string
   buckets: ObjectQueryFacetBucket[]
@@ -669,6 +707,9 @@ export interface ObjectQueryBuilder<
     options: { k: number }
   ): ObjectQueryBuilder<TObjectType, TRow>
 
+  /** Reorder up to 100 vector candidates with an explicitly registered server-side model. */
+  rerank(options: { model: RerankingModelRef }): ObjectQueryBuilder<TObjectType, TRow>
+
   /** Follow an outgoing link and make the linked object type the current result type. */
   traverse<TLinkToken extends LinkToken<TObjectType["id"], string, LinkTargetObjectTypeIdValue>>(
     link: TLinkToken,
@@ -750,7 +791,7 @@ export interface ObjectQueryBuilder<
   exists(): Promise<boolean>
 
   /** Count matching objects by configured facetable properties. */
-  facets(input: readonly ObjectQueryFacetInput<TObjectType>[]): Promise<ObjectQueryFacetResult[]>
+  facets(input: readonly ObjectQueryFacetInput<TObjectType>[]): Promise<ObjectQueryFacetsResult>
 
   /** Execute this query with an outer limit of one and return the first object. */
   first(): Promise<Simplify<TRow> | null>
@@ -763,6 +804,11 @@ export interface ObjectReadByIdHandle<out TObjectType extends ObjectTypeWithProp
 
   /** List links from this object, optionally filtered by link token. */
   listLinks(link?: LinkTokenForObjectType<TObjectType>): Promise<readonly ObjectLinkRow[]>
+
+  /** Read a `fileRef` property of this object. */
+  file(property: FilePropertyToken<TObjectType>): ObjectFileHandle
+  /** Read one file of a property holding a list of files. */
+  file(property: FileListPropertyToken<TObjectType>, index: number): ObjectFileHandle
 }
 
 /**

package/src/scheduler/runtime.ts

@@ -18,6 +18,8 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647
 export interface SchedulerRuntimeOptions {
   schedules: readonly ScheduleDefinition[]
   events: DomainEventLog
+  /** Evaluates cron schedules that set no time zone of their own. Defaults to UTC. */
+  timeZone?: string
   now?: () => Date
 }
 
@@ -30,6 +32,7 @@ export interface SchedulerController {
 export class SchedulerRuntime implements SchedulerController {
   private readonly schedules: readonly CronScheduleDefinition[]
   private readonly events: DomainEventLog
+  private readonly timeZone: string | undefined
   private readonly now: () => Date
   private started = false
   private timer: ReturnType<typeof setTimeout> | null = null
@@ -39,6 +42,8 @@ export class SchedulerRuntime implements SchedulerController {
   constructor(options: SchedulerRuntimeOptions) {
     this.schedules = options.schedules.filter(isCronSchedule)
     this.events = options.events
+    // `undefined` keeps the arithmetic UTC path; an explicit "UTC" would go through Intl.
+    this.timeZone = options.timeZone === "UTC" ? undefined : options.timeZone
     this.now = options.now ?? (() => new Date())
   }
 
@@ -60,7 +65,11 @@ export class SchedulerRuntime implements SchedulerController {
       // agree, or one unschedulable expression stops every other schedule in the project and
       // crash-loops the scheduler role.
       try {
-        const next = nextCronOccurrence(schedule.trigger.expression, now, schedule.trigger.timezone)
+        const next = nextCronOccurrence(
+          schedule.trigger.expression,
+          now,
+          schedule.trigger.timezone ?? this.timeZone
+        )
         this.nextOccurrences.set(schedule.id, next)
       } catch (error) {
         console.error(
@@ -178,7 +187,7 @@ export class SchedulerRuntime implements SchedulerController {
         const next = nextCronOccurrence(
           schedule.trigger.expression,
           occurrenceAt,
-          schedule.trigger.timezone
+          schedule.trigger.timezone ?? this.timeZone
         )
         this.nextOccurrences.set(schedule.id, next)
       } catch (error) {

package/src/security/builders.ts

@@ -2,6 +2,7 @@ import { SecurityValidationError } from "./errors"
 import type {
   GrantDefinition,
   GroupDefinition,
+  MarkingDefinition,
   MembershipOperation,
   MembershipPolicyDefinition,
   RoleDefinition,
@@ -18,11 +19,18 @@ export interface DefineGroupOptions {
   readonly description?: string
 }
 
+export interface DefineMarkingOptions {
+  readonly label?: string
+  readonly description?: string
+}
+
 export interface DefineRoleOptions {
   readonly label?: string
   readonly description?: string
   readonly grantedTo: readonly GroupDefinition[]
-  readonly grants: readonly GrantDefinition[]
+  readonly grants?: readonly GrantDefinition[]
+  /** Markings this role's members may read. */
+  readonly clearances?: readonly MarkingDefinition[]
 }
 
 export interface DefineMembershipPolicyOptions {
@@ -81,6 +89,37 @@ export function defineGroup<const TId extends string>(
   }
 }
 
+/** Read the ids of marking definitions, rejecting anything else such as a bare id. */
+export function markingIdsFrom(
+  markings: readonly MarkingDefinition[],
+  field: string
+): readonly string[] {
+  return markings.map((marking) => {
+    if (!isRecord(marking) || marking.kind !== "marking") {
+      throw new SecurityValidationError(`[Sixb] ${field} must contain only marking definitions.`)
+    }
+
+    assertNonEmptyString(marking.id, `${field} marking id`)
+    return marking.id
+  })
+}
+
+export function defineMarking<const TId extends string>(
+  id: TId,
+  options: DefineMarkingOptions = {}
+): MarkingDefinition<TId> {
+  assertNonEmptyString(id, "Marking id")
+  assertOptionalString(options.label, `Marking '${id}' label`)
+  assertOptionalString(options.description, `Marking '${id}' description`)
+
+  return {
+    kind: "marking",
+    id,
+    ...(options.label !== undefined ? { label: options.label } : {}),
+    ...(options.description !== undefined ? { description: options.description } : {}),
+  }
+}
+
 export function defineRole<const TId extends string>(
   id: TId,
   options: DefineRoleOptions
@@ -91,13 +130,17 @@ export function defineRole<const TId extends string>(
   assertNonEmptyArray(options.grantedTo, `Role '${id}' grantedTo`)
 
   const grantedToGroupIds = groupIdsFrom(options.grantedTo, `Role '${id}' grantedTo`)
+  const grants = options.grants ?? []
+  const clearances = markingIdsFrom(options.clearances ?? [], `Role '${id}' clearances`)
 
-  for (const grant of options.grants) {
+  for (const grant of grants) {
     assertGrantDefinition(grant, `Role '${id}' grants`)
   }
 
-  if (options.grants.length === 0) {
-    throw new SecurityValidationError(`[Sixb] Role '${id}' grants must not be empty.`)
+  if (grants.length === 0 && clearances.length === 0) {
+    throw new SecurityValidationError(
+      `[Sixb] Role '${id}' must declare at least one grant or clearance.`
+    )
   }
 
   return {
@@ -106,7 +149,8 @@ export function defineRole<const TId extends string>(
     ...(options.label !== undefined ? { label: options.label } : {}),
     ...(options.description !== undefined ? { description: options.description } : {}),
     grantedToGroupIds,
-    grants: options.grants,
+    grants,
+    ...(clearances.length > 0 ? { clearances } : {}),
   }
 }
 

package/src/security/index.ts

@@ -1,10 +1,11 @@
 export { applications } from "./applications"
 export type {
   DefineGroupOptions,
+  DefineMarkingOptions,
   DefineMembershipPolicyOptions,
   DefineRoleOptions,
 } from "./builders"
-export { defineGroup, defineMembershipPolicy, defineRole } from "./builders"
+export { defineGroup, defineMarking, defineMembershipPolicy, defineRole } from "./builders"
 export { SecurityValidationError } from "./errors"
 export type { BreadthSelector, BreadthTarget } from "./every"
 export { every } from "./every"
@@ -31,10 +32,13 @@ export type {
   GroupReference,
   ManageGrant,
   ManageGrantTarget,
+  MarkingDefinition,
   MembershipOperation,
   MembershipPolicyDefinition,
   ObserveGrant,
   ObserveGrantTarget,
+  RedactionReason,
+  Redactions,
   RegisteredSecurityDefinitions,
   RoleDefinition,
   RunGrant,
@@ -50,6 +54,7 @@ export {
   assertMembershipPolicyDefinition,
   assertRoleDefinition,
   isGroupDefinition,
+  isMarkingDefinition,
   isMembershipPolicyDefinition,
   isRoleDefinition,
   validateSecurityDefinitionsAtStartup,

package/src/security/markings.ts

@@ -0,0 +1,313 @@
+import type { DatasetDefinition } from "../datasets/types"
+import type { OntologyDefinitionCatalog } from "../ontology/registry"
+import type { ObjectType, Property } from "../ontology/types"
+import type { PipelineDefinition } from "../pipelines/types"
+import type { ProjectionDefinitionCatalog } from "../projections/registry"
+import type { ObjectProjectionDefinition } from "../projections/types"
+import { SecurityValidationError } from "./errors"
+
+/**
+ * Check every marking once at startup.
+ *
+ * A marking is enforced at read time from the property or column definition alone, so each rule
+ * here closes a path that would otherwise return the value unredacted or make enforcement
+ * ambiguous.
+ */
+export function validateMarkingsAtStartup(input: {
+  readonly markingIds: ReadonlySet<string>
+  readonly ontology: OntologyDefinitionCatalog
+  readonly datasetsById: ReadonlyMap<string, DatasetDefinition>
+  readonly pipelines: readonly PipelineDefinition[]
+  readonly projections: ProjectionDefinitionCatalog
+}): void {
+  validatePropertyMarkings(input.ontology, input.markingIds)
+  validateColumnMarkings(input.datasetsById, input.markingIds)
+  rejectPipelineStepsOverMarkedColumns(input.pipelines, input.datasetsById)
+  validateProjectionMarkings(input.projections, input.ontology, input.datasetsById)
+}
+
+// ── Declarations ────────────────────────────────────────────
+
+function validatePropertyMarkings(
+  ontology: OntologyDefinitionCatalog,
+  markingIds: ReadonlySet<string>
+): void {
+  for (const objectType of ontology.listObjectTypes()) {
+    for (const property of objectType.properties) {
+      validateProperty(objectType, property, markingIds)
+    }
+    for (const link of objectType.links) {
+      for (const property of link.properties ?? []) {
+        if (property.markings !== undefined) {
+          throw new SecurityValidationError(
+            `[Sixb] Link property '${objectType.id}.${link.id}.${property.id}' cannot carry markings. Mark object properties instead.`
+          )
+        }
+      }
+    }
+    assertSubtypeKeepsParentMarkings(objectType, ontology)
+  }
+}
+
+function validateProperty(
+  objectType: ObjectType,
+  property: Property,
+  markingIds: ReadonlySet<string>
+): void {
+  if (property.markings === undefined) return
+  const path = `${objectType.id}.${property.id}`
+  assertMarkingList(property.markings, `Property '${path}'`, markingIds)
+
+  // The primary id identifies the object in every response, link, and event.
+  if (property.primary) {
+    throw new SecurityValidationError(
+      `[Sixb] Primary property '${path}' cannot carry markings: it identifies the object.`
+    )
+  }
+  // Telemetry values also flow through history reads and telemetry events, which do not
+  // enforce markings yet.
+  if (property.mode === "telemetry") {
+    throw new SecurityValidationError(
+      `[Sixb] Telemetry property '${path}' cannot carry markings yet.`
+    )
+  }
+}
+
+/**
+ * A subtype inherits its parent's properties and may redefine them. Subtype rows are returned by
+ * parent-type reads, so a redefinition that dropped a marking would declassify the parent's data.
+ */
+function assertSubtypeKeepsParentMarkings(
+  objectType: ObjectType,
+  ontology: OntologyDefinitionCatalog
+): void {
+  if (!objectType.extends) return
+  const parent = ontology.getObjectTypeById(objectType.extends)
+  if (!parent) return
+
+  for (const parentProperty of parent.properties) {
+    const property = objectType.properties.find((candidate) => candidate.id === parentProperty.id)
+    const missing = missingMarkings(parentProperty.markings, property?.markings)
+    if (missing.length > 0) {
+      throw new SecurityValidationError(
+        `[Sixb] Property '${objectType.id}.${parentProperty.id}' must keep the markings of '${parent.id}.${parentProperty.id}': add ${missing.map((markingId) => `'${markingId}'`).join(", ")}.`
+      )
+    }
+  }
+}
+
+function validateColumnMarkings(
+  datasetsById: ReadonlyMap<string, DatasetDefinition>,
+  markingIds: ReadonlySet<string>
+): void {
+  for (const dataset of datasetsById.values()) {
+    for (const column of dataset.schema.columns) {
+      if (column.markings === undefined) continue
+      assertMarkingList(
+        column.markings,
+        `Dataset column '${dataset.id}.${column.name}'`,
+        markingIds
+      )
+    }
+  }
+}
+
+function assertMarkingList(
+  markings: unknown,
+  subject: string,
+  markingIds: ReadonlySet<string>
+): void {
+  if (!Array.isArray(markings) || markings.length === 0) {
+    throw new SecurityValidationError(
+      `[Sixb] ${subject} markings must be a non-empty list of marking ids.`
+    )
+  }
+  if (new Set(markings).size !== markings.length) {
+    throw new SecurityValidationError(`[Sixb] ${subject} lists the same marking twice.`)
+  }
+  for (const markingId of markings) {
+    if (typeof markingId !== "string" || !markingIds.has(markingId)) {
+      throw new SecurityValidationError(
+        `[Sixb] ${subject} references unknown marking '${String(markingId)}'. Add it to 'security/markings/' or pass it to createSixb({ markings }).`
+      )
+    }
+  }
+}
+
+// ── Propagation ─────────────────────────────────────────────
+
+/**
+ * A step's output inherits nothing from its inputs until Sixb can derive each output column's
+ * markings from the transform. Until then, reading a marked column would declassify it.
+ */
+function rejectPipelineStepsOverMarkedColumns(
+  pipelines: readonly PipelineDefinition[],
+  datasetsById: ReadonlyMap<string, DatasetDefinition>
+): void {
+  for (const pipeline of pipelines) {
+    for (const { step } of pipeline.graph.nodes) {
+      for (const input of Object.values(step.inputs)) {
+        const dataset = datasetsById.get(input.id)
+        const column = dataset?.schema.columns.find((candidate) => candidate.markings)
+        if (!dataset || !column) continue
+        throw new SecurityValidationError(
+          `[Sixb] Pipeline '${pipeline.id}' step '${step.id}' reads column '${dataset.id}.${column.name}', which carries ${markingList(column.markings)}. Pipeline steps cannot read marked columns yet.`
+        )
+      }
+    }
+  }
+}
+
+/**
+ * Objects are read through the ontology, so each projected property declares the markings of its
+ * column: the ontology stays the reviewed contract of what each reader receives. Values that
+ * identify objects or key links are returned wherever the object or link is, and telemetry does
+ * not enforce markings yet, so those columns cannot carry markings.
+ */
+function validateProjectionMarkings(
+  projections: ProjectionDefinitionCatalog,
+  ontology: OntologyDefinitionCatalog,
+  datasetsById: ReadonlyMap<string, DatasetDefinition>
+): void {
+  for (const projection of projections.listObjects()) {
+    const objectType = ontology.getObjectTypeById(projection.objectTypeId)
+    if (objectType) validateObjectProjection(projection, objectType, datasetsById)
+  }
+
+  for (const projection of projections.listLinks()) {
+    const role = `keys link '${projection.sourceObjectTypeId}.${projection.linkId}'`
+    for (const columnName of [projection.sourceField, projection.targetField]) {
+      assertUnmarkedColumn(projection, sourceColumn(projection, columnName, datasetsById), role)
+    }
+  }
+
+  for (const projection of projections.listTelemetry()) {
+    const columnNames = [
+      projection.objectIdField,
+      projection.atField,
+      ...Object.values(projection.properties).flatMap((mapping) =>
+        mapping.unitField === undefined
+          ? [mapping.valueField]
+          : [mapping.valueField, mapping.unitField]
+      ),
+    ]
+    for (const columnName of columnNames) {
+      const column = sourceColumn(projection, columnName, datasetsById)
+      if (!column.markings) continue
+      throw new SecurityValidationError(
+        `[Sixb] Projection '${projection.id}' reads column '${column.path}', which carries ${markingList(column.markings)}. Telemetry projections cannot read marked columns yet.`
+      )
+    }
+  }
+}
+
+function validateObjectProjection(
+  projection: ObjectProjectionDefinition,
+  objectType: ObjectType,
+  datasetsById: ReadonlyMap<string, DatasetDefinition>
+): void {
+  const keyRoles = objectProjectionKeyRoles(projection, objectType)
+
+  for (const [propertyId, columnName] of Object.entries(projection.properties)) {
+    const column = sourceColumn(projection, columnName, datasetsById)
+    const property = objectType.properties.find((candidate) => candidate.id === propertyId)
+    const path = `${objectType.id}.${propertyId}`
+    const keyRole = keyRoles.get(propertyId)
+    if (keyRole) {
+      assertUnmarkedColumn(projection, column, keyRole)
+      if (property?.markings) {
+        throw new SecurityValidationError(
+          `[Sixb] Projection '${projection.id}': property '${path}' ${keyRole} and cannot carry markings.`
+        )
+      }
+      continue
+    }
+    const missing = missingMarkings(column.markings, property?.markings)
+    if (missing.length > 0) {
+      throw new SecurityValidationError(
+        `[Sixb] Projection '${projection.id}': property '${path}' is projected from column '${column.path}', which carries ${markingList(column.markings)}. Add markings: ${markingList(missing)} to the property.`
+      )
+    }
+  }
+
+  for (const [linkId, link] of Object.entries(projection.links)) {
+    if (link.sourceField === undefined) continue
+    assertUnmarkedColumn(
+      projection,
+      sourceColumn(projection, link.sourceField, datasetsById),
+      `keys link '${objectType.id}.${linkId}'`
+    )
+  }
+
+  // The timestamp decides whether the source value or an app edit wins, which reveals how they
+  // compare.
+  const conflictResolution = projection.conflictResolution
+  if (conflictResolution?.strategy === "mostRecent") {
+    assertUnmarkedColumn(
+      projection,
+      sourceColumn(projection, conflictResolution.sourceTimestamp, datasetsById),
+      "decides which value wins under 'mostRecent'"
+    )
+  }
+}
+
+/** Properties whose value becomes an object id or a link key, with the role they play. */
+function objectProjectionKeyRoles(
+  projection: ObjectProjectionDefinition,
+  objectType: ObjectType
+): ReadonlyMap<string, string> {
+  const roles = new Map<string, string>()
+  for (const property of objectType.properties) {
+    if (property.primary) roles.set(property.id, `becomes the id of '${objectType.id}'`)
+  }
+  for (const [linkId, link] of Object.entries(projection.links)) {
+    if (link.sourcePropertyId === undefined) continue
+    roles.set(link.sourcePropertyId, `keys link '${objectType.id}.${linkId}'`)
+  }
+  return roles
+}
+
+interface SourceColumn {
+  readonly path: string
+  readonly markings?: readonly string[]
+}
+
+function sourceColumn(
+  projection: { readonly id: string; readonly datasetId: string },
+  columnName: string,
+  datasetsById: ReadonlyMap<string, DatasetDefinition>
+): SourceColumn {
+  const column = datasetsById
+    .get(projection.datasetId)
+    ?.schema.columns.find((candidate) => candidate.name === columnName)
+  // Projection validation runs first and resolves every mapped column.
+  if (!column) {
+    throw new Error(`[Sixb] Projection '${projection.id}' maps unknown column '${columnName}'.`)
+  }
+  return { path: `${projection.datasetId}.${columnName}`, markings: column.markings }
+}
+
+function assertUnmarkedColumn(
+  projection: { readonly id: string },
+  column: SourceColumn,
+  role: string
+): void {
+  if (!column.markings) return
+  throw new SecurityValidationError(
+    `[Sixb] Projection '${projection.id}': column '${column.path}' ${role} and cannot carry markings.`
+  )
+}
+
+// ── Helpers ─────────────────────────────────────────────────
+
+function missingMarkings(
+  required: readonly string[] | undefined,
+  declared: readonly string[] | undefined
+): readonly string[] {
+  const present = new Set(declared ?? [])
+  return (required ?? []).filter((markingId) => !present.has(markingId))
+}
+
+function markingList(markings: readonly string[] | undefined): string {
+  return `[${(markings ?? []).join(", ")}]`
+}

package/src/security/redactions.ts

@@ -0,0 +1,6 @@
+import type { Redactions } from "./types"
+
+/** List the values hidden from a reader that lacks a clearance for their markings. */
+export function missingClearanceRedactions(ids: Iterable<string>): Redactions {
+  return Object.fromEntries([...ids].map((id) => [id, { reason: "missing_clearance" }] as const))
+}