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

package/dist/psl-ast.mjs

@@ -1,3 +1,4 @@
+import { blindCast } from "@prisma-next/utils/casts";
 //#region src/control/psl-ast.ts
 /**
 * Name of the synthesised namespace bucket the framework parser uses for
@@ -32,6 +33,146 @@ function flatPslCompositeTypes(ast) {
 	return ast.namespaces.flatMap((ns) => ns.compositeTypes);
 }
 //#endregion
-export { UNSPECIFIED_PSL_NAMESPACE_ID, flatPslCompositeTypes, flatPslEnums, flatPslModels };
+//#region src/control/psl-extension-block-validator.ts
+/**
+* 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.
+*/
+function validateExtensionBlock(node, descriptor, sourceId, codecLookup, refCtx) {
+	const diagnostics = [];
+	const descriptorKeys = new Set(Object.keys(descriptor.parameters));
+	const nodeKeys = new Set(Object.keys(node.parameters));
+	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
+		});
+	}
+	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
+	});
+	for (const [key, param] of Object.entries(descriptor.parameters)) {
+		const captured = node.parameters[key];
+		if (captured === void 0) continue;
+		validateParam(node, descriptor, key, param, captured, sourceId, codecLookup, refCtx, diagnostics);
+	}
+	return diagnostics;
+}
+function validateParam(node, descriptor, key, param, captured, sourceId, codecLookup, refCtx, diagnostics) {
+	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 === void 0) {
+				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;
+			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));
+			} 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, descriptor, key, param, identifier, span, sourceId, refCtx, diagnostics) {
+	if (param.scope === "cross-space") return;
+	if (refCtx === void 0) return;
+	const namespacesToSearch = 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, refKind, namespaces) {
+	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;
+}
+//#endregion
+export { UNSPECIFIED_PSL_NAMESPACE_ID, flatPslCompositeTypes, flatPslEnums, flatPslModels, validateExtensionBlock };
 
 //# sourceMappingURL=psl-ast.mjs.map

package/dist/psl-ast.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"psl-ast.mjs","names":[],"sources":["../src/control/psl-ast.ts"],"sourcesContent":["export interface PslPosition {\n  readonly offset: number;\n  readonly line: number;\n  readonly column: number;\n}\n\nexport interface PslSpan {\n  readonly start: PslPosition;\n  readonly end: PslPosition;\n}\n\nexport type PslDiagnosticCode =\n  | 'PSL_UNTERMINATED_BLOCK'\n  | 'PSL_UNSUPPORTED_TOP_LEVEL_BLOCK'\n  | 'PSL_INVALID_NAMESPACE_BLOCK'\n  | 'PSL_INVALID_ATTRIBUTE_SYNTAX'\n  | 'PSL_INVALID_MODEL_MEMBER'\n  | 'PSL_UNSUPPORTED_MODEL_ATTRIBUTE'\n  | 'PSL_UNSUPPORTED_FIELD_ATTRIBUTE'\n  | 'PSL_INVALID_RELATION_ATTRIBUTE'\n  | 'PSL_INVALID_REFERENTIAL_ACTION'\n  | 'PSL_INVALID_DEFAULT_VALUE'\n  | 'PSL_INVALID_ENUM_MEMBER'\n  | 'PSL_INVALID_TYPES_MEMBER'\n  | 'PSL_INVALID_QUALIFIED_TYPE';\n\nexport interface PslDiagnostic {\n  readonly code: PslDiagnosticCode;\n  readonly message: string;\n  readonly sourceId: string;\n  readonly span: PslSpan;\n}\n\nexport interface PslDefaultFunctionValue {\n  readonly kind: 'function';\n  readonly name: 'autoincrement' | 'now';\n}\n\nexport interface PslDefaultLiteralValue {\n  readonly kind: 'literal';\n  readonly value: string | number | boolean;\n}\n\nexport type PslDefaultValue = PslDefaultFunctionValue | PslDefaultLiteralValue;\n\nexport type PslAttributeTarget = 'field' | 'model' | 'enum' | 'namedType';\n\nexport interface PslAttributePositionalArgument {\n  readonly kind: 'positional';\n  readonly value: string;\n  readonly span: PslSpan;\n}\n\nexport interface PslAttributeNamedArgument {\n  readonly kind: 'named';\n  readonly name: string;\n  readonly value: string;\n  readonly span: PslSpan;\n}\n\nexport type PslAttributeArgument = PslAttributePositionalArgument | PslAttributeNamedArgument;\n\nexport interface PslTypeConstructorCall {\n  readonly kind: 'typeConstructor';\n  readonly path: readonly string[];\n  readonly args: readonly PslAttributeArgument[];\n  readonly span: PslSpan;\n}\n\nexport interface PslAttribute {\n  readonly kind: 'attribute';\n  readonly target: PslAttributeTarget;\n  readonly name: string;\n  readonly args: readonly PslAttributeArgument[];\n  readonly span: PslSpan;\n}\n\nexport type PslReferentialAction = string;\n\nexport type PslFieldAttribute = PslAttribute;\n\nexport interface PslField {\n  readonly kind: 'field';\n  readonly name: string;\n  /** Unqualified type name, e.g. `\"User\"` for both `User`, `auth.User`, and `supabase:auth.User`. */\n  readonly typeName: string;\n  /** Namespace qualifier from a dot-qualified type reference, e.g. `\"auth\"` for `auth.User` or `supabase:auth.User`. Absent for unqualified types. */\n  readonly typeNamespaceId?: string;\n  /**\n   * Contract-space qualifier from a colon-prefix type reference, e.g. `\"supabase\"` for\n   * `supabase:auth.User` or `supabase:User`. Absent for local (same-space) type references.\n   *\n   * When present, the field references a model from a different contract space. The namespace\n   * (`typeNamespaceId`) and model name (`typeName`) identify the target within that space.\n   * Physical table resolution against the extension contract is deferred to the aggregate stage (M3).\n   */\n  readonly typeContractSpaceId?: string;\n  readonly typeConstructor?: PslTypeConstructorCall;\n  readonly optional: boolean;\n  readonly list: boolean;\n  readonly typeRef?: string;\n  readonly attributes: readonly PslFieldAttribute[];\n  readonly span: PslSpan;\n}\n\nexport interface PslUniqueConstraint {\n  readonly kind: 'unique';\n  readonly fields: readonly string[];\n  readonly span: PslSpan;\n}\n\nexport interface PslIndexConstraint {\n  readonly kind: 'index';\n  readonly fields: readonly string[];\n  readonly span: PslSpan;\n}\n\nexport type PslModelAttribute = PslAttribute;\n\nexport interface PslModel {\n  readonly kind: 'model';\n  readonly name: string;\n  readonly fields: readonly PslField[];\n  readonly attributes: readonly PslModelAttribute[];\n  readonly span: PslSpan;\n  /**\n   * Optional leading comment line emitted above the `model` keyword by the\n   * printer. Producers (e.g. `sqlSchemaIrToPslAst`) attach introspection\n   * advisories such as \"// WARNING: This table has no primary key in the\n   * database\" here. The parser leaves this field unset; round-tripping a\n   * parsed schema does not re-attach comments.\n   */\n  readonly comment?: string;\n}\n\nexport interface PslEnumValue {\n  readonly kind: 'enumValue';\n  readonly name: string;\n  /**\n   * Optional storage label for the enum member, captured from a trailing\n   * `@map(\"...\")` attribute on the member line. The parser populates this\n   * when the source PSL carries an explicit `@map`. Producers (e.g.\n   * `sqlSchemaIrToPslAst`) leave it unset; the printer emits `@map(...)`\n   * automatically when normalisation would change the printed member name\n   * (so an enum value `'in-progress'` becomes `inProgress @map(\"in-progress\")`\n   * in PSL, preserving the round-trip).\n   */\n  readonly mapName?: string;\n  readonly span: PslSpan;\n}\n\nexport interface PslEnum {\n  readonly kind: 'enum';\n  readonly name: string;\n  readonly values: readonly PslEnumValue[];\n  readonly attributes: readonly PslAttribute[];\n  readonly span: PslSpan;\n}\n\nexport interface PslCompositeType {\n  readonly kind: 'compositeType';\n  readonly name: string;\n  readonly fields: readonly PslField[];\n  readonly attributes: readonly PslAttribute[];\n  readonly span: PslSpan;\n}\n\nexport interface PslNamedTypeDeclaration {\n  readonly kind: 'namedType';\n  readonly name: string;\n  /**\n   * Parser invariant: exactly one of `baseType` and `typeConstructor` is set.\n   * Expressing this as a discriminated union trips TypeScript narrowing when\n   * the declaration flows through helpers that accept the full union.\n   */\n  readonly baseType?: string;\n  readonly typeConstructor?: PslTypeConstructorCall;\n  readonly attributes: readonly PslAttribute[];\n  readonly span: PslSpan;\n}\n\nexport interface PslTypesBlock {\n  readonly kind: 'types';\n  readonly declarations: readonly PslNamedTypeDeclaration[];\n  readonly span: PslSpan;\n}\n\n/**\n * Name of the synthesised namespace bucket the framework parser uses for\n * top-level declarations that appear outside any `namespace { … }` block.\n * The double-underscore decoration signals that the identifier is parser-\n * synthesised and never appears in user-authored PSL source — writing\n * `namespace __unspecified__ { … }` is a parse error.\n *\n * Distinct from the IR sentinel `__unbound__`: the PSL bucket describes\n * syntactic absence at the parser layer; the IR sentinel describes a late-\n * bound storage slot at the IR layer. Per-target interpreters decide how\n * (or whether) to map the PSL bucket to the IR sentinel.\n */\nexport const UNSPECIFIED_PSL_NAMESPACE_ID = '__unspecified__';\n\n/**\n * A named namespace block from a PSL document, or the parser's synthesised\n * `__unspecified__` bucket for declarations that appear outside any\n * `namespace { … }` block. Multiple `namespace foo { … }` blocks for the\n * same name across one or more files reopen-merge into a single entry;\n * `span` points at the first opening.\n */\nexport interface PslNamespace {\n  readonly kind: 'namespace';\n  readonly name: string;\n  readonly models: readonly PslModel[];\n  readonly enums: readonly PslEnum[];\n  readonly compositeTypes: readonly PslCompositeType[];\n  readonly span: PslSpan;\n}\n\nexport interface PslDocumentAst {\n  readonly kind: 'document';\n  readonly sourceId: string;\n  readonly namespaces: readonly PslNamespace[];\n  readonly types?: PslTypesBlock;\n  readonly span: PslSpan;\n}\n\n/**\n * Returns all models from every namespace in document order. Convenience\n * for consumers that don't (yet) need namespace-awareness.\n */\nexport function flatPslModels(ast: PslDocumentAst): readonly PslModel[] {\n  return ast.namespaces.flatMap((ns) => ns.models);\n}\n\n/**\n * Returns all enums from every namespace in document order.\n */\nexport function flatPslEnums(ast: PslDocumentAst): readonly PslEnum[] {\n  return ast.namespaces.flatMap((ns) => ns.enums);\n}\n\n/**\n * Returns all composite types from every namespace in document order.\n */\nexport function flatPslCompositeTypes(ast: PslDocumentAst): readonly PslCompositeType[] {\n  return ast.namespaces.flatMap((ns) => ns.compositeTypes);\n}\n\nexport interface ParsePslDocumentInput {\n  readonly schema: string;\n  readonly sourceId: string;\n}\n\nexport interface ParsePslDocumentResult {\n  readonly ast: PslDocumentAst;\n  readonly diagnostics: readonly PslDiagnostic[];\n  readonly ok: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;AAuMA,MAAa,+BAA+B;;;;;AA8B5C,SAAgB,cAAc,KAA0C;CACtE,OAAO,IAAI,WAAW,SAAS,OAAO,GAAG,MAAM;AACjD;;;;AAKA,SAAgB,aAAa,KAAyC;CACpE,OAAO,IAAI,WAAW,SAAS,OAAO,GAAG,KAAK;AAChD;;;;AAKA,SAAgB,sBAAsB,KAAkD;CACtF,OAAO,IAAI,WAAW,SAAS,OAAO,GAAG,cAAc;AACzD"}
+{"version":3,"file":"psl-ast.mjs","names":[],"sources":["../src/control/psl-ast.ts","../src/control/psl-extension-block-validator.ts"],"sourcesContent":["export type { AuthoringPslBlockDescriptorNamespace } from '../shared/framework-authoring';\nexport type {\n  PslBlockParam,\n  PslBlockParamList,\n  PslBlockParamOption,\n  PslBlockParamRef,\n  PslBlockParamValue,\n  PslDiagnosticCode,\n  PslExtensionBlock,\n  PslExtensionBlockParamList,\n  PslExtensionBlockParamOption,\n  PslExtensionBlockParamRef,\n  PslExtensionBlockParamScalarValue,\n  PslExtensionBlockParamValue,\n  PslPosition,\n  PslSpan,\n} from '../shared/psl-extension-block';\n\nimport type { CodecLookup } from '../shared/codec-types';\nimport type { AuthoringPslBlockDescriptorNamespace } from '../shared/framework-authoring';\nimport type { PslDiagnosticCode, PslExtensionBlock, PslSpan } from '../shared/psl-extension-block';\n\nexport interface PslDiagnostic {\n  readonly code: PslDiagnosticCode;\n  readonly message: string;\n  readonly sourceId: string;\n  readonly span: PslSpan;\n}\n\nexport interface PslDefaultFunctionValue {\n  readonly kind: 'function';\n  readonly name: 'autoincrement' | 'now';\n}\n\nexport interface PslDefaultLiteralValue {\n  readonly kind: 'literal';\n  readonly value: string | number | boolean;\n}\n\nexport type PslDefaultValue = PslDefaultFunctionValue | PslDefaultLiteralValue;\n\nexport type PslAttributeTarget = 'field' | 'model' | 'enum' | 'namedType';\n\nexport interface PslAttributePositionalArgument {\n  readonly kind: 'positional';\n  readonly value: string;\n  readonly span: PslSpan;\n}\n\nexport interface PslAttributeNamedArgument {\n  readonly kind: 'named';\n  readonly name: string;\n  readonly value: string;\n  readonly span: PslSpan;\n}\n\nexport type PslAttributeArgument = PslAttributePositionalArgument | PslAttributeNamedArgument;\n\nexport interface PslTypeConstructorCall {\n  readonly kind: 'typeConstructor';\n  readonly path: readonly string[];\n  readonly args: readonly PslAttributeArgument[];\n  readonly span: PslSpan;\n}\n\nexport interface PslAttribute {\n  readonly kind: 'attribute';\n  readonly target: PslAttributeTarget;\n  readonly name: string;\n  readonly args: readonly PslAttributeArgument[];\n  readonly span: PslSpan;\n}\n\nexport type PslReferentialAction = string;\n\nexport type PslFieldAttribute = PslAttribute;\n\nexport interface PslField {\n  readonly kind: 'field';\n  readonly name: string;\n  /** Unqualified type name, e.g. `\"User\"` for both `User`, `auth.User`, and `supabase:auth.User`. */\n  readonly typeName: string;\n  /** Namespace qualifier from a dot-qualified type reference, e.g. `\"auth\"` for `auth.User` or `supabase:auth.User`. Absent for unqualified types. */\n  readonly typeNamespaceId?: string;\n  /**\n   * Contract-space qualifier from a colon-prefix type reference, e.g. `\"supabase\"` for\n   * `supabase:auth.User` or `supabase:User`. Absent for local (same-space) type references.\n   *\n   * When present, the field references a model from a different contract space. The namespace\n   * (`typeNamespaceId`) and model name (`typeName`) identify the target within that space.\n   * Physical table resolution against the extension contract is deferred to the aggregate stage (M3).\n   */\n  readonly typeContractSpaceId?: string;\n  readonly typeConstructor?: PslTypeConstructorCall;\n  readonly optional: boolean;\n  readonly list: boolean;\n  readonly typeRef?: string;\n  readonly attributes: readonly PslFieldAttribute[];\n  readonly span: PslSpan;\n}\n\nexport interface PslUniqueConstraint {\n  readonly kind: 'unique';\n  readonly fields: readonly string[];\n  readonly span: PslSpan;\n}\n\nexport interface PslIndexConstraint {\n  readonly kind: 'index';\n  readonly fields: readonly string[];\n  readonly span: PslSpan;\n}\n\nexport type PslModelAttribute = PslAttribute;\n\nexport interface PslModel {\n  readonly kind: 'model';\n  readonly name: string;\n  readonly fields: readonly PslField[];\n  readonly attributes: readonly PslModelAttribute[];\n  readonly span: PslSpan;\n  /**\n   * Optional leading comment line emitted above the `model` keyword by the\n   * printer. Producers (e.g. `sqlSchemaIrToPslAst`) attach introspection\n   * advisories such as \"// WARNING: This table has no primary key in the\n   * database\" here. The parser leaves this field unset; round-tripping a\n   * parsed schema does not re-attach comments.\n   */\n  readonly comment?: string;\n}\n\nexport interface PslEnumValue {\n  readonly kind: 'enumValue';\n  readonly name: string;\n  /**\n   * Optional storage label for the enum member, captured from a trailing\n   * `@map(\"...\")` attribute on the member line. The parser populates this\n   * when the source PSL carries an explicit `@map`. Producers (e.g.\n   * `sqlSchemaIrToPslAst`) leave it unset; the printer emits `@map(...)`\n   * automatically when normalisation would change the printed member name\n   * (so an enum value `'in-progress'` becomes `inProgress @map(\"in-progress\")`\n   * in PSL, preserving the round-trip).\n   */\n  readonly mapName?: string;\n  readonly span: PslSpan;\n}\n\nexport interface PslEnum {\n  readonly kind: 'enum';\n  readonly name: string;\n  readonly values: readonly PslEnumValue[];\n  readonly attributes: readonly PslAttribute[];\n  readonly span: PslSpan;\n}\n\nexport interface PslCompositeType {\n  readonly kind: 'compositeType';\n  readonly name: string;\n  readonly fields: readonly PslField[];\n  readonly attributes: readonly PslAttribute[];\n  readonly span: PslSpan;\n}\n\nexport interface PslNamedTypeDeclaration {\n  readonly kind: 'namedType';\n  readonly name: string;\n  /**\n   * Parser invariant: exactly one of `baseType` and `typeConstructor` is set.\n   * Expressing this as a discriminated union trips TypeScript narrowing when\n   * the declaration flows through helpers that accept the full union.\n   */\n  readonly baseType?: string;\n  readonly typeConstructor?: PslTypeConstructorCall;\n  readonly attributes: readonly PslAttribute[];\n  readonly span: PslSpan;\n}\n\nexport interface PslTypesBlock {\n  readonly kind: 'types';\n  readonly declarations: readonly PslNamedTypeDeclaration[];\n  readonly span: PslSpan;\n}\n\n/**\n * Name of the synthesised namespace bucket the framework parser uses for\n * top-level declarations that appear outside any `namespace { … }` block.\n * The double-underscore decoration signals that the identifier is parser-\n * synthesised and never appears in user-authored PSL source — writing\n * `namespace __unspecified__ { … }` is a parse error.\n *\n * Distinct from the IR sentinel `__unbound__`: the PSL bucket describes\n * syntactic absence at the parser layer; the IR sentinel describes a late-\n * bound storage slot at the IR layer. Per-target interpreters decide how\n * (or whether) to map the PSL bucket to the IR sentinel.\n */\nexport const UNSPECIFIED_PSL_NAMESPACE_ID = '__unspecified__';\n\n/**\n * A named namespace block from a PSL document, or the parser's synthesised\n * `__unspecified__` bucket for declarations that appear outside any\n * `namespace { … }` block. Multiple `namespace foo { … }` blocks for the\n * same name across one or more files reopen-merge into a single entry;\n * `span` points at the first opening.\n */\nexport interface PslNamespace {\n  readonly kind: 'namespace';\n  readonly name: string;\n  readonly models: readonly PslModel[];\n  readonly enums: readonly PslEnum[];\n  readonly compositeTypes: readonly PslCompositeType[];\n  /**\n   * Extension-contributed top-level blocks parsed inside this namespace.\n   * These are the parsed AST nodes produced by the generic framework parser\n   * when it encounters a keyword claimed by a registered\n   * {@link AuthoringPslBlockDescriptorNamespace} entry.\n   *\n   * Absent when no extension blocks appear in this namespace. Order matches\n   * source order within the namespace; extension-contributed and built-in\n   * blocks live in their own slots, so a namespace mixing `model X { … }` and\n   * `policy_select Y { … }` keeps the model in `models` and the policy in\n   * `extensionBlocks`.\n   *\n   * Contrast with {@link ParsePslDocumentInput.pslBlockDescriptors}: that\n   * field holds the registry of declarative descriptors that teach the parser\n   * which keywords to accept; this field holds the resulting parsed nodes.\n   */\n  readonly extensionBlocks?: readonly PslExtensionBlock[];\n  readonly span: PslSpan;\n}\n\nexport interface PslDocumentAst {\n  readonly kind: 'document';\n  readonly sourceId: string;\n  readonly namespaces: readonly PslNamespace[];\n  readonly types?: PslTypesBlock;\n  readonly span: PslSpan;\n}\n\n/**\n * Returns all models from every namespace in document order. Convenience\n * for consumers that don't (yet) need namespace-awareness.\n */\nexport function flatPslModels(ast: PslDocumentAst): readonly PslModel[] {\n  return ast.namespaces.flatMap((ns) => ns.models);\n}\n\n/**\n * Returns all enums from every namespace in document order.\n */\nexport function flatPslEnums(ast: PslDocumentAst): readonly PslEnum[] {\n  return ast.namespaces.flatMap((ns) => ns.enums);\n}\n\n/**\n * Returns all composite types from every namespace in document order.\n */\nexport function flatPslCompositeTypes(ast: PslDocumentAst): readonly PslCompositeType[] {\n  return ast.namespaces.flatMap((ns) => ns.compositeTypes);\n}\n\nexport interface ParsePslDocumentInput {\n  readonly schema: string;\n  readonly sourceId: string;\n  /**\n   * Registry of declarative block descriptors, keyed by arbitrary path\n   * segments with {@link AuthoringPslBlockDescriptor} leaves. The registry\n   * teaches the parser which top-level keywords belong to extension\n   * contributions: when the parser encounters an unknown keyword, it looks\n   * it up here and, when found, reads the block generically into a\n   * {@link PslExtensionBlock} node. Absent or undefined means no extension\n   * blocks are registered and any unknown keyword yields\n   * `PSL_UNSUPPORTED_TOP_LEVEL_BLOCK`.\n   *\n   * Contrast with {@link PslNamespace.extensionBlocks}: that field holds the\n   * parsed block nodes in a namespace; this field holds the registry of\n   * descriptors that teach the parser how to read those blocks.\n   */\n  readonly pslBlockDescriptors?: AuthoringPslBlockDescriptorNamespace;\n  /**\n   * Codec lookup for validating `value`-kind extension block parameters.\n   * When provided alongside `pslBlockDescriptors`, the generic validator runs\n   * over every parsed extension block after the full AST is assembled,\n   * appending any diagnostics to the parse result. Absent or undefined means\n   * no codec validation runs; `ref` resolution still runs when namespace\n   * context is available (built from the assembled namespaces).\n   */\n  readonly codecLookup?: CodecLookup;\n}\n\nexport interface ParsePslDocumentResult {\n  readonly ast: PslDocumentAst;\n  readonly diagnostics: readonly PslDiagnostic[];\n  readonly ok: boolean;\n}\n","/**\n * Generic validator for extension-contributed top-level PSL blocks.\n *\n * One function — {@link validateExtensionBlock} — takes a parsed\n * {@link PslExtensionBlock}, its {@link AuthoringPslBlockDescriptor}, a\n * {@link CodecLookup} (for `value` parameters), and the set of\n * {@link PslNamespace} objects from the document (for `ref` resolution), and\n * returns the full list of {@link PslDiagnostic} objects for the block.\n *\n * Detection logic per failure mode:\n *\n * 1. **Unknown parameter** — keys present in `node.parameters` that are absent\n *    from `descriptor.parameters` (key-set difference). The parser stores\n *    unknown parameters as `kind:'value'` stubs; the validator discovers them\n *    by comparing the key sets, not by inspecting the captured kind.\n *\n * 2. **Missing required parameter** — `descriptor.parameters` entries with\n *    `required: true` whose key is absent from `node.parameters`.\n *\n * 3. **`option` value outside its set** — the captured `token` is not in\n *    `descriptor.values`.\n *\n * 4. **`value` rejected by its codec** — the raw string is first parsed as\n *    JSON (`JSON.parse(raw)`). If `JSON.parse` throws, the literal is not valid\n *    JSON and a `PSL_EXTENSION_INVALID_VALUE` diagnostic is emitted. If parsing\n *    succeeds but `codec.decodeJson(jsonValue)` throws, the JSON value is not\n *    acceptable to the codec and a `PSL_EXTENSION_INVALID_VALUE` diagnostic is\n *    emitted. If `codecLookup.get(codecId)` returns `undefined` (unknown codec\n *    id), a `PSL_EXTENSION_INVALID_VALUE` diagnostic is also emitted.\n *\n * 5. **`ref` that does not resolve within its scope** — the captured\n *    `identifier` is looked up in the PSL document's `PslNamespace` objects\n *    according to `param.scope`:\n *    - `same-namespace`: the referent must be in the same namespace as the\n *      block (the namespace containing the block).\n *    - `same-space`: the referent may be in any namespace in the document.\n *    - `cross-space`: pass-through — enforcement is scoped to first-consumer\n *      need (RLS roles). This case is documented and clearly flagged; the\n *      caller is responsible for wiring cross-space resolution when needed.\n *\n * 6. **`list`** — each element is validated against `param.of` recursively.\n *\n * ### `char`/`varchar` length\n * Not enforced. RLS `using`/`check` strings are unbounded text and the codec\n * already rejects structurally invalid literals; length constraints are a\n * database-side concern, not a PSL authoring constraint.\n *\n * ### `cross-space` scope\n * Implemented as a documented pass-through. The spec permits scoping\n * cross-space enforcement to first-consumer need (RLS roles). When RLS roles\n * arrive, wire `cross-space` resolution through the cross-contract-space\n * coordinate model `(spaceId, namespaceId, entityKind, entityName)`.\n */\n\nimport type { JsonValue } from '@prisma-next/contract/types';\nimport { blindCast } from '@prisma-next/utils/casts';\nimport type { CodecLookup } from '../shared/codec-types';\nimport type { AuthoringPslBlockDescriptor } from '../shared/framework-authoring';\nimport type {\n  PslBlockParam,\n  PslBlockParamRef,\n  PslExtensionBlock,\n  PslExtensionBlockParamValue,\n  PslSpan,\n} from '../shared/psl-extension-block';\nimport type { PslDiagnostic, PslNamespace } from './psl-ast';\n\n/**\n * Context for ref resolution during extension-block validation.\n *\n * - `ownerNamespace` is the `PslNamespace` that contains the block being\n *   validated. Used for `same-namespace` scope checks.\n * - `allNamespaces` is every namespace in the document. Used for `same-space`\n *   scope checks.\n */\nexport interface ExtensionBlockRefResolutionContext {\n  readonly ownerNamespace: PslNamespace;\n  readonly allNamespaces: readonly PslNamespace[];\n}\n\n/**\n * Validate a single parsed extension block against its descriptor.\n *\n * Returns an array of {@link PslDiagnostic} objects (possibly empty). The\n * caller is responsible for threading `sourceId` into each returned diagnostic\n * — the returned objects already have `sourceId` set from the `sourceId`\n * parameter.\n *\n * @param node - The parsed block node produced by the generic framework parser.\n * @param descriptor - The descriptor that claims this block's keyword.\n * @param sourceId - The PSL source file identifier (threaded into diagnostics).\n * @param codecLookup - Used to validate `value`-kind parameter literals via\n *   `codecLookup.get(codecId)?.decodeJson(JSON.parse(raw))`.\n * @param refCtx - Namespace context for `ref`-kind scope resolution. Required\n *   when any descriptor parameter is `kind: 'ref'`; may be omitted if none are.\n */\nexport function validateExtensionBlock(\n  node: PslExtensionBlock,\n  descriptor: AuthoringPslBlockDescriptor,\n  sourceId: string,\n  codecLookup: CodecLookup,\n  refCtx?: ExtensionBlockRefResolutionContext,\n): readonly PslDiagnostic[] {\n  const diagnostics: PslDiagnostic[] = [];\n\n  const descriptorKeys = new Set(Object.keys(descriptor.parameters));\n  const nodeKeys = new Set(Object.keys(node.parameters));\n\n  // 1. Unknown parameters — keys in the node not in the descriptor.\n  for (const key of nodeKeys) {\n    if (!descriptorKeys.has(key)) {\n      const captured = node.parameters[key];\n      diagnostics.push({\n        code: 'PSL_EXTENSION_UNKNOWN_PARAMETER',\n        message: `Unknown parameter \"${key}\" in \"${descriptor.keyword}\" block \"${node.name}\". The descriptor does not declare this parameter.`,\n        sourceId,\n        span: captured?.span ?? node.span,\n      });\n    }\n  }\n\n  // 2. Missing required parameters — required descriptor keys absent from the node.\n  for (const [key, param] of Object.entries(descriptor.parameters)) {\n    if (param.required === true && !nodeKeys.has(key)) {\n      diagnostics.push({\n        code: 'PSL_EXTENSION_MISSING_REQUIRED_PARAMETER',\n        message: `Required parameter \"${key}\" is missing from \"${descriptor.keyword}\" block \"${node.name}\".`,\n        sourceId,\n        span: node.span,\n      });\n    }\n  }\n\n  // 3–5. Per-parameter validation for parameters that are present.\n  for (const [key, param] of Object.entries(descriptor.parameters)) {\n    const captured = node.parameters[key];\n    if (captured === undefined) {\n      continue;\n    }\n    validateParam(\n      node,\n      descriptor,\n      key,\n      param,\n      captured,\n      sourceId,\n      codecLookup,\n      refCtx,\n      diagnostics,\n    );\n  }\n\n  return diagnostics;\n}\n\nfunction validateParam(\n  node: PslExtensionBlock,\n  descriptor: AuthoringPslBlockDescriptor,\n  key: string,\n  param: PslBlockParam,\n  captured: PslExtensionBlockParamValue,\n  sourceId: string,\n  codecLookup: CodecLookup,\n  refCtx: ExtensionBlockRefResolutionContext | undefined,\n  diagnostics: PslDiagnostic[],\n): void {\n  switch (param.kind) {\n    case 'option': {\n      if (captured.kind !== 'option') {\n        return;\n      }\n      if (!param.values.includes(captured.token)) {\n        diagnostics.push({\n          code: 'PSL_EXTENSION_OPTION_OUT_OF_SET',\n          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(', ')}.`,\n          sourceId,\n          span: captured.span,\n        });\n      }\n      return;\n    }\n\n    case 'value': {\n      if (captured.kind !== 'value') {\n        return;\n      }\n      const codec = codecLookup.get(param.codecId);\n      if (codec === undefined) {\n        diagnostics.push({\n          code: 'PSL_EXTENSION_INVALID_VALUE',\n          message: `Parameter \"${key}\" in \"${descriptor.keyword}\" block \"${node.name}\" references unknown codec \"${param.codecId}\".`,\n          sourceId,\n          span: captured.span,\n        });\n        return;\n      }\n      let jsonValue: unknown;\n      try {\n        jsonValue = JSON.parse(captured.raw);\n      } catch {\n        diagnostics.push({\n          code: 'PSL_EXTENSION_INVALID_VALUE',\n          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}`,\n          sourceId,\n          span: captured.span,\n        });\n        return;\n      }\n      try {\n        codec.decodeJson(\n          blindCast<JsonValue, 'JSON.parse returns a JsonValue-compatible value'>(jsonValue),\n        );\n      } catch (err) {\n        const reason = err instanceof Error ? err.message : String(err);\n        diagnostics.push({\n          code: 'PSL_EXTENSION_INVALID_VALUE',\n          message: `Parameter \"${key}\" in \"${descriptor.keyword}\" block \"${node.name}\" was rejected by codec \"${param.codecId}\": ${reason}`,\n          sourceId,\n          span: captured.span,\n        });\n      }\n      return;\n    }\n\n    case 'ref': {\n      if (captured.kind !== 'ref') {\n        return;\n      }\n      validateRef(\n        node,\n        descriptor,\n        key,\n        param,\n        captured.identifier,\n        captured.span,\n        sourceId,\n        refCtx,\n        diagnostics,\n      );\n      return;\n    }\n\n    case 'list': {\n      if (captured.kind !== 'list') {\n        return;\n      }\n      for (const item of captured.items) {\n        validateParam(\n          node,\n          descriptor,\n          key,\n          param.of,\n          item,\n          sourceId,\n          codecLookup,\n          refCtx,\n          diagnostics,\n        );\n      }\n      return;\n    }\n  }\n}\n\nfunction validateRef(\n  node: PslExtensionBlock,\n  descriptor: AuthoringPslBlockDescriptor,\n  key: string,\n  param: PslBlockParamRef,\n  identifier: string,\n  span: PslSpan,\n  sourceId: string,\n  refCtx: ExtensionBlockRefResolutionContext | undefined,\n  diagnostics: PslDiagnostic[],\n): void {\n  if (param.scope === 'cross-space') {\n    // cross-space enforcement is a documented pass-through. The spec permits\n    // scoping cross-space resolution to first-consumer need (RLS roles). When\n    // that consumer arrives, wire resolution here through the\n    // cross-contract-space coordinate model\n    // (spaceId, namespaceId, entityKind, entityName).\n    // For now, cross-space refs pass validation unconditionally.\n    return;\n  }\n\n  if (refCtx === undefined) {\n    // If no resolution context was provided, skip ref resolution. This matches\n    // the closed-grammar invariant: callers that register ref parameters must\n    // provide resolution context; callers without namespaces (e.g. unit tests\n    // that only exercise other validation modes) can omit it.\n    return;\n  }\n\n  const namespacesToSearch: readonly PslNamespace[] =\n    param.scope === 'same-namespace' ? [refCtx.ownerNamespace] : refCtx.allNamespaces;\n\n  if (!resolveEntityInNamespaces(identifier, param.refKind, namespacesToSearch)) {\n    const scopeLabel =\n      param.scope === 'same-namespace' ? 'the same namespace' : 'any namespace in the schema';\n    diagnostics.push({\n      code: 'PSL_EXTENSION_UNRESOLVED_REF',\n      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}.`,\n      sourceId,\n      span,\n    });\n  }\n}\n\n/**\n * Returns true when an entity named `name` of kind `refKind` exists in at\n * least one of the given namespaces.\n *\n * Built-in PSL entity kinds are mapped to their `PslNamespace` collection:\n * - `'model'`         → `ns.models`\n * - `'enum'`          → `ns.enums`\n * - `'compositeType'` → `ns.compositeTypes`\n *\n * Any other `refKind` is resolved against the namespace's `extensionBlocks`\n * array (matching by `block.kind === refKind` and `block.name === name`).\n * This covers extension-contributed entity kinds that reference other\n * extension-contributed blocks (e.g. a policy referencing a role block).\n */\nfunction resolveEntityInNamespaces(\n  name: string,\n  refKind: string,\n  namespaces: readonly PslNamespace[],\n): boolean {\n  for (const ns of namespaces) {\n    if (refKind === 'model') {\n      if (ns.models.some((m) => m.name === name)) return true;\n    } else if (refKind === 'enum') {\n      if (ns.enums.some((e) => e.name === name)) return true;\n    } else if (refKind === 'compositeType') {\n      if (ns.compositeTypes.some((ct) => ct.name === name)) return true;\n    } else {\n      if (ns.extensionBlocks?.some((b) => b.kind === refKind && b.name === name)) return true;\n    }\n  }\n  return false;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@prisma-next/framework-components",
-  "version": "0.12.0-dev.61",
+  "version": "0.12.0-dev.63",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Framework component types, assembly logic, and stack creation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.12.0-dev.61",
-    "@prisma-next/operations": "0.12.0-dev.61",
-    "@prisma-next/ts-render": "0.12.0-dev.61",
-    "@prisma-next/utils": "0.12.0-dev.61",
+    "@prisma-next/contract": "0.12.0-dev.63",
+    "@prisma-next/operations": "0.12.0-dev.63",
+    "@prisma-next/ts-render": "0.12.0-dev.63",
+    "@prisma-next/utils": "0.12.0-dev.63",
     "@standard-schema/spec": "^1.1.0",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.12.0-dev.61",
-    "@prisma-next/tsdown": "0.12.0-dev.61",
+    "@prisma-next/tsconfig": "0.12.0-dev.63",
+    "@prisma-next/tsdown": "0.12.0-dev.63",
     "tsdown": "0.22.1",
     "typescript": "5.9.3",
     "vitest": "4.1.7"

package/src/control/control-migration-types.ts

@@ -13,7 +13,11 @@ import type { Contract } from '@prisma-next/contract/types';
 import type { ImportRequirement } from '@prisma-next/ts-render';
 import type { Result } from '@prisma-next/utils/result';
 import type { TargetBoundComponentDescriptor } from '../shared/framework-components';
-import type { ControlDriverInstance, ControlFamilyInstance } from './control-instances';
+import type {
+  ControlAdapterInstance,
+  ControlDriverInstance,
+  ControlFamilyInstance,
+} from './control-instances';
 import type { OperationContext } from './control-result-types';
 
 // ============================================================================
@@ -537,7 +541,9 @@ export interface TargetMigrationsCapability<
     unknown
   >,
 > {
-  createPlanner(family: TFamilyInstance): MigrationPlanner<TFamilyId, TTargetId>;
+  createPlanner(
+    adapter: ControlAdapterInstance<TFamilyId, TTargetId>,
+  ): MigrationPlanner<TFamilyId, TTargetId>;
   createRunner(family: TFamilyInstance): MigrationRunner<TFamilyId, TTargetId>;
   /**
    * Synthesizes a family-specific schema IR from a contract for offline planning.

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

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;
@@ -212,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;
 }
 
@@ -248,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 {