From 8268ba0feba587583788cb8795c30b582430bca0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 30 Aug 2026 06:47:22 +0000 Subject: [PATCH 1/3] docs(adr): record the v5.0 project to environment rename and its no-alias decision ADR-0006 v4 gains a short section stating what the v5.0 tenancy rename covered, that no alias was kept, and why -- measured on main rather than recalled. The section states its reasons itself instead of quoting the instruction file that points here, which is what made the previous pointer a loop. The three byte-identical v5.0 banners in ADR-0004/0005/0008 move together: repointed at the new section, and the changeset path they named for the breaking-change list is dropped (that file no longer exists -- it was consumed at release, which is why a doc should not cite one as durable evidence). Placed before the two addenda so their 'first addendum' / 'second addendum at the end of this file' cross-references stay true. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EXxTW8mvPBhoHxmyPZ63de --- docs/adr/0004-cloud-multi-kernel.md | 2 +- .../0005-metadata-customization-overlay.md | 2 +- docs/adr/0006-project-environment-split.v4.md | 58 +++++++++++++++++++ 3 files changed, 60 insertions(+), 2 deletions(-) diff --git a/docs/adr/0004-cloud-multi-kernel.md b/docs/adr/0004-cloud-multi-kernel.md index c8de0cbeeb..42c3e99ea9 100644 --- a/docs/adr/0004-cloud-multi-kernel.md +++ b/docs/adr/0004-cloud-multi-kernel.md @@ -1,6 +1,6 @@ # ADR-0004: Cloud Control Plane + Per-Project Kernels -> **v5.0 update (2026):** Throughout this document, the term *project* has been renamed to *environment* (no aliases; CLI flags, URL paths, schemas, env vars all hard-renamed). See ADR-0006 for the rationale and `.changeset/v5-project-to-environment-rename.md` for the breaking-change list. The body below is preserved verbatim for historical context. +> **v5.0 update (2026):** Throughout this document, the term *project* has been renamed to *environment* (no aliases; CLI flags, URL paths, schemas, env vars all hard-renamed). See [ADR-0006 v4 — the v5.0 rename and its no-alias decision](./0006-project-environment-split.v4.md#the-v50-rename-and-its-no-alias-decision) for the rationale. The body below is preserved verbatim for historical context. **Status**: Superseded (2026-04-23) — the physical split between `apps/cloud` diff --git a/docs/adr/0005-metadata-customization-overlay.md b/docs/adr/0005-metadata-customization-overlay.md index c3134cba7c..77ac9fa7c3 100644 --- a/docs/adr/0005-metadata-customization-overlay.md +++ b/docs/adr/0005-metadata-customization-overlay.md @@ -1,6 +1,6 @@ # ADR-0005: Metadata Customization Overlay (Artifact + sys_metadata Delta) -> **v5.0 update (2026):** Throughout this document, the term *project* has been renamed to *environment* (no aliases; CLI flags, URL paths, schemas, env vars all hard-renamed). See ADR-0006 for the rationale and `.changeset/v5-project-to-environment-rename.md` for the breaking-change list. The body below is preserved verbatim for historical context. +> **v5.0 update (2026):** Throughout this document, the term *project* has been renamed to *environment* (no aliases; CLI flags, URL paths, schemas, env vars all hard-renamed). See [ADR-0006 v4 — the v5.0 rename and its no-alias decision](./0006-project-environment-split.v4.md#the-v50-rename-and-its-no-alias-decision) for the rationale. The body below is preserved verbatim for historical context. **Status**: Accepted (2026-05-16) · **Amended** (2026-05-22, see "Amendment: post-ADR-0006 v4 scope") · **Amended** (2026-04-13, branch concept removed — see [ADR-0008 §0](./0008-metadata-repository-and-change-log.md#0-2026-04-13-amendment--drop-project-and-branch-from-metaref)) · **Amended** (2026-08-09, #6825 — the Phase-1 overlay-index migration is deleted; see "Amendment (2026-08-09, #6825): overlay-index delivery after the Phase-1 migration was deleted") diff --git a/docs/adr/0006-project-environment-split.v4.md b/docs/adr/0006-project-environment-split.v4.md index 7ba992b73e..c9ccab7e21 100644 --- a/docs/adr/0006-project-environment-split.v4.md +++ b/docs/adr/0006-project-environment-split.v4.md @@ -255,6 +255,64 @@ when needed. --- +## The v5.0 rename and its no-alias decision + +**Recorded 2026-08-30 (#12747); the decision itself is v5.0's.** This section +writes down a decision that was made and enforced platform-wide but never +stated, and it is written *here* because this record is where the rest of the +repository sends a reader who asks why the platform says `environment`. It +therefore states its reasons directly, rather than citing back the instruction +file that cites this record. + +**What was renamed.** The tenancy noun `project` became `environment` on every +surface the platform owns. Measured on `main`, 2026-08-30: + +| Surface | Spelling today | +|:---|:---| +| CLI command group | `packages/cli/src/commands/environments/` — `list`, `show`, `create`, `switch`, `bind`; there is no `projects` group | +| Control-plane routes | `/api/v1/cloud/environments` | +| Request header | `X-Environment-Id` (read in `packages/rest/src/rest-server.ts`) | +| Environment variable | `OS_ENVIRONMENT_ID` (read in `packages/runtime`, `service-job`, `cloud-connection`) | + +Afterwards `project` keeps exactly one meaning here: the npm/monorepo sense — a +checkout, a workspace, a `package.json` — which is the sense the v4 body above +unifies onto Package. + +**No alias was kept, and that half is the load-bearing one.** There is no +`OS_PROJECT_ID` and no `X-Project-Id` in the tree, and ADR-0087's conversion +registry — the declared home for any tolerated legacy spelling — carries no +entry translating `project` to `environment`. Since a tolerated alias would have +to be declared there, the empty registry is positive evidence that none was +tolerated, not merely evidence that nobody recorded one. + +**Why no alias.** Three reasons, none of which expires with the price: + +1. **One word per concept, or the vocabulary becomes a guess per call site.** An + alias makes both spellings correct, so every reader and every code generator + has to pick one, and a wrong pick typechecks. This is D3's argument below + applied one level up: a split vocabulary is worse than a uniformly old one, + because the reader cannot tell which half is the mistake. +2. **A compatibility spelling outlives the reason for it.** It is cheap only + while it is understood as temporary. Nothing schedules its removal, each new + consumer learns it as a legitimate second form, and the mapping between the + two spellings becomes a permanent seam that every consumer reimplements. +3. **The window was open, and it does not reopen at this price.** The Context + above records the condition the rename was taken under — *"The platform is + still pre-launch; the same one-shot-wipe window v3 used remains open."* Taken + then, the rename cost one coordinated edit; taken later it would cost a + deprecation cycle plus the alias it exists to avoid. The startup-stage + posture is to spend that window rather than bank a migration: no gradualism, + no dual-spelling interval, no single release carrying both. + +**What this section does not claim.** Not that the string `project` is absent +from the tree — it remains correct in the npm/monorepo sense, in domain fixtures +modelling a customer's own project object, and in the API identifiers the two +addenda below adjudicate. The claim is the narrower, checkable one: on the +surfaces tabled above the platform emits a single spelling, and no declared +alias accepts the other. + +--- + ## Addendum (2026-08-27, #12473) — the rename stops at the CLI's user-facing vocabulary: three API surfaces keep `project` deliberately **Provenance.** Maintainer ruling on From c62675999c9e64e6f818265c4f8d0b3c783b4e56 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 30 Aug 2026 06:47:47 +0000 Subject: [PATCH 2/3] docs(adr): point ADR-0007 and ADR-0008 Builds-on at the Accepted ADR-0006 v4 Both linked ADR-0006 under the bare filename, which holds the Superseded v3. The redirect works, so the link checker was green either way and nothing would ever have gone red. Repointed at the .v4 filename -- the revision that carries the API-surface vocabulary boundary -- with a short parenthetical on each so the historical fact a Builds-on line records is not silently destroyed: these records really were built on v3. No mechanical Builds-on-vs-Superseded rule is added; two instances do not justify a permanent gate. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EXxTW8mvPBhoHxmyPZ63de --- docs/adr/0007-settings-manifest-and-kv-store.md | 2 +- docs/adr/0008-metadata-repository-and-change-log.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/adr/0007-settings-manifest-and-kv-store.md b/docs/adr/0007-settings-manifest-and-kv-store.md index 72e9f8c3af..b2d9c0d96a 100644 --- a/docs/adr/0007-settings-manifest-and-kv-store.md +++ b/docs/adr/0007-settings-manifest-and-kv-store.md @@ -2,7 +2,7 @@ **Status**: Accepted — backend implemented; UI pending (objectui) (proposed 2026-05-20 · calibrated 2026-06-12) **Deciders**: ObjectStack Protocol Architects -**Builds on**: [ADR-0005](./0005-metadata-customization-overlay.md) (Metadata Customization Overlay), [ADR-0006](./0006-project-environment-split.md) (Project/Environment Split) +**Builds on**: [ADR-0005](./0005-metadata-customization-overlay.md) (Metadata Customization Overlay), [ADR-0006 v4](./0006-project-environment-split.v4.md) (Project/Environment Split — this record was originally built on v3, superseded by v4) **Consumers**: `@objectstack/spec`, `@objectstack/platform-objects`, new `@objectstack/service-settings`, `@objectstack/plugin-auth` (Setup app), `objectui` (Settings renderer) --- diff --git a/docs/adr/0008-metadata-repository-and-change-log.md b/docs/adr/0008-metadata-repository-and-change-log.md index a08d21a614..c5f4584abf 100644 --- a/docs/adr/0008-metadata-repository-and-change-log.md +++ b/docs/adr/0008-metadata-repository-and-change-log.md @@ -1,11 +1,11 @@ # ADR-0008: Metadata Repository, Change Log & Subscription (M0 → M4) -> **v5.0 update (2026):** Throughout this document, the term *project* has been renamed to *environment* (no aliases; CLI flags, URL paths, schemas, env vars all hard-renamed). See ADR-0006 for the rationale and `.changeset/v5-project-to-environment-rename.md` for the breaking-change list. The body below is preserved verbatim for historical context. +> **v5.0 update (2026):** Throughout this document, the term *project* has been renamed to *environment* (no aliases; CLI flags, URL paths, schemas, env vars all hard-renamed). See [ADR-0006 v4 — the v5.0 rename and its no-alias decision](./0006-project-environment-split.v4.md#the-v50-rename-and-its-no-alias-decision) for the rationale. The body below is preserved verbatim for historical context. **Status**: Accepted (2026-05-22) · Amended 2026-04-13 — branch concept removed (see §0 Amendment). **Deciders**: ObjectStack Protocol Architects -**Builds on**: [ADR-0003](./0003-package-as-first-class-citizen.md), [ADR-0004](./0004-cloud-multi-kernel.md), [ADR-0005](./0005-metadata-customization-overlay.md), [ADR-0006](./0006-project-environment-split.md) +**Builds on**: [ADR-0003](./0003-package-as-first-class-citizen.md), [ADR-0004](./0004-cloud-multi-kernel.md), [ADR-0005](./0005-metadata-customization-overlay.md), [ADR-0006 v4](./0006-project-environment-split.v4.md) (this record was originally built on v3, superseded by v4) **Supersedes (parts of)**: ad-hoc HMR wiring in `packages/metadata` and the local-only POST contract between CLI and runtime. --- From 779109433ac2180c24701a0ffc63423a215c55ff Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 30 Aug 2026 06:48:02 +0000 Subject: [PATCH 3/3] docs(adr): mark ADR-0006 v2 Superseded -- two files under one number claimed Accepted v2 (three-layer tenancy: Project and Environment as siblings under Organization, joined by sys_deployment) still read 'Accepted (v2)' while v4 also reads Accepted. v4's own Supersedes line already names v2. Verified before changing rather than assumed: nothing in v2's Decision is uniquely live. It keeps sys_project as the physical table, plans a dual sys_project / sys_environment ORM name, and holds the API URLs at /api/v1/cloud/projects with provisionProject on the SDK -- every one of which v4 and the v5.0 rename reverse, and the dual-name plan is exactly the alias posture the rename refused. Unlike v3 this file carries no redirect of any kind, so a reader or a corpus scan keying on 'Status: Accepted' had nothing telling it to go read v4. Status line only; neither v2 nor v3 is deleted -- they are part of the record. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EXxTW8mvPBhoHxmyPZ63de --- docs/adr/0006-project-environment-split.v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/0006-project-environment-split.v2.md b/docs/adr/0006-project-environment-split.v2.md index 7f5b7786bb..ca09495d9a 100644 --- a/docs/adr/0006-project-environment-split.v2.md +++ b/docs/adr/0006-project-environment-split.v2.md @@ -1,6 +1,6 @@ # ADR-0006: Three-Layer Tenancy — Organization, Project, Environment -**Status**: Accepted (v2) +**Status**: Superseded by v4 (`0006-project-environment-split.v4.md`) — 2026-05-20 **Date**: 2026-05-20 (v1) / 2026-05-20 (v2 — same day revision) **Deciders**: ObjectStack Protocol Architects **Builds on**: ADR-0002 (Environment-Per-Database Isolation), ADR-0003 (Package as First-Class Citizen), ADR-0005 (Metadata Customization Overlay)