fix: align skills with sails header routing

Author: ukint-vs

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test-layout test-skills test-parser test-install test-packaging test-update verify
+.PHONY: test-layout test-skills test-parser test-install test-packaging test-update verify verify-real verify-all
 
 test-layout:
 	python3 tests/test_repo_layout.py
@@ -21,3 +21,8 @@ test-update:
 	python3 tests/test_update_check.py
 
 verify: test-layout test-skills test-parser test-install test-packaging test-update
+
+verify-real:
+	bash scripts/verify-real-sails-program.sh
+
+verify-all: verify verify-real

references/delayed-message-pattern.md

@@ -6,21 +6,24 @@ Use this pattern for future-block work such as reminders, auctions, inactivity c
 
 ## Canonical Self-Message Payload
 
-For a standard Sails self-call by route name, encode service, method, and arguments in order, then concatenate:
+For a Sails 1.0 self-call, build the same Sails Header v1 plus SCALE-encoded params that generated clients use. In generated Rust client code this is the `io::<Call>::encode_call(route_idx, args...)` helper:
 
 ```rust
-let payload = [
-    "ReminderBoard".encode(),
-    "TriggerReminder".encode(),
-    id.encode(),
-]
-.concat();
+use reminder_board_client::{
+    ReminderBoardClientProgram,
+    reminder_board::io::TriggerReminder,
+};
+
+let payload = TriggerReminder::encode_call(
+    ReminderBoardClientProgram::ROUTE_ID_REMINDER_BOARD,
+    id,
+);
 ```
 
-- This is the route-prefixed byte shape to use when a delayed internal message cannot go through a generated client call directly.
-- Keep the service and method names aligned with the exported Sails routes.
-
-Note: In Sails 1.0, messages use the binary header protocol instead of SCALE-string routing for the route prefix. See `../../references/sails-header-wire-format.md` for the encoding.
+- This is the header-routed byte shape to use when a delayed internal message cannot go through a generated client send directly.
+- Keep the route constant and generated `io` type aligned with the exported Sails route.
+- If generated client code is unavailable, manually encode the Sails Header v1 followed by SCALE-encoded params. See `../../references/sails-header-wire-format.md` for the header layout.
+- The legacy SCALE-string route form (`service`, `method`, then args) is not a valid Sails 1.0 delayed self-message payload.
 
 ## Sending The Delayed Message
 
@@ -71,4 +74,4 @@ pub fn trigger_reminder(&mut self, id: u64) {
 
 - Use `run_to_block` for delay-sensitive assertions.
 - Assert both the scheduler-side effect and the eventual handler-side effect.
-- If debugging the raw byte route, test the payload shape directly before blaming gas or timing.
+- If debugging the raw byte route, assert the payload starts with the Sails Header v1 bytes (`GM`, version `0x01`, header length `0x10`) before blaming gas or timing.

references/gear-builtin-actors.md

@@ -152,7 +152,7 @@ When debugging a builtin reply:
 1. Confirm the sender targeted a builtin `ActorId`, not a program. If it was a program, this skill does not apply — go to `gear-message-execution`.
 2. Identify the matching helper crate by source `ActorId` ↔ builtin id.
 3. Classify: empty success, typed `Response`, or error reply.
-4. Decode as `gbuiltin_*::Response` using `parity_scale_codec::Decode` — not a Sails generated client, not `ProgramMetadata`. There is no Sails route prefix on a builtin reply.
+4. Decode as `gbuiltin_*::Response` using `parity_scale_codec::Decode` — not a Sails generated client, not `ProgramMetadata`. There is no Sails Header framing on a builtin reply.
 5. On error replies, inspect the payload as `BuiltinActorError` (defined in the `builtins-common` crate at `vara/sdk/builtins/common/src/lib.rs`; import as `use builtins_common::BuiltinActorError;`). Common variants: `InsufficientGas` when the caller-supplied `gas_limit` is below the call's weight; `GasAllowanceExceeded` when the block-level allowance is exhausted; `InsufficientValue`; `DecodingError`; and `Custom(LimitedStr<'static>)` for actor-specific errors.
 
 ## Gas and ED
@@ -164,7 +164,7 @@ When debugging a builtin reply:
 ## Guardrails
 
 - **Do not hardcode an `ActorId` without citing a runtime file.** Re-derive with `hash((b"built/in", id).encode())` or copy from `vara/runtime/vara/src/lib.rs`, and note the source.
-- **Do not decode builtin replies with a Sails client.** There is no route prefix; use the helper crate's `Response` type.
+- **Do not decode builtin replies with a Sails client.** There is no Sails Header framing; use the helper crate's `Response` type.
 - **Do not call a builtin from a sync handler.** The call is `_for_reply`; the handler must be async.
 - **Do not assume a reply shape across runtime versions.** Helper crates evolve — pin to a workspace version that matches the target runtime.
 - **Do not wrap a builtin behind a service handler that loses idempotency.** Broker services should carry their own retry and reconciliation state; the builtin has no memory.

references/gear-execution-model.md

@@ -28,7 +28,7 @@
 - Name actors, commands, queries, replies, events, and failure paths in specs before implementation starts.
 - Use delayed messages for future block work when the program really must revisit state later.
 - Use gas reservation only when future work needs a preserved execution budget across blocks.
-- Prefer generated Sails clients for normal app paths so route prefixes and reply decoding stay aligned with the program contract.
+- Prefer generated Sails clients for normal app paths so Sails Header routing and reply decoding stay aligned with the program contract.
 
 ## Validation Implications
 

references/gear-gstd-api-and-syscalls.md

@@ -32,7 +32,7 @@ Use `msg` when the design question is about payload handling, outbound messages,
 | Await a reply in async code | `_for_reply` helpers such as `msg::send_bytes_for_reply` | same send wrappers plus async runtime locks | send syscalls plus reply deposit or reply-hook handling |
 | Spend reserved gas on later messaging | reservation-backed send or reply variants | reservation send or reply wrappers | `gr_reservation_send`, `gr_reservation_send_commit`, `gr_reservation_reply`, `gr_reservation_reply_commit` |
 
-Design note: prefer typed APIs for stable app contracts. Use bytes variants when the route is intentionally raw or when isolating codec or route-prefix bugs in Sails.
+Design note: prefer typed APIs for stable app contracts. Use bytes variants when the route is intentionally raw or when isolating codec or Sails Header routing bugs.
 
 ### `gstd::exec`
 

references/gear-messaging-and-replies.md

@@ -7,7 +7,7 @@
 - Use delayed variants when execution must happen in a future block.
 - Use reservation-backed variants when later execution needs preserved gas.
 - Use staged payload flows only when the payload must be built incrementally.
-- When a Sails program calls a Sails constructor or service, prefer generated clients or equivalent route-prefixed encoding rather than an ad hoc raw struct payload.
+- When a Sails program calls a Sails constructor or service, prefer generated clients or equivalent Sails Header-aware encoding rather than an ad hoc raw struct payload.
 
 ## Message Lifecycle Checklist
 
@@ -37,9 +37,9 @@
 
 ## Sails Routing Notes
 
-- Generated Sails clients encode the correct service and method route prefixes for you.
-- The Sails wire format is route-prefixed encoded data, so a bare raw struct is not a normal constructor or service payload.
-- If a payload uses the wrong route prefix, decode fails even when the payload body type is otherwise correct.
+- Generated Sails clients encode the Sails Header and SCALE body for you.
+- The Sails 1.0 wire format is Sails Header v1 plus encoded data, so a bare raw struct is not a normal constructor or service payload.
+- If a payload uses the wrong interface ID, entry ID, or route index, decode fails even when the payload body type is otherwise correct.
 - Treat generated clients as the default path and use low-level byte encoding only to isolate transport or codec bugs.
 
 ## Guardrails

references/gear-sails-production-patterns.md

@@ -516,7 +516,7 @@ let reply = DemoProgram::client(program_id)
 
 Use generated clients by default because they preserve:
 
-- route-prefix correctness
+- Sails Header routing correctness
 - reply decoding
 - test mocks
 - consistency between Rust and TS consumers
@@ -533,12 +533,10 @@ fn send_timeout_from_reservation(
     player_id: ActorId,
     delay: u32,
 ) {
-    let request = [
-        "Battle".encode(),
-        "AutomaticMove".to_string().encode(),
-        player_id.encode(),
-    ]
-    .concat();
+    let request = battle_client::battle::io::AutomaticMove::encode_call(
+        battle_client::BattleClientProgram::ROUTE_ID_BATTLE,
+        player_id,
+    );
 
     msg::send_bytes_delayed_from_reservation(
         reservation_id,
@@ -553,12 +551,10 @@ fn send_timeout_from_reservation(
 
 ```rust
 fn send_cleanup(player: ActorId, gas: u64, delay: u32) {
-    let payload = [
-        "Game".encode(),
-        "RemoveInstance".encode(),
-        player.encode(),
-    ]
-    .concat();
+    let payload = game_client::game::io::RemoveInstance::encode_call(
+        game_client::GameClientProgram::ROUTE_ID_GAME,
+        player,
+    );
 
     msg::send_bytes_with_gas_delayed(Syscall::program_id(), payload, gas, 0, delay)
         .expect("Error in sending message");

references/sails-cheatsheet.md

@@ -58,7 +58,7 @@ These errors appear in order of frequency from builder feedback.
 ## IDL And Clients
 - Sails generates IDL from Rust types at build time.
 - Generated clients are the default typed integration surface for Rust and TypeScript.
-- Generated clients encode the correct payloads for constructor and service calls using route-prefixed SCALE encoding.
+- Generated clients encode the correct payloads for constructor and service calls using the Sails Header plus SCALE body.
 - The IDL uses V2 syntax (see `../../references/sails-idl-v2-syntax.md`) and messages use a binary header protocol (see `../../references/sails-header-wire-format.md`).
 - Architecture decisions must keep exported DTO names distinct from service names.
 - Events are part of the public interface and should map to meaningful state transitions.
@@ -67,7 +67,7 @@ These errors appear in order of frequency from builder feedback.
 - Specs should talk in terms of program constructors, service routes, commands, queries, and events.
 - Specs should name the chosen state ownership pattern instead of leaving storage implicit.
 - Architecture plans should keep `#[program]` thin and push logic into services.
-- Implementation guidance should prefer generated clients or other Sails route-prefixed encoding over raw payload handling.
+- Implementation guidance should prefer generated clients or other Sails Header-aware encoding over raw payload handling.
 
 ## See Also
 - `references/sails-rs-imports.md`

references/sails-header-wire-format.md

@@ -4,22 +4,24 @@ Source of truth: [docs/sails-header-v1-spec.md](https://github.com/gear-tech/sai
 
 ## Overview
 
-Every Sails message begins with a 16-byte base header (extensions optional) prepended to the SCALE-encoded payload. The header lives entirely within the Gear message payload — no runtime or consensus changes required.
+Every Sails 1.0 message begins with a 16-byte header prepended to the SCALE-encoded payload. The header lives entirely within the Gear message payload — no runtime or consensus changes required.
 
 ## Base Header Layout
 
 ```
 Byte offset  Field          Size (bytes)  Description
 0–1          Magic          2             ASCII "GM" (0x47 0x4D)
 2            Version        1             0x01
-3            Header length  1             Total header size; base = 0x10
+3            Header length  1             Must be 0x10 in v1
 4–11         Interface ID   8             64-bit ID from interface hash
 12–13        Entry ID       2             Little-endian 16-bit entry identifier
 14           Route Index    1             0x00 = infer route if unambiguous
 15           Reserved       1             Must be 0x00 in v1
->15          Extensions     variable      Present only if header length > 0x10
+>15          Payload        variable      SCALE-encoded params or body
 ```
 
+Extension-sized headers are reserved for future versions. A v1 decoder must reject header lengths other than `0x10`.
+
 ## Identifier Derivation
 
 ### Interface ID
@@ -42,15 +44,15 @@ Generated clients encode/decode the header automatically. When debugging wire pa
 ## Interface ID Stability
 
 - Adding or removing methods/types **changes** the interface ID
-- Renaming methods does NOT change the interface ID (hash is structural)
-- `@entry_id` overrides allow pinning specific entry points across versions
+- Renaming public methods **changes** the interface ID because the exported function route name is hashed
+- `@entry_id` overrides allow pinning specific entry points across versions, but they do not preserve the interface ID after a method rename
 - Programs hosting V1 and V2 services simultaneously can use `route_idx` to disambiguate
 
 ## Validation Checklist
 
 1. Magic: first two bytes are `0x47 0x4D`
 2. Version: `0x01`
-3. Header length: `= 0x10` for v1; `> 0x10` only when extensions are present and must be `<= payload_length`
+3. Header length: must equal `0x10` for v1; reject smaller, larger, or extension-sized v1 headers
 4. Reserved byte: must be `0x00` in v1
 5. Route inference (`0x00`): resolve only if exactly one matching instance exists
 

references/sails-idl-v2-syntax.md

@@ -67,9 +67,18 @@ struct Point<T> { x: T, y: T }
 enum Result<T, E> { Ok(T), Err(E) }
 ```
 
-### Built-in Aliases
+### Built-in Primitives And Common Aliases
 
-`actor` = `ActorId([u8; 32])`, `code` = `CodeId([u8; 32])`, `u256` = `U256([u64; 4])`, `h160` = `H160([u8; 20])`, `h256` = `H256([u8; 32])`, `map<K,V>` = `[(K,V)]`, `set<T>` = `[T]`
+Built-in primitives include `actor` = `ActorId([u8; 32])`, `code` = `CodeId([u8; 32])`, `messageid` = `MessageId([u8; 32])`, `u256` = `U256([u64; 4])`, `h160` = `H160([u8; 20])`, and `h256` = `H256([u8; 32])`.
+
+`map<K,V>` and `set<T>` are not built in. Declare them in a `types` block before use:
+
+```
+types {
+    alias map<K,V> = [(K,V)];
+    alias set<T> = [T];
+}
+```
 
 ## Service
 
@@ -170,6 +179,8 @@ service Canvas {
     }
 
     types {
+        alias map<K,V> = [(K,V)];
+        alias set<T> = [T];
         struct Color { color: [u8; 4], space: ColorSpace }
         enum ColorError { InvalidSource, DeadPoint }
         struct Point<T> { x: T, y: T }