@sixb/core 0.1.19 → 0.1.21

package/src/security/dataset-version-markings.ts

@@ -0,0 +1,163 @@
+import type { DatasetDefinition } from "../datasets/types"
+import { isUnknownLineage, lineageColumn, versionLineage } from "../lake-storage/lineage"
+import type { DatasetColumnRef, DatasetVersion, LakeStorage } from "../lake-storage/types"
+import { MarkingSets } from "./marking-sets"
+
+/** Markings of each column of one dataset version. A column without markings has an empty set. */
+export type VersionColumnMarkings = ReadonlyMap<string, ReadonlySet<string>>
+
+export interface VersionClassification {
+  readonly columns: VersionColumnMarkings
+  /**
+   * Why part of the version was classified conservatively, with every marking it could hold.
+   * Absent when every column was classified from its lineage.
+   */
+  readonly conservative?: string
+}
+
+/**
+ * Markings each version of a dataset carries.
+ *
+ * Markings are never stored. A column carries the markings its registered dataset declares, and
+ * those every column its lineage lists declares. The version records that lineage resolved across
+ * every upstream step and every row it keeps (`DatasetVersion.lineage`), so a version keeps the
+ * classification of the code that produced it, and classifying it reads no other version.
+ *
+ * Wherever the record does not say what a column holds (no lineage on a pipeline version, or on
+ * any version of a provider that does not declare `recordsLineage`, an unknown history, a column
+ * it does not list, a dataset no longer registered) the column is classified with every marking
+ * the project declares.
+ */
+export interface DatasetVersionMarkings {
+  classify(version: DatasetVersion): VersionClassification
+  /**
+   * Every marking declared on a registered column. Every classification, conservative ones
+   * included, is drawn from it, so a reader cleared for all of it needs no classification. Empty
+   * when the project declares no column markings.
+   */
+  everyMarking(): ReadonlySet<string>
+}
+
+export interface DatasetVersionMarkingsOptions {
+  readonly datasets: { list(): readonly DatasetDefinition[] }
+  /** The lake the versions are read from: whether it records lineage on every version. */
+  readonly lakeStorage: Pick<LakeStorage, "recordsLineage">
+}
+
+export function createDatasetVersionMarkings(
+  options: DatasetVersionMarkingsOptions
+): DatasetVersionMarkings {
+  const sets = new MarkingSets()
+
+  // Built on first use: a host that never classifies a version pays nothing for it.
+  let declared: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>> | undefined
+  const declaredByDataset = () =>
+    (declared ??= new Map(
+      options.datasets
+        .list()
+        .map((dataset) => [
+          dataset.id,
+          new Map(dataset.schema.columns.map((column) => [column.name, sets.of(column.markings)])),
+        ])
+    ))
+
+  /**
+   * Every marking a registered column declares: what a column may hold where its record does not
+   * say. The pipelines that wrote it may have read datasets the current code no longer reads, so
+   * nothing narrower is safe.
+   */
+  let every: ReadonlySet<string> | undefined
+  const everyMarking = () =>
+    (every ??= sets.union(
+      [...declaredByDataset().values()].flatMap((columns) => [...columns.values()])
+    ))
+
+  const classify = (version: DatasetVersion): VersionClassification => {
+    const subject = `version '${version.versionId}' of '${version.datasetId}'`
+    const own = declaredByDataset().get(version.datasetId)
+
+    // No definition says what its columns declare: they may hold anything a column declares.
+    if (!own) return conservatively(version, `dataset '${version.datasetId}' is not registered`)
+
+    const lineage = versionLineage(version, options.lakeStorage)
+    if (isUnknownLineage(lineage)) {
+      // A reason core derived names this version. A recorded one names where the lineage was
+      // lost: upstream, or, for a provider that could not decode it, this version's own record.
+      return conservatively(
+        version,
+        lineage === version.lineage
+          ? `the lineage of ${subject} is unknown: ${lineage.unknown}`
+          : lineage.unknown
+      )
+    }
+
+    let conservative: string | undefined
+    const markingsOf = (ref: DatasetColumnRef): ReadonlySet<string> | undefined => {
+      const columns = declaredByDataset().get(ref.datasetId)
+      if (columns) return columns.get(ref.column)
+      conservative ??= `dataset '${ref.datasetId}' is not registered`
+      return everyMarking()
+    }
+
+    const rows = sets.union(lineage.rows.map(markingsOf))
+    const columns = new Map(
+      version.schema.columns.map(({ name }) => {
+        const values = lineageColumn(lineage, name)
+        if (!values) {
+          conservative ??= `${subject} recorded no lineage for column '${name}'`
+          return [name, everyMarking()]
+        }
+
+        return [name, sets.union([own.get(name), rows, ...values.map(markingsOf)])]
+      })
+    )
+
+    return { columns, ...(conservative === undefined ? {} : { conservative }) }
+  }
+
+  const conservatively = (version: DatasetVersion, reason: string): VersionClassification => {
+    const markings = everyMarking()
+    return {
+      columns: new Map(version.schema.columns.map(({ name }) => [name, markings])),
+      conservative: reason,
+    }
+  }
+
+  return { classify, everyMarking }
+}
+
+// ── Host capability ─────────────────────────────────────────
+
+const datasetVersionMarkingsKey: unique symbol = Symbol("sixb.datasetVersionMarkings")
+
+interface DatasetVersionMarkingsOwner {
+  readonly [datasetVersionMarkingsKey]?: DatasetVersionMarkings
+}
+
+/** One classifier per host, so every reader shares the markings it reads from the definitions. */
+export function registerDatasetVersionMarkings(
+  owner: object,
+  markings: DatasetVersionMarkings
+): void {
+  const registered = (owner as DatasetVersionMarkingsOwner)[datasetVersionMarkingsKey]
+  if (registered && registered !== markings) {
+    throw new Error("[Sixb] Dataset version markings are already registered for this owner.")
+  }
+
+  Object.defineProperty(owner, datasetVersionMarkingsKey, {
+    configurable: false,
+    enumerable: false,
+    value: markings,
+    writable: false,
+  })
+}
+
+export function getDatasetVersionMarkings(owner: object): DatasetVersionMarkings {
+  const markings = (owner as DatasetVersionMarkingsOwner)[datasetVersionMarkingsKey]
+  if (markings) return markings
+  throw new Error("[Sixb] Dataset version markings are not registered for this runtime.")
+}
+
+export function shareDatasetVersionMarkings(source: object, target: object): void {
+  registerDatasetVersionMarkings(target, getDatasetVersionMarkings(source))
+}

package/src/security/every.ts

@@ -20,7 +20,6 @@ import type { ShareDefinition } from "../shares"
 import type { SyncDefinition } from "../syncs"
 import type { WorkflowDefinition } from "../workflows/types"
 import { SecurityValidationError } from "./errors"
-import type { ApplicationDefinition } from "./types"
 
 /** Capability targets a breadth selector can range over. */
 export const BREADTH_TARGETS = [
@@ -30,7 +29,6 @@ export const BREADTH_TARGETS = [
   "workflow",
   "sync",
   "pipeline",
-  "application",
   "connector",
   "share",
 ] as const
@@ -44,7 +42,6 @@ interface BreadthTargetInput {
   workflow: WorkflowDefinition
   sync: SyncDefinition
   pipeline: PipelineDefinition
-  application: ApplicationDefinition
   connector: ConnectorDefinition
   share: ShareDefinition
 }
@@ -106,7 +103,6 @@ export const every = {
   workflow: (): BreadthSelector<"workflow"> => all("workflow"),
   sync: (): BreadthSelector<"sync"> => all("sync"),
   pipeline: (): BreadthSelector<"pipeline"> => all("pipeline"),
-  application: (): BreadthSelector<"application"> => all("application"),
   connector: (): BreadthSelector<"connector"> => all("connector"),
   share: (): BreadthSelector<"share"> => all("share"),
 }

package/src/security/grants.ts

@@ -1,7 +1,7 @@
 /**
  * Grant builders for role definitions.
  *
- * Grants are plain data referencing application and runtime definitions
+ * Grants are plain data referencing runtime definitions
  * by id. They carry no enforcement logic — the authorization engine expands
  * each grant's selection into per-principal id sets at startup, so runtime
  * checks stay simple `set.has(id)` lookups.
@@ -31,14 +31,13 @@ import {
   isBreadthSelector,
 } from "./every"
 import type {
-  AccessGrant,
   AgentRunGrant,
   AppendGrant,
-  ApplicationDefinition,
   ApplyGrant,
   EditGrant,
   ManageGrant,
   ObserveGrant,
+  ProjectSurfaceReference,
   RunGrant,
   Selection,
   ShareGrant,
@@ -54,7 +53,7 @@ const VIEW_TARGETS = ["object", "dataset"] as const
 const RUN_TARGETS = ["workflow", "sync", "pipeline"] as const
 
 /**
- * Seven of the nine targets carry a `kind` discriminant naming themselves. The other two — an
+ * Six of the eight targets carry a `kind` discriminant naming themselves. The other two — an
  * `ObjectType` and an `ActionDefinition` — carry none, and each appears in exactly one builder that
  * allows no other undiscriminated target, so the allowed set names them unambiguously.
  */
@@ -63,7 +62,6 @@ const TARGET_BY_DEFINITION_KIND: Readonly<Partial<Record<string, BreadthTarget>>
   sync: "sync",
   pipeline: "pipeline",
   workflow: "workflow",
-  application: "application",
   connector: "connector",
   share: "share",
 }
@@ -82,7 +80,7 @@ function targetOfDefinition<TTarget extends BreadthTarget>(
   // `spec.universeKey` with a `TypeError` naming neither the role nor the definition.
   if (discriminated) {
     if (!isAllowedTarget(discriminated, allowedTargets)) {
-      // "one targeting x", not "a x definition": four of the eight targets start with a vowel, and
+      // "one targeting x", not "a x definition": object and action start with a vowel, and
       // this string ships in a release. Same reason the selector branch below writes no article.
       throw new SecurityValidationError(
         `[Sixb] ${label} accepts ${allowedTargets.join(" or ")} definitions, but received one targeting ${discriminated}.`
@@ -158,11 +156,6 @@ function resolveGrant<TDefinition extends { readonly id?: unknown }, TTarget ext
   return { target, selection: { all: false, ids } }
 }
 
-function access(input: GrantInput<ApplicationDefinition, "application">): AccessGrant {
-  const { selection } = resolveGrant(input, "can.access", ["application"])
-  return { kind: "grant", capability: "access", target: "application", selection }
-}
-
 function view<const TObjectTypeId extends string>(
   input: ShareTarget<TObjectTypeId>
 ): ShareViewGrantBuilder<TObjectTypeId>
@@ -266,17 +259,45 @@ function isAgentUsageReference(input: unknown): input is AgentUsageReference {
   )
 }
 
-function observe(input: "logs" | AgentUsageReference): ObserveGrant {
-  if (input !== "logs" && !isAgentUsageReference(input)) {
-    throw new SecurityValidationError('[Sixb] can.observe accepts "logs" or agent.usage.')
+type ObservableReference = ProjectSurfaceReference | AgentUsageReference
+
+/**
+ * Every reference `can.observe` accepts, keyed by its `kind`, which is also its grant target. The
+ * full `Record` is what stops a new `project` member from compiling until it is listed here.
+ */
+const OBSERVABLE_REFERENCES: Readonly<Record<ObservableReference["kind"], string>> = {
+  logs: "project.logs",
+  activity: "project.activity",
+  aiUsage: "agent.usage",
+}
+
+function isObservableReference(input: unknown): input is ObservableReference {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    "kind" in input &&
+    typeof input.kind === "string" &&
+    Object.hasOwn(OBSERVABLE_REFERENCES, input.kind)
+  )
+}
+
+function observe(input: ObservableReference): ObserveGrant {
+  const value: unknown = input
+
+  // Older role files pass the string form. Point them at the reference instead of only rejecting
+  // the input.
+  if (value === "logs") {
+    throw new SecurityValidationError(
+      '[Sixb] can.observe("logs") is now can.observe(project.logs), imported from "@sixb/core".'
+    )
   }
-  const target = input === "logs" ? "logs" : "aiUsage"
-  return {
-    kind: "grant",
-    capability: "observe",
-    target,
-    selection: { all: false, ids: [target] },
+
+  if (!isObservableReference(value)) {
+    const accepted = Object.values(OBSERVABLE_REFERENCES).join(" or ")
+    throw new SecurityValidationError(`[Sixb] can.observe accepts ${accepted}.`)
   }
+
+  return { kind: "grant", capability: "observe", target: value.kind }
 }
 
 function manage(input: GrantInput<ConnectorDefinition, "connector">): ManageGrant<"connector">
@@ -285,12 +306,7 @@ function manage(
   input: GrantInput<ConnectorDefinition, "connector"> | AgentUsageReference
 ): ManageGrant {
   if (isAgentUsageReference(input)) {
-    return {
-      kind: "grant",
-      capability: "manage",
-      target: "aiUsage",
-      selection: { all: false, ids: ["aiUsage"] },
-    }
+    return { kind: "grant", capability: "manage", target: "aiUsage" }
   }
   return {
     kind: "grant",
@@ -301,7 +317,6 @@ function manage(
 }
 
 export const can = {
-  access,
   view,
   edit,
   append,

package/src/security/index.ts

@@ -1,4 +1,3 @@
-export { applications } from "./applications"
 export type {
   DefineGroupOptions,
   DefineMarkingOptions,
@@ -17,13 +16,12 @@ export {
   missingMembershipGroupIds,
   resolveMembershipPolicyScope,
 } from "./membership-policies"
+export { project } from "./project"
 export type { SecurityDefinitionCatalog, SecurityRegistryOptions } from "./registry"
 export { SecurityRegistry } from "./registry"
 export type {
-  AccessGrant,
   AgentRunGrant,
   AppendGrant,
-  ApplicationDefinition,
   ApplyGrant,
   EditGrant,
   GrantCapability,
@@ -37,6 +35,8 @@ export type {
   MembershipPolicyDefinition,
   ObserveGrant,
   ObserveGrantTarget,
+  ProjectReference,
+  ProjectSurfaceReference,
   RedactionReason,
   Redactions,
   RegisteredSecurityDefinitions,

package/src/security/internal.ts

@@ -0,0 +1,18 @@
+/**
+ * Marking plumbing for this repo's hosts and workers, not for app authors.
+ *
+ * `checkPipelineMarkings` is the SQL preflight the API server and CLI run before serving. The
+ * projection worker shares the host's version classifier with `shareDatasetVersionMarkings`, then
+ * classifies each pinned version and refuses one with `assertProjectionVersionMarkings`. The API
+ * server reads the versions projections applied ahead of its first request with
+ * `warmAppliedMarkings`, and the CLI reports what they add with `getAppliedMarkings`.
+ */
+export { getAppliedMarkings, warmAppliedMarkings } from "./applied-markings-host"
+export type {
+  DatasetVersionMarkings,
+  VersionClassification,
+  VersionColumnMarkings,
+} from "./dataset-version-markings"
+export { getDatasetVersionMarkings, shareDatasetVersionMarkings } from "./dataset-version-markings"
+export { checkPipelineMarkings } from "./pipeline-markings"
+export { assertProjectionVersionMarkings } from "./projection-markings"

package/src/security/marking-propagation.ts

@@ -0,0 +1,255 @@
+import type { DatasetDefinition } from "../datasets/types"
+import { lineageColumn } from "../lake-storage/lineage"
+import type { DatasetColumnLineage, DatasetColumnRef } from "../lake-storage/types"
+import { runStepLineage, stepReadColumns } from "../pipelines/lineage"
+import type { PipelineDefinition, PipelineStepDefinition } from "../pipelines/types"
+
+/** A step of a registered pipeline. A step reused by two pipelines is two registered steps. */
+export interface RegisteredStep {
+  readonly pipelineId: string
+  readonly step: PipelineStepDefinition
+}
+
+/** The column that declares a marking, and the steps it went through to reach a column. */
+export interface MarkingOrigin {
+  readonly column: DatasetColumnRef
+  /** `pipeline/step`, upstream first. Empty when the column declares the marking itself. */
+  readonly steps: readonly string[]
+}
+
+/** Each marking a column carries, with one path it arrived by. */
+export type ColumnMarkingOrigins = ReadonlyMap<string, MarkingOrigin>
+
+/** Markings of every column of every registered dataset, derived from the definitions. */
+export interface DatasetMarkings {
+  /** Empty for a column without markings or that is not registered. */
+  of(column: DatasetColumnRef): ColumnMarkingOrigins
+}
+
+export function registeredSteps(
+  pipelines: readonly PipelineDefinition[]
+): readonly RegisteredStep[] {
+  return pipelines.flatMap((pipeline) =>
+    pipeline.graph.nodes.map(({ step }) => ({ pipelineId: pipeline.id, step }))
+  )
+}
+
+/** Lineage of each `run` step, built once per step object; undefined for other steps. */
+export function runStepLineages(
+  datasetsById: ReadonlyMap<string, DatasetDefinition>
+): (entry: RegisteredStep) => DatasetColumnLineage | undefined {
+  const lineages = new Map<PipelineStepDefinition, DatasetColumnLineage>()
+
+  return ({ step }) => {
+    if (step.executor.kind !== "run") return undefined
+
+    let lineage = lineages.get(step)
+    if (!lineage) {
+      lineage = runStepLineage(step, datasetsById)
+      lineages.set(step, lineage)
+    }
+
+    return lineage
+  }
+}
+
+export function stepLabel(entry: RegisteredStep): string {
+  return `${entry.pipelineId}/${entry.step.id}`
+}
+
+type MutableOrigins = Map<string, MarkingOrigin>
+
+const NO_MARKINGS: ColumnMarkingOrigins = new Map()
+
+interface KnownLineage {
+  readonly lineage: DatasetColumnLineage
+  /** What a column the lineage does not list depends on. */
+  readonly reads: readonly DatasetColumnRef[]
+}
+
+/**
+ * Markings each column carries according to the registered definitions: the ones it declares, and
+ * the ones each step derives from the columns it depends on, once that step's lineage is known.
+ *
+ * What decided the rows of a step's inputs decides the rows of its output, whether or not the step
+ * reads a column of that input: `SELECT count(*) FROM rich` reveals which rows `rich` holds. So
+ * each dataset also keeps the markings of its row dependencies, and every output column of a step
+ * carries those of every input it reads, as the lineage each version records does.
+ *
+ * A step may read its own output and a dataset may have several producers, so a step whose output
+ * gains a marking queues the steps that read that output, until nothing changes. Lineage can be
+ * added in rounds: each round only revisits what the new lineage reaches.
+ */
+export class MarkingPropagation implements DatasetMarkings {
+  private readonly datasetsById: ReadonlyMap<string, DatasetDefinition>
+  /** Marked columns only, by dataset, built when a dataset is first looked at. */
+  private readonly markings = new Map<string, Map<string, MutableOrigins>>()
+  /** Markings of what decides each dataset's rows, for datasets a step writes. */
+  private readonly rowMarkings = new Map<string, MutableOrigins>()
+  private readonly ordered: readonly RegisteredStep[]
+  private readonly readers = new Map<string, RegisteredStep[]>()
+  private readonly known = new Map<RegisteredStep, KnownLineage>()
+  private readonly queue = new Set<RegisteredStep>()
+
+  constructor(
+    datasetsById: ReadonlyMap<string, DatasetDefinition>,
+    steps: readonly RegisteredStep[]
+  ) {
+    this.datasetsById = datasetsById
+    this.ordered = inDependencyOrder(steps)
+
+    for (const entry of steps) {
+      for (const input of new Set(Object.values(entry.step.inputs).map((dataset) => dataset.id))) {
+        appendTo(this.readers, input, entry)
+      }
+    }
+  }
+
+  of(ref: DatasetColumnRef): ColumnMarkingOrigins {
+    return this.markedColumns(ref.datasetId).get(ref.column) ?? NO_MARKINGS
+  }
+
+  /**
+   * Derive markings through every step `lineageOf` knows the lineage of. A step it returns null
+   * for derives nothing until a later call knows it.
+   */
+  derive(lineageOf: (entry: RegisteredStep) => DatasetColumnLineage | null): this {
+    for (const entry of this.ordered) {
+      if (this.known.has(entry)) continue
+
+      const lineage = lineageOf(entry)
+      if (!lineage) continue
+
+      this.known.set(entry, { lineage, reads: stepReadColumns(entry.step) })
+      this.queue.add(entry)
+    }
+
+    for (const entry of this.queue) {
+      this.queue.delete(entry)
+      const known = this.known.get(entry)
+      if (!known || !this.apply(entry, known)) continue
+
+      // Entries added while iterating a Set are visited, so the queue drains in this loop.
+      for (const reader of this.readers.get(entry.step.output.id) ?? []) {
+        if (this.known.has(reader)) this.queue.add(reader)
+      }
+    }
+
+    return this
+  }
+
+  /** Whether the output's rows or any output column gained a marking. */
+  private apply(entry: RegisteredStep, { lineage, reads }: KnownLineage): boolean {
+    const label = stepLabel(entry)
+    const rows = this.union(lineage.rows)
+
+    for (const input of new Set(Object.values(entry.step.inputs).map((dataset) => dataset.id))) {
+      for (const [markingId, origin] of this.rowMarkings.get(input) ?? []) {
+        if (!rows.has(markingId)) rows.set(markingId, origin)
+      }
+    }
+
+    let everyRead: ReadonlyMap<string, MarkingOrigin> | undefined
+    let changed = false
+
+    const outputId = entry.step.output.id
+    let outputRows = this.rowMarkings.get(outputId)
+
+    for (const [markingId, origin] of rows) {
+      if (outputRows?.has(markingId)) continue
+      if (!outputRows) {
+        outputRows = new Map()
+        this.rowMarkings.set(outputId, outputRows)
+      }
+
+      outputRows.set(markingId, { column: origin.column, steps: [...origin.steps, label] })
+      changed = true
+    }
+
+    const marked = this.markedColumns(outputId)
+    for (const { name: column } of this.datasetsById.get(outputId)?.schema.columns ?? []) {
+      const values = lineageColumn(lineage, column)
+      const valueSource = values ? this.union(values) : (everyRead ?? this.union(reads))
+      if (!values) everyRead = valueSource
+
+      for (const source of [rows, valueSource]) {
+        for (const [markingId, origin] of source) {
+          let origins = marked.get(column)
+          if (origins?.has(markingId)) continue
+          if (!origins) {
+            origins = new Map()
+            marked.set(column, origins)
+          }
+
+          origins.set(markingId, { column: origin.column, steps: [...origin.steps, label] })
+          changed = true
+        }
+      }
+    }
+
+    return changed
+  }
+
+  private markedColumns(datasetId: string): Map<string, MutableOrigins> {
+    let columns = this.markings.get(datasetId)
+    if (!columns) {
+      columns = new Map()
+      for (const column of this.datasetsById.get(datasetId)?.schema.columns ?? []) {
+        if (!column.markings?.length) continue
+
+        const origin = { column: { datasetId, column: column.name }, steps: [] }
+        columns.set(column.name, new Map(column.markings.map((id) => [id, origin])))
+      }
+
+      this.markings.set(datasetId, columns)
+    }
+
+    return columns
+  }
+
+  /** Every marking of these columns, each with the first origin found. */
+  private union(columns: readonly DatasetColumnRef[]): MutableOrigins {
+    const union: MutableOrigins = new Map()
+    for (const column of columns) {
+      for (const [markingId, origin] of this.of(column)) {
+        if (!union.has(markingId)) union.set(markingId, origin)
+      }
+    }
+    return union
+  }
+}
+
+/** Producers before consumers, so most markings arrive by their shortest path. */
+function inDependencyOrder(steps: readonly RegisteredStep[]): readonly RegisteredStep[] {
+  const producers = producersByDataset(steps)
+  const ordered: RegisteredStep[] = []
+  const visited = new Set<RegisteredStep>()
+
+  const visit = (entry: RegisteredStep): void => {
+    if (visited.has(entry)) return
+
+    visited.add(entry)
+    for (const input of Object.values(entry.step.inputs)) {
+      for (const producer of producers.get(input.id) ?? []) visit(producer)
+    }
+
+    ordered.push(entry)
+  }
+
+  for (const entry of steps) visit(entry)
+  return ordered
+}
+
+function producersByDataset(
+  steps: readonly RegisteredStep[]
+): ReadonlyMap<string, readonly RegisteredStep[]> {
+  const producers = new Map<string, RegisteredStep[]>()
+  for (const entry of steps) appendTo(producers, entry.step.output.id, entry)
+  return producers
+}
+
+function appendTo<TValue>(map: Map<string, TValue[]>, key: string, value: TValue): void {
+  const values = map.get(key)
+  if (values) values.push(value)
+  else map.set(key, [value])
+}

package/src/security/marking-sets.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared, immutable sets of marking ids.
+ *
+ * Every column of every resolved version holds one of a handful of distinct sets, so each distinct
+ * set is created once and compared by identity.
+ */
+export class MarkingSets {
+  readonly empty: ReadonlySet<string> = new Set()
+  private readonly sets = new Map<string, ReadonlySet<string>>([["", this.empty]])
+
+  of(markingIds: Iterable<string> | undefined): ReadonlySet<string> {
+    // Most columns carry no marking.
+    if (markingIds === undefined || (Array.isArray(markingIds) && markingIds.length === 0)) {
+      return this.empty
+    }
+
+    const sorted = [...new Set(markingIds)].sort()
+    const key = sorted.join("\u0000")
+
+    let set = this.sets.get(key)
+    if (!set) {
+      set = new Set(sorted)
+      this.sets.set(key, set)
+    }
+
+    return set
+  }
+
+  /** The union of sets this instance created. */
+  union(sets: Iterable<ReadonlySet<string> | undefined>): ReadonlySet<string> {
+    let single: ReadonlySet<string> | undefined
+    const ids: string[] = []
+
+    for (const set of sets) {
+      if (!set || set.size === 0) continue
+      single = single === undefined && ids.length === 0 ? set : undefined
+      ids.push(...set)
+    }
+
+    return single ?? this.of(ids)
+  }
+}