refactor(results): use semantic result application identifiers

ARCHITECTURE.md

@@ -3,11 +3,20 @@
 ## Deployment boundary
 
 `pg-llm-batch` remains independently deployable and embeddable. PostgreSQL owns
-configuration, encrypted secrets, token counting, JSONL payloads, and durable
+configuration, secret storage, token counting, JSONL payloads, and durable
 provider lifecycle state. Provider HTTP behavior remains behind
 `BatchAPIClient`, while host services may inject credential, observation-order,
 and lifecycle-persistence seams without changing provider semantics.
 
+Protected `SecretStore` does **not** make encryption-at-rest mandatory. A supplied
+Fernet key encrypts stored values; without one, the current compatibility path
+base64-obfuscates values unless the caller explicitly sets
+`require_encryption=True`. Mandatory Fernet policy, migration of historical
+unencrypted rows, key rotation/recovery, and external key-custody evidence remain
+the buyer/security gap tracked by #121 and the active config/secret source owner.
+Do not describe the protected product as encryption-required until that contract
+is normally integrated and released.
+
 ## Durable lifecycle tenancy
 
 `DurableBatchAPIClient` is the backward-compatible standalone facade.
@@ -55,6 +64,56 @@ Rollback to the former two-column key is unsafe until an operator proves that no
 The packaged schema and Docker initialization schema are maintained as exact
 mirrors and must be reapplied successfully more than once.
 
+## Reconciliation orchestration boundary
+
+Protected `main` contains bounded reconciliation primitives, not a package-owned
+automatic worker. `reconcile_batch_candidates()` executes one finite
+scheduler-independent provider pass. Its protected contract explicitly leaves
+candidate discovery, scheduling, tenant authorization, and any cross-process
+lease to the host. Durable candidate discovery, PostgreSQL advisory single-flight,
+and caller-owned result/checkpoint application are separate primitives; their
+presence must not be described as an autonomous reconciliation service.
+
+Issue #102 remains the buyer/operability gap for composing those primitives into
+a bounded automatic loop with crash/restart recovery, durable terminal-work
+retirement, content-free operator evidence, and realistic high-cardinality
+acceptance. A future loop must preserve minimal PostgreSQL transactions: reserve
+or read the minimum durable state, commit or roll back before provider/model
+network work or retry backoff, and open a new bounded transaction only for the
+next durable transition. Session-advisory coordination remains transient and
+must not be represented as a durable lease or as distributed exactly-once
+delivery.
+
+The active reconciliation source slices remain separately owned by their
+canonical PRs/issues, including candidate validation, bounded database result
+materialization, sweep evidence, and Result Application. This documentation
+records the protected capability boundary only; it does not transfer their
+runtime/test authority into #324 or authorize a competing scheduler branch.
+
+## Diagnostic disclosure boundary
+
+`check_health()` is an operator-facing diagnostic report, not a public-safe
+serialization contract. Protected `main` currently preserves backend `detail`
+values and maps a database failure to `detail=str(exc)`, so that internal report
+can contain lower-layer PostgreSQL diagnostics. The HTTP `/healthz` path does
+not expose that report directly: `serve_healthz()` passes it through
+`public_health_report()`, which emits only the fixed required component names and
+boolean readiness states.
+
+The standalone `health` CLI currently prints the unprojected `check_health()`
+report. Its output must therefore be treated as operator-only and must not be
+represented as safe for untrusted logs, tenant-visible telemetry, public HTTP,
+or other user-facing surfaces. Issue #203 owns the remaining runtime hardening:
+the CLI needs a bounded content-free projection or equally strict coded
+diagnostic contract while preserving readiness exit semantics and useful
+operator failure classification. DSNs, credentials, certificate/private-key
+material, SQL text, provider content, arbitrary exception strings, and backend
+connection diagnostics must not become public diagnostic evidence.
+
+This section records the protected capability boundary only. It does not move
+`health.py` or CLI runtime/test authority into #324; source work for #203 still
+requires the invocation-scoped writer/path census before mutation.
+
 ## Logical restore execution
 
 `restore_postgres_logical_backup()` is a bounded direct-SQL restore seam. The
@@ -70,6 +129,26 @@ Post-restore metadata mismatch is fail-closed and must be treated as unsafe
 because the SQL transaction may already have committed. This seam does not
 complete isolated schema/RLS/PITR acceptance.
 
+## Result application boundary
+
+Checkpointed result application is a package-owned domain service. Internally,
+its ubiquitous language is `transaction_cursor`, `checkpointed_record`,
+`record_effect`, `record_applied`, and `result_checkpoint`. The released
+`apply_checkpointed_result_in_transaction(cursor, checkpoint_store,
+consumer_name, item, apply_record)` keyword signature and the public
+`ResultApplicationOutcome(applied, checkpoint)` dataclass field/introspection
+shape remain compatibility adapters because renaming them would be a released
+source/serialization break. The adapter immediately translates to/from a
+private semantic outcome model. Additive `.record_applied` and
+`.result_checkpoint` properties expose the semantic vocabulary without changing
+historical `dataclasses.fields` or `dataclasses.asdict` output.
+
+The service preserves the same transaction and replay invariants: the local
+record effect and checkpoint save occur under the caller-owned transaction,
+exact replay skips the effect, checkpoint regression fails closed, and the
+scoped cursor is revoked when synchronous effect execution ends. This naming
+boundary changes no provider protocol or database schema.
+
 ## Modular interoperability
 
 CWL hosts such as `contextual-orchestrator` and `naruon` supply tenant context

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Bounded read-only PostgreSQL PITR target-configuration observation on a caller-owned already-connected isolated recovery target. The observer first snapshots the exact reviewed `PostgresPitrRecoveryTarget`; wrong-type authority or a target mutated out of that reviewed contract fails before cursor acquisition or database I/O. It reads exactly eight recovery-target settings plus `pg_is_in_recovery()`, uses bounded result materialization, and fails closed on malformed, duplicate, oversized, pending-restart, inactive-recovery, or mismatched evidence. When a reviewed `name` or `immediate` target intentionally has no inclusion edge, the effective `recovery_target_inclusive` setting must remain PostgreSQL 18's default `on`; time/XID/LSN targets retain their explicit reviewed inclusion edge. Returned provenance is content-free. The observer does not write recovery configuration, create `recovery.signal`, supply `restore_command`, prove WAL/archive/timeline completeness or target attainment, promote recovery, prove application readiness, or establish achieved RPO/RTO or DR capability.
+- Caller-owned physical/WAL/PITR recovery profile binder
+  (`bind_postgres_physical_recovery_profile()` /
+  `parse_postgres_physical_recovery_profile()`). The seam records method,
+  recovery-target kind, continuous-WAL necessity, isolated-target readiness,
+  and optional RPO/RTO objectives without executing backup or restore.
+  `wal_archive_required=False` means no continuous archive, not the absence of
+  backup-internal WAL. `pitr` plus `immediate` is a consistent-state stop, not
+  replay-to-end-of-archive. Lone-surrogate profile text fails as
+  `PostgresPhysicalRecoveryError`.
 - Bounded `restore_postgres_logical_backup()` executor that runs one
   shell-free `pg_restore --single-transaction --exit-on-error` against a
   caller-owned private archive descriptor. Callers must pass exact-boolean
@@ -135,6 +145,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Replaced generic package-owned Result Application implementation names with
+  `application_phase`, `record_applied`, `result_checkpoint`,
+  `transaction_cursor`, `checkpointed_record`, and `record_effect`. The released
+  `apply_checkpointed_result_in_transaction(cursor, ..., item, apply_record)`
+  keyword signature and public `ResultApplicationOutcome(applied, checkpoint)`
+  dataclass field/introspection/`asdict` shape remain unchanged at an explicit
+  compatibility boundary; additive `.record_applied` and `.result_checkpoint`
+  reads expose semantic vocabulary while provider wire contracts and PostgreSQL
+  persistence remain unchanged.
 - Bound repository CI checkouts to the exact pull-request source head and verify
   the checked-out commit before tests, coverage, packaging, or container gates.
 - Migrated package licensing to PEP 639 with an SPDX `Apache-2.0` expression,
@@ -148,4 +167,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial standalone and embeddable PostgreSQL LLM batch engine extraction.
+- Initial standalone and embeddable PostgreSQL LLM batch engine extraction.

docs/doctoring/batch-inference-port-convergence.md

@@ -0,0 +1,66 @@
+# BatchInferencePort convergence doctoring
+
+## Purpose
+
+`pg-llm-batch` owns durable asynchronous batch lifecycle, token/size accounting, tenant-scoped persistence, checkpoint/result application, and the provider-neutral `BatchInferencePort` boundary. `contextual-orchestrator` owns provider/model discovery, routing/fallback, credential discovery and concrete LLM execution authority. This note prevents a structural Python `Protocol` or a renamed direct HTTP client from being mistaken for that completed authority split.
+
+This is a doctoring/evidence surface. Mutable branch heads below are dated candidate evidence only and must be refreshed before integration or release decisions.
+
+## Current evidence snapshot — 2026-09-16
+
+Protected `main` remains on the pre-convergence implementation and does not establish a released Contextual-Orchestrator-backed batch adapter.
+
+Draft #319 at `7b1864028d952c233abf1318e8b8b0c3351c5b65` already contains `pg_llm_batch/batch_inference_port.py` and `tests/test_batch_inference_port.py`. The candidate `BatchInferencePort` exposes upload, create, status, cancel, result-download and file-delete lifecycle operations. Its tests prove that the shipped `BatchAPIClient` and a non-HTTP adapter can satisfy the protocol while discovery/routing methods remain outside the port.
+
+That is useful candidate evidence, but it is not the end state required by #318:
+
+- `BatchAPIClient` remains a conforming implementation and still owns direct OpenAI-compatible `/files` + `/batches` HTTP behavior on its active source lineage;
+- `create_batch_job` still accepts a host-selected `endpoint` string, so the candidate protocol alone does not prove semantic operation identity is separated from provider wire routing;
+- the protocol deliberately permits an arbitrary host adapter and therefore does not itself bind execution to a versioned immutable `contextual-orchestrator` API/client/schema;
+- a mutable #319 head is neither protected product truth nor immutable dependency identity.
+
+Draft #317 remains the active `batch_api_client.py` writer for #301/#302/#347. Issue #201 owns first-class endpoint preparation/accounting. Issue #318 owns the released-contract/ACL convergence. Canonical product documentation remains separated across #229 and #324. No parallel source writer should be created while those paths overlap.
+
+## Required authority split
+
+The final boundary must make the following ownership executable rather than descriptive:
+
+| Concern | Canonical owner |
+| --- | --- |
+| PostgreSQL durable lifecycle, tenant/RLS, token/size accounting, idempotency, checkpoint/result application | `pg-llm-batch` |
+| Provider/model discovery and selection | `contextual-orchestrator` |
+| Provider credentials/key discovery | `contextual-orchestrator` |
+| Routing, fallback and provider-specific execution semantics | `contextual-orchestrator` |
+| Versioned batch lifecycle ACL consumed by pg | pg-owned adapter over an immutable released CO API/client/schema |
+| Provider wire identifiers returned as evidence | adapter boundary only; never pg domain authority by themselves |
+
+No implementation may copy CO source, query another service database, pin a mutable CO branch, hard-code provider/model/group authority, or treat a protected source SHA as a released contract.
+
+## RED-to-GREEN acceptance
+
+Before replacing or restricting direct-provider authority, the serialized owner must establish realistic REDs for all of these conditions and then make the minimum causal repair:
+
+1. **Released-contract admission.** A pg adapter must reject missing, mutable, incompatible or unverifiable CO contract identity and admit only an explicitly supported immutable released API/client/schema identity.
+2. **No hidden provider authority.** Durable pg lifecycle callers must not need provider/model/group/key discovery. Provider wire endpoints or route selection must not become hidden authority merely because they are passed through a `Protocol` method.
+3. **Primitive authority before transport.** The #347 invariant survives migration: behavior-bearing caller identifiers are rejected before URL formatting, credential resolution, transport preparation, comparison, logging, persistence or evidence retention.
+4. **Usage honesty.** Measured, estimated and unavailable usage remain distinguishable. Unknown usage or unknown price is never coerced to zero or an authoritative complete measured total; zero usage remains distinct from unknown price.
+5. **Lifecycle semantics.** Submit/status/cancel/result retrieval preserve idempotency, bounded response handling and provider-neutral lifecycle state without inventing unsupported provider behavior.
+6. **Termination semantics.** User cancellation, provider terminal state and any administrator policy timeout remain distinguishable. Reasoning, streaming or tool execution is not terminated merely because elapsed time crossed an arbitrary default.
+7. **Database transaction boundary.** Remote inference, provider queue wait, retry backoff and long CPU/GPU/tokenization work occur outside avoidable explicit PostgreSQL transactions and locks. Transactions cover only the minimal durable aggregate transition before or after external work.
+8. **Standalone compatibility is explicit.** If a direct provider adapter is retained for standalone use, it is a deliberately bounded compatibility adapter with the same security/accounting invariants. It is not silently treated as the production CO-backed authority.
+
+GREEN requires exact-head repository tests plus the then-live security/SAST/review gates. A predecessor GREEN does not transfer after source/base movement.
+
+## Migration order
+
+Use the existing serialized owners rather than creating a sibling implementation:
+
+1. settle #317/#347 and the overlapping endpoint/accounting writers with their own RED→repair→exact-head evidence;
+2. repeat #316's open-PR and no-PR path census for `batch_inference_port.py`, `batch_api_client.py`, endpoint preparation/accounting, package exports and tests;
+3. obtain an eligible immutable CO release from the current CO release owner and verify API/client/schema identity, SBOM/provenance/reproducibility and rollback evidence;
+4. author the pg ACL REDs against that released boundary, then implement the minimum adapter/port repair without source copying or cross-service SQL;
+5. ordinary/non-force reconcile descendants, reacquire exact-final-head evidence, converge #229/#324 documentation, and only then promote an immutable pg release and consumer canary.
+
+## Release claim boundary
+
+A protocol class, branch-local test, protected commit, successful Release Acceptance workflow, package build or documentation statement is not an immutable release. Completion requires a normally integrated protected exact head and verified version/CHANGELOG/tag/package/SBOM/provenance/reproducibility/rollback artifacts. The consuming pg release must bind to the eligible immutable CO contract it actually uses.