@prisma-next/contract 0.11.0 → 0.12.0

package/src/cross-reference.ts

@@ -0,0 +1,28 @@
+import { blindCast } from '@prisma-next/utils/casts';
+import { type Type, type } from 'arktype';
+import { asNamespaceId, type NamespaceId } from './namespace-id';
+
+export interface CrossReference {
+  readonly namespace: NamespaceId;
+  readonly model: string;
+}
+
+export const CrossReferenceSchema = blindCast<
+  Type<CrossReference>,
+  'namespace is validated as string at runtime and branded to NamespaceId by asNamespaceId in crossRef(); the schema accepts plain strings but the public type reflects the branded shape'
+>(
+  type({
+    '+': 'reject',
+    namespace: 'string',
+    model: 'string',
+  }),
+);
+
+const DEFAULT_CROSS_REF_NAMESPACE = '__unbound__';
+
+export function crossRef(
+  model: string,
+  namespace: string = DEFAULT_CROSS_REF_NAMESPACE,
+): CrossReference {
+  return { namespace: asNamespaceId(namespace), model };
+}

package/src/domain-envelope.ts

@@ -0,0 +1,87 @@
+import { DomainNamespaceResolutionError } from './contract-validation-error';
+import type { ContractModelBase, ContractValueObject } from './domain-types';
+
+export const UNBOUND_DOMAIN_NAMESPACE_ID = '__unbound__' as const;
+
+/**
+ * One namespace's application-domain entities — models and optional value
+ * objects keyed by entity name within that namespace coordinate.
+ */
+export interface ApplicationDomainNamespace<
+  TModels extends Record<string, ContractModelBase> = Record<string, ContractModelBase>,
+> {
+  readonly models: TModels;
+  readonly valueObjects?: Record<string, ContractValueObject>;
+}
+
+/**
+ * Application-domain envelope: entity content keyed by namespace id.
+ * Mirrors the storage plane's `namespaces` segment (ADR 221).
+ */
+export interface ApplicationDomain<
+  TModels extends Record<string, ContractModelBase> = Record<string, ContractModelBase>,
+> {
+  readonly namespaces: Readonly<Record<string, ApplicationDomainNamespace<TModels>>>;
+}
+
+export type ContractWithDomain = {
+  readonly domain: ApplicationDomain;
+};
+
+export function resolveSingleDomainNamespaceId(
+  domain: ApplicationDomain,
+  namespaceId?: string,
+): string {
+  if (namespaceId !== undefined) {
+    if (!Object.hasOwn(domain.namespaces, namespaceId)) {
+      throw new DomainNamespaceResolutionError(
+        `domain namespace "${namespaceId}" is not present on the contract`,
+      );
+    }
+    return namespaceId;
+  }
+
+  const namespaceIds = Object.keys(domain.namespaces);
+  if (namespaceIds.length === 0) {
+    throw new DomainNamespaceResolutionError('domain has no namespaces');
+  }
+  if (namespaceIds.length > 1) {
+    throw new DomainNamespaceResolutionError(
+      `expected exactly one domain namespace, found ${namespaceIds.length} (${namespaceIds.join(', ')})`,
+    );
+  }
+  const [soleNamespaceId] = namespaceIds;
+  if (soleNamespaceId === undefined) {
+    throw new DomainNamespaceResolutionError('domain has no namespaces');
+  }
+  return soleNamespaceId;
+}
+
+// Transitional single-namespace projection; pending runtime-qualification slice.
+export function contractModels<TModels extends Record<string, ContractModelBase>>(
+  contract: { readonly domain: ApplicationDomain<TModels> },
+  namespaceId?: string,
+): TModels {
+  const resolved = resolveSingleDomainNamespaceId(contract.domain, namespaceId);
+  const domainNamespace = contract.domain.namespaces[resolved];
+  if (domainNamespace === undefined) {
+    throw new DomainNamespaceResolutionError(
+      `domain namespace "${resolved}" is not present on the contract`,
+    );
+  }
+  return domainNamespace.models;
+}
+
+export function contractValueObjects<TModels extends Record<string, ContractModelBase>>(
+  contract: { readonly domain: ApplicationDomain<TModels> },
+  namespaceId?: string,
+): Record<string, ContractValueObject> | undefined {
+  const resolved = resolveSingleDomainNamespaceId(contract.domain, namespaceId);
+  const domainNamespace = contract.domain.namespaces[resolved];
+  if (domainNamespace === undefined) {
+    throw new DomainNamespaceResolutionError(
+      `domain namespace "${resolved}" is not present on the contract`,
+    );
+  }
+  return domainNamespace.valueObjects;
+}

package/src/domain-types.ts

@@ -1,3 +1,5 @@
+import type { CrossReference } from './cross-reference';
+
 export type ScalarFieldType = {
   readonly kind: 'scalar';
   readonly codecId: string;
@@ -29,13 +31,13 @@ export type ContractRelationOn = {
 };
 
 export type ContractReferenceRelation = {
-  readonly to: string;
+  readonly to: CrossReference;
   readonly cardinality: '1:1' | '1:N' | 'N:1';
   readonly on: ContractRelationOn;
 };
 
 export type ContractEmbedRelation = {
-  readonly to: string;
+  readonly to: CrossReference;
   readonly cardinality: '1:1' | '1:N';
 };
 
@@ -61,7 +63,7 @@ export interface ContractModelBase<TModelStorage extends ModelStorageBase = Mode
   readonly storage: TModelStorage;
   readonly discriminator?: ContractDiscriminator;
   readonly variants?: Record<string, ContractVariantEntry>;
-  readonly base?: string;
+  readonly base?: CrossReference;
   readonly owner?: string;
 }
 
@@ -72,24 +74,20 @@ export interface ContractModel<TModelStorage extends ModelStorageBase = ModelSto
 
 // ── Relation key helpers ─────────────────────────────────────────────────────
 
-type HasModelsWithRelations = {
-  readonly models: Record<string, { readonly relations: Record<string, ContractRelation> }>;
-};
-
 export type ReferenceRelationKeys<
-  TContract extends HasModelsWithRelations,
-  ModelName extends string & keyof TContract['models'],
+  TModels extends Record<string, { readonly relations: Record<string, ContractRelation> }>,
+  ModelName extends string & keyof TModels,
 > = {
-  [K in keyof TContract['models'][ModelName]['relations']]: TContract['models'][ModelName]['relations'][K] extends ContractReferenceRelation
+  [K in keyof TModels[ModelName]['relations']]: TModels[ModelName]['relations'][K] extends ContractReferenceRelation
     ? K
     : never;
-}[keyof TContract['models'][ModelName]['relations']];
+}[keyof TModels[ModelName]['relations']];
 
 export type EmbedRelationKeys<
-  TContract extends HasModelsWithRelations,
-  ModelName extends string & keyof TContract['models'],
+  TModels extends Record<string, { readonly relations: Record<string, ContractRelation> }>,
+  ModelName extends string & keyof TModels,
 > = {
-  [K in keyof TContract['models'][ModelName]['relations']]: TContract['models'][ModelName]['relations'][K] extends ContractReferenceRelation
+  [K in keyof TModels[ModelName]['relations']]: TModels[ModelName]['relations'][K] extends ContractReferenceRelation
     ? never
     : K;
-}[keyof TContract['models'][ModelName]['relations']];
+}[keyof TModels[ModelName]['relations']];

package/src/exports/contract-validation-error.ts

@@ -1,4 +1,5 @@
 export {
   ContractValidationError,
   type ContractValidationPhase,
+  DomainNamespaceResolutionError,
 } from '../contract-validation-error';

package/src/exports/hashing-utils.ts

@@ -0,0 +1,12 @@
+export {
+  createPreserveEmptyPredicate,
+  matchesPathPattern,
+  type PathPattern,
+  type PathSegment as PreserveEmptyPathSegment,
+} from '../canonicalization-path-match';
+export {
+  compareByNameProperty,
+  createStorageSort,
+  type NamedArraySortTarget,
+  type PathSegment as StorageSortPathSegment,
+} from '../canonicalization-storage-sort';

package/src/exports/hashing.ts

@@ -2,6 +2,8 @@ export {
   type CanonicalizeContractOptions,
   canonicalizeContract,
   canonicalizeContractToObject,
+  type PreserveEmptyPredicate,
   type SerializeContract,
+  type StorageSort,
 } from '../canonicalization';
 export { computeExecutionHash, computeProfileHash, computeStorageHash } from '../hashing';

package/src/exports/types.ts

@@ -1,4 +1,23 @@
-export type { Contract, ContractExecutionSection } from '../contract-types';
+export type {
+  Contract,
+  ContractExecutionSection,
+  ContractModelsMap,
+  ContractValueObjectsMap,
+} from '../contract-types';
+export { DomainNamespaceResolutionError } from '../contract-validation-error';
+export type { CrossReference } from '../cross-reference';
+export { CrossReferenceSchema, crossRef } from '../cross-reference';
+export type {
+  ApplicationDomain,
+  ApplicationDomainNamespace,
+  ContractWithDomain,
+} from '../domain-envelope';
+export {
+  contractModels,
+  contractValueObjects,
+  resolveSingleDomainNamespaceId,
+  UNBOUND_DOMAIN_NAMESPACE_ID,
+} from '../domain-envelope';
 export type {
   ContractDiscriminator,
   ContractEmbedRelation,
@@ -18,6 +37,8 @@ export type {
   UnionFieldType,
   ValueObjectFieldType,
 } from '../domain-types';
+export type { NamespaceId } from '../namespace-id';
+export { asNamespaceId } from '../namespace-id';
 export type {
   $,
   Brand,
@@ -41,7 +62,9 @@ export type {
   ProfileHashBase,
   Source,
   StorageBase,
+  StorageEntitySlot,
   StorageHashBase,
+  StorageNamespace,
 } from '../types';
 export {
   coreHash,

package/src/hashing.ts

@@ -1,6 +1,11 @@
 import { createHash } from 'node:crypto';
+import { ifDefined } from '@prisma-next/utils/defined';
 import type { JsonObject } from '@prisma-next/utils/json';
-import { canonicalizeContract } from './canonicalization';
+import {
+  canonicalizeContract,
+  type PreserveEmptyPredicate,
+  type StorageSort,
+} from './canonicalization';
 import type { Contract } from './contract-types';
 import type { ExecutionHashBase, ProfileHashBase, StorageHashBase } from './types';
 
@@ -12,7 +17,13 @@ function sha256(content: string): string {
   return `sha256:${hash.digest('hex')}`;
 }
 
-function hashContract(section: Record<string, unknown>): string {
+type HashContractSection = Record<string, unknown> & {
+  readonly shouldPreserveEmpty?: PreserveEmptyPredicate;
+  readonly sortStorage?: StorageSort;
+};
+
+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 /
@@ -20,29 +31,35 @@ function hashContract(section: Record<string, unknown>): string {
   // missing precise Contract typing on the other slots is
   // immaterial for the hash result.
   const contract = {
-    targetFamily: section['targetFamily'],
-    target: section['target'],
+    targetFamily: sectionData['targetFamily'],
+    target: sectionData['target'],
     roots: {},
-    models: {},
-    storage: section['storage'] ?? {},
-    execution: section['execution'],
+    domain: { namespaces: {} },
+    storage: sectionData['storage'] ?? {},
+    execution: sectionData['execution'],
     extensionPacks: {},
-    capabilities: section['capabilities'] ?? {},
+    capabilities: sectionData['capabilities'] ?? {},
     meta: {},
     profileHash: '',
-    ...section,
+    ...sectionData,
   } as unknown as Contract;
   return canonicalizeContract(contract, {
     schemaVersion: SCHEMA_VERSION,
     serializeContract: (c) => JSON.parse(JSON.stringify(c)) as JsonObject,
+    ...ifDefined('shouldPreserveEmpty', shouldPreserveEmpty),
+    ...ifDefined('sortStorage', sortStorage),
   });
 }
 
-export function computeStorageHash(args: {
+export type ComputeStorageHashArgs = {
   target: string;
   targetFamily: string;
   storage: Record<string, unknown>;
-}): StorageHashBase<string> {
+  readonly shouldPreserveEmpty?: PreserveEmptyPredicate;
+  readonly sortStorage?: StorageSort;
+};
+
+export function computeStorageHash(args: ComputeStorageHashArgs): StorageHashBase<string> {
   return sha256(hashContract(args)) as StorageHashBase<string>;
 }
 

package/src/namespace-id.ts

@@ -0,0 +1,10 @@
+import { blindCast } from '@prisma-next/utils/casts';
+
+export type NamespaceId = string & { readonly __brand: 'NamespaceId' };
+
+export function asNamespaceId(value: string): NamespaceId {
+  return blindCast<
+    NamespaceId,
+    'NamespaceId is a compile-time-only brand on string; this factory is the sole assertion site'
+  >(value);
+}

package/src/types.ts

@@ -48,13 +48,34 @@ export function profileHash<const T extends string>(value: T): ProfileHashBase<T
   return value as ProfileHashBase<T>;
 }
 
+/**
+ * One entity-kind slot in a namespace — a map of entity name to entry.
+ * Values are opaque at the foundation layer; family and target concretions
+ * refine them to typed IR classes.
+ */
+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.
+ */
+export interface StorageNamespace {
+  readonly id: string;
+}
+
 /**
  * Base type for family-specific storage blocks.
  * Family storage types (SqlStorage, MongoStorage, etc.) extend this to carry the
  * storage hash alongside family-specific data (tables, collections, etc.).
+ *
+ * The `namespaces` map is carried by every hydrated storage block. Serialized
+ * envelope shape is target-owned; this types the in-memory contract after
+ * `deserializeContract`.
  */
 export interface StorageBase<THash extends string = string> {
   readonly storageHash: StorageHashBase<THash>;
+  readonly namespaces: Readonly<Record<string, StorageNamespace>>;
 }
 
 export interface FieldType {