# Migration Notes

## `0.1.x` to `0.2.0`

`0.2.0` introduces the Stable Production baseline for multi-team internal platform usage.

### New Stable Surface

- Prefer imports from [`logos_adk`](../logos_adk/__init__.py) and the modules listed in
  [`logos_adk.version`](../logos_adk/version.py) for semver-governed usage.
- Avoid importing private implementation modules unless the docs explicitly mark them as stable.

### Observability Changes

- Every emitted span and metric now carries:
  - `framework.version`
  - `framework.api_version`
  - `agent.config.path`
  - `agent.config.fingerprint`
- Error spans now include `exception_type` when the root run fails.
- Native observability dashboards and alert rules now cover provider timeouts, circuit breaker openings, and state backend failures.

### Reliability Changes

- Task queues now support:
  - idempotency keys
  - retry budgets
  - dead-letter recording
  - replay of failed work

### Security Config Changes

New optional `security` fields:

- `output_max_length`
- `input_pii_action`
- `output_pii_action`
- `audit_redact_pii`
- `audit_retention_days`

New optional `scaling.task_queue` fields:

- `max_retries`
- `idempotency_ttl_seconds`

Existing configs remain valid.

## `0.2.x` to `0.3.0`

`0.3.0` adds public-framework quality artifacts for external users.

### New Artifacts

- release notes and public release history in `CHANGELOG.md`
- upgrade workflow commands under `logos-adk upgrade`
- project generators under `logos-adk project`
- RBAC roles for serve-layer principals

### Recommended Actions

- prefer `logos_adk` root imports and the documented stable modules for application code
- validate RBAC roles instead of only raw scopes where appropriate
- review `docs/public-api.md`, `docs/upgrade-guide.md`, and `docs/reference-architectures.md`
