Changelog & Versioning

Versioning policy

ObjectOS follows Semantic Versioning: MAJOR.MINOR.PATCH.

All @objectstack/* packages release together with a synchronized version number — they're tested as a matrix, not independently.

Compatibility matrix

Support windows

Critical security fixes are backported to the current and previous major. Everything else lands on main.

Release notes

Released ObjectOS versions and their CHANGELOG entries are published at:

• npm: @objectstack/runtime
• GitHub: github.com/objectstack-ai/objectos/releases
• Source CHANGELOG: CHANGELOG.md
• Long-form release notes: RELEASE_NOTES.md

Subscribe to releases on GitHub to get notified.

Recent highlights

9.x — current release train

ObjectOS One and the bundled server now ship on @objectstack 9.7.0. The runtime boot contract is unchanged from 8.0 — createStandaloneStack still takes the same artifact, environment, and database settings — so an 8.0 deployment rolls forward without config changes. The author-facing surface is what moved:

• Analytics datasets are the single author surface (9.0, breaking) — dashboard widgets, reports, and list-charts now bind a semantic dataset (defineDataset(...)) and select dimensions/measures by name. The old inline query fields (object/valueField/aggregate on widgets, objectName/columns/groupingsDown on reports, xAxisField/yAxisFields on list-charts) were removed. Migration: move the inline query into a defineDataset and reference it by name. ChartTypeSchema also dropped 8 variant types that only rendered as their base (stacked-bar→bar, spline→line, bubble→scatter, …).
• Stricter build-time validation (9.6–9.7) — os compile now fails on bare field references (amount instead of record.amount), unknown CEL functions, and wrong flow-value interpolation syntax, each with a did-you-mean hint. A stack that previously "built but was silently wrong" now fails loudly — re-run os compile after upgrading and fix what it flags.
• Number-field formulas compute mixed arithmetic (9.7) — record.amount / 100 and record.price * 2 now evaluate instead of silently yielding null; the / 100.0 float-literal workaround is no longer needed.
• Object-level REST gating, now enforced (ADR-0049) — an object's apiEnabled: false removes it from the REST surface, and an apiMethods whitelist restricts which operations are reachable. Previously parsed but not enforced.
• Package documentation as metadata + book navigation (9.3–9.6) — src/docs/*.md register as doc metadata; the book element (ADR-0046) declares a derived-membership navigation spine, served at GET /api/v1/meta/book/:name/tree with audience gating.
• os package install (9.3) — install a package into a running runtime from a catalog id or an inline air-gapped artifact, authenticating with --email / --password.
• Approvals (9.3) — send-back-for-revision (maxRevisions, default 3), jobs-backed SLA auto-escalation, list search/pagination, and session-less bilingual approve/reject confirm links.
• Inbound webhook flow triggers (9.3) — a type: 'api' flow mounts an HMAC-verified POST /api/v1/automation/hooks/:flowName/:hookId endpoint with idempotent, queue-backed ingestion.
• Notification retention defaults on (9.5) — notification history auto-prunes at 90 days; set the messaging retentionDays: 0 to keep history forever.
• CLI bundles AI provider SDKs (9.0) — OpenAI-compatible providers (DeepSeek, DashScope, SiliconFlow, OpenRouter, Cloudflare) work out of the box on a globally-installed CLI.

One flow-authoring behavior change to note: a create_record node's outputVariable now holds the created record object (was the bare id), so update {var} references that expected an id to {var.id}.

8.0.x

ObjectOS One and the bundled server shipped on @objectstack 8.0.1.

• MCP over Streamable HTTP — every deployment can act as a network-reachable Model Context Protocol server. Opt in with OS_MCP_SERVER_ENABLED=true; the endpoint is served at /api/v1/mcp with fail-closed auth (anonymous requests are rejected). The plugin was renamed @objectstack/plugin-mcp-server → @objectstack/mcp.
• Self-serve API keys — POST /api/v1/keys mints a show-once sys_api_key. The REST data and metadata APIs (/api/v1/data, /api/v1/meta) now authenticate API keys through the same verifier as MCP, running under the key owner's permissions and record-level security.
• Field-level conditional rules — visibleWhen, readonlyWhen, and requiredWhen are enforced server-side by ObjectQL, not just in the form UI.
• Reusable RLS read filter — security.getReadFilter(object, context) exposes the record-access read scope; analytics datasets, dashboards, and reports bridge to it and fail closed when the scope cannot be applied.
• Standalone host stack — the runtime ships a single-tenant createStandaloneStack host; the 7.x cloud-connected, hostname-routed createObjectOSStack wrapper was removed. A cloud deployment now points OS_ARTIFACT_FILE at a published artifact URL.

5.0 — project → environment rename (shipped)

The runtime concept formerly called Project was renamed to Environment throughout. Affected:

• CLI flags: --environment / -e
• HTTP paths: /api/v1/environments/:environmentId/...
• Headers: X-Environment-Id
• Env vars: OS_ENVIRONMENT_ID (OS_PROJECT_ID kept as a deprecated alias)
• DB columns: environment_id
• JSON schemas: EnvironmentArtifact

Upgrading

See Upgrade and Rollback for the mechanical steps. Pre-flight:

1. Read the CHANGELOG entry for every minor between your current and target version.
2. Run os diff <old-artifact> <new-artifact> to surface breaking schema changes.
3. Run os doctor against the target version.
4. Bring up one canary instance before rolling the fleet.
5. Have a rollback plan for both the image tag and the artifact version (they roll independently).

Reporting regressions

If a patch or minor breaks something previously working, file a bug at github.com/objectstack-ai/objectos/issues with the version you upgraded from / to. We treat regressions as the highest-priority class of bug.