docs: make public surface commercial-license aware

[seonghobae]

Public-documentation child for the commercial PostgreSQL-driver migration. This lane owns only README.md and docs/index.md; runtime, driver/schema/tests/workflows, root CHANGELOG.md, product-gap documentation, PRD/TRD, ADR/operator material, and release truth remain with their canonical owners.

Exact current topology — 2026-09-20

• canonical parent feat(postgres): define driver-neutral migration port #323: 797b929b1e2cbc0f8a5568bea89841d0f8c193ad;
• exact current docs: make public surface commercial-license aware #321: d5057439ecf41e237958905c001894b045383d10;
• exact-current docs: make public surface commercial-license aware #321 CI 35447536510: SUCCESS;
• exact-current docs: make public surface commercial-license aware #321 Release Acceptance 35447536575: SUCCESS.

This exact head is repository-local GREEN. That does not satisfy the unintegrated Draft ancestry, independent approval, central required-workflow/governance prerequisites, or immutable-release boundary; no predecessor evidence transfers to a future moved head.

Documentation contract

The public surface distinguishes Draft candidate state from protected/released truth. Remote PostgreSQL TLS/server identity remains #123/#342 authority. The recovery-target observer handoff remains bounded to reviewed PostgreSQL recovery-target settings plus pg_is_in_recovery() on an already-connected isolated recovery target; these docs do not claim configuration mutation, WAL/archive/timeline validation, target attainment, application readiness, achieved RPO/RTO, HA/DR, CSAP, SOC 2, certification, or end-to-end PITR.

This head also repairs two buyer-facing disclosure boundaries from live source rather than broadening runtime authority:

• SecretStore encrypts at rest only when a Fernet key is supplied. Without one, the compatibility path base64-obfuscates values unless require_encryption=True; mandatory encryption/migration/key-lifecycle remains [Security] Make provider-secret encryption an explicit deployment policy #121 authority.
• /healthz exposes only fixed required-component names and boolean readiness. Operator-facing health internals remain a separate boundary; CLI diagnostic-disclosure hardening remains [Privacy/Operability] Bound CLI health diagnostics without losing operator actionability #203 authority.

Root ARCHITECTURE.md, CHANGELOG.md, Result Application doctoring, and docs/product-technical-gap-baseline.md remain #324 authority; #348 is the recovery ADR/operator-documentation descendant.

Direct child #352

#352 is now exact 5cdbd57ab66c39c92c921cf3c88897938a6c61cb, 15 ahead / 0 behind from this exact #321 with merge base exactly #321. Its effective relative surface is README.md, tests/test_readme_registry_links.py, and tests/test_count_tokens_stdin_documentation.py.

The child retains the secret-storage and health-disclosure public contracts and the two-stage legacy SQL retirement truth: fresh initialization no longer creates the former pg_cron + http provider retriever, while existing upgraded volumes may still retain extension/schedule/object state until the preservation-first retirement migration reaches protected main. Issue #103 remains the durable retirement owner; package/preload removal is a later stage.

Predecessor #352 b08218d2... produced real CI RED in 35456862486: the older count-tokens documentation regression still required the superseded pgsql-http ... retired literal even though the current README and newer regression deliberately distinguish fresh-init behavior from existing-volume cleanup. Current 5cdbd57a... changes only that stale executable assertion; it does not weaken or rewrite the README contract. Fresh exact-head CI 35477695148 and Release Acceptance 35477695138 are both SUCCESS. This is independent child evidence; it does not transfer from #321 and does not satisfy independent approval, protected integration, or immutable-release authority.

A separate compose/runpy warning observed in the predecessor CI is already owned by canonical Draft #252; issue #354 now points to that existing one-file warning repair rather than creating a competing writer.

Integration boundary

#323 remains Draft and root #233 remains the protected integration prerequisite. Normal order remains central prerequisite convergence → #233 normal protected integration → #323 reconcile/integrate with fresh evidence → this documentation child reconcile/evidence → #352 reconcile/evidence → normal integration → existing-volume extension retirement → later compatibility-image package/preload removal with rollback evidence → canonical root documentation convergence → protected-head immutable release.

No self-approval, force update, destructive rebase, routine bypass merge, predecessor-check transfer, mutable dependency substitution, sibling source copy, source-neutral wake/no-op commit, or branch-only release claim is accepted.

Refs #103, #121, #123, #184, #203, #229, #233, #244, #252, #299, #316, #322, #323, #324, #342, #348, #352, #354.

[coderabbitai]

📝 Walkthrough

Walkthrough

README와 docs/index.md에 LGPL-3.0-only Psycopg 의존성 상태, 개발용 PostgreSQL 비밀번호 절차, 시크릿 기반 DSN 예제 및 상용 릴리스 검증 기준을 추가했습니다.

Changes

상용 의존성 및 개발 절차 문서화

Layer / File(s)	Summary
의존성 상태 및 릴리스 검증 README.md, docs/index.md	psycopg[binary]>=3.1의 LGPL-3.0-only 상태와 issue #322를 상용 배포 차단 사항으로 명시했습니다. 릴리스 검증에 GPL/LGPL/AGPL 런타임 패키지 제거 기준을 추가했습니다.
개발용 자격 증명 절차 README.md, docs/index.md	개발용 PostgreSQL 비밀번호를 생성하고 로컬 시크릿 저장소에 보관하는 절차를 추가했습니다. 기존 pgdata 볼륨 재사용, 볼륨 삭제 및 자격 증명 순환 절차를 설명했습니다.
시크릿 기반 DSN 예제 README.md	하드코딩된 비밀번호를 환경변수 기반 DSN으로 변경했습니다. 프로그램적 배치와 테스트 예제도 같은 방식을 사용하도록 갱신했습니다.

Estimated code review effort: 2 (간단) | ~10분

Merge Risk: ⚪ Minimal · up to 6e6e4

The documentation change is otherwise merge-ready after normal checks; one localized Markdown reference-formatting issue at README.md:267 should be corrected, but no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 README와 docs/index.md에 상용 라이선스 상태와 상용 사용 제한을 문서화하는 주요 변경 사항을 정확하게 요약합니다.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/public-surface-metadata

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[devin-ai-integration]

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

Devin Review found 2 new potential issues.

[seonghobae]

#345 now owns the remaining cross-owner documentation convergence required by #299's still-valid review finding. This PR is the canonical README.md / docs/index.md owner, so its eventual post-#323 reconciliation must inherit the public-documentation portion: the recovery-target observer APIs remain module-scoped; they read exactly eight PostgreSQL recovery-target settings plus pg_is_in_recovery() on a caller-owned isolated target; connection/timeout authority stays caller-owned; and the docs must not imply configuration mutation, WAL/archive/timeline/target-attainment, promotion/application-readiness, achieved RPO/RTO/HA/DR, or certification guarantees.

Do not move this stale-parent child solely to satisfy #345. First let #323 reach one stable exact-head GREEN generation, then ordinary/non-force reconcile #321 and include this two-file documentation delta in that legitimate generation. Predecessor CI/Release Acceptance does not transfer.

[seonghobae]

2026-09-18 public-surface child handoff: #352 is now Draft and based on this exact #321 head 36261459b9acaddfeb1bbd45ae027d09ff92cb9f. Ordinary two-parent reconciliation c2839c3ddb4c9e859b4319ef4e19b9f2832a35f3 preserved this PR's public/recovery/operator documentation while applying registry-safe absolute README links; 7b9f8600... added the focused preservation regression.

A later ordinary child e299bcc43675ef9fd5228d78688f0bfb6ede010f concurrently removed the bootstrap-DSN, logical-restore, OpenTelemetry, tenant/RLS, CLI-secret, bounded-input, and legacy-network-retirement public links. Because that exact diff violated the focused regression, it was treated as a deterministic RED rather than as a race or grounds for closing the PR. Minimum ordinary-forward repair 311ef7af5044425b27fd85d505734c5324f13bb7 restores only the reviewed README blob; the test remains unchanged.

Fresh compare from this exact #321 head to #352 current is 5 ahead / 0 behind with merge base exactly #321; effective paths remain only README.md and tests/test_readme_registry_links.py. Fresh child CI 35294813920 and Release Acceptance 35294813870 are queued. Keep #321 canonical parent and #352 Draft until normal parent integration and exact-child acceptance/review.

[seonghobae]

Current-head licensing review found an inherited blocker outside this PR's two-file writer scope. Parent #323 and this exact head both carry NOTICE blob 7bb6d4c35d607d3285bea796ac34b5c4538cde25, whose runtime inventory still lists LGPL Psycopg and omits the new default pg8000 runtime, while pyproject.toml and these public docs say pg8000 is default and Psycopg is optional test/dev only. Exact evidence and acceptance requirements are recorded on canonical owner issue #322. I did not broaden #321 or infer/fabricate license rights; #321 remains Draft and unmergeable as released-commercial documentation until the parent licensing notice and final artifact/SBOM/provenance are consistent.

[seonghobae]

Parent licensing repair reconciliation (2026-09-19).

Canonical parent #323 advanced to exact 797b929b1e2cbc0f8a5568bea89841d0f8c193ad with the NOTICE dependency-scope RED/GREEN repair. This docs branch was ordinary two-parent restacked without force update as e0b0bc2b9ef2d5048c0cf38961288cc41232754b.

Exact compare from current parent is behind 0 and changes only README.md plus docs/index.md; the inherited NOTICE/test repair remains ancestry rather than a copied docs delta. New CI 35436837733 and Release Acceptance 35436837732 are queued, so predecessor checks do not transfer. Draft/Proposed remains correct.

[seonghobae]

2026-09-20 KST public-surface writer census: new Draft #353 appeared directly from protected main and changes the same README.md + docs/index.md pair owned by this serialized documentation lane (with #352 as the current README-side child). Exact #353 is 074f672c57750965c70b32299d1ec6e211592f7a and its current unique candidate content is limited to the README DeepWiki badge plus a front-matter/public-overview source.

#353 has been marked as a wrong-base/single-writer repair finding and frozen for source movement. Do not overwrite this lane with #353's main-based tree. Preserve any valid #353 content only through ordinary/non-force serialization behind the current public-doc stack, or a successor that completely inherits the valid delta and reacquires exact-head evidence. No current #321/#352 source movement is required from the finding itself.