TML-2804: extensions can contribute top-level PSL block keywords

[wmadden]

At a glance

An extension can now register a new top-level keyword for the PSL parser. Here's what authoring looks like once an extension ships such a contribution — concretely, what RLS will let you write once the RLS project lands on top of this:

namespace public {
  model Profile {
    id     String @id
    userId String @unique
  }

  policy profiles_select_anon {
    target = Profile
    using  = "true"
  }
}

The framework's PSL parser doesn't know about policy. The Postgres extension does, because it ships a contribution that registers the keyword along with everything needed to make it round-trip through parse → IR → JSON → IR → print. This PR is the mechanism that makes that possible. RLS itself ships in a separate project.

What this PR decides

An extension registers a new top-level PSL keyword with one descriptor that carries both a parser and a printer, plus a matching lowering factory in the existing entityTypes registry — the two tied together by a shared discriminator string:

const policyContributions: AuthoringContributions = {
  pslBlocks: {
    policy: {
      discriminator: 'postgres-policy',
      // method syntax (not arrow properties) so a contribution's concrete node
      // type assigns across the printer's parameter — see the descriptor JSDoc.
      parser(ctx): PostgresPolicyAst { /* read source lines, return the AST node */ },
      printer(node: PostgresPolicyAst, ctx): string { /* render back to PSL source */ },
    },
  },
  entityTypes: {
    policy: {
      kind: 'entity',
      discriminator: 'postgres-policy',
      output: { factory: (input) => new PostgresPolicyIr(input) },
    },
  },
};

Parser and printer live on one descriptor because they cannot exist independently — a parser with no printer breaks contract infer, a printer with no parser parses nothing. The lowering factory stays in entityTypes because a factory can stand alone (the TS-builder path reaches it without PSL). Load-time validation enforces the one direction that matters: every pslBlocks descriptor must have a matching-discriminator entityTypes factory.

Why this had to ship

The framework's PSL parser had a fixed set of top-level keywords (model, enum, type, types, namespace) and no way for an extension to add new ones. Three downstream projects were blocked by that gap and would otherwise re-litigate "where should this keyword live" on every first PR:

• Postgres RLS wants policy { … } blocks. Without an extension surface, RLS would either edit the framework parser directly (so SQLite + Mongo carry parser surface they can never use), or be authorable only through the TypeScript builder (breaking the framework's PSL/TS structural-parity promise).
• Postgres roles / privileges wants role { … } for the same reasons.
• Postgres-specific entity types (custom domains, etc.) — same shape.

Shipping the mechanism now means each downstream feature lands as a focused PR.

How it works

AuthoringContributions had three namespaces before this PR — type (type constructors), field (field presets), entityTypes (entity factories). This PR adds one: pslBlocks, whose descriptors each carry a parser + a printer.

Parsing. The framework parser's top-level dispatch already handled the five built-in keywords; everything else surfaced an Unsupported top-level block diagnostic. Now, on an unknown identifier, the parser consults the pslBlocks registry: if a descriptor claims the keyword, its parser runs and produces an AST node that lands in a new generic slot on PslNamespace:

interface PslNamespace {
  // ...existing per-kind slots (models, enums, compositeTypes, ...)
  readonly extensionBlocks: readonly PslExtensionBlock[];
}

interface PslExtensionBlock {
  readonly kind: string;   // matches the contribution's discriminator
  readonly name: string;   // every block kind we've shipped or planned has one
  readonly span: PslSpan;
}

The slot is generic deliberately — a typed slot per contributed kind would force a framework PR for every new kind, defeating the point. (Note: this is the PSL-AST layer. ADR 224's entries coordinate-addressing is a distinct, IR-layer concept on the lowered namespace concretions; the PSL AST keeps its per-kind-slot shape for now. Converging it onto entries is a decided, planned follow-up — see "Alternatives considered.")

The contributed-parser contract is enforced at the parser boundary. A contributed parser is foreign code the framework invokes, so the dispatch site holds it to a contract rather than trusting it:

• A parser that throws is caught and converted to a PSL_EXTENSION_BLOCK_PARSE_FAILED diagnostic against the block span — the rest of the document keeps parsing, instead of one bad extension crashing the whole parse (and contract infer with it).
• A parser that returns no node produces the same diagnostic rather than silently dropping the block.
• Immediately after the parser returns, the dispatch asserts node.kind === descriptor.discriminator. A discriminator typo (postgres-polcy) now fails at parse time naming the descriptor, instead of surfacing far away as "no contribution registered" at print time. This makes the routing invariant — which the type system can't express, since the framework holds the descriptor at its base shape — a checked one, documented on both AuthoringPslBlockDescriptor.discriminator and PslExtensionBlock.kind.

Printing. The PSL printer is two-phase (AST → PrintDocument → string), and both need to handle extension-contributed blocks for contract infer to keep working. Phase 1 carries them into a PrintNamespaceSection.extensionBlocks slot; phase 2 builds a discriminator-keyed map from pslBlocks and renders each block by calling the owning descriptor's printer. If a block's discriminator has no matching descriptor, the serializer throws (silent-drop would lose user-authored content during contract infer). The CLI's contract infer threads the assembled pslBlocks namespace through to printPsl(ast, { pslBlocks }).

Validation at load time. Within-namespace duplicates throw, naming both extensions. A pslBlocks descriptor with no matching entityTypes factory throws. Malformed descriptors — objects carrying kind/discriminator but not satisfying the descriptor shape — are rejected rather than silently treated as sub-namespaces.

What's in the diff

The substrate, plus a test-only fixture extension (fake_policy { target = T; using = "..." }) that ships the descriptor + factory and exercises the full round-trip:

PSL text → parse → AST → lower (entityTypes factory) → IR class instance
                       → JSON serialize → JSON hydrate → IR class instance
                                                       → print → PSL text → re-parse → equivalent AST

Tests pin the substrate end-to-end:

• Round-trip (fake-extension.round-trip.test.ts): parse correctness, round-trip equivalence, factory output, JSON serialize/hydrate, mixed framework + fixture round-trip, and the unknown-keyword diagnostic.
• Parser failure isolation (parser.extension-blocks.test.ts): a throwing contributed parser → diagnostic with the document still parsing; an undefined return → diagnostic; kind ≠ discriminator → diagnostic naming both.
• contract infer end-to-end (contract-infer.command.test.ts): a real fake_policy block driven through the actual command path (control-stack namespace → command → printPsl → written file), asserting the rendered block survives to disk.
• Type narrowing (framework-authoring-psl.types.test-d.ts): parser-return = printer-input = factory-input on the contribution literal, plus a negative test (@ts-expect-error) pinning that the descriptor's method form — not arrow properties — is what lets a narrower contributed node assign to the base descriptor.

The fixture is the regression test for the substrate going forward; downstream consumers (RLS first) follow its pattern. No production contribution ships from this PR.

The branch is rebased onto current main (incorporating ADR 224 / #715). The slice's spec + plan ride along as project artifacts (deleted at close-out by the follow-up docs slice). The commit history reflects the build → review-restructure → review-remediation path; it squash-merges to a single commit.

Out of scope

• No real RLS / roles / custom-Postgres-type implementations. Downstream projects that consume this substrate.
• No keyword migration. All existing keywords stay framework-parsed. In particular, enum is not moved to an extension — see "Alternatives considered."
• No PslNamespace → entries migration in this slice. The substrate ships the flat extensionBlocks slot as a deliberate interim; converging the PSL AST onto ADR 224's entries[kind][name] shape is the project's closing slice, TML-2849 — see "Alternatives considered."
• No custom-attribute extensibility (@policy(…)). Different SPI shape; tracked separately.
• No pluggable expression grammar.
• No three-layer extensibility ADR / subsystem-doc updates / AGENTS.md entities→entityTypes doc-bug fix / project-directory deletion. Those land in TML-2806 (the docs + close-out slice), stacked after this PR so the ADR codifies the substrate as actually shipped.

Verification

Gate	Result
pnpm typecheck (the four touched packages + dependents)	pass (135 tasks)
pnpm test:packages for framework-components / psl-parser / psl-printer / cli	pass (344 / 99 / 38 / 1212)
pnpm lint:deps	clean (1026 modules)
pnpm lint:casts	current=1282 merge-base=1289 delta=-7 (no regression; net cast reduction)

A workspace-wide typecheck has one pre-existing failure unrelated to this PR: @prisma-next/integration-tests can't resolve @prisma-next/adapter-sqlite/control (the ./control export lacks a types condition — an artifact of the #715 / ADR-224 merge). @prisma-next/adapter-postgres has the same missing-condition shape. Tracked separately in TML-2844; out of this PR's scope.

Alternatives considered

Two descriptors for parser and printer (the first cut of this PR: separate pslBlocks + pslPrinters namespaces tied by a discriminator cross-check). Rejected on review: they cannot exist independently, so expressing them as two registrations validated against each other is ceremony around one thing. Collapsed to a single descriptor carrying both — which also removes a type guard and the parser↔printer cross-check.

Folding the entityTypes factory into the same descriptor too. Considered (if a PSL block always needs a factory, why not bundle all three?). Kept separate because the reverse isn't true today — entityTypes can stand alone (the TS-builder path; e.g. the existing enum factory has no extension-contributed PSL block, since enum is framework-parsed). The deeper question this surfaces — should every entity with a PSL representation contribute its own parser/printer rather than relying on framework-parsing? — is real but belongs to the enum-as-domain-plane work in TML-2815.

Migrating enum to an extension contribution as the load-bearing proof-of-concept (the original project framing). Rejected: enum is an application-level (domain-plane, ADR 221) concept that happens to have target-specific storage (Postgres native enum, SQLite TEXT, Mongo string), not a Postgres feature. Migrating it would remove enum from SQLite + Mongo contracts — a regression vs Prisma 1.x/2.x. Cross-target enum support is TML-2815. The integration-test fixture substitutes for the missing real migration; RLS is the first real consumer.

Shipping parser extensibility without the printer. Smaller diff, but contract infer would silently break for every extension-contributed block kind. They ship together.

The flat extensionBlocks slot vs. ADR 224's entries shape. This was the open question at review. The PSL AST and the contract IR are two near-identical trees, and ADR 224 gave only the IR a uniform entity coordinate (storage.namespaces[id].entries[kind][name]). A flat extensionBlocks array next to the built-in per-kind slots is a less-general second answer to the same "address namespace entities by kind and name" problem — and "no generic consumer needs the coordinate shape yet" is circular, since the coordinate shape is what would let such consumers exist (the bet ADR 224 already made at the IR layer). The decision: the PSL AST converges on entries. Because that migration is framework-wide (parser, both printer phases, sqlSchemaIrToPslAst, every PSL-AST consumer and test), it does not ride in this substrate slice — the flat slot ships as a deliberate interim, and the full migration is the project's closing slice, TML-2849, sequenced before the ADR so the ADR records the converged shape. The interim is safe because extensions contribute AST nodes through the descriptor SPI and never touch PslNamespace directly, so the storage-shape migration is framework-internal.

A typed PslNamespace slot per contributed kind (policies: PslPolicy[], …). Rejected: every new kind would need a framework PR. The generic extensionBlocks slot keeps the framework AST stable as extensions add kinds (and is the interim the entries migration subsumes).

Silent-drop on a missing printer, or a crashing contributed parser vs. diagnose. Diagnose — silent-drop loses user-authored content during contract infer, and a thrown error from a contributed parser would take down the whole parse rather than the one block. Both degrade to a PSL_EXTENSION_BLOCK_PARSE_FAILED diagnostic instead.

---

Refs: TML-2804 (this slice), TML-2803 (planning), TML-2849 (PSL-AST → entries migration, closing slice), TML-2806 (docs + close-out slice), TML-2844 (adapter types-condition fix), TML-2815 (enum-as-application-concept, sibling project).

Generated with Devin

Summary by CodeRabbit

Release Notes

• New Features
  • PSL now supports extension-contributed top-level blocks, allowing custom block types to be defined and used in schema files.
  • Enhanced the parser and printer to handle these custom blocks with proper validation, diagnostics, and round-trip support (parse → print → parse).
  • Cross-registry validation ensures extension blocks are properly linked to their corresponding entity type definitions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 84f850f8-18ef-4f69-9c5c-f2bc606ed17d

📥 Commits

Reviewing files that changed from the base of the PR and between 93be405 and 9e93e0f.

📒 Files selected for processing (4)

• packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts
• packages/1-framework/1-core/framework-components/test/control-stack.test.ts
• packages/1-framework/2-authoring/psl-printer/src/print-psl.ts
• packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/1-framework/1-core/framework-components/test/control-stack.test.ts
• packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts
• packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts

---

📝 Walkthrough

Walkthrough

Adds an authoring registry for PSL top-level extension blocks: shared SPI types, descriptor namespace and validation, control-stack assembly, parser routing and diagnostics, printer dispatch with options, CLI wiring, and comprehensive tests and fixtures.

Changes

PSL Extension-Block Authoring and Rendering

Layer / File(s)	Summary
Extension-block SPI types and PSL AST contracts packages/1-framework/1-core/framework-components/src/shared/psl-extension-block.ts, packages/1-framework/1-core/framework-components/src/control/psl-ast.ts	Adds position/span/diagnostic primitives and extension-block descriptor base shapes, makes AST carry extensionBlocks per namespace and parse input accept optional pslBlocks namespace.
Authoring descriptor types and validation rules packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts	Adds AuthoringPslBlockDescriptor with required parser/printer functions, type-guard predicate, discriminator-leaf collection, and cross-registry validation that enforces matching entityTypes factories.
Control-stack assembly and authoring exports packages/1-framework/1-core/framework-components/src/control/control-stack.ts, packages/1-framework/1-core/framework-components/src/exports/authoring.ts	Extends assembled contributions to merge and validate pslBlocks descriptors, includes cross-registry collision checks, and re-exports new authoring types and guards.
PSL parser extension-block support packages/1-framework/2-authoring/psl-parser/src/parser.ts, packages/1-framework/2-authoring/psl-parser/src/exports/index.ts	Recognizes keyword BlockName { ... } patterns, resolves contributed descriptors, invokes parser functions with bounds/diagnostics context, accumulates blocks per namespace, and emits parse failures as diagnostics.
Printer options, types, and exports packages/1-framework/2-authoring/psl-printer/src/print-psl.ts, packages/1-framework/2-authoring/psl-printer/src/print-document.ts, packages/1-framework/2-authoring/psl-printer/src/exports/index.ts	Adds PrintPslOptions with optional pslBlocks, carries extension blocks through print-document structures, and exports printer context contracts.
Print serialization with extension-block dispatch packages/1-framework/2-authoring/psl-printer/src/serialize-print-document.ts	Builds discriminator-keyed printer dispatch maps from authoring namespace, constructs shared printer context, and renders extension blocks by invoking matched printer functions.
Control API and CLI integration packages/1-framework/3-tooling/cli/src/control-api/..., packages/1-framework/3-tooling/cli/src/commands/...	Adds getPslBlocksNamespace() method to control client, includes pslBlocksNamespace in inspect-live-schema results, and passes it into contract-infer PSL printing.
Framework authoring assembly tests packages/1-framework/1-core/framework-components/test/control-stack.test.ts	Tests control-stack assembly for empty state and pslBlocks merge/validation scenarios including duplicate detection and factory linkage.
Type-safety tests for PSL authoring packages/1-framework/1-core/framework-components/test/framework-authoring-psl.types.test-d.ts	Compile-time type tests assert parser/printer output compatibility, entity factory matching, discriminator literal preservation, and printer function variance constraints.
Parser behavior tests for extension blocks packages/1-framework/2-authoring/psl-parser/test/parser.extension-blocks.test.ts	Tests recognized/unrecognized keywords, diagnostics propagation, source order, mixed built-in/extension blocks, and failure isolation when contributed parsers malfunction.
Fake-policy extension fixture and printer tests packages/1-framework/2-authoring/psl-printer/test/fixtures/fake-extension.ts, packages/1-framework/2-authoring/psl-printer/test/fake-extension.round-trip.test.ts, packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.extension-blocks.test.ts	Defines test-only fake_policy extension with parser/printer/IR hydration; tests round-trip parsing/printing, mixing with built-in blocks, indentation, and error cases.
CLI tests and cross-package fixture updates packages/1-framework/3-tooling/cli/test/..., packages/2-mongo-family/.../test/..., packages/2-sql/.../test/...	Updates test mocks and fixtures across CLI, mongo, and SQL packages to include pslBlocks and pslPrinters namespaces in authoring context shapes.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Suggested reviewers

• aqrln

Poem

🐰 With whiskers twitching, I parse and write,

I stitch new blocks from day to night,
Keywords dance in schema rows,
Printers hum and parsing grows,
Hooray — extensions jump to light!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.98% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'TML-2804: extensions can contribute top-level PSL block keywords' clearly and concisely summarizes the main change: enabling extensions to register new top-level PSL block keywords. It is specific, descriptive, and directly reflects the primary objective documented in the PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2804-slice-1-parsing-printing-extensibility-substrate

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@prisma-next/extension-author-tools

npm i https://pkg.pr.new/@prisma-next/extension-author-tools@718

@prisma-next/mongo-runtime

npm i https://pkg.pr.new/@prisma-next/mongo-runtime@718

@prisma-next/family-mongo

npm i https://pkg.pr.new/@prisma-next/family-mongo@718

@prisma-next/sql-runtime

npm i https://pkg.pr.new/@prisma-next/sql-runtime@718

@prisma-next/family-sql

npm i https://pkg.pr.new/@prisma-next/family-sql@718

@prisma-next/extension-arktype-json

npm i https://pkg.pr.new/@prisma-next/extension-arktype-json@718

@prisma-next/middleware-cache

npm i https://pkg.pr.new/@prisma-next/middleware-cache@718

@prisma-next/mongo

npm i https://pkg.pr.new/@prisma-next/mongo@718

@prisma-next/extension-paradedb

npm i https://pkg.pr.new/@prisma-next/extension-paradedb@718

@prisma-next/extension-pgvector

npm i https://pkg.pr.new/@prisma-next/extension-pgvector@718

@prisma-next/extension-postgis

npm i https://pkg.pr.new/@prisma-next/extension-postgis@718

@prisma-next/postgres

npm i https://pkg.pr.new/@prisma-next/postgres@718

@prisma-next/sql-orm-client

npm i https://pkg.pr.new/@prisma-next/sql-orm-client@718

@prisma-next/sqlite

npm i https://pkg.pr.new/@prisma-next/sqlite@718

@prisma-next/target-mongo

npm i https://pkg.pr.new/@prisma-next/target-mongo@718

@prisma-next/adapter-mongo

npm i https://pkg.pr.new/@prisma-next/adapter-mongo@718

@prisma-next/driver-mongo

npm i https://pkg.pr.new/@prisma-next/driver-mongo@718

@prisma-next/contract

npm i https://pkg.pr.new/@prisma-next/contract@718

@prisma-next/utils

npm i https://pkg.pr.new/@prisma-next/utils@718

@prisma-next/config

npm i https://pkg.pr.new/@prisma-next/config@718

@prisma-next/errors

npm i https://pkg.pr.new/@prisma-next/errors@718

@prisma-next/framework-components

npm i https://pkg.pr.new/@prisma-next/framework-components@718

@prisma-next/operations

npm i https://pkg.pr.new/@prisma-next/operations@718

@prisma-next/ts-render

npm i https://pkg.pr.new/@prisma-next/ts-render@718

@prisma-next/contract-authoring

npm i https://pkg.pr.new/@prisma-next/contract-authoring@718

@prisma-next/ids

npm i https://pkg.pr.new/@prisma-next/ids@718

@prisma-next/psl-parser

npm i https://pkg.pr.new/@prisma-next/psl-parser@718

@prisma-next/psl-printer

npm i https://pkg.pr.new/@prisma-next/psl-printer@718

@prisma-next/cli

npm i https://pkg.pr.new/@prisma-next/cli@718

@prisma-next/cli-telemetry

npm i https://pkg.pr.new/@prisma-next/cli-telemetry@718

@prisma-next/emitter

npm i https://pkg.pr.new/@prisma-next/emitter@718

@prisma-next/migration-tools

npm i https://pkg.pr.new/@prisma-next/migration-tools@718

prisma-next

npm i https://pkg.pr.new/prisma-next@718

@prisma-next/vite-plugin-contract-emit

npm i https://pkg.pr.new/@prisma-next/vite-plugin-contract-emit@718

@prisma-next/mongo-codec

npm i https://pkg.pr.new/@prisma-next/mongo-codec@718

@prisma-next/mongo-contract

npm i https://pkg.pr.new/@prisma-next/mongo-contract@718

@prisma-next/mongo-value

npm i https://pkg.pr.new/@prisma-next/mongo-value@718

@prisma-next/mongo-contract-psl

npm i https://pkg.pr.new/@prisma-next/mongo-contract-psl@718

@prisma-next/mongo-contract-ts

npm i https://pkg.pr.new/@prisma-next/mongo-contract-ts@718

@prisma-next/mongo-emitter

npm i https://pkg.pr.new/@prisma-next/mongo-emitter@718

@prisma-next/mongo-schema-ir

npm i https://pkg.pr.new/@prisma-next/mongo-schema-ir@718

@prisma-next/mongo-query-ast

npm i https://pkg.pr.new/@prisma-next/mongo-query-ast@718

@prisma-next/mongo-orm

npm i https://pkg.pr.new/@prisma-next/mongo-orm@718

@prisma-next/mongo-query-builder

npm i https://pkg.pr.new/@prisma-next/mongo-query-builder@718

@prisma-next/mongo-lowering

npm i https://pkg.pr.new/@prisma-next/mongo-lowering@718

@prisma-next/mongo-wire

npm i https://pkg.pr.new/@prisma-next/mongo-wire@718

@prisma-next/sql-contract

npm i https://pkg.pr.new/@prisma-next/sql-contract@718

@prisma-next/sql-errors

npm i https://pkg.pr.new/@prisma-next/sql-errors@718

@prisma-next/sql-operations

npm i https://pkg.pr.new/@prisma-next/sql-operations@718

@prisma-next/sql-schema-ir

npm i https://pkg.pr.new/@prisma-next/sql-schema-ir@718

@prisma-next/sql-contract-psl

npm i https://pkg.pr.new/@prisma-next/sql-contract-psl@718

@prisma-next/sql-contract-ts

npm i https://pkg.pr.new/@prisma-next/sql-contract-ts@718

@prisma-next/sql-contract-emitter

npm i https://pkg.pr.new/@prisma-next/sql-contract-emitter@718

@prisma-next/sql-lane-query-builder

npm i https://pkg.pr.new/@prisma-next/sql-lane-query-builder@718

@prisma-next/sql-relational-core

npm i https://pkg.pr.new/@prisma-next/sql-relational-core@718

@prisma-next/sql-builder

npm i https://pkg.pr.new/@prisma-next/sql-builder@718

@prisma-next/target-postgres

npm i https://pkg.pr.new/@prisma-next/target-postgres@718

@prisma-next/target-sqlite

npm i https://pkg.pr.new/@prisma-next/target-sqlite@718

@prisma-next/adapter-postgres

npm i https://pkg.pr.new/@prisma-next/adapter-postgres@718

@prisma-next/adapter-sqlite

npm i https://pkg.pr.new/@prisma-next/adapter-sqlite@718

@prisma-next/driver-postgres

npm i https://pkg.pr.new/@prisma-next/driver-postgres@718

@prisma-next/driver-sqlite

npm i https://pkg.pr.new/@prisma-next/driver-sqlite@718

commit: 9e93e0f

[github-actions]

size-limit report 📦

Path	Size
postgres / no-emit	145.62 KB (+0.39% 🔺)
postgres / emit	117.08 KB (+0.01% 🔺)
mongo / no-emit	76.59 KB (+0.65% 🔺)
mongo / emit	70.95 KB (0%)
cf-worker / no-emit	175.17 KB (+0.32% 🔺)
cf-worker / emit	143.48 KB (0%)

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts`:
- Around line 456-489: collectAuthoringLeafDiscriminators currently descends
into objects that look like malformed descriptors (e.g., have a "kind" or
"discriminator" property) because isLeaf(value) returns false, letting invalid
descriptor-like objects bypass validation; update
collectAuthoringLeafDiscriminators so that before recursively descending it
checks for descriptor-like keys (at minimum "discriminator" and the alias
"kind") and, if present but the object does not satisfy isLeaf, treat it as a
leaf (i.e., record the path or surface it to validation) instead of recursing;
reference the collectAuthoringLeafDiscriminators function and the isLeaf
predicate when implementing this check so malformed descriptor objects are
discovered and rejected during load-time validation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: cdb3a9d9-edbf-4982-946e-3a96f57e2da1

📥 Commits

Reviewing files that changed from the base of the PR and between c159cd4 and 631ff01.

⛔ Files ignored due to path filters (4)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
• projects/target-contributed-psl-blocks/plan.md is excluded by !projects/**
• projects/target-contributed-psl-blocks/slices/substrate/plan.md is excluded by !projects/**
• projects/target-contributed-psl-blocks/spec.md is excluded by !projects/**

📒 Files selected for processing (33)

• packages/1-framework/1-core/framework-components/src/control/control-stack.ts
• packages/1-framework/1-core/framework-components/src/control/psl-ast.ts
• packages/1-framework/1-core/framework-components/src/exports/authoring.ts
• packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts
• packages/1-framework/1-core/framework-components/src/shared/psl-substrate.ts
• packages/1-framework/1-core/framework-components/test/control-stack.test.ts
• packages/1-framework/1-core/framework-components/test/framework-authoring-psl.types.test-d.ts
• packages/1-framework/2-authoring/psl-parser/src/exports/index.ts
• packages/1-framework/2-authoring/psl-parser/src/parser.ts
• packages/1-framework/2-authoring/psl-parser/test/parser.pack-blocks.test.ts
• packages/1-framework/2-authoring/psl-printer/package.json
• packages/1-framework/2-authoring/psl-printer/src/ast-to-print-document.ts
• packages/1-framework/2-authoring/psl-printer/src/exports/index.ts
• packages/1-framework/2-authoring/psl-printer/src/print-document.ts
• packages/1-framework/2-authoring/psl-printer/src/print-psl.ts
• packages/1-framework/2-authoring/psl-printer/src/serialize-print-document.ts
• packages/1-framework/2-authoring/psl-printer/test/fake-target-pack.round-trip.test.ts
• packages/1-framework/2-authoring/psl-printer/test/fixtures/fake-target-pack.ts
• packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.pack-blocks.test.ts
• packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.test.ts
• packages/1-framework/3-tooling/cli/src/commands/contract-infer.ts
• packages/1-framework/3-tooling/cli/src/commands/inspect-live-schema.ts
• packages/1-framework/3-tooling/cli/src/control-api/client.ts
• packages/1-framework/3-tooling/cli/src/control-api/types.ts
• packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts
• packages/1-framework/3-tooling/cli/test/commands/db-schema.command.test.ts
• packages/1-framework/3-tooling/cli/test/commands/inspect-live-schema.test.ts
• packages/1-framework/3-tooling/cli/test/config-types.test.ts
• packages/2-mongo-family/2-authoring/contract-psl/test/provider.test.ts
• packages/2-mongo-family/2-authoring/contract-ts/test/config-types.test.ts
• packages/2-sql/2-authoring/contract-psl/test/fixtures.ts
• packages/2-sql/2-authoring/contract-ts/test/config-types.test.ts
• packages/2-sql/9-family/src/core/psl-contract-infer/sql-schema-ir-to-psl-ast.ts

[wmadden]

There's incorrect vocabulary all over the place. What is a "pack block"? And don't use "pack", use "extension". There's more - see my comments.

Also we shouldn't separate psl printing from psl blocks. If you have one you must have the other.

Positively: I love the round trip test with the fake RLS policy block.

[wmadden]

Review addressed — restructure landed (force-pushed)

Thanks for the review. The feedback split into a vocabulary problem, an architectural one, and a few code-quality findings; all addressed across two restructure dispatches on top of a rebase onto current main (which now includes #715 / ADR 224). The branch was force-pushed; it squash-merges to a single commit.

Two commits carry the work:

• 3d7339487 — collapse the descriptor + fix validation (the architectural + code-quality changes)
• 64b7e746d — vocabulary sweep (pack → extension, drop "substrate")

Vocabulary

Thread	Resolution
psl-ast.ts:203 — avoid "pack", use "extension"	Done (64b7e746d). packBlocks slot → extensionBlocks.
psl-substrate.ts:66 — don't use "pack"	Done (64b7e746d).
psl-substrate.ts (file) — don't use "substrate"	Done (64b7e746d). File renamed psl-substrate.ts → psl-extension-block.ts (via git mv, history preserved).
parser.ts:220 — "Wtf is a pack block?"	Done (64b7e746d). PslPackBlock → PslExtensionBlock, helpers renamed; "extension block" is the term throughout.
psl-substrate.ts:14 — no transient IDs in source	Done (64b7e746d). The Ref: TML-2804 breadcrumb is gone; the surrounding comment already carries the rationale.

Scope note: I left legitimate pre-existing "pack" terminology untouched (the "extension pack" concept, pack manifest, the fakeTargetPackContributions test fixture name). rg over the four touched packages confirms zero PslPackBlock / packBlocks / psl-substrate / "pack block" remain.

Architecture — parser + printer are now one descriptor

Thread	Resolution
framework-authoring.ts:181 — "These should be one interface. If you provide a psl block you must also provide its printer."	Done (3d7339487). AuthoringPslBlockDescriptor now carries both parser and printer. AuthoringPslPrinterDescriptor, the pslPrinters namespace, and the parser↔printer cross-check are deleted.
framework-authoring.ts:557 — "the only reason to have the type predicates is to distinguish two objects which ought to be inseparable?"	Done (3d7339487). isAuthoringPslPrinterDescriptor is gone. The one remaining guard (isAuthoringPslBlockDescriptor) now distinguishes a block descriptor from an entityTypes descriptor / sub-namespace for the merge walker during assembly — a different job than splitting parser from printer. If you'd still like that one reworked, say so.
framework-authoring.ts:297 — "Why do we need this type guard?"	The guard count dropped 3 → 2 (entity + block). The survivor is load-bearing for the namespace merge walker (mergeAuthoringNamespaces needs a leaf predicate to tell descriptors from sub-namespaces). Not removable without reworking the walker; flagging in case you want that as a follow-up.
framework-authoring.ts:543 — "Should this include entity as well? … Why does helpers.enum() provide itself only to the TS builder? PSL has an enum representation too."	Decision (please confirm): entityTypes kept as a separate registry for this slice. Rationale: a factory can stand alone today (the TS-builder path — the existing enum factory has no extension-contributed PSL block because enum is framework-parsed), so folding it in would force every TS-builder entity to ship parser/printer. The deeper question you're pointing at — should every PSL-representable entity contribute its own parser/printer instead of relying on framework-parsing? — is real, and it's exactly the enum-dual-representation tension; I routed it to TML-2815 (enum-as-application-concept) rather than resolve it here. Validation now enforces the one direction that holds: a pslBlocks descriptor requires a matching entityTypes factory; a factory may stand alone. Spec records this as an explicit non-goal with the rationale.

entries pattern (psl-ast.ts:188)

You asked whether we can use #715's namespace.entries pattern here. Having dug into the merged code: entries is an IR-layer concept (ADR 224 — it addresses the lowered namespace concretions, storage.namespaces[id].entries[kind][name]). #715 deliberately left the PSL-AST PslNamespace on its per-kind slots (models/enums/compositeTypes). So adopting entries here would mean inventing a PSL-AST shape #715 chose not to build — and doing it for only extension blocks (while models/enums stay slots) would create exactly the inconsistency you'd dislike. Migrating the whole PSL AST to entries is a framework-wide change worth its own project. For this slice I kept the per-kind-slot shape with a generic extensionBlocks slot for contributed kinds. Flagged in the spec's non-goals + the PR description's "Alternatives considered." Open to a follow-up ticket for the full PSL-AST entries migration if you want it.

Code-quality findings

Thread	Resolution
framework-authoring.ts:456 (CodeRabbit) — malformed descriptor objects bypass validation	Done (3d7339487). collectAuthoringLeafDiscriminators now rejects values carrying kind/discriminator that fail the descriptor guard, instead of silently descending into them. New test pins the rejection.
client.ts:551 — "Why is stack optional?"	Done (3d7339487). Audited init(): it unconditionally assigns this.stack before setting initialized, and sibling methods already rely on that (this.stack! in emit). Dropped the ?./?? {} for this.stack! + a one-line comment recording the invariant. (The method also renamed getPslPrintersNamespace → getPslBlocksNamespace, since it returns the block namespace now.)

---

Validation after the restructure: pnpm typecheck clean on the four touched packages, their tests pass (framework-components 342 / psl-parser 96 / psl-printer 38 / cli 1211), lint:deps clean, lint:casts delta=-7 (net reduction). One pre-existing workspace-wide typecheck failure unrelated to this PR — @prisma-next/integration-tests can't resolve @prisma-next/adapter-sqlite/control (missing types export condition, an artifact of the #715/ADR-224 merge; adapter-postgres has the same shape). Worth a separate ticket.

Two threads have a decision I'd like you to confirm rather than just resolve — the entityTypes-separation (543) and the entries-layer call (188). The rest are straightforward done.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

packages/1-framework/2-authoring/psl-printer/test/fixtures/fake-target-pack.ts (1)

135-157: ⚡ Quick win

Consider extracting shared unescape logic.

The decodePslEscapes function duplicates the unescapePslString logic from ast-to-print-document.ts (lines 155-177). Both iterate character-by-character and handle the same escape sequences (\\, \", \', \n, \r) with identical logic.

Since unescapePslString is not currently exported, this duplication keeps the test fixture self-contained. However, extracting this to a shared utility (or exporting it from the printer) would reduce maintenance burden and ensure consistent escape handling across parser and printer paths.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/1-framework/2-authoring/psl-printer/test/fixtures/fake-target-pack.ts`
around lines 135 - 157, The test fixture duplicates the unescaping logic found
in ast-to-print-document.ts (function unescapePslString) via its local
decodePslEscapes; remove the duplication by moving the shared logic into a
single utility and reusing it: either export unescapePslString from
ast-to-print-document.ts and import it into fake-target-pack.ts (replacing
decodePslEscapes), or create a new shared helper (e.g., psl-string-utils with
unescapePslString) and update both callers (decodePslEscapes usage site and the
original location) to import that helper so escape handling for \\ , \", \', \n
and \r is centralized.

packages/1-framework/2-authoring/psl-printer/src/print-psl.ts (1)

28-31: ⚡ Quick win

Consider using ifDefined for conditional object spread.

The ternary-based conditional spread can be simplified using the ifDefined helper from @prisma-next/utils/defined, matching the established pattern in this codebase.

♻️ Refactor to use ifDefined

+import { ifDefined } from '`@prisma-next/utils/defined`';
+
 export function printPslFromAst(ast: PslDocumentAst, options: PrintPslOptions = {}): string {
   const doc = astDocumentToPrintDocument(ast);
   return serializePrintDocument(
     doc,
-    options.pslBlocks !== undefined ? { pslBlocks: options.pslBlocks } : {},
+    { ...ifDefined('pslBlocks', options.pslBlocks) },
   );
 }

Based on learnings from this repo: prefer ifDefined from @prisma-next/utils/defined for conditional object spreads instead of inline ternary-based spreads.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/1-framework/2-authoring/psl-printer/src/print-psl.ts` around lines
28 - 31, Replace the inline ternary used when calling serializePrintDocument
with the repository helper: import ifDefined from '`@prisma-next/utils/defined`'
and pass a conditional object produced by ifDefined for options.pslBlocks
instead of options.pslBlocks !== undefined ? { pslBlocks: options.pslBlocks } :
{}; specifically update the call site of serializePrintDocument and ensure the
import for ifDefined is added near other imports so the second argument only
contains the pslBlocks property when options.pslBlocks is defined.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts`:
- Around line 451-460: The current malformed-descriptor check in
framework-authoring.ts (inside the loader that walks namespaces) fires whenever
a non-leaf object has a kind/discriminator key; update the condition so it only
throws when the object actually looks like a broken descriptor: require that
kind/discriminator is present AND that the object does NOT contain any
descriptor-required fields (e.g. parser/printer or other descriptor properties
used by your descriptors). In short, replace the broad condition (record['kind']
!== undefined || record['discriminator'] !== undefined) with a tighter one that
also checks for the absence of descriptor fields (for example: (record.kind ||
record.discriminator) && !record.parser && !record.printer), so child namespaces
that legitimately use "kind"/"discriminator" segments are not rejected (and keep
mergeAuthoringNamespaces() behavior unchanged).
- Around line 530-546: The code currently collapses duplicate discriminators via
new Set and therefore misses duplicate-checks; update the validation in the
block/entity collection step (use the results of
collectAuthoringLeafDiscriminators for blockEntries and entityEntries) to detect
and reject duplicate discriminators within each group before creating
entityDiscriminators: scan blockEntries for repeated entry.discriminator and
throw a clear Error referencing the offending pslBlock paths and discriminator,
do the same for entityEntries (entityType) so duplicates are rejected rather
than silently last-wins, then proceed to build entityDiscriminators and keep the
existing cross-check between block.discriminator and entityDiscriminators.

---

Nitpick comments:
In `@packages/1-framework/2-authoring/psl-printer/src/print-psl.ts`:
- Around line 28-31: Replace the inline ternary used when calling
serializePrintDocument with the repository helper: import ifDefined from
'`@prisma-next/utils/defined`' and pass a conditional object produced by ifDefined
for options.pslBlocks instead of options.pslBlocks !== undefined ? { pslBlocks:
options.pslBlocks } : {}; specifically update the call site of
serializePrintDocument and ensure the import for ifDefined is added near other
imports so the second argument only contains the pslBlocks property when
options.pslBlocks is defined.

In
`@packages/1-framework/2-authoring/psl-printer/test/fixtures/fake-target-pack.ts`:
- Around line 135-157: The test fixture duplicates the unescaping logic found in
ast-to-print-document.ts (function unescapePslString) via its local
decodePslEscapes; remove the duplication by moving the shared logic into a
single utility and reusing it: either export unescapePslString from
ast-to-print-document.ts and import it into fake-target-pack.ts (replacing
decodePslEscapes), or create a new shared helper (e.g., psl-string-utils with
unescapePslString) and update both callers (decodePslEscapes usage site and the
original location) to import that helper so escape handling for \\ , \", \', \n
and \r is centralized.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 65f14c7b-a87f-4e76-8284-e0bb00be3847

📥 Commits

Reviewing files that changed from the base of the PR and between 631ff01 and 64b7e74.

📒 Files selected for processing (28)

• packages/1-framework/1-core/framework-components/src/control/control-stack.ts
• packages/1-framework/1-core/framework-components/src/control/psl-ast.ts
• packages/1-framework/1-core/framework-components/src/exports/authoring.ts
• packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts
• packages/1-framework/1-core/framework-components/src/shared/psl-extension-block.ts
• packages/1-framework/1-core/framework-components/test/control-stack.test.ts
• packages/1-framework/1-core/framework-components/test/framework-authoring-psl.types.test-d.ts
• packages/1-framework/2-authoring/psl-parser/src/exports/index.ts
• packages/1-framework/2-authoring/psl-parser/src/parser.ts
• packages/1-framework/2-authoring/psl-parser/test/parser.pack-blocks.test.ts
• packages/1-framework/2-authoring/psl-printer/package.json
• packages/1-framework/2-authoring/psl-printer/src/ast-to-print-document.ts
• packages/1-framework/2-authoring/psl-printer/src/exports/index.ts
• packages/1-framework/2-authoring/psl-printer/src/print-document.ts
• packages/1-framework/2-authoring/psl-printer/src/print-psl.ts
• packages/1-framework/2-authoring/psl-printer/src/serialize-print-document.ts
• packages/1-framework/2-authoring/psl-printer/test/fake-target-pack.round-trip.test.ts
• packages/1-framework/2-authoring/psl-printer/test/fixtures/fake-target-pack.ts
• packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.pack-blocks.test.ts
• packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.test.ts
• packages/1-framework/3-tooling/cli/src/commands/contract-infer.ts
• packages/1-framework/3-tooling/cli/src/commands/inspect-live-schema.ts
• packages/1-framework/3-tooling/cli/src/control-api/client.ts
• packages/1-framework/3-tooling/cli/src/control-api/types.ts
• packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts
• packages/1-framework/3-tooling/cli/test/commands/db-schema.command.test.ts
• packages/1-framework/3-tooling/cli/test/commands/inspect-live-schema.test.ts
• packages/1-framework/3-tooling/cli/test/config-types.test.ts

💤 Files with no reviewable changes (10)

• packages/1-framework/3-tooling/cli/test/config-types.test.ts
• packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts
• packages/1-framework/3-tooling/cli/src/commands/inspect-live-schema.ts
• packages/1-framework/3-tooling/cli/test/commands/inspect-live-schema.test.ts
• packages/1-framework/3-tooling/cli/test/commands/db-schema.command.test.ts
• packages/1-framework/3-tooling/cli/src/control-api/types.ts
• packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.test.ts
• packages/1-framework/3-tooling/cli/src/commands/contract-infer.ts
• packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.pack-blocks.test.ts
• packages/1-framework/3-tooling/cli/src/control-api/client.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• packages/1-framework/1-core/framework-components/src/exports/authoring.ts
• packages/1-framework/2-authoring/psl-printer/package.json
• packages/1-framework/2-authoring/psl-parser/test/parser.pack-blocks.test.ts
• packages/1-framework/2-authoring/psl-parser/src/parser.ts
• packages/1-framework/2-authoring/psl-printer/test/fake-target-pack.round-trip.test.ts

[coderabbitai]

🧹 Nitpick comments (1)

packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts (1)

377-377: ⚡ Quick win

Strengthen assertion to verify rendered block structure.

The current assertion only checks for the presence of 'fake_policy ReadOnlyUser', but does not verify that the target and using fields are correctly rendered. The printer at lines 326-332 explicitly formats these fields, and the test constructs a node with target: 'User' and using: 'auth.uid = user_id' (lines 344-345).

Add assertions to confirm the full block structure is written, ensuring the printer receives and renders all node fields correctly.

🔍 Suggested additional assertions

 const outputPath = join(testDir, 'output/contract.prisma');
 expect(existsSync(outputPath)).toBe(true);
 const content = readFileSync(outputPath, 'utf-8');
 expect(content).toContain('fake_policy ReadOnlyUser');
+expect(content).toContain('target = User');
+expect(content).toContain('using = "auth.uid = user_id"');

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts`
at line 377, The test only asserts 'fake_policy ReadOnlyUser' but must also
verify the printer rendered the node's target and using fields; update the test
(contract-infer.command.test.ts) to assert that the output contains the 'target:
User' and 'using: auth.uid = user_id' lines (or assert the full block sequence
with a single regex like /fake_policy ReadOnlyUser\s*{\s*target: User\s*using:
auth.uid = user_id\s*}/) so the printer code that formats target/using (the
rendering around lines 326-332) is exercised and validated.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In
`@packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts`:
- Line 377: The test only asserts 'fake_policy ReadOnlyUser' but must also
verify the printer rendered the node's target and using fields; update the test
(contract-infer.command.test.ts) to assert that the output contains the 'target:
User' and 'using: auth.uid = user_id' lines (or assert the full block sequence
with a single regex like /fake_policy ReadOnlyUser\s*{\s*target: User\s*using:
auth.uid = user_id\s*}/) so the printer code that formats target/using (the
rendering around lines 326-332) is exercised and validated.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 9fb55024-9e8e-487f-ad7d-33e3b8b0c6b6

📥 Commits

Reviewing files that changed from the base of the PR and between 64b7e74 and 93be405.

⛔ Files ignored due to path filters (3)

• projects/target-contributed-psl-blocks/plan.md is excluded by !projects/**
• projects/target-contributed-psl-blocks/slices/substrate/plan.md is excluded by !projects/**
• projects/target-contributed-psl-blocks/spec.md is excluded by !projects/**

📒 Files selected for processing (12)

• packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts
• packages/1-framework/1-core/framework-components/src/shared/psl-extension-block.ts
• packages/1-framework/1-core/framework-components/test/control-stack.test.ts
• packages/1-framework/1-core/framework-components/test/framework-authoring-psl.types.test-d.ts
• packages/1-framework/2-authoring/psl-parser/src/parser.ts
• packages/1-framework/2-authoring/psl-parser/test/parser.extension-blocks.test.ts
• packages/1-framework/2-authoring/psl-printer/test/fake-extension.round-trip.test.ts
• packages/1-framework/2-authoring/psl-printer/test/fixtures/fake-extension.ts
• packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.extension-blocks.test.ts
• packages/1-framework/3-tooling/cli/src/commands/inspect-live-schema.ts
• packages/1-framework/3-tooling/cli/src/control-api/types.ts
• packages/1-framework/3-tooling/cli/test/commands/contract-infer.command.test.ts

✅ Files skipped from review due to trivial changes (1)

• packages/1-framework/2-authoring/psl-printer/test/print-psl-from-ast.extension-blocks.test.ts

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/1-framework/3-tooling/cli/src/control-api/types.ts
• packages/1-framework/1-core/framework-components/src/shared/psl-extension-block.ts
• packages/1-framework/1-core/framework-components/test/control-stack.test.ts
• packages/1-framework/3-tooling/cli/src/commands/inspect-live-schema.ts
• packages/1-framework/2-authoring/psl-parser/src/parser.ts
• packages/1-framework/1-core/framework-components/src/shared/framework-authoring.ts

[wmadden]

Already addressed in commit 3d73394. collectAuthoringLeafDiscriminators now rejects objects that carry descriptor-shaped keys (kind/discriminator) but fail the leaf guard at load time, instead of silently recursing into them. A01 (thread PRRT_kwDOQM0QJc6HXxFJ) further tightens this in commit 4e1233c so valid sub-namespaces keyed 'kind'/'discriminator' still descend normally.

[wmadden]

Both findings in this review are already addressed. A04a (vocabulary): the pack→extension rename is done in commit 64b7e74 and reinforced in 046b45f — PslPackBlock → PslExtensionBlock, packBlocks → extensionBlocks, psl-substrate.ts → psl-extension-block.ts, with no remaining occurrences of the old names in src. A04b (parser+printer on one descriptor): done in commit 3d73394 — AuthoringPslBlockDescriptor now declares both parser and printer; the separate pslPrinters slot was deleted so they cannot diverge.

[wmadden]

A05a (ifDefined): done in commit c345054 — printPslFromAst now uses ifDefined('pslBlocks', options.pslBlocks) per the use-if-defined rule. A05b (fixture dedup): not addressed — unescapePslString is intentionally not exported from the printer, and the local copy in the test fixture keeps it self-contained. Exporting a printer internal purely to de-duplicate ~20 lines of test fixture would couple the test to printer internals without clear benefit.

[wmadden]

Done — commit 9e93e0f adds assertions for target = User and using = "auth.uid = user_id" (the actual =-and-quoted format the inline printer emits, matching the fixture printer in fake-extension.ts lines 127-128).

[wmadden-electric]

Converting to draft — pivoting the SPI shape

A design discussion concluded that the extension-contributed PSL block SPI should be declarative, not function-based. An extension should describe a top-level block — its keyword, name, and typed parameters — as data, and the framework interprets any declared block with one generic parser / validator / printer. It should not ship imperative parser / printer functions.

Why. The PSL grammar is closed and uniform (a block is a name + field declarations + x = y assignments + double-quoted values). So a block's structure can be described as data and validated/analysed without executing extension code. The function SPI on this branch re-implements parsing the framework already does, can't be validated from its data alone, and is the reason this PR needed the failure-isolation hardening (catching thrown parsers, undefined returns, kind/discriminator drift) — all of which exists only because arbitrary code runs at parse time. Describing blocks as data deletes that whole class of risk.

Parameter value-kinds (the vocabulary that replaces parser/printer):

• ref — resolves to a declared entity, with a scope constraint (same-namespace / same-space / cross-space) resolved against the cross-contract-space coordinate model from TML-2500 (M1): cross-contract FK carrier + aggregate-load checks #745.
• value — a codec-typed value; the codec owns PSL parse/print, the same rails field types and @default already use.
• option — one of a fixed set of allowed literal tokens (e.g. as = permissive | restrictive). An authoring-time parameter constraint — explicitly not a domain or persistence enum; the enums-as-domain project (docs(enums): enums-as-domain-concept — project spec, plan, design notes #748) is independent of this.
• list — combinator over the above.

Nothing here is discarded. The mechanism this branch built is cherry-picked into the reshaped project: the generic extensionBlocks slot, the unknown-keyword parser dispatch + diagnostic, the load-time validation (within-namespace duplicates, block↔factory matching, duplicate-discriminator + malformed-descriptor checks), the two-phase printer plumbing, the contract infer threading, and the round-trip test harness. Only the descriptor's parser/printer functions are replaced by the declarative descriptor + generic interpreter. The branch and its commits stay intact for cherry-picking.

Where the design + replan live: projects/target-contributed-psl-blocks/ (revised spec + plan) and a revision to ADR 126 (PSL top-level block SPI). This PR reopens once the reshaped substrate slice lands.