@superblocksteam/shared 0.9617.8 → 0.9618.1

package/src/database-lifecycle/dataImport.ts

@@ -13,6 +13,8 @@ export const DATA_IMPORT_STATES = [
   'validating',
   'validating_schema',
   'schema_validated',
+  'capturing_source',
+  'restoring',
   'ready',
   'importing',
   'completed',
@@ -60,19 +62,51 @@ export type DataImportUploadMetadata = {
 // signed URLs, credentials, ETags, and row samples stay out.
 export type PgDumpDataImportMetadata = {
   kind: 'pg_dump_custom';
+  capturedObjectKey?: string;
+  capturedSha256?: string;
+  capturedSizeBytes?: number;
   currentPrefixSizeBytes?: number;
   postgresMajorVersion?: number;
   prefixChecksumSha256?: string;
   prefixObjectKey?: string;
   requestedPrefixSizeBytes?: number;
+  source?: {
+    integrationConfigurationId: string;
+    integrationId: string;
+    profile: string;
+    profileId: string;
+    type: 'integration';
+  };
   tableNames?: string[];
 };
 
+export type CsvColumnMapping = {
+  source: string;
+  target: string;
+};
+
+// Settings the table-import worker requires before it COPY-loads one CSV.
+// Absent on uploads that only store the file.
+export type CsvTableImportPlan = {
+  columnMapping: CsvColumnMapping[];
+  dateStyle: string;
+  delimiter: ',' | ';' | '\t' | '|';
+  emptyAsNull: boolean;
+  encoding: 'UTF8' | 'WINDOWS1252';
+  hasHeader: boolean;
+  timeZone: string;
+  trimWhitespace: boolean;
+};
+
 export type CsvDataImportMetadata = {
   kind: 'csv';
   mode: 'append' | 'replace';
   table: string;
-};
+} & Partial<CsvTableImportPlan>;
+
+export type CsvImportPlanParse = { message: string; status: 'invalid' } | { plan: CsvTableImportPlan; status: 'ok' };
+
+export type CsvTableImportPlanPresence = { status: 'absent' } | CsvImportPlanParse;
 
 export type DataImportMetadata = PgDumpDataImportMetadata | CsvDataImportMetadata;
 
@@ -122,14 +156,119 @@ export function parseDataImportMetadata(kind: DataImportKind, value: unknown): D
     return parsePgDumpMetadata(value);
   }
   const table = canonicalCsvTable(value.table);
-  if (table === undefined || (value.mode !== 'append' && value.mode !== 'replace')) {
+  if (table === undefined || (value.mode !== 'append' && value.mode !== 'replace') || isReservedCsvImportTable(table)) {
     return undefined;
   }
-  const allowed = new Set(['kind', 'mode', 'table']);
+  const plan = parseCsvTableImportPlanFields(value);
+  if (plan.status === 'invalid') {
+    return undefined;
+  }
+  const allowed = new Set<string>(['kind', 'mode', 'table', ...(plan.status === 'ok' ? CSV_TABLE_IMPORT_PLAN_KEYS : [])]);
   if (Object.keys(value).some((key) => !allowed.has(key))) {
     return undefined;
   }
-  return { kind: 'csv', mode: value.mode, table };
+  if (plan.status === 'absent') {
+    return { kind: 'csv', mode: value.mode, table };
+  }
+  return { kind: 'csv', mode: value.mode, table, ...plan.plan };
+}
+
+export function csvTableImportPlan(metadata: CsvDataImportMetadata): CsvTableImportPlan | undefined {
+  if (
+    metadata.columnMapping === undefined ||
+    metadata.dateStyle === undefined ||
+    metadata.delimiter === undefined ||
+    metadata.emptyAsNull === undefined ||
+    metadata.encoding === undefined ||
+    metadata.hasHeader === undefined ||
+    metadata.timeZone === undefined ||
+    metadata.trimWhitespace === undefined
+  ) {
+    return undefined;
+  }
+  return {
+    columnMapping: metadata.columnMapping,
+    dateStyle: metadata.dateStyle,
+    delimiter: metadata.delimiter,
+    emptyAsNull: metadata.emptyAsNull,
+    encoding: metadata.encoding,
+    hasHeader: metadata.hasHeader,
+    timeZone: metadata.timeZone,
+    trimWhitespace: metadata.trimWhitespace
+  };
+}
+
+// The migrations ledger and system catalogs are not import targets.
+export function isReservedCsvImportTable(table: string): boolean {
+  const separator = table.indexOf('.');
+  if (separator < 1) {
+    return false;
+  }
+  const schema = table.slice(0, separator);
+  const name = table.slice(separator + 1);
+  if (schema === 'information_schema' || schema.startsWith('pg_')) {
+    return true;
+  }
+  return schema === 'public' && name === 'superblocks_schema_migrations';
+}
+
+const CSV_DATE_FORMAT_TO_DATE_STYLE: Record<string, string> = {
+  'DD.MM.YYYY': 'German, DMY',
+  'DD/MM/YYYY': 'ISO, DMY',
+  'MM/DD/YYYY': 'ISO, MDY',
+  'YYYY-MM-DD': 'ISO, YMD'
+};
+
+// Wizard spellings become the worker's DateStyle, encoding, and column list.
+// emptyAsNull stays on, the delimiter stays a comma, and the session time zone
+// stays UTC. The first row is always a header.
+export function csvImportPlanFromWizard(input: {
+  columnMappings: Record<string, string>;
+  dateFormat: string;
+  encoding: string;
+  trimWhitespace: boolean;
+}): CsvImportPlanParse {
+  const encoding = workerCsvEncoding(input.encoding);
+  if (!encoding) {
+    return { message: 'Encoding must be UTF-8 or Windows-1252.', status: 'invalid' };
+  }
+  const dateStyle = workerDateStyle(input.dateFormat);
+  if (!dateStyle) {
+    return {
+      message: 'Date format must be YYYY-MM-DD, MM/DD/YYYY, DD/MM/YYYY, or DD.MM.YYYY.',
+      status: 'invalid'
+    };
+  }
+  const columnMapping = columnMappingsFromWizard(input.columnMappings);
+  if (columnMapping.status === 'invalid') {
+    return columnMapping;
+  }
+  return readCsvTableImportPlan({
+    columnMapping: columnMapping.mapping,
+    dateStyle,
+    delimiter: ',',
+    emptyAsNull: true,
+    encoding,
+    hasHeader: true,
+    timeZone: 'UTC',
+    trimWhitespace: input.trimWhitespace
+  });
+}
+
+export function parseCsvTableImportPlanFields(value: Record<string, unknown>): CsvTableImportPlanPresence {
+  if (!CSV_TABLE_IMPORT_PLAN_KEYS.some((key) => value[key] !== undefined)) {
+    return { status: 'absent' };
+  }
+  return readCsvTableImportPlan({
+    columnMapping: value.columnMapping,
+    dateStyle: value.dateStyle,
+    delimiter: value.delimiter,
+    emptyAsNull: value.emptyAsNull,
+    encoding: value.encoding,
+    hasHeader: value.hasHeader,
+    timeZone: value.timeZone,
+    trimWhitespace: value.trimWhitespace
+  });
 }
 
 export function parseDataImportOutcome(value: unknown): DataImportOutcome | undefined {
@@ -235,6 +374,130 @@ function assignOptionalInteger(
   return true;
 }
 
+const CSV_TABLE_IMPORT_PLAN_KEYS = [
+  'columnMapping',
+  'dateStyle',
+  'delimiter',
+  'emptyAsNull',
+  'encoding',
+  'hasHeader',
+  'timeZone',
+  'trimWhitespace'
+] as const;
+
+const CSV_DATE_STYLE = /^(ISO|SQL|Postgres|German)(, (MDY|DMY|YMD))?$/;
+const CSV_TIME_ZONE = /^[A-Za-z0-9_+-]{1,64}(?:\/[A-Za-z0-9_+-]{1,64}){0,2}$/;
+const CSV_TARGET_COLUMN = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+const CSV_DELIMITERS = [',', ';', '\t', '|'] as const;
+
+function workerCsvEncoding(value: string): 'UTF8' | 'WINDOWS1252' | undefined {
+  const normalized = value.trim().toUpperCase().replace(/-/g, '');
+  if (normalized === 'UTF8') {
+    return 'UTF8';
+  }
+  if (normalized === 'WINDOWS1252' || normalized === 'CP1252') {
+    return 'WINDOWS1252';
+  }
+  return undefined;
+}
+
+function workerDateStyle(value: string): string | undefined {
+  const trimmed = value.trim();
+  return CSV_DATE_FORMAT_TO_DATE_STYLE[trimmed] ?? (CSV_DATE_STYLE.test(trimmed) ? trimmed : undefined);
+}
+
+function columnMappingsFromWizard(
+  mappings: Record<string, string>
+): { mapping: CsvColumnMapping[]; status: 'ok' } | { message: string; status: 'invalid' } {
+  const columnMapping: CsvColumnMapping[] = [];
+  const targets = new Set<string>();
+  for (const [source, target] of Object.entries(mappings)) {
+    const trimmedTarget = target.trim();
+    if (trimmedTarget.length === 0) {
+      continue;
+    }
+    const trimmedSource = source.trim();
+    if (trimmedSource.length === 0 || trimmedSource.length > 256) {
+      return { message: 'CSV column names must be 1 to 256 characters.', status: 'invalid' };
+    }
+    if (!CSV_TARGET_COLUMN.test(trimmedTarget)) {
+      return { message: 'Table column names must be identifiers.', status: 'invalid' };
+    }
+    const folded = trimmedTarget.toLowerCase();
+    if (targets.has(folded)) {
+      return { message: 'Each table column can only be mapped once.', status: 'invalid' };
+    }
+    targets.add(folded);
+    columnMapping.push({ source: trimmedSource, target: trimmedTarget });
+  }
+  columnMapping.sort((left, right) => (left.source < right.source ? -1 : left.source > right.source ? 1 : 0));
+  if (columnMapping.length === 0) {
+    return { message: 'Map at least one CSV column to a table column.', status: 'invalid' };
+  }
+  return { mapping: columnMapping, status: 'ok' };
+}
+
+function readCsvTableImportPlan(value: {
+  columnMapping: unknown;
+  dateStyle: unknown;
+  delimiter: unknown;
+  emptyAsNull: unknown;
+  encoding: unknown;
+  hasHeader: unknown;
+  timeZone: unknown;
+  trimWhitespace: unknown;
+}): CsvImportPlanParse {
+  if (!Array.isArray(value.columnMapping) || value.columnMapping.length === 0) {
+    return { message: 'Map at least one CSV column to a table column.', status: 'invalid' };
+  }
+  const columnMapping: CsvColumnMapping[] = [];
+  const targets = new Set<string>();
+  for (const entry of value.columnMapping) {
+    if (!isUnknownRecord(entry) || typeof entry.source !== 'string' || typeof entry.target !== 'string') {
+      return { message: 'CSV import settings are incomplete or not supported.', status: 'invalid' };
+    }
+    const source = entry.source.trim();
+    const target = entry.target.trim();
+    if (source.length === 0 || source.length > 256 || !CSV_TARGET_COLUMN.test(target)) {
+      return { message: 'CSV import settings are incomplete or not supported.', status: 'invalid' };
+    }
+    const folded = target.toLowerCase();
+    if (targets.has(folded)) {
+      return { message: 'Each table column can only be mapped once.', status: 'invalid' };
+    }
+    targets.add(folded);
+    columnMapping.push({ source, target });
+  }
+  if (typeof value.dateStyle !== 'string' || !CSV_DATE_STYLE.test(value.dateStyle)) {
+    return { message: 'Date format must be YYYY-MM-DD, MM/DD/YYYY, DD/MM/YYYY, or DD.MM.YYYY.', status: 'invalid' };
+  }
+  if (typeof value.delimiter !== 'string' || !CSV_DELIMITERS.includes(value.delimiter as (typeof CSV_DELIMITERS)[number])) {
+    return { message: 'CSV import settings are incomplete or not supported.', status: 'invalid' };
+  }
+  if (value.encoding !== 'UTF8' && value.encoding !== 'WINDOWS1252') {
+    return { message: 'Encoding must be UTF-8 or Windows-1252.', status: 'invalid' };
+  }
+  if (typeof value.timeZone !== 'string' || !CSV_TIME_ZONE.test(value.timeZone)) {
+    return { message: 'CSV import settings are incomplete or not supported.', status: 'invalid' };
+  }
+  if (typeof value.emptyAsNull !== 'boolean' || typeof value.hasHeader !== 'boolean' || typeof value.trimWhitespace !== 'boolean') {
+    return { message: 'CSV import settings are incomplete or not supported.', status: 'invalid' };
+  }
+  return {
+    plan: {
+      columnMapping,
+      dateStyle: value.dateStyle,
+      delimiter: value.delimiter as CsvTableImportPlan['delimiter'],
+      emptyAsNull: value.emptyAsNull,
+      encoding: value.encoding,
+      hasHeader: value.hasHeader,
+      timeZone: value.timeZone,
+      trimWhitespace: value.trimWhitespace
+    },
+    status: 'ok'
+  };
+}
+
 function isDecimalCount(value: unknown): value is string {
   return typeof value === 'string' && /^(0|[1-9][0-9]*)$/.test(value);
 }

package/src/database-lifecycle/importCompatibility.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest';
+
+import { AgentStatus } from '../types/organization/agent.js';
+import { DATABASE_LIFECYCLE_TAG_IMPORT_TRANSFORMS, evaluateAppDatabaseImportTag } from './importCompatibility.js';
+
+const IMPORT_OPERATIONS = ['complete_import_upload', 'describe_schema', 'import_table_data', 'prepare_import_upload'];
+
+function agent({
+  agentName,
+  operations = IMPORT_OPERATIONS,
+  profiles = ['production'],
+  status = AgentStatus.ACTIVE,
+  transforms = ['empty_as_null', 'trim_whitespace']
+}: {
+  agentName?: string;
+  operations?: string[];
+  profiles?: string[];
+  status?: AgentStatus | string;
+  transforms?: string[];
+} = {}) {
+  return {
+    status,
+    tags: {
+      ...(agentName === undefined ? {} : { 'databaseLifecycle:agentName': [agentName] }),
+      'databaseLifecycle:operations': operations,
+      [DATABASE_LIFECYCLE_TAG_IMPORT_TRANSFORMS]: transforms,
+      profile: profiles
+    }
+  };
+}
+
+describe('evaluateAppDatabaseImportTag', () => {
+  it('offers import and every advertised transform when one agent can run it', () => {
+    expect(evaluateAppDatabaseImportTag({ agents: [agent()], profileKey: 'production' })).toEqual({
+      availableTransforms: ['empty_as_null', 'trim_whitespace'],
+      missingOperations: [],
+      profileKey: 'production',
+      reason: '',
+      supportState: 'supported'
+    });
+  });
+
+  it('ignores a worker that does not own the data tag', () => {
+    const support = evaluateAppDatabaseImportTag({
+      agentName: 'owner',
+      agents: [agent({ agentName: 'other' }), agent({ agentName: 'owner', operations: ['describe_schema'] })],
+      profileKey: 'production'
+    });
+
+    expect(support.supportState).toBe('unsupported');
+    expect(support.missingOperations).toEqual(['complete_import_upload', 'import_table_data', 'prepare_import_upload']);
+  });
+
+  it('keeps a transform the owner advertises when another worker omits it', () => {
+    const support = evaluateAppDatabaseImportTag({
+      agentName: 'owner',
+      agents: [agent({ agentName: 'other', transforms: ['empty_as_null'] }), agent({ agentName: 'owner' })],
+      profileKey: 'production'
+    });
+
+    expect(support.supportState).toBe('supported');
+    expect(support.availableTransforms).toEqual(['empty_as_null', 'trim_whitespace']);
+  });
+
+  it('waits when the owning worker is not connected', () => {
+    const support = evaluateAppDatabaseImportTag({
+      agentName: 'owner',
+      agents: [agent({ agentName: 'other' })],
+      profileKey: 'production'
+    });
+
+    expect(support.supportState).toBe('temporarily_unavailable');
+    expect(support.reason).toContain('Its worker is not connected');
+  });
+
+  it('disables CSV when the worker does not advertise empty_as_null', () => {
+    const support = evaluateAppDatabaseImportTag({
+      agents: [agent({ transforms: ['trim_whitespace'] })],
+      profileKey: 'production'
+    });
+
+    expect(support.supportState).toBe('unsupported');
+    expect(support.availableTransforms).toEqual([]);
+    expect(support.reason).toContain('empty_as_null');
+  });
+
+  it('omits trim when a replica that can claim the import does not advertise it', () => {
+    const support = evaluateAppDatabaseImportTag({
+      agentName: 'owner',
+      agents: [
+        agent({ agentName: 'owner' }),
+        agent({
+          agentName: 'owner',
+          operations: ['import_table_data'],
+          transforms: ['empty_as_null']
+        })
+      ],
+      profileKey: 'production'
+    });
+
+    expect(support.supportState).toBe('supported');
+    expect(support.availableTransforms).toEqual(['empty_as_null']);
+  });
+
+  it('disables CSV when a replica that can claim the import omits empty_as_null', () => {
+    const support = evaluateAppDatabaseImportTag({
+      agentName: 'owner',
+      agents: [agent({ agentName: 'owner' }), agent({ agentName: 'owner', operations: ['import_table_data'], transforms: [] })],
+      profileKey: 'production'
+    });
+
+    expect(support.supportState).toBe('unsupported');
+    expect(support.availableTransforms).toEqual([]);
+    expect(support.reason).toContain('empty_as_null');
+  });
+
+  it('leaves out a transform that any capable agent does not advertise', () => {
+    const support = evaluateAppDatabaseImportTag({
+      agents: [agent(), agent({ transforms: ['empty_as_null'] })],
+      profileKey: 'production'
+    });
+
+    expect(support.supportState).toBe('supported');
+    expect(support.availableTransforms).toEqual(['empty_as_null']);
+  });
+
+  it('disables a tag whose connected agent is missing an import operation', () => {
+    const support = evaluateAppDatabaseImportTag({
+      agents: [agent({ operations: ['describe_schema', 'ensure_database', 'migrate_schema', 'prepare_import_upload'] })],
+      profileKey: 'production'
+    });
+
+    expect(support.supportState).toBe('unsupported');
+    expect(support.missingOperations).toEqual(['complete_import_upload', 'import_table_data']);
+    expect(support.reason).toContain('does not advertise the import operations');
+    expect(support.availableTransforms).toEqual([]);
+  });
+
+  it('reports that the check could not tell when no agent is connected', () => {
+    expect(evaluateAppDatabaseImportTag({ agents: undefined, profileKey: 'production' }).supportState).toBe('temporarily_unavailable');
+    expect(evaluateAppDatabaseImportTag({ agents: [], profileKey: 'production' }).supportState).toBe('temporarily_unavailable');
+    expect(
+      evaluateAppDatabaseImportTag({ agents: [agent({ status: AgentStatus.DISCONNECTED })], profileKey: 'production' }).supportState
+    ).toBe('temporarily_unavailable');
+  });
+});

package/src/database-lifecycle/importCompatibility.ts

@@ -0,0 +1,148 @@
+import { AgentStatus } from '../types/organization/agent.js';
+import type { AppDatabaseTagSupportState } from './appDatabaseCompatibility.js';
+import type { AgentLifecycleTagSource } from './edit-lifecycle-capability.js';
+import { DATABASE_LIFECYCLE_TAG_AGENT_NAME } from './physicalPoolIdentity.js';
+
+export const DATABASE_LIFECYCLE_TAG_IMPORT_TRANSFORMS = 'databaseLifecycle:importTransforms';
+
+/**
+ * Operations a data tag needs before CSV import can be offered.
+ *
+ * Kept off {@link APP_DATABASE_REQUIRED_OPERATIONS}. Missing one of these
+ * disables import. It must not make the app undeployable.
+ */
+export const APP_DATABASE_IMPORT_REQUIRED_OPERATIONS = ['complete_import_upload', 'import_table_data', 'prepare_import_upload'] as const;
+
+export const APP_DATABASE_IMPORT_TRANSFORMS = ['empty_as_null', 'trim_whitespace'] as const;
+export type AppDatabaseImportTransform = (typeof APP_DATABASE_IMPORT_TRANSFORMS)[number];
+
+export type AppDatabaseImportTagSupport = {
+  availableTransforms: AppDatabaseImportTransform[];
+  missingOperations: string[];
+  profileKey: string;
+  reason: string;
+  supportState: AppDatabaseTagSupportState;
+};
+
+const IMPORT_UNAVAILABLE_REASON =
+  'CSV import is not available for this data tag. The connected agent does not advertise the import operations.';
+const IMPORT_EMPTY_AS_NULL_REASON = 'CSV import is not available for this data tag. The connected agent does not advertise empty_as_null.';
+const IMPORT_OWNER_DISCONNECTED_REASON = 'CSV import is not available for this data tag. Its worker is not connected.';
+const IMPORT_UNKNOWN_REASON = 'CSV import could not be checked. No connected agent has published its capabilities.';
+
+/**
+ * Whether one data tag can accept a CSV import, from the agents connected now.
+ *
+ * `unsupported` is a standing gap. `temporarily_unavailable` means nothing
+ * connected could be read, so the tag may start working without an app change.
+ * When `agentName` is set, only the worker that owns the binding counts.
+ * Replicas that publish that same name stay together. Schema description is an
+ * HTTP route, so `describe_schema` is not required here.
+ *
+ * The wizard always sends `empty_as_null`. CSV stays off unless every replica
+ * that can claim `import_table_data` advertises it. Optional transforms are
+ * the intersection of those same replicas, including one that can claim the
+ * copy while missing an upload operation. The server only hands a replica a
+ * dispatch for an operation it advertises.
+ */
+export function evaluateAppDatabaseImportTag({
+  agentName,
+  agents,
+  profileKey
+}: {
+  agentName?: string | null;
+  agents: readonly AgentLifecycleTagSource[] | undefined;
+  profileKey: string;
+}): AppDatabaseImportTagSupport {
+  const active = (agents ?? []).filter(isActiveAgent);
+  if (agents === undefined || active.length === 0) {
+    return {
+      availableTransforms: [],
+      missingOperations: [...APP_DATABASE_IMPORT_REQUIRED_OPERATIONS],
+      profileKey,
+      reason: IMPORT_UNKNOWN_REASON,
+      supportState: 'temporarily_unavailable'
+    };
+  }
+  const owner = agentName?.trim() ?? '';
+  const counted = owner === '' ? active : active.filter((agent) => publishesAgentName(agent, owner));
+  if (owner !== '' && counted.length === 0) {
+    return {
+      availableTransforms: [],
+      missingOperations: [...APP_DATABASE_IMPORT_REQUIRED_OPERATIONS],
+      profileKey,
+      reason: IMPORT_OWNER_DISCONNECTED_REASON,
+      supportState: 'temporarily_unavailable'
+    };
+  }
+  const covering = counted.filter((agent) => coversProfile(agent, profileKey));
+  const claimants = covering.filter((agent) => publishedOperations(agent).includes('import_table_data'));
+  const capable = claimants.filter((agent) => missingOperations(agent).length === 0);
+  if (capable.length === 0) {
+    const missing = covering.length === 0 ? [...APP_DATABASE_IMPORT_REQUIRED_OPERATIONS] : missingAcross(covering);
+    return {
+      availableTransforms: [],
+      missingOperations: missing,
+      profileKey,
+      reason: IMPORT_UNAVAILABLE_REASON,
+      supportState: 'unsupported'
+    };
+  }
+  const availableTransforms = transformsInCommon(claimants);
+  if (!availableTransforms.includes('empty_as_null')) {
+    return {
+      availableTransforms: [],
+      missingOperations: [],
+      profileKey,
+      reason: IMPORT_EMPTY_AS_NULL_REASON,
+      supportState: 'unsupported'
+    };
+  }
+  return {
+    availableTransforms,
+    missingOperations: [],
+    profileKey,
+    reason: '',
+    supportState: 'supported'
+  };
+}
+
+function isActiveAgent(agent: AgentLifecycleTagSource): boolean {
+  return agent.status === AgentStatus.ACTIVE || agent.status === 'Active';
+}
+
+function publishesAgentName(agent: AgentLifecycleTagSource, agentName: string): boolean {
+  return (agent.tags?.[DATABASE_LIFECYCLE_TAG_AGENT_NAME] ?? []).includes(agentName);
+}
+
+function coversProfile(agent: AgentLifecycleTagSource, profileKey: string): boolean {
+  const profiles = agent.tags?.profile ?? [];
+  return profiles.includes('*') || profiles.includes(profileKey);
+}
+
+function publishedOperations(agent: AgentLifecycleTagSource): readonly string[] {
+  return agent.tags?.['databaseLifecycle:operations'] ?? [];
+}
+
+function missingOperations(agent: AgentLifecycleTagSource): string[] {
+  const operations = publishedOperations(agent);
+  return APP_DATABASE_IMPORT_REQUIRED_OPERATIONS.filter((operation) => !operations.includes(operation));
+}
+
+function missingAcross(agents: readonly AgentLifecycleTagSource[]): string[] {
+  const lists = agents.map(missingOperations).sort((left, right) => left.length - right.length || left.join().localeCompare(right.join()));
+  return lists[0] ?? [...APP_DATABASE_IMPORT_REQUIRED_OPERATIONS];
+}
+
+function transformsInCommon(agents: readonly AgentLifecycleTagSource[]): AppDatabaseImportTransform[] {
+  const counts = new Map<AppDatabaseImportTransform, number>();
+  for (const agent of agents) {
+    const advertised = new Set(agent.tags?.[DATABASE_LIFECYCLE_TAG_IMPORT_TRANSFORMS] ?? []);
+    for (const transform of APP_DATABASE_IMPORT_TRANSFORMS) {
+      if (advertised.has(transform)) {
+        counts.set(transform, (counts.get(transform) ?? 0) + 1);
+      }
+    }
+  }
+  return APP_DATABASE_IMPORT_TRANSFORMS.filter((transform) => counts.get(transform) === agents.length);
+}

package/src/database-lifecycle/index.test.ts

@@ -33,8 +33,11 @@ describe('database lifecycle contracts', () => {
       'complete_import_upload',
       'prepare_import_prefix_upload',
       'inspect_import_prefix',
+      'capture_integration_pg_dump',
+      'restore_integration_pg_dump',
       'restore_import_data',
-      'describe_schema'
+      'describe_schema',
+      'import_table_data'
     ]);
   });