@superblocksteam/shared 0.9614.3 → 0.9615.1

package/src/database-lifecycle/dataImport.ts

@@ -0,0 +1,244 @@
+export const DATA_IMPORT_KINDS = ['csv', 'pg_dump_custom'] as const;
+// CHECK union for every kind. Prefix/schema success is `schema_validated`.
+// `ready` stays available for CSV/JSON "validated, waiting to apply".
+// Only `completed`, `failed`, and `cancelled` release the concurrency slot.
+export const DATA_IMPORT_STATES = [
+  'requested',
+  'preparing_upload',
+  'preparing_prefix_upload',
+  'awaiting_upload',
+  'awaiting_prefix_upload',
+  'uploading',
+  'upload_completed',
+  'validating',
+  'validating_schema',
+  'schema_validated',
+  'ready',
+  'importing',
+  'completed',
+  'failed',
+  'cancelled'
+] as const;
+const DATA_IMPORT_TERMINAL_STATES = ['completed', 'failed', 'cancelled'] as const;
+export const DATA_IMPORT_ACTIVE_STATES = DATA_IMPORT_STATES.filter(
+  (state) => !(DATA_IMPORT_TERMINAL_STATES as readonly string[]).includes(state)
+);
+export const DATA_IMPORT_TARGET_TYPES = ['app_database'] as const;
+
+export type DataImportKind = (typeof DATA_IMPORT_KINDS)[number];
+export type DataImportState = (typeof DATA_IMPORT_STATES)[number];
+export type DataImportTargetType = (typeof DATA_IMPORT_TARGET_TYPES)[number];
+
+export type DataImportTargetBase = {
+  type: DataImportTargetType;
+};
+
+export type AppDatabaseDataImportTarget = DataImportTargetBase & {
+  applicationId: string;
+  bindingId: string;
+  profile: string;
+};
+
+// The persistence layer stores one target descriptor instead of destination-
+// specific columns. Add future destinations as new discriminated variants.
+export type DataImportTarget = AppDatabaseDataImportTarget;
+
+export type DataImportUploadMetadata = {
+  completedPartNumbers?: number[];
+  filename: string;
+  prefixExpiresAt?: number;
+  objectChecksumSha256?: string;
+  objectKey?: string;
+  objectSizeBytes?: string;
+  partCount?: number;
+  partSizeBytes?: number;
+  uploadId?: string;
+};
+
+// Kind-specific facts kept in one jsonb column. Discriminate by kind so CSV
+// table/mode cannot be stored in dump prefix fields. File contents, SQL,
+// signed URLs, credentials, ETags, and row samples stay out.
+export type PgDumpDataImportMetadata = {
+  kind: 'pg_dump_custom';
+  currentPrefixSizeBytes?: number;
+  postgresMajorVersion?: number;
+  prefixChecksumSha256?: string;
+  prefixObjectKey?: string;
+  requestedPrefixSizeBytes?: number;
+  tableNames?: string[];
+};
+
+export type CsvDataImportMetadata = {
+  kind: 'csv';
+  mode: 'append' | 'replace';
+  table: string;
+};
+
+export type DataImportMetadata = PgDumpDataImportMetadata | CsvDataImportMetadata;
+
+// Apply/terminal counts. Decimal strings, not JSON numbers, so values above
+// Number.MAX_SAFE_INTEGER do not round. Writers replace this object whole.
+export type DataImportOutcome = {
+  rowsDeleted?: string;
+  rowsInserted?: string;
+  rowsRead?: string;
+};
+
+const DATA_IMPORT_OUTCOME_KEYS = ['rowsDeleted', 'rowsInserted', 'rowsRead'] as const;
+
+// Kind decides the grain. Callers do not supply this string.
+// pg_dump_custom: one in-flight dump per binding.
+// csv: one in-flight import per canonical schema.table on that binding.
+export function mintDataImportConcurrencyKey(metadata: DataImportMetadata, target: AppDatabaseDataImportTarget): string {
+  if (metadata.kind === 'pg_dump_custom') {
+    return `pg_dump_custom:${target.bindingId}`;
+  }
+  return `csv:${target.bindingId}:${metadata.table}`;
+}
+
+export function parseDataImportTarget(value: unknown): DataImportTarget | undefined {
+  if (
+    !isUnknownRecord(value) ||
+    value.type !== 'app_database' ||
+    !isNonEmptyString(value.applicationId) ||
+    !isNonEmptyString(value.bindingId) ||
+    !isNonEmptyString(value.profile)
+  ) {
+    return undefined;
+  }
+  return {
+    applicationId: value.applicationId,
+    bindingId: value.bindingId,
+    profile: value.profile,
+    type: value.type
+  };
+}
+
+export function parseDataImportMetadata(kind: DataImportKind, value: unknown): DataImportMetadata | undefined {
+  if (!isUnknownRecord(value) || value.kind !== kind) {
+    return undefined;
+  }
+  if (kind === 'pg_dump_custom') {
+    return parsePgDumpMetadata(value);
+  }
+  const table = canonicalCsvTable(value.table);
+  if (table === undefined || (value.mode !== 'append' && value.mode !== 'replace')) {
+    return undefined;
+  }
+  const allowed = new Set(['kind', 'mode', 'table']);
+  if (Object.keys(value).some((key) => !allowed.has(key))) {
+    return undefined;
+  }
+  return { kind: 'csv', mode: value.mode, table };
+}
+
+export function parseDataImportOutcome(value: unknown): DataImportOutcome | undefined {
+  if (!isUnknownRecord(value)) {
+    return undefined;
+  }
+  if (Object.keys(value).some((key) => !DATA_IMPORT_OUTCOME_KEYS.includes(key as (typeof DATA_IMPORT_OUTCOME_KEYS)[number]))) {
+    return undefined;
+  }
+  const outcome: DataImportOutcome = {};
+  for (const key of DATA_IMPORT_OUTCOME_KEYS) {
+    const count = value[key];
+    if (count === undefined) {
+      continue;
+    }
+    if (!isDecimalCount(count)) {
+      return undefined;
+    }
+    outcome[key] = count;
+  }
+  return outcome;
+}
+
+export function sqlStringList(values: readonly string[]): string {
+  return values.map((value) => `'${value}'`).join(', ');
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+// One unquoted lowercase schema.table. Each part is at most 63 bytes, which
+// is PostgreSQL's identifier limit. A longer spelling would truncate to the
+// same relation as another accepted key.
+const CANONICAL_CSV_TABLE = /^[a-z_][a-z0-9_]{0,62}\.[a-z_][a-z0-9_]{0,62}$/;
+
+function canonicalCsvTable(value: unknown): string | undefined {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const table = value.trim();
+  if (!CANONICAL_CSV_TABLE.test(table)) {
+    return undefined;
+  }
+  return table;
+}
+
+function parsePgDumpMetadata(value: Record<string, unknown>): PgDumpDataImportMetadata | undefined {
+  const metadata: PgDumpDataImportMetadata = { kind: 'pg_dump_custom' };
+  if (!assignOptionalString(metadata, 'prefixChecksumSha256', value.prefixChecksumSha256)) return undefined;
+  if (!assignOptionalString(metadata, 'prefixObjectKey', value.prefixObjectKey)) return undefined;
+  if (!assignOptionalInteger(metadata, 'currentPrefixSizeBytes', value.currentPrefixSizeBytes)) return undefined;
+  if (!assignOptionalInteger(metadata, 'postgresMajorVersion', value.postgresMajorVersion)) return undefined;
+  if (!assignOptionalInteger(metadata, 'requestedPrefixSizeBytes', value.requestedPrefixSizeBytes)) return undefined;
+  if (value.tableNames !== undefined) {
+    if (!Array.isArray(value.tableNames) || !value.tableNames.every(isNonEmptyString)) {
+      return undefined;
+    }
+    metadata.tableNames = value.tableNames;
+  }
+  const allowed = new Set([
+    'kind',
+    'currentPrefixSizeBytes',
+    'postgresMajorVersion',
+    'prefixChecksumSha256',
+    'prefixObjectKey',
+    'requestedPrefixSizeBytes',
+    'tableNames'
+  ]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) {
+    return undefined;
+  }
+  return metadata;
+}
+
+function assignOptionalString<Key extends 'prefixChecksumSha256' | 'prefixObjectKey'>(
+  metadata: PgDumpDataImportMetadata,
+  key: Key,
+  value: unknown
+): boolean {
+  if (value === undefined) {
+    return true;
+  }
+  if (!isNonEmptyString(value)) {
+    return false;
+  }
+  metadata[key] = value;
+  return true;
+}
+
+function assignOptionalInteger(
+  metadata: PgDumpDataImportMetadata,
+  key: 'currentPrefixSizeBytes' | 'postgresMajorVersion' | 'requestedPrefixSizeBytes',
+  value: unknown
+): boolean {
+  if (value === undefined) {
+    return true;
+  }
+  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+    return false;
+  }
+  metadata[key] = value;
+  return true;
+}
+
+function isDecimalCount(value: unknown): value is string {
+  return typeof value === 'string' && /^(0|[1-9][0-9]*)$/.test(value);
+}
+
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

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

@@ -3,6 +3,7 @@ import { describe, expect, test } from 'vitest';
 import { ApiTriggerType } from '../types/api/index.js';
 import {
   DATABASE_LIFECYCLE_MANAGED_BY,
+  DATABASE_LIFECYCLE_OPERATIONS,
   LIFECYCLE_OPERATIONS,
   computeBindingKey,
   computeDesiredSpecHash,
@@ -20,17 +21,30 @@ import {
 } from './index.js';
 
 describe('database lifecycle contracts', () => {
-  // Postgres `ALTER TYPE ... ADD VALUE` appends. TypeORM's entity-vs-schema
-  // check treats enum label order as part of the contract, so this array must
-  // match the live `lifecycle_operation_enum` order rather than alphabetical
-  // or semantic grouping.
-  test('lists lifecycle operations in Postgres enum order', () => {
+  test('lists persisted operations first and appends import operations', () => {
     expect(LIFECYCLE_OPERATIONS).toEqual([
       'ensure_database',
       'migrate_schema',
       'retire_database',
       'ensure_physical_database_instance',
-      'retire_physical_database_instance'
+      'retire_physical_database_instance',
+      'verify_database_infra_absence',
+      'prepare_import_upload',
+      'complete_import_upload',
+      'prepare_import_prefix_upload',
+      'inspect_import_prefix',
+      'describe_schema'
+    ]);
+  });
+
+  test('keeps import operations out of the default agent operation set', () => {
+    expect(DATABASE_LIFECYCLE_OPERATIONS).toEqual([
+      'ensure_database',
+      'migrate_schema',
+      'retire_database',
+      'ensure_physical_database_instance',
+      'retire_physical_database_instance',
+      'verify_database_infra_absence'
     ]);
   });
 

package/src/database-lifecycle/index.ts

@@ -1,6 +1,22 @@
 import { sha256Base64 } from '../signing/hashing.js';
 import { ApiTriggerType } from '../types/api/index.js';
+import {
+  APP_DATABASE_IMPORT_OPERATIONS,
+  type AppDatabaseImportCallbackResult,
+  type AppDatabaseImportDispatchPayloadEnvelope,
+  type AppDatabaseImportErrorCode,
+  type AppDatabaseImportLifecycleOperation,
+  type InspectImportPrefixDispatchPayloadEnvelope,
+  type PrepareImportPrefixUploadDispatchPayloadEnvelope
+} from './appDatabaseImport.js';
 import type { DatabaseEngine } from './capacityPolicy.js';
+import {
+  DATA_IMPORT_KINDS,
+  DATA_IMPORT_TARGET_TYPES,
+  type DataImportKind,
+  type DataImportTargetBase,
+  type DataImportTargetType
+} from './dataImport.js';
 
 export const LIFECYCLE_TERMINAL_STATES = ['ready', 'failed', 'cancelled'] as const;
 export const LIFECYCLE_NON_TERMINAL_STATES = ['pending', 'provisioning', 'migrating', 'retiring'] as const;
@@ -13,16 +29,24 @@ export const LIFECYCLE_MIGRATION_STATES = ['pending', 'migrated', 'failed'] as c
 // are claimable pool-level work (wizard / eager provisioning, admin
 // decommission). Neither is bound to a database_binding row; the claim payload
 // carries provisioningId or the instance id instead of binding identity.
-// Appended in the order the labels were added because Postgres
-// `ALTER TYPE ... ADD VALUE` appends, and TypeORM's entity-vs-schema check
-// requires this array to match that live order.
+// Persisted database lifecycle operations come first in Postgres enum order.
+// Import operations are appended. Generic upload operations stay out of the
+// default agent set; prefix operations are stored by the data-import migration
+// but are not part of that default set either.
 export const LIFECYCLE_OPERATIONS = [
   'ensure_database',
   'migrate_schema',
   'retire_database',
   'ensure_physical_database_instance',
-  'retire_physical_database_instance'
+  'retire_physical_database_instance',
+  'verify_database_infra_absence',
+  'prepare_import_upload',
+  'complete_import_upload',
+  'prepare_import_prefix_upload',
+  'inspect_import_prefix',
+  'describe_schema'
 ] as const;
+export const GENERIC_IMPORT_OPERATIONS = ['prepare_import_upload', 'complete_import_upload'] as const;
 // The pool-scoped operations, which carry an organization directly and have no
 // binding, desired spec, or desired spec hash. `CK_lifecycle_request_shape`
 // enforces exactly this split at the database level.
@@ -55,6 +79,49 @@ export const DATABASE_LIFECYCLE_TAG_OPERATIONS = 'databaseLifecycle:operations';
 export const DATABASE_LIFECYCLE_TAG_ENGINES = 'databaseLifecycle:engines';
 export const DATABASE_LIFECYCLE_TAG_CAPABILITIES = 'databaseLifecycle:capabilities';
 export const DATABASE_LIFECYCLE_TAG_PHYSICAL_CONFIG_FINGERPRINT = 'databaseLifecycle:physicalConfigFingerprint';
+export {
+  APP_DATABASE_IMPORT_ERROR_CODES,
+  APP_DATABASE_IMPORT_OPERATIONS,
+  APP_DATABASE_IMPORT_STATES,
+  isAppDatabaseImportCallbackResult,
+  isAppDatabaseImportDispatchPayload,
+  isAppDatabaseImportLifecycleOperation,
+  parseAppDatabaseImportValidationMetadata,
+  type AppDatabaseImportCallbackResult,
+  type AppDatabaseImportDispatchDetails,
+  type AppDatabaseImportDispatchPayloadEnvelope,
+  type AppDatabaseImportErrorCode,
+  type AppDatabaseImportKind,
+  type AppDatabaseImportLifecycleOperation,
+  type AppDatabaseImportState,
+  type AppDatabaseImportValidationMetadata,
+  type InspectImportPrefixCallbackResult,
+  type InspectImportPrefixDispatchPayloadEnvelope,
+  type PrepareImportPrefixUploadCallbackResult,
+  type PrepareImportPrefixUploadDispatchPayloadEnvelope
+} from './appDatabaseImport.js';
+export {
+  DATA_IMPORT_ACTIVE_STATES,
+  DATA_IMPORT_KINDS,
+  DATA_IMPORT_STATES,
+  DATA_IMPORT_TARGET_TYPES,
+  mintDataImportConcurrencyKey,
+  parseDataImportMetadata,
+  parseDataImportOutcome,
+  parseDataImportTarget,
+  sqlStringList,
+  type AppDatabaseDataImportTarget,
+  type CsvDataImportMetadata,
+  type DataImportKind,
+  type DataImportTargetBase,
+  type DataImportMetadata,
+  type DataImportOutcome,
+  type DataImportState,
+  type PgDumpDataImportMetadata,
+  type DataImportTarget,
+  type DataImportTargetType,
+  type DataImportUploadMetadata
+} from './dataImport.js';
 export {
   CapacityPolicyValidationError,
   DATABASE_ENGINES,
@@ -79,8 +146,24 @@ export { DATABASE_LIFECYCLE_TAG_AGENT_NAME, PhysicalPoolIdentityError, parsePhys
 export { parsePhysicalDatabaseInstanceResourceKey, type PhysicalDatabaseInstanceResourceKey } from './physicalInstanceResourceKey.js';
 
 export type LifecycleOperation = (typeof LIFECYCLE_OPERATIONS)[number];
+export type GenericImportLifecycleOperation = (typeof GENERIC_IMPORT_OPERATIONS)[number];
+export type DatabaseLifecycleOperation = Exclude<LifecycleOperation, AppDatabaseImportLifecycleOperation | GenericImportLifecycleOperation>;
 export type PoolScopedLifecycleOperation = (typeof POOL_SCOPED_LIFECYCLE_OPERATIONS)[number];
 
+// Operations an existing agent must publish to count as covering App Database.
+// Import operations are stored by the data-import migration, but they are not
+// part of that default set.
+export const DATABASE_LIFECYCLE_OPERATIONS = LIFECYCLE_OPERATIONS.filter(
+  (operation): operation is DatabaseLifecycleOperation =>
+    operation !== 'describe_schema' &&
+    !(GENERIC_IMPORT_OPERATIONS as readonly string[]).includes(operation) &&
+    !(APP_DATABASE_IMPORT_OPERATIONS as readonly string[]).includes(operation)
+);
+
+export function isGenericImportLifecycleOperation(operation: string): operation is GenericImportLifecycleOperation {
+  return (GENERIC_IMPORT_OPERATIONS as readonly string[]).includes(operation);
+}
+
 export function isPoolScopedLifecycleOperation(operation: LifecycleOperation): operation is PoolScopedLifecycleOperation {
   return (POOL_SCOPED_LIFECYCLE_OPERATIONS as readonly string[]).includes(operation);
 }
@@ -99,6 +182,13 @@ export const LIFECYCLE_ERROR_CODES = [
   'migration_failed',
   'callback_failed',
   'configuration_conflict',
+  'upload_incomplete',
+  'checksum_mismatch',
+  'size_exceeded',
+  'table_not_found',
+  'column_not_found',
+  'invalid_value',
+  'permission_denied',
   // Server-side classification for a terminal callback that arrived for a
   // request whose desiredSpecHash no longer matches the binding (binding has
   // moved to a newer spec). The callback's metadata/state is discarded and
@@ -108,7 +198,54 @@ export const LIFECYCLE_ERROR_CODES = [
 
 export type LifecycleErrorCode = (typeof LIFECYCLE_ERROR_CODES)[number];
 
-export const LIFECYCLE_PROVIDER_DIAGNOSTIC_PHASES = ['apply', 'destroy', 'init', 'plan', 'unknown'] as const;
+export const LIFECYCLE_IMPORT_KINDS = DATA_IMPORT_KINDS;
+export const LIFECYCLE_IMPORT_TARGET_TYPES = DATA_IMPORT_TARGET_TYPES;
+
+export type LifecycleImportKind = DataImportKind;
+export type LifecycleImportTargetType = DataImportTargetType;
+
+export type LifecycleImportTarget = DataImportTargetBase & {
+  id: string;
+};
+
+export type LifecycleImportPart = {
+  eTag?: string;
+  expiresAt?: string;
+  partNumber: number;
+  url?: string;
+};
+
+// Shared fields used by prepare_import_upload and complete_import_upload.
+// Operation-specific consumers validate which optional fields are present.
+export type LifecycleImportPayload = {
+  expectedSizeBytes?: number;
+  filename?: string;
+  importId: string;
+  kind?: LifecycleImportKind;
+  objectKey?: string;
+  parts?: LifecycleImportPart[];
+  partSizeBytes?: number;
+  sha256?: string;
+  sizeBytes?: number;
+  target: LifecycleImportTarget;
+  uploadAlreadyComplete?: boolean;
+  uploadId?: string;
+};
+
+export type LifecycleTerminalCallbackPayload = {
+  bindingKey?: string;
+  connectionMetadata?: Record<string, string | number | boolean>;
+  error?: LifecycleTerminalCallbackError;
+  import?: LifecycleImportPayload;
+  lifecycleState: LifecycleTerminalState;
+  migrationState?: LifecycleMigrationState;
+  physicalConfigFingerprint?: string;
+  physicalDatabaseInstanceId?: string;
+  provisioningId?: string;
+  requestId: string;
+};
+
+export const LIFECYCLE_PROVIDER_DIAGNOSTIC_PHASES = ['apply', 'describe_schema', 'destroy', 'init', 'plan', 'unknown'] as const;
 export const MAX_LIFECYCLE_PROVIDER_DIAGNOSTICS = 3;
 export const LIFECYCLE_PROVIDER_DIAGNOSTIC_AWS_SERVICE_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
 export const LIFECYCLE_PROVIDER_DIAGNOSTIC_AWS_OPERATION_PATTERN = /^[A-Za-z][A-Za-z0-9]{0,63}$/;
@@ -278,6 +415,37 @@ export function sanitizeLifecycleProviderDiagnostics(value: unknown): LifecycleP
   return diagnostics.length > 0 ? diagnostics : undefined;
 }
 
+export type LifecycleTerminalCallbackError<TErrorCode extends string = LifecycleErrorCode> = {
+  code: TErrorCode;
+  diagnostics?: LifecycleProviderDiagnostic[];
+  message: string;
+};
+
+export type LifecycleTerminalCallbackEnvelope<TErrorCode extends string = LifecycleErrorCode> = {
+  bindingKey?: string;
+  connectionMetadata?: Record<string, unknown>;
+  error?: LifecycleTerminalCallbackError<TErrorCode>;
+  lifecycleState: LifecycleTerminalState;
+  migrationState?: LifecycleMigrationState;
+  requestId: string;
+};
+
+type AppDatabaseImportSuccessfulCallback = Omit<
+  LifecycleTerminalCallbackEnvelope<AppDatabaseImportErrorCode>,
+  'error' | 'lifecycleState'
+> & {
+  error?: never;
+  import: AppDatabaseImportCallbackResult;
+  lifecycleState: 'ready';
+};
+
+type AppDatabaseImportFailedCallback = Omit<LifecycleTerminalCallbackEnvelope<AppDatabaseImportErrorCode>, 'lifecycleState'> & {
+  import?: never;
+  lifecycleState: 'cancelled' | 'failed';
+};
+
+export type AppDatabaseImportCallback = AppDatabaseImportFailedCallback | AppDatabaseImportSuccessfulCallback;
+
 export type PhysicalMasterCredentialRef = {
   resolver: 'aws_secrets_manager';
   ref: string;
@@ -351,6 +519,24 @@ export type LifecycleRequest = {
   state: LifecycleState;
 };
 
+export const INFRA_ABSENCE_PROOF_KINDS = ['postgres_catalog_database_absent', 'aws_rds_resource_not_found'] as const;
+export type InfraAbsenceProofKind = (typeof INFRA_ABSENCE_PROOF_KINDS)[number];
+
+export type LifecycleInfraAbsenceEvidence = {
+  bindingId: string;
+  checkedAt: string;
+  physicalIdentifier: string;
+  proofKind: InfraAbsenceProofKind;
+  provider: {
+    awsAccountId?: string;
+    name: 'aws_rds' | 'postgresql';
+    region?: string;
+    requestId?: string;
+  };
+  requestId: string;
+  targetDatabase: string;
+};
+
 // Physical database instances back the M2 shared-RDS allocation pattern: dev-DB
 // provisioning issues `CREATE DATABASE`/`CREATE ROLE` against a pre-existing
 // physical database instance instead of spinning up a fresh RDS per binding.
@@ -493,7 +679,7 @@ export type PhysicalPoolSummary = {
 // For `ensure_physical_database_instance`, binding identity fields are empty
 // placeholders (the OPA keys the lock on provisioningId) and `provisioningId`
 // is required.
-export type LifecycleDispatchPayload = {
+export type DatabaseLifecycleDispatchPayload = {
   applicationId: string;
   bindingId: string;
   bindingKey: string;
@@ -508,15 +694,25 @@ export type LifecycleDispatchPayload = {
   // server supplies rather than anything a caller picks, and it goes away with
   // the worker's remaining shims in ENG-5127.
   environment?: string;
+  import?: LifecycleImportPayload;
   metadata?: { physicalConfigFingerprint?: string };
   migrations?: LifecycleMigration[];
-  operation: LifecycleOperation;
+  operation: DatabaseLifecycleOperation;
   profile: string;
   provisioningId?: string;
   requestId: string;
   resourceKey: string;
 };
 
+export type PrepareImportPrefixUploadDispatchPayload = PrepareImportPrefixUploadDispatchPayloadEnvelope<DatabaseRequirement>;
+export type InspectImportPrefixDispatchPayload = InspectImportPrefixDispatchPayloadEnvelope<DatabaseRequirement>;
+export type AppDatabaseImportDispatchPayload = AppDatabaseImportDispatchPayloadEnvelope<DatabaseRequirement>;
+export type GenericImportDispatchPayload = Omit<DatabaseLifecycleDispatchPayload, 'import' | 'operation'> & {
+  import: LifecycleImportPayload;
+  operation: GenericImportLifecycleOperation;
+};
+export type LifecycleDispatchPayload = DatabaseLifecycleDispatchPayload | GenericImportDispatchPayload | AppDatabaseImportDispatchPayload;
+
 const PHYSICAL_POOL_PROVISIONING_RESOURCE_KEY_PREFIX = 'physical-pool-provisioning';
 
 export function physicalPoolProvisioningResourceKey(provisioningId: string): string {

package/src/index.ts

@@ -28,5 +28,6 @@ export * from './jwt/index.js';
 export * from './org-features/index.js';
 export * from './database-lifecycle/index.js';
 export * from './database-lifecycle/appDatabaseCompatibility.js';
+export * from './database-lifecycle/appDatabaseStatus.js';
 export * from './database-lifecycle/edit-lifecycle-capability.js';
 export * from './environment-compatibility/appEnvironmentCompatibility.js';

package/src/plugins/templates/workflow.ts

@@ -14,8 +14,6 @@ export const WorkflowPlugin: Plugin = {
     sections: []
   },
   actionTemplate: {
-    sections: [
-      /* Dynamically filled out by resolverContext */
-    ]
+    sections: [/* Dynamically filled out by resolverContext */]
   }
 };

package/src/socket/protocol.ts

@@ -36,9 +36,11 @@ import {
 import {
   AiChatMessageDto,
   AiChatMessagePayload,
+  AiAbandonTurnEvent,
   AiPromptCostRequest,
   AiPromptCostResponse,
   AiWorkflowEvent,
+  AiEditAfterClarkReport,
   AiResolveAttachmentLeasesRequest,
   AiResolveAttachmentLeasesResponse,
   FactCreate,
@@ -148,9 +150,11 @@ export interface ServerMethods {
         >;
         getMessages: ServerMethodSchema<
           { applicationId: string; branchName?: string | null; limit?: number },
-          { messages: AiChatMessageDto[] }
+          { chatSessionId: string; messages: AiChatMessageDto[] }
         >;
-        new: ServerMethodSchema<{ applicationId: string; branchName?: string | null }, void>;
+        /** Id of the active chat session, created if the app has none yet. Reads no messages. */
+        getActiveSessionId: ServerMethodSchema<{ applicationId: string }, { chatSessionId: string }>;
+        new: ServerMethodSchema<{ applicationId: string; branchName?: string | null }, { chatSessionId: string }>;
         truncateAfterTimestamp: ServerMethodSchema<{ applicationId: string; sinceTimestamp: number }, void>;
       };
       billing: {
@@ -161,6 +165,14 @@ export interface ServerMethods {
           submit: ServerMethodSchema<AiWorkflowEvent, void>;
         };
       };
+      analytics: {
+        abandonTurn: {
+          submit: ServerMethodSchema<AiAbandonTurnEvent, void>;
+        };
+        editAfterClark: {
+          submit: ServerMethodSchema<AiEditAfterClarkReport, void>;
+        };
+      };
       /**
        * Resolve attachment leases and return fresh signed URLs.
        * Called by ai-service to refresh attachment leases before sending to LLM.

package/src/types/ai/index.ts

@@ -110,6 +110,45 @@ export interface AiWorkflowEvent {
   deploymentName?: string;
 }
 
+export const AI_ABANDON_TURN_ACTIONS = ['clear_chat', 'interrupt', 'stop'] as const;
+export type AiAbandonTurnAction = (typeof AI_ABANDON_TURN_ACTIONS)[number];
+
+export const AI_ABANDON_TURN_MODES = ['build', 'plan'] as const;
+export type AiAbandonTurnMode = (typeof AI_ABANDON_TURN_MODES)[number];
+
+export const AI_ABANDON_TURN_STATES = ['AgentPlanning', 'LLMGenerating', 'PostProcessing', 'RuntimeReviewing'] as const;
+export type AiAbandonTurnState = (typeof AI_ABANDON_TURN_STATES)[number];
+
+export function isAiAbandonTurnState(value: unknown): value is AiAbandonTurnState {
+  return typeof value === 'string' && AI_ABANDON_TURN_STATES.some((state) => state === value);
+}
+
+/** A user action that stopped or replaced an active Clark turn. */
+export interface AiAbandonTurnEvent {
+  action: AiAbandonTurnAction;
+  actionAt: string;
+  eventId: string;
+  mode: AiAbandonTurnMode;
+  model: string;
+  provider: string;
+  /** Undefined when the client had no session established yet; unknown attribution, not an invalid event. */
+  sessionId: string | undefined;
+  state: AiAbandonTurnState;
+  turnId: string;
+}
+
+/**
+ * Whether files a completed Clark turn changed were changed again outside Clark
+ * before the next prompt. `promptId` names the Clark turn being measured, not
+ * the prompt that closed the window. Carries only counts and tree hashes, never
+ * file paths or contents. `chatSessionId` is the chat the turn belongs to, and
+ * `definitionVersion` is the version of the rule the dev server measured with.
+ */
+export type AiEditAfterClarkReport = { promptId: string; chatSessionId?: string; definitionVersion: number } & (
+  | { result: 'finding' | 'no_finding'; overlapCount: number; postHash: string; preHash: string }
+  | { result: 'unmeasured' }
+);
+
 /**
  * Per-LLM-call token usage payload used to calculate prompt cost.
  */