@prisma/orm-framework 0.16.0

package/dist/framework-authoring-7YMP9TwM-C9P-N6_a.d.mts

@@ -0,0 +1,777 @@
+import { M as ExecutionMutationDefaultPhases, a as ColumnDefault } from "./domain-envelope-D6Wn9AmZ-BqZKTT9U.mjs";
+import { c as CodecLookup } from "./codec-types-XJO6eC9U-B_K2q0zm.mjs";
+import { Type } from "arktype";
+//#region ../../../1-framework/1-core/framework-components/dist/framework-authoring-7YMP9TwM.d.mts
+//#region src/shared/option-descriptor.d.ts
+/**
+ * An enumerated-value parameter: the author supplies one of `values`, spelled
+ * as a bare token in PSL and a string literal in TypeScript. Shared by the
+ * extension-block parameter vocabulary (`PslBlockParamOption`) and the helper
+ * argument vocabulary (`AuthoringArgumentDescriptor`) so the option concept is
+ * declared once. See ADR 239.
+ */
+interface AuthoringOption {
+  readonly kind: 'option';
+  readonly values: readonly string[];
+}
+//#endregion
+//#region src/shared/psl-extension-block.d.ts
+interface PslPosition {
+  readonly offset: number;
+  readonly line: number;
+  readonly column: number;
+}
+interface PslSpan {
+  readonly start: PslPosition;
+  readonly end: PslPosition;
+}
+type PslDiagnosticCode = 'PSL_UNTERMINATED_BLOCK' | 'PSL_UNSUPPORTED_TOP_LEVEL_BLOCK' | 'PSL_INVALID_NAMESPACE_BLOCK' | 'PSL_INVALID_ATTRIBUTE_SYNTAX' | 'PSL_INVALID_MODEL_MEMBER' | 'PSL_UNSUPPORTED_MODEL_ATTRIBUTE' | 'PSL_UNSUPPORTED_FIELD_ATTRIBUTE' | 'PSL_INVALID_RELATION_ATTRIBUTE' | 'PSL_INVALID_REFERENTIAL_ACTION' | 'PSL_INVALID_DEFAULT_VALUE' | 'PSL_INVALID_ENUM_MEMBER' | 'PSL_INVALID_TYPES_MEMBER' | 'PSL_INVALID_QUALIFIED_TYPE' |
+/**
+ * A qualified name (e.g. a dotted type or attribute reference) is structurally
+ * invalid, such as an over-qualified or trailing-separator name.
+ */
+'PSL_INVALID_QUALIFIED_NAME' |
+/**
+ * A reserved declaration keyword (`model`/`enum`/`namespace`/`type`) that
+ * committed the declaration kind on the keyword alone but is missing its name
+ * and/or opening brace. The recursive-descent parser produces a best-effort
+ * typed node for the malformed header and reports this code rather than
+ * `PSL_UNSUPPORTED_TOP_LEVEL_BLOCK`, which is reserved for a genuinely unknown
+ * top-level keyword.
+ */
+'PSL_INVALID_DECLARATION' |
+/**
+ * A malformed line inside an extension-contributed top-level block body, or
+ * a structurally invalid element inside a `list` parameter value.
+ *
+ * Replaces the overloaded `PSL_UNSUPPORTED_TOP_LEVEL_BLOCK` code that the
+ * generic framework parser previously used for these two parse-error sites
+ * inside extension blocks — keeping `PSL_UNSUPPORTED_TOP_LEVEL_BLOCK` for
+ * its original meaning (an unknown keyword at the top level) and giving
+ * extension-block parse errors their own code.
+ */
+'PSL_INVALID_EXTENSION_BLOCK_MEMBER' |
+/**
+ * A malformed JS-like object literal `{ key: value, … }` in value/argument
+ * position — a field missing its `:`, a field missing its value, or an
+ * unterminated `{`. The recursive-descent parser still produces a best-effort
+ * `ObjectLiteralExpr` node (preserving the lossless round-trip) and reports
+ * this code anchored on the offending token.
+ */
+'PSL_INVALID_OBJECT_LITERAL' |
+/**
+ * A string literal with no closing quote — the tokenizer stops the literal at
+ * a newline or at EOF when no terminating `"` is found, and the
+ * recursive-descent parser still consumes the token (preserving the lossless
+ * round-trip) but reports this code anchored on the string token's span.
+ */
+'PSL_UNTERMINATED_STRING' |
+/**
+ * An unknown parameter key in an extension-contributed block — a key present
+ * in the source block but absent from the descriptor's `parameters` map.
+ */
+'PSL_EXTENSION_UNKNOWN_PARAMETER' |
+/**
+ * A required parameter declared in the descriptor is absent from the parsed block.
+ */
+'PSL_EXTENSION_MISSING_REQUIRED_PARAMETER' |
+/**
+ * An `option`-kind parameter value is not one of the allowed tokens listed
+ * in the descriptor's `values` array.
+ */
+'PSL_EXTENSION_OPTION_OUT_OF_SET' |
+/**
+ * A `value`-kind parameter's raw text is not a valid JSON literal, or the
+ * parsed JSON value was rejected by the codec's `decodeJson` method, or the
+ * codec id is not registered in the lookup.
+ */
+'PSL_EXTENSION_INVALID_VALUE' |
+/**
+ * A `ref`-kind parameter identifier does not resolve to a declared entity of
+ * the required `refKind` within the declared scope.
+ */
+'PSL_EXTENSION_UNRESOLVED_REF' |
+/**
+ * A parameter key appears more than once in an extension block body.
+ * The first occurrence is kept; subsequent occurrences emit this diagnostic.
+ */
+'PSL_EXTENSION_DUPLICATE_PARAMETER' |
+/**
+ * A `@@`-prefixed block-attribute line inside an extension block has invalid syntax.
+ */
+'PSL_INVALID_EXTENSION_BLOCK_ATTRIBUTE' |
+/**
+ * Duplicate scopes are top level, namespace body, or block fields; diagnostics
+ * are first-wins and anchored on later name spans.
+ */
+'PSL_DUPLICATE_DECLARATION';
+/**
+ * A PSL diagnostic code contributed by a family or target package (e.g. an
+ * attribute-spec refine in a family's authoring layer). The framework union
+ * above stays the parser's own vocabulary; contributed codes share the
+ * `PSL_` pattern but their names are owned by the contributing package —
+ * no family or target vocabulary enters this module. Contributed codes
+ * must not reuse a framework code name; pick a domain-scoped prefix
+ * segment (e.g. `PSL_INDEX_`, `PSL_POLICY_`) to keep the namespaces
+ * collision-free.
+ */
+type ContributedPslDiagnosticCode = `PSL_${string}`;
+/**
+ * Descriptor vocabulary for a single parameter on a declared block.
+ *
+ * Four kinds:
+ * - `ref` — the parameter value is an identifier that must resolve to a
+ *   declared entity of `refKind` within the declared `scope`.
+ * - `value` — the parameter value is a PSL literal parsed and printed
+ *   through the codec identified by `codecId`.
+ * - `option` — the parameter value is one of the literal tokens in `values`.
+ *   Not a codec; not persisted data. A closed authoring-time constraint only.
+ * - `list` — a bracketed list whose elements each match the `of` descriptor.
+ */
+type PslBlockParam = PslBlockParamRef | PslBlockParamValue | PslBlockParamOption | PslBlockParamList;
+interface PslBlockParamRef {
+  readonly kind: 'ref';
+  readonly refKind: string;
+  readonly scope: 'same-namespace' | 'same-space' | 'cross-space';
+  readonly required?: boolean;
+}
+interface PslBlockParamValue {
+  readonly kind: 'value';
+  readonly codecId: string;
+  readonly required?: boolean;
+}
+interface PslBlockParamOption extends AuthoringOption {
+  readonly required?: boolean;
+}
+interface PslBlockParamList {
+  readonly kind: 'list';
+  readonly of: PslBlockParam;
+  readonly required?: boolean;
+}
+/**
+ * The parsed representation of a single parameter value on a uniform
+ * extension-block AST node. Mirrors the `PslBlockParam` descriptor
+ * vocabulary, plus `bare` for keyonly entries:
+ *
+ * - `ref`    → `PslExtensionBlockParamRef` — a raw identifier string
+ *   (resolution runs in the validator, not the parser).
+ * - `value`  → `PslExtensionBlockParamScalarValue` — a raw PSL literal string
+ *   (codec validation runs in the validator).
+ * - `option` → `PslExtensionBlockParamOption` — the chosen token.
+ * - `list`   → `PslExtensionBlockParamList` — ordered list of the above.
+ * - `bare`   → `PslExtensionBlockParamBare` — a bare identifier line with no
+ *   `= value` (e.g. `Low` in an enum block). The name is the key in
+ *   `parameters`; the interpreting consumer decides the default value.
+ *
+ * These shapes are intentionally minimal. The validator and lowering refine
+ * and consume them; the generic framework parser produces them.
+ */
+type PslExtensionBlockParamValue = PslExtensionBlockParamRef | PslExtensionBlockParamScalarValue | PslExtensionBlockParamOption | PslExtensionBlockParamList | PslExtensionBlockParamBare;
+interface PslExtensionBlockParamRef {
+  readonly kind: 'ref';
+  readonly identifier: string;
+  readonly span: PslSpan;
+}
+interface PslExtensionBlockParamScalarValue {
+  readonly kind: 'value';
+  readonly raw: string;
+  readonly span: PslSpan;
+}
+interface PslExtensionBlockParamOption {
+  readonly kind: 'option';
+  readonly token: string;
+  readonly span: PslSpan;
+}
+interface PslExtensionBlockParamList {
+  readonly kind: 'list';
+  readonly items: readonly PslExtensionBlockParamValue[];
+  readonly span: PslSpan;
+}
+/**
+ * A bare identifier line inside an extension block — a key with no `= value`.
+ * Emitted when a line matches `/^[A-Za-z_]\w*$/` with no assignment. The
+ * consumer decides what default value (if any) to apply.
+ */
+interface PslExtensionBlockParamBare {
+  readonly kind: 'bare';
+  readonly span: PslSpan;
+}
+/**
+ * A positional argument on a block attribute, e.g. the `"pg/text@1"` in
+ * `@@type("pg/text@1")`.
+ */
+interface PslExtensionBlockAttributeArg {
+  readonly kind: 'positional';
+  readonly value: string;
+  readonly span: PslSpan;
+}
+/**
+ * A `@@`-prefixed block-level attribute parsed inside an extension block,
+ * e.g. `@@type("pg/text@1")`. Block attributes are captured generically
+ * — the parser does not validate attribute names or argument shapes; that
+ * is a concern of the block's interpreter.
+ */
+interface PslExtensionBlockAttribute {
+  readonly name: string;
+  readonly args: readonly PslExtensionBlockAttributeArg[];
+  readonly span: PslSpan;
+}
+/**
+ * Base shape for a uniform extension-contributed top-level PSL block
+ * node, as produced by the generic framework parser and consumed by the
+ * validator, printer, and lowering factory.
+ *
+ * - `kind` is the routing discriminant, equal to the descriptor's
+ *   `discriminator`. The framework parser sets this to
+ *   `descriptor.discriminator` for every block it parses. Several keywords
+ *   may share one discriminator (e.g. `policy_select`/`policy_insert` both
+ *   route to `kind: 'policy'`) — `kind` identifies the entity/storage kind,
+ *   not the source syntax.
+ * - `keyword` is the source PSL keyword the block was declared with
+ *   (`policy_select`, `policy_insert`, …) — the parse-dispatch identity.
+ *   Distinct from `kind` precisely when a discriminator is shared by more
+ *   than one keyword; a lowering factory that contributes several keywords
+ *   under one discriminator reads `keyword` to tell its blocks apart, and
+ *   the printer re-emits each block under its own `keyword` regardless of
+ *   how many other keywords share its `kind`.
+ * - `name` is the block's declared name (the identifier after the keyword).
+ * - `parameters` is the descriptor-driven parameter map. Keys are
+ *   parameter names from the descriptor; values are the parsed parameter
+ *   representations. Only parameters present in the source are included
+ *   — absence of a required parameter is a validator concern, not a
+ *   parser concern. Insertion order is preserved; the first occurrence of a
+ *   duplicate key is retained and subsequent occurrences emit
+ *   `PSL_EXTENSION_DUPLICATE_PARAMETER`.
+ * - `blockAttributes` are `@@`-prefixed attribute lines inside the block, in
+ *   declaration order. Captured generically — names and args are not validated
+ *   by the parser.
+ * - `span` covers the full block from keyword to closing brace.
+ */
+interface PslExtensionBlock {
+  readonly kind: string;
+  /**
+   * The block's parse identity — the source PSL keyword it was declared
+   * with. `kind`/`discriminator` is its storage identity; several keywords
+   * can share one. E.g. the five `policy_*` keywords all lower to the
+   * `policy` entity kind.
+   */
+  readonly keyword: string;
+  readonly name: string;
+  readonly parameters: Record<string, PslExtensionBlockParamValue>;
+  readonly blockAttributes: readonly PslExtensionBlockAttribute[];
+  readonly span: PslSpan;
+}
+//#endregion
+//#region src/shared/framework-authoring.d.ts
+type AuthoringArgRef = {
+  readonly kind: 'arg';
+  readonly index: number;
+  readonly path?: readonly string[];
+  readonly default?: AuthoringTemplateValue;
+};
+/**
+ * Selects among `cases` by the value of the referenced argument: the resolved
+ * value must be one of the case keys, and the node resolves to that case's
+ * recursively resolved template. An absent argument resolves to `undefined`,
+ * which the enclosing object template omits entirely.
+ *
+ * Case coverage is validated against the referenced option argument's
+ * `values` at pack-registration time, so the runtime miss-throw is an
+ * assertion for type-bypassing callers, not a user-facing diagnostic.
+ *
+ * Must not be used in the `codecId`/`nullable`/`id`/`unique` positions of a
+ * preset output: the type-level `ResolveTemplateValue` does not implement
+ * select, and those fields feed TS builder-state inference. See ADR 239.
+ */
+interface AuthoringSelectRef {
+  readonly kind: 'select';
+  readonly index: number;
+  readonly path?: readonly string[];
+  readonly cases: Readonly<Record<string, AuthoringTemplateValue>>;
+}
+type AuthoringTemplateValue = string | number | boolean | null | AuthoringArgRef | AuthoringSelectRef | readonly AuthoringTemplateValue[] | {
+  readonly [key: string]: AuthoringTemplateValue;
+};
+interface AuthoringArgumentDescriptorCommon {
+  readonly name?: string;
+  readonly optional?: boolean;
+}
+type AuthoringArgumentDescriptor = AuthoringArgumentDescriptorCommon & ({
+  readonly kind: 'string';
+} | {
+  readonly kind: 'boolean';
+} | {
+  readonly kind: 'number';
+  readonly integer?: boolean;
+  readonly minimum?: number;
+  readonly maximum?: number;
+} | {
+  readonly kind: 'stringArray';
+} | {
+  readonly kind: 'object';
+  readonly properties: Record<string, AuthoringArgumentDescriptor>;
+} | AuthoringOption);
+interface AuthoringStorageTypeTemplate {
+  readonly codecId: string;
+  /**
+   * The storage type's base name — a plain string, never a template:
+   * parameters live in `typeParams` and the DDL renderer composes them.
+   * Optional so a type constructor whose {@link AuthoringTypeConstructorDescriptor.entityRefArg}
+   * names another entity can omit it entirely — its output for that case is
+   * derived by the codec at `codecId`. Every other consumer of this shape
+   * (field presets, plain type constructors) always supplies it.
+   */
+  readonly nativeType?: string;
+  readonly typeParams?: Record<string, AuthoringTemplateValue>;
+}
+/**
+ * Declares that one positional argument of a
+ * {@link AuthoringTypeConstructorDescriptor} call names another entity
+ * parsed from the same document, rather than carrying a literal value (e.g.
+ * `pg.enum(AalLevel)` naming a `native_enum` entity). `index` is the
+ * argument's position in the call; `entityKind` is the entries-slot
+ * discriminator the interpreter looks the named entity up under (the same
+ * shape {@link AuthoringEntityTypeFactoryOutput.factory} output is collected
+ * into, keyed by discriminator then block name).
+ *
+ * The interpreter resolves the named argument to the entity instance
+ * generically, driven only by this declaration — it has no target-specific
+ * knowledge of which type constructors carry one. Converting the resolved
+ * entity into the constructor's params is a separate, codec-owned concern:
+ * the codec descriptor registered for `output.codecId` supplies that
+ * conversion, not this framework type.
+ */
+interface AuthoringTypeConstructorEntityRef {
+  readonly index: number;
+  readonly entityKind: string;
+}
+interface AuthoringTypeConstructorDescriptor {
+  readonly kind: 'typeConstructor';
+  readonly args?: readonly AuthoringArgumentDescriptor[];
+  readonly output: AuthoringStorageTypeTemplate;
+  /** Present when one of this constructor's positional arguments names another document-local entity instead of carrying a literal value. Absent for ordinary literal-argument constructors. */
+  readonly entityRefArg?: AuthoringTypeConstructorEntityRef;
+}
+interface AuthoringColumnDefaultTemplateLiteral {
+  readonly kind: 'literal';
+  readonly value: AuthoringTemplateValue;
+}
+interface AuthoringColumnDefaultTemplateFunction {
+  readonly kind: 'function';
+  readonly expression: AuthoringTemplateValue;
+}
+type AuthoringColumnDefaultTemplate = AuthoringColumnDefaultTemplateLiteral | AuthoringColumnDefaultTemplateFunction;
+interface AuthoringExecutionDefaultsTemplate {
+  readonly onCreate?: AuthoringTemplateValue;
+  readonly onUpdate?: AuthoringTemplateValue;
+}
+interface AuthoringFieldPresetOutput extends AuthoringStorageTypeTemplate {
+  readonly nullable?: boolean;
+  readonly default?: AuthoringColumnDefaultTemplate;
+  readonly executionDefaults?: AuthoringExecutionDefaultsTemplate;
+  readonly id?: boolean;
+  readonly unique?: boolean;
+}
+interface AuthoringFieldPresetDescriptor {
+  readonly kind: 'fieldPreset';
+  readonly args?: readonly AuthoringArgumentDescriptor[];
+  readonly output: AuthoringFieldPresetOutput;
+}
+type AuthoringTypeNamespace = {
+  readonly [name: string]: AuthoringTypeConstructorDescriptor | AuthoringTypeNamespace;
+};
+type AuthoringFieldNamespace = {
+  readonly [name: string]: AuthoringFieldPresetDescriptor | AuthoringFieldNamespace;
+};
+/**
+ * Context surfaced to entity-type factories at call time. Currently a
+ * placeholder — sharpened as concrete consumers (enum, namespace, …)
+ * discover what the factory actually needs to read (codec lookup,
+ * namespace registry, …).
+ */
+/**
+ * A write-only sink that a factory may push authoring-time diagnostics into.
+ * The concrete type pushed must be structurally compatible with whatever the
+ * consumer accumulates (typically `ContractSourceDiagnostic[]`); the framework
+ * layer deliberately does not depend on that concrete type.
+ */
+interface AuthoringDiagnosticSink {
+  push(d: {
+    readonly code: string;
+    readonly message: string;
+    readonly sourceId: string;
+    readonly span?: unknown;
+  }): void;
+}
+/**
+ * A non-fatal advisory minted at authoring time. Fully formed at the push
+ * site — the transport and the flush never learn family or target
+ * vocabulary. Warnings batch together iff `code` AND `summary` match: the
+ * batched rendering asserts the summary of every member, so the grouping
+ * key must cover everything the summary claims.
+ */
+interface AuthoringWarning {
+  /** Stable machine code — what the user greps and what `process.emitWarning` stamps. */
+  readonly code: string;
+  /** Full text emitted when the warning is itemized (group at or below the batch threshold). */
+  readonly message: string;
+  /** Short subject label listed under a batched group summary (e.g. `object "…"`). */
+  readonly item: string;
+  /**
+   * Group summary text — what a batched group asserts about EVERY member.
+   * An over-threshold group renders as `"<count> <summary>"` above the item
+   * lines, so this starts with the plural noun phrase (e.g.
+   * `objects use <feature>. <remediation>`).
+   */
+  readonly summary: string;
+}
+/**
+ * A write-only sink for non-fatal authoring-time warnings a factory may
+ * emit. Entries travel verbatim to a single per-build flush — no
+ * narrowing, no per-kind fields; a plain `AuthoringWarning[]` satisfies
+ * this structurally.
+ */
+interface AuthoringWarningSink {
+  push(w: AuthoringWarning): void;
+}
+/**
+ * Emits collected authoring warnings once per build, grouped by `code`:
+ * a group at or below the threshold itemizes every `message`; above it,
+ * one summary — `"<count> <summary>"` followed by the `item` lines — so
+ * a build with many hits of one kind does not wall-of-text, and warnings
+ * of different codes never batch into each other's summary.
+ */
+declare function flushAuthoringWarnings(warnings: readonly AuthoringWarning[]): void;
+interface AuthoringEntityContext {
+  readonly family: string;
+  readonly target: string;
+  /** Codec registry available to factories that need to validate or decode values. */
+  readonly codecLookup?: CodecLookup;
+  /** Source file identifier threaded into diagnostics emitted by the factory. */
+  readonly sourceId?: string;
+  /** Push channel for authoring-time diagnostics emitted by the factory. */
+  readonly diagnostics?: AuthoringDiagnosticSink;
+  /** Push channel for non-fatal authoring-time warnings emitted by the factory. */
+  readonly warnings?: AuthoringWarningSink;
+  /**
+   * The target's default codec ids for an `enum` block that omits `@@type`.
+   * `text` is used when every member is a bare name or a string value;
+   * `int` is used when every member is an integer value. Every target pack
+   * populates this so `@@type` omission can be inferred consistently.
+   */
+  readonly enumInferenceCodecs?: {
+    readonly text: string;
+    readonly int: string;
+  };
+}
+/**
+ * Classifies an `enum` block's members (before codec decoding, which needs
+ * the codec chosen first) into which default codec an omitted `@@type`
+ * should resolve to:
+ *
+ * - every member is `bare`, or a `value` whose raw JSON is a string → `'text'`
+ * - every member is a `value` whose raw JSON is an integer → `'int'`
+ * - anything else (float, bigint, boolean, mixed, or a `ref`/`option`/`list`
+ *   parameter) → `null`, meaning the caller must require an explicit `@@type`.
+ */
+declare function classifyEnumMemberType(block: PslExtensionBlock): 'text' | 'int' | null;
+/**
+ * Resolves the codec id for an `enum` block. When `@@type` is absent, the codec
+ * is inferred from the members via {@link classifyEnumMemberType}; otherwise the
+ * explicit `@@type("codec")` argument is parsed. Pushes the appropriate
+ * diagnostic and returns `undefined` when neither yields a codec. `codecSpan` is
+ * the span downstream codec-validation diagnostics should anchor to. Shared by
+ * every family's enum factory so inference and the explicit path stay identical.
+ */
+declare function resolveEnumCodecId(block: PslExtensionBlock, ctx: AuthoringEntityContext): {
+  readonly codecId: string;
+  readonly codecSpan: PslSpan;
+} | undefined;
+interface AuthoringEntityTypeTemplateOutput {
+  readonly template: AuthoringTemplateValue;
+}
+/**
+ * Default `Input = never` is load-bearing for pack-bag-driven type
+ * narrowing. Factory parameter positions are contravariant, so a pack
+ * literal declaring `factory: (input: DemoEntityInput) => DemoEntity`
+ * is only assignable to the base descriptor's factory shape if the
+ * base's input is `never` (the bottom of the contravariant position).
+ * The concrete input/output types are recovered at the helper-derivation
+ * site via `EntityHelperFunction<Descriptor>`'s conditional inference,
+ * which reads them from the pack's `as const` literal factory signature
+ * — the base widening does not erase the literal because `satisfies`
+ * does not widen the declared type.
+ */
+interface AuthoringEntityTypeFactoryOutput<Input = never, Output = unknown> {
+  readonly factory: (input: Input, ctx: AuthoringEntityContext) => Output;
+}
+interface AuthoringEntityTypeDescriptor<Input = never, Output = unknown> {
+  readonly kind: 'entity';
+  readonly discriminator: string;
+  readonly args?: readonly AuthoringArgumentDescriptor[];
+  readonly output: AuthoringEntityTypeTemplateOutput | AuthoringEntityTypeFactoryOutput<Input, Output>;
+  /**
+   * arktype schema fragment for one entry whose envelope `kind` matches
+   * this descriptor's {@link discriminator}. The family validator composes
+   * contributed fragments into the per-namespace entry schema at
+   * validator construction time so the structural check covers
+   * pack-introduced kinds without the family core hard-coding the schema.
+   *
+   * Hydration uses {@link AuthoringEntityTypeFactoryOutput.factory}
+   * directly — the wire shape conforms structurally to the factory's
+   * `Input` after `validatorSchema` validates it.
+   */
+  readonly validatorSchema?: Type<unknown>;
+}
+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.
+ */
+interface AuthoringPslBlockDescriptor {
+  readonly kind: 'pslBlock';
+  readonly keyword: string;
+  readonly discriminator: string;
+  readonly name: {
+    readonly required: boolean;
+  };
+  readonly parameters: Record<string, PslBlockParam>;
+  /**
+   * When `true`, the block body accepts a variadic tail of parameters beyond
+   * the declared set. The block body may contain: fields (model-style),
+   * `key = value` parameters, and `@@` attributes. With `variadicParameters`,
+   * bare identifiers (keys without a `= value`) and undeclared `key = value`
+   * pairs flow into the variadic tail — their semantics belong to the
+   * lowering, not the parser.
+   *
+   * A key that IS declared in `parameters` must still be supplied as
+   * `key = value`; a bare occurrence of a declared key is a diagnostic.
+   *
+   * When `false` (default), the validator emits `PSL_EXTENSION_UNKNOWN_PARAMETER`
+   * for keys absent from `parameters`.
+   */
+  readonly variadicParameters?: boolean;
+  /**
+   * Declares that the model named by the block's ref parameter `parameter`
+   * must carry the bare `@@` model attribute `attribute`. The family
+   * interpreter enforces this generically over the whole parsed document —
+   * declaration order of the block and the model does not matter — and
+   * emits `PSL_EXTENSION_TARGET_MODEL_MISSING_ATTRIBUTE` naming the block
+   * and the model when the attribute is absent. A parameter that is
+   * missing or does not resolve to a model is not this rule's concern
+   * (missing-parameter and unresolved-ref diagnostics own those cases).
+   */
+  readonly requiresModelAttribute?: {
+    readonly parameter: string;
+    readonly attribute: string;
+  };
+}
+type AuthoringPslBlockDescriptorNamespace = {
+  readonly [name: string]: AuthoringPslBlockDescriptor | AuthoringPslBlockDescriptorNamespace;
+};
+/**
+ * Context surfaced to a model-attribute lowering at call time: the entity
+ * context shared with entity-type factories, plus the declaring model's
+ * name, its mapped storage name (the name of the storage object the model
+ * maps to; which kind of object that is belongs to the family, not the
+ * framework), and the namespace id the lowered entity should be filed
+ * under.
+ */
+interface AuthoringModelAttributeContext extends AuthoringEntityContext {
+  readonly modelName: string;
+  readonly storageName: string;
+  readonly namespaceId: string;
+}
+/**
+ * What a model-attribute lowering returns when it produces an entity: `key`
+ * is the identity the entity is stored under within its `entries` slot
+ * (`entries[attribute][key]`); `entity` is the value stored there. A
+ * lowering that instead pushed a diagnostic through
+ * {@link AuthoringModelAttributeContext.diagnostics} returns `undefined` —
+ * the same convention {@link AuthoringEntityTypeFactoryOutput} uses.
+ */
+interface AuthoringModelAttributeLoweringOutput {
+  readonly key: string;
+  readonly entity: unknown;
+}
+/**
+ * Declarative descriptor for an extension-contributed `@@` model attribute.
+ *
+ * An extension registers one of these per bare attribute name it
+ * contributes. The framework owns the generic consult in the interpreter's
+ * model-attribute loop; the contribution supplies only `spec` and `lower`.
+ *
+ * - `attribute` is the bare `@@` attribute name this descriptor claims and,
+ *   by the one-string rule, the `entries` slot its lowered entities are
+ *   grouped under (`entries[attribute][key]`).
+ * - `spec` is opaque to the framework core: an ADR-231 attribute-spec kit
+ *   `AttributeSpec<Out>` value (`modelAttribute(name, {...})` from
+ *   `@internal/psl-parser`). Framework core does not depend on
+ *   psl-parser and never inspects this field; the family interpreter,
+ *   which does depend on psl-parser, parses the attribute's arguments
+ *   against it.
+ * - `lower` receives the parsed arguments and the declaring model's
+ *   context, and returns the entity to file into `entries`, or `undefined`
+ *   after pushing a diagnostic via `ctx.diagnostics`.
+ *
+ * `Out` defaults to `never` — not `unknown` — for the same contravariance
+ * reason documented on {@link AuthoringEntityTypeFactoryOutput}: a concrete
+ * pack literal's narrower `lower(parsed: ConcreteOut, ctx)` is only
+ * assignable to this base shape when the base parameter is the bottom type.
+ */
+interface AuthoringModelAttributeDescriptor<Out = never> {
+  readonly kind: 'modelAttribute';
+  readonly attribute: string;
+  readonly spec: unknown;
+  readonly lower: (parsed: Out, ctx: AuthoringModelAttributeContext) => AuthoringModelAttributeLoweringOutput | undefined;
+}
+type AuthoringModelAttributeDescriptorNamespace = {
+  readonly [name: string]: AuthoringModelAttributeDescriptor | AuthoringModelAttributeDescriptorNamespace;
+};
+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 the parsed block nodes themselves, which live in a
+   * namespace's `entries` under their discriminator key; this field holds the
+   * registry of descriptors that teach the parser how to read those blocks.
+   */
+  readonly pslBlockDescriptors?: AuthoringPslBlockDescriptorNamespace;
+  /**
+   * Registry of declarative `@@` model attribute descriptors this
+   * contribution registers, keyed by arbitrary path segments. Each leaf is
+   * an {@link AuthoringModelAttributeDescriptor} that claims a bare model
+   * attribute name. The framework owns the generic consult in the family
+   * interpreter's model-attribute loop; the contribution supplies only the
+   * declarative spec and the lowering.
+   */
+  readonly modelAttributes?: AuthoringModelAttributeDescriptorNamespace;
+  /**
+   * Names the top-level type constructor that stores embedded value-object
+   * fields (fields typed as a value-object `type` block). A single named
+   * slot per component makes within-component ambiguity impossible by
+   * shape. Assembly rejects two components both declaring it, validates
+   * that the assembled namespace carries the named constructor as a
+   * top-level bare-eligible entry (see
+   * {@link collectScalarTypeConstructors}), and exposes the single value to
+   * family interpreters — so family layers never hardcode a target's type
+   * names.
+   */
+  readonly valueObjectStorageType?: string;
+}
+declare function isAuthoringArgRef(value: unknown): value is AuthoringArgRef;
+declare function isAuthoringTypeConstructorDescriptor(value: AuthoringTypeConstructorDescriptor | AuthoringTypeNamespace): value is AuthoringTypeConstructorDescriptor;
+declare function isAuthoringFieldPresetDescriptor(value: AuthoringFieldPresetDescriptor | AuthoringFieldNamespace): value is AuthoringFieldPresetDescriptor;
+declare function isAuthoringEntityTypeDescriptor(value: AuthoringEntityTypeDescriptor | AuthoringEntityTypeNamespace): value is AuthoringEntityTypeDescriptor;
+declare function isAuthoringPslBlockDescriptor(value: AuthoringPslBlockDescriptor | AuthoringPslBlockDescriptorNamespace): value is AuthoringPslBlockDescriptor;
+declare function isAuthoringModelAttributeDescriptor(value: AuthoringModelAttributeDescriptor | AuthoringModelAttributeDescriptorNamespace): value is AuthoringModelAttributeDescriptor;
+/**
+ * Returns true when `namespace` is a non-leaf key in `contributions.field`.
+ *
+ * `AuthoringFieldNamespace` permits a leaf descriptor at any depth — including
+ * the root — so a top-level `field: { Foo: { kind: 'fieldPreset', ... } }`
+ * registration must NOT be treated as a "namespace" with sub-paths. Callers
+ * use this predicate to gate dot-namespaced lookups (e.g. PSL `@Foo.bar`).
+ */
+declare function hasRegisteredFieldNamespace(contributions: AuthoringContributions | undefined, namespace: string): boolean;
+/**
+ * Merges `source` into `target` recursively at the descriptor-namespace
+ * level. `descriptorKind` is the `kind` value ('typeConstructor',
+ * 'fieldPreset', 'entity', or 'pslBlock') that identifies a descriptor
+ * (terminal merge point; same-path registrations across components are
+ * reported as duplicates) as opposed to a sub-namespace (recursion target).
+ *
+ * Path segments are validated against prototype-pollution names
+ * (`__proto__`, `constructor`, `prototype`). A value that is neither a
+ * recognized leaf nor a plain object — e.g. a malformed descriptor
+ * where the canonical leaf guard rejected it for missing `output` —
+ * is reported as an invalid contribution rather than recursed into,
+ * which would either silently mangle state or infinite-loop on
+ * primitive properties.
+ *
+ * Within-registry duplicate detection is this walker's job;
+ * cross-registry detection runs separately via
+ * `assertNoCrossRegistryCollisions` after merging completes.
+ */
+declare function mergeAuthoringNamespaces(target: Record<string, unknown>, source: Record<string, unknown>, path: readonly string[], descriptorKind: string, label: string): void;
+interface ScalarTypeConstructorOutput {
+  readonly codecId: string;
+  readonly nativeType: string;
+  readonly typeParams?: Record<string, unknown>;
+}
+/**
+ * Derives the scalar view of an assembled authoring type namespace: every
+ * **top-level** type constructor that is instantiable with an empty argument
+ * list — all declared args optional and no entity-ref argument. A bare type
+ * name `T` in a schema is semantically the zero-arg instantiation `T()`, so
+ * each entry is exactly what that call produces (defaulted template values
+ * applied, absent optional-arg typeParams keys omitted). Constructors
+ * registered under a namespace segment, constructors with required args, and
+ * entity-ref constructors are not scalars and are excluded.
+ *
+ * Eligibility needs no template inspection: templates that cannot resolve
+ * for their legal call shapes are rejected at the composition boundary by
+ * {@link assertResolvableTypeConstructorTemplates}, so the zero-arg
+ * instantiation below cannot fail for an eligible constructor.
+ */
+declare function collectScalarTypeConstructors(namespace: AuthoringTypeNamespace): ReadonlyMap<string, ScalarTypeConstructorOutput>;
+/**
+ * Boundary validation for a contributed authoring type namespace, called
+ * per contributing component at assembly (which supplies `contributedBy`
+ * for attribution). Rejects what the types cannot express — entity-ref
+ * constructors are skipped (their output derives from the referenced
+ * entity): a plain constructor must declare its output storage type name,
+ * and every `typeParams` arg-ref (including refs inside arg-ref defaults)
+ * must point at a declared argument index.
+ */
+declare function assertResolvableTypeConstructorTemplates(namespace: AuthoringTypeNamespace, contributedBy: string, path?: readonly string[]): void;
+declare function assertNoCrossRegistryCollisions(typeNamespace: AuthoringTypeNamespace, fieldNamespace: AuthoringFieldNamespace, entityTypeNamespace?: AuthoringEntityTypeNamespace, pslBlockNamespace?: AuthoringPslBlockDescriptorNamespace, modelAttributeNamespace?: AuthoringModelAttributeDescriptorNamespace): void;
+declare function resolveAuthoringTemplateValue(template: AuthoringTemplateValue | undefined, args: readonly unknown[]): unknown;
+declare function validateAuthoringHelperArguments(helperPath: string, descriptors: readonly AuthoringArgumentDescriptor[] | undefined, args: readonly unknown[]): void;
+declare function instantiateAuthoringTypeConstructor(descriptor: AuthoringTypeConstructorDescriptor, args: readonly unknown[]): {
+  readonly codecId: string;
+  readonly nativeType: string;
+  readonly typeParams?: Record<string, unknown>;
+};
+declare function instantiateAuthoringEntityType<TOutput = unknown>(helperPath: string, descriptor: AuthoringEntityTypeDescriptor, args: readonly unknown[], ctx: AuthoringEntityContext): TOutput;
+declare function instantiateAuthoringFieldPreset(descriptor: AuthoringFieldPresetDescriptor, args: readonly unknown[]): {
+  readonly descriptor: {
+    readonly codecId: string;
+    readonly nativeType: string;
+    readonly typeParams?: Record<string, unknown>;
+  };
+  readonly nullable: boolean;
+  readonly default?: ColumnDefault;
+  readonly executionDefaults?: ExecutionMutationDefaultPhases;
+  readonly id: boolean;
+  readonly unique: boolean;
+};
+//#endregion
+export { hasRegisteredFieldNamespace as $, PslBlockParam as A, PslExtensionBlockParamList as B, AuthoringTemplateValue as C, AuthoringWarning as D, AuthoringTypeNamespace as E, PslDiagnosticCode as F, PslPosition as G, PslExtensionBlockParamRef as H, PslExtensionBlock as I, assertNoCrossRegistryCollisions as J, PslSpan as K, PslExtensionBlockAttribute as L, PslBlockParamOption as M, PslBlockParamRef as N, AuthoringWarningSink as O, PslBlockParamValue as P, flushAuthoringWarnings as Q, PslExtensionBlockAttributeArg as R, AuthoringStorageTypeTemplate as S, AuthoringTypeConstructorEntityRef as T, PslExtensionBlockParamScalarValue as U, PslExtensionBlockParamOption as V, PslExtensionBlockParamValue as W, classifyEnumMemberType as X, assertResolvableTypeConstructorTemplates as Y, collectScalarTypeConstructors as Z, AuthoringModelAttributeLoweringOutput as _, AuthoringDiagnosticSink as a, isAuthoringFieldPresetDescriptor as at, AuthoringPslBlockDescriptorNamespace as b, AuthoringEntityTypeFactoryOutput as c, isAuthoringTypeConstructorDescriptor as ct, AuthoringFieldNamespace as d, resolveEnumCodecId as dt, instantiateAuthoringEntityType as et, AuthoringFieldPresetDescriptor as f, validateAuthoringHelperArguments as ft, AuthoringModelAttributeDescriptorNamespace as g, AuthoringModelAttributeDescriptor as h, AuthoringContributions as i, isAuthoringEntityTypeDescriptor as it, PslBlockParamList as j, ContributedPslDiagnosticCode as k, AuthoringEntityTypeNamespace as l, mergeAuthoringNamespaces as lt, AuthoringModelAttributeContext as m, AuthoringArgumentDescriptor as n, instantiateAuthoringTypeConstructor as nt, AuthoringEntityContext as o, isAuthoringModelAttributeDescriptor as ot, AuthoringFieldPresetOutput as p, ScalarTypeConstructorOutput as q, AuthoringColumnDefaultTemplate as r, isAuthoringArgRef as rt, AuthoringEntityTypeDescriptor as s, isAuthoringPslBlockDescriptor as st, AuthoringArgRef as t, instantiateAuthoringFieldPreset as tt, AuthoringEntityTypeTemplateOutput as u, resolveAuthoringTemplateValue as ut, AuthoringOption as v, AuthoringTypeConstructorDescriptor as w, AuthoringSelectRef as x, AuthoringPslBlockDescriptor as y, PslExtensionBlockParamBare as z };
+//# sourceMappingURL=framework-authoring-7YMP9TwM-C9P-N6_a.d.mts.map