Stability and releases

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

Every change on main runs formatting, linting, strict Pyright, framework tests, standalone application tests, architecture checks, exact OpenAPI and application-tool snapshots, and compatibility analysis against historical baselines.

The repository also snapshots public module signatures. An accidental API change fails CI; an intentional one must update the snapshot and changelog.

Agent-facing JSON has explicit compatibility boundaries. Structured CLI results and the coding-agent MCP server share one versioned schema, and CI verifies that their schemas remain identical. Application-tool manifests and the application MCP adapter each use their own version and retained schema snapshots. Breaking or unknown changes require a new versioned snapshot while the previous baseline remains unchanged.

These checks make change deliberate. 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.

3. Run tenchi check to verify formatting, lint, types, tests, architecture, and the current OpenAPI, 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 \
     --routes app.server.routes:api_routes \
     --title my_app \
     --version 0.1.0 \
     --diff openapi.json

   Also pass the snapshot's --description and --security values when the application configures them.

5. Run tenchi tools --diff tools.json against the pre-upgrade snapshot.

6. Run tenchi eval snapshot --diff evaluations.json against the pre-upgrade snapshot.

7. Review application wiring and generated-code convention changes.

8. Update snapshots only after accepting all compatibility reports.

9. Rerun tenchi check with the accepted snapshots.

10. 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.