@prisma-next/framework-components 0.8.0 → 0.9.0-dev.1

package/dist/ir.mjs

@@ -0,0 +1,39 @@
+//#region src/ir/ir-node.ts
+var IRNodeBase = class {};
+/**
+* Seal an IR class instance after its constructor has assigned all
+* fields. The free-helper form (rather than a `protected freeze()`
+* instance method) keeps the class type structurally narrow so emitted
+* contract literal types remain assignable to their class types.
+*
+* The helper name stays `freezeNode` — it operates on IR nodes
+* regardless of root naming.
+*/
+function freezeNode(node) {
+	Object.freeze(node);
+	return node;
+}
+//#endregion
+//#region src/ir/namespace.ts
+/**
+* Reserved sentinel namespace id meaning
+* "no namespace bound at authoring time; resolve from connection context".
+*
+* Materialised target-side as a singleton subclass of the target's
+* `NamespaceBase` concretion that overrides the namespace's
+* qualifier-emission methods to elide the prefix entirely. Call sites
+* stay polymorphic and never branch on `id === UNSPECIFIED_NAMESPACE_ID`
+* — the singleton's overrides drop the qualifier so emitted SQL / Mongo
+* commands look unqualified.
+*
+* Encoded as an exported const (rather than scattered string literals)
+* so the sentinel-id invariant is single-sourced: any production-source
+* site that constructs an unspecified-namespace singleton imports this
+* constant.
+*/
+const UNSPECIFIED_NAMESPACE_ID = "__unspecified__";
+var NamespaceBase = class extends IRNodeBase {};
+//#endregion
+export { IRNodeBase, NamespaceBase, UNSPECIFIED_NAMESPACE_ID, freezeNode };
+
+//# sourceMappingURL=ir.mjs.map

package/dist/ir.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.mjs","names":[],"sources":["../src/ir/ir-node.ts","../src/ir/namespace.ts"],"sourcesContent":["/**\n * Framework-level IR alphabet.\n *\n * The framework's contribution to Contract IR / Schema IR is a common\n * root for the IR class hierarchy and a freeze affordance. Family\n * abstract bases (e.g. `SqlNode`, `MongoSchemaIRNode`) refine the alphabet\n * for their family shape; targets ship the concrete classes.\n *\n * `kind` is an optional discriminator on the base. Families and leaves\n * that benefit from discriminated-union dispatch declare their own\n * literal `kind` at the level that earns it — Mongo leaves carry\n * per-class literals (`readonly kind = 'mongo-collection' as const`)\n * because Mongo IR has polymorphic walkers; SQL declares a single\n * family-level `kind = 'sql'` on `SqlNode` because SQL IR has no\n * polymorphic dispatch today. No framework consumer dispatches on\n * `IRNode.kind` at the BASE type — every dispatch site narrows\n * through a union of leaves where each leaf carries a literal kind, so\n * requiring `kind` at the base would be unearned. Future leaves that\n * earn polymorphic dispatch override with a required literal at that\n * leaf (e.g. `override readonly kind = 'postgres-enum' as const`).\n *\n * `IRNodeBase` carries no methods: the freeze-and-assign affordance\n * lives in the free `freezeNode` helper below. Keeping `freezeNode` out\n * of the class type means an emitted contract literal type\n * (`{ readonly kind: 'mongo-collection', ... }` or an unkeyed literal\n * like `{ nativeType, codecId, nullable }`) is structurally assignable\n * to its class type — a `protected freeze()` instance method would\n * otherwise leak into the public type surface and require the literal\n * to carry it too.\n *\n * Subclasses construct fields then call `freezeNode(this)` to seal the\n * instance. Frozen instances + plain readonly fields keep IR nodes\n * JSON-clean by construction, so `JSON.stringify(node)` produces canonical\n * JSON without a `toJSON()` method. The `ContractSerializer` SPI handles\n * round-trip from canonical JSON back to typed class instances.\n *\n * The name (`IRNode` / `IRNodeBase`) reflects the dual-hierarchy reality:\n * this base is the common root for both Contract IR and Schema IR class\n * hierarchies, not a Schema-IR-specific alphabet.\n */\n\nexport interface IRNode {\n  readonly kind?: string;\n}\n\nexport abstract class IRNodeBase implements IRNode {\n  abstract readonly kind?: string;\n}\n\n/**\n * Seal an IR class instance after its constructor has assigned all\n * fields. The free-helper form (rather than a `protected freeze()`\n * instance method) keeps the class type structurally narrow so emitted\n * contract literal types remain assignable to their class types.\n *\n * The helper name stays `freezeNode` — it operates on IR nodes\n * regardless of root naming.\n */\nexport function freezeNode<T extends IRNode>(node: T): T {\n  Object.freeze(node);\n  return node;\n}\n","import { type IRNode, IRNodeBase } from './ir-node';\n\n/**\n * Reserved sentinel namespace id meaning\n * \"no namespace bound at authoring time; resolve from connection context\".\n *\n * Materialised target-side as a singleton subclass of the target's\n * `NamespaceBase` concretion that overrides the namespace's\n * qualifier-emission methods to elide the prefix entirely. Call sites\n * stay polymorphic and never branch on `id === UNSPECIFIED_NAMESPACE_ID`\n * — the singleton's overrides drop the qualifier so emitted SQL / Mongo\n * commands look unqualified.\n *\n * Encoded as an exported const (rather than scattered string literals)\n * so the sentinel-id invariant is single-sourced: any production-source\n * site that constructs an unspecified-namespace singleton imports this\n * constant.\n */\nexport const UNSPECIFIED_NAMESPACE_ID = '__unspecified__' as const;\n\n/**\n * Framework-level building block for a \"namespace\" — the database-level\n * grouping under which storage objects (tables, collections, enums, …)\n * reside. Each target's namespace concretion maps the framework concept to\n * a target-native binding:\n *\n * - Postgres: a schema (`CREATE SCHEMA …`); rendered as `\"<schema>\"`.\n * - SQLite: the singleton `UNSPECIFIED_NAMESPACE_ID`; emitted SQL has no qualifier.\n * - Mongo: the connection's `db` field; addressed as a database name.\n *\n * See `UNSPECIFIED_NAMESPACE_ID` above for the sentinel id and the\n * singleton-subclass pattern that materialises it.\n */\nexport interface Namespace extends IRNode {\n  readonly id: string;\n}\n\nexport abstract class NamespaceBase extends IRNodeBase implements Namespace {\n  abstract readonly id: string;\n}\n"],"mappings":";AA6CA,IAAsB,aAAtB,MAAmD;;;;;;;;;;AAanD,SAAgB,WAA6B,MAAY;CACvD,OAAO,OAAO,KAAK;CACnB,OAAO;;;;;;;;;;;;;;;;;;;;AC1CT,MAAa,2BAA2B;AAmBxC,IAAsB,gBAAtB,cAA4C,WAAgC"}

package/dist/runtime.d.mts

@@ -1,4 +1,4 @@
-import { o as CodecCallContext } from "./codec-DcjlJbcO.mjs";
+import { o as CodecCallContext } from "./codec-BFOsuHKK.mjs";
 import { PlanMeta } from "@prisma-next/contract/types";
 
 //#region src/annotations.d.ts

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@prisma-next/framework-components",
-  "version": "0.8.0",
+  "version": "0.9.0-dev.1",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Framework component types, assembly logic, and stack creation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.8.0",
-    "@prisma-next/operations": "0.8.0",
-    "@prisma-next/ts-render": "0.8.0",
-    "@prisma-next/utils": "0.8.0",
+    "@prisma-next/contract": "0.9.0-dev.1",
+    "@prisma-next/operations": "0.9.0-dev.1",
+    "@prisma-next/ts-render": "0.9.0-dev.1",
+    "@prisma-next/utils": "0.9.0-dev.1",
     "@standard-schema/spec": "^1.1.0"
   },
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.8.0",
-    "@prisma-next/tsdown": "0.8.0",
+    "@prisma-next/tsconfig": "0.9.0-dev.1",
+    "@prisma-next/tsdown": "0.9.0-dev.1",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.5"
@@ -30,6 +30,7 @@
     "./control": "./dist/control.mjs",
     "./emission": "./dist/emission.mjs",
     "./execution": "./dist/execution.mjs",
+    "./ir": "./dist/ir.mjs",
     "./psl-ast": "./dist/psl-ast.mjs",
     "./runtime": "./dist/runtime.mjs",
     "./utils": "./dist/utils.mjs",

package/src/control/contract-serializer.ts

@@ -0,0 +1,37 @@
+import type { JsonObject } from '@prisma-next/utils/json';
+
+/**
+ * Framework SPI for moving a contract between its canonical on-disk JSON
+ * form and its in-memory class-hierarchy form. Both directions live on the
+ * same SPI so the conceptual seam — "the boundary where the contract
+ * crosses between persisted JSON and live class instances" — has a single
+ * named home.
+ *
+ * Both faces are needed by the framework today (round-trip property tests,
+ * drift detection, future canonicalization), not eventually. For most
+ * targets `serializeContract` is identity over JSON-clean class instances;
+ * the method exists because the seam is real, not as a convention placeholder.
+ *
+ * Implementers compose this SPI as a named property on their target
+ * descriptor (`descriptor.contractSerializer`); the descriptor itself
+ * remains the aggregator of all per-target SPIs.
+ */
+export interface ContractSerializer<TContract> {
+  /**
+   * Validate the JSON shape and construct typed class instances. Throws on
+   * structural / domain / storage validation failures. Returns the typed
+   * contract on success.
+   */
+  deserializeContract(json: unknown): TContract;
+
+  /**
+   * Serialize a typed contract to its canonical JSON shape. Returns
+   * `JsonObject` so callers can stringify, hash, or feed the result into
+   * another SPI without re-asserting JSON-cleanness. Targets whose contract
+   * fields are JSON-clean by construction return the contract unchanged
+   * (the symmetric pair to `deserializeContract`); targets that need to
+   * canonicalize on the way out (key ordering, dropping computed-only
+   * fields, normalizing numeric encodings) do that work here.
+   */
+  serializeContract(contract: TContract): JsonObject;
+}

package/src/control/control-capabilities.ts

@@ -83,7 +83,7 @@ export function hasOperationPreview<TFamilyId extends string, TSchemaIR>(
  * extension-contract-spaces project spec — TML-2397).
  *
  * The CLI's shared `applyAggregate` primitive uses this guard so that
- * `db init` / `db update` / `migration apply` route uniformly through one
+ * `db init` / `db update` / `migrate` route uniformly through one
  * dispatch path regardless of family.
  */
 export function hasMultiSpaceRunner<TFamilyId extends string, TTargetId extends string>(

package/src/control/control-descriptors.ts

@@ -1,3 +1,4 @@
+import type { Contract } from '@prisma-next/contract/types';
 import type {
   AdapterDescriptor,
   DriverDescriptor,
@@ -5,6 +6,7 @@ import type {
   FamilyDescriptor,
   TargetDescriptor,
 } from '../shared/framework-components';
+import type { ContractSerializer } from './contract-serializer';
 import type {
   ControlAdapterInstance,
   ControlDriverInstance,
@@ -33,7 +35,15 @@ export interface ControlTargetDescriptor<
     TFamilyId,
     TTargetId
   >,
+  TContract extends Contract = Contract,
 > extends TargetDescriptor<TFamilyId, TTargetId> {
+  /**
+   * JSON ⇄ class boundary for this target's contract. Every target
+   * ships the SPI: framework consumers reach the serializer through
+   * `descriptor.contractSerializer` rather than importing a per-target
+   * `deserializeContract` helper. The descriptor IS the aggregator.
+   */
+  readonly contractSerializer: ContractSerializer<TContract>;
   create(): TTargetInstance;
 }
 

package/src/control/control-instances.ts

@@ -15,7 +15,15 @@ import type {
 
 export interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR>
   extends FamilyInstance<TFamilyId> {
-  validateContract(contractJson: unknown): Contract;
+  /**
+   * The family seam-of-record for on-disk contract reads. Structurally
+   * validates the JSON envelope and hydrates IR-class instances via the
+   * per-target ContractSerializer. The single named entry point every
+   * CLI on-disk read crosses (TML-2536) — `as Contract` casts in
+   * production package sources are a serializer-bypass smell guarded by
+   * `pnpm lint:no-contract-cast`.
+   */
+  deserializeContract(contractJson: unknown): Contract;
 
   verify(options: {
     readonly driver: ControlDriverInstance<TFamilyId, string>;
@@ -25,27 +33,19 @@ export interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR>
     readonly configPath?: string;
   }): Promise<VerifyDatabaseResult>;
 
-  schemaVerify(options: {
-    readonly driver: ControlDriverInstance<TFamilyId, string>;
-    readonly contract: unknown;
-    readonly strict: boolean;
-    readonly contractPath: string;
-    readonly configPath?: string;
-    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, string>>;
-  }): Promise<VerifyDatabaseSchemaResult>;
-
   /**
    * Verify a contract against an already-introspected schema slice.
    *
-   * Difference from {@link schemaVerify}: no `driver`, no introspection
-   * — the caller hands over the schema directly. Used by the aggregate
-   * verifier to invoke the family's verification logic per member,
-   * with the schema **pre-projected** to that member's claimed slice
-   * via {@link import('@prisma-next/migration-tools/aggregate').projectSchemaToSpace}.
+   * Callers that need to verify against the live database compose
+   * {@link introspect} + `verifySchema` directly; the family
+   * interface deliberately exposes the introspection step so callers
+   * can pre-project the schema (e.g. the aggregate verifier projects
+   * each member's claimed slice via
+   * {@link import('@prisma-next/migration-tools/aggregate').projectSchemaToSpace}).
    *
    * Synchronous — no I/O. Idempotent.
    */
-  schemaVerifyAgainstSchema(options: {
+  verifySchema(options: {
     readonly contract: unknown;
     readonly schema: TSchemaIR;
     readonly strict: boolean;

package/src/control/control-migration-types.ts

@@ -50,13 +50,19 @@ export interface MigrationHints {
  * The on-disk JSON shape in `migration.json` matches this type
  * field-for-field — `JSON.stringify(metadata, null, 2)` is the canonical
  * writer output (defined in `@prisma-next/migration-tools/io`).
+ *
+ * The manifest carries identity (`from`, `to`, `migrationHash`) but
+ * not the full contract IRs themselves. The destination contract for a
+ * migration lives in the sibling `end-contract.json` on disk; the
+ * predecessor's contract lives in its own directory's `end-contract.json`.
+ * The runner depends only on `migration.json` + `ops.json` per package
+ * (plus the project-root / per-space `contract.json` head). See
+ * `docs/architecture docs/subsystems/7. Migration System.md`.
  */
 export interface MigrationMetadata {
   readonly migrationHash: string;
   readonly from: string | null;
   readonly to: string;
-  readonly fromContract: Contract | null;
-  readonly toContract: Contract;
   readonly hints: MigrationHints;
   readonly labels: readonly string[];
   /**
@@ -394,8 +400,8 @@ export interface MigrationPlanner<
      * Required at every call site to make the structural fact "I have a
      * prior contract / I don't" visible in the type. Reconciliation
      * commands (`db init`, `db update`) introspect a live schema and pass
-     * `null`; authoring commands (`migration plan`) pass the previous
-     * bundle's `metadata.toContract`.
+     * `null`; authoring commands (`migration plan`) load the previous
+     * bundle's `end-contract.json` from disk and pass the parsed value.
      */
     readonly fromContract: Contract | null;
     /**

package/src/control/control-schema-view.ts

@@ -8,7 +8,7 @@
  * core view via the `toSchemaView` method on `FamilyInstance`.
  */
 
-export type SchemaNodeKind =
+export type SchemaViewNodeKind =
   | 'root'
   | 'namespace'
   | 'collection'
@@ -22,7 +22,7 @@ export interface SchemaTreeVisitor<R> {
 }
 
 export interface SchemaTreeNodeOptions {
-  readonly kind: SchemaNodeKind;
+  readonly kind: SchemaViewNodeKind;
   readonly id: string;
   readonly label: string;
   readonly meta?: Record<string, unknown>;
@@ -30,7 +30,7 @@ export interface SchemaTreeNodeOptions {
 }
 
 export class SchemaTreeNode {
-  readonly kind: SchemaNodeKind;
+  readonly kind: SchemaViewNodeKind;
   readonly id: string;
   readonly label: string;
   readonly meta?: Record<string, unknown>;

package/src/control/control-spaces.ts

@@ -39,9 +39,8 @@ export interface ContractSpaceHeadRef {
 
 /**
  * Canonical structural shape of a migration package — the unit a planner
- * produces and a runner consumes: a directory name, the ADR 197 metadata
- * envelope (which carries the `toContract` snapshot), and the operation
- * list.
+ * produces and a runner consumes: a directory name, the metadata
+ * envelope, and the operation list.
  *
  * In-memory by default. Readers in `@prisma-next/migration-tools`
  * (`readMigrationPackage` / `readMigrationsDir`) return the augmented

package/src/control/control-stack.ts

@@ -2,11 +2,13 @@ import type { Codec } from '../shared/codec';
 import type { CodecLookup, CodecMeta } from '../shared/codec-types';
 import type {
   AuthoringContributions,
+  AuthoringEntityTypeNamespace,
   AuthoringFieldNamespace,
   AuthoringTypeNamespace,
 } from '../shared/framework-authoring';
 import {
   assertNoCrossRegistryCollisions,
+  isAuthoringEntityTypeDescriptor,
   isAuthoringFieldPresetDescriptor,
   isAuthoringTypeConstructorDescriptor,
   mergeAuthoringNamespaces,
@@ -29,6 +31,7 @@ import type {
 export interface AssembledAuthoringContributions {
   readonly field: AuthoringFieldNamespace;
   readonly type: AuthoringTypeNamespace;
+  readonly entityTypes: AuthoringEntityTypeNamespace;
 }
 
 export interface ControlStack<
@@ -147,6 +150,7 @@ export function assembleAuthoringContributions(
 ): AssembledAuthoringContributions {
   const field = {} as Record<string, unknown>;
   const type = {} as Record<string, unknown>;
+  const entityTypes = {} as Record<string, unknown>;
 
   for (const descriptor of descriptors) {
     if (descriptor.authoring?.field) {
@@ -158,25 +162,35 @@ export function assembleAuthoringContributions(
         'field',
       );
     }
-    if (!descriptor.authoring?.type) {
-      continue;
+    if (descriptor.authoring?.type) {
+      mergeAuthoringNamespaces(
+        type,
+        descriptor.authoring.type,
+        [],
+        isAuthoringTypeConstructorDescriptor,
+        'type',
+      );
+    }
+    if (descriptor.authoring?.entityTypes) {
+      mergeAuthoringNamespaces(
+        entityTypes,
+        descriptor.authoring.entityTypes,
+        [],
+        isAuthoringEntityTypeDescriptor,
+        'entity',
+      );
     }
-    mergeAuthoringNamespaces(
-      type,
-      descriptor.authoring.type,
-      [],
-      isAuthoringTypeConstructorDescriptor,
-      'type',
-    );
   }
 
   const fieldNamespace = field as AuthoringFieldNamespace;
   const typeNamespace = type as AuthoringTypeNamespace;
-  assertNoCrossRegistryCollisions(typeNamespace, fieldNamespace);
+  const entityTypeNamespace = entityTypes as AuthoringEntityTypeNamespace;
+  assertNoCrossRegistryCollisions(typeNamespace, fieldNamespace, entityTypeNamespace);
 
   return {
     field: fieldNamespace,
     type: typeNamespace,
+    entityTypes: entityTypeNamespace,
   };
 }
 

package/src/control/schema-verifier.ts

@@ -0,0 +1,51 @@
+import type { SchemaIssue } from './control-result-types';
+
+/**
+ * Framework SPI for verifying that an introspected schema matches the
+ * contract that authored it. The implementer walks the target's IR
+ * natively — concrete classes, target-only kinds — and reports issues.
+ *
+ * The framework verifier (per FR6) walks the contract-space aggregate,
+ * dispatches to the right target's verifier (`descriptor.schemaVerifier`)
+ * per space, and wraps the per-target results into a unified
+ * `VerifyDatabaseSchemaResult` with timings, summary, and per-node
+ * verification tree.
+ *
+ * Family-level abstract bases (e.g. `SqlSchemaVerifierBase`) carry the
+ * shared SQL/Mongo walk logic and expose protected hooks for target
+ * extensions; concrete target verifiers (`PostgresSchemaVerifier extends
+ * SqlSchemaVerifierBase`) own the dispatch on target-specific kinds.
+ *
+ * Target-specific issue kinds (RLS-policy-mismatch, namespace-mismatch,
+ * future function-shape-mismatch) are widened target-side; the framework
+ * `SchemaIssue` union (in `control-result-types.ts`) is intentionally not
+ * generic over target kinds in this project — see the spec's
+ * "Forward note: SchemaIssue layering" for the layering observation
+ * captured for a future project.
+ */
+export interface SchemaVerifier<TContract, TSchema> {
+  verifySchema(options: SchemaVerifyOptions<TContract, TSchema>): SchemaVerifyResult;
+}
+
+/**
+ * Minimal per-target verifier input. Family abstract bases extend this
+ * shape with family-specific options (`strict`, `frameworkComponents`,
+ * codec hooks, …) — the framework SPI itself stays at the contract +
+ * schema pair every implementer needs.
+ */
+export interface SchemaVerifyOptions<TContract, TSchema> {
+  readonly contract: TContract;
+  readonly schema: TSchema;
+}
+
+/**
+ * Per-target verifier result. The framework verifier wraps these into the
+ * existing `VerifyDatabaseSchemaResult` envelope (with timings, summary,
+ * per-node verification tree); the SPI itself returns just the
+ * core ok/issues pair so the seam between target-walk and
+ * framework-aggregation is explicit.
+ */
+export interface SchemaVerifyResult {
+  readonly ok: boolean;
+  readonly issues: readonly SchemaIssue[];
+}

package/src/exports/authoring.ts

@@ -3,6 +3,11 @@ export type {
   AuthoringArgumentDescriptor,
   AuthoringColumnDefaultTemplate,
   AuthoringContributions,
+  AuthoringEntityContext,
+  AuthoringEntityTypeDescriptor,
+  AuthoringEntityTypeFactoryOutput,
+  AuthoringEntityTypeNamespace,
+  AuthoringEntityTypeTemplateOutput,
   AuthoringFieldNamespace,
   AuthoringFieldPresetDescriptor,
   AuthoringFieldPresetOutput,
@@ -14,9 +19,11 @@ export type {
 export {
   assertNoCrossRegistryCollisions,
   hasRegisteredFieldNamespace,
+  instantiateAuthoringEntityType,
   instantiateAuthoringFieldPreset,
   instantiateAuthoringTypeConstructor,
   isAuthoringArgRef,
+  isAuthoringEntityTypeDescriptor,
   isAuthoringFieldPresetDescriptor,
   isAuthoringTypeConstructorDescriptor,
   mergeAuthoringNamespaces,

package/src/exports/control.ts

@@ -1,4 +1,5 @@
 export type { ImportRequirement } from '@prisma-next/ts-render';
+export type { ContractSerializer } from '../control/contract-serializer';
 export type {
   MigratableTargetDescriptor,
   OperationPreviewCapable,
@@ -78,9 +79,9 @@ export {
 } from '../control/control-result-types';
 export type {
   CoreSchemaView,
-  SchemaNodeKind,
   SchemaTreeNodeOptions,
   SchemaTreeVisitor,
+  SchemaViewNodeKind,
 } from '../control/control-schema-view';
 export { SchemaTreeNode } from '../control/control-schema-view';
 export type {
@@ -105,6 +106,11 @@ export {
   extractComponentIds,
   extractQueryOperationTypeImports,
 } from '../control/control-stack';
+export type {
+  SchemaVerifier,
+  SchemaVerifyOptions,
+  SchemaVerifyResult,
+} from '../control/schema-verifier';
 export type {
   ControlMutationDefaultEntry,
   ControlMutationDefaultRegistry,

package/src/exports/ir.ts

@@ -0,0 +1,6 @@
+export type { IRNode } from '../ir/ir-node';
+export { freezeNode, IRNodeBase } from '../ir/ir-node';
+export type { Namespace } from '../ir/namespace';
+export { NamespaceBase, UNSPECIFIED_NAMESPACE_ID } from '../ir/namespace';
+export type { Storage } from '../ir/storage';
+export type { StorageType } from '../ir/storage-type';

package/src/ir/ir-node.ts

@@ -0,0 +1,62 @@
+/**
+ * Framework-level IR alphabet.
+ *
+ * The framework's contribution to Contract IR / Schema IR is a common
+ * root for the IR class hierarchy and a freeze affordance. Family
+ * abstract bases (e.g. `SqlNode`, `MongoSchemaIRNode`) refine the alphabet
+ * for their family shape; targets ship the concrete classes.
+ *
+ * `kind` is an optional discriminator on the base. Families and leaves
+ * that benefit from discriminated-union dispatch declare their own
+ * literal `kind` at the level that earns it — Mongo leaves carry
+ * per-class literals (`readonly kind = 'mongo-collection' as const`)
+ * because Mongo IR has polymorphic walkers; SQL declares a single
+ * family-level `kind = 'sql'` on `SqlNode` because SQL IR has no
+ * polymorphic dispatch today. No framework consumer dispatches on
+ * `IRNode.kind` at the BASE type — every dispatch site narrows
+ * through a union of leaves where each leaf carries a literal kind, so
+ * requiring `kind` at the base would be unearned. Future leaves that
+ * earn polymorphic dispatch override with a required literal at that
+ * leaf (e.g. `override readonly kind = 'postgres-enum' as const`).
+ *
+ * `IRNodeBase` carries no methods: the freeze-and-assign affordance
+ * lives in the free `freezeNode` helper below. Keeping `freezeNode` out
+ * of the class type means an emitted contract literal type
+ * (`{ readonly kind: 'mongo-collection', ... }` or an unkeyed literal
+ * like `{ nativeType, codecId, nullable }`) is structurally assignable
+ * to its class type — a `protected freeze()` instance method would
+ * otherwise leak into the public type surface and require the literal
+ * to carry it too.
+ *
+ * Subclasses construct fields then call `freezeNode(this)` to seal the
+ * instance. Frozen instances + plain readonly fields keep IR nodes
+ * JSON-clean by construction, so `JSON.stringify(node)` produces canonical
+ * JSON without a `toJSON()` method. The `ContractSerializer` SPI handles
+ * round-trip from canonical JSON back to typed class instances.
+ *
+ * The name (`IRNode` / `IRNodeBase`) reflects the dual-hierarchy reality:
+ * this base is the common root for both Contract IR and Schema IR class
+ * hierarchies, not a Schema-IR-specific alphabet.
+ */
+
+export interface IRNode {
+  readonly kind?: string;
+}
+
+export abstract class IRNodeBase implements IRNode {
+  abstract readonly kind?: string;
+}
+
+/**
+ * Seal an IR class instance after its constructor has assigned all
+ * fields. The free-helper form (rather than a `protected freeze()`
+ * instance method) keeps the class type structurally narrow so emitted
+ * contract literal types remain assignable to their class types.
+ *
+ * The helper name stays `freezeNode` — it operates on IR nodes
+ * regardless of root naming.
+ */
+export function freezeNode<T extends IRNode>(node: T): T {
+  Object.freeze(node);
+  return node;
+}

package/src/ir/namespace.ts

@@ -0,0 +1,40 @@
+import { type IRNode, IRNodeBase } from './ir-node';
+
+/**
+ * Reserved sentinel namespace id meaning
+ * "no namespace bound at authoring time; resolve from connection context".
+ *
+ * Materialised target-side as a singleton subclass of the target's
+ * `NamespaceBase` concretion that overrides the namespace's
+ * qualifier-emission methods to elide the prefix entirely. Call sites
+ * stay polymorphic and never branch on `id === UNSPECIFIED_NAMESPACE_ID`
+ * — the singleton's overrides drop the qualifier so emitted SQL / Mongo
+ * commands look unqualified.
+ *
+ * Encoded as an exported const (rather than scattered string literals)
+ * so the sentinel-id invariant is single-sourced: any production-source
+ * site that constructs an unspecified-namespace singleton imports this
+ * constant.
+ */
+export const UNSPECIFIED_NAMESPACE_ID = '__unspecified__' as const;
+
+/**
+ * Framework-level building block for a "namespace" — the database-level
+ * grouping under which storage objects (tables, collections, enums, …)
+ * reside. Each target's namespace concretion maps the framework concept to
+ * a target-native binding:
+ *
+ * - Postgres: a schema (`CREATE SCHEMA …`); rendered as `"<schema>"`.
+ * - SQLite: the singleton `UNSPECIFIED_NAMESPACE_ID`; emitted SQL has no qualifier.
+ * - Mongo: the connection's `db` field; addressed as a database name.
+ *
+ * See `UNSPECIFIED_NAMESPACE_ID` above for the sentinel id and the
+ * singleton-subclass pattern that materialises it.
+ */
+export interface Namespace extends IRNode {
+  readonly id: string;
+}
+
+export abstract class NamespaceBase extends IRNodeBase implements Namespace {
+  abstract readonly id: string;
+}

package/src/ir/storage-type.ts

@@ -0,0 +1,23 @@
+import type { IRNode } from './ir-node';
+
+/**
+ * Framework-level alphabet for entries in a storage `types` slot.
+ *
+ * The slot is polymorphic at the framework level: a family or target can
+ * persist either a JSON-clean codec-triple object literal (carrying
+ * `kind: 'codec-instance'`) or a class-instance IR node with a narrower
+ * kind discriminator (e.g. `'postgres-enum'`). Hydration walkers,
+ * verifiers, and planners dispatch on the `kind` literal to recover the
+ * precise variant.
+ *
+ * The `kind` field is required at this layer (in contrast with
+ * `IRNode.kind` which is optional) because the slot's downstream
+ * consumers dispatch on it — without a guaranteed discriminator the
+ * polymorphic walk cannot pick the right reader. Concrete variants
+ * narrow `kind` to their literal and add their own field set;
+ * downstream consumers use `kind`-discriminator helpers to recover
+ * the precise shape.
+ */
+export interface StorageType extends IRNode {
+  readonly kind: string;
+}

package/src/ir/storage.ts

@@ -0,0 +1,41 @@
+import type { IRNode } from './ir-node';
+import type { Namespace } from './namespace';
+
+/**
+ * Framework-level promise that every Contract IR / Schema IR carries a
+ * collection of namespaces keyed by namespace id. Family storage
+ * concretions (`SqlStorage`, `MongoStorage`) refine the shape with
+ * family-specific fields (tables, collections, enums, …); target
+ * concretions add target fields where the family vocabulary doesn't
+ * reach.
+ *
+ * Keeping `namespaces` at the framework layer enforces that every storage
+ * object — across any target — is namespace-scoped. The framework can
+ * therefore walk the namespace map without knowing the family alphabet, and
+ * the `(namespace.id, name)` keying that the verifier and planner depend on
+ * is honest at every layer.
+ *
+ * Extends `IRNode` so the framework's IR-walking surfaces (verifiers,
+ * serializers) can dispatch on `Storage`-typed slots through the same
+ * IR-node alphabet as every other node — the structural dual already
+ * holds in code (every concrete storage class extends an IR-node base);
+ * the interface promotion makes the typing honest.
+ *
+ * **Persisted envelope shape is target-owned, not framework-promised.**
+ * Whether the `namespaces` map appears in the on-disk JSON envelope is
+ * a per-target decision made by `ContractSerializer.serializeContract`.
+ * Some targets emit a JSON-clean namespace shape that round-trips
+ * through `JSON.stringify` cleanly (SQL today via the family-layer
+ * identity serializer); others ship runtime-only fields on their
+ * namespace concretions and override `serializeContract` to strip
+ * them (Mongo). Future open (F16): extend the per-target
+ * `ContractSerializer` integration-test surface with an explicit
+ * envelope-shape assertion for each target, so the strip-vs-pass-through
+ * choice is locked at test time rather than implied by the override
+ * presence/absence. Earned by PR2's per-target namespace lift, when
+ * `PostgresSchema` / `SqliteUnspecifiedDatabase` start carrying
+ * target-specific fields.
+ */
+export interface Storage extends IRNode {
+  readonly namespaces: Readonly<Record<string, Namespace>>;
+}