@mandujs/core 0.21.0 → 0.22.0

package/src/resource/ddl/persistence-types.ts

@@ -0,0 +1,218 @@
+/**
+ * Phase 4c — Extended persistence options for `ResourceDefinition`.
+ *
+ * # Why a separate file (not module augmentation)?
+ *
+ * Module-augmenting `ResourceOptions.persistence` would pollute the shape
+ * of `ResourceDefinition` for every consumer of `@mandujs/core` — including
+ * apps that never opt into persistence. The augmentation would also load
+ * DDL-specific symbols into the global type graph, which is exactly what
+ * the `ddl/` subdirectory isolation is trying to prevent.
+ *
+ * Instead we keep persistence options as an INDEPENDENT type and narrow at
+ * the use site (`snapshotFromResources`). `ResourceDefinition.options.persistence`
+ * is typed as `unknown` by the public schema; this module's `asPersistence()`
+ * is the single type-check gate. This preserves backward compatibility —
+ * existing resource files without `persistence` keep working — while
+ * giving the DDL layer a fully-typed view.
+ *
+ * # Identifier validation
+ *
+ * All identifier-shaped fields (`tableName`, `fieldOverrides[key].columnName`,
+ * `indexes[].name`) are validated against {@link SAFE_PERSISTENCE_IDENTIFIER_RE}
+ * at narrowing time. This is defense-in-depth in addition to `quoteIdent`:
+ *   - `quoteIdent` catches SQL-injection characters (double quotes, backticks,
+ *     NUL bytes) — but only when the value reaches DDL emission.
+ *   - The same values ALSO feed `path.join` calls in `writeSchemaArtifacts`
+ *     (`.mandu/generated/server/schema/{tableName}.sql`) and could otherwise
+ *     allow path traversal via `..`, `/`, or `\` in the declared name.
+ *   - Restricting to `[A-Za-z_][A-Za-z0-9_]*` closes both surfaces uniformly
+ *     and matches the constraint already enforced on `definition.name` by
+ *     `validateResourceDefinition` in schema.ts.
+ *
+ * References:
+ *   - docs/rfcs/0001-db-resource-layer.md §4 D1 (opt-in persistence field)
+ *   - docs/rfcs/0001-db-resource-layer.md Appendix D.1 (dialect divergence)
+ *   - docs/security/phase-4c-audit.md §H-01 (path traversal remediation)
+ *   - packages/core/src/resource/ddl/types.ts (canonical DDL contract)
+ */
+
+import type { SqlProvider, DdlDefault, DdlIndex } from "./types";
+
+// ============================================
+// Identifier validation
+// ============================================
+
+/**
+ * The set of names allowed for DDL identifiers that originate from
+ * user-authored resource options (`tableName`, `columnName`, index
+ * `name`). Starts with a letter or underscore, followed by letters,
+ * digits, or underscores — i.e. the portable SQL identifier subset
+ * that is also safe to interpolate into a filesystem path segment.
+ *
+ * Rejects:
+ *   - path separators (`/`, `\`) — prevents path traversal via
+ *     `writeSchemaArtifacts` which writes `{tableName}.sql`.
+ *   - `..`, `.` — parent/current directory markers.
+ *   - whitespace and control characters — break both filesystems and
+ *     terminal rendering in CLI output.
+ *   - quote characters — redundant with `quoteIdent` but cheaper to
+ *     reject early than per-dialect at emit time.
+ *
+ * Tightness rationale: we prefer a whitelist over a blacklist because
+ * OS + dialect quoting behavior varies; a whitelist aligns the two and
+ * stays simple to reason about.
+ */
+export const SAFE_PERSISTENCE_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Upper bound — mirrors `emit.ts:MAX_IDENT_LENGTH` so DDL identifiers
+ * never grow past the tighter of PG (63) / MySQL (64) limits. Enforcing
+ * it here gives a clearer error than the downstream emit-time throw.
+ */
+const MAX_PERSISTENCE_IDENTIFIER_LENGTH = 63;
+
+function assertSafeIdentifier(kind: string, value: string): void {
+  if (value.length === 0) {
+    throw new TypeError(`options.persistence.${kind} must not be empty`);
+  }
+  if (value.length > MAX_PERSISTENCE_IDENTIFIER_LENGTH) {
+    throw new TypeError(
+      `options.persistence.${kind} too long (${value.length} > ${MAX_PERSISTENCE_IDENTIFIER_LENGTH}): ${value.slice(0, 32)}...`
+    );
+  }
+  if (!SAFE_PERSISTENCE_IDENTIFIER_RE.test(value)) {
+    throw new TypeError(
+      `options.persistence.${kind} ${JSON.stringify(value)} contains characters outside [A-Za-z0-9_] or does not start with a letter/underscore. ` +
+        `This restriction blocks SQL injection and path traversal uniformly; use ${SAFE_PERSISTENCE_IDENTIFIER_RE} to construct the name.`
+    );
+  }
+}
+
+// ============================================
+// Extended persistence options — opt-in
+// ============================================
+
+/**
+ * Per-field override block. Merged on top of values derived from
+ * `ResourceField` by `snapshotFromResources`. All fields are optional.
+ *
+ * `columnName` beats the default `camelCase → snake_case` transform.
+ * `nullable` beats `!field.required`.
+ * `default` beats `field.default` (and bypasses its string-magic parsing).
+ * `maxLength` is used when the Mandu field type is `string`.
+ */
+export interface FieldOverride {
+  /** Explicit column name override. Must match `/^[a-z_][a-z0-9_]*$/i`. */
+  columnName?: string;
+  /** Explicit NULL allowance. */
+  nullable?: boolean;
+  /** Explicit DEFAULT clause (bypasses `field.default` string magic). */
+  default?: DdlDefault;
+  /** VARCHAR length for `string` fields. Ignored for other types. */
+  maxLength?: number;
+  /** Mark as indexed (single-column, non-unique). */
+  indexed?: boolean;
+  /** Mark as UNIQUE. */
+  unique?: boolean;
+}
+
+/**
+ * Persistence block on a resource definition — opt-in to DDL/migration.
+ * Resources without this field are ignored by the diff engine.
+ */
+export interface ExtendedResourcePersistence {
+  /** Which SQL provider this resource targets. Must be consistent across the project. */
+  provider: SqlProvider;
+  /** Explicit table name. Overrides auto-pluralization of `resource.name`. */
+  tableName?: string;
+  /**
+   * Primary key field key. Can be a single string (v1) or a 1-element array
+   * (future-compatible). Multi-element arrays are rejected — composite keys
+   * are v2+.
+   */
+  primaryKey?: string | [string];
+  /** Multi-column indexes. Single-column indexes live on the field itself. */
+  indexes?: DdlIndex[];
+  /** Per-field overrides keyed by the Mandu field name. */
+  fieldOverrides?: Record<string, FieldOverride>;
+}
+
+// ============================================
+// Safe narrowing
+// ============================================
+
+/**
+ * Narrow `unknown` (the public schema type for `options.persistence`) to
+ * `ExtendedResourcePersistence`. Returns `undefined` when the value is
+ * missing or empty. Throws `TypeError` on structurally-broken objects OR
+ * on identifier-shaped fields that contain SQL-injection / path-traversal
+ * characters (see {@link SAFE_PERSISTENCE_IDENTIFIER_RE}).
+ *
+ * This is the ONLY place the DDL layer trusts the shape of the persistence
+ * block; downstream code never sees `unknown`.
+ */
+export function asPersistence(raw: unknown): ExtendedResourcePersistence | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "object") {
+    throw new TypeError(`options.persistence must be an object, got ${typeof raw}`);
+  }
+  const obj = raw as Record<string, unknown>;
+  const provider = obj.provider;
+  if (provider !== "postgres" && provider !== "mysql" && provider !== "sqlite") {
+    throw new TypeError(
+      `options.persistence.provider must be one of "postgres" | "mysql" | "sqlite", got ${JSON.stringify(provider)}`
+    );
+  }
+  if (obj.tableName !== undefined) {
+    if (typeof obj.tableName !== "string") {
+      throw new TypeError(`options.persistence.tableName must be a string`);
+    }
+    assertSafeIdentifier("tableName", obj.tableName);
+  }
+  if (obj.primaryKey !== undefined) {
+    const pk = obj.primaryKey;
+    if (
+      typeof pk !== "string" &&
+      !(Array.isArray(pk) && pk.length === 1 && typeof pk[0] === "string")
+    ) {
+      throw new TypeError(
+        `options.persistence.primaryKey must be a string or single-element string array (composite keys are v2)`
+      );
+    }
+  }
+  if (obj.indexes !== undefined) {
+    if (!Array.isArray(obj.indexes)) {
+      throw new TypeError(`options.persistence.indexes must be an array`);
+    }
+    for (let i = 0; i < obj.indexes.length; i++) {
+      const idx = obj.indexes[i] as { name?: unknown } | undefined;
+      if (idx && typeof idx === "object" && typeof idx.name === "string") {
+        assertSafeIdentifier(`indexes[${i}].name`, idx.name);
+      }
+    }
+  }
+  if (obj.fieldOverrides !== undefined) {
+    if (typeof obj.fieldOverrides !== "object" || obj.fieldOverrides === null || Array.isArray(obj.fieldOverrides)) {
+      throw new TypeError(`options.persistence.fieldOverrides must be an object`);
+    }
+    for (const [key, value] of Object.entries(obj.fieldOverrides as Record<string, unknown>)) {
+      if (value === undefined || value === null) continue;
+      if (typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(
+          `options.persistence.fieldOverrides.${key} must be an object`
+        );
+      }
+      const col = (value as { columnName?: unknown }).columnName;
+      if (col !== undefined) {
+        if (typeof col !== "string") {
+          throw new TypeError(
+            `options.persistence.fieldOverrides.${key}.columnName must be a string`
+          );
+        }
+        assertSafeIdentifier(`fieldOverrides.${key}.columnName`, col);
+      }
+    }
+  }
+  return obj as unknown as ExtendedResourcePersistence;
+}

package/src/resource/ddl/snapshot.ts

@@ -0,0 +1,447 @@
+/**
+ * Phase 4c — Schema snapshot normalization + serialization.
+ *
+ * Pure functions, no I/O beyond the Bun-native SHA-256 hasher. Given the
+ * same `ParsedResource[]`, these functions MUST produce byte-identical
+ * `Snapshot` objects and byte-identical serialized JSON — this guarantee
+ * is what makes the snapshot file usable as a git-checked-in artifact and
+ * what makes checksum-based tamper detection (Agent C) meaningful.
+ *
+ * Pipeline:
+ *
+ *   ParsedResource[]  --snapshotFromResources-->  Snapshot
+ *                                                    |
+ *                                    serializeSnapshot | parseSnapshot
+ *                                                    v
+ *                                                 JSON string  (committed to .mandu/schema/applied.json)
+ *
+ * Nothing here touches the filesystem — the CLI (Agent E) and generator
+ * (Agent D) are responsible for where the snapshot lives on disk.
+ *
+ * Normalization rules (documented in detail on each helper below):
+ *   1. Only resources with a well-formed `options.persistence` are included.
+ *   2. All resources must target the same `SqlProvider`; mixing throws.
+ *   3. Table name: `options.persistence.tableName` > auto-pluralized
+ *      `definition.name`. `options.autoPlural === false` keeps it singular.
+ *   4. Column name: `fieldOverrides[key].columnName` > `camelCase → snake_case`.
+ *   5. Primary key: `options.persistence.primaryKey` (string|[string]) >
+ *      field with `primary: true` > error. Composite PK is v2+.
+ *   6. `DdlDefault` derived from `field.default` with the string-magic
+ *      "now" / "current_timestamp" shortcut. See `normalizeDefault`.
+ *
+ * References:
+ *   docs/bun/phase-4c-team-plan.md §3 Agent B
+ *   docs/rfcs/0001-db-resource-layer.md Appendix D.1 (dialect divergence)
+ *   docs/rfcs/0001-db-resource-layer.md §4 D5 (opt-in `persistence` field)
+ */
+
+import type { ParsedResource } from "../parser";
+import type { ResourceField, ResourceOptions } from "../schema";
+import type {
+  DdlDefault,
+  DdlFieldDef,
+  DdlFieldType,
+  DdlIndex,
+  DdlResource,
+  Snapshot,
+  SqlProvider,
+} from "./types";
+import { asPersistence, type ExtendedResourcePersistence, type FieldOverride } from "./persistence-types";
+
+// ============================================
+// Public API
+// ============================================
+
+/**
+ * Normalize `ParsedResource[]` into a provider-tagged `Snapshot`.
+ *
+ * Resources whose `options.persistence` is missing/empty are silently
+ * dropped — the resource generator emits contract/types/slot/client but
+ * no DDL for such resources.
+ *
+ * Insertion order of fields (the order keys appear in the source
+ * `definition.fields` object) is preserved; this is the author's intent
+ * and the emit order for `CREATE TABLE`.
+ *
+ * Top-level `snapshot.resources` is sorted alphabetically by `name` —
+ * this is what makes `serializeSnapshot` output stable across runs even
+ * if the caller scans files in a different order.
+ *
+ * @throws TypeError on:
+ *   - conflicting providers across persistent resources
+ *   - zero primary-key fields on a persistent resource
+ *   - more than one primary-key field (composite PK is v2)
+ *   - duplicate table name after pluralization
+ *   - invalid `field.default` value (functions, symbols, objects)
+ *   - structurally broken `options.persistence` (see `asPersistence`)
+ */
+export function snapshotFromResources(resources: readonly ParsedResource[]): Snapshot {
+  const ddlResources: DdlResource[] = [];
+  let provider: SqlProvider | undefined;
+  const seenTableNames = new Map<string, string>(); // tableName -> first resource that claimed it
+
+  for (const parsed of resources) {
+    // `options.persistence` is not declared on the public ResourceOptions —
+    // it's an opt-in additive field (see persistence-types.ts for rationale).
+    // Read it via an unknown cast and narrow with `asPersistence`.
+    const rawPersistence = (parsed.definition.options as Record<string, unknown> | undefined)?.persistence;
+    const persistence = asPersistence(rawPersistence);
+    if (!persistence) continue; // non-persistent resource — skip
+
+    if (provider === undefined) {
+      provider = persistence.provider;
+    } else if (provider !== persistence.provider) {
+      throw new TypeError(
+        `Mixed SQL providers in resource set: resource "${parsed.resourceName}" declares provider "${persistence.provider}" but the snapshot is already building for "${provider}". All persistent resources in a project must share one provider.`
+      );
+    }
+
+    const ddlResource = normalizeResource(parsed, persistence);
+
+    const prior = seenTableNames.get(ddlResource.name);
+    if (prior !== undefined) {
+      throw new TypeError(
+        `Duplicate table name "${ddlResource.name}" — resources "${prior}" and "${parsed.resourceName}" both map to it. Use options.persistence.tableName to disambiguate.`
+      );
+    }
+    seenTableNames.set(ddlResource.name, parsed.resourceName);
+
+    ddlResources.push(ddlResource);
+  }
+
+  ddlResources.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  return {
+    version: 1,
+    provider: provider ?? "postgres", // empty set → default to postgres; it's meaningless for an empty resource list
+    resources: ddlResources,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Deterministic JSON serialization — 2-space indent, sorted object keys,
+ * stable array order. Byte-for-byte stable for the same `Snapshot`,
+ * modulo `generatedAt` which the caller controls.
+ *
+ * We intentionally sort object keys rather than trusting the property
+ * insertion order of the callers' objects — this guards against subtle
+ * non-determinism when `Snapshot` is built by code that constructs
+ * objects in different orders across refactors.
+ *
+ * Arrays are NOT sorted — their order is semantically load-bearing
+ * (field emit order, sorted resource order).
+ */
+export function serializeSnapshot(s: Snapshot): string {
+  return stringifyWithSortedKeys(s, 2);
+}
+
+/**
+ * Parse a snapshot JSON string.
+ *
+ * @throws TypeError on invalid JSON, missing required fields, or
+ *   `version` that this build does not understand.
+ */
+export function parseSnapshot(raw: string): Snapshot {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new TypeError(
+      `Invalid snapshot JSON: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new TypeError(`Snapshot must be a JSON object, got ${typeof parsed}`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj.version !== 1) {
+    throw new TypeError(
+      `Unsupported snapshot version ${JSON.stringify(obj.version)}. This build understands version 1 only.`
+    );
+  }
+  if (obj.provider !== "postgres" && obj.provider !== "mysql" && obj.provider !== "sqlite") {
+    throw new TypeError(`Snapshot has invalid provider ${JSON.stringify(obj.provider)}`);
+  }
+  if (!Array.isArray(obj.resources)) {
+    throw new TypeError(`Snapshot.resources must be an array`);
+  }
+  if (typeof obj.generatedAt !== "string") {
+    throw new TypeError(`Snapshot.generatedAt must be an ISO string`);
+  }
+  // Deeper structural validation of resources is deferred to the diff
+  // engine; tampering with fields of a stored snapshot would be caught
+  // by the migration runtime's checksum before diff ever runs.
+  return parsed as Snapshot;
+}
+
+/**
+ * SHA-256 of the canonical serialization of a snapshot. Useful for quick
+ * change detection ("has the committed schema drifted from the applied
+ * snapshot?").
+ *
+ * Note: `generatedAt` is part of the canonical serialization, so two
+ * snapshots with the same resources but different generation times will
+ * hash differently. Callers that want a time-stable hash should zero out
+ * `generatedAt` before calling.
+ */
+export function hashSnapshot(s: Snapshot): string {
+  const canonical = serializeSnapshot(s);
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(canonical);
+  return hasher.digest("hex");
+}
+
+// ============================================
+// Internals — resource normalization
+// ============================================
+
+function normalizeResource(
+  parsed: ParsedResource,
+  persistence: ExtendedResourcePersistence
+): DdlResource {
+  const { definition } = parsed;
+  const tableName = resolveTableName(definition.name, definition.options, persistence);
+  const overrides = persistence.fieldOverrides ?? {};
+
+  // Respect insertion order — Object.entries preserves the author's key order.
+  const fieldEntries = Object.entries(definition.fields);
+  if (fieldEntries.length === 0) {
+    // parser.ts already validates this, but guard defensively.
+    throw new TypeError(`Resource "${parsed.resourceName}" has no fields`);
+  }
+
+  const declaredPk = resolveDeclaredPrimaryKey(persistence.primaryKey);
+  const fields: DdlFieldDef[] = [];
+  const pkFieldKeys: string[] = [];
+  // Author field key (e.g. "passwordHash") → resolved column name (e.g. "password_hash").
+  // Used by index normalization below to resolve declared index fields.
+  const keyToColumn = new Map<string, string>();
+
+  for (const [fieldKey, field] of fieldEntries) {
+    const override = overrides[fieldKey];
+    const ddlField = normalizeField(fieldKey, field, override, declaredPk, parsed.resourceName);
+    if (ddlField.primary) pkFieldKeys.push(fieldKey);
+    fields.push(ddlField);
+    keyToColumn.set(fieldKey, ddlField.name);
+  }
+
+  if (pkFieldKeys.length === 0) {
+    throw new TypeError(
+      `Resource "${parsed.resourceName}" must have exactly one primary key field. Mark a field with \`primary: true\` (via fieldOverrides) or declare \`options.persistence.primaryKey\`.`
+    );
+  }
+  if (pkFieldKeys.length > 1) {
+    throw new TypeError(
+      `Resource "${parsed.resourceName}" has ${pkFieldKeys.length} primary key fields (${pkFieldKeys.join(", ")}). Composite primary keys are not supported in v1.`
+    );
+  }
+
+  const indexes = normalizeIndexes(persistence.indexes, keyToColumn, parsed.resourceName);
+
+  return { name: tableName, fields, indexes };
+}
+
+function resolveTableName(
+  resourceName: string,
+  options: ResourceOptions | undefined,
+  persistence: ExtendedResourcePersistence
+): string {
+  if (persistence.tableName) return persistence.tableName;
+  // `options.pluralName` from the existing schema takes precedence over auto-plural,
+  // but `tableName` trumps both — this preserves backward compat for users who
+  // had a `pluralName` before Phase 4c.
+  if (options?.pluralName) return options.pluralName;
+  if (options?.autoPlural === false) return resourceName;
+  return pluralize(resourceName);
+}
+
+/**
+ * Conservative v1 pluralizer.
+ *
+ * Rules (in order):
+ *   1. ends with `y` preceded by a consonant → `ies` ("city" → "cities")
+ *   2. ends with `s` / `x` / `z` / `ch` / `sh` → `+es` ("box" → "boxes")
+ *   3. default                                 → `+s` ("user" → "users")
+ *
+ * English has irregular plurals the framework cannot infer — that's the
+ * escape hatch `options.persistence.tableName` exists for.
+ */
+function pluralize(singular: string): string {
+  if (/[^aeiou]y$/i.test(singular)) {
+    return singular.slice(0, -1) + "ies";
+  }
+  if (/(?:s|x|z|ch|sh)$/i.test(singular)) {
+    return singular + "es";
+  }
+  return singular + "s";
+}
+
+function resolveDeclaredPrimaryKey(declared: ExtendedResourcePersistence["primaryKey"]): string | undefined {
+  if (declared === undefined) return undefined;
+  if (typeof declared === "string") return declared;
+  return declared[0];
+}
+
+// ============================================
+// Internals — field normalization
+// ============================================
+
+function normalizeField(
+  fieldKey: string,
+  field: ResourceField,
+  override: FieldOverride | undefined,
+  declaredPk: string | undefined,
+  resourceName: string
+): DdlFieldDef {
+  const name = override?.columnName ?? toSnakeCase(fieldKey);
+  const nullable = override?.nullable ?? !(field.required ?? false);
+
+  // A field is a primary key if:
+  //   - the explicit `persistence.primaryKey` names it, OR
+  //   - the field's declaration carries `primary: true` (an opt-in, not the
+  //     default on Mandu's ResourceField type; accessed via a best-effort
+  //     cast because `ResourceField` predates this feature).
+  const declaredPkMatch = declaredPk !== undefined && declaredPk === fieldKey;
+  const fieldLevelPk = Boolean((field as ResourceField & { primary?: boolean }).primary);
+  const primary = declaredPkMatch || fieldLevelPk;
+
+  const unique = override?.unique ?? Boolean((field as ResourceField & { unique?: boolean }).unique);
+  const indexed = override?.indexed ?? Boolean((field as ResourceField & { indexed?: boolean }).indexed);
+
+  const def = override?.default ?? normalizeDefault(field.default, fieldKey, resourceName);
+
+  const result: DdlFieldDef = {
+    name,
+    type: field.type as DdlFieldType,
+    nullable,
+    primary,
+    unique,
+    indexed,
+  };
+  if (def !== undefined) result.default = def;
+  const maxLength = override?.maxLength ?? (field as ResourceField & { maxLength?: number }).maxLength;
+  if (typeof maxLength === "number") result.maxLength = maxLength;
+  return result;
+}
+
+/**
+ * `camelCase` / `PascalCase` → `snake_case`. Leaves already-snake names
+ * untouched. Runs of consecutive capitals are treated as a single word
+ * (`HTTPRequest` → `http_request`) which matches PostgreSQL/Drizzle
+ * conventions.
+ */
+export function toSnakeCase(input: string): string {
+  if (input.length === 0) return input;
+  // Insert underscores at run-of-caps/start-of-word boundaries, then lowercase.
+  return input
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2") // camelCase → camel_Case
+    .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2") // HTTPServer → HTTP_Server
+    .toLowerCase();
+}
+
+/**
+ * Normalize `ResourceField.default` to a `DdlDefault` discriminated union.
+ *
+ * Rules:
+ *   undefined                            → no DEFAULT (returns undefined)
+ *   null                                 → { kind: "null" }
+ *   "now" | "current_timestamp"          → { kind: "now" }
+ *   string (other)                       → { kind: "literal", value }
+ *   number | boolean                     → { kind: "literal", value }
+ *   function | symbol | object | array   → throws TypeError
+ *
+ * Arrays/objects are explicitly rejected: their JSON representation depends
+ * on the receiving dialect's JSON column semantics, and the v1 contract
+ * is that DEFAULT values are scalar. Users with JSON defaults should use
+ * `{ kind: "sql", expr: "'[]'" }` via `fieldOverrides[key].default`.
+ */
+function normalizeDefault(
+  raw: unknown,
+  fieldKey: string,
+  resourceName: string
+): DdlDefault | undefined {
+  if (raw === undefined) return undefined;
+  if (raw === null) return { kind: "null" };
+  if (typeof raw === "string") {
+    if (raw === "now" || raw === "current_timestamp") return { kind: "now" };
+    return { kind: "literal", value: raw };
+  }
+  if (typeof raw === "number") {
+    if (!Number.isFinite(raw)) {
+      throw new TypeError(
+        `Field "${resourceName}.${fieldKey}" has non-finite default (${String(raw)}). DEFAULT must be a finite number.`
+      );
+    }
+    return { kind: "literal", value: raw };
+  }
+  if (typeof raw === "boolean") return { kind: "literal", value: raw };
+  // Functions, symbols, objects, arrays, BigInt — none are representable
+  // as a portable SQL DEFAULT literal. Force the user to be explicit via
+  // `fieldOverrides[key].default = { kind: "sql", expr: ... }`.
+  throw new TypeError(
+    `Field "${resourceName}.${fieldKey}" has unsupported default type (${typeof raw}). Use a string, number, boolean, or null — or override via options.persistence.fieldOverrides.${fieldKey}.default with an explicit DdlDefault.`
+  );
+}
+
+// ============================================
+// Internals — index normalization
+// ============================================
+
+/**
+ * Normalize user-declared indexes to DDL shape. The author's `idx.fields`
+ * entries are field KEYS (as written in `definition.fields`); we resolve
+ * each to the post-snake_case column name via `keyToColumn`. Entries
+ * that don't match a known field key are passed through verbatim —
+ * that supports the escape hatch of referencing a column directly.
+ */
+function normalizeIndexes(
+  declared: DdlIndex[] | undefined,
+  keyToColumn: ReadonlyMap<string, string>,
+  resourceName: string
+): DdlIndex[] {
+  if (!declared || declared.length === 0) return [];
+  const list = declared.map((idx) => {
+    if (!idx.name) throw new TypeError(`Index on "${resourceName}" is missing a name`);
+    if (!Array.isArray(idx.fields) || idx.fields.length === 0) {
+      throw new TypeError(`Index "${resourceName}.${idx.name}" must declare at least one field`);
+    }
+    const columns = idx.fields.map((key) => keyToColumn.get(key) ?? key);
+    return { name: idx.name, fields: columns, unique: Boolean(idx.unique) };
+  });
+  // Stable sort by name — makes snapshot output deterministic.
+  list.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  // Detect duplicate index names after normalization.
+  for (let i = 1; i < list.length; i++) {
+    if (list[i].name === list[i - 1].name) {
+      throw new TypeError(`Duplicate index name "${list[i].name}" on resource "${resourceName}"`);
+    }
+  }
+  return list;
+}
+
+// ============================================
+// Internals — deterministic JSON
+// ============================================
+
+/**
+ * `JSON.stringify` that sorts object keys at every depth. Arrays are
+ * preserved in order. `undefined` values (and their keys) are dropped.
+ */
+function stringifyWithSortedKeys(value: unknown, indent: number): string {
+  return JSON.stringify(sortKeys(value), null, indent);
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).filter(
+      ([, v]) => v !== undefined
+    );
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of entries) out[k] = sortKeys(v);
+    return out;
+  }
+  return value;
+}