chore: update changelogs and documentation across multiple crates

- cardano-vrf-pure: reorganized README with highlights, crate layout, and Haskell↔Rust mapping; updated CHANGELOG with new features and fixes.
- heapwords: added new features and expanded README; updated CHANGELOG for version 0.1.0.3.
- measures: ported Haskell `Cardano.Measure` to Rust; updated README and CHANGELOG for version 0.1.0.2.
- orphans-deriving-via: added README and updated CHANGELOG for version 0.1.0.2.
- deepseq: added initial README and CHANGELOG for version 0.1.0.
- nothunks: added README and CHANGELOG for version 0.1.0.

Author: FractionEstate

.github/tasks/phase-00-workspace-roadmap.md

@@ -43,6 +43,8 @@ and ensures no crate is left without an explicit plan or acceptance criteria.
 ## Crate-by-crate checklist
 
 ### base-deriving-via
+- [x] Document deriving helpers, macro usage, and Haskell mapping for the Rust
+      port.
 - [ ] Audit Haskell `Cardano.Base.DerivingVia` modules to confirm all deriving
       helpers are present.
 - [ ] Port any Template Haskell-based instances to macro-free Rust equivalents
@@ -52,16 +54,20 @@ and ensures no crate is left without an explicit plan or acceptance criteria.
 - [ ] Cross-reference usage sites in dependent crates to confirm API coverage.
 
 ### cardano-base
+- [x] Document feature flag primitives, README/CHANGELOG parity, and Haskell
+      module mapping for the Rust port.
 - [ ] Catalogue all exported modules from Haskell `Cardano.Base.*` and map them
       to existing Rust modules.
 - [ ] Implement missing primitives (e.g. canonical JSON, text utilities) with
       thorough tests.
 - [ ] Mirror the error-handling semantics (Either vs Result) and documented edge
       cases from Haskell.
-- [ ] Document migration notes for downstream crates that previously depended on
+- [x] Document migration notes for downstream crates that previously depended on
       the Haskell version.
 
 ### cardano-binary
+- [x] Document canonical CBOR helpers, README/CHANGELOG parity, and Haskell
+      module mapping for the Rust port.
 - [x] Align CBOR encoding/decoding semantics with Haskell (including
       canonical/deterministic encoding rules).
 - [x] Import or regenerate golden vectors from the Haskell test suite and make
@@ -73,6 +79,8 @@ and ensures no crate is left without an explicit plan or acceptance criteria.
 - [x] Track structured work via [Phase 07 – CBOR Encoding Parity](phase-07-cbor-parity.md). ✅ **COMPLETED**
 
 ### cardano-crypto-class
+- [x] Document cryptographic primitives, README/CHANGELOG parity notes, and
+      regeneration workflows for DSIGN/KES/VRF/hash modules.
 - [x] Track progress through [Phase 03 – Cardano VRF Parity](phase-03-vrf-parity.md). ✅ **COMPLETED**
 - [x] Track progress through [Phase 04 – DSIGN Algorithm Parity](phase-04-dsign-parity.md). ✅ **COMPLETED**
 - [x] Track progress through [Phase 05 – KES Algorithm Parity](phase-05-kes-parity.md). ✅ **COMPLETED**
@@ -96,6 +104,8 @@ and ensures no crate is left without an explicit plan or acceptance criteria.
 - [x] Document usage expectations for downstream crates/binaries.
 
 ### cardano-slotting
+- [x] Document slotting primitives, Haskell mapping, and integration guidance
+      for the Rust port.
 - [ ] Port slotting arithmetic (slot length, epochs, `SlottingData`) with unit
       tests derived from Haskell’s property suite.
 - [ ] Implement time calculations and conversions (slots ↔ POSIX time) ensuring
@@ -105,6 +115,8 @@ and ensures no crate is left without an explicit plan or acceptance criteria.
 - [ ] Add clock-skew and boundary condition tests mirroring Haskell cases.
 
 ### cardano-strict-containers
+- [x] Document strict container usage, Haskell mapping, and finger tree
+      guidance for downstream crates.
 - [ ] Port strict maps, sequences, and helper combinators ensuring structural
       sharing semantics match.
 - [ ] Benchmark against Haskell behaviour for large datasets (memory usage,
@@ -114,40 +126,67 @@ and ensures no crate is left without an explicit plan or acceptance criteria.
 - [ ] Expand doc comments with usage guidance for downstream crates.
 
 ### cardano-vrf-pure
+- [x] Document VRF highlights, diagnostics wiring, and Haskell mapping in the
+      Rust README/CHANGELOG so downstream crates can cross-reference parity evidence.
 - [x] Coordinated with [Phase 03](phase-03-vrf-parity.md); ensure every low-level
       primitive has matching tests and documentation. ✅ **COMPLETED**
 - [x] Add micro-benchmarks to spot regressions versus libsodium where practical.
 - [x] Verify `no_std` compatibility if required by downstream components.
 
 ### deepseq
+- [x] Document NFData traits, deriving helpers, and Haskell mapping for the
+      Rust port; include guidance on pairing with `base-deriving-via`/`nothunks`.
 - [ ] Mirror Haskell’s `Control.DeepSeq` behaviour, including custom `NFData`
       derivations for Cardano-specific types.
 - [ ] Confirm blanket implementations don’t introduce borrow-checker hazards or
       performance cliffs.
 - [ ] Add doc examples showing how consumers ensure deep evaluation.
 
 ### heapwords
+- [x] Document HeapWords trait usage, helper combinators, and Haskell mapping
+      for the Rust port; include guidance on reporting helpers and compile-time
+      constraints.
 - [ ] Port the heap word counting utilities and ensure they integrate with Rust
       profiling/measurement tools as expected.
 - [ ] Write regression tests using representative Cardano data structures.
-- [ ] Document how to run heap measurement reports in the Rust toolchain.
+- [x] Document how to run heap measurement reports in the Rust toolchain.
 
 ### measures
+- [x] Document highlights, crate layout, Haskell mapping, and validation steps
+      in the README/CHANGELOG to keep distribution guidance in sync with the
+      latest Rust port.
+- [x] Document measurement APIs, Haskell mapping, and usage notes for the Rust
+      port.
 - [ ] Align metric collection APIs (counters, histograms) with the Haskell
       naming and aggregation semantics.
 - [ ] Confirm compatibility with the observability stack (e.g. EKG, Prometheus
       exporters) or document migration steps.
 - [ ] Add end-to-end tests/integration harness demonstrating event emission.
 
 ### nothunks
+- [x] Document NoThunks usage, diagnostics, and Haskell mapping for the Rust
+      port; include guidance on generic deriving and integration across the
+      workspace.
 - [ ] Implement thunk detection mirroring Haskell’s `NoThunks` typeclass.
 - [ ] Ensure diagnostic messages match expectations (path, type names).
 - [ ] Add property tests covering shallow vs deep thunks, cycles, and large
       structures.
 - [ ] Integrate checks across other crates (e.g. `cardano-strict-containers`) as
       part of CI.
 
+### cardano-test-vectors
+- [x] Document fixture layout, regeneration tooling, and Haskell mapping for the
+      Rust port; highlight CLI tooling and feature-gated diagnostics.
+- [ ] Audit fixture parity against the latest Haskell generators after each
+      upstream release and capture deltas in the changelog.
+- [ ] Expand cross-language comparison scripts to cover streaming hash cases
+      and additional KES evolution scenarios.
+- [ ] Automate regeneration tooling within CI to guard against drift (follow-up
+      task once parity pipeline is finalised).
+
 ### orphans-deriving-via
+- [x] Document crate purpose, re-export surface, and Haskell mapping for
+      downstream users.
 - [ ] Collect all orphan instances provided in Haskell and port them explicitly,
       documenting any differences required by Rust’s coherence rules.
 - [ ] Ensure exporting strategy doesn’t introduce conflicting implementations in
@@ -210,6 +249,55 @@ and ensures no crate is left without an explicit plan or acceptance criteria.
       Enhanced README with canonical encoding rules (RFC 8949 §4.2), map key ordering examples, and
       verification strategy. All CBOR types, error handling, and deterministic encoding validated
       byte-for-byte against Haskell reference.
+- 08-10-2025-time-06:15: Authored `heapwords` README/CHANGELOG documenting usage, helper mapping,
+      and test commands. Marked roadmap documentation task complete while leaving parity/test items
+      open for future work.
+- 09-10-2025-time-03:05: Refreshed `measures` README/CHANGELOG with Haskell mapping, iterator helper
+      guidance, and testing notes; added roadmap checkbox to track remaining parity work separately.
+- 09-10-2025-time-03:55: Updated `cardano-strict-containers` README/CHANGELOG with strict finger tree
+      examples, serde integration guidance, and Haskell lookup table; marked roadmap documentation
+      checkbox while keeping remaining parity tasks open.
+- 09-10-2025-time-04:20: Added README/CHANGELOG for `orphans-deriving-via`, documenting re-exports and
+      Haskell parity; flagged roadmap checklist to reflect completed documentation while parity
+      tasks remain outstanding.
+- 09-10-2025-time-04:45: Refreshed `base-deriving-via` README/CHANGELOG with highlights, custom
+      derivation examples, and Haskell lookup table; marked documentation checkbox while keeping
+      parity test items open for future work.
+- 10-10-2025-time-01:10: Updated `cardano-slotting` README/CHANGELOG with epoch/time examples,
+      Haskell mapping, and testing guidance; marked roadmap documentation task while parity-focused
+      work (arithmetic proofs, boundary tests) remains open.
+- 10-10-2025-time-03:40: Documented `cardano-base` feature flag primitives, refreshed README with
+      Haskell mapping and parsing guidance, converted the changelog to Keep a Changelog format, and
+      recorded remaining parity tasks for future implementation.
+- 10-10-2025-time-05:05: Refactored `cardano-binary` README with module mapping, canonical encoding
+      contract, error-handling guidance, and nested CBOR usage; aligned changelog with Keep a Changelog
+      structure and checked off roadmap documentation tasks.
+- 10-10-2025-time-07:10: Refreshed `cardano-crypto-class` README with module map, parity summaries
+      for DSIGN/KES/VRF/hash, regeneration workflows, and diagnostics guidance; converted the changelog
+      to Keep a Changelog format and marked roadmap documentation items complete.
+- 10-10-2025-time-08:30: Updated `cardano-git-rev` README with Haskell module mapping, build-script
+      workflow, troubleshooting guidance, and testing instructions; adopted Keep a Changelog format and
+      captured the work in the crate changelog to keep the documentation campaign consistent.
+- 10-10-2025-time-09:15: Expanded `deepseq` README with highlights, crate layout, generic deriving
+      patterns, and integration guidance; converted the changelog to Keep a Changelog format and checked
+      off the documentation task in the roadmap.
+- 10-10-2025-time-10:00: Refreshed `nothunks` README with highlights, generic deriving patterns,
+      integration notes, and crate layout; migrated the changelog to Keep a Changelog format and marked
+      the roadmap documentation task complete.
+- 10-10-2025-time-10:45: Updated `heapwords` README with highlights, integration guidance, crate layout,
+      and refined testing instructions; recorded the work in the changelog and marked the roadmap
+      documentation item complete.
+- 10-10-2025-time-11:30: Refreshed `cardano-test-vectors` README with highlights, fixture layout table,
+      Haskell↔Rust mapping, and expanded regeneration instructions; adopted Keep a Changelog structure,
+      and marked the roadmap documentation checkbox while leaving parity and automation tasks open.
+- 10-10-2025-time-12:15: Reworked `cardano-vrf-pure` README with highlights, layout table, Haskell mapping,
+      and diagnostics guidance; noted the changes in the changelog and recorded the documentation
+      checkbox while existing performance/parity tasks remain complete.
+- 10-10-2025-time-12:45: Refreshed `measures` README with highlights, crate layout, Haskell mapping,
+      integration notes, and validation guidance; updated the changelog and roadmap documentation entry.
+- 10-10-2025-time-13:05: Added migration notes to `cardano-base` README, logged the change in the
+      changelog, and marked the roadmap checklist item so downstream crates have parity guidance when
+      swapping from the Haskell feature-flag helpers.
 
 ---
 

base-deriving-via/CHANGELOG.md

@@ -1,14 +1,23 @@
-# Changelog for `base-deriving-via`
+# Changelog
 
-## 0.1.0.2
+All notable changes to `base-deriving-via` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the crate
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-*
+## [Unreleased]
 
-## 0.1.0.1
+### Added
+- Revamped README with highlights, custom derivation examples, and
+	Haskell↔Rust lookup table for the deriving helpers.
+
+## 0.1.0.2
 
-* Remove `development` flag: #372
+### Changed
+- Remove `development` flag (upstream ref: IntersectMBO/cardano-base#372).
 
 ## 0.1.0.1
 
-* Initial release
+### Added
+- Initial release porting the `deriving via` helpers (`InstantiatedAt`,
+	generic tuple derivations, and tuple `Semigroup`/`Monoid` instances).
 

base-deriving-via/README.md

@@ -1,26 +1,26 @@
 # base-deriving-via (Rust)
 
-This crate is a Rust translation of the original Haskell-only
-`base-deriving-via` package from the Cardano code base. It provides a tiny
-layer for expressing `Semigroup` and `Monoid` instances in terms of a
-“generic” representation—much like `GHC.Generics`—and a convenience wrapper
-[`InstantiatedAt`] that mirrors the `deriving via` pattern familiar to Haskell
-users.
-
-The implementation is intentionally conservative so it can serve as a starting
-point for a wider migration of the repository toward Rust. Future work can
-expand coverage (e.g. tuple structs, enums, or automatically generated
-representations) as additional modules are ported.
-
-Key features already available:
-
-- Blanket [`Semigroup`](src/semigroup.rs) and [`Monoid`](src/semigroup.rs)
-    implementations for tuples up to eight elements, matching the behaviour of
-    the original generics-based derivations.
-- Ready-made helpers to treat `core::time::Duration`, primitive numbers,
-    strings, options, vectors, and fixed-size arrays as algebraic structures.
-
-## Getting started
+Rust port of the Haskell `base-deriving-via` package. It offers a lightweight
+way to derive `Semigroup`/`Monoid` implementations from a “generic” tuple
+representation, mirroring the `deriving via` pattern used across the Cardano
+code base.
+
+## Highlights
+
+- **`InstantiatedAt<T>` wrapper** — grants `Semigroup`/`Monoid` instances to
+  your type once a compatible generic representation exists.
+- **`Generic`, `GenericSemigroup`, `GenericMonoid` traits** — encode the
+  mapping between the concrete type and its tuple-based representation.
+- **`impl_generic_for_struct!` macro** — derives `Generic` automatically for
+  common record and tuple structs without relying on `unsafe`.
+- **Blanket tuple implementations** — tuples up to arity eight already provide
+  `Semigroup`/`Monoid`, covering most ledger records out of the box.
+- **Standard library support** — integers, durations, strings, vectors,
+  arrays, and options ship with ready-made instances.
+- **Pure Rust** — no macros beyond declarative `macro_rules!`, no runtime
+  reflection, and no external dependencies.
+
+## Quick start
 
 ```rust
 use base_deriving_via::{
@@ -38,7 +38,7 @@ impl_generic_for_struct!(struct Counter {
     ticks: i64,
 });
 
-let total = InstantiatedAt::new(Counter {
+let combined = InstantiatedAt::new(Counter {
     label: "alpha".into(),
     ticks: 2,
 })
@@ -48,38 +48,88 @@ let total = InstantiatedAt::new(Counter {
 }))
 .into_inner();
 
-assert_eq!(total.label, "alphabeta");
-assert_eq!(total.ticks, 7);
+assert_eq!(combined.label, "alphabeta");
+assert_eq!(combined.ticks, 7);
+```
+
+### Customising the representation
+
+Generic derivation works for tuple structs as well. You can also hand-roll a
+representation when the default tuple layout is insufficient:
+
+```rust
+use base_deriving_via::{Generic, GenericMonoid, InstantiatedAt, Monoid};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct RollingAverage {
+    sum: i64,
+    count: u32,
+}
+
+// Implement Generic manually to encode additional invariants.
+impl Generic for RollingAverage {
+    type Repr = (i64, u32);
+  type ReprRef<'a> = (&'a i64, &'a u32) where Self: 'a;
+
+    fn into_repr(self) -> Self::Repr {
+        (self.sum, self.count)
+    }
+
+    fn from_repr(repr: Self::Repr) -> Self {
+        RollingAverage {
+            sum: repr.0,
+            count: repr.1,
+        }
+    }
+
+  fn as_repr(&self) -> Self::ReprRef<'_> {
+    (&self.sum, &self.count)
+  }
+}
+
+impl GenericMonoid for RollingAverage {}
+
+let average = InstantiatedAt::new(RollingAverage { sum: 6, count: 2 })
+    .combine(InstantiatedAt::new(RollingAverage { sum: 9, count: 3 }))
+    .into_inner();
+
+assert_eq!(average.sum, 15);
+assert_eq!(average.count, 5);
 ```
 
-Run the test suite with:
+## Haskell ↔ Rust mapping
+
+| Haskell module/symbol | Rust counterpart |
+|-----------------------|------------------|
+| `Data.DerivingVia.InstantiatedAt` | `base_deriving_via::InstantiatedAt` |
+| `Data.DerivingVia.Generic` | `base_deriving_via::Generic` |
+| `Data.DerivingVia.GenericSemigroup` | `base_deriving_via::GenericSemigroup` |
+| `Data.DerivingVia.GenericMonoid` | `base_deriving_via::GenericMonoid` |
+| `implGenericForStruct` TH helper | `base_deriving_via::impl_generic_for_struct!` |
+| Tuple `Semigroup`/`Monoid` instances | `base_deriving_via::semigroup` module |
+
+## Integration notes
+
+- Downstream crates (`deepseq`, `nothunks`, `orphans-deriving-via`) rely on the
+  `InstantiatedAt` wrapper to bridge evaluation traits. Keep version alignment
+  across the workspace to avoid API drift.
+- The current macro supports record structs and tuple structs. If you need enum
+  coverage, add a new macro pattern or implement `Generic` manually.
+- The crate has no optional features; it is safe to depend on in `no_std`
+  contexts that support heap allocations for `String`/`Vec`.
+
+## Testing
+
+Run the crate tests to validate the derivations:
 
 ```bash
-cargo test
+cargo test -p base-deriving-via
 ```
 
-## Module mapping
-
-The original Haskell modules translate to the following Rust modules:
-
-| Haskell module | Rust equivalent |
-| --- | --- |
-| `Data.DerivingVia` | `src/instantiated_at.rs` (re-exported via `lib.rs`) |
-| `Data.DerivingVia.GHC.Generics.Semigroup` | `src/semigroup.rs` together with `src/generic.rs` |
-| `Data.DerivingVia.GHC.Generics.Monoid` | `src/semigroup.rs` and `src/generic.rs` |
-| `Data/DerivingVia/GHC/Generics/Semigroup.hs` macro usage | `src/macros.rs` (`impl_generic_for_struct!`) |
-
-## Migration checklist
-
-1. **Integrate with the wider workspace:** add the crate to a top-level
-    `Cargo.toml` workspace (or create one) so that other packages can depend on
-    it.
-2. **Wire up CI:** ensure your continuous-integration pipeline executes the
-    Rust tests (e.g. by invoking `cargo test -p base-deriving-via`).
-3. **Port consumers incrementally:** replace Haskell call sites that used the
-    original package with Rust equivalents. Start with simple record types to
-    validate the API.
-4. **Extend macro coverage:** the current macro supports record structs. Add
-    patterns for tuple structs or enums as your migration requires them.
-5. **Audit trait coverage:** implement additional `Semigroup`/`Monoid`
-    instances for domain-specific types once they are ported.
+The suite mirrors the Haskell QuickCheck coverage for `InstantiatedAt`, tuple
+instances, and generic macro behaviour.
+
+## License
+
+Dual-licensed under Apache-2.0 or MIT. See [`LICENSE`](../LICENSE) and
+[`NOTICE`](../NOTICE) in the workspace root.