feat(ethexe-consensus): mini-announces for instant injected TX promises

.gitignore

@@ -1,3 +1,6 @@
+# claude code
+.claude/worktrees/
+
 # misc
 .binpath
 log/

.graphify_python

@@ -0,0 +1 @@
+/Users/ukintvs/.local/pipx/venvs/graphifyy/bin/python

.rust-analyzer.toml

@@ -0,0 +1,54 @@
+[workspace]
+# Keep analysis limited to the main workspace crates.
+symbol.search.scope = "workspace"
+
+[workspace.files]
+# Avoid watching build output to keep the language server responsive.
+watcher = "notify"
+exclude = [
+    "target",
+    "*/target",
+    "node/runtime/wasm",
+    "npins",
+    "examples",
+    "*/examples",
+    "demos",
+    "*/demos",
+    "*/proc-macro",
+    "pallets/gear/proc-macro",
+]
+
+[workspace.cargo]
+# Reuse a lightweight target directory dedicated to rust-analyzer.
+targetDir = "target/rust-analyzer"
+# Skip benches/examples/tests to reduce the amount of metadata cargo emits.
+allTargets = false
+# Build scripts in this workspace are heavy; turning them off keeps the server light.
+buildScripts.enable = false
+# Only enable the `std` feature flag for most crates to keep dependencies lean.
+features = ["std"]
+# Some crates rely on defaults, so we keep them.
+noDefaultFeatures = false
+# Provide an isolated set of environment variables so rust-analyzer does not inherit
+# project-specific overrides that would trigger additional builds.
+extraEnv = {
+    "RUSTFLAGS" = "",
+    "SKIP_WASM_BUILD" = "1",
+}
+
+[workspace.procMacro]
+# Disable proc-macro expansion; it is expensive in this workspace and seldom needed
+# for lightweight navigation/autocomplete.
+enable = false
+
+# Disable automatic check on save to prevent building demo crates
+checkOnSave = false
+
+[workspace.check]
+# Make `cargo check` a manual command (not on save) and keep it light if triggered.
+command = "check"
+extraArgs = [
+    "--workspace",
+    "--all-features",
+    "--lib",
+]

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.serena/memories/project_overview.md

@@ -0,0 +1,6 @@
+# Project Overview
+- Purpose: Gear Protocol (Substrate-based) providing actor-model smart contract platform and Vara node runtime; workspace hosts runtime, pallets, SDK/tooling, and examples.
+- Tech stack: Rust 2024 edition; Cargo workspace with many crates (node CLI/service, pallets in `pallets/`, runtime specs in `runtime/*`, core libraries `gcore`, `gstd`, `gclient`, `gcli`, `gtest`, `gsdk`, etc.); WASM targets; Substrate framework; Foundry-based Solidity contracts in `ethexe/contracts`; scripts in Bash.
+- Key layout: `node/` (CLI/service/authorship/testing), `pallets/` (Substrate pallets incl. gear), `runtime/` (runtime definitions), `core*` directories (processor/backend/errors), `common/` libs/codegen, `examples/` smart-contract samples, `utils/` tooling (fuzzers, gear-wasmer-cache), `scripts/` helpers (`gear.sh`), `Makefile` targets, `g*` crates (alloc, primitives, std, sdk, etc.), `docker/`, `ansible/`, `terraform/`, `ethexe/` alt node/contracts.
+- Tooling: main entry via `./scripts/gear.sh <command> <subcommand> [...]` (build/check/clippy/format/run/test/etc.) with Makefile wrappers; uses cargo-hack and cargo-nextest (auto-installed by gear.sh init); rust-toolchain pinned; rustfmt config in `rustfmt.toml`.
+- Docs: `README.md` describes protocol vision; `DEVELOPMENT.md` notes `[skip-ci]` for CI skipping syntax.

.serena/memories/style_and_conventions.md

@@ -0,0 +1,6 @@
+# Style and Conventions
+- Language: Rust 2024 edition across workspace; follow standard Rust patterns for Substrate pallets/runtime and async actor-style contracts.
+- Formatting: rustfmt with `imports_granularity = "Crate"` and doc-comment formatting enabled; use `cargo fmt` via `make fmt` or `./scripts/gear.sh format gear`. Editorconfig enforces LF and final newline.
+- Lints: prefer clean clippy runs (`make clippy` / `./scripts/gear.sh clippy gear`/`examples`); tests use cargo-nextest where configured.
+- CI skip token is `[skip-ci]` (not `[skip ci]`).
+- Keep comments concise; align with existing module organization (pallets/runtime/SDK crates) and Substrate naming conventions.

.serena/memories/suggested_commands.md

@@ -0,0 +1,10 @@
+# Suggested Commands
+- Show help: `./scripts/gear.sh --help` (per-command usage) or review `Makefile` targets.
+- Format: `make fmt` (rustfmt whole workspace) or check-only `make fmt-check`.
+- Lint: `make clippy` (workspace + examples) or `make clippy-release` for release mode.
+- Test: `make test` (workspace tests minus some heavy crates) or targeted `make test-pallet`, `make test-gsdk`, `make test-gcli`; doc tests via `./scripts/gear.sh test docs`.
+- Pre-flight: `make pre-commit` runs fmt + typos + clippy + test + runtime import checks; heavier but good for full validation.
+- Build: `make gear` (workspace), `make node` (node binary), `make gear-release`/`node-release` for release builds.
+- Run node: `make run-node` or `make run-dev-node` (sets debug logs).
+- Init tooling: `./scripts/gear.sh init cargo` (installs cargo-hack and cargo-nextest), `./scripts/gear.sh init wasm` for WASM toolchain setup.
+- Clean: `make clean` (cargo clean + git clean -fdx) — beware it removes untracked files.

.serena/memories/task_completion.md

@@ -0,0 +1,6 @@
+# When Finishing a Task
+- Run formatting (`make fmt`) and ensure clippy is clean for touched crates (`make clippy` or narrower gear.sh clippy commands).
+- Execute relevant tests for affected areas; default is `make test` (may be heavy) or scope to pallets/runtime/client examples as appropriate (e.g., `make test-pallet`, `make test-gsdk`).
+- For comprehensive verification, `make pre-commit` (fmt + typos + clippy + test + runtime-import checks) when time allows.
+- If changing node binaries/runtime, consider rebuild: `make node` or `make gear` and rerun smoke tests as needed.
+- Document notable changes/commands run in PR description; use `[skip-ci]` only if intentionally bypassing CI.

.serena/project.yml

@@ -0,0 +1,82 @@
+# list of languages for which language servers are started; choose from:
+#   al               bash             clojure          cpp              csharp           csharp_omnisharp
+#   dart             elixir           elm              erlang           fortran          go
+#   haskell          java             julia            kotlin           lua              markdown
+#   nix              perl             php              python           python_jedi      r
+#   rego             ruby             ruby_solargraph  rust             scala            swift
+#   terraform        typescript       typescript_vts   yaml             zig
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+# Special requirements:
+#   - csharp: Requires the presence of a .sln file in the project folder.
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+- rust
+encoding: "utf-8"
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "gear"
+included_optional_tools: []

TODOS.md

@@ -0,0 +1,45 @@
+# TODOS
+
+## Ethexe: Guard batch commitment during mini-announce computation
+
+**What:** When a new ETH block arrives while the producer is in `WaitingAnnounceComputed` (computing a mini-announce), `DefaultProcessing::new_head` transitions to Initial without creating a batch commitment for the current block. Block N's batch is lost and must be recovered by block N+1's `collect_not_committed_predecessors`.
+
+**Why:** Mini-announces increase the time spent in `WaitingAnnounceComputed` (one cycle per mini-announce vs one per block before), making this window more likely to be hit. The batch commitment for block N is only triggered from `ReadyForMiniAnnounce` → `process_new_head`, so a new head arriving mid-computation skips it.
+
+**Impact:** Low in practice. `create_batch_commitment` is mostly DB reads (~100ms). The 12s ETH block interval makes collision unlikely. If it does happen, block N's announces are still in the DB and will be included in the next block's batch via `collect_not_committed_predecessors`. Only validators/rewards/code commitments queued specifically for block N could be missed.
+
+**Fix options:**
+- Override `process_new_head` for `WaitingAnnounceComputed` to also trigger `AggregateBatchCommitment` with `next_block` saved (same pattern as `ReadyForMiniAnnounce`)
+- Or: accept the current behavior since `collect_not_committed_predecessors` provides recovery
+
+**Files:** `ethexe/consensus/src/validator/producer.rs:154-172`
+
+**Origin:** Flagged by Gemini, Claude bot, and Codex in PR #5321 review. Pre-existing behavior, not introduced by mini-announces, but window is wider now.
+
+## ~~Ethexe: Squash mini-announce chains into single announce in DB~~ DONE
+
+Implemented as producer-only squash: accumulated TXs in-memory, single squashed announce written to DB. Depth capped at 2 (base + squashed). No subordinate changes needed. CDL patches and `is_same_block` kept as correct safety nets for depth-2 chains.
+
+## Ethexe: Depth-1 optimization — eliminate base announce
+
+**What:** Currently blocks have `{base, squashed}` (depth 2). True depth-1 would mean a single announce per block containing both canonical events and injected TXs. This would allow reverting block-aware CDL patches and `leaf_announces`.
+
+**Why:** With depth-1, hop-counting = block-counting, so CDL simplification becomes safe. About ~80 lines of block-aware counting code could be removed.
+
+**Blocker:** TX validation requires the base to be computed first — `select_for_announce` validates TXs against the state at the parent announce. Without a computed base, TXs targeting programs created by canonical events (current block) would be incorrectly rejected as "unknown destination."
+
+**Fix options:**
+- Two-phase compute: compute canonical events first (without an announce), then select TXs, then build single announce
+- Accept the limitation: TXs targeting current-block programs are deferred to next block
+
+**Priority:** P3 — the depth-2 solution works well. This is a nice-to-have simplification.
+
+**Depends on:** Squash landing and proving stable in production.
+
+**Files:** `ethexe/consensus/src/validator/producer.rs`, `ethexe/consensus/src/announces.rs`, `ethexe/compute/src/compute.rs`
+
+**Origin:** CEO review of squash plan, 2026-04-15.
+
+## ~~Ethexe: producer_delay=0 causes tight mini-announce loop~~ MITIGATED
+
+With squashing, `delay=0` means "accumulate on first tick, squash on second tick." No more compute-per-mini cycle. The producer does at most 2 compute calls per block regardless of delay setting. The busy spin is eliminated.

conductor/archive/ethexe_version_20260123/index.md

@@ -0,0 +1,5 @@
+# Track ethexe_version_20260123 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/ethexe_version_20260123/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "ethexe_version_20260123",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-01-23T12:00:00Z",
+  "updated_at": "2026-01-23T12:00:00Z",
+  "description": "implement --version arg for ethexe-cli to output version string like 0.1.0-123abcd"
+}

conductor/archive/ethexe_version_20260123/plan.md

@@ -0,0 +1,16 @@
+# Implementation Plan: ethexe-cli Version Argument
+
+## Phase 1: Discovery & Infrastructure
+- [x] Task: Locate CLI entry point in `ethexe/cli` and identify `clap` configuration. [checkpoint: f136ac0]
+- [x] Task: Implement build script or utility to capture the short commit hash during compilation. [checkpoint: f136ac0]
+- [x] Task: Conductor - User Manual Verification 'Discovery & Infrastructure' (Protocol in workflow.md) [checkpoint: f136ac0]
+
+## Phase 2: Implementation (TDD)
+- [x] Task: Write Tests: Create a test to verify the output of the version command. [checkpoint: f136ac0]
+    - [x] Define expected regex for `<semver>-<short-hash>`. [checkpoint: f136ac0]
+- [x] Task: Implement: Integrate the version string into the `clap` app configuration. [checkpoint: 6a3b11c]
+- [x] Task: Conductor - User Manual Verification 'Implementation (TDD)' (Protocol in workflow.md) [checkpoint: 6d815de]
+
+## Phase 3: Final Verification
+- [x] Task: Build the binary and verify the output manually. [checkpoint: 6d815de]
+- [x] Task: Conductor - User Manual Verification 'Final Verification' (Protocol in workflow.md) [checkpoint: 6d815de]

conductor/archive/ethexe_version_20260123/spec.md

@@ -0,0 +1,19 @@
+# Specification: ethexe-cli Version Argument
+
+## Overview
+Add support for a `--version` flag to the `ethexe-cli` to provide users with precise build information, including the semantic version and the short commit hash of the source code.
+
+## Functional Requirements
+- The `ethexe-cli` executable must accept `--version` and `-V` flags.
+- The output must follow the format: `<semver>-<short-hash>`.
+- Example output: `0.1.10-a1b2c3d`.
+- The command must exit successfully after printing the version.
+
+## Non-Functional Requirements
+- Performance: The version check should be instantaneous.
+- Maintainability: Version information should be derived from the crate's `Cargo.toml` or workspace metadata.
+
+## Acceptance Criteria
+- Running `ethexe --version` prints the correct version and hash.
+- Running `ethexe -V` prints the correct version and hash.
+- The short hash corresponds to the current HEAD at the time of build.

conductor/archive/fix_build_rs_git_tracking_20260123/index.md

@@ -0,0 +1,5 @@
+# Track fix_build_rs_git_tracking_20260123 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/archive/fix_build_rs_git_tracking_20260123/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "fix_build_rs_git_tracking_20260123",
+  "type": "fix",
+  "status": "new",
+  "created_at": "2026-01-23T12:05:00Z",
+  "updated_at": "2026-01-23T12:05:00Z",
+  "description": "Improve git tracking in ethexe/cli/build.rs by watching specific refs"
+}

conductor/archive/fix_build_rs_git_tracking_20260123/plan.md

@@ -0,0 +1,9 @@
+# Implementation Plan: Improve Git Tracking in ethexe-cli build.rs
+
+## Phase 1: Implementation
+- [x] Task: Update `ethexe/cli/build.rs` with robust git tracking logic. [checkpoint: 7852b02]
+- [x] Task: Conductor - User Manual Verification 'Implementation' (Protocol in workflow.md) [checkpoint: 7852b02]
+
+## Phase 2: Verification
+- [x] Task: Build the CLI and verify that the `GIT_SHA` remains correct. [checkpoint: 7852b02]
+- [x] Task: Conductor - User Manual Verification 'Verification' (Protocol in workflow.md) [checkpoint: 7852b02]

conductor/archive/fix_build_rs_git_tracking_20260123/spec.md

@@ -0,0 +1,13 @@
+# Specification: Improve Git Tracking in ethexe-cli build.rs
+
+## Overview
+The current `build.rs` in `ethexe/cli` uses `cargo:rerun-if-changed=../../.git/refs`, which is unreliable for detecting commit or branch changes because directory timestamps may not update. This track replaces it with a robust mechanism that tracks `.git/HEAD` and the specific ref file it points to.
+
+## Functional Requirements
+- Build script must correctly detect commit changes and branch switches.
+- Replace directory-based `rerun-if-changed` with explicit file-based tracking.
+
+## Acceptance Criteria
+- `ethexe/cli/build.rs` is updated to read `.git/HEAD`.
+- If `.git/HEAD` contains a ref, the build script instructs Cargo to watch that specific ref file.
+- `cargo:rerun-if-changed=../../.git/HEAD` is maintained.

conductor/code_styleguides/general.md

@@ -0,0 +1,23 @@
+# General Code Style Principles
+
+This document outlines general coding principles that apply across all languages and frameworks used in this project.
+
+## Readability
+- Code should be easy to read and understand by humans.
+- Avoid overly clever or obscure constructs.
+
+## Consistency
+- Follow existing patterns in the codebase.
+- Maintain consistent formatting, naming, and structure.
+
+## Simplicity
+- Prefer simple solutions over complex ones.
+- Break down complex problems into smaller, manageable parts.
+
+## Maintainability
+- Write code that is easy to modify and extend.
+- Minimize dependencies and coupling.
+
+## Documentation
+- Document *why* something is done, not just *what*.
+- Keep documentation up-to-date with code changes.

conductor/index.md

@@ -0,0 +1,14 @@
+# Project Context
+
+## Definition
+- [Product Definition](./product.md)
+- [Product Guidelines](./product-guidelines.md)
+- [Tech Stack](./tech-stack.md)
+
+## Workflow
+- [Workflow](./workflow.md)
+- [Code Style Guides](./code_styleguides/)
+
+## Management
+- [Tracks Registry](./tracks.md)
+- [Tracks Directory](./tracks/)