@prisma-next/framework-components 0.12.0-dev.7 → 0.12.0-dev.70

package/src/control/verifier-disposition.ts

@@ -0,0 +1,62 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
+import type { SchemaVerificationNode } from './control-result-types';
+
+export type VerificationStatus = SchemaVerificationNode['status'];
+
+export type VerifierOutcome = VerificationStatus | 'suppress';
+
+/**
+ * Target-neutral classification of a verifier finding, abstracted away from any
+ * one storage model's vocabulary. Each family classifies its own concrete issue
+ * kinds into these categories; the framework only grades the category against a
+ * control policy.
+ *
+ * - `declaredMissing` — a declared object/element is absent from the database.
+ * - `declaredIncompatible` — a declared object/element exists but its shape diverges.
+ * - `valueDrift` — the value set of an existing type drifted (e.g. enum values).
+ * - `extraNestedElement` — an undeclared element nested inside a declared object
+ *   (a SQL column, a document field).
+ * - `extraAuxiliary` — an undeclared auxiliary attached to a declared object
+ *   (a SQL constraint/index, a Mongo index/validator).
+ * - `extraTopLevelObject` — an undeclared top-level object (a SQL table, a
+ *   Mongo collection).
+ */
+export type VerifierIssueCategory =
+  | 'declaredMissing'
+  | 'declaredIncompatible'
+  | 'valueDrift'
+  | 'extraNestedElement'
+  | 'extraAuxiliary'
+  | 'extraTopLevelObject';
+
+/**
+ * Grades a target-neutral issue category against a control policy.
+ *
+ * - `observed` warns on everything.
+ * - `tolerated` suppresses only an extra nested element (everything else fails).
+ * - `external` suppresses every extra category and value drift (existence and
+ *   declared-shape divergences still fail).
+ * - `managed` (and any other) fails.
+ */
+export function dispositionForCategory(
+  controlPolicy: ControlPolicy,
+  category: VerifierIssueCategory,
+): VerifierOutcome {
+  if (controlPolicy === 'observed') {
+    return 'warn';
+  }
+  if (controlPolicy === 'tolerated' && category === 'extraNestedElement') {
+    return 'suppress';
+  }
+  if (controlPolicy === 'external') {
+    if (
+      category === 'extraNestedElement' ||
+      category === 'extraAuxiliary' ||
+      category === 'extraTopLevelObject' ||
+      category === 'valueDrift'
+    ) {
+      return 'suppress';
+    }
+  }
+  return 'fail';
+}

package/src/exports/authoring.ts

@@ -11,6 +11,8 @@ export type {
   AuthoringFieldNamespace,
   AuthoringFieldPresetDescriptor,
   AuthoringFieldPresetOutput,
+  AuthoringPslBlockDescriptor,
+  AuthoringPslBlockDescriptorNamespace,
   AuthoringStorageTypeTemplate,
   AuthoringTemplateValue,
   AuthoringTypeConstructorDescriptor,
@@ -25,8 +27,22 @@ export {
   isAuthoringArgRef,
   isAuthoringEntityTypeDescriptor,
   isAuthoringFieldPresetDescriptor,
+  isAuthoringPslBlockDescriptor,
   isAuthoringTypeConstructorDescriptor,
   mergeAuthoringNamespaces,
   resolveAuthoringTemplateValue,
   validateAuthoringHelperArguments,
 } from '../shared/framework-authoring';
+export type {
+  PslBlockParam,
+  PslBlockParamList,
+  PslBlockParamOption,
+  PslBlockParamRef,
+  PslBlockParamValue,
+  PslExtensionBlock,
+  PslExtensionBlockParamList,
+  PslExtensionBlockParamOption,
+  PslExtensionBlockParamRef,
+  PslExtensionBlockParamScalarValue,
+  PslExtensionBlockParamValue,
+} from '../shared/psl-extension-block';

package/src/exports/control.ts

@@ -95,6 +95,7 @@ export {
   assembleControlMutationDefaults,
   assembleScalarTypeDescriptors,
   assertUniqueCodecOwner,
+  buildExtensionLoadOrder,
   createControlStack,
   extractCodecLookup,
   extractCodecTypeImports,
@@ -106,6 +107,12 @@ export type {
   SchemaVerifyOptions,
   SchemaVerifyResult,
 } from '../control/schema-verifier';
+export type {
+  VerificationStatus,
+  VerifierIssueCategory,
+  VerifierOutcome,
+} from '../control/verifier-disposition';
+export { dispositionForCategory } from '../control/verifier-disposition';
 export type {
   ControlMutationDefaultEntry,
   ControlMutationDefaultRegistry,

package/src/exports/psl-ast.ts

@@ -1 +1,3 @@
 export * from '../control/psl-ast';
+export type { ExtensionBlockRefResolutionContext } from '../control/psl-extension-block-validator';
+export { validateExtensionBlock } from '../control/psl-extension-block-validator';

package/src/ir/namespace.ts

@@ -41,28 +41,30 @@ export const UNBOUND_NAMESPACE_ID = '__unbound__' as const;
  *
  * The framework promises only the coordinate (`id`) — the named storage
  * entities a namespace contains are family-typed (SQL contributes
- * `tables`, Mongo contributes `collections`, future families pick their
- * own native idiom). Generic consumers walking "all named entries" go
- * through a family-typed namespace, not the framework `Namespace`.
+ * `table` / `type`, Mongo contributes `collection`, future families pick
+ * their own native idiom under `entries`). Generic consumers walking "all
+ * named entries" go through a family-typed namespace, not the framework
+ * `Namespace`.
  *
  * Every namespace concretion (e.g. family-built SQL namespaces,
  * `MongoUnboundNamespace`, target-promoted namespaces like
- * `PostgresSchema`) carries exactly: `id` (enumerable string), `kind`
- * (non-enumerable string discriminator set via `Object.defineProperty`),
- * and one or more entity-kind slot maps — each an own-enumerable property
- * whose key is the entity kind (`tables`, `types`, `collections`,
- * target-pack-contributed slot names) and whose value is a
- * `Record<entityName, EntityIRClass>`. No other own-enumerable data lives
- * on a namespace; non-entity computed data lives on the surrounding storage
- * or contract IR. The framework's `elementCoordinates(storage)` walk relies
- * on this invariant to enumerate entities structurally without
- * family-specific knowledge.
+ * `PostgresSchema`) carries exactly: `id` (enumerable string),
+ * `entries` (frozen object holding entity-kind slot maps), and `kind`
+ * (non-enumerable string discriminator set via `Object.defineProperty`).
+ * Each slot map under `entries` uses a singular essence key (`table`,
+ * `type`, `collection`, …) mapping entity names to IR classes. No other
+ * own-enumerable data lives on a namespace; non-entity computed data lives
+ * on the surrounding storage or contract IR. The framework's
+ * `elementCoordinates(storage)` walk relies on this invariant to enumerate
+ * entities structurally without family-specific knowledge.
  */
 export interface Namespace extends IRNode, StorageNamespace {
   readonly kind: string;
+  readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 }
 
 export abstract class NamespaceBase extends IRNodeBase implements Namespace {
   abstract readonly id: string;
+  abstract readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
   abstract override readonly kind: string;
 }

package/src/ir/storage.ts

@@ -30,18 +30,19 @@ export interface EntityCoordinate {
  * value, yielded as {@link EntityCoordinate} tuples with
  * `plane: 'storage'` (the parameter type binds the plane).
  *
- * Iterates each namespace's own-enumerable properties structurally.
- * Skips `id` (known scalar); `kind` is non-enumerable on namespace
- * concretions and does not appear in `Object.entries`. For every other
- * property whose value is a non-null object, yields one coordinate per
- * entry key in that map. No family-specific slot vocabulary is required.
+ * Iterates each namespace's `entries` slot maps structurally. Skips
+ * non-object `entries`; `id` and `kind` are not walked (`kind` is
+ * non-enumerable on concretions). For every entity-kind key under
+ * `entries` whose value is a non-null object, yields one coordinate per
+ * entity name in that map. No family-specific slot vocabulary is required.
  */
 export function* elementCoordinates(
   storage: Pick<StorageBase, 'namespaces'>,
 ): Generator<EntityCoordinate> {
   for (const [namespaceId, ns] of Object.entries(storage.namespaces)) {
-    for (const [entityKind, slot] of Object.entries(ns)) {
-      if (entityKind === 'id') continue;
+    const entries = ns.entries;
+    if (entries === null || typeof entries !== 'object') continue;
+    for (const [entityKind, slot] of Object.entries(entries)) {
       if (slot === null || typeof slot !== 'object') continue;
       for (const entityName of Object.keys(slot)) {
         yield { plane: 'storage', namespaceId, entityKind, entityName };

package/src/shared/framework-authoring.ts

@@ -7,8 +7,10 @@ import {
   isColumnDefaultLiteralInputValue,
   isExecutionMutationDefaultValue,
 } from '@prisma-next/contract/types';
+import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Type } from 'arktype';
+import type { PslBlockParam } from './psl-extension-block';
 
 export type AuthoringArgRef = {
   readonly kind: 'arg';
@@ -157,10 +159,55 @@ export type AuthoringEntityTypeNamespace = {
   readonly [name: string]: AuthoringEntityTypeDescriptor | AuthoringEntityTypeNamespace;
 };
 
+/**
+ * Declarative descriptor for an extension-contributed top-level PSL block.
+ *
+ * An extension registers one of these per keyword it contributes. The
+ * framework owns the generic parser, validator, and printer — no
+ * parsing or printing code runs from the extension.
+ *
+ * - `keyword` is the PSL top-level identifier this descriptor claims
+ *   (`policy_select`, `role`, …).
+ * - `discriminator` is the routing key used by the printer dispatch and
+ *   the `entityTypes` lowering factory lookup. Convention:
+ *   `<target-or-family>-<kind>` (`postgres-policy-select`).
+ * - `name.required` declares whether the block must have a name token
+ *   after the keyword. Currently always `true` — anonymous blocks are
+ *   not part of the closed-grammar premise — but the field is explicit
+ *   so the type can evolve without a breaking change.
+ * - `parameters` maps parameter names to their value-kind descriptors
+ *   (`ref` / `value` / `option` / `list`). The generic parser and
+ *   validator interpret these; the extension supplies no parser or
+ *   printer function.
+ */
+export interface AuthoringPslBlockDescriptor {
+  readonly kind: 'pslBlock';
+  readonly keyword: string;
+  readonly discriminator: string;
+  readonly name: { readonly required: boolean };
+  readonly parameters: Record<string, PslBlockParam>;
+}
+
+export type AuthoringPslBlockDescriptorNamespace = {
+  readonly [name: string]: AuthoringPslBlockDescriptor | AuthoringPslBlockDescriptorNamespace;
+};
+
 export interface AuthoringContributions {
   readonly type?: AuthoringTypeNamespace;
   readonly field?: AuthoringFieldNamespace;
   readonly entityTypes?: AuthoringEntityTypeNamespace;
+  /**
+   * Registry of declarative block descriptors this contribution registers,
+   * keyed by arbitrary path segments. Each leaf is an
+   * {@link AuthoringPslBlockDescriptor} that claims a PSL top-level keyword.
+   * The framework owns the generic parser, validator, and printer; the
+   * contribution supplies only these declarative descriptors.
+   *
+   * Contrast with {@link PslNamespace.extensionBlocks}: that field holds
+   * the parsed block nodes in a namespace; this field holds the registry
+   * of descriptors that teach the parser how to read those blocks.
+   */
+  readonly pslBlockDescriptors?: AuthoringPslBlockDescriptorNamespace;
 }
 
 export function isAuthoringArgRef(value: unknown): value is AuthoringArgRef {
@@ -228,6 +275,42 @@ export function isAuthoringEntityTypeDescriptor(
   return typeof factory === 'function' || template !== undefined;
 }
 
+export function isAuthoringPslBlockDescriptor(
+  value: unknown,
+): value is AuthoringPslBlockDescriptor {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const record = blindCast<
+    Record<string, unknown>,
+    'type-guard probing an unknown candidate-descriptor object for known property names'
+  >(value);
+  if (record['kind'] !== 'pslBlock') {
+    return false;
+  }
+  const keyword = record['keyword'];
+  if (typeof keyword !== 'string' || keyword.length === 0) {
+    return false;
+  }
+  const discriminator = record['discriminator'];
+  if (typeof discriminator !== 'string' || discriminator.length === 0) {
+    return false;
+  }
+  const name = record['name'];
+  if (typeof name !== 'object' || name === null) {
+    return false;
+  }
+  const nameRecord = blindCast<
+    Record<string, unknown>,
+    'type-guard probing the name property of a candidate pslBlock descriptor'
+  >(name);
+  if (typeof nameRecord['required'] !== 'boolean') {
+    return false;
+  }
+  const parameters = record['parameters'];
+  return typeof parameters === 'object' && parameters !== null && !Array.isArray(parameters);
+}
+
 /**
  * Returns true when `namespace` is a non-leaf key in `contributions.field`.
  *
@@ -341,10 +424,127 @@ function collectAuthoringLeafPaths(
   return paths;
 }
 
+interface AuthoringLeafEntry {
+  readonly path: string;
+  readonly discriminator: string;
+}
+
+function collectAuthoringLeafDiscriminators(
+  namespace: Readonly<Record<string, unknown>>,
+  isLeaf: (value: unknown) => boolean,
+  label: string,
+  path: readonly string[] = [],
+): AuthoringLeafEntry[] {
+  const entries: AuthoringLeafEntry[] = [];
+  for (const [key, value] of Object.entries(namespace)) {
+    const currentPath = [...path, key];
+    if (isLeaf(value)) {
+      const record = blindCast<
+        Record<string, unknown>,
+        'discriminator extraction from a leaf already validated by isLeaf'
+      >(value);
+      const discriminator = record['discriminator'];
+      if (typeof discriminator === 'string' && discriminator.length > 0) {
+        entries.push({ path: currentPath.join('.'), discriminator });
+      }
+      continue;
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      const record = blindCast<
+        Readonly<Record<string, unknown>>,
+        'walker inspects a non-leaf value for descriptor-shaped keys before recursing'
+      >(value);
+      // A value carrying descriptor-shaped keys (`kind`/`keyword`/`discriminator`)
+      // but failing `isAuthoringPslBlockDescriptor` (e.g. missing `parameters`) is
+      // a malformed declarative descriptor. Descending into it as a sub-namespace
+      // would silently skip it, so a half-built contribution would pass validation.
+      // Reject it at load time instead, naming the path and what's wrong.
+      //
+      // A valid sub-namespace whose key happens to be named `kind`, `keyword`, or
+      // `discriminator` (but which does not look like a descriptor overall) must
+      // still descend normally — the check requires descriptor-shaped keys present
+      // AND the leaf guard rejecting it.
+      if (
+        (record['kind'] !== undefined ||
+          record['keyword'] !== undefined ||
+          record['discriminator'] !== undefined) &&
+        !isLeaf(value)
+      ) {
+        const hasKind = record['kind'] === 'pslBlock';
+        const hasKeyword = typeof record['keyword'] === 'string';
+        const hasDiscriminator = typeof record['discriminator'] === 'string';
+        if (hasKind || (hasKeyword && hasDiscriminator)) {
+          throw new Error(
+            `Malformed authoring ${label} contribution at "${currentPath.join('.')}". The value carries descriptor keys (kind/keyword/discriminator) but does not satisfy the ${label} descriptor shape. Fix the contribution so it is a complete descriptor, or remove the stray keys if it was meant to be a sub-namespace.`,
+          );
+        }
+      }
+      entries.push(...collectAuthoringLeafDiscriminators(record, isLeaf, label, currentPath));
+    }
+  }
+  return entries;
+}
+
+/**
+ * Throws when two or more entries in the same namespace share a discriminator.
+ * Duplicate discriminators within a namespace make dispatch ambiguous — the
+ * lowering factory lookup dispatches by discriminator, so one would silently
+ * shadow the other. Catch duplicates before building any dispatch map.
+ */
+function assertUniqueDiscriminators(entries: readonly AuthoringLeafEntry[], label: string): void {
+  const seen = new Map<string, string>();
+  for (const { path, discriminator } of entries) {
+    const existing = seen.get(discriminator);
+    if (existing !== undefined) {
+      throw new Error(
+        `Duplicate ${label} discriminator "${discriminator}" registered at both "${existing}" and "${path}". Each ${label} contribution must use a unique discriminator.`,
+      );
+    }
+    seen.set(discriminator, path);
+  }
+}
+
+/**
+ * Every `pslBlockDescriptors` entry needs a matching `entityTypes` factory
+ * (same discriminator): the parser would otherwise produce an AST node
+ * nothing can lower to an IR class instance. The link is one-directional
+ * — an `entityTypes` factory may stand alone (e.g. `enum`, reachable from
+ * the TypeScript builder without any PSL block).
+ */
+function assertPslBlocksHaveFactories(
+  entityTypeNamespace: AuthoringEntityTypeNamespace,
+  pslBlockNamespace: AuthoringPslBlockDescriptorNamespace,
+): void {
+  const blockEntries = collectAuthoringLeafDiscriminators(
+    pslBlockNamespace,
+    isAuthoringPslBlockDescriptor,
+    'pslBlock',
+  );
+  const entityEntries = collectAuthoringLeafDiscriminators(
+    entityTypeNamespace,
+    isAuthoringEntityTypeDescriptor,
+    'entityType',
+  );
+
+  assertUniqueDiscriminators(blockEntries, 'pslBlock');
+  assertUniqueDiscriminators(entityEntries, 'entityType');
+
+  const entityDiscriminators = new Set(entityEntries.map((entry) => entry.discriminator));
+
+  for (const block of blockEntries) {
+    if (!entityDiscriminators.has(block.discriminator)) {
+      throw new Error(
+        `Incomplete extension contribution: pslBlock helper "${block.path}" registers discriminator "${block.discriminator}" but no entityType contribution shares that discriminator. An extension-contributed PSL block requires a matching entityType factory so the parsed AST node can lower to an IR class instance; add an entityType helper with discriminator "${block.discriminator}".`,
+      );
+    }
+  }
+}
+
 export function assertNoCrossRegistryCollisions(
   typeNamespace: AuthoringTypeNamespace,
   fieldNamespace: AuthoringFieldNamespace,
   entityTypeNamespace: AuthoringEntityTypeNamespace = {},
+  pslBlockNamespace: AuthoringPslBlockDescriptorNamespace = {},
 ): void {
   const typePaths = new Set(
     collectAuthoringLeafPaths(typeNamespace, isAuthoringTypeConstructorDescriptor),
@@ -360,20 +560,33 @@ export function assertNoCrossRegistryCollisions(
   // `mergeHelperNamespaces` in composed-authoring-helpers.ts), which throws
   // on same-path registrations within any single registry before this check
   // runs. This function only handles the cross-registry case.
+  //
+  // Cross-registry collisions are checked among `type` / `field` /
+  // `entityTypes` only — these three are user-facing helper paths that PSL
+  // must resolve unambiguously. `pslBlockDescriptors` is an internal
+  // framework index consumed by parser and printer dispatch, not a
+  // user-facing helper path; the natural authoring pattern is the same
+  // path key in `entityTypes` and `pslBlockDescriptors` for a single
+  // contribution. The block→factory link is enforced by
+  // `assertPslBlocksHaveFactories` via the discriminator string, not by path.
+  const ambiguityHint =
+    'Register each path in only one of authoringContributions.field / authoringContributions.type / authoringContributions.entityTypes.';
   for (const fieldPath of fieldPaths) {
     if (typePaths.has(fieldPath)) {
       throw new Error(
-        `Ambiguous authoring registry path "${fieldPath}". The same path is registered as both a type constructor and a field preset; PSL resolution would be ambiguous. Register each path in only one of authoringContributions.field / authoringContributions.type / authoringContributions.entityTypes.`,
+        `Ambiguous authoring registry path "${fieldPath}". The same path is registered as both a type constructor and a field preset; PSL resolution would be ambiguous. ${ambiguityHint}`,
       );
     }
   }
   for (const entityPath of entityPaths) {
     if (typePaths.has(entityPath) || fieldPaths.has(entityPath)) {
       throw new Error(
-        `Ambiguous authoring registry path "${entityPath}". The same path is registered as an entity contribution AND as a type constructor or field preset; PSL resolution would be ambiguous. Register each path in only one of authoringContributions.field / authoringContributions.type / authoringContributions.entityTypes.`,
+        `Ambiguous authoring registry path "${entityPath}". The same path is registered as an entity contribution AND as a type constructor or field preset; PSL resolution would be ambiguous. ${ambiguityHint}`,
       );
     }
   }
+
+  assertPslBlocksHaveFactories(entityTypeNamespace, pslBlockNamespace);
 }
 
 export function resolveAuthoringTemplateValue(

package/src/shared/framework-components.ts

@@ -227,6 +227,8 @@ export type TargetPackRef<
   TTargetId extends string = string,
 > = PackRefBase<'target', TFamilyId> & {
   readonly targetId: TTargetId;
+  /** The namespace a bare (un-namespaced) entity name resolves to for this target (e.g. Postgres `'public'`). */
+  readonly defaultNamespaceId: string;
 };
 
 export type AdapterPackRef<

package/src/shared/psl-extension-block.ts

@@ -0,0 +1,184 @@
+/**
+ * Shape-only types for the PSL source-position primitives, diagnostic
+ * codes, extension-block descriptor vocabulary, and the uniform
+ * extension-block AST node base.
+ *
+ * These live in the shared plane so an extension's authoring descriptor
+ * (`AuthoringPslBlockDescriptor` in `framework-authoring`) can reference
+ * them without crossing the shared → migration-plane boundary. The
+ * migration-plane `psl-ast.ts` re-exports everything here for consumers
+ * that import PSL AST types from the control entrypoint.
+ */
+
+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_NAMESPACE_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'
+  | 'PSL_INVALID_QUALIFIED_TYPE'
+  /**
+   * A malformed line inside an extension-contributed top-level block body, or
+   * a structurally invalid element inside a `list` parameter value.
+   *
+   * Replaces the overloaded `PSL_UNSUPPORTED_TOP_LEVEL_BLOCK` code that the
+   * generic framework parser previously used for these two parse-error sites
+   * inside extension blocks — keeping `PSL_UNSUPPORTED_TOP_LEVEL_BLOCK` for
+   * its original meaning (an unknown keyword at the top level) and giving
+   * extension-block parse errors their own code.
+   */
+  | 'PSL_INVALID_EXTENSION_BLOCK_MEMBER'
+  /**
+   * An unknown parameter key in an extension-contributed block — a key present
+   * in the source block but absent from the descriptor's `parameters` map.
+   */
+  | 'PSL_EXTENSION_UNKNOWN_PARAMETER'
+  /**
+   * A required parameter declared in the descriptor is absent from the parsed block.
+   */
+  | 'PSL_EXTENSION_MISSING_REQUIRED_PARAMETER'
+  /**
+   * An `option`-kind parameter value is not one of the allowed tokens listed
+   * in the descriptor's `values` array.
+   */
+  | 'PSL_EXTENSION_OPTION_OUT_OF_SET'
+  /**
+   * A `value`-kind parameter's raw text is not a valid JSON literal, or the
+   * parsed JSON value was rejected by the codec's `decodeJson` method, or the
+   * codec id is not registered in the lookup.
+   */
+  | 'PSL_EXTENSION_INVALID_VALUE'
+  /**
+   * A `ref`-kind parameter identifier does not resolve to a declared entity of
+   * the required `refKind` within the declared scope.
+   */
+  | 'PSL_EXTENSION_UNRESOLVED_REF';
+
+/**
+ * Descriptor vocabulary for a single parameter on a declared block.
+ *
+ * Four kinds:
+ * - `ref` — the parameter value is an identifier that must resolve to a
+ *   declared entity of `refKind` within the declared `scope`.
+ * - `value` — the parameter value is a PSL literal parsed and printed
+ *   through the codec identified by `codecId`.
+ * - `option` — the parameter value is one of the literal tokens in `values`.
+ *   Not a codec; not persisted data. A closed authoring-time constraint only.
+ * - `list` — a bracketed list whose elements each match the `of` descriptor.
+ */
+export type PslBlockParam =
+  | PslBlockParamRef
+  | PslBlockParamValue
+  | PslBlockParamOption
+  | PslBlockParamList;
+
+export interface PslBlockParamRef {
+  readonly kind: 'ref';
+  readonly refKind: string;
+  readonly scope: 'same-namespace' | 'same-space' | 'cross-space';
+  readonly required?: boolean;
+}
+
+export interface PslBlockParamValue {
+  readonly kind: 'value';
+  readonly codecId: string;
+  readonly required?: boolean;
+}
+
+export interface PslBlockParamOption {
+  readonly kind: 'option';
+  readonly values: readonly string[];
+  readonly required?: boolean;
+}
+
+export interface PslBlockParamList {
+  readonly kind: 'list';
+  readonly of: PslBlockParam;
+  readonly required?: boolean;
+}
+
+/**
+ * The parsed representation of a single parameter value on a uniform
+ * extension-block AST node. Mirrors the `PslBlockParam` descriptor
+ * vocabulary:
+ *
+ * - `ref`    → `PslExtensionBlockParamRef` — a raw identifier string
+ *   (resolution runs in the validator, not the parser).
+ * - `value`  → `PslExtensionBlockParamValue` — a raw PSL literal string
+ *   (codec validation runs in the validator).
+ * - `option` → `PslExtensionBlockParamOption` — the chosen token.
+ * - `list`   → `PslExtensionBlockParamList` — ordered list of the above.
+ *
+ * These shapes are intentionally minimal. The validator and lowering refine
+ * and consume them; the generic framework parser produces them.
+ */
+export type PslExtensionBlockParamValue =
+  | PslExtensionBlockParamRef
+  | PslExtensionBlockParamScalarValue
+  | PslExtensionBlockParamOption
+  | PslExtensionBlockParamList;
+
+export interface PslExtensionBlockParamRef {
+  readonly kind: 'ref';
+  readonly identifier: string;
+  readonly span: PslSpan;
+}
+
+export interface PslExtensionBlockParamScalarValue {
+  readonly kind: 'value';
+  readonly raw: string;
+  readonly span: PslSpan;
+}
+
+export interface PslExtensionBlockParamOption {
+  readonly kind: 'option';
+  readonly token: string;
+  readonly span: PslSpan;
+}
+
+export interface PslExtensionBlockParamList {
+  readonly kind: 'list';
+  readonly items: readonly PslExtensionBlockParamValue[];
+  readonly span: PslSpan;
+}
+
+/**
+ * Base shape for a uniform extension-contributed top-level PSL block
+ * node, as produced by the generic framework parser and consumed by the
+ * validator and lowering factory.
+ *
+ * - `kind` is the routing discriminant, equal to the descriptor's
+ *   `discriminator`. The framework parser sets this to
+ *   `descriptor.discriminator` for every block it parses.
+ * - `name` is the block's declared name (the identifier after the keyword).
+ * - `parameters` is the descriptor-driven parameter map. Keys are
+ *   parameter names from the descriptor; values are the parsed parameter
+ *   representations. Only parameters present in the source are included
+ *   — absence of a required parameter is a validator concern, not a
+ *   parser concern.
+ * - `span` covers the full block from keyword to closing brace.
+ */
+export interface PslExtensionBlock {
+  readonly kind: string;
+  readonly name: string;
+  readonly parameters: Record<string, PslExtensionBlockParamValue>;
+  readonly span: PslSpan;
+}