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

package/src/control/control-stack.ts

@@ -1,15 +1,18 @@
+import { blindCast } from '@prisma-next/utils/casts';
 import type { Codec } from '../shared/codec';
 import type { CodecLookup, CodecMeta } from '../shared/codec-types';
 import type {
   AuthoringContributions,
   AuthoringEntityTypeNamespace,
   AuthoringFieldNamespace,
+  AuthoringPslBlockDescriptorNamespace,
   AuthoringTypeNamespace,
 } from '../shared/framework-authoring';
 import {
   assertNoCrossRegistryCollisions,
   isAuthoringEntityTypeDescriptor,
   isAuthoringFieldPresetDescriptor,
+  isAuthoringPslBlockDescriptor,
   isAuthoringTypeConstructorDescriptor,
   mergeAuthoringNamespaces,
 } from '../shared/framework-authoring';
@@ -32,6 +35,7 @@ export interface AssembledAuthoringContributions {
   readonly field: AuthoringFieldNamespace;
   readonly type: AuthoringTypeNamespace;
   readonly entityTypes: AuthoringEntityTypeNamespace;
+  readonly pslBlockDescriptors: AuthoringPslBlockDescriptorNamespace;
 }
 
 export interface ControlStack<
@@ -151,6 +155,7 @@ export function assembleAuthoringContributions(
   const field = {} as Record<string, unknown>;
   const type = {} as Record<string, unknown>;
   const entityTypes = {} as Record<string, unknown>;
+  const pslBlockDescriptors: Record<string, unknown> = {};
 
   for (const descriptor of descriptors) {
     if (descriptor.authoring?.field) {
@@ -180,17 +185,36 @@ export function assembleAuthoringContributions(
         'entity',
       );
     }
+    if (descriptor.authoring?.pslBlockDescriptors) {
+      mergeAuthoringNamespaces(
+        pslBlockDescriptors,
+        descriptor.authoring.pslBlockDescriptors,
+        [],
+        isAuthoringPslBlockDescriptor,
+        'pslBlock',
+      );
+    }
   }
 
   const fieldNamespace = field as AuthoringFieldNamespace;
   const typeNamespace = type as AuthoringTypeNamespace;
   const entityTypeNamespace = entityTypes as AuthoringEntityTypeNamespace;
-  assertNoCrossRegistryCollisions(typeNamespace, fieldNamespace, entityTypeNamespace);
+  const pslBlockDescriptorNamespace = blindCast<
+    AuthoringPslBlockDescriptorNamespace,
+    'merge target accumulator narrows to typed namespace post-merge'
+  >(pslBlockDescriptors);
+  assertNoCrossRegistryCollisions(
+    typeNamespace,
+    fieldNamespace,
+    entityTypeNamespace,
+    pslBlockDescriptorNamespace,
+  );
 
   return {
     field: fieldNamespace,
     type: typeNamespace,
     entityTypes: entityTypeNamespace,
+    pslBlockDescriptors: pslBlockDescriptorNamespace,
   };
 }
 
@@ -345,12 +369,107 @@ export function validateScalarTypeCodecIds(
   return errors;
 }
 
+interface DependencyDeclaringDescriptor {
+  readonly id: string;
+  readonly contractSpace?: {
+    readonly contractJson?: {
+      readonly extensionPacks?: Readonly<Record<string, unknown>>;
+    };
+  };
+}
+
+function readDeclaredDependencyIds(descriptor: DependencyDeclaringDescriptor): readonly string[] {
+  const packs = descriptor.contractSpace?.contractJson?.extensionPacks;
+  if (packs === null || typeof packs !== 'object') return [];
+  return Object.keys(packs);
+}
+
+/**
+ * Builds a dependency-respecting load order for the given extension descriptors
+ * using Kahn's topological sort algorithm. Dependencies (packs declared in
+ * `contractSpace.contractJson.extensionPacks`) are placed before the extensions
+ * that depend on them.
+ *
+ * Throws if the dependency graph contains a cycle, with an error message that
+ * names every extension involved in the cycle.
+ *
+ * Throws if any extension declares a dependency on a pack ID that is not present
+ * in the provided list — add the missing pack to the `extensionPacks` list to
+ * resolve the error.
+ */
+
+export function buildExtensionLoadOrder(
+  extensions: ReadonlyArray<DependencyDeclaringDescriptor>,
+): readonly string[] {
+  if (extensions.length === 0) return [];
+
+  const idSet = new Set(extensions.map((e) => e.id));
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+
+  for (const ext of extensions) {
+    if (!inDegree.has(ext.id)) inDegree.set(ext.id, 0);
+    if (!dependents.has(ext.id)) dependents.set(ext.id, []);
+  }
+
+  for (const ext of extensions) {
+    for (const depId of readDeclaredDependencyIds(ext)) {
+      if (!idSet.has(depId)) {
+        throw new Error(
+          `Extension "${ext.id}" declares a dependency on "${depId}", but "${depId}" is not in the provided extension set. Add the missing space to extensionPacks.`,
+        );
+      }
+      inDegree.set(ext.id, (inDegree.get(ext.id) ?? 0) + 1);
+      const list = dependents.get(depId);
+      if (list !== undefined) list.push(ext.id);
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [id, deg] of inDegree) {
+    if (deg === 0) queue.push(id);
+  }
+  queue.sort();
+
+  const result: string[] = [];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    if (id === undefined) break;
+    result.push(id);
+    const children = dependents.get(id) ?? [];
+    children.sort();
+    for (const childId of children) {
+      const newDeg = (inDegree.get(childId) ?? 1) - 1;
+      inDegree.set(childId, newDeg);
+      if (newDeg === 0) queue.push(childId);
+    }
+  }
+
+  if (result.length < extensions.length) {
+    const cycleMembers = extensions
+      .map((e) => e.id)
+      .filter((id) => !result.includes(id))
+      .sort();
+    throw new Error(
+      `Extension dependency cycle detected. Cycle members: ${cycleMembers.map((id) => `"${id}"`).join(', ')}.`,
+    );
+  }
+
+  return result;
+}
+
 export function createControlStack<TFamilyId extends string, TTargetId extends string>(
   input: CreateControlStackInput<TFamilyId, TTargetId>,
 ): ControlStack<TFamilyId, TTargetId> {
   const { family, target, adapter, driver, extensionPacks = [] } = input;
 
-  const allDescriptors = [family, target, ...(adapter ? [adapter] : []), ...extensionPacks];
+  const orderedIds = buildExtensionLoadOrder(extensionPacks);
+  const extensionById = new Map(extensionPacks.map((ext) => [ext.id, ext]));
+  const orderedExtensionPacks = orderedIds
+    .map((id) => extensionById.get(id))
+    .filter((ext): ext is ControlExtensionDescriptor<TFamilyId, TTargetId> => ext !== undefined);
+
+  const allDescriptors = [family, target, ...(adapter ? [adapter] : []), ...orderedExtensionPacks];
 
   const codecLookup = extractCodecLookup(allDescriptors);
   const scalarTypeDescriptors = assembleScalarTypeDescriptors(allDescriptors);
@@ -360,11 +479,11 @@ export function createControlStack<TFamilyId extends string, TTargetId extends s
     target,
     adapter,
     driver,
-    extensionPacks: extensionPacks as readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[],
+    extensionPacks: orderedExtensionPacks,
 
     codecTypeImports: extractCodecTypeImports(allDescriptors),
     queryOperationTypeImports: extractQueryOperationTypeImports(allDescriptors),
-    extensionIds: extractComponentIds(family, target, adapter, extensionPacks),
+    extensionIds: extractComponentIds(family, target, adapter, orderedExtensionPacks),
     codecLookup,
     authoringContributions: assembleAuthoringContributions(allDescriptors),
     scalarTypeDescriptors,

package/src/control/psl-ast.ts

@@ -1,28 +1,24 @@
-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';
+export type { AuthoringPslBlockDescriptorNamespace } from '../shared/framework-authoring';
+export type {
+  PslBlockParam,
+  PslBlockParamList,
+  PslBlockParamOption,
+  PslBlockParamRef,
+  PslBlockParamValue,
+  PslDiagnosticCode,
+  PslExtensionBlock,
+  PslExtensionBlockParamList,
+  PslExtensionBlockParamOption,
+  PslExtensionBlockParamRef,
+  PslExtensionBlockParamScalarValue,
+  PslExtensionBlockParamValue,
+  PslPosition,
+  PslSpan,
+} from '../shared/psl-extension-block';
+
+import type { CodecLookup } from '../shared/codec-types';
+import type { AuthoringPslBlockDescriptorNamespace } from '../shared/framework-authoring';
+import type { PslDiagnosticCode, PslExtensionBlock, PslSpan } from '../shared/psl-extension-block';
 
 export interface PslDiagnostic {
   readonly code: PslDiagnosticCode;
@@ -82,10 +78,19 @@ export type PslFieldAttribute = PslAttribute;
 export interface PslField {
   readonly kind: 'field';
   readonly name: string;
-  /** Unqualified type name, e.g. `"User"` for both `User` and `auth.User`. */
+  /** Unqualified type name, e.g. `"User"` for both `User`, `auth.User`, and `supabase:auth.User`. */
   readonly typeName: string;
-  /** Namespace qualifier from a dot-qualified type reference, e.g. `"auth"` for `auth.User`. Absent for unqualified types. */
+  /** Namespace qualifier from a dot-qualified type reference, e.g. `"auth"` for `auth.User` or `supabase:auth.User`. Absent for unqualified types. */
   readonly typeNamespaceId?: string;
+  /**
+   * Contract-space qualifier from a colon-prefix type reference, e.g. `"supabase"` for
+   * `supabase:auth.User` or `supabase:User`. Absent for local (same-space) type references.
+   *
+   * When present, the field references a model from a different contract space. The namespace
+   * (`typeNamespaceId`) and model name (`typeName`) identify the target within that space.
+   * Physical table resolution against the extension contract is deferred to the aggregate stage (M3).
+   */
+  readonly typeContractSpaceId?: string;
   readonly typeConstructor?: PslTypeConstructorCall;
   readonly optional: boolean;
   readonly list: boolean;
@@ -203,6 +208,23 @@ export interface PslNamespace {
   readonly models: readonly PslModel[];
   readonly enums: readonly PslEnum[];
   readonly compositeTypes: readonly PslCompositeType[];
+  /**
+   * Extension-contributed top-level blocks parsed inside this namespace.
+   * These are the parsed AST nodes produced by the generic framework parser
+   * when it encounters a keyword claimed by a registered
+   * {@link AuthoringPslBlockDescriptorNamespace} entry.
+   *
+   * Absent when no extension blocks appear in this namespace. Order matches
+   * source order within the namespace; extension-contributed and built-in
+   * blocks live in their own slots, so a namespace mixing `model X { … }` and
+   * `policy_select Y { … }` keeps the model in `models` and the policy in
+   * `extensionBlocks`.
+   *
+   * Contrast with {@link ParsePslDocumentInput.pslBlockDescriptors}: that
+   * field holds the registry of declarative descriptors that teach the parser
+   * which keywords to accept; this field holds the resulting parsed nodes.
+   */
+  readonly extensionBlocks?: readonly PslExtensionBlock[];
   readonly span: PslSpan;
 }
 
@@ -239,6 +261,30 @@ export function flatPslCompositeTypes(ast: PslDocumentAst): readonly PslComposit
 export interface ParsePslDocumentInput {
   readonly schema: string;
   readonly sourceId: string;
+  /**
+   * Registry of declarative block descriptors, keyed by arbitrary path
+   * segments with {@link AuthoringPslBlockDescriptor} leaves. The registry
+   * teaches the parser which top-level keywords belong to extension
+   * contributions: when the parser encounters an unknown keyword, it looks
+   * it up here and, when found, reads the block generically into a
+   * {@link PslExtensionBlock} node. Absent or undefined means no extension
+   * blocks are registered and any unknown keyword yields
+   * `PSL_UNSUPPORTED_TOP_LEVEL_BLOCK`.
+   *
+   * 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;
+  /**
+   * Codec lookup for validating `value`-kind extension block parameters.
+   * When provided alongside `pslBlockDescriptors`, the generic validator runs
+   * over every parsed extension block after the full AST is assembled,
+   * appending any diagnostics to the parse result. Absent or undefined means
+   * no codec validation runs; `ref` resolution still runs when namespace
+   * context is available (built from the assembled namespaces).
+   */
+  readonly codecLookup?: CodecLookup;
 }
 
 export interface ParsePslDocumentResult {

package/src/control/psl-extension-block-validator.ts

@@ -0,0 +1,340 @@
+/**
+ * Generic validator for extension-contributed top-level PSL blocks.
+ *
+ * One function — {@link validateExtensionBlock} — takes a parsed
+ * {@link PslExtensionBlock}, its {@link AuthoringPslBlockDescriptor}, a
+ * {@link CodecLookup} (for `value` parameters), and the set of
+ * {@link PslNamespace} objects from the document (for `ref` resolution), and
+ * returns the full list of {@link PslDiagnostic} objects for the block.
+ *
+ * Detection logic per failure mode:
+ *
+ * 1. **Unknown parameter** — keys present in `node.parameters` that are absent
+ *    from `descriptor.parameters` (key-set difference). The parser stores
+ *    unknown parameters as `kind:'value'` stubs; the validator discovers them
+ *    by comparing the key sets, not by inspecting the captured kind.
+ *
+ * 2. **Missing required parameter** — `descriptor.parameters` entries with
+ *    `required: true` whose key is absent from `node.parameters`.
+ *
+ * 3. **`option` value outside its set** — the captured `token` is not in
+ *    `descriptor.values`.
+ *
+ * 4. **`value` rejected by its codec** — the raw string is first parsed as
+ *    JSON (`JSON.parse(raw)`). If `JSON.parse` throws, the literal is not valid
+ *    JSON and a `PSL_EXTENSION_INVALID_VALUE` diagnostic is emitted. If parsing
+ *    succeeds but `codec.decodeJson(jsonValue)` throws, the JSON value is not
+ *    acceptable to the codec and a `PSL_EXTENSION_INVALID_VALUE` diagnostic is
+ *    emitted. If `codecLookup.get(codecId)` returns `undefined` (unknown codec
+ *    id), a `PSL_EXTENSION_INVALID_VALUE` diagnostic is also emitted.
+ *
+ * 5. **`ref` that does not resolve within its scope** — the captured
+ *    `identifier` is looked up in the PSL document's `PslNamespace` objects
+ *    according to `param.scope`:
+ *    - `same-namespace`: the referent must be in the same namespace as the
+ *      block (the namespace containing the block).
+ *    - `same-space`: the referent may be in any namespace in the document.
+ *    - `cross-space`: pass-through — enforcement is scoped to first-consumer
+ *      need (RLS roles). This case is documented and clearly flagged; the
+ *      caller is responsible for wiring cross-space resolution when needed.
+ *
+ * 6. **`list`** — each element is validated against `param.of` recursively.
+ *
+ * ### `char`/`varchar` length
+ * Not enforced. RLS `using`/`check` strings are unbounded text and the codec
+ * already rejects structurally invalid literals; length constraints are a
+ * database-side concern, not a PSL authoring constraint.
+ *
+ * ### `cross-space` scope
+ * Implemented as a documented pass-through. The spec permits scoping
+ * cross-space enforcement to first-consumer need (RLS roles). When RLS roles
+ * arrive, wire `cross-space` resolution through the cross-contract-space
+ * coordinate model `(spaceId, namespaceId, entityKind, entityName)`.
+ */
+
+import type { JsonValue } from '@prisma-next/contract/types';
+import { blindCast } from '@prisma-next/utils/casts';
+import type { CodecLookup } from '../shared/codec-types';
+import type { AuthoringPslBlockDescriptor } from '../shared/framework-authoring';
+import type {
+  PslBlockParam,
+  PslBlockParamRef,
+  PslExtensionBlock,
+  PslExtensionBlockParamValue,
+  PslSpan,
+} from '../shared/psl-extension-block';
+import type { PslDiagnostic, PslNamespace } from './psl-ast';
+
+/**
+ * Context for ref resolution during extension-block validation.
+ *
+ * - `ownerNamespace` is the `PslNamespace` that contains the block being
+ *   validated. Used for `same-namespace` scope checks.
+ * - `allNamespaces` is every namespace in the document. Used for `same-space`
+ *   scope checks.
+ */
+export interface ExtensionBlockRefResolutionContext {
+  readonly ownerNamespace: PslNamespace;
+  readonly allNamespaces: readonly PslNamespace[];
+}
+
+/**
+ * Validate a single parsed extension block against its descriptor.
+ *
+ * Returns an array of {@link PslDiagnostic} objects (possibly empty). The
+ * caller is responsible for threading `sourceId` into each returned diagnostic
+ * — the returned objects already have `sourceId` set from the `sourceId`
+ * parameter.
+ *
+ * @param node - The parsed block node produced by the generic framework parser.
+ * @param descriptor - The descriptor that claims this block's keyword.
+ * @param sourceId - The PSL source file identifier (threaded into diagnostics).
+ * @param codecLookup - Used to validate `value`-kind parameter literals via
+ *   `codecLookup.get(codecId)?.decodeJson(JSON.parse(raw))`.
+ * @param refCtx - Namespace context for `ref`-kind scope resolution. Required
+ *   when any descriptor parameter is `kind: 'ref'`; may be omitted if none are.
+ */
+export function validateExtensionBlock(
+  node: PslExtensionBlock,
+  descriptor: AuthoringPslBlockDescriptor,
+  sourceId: string,
+  codecLookup: CodecLookup,
+  refCtx?: ExtensionBlockRefResolutionContext,
+): readonly PslDiagnostic[] {
+  const diagnostics: PslDiagnostic[] = [];
+
+  const descriptorKeys = new Set(Object.keys(descriptor.parameters));
+  const nodeKeys = new Set(Object.keys(node.parameters));
+
+  // 1. Unknown parameters — keys in the node not in the descriptor.
+  for (const key of nodeKeys) {
+    if (!descriptorKeys.has(key)) {
+      const captured = node.parameters[key];
+      diagnostics.push({
+        code: 'PSL_EXTENSION_UNKNOWN_PARAMETER',
+        message: `Unknown parameter "${key}" in "${descriptor.keyword}" block "${node.name}". The descriptor does not declare this parameter.`,
+        sourceId,
+        span: captured?.span ?? node.span,
+      });
+    }
+  }
+
+  // 2. Missing required parameters — required descriptor keys absent from the node.
+  for (const [key, param] of Object.entries(descriptor.parameters)) {
+    if (param.required === true && !nodeKeys.has(key)) {
+      diagnostics.push({
+        code: 'PSL_EXTENSION_MISSING_REQUIRED_PARAMETER',
+        message: `Required parameter "${key}" is missing from "${descriptor.keyword}" block "${node.name}".`,
+        sourceId,
+        span: node.span,
+      });
+    }
+  }
+
+  // 3–5. Per-parameter validation for parameters that are present.
+  for (const [key, param] of Object.entries(descriptor.parameters)) {
+    const captured = node.parameters[key];
+    if (captured === undefined) {
+      continue;
+    }
+    validateParam(
+      node,
+      descriptor,
+      key,
+      param,
+      captured,
+      sourceId,
+      codecLookup,
+      refCtx,
+      diagnostics,
+    );
+  }
+
+  return diagnostics;
+}
+
+function validateParam(
+  node: PslExtensionBlock,
+  descriptor: AuthoringPslBlockDescriptor,
+  key: string,
+  param: PslBlockParam,
+  captured: PslExtensionBlockParamValue,
+  sourceId: string,
+  codecLookup: CodecLookup,
+  refCtx: ExtensionBlockRefResolutionContext | undefined,
+  diagnostics: PslDiagnostic[],
+): void {
+  switch (param.kind) {
+    case 'option': {
+      if (captured.kind !== 'option') {
+        return;
+      }
+      if (!param.values.includes(captured.token)) {
+        diagnostics.push({
+          code: 'PSL_EXTENSION_OPTION_OUT_OF_SET',
+          message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" has value "${captured.token}" which is not one of the allowed values: ${param.values.map((v) => `"${v}"`).join(', ')}.`,
+          sourceId,
+          span: captured.span,
+        });
+      }
+      return;
+    }
+
+    case 'value': {
+      if (captured.kind !== 'value') {
+        return;
+      }
+      const codec = codecLookup.get(param.codecId);
+      if (codec === undefined) {
+        diagnostics.push({
+          code: 'PSL_EXTENSION_INVALID_VALUE',
+          message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" references unknown codec "${param.codecId}".`,
+          sourceId,
+          span: captured.span,
+        });
+        return;
+      }
+      let jsonValue: unknown;
+      try {
+        jsonValue = JSON.parse(captured.raw);
+      } catch {
+        diagnostics.push({
+          code: 'PSL_EXTENSION_INVALID_VALUE',
+          message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" is not a valid JSON literal (expected a JSON string, number, boolean, or null): ${captured.raw}`,
+          sourceId,
+          span: captured.span,
+        });
+        return;
+      }
+      try {
+        codec.decodeJson(
+          blindCast<JsonValue, 'JSON.parse returns a JsonValue-compatible value'>(jsonValue),
+        );
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        diagnostics.push({
+          code: 'PSL_EXTENSION_INVALID_VALUE',
+          message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" was rejected by codec "${param.codecId}": ${reason}`,
+          sourceId,
+          span: captured.span,
+        });
+      }
+      return;
+    }
+
+    case 'ref': {
+      if (captured.kind !== 'ref') {
+        return;
+      }
+      validateRef(
+        node,
+        descriptor,
+        key,
+        param,
+        captured.identifier,
+        captured.span,
+        sourceId,
+        refCtx,
+        diagnostics,
+      );
+      return;
+    }
+
+    case 'list': {
+      if (captured.kind !== 'list') {
+        return;
+      }
+      for (const item of captured.items) {
+        validateParam(
+          node,
+          descriptor,
+          key,
+          param.of,
+          item,
+          sourceId,
+          codecLookup,
+          refCtx,
+          diagnostics,
+        );
+      }
+      return;
+    }
+  }
+}
+
+function validateRef(
+  node: PslExtensionBlock,
+  descriptor: AuthoringPslBlockDescriptor,
+  key: string,
+  param: PslBlockParamRef,
+  identifier: string,
+  span: PslSpan,
+  sourceId: string,
+  refCtx: ExtensionBlockRefResolutionContext | undefined,
+  diagnostics: PslDiagnostic[],
+): void {
+  if (param.scope === 'cross-space') {
+    // cross-space enforcement is a documented pass-through. The spec permits
+    // scoping cross-space resolution to first-consumer need (RLS roles). When
+    // that consumer arrives, wire resolution here through the
+    // cross-contract-space coordinate model
+    // (spaceId, namespaceId, entityKind, entityName).
+    // For now, cross-space refs pass validation unconditionally.
+    return;
+  }
+
+  if (refCtx === undefined) {
+    // If no resolution context was provided, skip ref resolution. This matches
+    // the closed-grammar invariant: callers that register ref parameters must
+    // provide resolution context; callers without namespaces (e.g. unit tests
+    // that only exercise other validation modes) can omit it.
+    return;
+  }
+
+  const namespacesToSearch: readonly PslNamespace[] =
+    param.scope === 'same-namespace' ? [refCtx.ownerNamespace] : refCtx.allNamespaces;
+
+  if (!resolveEntityInNamespaces(identifier, param.refKind, namespacesToSearch)) {
+    const scopeLabel =
+      param.scope === 'same-namespace' ? 'the same namespace' : 'any namespace in the schema';
+    diagnostics.push({
+      code: 'PSL_EXTENSION_UNRESOLVED_REF',
+      message: `Parameter "${key}" in "${descriptor.keyword}" block "${node.name}" refers to "${identifier}" (expected ${param.refKind}), but no entity with that name and kind was found in ${scopeLabel}.`,
+      sourceId,
+      span,
+    });
+  }
+}
+
+/**
+ * Returns true when an entity named `name` of kind `refKind` exists in at
+ * least one of the given namespaces.
+ *
+ * Built-in PSL entity kinds are mapped to their `PslNamespace` collection:
+ * - `'model'`         → `ns.models`
+ * - `'enum'`          → `ns.enums`
+ * - `'compositeType'` → `ns.compositeTypes`
+ *
+ * Any other `refKind` is resolved against the namespace's `extensionBlocks`
+ * array (matching by `block.kind === refKind` and `block.name === name`).
+ * This covers extension-contributed entity kinds that reference other
+ * extension-contributed blocks (e.g. a policy referencing a role block).
+ */
+function resolveEntityInNamespaces(
+  name: string,
+  refKind: string,
+  namespaces: readonly PslNamespace[],
+): boolean {
+  for (const ns of namespaces) {
+    if (refKind === 'model') {
+      if (ns.models.some((m) => m.name === name)) return true;
+    } else if (refKind === 'enum') {
+      if (ns.enums.some((e) => e.name === name)) return true;
+    } else if (refKind === 'compositeType') {
+      if (ns.compositeTypes.some((ct) => ct.name === name)) return true;
+    } else {
+      if (ns.extensionBlocks?.some((b) => b.kind === refKind && b.name === name)) return true;
+    }
+  }
+  return false;
+}