Public API docblocks still describe emission in Prisma schema-language terms

[borisno2]

The problem

The Prisma 8 build deleted schema-language generation: the generator emits a TypeScript Contract module and Prisma emits contract.json / contract.d.ts from it (ADR-0040). Roughly 51 TSDoc comments across 16 source files still describe what a config option does in terms of the schema language it no longer produces.

The heaviest concentrations:

File	Count
packages/core/src/config/types.ts	17
packages/auth/src/config/types.ts	12
packages/storage/src/utils/multi-column.ts	3
packages/auth/src/config/derive-auth-lists.ts	2
packages/auth/src/server/index.ts	2

Representative examples, all on exported config options:

• ListConfig.db.map — "Adds a @@map attribute to the generated Prisma model. … // Generates: model AuthUser { ... @@map("user") }"
• ListConfig.db.schema — "Adds a @@schema attribute to the generated Prisma model", requiring "the multiSchema preview feature". The contract carries a namespace; there is no preview feature.
• DatabaseConfig.schemas — "the generator enables Prisma's multiSchema preview feature and emits the schemas = [...] array on the datasource block"
• ListConfig.db.indexes — // Generates: @@unique([studentId, productionId])
• OutputConfig — "prisma/schema.prisma and the .opensaas bundle to .opensaas/"

Why it matters more than an ordinary stale comment

The repo's own comment rule makes public API docblocks the deliberate exception to "default to none", precisely because they are what a consumer's editor shows — "that is a contract, not a narration of the implementation beneath it." A reader hovering db.schema today is told to expect an attribute in a file the generator does not write.

It is also the class of defect that surface-diffing cannot catch: the option is real, the name is right, and only the described effect is wrong. Same shape as #1389, which is one instance of it (db.indexes and sort).

What to do

Rewrite the affected docblocks against what the contract actually carries — namespace, table map, column map, unique constraint, index — and drop the // Generates: lines that quote schema-language output, or replace them with the contract shape. Take the code as the truth; packages/core/src/contract/derive.ts is where each option lands.

Needs a changeset (minor, per the integration branch's policy on #1175).

Worth doing as one sweep rather than per option, and worth a mechanical check afterwards — @@map, @@schema, @@unique, @@index, schema.prisma, multiSchema, previewFeatures — scoped to packages/*/src and excluding the migration command, whose job is reading a source project's Prisma schema and which is legitimately out of scope (spec section 15).

Context

• Found while rewriting the agent-guidance files for Agent guidance rewritten and the prisma-8 branch integrated to main #1175 (PR Agent guidance rewritten for the Prisma 8 architecture #1410). The guidance files themselves are clean of this; this is the source side of the same class.
• Public TSDoc on ListIndexFieldRef describes a generate-time 'sort' refusal that does not exist #1389 — the db.indexes / sort TSDoc, one instance
• ADR-0040 — the deletion

---

🤖 Generated with Claude Code

[borisno2]

This was generated by AI during triage.

Confirmed still present on prisma-8: packages/core/src/config/types.ts alone has 24 remaining matches for @@map/@@schema/@@unique/@@index/multiSchema/schema.prisma in TSDoc (e.g. db.map, db.schema, db.indexes, DatabaseConfig.schemas, OutputConfig's output-paths comment), none of which the Prisma 8 pipeline emits.

Setting ready-for-agent: the fix is a mechanical rewrite against packages/core/src/contract/derive.ts's actual behaviour, with a minor changeset already specified in the issue.

---

Generated by Claude Code