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