Scope target-extensible IR project: multi-schema Postgres, cross-namespace FKs, Supabase foundation (TML-2459)

[wmadden]

At a glance

After this project lands, a Postgres contract can declare its schemas, place models in them, and reference across them — the capability that today's IR can't express:

defineContract((m) => ({
  namespaces: ['public', 'auth'],
  models: {
    User: m.model('User', {
      namespace: 'auth',
      fields: { id: m.field.uuid().primary(), email: m.field.text() },
    }),
    Profile: m.model('Profile', {
      namespace: 'public',
      fields: {
        id: m.field.uuid().primary(),
        userId: m.field.uuid().constraints(m.constraints.ref(User)),
        // → emits ALTER TABLE "public"."profiles" ADD CONSTRAINT ...
        //   FOREIGN KEY ("user_id") REFERENCES "auth"."users"("id")
      },
    }),
  },
}));

For multi-tenant Postgres, the new __unspecified__ sentinel lets the connection's search_path bind models to a tenant schema at runtime — the contract describes the shape, the connection picks the namespace.

The PSL surface is structurally parallel to the TS builder; switching between them stays mechanical for users.

What this PR is

This is a scoping PR. It lands the project's spec and plan as documentation under projects/target-extensible-ir/; execution lands as 7 follow-up PRs across the milestones below. The substance of this PR is the scope review — implementation review comes later, milestone by milestone.

• Spec: projects/target-extensible-ir/spec.md
• Plan: projects/target-extensible-ir/plan.md
• Linear project: Target-Extensible IR (7 milestone tickets, TML-2468 through TML-2474)

The problem we're solving

Today, every Postgres contract lives implicitly in the public schema. Postgres-specific concepts — additional schemas, CREATE TYPE … AS ENUM, RLS policies, custom functions — either get smuggled through the untyped annotations: SqlAnnotations escape hatch, are reconstructed outside the IR (enums today are glued in via codec control hooks), or simply aren't supported at all (RLS, custom functions, multi-namespace FKs).

Authors hit this directly: auth.users (Supabase's user table, in the auth schema) cannot be referenced from a user's contract because the IR has no way to express "a table in a different schema." That single constraint is what blocks the Supabase integration, and it's the same architectural shape that prevents future first-class support for RLS, custom Postgres functions, MySQL databases, and dialect-specific concepts in any future SQL target (CockroachDB, planetscale, neon).

The decision

Refactor Contract IR and Schema IR from flat data shapes (type = { … }) into a polymorphic class hierarchy layered as framework interfaces → family abstract bases → target concrete classes. Targets gain a typed home for dialect-specific concepts; framework consumers depend on framework SPI interfaces, not on concrete target classes. The Namespace concept becomes first-class at the framework layer; authoring DSL surfaces in PSL and the TS builder expose it.

The recipe isn't new — it's already proven in production by OpFactoryCall (ADR 195) for the migration-op layer and by MongoSchemaNode for Mongo's schema IR. This project consolidates the convention and applies it consistently to the two IRs that haven't yet adopted it.

What this delivers

Three user-facing capabilities ship with this project:

1. Multi-schema Postgres contracts. Declare and reference models in named namespaces. Non-default namespaces emit with the correct "<schema>"."<table>" qualifier in DDL.
2. Cross-namespace FK references within a single contract space. This is the FL-02 fix — public.profiles.user_id REFERENCES auth.users(id) works end-to-end. Single biggest direct unblocker for Supabase.
3. Connection-bound multi-tenancy. __unspecified__ + connection search_path lets one contract describe a shape that's bound to different schemas at runtime. Real customer story for SaaS Postgres deployments independent of Supabase.

Why this clears the path for Supabase

Without this project, every Supabase deliverable (RLS policies, createSupabaseRuntime, auth.users queryable surface) forces an ad-hoc IR decision and becomes "feature + foundational refactor in disguise."

After this project, those deliverables are bounded feature PRs on a stable foundation: introduce PostgresRlsPolicy as a target-only IR kind (small PR following the established recipe), build the Supabase contract package modelling auth.users as a contract-space contribution, ship the runtime split. Rough sizing: 4–6 weeks of focused Supabase work after this project lands. The trade is more time-to-Supabase now in exchange for much less time-to-Supabase-and-everything-after-it later.

Sequencing

Seven milestones, M1 → M2 → M3 → M4 → M5a → M5b → M6:

#	Milestone	Linear
M1	Foundation: framework SPI interfaces + per-SPI family abstract bases	TML-2468
M2	Mongo migration: first consumer of the foundation	TML-2469
M3	Postgres SPI shells + `validateContract` migration	TML-2470
M4	Enum exemplar (low-risk refactor)	TML-2471
M5a	Namespace exemplar + authoring DSL	TML-2472
M5b	Cross-namespace FK references (FL-02 fix)	TML-2473
M6	Documentation + ADR drafts	TML-2474

External strict-precedence dependencies (must land before M1):

• TML-2457 (APP_SPACE_ID coupling audit) — direct test-file conflicts with M3.
• TML-2463 (SQLite multi-space planner) — SQLite planner conflicts with M3.
• TML-2408 (port contract spaces to Mongo) — Mongo IR conflicts with M2.

TML-2464 (strip single/multi-space branching) must land after this project so its branch-removal touches IR-walking sites once, post-IR-flip, rather than twice.

Alternatives considered

• Ship Supabase via shims (skip this project; ship RLS + cross-schema FKs through annotations: SqlAnnotations and target-specific code paths). Rejected: shim-shaped IR becomes load-bearing in production; removing it later requires this project plus a migration of every shimmed concept. We'd buy 2–3 weeks of Supabase delivery now and pay it back many times over across every Supabase-adjacent feature and every future SQL target.
• Mongo as a parallel stream (land SQL exemplars first, fold Mongo in afterwards). Rejected: SPI shape disagreements would surface only after both SQL exemplars committed to the wrong shape. M2 puts Mongo on the critical path as the second consumer, pressuring the SPI shapes against a second family before SQL targets commit. The cost is one additional sequenced milestone; the benefit is the SPI shapes get validated by a second family while they're still cheap to flex.
• Cross-contract-space FKs in scope (fold refIn(otherSpace, …) into this project). Rejected as out of scope: cross-contract reference semantics tangle with TML-2397's contract-spaces work and require their own design pass. Cross-namespace (within one contract space) is in scope and delivers the user-visible Supabase value; cross-contract-space is a separate follow-up.
• Defer the IR refactor entirely (ship Supabase as a flat-IR product, postpone the architecture work indefinitely). Rejected: the IR rot would accrue against every future SQL target (CockroachDB, planetscale, neon) that faces the same Postgres-isms problem. Doing the foundational work once, now, is cheaper than carrying the architectural tax across every future target.

Test plan

This PR is docs-only; verification is reviewer-shaped:

• Spec and plan are internally consistent (FRs map to ACs, ACs map to milestones, sequencing notes match Linear blockedBy chains).
• All cross-doc links resolve (ADRs, existing reference implementations, sibling project docs).
• Linear project + 7 milestone tickets exist with the correct blockedBy chain (TML-2468 → … → TML-2474; M1 also blocked by TML-2457, TML-2463, TML-2408).
• TML-2408 carries the sequencing-constraint comment about Mongo landing fully aggregate-native (not in a half-migrated transition window) so M2 doesn't have to untangle two simultaneous reshapings.

Refs: TML-2459

Summary by CodeRabbit

• New Features

  • Added CipherStash searchable encryption extension and demo; ParadeDB demo; multi-extension monorepo example.
  • Multi-space migration/apply execution with per-space breakdowns and aggregate planning.

• Documentation

  • New architecture pattern catalogue, CLI & Mongo subsystem docs, OSS governance/supply-chain docs, and CipherStash developer guide.

• Improvements

  • Indexes now support typed type + options with registry/validation and clearer diagnostics.
  • CLI/migration output, tooling, and middleware enhanced for richer per-space and raw-SQL workflows.

[coderabbitai]

📝 Walkthrough

Walkthrough

Large multi-area change adding index-type/type-options support and validation, removing legacy OperationTypes in favor of queryOperationTypes, introducing aggregate multi-space migration planning/apply and per-space outputs, extending runtime middleware with a param-ref mutator and raw-SQL AST, unifying marker reads, and adding a CipherStash extension plus several examples and tests. Many docs, skills, and emitter/test updates accompany the behavior changes.

Changes

Index-type registry, validation, and authoring

Layer / File(s)	Summary
ADR and design docs/architecture docs/adrs/ADR 210 - Index-type registry.md	New ADR defining index-type registry semantics and validation placement.
Index-type builder & runtime registry packages/2-sql/1-core/contract/src/index-types.ts, .../exports/index-types.ts, .../package.json	Adds defineIndexTypes(), IndexTypeBuilder, IndexTypeRegistry and createIndexTypeRegistry().
Validation packages/2-sql/1-core/contract/src/index-type-validation.ts, .../validators.ts, tests	Adds validateIndexTypes(contract, registry); Index storage shape uses type/options; duplicate-detection normalized by sorted options.
Authoring (PSL/TS) and lowering packages/2-sql/2-authoring/contract-psl/*, packages/2-sql/2-authoring/contract-ts/*	PSL gains parseObjectLiteralStringMap for options; PSL/TS DSL accept type + options, lowered into contract IR; type-level pack threading added.
Emitter / verify / schema packages/2-sql/3-tooling/emitter/*, packages/2-sql/9-family/src/core/schema-verify/verify-helpers.ts	Emitter emits type/options; schema-verify matches indexes including extras (loose string-coerced option equality).
Tests packages/2-sql/**/test/*	New/updated tests for builder, registry, parser, validator, emitter, and verify semantics.

---

OperationTypes removal and TypeMaps / emitter adjustments

Layer / File(s)	Summary
Framework surfaces & stacks packages/1-framework/1-core/framework-components/src/*, .../src/control/control-stack.ts, .../src/exports/control.ts	Removes operationTypeImports from control stack/metadata; replaces with queryOperationTypes.
Emitter / DTS generation packages/1-framework/3-tooling/emitter/src/generate-contract-dts.ts, .../src/emit.ts	generateContractDts drops operationTypeImports and no longer generates OperationTypes export; tests updated.
Operations registry API packages/1-framework/1-core/operations/src/index.ts, docs, tests	Registry API changed to register(name, descriptor); descriptor shape simplified to { self, impl } and OperationDescriptors keyed by name.
TypeMaps / generated contracts packages/2-mongo-family/*, examples/*/src/prisma/contract.d.ts	TypeMaps generics and generated contract DTS/JSON adjusted to omit OperationTypes and accept queryOperationTypes instead; many generated artifacts updated.
Tests / emitter tests packages/*/test/*, packages/1-framework/3-tooling/emitter/test/*	Refactors to new inputs and expected TypeMaps shapes.

---

CLI: multi-space aggregate planning/apply and UX

Layer / File(s)	Summary
Aggregate apply primitive packages/1-framework/3-tooling/cli/src/control-api/operations/apply-aggregate.ts	New applyAggregate primitive: ordered per-space apply, progress spans, failure mapping, per-space breakdown builders.
Migration apply rewrite packages/1-framework/3-tooling/cli/src/control-api/operations/migration-apply.ts, .../types.ts, .../client.ts	executeMigrationApply rewritten to load contract-space aggregate, graph-walk plan per space, call applyAggregate, and return perSpace + optional pathDecision.
Plan/status commands & inputs packages/1-framework/3-tooling/cli/src/commands/migration-plan.ts, migration-status.ts, utils/extension-pack-inputs.ts, contract-space-aggregate-loader.ts	Surfaces emitted extension dirs in plan results, canonicalizes extension inputs, loads aggregate for status, computes per-space totals and totalPendingAcrossSpaces.
Formatting / CLI outputs packages/1-framework/3-tooling/cli/src/utils/formatters/migrations.ts, migration-apply.ts, db-init.ts, db-update.ts	Adds per-space render block, moves destructive marker to suffix, includes perSpace in JSON outputs and new summary text.
Runner integration & family shims packages/2-mongo-family/9-family/src/core/mongo-target-descriptor.ts	Mongo runner implements executeAcrossSpaces as a one-space shim and returns structured failures when unsupported.
Tests packages/1-framework/3-tooling/cli/test/*	New and updated tests pin perSpace JSON shapes, plan emitted-extension rendering, progress labels, and aggregate status helpers.

---

Runtime, middleware, param-ref mutator, raw-SQL, and marker read

Layer / File(s)	Summary
Param-ref mutator middleware packages/2-sql/4-lanes/relational-core/src/middleware/param-ref-mutator.ts, .../exports/middleware.ts, .../src/index.ts	New SqlParamRefMutator API and createSqlParamRefMutator(plan) providing entries(), replaceValue(s), and currentParams(); re-exported via package middleware entry.
Middleware SPI and threading packages/1-framework/1-core/framework-components/src/execution/run-with-middleware.ts, .../runtime-middleware.ts, packages/2-sql/5-runtime/src/middleware/sql-middleware.ts	Runtime middleware generics extended with ParamRefMutator type; runWithMiddleware accepts paramsMutator and forwards into beforeExecute hooks; beforeExecute hook signature widened to accept params mutator and optional returns.
Abort phases & helpers packages/1-framework/1-core/framework-components/src/execution/runtime-error.ts, race-against-abort.ts	RuntimeAbortedPhase expanded (beforeExecute/afterExecute/onRow); checkAborted accepts structural { signal?: AbortSignal }.
Raw SQL AST & decoding/lints packages/2-sql/4-lanes/relational-core/src/ast/types.ts, packages/2-sql/5-runtime/src/codecs/*, .../middleware/lints.ts	RawSqlExpr AST node added; alias/projection/decoding and middleware lints updated to handle raw-sql (opt-out structural lints, raw guardrails).
Marker read unification packages/2-sql/4-lanes/relational-core/src/ast/adapter-types.ts, packages/2-sql/5-runtime/src/runtime-spi.ts, packages/2-sql/5-runtime/src/sql-runtime.ts	Adapter profile and runtime SPI replace readMarkerStatement/parseMarkerRow pair with async readMarker(queryable) returning tagged MarkerReadResult (present/absent/no-table); runtime verifyMarker uses new API.
Plan helper packages/2-sql/4-lanes/relational-core/src/plan.ts	Adds planFromAst(ast, contract, laneId) helper to produce SqlQueryPlan envelopes.
Tests packages/2-sql/**/test/*	New tests for param-ref mutator, RawSqlExpr handling, marker-driven verify flows, and updated lints/decoding tests.

---

CipherStash extension and integration example

Layer / File(s)	Summary
Extension package & wiring packages/3-extensions/cipherstash/src/*, prisma-next.config.ts, package.json	New extension package with authoring types, control/runtime/middleware/migration exports, pack metadata, and config for contract/migration generation.
Contract & migrations packages/3-extensions/cipherstash/src/contract/*, migrations/*	PSL contract, generated contract.json/.d.ts, and migration to install EQL bundle; migration materialisation helpers added.
Runtime SDK adapter & middleware examples/cipherstash-integration/src/sdk.ts, src/encryption/index.ts, src/db.ts, src/*	SDK adapter for @cipherstash/stack, encryption client wiring, bulk-encrypt middleware, and example runtime/demo app using cipherstashEq/cipherstashIlike plus decryptAll.
Example project & generated artifacts examples/cipherstash-integration/*	New example with config, prisma schema, migrations, generated contract DTS/JSON, tests, and type-only operator assertions.
Docs / DEVELOPING packages/3-extensions/cipherstash/README.md, DEVELOPING.md	Contributor guide and README for extension.
Tests & type checks examples/*/src/prisma/contract.d.ts, cipherstash-operators.types.ts	Generated artifacts and typetests updated to reflect integration.

---

Examples additions & utilities

Layer / File(s)	Summary
ParadeDB demo examples/paradedb-demo/*	Complete demo: docker-compose, Prisma contract with BM25 index, runtime db wiring, query helpers, CLI entry, seed/drop scripts, tests, configs.
Multi-extension monorepo example examples/multi-extension-monorepo/*	Two internal extension packs (audit, feature-flags) with contracts, migrations, control descriptors, and an e2e test asserting multi-space plan/app atomicity and ordering.
Various examples regenerated examples/prisma-next-demo/*, examples/prisma-next-cloudflare-worker/*	Regenerated contract DTS/JSON artifacts to match TypeMaps/operation-type changes; tests adjusted.
Tests / CI config many examples test files	Integration/type tests updated or added to validate new behaviors.

---

Docs, agents, rules, and misc

Layer / File(s)	Summary
Patterns & Architecture docs docs/architecture docs/patterns/*, docs/architecture docs/subsystems/*	Adds architecture pattern catalogue and multiple pattern pages; CLI subsystem doc; Mongo/CLI/Migration system additions.
Cursor rules / agent skills .agents/rules/*, .agents/skills/*, .cursor/rules/README.md	New explicit-opt-in-over-diagnostics rule, git signoff rule, reorganized drive-discussion/drive-pr-local-review skills; some skill files removed.
Dependabot / OSS docs .github/dependabot.yml, docs/oss/*, CONTRIBUTING.md, SECURITY.md	Dependabot cooldown config added; OSS governance & supply-chain docs; minor DCO whitespace fix.
Various exports / package map tweaks packages/*/package.json, tsdown/exports updates	New package exports added (index-types, middleware), small package manifest and dependency adjustments.
Tests updated widely many packages/*/test/*, examples tests	Extensive test updates to cover new shapes, API signatures, and behaviors.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User as User
  participant CLI as CLI (migration-apply)
  participant Loader as Aggregate Loader
  participant Planner as Graph-walk Planner
  participant Runner as Multi-space Runner
  participant DB as Database

  rect rgba(200, 230, 255, 0.5)
  User->>CLI: prisma-next migration apply
  CLI->>Loader: buildContractSpaceAggregate(contract.json, extensionPacks, appPackages)
  Loader-->>CLI: Aggregate { members, graphs }
  CLI->>DB: readAllMarkers()
  DB-->>CLI: markersBySpace (optional)
  CLI->>Planner: plan per space (graphWalkStrategy, markers, ref?)
  Planner-->>CLI: applyOrder + perSpace plans
  alt No pending ops
    CLI-->>User: Success (perSpace breakdown, 0 ops)
  else Pending ops
    CLI->>Runner: executeAcrossSpaces(applyOrder, perSpaceOptions)
    Runner->>DB: apply space N operations (transactional)
    DB-->>Runner: applied results per space
    Runner-->>CLI: perSpaceResults
    CLI-->>User: Success (applied totals, perSpace, pathDecision?)
  end
  end

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~180 minutes

Possibly related PRs

• prisma/prisma-next#430 — Introduces the same index-type registry and type/options propagation across authoring, validation, and emission.
• prisma/prisma-next#482 — Refactors CLI to operate over ContractSpaceAggregate with emitted extension dirs and per-space planning.
• prisma/prisma-next#439 — Adds/updates CipherStash contract-space artifacts and related migration/io utilities.

A rabbit hops in, with notes so neat,
Indexes typed and migrations complete.
Param slots bend where middlewares play,
Ciphered letters dance and stay.
Thump-thump—ship the change, then nap all day. 🐇

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2459-plan

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch tml-2459-plan

[pkg-pr-new]

Open in StackBlitz

@prisma-next/mongo-runtime

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

@prisma-next/family-mongo

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

@prisma-next/sql-runtime

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

@prisma-next/family-sql

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

@prisma-next/extension-arktype-json

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

@prisma-next/middleware-telemetry

npm i https://pkg.pr.new/@prisma-next/middleware-telemetry@460

@prisma-next/mongo

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

@prisma-next/extension-paradedb

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

@prisma-next/extension-pgvector

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

@prisma-next/postgres

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

@prisma-next/sql-orm-client

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

@prisma-next/sqlite

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

@prisma-next/target-mongo

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

@prisma-next/adapter-mongo

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

@prisma-next/driver-mongo

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

@prisma-next/contract

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

@prisma-next/utils

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

@prisma-next/config

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

@prisma-next/errors

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

@prisma-next/framework-components

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

@prisma-next/operations

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

@prisma-next/ts-render

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

@prisma-next/contract-authoring

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

@prisma-next/ids

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

@prisma-next/psl-parser

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

@prisma-next/psl-printer

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

@prisma-next/cli

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

@prisma-next/emitter

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

@prisma-next/migration-tools

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

prisma-next

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

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

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

@prisma-next/mongo-codec

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

@prisma-next/mongo-contract

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

@prisma-next/mongo-value

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

@prisma-next/mongo-contract-psl

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

@prisma-next/mongo-contract-ts

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

@prisma-next/mongo-emitter

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

@prisma-next/mongo-schema-ir

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

@prisma-next/mongo-query-ast

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

@prisma-next/mongo-orm

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

@prisma-next/mongo-query-builder

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

@prisma-next/mongo-lowering

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

@prisma-next/mongo-wire

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

@prisma-next/sql-contract

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

@prisma-next/sql-errors

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

@prisma-next/sql-operations

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

@prisma-next/sql-schema-ir

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

@prisma-next/sql-contract-psl

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

@prisma-next/sql-contract-ts

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

@prisma-next/sql-contract-emitter

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

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

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

@prisma-next/sql-relational-core

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

@prisma-next/sql-builder

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

@prisma-next/target-postgres

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

@prisma-next/target-sqlite

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

@prisma-next/adapter-postgres

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

@prisma-next/adapter-sqlite

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

@prisma-next/driver-postgres

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

@prisma-next/driver-sqlite

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

commit: 2653dba

[coderabbitai]

Actionable comments posted: 9

Note

Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

packages/2-sql/3-tooling/emitter/test/emitter-hook.generation.basic.test.ts (1)

954-957: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix generateContractDts argument placement in the execution-hash test

Line 954 is still using the old extra-array position, so hashes are not being passed in the same position as the rest of this file’s updated calls. This can make the test validate the wrong invocation path.

Suggested patch

-    const types = generateContractDts(ir, sqlEmission, [], [], {
-      ...testHashes,
-      executionHash: 'test-exec-hash',
-    });
+    const types = generateContractDts(ir, sqlEmission, [], {
+      ...testHashes,
+      executionHash: 'test-exec-hash',
+    });

🤖 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/2-sql/3-tooling/emitter/test/emitter-hook.generation.basic.test.ts`
around lines 954 - 957, The test call to generateContractDts is passing hashes
in the old extra-array position; change the invocation so the hashes object is
the sixth argument (not the fifth) to match other calls—i.e., call
generateContractDts(ir, sqlEmission, [], [], {}, { ...testHashes, executionHash:
'test-exec-hash' }) so the fifth argument is an empty options object and the
sixth carries the hashes (update the call in the execution-hash test referencing
generateContractDts).

packages/2-sql/5-runtime/test/sql-family-adapter.test.ts (1)

26-48: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Delegation test is currently tautological.

Line 38–48 only verifies a constant return value; it does not prove markerReader.readMarker actually forwards to the profile method with the provided queryable.

Suggested test hardening

-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
@@
-  it('delegates readMarker to adapter profile', async () => {
-    const adapter = new SqlFamilyAdapter(testContract, testProfile);
+  it('delegates readMarker to adapter profile', async () => {
+    const readMarker = vi.fn(async () => ({ kind: 'absent' as const }));
+    const adapter = new SqlFamilyAdapter(testContract, { ...testProfile, readMarker });
@@
     const result = await adapter.markerReader.readMarker(fakeQueryable);
 
+    expect(readMarker).toHaveBeenCalledWith(fakeQueryable);
     expect(result).toEqual({ kind: 'absent' });
   });

As per coding guidelines: "Avoid tautological tests that only restate fixture input - tests must verify behavior, not mirror object shape passed by the test itself."

🤖 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/2-sql/5-runtime/test/sql-family-adapter.test.ts` around lines 26 -
48, The test is tautological because it only asserts the fixture return; modify
it so markerReader.readMarker actually delegates to the profile's
implementation: replace the current testProfile or stub its readMarker with a
spy/fixture that records the queryable argument and returns a distinct value
(e.g., { kind: 'some' }) and then assert that calling
adapter.markerReader.readMarker(fakeQueryable) returns that distinct value and
that the profile.readMarker spy was invoked with the exact fakeQueryable;
reference the SqlFamilyAdapter constructor, adapter.markerReader.readMarker, and
the testProfile/readMarker stub to locate where to change the test.

packages/2-sql/5-runtime/src/sql-runtime.ts (1)

404-411: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Set startup verification state in the optional-missing marker branch.

On Line 409, verified is set but startupVerified remains false. In mode: 'startup', that re-runs verifyMarker() on every execute instead of one startup check.

Suggested fix

   if (readResult.kind !== 'present') {
     if (this.verify.requireMarker) {
       throw runtimeError('CONTRACT.MARKER_MISSING', 'Contract marker not found in database');
     }

     this.verified = true;
+    this.startupVerified = true;
     return;
   }

🤖 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/2-sql/5-runtime/src/sql-runtime.ts` around lines 404 - 411, The
optional-missing marker branch sets this.verified but forgets to set
this.startupVerified, causing verifyMarker() to re-run in mode: 'startup';
update the non-present branch inside the readResult.kind !== 'present' path
(where verify.requireMarker is false) to also set this.startupVerified = true
(in the same place you set this.verified) so startup mode treats the check as
completed and won't re-run on every execute; refer to readResult,
verify.requireMarker, this.verified, this.startupVerified, and
verifyMarker()/execute to locate and adjust the logic.

packages/1-framework/3-tooling/cli/src/utils/formatters/migrations.ts (1)

11-12: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Replace transient spec/milestone references in inline comments.

These comments reference transient artifacts (spec OQ-4, M6 sub-spec, AC4/AC5). Please rephrase them to stable behavioral intent.

As per coding guidelines, source-code comments must not reference transient project artifacts such as sub-spec sections or milestone acceptance criteria.

Also applies to: 91-92, 168-169, 404-405, 419-420

🤖 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/src/utils/formatters/migrations.ts` around
lines 11 - 12, Several inline comments in migrations.ts reference transient
artifacts (e.g., "spec OQ-4", "M6 sub-spec", "AC4/AC5"); update those comments
to state the stable behavioral intent instead (for example: describe the exact
rendering behavior, expected output format, or compatibility rationale). Locate
the commented lines mentioned (the block referencing legacy string[] renderer,
and the other occurrences around the indexes you saw) and replace the transient
labels with clear, version-agnostic descriptions of what the code must do or why
the special-case exists (e.g., "render byte-for-byte for legacy string[]
renderer", "preserve verbatim rendering for mongodb-shell", "ensure
backwards-compatible output formatting"), keeping the comment content focused on
behavior rather than milestones or acceptance criteria.

🟡 Minor comments (17)

docs/architecture docs/patterns/spi-at-lowest-consuming-layer.md-27-44 (1)

27-44: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add a language identifier to the fenced diagram block.

This code fence is missing a language tag and triggers MD040 in markdownlint.

Suggested patch

-```
+```text
 ┌────────────────────────────────────────────────────┐
 │ tooling / orchestration layer (the caller)         │
 │   imports the SPI; calls it; knows nothing about   │
@@
 └────────────────────────────────────────────────────┘

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In @docs/architecture docs/patterns/spi-at-lowest-consuming-layer.md around
lines 27 - 44, The fenced diagram block in spi-at-lowest-consuming-layer.md is
missing a language tag causing markdownlint MD040; update the triple-backtick
that opens the ASCII diagram to include a language identifier (e.g., text) so the block becomes text ... ```; locate the ASCII diagram block shown in the
diff and add the language tag to the opening fence only.

</details>

</blockquote></details>
<details>
<summary>docs/architecture docs/patterns/json-canonical-class-in-memory.md-28-42 (1)</summary><blockquote>

`28-42`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_

**Add a language identifier to the fenced structure diagram.**

This fence currently triggers MD040 (fenced code blocks should specify a language).

<details>
<summary>Suggested patch</summary>

```diff
-```
+```text
             authoring                      apply / consume
                 │                                 ▲
                 ▼                                 │
@@
        polymorphic                   reviewable, replayable
        dispatch                      across processes
 ```
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In @docs/architecture docs/patterns/json-canonical-class-in-memory.md around
lines 28 - 42, The fenced diagram block uses a plain fence without a language tag (triggering MD040); update the opening fence to include a language identifier such as "text" (e.g., change to ```text) for the ASCII-art
diagram in the fenced structure diagram so the linter recognizes the language
and MD040 is satisfied; locate the triple-backtick fence surrounding the ASCII
diagram and add the language token to the opening fence (leave the closing fence
unchanged).

</details>

</blockquote></details>
<details>
<summary>docs/architecture docs/patterns/json-canonical-class-in-memory.md-49-53 (1)</summary><blockquote>

`49-53`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_

**Reference links are accidentally code-formatted, so they won’t render as links.**

The `Path` cells wrap the entire markdown link in backticks (`` `[...](...)` ``), which turns them into code literals.

<details>
<summary>Suggested patch</summary>

```diff
-| Migration `ops.json` (Mongo)    | `[packages/3-mongo-target/1-mongo-target/src/core/op-factory-call.ts](../../../packages/3-mongo-target/1-mongo-target/src/core/op-factory-call.ts)`                     | `OpFactoryCall` classes serialise via `JSON.stringify` to `ops.json`; the runner rehydrates and walks the same class hierarchy at apply time.  |
-| Migration `ops.json` (Postgres) | `[packages/3-targets/3-targets/postgres/src/core/migrations/op-factory-call.ts](../../../packages/3-targets/3-targets/postgres/src/core/migrations/op-factory-call.ts)` | Same shape on the SQL side; demonstrates the pattern is target-agnostic.                                                                       |
-| Mongo wire commands             | `[packages/2-mongo-family/6-transport/mongo-wire/src/wire-commands.ts](../../../packages/2-mongo-family/6-transport/mongo-wire/src/wire-commands.ts)`                   | Wire commands round-trip natively because MongoDB commands *are* JSON; the canonical example of the pattern's "JSON is the contract" property. |
+| Migration `ops.json` (Mongo)    | [`packages/3-mongo-target/1-mongo-target/src/core/op-factory-call.ts`](../../../packages/3-mongo-target/1-mongo-target/src/core/op-factory-call.ts)                     | `OpFactoryCall` classes serialise via `JSON.stringify` to `ops.json`; the runner rehydrates and walks the same class hierarchy at apply time.  |
+| Migration `ops.json` (Postgres) | [`packages/3-targets/3-targets/postgres/src/core/migrations/op-factory-call.ts`](../../../packages/3-targets/3-targets/postgres/src/core/migrations/op-factory-call.ts) | Same shape on the SQL side; demonstrates the pattern is target-agnostic.                                                                       |
+| Mongo wire commands             | [`packages/2-mongo-family/6-transport/mongo-wire/src/wire-commands.ts`](../../../packages/2-mongo-family/6-transport/mongo-wire/src/wire-commands.ts)                   | Wire commands round-trip natively because MongoDB commands *are* JSON; the canonical example of the pattern's "JSON is the contract" property. |
```
</details>

   
As per coding guidelines, "Keep docs current (READMEs, rules, links) (see `.cursor/rules/doc-maintenance.mdc`)."

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In `@docs/architecture` docs/patterns/json-canonical-class-in-memory.md around
lines 49 - 53, The table in docs/architecture
docs/patterns/json-canonical-class-in-memory.md has its Path cells formatted as
code literals (backticked) so links won't render; edit the rows such as
"Migration `ops.json` (Mongo)", "Migration `ops.json` (Postgres)" and "Mongo
wire commands" and remove the surrounding backticks around the markdown links
(e.g. change `[...](...)` wrapped with backticks to plain `[...](...)`) so the
links render as clickable links while keeping the visible text and target
unchanged.
```

</details>

</blockquote></details>
<details>
<summary>docs/architecture docs/patterns/capability-gating.md-27-44 (1)</summary><blockquote>

`27-44`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_

**Add a language identifier on the fenced example block.**

At Line 27, add a language tag (for example `ts`) to clear MD040.

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In @docs/architecture docs/patterns/capability-gating.md around lines 27 - 44,
The fenced code block containing the example of capability objects and the
consumption-site check (showing symbols like contract.capabilities,
adapter.profile.capabilities, lowerWithLateral, lowerWithCorrelatedSubquery)
needs a language tag to satisfy MD040; update the opening triple-backtick to
include a language identifier such as ts (e.g., change tots) so the
block is marked as TypeScript.

</details>

</blockquote></details>
<details>
<summary>docs/architecture docs/patterns/frozen-class-ast.md-28-53 (1)</summary><blockquote>

`28-53`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_

**Specify the code-fence language to satisfy markdown linting.**

At Line 28, add a language token (`ts`) so MD040 passes.

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In @docs/architecture docs/patterns/frozen-class-ast.md around lines 28 - 53,
The code fence at the top of the snippet is missing a language token which
causes MD040; update the opening triple-backtick to include the TypeScript token
(i.e., change tots) so the fenced block containing the FooAstNode,
FooLiteral, FooVisitor, accept and rewrite examples is treated as TypeScript for
linting.

</details>

</blockquote></details>
<details>
<summary>docs/architecture docs/patterns/package-layering.md-35-49 (1)</summary><blockquote>

`35-49`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_

**Add a language identifier to the fenced block.**

At Line 35, the code fence is missing a language tag, which will keep `markdownlint` warning MD040 active.

<details>
<summary>Suggested patch</summary>

```diff
-```
+```text
 packages/
 ├── 1-framework/        # Framework domain (target-agnostic)
 │   ├── 1-core/         # Lowest layer; foundational types
@@
 ├── 3-mongo-target/     # Mongo target
 └── 3-extensions/       # Extension packs (pgvector, sql-orm-client, …)
 ```
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In @docs/architecture docs/patterns/package-layering.md around lines 35 - 49,
The fenced code block that starts with the "packages/" tree is missing a
language tag which triggers markdownlint MD040; update the opening
triple-backtick for that block to include a language identifier (e.g., change
totext) so the snippet is treated as plain text; locate the block that
begins with "packages/" and modify only the opening fence to add the language
identifier.

</details>

</blockquote></details>
<details>
<summary>docs/architecture docs/patterns/three-layer-polymorphic-ir.md-29-52 (1)</summary><blockquote>

`29-52`: _⚠️ Potential issue_ | _🟡 Minor_ | _⚡ Quick win_

**Add a language tag to the fenced diagram block.**

Line 29 uses a plain fenced block; `markdownlint` (`MD040`) expects a language identifier, and this can break lint gates.

 
<details>
<summary>Suggested fix</summary>

```diff
-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
 │ framework layer (target-agnostic)                           │
 ...
 └─────────────────────────────────────────────────────────────┘
 ```
```
</details>
As per coding guidelines, keep docs current and passing repository documentation standards.

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In @docs/architecture docs/patterns/three-layer-polymorphic-ir.md around lines
29 - 52, The fenced ASCII diagram block starting with the "framework layer
(target-agnostic)" text is missing a language identifier which triggers
markdownlint MD040; fix it by adding a language tag (e.g., "text") to the
opening triple-backtick fence for that diagram block so the block becomes

examples/paradedb-demo/docker-compose.yaml-3-3 (1)

3-3: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Pin ParadeDB image to an immutable tag (or digest).

Using :latest makes local setup non-reproducible and can break example behavior unexpectedly when upstream updates.

🤖 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 `@examples/paradedb-demo/docker-compose.yaml` at line 3, Replace the mutable
image tag "paradedb/paradedb:latest" with an immutable reference to make the
example reproducible; update the Docker Compose service image (the line
containing image: paradedb/paradedb:latest) to a specific version tag like
paradedb/paradedb:vX.Y.Z or a content-addressable digest form
paradedb/paradedb@sha256:<digest>, and document or pin the chosen tag/digest in
the example README so future runs use the exact same image.

packages/1-framework/3-tooling/migration/test/invariants.test.ts-62-66 (1)

62-66: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove transient sub-spec references from this inline comment.

Line 66 references sub-spec § 3, which violates the repo’s source-comment policy for transient artifacts. Reword this to describe behavior directly without spec-section pointers.

As per coding guidelines: "Source-code comments must not reference transient project artifacts ... and sub-spec section references (e.g., § 3.2)."

🤖 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/migration/test/invariants.test.ts` around
lines 62 - 66, Update the inline comment in invariants.test.ts (the block that
mentions Cipherstash's `installEqlBundle` and structural `create-*` ops) to
remove the transient reference "sub-spec § 3 / cipherstash-migration.spec.md"
and instead describe the behavior directly: state that those operations are the
canonical examples of additive operations that include invariantIds for marker
bookkeeping and replay tracking, and clarify the distinction between
operationClass (policy gating) and invariantId (replay tracking).

packages/1-framework/3-tooling/cli/test/commands/migration-show.test.ts-335-338 (1)

335-338: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove transient milestone/task identifiers from the inline comment.

Please avoid T6.6 / AC8 references in source comments and keep only behavior-focused wording.

Proposed edit

-    // M6 (T6.6 / AC8): operationClass tags no longer inlined in the
+    // Operation-class tags are no longer inlined in the
     // human-readable line. Destructive ops still render a "(destructive)"
     // marker (replaces the old "[destructive]" tag); additive/widening/
     // mutative/data render bare.

As per coding guidelines: "Source-code comments must not reference transient project artifacts including ... milestone-task IDs ... [and] milestone-named acceptance criteria."

🤖 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/migration-show.test.ts`
around lines 335 - 338, Remove the transient milestone/task identifiers "T6.6 /
AC8" from the inline comment that begins with "M6 (T6.6 / AC8): operationClass
tags no longer inlined..." in migration-show.test.ts and rewrite it to be
behavior-focused (e.g., "M6: operationClass tags no longer inlined in the
human-readable line. Destructive ops still render a '(destructive)' marker;
additive/widening/mutative/data render bare."). Ensure only the transient IDs
are removed and the comment still documents the expected behavior.

examples/paradedb-demo/prisma-next.config.ts-19-20 (1)

19-20: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove lint suppression and handle missing DATABASE_URL explicitly.

This bypasses the lint policy and hides a clearer config error path. Prefer resolving the env var once and throwing a direct error if absent, then pass a non-null value to connection.

As per coding guidelines: “Never suppress biome lints.”

🤖 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 `@examples/paradedb-demo/prisma-next.config.ts` around lines 19 - 20, Remove
the biome lint suppression and stop using the non-null assertion on
process.env['DATABASE_URL']!; instead, read process.env['DATABASE_URL'] into a
local constant (e.g., const databaseUrl = process.env['DATABASE_URL']), verify
it is defined and throw a clear error if missing, then pass that validated
non-null value into the connection field (replace the use of
process.env['DATABASE_URL']! in the connection setting). Ensure the thrown error
message clearly states that DATABASE_URL is required.

packages/1-framework/3-tooling/migration/test/materialise-extension-migration-package-if-missing.test.ts-42-42 (1)

42-42: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove transient acceptance-criteria IDs from the comment.

Please reword this line to describe the invariant directly without AC-7 / AM12 identifiers.

As per coding guidelines: “Source-code comments must not reference transient project artifacts including milestone acceptance criteria.”

🤖 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/migration/test/materialise-extension-migration-package-if-missing.test.ts`
at line 42, Update the test title string in the it(...) call so it no longer
references transient IDs; replace "leaves on-disk content byte-identical when
the dir already exists (AC-7 / AM12)" with a direct invariant description such
as "leaves on-disk content byte-identical when the directory already exists" in
the test defined by the it(...) invocation to remove the acceptance-criteria
identifiers.

packages/1-framework/3-tooling/cli/test/output.migration-commands.test.ts-22-24 (1)

22-24: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Avoid transient milestone/spec references in test comments.

Please rewrite these comments to describe behavior directly (without M6, AC*, or sub-spec references), per repo doc-maintenance rules.

As per coding guidelines: “Source-code comments must not reference transient project artifacts including milestone-task IDs, milestone acceptance criteria, and sub-spec references.”

Also applies to: 57-57, 64-64

🤖 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/output.migration-commands.test.ts`
around lines 22 - 24, The comment above the assertion
expect(stripped).toContain('Next: prisma-next migration status') (and similar
comments at the other noted locations) includes transient milestone/sub-spec
references (e.g., "M6 sub-spec § Output shape § footer"); replace those comments
with a concise description of the observable behavior being tested — for
example: state that a no-op apply still shows the canonical next-step hint so
the user knows where to verify state — and remove any mentions of milestone IDs,
acceptance criteria tags, or sub-spec references; update the comment text near
the assert in output.migration-commands.test.ts accordingly.

packages/3-extensions/cipherstash/DEVELOPING.md-57-58 (1)

57-58: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use consistent Arktype capitalization in docs.

Line 58 uses arktype; the rest of the repo/docs use Arktype. Aligning wording improves grep/search consistency.

✏️ Suggested doc fix

-- `RuntimeParameterizedCodecDescriptor<{ equality, freeTextSearch }>`
-  with arktype `paramsSchema` validated at the contract boundary.
+- `RuntimeParameterizedCodecDescriptor<{ equality, freeTextSearch }>`
+  with Arktype `paramsSchema` validated at the contract boundary.

🤖 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/3-extensions/cipherstash/DEVELOPING.md` around lines 57 - 58, Change
the lowercase "arktype" to the project-standard "Arktype" in the docs where
`RuntimeParameterizedCodecDescriptor<{ equality, freeTextSearch }>` and
`paramsSchema` are described so the wording is consistent; update the phrase on
the line that currently reads "arktype `paramsSchema`" to "Arktype
`paramsSchema`" to match other docs and repo grep conventions.

examples/multi-extension-monorepo/test/multi-space.e2e.integration.test.ts-1-47 (1)

1-47: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Replace milestone/tracking IDs in comments with durable behavior wording.

The block comment currently includes transient identifiers (T4.4, TC-8, AC5, NFR6). Please keep only stable behavior descriptions.

As per coding guidelines, “Source-code comments must not reference transient project artifacts including milestone-task IDs and milestone acceptance criteria codes.”

🤖 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 `@examples/multi-extension-monorepo/test/multi-space.e2e.integration.test.ts`
around lines 1 - 47, The top block comment in the test (the multi-extension
monorepo E2E description and the "Layers of coverage" numbered list) contains
transient milestone/tracking IDs (e.g., T4.4, TC-8, AC5, NFR6); remove those IDs
and rewrite any reference to them as stable behavioral descriptions only,
preserving the existing numbered coverage points and examples (the "Pinned
per-space artefacts on disk", "Multi-space planning", "Multi-space apply", and
"Order-independent" paragraphs) so the comment documents durable behavior rather
than project task identifiers.

packages/1-framework/3-tooling/cli/test/output.db-update.test.ts-82-83 (1)

82-83: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove transient milestone/acceptance references from inline comments.

These comments encode temporary tracking labels (M6, T6.6, AC*, spec/OQ) instead of durable behavior intent. Please rewrite them as plain behavior-focused notes.

As per coding guidelines, “Source-code comments must not reference transient project artifacts including milestone-task IDs and milestone acceptance criteria codes.”

Also applies to: 198-202, 300-303, 385-390

🤖 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/output.db-update.test.ts` around
lines 82 - 83, Replace transient project-tracking labels in inline comments
(e.g. the comment starting "// M6 (T6.6 / AC8): inline operationClass tags
removed; destructive ops keep a "(destructive)" marker on the same line.") with
plain, behavior-focused notes that state the intent (for example: "Inline
operationClass tags are removed; destructive operations retain a '(destructive)'
marker on the same line."). Apply the same change to the other commented blocks
referenced (lines ~198-202, ~300-303, ~385-390), removing milestone/task/AC/spec
codes and keeping only durable descriptions of behavior or requirements.

packages/1-framework/3-tooling/cli/src/control-api/operations/migration-apply.ts-73-74 (1)

73-74: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove transient sub-spec references from source comments.

Comments now include Sub-spec § ... references; these are transient artifacts and should be rewritten as stable behavior descriptions.

As per coding guidelines, source-code comments must not reference transient artifacts such as sub-spec section references.

Also applies to: 113-114

🤖 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/src/control-api/operations/migration-apply.ts`
around lines 73 - 74, Remove the transient "Sub-spec § ..." reference in the
comment containing "Sub-spec § `--ref <hash>` semantics under multi-space." and
rewrite it as a stable, descriptive sentence that explains the actual behavior
of the --ref option (e.g., that --ref accepts a migration hash to target a
specific migration across multiple spaces and how conflicts are resolved), and
make the same change for the other comment at the block referenced by lines
113-114; update the comment text near the migration-apply module (the comment
containing "`--ref <hash>` semantics under multi-space") so it documents
concrete behavior rather than a sub-spec pointer.

🧹 Nitpick comments (13)

.agents/rules/explicit-opt-in-over-diagnostics.mdc (1)

3-47: ⚡ Quick win

Trim or de-scope this as an always-applied rule.

Given alwaysApply: true, this is too long for an always-on rulecard. Keep a short always-on directive and move examples/rationale to a non-always rule (or docs), or set alwaysApply: false with scoped globs if this is domain-specific.

Proposed frontmatter-level adjustment

 ---
 description: Prefer requiring explicit opt-in over emitting diagnostics on intentional user paths
-alwaysApply: true
+alwaysApply: false
+globs:
+  - "**/*.{ts,tsx,js,md,mdc}"
 ---

Based on learnings: "Always-apply rules must be short, globally relevant, and stable; rules applying only to specific areas (SQL, CLI, tests) should set alwaysApply: false and use globs in frontmatter".

🤖 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 @.agents/rules/explicit-opt-in-over-diagnostics.mdc around lines 3 - 47, The
rule is too long and domain-specific to remain always-on; update the frontmatter
by either (A) trimming this card to a short, globally-relevant directive and
moving examples/rationale into a non-always rule or external docs, or (B) change
alwaysApply: true to alwaysApply: false and add targeted globs so it only runs
for relevant files (e.g., SQL/CLI/test paths); locate the top-level frontmatter
key alwaysApply and the rule body titled "Explicit opt-in over noisy
diagnostics" to make the change and move or reduce the examples accordingly.

.agents/skills/drive-create-spec/SKILL.md (1)

104-104: 💤 Low value

Consider consistent spelling: use "implementer" instead of "implementor".

Lines 104 and 112 use "implementor". The rest of the codebase consistently uses "implementer" (found in projects/oss-setup/spec.md and projects/extension-contract-spaces/spec.md). Standardizing on "implementer" aligns with the established codebase convention and modern technical writing usage.

🤖 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 @.agents/skills/drive-create-spec/SKILL.md at line 104, Replace the
nonstandard spelling "implementor" with the codebase-preferred "implementer"
wherever it appears in the SKILL.md requirement wording (the requirement
sentences that currently read "implementor"). Update both instances reported
(the two requirement lines) and run a quick grep/search for any other
occurrences to ensure consistency with projects/oss-setup/spec.md and
projects/extension-contract-spaces/spec.md; no behavioral changes required, just
textual replacement.

packages/2-sql/2-authoring/contract-psl/src/psl-attribute-parsing.ts (1)

209-243: 💤 Low value

Escape handling covers common cases.

The escape detection logic (line 219: body[index - 1] !== '\\') handles simple escaped quotes but wouldn't correctly handle edge cases like escaped backslashes followed by quotes ("value\\"). For V1 PSL string options this is acceptable, as the diagnostic message indicates this is a limited surface. The actual quote parsing/unescaping is delegated to parseQuotedStringLiteral which likely handles these cases properly.

💡 Future consideration for more robust escape handling

For completeness, counting consecutive backslashes would handle all escape sequences:

 function splitObjectLiteralEntries(body: string): readonly string[] {
   // ... existing setup ...
   for (let index = 0; index < body.length; index += 1) {
     const ch = body[index] ?? '';
     if (quote) {
-      if (ch === quote && body[index - 1] !== '\\') {
+      // Count consecutive backslashes before quote
+      let backslashCount = 0;
+      for (let j = index - 1; j >= 0 && body[j] === '\\'; j--) backslashCount++;
+      if (ch === quote && backslashCount % 2 === 0) {
         quote = null;
       }

Not needed for V1, but worth considering if PSL object literals expand beyond simple string options.

🤖 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/2-sql/2-authoring/contract-psl/src/psl-attribute-parsing.ts` around
lines 209 - 243, splitObjectLiteralEntries' quote-termination logic incorrectly
treats a quote as unescaped if the immediately preceding char is not a single
backslash; update the check inside the if (quote) block so you count consecutive
backslashes immediately before body[index] and only treat the quote as closing
when that count is even (i.e., not escaped). Modify the logic in
splitObjectLiteralEntries (the quote handling around body[index - 1] !== '\\')
to walk backward from index-1, count backslashes, and use count % 2 === 0 to
decide whether to clear quote, leaving the rest of the function intact.

packages/2-sql/4-lanes/relational-core/src/plan.ts (1)

24-40: ⚡ Quick win

Remove manual line wrapping from JSDoc.

The JSDoc comment spans multiple paragraphs with manual ~80-column line breaks. Per coding guidelines, JSDoc prose should avoid manual wrapping.

📝 Proposed fix

 /**
- * Wraps an `AnyQueryAst` (typically a `RawSqlExpr` constructed package-internally
- * by an extension's migration factory) in a fully-populated `SqlQueryPlan`
- * whose `meta` is sourced from the supplied contract.
+ * Wraps an `AnyQueryAst` (typically a `RawSqlExpr` constructed package-internally by an extension's migration factory) in a fully-populated `SqlQueryPlan` whose `meta` is sourced from the supplied contract.
  *
- * Centralising the envelope here means consumers (cipherstash migration
- * factories today; future raw-sql callers) cannot drift on `storageHash` /
- * `target` / `targetFamily`, which would otherwise surface as a subtle
- * `assertContractMatches` failure inside `dataTransform`. `params` defaults
- * to `[]` because parameters embedded in the AST as `ParamRef`s are resolved
- * at lowering time (`encodeParams` walks `plan.ast.collectParamRefs()`),
- * not at plan-construction time.
+ * Centralising the envelope here means consumers (cipherstash migration factories today; future raw-sql callers) cannot drift on `storageHash` / `target` / `targetFamily`, which would otherwise surface as a subtle `assertContractMatches` failure inside `dataTransform`. `params` defaults to `[]` because parameters embedded in the AST as `ParamRef`s are resolved at lowering time (`encodeParams` walks `plan.ast.collectParamRefs()`), not at plan-construction time.
  *
- * The default `laneId` of `'raw'` reflects raw-SQL plans' standard lane tag;
- * callers (e.g. a future `sql-raw-factory`) may override to differentiate
- * the plan's provenance.
+ * The default `laneId` of `'raw'` reflects raw-SQL plans' standard lane tag; callers (e.g. a future `sql-raw-factory`) may override to differentiate the plan's provenance.
  */

🤖 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/2-sql/4-lanes/relational-core/src/plan.ts` around lines 24 - 40, The
JSDoc above the SqlQueryPlan wrapper contains manual ~80-column line breaks and
multi-paragraph wrapped text; reflow the comment into normal, unwrapped prose
(single or multiple paragraphs as appropriate) without manual line breaks,
preserving all original content and references to AnyQueryAst, RawSqlExpr,
SqlQueryPlan, params, storageHash/target/targetFamily, encodeParams, and the
default laneId 'raw' so the documentation reads naturally and adheres to the
project's JSDoc guidelines.

packages/2-sql/4-lanes/relational-core/src/ast/adapter-types.ts (1)

12-14: ⚡ Quick win

Remove manual line wrapping from JSDoc.

The JSDoc comment uses manual ~80-column line wraps. Per coding guidelines, JSDoc prose should avoid manual line breaks and allow the formatter/viewer to handle wrapping.

📝 Proposed fix

-/**
- * Outcome of an adapter's marker read. `no-table` means the marker storage itself is absent (e.g. attaching to a database that was never `db init`'d); `absent` means the storage exists but holds no row for the requested space; `present` carries the parsed record. Callers distinguish these so runtime telemetry and `requireMarker` policy can react to each case appropriately.
- */
+/** Outcome of an adapter's marker read. `no-table` means the marker storage itself is absent (e.g. attaching to a database that was never `db init`'d); `absent` means the storage exists but holds no row for the requested space; `present` carries the parsed record. Callers distinguish these so runtime telemetry and `requireMarker` policy can react to each case appropriately. */

🤖 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/2-sql/4-lanes/relational-core/src/ast/adapter-types.ts` around lines
12 - 14, The JSDoc above the adapter marker read outcome is manually wrapped to
~80 columns; remove the manual line breaks so the comment becomes a single
unbroken paragraph (no hard line wraps) describing the three statuses
(`no-table`, `absent`, `present`) and their semantics; update the comment block
located above the adapter marker read type/definition in adapter-types.ts (the
JSDoc that begins "Outcome of an adapter's marker read") so formatting is
natural prose with no manual line wrapping.

packages/2-sql/5-runtime/src/codecs/alias-resolver.ts (1)

24-26: ⚡ Quick win

Remove manual line wrapping from inline comment.

The inline comment uses manual line breaks. Per coding guidelines, comments should avoid manual ~80-column wrapping.

📝 Proposed fix

   } else if (ast.kind === 'raw-sql') {
-    // Raw-SQL ASTs do not bind a single primary table — alias resolution
-    // is driven by inline `IdentifierRef`s the caller embedded directly.
+    // Raw-SQL ASTs do not bind a single primary table — alias resolution is driven by inline `IdentifierRef`s the caller embedded directly.
   } else {

🤖 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/2-sql/5-runtime/src/codecs/alias-resolver.ts` around lines 24 - 26,
The inline comment inside the else if (ast.kind === 'raw-sql') branch contains
manual line breaks; replace it with a single unwrapped comment line (or let the
editor handle wrapping) so it reads continuously (e.g., "// Raw-SQL ASTs do not
bind a single primary table — alias resolution is driven by inline
`IdentifierRef`s the caller embedded directly.") while keeping the same wording
and meaning.

packages/2-sql/2-authoring/contract-ts/src/contract-dsl.ts (1)

699-706: ⚡ Quick win

Use ifDefined() for new conditional spreads in index().

Line 702–706 uses inline spread conditionals for name, type, and options; this should follow the project’s ifDefined() pattern for consistency.

♻️ Suggested refactor

   return {
     kind: 'index',
     fields: normalizeFieldRefInput(fields),
-    ...(options?.name !== undefined ? { name: options.name } : {}),
-    ...(options?.type !== undefined ? { type: options.type } : {}),
-    ...(options?.options !== undefined
-      ? { options: options.options as Record<string, unknown> }
-      : {}),
+    ...ifDefined('name', options?.name),
+    ...ifDefined('type', options?.type),
+    ...ifDefined('options', options?.options as Record<string, unknown>),
   };

As per coding guidelines, "{packages,examples,test}/**/*.{ts,tsx}: Use ifDefined() from @prisma-next/utils/defined for conditional object spreads instead of inline conditional spread patterns."

🤖 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/2-sql/2-authoring/contract-ts/src/contract-dsl.ts` around lines 699
- 706, The index() return object uses inline conditional spreads for name, type,
and options; replace those with calls to ifDefined(...) from
'@prisma-next/utils/defined' to match project pattern. Import ifDefined at the
top if missing, then change the object to include ifDefined('name',
options?.name), ifDefined('type', options?.type), and ifDefined('options',
options?.options as Record<string, unknown>) while keeping the existing kind and
fields (normalizeFieldRefInput(fields)) intact. Ensure types remain the same and
remove the inline ...(condition ? { key: value } : {}) spreads.

packages/1-framework/3-tooling/cli/test/utils/extension-pack-inputs.test.ts (1)

25-31: 💤 Low value

Prefer double-cast pattern for test stub objects.

The empty-cast stubs use direct casts ({} as MigrationMetadata), but the test-mocking guideline recommends double casts (as unknown as X) for clarity and safety at mock boundaries.

♻️ Refactor to use double-cast pattern

-const STUB_METADATA = {} as MigrationMetadata;
-const STUB_OPS = {} as MigrationOps;
+const STUB_METADATA = {} as unknown as MigrationMetadata;
+const STUB_OPS = {} as unknown as MigrationOps;
 const migrationPkg: DescriptorMigrationPackage = {

As per coding guidelines, use double casts (as unknown as X) for mocks and dynamic proxies in tests instead of direct casts.

🤖 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/utils/extension-pack-inputs.test.ts`
around lines 25 - 31, The test uses direct casts for stub objects
(STUB_METADATA, STUB_OPS) which should be replaced with the double-cast pattern;
update the declarations so the empty object is cast as unknown first and then to
the target type (e.g., STUB_METADATA and STUB_OPS should be created as {} as
unknown as MigrationMetadata and {} as unknown as MigrationOps) and ensure any
uses in migrationPkg remain unchanged.

packages/1-framework/3-tooling/cli/src/control-api/operations/apply-aggregate.ts (1)

206-211: ⚡ Quick win

Drop transient spec references in implementation comments.

Line 210 references M6 sub-spec § Required changes 1; please replace it with a behavior-focused comment only.

As per coding guidelines, source-code comments must not reference transient project artifacts such as sub-spec section pointers.

🤖 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/src/control-api/operations/apply-aggregate.ts`
around lines 206 - 211, Update the implementation comment above the function
that projects planner per-space resolutions into
AggregatePerSpaceExecutionEntry[] (the comment that references "M6 sub-spec §
Required changes 1") to remove the transient sub-spec pointer and instead
describe the intended behavior: explain that for apply-mode (includeMarkers ===
true) the function should include marker-adjusted entries per space, and for
non-apply modes it should omit markers and only emit executed resolution data;
mention the relevant symbols AggregatePerSpaceExecutionEntry and includeMarkers
to make the behavioral intent clear.

packages/1-framework/3-tooling/cli/src/control-api/operations/db-apply-aggregate.ts (1)

130-134: ⚡ Quick win

Please replace transient planning references in comments with behavior-only wording.

Line 132 and Line 210 currently reference milestone/spec artifacts. Keep these comments implementation-focused so they remain stable as planning docs evolve.

As per coding guidelines, source-code comments must avoid transient artifacts like milestone references and sub-spec section pointers.

Also applies to: 206-210

🤖 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/src/control-api/operations/db-apply-aggregate.ts`
around lines 130 - 134, Replace transient planning/spec references in the
comments around the orphan-marker pre-flight logic in db-apply-aggregate.ts (the
block mentioning "Orphan-marker pre-flight", "M2 marker-check", and the call
runContractSpaceVerifierMarkerCheck and references to `db init` / `db update`).
Reword those lines (including the ones around 206-210 and specifically the prior
mention at line ~132) to behavior-only wording: describe what the code does
(e.g., "refuse to apply when a marker row exists for a space that is not
declared in the aggregate; this mirrors the marker check performed by
runContractSpaceVerifierMarkerCheck and runs before planning to prevent applying
with orphaned markers") and remove any milestone/spec section references or
transient planning artifacts.

packages/1-framework/3-tooling/cli/src/control-api/types.ts (1)

319-323: ⚡ Quick win

Remove transient planning references from source comments.

Line 319, Line 540, and Line 628 include sub-spec § / F4/F7 style references. Please rewrite these comments to describe behavior directly without milestone/spec artifact pointers.

As per coding guidelines, source-code comments must not reference transient artifacts such as sub-spec sections or milestone acceptance identifiers.

Also applies to: 540-541, 628-633

🤖 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/src/control-api/types.ts` around lines 319
- 323, Remove transient milestone/spec references from the inline comment that
currently begins "M6 sub-spec § Output shape contract — every space involved in
a run is observable in the success summary, including its post-apply marker, so
the per-space invariant is visible to the user (closing F4 / F7 from
`e2e-verification.md`)." and the other comment blocks that mention "sub-spec §"
/ "F4/F7"; instead rewrite each comment to state the behavior directly (for
example: "Output contract: the success summary must include every space involved
in a run along with its post-apply marker so users can observe the per-space
invariant") and apply the same treatment to the similar comments that reference
sub-specs or milestone IDs elsewhere in this file; keep the text focused on the
observed behavior and acceptance criteria without referencing spec sections or
milestone identifiers.

packages/1-framework/3-tooling/migration/src/aggregate/strategies/graph-walk.ts (1)

59-62: ⚡ Quick win

Use ifDefined() for conditional spread here.

Replace the inline conditional spread with the shared ifDefined() helper for consistency with repo conventions.

As per coding guidelines: “Use ifDefined() from @prisma-next/utils/defined for conditional object spreads instead of inline conditional spread patterns.”

🤖 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/migration/src/aggregate/strategies/graph-walk.ts`
around lines 59 - 62, The conditional spread when calling findPathWithDecision
should use the shared helper ifDefined from `@prisma-next/utils/defined` rather
than an inline ternary; update the call that constructs the options object (the
call assigning outcome via findPathWithDecision(graph, fromHash,
member.headRef.hash, { required, ...(refName !== undefined ? { refName } : {}),
})) to import and use ifDefined to include refName only when defined (e.g., {
required, ...ifDefined('refName', refName) } pattern), keeping the other
parameters (graph, fromHash, member.headRef.hash, required) unchanged and
ensuring the ifDefined helper is imported at the top of the file.

packages/1-framework/3-tooling/cli/src/control-api/operations/migration-apply.ts (1)

209-209: ⚡ Quick win

Use ifDefined() instead of ternary conditional spreads for optional fields.

This file mixes both patterns. Please switch these conditional spreads to ifDefined(...) for consistency with the repo standard.

Proposed refactor

-      ...(isAppMember && refName !== undefined ? { refName } : {}),
+      ...ifDefined('refName', isAppMember ? refName : undefined),

-        ...(isAppMember && refName !== undefined ? { refName } : {}),
+        ...ifDefined('refName', isAppMember ? refName : undefined),

-        ...(appPlan.pathDecision.refName !== undefined
-          ? { refName: appPlan.pathDecision.refName }
-          : {}),
+        ...ifDefined('refName', appPlan.pathDecision.refName),

-    ...(pathDecision !== undefined ? { pathDecision } : {}),
+    ...ifDefined('pathDecision', pathDecision),

Based on learnings, this repo prefers ifDefined for conditional object spreads instead of inline ternary spread patterns.

Also applies to: 234-234, 429-431, 450-450

🤖 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/src/control-api/operations/migration-apply.ts`
at line 209, Replace the inline ternary spread patterns like ...(isAppMember &&
refName !== undefined ? { refName } : {}) with the repository-standard
ifDefined(...) helper; e.g. use ifDefined(refName, v => ({ refName: v })) (or
ifDefined(isAppMember && refName, v => ({ refName: v })) if the presence depends
on a separate boolean) and apply the same replacement for the other conditional
spreads mentioned (the similar ternary spreads at the other occurrences).

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Reframe capability ownership: adapter-reported; contract declares requirements.

This section currently presents capabilities as defined on the contract (contract.capabilities), which conflicts with the documented ownership model. Please reword and adjust the example to show contract requirements vs adapter-reported offered capabilities.

As per coding guidelines: "Describe capabilities as adapter-reported and negotiated at connect time" and "Frame contract capabilities as requirements, not definitions".

Also applies to: 27-37

🤖 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 `@docs/architecture` docs/patterns/capability-gating.md around lines 10 - 11,
Update the wording and example so capabilities are presented as adapter-reported
(offered) and the contract only declares required capabilities; specifically
replace usages that treat contract.capabilities as definitions with phrasing
that the contract lists required capability names while adapters advertise
offered capabilities (e.g., adapter.capabilities or
adapter.profile.capabilities) and show a negotiation/connect-time check that
validates adapter-offered capabilities against contract requirements; also apply
the same reframing to the later example/use around the other occurrences
currently mirroring the incorrect ownership model.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Remove @ts-nocheck from declaration output.

This suppresses type safety entirely and violates repo policy for TS sources. If this is a placeholder, keep it type-checkable with explicit minimal declarations instead of globally disabling checks.

As per coding guidelines: **/*.{ts,tsx}: Never use @ts-nocheck``.

🤖 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 `@examples/cipherstash-integration/migrations/cipherstash/contract.d.ts` at
line 1, Remove the top-level "// `@ts-nocheck`" in contract.d.ts and make the file
type-checkable by adding explicit minimal declarations for the exported
migration/contract types instead of disabling checks; specifically replace the
nocheck with concrete exported declarations (e.g., export interface/ type for
the contract/migration shapes or declare module exports used elsewhere) so every
exported symbol is typed and the file passes tsc without suppressing
diagnostics.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Validate command/arguments before opening the DB connection.

Right now, invalid/unknown command paths still attempt db.connect(...) first. That makes usage/error flows fail on DB/env issues even when no query should run. Parse/validate first, then connect only for executable commands.

Also applies to: 115-120

🤖 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 `@examples/paradedb-demo/src/main.ts` around lines 50 - 53, Validate and parse
the CLI command/arguments before opening the DB connection: in main, call your
argument parsing/validation routine (e.g., parseArgs/validateCommand) and check
that the requested command actually needs DB access and that arguments are
valid; only then call loadAppConfig() and await db.connect({ url: databaseUrl })
for executable DB commands. Move any error/usage reporting for unknown or no-op
commands to run before invoking db.connect so invalid commands never trigger a
database/env connection attempt (apply same change for the other occurrence
around the commands handling near the end of main).

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

cat -n examples/paradedb-demo/src/orm-client/client.ts | head -30

Repository: prisma/prisma-next

Length of output: 741

---

🏁 Script executed:

rg -A 5 -B 5 "db.context" examples/paradedb-demo/src/orm-client/client.ts

Repository: prisma/prisma-next

Length of output: 409

---

🏁 Script executed:

rg -r "ExecutionContext" examples/paradedb-demo/src/orm-client/ -A 2 -B 2

Repository: prisma/prisma-next

Length of output: 44

---

🏁 Script executed:

fd "*.ts" examples/paradedb-demo/src/orm-client/ | xargs cat -n

Repository: prisma/prisma-next

Length of output: 346

---

🏁 Script executed:

rg "db\." examples/paradedb-demo/src/orm-client/client.ts -A 2 -B 2

Repository: prisma/prisma-next

Length of output: 222

---

🏁 Script executed:

fd "contract" examples/paradedb-demo/src/ --type f

Repository: prisma/prisma-next

Length of output: 158

---

🏁 Script executed:

rg "Contract" examples/paradedb-demo/src/orm-client/client.ts -B 5 -A 5

Repository: prisma/prisma-next

Length of output: 553

---

🏁 Script executed:

find examples/paradedb-demo/src/prisma -name "*.ts" -type f

Repository: prisma/prisma-next

Length of output: 150

---

🏁 Script executed:

cat examples/paradedb-demo/src/prisma/db.ts

Repository: prisma/prisma-next

Length of output: 378

---

🏁 Script executed:

rg "context" examples/paradedb-demo/src/prisma/db.ts -B 3 -A 3

Repository: prisma/prisma-next

Length of output: 44

---

🏁 Script executed:

find . -path "*/packages/*postgres*" -name "*.ts" -type f | grep -i "runtime\|index" | head -20

Repository: prisma/prisma-next

Length of output: 742

---

🏁 Script executed:

rg "function postgres" --type ts -B 5 -A 10

Repository: prisma/prisma-next

Length of output: 7939

---

🏁 Script executed:

rg "export.*postgres" packages/sql-runtimes/postgres/src -A 5

Repository: prisma/prisma-next

Length of output: 137

---

🏁 Script executed:

rg "type PostgresClient" packages/3-extensions/postgres/src/runtime/postgres.ts -B 2 -A 5

Repository: prisma/prisma-next

Length of output: 44

---

🏁 Script executed:

rg "interface PostgresClient" packages/3-extensions/postgres/src -B 2 -A 5

Repository: prisma/prisma-next

Length of output: 828

---

🏁 Script executed:

rg "PostgresClient" packages/3-extensions/postgres/src/exports/runtime.ts -B 3 -A 3

Repository: prisma/prisma-next

Length of output: 226

---

🏁 Script executed:

rg "context" packages/3-extensions/postgres/src/runtime/postgres.ts -B 5 -A 5

Repository: prisma/prisma-next

Length of output: 2123

---

Remove unnecessary blind cast to ExecutionContext<Contract>.

The db.context property is already typed as ExecutionContext<Contract> by the PostgresClient<Contract> interface. The cast serves no purpose and should be replaced with an explicit type annotation:

-const context = db.context as ExecutionContext<Contract>;
+const context: ExecutionContext<Contract> = db.context;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	const context = db.context as ExecutionContext<Contract>;
	const context: ExecutionContext<Contract> = db.context;

🤖 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 `@examples/paradedb-demo/src/orm-client/client.ts` at line 8, Remove the
unnecessary type cast on db.context: replace the blind cast "db.context as
ExecutionContext<Contract>" by declaring a properly typed variable (e.g., const
context: ExecutionContext<Contract> = db.context) or simply use db.context
directly, since PostgresClient<Contract> already types db.context as
ExecutionContext<Contract>; update the reference to the symbols context,
db.context, ExecutionContext, Contract, and PostgresClient accordingly.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Make onRow and afterExecute abort-aware too.

Line 96/106 adds cooperative cancellation for beforeExecute, but Line 119 and Line 147 still await middleware hooks directly. That leaves abort responsiveness inconsistent across middleware phases and can stall cancellation until hook completion.

💡 Suggested parity fix

       for await (const row of rowSource as AsyncIterable<Row> | Iterable<Row>) {
         if (source === 'driver') {
           for (const mw of middleware) {
             if (mw.onRow) {
-              await mw.onRow(row as Record<string, unknown>, exec, ctx);
+              checkAborted(ctx, 'onRow');
+              await raceAgainstAbort(
+                Promise.resolve(mw.onRow(row as Record<string, unknown>, exec, ctx)),
+                ctx.signal,
+                'onRow',
+              );
             }
           }
         }
@@
     const latencyMs = Date.now() - startedAt;
     for (const mw of middleware) {
       if (mw.afterExecute) {
-        await mw.afterExecute(exec, { rowCount, latencyMs, completed, source }, ctx);
+        checkAborted(ctx, 'afterExecute');
+        await raceAgainstAbort(
+          Promise.resolve(mw.afterExecute(exec, { rowCount, latencyMs, completed, source }, ctx)),
+          ctx.signal,
+          'afterExecute',
+        );
       }
     }

Also applies to: 117-121, 145-148

🤖 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/1-core/framework-components/src/execution/run-with-middleware.ts`
around lines 95 - 107, The middleware cancellation handling is inconsistent:
only beforeExecute is wrapped with checkAborted and raceAgainstAbort; make onRow
and afterExecute abort-aware the same way. In runWithMiddleware, call
checkAborted(ctx, 'onRow')/checkAborted(ctx, 'afterExecute') before invoking
mw.onRow or mw.afterExecute, and if the hook returns a value or a promise pass
it through raceAgainstAbort(Promise.resolve(...), ctx.signal,
'onRow'/'afterExecute') so these phases are cancelled consistently (use the
existing symbols mw.onRow, mw.afterExecute, raceAgainstAbort, checkAborted,
ctx.signal, and paramsMutator where needed).

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Ensure apply span is always closed when runner throws.

If executeAcrossSpaces() throws, Line 174/184 are skipped and the progress stream gets a dangling apply span.

Suggested fix

-  const runnerResult = await (
-    runner as MultiSpaceCapableRunner<TFamilyId, TTargetId>
-  ).executeAcrossSpaces({ driver, perSpaceOptions });
+  let runnerResult;
+  try {
+    runnerResult = await (
+      runner as MultiSpaceCapableRunner<TFamilyId, TTargetId>
+    ).executeAcrossSpaces({ driver, perSpaceOptions });
+  } catch (error) {
+    onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'error' });
+    throw error;
+  }

🤖 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/src/control-api/operations/apply-aggregate.ts`
around lines 169 - 185, The apply span (APPLY_SPAN_ID) isn't closed if
runner.executeAcrossSpaces throws — wrap the await (runner.executeAcrossSpaces /
executeAcrossSpaces call on the MultiSpaceCapableRunner) in try/catch/finally:
in finally always call onProgress?.({ action, kind: 'spanEnd', spanId:
APPLY_SPAN_ID, outcome: ... }) and set outcome to 'ok' when runnerResult.ok is
true, otherwise 'error'; in the catch convert the thrown error into a notOk
failure (include error.message/summary and any meta like failingSpace if
available) and return it so the function always closes the span before
returning.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

if-missing flow is race-prone and can clobber existing paths.

Current check-then-write is non-atomic: if pkgDir appears between directoryExists() and materialiseMigrationPackage(), the later rm(..., force: true) can delete and rewrite it. Same risk applies to pre-existing non-directory paths. Please switch to an atomic create-first approach (mkdir(pkgDir) and handle EEXIST) so existing paths are never removed in this code path.

Also applies to: 160-167

🤖 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/migration/src/io.ts` around lines 153 - 157,
The current check-then-write flow around directoryExists(pkgDir) +
materialiseMigrationPackage(targetDir, pkg) is race-prone and may clobber
existing paths; change it to an atomic create-first approach by attempting to
create the package directory with mkdir(pkgDir) and treating EEXIST as "already
exists" (return { written: false }) while only proceeding to
materialiseMigrationPackage when mkdir succeeds, and avoid calling rm(...,
force: true) on an existing path; apply the same pattern to the other identical
block that currently performs the directoryExists check (the second instance
that uses pkgDir/targetDir/pkg).

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify generateContractTypes signature matches documentation

# Search for the function implementation
ast-grep --pattern 'generateContractTypes($$$) { $$$ }'

# Also search for the function definition/interface
rg -nP --type=ts -C5 'generateContractTypes\s*[:(]' -g '!**/node_modules/**' -g '!**/*.md'

Repository: prisma/prisma-next

Length of output: 1695

---

🏁 Script executed:

#!/bin/bash
# Search for the hook interface or type definition
rg -nP --type=ts 'generateContractTypes' --max-count=20 -B3 -A3 -g '!**/node_modules/**' -g '!**/*.md' -g '!**/test/**'

Repository: prisma/prisma-next

Length of output: 44

---

🏁 Script executed:

#!/bin/bash
# Search more broadly for generateContractTypes
rg -nP --type=ts 'generateContractTypes' -B5 -A5 | head -100

# Also search for hook interface definitions
rg -nP --type=ts 'interface.*Hook|type.*Hook' packages/2-sql/3-tooling/emitter -B2 -A8

Repository: prisma/prisma-next

Length of output: 3152

---

🏁 Script executed:

#!/bin/bash
# Find generateContractDts implementation
rg -nP 'generateContractDts|function.*generateContractDts' --type=ts -B2 -A10 | head -60

# Search for hook interface definitions in emitter packages
find packages/2-sql/3-tooling/emitter packages/2-mongo-family/3-tooling/emitter -name '*.ts' -type f ! -path '*/node_modules/*' | head -20

Repository: prisma/prisma-next

Length of output: 8379

---

🏁 Script executed:

#!/bin/bash
# Check the emitter package source files
cat packages/2-sql/3-tooling/emitter/src/index.ts | head -100

# Also look for the function signature
rg -nP 'export.*generateContractDts|function generateContractDts|const generateContractDts' packages/2-sql/3-tooling/emitter/src -B2 -A15

Repository: prisma/prisma-next

Length of output: 3963

---

🏁 Script executed:

#!/bin/bash
# Search for generateContractTypes method in SQL emitter
rg -nP 'generateContractTypes' packages/2-sql/3-tooling/emitter/src -B2 -A20

# Also check the total line count of the file
wc -l packages/2-sql/3-tooling/emitter/src/index.ts

Repository: prisma/prisma-next

Length of output: 112

---

🏁 Script executed:

#!/bin/bash
# Search for generateContractTypes and show full context
rg -nP 'generateContractTypes' packages/2-sql/3-tooling/emitter/src/index.ts -B3 -A25

Repository: prisma/prisma-next

Length of output: 44

---

🏁 Script executed:

#!/bin/bash
# Read the README to see the actual documentation
cat packages/2-sql/3-tooling/emitter/README.md | head -100

# Search for the hook interface definition in framework-components
rg -nP 'generateContractTypes|GenerateContractTypes' packages/ -l --type=ts | grep -v node_modules | grep -v test

Repository: prisma/prisma-next

Length of output: 2922

---

🏁 Script executed:

#!/bin/bash
# Check the hook interface definition
cat packages/1-framework/1-core/framework-components/src/control/emission-types.ts | head -150

# Also check the generateContractDts implementation
rg -nP 'generateContractTypes|export.*function.*generateContractDts' packages/1-framework/3-tooling/emitter/src/generate-contract-dts.ts -B3 -A15

Repository: prisma/prisma-next

Length of output: 2424

---

🏁 Script executed:

#!/bin/bash
# Search for the TargetFamilyHook interface that the SQL emitter should implement
rg -nP 'interface.*TargetFamilyHook|type.*TargetFamilyHook' packages/ --type=ts -B2 -A30 | head -80

Repository: prisma/prisma-next

Length of output: 44

---

🏁 Script executed:

#!/bin/bash
# Look at the SQL emitter source to see what interface it claims to implement
grep -n "export.*sqlEmission\|interface\|implements" packages/2-sql/3-tooling/emitter/src/index.ts | head -30

# Check the complete sqlEmission object definition
sed -n '20,150p' packages/2-sql/3-tooling/emitter/src/index.ts

Repository: prisma/prisma-next

Length of output: 4805

---

🏁 Script executed:

#!/bin/bash
# Continue reading the sqlEmission object to find generateContractTypes
sed -n '150,300p' packages/2-sql/3-tooling/emitter/src/index.ts

Repository: prisma/prisma-next

Length of output: 6595

---

🏁 Script executed:

#!/bin/bash
# Continue to see the rest of the sqlEmission object
sed -n '300,380p' packages/2-sql/3-tooling/emitter/src/index.ts

Repository: prisma/prisma-next

Length of output: 2928

---

Rewrite the hook responsibilities to match the actual implementation.

The documented generateContractTypes() method does not exist on the hook interface. The actual hook provides helper methods (generateStorageType(), generateModelStorageType(), getFamilyImports(), getFamilyTypeAliases(), getTypeMapsExpression(), getContractWrapper(), and optionally resolveFieldTypeParams()). The framework's generateContractDts() function orchestrates contract emission by calling these helper methods. The codecTypeImports parameter belongs to the framework function, not a hook method.

🤖 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/2-sql/3-tooling/emitter/README.md` at line 16, Update the README so
the hook responsibilities match the actual implementation: remove the
nonexistent generateContractTypes() entry and instead document the hook helper
methods generateStorageType(), generateModelStorageType(), getFamilyImports(),
getFamilyTypeAliases(), getTypeMapsExpression(), getContractWrapper(), and the
optional resolveFieldTypeParams(); clarify that generateContractDts() (the
framework function) orchestrates contract emission and that the codecTypeImports
parameter belongs to generateContractDts(), not to any hook method.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add the canonical shared-plane export subpath (./adapter).

This package already exposes multi-plane-style subpaths (./control, ./runtime), but it’s missing ./adapter for the shared-plane surface.

Suggested export map adjustment

  "exports": {
+   "./adapter": "./dist/pack.mjs",
    "./column-types": "./dist/column-types.mjs",
    "./control": "./dist/control.mjs",
    "./middleware": "./dist/middleware.mjs",
    "./migration": "./dist/migration.mjs",
    "./operation-types": "./dist/operation-types.mjs",
    "./pack": "./dist/pack.mjs",
    "./runtime": "./dist/runtime.mjs",
    "./package.json": "./package.json"
  },

As per coding guidelines: “Multi-plane entrypoints must use subpath exports: ./control for migration plane, ./runtime for runtime plane, ./adapter for shared plane, mapped in architecture.config.json.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	"exports": {
	"./column-types": "./dist/column-types.mjs",
	"./control": "./dist/control.mjs",
	"./middleware": "./dist/middleware.mjs",
	"./migration": "./dist/migration.mjs",
	"./operation-types": "./dist/operation-types.mjs",
	"./pack": "./dist/pack.mjs",
	"./runtime": "./dist/runtime.mjs",
	"./package.json": "./package.json"
	"exports": {
	"./adapter": "./dist/pack.mjs",
	"./column-types": "./dist/column-types.mjs",
	"./control": "./dist/control.mjs",
	"./middleware": "./dist/middleware.mjs",
	"./migration": "./dist/migration.mjs",
	"./operation-types": "./dist/operation-types.mjs",
	"./pack": "./dist/pack.mjs",
	"./runtime": "./dist/runtime.mjs",
	"./package.json": "./package.json"
	},

🤖 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/3-extensions/cipherstash/package.json` around lines 53 - 61, The
package export map is missing the shared-plane subpath "./adapter"; add an
exports entry for "./adapter" (pointing to the built entry, e.g.
"./dist/adapter.mjs") alongside the existing "./control" and "./runtime" entries
and ensure the built artifact exists, then update architecture.config.json to
include the "./adapter" mapping for the shared-plane surface so it aligns with
the multi-plane entrypoint conventions.

[coderabbitai]

Actionable comments posted: 2

🤖 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 @.agents/skills/record-gotcha/SKILL.md:
- Around line 162-170: Add a language identifier to the fenced code block that
contains the commit message template (the triple-backtick block starting with
the commit template "docs(gotcha): record <one-line title>") to silence
markdownlint; update the opening fence from ``` to ```text so the block is
explicitly marked as plain text.
- Around line 62-64: Replace the three TODO placeholders in the table rows for
Prisma Next, Prisma Compute, and Prisma Postgres with the actual Linear project
keys for their main backlog projects (replace `TODO: confirm main PN project
key`, `TODO: confirm main Compute project key`, and `TODO: confirm main PPg
project key` with the correct keys for the `pn-gotchas`, `compute-gotchas`, and
`ppg-gotchas` projects), ensuring the values match what the "Filing a normal
bug" workflow expects so that the workflow (referenced as "Filing a normal bug")
can use those keys when creating tickets.

🪄 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: ec334591-68e2-4f6a-ac45-7cc1ee3a1b19

📥 Commits

Reviewing files that changed from the base of the PR and between 9edbeef and 0680d6a.

📒 Files selected for processing (1)

• .agents/skills/record-gotcha/SKILL.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Search for Linear issues tracking the TODO resolution

rg -n "TODO.*confirm main.*project key" --type=md

Repository: prisma/prisma-next

Length of output: 44

---

🏁 Script executed:

git ls-files | grep -i "SKILL.md"

Repository: prisma/prisma-next

Length of output: 1022

---

🏁 Script executed:

if [ -f ".agents/skills/record-gotcha/SKILL.md" ]; then
  echo "File exists"
  wc -l ".agents/skills/record-gotcha/SKILL.md"
  echo "---"
  sed -n '60,70p' ".agents/skills/record-gotcha/SKILL.md"
else
  echo "File does not exist"
fi

Repository: prisma/prisma-next

Length of output: 1489

---

🏁 Script executed:

sed -n '170,190p' ".agents/skills/record-gotcha/SKILL.md"

Repository: prisma/prisma-next

Length of output: 1507

---

🏁 Script executed:

rg -n "TODO\|Linear\|project key" ".agents/skills/record-gotcha/SKILL.md" | head -30

Repository: prisma/prisma-next

Length of output: 44

---

Resolve Linear project keys for main backlog column before merge.

The table (lines 62–64) contains three TODO placeholders for main backlog project keys that are directly referenced by the "Filing a normal bug" workflow (line 182). The workflow explicitly instructs to "fill in the TODOs" when filing tickets, so these must be resolved for the skill to be functional.

Confirm and fill in the three project keys for Prisma Next, Compute, and Postgres main backlogs.

🤖 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 @.agents/skills/record-gotcha/SKILL.md around lines 62 - 64, Replace the
three TODO placeholders in the table rows for Prisma Next, Prisma Compute, and
Prisma Postgres with the actual Linear project keys for their main backlog
projects (replace `TODO: confirm main PN project key`, `TODO: confirm main
Compute project key`, and `TODO: confirm main PPg project key` with the correct
keys for the `pn-gotchas`, `compute-gotchas`, and `ppg-gotchas` projects),
ensuring the values match what the "Filing a normal bug" workflow expects so
that the workflow (referenced as "Filing a normal bug") can use those keys when
creating tickets.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language identifier to fenced code block.

The commit message template fenced code block is missing a language identifier, which triggers a markdownlint warning.

📝 Proposed fix

-```
+```text
 docs(gotcha): record <one-line title>
 
 <2–4 line summary: what was surprising, workaround in one sentence,
 ticket id.>
 
 Filed as <TML-XXXX> in <gotchas project name>.

</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>

[warning] 162-162: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

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

In @.agents/skills/record-gotcha/SKILL.md around lines 162 - 170, Add a language
identifier to the fenced code block that contains the commit message template
(the triple-backtick block starting with the commit template "docs(gotcha):
record ") to silence markdownlint; update the opening fence from
totext so the block is explicitly marked as plain text.

</details>

<!-- fingerprinting:phantom:triton:puma -->

<!-- d98c2f50 -->

<!-- This is an auto-generated comment by CodeRabbit -->