@superblocksteam/shared 0.9617.8 → 0.9618.1

package/src/database-lifecycle/appDatabaseImport.ts

@@ -1,6 +1,12 @@
 import type { DataImportKind, DataImportState } from './dataImport.js';
 
-export const APP_DATABASE_IMPORT_OPERATIONS = ['prepare_import_prefix_upload', 'inspect_import_prefix', 'restore_import_data'] as const;
+export const APP_DATABASE_IMPORT_OPERATIONS = [
+  'prepare_import_prefix_upload',
+  'inspect_import_prefix',
+  'capture_integration_pg_dump',
+  'restore_integration_pg_dump',
+  'restore_import_data'
+] as const;
 // Subset of DATA_IMPORT_STATES. Prefix success is schema_validated, not ready.
 export const APP_DATABASE_IMPORT_STATES = [
   'requested',
@@ -8,7 +14,10 @@ export const APP_DATABASE_IMPORT_STATES = [
   'awaiting_prefix_upload',
   'validating_schema',
   'schema_validated',
+  'capturing_source',
+  'restoring',
   'uploading',
+  'upload_completed',
   'importing',
   'completed',
   'failed',
@@ -26,6 +35,13 @@ export const APP_DATABASE_IMPORT_ERROR_CODES = [
   'internal',
   'invalid_input',
   'size_mismatch',
+  'source_connection_failed',
+  'source_dump_failed',
+  'source_integration_forbidden',
+  'source_integration_not_found',
+  'source_integration_unsupported',
+  'source_profile_unavailable',
+  'source_worker_mismatch',
   'checksum_mismatch',
   'commit_uncertain',
   'stream_failed',
@@ -45,11 +61,18 @@ export type AppDatabaseImportValidationMetadata = {
 export type AppDatabaseImportDispatchDetails = {
   importId: string;
   kind: AppDatabaseImportKind;
-  prefixSizeBytes: number;
   profileToken: string;
   resourceToken: string;
 };
 
+export type AppDatabaseImportSource = {
+  integrationConfigurationId: string;
+  integrationId: string;
+  profile: string;
+  profileId: string;
+  type: 'integration';
+};
+
 type AppDatabaseImportDispatchBase<TDesiredSpec> = {
   applicationId: string;
   bindingId: string;
@@ -71,17 +94,35 @@ type AppDatabaseImportDispatchBase<TDesiredSpec> = {
 export type PrepareImportPrefixUploadDispatchPayloadEnvelope<TDesiredSpec> = AppDatabaseImportDispatchBase<TDesiredSpec> & {
   import: AppDatabaseImportDispatchDetails & {
     expectedSizeBytes: number;
+    prefixSizeBytes: number;
   };
   operation: 'prepare_import_prefix_upload';
 };
 
 export type InspectImportPrefixDispatchPayloadEnvelope<TDesiredSpec> = AppDatabaseImportDispatchBase<TDesiredSpec> & {
   import: AppDatabaseImportDispatchDetails & {
+    prefixSizeBytes: number;
     prefixObjectKey: string;
   };
   operation: 'inspect_import_prefix';
 };
 
+export type CaptureIntegrationPgDumpDispatchPayloadEnvelope<TDesiredSpec> = AppDatabaseImportDispatchBase<TDesiredSpec> & {
+  import: AppDatabaseImportDispatchDetails & {
+    source: AppDatabaseImportSource;
+  };
+  operation: 'capture_integration_pg_dump';
+};
+
+export type RestoreIntegrationPgDumpDispatchPayloadEnvelope<TDesiredSpec> = AppDatabaseImportDispatchBase<TDesiredSpec> & {
+  import: AppDatabaseImportDispatchDetails & {
+    objectKey: string;
+    sha256: string;
+    sizeBytes: number;
+  };
+  operation: 'restore_integration_pg_dump';
+};
+
 export type RestoreImportDataDispatchPayloadEnvelope<TDesiredSpec> = AppDatabaseImportDispatchBase<TDesiredSpec> & {
   import: AppDatabaseImportDispatchDetails & {
     objectKey: string;
@@ -91,9 +132,11 @@ export type RestoreImportDataDispatchPayloadEnvelope<TDesiredSpec> = AppDatabase
 };
 
 export type AppDatabaseImportDispatchPayloadEnvelope<TDesiredSpec> =
+  | CaptureIntegrationPgDumpDispatchPayloadEnvelope<TDesiredSpec>
   | InspectImportPrefixDispatchPayloadEnvelope<TDesiredSpec>
   | PrepareImportPrefixUploadDispatchPayloadEnvelope<TDesiredSpec>
-  | RestoreImportDataDispatchPayloadEnvelope<TDesiredSpec>;
+  | RestoreImportDataDispatchPayloadEnvelope<TDesiredSpec>
+  | RestoreIntegrationPgDumpDispatchPayloadEnvelope<TDesiredSpec>;
 
 export type PrepareImportPrefixUploadCallbackResult = {
   prefixObjectKey: string;
@@ -114,7 +157,25 @@ export type InspectImportPrefixCallbackResult =
       validationMetadata: AppDatabaseImportValidationMetadata;
     };
 
-export type AppDatabaseImportCallbackResult = InspectImportPrefixCallbackResult | PrepareImportPrefixUploadCallbackResult;
+export type CaptureIntegrationPgDumpCallbackResult = {
+  artifact: {
+    objectKey: string;
+    sha256: string;
+    sizeBytes: number;
+  };
+  result: 'integration_pg_dump_captured';
+};
+
+export type RestoreIntegrationPgDumpCallbackResult = {
+  result: 'integration_pg_dump_restored';
+  validationMetadata: AppDatabaseImportValidationMetadata;
+};
+
+export type AppDatabaseImportCallbackResult =
+  | CaptureIntegrationPgDumpCallbackResult
+  | InspectImportPrefixCallbackResult
+  | PrepareImportPrefixUploadCallbackResult
+  | RestoreIntegrationPgDumpCallbackResult;
 
 const importOperations = new Set<string>(APP_DATABASE_IMPORT_OPERATIONS);
 
@@ -131,8 +192,26 @@ export function isAppDatabaseImportDispatchPayload(
   if (!isNonEmptyString(value.import.profileToken) || !isNonEmptyString(value.import.resourceToken)) {
     return false;
   }
+  if (value.operation === 'capture_integration_pg_dump') {
+    return (
+      hasOnlyKeys(value.import, ['importId', 'kind', 'profileToken', 'resourceToken', 'source']) &&
+      isAppDatabaseImportSource(value.import.source)
+    );
+  }
+  if (value.operation === 'restore_integration_pg_dump') {
+    return (
+      hasOnlyKeys(value.import, ['importId', 'kind', 'objectKey', 'profileToken', 'resourceToken', 'sha256', 'sizeBytes']) &&
+      isSafeObjectKey(value.import.objectKey) &&
+      isPositiveInteger(value.import.sizeBytes) &&
+      isSha256(value.import.sha256)
+    );
+  }
   if (value.operation === 'prepare_import_prefix_upload') {
-    return value.import.prefixObjectKey === undefined && isPositiveInteger(value.import.expectedSizeBytes);
+    return (
+      hasOnlyKeys(value.import, ['expectedSizeBytes', 'importId', 'kind', 'prefixSizeBytes', 'profileToken', 'resourceToken']) &&
+      isPositiveInteger(value.import.expectedSizeBytes) &&
+      isPositiveInteger(value.import.prefixSizeBytes)
+    );
   }
   if (value.operation === 'restore_import_data') {
     return (
@@ -144,7 +223,8 @@ export function isAppDatabaseImportDispatchPayload(
   }
   return (
     value.operation === 'inspect_import_prefix' &&
-    value.import.expectedSizeBytes === undefined &&
+    hasOnlyKeys(value.import, ['importId', 'kind', 'prefixObjectKey', 'prefixSizeBytes', 'profileToken', 'resourceToken']) &&
+    isPositiveInteger(value.import.prefixSizeBytes) &&
     isNonEmptyString(value.import.prefixObjectKey)
   );
 }
@@ -165,6 +245,22 @@ export function isAppDatabaseImportCallbackResult(value: unknown): value is AppD
       value.nextPrefixSizeBytes > value.inspectedPrefixSizeBytes
     );
   }
+  if (value.result === 'integration_pg_dump_captured') {
+    return (
+      hasOnlyKeys(value, ['artifact', 'result']) &&
+      isUnknownRecord(value.artifact) &&
+      hasOnlyKeys(value.artifact, ['objectKey', 'sha256', 'sizeBytes']) &&
+      isSafeObjectKey(value.artifact.objectKey) &&
+      isPositiveInteger(value.artifact.sizeBytes) &&
+      isSha256(value.artifact.sha256)
+    );
+  }
+  if (value.result === 'integration_pg_dump_restored') {
+    return (
+      hasOnlyKeys(value, ['result', 'validationMetadata']) &&
+      parseAppDatabaseImportValidationMetadata(value.validationMetadata, true) !== undefined
+    );
+  }
   return (
     value.result === 'schema_validated' &&
     parseAppDatabaseImportValidationMetadata(value.validationMetadata) !== undefined &&
@@ -172,11 +268,27 @@ export function isAppDatabaseImportCallbackResult(value: unknown): value is AppD
   );
 }
 
+export function isAppDatabaseImportSource(value: unknown): value is AppDatabaseImportSource {
+  return (
+    isUnknownRecord(value) &&
+    hasOnlyKeys(value, ['integrationConfigurationId', 'integrationId', 'profile', 'profileId', 'type']) &&
+    value.type === 'integration' &&
+    isNonEmptyString(value.integrationId) &&
+    isNonEmptyString(value.integrationConfigurationId) &&
+    isNonEmptyString(value.profileId) &&
+    isNonEmptyString(value.profile)
+  );
+}
+
 // Rebuild metadata from its allowlisted fields so archive contents, SQL, rows,
 // and other worker-provided details cannot cross this contract boundary.
-export function parseAppDatabaseImportValidationMetadata(value: unknown): AppDatabaseImportValidationMetadata | undefined {
+export function parseAppDatabaseImportValidationMetadata(
+  value: unknown,
+  requireExact = false
+): AppDatabaseImportValidationMetadata | undefined {
   if (
     !isUnknownRecord(value) ||
+    (requireExact && !hasOnlyKeys(value, ['postgresMajorVersion', 'tableNames'])) ||
     !isPositiveInteger(value.postgresMajorVersion) ||
     !Array.isArray(value.tableNames) ||
     !value.tableNames.every(isNonEmptyString)
@@ -203,7 +315,6 @@ function hasImportDispatchBase(value: Record<string, unknown>): value is ImportD
     isUnknownRecord(value.import) &&
     isNonEmptyString(value.import.importId) &&
     value.import.kind === 'pg_dump_custom' &&
-    isPositiveInteger(value.import.prefixSizeBytes) &&
     isNonEmptyString(value.organizationId) &&
     isNonEmptyString(value.profile) &&
     isNonEmptyString(value.requestId) &&
@@ -233,6 +344,21 @@ function isPositiveInteger(value: unknown): value is number {
   return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
 }
 
+function isSha256(value: unknown): value is string {
+  return typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+}
+
+function isSafeObjectKey(value: unknown): value is string {
+  return (
+    typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._/-]{0,1023}$/.test(value) && !value.split('/').some((segment) => segment === '..')
+  );
+}
+
 function isUnknownRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+
+function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  const allowedKeys = new Set(allowed);
+  return Object.keys(value).every((key) => allowedKeys.has(key));
+}

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

@@ -1,9 +1,17 @@
 import { describe, expect, it } from 'vitest';
 
 import { ViewMode } from '../types/event/index.js';
-import { isProductionDatabaseRetirementEligible, type AppDatabaseStatus, type AppDatabaseStatusBinding } from './appDatabaseStatus.js';
+import {
+  databaseWideOperationBlockReason,
+  isProductionDatabaseRetirementEligible,
+  preferredBlockingDatabaseOperation,
+  TABLE_IMPORT_IN_PROGRESS_REASON,
+  type AppDatabaseStatus,
+  type AppDatabaseStatusBinding
+} from './appDatabaseStatus.js';
 
 const binding: AppDatabaseStatusBinding = {
+  agentName: 'customer-opa',
   bindingId: 'binding-1',
   created: '2026-09-14T00:00:00.000Z',
   instance: null,
@@ -103,3 +111,14 @@ describe('production database retirement eligibility', () => {
     ).toBe(false);
   });
 });
+
+describe('database-wide operation block', () => {
+  it('prefers retirement over a migration and names the operation the import has to wait for', () => {
+    expect(preferredBlockingDatabaseOperation(['restore_import_data', 'migrate_schema', 'retire_database'])).toBe('retire_database');
+    expect(preferredBlockingDatabaseOperation(['import_table_data'])).toBeUndefined();
+    expect(databaseWideOperationBlockReason('migrate_schema')).toBe('A schema migration is running on this database.');
+    expect(databaseWideOperationBlockReason('restore_import_data')).toBe('A database restore is running on this data tag.');
+    expect(databaseWideOperationBlockReason('retire_database')).toBe('This database is being removed.');
+    expect(TABLE_IMPORT_IN_PROGRESS_REASON).toBe('A table import is running on this database.');
+  });
+});

package/src/database-lifecycle/appDatabaseStatus.ts

@@ -1,5 +1,6 @@
 import { ViewMode } from '../types/event/index.js';
 import type { AppDatabaseTagRef } from './appDatabaseCompatibility.js';
+import type { AppDatabaseImportTagSupport } from './importCompatibility.js';
 import type { DatabaseEngine, LifecycleMigrationState, LifecycleState } from './index.js';
 
 /**
@@ -20,13 +21,46 @@ export type AppDatabaseStatusIntegration = {
   pluginId: string;
 };
 
+// These rewrite or remove the whole database. A CSV import into any table on
+// that binding has to wait until the lifecycle request leaves these states.
+export const DATABASE_WIDE_LIFECYCLE_OPERATIONS = ['migrate_schema', 'restore_import_data', 'retire_database'] as const;
+export type DatabaseWideLifecycleOperation = (typeof DATABASE_WIDE_LIFECYCLE_OPERATIONS)[number];
+
+export const TABLE_IMPORT_IN_PROGRESS_REASON = 'A table import is running on this database.';
+
+export function databaseWideOperationBlockReason(operation: DatabaseWideLifecycleOperation): string {
+  switch (operation) {
+    case 'migrate_schema':
+      return 'A schema migration is running on this database.';
+    case 'restore_import_data':
+      return 'A database restore is running on this data tag.';
+    case 'retire_database':
+      return 'This database is being removed.';
+  }
+}
+
+const BLOCKING_OPERATION_PRIORITY = ['retire_database', 'migrate_schema', 'restore_import_data'] as const;
+
+export function preferredBlockingDatabaseOperation(operations: readonly string[]): DatabaseWideLifecycleOperation | undefined {
+  return BLOCKING_OPERATION_PRIORITY.find((operation) => operations.includes(operation));
+}
+
 export type AppDatabaseStatusBinding = {
+  /**
+   * Owning OPA deployment name (`databaseLifecycle:agentName`). Null on
+   * bindings created before ownership tracking. Schema reads route to this
+   * agent; without it the browser cannot authorize a describe call.
+   */
+  agentName: string | null;
   bindingId: string;
   created: string;
   instance: AppDatabaseStatusInstance | null;
   integration: AppDatabaseStatusIntegration | null;
   lastActivity: string;
   lifecycleState: LifecycleState;
+  // Set while migrate_schema, restore_import_data, or retire_database is still
+  // pending or running for this binding.
+  inProgressOperation?: DatabaseWideLifecycleOperation;
   logicalName: string;
   migrationDirectory: string | null;
   migrationState: LifecycleMigrationState;
@@ -35,6 +69,11 @@ export type AppDatabaseStatusBinding = {
 export type AppDatabaseStatusTag = AppDatabaseTagRef & {
   /** Null when this data tag has no live (non-cancelled) database. */
   binding: AppDatabaseStatusBinding | null;
+  /**
+   * Whether this tag's registered worker can run a CSV import. Computed by
+   * the server from connected-agent registrations, not from a browser probe.
+   */
+  csvImport?: AppDatabaseImportTagSupport;
   /**
    * True when this data tag had a database that was retired. The live
    * binding is omitted so the tag can be provisioned again, but Status

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

@@ -1,6 +1,7 @@
 import { describe, expect, test } from 'vitest';
 
 import {
+  csvImportPlanFromWizard,
   mintDataImportConcurrencyKey,
   parseDataImportMetadata,
   parseDataImportTarget,
@@ -62,6 +63,12 @@ describe('data import contracts', () => {
     }
     expect(mintDataImportConcurrencyKey(spaced, target)).toBe(`csv:${target.bindingId}:public.orders`);
     expect(mintDataImportConcurrencyKey(plain, target)).toBe(mintDataImportConcurrencyKey(spaced, target));
+    expect(mintDataImportConcurrencyKey({ kind: 'csv', mode: 'append', table: 'public.users' }, target)).not.toBe(
+      mintDataImportConcurrencyKey(plain, target)
+    );
+    expect(mintDataImportConcurrencyKey(plain, { ...target, bindingId: 'binding-production' })).not.toBe(
+      mintDataImportConcurrencyKey(plain, target)
+    );
     expect(parseDataImportMetadata('csv', { kind: 'csv', mode: 'append', table: '   ' })).toBeUndefined();
     expect(parseDataImportMetadata('csv', { kind: 'csv', mode: 'append', table: 'public. order items' })).toBeUndefined();
     for (const table of ['PUBLIC.ORDERS', 'public."orders"', '"public"."orders"', 'orders']) {
@@ -80,6 +87,74 @@ describe('data import contracts', () => {
     expect(parseDataImportMetadata('csv', { kind: 'csv', mode: 'append', table: `public.${sixtyThree}y` })).toBeUndefined();
   });
 
+  test('keeps a csv upload without a table plan and stores a complete plan', () => {
+    expect(parseDataImportMetadata('csv', { kind: 'csv', mode: 'append', table: 'public.orders' })).toEqual({
+      kind: 'csv',
+      mode: 'append',
+      table: 'public.orders'
+    });
+    const plan = {
+      columnMapping: [{ source: 'id', target: 'id' }],
+      dateStyle: 'ISO, YMD',
+      delimiter: ',' as const,
+      emptyAsNull: true,
+      encoding: 'UTF8' as const,
+      hasHeader: true,
+      timeZone: 'UTC',
+      trimWhitespace: true
+    };
+    expect(parseDataImportMetadata('csv', { kind: 'csv', mode: 'replace', table: 'public.orders', ...plan })).toEqual({
+      kind: 'csv',
+      mode: 'replace',
+      table: 'public.orders',
+      ...plan
+    });
+    expect(
+      parseDataImportMetadata('csv', { kind: 'csv', mode: 'append', table: 'public.superblocks_schema_migrations', ...plan })
+    ).toBeUndefined();
+    expect(parseDataImportMetadata('csv', { kind: 'csv', mode: 'append', table: 'public.superblocks_schema_migrations' })).toBeUndefined();
+    expect(parseDataImportMetadata('csv', { kind: 'csv', mode: 'append', table: 'pg_catalog.pg_class', ...plan })).toBeUndefined();
+  });
+
+  test('maps wizard date formats and encodings onto the worker plan', () => {
+    const mapped = csvImportPlanFromWizard({
+      columnMappings: { id: 'id', skipped: '' },
+      dateFormat: 'YYYY-MM-DD',
+      encoding: 'utf-8',
+      trimWhitespace: true
+    });
+    expect(mapped).toEqual({
+      plan: {
+        columnMapping: [{ source: 'id', target: 'id' }],
+        dateStyle: 'ISO, YMD',
+        delimiter: ',',
+        emptyAsNull: true,
+        encoding: 'UTF8',
+        hasHeader: true,
+        timeZone: 'UTC',
+        trimWhitespace: true
+      },
+      status: 'ok'
+    });
+    expect(
+      csvImportPlanFromWizard({
+        columnMappings: { id: 'id' },
+        dateFormat: 'MM/DD/YYYY',
+        encoding: 'windows-1252',
+        trimWhitespace: false
+      })
+    ).toMatchObject({ plan: { dateStyle: 'ISO, MDY', encoding: 'WINDOWS1252', trimWhitespace: false }, status: 'ok' });
+    expect(
+      csvImportPlanFromWizard({ columnMappings: { id: 'id' }, dateFormat: 'YYYY-MM-DD', encoding: 'utf-16', trimWhitespace: true })
+    ).toEqual({ message: 'Encoding must be UTF-8 or Windows-1252.', status: 'invalid' });
+    expect(
+      csvImportPlanFromWizard({ columnMappings: { id: '' }, dateFormat: 'not-a-date', encoding: 'utf-8', trimWhitespace: true })
+    ).toEqual({
+      message: 'Date format must be YYYY-MM-DD, MM/DD/YYYY, DD/MM/YYYY, or DD.MM.YYYY.',
+      status: 'invalid'
+    });
+  });
+
   test('rejects zero prefix sizes and a zero postgres major', () => {
     const base = { kind: 'pg_dump_custom' as const };
     expect(parseDataImportMetadata('pg_dump_custom', { ...base, currentPrefixSizeBytes: 0 })).toBeUndefined();