@prisma-next/emitter 0.3.0-dev.4 → 0.3.0-dev.41

package/README.md

@@ -6,7 +6,7 @@ Contract emission engine that transforms authored data models into canonical JSO
 
 The emitter is the core of Prisma Next's contract-first architecture. It takes authored data models (from PSL or TypeScript builders) and produces two deterministic artifacts:
 
-1. **`contract.json`** — Canonical JSON representation of the data contract with embedded `coreHash` and `profileHash`. Callers may add `_generated` metadata field to indicate it's a generated artifact (excluded from canonicalization/hashing).
+1. **`contract.json`** — Canonical JSON representation of the data contract with embedded `storageHash` and optional `executionHash`/`profileHash`. Callers may add `_generated` metadata field to indicate it's a generated artifact (excluded from canonicalization/hashing).
 2. **`contract.d.ts`** — TypeScript type definitions used by query builders and tooling (types-only, no runtime code). Includes warning header comments generated by target family hooks to indicate it's a generated file.
 
 The emitter is target-family-agnostic and uses a pluggable hook system (`TargetFamilyHook`) to handle family-specific validation and type generation. This keeps the core thin while allowing SQL, Document, and other target families to extend emission behavior.
@@ -19,7 +19,7 @@ Provide a deterministic, verifiable representation of the application's data con
 
 - **Parse**: Accept contract IR (Intermediate Representation) from authoring surfaces
 - **Validate**: Core structure validation plus family-specific type and structure validation via hooks
-- **Canonicalize**: Compute `coreHash` (schema meaning) and `profileHash` (capabilities/pins) from canonical JSON
+- **Canonicalize**: Compute `storageHash` (schema meaning), `executionHash` (execution defaults), and `profileHash` (capabilities/pins) from canonical JSON
 - **Emit**: Generate `contract.json` and `contract.d.ts` with family-specific type generation
 - **Descriptor-Agnostic**: The emitter is completely agnostic to how descriptors are produced. It receives pre-assembled `OperationRegistry`, `codecTypeImports`, `operationTypeImports`, and `extensionIds` from the CLI or family helpers—no pack manifest parsing happens inside the emitter.
 
@@ -90,7 +90,8 @@ flowchart TD
 - **Note**: `TargetFamilyHook`, `ValidationContext`, and `TypesImportSpec` types are defined in `@prisma-next/contract/types` (shared plane) and re-exported from this package for backward compatibility.
 
 ### Hashing (`hashing.ts`)
-- `computeCoreHash`: SHA-256 of schema structure (models, storage, relations)
+- `computeStorageHash`: SHA-256 of schema structure (models, storage, relations)
+- `computeExecutionHash`: SHA-256 of execution defaults
 - `computeProfileHash`: SHA-256 of capabilities and adapter pins
 
 ### Canonicalization (`canonicalization.ts`)
@@ -156,7 +157,8 @@ const result = await emit(ir, {
 
 // result.contractJson: string (JSON) - canonical JSON without _generated metadata
 // result.contractDts: string (TypeScript definitions) - includes warning header
-// result.coreHash: string
+// result.storageHash: string
+// result.executionHash?: string
 // result.profileHash?: string
 ```
 

package/dist/exports/index.d.mts

@@ -0,0 +1,3 @@
+import { EmitOptions, EmitResult, emit } from "@prisma-next/core-control-plane/emission";
+import { TargetFamilyHook, TypesImportSpec, ValidationContext } from "@prisma-next/contract/types";
+export { type EmitOptions, type EmitResult, type TargetFamilyHook, type TypesImportSpec, type ValidationContext, emit };

package/dist/exports/index.mjs

@@ -0,0 +1,3 @@
+import { emit } from "@prisma-next/core-control-plane/emission";
+
+export { emit };

package/dist/test/{utils.d.ts → utils.d.mts}

@@ -1,4 +1,6 @@
-import { ContractIR } from '@prisma-next/contract/ir';
+import { ContractIR } from "@prisma-next/contract/ir";
+
+//#region test/utils.d.ts
 
 /**
  * Factory function for creating ContractIR objects in tests.
@@ -9,8 +11,9 @@ import { ContractIR } from '@prisma-next/contract/ir';
  * from the result (useful for testing validation of missing fields).
  */
 declare function createContractIR(overrides?: Partial<ContractIR> & {
-    coreHash?: string;
-    profileHash?: string;
+  storageHash?: string;
+  profileHash?: string;
 }): ContractIR;
-
+//#endregion
 export { createContractIR };
+//# sourceMappingURL=utils.d.mts.map

package/dist/test/utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.mts","names":[],"sources":["../../test/utils.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;;;;;;iBAAgB,gBAAA,aACH,QAAQ;;;IAClB"}

package/dist/test/utils.mjs

@@ -0,0 +1,59 @@
+import { irHeader, irMeta } from "@prisma-next/contract/ir";
+
+//#region test/utils.ts
+/**
+* Factory function for creating ContractIR objects in tests.
+* Provides sensible defaults and allows overriding specific fields.
+* Uses the emitter factories internally for consistency.
+*
+* If a field is explicitly set to `undefined` in overrides, it will be omitted
+* from the result (useful for testing validation of missing fields).
+*/
+function createContractIR(overrides = {}) {
+	const hasTarget = "target" in overrides;
+	const hasTargetFamily = "targetFamily" in overrides;
+	const hasStorageHash = "storageHash" in overrides;
+	const hasSchemaVersion = "schemaVersion" in overrides;
+	const hasModels = "models" in overrides;
+	const hasRelations = "relations" in overrides;
+	const hasStorage = "storage" in overrides;
+	const hasCapabilities = "capabilities" in overrides;
+	const hasExtensionPacks = "extensionPacks" in overrides;
+	const hasMeta = "meta" in overrides;
+	const hasSources = "sources" in overrides;
+	const headerOpts = {};
+	if (hasTarget && overrides.target !== void 0) headerOpts.target = overrides.target;
+	else if (!hasTarget) headerOpts.target = "postgres";
+	if (hasTargetFamily && overrides.targetFamily !== void 0) headerOpts.targetFamily = overrides.targetFamily;
+	else if (!hasTargetFamily) headerOpts.targetFamily = "sql";
+	if (hasStorageHash && overrides.storageHash !== void 0) headerOpts.storageHash = overrides.storageHash;
+	else if (!hasStorageHash) headerOpts.storageHash = "sha256:test";
+	if (overrides.profileHash !== void 0) headerOpts.profileHash = overrides.profileHash;
+	const header = irHeader(headerOpts);
+	const metaOpts = {};
+	if (hasCapabilities && overrides.capabilities !== void 0) metaOpts.capabilities = overrides.capabilities;
+	else if (!hasCapabilities) metaOpts.capabilities = {};
+	if (hasExtensionPacks && overrides.extensionPacks !== void 0) metaOpts.extensionPacks = overrides.extensionPacks;
+	else if (!hasExtensionPacks) metaOpts.extensionPacks = {};
+	if (hasMeta && overrides.meta !== void 0) metaOpts.meta = overrides.meta;
+	else if (!hasMeta) metaOpts.meta = {};
+	if (hasSources && overrides.sources !== void 0) metaOpts.sources = overrides.sources;
+	else if (!hasSources) metaOpts.sources = {};
+	const meta = irMeta(Object.keys(metaOpts).length > 0 ? metaOpts : void 0);
+	return {
+		schemaVersion: hasSchemaVersion && overrides.schemaVersion !== void 0 ? overrides.schemaVersion : hasSchemaVersion && overrides.schemaVersion === void 0 ? void 0 : header.schemaVersion,
+		target: header.target,
+		targetFamily: header.targetFamily,
+		capabilities: hasCapabilities && overrides.capabilities === void 0 ? void 0 : !hasCapabilities || overrides.capabilities !== void 0 ? meta.capabilities : {},
+		extensionPacks: hasExtensionPacks && overrides.extensionPacks === void 0 ? void 0 : !hasExtensionPacks || overrides.extensionPacks !== void 0 ? meta.extensionPacks : {},
+		meta: hasMeta && overrides.meta === void 0 ? void 0 : !hasMeta || overrides.meta !== void 0 ? meta.meta : {},
+		sources: hasSources && overrides.sources === void 0 ? void 0 : !hasSources || overrides.sources !== void 0 ? meta.sources : {},
+		storage: hasStorage && overrides.storage === void 0 ? void 0 : hasStorage && overrides.storage !== void 0 ? overrides.storage : !hasStorage ? { tables: {} } : {},
+		models: hasModels && overrides.models === void 0 ? void 0 : hasModels && overrides.models !== void 0 ? overrides.models : !hasModels ? {} : {},
+		relations: hasRelations && overrides.relations === void 0 ? void 0 : hasRelations && overrides.relations !== void 0 ? overrides.relations : !hasRelations ? {} : {}
+	};
+}
+
+//#endregion
+export { createContractIR };
+//# sourceMappingURL=utils.mjs.map

package/dist/test/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.mjs","names":["headerOpts: {\n    target?: string;\n    targetFamily?: string;\n    storageHash?: string;\n    profileHash?: string;\n  }","metaOpts: {\n    capabilities?: Record<string, Record<string, boolean>>;\n    extensionPacks?: Record<string, unknown>;\n    meta?: Record<string, unknown>;\n    sources?: Record<string, unknown>;\n  }"],"sources":["../../test/utils.ts"],"sourcesContent":["import { type ContractIR, irHeader, irMeta } from '@prisma-next/contract/ir';\n\n/**\n * Factory function for creating ContractIR objects in tests.\n * Provides sensible defaults and allows overriding specific fields.\n * Uses the emitter factories internally for consistency.\n *\n * If a field is explicitly set to `undefined` in overrides, it will be omitted\n * from the result (useful for testing validation of missing fields).\n */\nexport function createContractIR(\n  overrides: Partial<ContractIR> & { storageHash?: string; profileHash?: string } = {},\n): ContractIR {\n  // Check if fields are explicitly undefined (not just missing)\n  const hasTarget = 'target' in overrides;\n  const hasTargetFamily = 'targetFamily' in overrides;\n  const hasStorageHash = 'storageHash' in overrides;\n  const hasSchemaVersion = 'schemaVersion' in overrides;\n  const hasModels = 'models' in overrides;\n  const hasRelations = 'relations' in overrides;\n  const hasStorage = 'storage' in overrides;\n  const hasCapabilities = 'capabilities' in overrides;\n  const hasExtensionPacks = 'extensionPacks' in overrides;\n  const hasMeta = 'meta' in overrides;\n  const hasSources = 'sources' in overrides;\n\n  // Build header, omitting fields that are explicitly undefined\n  const headerOpts: {\n    target?: string;\n    targetFamily?: string;\n    storageHash?: string;\n    profileHash?: string;\n  } = {};\n\n  if (hasTarget && overrides.target !== undefined) {\n    headerOpts.target = overrides.target;\n  } else if (!hasTarget) {\n    headerOpts.target = 'postgres';\n  }\n\n  if (hasTargetFamily && overrides.targetFamily !== undefined) {\n    headerOpts.targetFamily = overrides.targetFamily;\n  } else if (!hasTargetFamily) {\n    headerOpts.targetFamily = 'sql';\n  }\n\n  if (hasStorageHash && overrides.storageHash !== undefined) {\n    headerOpts.storageHash = overrides.storageHash;\n  } else if (!hasStorageHash) {\n    headerOpts.storageHash = 'sha256:test';\n  }\n\n  // profileHash is not part of ContractIR, but we can accept it for header creation\n  if (overrides.profileHash !== undefined) {\n    headerOpts.profileHash = overrides.profileHash;\n  }\n\n  const header = irHeader(\n    headerOpts as {\n      target: string;\n      targetFamily: string;\n      storageHash: string;\n      profileHash?: string;\n    },\n  );\n\n  // Build meta, handling explicitly undefined fields\n  // If a field is explicitly undefined, we'll omit it from the result later\n  const metaOpts: {\n    capabilities?: Record<string, Record<string, boolean>>;\n    extensionPacks?: Record<string, unknown>;\n    meta?: Record<string, unknown>;\n    sources?: Record<string, unknown>;\n  } = {};\n\n  if (hasCapabilities && overrides.capabilities !== undefined) {\n    metaOpts.capabilities = overrides.capabilities;\n  } else if (!hasCapabilities) {\n    metaOpts.capabilities = {};\n  }\n\n  if (hasExtensionPacks && overrides.extensionPacks !== undefined) {\n    metaOpts.extensionPacks = overrides.extensionPacks;\n  } else if (!hasExtensionPacks) {\n    metaOpts.extensionPacks = {};\n  }\n\n  if (hasMeta && overrides.meta !== undefined) {\n    metaOpts.meta = overrides.meta;\n  } else if (!hasMeta) {\n    metaOpts.meta = {};\n  }\n\n  if (hasSources && overrides.sources !== undefined) {\n    metaOpts.sources = overrides.sources;\n  } else if (!hasSources) {\n    metaOpts.sources = {};\n  }\n\n  const meta = irMeta(Object.keys(metaOpts).length > 0 ? metaOpts : undefined);\n\n  // Build result by constructing the object directly (ContractIR doesn't include storageHash/profileHash)\n  // When fields are explicitly undefined, include them as undefined (tests use type assertions to bypass TS)\n  const result = {\n    schemaVersion:\n      hasSchemaVersion && overrides.schemaVersion !== undefined\n        ? overrides.schemaVersion\n        : hasSchemaVersion && overrides.schemaVersion === undefined\n          ? (undefined as unknown as string)\n          : header.schemaVersion,\n    target: header.target,\n    targetFamily: header.targetFamily,\n    // Only include meta fields if they're not explicitly undefined\n    capabilities:\n      hasCapabilities && overrides.capabilities === undefined\n        ? (undefined as unknown as Record<string, Record<string, boolean>>)\n        : !hasCapabilities || overrides.capabilities !== undefined\n          ? meta.capabilities\n          : ({} as Record<string, Record<string, boolean>>),\n    extensionPacks:\n      hasExtensionPacks && overrides.extensionPacks === undefined\n        ? (undefined as unknown as Record<string, unknown>)\n        : !hasExtensionPacks || overrides.extensionPacks !== undefined\n          ? meta.extensionPacks\n          : ({} as Record<string, unknown>),\n    meta:\n      hasMeta && overrides.meta === undefined\n        ? (undefined as unknown as Record<string, unknown>)\n        : !hasMeta || overrides.meta !== undefined\n          ? meta.meta\n          : ({} as Record<string, unknown>),\n    sources:\n      hasSources && overrides.sources === undefined\n        ? (undefined as unknown as Record<string, unknown>)\n        : !hasSources || overrides.sources !== undefined\n          ? meta.sources\n          : ({} as Record<string, unknown>),\n    // Only include family sections if they're not explicitly undefined\n    storage:\n      hasStorage && overrides.storage === undefined\n        ? (undefined as unknown as Record<string, unknown>)\n        : hasStorage && overrides.storage !== undefined\n          ? (overrides.storage as Record<string, unknown>)\n          : !hasStorage\n            ? ({ tables: {} } as Record<string, unknown>)\n            : ({} as Record<string, unknown>),\n    models:\n      hasModels && overrides.models === undefined\n        ? (undefined as unknown as Record<string, unknown>)\n        : hasModels && overrides.models !== undefined\n          ? (overrides.models as Record<string, unknown>)\n          : !hasModels\n            ? {}\n            : ({} as Record<string, unknown>),\n    relations:\n      hasRelations && overrides.relations === undefined\n        ? (undefined as unknown as Record<string, unknown>)\n        : hasRelations && overrides.relations !== undefined\n          ? (overrides.relations as Record<string, unknown>)\n          : !hasRelations\n            ? {}\n            : ({} as Record<string, unknown>),\n  } as ContractIR;\n\n  return result;\n}\n"],"mappings":";;;;;;;;;;;AAUA,SAAgB,iBACd,YAAkF,EAAE,EACxE;CAEZ,MAAM,YAAY,YAAY;CAC9B,MAAM,kBAAkB,kBAAkB;CAC1C,MAAM,iBAAiB,iBAAiB;CACxC,MAAM,mBAAmB,mBAAmB;CAC5C,MAAM,YAAY,YAAY;CAC9B,MAAM,eAAe,eAAe;CACpC,MAAM,aAAa,aAAa;CAChC,MAAM,kBAAkB,kBAAkB;CAC1C,MAAM,oBAAoB,oBAAoB;CAC9C,MAAM,UAAU,UAAU;CAC1B,MAAM,aAAa,aAAa;CAGhC,MAAMA,aAKF,EAAE;AAEN,KAAI,aAAa,UAAU,WAAW,OACpC,YAAW,SAAS,UAAU;UACrB,CAAC,UACV,YAAW,SAAS;AAGtB,KAAI,mBAAmB,UAAU,iBAAiB,OAChD,YAAW,eAAe,UAAU;UAC3B,CAAC,gBACV,YAAW,eAAe;AAG5B,KAAI,kBAAkB,UAAU,gBAAgB,OAC9C,YAAW,cAAc,UAAU;UAC1B,CAAC,eACV,YAAW,cAAc;AAI3B,KAAI,UAAU,gBAAgB,OAC5B,YAAW,cAAc,UAAU;CAGrC,MAAM,SAAS,SACb,WAMD;CAID,MAAMC,WAKF,EAAE;AAEN,KAAI,mBAAmB,UAAU,iBAAiB,OAChD,UAAS,eAAe,UAAU;UACzB,CAAC,gBACV,UAAS,eAAe,EAAE;AAG5B,KAAI,qBAAqB,UAAU,mBAAmB,OACpD,UAAS,iBAAiB,UAAU;UAC3B,CAAC,kBACV,UAAS,iBAAiB,EAAE;AAG9B,KAAI,WAAW,UAAU,SAAS,OAChC,UAAS,OAAO,UAAU;UACjB,CAAC,QACV,UAAS,OAAO,EAAE;AAGpB,KAAI,cAAc,UAAU,YAAY,OACtC,UAAS,UAAU,UAAU;UACpB,CAAC,WACV,UAAS,UAAU,EAAE;CAGvB,MAAM,OAAO,OAAO,OAAO,KAAK,SAAS,CAAC,SAAS,IAAI,WAAW,OAAU;AAiE5E,QA7De;EACb,eACE,oBAAoB,UAAU,kBAAkB,SAC5C,UAAU,gBACV,oBAAoB,UAAU,kBAAkB,SAC7C,SACD,OAAO;EACf,QAAQ,OAAO;EACf,cAAc,OAAO;EAErB,cACE,mBAAmB,UAAU,iBAAiB,SACzC,SACD,CAAC,mBAAmB,UAAU,iBAAiB,SAC7C,KAAK,eACJ,EAAE;EACX,gBACE,qBAAqB,UAAU,mBAAmB,SAC7C,SACD,CAAC,qBAAqB,UAAU,mBAAmB,SACjD,KAAK,iBACJ,EAAE;EACX,MACE,WAAW,UAAU,SAAS,SACzB,SACD,CAAC,WAAW,UAAU,SAAS,SAC7B,KAAK,OACJ,EAAE;EACX,SACE,cAAc,UAAU,YAAY,SAC/B,SACD,CAAC,cAAc,UAAU,YAAY,SACnC,KAAK,UACJ,EAAE;EAEX,SACE,cAAc,UAAU,YAAY,SAC/B,SACD,cAAc,UAAU,YAAY,SACjC,UAAU,UACX,CAAC,aACE,EAAE,QAAQ,EAAE,EAAE,GACd,EAAE;EACb,QACE,aAAa,UAAU,WAAW,SAC7B,SACD,aAAa,UAAU,WAAW,SAC/B,UAAU,SACX,CAAC,YACC,EAAE,GACD,EAAE;EACb,WACE,gBAAgB,UAAU,cAAc,SACnC,SACD,gBAAgB,UAAU,cAAc,SACrC,UAAU,YACX,CAAC,eACC,EAAE,GACD,EAAE;EACd"}

package/package.json

@@ -1,43 +1,51 @@
 {
   "name": "@prisma-next/emitter",
-  "version": "0.3.0-dev.4",
+  "version": "0.3.0-dev.41",
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "test"
   ],
   "dependencies": {
     "arktype": "^2.0.0",
-    "@prisma-next/contract": "0.3.0-dev.4",
-    "@prisma-next/core-control-plane": "0.3.0-dev.4"
+    "@prisma-next/contract": "0.3.0-dev.41",
+    "@prisma-next/core-control-plane": "0.3.0-dev.41"
   },
   "devDependencies": {
     "@types/node": "24.10.4",
-    "@vitest/coverage-v8": "4.0.16",
-    "tsup": "8.5.1",
+    "tsdown": "0.18.4",
     "typescript": "5.9.3",
-    "vitest": "4.0.16",
-    "@prisma-next/operations": "0.3.0-dev.4",
-    "@prisma-next/test-utils": "0.0.1"
+    "vitest": "4.0.17",
+    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/operations": "0.3.0-dev.41",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "exports": {
     ".": {
-      "types": "./dist/exports/index.d.ts",
-      "import": "./dist/exports/index.js"
+      "types": "./dist/exports/index.d.mts",
+      "import": "./dist/exports/index.mjs"
     },
     "./test/utils": {
-      "types": "./dist/test/utils.d.ts",
-      "import": "./dist/test/utils.js"
+      "types": "./dist/test/utils.d.mts",
+      "import": "./dist/test/utils.mjs"
     }
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/3-tooling/emitter"
+  },
   "scripts": {
-    "build": "tsup --config tsup.config.ts",
+    "build": "tsdown",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --project tsconfig.json --noEmit",
-    "lint": "biome check . --config-path ../../../../biome.json --error-on-warnings",
-    "lint:fix": "biome check --write . --config-path ../../../../biome.json",
-    "lint:fix:unsafe": "biome check --write --unsafe . --config-path ../../../../biome.json",
-    "clean": "node ../../../../scripts/clean.mjs"
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
   }
 }

package/src/exports/index.ts

@@ -0,0 +1,9 @@
+// Re-export types from @prisma-next/contract for backward compatibility
+export type {
+  TargetFamilyHook,
+  TypesImportSpec,
+  ValidationContext,
+} from '@prisma-next/contract/types';
+export type { EmitOptions, EmitResult } from '@prisma-next/core-control-plane/emission';
+// Re-export emit function and types from core-control-plane
+export { emit } from '@prisma-next/core-control-plane/emission';

package/src/target-family.ts

@@ -0,0 +1,7 @@
+// Re-export types from @prisma-next/contract for backward compatibility
+// These types were moved to @prisma-next/contract to resolve dependency violations
+export type {
+  TargetFamilyHook,
+  TypesImportSpec,
+  ValidationContext,
+} from '@prisma-next/contract/types';

package/test/canonicalization.test.ts

@@ -0,0 +1,331 @@
+import { canonicalizeContract } from '@prisma-next/core-control-plane/emission';
+import { describe, expect, it } from 'vitest';
+import { createContractIR } from './utils';
+
+describe('canonicalization', () => {
+  it('orders top-level sections correctly', () => {
+    const ir = createContractIR({
+      capabilities: { postgres: { jsonAgg: true } },
+      meta: { source: 'test' },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+
+    const keys = Object.keys(parsed);
+    const schemaVersionIndex = keys.indexOf('schemaVersion');
+    const targetFamilyIndex = keys.indexOf('targetFamily');
+    const targetIndex = keys.indexOf('target');
+    const modelsIndex = keys.indexOf('models');
+    const storageIndex = keys.indexOf('storage');
+    const capabilitiesIndex = keys.indexOf('capabilities');
+    const metaIndex = keys.indexOf('meta');
+
+    expect(schemaVersionIndex).toBeLessThan(targetFamilyIndex);
+    expect(targetFamilyIndex).toBeLessThan(targetIndex);
+    expect(targetIndex).toBeLessThan(modelsIndex);
+    expect(modelsIndex).toBeLessThan(storageIndex);
+    expect(storageIndex).toBeLessThan(capabilitiesIndex);
+    expect(capabilitiesIndex).toBeLessThan(metaIndex);
+  });
+
+  it('omits nullable false from columns', () => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              id: { codecId: 'pg/int4@1', nativeType: 'int4', nullable: false },
+              email: { codecId: 'pg/text@1', nativeType: 'text', nullable: true },
+            },
+          },
+        },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const storage = parsed['storage'] as Record<string, unknown>;
+    const tables = storage['tables'] as Record<string, unknown>;
+    const user = tables['user'] as Record<string, unknown>;
+    const columns = user['columns'] as Record<string, unknown>;
+    const id = columns['id'] as Record<string, unknown>;
+    const email = columns['email'] as Record<string, unknown>;
+    expect(id['nullable']).toBeUndefined();
+    expect(email['nullable']).toBe(true);
+  });
+
+  it.each([
+    { nullable: false },
+    { nullable: undefined },
+  ])('omits nullable:false for columns with defaults (nullable=$nullable)', ({ nullable }) => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              created_at: {
+                codecId: 'pg/timestamptz@1',
+                nativeType: 'timestamptz',
+                nullable,
+                default: { kind: 'function', expression: 'now()' },
+              },
+              updated_at: {
+                codecId: 'pg/timestamptz@1',
+                nativeType: 'timestamptz',
+                nullable: true,
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const storage = parsed['storage'] as Record<string, unknown>;
+    const tables = storage['tables'] as Record<string, unknown>;
+    const user = tables['user'] as Record<string, unknown>;
+    const columns = user['columns'] as Record<string, unknown>;
+    const createdAt = columns['created_at'] as Record<string, unknown>;
+    const updatedAt = columns['updated_at'] as Record<string, unknown>;
+    expect(createdAt['nullable']).toBeUndefined();
+    expect(updatedAt['nullable']).toBe(true);
+  });
+
+  it('preserves nullable:true for columns with defaults', () => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              bio: {
+                codecId: 'pg/text@1',
+                nativeType: 'text',
+                nullable: true,
+                default: { kind: 'literal', value: '' },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const storage = parsed['storage'] as Record<string, unknown>;
+    const tables = storage['tables'] as Record<string, unknown>;
+    const user = tables['user'] as Record<string, unknown>;
+    const columns = user['columns'] as Record<string, unknown>;
+    const bio = columns['bio'] as Record<string, unknown>;
+    expect(bio['nullable']).toBe(true);
+    expect(bio['default']).toEqual({ kind: 'literal', value: '' });
+  });
+
+  it('omits empty arrays and objects except required ones', () => {
+    const ir = createContractIR();
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result);
+    expect(parsed).toMatchObject({
+      models: expect.anything(),
+      storage: {
+        tables: expect.anything(),
+      },
+    });
+    // Required top-level fields (capabilities, extensionPacks, meta, relations, sources) are preserved even when empty
+    // because they are required by ContractIR and needed for round-trip tests
+    expect(parsed).toMatchObject({
+      capabilities: expect.anything(),
+      extensionPacks: expect.anything(),
+      meta: expect.anything(),
+      relations: expect.anything(),
+      sources: expect.anything(),
+    });
+  });
+
+  it('preserves semantic array order for column lists', () => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              first: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+              second: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+            },
+            primaryKey: {
+              columns: ['second', 'first'],
+            },
+          },
+        },
+      },
+    });
+
+    const result1 = canonicalizeContract(ir);
+
+    const ir2 = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              first: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+              second: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+            },
+            primaryKey: {
+              columns: ['first', 'second'],
+            },
+          },
+        },
+      },
+    });
+
+    const result2 = canonicalizeContract(ir2);
+
+    expect(result1).not.toBe(result2);
+  });
+
+  it('sorts indexes by canonical name', () => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              id: { codecId: 'pg/int4@1', nativeType: 'int4', nullable: false },
+            },
+            indexes: [
+              { columns: ['id'], name: 'user_email_idx' },
+              { columns: ['id'], name: 'user_name_idx' },
+            ],
+          },
+        },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const storage = parsed['storage'] as Record<string, unknown>;
+    const tables = storage['tables'] as Record<string, unknown>;
+    const user = tables['user'] as Record<string, unknown>;
+    const indexes = user['indexes'] as Array<{ name: string }>;
+    const indexNames = indexes.map((idx) => idx.name);
+    expect(indexNames).toEqual(['user_email_idx', 'user_name_idx']);
+  });
+
+  it('sorts uniques by canonical name', () => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              id: { codecId: 'pg/int4@1', nativeType: 'int4', nullable: false },
+              email: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+              username: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+            },
+            uniques: [
+              { columns: ['username'], name: 'user_username_key' },
+              { columns: ['email'], name: 'user_email_key' },
+            ],
+          },
+        },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const storage = parsed['storage'] as Record<string, unknown>;
+    const tables = storage['tables'] as Record<string, unknown>;
+    const user = tables['user'] as Record<string, unknown>;
+    const uniques = user['uniques'] as Array<{ name: string }>;
+    const uniqueNames = uniques.map((u) => u.name);
+    expect(uniqueNames).toEqual(['user_email_key', 'user_username_key']);
+  });
+
+  it('preserves column order in composite unique constraints', () => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              id: { codecId: 'pg/int4@1', nativeType: 'int4', nullable: false },
+              first_name: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+              last_name: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+            },
+            uniques: [{ columns: ['last_name', 'first_name'], name: 'user_name_key' }],
+          },
+        },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const storage = parsed['storage'] as Record<string, unknown>;
+    const tables = storage['tables'] as Record<string, unknown>;
+    const user = tables['user'] as Record<string, unknown>;
+    const uniques = user['uniques'] as Array<{ columns: string[] }>;
+    expect(uniques[0]!.columns).toEqual(['last_name', 'first_name']);
+  });
+
+  it('sorts nested object keys lexicographically', () => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              z_field: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+              a_field: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+              m_field: { codecId: 'pg/text@1', nativeType: 'text', nullable: false },
+            },
+          },
+        },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const storage = parsed['storage'] as Record<string, unknown>;
+    const tables = storage['tables'] as Record<string, unknown>;
+    const user = tables['user'] as Record<string, unknown>;
+    const columns = user['columns'] as Record<string, unknown>;
+    const columnKeys = Object.keys(columns);
+    expect(columnKeys).toEqual(['a_field', 'm_field', 'z_field']);
+  });
+
+  it('sorts extension namespaces lexicographically', () => {
+    const ir = createContractIR({
+      extensionPacks: {
+        pgvector: { version: '0.0.1' },
+        postgres: { version: '0.0.1' },
+        another: { version: '0.0.1' },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const extensionPacks = parsed['extensionPacks'] as Record<string, unknown>;
+    const extensionKeys = Object.keys(extensionPacks);
+    expect(extensionKeys).toEqual(['another', 'pgvector', 'postgres']);
+  });
+
+  it('omits generated false', () => {
+    const ir = createContractIR({
+      storage: {
+        tables: {
+          user: {
+            columns: {
+              id: { codecId: 'pg/int4@1', nativeType: 'int4', nullable: false, generated: false },
+            },
+          },
+        },
+      },
+    });
+
+    const result = canonicalizeContract(ir);
+    const parsed = JSON.parse(result) as Record<string, unknown>;
+    const storage = parsed['storage'] as Record<string, unknown>;
+    const tables = storage['tables'] as Record<string, unknown>;
+    const user = tables['user'] as Record<string, unknown>;
+    const columns = user['columns'] as Record<string, unknown>;
+    const id = columns['id'] as Record<string, unknown>;
+    expect(id['generated']).toBeUndefined();
+  });
+});