Skip to content

Commit b7a688e

Browse files
fix(client,platform-objects,docs): in-system copy says "this system", not "this environment" (cloud#3002 ruling A) (#24482)
Fixes #24456 Clause-②: no (copy only: TSDoc, two hand-written docs pages and three translated help values; no accept set, export, shape, status or code moves) ## What this does PR #24454 moved the spec's source sentences to objectstack-ai/cloud#3002 ruling A, as triage applied it (`6250167038` on #24327, `6252585695` on #24368): - a set "made here, not from a package" reads "authored in this system"; - "the system the caller is in" drops the noun, or says "this system"; - a string that means a deployment or configuration scope keeps its word. This PR makes the client SDK, the hand-written docs and the three translated bundles match it. It also qualifies the `/ai/models` decision citation as `cloud ADR-0028` (Prime Directive #13). ## Per-string reading Line numbers are on base `31ce45c07`. "Clause 1/2/3" are the three bullets above, in order. | site | before | after, or kept: reason | |:--|:--|:--| | `packages/client/src/index.ts:6702`, TSDoc of `ai.models()` (ships in the `.d.ts`) | Models this environment offers in the chat model picker (ADR-0028) | Models this system offers in the chat model picker (cloud ADR-0028). Clause 2: the system the caller asks. This is the spec's `AiModelsResponse.models` describe as PR #24454 left it. The citation is qualified, see below | | `content/docs/api/plugin-endpoints.mdx:112`, the `GET /ai/models` row | Models this environment offers (ADR-0028) | Models this system offers (cloud ADR-0028). Same reading | | `content/docs/permissions/permission-sets.mdx:369`, "One authoritative store" | a package's declaration, or a definition authored in this environment and saved in `sys_metadata` | ... a definition authored in this system and saved in `sys_metadata`. Clause 1: set against "a package's declaration" | | `permission-sets.mdx:387`, the edit consequence | Every other set (one created in this environment, a clone, or one saved into a writable runtime package) | (one authored in this system, a clone, or ...). Clause 1 | | `permission-sets.mdx:393-394`, the delete consequence (wrapped over two lines, so a line grep misses it; found by a multi-line scan) | A set you created in this environment is removed. | A set authored in this system is removed. Clause 1: set against "a set that ships with an installed package/app" | | `permission-sets.mdx:422`, the clone door | saves the copy ... as a set authored in this environment: no package, ... | ... as a set authored in this system: no package, ... Clause 1: the clone is saved into no package | | `content/docs/permissions/authentication.mdx:252`, first-run bootstrap status | does this environment have no **human** user yet? | does this system have no **human** user yet? Clause 2: the probe asks the running system about its own users | | `authentication.mdx:312-313`, set-initial-password (wrapped over two lines) | an email/password way in to this environment without the SSO round-trip | ... way in to this system ... Clause 2. This is the same sense as cloud-connection's "Sign in to this environment", which #24404 rewrote | | `authentication.mdx:1125`, the endpoint list's bootstrap-status entry | whether this environment has no human user yet | whether this system has no human user yet. Clause 2, as `:252` | | `zh-CN.metadata-forms.generated.ts:2337`, `metadataForms.permission.fields.packageId.helpText` | ... 在本环境中创建的权限集请留空。 | ... 在本系统中创建的权限集请留空。 Follows the `en` value PR #24454 regenerated ("Leave empty for a set authored in this system.") | | `ja-JP.metadata-forms.generated.ts:2337`, same key | ... この環境で作成したセットでは空のままにします。 | ... このシステムで作成したセットでは空のままにします。 Same | | `es-ES.metadata-forms.generated.ts:2337`, same key | ... Déjalo vacío para un conjunto creado en este entorno. | ... Déjalo vacío para un conjunto creado en este sistema. Same | | `packages/client/src/index.ts:3341`, `:3343`, TSDoc of `environments.activate(id)` | Activate this environment for the current session ... routed to this environment's database | **kept**: deployment scope. The method addresses `/api/v1/cloud/environments/:id` on the control plane. "this environment" is the one `id` names, one environment among several | | `index.ts:3353`, TSDoc of `environments.rotateCredential(id, ...)` | Rotate the active database credential for this environment. | **kept**: the same control-plane route family and the same scope | | `index.ts:3364`, TSDoc of `environments.updateHostname(id, ...)` | Update the hostname bound to this environment. | **kept**: the same | | `index.ts:7816-7817`, `:7852-7853`, TSDoc of the environment-scoped metadata client's `deleteItem` and `history` (each wrapped) | ... scoped to this environment. | **kept**: configuration scope. This is the scoped client's `/environments/:environmentId` mount, set against its unscoped twin in the same sentence | | `permission-sets.mdx:380`, the edit consequence's lead | **A set shipped in code cannot be edited in the environment.** | **A set shipped in code cannot be edited in this system.** Clause 2: the running system, in the same consequence list as `:387`'s "one authored in this system" | | `permission-sets.mdx:394-395`, the delete consequence (wrapped) | A set that ships with an installed package/app cannot be removed from the environment: its definition stays served from the package. | ... cannot be removed from this system: ... Clause 2: it follows "A set authored in this system is removed." in the same bullet | | `authentication.mdx:268-269`, the bootstrap-status fail-open sentence (wrapped) | ... rather than offering to create an owner on an environment that may already have one. | ... rather than offering to create an owner when one may already exist. Clause 2, with the noun dropped: the same running system `:252` names in this section | | `content/docs/api/client-sdk.mdx:395`, the comment on the `ai.models()` example | // plan-filtered picker list (ADR-0028) | // plan-filtered picker list (cloud ADR-0028). The same qualification as the TSDoc and the `plugin-endpoints.mdx` row; see the next section | | `permission-sets.mdx:239`, how a position's `permissionSets` resolve | Each name in `permissionSets` is resolved in the environment's catalog | **kept**: the spec calls the same lookup "the environment catalog" (`packages/spec/src/identity/position.zod.ts:16`, `:93`, `:107`), and PR #24454 left it | | `permission-sets.mdx:374`, `:401` | `?scope=environment`; "environment metadata under `single`" | **kept**: configuration scope. Both name the ADR-0131 environment scope, as against an organization's | | `permission-sets.mdx:345`, `:350`, `:360`, `:421` | "package vs environment sets", "environment-authored sets", "An environment write", "Environment-authored sets", "environment-authored set" | **kept**: "environment-authored" is the documented name of the provenance class, which the spec also keeps (`permission-set-owner-binding.ts:103`). The `:345` heading and `:350` use the same class vocabulary. This round's census found those two beyond the seat's list; they are kept for the same reason | The translations keep each locale's verb. 创建, 作成 and creado are the usual words in those locales for making a record here, which is the sense the class names. Only the noun moves, to the words this family's earlier translations chose: 本系统 / このシステム / este sistema (PR #24432). ## The `ADR-0028` citation: read as cloud's - This registry's `docs/adr/0028-metadata-naming-and-namespace-isolation.md` is "Metadata Naming & Namespace Isolation". It says nothing about models, plans or a picker. - `/ai/models` is served by `service-ai`, which this repository does not ship. `content/docs/kernel/services-checklist.mdx` says "`service-ai` (chat, completion, models, conversations) is Cloud/EE". The v17.0.0 entry that introduced `ai.models()` together with this citation (`packages/client/CHANGELOG.md`, changeset `8b9d71e`) says "`service-ai` is a Cloud/EE package in the `cloud` repo". Plan policy also stays server-side in cloud (`packages/cloud-connection/package.json`, cloud ADR-0008). - This session could not read cloud's own registry. `add_repo` for objectstack-ai/cloud answered "you don't have access". So this PR does not confirm cloud ADR-0028's title. The qualification rests on two facts: this registry's 0028 is unrelated, and the code the citation governs lives in cloud. - `scripts/check-adr-anchors.mjs` recognises the `cloud ADR-` qualifier and skips it (`CROSS_REPO_QUALIFIERS`). ## Translations and their source-hash record None of the three leaves has a recorded source hash, so no hash moves: - `grep -c metadataForms` over the six `*.source-hashes.ts` / `*.source-hashes.generated.ts` files answers 0 for each. - A generated-section table carries an entry only while the leaf is a byte copy of its source (`source-hash.ts`, `GENERATED_SECTIONS`, and each table's header). These three leaves are translations, so each is legacy-trusted. - `node scripts/check-i18n-bundles.mjs --write` ran on the edited tree and exited 0. It rewrote every bundle file (mtimes moved to the run), and `git status --porcelain` stayed empty afterwards. The generator kept all three hand values and wrote no hash entry. - No key was added or dropped. ## Changeset `.changeset/24456-client-platform-objects-this-system.md` is a `patch` for `@objectstack/client` and `@objectstack/platform-objects`. Both publish (`private` unset, and `files` ships `dist`). The TSDoc reaches the client's `.d.ts`, and the bundles reach platform-objects' `dist`. The docs pages publish nothing. ## Verification Every reading is at HEAD `3becd9711` on base `31ce45c07`, unless it is marked as taken at `1fd900cfd`. The second commit, `3becd9711`, changes three hand-written docs pages and no package file (`git diff --stat 1fd900c 3becd97`). So the typecheck, test and i18n `--write` readings taken at `1fd900cfd` cover the same package bytes. Each exit code was captured before any pipe. - Build: `turbo run build --filter=!@objectstack/docs --concurrency=2` through `scripts/pm/os-verify-lock.sh`. At `1fd900cfd`: `Tasks: 76 successful, 76 total`, `VERDICT command-exit 0`. At `3becd9711`, in a recreated worktree: `Tasks: 76 successful, 76 total`, `Cached: 76 cached, 76 total` (FULL TURBO), `VERDICT command-exit 0`. - Typecheck, at `1fd900cfd`: `pnpm --filter @objectstack/client --filter @objectstack/platform-objects typecheck` exited 0 (`VERDICT command-exit 0`), with `check:test-typecheck: OK` for both. - Tests, at `1fd900cfd`: `@objectstack/platform-objects` `Test Files 77 passed (77)`, `Tests 1184 passed (1184)`. `@objectstack/client` `Test Files 52 passed (52)`, `Tests 671 passed (671)`. `VERDICT command-exit 0`. - `eslint --no-inline-config` over the four changed `.ts` files: exit 0, no output, at both heads. - Gates: `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` at `3becd9711` (9 paths) derived 90 commands, the same 90 as at `1fd900cfd`, and all 90 exited 0. The reconciliation `--ran` answered "Run reconciliation — 90 derived, 90 run, 0 NOT-MEASURED, 0 UNRUN". Among them: - `pnpm check:i18n`: "OK (10 package(s) — all bundles in sync, no undeclared authoring keys)". - `pnpm check:i18n-stale-fill`: "OK (11 bundle set(s) — no new stale fills, 0 baselined)". - `pnpm check:nul-bytes`: OK. - `pnpm check:doc-authoring`: clean. - `pnpm --filter @objectstack/spec run check:docs`: "227 generated files in sync". - `pnpm check:dts-closure`: 178/178 present. - I also ran the 11 declared-wide families and the 4 artifact-roster families whose roster sits under a path of this diff (`check-changeset-fixed`, `check:authz-resolver`, `check:error-code-casing`, `check:filter-alias-parity`). All 15 exited 0, at both heads. - Control-byte self-scan over the 9 changed files at `3becd9711`: no hits. - No ablation and no reverse verification: the diff changes copy only, and no test pins any old sentence. `git grep -F` finds each old sentence only at its own site. - Not run locally: `test:repo` (CI `Test Core`), and the 6 families that take a value from the workflow (CI only). ## Acceptance notes None of these is this card's to move. Carrier for each: none, unless named. - `packages/spec/src/api/protocol.zod.ts:3359` and `:3362` cite a bare `ADR-0028` beside `/ai/models` ("the environment's plan-filtered picker list (ADR-0028)", "the ADR-0028 allowlist"). Spec is `domain:spec`'s and on hold here. The same `:3359` line and `:3371` ("Whether this is the environment default") keep "environment", as PR #24454 read them: the deployment's plan-scoped list and its configured default. --- _Generated by [Claude Code](https://claude.ai/code/session_01SYEJqDL3NXxrJRBVqaMu9T)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 33a45cc commit b7a688e

9 files changed

Lines changed: 30 additions & 18 deletions

File tree

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
'@objectstack/client': patch
3+
'@objectstack/platform-objects': patch
4+
---
5+
6+
Clause-②: no
7+
8+
fix(client,platform-objects): the `ai.models()` TSDoc and the translated permission-set `packageId` help say "this system", as the spec now does
9+
10+
- **What changed.** Inside the running system, published copy names the system the reader is in as "this system", and a permission set made here, not shipped by a package, is "authored in this system". `@objectstack/spec` already says both (`AiModelsResponse.models`, the permission set's `packageId` help text); this follows it in two more places.
11+
- The TSDoc of `client.ai.models()` now reads "Models this system offers in the chat model picker (cloud ADR-0028)". The citation is qualified as `cloud ADR-0028`: the AI service that serves this list is a cloud package, and this repository's ADR-0028 is about metadata naming.
12+
- The zh-CN, ja-JP and es-ES values of the permission set's `packageId` help text in the Setup forms bundle now say 本系统 / このシステム / este sistema where they said 本环境 / この環境 / este entorno, matching the English text "Leave empty for a set authored in this system."
13+
- **Unchanged.** Every method, route, type, form field, key and behaviour. No translation key is added or removed.

‎content/docs/api/client-sdk.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -392,7 +392,7 @@ for await (const frame of await client.ai.chatStream({ messages })) {
392392
}
393393

394394
await client.ai.complete({ prompt: 'Summarise this account in one line:' });
395-
await client.ai.models(); // plan-filtered picker list (ADR-0028)
395+
await client.ai.models(); // plan-filtered picker list (cloud ADR-0028)
396396

397397
// Conversations — all six routes, scoped to the authenticated user server-side.
398398
const conv = await client.ai.conversations.create({ title: 'Q3 pipeline' });

‎content/docs/api/plugin-endpoints.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ These are the routes `service-ai` mounts, and the SDK method that reaches each:
109109
| POST | `/ai/chat` | `ai.chat` / `ai.chatStream` | Chat completion — JSON with `stream: false`, otherwise the Vercel UI Message Stream |
110110
| POST | `/ai/chat/stream` | — | Generic-SSE twin of `/ai/chat`: the same completion without the tool loop or persistence |
111111
| POST | `/ai/complete` | `ai.complete` | Text completion |
112-
| GET | `/ai/models` | `ai.models` | Models this environment offers (ADR-0028) |
112+
| GET | `/ai/models` | `ai.models` | Models this system offers (cloud ADR-0028) |
113113
| GET | `/ai/status` | — | Active adapter provenance (console diagnostics) |
114114
| GET | `/ai/effective-model` | — | Resolved model ids and their source (console diagnostics) |
115115
| POST / GET | `/ai/conversations` | `ai.conversations.create` / `.list` | Create / list conversations — the list is newest first and pages by keyset: send the `id` of the last conversation you hold as `cursor`, and read `hasMore` to learn whether another page follows |

‎content/docs/permissions/authentication.mdx‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,7 @@ console.log('Current user:', session.data.user);
249249
### First-run bootstrap status
250250

251251
`GET /api/v1/auth/bootstrap-status` answers one question — is the admission gate's
252-
bootstrap window open, i.e. does this environment have no **human** user yet? Service
252+
bootstrap window open, i.e. does this system have no **human** user yet? Service
253253
rows (such as the legacy `usr_system` row) do not count.
254254

255255
```typescript
@@ -265,8 +265,7 @@ creation); `client.auth.bootstrapStatus()` is the SDK method that builds it.
265265

266266
It **fails open**: if no data engine is wired, or the count query throws, it
267267
answers `{ "hasOwner": true }` so a client falls through to the ordinary login
268-
flow rather than offering to create an owner on an environment that may already
269-
have one.
268+
flow rather than offering to create an owner when one may already exist.
270269

271270
<Callout type="warn">
272271
This route is unauthenticated, so treat `hasOwner: false` as a hint to render a
@@ -310,7 +309,7 @@ const response = await fetch('http://localhost:3000/api/v1/auth/reset-password',
310309
signed-in user who has no credential account yet — the account was onboarded
311310
through SSO, through the cloud OAuth provider, or imported with
312311
`passwordPolicy: 'none'`. It gives that user an email/password way in to this
313-
environment without the SSO round-trip.
312+
system without the SSO round-trip.
314313

315314
```typescript
316315
const response = await fetch('http://localhost:3000/api/v1/auth/set-initial-password', {
@@ -1122,7 +1121,7 @@ All endpoints are available under `/api/v1/auth/*`:
11221121
#### Session
11231122

11241123
- `GET /api/v1/auth/get-session` - Get current user session
1125-
- `GET /api/v1/auth/bootstrap-status` - Public, unauthenticated first-run probe: `{ "hasOwner": boolean }`, telling a client whether the admission gate's bootstrap window is still open — i.e. whether this environment has no human user yet ([details](#first-run-bootstrap-status))
1124+
- `GET /api/v1/auth/bootstrap-status` - Public, unauthenticated first-run probe: `{ "hasOwner": boolean }`, telling a client whether the admission gate's bootstrap window is still open — i.e. whether this system has no human user yet ([details](#first-run-bootstrap-status))
11261125

11271126
#### Password Management
11281127

‎content/docs/permissions/permission-sets.mdx‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -366,7 +366,7 @@ or uninstall, and every other `/packages` write verb refuse any other caller
366366
## One authoritative store — the definition (ADR-0094 D1, ADR-0131 D3)
367367

368368
A permission-set **definition** has a single authoritative store: the metadata
369-
layer — a package's declaration, or a definition authored in this environment
369+
layer — a package's declaration, or a definition authored in this system
370370
and saved in `sys_metadata` — served by name from the security catalog.
371371
Nothing mirrors it into a row: the `sys_permission_set` record ADR-0094 kept
372372
as a projection is retired, its object is no longer registered, and no data
@@ -377,22 +377,22 @@ goes through the metadata door (`PUT` or `DELETE /api/v1/meta/permission/:name`)
377377
which requires `manage_metadata` — and, under a `group` or `isolated` tenancy
378378
posture, the platform operator. This has three author-visible consequences:
379379

380-
- **A set shipped in code cannot be edited in the environment.** That is a set
380+
- **A set shipped in code cannot be edited in this system.** That is a set
381381
an installed package declares (a `*.permission.ts` file, a stack's
382382
`permissionSets`) or a platform default such as `member_default`. Editing it
383383
through Setup or the metadata API answers `403 NOT_OVERRIDABLE` and stores
384384
nothing. Clone it to a new name instead (the **Clone** action on the set, or
385385
the clone door below) and edit the clone:
386386
the clone is your organization's own set, and package upgrades keep reaching
387-
the original. Every other set (one created in this environment, a clone, or
387+
the original. Every other set (one authored in this system, a clone, or
388388
one saved into a writable runtime package) is edited in place: the edit
389389
lands on its one stored definition.
390390
- **The API name is immutable after creation.** It is the definition's metadata
391391
identity, and the metadata door addresses the set by it, so there is no
392392
rename. Clone the set to a new name instead.
393-
- **A delete depends on where the definition lives.** A set you created in this
394-
environment is removed. A set that ships with an installed package/app cannot
395-
be removed from the environment: its definition stays served from the
393+
- **A delete depends on where the definition lives.** A set authored in this
394+
system is removed. A set that ships with an installed package/app cannot
395+
be removed from this system: its definition stays served from the
396396
package. Uninstall the owning package to remove a packaged set entirely.
397397

398398
An older database keeps the `sys_permission_set` table and its rows, and
@@ -419,7 +419,7 @@ POST /api/v1/security/permission-sets/:name/clone body: { "name": "...", "lab
419419
The clone door copies a set's whole definition under a new machine name. It
420420
reads the source from the security catalog, where every packaged and
421421
environment-authored set lives. It saves the copy through the metadata layer
422-
as a set authored in this environment: no package, and no link back to the set
422+
as a set authored in this system: no package, and no link back to the set
423423
it was copied from, so changes to the source never reach the copy.
424424

425425
- **The body is `{ name, label }`, both required, and nothing else.** `name` is

‎packages/client/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6699,7 +6699,7 @@ export class ObjectStackClient {
66996699
},
67006700

67016701
/**
6702-
* Models this environment offers in the chat model picker (ADR-0028) —
6702+
* Models this system offers in the chat model picker (cloud ADR-0028) —
67036703
* plan-filtered, with the default flagged. Populate a model picker from
67046704
* this rather than hard-coding ids.
67056705
*/

‎packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2334,7 +2334,7 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
23342334
},
23352335
packageId: {
23362336
label: "ID de paquete",
2337-
helpText: "El paquete que distribuye este conjunto; un valor que nombra otro paquete se rechaza. Déjalo vacío para un conjunto creado en este entorno."
2337+
helpText: "El paquete que distribuye este conjunto; un valor que nombra otro paquete se rechaza. Déjalo vacío para un conjunto creado en este sistema."
23382338
},
23392339
systemPermissions: {
23402340
label: "Permisos del sistema",

‎packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2334,7 +2334,7 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
23342334
},
23352335
packageId: {
23362336
label: "所属パッケージ ID",
2337-
helpText: "このセットを同梱しているパッケージです。別のパッケージを指す値は拒否されます。この環境で作成したセットでは空のままにします。"
2337+
helpText: "このセットを同梱しているパッケージです。別のパッケージを指す値は拒否されます。このシステムで作成したセットでは空のままにします。"
23382338
},
23392339
systemPermissions: {
23402340
label: "システム権限",

‎packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2334,7 +2334,7 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
23342334
},
23352335
packageId: {
23362336
label: "所属包 ID",
2337-
helpText: "分发这个权限集的包;填写其他包的 id 会被拒绝。在本环境中创建的权限集请留空。"
2337+
helpText: "分发这个权限集的包;填写其他包的 id 会被拒绝。在本系统中创建的权限集请留空。"
23382338
},
23392339
systemPermissions: {
23402340
label: "系统权限",

0 commit comments

Comments
 (0)