@prisma-next/framework-components 0.13.0-dev.34 → 0.13.0-dev.36

package/dist/ir.d.mts

@@ -1,4 +1,6 @@
 import { ApplicationDomain, StorageBase, StorageNamespace } from "@prisma-next/contract/types";
+import { isPlainRecord } from "@prisma-next/contract/is-plain-record";
+import { Type } from "arktype";
 
 //#region src/ir/ir-node.d.ts
 /**
@@ -216,6 +218,27 @@ interface Storage extends IRNode {
  */
 declare function domainElementCoordinates(domain: Pick<ApplicationDomain, 'namespaces'>): Generator<EntityCoordinate>;
 //#endregion
+//#region src/ir/entity-kind.d.ts
+interface EntityKindDescriptor<Input, Node> {
+  readonly kind: string;
+  readonly schema: Type<unknown>;
+  readonly construct: (input: Input) => Node;
+}
+type AnyEntityKindDescriptor = EntityKindDescriptor<never, unknown>;
+/**
+ * Hydrates a namespace's entities from raw JSON maps into IR class instances.
+ *
+ * For each kind in `entries`: if the descriptor map has a descriptor,
+ * construct each inner-map value; otherwise freeze-and-carry (`'carry'`)
+ * or throw naming the kind and nsId (`'fail'`).
+ *
+ * The single boundary cast hands `value` to `descriptor.construct` as its
+ * `Input`. The value satisfies the kind's `Input` either by the
+ * entries-input contract at authoring time or by prior `validateStorage`
+ * validation at hydration time.
+ */
+declare function hydrateNamespaceEntities(entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>, kinds: ReadonlyMap<string, AnyEntityKindDescriptor>, onUnknown: 'carry' | 'fail', nsId?: string): Record<string, Readonly<Record<string, unknown>>>;
+//#endregion
 //#region src/ir/storage-type.d.ts
 /**
  * Framework-level alphabet for entries in a storage `types` slot.
@@ -239,5 +262,5 @@ interface StorageType extends IRNode {
   readonly kind: string;
 }
 //#endregion
-export { type EntityCoordinate, type IRNode, IRNodeBase, type Namespace, NamespaceBase, type Storage, type StorageType, UNBOUND_NAMESPACE_ID, domainElementCoordinates, elementCoordinates, entityAt, freezeNode };
+export { type AnyEntityKindDescriptor, type EntityCoordinate, type EntityKindDescriptor, type IRNode, IRNodeBase, type Namespace, NamespaceBase, type Storage, type StorageType, UNBOUND_NAMESPACE_ID, domainElementCoordinates, elementCoordinates, entityAt, freezeNode, hydrateNamespaceEntities, isPlainRecord };
 //# sourceMappingURL=ir.d.mts.map

package/dist/ir.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ir.d.mts","names":[],"sources":["../src/ir/ir-node.ts","../src/ir/namespace.ts","../src/ir/storage.ts","../src/ir/domain.ts","../src/ir/storage-type.ts"],"mappings":";;;;;;AAyCA;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;;;;;;;;;AAAwD;;;;AChCxD;;;;AAA0D;AAkC1D;;;;UDnBiB,MAAA;EAAA,SACN,IAAI;AAAA;AAAA,uBAGO,UAAA,YAAsB,MAAM;EAAA,kBAC9B,IAAI;AAAA;;;;;;;;;;iBAYR,UAAA,WAAqB,MAAA,EAAQ,IAAA,EAAM,CAAA,GAAI,CAAA;;;;AAjBvD;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;;;;;;;cChCa,oBAAA;;ADgC2C;;;;AChCxD;;;;AAA0D;AAkC1D;;;;;;;;;;;;;;;;;;;;AAE2D;AAG3D;UALiB,SAAA,SAAkB,MAAA,EAAQ,gBAAA;EAAA,SAChC,IAAA;EAAA,SACA,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA;AAAA;AAAA,uBAG/B,aAAA,SAAsB,UAAA,YAAsB,SAAA;EAAA,kBAC9C,EAAA;EAAA,kBACA,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA;EAAA,kBACjC,IAAA;AAAA;;;AD3B7B;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;AAjBA,UEpBiB,gBAAA;EAAA,SACN,KAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,SACA,UAAA;AAAA;;;AFiC6C;;;;AChCxD;;;;AAA0D;iBCazC,kBAAA,CACf,OAAA,EAAS,IAAA,CAAK,WAAA,kBACb,SAAA,CAAU,gBAAA;;;;;;;iBAuBG,QAAA,cACd,OAAA,EAAS,IAAA,CAAK,WAAA,iBACd,KAAA,EAAO,IAAA,CAAK,gBAAA,iDACX,CAAA;;;;;;;;;;;;;ADLwD;AAG3D;;;;;;;;;;;;;;;;;;;;;AAGiC;UC+ChB,OAAA,SAAgB,MAAA;EAAA,SACtB,UAAA,EAAY,QAAA,CAAS,MAAA,SAAe,SAAA;AAAA;;;;AF3E/C;;;;AACe;AAGf;iBGnCiB,wBAAA,CACf,MAAA,EAAQ,IAAA,CAAK,iBAAA,kBACZ,SAAA,CAAU,gBAAA;;;;;AH6Bb;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;UItCiB,WAAA,SAAoB,MAAM;EAAA,SAChC,IAAI;AAAA"}
+{"version":3,"file":"ir.d.mts","names":[],"sources":["../src/ir/ir-node.ts","../src/ir/namespace.ts","../src/ir/storage.ts","../src/ir/domain.ts","../src/ir/entity-kind.ts","../src/ir/storage-type.ts"],"mappings":";;;;;;;;;;AAyCA;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;;;;;;;;;AAAwD;;;;AChCxD;;;;AAA0D;AAkC1D;;UDnBiB,MAAA;EAAA,SACN,IAAI;AAAA;AAAA,uBAGO,UAAA,YAAsB,MAAM;EAAA,kBAC9B,IAAI;AAAA;;;;;;;;;;iBAYR,UAAA,WAAqB,MAAA,EAAQ,IAAA,EAAM,CAAA,GAAI,CAAA;;;;;;AAjBvD;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;;;;;cChCa,oBAAA;;;;ADgC2C;;;;AChCxD;;;;AAA0D;AAkC1D;;;;;;;;;;;;;;;;;;;;UAAiB,SAAA,SAAkB,MAAA,EAAQ,gBAAA;EAAA,SAChC,IAAA;EAAA,SACA,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA;AAAA;AAAA,uBAG/B,aAAA,SAAsB,UAAA,YAAsB,SAAA;EAAA,kBAC9C,EAAA;EAAA,kBACA,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA;EAAA,kBACjC,IAAA;AAAA;;;AD3B7B;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;;;AAjBA,UEjBiB,gBAAA;EAAA,SACN,KAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;EAAA,SACA,UAAA;AAAA;;;AF8B6C;;;;AChCxD;;;;AAA0D;iBCgBzC,kBAAA,CACf,OAAA,EAAS,IAAA,CAAK,WAAA,kBACb,SAAA,CAAU,gBAAA;;;;;;;iBAmBG,QAAA,cACd,OAAA,EAAS,IAAA,CAAK,WAAA,iBACd,KAAA,EAAO,IAAA,CAAK,gBAAA,iDACX,CAAA;;;;;;;;;;;;;ADJwD;AAG3D;;;;;;;;;;;;;;;;;;;;;AAGiC;UC8ChB,OAAA,SAAgB,MAAA;EAAA,SACtB,UAAA,EAAY,QAAA,CAAS,MAAA,SAAe,SAAA;AAAA;;;;;;AF1E/C;;;;iBG/BiB,wBAAA,CACf,MAAA,EAAQ,IAAA,CAAK,iBAAA,kBACZ,SAAA,CAAU,gBAAA;;;UCTI,oBAAA;EAAA,SACN,IAAA;EAAA,SAEA,MAAA,EAAQ,IAAA;EAAA,SACR,SAAA,GAAY,KAAA,EAAO,KAAA,KAAU,IAAA;AAAA;AAAA,KAG5B,uBAAA,GAA0B,oBAAoB;;;AJgC3C;AAGf;;;;AACwB;AAYxB;;;;iBIlCgB,wBAAA,CACd,OAAA,EAAS,QAAA,CAAS,MAAA,SAAe,QAAA,CAAS,MAAA,sBAC1C,KAAA,EAAO,WAAA,SAAoB,uBAAA,GAC3B,SAAA,oBACA,IAAA,YACC,MAAA,SAAe,QAAA,CAAS,MAAA;;;;;;;AJY3B;;;;AACe;AAGf;;;;AACwB;AAYxB;;;;UKtCiB,WAAA,SAAoB,MAAM;EAAA,SAChC,IAAI;AAAA"}

package/dist/ir.mjs

@@ -1,4 +1,5 @@
 import { blindCast } from "@prisma-next/utils/casts";
+import { isPlainRecord } from "@prisma-next/contract/is-plain-record";
 //#region src/ir/domain.ts
 /**
 * Lazy walk over every named domain entity in a {@link ApplicationDomain},
@@ -20,6 +21,33 @@ function* domainElementCoordinates(domain) {
 	}
 }
 //#endregion
+//#region src/ir/entity-kind.ts
+/**
+* Hydrates a namespace's entities from raw JSON maps into IR class instances.
+*
+* For each kind in `entries`: if the descriptor map has a descriptor,
+* construct each inner-map value; otherwise freeze-and-carry (`'carry'`)
+* or throw naming the kind and nsId (`'fail'`).
+*
+* The single boundary cast hands `value` to `descriptor.construct` as its
+* `Input`. The value satisfies the kind's `Input` either by the
+* entries-input contract at authoring time or by prior `validateStorage`
+* validation at hydration time.
+*/
+function hydrateNamespaceEntities(entries, kinds, onUnknown, nsId) {
+	const result = {};
+	for (const [kind, rawMap] of Object.entries(entries)) {
+		const descriptor = kinds.get(kind);
+		if (descriptor !== void 0) {
+			const built = {};
+			for (const [name, value] of Object.entries(rawMap)) built[name] = descriptor.construct(blindCast(value));
+			result[kind] = Object.freeze(built);
+		} else if (onUnknown === "carry") result[kind] = Object.freeze(rawMap);
+		else throw new Error(`Unknown entries key "${kind}" in namespace "${nsId ?? "?"}"; no hydration factory registered for this entity kind`);
+	}
+	return result;
+}
+//#endregion
 //#region src/ir/ir-node.ts
 var IRNodeBase = class {};
 /**
@@ -90,9 +118,6 @@ function* elementCoordinates(storage) {
 		}
 	}
 }
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
 /**
 * Looks up a single entity in a `Storage`-shaped value by its full coordinate.
 * Returns `undefined` if the namespace, entity kind, or entity name is absent.
@@ -103,13 +128,13 @@ function entityAt(storage, coord) {
 	const ns = storage.namespaces[coord.namespaceId];
 	if (ns === void 0) return void 0;
 	const entries = ns.entries;
-	if (!isRecord(entries)) return void 0;
+	if (!isPlainRecord(entries)) return void 0;
 	const kindMap = entries[coord.entityKind];
-	if (!isRecord(kindMap)) return void 0;
+	if (!isPlainRecord(kindMap)) return void 0;
 	if (!Object.hasOwn(kindMap, coord.entityName)) return void 0;
 	return blindCast(kindMap[coord.entityName]);
 }
 //#endregion
-export { IRNodeBase, NamespaceBase, UNBOUND_NAMESPACE_ID, domainElementCoordinates, elementCoordinates, entityAt, freezeNode };
+export { IRNodeBase, NamespaceBase, UNBOUND_NAMESPACE_ID, domainElementCoordinates, elementCoordinates, entityAt, freezeNode, hydrateNamespaceEntities, isPlainRecord };
 
 //# sourceMappingURL=ir.mjs.map

package/dist/ir.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ir.mjs","names":[],"sources":["../src/ir/domain.ts","../src/ir/ir-node.ts","../src/ir/namespace.ts","../src/ir/storage.ts"],"sourcesContent":["import type { ApplicationDomain } from '@prisma-next/contract/types';\nimport type { EntityCoordinate } from './storage';\n\n/**\n * Lazy walk over every named domain entity in a {@link ApplicationDomain},\n * yielded as {@link EntityCoordinate} tuples with `plane: 'domain'`.\n *\n * Same structural rules as {@link elementCoordinates} over storage: skip\n * scalar `id`; each other object-valued property is an entity-kind slot.\n */\nexport function* domainElementCoordinates(\n  domain: Pick<ApplicationDomain, 'namespaces'>,\n): Generator<EntityCoordinate> {\n  for (const [namespaceId, ns] of Object.entries(domain.namespaces)) {\n    for (const [entityKind, slot] of Object.entries(ns)) {\n      if (entityKind === 'id') continue;\n      if (slot === null || typeof slot !== 'object') continue;\n      for (const entityName of Object.keys(slot)) {\n        yield { plane: 'domain', namespaceId, entityKind, entityName };\n      }\n    }\n  }\n}\n","/**\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 = 'pack-contributed-kind' 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 { StorageNamespace } from '@prisma-next/contract/types';\nimport { type IRNode, IRNodeBase } from './ir-node';\n\n/**\n * Reserved sentinel namespace id for the late-bound storage slot —\n * the slot whose binding the target resolves at connection time\n * rather than at authoring time. Postgres uses it for `search_path`\n * late binding; SQLite uses it for the trivial singleton; Mongo uses\n * it for the connection's `db` binding.\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 === UNBOUND_NAMESPACE_ID`\n * — the singleton's overrides drop the qualifier so emitted SQL / Mongo\n * commands look unqualified.\n *\n * The double-underscore decoration marks the id as a framework-reserved\n * coordinate when it appears in a JSON envelope (cold-read-as-reserved\n * — no realistic collision with user-declared namespace names).\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 unbound-namespace singleton imports this\n * constant.\n */\nexport const UNBOUND_NAMESPACE_ID = '__unbound__' 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 `UNBOUND_NAMESPACE_ID`; emitted SQL has no qualifier.\n * - Mongo: the connection's `db` field; addressed as a database name.\n *\n * See `UNBOUND_NAMESPACE_ID` above for the sentinel id and the\n * singleton-subclass pattern that materialises it.\n *\n * The framework promises only the coordinate (`id`) — the named storage\n * entities a namespace contains are family-typed (SQL contributes\n * `table` / `type`, Mongo contributes `collection`, future families pick\n * their own native idiom under `entries`). Generic consumers walking \"all\n * named entries\" go through a family-typed namespace, not the framework\n * `Namespace`.\n *\n * Every namespace concretion (e.g. family-built SQL namespaces,\n * `MongoUnboundNamespace`, target-promoted namespaces like\n * `PostgresSchema`) carries exactly: `id` (enumerable string),\n * `entries` (frozen object holding entity-kind slot maps), and `kind`\n * (non-enumerable string discriminator set via `Object.defineProperty`).\n * Each slot map under `entries` uses a singular essence key (`table`,\n * `type`, `collection`, …) mapping entity names to IR classes. No other\n * own-enumerable data lives on a namespace; non-entity computed data lives\n * on the surrounding storage or contract IR. The framework's\n * `elementCoordinates(storage)` walk relies on this invariant to enumerate\n * entities structurally without family-specific knowledge.\n */\nexport interface Namespace extends IRNode, StorageNamespace {\n  readonly kind: string;\n  readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n}\n\nexport abstract class NamespaceBase extends IRNodeBase implements Namespace {\n  abstract readonly id: string;\n  abstract readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n  abstract override readonly kind: string;\n}\n","import type { StorageBase } from '@prisma-next/contract/types';\nimport { blindCast } from '@prisma-next/utils/casts';\nimport type { IRNode } from './ir-node';\nimport type { Namespace } from './namespace';\n\n/**\n * Canonical address for a named entity in Contract IR / Schema IR.\n *\n * `plane` is `'domain' | 'storage'`: which top-level contract plane the\n * entity lives on. Domain-side walks yield `plane: 'domain'` via\n * {@link domainElementCoordinates}; {@link elementCoordinates} over storage\n * yields `plane: 'storage'`.\n *\n * Cross-plane references obey a directional invariant: domain → storage is\n * allowed; storage → domain is forbidden. That rule is enforced by a\n * separate validator, not by constraining this coordinate shape — the\n * coordinate carries the axis the validator checks.\n *\n * Iteration order over namespace properties follows `Object.entries` order;\n * consumers that depend on ordering must sort.\n */\nexport interface EntityCoordinate {\n  readonly plane: 'domain' | 'storage';\n  readonly namespaceId: string;\n  readonly entityKind: string;\n  readonly entityName: string;\n}\n\n/**\n * Lazy walk over every named storage entity in a `Storage`-shaped\n * value, yielded as {@link EntityCoordinate} tuples with\n * `plane: 'storage'` (the parameter type binds the plane).\n *\n * Iterates each namespace's `entries` kind maps structurally. Skips\n * non-object `entries`; `id` and `kind` are not walked (`kind` is\n * non-enumerable on concretions). For every entity-kind key under\n * `entries` whose value is a non-null object, yields one coordinate per\n * entity name in that map. No family-specific kind vocabulary is required.\n */\nexport function* elementCoordinates(\n  storage: Pick<StorageBase, 'namespaces'>,\n): Generator<EntityCoordinate> {\n  for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {\n    const entries = ns.entries;\n    if (entries === null || typeof entries !== 'object') continue;\n    for (const [entityKind, kindMap] of Object.entries(entries)) {\n      if (kindMap === null || typeof kindMap !== 'object') continue;\n      for (const entityName of Object.keys(kindMap)) {\n        yield { plane: 'storage', namespaceId, entityKind, entityName };\n      }\n    }\n  }\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n  return typeof value === 'object' && value !== null;\n}\n\n/**\n * Looks up a single entity in a `Storage`-shaped value by its full coordinate.\n * Returns `undefined` if the namespace, entity kind, or entity name is absent.\n * The type parameter is a caller assertion — the walk itself is structural\n * and cannot verify the entity's shape.\n */\nexport function entityAt<T = unknown>(\n  storage: Pick<StorageBase, 'namespaces'>,\n  coord: Pick<EntityCoordinate, 'namespaceId' | 'entityKind' | 'entityName'>,\n): T | undefined {\n  const ns = storage.namespaces[coord.namespaceId];\n  if (ns === undefined) return undefined;\n  const entries = ns.entries;\n  if (!isRecord(entries)) return undefined;\n  const kindMap = entries[coord.entityKind];\n  if (!isRecord(kindMap)) return undefined;\n  if (!Object.hasOwn(kindMap, coord.entityName)) return undefined;\n  return blindCast<T | undefined, 'caller asserts the entity type at this coordinate'>(\n    kindMap[coord.entityName],\n  );\n}\n\n/**\n * Framework-level promise that every Contract IR / Schema IR carries a\n * collection of namespaces keyed by namespace id. Family storage\n * concretions (`SqlStorage`, `MongoStorage`) refine the shape with\n * family-specific fields (tables, collections, enums, …); target\n * concretions add target fields where the family vocabulary doesn't\n * reach.\n *\n * Keeping `namespaces` at the framework layer enforces that every storage\n * object — across any target — is namespace-scoped. The framework can\n * therefore walk the namespace map without knowing the family alphabet, and\n * the `(namespace.id, name)` keying that the verifier and planner depend on\n * is honest at every layer.\n *\n * Extends `IRNode` so the framework's IR-walking surfaces (verifiers,\n * serializers) can dispatch on `Storage`-typed fields through the same\n * IR-node alphabet as every other node — the structural dual already\n * holds in code (every concrete storage class extends an IR-node base);\n * the interface promotion makes the typing honest.\n *\n * **Persisted envelope shape is target-owned, not framework-promised.**\n * Whether the `namespaces` map appears in the on-disk JSON envelope is\n * a per-target decision made by `ContractSerializer.serializeContract`.\n * Some targets emit a JSON-clean namespace shape that round-trips\n * through `JSON.stringify` cleanly (SQL today via the family-layer\n * identity serializer); others ship runtime-only fields on their\n * namespace concretions and override `serializeContract` to strip\n * them (Mongo). Future open (F16): extend the per-target\n * `ContractSerializer` integration-test surface with an explicit\n * envelope-shape assertion for each target, so the strip-vs-pass-through\n * choice is locked at test time rather than implied by the override\n * presence/absence. Earned by PR2's per-target namespace lift, when\n * `PostgresSchema` / `SqliteUnboundDatabase` start carrying\n * target-specific fields.\n */\nexport interface Storage extends IRNode {\n  readonly namespaces: Readonly<Record<string, Namespace>>;\n}\n"],"mappings":";;;;;;;;;AAUA,UAAiB,yBACf,QAC6B;CAC7B,KAAK,MAAM,CAAC,aAAa,OAAO,OAAO,QAAQ,OAAO,UAAU,GAC9D,KAAK,MAAM,CAAC,YAAY,SAAS,OAAO,QAAQ,EAAE,GAAG;EACnD,IAAI,eAAe,MAAM;EACzB,IAAI,SAAS,QAAQ,OAAO,SAAS,UAAU;EAC/C,KAAK,MAAM,cAAc,OAAO,KAAK,IAAI,GACvC,MAAM;GAAE,OAAO;GAAU;GAAa;GAAY;EAAW;CAEjE;AAEJ;;;ACuBA,IAAsB,aAAtB,MAAmD,CAEnD;;;;;;;;;;AAWA,SAAgB,WAA6B,MAAY;CACvD,OAAO,OAAO,IAAI;CAClB,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;ACnCA,MAAa,uBAAuB;AAuCpC,IAAsB,gBAAtB,cAA4C,WAAgC,CAI5E;;;;;;;;;;;;;;AC9BA,UAAiB,mBACf,SAC6B;CAC7B,KAAK,MAAM,CAAC,aAAa,OAAO,OAAO,QAAQ,QAAQ,UAAU,GAAG;EAClE,MAAM,UAAU,GAAG;EACnB,IAAI,YAAY,QAAQ,OAAO,YAAY,UAAU;EACrD,KAAK,MAAM,CAAC,YAAY,YAAY,OAAO,QAAQ,OAAO,GAAG;GAC3D,IAAI,YAAY,QAAQ,OAAO,YAAY,UAAU;GACrD,KAAK,MAAM,cAAc,OAAO,KAAK,OAAO,GAC1C,MAAM;IAAE,OAAO;IAAW;IAAa;IAAY;GAAW;EAElE;CACF;AACF;AAEA,SAAS,SAAS,OAA4D;CAC5E,OAAO,OAAO,UAAU,YAAY,UAAU;AAChD;;;;;;;AAQA,SAAgB,SACd,SACA,OACe;CACf,MAAM,KAAK,QAAQ,WAAW,MAAM;CACpC,IAAI,OAAO,KAAA,GAAW,OAAO,KAAA;CAC7B,MAAM,UAAU,GAAG;CACnB,IAAI,CAAC,SAAS,OAAO,GAAG,OAAO,KAAA;CAC/B,MAAM,UAAU,QAAQ,MAAM;CAC9B,IAAI,CAAC,SAAS,OAAO,GAAG,OAAO,KAAA;CAC/B,IAAI,CAAC,OAAO,OAAO,SAAS,MAAM,UAAU,GAAG,OAAO,KAAA;CACtD,OAAO,UACL,QAAQ,MAAM,WAChB;AACF"}
+{"version":3,"file":"ir.mjs","names":[],"sources":["../src/ir/domain.ts","../src/ir/entity-kind.ts","../src/ir/ir-node.ts","../src/ir/namespace.ts","../src/ir/storage.ts"],"sourcesContent":["import type { ApplicationDomain } from '@prisma-next/contract/types';\nimport type { EntityCoordinate } from './storage';\n\n/**\n * Lazy walk over every named domain entity in a {@link ApplicationDomain},\n * yielded as {@link EntityCoordinate} tuples with `plane: 'domain'`.\n *\n * Same structural rules as {@link elementCoordinates} over storage: skip\n * scalar `id`; each other object-valued property is an entity-kind slot.\n */\nexport function* domainElementCoordinates(\n  domain: Pick<ApplicationDomain, 'namespaces'>,\n): Generator<EntityCoordinate> {\n  for (const [namespaceId, ns] of Object.entries(domain.namespaces)) {\n    for (const [entityKind, slot] of Object.entries(ns)) {\n      if (entityKind === 'id') continue;\n      if (slot === null || typeof slot !== 'object') continue;\n      for (const entityName of Object.keys(slot)) {\n        yield { plane: 'domain', namespaceId, entityKind, entityName };\n      }\n    }\n  }\n}\n","import { blindCast } from '@prisma-next/utils/casts';\nimport type { Type } from 'arktype';\n\nexport interface EntityKindDescriptor<Input, Node> {\n  readonly kind: string;\n  // Type<unknown>, not Type<Input>: AnyEntityKindDescriptor widens Input to never, which would force an unusable Type<never>; concrete descriptors still carry their real schema.\n  readonly schema: Type<unknown>;\n  readonly construct: (input: Input) => Node;\n}\n\nexport type AnyEntityKindDescriptor = EntityKindDescriptor<never, unknown>;\n\n/**\n * Hydrates a namespace's entities from raw JSON maps into IR class instances.\n *\n * For each kind in `entries`: if the descriptor map has a descriptor,\n * construct each inner-map value; otherwise freeze-and-carry (`'carry'`)\n * or throw naming the kind and nsId (`'fail'`).\n *\n * The single boundary cast hands `value` to `descriptor.construct` as its\n * `Input`. The value satisfies the kind's `Input` either by the\n * entries-input contract at authoring time or by prior `validateStorage`\n * validation at hydration time.\n */\nexport function hydrateNamespaceEntities(\n  entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>,\n  kinds: ReadonlyMap<string, AnyEntityKindDescriptor>,\n  onUnknown: 'carry' | 'fail',\n  nsId?: string,\n): Record<string, Readonly<Record<string, unknown>>> {\n  const result: Record<string, Readonly<Record<string, unknown>>> = {};\n  for (const [kind, rawMap] of Object.entries(entries)) {\n    const descriptor = kinds.get(kind);\n    if (descriptor !== undefined) {\n      const built: Record<string, unknown> = {};\n      for (const [name, value] of Object.entries(rawMap)) {\n        built[name] = descriptor.construct(\n          blindCast<\n            never,\n            \"value is this kind's descriptor Input: when authoring, the typed entries-input contract produces it; when hydrating, it was validated against descriptor.schema before this loop. The never target is AnyEntityKindDescriptor's erased Input parameter.\"\n          >(value),\n        );\n      }\n      result[kind] = Object.freeze(built);\n    } else if (onUnknown === 'carry') {\n      result[kind] = Object.freeze(rawMap);\n    } else {\n      throw new Error(\n        `Unknown entries key \"${kind}\" in namespace \"${nsId ?? '?'}\"; no hydration factory registered for this entity kind`,\n      );\n    }\n  }\n  return result;\n}\n","/**\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 = 'pack-contributed-kind' 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 { StorageNamespace } from '@prisma-next/contract/types';\nimport { type IRNode, IRNodeBase } from './ir-node';\n\n/**\n * Reserved sentinel namespace id for the late-bound storage slot —\n * the slot whose binding the target resolves at connection time\n * rather than at authoring time. Postgres uses it for `search_path`\n * late binding; SQLite uses it for the trivial singleton; Mongo uses\n * it for the connection's `db` binding.\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 === UNBOUND_NAMESPACE_ID`\n * — the singleton's overrides drop the qualifier so emitted SQL / Mongo\n * commands look unqualified.\n *\n * The double-underscore decoration marks the id as a framework-reserved\n * coordinate when it appears in a JSON envelope (cold-read-as-reserved\n * — no realistic collision with user-declared namespace names).\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 unbound-namespace singleton imports this\n * constant.\n */\nexport const UNBOUND_NAMESPACE_ID = '__unbound__' 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 `UNBOUND_NAMESPACE_ID`; emitted SQL has no qualifier.\n * - Mongo: the connection's `db` field; addressed as a database name.\n *\n * See `UNBOUND_NAMESPACE_ID` above for the sentinel id and the\n * singleton-subclass pattern that materialises it.\n *\n * The framework promises only the coordinate (`id`) — the named storage\n * entities a namespace contains are family-typed (SQL contributes\n * `table` / `type`, Mongo contributes `collection`, future families pick\n * their own native idiom under `entries`). Generic consumers walking \"all\n * named entries\" go through a family-typed namespace, not the framework\n * `Namespace`.\n *\n * Every namespace concretion (e.g. family-built SQL namespaces,\n * `MongoUnboundNamespace`, target-promoted namespaces like\n * `PostgresSchema`) carries exactly: `id` (enumerable string),\n * `entries` (frozen object holding entity-kind slot maps), and `kind`\n * (non-enumerable string discriminator set via `Object.defineProperty`).\n * Each slot map under `entries` uses a singular essence key (`table`,\n * `type`, `collection`, …) mapping entity names to IR classes. No other\n * own-enumerable data lives on a namespace; non-entity computed data lives\n * on the surrounding storage or contract IR. The framework's\n * `elementCoordinates(storage)` walk relies on this invariant to enumerate\n * entities structurally without family-specific knowledge.\n */\nexport interface Namespace extends IRNode, StorageNamespace {\n  readonly kind: string;\n  readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n}\n\nexport abstract class NamespaceBase extends IRNodeBase implements Namespace {\n  abstract readonly id: string;\n  abstract readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;\n  abstract override readonly kind: string;\n}\n","import { isPlainRecord } from '@prisma-next/contract/is-plain-record';\nimport type { StorageBase } from '@prisma-next/contract/types';\nimport { blindCast } from '@prisma-next/utils/casts';\nimport type { IRNode } from './ir-node';\nimport type { Namespace } from './namespace';\n\nexport { isPlainRecord };\n\n/**\n * Canonical address for a named entity in Contract IR / Schema IR.\n *\n * `plane` is `'domain' | 'storage'`: which top-level contract plane the\n * entity lives on. Domain-side walks yield `plane: 'domain'` via\n * {@link domainElementCoordinates}; {@link elementCoordinates} over storage\n * yields `plane: 'storage'`.\n *\n * Cross-plane references obey a directional invariant: domain → storage is\n * allowed; storage → domain is forbidden. That rule is enforced by a\n * separate validator, not by constraining this coordinate shape — the\n * coordinate carries the axis the validator checks.\n *\n * Iteration order over namespace properties follows `Object.entries` order;\n * consumers that depend on ordering must sort.\n */\nexport interface EntityCoordinate {\n  readonly plane: 'domain' | 'storage';\n  readonly namespaceId: string;\n  readonly entityKind: string;\n  readonly entityName: string;\n}\n\n/**\n * Lazy walk over every named storage entity in a `Storage`-shaped\n * value, yielded as {@link EntityCoordinate} tuples with\n * `plane: 'storage'` (the parameter type binds the plane).\n *\n * Iterates each namespace's `entries` kind maps structurally. Skips\n * non-object `entries`; `id` and `kind` are not walked (`kind` is\n * non-enumerable on concretions). For every entity-kind key under\n * `entries` whose value is a non-null object, yields one coordinate per\n * entity name in that map. No family-specific kind vocabulary is required.\n */\nexport function* elementCoordinates(\n  storage: Pick<StorageBase, 'namespaces'>,\n): Generator<EntityCoordinate> {\n  for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {\n    const entries = ns.entries;\n    if (entries === null || typeof entries !== 'object') continue;\n    for (const [entityKind, kindMap] of Object.entries(entries)) {\n      if (kindMap === null || typeof kindMap !== 'object') continue;\n      for (const entityName of Object.keys(kindMap)) {\n        yield { plane: 'storage', namespaceId, entityKind, entityName };\n      }\n    }\n  }\n}\n\n/**\n * Looks up a single entity in a `Storage`-shaped value by its full coordinate.\n * Returns `undefined` if the namespace, entity kind, or entity name is absent.\n * The type parameter is a caller assertion — the walk itself is structural\n * and cannot verify the entity's shape.\n */\nexport function entityAt<T = unknown>(\n  storage: Pick<StorageBase, 'namespaces'>,\n  coord: Pick<EntityCoordinate, 'namespaceId' | 'entityKind' | 'entityName'>,\n): T | undefined {\n  const ns = storage.namespaces[coord.namespaceId];\n  if (ns === undefined) return undefined;\n  const entries = ns.entries;\n  if (!isPlainRecord(entries)) return undefined;\n  const kindMap = entries[coord.entityKind];\n  if (!isPlainRecord(kindMap)) return undefined;\n  if (!Object.hasOwn(kindMap, coord.entityName)) return undefined;\n  return blindCast<T | undefined, 'caller asserts the entity type at this coordinate'>(\n    kindMap[coord.entityName],\n  );\n}\n\n/**\n * Framework-level promise that every Contract IR / Schema IR carries a\n * collection of namespaces keyed by namespace id. Family storage\n * concretions (`SqlStorage`, `MongoStorage`) refine the shape with\n * family-specific fields (tables, collections, enums, …); target\n * concretions add target fields where the family vocabulary doesn't\n * reach.\n *\n * Keeping `namespaces` at the framework layer enforces that every storage\n * object — across any target — is namespace-scoped. The framework can\n * therefore walk the namespace map without knowing the family alphabet, and\n * the `(namespace.id, name)` keying that the verifier and planner depend on\n * is honest at every layer.\n *\n * Extends `IRNode` so the framework's IR-walking surfaces (verifiers,\n * serializers) can dispatch on `Storage`-typed fields through the same\n * IR-node alphabet as every other node — the structural dual already\n * holds in code (every concrete storage class extends an IR-node base);\n * the interface promotion makes the typing honest.\n *\n * **Persisted envelope shape is target-owned, not framework-promised.**\n * Whether the `namespaces` map appears in the on-disk JSON envelope is\n * a per-target decision made by `ContractSerializer.serializeContract`.\n * Some targets emit a JSON-clean namespace shape that round-trips\n * through `JSON.stringify` cleanly (SQL today via the family-layer\n * identity serializer); others ship runtime-only fields on their\n * namespace concretions and override `serializeContract` to strip\n * them (Mongo). Future open (F16): extend the per-target\n * `ContractSerializer` integration-test surface with an explicit\n * envelope-shape assertion for each target, so the strip-vs-pass-through\n * choice is locked at test time rather than implied by the override\n * presence/absence. Earned by PR2's per-target namespace lift, when\n * `PostgresSchema` / `SqliteUnboundDatabase` start carrying\n * target-specific fields.\n */\nexport interface Storage extends IRNode {\n  readonly namespaces: Readonly<Record<string, Namespace>>;\n}\n"],"mappings":";;;;;;;;;;AAUA,UAAiB,yBACf,QAC6B;CAC7B,KAAK,MAAM,CAAC,aAAa,OAAO,OAAO,QAAQ,OAAO,UAAU,GAC9D,KAAK,MAAM,CAAC,YAAY,SAAS,OAAO,QAAQ,EAAE,GAAG;EACnD,IAAI,eAAe,MAAM;EACzB,IAAI,SAAS,QAAQ,OAAO,SAAS,UAAU;EAC/C,KAAK,MAAM,cAAc,OAAO,KAAK,IAAI,GACvC,MAAM;GAAE,OAAO;GAAU;GAAa;GAAY;EAAW;CAEjE;AAEJ;;;;;;;;;;;;;;;ACEA,SAAgB,yBACd,SACA,OACA,WACA,MACmD;CACnD,MAAM,SAA4D,CAAC;CACnE,KAAK,MAAM,CAAC,MAAM,WAAW,OAAO,QAAQ,OAAO,GAAG;EACpD,MAAM,aAAa,MAAM,IAAI,IAAI;EACjC,IAAI,eAAe,KAAA,GAAW;GAC5B,MAAM,QAAiC,CAAC;GACxC,KAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,MAAM,GAC/C,MAAM,QAAQ,WAAW,UACvB,UAGE,KAAK,CACT;GAEF,OAAO,QAAQ,OAAO,OAAO,KAAK;EACpC,OAAO,IAAI,cAAc,SACvB,OAAO,QAAQ,OAAO,OAAO,MAAM;OAEnC,MAAM,IAAI,MACR,wBAAwB,KAAK,kBAAkB,QAAQ,IAAI,wDAC7D;CAEJ;CACA,OAAO;AACT;;;ACRA,IAAsB,aAAtB,MAAmD,CAEnD;;;;;;;;;;AAWA,SAAgB,WAA6B,MAAY;CACvD,OAAO,OAAO,IAAI;CAClB,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;ACnCA,MAAa,uBAAuB;AAuCpC,IAAsB,gBAAtB,cAA4C,WAAgC,CAI5E;;;;;;;;;;;;;;AC3BA,UAAiB,mBACf,SAC6B;CAC7B,KAAK,MAAM,CAAC,aAAa,OAAO,OAAO,QAAQ,QAAQ,UAAU,GAAG;EAClE,MAAM,UAAU,GAAG;EACnB,IAAI,YAAY,QAAQ,OAAO,YAAY,UAAU;EACrD,KAAK,MAAM,CAAC,YAAY,YAAY,OAAO,QAAQ,OAAO,GAAG;GAC3D,IAAI,YAAY,QAAQ,OAAO,YAAY,UAAU;GACrD,KAAK,MAAM,cAAc,OAAO,KAAK,OAAO,GAC1C,MAAM;IAAE,OAAO;IAAW;IAAa;IAAY;GAAW;EAElE;CACF;AACF;;;;;;;AAQA,SAAgB,SACd,SACA,OACe;CACf,MAAM,KAAK,QAAQ,WAAW,MAAM;CACpC,IAAI,OAAO,KAAA,GAAW,OAAO,KAAA;CAC7B,MAAM,UAAU,GAAG;CACnB,IAAI,CAAC,cAAc,OAAO,GAAG,OAAO,KAAA;CACpC,MAAM,UAAU,QAAQ,MAAM;CAC9B,IAAI,CAAC,cAAc,OAAO,GAAG,OAAO,KAAA;CACpC,IAAI,CAAC,OAAO,OAAO,SAAS,MAAM,UAAU,GAAG,OAAO,KAAA;CACtD,OAAO,UACL,QAAQ,MAAM,WAChB;AACF"}

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@prisma-next/framework-components",
-  "version": "0.13.0-dev.34",
+  "version": "0.13.0-dev.36",
   "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.13.0-dev.34",
-    "@prisma-next/operations": "0.13.0-dev.34",
-    "@prisma-next/ts-render": "0.13.0-dev.34",
-    "@prisma-next/utils": "0.13.0-dev.34",
+    "@prisma-next/contract": "0.13.0-dev.36",
+    "@prisma-next/operations": "0.13.0-dev.36",
+    "@prisma-next/ts-render": "0.13.0-dev.36",
+    "@prisma-next/utils": "0.13.0-dev.36",
     "@standard-schema/spec": "^1.1.0",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.13.0-dev.34",
-    "@prisma-next/tsdown": "0.13.0-dev.34",
+    "@prisma-next/tsconfig": "0.13.0-dev.36",
+    "@prisma-next/tsdown": "0.13.0-dev.36",
     "tsdown": "0.22.1",
     "typescript": "5.9.3",
     "vitest": "4.1.8"

package/src/exports/ir.ts

@@ -1,8 +1,10 @@
 export { domainElementCoordinates } from '../ir/domain';
+export type { AnyEntityKindDescriptor, EntityKindDescriptor } from '../ir/entity-kind';
+export { hydrateNamespaceEntities } from '../ir/entity-kind';
 export type { IRNode } from '../ir/ir-node';
 export { freezeNode, IRNodeBase } from '../ir/ir-node';
 export type { Namespace } from '../ir/namespace';
 export { NamespaceBase, UNBOUND_NAMESPACE_ID } from '../ir/namespace';
 export type { EntityCoordinate, Storage } from '../ir/storage';
-export { elementCoordinates, entityAt } from '../ir/storage';
+export { elementCoordinates, entityAt, isPlainRecord } from '../ir/storage';
 export type { StorageType } from '../ir/storage-type';

package/src/ir/entity-kind.ts

@@ -0,0 +1,54 @@
+import { blindCast } from '@prisma-next/utils/casts';
+import type { Type } from 'arktype';
+
+export interface EntityKindDescriptor<Input, Node> {
+  readonly kind: string;
+  // Type<unknown>, not Type<Input>: AnyEntityKindDescriptor widens Input to never, which would force an unusable Type<never>; concrete descriptors still carry their real schema.
+  readonly schema: Type<unknown>;
+  readonly construct: (input: Input) => Node;
+}
+
+export type AnyEntityKindDescriptor = EntityKindDescriptor<never, unknown>;
+
+/**
+ * Hydrates a namespace's entities from raw JSON maps into IR class instances.
+ *
+ * For each kind in `entries`: if the descriptor map has a descriptor,
+ * construct each inner-map value; otherwise freeze-and-carry (`'carry'`)
+ * or throw naming the kind and nsId (`'fail'`).
+ *
+ * The single boundary cast hands `value` to `descriptor.construct` as its
+ * `Input`. The value satisfies the kind's `Input` either by the
+ * entries-input contract at authoring time or by prior `validateStorage`
+ * validation at hydration time.
+ */
+export function hydrateNamespaceEntities(
+  entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
+  kinds: ReadonlyMap<string, AnyEntityKindDescriptor>,
+  onUnknown: 'carry' | 'fail',
+  nsId?: string,
+): Record<string, Readonly<Record<string, unknown>>> {
+  const result: Record<string, Readonly<Record<string, unknown>>> = {};
+  for (const [kind, rawMap] of Object.entries(entries)) {
+    const descriptor = kinds.get(kind);
+    if (descriptor !== undefined) {
+      const built: Record<string, unknown> = {};
+      for (const [name, value] of Object.entries(rawMap)) {
+        built[name] = descriptor.construct(
+          blindCast<
+            never,
+            "value is this kind's descriptor Input: when authoring, the typed entries-input contract produces it; when hydrating, it was validated against descriptor.schema before this loop. The never target is AnyEntityKindDescriptor's erased Input parameter."
+          >(value),
+        );
+      }
+      result[kind] = Object.freeze(built);
+    } else if (onUnknown === 'carry') {
+      result[kind] = Object.freeze(rawMap);
+    } else {
+      throw new Error(
+        `Unknown entries key "${kind}" in namespace "${nsId ?? '?'}"; no hydration factory registered for this entity kind`,
+      );
+    }
+  }
+  return result;
+}

package/src/ir/storage.ts

@@ -1,8 +1,11 @@
+import { isPlainRecord } from '@prisma-next/contract/is-plain-record';
 import type { StorageBase } from '@prisma-next/contract/types';
 import { blindCast } from '@prisma-next/utils/casts';
 import type { IRNode } from './ir-node';
 import type { Namespace } from './namespace';
 
+export { isPlainRecord };
+
 /**
  * Canonical address for a named entity in Contract IR / Schema IR.
  *
@@ -52,10 +55,6 @@ export function* elementCoordinates(
   }
 }
 
-function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
-  return typeof value === 'object' && value !== null;
-}
-
 /**
  * Looks up a single entity in a `Storage`-shaped value by its full coordinate.
  * Returns `undefined` if the namespace, entity kind, or entity name is absent.
@@ -69,9 +68,9 @@ export function entityAt<T = unknown>(
   const ns = storage.namespaces[coord.namespaceId];
   if (ns === undefined) return undefined;
   const entries = ns.entries;
-  if (!isRecord(entries)) return undefined;
+  if (!isPlainRecord(entries)) return undefined;
   const kindMap = entries[coord.entityKind];
-  if (!isRecord(kindMap)) return undefined;
+  if (!isPlainRecord(kindMap)) return undefined;
   if (!Object.hasOwn(kindMap, coord.entityName)) return undefined;
   return blindCast<T | undefined, 'caller asserts the entity type at this coordinate'>(
     kindMap[coord.entityName],