Upgrade from 0.2 to 0.3

This guide is for users migrating from 0.2.0-rc.1 to or evaluating 0.3.0. The stable release is available through GitHub Releases, npm, and PyPI; still verify the target version in the selected channel before installation.

Before upgrading

1. Commit or back up the application and record Node, Python, configuration, Session directory, and package versions.
2. Stop active CLI, Worker, and SDK processes.
3. Back up sessions/, .coremind/, and business-side effect receipts. Keep secrets only in environment variables.
4. Move direct dependencies on low-level model, message, or tool types to CoreMind public types.

Install and diagnose

For a source checkout, run at the repository root:

npm ci
npm run build:python-worker
npm run check

Upgrade all eight npm packages as one version family. Upgrade the Python wheel as a whole; never pair the new Python client with an old Worker. Then run:

coremind --version
coremind doctor coremind.yaml
coremind check coremind.yaml --profile strict

Compatibility and additive contracts

• Config remains schema v2 and Protocol requests remain v1. Permission modes, generic outcomes, and CLI exit codes are retained.
• RunResult.operation and RunResult.snapshot are authoritative evidence. JSON readers must tolerate additive fields, while TypeScript fixtures that construct RunResult manually must add the snapshot.
• The Python SDK requires its bundled Worker to advertise runSnapshot; mixed versions fail with protocol_capability_missing.
• Session migration creates .v3.backup, publishes through the versioned repository, and switches the stable public path last. Lossy migration fails closed and preserves the source.
• Large tool output enters .coremind/artifacts/; the model receives only a bounded preview and workspace-relative reference. Suspected credentials are never persisted as artifacts.
• TUI adds /artifacts and /context; /status includes recovery, compaction, artifacts, and evaluation.
• Lifecycle extensions expose only four events and require explicit trust, capability declarations, and grants. They are not an operating-system sandbox.
• Provider certification now requires seven live checks; older five-check evidence is not current certification.

Verify

Run the same business case through CLI, TypeScript, and Python and compare snapshot.runId, operation, outcome, metrics, and trace. A write case must also cover approval, checkpoint, diff, restore, Session resume, and abort.

Roll back

1. Stop all new-version processes and retain RunState, traces, artifacts, and external effect receipts as audit evidence.
2. Handle a lock only after proving that no writer is alive; never delete an active lock.
3. Restore the legacy Session from .v3.backup, then return the complete npm package family and Python wheel to 0.2.0-rc.1.
4. Never roll back one internal package in isolation or replay an external effect whose result is uncertain.

See the detailed Runtime Adapter, Session and recovery, and Context and Artifact migrations.