setspec 0.2.0__tar.gz

setspec-0.2.0/.editorconfig

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_size = 4
+max_line_length = 100
+
+[*.{toml,yml,yaml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = off
+
+[Makefile]
+indent_style = tab

setspec-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,150 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install ruff
+      - run: ruff format --check .
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install ruff
+      - run: ruff check .
+
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: mypy src tests
+
+  boundaries:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: lint-imports
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python-version }}" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" --cov --cov-report=xml
+
+  tests-314-early-warning:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.14" }
+      # Deliberately unlocked: this job resolves from the ranges in `pyproject.toml`, because
+      # pinning versions that have no 3.14 wheels would defeat the purpose of an early warning
+      # (requirements/README.md).
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not live and not performance"
+
+  coverage:
+    needs: [tests]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" --cov --cov-report=term-missing --cov-fail-under=95
+
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m contract
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        # gitleaks scans *history*, and `actions/checkout` fetches a single commit by default.
+        # For a push it is handed `<first-pushed>^..<last-pushed>`, so the parent of the first
+        # pushed commit has to be in the object store; in a depth-1 clone it is not, and git
+        # answers "unknown revision", which the action reports as exit code 1. It fails the same
+        # way whether or not a secret exists, so a green run would not have meant anything either.
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install pip-audit
+      # Audit the locked set, not the job's own environment: a bare `pip-audit` here inspects an
+      # environment containing only pip-audit itself and reports nothing (Security Standards §11).
+      - run: pip-audit --require-hashes -r requirements/ci.lock
+      - run: pip-audit --require-hashes -r requirements/release.lock
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      # The same pinned build chain the release uses, so a wheel that builds here is the wheel
+      # that ships: `--no-isolation` takes the backend from this lock rather than re-resolving
+      # hatchling from the index at build time.
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+
+  install-check:
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - run: pip install dist/*.whl
+      - run: python -c "import setspec"
+      # The marker is easy to add to the source tree and easy to leave out of the built wheel, and
+      # the failure is silent: a consumer's `mypy --strict` treats every import from an unmarked
+      # package as untyped rather than erroring. Asserted against the *installed* wheel.
+      - name: py.typed ships in the wheel
+        run: |
+          python -c "
+          import pathlib, setspec
+          marker = pathlib.Path(setspec.__file__).parent / 'py.typed'
+          assert marker.is_file(), 'py.typed missing from the installed wheel'
+          "

setspec-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  workflow_dispatch:   # manual TestPyPI dry run; see publish-testpypi below
+
+permissions:
+  id-token: write   # required for PyPI Trusted Publishing
+  contents: write   # required to create the GitHub release
+
+jobs:
+  release:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment: pypi   # must match the Environment name set on the PyPI trusted publisher
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - run: pip install "dist/$(ls dist | grep .whl)[dev]"
+      - run: pytest -m "not live and not performance"
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  publish-testpypi:
+    # Manual only, via Actions -> Release -> Run workflow. Packaging and Release Standards §6
+    # requires a successful TestPyPI publish ahead of a package's first real release; 0.2.0 is
+    # this package's first published version, so run this once before tagging v0.2.0. Later
+    # releases may skip it, or use it again as a dry run.
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    # No `environment:` here, matching the other package repositories. The OIDC claim must match
+    # the trusted publisher exactly: declaring an environment the TestPyPI publisher was not
+    # configured with fails the exchange. Add one only alongside configuring it there.
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - run: pip install "dist/$(ls dist | grep .whl)[dev]"
+      - run: pytest -m "not live and not performance"
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

setspec-0.2.0/.gitignore

@@ -0,0 +1,100 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# ---- Packaging / build backends ----
+pip-wheel-metadata/
+share/python-wheels/
+
+# ---- Testing / coverage ----
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+*.py,cover
+htmlcov/
+nosetests.xml
+.hypothesis/
+
+# ---- Type checking / linting ----
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pytype/
+
+# ---- Virtual environments ----
+.venv/
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+.python-version
+
+# ---- Distribution / dependency locking ----
+# requirements/*.lock is deliberately NOT ignored. The lock files are committed
+# inputs: CI and release jobs install from them with --require-hashes (Packaging
+# and Release Standards §4, Security Standards §11), so an ignored lock file
+# means a checkout that cannot build.
+
+# ---- Editors / OS ----
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ---- Suite runtime state (this component's local data) ----
+# The application writes to XDG paths at runtime (~/.config, ~/.local/share,
+# ~/.local/state per Master Architecture §1.2), never inside the repository.
+# These entries only guard against a developer pointing XDG_* at the repo
+# during local testing.
+.local/
+.config/
+*.sqlite3
+*.sqlite3-journal
+*.sqlite3-wal
+*.sqlite3-shm
+/data/
+/logs/
+/backups/
+/artifacts/
+/exports/
+
+# ---- Secrets ----
+# Per Security Standards §8: secrets are never committed. Config files may
+# only name where a secret comes from (*_env / *_file), never the value.
+.env
+.env.*
+*.key
+*.pem
+secrets.toml
+
+# ---- Node-free JS assets (MirrorWall consumers may still use a local tool) ----
+node_modules/
+
+# ---- Build artifacts from docs generation ----
+docs/api/openapi-v1.json.tmp

setspec-0.2.0/.importlinter

@@ -0,0 +1,27 @@
+[importlinter]
+root_packages =
+    setspec
+# The forbidden modules below are external distributions, not submodules of setspec, so the graph
+# has to include external packages for the contracts to be able to see them at all.
+include_external_packages = True
+
+[importlinter:contract:no-application-imports]
+name = SetSpec must not import applications
+type = forbidden
+source_modules =
+    setspec
+forbidden_modules =
+    freeweight
+    loadcoach
+    ideapress
+
+[importlinter:contract:no-capability-packages]
+name = SetSpec must not import capability packages
+type = forbidden
+source_modules =
+    setspec
+forbidden_modules =
+    modelrack
+    sweatmeter
+    weightsdb
+    mirrorwall

setspec-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks

setspec-0.2.0/CHANGELOG.md

@@ -0,0 +1,247 @@
+# Changelog
+
+All notable changes to `setspec` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
+[Semantic Versioning](https://semver.org/), pre-1.0 per
+packaging and release standards §3.
+
+## [Unreleased]
+
+### Added
+- **`metric_key` on `MetricValueFields`.** The model declared value, unit, aggregation, direction,
+  sample count and dispersion — and nothing saying *which metric it is*. Both
+  `BenchmarkResultFields.metrics` and `BenchmarkRunSummaryFields.aggregate_metrics` carry sequences
+  of it, so a consumer receiving a run summary got a list of numbers it could not attribute, chart,
+  compare across runs, or check for the metric it was looking for. Required rather than optional:
+  an unattributable number is not a measurement. Constrained to lower snake case, because a metric
+  key is an identifier consumers match on and `ttft_ms` / `TTFT_ms` from two producers would be two
+  metrics to every reader and one to every author.
+
+  The payload stays at schema **1.0**: the suite is pre-freeze, no consumer outside it reads these
+  documents yet, and results produced during development are not being retained. After M3 the same
+  change would be a minor.
+
+- **The release workflow can publish, and can rehearse first.** `release.yml` gained the
+  `publish-testpypi` job every other package repository has — manual only, via *Actions → Release →
+  Run workflow* — because packaging and release standards §6 requires a successful TestPyPI publish
+  ahead of a package's **first** real release, and `0.2.0` is this one. The `release` job gained
+  `environment: pypi`, which must match the Environment name configured on the PyPI trusted
+  publisher; without it the OIDC exchange has nothing to match and the publish is rejected.
+- **`requirements/ci.lock`, `release.in` and `release.lock`**, hash-pinned — required by packaging
+  standards §4 and present in `baseaicore`, `modelrack` and `sweatmeter`, absent here. Every
+  blocking CI job now installs the locked toolchain and then `pip install . --no-deps`; the build
+  jobs use the release lock with `--no-isolation`, so the wheel CI checks is produced by the same
+  pinned backend as the wheel that ships. Without them every run re-resolved, and a new `ruff` or
+  `mypy` release could change the result with no commit to explain it.
+
+  The 3.14 early-warning job stays unlocked on purpose: pinning versions that have no 3.14 wheels
+  would defeat the point of an early warning.
+
+  Verified by installing both locks under `--require-hashes` into a clean interpreter and running
+  every CI job against them — format, lint, mypy, import-linter, tests, coverage, contracts,
+  `pip-audit` and the workflow's own build and `twine check`.
+- Capability vocabulary **1.1**: the reserved root `user`, whose specializations (`user.<slug>`)
+  carry FreeWeight's user-authored goal evidence (ADR-0032 §1). One root added once closes the
+  question permanently — the existing open-ended specialization rule accepts every goal any user
+  will ever write, so no future rubric is a vocabulary change. `RESERVED_ROOTS` is exported
+  alongside `CAPABILITIES`.
+- `benchmark.goal_pack` and `benchmark.calibration_report` (`setspec.goal.v1`), both registered in
+  `SUPPORTED_SCHEMAS` and listed in `DRAFT_SCHEMAS`. The calibration report is a payload in its own
+  right rather than a field group on evidence because it is meaningful precisely when **no**
+  evidence was emitted: a goal below its calibration gate produces no evidence record at all
+  (ADR-0032 §3).
+- The goal-sourced field group on `capability.evidence`: `judge_validity_factor`, `goal_hash`,
+  `goal_pack_version`, `score_method_mix`, `judge_set`, `calibration` and `uncalibrated`
+  (ADR-0032 §5). Every field is optional and absent on a non-goal record, and
+  `judge_validity_factor` defaults to `1.0` — so **no previously valid document changed meaning
+  and no existing confidence value changed**, which a regression test asserts directly.
+
+### Changed
+
+- A bare reserved root is now refused by `validate_capability` and reported `False` by
+  `is_known_capability`. `user` is a namespace, not a capability: a payload claiming
+  `capability_id: "user"` has lost the identity that is the entire point of the namespace.
+  This affects no term that existed before 1.1.
+- **Forward-compatibility leniency narrows, as it must.** A payload declaring
+  `vocabulary_version: "1.1"` with a root this build does not know was previously accepted — `1.1`
+  was a newer minor than `1.0`, so the spec §13 exception applied. It is now refused, because
+  `1.1` is this build's own vocabulary and there is nothing newer about it. This is what forward
+  compatibility *means* rather than a regression: leniency exists to carry terms from a future
+  this build has not seen, and it evaporates for a version this build has arrived at. A payload
+  declaring `1.2` or later is unaffected. Producers on `1.1` must emit roots that exist at `1.1`.
+
+### Fixed
+- **Coverage measured a directory nothing imports.** `[tool.coverage.run] source` named
+  `src/setspec`, the source *path*, while CI installs the built distribution — so the moment the
+  jobs stopped using an editable install, coverage reported **0 %** and failed the 95 % floor for a
+  reason unrelated to the tests. It now names the importable package, with `[tool.coverage.paths]`
+  folding the source tree and site-packages into one name, matching `baseaicore`. Both install
+  modes report 100 %.
+- **`pip-audit` in CI was auditing nothing.** A bare `pip-audit` inspects the job's own
+  environment, which contained only `pip-audit` itself, so that job had been reporting clean on an
+  empty set. It now audits both locks.
+- **`install-check` did not verify that `py.typed` reaches the wheel.** The marker is easy to add
+  to the source tree and easy to leave out of the build, and the failure is silent: a consumer's
+  `mypy --strict` treats an unmarked package as untyped rather than erroring. Asserted against the
+  installed wheel now. (It does ship — this closes the hole, it does not fix a break.)
+
+- The package ships a `py.typed` marker, matching every other implemented package in the suite
+  (`baseaicore`, `modelrack`, `sweatmeter`). Without it, `mypy --strict` in a consuming repository
+  cannot see this package's types at all and treats every import from it as untyped.
+
+## [0.2.0] — 2026-08-23
+
+Phase 2 of the [development plan](docs/packages/setspec/development-plan.md): provisional
+benchmark and evidence payloads. FreeWeight now has concrete models to build against —
+`model.identity`, `machine.profile`, `benchmark.result`, `benchmark.run_summary`,
+`capability.evidence` and `benchmark.evidence_bundle` — all registered in `SUPPORTED_SCHEMAS` at
+`1.0` but explicitly **draft**: Phase 4 may still reshape a field once FreeWeight has produced real
+results against it, per this phase's own known risk (guessing the result shape before its producer
+exists).
+
+### Added
+- `setspec.model.v1`: `ModelIdentityOut`/`In`, the exchange form of `baseaicore.ModelIdentity` plus
+  a `ModelDescriptor` snapshot. `canonical_id` and `identity_confidence` are carried on the wire
+  but recomputed from the identity triple and checked on every construction — a producer that
+  materializes them inconsistently is rejected, not silently trusted.
+- `setspec.machine.v1`: `MachineProfileOut`/`In`, `GpuProfileFields`, `StorageDeviceFields` — a
+  field-for-field mirror of `baseaicore.MachineProfile`, including which fields are required
+  versus optional. `machine_fingerprint` is carried but deliberately **not** re-verified, matching
+  `MachineProfile`'s own documented reason: its inclusion policy may change after the profile was
+  written, and a historically valid profile must still reconstruct exactly as stored.
+- `setspec.benchmark.v1`: `BenchmarkResultOut`/`In` and `BenchmarkRunSummaryOut`/`In`, built from
+  Machine Identity §6's minimum
+  provenance set — the one place a result's required shape was already normative before any
+  FreeWeight code existed. `runtime_profile_hash` is recomputed from the embedded profile and
+  checked, the same reasoning as `canonical_id`. Every other hash-shaped field (`manifest_hash`,
+  `prompt_subset_hash`, `reproducibility_fingerprint`) is validated only as non-empty: this package
+  cannot yet compute FreeWeight's own hashes, and guessing a format risks rejecting the first real
+  result over a formatting nuance instead of the risk Phase 2's tests actually target.
+- `setspec.capability.v1`: `CapabilityEvidenceOut`/`In` and `EvidenceBundleOut`/`In`, reproducing
+  ADR-0022 §1's normative field table
+  verbatim. `measured_at` later than `computed_at` is rejected as incoherent — the schema-level
+  enforcement of ADR-0022 §2's rule that recomputing evidence must not make it look fresher.
+- `setspec.provenance`: `EnvironmentFields`, the provider/driver/OS block shared by
+  `benchmark.result`, `benchmark.run_summary` and `capability.evidence`. It gets a neutral home
+  for the same reason `setspec.metrics` has one: a sub-model used by two payload types belongs to
+  neither, and had it lived in `benchmark/v1.py`, the day `benchmark.result` needed a changed
+  environment shape whoever edited that class would silently have changed `capability.evidence`
+  v1 too — a frozen contract mutating because someone edited a different payload's module.
+- `setspec.envelope.DRAFT_SCHEMAS`: which registered schemas are still provisional. The
+  development plan asks for draft status to be visible *in the API*, not only in prose. It is a
+  separate set rather than a `"1.0-draft"` version string because the latter would have to be
+  parsed by `SchemaVersion`, whose contract is that a version is exactly two integers and
+  non-canonical spellings are refused — loosening that permanently, to describe a condition that
+  ends at Phase 4, would weaken the version format every frozen schema depends on. Freezing a
+  schema is one deletion from this set.
+- `benchmark.result` gains the provenance Machine Identity §6
+  calls "optional but strongly recommended, and required for any benchmark whose numbers depend on
+  them": `measurement_class` (cold/warm/cache_reused/n-a), `telemetry_summary` (peak VRAM,
+  peak/mean power, max temperature, throttle flag) and `raw_response_ref` — plus `error_code`,
+  `error_text`, `completed_cases` and `total_cases` from FreeWeight's own `run_tests` row. These
+  had to be declared rather than left out: the writer half of each pair forbids unknown keys, so a
+  field this schema does not name is one a producer *cannot emit at all*. A memory or energy
+  benchmark — whose numbers §6 says depend on telemetry — could not have exported a conformant
+  result, and a `failed` result had no field in which to say why it failed.
+- `RuntimeProfileFields.profile_hash`, a public property delegating to
+  `baseaicore.RuntimeProfile`. A consumer needs the hash for the same reason a producer does —
+  two results are comparable only if their profiles hash identically — and previously the only
+  way to it was a private helper reached across class boundaries behind two `noqa: SLF001`
+  waivers.
+- `setspec.vocabulary`: `CAPABILITIES`, `CAPABILITY_VOCABULARY_VERSION` (`"1.0"`),
+  `validate_capability`, `is_known_capability`. A specialization validates against its **root**
+  rather than needing individual enumeration — `coding.rust` is accepted the moment `coding` is
+  known — and an unknown ID is accepted leniently only when the payload declares a newer *minor*
+  of the vocabulary's current major, never across a major.
+- `setspec.base`: `WireSequence`, an ordered-collection field type alongside `WireEnum`. Strict
+  mode validates the *input Python type*, and a bare `tuple[T, ...]` under `strict=True` accepts
+  only an actual `tuple` — never the `list` every JSON array deserializes to — so every
+  ordered-collection field in Phase 2 needed this to accept a real document at all.
+- `Aggregation` gains `P50`, `RATIO` and `RAW`, matching aggregation kinds FreeWeight's own data
+  model already names that Phase 1's set did not cover.
+
+### Changed
+- `PayloadDefinition` now sets `extra="allow"` itself, rather than leaving pydantic's default
+  (`extra="ignore"`). A definition nested inside another payload — `model: ModelIdentityFields`
+  inside `CapabilityEvidenceFields` — is typed as the bare definition, not a generated `Out`/`In`,
+  so its own default governs unknown-key handling regardless of which half of the *outer* pair is
+  in use; `ignore` would have silently dropped an unrecognized field from every nested object in
+  both directions, which is precisely the loss ADR-0009 rule 4
+  exists to prevent. This is additive for every Phase 1 payload, which had no nested fields to
+  expose the gap.
+
+### Fixed
+- `completed_cases` greater than `total_cases` is now rejected, the same arithmetic honesty the
+  timestamp ordering checks already enforced: "12 of 10 cases done" is a producer bug, and a
+  consumer rendering it as a percentage would show one above 100%.
+- A garbled sentence in `setspec.machine.v1`'s module docstring, left by an edit, made the
+  explanation of why `machine_fingerprint` is *not* re-verified unreadable — the one place this
+  package carries a hash-shaped field without checking it, so the reason it is deliberate rather
+  than an oversight is exactly the thing that had to be legible.
+- A test fixture (`tests/unit/test_payloads_benchmark.py`) embedded one module-level dict by
+  reference into every result it built; a test that mutated its own copy was actually mutating the
+  shared fixture in place, corrupting every test built after it in file execution order. It passed
+  under Python 3.13 by luck of `pytest-randomly`'s seed and failed outright under 3.14, whose
+  ordering exposed it — the bug was reference aliasing, not a Python-version incompatibility.
+  Fixed by building the dict fresh on every call; verified stable across five randomized runs on
+  both interpreters.
+
+## [0.1.0] — 2026-08-23
+
+Phase 1 of the [development plan](docs/packages/setspec/development-plan.md): the envelope,
+versioning and serialization core. Any payload can now be wrapped, versioned, validated,
+serialized canonically and rejected correctly when its major version is unsupported. No payload
+type is registered yet — Phase 2 adds the first ones against this machinery, which is why
+`SUPPORTED_SCHEMAS` ships empty rather than pre-declaring shapes that do not exist.
+
+### Added
+- `envelope`: `SchemaEnvelope`, `GeneratorInfo`, `SchemaVersion`, `SUPPORTED_SCHEMAS`,
+  `load_envelope`, `dump_envelope`. The reader policy of
+  ADR-0009 rule 3 is enforced in both directions: a
+  newer minor within a supported major is accepted with its unknown fields intact, an unsupported
+  major is refused with `SchemaVersionUnsupported` naming the schema, the received version and
+  every supported one — and is never partially parsed.
+- `serialization`: canonical JSON via `baseaicore.canonical_json` (delegated, not reimplemented, so
+  a payload hashes identically to every other hashed structure in the suite); `MeasurementField`,
+  mapping `UNSUPPORTED ↔ "unsupported"` and refusing `null`, bools and numeric strings; and
+  `TimestampField`, RFC 3339 UTC at millisecond precision with naive datetimes rejected.
+- `serialization`: `parse_json` with size and depth guards applied *before* the parser runs, so a
+  hostile document is refused by a named limit rather than by a `RecursionError`. Limits are the
+  module constants `MAX_PAYLOAD_BYTES` (16 MiB, matching API Standards §10) and
+  `MAX_PAYLOAD_DEPTH` (64); callers may pass tighter ones per call.
+- `base`: `PayloadDefinition`, `StrictPayload`, `PreservingPayload` and `payload_models`, which
+  generates the `Out`/`In` pair required by
+  ADR-0009 rule 4 from one definition — so a writer
+  cannot emit a field it does not know and a reader cannot strip one. The round-trip contract is
+  asserted per class, never across the pair.
+- `base`: `WireEnum`, for enum fields that must accept their own string values from a parsed
+  document while the bases otherwise validate strictly.
+- `metrics`: `MetricValueOut`/`MetricValueIn` and `Aggregation`. The
+  ADR-0016 §6 invariants are structural rather than
+  advisory: a real value must report at least one supported sample, an unsupported value must
+  report none, and dispersion needs at least two — so `value=0.0, sample_count=0` cannot be
+  serialized at all.
+- `errors`: `SchemaVersionUnsupported` (code `SCHEMA_VERSION_UNSUPPORTED`), with
+  `baseaicore.ValidationError` re-exported so callers import both from one place.
+
+### Changed
+- Coverage floor raised from 85 % to 95 %, the number [spec §18](docs/packages/setspec/spec.md)
+  and every phase's acceptance criteria actually state; the scaffold shipped 85 in both
+  `pyproject.toml` and the CI job. Current coverage is 100 %.
+- `.importlinter`: the second contract listed no forbidden modules at all, and its inline
+  `root_packages`/`source_modules` values were read character by character — `lint-imports` failed
+  with `Could not find package 's'` and therefore checked nothing. Rewritten as newline-separated
+  lists with `include_external_packages`, and renamed from `no-sibling-packages` to
+  `no-capability-packages`: `modelrack`, `sweatmeter`, `weightsdb` and `mirrorwall` sit in the
+  layer *above* SetSpec, so they were never siblings.
+
+### Fixed
+- `ruff format --check .` failed on nine vendored documents under `docs/`. ruff 0.16 formats Python
+  code blocks inside markdown, and those files are byte-identical copies of the suite's master
+  documents shared with nine other repositories — reformatting them here would desync every copy.
+  `docs/` is now excluded from ruff instead.
+
+### Security
+- `pytest` moved from `>=8,<9` to `>=9.0.3,<10`, excluding PYSEC-2026-1845 (vulnerable
+  `/tmp/pytest-of-{user}` handling, affecting pytest through 9.0.2). Matches the pin BaseAiCore
+  already moved to; the suite passes unchanged on pytest 9.