@rootzero/contracts 1.25.0 → 1.26.0

package/codec/Buffers.sol

@@ -1,17 +1,12 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Cursors} from "../utils/Cursors.sol";
+import {ValueOverflow} from "../utils/Errors.sol";
 
 /// @title Buffers
 /// @notice Allocation and finalization helpers for mutable memory byte buffers.
-/// @dev Packed buffer positions use `Cursors`; flag bit 0 denotes growth policy.
-/// `write` copies from memory, while `copy` copies directly from calldata.
+/// @dev `write` copies from memory, while `copy` copies directly from calldata.
 library Buffers {
-    using Cursors for uint;
-
-    uint8 internal constant Growable = 1;
-
     /// @dev A reserved memory write exceeds the physical backing buffer.
     error BufferOverflow();
     /// @dev A buffer cursor does not match its logical or physical capacity.
@@ -19,12 +14,12 @@ library Buffers {
 
     /// @notice Create a packed buffer cursor at write position zero.
     /// @param len Initial logical byte capacity.
-    /// @param count Number of logical items represented by the buffer.
-    /// @param growable Whether writes may expand the logical capacity.
+    /// @param stride Optional blocks per group represented by the buffer.
     /// @param tag Cursor identity tag.
     /// @return cur Packed buffer cursor.
-    function cursor(uint len, uint count, bool growable, uint8 tag) internal pure returns (uint cur) {
-        cur = Cursors.create(0, len, count, growable ? Growable : 0, tag);
+    function cursor(uint len, uint8 stride, uint8 tag) internal pure returns (uint cur) {
+        if (len > type(uint32).max) revert ValueOverflow();
+        cur = (len << 64) | (uint(stride) << 96) | (uint(tag) << 120);
     }
 
     /// @notice Reserve relative write space and return the updated packed buffer cursor.
@@ -43,24 +38,28 @@ library Buffers {
         uint advance,
         uint touch
     ) internal pure returns (uint updated, bytes memory dst, uint i) {
-        uint len;
-        (i, , len) = cur.decode();
+        i = uint32(cur);
+        uint len = uint32(cur >> 64);
         uint required = i + (advance > touch ? advance : touch);
         bool empty = buffer.length == 0;
         dst = buffer;
 
-        if (cur.flagged(Growable) && required > len) {
+        if (required > len) {
             len = len == 0 ? 64 : len * 2;
             while (len < required) {
                 len *= 2;
             }
-            cur = cur.resize(len);
+            if (len > type(uint32).max) revert ValueOverflow();
+            cur = (cur & ~(uint(type(uint32).max) << 64)) | (len << 64);
             if (!empty) dst = resize(dst, i, len);
         }
 
-        updated = cur.advance(advance);
+        updated = cur + advance;
 
-        if (empty) dst = alloc(len);
+        if (empty) {
+            uint padded = ((len + 31) & ~uint(31)) + 32;
+            dst = new bytes(padded);
+        }
         if (required > dst.length) revert BufferOverflow();
     }
 
@@ -81,7 +80,8 @@ library Buffers {
     /// @param capacity Requested capacity of the new buffer.
     /// @return resized Newly allocated buffer containing the written prefix.
     function resize(bytes memory buffer, uint written, uint capacity) internal pure returns (bytes memory resized) {
-        resized = alloc(capacity);
+        uint padded = ((capacity + 31) & ~uint(31)) + 32;
+        resized = new bytes(padded);
         assembly ("memory-safe") {
             mcopy(add(resized, 0x20), add(buffer, 0x20), written)
         }
@@ -171,9 +171,13 @@ library Buffers {
     /// @param buffer Backing byte buffer.
     /// @return out Empty bytes when unused, otherwise the written prefix.
     function finish(uint cur, bytes memory buffer) internal pure returns (bytes memory out) {
-        (uint i, , uint len) = cur.decode();
+        uint i = uint32(cur);
+        uint len = uint32(cur >> 64);
         if (i == 0) return new bytes(0);
         if (i > len || i > buffer.length) revert IncompleteBuffer();
-        out = trim(buffer, i);
+        assembly ("memory-safe") {
+            mstore(buffer, i)
+        }
+        out = buffer;
     }
 }

package/codec/Decoders.sol

@@ -5,6 +5,7 @@ import {AssetAmount, AccountAsset, HostAsset, AccountAmount, HostAmount, HostAcc
 import {Blocks} from "./Blocks.sol";
 import {Sizes, Specs} from "./Specs.sol";
 import {Cursors, Cur} from "../utils/Cursors.sol";
+import {UnconsumedData} from "../utils/Errors.sol";
 
 using Decoders for Cur;
 
@@ -17,40 +18,11 @@ library Decoders {
     // Cur memory adapters
     // -------------------------------------------------------------------------
 
-    /// @notice Wrap a calldata source in an ungrouped cursor.
-    /// @param source Calldata region to wrap.
-    /// @return cur Cursor spanning the complete source.
-    function wrap(bytes calldata source) internal pure returns (Cur memory cur) {
-        cur.state = Cursors.wrap(source, 0, 0);
-    }
-
-    /// @notice Wrap the calldata tail beginning at relative position `i`.
-    /// @param source Calldata region containing the tail.
-    /// @param i Relative tail position.
-    /// @return cur Cursor spanning `source[i:]`.
-    function wrap(bytes calldata source, uint i) internal pure returns (Cur memory cur) {
-        cur.state = Cursors.wrap(source[i:], 0, 0);
-    }
-
-    /// @notice Open a non-empty calldata source as an ungrouped cursor.
+    /// @notice Open a calldata source without inspecting its contents.
     /// @param source Calldata region to open.
     /// @return cur Cursor spanning the complete source.
     function open(bytes calldata source) internal pure returns (Cur memory cur) {
-        if (source.length == 0) revert Blocks.EmptyRun();
-        cur.state = Cursors.wrap(source, 0, 0);
-    }
-
-    /// @notice Open the first homogeneous batch in `source`.
-    /// @param source Calldata block stream to open.
-    /// @return cur Counted cursor spanning the first homogeneous batch.
-    function batch(bytes calldata source) internal pure returns (Cur memory cur) {
-        (uint abs, uint limit) = Cursors.bounds(source);
-        if (abs == limit) revert Blocks.EmptyRun();
-
-        bytes4 key = bytes4(source);
-        (uint count, uint end) = Blocks.run(abs, limit, key);
-        if (count == 0) revert Blocks.EmptyRun();
-        cur.state = Cursors.create(abs, end - abs, count, 0, 0);
+        cur.state = Cursors.wrap(source, 0);
     }
 
     /// @notice Return whether `cur` has unread bytes.
@@ -60,6 +32,12 @@ library Decoders {
         return cur.state.more();
     }
 
+    /// @notice Require the complete decoder source to have been consumed.
+    /// @param cur Decoder cursor to close.
+    function close(Cur memory cur) internal pure {
+        if (cur.state.more()) revert UnconsumedData();
+    }
+
     /// @notice Return the cursor's current absolute calldata position.
     /// @param cur Cursor to inspect.
     /// @return Current absolute calldata position.
@@ -164,9 +142,9 @@ library Decoders {
     /// @param cur Cursor whose calldata is returned.
     /// @return Complete cursor region.
     function raw(Cur memory cur) internal pure returns (bytes calldata) {
-        (, uint offset, uint len) = cur.state.decode();
-        if (len > msg.data.length || offset > msg.data.length - len) revert Blocks.MalformedBlocks();
-        return msg.data[offset:offset + len];
+        (uint abs, uint end) = cur.state.bounds();
+        if (end > msg.data.length) revert Blocks.MalformedBlocks();
+        return msg.data[abs:end];
     }
 
     /// @notice Return relative calldata range `[from, to)` from `cur`.
@@ -398,6 +376,26 @@ library Decoders {
         node = Blocks.unpackNode(abs);
     }
 
+    /// @notice Decode and consume one CASHOUT block.
+    /// @param cur Cursor advanced past the block.
+    /// @return amount Native-asset amount to withdraw.
+    function unpackCashout(Cur memory cur) internal pure returns (uint amount) {
+        uint abs;
+        (cur.state, abs) = cur.state.consume(Sizes.Cashout);
+        amount = Blocks.unpackCashout(abs);
+    }
+
+    /// @notice Decode and consume one BOOTSTRAP block.
+    /// @param cur Cursor advanced past the block.
+    /// @return asset Decoded asset identifier.
+    /// @return amount Decoded balance amount.
+    /// @return budget Decoded native-value budget contribution.
+    function unpackBootstrap(Cur memory cur) internal pure returns (bytes32 asset, uint amount, uint budget) {
+        uint abs;
+        (cur.state, abs) = cur.state.consume(Sizes.Bootstrap);
+        return Blocks.unpackBootstrap(abs);
+    }
+
     /// @notice Decode and consume one ASSET block.
     /// @param cur Cursor advanced past the block.
     /// @return asset Decoded asset identifier.
@@ -738,14 +736,14 @@ library Decoders {
     /// @notice Decode and consume one STEP block.
     /// @param cur Cursor advanced past the block.
     /// @return cmd Decoded command identifier.
-    /// @return resources Decoded packed resources.
+    /// @return value Decoded native value.
     /// @return input Decoded command input.
     function unpackStep(
         Cur memory cur
-    ) internal pure returns (uint cmd, uint resources, bytes calldata input) {
+    ) internal pure returns (uint cmd, uint128 value, bytes calldata input) {
         uint abs = cur.state.absolute();
         uint end;
-        (cmd, resources, input, end) = Blocks.unpackStep(abs);
+        (cmd, value, input, end) = Blocks.unpackStep(abs);
         cur.state = cur.state.seekAbs(end);
     }
 

package/codec/Descriptors.sol

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Specs} from "./Specs.sol";
+import {Blocks} from "./Blocks.sol";
+import {Buffers} from "./Buffers.sol";
+import {Sizes, Specs} from "./Specs.sol";
 import {Lanes} from "../utils/Lanes.sol";
 
 /// @title Flags
@@ -19,107 +21,108 @@ library Flags {
 /// @title Descriptors
 /// @notice Packing and lane metadata helpers for endpoint descriptors.
 library Descriptors {
-    /// @dev The requested lane is not part of an endpoint descriptor.
-    error InvalidLane();
-
     /// @notice Create a descriptor from endpoint lane specifications and flags.
     /// @dev Layout: `[state key:4][stride:1]`
     /// `[input key:4][stride:1]`
     /// `[output key:4][min:4][max:4][hint:3][stride:1]`
-    /// `[reserved:4]`
-    /// `[transactions:1]`
+    /// `[reserved:5]`
     /// `[flags:1]`. Flag bits: funded = 0, admin = 1; bits 6 and 7 are
     /// reserved for endpoint-defined custom flags.
+    /// @dev TODO: Add per-lane cardinality metadata so off-chain consumers can
+    /// distinguish exactly-one lanes from batches. Command decoding must remain
+    /// the runtime source of truth; this metadata should not restore eager scans.
     /// @param state State lane specification.
     /// @param input Direct input lane specification.
     /// @param output Output writer specification.
-    /// @param transactions Transactions produced per batch.
     /// @param flags Endpoint behavior flags.
     /// @return descriptor Packed endpoint descriptor.
     function create(
         uint state,
         uint input,
         uint output,
-        uint8 transactions,
         uint8 flags
     ) internal pure returns (uint descriptor) {
         output = Specs.normalize(output);
-        descriptor = pack(state, input, output, transactions, flags);
-    }
-
-    /// @dev Pack endpoint specs and flags into a descriptor.
-    /// @param state State specification.
-    /// @param input Input specification.
-    /// @param output Normalized direct output specification.
-    /// @param transactions Transactions produced per batch.
-    /// @param flags Endpoint behavior flags.
-    /// @return descriptor Packed endpoint descriptor.
-    function pack(
-        uint state,
-        uint input,
-        uint output,
-        uint8 transactions,
-        uint8 flags
-    ) private pure returns (uint descriptor) {
         descriptor |= uint(Specs.lane(state)) << 216;
         descriptor |= uint(Specs.lane(input)) << 176;
         descriptor |= (output >> 128) << 48;
-        descriptor |= uint(transactions) << 8;
         descriptor |= flags;
     }
 
-    /// @notice Return whether a descriptor contains `flag`.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @param flag Flag bit or bit set to test.
-    /// @return Whether any requested flag bit is present.
-    function flagged(uint descriptor, uint8 flag) internal pure returns (bool) {
-        return uint8(descriptor) & flag != 0;
+    /// @dev Wrap endpoint input with its descriptor stride and lane tag.
+    function inputCursor(bytes calldata source, uint descriptor) private pure returns (uint cur) {
+        uint tag = Lanes.Input;
+        assembly ("memory-safe") {
+            cur := or(
+                or(or(shl(32, source.offset), shl(64, source.length)), shl(96, byte(9, descriptor))),
+                shl(120, tag)
+            )
+        }
+    }
+
+    /// @dev Wrap command state with its descriptor stride and lane tag.
+    function stateCursor(bytes calldata source, uint descriptor) private pure returns (uint cur) {
+        uint tag = Lanes.State;
+        assembly ("memory-safe") {
+            cur := or(
+                or(or(shl(32, source.offset), shl(64, source.length)), shl(96, byte(4, descriptor))),
+                shl(120, tag)
+            )
+        }
+    }
+
+    /// @dev Initialize the output writer from the selected lower decoder lane.
+    /// The run count is an allocation hint only; decoding and finalization validate the source.
+    function writerCursor(uint decoders, uint descriptor) private pure returns (uint writer) {
+        uint outputStride = uint8(descriptor >> 48);
+        if (outputStride == 0) return 0;
+
+        uint decoderStride = uint8(decoders >> 96);
+        uint count;
+        if (decoderStride != 0) {
+            uint abs = uint32(decoders >> 32);
+            uint end = abs + uint32(decoders >> 64);
+            uint laneShift = uint8(decoders >> 120) == Lanes.Input ? 176 : 216;
+            count = Blocks.runCount(
+                abs,
+                end,
+                bytes4(uint32(descriptor >> (laneShift + 8)))
+            ) / decoderStride * outputStride;
+        }
+
+        uint capacity = count * (Sizes.Header + uint24(descriptor >> 56));
+        writer = Buffers.cursor(capacity, uint8(outputStride), 0);
     }
 
-    /// @notice Return the effective per-batch stride for `lane`.
-    /// @dev Descriptor creation resolves implicit spec strides, so every lane
-    /// stores its effective value directly.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @param lane Lane identifier from `Lanes`.
-    /// @return Effective blocks per batch for the lane.
-    function stride(uint descriptor, uint8 lane) internal pure returns (uint8) {
-        if (lane == Lanes.State) return uint8(descriptor >> 216);
-        if (lane == Lanes.Input) return uint8(descriptor >> 176);
-        if (lane == Lanes.Output) return uint8(descriptor >> 48);
-        if (lane == Lanes.Transactions) return uint8(descriptor >> 8);
-        revert InvalidLane();
+    /// @notice Open descriptor-backed input and output cursors.
+    function openInput(
+        uint descriptor,
+        bytes calldata input
+    ) internal pure returns (uint decoders, uint writer) {
+        decoders = inputCursor(input, descriptor);
+        writer = writerCursor(decoders, descriptor);
     }
 
-    /// @notice Return the effective block key for `lane`.
-    /// @dev Transaction blocks have a fixed protocol key that is not stored in
-    /// the descriptor.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @param lane Lane identifier from `Lanes`.
-    /// @return Effective block key for the lane.
-    function key(uint descriptor, uint8 lane) internal pure returns (bytes4) {
-        if (lane == Lanes.State) return bytes4(uint32(descriptor >> 224));
-        if (lane == Lanes.Input) return bytes4(uint32(descriptor >> 184));
-        if (lane == Lanes.Output) return bytes4(uint32(descriptor >> 144));
-        if (lane == Lanes.Transactions) return Specs.key(Specs.Transaction);
-        revert InvalidLane();
+    /// @notice Open descriptor-backed state and output cursors.
+    function openState(
+        uint descriptor,
+        bytes calldata state
+    ) internal pure returns (uint decoders, uint writer) {
+        decoders = stateCursor(state, descriptor);
+        writer = writerCursor(decoders, descriptor);
     }
 
-    /// @notice Return the buffer configuration for descriptor writer `lane`.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @param lane Output or transaction writer lane.
-    /// @param groups Number of execution batches to allocate for.
-    /// @return capacity Initial logical byte capacity.
-    /// @return growable Whether the writer may grow beyond that capacity.
-    function allocation(uint descriptor, uint8 lane, uint groups) internal pure returns (uint capacity, bool growable) {
-        if (lane == Lanes.Output) {
-            uint spec = uint(uint128(descriptor >> 48)) << 128;
-            return Specs.allocation(spec, groups);
+    /// @notice Open paired descriptor-backed state, input, and output cursors.
+    /// @dev Input remains low when present; otherwise state becomes the active lower lane.
+    function open(
+        uint descriptor,
+        bytes calldata state,
+        bytes calldata input
+    ) internal pure returns (uint decoders, uint writer) {
+        decoders = inputCursor(input, descriptor) | (stateCursor(state, descriptor) << 128);
+        if (uint8(decoders >> 96) == 0) {
+            decoders = (decoders << 128) | (decoders >> 128);
         }
-        if (lane == Lanes.Transactions) {
-            uint count = groups * stride(descriptor, lane);
-            return Specs.allocation(Specs.Transaction, count);
-        }
-
-        revert InvalidLane();
+        writer = writerCursor(decoders, descriptor);
     }
 }

package/codec/Keys.sol

@@ -11,6 +11,10 @@ library Keys {
     bytes4 constant Empty = bytes4(0);
     /// @dev Input amount - (bytes32 asset, uint amount)
     bytes4 constant Amount = bytes4(keccak256("#amount"));
+    /// @dev Native-asset cashout request - (uint amount)
+    bytes4 constant Cashout = bytes4(keccak256("#cashout"));
+    /// @dev Pipeline bootstrap request - (bytes32 asset, uint amount, uint budget)
+    bytes4 constant Bootstrap = bytes4(keccak256("#bootstrap"));
     /// @dev Ledger balance - (bytes32 asset, uint amount)
     bytes4 constant Balance = bytes4(keccak256("#balance"));
     /// @dev Liability-only debt state - (bytes32 liability, uint debt)
@@ -35,7 +39,7 @@ library Keys {
     bytes4 constant Account = bytes4(keccak256("#account"));
     /// @dev Transfer record passed through the pipeline - (bytes32 from, bytes32 to, bytes32 asset, uint amount)
     bytes4 constant Transaction = bytes4(keccak256("#transaction"));
-    /// @dev Sub-command invocation - (uint cmd, uint resources, #bytes as input)
+    /// @dev Sub-command invocation - (uint cmd, uint128 value, #bytes as input)
     bytes4 constant Step = bytes4(keccak256("#step"));
     /// @dev Portal relay input - (uint portal, uint resources, #bytes as input)
     bytes4 constant Relay = bytes4(keccak256("#relay"));

package/codec/Schema.sol

@@ -32,6 +32,8 @@ pragma solidity ^0.8.33;
 // - `resources` fields are chain-specific resource words. A portal adapter
 //   interprets them for the destination runtime. EVM resources use the low
 //   128 bits as native value.
+// - STEP encodes native `value` directly as uint128; it does not carry a
+//   chain-specific resources word
 // - dotted field names and aliases, e.g. `dst.portal` or `#bytes as dst.payload`,
 //   are offchain projection metadata only and do not change runtime encoding
 // - `at N` assigns an offchain presentation position to one sibling; explicit
@@ -84,6 +86,7 @@ library Schemas {
     string constant Account = "bytes32 account";
     string constant Asset = "bytes32 asset";
     string constant Status = "uint code";
+    string constant Cashout = "uint amount";
 
     // Two-word payloads
 
@@ -95,6 +98,7 @@ library Schemas {
 
     // Three-word payloads
 
+    string constant Bootstrap = "bytes32 asset, uint amount, uint budget";
     string constant Allocation = "uint host, bytes32 asset, uint amount";
     string constant Allowance = "uint host, bytes32 asset, uint amount";
     string constant Custody = "uint host, bytes32 asset, uint amount";
@@ -110,8 +114,8 @@ library Schemas {
 
     // Composite payloads
 
+    string constant Step = "uint cmd, uint128 value, #bytes as input";
     string constant Call = "uint target, uint resources, #bytes as payload";
-    string constant Step = "uint cmd, uint resources, #bytes as input";
     string constant Relay = "uint portal, uint resources, #bytes as input";
     string constant Dispatch = "uint portal, uint resources, #bytes as payload";
     string constant Context = "bytes32 account, #bytes as state, #bytes as input";

package/codec/Specs.sol

@@ -21,8 +21,14 @@ library Sizes {
     uint constant B128 = Header + 4 * Word;
     /// @dev 8 header + 160 payload = 168 bytes total.
     uint constant B160 = Header + 5 * Word;
+    /// @dev Minimum STEP size: 8 header + 32 command + 16 value + 8 nested BYTES header.
+    uint constant Step = 2 * Header + Word + 16;
     /// @dev STATUS block: 8 header + 32 status code = 40 bytes
     uint constant Status = B32;
+    /// @dev CASHOUT block: 8 header + 32 native-asset amount = 40 bytes
+    uint constant Cashout = B32;
+    /// @dev BOOTSTRAP block: 8 header + 32 asset + 32 amount + 32 budget = 104 bytes
+    uint constant Bootstrap = B96;
     /// @dev AMOUNT block: 8 header + 32 asset + 32 amount = 72 bytes
     uint constant Amount = B64;
     /// @dev BALANCE block: 8 header + 32 asset + 32 amount = 72 bytes
@@ -44,7 +50,7 @@ library Sizes {
 /// `[key:4][min:4][max:4][hint:3][stride:1][reserved:16]`.
 /// The upper eight bytes of a fixed-layout spec are its encoded block header,
 /// allowing the entire spec word to be written directly as that header.
-/// A maximum of zero means unbounded and requires a growable writer.
+/// A maximum of zero means the payload size is unbounded.
 library Specs {
     /// @dev A payload is incompatible with its block specification.
     error InvalidSpec();
@@ -58,11 +64,14 @@ library Specs {
     uint private constant Exact128 = 128 * SizeFields;
     uint private constant UnboundedHint128 = uint(128) << 136;
     uint private constant UnboundedMin40Hint256 = (uint(40) << 192) | (uint(256) << 136);
+    uint private constant UnboundedMin56Hint256 = (uint(56) << 192) | (uint(256) << 136);
     uint private constant UnboundedMin72Hint256 = (uint(72) << 192) | (uint(256) << 136);
     uint private constant UnboundedMin48Hint512 = (uint(48) << 192) | (uint(512) << 136);
     uint private constant UnboundedMin104Hint256 = (uint(104) << 192) | (uint(256) << 136);
 
     uint constant Empty = uint(bytes32(Keys.Empty));
+    uint constant Cashout = uint(bytes32(Keys.Cashout)) | Exact32;
+    uint constant Bootstrap = uint(bytes32(Keys.Bootstrap)) | Exact96;
     uint constant Amount = uint(bytes32(Keys.Amount)) | Exact64;
     uint constant Balance = uint(bytes32(Keys.Balance)) | Exact64;
     uint constant Debt = uint(bytes32(Keys.Debt)) | Exact64;
@@ -76,7 +85,7 @@ library Specs {
     uint constant String = uint(bytes32(Keys.String)) | UnboundedHint128;
     uint constant Account = uint(bytes32(Keys.Account)) | Exact32;
     uint constant Transaction = uint(bytes32(Keys.Transaction)) | Exact128;
-    uint constant Step = uint(bytes32(Keys.Step)) | UnboundedMin72Hint256;
+    uint constant Step = uint(bytes32(Keys.Step)) | UnboundedMin56Hint256;
     uint constant Relay = uint(bytes32(Keys.Relay)) | UnboundedMin72Hint256;
     uint constant Context = uint(bytes32(Keys.Context)) | UnboundedMin48Hint512;
     uint constant Recover = uint(bytes32(Keys.Recover)) | UnboundedMin104Hint256;
@@ -205,18 +214,19 @@ library Specs {
     /// @param groups Number of groups.
     /// @return Number of blocks across all groups.
     function count(uint spec, uint groups) internal pure returns (uint) {
-        return groups * stride(normalize(spec));
+        uint8 n = uint8(spec >> 128);
+        if (n == 0 && uint32(spec >> 224) != 0) n = 1;
+        return groups * n;
     }
 
-    /// @notice Return the buffer configuration for `groups` of `spec`.
-    /// @dev Dynamic specs use their allocation hint and a maximum of zero means growable.
+    /// @notice Return the initial buffer capacity for `groups` of `spec`.
     /// @param spec Packed block specification.
     /// @param groups Number of groups to allocate.
     /// @return capacity Initial encoded byte capacity.
-    /// @return growable Whether the buffer may grow beyond its initial capacity.
-    function allocation(uint spec, uint groups) internal pure returns (uint capacity, bool growable) {
-        capacity = count(spec, groups) * (Sizes.Header + uint24(spec >> 136));
-        growable = uint32(spec >> 160) == 0;
+    function allocation(uint spec, uint groups) internal pure returns (uint capacity) {
+        uint8 n = uint8(spec >> 128);
+        if (n == 0 && uint32(spec >> 224) != 0) n = 1;
+        capacity = groups * n * (Sizes.Header + uint24(spec >> 136));
     }
 
     /// @notice Return `spec` grouped with an explicit stride.

package/codec/Writers.sol

@@ -8,8 +8,7 @@ import {Sizes, Specs} from "./Specs.sol";
 
 /// @notice Sequential block stream writer backed by a pre-allocated memory buffer.
 struct Writer {
-    /// @dev Packed cursor metadata. `len` is logical capacity and flag bit 0
-    /// indicates whether the backing buffer may grow.
+    /// @dev Packed cursor metadata. `len` is the current logical capacity.
     uint cur;
     /// @dev Destination buffer. Physical capacity may be padded up to a full 32-byte word;
     /// final length is set to the packed write position by `finish`.
@@ -30,22 +29,18 @@ library Writers {
 
     /// @notice Initialize writer metadata without allocating a backing buffer.
     /// @param len Initial logical byte capacity of the writer.
-    /// @param growable Whether append helpers may expand the capacity.
     /// @return writer Unallocated writer positioned at index 0.
-    function init(uint len, bool growable) internal pure returns (Writer memory writer) {
-        writer.cur = Buffers.cursor(len, 0, growable, 0);
+    function init(uint len) internal pure returns (Writer memory writer) {
+        writer.cur = Buffers.cursor(len, 0, 0);
     }
 
     /// @notice Initialize writer metadata for `groups` of blocks described by `spec`.
     /// @param spec Packed block key, payload bounds, allocation hint, and flags.
     /// @param groups Number of descriptor groups the writer is expected to encode.
-    /// @return writer Unallocated writer with capacity derived from the specification,
-    /// or an inert empty writer when its capacity is zero.
+    /// @return writer Unallocated writer with initial capacity derived from the specification.
     function init(uint spec, uint groups) internal pure returns (Writer memory writer) {
-        (uint capacity, bool growable) = Specs.allocation(spec, groups);
-        if (capacity == 0) return writer;
-
-        writer.cur = Buffers.cursor(capacity, Specs.count(spec, groups), growable, 0);
+        uint capacity = Specs.allocation(spec, groups);
+        writer.cur = Buffers.cursor(capacity, Specs.stride(Specs.normalize(spec)), 0);
     }
 
     // -------------------------------------------------------------------------
@@ -66,7 +61,7 @@ library Writers {
     /// @param size Number of bytes to reserve and touch.
     /// @return i Relative offset reserved for the write.
     function reserve(Writer memory writer, uint size) private pure returns (uint i) {
-        return reserve(writer, size, size);
+        (writer.cur, writer.dst, i) = Buffers.reserve(writer.cur, writer.dst, size, size);
     }
 
     // -------------------------------------------------------------------------
@@ -417,12 +412,12 @@ library Writers {
     /// @notice Append a STEP block.
     /// @param writer Destination writer.
     /// @param cmd Command identifier to encode.
-    /// @param resources Packed resources to encode.
+    /// @param value Native value to encode.
     /// @param input Command input to encode.
-    function appendStep(Writer memory writer, uint cmd, uint resources, bytes memory input) internal pure {
-        uint size = Sizes.B64 + Sizes.Header + input.length;
+    function appendStep(Writer memory writer, uint cmd, uint128 value, bytes memory input) internal pure {
+        uint size = Sizes.Step + input.length;
         uint i = reserve(writer, size);
-        Blocks.writeStep(writer.dst, i, cmd, resources, input);
+        Blocks.writeStep(writer.dst, i, cmd, value, input);
     }
 
     /// @notice Append a CALL block.
@@ -566,10 +561,10 @@ library Writers {
     }
 
     /// @notice Append a STEP block by copying its nested input from calldata.
-    function copyStep(Writer memory writer, uint cmd, uint resources, bytes calldata input) internal pure {
-        uint size = Sizes.B64 + Sizes.Header + input.length;
+    function copyStep(Writer memory writer, uint cmd, uint128 value, bytes calldata input) internal pure {
+        uint size = Sizes.Step + input.length;
         uint i = reserve(writer, size);
-        Blocks.copyStep(writer.dst, i, cmd, resources, input);
+        Blocks.copyStep(writer.dst, i, cmd, value, input);
     }
 
     /// @notice Append a CALL block by copying its nested payload from calldata.