@prisma-next/framework-components 0.5.0-dev.6 → 0.5.0-dev.61

package/src/{control-migration-types.ts → control/control-migration-types.ts}

@@ -11,8 +11,8 @@
 
 import type { Contract } from '@prisma-next/contract/types';
 import type { Result } from '@prisma-next/utils/result';
+import type { TargetBoundComponentDescriptor } from '../shared/framework-components';
 import type { ControlDriverInstance, ControlFamilyInstance } from './control-instances';
-import type { TargetBoundComponentDescriptor } from './framework-components';
 
 // ============================================================================
 // Operation Classes and Policy
@@ -28,61 +28,23 @@ import type { TargetBoundComponentDescriptor } from './framework-components';
 export type MigrationOperationClass = 'additive' | 'widening' | 'destructive' | 'data';
 
 // ============================================================================
-// Data Transform Operation
+// Serialized Query Plan
 // ============================================================================
 
 /**
  * A lowered query statement as stored in ops.json.
  * Contains the SQL string and parameter values — ready for execution.
  * Lowering from query builder AST to SQL happens at verify time.
+ *
+ * The Postgres `dataTransform` factory uses this shape internally to
+ * carry the user's lowered `check`/`run` plans before wrapping them
+ * into precheck/execute/postcheck steps on the unified migration op.
  */
 export interface SerializedQueryPlan {
   readonly sql: string;
   readonly params: readonly unknown[];
 }
 
-/**
- * A data transform operation within a migration edge.
- *
- * Data transforms are authored in TypeScript using the query builder,
- * serialized to JSON ASTs at verification time, and rendered to SQL
- * by the target adapter at apply time.
- *
- * The `name` serves as the invariant identity — it's recorded in the
- * ledger and used for invariant-aware routing via environment refs.
- *
- * In draft state (before verification), `check` and `run` are null.
- * After verification, they contain the serialized query ASTs.
- */
-export interface DataTransformOperation extends MigrationPlanOperation {
-  readonly operationClass: 'data';
-  /**
-   * The invariant name for this data transform.
-   * Recorded in the ledger on successful edge completion.
-   * Used by environment refs to declare required invariants.
-   */
-  readonly name: string;
-  /**
-   * Path to the TypeScript source file that produced this operation.
-   * Not part of edgeId computation — for traceability only.
-   */
-  readonly source: string;
-  /**
-   * Serialized check query plan, or a boolean literal.
-   * - SerializedQueryPlan: describes violations; empty result = already applied.
-   * - false: always run (no check).
-   * - true: always skip.
-   * - null: not yet serialized (draft state).
-   */
-  readonly check: SerializedQueryPlan | boolean | null;
-  /**
-   * Serialized run query plans.
-   * - Array of serialized query plans to execute sequentially.
-   * - null: not yet serialized (draft state).
-   */
-  readonly run: readonly SerializedQueryPlan[] | null;
-}
-
 /**
  * Policy defining which operation classes are allowed during a migration.
  */
@@ -105,6 +67,17 @@ export interface MigrationPlanOperation {
   readonly label: string;
   /** The class of operation (additive, widening, destructive). */
   readonly operationClass: MigrationOperationClass;
+  /**
+   * Optional opt-in routing identity for data-transform operations.
+   * Presence opts the transform into invariant-aware routing; absence
+   * means it is path-dependent and not referenceable from refs.
+   *
+   * Lives on the base op so the manifest emitter and
+   * `deriveProvidedInvariants` can read it without depending on a
+   * target-specific shape. Schema-DDL ops (additive / widening /
+   * destructive) leave it undefined.
+   */
+  readonly invariantId?: string;
 }
 
 // ============================================================================
@@ -151,6 +124,17 @@ export interface MigrationPlan {
   };
   /** Ordered list of operations to execute. */
   readonly operations: readonly MigrationPlanOperation[];
+  /**
+   * Sorted, deduplicated invariant ids declared by this plan's data-transform
+   * ops. Authored migrations carry the canonical value from
+   * `migration.json.providedInvariants`; planner-built plans (`db init`,
+   * `db update`) omit it (the runner treats it as `[]`). Runners read this
+   * field for marker writes and self-edge no-op detection rather than
+   * re-deriving from `operations`, since the manifest is the canonical
+   * source for the invariant set across all runners (postgres, sqlite,
+   * mongo).
+   */
+  readonly providedInvariants?: readonly string[];
 }
 
 /**
@@ -289,21 +273,23 @@ export interface MigrationPlanner<
     readonly contract: unknown;
     readonly schema: unknown;
     readonly policy: MigrationOperationPolicy;
-    /**
-     * Storage hash of the "from" contract (the state the planner assumes the
-     * database starts at). Planners use this to populate `describe()` on the
-     * produced plan so the rendered `migration.ts` has correct `from`/`to`
-     * metadata.
-     */
-    readonly fromHash: string;
     /**
      * The "from" contract (the state the planner assumes the database starts
-     * at). Planners pass this to data-safety strategies so they can compare
-     * `from` and `to` column shapes (e.g. to detect unsafe type changes).
-     * `db update` / `db init` reconcile against the live schema and have no
-     * "from" contract; only `migration plan` provides one.
+     * at), or `null` for a baseline plan with no prior state.
+     *
+     * Planners derive any "from" identity they need to stamp onto the
+     * produced plan's `describe()` from `fromContract?.storage.storageHash
+     * ?? null`. They also pass this to data-safety strategies so they can
+     * compare `from` and `to` column shapes (e.g. to detect unsafe type
+     * changes).
+     *
+     * Required at every call site to make the structural fact "I have a
+     * prior contract / I don't" visible in the type. Reconciliation
+     * commands (`db init`, `db update`) introspect a live schema and pass
+     * `null`; authoring commands (`migration plan`) pass the previous
+     * bundle's `metadata.toContract`.
      */
-    readonly fromContract?: unknown;
+    readonly fromContract: Contract | null;
     /**
      * Active framework components participating in this composition.
      * Families/targets can interpret this list to derive family-specific metadata.
@@ -335,6 +321,16 @@ export interface MigrationRunner<
   TFamilyId extends string = string,
   TTargetId extends string = string,
 > {
+  /**
+   * Execute a migration plan against the configured driver.
+   *
+   * The `plan` parameter is trusted input. Callers are responsible for
+   * upstream verification of the originating migration package — typically
+   * by obtaining the package via `readMigrationPackage` from
+   * `@prisma-next/migration-tools/io`, which performs hash-integrity checks
+   * at the load boundary. Runners do not re-verify the plan and assume the
+   * `(metadata, ops)` pair on disk has not been tampered with since emit.
+   */
   execute(options: {
     readonly plan: MigrationPlan;
     readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
@@ -414,11 +410,12 @@ export interface MigrationScaffoldContext {
   /** Absolute path to the contract.json file, if one exists. Used by targets that emit typed-contract imports. */
   readonly contractJsonPath?: string;
   /**
-   * Storage hash of the "from" contract. Targets use this to populate
-   * `describe()` on the rendered empty migration so that identity metadata
-   * is correctly populated.
+   * Storage hash of the "from" contract, or `null` for a baseline scaffold
+   * with no prior state. Targets use this to populate `describe()` on the
+   * rendered empty migration so that identity metadata is correctly
+   * populated.
    */
-  readonly fromHash: string;
+  readonly fromHash: string | null;
   /**
    * Storage hash of the "to" contract. Same purpose as `fromHash` — threaded
    * through so the rendered class's `describe()` declares the correct

package/src/control/control-operation-preview.ts

@@ -0,0 +1,23 @@
+/**
+ * Family-agnostic textual preview of a migration plan, used by the CLI to
+ * render a "DDL preview" section for `db init` / `db update` / `migration plan`
+ * / `migration show`. Each statement carries a free-form `language` tag so
+ * formatters can suffix `;` for SQL but render Mongo shell lines verbatim.
+ *
+ * Producers are family-specific: SQL emits `language: 'sql'` (existing DDL
+ * extraction); Mongo emits `language: 'mongodb-shell'` via the
+ * `MongoDdlCommandFormatter` visitor.
+ *
+ * The capability `OperationPreviewCapable` (declared in
+ * `./control-capabilities`) is how a family announces it can produce these.
+ */
+
+export interface OperationPreviewStatement {
+  readonly text: string;
+  /** Dialect identifier, e.g. `'sql'`, `'mongodb-shell'`. Free-form by design (OQ-3). */
+  readonly language: string;
+}
+
+export interface OperationPreview {
+  readonly statements: readonly OperationPreviewStatement[];
+}

package/src/{control-stack.ts → control/control-stack.ts}

@@ -1,25 +1,30 @@
-import type { CodecLookup } from './codec-types';
-import type {
-  ControlAdapterDescriptor,
-  ControlDriverDescriptor,
-  ControlExtensionDescriptor,
-  ControlFamilyDescriptor,
-  ControlTargetDescriptor,
-} from './control-descriptors';
+import type { Codec } from '../shared/codec';
+import type { CodecLookup, CodecMeta } from '../shared/codec-types';
 import type {
   AuthoringContributions,
   AuthoringFieldNamespace,
-  AuthoringFieldPresetDescriptor,
-  AuthoringTypeConstructorDescriptor,
   AuthoringTypeNamespace,
-} from './framework-authoring';
-import type { ComponentMetadata } from './framework-components';
+} from '../shared/framework-authoring';
+import {
+  assertNoCrossRegistryCollisions,
+  isAuthoringFieldPresetDescriptor,
+  isAuthoringTypeConstructorDescriptor,
+  mergeAuthoringNamespaces,
+} from '../shared/framework-authoring';
+import type { ComponentMetadata } from '../shared/framework-components';
 import type {
   ControlMutationDefaultEntry,
   ControlMutationDefaults,
   MutationDefaultGeneratorDescriptor,
-} from './mutation-default-types';
-import type { TypesImportSpec } from './types-import-spec';
+} from '../shared/mutation-default-types';
+import type { TypesImportSpec } from '../shared/types-import-spec';
+import type {
+  ControlAdapterDescriptor,
+  ControlDriverDescriptor,
+  ControlExtensionDescriptor,
+  ControlFamilyDescriptor,
+  ControlTargetDescriptor,
+} from './control-descriptors';
 
 export interface AssembledAuthoringContributions {
   readonly field: AuthoringFieldNamespace;
@@ -153,70 +158,6 @@ export function extractComponentIds(
   return ids;
 }
 
-function isTypeConstructorDescriptor(value: unknown): value is AuthoringTypeConstructorDescriptor {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    (value as { kind?: unknown }).kind === 'typeConstructor'
-  );
-}
-
-function isFieldPresetDescriptor(value: unknown): value is AuthoringFieldPresetDescriptor {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    (value as { kind?: unknown }).kind === 'fieldPreset'
-  );
-}
-
-function mergeAuthoringNamespaces(
-  target: Record<string, unknown>,
-  source: Record<string, unknown>,
-  path: readonly string[],
-  leafGuard: (value: unknown) => boolean,
-  label: string,
-): void {
-  const assertSafePath = (currentPath: readonly string[]) => {
-    const blockedSegment = currentPath.find(
-      (segment) => segment === '__proto__' || segment === 'constructor' || segment === 'prototype',
-    );
-    if (blockedSegment) {
-      throw new Error(
-        `Invalid authoring ${label} helper "${currentPath.join('.')}". Helper path segments must not use "${blockedSegment}".`,
-      );
-    }
-  };
-
-  for (const [key, sourceValue] of Object.entries(source)) {
-    const currentPath = [...path, key];
-    assertSafePath(currentPath);
-    const hasExistingValue = Object.hasOwn(target, key);
-    const existingValue = hasExistingValue ? target[key] : undefined;
-
-    if (!hasExistingValue) {
-      target[key] = sourceValue;
-      continue;
-    }
-
-    const existingIsLeaf = leafGuard(existingValue);
-    const sourceIsLeaf = leafGuard(sourceValue);
-
-    if (existingIsLeaf || sourceIsLeaf) {
-      throw new Error(
-        `Duplicate authoring ${label} helper "${currentPath.join('.')}". Descriptor contributions must be unique across composed components.`,
-      );
-    }
-
-    mergeAuthoringNamespaces(
-      existingValue as Record<string, unknown>,
-      sourceValue as Record<string, unknown>,
-      currentPath,
-      leafGuard,
-      label,
-    );
-  }
-}
-
 export function assembleAuthoringContributions(
   descriptors: ReadonlyArray<{ readonly authoring?: AuthoringContributions }>,
 ): AssembledAuthoringContributions {
@@ -229,7 +170,7 @@ export function assembleAuthoringContributions(
         field,
         descriptor.authoring.field,
         [],
-        isFieldPresetDescriptor,
+        isAuthoringFieldPresetDescriptor,
         'field',
       );
     }
@@ -240,14 +181,18 @@ export function assembleAuthoringContributions(
       type,
       descriptor.authoring.type,
       [],
-      isTypeConstructorDescriptor,
+      isAuthoringTypeConstructorDescriptor,
       'type',
     );
   }
 
+  const fieldNamespace = field as AuthoringFieldNamespace;
+  const typeNamespace = type as AuthoringTypeNamespace;
+  assertNoCrossRegistryCollisions(typeNamespace, fieldNamespace);
+
   return {
-    field: field as AuthoringFieldNamespace,
-    type: type as AuthoringTypeNamespace,
+    field: fieldNamespace,
+    type: typeNamespace,
   };
 }
 
@@ -326,27 +271,65 @@ export function assembleControlMutationDefaults(
 }
 
 export function extractCodecLookup(
-  descriptors: ReadonlyArray<Pick<ComponentMetadata & { id?: string }, 'types' | 'id'>>,
+  descriptors: ReadonlyArray<Pick<ComponentMetadata & { id: string }, 'types' | 'id'>>,
 ): CodecLookup {
-  const byId = new Map<string, import('./codec-types').Codec>();
+  const byId = new Map<string, Codec>();
+  const targetTypesById = new Map<string, readonly string[]>();
+  const metaById = new Map<string, CodecMeta>();
+  const renderersById = new Map<string, (params: Record<string, unknown>) => string | undefined>();
   const owners = new Map<string, string>();
   for (const descriptor of descriptors) {
-    const codecInstances = descriptor.types?.codecTypes?.codecInstances;
-    if (!codecInstances) continue;
-    const descriptorId = descriptor.id ?? '<unknown>';
-    for (const codec of codecInstances) {
+    const codecTypes = descriptor.types?.codecTypes;
+    const descriptorId = descriptor.id;
+    // Descriptor-side metadata is the single source of truth for `targetTypes` / `meta` / `renderOutputType`. Every contributor ships a `codecDescriptors` list on `types.codecTypes`.
+    for (const codecDescriptor of codecTypes?.codecDescriptors ?? []) {
       assertUniqueCodecOwner({
-        codecId: codec.id,
+        codecId: codecDescriptor.codecId,
         owners,
         descriptorId,
-        entityLabel: 'codec instance',
-        entityOwnershipLabel: 'codec instance provider',
+        entityLabel: 'codec descriptor',
+        entityOwnershipLabel: 'codec descriptor provider',
       });
-      owners.set(codec.id, descriptorId);
-      byId.set(codec.id, codec);
+      owners.set(codecDescriptor.codecId, descriptorId);
+      if (Array.isArray(codecDescriptor.targetTypes)) {
+        targetTypesById.set(codecDescriptor.codecId, codecDescriptor.targetTypes);
+      }
+      if (codecDescriptor.meta !== undefined) {
+        metaById.set(codecDescriptor.codecId, codecDescriptor.meta);
+      }
+      if (typeof codecDescriptor.renderOutputType === 'function') {
+        renderersById.set(codecDescriptor.codecId, codecDescriptor.renderOutputType);
+      }
+      // Materialize a representative `Codec` instance for `byId.get()` so consumers reading the lookup's instance side (e.g. SQL renderer's cast-policy lookup, or the contract emitter's literal-default `encodeJson` resolver) keep finding the codec.
+      //
+      // Two cohorts:
+      // - Non-parameterized descriptors: factory must succeed; any throw is a real bug and we let it propagate (no silent try/catch).
+      // - Parameterized descriptors: try with empty params. Many parameterized codecs treat params as advisory (e.g. `pg/timestamptz@1` whose precision is rendered into the `nativeType` only and never read by the runtime codec), so an empty-params construction yields a usable representative for id-keyed lookups (e.g. emit-time literal-default encoding). Codecs whose factory genuinely requires params (e.g. `pg/vector@1` threading `length` into the runtime codec) will throw; for those, per-column instances are materialized at runtime by `buildContractCodecRegistry` and the id-keyed lookup miss is correct (the column-aware path resolves them).
+      if (!byId.has(codecDescriptor.codecId)) {
+        if (codecDescriptor.isParameterized) {
+          try {
+            const representative = codecDescriptor.factory({} as never)({
+              name: `<lookup:${codecDescriptor.codecId}>`,
+            } as Parameters<ReturnType<typeof codecDescriptor.factory>>[0]);
+            byId.set(codecDescriptor.codecId, representative);
+          } catch {
+            // Factory requires concrete params; skip representative materialization. Per-column instances are built at runtime; id-keyed lookup miss is the correct outcome here.
+          }
+        } else {
+          const representative = codecDescriptor.factory(undefined as never)({
+            name: `<lookup:${codecDescriptor.codecId}>`,
+          } as Parameters<ReturnType<typeof codecDescriptor.factory>>[0]);
+          byId.set(codecDescriptor.codecId, representative);
+        }
+      }
     }
   }
-  return { get: (id) => byId.get(id) };
+  return {
+    get: (id) => byId.get(id),
+    targetTypesFor: (id) => targetTypesById.get(id),
+    metaFor: (id) => metaById.get(id),
+    renderOutputTypeFor: (id, params) => renderersById.get(id)?.(params),
+  };
 }
 
 export function validateScalarTypeCodecIds(

package/src/control/emission-types.ts

@@ -0,0 +1,49 @@
+import type { Contract, ContractModel } from '@prisma-next/contract/types';
+import type { TypesImportSpec } from '../shared/types-import-spec';
+
+export interface GenerateContractTypesOptions {
+  readonly queryOperationTypeImports?: ReadonlyArray<TypesImportSpec>;
+}
+
+export interface ValidationContext {
+  readonly codecTypeImports?: ReadonlyArray<TypesImportSpec>;
+  readonly operationTypeImports?: ReadonlyArray<TypesImportSpec>;
+  readonly extensionIds?: ReadonlyArray<string>;
+}
+
+export interface EmissionSpi {
+  readonly id: string;
+
+  generateStorageType(contract: Contract, storageHashTypeName: string): string;
+
+  generateModelStorageType(modelName: string, model: ContractModel): string;
+
+  getFamilyImports(): string[];
+
+  getFamilyTypeAliases(options?: GenerateContractTypesOptions): string;
+
+  getTypeMapsExpression(): string;
+
+  getContractWrapper(contractBaseName: string, typeMapsName: string): string;
+
+  /**
+   * Per-family resolver for typeParams that don't live inline on the
+   * framework-domain `ContractField`. Some families (notably SQL) let columns
+   * reference a named entry in `storage.types` via `typeRef`; the typeParams
+   * live on that named entry rather than on the domain field. The framework
+   * emit path consults this hook so the codec's `renderOutputType` can run
+   * for typeRef-shaped columns.
+   *
+   * Inline `field.type.typeParams` always takes precedence; the hook is only
+   * consulted when the domain field has no typeParams. Families without
+   * named storage types (e.g. mongo) don't implement this hook.
+   *
+   * Returns `undefined` when the field has no resolvable typeParams.
+   */
+  resolveFieldTypeParams?(
+    modelName: string,
+    fieldName: string,
+    model: ContractModel,
+    contract: Contract,
+  ): Record<string, unknown> | undefined;
+}

package/src/control/psl-ast.ts

@@ -0,0 +1,193 @@
+export interface PslPosition {
+  readonly offset: number;
+  readonly line: number;
+  readonly column: number;
+}
+
+export interface PslSpan {
+  readonly start: PslPosition;
+  readonly end: PslPosition;
+}
+
+export type PslDiagnosticCode =
+  | 'PSL_UNTERMINATED_BLOCK'
+  | 'PSL_UNSUPPORTED_TOP_LEVEL_BLOCK'
+  | 'PSL_INVALID_ATTRIBUTE_SYNTAX'
+  | 'PSL_INVALID_MODEL_MEMBER'
+  | 'PSL_UNSUPPORTED_MODEL_ATTRIBUTE'
+  | 'PSL_UNSUPPORTED_FIELD_ATTRIBUTE'
+  | 'PSL_INVALID_RELATION_ATTRIBUTE'
+  | 'PSL_INVALID_REFERENTIAL_ACTION'
+  | 'PSL_INVALID_DEFAULT_VALUE'
+  | 'PSL_INVALID_ENUM_MEMBER'
+  | 'PSL_INVALID_TYPES_MEMBER';
+
+export interface PslDiagnostic {
+  readonly code: PslDiagnosticCode;
+  readonly message: string;
+  readonly sourceId: string;
+  readonly span: PslSpan;
+}
+
+export interface PslDefaultFunctionValue {
+  readonly kind: 'function';
+  readonly name: 'autoincrement' | 'now';
+}
+
+export interface PslDefaultLiteralValue {
+  readonly kind: 'literal';
+  readonly value: string | number | boolean;
+}
+
+export type PslDefaultValue = PslDefaultFunctionValue | PslDefaultLiteralValue;
+
+export type PslAttributeTarget = 'field' | 'model' | 'enum' | 'namedType';
+
+export interface PslAttributePositionalArgument {
+  readonly kind: 'positional';
+  readonly value: string;
+  readonly span: PslSpan;
+}
+
+export interface PslAttributeNamedArgument {
+  readonly kind: 'named';
+  readonly name: string;
+  readonly value: string;
+  readonly span: PslSpan;
+}
+
+export type PslAttributeArgument = PslAttributePositionalArgument | PslAttributeNamedArgument;
+
+export interface PslTypeConstructorCall {
+  readonly kind: 'typeConstructor';
+  readonly path: readonly string[];
+  readonly args: readonly PslAttributeArgument[];
+  readonly span: PslSpan;
+}
+
+export interface PslAttribute {
+  readonly kind: 'attribute';
+  readonly target: PslAttributeTarget;
+  readonly name: string;
+  readonly args: readonly PslAttributeArgument[];
+  readonly span: PslSpan;
+}
+
+export type PslReferentialAction = string;
+
+export type PslFieldAttribute = PslAttribute;
+
+export interface PslField {
+  readonly kind: 'field';
+  readonly name: string;
+  readonly typeName: string;
+  readonly typeConstructor?: PslTypeConstructorCall;
+  readonly optional: boolean;
+  readonly list: boolean;
+  readonly typeRef?: string;
+  readonly attributes: readonly PslFieldAttribute[];
+  readonly span: PslSpan;
+}
+
+export interface PslUniqueConstraint {
+  readonly kind: 'unique';
+  readonly fields: readonly string[];
+  readonly span: PslSpan;
+}
+
+export interface PslIndexConstraint {
+  readonly kind: 'index';
+  readonly fields: readonly string[];
+  readonly span: PslSpan;
+}
+
+export type PslModelAttribute = PslAttribute;
+
+export interface PslModel {
+  readonly kind: 'model';
+  readonly name: string;
+  readonly fields: readonly PslField[];
+  readonly attributes: readonly PslModelAttribute[];
+  readonly span: PslSpan;
+  /**
+   * Optional leading comment line emitted above the `model` keyword by the
+   * printer. Producers (e.g. `sqlSchemaIrToPslAst`) attach introspection
+   * advisories such as "// WARNING: This table has no primary key in the
+   * database" here. The parser leaves this field unset; round-tripping a
+   * parsed schema does not re-attach comments.
+   */
+  readonly comment?: string;
+}
+
+export interface PslEnumValue {
+  readonly kind: 'enumValue';
+  readonly name: string;
+  /**
+   * Optional storage label for the enum member, captured from a trailing
+   * `@map("...")` attribute on the member line. The parser populates this
+   * when the source PSL carries an explicit `@map`. Producers (e.g.
+   * `sqlSchemaIrToPslAst`) leave it unset; the printer emits `@map(...)`
+   * automatically when normalisation would change the printed member name
+   * (so an enum value `'in-progress'` becomes `inProgress @map("in-progress")`
+   * in PSL, preserving the round-trip).
+   */
+  readonly mapName?: string;
+  readonly span: PslSpan;
+}
+
+export interface PslEnum {
+  readonly kind: 'enum';
+  readonly name: string;
+  readonly values: readonly PslEnumValue[];
+  readonly attributes: readonly PslAttribute[];
+  readonly span: PslSpan;
+}
+
+export interface PslCompositeType {
+  readonly kind: 'compositeType';
+  readonly name: string;
+  readonly fields: readonly PslField[];
+  readonly attributes: readonly PslAttribute[];
+  readonly span: PslSpan;
+}
+
+export interface PslNamedTypeDeclaration {
+  readonly kind: 'namedType';
+  readonly name: string;
+  /**
+   * Parser invariant: exactly one of `baseType` and `typeConstructor` is set.
+   * Expressing this as a discriminated union trips TypeScript narrowing when
+   * the declaration flows through helpers that accept the full union.
+   */
+  readonly baseType?: string;
+  readonly typeConstructor?: PslTypeConstructorCall;
+  readonly attributes: readonly PslAttribute[];
+  readonly span: PslSpan;
+}
+
+export interface PslTypesBlock {
+  readonly kind: 'types';
+  readonly declarations: readonly PslNamedTypeDeclaration[];
+  readonly span: PslSpan;
+}
+
+export interface PslDocumentAst {
+  readonly kind: 'document';
+  readonly sourceId: string;
+  readonly models: readonly PslModel[];
+  readonly enums: readonly PslEnum[];
+  readonly compositeTypes: readonly PslCompositeType[];
+  readonly types?: PslTypesBlock;
+  readonly span: PslSpan;
+}
+
+export interface ParsePslDocumentInput {
+  readonly schema: string;
+  readonly sourceId: string;
+}
+
+export interface ParsePslDocumentResult {
+  readonly ast: PslDocumentAst;
+  readonly diagnostics: readonly PslDiagnostic[];
+  readonly ok: boolean;
+}