feat(library): separate official and private legal sources

[Eysn0130]

What changed

• Add a team-maintained official catalog lifecycle: install, monotonic update, enable/disable, uninstall, resumable official-source download, immutable releases, and per-source byte/hash verification.
• Add a physically separate per-OS-user legal-reference library with explicit local add/delete, owner-only permissions, immutable snapshots, and read-only private_* Agent operations.
• Keep Analytix case projects outside DeepLaw and document the future official-only integration gate.
• Upgrade the Codex/Claude plugin contract to one read-only MCP tool with eight explicit operations.
• Record the 28-document catalog, source table, extraction-risk boundaries, and a v0.3 white-box benchmark that asserts risky PDFs remain in uncertain_evidence.

Why

DeepLaw needed a complete lifecycle for official team updates and user-owned legal references without mixing authority, rankings, storage, or case-project data. The previous package could build a release but did not let a fresh Agent installation acquire the maintained catalog or safely manage a separate private reference scope.

During final cold-start validation, a transient official-site HTTP 502 also exposed an overly short retry window. The downloader now uses bounded exponential backoff, preserves only hash-verified cache entries, and still refuses non-official mirror fallback.

User and developer impact

• A new user can run uv tool install . and deeplaw official install to fetch all 28 declared sources from official URLs and build the same immutable release locally.
• Team catalog additions arrive through explicit deeplaw official update; users can disable or uninstall official data without touching private references.
• User uploads remain local, unverified, authority rank 0, and physically isolated from the official catalog.
• MCP stays read-only; uploads and deletes are CLI administration only.
• Existing non-legal Analytix behavior is unchanged because no Analytix code is modified.

Validation

• uv run pytest — 155 passed
• uv run ruff check .
• uv lock --check
• git diff --check
• 26 JSON/schema/catalog/benchmark files parsed and benchmark hashes revalidated
• wheel and sdist built; required contracts, catalog, and governance overlay verified inside the wheel
• clean-home official acquisition: 28/28 cached sources hash-verified, 28 documents, 3234 segments, 111 relations
• benchmark: 32/32 white-box cases, including 6 assertions that extraction-risk material appears only in uncertain_evidence; 109/109 receipts verified
• isolated Codex marketplace install and live stdio MCP call: one read-only tool, eight operations
• private-library add/search/delete smoke test with 0700/0600/0400 permissions and zero retained sources/releases after deletion

Honest limits

This remains a 0.3.0 alpha candidate, not a production legal opinion system or a cross-system leaderboard result. The catalog is protected by HTTPS, monotonic sequence, and hashes but is not yet cryptographically signed. Claude Code and OpenCode CLIs were not present on this host, so their manifests are statically validated rather than claimed as host-runtime tests.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f39f418b39

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".