Upgrade Tenchi safely

Tenchi is pre-1.0. It follows semantic versioning with pre-1.0 semantics: minor releases may change public APIs while the framework finds the cleanest durable shape.

What is protected today

Tenchi gives each public surface an explicit compatibility boundary:

• Public Python signatures are checked as part of every release. Intentional changes appear in the changelog so you can identify required application updates before upgrading.
• OpenAPI, durable job messages, application tools, and evaluation policy have compatibility reports you can run against your own historical snapshots.
• Structured CLI results and the coding-agent MCP server share one versioned schema. Application-tool manifests and application MCP results use separate versioned schemas. Contract-driven change plans also carry their own schema version and a content-derived plan ID. A breaking wire-format change receives a new version rather than silently changing an existing one.
• tenchi.toml protects the evidence your repository requires before a change is complete. tenchi verify rejects a change that weakens a requirement relative to the selected historical commit.

These guarantees make changes visible and reviewable. They do not promise that every pre-1.0 release is source-compatible.

Upgrade safely

1. Read the release entry in CHANGELOG.md.

2. Upgrade Tenchi in a branch and refresh the lockfile. Before running tenchi verify for its receipt, update .gitignore for caches, logs, coverage output, and local databases that project commands are expected to create. Do not ignore source, snapshots, lockfiles, or configuration.

3. Run tenchi check to verify formatting, lint, types, tests, architecture, and the current OpenAPI, job-message, application-tool, and evaluation-policy snapshots.

4. Compare OpenAPI with the same route target and metadata used to create the snapshot:

   shell

   uv run tenchi openapi --diff openapi.json

   The command discovers the route module's literal OPENAPI_* declarations; pass explicit metadata flags only when overriding that convention.

5. If the application has durable jobs, run tenchi jobs --diff jobs.json against the pre-upgrade snapshot.

6. If it has application tools, run tenchi tools --diff tools.json against the pre-upgrade snapshot.

7. If it has evaluations, run tenchi eval snapshot --diff evaluations.json against the pre-upgrade snapshot.

8. Review application wiring, tenchi.toml, and generated-code convention changes. Do not weaken verification requirements to make the upgrade pass.

9. Update snapshots only after accepting all compatibility reports.

10. Rerun tenchi check with the accepted snapshots.

11. Run tenchi verify --base-ref <pre-upgrade-ref> to produce one final receipt against the pre-upgrade commit.

Pin a compatible minor range or an exact version according to the application's risk tolerance. Production applications should not upgrade framework versions implicitly during deployment.

Deprecation metadata

Contract deprecation is part of the API itself. Use deprecated=True while an operation remains available, or provide a timestamp. Add sunset= when callers need a concrete removal date. Tenchi emits the lifecycle metadata in OpenAPI and response headers.

What will gate 1.0

Tenchi should reach 1.0 after its contract, response, client, context, and composition APIs have been exercised by several independently maintained applications and can remain stable across normal framework evolution.

The bar is not a large feature checklist. It is confidence that the small core has earned its abstractions and that users can upgrade predictably.