@rootzero/contracts 1.13.0 → 1.15.0

package/core/Endpoint.sol

@@ -1,162 +1,65 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Cursors, Cur} from "../Cursors.sol";
-import {Keys} from "../blocks/Keys.sol";
+import {Execution, Executions} from "../execution/Execution.sol";
 import {EndpointEvent} from "../events/Endpoint.sol";
-import {LabeledEvent} from "../events/Labeled.sol";
-import {SchemaEvent} from "../events/Schema.sol";
-import {Runtime} from "./Runtime.sol";
-
-/// @title Lane
-/// @notice Bit offsets for endpoint descriptor lanes.
-library Lane {
-    /// @dev Descriptor shift for the state lane.
-    uint internal constant State = 184;
-    /// @dev Descriptor shift for the input lane.
-    uint internal constant Input = 112;
-    /// @dev Descriptor shift for the output lane.
-    uint internal constant Output = 40;
-}
+import {Label} from "../annotations/Label.sol";
+import {Schema} from "../annotations/Schema.sol";
+import {Descriptors} from "../codec/Descriptors.sol";
 
 /// @title EndpointBase
 /// @notice Shared endpoint metadata helpers.
-abstract contract EndpointBase is Runtime, EndpointEvent, LabeledEvent, SchemaEvent {
-    /// @dev Pack endpoint lanes and flags into a descriptor.
-    /// A non-empty lane with group 0 defaults to group 1; a zero lane is absent.
-    /// Layout: `[state:8][group:1][input:8][group:1][output:8][group:1]`
-    /// `[flags:1][reserved:4]`. Flag bits: funded = 0, admin = 1.
-    /// @param state Packed state lane plus optional group byte.
-    /// @param input Packed input lane plus optional group byte.
-    /// @param output Packed output lane plus optional group byte.
-    /// @param funded Whether the endpoint accepts nonzero native value.
-    /// @param admin Whether the endpoint is restricted to the admin account.
-    /// @return value Packed endpoint descriptor as an integer.
-    function pack(
-        bytes9 state,
-        bytes9 input,
-        bytes9 output,
-        bool funded,
-        bool admin
-    ) private pure returns (uint value) {
-        value |= uint(uint72(state)) << Lane.State;
-        value |= uint(uint72(input)) << Lane.Input;
-        value |= uint(uint72(output)) << Lane.Output;
-        value |= uint(funded ? 1 : 0) << 32;
-        value |= uint(admin ? 1 : 0) << 33;
-    }
-
-    /// @dev Return a lane's effective group size, defaulting non-empty lanes to one.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @param shift Bit offset of the lane to inspect.
-    /// @return size Effective group size, or zero when the lane is absent.
-    function laneGroup(bytes32 descriptor, uint shift) private pure returns (uint8 size) {
-        uint72 lane = uint72(uint(descriptor) >> shift);
-        if (lane == 0) return 0;
-
-        size = uint8(lane);
-        if (size == 0) size = 1;
-    }
-
-    /// @dev Open a descriptor lane and return its effective group and output counts.
-    /// An absent lane inherits `expected`; a present lane must match it when nonzero.
-    /// @param source Block stream to open for the requested lane.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @param shift Bit offset of the lane to open.
-    /// @param expected Required group count, or zero to accept the lane's count.
-    /// @return cur Cursor scoped to the lane's first block run.
-    /// @return groups Number of lane groups in `cur`, or `expected` for an absent lane.
-    /// @return outputs Number of output blocks implied by `groups` and the descriptor output lane.
-    function openLane(
-        bytes calldata source,
-        bytes32 descriptor,
-        uint shift,
-        uint expected
-    ) internal pure returns (Cur memory cur, uint groups, uint outputs) {
-        (cur, groups) = Cursors.init(source, laneGroup(descriptor, shift));
-        if (groups == 0) groups = expected;
-        else if (expected != 0 && groups != expected) revert Cursors.BadRatio();
-        outputs = groups * laneGroup(descriptor, Lane.Output);
+abstract contract EndpointBase is EndpointEvent, Label, Schema {
+    /// @notice Create and publish endpoint metadata with a default label.
+    /// @param id Endpoint node ID.
+    /// @param name Default human-readable endpoint label.
+    /// @param state State block specification.
+    /// @param input Input block specification.
+    /// @param output Output block specification.
+    /// @param transactions Number of transaction blocks produced per batch, or zero for none.
+    /// @param flags Packed endpoint behavior flags.
+    /// @return descriptor Packed endpoint lane metadata and flags.
+    function endpoint(
+        uint id,
+        string memory name,
+        uint state,
+        uint input,
+        uint output,
+        uint8 transactions,
+        uint8 flags
+    ) internal returns (uint descriptor) {
+        descriptor = Descriptors.create(state, input, output, transactions, flags);
+        return endpoint(id, name, descriptor);
     }
 
-    /// @notice Open an endpoint state stream and return the expected output block count.
-    /// @param source State block stream to open.
-    /// @param descriptor Packed endpoint descriptor.
-    /// @return state Cursor scoped to the state lane's first block run.
-    /// @return outputs Number of output blocks implied by the state group count.
-    function openState(
-        bytes calldata source,
-        bytes32 descriptor
-    ) internal pure returns (Cur memory state, uint outputs) {
-        (state, , outputs) = openLane(source, descriptor, Lane.State, 0);
+    /// @notice Publish already constructed endpoint metadata with a default label.
+    /// @param id Endpoint node ID.
+    /// @param name Default human-readable endpoint label.
+    /// @param descriptor Packed endpoint lane metadata and flags.
+    /// @return The published endpoint descriptor.
+    function endpoint(uint id, string memory name, uint descriptor) internal returns (uint) {
+        emit Endpoint(host, id, descriptor);
+        label(id, bytes32(0), name);
+        return descriptor;
     }
 
-    /// @notice Open an endpoint input stream and return the expected output block count.
+    /// @notice Open an endpoint input stream with an expected batch count.
     /// @param source Input block stream to open.
     /// @param descriptor Packed endpoint descriptor.
-    /// @return input Cursor scoped to the input lane's first block run.
-    /// @return outputs Number of output blocks implied by the input group count.
+    /// @param batches Required batch count, or zero to accept the input count.
+    /// @return exec Execution with its output buffer metadata initialized for the input batch count.
     function openInput(
         bytes calldata source,
-        bytes32 descriptor
-    ) internal pure returns (Cur memory input, uint outputs) {
-        (input, , outputs) = openLane(source, descriptor, Lane.Input, 0);
-    }
-
-    /// @notice Return an 8-byte lane value for a generic LIST containing `item`.
-    /// @param item Block key expected inside each LIST payload.
-    /// @return Packed lane key `[Keys.List][item]`.
-    function many(bytes4 item) internal pure returns (bytes8) {
-        return bytes8(bytes.concat(Keys.List, item));
+        uint descriptor,
+        uint batches
+    ) internal view returns (Execution memory exec) {
+        return Executions.openInput(source, descriptor, batches);
     }
 
-    /// @notice Append an explicit group size to an 8-byte lane value.
-    /// @param value Packed lane key `[key][item]`.
-    /// @param size Explicit per-operation group size for the lane.
-    /// @return Packed lane key plus group byte.
-    function group(bytes8 value, uint8 size) internal pure returns (bytes9) {
-        return bytes9(bytes.concat(value, bytes1(size)));
-    }
-
-    /// @notice Publish a context-local block schema and return its key.
-    /// @param key Context-local key value.
-    /// @param body Schema DSL string describing the block payload body.
-    /// @return The context-local block key.
-    function schema(uint32 key, string memory body) internal returns (bytes4) {
-        return schema(key, body, bytes32(0));
-    }
-
-    /// @notice Publish a named context-local block schema and return its key.
-    /// @param key Context-local key value.
-    /// @param body Schema DSL string describing the block payload body.
-    /// @param name Schema alias name, or zero for unnamed schemas.
-    /// @return The context-local block key.
-    function schema(uint32 key, string memory body, bytes32 name) internal returns (bytes4) {
-        bytes4 k = bytes4(key);
-        emit Schema(host, k, body, name);
-        return k;
-    }
-
-    /// @notice Create and publish endpoint metadata with a default label.
-    /// @param id Endpoint node ID.
-    /// @param name Default human-readable endpoint label.
-    /// @param state Packed state lane plus optional group byte.
-    /// @param input Packed input lane plus optional group byte.
-    /// @param output Packed output lane plus optional group byte.
-    /// @param funded Whether the endpoint accepts nonzero native value.
-    /// @param admin Whether the endpoint is restricted to the admin account.
-    /// @return descriptor Packed endpoint lane metadata and flags.
-    function endpoint(
-        uint id,
-        string memory name,
-        bytes9 state,
-        bytes9 input,
-        bytes9 output,
-        bool funded,
-        bool admin
-    ) internal returns (bytes32 descriptor) {
-        descriptor = bytes32(pack(state, input, output, funded, admin));
-        emit Endpoint(host, id, descriptor);
-        emit Labeled(id, bytes32(0), name);
+    /// @notice Finalize an execution output and return its encoded block stream.
+    /// @param exec Completed endpoint execution.
+    /// @return Encoded output block stream.
+    function close(Execution memory exec) internal pure returns (bytes memory) {
+        return Executions.finish(exec);
     }
 }

package/core/Host.sol

@@ -1,15 +1,17 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {AccessControl} from "./Access.sol";
+import {AccessDenied, CallerAccess, CommanderAccess} from "./Access.sol";
+import {Runtime} from "./Runtime.sol";
+import {Annotate} from "../commands/admin/Annotate.sol";
 import {Appoint} from "../commands/admin/Appoint.sol";
 import {Authorize} from "../commands/admin/Authorize.sol";
 import {Dismiss} from "../commands/admin/Dismiss.sol";
 import {Unauthorize} from "../commands/admin/Unauthorize.sol";
 import {ExecutePayable} from "../commands/admin/Execute.sol";
-import {Label} from "../commands/admin/Label.sol";
 import {Revoke} from "../guards/Revoke.sol";
 import {IntroductionEvent} from "../events/Introduction.sol";
+import {Accounts} from "../utils/Accounts.sol";
 import {Nodes} from "../utils/Nodes.sol";
 
 /// @title IHostIntroduction
@@ -21,6 +23,55 @@ interface IHostIntroduction {
     function introduce(uint peer, uint blocknum) external;
 }
 
+/// @title HostIntroduction
+/// @notice Shared deployment-time introduction behavior for rootzero hosts.
+/// Calls a deployed commander during construction without adding an inbound
+/// introduction endpoint to the inheriting host.
+abstract contract HostIntroduction is Runtime {
+    /// @param cmdr Commander address to introduce this host to when it is a deployed contract.
+    /// @dev Deployment reverts if a contract commander does not accept `introduce(uint,uint)`.
+    constructor(address cmdr) {
+        if (cmdr == address(0) || cmdr == address(this) || cmdr.code.length == 0) return;
+        introduceTo(Nodes.toHost(cmdr));
+    }
+
+    /// @notice Introduce this host to the contract address embedded in a local EVM node ID.
+    /// @dev Accepts host and endpoint IDs such as commands, ports, queries, and guards.
+    /// Reverts when `node` is not local or embeds the zero address.
+    /// @param node Local EVM node ID whose underlying contract receives the introduction.
+    function introduceTo(uint node) internal {
+        IHostIntroduction(Nodes.addr(node)).introduce(host, block.number);
+    }
+}
+
+/// @title CommandHost
+/// @notice Minimal host base for commander-only command execution.
+/// Does not include admin commands, peer authorization, guardians, inbound
+/// introductions, generic execution, or a native-token receive function.
+/// Commands using trusted `NodeCalls` must separately compose a `TrustAccess` policy.
+abstract contract CommandHost is CommanderAccess, CallerAccess, HostIntroduction {
+    /// @dev Thrown when a commander-only host is deployed without an external commander.
+    error InvalidCommander();
+
+    /// @param cmdr Nonzero address allowed to invoke hosted commands.
+    constructor(address cmdr) CommanderAccess(cmdr) HostIntroduction(cmdr) {
+        if (cmdr == address(0)) revert InvalidCommander();
+    }
+
+    function enforceCaller(address caller) internal view virtual override returns (address) {
+        return enforceCommander(caller);
+    }
+
+}
+
+/// @title Admins
+/// @notice Optional bundle of the default host administration commands.
+abstract contract Admins is Annotate, ExecutePayable, Authorize, Unauthorize {}
+
+/// @title Guardians
+/// @notice Optional bundle for guardian management and the default revoke guard.
+abstract contract Guardians is Appoint, Dismiss, Revoke {}
+
 /// @title Host
 /// @notice Abstract base contract for rootzero host implementations.
 /// Inherits admin command support (authorize, unauthorize, label, executePayable),
@@ -28,30 +79,21 @@ interface IHostIntroduction {
 /// optionally introduces itself to a commander host at deployment.
 /// Accepts native ETH payments via the `receive` function.
 abstract contract Host is
-    Authorize,
-    Unauthorize,
-    Revoke,
-    Appoint,
-    Dismiss,
-    Label,
-    ExecutePayable,
+    Admins,
+    Guardians,
+    HostIntroduction,
     IntroductionEvent,
     IHostIntroduction
 {
-    /// @param cmdr Commander address; passed to `AccessControl`.
+    /// @param cmdr Commander address; used by the composed access capabilities.
     ///        If `cmdr` is a deployed contract, the host calls `introduce`
     ///        on it during construction.
-    constructor(address cmdr) AccessControl(cmdr) {
-        if (cmdr == address(0) || cmdr == address(this) || cmdr.code.length == 0) return;
-        introduceTo(Nodes.toHost(cmdr));
-    }
+    constructor(address cmdr) CommanderAccess(cmdr) HostIntroduction(cmdr) {}
 
-    /// @notice Introduce this host to the contract address embedded in a local EVM node ID.
-    /// @dev Accepts host and endpoint IDs such as commands, ports, queries, and guards.
-    /// Reverts when `node` is not local or embeds the zero address.
-    /// @param node Local EVM node ID whose underlying contract receives the introduction.
-    function introduceTo(uint node) internal {
-        IHostIntroduction(Nodes.addr(node)).introduce(host, block.number);
+    /// @notice Assert that `caller` may invoke commands on a peer-aware host.
+    function enforceCaller(address caller) internal view virtual override returns (address) {
+        if (caller == address(0) || !isTrustedCaller(caller)) revert AccessDenied();
+        return caller;
     }
 
     /// @notice Record a host introduction claim.
@@ -59,7 +101,7 @@ abstract contract Host is
     /// @param peer Host node ID being introduced.
     /// @param blocknum Block number at which the host was deployed.
     function introduce(uint peer, uint blocknum) external {
-        emit Introduction(host, Nodes.matchHost(peer, msg.sender), blocknum);
+        emit Introduction(host, Nodes.matchHost(peer, msg.sender), Accounts.toUser(tx.origin), blocknum);
     }
 
     /// @notice Accept native ETH transfers (e.g. from command value flows).

package/core/Pipeline.sol

@@ -1,17 +1,17 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {Cursors, Cur, Readers, Reader} from "../Cursors.sol";
-import {Payable} from "./Payable.sol";
+import {Decoders, Cur, Readers, Reader} from "../Codec.sol";
 import {Settlement} from "./Settlement.sol";
-import {Budget} from "../utils/Value.sol";
+import {Budget, Budgets} from "../execution/Budget.sol";
 
-using Cursors for Cur;
+using Decoders for Cur;
 using Readers for Reader;
+using Budgets for Budget;
 
 /// @title Pipeline
 /// @notice Core pipeline functionality shared by higher-level surfaces.
-abstract contract Pipeline is Payable, Settlement {
+abstract contract Pipeline is Settlement {
     /// @dev Thrown when the pipeline finishes with non-empty threaded state.
     error UnexpectedState();
 
@@ -19,20 +19,20 @@ abstract contract Pipeline is Payable, Settlement {
     /// Called once per STEP block. The returned state becomes the state passed to
     /// the next step, and the final returned state must be empty. Returned
     /// transactions are decoded and passed individually to `settle` before the next step runs.
-    /// @param target Node ID to invoke or handle.
+    /// @param cmd Command node ID to invoke or handle.
     /// @param account Account identifier for the piped context.
     /// @param state Current threaded state block stream.
-    /// @param request Step request block stream.
+    /// @param input Step input block stream.
     /// @param value Native EVM value assigned to this step.
-    /// @return nextState Updated state block stream for the next step.
+    /// @return output Updated state block stream for the next step.
     /// @return transactions Transaction block stream produced by the command.
     function dispatch(
-        uint target,
+        uint cmd,
         bytes32 account,
         bytes memory state,
-        bytes calldata request,
+        bytes calldata input,
         uint128 value
-    ) internal virtual returns (bytes memory nextState, bytes memory transactions);
+    ) internal virtual returns (bytes memory output, bytes memory transactions);
 
     /// @notice Execute a STEP block stream through the pipeline.
     /// @dev Reverts with `UnexpectedState` if the final threaded state is non-empty.
@@ -42,12 +42,13 @@ abstract contract Pipeline is Payable, Settlement {
     /// @param steps STEP block stream to execute.
     /// @param budget Mutable native-value budget shared across all steps.
     function pipe(bytes32 account, bytes memory state, bytes calldata steps, Budget memory budget) internal {
-        (Cur memory input, ) = Cursors.init(steps, 1);
+        Cur memory cur = Decoders.open(steps, 1);
 
-        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 txs;
-            (state, txs.source) = dispatch(target, account, state, request, useValue(budget, resources));
+            (state, txs.source) = dispatch(cmd, account, state, input, budget.use(resources));
+
             while (txs.more()) {
                 (bytes32 from, bytes32 to, bytes32 asset, uint amount) = txs.unpackTransaction();
                 settle(from, to, asset, amount);

package/core/Types.sol

@@ -17,7 +17,7 @@ struct AccountAsset {
     bytes32 asset;
 }
 
-/// @notice Account-scoped amount shape for requests, responses, and reporting.
+/// @notice Account-scoped amount shape for inputs, responses, and reporting.
 struct AccountAmount {
     /// @dev Account identifier.
     bytes32 account;

package/docs/Schema.md

@@ -1,6 +1,6 @@
 # Schema
 
-Rootzero request and response data is encoded as a stream of typed blocks. A
+Rootzero input and response data is encoded as a stream of typed blocks. A
 schema string describes the payload body for discovery events and tooling; the
 runtime block key is the compact type tag that identifies that payload layout in
 the active schema context. The block alias is published separately from the
@@ -27,12 +27,23 @@ For example, the standard `amount` alias uses the key derived from `#amount`
 and the schema body `{ bytes32 asset, uint amount }`. Custom block keys do not
 have to be keccak-derived. They
 are opaque `bytes4` tags and only need to be unique in the context where they are
-used. A host can publish the meaning of a custom key with:
+used. A host can publish the meaning of a custom key as an annotation:
 
 ```solidity
-event Schema(uint indexed host, bytes4 key, string schema, bytes32 name);
+event Annotation(uint indexed entity, bytes data);
+#schema { uint spec, #string as body, bytes32 name }
 ```
 
+Annotation merge behavior is defined by the annotation block type rather than
+by the `Annotation` event. A `#schema` annotation is identified by its entity
+and the block key encoded in `spec`: distinct keys accumulate, while the latest
+trusted claim for the same key replaces the earlier one. Other annotation types
+may define additive, historical, or explicitly revocable behavior instead.
+
+The standard `#action { uint action }` annotation assigns one primary semantic
+action to an entity. The latest trusted value replaces the previous value, and
+`Actions.None` clears the classification.
+
 For example, a host-specific payment block can use a small literal, the command
 selector, or any other chosen `bytes4` value as long as that key is not
 overloaded in the relevant host/schema context.
@@ -50,7 +61,7 @@ schema: { bytes32 asset, uint amount }
 A block body can reference another block alias as a child item with `#`:
 
 ```txt
-{ bytes32 account, #bytes as state, #bytes as request }
+{ bytes32 account, #bytes as state, #bytes as input }
 ```
 
 The empty schema string `""` means the block has no structured payload. This is
@@ -72,8 +83,8 @@ length, fixed fields may appear before, after, or between child blocks.
 
 ```txt
 { uint target, uint resources, #bytes as payload }
-{ bytes32 account, #bytes as state, #bytes as request }
-{ bytes4 key, #string as body, bytes32 name }
+{ bytes32 account, #bytes as state, #bytes as input }
+{ uint spec, #string as body, bytes32 name }
 { #bytes as left, uint op, #bytes as right }
 ```
 
@@ -108,24 +119,30 @@ generic list block; it does not repeat the item in place.
 ## Endpoint Lanes
 
 Endpoint descriptors identify each lane with a block key and group size. In
-Solidity, endpoint definition helpers accept `bytes9` lane values, with plain
-`bytes4` keys and the `bytes8` values returned by `many(item)` widening
-implicitly. A plain key or `many(item)` stores a zero group byte that readers
-interpret as group size 1, while `bytes9(0)` or `Keys.Empty` means the endpoint
-has no blocks in that lane. Use
-`group(lane, size)` when a lane needs an explicit group size other than 1.
+Solidity, endpoint definition helpers accept block specs such as `Specs.Amount`.
+A zero group is interpreted as group size 1, while `Specs.Empty` means the
+endpoint has no blocks in that lane. Use `group(spec, size)` when a lane needs
+an explicit group size other than 1.
 
-The packed descriptor stores each lane key as an 8-byte value:
+The packed descriptor uses these lane layouts:
 
 ```txt
-[key bytes4][item bytes4]
+state   [key:4][group:1]
+input   [key:4][item:4][group:1]
+output  [key:4][min:4][max:4][hint:4][group:1]
 ```
 
-A plain block key is widened into `[key][0]`, so normal endpoint declarations can
-pass standard `bytes4` keys directly. A lane with a nonzero `item` describes a
-generic container block: `key` is the top-level wire key and `item` is the
-contained item key. The built-in `many(item)` helper creates `[Keys.List][item]`
-with the default group size 1, matching the DSL form `many #item`.
+Containers are exclusive to input. A plain input spec is compressed into
+`[spec.key][0]`. A spec with a nonzero container is compressed into
+`[spec.container][spec.key]`: the container is the top-level wire key and the
+item is its contained block key. The built-in `many(spec)` helper annotates the
+spec with `Specs.List` as its container, matching the DSL form `many #item`.
+Output lanes retain their size bounds and allocation hint so execution can
+reconstruct the output spec and initialize its writer directly. The Solidity
+output decoder returns this as a left-aligned, writer-ready spec that retains
+its encoded group. Its container and reserved fields are cleared. `Specs.group`
+returns the effective group, interpreting an encoded zero as one for a
+non-empty spec.
 
 Any non-empty lane resolves its key to a block alias and schema body through the
 active schema context. If the item slot is nonzero, tooling also resolves that
@@ -149,7 +166,7 @@ top-level structure.
 
 ## Field Aliases
 
-Block aliases are published in `Schema` events. Field aliases are presentation
+Block aliases are published in `#schema` annotations. Field aliases are presentation
 metadata for tooling. They do not change payload layout or runtime keys.
 
 ```txt
@@ -299,33 +316,33 @@ invalid in any path segment.
 - `#string`: UTF-8 string bytes, written without a body
 - `#list`: generic list wrapper emitted by `many`
 
-Custom input shapes should define their own context-local block key and publish
-that key with a `Schema` event. Endpoint contracts can use `schema(...)` for
-that publication:
+Custom input shapes should define their own context-local block spec and publish
+it with a `#schema` annotation. Endpoint contracts can use `schema(...)` to
+construct and publish that spec:
 
 ```solidity
-bytes4 input = schema(1, "{ bytes32 asset, uint amount }");
+uint input = schema(1, 64, 64, 64, "{ bytes32 asset, uint amount }", bytes32(0));
 ```
 
 Use different numeric keys when a host needs more than one local block key. The
 key can also be a selector or any other `bytes4` value that is unique in the
-context where it is used. The alias names the block; the schema string describes
-only the payload body.
+context where it is used. The numeric arguments after the key are the minimum,
+maximum, and allocation hint payload sizes. The alias names the block; the
+schema string describes only the payload body.
 
 ## Standard Blocks
 
-Common protocol schemas live in `contracts/blocks/Schema.sol`:
+Common protocol schemas live in `contracts/codec/Schema.sol`:
 
 ```txt
 amount   { bytes32 asset, uint amount }
 balance  { bytes32 asset, uint amount }
 custody  { uint host, bytes32 asset, uint amount }
 call     { uint target, uint resources, #bytes as payload }
-step     { uint target, uint resources, #bytes as request }
-context  { bytes32 account, #bytes as state, #bytes as request }
+step     { uint cmd, uint resources, #bytes as input }
+context  { bytes32 account, #bytes as state, #bytes as input }
 recover  { uint handler, uint resources, bytes32 key, #bytes as witness }
-auth     { uint cid, uint deadline, #bytes as proof }
-schema   { bytes4 key, #string as body, bytes32 name }
+schema   { uint spec, #string as body, bytes32 name }
 ```
 
 `Keys.sol` contains the corresponding standard runtime keys.

package/events/Annotation.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {EventEmitter} from "./Emitter.sol";
+
+/// @notice Emitted to attach encoded annotation blocks to an entity.
+/// @dev `data` is a protocol block stream. A single block is the conventional
+/// case, but related annotations may be emitted together. Annotations are claims
+/// by the emitting contract, and each block key defines its annotation type.
+/// Consumers process events in log order and blocks in stream order, then apply
+/// the identity and merge rules defined by each annotation type. The event does
+/// not impose a universal replacement policy: a type may replace, accumulate,
+/// preserve history, or define its own revocation convention.
+abstract contract AnnotationEvent is EventEmitter {
+    string private constant ABI = "event Annotation(uint indexed entity, bytes data)";
+
+    /// @param entity Entity being annotated.
+    /// @param data Encoded annotation block stream, conventionally containing one block.
+    event Annotation(uint indexed entity, bytes data);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/events/Endpoint.sol

@@ -6,12 +6,12 @@ import {EventEmitter} from "./Emitter.sol";
 /// @title EndpointEvent
 /// @notice Emitted during host deployment to publish a callable endpoint descriptor.
 abstract contract EndpointEvent is EventEmitter {
-    string private constant ABI = "event Endpoint(uint indexed host, uint id, bytes32 descriptor)";
+    string private constant ABI = "event Endpoint(uint indexed host, uint id, uint descriptor)";
 
     /// @param host Host node ID that exposes the endpoint.
     /// @param id Endpoint node ID.
     /// @param descriptor Packed endpoint lane metadata and flags.
-    event Endpoint(uint indexed host, uint id, bytes32 descriptor);
+    event Endpoint(uint indexed host, uint id, uint descriptor);
 
     constructor() {
         emit EventAbi(ABI);

package/events/Guardian.sol

@@ -3,12 +3,12 @@ pragma solidity ^0.8.33;
 
 import { EventEmitter } from "./Emitter.sol";
 
-/// @notice Emitted when a guardian account status changes on a host.
+/// @notice Emitted when a user account's guardian role changes on a host.
 abstract contract GuardianEvent is EventEmitter {
     string private constant ABI = "event Guardian(uint indexed host, bytes32 account, bool active)";
 
     /// @param host Host node ID where the guardian change occurred.
-    /// @param account Guardian account ID.
+    /// @param account User account ID assigned or removed as a guardian.
     /// @param active True if the guardian is enabled, false if revoked.
     event Guardian(uint indexed host, bytes32 account, bool active);
 

package/events/Introduction.sol

@@ -5,12 +5,13 @@ import { EventEmitter } from "./Emitter.sol";
 
 /// @notice Emitted when a host introduces itself to another host.
 abstract contract IntroductionEvent is EventEmitter {
-    string private constant ABI = "event Introduction(uint indexed host, uint peer, uint blocknum)";
+    string private constant ABI = "event Introduction(uint indexed host, uint peer, bytes32 origin, uint blocknum)";
 
     /// @param host Host node ID receiving the introduction.
     /// @param peer Host node ID of the introducing contract.
+    /// @param origin Transaction-origin address encoded as a chain-agnostic user account.
     /// @param blocknum Block number at which the host was deployed.
-    event Introduction(uint indexed host, uint peer, uint blocknum);
+    event Introduction(uint indexed host, uint peer, bytes32 origin, uint blocknum);
 
     constructor() {
         emit EventAbi(ABI);