@prisma-next/contract 0.12.0 → 0.13.0-dev.10

package/src/domain-namespace-access.ts

@@ -0,0 +1,32 @@
+import { DomainNamespaceResolutionError } from './contract-validation-error';
+import { soleDomainNamespaceId } from './default-namespace';
+import type { ApplicationDomain } from './domain-envelope';
+import type { ContractModelBase, ContractValueObject } from './domain-types';
+
+/**
+ * Models map for the contract's single domain namespace. Throws when the
+ * contract does not declare exactly one namespace — bare-name access is
+ * ambiguous across namespaces and must be qualified explicitly (TML-2550).
+ */
+export function domainModelsAtDefaultNamespace<TModels extends Record<string, ContractModelBase>>(
+  domain: ApplicationDomain<TModels>,
+): TModels {
+  const namespaceId = soleDomainNamespaceId(domain);
+  const domainNamespace = domain.namespaces[namespaceId];
+  if (domainNamespace === undefined) {
+    throw new DomainNamespaceResolutionError(
+      `domain namespace "${namespaceId}" is not present on the contract`,
+    );
+  }
+  return domainNamespace.models;
+}
+
+/**
+ * Value objects for the contract's single domain namespace, when present.
+ * Throws when the contract does not declare exactly one namespace.
+ */
+export function domainValueObjectsAtDefaultNamespace<
+  TModels extends Record<string, ContractModelBase>,
+>(domain: ApplicationDomain<TModels>): Record<string, ContractValueObject> | undefined {
+  return domain.namespaces[soleDomainNamespaceId(domain)]?.valueObjects;
+}

package/src/domain-types.ts

@@ -1,4 +1,6 @@
 import type { CrossReference } from './cross-reference';
+import type { JsonValue } from './types';
+import type { ValueSetRef } from './value-set-ref';
 
 export type ScalarFieldType = {
   readonly kind: 'scalar';
@@ -23,6 +25,17 @@ export type ContractField = {
   readonly type: ContractFieldType;
   readonly many?: true;
   readonly dict?: true;
+  readonly valueSet?: ValueSetRef;
+};
+
+/**
+ * A domain enum: an ordered set of named members, each with a codec-encoded
+ * value. The `codecId` identifies the codec used to encode member values in
+ * storage. The `members` array is ordered (declaration order is preserved).
+ */
+export type ContractEnum = {
+  readonly codecId: string;
+  readonly members: readonly { readonly name: string; readonly value: JsonValue }[];
 };
 
 export type ContractRelationOn = {
@@ -30,12 +43,30 @@ export type ContractRelationOn = {
   readonly targetFields: readonly string[];
 };
 
-export type ContractReferenceRelation = {
+export type ContractRelationThrough = {
+  readonly table: string;
+  readonly namespaceId: string;
+  readonly parentColumns: readonly string[];
+  readonly childColumns: readonly string[];
+  readonly targetColumns: readonly string[];
+};
+
+export type ContractManyToManyRelation = {
+  readonly to: CrossReference;
+  readonly cardinality: 'N:M';
+  readonly on: ContractRelationOn;
+  readonly through: ContractRelationThrough;
+};
+
+export type ContractNonJunctionRelation = {
   readonly to: CrossReference;
   readonly cardinality: '1:1' | '1:N' | 'N:1';
   readonly on: ContractRelationOn;
+  readonly through?: never;
 };
 
+export type ContractReferenceRelation = ContractManyToManyRelation | ContractNonJunctionRelation;
+
 export type ContractEmbedRelation = {
   readonly to: CrossReference;
   readonly cardinality: '1:1' | '1:N';

package/src/enum-accessor.ts

@@ -0,0 +1,173 @@
+import type { Contract } from './contract-types';
+import type { ContractEnum } from './domain-types';
+import type { JsonValue } from './types';
+
+/**
+ * Runtime view of a domain enum, built at the client from the emitted
+ * `ContractEnum` JSON (codec-encoded `JsonValue` members, literal types erased).
+ *
+ * This deliberately mirrors the accessor shape of the authoring-time
+ * `EnumTypeHandle` (in `contract-ts`) rather than reusing it: that handle carries
+ * the literal value generics and lives in the authoring layer, which the
+ * foundation layer cannot depend on. The two are the same surface seen from the
+ * two planes — authoring (typed) and runtime (validated JSON).
+ */
+export interface EnumAccessor {
+  readonly values: readonly JsonValue[];
+  readonly names: readonly string[];
+  readonly members: Readonly<Record<string, JsonValue>>;
+  has(v: JsonValue): boolean;
+  nameOf(v: JsonValue): string | undefined;
+  ordinalOf(v: JsonValue): number;
+}
+
+export function createEnumAccessor(contractEnum: ContractEnum): EnumAccessor {
+  const values = Object.freeze(contractEnum.members.map((m) => m.value));
+  const names = Object.freeze(contractEnum.members.map((m) => m.name));
+  const members: Readonly<Record<string, JsonValue>> = Object.freeze(
+    Object.fromEntries(contractEnum.members.map((m) => [m.name, m.value])),
+  );
+
+  const valueSet = new Set(values);
+  const valueToName = new Map(contractEnum.members.map((m) => [m.value, m.name]));
+  const valueToOrdinal = new Map(values.map((v, i) => [v, i]));
+
+  return {
+    values,
+    names,
+    members,
+    has: (v: JsonValue) => valueSet.has(v),
+    nameOf: (v: JsonValue) => valueToName.get(v),
+    ordinalOf: (v: JsonValue) => valueToOrdinal.get(v) ?? -1,
+  };
+}
+
+/**
+ * Build the enum-accessor map for a single namespace, keyed by enum name.
+ * Each namespace facet exposes only its own enums — the IR keys enums under
+ * `domain.namespaces[ns].enum`, so the same name in two namespaces resolves
+ * independently rather than colliding in one flat map.
+ */
+export function buildEnumsMapForNamespace(
+  domain: {
+    readonly namespaces: Readonly<
+      Record<string, { readonly enum?: Readonly<Record<string, ContractEnum>> }>
+    >;
+  },
+  namespaceId: string,
+): Record<string, EnumAccessor> {
+  const result: Record<string, EnumAccessor> = {};
+  const namespace = domain.namespaces[namespaceId];
+  if (namespace?.enum) {
+    for (const [name, contractEnum] of Object.entries(namespace.enum)) {
+      result[name] = createEnumAccessor(contractEnum);
+    }
+  }
+  return result;
+}
+
+/**
+ * Build the enum-accessor map for every namespace of a domain, keyed by
+ * namespace id then enum name. This is the lane-agnostic enum surface the
+ * `db.enums` facade member exposes: enums are contract metadata, the same
+ * whether reached through the sql lane or the orm lane, so the facade builds
+ * this once and projects it per target.
+ */
+export function buildNamespacedEnums(domain: {
+  readonly namespaces: Readonly<
+    Record<string, { readonly enum?: Readonly<Record<string, ContractEnum>> }>
+  >;
+}): Record<string, Record<string, EnumAccessor>> {
+  const result: Record<string, Record<string, EnumAccessor>> = {};
+  for (const namespaceId of Object.keys(domain.namespaces)) {
+    result[namespaceId] = buildEnumsMapForNamespace(domain, namespaceId);
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Type-level projection of the namespaced enum surface.
+//
+// These types derive the literal-preserving accessor shape from the contract,
+// hung off the `db.enums` facade map (`db.enums.<ns>.<Name>`). They are the
+// same accessors the runtime builds above, but typed from the two emission
+// paths:
+//   - Emitted contracts carry the literal enum entries under
+//     `domain.namespaces[ns].enum`; each maps to a `ContractEnumAccessor`.
+//   - The no-emit (built) contract carries them flat on `enumAccessors`
+//     (already accessor-shaped, literal-preserving), since its built domain
+//     type does not narrow `namespaces[ns].enum`. All authored enums land in
+//     the single built namespace, so exposing the flat map per namespace is
+//     correct there.
+// Only `SqlContractResult` carries `enumAccessors`; emitted contracts never
+// do, so the two carriers never overlap.
+// ---------------------------------------------------------------------------
+
+type Present<T> = Exclude<T, undefined>;
+
+// A domain enum entry as carried in `domain.namespaces[ns].enum[name]`: an
+// ordered member tuple. The no-emit (built) path preserves the literal member
+// values so the derived accessor keeps its literal `values`/`names`/`members`.
+type EnumMemberEntry = { readonly name: string; readonly value: unknown };
+type EnumEntry = { readonly members: readonly EnumMemberEntry[] };
+
+type EnumEntryValues<Entry extends EnumEntry> = {
+  readonly [I in keyof Entry['members']]: Entry['members'][I] extends EnumMemberEntry
+    ? Entry['members'][I]['value']
+    : never;
+};
+
+type EnumEntryNames<Entry extends EnumEntry> = {
+  readonly [I in keyof Entry['members']]: Entry['members'][I] extends EnumMemberEntry
+    ? Entry['members'][I]['name']
+    : never;
+};
+
+type EnumEntryMembers<Entry extends EnumEntry> = {
+  readonly [M in Entry['members'][number] as M['name']]: M['value'];
+};
+
+// The runtime accessor shape for one enum, with literal `values`/`names`/
+// `members` derived from the entry's member tuple. Mirrors `EnumAccessor`'s
+// runtime surface and the authoring `EnumTypeHandle` accessor.
+export type ContractEnumAccessor<Entry extends EnumEntry> = {
+  readonly values: EnumEntryValues<Entry>;
+  readonly names: EnumEntryNames<Entry>;
+  readonly members: EnumEntryMembers<Entry>;
+  has(v: EnumEntryValues<Entry>[number]): boolean;
+  nameOf(v: EnumEntryValues<Entry>[number]): string | undefined;
+  ordinalOf(v: EnumEntryValues<Entry>[number]): number;
+};
+
+type EnumEntriesToAccessors<Enums> = {
+  readonly [K in keyof Enums]: Enums[K] extends EnumEntry ? ContractEnumAccessor<Enums[K]> : never;
+};
+
+type BuiltEnumAccessorsOf<TContract> = TContract extends {
+  readonly enumAccessors: infer A;
+}
+  ? A
+  : Record<never, never>;
+
+type NamespaceEnumEntries<TNamespace> = TNamespace extends {
+  readonly enum?: infer E;
+}
+  ? unknown extends E
+    ? Record<never, never>
+    : Present<E>
+  : Record<never, never>;
+
+// The per-namespace enum accessors. Each namespace exposes only its own enums
+// (the IR's `domain.namespaces[ns].enum`), so the same enum name in two
+// namespaces resolves to each namespace's own accessor.
+export type NamespaceEnumAccessors<
+  TContract extends Contract,
+  NsId extends keyof TContract['domain']['namespaces'],
+> = EnumEntriesToAccessors<NamespaceEnumEntries<TContract['domain']['namespaces'][NsId]>> &
+  BuiltEnumAccessorsOf<TContract>;
+
+// The lane-agnostic enum surface exposed on the `db.enums` facade member: a
+// namespace-keyed map projected per target exactly like `db.sql` / `db.orm`.
+export type NamespacedEnums<TContract extends Contract> = {
+  readonly [Ns in keyof TContract['domain']['namespaces']]: NamespaceEnumAccessors<TContract, Ns>;
+};

package/src/exports/apply-specifier-default-control-policy.ts

@@ -0,0 +1 @@
+export { applySpecifierDefaultControlPolicy } from '../apply-specifier-default-control-policy';

package/src/exports/default-namespace.ts

@@ -0,0 +1 @@
+export { soleDomainNamespaceId, UNBOUND_DOMAIN_NAMESPACE_ID } from '../default-namespace';

package/src/exports/enum-accessor.ts

@@ -0,0 +1,11 @@
+export type {
+  ContractEnumAccessor,
+  EnumAccessor,
+  NamespacedEnums,
+  NamespaceEnumAccessors,
+} from '../enum-accessor';
+export {
+  buildEnumsMapForNamespace,
+  buildNamespacedEnums,
+  createEnumAccessor,
+} from '../enum-accessor';

package/src/exports/resolve-domain-model.ts

@@ -0,0 +1 @@
+export { type ResolvedDomainModel, resolveDomainModel } from '../resolve-domain-model';

package/src/exports/types.ts

@@ -1,33 +1,39 @@
 export type {
   Contract,
   ContractExecutionSection,
-  ContractModelsMap,
-  ContractValueObjectsMap,
+  ContractModelDefinitions,
+  ContractValueObjectDefinitions,
 } from '../contract-types';
 export { DomainNamespaceResolutionError } from '../contract-validation-error';
+export type { ControlPolicy } from '../control-policy';
+export { effectiveControlPolicy } from '../control-policy';
 export type { CrossReference } from '../cross-reference';
 export { CrossReferenceSchema, crossRef } from '../cross-reference';
+export { soleDomainNamespaceId } from '../default-namespace';
 export type {
   ApplicationDomain,
   ApplicationDomainNamespace,
   ContractWithDomain,
 } from '../domain-envelope';
+export { UNBOUND_DOMAIN_NAMESPACE_ID } from '../domain-envelope';
 export {
-  contractModels,
-  contractValueObjects,
-  resolveSingleDomainNamespaceId,
-  UNBOUND_DOMAIN_NAMESPACE_ID,
-} from '../domain-envelope';
+  domainModelsAtDefaultNamespace,
+  domainValueObjectsAtDefaultNamespace,
+} from '../domain-namespace-access';
 export type {
   ContractDiscriminator,
   ContractEmbedRelation,
+  ContractEnum,
   ContractField,
   ContractFieldType,
+  ContractManyToManyRelation,
   ContractModel,
   ContractModelBase,
+  ContractNonJunctionRelation,
   ContractReferenceRelation,
   ContractRelation,
   ContractRelationOn,
+  ContractRelationThrough,
   ContractValueObject,
   ContractVariantEntry,
   EmbedRelationKeys,
@@ -39,6 +45,7 @@ export type {
 } from '../domain-types';
 export type { NamespaceId } from '../namespace-id';
 export { asNamespaceId } from '../namespace-id';
+export { type ResolvedDomainModel, resolveDomainModel } from '../resolve-domain-model';
 export type {
   $,
   Brand,
@@ -58,6 +65,7 @@ export type {
   GeneratedValueSpec,
   JsonPrimitive,
   JsonValue,
+  LedgerEntryRecord,
   PlanMeta,
   ProfileHashBase,
   Source,
@@ -74,3 +82,4 @@ export {
   isExecutionMutationDefaultValue,
   profileHash,
 } from '../types';
+export type { ValueSetRef } from '../value-set-ref';

package/src/hashing.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { blindCast, castAs } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { JsonObject } from '@prisma-next/utils/json';
 import {
@@ -11,6 +12,33 @@ import type { ExecutionHashBase, ProfileHashBase, StorageHashBase } from './type
 
 const SCHEMA_VERSION = '1';
 
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// Storage hashes fingerprint table/column layout, not which target pack emitted a
+// namespace. Persisted contract.json carries namespace `kind` discriminators;
+// authoring-time hashes never included them (IR `kind` is non-enumerable).
+function omitNamespaceKindsForHash(storage: unknown): unknown {
+  if (!isPlainRecord(storage)) {
+    return storage;
+  }
+  const namespaces = storage['namespaces'];
+  if (!isPlainRecord(namespaces)) {
+    return storage;
+  }
+  const stripped: Record<string, unknown> = {};
+  for (const [nsId, ns] of Object.entries(namespaces)) {
+    if (isPlainRecord(ns)) {
+      const { kind: _kind, ...rest } = ns;
+      stripped[nsId] = rest;
+    } else {
+      stripped[nsId] = ns;
+    }
+  }
+  return { ...storage, namespaces: stripped };
+}
+
 function sha256(content: string): string {
   const hash = createHash('sha256');
   hash.update(content);
@@ -24,28 +52,23 @@ type HashContractSection = Record<string, unknown> & {
 
 function hashContract(section: HashContractSection): string {
   const { shouldPreserveEmpty, sortStorage, ...sectionData } = section;
-  // Blind cast: the synthesised object is a hash-only stand-in
-  // — never returned to callers, never executed as a Contract.
-  // `canonicalizeContract` only walks the storage / execution /
-  // capabilities slices, all of which are populated above, so the
-  // missing precise Contract typing on the other slots is
-  // immaterial for the hash result.
-  const contract = {
+  const storageForHash = omitNamespaceKindsForHash(sectionData['storage'] ?? {});
+  const contract = blindCast<Contract, 'hash-only partial contract for canonicalizeContract'>({
     targetFamily: sectionData['targetFamily'],
     target: sectionData['target'],
     roots: {},
     domain: { namespaces: {} },
-    storage: sectionData['storage'] ?? {},
     execution: sectionData['execution'],
     extensionPacks: {},
     capabilities: sectionData['capabilities'] ?? {},
     meta: {},
     profileHash: '',
     ...sectionData,
-  } as unknown as Contract;
+    storage: storageForHash,
+  });
   return canonicalizeContract(contract, {
     schemaVersion: SCHEMA_VERSION,
-    serializeContract: (c) => JSON.parse(JSON.stringify(c)) as JsonObject,
+    serializeContract: (c) => castAs<JsonObject>(JSON.parse(JSON.stringify(c))),
     ...ifDefined('shouldPreserveEmpty', shouldPreserveEmpty),
     ...ifDefined('sortStorage', sortStorage),
   });
@@ -60,7 +83,9 @@ export type ComputeStorageHashArgs = {
 };
 
 export function computeStorageHash(args: ComputeStorageHashArgs): StorageHashBase<string> {
-  return sha256(hashContract(args)) as StorageHashBase<string>;
+  return blindCast<StorageHashBase<string>, 'sha256 digest of canonicalized storage'>(
+    sha256(hashContract(args)),
+  );
 }
 
 export function computeExecutionHash(args: {
@@ -68,7 +93,9 @@ export function computeExecutionHash(args: {
   targetFamily: string;
   execution: Record<string, unknown>;
 }): ExecutionHashBase<string> {
-  return sha256(hashContract(args)) as ExecutionHashBase<string>;
+  return blindCast<ExecutionHashBase<string>, 'sha256 digest of canonicalized execution'>(
+    sha256(hashContract(args)),
+  );
 }
 
 export function computeProfileHash(args: {
@@ -76,5 +103,7 @@ export function computeProfileHash(args: {
   targetFamily: string;
   capabilities: Record<string, Record<string, boolean>>;
 }): ProfileHashBase<string> {
-  return sha256(hashContract(args)) as ProfileHashBase<string>;
+  return blindCast<ProfileHashBase<string>, 'sha256 digest of canonicalized profile'>(
+    sha256(hashContract(args)),
+  );
 }

package/src/resolve-domain-model.ts

@@ -0,0 +1,27 @@
+import type { ApplicationDomain } from './domain-envelope';
+import type { ContractModelBase } from './domain-types';
+
+export interface ResolvedDomainModel {
+  readonly namespaceId: string;
+  readonly model: ContractModelBase;
+}
+
+/**
+ * Resolve a bare domain model name to its namespace coordinate and model IR by
+ * scanning the contract's namespaces. For the single-namespace contracts in
+ * scope the scan is exact; cross-namespace bare-name collisions are selected
+ * explicitly (TML-2550).
+ */
+export function resolveDomainModel(
+  domain: ApplicationDomain,
+  modelName: string,
+): ResolvedDomainModel | undefined {
+  for (const namespaceId of Object.keys(domain.namespaces)) {
+    const model = domain.namespaces[namespaceId]?.models[modelName];
+    if (model !== undefined) {
+      return { namespaceId, model };
+    }
+  }
+
+  return undefined;
+}

package/src/types.ts

@@ -57,11 +57,13 @@ export type StorageEntitySlot = Readonly<Record<string, unknown>>;
 
 /**
  * Plain-data namespace entry in a storage block. Every hydrated contract
- * carries at least `id` plus zero or more entity-kind slot maps (`tables`,
- * `collections`, …). Foundation declares only this shape — no IR machinery.
+ * carries at least `id` plus entity-kind slot maps under `entries`
+ * (`table`, `collection`, …). Foundation declares only this shape — no IR
+ * machinery.
  */
 export interface StorageNamespace {
   readonly id: string;
+  readonly entries: Readonly<Record<string, StorageEntitySlot>>;
 }
 
 /**
@@ -243,3 +245,17 @@ export interface ContractMarkerRecord {
   readonly meta: Record<string, unknown>;
   readonly invariants: readonly string[];
 }
+
+/**
+ * One applied migration edge from the per-space ledger journal.
+ * Returned by `readLedger` in append (apply) order.
+ */
+export interface LedgerEntryRecord {
+  readonly space: string;
+  readonly migrationName: string;
+  readonly migrationHash: string;
+  readonly from: string | null;
+  readonly to: string;
+  readonly appliedAt: Date;
+  readonly operationCount: number;
+}

package/src/validate-domain.ts

@@ -140,6 +140,12 @@ function validateVariantsAndBases(modelIndex: ModelIndex, errors: string[]): voi
 function validateRelationTargets(modelIndex: ModelIndex, errors: string[]): void {
   for (const { namespaceId, name: modelName, model } of iterateIndexedModels(modelIndex)) {
     for (const [relName, relation] of Object.entries(model.relations ?? {})) {
+      // Cross-space relations (relation.to.space is defined) target a model in a
+      // different contract space. The local domain index only contains this
+      // contract's own models, so the target is intentionally absent here.
+      // Existence of the target is verified by the aggregate verifier at
+      // deploy time (after the spaces are composed), not at parse time.
+      if (relation.to.space !== undefined) continue;
       if (!lookupModel(modelIndex, relation.to)) {
         errors.push(
           `Relation "${relName}" on model "${namespaceId}:${modelName}" targets "${relation.to.namespace}:${relation.to.model}" which does not exist in domain.namespaces`,

package/src/value-set-ref.ts

@@ -0,0 +1,26 @@
+/**
+ * Space-aware reference coordinate for a domain enum or storage value-set.
+ *
+ * `plane` names the contract plane the referenced entity lives in:
+ * - `'domain'` — the entity lives in the domain plane's `enum` slot.
+ * - `'storage'` — the entity lives in the storage plane's `valueSet` slot.
+ *
+ * `entityKind` names the source entity-kind:
+ * - `'enum'` — the referenced entity is a domain enum.
+ * - `'value-set'` — the referenced entity is a storage value-set.
+ *
+ * `namespaceId` admits the `UNBOUND_NAMESPACE_ID` (`__unbound__`) sentinel for
+ * single-namespace (unbound) references.
+ *
+ * Cross-space discrimination is presence-based: when `spaceId` is absent the
+ * reference is local (same contract-space); when `spaceId` is present the
+ * reference is cross-space. This mirrors the `ForeignKeyReference` carrier
+ * convention — no separate tag field — so local refs are JSON-minimal.
+ */
+export interface ValueSetRef {
+  readonly plane: 'domain' | 'storage';
+  readonly namespaceId: string;
+  readonly entityKind: 'enum' | 'value-set';
+  readonly name: string;
+  readonly spaceId?: string;
+}

package/dist/canonicalization-DFE0HJkI.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonicalization-DFE0HJkI.d.mts","names":[],"sources":["../src/canonicalization.ts"],"mappings":";;;;;;AAcA;;;;;;KAAY,iBAAA,IAAqB,QAAA,EAAU,QAAA,KAAa,UAAU;;AAAA;AAUlE;;;;AAA6D;AAS7D;KATY,sBAAA,IAA0B,IAAuB;;;AASlB;AA6K3C;;;;KA7KY,WAAA,IAAe,OAAgB;AAAA,UA6K1B,2BAAA;EAAA,SACN,aAAA;EAAA;;;;;;;;AA0ByB;AAQpC;EAlCW,SAWA,iBAAA,EAAmB,iBAAA;;;;;;;WAOnB,mBAAA,GAAsB,sBAAA;EAiB/B;;;;;AAEO;AA0BT;EA5BE,SATS,WAAA,GAAc,WAAA;AAAA;;;;;;iBAQT,4BAAA,CACd,QAAA,EAAU,QAAA,EACV,OAAA,EAAS,2BAAA,GACR,MAAA;AAAA,iBA0Ba,oBAAA,CACd,QAAA,EAAU,QAAA,EACV,OAAA,EAAS,2BAA2B"}