ObjectStackObjectStack

v18

The v18 line and its GA release, 18.0.0, which closes the `18.0.0-next.N` prerelease train and publishes to npm's `latest` tag. It carries ADR-0131 (organization ownership is total, with no NULL `organization_id`) and landed its breaking changes in stages, each with its own migration.

Release status: 18.0.0 is GA — the release this page documents. It closes the v18 prerelease train, which published as 18.0.0-next.N on npm's next dist-tag. The 18.0.0 cut leaves Changesets pre mode, so the @objectstack/* packages stop publishing as 18.0.0-next.N, and 18.0.0 publishes to npm's latest dist-tag, which moves from 17.x to 18 with it. A ^17 dependency range still never moves to 18 by itself: move every @objectstack/* dependency to 18 together, and read Upgrading before you do.

The v18 line exists for one decision whose changes do not fit in a 17.x minor: ADR-0131, organization ownership is total — no NULL organization_id; declared metadata stays in code; a row exists only when an organization authored it. Its changes reshape stored data and narrow what the runtime accepts, so the ADR stages them in one major (its D14) instead of spreading them across 17.x minors. While the line was open, every other breaking change that landed on main shipped on it too, under the same rules.

Upgrading a database to 18.0.0

An existing database moves to 18.0.0 through the organization-ownership ceremony, os migrate organization-ownership (ADR-0131 D10).

  • A fresh install writes a birth marker. The first boot that creates a datastore from empty writes a sys_migration row (adr-0131-organization-ownership) naming the ownership shape generation it was born in. A fresh 18.0.0 install never needs the ceremony, under any tenancy posture.
  • A database without one is refused at boot. A database 17.x or an 18.0 pre-release (18.0.0-next.*) created carries no birth marker, so an 18.0.0 server refuses it and names the ceremony command. Start 18.0.0 against it once (the refused boot still creates the tables 18.0.0 adds), take a backup, run os migrate organization-ownership --out plan.json, review the plan, run os migrate organization-ownership --apply --plan-file plan.json --backup-taken, and start the server again. The ceremony writes the same marker, verified, when its post-check passes.
  • A development boot passes --dev. On a deployment served with --dev (os dev, os serve --dev), for example a local one with no OS_AUTH_SECRET, both ceremony commands take --dev, as the refusal os serve --dev prints names them. os dev runs the ceremony itself for a local SQLite development database, once os build has replaced the artifact 17.x compiled: with that artifact in dist/, its in-place upgrade refused its plan and changed nothing.
  • Walled postures boot. OS_TENANCY_POSTURE=group and isolated (and OS_MULTI_ORG_ENABLED=true) boot on a fresh install and on a database the ceremony upgraded, under the same prerequisites as 17.x: the enterprise @objectstack/organizations runtime and OS_PLATFORM_OWNER_EMAIL. The 18.0 pre-releases refused them; 18.0.0 does not. 18.0.0 also refuses a walled boot until a membership policy is declared (OS_AUTH_MEMBERSHIP_POLICY=invite-only, or auto chosen knowingly): ✖ FATAL: tenancy posture 'group' is walled, but this deployment never declared a membership policy.
  • A production os serve needs an auth secret. A production os serve whose stack enables auth and which resolves no OS_AUTH_SECRET is refused before any plugin starts: with no AuthPlugin, no caller can authenticate and every row the boot wrote would have no owner. Set the secret, or serve without the data API (--no-server). os dev and os serve --dev use a development fallback and need none, and os start generates an auth secret on its first run and persists it to <home>/auth-secret. From 18.1.0, --no-server is not a way round the refusal, a production boot whose stack mounts no auth is refused the same way, and so is one whose @objectstack/plugin-auth fails to load (18.1.0, boot and deployment).

The step-by-step is Upgrading to 18.0, each step's measured output is in the walked 18.0.0 upgrade checklist, and every flag is in os migrate organization-ownership.

How a breaking stage lands on this line

  • Through next before latest. Every major is published to the next dist-tag for at least one RC cycle before latest (ADR-0087 D6). While Changesets was in pre mode with the tag next, every release cut from main was the next 18.0.0-next.N, carrying everything merged since the cut before it; 18.0.0 is the cut that takes the line to latest.

  • One stage, one changeset, one migration. ADR-0131 lands in stages, in the order the ADR records, and each stage that breaks something says so in its own changeset: what breaks, and how to move from the old shape to the new one. Those changesets become the CHANGELOG.md entries shipped inside each 18.0.0-next.N package, so read the CHANGELOG of every prerelease you move to — moving from one 18.0.0-next.N to the next can break you.

  • Protocol 18 comes with it. PROTOCOL_VERSION is 18.0.0 on main, so a v18 prerelease's handshake admits engines.protocol: '^18' and refuses '^17'. Read Upgrading before you move an app's declared range.

  • The AI skills move with the packages. From v18 the skills catalog is the @objectstack/skills package, on the same version as every other @objectstack/* package, and it moves only with them. A 17.x project has no such dependency — its skills were installed with skills add from the repository's main — and the sync from the package skips every skill a skills add installed (Skipped … installed with skills add, exit 0), so bumping the packages alone keeps the 17.x-era skill text. After moving the @objectstack/* dependencies to 18, remove those skills, then add the catalog at the new @objectstack/spec's version and copy it into your agent's directory (Upgrading, step 4):

    npx skills remove objectstack-ai objectstack-api objectstack-automation \
      objectstack-data objectstack-formula objectstack-i18n objectstack-platform \
      objectstack-pm-dispatch objectstack-query objectstack-ui objectstack-upgrade -y
    pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
    npx skills@1.7.2 experimental_sync --agent claude-code --copy -y

    Add the package with the manager that installed the project: in a pnpm project, npm install --save-dev fails (npm error Cannot read properties of null (reading 'edgesOut'), measured on the 18.0.0 upgrade walk). npx skills remove --all replaces the first command when these are the only skills the project has: run npx skills list first, because --all removes every installed skill without asking.

  • 18.0.0 ends the prerelease. It is the GA cut: it leaves pre mode and publishes the line to latest.

  • After 18.0.0, a breaking change ships in a minor or a patch. The line takes no further major. Under the maintainer's 2026-10-21 level rule (#25105), a change to the metadata protocol (added, narrowed or semantic) takes minor, and every other change takes patch, breaking or not: a non-protocol breaking change keeps its BREAKING banner and its ADR-0087 disposition. A ^18.0.0 range can therefore move you to a release that breaks you. Pin exact versions, and read each release's page before you move.

Per-release notes

Each release below is a self-contained page: what it changed, what breaks, and its own upgrade checklist.

  • 18.3.0 — customization pairs for installed packages (ADR-0146), ownership queues, per-organization connector credentials and a whole-deployment export. 305 of its 1,379 entries are declared breaking: 264 need you to act and 41 are converted by os migrate meta. Its upgrade checklist moves an 18.2.0 app to 18.3.0, and is compiled from the changesets, not walked.
  • 18.2.0 — the first release that ships the Console and the @object-ui/* packages from this repository, at one version with @objectstack/*. 59 of its 231 changesets are declared breaking: 52 need you to act and 7 are converted by os migrate meta. Its upgrade checklist moves an 18.1.0 app to 18.2.0, and is compiled from the changesets, not walked.
  • 18.1.0 — the first minor, and a minor that breaks: 91 of its changesets are declared breaking (ruling A grades a non-protocol breaking change patch and a protocol narrowing minor). Its upgrade checklist moves an 18.0.0 app to 18.1.0, and was walked on 2026-10-24 from 18.0.0 on one small SQLite app.
  • 18.0.0 — the GA cut. Its upgrade checklist moves a 17.x app and its database to 18.0.0, and was walked from 17.7.0.

On this page