Upgrade guide — move between major versions

There are two upgrades on this platform, and they run on separate clocks:

Most upgrade questions are really the question which of these am I doing. You can do either one alone. A platform move does not rewrite your app, and republishing your app does not move the runtime.

The platform runtime

The platform ships as a single version-locked train: every @objectstack/* package shares one version number, and that number is the platform version.

Moving the tag

The official image is ghcr.io/objectstack-ai/objectstack, and its tags mirror @objectstack/cli versions: the exact X.Y.Z, plus the rolling X.Y, X and latest tags. Pin the exact version in production and move it deliberately:

# docker-compose.yml, or your orchestrator's manifest
image: ghcr.io/objectstack-ai/objectstack:17.7.0

On a host running the artifact directly under systemd, the same move is a file swap: replace the artifact and restart the service. Roll back by restoring the previous artifact.

See Self-hosting for both deployment shapes in full.

Moving the dependency pins

Not every deployment moves a tag. An app that consumes the platform as npm dependencies — @objectstack/* in its own package.json, which is the shape create-objectstack scaffolds — carries the platform version in its dependency tree and moves it there. There is no os command for this move; it is three steps you run yourself.

1. Bump every @objectstack/* dependency together, to the same version. The train is version-locked — every package on it shares one version number — so a partial bump produces a combination that was never built or released as a set. Include devDependencies: @objectstack/cli is the os binary that validates and builds your app, and a CLI left a release behind runs the previous release's author-time rules over your metadata.
2. Regenerate the lockfile, and commit it (pnpm install / npm install / yarn install). This is the step that actually moves the code. A project pinned to exact versions moves because step 1 edited the pins; a project on the scaffold's default ranges (^17.0.0) moves entirely here. Read whatever peer-dependency warnings this prints — the --frozen-lockfile install your CI runs skips resolution and will never print them.
3. Check the two protocol declarations your app ships — specVersion in objectstack.manifest.json, and engines.protocol in your defineStack manifest. Both name the protocol major, so a move inside one major leaves both alone, and a major boundary is where they change. Move them deliberately when you cross one; never edit them to silence a mismatch.

Then run the loop below — os validate before os build — because moving the pins can move the gate.

What the boot does when the database disagrees

Moving the runtime can leave the physical database shaped for the previous version. What happens next depends on which deployment shape you run.

The standing production policy is hands-off. Under NODE_ENV=production, automatic reconciliation is ignored and every divergence is warned about, on the assumption that an operator runs os migrate deliberately:

os migrate plan     # how the database has drifted, categorised safe / needs-confirm / destructive
os migrate apply    # applies the loosening changes
os migrate apply --allow-destructive   # the narrowing ones, once you have read the plan

The artifact-pinned boot is stricter, because there is nobody at a terminal: a container simply comes up carrying a different artifact than the one that shaped the database. On that path the boot applies safe and needs-confirm drift itself, and refuses to start on destructive drift, printing every change and the command that resolves it. Nothing is skipped silently — "shrug and serve" is the state that gate exists to delete. The refusal happens before the HTTP port binds, so a refused boot is a boot that never served traffic.

A runtime move can still force metadata edits

The table at the top of this page says a runtime move does not touch your metadata. That is true in the narrow sense — nothing rewrites your source files — and it is not the same claim as no metadata work is needed. The difference has been measured.

An application repository was upgraded across a single minor, 17.2.0 → 17.3.0, by a reader holding only this documentation, the CHANGELOG.md files inside the published npm tarballs, and the os CLI's own output. Moving the pins and restarting was not enough:

• os validate refused the stack, and so did os build. The release registered one more author-time rule — the count printed by os validate moved from 41 to 42 — and two objects that compiled on 17.2.0 stopped compiling. That is a build-stopping gate, not a warning.
• A lint family widened onto surfaces it had not read before. In that app the count went from zero findings to 429.
• A constraint that had been declared but inert started being enforced, so nine identifier fields acquired a unique index on the next migration.

None of that is a protocol-major event. It does not appear in the conversion window described below, and os migrate meta has nothing to replay for any of it — see "Nothing to migrate" is not "you are done". The only channel that carries these is the release's own checklist, under Per-release specifics.

When a platform move forces an app move

Each package declares the protocol major it was authored against, and the runtime checks that handshake first, before it loads anything:

manifest: {
  // ...
  engines: { protocol: '^17' },
}

The load path then converts old metadata shapes to the canonical current shape as it reads them, emitting a deprecation notice per conversion. That window is exactly one major wide. Metadata authored against the previous major loads and runs; a shape retired one major further back is rejected, and the rejection carries the fix — the old spelling, the new spelling, and the command that lists every site to edit.

The practical consequence:

• One major behind — it runs. You will see conversion notices in the boot log. Migrate at your convenience.
• Two or more majors behind — the load rejects the retired shapes. The metadata half is no longer optional, and it is the next section.

The metadata app

Your app is versioned by you, upgraded by you, and shipped as a compiled artifact. Upgrading it across one or more protocol majors is one command followed by your normal build.

One command covers every major you skipped

os migrate meta --from 16     # the major your metadata was authored against

--from is the major you wrote against, not the one you are going to. The command replays every step between that major and this runtime's, in order, in a single pass — so upgrading across skipped majors does not mean running it once per major, and does not mean reading several release checklists and merging them by hand:

The chain reaches back to protocol 16 — that floor is a release-policy decision, not an accident of what still exists. Below it the command refuses with a message naming the floor rather than half-migrating you.

Useful flags:

It reads your source and no database. (Its sibling, os migrate meta --stored, does the opposite — it rewrites one deployment's stored metadata rows and reads no config. The two are mutually exclusive.)

What it does not do — read the output

$ os migrate meta --from 17
Nothing to migrate — the metadata is already canonical for this range.

That split is the reason the per-major checklists below still matter: renames and retired keys the tool enumerates for you; decisions it cannot make for you stay yours. The run also ends by naming the per-deployment data migrations that remain (os migrate files-to-references, os migrate value-shapes, and friends) — scoped to the field classes your metadata actually declares. It reads no database, so that list is what is left to consider, never what this deployment has already done.

The loop

os migrate meta --from 16     # 1. read the mechanical change list and the to-dos
                              # 2. apply the edits (--write writes the ones it can
                              #    trace and lists the rest); resolve the to-dos
                              #    and the checklist items below
os validate                   # 3. the gate — schema, CEL predicates, widget bindings
os build                      # 4. compile to dist/objectstack.json
                              # 5. ship the artifact; restart
os migrate plan               # 6. reconcile the database to the new metadata

Step 3 is the real gate: os validate runs the same checks as os build but writes no artifact, which makes it the fast inner loop while you work through the to-dos. Full command reference in the CLI documentation.

Per-release specifics

Everything above is the mechanism. The contents of a given release — which keys were renamed, which defaults changed, which grant you now have to declare explicitly — live on that major's release page, written for app authors and compiled at release time.

Read the checklist for every release you are crossing, not only the one you are landing on — and that means every minor inside a major as well as every major boundary. A minor moves the runtime without moving your metadata's protocol major, so os migrate meta has nothing to replay for it; that is exactly why the minor's own accept-set tightenings, default flips and authorization narrowings have no other channel to reach you than the page below.

Only the v17 line is broken out per release. Each of its three minors shipped breaking changes under the repo's launch-window convention — which ships a breaking change as minor rather than major, so the version number is not the migration signal and the changelog entry is. Earlier majors' release pages carry one checklist per major, which is what those rows link to.

The release notes overview summarizes what each major changed.

What the installed artifact tells you, without a second worktree

The release pages are written for a human. The same delta ships inside the package, for your tooling: @objectstack/spec carries a spec-changes.json, and from the release that follows 17.4.0 on it carries a release section describing the release you actually installed — from → to at the package version, not at the protocol major.

# What did the release I just installed change?
jq '.release | {fromVersion, toVersion,
                added: (.added | length), removed: (.removed | length),
                converted: (.converted | length), migrated: (.migrated | length)}' \
  node_modules/@objectstack/spec/spec-changes.json

added and removed are the public exports that arrived and left, each one named — "./ai: AgentSchema (const)", the entry point followed by the export and its kind. converted and migrated are the ADR-0087 conversions and semantic migrations first registered in that release. The same file's perMajor records are unchanged and still answer the major-boundary question, and so does aggregate — for its converted and migrated, which are derived from the ADR-0087 registries across the whole from → to range.

⛔ But not for aggregate.added / aggregate.removed. Those come from the same one-release export diff as the section above, not from the major range the record is keyed by, so when they are filled the aggregate record carries a surfaceScope naming the exact pair they span:

jq '.aggregate | {from, to, surfaceScope,
                  added: (.added | length), removed: (.removed | length)}' \
  node_modules/@objectstack/spec/spec-changes.json

surfaceScope absent means that record claims no export diff at all and its added / removed are empty — the registry-only shape. ⛔ Read that as "this record does not say", never as "nothing was added between from and to", which is the same rule the release section states for itself below. A release whose aggregate arrays disagree with the two published tarballs, or carry no surfaceScope, does not publish.

The os CLI reads the same section, so a CI job does not have to know the file exists:

os validate --json | jq .specReleaseChanges

Three properties worth relying on:

• The section describes a release, not a major. Every entry in added arrived in toVersion and every entry in removed left in it. That is the one question the perMajor records cannot answer, and it is the question a minor upgrade asks.
• A missing section is not an empty one. The key is absent when the delta could not be computed — a release published before this section existed, or one whose predecessor shipped no export snapshot. os validate --json reports null in exactly those cases. ⛔ Do not read an absent section as "nothing changed"; read it as "this artifact does not say".
• It is verified against the artifacts before it ships. The release lane recomputes the delta from the previously published tarball and the one about to be published, and a release whose section disagrees with them does not publish. The numbers are as true as the two tarballs are.

The per-package changelogs are the exhaustive record

The release pages above are triaged, deliberately: a change is written up there when it can be reached from something an application ships or operates, and changes that move only the platform's own internals are left out. That triage is what makes a release page readable — 17.3.0 alone carries 862 changelog entries across the train — and it is also the page's limit.

The exhaustive record is the CHANGELOG.md shipped inside every published package, so you already have a copy of the ones that matter to you:

less node_modules/@objectstack/spec/CHANGELOG.md
less node_modules/@objectstack/cli/CHANGELOG.md
# …one per @objectstack/* package your app depends on

Read them whenever a release checklist does not explain what you are seeing, whenever you maintain a plugin or a driver against our internal contracts, and whenever you are crossing several releases at once. They are per-change, and they carry the reasoning and the migration for entries too narrow to reach a release page. On one measured documentation-only upgrade, these files — not the release pages — were where the answer to every question turned out to be, which is why this section is here rather than one line about two old majors. Curated notes for v10 and v11 were never backfilled at all, so for those two majors the changelogs are the only record there is.

What a major is allowed to change in the first place — which edits count as breaking, and the deprecation window a property must sit through before it can be removed — is the Backward Compatibility Policy.

Not this page

Upgrading an installed package — a template app or a third-party package already installed into a deployment — is a different operation with its own lifecycle (pre-check, plan, snapshot, execute, validate, commit or roll back). It is neither of the two halves above: it moves someone else's metadata inside your deployment. See the package upgrade protocol.