@prisma-next/sql-contract 0.9.0 → 0.10.0

package/src/ir/sql-storage.ts

@@ -2,15 +2,16 @@ import type { StorageHashBase } from '@prisma-next/contract/types';
 import {
   freezeNode,
   type Namespace,
+  NamespaceBase,
   type Storage,
-  UNSPECIFIED_NAMESPACE_ID,
+  UNBOUND_NAMESPACE_ID,
 } from '@prisma-next/framework-components/ir';
 import {
   isPostgresEnumStorageEntry,
   type PostgresEnumStorageEntry,
 } from './postgres-enum-storage-entry';
 import { SqlNode } from './sql-node';
-import { SqlUnspecifiedNamespace } from './sql-unspecified-namespace';
+import { SqlUnboundNamespace } from './sql-unbound-namespace';
 import { StorageTable, type StorageTableInput } from './storage-table';
 import {
   isStorageTypeInstance,
@@ -19,50 +20,104 @@ import {
 } from './storage-type-instance';
 
 /**
- * Polymorphic value type for `SqlStorage.types` entries (Decision 18,
- * Option B). The slot's framework alphabet is `StorageType` — codec
- * triples (`StorageTypeInstance` with `kind: 'codec-instance'`) and
- * target-specific IR class instances structurally satisfying
- * `PostgresEnumStorageEntry` (with `kind: 'postgres-enum'`) are the
- * two variants the SQL family ships today. The construction side also
- * accepts {@link StorageTypeInstanceInput} so callers can pass raw
- * codec triples; the constructor stamps the discriminator.
+ * Polymorphic value type for document-scoped `SqlStorage.types` entries
+ * (codec aliases / parameterised native type registrations). Postgres
+ * native enum registrations live under
+ * `storage.namespaces[namespaceId].types` instead.
  */
 export type SqlStorageTypeEntry =
   | StorageTypeInstance
-  | PostgresEnumStorageEntry
-  | StorageTypeInstanceInput;
+  | StorageTypeInstanceInput
+  | PostgresEnumStorageEntry;
 
 const DEFAULT_NAMESPACES: Readonly<Record<string, Namespace>> = Object.freeze({
-  [UNSPECIFIED_NAMESPACE_ID]: SqlUnspecifiedNamespace.instance,
+  [UNBOUND_NAMESPACE_ID]: SqlUnboundNamespace.instance,
 });
 
+export interface SqlNamespaceTablesInput {
+  readonly id: string;
+  readonly tables?: Record<string, StorageTable | StorageTableInput>;
+  readonly types?: Record<string, PostgresEnumStorageEntry>;
+}
+
 export interface SqlStorageInput<THash extends string = string> {
   readonly storageHash: StorageHashBase<THash>;
-  readonly tables: Record<string, StorageTable | StorageTableInput>;
   readonly types?: Record<string, SqlStorageTypeEntry>;
-  readonly namespaces?: Readonly<Record<string, Namespace>>;
+  readonly namespaces?: Readonly<Record<string, Namespace | SqlNamespaceTablesInput>>;
+}
+
+class SqlNamespacePayload extends NamespaceBase {
+  declare readonly kind?: string;
+  declare readonly types?: Readonly<Record<string, PostgresEnumStorageEntry>>;
+
+  readonly id: string;
+  readonly tables: Readonly<Record<string, StorageTable>>;
+
+  constructor(input: SqlNamespaceTablesInput) {
+    super();
+    this.id = input.id;
+    this.tables = Object.freeze(
+      Object.fromEntries(
+        Object.entries(input.tables ?? {}).map(([name, t]) => [
+          name,
+          t instanceof StorageTable ? t : new StorageTable(t),
+        ]),
+      ),
+    );
+    if (input.types !== undefined && Object.keys(input.types).length > 0) {
+      Object.defineProperty(this, 'types', {
+        value: Object.freeze({ ...input.types }),
+        writable: false,
+        enumerable: true,
+        configurable: false,
+      });
+    }
+    Object.defineProperty(this, 'kind', {
+      value: 'sql-namespace',
+      writable: false,
+      enumerable: false,
+      configurable: true,
+    });
+    freezeNode(this);
+  }
+}
+
+function normaliseNamespaceEntry(
+  nsKey: string,
+  ns: Namespace | SqlNamespaceTablesInput,
+): Namespace {
+  if (ns instanceof NamespaceBase) {
+    return ns;
+  }
+  const input = ns as SqlNamespaceTablesInput; // JSON namespace payloads match SqlNamespaceTablesInput before SqlNamespacePayload materialises StorageTable instances.
+  const tableCount = Object.keys(input.tables ?? {}).length;
+  const typeCount = Object.keys(input.types ?? {}).length;
+  if (nsKey === UNBOUND_NAMESPACE_ID && tableCount === 0 && typeCount === 0) {
+    return SqlUnboundNamespace.instance;
+  }
+  return new SqlNamespacePayload(input);
 }
 
 /**
  * SQL Contract IR root node for the `storage` field.
  *
  * Single concrete family-shared class — both Postgres and SQLite
- * consume this same class today. Per-target storage subclasses are
+ * consume this class today. Per-target storage subclasses are
  * introduced when each target's namespace shape earns its
  * target-specific concretion (target-specific derived fields,
  * target-specific storage extensions).
  *
  * Honours the framework `Storage` interface: every SQL IR carries a
  * `namespaces` map keyed by namespace id. The default singleton
- * (`{ [UNSPECIFIED_NAMESPACE_ID]: SqlUnspecifiedNamespace.instance }`)
+ * (`{ [UNBOUND_NAMESPACE_ID]: SqlUnboundNamespace.instance }`)
  * binds every contract authored before per-target namespace concretions
- * land; per-target namespace classes (`PostgresSchema.unspecified`,
- * `SqliteUnspecifiedDatabase.instance`) earn their slots when each
+ * land; per-target namespace classes (`PostgresSchema.unbound`,
+ * `SqliteUnboundDatabase.instance`) earn their slots when each
  * target's namespace shape lands.
  *
- * The constructor normalises nested IR-class fields (`tables`, optional
- * `types`) into class instances so downstream walks see a uniform AST.
+ * The constructor normalises optional `types` into class instances and
+ * materialises plain namespace envelope objects into `Namespace` class
+ * instances so downstream walks see a uniform AST.
  * `types` is polymorphic per Decision 18 Option B: codec-triple inputs
  * are stamped with `kind: 'codec-instance'`; class-instance kinds
  * (e.g. Postgres-enum entries satisfying `PostgresEnumStorageEntry`)
@@ -71,31 +126,42 @@ export interface SqlStorageInput<THash extends string = string> {
  * responsibility (so the family base does not import target-specific
  * subclasses).
  */
+// SQL concretions always store `StorageTable`-shaped values in `tables`.
+// `tables` is a SQL-family idiom — the framework `Namespace` contract no
+// longer mandates this field; Mongo namespaces carry `collections`
+// instead. The `__unbound__` slot uses the same narrowing as every other
+// SQL namespace; the wider `Record<string, object>` on `StorageTable` is
+// only there so emitted `contract.d.ts` table literals (which lack the
+// runtime `kind` discriminator on `StorageTable`) structurally satisfy
+// the slot without a class-instance check.
+export type SqlNamespace = Namespace & {
+  readonly tables: Readonly<Record<string, StorageTable>>;
+  readonly types?: Readonly<Record<string, PostgresEnumStorageEntry>>;
+};
+
 export class SqlStorage<THash extends string = string> extends SqlNode implements Storage {
   readonly storageHash: StorageHashBase<THash>;
-  readonly tables: Readonly<Record<string, StorageTable>>;
-  readonly namespaces: Readonly<Record<string, Namespace>>;
-  // SQL-family slot view: the two structural variants the family ships
-  // today (codec triples + Postgres-enum structural entries). Each
-  // variant extends the framework `StorageType` alphabet; the SQL
-  // narrowing keeps cross-domain layering clean — SQL-family consumers
-  // dispatch via `isStorageTypeInstance` / `isPostgresEnumStorageEntry`
-  // type guards rather than importing the target's concrete IR class
-  // (cross-domain rule: SQL may not import `target-*`).
+  readonly namespaces: Readonly<Record<string, SqlNamespace>> & {
+    readonly __unbound__: SqlNamespace;
+  };
   declare readonly types?: Readonly<Record<string, StorageTypeInstance | PostgresEnumStorageEntry>>;
 
   constructor(input: SqlStorageInput<THash>) {
     super();
     this.storageHash = input.storageHash;
-    this.tables = Object.freeze(
-      Object.fromEntries(
-        Object.entries(input.tables).map(([name, t]) => [
-          name,
-          t instanceof StorageTable ? t : new StorageTable(t),
-        ]),
-      ),
+    const inputNamespaces = input.namespaces ?? DEFAULT_NAMESPACES;
+    const normalised: Record<string, SqlNamespace> = Object.fromEntries(
+      Object.entries(inputNamespaces).map(([nsKey, ns]) => [
+        nsKey,
+        normaliseNamespaceEntry(nsKey, ns) as SqlNamespace,
+      ]),
     );
-    this.namespaces = input.namespaces ?? DEFAULT_NAMESPACES;
+    if (!normalised[UNBOUND_NAMESPACE_ID]) {
+      normalised[UNBOUND_NAMESPACE_ID] = SqlUnboundNamespace.instance as SqlNamespace;
+    }
+    this.namespaces = Object.freeze(normalised) as Readonly<Record<string, SqlNamespace>> & {
+      readonly __unbound__: SqlNamespace;
+    };
     if (input.types !== undefined) {
       this.types = Object.freeze(
         Object.fromEntries(
@@ -108,9 +174,9 @@ export class SqlStorage<THash extends string = string> extends SqlNode implement
 }
 
 /**
- * Strict polymorphic-slot dispatch for `SqlStorage.types` entries
- * (TML-2536). Every entry must carry a recognised `kind` discriminator
- * — either `'codec-instance'` (codec triple, family-shared) or
+ * Strict polymorphic-slot dispatch for `SqlStorage.types` entries.
+ * Every entry must carry a recognised `kind` discriminator — either
+ * `'codec-instance'` (codec triple, family-shared) or
  * `'postgres-enum'` (target-specific IR class). Untagged or
  * unrecognised inputs throw a diagnostic naming the entry and its
  * `kind`, so format drift surfaces loudly at the deserializer

package/src/ir/{sql-unspecified-namespace.ts → sql-unbound-namespace.ts}

@@ -1,22 +1,25 @@
 import {
   freezeNode,
   NamespaceBase,
-  UNSPECIFIED_NAMESPACE_ID,
+  UNBOUND_NAMESPACE_ID,
 } from '@prisma-next/framework-components/ir';
+import type { StorageTable } from './storage-table';
 
 /**
- * Family-layer placeholder for the SQL unspecified-namespace singleton.
+ * Family-layer placeholder for the SQL unbound-namespace singleton —
+ * the late-bound slot whose binding the target resolves at connection
+ * time rather than at authoring time.
  *
  * SQL contracts honour the framework `Storage.namespaces` invariant from
  * the moment they appear in the IR. Today `SqlStorage` is family-shared
  * (Postgres + SQLite consume the same class); a per-target namespace
- * concretion (`PostgresSchema.unspecified`, `SqliteUnspecifiedDatabase.instance`)
+ * concretion (`PostgresSchema.unbound`, `SqliteUnboundDatabase.instance`)
  * earns its existence when each target's namespace shape lands. Until
  * then the family ships a single placeholder singleton so the JSON
  * envelope and runtime walk are honest at every layer.
  *
  * The `kind` discriminator is installed as a non-enumerable own property
- * so the JSON envelope reads `{ "id": "__unspecified__" }` — symmetric
+ * so the JSON envelope reads `{ "id": "__unbound__" }` — symmetric
  * with the family-level non-enumerable `kind` on `SqlNode` and bounded
  * to the minimum data the framework `Namespace` interface promises.
  *
@@ -32,10 +35,11 @@ import {
  * fields safely, lift `freezeNode` to a leaf-class `seal()` hook each
  * leaf calls explicitly at the end of its own constructor.
  */
-export class SqlUnspecifiedNamespace extends NamespaceBase {
-  static readonly instance: SqlUnspecifiedNamespace = new SqlUnspecifiedNamespace();
+export class SqlUnboundNamespace extends NamespaceBase {
+  static readonly instance: SqlUnboundNamespace = new SqlUnboundNamespace();
 
-  readonly id = UNSPECIFIED_NAMESPACE_ID;
+  readonly id = UNBOUND_NAMESPACE_ID;
+  readonly tables: Readonly<Record<string, StorageTable>> = Object.freeze({});
   declare readonly kind?: string;
 
   private constructor() {

package/src/ir/storage-table.ts

@@ -15,7 +15,8 @@ export interface StorageTableInput {
 }
 
 /**
- * SQL Contract IR node for a single table entry in `SqlStorage.tables`.
+ * SQL Contract IR node for a single table entry in a namespace's
+ * `tables` map.
  *
  * The constructor normalises nested IR-class fields (columns, primary
  * key, uniques, indexes, foreign keys) into the appropriate class
@@ -23,10 +24,7 @@ export interface StorageTableInput {
  * the input was a JSON literal or an already-constructed class.
  *
  * The table's `name` is not on the class — tables are keyed by name in
- * the parent `SqlStorage.tables: Record<string, StorageTable>` map.
- * A future namespace-aware milestone will add a `namespaceId` field
- * when namespace-keyed storage lands; today's single-namespace shape
- * needs neither field.
+ * the parent namespace's `tables: Record<string, StorageTable>` map.
  */
 export class StorageTable extends SqlNode {
   readonly columns: Readonly<Record<string, StorageColumn>>;

package/src/types.ts

@@ -7,9 +7,9 @@ export {
   type ReferentialAction,
 } from './ir/foreign-key';
 export {
-  ForeignKeyReferences,
-  type ForeignKeyReferencesInput,
-} from './ir/foreign-key-references';
+  ForeignKeyReference,
+  type ForeignKeyReferenceInput,
+} from './ir/foreign-key-reference';
 export {
   isPostgresEnumStorageEntry,
   POSTGRES_ENUM_KIND,
@@ -19,11 +19,12 @@ export { PrimaryKey, type PrimaryKeyInput } from './ir/primary-key';
 export { Index, type IndexInput } from './ir/sql-index';
 export { SqlNode } from './ir/sql-node';
 export {
+  type SqlNamespaceTablesInput,
   SqlStorage,
   type SqlStorageInput,
   type SqlStorageTypeEntry,
 } from './ir/sql-storage';
-export { SqlUnspecifiedNamespace } from './ir/sql-unspecified-namespace';
+export { SqlUnboundNamespace } from './ir/sql-unbound-namespace';
 export { StorageColumn, type StorageColumnInput } from './ir/storage-column';
 export { StorageTable, type StorageTableInput } from './ir/storage-table';
 export {