deepline 0.3.195 → 0.3.197

package/dist/bundling-sources/shared_libs/plays/workspace-bundle.ts

@@ -0,0 +1,651 @@
+/**
+ * A portable snapshot of what a workspace LOOKS like.
+ *
+ * The dashboard has exactly one seeded shape today — the hand-written arrays in
+ * `apps/deepline-api/src/lib/auth/local-dev-fixtures.ts` — and reviewing a UI
+ * against five invented plays tells you very little about how it holds up on a
+ * real one. A bundle is those same arrays, captured from a live workspace
+ * instead of typed by hand, so a preview or a local stack can be filled with
+ * data that has real shapes: real column counts, real name lengths, real
+ * provider mixes, real run durations, real failure modes.
+ *
+ * The bundle deliberately carries NO credentials and NO identifiers that bind
+ * it back to the workspace it came from. Everything under
+ * `integrationCredentials`, `oauthConnections`, `apiKeys`, `playSecrets` and
+ * friends is simply not part of the capture surface — not excluded by a filter
+ * that could regress, but absent from the types below, so there is no field for
+ * a secret to travel in. See `REDACTED_VALUE_KINDS` for what is rewritten on
+ * the way out.
+ */
+
+import type { PlaySheetContract, PlayStaticPipeline } from './static-pipeline';
+
+export const WORKSPACE_BUNDLE_API_VERSION =
+  'deepline.dev/workspace-bundle/v1' as const;
+
+/**
+ * Wire-compatible with `LocalDevPlayFixture`. The loader feeds these straight
+ * into `internal.plays.registerOrgPlayRevisionInternal`, so the field names are
+ * that mutation's, not ours.
+ */
+export type BundlePlay = {
+  name: string;
+  description: string;
+  sourceCode: string;
+  sourceHash: string;
+  artifactStorageKey: string;
+  staticPipeline: PlayStaticPipeline;
+};
+
+/** Wire-compatible with `LocalDevPlayRunFixture`. */
+export type BundleRun = {
+  key: string;
+  playName: string;
+  /**
+   * Age at capture, not an absolute timestamp. A bundle loaded three weeks
+   * after it was captured should still read as "ran 20 minutes ago", because
+   * the feed's whole job is showing recency — absolute timestamps would make
+   * every loaded workspace look abandoned.
+   */
+  ageMs: number;
+  status: 'completed' | 'failed';
+  inputSummary: Record<string, unknown>;
+  result?: Record<string, unknown>;
+  resultSummary?: Record<string, unknown>;
+  tableNamespace?: string;
+  error?: string;
+  logs: string[];
+};
+
+/** Wire-compatible with `LocalDevPlaySheetFixture`. */
+export type BundleSheet = {
+  playName: string;
+  tableNamespace: string;
+  runKey: string;
+  sheetContract: PlaySheetContract;
+  rows: Array<Record<string, unknown> & { __deeplineRowKey: string }>;
+};
+
+/**
+ * Wire-compatible with `createLocalDevMonitorFixtures`' output MINUS `orgId`,
+ * `installedAt` and `updatedAt`: those are minted by the loader against the
+ * destination org, and carrying the source org id is exactly the binding this
+ * format exists to avoid.
+ */
+export type BundleMonitor = {
+  monitorKey: string;
+  name: string;
+  sourceProvider: string;
+  sourceCapability: string;
+  tool: string;
+  payload: Record<string, unknown>;
+  controls: Record<string, unknown>;
+  outputs: Record<string, unknown>;
+  providerBinding: Record<string, unknown>;
+  billingState: Record<string, unknown>;
+  subjectKind: string;
+  subjectValue: string;
+  subjectLabel: string;
+  signalKey: string;
+  signalLabel: string;
+  signalGroupKey: string;
+  signalGroupLabel: string;
+  searchText: string;
+  publicPreview: Record<string, unknown>;
+};
+
+/** Wire-compatible with `LocalDevMonitorEventFixture`. */
+export type BundleMonitorEvent = {
+  monitorKey: string;
+  tableName: string;
+  payload: Record<string, unknown>;
+  /** Age at capture, for the same reason `BundleRun.ageMs` is. */
+  ageMs: number;
+};
+
+export type WorkspaceBundleRedactionMode = 'pseudonymized' | 'raw';
+
+export type WorkspaceBundle = {
+  apiVersion: typeof WORKSPACE_BUNDLE_API_VERSION;
+  capturedAt: string;
+  /**
+   * Enough to know what you are looking at, and nothing that resolves back to
+   * a tenant. A label the operator typed, never the org id or slug.
+   */
+  source: { label: string };
+  redaction: {
+    mode: WorkspaceBundleRedactionMode;
+    /** Which value kinds were rewritten. Empty iff mode is 'raw'. */
+    kinds: readonly RedactedValueKind[];
+  };
+  plays: BundlePlay[];
+  runs: BundleRun[];
+  sheets: BundleSheet[];
+  monitors: BundleMonitor[];
+  monitorEvents: BundleMonitorEvent[];
+};
+
+export const REDACTED_VALUE_KINDS = [
+  'email',
+  'phone',
+  'linkedin',
+  'person_name',
+  'person_given',
+  'person_family',
+] as const;
+
+export type RedactedValueKind = (typeof REDACTED_VALUE_KINDS)[number];
+
+const EMAIL_RE = /^[^\s@]+@[^\s@.]+\.[^\s@]+$/;
+const LINKEDIN_RE = /^https?:\/\/([a-z0-9-]+\.)?linkedin\.com\/in\/[^\s]+$/i;
+// Deliberately narrow: 7+ digits with optional punctuation and country code.
+// A loose pattern here eats revenue figures and employee counts, which are the
+// numbers that make a captured sheet look like real data.
+const PHONE_RE = /^\+?[\d][\d\s().-]{6,}\d$/;
+
+/**
+ * Columns holding ONE token of a person's name.
+ *
+ * These are why the first capture of a real workspace leaked: `first_name:
+ * "Steven"` is a single capitalised word, so a rule demanding two or three
+ * words passed it straight through while correctly rewriting the `full_name`
+ * sitting beside it.
+ */
+const GIVEN_NAME_COLUMN_RE = /(^|_)(first|given|fore)_?name($|_)/i;
+const FAMILY_NAME_COLUMN_RE = /(^|_)(last|family|sur)_?name($|_)/i;
+
+/** Columns holding a whole person name. */
+const PERSON_NAME_COLUMN_RE =
+  /(^|_)(full|contact|person|owner|founder|exec|prospect|lead|attendee)(_?name)?($|_)/i;
+
+/** A corporate suffix settles it: an organisation, whatever the column says. */
+const COMPANY_SUFFIX_RE =
+  /\b(inc|llc|ltd|limited|gmbh|corp|corporation|co|company|plc|holdings|group|labs|partners|ventures|capital|associates|solutions|services|systems|technologies)\b\.?/i;
+
+/**
+ * The same two things, found INSIDE free text rather than as a whole value.
+ *
+ * Run logs, result summaries and Play source code are prose and code, not
+ * cells — a real capture leaked `steven.wilhelm@…` out of a log line and
+ * `linkedin.com/in/dion-mokhtari` out of a result blob, because a whole-value
+ * matcher never looks inside a sentence. Only emails and LinkedIn URLs are
+ * swept this way: they are unambiguous. Scanning free text for phone numbers
+ * would eat request ids, row counts and timestamps.
+ */
+const EMAIL_IN_TEXT = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g;
+const LINKEDIN_IN_TEXT =
+  /https?:\/\/(?:[a-z0-9-]+\.)?linkedin\.com\/in\/[\w%-]+/gi;
+
+/** One capitalised name token, tolerating apostrophes, hyphens and initials. */
+const NAME_TOKEN = String.raw`\p{Lu}[\p{L}'’-]*\.?`;
+const SINGLE_NAME_RE = new RegExp(`^${NAME_TOKEN}$`, 'u');
+const FULL_NAME_RE = new RegExp(`^${NAME_TOKEN}(?: ${NAME_TOKEN}){1,3}$`, 'u');
+
+/**
+ * Deterministic within one capture, meaningless across captures.
+ *
+ * The salt is generated per capture and never written to the bundle, so the
+ * same input maps to the same pseudonym throughout one snapshot — joins,
+ * dedupes and group-bys keep working, and the UI keeps looking like it is
+ * showing a coherent dataset — while nothing in the published artifact lets you
+ * walk a pseudonym back to the person.
+ */
+export type Pseudonymizer = (value: string, kind: RedactedValueKind) => string;
+
+const FIRST_NAMES = [
+  'Avery',
+  'Rowan',
+  'Marlowe',
+  'Sasha',
+  'Imani',
+  'Dara',
+  'Niko',
+  'Priya',
+  'Elena',
+  'Tobias',
+  'Naomi',
+  'Kwame',
+  'Lucia',
+  'Soren',
+  'Mira',
+  'Idris',
+  'Freya',
+  'Omar',
+  'Talia',
+  'Bastien',
+  'Ines',
+  'Hugo',
+  'Zola',
+  'Rafael',
+];
+
+const LAST_NAMES = [
+  'Okonkwo',
+  'Vance',
+  'Halloran',
+  'Moreau',
+  'Castellanos',
+  'Nakamura',
+  'Lindqvist',
+  'Abadi',
+  'Ferreira',
+  'Whitlock',
+  'Draper',
+  'Sorensen',
+  'Bergström',
+  'Nakashima',
+  'Okafor',
+  'Delacroix',
+  'Ramirez',
+  'Thorne',
+  'Adeyemi',
+  'Kowalski',
+  'Mensah',
+  'Beaumont',
+  'Ivanova',
+  'Quintero',
+];
+
+/** FNV-1a. Not a security primitive — it is salted upstream, see `createPseudonymizer`. */
+function hash32(input: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h >>> 0;
+}
+
+function pick<T>(list: readonly T[], seed: number): T {
+  return list[seed % list.length]!;
+}
+
+/**
+ * Split an identifier that encodes a person's name into its name tokens.
+ *
+ * Handles the three shapes that carry one in practice: an email local part
+ * (`steven.wilhelm`), a LinkedIn slug (`steven-wilhelm-4821`), and a plain
+ * name. Trailing disambiguation digits are dropped so `steven-wilhelm-4821`
+ * and `steven-wilhelm` resolve to the same person.
+ */
+function nameTokensOf(raw: string): string[] {
+  const tokens = raw
+    .split(/[\s._+-]+/)
+    .filter((token) => token !== '' && !/^\d+$/.test(token));
+  return tokens.length > 0 ? tokens : [raw];
+}
+
+/**
+ * Build a pseudonymizer bound to one random salt.
+ *
+ * Pass the salt explicitly only from tests. Production callers let it default
+ * so that two captures of the same workspace produce different pseudonyms and
+ * cannot be correlated with each other.
+ */
+export function createPseudonymizer(
+  salt: string = Math.random().toString(36).slice(2) +
+    Math.random().toString(36).slice(2),
+): Pseudonymizer {
+  const cache = new Map<string, string>();
+
+  return (value, kind) => {
+    const cacheKey = `${kind}${value}`;
+    const cached = cache.get(cacheKey);
+    if (cached !== undefined) return cached;
+
+    const seed = hash32(`${salt}${kind}${value.toLowerCase()}`);
+    // Name tokens map per TOKEN, not per whole value, so `first_name`,
+    // `last_name` and `full_name` in one row still compose into a single
+    // consistent person rather than three unrelated ones.
+    const givenFor = (token: string) =>
+      pick(FIRST_NAMES, hash32(`${salt} person_given ${token.toLowerCase()}`));
+    const familyFor = (token: string) =>
+      pick(LAST_NAMES, hash32(`${salt} person_family ${token.toLowerCase()}`));
+
+    const tokens = value.trim().split(/\s+/);
+    const first = givenFor(tokens[0] ?? value);
+    const last = familyFor(tokens[tokens.length - 1] ?? value);
+
+    let replaced: string;
+    switch (kind) {
+      case 'email': {
+        // The domain survives. It is a company, not a person, and it is what
+        // makes a captured sheet still read as "twelve people at four
+        // companies" rather than as noise.
+        //
+        // The local part is rebuilt from ITS OWN name tokens, through the same
+        // per-token mapping the name columns use, so `steven.wilhelm@acme.com`
+        // lands on the same invented person as the `first_name` and
+        // `last_name` beside it. Otherwise a row reads as a mix-up rather than
+        // as a person, which is precisely what a reviewer notices.
+        const at = value.lastIndexOf('@');
+        const domain = value.slice(at + 1);
+        const localTokens = nameTokensOf(value.slice(0, at));
+        replaced = `${givenFor(localTokens[0]).toLowerCase()}.${familyFor(
+          localTokens[localTokens.length - 1],
+        ).toLowerCase()}@${domain}`;
+        break;
+      }
+      case 'linkedin': {
+        // Same reasoning as the email: the slug carries the person's name, so
+        // map its tokens rather than inventing an unrelated one.
+        const slug = value.replace(/\/+$/, '').split('/in/')[1] ?? value;
+        const slugTokens = nameTokensOf(slug);
+        replaced = `https://www.linkedin.com/in/${givenFor(
+          slugTokens[0],
+        ).toLowerCase()}-${familyFor(
+          slugTokens[slugTokens.length - 1],
+        ).toLowerCase()}-${(seed % 900000) + 100000}`;
+        break;
+      }
+      case 'phone': {
+        // Keep the shape — length and punctuation drive column width, which is
+        // half of what a table review is actually looking at.
+        let digitIndex = 0;
+        const digits = String(1000000000 + (seed % 899999999));
+        replaced = value.replace(/\d/g, () => {
+          const next = digits[digitIndex % digits.length]!;
+          digitIndex += 1;
+          return next;
+        });
+        break;
+      }
+      case 'person_name':
+        replaced = tokens.length === 1 ? first : `${first} ${last}`;
+        break;
+      case 'person_given':
+        replaced = first;
+        break;
+      case 'person_family':
+        replaced = last;
+        break;
+    }
+
+    cache.set(cacheKey, replaced);
+    return replaced;
+  };
+}
+
+/**
+ * Classify a single cell. Column name is a hint, not the decision: a column
+ * called `owner` holding `"Acme Holdings LLC"` is a company, and a column
+ * called `contact` holding an address is an email wherever it sits.
+ */
+export function classifyValue(
+  column: string,
+  value: unknown,
+): RedactedValueKind | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (trimmed === '') return null;
+
+  if (EMAIL_RE.test(trimmed)) return 'email';
+  if (LINKEDIN_RE.test(trimmed)) return 'linkedin';
+  if (PHONE_RE.test(trimmed) && /\d{7}/.test(trimmed.replace(/\D/g, ''))) {
+    return 'phone';
+  }
+  // A corporate suffix settles it before the column name gets a say: a value
+  // like "Mears Group, Inc." is an organisation wherever it sits.
+  if (COMPANY_SUFFIX_RE.test(trimmed)) return null;
+
+  // Single-token columns accept a single token; whole-name columns still
+  // require at least two, so a bare company in an `owner` column stays put.
+  if (GIVEN_NAME_COLUMN_RE.test(column) && SINGLE_NAME_RE.test(trimmed)) {
+    return 'person_given';
+  }
+  if (FAMILY_NAME_COLUMN_RE.test(column) && SINGLE_NAME_RE.test(trimmed)) {
+    return 'person_family';
+  }
+  if (PERSON_NAME_COLUMN_RE.test(column) && FULL_NAME_RE.test(trimmed)) {
+    return 'person_name';
+  }
+  return null;
+}
+
+/**
+ * Redact one value, however deeply it is buried.
+ *
+ * Play sheets routinely carry a JSON blob in a single cell — a provider's raw
+ * response, an evaluation record — and the first capture of a real workspace
+ * leaked a LinkedIn URL exactly that way: the cell was a *string*, so a
+ * top-level check saw one long opaque value and passed it through while the
+ * personal data sat one `JSON.parse` below it. Objects, arrays and
+ * JSON-in-a-string are all walked, and a JSON string is re-serialised so the
+ * cell keeps the shape the grid renders.
+ */
+function redactValue(
+  column: string,
+  value: unknown,
+  pseudonymize: Pseudonymizer,
+): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(column, item, pseudonymize));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, nested]) => [
+        key,
+        redactValue(key, nested, pseudonymize),
+      ]),
+    );
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (
+      (trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+      (trimmed.startsWith('[') && trimmed.endsWith(']'))
+    ) {
+      try {
+        const parsed: unknown = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object') {
+          return JSON.stringify(redactValue(column, parsed, pseudonymize));
+        }
+      } catch {
+        // Not JSON after all — a cell that merely starts with a brace. Fall
+        // through and treat it as the plain string it is.
+      }
+    }
+    const kind = classifyValue(column, value);
+    if (kind) return pseudonymize(value, kind);
+    // Not a personal value on its own — but it may still CONTAIN one. Log
+    // lines, result summaries and Play source all carry addresses inline.
+    return redactFreeText(value, pseudonymize);
+  }
+  return value;
+}
+
+/** Rewrite every email and LinkedIn URL found inside a block of text. */
+export function redactFreeText(
+  text: string,
+  pseudonymize: Pseudonymizer,
+): string {
+  return text
+    .replace(EMAIL_IN_TEXT, (match) => pseudonymize(match, 'email'))
+    .replace(LINKEDIN_IN_TEXT, (match) => pseudonymize(match, 'linkedin'));
+}
+
+function redactRow(
+  row: Record<string, unknown>,
+  pseudonymize: Pseudonymizer,
+): Record<string, unknown> {
+  return redactValue('', row, pseudonymize) as Record<string, unknown>;
+}
+
+/**
+ * Rewrite every personal value in a bundle, in place of the originals.
+ *
+ * This runs at CAPTURE time, before the bundle is ever written to disk or
+ * pushed to R2 — so the raw values exist only in the capturing process's
+ * memory. Redacting after the fact would mean a raw artifact had already
+ * existed somewhere, which is the thing worth avoiding.
+ */
+export function redactWorkspaceBundle(
+  bundle: WorkspaceBundle,
+  pseudonymize: Pseudonymizer = createPseudonymizer(),
+): WorkspaceBundle {
+  const text = (value: string) => redactFreeText(value, pseudonymize);
+  const blob = <T>(value: T): T => redactValue('', value, pseudonymize) as T;
+
+  return {
+    ...bundle,
+    redaction: { mode: 'pseudonymized', kinds: REDACTED_VALUE_KINDS },
+    // Plays: a description or a hardcoded literal in the source routinely
+    // names a real prospect. The source stays valid — an address is replaced
+    // by an address.
+    plays: bundle.plays.map((play) => ({
+      ...play,
+      description: text(play.description),
+      sourceCode: text(play.sourceCode),
+      staticPipeline: blob(play.staticPipeline),
+    })),
+    // Runs: logs and result summaries are where a real capture leaked most.
+    // They are prose about the rows the Play touched, so they name them.
+    runs: bundle.runs.map((run) => ({
+      ...run,
+      logs: run.logs.map(text),
+      inputSummary: blob(run.inputSummary),
+      ...(run.result ? { result: blob(run.result) } : {}),
+      ...(run.resultSummary ? { resultSummary: blob(run.resultSummary) } : {}),
+      ...(run.error ? { error: text(run.error) } : {}),
+    })),
+    sheets: bundle.sheets.map((sheet) => ({
+      ...sheet,
+      rows: sheet.rows.map((row) => {
+        const redacted = redactRow(row, pseudonymize);
+        // The row key is an identity, not a value, and the sheet's own
+        // contract keys off it. Rewriting it would break row updates.
+        redacted.__deeplineRowKey = row.__deeplineRowKey;
+        return redacted as BundleSheet['rows'][number];
+      }),
+    })),
+    monitorEvents: bundle.monitorEvents.map((event) => ({
+      ...event,
+      payload: redactRow(event.payload, pseudonymize),
+    })),
+    monitors: bundle.monitors.map((monitor) => ({
+      ...monitor,
+      payload: blob(monitor.payload),
+      outputs: blob(monitor.outputs),
+      subjectValue: text(monitor.subjectValue),
+      subjectLabel: text(monitor.subjectLabel),
+      // `searchText` is a flattened concatenation of the fields above it, so it
+      // leaks whatever they held. Recompute rather than redact.
+      searchText: [monitor.name, monitor.subjectLabel, monitor.signalLabel]
+        .filter(Boolean)
+        .join(' ')
+        .toLowerCase(),
+      publicPreview: redactRow(monitor.publicPreview, pseudonymize),
+    })),
+  };
+}
+
+export class WorkspaceBundleFormatError extends Error {}
+
+function requireArray(value: unknown, field: string): unknown[] {
+  if (!Array.isArray(value)) {
+    throw new WorkspaceBundleFormatError(
+      `workspace bundle field "${field}" must be an array, got ${typeof value}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Validate an untrusted bundle.
+ *
+ * A bundle arrives from R2 and is fed to mutations that write a workspace, so
+ * it is untrusted input even when we wrote it ourselves — a stale object under
+ * a reused key is the ordinary case, not the exotic one. Fails loudly and
+ * names the field; never repairs, defaults, or drops a malformed record.
+ */
+export function parseWorkspaceBundle(input: unknown): WorkspaceBundle {
+  if (typeof input !== 'object' || input === null) {
+    throw new WorkspaceBundleFormatError(
+      `workspace bundle must be an object, got ${input === null ? 'null' : typeof input}`,
+    );
+  }
+  const raw = input as Record<string, unknown>;
+
+  if (raw.apiVersion !== WORKSPACE_BUNDLE_API_VERSION) {
+    throw new WorkspaceBundleFormatError(
+      `unsupported workspace bundle apiVersion ${JSON.stringify(raw.apiVersion)}; this build reads ${WORKSPACE_BUNDLE_API_VERSION}`,
+    );
+  }
+
+  const redaction = raw.redaction as WorkspaceBundle['redaction'] | undefined;
+  if (
+    !redaction ||
+    (redaction.mode !== 'pseudonymized' && redaction.mode !== 'raw')
+  ) {
+    throw new WorkspaceBundleFormatError(
+      'workspace bundle is missing a redaction mode; refusing to load data whose handling is unstated',
+    );
+  }
+
+  const bundle: WorkspaceBundle = {
+    apiVersion: WORKSPACE_BUNDLE_API_VERSION,
+    capturedAt: typeof raw.capturedAt === 'string' ? raw.capturedAt : '',
+    source: { label: String((raw.source as { label?: unknown })?.label ?? '') },
+    redaction,
+    plays: requireArray(raw.plays, 'plays') as BundlePlay[],
+    runs: requireArray(raw.runs, 'runs') as BundleRun[],
+    sheets: requireArray(raw.sheets, 'sheets') as BundleSheet[],
+    monitors: requireArray(raw.monitors, 'monitors') as BundleMonitor[],
+    monitorEvents: requireArray(
+      raw.monitorEvents,
+      'monitorEvents',
+    ) as BundleMonitorEvent[],
+  };
+
+  // Referential integrity: a run or sheet naming a play the bundle does not
+  // carry would seed a workspace whose feed rows open onto nothing.
+  const playNames = new Set(bundle.plays.map((play) => play.name));
+  for (const run of bundle.runs) {
+    if (!playNames.has(run.playName)) {
+      throw new WorkspaceBundleFormatError(
+        `run ${JSON.stringify(run.key)} names play ${JSON.stringify(run.playName)}, which the bundle does not carry`,
+      );
+    }
+  }
+  const runKeys = new Set(bundle.runs.map((run) => run.key));
+  for (const sheet of bundle.sheets) {
+    if (!playNames.has(sheet.playName)) {
+      throw new WorkspaceBundleFormatError(
+        `sheet for namespace ${JSON.stringify(sheet.tableNamespace)} names play ${JSON.stringify(sheet.playName)}, which the bundle does not carry`,
+      );
+    }
+    if (!runKeys.has(sheet.runKey)) {
+      throw new WorkspaceBundleFormatError(
+        `sheet for namespace ${JSON.stringify(sheet.tableNamespace)} names run ${JSON.stringify(sheet.runKey)}, which the bundle does not carry`,
+      );
+    }
+  }
+  const monitorKeys = new Set(
+    bundle.monitors.map((monitor) => monitor.monitorKey),
+  );
+  for (const event of bundle.monitorEvents) {
+    if (!monitorKeys.has(event.monitorKey)) {
+      throw new WorkspaceBundleFormatError(
+        `monitor event names monitor ${JSON.stringify(event.monitorKey)}, which the bundle does not carry`,
+      );
+    }
+  }
+
+  return bundle;
+}
+
+/** Counts for an operator to eyeball before pushing or loading. */
+export function summarizeWorkspaceBundle(bundle: WorkspaceBundle): string {
+  const rows = bundle.sheets.reduce(
+    (total, sheet) => total + sheet.rows.length,
+    0,
+  );
+  return [
+    `${bundle.plays.length} plays`,
+    `${bundle.runs.length} runs`,
+    `${bundle.sheets.length} sheets / ${rows} rows`,
+    `${bundle.monitors.length} monitors`,
+    `${bundle.monitorEvents.length} monitor events`,
+    bundle.redaction.mode,
+  ].join(' · ');
+}