WIP

haskell/notes/001-garnet.md

@@ -56,3 +56,57 @@ It appears far enough along to prove the interop path and demonstrate the toolin
 reuse without more work on build integration, test coverage, and dependency stability.
 
 In reviewer terms: promising experiment, useful reference, not ready to trust as infrastructure.
+
+## Ecosystem Maturity
+
+Rust/Haskell interop is uneven.
+
+The low-level foundation is mature enough. Haskell has had a solid FFI story for years, and Rust is comfortable exporting or importing a C ABI.
+If the boundary is narrow and C-like, the approach is viable.
+
+The weak part is the tooling layer. Header generation on the Rust side is serviceable. Binding generation on the Haskell side is improving, but it
+still looks early. The Garnet repo reflects that gap exactly: the ABI path works, but the workflow still needs custom glue and hand-written cleanup.
+
+Reviewer verdict: mature enough for disciplined teams, not mature enough to feel easy.
+
+## Calling Direction
+
+### Calling Rust From Haskell
+
+This is the easier direction.
+
+Rust can expose a conventional C ABI, and Haskell can consume it through its normal FFI mechanisms. That keeps the ownership model and runtime story
+relatively simple, at least compared with the reverse direction.
+
+This is the path Garnet takes, and it is the right first choice.
+
+### Calling Haskell From Rust
+
+This is the harder direction.
+
+Once Rust starts calling into Haskell, the GHC runtime becomes part of the design. That raises the complexity around runtime initialization,
+threading, callbacks, shutdown, and operational correctness. It is possible, but it is a sharper tool and a worse default.
+
+Reviewer verdict: call Rust from Haskell when possible; only call Haskell from Rust when there is a strong reason.
+
+## Toolchain Recommendation
+
+Current best default:
+
+- keep the ABI small and C-shaped
+- use Rust `extern "C"` plus `repr(C)` at the boundary
+- use `cbindgen` to emit headers
+- keep Haskell bindings thin
+- write the final Haskell API by hand
+
+That is not glamorous, but it is the most credible path today.
+
+For teams that want the lowest risk, hand-written Haskell FFI bindings are still easier to trust than a large generated surface. For teams exploring
+automation, `hs-bindgen` is interesting but still reads as early-stage technology.
+
+## Practical Read On Garnet
+
+Garnet is valuable because it shows both sides of the story.
+
+It shows that the basic interop path works. It also shows that the surrounding tooling is not yet smooth enough to disappear into the background.
+That makes it a good experiment and a fair warning.

haskell/notes/_template.md

@@ -0,0 +1,77 @@
+# <Project> Findings
+
+Date: YYYY-MM-DD
+Path inspected: `<path>`
+
+## Summary
+
+`<path>` is a <one-line description>.
+
+The repo is trying to prove or build <main idea>.
+
+Verdict in one sentence: <works as X, does not yet read as Y>.
+
+## What It Contains
+
+- `<path/to/file-or-dir>` - <why it matters>
+- `<path/to/file-or-dir>` - <why it matters>
+- `<path/to/file-or-dir>` - <why it matters>
+- `<path/to/file-or-dir>` - <why it matters>
+
+## Review
+
+State the main architectural idea plainly.
+
+Say what the repo gets right.
+
+Say what still looks early, brittle, overcomplicated, missing, or high-risk.
+
+Call out the main constraint directly: <build glue / unstable deps / missing tests / wrapper burden / runtime complexity / unclear ownership / etc.>
+
+Keep this section short and judgmental in the useful sense. Write like a reviewer, not a tour guide.
+
+## Pros
+
+- <clear strength>
+- <clear strength>
+- <clear strength>
+- <clear strength>
+
+## Cons
+
+- <clear weakness>
+- <clear weakness>
+- <clear weakness>
+- <clear weakness>
+
+## Status
+
+Current status: <working prototype / partial implementation / mature subsystem / etc.>
+
+State what is already proven.
+
+State what would still need work before repeated reuse or production use.
+
+End with a short reviewer verdict: <promising experiment / solid foundation / not ready to trust / etc.>
+
+## Optional Sections
+
+Add only if they help:
+
+- `## Ecosystem Maturity`
+- `## Calling Direction`
+- `## Toolchain Recommendation`
+- `## Practical Read On <Project>`
+- `## Risks`
+- `## Next Problems`
+
+## Writing Rules
+
+- Use Title Case for headings.
+- Keep the tone direct and critical.
+- Prefer short paragraphs over long walkthroughs.
+- Do not write like an assistant explaining itself.
+- Avoid filler such as "it appears" unless the point is genuinely uncertain.
+- Prefer verdicts over summaries when the evidence is already clear.
+- If something is fragile, say it is fragile.
+- If something is promising but early, say that plainly.