[RCmerci]

The 16 interfaces under **/spec/**/*.mli did not consistently follow the repository's journal-mli-spec structure. Organize each with TLDR first and a complete minimal usage example second, followed by applicable construction, capability, lifecycle/recovery and observation sections. Clarify state installation, typed outcomes and resource ownership in English while preserving existing API contracts and behavior.

The diff is limited to these spec interfaces. Core declarations are moved where dependencies permit; large dependent signatures retain their order and use accurate linked summaries.

Validation on the final source:

• All spec directories build: dune build @app/spec/worker_coordination/all @logseq_overlay_db/spec/all @logseq_sync/spec/all @logseq_db_worker/spec/all.
• Compiler AST comparison preserves all 906 top-level signature items, removing only documentation attributes and source locations before comparison.
• All 16 minimal examples typecheck against the built public interfaces; all 30 documentation code blocks parse.
• 908 Alcotest cases across 19 suites and the Worker coordination contract checks (24 positive, 31 negative) pass.
• Required section ordering, English text and git diff --check pass. Independent read-only review passes after correcting the coordinator example to use an already bootstrapped state.

Remaining environment/validation blockers:

• The full dune build @all app/native_embed.exe.o and overall dune runtest --force exit unsuccessfully because the installed LUI lacks Lui_protocol.VirtualWindow and the ~virtual_rows argument to Lui_app.create_with_extensions. The successful tests above are partial regression evidence, not a fully green App run.
• Apple build preflight also rejects the existing LUI Swift checkout because its revision differs from the repository's locked pin. Existing dependency checkouts, switches and pins were preserved.
• spec-dev-tool check --all reports six pre-existing invalid decision documents; their contents are unchanged from the base revision.

Source identity: base b20511e9f23c3bae8427dab9e235d2c15cfa3b02, head dc612cbb7a669c9188027bcc9d09a68aa369e0f8; reviewed diff SHA256 c6b01112d4091f99aefb9e8e2c3d60b595f75f70206f89ade608e0c2e46512e7.

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-07T12:15:15.963686Z	dc612cb	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.