fix(planner): emit executable DDL for NOT NULL columns on non-empty tables

docs/architecture docs/subsystems/7. Migration System.md

@@ -298,6 +298,16 @@ For CLI usage, output formats, and common failure modes, see the canonical comma
 
 Greenfield, brownfield-conservative, and brownfield-incremental paths are supported. Baselines help bootstrap fresh environments; incremental adoption expands contract coverage safely over time. See [ADR 122 — Database Initialization & Adoption](../adrs/ADR%20122%20-%20Database%20Initialization%20&%20Adoption.md).
 
+### `db update` (live reconciliation)
+
+`prisma-next db update` is the **reconciliation** entrypoint. It introspects the live database schema, diffs it against the destination contract, and applies the resulting operations.
+
+Unlike `migration apply`, which replays serialized edges, `db update` always works from a live introspection. Plans produced by the planner carry `origin: null` (no prior-state assertion). The runner treats this as "trust the planner": operations are always applied regardless of marker state. This ensures `db update` can recover from schema drift — for example, when a DBA manually drops a column, the planner detects the missing column and re-adds it even though the contract marker already matches the destination hash.
+
+By contrast, `migration apply` constructs plans with `origin: { storageHash }` from the migration chain. When the marker matches the destination, the runner skips operations (the migration was already applied). This provides safe idempotent replays.
+
+**NOT NULL columns without defaults.** The planner first resolves a temporary default by consulting codec hooks (for parameterized or extension-owned types) and then built-in fallbacks (`''` for text, `0` for integers, `false` for booleans, `'{}'` for arrays, `''::tsvector` for `tsvector`, length-aware zero literals for `bit(n)`, etc.). When a safe literal is available, it emits a reusable 2-step recipe: add the column with the temporary default, then drop the default immediately after. Existing rows permanently retain the backfilled value; future inserts must provide an explicit value. When no safe temporary default is known, the planner falls back to the empty-table precheck path.
+
 ## Multi-Service Namespacing
 
 Per-service markers allow independent contracts within a single physical database (e.g., Postgres schemas). Each service has its own `prisma_contract.marker`; permissions and verification remain isolated. For engines without schemas, use separate databases. See namespacing notes in [ADR 021 — Contract Marker Storage](../adrs/ADR%20021%20-%20Contract%20Marker%20Storage.md).
@@ -333,5 +343,3 @@ Provide:
 - edges/<edgeId>/migration.json — manifests with ops and checks; optional tasks modules
 - graph.index.json (optional) — committed graph index when enabled
 - digests — content hashes for integrity
-
-

packages/2-sql/3-tooling/family/src/core/migrations/types.ts

@@ -164,6 +164,16 @@ export interface ExpandNativeTypeInput {
   readonly typeParams?: Record<string, unknown>;
 }
 
+/**
+ * Input for resolving a temporary SQL literal used to backfill existing rows when
+ * adding a NOT NULL column without an explicit default.
+ */
+export interface ResolveTemporaryDefaultLiteralInput {
+  readonly nativeType: string;
+  readonly codecId?: string;
+  readonly typeParams?: Record<string, unknown>;
+}
+
 export interface CodecControlHooks<TTargetDetails = unknown> {
   planTypeOperations?: (options: {
     readonly typeName: string;
@@ -194,6 +204,18 @@ export interface CodecControlHooks<TTargetDetails = unknown> {
    * Returns the expanded type string, or the original nativeType if no expansion is needed.
    */
   expandNativeType?: (input: ExpandNativeTypeInput) => string;
+  /**
+   * Resolves a temporary SQL literal for safely adding a NOT NULL column without an explicit
+   * default to a non-empty table.
+   *
+   * Return semantics:
+   * - string: use this literal
+   * - null: explicitly no safe temporary default is known; fall back to another strategy
+   * - undefined: no opinion; planner may use built-in fallbacks
+   */
+  resolveTemporaryDefaultLiteral?: (
+    input: ResolveTemporaryDefaultLiteralInput,
+  ) => string | null | undefined;
 }
 
 export interface SqlControlExtensionDescriptor<TTargetId extends string>

packages/2-sql/3-tooling/family/src/exports/control.ts

@@ -47,6 +47,7 @@ export type {
   CreateSqlMigrationPlanOptions,
   ExpandNativeTypeInput,
   PslScalarTypeDescriptor,
+  ResolveTemporaryDefaultLiteralInput,
   SqlControlAdapterDescriptor,
   SqlControlExtensionDescriptor,
   SqlControlStaticContributions,

packages/3-extensions/pgvector/src/exports/control.ts

@@ -7,6 +7,18 @@ import { pgvectorOperationSignature, pgvectorPackMeta } from '../core/descriptor
 
 const PGVECTOR_CODEC_ID = 'pg/vector@1' as const;
 
+function buildZeroVectorTemporaryDefaultLiteral(
+  typeParams: Record<string, unknown> | undefined,
+): string | null {
+  const length = typeParams?.['length'];
+  if (typeof length !== 'number' || !Number.isInteger(length) || length <= 0) {
+    return null;
+  }
+
+  const zeroVector = `[${new Array(length).fill('0').join(',')}]`;
+  return `'${zeroVector}'::vector`;
+}
+
 const vectorControlPlaneHooks: CodecControlHooks = {
   expandNativeType: ({ nativeType, typeParams }) => {
     const length = typeParams?.['length'];
@@ -15,6 +27,8 @@ const vectorControlPlaneHooks: CodecControlHooks = {
     }
     return nativeType;
   },
+  resolveTemporaryDefaultLiteral: ({ typeParams }) =>
+    buildZeroVectorTemporaryDefaultLiteral(typeParams),
 };
 
 const pgvectorDatabaseDependencies: ComponentDatabaseDependencies<unknown> = {