@abloatai/transaction 0.58.0 → 0.59.1

package/src/pricing.ts

@@ -46,7 +46,7 @@ export type { MeterEvent, PlanTier, RateBracket };
  * could observe the difference. It is emitted into the generated pricing
  * documentation so a stale copy is identifiable on sight.
  */
-export const PRICING_VERSION = '2026-08-24';
+export const PRICING_VERSION = '2026-08-28';
 
 /**
  * Resolve a stored plan string (`stripe_subscription.plan`) to a tier.
@@ -257,7 +257,7 @@ export const PLANS = z
       hardCapOps: null,
       hardCapOpsPerDay: null,
       storageGib: 50,
-      maxConcurrentConnections: 1_000,
+      maxConcurrentConnections: 5_000,
       contractPriced: false,
       features: ['auditExport'],
     },
@@ -397,3 +397,17 @@ export function dailyOpsCapForTier(tier: PlanTier): number | null {
 export function connectionCapForTier(tier: PlanTier): number | null {
   return PLANS[tier].maxConcurrentConnections;
 }
+
+/**
+ * The first public tier that can reserve the requested connection capacity.
+ * A `null` cap is negotiated capacity, not infinity in the runtime; it is the
+ * commercial catch-all that sends the buyer into an Enterprise capacity plan.
+ */
+export function selectPlanForConnectionCapacity(connections: number): PlanTier {
+  const requested = Number.isFinite(connections) ? Math.max(1, Math.ceil(connections)) : 1;
+  for (const tier of PLAN_ORDER) {
+    const cap = PLANS[tier].maxConcurrentConnections;
+    if (cap === null || requested <= cap) return tier;
+  }
+  return 'enterprise';
+}

package/src/schema/ddl.ts

@@ -318,7 +318,9 @@ export function generateProvisionPlan(
     for (const [fieldName, meta] of Object.entries(model.fields)) {
       const col = meta.column ?? camelToSnake(fieldName);
       if (BASE_COLUMNS.has(col) || col === orgCol) continue;
-      statements.push(`ALTER TABLE ${qt} ADD COLUMN IF NOT EXISTS ${q(col)} ${sqlType(meta.type)};`);
+      statements.push(
+        `ALTER TABLE ${qt} ADD COLUMN IF NOT EXISTS ${q(col)} ${sqlType(meta.type)}${meta.isOptional ? '' : ' NOT NULL'};`,
+      );
       if (meta.type === 'enum' && meta.enumValues && meta.enumValues.length > 0) {
         const cname = `${table}_${col}_enum`;
         const allowed = meta.enumValues.map((v) => `'${v.replace(/'/g, "''")}'`).join(', ');

package/src/schema/deployment/backfill.ts

@@ -0,0 +1,88 @@
+export type BackfillStatus = 'pending' | 'running' | 'paused' | 'succeeded' | 'failed' | 'cancelled';
+
+export interface BackfillCheckpoint {
+  readonly jobId: string;
+  readonly idempotencyKey: string;
+  readonly cursor: string | null;
+  readonly processed: number;
+  readonly batches: number;
+  readonly status: BackfillStatus;
+  readonly updatedAt: string;
+  readonly error?: string;
+}
+
+export interface BackfillBatchResult {
+  readonly nextCursor: string | null;
+  readonly processed: number;
+  readonly done: boolean;
+}
+
+export interface ResumableBackfillEffects {
+  readonly load: (jobId: string) => Promise<BackfillCheckpoint | null>;
+  readonly save: (checkpoint: BackfillCheckpoint) => Promise<void>;
+  /** Must be idempotent for the job idempotency key and input cursor. */
+  readonly runBatch: (input: { jobId: string; idempotencyKey: string; cursor: string | null; limit: number; signal?: AbortSignal }) => Promise<BackfillBatchResult>;
+  readonly now?: () => string;
+  readonly retry?: (error: unknown, attempt: number) => Promise<void>;
+  /** Operational throttle checked before each batch; pause preserves the checkpoint for an exact resume. */
+  readonly beforeBatch?: (checkpoint: BackfillCheckpoint) => Promise<'run' | 'pause'>;
+  readonly onProgress?: (checkpoint: BackfillCheckpoint) => Promise<void> | void;
+}
+
+export interface ResumableBackfillOptions {
+  readonly jobId: string;
+  readonly idempotencyKey: string;
+  readonly batchSize?: number;
+  readonly maxBatches?: number;
+  readonly maxAttempts?: number;
+  readonly signal?: AbortSignal;
+}
+
+/** Bounded, resumable runner. A durable effect owns checkpoints; the transform owns idempotency. */
+export async function runResumableBackfill(effects: ResumableBackfillEffects, options: ResumableBackfillOptions): Promise<BackfillCheckpoint> {
+  if (!options.jobId || !options.idempotencyKey) throw new Error('backfill jobId and idempotencyKey are required');
+  const batchSize = options.batchSize ?? 500;
+  const maxBatches = options.maxBatches ?? 100;
+  const maxAttempts = options.maxAttempts ?? 3;
+  if (batchSize < 1 || maxBatches < 1 || maxAttempts < 1) throw new Error('backfill bounds must be positive');
+  const now = effects.now ?? (() => new Date().toISOString());
+  let checkpoint = await effects.load(options.jobId) ?? { jobId: options.jobId, idempotencyKey: options.idempotencyKey, cursor: null, processed: 0, batches: 0, status: 'pending' as const, updatedAt: now() };
+  if (checkpoint.idempotencyKey !== options.idempotencyKey) throw new Error(`backfill job ${options.jobId} was created with a different idempotency key`);
+  if (checkpoint.status === 'succeeded') return checkpoint;
+  for (let batch = 0; batch < maxBatches; batch++) {
+    if (options.signal?.aborted) {
+      checkpoint = { ...checkpoint, status: 'cancelled', updatedAt: now() };
+      await effects.save(checkpoint);
+      return checkpoint;
+    }
+    if (await effects.beforeBatch?.(checkpoint) === 'pause') {
+      checkpoint = { ...checkpoint, status: 'paused', updatedAt: now() };
+      await effects.save(checkpoint);
+      await effects.onProgress?.(checkpoint);
+      return checkpoint;
+    }
+    let result: BackfillBatchResult | undefined;
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        result = await effects.runBatch({ jobId: options.jobId, idempotencyKey: options.idempotencyKey, cursor: checkpoint.cursor, limit: batchSize, ...(options.signal ? { signal: options.signal } : {}) });
+        break;
+      } catch (error) {
+        lastError = error;
+        if (attempt < maxAttempts) await effects.retry?.(error, attempt);
+      }
+    }
+    if (!result) {
+      checkpoint = { ...checkpoint, status: 'failed', updatedAt: now(), error: lastError instanceof Error ? lastError.message : String(lastError) };
+      await effects.save(checkpoint);
+      await effects.onProgress?.(checkpoint);
+      return checkpoint;
+    }
+    if (!result.done && result.nextCursor === checkpoint.cursor) throw new Error(`backfill job ${options.jobId} did not advance its cursor`);
+    checkpoint = { jobId: checkpoint.jobId, idempotencyKey: checkpoint.idempotencyKey, cursor: result.nextCursor, processed: checkpoint.processed + result.processed, batches: checkpoint.batches + 1, status: result.done ? 'succeeded' : 'running', updatedAt: now() };
+    await effects.save(checkpoint);
+    await effects.onProgress?.(checkpoint);
+    if (result.done) return checkpoint;
+  }
+  return checkpoint;
+}

package/src/schema/deployment/contracts.ts

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import type { SchemaJSON } from '../serialize.js';
+import type { BackfillValue, RenameHints } from '../diff.js';
+import type { MigrationStep } from '../diff.js';
+
+export const deploymentPhaseSchema = z.enum(['intent', 'expand', 'dual_write', 'backfill', 'verify', 'switch', 'contract', 'recover']);
+export type DeploymentPhase = z.infer<typeof deploymentPhaseSchema>;
+export const deploymentOwnerSchema = z.enum(['application', 'application_migration', 'ablo']);
+export type DeploymentOwner = z.infer<typeof deploymentOwnerSchema>;
+export const deploymentSeveritySchema = z.enum(['blocker', 'error', 'warning', 'info']);
+export type DeploymentSeverity = z.infer<typeof deploymentSeveritySchema>;
+export const deploymentCategorySchema = z.enum(['policy_intent', 'physical_contract', 'compatibility', 'data_movement', 'destructive_contract', 'advisory', 'observation']);
+export type DeploymentCategory = z.infer<typeof deploymentCategorySchema>;
+export const deploymentDirectionSchema = z.enum(['source_to_active', 'source_to_database', 'active_to_database', 'client_to_active']);
+export type DeploymentDirection = z.infer<typeof deploymentDirectionSchema>;
+
+export const databaseColumnSnapshotSchema = z.object({
+  name: z.string(), dataType: z.string(), nullable: z.boolean(), default: z.string().nullable(), primary: z.boolean(), unique: z.boolean(),
+  /** Capped count of rows whose required routing value is NULL; absent for ordinary columns. */
+  nullCount: z.number().int().nonnegative().nullable().optional(),
+});
+export type DatabaseColumnSnapshot = z.infer<typeof databaseColumnSnapshotSchema>;
+export const databaseIndexSnapshotSchema = z.object({
+  name: z.string(), columns: z.array(z.string()), unique: z.boolean(), valid: z.boolean(), ready: z.boolean(), predicate: z.string().nullable(),
+});
+export const databaseForeignKeySnapshotSchema = z.object({
+  name: z.string(), columns: z.array(z.string()), referencedSchema: z.string(), referencedTable: z.string(), referencedColumns: z.array(z.string()), validated: z.boolean(),
+});
+export const databaseTableSnapshotSchema = z.object({
+  schema: z.string(), name: z.string(), columns: z.record(z.string(), databaseColumnSnapshotSchema),
+  indexes: z.array(databaseIndexSnapshotSchema).optional(), foreignKeys: z.array(databaseForeignKeySnapshotSchema).optional(),
+  rowLevelSecurity: z.boolean().nullable(), forceRowLevelSecurity: z.boolean().nullable(),
+  replicaIdentity: z.string().nullable(), publicationMember: z.boolean().nullable(),
+});
+export type DatabaseTableSnapshot = z.infer<typeof databaseTableSnapshotSchema>;
+export const databaseSnapshotSchema = z.object({
+  observedAt: z.string(), subject: z.string(), fingerprint: z.string(), appSchema: z.string(), ownership: z.enum(['application', 'ablo']),
+  tables: z.record(z.string(), databaseTableSnapshotSchema),
+});
+export type DatabaseSnapshot = z.infer<typeof databaseSnapshotSchema>;
+
+export interface SourceSchemaSnapshot { readonly observedAt: string; readonly path: string; readonly hash: string; readonly schema: SchemaJSON; }
+export interface ActiveSchemaSnapshot { readonly observedAt: string; readonly schemaId: string; readonly version: number; readonly hash: string; readonly pushedAt: string | null; readonly schema: SchemaJSON; }
+export interface DeploymentTarget { readonly organizationId: string | null; readonly projectId: string | null; readonly branchId: string | null; readonly databaseSubject: string | null; readonly confirmed: boolean; }
+export const deploymentGateSchema = z.object({
+  id: z.string().min(1),
+  phase: z.enum(['expand', 'dual_write', 'backfill', 'verify', 'switch', 'contract']),
+  owner: deploymentOwnerSchema,
+  resource: z.string().min(1),
+  title: z.string().min(1),
+  action: z.string().min(1),
+  status: z.enum(['pending', 'ready', 'satisfied']),
+  dependsOn: z.array(z.string()).default([]),
+  approval: z.string().min(1).optional(),
+});
+export const deploymentManifestSchema = z.object({
+  id: z.string().min(1),
+  live: z.boolean().default(true),
+  targetPhase: z.enum(['expand', 'dual_write', 'backfill', 'verify', 'switch', 'contract']).default('expand'),
+  gates: z.array(deploymentGateSchema),
+});
+export type DeploymentGate = z.infer<typeof deploymentGateSchema>;
+export type DeploymentManifest = z.infer<typeof deploymentManifestSchema>;
+export interface DeploymentIntent { readonly renames?: RenameHints; readonly backfills?: readonly BackfillValue[]; readonly acceptDestructive?: boolean; readonly manifest?: DeploymentManifest; }
+export interface DeploymentObservation { readonly target: DeploymentTarget; readonly source: SourceSchemaSnapshot; readonly active: ActiveSchemaSnapshot | null; readonly database: DatabaseSnapshot | null; readonly intent?: DeploymentIntent; readonly supplementalFindings?: readonly DeploymentFinding[]; }
+
+export interface DeploymentFinding {
+  readonly id: string; readonly code: string; readonly category: DeploymentCategory; readonly severity: DeploymentSeverity;
+  readonly direction: DeploymentDirection; readonly phase: DeploymentPhase; readonly owner: DeploymentOwner;
+  readonly model?: string; readonly field?: string; readonly column?: string; readonly from?: unknown; readonly to?: unknown;
+  readonly message: string; readonly action: string;
+  readonly dependsOn?: readonly string[];
+}
+export interface DeploymentStep {
+  readonly id: string; readonly phase: DeploymentPhase; readonly owner: DeploymentOwner; readonly title: string; readonly action: string;
+  readonly dependsOn: readonly string[]; readonly findingIds: readonly string[]; readonly status: 'ready' | 'blocked' | 'advisory'; readonly executableByAblo: boolean;
+}
+export interface SchemaDeploymentPlan {
+  readonly id: 'ablo-schema-deployment-plan-v1'; readonly mode: 'plan'; readonly createdAt: string; readonly fingerprint: string; readonly target: DeploymentTarget;
+  readonly states: { readonly source: Omit<SourceSchemaSnapshot, 'schema'>; readonly active: Omit<ActiveSchemaSnapshot, 'schema'> | null; readonly database: Omit<DatabaseSnapshot, 'tables'> | null; };
+  readonly findings: readonly DeploymentFinding[]; readonly steps: readonly DeploymentStep[]; readonly outcome: 'aligned' | 'ready' | 'blocked';
+  readonly operations: { readonly sourceToActive: readonly MigrationStep[]; readonly provision: readonly MigrationStep[] };
+  readonly rollbackTarget: { readonly schemaId: string; readonly version: number; readonly hash: string; readonly strategy: 'reactivate_artifact'; } | null;
+  readonly recovery: 'rollback' | 'forward_only';
+}
+export interface DeploymentApplyResult { readonly plan: SchemaDeploymentPlan; readonly appliedStepIds: readonly string[]; readonly verification: SchemaDeploymentPlan; readonly recorded: boolean; }
+
+export const deploymentTargetSchema = z.object({
+  organizationId: z.string().nullable(), projectId: z.string().nullable(), branchId: z.string().nullable(), databaseSubject: z.string().nullable(), confirmed: z.boolean(),
+});
+export const deploymentFindingSchema = z.object({
+  id: z.string(), code: z.string(), category: deploymentCategorySchema, severity: deploymentSeveritySchema,
+  direction: deploymentDirectionSchema, phase: deploymentPhaseSchema, owner: deploymentOwnerSchema,
+  model: z.string().optional(), field: z.string().optional(), column: z.string().optional(), from: z.unknown().optional(), to: z.unknown().optional(),
+  message: z.string(), action: z.string(),
+  dependsOn: z.array(z.string()).readonly().optional(),
+});
+export const deploymentStepSchema = z.object({
+  id: z.string(), phase: deploymentPhaseSchema, owner: deploymentOwnerSchema, title: z.string(), action: z.string(),
+  dependsOn: z.array(z.string()).readonly(), findingIds: z.array(z.string()).readonly(), status: z.enum(['ready', 'blocked', 'advisory']), executableByAblo: z.boolean(),
+});
+export const schemaDeploymentPlanSchema = z.object({
+  id: z.literal('ablo-schema-deployment-plan-v1'), mode: z.literal('plan'), createdAt: z.string(), fingerprint: z.string(), target: deploymentTargetSchema,
+  states: z.object({
+    source: z.object({ observedAt: z.string(), path: z.string(), hash: z.string() }),
+    active: z.object({ observedAt: z.string(), schemaId: z.string(), version: z.number(), hash: z.string(), pushedAt: z.string().nullable() }).nullable(),
+    database: z.object({ observedAt: z.string(), subject: z.string(), fingerprint: z.string(), appSchema: z.string(), ownership: z.enum(['application', 'ablo']) }).nullable(),
+  }),
+  findings: z.array(deploymentFindingSchema).readonly(), steps: z.array(deploymentStepSchema).readonly(), outcome: z.enum(['aligned', 'ready', 'blocked']),
+  // Submitted operations are never executed. Apply re-observes and returns a
+  // server-built plan; this field is retained only to validate the full plan
+  // envelope and obtain its fingerprint.
+  operations: z.object({
+    sourceToActive: z.array(z.custom<MigrationStep>()).readonly(),
+    provision: z.array(z.custom<MigrationStep>()).readonly(),
+  }),
+  rollbackTarget: z.object({ schemaId: z.string(), version: z.number(), hash: z.string(), strategy: z.literal('reactivate_artifact') }).nullable(),
+  recovery: z.enum(['rollback', 'forward_only']),
+});

package/src/schema/deployment/fingerprint.ts

@@ -0,0 +1,13 @@
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+/** Stable non-cryptographic identity used only to detect a changed reviewed plan. */
+export function deploymentFingerprint(value: unknown): string {
+  const input = canonical(value);
+  let hash = 0xcbf29ce484222325n;
+  for (let index = 0; index < input.length; index++) { hash ^= BigInt(input.charCodeAt(index)); hash = BigInt.asUintN(64, hash * 0x100000001b3n); }
+  return `plan_${hash.toString(16).padStart(16, '0')}`;
+}

package/src/schema/deployment/index.ts

@@ -0,0 +1,132 @@
+import type { DeploymentApplyResult, DeploymentFinding, DeploymentObservation, DeploymentStep, SchemaDeploymentPlan } from './contracts.js';
+import { deploymentFingerprint } from './fingerprint.js';
+import { reconcileDeploymentManifest, reconcilePolicyIntent, reconcileSchemaToDatabase, reconcileSourceToActiveResult } from './reconcile.js';
+import { sequenceDeployment } from './sequence.js';
+
+export * from './contracts.js';
+export { deploymentFingerprint } from './fingerprint.js';
+export { reconcileClientToActive, reconcileDeploymentManifest, reconcilePolicyIntent, reconcileSchemaToDatabase, reconcileSourceToActive, reconcileSourceToActiveResult } from './reconcile.js';
+export { sequenceDeployment } from './sequence.js';
+export * from './backfill.js';
+export * from './postgresCatalog.js';
+
+function physicalEvidenceKey(finding: DeploymentFinding): string {
+  return JSON.stringify([
+    finding.code,
+    finding.category,
+    finding.severity,
+    finding.phase,
+    finding.owner,
+    finding.model,
+    finding.field,
+    finding.column,
+    finding.from,
+    finding.to,
+    finding.message,
+    finding.action,
+  ]);
+}
+
+function physicalResourceKey(finding: DeploymentFinding): string {
+  return JSON.stringify([finding.model, finding.column, finding.field]);
+}
+
+function planStates(observation: DeploymentObservation): SchemaDeploymentPlan['states'] {
+  const { schema: _sourceSchema, ...source } = observation.source;
+  const active = observation.active ? (({ schema: _activeSchema, ...state }) => state)(observation.active) : null;
+  const database = observation.database ? (({ tables: _tables, ...state }) => state)(observation.database) : null;
+  return { source, active, database };
+}
+
+/** The one pure reconciliation skeleton every lifecycle surface projects. */
+export function buildSchemaDeploymentPlan(observation: DeploymentObservation, now = new Date().toISOString()): SchemaDeploymentPlan {
+  const sourceToActive = reconcileSourceToActiveResult(
+    observation.active?.schema ?? null,
+    observation.source.schema,
+    observation.intent?.renames,
+    observation.intent?.backfills,
+    observation.database,
+  );
+  const provision = reconcileSourceToActiveResult(null, observation.source.schema).operations;
+  const sourceToDatabase = reconcileSchemaToDatabase(observation.source.schema, observation.database, 'source_to_database');
+  const sourcePhysicalEvidence = new Set(sourceToDatabase.map(physicalEvidenceKey));
+  const sourcePhysicalResources = new Set(sourceToDatabase.map(physicalResourceKey));
+  const activeDatabaseFindings = observation.active
+    ? reconcileSchemaToDatabase(observation.active.schema, observation.database, 'active_to_database')
+    : [];
+  const candidateAlignedActiveFindings: DeploymentFinding[] = [];
+  const activeToDatabase = activeDatabaseFindings.filter((finding) => {
+    if (sourcePhysicalEvidence.has(physicalEvidenceKey(finding))) return false;
+    if (!sourcePhysicalResources.has(physicalResourceKey(finding))) {
+      candidateAlignedActiveFindings.push(finding);
+      return false;
+    }
+    return true;
+  });
+  const candidateAlignmentEvidence: DeploymentFinding[] = candidateAlignedActiveFindings.length === 0 ? [] : [{
+    id: 'active_to_database:candidate_alignment_verified',
+    code: 'candidate_alignment_verified',
+    category: 'observation',
+    severity: 'info',
+    direction: 'active_to_database',
+    phase: 'verify',
+    owner: observation.database?.ownership === 'ablo' ? 'ablo' : 'application_migration',
+    from: { activePhysicalDifferences: candidateAlignedActiveFindings.length },
+    to: 'source_database_alignment',
+    message: `PostgreSQL differs from the active artifact at ${candidateAlignedActiveFindings.length} physical contract location(s), and the candidate source already matches those locations.`,
+    action: 'Treat these differences as completed expand work; review the remaining source-to-active compatibility findings before activation.',
+  }];
+  const findings = [
+    ...reconcilePolicyIntent(observation.source.schema),
+    ...reconcileDeploymentManifest(observation.intent?.manifest),
+    ...sourceToActive.findings,
+    ...sourceToDatabase,
+    ...activeToDatabase,
+    ...candidateAlignmentEvidence,
+    ...(observation.supplementalFindings ?? []),
+  ];
+  const unique = [...new Map(findings.map((finding) => [finding.id, finding])).values()].map((finding) =>
+    observation.intent?.acceptDestructive && finding.category === 'destructive_contract' &&
+      finding.code !== 'mixed_expand_contract' && finding.code !== 'contract_approval_required' && finding.code !== 'lifecycle_dependency_unsatisfied'
+      ? { ...finding, severity: 'warning' as const, action: `${finding.action} Destructive intent was explicitly accepted for this reviewed plan.` }
+      : finding
+  );
+  const steps = sequenceDeployment(unique);
+  const blocking = unique.some(({ severity }) => severity === 'blocker' || severity === 'error');
+  const meaningful = unique.some(({ category }) => category !== 'advisory');
+  const states = planStates(observation);
+  const destructive = unique.some(({ category }) => category === 'destructive_contract');
+  const rollbackTarget = observation.active && !destructive ? { schemaId: observation.active.schemaId, version: observation.active.version, hash: observation.active.hash, strategy: 'reactivate_artifact' as const } : null;
+  const fingerprint = deploymentFingerprint({
+    target: observation.target,
+    states: {
+      source: { hash: states.source.hash },
+      active: states.active ? { schemaId: states.active.schemaId, version: states.active.version, hash: states.active.hash } : null,
+      database: states.database ? { subject: states.database.subject, fingerprint: states.database.fingerprint, ownership: states.database.ownership } : null,
+    },
+    intent: observation.intent ?? {}, findings: unique, steps, operations: { sourceToActive: sourceToActive.operations, provision },
+  });
+  return { id: 'ablo-schema-deployment-plan-v1', mode: 'plan', createdAt: now, fingerprint, target: observation.target, states, findings: unique, steps, operations: { sourceToActive: sourceToActive.operations, provision }, outcome: blocking ? 'blocked' : meaningful ? 'ready' : 'aligned', rollbackTarget, recovery: rollbackTarget ? 'rollback' : 'forward_only' };
+}
+
+export interface SchemaDeploymentLifecycleEffects {
+  readonly observe: () => Promise<DeploymentObservation>;
+  readonly approve?: (plan: SchemaDeploymentPlan) => Promise<boolean>;
+  readonly apply?: (step: DeploymentStep, plan: SchemaDeploymentPlan) => Promise<void>;
+  readonly record?: (result: Omit<DeploymentApplyResult, 'recorded'>) => Promise<void>;
+}
+
+/** One observe → reconcile → sequence → approve → apply → verify → record path. */
+export async function runSchemaDeploymentLifecycle(effects: SchemaDeploymentLifecycleEffects, mode: 'plan' | 'apply' = 'plan'): Promise<SchemaDeploymentPlan | DeploymentApplyResult> {
+  const plan = buildSchemaDeploymentPlan(await effects.observe());
+  if (mode === 'plan') return plan;
+  if (plan.outcome === 'blocked') throw new Error(`schema deployment plan ${plan.fingerprint} is blocked`);
+  if (!effects.apply) throw new Error('schema deployment apply effect is not configured');
+  if (effects.approve && !(await effects.approve(plan))) throw new Error('schema deployment was not approved');
+  const appliedStepIds: string[] = [];
+  for (const step of plan.steps) if (step.executableByAblo && step.status === 'ready') { await effects.apply(step, plan); appliedStepIds.push(step.id); }
+  const verification = buildSchemaDeploymentPlan(await effects.observe());
+  const unrecorded = { plan, appliedStepIds, verification };
+  await effects.record?.(unrecorded);
+  return { ...unrecorded, recorded: effects.record !== undefined };
+}

package/src/schema/deployment/postgresCatalog.ts

@@ -0,0 +1,131 @@
+import type { DatabaseTableSnapshot } from './contracts.js';
+
+export interface PostgresColumnCatalogRow {
+  tableName: string;
+  columnName: string;
+  dataType: string;
+  nullable: boolean;
+  defaultValue: string | null;
+  primary: boolean;
+  uniqueColumn: boolean;
+  rowLevelSecurity: boolean;
+  forceRowLevelSecurity: boolean;
+  replicaIdentity: string;
+  publicationMember: boolean;
+}
+
+export interface PostgresIndexCatalogRow {
+  tableName: string;
+  indexName: string;
+  columns: string[];
+  uniqueIndex: boolean;
+  valid: boolean;
+  ready: boolean;
+  predicate: string | null;
+}
+
+export interface PostgresForeignKeyCatalogRow {
+  tableName: string;
+  constraintName: string;
+  columns: string[];
+  referencedSchema: string;
+  referencedTable: string;
+  referencedColumns: string[];
+  validated: boolean;
+}
+
+export const POSTGRES_COLUMN_CATALOG_SQL = `
+  SELECT c.relname AS "tableName", a.attname AS "columnName",
+    format_type(a.atttypid, a.atttypmod) AS "dataType", NOT a.attnotnull AS nullable,
+    pg_get_expr(d.adbin, d.adrelid) AS "defaultValue",
+    EXISTS (SELECT 1 FROM pg_constraint k WHERE k.conrelid = c.oid AND k.contype = 'p' AND cardinality(k.conkey) = 1 AND a.attnum = ANY(k.conkey)) AS primary,
+    EXISTS (SELECT 1 FROM pg_constraint k WHERE k.conrelid = c.oid AND k.contype IN ('p','u') AND cardinality(k.conkey) = 1 AND a.attnum = ANY(k.conkey)) AS "uniqueColumn",
+    c.relrowsecurity AS "rowLevelSecurity", c.relforcerowsecurity AS "forceRowLevelSecurity",
+    c.relreplident::text AS "replicaIdentity",
+    EXISTS (SELECT 1 FROM pg_publication_tables p WHERE p.schemaname = n.nspname AND p.tablename = c.relname) AS "publicationMember"
+  FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+  JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+  LEFT JOIN pg_attrdef d ON d.adrelid = c.oid AND d.adnum = a.attnum
+  WHERE n.nspname = $1 AND c.relkind IN ('r','p') ORDER BY c.relname, a.attnum
+`;
+
+export const POSTGRES_INDEX_CATALOG_SQL = `
+  SELECT t.relname AS "tableName", i.relname AS "indexName",
+    ARRAY(SELECT a.attname FROM unnest(ix.indkey) WITH ORDINALITY keys(attnum, ord) JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = keys.attnum ORDER BY keys.ord) AS columns,
+    ix.indisunique AS "uniqueIndex", ix.indisvalid AS valid, ix.indisready AS ready,
+    pg_get_expr(ix.indpred, ix.indrelid) AS predicate
+  FROM pg_index ix JOIN pg_class t ON t.oid = ix.indrelid JOIN pg_class i ON i.oid = ix.indexrelid
+  JOIN pg_namespace n ON n.oid = t.relnamespace WHERE n.nspname = $1 ORDER BY t.relname, i.relname
+`;
+
+export const POSTGRES_FOREIGN_KEY_CATALOG_SQL = `
+  SELECT t.relname AS "tableName", c.conname AS "constraintName",
+    ARRAY(SELECT a.attname FROM unnest(c.conkey) WITH ORDINALITY keys(attnum, ord) JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = keys.attnum ORDER BY keys.ord) AS columns,
+    rn.nspname AS "referencedSchema", rt.relname AS "referencedTable",
+    ARRAY(SELECT a.attname FROM unnest(c.confkey) WITH ORDINALITY keys(attnum, ord) JOIN pg_attribute a ON a.attrelid = c.confrelid AND a.attnum = keys.attnum ORDER BY keys.ord) AS "referencedColumns",
+    c.convalidated AS validated
+  FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid JOIN pg_namespace n ON n.oid = t.relnamespace
+  JOIN pg_class rt ON rt.oid = c.confrelid JOIN pg_namespace rn ON rn.oid = rt.relnamespace
+  WHERE c.contype = 'f' AND n.nspname = $1 ORDER BY t.relname, c.conname
+`;
+
+export function quotePostgresIdentifier(value: string): string {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+export function postgresNullCountSql(appSchema: string, table: string, column: string): string {
+  const qualified = `${quotePostgresIdentifier(appSchema)}.${quotePostgresIdentifier(table)}`;
+  return `SELECT count(*)::int AS n FROM (SELECT 1 FROM ${qualified} WHERE ${quotePostgresIdentifier(column)} IS NULL LIMIT 501) unstamped`;
+}
+
+export function foldPostgresCatalog(
+  appSchema: string,
+  columns: readonly PostgresColumnCatalogRow[],
+  indexes: readonly PostgresIndexCatalogRow[],
+  foreignKeys: readonly PostgresForeignKeyCatalogRow[],
+): Record<string, DatabaseTableSnapshot> {
+  const tables: Record<string, DatabaseTableSnapshot> = {};
+  for (const row of columns) {
+    const table = tables[row.tableName] ?? {
+      schema: appSchema,
+      name: row.tableName,
+      columns: {},
+      indexes: [],
+      foreignKeys: [],
+      rowLevelSecurity: row.rowLevelSecurity,
+      forceRowLevelSecurity: row.forceRowLevelSecurity,
+      replicaIdentity: row.replicaIdentity,
+      publicationMember: row.publicationMember,
+    };
+    table.columns[row.columnName] = {
+      name: row.columnName,
+      dataType: row.dataType,
+      nullable: row.nullable,
+      default: row.defaultValue,
+      primary: row.primary,
+      unique: row.uniqueColumn,
+    };
+    tables[row.tableName] = table;
+  }
+  for (const row of indexes) {
+    tables[row.tableName]?.indexes?.push({
+      name: row.indexName,
+      columns: row.columns,
+      unique: row.uniqueIndex,
+      valid: row.valid,
+      ready: row.ready,
+      predicate: row.predicate,
+    });
+  }
+  for (const row of foreignKeys) {
+    tables[row.tableName]?.foreignKeys?.push({
+      name: row.constraintName,
+      columns: row.columns,
+      referencedSchema: row.referencedSchema,
+      referencedTable: row.referencedTable,
+      referencedColumns: row.referencedColumns,
+      validated: row.validated,
+    });
+  }
+  return tables;
+}