docs: add VERIFY.md control surface and features/ map for agent-driven verification

Author: johnteee

VERIFY.md

@@ -0,0 +1,69 @@
+# VERIFY — fpRust
+
+How an agent launches, checks, drives, and cleans up verification of this
+library. Read this plus the relevant `features/*.md` file before touching the
+code.
+
+`source_commit: 18a96af` · `last_verified_at: 2026-09-23` · `verification_status: passed`
+
+## Launch
+
+```bash
+cd <repo root>
+cargo test
+```
+
+Runs 120 unit tests (in-module `#[test]` blocks under `src/`) plus 24 doc
+tests — ~10s total. `test.sh` and `paralleltest.sh` are legacy wrappers;
+`cargo test` is the canonical surface. `clippy.sh` runs the linter.
+
+## Doctor
+
+```bash
+cargo test maybe::test_maybe -- --exact   # smoke: ~1s (name a real test)
+cargo build
+```
+
+A healthy tree: smoke test PASS, `cargo build` clean, full suite
+`120 passed; 0 failed` + `24 passed` doc tests.
+
+## Drive
+
+- Per feature: run `cargo test <module>::` (e.g. `cargo test fp::`) from the
+  feature file's Drive section.
+- For behavior not covered by a test, write a scratch driver **outside** the
+  repo: `cargo new /tmp/fprust-driver`, add to its `Cargo.toml`:
+
+  ```toml
+  [dependencies]
+  fp_rust = { path = "<repo root>" }
+  futures = "0.3"
+  ```
+
+  then `cargo run` — never add driver files inside the repo.
+
+## Evidence
+
+- Save `cargo test <module> -- --nocapture` output to files under a scratch
+  dir (e.g. `/tmp/fprust-evidence/`).
+- For scratch drivers, record the driver source plus its stdout.
+
+## When a check fails
+
+Classify before fixing — four different failures need four different repairs:
+
+| Class | Meaning | Repair |
+| --- | --- | --- |
+| Product regression | Library behavior changed for the worse | Report; do not edit the map or tests to match |
+| Doc drift | The map/VERIFY.md no longer matches the library | Update the doc; the product is fine |
+| Spec/oracle error | The acceptance spec or test expectation is wrong | Oracles are read-only; propose the change for review |
+| Harness failure | Toolchain, cargo, target/, or environment broke | Fix the harness; the product is fine |
+
+Never "fix" a failing check by editing the map or a test to describe the new
+behavior — that hides product regressions. If the new behavior is intentional,
+the map/test update is a separate reviewed change.
+
+## Cleanup
+
+- Remove scratch driver dirs and evidence dirs you created.
+- `git status` must show no modifications inside the repo.

features/README.md

@@ -0,0 +1,20 @@
+# Feature Map — fpRust
+
+One file per feature area. Each answers: what exists, how to drive it, what
+usually lies. Sweep order for a broad regression pass:
+`core.md` → `reactive.md` → `concurrency.md`.
+
+- [core.md](core.md) — Maybe/Optional, fp functions, common helpers
+- [reactive.md](reactive.md) — MonadIO, Publisher
+- [concurrency.md](concurrency.md) — Actor, Coroutine, Handler, sync primitives
+
+## Maintenance
+
+Each feature file carries `source_commit` + `last_verified_at` +
+`verification_status`. After any change to the covered source files, re-run
+the affected feature's Drive section and update the metadata. Do not rewrite
+the map on a schedule — re-verify on relevant code change only (event-driven,
+not calendar-driven).
+
+A `verification_status` of `failed` means the product changed; classify the
+failure per VERIFY.md §When a check fails before editing the map.

features/concurrency.md

@@ -0,0 +1,55 @@
+# Feature: concurrency
+
+`source_commit: 18a96af` · `last_verified_at: 2026-09-23` · `verification_status: passed`
+
+User goal: Actor model, coroutines (`cor_do_m`), Handler job posting, and
+sync primitives (BlockingQueue, CountdownLatch, WillAsync/WillSync).
+
+## Preconditions
+
+- Repo root; `cargo test` works.
+
+## Entry points
+
+| Area | Files | Tests |
+| --- | --- | --- |
+| Actor | `src/actor.rs` | `actor::test_*` (9) |
+| Coroutine | `src/cor.rs` | `cor::test_*` (10) |
+| Handler | `src/handler.rs` | `handler::test_*` (8) |
+| sync primitives | `src/sync.rs` | `sync::test_*` (17) |
+
+## Drive
+
+```bash
+cargo test actor::
+cargo test cor::
+cargo test handler::
+cargo test sync::
+```
+
+## Observable outcomes
+
+- Actor: receives in order; spawn child + forward; context accumulates
+  state; double-start safe; send after stop rejected; ask returns reply.
+- Coroutine: `cor_do_m` sequences yields; start idempotent; lifecycle states
+  correct; `yield_from` on a dead target returns None.
+- Handler: jobs run FIFO; post before start preserved; post after stop
+  rejected; double-start keeps running.
+- sync: BlockingQueue FIFO offer/poll + put/take, poll-empty → None,
+  take-timeout → None, is_alive/stop; CountdownLatch releases all waiters,
+  zero doesn't block, below-zero safe; WillAsync lifecycle + remove callback.
+
+## Failure paths
+
+- Actor messages out of order or send-after-stop accepted → lifecycle broken.
+- `cor_do_m` skipping yields or dead-target yield_from hanging → coroutine
+  broken.
+- Handler FIFO violated or post-after-stop accepted → ordering/guard broken.
+- BlockingQueue poll on empty blocking instead of None → non-blocking
+  contract broken; CountdownLatch not releasing all waiters → latch broken.
+
+## Evidence
+
+- `cargo test <module> -- --nocapture` output; cross-thread tests
+  (`cross_thread_producer`, `countdownlatch_cross_thread`) are the oracle
+  for concurrency claims — a single-threaded pass proves nothing there.

features/core.md

@@ -0,0 +1,49 @@
+# Feature: core
+
+`source_commit: 18a96af` · `last_verified_at: 2026-09-23` · `verification_status: passed`
+
+User goal: Optional/Maybe semantics, fp function helpers (map/reduce/filter/
+fold/compose/pipe/partial/spread), common helpers (LinkedListAsync,
+SubscriptionFunc, RawFunc/RawReceiver, get_mut, generate_id).
+
+## Preconditions
+
+- Repo root; `cargo test` works (VERIFY.md → Launch, Doctor).
+
+## Entry points
+
+| Area | Files | Tests |
+| --- | --- | --- |
+| Maybe | `src/maybe.rs` | `maybe::test_*` (17) + doc tests |
+| fp functions | `src/fp.rs` | `fp::test_*` (23) + doc tests |
+| common helpers | `src/common.rs` | `common::test_*` (14) |
+
+## Drive
+
+```bash
+cargo test maybe::
+cargo test fp::
+cargo test common::
+```
+
+## Observable outcomes
+
+- `Maybe::just(1)` present; `Maybe::val()` unwraps; `map`/`ap`/`just` doc
+  tests pin the API shape.
+- fp: `compose`/`pipe` are mirrors (`test_fp_compose_pipe_are_mirror`);
+  `partial_left_last_one`; `spread_and_call`; `fp!` macro curried forms.
+- common: `LinkedListAsync` FIFO + clone-shares-state; `SubscriptionFunc`
+  clone-equal-same-id / distinct-ids; `RawFunc`/`RawReceiver` invoke/pass.
+
+## Failure paths
+
+- `just` of a value reporting absent → presence contract broken.
+- `compose`/`pipe` no longer mirroring → ordering contract broken.
+- `LinkedListAsync` clone not sharing state or draining out of order →
+  shared-state FIFO broken.
+- `SubscriptionFunc` clones comparing unequal → identity contract broken.
+
+## Evidence
+
+- `cargo test <module> -- --nocapture` output; doc tests are part of the
+  oracle — a doc-test failure is a product failure, not a doc nit.

features/reactive.md

@@ -0,0 +1,43 @@
+# Feature: reactive
+
+`source_commit: 18a96af` · `last_verified_at: 2026-09-23` · `verification_status: passed`
+
+User goal: Rx-like MonadIO streams and Publisher pub/sub.
+
+## Preconditions
+
+- Repo root; `cargo test` works.
+
+## Entry points
+
+| Area | Files | Tests |
+| --- | --- | --- |
+| MonadIO | `src/monadio.rs` | `monadio::test_*` (13) |
+| Publisher | `src/publisher.rs` | `publisher::test_*` (14) |
+
+## Drive
+
+```bash
+cargo test monadio::
+cargo test publisher::
+```
+
+## Observable outcomes
+
+- MonadIO `of` returns value; `subscribe`/`subscribe_fn` deliver via on_next.
+- Publisher: `publish` notifies all subscribers; `map` runs on publish;
+  `unsubscribe` stops delivery to the correct observer only; subscribe
+  returns the same handle for the same observer; blocking-queue subscription
+  mode works.
+
+## Failure paths
+
+- `unsubscribe` removing the wrong observer or not stopping delivery →
+  observer-registry broken.
+- `map` not running on publish → transform chain broken.
+- Multiple subscribers not all notified → fanout broken.
+- Blocking-queue mode losing values → queue bridge broken.
+
+## Evidence
+
+- `cargo test <module> -- --nocapture` output.