v0.2.0: third INFRA demo batch (9), per-direction tutorials, hash/compress benches, release metadata

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-07-12 18:43:00 +00:00 · 2026-07-12 18:43:00 +00:00 · a5d981a2e4
parent c7602c4713
commit a5d981a2e4
42 changed files with 1588 additions and 16 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -32,6 +32,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 无。

+## [0.2.0] - 2026-07-12
+
+### Added — INFRA flagship demos, tutorials & performance evidence（INFRA 旗舰 demo、教程与性能证据）
+
+- feat(examples): second demo batch — `actor_worker_pool` (supervised
+  restart / routing / backpressure), `build_pipeline` (wave scheduling /
+  incremental rebuild / auto-bisect), `serialization_studio` (typed wire +
+  JSON round-trips / breaking-change detection), `dst_explorer`
+  (deterministic replay / DPOR / linearizability), `config_diff_ops`
+  (TOML/INI + diff3 + semver)（第二批 5 个 INFRA 端到端 demo）
+- feat(examples): third demo batch — `hash_integrity`（SHA-2/3、BLAKE2b、
+  HMAC 防篡改、HKDF/PBKDF2、流式 == 一次性、xxHash 分片）、
+  `compress_workbench`（DEFLATE/zlib/gzip/zstd/LZ4 压缩率对比、字典压缩、
+  损坏归档拒绝）、`time_scheduler`（RFC 3339/2822、POSIX TZ 夏令时、
+  时间轮、工作窃取调度）、`resilience_gateway`（退避重试、熔断器、
+  令牌桶/滑动窗口、隔板、AIMD、对冲请求）、`cli_devtool`（类型化校验、
+  拼写建议、help/补全生成）、`observability_kit`（HDR 直方图、DDSketch、
+  span 追踪）、`text_editor_core`（rope/piece table、Myers diff、
+  LRU/布隆/roaring）、`parser_playground`（表达式求值、JSON 错误恢复、
+  增量解析）、`pbt_fuzz_lab`（属性缩小、往返律、种子化图 fuzz）——
+  20 directions now ship runnable end-to-end demos
+- feat(bench): `benches/infra_hash_bench` (crypto digests vs fast hashes,
+  streaming == one-shot smoke) and `benches/infra_compress_bench`
+  (deflate/zstd/lz4 round-trip throughput, lossless smoke); native results
+  archived in `benches/results/infra-hash-compress-native-2026-07-12.md`
+  （新增哈希/压缩原生基准与结果归档）
+- docs(tutorials): hands-on handbook for every direction —
+  `docs/tutorials/README.md` (EN) and `docs/zh/tutorials.md` (中文)，
+  key APIs + runnable snippets + demo mapping
+- docs(readme): bilingual demo overview tables now list all 20 runnable
+  example workflows（README 中英 demo 总览表补齐 20 条）
+
 ## [0.1.0] - 2026-07-12

 ### Added — Real OSM Playground & ecosystem（真实 OSM Playground 与生态）
@ -246,5 +278,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Project adopts the "successor function" API philosophy from Rust's
  `pathfinding` crate, with independent algorithm implementations.

-[Unreleased]: https://github.com/Suquster/moonbit-pathfinding/compare/v0.0.1...HEAD
+[Unreleased]: https://github.com/Suquster/moonbit-pathfinding/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Suquster/moonbit-pathfinding/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Suquster/moonbit-pathfinding/compare/v0.0.1...v0.1.0
 [0.0.1]: https://github.com/Suquster/moonbit-pathfinding/releases/tag/v0.0.1
--- a/README.md
+++ b/README.md
@ -5,7 +5,7 @@
 <!-- Tier-1 6 badges (per tasks.md 10.1): License / CI / Version / mooncakes.io / Playground / Formally verified -->
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
 [![CI](https://github.com/Suquster/moonbit-pathfinding/actions/workflows/ci.yml/badge.svg)](https://github.com/Suquster/moonbit-pathfinding/actions/workflows/ci.yml)
-[![Version](https://img.shields.io/badge/version-v0.1.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-v0.2.0-blue)](./CHANGELOG.md)
 [![mooncakes.io](https://img.shields.io/badge/mooncakes.io-Suquster%2Fmoonbit--pathfinding-orange)](https://mooncakes.io/docs/Suquster/moonbit-pathfinding)
 [![Playground](https://img.shields.io/badge/Playground-live-brightgreen)](https://suquster.github.io/moonbit-pathfinding/)
 [![Executable contracts](https://img.shields.io/badge/proof_predicates-runtime_checked-yellow)](#formal-verification)
@ -34,7 +34,7 @@
   CH → Hub Labels → PHAST) plus 20 infra directions, published on
   [mooncakes.io](https://mooncakes.io/docs/Suquster/moonbit-pathfinding)
   with a [live in-browser playground](https://suquster.github.io/moonbit-pathfinding/).
-2. **An engineering benchmark for the ecosystem** — 3331 tests across four
+2. **An engineering benchmark for the ecosystem** — 3339 tests across four
   backends (wasm-gc / native / js / wasm), executable proof predicates,
   executable README (`moon test README.mbt.md`), DST + differential PBT,
   zero-warning `--deny-warn` CI gates, and a published
@ -197,6 +197,15 @@ stories instead of isolated snippets — pathfinding and INFRA directions alike:
 | Serialization studio | `moon run examples/serialization_studio` | serialization | .proto parse/validate, typed wire + JSON round-trips, canonical bytes, breaking-change detection, codegen |
 | DST explorer | `moon run examples/dst_explorer` | dst | Seeded deterministic replays, partition/crash fault injection, DPOR exploration, shrinking, linearizability checking |
 | Config & diff ops | `moon run examples/config_diff_ops` | infra_config + infra_diff | TOML/INI parsing, unified diffs, patch apply/revert, diff3 merge with conflicts, semver gates |
+| Hash integrity | `moon run examples/hash_integrity` | infra_hash | SHA-2/SHA-3/BLAKE2b digests (sha256 matches `sha256sum`), HMAC tamper detection, HKDF/PBKDF2 key derivation, streaming == one-shot, xxHash sharding |
+| Compress workbench | `moon run examples/compress_workbench` | infra_compress | DEFLATE/zlib/gzip/zstd/LZ4 ratio shoot-out, lossless round-trips, dictionary compression, corrupted-archive rejection |
+| Time scheduler | `moon run examples/time_scheduler` | infra_time + infra_timer | RFC 3339/2822 + strftime, civil arithmetic, POSIX TZ DST rules, duration round-trip, timer wheel, work-stealing scheduler with real steals |
+| Resilience gateway | `moon run examples/resilience_gateway` | infra_resilience | Capped backoff + retry, circuit-breaker state machine, token bucket vs sliding window, bulkhead, AIMD, hedged requests |
+| CLI devtool | `moon run examples/cli_devtool` | infra_cli | Subcommand parsing with defaults, typed validation with choices, typo suggestions, bundled shorts, generated help + bash completion |
+| Observability kit | `moon run examples/observability_kit` | infra_metrics | HDR histogram tail percentiles, mergeable DDSketch quantiles, span tracer with total vs self time |
+| Text editor core | `moon run examples/text_editor_core` | infra_text + infra_ds | Rope + piece-table edits converge, graphemes/display width, Myers diff, LRU eviction, bloom filter, roaring-bitmap intersection |
+| Parser playground | `moon run examples/parser_playground` | parser_combinator | Precedence-correct expression eval, JSON with rendered error positions, error recovery diagnostics, incremental chunked parsing |
+| PBT & fuzz lab | `moon run examples/pbt_fuzz_lab` | infra_pbt + infra_fuzz | Property checking, shrinking to boundary counterexample (500), distribution stats, round-trip laws, seeded graph fuzzing + structural shrinking |

 Verify all example outputs with checked markers:

@ -209,6 +218,10 @@ Latest evidence:
 and
 [`docs/examples/latest-examples-run.json`](./docs/examples/latest-examples-run.json).

+Hands-on tutorials for every direction (key APIs + minimal snippets + the
+demo that exercises them): [`docs/tutorials/README.md`](./docs/tutorials/README.md)
+(中文版: [`docs/zh/tutorials.md`](./docs/zh/tutorials.md)).
+
 ---

 ## Release Readiness
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@ -4,7 +4,7 @@

 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
 [![CI](https://github.com/Suquster/moonbit-pathfinding/actions/workflows/ci.yml/badge.svg)](https://github.com/Suquster/moonbit-pathfinding/actions/workflows/ci.yml)
-[![Version](https://img.shields.io/badge/version-v0.1.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-v0.2.0-blue)](./CHANGELOG.md)
 [![mooncakes.io](https://img.shields.io/badge/mooncakes.io-Suquster%2Fmoonbit--pathfinding-orange)](https://mooncakes.io/docs/Suquster/moonbit-pathfinding)
 [![Playground](https://img.shields.io/badge/Playground-live-brightgreen)](https://suquster.github.io/moonbit-pathfinding/)
 [![Executable contracts](https://img.shields.io/badge/proof_predicates-runtime_checked-yellow)](#formal-verification)
@ -24,7 +24,7 @@
   （BFS → A\* → JPS → ALT → CH → Hub Labels → PHAST）+ 20 个 INFRA 方向，
   已发布 [mooncakes.io](https://mooncakes.io/docs/Suquster/moonbit-pathfinding)，
   并提供[打开即玩的浏览器 playground](https://suquster.github.io/moonbit-pathfinding/)。
-2. **生态工程标杆** — 3331 个测试跨四后端（wasm-gc / native / js / wasm）、
+2. **生态工程标杆** — 3339 个测试跨四后端（wasm-gc / native / js / wasm）、
   可执行 proof predicates、可执行 README（`moon test README.mbt.md`）、
   DST + 差分 PBT、零警告 `--deny-warn` CI 门禁，以及已发布的
   [对标 Rust `pathfinding` crate 正面对比](./benches/results/latest-rust-comparison.md)
@ -138,6 +138,15 @@ path = [0, 1, 2, 3]
 | 序列化工作台 | `moon run examples/serialization_studio` | serialization | .proto 解析校验、类型化二进制/JSON 往返、规范字节、破坏性变更检测、代码生成 |
 | DST 探索器 | `moon run examples/dst_explorer` | dst | 种子确定性重放、分区/崩溃注错、DPOR 探索、缩小最小复现、线性一致性检查 |
 | 配置与差分运维 | `moon run examples/config_diff_ops` | infra_config + infra_diff | TOML/INI 解析、统一 diff、补丁应用/回退、diff3 三方合并冲突、semver 门禁 |
+| 哈希完整性 | `moon run examples/hash_integrity` | infra_hash | SHA-2/SHA-3/BLAKE2b 摘要（sha256 与 `sha256sum` 一致）、HMAC 防篡改、HKDF/PBKDF2 派生、流式 == 一次性、xxHash 分片 |
+| 压缩工作台 | `moon run examples/compress_workbench` | infra_compress | DEFLATE/zlib/gzip/zstd/LZ4 压缩率对比、无损往返、字典压缩、损坏归档拒绝 |
+| 时间调度器 | `moon run examples/time_scheduler` | infra_time + infra_timer | RFC 3339/2822 + strftime、公历运算、POSIX TZ 夏令时、时长往返、时间轮、工作窃取调度（真实 steal 计数） |
+| 韧性网关 | `moon run examples/resilience_gateway` | infra_resilience | 封顶退避重试、熔断器状态机、令牌桶 vs 滑动窗口、隔板、AIMD、对冲请求 |
+| CLI 开发工具 | `moon run examples/cli_devtool` | infra_cli | 子命令解析与默认值、带 choices 的类型化校验、拼写建议、短参展开、生成 help + bash 补全 |
+| 观测套件 | `moon run examples/observability_kit` | infra_metrics | HDR 直方图尾部分位数、可合并 DDSketch 分位数、span 追踪 total vs self 时间 |
+| 文本编辑器内核 | `moon run examples/text_editor_core` | infra_text + infra_ds | Rope 与 piece table 编辑收敛、字素/显示宽度、Myers 差分、LRU 淘汰、布隆过滤器、roaring 位图求交 |
+| 解析器演练场 | `moon run examples/parser_playground` | parser_combinator | 优先级正确的表达式求值、JSON 精确错误位置渲染、错误恢复诊断、增量分块解析 |
+| PBT 与 fuzz 实验室 | `moon run examples/pbt_fuzz_lab` | infra_pbt + infra_fuzz | 属性检查、缩小到边界反例（500）、分布统计、往返律、种子化图 fuzz 与结构缩小 |

 一键验证示例输出 marker：

@ -150,6 +159,10 @@ pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File scripts\examples_guard.ps1
 与
 [`docs/examples/latest-examples-run.json`](./docs/examples/latest-examples-run.json)。

+各方向上手教程（关键 API + 最小片段 + 对应 demo）：
+[`docs/zh/tutorials.md`](./docs/zh/tutorials.md)（英文完整版
+[`docs/tutorials/README.md`](./docs/tutorials/README.md)）。
+
 ---

 ## 发布就绪 · Release Readiness
--- a/benches/infra_compress_bench/infra_compress_bench.mbt
+++ b/benches/infra_compress_bench/infra_compress_bench.mbt
@ -0,0 +1,48 @@
+// infra_compress_bench.mbt —— 压缩方向基准：DEFLATE / zstd(entropy) /
+// LZ4 在重复性日志负载上的压缩 + 解压 round-trip 吞吐对比，
+// smoke 校验三者均无损。
+
+///|
+fn cb_log_payload(lines : Int) -> Array[Int] {
+  let sb = StringBuilder::new()
+  for i in 0..<lines {
+    sb.write_string(
+      "2026-07-12T18:0\{i % 10}:0\{i % 6}Z INFO handled path=/api/v\{i % 3}/route status=200 rt=\{i % 40}ms\n",
+    )
+  }
+  @codec.utf8_bytes_of_string(sb.to_string())
+}
+
+///|
+test "smoke: all codecs round-trip losslessly" {
+  let data = cb_log_payload(64)
+  let n = data.length()
+  assert_true(@compress.inflate(@compress.deflate(data)) == Some(data))
+  assert_true(
+    @compress.zstd_decompress(@compress.zstd_compress_entropy(data, true), n) ==
+    Some(data),
+  )
+  assert_true(
+    @compress.lz4_decompress(@compress.lz4_compress(data), n) == Some(data),
+  )
+}
+
+///|
+test "bench: compress + decompress round-trip throughput" (b : @bench.T) {
+  for lines in [64, 512] {
+    let data = cb_log_payload(lines)
+    let n = data.length()
+    b.bench(name="deflate_roundtrip_\{n}B", fn() {
+      let c = @compress.deflate(data)
+      b.keep(@compress.inflate(c))
+    })
+    b.bench(name="zstd_roundtrip_\{n}B", fn() {
+      let c = @compress.zstd_compress_entropy(data, false)
+      b.keep(@compress.zstd_decompress(c, n))
+    })
+    b.bench(name="lz4_roundtrip_\{n}B", fn() {
+      let c = @compress.lz4_compress(data)
+      b.keep(@compress.lz4_decompress(c, n))
+    })
+  }
+}
--- a/benches/infra_compress_bench/moon.pkg
+++ b/benches/infra_compress_bench/moon.pkg
@ -0,0 +1,12 @@
+// Package: benches/infra_compress_bench
+//
+// 压缩方向基准：DEFLATE / zstd(entropy) / LZ4 在重复性日志负载上的
+// 压缩 + 解压 round-trip 吞吐与压缩率对比。
+//
+// 运行命令（native 前置 `export LIBRARY_PATH=/usr/lib64:/usr/lib`）：
+//   moon bench -p benches/infra_compress_bench --target native
+import {
+  "moonbitlang/core/bench",
+  "Suquster/moonbit-pathfinding/src/infra_compress" @compress,
+  "Suquster/moonbit-pathfinding/src/infra_codec" @codec,
+}
--- a/benches/infra_compress_bench/pkg.generated.mbti
+++ b/benches/infra_compress_bench/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/benches/infra_compress_bench"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/benches/infra_hash_bench/infra_hash_bench.mbt
+++ b/benches/infra_hash_bench/infra_hash_bench.mbt
@ -0,0 +1,49 @@
+// infra_hash_bench.mbt —— 哈希方向基准：SHA-256 加密摘要 vs
+// xxHash64 / FNV-1a / CRC32 快速哈希在同一确定性负载上的吞吐对比，
+// 以及流式分块与一次性摘要的等价校验。
+
+///|
+fn hb_payload(n : Int, seed : Int) -> Array[Int] {
+  let out : Array[Int] = []
+  let mut s = seed
+  for _ in 0..<n {
+    s = (s * 1103515245 + 12345) & 0x7FFFFFFF
+    out.push(s % 256)
+  }
+  out
+}
+
+///|
+test "smoke: digests agree between streaming and one-shot" {
+  let data = hb_payload(4096, 20260712)
+  let one = @hash.sha256(data)
+  let head : Array[Int] = []
+  let tail : Array[Int] = []
+  for i in 0..<4096 {
+    if i < 2048 {
+      head.push(data[i])
+    } else {
+      tail.push(data[i])
+    }
+  }
+  let h = @hash.Sha256Hasher::new()
+  h.update(head)
+  h.update(tail)
+  assert_eq(@hash.digest_hex(h.finalize()), @hash.digest_hex(one))
+  let c = @hash.Crc32Hasher::new()
+  c.update(data)
+  assert_eq(c.finalize(), @hash.crc32(data))
+}
+
+///|
+test "bench: crypto digest vs fast non-crypto hashes" (b : @bench.T) {
+  for n in [1024, 16384] {
+    let data = hb_payload(n, 20260712)
+    b.bench(name="sha256_\{n}", fn() { b.keep(@hash.sha256(data)) })
+    b.bench(name="sha3_256_\{n}", fn() { b.keep(@hash.sha3_256(data)) })
+    b.bench(name="blake2b_\{n}", fn() { b.keep(@hash.blake2b(data)) })
+    b.bench(name="xxhash64_\{n}", fn() { b.keep(@hash.xxhash64(data, 42)) })
+    b.bench(name="fnv1a_64_\{n}", fn() { b.keep(@hash.fnv1a_64(data)) })
+    b.bench(name="crc32_\{n}", fn() { b.keep(@hash.crc32(data)) })
+  }
+}
--- a/benches/infra_hash_bench/moon.pkg
+++ b/benches/infra_hash_bench/moon.pkg
@ -0,0 +1,12 @@
+// Package: benches/infra_hash_bench
+//
+// 哈希方向基准：加密摘要（SHA-256）吞吐 vs 快速非加密哈希
+// （xxHash64 / FNV-1a / CRC32）在同一负载上的相对开销，
+// 以及流式 SHA-256 与一次性调用的等价性能。
+//
+// 运行命令（native 前置 `export LIBRARY_PATH=/usr/lib64:/usr/lib`）：
+//   moon bench -p benches/infra_hash_bench --target native
+import {
+  "moonbitlang/core/bench",
+  "Suquster/moonbit-pathfinding/src/infra_hash" @hash,
+}
--- a/benches/infra_hash_bench/pkg.generated.mbti
+++ b/benches/infra_hash_bench/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/benches/infra_hash_bench"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/benches/results/infra-hash-compress-native-2026-07-12.md
+++ b/benches/results/infra-hash-compress-native-2026-07-12.md
@ -0,0 +1,52 @@
+# INFRA hash / compress native benchmarks — 2026-07-12
+
+- Toolchain: moon 0.1.20260703 (native backend, release)
+- Command:
+  `export LIBRARY_PATH=/usr/lib64:/usr/lib && moon bench -p benches/infra_hash_bench --target native`
+  and `moon bench -p benches/infra_compress_bench --target native`
+- Payloads are deterministic (seeded LCG bytes for hashing; repetitive
+  structured log text for compression), so runs are reproducible.
+
+## Hashing: crypto digests vs fast non-crypto hashes
+
+`benches/infra_hash_bench` — one-shot digest over the same byte payload.
+
+| name | time (mean ± σ) | range (min … max) |
+|---|---|---|
+| sha256_1024 | 5.57 µs ± 19.13 ns | 5.54 µs … 5.59 µs |
+| sha3_256_1024 | 23.10 µs ± 42.43 ns | 23.06 µs … 23.18 µs |
+| blake2b_1024 | 10.29 µs ± 276.23 ns | 9.96 µs … 10.66 µs |
+| xxhash64_1024 | 680.25 ns ± 0.24 ns | 679.85 ns … 680.62 ns |
+| fnv1a_64_1024 | 996.79 ns ± 0.66 ns | 996.18 ns … 997.87 ns |
+| crc32_1024 | 2.04 µs ± 0.90 ns | 2.04 µs … 2.04 µs |
+| sha256_16384 | 80.18 µs ± 2.14 µs | 78.86 µs … 84.59 µs |
+| sha3_256_16384 | 348.40 µs ± 786.41 ns | 347.68 µs … 350.35 µs |
+| blake2b_16384 | 153.84 µs ± 287.37 ns | 153.36 µs … 154.36 µs |
+| xxhash64_16384 | 10.63 µs ± 11.89 ns | 10.62 µs … 10.66 µs |
+| fnv1a_64_16384 | 16.45 µs ± 23.54 ns | 16.43 µs … 16.50 µs |
+| crc32_16384 | 33.46 µs ± 870.00 ns | 32.89 µs … 34.85 µs |
+
+Reading: at 16 KiB, xxHash64 is ~7.5× faster than SHA-256 and ~33× faster
+than SHA3-256 — use non-crypto hashes for sharding/dedup keys and crypto
+digests only where integrity/authentication matters. The smoke test in the
+same package proves streaming (`Sha256Hasher`/`Crc32Hasher`) equals one-shot.
+
+## Compression: compress + decompress round-trip
+
+`benches/infra_compress_bench` — full round-trip (compress then decompress)
+on repetitive log text; smoke test asserts all three are lossless.
+
+| name | time (mean ± σ) | range (min … max) |
+|---|---|---|
+| deflate_roundtrip_4588B | 77.08 µs ± 280.67 ns | 76.74 µs … 77.52 µs |
+| zstd_roundtrip_4588B | 168.45 µs ± 208.90 ns | 168.10 µs … 168.80 µs |
+| lz4_roundtrip_4588B | 10.83 µs ± 44.70 ns | 10.76 µs … 10.89 µs |
+| deflate_roundtrip_36734B | 360.15 µs ± 11.79 µs | 346.09 µs … 373.87 µs |
+| zstd_roundtrip_36734B | 323.31 µs ± 1.28 µs | 321.15 µs … 325.01 µs |
+| lz4_roundtrip_36734B | 70.53 µs ± 197.55 ns | 70.32 µs … 70.94 µs |
+
+Reading: LZ4 is the speed king (~7× faster round-trip than DEFLATE at 36 KB)
+at a lower compression ratio; zstd's entropy path scales better than DEFLATE
+as payloads grow (faster at 36 KB despite losing at 4.5 KB). For ratio
+numbers on the same class of payload, see `moon run examples/compress_workbench`
+(deflate ≈46‰, zstd ≈44‰, lz4 ≈48‰ on a 2 880-byte log payload).
--- a/docs/articles/building-a-production-grade-pathfinding-library-in-moonbit.md
+++ b/docs/articles/building-a-production-grade-pathfinding-library-in-moonbit.md
@ -138,11 +138,14 @@ then import `"Suquster/moonbit-pathfinding/src/directed"` in your
  perfect-maze generator + A\* solver CLI.

 The repository also treats its INFRA directions as first-class citizens,
-not side quests: each ships a runnable end-to-end workflow under
-`examples/` (`moon run examples/actor_worker_pool`, `build_pipeline`,
-`serialization_studio`, `dst_explorer`, `config_diff_ops`,
-`mini_compiler_pipeline`, `regex_toolkit`, `log_pipeline`), backed by the
-same test/bench/acceptance gates as the pathfinding core.
+not side quests: all 20 directions ship runnable end-to-end workflows under
+`examples/` — from `actor_worker_pool`, `build_pipeline`,
+`serialization_studio`, `dst_explorer` and `config_diff_ops` to
+`hash_integrity`, `compress_workbench`, `time_scheduler`,
+`resilience_gateway`, `cli_devtool`, `observability_kit`,
+`text_editor_core`, `parser_playground` and `pbt_fuzz_lab` — backed by the
+same test/bench/acceptance gates as the pathfinding core, with per-direction
+tutorials in `docs/tutorials/README.md`.

 ## Takeaways for MoonBit library authors

--- a/docs/tutorials/README.md
+++ b/docs/tutorials/README.md
@ -0,0 +1,211 @@
+# Hands-on Tutorials — every direction, by example
+
+Each section below is a five-minute tutorial for one direction of the
+library: the key public APIs, a minimal snippet you can paste into a
+`is-main` package, and the runnable demo that exercises the full workflow.
+All snippets are drawn from the demos under `examples/`, so they compile
+and run as shown. Run any demo with:
+
+```bash
+moon run examples/<name>
+```
+
+The pathfinding core is covered by the executable docs in
+[`docs/zh/algorithms/`](../zh/algorithms/README.md); this handbook focuses on
+the INFRA directions that ship alongside it.
+
+## 1. Pathfinding (BFS / Dijkstra / A*)
+
+Demos: `examples/maze_solver`, `examples/network_routing`,
+`examples/eight_puzzle`.
+
+```moonbit
+let result = @pathfinding.dijkstra(
+  start,
+  fn(n) { neighbors_of(n) }, // (N) -> Array[(N, W)]
+  fn(n) { n == goal },
+)
+```
+
+Nodes can be any `Eq + Hash` type, weights any `Weight + Compare` type.
+See the per-algorithm executable docs for BFS/A*/JPS/CH/ALT and more.
+
+## 2. Mini compiler (`src/mini_compiler`)
+
+Demo: `examples/mini_compiler_pipeline` — lexer → parser → HM type
+inference → optimizer → bytecode VM with tail-call optimization,
+interpreter differential testing, and JS emission from one source program.
+
+## 3. Regex engine (`src/regex_engine`)
+
+Demo: `examples/regex_toolkit` — named captures, `replace_all` redaction,
+`split`, and linear-time matching (ReDoS-resistant NFA simulation).
+
+## 4. Structured logging (`src/logging`)
+
+Demo: `examples/log_pipeline` — trace spans with W3C `traceparent`
+propagation, JSON/logfmt/pretty renderers, PII redaction, env-filter.
+
+## 5. Actors (`src/actor`)
+
+Demo: `examples/actor_worker_pool`.
+
+```moonbit
+let sys = @actor.ActorSystem::new()
+// supervised pool: faults trigger restart per SupervisorSpec
+// routing: round-robin / random / consistent-hash
+// bounded mailboxes give natural backpressure
+```
+
+## 6. Build tool (`src/build_tool`)
+
+Demo: `examples/build_pipeline` — rule parsing, parallel wave scheduling,
+minimal incremental rebuilds (dirty closure), cached execution, auto-bisect
+for first-bad-commit search.
+
+## 7. Serialization (`src/serialization`)
+
+Demo: `examples/serialization_studio` — `.proto` parse/validate, typed
+wire + JSON round-trips, canonical bytes, breaking-change detection.
+
+## 8. Deterministic simulation testing (`src/dst`)
+
+Demo: `examples/dst_explorer` — seeded deterministic replays,
+partition/crash fault injection, DPOR exploration, shrinking,
+linearizability checking.
+
+## 9. Config + diff (`src/infra_config`, `src/infra_diff`)
+
+Demo: `examples/config_diff_ops` — TOML/INI parsing, unified diffs, patch
+apply/revert, diff3 three-way merge with conflict detection, SemVer gates.
+
+## 10. Hashing (`src/infra_hash`)
+
+Demo: `examples/hash_integrity`.
+
+```moonbit
+@hash.sha256_hex(artifact)                    // matches sha256sum
+let tag = @hash.hmac_sha256(key, message)     // authentication tag
+let okm = @hash.hkdf(ikm, salt, info, 32)     // key derivation
+let dk = @hash.pbkdf2_hmac_sha256(pw, salt, 1000, 32)
+let h = @hash.Sha256Hasher::new()             // streaming == one-shot
+h.update(chunk1); h.update(chunk2); h.finalize()
+let shard = (@hash.xxhash64(bytes, 42) % 3UL).to_int()
+```
+
+Rule of thumb (see `benches/results/infra-hash-compress-native-2026-07-12.md`):
+xxHash64 is ~7.5× faster than SHA-256 at 16 KiB — use non-crypto hashes for
+sharding, crypto digests for integrity.
+
+## 11. Compression (`src/infra_compress`)
+
+Demo: `examples/compress_workbench`.
+
+```moonbit
+let c = @compress.deflate(data)               // smallest here (46‰)
+@compress.inflate(c) == Some(data)            // lossless
+let zs = @compress.zstd_compress_entropy(data, true)
+let zd = @compress.zlib_compress_with_dict(small, dict) // shared dict wins on tiny payloads
+@compress.gzip_decompress(corrupted) is None  // CRC rejects tampering
+```
+
+LZ4 is ~7× faster round-trip than DEFLATE at 36 KB; zstd's entropy path
+scales best as payloads grow.
+
+## 12. Time + timers (`src/infra_time`, `src/infra_timer`)
+
+Demo: `examples/time_scheduler`.
+
+```moonbit
+let dt = @time.parse_iso8601("2026-07-12T18:30:00.250Z").unwrap()
+@time.format_rfc2822(dt, 0)
+let rule = @time.parse_posix_tz("EST5EDT,M3.2.0/2,M11.1.0/2").unwrap()
+let (offset, name) = @time.tz_offset_at(rule, dt) // seconds, "EDT"
+let d = @time.parse_duration("2h30m").unwrap()    // Go-style durations
+let wheel = @timer.TimerWheel::new()               // hierarchical wheel
+let ws = @timer.WorkStealingScheduler::new(4)      // real steal counts
+```
+
+## 13. Resilience (`src/infra_resilience`)
+
+Demo: `examples/resilience_gateway`.
+
+```moonbit
+let (ok, attempts) = @res.retry_run(policy, fn(i) { call(i) })
+let cb = @res.CircuitBreaker::create(3, 1000)  // Closed→Open→HalfOpen→Closed
+let tb = @res.TokenBucket::create(3, 1)
+let bh = @res.Bulkhead::create(2, 1)           // slots + queue
+let aimd = @res.AimdLimiter::create(10, 1, 100) // initial, min, max
+let fire = @res.hedge_schedule(policy)          // hedged requests
+```
+
+## 14. CLI (`src/infra_cli`)
+
+Demo: `examples/cli_devtool` — subcommands, typed validation with choices,
+`suggest_option` typo hints, bundled short flags, `help_text`, and
+`completion_bash` generation.
+
+## 15. Metrics (`src/infra_metrics`)
+
+Demo: `examples/observability_kit`.
+
+```moonbit
+let h = @metrics.HdrHistogram::new(3)
+h.record(latency_ms)
+h.value_at_percentile(99.9)
+let s1 = @metrics.DDSketch::new(0.01)  // mergeable across shards
+s1.merge_with(s2)
+let tracer = @metrics.SpanTracer::new() // total vs self time per span
+```
+
+## 16. Text + data structures (`src/infra_text`, `src/infra_ds`)
+
+Demo: `examples/text_editor_core`.
+
+```moonbit
+let rope = @text.Rope::from_string(src)
+rope.delete(12, 16)        // half-open [lo, hi)
+rope.insert(12, "println(\"hi\")")
+rope.line_col_at(offset)
+@text.grapheme_count("héllo 世界") // 8; display_width counts CJK as 2
+let ops = @text.myers_diff(before, after)
+let lru = @ds.LruCache::create(2)
+let bloom = @ds.BloomFilter::create(1024, 3)
+let bitmap = @ds.RoaringBitmap::new()
+```
+
+Note `PieceTable::delete(off, count)` takes a count while
+`Rope::delete(lo, hi)` takes a half-open range.
+
+## 17. Parser combinators (`src/parser_combinator`)
+
+Demo: `examples/parser_playground`.
+
+```moonbit
+@pc.parse_and_eval("2 ^ 3 ^ 2") // 512 — right-assoc power, correct precedence
+let json = @pc.parse_json(src)  // errors carry rendered caret positions
+let (value, errors) = @pc.parse_json_recover(bad) // recovery diagnostics
+let g = @pc.lift(parser)
+let step = g.run_incremental(chunk1)  // NeedMore, not a false failure
+let result = @pc.drive(step, [chunk2, chunk3], closed=true)
+```
+
+## 18. PBT + fuzzing (`src/infra_pbt`, `src/infra_fuzz`)
+
+Demo: `examples/pbt_fuzz_lab`.
+
+```moonbit
+@pbt.holds_for_all(@pbt.gen_int_range(0, 1000), fn(n) { n + n == 2 * n })
+let r = @pbt.check_with_shrink(gen, prop, @pbt.shrink_int) // minimal counterexample
+@pbt.round_trip(gen, encode, decode)  // encode/decode law
+let g = @fuzz.fuzz_graph_gen(5, 42)   // seeded, reproducible graphs
+@fuzz.shrink_fuzz_graph(failing)      // structurally smaller candidates
+```
+
+## Benchmarks and evidence
+
+- Algorithm + INFRA native benchmarks live under `benches/`; results under
+  [`benches/results/`](../../benches/results/).
+- Example outputs are guarded by `scripts/examples_guard.ps1`; latest
+  evidence in [`docs/examples/latest-examples-run.md`](../examples/latest-examples-run.md).
+- Full acceptance gate: `bash scripts/acceptance.sh`.
--- a/docs/zh/tutorials.md
+++ b/docs/zh/tutorials.md
@ -0,0 +1,37 @@
+# 上手教程 —— 每个方向五分钟
+
+英文完整版见 [`docs/tutorials/README.md`](../tutorials/README.md)。本页按方向给出
+关键 API、最小片段与对应可运行 demo（片段均取自 `examples/` 下真实代码，可编译
+可运行）。任一 demo 用 `moon run examples/<名称>` 运行。
+
+寻路核心算法的可执行文档见 [`docs/zh/algorithms/`](./algorithms/README.md)。
+
+| 方向 | demo | 关键 API |
+|---|---|---|
+| 寻路核心 | maze_solver / network_routing / eight_puzzle | `dijkstra(start, neighbors, is_goal)`，节点任意 `Eq + Hash` 类型 |
+| 迷你编译器 | mini_compiler_pipeline | 词法→语法→HM 推断→优化→字节码 VM+TCO、解释器差分、JS 发射 |
+| 正则引擎 | regex_toolkit | 命名捕获、`replace_all`、`split`、线性时间抗 ReDoS |
+| 结构化日志 | log_pipeline | trace span + W3C traceparent、JSON/logfmt/pretty、PII 脱敏 |
+| Actor | actor_worker_pool | 监督重启（`SupervisorSpec`）、路由策略、有界邮箱背压 |
+| 构建工具 | build_pipeline | 波次调度、脏闭包增量重建、缓存执行、auto-bisect |
+| 序列化 | serialization_studio | .proto 解析、二进制/JSON 往返、破坏性变更检测 |
+| DST | dst_explorer | 种子确定性重放、DPOR、缩小、线性一致性 |
+| 配置+差分 | config_diff_ops | TOML/INI、统一 diff、patch 应用/回退、diff3、semver |
+| 哈希 | hash_integrity | `sha256_hex`（与 sha256sum 一致）、`hmac_sha256`、`hkdf`、`pbkdf2_hmac_sha256`、流式 `Sha256Hasher`、`xxhash64` 分片 |
+| 压缩 | compress_workbench | `deflate`/`zstd_compress_entropy`/`lz4_compress` 无损往返、`zlib_compress_with_dict` 字典、损坏 CRC 拒绝 |
+| 时间+定时器 | time_scheduler | `parse_iso8601`、`parse_posix_tz` 夏令时、`parse_duration("2h30m")`、`TimerWheel`、`WorkStealingScheduler` |
+| 韧性原语 | resilience_gateway | `retry_run` 封顶退避、`CircuitBreaker` 状态机、`TokenBucket`/`SlidingWindowLimiter`、`Bulkhead`、`AimdLimiter::create(initial, min, max)`、`hedge_schedule` |
+| CLI | cli_devtool | 子命令解析、类型化校验 + choices、`suggest_option` 拼写建议、`help_text`、`completion_bash` |
+| 指标 | observability_kit | `HdrHistogram` 尾部分位数、可合并 `DDSketch`、`SpanTracer` total vs self |
+| 文本+数据结构 | text_editor_core | `Rope::delete(lo, hi)` 半开区间（`PieceTable::delete(off, count)` 是计数）、`grapheme_count`、`myers_diff`、`LruCache`、`BloomFilter`、`RoaringBitmap` |
+| 解析器组合子 | parser_playground | `parse_and_eval`（优先级/结合性正确）、`parse_json_recover` 错误恢复、`run_incremental` + `drive` 增量解析 |
+| PBT + fuzz | pbt_fuzz_lab | `holds_for_all`、`check_with_shrink` 最小反例、`round_trip` 往返律、`fuzz_graph_gen` 种子化图、`shrink_fuzz_graph` |
+
+## 性能证据
+
+- 哈希/压缩原生基准（含解读）：
+  [`benches/results/infra-hash-compress-native-2026-07-12.md`](../../benches/results/infra-hash-compress-native-2026-07-12.md)
+  —— 16 KiB 下 xxHash64 比 SHA-256 快约 7.5×；36 KB 下 LZ4 往返比 DEFLATE 快约 7×。
+- 其余方向基准见 `benches/`（timer/metrics/text/parser/codec/actor/dst 等），
+  结果归档于 `benches/results/`。
+- 全量门禁：`bash scripts/acceptance.sh`。
--- a/docs/项目申报书.md
+++ b/docs/项目申报书.md
@ -8,7 +8,7 @@
 | 参赛赛道 | MoonBit × CCF 开源创新大赛 |
 | 作品仓库（GitLink） | https://www.gitlink.org.cn/Taoyouce/moonbit-pathfinding |
 | GitHub 镜像 | https://github.com/Suquster/moonbit-pathfinding |
-| 包发布（mooncakes.io） | https://mooncakes.io/docs/Suquster/moonbit-pathfinding （`moon add Suquster/moonbit-pathfinding`，当前版本 v0.1.0） |
+| 包发布（mooncakes.io） | https://mooncakes.io/docs/Suquster/moonbit-pathfinding （`moon add Suquster/moonbit-pathfinding`，当前版本 v0.2.0） |
 | 开源许可 | Apache-2.0 |
 | 开发语言 | MoonBit |

@ -155,12 +155,15 @@ Rust `pathfinding` crate v4.11.0 公开 API + 预构建邻接表，`cargo --rele
 ## 七、用户体验

 - **低摩擦安装**：`moon add Suquster/moonbit-pathfinding` 一行安装（已发布
-  mooncakes.io v0.1.0）。
+  mooncakes.io v0.2.0）。
 - **交互式 Playground**：网格寻路可视化，由 `src/` 同一算法库编译为 wasm-gc 驱动。
 - **可执行文档**：README 示例即测试，复制即可运行。
- **全方向可运行 demo**：11 个 `moon run examples/...` 端到端工作流，寻路
+- **全方向可运行 demo**：20 个 `moon run examples/...` 端到端工作流，寻路
  （迷宫 / 路由 / 八数码）与 INFRA（迷你编译器 / 正则 / 日志 / actor /
-  构建工具 / 序列化 / DST / 配置与 diff）各方向同等闭环。
+  构建工具 / 序列化 / DST / 配置与 diff / 哈希 / 压缩 / 时间与定时器 /
+  韧性原语 / CLI / 指标观测 / 文本与数据结构 / 解析器组合子 / PBT 与
+  fuzz）各方向同等闭环；配套各方向上手教程
+  （`docs/tutorials/README.md` 与 `docs/zh/tutorials.md`）。
 - **AI-agent 友好**：后继函数式 API + `docs/AI_AGENT_USAGE.md` 用量指南。

 ---
@ -192,4 +195,4 @@ FIPS 规范，对拍对象为权威参考实现（CPython、Go stdlib、python-l

 ---

-*本申报书对应作品版本 v0.1.0，仓库与 mooncakes 包均已公开同步。*
+*本申报书对应作品版本 v0.2.0，仓库与 mooncakes 包均已公开同步。*
--- a/examples/cli_devtool/cli_devtool.mbt
+++ b/examples/cli_devtool/cli_devtool.mbt
@ -0,0 +1,93 @@
+// examples/cli_devtool — runnable demonstration of the `src/infra_cli`
+// direction as a deploy-tool CLI: declare a command with a subcommand,
+// parse args with defaults and bundled shorts, validate typed values with
+// choices, suggest fixes for typos, and emit help + bash completion.
+//
+// Run with:
+//   moon run examples/cli_devtool
+
+///|
+fn deploy_command() -> @cli.Command {
+  {
+    name: "shipit",
+    about: "deploy services to a cluster",
+    specs: [
+      @cli.flag_spec("verbose", "v", "enable verbose logging"),
+      @cli.value_spec("region", "r", "target region", Some("us-east-1")),
+    ],
+    subcommands: [
+      {
+        name: "deploy",
+        about: "roll out a service version",
+        specs: [
+          @cli.value_spec("service", "s", "service name", None),
+          @cli.value_spec("replicas", "n", "replica count", Some("2")),
+          @cli.value_spec("env", "e", "target environment", Some("staging")),
+          @cli.flag_spec("dry-run", "d", "plan only, no changes"),
+        ],
+        subcommands: [],
+      },
+    ],
+  }
+}
+
+///|
+fn main {
+  let cmd = deploy_command()
+  println("=== 1. parse a realistic invocation ===")
+  let argv = [
+    "deploy", "--service", "router", "-n", "4", "--env", "prod", "--dry-run",
+  ]
+  match @cli.parse(cmd, argv) {
+    Ok(parsed) => {
+      println("command path : \{parsed.command_path.join(" ")}")
+      let svc = parsed.value_of("service").unwrap_or("?")
+      println("service      : \{svc}")
+      match parsed.int_of("replicas") {
+        Ok(n) => println("replicas     : \{n} (typed Int64)")
+        Err(e) => println("replicas err : \{e}")
+      }
+      println("dry-run flag : \{parsed.has_flag("dry-run")}")
+      let region = parsed.value_of("region").unwrap_or("us-east-1")
+      println("region       : \{region} (default applies)")
+      println("")
+      println("=== 2. typed validation with choices ===")
+      let errors = @cli.validate_rules(parsed, [
+        @cli.rule("replicas", required=true, vtype=VInt),
+        @cli.rule("env", required=true, choices=["staging", "prod"]),
+      ])
+      println("rule errors  : \{errors.length()} (all rules satisfied)")
+    }
+    Err(e) => println("parse error: \{e}")
+  }
+  println("")
+  println("=== 3. helpful failure: unknown flag + typo suggestion ===")
+  match @cli.parse(cmd, ["deploy", "--servcie", "router"]) {
+    Ok(_) => println("unexpectedly parsed")
+    Err(e) => {
+      println("error        : \{e}")
+      match @cli.suggest_option("servcie", ["service", "replicas", "env"]) {
+        Some(s) => println("did you mean : --\{s}")
+        None => println("no suggestion")
+      }
+    }
+  }
+  println("")
+  println("=== 4. bundled short flags expand ===")
+  let expanded = @cli.expand_bundled_shorts(["-vd"], [
+    @cli.flag_spec("verbose", "v", ""),
+    @cli.flag_spec("dry-run", "d", ""),
+  ])
+  println("-vd expands to: \{expanded.join(" ")}")
+  println("")
+  println("=== 5. generated help ===")
+  println(@cli.help_text(cmd))
+  println("=== 6. bash completion (first lines) ===")
+  let script = @cli.completion_bash(cmd)
+  let lines = script.split("\n").collect()
+  let upto = if lines.length() < 6 { lines.length() } else { 6 }
+  for i in 0..<upto {
+    println(lines[i].to_owned())
+  }
+  println("... (\{lines.length()} lines total)")
+}
--- a/examples/cli_devtool/moon.pkg
+++ b/examples/cli_devtool/moon.pkg
@ -0,0 +1,16 @@
+// Runnable example: cli_devtool
+//
+// CLI argument-parsing toolchain with the `src/infra_cli` direction:
+// subcommands, flags/values with defaults, typed validation, typo
+// suggestions via Damerau-Levenshtein, help text, and shell completions.
+//
+// Run with:
+//   moon run examples/cli_devtool
+
+import {
+  "Suquster/moonbit-pathfinding/src/infra_cli" @cli,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/cli_devtool/pkg.generated.mbti
+++ b/examples/cli_devtool/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/cli_devtool"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/compress_workbench/compress_workbench.mbt
+++ b/examples/compress_workbench/compress_workbench.mbt
@ -0,0 +1,101 @@
+// examples/compress_workbench — runnable demonstration of the
+// `src/infra_compress` direction as a log-shipping workflow: compress a
+// repetitive log payload with DEFLATE / zlib / gzip / zstd / LZ4, compare
+// ratios, verify lossless round-trips, exploit shared dictionaries for
+// small payloads, and reject corrupted archives.
+//
+// Run with:
+//   moon run examples/compress_workbench
+
+///|
+fn build_log_payload() -> Array[Int] {
+  let sb = StringBuilder::new()
+  for i in 0..<40 {
+    sb.write_string(
+      "2026-07-12T18:0\{i % 10}:00Z INFO request handled path=/api/v1/route status=200\n",
+    )
+  }
+  @codec.utf8_bytes_of_string(sb.to_string())
+}
+
+///|
+fn ratio_permille(compressed : Int, original : Int) -> Int {
+  compressed * 1000 / original
+}
+
+///|
+fn main {
+  let data = build_log_payload()
+  let n = data.length()
+  println("=== 1. codec shoot-out on a \{n}-byte log payload ===")
+  let df = @compress.deflate(data)
+  let zl = @compress.zlib_compress(data)
+  let gz = @compress.gzip_compress(data)
+  let zs = @compress.zstd_compress_entropy(data, true)
+  let lz = @compress.lz4_compress(data)
+  println(
+    "deflate: \{df.length()} bytes (\{ratio_permille(df.length(), n)}‰)",
+  )
+  println(
+    "zlib   : \{zl.length()} bytes (\{ratio_permille(zl.length(), n)}‰)",
+  )
+  println(
+    "gzip   : \{gz.length()} bytes (\{ratio_permille(gz.length(), n)}‰)",
+  )
+  println(
+    "zstd   : \{zs.length()} bytes (\{ratio_permille(zs.length(), n)}‰)",
+  )
+  println(
+    "lz4    : \{lz.length()} bytes (\{ratio_permille(lz.length(), n)}‰)",
+  )
+  println("")
+  println("=== 2. lossless round-trips ===")
+  println("inflate(deflate)  == input: \{@compress.inflate(df) == Some(data)}")
+  println(
+    "zlib_decompress   == input: \{@compress.zlib_decompress(zl) == Some(data)}",
+  )
+  println(
+    "gzip_decompress   == input: \{@compress.gzip_decompress(gz) == Some(data)}",
+  )
+  println(
+    "zstd_decompress   == input: \{@compress.zstd_decompress(zs, n) == Some(data)}",
+  )
+  println(
+    "lz4_decompress    == input: \{@compress.lz4_decompress(lz, n) == Some(data)}",
+  )
+  let frame = @compress.lz4_frame_compress(data)
+  println(
+    "lz4 frame decode  == input: \{@compress.lz4_frame_decompress(frame, n) == Some(data)}",
+  )
+  println("")
+  println("=== 3. dictionary compression for small payloads ===")
+  let dict = @codec.utf8_bytes_of_string(
+    "INFO request handled path=/api/v1/route status=200",
+  )
+  let small = @codec.utf8_bytes_of_string(
+    "INFO request handled path=/api/v1/route status=200 rt=3ms",
+  )
+  let plain = @compress.zlib_compress(small)
+  let with_dict = @compress.zlib_compress_with_dict(small, dict)
+  println("zlib plain    : \{plain.length()} bytes")
+  println("zlib with dict: \{with_dict.length()} bytes")
+  println(
+    "dict round-trip ok: \{@compress.zlib_decompress_with_dict(with_dict, dict) == Some(small)}",
+  )
+  println("")
+  println("=== 4. corrupted archives are rejected, not mis-decoded ===")
+  let bad = gz.copy()
+  bad[bad.length() - 1] = (bad[bad.length() - 1] + 1) % 256
+  let bad_verdict = match @compress.gzip_decompress(bad) {
+    Some(_) => "accepted (unexpected)"
+    None => "rejected"
+  }
+  println("gzip with flipped CRC byte -> \{bad_verdict}")
+  let truncated = zl.copy()
+  let _ = truncated.pop()
+  let trunc_verdict = match @compress.zlib_decompress(truncated) {
+    Some(_) => "accepted (unexpected)"
+    None => "rejected"
+  }
+  println("zlib truncated by 1 byte   -> \{trunc_verdict}")
+}
--- a/examples/compress_workbench/moon.pkg
+++ b/examples/compress_workbench/moon.pkg
@ -0,0 +1,17 @@
+// Runnable example: compress_workbench
+//
+// Compression workbench with the `src/infra_compress` direction:
+// DEFLATE / zlib / gzip / zstd / LZ4 round-trips with ratios, dictionary
+// compression, and corrupted-input rejection.
+//
+// Run with:
+//   moon run examples/compress_workbench
+
+import {
+  "Suquster/moonbit-pathfinding/src/infra_compress" @compress,
+  "Suquster/moonbit-pathfinding/src/infra_codec" @codec,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/compress_workbench/pkg.generated.mbti
+++ b/examples/compress_workbench/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/compress_workbench"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/hash_integrity/hash_integrity.mbt
+++ b/examples/hash_integrity/hash_integrity.mbt
@ -0,0 +1,72 @@
+// examples/hash_integrity — runnable demonstration of the `src/infra_hash`
+// direction as a realistic artifact-integrity workflow: digest a release
+// artifact with the SHA-2 / SHA-3 / BLAKE2b families, authenticate it with
+// HMAC, derive session keys via HKDF, stretch a password via PBKDF2,
+// checksum streams incrementally, and pick fast non-crypto hashes for
+// hash-table sharding.
+//
+// Run with:
+//   moon run examples/hash_integrity
+
+///|
+fn main {
+  let artifact = "moonbit-pathfinding-v0.1.0.tar"
+  println("=== 1. release artifact digests (hex) ===")
+  println("sha256  : \{@hash.sha256_hex(artifact)}")
+  println("sha512  : \{@hash.sha512_hex(artifact)}")
+  println("sha3-256: \{@hash.sha3_256_hex(artifact)}")
+  println("blake2b : \{@hash.blake2b_hex(artifact)}")
+  println("md5     : \{@hash.md5_hex(artifact)} (legacy, display only)")
+  println("")
+  println("=== 2. HMAC authentication of a manifest ===")
+  let key = @hash.utf8_bytes("release-signing-key")
+  let manifest = @hash.utf8_bytes("name=pathfinding;version=0.1.0")
+  let tag = @hash.hmac_sha256(key, manifest)
+  println("hmac-sha256: \{@hash.digest_hex(tag)}")
+  let tampered = @hash.utf8_bytes("name=pathfinding;version=9.9.9")
+  let tag2 = @hash.hmac_sha256(key, tampered)
+  println("tamper detected (tags differ): \{tag != tag2}")
+  println("")
+  println("=== 3. HKDF session keys from a shared secret ===")
+  let ikm = @hash.utf8_bytes("shared-ecdh-secret")
+  let salt = @hash.utf8_bytes("handshake-salt")
+  let info = @hash.utf8_bytes("session-encryption")
+  match @hash.hkdf(ikm, salt, info, 32) {
+    Some(okm) => println("hkdf-sha256 (32B): \{@hash.digest_hex(okm)}")
+    None => println("hkdf failed")
+  }
+  println("")
+  println("=== 4. PBKDF2 password stretching ===")
+  let pw = @hash.utf8_bytes("correct horse battery staple")
+  let pw_salt = @hash.utf8_bytes("per-user-salt")
+  match @hash.pbkdf2_hmac_sha256(pw, pw_salt, 1000, 32) {
+    Some(dk) => println("pbkdf2 (1000 iters, 32B): \{@hash.digest_hex(dk)}")
+    None => println("pbkdf2 failed")
+  }
+  println("")
+  println("=== 5. streaming checksum equals one-shot ===")
+  let whole = @hash.utf8_bytes("chunk-a|chunk-b|chunk-c")
+  let one_shot = @hash.crc32(whole)
+  let h = @hash.Crc32Hasher::new()
+  h.update(@hash.utf8_bytes("chunk-a|"))
+  h.update(@hash.utf8_bytes("chunk-b|"))
+  h.update(@hash.utf8_bytes("chunk-c"))
+  let streamed = h.finalize()
+  println("crc32 one-shot : \{one_shot}")
+  println("crc32 streamed : \{streamed} (equal: \{one_shot == streamed})")
+  let sh = @hash.Sha256Hasher::new()
+  sh.update(@hash.utf8_bytes("chunk-a|chunk-b|"))
+  sh.update(@hash.utf8_bytes("chunk-c"))
+  let sha_stream = sh.finalize()
+  println("sha256 streamed == one-shot: \{sha_stream == @hash.sha256(whole)}")
+  println("")
+  println("=== 6. fast non-crypto hashes for sharding ===")
+  let keys = ["user-1", "user-2", "user-3", "user-4"]
+  for k in keys {
+    let b = @hash.utf8_bytes(k)
+    let shard = (@hash.xxhash64(b, 42) % 3UL).to_int()
+    println(
+      "\{k}: xxh64 shard #\{shard}, fnv1a=\{@hash.fnv1a_32(b)}, murmur3=\{@hash.murmur3_32(b, 0)}",
+    )
+  }
+}
--- a/examples/hash_integrity/moon.pkg
+++ b/examples/hash_integrity/moon.pkg
@ -0,0 +1,16 @@
+// Runnable example: hash_integrity
+//
+// Hashing / MAC / KDF toolchain with the `src/infra_hash` direction:
+// FIPS digests (SHA-2 / SHA-3 / BLAKE2b / MD5 / SHA-1), HMAC, HKDF,
+// PBKDF2, streaming hashers, and fast non-crypto hashes for tables.
+//
+// Run with:
+//   moon run examples/hash_integrity
+
+import {
+  "Suquster/moonbit-pathfinding/src/infra_hash" @hash,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/hash_integrity/pkg.generated.mbti
+++ b/examples/hash_integrity/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/hash_integrity"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/observability_kit/moon.pkg
+++ b/examples/observability_kit/moon.pkg
@ -0,0 +1,16 @@
+// Runnable example: observability_kit
+//
+// Metrics toolchain with the `src/infra_metrics` direction: HDR histogram
+// latency percentiles, mergeable DDSketch quantiles with bounded relative
+// error, and a span tracer with self/total time aggregation.
+//
+// Run with:
+//   moon run examples/observability_kit
+
+import {
+  "Suquster/moonbit-pathfinding/src/infra_metrics" @metrics,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/observability_kit/observability_kit.mbt
+++ b/examples/observability_kit/observability_kit.mbt
@ -0,0 +1,71 @@
+// examples/observability_kit — runnable demonstration of the
+// `src/infra_metrics` direction as a service-latency dashboard: record
+// request latencies into an HDR histogram, read tail percentiles, merge
+// per-shard DDSketches with bounded relative error, and profile a request
+// with a span tracer (total vs self time).
+//
+// Run with:
+//   moon run examples/observability_kit
+
+///|
+fn main {
+  println("=== 1. HDR histogram latency percentiles ===")
+  let hdr = @metrics.HdrHistogram::new(3)
+  // simulate 1000 requests: mostly fast, a slow tail
+  for i in 0..<1000 {
+    let latency = if i % 100 == 0 {
+      (900 + i / 10).to_int64() // 1% slow outliers
+    } else {
+      (10 + i % 40).to_int64() // 10-49 ms steady state
+    }
+    hdr.record(latency)
+  }
+  println("count : \{hdr.count()}, max: \{hdr.max_value()} ms")
+  for p in [50.0, 90.0, 99.0, 99.9] {
+    match hdr.value_at_percentile(p) {
+      Some(v) => println("p\{p} : \{v} ms")
+      None => println("p\{p} : n/a")
+    }
+  }
+  println("")
+  println("=== 2. mergeable DDSketch across shards ===")
+  let shard_a = @metrics.DDSketch::new(0.01)
+  let shard_b = @metrics.DDSketch::new(0.01)
+  for i in 0..<500 {
+    shard_a.add(10.0 + (i % 50).to_double())
+    shard_b.add(200.0 + (i % 300).to_double())
+  }
+  shard_a.merge_with(shard_b)
+  println(
+    "merged count : \{shard_a.count()} (error bound \{shard_a.error_bound()})",
+  )
+  match shard_a.quantile(0.5) {
+    Some(q) => println("merged p50   : \{q}")
+    None => println("merged p50   : n/a")
+  }
+  match shard_a.quantile(0.99) {
+    Some(q) => println("merged p99   : \{q}")
+    None => println("merged p99   : n/a")
+  }
+  println("")
+  println("=== 3. span tracer: total vs self time ===")
+  let tracer = @metrics.SpanTracer::new()
+  let root = tracer.start("handle_request", 0)
+  let _db = tracer.start("db_query", 10)
+  let _ = tracer.end(60) // db_query: 50ms
+  let _render = tracer.start("render", 65)
+  let _ = tracer.end(90) // render: 25ms
+  let _ = tracer.end(100) // handle_request: 100ms total
+  println("finished spans: \{tracer.finished_count()}")
+  for name in tracer.stat_names() {
+    match tracer.stat(name) {
+      Some((calls, total, self_time)) =>
+        println(
+          "\{name}: calls=\{calls}, total=\{total}ms, self=\{self_time}ms",
+        )
+      None => ()
+    }
+  }
+  let children = tracer.children_of(root)
+  println("root has \{children.length()} child spans")
+}
--- a/examples/observability_kit/pkg.generated.mbti
+++ b/examples/observability_kit/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/observability_kit"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/parser_playground/moon.pkg
+++ b/examples/parser_playground/moon.pkg
@ -0,0 +1,16 @@
+// Runnable example: parser_playground
+//
+// Parser-combinator toolchain with the `src/parser_combinator` direction:
+// arithmetic expression parsing and evaluation, JSON parsing with error
+// rendering, error recovery, and incremental (streaming) parsing.
+//
+// Run with:
+//   moon run examples/parser_playground
+
+import {
+  "Suquster/moonbit-pathfinding/src/parser_combinator" @pc,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/parser_playground/parser_playground.mbt
+++ b/examples/parser_playground/parser_playground.mbt
@ -0,0 +1,78 @@
+// examples/parser_playground — runnable demonstration of the
+// `src/parser_combinator` direction as a language-tooling workflow: parse
+// and evaluate arithmetic with correct precedence/associativity, parse
+// JSON with precise error positions, recover from malformed JSON while
+// collecting diagnostics, and feed a grammar incrementally chunk by chunk.
+//
+// Run with:
+//   moon run examples/parser_playground
+
+///|
+fn main {
+  println("=== 1. arithmetic: parse + eval with precedence ===")
+  for src in ["1 + 2 * 3", "(1 + 2) * 3", "2 ^ 3 ^ 2", "10 - 4 - 3"] {
+    match @pc.parse_and_eval(src) {
+      Ok(v) => println("\{src} = \{v}")
+      Err(_) => println("\{src} -> parse error")
+    }
+  }
+  println("")
+  println("=== 2. expression AST round-trip ===")
+  let parser = @pc.expr_parser()
+  match parser.parse_string("1 + 2 * 3") {
+    Ok(ast, _) =>
+      println("printed AST: \{@pc.print_expr(ast)} -> \{@pc.eval_expr(ast)}")
+    Fail(_, ..) => println("parse failed")
+  }
+  println("")
+  println("=== 3. JSON parsing with precise errors ===")
+  match
+    @pc.parse_json(
+      "{\"name\": \"router\", \"port\": 8080, \"tags\": [\"a\", \"b\"]}",
+    ) {
+    Ok(json) => println("parsed json : \{@pc.print_json(json)}")
+    Err(_) => println("unexpected parse failure")
+  }
+  let bad = "{\"name\": \"router\", \"port\": }"
+  let jp = @pc.json_parser()
+  match jp.explain_failure(bad) {
+    Some(msg) => println("bad json    : \{msg}")
+    None => println("bad json unexpectedly parsed")
+  }
+  println("")
+  println("=== 4. error recovery collects diagnostics ===")
+  let (recovered, errors) = @pc.parse_json_recover("[1, oops, 3]")
+  match recovered {
+    Some(json) => println("recovered   : \{@pc.print_json(json)}")
+    None => println("no recovery possible")
+  }
+  println("diagnostics : \{errors.length()} error(s) collected")
+  println("")
+  println("=== 5. incremental parsing, chunk by chunk ===")
+  // framed-number protocol: '<' digits '>' — a prefix that fails at the
+  // data boundary yields NeedMore instead of a false parse failure.
+  let digits = @pc.many1(
+    @pc.satisfy(fn(c) { c >= '0' && c <= '9' }, label="digit"),
+  )
+  let framed = @pc.map(@pc.between(@pc.pchar('<'), digits, @pc.pchar('>')), fn(
+    ds,
+  ) {
+    let mut n = 0
+    for c in ds {
+      n = n * 10 + (c.to_int() - '0'.to_int())
+    }
+    n
+  })
+  let grammar = @pc.lift(framed)
+  let first = grammar.run_incremental("<12")
+  match first {
+    NeedMore(_) =>
+      println("after chunk '<12': parser needs more input (no false failure)")
+    Done(_) => println("after chunk '<12': unexpectedly done")
+  }
+  let result = @pc.drive(first, ["34", "5>"], closed=true)
+  match result.value() {
+    Some(n) => println("streamed 3 chunks '<12'+'34'+'5>' -> \{n}")
+    None => println("stream parse failed")
+  }
+}
--- a/examples/parser_playground/pkg.generated.mbti
+++ b/examples/parser_playground/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/parser_playground"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/pbt_fuzz_lab/moon.pkg
+++ b/examples/pbt_fuzz_lab/moon.pkg
@ -0,0 +1,18 @@
+// Runnable example: pbt_fuzz_lab
+//
+// Property-based testing + fuzzing toolchain with the `src/infra_pbt` and
+// `src/infra_fuzz` directions: generators, properties with shrinking
+// counterexamples, distribution stats, encode/decode round-trip laws, and
+// random graph generation with structural shrinking.
+//
+// Run with:
+//   moon run examples/pbt_fuzz_lab
+
+import {
+  "Suquster/moonbit-pathfinding/src/infra_pbt" @pbt,
+  "Suquster/moonbit-pathfinding/src/infra_fuzz" @fuzz,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/pbt_fuzz_lab/pbt_fuzz_lab.mbt
+++ b/examples/pbt_fuzz_lab/pbt_fuzz_lab.mbt
@ -0,0 +1,89 @@
+// examples/pbt_fuzz_lab — runnable demonstration of the `src/infra_pbt` +
+// `src/infra_fuzz` directions as a testing-lab workflow: check properties
+// over generated inputs, watch a false property shrink to a minimal
+// counterexample, inspect generator distribution stats, verify an
+// encode/decode round-trip law, and generate + shrink random graphs for
+// differential fuzzing.
+//
+// Run with:
+//   moon run examples/pbt_fuzz_lab
+
+///|
+fn main {
+  println("=== 1. a true property holds for all generated inputs ===")
+  let gen_small = @pbt.gen_int_range(0, 1000)
+  let holds = @pbt.holds_for_all(gen_small, fn(n) { n + n == 2 * n })
+  println("forall n in [0,1000): n + n == 2n -> \{holds}")
+  println("")
+  println("=== 2. a false property shrinks to a minimal counterexample ===")
+  // claim: every number is < 500 — false, and shrinking should drive the
+  // counterexample down to the boundary 500.
+  let result = @pbt.check_with_shrink(
+    gen_small,
+    fn(n) { n < 500 },
+    @pbt.shrink_int,
+  )
+  match (result.passed, result.counterexample) {
+    (false, Some(cex)) =>
+      println("property n < 500 failed, shrunk counterexample: \{cex}")
+    (true, _) => println("property unexpectedly passed")
+    (false, None) => println("failed without counterexample")
+  }
+  println("")
+  println("=== 3. generator distribution stats ===")
+  let gen_dice = @pbt.frequency([
+    (1, @pbt.gen_int_range(0, 10)),
+    (3, @pbt.gen_int_range(10, 100)),
+  ])
+  let (ok, stats) = @pbt.holds_for_all_stats(gen_dice, fn(_n) { true }, fn(n) {
+    if n < 10 {
+      "small"
+    } else {
+      "large"
+    }
+  })
+  println(
+    "weighted 1:3 generator over \{stats.total()} samples -> small=\{stats.count("small")}, large=\{stats.count("large")} (ok=\{ok})",
+  )
+  println("")
+  println("=== 4. encode/decode round-trip law ===")
+  let rt = @pbt.round_trip(
+    @pbt.gen_int_range(0, 65536),
+    fn(n) {
+      let b = Bytes::makei(2, fn(i) {
+        if i == 0 {
+          (n / 256 % 256).to_byte()
+        } else {
+          (n % 256).to_byte()
+        }
+      })
+      b
+    },
+    fn(b) {
+      if b.length() == 2 {
+        Some(b[0].to_int() * 256 + b[1].to_int())
+      } else {
+        None
+      }
+    },
+  )
+  println("decode(encode(n)) == n for u16 big-endian: \{rt}")
+  println("")
+  println("=== 5. random graphs for differential fuzzing ===")
+  let rng = @pbt.rng_new(42)
+  let g = @fuzz.fuzz_graph_gen(8, 16).generate(rng)
+  println("generated graph: \{g.n} nodes, \{g.edges.length()} edges (seed 42)")
+  let g2 = @fuzz.fuzz_graph_gen(8, 16).generate(@pbt.rng_new(42))
+  println("same seed reproduces identical graph: \{g == g2}")
+  println("")
+  println("=== 6. structural shrinking of a failing graph ===")
+  let candidates = @fuzz.shrink_fuzz_graph(g)
+  println("shrink candidates: \{candidates.length()}")
+  let mut smaller = 0
+  for c in candidates {
+    if c.edges.length() < g.edges.length() || c.n < g.n {
+      smaller = smaller + 1
+    }
+  }
+  println("all candidates strictly smaller: \{smaller == candidates.length()}")
+}
--- a/examples/pbt_fuzz_lab/pkg.generated.mbti
+++ b/examples/pbt_fuzz_lab/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/pbt_fuzz_lab"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/resilience_gateway/moon.pkg
+++ b/examples/resilience_gateway/moon.pkg
@ -0,0 +1,17 @@
+// Runnable example: resilience_gateway
+//
+// Resilience toolchain with the `src/infra_resilience` direction:
+// exponential backoff with jitter, retry budgets, circuit breakers,
+// token-bucket and sliding-window rate limiting, bulkhead isolation,
+// AIMD adaptive concurrency, and hedged requests.
+//
+// Run with:
+//   moon run examples/resilience_gateway
+
+import {
+  "Suquster/moonbit-pathfinding/src/infra_resilience" @res,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/resilience_gateway/pkg.generated.mbti
+++ b/examples/resilience_gateway/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/resilience_gateway"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/resilience_gateway/resilience_gateway.mbt
+++ b/examples/resilience_gateway/resilience_gateway.mbt
@ -0,0 +1,94 @@
+// examples/resilience_gateway — runnable demonstration of the
+// `src/infra_resilience` direction as an API-gateway workflow: retry a
+// flaky upstream with capped exponential backoff, trip and recover a
+// circuit breaker, rate-limit clients with token bucket and sliding
+// window, isolate tenants with a bulkhead, adapt concurrency with AIMD,
+// and cut tail latency with hedged requests.
+//
+// Run with:
+//   moon run examples/resilience_gateway
+
+///|
+fn main {
+  println("=== 1. capped exponential backoff + retry ===")
+  let policy : @res.BackoffPolicy = {
+    base_ms: 100,
+    cap_ms: 2000,
+    max_retries: 6,
+  }
+  let sched = []
+  for attempt in 0..<6 {
+    sched.push(@res.backoff_delay(policy, attempt).to_string())
+  }
+  println("delays (ms) : \{sched.join(", ")}")
+  println(
+    "jittered #3 : \{@res.backoff_delay_jittered(policy, 3, 42)} ms (deterministic seed)",
+  )
+  let (ok, attempts) = @res.retry_run(policy, fn(attempt) { attempt >= 2 })
+  println("flaky upstream succeeds on 3rd try: ok=\{ok}, attempts=\{attempts}")
+  println("")
+  println("=== 2. circuit breaker state machine ===")
+  let cb = @res.CircuitBreaker::create(3, 1000)
+  println("initial     : \{cb.state_of()}")
+  cb.record_failure(0)
+  cb.record_failure(10)
+  cb.record_failure(20)
+  println("3 failures  : \{cb.state_of()} (allow now: \{cb.allow(30)})")
+  println("after cooldown: allow=\{cb.allow(1500)} -> \{cb.state_of()}")
+  cb.record_success()
+  println("probe success: \{cb.state_of()}")
+  println("")
+  println("=== 3. rate limiting: token bucket vs sliding window ===")
+  let bucket = @res.TokenBucket::create(3, 1)
+  let bucket_hits = []
+  for i in 0..<5 {
+    bucket_hits.push(bucket.try_acquire(i.to_int64() * 10).to_string())
+  }
+  println("token bucket (cap 3): \{bucket_hits.join(", ")}")
+  let win = @res.SlidingWindowLimiter::create(1000, 3)
+  let win_hits = []
+  for i in 0..<5 {
+    win_hits.push(win.try_acquire(i.to_int64() * 100).to_string())
+  }
+  println("sliding window (3/s) : \{win_hits.join(", ")}")
+  println("after window slides  : \{win.try_acquire(1500)}")
+  println("")
+  println("=== 4. bulkhead isolation per tenant ===")
+  let bh = @res.Bulkhead::create(2, 1)
+  let admissions = []
+  for _i in 0..<4 {
+    let verdict = match bh.try_acquire() {
+      Admitted => "admitted"
+      Enqueued => "enqueued"
+      Rejected => "rejected"
+    }
+    admissions.push(verdict)
+  }
+  println("4 concurrent calls (2 slots + 1 queue): \{admissions.join(", ")}")
+  let _ = bh.release()
+  println(
+    "after release: in-flight=\{bh.in_flight_count()}, queued=\{bh.queued_count()}, rejected=\{bh.rejected_count()}",
+  )
+  println("")
+  println("=== 5. AIMD adaptive concurrency ===")
+  let aimd = @res.AimdLimiter::create(10, 1, 100)
+  for _i in 0..<5 {
+    aimd.on_success()
+  }
+  println("after 5 successes : limit = \{aimd.current_limit()}")
+  aimd.on_overload()
+  println(
+    "after overload    : limit = \{aimd.current_limit()} (multiplicative decrease)",
+  )
+  println("")
+  println("=== 6. hedged requests cut tail latency ===")
+  let hedge : @res.HedgePolicy = { hedge_after_ms: 50, max_hedges: 2 }
+  println(
+    "hedge fire times : \{@res.hedge_schedule(hedge).map(fn(t) { t.to_string() }).join(", ")} ms",
+  )
+  let latencies = [300, 80, 120]
+  let (winner, latency, wasted) = @res.hedge_outcome(hedge, latencies)
+  println(
+    "upstream latencies \{latencies.map(fn(t) { t.to_string() }).join("/")}ms -> winner #\{winner} at \{latency}ms (wasted \{wasted})",
+  )
+}
--- a/examples/text_editor_core/moon.pkg
+++ b/examples/text_editor_core/moon.pkg
@ -0,0 +1,18 @@
+// Runnable example: text_editor_core
+//
+// Text + data-structure toolchain with the `src/infra_text` and
+// `src/infra_ds` directions: rope editing with line/column mapping,
+// piece-table edits, grapheme clusters and display width, Myers character
+// diff, plus LRU cache, bloom filter, and roaring bitmap indexes.
+//
+// Run with:
+//   moon run examples/text_editor_core
+
+import {
+  "Suquster/moonbit-pathfinding/src/infra_text" @text,
+  "Suquster/moonbit-pathfinding/src/infra_ds" @ds,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/text_editor_core/pkg.generated.mbti
+++ b/examples/text_editor_core/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/text_editor_core"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/text_editor_core/text_editor_core.mbt
+++ b/examples/text_editor_core/text_editor_core.mbt
@ -0,0 +1,82 @@
+// examples/text_editor_core — runnable demonstration of the
+// `src/infra_text` + `src/infra_ds` directions as an editor-backend
+// workflow: edit a buffer through a rope with line/column mapping, apply
+// the same edits through a piece table, segment graphemes and compute
+// terminal display width, produce a Myers character diff, and back the
+// editor with LRU / bloom / roaring-bitmap indexes.
+//
+// Run with:
+//   moon run examples/text_editor_core
+
+///|
+fn main {
+  println("=== 1. rope editing with line/column mapping ===")
+  let rope = @text.Rope::from_string("fn main {\n  todo\n}\n")
+  rope.delete(12, 16) // half-open range [12, 16) removes "todo"
+  rope.insert(12, "println(\"hi\")")
+  println("buffer after edit:\n\{rope.to_string()}")
+  println(
+    "len \{rope.len()}, lines \{rope.line_count()}, depth \{rope.depth()}",
+  )
+  let (line, col) = rope.line_col_at(14)
+  println("offset 14 -> line \{line}, col \{col}")
+  println("line 1 starts at offset \{rope.offset_of_line(1)}")
+  println("")
+  println("=== 2. piece table applies the same edit ===")
+  let pt = @text.PieceTable::from_string("fn main {\n  todo\n}\n")
+  pt.delete(12, 4)
+  pt.insert(12, "println(\"hi\")")
+  println("piece table == rope: \{pt.to_string() == rope.to_string()}")
+  println("pieces: \{pt.piece_count()}, len: \{pt.len()}")
+  println("")
+  println("=== 3. graphemes + display width ===")
+  let s = "héllo 世界"
+  println("string       : \{s}")
+  println("graphemes    : \{@text.grapheme_count(s)}")
+  println("display width: \{@text.display_width(s)} (CJK counts as 2 cells)")
+  println("case-fold eq : \{@text.eq_fold("HÉLLO 世界", s)}")
+  println("")
+  println("=== 4. Myers character diff ===")
+  let before = "let x = compute(a, b)"
+  let after = "let x = compute(a, b, c)"
+  let ops = @text.myers_diff(before, after)
+  println("edit cost: \{@text.diff_edit_cost(ops)}")
+  println("apply(diff) == after : \{@text.diff_apply(ops) == after}")
+  println("source(diff) == before: \{@text.diff_source(ops) == before}")
+  println("")
+  println("=== 5. LRU cache for rendered lines ===")
+  let cache : @ds.LruCache[Int, String] = @ds.LruCache::create(2)
+  cache.put(1, "render:line-1")
+  cache.put(2, "render:line-2")
+  let _ = cache.get(1) // touch 1 so 2 becomes LRU
+  cache.put(3, "render:line-3") // evicts 2
+  let hit1 = match cache.get(1) {
+    Some(_) => "hit"
+    None => "miss"
+  }
+  let hit2 = match cache.get(2) {
+    Some(_) => "hit"
+    None => "miss (evicted)"
+  }
+  println(
+    "line 1: \{hit1}, line 2: \{hit2}, size \{cache.size()}/\{cache.cap()}",
+  )
+  println("")
+  println("=== 6. bloom filter + roaring bitmap indexes ===")
+  let bloom = @ds.BloomFilter::create(1024, 3)
+  bloom.insert("symbol:main")
+  bloom.insert("symbol:rope")
+  println("bloom has 'symbol:main' : \{bloom.contains("symbol:main")}")
+  println("bloom has 'symbol:nope' : \{bloom.contains("symbol:nope")}")
+  let dirty_lines = @ds.RoaringBitmap::new()
+  let _ = dirty_lines.add(1)
+  let _ = dirty_lines.add(2)
+  let _ = dirty_lines.add(100000)
+  let visible = @ds.RoaringBitmap::new()
+  let _ = visible.add(2)
+  let _ = visible.add(3)
+  let redraw = dirty_lines.intersect_with(visible)
+  println(
+    "dirty ∩ visible lines: \{redraw.to_array().map(fn(v) { v.to_string() }).join(", ")} (cardinality \{redraw.cardinality()})",
+  )
+}
--- a/examples/time_scheduler/moon.pkg
+++ b/examples/time_scheduler/moon.pkg
@ -0,0 +1,18 @@
+// Runnable example: time_scheduler
+//
+// Date/time + timer toolchain with the `src/infra_time` and
+// `src/infra_timer` directions: RFC 3339 / ISO 8601 parsing and
+// formatting, civil-calendar arithmetic, POSIX TZ DST rules, ISO 8601
+// durations, a hierarchical timer wheel, and a work-stealing scheduler.
+//
+// Run with:
+//   moon run examples/time_scheduler
+
+import {
+  "Suquster/moonbit-pathfinding/src/infra_time" @time,
+  "Suquster/moonbit-pathfinding/src/infra_timer" @timer,
+}
+
+options(
+  "is-main": true,
+)
--- a/examples/time_scheduler/pkg.generated.mbti
+++ b/examples/time_scheduler/pkg.generated.mbti
@ -0,0 +1,13 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Suquster/moonbit-pathfinding/examples/time_scheduler"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits
+
--- a/examples/time_scheduler/time_scheduler.mbt
+++ b/examples/time_scheduler/time_scheduler.mbt
@ -0,0 +1,110 @@
+// examples/time_scheduler — runnable demonstration of the `src/infra_time`
+// + `src/infra_timer` directions as a cron-like maintenance-window
+// workflow: parse RFC 3339 timestamps, do civil-calendar arithmetic, apply
+// a POSIX TZ rule with DST, parse ISO 8601 durations, schedule timeouts on
+// a hierarchical timer wheel, and dispatch jobs on a work-stealing
+// scheduler.
+//
+// Run with:
+//   moon run examples/time_scheduler
+
+///|
+fn main {
+  println("=== 1. parse + format RFC 3339 / ISO 8601 ===")
+  let dt = match @time.parse_iso8601("2026-07-12T18:30:00.250Z") {
+    Some(d) => d
+    None => {
+      println("parse failed")
+      return
+    }
+  }
+  println("parsed      : \{dt}")
+  println("iso8601     : \{@time.format_iso8601(dt)}")
+  println("rfc2822     : \{@time.format_rfc2822(dt, 0)}")
+  println("rfc3339 +08 : \{@time.format_rfc3339_with_offset(dt, 8 * 60)}")
+  println("iso week    : \{@time.format_iso_week_date(dt)}")
+  let pretty = @time.strftime(dt, "%a %b %e, %Y %H:%M:%S")
+  println("strftime    : \{pretty}")
+  println("")
+  println("=== 2. civil-calendar arithmetic ===")
+  let next_month = dt.add_months(1)
+  println("+1 month    : \{@time.format_iso_date(next_month)}")
+  let leap = @time.is_leap_year(2028)
+  println(
+    "2028 leap   : \{leap}, Feb 2028 has \{@time.days_in_month(2028, 2)} days",
+  )
+  let deadline = dt.add_days(45)
+  println(
+    "+45 days    : \{@time.format_iso_date(deadline)} (weekday \{deadline.weekday()})",
+  )
+  println("day of year : \{dt.day_of_year()}")
+  println("")
+  println("=== 3. POSIX TZ rule with DST (US Eastern) ===")
+  match @time.parse_posix_tz("EST5EDT,M3.2.0/2,M11.1.0/2") {
+    Some(rule) => {
+      let (offset, name) = @time.tz_offset_at(rule, dt)
+      println(
+        "2026-07-12 UTC -> \{name} (offset \{offset / 3600}h), DST: \{@time.is_dst(rule, dt)}",
+      )
+      println(
+        "local time  : \{@time.format_rfc3339_with_offset(dt, offset / 60)}",
+      )
+      let winter = match @time.parse_iso8601("2026-01-12T18:30:00Z") {
+        Some(d) => d
+        None => dt
+      }
+      let (woff, wname) = @time.tz_offset_at(rule, winter)
+      println(
+        "2026-01-12 UTC -> \{wname} (offset \{woff / 3600}h), DST: \{@time.is_dst(rule, winter)}",
+      )
+    }
+    None => println("tz parse failed")
+  }
+  println("")
+  println("=== 4. human-readable durations ===")
+  match @time.parse_duration("2h30m") {
+    Some(d) => {
+      println(
+        "2h30m       : \{d.total_minutes()} minutes (round-trip: \{d.to_string()})",
+      )
+      let ends = dt.add_duration(d)
+      println("window ends : \{@time.format_iso8601(ends)}")
+    }
+    None => println("duration parse failed")
+  }
+  println("")
+  println("=== 5. hierarchical timer wheel ===")
+  let wheel = @timer.TimerWheel::new()
+  let t_short = wheel.schedule(3)
+  let t_mid = wheel.schedule(10)
+  let t_cancel = wheel.schedule(5)
+  println("scheduled 3 timers (ticks 3, 10, 5), pending = \{wheel.pending()}")
+  println("cancel #\{t_cancel}: \{wheel.cancel(t_cancel)}")
+  let mut fired_short = false
+  let mut fired_mid = false
+  for _tick in 0..<12 {
+    let fired = wheel.advance()
+    for id in fired {
+      if id == t_short {
+        fired_short = true
+      }
+      if id == t_mid {
+        fired_mid = true
+      }
+    }
+  }
+  println(
+    "after 12 ticks: short fired = \{fired_short}, mid fired = \{fired_mid}, pending = \{wheel.pending()}",
+  )
+  println("")
+  println("=== 6. work-stealing scheduler ===")
+  let ws = @timer.WorkStealingScheduler::new(4)
+  // pile all work on worker 0 so idle workers must steal
+  for i in 0..<16 {
+    let _ = ws.submit(0, if i % 5 == 0 { 2 } else { 0 })
+  }
+  let executed = ws.run()
+  println(
+    "workers: \{ws.workers()}, executed \{executed.length()} tasks, steals: \{ws.steal_count()}",
+  )
+}
--- a/moon.mod
+++ b/moon.mod
@ -1,6 +1,6 @@
 name = "Suquster/moonbit-pathfinding"

-version = "0.1.0"
+version = "0.2.0"

 readme = "README.md"