bolt1

commit b8731a656b99e3bc13cb719ee0f4bf85a94ab075
parent c9aef2076cf97347841c16de38657caa531c1622
Author: Jared Tobin <jared@jtobin.io>
Date:   Sun, 25 Jan 2026 11:07:21 +0400

docs: add ARCH2 architecture notes and IMPL3 plan

ARCH2 outlines module decomposition strategy for BOLT #1 stabilization.
IMPL3 details the implementation phases:
- Phase 1: Fundamental types (signed/truncated unsigned integers)
- Phase 2: Validation hardening (message size limits)
- Phase 3: Extension TLV policy verification
- Phase 4: Module split into Prim/TLV/Message/Codec

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Diffstat:
A
plans/ARCH2.md
 | 
39
+++++++++++++++++++++++++++++++++++++++
A
plans/IMPL3.md
 | 
38
++++++++++++++++++++++++++++++++++++++

2 files changed, 77 insertions(+), 0 deletions(-)
diff --git a/plans/ARCH2.md b/plans/ARCH2.md
@@ -0,0 +1,39 @@
+# ARCH2 - BOLT #1 Stabilization Architecture Notes
+
+## Goals
+
+- Complete fundamental type coverage (signed + truncated unsigned ints).
+- Tighten protocol validation (feature padding, message size limits).
+- Clarify extension TLV handling in the API surface.
+- Decompose the monolithic module into focused components while
+  preserving existing public API via re-exports.
+
+## Module Responsibilities
+
+- Lightning.Protocol.BOLT1.Prim
+  - Integer encoders/decoders, BigSize, truncated integers.
+  - Minimality and bounds checks.
+
+- Lightning.Protocol.BOLT1.TLV
+  - TLV record/stream types and parsing strategies.
+  - Extension TLV validation policy.
+
+- Lightning.Protocol.BOLT1.Message
+  - Message ADTs, feature bitset helpers, init TLVs.
+  - Invariant enforcement for message constructors.
+
+- Lightning.Protocol.BOLT1.Codec
+  - Message payload encoding/decoding.
+  - Envelope handling and message size limits.
+
+- Lightning.Protocol.BOLT1
+  - Re-export of public API for external consumers.
+
+## Validation Strategy
+
+- Reject non-minimal BigSize encodings.
+- Reject unknown even TLVs in extensions unless the caller uses a
+  raw/unsafe TLV decoder explicitly.
+- Enforce byte-aligned init feature bitsets.
+- Enforce maximum 65535 byte envelope size.
+
diff --git a/plans/IMPL3.md b/plans/IMPL3.md
@@ -0,0 +1,38 @@
+# IMPL3 - BOLT #1 Stabilization Pass
+
+## Phase 1: Fundamental Types + Tests
+
+- Implement signed integers (s16/s32/s64) and truncated unsigned
+  integers (tu16/tu32/tu64) per BOLT #1.
+- Add test vectors from Appendix D (signed integers).
+- Add negative tests for minimality/length rules.
+
+## Phase 2: Validation Hardening
+
+- Enforce `init` feature bitset padding/byte alignment.
+- Enforce message size limits (type + payload + extension <= 65535).
+- Maintain length overflow checks for all u16 length fields.
+
+## Phase 3: Extension TLV Policy
+
+- Ensure unknown even TLVs in extensions cause decode failure.
+- Expose clear decode API surface for extensions (raw vs. validated).
+- Add tests for unknown even TLV rejection and extension handling.
+
+## Phase 4: Module Split
+
+- Split `Lightning.Protocol.BOLT1` into:
+  - `Lightning.Protocol.BOLT1.Prim`
+  - `Lightning.Protocol.BOLT1.TLV`
+  - `Lightning.Protocol.BOLT1.Message`
+  - `Lightning.Protocol.BOLT1.Codec`
+- Preserve the existing public API via re-exports.
+- Update cabal + test imports accordingly.
+
+## Independent Work Chunks
+
+1) Fundamental type encoding/decoding + vectors/tests.
+2) Validation hardening for init features + message size limits.
+3) Extension TLV policy changes + test additions.
+4) Module split and cabal/test updates.
+