adityamukho · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026
@@ -41,7 +41,10 @@ jobs:
       - name: Install required cargo
         run: cargo install clippy-sarif sarif-fmt
 
-      - name: Run rust-clippy
+      - name: Run rust-clippy (strict — fails on warnings)
+        run: cargo clippy --all-features -- -D warnings
+
+      - name: Run rust-clippy (SARIF upload for code scanning)
         run:
           cargo clippy
           --all-features

@@ -15,7 +15,10 @@ permissions:
 jobs:
   build:
 
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
 
     steps:
     - uses: actions/checkout@v3

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.19.0 — Phase 7.9: Publish Prep (2026-04-08)
+
+### Changed (breaking — internal visibility only)
+- `Minigraf::repl()` factory method replaces direct `Repl::new(FactStorage)` constructor — users call `db.repl().run()` instead
+- All internal types narrowed to `pub(crate)`: `FactStorage`, `PersistentFactStorage`, `FileHeader`, `StorageBackend`, `DatalogExecutor`, `PatternMatcher`, `Fact`, `TxId`, `VALID_TIME_FOREVER`, `Wal`, and all related internals
+- `Minigraf::inner_fact_storage()` removed (was unused)
+
+### Added
+- `Minigraf::repl(&self) -> Repl<'_>` — constructs an interactive REPL session; `Repl` now borrows `&Minigraf` for lifetime safety
+- Full rustdoc on all public API items with `# Examples` doctests
+- `[package.metadata.docs.rs]` in `Cargo.toml` — docs.rs builds with `all-features = true`
+- `#![warn(missing_docs)]` — enforces documentation coverage going forward
+- crates.io and docs.rs badges in `README.md`
+- Installation section in `README.md` (`cargo add minigraf` / `[dependencies]` block)
+- macOS and Windows added to CI test matrix (`rust.yml`)
+- Strict `cargo clippy -- -D warnings` step in `rust-clippy.yml`
+
+### Fixed
+- Bare `.unwrap()` in library code replaced with `.expect("lock poisoned")` (RwLock operations in `cache.rs`, `evaluator.rs`) and `.expect("WAL not initialized")` (`db.rs`)
+- `FileHeader::to_bytes` now takes `self` by value (clippy `wrong_self_convention`)
+- Broken intra-doc link `[Repl::run]` in `db.rs` fixed to `[crate::repl::Repl::run]`
+
+788 tests.
+
 ## v0.18.0 — Phase 7.8: Prepared Statements (2026-04-04)
 
 ### Added

@@ -167,7 +167,7 @@ Auto-migrates v1/v2/v3/v4/v5/v6 → v7 on open/checkpoint.
 
 ## Test Coverage
 
-**780 tests passing** (unit + integration + doc).
+**788 tests passing** (unit + integration + doc).
 See `TEST_COVERAGE.md` for the full per-file breakdown.
 
 **Testing conventions** — see the Testing Conventions section below before writing any tests.

@@ -1,6 +1,6 @@
 [package]
 name = "minigraf"
-version = "0.18.0"
+version = "0.19.0"
 edition = "2024"
 description = "Zero-config, single-file, embedded graph database with bi-temporal Datalog queries"
 license = "MIT OR Apache-2.0"
@@ -11,6 +11,10 @@ categories = ["database-implementations", "embedded"]
 readme = "README.md"
 documentation = "https://docs.rs/minigraf"
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
 [dependencies]
 serde = { version = "1.0", features = ["derive"] }
 postcard = { version = "1.0", features = ["alloc"] }

@@ -1,11 +1,13 @@
 # Minigraf
 
+[![crates.io](https://img.shields.io/crates/v/minigraf.svg)](https://crates.io/crates/minigraf)
+[![docs.rs](https://docs.rs/minigraf/badge.svg)](https://docs.rs/minigraf)
 [![Build Status](https://github.com/adityamukho/minigraf/actions/workflows/rust.yml/badge.svg)](https://github.com/adityamukho/minigraf/actions/workflows/rust.yml)
 [![Clippy Status](https://github.com/adityamukho/minigraf/actions/workflows/rust-clippy.yml/badge.svg)](https://github.com/adityamukho/minigraf/actions/workflows/rust-clippy.yml)
 [![Coverage](https://codecov.io/gh/adityamukho/minigraf/branch/main/graph/badge.svg)](https://codecov.io/gh/adityamukho/minigraf)
 [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/adityamukho/minigraf#license)
 [![Rust Edition](https://img.shields.io/badge/rust-2024-orange.svg)](https://blog.rust-lang.org/2024/10/17/Rust-1.82.0.html)
-[![Phase](https://img.shields.io/badge/phase-7.8%20complete-blue.svg)](https://github.com/adityamukho/minigraf/blob/main/ROADMAP.md)
+[![Phase](https://img.shields.io/badge/phase-7.9%20complete-blue.svg)](https://github.com/adityamukho/minigraf/blob/main/ROADMAP.md)
 
 > **Embedded graph memory for AI agents, mobile apps, and the browser** — the SQLite of bi-temporal graph databases
 
@@ -34,6 +36,19 @@ Minigraf is a **single-file embedded graph database** that lets you:
 5. **Graph-native** - Facts (Entity-Attribute-Value) are literally edges
 6. **LLM-friendly** - The small, uniform grammar (`[?e :attr ?v]` patterns, no JOIN variants, no subquery nesting) is easy for AI coding assistants to generate correctly from a few examples; the entire language fits in a system prompt
 
+## Installation
+
+```toml
+[dependencies]
+minigraf = "0.19"
+```
+
+Or via cargo:
+
+```sh
+cargo add minigraf
+```
+
 ## Quick Start
 
 ```rust

@@ -498,11 +498,11 @@ Current v5 stores index data as paged blobs (page type `0x11`). v6 introduces pr
 
 ---
 
-## Phase 7: Datalog Completeness 🔄 IN PROGRESS
+## Phase 7: Datalog Completeness ✅ COMPLETE
 
 **Goal**: Complete the Datalog query engine — negation, aggregation, disjunction, temporal range queries, and prepared statements
 
-**Status**: 🔄 In Progress (7.1a + 7.1b + 7.2a + 7.2b + 7.3 + 7.4 + 7.5 + 7.6 + 7.7a complete ✅)
+**Status**: ✅ Complete (7.1a + 7.1b + 7.2a + 7.2b + 7.3 + 7.4 + 7.5 + 7.6 + 7.7a + 7.7b + 7.8 + 7.9 complete)
 
 **Priority**: 🔴 Critical — without these, realistic production queries cannot be expressed in Datalog
 
@@ -520,8 +520,8 @@ Current v5 stores index data as paged blobs (page type `0x11`). v6 introduces pr
 - **7.6** ✅ Temporal Metadata Bindings + Range Queries (`:db/valid-from`, `:db/valid-to`, `:db/tx-count` as queryable pseudo-attributes; unlocks Time Interval, Time-Point Lookup, Time-Interval Lookup query classes)
 - **7.7a** Window Functions — `sum`, `count`, `min`, `max`, `avg`, `rank`, `row-number` with unbounded-preceding frame; `FunctionRegistry` introduced (built-ins only); `lag`/`lead` and sliding frames deferred to post-1.0 backlog
 - **7.7b** ✅ User-Defined Functions (UDFs) — public `register_aggregate`/`register_predicate` API on the `FunctionRegistry` introduced in 7.7a
-- **7.8** Prepared Statements (parse + plan once, execute many times, temporal bind slots; implemented after full clause set including predicate-argument positions)
-- **7.9** Publish Prep (crates.io — API cleanup, rustdoc, clippy, `unwrap` audit, CI matrix)
+- **7.8** ✅ Prepared Statements (parse + plan once, execute many times, temporal bind slots; implemented after full clause set including predicate-argument positions)
+- **7.9** ✅ Publish Prep (crates.io — API cleanup, rustdoc, clippy, `unwrap` audit, CI matrix)
 
 ### 7.1a Stratified Negation — `not` ✅ COMPLETE
 
@@ -1082,10 +1082,12 @@ The query optimizer uses selectivity estimates to pick join order. Different `:a
 
 ---
 
-### 7.9 Publish Prep (crates.io)
+### 7.9 Publish Prep (crates.io) ✅ COMPLETE
 
 **Goal**: Make the public API clean, documented, and safe before publishing to crates.io.
 
+**Status**: ✅ Complete (v0.19.0, 2026-04-08)
+
 **Scope**:
 - Narrow `lib.rs` exports — expose only `Minigraf`, `WriteTransaction`, and the query/result types; mark internal types (`PersistentFactStorage`, `FileHeader`, `PAGE_SIZE`, `Repl`, `Wal`, etc.) as `pub(crate)` or remove re-exports
 - Rustdoc sweep — add doc comments with examples to all public API items
@@ -1607,7 +1609,7 @@ When evaluating features, ask:
 - ✅ Phase 7.7a: Complete (April 2026) - Window functions (`sum/count/min/max/avg/rank/row-number :over`), `FunctionRegistry`, 705 tests
 - ✅ Phase 7.7b: Complete (April 2026) - User-Defined Functions (`register_aggregate`/`register_predicate`), 727 tests
 - ✅ Phase 7.8: Complete (April 2026) - Prepared statements (`$slot` bind tokens, temporal bind slots, plan reuse), 780 tests
-- 🎯 Phase 7.9: Publish prep (crates.io API cleanup, Rustdoc sweep, `unwrap` audit) - **NEXT**
+- ✅ Phase 7.9: Complete (April 2026) - Publish prep (crates.io API cleanup, Rustdoc sweep, `unwrap` audit, CI matrix), 788 tests
 - 🎯 Phase 8: 3-4 months (Cross-platform — WASM, mobile, language bindings)
 - 🎯 Phase 9: Ongoing (Ecosystem — integration examples, cookbook, GraphRAG/LangChain examples)
 - 🎯 **v1.0.0: 9-12 months**
@@ -1618,21 +1620,22 @@ When evaluating features, ask:
 
 ## Current Focus
 
-**Right Now**: Phase 7.8 Complete — Phase 7.9 Next (Publish Prep)
+**Right Now**: Phase 7.9 Complete — Phase 8 Next (Cross-Platform Expansion)
 
-**Phase 7.8 Achievements**:
-1. ✅ `$identifier` bind slot tokens in entity, value, `:as-of`, and `:valid-at` positions
-2. ✅ `EdnValue::BindSlot`, `AsOf::Slot`, `ValidAt::Slot`, `Expr::Slot` AST variants
-3. ✅ `BindValue` enum: `Entity(Uuid)`, `Val(Value)`, `TxCount(u64)`, `Timestamp(i64)`, `AnyValidTime`
-4. ✅ `PreparedQuery` struct — stores AST + optimised plan; re-executes against current fact store state
-5. ✅ `Minigraf::prepare(query_str) -> Result<PreparedQuery>` public API method
-6. ✅ `PreparedQuery::execute(bindings) -> Result<QueryResult>` — deep-clone + AST walk substitution
-7. ✅ Panic guards in `executor.rs` / `storage.rs` for unsubstituted slots reaching runtime
-8. ✅ `BindValue` and `PreparedQuery` re-exported from `lib.rs`
-9. ✅ `tests/prepared_statements_test.rs` — 17 integration tests; 780 tests passing; version bumped to v0.18.0
+**Phase 7.9 Achievements**:
+1. ✅ `Minigraf::repl(&self) -> Repl<'_>` factory method — `Repl` now borrows `&Minigraf`
+2. ✅ All internal types narrowed to `pub(crate)`: `FactStorage`, `PersistentFactStorage`, `FileHeader`, `StorageBackend`, `DatalogExecutor`, `PatternMatcher`, `Fact`, `TxId`, `VALID_TIME_FOREVER`, `Wal`, etc.
+3. ✅ Full rustdoc on all public API items with `# Examples` doctests; 8 new doctests
+4. ✅ `[package.metadata.docs.rs]` in `Cargo.toml` — docs.rs builds with `all-features = true`
+5. ✅ `#![warn(missing_docs)]` — enforces documentation coverage going forward
+6. ✅ Bare `.unwrap()` in library code replaced with `.expect("lock poisoned")` / `.expect("WAL not initialized")`
+7. ✅ `cargo clippy -- -D warnings` clean
+8. ✅ macOS and Windows added to CI test matrix (`rust.yml`)
+9. ✅ crates.io and docs.rs badges + Installation section in `README.md`
+10. ✅ 788 tests passing; version bumped to v0.19.0
 
-**Immediate Next Steps (Phase 7.9)**:
-1. Publish Prep — narrow `lib.rs` exports, Rustdoc sweep, `unwrap` audit, `cargo doc --no-deps` clean
+**Immediate Next Steps (Phase 8)**:
+1. Cross-Platform Expansion — WASM, mobile, language bindings
 
 **Key Decisions Made**:
 - ✅ Datalog query language (simpler, better for temporal)
@@ -1648,4 +1651,4 @@ See [GitHub Issues](https://github.com/adityamukho/minigraf/issues) for specific
 
 ---
 
-Last Updated: Phase 7.8 Complete - Prepared statements (`$slot` bind tokens, temporal bind slots, plan reuse), 780 tests passing, v0.18.0 (April 2026)
+Last Updated: Phase 7.9 Complete - Publish prep (API cleanup, Rustdoc sweep, `unwrap` audit, CI matrix), 788 tests passing, v0.19.0 (April 2026)
@@ -1,10 +1,10 @@
 # Minigraf Test Coverage Report
 
-**Last Updated**: Phase 7.8 COMPLETE - Prepared statements, 780 tests ✅
+**Last Updated**: Phase 7.9 COMPLETE - Publish prep, 788 tests ✅
 
 ## Test Summary
 
-**Total Tests**: 780 ✅ (773 passing, 7 ignored)
+**Total Tests**: 788 ✅ (781 passing, 7 ignored)
 - ✅ 524 unit tests (lib, +19 from `prepared.rs`)
 - ✅ 24 bi-temporal tests (integration)
 - ✅ 10 complex query tests (integration)
@@ -27,13 +27,27 @@
 - ✅ 12 window function tests (integration, Phase 7.7a — cumulative sum/count/min/avg, rank with ties, row-number, partition-by, desc ordering, mixed aggregate+window, edge cases, lag/lead parse rejection)
 - ✅ 14 UDF tests (integration, Phase 7.7b — custom aggregates, custom predicates, UDF as window function, name collision guards, runtime errors, thread safety)
 - ✅ 17 prepared statement tests (integration, Phase 7.8 — entity/value/as-of/valid-at slots, combined temporal+entity, AnyValidTime, error paths, plan reuse)
-- ✅ 15 doc tests
+- ✅ 23 doc tests (15 prior + 8 new from Phase 7.9 rustdoc sweep on public API items)
 
-**Status**: ✅ **All 773 tests passing** (7 ignored: confirmed or+neg-cycle stratification bug)
+**Status**: ✅ **All 781 tests passing** (7 ignored: confirmed or+neg-cycle stratification bug)
+
+## Phase 7.9 Completion Status: ✅ COMPLETE
+
+**Phase 7.9 Features** (current, complete):
+- ✅ `Minigraf::repl(&self) -> Repl<'_>` factory method — `Repl` now borrows `&Minigraf` for lifetime safety
+- ✅ All internal types narrowed to `pub(crate)`: `FactStorage`, `PersistentFactStorage`, `FileHeader`, `StorageBackend`, `DatalogExecutor`, `PatternMatcher`, `Fact`, `TxId`, `VALID_TIME_FOREVER`, `Wal`, etc.
+- ✅ Full rustdoc on all public API items with `# Examples` doctests; 8 new doctests added
+- ✅ `[package.metadata.docs.rs]` in `Cargo.toml` — docs.rs builds with `all-features = true`
+- ✅ `#![warn(missing_docs)]` — enforces documentation coverage going forward
+- ✅ Bare `.unwrap()` in library code replaced with `.expect("lock poisoned")` / `.expect("WAL not initialized")`
+- ✅ `cargo clippy -- -D warnings` clean
+- ✅ macOS and Windows added to CI test matrix (`rust.yml`)
+- ✅ crates.io and docs.rs badges + Installation section in `README.md`
+- ✅ 788 tests passing (unit + integration + doc); version bumped to v0.19.0
 
 ## Phase 7.8 Completion Status: ✅ COMPLETE
 
-**Phase 7.8 Features** (current, complete):
+**Phase 7.8 Features** (complete):
 - ✅ `EdnValue::BindSlot(String)`, `AsOf::Slot(String)`, `ValidAt::Slot(String)`, `Expr::Slot(String)` AST variants in `types.rs`
 - ✅ `BindValue` enum in `src/query/datalog/prepared.rs`: `Entity(Uuid)`, `Val(Value)`, `TxCount(u64)`, `Timestamp(i64)`, `AnyValidTime`
 - ✅ `PreparedQuery` struct — stores parsed AST + optimised plan + `Arc` handles to fact store and registries; re-executes against live fact store state
@@ -686,9 +700,9 @@ cargo test -- --nocapture
 
 ## Conclusion
 
-**Phase 7.8 Status**: ✅ **COMPLETE**
+**Phase 7.9 Status**: ✅ **COMPLETE**
 
-**Test Quality**: ✅ **Excellent** — High confidence in all Phase 3-7.8 features
+**Test Quality**: ✅ **Excellent** — High confidence in all Phase 3-7.9 features
 
 **Strengths**:
 - WAL crash safety verified with real `mem::forget` simulation
@@ -709,14 +723,15 @@ cargo test -- --nocapture
 - Window functions verified: cumulative aggregates, rank/row-number, partition-by, desc ordering, mixed aggregate+window (Phase 7.7a)
 - User-defined functions verified: custom aggregates, custom predicates, UDF as window function, name collision guards, runtime error handling, thread safety (Phase 7.7b)
 - Prepared statements verified: entity/value/as-of/valid-at slot positions, AnyValidTime, combined temporal+entity (agentic loop pattern), plan reuse, all error paths (Phase 7.8)
-- 780 tests covering all Phase 3-7.8 features
+- Public API surface verified via rustdoc doctests: `Minigraf::open`, `execute`, `prepare`, `repl`, `WriteTransaction`, `OpenOptions` (Phase 7.9)
+- 788 tests covering all Phase 3-7.9 features
 
-**Confidence Level**: ✅ **Production-ready for Phase 7.8 scope**
+**Confidence Level**: ✅ **Production-ready for Phase 7.9 scope**
 
-**Readiness for Phase 7.9**: ✅ **Ready to proceed**
+**Readiness for Phase 8**: ✅ **Ready to proceed**
 
-The prepared-statement-capable, UDF-capable, window-function-capable, disjunction + aggregation + arithmetic/predicate expression capable, stratified-negation-capable, on-disk B+tree indexed, packed, cached bi-temporal Datalog engine is **solid, well-tested, and benchmarked**.
+The publish-ready, prepared-statement-capable, UDF-capable, window-function-capable, disjunction + aggregation + arithmetic/predicate expression capable, stratified-negation-capable, on-disk B+tree indexed, packed, cached bi-temporal Datalog engine is **solid, well-tested, documented, and benchmarked**.
 
 ---
 
-**Next Steps**: Begin Phase 7.9 (Publish Prep — crates.io API cleanup, Rustdoc sweep, `unwrap` audit)
+**Next Steps**: Begin Phase 8 (Cross-Platform Expansion — WASM, mobile, language bindings)
@@ -219,7 +219,7 @@ impl Drop for Inner {
 /// # Fact Size Limit (file-backed databases only)
 ///
 /// Each fact persisted to a `.graph` file must serialise to at most
-/// [`crate::storage::packed_pages::MAX_FACT_BYTES`] bytes (currently 4 080).
+/// 4 080 bytes (the per-page capacity limit).
 ///
 /// In practice, `Value::String` content is limited to roughly **3 900–4 000 bytes**
 /// depending on entity and attribute name lengths.
@@ -600,17 +600,19 @@ impl Minigraf {
         )
     }
 
-    /// Returns a clone of the underlying `FactStorage` for use by the REPL.
+    /// Return an interactive REPL that reads commands from stdin.
     ///
-    /// Cloning is cheap — `FactStorage` is `Arc`-backed.
+    /// The REPL borrows the database for the duration of the session.
+    /// Call [`crate::repl::Repl::run`] to start the interactive loop.
     ///
-    /// # Warning
-    /// This method bypasses the WAL and the write lock. It is intended **only** for
-    /// the built-in REPL (`src/main.rs`). External callers should use
-    /// [`Minigraf::execute`] or [`Minigraf::begin_write`] to ensure crash safety.
-    #[doc(hidden)]
-    pub fn inner_fact_storage(&self) -> crate::graph::FactStorage {
-        self.inner.fact_storage.clone()
+    /// # Example
+    /// ```no_run
+    /// # use minigraf::Minigraf;
+    /// let db = Minigraf::in_memory().unwrap();
+    /// db.repl().run();
+    /// ```
+    pub fn repl(&self) -> crate::repl::Repl<'_> {
+        crate::repl::Repl::new(self)
     }
 
     /// Compute the WAL sidecar path for a given database path.
@@ -711,7 +713,7 @@ impl Minigraf {
     /// # Example
     /// ```
     /// # use minigraf::db::Minigraf;
-    /// # use minigraf::graph::types::Value;
+    /// # use minigraf::Value;
     /// let db = Minigraf::in_memory().unwrap();
     /// db.register_aggregate(
     ///     "mysum",
@@ -771,7 +773,7 @@ impl Minigraf {
     /// # Example
     /// ```
     /// # use minigraf::db::Minigraf;
-    /// # use minigraf::graph::types::Value;
+    /// # use minigraf::Value;
     /// let db = Minigraf::in_memory().unwrap();
     /// db.register_predicate(
     ///     "email?",
@@ -939,7 +941,7 @@ impl<'a> WriteTransaction<'a> {
                     *wal = Some(WalWriter::open_or_create(&wal_path)?);
                 }
 
-                let wal_writer = wal.as_mut().unwrap();
+                let wal_writer = wal.as_mut().expect("WAL not initialized");
                    wal_writer.append_entry(tx_count, facts)?;
                 pfs.mark_dirty();
                 *wal_entry_count += 1;
@@ -1012,6 +1014,14 @@ impl Drop for WriteTransaction<'_> {
 mod tests {
     use super::*;
 
+    // ── repl factory ────────────────────────────────────────────────────────
+
+    #[test]
+    fn repl_constructed_from_db() {
+        let db = Minigraf::in_memory().unwrap();
+        let _repl = db.repl();
+    }
+
     // ── in_memory basic ─────────────────────────────────────────────────────
 
     #[test]