# Changelog

<!-- markdownlint-disable MD024 -->

All notable changes to this project will be documented in this file.

The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)**
and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0.0.html)**.

---

## [Unreleased]

---

## [0.3.1] - 2026-05-27

### Added

- Added `accountable_record.boundary` as the typed input-boundary layer for
  parsed TOML and JSON data.
- Added TOML boundary helpers for establishing `dict[str, object]` and
  `list[object]` shapes from parsed TOML input.
- Added JSON boundary helpers for establishing trusted object-shaped parsed JSON
  input.
- Added shared utility modules for reusable loading and version helper behavior.
- Added decision records clarifying generated/export artifact treatment,
  contract-resolution versus AR element locks, and the boundary between the
  generic `se-contract-kit` verifier frame and AR-specific checks.

### Changed

- Replaced loose `Any`-based parsed-data handling with explicit
  `dict[str, object]` boundary typing across the staged pipeline.
- Updated manifest-schema, repository-profile, identity, contract, source,
  element, catalog, export, resolution, generated-artifact, and transition code
  to narrow opaque parsed input through boundary helpers before use.
- Updated JSON and TOML readers so parsed data is validated at the file boundary
  before downstream stage logic consumes it.
- Updated scalar/shape helpers to return newly validated typed collections
  instead of returning partially narrowed raw parser output.
- Tightened strict Pyright compatibility by removing remaining `Unknown` and
  partially unknown parsed-data flows.
- Updated generated-artifact collection to reject valid non-object JSON as a
  malformed stage input rather than allowing later attribute-access failures.
- Clarified current contract behavior: stage 080 generated element validation
  uses the stage 060 export artifact set in this contract version, with a
  distinct `data/generated/` tree reserved for a future contract-versioned
  change.

### Fixed

- Fixed strict Pyright/Pylance failures caused by raw `json.loads()`,
  `tomllib.load()`, `dict[str, Any]`, bare `dict`, and raw
  `isinstance(value, dict)` narrowing.
- Fixed parser-boundary cases where valid non-object JSON could reach code that
  expected an object.

---

## [0.3.0] - 2026-05-26

### Added

- Added the staged Accountable Record pipeline spine.
- Added `PipelineRunContext` for fixed run input, including target repository
  selection.
- Added immutable `PipelineState` for accumulated diagnostics and stage outputs.
- Added explicit stage artifact models for staged pipeline outputs.
- Added decorator-registered stage transforms for `s010` through `s090`.
- Added the canonical staged CLI command: `accountable-record run`.
- Added `run sNNN` behavior where `run s040` runs `s010` through `s040`.
- Added `run all` behavior for the full staged pipeline.
- Added convenience aliases for catalog, export, resolution, generated-artifact,
  and documentation stages.
- Added target-aware identity validation using `SE_MANIFEST.toml`.
- Added contract-context validation.
- Added source-material validation.
- Added verifiable element declaration validation.
- Added normalized catalog construction and validation.
- Added machine-readable export validation.
- Added resolution-lock validation.
- Added generated-artifact validation.
- Added documentation planning/render validation.
- Added diagnostic vocabulary with concern-based AR diagnostic codes.
- Added shared diagnostic specification support for stage-local diagnostic
  definitions.
- Added validation support for both the verifier repository and target
  Accountable Record repositories.

---

## Notes on Versioning and Releases

This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

- **MAJOR** versions indicate breaking changes.
- **MINOR** versions indicate backward-compatible additions or clarifications.
- **PATCH** versions indicate editorial fixes, documentation updates, or
  non-normative changes.

Versions are defined by git tags of the form `vX.Y.Z`.
Tagged releases are the authoritative source of version state.

Documentation and badges, where present, should reference the latest tagged
release.

## Release Procedure (Required)

Follow these steps exactly when creating a new release.

### Task 1. Update release metadata (manual edits)

1.1. `CITATION.cff` - update `version` and `date-released`
1.2. CHANGELOG.md: add section, move unreleased entries, update links
1.3. `pyproject.toml` - update `fallback-version` (near the end of the file)

### Task 2. Validate

```shell
uv sync --extra dev --extra docs --upgrade

uv run se-manifest validate-manifest --strict

uv run accountable-record write-lock
uv run accountable-record verify-lock
uv run accountable-record run all

git add -A
uvx pre-commit run --all-files
uv run python -m pyright
uv run python -m pytest
uvx ruff check .
uvx ruff format .

git add -A
uvx pre-commit run --all-files
```

### Task 3. build

```shell
uv build
uvx twine check dist/*
```

### Task 4. Commit, push, tag

```shell
git add -A
git commit -m "Prepare X.Y.Z"
git push -u origin main
```

Verify actions run on GitHub. After success:

```shell
git tag vX.Y.Z -m "X.Y.Z"
git push origin vX.Y.Z
```

### Task 5. Verify tag consistency

```shell
uv run se-manifest validate-manifest --require-tag
```

Confirms CITATION.cff version matches the pushed git tag.
Run this after `git push origin vX.Y.Z`; it will fail before that point.

## Only As Needed (delete a tag)

```shell
git tag -d vX.Z.Y
git push origin :refs/tags/vX.Z.Y
```

## Links

[Unreleased]: https://github.com/structural-explainability/accountable-record-py/compare/v0.3.1...HEAD
[0.3.1]: https://github.com/structural-explainability/accountable-record-py/releases/tag/v0.3.1
[0.3.0]: https://github.com/structural-explainability/accountable-record-py/releases/tag/v0.3.0
