[wmadden-electric]

Today a cosmetic-looking rename of a Composer app's root can deploy into another repository's Project:

// repo A, before
export default appRoot('store', …)
// repo A, after a rename that looks harmless
export default appRoot('billing', …)   // 'billing' is repo B's Project

The root's name is the app's identity, and Composer falls back to matching Projects by display name, so the next push from repo A reconciles into repo B's production environment. The same defect one level down deletes data: renaming a database's name from catalog to catalogue deletes the database and creates an empty one.

This pull request records the design that fixes both, as two Drive projects. The design document for the team is .drive/projects/node-identity-and-consent/design.md. It replaces #355, which checked the GitHub repository id inside Composer.

The decision

1. Every node is declared with an id, the last segment of its address. postgres({ id: 'catalog' }) inside appRoot({ id: 'shop' }) has the address and platform logicalId shop.catalog, the address format that already ships. name no longer gives identity.
2. A deploy finds its Project by logicalId only, and creates one only with --create. The display-name fallback goes. Console creates the Project when a repository is connected, and a one-time script gives older connected Projects a logicalId.
3. A deploy that would delete a database or bucket asks first, following Prisma ORM's rules: --delete shop.catalog, or --rename shop.catalog:shop.catalogue to keep the data under the new address. --yes never answers, and CI fails closed.
4. prisma deploy --name is removed.
5. Later, on the platform: CI tokens scoped to one Project, and answering a CI deploy's questions in Console.

What is in this pull request

• .drive/projects/node-identity-and-consent/design.md: the whole design, the requirements it meets, the decision records it will change, the delivery order, open questions and alternatives.
• .drive/projects/deployment-identity/: spec, plan and notes for part 1 (find by logicalId only, --create, Console creates the Project, the backfill), which is ready to execute.
• .drive/projects/node-identity-and-consent/spec.md and plan.md: the contract and plan for parts 2 to 4.

Nothing under docs/design/ changes yet; the decision records are amended when each part lands.

Open question for review

Whether a node keeps name as a Console label beside id. The document recommends removing it, so every platform name stays the node's address.

Alternatives considered

• Check the GitHub repository id in Composer (fix(cloud): reject GitHub deploys to a different connected project #355). Makes Composer depend on GitHub, and re-checks at deploy time what the platform decided at connect time.
• Have CI's token exchange return the app name and the deploy action pass --name. Hides the identity from the repository, so a local and a CI deploy of the same file can reach different Projects.
• A per-node logicalId field. The platform logicalId is the full address, so the same word would mean two different strings.
• Consent written into the code (author-written rename declarations, Terraform-style moved blocks). The ORM rejected this: the code keeps describing a system that no longer exists.

Agent: brunhilde-44

🤖 Generated with Claude Code

[prisma-gizmo]

✅ Gizmo reviewed 4e4a43f — posted 1 inline comment(s) this pass.

Open findings: 🟠 1 major · 🟡 7 minor

Change walkthrough

This delta rewrites the node-identity-and-consent project documentation for handoff: the previous three-document arrangement (design-notes.md plus two assets) is replaced by a single design.md that carries the full design — the required id field on every node, logicalId-only Project resolution with --create, and the ORM-style consent model (--delete/--rename, --yes never consents, CLI.CONSENT_REQUIRED fails closed in CI). The spec and plan are restructured around four independently shippable parts, and the already-executing deployment-identity project's docs are updated to reference the new file and to note that --name survives part 1 but is removed by part 2.

How it fits the codebase. The design is anchored to the repo's recorded decisions: the four ADRs it amends or supersedes (ADR-0006, ADR-0024, ADR-0050, ADR-0057) all exist at the linked paths, the consent rules defer to the ORM's CLI Style Guide, and the CLI.* dotted error codes follow ADR-0044. The mechanism claims check out against the source: deps as a provision option, compute/postgres/rawPostgres/bucket constructors, the destroy-only-finds behavior, and the module entry being configured in prisma.config.ts (which is why the deployment-identity examples dropped the file argument) are all real.

Consistency across the project docs. The spec's anchor links into design.md resolve to real headings; the plan's part dependencies and sequencing agree with the design's delivery-order table and its own "Needs first"/"Hands to" lines; the transitional constraints (one breaking release for part 2, --delete before --rename) are stated identically in both. No stale references to the deleted design-notes.md or asset files remain anywhere in the repo.

[coderabbitai]

Pre-merge checks: 2

Failed checks: 2 inconclusive

Check name	Status	Explanation	Resolution
Title check		This assessment has not completed. The check will be retried on the next pre-merge check run.
Description check		This assessment has not completed. The check will be retried on the next pre-merge check run.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[prisma-gizmo]

New findings: 🟠 1 major · 🟡 6 minor · trace

[prisma-gizmo]

🟠 Major · consistency — DoD amends the superseded ADR-0051 and never names ADR-0057, the live record for Project resolution

"The two Composer decision records named above" are ADR-0024 and ADR-0051 ("a node's address is its logical ID on the platform", referenced at line 26 and in the references at line 61). ADR-0057 supersedes ADR-0051, and it is ADR-0057's Consequences that record the behavior this project deletes: "container resolution falls back to matching a Project by display name … a compatibility path" (and ADR-0057 also rejects "Match on display names"). If slice 3 amends only the records named here, the repository's binding decision record keeps prescribing the fallback the new resolver no longer implements. The same omission repeats in plan.md slice 3 ("the decision records on stage resolution and node addresses amended") and in the node-identity-and-consent spec and plan.

Recommended fix

Suggested change

- [ ] The two Composer decision records named above are amended. The deploying guide and the core-concepts skill say that a deploy finds its Project by `logicalId` and needs `--create` to make one. The guide's `prisma deploy module.ts --name demo-42` example still works, with `--create` on its first run.

- [ ] The two Composer decision records named above are amended, together with ADR-0057 ("a node's address is its full path from the app name"), which supersedes ADR-0051 and is the live record that carries the display-name fallback. The deploying guide and the core-concepts skill say that a deploy finds its Project by `logicalId` and needs `--create` to make one. The guide's `prisma deploy module.ts --name demo-42` example still works, with `--create` on its first run.

[prisma-gizmo]

🟡 Minor · consistency — Model statement cites ADR-0051, the superseded record, instead of ADR-0057

ADR-0051 was superseded by ADR-0057, which is the live record for "the address is the node's logicalId" (for the root, the address is the app name, so the claim here still holds). Citing only the superseded ADR — here, and in the references lists of both projects' specs — sends the reader to a dead record. The same stale citation appears in .drive/projects/deployment-identity/spec.md (references) and .drive/projects/node-identity-and-consent/spec.md and its design-notes D2.

Recommended fix

Suggested change

	The Project's `logicalId` is the app name (ADR-0051). Container resolution matches on it and on nothing else. If no Project matches, the deploy stops unless `--create` was passed. The platform creates the Project when a repo is connected, so a connected repo's CI run always finds its Project and never needs `--create`.
	The Project's `logicalId` is the app name (ADR-0051, superseded by ADR-0057, which keeps this: the root's address is the app name, and the address is the node's `logicalId`).

[prisma-gizmo]

🟡 Minor · consistency — Walkthrough's proposed API puts logicalId/name in provision() options, contradicting settled decision D1

The example passes logicalId: 'web', logicalId: 'api' and logicalId: 'auth' inside the provision() options object, but design-notes D1 settles that "logicalId lives on the node definition (postgres({ logicalId }), module({ logicalId, name }, …)), not on the provision() call" — the provision-time override stays id, for provisioning the same node twice or a packaged module. The glossary likewise defines the provision-time override as id. A handoff implementer reading this asset as the worked example could build the wrong constructor surface.

Recommended fix

Suggested change

	const auth = provision(authModule, { logicalId: 'auth', secrets: { signingKey: envSecret('AUTH_SIGNING_SECRET') } });
	provision(web, { logicalId: 'web', name: 'Web', deps: { db: catalog, auth: auth.rpc } });
	provision(api, { logicalId: 'api', deps: { db: catalog } });
	const auth = provision(authModule, { secrets: { signingKey: envSecret('AUTH_SIGNING_SECRET') } });
	provision(web({ logicalId: 'web', name: 'Web' }), { deps: { db: catalog, auth: auth.rpc } });
	provision(api({ logicalId: 'api' }), { deps: { db: catalog } });

[prisma-gizmo]

🟡 Minor · consistency — Takeover prompt in 5b offers (--yes), which the design's consent model forbids

The scenario shows Continue? (--yes) for deploying into a Project that holds another source's production deploy. D8 and the spec settle that --yes never consents to a data-losing action — the consent flags are per-subject --delete <subject> / --rename <old>:<new>. Setting logicalId: 'billing' over store is exactly a root re-identification, so the consistent answer mechanism is --rename store:billing. The surrounding text hedges ("Whether Composer asks, or just logs, is a separate decision"), but the illustrated mechanism contradicts the consent model the design hands off.

Recommended fix

Suggested change

	another source. Continue? (--yes)
	another source. Continue? (--rename store:billing)

[prisma-gizmo]

🟡 Minor · consistency — Scenarios use the retired word "stage" for what ADR-0059 renames to "environment"

B1 says "same stages" and D5 (line 57) "User destroys a stage, or production". ADR-0059 replaces "stage" with "environment" on every Composer surface (guides, errors, agent skill), and these handoff docs seed exactly those surfaces. The same slip appears in the walkthrough's §2 table ("overwrites its production stage") and in node-identity design-notes ("The hash differs per stage"). Quoting ADR-0024's title is fine; describing behavior is not.

Recommended fix

Suggested change

	| B1 | Author changes the root `name` from "Store" to "Storefront". | Console label changes. Same Project, same stages, same data. | D1, D3 |
	| B1 | Author changes the root `name` from "Store" to "Storefront". | Console label changes. Same Project, same environments, same data. | D1, D3 |

[prisma-gizmo]

🟡 Minor · consistency — E3 and open item 5 still list the fate of --name as unsettled, but the design settles it

Row E3 (line 66) marks --name as "Open" and item 5 here repeats "the fate of --name" as an open item, but the settled design removes it: design-notes "Smaller consequences" ("--name on prisma deploy goes away"), the spec's phase 2 ("--name on prisma deploy goes away") and plan phase 2 ("--name is removed from prisma deploy"). A reader reconciling the asset against the spec gets two different answers.

Recommended fix

Delete open item 5 and change the E3 row's "Open" to the settled answer: --name is removed in phase 2 and re-identifying the root is --rename.

[prisma-gizmo]

🟡 Minor · correctness — D10 claims leftover Projects are "set by hand in Console", which deployment-identity's spec defers as an open question

D2's safe-removal story assumes D10 covers old Projects, but D10 only backfills linked Projects from the link's reserved module name. For the remaining population — Projects old enough to predate logicalId that also have no repo link — D10 says they are "set by hand in Console", yet the deployment-identity spec's open questions (line 55) defer "whether Console should also allow editing a Project's logicalId by hand for Projects with no link" to the follow-on project "if it comes up". Both cannot hold: either the Console capability exists (then the spec's open question is already answered) or it does not (then this population loses display-name resolution with no remediation, and --create would build them a second, empty Project). The cross-cutting requirement "every repo connected through Console today keeps deploying" is unaffected — linked Projects are backfilled — but the docs disagree about the unlinked tail.

Recommended fix

Reconcile the two documents: either state in D10 that Console editing of a Project's logicalId ships with the backfill slice, or scope D10 to linked Projects and record that unlinked Projects without a logicalId have no automatic remediation and their deploys stop with the --create message.

[prisma-gizmo]

New findings: none · trace

Still open from previous reviews: 🟠 1 major · 🟡 6 minor

[prisma-gizmo]

New findings: 🟡 1 minor · trace

Still open from previous reviews: 🟠 1 major · 🟡 6 minor

[prisma-gizmo]

🟡 Minor · consistency — Design examples use an appRoot constructor that does not exist; the root constructor is module

The "Today" example (line 15), the "After" example (line 21), the address table (line 29) and the "Declaring a node" section (line 51, which lists appRoot and module as separate constructors) all use appRoot, but no such constructor exists anywhere in packages or docs — grep -rn appRoot packages docs returns nothing. The root module is declared module('auth-example', …) in examples/auth, ADR-0006 names the root a module, and the PR description itself uses module('store', …) for today's syntax. In a document written for handoff, presenting a nonexistent constructor as both the current and the proposed API will send part 2's implementers looking for an API that isn't there, or have them invent one.

Recommended fix

Use module in the examples (export default module('shop', ({ provision }) => { … }) today, module({ id: 'shop' }, …) after), drop appRoot from the line-51 list and the address table — or, if a dedicated root constructor is genuinely intended, state its introduction explicitly in "The design" and in part 2 of the delivery order.