Document migration authoring strategy and emit/runner ADRs

[wmadden]

Stack

• PR D (this PR) - docs/ADRs
• PR A - CLI emit unification (depends on this)
• PR B - class-flow scaffolding spine (depends on A)
• PR C - Mongo data transforms (depends on B; is the rebased Add MongoDB data transform operations #349)

Summary

Pure docs. Lands the design context for the migration-authoring redesign:
nine new ADRs, three amended, two subsystem doc rewrites, and the working
specs/plans under projects/mongo-migration-authoring/. No code changes.

This PR is intentionally first in the stack so reviewers of A/B/C can link
to ADRs at their merged path on main.

ADRs

New:

• ADR 192 - ops.json is the migration contract
• ADR 193 - class-flow as the canonical authoring strategy
• ADR 194 - plans carry their own authoring surface
• ADR 195 - planner IR with two renderers (OpFactoryCall pattern)
• ADR 196 - in-process emit for class-flow targets
• ADR 197 - migration packages snapshot their own contract
• ADR 198 - runner decoupled from driver via visitor SPIs
• ADR 199 - storage-only migration identity
• ADR 200 - placeholder() utility for scaffolded migration slots

Amended:

• ADR 027 - registers the PN-MIG-2xxx error code range
• ADR 044 - supersession note for unified check shape
• ADR 188 - data transform addendum

Subsystem docs

• docs/architecture docs/subsystems/7. Migration System.md - adds an Authoring strategies section and generalises the contract-to-schema discussion
• docs/architecture docs/subsystems/10. MongoDB Family.md - corrects stale "no migrations" claims

Project workspace

• projects/mongo-migration-authoring/specs/*.md and plans/*.md - the working specs/plans the implementation PRs reference

Test plan

• Markdown links render on GitHub
• Cross-references between ADRs resolve

Summary by CodeRabbit

• New Features

  • Class-flow TypeScript authoring for MongoDB migrations with in-process emit; ops.json is the authoritative apply-time artifact.
  • New Mongo "data transform" migration operation and scaffold placeholders that surface a clear error when left unfilled.
  • Migration packages now snapshot contract artifacts and use a storage-only migration identity tied to emitted operations.

• Documentation

  • Extensive ADR updates covering planner IR & dual renderers, runner/driver decoupling, three-phase execution, identity/attestation, and migration lifecycle changes.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 0b2a893a-92f6-4746-8852-903dc961a4ce

📥 Commits

Reviewing files that changed from the base of the PR and between 8f37618 and 8a460a7.

⛔ Files ignored due to path filters (1)

• projects/mongo-migration-authoring/specs/data-migrations.spec.md is excluded by !projects/**

📒 Files selected for processing (11)

• docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md
• docs/architecture docs/adrs/ADR 041 - Custom operation loading via local packages + preflight bundles.md
• docs/architecture docs/adrs/ADR 192 - ops.json is the migration contract.md
• docs/architecture docs/adrs/ADR 193 - Class-flow as the canonical migration authoring strategy.md
• docs/architecture docs/adrs/ADR 194 - Plans carry their own authoring surface.md
• docs/architecture docs/adrs/ADR 196 - In-process emit for class-flow targets.md
• docs/architecture docs/adrs/ADR 197 - Migration packages snapshot their own contract.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md
• docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded migration slots.md
• docs/architecture docs/subsystems/10. MongoDB Family.md
• docs/architecture docs/subsystems/7. Migration System.md

---

📝 Walkthrough

Walkthrough

Adds nine ADRs and multiple subsystem updates to make ops.json the authoritative migration contract, specify class-flow authoring and planner IR with dual renderers (ops + TypeScript), define in-process emit and placeholder behavior, snapshot per-migration contracts, decouple the Mongo runner via visitor SPIs, add PN‑MIG error codes, and mark emitted migration artifacts as generated in .gitattributes.

Changes

Cohort / File(s)	Summary
Git attributes \.gitattributes	Treats emitted migration artifacts as generated by adding **/contract.d.ts, **/contract.json, **/ops.json, **/migration.json as linguist-generated.
New ADRs docs/architecture docs/adrs/ADR 192 - ...ops.json is the migration contract.md, .../ADR 193 - Class-flow ...md, .../ADR 194 - Plans carry ...md, .../ADR 195 - Planner IR ...md, .../ADR 196 - In-process emit ...md, .../ADR 197 - Migration packages ...md, .../ADR 198 - Runner decoupled ...md, .../ADR 199 - Storage-only ...md, .../ADR 200 - Placeholder ...md	Adds nine ADRs covering: ops.json as the attested contract; class-flow and in-process emit; MigrationPlan/authoring-surface split; OpFactoryCall IR and two renderers; per-migration contract snapshots; runner dependency decoupling via visitor SPIs; storage-only migration identity hashing; and a placeholder API (PN‑MIG codes).
Mongo operation model docs/architecture docs/adrs/ADR 188 - MongoDB migration operation model.md	Adds MongoDataTransformOperation and MongoDataTransformCheck interfaces and documents data-transform operation semantics, check evaluation, and execution via adapter.lower() → driver.execute().
Updated ADRs & Index docs/architecture docs/adrs/ADR 027.md, .../ADR 028.md, .../ADR 029.md, .../ADR 038.md, .../ADR 040.md, .../ADR 041.md, .../ADR 044.md, .../ADR 116.md, .../ADR 166.md, .../ADR 169.md, docs/architecture docs/ADR-INDEX.md	Rewires references to replace ADR 044 with per-family sources (ADR 028 for SQL, ADR 188 for Mongo), marks ADR 044 as superseded, updates examples and check shapes, and registers PN‑MIG error codes.
Subsystem docs docs/architecture docs/subsystems/7. Migration System.md, .../10. MongoDB Family.md, .../5. Adapters & Targets.md, .../6. Ecosystem Extensions & Packs.md	Updates subsystem narratives to reflect ops.json-centric pipeline, class-flow authoring, planner IR/renderers, runner decoupling, storage-only identity, and Mongo data-transform support.
Conformance & references docs/architecture docs/adrs/ADR 026 - Conformance Kit Certification.md, .../ADR 193.md	Adjusts conformance/reference lists to include ADR 028/188 and remove ADR 044 where applicable.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as CLI (plan/emit/apply)
  participant Planner as Planner (OpFactoryCall[] IR)
  participant RendererOps as Renderer (renderOps)
  participant RendererTS as Renderer (renderTypeScript)
  participant Artifacts as Artifacts (`ops.json` + `migration.json` + `migration.ts`)
  participant Runner as Runner
  participant DB as Database

  CLI->>Planner: run "migration plan"/"emit"
  Planner->>Planner: produce OpFactoryCall[] IR
  Planner->>RendererOps: renderOps(IR)
  RendererOps->>Artifacts: write `ops.json` + attest `migration.json`
  Planner->>RendererTS: renderTypeScript(IR)
  RendererTS->>Artifacts: write `migration.ts` (authoring surface)
  CLI->>Runner: "migration apply"
  Runner->>Artifacts: read `ops.json` + `migration.json`
  Runner->>Runner: verify migrationId attestation
  Runner->>DB: execute precheck → execute → postcheck per operation

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• prisma/prisma-next#212 — Broad migration ADR and documentation alignment; this PR appears to implement the ADR updates discussed there.

Possibly related PRs

• Document migration authoring strategy and emit/runner ADRs #352 — Overlapping PR that introduces the same ADR additions/edits and identical .gitattributes generated-file entries.

Poem

🐇 I sketched IR leaves and two bright streams,
Ops march forward while TypeScript dreams,
A placeholder hops where gaps must start,
Contracts copied close to the heart,
Nine ADRs stitched — a migration art.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title directly and clearly summarizes the main change: adding documentation (ADRs) for migration authoring strategy and emit/runner design decisions.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2219-d-adrs-and-subsystem-docs

---

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

[pkg-pr-new]

Open in StackBlitz

@prisma-next/mongo-runtime

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

@prisma-next/family-mongo

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

@prisma-next/sql-runtime

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

@prisma-next/family-sql

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

@prisma-next/middleware-telemetry

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

@prisma-next/mongo

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

@prisma-next/extension-paradedb

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

@prisma-next/extension-pgvector

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

@prisma-next/postgres

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

@prisma-next/sql-orm-client

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

@prisma-next/sqlite

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

@prisma-next/target-mongo

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

@prisma-next/adapter-mongo

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

@prisma-next/driver-mongo

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

@prisma-next/contract

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

@prisma-next/utils

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

@prisma-next/config

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

@prisma-next/errors

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

@prisma-next/framework-components

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

@prisma-next/operations

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

@prisma-next/contract-authoring

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

@prisma-next/ids

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

@prisma-next/psl-parser

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

@prisma-next/psl-printer

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

@prisma-next/cli

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

@prisma-next/emitter

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

@prisma-next/migration-tools

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

prisma-next

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

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

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

@prisma-next/runtime-executor

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/runtime-executor@352

@prisma-next/mongo-codec

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

@prisma-next/mongo-contract

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

@prisma-next/mongo-value

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

@prisma-next/mongo-contract-psl

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

@prisma-next/mongo-contract-ts

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

@prisma-next/mongo-emitter

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

@prisma-next/mongo-schema-ir

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

@prisma-next/mongo-query-ast

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

@prisma-next/mongo-orm

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

@prisma-next/mongo-pipeline-builder

npm i https://pkg.pr.new/prisma/prisma-next/@prisma-next/mongo-pipeline-builder@352

@prisma-next/mongo-lowering

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

@prisma-next/mongo-wire

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

@prisma-next/sql-contract

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

@prisma-next/sql-errors

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

@prisma-next/sql-operations

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

@prisma-next/sql-schema-ir

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

@prisma-next/sql-contract-psl

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

@prisma-next/sql-contract-ts

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

@prisma-next/sql-contract-emitter

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

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

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

@prisma-next/sql-relational-core

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

@prisma-next/sql-builder

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

@prisma-next/target-postgres

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

@prisma-next/target-sqlite

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

@prisma-next/adapter-postgres

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

@prisma-next/adapter-sqlite

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

@prisma-next/driver-postgres

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

@prisma-next/driver-sqlite

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

commit: 8a460a7

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (3)

docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md (1)

17-35: Move implementation algorithm details out of the ADR body.

This block is effectively production-level implementation logic. For ADRs in this repo, please keep the decision and constraints, and move exact algorithm/code mechanics to subsystem docs or implementation docs.

Based on learnings: "ADRs in prisma/prisma-next should document architectural design decisions and the key constraints/assumptions only. Do not include implementation algorithms, emitter derivation logic, or step-by-step derivation/migration rules."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 199 - Storage-only migration identity.md
around lines 17 - 35, This ADR currently contains production-level algorithm
code (computeMigrationId, canonicalizeJson, sha256Hex, MigrationManifest,
MigrationOps) that should be removed from the ADR body and moved to
implementation/subsystem docs; replace the code block with a short, high-level
description of the migration identity decision (e.g., "migration identity is
computed deterministically from a manifest and ops using a canonicalized SHA-256
hash") plus any constraints/assumptions, and create a separate implementation
doc that contains the exact algorithm, function signature (computeMigrationId),
and details about canonicalization and hashing.

docs/architecture docs/subsystems/7. Migration System.md (2)

77-84: Use ASCII in Mermaid node labels.

The empty set symbol ∅ in the node label violates the coding guideline to prefer ASCII.

As per coding guidelines: "Prefer ASCII in Mermaid node labels (avoid curly quotes, arrows like →, ellipses like …, and emoji prefixes)."

♻️ Proposed fix for ASCII compliance

 ```mermaid
 flowchart LR
-  Empty["∅"] -- e1 --> H1
+  Empty[Empty] -- e1 --> H1
   H1 -- e2 --> H2

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/subsystems/7. Migration System.md around lines 77 -
84, The Mermaid diagram uses a non-ASCII empty-set symbol in the node label
Empty["∅"]; update the node label to use ASCII (e.g., Empty[Empty] or
Empty["Empty"]) so it follows the guideline. Edit the flowchart block containing
nodes Empty, H1, H2, H2a, H3 and replace the label "∅" with an ASCII word; keep
the node identifier (Empty) and the edge tokens (-- e1 --> etc.) unchanged.

---

16-19: Use ASCII in Mermaid node labels.

The empty set symbol ∅ in Mermaid node labels violates the coding guideline to prefer ASCII. Replace with "Empty" or just use the node ID without a label override.

As per coding guidelines: "Prefer ASCII in Mermaid node labels (avoid curly quotes, arrows like →, ellipses like …, and emoji prefixes)."

♻️ Proposed fix for ASCII compliance

 ```mermaid
 flowchart LR
-  E["∅"] -- "e1:createCollection(users)" --> H1[H1]
+  E[Empty] -- "e1:createCollection(users)" --> H1[H1]

</details>

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

Verify each finding against the current code and only fix it if needed.

In @docs/architecture docs/subsystems/7. Migration System.md around lines 16 -
19, Replace the non-ASCII empty set symbol in the Mermaid node label for node E
with an ASCII alternative; locate the flowchart line containing node identifier
E and the edge labeled "e1:createCollection(users)" and change the node label
from "∅" to an ASCII label such as Empty (or remove the quoted label override to
use the node ID E) so the Mermaid diagram complies with the ASCII-label
guideline.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md:

• Around line 128-130: The ADR text and the implementation disagree: update
  either the ADR or the code so the contract is unambiguous—either change ADR 027
  entries for PN-MIG-2003 and PN-MIG-2004 to state that evaluateMigrationTs
  expects the default export to be a function and that invoking it returns an
  array (matching evaluateMigrationTs in migration-ts.ts), or change
  evaluateMigrationTs to implement ADR 194’s contract (require the default export
  be a Migration subclass and that Migration.operations getter returns an array);
  reference evaluateMigrationTs, PN-MIG-2003, PN-MIG-2004 and ADR 194 when making
  the change so the wording and validation align.

In @docs/architecture docs/adrs/ADR 192 - ops.json is the migration contract.md:

• Around line 23-24: The wording for migrationId is ambiguous; update the
  sentence that currently says "computed over the manifest and ops.json" to
  explicitly state it is computed over the "stripped manifest metadata +
  ops.json" per ADR 199 (so readers know fields like fromContract,
  toContract, and hints are not included), and add a short parenthetical or
  clause referencing ADR 199 and the stripped-manifest rule; ensure this
  clarification appears near the mention of migrationId/migration.json and
  note that edits to migration.ts that don't change emitted ops won't affect the
  id.

In @docs/architecture docs/adrs/ADR 197 - Migration packages snapshot their own
contract.md:

• Around line 7-14: Add the missing fence language specifier "text" to the two
  Markdown fenced code blocks that show directory trees so they no longer trigger
  MD040: update the block beginning with the
  migrations/20250612T0930_backfill-status/ tree to start with text and likewise update the block beginning with the migrations/20250613T1100_split-name/ tree to start with text; ensure both
  opening fences include the language identifier and leave the tree contents
  unchanged.

In @docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md:

• Line 74: The plain text reference "ADR 192 — ops.json is the migration
  contract (concurrent)" should be converted to the same clickable link format
  used elsewhere; replace that exact string with a Markdown link pointing to ADR
  192 (e.g., ADR 192 — ops.json is the migration contract (concurrent)) so
  cross-reference checks resolve and the reference style matches adjacent ADR
  links.

In @docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded
migration slots.md:

• Around line 21-25: The fenced code block containing the PN-MIG-2001
  placeholder message is missing a language tag (MD040); update the opening fence
  in "ADR 200 - Placeholder utility for scaffolded migration slots.md" for that
  block (the block that starts with "PN-MIG-2001 Unfilled migration placeholder")
  by adding a language identifier such as text (e.g., change totext) so
  the linter no longer flags the missing fence language.

---

Nitpick comments:
In @docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md:

• Around line 17-35: This ADR currently contains production-level algorithm code
  (computeMigrationId, canonicalizeJson, sha256Hex, MigrationManifest,
  MigrationOps) that should be removed from the ADR body and moved to
  implementation/subsystem docs; replace the code block with a short, high-level
  description of the migration identity decision (e.g., "migration identity is
  computed deterministically from a manifest and ops using a canonicalized SHA-256
  hash") plus any constraints/assumptions, and create a separate implementation
  doc that contains the exact algorithm, function signature (computeMigrationId),
  and details about canonicalization and hashing.

In @docs/architecture docs/subsystems/7. Migration System.md:

• Around line 77-84: The Mermaid diagram uses a non-ASCII empty-set symbol in
  the node label Empty["∅"]; update the node label to use ASCII (e.g.,
  Empty[Empty] or Empty["Empty"]) so it follows the guideline. Edit the flowchart
  block containing nodes Empty, H1, H2, H2a, H3 and replace the label "∅" with an
  ASCII word; keep the node identifier (Empty) and the edge tokens (-- e1 -->
  etc.) unchanged.
• Around line 16-19: Replace the non-ASCII empty set symbol in the Mermaid node
  label for node E with an ASCII alternative; locate the flowchart line containing
  node identifier E and the edge labeled "e1:createCollection(users)" and change
  the node label from "∅" to an ASCII label such as Empty (or remove the quoted
  label override to use the node ID E) so the Mermaid diagram complies with the
  ASCII-label guideline.

</details>

<details>
<summary>🪄 Autofix (Beta)</summary>

Fix all unresolved CodeRabbit comments on this PR:

- [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended)
- [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Path: .coderabbit.yml

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `b8329017-c1f9-48a9-ba81-72ae6c336bf0`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 9ae33cf4e9d537c1437c5e6621934a6c7f9e4cd3 and 122903f79878894daa2e44371f30ca0f8b509408.

</details>

<details>
<summary>⛔ Files ignored due to path filters (9)</summary>

* `projects/mongo-migration-authoring/plans/data-migrations-plan.md` is excluded by `!projects/**`
* `projects/mongo-migration-authoring/specs/class-flow-scaffolding.md` is excluded by `!projects/**`
* `projects/mongo-migration-authoring/specs/data-migrations.spec.md` is excluded by `!projects/**`
* `projects/mongo-migration-authoring/specs/data-transform-check-unification.md` is excluded by `!projects/**`
* `projects/mongo-migration-authoring/specs/data-transform-placeholder.md` is excluded by `!projects/**`
* `projects/mongo-migration-authoring/specs/migration-emit-unification.md` is excluded by `!projects/**`
* `projects/mongo-migration-authoring/specs/migration-package-polish.md` is excluded by `!projects/**`
* `projects/mongo-migration-authoring/specs/planner-dual-output.spec.md` is excluded by `!projects/**`
* `projects/mongo-migration-authoring/specs/target-owned-migration-scaffolding.md` is excluded by `!projects/**`

</details>

<details>
<summary>📒 Files selected for processing (15)</summary>

* `.gitattributes`
* `docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md`
* `docs/architecture docs/adrs/ADR 044 - Pre & post check vocabulary v1.md`
* `docs/architecture docs/adrs/ADR 188 - MongoDB migration operation model.md`
* `docs/architecture docs/adrs/ADR 192 - ops.json is the migration contract.md`
* `docs/architecture docs/adrs/ADR 193 - Class-flow as the canonical migration authoring strategy.md`
* `docs/architecture docs/adrs/ADR 194 - Plans carry their own authoring surface.md`
* `docs/architecture docs/adrs/ADR 195 - Planner IR with two renderers.md`
* `docs/architecture docs/adrs/ADR 196 - In-process emit for class-flow targets.md`
* `docs/architecture docs/adrs/ADR 197 - Migration packages snapshot their own contract.md`
* `docs/architecture docs/adrs/ADR 198 - Runner decoupled from driver via visitor SPIs.md`
* `docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md`
* `docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded migration slots.md`
* `docs/architecture docs/subsystems/10. MongoDB Family.md`
* `docs/architecture docs/subsystems/7. Migration System.md`

</details>

</details>

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

[coderabbitai]

Actionable comments posted: 4

♻️ Duplicate comments (1)

docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded migration slots.md (1)

21-25: ⚠️ Potential issue | 🟡 Minor

Add a language tag to the fenced code block.

Line 21 should specify a fence language (e.g., text) to satisfy MD040.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 200 - Placeholder utility for scaffolded
migration slots.md around lines 21 - 25, The fenced code block that shows the
migration message (the block starting with "PN-MIG-2001  Unfilled migration
placeholder" and the placeholder instruction) is missing a language tag; add a
fence language such as ```text (e.g., change ``` to ```text) to satisfy MD040
and ensure the block is treated as plain text by the linter.

🧹 Nitpick comments (3)

docs/architecture docs/adrs/ADR 198 - Runner decoupled from driver via visitor SPIs.md (1)

50-61: Condense execution mechanics to decision-level text.

Line 50–61 documents stepwise execution internals (visitor dispatch and adapter/driver flow) at implementation granularity. Recommend keeping only constraints and invariants here, with a link to subsystem docs for execution mechanics.

Based on learnings: "ADRs in prisma/prisma-next should document architectural design decisions and the key constraints/assumptions only. Do not include implementation algorithms, emitter derivation logic, or step-by-step derivation/migration rules."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 198 - Runner decoupled from driver via
visitor SPIs.md around lines 50 - 61, The ADR currently exposes
implementation-level execution steps (visitor dispatch, concrete executors and
driver calls like CreateIndexCommand/DropIndexCommand/CreateCollectionCommand
using accept(visitor), MongoCommandExecutor, MongoInspectionExecutor,
adapter.lower(plan) and driver.execute(wireCommand)), so condense this section
to state only the high-level decision, key constraints and invariants (e.g.,
"DDL uses frozen AST nodes dispatched via a visitor SPI; runner is decoupled
from driver; DML uses adapter→driver transport"), remove the step-by-step
mechanics and concrete method calls, and replace them with a short pointer
sentence linking to the subsystem implementation/design docs that contain the
detailed execution mechanics and examples (retain the command/type names as
keywords for cross-reference).

docs/architecture docs/adrs/ADR 195 - Planner IR with two renderers.md (1)

75-122: Move renderer algorithm walkthroughs out of the ADR.

Line 75–122 goes deep into implementation mechanics (renderVisitor, file composition details). For ADRs, keep the decision/constraints and move algorithm-level guidance to subsystem docs to reduce ADR churn.

Based on learnings: "ADRs in prisma/prisma-next should document architectural design decisions and the key constraints/assumptions only. Do not include implementation algorithms, emitter derivation logic, or step-by-step derivation/migration rules."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 195 - Planner IR with two renderers.md
around lines 75 - 122, The ADR includes algorithm-level implementation details
(examples and walkthroughs for renderVisitor, renderCallVisitor, renderOps,
renderCallsToTypeScript and file-composition mechanics) that should be removed
from the ADR body; replace that section with a brief decision summary stating
that rendering is external to IR nodes and reference the subsystem docs for
implementation (e.g., a note to see the renderer docs for visitor examples and
the TypeScript emitter), and move the detailed examples and step‑by‑step
algorithms (including the sketch of PlannerProducedMongoMigration wiring and
Migration file composition) into the renderer/subsystem documentation.

docs/architecture docs/adrs/ADR 197 - Migration packages snapshot their own contract.md (1)

25-25: Consider more concise phrasing (optional).

For brevity, "at the moment the migration was scaffolded" could be shortened to "when the migration was scaffolded."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 197 - Migration packages snapshot their own
contract.md at line 25, Replace the phrase "at the moment the migration was
scaffolded" with the more concise "when the migration was scaffolded" in the
sentence describing `contract.json` and `contract.d.ts` snapshots so the line
reads: "`contract.json` and `contract.d.ts` are copies — snapshots of the
project's emitted contract when the migration was scaffolded. The migration
never reaches outside its own directory for type information."

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/architecture` docs/subsystems/7. Migration System.md:
- Around line 232-235: Update the docs to match the implemented migrationId
formula: state that canonicalized fromContract and toContract are included in
the hash (they appear in partHashes in
packages/1-framework/3-tooling/migration/src/attestation.ts) rather than
excluded; describe that migrationId is computed from strippedManifest + ops plus
the canonicalized fromContract/toContract (and hints if present) as represented
by partHashes so the doc's description of strippedManifest and the inputs to the
hash align with the attestation implementation.
- Around line 307-321: The CLI command list in "7. Migration System.md" is out
of sync: add an entry for the existing migration verify command or mark it as
deprecated/transitioning; locate the command implementation in
packages/1-framework/3-tooling/cli/src/commands/migration-verify.ts and either
(A) add a line to the Helpful Commands block like "`prisma-next migration verify
[--db <url>] [--ref <name>]` — <short description>`" describing its behavior,
options and status, or (B) add a short parenthetical after the list noting that
`migration verify` is deprecated/transitionary and link to the canonical docs;
ensure the README follows the doc-maintenance.mdc guideline by preferring a link
to the canonical CLI docs if the command surface changes frequently.
- Line 18: Replace the non-ASCII Mermaid node labels `∅` used in the diagram
(e.g., the node declaration E["∅"] and the other occurrence at line 79) with an
ASCII-only label such as `Empty` (e.g., E["Empty"]) so the Mermaid diagrams
follow repo conventions; update both occurrences (the E node and the matching
node on line 79) ensuring any references like the edge E["∅"] --
"e1:createCollection(users)" are updated to use the new ASCII label.
- Around line 23-31: The markdown fenced code blocks that show the migration
directory listing (the block starting with "migrations/ 
20260118T1205_add_users/" and the later block around lines 198-213) are missing
language tags; update both opening fences from ``` to ```text so they satisfy
MD040 (e.g., change the block that contains "migration.ts / migration.json /
ops.json / contract.json / contract.d.ts" to start with ```text and do the same
for the other fenced block).

---

Duplicate comments:
In `@docs/architecture` docs/adrs/ADR 200 - Placeholder utility for scaffolded
migration slots.md:
- Around line 21-25: The fenced code block that shows the migration message (the
block starting with "PN-MIG-2001  Unfilled migration placeholder" and the
placeholder instruction) is missing a language tag; add a fence language such as
```text (e.g., change ``` to ```text) to satisfy MD040 and ensure the block is
treated as plain text by the linter.

---

Nitpick comments:
In `@docs/architecture` docs/adrs/ADR 195 - Planner IR with two renderers.md:
- Around line 75-122: The ADR includes algorithm-level implementation details
(examples and walkthroughs for renderVisitor, renderCallVisitor, renderOps,
renderCallsToTypeScript and file-composition mechanics) that should be removed
from the ADR body; replace that section with a brief decision summary stating
that rendering is external to IR nodes and reference the subsystem docs for
implementation (e.g., a note to see the renderer docs for visitor examples and
the TypeScript emitter), and move the detailed examples and step‑by‑step
algorithms (including the sketch of PlannerProducedMongoMigration wiring and
Migration file composition) into the renderer/subsystem documentation.

In `@docs/architecture` docs/adrs/ADR 197 - Migration packages snapshot their own
contract.md:
- Line 25: Replace the phrase "at the moment the migration was scaffolded" with
the more concise "when the migration was scaffolded" in the sentence describing
`contract.json` and `contract.d.ts` snapshots so the line reads:
"`contract.json` and `contract.d.ts` are copies — snapshots of the project's
emitted contract when the migration was scaffolded. The migration never reaches
outside its own directory for type information."

In `@docs/architecture` docs/adrs/ADR 198 - Runner decoupled from driver via
visitor SPIs.md:
- Around line 50-61: The ADR currently exposes implementation-level execution
steps (visitor dispatch, concrete executors and driver calls like
CreateIndexCommand/DropIndexCommand/CreateCollectionCommand using
accept(visitor), MongoCommandExecutor, MongoInspectionExecutor,
adapter.lower(plan) and driver.execute(wireCommand)), so condense this section
to state only the high-level decision, key constraints and invariants (e.g.,
"DDL uses frozen AST nodes dispatched via a visitor SPI; runner is decoupled
from driver; DML uses adapter→driver transport"), remove the step-by-step
mechanics and concrete method calls, and replace them with a short pointer
sentence linking to the subsystem implementation/design docs that contain the
detailed execution mechanics and examples (retain the command/type names as
keywords for cross-reference).

🪄 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: ea6e9b8d-f160-4eae-a06c-e02877020e8d

📥 Commits

Reviewing files that changed from the base of the PR and between 122903f and 4be4a19.

⛔ Files ignored due to path filters (9)

• projects/mongo-migration-authoring/plans/data-migrations-plan.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/class-flow-scaffolding.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/data-migrations.spec.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/data-transform-check-unification.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/data-transform-placeholder.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/migration-emit-unification.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/migration-package-polish.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/planner-dual-output.spec.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/target-owned-migration-scaffolding.md is excluded by !projects/**

📒 Files selected for processing (15)

• .gitattributes
• docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md
• docs/architecture docs/adrs/ADR 044 - Pre & post check vocabulary v1.md
• docs/architecture docs/adrs/ADR 188 - MongoDB migration operation model.md
• docs/architecture docs/adrs/ADR 192 - ops.json is the migration contract.md
• docs/architecture docs/adrs/ADR 193 - Class-flow as the canonical migration authoring strategy.md
• docs/architecture docs/adrs/ADR 194 - Plans carry their own authoring surface.md
• docs/architecture docs/adrs/ADR 195 - Planner IR with two renderers.md
• docs/architecture docs/adrs/ADR 196 - In-process emit for class-flow targets.md
• docs/architecture docs/adrs/ADR 197 - Migration packages snapshot their own contract.md
• docs/architecture docs/adrs/ADR 198 - Runner decoupled from driver via visitor SPIs.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md
• docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded migration slots.md
• docs/architecture docs/subsystems/10. MongoDB Family.md
• docs/architecture docs/subsystems/7. Migration System.md

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

• .gitattributes
• docs/architecture docs/adrs/ADR 044 - Pre & post check vocabulary v1.md
• docs/architecture docs/subsystems/10. MongoDB Family.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md
• docs/architecture docs/adrs/ADR 192 - ops.json is the migration contract.md
• docs/architecture docs/adrs/ADR 193 - Class-flow as the canonical migration authoring strategy.md

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

• docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md
• docs/architecture docs/adrs/ADR 194 - Plans carry their own authoring surface.md
• docs/architecture docs/adrs/ADR 196 - In-process emit for class-flow targets.md
• docs/architecture docs/adrs/ADR 188 - MongoDB migration operation model.md

[coderabbitai]

Actionable comments posted: 2

♻️ Duplicate comments (6)

docs/architecture docs/subsystems/7. Migration System.md (4)

18-18: ⚠️ Potential issue | 🟡 Minor

Use ASCII Mermaid node labels.

∅ in Mermaid labels violates the repo Mermaid guidance; switch to an ASCII label like Empty.

As per coding guidelines: "**/*.md: Prefer ASCII in Mermaid node labels (avoid curly quotes, arrows like →, ellipses like …, and emoji prefixes)`."

Also applies to: 79-79

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/subsystems/7. Migration System.md at line 18, Replace
the non-ASCII Mermaid node label E["∅"] with an ASCII label (e.g., E["Empty"])
to comply with the repo guidance; update any identical occurrences (the other
instance noted in the file) so all Mermaid node labels use plain ASCII (use the
existing node identifier E and the edge label e1:createCollection(users) to
locate the spot to change).

---

307-321: ⚠️ Potential issue | 🟠 Major

Command synopsis is missing the existing migration verify command.

The current command list omits migration verify even though it exists in the CLI command set. Please include it or explicitly mark deprecation/transition status with a canonical reference.

As per coding guidelines: "**/*.{md,ts,tsx}: Keep docs current (READMEs, rules, links) and prefer links to canonical docs over long comments (see doc-maintenance.mdc rule)`."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/subsystems/7. Migration System.md around lines 307 -
321, Add the missing CLI entry for the existing migration verify command to the
command synopsis: insert a line for "prisma-next migration verify [--db <url>]
[--ref <name>]" (or the correct flags your CLI supports) into the Helpful
Commands list (near other migration subcommands like migration
apply/status/show) or else add a short note declaring it
deprecated/transitioning with a canonical doc link; ensure the phrasing matches
the existing entries and references "migration verify" exactly so readers can
find it.

---

232-235: ⚠️ Potential issue | 🟠 Major

Migration ID hash inputs are documented inconsistently with current implementation.

This section says canonicalized fromContract/toContract/hints are excluded from hashing; previous implementation references indicate these are included in partHashes. Please align this text with actual attestation logic (or clearly mark it as future behavior gated on follow-up PRs).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/subsystems/7. Migration System.md around lines 232 -
235, The documentation for migrationId is inconsistent with the implementation:
update the paragraph describing migrationId computation to match the attestation
logic by stating whether canonicalized fromContract, toContract, and hints are
included via partHashes (i.e., partHashes are part of the input to migrationId)
or explicitly mark this behavior as a future gated change; reference the symbols
migrationId, strippedManifest, fromContract, toContract, hints, and partHashes
and describe that the canonicalized contracts/hints are either included in the
hash through partHashes or that the current implementation excludes them and the
doc should note that mismatch and the intended follow-up PR.

---

23-31: ⚠️ Potential issue | 🟡 Minor

Add language identifiers to both migration-layout fenced blocks.

Both directory-tree blocks should use an explicit fence language (use text) to satisfy MD040.

Also applies to: 198-213

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/subsystems/7. Migration System.md around lines 23 -
31, The fenced directory-tree blocks (the ones beginning with "migrations/" and
the other similar migration-layout block later) are missing a language
identifier and trigger MD040; update both fenced code blocks to use an explicit
language tag by changing their opening fences from ``` to ```text so the
directory-tree snippets (the block containing "migrations/ 
20260118T1205_add_users/ ...") and the duplicate block further down (the other
migration-layout block) are fenced as ```text.

docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded migration slots.md (1)

21-25: ⚠️ Potential issue | 🟡 Minor

Add a language tag to the PN-MIG error example block.

This fenced block still lacks a language identifier (MD040). Use text.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 200 - Placeholder utility for scaffolded
migration slots.md around lines 21 - 25, The fenced example block showing the
PN-MIG-2001 Unfilled migration placeholder needs a language tag to satisfy
MD040; edit the markdown file and change the triple-backtick fence that wraps
the PN-MIG-2001 example to use the "text" language identifier (i.e., ```text) so
the code block is properly annotated; locate the block containing "PN-MIG-2001 
Unfilled migration placeholder" and the reference to the `placeholder(...)` call
when making the change.

docs/architecture docs/adrs/ADR 197 - Migration packages snapshot their own contract.md (1)

7-14: ⚠️ Potential issue | 🟡 Minor

Add language identifiers to both directory-tree fenced blocks.

Both tree blocks are still missing a fence language (MD040). Please use text for these two blocks.

As per coding guidelines: "**/*.md: Prefer ASCII in Mermaid node labels ... Keep Mermaid diagram labels short ...`" and markdown hygiene requirements for docs in this repo include proper fenced block annotations.

Also applies to: 69-79

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 197 - Migration packages snapshot their own
contract.md around lines 7 - 14, The two directory-tree fenced code blocks that
show the migration layout (the block containing lines like
"migrations/20250612T0930_backfill-status/" and the list including
"migration.ts", "migration.json", "ops.json", "contract.json", "contract.d.ts")
are missing a fence language and should be annotated with text; update each
triple-backtick fence that surrounds those tree blocks to be ```text so the
blocks pass MD040 and follow the repo's markdown hygiene rules.

🧹 Nitpick comments (1)

docs/architecture docs/adrs/ADR 195 - Planner IR with two renderers.md (1)

75-122: Trim implementation-level renderer walkthrough from ADR body.

This ADR currently reads partly like implementation design notes (visitor bodies, file composition mechanics, reverse-engineering specifics). Consider keeping the decision, invariants, and trade-offs here, and move derivation mechanics to the Migration System subsystem doc.

Based on learnings: "ADRs in prisma/prisma-next should document architectural design decisions and the key constraints/assumptions only. Do not include implementation algorithms, emitter derivation logic, or step-by-step derivation/migration rules."

Also applies to: 137-157

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 195 - Planner IR with two renderers.md
around lines 75 - 122, The ADR includes implementation-level renderer
walkthroughs that read like design notes; remove or relocate the detailed
visitor and file-composition examples (renderVisitor, renderOps,
renderCallVisitor, renderCallsToTypeScript, and the wiring notes around
PlannerProducedMongoMigration and renderTypeScript) from the ADR body and
instead summarize the architectural decision and constraints (what rendering
responsibility is, why it is external to IR nodes, and trade-offs), then move
the detailed emitter/derivation mechanics and example snippets into the
Migration System subsystem doc or an implementation appendix.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/architecture` docs/adrs/ADR 197 - Migration packages snapshot their own
contract.md:
- Around line 31-49: This section currently presents the
copyContractToMigrationDir behavior as if implemented; update the ADR text to
explicitly mark it as target/planned behavior until the implementation PR lands
by adding a clear sentence like "Planned/target-state: the
copyContractToMigrationDir helper (see copyContractToMigrationDir) will perform
a snapshot copy of contract.json and optional contract.d.ts into the migration
package; current scaffolding in migration-ts.ts still derives imports from
contractJsonPath." Also mention that migration-ts.ts
(packages/1-framework/3-tooling/migration/src/migration-ts.ts) remains unchanged
today so readers know this is not yet present in main.

In `@docs/architecture` docs/adrs/ADR 200 - Placeholder utility for scaffolded
migration slots.md:
- Around line 55-70: Update this ADR section to indicate the
sentinel-to-placeholder() change is the intended/target design (not yet live) by
marking the replacement as "planned/target behavior" or "design intent" until
runtime snippets and code paths are migrated; explicitly note that
examples/snippets referencing TODO/TodoMarker/TO DO symbol in runtime (e.g., the
dataTransform runtime handling) are still present in the repo and will be
replaced when implementation lands, and add a short migration status line that
references the placeholder() symbol as the future API and TODO/TodoMarker as the
current temporary runtime artifact.

---

Duplicate comments:
In `@docs/architecture` docs/adrs/ADR 197 - Migration packages snapshot their own
contract.md:
- Around line 7-14: The two directory-tree fenced code blocks that show the
migration layout (the block containing lines like
"migrations/20250612T0930_backfill-status/" and the list including
"migration.ts", "migration.json", "ops.json", "contract.json", "contract.d.ts")
are missing a fence language and should be annotated with text; update each
triple-backtick fence that surrounds those tree blocks to be ```text so the
blocks pass MD040 and follow the repo's markdown hygiene rules.

In `@docs/architecture` docs/adrs/ADR 200 - Placeholder utility for scaffolded
migration slots.md:
- Around line 21-25: The fenced example block showing the PN-MIG-2001 Unfilled
migration placeholder needs a language tag to satisfy MD040; edit the markdown
file and change the triple-backtick fence that wraps the PN-MIG-2001 example to
use the "text" language identifier (i.e., ```text) so the code block is properly
annotated; locate the block containing "PN-MIG-2001  Unfilled migration
placeholder" and the reference to the `placeholder(...)` call when making the
change.

In `@docs/architecture` docs/subsystems/7. Migration System.md:
- Line 18: Replace the non-ASCII Mermaid node label E["∅"] with an ASCII label
(e.g., E["Empty"]) to comply with the repo guidance; update any identical
occurrences (the other instance noted in the file) so all Mermaid node labels
use plain ASCII (use the existing node identifier E and the edge label
e1:createCollection(users) to locate the spot to change).
- Around line 307-321: Add the missing CLI entry for the existing migration
verify command to the command synopsis: insert a line for "prisma-next migration
verify [--db <url>] [--ref <name>]" (or the correct flags your CLI supports)
into the Helpful Commands list (near other migration subcommands like migration
apply/status/show) or else add a short note declaring it
deprecated/transitioning with a canonical doc link; ensure the phrasing matches
the existing entries and references "migration verify" exactly so readers can
find it.
- Around line 232-235: The documentation for migrationId is inconsistent with
the implementation: update the paragraph describing migrationId computation to
match the attestation logic by stating whether canonicalized fromContract,
toContract, and hints are included via partHashes (i.e., partHashes are part of
the input to migrationId) or explicitly mark this behavior as a future gated
change; reference the symbols migrationId, strippedManifest, fromContract,
toContract, hints, and partHashes and describe that the canonicalized
contracts/hints are either included in the hash through partHashes or that the
current implementation excludes them and the doc should note that mismatch and
the intended follow-up PR.
- Around line 23-31: The fenced directory-tree blocks (the ones beginning with
"migrations/" and the other similar migration-layout block later) are missing a
language identifier and trigger MD040; update both fenced code blocks to use an
explicit language tag by changing their opening fences from ``` to ```text so
the directory-tree snippets (the block containing "migrations/ 
20260118T1205_add_users/ ...") and the duplicate block further down (the other
migration-layout block) are fenced as ```text.

---

Nitpick comments:
In `@docs/architecture` docs/adrs/ADR 195 - Planner IR with two renderers.md:
- Around line 75-122: The ADR includes implementation-level renderer
walkthroughs that read like design notes; remove or relocate the detailed
visitor and file-composition examples (renderVisitor, renderOps,
renderCallVisitor, renderCallsToTypeScript, and the wiring notes around
PlannerProducedMongoMigration and renderTypeScript) from the ADR body and
instead summarize the architectural decision and constraints (what rendering
responsibility is, why it is external to IR nodes, and trade-offs), then move
the detailed emitter/derivation mechanics and example snippets into the
Migration System subsystem doc or an implementation appendix.

🪄 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: d140c0ec-2141-46e8-bc88-1ab0b92acd9e

📥 Commits

Reviewing files that changed from the base of the PR and between 4be4a19 and 7482e70.

⛔ Files ignored due to path filters (9)

• projects/mongo-migration-authoring/plans/data-migrations-plan.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/class-flow-scaffolding.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/data-migrations.spec.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/data-transform-check-unification.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/data-transform-placeholder.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/migration-emit-unification.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/migration-package-polish.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/planner-dual-output.spec.md is excluded by !projects/**
• projects/mongo-migration-authoring/specs/target-owned-migration-scaffolding.md is excluded by !projects/**

📒 Files selected for processing (15)

• .gitattributes
• docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md
• docs/architecture docs/adrs/ADR 044 - Pre & post check vocabulary v1.md
• docs/architecture docs/adrs/ADR 188 - MongoDB migration operation model.md
• docs/architecture docs/adrs/ADR 192 - ops.json is the migration contract.md
• docs/architecture docs/adrs/ADR 193 - Class-flow as the canonical migration authoring strategy.md
• docs/architecture docs/adrs/ADR 194 - Plans carry their own authoring surface.md
• docs/architecture docs/adrs/ADR 195 - Planner IR with two renderers.md
• docs/architecture docs/adrs/ADR 196 - In-process emit for class-flow targets.md
• docs/architecture docs/adrs/ADR 197 - Migration packages snapshot their own contract.md
• docs/architecture docs/adrs/ADR 198 - Runner decoupled from driver via visitor SPIs.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md
• docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded migration slots.md
• docs/architecture docs/subsystems/10. MongoDB Family.md
• docs/architecture docs/subsystems/7. Migration System.md

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

• .gitattributes
• docs/architecture docs/subsystems/10. MongoDB Family.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md
• docs/architecture docs/adrs/ADR 192 - ops.json is the migration contract.md
• docs/architecture docs/adrs/ADR 196 - In-process emit for class-flow targets.md
• docs/architecture docs/adrs/ADR 193 - Class-flow as the canonical migration authoring strategy.md

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

• docs/architecture docs/adrs/ADR 044 - Pre & post check vocabulary v1.md
• docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md
• docs/architecture docs/adrs/ADR 194 - Plans carry their own authoring surface.md
• docs/architecture docs/adrs/ADR 188 - MongoDB migration operation model.md

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/architecture` docs/adrs/ADR 041 - Custom operation loading via local
packages + preflight bundles.md:
- Around line 146-147: Duplicate ADR entries appear in the References section:
remove the repeated ADR 028 and the redundant ADR 188 so each ADR is listed only
once; specifically, edit the References block that contains "ADR 028 — Migration
structure & operations" and "ADR 188 — MongoDB migration operation model" to
keep a single occurrence of ADR 028 and a single occurrence of ADR 188 (remove
the extra lines shown in the diff).

In `@docs/architecture` docs/subsystems/7. Migration System.md:
- Around line 237-241: The docs claim migrationId is computed from
(strippedManifest, ops) only, but the implementation in migration attestation
includes canonicalFromContract and canonicalToContract in the hashed parts;
update the text to state that migrationId is computed from (strippedManifest,
ops, canonicalFromContract, canonicalToContract) so storage-contract changes
affect the hash, and reference the attestation implementation (function/logic
that builds partHashes in
packages/1-framework/3-tooling/migration/src/attestation.ts) to ensure the doc
matches the code.

🪄 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: 0f6472e6-c4a7-45ed-8ff7-2fc4f07b6aac

📥 Commits

Reviewing files that changed from the base of the PR and between 7482e70 and 8f37618.

⛔ Files ignored due to path filters (1)

• projects/mongo-migration-authoring/specs/data-migrations.spec.md is excluded by !projects/**

📒 Files selected for processing (18)

• docs/architecture docs/ADR-INDEX.md
• docs/architecture docs/adrs/ADR 026 - Conformance Kit Certification.md
• docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md
• docs/architecture docs/adrs/ADR 028 - Migration Structure & Operations.md
• docs/architecture docs/adrs/ADR 029 - Shadow DB preflight semantics.md
• docs/architecture docs/adrs/ADR 038 - Operation idempotency classification & enforcement.md
• docs/architecture docs/adrs/ADR 040 - Node task execution environment & sandboxing.md
• docs/architecture docs/adrs/ADR 041 - Custom operation loading via local packages + preflight bundles.md
• docs/architecture docs/adrs/ADR 116 - Extension-aware migration ops.md
• docs/architecture docs/adrs/ADR 166 - Referential actions for foreign keys.md
• docs/architecture docs/adrs/ADR 169 - On-disk migration persistence.md
• docs/architecture docs/adrs/ADR 195 - Planner IR with two renderers.md
• docs/architecture docs/adrs/ADR 196 - In-process emit for class-flow targets.md
• docs/architecture docs/adrs/ADR 198 - Runner decoupled from driver via visitor SPIs.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md
• docs/architecture docs/subsystems/5. Adapters & Targets.md
• docs/architecture docs/subsystems/6. Ecosystem Extensions & Packs.md
• docs/architecture docs/subsystems/7. Migration System.md

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

• docs/architecture docs/adrs/ADR 038 - Operation idempotency classification & enforcement.md
• docs/architecture docs/subsystems/6. Ecosystem Extensions & Packs.md
• docs/architecture docs/adrs/ADR 169 - On-disk migration persistence.md
• docs/architecture docs/adrs/ADR 166 - Referential actions for foreign keys.md
• docs/architecture docs/adrs/ADR 040 - Node task execution environment & sandboxing.md
• docs/architecture docs/adrs/ADR 116 - Extension-aware migration ops.md
• docs/architecture docs/subsystems/5. Adapters & Targets.md
• docs/architecture docs/ADR-INDEX.md
• docs/architecture docs/adrs/ADR 196 - In-process emit for class-flow targets.md
• docs/architecture docs/adrs/ADR 027 - Error Envelope Stable Codes.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md

[wmadden]

Triage summary for this review (CodeRabbit) — see agent-os/specs/review-framework/reviews/prisma_prisma-next_pr-352/review-actions.md:

Inline findings — all have dedicated threads, addressed there:

• ADR 192 line 23–24 (migrationId wording) → A02 — will address
• ADR 197 lines 7–14 (fence language) → A03 — will address
• ADR 199 line 74 (ADR 192 link) → A05 — will address
• ADR 200 lines 21–25 (fence language) → A06 — will address
• ADR 027 lines 128–130 (PN-MIG-2003/2004 vs evaluateMigrationTs) → already-resolved/outdated thread PRRT_kwDOQM0QJc58AYEO. The ADR 027 entries describe the target class-flow contract (per ADR 196); the current evaluateMigrationTs still expects a function default export and throws plain Errors. That implementation alignment is part of the broader class-flow rollout, not this doc-only PR.

Nitpicks — Mermaid ASCII (lines 16–19, 77–84): covered by A08 (single thread on line 18 with "also applies to 79–79").

Nitpick — ADR 199 §17–35 ("move computeMigrationId algo out of ADR"): wont_address (A11a). The 17-line snippet is the decision — it is the precise contract the implementation must satisfy ("strip these fields, hash the rest"). Splitting it into a subsystem doc would create two sources of truth for what is, in effect, a one-paragraph spec. The surrounding At-a-glance / Decision / Why / Consequence / Alternatives narrative satisfies the "decision over algorithm" guideline; the snippet is the unambiguous spec.

[wmadden]

Triage summary for this review (CodeRabbit):

Duplicates and inline findings (already covered):

• ADR 200 lines 21–25 (fence language) → A06 (will address)
• 7. Migration System line 18 (Mermaid ASCII) → A08 (will address)
• 7. Migration System lines 232–235 (migrationId hash inputs) → A09 / A10 — deferred to TML-2269 (implementation needs to align with ADR 199; doc stays as decided)
• 7. Migration System lines 23–31 (fence language) → already-resolved thread PRRT_kwDOQM0QJc58AhHr
• 7. Migration System lines 307–321 (migration verify command synopsis) → already-resolved thread PRRT_kwDOQM0QJc58AhHw

Nitpicks (decomposed into sub-actions in review-actions.md):

• A12a — ADR 198 §50–61 ("condense execution mechanics"): wont_address. These two short paragraphs are the architectural decision — they identify which abstractions carry which traffic (DDL → accept(visitor); DML → adapter.lower → driver.execute) and explain why the earlier MongoDmlExecutor was deleted. No method bodies or algorithm steps are present; the named symbols are the SPI surface the ADR pins down.
• A12b — ADR 195 §75–122 (and 137–157) ("move renderer algo out"): wont_address. ADR 195's whole reason to exist is the two-renderer split. The minimal visitor sketches name the SPIs (renderVisitor, renderCallVisitor, renderOps, renderCallsToTypeScript) and show how PlannerProducedMongoMigration wires both. The §"Why rendering is external to the IR nodes" section is decision-level. Subsystem doc 7 already references this ADR for the planner→IR→render flow.
• A12c — ADR 197 line 25 (wording polish): will_address. Will rephrase "at the moment the migration was scaffolded" → "when the migration was scaffolded".

[wmadden]

Triage summary for this review (CodeRabbit) — every finding here is already covered by a dedicated thread or a now-resolved one:

• 7. Migration System line 18 (Mermaid ASCII) → A08 (will address)
• 7. Migration System lines 232–235 (migrationId hash inputs) → A09 / A10 — deferred to TML-2269
• 7. Migration System lines 307–321 (migration verify synopsis) → already-resolved PRRT_kwDOQM0QJc58AhHw
• 7. Migration System lines 23–31 (fence language) → already-resolved PRRT_kwDOQM0QJc58AhHr
• ADR 200 lines 21–25 (fence language) → A06 (will address)
• ADR 197 lines 7–14 (fence language) → A03 (will address)
• ADR 195 §75–122 (move renderer algo) → A12b (wont_address — see review #4135784808 summary)

No new sub-actions for this review.

[wmadden]

Triage summary for this review (CodeRabbit) — both inline findings are already covered:

• ADR 041 lines 146–147 (duplicate ADR References) → A01 (will address)
• 7. Migration System lines 237–241 (migrationId hash inputs) → A09 / A10 — deferred to TML-2269

No new sub-actions for this review.

[wmadden]

Done on A12c (tracked in this triage summary) in 112bbc9 — ADR 197 line 25 now reads "snapshots of the project's emitted contract when the migration was scaffolded." A12a and A12b remain wont_address as previously triaged.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/architecture` docs/adrs/ADR 192 - ops.json is the migration contract.md:
- Around line 7-15: The fenced directory-tree block that begins with
"migrations/" is missing a language tag; change the opening fence from ``` to
```text so the block becomes a "text" fenced code block (this will fix MD040).
Locate the directory-tree block in the ADR 192 document (the one showing
migrations/ → 2025-06-12T0930_backfill-status/) and update only the opening
fence to include the text language identifier.

In `@docs/architecture` docs/subsystems/7. Migration System.md:
- Around line 23-31: The fenced directory-tree block in the Migration System doc
is missing a language tag (causing MD040); update the code fence that starts
with the migrations/ listing to include the language identifier "text" (i.e.,
change ``` to ```text) so the directory-tree is treated as plain text; locate
the block in the Migration System content (the three-backtick fenced block
containing "migrations/" and its nested files) and add "text" immediately after
the opening backticks.
- Around line 203-218: Update the second fenced code block that contains the
migrations directory tree in "7. Migration System.md" to include a language
identifier (e.g., add "text" after the opening backticks) so the block becomes
```text; this addresses the missing language tag for the directory-tree code
block that starts with the "migrations/" listing.

🪄 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: 9a6ac5cd-fadc-4c0d-8b6f-2d1c76307099

📥 Commits

Reviewing files that changed from the base of the PR and between 8f37618 and ff7fbe8.

📒 Files selected for processing (6)

• docs/architecture docs/adrs/ADR 041 - Custom operation loading via local packages + preflight bundles.md
• docs/architecture docs/adrs/ADR 192 - ops.json is the migration contract.md
• docs/architecture docs/adrs/ADR 197 - Migration packages snapshot their own contract.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md
• docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded migration slots.md
• docs/architecture docs/subsystems/7. Migration System.md

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

• docs/architecture docs/adrs/ADR 041 - Custom operation loading via local packages + preflight bundles.md
• docs/architecture docs/adrs/ADR 199 - Storage-only migration identity.md

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

• docs/architecture docs/adrs/ADR 200 - Placeholder utility for scaffolded migration slots.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add language identifier to directory-tree fence.

The fenced code block is missing a language tag, triggering MD040. Use text for consistency with other directory trees in this PR.

📝 Proposed fix

-```
+```text
 migrations/
   2025-06-12T0930_backfill-status/
     migration.json          # manifest: from/to hashes, migrationId

🧰 Tools

🪛 markdownlint-cli2 (0.22.0)

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

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/adrs/ADR 192 - ops.json is the migration contract.md
around lines 7 - 15, The fenced directory-tree block that begins with
"migrations/" is missing a language tag; change the opening fence from ``` to
```text so the block becomes a "text" fenced code block (this will fix MD040).
Locate the directory-tree block in the ADR 192 document (the one showing
migrations/ → 2025-06-12T0930_backfill-status/) and update only the opening
fence to include the text language identifier.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add language identifier to directory-tree fence.

The fenced code block is missing a language tag. Use text for directory-tree output to satisfy MD040.

📝 Proposed fix

-```
+```text
 migrations/
   20260118T1205_add_users/
     migration.ts            # authoring surface — the developer edits this

🧰 Tools

🪛 markdownlint-cli2 (0.22.0)

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

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/subsystems/7. Migration System.md around lines 23 -
31, The fenced directory-tree block in the Migration System doc is missing a
language tag (causing MD040); update the code fence that starts with the
migrations/ listing to include the language identifier "text" (i.e., change ```
to ```text) so the directory-tree is treated as plain text; locate the block in
the Migration System content (the three-backtick fenced block containing
"migrations/" and its nested files) and add "text" immediately after the opening
backticks.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add language identifier to second directory-tree fence.

This fenced code block also needs a language tag for consistency and to clear MD040.

📝 Proposed fix

-```
+```text
 migrations/
   20260118T1205_add_users/
     migration.ts            # authoring surface — TypeScript the developer edits

🧰 Tools

🪛 markdownlint-cli2 (0.22.0)

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

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/architecture` docs/subsystems/7. Migration System.md around lines 203 -
218, Update the second fenced code block that contains the migrations directory
tree in "7. Migration System.md" to include a language identifier (e.g., add
"text" after the opening backticks) so the block becomes ```text; this addresses
the missing language tag for the directory-tree code block that starts with the
"migrations/" listing.