/ ROADMAP.adoc
ROADMAP.adoc
1 // SPDX-License-Identifier: AGPL-3.0-or-later 2 // SPDX-FileCopyrightText: 2025 Hyperpolymath Contributors 3 = Bebop-V-FFI Roadmap 4 :toc: left 5 :toclevels: 3 6 :icons: font 7 :source-highlighter: rouge 8 9 > Development roadmap from initial implementation through next-generation hybrid architecture 10 11 == Quick Summary 12 13 === Done (v0.0.1) 14 15 * [x] ABI contract (`include/bebop_v_ffi.h`) — stable 16 * [x] V bindings (`v/bebop_bridge.v`) — complete 17 * [x] Zig build system and stub implementation 18 * [x] Documentation and white paper 19 * [x] Schema (`schemas/sensors.bop`) 20 21 === Now 22 23 * Implement actual Bebop decode in Zig 24 * Generate real wire bytes for golden vectors (using `bebopc`) 25 * Implement encode 26 27 === Next 28 29 * CI matrix (Linux/macOS, multiple Zig versions) 30 * V integration test (link V to Zig .so) 31 * Rust implementation (plug-compatible; help wanted) 32 33 === Later 34 35 * Fuzz tests around decode/encode 36 * Publish V module packaging guidance 37 * WASM target for browser/Deno 38 39 --- 40 41 == Detailed Waypoints 42 43 This roadmap outlines three major waypoints for Bebop-V-FFI development: 44 45 1. **Release** - Core FFI implementation, testing, documentation 46 2. **Package** - Distribution via package managers, ecosystem integration 47 3. **Next-Gen Development** - Rust-V-Bebop hybrid architecture 48 49 Each waypoint builds on the previous, with clear milestones and success criteria. 50 51 --- 52 53 == Waypoint 1: Release 54 55 *Goal*: Stable v1.0.0 release with complete FFI bindings, comprehensive tests, and production-ready documentation. 56 57 === Phase 1.1: Core Implementation 58 59 [cols="1,3,1"] 60 |=== 61 |Status |Task |Priority 62 63 |[ ] 64 |Implement Bebop runtime C wrapper 65 |P0 66 67 |[ ] 68 |Create V FFI bindings to C layer 69 |P0 70 71 |[ ] 72 |Implement zero-copy buffer management 73 |P0 74 75 |[ ] 76 |Add arena allocator for embedded targets 77 |P1 78 79 |[ ] 80 |Implement endianness handling (little/big) 81 |P1 82 83 |[ ] 84 |Add bounds checking for all decode operations 85 |P0 86 |=== 87 88 === Phase 1.2: Code Generation 89 90 [cols="1,3,1"] 91 |=== 92 |Status |Task |Priority 93 94 |[ ] 95 |Create `bebopc` V generator plugin 96 |P0 97 98 |[ ] 99 |Generate struct definitions from `.bop` schemas 100 |P0 101 102 |[ ] 103 |Generate encode/decode functions per type 104 |P0 105 106 |[ ] 107 |Support all Bebop primitive types 108 |P0 109 110 |[ ] 111 |Support arrays, maps, unions 112 |P1 113 114 |[ ] 115 |Support message evolution (optional fields) 116 |P1 117 118 |[ ] 119 |Add `--embed` flag for single-file output 120 |P2 121 |=== 122 123 === Phase 1.3: Kaldor Integration 124 125 [cols="1,3,1"] 126 |=== 127 |Status |Task |Priority 128 129 |[ ] 130 |Define Kaldor telemetry schemas (`.bop` files) 131 |P0 132 133 |[ ] 134 |Generate V bindings for Kaldor messages 135 |P0 136 137 |[ ] 138 |Integrate with ESP32-C6 Matter firmware 139 |P1 140 141 |[ ] 142 |Test with Kaldor backend (Deno) 143 |P1 144 145 |[ ] 146 |Validate cross-language wire compatibility 147 |P0 148 |=== 149 150 === Phase 1.4: Testing & Documentation 151 152 [cols="1,3,1"] 153 |=== 154 |Status |Task |Priority 155 156 |[ ] 157 |Unit tests for all encode/decode operations 158 |P0 159 160 |[ ] 161 |Property-based tests (fuzzing) 162 |P1 163 164 |[ ] 165 |Integration tests with real hardware (ESP32-C6) 166 |P1 167 168 |[ ] 169 |Performance benchmarks vs. raw C 170 |P2 171 172 |[ ] 173 |API documentation (full coverage) 174 |P0 175 176 |[ ] 177 |Tutorial: Getting Started guide 178 |P1 179 180 |[ ] 181 |Tutorial: Kaldor integration guide 182 |P1 183 |=== 184 185 === Release Criteria 186 187 * [ ] All P0 tasks complete 188 * [ ] 80%+ test coverage 189 * [ ] Zero memory leaks (Valgrind clean) 190 * [ ] <20KB compiled library size 191 * [ ] Benchmarks documented 192 * [ ] RSR Bronze compliance verified 193 * [ ] Security review complete 194 195 === Target: v1.0.0 196 197 --- 198 199 == Waypoint 2: Package 200 201 *Goal*: Distribute Bebop-V-FFI through standard package managers and integrate with the broader V and IIoT ecosystems. 202 203 === Phase 2.1: V Package Manager (vpkg/vpm) 204 205 [cols="1,3,1"] 206 |=== 207 |Status |Task |Priority 208 209 |[ ] 210 |Create `v.mod` manifest file 211 |P0 212 213 |[ ] 214 |Register with VPM registry 215 |P1 216 217 |[ ] 218 |Add install instructions to README 219 |P0 220 221 |[ ] 222 |Test installation from fresh system 223 |P1 224 225 |[ ] 226 |Document version compatibility matrix 227 |P1 228 |=== 229 230 === Phase 2.2: System Packages 231 232 [cols="1,3,1"] 233 |=== 234 |Status |Task |Priority 235 236 |[ ] 237 |Create Guix package definition 238 |P1 239 240 |[ ] 241 |Create Nix flake 242 |P2 243 244 |[ ] 245 |Create AUR PKGBUILD (Arch Linux) 246 |P2 247 248 |[ ] 249 |Create Homebrew formula (macOS) 250 |P2 251 252 |[ ] 253 |Create Debian/Ubuntu .deb package 254 |P3 255 |=== 256 257 === Phase 2.3: Ecosystem Integration 258 259 [cols="1,3,1"] 260 |=== 261 |Status |Task |Priority 262 263 |[ ] 264 |Publish Kaldor schemas to central registry 265 |P1 266 267 |[ ] 268 |Create GitHub Action for schema validation 269 |P2 270 271 |[ ] 272 |Add to awesome-v and awesome-iiot lists 273 |P2 274 275 |[ ] 276 |Write blog post / announcement 277 |P1 278 279 |[ ] 280 |Create demo video 281 |P2 282 |=== 283 284 === Phase 2.4: CI/CD & Releases 285 286 [cols="1,3,1"] 287 |=== 288 |Status |Task |Priority 289 290 |[ ] 291 |Automated releases via GitLab CI / GitHub Actions 292 |P1 293 294 |[ ] 295 |Semantic versioning automation 296 |P1 297 298 |[ ] 299 |CHANGELOG generation 300 |P1 301 302 |[ ] 303 |Binary artifacts for major platforms 304 |P2 305 306 |[ ] 307 |Reproducible builds (Guix/Nix) 308 |P1 309 |=== 310 311 === Package Criteria 312 313 * [ ] Available via `vpkg install bebop-v-ffi` 314 * [ ] Guix package in official channel 315 * [ ] Nix flake in nixpkgs (or overlay) 316 * [ ] AUR package available 317 * [ ] Automated release pipeline 318 * [ ] Semantic versioning enforced 319 320 === Target: v1.1.0 - v1.x 321 322 --- 323 324 == Waypoint 3: Next-Gen Development (Rust-V-Bebop) 325 326 *Goal*: Hybrid architecture combining Rust's safety guarantees with V's simplicity, enabling advanced IIoT patterns. 327 328 === Vision 329 330 The next generation of Bebop-V-FFI will introduce a *Rust core* with V bindings, similar to the https://github.com/hyperpolymath/bunsenite[bunsenite] architecture: 331 332 [source] 333 ---- 334 ┌─────────────────────────────────────────────────────────┐ 335 │ V Application │ 336 │ (ESP32-C6 / RISC-V firmware) │ 337 └─────────────────────────┬───────────────────────────────┘ 338 │ 339 ▼ 340 ┌─────────────────────────────────────────────────────────┐ 341 │ Zig FFI Layer │ 342 │ (Stable C ABI, ~15KB) │ 343 └─────────────────────────┬───────────────────────────────┘ 344 │ 345 ▼ 346 ┌─────────────────────────────────────────────────────────┐ 347 │ Rust Core Library │ 348 │ (bebop-rs + custom Kaldor extensions) │ 349 ├─────────────────────────────────────────────────────────┤ 350 │ - Zero-copy parsing (verified safe) │ 351 │ - Compile-time schema validation │ 352 │ - Async encoding for large messages │ 353 │ - WASM target for browser/Deno │ 354 └─────────────────────────┬───────────────────────────────┘ 355 │ 356 ▼ 357 ┌─────────────────────────────────────────────────────────┐ 358 │ Bebop Wire Format │ 359 └─────────────────────────────────────────────────────────┘ 360 ---- 361 362 === Phase 3.1: Rust Core 363 364 [cols="1,3,1"] 365 |=== 366 |Status |Task |Priority 367 368 |[ ] 369 |Fork/integrate bebop-rs crate 370 |P0 371 372 |[ ] 373 |Add Kaldor-specific extensions 374 |P1 375 376 |[ ] 377 |Implement zero-copy views (lifetimes) 378 |P0 379 380 |[ ] 381 |Add `#![deny(unsafe_code)]` audit 382 |P0 383 384 |[ ] 385 |WASM target for browser/Deno 386 |P1 387 388 |[ ] 389 |`no_std` support for bare-metal 390 |P1 391 |=== 392 393 === Phase 3.2: Zig FFI Layer 394 395 [cols="1,3,1"] 396 |=== 397 |Status |Task |Priority 398 399 |[ ] 400 |Design stable C ABI interface 401 |P0 402 403 |[ ] 404 |Implement Zig wrapper functions 405 |P0 406 407 |[ ] 408 |Add error code translation 409 |P1 410 411 |[ ] 412 |Memory ownership semantics (who frees?) 413 |P0 414 415 |[ ] 416 |Thread safety guarantees 417 |P1 418 |=== 419 420 === Phase 3.3: V Bindings (v2) 421 422 [cols="1,3,1"] 423 |=== 424 |Status |Task |Priority 425 426 |[ ] 427 |Update V bindings to use Zig FFI 428 |P0 429 430 |[ ] 431 |Maintain API compatibility with v1 432 |P1 433 434 |[ ] 435 |Add async encode/decode support 436 |P2 437 438 |[ ] 439 |Streaming decode for large messages 440 |P2 441 442 |[ ] 443 |Compile-time schema embedding 444 |P2 445 |=== 446 447 === Phase 3.4: Multi-Language Parity 448 449 [cols="1,3,1"] 450 |=== 451 |Status |Task |Priority 452 453 |[ ] 454 |Deno/TypeScript bindings via WASM 455 |P1 456 457 |[ ] 458 |ReScript bindings (Kaldor frontend) 459 |P2 460 461 |[ ] 462 |Python bindings (PyO3) 463 |P3 464 465 |[ ] 466 |Go bindings (CGo) 467 |P3 468 |=== 469 470 === Phase 3.5: Advanced Features 471 472 [cols="1,3,1"] 473 |=== 474 |Status |Task |Priority 475 476 |[ ] 477 |Schema registry integration 478 |P2 479 480 |[ ] 481 |Message validation hooks 482 |P2 483 484 |[ ] 485 |Encryption layer (optional) 486 |P2 487 488 |[ ] 489 |Compression (LZ4) for large payloads 490 |P3 491 492 |[ ] 493 |Metrics/tracing integration 494 |P3 495 |=== 496 497 === Next-Gen Criteria 498 499 * [ ] Rust core with zero `unsafe` blocks 500 * [ ] Zig FFI with stable C ABI 501 * [ ] V bindings API-compatible with v1 502 * [ ] WASM support for browser/Deno 503 * [ ] `no_std` support for bare-metal 504 * [ ] RSR Silver tier compliance 505 * [ ] Formal verification (stretch goal) 506 507 === Target: v2.0.0 508 509 --- 510 511 == Timeline 512 513 [source] 514 ---- 515 2025 Q1 │ Waypoint 1: Release 516 │ ├── Core implementation 517 │ ├── Code generation 518 │ └── Kaldor integration 519 │ 520 2025 Q2 │ Waypoint 1 (cont.) + Waypoint 2: Package 521 │ ├── Testing & documentation 522 │ ├── v1.0.0 release 523 │ ├── VPM registration 524 │ └── System packages 525 │ 526 2025 Q3 │ Waypoint 2 (cont.) 527 │ ├── Ecosystem integration 528 │ └── CI/CD automation 529 │ 530 2025 Q4 │ Waypoint 3: Next-Gen Development 531 │ ├── Rust core development 532 │ └── Zig FFI layer 533 │ 534 2026 Q1 │ Waypoint 3 (cont.) 535 │ ├── V bindings v2 536 │ ├── Multi-language parity 537 │ └── v2.0.0 release 538 ---- 539 540 == Success Metrics 541 542 === Adoption 543 544 * [ ] 500+ VPM downloads within 6 months 545 * [ ] 50+ GitHub stars 546 * [ ] 10+ production deployments (Kaldor nodes) 547 * [ ] 5+ external contributors 548 549 === Quality 550 551 * [ ] 90%+ test coverage 552 * [ ] <5ms encode latency (1KB message) 553 * [ ] Zero memory leaks 554 * [ ] Zero CVEs in first year 555 556 === Ecosystem 557 558 * [ ] Integrated into 3+ Kaldor device types 559 * [ ] Used by 2+ external IIoT projects 560 * [ ] Featured in V community showcase 561 562 == Contributing 563 564 Contributions are welcome at all phases! See link:CONTRIBUTING.md[CONTRIBUTING.md] for: 565 566 * TPCF perimeter assignments 567 * Coding standards 568 * Pull request process 569 570 === Good First Issues 571 572 Look for issues labeled: 573 574 * `good first issue` - Beginner-friendly tasks 575 * `help wanted` - Areas where we need community help 576 * `documentation` - Non-code contributions 577 578 == Resources 579 580 * https://bebop.sh/guide/[Bebop Documentation] 581 * https://github.com/vlang/v/blob/master/doc/docs.md[V Language Documentation] 582 * https://github.com/hyperpolymath/kaldor-iiot[Kaldor IIoT Platform] 583 * https://github.com/hyperpolymath/bunsenite[Bunsenite] - Reference FFI architecture 584 585 --- 586 587 *Status*: Active Development + 588 *Last Updated*: 2025-12-24 + 589 *Next Review*: Monthly 590 591 _"Plan the work, work the plan."_