Skip to content

Commit 96eb587

Browse files
committed
docs(project): drop EA framing from umbrella plan/spec
EA shipped without this work, so the umbrella no longer has a deadline. Replace the pre-EA/post-EA sequencing with deadline-free framing: S1+S2 are the must-ship core, S3 is additive and can land independently. The default-namespace fallback is reframed as a backward-compatibility mechanism for existing consumers rather than EA protection. Removes the EA-timeline constraint/risk and renumbers the surrounding items. Signed-off-by: Will Madden <madden@prisma.io>
1 parent ab6875c commit 96eb587

2 files changed

Lines changed: 34 additions & 36 deletions

File tree

projects/target-extensible-ir-namespaces/plan.md

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22

33
**Spec:** [`projects/target-extensible-ir-namespaces/spec.md`](./spec.md)
44
**Linear Project:** [Target-Extensible IR + Namespaces](https://linear.app/prisma-company/project/target-extensible-ir-namespaces-fd69eff8aec6)
5-
**Purpose** _(from spec)_: Make first-class namespaces and target-extensible IR usable for the downstream Supabase integration. The IR gains a pack-contributed entity-kind mechanism (proven by Postgres enum migrating off the framework-shared `types` slot); runtime SQL and the DSL/ORM surfaces qualify identifiers and dispatch through default-namespace fallback so EA users on single-namespace contracts experience zero breakage; the explicit namespace-aware surface (`db.sql.auth.user`) ships post-EA as purely additive work.
5+
**Purpose** _(from spec)_: Make first-class namespaces and target-extensible IR usable for the downstream Supabase integration. The IR gains a pack-contributed entity-kind mechanism (proven by Postgres enum migrating off the framework-shared `types` slot); runtime SQL and the DSL/ORM surfaces qualify identifiers and dispatch through default-namespace fallback so existing single-namespace consumers experience zero breakage; the explicit namespace-aware surface (`db.sql.auth.user`) lands later as purely additive work.
66

77
## At a glance
88

9-
Three units, single stack thread: **S1 (sub-project) → S2 (slice) → S3 (slice)**. S1 + S2 are pre-EA must-ship; S3 is post-EA additive. No parallelisation at the umbrella level — each unit gates the next on substrate, not just on convention. The umbrella plan delegates execution detail to S1 (now closed; durable decisions in [ADR 221](../../docs/architecture%20docs/adrs/ADR%20221%20-%20Contract%20IR%20two%20planes%20with%20uniform%20entity%20coordinate%20and%20pack-contributed%20entity%20kinds.md)) and to S2/S3 slice specs which will be authored via `drive-specify-slice` at pickup time.
9+
Three units, single stack thread: **S1 (sub-project) → S2 (slice) → S3 (slice)**. S1 + S2 are the must-ship core; S3 is additive and can land independently. No parallelisation at the umbrella level — each unit gates the next on substrate, not just on convention. The umbrella plan delegates execution detail to S1 (now closed; durable decisions in [ADR 221](../../docs/architecture%20docs/adrs/ADR%20221%20-%20Contract%20IR%20two%20planes%20with%20uniform%20entity%20coordinate%20and%20pack-contributed%20entity%20kinds.md)) and to S2/S3 slice specs which will be authored via `drive-specify-slice` at pickup time.
1010

1111
## Composition
1212

@@ -26,13 +26,13 @@ Three units, single stack thread: **S1 (sub-project) → S2 (slice) → S3 (slic
2626

2727
**Validation gate.** Each S1 slice has its own validation gate (see S1's plan). S1 closes when all six slices land and S1's PDoD1-PDoD11 are met.
2828

29-
**Pre/Post-EA.** Pre-EA must-ship.
29+
**Priority.** Must-ship core (closed).
3030

3131
#### S2 — runtime SQL qualification + default-namespace DSL/ORM fallback
3232

3333
**Unit type:** Slice (single PR).
3434

35-
**Purpose.** Close the runtime loop on PR #534's namespace IR: runtime SQL emits namespace-qualified identifiers; DSL/ORM reads through per-family default-namespace fallback (`'public'` for Postgres; `'__unbound__'` for Mongo/SQLite) so legacy query code keeps working unchanged. The fallback is the load-bearing EA-protection mechanism.
35+
**Purpose.** Close the runtime loop on PR #534's namespace IR: runtime SQL emits namespace-qualified identifiers; DSL/ORM reads through per-family default-namespace fallback (`'public'` for Postgres; `'__unbound__'` for Mongo/SQLite) so legacy query code keeps working unchanged. The fallback is the load-bearing backward-compatibility mechanism.
3636

3737
**Scope.** ~10-12 files: family façade hardcoded `defaultNamespace` constant; DSL `Db<C>` type-resolution path; ORM accessor type-resolution path; runtime SQL identifier-qualification at the relational-core / runtime layers. Slice spec authored via `drive-specify-slice` at pickup time; lands at `projects/target-extensible-ir-namespaces/slices/runtime-qualification/spec.md`.
3838

@@ -49,7 +49,7 @@ Three units, single stack thread: **S1 (sub-project) → S2 (slice) → S3 (slic
4949
- `pnpm lint:deps`
5050
- **Project-specific check:** the demo app's `examples/prisma-next-demo/src/queries/*.ts` files compile and run unchanged after S2 lands. (Surfaces FR5 satisfaction.)
5151

52-
**Pre/Post-EA.** Pre-EA must-ship.
52+
**Priority.** Must-ship core.
5353

5454
#### S3 — explicit namespace-aware DSL/ORM surface
5555

@@ -72,7 +72,7 @@ Three units, single stack thread: **S1 (sub-project) → S2 (slice) → S3 (slic
7272
- `pnpm lint:deps`
7373
- **Project-specific check:** demo app migrates one query from `db.sql.user` to `db.sql.public.user` (explicit-namespace form) and both forms compile + run.
7474

75-
**Pre/Post-EA.** Post-EA additive.
75+
**Priority.** Additive (can land independently).
7676

7777
### Parallel groups
7878

@@ -97,36 +97,35 @@ Within S1, S1's own plan defines parallelisation opportunities (Slices 4 + 5 are
9797

9898
| Project-DoD | Delivered by |
9999
|---|---|
100-
| **PDoD1.** All units delivered or deferred | S1 + S2 (pre-EA) + S3 (post-EA, or deferred to a sibling initiative) |
100+
| **PDoD1.** All units delivered or deferred | S1 + S2 + S3 (additive; or deferred to a sibling initiative) |
101101
| **PDoD2.** Multi-namespace contract authorable + emittable + queryable end-to-end | S1 (authoring + emission) + S2 (queryable) |
102102
| **PDoD3.** Pack-contributed entity-kind substrate exercised end-to-end (Postgres enum migration) | S1 (inherits its own PDoD3) |
103103
| **PDoD4.** Runtime SQL identifier-qualification | S2 |
104-
| **PDoD5.** EA users on default-namespace contracts experience zero query-API breakage | S2 (default-namespace fallback) + verified across S1+S2 landings |
104+
| **PDoD5.** Existing consumers on default-namespace contracts experience zero query-API breakage | S2 (default-namespace fallback) + verified across S1+S2 landings |
105105
| **PDoD6.** Long-lived ADRs migrated to `docs/architecture docs/adrs/` | Close-out task; lifts ADRs from S1 + any S2/S3 ADRs |
106106
| **PDoD7.** Linear Project marked Completed | Close-out task (auto via PR-merge integration) |
107107
| **PDoD8.** Rolled-up project folders archived; umbrella folder deleted | Close-out task |
108108
| **PDoD9.** Repo-wide references stripped | Close-out task |
109109

110110
## Risks + open questions
111111

112-
1. **EA timeline slip.** A2 in the spec is the binding constraint. Honest budget for pre-EA scope is ~12-15 days (S1: 10-12 + S2: 2-3); "few days" framing was unrealistic. Working position is to slip pre-EA by 1-2 weeks rather than ship breaking IR changes into EA. If the slip is unacceptable to the team, the conversation re-opens at umbrella level — options are (a) ship without S1's IR reshape and accept breaking changes for EA users when S1 lands later, (b) compress S1 via aggressive parallelism (compression-sprint plan, previously discarded), or (c) defer S2's namespace-qualification too and ship EA on the unchanged surface with namespaces deferred to the next minor.
113-
2. **S1 internal slice falsifications cascade to umbrella.** *(Resolved — S1 closed; durable decisions in [ADR 221](../../docs/architecture%20docs/adrs/ADR%20221%20-%20Contract%20IR%20two%20planes%20with%20uniform%20entity%20coordinate%20and%20pack-contributed%20entity%20kinds.md).)* S1's assumptions held without forcing an umbrella-level re-sequencing of S2 / S3.
114-
3. **A4 default-namespace fallback sufficiency.** If EA users start writing multi-namespace contracts before S3 lands, the flat DSL surface becomes inadequate and S3's post-EA window compresses. Mitigation: EA release notes communicate the namespace-aware surface as "coming soon."
115-
4. **Linear audit surfaces unexpected scope.** The 21 Linear tickets currently in the project may include work that wasn't accounted for in this umbrella's three-unit composition. If audit surfaces real-scope work the umbrella missed, the plan re-opens.
112+
1. **S1 internal slice falsifications cascade to umbrella.** *(Resolved — S1 closed; durable decisions in [ADR 221](../../docs/architecture%20docs/adrs/ADR%20221%20-%20Contract%20IR%20two%20planes%20with%20uniform%20entity%20coordinate%20and%20pack-contributed%20entity%20kinds.md).)* S1's assumptions held without forcing an umbrella-level re-sequencing of S2 / S3.
113+
2. **A3 default-namespace fallback sufficiency.** If consumers start writing multi-namespace contracts before S3 lands, the flat DSL surface becomes inadequate and S3 rises in priority. Mitigation: document the namespace-aware surface as a planned addition so consumers know explicit navigation is coming.
114+
3. **Linear audit surfaces unexpected scope.** The Linear tickets in the project may include work that wasn't accounted for in this umbrella's three-unit composition. If audit surfaces real-scope work the umbrella missed, the plan re-opens.
116115

117116
## Sequencing visualisation
118117

119118
```text
120119
PR #534 ✓ (merged)
121120
122121
123-
S1 — contract-ir-planes (sub-project, 6 slices internally, ~10-12 days)
122+
S1 — contract-ir-planes (sub-project, 5 merged slices) ✓ CLOSED
124123
125124
126-
S2 — runtime-qualification (slice, ~2-3 days)
125+
S2 — runtime-qualification (slice) → next
127126
128-
← EA cut here
129-
S3 — explicit-namespace-dsl (slice, ~2-3 days, additive, post-EA)
127+
128+
S3 — explicit-namespace-dsl (slice, additive)
130129
131130
132131
Downstream: Supabase integration consumes this substrate

0 commit comments

Comments
 (0)