# OpenRath v2 API and Maintenance Policy

This policy is part of the Stable v2.0.0 release. It defines public contract
classifications, compatibility expectations, and the maintenance process.

## Stability levels

- **Stable:** documented public Python symbols, persisted v2 schemas, stable
  error codes, and migration CLI. Breaking changes require a new major version.
- **Preview:** explicitly labelled new API, deployment-helper, or adapter SDK
  surfaces. Changes are documented with release notes and migration guidance.
- **Experimental:** explicitly labelled research integrations and extension
  hooks. They may change in a minor release and must not be required for the
  durable Run, security, or storage contracts.
- Public v2 additions carry an explicit classification in release notes or
  this policy. Internal modules and names beginning with `_` remain internal.

The Agent Server OpenAPI document is the contract source for `/v1` operations
and records each operation's stability classification.

OpenRath v2.0.0 itself is a Stable release. Per-surface classifications describe
compatibility commitments for individual APIs; they do not change the release
status of v2.0.0.

For `2.0.0`, the Python v1 façade remains supported and the Agent Server follows
the compatibility process defined here.

## Action and object authorization

Authentication alone grants no access. Tokens carry explicit action grants;
`*` is an intentionally privileged reference-only grant. The service enforces
the following minimum actions:

| Resource | Read | Mutate or control |
| --- | --- | --- |
| Assistant | `assistant.read` | `assistant.create` |
| Session | `session.read` | `session.create` |
| Run | `run.read` | `run.create`, `run.cancel`, `run.resume` |
| Interrupt | `interrupt.read` | `interrupt.decide` |
| Feedback | — | `feedback.create` |
| Memory | `memory.search` | `memory.put`, `memory.delete` |
| Metrics | `metrics.read` | — |

Run, Session, Interrupt, Feedback, and Memory operations also verify tenant and
project scope. A user-scoped memory namespace cannot name another principal
unless the token has `memory.admin`. Cross-scope objects are returned as not
found to avoid disclosing their existence. Control-plane mutations emit
redacted security audit events when an `AuditSink` is configured.

## SemVer and deprecation

- Patch releases contain compatible fixes, security updates, and documentation.
- Minor releases may add compatible functionality.
- Breaking Stable API or persisted-schema changes require a new major release.
- Stable APIs are deprecated before removal. The default notice is two minor
  releases and at least six months, unless retaining the API would preserve an
  actively exploitable vulnerability.
- Database migrations are forward-only and additive during the rollback
  window. Application rollback precedes removal of old columns or tables.

## v1 compatibility

The v1 Python façade remains available through its published maintenance
window. v1 JSONL Sessions import as non-resumable historical evidence because
they do not contain a durable program counter or effect outcome. Maintenance
updates and timelines are published through release notes.

## Security reporting

Report suspected vulnerabilities privately through the repository's GitHub
Security Advisory flow. Do not open a public issue with exploit details,
credentials, tenant data, or unredacted traces. Maintainers should acknowledge,
triage severity, coordinate a fix and advisory, and publish remediation and
affected-version information. Secrets found in reports must be rotated rather
than copied into tests or logs.

## Release integrity

Releases publish compatibility and migration notes, reproducible image
digests, dependency locks, a CycloneDX SBOM, security scans, and benchmark
profiles. Tag and artifact publication remain explicit repository-owner
actions.

Source:
[tagged API governance document](https://github.com/Rath-Team/OpenRath/blob/v2.0.0/deploy/docs/api-governance-v2.md).