Skip to content

feat(reporting): support definition-driven official finality - #1925

Open
rachitm022 wants to merge 39 commits into
mainfrom
rmatani/ai-22659-support-definition-driven-official
Open

rachitm022 wants to merge 39 commits into
mainfrom
rmatani/ai-22659-support-definition-driven-official

Conversation

@rachitm022

Copy link
Copy Markdown
Collaborator

Why

Reliable Reporting definitions can select one of three official-finality policies, but the Python SDK previously synthesized official closes from source timing metadata. That made policy ownership ambiguous and allowed scheduled rereads to create revisions even when content had not changed.

This implements AI-22659.

What changed

  • Retain the exact selected report-definition policy: source_final, contractual_cutoff, or stabilized. The SDK never selects or defaults a policy.
  • Require authoritative provider evidence for source_final, and verified full-period snapshots for cutoff/stabilized promotion.
  • Retain bounded, account-scoped scheduled observation history in memory and PostgreSQL. Unchanged scheduled rereads advance evidence without creating duplicate snapshot revisions.
  • Make official writes proof-only, restart-safe, concurrency-safe, and compatible with historical readable official revisions.
  • Preserve historical verification-key identities when no policy is selected.
  • Document policy ownership and rolling-deployment requirements.
  • Keep the package-grain Reliable Reporting 1.2 offering snapshot-only: it requires no official close and never becomes official merely because time elapsed.

Verification

  • Linux Python 3.10–3.13 native suites passed; Python 3.12 coverage was 92.22%.
  • PostgreSQL 16 Core: 2,973 passed. Production: 1,357 passed.
  • Final reporting regression selection: 2,253 passed.
  • Final focused finality/admission suite: 494 passed, 245 skipped on macOS; PostgreSQL variants passed in the Linux/PG runs.
  • make lint typecheck-all, configured Pyright, mypy, Black, generated-code, schema, packaging, installed-wheel, and Python↔TypeScript storage interoperability checks passed.

Known custom-store limitations

  • A pre-upgrade custom observation/checkpoint publisher that discarded scheduled history cannot always reconstruct the scheduled anchor after a tracked manual observation. Such publishers should implement bounded history or migrate checkpoint state before enabling explicit close.
  • Exact contractual replay comparison requires retained winning evidence. Core stores that retain no observation manifest can verify policy-valid evidence but cannot byte-compare a changed, still-valid source cutoff; the immutable revision itself is not changed.

Native memory and PostgreSQL stores retain the required evidence and are covered by restart, concurrency, migration, and replay tests.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant