@sixb/core 0.1.17 → 0.1.18

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))
+}

package/src/security/registry.ts

@@ -1,10 +1,17 @@
 import { type ResolvedRole, resolveRoleGrants } from "../authorization"
 import { APPLICATION_IDS } from "./applications"
-import type { GroupDefinition, MembershipPolicyDefinition, RoleDefinition } from "./types"
+import type {
+  GroupDefinition,
+  MarkingDefinition,
+  MembershipPolicyDefinition,
+  RoleDefinition,
+} from "./types"
 import { validateSecurityDefinitionsAtStartup } from "./validation"
 
 /** Read-only access to validated security definitions and resolved role grants. */
 export interface SecurityDefinitionCatalog {
+  listMarkings(): readonly MarkingDefinition[]
+  getMarkingById(markingId: string): MarkingDefinition | null
   listGroups(): readonly GroupDefinition[]
   getGroupById(groupId: string): GroupDefinition | null
   listRoles(): readonly RoleDefinition[]
@@ -15,6 +22,7 @@ export interface SecurityDefinitionCatalog {
 }
 
 export interface SecurityRegistryOptions {
+  readonly markings?: readonly MarkingDefinition[]
   readonly groups?: readonly GroupDefinition[]
   readonly roles?: readonly RoleDefinition[]
   readonly membershipPolicies?: readonly MembershipPolicyDefinition[]
@@ -32,6 +40,7 @@ export interface SecurityRegistryOptions {
 }
 
 export class SecurityRegistry implements SecurityDefinitionCatalog {
+  private readonly markingsById: ReadonlyMap<string, MarkingDefinition>
   private readonly groupsById: ReadonlyMap<string, GroupDefinition>
   private readonly rolesById: ReadonlyMap<string, RoleDefinition>
   private readonly membershipPoliciesById: ReadonlyMap<string, MembershipPolicyDefinition>
@@ -39,6 +48,7 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
 
   constructor(input: SecurityRegistryOptions) {
     const definitions = validateSecurityDefinitionsAtStartup({
+      markings: input.markings ?? [],
       groups: input.groups ?? [],
       roles: input.roles ?? [],
       membershipPolicies: input.membershipPolicies ?? [],
@@ -71,6 +81,7 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       getSubTypes: input.getSubTypes ?? (() => []),
     }
 
+    this.markingsById = definitions.markingsById
     this.groupsById = definitions.groupsById
     this.rolesById = definitions.rolesById
     this.membershipPoliciesById = definitions.membershipPoliciesById
@@ -78,9 +89,18 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       id: role.id,
       grantedToGroupIds: role.grantedToGroupIds,
       grants: resolveRoleGrants(role, universe),
+      clearances: new Set(role.clearances ?? []),
     }))
   }
 
+  listMarkings(): readonly MarkingDefinition[] {
+    return [...this.markingsById.values()]
+  }
+
+  getMarkingById(markingId: string): MarkingDefinition | null {
+    return this.markingsById.get(markingId) ?? null
+  }
+
   listGroups(): readonly GroupDefinition[] {
     return [...this.groupsById.values()]
   }

package/src/security/types.ts

@@ -7,6 +7,28 @@ export interface GroupDefinition<TId extends string = string> {
   readonly description?: string
 }
 
+/**
+ * A classification carried by sensitive properties and dataset columns.
+ *
+ * A principal reads a marked value only when one of its roles lists the marking in `clearances`.
+ * No grant bypasses a marking.
+ */
+export interface MarkingDefinition<TId extends string = string> {
+  readonly kind: "marking"
+  readonly id: TId
+  readonly label?: string
+  readonly description?: string
+}
+
+/** Why a value was omitted from a read. */
+export type RedactionReason = "missing_clearance"
+
+/**
+ * Values omitted from a read, keyed by property id or column name. A redacted value is absent,
+ * never `null`.
+ */
+export type Redactions = Readonly<Record<string, { readonly reason: RedactionReason }>>
+
 /**
  * A group named either by its definition or by its id.
  *
@@ -149,6 +171,8 @@ export interface RoleDefinition<TId extends string = string> {
   readonly description?: string
   readonly grantedToGroupIds: readonly string[]
   readonly grants: readonly GrantDefinition[]
+  /** Ids of the markings this role's members may read. Absent means none. */
+  readonly clearances?: readonly string[]
 }
 
 export type MembershipOperation = "invite" | "assignGroups" | "suspend"
@@ -162,6 +186,8 @@ export interface MembershipPolicyDefinition<TId extends string = string> {
 }
 
 export interface RegisteredSecurityDefinitions {
+  readonly markings: readonly MarkingDefinition[]
+  readonly markingsById: ReadonlyMap<string, MarkingDefinition>
   readonly groups: readonly GroupDefinition[]
   readonly groupsById: ReadonlyMap<string, GroupDefinition>
   readonly roles: readonly RoleDefinition[]

package/src/security/validation.ts

@@ -5,6 +5,7 @@ import type {
   GrantCapability,
   GrantDefinition,
   GroupDefinition,
+  MarkingDefinition,
   MembershipPolicyDefinition,
   RegisteredSecurityDefinitions,
   RoleDefinition,
@@ -132,6 +133,32 @@ function assertNoDuplicateOperations(
   }
 }
 
+export function assertMarkingDefinition(
+  value: unknown,
+  createError: CreateSecurityError = (message) => new SecurityValidationError(message)
+): asserts value is MarkingDefinition {
+  if (!isRecord(value)) {
+    throw createError("[Sixb] Marking definition must be an object.")
+  }
+
+  if (value.kind !== "marking") {
+    throw createError("[Sixb] Marking definition kind must be 'marking'.")
+  }
+
+  assertNonEmptyString(value.id, "Marking id", createError)
+  assertOptionalString(value.label, `Marking '${value.id}' label`, createError)
+  assertOptionalString(value.description, `Marking '${value.id}' description`, createError)
+}
+
+export function isMarkingDefinition(value: unknown): value is MarkingDefinition {
+  try {
+    assertMarkingDefinition(value, (message) => new Error(message))
+    return true
+  } catch {
+    return false
+  }
+}
+
 export function assertGroupDefinition(
   value: unknown,
   createError: CreateSecurityError = (message) => new SecurityValidationError(message)
@@ -285,6 +312,10 @@ export function assertRoleDefinition(
   for (const grant of value.grants) {
     assertGrantDefinition(grant, `Role '${value.id}' grants`, createError)
   }
+
+  if (value.clearances !== undefined) {
+    assertStringArray(value.clearances, `Role '${value.id}' clearances`, createError)
+  }
 }
 
 export function isRoleDefinition(value: unknown): value is RoleDefinition {
@@ -297,6 +328,7 @@ export function isRoleDefinition(value: unknown): value is RoleDefinition {
 }
 
 export function validateSecurityDefinitionsAtStartup(input: {
+  readonly markings?: readonly MarkingDefinition[]
   readonly groups: readonly GroupDefinition[]
   readonly membershipPolicies: readonly MembershipPolicyDefinition[]
   readonly roles?: readonly RoleDefinition[]
@@ -325,10 +357,21 @@ export function validateSecurityDefinitionsAtStartup(input: {
   /** Registered Share ids — when provided, share grants must reference them. */
   readonly shareIds?: ReadonlySet<string>
 }): RegisteredSecurityDefinitions {
+  const markingsById = new Map<string, MarkingDefinition>()
   const groupsById = new Map<string, GroupDefinition>()
   const rolesById = new Map<string, RoleDefinition>()
   const membershipPoliciesById = new Map<string, MembershipPolicyDefinition>()
 
+  for (const marking of input.markings ?? []) {
+    assertMarkingDefinition(marking)
+
+    if (markingsById.has(marking.id)) {
+      throw new SecurityValidationError(`[Sixb] Duplicate marking id: ${marking.id}`)
+    }
+
+    markingsById.set(marking.id, marking)
+  }
+
   for (const group of input.groups) {
     assertGroupDefinition(group)
 
@@ -352,11 +395,23 @@ export function validateSecurityDefinitionsAtStartup(input: {
       )
     }
 
-    if (role.grants.length === 0) {
-      throw new SecurityValidationError(`[Sixb] Role '${role.id}' must declare at least one grant.`)
+    const clearances = role.clearances ?? []
+    if (role.grants.length === 0 && clearances.length === 0) {
+      throw new SecurityValidationError(
+        `[Sixb] Role '${role.id}' must declare at least one grant or clearance.`
+      )
     }
 
     assertNoDuplicateIds(role.grantedToGroupIds, `Role '${role.id}' grantedTo`)
+    assertNoDuplicateIds(clearances, `Role '${role.id}' clearances`)
+
+    for (const markingId of clearances) {
+      if (!markingsById.has(markingId)) {
+        throw new SecurityValidationError(
+          `[Sixb] Role '${role.id}' clearances reference unknown marking '${markingId}'. Add it to 'security/markings/' or pass it to createSixb({ markings }).`
+        )
+      }
+    }
 
     for (const groupId of role.grantedToGroupIds) {
       if (!groupsById.has(groupId)) {
@@ -416,6 +471,8 @@ export function validateSecurityDefinitionsAtStartup(input: {
   }
 
   return {
+    markings: [...markingsById.values()],
+    markingsById,
     groups: [...groupsById.values()],
     groupsById,
     roles: [...rolesById.values()],

package/src/storage/agents/provider.ts

@@ -150,6 +150,17 @@ export function assertConversationAgentRunSpec(
       `[${prefix}] Conversational Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
     )
   }
+  for (const [name, value] of [
+    ["timeZone", spec.timeZone],
+    ["locale", spec.locale],
+  ] as const) {
+    if (value !== undefined && (typeof value !== "string" || value.trim().length === 0)) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Conversational Agent run '${name}' must be a non-empty string.`
+      )
+    }
+  }
 }
 
 function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {

package/src/storage/agents/types.ts

@@ -1,5 +1,5 @@
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message"
-import type { AgentReasoningLevel } from "../../agents/types"
+import type { AgentReasoning } from "../../agents/types"
 import type { Principal } from "../../auth"
 import type { FileRef } from "../../blob-storage"
 import type { SixbErrorCode, SixbFailure } from "../../errors/types"
@@ -123,8 +123,9 @@ export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number]
 
 /**
  * Why a run ended — Sixb's provider-independent vocabulary. It includes model-loop reasons plus
- * platform-level endings such as `timeout`, so reads remain typed and exhaustive. `other` and
- * `unknown` preserve terminal state when a provider adds a new reason.
+ * platform-level endings such as `timeout`, or `interrupted` for a turn whose worker died before
+ * finishing it, so reads remain typed and exhaustive. `other` and `unknown` preserve terminal state
+ * when a provider adds a new reason.
  */
 export const AGENT_RUN_FINISH_REASONS = [
   "stop",
@@ -132,6 +133,7 @@ export const AGENT_RUN_FINISH_REASONS = [
   "content-filter",
   "tool-calls",
   "timeout",
+  "interrupted",
   "error",
   "other",
   "unknown",
@@ -162,6 +164,7 @@ export const AGENT_RUN_DIAGNOSTIC_CODES = [
   "output_collection_failed",
   "output_file_changed",
   "output_storage_failed",
+  "step_limit_reached",
 ] as const
 
 /**
@@ -178,7 +181,8 @@ export type AgentRunDiagnosticSeverity = "warning" | "error"
 export interface AgentRunDiagnostic {
   readonly code: AgentRunDiagnosticCode
   readonly severity: AgentRunDiagnosticSeverity
-  readonly scope: "output"
+  /** `output` for published files, `run` for the turn as a whole. */
+  readonly scope: "output" | "run"
   /** Relative path inside the run's published output directory, when one file is involved. */
   readonly path?: string
   /** Sanitized, stable copy suitable for display to an end user. */
@@ -224,16 +228,20 @@ export interface ConversationAgentRunRecord extends AgentRunRecordBase {
   readonly spec?: ConversationAgentRunSpec
 }
 
-/** Immutable, serialisable model selection for one conversational turn. */
+/** Immutable, serialisable model selection and requester settings for one conversational turn. */
 export interface ConversationAgentRunSpec {
   readonly model: LanguageModelRef
-  readonly reasoning?: AgentReasoningLevel
+  readonly reasoning?: AgentReasoning
+  /** Canonical IANA time zone of the requester. Absent uses the project time zone. */
+  readonly timeZone?: string
+  /** Canonical BCP 47 language of the requester. Absent uses the project locale. */
+  readonly locale?: string
 }
 
 /** Immutable, serialisable child configuration captured before dispatch. */
 export interface SubagentRunSpec {
   readonly model: LanguageModelRef
-  readonly reasoning?: AgentReasoningLevel
+  readonly reasoning?: AgentReasoning
   /** Focused task supplied by the parent Agent. */
   readonly task: string
   /** Project tools available when the child was admitted. Runtime tools are injected separately. */

package/src/storage/index.ts

@@ -21,6 +21,7 @@ export type {
 } from "../materialization/model"
 export type { ModelProviderIds } from "../models/events"
 export type { ObjectRef } from "../ontology"
+export type { RedactionReason, Redactions } from "../security/types"
 export type {
   ShareAccessPlan,
   ShareScopedActionGrant,