@rootzero/contracts 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -3,6 +3,90 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.15.0
+
+### Breaking Changes
+
+- Replaced the monolithic `AccessControl` base with the composable
+  `CommanderAccess`, `AdminAccess`, `NodeAccess`, `GuardianAccess`,
+  `CallerAccess`, and `TrustAccess` capabilities. `CommandBase` now requires a
+  concrete caller policy and no longer inherits outbound `NodeCalls`.
+- Split host composition into the commander-only `CommandHost`, the advanced
+  `Host`, and the optional `Admins` and `Guardians` feature bundles. Commands
+  that use trusted outbound calls must now inherit `NodeCalls` directly and
+  compose a `TrustAccess` implementation.
+- Removed the guardian account subtype. Guardians are now ordinary user
+  accounts assigned a host-local role, so previously encoded guardian account
+  IDs are not compatible.
+- Replaced the `Labeled` and `Schema` discovery events and their dedicated admin
+  commands with typed blocks in the generic `Annotation` event and the
+  `annotate` admin command.
+- Added the origin user account to `Introduction`, changing its event signature
+  to `Introduction(uint indexed host, uint peer, bytes32 origin, uint blocknum)`.
+
+### Added
+
+- Added opt-in `Label`, `Schema`, and `Action` annotation mixins together with
+  canonical `#label`, `#schema`, `#annotation`, and `#action` codec support.
+- Added semantic action annotations to deposit, payable deposit, withdrawal,
+  burn, payout, and port settlement endpoints.
+
+### Changed
+
+- Enabled the Solidity optimizer with 200 runs and pinned release testing to
+  the Cancun EVM target, the minimum target supporting the codec's `MCOPY` use.
+- Guardians can revoke node access but remain unable to grant it; admin
+  commands continue to require both the immutable commander caller and its
+  derived admin account.
+
+### Upgrade Compatibility
+
+- Existing deployments are not upgradeable and this release does not preserve
+  storage layout or guardian mapping keys for proxy upgrades. Deploy fresh host
+  contracts when adopting this version.
+
+## 1.14.0
+
+### Breaking Changes
+
+- Replaced `CommandContext` and the separate payable value lifecycle with the
+  unified `Execution` context. Endpoint and command implementations now open an
+  execution directly from calldata, use its packed decoder and writer lanes,
+  and finish through the shared `close` helpers.
+- Reworked the block codec around absolute-position `Blocks` primitives,
+  packed `Cursors`, cursor-backed `Decoders`, lazy `Buffers`, and thin
+  `Writers`. Several low-level cursor and writer APIs were renamed or removed.
+- Redefined block specs and endpoint descriptors. Specs now encode key, minimum,
+  maximum, allocation hint, stride, and optional LIST container metadata;
+  descriptors use normalized lane specs and include a transaction stride.
+- Replaced the `Cursors.sol` package entry point with `Codec.sol`, added the
+  command-authoring `Commands.sol` entry point, and reorganized exports across
+  the package barrels.
+- Endpoint selectors are now derived from endpoint names. The configured name
+  must match the implementing function name, and descriptor values are
+  represented as `uint` throughout.
+- Removed the AUTH and BOUNTY codec blocks, the obsolete `Payable`/`Values`
+  helpers, and superseded decoder, writer, schema, and descriptor overloads.
+
+### Added
+
+- Added packed output and transaction writer lanes to `Execution`, including
+  semantic output helpers, queued credit/debit transactions, budget refunds,
+  and direct transaction finalization.
+- Added detachable `Budget` values for pipeline-style consumers, shared lane
+  identifiers, spec-driven writer allocation, and optimized semantic block
+  readers, writers, and composite unpackers.
+- Added a transaction-output example, command and codec barrel import examples,
+  and expanded coverage for packed cursors, buffers, descriptors, budgets,
+  execution output, and command flows.
+
+### Changed
+
+- Standardized command, query, guard, and port implementations on the same
+  execution open/close lifecycle and renamed request terminology to input.
+- Expanded NatSpec across the new execution and codec APIs and refreshed the
+  protocol, schema, indexing, and multi-chain documentation.
+
 ## 1.13.0
 
 ### Breaking Changes
@@ -88,7 +172,7 @@ breaking API changes. Breaking changes are called out explicitly.
 - Portal no longer emits `Recovered` when retrying an undelivered witness.
 - Renamed `Cursors.exit` to `ensureAt` and renamed its position argument to
   `pos`.
-- Removed the redundant `next` return value from both `Cursors.init` overloads;
+- Removed the redundant `next` return value from both `Decoders.init` overloads;
   callers should use the returned cursor's `len` as the run boundary.
 - Changed `Cursors.list` to require the expected current cursor position as
   `pos` before entering the LIST block.
@@ -163,7 +247,7 @@ breaking API changes. Breaking changes are called out explicitly.
   as the discovery/event surface for dispatch tracking.
 - Added `ContextRecovery` schema/cursor support and context schema aliases for
   reusable nested block schemas.
-- Added `Values.drain`, `Payable.openValue`, and `Payable.closeValue` to make
+- Added `Values.drain`, `Payable.openValue`, and `Payable.end` to make
   payable command budget lifecycles explicit.
 
 ## 1.6.0
@@ -223,7 +307,7 @@ breaking API changes. Breaking changes are called out explicitly.
 
 ### Breaking Changes
 
-- Simplified `Cursors.init` to parse a single run from the start of a calldata slice. Callers that previously passed an offset must slice first or use `Cursors.open(source, i)`.
+- Simplified `Decoders.init` to parse a single run from the start of a calldata slice. Callers that previously passed an offset must slice first or use `Decoders.open(source, i)`.
 - Tightened command, query, and peer request parsing around the single-run convention used by current protocol endpoints.
 
 ### Added

package/Codec.sol

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+// Aggregator: re-exports the complete block encoding and decoding surface.
+// Import this file for low-level codec extensions and direct stream processing.
+
+import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
+import { Keys } from "./codec/Keys.sol";
+import { Sizes, Specs } from "./codec/Specs.sol";
+import { Descriptors } from "./codec/Descriptors.sol";
+import { Schemas } from "./codec/Schema.sol";
+import { Decoders } from "./codec/Decoders.sol";
+import { Cursors, Cur } from "./utils/Cursors.sol";
+import { Readers, Reader } from "./codec/Readers.sol";
+import { Blocks } from "./codec/Blocks.sol";
+import { Buffers } from "./codec/Buffers.sol";
+import { Writer, Writers } from "./codec/Writers.sol";
+
+
+
+

package/Commands.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+// Aggregator: re-exports the types and helpers needed to author commands.
+// Import this file for both standard Execution-based commands and custom decoders.
+
+import {CommandBase} from "./commands/Base.sol";
+import {Execution, Executions} from "./execution/Execution.sol";
+import {Lanes} from "./utils/Lanes.sol";
+import {Blocks} from "./codec/Blocks.sol";
+import {Sizes, Specs} from "./codec/Specs.sol";
+import {Decoders} from "./codec/Decoders.sol";
+import {Cursors, Cur} from "./utils/Cursors.sol";
+import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx} from "./core/Types.sol";

package/Core.sol

@@ -4,18 +4,20 @@ pragma solidity ^0.8.33;
 // Aggregator: re-exports the core host, runtime, access, ledger, settlement, pipeline, node-call, and validation layer.
 // Import this file to bring the full rootzero host base layer into scope.
 
-import { AccessControl } from "./core/Access.sol";
+import { Action } from "./annotations/Action.sol";
+import { Label } from "./annotations/Label.sol";
+import { Schema } from "./annotations/Schema.sol";
+import { AdminAccess, CallerAccess, CommanderAccess, GuardianAccess, NodeAccess, TrustAccess } from "./core/Access.sol";
 import { Balances, InsufficientFunds } from "./core/Balances.sol";
 import { Escrows, InsufficientEscrow } from "./core/Escrows.sol";
 import { NativeAsset, Runtime } from "./core/Runtime.sol";
-import { Host, IHostIntroduction } from "./core/Host.sol";
-import { CommandCalls, FailedCall, NodeCalls, PortCalls } from "./core/Calls.sol";
-import { EndpointBase, Lane } from "./core/Endpoint.sol";
-import { Payable } from "./core/Payable.sol";
+import { Admins, CommandHost, Guardians, Host, HostIntroduction, IHostIntroduction } from "./core/Host.sol";
+import { CommandCalls, FailedCall, NodeCalls, PortCalls, RawNodeCalls } from "./core/Calls.sol";
+import { EndpointBase } from "./core/Endpoint.sol";
 import { Pipeline } from "./core/Pipeline.sol";
+import { Budget, Budgets } from "./execution/Budget.sol";
 import { CreditAccountHook, DebitAccountHook, Settlement } from "./core/Settlement.sol";
 import { Portal } from "./core/Portal.sol";
-import { RecoverHook } from "./commands/Recover.sol";
 import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 

package/Endpoints.sol

@@ -4,11 +4,7 @@ pragma solidity ^0.8.33;
 // Aggregator: re-exports command, admin, port, guard, and query endpoint abstractions.
 // Import this file to inherit from the full rootzero callable host surface without managing individual paths.
 
-// Shared helpers
-import { Keys } from "./blocks/Keys.sol";
-import { CommandBase, CommandContext } from "./commands/Base.sol";
-import { EndpointBase, Lane } from "./core/Endpoint.sol";
-import { Payable } from "./core/Payable.sol";
+// Shared endpoint hooks
 import { CreditAccountHook, DebitAccountHook } from "./core/Settlement.sol";
 
 // Commands
@@ -27,13 +23,12 @@ import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 import { AdminBase } from "./commands/admin/Base.sol";
 import { AllowAssets, AllowAssetsHook } from "./commands/admin/AllowAssets.sol";
 import { Allowance, AllowanceHook } from "./commands/admin/Allowance.sol";
+import { Annotate } from "./commands/admin/Annotate.sol";
 import { Appoint } from "./commands/admin/Appoint.sol";
 import { Authorize } from "./commands/admin/Authorize.sol";
 import { DenyAssets, DenyAssetsHook } from "./commands/admin/DenyAssets.sol";
 import { Dismiss } from "./commands/admin/Dismiss.sol";
 import { ExecutePayable } from "./commands/admin/Execute.sol";
-import { Label } from "./commands/admin/Label.sol";
-import { PublishSchema } from "./commands/admin/Schemas.sol";
 import { Unauthorize } from "./commands/admin/Unauthorize.sol";
 
 // Port endpoints

package/Events.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8.33;
 // Aggregator: re-exports all event contracts.
 // Import this file to get access to every event emitter in one import.
 
+import { AnnotationEvent } from "./events/Annotation.sol";
 import { AssetEvent, AssetStatusEvent } from "./events/Asset.sol";
 import { Actions } from "./utils/Actions.sol";
 import { BalanceEvent } from "./events/Balance.sol";
@@ -16,12 +17,10 @@ import { RecoveredEvent } from "./events/Recovered.sol";
 import { EventEmitter } from "./events/Emitter.sol";
 import { GuardianEvent } from "./events/Guardian.sol";
 import { IntroductionEvent } from "./events/Introduction.sol";
-import { LabeledEvent } from "./events/Labeled.sol";
 import { LockedEvent } from "./events/Locked.sol";
 import { NodeEvent } from "./events/Node.sol";
 import { RootedEvent } from "./events/Rooted.sol";
 import { RouteEvent } from "./events/Route.sol";
-import { SchemaEvent } from "./events/Schema.sol";
 import { SpentEvent } from "./events/Spent.sol";
 import { UndeliveredEvent } from "./events/Undelivered.sol";
 import { UnlockedEvent } from "./events/Unlocked.sol";

package/README.md

@@ -10,7 +10,7 @@ of the protocol: the base contracts, block codecs, and helpers that rootzero
 applications compose.
 
 Two decisions shape everything below. First, all data that crosses a host
-boundary is encoded in one binary block format, so a request means the same
+boundary is encoded in one binary block format, so a input means the same
 bytes on every chain. Second, every surface operates on *runs* of blocks rather
 than single values, so batching is the default, not a feature added later. This
 guide introduces the protocol bottom-up: blocks, then identities, then hosts
@@ -27,18 +27,18 @@ npx create-rootzero@latest my-app
 npm install @rootzero/contracts
 ```
 
-A minimal host composes the base `Host` with the endpoints it needs and
-implements their policy hooks:
+A minimal commander-only host composes `CommandHost` with the endpoints it
+needs and implements their policy hooks:
 
 ```solidity
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { Host, Balances } from "@rootzero/contracts/Core.sol";
+import { CommandHost, Balances } from "@rootzero/contracts/Core.sol";
 import { Deposit } from "@rootzero/contracts/Endpoints.sol";
 
-contract ExampleHost is Host, Balances, Deposit {
-    constructor(address rootzero) Host(rootzero) {}
+contract ExampleHost is CommandHost, Balances, Deposit {
+    constructor(address commander) CommandHost(commander) {}
 
     function deposit(bytes32 account, bytes32 asset, uint amount) internal override {
         uint balance = creditTo(account, asset, amount);
@@ -47,8 +47,31 @@ contract ExampleHost is Host, Balances, Deposit {
 }
 ```
 
+`CommandHost` requires a nonzero commander and accepts command calls only from
+that address. It has no built-in admin commands, peer registry, guardians,
+inbound introduction endpoint, generic execution command, or native-token
+receive function. Use `Host` instead when the application needs those advanced
+facilities; its commands accept the commander, the host itself, and explicitly
+authorized host callers.
+
+Both host types introduce themselves during deployment when the commander is a
+contract. That commander must implement `introduce(uint,uint)` and accept the
+call, otherwise deployment reverts. EOA commanders do not receive an
+introduction call.
+
+Host contracts are designed for fresh deployment rather than proxy upgrades.
+Releases may change inheritance storage layout, immutable configuration, and
+encoded identity formats; storage compatibility across versions is not
+supported.
+
+Commands using trusted outbound `NodeCalls` also require a `TrustAccess`
+implementation. The advanced `Host` supplies one through its composed node access, while
+`CommandHost` deliberately does not. A minimal host can explicitly compose a
+custom trust policy, or a command that intentionally targets arbitrary nodes
+can inherit `RawNodeCalls` instead.
+
 Deploy it with your own address as commander and you can call its commands
-directly. A request is a run of binary blocks — here, a single `#amount` block
+directly. A input is a run of binary blocks — here, a single `#amount` block
 asking to deposit an asset (the encoders are a few lines each; see
 [`test/helpers/blocks.ts`](test/helpers/blocks.ts) for reference
 implementations):
@@ -57,8 +80,8 @@ implementations):
 const host = await ethers.deployContract("ExampleHost", [deployer.address]);
 
 const account = encodeUserAccount(user.address); // receiving account
-const request = encodeAmountBlock(asset, 100n); // what to deposit
-await host.deposit({ account, state: "0x", input: request }); // emits Balance
+const input = encodeAmountBlock(asset, 100n); // what to deposit
+await host.deposit({ account, state: "0x", input: input }); // emits Balance
 ```
 
 The rest of this guide explains the ideas this example leans on — blocks, IDs,
@@ -66,7 +89,7 @@ hosts, commands — and the surfaces built on top of them.
 
 ## Blocks
 
-Every request, response, and piece of in-flight state is a stream of typed
+Every input, response, and piece of in-flight state is a stream of typed
 blocks. A block is a four-byte key, a four-byte big-endian length, and a
 payload:
 
@@ -85,7 +108,7 @@ amount { bytes32 asset, uint amount }
 is 72 bytes on the wire: an 8-byte header followed by two big-endian 32-byte
 fields. There is no ABI encoding and no chain-specific type anywhere in the
 format — field types are chain-neutral integers, bytes, and booleans. A deposit
-request built for an EVM host is byte-for-byte the request a CosmWasm or Solana
+input built for an EVM host is byte-for-byte the input a CosmWasm or Solana
 port would parse; what differs per chain is how a host *resolves* the
 identifiers inside, never how the bytes are laid out.
 
@@ -96,11 +119,11 @@ paths give off-chain tooling presentation names without changing a single byte
 on the wire. The full schema language is specified in
 [`docs/Schema.md`](docs/Schema.md). The standard block schemas live in
 `Schemas` and their runtime keys in `Keys` (both via
-`@rootzero/contracts/Cursors.sol`).
+`@rootzero/contracts/Codec.sol`).
 
 ## Batches
 
-A request is not a single struct; it is a run of blocks. One `#amount` block
+A input is not a single struct; it is a run of blocks. One `#amount` block
 asks for one deposit, five blocks ask for five, and the code path is identical
 — every endpoint parses with a cursor and loops until the stream is exhausted.
 The descriptor lane key is the prime item: it is the block type that may repeat
@@ -117,15 +140,15 @@ Off-chain, building a batch is concatenation. Using the reference encoders from
 import { concat } from "ethers";
 import { encodeAmountBlock } from "./helpers/blocks";
 
-const request = concat([
+const input = concat([
   encodeAmountBlock(usdc, 250_000_000n),
   encodeAmountBlock(dai, 250n * 10n ** 18n),
 ]);
-// deposit(request) returns two #balance blocks in its state output and an
+// deposit(input) returns two #balance blocks in its state output and an
 // empty transaction output
 ```
 
-Everything downstream keeps this shape: commands loop over request blocks,
+Everything downstream keeps this shape: commands loop over input blocks,
 settlement loops over transactions, pipelines loop over steps. Batching is
 never a special case.
 
@@ -164,7 +187,8 @@ Structured EVM IDs use:
 where `type` packs `[uint16 representation][uint8 category][uint8 subtype]`. A
 structured ID announces what it is (an account, an asset, a node) and which
 chain it lives on, and the payload usually embeds the underlying address. User
-accounts are chain-agnostic; admin and guardian accounts are chain-local.
+accounts are chain-agnostic, while admin accounts are chain-local. Guardians
+are normal user accounts assigned a host-specific role.
 Assets are unique IDs in the same single-word form as accounts and nodes.
 Nodes are hosts, commands, ports, queries, and guards.
 
@@ -186,13 +210,18 @@ bytes32 opaque = Ids.toKeccak(preimage);  // 0x00-prefixed opaque ID
 
 A host is one contract assembled from mixins. The base `Host` brings access
 control and the admin surface (authorize, unauthorize, appoint, dismiss,
-label, executePayable) plus the guardian `revoke` action; you add the
+annotate, executePayable) plus the guardian `revoke` action; you add the
 endpoints you need and the policy hooks they require. Keeping a ledger is
 optional: the `Balances` mixin provides one, but a host can just as well
 implement commands that hold no persistent state in the host at all —
 forwarding funds elsewhere, or operating only on the state threaded through a
 pipeline.
 
+The built-in surface is also available as two independent feature bundles:
+`Admins` provides annotate, authorize, unauthorize, and executePayable;
+`Guardians` provides appoint, dismiss, and revoke. The full `Host` composes
+both, while smaller hosts can inherit either bundle separately.
+
 Trust is explicit and minimal. Each host has an immutable **commander**
 address fixed at construction, from which its **admin account** is derived.
 Other contracts become callers only when their node ID is authorized into the
@@ -242,7 +271,7 @@ function deposit(
         output.appendBalance(asset, amount);
     }
 
-    return (output.finish(), "");
+    return (end(output), "");
 }
 ```
 
@@ -252,16 +281,18 @@ lanes, derived group sizes, and flags, plus a human-readable label:
 
 ```solidity
 abstract contract MyCommand is CommandBase {
-    bytes32 private immutable descriptor;
+    uint private immutable descriptor;
 
     constructor() {
-        (, descriptor) = command("myCommand", Keys.Empty, Keys.Amount, Keys.Balance, 0, false, false);
+        (, descriptor) = command("myCommand", Specs.Empty, Specs.Amount, Specs.Balance, 0, false, false);
     }
 
     function myCommand(
-        CommandContext calldata c
+        bytes32 account,
+        bytes calldata state,
+        bytes calldata input
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        // parse c.input, loop, return the output state run and any transactions
+        // parse input, loop, return the output state run and any transactions
     }
 }
 ```
@@ -279,25 +310,25 @@ A single command is rarely the whole story. A pipeline is a run of `#step`
 blocks executed in order within one transaction:
 
 ```txt
-step { uint target, uint resources, #bytes as request }
+step { uint cmd, uint resources, #bytes as input }
 ```
 
-Each step names a target command, the resources it may spend, and its request.
+Each step names a command, the resources it may spend, and its input.
 The returned state threads into the next command and the final state must be
 empty. Returned transactions do not enter the state lane; the pipeline passes
 each decoded transaction to the shared settlement implementation before
 running the next step. This is the core of `Pipeline.pipe`:
 
 ```solidity
-while (input.i < input.len) {
-    (uint target, uint resources, bytes calldata request) = input.unpackStep();
+while (cur.more()) {
+    (uint cmd, uint resources, bytes calldata input) = cur.unpackStep();
     Reader memory transactions;
     (state, transactions.source) = dispatch(
-        target,
+        cmd,
         account,
         state,
-        request,
-        useValue(budget, resources)
+        input,
+        budget.use(resources)
     );
     while (transactions.more()) {
         (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
@@ -308,7 +339,7 @@ if (state.length != 0) revert UnexpectedState();
 ```
 
 A transfer, for instance, is a two-step pipeline: `debitAccount` turns an
-`#amount` request into `#balance` state, and `payout` consumes that state
+`#amount` input into `#balance` state, and `payout` consumes that state
 toward a recipient. Because a pipeline is just blocks, it is also the unit of
 command batching — and `resources` is a chain-specific word interpreted by the
 portal adapter (on EVM, the low 128 bits are native value in wei, drawn from a
@@ -316,13 +347,13 @@ shared budget), so the same pipeline bytes are meaningful to every port.
 
 ## Queries
 
-Queries are the read endpoints: view functions that take a block-stream request
+Queries are the read endpoints: view functions that take a block-stream input
 and return a block-stream response, with the same batch shape as commands. The
 standard `getBalances` query takes a run of positions and answers each one in
 order:
 
 ```txt
-request:  accountAsset { bytes32 account, bytes32 asset }
+input:  accountAsset { bytes32 account, bytes32 asset }
 response: accountAmount { bytes32 account, bytes32 asset, uint amount }
 ```
 
@@ -345,8 +376,8 @@ This is also the cross-portal mechanism. `relayPayable` (or `portDispatchPayable
 wraps a pipe and addresses it to a portal, commonly the destination host ID;
 a bridge adapter moves the **raw
 bytes**; the destination host parses them with the same cursor rules and runs
-the same pipeline loop. Nothing in the payload is EVM-specific — step targets
-are destination-local node IDs, and only the adapter boundary (native
+the same pipeline loop. Nothing in the payload is EVM-specific — step commands
+are destination-local command IDs, and only the adapter boundary (native
 transfers, address resolution, signatures) is chain-specific. The parity rule
 for ports is strict: every chain's implementation must parse the same input
 bytes and produce the same output bytes for every endpoint.
@@ -377,10 +408,12 @@ Import from the package entry points rather than deep paths:
 
 - `@rootzero/contracts/Core.sol` — `Host`, access control, `Balances`,
   `Settlement`, `Pipeline`, `Portal`, validator
+- `@rootzero/contracts/Commands.sol` — `CommandBase`, `Execution`, codec
+  helpers, and shared value types for authoring custom commands
 - `@rootzero/contracts/Endpoints.sol` — command, admin, port, guard, and query
   mixins and their hooks
-- `@rootzero/contracts/Cursors.sol` — calldata `Cur`/`Cursors`, memory
-  `Reader`/`Readers`, `Writers`, `Schemas`, `Keys`
+- `@rootzero/contracts/Codec.sol` — `Blocks`, calldata `Cur`/`Cursors`, memory
+  `Reader`/`Readers`, `Writers`, `Schemas`, `Keys`, and `Specs`
 - `@rootzero/contracts/Utils.sol` — `Ids`, `Nodes`, `Assets`, `Accounts`,
   layout and value helpers
 - `@rootzero/contracts/Events.sol` — protocol event contracts

package/Utils.sol

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports all utility libraries (Keys, Accounts, Actions, Assets, ECDSA, Ids, Nodes, Selectors, Layout, Utils, Value).
+// Aggregator: re-exports protocol identifier, asset, account, cryptographic,
+// layout, and general-purpose utility helpers.
 // Import this file to access the full utility surface without managing individual paths.
 
-import { Keys } from "./blocks/Keys.sol";
 import { Accounts } from "./utils/Accounts.sol";
 import { Actions } from "./utils/Actions.sol";
 import { Amounts, Assets } from "./utils/Assets.sol";
@@ -13,9 +13,7 @@ import { Ids } from "./utils/Ids.sol";
 import { Nodes } from "./utils/Nodes.sol";
 import { Selectors } from "./utils/Selectors.sol";
 import { Layout } from "./utils/Layout.sol";
-import { Schemas } from "./blocks/Schema.sol";
 import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, divisible, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
-import { Budget, Values } from "./utils/Value.sol";
 
 
 

package/annotations/Action.sol

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {AnnotationEvent} from "../events/Annotation.sol";
+import {Blocks} from "../codec/Blocks.sol";
+
+/// @title Action
+/// @notice Emits a primary semantic action annotation for an entity.
+/// @dev For a trusted emitter, the latest action replaces the earlier value.
+abstract contract Action is AnnotationEvent {
+    /// @notice Attach a primary semantic action to `entity`.
+    /// @param entity Entity receiving the action annotation.
+    /// @param value Canonical action identifier, such as a value from `Actions`.
+    function action(uint entity, uint value) internal virtual {
+        emit Annotation(entity, Blocks.action(value));
+    }
+}

package/annotations/Label.sol

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {AnnotationEvent} from "../events/Annotation.sol";
+import {Blocks} from "../codec/Blocks.sol";
+
+/// @title Label
+/// @notice Emits standard label annotation blocks for entities.
+/// @dev A label is identified by its entity and namespace. For a trusted
+/// emitter, the latest label in a namespace replaces the earlier value.
+abstract contract Label is AnnotationEvent {
+    /// @notice Attach a human-readable namespaced label to `entity`.
+    /// @param entity Entity receiving the label annotation.
+    /// @param namespace Label namespace.
+    /// @param name Human-readable name within the namespace.
+    function label(
+        uint entity,
+        bytes32 namespace,
+        string memory name
+    ) internal virtual {
+        emit Annotation(entity, Blocks.label(namespace, name));
+    }
+}

package/annotations/Schema.sol

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Blocks} from "../codec/Blocks.sol";
+import {Specs} from "../codec/Specs.sol";
+import {AnnotationEvent} from "../events/Annotation.sol";
+import {Runtime} from "../core/Runtime.sol";
+
+/// @title Schema
+/// @notice Emits standard block-schema annotations for the current host.
+/// @dev Schema annotations accumulate for distinct block keys. For a trusted
+/// emitter, the latest schema for the same block key replaces the earlier claim.
+abstract contract Schema is Runtime, AnnotationEvent {
+    /// @notice Construct and publish a context-local block specification.
+    /// @param key Context-local key value.
+    /// @param min Minimum accepted payload length.
+    /// @param max Maximum accepted payload length; zero means unbounded.
+    /// @param hint Initial per-block payload capacity.
+    /// @param body Schema DSL string describing the block payload body.
+    /// @param name Schema alias name, or zero for unnamed schemas.
+    /// @return spec The context-local block specification.
+    function schema(
+        uint32 key,
+        uint32 min,
+        uint32 max,
+        uint32 hint,
+        string memory body,
+        bytes32 name
+    ) internal returns (uint spec) {
+        spec = Specs.create(key, min, max, hint);
+        return schema(spec, body, name);
+    }
+
+    /// @notice Construct and publish an exact-size context-local block specification.
+    /// @param key Context-local key value.
+    /// @param size Exact payload length and initial per-block payload capacity.
+    /// @param body Schema DSL string describing the block payload body.
+    /// @param name Schema alias name, or zero for unnamed schemas.
+    /// @return spec The context-local block specification.
+    function schema(uint32 key, uint32 size, string memory body, bytes32 name) internal returns (uint spec) {
+        return schema(Specs.create(key, size), body, name);
+    }
+
+    /// @notice Publish an already constructed block specification for the current host.
+    /// @param spec Packed block specification.
+    /// @param body Schema DSL string describing the block payload body.
+    /// @param name Schema alias name, or zero for unnamed schemas.
+    /// @return The published block specification.
+    function schema(uint spec, string memory body, bytes32 name) internal returns (uint) {
+        emit Annotation(host, Blocks.schema(spec, body, name));
+        return spec;
+    }
+}