Hive language: gallery, direct-edit checker, hive_view, live UI and euler_hive

.env.example

@@ -17,3 +17,17 @@
 # Example of a credential a live/network-gated test would need. Tests that
 # require one must skip cleanly when it is unset.
 # EXAMPLE_API_KEY=replace-me
+
+# OpenRouter key for every live model call (hive_view --live, the OpenHuman
+# examples, examples/openhuman --bin euler_hive). All inference goes here.
+# OPENROUTER_API_KEY=replace-me
+# Optional model override for those live runs.
+# OPENROUTER_MODEL=deepseek/deepseek-v4-pro
+
+# TinyHumans API key for euler_hive's non-inference modules: web search
+# through the backend's agent integrations (Parallel, Gemini grounding) via
+# the TinyHumans SDK, and CortexDB memory behind the TinyHumans backend.
+# Never used for inference.
+TINYHUMANS_API_KEY=replace-me
+# Optional TinyHumans backend origin (default https://api.tinyhumans.ai).
+# TINYHUMANS_BACKEND_URL=https://api.tinyhumans.ai

.gitignore

@@ -2,6 +2,12 @@
 /target/
 /examples/*/target/
 /examples/openhuman/workspace/
+
+# Live hive_view run artifacts (requests, replies, frames, usage). Kept out
+# of target/ so `cargo clean` does not wipe them; override with HIVE_RUNS_DIR.
+# The euler_hive example writes its runs (problem statements, transcripts,
+# sandbox programs, answers, oracles) here too; none of it may be committed.
+/hive-runs/
 **/*.rs.bk
 *.pdb
 

AGENTS.md

@@ -19,13 +19,14 @@ sees of the shared transcript.
 Three rules decide what belongs here:
 
 1. **The host owns storage.** The core mechanics open no database, file, or
-   socket. `crates/tinyhivemind-core` is a pure algebra; `crates/tinyhivemind` owns
-   *ports* a host implements. In particular there is no second
+   socket. `crates/tinyhivemind-core` is a pure algebra, and its `runtime`
+   module owns the *ports* a host implements. In particular there is no second
    append-only journal: messages are addressed by sequence number across
    surfaces the host owns, so a second log could not be made consistent with the
    first.
-2. **Keep host types at the adapter boundary.** The core, runtime, hive,
-   embed, and TypeSafe crates do not name types from a consuming application.
+2. **Keep host types at the adapter boundary.** The core crate (including its
+   `runtime`, `hive`, `embed`, `typesafe`, and `driver` modules) and
+   `tinyhivemind-lang` do not name types from a consuming application.
    They accept snapshots, borrowed views, or narrow ports. The
    `tinyhivemind-openhuman` adapter explicitly names OpenHuman types and keeps
    that dependency out of the pure crates.

README.md

@@ -155,8 +155,7 @@ option — never straight at the option:
 Every member computes an urge from the salience field and its own affinity, and
 whoever bids highest takes the floor. A member whose urge never clears its
 threshold does not bid at all. This is the response-threshold model of division
-of labour, and it is also
-[Pandemonium](https://en.wikipedia.org/wiki/Pandemonium_architecture)'s
+of labour, and it is also [Pandemonium](https://en.wikipedia.org/wiki/Pandemonium_architecture)'s
 decision demon, which is the same idea arrived at from the AI side.
 
 ```text
@@ -168,8 +167,7 @@ auditor  --                        <- threshold never cleared, does not bid
 floor = planner
 ```
 
-Every one of those is
-[fixed-point](https://en.wikipedia.org/wiki/Fixed-point_arithmetic) integer
+Every one of those is [fixed-point](https://en.wikipedia.org/wiki/Fixed-point_arithmetic) integer
 arithmetic. Every payload derives `Eq`, and every episode replays byte for byte
 from the same transcript.
 
@@ -364,7 +362,8 @@ commits the round's state after all authorized turns are appended.
 
 `tinyhivemind-lang` makes a hive’s definition editable data: roles, goals,
 seats, memory bindings and policies, with guarded patches and an evaluated
-lineage. Read the [language specification](docs/specs/hive-language.md).
+lineage. A package is a `hive.json`, Markdown prompts, and a constitution no self-edit may
+touch. Read the [language specification](docs/specs/hive-language.md), or start from the [gallery](crates/tinyhivemind-lang/examples/hives).
 
 `tinyhivemind-tools` renders native `tinytools::ToolSpec` definitions and
 records episode calls. `tinyhivemind-hives` coordinates durable messages and
@@ -452,11 +451,10 @@ the library asks the host to reinitialize instead of silently skipping history.
 No. The host owns the agent lifecycle, model calls, queueing, storage, and
 authorization. The core mention fold resolves a direct addressee; the host can
 use that decision to schedule one turn. The optional embedding layer can
-recommend a primary and bounded specialist set; the `hive` module can
-select a round inside a
-bounded deliberation. The host decides whether to run those turns, what models
-to use, what long-term memory or search to provide, and how to persist the
-result. A workspace such as Buzz could host these mechanics, but it is a
+recommend a primary and bounded specialist set; the `hive` module can select a
+round inside a bounded deliberation. The host decides whether to run those
+turns, what models to use, what long-term memory or search to provide, and how
+to persist the result. A workspace such as Buzz could host these mechanics, but it is a
 separate system with its own routing and context policy.
 
 ## Use it
@@ -467,7 +465,7 @@ git submodule add https://github.com/tinyhumansai/tinyhivemind.git vendor/tinyhi
 
 ```toml
 [dependencies]
-tinyhivemind = { path = "vendor/tinyhivemind/crates/tinyhivemind" }
+tinyhivemind-core = { path = "vendor/tinyhivemind/crates/tinyhivemind-core" }
 ```
 
 ```sh
@@ -486,6 +484,7 @@ That prints one deliberation episode turn by turn—the fastest way to see the m
 | [Cross-desk referral](https://github.com/tinyhumansai/tinyhivemind/wiki/Cross-desk-referral) | asking another channel a question, and getting the answer back |
 | [Hive episodes](https://github.com/tinyhumansai/tinyhivemind/wiki/Hive-episodes) | salience, quorum, cross-inhibition, and the attention market |
 | [Trace grammar](https://github.com/tinyhumansai/tinyhivemind/wiki/Trace-grammar) | what a marker deposits, and what real models get wrong |
+| [Hive language](https://github.com/tinyhumansai/tinyhivemind/wiki/Hive-language) | a hive as a portable package, its guarded edits, and the gallery |
 | [Episode policy](https://github.com/tinyhumansai/tinyhivemind/wiki/Episode-policy) | every setting, and how to tune it to the size of a desk |
 | [Benchmarks](https://github.com/tinyhumansai/tinyhivemind/wiki/Benchmarks) | the full report, including what it does not show |
 | [Host integration](https://github.com/tinyhumansai/tinyhivemind/wiki/Host-integration) | the ports, and what your application owes the library |

ROADMAP.md

@@ -15,11 +15,11 @@ consumer builds.
 | P1 | Chat identity: `MAIN_THREAD_ID`, `GENERAL_DESK`, `is_general_chat`, `same_conversation` | **done** |
 | P2 | Desk types, then the membership algebra behind `DeskSet<'a>` | **done** |
 | P3 | The `@` grammar, `Mention`/`MentionTarget`, and resolution over `Roster`/`Person` | **done** |
-| P4 | `crates/tinyhivemind`: the `SessionLog` port, the paging walk, and the **attributed** transcript projection | **done** |
+| P4 | The `SessionLog` port (originally `crates/tinyhivemind`, now core's `runtime` module), the paging walk, and the **attributed** transcript projection | **done** |
 | P5 | Continuous sharing — re-seed on a watermark rather than only on a rebind | **done** |
 | P6 | The responder ladder and a model-backed `Selector` port | **core plan retained**; unused waiting port retired |
 | P7 | A bounded mention-dispatch edge | **core decision retained**; unused queue wrapper retired |
-| P8 | `crates/tinyhivemind-hive`: bounded group deliberation — the trace grammar, salience, quorum with cross-inhibition, the attention market, and the episode state machine | **done** |
+| P8 | Bounded group deliberation (originally `crates/tinyhivemind-hive`, now core's `hive` module) — the trace grammar, salience, quorum with cross-inhibition, the attention market, and the episode state machine | **done** |
 | P9 | `!refute`, evidential grounding, grounded objections, and the benchmark arm that scored them | Historical experiment; refutation trace retained, losing quorum knobs retired |
 | P10 | A transactive-memory directory folded from traces, `BidReason::Knows`, and `!defer` | Directory retained for division; losing delegation and deferral paths retired |
 | P11 | `SessionMessage.parent` and the structured trace sidecar | planned |
@@ -106,9 +106,9 @@ advocate rather than debiting an option, and an attention market that ranks
 eligible speakers. A later step may authorize a bounded round of them.
 
 It adds **no port**. An episode is a pure fold, and the host does its waiting
-through the session log and turn scheduler it already implements.
-`crates/tinyhivemind-hive` is in the `pure_crates` list in
-`.github/scripts/assert-pure.sh`.
+through the session log and turn scheduler it already implements. It now
+lives in `crates/tinyhivemind-core/src/hive/`, and `tinyhivemind-core` is in
+the `pure_crates` list in `.github/scripts/assert-pure.sh`.
 
 It is also not a claim that group deliberation produces better answers. Almost
 every positive multi-agent result in the literature is confounded by compute,
@@ -158,8 +158,8 @@ epoch-scoped consent, under which a grant issued later cannot cover a request
 minted earlier. `Ask` names exactly one person, resolved through the existing
 roster and desk algebra, and never an agent.
 
-The original phase also added an `ApprovalGate` waiting port in
-`crates/tinyhivemind`. That unused wrapper has since been retired; a host
+The original phase also added an `ApprovalGate` waiting port in the former
+`crates/tinyhivemind` runtime crate. That unused wrapper has since been retired; a host
 handles the wait after the pure decision. The ADR's lasting choice is that the
 fold is total: a gate that can fail can be bypassed by failing, so `approve`
 returns no `Result` and adds no `Error` variant. See

crates/tinyhivemind-core/examples/bench/README.md

@@ -109,7 +109,7 @@ Every arm decides the same rooms from the same private evaluations.
 
 | arm | what it is |
 | --- | --- |
-| `ladder` | Today's behaviour: `responder_plan` in `tinyhivemind` selects one responder off the real ladder and that agent answers alone. One deliberation turn — but two model calls when the ladder takes the `Select` rung, since the router has to be asked who answers before anybody does, and the two are sequential. |
+| `ladder` | Today's behaviour: `responder_plan` in `tinyhivemind-core` selects one responder off the real ladder and that agent answers alone. One deliberation turn — but two model calls when the ladder takes the `Select` rung, since the router has to be asked who answers before anybody does, and the two are sequential. |
 | `vote` | The honest matched-budget control — independent answers decided by plurality, nobody seeing anybody. It is given the *whole* budget, more turns than the deliberation actually spends. |
 | `hive` | A deliberation episode at `EpisodePolicy::DEFAULT`. |
 | `hive+` | The same, at the tuned policy: a majority quorum that is never unanimity, and three turns of budget per member. |

crates/tinyhivemind-core/examples/bench/arms.rs

@@ -6,7 +6,7 @@
 //! arms over the *same* rooms and the same private evaluations:
 //!
 //! - **ladder** — today's behaviour. One message selects exactly one responder
-//!   off the deterministic ladder in `tinyhivemind`, that agent answers, and the
+//!   off the deterministic ladder in `tinyhivemind-core`, that agent answers, and the
 //!   interaction ends. One turn.
 //! - **vote** — self-consistency at a matched turn budget. The same number of
 //!   turns the episode was allowed, each spent on one member's independent

crates/tinyhivemind-core/examples/bench/cli/README.md

@@ -0,0 +1,10 @@
+# `cli/`
+
+Command-line parsing for the bench binary. The flag table itself is in
+`main.rs`'s crate doc.
+
+| File | Purpose |
+| --- | --- |
+| `mod.rs` | `Options`, the parsed argument set every other module reads, and `Mode`, what `--sweep`, `--trace`, `--swarm` and the other modes pick between. |
+| `flags.rs` | The per-flag handlers `Options::parse` delegates to, grouped by what they configure: scale, expertise, and the live backends. |
+| `test.rs` | Flag parsing regressions: fidelity and fact-noise validation, and how `--api-base` interacts with the explicit modes. |

crates/tinyhivemind-core/examples/bench/horizon/README.md

@@ -0,0 +1,10 @@
+# `horizon/`
+
+The long-horizon sweep (`--stages N`): a chain of sub-decisions decided by the
+same members, where context accumulates and a wrong stage poisons the next.
+See [`../HORIZON.md`](../HORIZON.md) for the method.
+
+| File | Purpose |
+| --- | --- |
+| `mod.rs` | The staged rooms, the `solo`, `solo+fold`, `hive+` and `hive+pooled` arms, and the end-to-end report. |
+| `test.rs` | Distinct option names per stage, inherited windows, poisoning, the soloist's whole brief, and that a chain is never likelier than one of its stages. |

crates/tinyhivemind-core/examples/bench/live_swarm/README.md

@@ -0,0 +1,10 @@
+# `live_swarm/`
+
+Driving a live federation of desks (`--swarm`) through a real backend: several
+desks, each seated over a CLI agent or the HTTP backend, that reach each other
+only through a referral. See [`../SWARM.md`](../SWARM.md).
+
+| File | Purpose |
+| --- | --- |
+| `mod.rs` | The drivers: what runs, from simulated federations to live desks and one traced episode. |
+| `totals.rs` | What a federated comparison counts and how it prints: per-arm outcomes, running totals, the arm fan-out, and the table. |

crates/tinyhivemind-core/examples/bench/main.rs

@@ -19,7 +19,7 @@
 //! the right answer is to pool what its members separately believe. Four arms
 //! decide the same rooms from the same private evaluations:
 //!
-//! - `ladder` — the responder ladder in `tinyhivemind` selects one responder and
+//! - `ladder` — the responder ladder in `tinyhivemind-core` selects one responder and
 //!   that agent answers alone. One turn. This is today's behaviour.
 //! - `vote` — the honest matched-budget control: independent answers decided by
 //!   plurality, with nobody seeing anybody. It is given the whole budget, which

crates/tinyhivemind-core/examples/bench/parallel/README.md

@@ -0,0 +1,8 @@
+# `parallel/`
+
+Tests for [`../parallel.rs`](../parallel.rs), the scoped-thread fan-out that
+spreads per-room loops across cores without changing a number.
+
+| File | Purpose |
+| --- | --- |
+| `test.rs` | Results come back in input order at every job count and whatever order threads finish in; the first error in input order is reported; short slices, panicking closures, and the mutable map are covered. |

crates/tinyhivemind-core/examples/bench/scenario/README.md

@@ -0,0 +1,9 @@
+# `scenario/`
+
+Tests for [`../scenario.rs`](../scenario.rs), the file format for a real
+problem a live room solves, with the private facts behind it. The shipped
+scenarios live in [`../scenarios/`](../scenarios/).
+
+| File | Purpose |
+| --- | --- |
+| `test.rs` | Every shipped scenario parses, records an answer that is on offer, and gives every member something of its own. |

crates/tinyhivemind-core/examples/bench/swarm/format/README.md

@@ -0,0 +1,8 @@
+# `swarm/format/`
+
+Tests for [`../format.rs`](../format.rs), the wire text a swarm's members
+exchange across a referral and the trace line a run keeps.
+
+| File | Purpose |
+| --- | --- |
+| `test.rs` | Reading and fact clauses round-trip without disturbing each other, several desks can rule out several options, and an unowned disqualification is dropped. |

crates/tinyhivemind-core/examples/bench/variety/README.md

@@ -0,0 +1,10 @@
+# `variety/`
+
+The variety sweep (`--facets F`): one task made of several independent
+sub-decisions at once, each needing a different kind of attention. See
+[`../VARIETY.md`](../VARIETY.md).
+
+| File | Purpose |
+| --- | --- |
+| `mod.rs` | The faceted rooms, facet ownership, the arms, and the all-facets report. |
+| `test.rs` | Distinct option names per facet and against stages, owners reading their facet more tightly, and what one seat holds against a soloist. |

crates/tinyhivemind-core/examples/driver_bench/README.md

@@ -1,4 +1,4 @@
-# `bench`
+# `driver_bench`
 
 What the completion driver's policy costs, measured rather than asserted, with
 no model and no credential.
@@ -9,8 +9,8 @@ no model and no credential.
 | `sim.rs` | a stochastic room whose turns land at different times, and a router that returns well-formed evaluations so real acceptance runs |
 
 ```sh
-cargo run --release -p tinyhivemind-openhuman --example bench
-cargo run --release -p tinyhivemind-openhuman --example bench -- --episodes 2000 --members 8
+cargo run --release -p tinyhivemind-core --example driver_bench
+cargo run --release -p tinyhivemind-core --example driver_bench -- --episodes 2000 --members 8
 ```
 
 Every arm runs the same seeded rooms through the same `CompletionDriver`, so a

crates/tinyhivemind-core/src/aside/README.md

@@ -29,7 +29,7 @@ imposes no ceiling on members or messages, and `must_surface` and
 Two rules give the mechanism its shape and neither is enforced here, because
 neither is a decision this fold could make:
 
-- **A redaction is a row, not an absence.** `tinyhivemind`'s projection elides
+- **A redaction is a row, not an absence.** The runtime's projection elides
   content and keeps the row, so a reader outside an audience still sees that
   the exchange happened, who wrote it and to whom. That is what makes an aside
   auditable rather than a covert channel.

crates/tinyhivemind-core/src/driver/conduct/test/README.md

@@ -0,0 +1,15 @@
+# `driver/conduct/test/`
+
+Unit tests for the conductor, driven by a host that is only an in-memory
+journal. `mod.rs` declares the behaviour groups below; each file is one group.
+
+| File | Purpose |
+| --- | --- |
+| `mod.rs` | Module doc and the submodule declarations. |
+| `support.rs` | Shared fixtures: a hive of named seats, a router that always asks for clarification, the journal, and one wave driven the way a host drives it. |
+| `door.rs` | Who starts an episode: routed starters, a task at sequence zero, refused starters, and every plan shape. |
+| `desk.rs` | Desk work: stalled-seat nudges, placed and unplaced broadcasts, handoffs, the broadcast budget, the turn wall, and the commit protocol. |
+| `conversations.rs` | Conversations opened by an ask: running first, concluding to the asker, group asks, silent askees, refused replies, and thread prefetch. |
+| `parked.rs` | Parked seats held by the host, released where they stopped, and snapshots taken and refused between waves. |
+| `links.rs` | The links a host reads back to draw the desk: conversation roots on rows, and the rows events name. |
+| `wire.rs` | Pinned wire forms of turns, notes, commits, events, refusals, snapshots, and the conduct policy. |

crates/tinyhivemind-core/src/driver/engine/brief/README.md

@@ -0,0 +1,8 @@
+# `driver/engine/brief/`
+
+Tests for [`../brief.rs`](../brief.rs), which renders what the episode itself
+has to tell a seat before its turn.
+
+| File | Purpose |
+| --- | --- |
+| `test.rs` | The brief says what the episode knows and only that: the assignment and the parent a seat must name, concluded and in-progress conversations with their transcripts, thread and group-thread briefs, the standing contract, elsewhere context, and naming seats by name or id. |

crates/tinyhivemind-core/src/hive/exchange/README.md

@@ -74,7 +74,7 @@ folded; rounds are carried", below, for why that one cannot come out of the log.
 which members it names, and how many rows the episode may still write. It does
 no waiting and **chooses no peer**: who a member wants to contact is that
 member's judgement, and the audience it writes is validated by
-`tinyhivemind::aside::aside` exactly as an aside riding alongside a turn is.
+`tinyhivemind_core::aside::aside` exactly as an aside riding alongside a turn is.
 
 `ExchangeRound::Open::members` is in desk order and contains only members that
 are active on the episode's desk and still under their own contact cap. A host

crates/tinyhivemind-core/src/runtime/README.md

@@ -1,4 +1,4 @@
-# `tinyhivemind` feature modules
+# `runtime` feature modules
 
 One directory per feature area, wired together and re-exported from
 [`mod.rs`](mod.rs). Each answers a different question a host needs answered

crates/tinyhivemind-core/src/runtime/error/README.md

@@ -4,7 +4,7 @@ The crate-wide `Error` and `Result<T>`.
 
 ## Why it exists
 
-Every fallible public function in `tinyhivemind` returns the same `Result<T>`,
+Every fallible public function in core's `runtime` module returns the same `Result<T>`,
 so a host writes one match arm, not one per module. The enum names the ways a
 *host* implementation of a port can violate its contract, including bad
 pages and stale cursors. It also reports an overflowing present set, a digest

crates/tinyhivemind-core/tests/migrated_runtime/README.md

@@ -1,6 +1,6 @@
 # Runtime integration tests
 
-These tests use only the public `tinyhivemind` API.
+These tests use only the public `tinyhivemind_core::runtime` API.
 
 | File | Coverage |
 | --- | --- |