@sixb/core 0.1.17 → 0.1.18

package/src/ontology/validation/index.ts

@@ -24,6 +24,7 @@ export {
 } from "./properties"
 export { validateQueryMetadata } from "./query"
 export {
+  assertValidFileRefs,
   isRecord,
   resolveValueTypeRef,
   resolveValueTypeSchema,

package/src/ontology/validation/schema.ts

@@ -1,4 +1,4 @@
-import { isFileRef } from "../../blob-storage/validation"
+import { isFileRef, isValidFileRef } from "../../blob-storage/validation"
 import { withFailureMessage } from "../../errors/failure-message"
 import type { ObjectFieldSchema, Schema, ValueType, ValueTypeRefSchema } from ".."
 import { isDecimalString } from "../decimal"
@@ -201,6 +201,31 @@ export function validateSchemaValue(
   }
 }
 
+/**
+ * Reject a value from a caller that holds a file reference whose `mediaType` is not exactly one
+ * media type, anywhere inside it. Call it where caller input is accepted, after
+ * `validateSchemaValue`; that validator also re-checks stored state, which must keep loading
+ * references written before the rule.
+ */
+export function assertValidFileRefs(value: unknown, path: string): void {
+  if (isFileRef(value)) {
+    if (!isValidFileRef(value)) {
+      throw withFailureMessage(
+        new OntologyValidationError(
+          `[Sixb] Property ${path}.mediaType must be one media type, such as "application/pdf"`
+        ),
+        `Property ${path}.mediaType must be one media type, such as "application/pdf".`
+      )
+    }
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) assertValidFileRefs(item, `${path}[${index}]`)
+  } else if (isRecord(value)) {
+    for (const [key, item] of Object.entries(value)) assertValidFileRefs(item, `${path}.${key}`)
+  }
+}
+
 function validateFieldValue(
   field: ObjectFieldSchema,
   value: unknown,

package/src/runtime/create.ts

@@ -4,7 +4,12 @@ import type { AgentToolDefinition } from "../agents"
 import { assertNoAgentDefinitions } from "../agents/retired-config"
 import type { SixbAuthConfig } from "../auth"
 import type { BlobStorage } from "../blob-storage"
-import { discoverOntologySources, discoverProjectDefinitions } from "../bootstrap"
+import {
+  discoverAgentSkills,
+  discoverOntologyFiles,
+  discoverProjectInstructions,
+} from "../bootstrap/agent-context"
+import { discoverOntologySources, discoverProjectDefinitions } from "../bootstrap/discovery"
 import type { Broker } from "../broker"
 import type { ConnectorConnectionOptions, ConnectorDefinition } from "../connectors/types"
 import type { DatasetDefinition } from "../datasets"
@@ -20,7 +25,12 @@ import type { Queues } from "../queues"
 import type { RuleDefinition } from "../rules"
 import type { SandboxFactory } from "../sandboxes"
 import type { ScheduleDefinition } from "../schedules"
-import type { GroupDefinition, MembershipPolicyDefinition, RoleDefinition } from "../security"
+import type {
+  GroupDefinition,
+  MarkingDefinition,
+  MembershipPolicyDefinition,
+  RoleDefinition,
+} from "../security"
 import type { ParamsConfig } from "../shared/params/types"
 import type { ShareDefinition } from "../shares"
 import type { Storage } from "../storage"
@@ -32,6 +42,13 @@ import type { OntologySource } from "./types"
 
 export interface CreateSixbOptions<in out TParams extends ParamsConfig = ParamsConfig> {
   id?: string
+  /** BCP 47 language of the project, such as `"fr-FR"`. Defaults to `"en"`. */
+  locale?: string
+  /**
+   * IANA time zone of the project, such as `"Europe/Paris"`. Defaults to `"UTC"`. Cron schedules
+   * without their own time zone and agent runs use it.
+   */
+  timeZone?: string
   broker: Broker
   storage: Storage
   lakeStorage: LakeStorage
@@ -63,6 +80,7 @@ export interface CreateSixbOptions<in out TParams extends ParamsConfig = ParamsC
   projections?: readonly ProjectionDefinition[]
   rules?: readonly RuleDefinition[]
   workflows?: readonly WorkflowDefinition[]
+  markings?: readonly MarkingDefinition[]
   groups?: readonly GroupDefinition[]
   roles?: readonly RoleDefinition[]
   membershipPolicies?: readonly MembershipPolicyDefinition[]
@@ -78,7 +96,8 @@ export interface CreateSixbOptions<in out TParams extends ParamsConfig = ParamsC
  * The host auto-discovers exported definitions from `ontology/`, `actions/`, `datasets/`,
  * `connectors/`, `syncs/`, `schedules/`, `pipelines/`, `projections/`,
  * `rules/`, `workflows/`, `shares/`, and `security/{groups,roles,policies}/`
- * relative to `projectRoot`.
+ * relative to `projectRoot`, along with the Agent's `skills/`, `SIXB.md`, and the docs and scripts
+ * under `ontology/`.
  */
 export async function createSixb<const TParams extends ParamsConfig = ParamsConfig>(
   options: CreateSixbOptions<TParams>
@@ -87,7 +106,7 @@ export async function createSixb<const TParams extends ParamsConfig = ParamsConf
   const projectRoot = resolve(options.projectRoot ?? process.cwd())
 
   const discoveredOntology = await discoverOntologySources(projectRoot)
-  const allSources = [...(options.ontologies ?? []), ...discoveredOntology]
+  const allSources = [...(options.ontologies ?? []), ...discoveredOntology.sources]
 
   if (allSources.length === 0) {
     throw new RuntimeError(
@@ -96,12 +115,17 @@ export async function createSixb<const TParams extends ParamsConfig = ParamsConf
   }
 
   const definitions = await discoverProjectDefinitions(projectRoot)
+  const skills = await discoverAgentSkills(projectRoot)
+  const instructions = await discoverProjectInstructions(projectRoot)
+  const ontologyFiles = await discoverOntologyFiles(projectRoot)
 
   // Explicit definitions come first so local setup can override ordering while duplicate ids are
   // still rejected by the SixbHost constructor. Every family merges — `actions` and `projections`
   // used to *replace* discovery instead, silently and undocumented.
   return new SixbHost<TParams>({
     id: options.id,
+    locale: options.locale,
+    timeZone: options.timeZone,
     ontology: allSources,
     broker: options.broker,
     storage: options.storage,
@@ -124,11 +148,17 @@ export async function createSixb<const TParams extends ParamsConfig = ParamsConf
     projections: [...(options.projections ?? []), ...definitions.projections],
     rules: [...(options.rules ?? []), ...definitions.rules],
     workflows: [...(options.workflows ?? []), ...definitions.workflows],
+    markings: [...(options.markings ?? []), ...definitions.markings],
     groups: [...(options.groups ?? []), ...definitions.groups],
     roles: [...(options.roles ?? []), ...definitions.roles],
     membershipPolicies: [...(options.membershipPolicies ?? []), ...definitions.membershipPolicies],
     models: options.models,
     tools: options.tools,
+    agent: {
+      skills,
+      ...(instructions === undefined ? {} : { instructions }),
+      ontologyDocs: { modules: discoveredOntology.modules, ...ontologyFiles },
+    },
     shares: [...(options.shares ?? []), ...definitions.shares],
     auth: options.auth,
   })

package/src/runtime/definitions.ts

@@ -1,5 +1,5 @@
 import type { ActionDefinitionCatalog } from "../actions"
-import type { AgentToolCatalog } from "../agents"
+import type { AgentDefinitions, AgentToolCatalog } from "../agents"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets"
 import type { ModelCatalog } from "../models"
@@ -24,6 +24,8 @@ export interface SixbDefinitions {
   readonly ontology: OntologyDefinitionCatalog
   readonly actions: ActionDefinitionCatalog
   readonly tools: AgentToolCatalog
+  /** The project files the Agent reads: `skills/`, `SIXB.md`, and the docs of `ontology/`. */
+  readonly agent: AgentDefinitions
   readonly connectors: DefinitionCatalog<ConnectorDefinition>
   readonly datasets: DefinitionCatalog<DatasetDefinition>
   /** Absent until a project configures `models` in createSixb(). */

package/src/runtime/host.ts

@@ -7,7 +7,7 @@
 
 import { resolve } from "node:path"
 import type { ActionDefinition } from "../actions/types"
-import type { AgentToolDefinition } from "../agents"
+import type { AgentDefinitionsInput, AgentToolDefinition } from "../agents"
 import {
   AuthRuntime,
   AuthRuntimeError,
@@ -74,6 +74,7 @@ import { type SchedulerController, SchedulerRuntime } from "../scheduler"
 import type { ScheduleDefinition } from "../schedules"
 import type {
   GroupDefinition,
+  MarkingDefinition,
   MembershipPolicyDefinition,
   RoleDefinition,
   SecurityDefinitionCatalog,
@@ -86,6 +87,13 @@ import type { RegisteredWebhook } from "../webhooks"
 import { WebhookRegistry, WebhookValidationError } from "../webhooks"
 import type { WorkflowDefinition } from "../workflows"
 import type { SixbDefinitions } from "./definitions"
+import { RuntimeError } from "./errors"
+import {
+  canonicalLocale,
+  canonicalTimeZone,
+  DEFAULT_PROJECT_LOCALE,
+  DEFAULT_PROJECT_TIME_ZONE,
+} from "./locale"
 import {
   createOntologyMutationRuntime,
   registerOntologyMutationRuntime,
@@ -98,6 +106,10 @@ import type { OntologySource, SixbHostContext, SixbRuntimeContext } from "./type
 
 export interface SixbHostOptions<in out TParams extends ParamsConfig = ParamsConfig> {
   id?: string
+  /** BCP 47 language of the project. Defaults to `"en"`. */
+  locale?: string
+  /** IANA time zone of the project. Defaults to `"UTC"`. */
+  timeZone?: string
   ontology: readonly OntologySource[]
   broker: Broker
   storage: Storage
@@ -129,6 +141,9 @@ export interface SixbHostOptions<in out TParams extends ParamsConfig = ParamsCon
   models?: ModelCatalogInput
   /** Project tools available to Agent runtimes. */
   tools?: readonly AgentToolDefinition[]
+  /** The project files the Agent reads. createSixb() discovers them. */
+  agent?: AgentDefinitionsInput
+  markings?: readonly MarkingDefinition[]
   groups?: readonly GroupDefinition[]
   roles?: readonly RoleDefinition[]
   membershipPolicies?: readonly MembershipPolicyDefinition[]
@@ -141,6 +156,10 @@ export interface SixbHostOptions<in out TParams extends ParamsConfig = ParamsCon
 // return `SixbHost` that returns `new SixbHost(options)`.
 export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
   readonly projectId: string
+  /** Canonical BCP 47 language of the project. */
+  readonly locale: string
+  /** Canonical IANA time zone of the project. */
+  readonly timeZone: string
   private readonly webhookRegistry: WebhookRegistry
   private readonly hostContext: SixbHostContext
   private readonly committedFacts: OntologyOutboxDispatcher
@@ -167,6 +186,8 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
   constructor(options: SixbHostOptions<TParams>) {
     const errorReporter = attachSixbErrorReporter(this, options.onError)
     this.projectId = options.id ?? "default"
+    this.locale = resolveProjectLocale(options.locale)
+    this.timeZone = resolveProjectTimeZone(options.timeZone)
     this.broker = options.broker
     this.eventService = createDomainEventService({
       projectId: this.projectId,
@@ -280,6 +301,7 @@ export class SixbHost<in out TParams extends ParamsConfig = ParamsConfig> {
     this.scheduler = new SchedulerRuntime({
       schedules: definitions.schedules.list(),
       events: this.eventService,
+      timeZone: this.timeZone,
     })
   }
 
@@ -410,6 +432,28 @@ export type SixbHostView = Omit<SixbHost, "withScope"> & {
   withScope(scope: ExecutionScope): object
 }
 
+function resolveProjectLocale(locale: unknown): string {
+  if (locale === undefined) return DEFAULT_PROJECT_LOCALE
+  const canonical = canonicalLocale(locale)
+  if (canonical === undefined) {
+    throw new RuntimeError(
+      `[Sixb] 'locale' must be a BCP 47 language tag such as "fr-FR"; received ${JSON.stringify(locale)}.`
+    )
+  }
+  return canonical
+}
+
+function resolveProjectTimeZone(timeZone: unknown): string {
+  if (timeZone === undefined) return DEFAULT_PROJECT_TIME_ZONE
+  const canonical = canonicalTimeZone(timeZone)
+  if (canonical === undefined) {
+    throw new RuntimeError(
+      `[Sixb] 'timeZone' must be an IANA time zone such as "Europe/Paris"; received ${JSON.stringify(timeZone)}.`
+    )
+  }
+  return canonical
+}
+
 function validateAuthStrategySecurityReferences(
   strategy: ReturnType<AuthRuntime["getStrategy"]>,
   security: SecurityDefinitionCatalog

package/src/runtime/index.ts

@@ -30,12 +30,15 @@ export { SixbHost } from "./host"
 export type { Sixb } from "./sixb"
 export type {
   BatchItemResult,
+  FileListPropertyToken,
+  FilePropertyToken,
   ListResult,
   ListResultWithoutTotal,
   ObjectByIdHandle,
   ObjectExpandBuilder,
   ObjectExpandOptions,
   ObjectExpansionSort,
+  ObjectFileHandle,
   ObjectQueryBuilder,
   ObjectQueryFacetBucket,
   ObjectQueryFacetInput,

package/src/runtime/locale.ts

@@ -0,0 +1,26 @@
+/** Language assumed when a project sets none. */
+export const DEFAULT_PROJECT_LOCALE = "en"
+
+/** Time zone assumed when a project sets none; cron schedules have always used it. */
+export const DEFAULT_PROJECT_TIME_ZONE = "UTC"
+
+/** The canonical form of a BCP 47 language tag (`fr-fr` → `fr-FR`), or `undefined` if invalid. */
+export function canonicalLocale(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined
+  try {
+    const [locale] = Intl.getCanonicalLocales(value)
+    return locale
+  } catch {
+    return undefined
+  }
+}
+
+/** The canonical IANA name of a time zone (`europe/paris` → `Europe/Paris`), or `undefined`. */
+export function canonicalTimeZone(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.trim() !== value || value === "") return undefined
+  try {
+    return new Intl.DateTimeFormat("en-US", { timeZone: value }).resolvedOptions().timeZone
+  } catch {
+    return undefined
+  }
+}

package/src/runtime/resolve-definitions.ts

@@ -1,7 +1,8 @@
 import { ActionRegistry } from "../actions"
 import type { ActionDefinition } from "../actions/types"
-import type { AgentToolDefinition } from "../agents"
+import type { AgentDefinitionsInput, AgentToolDefinition } from "../agents"
 import { assertNoAgentDefinitions } from "../agents/retired-config"
+import { createAgentSkillCatalog } from "../agents/skills"
 import { createAgentToolCatalog } from "../agents/tool-catalog"
 import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets/types"
@@ -9,6 +10,7 @@ import { assertDatasetDefinition } from "../datasets/validation"
 import { createModelCatalog, type ModelCatalogInput } from "../models"
 import { sameEmbeddingModel } from "../models/embedding-model"
 import { OntologyRegistry } from "../ontology"
+import { createOntologyDocsCatalog } from "../ontology/docs"
 import type { PipelineDefinition } from "../pipelines/types"
 import { ProjectionRegistry } from "../projections"
 import type { ProjectionDefinition } from "../projections/types"
@@ -16,10 +18,12 @@ import { type RuleDefinition, validateRulesAtStartup } from "../rules"
 import { type ScheduleDefinition, validateSchedulesAtStartup } from "../schedules"
 import {
   type GroupDefinition,
+  type MarkingDefinition,
   type MembershipPolicyDefinition,
   type RoleDefinition,
   SecurityRegistry,
 } from "../security"
+import { validateMarkingsAtStartup } from "../security/markings"
 import { type ShareDefinition, validateSharesAtStartup } from "../shares"
 import type { SyncDefinition } from "../syncs"
 import {
@@ -44,8 +48,10 @@ interface DefinitionOptions {
   readonly rules?: readonly RuleDefinition[]
   readonly workflows?: readonly WorkflowDefinition[]
   readonly tools?: readonly AgentToolDefinition[]
+  readonly agent?: AgentDefinitionsInput
   readonly models?: ModelCatalogInput
   readonly shares?: readonly ShareDefinition[]
+  readonly markings?: readonly MarkingDefinition[]
   readonly groups?: readonly GroupDefinition[]
   readonly roles?: readonly RoleDefinition[]
   readonly membershipPolicies?: readonly MembershipPolicyDefinition[]
@@ -89,6 +95,11 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
     }
   }
   const tools = createAgentToolCatalog(options.tools)
+  const skills = createAgentSkillCatalog(options.agent?.skills)
+  const ontologyDocs = createOntologyDocsCatalog({
+    objectTypes: ontology.listObjectTypes(),
+    ...(options.agent?.ontologyDocs === undefined ? {} : { docs: options.agent.ontologyDocs }),
+  })
   const connectorsById = indexUniqueDefinitions("connector", options.connectors ?? [])
 
   // Datasets resolve first because syncs, pipelines, projections, and security depend on them.
@@ -152,10 +163,12 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
     registeredActionIds,
     ...(models === undefined ? {} : { models }),
     tools,
+    skills,
   })
   const workflowsById = indexUniqueDefinitions("workflow", workflows)
 
   const security = new SecurityRegistry({
+    markings: options.markings ?? [],
     groups: options.groups ?? [],
     roles: options.roles ?? [],
     membershipPolicies: options.membershipPolicies ?? [],
@@ -181,11 +194,25 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
     syncs,
     telemetryProjections: projectionRegistry.listTelemetry(),
   })
+  validateMarkingsAtStartup({
+    markingIds: new Set(security.listMarkings().map((marking) => marking.id)),
+    ontology,
+    datasetsById,
+    pipelines,
+    projections: projectionRegistry,
+  })
 
   return Object.freeze({
     ontology,
     actions: actionRegistry,
     tools,
+    agent: Object.freeze({
+      skills,
+      ...(options.agent?.instructions === undefined
+        ? {}
+        : { instructions: options.agent.instructions }),
+      ontologyDocs,
+    }),
     connectors: createDefinitionCatalog(connectorsById),
     datasets: createDefinitionCatalog(datasetsById),
     ...(models === undefined ? {} : { models }),

package/src/runtime/sixb.ts

@@ -110,7 +110,7 @@ function createExecutionFacades<TParams extends Record<string, unknown>>(
   dependencies: SixbDependencies
 ): Omit<Sixb<TParams>, "execution"> {
   return {
-    objects: createObjectsRuntime(runtime, execution),
+    objects: createObjectsRuntime(runtime, execution, dependencies.blobStorage),
     actions: createActionsRuntime(runtime, execution),
     datasets: createDatasetsRuntime(
       runtime,

package/src/runtime/types.ts

@@ -12,6 +12,7 @@ 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"
@@ -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 ──────────────────────────────────
 
 /**
@@ -100,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.
@@ -109,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
 }
@@ -313,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> =
@@ -773,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 } : {}),
   }
 }