From 3c8de8422da8e188085b39c0d086e096dacc3826 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 18 Sep 2026 09:00:59 +0900 Subject: [PATCH 01/12] docs: use registry-safe README links --- README.md | 29 +++++------------------------ 1 file changed, 5 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 935ba5be4..3dda56513 100644 --- a/README.md +++ b/README.md @@ -205,7 +205,7 @@ a generic SQL surface, and still require normal authentication, authorization, and SQL-injection controls. Direct SQL consumers that do not establish an authorized tenant scope see no lifecycle rows after RLS is enabled. -See [`docs/remote-batch-lifecycle.md`](docs/remote-batch-lifecycle.md) for the +See [`docs/remote-batch-lifecycle.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/remote-batch-lifecycle.md) for the migration, rollback, pooling, recovery, custom-recorder, and assurance contract. For a caller-owned logical archive, use `restore_postgres_logical_backup()` only @@ -216,9 +216,6 @@ The executor runs `pg_restore --single-transaction --exit-on-error`. Custom-format restore seeks through the archive, so success is not required to leave the descriptor at end-of-file. If metadata changes after `pg_restore` exits zero, treat the target as unsafe and do not retry into the same service. -See [`docs/doctoring/postgres-logical-restore.md`](docs/doctoring/postgres-logical-restore.md) -for the operator steps. - ## Embed as a git submodule ```bash @@ -298,9 +295,7 @@ client = OpenTelemetryBatchAPIClient.from_global_provider( The emitted spans and metrics use bounded operation and outcome vocabularies and never include endpoint aliases, provider URLs, resource IDs, credentials, -metadata, prompts, or provider response bodies. See the -[OpenTelemetry operation contract](docs/doctoring/opentelemetry-operations.md) -for signals, ownership boundaries, privacy rules, and APA 7 references. +metadata, prompts, or provider response bodies. --- @@ -317,26 +312,12 @@ PG_LLM_BATCH_TEST_DSN=postgresql://pgllm:pgllm@localhost:5432/pgllm \ ## Docs -- [`docs/remote-batch-lifecycle.md`](docs/remote-batch-lifecycle.md) +- [`docs/remote-batch-lifecycle.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/remote-batch-lifecycle.md) — standalone and tenant-scoped durable lifecycle operation, RLS trust boundary, migration, rollback, pooling, and recovery. -- [`docs/doctoring/tenant-scoped-lifecycle.md`](docs/doctoring/tenant-scoped-lifecycle.md) - — tenant identity, RLS authority, compatibility, and APA 7 references. -- [`docs/doctoring/cli-secret-input.md`](docs/doctoring/cli-secret-input.md) - — no-echo interactive secret entry, bounded stdin automation, fail-closed - validation, verification, and security references. -- [`docs/doctoring/count-tokens-stdin-privacy.md`](docs/doctoring/count-tokens-stdin-privacy.md) - — bounded UTF-8 prompt ingestion without argv exposure, exact text semantics, - failure ordering, verification, and APA 7 references. -- [`docs/doctoring/legacy-pgsql-http-retrieval.md`](docs/doctoring/legacy-pgsql-http-retrieval.md) - — retirement of direct SQL provider networking, existing-volume remediation, - rollback, and the validated Python provider boundary. -- [`docs/doctoring/opentelemetry-operations.md`](docs/doctoring/opentelemetry-operations.md) - — opt-in operation traces/metrics, host ownership, privacy and cardinality - boundaries, verification, and APA 7 references. -- [`docs/papers/`](docs/papers/) — CC BY 4.0 reference papers on LLM batching +- [`docs/papers/`](https://github.com/ContextualWisdomLab/pg-llm-batch/tree/main/docs/papers/) — CC BY 4.0 reference papers on LLM batching (PagedAttention/vLLM, DeepSpeed-FastGen) with citations. ## License -Apache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE). +Apache-2.0. See [`LICENSE`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/LICENSE) and [`NOTICE`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/NOTICE). From 7b9f860004690abe547719ef1b5bb6cf1530f8e1 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 18 Sep 2026 10:08:49 +0900 Subject: [PATCH 02/12] test(readme): preserve registry-safe public documentation links --- tests/test_readme_registry_links.py | 30 +++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 tests/test_readme_registry_links.py diff --git a/tests/test_readme_registry_links.py b/tests/test_readme_registry_links.py new file mode 100644 index 000000000..ac3675e8f --- /dev/null +++ b/tests/test_readme_registry_links.py @@ -0,0 +1,30 @@ +from pathlib import Path +import re + + +_REPOSITORY_RELATIVE_TARGET = re.compile( + r"\]\((?:docs/[^)]+|LICENSE|NOTICE)\)" +) + +_REQUIRED_PUBLIC_LINKS = ( + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/NOTICE", + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/remote-batch-lifecycle.md", + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/tenant-scoped-lifecycle.md", + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/bootstrap-dsn-precedence.md", + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/cli-secret-input.md", + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/count-tokens-stdin-privacy.md", + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/legacy-pgsql-http-retrieval.md", + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/opentelemetry-operations.md", + "https://github.com/ContextualWisdomLab/pg-llm-batch/tree/main/docs/papers/", + "https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/LICENSE", +) + + +def test_packaged_readme_keeps_repository_links_registry_safe_and_discoverable() -> None: + """Require absolute package-registry links without dropping public operator docs.""" + + readme = (Path(__file__).parents[1] / "README.md").read_text(encoding="utf-8") + + assert _REPOSITORY_RELATIVE_TARGET.search(readme) is None + for url in _REQUIRED_PUBLIC_LINKS: + assert url in readme From e299bcc43675ef9fd5228d78688f0bfb6ede010f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 18 Sep 2026 10:15:19 +0900 Subject: [PATCH 03/12] docs: remove registry-internal README references --- README.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 03f8c56ef..97bee284a 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ python -m pg_llm_batch health unset PG_LLM_BATCH_DSN ``` -Explicit CLI `--dsn` values have a different confidentiality boundary: password, `passfile`, TLS private-key, TLS key-password, and OAuth-client-secret material is rejected before connection work so credentials are not normalized into an argv transport. See [`docs/doctoring/bootstrap-dsn-precedence.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/bootstrap-dsn-precedence.md). +Explicit CLI `--dsn` values have a different confidentiality boundary: password, `passfile`, TLS private-key, TLS key-password, and OAuth-client-secret material is rejected before connection work so credentials are not normalized into an argv transport. ### Configure the provider boundary @@ -202,7 +202,7 @@ The repository contains bounded backup, restore, catalog, replay, and recovery-e The Draft recovery-target observer in `pg_llm_batch.postgres_recovery_target_configuration` remains module-scoped. `observe_postgres_recovery_target_configuration(...)` performs one fixed catalog-qualified read over the eight reviewed PostgreSQL recovery-target settings plus `pg_is_in_recovery()` on an already-connected isolated recovery target; `postgres_recovery_target_configuration_was_observed(...)` checks the resulting bounded evidence. This proves only that the effective settings visible to that connection match the reviewed target contract while recovery is active. It does not write PostgreSQL configuration, create `recovery.signal`, supply `restore_command`, validate or replay WAL bytes, prove archive completeness or timeline ancestry, prove target attainment or replay completion, pause/resume/promote recovery, prove application readiness, or establish achieved RPO/RTO, HA/DR, CSAP, SOC 2, or certification. The caller owns connection and timeout policy, and the observer's diagnostics/evidence remain content-minimal. -For a caller-owned logical archive, use `restore_postgres_logical_backup()` only against an isolated libpq service after you can assert `source_superusers_trusted=True`. The service name is not an authorization boundary. Only `PGPASSWORD`, `PGPASSFILE`, and `PGSERVICEFILE` may be inherited. The executor runs `pg_restore --single-transaction --exit-on-error`. Custom-format restore seeks through the archive, so success is not required to leave the descriptor at end-of-file. If metadata changes after `pg_restore` exits zero, treat the target as unsafe and do not retry into the same service. This subprocess contract is distinct from package-created pg8000 connections. See [`docs/doctoring/postgres-logical-restore.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/postgres-logical-restore.md). +For a caller-owned logical archive, use `restore_postgres_logical_backup()` only against an isolated libpq service after you can assert `source_superusers_trusted=True`. The service name is not an authorization boundary. Only `PGPASSWORD`, `PGPASSFILE`, and `PGSERVICEFILE` may be inherited. The executor runs `pg_restore --single-transaction --exit-on-error`. Custom-format restore seeks through the archive, so success is not required to leave the descriptor at end-of-file. If metadata changes after `pg_restore` exits zero, treat the target as unsafe and do not retry into the same service. This subprocess contract is distinct from package-created pg8000 connections. ## Embedding boundary @@ -241,7 +241,7 @@ Idempotent provider `GET` operations use up to three total attempts by default f ## Observability -Hosts that already operate OpenTelemetry may opt into `OpenTelemetryBatchAPIClient`. Emitted spans and metrics use bounded operation/outcome vocabularies and exclude endpoint aliases, provider URLs, resource identifiers, credentials, metadata, prompts, and provider bodies. See [`docs/doctoring/opentelemetry-operations.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/opentelemetry-operations.md). +Hosts that already operate OpenTelemetry may opt into `OpenTelemetryBatchAPIClient`. Emitted spans and metrics use bounded operation/outcome vocabularies and exclude endpoint aliases, provider URLs, resource identifiers, credentials, metadata, prompts, and provider bodies. ## Tests @@ -262,12 +262,6 @@ Repository CI additionally verifies supported Python versions, exact owned produ ## Docs - [`docs/remote-batch-lifecycle.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/remote-batch-lifecycle.md) — durable lifecycle, tenant identity, RLS, migration, rollback, pooling, and recovery. -- [`docs/doctoring/tenant-scoped-lifecycle.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/tenant-scoped-lifecycle.md) — tenant/RLS authority and references. -- [`docs/doctoring/bootstrap-dsn-precedence.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/bootstrap-dsn-precedence.md) — bootstrap source precedence, argv confidentiality, and concrete-driver boundary. -- [`docs/doctoring/cli-secret-input.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/cli-secret-input.md) — no-echo and bounded stdin secret input. -- [`docs/doctoring/count-tokens-stdin-privacy.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/count-tokens-stdin-privacy.md) — bounded UTF-8 prompt ingestion without argv exposure. -- [`docs/doctoring/legacy-pgsql-http-retrieval.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/legacy-pgsql-http-retrieval.md) — retirement of direct SQL provider networking. -- [`docs/doctoring/opentelemetry-operations.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/opentelemetry-operations.md) — telemetry ownership, privacy, cardinality, verification, and references. - [`docs/papers/`](https://github.com/ContextualWisdomLab/pg-llm-batch/tree/main/docs/papers/) — reference papers used by repository doctoring. ## License and release authority From 311ef7af5044425b27fd85d505734c5324f13bb7 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 18 Sep 2026 10:18:41 +0900 Subject: [PATCH 04/12] docs(readme): preserve public operator links under registry-safe contract --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 97bee284a..03f8c56ef 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ python -m pg_llm_batch health unset PG_LLM_BATCH_DSN ``` -Explicit CLI `--dsn` values have a different confidentiality boundary: password, `passfile`, TLS private-key, TLS key-password, and OAuth-client-secret material is rejected before connection work so credentials are not normalized into an argv transport. +Explicit CLI `--dsn` values have a different confidentiality boundary: password, `passfile`, TLS private-key, TLS key-password, and OAuth-client-secret material is rejected before connection work so credentials are not normalized into an argv transport. See [`docs/doctoring/bootstrap-dsn-precedence.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/bootstrap-dsn-precedence.md). ### Configure the provider boundary @@ -202,7 +202,7 @@ The repository contains bounded backup, restore, catalog, replay, and recovery-e The Draft recovery-target observer in `pg_llm_batch.postgres_recovery_target_configuration` remains module-scoped. `observe_postgres_recovery_target_configuration(...)` performs one fixed catalog-qualified read over the eight reviewed PostgreSQL recovery-target settings plus `pg_is_in_recovery()` on an already-connected isolated recovery target; `postgres_recovery_target_configuration_was_observed(...)` checks the resulting bounded evidence. This proves only that the effective settings visible to that connection match the reviewed target contract while recovery is active. It does not write PostgreSQL configuration, create `recovery.signal`, supply `restore_command`, validate or replay WAL bytes, prove archive completeness or timeline ancestry, prove target attainment or replay completion, pause/resume/promote recovery, prove application readiness, or establish achieved RPO/RTO, HA/DR, CSAP, SOC 2, or certification. The caller owns connection and timeout policy, and the observer's diagnostics/evidence remain content-minimal. -For a caller-owned logical archive, use `restore_postgres_logical_backup()` only against an isolated libpq service after you can assert `source_superusers_trusted=True`. The service name is not an authorization boundary. Only `PGPASSWORD`, `PGPASSFILE`, and `PGSERVICEFILE` may be inherited. The executor runs `pg_restore --single-transaction --exit-on-error`. Custom-format restore seeks through the archive, so success is not required to leave the descriptor at end-of-file. If metadata changes after `pg_restore` exits zero, treat the target as unsafe and do not retry into the same service. This subprocess contract is distinct from package-created pg8000 connections. +For a caller-owned logical archive, use `restore_postgres_logical_backup()` only against an isolated libpq service after you can assert `source_superusers_trusted=True`. The service name is not an authorization boundary. Only `PGPASSWORD`, `PGPASSFILE`, and `PGSERVICEFILE` may be inherited. The executor runs `pg_restore --single-transaction --exit-on-error`. Custom-format restore seeks through the archive, so success is not required to leave the descriptor at end-of-file. If metadata changes after `pg_restore` exits zero, treat the target as unsafe and do not retry into the same service. This subprocess contract is distinct from package-created pg8000 connections. See [`docs/doctoring/postgres-logical-restore.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/postgres-logical-restore.md). ## Embedding boundary @@ -241,7 +241,7 @@ Idempotent provider `GET` operations use up to three total attempts by default f ## Observability -Hosts that already operate OpenTelemetry may opt into `OpenTelemetryBatchAPIClient`. Emitted spans and metrics use bounded operation/outcome vocabularies and exclude endpoint aliases, provider URLs, resource identifiers, credentials, metadata, prompts, and provider bodies. +Hosts that already operate OpenTelemetry may opt into `OpenTelemetryBatchAPIClient`. Emitted spans and metrics use bounded operation/outcome vocabularies and exclude endpoint aliases, provider URLs, resource identifiers, credentials, metadata, prompts, and provider bodies. See [`docs/doctoring/opentelemetry-operations.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/opentelemetry-operations.md). ## Tests @@ -262,6 +262,12 @@ Repository CI additionally verifies supported Python versions, exact owned produ ## Docs - [`docs/remote-batch-lifecycle.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/remote-batch-lifecycle.md) — durable lifecycle, tenant identity, RLS, migration, rollback, pooling, and recovery. +- [`docs/doctoring/tenant-scoped-lifecycle.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/tenant-scoped-lifecycle.md) — tenant/RLS authority and references. +- [`docs/doctoring/bootstrap-dsn-precedence.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/bootstrap-dsn-precedence.md) — bootstrap source precedence, argv confidentiality, and concrete-driver boundary. +- [`docs/doctoring/cli-secret-input.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/cli-secret-input.md) — no-echo and bounded stdin secret input. +- [`docs/doctoring/count-tokens-stdin-privacy.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/count-tokens-stdin-privacy.md) — bounded UTF-8 prompt ingestion without argv exposure. +- [`docs/doctoring/legacy-pgsql-http-retrieval.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/legacy-pgsql-http-retrieval.md) — retirement of direct SQL provider networking. +- [`docs/doctoring/opentelemetry-operations.md`](https://github.com/ContextualWisdomLab/pg-llm-batch/blob/main/docs/doctoring/opentelemetry-operations.md) — telemetry ownership, privacy, cardinality, verification, and references. - [`docs/papers/`](https://github.com/ContextualWisdomLab/pg-llm-batch/tree/main/docs/papers/) — reference papers used by repository doctoring. ## License and release authority From 54f24a78cbd217dae888fa979072cffd0dc3183f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 18 Sep 2026 15:04:11 +0900 Subject: [PATCH 05/12] test(readme): satisfy module docstring gate --- tests/test_readme_registry_links.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/test_readme_registry_links.py b/tests/test_readme_registry_links.py index ac3675e8f..37b29f022 100644 --- a/tests/test_readme_registry_links.py +++ b/tests/test_readme_registry_links.py @@ -1,3 +1,5 @@ +"""Regression contract for registry-safe public README links.""" + from pathlib import Path import re From 40cf352e6ac4cd5b6626a93ac69ca7439abe8335 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 20 Sep 2026 00:04:41 +0900 Subject: [PATCH 06/12] test(docs): reject overstated secret encryption claim --- tests/test_readme_registry_links.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tests/test_readme_registry_links.py b/tests/test_readme_registry_links.py index 37b29f022..62d5e8ba7 100644 --- a/tests/test_readme_registry_links.py +++ b/tests/test_readme_registry_links.py @@ -30,3 +30,14 @@ def test_packaged_readme_keeps_repository_links_registry_safe_and_discoverable() assert _REPOSITORY_RELATIVE_TARGET.search(readme) is None for url in _REQUIRED_PUBLIC_LINKS: assert url in readme + + +def test_packaged_readme_does_not_overstate_secret_storage_encryption() -> None: + """Keep public SecretStore claims aligned with the optional Fernet boundary.""" + + readme = (Path(__file__).parents[1] / "README.md").read_text(encoding="utf-8") + + assert "KV config + encrypted-secret store" not in readme + assert "| KV config + secret store | `pg_llm_batch/config.py` |" in readme + assert "SecretStore` encrypts values only when a Fernet key is supplied" in readme + assert "base64-obfuscates values unless the store is configured with `require_encryption=True`" in readme From 315764c12d3e467363c8cb9879f654c48cc32392 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 20 Sep 2026 00:05:46 +0900 Subject: [PATCH 07/12] docs: make secret-store encryption boundary explicit --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 03f8c56ef..045110a50 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ retired; automatic reconciliation is a separate product capability rather than a | Tenant-qualified lifecycle persistence and reads | `pg_llm_batch/db.py` | | PostgreSQL driver abstraction | `pg_llm_batch/postgres_driver_port.py` | | Admitted runtime driver selection | `pg_llm_batch/postgres_driver_runtime.py` | -| KV config + encrypted-secret store | `pg_llm_batch/config.py` | +| KV config + secret store | `pg_llm_batch/config.py` | | Optional OpenTelemetry operations | `pg_llm_batch/observability.py` | | DDL subset | `pg_llm_batch/schema.sql` | | Readiness (`/healthz`) | `pg_llm_batch/health.py` | @@ -109,6 +109,8 @@ python -m pg_llm_batch config set-secret gateway_api_key.default `config set-secret` does not accept secret plaintext in process arguments. Interactive entry is no-echo; automation may provide one bounded logical line on standard input from an already-owned credential source. +Package-managed secret storage is not automatically encrypted. `SecretStore` encrypts values only when a Fernet key is supplied; without one, the compatibility path base64-obfuscates values unless the store is configured with `require_encryption=True`. Mandatory encryption migration, key rotation/recovery, and external key custody remain tracked under [issue #121](https://github.com/ContextualWisdomLab/pg-llm-batch/issues/121). + Production gateway destinations require HTTPS. Plain HTTP is accepted only for explicit loopback development endpoints (`localhost`, `127.0.0.0/8`, or `::1`). User information, query parameters, fragments, whitespace, and invalid ports are rejected before provider credentials are acquired. To encrypt package-managed secrets at rest, supply a Fernet bootstrap key through the reviewed deployment path, for example in a local development shell: From 219f12db1451c8f3e3e278d81561dc76685c1bf3 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 20 Sep 2026 01:01:57 +0900 Subject: [PATCH 08/12] test(docs): pin health disclosure boundary --- tests/test_readme_registry_links.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tests/test_readme_registry_links.py b/tests/test_readme_registry_links.py index 62d5e8ba7..d7fb4e4d6 100644 --- a/tests/test_readme_registry_links.py +++ b/tests/test_readme_registry_links.py @@ -41,3 +41,14 @@ def test_packaged_readme_does_not_overstate_secret_storage_encryption() -> None: assert "| KV config + secret store | `pg_llm_batch/config.py` |" in readme assert "SecretStore` encrypts values only when a Fernet key is supplied" in readme assert "base64-obfuscates values unless the store is configured with `require_encryption=True`" in readme + + +def test_packaged_readme_distinguishes_public_healthz_from_operator_cli_diagnostics() -> None: + """Keep the README explicit about the unresolved CLI health disclosure boundary.""" + + readme = (Path(__file__).parents[1] / "README.md").read_text(encoding="utf-8") + + assert "fixed required component names and boolean readiness" in readme + assert "operator-facing diagnostic surface" in readme + assert "untrusted logs" in readme + assert "https://github.com/ContextualWisdomLab/pg-llm-batch/issues/203" in readme From 649218244feb90eab3b5a58e5eaca982c72cbe44 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 20 Sep 2026 01:02:39 +0900 Subject: [PATCH 09/12] docs: bound CLI health disclosure claim --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 045110a50..d052e8579 100644 --- a/README.md +++ b/README.md @@ -148,12 +148,14 @@ for payload in result["ready"]: ## Health / readiness -`GET /healthz` returns `200` only when the package's database-side readiness contract is satisfied; otherwise it returns `503`. +`GET /healthz` is the content-minimal public readiness surface. It returns only fixed required component names and boolean readiness, with `200` when the package's database-side readiness contract is satisfied and `503` otherwise. ```bash python -m pg_llm_batch health ``` +The current CLI `health` command is an operator-facing diagnostic surface, not the public `/healthz` projection. Its raw report can still include lower-layer/database detail, so do not route it into untrusted logs, tenant-visible telemetry, support bundles, or public/user-facing responses. [Issue #203](https://github.com/ContextualWisdomLab/pg-llm-batch/issues/203) owns the runtime contract that will bound the default CLI output without losing operator actionability; this README statement does not claim that repair is already implemented. + The Docker `HEALTHCHECK` and Compose PostgreSQL service use the package-owned health function rather than treating mere TCP acceptance as product readiness. --- From 4e43cf29a3c014f716951d41c89fb0073f1bbc06 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 20 Sep 2026 02:01:58 +0900 Subject: [PATCH 10/12] test(docs): pin legacy extension retirement boundary --- tests/test_readme_registry_links.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/tests/test_readme_registry_links.py b/tests/test_readme_registry_links.py index d7fb4e4d6..f5930164c 100644 --- a/tests/test_readme_registry_links.py +++ b/tests/test_readme_registry_links.py @@ -52,3 +52,14 @@ def test_packaged_readme_distinguishes_public_healthz_from_operator_cli_diagnost assert "operator-facing diagnostic surface" in readme assert "untrusted logs" in readme assert "https://github.com/ContextualWisdomLab/pg-llm-batch/issues/203" in readme + + +def test_packaged_readme_distinguishes_fresh_init_from_existing_volume_extension_retirement() -> None: + """Do not promote fresh-install cron/http retirement into upgraded-volume truth.""" + + readme = (Path(__file__).parents[1] / "README.md").read_text(encoding="utf-8") + + assert "Fresh initialization no longer creates the former `pg_cron` + `http` provider retriever" in readme + assert "Existing volumes can still contain those extensions" in readme + assert "preservation-first retirement migration" in readme + assert "https://github.com/ContextualWisdomLab/pg-llm-batch/issues/103" in readme From b08218d2de8bf1c9c65a5f928f29c31ceb02b890 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 20 Sep 2026 02:02:59 +0900 Subject: [PATCH 11/12] docs: bound legacy extension retirement claims --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index d052e8579..c6aa14e5d 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,7 @@ llm_requests ──▶ PostgresBatchOrchestrator.prepare_batches() durable lifecycle + tenant/RLS + reconciliation evidence ``` -Provider-facing polling and retrieval stay outside PostgreSQL. The former bundled `pg_cron` + `pgsql-http` provider retriever is -retired; automatic reconciliation is a separate product capability rather than a second database-side network authority. +Provider-facing polling and retrieval stay outside PostgreSQL. Fresh initialization no longer creates the former `pg_cron` + `http` provider retriever. Existing volumes can still contain those extensions, schedules, or extension-owned objects until the preservation-first retirement migration reaches protected `main`; the compatibility image therefore still retains the legacy packages and preload needed for that transition. [Issue #103](https://github.com/ContextualWisdomLab/pg-llm-batch/issues/103) owns existing-volume retirement and the later package/preload removal stage. Automatic reconciliation is a separate product capability rather than a second database-side network authority. | Piece | Module | | --- | --- | From 5cdbd57ab66c39c92c921cf3c88897938a6c61cb Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 20 Sep 2026 09:02:05 +0900 Subject: [PATCH 12/12] test(docs): align SQL retirement contract with staged cleanup --- tests/test_count_tokens_stdin_documentation.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/tests/test_count_tokens_stdin_documentation.py b/tests/test_count_tokens_stdin_documentation.py index 42a90866a..8e0bbf00d 100644 --- a/tests/test_count_tokens_stdin_documentation.py +++ b/tests/test_count_tokens_stdin_documentation.py @@ -33,8 +33,13 @@ def test_doctoring_matches_cli_byte_limit_and_privacy_authority() -> None: def test_readme_does_not_claim_retired_sql_provider_authority() -> None: - """The root architecture must not advertise the retired SQL retriever.""" + """The root architecture must separate fresh-init retirement from legacy cleanup.""" text = README.read_text(encoding="utf-8") assert "(or) pg_cron job" not in text - assert "former bundled `pg_cron` + `pgsql-http` provider retriever is\nretired" in text + assert ( + "Fresh initialization no longer creates the former `pg_cron` + `http` " + "provider retriever" + ) in text + assert "Existing volumes can still contain those extensions" in text + assert "preservation-first retirement migration" in text