@abloatai/transaction 0.57.0 → 0.59.0

package/src/observability.ts

@@ -1,8 +1,8 @@
 /**
  * The observability the confirmation core reports on its own behalf.
  *
- * Coordination outcomes — a claim changing state, a stale-write collision that
- * notified instead of aborting — happen with no UI and no local store anywhere,
+ * Coordination outcomes — a claim changing state or a rejected write collision
+ * — happen with no UI and no local store anywhere,
  * so the core must be able to report them without depending on the consumer's
  * full provider (ADR 0016).
  *
@@ -11,13 +11,13 @@
  * this interface, so a single implementation still satisfies both.
  */
 
-import type { ClaimEvent, ConflictEvent } from './coordination/events.js';
+import type { ClaimEvent, ConflictEvent } from './claims/events.js';
 
 export interface CoordinationObservability {
   /** Capture a claim state change (acquired / queued / granted / lost / rejected / expired). */
   captureClaim(event: ClaimEvent): void;
 
-  /** Capture a notify-instead-of-abort stale-write collision. */
+  /** Capture a rejected stale-write or foreign-claim collision. */
   captureConflict(event: ConflictEvent): void;
 }
 

package/src/{wire/delta.ts → observation/contract.ts}

@@ -6,7 +6,7 @@
  * layer, alongside the other protocol shapes in `wire/`.
  *
  * The wire delta is a projection of the stored `sync_deltas` row (the
- * `syncDeltaRowSchema` in `../log/syncDeltaRow.ts`) and differs from it
+ * `syncDeltaRowSchema` in `./persistence/syncDeltaRow.ts`) and differs from it
  * in three ways: it omits `organizationId` (the tenant-isolation predicate is
  * never broadcast), it uses the full action vocabulary (see
  * {@link syncDeltaActionSchema}) rather than plain create, update, and delete, and
@@ -26,7 +26,7 @@
  */
 
 import { z } from 'zod';
-import { correlationIdSchema } from './commit.js';
+import { correlationIdSchema } from '../commit/contract.js';
 import { participantKindSchema } from '../coordination/schema.js';
 import type { ParticipantKind, ParticipantRef } from '../types/participant.js';
 import type { AssertExact } from '../types/assertExact.js';

package/src/{wire/feedEvent.ts → observation/feedContract.ts}

@@ -14,9 +14,9 @@
  */
 
 import { z } from 'zod';
-import { logEventSchema, logOpSchema, type LogEvent } from './accountResponses.js';
-import { claimEventSchema, type ClaimEvent } from './claimEvent.js';
-import { listEnvelopeSchema, type ListEnvelope } from './listEnvelope.js';
+import { logEventSchema, logOpSchema, type LogEvent } from '../wire/accountResponses.js';
+import { claimEventSchema, type ClaimEvent } from '../claims/eventContract.js';
+import { listEnvelopeSchema, type ListEnvelope } from '../wire/listEnvelope.js';
 
 /**
  * One entry, from either source. Discriminated on `object`, so a consumer
@@ -71,4 +71,3 @@ export type LogQuery = z.infer<typeof logQuerySchema>;
  * What is here is the definition the producer will fill: the union parses
  * today's pages unchanged, and the cursor already carries the second position.
  */
-

package/src/{transport → observation}/httpFeed.ts

@@ -1,9 +1,9 @@
-import { formatFeedCursor, parseFeedCursor } from '../wire/feedCursor.js';
-import type { HttpLogsResource } from '../resources/httpResources.js';
+import { formatFeedCursor, parseFeedCursor } from './cursor.js';
+import type { HttpLogsResource } from '../client/resources/httpResources.js';
 import type {
   ObserveOptions,
   ObservedDelta,
-} from '../transactionLayer.js';
+} from '../client/contract.js';
 
 const DEFAULT_PAGE_SIZE = 100;
 const DEFAULT_POLL_INTERVAL_MS = 500;

package/src/observation/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Observation subsystem.
+ *
+ * Start here and descend through delta contracts, feed contracts, cursor
+ * handling, delivery inspection, HTTP polling, and persisted row projection.
+ */
+export * from './contract.js';
+export * from './cursor.js';
+export * from './feedContract.js';
+export * from './deliveryContract.js';
+export * from './httpFeed.js';
+export * from './persistence/syncDeltaRow.js';

package/src/{log → observation/persistence}/syncDeltaRow.ts

@@ -16,25 +16,25 @@
  * incorrectly as a physical-residency guarantee.
  *
  * This is the stored shape. The delta broadcast to clients is a narrower projection
- * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
+ * of it — see {@link import('../contract.js').syncDeltaWireCoreSchema} — and
  * the field names here mirror those on that wire delta.
  */
 
 import { z } from 'zod';
-import type { ModelResidency } from '../schema/residency.js';
+import type { ModelResidency } from '../../schema/residency.js';
 import {
   participantKindSchema,
   confirmationStateSchema,
   syncDeltaActionSchema,
-} from '../wire/delta.js';
+} from '../contract.js';
 
 // ── Enumerations that mirror the corresponding Postgres enum types ────────────
 
 // `participant_kind` and `confirmation_state` are shared with the wire delta and
-// live at the wire layer (see `../wire/delta.js`); they are re-exported here so
+// live in the observation contract (see `../contract.js`); they are re-exported here so
 // code that imports them from `schema` keeps resolving.
-export { participantKindSchema, confirmationStateSchema } from '../wire/delta.js';
-export type { ParticipantKind, ConfirmationState } from '../wire/delta.js';
+export { participantKindSchema, confirmationStateSchema } from '../contract.js';
+export type { ParticipantKind, ConfirmationState } from '../contract.js';
 
 /** `backfill_provenance` */
 export const backfillProvenanceSchema = z.enum(['exact', 'inferred', 'unknown']);
@@ -116,4 +116,3 @@ export const DELTA_PHYSICAL_STORAGE = {
   core: 'control',
   attribution: 'control',
 } as const satisfies Record<string, ModelResidency>;
-

package/src/pricing.ts

@@ -28,10 +28,9 @@
  * invoice, because raising one number does not fail anything that pins the
  * other.
  *
- * Storage is deliberately absent from {@link billableAxisSchema}. It is a real
- * recurring cost and it is quoted per tier as a ceiling, but no per-organization
- * bytes sampler emits it yet, and pricing a dimension nothing measures would be
- * a claim the invoice cannot support. Add the axis when the sampler ships.
+ * Audit-log storage is quoted as an included allowance plus Scale overage. It
+ * remains separate from the request meter because GiB-months come from a
+ * periodic storage sampler rather than an API event.
  */
 
 import { z } from 'zod';
@@ -47,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-07-31';
+export const PRICING_VERSION = '2026-08-28';
 
 /**
  * Resolve a stored plan string (`stripe_subscription.plan`) to a tier.
@@ -66,8 +65,8 @@ export function toPlanTier(plan: string | null | undefined): PlanTier {
 }
 
 /**
- * The axes a bill is actually computed from: `ops` is metered, `connections` is
- * capped. Storage is quoted but not billed, so it is not here.
+ * The request-time axes: `ops` is metered and `connections` is capped. Audit
+ * storage is sampled periodically, so it does not map from a request event.
  */
 export const billableAxisSchema = z.enum(['ops', 'connections']);
 export type BillableAxis = z.infer<typeof billableAxisSchema>;
@@ -184,11 +183,12 @@ const rateCardSchema = z
  * knob; the bracket structure is the contract.
  */
 export const OPS_RATE_CARD: readonly RateBracket[] = rateCardSchema.parse([
-  { throughOps: 50_000_000, usdPerMillionOps: 2.0 },
-  { throughOps: 500_000_000, usdPerMillionOps: 1.2 },
-  { throughOps: null, usdPerMillionOps: 0.6 },
+  { throughOps: null, usdPerMillionOps: 5 },
 ]);
 
+/** Scale audit-log storage above the included allowance, per GiB-month. */
+export const AUDIT_LOG_STORAGE_USD_PER_GIB_MONTH = 1;
+
 /**
  * A tier. `null` on a floor, a cap, or a quota means negotiated rather than
  * unlimited, and the runtime treats it as "no typed default, use the operator's
@@ -206,9 +206,9 @@ export const planDefinitionSchema = z.object({
    */
   monthlyMinimumUsd: z.number().nonnegative().nullable(),
   /**
-   * A hard monthly stop on operations. Set only where the tier is not billed at
-   * all: Free is capped rather than metered, so exceeding it is refused instead
-   * of invoiced. `null` on every metered tier.
+   * The no-billing monthly stop. On Free this is also the included allowance:
+   * organizations without billing enabled stop here, while organizations that
+   * enable billing pay only for operations above it. `null` on paid tiers.
    */
   hardCapOps: z.number().int().positive().nullable(),
   /**
@@ -220,7 +220,7 @@ export const planDefinitionSchema = z.object({
    * are billed rather than stopped.
    */
   hardCapOpsPerDay: z.number().int().positive().nullable(),
-  /** Quoted ceiling on stored data, in GiB. Not billed. `null` is negotiated. */
+  /** Included audit-log storage, in GiB. `null` means contract-priced capacity. */
   storageGib: z.number().positive().nullable(),
   /** Hard concurrent-connection cap, the real Free to Scale boundary. */
   maxConcurrentConnections: z.number().int().positive().nullable(),
@@ -240,7 +240,7 @@ export const PLANS = z
     free: {
       tier: 'free',
       label: 'Free',
-      summary: 'Build against the real engine without a card.',
+      summary: 'Free for early-stage teams building against the real engine.',
       monthlyMinimumUsd: 0,
       hardCapOps: 100_000,
       hardCapOpsPerDay: 10_000,
@@ -252,20 +252,20 @@ export const PLANS = z
     scale: {
       tier: 'scale',
       label: 'Scale',
-      summary: 'Production traffic, metered above a monthly floor.',
-      monthlyMinimumUsd: 20,
+      summary: 'Built for scaling teams with production traffic.',
+      monthlyMinimumUsd: 250,
       hardCapOps: null,
       hardCapOpsPerDay: null,
       storageGib: 50,
-      maxConcurrentConnections: 1_000,
+      maxConcurrentConnections: 5_000,
       contractPriced: false,
       features: ['auditExport'],
     },
     enterprise: {
       tier: 'enterprise',
       label: 'Enterprise',
-      summary: 'Committed volume, private networking, and an uptime guarantee.',
-      monthlyMinimumUsd: 2_000,
+      summary: 'Custom infrastructure, security, and support for critical workloads.',
+      monthlyMinimumUsd: 4_000,
       hardCapOps: null,
       hardCapOpsPerDay: null,
       storageGib: null,
@@ -336,8 +336,8 @@ export function opsForUsd(usd: number): number {
 }
 
 /**
- * The operations a tier includes, as shown on the pricing page. A capped tier
- * shows its cap; a metered tier shows what its floor covers, computed from the
+ * The operations a tier includes, as shown on the pricing page. Free shows its
+ * pay-as-you-go allowance; a tier with a floor shows what that floor covers, computed from the
  * floor rather than stored beside it. `null` where the terms are contractual.
  */
 export function monthlyOpsAllowance(tier: PlanTier): number | null {
@@ -348,17 +348,38 @@ export function monthlyOpsAllowance(tier: PlanTier): number | null {
 }
 
 /**
- * The invoice for a month: the floor, or the metered usage, whichever is
- * greater. A capped tier is never billed above its floor because the cap is
- * enforced before the usage exists. `null` where the terms are contractual.
+ * The invoice for a month. Free subtracts its included operations before
+ * applying the rate. Scale charges the floor or metered usage, whichever is
+ * greater. `null` where the terms are contractual.
  */
 export function monthlyBillUsd(tier: PlanTier, ops: number): number | null {
   const plan = PLANS[tier];
   if (plan.contractPriced || plan.monthlyMinimumUsd === null) return null;
-  if (plan.hardCapOps !== null) return plan.monthlyMinimumUsd;
+  if (plan.hardCapOps !== null) {
+    return roundUsd(usdForOps(Math.max(0, ops - plan.hardCapOps)));
+  }
   return roundUsd(Math.max(plan.monthlyMinimumUsd, usdForOps(ops)));
 }
 
+/**
+ * Audit-log storage overage for a month. Free and Scale meter only the GiB
+ * above their included amount, and Enterprise is priced in the contract.
+ */
+export function auditLogStorageBillUsd(tier: PlanTier, storageGib: number): number | null {
+  const plan = PLANS[tier];
+  if (plan.contractPriced || plan.storageGib === null) return null;
+  if (!Number.isFinite(storageGib)) return 0;
+  return roundUsd(Math.max(0, storageGib - plan.storageGib) * AUDIT_LOG_STORAGE_USD_PER_GIB_MONTH);
+}
+
+/** The complete published estimate across operation and audit-storage usage. */
+export function monthlyEstimateUsd(tier: PlanTier, ops: number, auditStorageGib: number): number | null {
+  const operationsBill = monthlyBillUsd(tier, ops);
+  const storageBill = auditLogStorageBillUsd(tier, auditStorageGib);
+  if (operationsBill === null || storageBill === null) return null;
+  return roundUsd(operationsBill + storageBill);
+}
+
 /**
  * The daily operations cap for a tier: the typed default the quota gate falls
  * back to when no `plan_limit` row sets one. `null` means the tier is metered
@@ -376,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,81 @@
+import type { DeploymentApplyResult, 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 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,
+  );
+  const provision = reconcileSourceToActiveResult(null, observation.source.schema).operations;
+  const findings = [
+    ...reconcilePolicyIntent(observation.source.schema),
+    ...reconcileDeploymentManifest(observation.intent?.manifest),
+    ...sourceToActive.findings,
+    ...reconcileSchemaToDatabase(observation.source.schema, observation.database, 'source_to_database'),
+    ...(observation.active ? reconcileSchemaToDatabase(observation.active.schema, observation.database, 'active_to_database') : []),
+    ...(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 };
+}