feat(migrations): add atomic checkpoint storage operator

.github/workflows/ci.yml

@@ -31,6 +31,9 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact source head
+        run: test "$(git rev-parse HEAD)" = "${{ github.event.pull_request.head.sha || github.sha }}"
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
@@ -58,6 +61,9 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact source head
+        run: test "$(git rev-parse HEAD)" = "${{ github.event.pull_request.head.sha || github.sha }}"
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
@@ -111,6 +117,9 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact source head
+        run: test "$(git rev-parse HEAD)" = "${{ github.event.pull_request.head.sha || github.sha }}"
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
@@ -122,8 +131,8 @@ jobs:
           prune-cache: true
       - name: Install locked dependencies
         run: uv sync --locked
-      - name: Run live checkpoint audit integration
-        run: uv run pytest -q tests/test_checkpoint_audit_integration.py -m integration
+      - name: Run live checkpoint storage integration
+        run: uv run pytest -q tests/test_checkpoint_audit_integration.py tests/test_checkpoint_migration_operator_integration.py -m integration
 
   container-builds:
     name: Container builds
@@ -138,9 +147,12 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact source head
+        run: test "$(git rev-parse HEAD)" = "${{ github.event.pull_request.head.sha || github.sha }}"
       - name: Validate Compose configuration
         run: docker compose config >/dev/null
       - name: Build component image
         run: docker build --tag pg-llm-batch:ci .
       - name: Build PostgreSQL image
-        run: docker build --tag pg-llm-batch-postgres:ci docker/postgres
+        run: docker build --tag pg-llm-batch-postgres:ci docker/postgres

AGENTS.md

@@ -237,3 +237,36 @@ add CODEOWNERS-based merge gates until multiple independent maintainers exist.
   deterministic transaction, event-time, tenant, validation, bounded-read,
   migration, rollback, immutability-trigger, compatibility, and documentation
   tests.
+
+## Checkpoint migration operator contract
+
+- Keep the **Checkpoint migration operator** opt-in through
+  `init-checkpoint-storage`; `init-db` must remain the backward-compatible core
+  schema command.
+- Load, bounded-read, strict UTF-8 decode, and SHA-256 identify both
+  `0007_result_stream_checkpoints` and
+  `0008_result_checkpoint_audit_events` before database access. Each file is
+  limited to 1 MiB plus one detection byte and the SQL body remains private.
+- Obtain the fixed two-key transaction-level advisory lock with
+  `pg_advisory_xact_lock`, then execute migration 0007 before migration 0008 in
+  one PostgreSQL transaction and issue one commit only after both succeed.
+- A second-migration failure must roll back the first migration from the same
+  invocation and release the transaction-level advisory lock automatically.
+- Emit only immutable migration identifiers, bounded byte counts, SHA-256, and
+  schema version after commit. SHA-256 is change-identification evidence and
+  **not a signature**, provenance statement, remote attestation, or release
+  authority.
+- Preserve the independent `apply_result_checkpoint_schema()` and
+  `apply_result_checkpoint_audit_schema()` helpers for hosts that intentionally
+  own separate transactions. Do not add a migration ledger, downgrade, or
+  destructive retained-evidence rollback to this bounded operator.
+- Keep standalone operation and modular MSA use independent of `naruon` and
+  `contextual-orchestrator`. Advisory locking coordinates cooperating package
+  operators; it is not authorization and does not constrain an administrator or
+  unrelated SQL client.
+- Maintain 100% production statement, branch, and public-docstring coverage with
+  deterministic input-bound, order, transaction, rollback, live PostgreSQL,
+  concurrency, compatibility, CLI, documentation, and body-free evidence tests.
+- Update README, architecture, ADR, operator documentation, doctoring, and
+  CHANGELOG whenever migration ordering, locking, evidence, failure, or
+  compatibility semantics change.

ARCHITECTURE.md

@@ -303,6 +303,49 @@ the surrounding transaction later committed. The host owns telemetry retention,
 access control, alerting, collector availability, database-client
 instrumentation, and any correlation outside this confidential package boundary.
 
+## Checkpoint schema migration operator boundary
+
+`init-checkpoint-storage` is an explicit opt-in operator command for existing
+PostgreSQL volumes. It preserves `init-db` as the core-schema command and keeps
+the independent `apply_result_checkpoint_schema()` and
+`apply_result_checkpoint_audit_schema()` helpers compatible for hosts that
+intentionally own separate transactions.
+
+Before database access, the operator bounded-reads, strict UTF-8 decodes, counts,
+and SHA-256 identifies `0007_result_stream_checkpoints` and
+`0008_result_checkpoint_audit_events` in that exact order. Each file is limited
+to 1 MiB plus one oversize-detection byte. The loaded SQL remains private; public
+migration descriptors contain only configured identifiers, positive bounded byte
+counts, and lowercase SHA-256.
+
+After both inputs are valid, one package-owned PostgreSQL transaction obtains the
+fixed two-key `pg_advisory_xact_lock`, executes migration 0007, executes migration
+0008, and issues one commit. A migration 0008 failure rolls back migration 0007
+from the same invocation and transaction end releases the lock automatically.
+The advisory lock serializes cooperating package operators; it is not an
+authorization mechanism and does not constrain an administrator, owner,
+superuser, or unrelated SQL client.
+
+The CLI emits one canonical JSON report only after commit. It excludes DSNs,
+credentials, SQL bodies, tenants, checkpoint values, provider payloads, audit
+rows, and raw database exception text. SHA-256 is deterministic
+change-identification evidence and is not a signature, provenance claim, remote
+attestation, publication authority, or integrated-release approval.
+
+No migration ledger, downgrade path, destructive retained-evidence rollback,
+provider credential, LLM key, `naruon`, or `contextual-orchestrator` dependency is
+introduced. Fresh Docker data directories retain their ordered initialization
+scripts; existing PostgreSQL volumes use the explicit operator command.
+
+```text
+init-checkpoint-storage
+    ├─ bounded load: 0007_result_stream_checkpoints
+    ├─ bounded load: 0008_result_checkpoint_audit_events
+    ├─ pg_advisory_xact_lock(PGLM, BATH)
+    ├─ execute 0007 → 0008
+    └─ one commit → bounded migration identity JSON
+```
+
 ## Modular interoperability
 
 CWL hosts such as `contextual-orchestrator` and `naruon` supply tenant context
@@ -327,7 +370,10 @@ place local PostgreSQL effects and `save_in_transaction()` on the same caller
 cursor; cross-system effects remain host-owned recovery boundaries. Hosts that
 choose the audited store gain transaction-coupled accepted-save evidence but
 still own identity authorization, retention, export, and stronger tamper-proof
-controls where required.
+controls where required. Hosts may use the checkpoint migration operator as a
+standalone deployment primitive and retain its bounded descriptors in a
+change-management record, but must not reinterpret them as tenant authorization
+or release provenance.
 
 ## Verification boundary
 
@@ -373,5 +419,10 @@ attributes, storage-agnostic operation spans, seconds-based nonnegative duration
 confidential failure classification, explicit Error status without descriptions,
 Unset success status, disabled exception recording, and preservation of
 application results and exception identity during ordinary tracer, meter, span,
-status, and clock failures. Final merge evidence must be regenerated against the
-integrated base; successful stacked-base runs are not reusable release evidence.
+status, and clock failures. Checkpoint migration operator tests prove strict
+bounded input, canonical identities, load-before-connect, one transaction-level
+advisory lock, exact 0007→0008 order, one commit, second-migration rollback,
+concurrent lock waiting, body-free JSON, unchanged `init-db`, and 100% production
+statement, branch, and public-docstring coverage. Final merge evidence must be
+regenerated against the integrated base; successful stacked-base runs are not
+reusable release evidence.

CHANGELOG.md

@@ -9,6 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Explicit opt-in `init-checkpoint-storage` operator for existing PostgreSQL
+  volumes. It bounded-reads, validates, and SHA-256 identifies
+  `0007_result_stream_checkpoints` and
+  `0008_result_checkpoint_audit_events` before database access, obtains one
+  fixed two-key `pg_advisory_xact_lock`, executes both migrations in canonical
+  order inside one transaction, and issues one commit only after both succeed.
+  Failure in migration 0008 rolls back migration 0007 from the same invocation.
+  Success output contains only stable migration identifiers, byte counts,
+  SHA-256, and schema version; the digest is change-identification evidence, not
+  a signature, attestation, provenance statement, or release authority.
+  `init-db` and the two independent migration helpers remain compatible. Live
+  PostgreSQL tests prove rollback and advisory-lock serialization. No migration
+  ledger, downgrade, destructive retained-evidence rollback, version bump, or
+  release is included.
 - Optional append-only checkpoint accepted-save audit evidence through
   `AuditedPostgresBatchResultCheckpointStore` and
   `llm_result_checkpoint_audit_events`. Successful save calls append a fixed

CLAUDE.md

@@ -214,3 +214,35 @@
 - Maintain test-first transaction, event-time, validation, bounded-read,
   migration, rollback, trigger, compatibility, documentation, and 100%
   production statement/branch/public-docstring coverage.
+
+## Checkpoint migration operator invariants
+
+- Keep the **Checkpoint migration operator** explicit and opt-in through
+  `init-checkpoint-storage`; never expand `init-db` to install optional checkpoint
+  objects silently.
+- Bounded-read, strict UTF-8 decode, and SHA-256 identify
+  `0007_result_stream_checkpoints` and
+  `0008_result_checkpoint_audit_events` before database access. The maximum
+  package read is 1 MiB plus one oversize-detection byte per file.
+- Acquire the fixed two-key transaction-level advisory lock with
+  `pg_advisory_xact_lock`, execute 0007 before 0008 in one transaction, and issue
+  one commit only after both succeed.
+- A second-migration failure must roll back the first migration from the same
+  invocation. Transaction exit must release the transaction-level advisory lock;
+  do not add a persistent lock table or migration ledger for this slice.
+- Public and CLI evidence contains only configured migration IDs, bounded byte
+  counts, SHA-256, and schema version after commit. SHA-256 is
+  change-identification evidence and **not a signature**, provenance, remote
+  attestation, or release approval.
+- Preserve source compatibility for `apply_result_checkpoint_schema()` and
+  `apply_result_checkpoint_audit_schema()`. They remain available to hosts that
+  intentionally coordinate independent transactions.
+- Treat advisory locking as cooperative serialization, not authorization. An
+  administrator, superuser, owner, or unrelated SQL client remains outside the
+  lock assurance boundary.
+- Preserve standalone and modular MSA use without requiring `naruon`,
+  `contextual-orchestrator`, provider credentials, or an LLM key.
+- Maintain 100% production statement, branch, and public-docstring coverage with
+  strict red-green-refactor tests for bounded input, exact order, one lock, one
+  transaction, one commit, rollback, concurrency, compatibility, CLI output,
+  documentation, and body-free diagnostics.

README.md

@@ -19,6 +19,9 @@ core and relicensed under Apache-2.0. See [`NOTICE`](NOTICE) for provenance.
   bootstrap transport.
 - **Durable provider reconciliation.** Opt-in lifecycle clients persist ordered
   remote state across restarts and worker failover.
+- **Atomic checkpoint upgrades.** Existing PostgreSQL volumes can install the
+  durable checkpoint and accepted-save audit schemas with one explicit,
+  serialized, all-or-nothing operator command.
 - **Standalone or tenant-scoped operation.** Existing single-tenant consumers
   retain a compatible facade, while shared-table MSA deployments can use a
   trusted tenant-qualified identity and forced PostgreSQL row-level security.
@@ -64,6 +67,12 @@ Optional durable projection:
 
     TenantDurableBatchAPIClient
         └─ (tenant_scope, endpoint_alias, remote_batch_id)
+
+Optional checkpoint schema operator:
+    init-checkpoint-storage
+        ├─ 0007_result_stream_checkpoints
+        ├─ 0008_result_checkpoint_audit_events
+        └─ pg_advisory_xact_lock → one transaction → one commit
 ```
 
 | Capability | Module |
@@ -74,6 +83,8 @@ Optional durable projection:
 | Incremental bounded result and error records | `pg_llm_batch/result_streaming.py` |
 | Durable standalone and tenant lifecycle clients | `pg_llm_batch/durable_client.py` |
 | Tenant-qualified lifecycle persistence and reads | `pg_llm_batch/db.py` |
+| Durable checkpoint persistence and audit | `pg_llm_batch/checkpoint_store.py`, `pg_llm_batch/checkpoint_audit.py` |
+| Atomic checkpoint schema planning and application | `pg_llm_batch/checkpoint_migrations.py` |
 | Opt-in OpenTelemetry operations | `pg_llm_batch/observability.py` |
 | KV configuration and encrypted secrets | `pg_llm_batch/config.py` |
 | Canonical PostgreSQL DDL | `pg_llm_batch/schema.sql` |
@@ -107,6 +118,23 @@ python -m pg_llm_batch config set-secret \
   gateway_api_key.default sk-your-key
 ```
 
+`init-db` applies only the backward-compatible core batch schema. To upgrade an
+existing PostgreSQL volume for durable result checkpoints and accepted-save audit
+evidence, run the explicit opt-in command:
+
+```bash
+python -m pg_llm_batch init-checkpoint-storage
+```
+
+The command bounded-reads and SHA-256 identifies
+`0007_result_stream_checkpoints` and
+`0008_result_checkpoint_audit_events` before database access, obtains one
+transaction-level `pg_advisory_xact_lock`, applies both in one transaction, and
+issues one commit. A failure in the second migration rolls back the first. The
+success JSON contains migration identifiers, byte counts, and SHA-256 only;
+SHA-256 is change-identification evidence and not a signature or attestation.
+See the [checkpoint storage migration operator guide](docs/checkpoint-storage-migrations.md).
+
 Production gateway destinations require HTTPS. Plain HTTP is accepted only for
 explicit loopback development endpoints. URLs containing user information,
 queries, fragments, whitespace, controls, backslashes, or invalid ports fail
@@ -381,10 +409,18 @@ PG_LLM_BATCH_TEST_DSN=postgresql://pgllm:pgllm@localhost:5432/pgllm \
 Protected CI verifies Python 3.10, 3.12, and 3.14; compilation; Ruff; 100%
 production statement and branch coverage; 100% production docstrings; lockfile
 freshness; source and wheel packaging; Compose validation; component and
-PostgreSQL container builds; SAST; and security scanning.
+PostgreSQL container builds; live checkpoint migration rollback and advisory
+serialization; SAST; and security scanning.
 
 ## Documentation
 
+- [`docs/checkpoint-storage-migrations.md`](docs/checkpoint-storage-migrations.md)
+  — atomic existing-volume checkpoint/audit upgrade, rollback, evidence, and
+  concurrency contract.
+- [`docs/adr/0010-atomic-checkpoint-schema-operator.md`](docs/adr/0010-atomic-checkpoint-schema-operator.md)
+  — decision record for ordered transaction-level advisory locking.
+- [`docs/doctoring/checkpoint-migration-operator.md`](docs/doctoring/checkpoint-migration-operator.md)
+  — standards mapping, exact verification boundary, and APA 7 references.
 - [`docs/remote-batch-lifecycle.md`](docs/remote-batch-lifecycle.md) — standalone
   and tenant lifecycle operations, RLS trust boundary, migration, rollback, and
   recovery.