@sixb/core 0.1.20 → 0.1.21

package/src/security/pipeline-markings.ts

@@ -0,0 +1,175 @@
+import type { DatasetDefinition } from "../datasets/types"
+import type {
+  LakeStorageWithSql,
+  SqlTransformAnalysis,
+  SqlTransformColumnRef,
+} from "../lake-storage/sql-transforms"
+import type { DatasetColumnLineage, DatasetColumnRef, LakeStorage } from "../lake-storage/types"
+import { PipelineError } from "../pipelines/errors"
+import { stepInputColumns, stepReadColumns } from "../pipelines/lineage"
+import type { PipelineStepDefinition } from "../pipelines/types"
+import type { SixbDefinitions } from "../runtime/definitions"
+import { SecurityValidationError } from "./errors"
+import {
+  type DatasetMarkings,
+  MarkingPropagation,
+  type RegisteredStep,
+  registeredSteps,
+  runStepLineages,
+} from "./marking-propagation"
+import { describeOrigins, validateProjectionMarkings } from "./projection-markings"
+
+/**
+ * Derive the markings SQL steps give their outputs and check every projection against them.
+ *
+ * Startup cannot see through SQL, so this preflight completes it before a host serves traffic. It
+ * is a diagnostic: each version records the lineage of the SQL that actually ran, and reads and
+ * projections enforce markings from that record whether or not this ran.
+ *
+ * Only steps that read a marked column are analyzed, each step once. Analyzing a step can mark
+ * the inputs of others, so steps are analyzed in waves, a few at a time within a wave. A step whose
+ * SQL cannot be analyzed, or a lake provider that cannot analyze SQL, is reported with the step
+ * and a marked column it reads.
+ */
+export async function checkPipelineMarkings(input: {
+  readonly definitions: Pick<SixbDefinitions, "ontology" | "datasets" | "pipelines" | "projections">
+  readonly lakeStorage: LakeStorage | LakeStorageWithSql
+}): Promise<void> {
+  const { definitions, lakeStorage } = input
+  const datasetsById = new Map(definitions.datasets.list().map((dataset) => [dataset.id, dataset]))
+  const steps = registeredSteps(definitions.pipelines.list())
+  const runLineageOf = runStepLineages(datasetsById)
+  const analyzed = new Map<PipelineStepDefinition, DatasetColumnLineage>()
+  const lineageOf = (entry: RegisteredStep) =>
+    runLineageOf(entry) ?? analyzed.get(entry.step) ?? null
+
+  const markings = new MarkingPropagation(datasetsById, steps).derive(lineageOf)
+
+  for (;;) {
+    const wave = new Map<PipelineStepDefinition, RegisteredStep>()
+    for (const entry of steps) {
+      if (entry.step.executor.kind !== "sql" || analyzed.has(entry.step)) continue
+      if (stepReadColumns(entry.step).some((ref) => markings.of(ref).size > 0)) {
+        if (!wave.has(entry.step)) wave.set(entry.step, entry)
+      }
+    }
+
+    if (wave.size === 0) break
+
+    await forEachConcurrently([...wave], ANALYSIS_CONCURRENCY, async ([step, entry]) => {
+      analyzed.set(step, await analyzeSqlStep(entry, markings, datasetsById, lakeStorage))
+    })
+    markings.derive(lineageOf)
+  }
+
+  validateProjectionMarkings(definitions.projections, definitions.ontology, markings)
+}
+
+/** Analyses run at once. A provider may open a database per analysis, so a wave is not unbounded. */
+const ANALYSIS_CONCURRENCY = 8
+
+/** Run `task` on each item, `limit` at a time. Stops starting new tasks once one fails. */
+async function forEachConcurrently<TItem>(
+  items: readonly TItem[],
+  limit: number,
+  task: (item: TItem) => Promise<void>
+): Promise<void> {
+  const pending = items.values()
+  let failed = false
+
+  const worker = async () => {
+    for (const item of pending) {
+      if (failed) return
+
+      try {
+        await task(item)
+      } catch (error) {
+        failed = true
+        throw error
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker))
+}
+
+async function analyzeSqlStep(
+  entry: RegisteredStep,
+  markings: DatasetMarkings,
+  datasetsById: ReadonlyMap<string, DatasetDefinition>,
+  lakeStorage: LakeStorage | LakeStorageWithSql
+): Promise<DatasetColumnLineage> {
+  const { step } = entry
+  const subject = `[Sixb] Pipeline '${entry.pipelineId}' step '${step.id}'`
+
+  if (step.executor.kind !== "sql") throw new PipelineError(`${subject} is not a SQL step.`)
+
+  const sql = "sql" in lakeStorage ? lakeStorage.sql : undefined
+  if (!sql?.analyze) {
+    throw new SecurityValidationError(
+      `${subject} reads ${describeMarkedRead(step, markings)}, but the lake provider cannot analyze SQL to derive the markings of its output. Use a lake provider that analyzes SQL, or pick only unmarked columns.`
+    )
+  }
+
+  const inputs = Object.entries(step.inputs)
+  let analysis: SqlTransformAnalysis
+  try {
+    analysis = await sql.analyze({
+      sql: step.executor.sql,
+      sources: Object.fromEntries(
+        inputs.map(([name, dataset]) => [
+          name,
+          {
+            dataset: registeredDataset(datasetsById, dataset.id, subject),
+            columns: stepInputColumns(dataset),
+          },
+        ])
+      ),
+    })
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new PipelineError(`${subject} could not be analyzed: ${reason}`, { cause: error })
+  }
+
+  if (!analysis.supported) {
+    throw new SecurityValidationError(
+      `${subject} reads ${describeMarkedRead(step, markings)}, but its SQL cannot be analyzed: ${analysis.reason}. Rewrite that part of the query, or pick only unmarked columns.`
+    )
+  }
+
+  const datasetIdBySource = new Map(inputs.map(([name, dataset]) => [name, dataset.id]))
+  const toRef = (ref: SqlTransformColumnRef): DatasetColumnRef => {
+    const datasetId = datasetIdBySource.get(ref.source)
+    if (datasetId === undefined) {
+      throw new PipelineError(`${subject} analysis references unknown source '${ref.source}'.`)
+    }
+
+    return { datasetId, column: ref.column }
+  }
+
+  return {
+    rows: analysis.lineage.rows.map(toRef),
+    columns: Object.fromEntries(
+      Object.entries(analysis.lineage.columns).map(([column, refs]) => [column, refs.map(toRef)])
+    ),
+  }
+}
+
+/** A marked column the step reads, for messages. */
+function describeMarkedRead(step: PipelineStepDefinition, markings: DatasetMarkings): string {
+  const ref = stepReadColumns(step).find((candidate) => markings.of(candidate).size > 0)
+  if (!ref) return "no marked column"
+
+  const path = `${ref.datasetId}.${ref.column}`
+  return `column '${path}', which carries ${describeOrigins(markings.of(ref), path)}`
+}
+
+function registeredDataset(
+  datasetsById: ReadonlyMap<string, DatasetDefinition>,
+  datasetId: string,
+  subject: string
+): DatasetDefinition {
+  const dataset = datasetsById.get(datasetId)
+  if (!dataset) throw new PipelineError(`${subject} reads unregistered dataset '${datasetId}'.`)
+  return dataset
+}

package/src/security/project.ts

@@ -0,0 +1,8 @@
+import type { ProjectReference } from "./types"
+
+/** Project-wide surfaces used in security grants such as `can.observe(project.logs)`. */
+export const project: ProjectReference = Object.freeze({
+  kind: "project",
+  logs: Object.freeze({ kind: "logs" }),
+  activity: Object.freeze({ kind: "activity" }),
+})

package/src/security/projection-markings.ts

@@ -0,0 +1,421 @@
+import type { DatasetVersion } from "../lake-storage/types"
+import type { OntologyDefinitionCatalog } from "../ontology/registry"
+import type { ObjectType } from "../ontology/types"
+import type { ProjectionDefinitionCatalog } from "../projections/registry"
+import type {
+  LinkProjectionDefinition,
+  ObjectProjectionDefinition,
+  ProjectionDefinition,
+  TelemetryProjectionDefinition,
+} from "../projections/types"
+import type { VersionClassification } from "./dataset-version-markings"
+import { SecurityValidationError } from "./errors"
+import type { ColumnMarkingOrigins, DatasetMarkings, MarkingOrigin } from "./marking-propagation"
+
+type OntologyLookup = Pick<OntologyDefinitionCatalog, "getObjectTypeById">
+
+/** Markings of one column of the projection's dataset. */
+type ColumnMarkingsLookup = (column: string) => readonly string[]
+
+/** What a marked key column makes unreadable: the objects it identifies, or the link it keys. */
+export type ProjectionKeyTarget =
+  | { readonly kind: "type"; readonly objectTypeId: string }
+  | {
+      readonly kind: "link"
+      readonly objectTypeId: string
+      readonly linkId: string
+      readonly targetObjectTypeId: string
+    }
+
+/** A marking rule a projection breaks. */
+type ProjectionMarkingViolation =
+  | {
+      readonly kind: "undeclared"
+      readonly property: string
+      readonly objectTypeId: string
+      readonly propertyId: string
+      readonly column: string
+      readonly missing: readonly string[]
+    }
+  | {
+      readonly kind: "markedKeyColumn"
+      readonly column: string
+      readonly role: string
+      readonly targets: readonly ProjectionKeyTarget[]
+      /** The property the column fills, when the key is a property. */
+      readonly property?: { readonly objectTypeId: string; readonly propertyId: string }
+    }
+  | { readonly kind: "markedKeyProperty"; readonly property: string; readonly role: string }
+  | { readonly kind: "telemetry"; readonly column: string }
+
+/**
+ * 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.
+ *
+ * Startup checks it with the markings columns declare or inherit through `run` steps, and the
+ * pipeline preflight with the markings SQL steps derive as well.
+ */
+export function validateProjectionMarkings(
+  projections: ProjectionDefinitionCatalog,
+  ontology: OntologyLookup,
+  markings: DatasetMarkings
+): void {
+  const all = [
+    ...projections.listObjects(),
+    ...projections.listLinks(),
+    ...projections.listTelemetry(),
+  ]
+
+  for (const projection of all) {
+    const originsOf = (column: string) => markings.of({ datasetId: projection.datasetId, column })
+    const violation = firstViolation(projection, ontology, (column) => [
+      ...originsOf(column).keys(),
+    ])
+    if (!violation) continue
+
+    const carries = (column: string): CarriedMarkings => {
+      const origins = originsOf(column)
+      return {
+        text: describeOrigins(origins, `${projection.datasetId}.${column}`),
+        inherited: [...origins.values()].some((origin) => origin.steps.length > 0),
+      }
+    }
+
+    throw new SecurityValidationError(
+      violationMessage(
+        `[Sixb] Projection '${projection.id}'`,
+        projection.datasetId,
+        violation,
+        carries
+      )
+    )
+  }
+}
+
+/**
+ * Refuse to project a dataset version whose columns carry more markings than the projection
+ * allows. A version keeps the markings of the code that produced it, so a version written before
+ * the current code can carry markings startup did not see. Call it once per version, before
+ * reading its rows; it reads nothing, so what it throws is a refusal that no retry changes.
+ */
+export function assertProjectionVersionMarkings(input: {
+  readonly projection: ProjectionDefinition
+  readonly ontology: OntologyLookup
+  readonly version: DatasetVersion
+  readonly classification: VersionClassification
+}): void {
+  const { projection, version, classification } = input
+  const markingsOf = (column: string) => [...(classification.columns.get(column) ?? [])].sort()
+  const violation = firstViolation(projection, input.ontology, markingsOf)
+  if (!violation) return
+
+  const subject = `[Sixb] Projection '${projection.id}' cannot read version '${version.versionId}' of dataset '${version.datasetId}'`
+  const carries = (column: string): CarriedMarkings => ({
+    text: `${markingList(markingsOf(column))} in this version`,
+    inherited: true,
+  })
+  const conservative =
+    classification.conservative === undefined
+      ? ""
+      : ` The version was classified with every marking its sources could hold, because ${classification.conservative}.`
+  const rerun = `If the code that writes '${version.datasetId}' no longer derives these markings, rerun its pipeline.`
+
+  throw new Error(
+    `${violationMessage(subject, version.datasetId, violation, carries)}${conservative} ${rerun}`
+  )
+}
+
+/** Markings an applied version gives a projection's targets beyond what the ontology declares. */
+export interface ProjectionSurplus {
+  /** Markings a mapped column carries that its property does not declare. */
+  readonly properties: readonly {
+    readonly objectTypeId: string
+    readonly propertyId: string
+    readonly column: string
+    readonly markings: readonly string[]
+  }[]
+  /** Marked key columns, with what each one makes unreadable and why. */
+  readonly keys: readonly {
+    readonly target: ProjectionKeyTarget
+    readonly column: string
+    readonly role: string
+    readonly markings: readonly string[]
+  }[]
+}
+
+/**
+ * What a projection's targets carry beyond their declarations when read from columns with these
+ * markings: every rule it breaks, as markings to add to properties and to key targets. A property
+ * that keys a link keeps its markings on the property as well.
+ */
+export function projectionSurplus(
+  projection: ProjectionDefinition,
+  ontology: OntologyLookup,
+  markingsOf: ColumnMarkingsLookup
+): ProjectionSurplus {
+  const properties: ProjectionSurplus["properties"][number][] = []
+  const keys: ProjectionSurplus["keys"][number][] = []
+
+  for (const violation of projectionMarkingViolations(projection, ontology, markingsOf)) {
+    switch (violation.kind) {
+      case "undeclared":
+        properties.push({
+          objectTypeId: violation.objectTypeId,
+          propertyId: violation.propertyId,
+          column: violation.column,
+          markings: violation.missing,
+        })
+        break
+      case "markedKeyColumn": {
+        const markings = markingsOf(violation.column)
+        for (const target of violation.targets) {
+          keys.push({ target, column: violation.column, role: violation.role, markings })
+        }
+
+        const property = violation.property
+        if (property && violation.targets.some((target) => target.kind === "link")) {
+          properties.push({ ...property, column: violation.column, markings })
+        }
+        break
+      }
+      // Startup refuses a marked key property and a marked telemetry column from the code alone.
+      case "markedKeyProperty":
+      case "telemetry":
+        break
+    }
+  }
+
+  return { properties, keys }
+}
+
+// ── Rules ───────────────────────────────────────────────────
+
+function firstViolation(
+  projection: ProjectionDefinition,
+  ontology: OntologyLookup,
+  markingsOf: ColumnMarkingsLookup
+): ProjectionMarkingViolation | null {
+  const first = projectionMarkingViolations(projection, ontology, markingsOf).next()
+  return first.done ? null : first.value
+}
+
+/** Every marking rule the projection breaks, the first one being the one messages report. */
+function* projectionMarkingViolations(
+  projection: ProjectionDefinition,
+  ontology: OntologyLookup,
+  markingsOf: ColumnMarkingsLookup
+): Generator<ProjectionMarkingViolation> {
+  switch (projection._tag) {
+    case "ObjectProjectionDefinition": {
+      const objectType = ontology.getObjectTypeById(projection.objectTypeId)
+      if (objectType) yield* objectProjectionViolations(projection, objectType, markingsOf)
+      return
+    }
+    case "LinkProjectionDefinition":
+      yield* linkProjectionViolations(projection, markingsOf)
+      return
+    case "TelemetryProjectionDefinition":
+      yield* telemetryProjectionViolations(projection, markingsOf)
+      return
+  }
+}
+
+function* objectProjectionViolations(
+  projection: ObjectProjectionDefinition,
+  objectType: ObjectType,
+  markingsOf: ColumnMarkingsLookup
+): Generator<ProjectionMarkingViolation> {
+  const keyRoles = objectProjectionKeyRoles(projection, objectType)
+
+  for (const [propertyId, column] of Object.entries(projection.properties)) {
+    const property = objectType.properties.find((candidate) => candidate.id === propertyId)
+    const path = `${objectType.id}.${propertyId}`
+    const keyRole = keyRoles.get(propertyId)
+
+    if (keyRole) {
+      if (markingsOf(column).length > 0) {
+        yield {
+          kind: "markedKeyColumn",
+          column,
+          role: keyRole.role,
+          targets: keyRole.targets,
+          property: { objectTypeId: objectType.id, propertyId },
+        }
+      } else if (property?.markings) {
+        yield { kind: "markedKeyProperty", property: path, role: keyRole.role }
+      }
+      continue
+    }
+
+    const declared = new Set(property?.markings ?? [])
+    const missing = markingsOf(column).filter((markingId) => !declared.has(markingId))
+    if (missing.length > 0) {
+      yield {
+        kind: "undeclared",
+        property: path,
+        objectTypeId: objectType.id,
+        propertyId,
+        column,
+        missing,
+      }
+    }
+  }
+
+  for (const [linkId, link] of Object.entries(projection.links)) {
+    if (link.sourceField === undefined) continue
+
+    const role = `keys link '${objectType.id}.${linkId}'`
+    const target = linkTarget(objectType.id, linkId, link.targetObjectTypeId)
+    yield* markedKeyColumn(link.sourceField, role, [target], markingsOf)
+  }
+
+  // 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") {
+    const role = "decides which value wins under 'mostRecent'"
+    const target: ProjectionKeyTarget = { kind: "type", objectTypeId: objectType.id }
+    yield* markedKeyColumn(conflictResolution.sourceTimestamp, role, [target], markingsOf)
+  }
+}
+
+function* linkProjectionViolations(
+  projection: LinkProjectionDefinition,
+  markingsOf: ColumnMarkingsLookup
+): Generator<ProjectionMarkingViolation> {
+  const role = `keys link '${projection.sourceObjectTypeId}.${projection.linkId}'`
+  const targets = [
+    linkTarget(projection.sourceObjectTypeId, projection.linkId, projection.targetObjectTypeId),
+  ]
+  yield* markedKeyColumn(projection.sourceField, role, targets, markingsOf)
+  yield* markedKeyColumn(projection.targetField, role, targets, markingsOf)
+}
+
+function* telemetryProjectionViolations(
+  projection: TelemetryProjectionDefinition,
+  markingsOf: ColumnMarkingsLookup
+): Generator<ProjectionMarkingViolation> {
+  const columns = [
+    projection.objectIdField,
+    projection.atField,
+    ...Object.values(projection.properties).flatMap((mapping) =>
+      mapping.unitField === undefined
+        ? [mapping.valueField]
+        : [mapping.valueField, mapping.unitField]
+    ),
+  ]
+
+  for (const column of columns) {
+    if (markingsOf(column).length > 0) yield { kind: "telemetry", column }
+  }
+}
+
+interface KeyRole {
+  readonly role: string
+  readonly targets: readonly ProjectionKeyTarget[]
+}
+
+/** Properties whose value becomes an object id or a link key, with the role they play. */
+function objectProjectionKeyRoles(
+  projection: ObjectProjectionDefinition,
+  objectType: ObjectType
+): ReadonlyMap<string, KeyRole> {
+  const roles = new Map<string, KeyRole>()
+
+  for (const property of objectType.properties) {
+    if (!property.primary) continue
+    roles.set(property.id, {
+      role: `becomes the id of '${objectType.id}'`,
+      targets: [{ kind: "type", objectTypeId: objectType.id }],
+    })
+  }
+
+  for (const [linkId, link] of Object.entries(projection.links)) {
+    if (link.sourcePropertyId === undefined) continue
+    // An id that also keys a link plays both roles; messages name the link.
+    roles.set(link.sourcePropertyId, {
+      role: `keys link '${objectType.id}.${linkId}'`,
+      targets: [
+        ...(roles.get(link.sourcePropertyId)?.targets ?? []),
+        linkTarget(objectType.id, linkId, link.targetObjectTypeId),
+      ],
+    })
+  }
+
+  return roles
+}
+
+function linkTarget(
+  objectTypeId: string,
+  linkId: string,
+  targetObjectTypeId: string
+): ProjectionKeyTarget {
+  return { kind: "link", objectTypeId, linkId, targetObjectTypeId }
+}
+
+function* markedKeyColumn(
+  column: string,
+  role: string,
+  targets: readonly ProjectionKeyTarget[],
+  markingsOf: ColumnMarkingsLookup
+): Generator<ProjectionMarkingViolation> {
+  if (markingsOf(column).length > 0) yield { kind: "markedKeyColumn", column, role, targets }
+}
+
+// ── Messages ────────────────────────────────────────────────
+
+/** What a column carries, for messages, and whether any of it comes from elsewhere. */
+interface CarriedMarkings {
+  readonly text: string
+  readonly inherited: boolean
+}
+
+function violationMessage(
+  subject: string,
+  datasetId: string,
+  violation: ProjectionMarkingViolation,
+  carries: (column: string) => CarriedMarkings
+): string {
+  const path = (column: string) => `${datasetId}.${column}`
+
+  switch (violation.kind) {
+    case "undeclared":
+      return `${subject}: property '${violation.property}' is projected from column '${path(violation.column)}', which carries ${carries(violation.column).text}. Add markings: ${markingList(violation.missing)} to the property.`
+    case "markedKeyColumn": {
+      const carried = carries(violation.column)
+      const inherited = carried.inherited ? `, but carries ${carried.text}` : ""
+      return `${subject}: column '${path(violation.column)}' ${violation.role} and cannot carry markings${inherited}.`
+    }
+    case "markedKeyProperty":
+      return `${subject}: property '${violation.property}' ${violation.role} and cannot carry markings.`
+    case "telemetry":
+      return `${subject}: column '${path(violation.column)}' carries ${carries(violation.column).text}, and telemetry projections cannot read marked columns yet.`
+  }
+}
+
+/**
+ * `[financial] from 'raw_invoices.amount' through step 'invoices/normalize'`: each marking with one
+ * path it arrived by. Markings the column declares itself have no path.
+ */
+export function describeOrigins(origins: ColumnMarkingOrigins, columnPath: string): string {
+  const groups = new Map<string, string[]>()
+  for (const [markingId, origin] of origins) {
+    const path = originPath(origin, columnPath)
+    groups.set(path, [...(groups.get(path) ?? []), markingId])
+  }
+  return [...groups].map(([path, markingIds]) => `${markingList(markingIds)}${path}`).join(" and ")
+}
+
+function originPath(origin: MarkingOrigin, columnPath: string): string {
+  const source = `${origin.column.datasetId}.${origin.column.column}`
+  if (origin.steps.length === 0 && source === columnPath) return ""
+
+  const steps = origin.steps.map((step) => `'${step}'`).join(", ")
+  return ` from '${source}' through ${origin.steps.length === 1 ? "step" : "steps"} ${steps}`
+}
+
+function markingList(markings: readonly string[]): string {
+  return `[${markings.join(", ")}]`
+}

package/src/security/redactions.ts

@@ -1,6 +1,11 @@
 import type { Redactions } from "./types"
 
-/** List the values hidden from a reader that lacks a clearance for their markings. */
+const MISSING_CLEARANCE = Object.freeze({ reason: "missing_clearance" } as const)
+
+/**
+ * List the values hidden from a reader that lacks a clearance for their markings. Deeply frozen,
+ * so every row and event redacted the same way can share it.
+ */
 export function missingClearanceRedactions(ids: Iterable<string>): Redactions {
-  return Object.fromEntries([...ids].map((id) => [id, { reason: "missing_clearance" }] as const))
+  return Object.freeze(Object.fromEntries([...ids].map((id) => [id, MISSING_CLEARANCE] as const)))
 }

package/src/security/types.ts

@@ -116,9 +116,27 @@ export interface AgentRunGrant {
   readonly target: "agent"
 }
 
-export type ObserveGrantTarget = "logs" | "aiUsage"
+export type ObserveGrantTarget = "logs" | "aiUsage" | "activity"
 
-/** Read the project's logs or its AI usage. Each is one surface, so there is nothing to select. */
+/**
+ * Project-wide surfaces used in security grants such as `can.observe(project.logs)`. Each member's
+ * `kind` is the grant target it selects.
+ */
+export interface ProjectReference {
+  readonly kind: "project"
+  /** The project's captured logs. */
+  readonly logs: { readonly kind: "logs" }
+  /** Visits and page views recorded in the project's app. */
+  readonly activity: { readonly kind: "activity" }
+}
+
+/** Any member of `project`, such as `project.logs`. */
+export type ProjectSurfaceReference = ProjectReference[Exclude<keyof ProjectReference, "kind">]
+
+/**
+ * Read the project's logs, its AI usage or its app activity. Each is one surface, so there is
+ * nothing to select.
+ */
 export interface ObserveGrant {
   readonly kind: "grant"
   readonly capability: "observe"

package/src/security/validation.ts

@@ -251,16 +251,23 @@ export function assertGrantDefinition(
     )
   }
 
-  if (value.capability === "observe" && value.target !== "logs" && value.target !== "aiUsage") {
-    throw createError(`[Sixb] ${field} observe grant target must be 'logs' or 'aiUsage'.`)
+  if (
+    value.capability === "observe" &&
+    value.target !== "logs" &&
+    value.target !== "aiUsage" &&
+    value.target !== "activity"
+  ) {
+    throw createError(
+      `[Sixb] ${field} observe grant target must be 'logs', 'aiUsage', or 'activity'.`
+    )
   }
 
   if (value.capability === "manage" && value.target !== "connector" && value.target !== "aiUsage") {
     throw createError(`[Sixb] ${field} manage grant target must be 'connector' or 'aiUsage'.`)
   }
 
-  // The agent, logs and AI usage are one surface each, so their grants select nothing. The checks
-  // above settled the capability and target, so the kind is known.
+  // The agent, logs, AI usage and activity are one surface each, so their grants select nothing.
+  // The checks above settled the capability and target, so the kind is known.
   if (isSingletonGrantKind(grantKindOf(value as unknown as GrantDefinition))) {
     if (value.selection !== undefined) {
       throw createError(