prisma · StevenMcClankerton · Aug 28, 2026 · Aug 28, 2026 · Aug 28, 2026 · Aug 28, 2026
@@ -66,7 +66,7 @@ A parameter is one of four kinds. The split is principled, not incidental:
 
 ## How the framework interprets a block
 
-**Parse.** On an unknown top-level keyword, the framework looks it up in the `pslBlockDescriptors` registry. If a descriptor claims it, the generic parser reads the block into a `PslExtensionBlock` node — a name plus a `parameters` map keyed by parameter name. No extension code runs.
+**Parse.** On an unknown top-level keyword, the framework looks it up in the `pslBlockDescriptors` registry. If a descriptor claims it, the generic parser reads the block into a `PslExtensionBlock` node — a name, a `parameters` map keyed by parameter name, and an `attributes` map holding the `@@` attributes interpreted through the specs the descriptor declares in `attributes`. No extension code runs.
-**Parse.** On an unknown top-level keyword, the framework looks it up in the `pslBlockDescriptors` registry. If a descriptor claims it, the generic parser reads the block into a `PslExtensionBlock` node — a name, a `parameters` map keyed by parameter name, and an `attributes` map holding the `@@` attributes interpreted through the specs the descriptor declares in `attributes`. No extension code runs.
+**Parse.** On an unknown top-level keyword, the framework looks it up in the `pslBlockDescriptors` registry. If a descriptor claims it, the generic parser reads the block into a `PslExtensionBlock` node — a name, a `parameters` map keyed by parameter name, and an `attributes` map holding the `@@` attributes interpreted through the specs the descriptor declares in `attributes`. No extension-specific parse or print code runs; the framework invokes the declared attribute factories to obtain the specifications.
-**Parse.** On an unknown top-level keyword, the framework looks it up in the `pslBlockDescriptors` registry. If a descriptor claims it, the generic parser reads the block into a `PslExtensionBlock` node — a name, a `parameters` map keyed by parameter name, and an `attributes` map holding the `@@` attributes interpreted through the specs the descriptor declares in `attributes`. No extension code runs.
+**Parse.** On an unknown top-level keyword, the framework looks it up in the `pslBlockDescriptors` registry. If a descriptor claims it, the generic parser reads the block into a `PslExtensionBlock` node — a name, a `parameters` map keyed by parameter name, and an `attributes` map holding the `@@` attributes interpreted through the specs the descriptor declares in `attributes`. No extension-specific parse or print code runs; the framework invokes the declared attribute factories to obtain the specifications.
 
 **Validate.** The validator checks, at parse time and with source spans: unknown parameters; missing required parameters; an `option` value outside the declared set; a `value` the codec's `decodeJson` rejects; and a `ref` that doesn't resolve within its declared scope.
 

@@ -46,7 +46,7 @@ The SQL and Mongo family interpreters are the first consumers. They define their
 
 The kit consumes `ExpressionAst` directly. No intermediate argument representation is introduced, and no combinator reparses flattened source text except `json()`, the deliberate quoted-JSON-object exception.
 
-Attributes are a PSL authoring concern, so the kit lives in `psl-parser` rather than framework core. The current constructors cover field and model attributes. `AttributeLevel` reserves a block level, but generic-block attribute construction and interpretation remain future work.
+Attributes are a PSL authoring concern, so the kit is in `psl-parser` rather than framework core. The constructors cover field, model, and block attributes: `blockAttribute()` builds a spec over `BlockInterpretCtx` (no `selfModel`), a block descriptor declares its attributes on `AuthoringPslBlockDescriptor.attributes` as nullary factories, and the generic block reconstruction interprets them into `PslExtensionBlock.attributes`.
 
 ---
 
@@ -298,7 +298,6 @@ The current implementation is sufficient for interpreter consumption but not yet
 
 - Add central spec discovery and traversable combinator metadata for language-tooling consumers.
 - Decide whether reference combinators should expose declaration-bearing results while preserving the interpreter's string-oriented lowering needs.
-- Add block-level construction and interpretation if generic-block attributes adopt this mechanism.
 - Revisit signature-derived `TypedFuncCall` output types if downstream code needs statically discriminated call unions.
 - Decide whether literal-to-field-type compatibility should remain in lowering or gain a dedicated field-context combinator.
 

@@ -16,6 +16,7 @@ export type {
   PslExtensionBlockParamRef,
   PslExtensionBlockParamScalarValue,
   PslExtensionBlockParamValue,
+  PslExtensionBlockParsedAttribute,
   PslPosition,
   PslSpan,
 } from '../shared/psl-extension-block';

@@ -63,4 +63,5 @@ export type {
   PslExtensionBlockParamRef,
   PslExtensionBlockParamScalarValue,
   PslExtensionBlockParamValue,
+  PslExtensionBlockParsedAttribute,
 } from '../shared/psl-extension-block';
@@ -7,6 +7,7 @@ import {
   isColumnDefaultLiteralInputValue,
   isExecutionMutationDefaultValue,
 } from '@internal/contract/types';
+import { invariant } from '@internal/utils/assertions';
 import { blindCast } from '@internal/utils/casts';
 import { ifDefined } from '@internal/utils/defined';
 import { InternalError } from '@internal/utils/internal-error';
@@ -330,7 +331,7 @@ export function resolveEnumCodecId(
   ctx: AuthoringEntityContext,
 ): { readonly codecId: string; readonly codecSpan: PslSpan } | undefined {
   const sourceId = ctx.sourceId ?? 'unknown';
-  const typeAttr = block.blockAttributes.find((a) => a.name === 'type');
+  const typeAttr = block.attributes['type'];
 
   if (typeAttr === undefined) {
     const inferredKind = classifyEnumMemberType(block);
@@ -346,21 +347,9 @@ export function resolveEnumCodecId(
     return { codecId: ctx.enumInferenceCodecs[inferredKind], codecSpan: block.span };
   }
 
-  const rawCodecArg = typeAttr.args[0]?.value;
-  const codecId =
-    rawCodecArg?.startsWith('"') && rawCodecArg.endsWith('"') && rawCodecArg.length >= 2
-      ? rawCodecArg.slice(1, -1)
-      : undefined;
-  if (codecId === undefined) {
-    ctx.diagnostics?.push({
-      code: 'PSL_ENUM_MISSING_TYPE',
-      message: `enum "${block.name}" @@type attribute must have a quoted codec id argument`,
-      sourceId,
-      span: typeAttr.span,
-    });
-    return undefined;
-  }
-  return { codecId, codecSpan: typeAttr.args[0]?.span ?? typeAttr.span };
+  const codecId = typeAttr.args['codecId'];
+  invariant(typeof codecId === 'string', '@@type on an enum block parses one string argument');
+  return { codecId, codecSpan: typeAttr.span };
 }
 
 export interface AuthoringEntityTypeTemplateOutput {
@@ -464,6 +453,7 @@ export interface AuthoringPslBlockDescriptor {
     readonly parameter: string;
     readonly attribute: string;
   };
+  readonly attributes?: Readonly<Record<string, unknown>>;
 }
 
 export type AuthoringPslBlockDescriptorNamespace = {
@@ -735,7 +725,15 @@ function isWellFormedDescriptor(value: unknown, descriptorKind: string): boolean
       if (!('required' in name) || typeof name.required !== 'boolean') return false;
       if (!('parameters' in value)) return false;
       const parameters = value.parameters;
-      return typeof parameters === 'object' && parameters !== null && !Array.isArray(parameters);
+      if (typeof parameters !== 'object' || parameters === null || Array.isArray(parameters)) {
+        return false;
+      }
+      if (!('attributes' in value) || value.attributes === undefined) return true;
+      const attributes = value.attributes;
+      if (typeof attributes !== 'object' || attributes === null || Array.isArray(attributes)) {
+        return false;
+      }
+      return Object.values(attributes).every((factory) => typeof factory === 'function');
     }
     case 'modelAttribute': {
       if (

@@ -111,6 +111,7 @@ export type PslDiagnosticCode =
    * A `@@`-prefixed block-attribute line inside an extension block has invalid syntax.
    */
   | 'PSL_INVALID_EXTENSION_BLOCK_ATTRIBUTE'
+  | 'PSL_EXTENSION_UNKNOWN_BLOCK_ATTRIBUTE'
   /**
    * Duplicate scopes are top level, namespace body, or block fields; diagnostics
    * are first-wins and anchored on later name spans.
@@ -251,6 +252,11 @@ export interface PslExtensionBlockAttribute {
   readonly span: PslSpan;
 }
 
+export interface PslExtensionBlockParsedAttribute {
+  readonly args: Readonly<Record<string, unknown>>;
+  readonly span: PslSpan;
+}
+
 /**
  * Base shape for a uniform extension-contributed top-level PSL block
  * node, as produced by the generic framework parser and consumed by the
@@ -294,5 +300,6 @@ export interface PslExtensionBlock {
   readonly name: string;
   readonly parameters: Record<string, PslExtensionBlockParamValue>;
   readonly blockAttributes: readonly PslExtensionBlockAttribute[];
+  readonly attributes: Readonly<Record<string, PslExtensionBlockParsedAttribute>>;
   readonly span: PslSpan;
 }
@@ -722,6 +722,71 @@ describe('assembleAuthoringContributions', () => {
     ).toThrow(/Malformed authoring pslBlock contribution at "broken"/);
   });
 
+  it('keeps a pslBlockDescriptors entry that declares block attributes', () => {
+    const mapFactory = () => ({ level: 'block', name: 'map' });
+    const result = assembleAuthoringContributions([
+      createDescriptor({
+        authoring: {
+          entityTypes: {
+            foo: { kind: 'entity', discriminator: 'fake-foo', output: { factory: () => ({}) } },
+          },
+          pslBlockDescriptors: {
+            fooBlock: {
+              ...makeDeclarativePslBlockDescriptor('fake-foo'),
+              attributes: { map: mapFactory },
+            },
+          },
+        },
+      }),
+    ]);
+    expect(result.pslBlockDescriptors['fooBlock']).toMatchObject({
+      attributes: { map: mapFactory },
+    });
+  });
+
+  it.each([
+    ['an undefined factory', { map: undefined }],
+    ['a non-function factory', { map: 'map' }],
+  ])('rejects a pslBlockDescriptors entry whose attributes carries %s', (_label, attributes) => {
+    expect(() =>
+      assembleAuthoringContributions([
+        createDescriptor({
+          authoring: {
+            entityTypes: {
+              foo: { kind: 'entity', discriminator: 'fake-foo', output: { factory: () => ({}) } },
+            },
+            pslBlockDescriptors: {
+              fooBlock: {
+                ...makeDeclarativePslBlockDescriptor('fake-foo'),
+                attributes,
+              } as unknown as never,
+            },
+          },
+        }),
+      ]),
+    ).toThrow(/Malformed authoring pslBlock contribution at "fooBlock"/);
+  });
+
+  it('rejects a pslBlockDescriptors entry whose attributes is not a record', () => {
+    expect(() =>
+      assembleAuthoringContributions([
+        createDescriptor({
+          authoring: {
+            entityTypes: {
+              foo: { kind: 'entity', discriminator: 'fake-foo', output: { factory: () => ({}) } },
+            },
+            pslBlockDescriptors: {
+              fooBlock: {
+                ...makeDeclarativePslBlockDescriptor('fake-foo'),
+                attributes: 'map',
+              } as unknown as never,
+            },
+          },
+        }),
+      ]),
+    ).toThrow(/Malformed authoring pslBlock contribution at "fooBlock"/);
+  });
+
   it('descends into a pslBlockDescriptors sub-namespace whose key is "kind" or "discriminator" without triggering malformed check', () => {
     // A sub-namespace keyed "kind" or "discriminator" that does not itself
     // look like a descriptor must descend normally.

@@ -983,6 +983,7 @@ describe('classifyEnumMemberType', () => {
       name: 'TestEnum',
       parameters,
       blockAttributes: [],
+      attributes: {},
       span: testSpan,
     };
   }

@@ -21,7 +21,15 @@ function makeExtensionBlock(
   name: string,
   keyword: string = discriminator,
 ): PslExtensionBlock {
-  return { kind: discriminator, keyword, name, parameters: {}, blockAttributes: [], span: SPAN };
+  return {
+    kind: discriminator,
+    keyword,
+    name,
+    parameters: {},
+    blockAttributes: [],
+    attributes: {},
+    span: SPAN,
+  };
 }
 
 describe('makePslNamespace / makePslNamespaceEntries', () => {

@@ -11,6 +11,8 @@ import type {
   PslBlockParamOption,
   PslBlockParamRef,
   PslBlockParamValue,
+  PslExtensionBlock,
+  PslExtensionBlockParsedAttribute,
 } from '../src/shared/psl-extension-block';
 
 describe('PslBlockParam discriminated union', () => {
@@ -157,3 +159,30 @@ describe('isAuthoringPslBlockDescriptor', () => {
     }
   });
 });
+
+describe('block attributes', () => {
+  it('a descriptor declares its block attributes as erased factories, sibling of parameters', () => {
+    const descriptor = {
+      kind: 'pslBlock',
+      keyword: 'native_enum',
+      discriminator: 'native_enum',
+      name: { required: true },
+      parameters: {},
+      attributes: { map: () => ({ level: 'block', name: 'map' }) },
+    } as const;
+    expectTypeOf(descriptor).toMatchTypeOf<AuthoringPslBlockDescriptor>();
+    expectTypeOf<AuthoringPslBlockDescriptor['attributes']>().toEqualTypeOf<
+      Readonly<Record<string, unknown>> | undefined
+    >();
+  });
+
+  it('a block node carries its parsed attributes as plain data keyed by attribute name', () => {
+    expectTypeOf<PslExtensionBlock['attributes']>().toEqualTypeOf<
+      Readonly<Record<string, PslExtensionBlockParsedAttribute>>
+    >();
+    expectTypeOf<PslExtensionBlockParsedAttribute['args']>().toEqualTypeOf<
+      Readonly<Record<string, unknown>>
+    >();
+    expectTypeOf<Omit<PslExtensionBlock, 'attributes'>>().not.toMatchTypeOf<PslExtensionBlock>();
+  });
+});
@@ -127,6 +127,7 @@ function validNode(): PslExtensionBlock {
       using: { kind: 'value', raw: '"auth.uid() = user_id"', span: stubSpan() },
     },
     blockAttributes: [],
+    attributes: {},
   };
 }
 
@@ -511,6 +512,7 @@ describe('validateExtensionBlock', () => {
             target: { kind: 'ref', identifier: 'Post', span: stubSpan() },
           },
           blockAttributes: [],
+          attributes: {},
         };
 
         const diagnostics = validateExtensionBlock(
@@ -550,6 +552,7 @@ describe('validateExtensionBlock', () => {
             target: { kind: 'ref', identifier: 'Ghost', span: stubSpan() },
           },
           blockAttributes: [],
+          attributes: {},
         };
 
         const diagnostics = validateExtensionBlock(
@@ -638,6 +641,7 @@ describe('validateExtensionBlock', () => {
           },
         },
         blockAttributes: [],
+        attributes: {},
       };
 
       const diagnostics = validateExtensionBlock(node, listDescriptor, SOURCE_ID, codecLookup);
@@ -686,6 +690,7 @@ describe('validateExtensionBlock', () => {
           using: { kind: 'value', raw: 'not_quoted', span: stubSpan() },
         },
         blockAttributes: [],
+        attributes: {},
         // target (required) is missing
         // using (required) — present but invalid
       };

@@ -0,0 +1,38 @@
+import type { PslDiagnostic } from '@internal/framework-components/psl-ast';
+import type { AstNode } from '../syntax/ast-helpers';
+import type {
+  AttributeOut,
+  AttributeSpec,
+  BlockInterpretCtx,
+  Param,
+  PositionalParam,
+} from './types';
+
+interface BlockAttributeConfig<
+  Pos extends readonly PositionalParam<unknown, BlockInterpretCtx>[],
+  Named extends Record<string, Param<unknown, BlockInterpretCtx>>,
+> {
+  readonly positional?: Pos;
+  readonly named?: Named;
+  readonly refine?: (
+    parsed: AttributeOut<Pos, Named>,
+    ctx: BlockInterpretCtx,
+    attributeNode: AstNode,
+  ) => readonly PslDiagnostic[];
+}
+
+export function blockAttribute<
+  const Pos extends readonly PositionalParam<unknown, BlockInterpretCtx>[] = readonly [],
+  const Named extends Record<string, Param<unknown, BlockInterpretCtx>> = Record<never, never>,
+>(
+  name: string,
+  config: BlockAttributeConfig<Pos, Named>,
+): AttributeSpec<AttributeOut<Pos, Named>, BlockInterpretCtx> {
+  return {
+    level: 'block',
+    name,
+    positional: config.positional ?? [],
+    named: config.named ?? {},
+    ...(config.refine !== undefined ? { refine: config.refine } : {}),
+  };
+}
@@ -1,16 +1,17 @@
 import type { PslDiagnostic } from '@internal/framework-components/psl-ast';
 import { notOk, ok, type Result } from '@internal/utils/result';
 import { BooleanLiteralExprAst } from '../../syntax/ast/expressions';
-import type { ArgType } from '../types';
+import type { ArgType, BlockInterpretCtx } from '../types';
 import { leafDiagnostic } from './diagnostic';
 
-export function bool(): ArgType<boolean> {
+export function bool(): ArgType<boolean, BlockInterpretCtx> {
   return {
     kind: 'bool',
     label: 'boolean',
     parse: (arg, ctx): Result<boolean, readonly PslDiagnostic[]> => {
-      if (arg instanceof BooleanLiteralExprAst) {
-        const value = arg.value();
+      const literal = BooleanLiteralExprAst.cast(arg.syntax);
+      if (literal !== undefined) {
+        const value = literal.value();
         if (value !== undefined) return ok(value);
       }
       return notOk([leafDiagnostic(ctx, arg, 'Expected a boolean literal')]);

@@ -1,12 +1,12 @@
 import type { PslDiagnostic, PslDiagnosticCode } from '@internal/framework-components/psl-ast';
 import { nodePslSpan } from '../../resolve';
 import type { AstNode } from '../../syntax/ast-helpers';
-import type { InterpretCtx } from '../types';
+import type { BlockInterpretCtx } from '../types';
 
 export const ATTRIBUTE_DIAGNOSTIC_CODE: PslDiagnosticCode = 'PSL_INVALID_ATTRIBUTE_SYNTAX';
 
 export function leafDiagnostic(
-  ctx: InterpretCtx,
+  ctx: BlockInterpretCtx,
   node: AstNode,
   message: string,
   code: PslDiagnostic['code'] = ATTRIBUTE_DIAGNOSTIC_CODE,

@@ -11,10 +11,7 @@ export function entityRef(): ArgType<string> {
     kind: 'entityRef',
     label: 'model name',
     parse: (arg, ctx): Result<string, readonly PslDiagnostic[]> => {
-      if (!(arg instanceof IdentifierAst)) {
-        return notOk([leafDiagnostic(ctx, arg, 'Expected a model name')]);
-      }
-      const name = arg.name();
+      const name = IdentifierAst.cast(arg.syntax)?.name();
       if (name === undefined) {
         return notOk([leafDiagnostic(ctx, arg, 'Expected a model name')]);
       }