M4 AP-4: BYOM example + docs (guide, API reference, offline example, CI smoke)

[STiFLeR7]

Summary

AP-4 of Milestone M4 (BYOM recovery library). Ships the developer-facing surface for the recovery mechanism that AP-1–AP-3 already landed — no new recovery logic. Everything an outside developer needs to add Re-grounding Recovery to their own agent, on the public cairn API, proven offline.

• Public reference infra: export FileCheckpointStore / FileEffectLedger (aliases of the concrete cairn.runtime.* classes) so examples/docs use only the top-level surface — the sole src/ change (__init__.py +4).
• Runnable example examples/byom_recovery.py: three deterministic demos on a mock model — demo_primitives (bring-your-own-loop), demo_agent (batteries-included), demo_effect_once (torn side-effect → exactly-once). Plus an opt-in stdlib Ollama adapter (CAIRN_OLLAMA=1), never run in CI.
• Guide docs/guide/recovery-in-your-agent.md: both paths, exactly-once effects, local-model run, honest 0.x/claims scope.
• API reference docs/guide/public-api-reference.md: every name in cairn.__all__ (verified against the live 20-name surface).
• Minimal CI .github/workflows/ci.yml: pytest on 3.10/3.12 — the example smoke test rides along. Tests only; no publish/release/tag/deploy (v1.0 hold intact).
• README: one additive pointer to the guide + example.

Governance

• 0.x, no publish/release/announce — CI runs tests only.
• ADR-0007 (no hardcoded harness): goal/model/effect wired in the example, not the library.
• ADR-0009 (honest scope): guide states plainly that the live claim C1 is not confirmed; the library lets a user reproduce the evidence on their own model.
• recover() deliberately takes no goal param (AP-3 deviation; carried in the checkpoint) — reflected in the reference. Design-spec §5 update is tracked for AP-5.

Test Plan

• Full suite green: 137 passed (was 131; +3 public-export guard, +3 example smoke).
• python examples/byom_recovery.py prints exactly 3 lines, offline, showing real recovery (regrounded=1, recovery_tax=1, exactly-once skip).
• Example & guide use public API only (no cairn.runtime/harness/state reach-through).
• No secrets / no .env; CI has no outward steps.
• Independent holistic review: READY TO MERGE (10/10 axes PASS).
• Maintainer review + merge (yours).

🤖 Generated with Claude Code

[STiFLeR7]

Maintainer review — APPROVED for merge ✅

Reviewed from my side. This slice ships the BYOM developer surface without touching validated recovery logic — exactly AP-4's scope.

• Suite green: 137 passed (was 131; +6 new). Example runs offline and prints real recovery numbers (regrounded=1, recovery_tax=1, exactly-once skip).
• Public-API only in example + guide; sole src/ change is the two aliased exports.
• Governance intact: CI is test-only (no publish/release/tag), 0.x + v1.0 hold untouched, ADR-0007 & ADR-0009 honored. No secrets, no .env.
• Docs accurate: API reference matches the live cairn.__all__; honest-scope note present (C1 not confirmed); recover() no-goal deviation correctly reflected.

MERGEABLE / CLEAN. Merging to master. Spec §5/§9 update + trackers/CHANGELOG tracked for AP-5.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3ab5fe471e

ℹ️ 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".

[chatgpt-codex-connector]

Include main in the push trigger

In this checkout the integration branch is main (the recent merge commits are on main, and there is no local master branch), so this workflow will not run on post-merge or direct pushes to the default branch; it only runs for master, milestone-*, and phase-*. Please add main here or remove the branch filter so CI actually protects the branch changes land on.

Useful? React with 👍 / 👎.