@sixb/core 0.1.16 → 0.1.18

package/src/agents/index.ts

@@ -1,3 +1,4 @@
+export type { PropertyClearance } from "../objects/property-clearance"
 export type {
   AgentFileDataProjection,
   AgentFileDataResolverInput,
@@ -18,6 +19,7 @@ export {
   agentServiceAccountId,
   ensureManagedAgentExecutionIdentity,
   resolveAgentExecutionAuthorization,
+  resolveAgentPropertyClearance,
   resolveInheritedAgentExecutionAuthorization,
 } from "./authority"
 export { defineAgentTool } from "./builders"
@@ -84,6 +86,7 @@ export {
 } from "./ids"
 export {
   AGENT_MESSAGE_CONTENT_VERSION,
+  type AgentContinuationPart,
   type AgentFilePart,
   type AgentMessage,
   type AgentMessagePart,
@@ -105,11 +108,19 @@ export type {
 export { runModelLoop } from "./model-loop"
 export { agent } from "./reference"
 export {
+  isRetryableAgentRun,
   type RequestAgentRunInput,
   type RequestAgentRunResult,
   requestAgentRun,
   retryAgentRun,
 } from "./request"
+export type {
+  AgentDefinitions,
+  AgentDefinitionsInput,
+  AgentProjectFile,
+  AgentSkillCatalog,
+  AgentSkillDefinition,
+} from "./skills"
 export type {
   AgentCompactionFailureCode,
   AgentRunControlStreamId,
@@ -144,11 +155,11 @@ export { isAgentToolResult } from "./tool-result"
 export type {
   AgentDescriptor,
   AgentReasoning,
-  AgentReasoningLevel,
   AgentReference,
   AgentToolArtifact,
   AgentToolArtifactPutInput,
   AgentToolArtifacts,
+  AgentToolAttachments,
   AgentToolContent,
   AgentToolDefinition,
   AgentToolDescriptionBuilder,
@@ -161,6 +172,7 @@ export type {
   AgentToolRunBuilder,
   AgentToolRunContext,
   AgentToolRunInfo,
+  AgentToolRuntimeFacade,
   AgentToolTextContent,
   AgentUsageReference,
   InferAgentToolInput,

package/src/agents/message.ts

@@ -60,6 +60,14 @@ interface AgentToolCallBase {
   readonly providerMetadata?: ProviderData
 }
 
+/**
+ * The user asked the Agent to continue an answer the turn limit cut short. Sixb writes the
+ * instruction the model reads; chats show no message for it.
+ */
+export interface AgentContinuationPart {
+  readonly type: "continuation"
+}
+
 /** Ordered, hidden provider state required to replay a model response losslessly. */
 export interface AgentProviderStatePart {
   readonly type: "provider-state"
@@ -84,6 +92,7 @@ export type AgentMessagePart =
   | AgentStepStartPart
   | AgentFilePart
   | AgentContextPart
+  | AgentContinuationPart
   | AgentToolCallPart
   | AgentProviderStatePart
 

package/src/agents/request.ts

@@ -3,6 +3,7 @@ import type { Principal } from "../auth"
 import { SYSTEM_PRINCIPAL } from "../auth"
 import { assertAuthorized } from "../authorization"
 import type { FileRef } from "../blob-storage"
+import { isValidFileRef } from "../blob-storage/validation"
 import {
   canInheritAgentRequestAuthorization,
   createInheritedAgentExecutionRecord,
@@ -10,8 +11,10 @@ import {
 import { resolveExecutionScopeAuthorization } from "../execution/authorization"
 import { ensureExecutionRecord, executionRecordInputFromRuntime } from "../execution/durable"
 import type { ExecutionContext } from "../execution/types"
-import type { LanguageModelCatalog, LanguageModelRef } from "../models"
-import { isModelReasoning } from "../models/language-model"
+import type { LanguageModelCatalog, LanguageModelEntry, LanguageModelRef } from "../models"
+import { isModelReasoning, modelReasoningSupportIssue } from "../models/language-model"
+import { resolveLanguageModel } from "../models/resolve"
+import { canonicalLocale, canonicalTimeZone } from "../runtime/locale"
 import type { SixbRuntimeContext } from "../runtime/types"
 import {
   type AgentStorage,
@@ -33,13 +36,19 @@ import { resolveAgentContextParts } from "./context-resolution"
 import { dispatchQueuedAgentRuns } from "./dispatch"
 import { AgentRequestError } from "./errors"
 import { createAgentMessageId, createAgentRunId, createAgentThreadId } from "./ids"
+import type { AgentMessagePart } from "./message"
 import { assertNoAgentSelector } from "./retired-config"
 import { publishAgentRunActivity } from "./streams/protocol"
-import { AGENT_REASONING_LEVELS, type AgentReasoningLevel } from "./types"
+import { AGENT_REASONING_LEVELS, type AgentReasoning } from "./types"
 
 export interface RequestAgentRunInput {
-  /** The user's message that triggers the turn. */
-  readonly text: string
+  /** The user's message that triggers the turn. Omitted only to {@link continue}. */
+  readonly text?: string
+  /**
+   * Continue an answer the turn limit cut short, in an existing thread. Sixb writes the
+   * instruction the model reads, so the request carries no text, attachments, or context.
+   */
+  readonly continue?: boolean
   /** Blob-backed files attached to the trigger message. */
   readonly attachments?: readonly FileRef[]
   /** Structured page/object context snapshotted onto the triggering user message. */
@@ -48,8 +57,15 @@ export interface RequestAgentRunInput {
   readonly threadId?: string
   /** Configured language model selected for this turn. Omitted uses the agent default. */
   readonly model?: LanguageModelRef
-  /** Provider-neutral reasoning effort selected for this turn. */
-  readonly reasoning?: AgentReasoningLevel
+  /** Reasoning effort or token budget for this turn. Omitted uses the model's default. */
+  readonly reasoning?: AgentReasoning
+  /**
+   * IANA time zone of the person asking, such as their browser's. The Agent presents dates and
+   * times in it. Omitted uses the project time zone.
+   */
+  readonly timeZone?: string
+  /** BCP 47 language of the person asking. Omitted uses the project locale. */
+  readonly locale?: string
   /** Title to stamp on the thread when one is created. */
   readonly title?: string
   /** Explicit id for the trigger (user) message. Defaults to a generated id. */
@@ -88,7 +104,17 @@ export async function requestAgentRun(
   assertNoAgentSelector(input)
   assertAuthorized(runtime, { kind: "agent.run" })
   assertRequestAuthorityCanRunAgent(runtime)
-  const spec = resolveConversationRunSpec({ models, input })
+  const trigger = triggerParts(input)
+  const continued = input.continue ? await continuedSelection(runtime, models, input) : {}
+  const spec = await resolveConversationRunSpec({
+    models,
+    input: {
+      ...input,
+      model: input.model ?? continued.model,
+      reasoning: input.reasoning ?? continued.reasoning,
+    },
+  })
+  assertAttachments(input.attachments)
 
   // Resolve context before creating a thread: invalid or inaccessible references must not leave an
   // empty conversation behind. The resulting parts are the exact snapshot persisted below.
@@ -142,7 +168,7 @@ export async function requestAgentRun(
         role: "user",
         parts: [
           ...contextParts,
-          { type: "text", text: input.text },
+          ...trigger,
           ...(input.attachments ?? []).map((fileRef) => ({ type: "file" as const, fileRef })),
         ],
         authorPrincipal: principal,
@@ -173,6 +199,15 @@ export async function requestAgentRun(
   }
 }
 
+/** A failed turn, or one its worker died during, can run again from the same trigger message. */
+export function isRetryableAgentRun(
+  run: Pick<ConversationAgentRunRecord, "status" | "finishReason">
+): boolean {
+  return (
+    run.status === "failed" || (run.status === "cancelled" && run.finishReason === "interrupted")
+  )
+}
+
 /** Retry a failed turn as a new child execution while reusing its immutable trigger message. */
 export async function retryAgentRun(
   runtime: SixbRuntimeContext,
@@ -186,10 +221,10 @@ export async function retryAgentRun(
   })
   assertAuthorized(runtime, { kind: "agent.run" })
   assertRequestAuthorityCanRunAgent(runtime)
-  if (failedRun.status !== "failed") {
+  if (!isRetryableAgentRun(failedRun)) {
     throw new AgentRequestError(
       "run_not_retryable",
-      `[Sixb] Only failed Agent runs can be retried.`
+      `[Sixb] Only failed or interrupted Agent runs can be retried.`
     )
   }
 
@@ -227,10 +262,10 @@ export async function retryAgentRun(
       triggerMessageId: failedRun.triggerMessageId,
       spec:
         failedRun.spec ??
-        resolveConversationRunSpec({
+        (await resolveConversationRunSpec({
           models,
           input: {},
-        }),
+        })),
     })
   })
   await publishRunActivity(runtime, run)
@@ -238,6 +273,70 @@ export async function retryAgentRun(
   return { run, ...(jobId ? { jobId } : {}), createdThread: false }
 }
 
+/**
+ * A continuation picks up where the cut-short turn stopped, with its model and reasoning unless the
+ * request chooses others. A model that has since left the catalog falls back to the defaults.
+ */
+async function continuedSelection(
+  runtime: SixbRuntimeContext,
+  models: LanguageModelCatalog | undefined,
+  input: RequestAgentRunInput
+): Promise<Pick<RequestAgentRunInput, "model" | "reasoning">> {
+  const agents = requireAgentStorage(runtime)
+  const threadId = input.threadId ?? ""
+  if (!(await agents.threads.getById({ projectId: runtime.projectId, id: threadId }))) {
+    throw new AgentRequestError(
+      "thread_not_found",
+      "[Sixb] An Agent continuation needs an existing thread."
+    )
+  }
+  if (input.model !== undefined || input.reasoning !== undefined) return {}
+  const { runs } = await agents.runs.list({
+    projectId: runtime.projectId,
+    threadId,
+    kinds: ["conversation"],
+    order: "desc",
+    limit: 1,
+  })
+  const spec = runs[0]?.kind === "conversation" ? runs[0].spec : undefined
+  if (!spec || !models?.getByRef(spec.model)) return {}
+  return {
+    model: spec.model,
+    ...(spec.reasoning === undefined ? {} : { reasoning: spec.reasoning }),
+  }
+}
+
+/** The words of the user, or the continuation Sixb words for them. */
+function triggerParts(input: RequestAgentRunInput): readonly AgentMessagePart[] {
+  if (input.continue === true) {
+    if (input.text !== undefined || input.attachments?.length || input.context?.length) {
+      throw new AgentRequestError(
+        "invalid_message",
+        "[Sixb] An Agent continuation carries no text, attachments, or context."
+      )
+    }
+    return [{ type: "continuation" }]
+  }
+  if (typeof input.text !== "string" || input.text.trim().length === 0) {
+    throw new AgentRequestError(
+      "invalid_message",
+      "[Sixb] An Agent message needs text, or `continue: true` to continue the previous answer."
+    )
+  }
+  return [{ type: "text", text: input.text }]
+}
+
+function assertAttachments(attachments: readonly FileRef[] | undefined): void {
+  for (const [index, attachment] of (attachments ?? []).entries()) {
+    if (!isValidFileRef(attachment)) {
+      throw new AgentRequestError(
+        "invalid_attachment",
+        `[Sixb] Attachment ${index} is not a valid file reference.`
+      )
+    }
+  }
+}
+
 function assertSandboxExecutionAvailable(thread: AgentThreadRecord): void {
   if (thread.sandboxState && !["new", "ready"].includes(thread.sandboxState.status)) {
     throw new AgentRequestError(
@@ -281,10 +380,14 @@ async function assertAiLimitPreflight(
   }
 }
 
-function resolveConversationRunSpec(input: {
+/**
+ * Freeze the model selection of a turn. The model's default reasoning is resolved here, not by the
+ * worker, so a retry runs with the reasoning the turn was admitted with.
+ */
+async function resolveConversationRunSpec(input: {
   readonly models?: LanguageModelCatalog
-  readonly input: Pick<RequestAgentRunInput, "model" | "reasoning">
-}): ConversationAgentRunSpec {
+  readonly input: Pick<RequestAgentRunInput, "model" | "reasoning" | "timeZone" | "locale">
+}): Promise<ConversationAgentRunSpec> {
   if (!input.models) {
     throw new AgentRequestError(
       "model_not_found",
@@ -300,20 +403,73 @@ function resolveConversationRunSpec(input: {
     )
   }
 
-  const reasoning = input.input.reasoning
-  if (reasoning !== undefined && !isModelReasoning(reasoning)) {
-    throw new AgentRequestError(
-      "invalid_model_selection",
-      `[Sixb] Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
-    )
+  const explicitReasoning = input.input.reasoning
+  if (explicitReasoning !== undefined) {
+    await assertModelSupportsReasoning(model, explicitReasoning)
   }
+  const reasoning = explicitReasoning ?? model.model.defaultReasoning
+  const timeZone = requestedSetting(
+    "timeZone",
+    input.input.timeZone,
+    canonicalTimeZone,
+    "an IANA time zone"
+  )
+  const locale = requestedSetting(
+    "locale",
+    input.input.locale,
+    canonicalLocale,
+    "a BCP 47 language tag"
+  )
 
   return Object.freeze({
     model: Object.freeze({ provider: selected.provider, modelId: selected.modelId }),
     ...(reasoning === undefined ? {} : { reasoning }),
+    ...(timeZone === undefined ? {} : { timeZone }),
+    ...(locale === undefined ? {} : { locale }),
   })
 }
 
+function requestedSetting(
+  field: "timeZone" | "locale",
+  value: string | undefined,
+  canonical: (value: unknown) => string | undefined,
+  expected: string
+): string | undefined {
+  if (value === undefined) return undefined
+  const resolved = canonical(value)
+  if (resolved === undefined) {
+    throw new AgentRequestError(
+      "invalid_locale",
+      `[Sixb] Agent request '${field}' must be ${expected}; received ${JSON.stringify(value)}.`
+    )
+  }
+  return resolved
+}
+
+// Checked against the model's resolved capabilities, as `GET /api/models` reports them (its
+// configured ones when the provider catalog is unavailable). Undeclared capabilities accept any
+// level; the provider then falls back to its own default.
+async function assertModelSupportsReasoning(
+  entry: LanguageModelEntry,
+  reasoning: unknown
+): Promise<void> {
+  if (!isModelReasoning(reasoning)) {
+    throw new AgentRequestError(
+      "invalid_model_selection",
+      `[Sixb] Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
+    )
+  }
+  if (reasoning === "provider-default") return
+  const model = await resolveLanguageModel(entry.model)
+  const issue = modelReasoningSupportIssue(model.definition.capabilities.reasoning, reasoning)
+  if (issue !== undefined) {
+    throw new AgentRequestError(
+      "invalid_model_selection",
+      `[Sixb] Language model '${entry.provider}/${entry.modelId}' cannot use this reasoning: ${issue}.`
+    )
+  }
+}
+
 async function prepareDurableAgentExecution(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,

package/src/agents/skills.ts

@@ -0,0 +1,63 @@
+import type { OntologyDocsCatalog, OntologyDocsInput } from "../ontology/docs"
+import { RuntimeError } from "../runtime/errors"
+
+/** A project file the Agent receives byte-for-byte in its sandbox. */
+export interface AgentProjectFile {
+  /** POSIX path, relative to the directory the file is installed in. */
+  readonly path: string
+  readonly contents: string | Uint8Array
+  /** Permission bits, kept only for executable files. */
+  readonly mode?: number
+}
+
+/** An Agent Skill read from `skills/<name>/SKILL.md` and the files next to it. */
+export interface AgentSkillDefinition {
+  readonly name: string
+  readonly description: string
+  /** Every file of the skill directory, `SKILL.md` included. */
+  readonly files: readonly AgentProjectFile[]
+}
+
+/** Immutable catalog of the Agent Skills registered with a Sixb host. */
+export interface AgentSkillCatalog {
+  list(): readonly AgentSkillDefinition[]
+  getByName(name: string): AgentSkillDefinition | null
+}
+
+/** The project files the Agent reads. createSixb() discovers them; tests may pass them directly. */
+export interface AgentDefinitionsInput {
+  /** Agent Skills, from `skills/`. */
+  readonly skills?: readonly AgentSkillDefinition[]
+  /** The conversational Agent's instructions, from `SIXB.md`. */
+  readonly instructions?: string
+  /** The modules, docs, and scripts of `ontology/`. */
+  readonly ontologyDocs?: OntologyDocsInput
+}
+
+/** The project files the Agent reads, validated with the other definitions. */
+export interface AgentDefinitions {
+  readonly skills: AgentSkillCatalog
+  /** Absent without `SIXB.md`. */
+  readonly instructions?: string
+  /** Where each object type's reference doc lives, with the docs and scripts of `ontology/`. */
+  readonly ontologyDocs: OntologyDocsCatalog
+}
+
+/** Index skills by name. Discovery validates each skill; names must also be unique. */
+export function createAgentSkillCatalog(
+  definitions: readonly AgentSkillDefinition[] | undefined
+): AgentSkillCatalog {
+  const skills = Object.freeze([...(definitions ?? [])])
+  const skillsByName = new Map<string, AgentSkillDefinition>()
+  for (const skill of skills) {
+    if (skillsByName.has(skill.name)) {
+      throw new RuntimeError(`[Sixb] Duplicate Agent Skill name: ${skill.name}`)
+    }
+    skillsByName.set(skill.name, skill)
+  }
+
+  return Object.freeze({
+    list: () => skills,
+    getByName: (name: string) => skillsByName.get(name) ?? null,
+  })
+}

package/src/agents/types.ts

@@ -1,10 +1,13 @@
-import type { BlobBody, FileRef } from "../blob-storage"
+import type { ActionsRuntime } from "../actions/execution"
+import type { BlobBody, FileRef, OpenedFileRef } from "../blob-storage"
 import type { ConnectorRuntime } from "../connectors"
 import type { JsonPrimitive, JsonValue, ReadonlyJsonValue } from "../json"
 import type { Logger } from "../logging"
 import { type LanguageModelRef, MODEL_REASONING_LEVELS, type ModelReasoning } from "../models"
+import type { ModelsRuntime } from "../models/generation-types"
 import type { InferSchema } from "../ontology/inference"
 import type { Schema } from "../ontology/types"
+import type { ObjectReader } from "../runtime/types"
 
 export type {
   AgentContextEntryInput,
@@ -32,9 +35,6 @@ export interface AgentDescriptor {
 
 export type AgentReasoning = ModelReasoning
 
-/** @deprecated Use {@link AgentReasoning}. */
-export type AgentReasoningLevel = AgentReasoning
-
 export const AGENT_REASONING_LEVELS = MODEL_REASONING_LEVELS
 
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
@@ -98,6 +98,19 @@ export interface AgentToolArtifacts {
   put(input: AgentToolArtifactPutInput): Promise<AgentToolArtifact>
 }
 
+/**
+ * The files attached to the run that invoked a tool: the messages of a chat's thread, or the input
+ * files of a workflow AI task. A child Agent has none.
+ */
+export interface AgentToolAttachments {
+  /**
+   * Open an attachment by the `key` the Agent sees in `$SIXB_ATTACHMENTS`. Returns null when its
+   * stored file is gone, and throws an `AgentToolPublicError` for a key that is not one of this
+   * run's attachments.
+   */
+  open(key: string): Promise<OpenedFileRef | null>
+}
+
 export type AgentToolTextContent = {
   readonly type: "text"
   readonly text: string
@@ -120,6 +133,22 @@ export type AgentToolResult = {
   readonly content: readonly AgentToolContent[]
 }
 
+/**
+ * The run's domain SDK as an agent tool sees it. Unlike workflow steps and actions, it acts as the
+ * run's requester: the signed-in user in a chat, that same user in a child Agent, and the step's
+ * groups in a workflow AI task.
+ *
+ * A structural view of the public `Sixb` SDK, like `WorkflowRuntimeFacade`: the handler receives the
+ * run's bound SDK, and this type guides it to what a tool should do. It reads objects and changes
+ * them by requesting actions, which validate and record the change. Authority comes from the run,
+ * not from this view.
+ */
+export interface AgentToolRuntimeFacade extends ObjectReader {
+  readonly actions: ActionsRuntime
+  readonly models: ModelsRuntime
+  readonly connector: ConnectorRuntime
+}
+
 /** The narrow, run-scoped surface passed to an agent tool handler. */
 export interface AgentToolRunContext<
   TInput extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
@@ -128,9 +157,10 @@ export interface AgentToolRunContext<
   readonly toolCallId: string
   readonly signal: AbortSignal
   readonly run: AgentToolRunInfo
-  readonly connector: ConnectorRuntime
+  readonly sixb: AgentToolRuntimeFacade
   readonly logger: Logger
   readonly artifacts: AgentToolArtifacts
+  readonly attachments: AgentToolAttachments
 }
 
 /** Agent tool handlers may return only values safe to persist in agent messages. */

package/src/auth/runtime.ts

@@ -655,6 +655,7 @@ export class AuthRuntime {
     caller: AuthenticatedUserRequestSession,
     input: CreatePersonalAccessTokenInput
   ): Promise<CreateAccessTokenResult> {
+    assertSessionCaller(caller)
     const storage = this.requireAuthStorage()
     // A personal token can only carry groups the caller currently belongs to.
     const groupIds = constrainRequestedGroupIds(input.groupIds, caller.groupIds, {
@@ -815,6 +816,7 @@ export class AuthRuntime {
     caller: AuthenticatedUserRequestSession,
     input: CreateServiceAccountAccessTokenInput
   ): Promise<CreateServiceAccountAccessTokenResult> {
+    assertSessionCaller(caller)
     const storage = this.requireAuthStorage()
     const { serviceAccount, groupIds: serviceAccountGroupIds } =
       await this.requireManageableServiceAccount(storage, caller.groupIds, input.serviceAccountId)
@@ -1564,6 +1566,18 @@ function callerSessionId(caller: AuthenticatedRequestAuthSession): string | unde
   return caller.credentialSource === "session" ? caller.session.id : undefined
 }
 
+// Access tokens are created only by a signed-in person, never by another access token. A token
+// minting one could hand out more groups or a later expiry than it carries, and what it minted
+// would outlive its own revocation.
+function assertSessionCaller(caller: AuthenticatedUserRequestSession): void {
+  if (caller.credentialSource !== "session") {
+    throw new AuthRuntimeError(
+      "authorization_denied",
+      "[Sixb] Access tokens can only be created from a signed-in session, not with another access token."
+    )
+  }
+}
+
 function constrainTokenGroupIds(
   principalGroupIds: readonly string[],
   accessToken: AccessTokenRecord

package/src/auth/types.ts

@@ -190,6 +190,12 @@ export interface OidcStartSignInInput {
 
 export interface OidcStartSignInResult {
   readonly redirectTo: string
+  /**
+   * The `state` sent to the provider. The server keeps it in a cookie until `expiresAt` and
+   * completes the callback only in the browser that holds it.
+   */
+  readonly state: string
+  readonly expiresAt: Date
 }
 
 export interface OidcCallbackInput {

package/src/authorization/resolve.ts

@@ -70,7 +70,7 @@ function expandSelection(
  *
  * Pure set-union over pre-resolved roles: roles match when their grantedTo
  * groups intersect the principal's memberships, and their concrete id sets
- * union into the principal's grant index.
+ * and clearances union into the principal's context.
  */
 export function resolveAuthorizationContext(input: {
   readonly principal: Principal
@@ -81,6 +81,7 @@ export function resolveAuthorizationContext(input: {
   const memberGroupIds = new Set(input.groupIds)
   const roleIds: string[] = []
   const grants = emptyGrantSets()
+  const clearances = new Set<string>()
 
   for (const role of input.roles) {
     if (!role.grantedToGroupIds.some((groupId) => memberGroupIds.has(groupId))) {
@@ -96,6 +97,9 @@ export function resolveAuthorizationContext(input: {
         grants[kind].add(id)
       }
     }
+    for (const markingId of role.clearances ?? []) {
+      clearances.add(markingId)
+    }
   }
 
   return {
@@ -104,5 +108,6 @@ export function resolveAuthorizationContext(input: {
     groupIds: input.groupIds,
     roleIds,
     grants,
+    clearances,
   }
 }

package/src/authorization/types.ts

@@ -42,6 +42,8 @@ export interface ResolvedRole {
   readonly id: string
   readonly grantedToGroupIds: readonly string[]
   readonly grants: GrantIndex
+  /** Marking ids this role clears. Absent means none. */
+  readonly clearances?: ReadonlySet<string>
 }
 
 export interface AuthorizationContext {
@@ -51,4 +53,9 @@ export interface AuthorizationContext {
   /** Roles whose grantedTo groups intersect the principal's memberships. */
   readonly roleIds: readonly string[]
   readonly grants: GrantIndex
+  /**
+   * Marking ids the principal may read, unioned from its roles. Absent means none: a context built
+   * without clearances reads no marked property.
+   */
+  readonly clearances?: ReadonlySet<string>
 }