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.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) 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 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. ---