@rootzero/contracts 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -3,6 +3,106 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.16.0
+
+### Breaking Changes
+
+- Removed the unused generic `Position` event and `PositionEvent` base contract.
+- Renamed transaction handling from settlement to posting: the transaction
+  helper is now `post(...)`, and `portSettle(bytes)` is now `portPost(bytes)`.
+  The port selector and node ID change, and its action is now `Actions.Post`
+  (`14`) instead of `Actions.Settle` (`3`). The `Settlement` convenience base
+  implements both the transaction `PostHook` and position `SettleHook`.
+- Removed `openInput` from `EndpointBase`. Port, query, and guard bases expose
+  `openInput` through the input-only `InputEndpointBase`, while custom commands
+  must pass both state and input through `openCommand`.
+- Removed the wildcard `Specs.Any` state type. The stateful relay is now
+  `relayBalancePayable` and accepts `BALANCE` state blocks; `relayPayable`
+  explicitly accepts empty state.
+- Renamed the numeric `Position` fields from `assets` and `liabilities` to
+  `amount` and `debt`.
+- Renamed `Budget.use` to `useResourceValue` and split execution spending into
+  exact `useValue` and packed-resource `useResourceValue` helpers.
+- Renamed `RoutePayableHook.route` to `RelayPayableHook.relayTo`. Recovery hooks
+  are now `RecoverPayableHook` implementations that receive the complete
+  resource word and mutable execution budget.
+
+### Added
+
+- Added the hostless `#position` state block for threading asset-liability pairs
+  between pipeline commands.
+- Added the `settle` command, the position `SettleHook`, and the transaction
+  `PostHook`. The `Settlement` convenience base provides default implementations
+  of both through the debit and credit account hooks.
+- Added `relayBalancePayable` for relaying required `BALANCE` state while
+  `relayPayable` now explicitly relays with empty state.
+- Added memory-backed `InternalDebitAccount`, `InternalCreditAccount`, and
+  `InternalSettle` adapters for hosts that execute canonical commands directly
+  from their pipeline dispatcher.
+
+### Changed
+
+- Documented the command state-safety invariant: every command must handle the
+  complete supplied state stream or revert, and commands with empty state lanes
+  must reject non-empty state.
+- Endpoint decoder opening now requires the complete supplied lane to be one
+  homogeneous run of the descriptor's declared key; trailing block types are
+  rejected instead of silently left outside the decoder cursor.
+- Block runs and cursors now retain raw block counts only. Descriptor stride
+  conversion and state/input group reconciliation happen once in execution
+  opening rather than in `Blocks` or `Cursors`.
+- Pipeline transaction streams are posted before the next step, and position
+  state is settled separately through the scalar asset, amount, liability, and
+  debt hook.
+
+### Upgrade Compatibility
+
+- Command and port selectors, block schemas, and hook signatures changed in
+  this release. Deploy fresh hosts and update pipeline builders and peer
+  integrations together.
+
+## 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

package/Codec.sol

@@ -4,7 +4,7 @@ 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 { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
 import { Keys } from "./codec/Keys.sol";
 import { Sizes, Specs } from "./codec/Specs.sol";
 import { Descriptors } from "./codec/Descriptors.sol";

package/Commands.sol

@@ -11,4 +11,4 @@ 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";
+import {AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx} from "./core/Types.sol";

package/Core.sol

@@ -4,18 +4,21 @@ 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 { 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 { CreditAccountHook, DebitAccountHook, PostHook, SettleHook, Settlement } from "./core/Settlement.sol";
 import { Portal } from "./core/Portal.sol";
-import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Tx } from "./core/Types.sol";
+import { AssetAmount, AccountAsset, AccountAmount, HostAmount, HostAccountAsset, HostAccountAmount, Position, Tx } from "./core/Types.sol";
 import { Validator } from "./core/Validator.sol";
 
 

package/Endpoints.sol

@@ -5,7 +5,7 @@ pragma solidity ^0.8.33;
 // Import this file to inherit from the full rootzero callable host surface without managing individual paths.
 
 // Shared endpoint hooks
-import { CreditAccountHook, DebitAccountHook } from "./core/Settlement.sol";
+import { CreditAccountHook, DebitAccountHook, PostHook, SettleHook } from "./core/Settlement.sol";
 
 // Commands
 import { Allocate, AllocateHook } from "./commands/Allocate.sol";
@@ -15,21 +15,21 @@ import { DebitAccount } from "./commands/Debit.sol";
 import { Deposit, DepositHook, DepositPayable, DepositPayableHook } from "./commands/Deposit.sol";
 import { Payout, PayoutHook } from "./commands/Payout.sol";
 import { Provision, ProvisionHook, ProvisionPayable, ProvisionPayableHook } from "./commands/Provision.sol";
-import { RecoverHook, RecoverPayable } from "./commands/Recover.sol";
-import { RelayPayable, RoutePayableHook } from "./commands/Relay.sol";
+import { RecoverPayable, RecoverPayableHook } from "./commands/Recover.sol";
+import { RelayPayable, RelayBalancePayable, RelayPayableHook } from "./commands/Relay.sol";
+import { Settle } from "./commands/Settle.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands
 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
@@ -42,7 +42,7 @@ import { PortDebitAccount } from "./ports/Debit.sol";
 import { PortDenyAssets } from "./ports/DenyAssets.sol";
 import { PortPipePayable } from "./ports/Pipe.sol";
 import { PortDispatchPayable } from "./ports/Dispatch.sol";
-import { PortSettle } from "./ports/Settle.sol";
+import { PortPost } from "./ports/Post.sol";
 
 // Guard endpoints
 import { GuardBase } from "./guards/Base.sol";

package/Events.sol

@@ -4,24 +4,22 @@ 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";
 import { CommanderEvent } from "./events/Commander.sol";
 import { DispatchEvent } from "./events/Dispatch.sol";
 import { EndpointEvent } from "./events/Endpoint.sol";
-import { PositionEvent } from "./events/Position.sol";
 import { ReceivedEvent } from "./events/Received.sol";
 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

@@ -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,6 +47,29 @@ 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 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
@@ -126,7 +149,7 @@ const input = concat([
 ```
 
 Everything downstream keeps this shape: commands loop over input blocks,
-settlement loops over transactions, pipelines loop over steps. Batching is
+posting loops over transactions, pipelines loop over steps. Batching is
 never a special case.
 
 ## IDs, Accounts, Assets, and Nodes
@@ -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
@@ -219,30 +248,51 @@ struct CommandContext {
 
 Every command returns two block streams: `state`, which is threaded into the
 next pipeline step, and `transactions`, which contains `#transaction` blocks
-for the pipeline host to settle outside the state lane. Either stream may be
+for the pipeline host to post outside the state lane. Either stream may be
 empty.
 
-The input carries instructions; the state carries live value. While a
-sequence of commands executes, `#balance` and `#custody` blocks in the state
-are the funds being moved — produced by one command, consumed by the next.
+State is linear, not optional ambient context. A command is responsible for
+the entire state stream it receives: it must validate and consume it, transform
+and return it, forward it intact, or revert. A command must never succeed while
+silently ignoring or dropping supplied state. Commands that declare
+`Specs.Empty` state therefore reject any non-empty state, while commands that
+accept state validate the complete stream against their declared state schema.
+This is especially important for `#position`, because dropping a position could
+silently discard both live value and an outstanding debt requirement.
 
-The standard `Deposit` mixin shows the canonical shape — open the input,
-loop the batch, call the hook, write the output run:
+The input carries instructions; the state carries live value. While a
+sequence of commands executes, `#balance`, `#custody`, and `#position` blocks
+in the state are the value being moved — produced by one command, consumed by
+the next. A position carries an asset-liability pair as
+`{ asset, amount, liability, debt }`.
+
+`#position` is general live state rather than a lending-specific debt record.
+It pairs value acquired or controlled with value owed or required. A command
+may preserve or replace either side and return the resulting position for the
+next step; `settle` terminally consumes the pair. This supports swaps,
+borrowing, refinancing, collateral changes, callback obligations, cross-host
+claims, fees, netting, and other multi-step operations. A position is a
+transient representation and does not itself create or erase an obligation
+recorded by an external system.
+
+The standard `Deposit` mixin shows the canonical shape: open and validate both
+command lanes, loop the batch, call the hook, and write the output run:
 
 ```solidity
 function deposit(
-    CommandContext calldata c
+    bytes32 account,
+    bytes calldata state,
+    bytes calldata input
 ) external onlyCommand returns (bytes memory, bytes memory) {
-    (Cur memory input, uint outputs) = openInput(c.input, descriptor);
-    Writer memory output = Writers.allocBalances(outputs);
+    Execution memory exec = openCommand(state, input, descriptor, 0);
 
-    while (input.i < input.len) {
-        (bytes32 asset, uint amount) = input.unpackAmount();
-        deposit(c.account, asset, amount); // host policy hook
-        output.appendBalance(asset, amount);
+    while (exec.more()) {
+        (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
+        deposit(account, asset, amount); // host policy hook
+        exec.outputBalance(asset, amount);
     }
 
-    return (end(output), "");
+    return close(exec, account);
 }
 ```
 
@@ -263,7 +313,13 @@ abstract contract MyCommand is CommandBase {
         bytes calldata state,
         bytes calldata input
     ) external onlyCommand returns (bytes memory, bytes memory) {
-        // parse input, loop, return the output state run and any transactions
+        Execution memory exec = openCommand(state, input, descriptor, 0);
+        while (exec.more()) {
+            (bytes32 asset, uint amount) = exec.unpackAmount(Lanes.Input);
+            // Apply command-specific behavior for this group.
+            exec.outputBalance(asset, amount);
+        }
+        return close(exec, account);
     }
 }
 ```
@@ -272,8 +328,10 @@ The standard commands cover the common ledger movements: `deposit` and
 `depositPayable` (external funds in), `withdraw` and `burn` (funds out),
 `debitAccount` and `creditAccount` (internal movements), `payout` (deliver
 state to other accounts), `allocate` (turn balance state into custody),
-`provision` (provision custody from an external allocation), and `relayPayable`
-(hand a pipeline to another portal).
+`provision` (provision custody from an external allocation), `settle` (consume
+asset-liability position state), `relayPayable` (relay a pipeline without
+state), and `relayBalancePayable` (relay balance state and a pipeline to another
+portal).
 
 ## Pipelines
 
@@ -287,7 +345,7 @@ step { uint cmd, uint resources, #bytes as input }
 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
+each decoded transaction to the shared posting implementation before
 running the next step. This is the core of `Pipeline.pipe`:
 
 ```solidity
@@ -299,11 +357,11 @@ while (cur.more()) {
         account,
         state,
         input,
-        budget.use(resources)
+        budget.useResourceValue(resources)
     );
     while (transactions.more()) {
         (bytes32 from, bytes32 to, bytes32 asset, uint amount) = transactions.unpackTransaction();
-        settle(from, to, asset, amount);
+        post(from, to, asset, amount);
     }
 }
 if (state.length != 0) revert UnexpectedState();
@@ -316,6 +374,31 @@ 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
 shared budget), so the same pipeline bytes are meaningful to every port.
 
+Hosts that implement a pipeline locally can inherit `InternalDebitAccount`,
+`InternalCreditAccount`, and `InternalSettle` to advertise the canonical command
+endpoints while routing their local command IDs through `executeDebitAccount`,
+`executeCreditAccount`, and `executeSettle`. These adapters consume the
+memory-backed pipeline state directly and avoid an external self-call. The host
+dispatcher must reject nonzero step value before invoking them because all three
+commands are non-funded.
+
+Positions also support backward-composed pipelines. In an exact-output route,
+the asset side can represent the desired result while the liability side
+represents the value currently required upstream. Each hop consumes one
+position, fulfills or transforms its current requirement, and returns the next
+position:
+
+```txt
+position(C, 100, C, 100)
+→ position(C, 100, B, 50)
+→ position(C, 100, A, 25)
+→ settle
+```
+
+This is backward composition, not backward execution: `#step` blocks still
+execute forward in their encoded order. Exact-output routing is only one use;
+other commands may transform the asset side, the liability side, or both.
+
 ## Queries
 
 Queries are the read endpoints: view functions that take a block-stream input
@@ -336,15 +419,15 @@ the descriptor's lanes through the published block schemas.
 Ports are the host-to-host surfaces, callable only by trusted peer hosts. The two
 central ones are batches all the way down:
 
-- `portSettle` consumes `transaction { bytes32 from, bytes32 to, bytes32 asset,
+- `portPost` consumes `transaction { bytes32 from, bytes32 to, bytes32 asset,
   uint amount }` blocks, debiting `from` and crediting `to` per
-  block — how two hosts record settlement between their ledgers.
+  block — how two hosts post transactions between their ledgers.
 - `portPipePayable` consumes `context` blocks, each carrying an account, an
   initial state, and a run of steps — a complete pipeline delivered by another
   host, executed locally against the port call's shared value budget.
 
-This is also the cross-portal mechanism. `relayPayable` (or `portDispatchPayable`)
-wraps a pipe and addresses it to a portal, commonly the destination host ID;
+This is also the cross-portal mechanism. `relayPayable`, `relayBalancePayable`,
+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 commands
@@ -357,9 +440,9 @@ bytes and produce the same output bytes for every endpoint.
 
 Admin commands use the regular command shape but are gated to the host's admin
 account: trust management (`authorize`, `unauthorize`), guardian management
-(`appoint`, `dismiss`), metadata (`label`, `publishSchema`), asset gating (`allowAssets`,
-`denyAssets`, `allowance`), lifecycle (`init`, `destroy`), and raw calls
-(`executePayable`). Guards go the other way: direct actions guardians can take
+(`appoint`, `dismiss`), metadata (`annotate`), optional asset gating
+(`allowAssets`, `denyAssets`, `allowance`), and raw calls (`executePayable`).
+Guards go the other way: direct actions guardians can take
 without any command context — the default is `revoke`, which lets a guardian
 drop a trusted node immediately.
 

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;
+    }
+}