## Linked issue
Close-out of #30051 and its QA follow-up #30568, both merged. No Linear
project or ticket, by explicit operator direction.
## At a glance
```text
List ADR 248 → ADR 258 (indexed; ADR 178 examples and explanation updated directly)
Evidence commit → transient project directory removed
```
## Summary
Close nullable scalar lists without losing the failed-QA record or the
rationale for the shipped wire incompatibility. Keep the decisions in
[ADR
258](docs/architecture%20docs/adrs/ADR%20258%20-%20List%20cardinality%20has%20independent%20container%20and%20element%20nullability.md)
and the verification lesson in `drive/retro/README.md`; remove the
completed coordination documents.
## Decision and DoD
All four planned slices shipped together in #30051
(`982bca13644e9d7cdd9702c97a10d9d20482efeb`); #30568
(`84b3bb693c395ec21ccf2de97d5db4787c805d03`) resolves the Mongo
container-null QA failure. Both PRs passed all 27 checks. Paginated
review-thread queries found nine resolved threads on #30051 and no
threads on #30568, with no further pages.
The [immutable acceptance
audit](https://github.com/prisma/orm/blob/d5b794f3ba9e450bd5599a31ed5e925666ae8e6d/projects/nullable-scalar-lists/closeout.md)
maps all nine DoD items: parsing/formatting, family lowering, nested
descriptors, emitted/inferred types, builder parity, PostgreSQL checks
and runtime, Mongo validation/result shapes, and durable documentation.
No feature slice is deferred. The [final
retrospective](https://github.com/prisma/orm/blob/d5b794f3ba9e450bd5599a31ed5e925666ae8e6d/projects/nullable-scalar-lists/retros.md)
is complete.
The four spec decisions now map to ADR 258:
1. Nested cardinality and element semantics, including native SQL
storage versus JSON-backed value objects.
2. Check-based migration comparison: an absent CHECK does **not** imply
nullable elements; inference retains strict types plus `noCheck`.
3. Literal-only `.many({ elementsNullable: true })`, independently
combined with `.optional()`.
4. Value-object domain semantics without treating JSONB as a native
array; scalar lists were the acceptance target.
**Compatibility exception:** strict-list JSON and affected hashes
intentionally change and legacy `many: true` is rejected, while
strict-list PostgreSQL DDL stays unchanged. This operator-authorized
exception does not satisfy or weaken the default historical-artifact
compatibility floor. ADR 258 records historical-state upgrade
obligations and limits. The later Mongo fix is separate: retain applied
history and apply a **new** validator migration, not a production
snapshot rewrite.
## Evidence and classification
The first DCO-signed commit,
[`d5b794f3ba9e450bd5599a31ed5e925666ae8e6d`](https://github.com/prisma/orm/commit/d5b794f3ba9e450bd5599a31ed5e925666ae8e6d),
preserves the [QA
script](https://github.com/prisma/orm/blob/d5b794f3ba9e450bd5599a31ed5e925666ae8e6d/projects/nullable-scalar-lists/manual-qa.md),
[original failed run, scoped successful rerun and final
disposition](https://github.com/prisma/orm/blob/d5b794f3ba9e450bd5599a31ed5e925666ae8e6d/projects/nullable-scalar-lists/manual-qa-run.md),
retro and acceptance audit. The second deletes the directory.
All nine original files are transient: project `spec.md`/`plan.md`;
representation `spec.md`/`plan.md`; SQL-enforcement `spec.md`/`plan.md`;
Mongo `spec.md`/`plan.md`/`status.md`. The five added evidence files are
transient too. No whole-file migration; all decisions are preserved in
the ADR. Ignored review notes and the trace are archived locally outside
the deleted directory. External-reference scanning, including decoded
and resolved relative links, found zero references to repair.
## Testing performed
- `pnpm lint:deps`, `lint:docs`, `lint:skills`, `lint:rules`,
`lint:rules:symlinks`, `lint:rules:footprint`: passed. Docs lint retains
existing missing-Responsibilities warnings.
- Changed-document local file links, renamed-ADR paths, external project
references, final diff scope, DCO trailers and `git diff --check`:
passed.
- Implementation verification comes from the merged PRs, not new
database-suite executions. The preserved scoped real-Mongo rerun accepts
null containers while rejecting strict null elements with code 121; 56
distinct regression cases shipped in the fix. Initial failure and local
environment limitations remain documented.
## Skill update
No new public API or behavior in this docs-only close-out. The durable
verification lesson is added to `drive/retro/README.md`; existing
upgrade instructions are referenced, not rewritten.
## Checklist
- [x] All commits carry DCO sign-off (`git commit -s`).
- [x] CONTRIBUTING.md read; one logical close-out concern.
- [x] Tests: n/a for documentation-only changes; merged implementation
evidence cited.
- [ ] Linear-prefixed title: not applicable; operator explicitly
requested no ticket and a conventional docs/chore title.
- [x] Skill update section completed.
## Notes for the reviewer
No runtime, example, CI, compatibility-shim or production-snapshot
changes. Only the list ADR is renumbered; the unrelated ADR 248 and
duplicated ADR 255 remain untouched. This PR is non-draft; auto-merge is
not enabled. Close-out CI/review remain the normal merge gates.
## Alternatives considered
Retaining the project directory would leave obsolete coordination
material as reference documentation. Silently claiming legacy-artifact
compatibility would contradict the shipped serializers; adding a
compatibility shim or rewriting production history is outside the
authorized decision.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified that nested lists have independently defined container and
item nullability, including the supported nullable and non-nullable
combinations and how they are represented and validated.
* Documented compatibility changes: legacy list declarations are no
longer accepted, and historical snapshots and applied migrations may
require upgrades. The MongoDB container-validator correction has a
separate deployment procedure.
* Updated related architecture guidance and added a retrospective entry
covering verification, CI readiness, and nullability checks.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Signed-off-by: Steven McClankerton <tatarintsev@prisma.io>
Co-authored-by: Steven McClankerton <tatarintsev@prisma.io>
