Skip to content

Commit 69673aa

Browse files
committed
docs(releases): 18.0.0 notes — highlights, release facts, checklist steps 1-2 (WIP)
Claude-Session: https://claude.ai/code/session_01FM29ZqLTrnPNXxijioZwMp Co-authored-by: Claude <noreply@anthropic.com>
1 parent fcb40ad commit 69673aa

1 file changed

Lines changed: 250 additions & 0 deletions

File tree

‎content/docs/releases/v18/18-0.mdx‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
---
2+
title: 18.0.0
3+
description: "The v18 GA release, published 2026-10-20: organization ownership is total (ADR-0131), so a database 17.x created takes the ownership ceremony before 18.0.0 serves it; protocol 18; a flow reads one expression dialect per slot; the security catalog is metadata; API keys expire; the CORS default admits no cross-origin caller. With its upgrade checklist, walked once from 17.7.0."
4+
---
5+
6+
## Highlights — 18.0.0
7+
8+
- **A database 17.x created is upgraded by a ceremony before 18.0.0 serves it.**
9+
ADR-0131 makes organization ownership total: no NULL `organization_id`.
10+
`os serve` 18.0.0 starts on a database it created itself, or on one that
11+
`os migrate organization-ownership` certified, and refuses any other before it
12+
listens (`dd29bbe`, `12d1476`). The ceremony's plan reads only, and `--apply`
13+
runs only the plan you reviewed (`f9b4217`). ⚠️ **Read [step 2 of the upgrade
14+
checklist](#2-upgrade-the-database) before the first 18.0.0 boot of a 17.x
15+
database.**
16+
- **Protocol 18.** `PROTOCOL_VERSION` is `18.0.0`: the handshake admits
17+
`engines.protocol: '^18'` and refuses `'^17'` (`4e9fe9f`). The ADR-0087
18+
conversions whose one-major window ran out leave the load path, so a retired
19+
spelling is refused with its rename instead of being rewritten (`5fd2c76`,
20+
`c5dd7fc`, `bc0538a`, `105902f`, `8693110`, `d176b0a`, `f606ba2`, `f901746`).
21+
- **A flow reads one expression dialect per slot** (ADR-0032). A value slot takes
22+
a CEL value envelope and refuses the single-brace `{…}` template; a text slot
23+
takes `{{ }}` holes; a CEL root the flow does not bind is refused at
24+
`os validate`; `$` names belong to the engine; and every builtin node's
25+
`config` is held to its executor's contract (`0e9e7b7`, `2b61f2d`, `7958bdf`,
26+
`5fb1746`, `2f70c22`).
27+
- **Positions, permission sets and capabilities are metadata.** The four catalog
28+
row objects retire (`sys_position`, `sys_permission_set`,
29+
`sys_position_permission_set`, `sys_capability`), a position names its sets in
30+
`permissionSets`, a grant names its set by name, and a name has one holder per
31+
deployment (ADR-0131 D3/D4; `66949b7`, `bfc15d2`, `6f21216`, `fe98cc6`).
32+
Declared sharing rules, webhooks and email templates are read from the registry
33+
and are read-only (`5e97907`, `191e043`, `7de0265`).
34+
- **Page components are judged as errors.** An undeclared prop, a value its row
35+
refuses or a missing binding fails `os validate`, `os build`, `os lint` and the
36+
metadata save door, where 17.7.0 printed an advisory (`4f68ba1`, `32fa194`,
37+
`d0c09e4`). An element binds its data through `dataSource` only (`317cddd`).
38+
- **Credentials and origins close by default.** A key created without an expiry
39+
lives 90 days, a key unused for 90 days is refused, and a key that existed
40+
with no expiry has one year from the upgrade (`1d79556`). The CORS default
41+
admits no cross-origin caller, and `'*'` with credentials fails the boot
42+
(`f7546a4`). The inbound `api` hook verifies only the timestamped signature
43+
(`5ce6773`).
44+
- **The AI skills ship with the packages,** as `@objectstack/skills`, on the same
45+
version as every other `@objectstack/*` package.
46+
47+
---
48+
49+
## Release facts, as measured
50+
51+
Read with `npm view` and `npm pack` on 2026-10-20, after the publish:
52+
53+
| | Measured |
54+
| :--- | :--- |
55+
| `latest` | `18.0.0`, on every `@objectstack/*` package read (`spec`, `cli`, `runtime`, `core`, `objectql`, `skills`, `organizations`) and on `create-objectstack` |
56+
| `next` | `18.0.0-next.5`, which is **older** than `latest`. ⛔ Never install `@next` for 18: it resolves a prerelease that 18.0.0 supersedes |
57+
| `rc` | `17.0.0-rc.6` (`@objectstack/skills` and `@objectstack/organizations` carry no `rc` tag) |
58+
| Published | `@objectstack/cli@18.0.0` at 2026-10-20 12:44 UTC |
59+
| Prereleases | `18.0.0-next.0` … `next.3` and `next.5`. `next.4` was never published, although the CHANGELOG carries a section for it |
60+
61+
Install 18 by its exact version (`18.0.0`) or a caret range (`^18.0.0`); both
62+
resolve `latest`. Moving the stale `next` tag is a release act, outside these
63+
notes.
64+
65+
### How to read the 18.0.0 CHANGELOG
66+
67+
The `## 18.0.0` section of each package's `CHANGELOG.md` is the whole v18 line:
68+
every changeset of every `18.0.0-next.N`, in landing order. In
69+
`@objectstack/spec` it holds 341 entries; across the 53 packages whose
70+
CHANGELOG has an `18.0.0` section it holds 1,115 distinct entries, 340 of them
71+
marked breaking or narrowing. Read it with two cautions:
72+
73+
- **A later entry can undo an earlier one.** `ae6bd1a` says "18.0 supports fresh
74+
`single` installs only — `os migrate organization-ownership` refuses, and
75+
`os serve` refuses a walled posture at boot"; `12d1476` and `fc34d00`, later in
76+
the same section, open the ceremony and lift the walled refusal, and the
77+
18.0.0 tarball does what the later entries say. `record:json` is declared by
78+
`97b8e7a` and retired by `030a7b8`; it shipped only in `18.0.0-next.3`.
79+
- **The refusal is the authority.** Every refusal this page quotes was read off
80+
the published 18.0.0 packages, not off the CHANGELOG: where the two differ,
81+
the package's own message says what the package does.
82+
83+
The checklist below is curated from that record, not copied from it: it keeps
84+
the changes an application must edit for, and leaves out the ones that move only
85+
the platform's internals, its own tooling and the Console's code (the Console's
86+
changes are in the `@objectstack/console` CHANGELOG).
87+
88+
---
89+
90+
## Upgrade checklist
91+
92+
⚠️ One checklist per release, for the release you are landing on **and** every
93+
release you cross to get there: a 17.4.0 app reads the
94+
[17.5.0](/docs/releases/v17/17-5#upgrade-checklist),
95+
[17.6.0](/docs/releases/v17/17-6#upgrade-checklist) and
96+
[17.7.0](/docs/releases/v17/17-7#upgrade-checklist) lists before this one. On an
97+
`18.0.0-next.N` prerelease, read the CHANGELOG entries after your prerelease
98+
instead: this list is written for 17.x.
99+
100+
### 18.0.0
101+
102+
<Callout type="warn">
103+
**How far this list has been walked.** Once, on 2026-10-20, from 17.7.0: an app
104+
scaffolded with `create-objectstack@17.7.0` (the `blank` template, pnpm, its
105+
skills installed by `skills add`), booted once on 17.7.0 with
106+
`objectstack start` so that it created a SQLite database holding one admin and
107+
three records, then moved to 18.0.0 from npm by following steps 1 and 2 below.
108+
Each line says how it was measured:
109+
110+
- **Measured in the walk** — the step was run, and the quoted text is what 18.0.0
111+
printed.
112+
- **Probed on 18.0.0** — the walk's app carries none of it, so a probe stack was
113+
refused by the installed 18.0.0 packages (`defineStack`, or `os validate`
114+
exiting `1`), and the quoted text is that refusal.
115+
- **Read off the 18.0.0 tarball** — the code or the message was found in the
116+
published package (`npm pack @objectstack/PKG@18.0.0`), and nothing was run.
117+
118+
⛔ The walk was one small app on SQLite under the `single` posture. A walled
119+
database (`group` / `isolated`), Postgres, MySQL and Turso were not walked, and
120+
no upgrade of a production application was run for this page.
121+
</Callout>
122+
123+
#### 1. Move the pins
124+
125+
- **Move every `@objectstack/*` dependency to 18.0.0 together**,
126+
`devDependencies` included, and regenerate the lockfile —
127+
[Moving the dependency pins](/docs/upgrading#moving-the-dependency-pins). The
128+
walk edited six `^17.7.0` ranges and `@objectstack/cli` to `^18.0.0`; the
129+
install moved all seven to 18.0.0 and printed no peer-dependency warning.
130+
*Measured in the walk.*
131+
- **Move the protocol declarations to 18.** `engines.protocol` in your
132+
`defineStack` manifest becomes `'^18'`, and `specVersion` in
133+
`objectstack.manifest.json` becomes `'^18.0.0'` — what
134+
`create-objectstack@18.0.0` stamps. `os migrate meta --from 17 --write`
135+
rewrites `engines.protocol` for you (it printed
136+
`objectstack.config.ts:38 manifest.engines.protocol: '^17' → '^18'`);
137+
`specVersion` is a hand edit, and neither `os validate` nor the boot reads it.
138+
Left on `'^17'`, `os validate` and `os build` still pass with a warning, and
139+
the boot refuses before it serves (exit `1`):
140+
141+
```text
142+
⚠ Installed @objectstack/spec is v18.0.0 but this app declares engines.protocol '^17', which targets protocol v17.
143+
✗ package 'com.example.v17app' targets protocol ^17 (engines.protocol) but this runtime is protocol 18.0.0. This is a major-version break. Run: objectstack migrate meta --from 17
144+
```
145+
146+
*Measured in the walk.*
147+
- **Read `os migrate meta --from 17` as a list to search, not a list to do.** On
148+
the walk's app — one object, two fields, no flow, page or permission set — it
149+
printed `406 manual change(s) require your judgment`: every protocol-18 manual
150+
entry it could not prove absent from the stack. Step 3 below is the curated
151+
version for an application. *Measured in the walk.*
152+
- **Move the AI skills.** From v18 the catalog is the `@objectstack/skills`
153+
package. A 17.x project has none: its skills were installed with
154+
`skills add` from the repository. Remove those, add the package at your
155+
`@objectstack/spec` version with **your project's package manager**, and copy
156+
it into your agent's directory:
157+
158+
```bash
159+
npx skills remove objectstack-ai objectstack-api objectstack-automation \
160+
objectstack-data objectstack-formula objectstack-i18n objectstack-platform \
161+
objectstack-pm-dispatch objectstack-query objectstack-ui objectstack-upgrade -y
162+
pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
163+
# npm: npm install --save-dev "@objectstack/skills@…" · yarn: yarn add -D "@objectstack/skills@…"
164+
npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
165+
```
166+
167+
Measured in the walk: before the removal, the sync printed
168+
`Skipped objectstack-ai from @objectstack/skills: installed with 'skills add' from objectstack-ai/objectstack`
169+
for each of the ten skills, then `Nothing to sync.`, and exited `0` — so
170+
bumping the packages alone keeps the 17.x-era skill text. After it, the sync
171+
printed `Synced 10 skills`. In the walk's pnpm project,
172+
`npm install --save-dev` exited `1` with
173+
`npm error Cannot read properties of null (reading 'edgesOut')`, so use the
174+
manager that installed the project (`create-objectstack` uses pnpm when it is
175+
available). The command writes the exact version, `"@objectstack/skills": "18.0.0"`:
176+
move it with the other pins at the next upgrade. *Measured in the walk.*
177+
- **Run `os validate`, then `os build`.** On the walk's app both passed on 18.0.0
178+
once the declarations read `'^18'`. Step 3 lists what fails a richer app.
179+
*Measured in the walk.*
180+
181+
#### 2. Upgrade the database
182+
183+
A database that 17.x (or an `18.0.0-next.N` prerelease) created carries no
184+
organization-ownership marker, and 18.0.0 does not serve it until the ownership
185+
ceremony has certified it. A database 18.0.0 creates from empty writes its own
186+
birth marker and needs none of this. The command's reference is
187+
[`os migrate organization-ownership`](/docs/deployment/cli#os-migrate-organization-ownership).
188+
189+
- **Before the first 18.0.0 boot, clear the security-catalog overlays:**
190+
`os migrate security-catalog-overlays` lists the environment's stored
191+
permission-set and position rows whose name a package now holds, which a v18
192+
cold boot refuses with `422 NAMESPACE_CONFLICT`; the preview exits `1` when it
193+
lists a row, and `--apply` deletes them (`db9cf80`, `e030d43`).
194+
*Measured in the walk — see the note under this list.*
195+
- **Start 18.0.0 against the database once.** It is refused before it listens,
196+
exit `1`, from the `com.objectstack.organization-ownership-boot-guard` plugin
197+
(error code `ORGANIZATION_OWNERSHIP_MIGRATION_REQUIRED`):
198+
199+
```text
200+
✗ This database carries no organization-ownership marker: 17.x or an 18.0 pre-release (18.0.0-next.*) created it, and this release serves only a database it created itself or one its ownership ceremony upgraded. sys_audit_log, sys_flow_credential, sys_flow_dispatch, sys_job, sys_job_queue, sys_job_run, sys_metadata, sys_metadata_audit, sys_metadata_commit, sys_metadata_history, sys_migration, sys_migration_journal, sys_secret still carry a physical organization_id column its object no longer declares. The server refuses to start rather than serve it in a shape it was never migrated to. Run 'os migrate organization-ownership --out PLAN' to write and review its plan, take a backup, then run 'os migrate organization-ownership --apply --plan-file PLAN --backup-taken', and start again.
201+
```
202+
203+
The refused boot is not wasted: its schema sync creates the tables 18.0.0
204+
adds, which the ceremony moves rows into. In the walk, a plan drawn before
205+
that boot covered 77 tables and one drawn after it 81. *Measured in the walk.*
206+
- **Do not reach for `os migrate apply --allow-destructive` first.** Before the
207+
ceremony, the boot log and `os migrate plan` list the `organization_id`
208+
columns as orphaned and name `os migrate apply --allow-destructive` (28
209+
destructive changes in the walk, with no word of the ceremony). Run on a copy
210+
of the walk's database, that apply exited `1` and dropped nothing:
211+
`✗ Refusing to drop sys_comment.reactions: the emoji reactions stored in it are not yet carried into sys_comment_reaction records …`.
212+
The ceremony comes first. *Measured in the walk, on a copy.*
213+
- **Take a backup.** The platform takes none, and `--apply` asks you to state
214+
that you took one. For SQLite, stop the server and copy the database file
215+
with its `-wal` and `-shm` files, or use `sqlite3 FILE ".backup …"`.
216+
*Measured in the walk (a stopped-server copy).*
217+
- **Write the plan and review it:**
218+
`os migrate organization-ownership --out plan.json`. It reads only; per table
219+
it prints the fate (`attribution`, `column-drop`, `mirror-deletion`,
220+
`report`), the row count, the rows with no organization, and whether the
221+
table will receive `NOT NULL`. The walk's plan: 81 tables, 34 to receive
222+
`NOT NULL`, `unattributableRows: 0`. A row whose owner cannot be derived
223+
blocks certification until you give it an organization or delete it.
224+
*Measured in the walk.*
225+
- **Apply the reviewed plan:**
226+
`os migrate organization-ownership --apply --plan-file plan.json --backup-taken`.
227+
The walk's run attributed 32 rows, rewrote 2 grants to name their permission
228+
set, deleted 49 mirror rows (the retired catalog rows and the seeded email
229+
templates), dropped 14 `organization_id` columns, set `NOT NULL` on 32 tables,
230+
and ended `✓ The ceremony is complete; recorded as adr-0131-organization-ownership.`
231+
It refuses to run beside a process that holds the SQLite file open
232+
(`0b9391b`): stop the server first. *Measured in the walk.*
233+
- **Start the server.** In the walk 18.0.0 served the database: the 17.7.0
234+
admin signed in with the same password, kept `platform_admin`, `org_owner`
235+
and `admin_full_access`, read the three notes with their organization, and
236+
wrote a fourth. *Measured in the walk.*
237+
- **Then clear the drift that remains.** The first served boot still logged
238+
three orphaned columns (`sys_comment.reactions`,
239+
`sys_sso_provider.created_by` / `updated_by`). Carry the reactions first —
240+
`os migrate comment-reactions` to preview, `os migrate comment-reactions --apply --yes`
241+
to record a verified run (`9963322`, `6673c80`) — then
242+
`os migrate apply --allow-destructive --yes`, which dropped the three. The next
243+
boot logged no drift. *Measured in the walk.*
244+
245+
`os migrate security-catalog-overlays` was run in the walk against the
246+
17.7.0-created database before its first 18.0.0 boot; see the walk record in the
247+
pull request that wrote this page for its output. `os dev` runs the ceremony on
248+
its own for a local SQLite development database, according to the
249+
[CLI reference](/docs/deployment/cli#os-migrate-organization-ownership); the
250+
walk used `objectstack start` and did not exercise that path.

0 commit comments

Comments
 (0)