Add native numeric evidence and Assay companion conformance

[cirsteve]

Summary

• Release paa-contracts 0.3.0 with native numeric evidence verdicts; older
  envelope versions remain string-only.
• Add the Assay scalar-quality companion contract and numeric fixtures.
• Bind the positive fixture to the actual inbound_reply_surfacing evaluator,
  correct its canonical content address, and strengthen required lineage refs.
• Exercise companion ranges/types, declaration identity, negative cases, and
  full fixture conformance.

This is Assay's schema/conformance prerequisite, not a runtime dependency of
the Assay verifier: RankOneLabs/assay#1

Validation

• 766 runtime/conformance tests and 89 contracts-package tests passed.
• Ruff, strict source mypy, wheel and source builds passed.
• Corrected fixture also passed paadotdev's real content-address and semantic
  validators.

Summary by CodeRabbit

• New Features

  • Added draft 0.3.0 evidence records with native numeric verdicts while retaining string verdict compatibility.
  • Added an Assay scalar quality payload schema supporting verdicts from 0 through 1.
  • Added a published evidence example demonstrating a numeric quality verdict.

• Bug Fixes

  • Improved validation for verdict types, lineage fields, schema references, and published declarations.

• Documentation

  • Updated package and runtime-conformance documentation for the new evidence-record capabilities and compatibility rules.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Essentials

Run ID: c0d3b7ef-49e7-49db-870b-7a23278c34ec

📥 Commits

Reviewing files that changed from the base of the PR and between b3f9fd9 and ef37850.

⛔ Files ignored due to path filters (1)

• packages/paa-contracts/uv.lock is excluded by !**/*.lock

📒 Files selected for processing (2)

• conformance/test_operating_records.py
• package.json

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

📝 Walkthrough

Walkthrough

The evidence record schema advances to 0.3.0-draft. Version 0.3.0 supports numeric verdicts, while versions 0.1.0 and 0.2.0 retain string-only verdicts. New fixtures and conformance tests validate schemas, lineage, declarations, and numeric bounds.

Changes

Evidence record contract

Layer / File(s)	Summary
Record schema and fixtures schemas/paa-evidence-record.schema.json, examples/runtime-conformance/payload-schemas/assay-scalar-quality.schema.json, examples/runtime-conformance/evidence-records/..., examples/runtime-conformance/invalid/evidence-cases.json	The 0.3.0 schema accepts numeric or string verdicts. Earlier schema versions remain string-only. Positive and negative fixtures cover numeric bounds, lineage, and invalid verdict types.
Conformance validation conformance/test_evidence_integrity.py, conformance/test_operating_records.py, conformance/test_corpus_integrity.py	Conformance tests validate companion schemas, numeric verdict limits, required lineage, published declarations, retained schema versions, and updated corpus counts.
Package release updates packages/paa-contracts/pyproject.toml, packages/paa-contracts/src/paa_contracts/__init__.py, packages/paa-contracts/README.md, packages/paa-contracts/tests/test_contracts.py, pyproject.toml, README.md, package.json	The package version and conformance dependency requirement advance to 0.3.0. Documentation and fixture-count assertions describe the new contract.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to ef378

The reviewed changes are mergeable with normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 5 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main changes: native numeric evidence verdicts and Assay companion conformance.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 5 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/native-numeric-evidence

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

🟡 Changes recommended

Moderate unresolved compatibility, lockfile, and package-version findings remain.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR releases paa-contracts 0.3.0 with version-gated numeric evidence verdicts and adds Assay scalar-quality companion conformance.

Changes:

• Adds native numeric verdict support while preserving legacy envelopes.
• Adds Assay schemas, fixtures, lineage checks, and negative cases.
• Updates documentation, metadata, dependencies, locks, and conformance tests.

File summaries

File	Summary
uv.lock	Updates the workspace contract version. Moderate finding (1 vote): regenerate the package-local lock as well.
schemas/paa-evidence-record.schema.json	Adds v0.3 numeric verdict support. Moderate finding (1 vote): add a v0.3 string positive case.
README.md	Documents contract version changes.
pyproject.toml	Raises the conformance dependency minimum.
packages/paa-contracts/tests/test_contracts.py	Updates corpus count assertions.
packages/paa-contracts/src/paa_contracts/__init__.py	Bumps the package version.
packages/paa-contracts/README.md	Documents Assay fixtures and v0.3 behavior.
packages/paa-contracts/pyproject.toml	Sets the package release to 0.3.0. Moderate findings (2 votes each): regenerate the nested lockfile and align npm package metadata to 0.3.0.
examples/runtime-conformance/payload-schemas/assay-scalar-quality.schema.json	Adds the Assay companion schema. Moderate finding (1 vote): add v0.1/v0.2 companion-validator negatives.
examples/runtime-conformance/invalid/evidence-cases.json	Adds numeric verdict negative cases.
examples/runtime-conformance/evidence-records/evidence/paa/772600716f1b221836cd5f0732e7633e38edb6903e48f463dbfb4c97f848672a/evidence.json	Adds the numeric Assay evidence fixture.
conformance/test_operating_records.py	Tests retained versions and numeric evidence.
conformance/test_evidence_integrity.py	Tests companion schemas and declaration identity.
conformance/test_corpus_integrity.py	Updates corpus totals.

Review details

Suppressed comments (2)

examples/runtime-conformance/payload-schemas/assay-scalar-quality.schema.json:11

• This v0.3-only const is a compatibility boundary, but no test exercises it. The new v0.1/v0.2 numeric cases validate only the base schema via violations("evidence", ...), while companion tests always start from a v0.3 record; removing this guard would leave the suite green and allow an old envelope through this companion schema. Add companion-validator negatives for v0.1 and v0.2 records.

        "record_schema": { "const": "paa-evidence-record/0.3.0-draft" },

schemas/paa-evidence-record.schema.json:147

• The new union is exercised only by the numeric v0.3 fixture. Existing string fixtures are v0.1/v0.2, and the companion test intentionally rejects strings, so no test proves that a v0.3 string remains valid; changing this to type: number would leave the current tests green while violating the documented compatibility contract. Add a v0.3 string positive/base-validation case.

          "type": ["string", "number"],

• Files reviewed: 13/14 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cirsteve]

Addressed the approved review findings in ef37850:

• Aligned @paadev/paa-contracts npm metadata with the Python contract release at 0.3.0.
• Removed the obsolete package-local lockfile; the workspace lock remains authoritative. The reported package-directory install failure was not reproduced: uv lock --check --offline succeeds from packages/paa-contracts both before and after removal.
• Added a positive base-schema conformance test protecting v0.3 string verdict compatibility.

Validation: 767 runtime/conformance tests and 89 contract-package tests pass; lint and runtime type checks pass; npm pack dry-run identifies version 0.3.0; git diff --check passes.

The suppressed claim that removing the companion's v0.3 const would admit older envelopes was checked and is incorrect: the base schema requires string verdicts for older versions, while the scalar companion requires numbers. Those envelopes remain rejected even without that const. The guard itself remains unchanged. No review threads were automatically resolved.