@prisma-next/framework-components 0.12.0-dev.61 → 0.12.0-dev.62

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;
+}

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/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/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(