@prisma-next/family-sql 0.11.0-dev.71 → 0.11.0-dev.73

package/dist/ir.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ir.d.mts","names":[],"sources":["../src/core/ir/sql-contract-serializer-base.ts","../src/core/ir/sql-contract-serializer.ts","../src/core/ir/sql-schema-verifier-base.ts"],"mappings":";;;;;;;;;KAwCY,yBAAA,IAA6B,KAAA,cAAmB,mBAAmB;;;AAA/E;;;;AAA+E;AA0B/E;;;;;;;;;;;;;;;;;uBAAsB,yBAAA,mBAA4C,QAAA,CAAS,UAAA,cAC9D,kBAAA,CAAmB,SAAA;EAAA,iBAKX,kBAAA;EAAA,iBAHF,cAAA;cAGE,kBAAA,GAAoB,WAAA,SAAoB,yBAAA,GACzD,kBAAA,GAAqB,WAAA,SAAoB,IAAA;EAW3C,mBAAA,WAA8B,SAAA,GAAY,SAAA,CAAA,CAAW,IAAA,YAAgB,CAAA;EAMrE,iBAAA,CAAkB,QAAA,EAAU,SAAA,GAAY,UAAA;EAIxC,mBAAA,EAJkD,gCAAA,CAI/B,sBAAA;EAEnB,WAAA,EAFmB,gCAAA,CAER,WAAA;EAAA,UAED,yBAAA,CAA0B,IAAA,YAAgB,QAAA,CAAS,UAAA;EAAA,UAOnD,iBAAA,CAAkB,SAAA,EAAW,QAAA,CAAS,UAAA,IAAc,QAAA,CAAS,UAAA;EAAA,UA0C7D,sBAAA,CACR,UAAA,EAAY,QAAA,CAAS,MAAA,SAAe,SAAA,GAAY,MAAA,sBAC/C,QAAA,CAAS,MAAA,SAAe,SAAA;EAAA,UAcjB,wBAAA,CACR,IAAA,UACA,GAAA,EAAK,SAAA,GAAY,MAAA,oBAChB,SAAA,GAAY,uBAAA;EAAA,UAsEL,uBAAA,CAAwB,KAAA,EAAO,mBAAA,GAAsB,mBAAA;EAAA,UAerD,uBAAA,CAAwB,QAAA,EAAU,QAAA,CAAS,UAAA,IAAc,SAAA;AAAA;;;;;;;;;AAnNrE;;;cC3Ba,qBAAA,SAA8B,yBAAA,CAA0B,QAAA,CAAS,UAAA;;;;;;;;;;;;;AD2B9E;;;;AAA+E;AA0B/E;;;;;;;uBEvCsB,qBAAA,gCACT,cAAA,CAAe,SAAA,EAAW,OAAA;EAErC,YAAA,CAAa,OAAA,EAAS,mBAAA,CAAoB,SAAA,EAAW,OAAA,IAAW,kBAAA;EF2CzC;;;;;;EAAA,mBE9BJ,qBAAA,CACjB,OAAA,EAAS,mBAAA,CAAoB,SAAA,EAAW,OAAA,aAC9B,WAAA;EFiDO;;;;;EAAA,mBE1CA,sBAAA,CACjB,OAAA,EAAS,mBAAA,CAAoB,SAAA,EAAW,OAAA,aAC9B,WAAA;AAAA"}
+{"version":3,"file":"ir.d.mts","names":[],"sources":["../src/core/ir/sql-contract-serializer-base.ts","../src/core/ir/sql-contract-serializer.ts","../src/core/ir/sql-schema-verifier-base.ts"],"mappings":";;;;;;;;;KAwCY,yBAAA,IAA6B,KAAA,cAAmB,mBAAmB;;;AAA/E;;;;AAA+E;AA0B/E;;;;;;;;;;;;;;;;;uBAAsB,yBAAA,mBAA4C,QAAA,CAAS,UAAA,cAC9D,kBAAA,CAAmB,SAAA;EAAA,iBAKX,kBAAA;EAAA,iBAHF,cAAA;cAGE,kBAAA,GAAoB,WAAA,SAAoB,yBAAA,GACzD,kBAAA,GAAqB,WAAA,SAAoB,IAAA;EAW3C,mBAAA,WAA8B,SAAA,GAAY,SAAA,CAAA,CAAW,IAAA,YAAgB,CAAA;EAMrE,iBAAA,CAAkB,QAAA,EAAU,SAAA,GAAY,UAAA;EAIxC,mBAAA,EAJkD,gCAAA,CAI/B,sBAAA;EAEnB,WAAA,EAFmB,gCAAA,CAER,WAAA;EAAA,UAED,yBAAA,CAA0B,IAAA,YAAgB,QAAA,CAAS,UAAA;EAAA,UAOnD,iBAAA,CAAkB,SAAA,EAAW,QAAA,CAAS,UAAA,IAAc,QAAA,CAAS,UAAA;EAAA,UA6C7D,sBAAA,CACR,UAAA,EAAY,QAAA,CAAS,MAAA,SAAe,SAAA,GAAY,MAAA,sBAC/C,QAAA,CAAS,MAAA,SAAe,SAAA;EAAA,UAcjB,wBAAA,CACR,IAAA,UACA,GAAA,EAAK,SAAA,GAAY,MAAA,oBAChB,SAAA,GAAY,uBAAA;EAAA,UAsEL,uBAAA,CAAwB,KAAA,EAAO,mBAAA,GAAsB,mBAAA;EAAA,UAerD,uBAAA,CAAwB,QAAA,EAAU,QAAA,CAAS,UAAA,IAAc,SAAA;AAAA;;;;;;;;;AAtNrE;;;cC3Ba,qBAAA,SAA8B,yBAAA,CAA0B,QAAA,CAAS,UAAA;;;;;;;;;;;;;AD2B9E;;;;AAA+E;AA0B/E;;;;;;;uBEvCsB,qBAAA,gCACT,cAAA,CAAe,SAAA,EAAW,OAAA;EAErC,YAAA,CAAa,OAAA,EAAS,mBAAA,CAAoB,SAAA,EAAW,OAAA,IAAW,kBAAA;EF2CzC;;;;;;EAAA,mBE9BJ,qBAAA,CACjB,OAAA,EAAS,mBAAA,CAAoB,SAAA,EAAW,OAAA,aAC9B,WAAA;EFiDO;;;;;EAAA,mBE1CA,sBAAA,CACjB,OAAA,EAAS,mBAAA,CAAoB,SAAA,EAAW,OAAA,aAC9B,WAAA;AAAA"}

package/dist/sql-contract-serializer-8axtK4lg.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sql-contract-serializer-8axtK4lg.mjs","names":[],"sources":["../src/core/ir/sql-contract-serializer-base.ts","../src/core/ir/sql-contract-serializer.ts"],"sourcesContent":["import { ContractValidationError } from '@prisma-next/contract/contract-validation-error';\nimport type { Contract } from '@prisma-next/contract/types';\nimport type { ContractSerializer } from '@prisma-next/framework-components/control';\nimport {\n  type Namespace,\n  NamespaceBase,\n  UNBOUND_NAMESPACE_ID,\n} from '@prisma-next/framework-components/ir';\nimport { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/canonicalization-hooks';\nimport {\n  buildSqlNamespace,\n  type SqlNamespaceTablesInput,\n  SqlStorage,\n  type SqlStorageInput,\n  type SqlStorageTypeEntry,\n  SqlUnboundNamespace,\n  StorageTable,\n  type StorageTableInput,\n} from '@prisma-next/sql-contract/types';\nimport {\n  createSqlContractSchema,\n  validateSqlContractFully,\n} from '@prisma-next/sql-contract/validators';\nimport { blindCast } from '@prisma-next/utils/casts';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport type { JsonObject } from '@prisma-next/utils/json';\nimport { type Type, type } from 'arktype';\n\nconst NamespaceRawSchema = type({\n  id: 'string',\n  'kind?': 'string',\n  // Undeclared keys (`tables`, `enum`, and any pack-contributed slot maps)\n  // intentionally pass through; the slot loop below iterates them by name.\n  '+': 'ignore',\n});\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nexport type SqlEntityHydrationFactory = (entry: unknown) => SqlStorageTypeEntry;\n\n/**\n * SQL family `ContractSerializer` abstract base. Carries the SQL-shared\n * deserialization pipeline:\n *\n * 1. `parseSqlContractStructure` validates the on-disk JSON envelope\n *    against the SQL contract arktype schema (`validateSqlContractFully`)\n *    and returns the validated flat-data shape.\n * 2. `hydrateSqlStorage` walks the validated `storage` subtree and\n *    constructs the family-shared SQL Contract IR class hierarchy\n *    (`SqlStorage` -> `StorageTable` -> `StorageColumn` / `PrimaryKey`\n *    / …). The rest of the contract envelope is JSON-clean primitive\n *    data and passes through unchanged.\n * 3. `constructTargetContract` is the target-specific extension hook;\n *    defaults to identity. Targets that need to attach target-only\n *    fields (e.g. target-specific derived storage fields) override it.\n *\n * Default `serializeContract` is identity over the contract — concrete\n * SQL targets ship JSON-clean class instances, so the contract value\n * can be stringified directly. The non-enumerable family-level `kind`\n * discriminator on `SqlNode` instances stays out of the persisted\n * envelope automatically. Targets that need to canonicalize on the way\n * out (key ordering, dropping computed-only fields) override\n * `serializeContract` directly.\n */\nexport abstract class SqlContractSerializerBase<TContract extends Contract<SqlStorage>>\n  implements ContractSerializer<TContract>\n{\n  private readonly contractSchema: Type<unknown> | undefined;\n\n  constructor(\n    private readonly entityTypeRegistry: ReadonlyMap<string, SqlEntityHydrationFactory> = new Map(),\n    validatorFragments?: ReadonlyMap<string, Type<unknown>>,\n  ) {\n    // Only build a fragments-aware contract schema when pack contributions\n    // exist. The cached module-level default in `validators.ts` covers the\n    // no-contributions case and avoids per-instance schema compilation.\n    this.contractSchema =\n      validatorFragments !== undefined && validatorFragments.size > 0\n        ? createSqlContractSchema(validatorFragments)\n        : undefined;\n  }\n\n  deserializeContract<T extends TContract = TContract>(json: unknown): T {\n    const validated = this.parseSqlContractStructure(json);\n    const hydrated = this.hydrateSqlStorage(validated);\n    return this.constructTargetContract(hydrated) as T;\n  }\n\n  serializeContract(contract: TContract): JsonObject {\n    return contract as unknown as JsonObject;\n  }\n\n  shouldPreserveEmpty = sqlContractCanonicalizationHooks.shouldPreserveEmpty;\n\n  sortStorage = sqlContractCanonicalizationHooks.sortStorage;\n\n  protected parseSqlContractStructure(json: unknown): Contract<SqlStorage> {\n    return validateSqlContractFully<Contract<SqlStorage>>(\n      json,\n      this.contractSchema !== undefined ? { contractSchema: this.contractSchema } : undefined,\n    );\n  }\n\n  protected hydrateSqlStorage(validated: Contract<SqlStorage>): Contract<SqlStorage> {\n    const types = validated.storage.types;\n    const hydratedTypes =\n      types !== undefined\n        ? Object.fromEntries(\n            Object.entries(types).map(([name, entry]) => [\n              name,\n              this.hydrateStorageTypeEntry(entry),\n            ]),\n          )\n        : undefined;\n\n    const rawNamespaces = validated.storage.namespaces;\n    if (rawNamespaces === undefined) {\n      throw new ContractValidationError(\n        'Contract storage.namespaces is required after structural validation',\n        'structural',\n      );\n    }\n    const hydratedNamespaces = this.hydrateSqlNamespaceMap(rawNamespaces);\n    // Keep the `__unbound__` brand sound: a deserialized contract may declare\n    // only named namespaces (cross-namespace contracts omit the late-bound\n    // slot), so inject the family unbound singleton when absent rather than\n    // asserting a shape that isn't present.\n    const unbound = hydratedNamespaces[UNBOUND_NAMESPACE_ID] ?? SqlUnboundNamespace.instance;\n\n    return {\n      ...validated,\n      storage: new SqlStorage({\n        storageHash: validated.storage.storageHash,\n        ...ifDefined('types', hydratedTypes),\n        // `__unbound__` is guaranteed present above; the residual narrowing is\n        // the family invariant that hydrated SQL namespaces are `SqlNamespace`\n        // instances (target/family classes, not the wider framework `Namespace`).\n        namespaces: blindCast<\n          SqlStorageInput['namespaces'],\n          'hydrated SQL namespaces are SqlNamespace instances; __unbound__ guaranteed present (injected above)'\n        >({ ...hydratedNamespaces, [UNBOUND_NAMESPACE_ID]: unbound }),\n      }),\n    };\n  }\n\n  protected hydrateSqlNamespaceMap(\n    namespaces: Readonly<Record<string, Namespace | Record<string, unknown>>>,\n  ): Readonly<Record<string, Namespace>> {\n    return Object.fromEntries(\n      Object.entries(namespaces).map(([nsId, namespaceEntryRaw]) => {\n        // Raw entries passed structural validation; hydrate materialises family IR class instances.\n        const namespaceHydrated = this.hydrateSqlNamespaceEntry(nsId, namespaceEntryRaw);\n        const namespaceMaterialised =\n          namespaceHydrated instanceof NamespaceBase\n            ? namespaceHydrated\n            : buildSqlNamespace(namespaceHydrated);\n        return [nsId, namespaceMaterialised];\n      }),\n    );\n  }\n\n  protected hydrateSqlNamespaceEntry(\n    nsId: string,\n    raw: Namespace | Record<string, unknown>,\n  ): Namespace | SqlNamespaceTablesInput {\n    if (raw instanceof NamespaceBase) {\n      return raw;\n    }\n    const rawRecord = isPlainRecord(raw) ? raw : {};\n    const id = typeof rawRecord['id'] === 'string' ? rawRecord['id'] : nsId;\n    const parsed = NamespaceRawSchema({ ...rawRecord, id });\n    if (parsed instanceof type.errors) {\n      const messages = parsed.map((p: { message: string }) => p.message).join('; ');\n      throw new ContractValidationError(`Namespace hydration failed: ${messages}`, 'structural');\n    }\n    const result: Record<string, unknown> = { id };\n\n    for (const [propertyKey, slotValue] of Object.entries(parsed)) {\n      if (propertyKey === 'id') continue;\n      if (slotValue === null || typeof slotValue !== 'object') continue;\n\n      if (propertyKey === 'tables') {\n        result['tables'] = Object.fromEntries(\n          Object.entries(slotValue as Record<string, unknown>).map(([tableName, table]) => [\n            tableName,\n            table instanceof StorageTable ? table : new StorageTable(table as StorageTableInput),\n          ]),\n        );\n        continue;\n      }\n\n      const hydratedSlot = Object.fromEntries(\n        Object.entries(slotValue as Record<string, unknown>).map(([entryName, entry]) => {\n          if (typeof entry !== 'object' || entry === null) {\n            return [entryName, entry];\n          }\n          const kind = (entry as { kind?: unknown }).kind;\n          if (typeof kind === 'string') {\n            const factory = this.entityTypeRegistry.get(kind);\n            if (factory !== undefined) {\n              return [entryName, factory(entry)];\n            }\n          }\n          return [entryName, entry];\n        }),\n      );\n      if (Object.keys(hydratedSlot).length > 0) {\n        result[propertyKey] = hydratedSlot;\n      }\n    }\n\n    const enumRaw = rawRecord['enum'];\n    if (enumRaw !== undefined && typeof enumRaw === 'object' && enumRaw !== null) {\n      for (const entry of Object.values(enumRaw as Record<string, unknown>)) {\n        if (typeof entry !== 'object' || entry === null) continue;\n        const kind = (entry as { kind?: unknown }).kind;\n        if (typeof kind === 'string' && this.entityTypeRegistry.get(kind) === undefined) {\n          throw new ContractValidationError(\n            `Entry kind '${kind}' has no registered hydration factory.`,\n            'structural',\n          );\n        }\n      }\n    }\n\n    const tables = (result['tables'] ?? {}) as Record<string, StorageTable>;\n    const enumSlot = result['enum'] as NonNullable<SqlNamespaceTablesInput['enum']> | undefined;\n    return {\n      ...result,\n      tables,\n      ...(enumSlot !== undefined ? { enum: enumSlot } : {}),\n    } as SqlNamespaceTablesInput;\n  }\n\n  protected hydrateStorageTypeEntry(entry: SqlStorageTypeEntry): SqlStorageTypeEntry {\n    if (typeof entry !== 'object' || entry === null) {\n      return entry;\n    }\n    const kind = (entry as { kind?: unknown }).kind;\n    if (typeof kind !== 'string') {\n      return entry;\n    }\n    const factory = this.entityTypeRegistry.get(kind);\n    if (factory === undefined) {\n      return entry;\n    }\n    return factory(entry);\n  }\n\n  protected constructTargetContract(hydrated: Contract<SqlStorage>): TContract {\n    return hydrated as TContract;\n  }\n}\n","import type { Contract } from '@prisma-next/contract/types';\nimport type { SqlStorage } from '@prisma-next/sql-contract/types';\nimport { SqlContractSerializerBase } from './sql-contract-serializer-base';\n\n/**\n * Default SQL family `ContractSerializer` concretion. Inherits the\n * full SQL-shared deserialization pipeline (structural validation +\n * IR-class hydration) without pack-registered `storage.types`\n * hydration factories — targets that emit polymorphic JSON outside the\n * codec-typed envelope wire a target-specific subclass with a populated\n * registry (see Postgres). Family-level call sites instantiate this\n * default directly when no target serializer is supplied.\n */\nexport class SqlContractSerializer extends SqlContractSerializerBase<Contract<SqlStorage>> {\n  constructor() {\n    super(new Map());\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"sql-contract-serializer-8axtK4lg.mjs","names":[],"sources":["../src/core/ir/sql-contract-serializer-base.ts","../src/core/ir/sql-contract-serializer.ts"],"sourcesContent":["import { ContractValidationError } from '@prisma-next/contract/contract-validation-error';\nimport type { Contract } from '@prisma-next/contract/types';\nimport type { ContractSerializer } from '@prisma-next/framework-components/control';\nimport {\n  type Namespace,\n  NamespaceBase,\n  UNBOUND_NAMESPACE_ID,\n} from '@prisma-next/framework-components/ir';\nimport { sqlContractCanonicalizationHooks } from '@prisma-next/sql-contract/canonicalization-hooks';\nimport {\n  buildSqlNamespace,\n  type SqlNamespaceTablesInput,\n  SqlStorage,\n  type SqlStorageInput,\n  type SqlStorageTypeEntry,\n  SqlUnboundNamespace,\n  StorageTable,\n  type StorageTableInput,\n} from '@prisma-next/sql-contract/types';\nimport {\n  createSqlContractSchema,\n  validateSqlContractFully,\n} from '@prisma-next/sql-contract/validators';\nimport { blindCast } from '@prisma-next/utils/casts';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport type { JsonObject } from '@prisma-next/utils/json';\nimport { type Type, type } from 'arktype';\n\nconst NamespaceRawSchema = type({\n  id: 'string',\n  'kind?': 'string',\n  // Undeclared keys (`tables`, `enum`, and any pack-contributed slot maps)\n  // intentionally pass through; the slot loop below iterates them by name.\n  '+': 'ignore',\n});\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nexport type SqlEntityHydrationFactory = (entry: unknown) => SqlStorageTypeEntry;\n\n/**\n * SQL family `ContractSerializer` abstract base. Carries the SQL-shared\n * deserialization pipeline:\n *\n * 1. `parseSqlContractStructure` validates the on-disk JSON envelope\n *    against the SQL contract arktype schema (`validateSqlContractFully`)\n *    and returns the validated flat-data shape.\n * 2. `hydrateSqlStorage` walks the validated `storage` subtree and\n *    constructs the family-shared SQL Contract IR class hierarchy\n *    (`SqlStorage` -> `StorageTable` -> `StorageColumn` / `PrimaryKey`\n *    / …). The rest of the contract envelope is JSON-clean primitive\n *    data and passes through unchanged.\n * 3. `constructTargetContract` is the target-specific extension hook;\n *    defaults to identity. Targets that need to attach target-only\n *    fields (e.g. target-specific derived storage fields) override it.\n *\n * Default `serializeContract` is identity over the contract — concrete\n * SQL targets ship JSON-clean class instances, so the contract value\n * can be stringified directly. The non-enumerable family-level `kind`\n * discriminator on `SqlNode` instances stays out of the persisted\n * envelope automatically. Targets that need to canonicalize on the way\n * out (key ordering, dropping computed-only fields) override\n * `serializeContract` directly.\n */\nexport abstract class SqlContractSerializerBase<TContract extends Contract<SqlStorage>>\n  implements ContractSerializer<TContract>\n{\n  private readonly contractSchema: Type<unknown> | undefined;\n\n  constructor(\n    private readonly entityTypeRegistry: ReadonlyMap<string, SqlEntityHydrationFactory> = new Map(),\n    validatorFragments?: ReadonlyMap<string, Type<unknown>>,\n  ) {\n    // Only build a fragments-aware contract schema when pack contributions\n    // exist. The cached module-level default in `validators.ts` covers the\n    // no-contributions case and avoids per-instance schema compilation.\n    this.contractSchema =\n      validatorFragments !== undefined && validatorFragments.size > 0\n        ? createSqlContractSchema(validatorFragments)\n        : undefined;\n  }\n\n  deserializeContract<T extends TContract = TContract>(json: unknown): T {\n    const validated = this.parseSqlContractStructure(json);\n    const hydrated = this.hydrateSqlStorage(validated);\n    return this.constructTargetContract(hydrated) as T;\n  }\n\n  serializeContract(contract: TContract): JsonObject {\n    return contract as unknown as JsonObject;\n  }\n\n  shouldPreserveEmpty = sqlContractCanonicalizationHooks.shouldPreserveEmpty;\n\n  sortStorage = sqlContractCanonicalizationHooks.sortStorage;\n\n  protected parseSqlContractStructure(json: unknown): Contract<SqlStorage> {\n    return validateSqlContractFully<Contract<SqlStorage>>(\n      json,\n      this.contractSchema !== undefined ? { contractSchema: this.contractSchema } : undefined,\n    );\n  }\n\n  protected hydrateSqlStorage(validated: Contract<SqlStorage>): Contract<SqlStorage> {\n    const types = validated.storage.types;\n    const hydratedTypes =\n      types !== undefined\n        ? Object.fromEntries(\n            Object.entries(types).map(([name, entry]) => [\n              name,\n              this.hydrateStorageTypeEntry(entry),\n            ]),\n          )\n        : undefined;\n\n    const rawNamespaces = validated.storage.namespaces;\n    if (rawNamespaces === undefined) {\n      throw new ContractValidationError(\n        'Contract storage.namespaces is required after structural validation',\n        'structural',\n      );\n    }\n    const hydratedNamespaces = this.hydrateSqlNamespaceMap(rawNamespaces);\n    // Compatibility shim: production code that addresses `__unbound__` for table\n    // metadata lookups (collection-contract, query-plan-mutations, model-accessor,\n    // query-plan-meta, where-binding) uses optional chaining and tolerates absence,\n    // but runtime-qualification (TML-2605) has not yet landed cross-namespace table\n    // routing. Injecting the empty singleton here keeps helpers that augment the\n    // deserialized JSON (e.g. buildMixedPolyContract) working by providing a slot to\n    // write into. Once runtime-qualification routes table lookups by namespace, this\n    // shim should be removed.\n    const unbound = hydratedNamespaces[UNBOUND_NAMESPACE_ID] ?? SqlUnboundNamespace.instance;\n\n    return {\n      ...validated,\n      storage: new SqlStorage({\n        storageHash: validated.storage.storageHash,\n        ...ifDefined('types', hydratedTypes),\n        // Cast narrows the result of hydrateSqlNamespaceMap from the wider\n        // framework `Namespace` to the SQL-family `SqlNamespace`.\n        namespaces: blindCast<\n          SqlStorageInput['namespaces'],\n          'hydrated SQL namespaces are SqlNamespace instances (family hydration guarantees this)'\n        >({ ...hydratedNamespaces, [UNBOUND_NAMESPACE_ID]: unbound }),\n      }),\n    };\n  }\n\n  protected hydrateSqlNamespaceMap(\n    namespaces: Readonly<Record<string, Namespace | Record<string, unknown>>>,\n  ): Readonly<Record<string, Namespace>> {\n    return Object.fromEntries(\n      Object.entries(namespaces).map(([nsId, namespaceEntryRaw]) => {\n        // Raw entries passed structural validation; hydrate materialises family IR class instances.\n        const namespaceHydrated = this.hydrateSqlNamespaceEntry(nsId, namespaceEntryRaw);\n        const namespaceMaterialised =\n          namespaceHydrated instanceof NamespaceBase\n            ? namespaceHydrated\n            : buildSqlNamespace(namespaceHydrated);\n        return [nsId, namespaceMaterialised];\n      }),\n    );\n  }\n\n  protected hydrateSqlNamespaceEntry(\n    nsId: string,\n    raw: Namespace | Record<string, unknown>,\n  ): Namespace | SqlNamespaceTablesInput {\n    if (raw instanceof NamespaceBase) {\n      return raw;\n    }\n    const rawRecord = isPlainRecord(raw) ? raw : {};\n    const id = typeof rawRecord['id'] === 'string' ? rawRecord['id'] : nsId;\n    const parsed = NamespaceRawSchema({ ...rawRecord, id });\n    if (parsed instanceof type.errors) {\n      const messages = parsed.map((p: { message: string }) => p.message).join('; ');\n      throw new ContractValidationError(`Namespace hydration failed: ${messages}`, 'structural');\n    }\n    const result: Record<string, unknown> = { id };\n\n    for (const [propertyKey, slotValue] of Object.entries(parsed)) {\n      if (propertyKey === 'id') continue;\n      if (slotValue === null || typeof slotValue !== 'object') continue;\n\n      if (propertyKey === 'tables') {\n        result['tables'] = Object.fromEntries(\n          Object.entries(slotValue as Record<string, unknown>).map(([tableName, table]) => [\n            tableName,\n            table instanceof StorageTable ? table : new StorageTable(table as StorageTableInput),\n          ]),\n        );\n        continue;\n      }\n\n      const hydratedSlot = Object.fromEntries(\n        Object.entries(slotValue as Record<string, unknown>).map(([entryName, entry]) => {\n          if (typeof entry !== 'object' || entry === null) {\n            return [entryName, entry];\n          }\n          const kind = (entry as { kind?: unknown }).kind;\n          if (typeof kind === 'string') {\n            const factory = this.entityTypeRegistry.get(kind);\n            if (factory !== undefined) {\n              return [entryName, factory(entry)];\n            }\n          }\n          return [entryName, entry];\n        }),\n      );\n      if (Object.keys(hydratedSlot).length > 0) {\n        result[propertyKey] = hydratedSlot;\n      }\n    }\n\n    const enumRaw = rawRecord['enum'];\n    if (enumRaw !== undefined && typeof enumRaw === 'object' && enumRaw !== null) {\n      for (const entry of Object.values(enumRaw as Record<string, unknown>)) {\n        if (typeof entry !== 'object' || entry === null) continue;\n        const kind = (entry as { kind?: unknown }).kind;\n        if (typeof kind === 'string' && this.entityTypeRegistry.get(kind) === undefined) {\n          throw new ContractValidationError(\n            `Entry kind '${kind}' has no registered hydration factory.`,\n            'structural',\n          );\n        }\n      }\n    }\n\n    const tables = (result['tables'] ?? {}) as Record<string, StorageTable>;\n    const enumSlot = result['enum'] as NonNullable<SqlNamespaceTablesInput['enum']> | undefined;\n    return {\n      ...result,\n      tables,\n      ...(enumSlot !== undefined ? { enum: enumSlot } : {}),\n    } as SqlNamespaceTablesInput;\n  }\n\n  protected hydrateStorageTypeEntry(entry: SqlStorageTypeEntry): SqlStorageTypeEntry {\n    if (typeof entry !== 'object' || entry === null) {\n      return entry;\n    }\n    const kind = (entry as { kind?: unknown }).kind;\n    if (typeof kind !== 'string') {\n      return entry;\n    }\n    const factory = this.entityTypeRegistry.get(kind);\n    if (factory === undefined) {\n      return entry;\n    }\n    return factory(entry);\n  }\n\n  protected constructTargetContract(hydrated: Contract<SqlStorage>): TContract {\n    return hydrated as TContract;\n  }\n}\n","import type { Contract } from '@prisma-next/contract/types';\nimport type { SqlStorage } from '@prisma-next/sql-contract/types';\nimport { SqlContractSerializerBase } from './sql-contract-serializer-base';\n\n/**\n * Default SQL family `ContractSerializer` concretion. Inherits the\n * full SQL-shared deserialization pipeline (structural validation +\n * IR-class hydration) without pack-registered `storage.types`\n * hydration factories — targets that emit polymorphic JSON outside the\n * codec-typed envelope wire a target-specific subclass with a populated\n * registry (see Postgres). Family-level call sites instantiate this\n * default directly when no target serializer is supplied.\n */\nexport class SqlContractSerializer extends SqlContractSerializerBase<Contract<SqlStorage>> {\n  constructor() {\n    super(new Map());\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,38 +1,46 @@
 {
   "name": "@prisma-next/family-sql",
-  "version": "0.11.0-dev.71",
+  "version": "0.11.0-dev.73",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "SQL family descriptor for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.11.0-dev.71",
-    "@prisma-next/emitter": "0.11.0-dev.71",
-    "@prisma-next/framework-components": "0.11.0-dev.71",
-    "@prisma-next/migration-tools": "0.11.0-dev.71",
-    "@prisma-next/operations": "0.11.0-dev.71",
-    "@prisma-next/sql-contract": "0.11.0-dev.71",
-    "@prisma-next/sql-contract-emitter": "0.11.0-dev.71",
-    "@prisma-next/sql-contract-ts": "0.11.0-dev.71",
-    "@prisma-next/sql-operations": "0.11.0-dev.71",
-    "@prisma-next/sql-relational-core": "0.11.0-dev.71",
-    "@prisma-next/sql-runtime": "0.11.0-dev.71",
-    "@prisma-next/sql-schema-ir": "0.11.0-dev.71",
-    "@prisma-next/utils": "0.11.0-dev.71",
+    "@prisma-next/contract": "0.11.0-dev.73",
+    "@prisma-next/emitter": "0.11.0-dev.73",
+    "@prisma-next/framework-components": "0.11.0-dev.73",
+    "@prisma-next/migration-tools": "0.11.0-dev.73",
+    "@prisma-next/operations": "0.11.0-dev.73",
+    "@prisma-next/sql-contract": "0.11.0-dev.73",
+    "@prisma-next/sql-contract-emitter": "0.11.0-dev.73",
+    "@prisma-next/sql-contract-ts": "0.11.0-dev.73",
+    "@prisma-next/sql-operations": "0.11.0-dev.73",
+    "@prisma-next/sql-relational-core": "0.11.0-dev.73",
+    "@prisma-next/sql-runtime": "0.11.0-dev.73",
+    "@prisma-next/sql-schema-ir": "0.11.0-dev.73",
+    "@prisma-next/utils": "0.11.0-dev.73",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@prisma-next/driver-postgres": "0.11.0-dev.71",
-    "@prisma-next/psl-parser": "0.11.0-dev.71",
-    "@prisma-next/psl-printer": "0.11.0-dev.71",
-    "@prisma-next/sql-contract-psl": "0.11.0-dev.71",
-    "@prisma-next/test-utils": "0.11.0-dev.71",
-    "@prisma-next/tsconfig": "0.11.0-dev.71",
-    "@prisma-next/tsdown": "0.11.0-dev.71",
+    "@prisma-next/driver-postgres": "0.11.0-dev.73",
+    "@prisma-next/psl-parser": "0.11.0-dev.73",
+    "@prisma-next/psl-printer": "0.11.0-dev.73",
+    "@prisma-next/sql-contract-psl": "0.11.0-dev.73",
+    "@prisma-next/test-utils": "0.11.0-dev.73",
+    "@prisma-next/tsconfig": "0.11.0-dev.73",
+    "@prisma-next/tsdown": "0.11.0-dev.73",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.6"
   },
+  "peerDependencies": {
+    "typescript": ">=5.9"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "files": [
     "dist",
     "src"
@@ -49,6 +57,9 @@
     "./verify": "./dist/verify.mjs",
     "./package.json": "./package.json"
   },
+  "engines": {
+    "node": ">=24"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/prisma/prisma-next.git",

package/src/core/ir/sql-contract-serializer-base.ts

@@ -123,10 +123,14 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
       );
     }
     const hydratedNamespaces = this.hydrateSqlNamespaceMap(rawNamespaces);
-    // Keep the `__unbound__` brand sound: a deserialized contract may declare
-    // only named namespaces (cross-namespace contracts omit the late-bound
-    // slot), so inject the family unbound singleton when absent rather than
-    // asserting a shape that isn't present.
+    // Compatibility shim: production code that addresses `__unbound__` for table
+    // metadata lookups (collection-contract, query-plan-mutations, model-accessor,
+    // query-plan-meta, where-binding) uses optional chaining and tolerates absence,
+    // but runtime-qualification (TML-2605) has not yet landed cross-namespace table
+    // routing. Injecting the empty singleton here keeps helpers that augment the
+    // deserialized JSON (e.g. buildMixedPolyContract) working by providing a slot to
+    // write into. Once runtime-qualification routes table lookups by namespace, this
+    // shim should be removed.
     const unbound = hydratedNamespaces[UNBOUND_NAMESPACE_ID] ?? SqlUnboundNamespace.instance;
 
     return {
@@ -134,12 +138,11 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
       storage: new SqlStorage({
         storageHash: validated.storage.storageHash,
         ...ifDefined('types', hydratedTypes),
-        // `__unbound__` is guaranteed present above; the residual narrowing is
-        // the family invariant that hydrated SQL namespaces are `SqlNamespace`
-        // instances (target/family classes, not the wider framework `Namespace`).
+        // Cast narrows the result of hydrateSqlNamespaceMap from the wider
+        // framework `Namespace` to the SQL-family `SqlNamespace`.
         namespaces: blindCast<
           SqlStorageInput['namespaces'],
-          'hydrated SQL namespaces are SqlNamespace instances; __unbound__ guaranteed present (injected above)'
+          'hydrated SQL namespaces are SqlNamespace instances (family hydration guarantees this)'
         >({ ...hydratedNamespaces, [UNBOUND_NAMESPACE_ID]: unbound }),
       }),
     };