1  ;; SPDX-License-Identifier: AGPL-3.0-or-later
 2  ;; SPDX-FileCopyrightText: 2025 Hyperpolymath Contributors
 3  ;;
 4  ;; PLAYBOOK.scm - Operational runbooks and procedures
 5  
 6  (playbook
 7   (version 1)
 8   (project "bebop-v-ffi")
 9  
10   (runbooks
11    ((id "add-new-message-type")
12     (description "Add a new Bebop message type to the FFI")
13     (steps
14      "1. Add message to schemas/*.bop"
15      "2. Run scripts/gen_c_from_schema.sh"
16      "3. Add corresponding struct to include/bebop_v_ffi.h"
17      "4. Add decode/encode functions to header"
18      "5. Update v/bebop_bridge.v with V bindings"
19      "6. Implement in Zig (implementations/zig/)"
20      "7. Add golden test vectors"
21      "8. Update docs if needed"))
22  
23    ((id "add-implementation")
24     (description "Add a new language implementation (e.g., Rust)")
25     (steps
26      "1. Create implementations/<lang>/ directory"
27      "2. Implement all functions from bebop_v_ffi.h"
28      "3. Use VBytes for all byte slices"
29      "4. Implement context-based allocation"
30      "5. Pass all golden vector tests"
31      "6. Document build process"
32      "7. Add to CI matrix"))
33  
34    ((id "release-checklist")
35     (description "Steps before tagging a release")
36     (steps
37      "1. All golden vector tests pass"
38      "2. ABI header unchanged or version bumped"
39      "3. CHANGELOG updated"
40      "4. STATE.scm updated"
41      "5. Docs reflect current state"
42      "6. CI green on all platforms"
43      "7. Tag with semantic version"))
44  
45    ((id "debug-decode-failure")
46     (description "Troubleshoot decode failures")
47     (steps
48      "1. Check wire bytes against golden vectors"
49      "2. Verify framing (4-byte length prefix)"
50      "3. Check endianness (little-endian)"
51      "4. Validate schema version match"
52      "5. Check context not already freed"
53      "6. Run with debug logging enabled"))
54  
55    ((id "abi-breaking-change")
56     (description "Process for ABI-breaking changes")
57     (steps
58      "1. Document reason in ADR"
59      "2. Bump major version"
60      "3. Update all implementations"
61      "4. Update V bindings"
62      "5. Regenerate golden vectors"
63      "6. Notify downstream consumers"
64      "7. Update migration guide")))
65  
66   (emergency-procedures
67    ((id "revert-bad-release")
68     (steps
69      "1. git revert to last known good"
70      "2. Tag new patch release"
71      "3. Notify consumers"
72      "4. Post-mortem in docs/incidents/"))))