Echo/wasm spec 000 scaffold #141

flyingrobots · 2025-12-11T22:09:37Z

Echo is becoming JITOS kernel

Adds spec 0000 scaffold

Specs will be:

Documentation
Interactive Onboarding Demos
Rust + WASM + WW + TS
JITOS Contributor Certification Materials
Live Tests

This sets up the foundation to build these specs.

coderabbitai · 2025-12-11T22:09:46Z

Summary by CodeRabbit

Release Notes

New Features
- Added WebSocket-to-Unix socket gateway enabling browser clients to connect to the session hub with TLS support and origin filtering.
- Introduced WASM-based living specs runner for in-browser kernel testing and validation.
- Enhanced error handling with structured error responses for unauthorized RMG publishes and protocol violations.
Documentation
- Added comprehensive methodology guide and RMG View Protocol specification.
- Updated scripting integration examples and architecture documentation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

This PR introduces a WebSocket-to-Unix-socket gateway for session management with frame validation and optional TLS, enforces single-producer semantics on RMG streams with structured error handling in the session service, adds a WASM-based living specification framework using Leptos+Trunk, pivots scripting documentation from Lua to Rhai throughout, and establishes engineering standards including the JITOS kernel branding and methodology documentation.

Changes

Cohort / File(s)	Summary
WebSocket Gateway – New Crate `crates/echo-session-ws-gateway/Cargo.toml`, `crates/echo-session-ws-gateway/README.md`, `crates/echo-session-ws-gateway/src/main.rs`	Adds a new Tokio+Axum WebSocket-to-Unix-socket bridge with configurable TLS, origin filtering, 12-byte framing protocol (4-byte length header, 32-byte trailer), max payload guards (8 MiB default), graceful shutdown on Ctrl-C, per-connection task spawning for WS reader/writer and UDS reader/writer, and ping/pong keepalive.
RMG Stream Authority Enforcement `crates/echo-session-service/src/main.rs`, `crates/echo-session-client/src/lib.rs`	Adds per-RmgId producer ownership validation in session service; rejects non-owner publishes with E_FORBIDDEN_PUBLISH (403); enforces snapshot→diff sequencing and epoch/hash continuity; forwards error payloads to initiating connection and broadcasts valid frames. Client now surfaces error messages as local notifications with kind NotifyKind::Error.
WASM Living Spec Scaffold (spec-000) `specs/spec-000-rewrite/Cargo.toml`, `specs/spec-000-rewrite/README.md`, `specs/spec-000-rewrite/index.html`, `specs/spec-000-rewrite/src/lib.rs`	Adds Leptos+Trunk CSR scaffold with epoch-counter component, dark-themed HTML layout, WASM entry point, and make targets (`spec-000-dev`, `spec-000-build`); establishes a living specification runner embedded in the browser.
Workspace & Build Configuration `Cargo.toml`, `Makefile`	Adds `crates/echo-session-ws-gateway` and `specs/spec-000-rewrite` to workspace members; introduces `spec-000-dev` (runs `trunk serve`) and `spec-000-build` (runs `trunk build --release`) phony targets.
Scripting Runtime Pivot: Lua → Rhai `crates/rmg-ffi/Cargo.toml`, `crates/rmg-ffi/README.md`, `crates/rmg-ffi/src/lib.rs`, `docs/rmg-demo-roadmap.md`, `docs/rmg-runtime-architecture.md`, `docs/roadmap-mwmr-mini-epic.md`, `docs/rust-rhai-ts-division.md`, `docs/spec-concurrency-and-authoring.md`, `docs/spec-mwmr-concurrency.md`, `docs/spec-networking.md`, `docs/spec-rmg-core.md`	Systematically replaces Lua references with Rhai across documentation and package descriptions; updates code examples from Lua syntax to Rhai syntax (e.g., `{entity = id}` → `#{ entity: id }`); reflects Rhai as the deterministic scripting layer for gameplay authoring.
Engineering Standards & Methodology `CONTRIBUTING.md`, `README.md`, `docs/METHODOLOGY.md`, `docs/decision-log.md`, `docs/execution-plan.md`, `docs/phase1-plan.md`, `docs/spec-rmg-view-protocol.md`, `docs/tasks.md`, `WASM-TASKS.md`	Adds JITOS kernel branding, METHODOLOGY.md detailing 5x Duty living-spec workflow, expanded decision log with authority/gateway/Rhai decisions, marks three RMG View Protocol tasks as completed (define protocol, generalize as EIP, enforce authority), expands task list with viewer dirty-flag sync, pub/sub toggles, and integration testing.

Sequence Diagram

sequenceDiagram
    autonumber
    actor Pub as Publisher<br/>(Client 1)
    participant SS as Session Service
    actor Sub as Subscriber<br/>(Client 2)
    
    rect rgba(150, 200, 200, 0.2)
    note over Pub,Sub: Ownership Enforcement: Valid Publisher
    Pub->>SS: Message::RmgStream<br/>(Snapshot, rmg_id=X)
    SS->>SS: Check: producer set?<br/>No → assign Pub
    SS->>SS: Validate snapshot state<br/>(epoch, hash)
    SS->>Sub: Broadcast RmgStream<br/>(fresh timestamp)
    SS->>Pub: Implicit ack<br/>(frame accepted)
    end
    
    rect rgba(200, 150, 150, 0.2)
    note over Pub,Sub: Ownership Enforcement: Non-Owner Rejected
    actor Attacker as Attacker<br/>(Client 3)
    Attacker->>SS: Message::RmgStream<br/>(Diff, rmg_id=X)
    SS->>SS: Check: producer set?<br/>Yes, != Attacker
    SS->>Attacker: Message::Error<br/>(E_FORBIDDEN_PUBLISH, 403)
    SS--XSub: (frame rejected,<br/>no broadcast)
    end
    
    rect rgba(200, 200, 150, 0.2)
    note over Pub,Sub: Client: Error Notification Flow
    Attacker->>Attacker: Recv Message::Error
    Attacker->>Attacker: Convert to Notification<br/>(NotifyKind::Error,<br/>NotifyScope::Local)
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50–75 minutes

Areas requiring careful attention:

crates/echo-session-ws-gateway/src/main.rs: Frame parsing logic (12-byte header with 4-byte length at offset 8, 32-byte trailer validation), TLS configuration/loading, per-client task spawning (reader/writer/keepalive), origin filtering, Unix socket connection error handling, and graceful shutdown coordination.
crates/echo-session-service/src/main.rs: RmgStream ownership enforcement (per-connection producer tracking, E_FORBIDDEN_PUBLISH rejection, epoch/hash validation logic, snapshot↔diff sequencing); new error payload construction; ensure error responses don't bypass the connection check.
specs/spec-000-rewrite/src/lib.rs: Leptos component correctness, WASM entry point (panic hook setup), signal state management, and JSX rendering logic.
Heterogeneous changes: Documentation Lua→Rhai substitutions are repetitive but numerous; spot-check a few to ensure terminology consistency, especially in executable examples (spec-concurrency-and-authoring.md, spec-networking.md, spec-rmg-core.md).

Possibly related PRs

Rmg viewer #138 — Modifies the same RMG/session/viewer stack (session service, session client, protocol definitions), indicating parallel or sequential work on the streaming and viewer architecture.

🚀 A gateway opens wide, three clients now collide,
One rules the stream with might, two others turned aside—
From Lua's ancient tongue we pivot to Rhai's flame,
A WASM-born spec runner joins the coding game! 🎪✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 69.23% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the primary change: introducing a WASM spec-000 scaffold with new crate infrastructure, documentation, and build targets.
Description check	✅ Passed	The description directly relates to the changeset by explaining the strategic context (JITOS kernel) and the purpose of the scaffold, aligning with the extensive documentation and structural additions.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch echo/wasm-spec-000-scaffold

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Signed-off-by: James Ross <[email protected]>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

specs/spec-000-rewrite/src/lib.rs

crates/echo-session-ws-gateway/src/main.rs

coderabbitai

Actionable comments posted: 20

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

docs/rust-rhai-ts-division.md (1)

5-76: LGTM: Comprehensive Rhai pivot with minor formatting issues.

The document consistently replaces Lua with Rhai across all layers (runtime stack, gameplay authoring, bindings, tooling). The technical division remains sound.

Minor formatting issue: markdownlint flags missing blank lines around headings at lines 22, 32, 38, and 43. While not critical, fixing these improves markdown standards compliance.

Apply this diff to fix heading spacing:
 - `rmg-cli` – CLI utilities
 
 ---
+
 ## Rhai (gameplay authoring layer)
 
 ### Responsibilities
(Repeat pattern for other flagged headings at lines 32, 38, 43)

crates/echo-session-service/src/main.rs (1)

455-557: Refactor authorization logic for clarity.

The RmgStream handler consolidates ownership checks, epoch validation, and broadcast logic in a deeply nested structure spanning 100+ lines. While functionally correct, the cognitive complexity is high.

Consider extracting validation into dedicated functions:

validate_producer_authority(stream, conn_id, rmg_id) -> Result<(), ErrorPayload>
validate_frame_sequence(stream, frame) -> Result<(), ErrorPayload>

This would:

Reduce nesting (currently 4-5 levels)
Make error paths testable in isolation
Improve readability of the happy path
Allow reuse if other message types need similar validation

Example extraction:

fn validate_producer_authority(
    stream: &StreamState,
    conn_id: u64,
    rmg_id: RmgId,
) -> Result<(), ErrorPayload> {
    if let Some(p) = stream.producer {
        if p != conn_id {
            return Err(ErrorPayload {
                code: 403,
                name: "E_FORBIDDEN_PUBLISH".into(),
                details: None,
                message: format!("rmg_id {} is owned by {}", rmg_id, p),
            });
        }
    }
    Ok(())
}

fn validate_frame_sequence(
    stream: &mut StreamState,
    frame: &RmgFrame,
) -> Result<(), ErrorPayload> {
    match frame {
        RmgFrame::Snapshot(s) => {
            stream.last_epoch = Some(s.epoch);
            stream.last_hash = s.state_hash;
            stream.latest_snapshot = Some(s.clone());
            Ok(())
        }
        RmgFrame::Diff(d) => {
            let last = stream.last_epoch.ok_or_else(|| ErrorPayload {
                code: 409,
                name: "E_RMG_SNAPSHOT_REQUIRED".into(),
                details: None,
                message: "send a snapshot before the first diff".into(),
            })?;
            
            if d.from_epoch != last || d.to_epoch != d.from_epoch + 1 {
                return Err(ErrorPayload {
                    code: 409,
                    name: "E_RMG_EPOCH_GAP".into(),
                    details: None,
                    message: format!(
                        "expected {}->{} but got {}->{}",
                        last, last + 1, d.from_epoch, d.to_epoch
                    ),
                });
            }
            
            stream.last_epoch = Some(d.to_epoch);
            stream.last_hash = d.state_hash;
            Ok(())
        }
    }
}

Then the main handler simplifies to:

Message::RmgStream { rmg_id, frame } => {
    let (subs, pkt) = {
        let mut h = hub.lock().await;
        let stream = h.streams.entry(rmg_id).or_default();
        
        // Validate producer
        if let Err(payload) = validate_producer_authority(stream, conn_id, rmg_id) {
            let tx = h.conns.get(&conn_id).map(|c| c.tx.clone());
            let ts = h.alloc_ts();
            if let Some(tx) = tx {
                let pkt = encode_message(Message::Error(payload.clone()), ts)?;
                let _ = tx.send(pkt).await;
            }
            anyhow::bail!("producer authorization failed");
        }
        
        // Validate and update sequence
        if let Err(payload) = validate_frame_sequence(stream, &frame) {
            let tx = h.conns.get(&conn_id).map(|c| c.tx.clone());
            let ts = h.alloc_ts();
            if let Some(tx) = tx {
                let pkt = encode_message(Message::Error(payload.clone()), ts)?;
                let _ = tx.send(pkt).await;
            }
            anyhow::bail!("frame sequence validation failed");
        }
        
        // Set producer if first publish
        if stream.producer.is_none() {
            stream.producer = Some(conn_id);
        }
        
        let subs = stream.subscribers.clone();
        let ts = h.alloc_ts();
        let pkt = encode_message(Message::RmgStream { rmg_id, frame }, ts)?;
        (subs, pkt)
    };
    
    let h = hub.lock().await;
    for sub in subs {
        if let Some(conn) = h.conns.get(&sub) {
            let _ = conn.tx.send(pkt.clone()).await;
        }
    }
}

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1627b79 and 35b06d7.

⛔ Files ignored due to path filters (3)

Cargo.lock is excluded by !**/*.lock
assets/echo-white-2.svg is excluded by !**/*.svg
assets/echo-white.svg is excluded by !**/*.svg

📒 Files selected for processing (31)

CONTRIBUTING.md (2 hunks)
Cargo.toml (1 hunks)
Makefile (1 hunks)
README.md (4 hunks)
WASM-TASKS.md (1 hunks)
crates/echo-session-client/src/lib.rs (2 hunks)
crates/echo-session-service/src/main.rs (3 hunks)
crates/echo-session-ws-gateway/Cargo.toml (1 hunks)
crates/echo-session-ws-gateway/README.md (1 hunks)
crates/echo-session-ws-gateway/src/main.rs (1 hunks)
crates/rmg-ffi/Cargo.toml (1 hunks)
crates/rmg-ffi/README.md (1 hunks)
crates/rmg-ffi/src/lib.rs (1 hunks)
docs/METHODOLOGY.md (1 hunks)
docs/decision-log.md (1 hunks)
docs/execution-plan.md (3 hunks)
docs/phase1-plan.md (5 hunks)
docs/rmg-demo-roadmap.md (2 hunks)
docs/rmg-runtime-architecture.md (1 hunks)
docs/roadmap-mwmr-mini-epic.md (1 hunks)
docs/rust-rhai-ts-division.md (3 hunks)
docs/spec-concurrency-and-authoring.md (3 hunks)
docs/spec-mwmr-concurrency.md (1 hunks)
docs/spec-networking.md (2 hunks)
docs/spec-rmg-core.md (1 hunks)
docs/spec-rmg-view-protocol.md (1 hunks)
docs/tasks.md (1 hunks)
specs/spec-000-rewrite/Cargo.toml (1 hunks)
specs/spec-000-rewrite/README.md (1 hunks)
specs/spec-000-rewrite/index.html (1 hunks)
specs/spec-000-rewrite/src/lib.rs (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.rs

📄 CodeRabbit inference engine (AGENTS.md)

Every source file must start with exactly // SPDX-License-Identifier: Apache-2.0 and // © James Ross Ω FLYING•ROBOTS <https://github.com/flyingrobots>

Files:

specs/spec-000-rewrite/src/lib.rs
crates/echo-session-client/src/lib.rs
crates/rmg-ffi/src/lib.rs
crates/echo-session-ws-gateway/src/main.rs
crates/echo-session-service/src/main.rs

🧠 Learnings (13)

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Consult `docs/architecture-outline.md` before touching runtime code in `packages/echo-core`

Applied to files:

docs/rust-rhai-ts-division.md
README.md
docs/spec-concurrency-and-authoring.md
CONTRIBUTING.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Applies to packages/echo-core/src/**/*.rs : Tests and benchmarks are mandatory for runtime changes once the harness exists

Applied to files:

docs/rust-rhai-ts-division.md
specs/spec-000-rewrite/Cargo.toml
Cargo.toml
README.md
crates/echo-session-ws-gateway/Cargo.toml
docs/spec-concurrency-and-authoring.md
docs/phase1-plan.md
crates/rmg-ffi/Cargo.toml
CONTRIBUTING.md
docs/execution-plan.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Applies to packages/echo-core/src/**/*.rs : Public APIs across crates (`rmg-core`, `rmg-ffi`, `rmg-wasm`) must carry rustdoc comments explaining intent, invariants, and usage

Applied to files:

docs/rust-rhai-ts-division.md
specs/spec-000-rewrite/Cargo.toml
Cargo.toml
README.md
crates/echo-session-ws-gateway/Cargo.toml
crates/rmg-ffi/src/lib.rs
crates/rmg-ffi/Cargo.toml
docs/tasks.md
crates/echo-session-ws-gateway/src/main.rs
crates/rmg-ffi/README.md
CONTRIBUTING.md
crates/echo-session-ws-gateway/README.md
docs/execution-plan.md
crates/echo-session-service/src/main.rs

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Applies to packages/echo-core/src/**/*.rs : Respect determinism: preferably use Echo PRNG instead of random seeds without mitigation

Applied to files:

docs/rust-rhai-ts-division.md
specs/spec-000-rewrite/Cargo.toml
README.md
docs/spec-concurrency-and-authoring.md
crates/rmg-ffi/README.md
CONTRIBUTING.md
docs/execution-plan.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Formatting is auto-fixed with `cargo fmt` by default; set `ECHO_AUTO_FMT=0` to run check-only

Applied to files:

README.md
crates/rmg-ffi/Cargo.toml
CONTRIBUTING.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Keep `main` pristine; feature work belongs on branches named `echo/<feature>` or `timeline/<experiment>`

Applied to files:

README.md
CONTRIBUTING.md
docs/execution-plan.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Run `cargo clippy --all-targets -- -D missing_docs` and `cargo test` before every PR

Applied to files:

README.md
CONTRIBUTING.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Capture milestones, blockers, and decisions in `docs/decision-log.md`, relevant specs, or PR descriptions

Applied to files:

docs/decision-log.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Record outcomes and next steps in `docs/decision-log.md` and ensure impacted docs stay in sync when wrapping up a session

Applied to files:

docs/decision-log.md
docs/phase1-plan.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Every meaningful design choice should be documented in `docs/` (specs, diagrams, memorials) or `docs/decision-log.md`

Applied to files:

docs/decision-log.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: When a PR touches non-doc code, update `docs/execution-plan.md` and `docs/decision-log.md` in the same PR

Applied to files:

CONTRIBUTING.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Applies to **/*.rs : Every source file must start with exactly `// SPDX-License-Identifier: Apache-2.0` and `// © James Ross Ω FLYING•ROBOTS <https://github.com/flyingrobots>`

Applied to files:

CONTRIBUTING.md

📚 Learning: 2025-12-10T11:22:22.785Z

Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-10T11:22:22.785Z
Learning: Start each session by updating *Today's Intent* in `docs/execution-plan.md`

Applied to files:

docs/execution-plan.md

🧬 Code graph analysis (1)

crates/echo-session-service/src/main.rs (1)

crates/echo-session-proto/src/wire.rs (2)

decode_message (263-292)

encode_message (232-260)

🪛 checkmake (0.2.2)

Makefile

[warning] 131-131: Missing required phony target "all"

(minphony)

[warning] 131-131: Missing required phony target "clean"

(minphony)

[warning] 131-131: Missing required phony target "test"

(minphony)

🪛 LanguageTool

docs/spec-rmg-view-protocol.md

[grammar] ~40-~40: Ensure spelling is correct
Context: ...se) and clear dirty on success; retry/backoff on error. - Subscriptions: apply incomi...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

README.md

[grammar] ~11-~11: Ensure spelling is correct
Context: ...nstead of hopes and prayers. > > THE REVΩLUTION WILL BE DETERMINISTIC. > **THE PROO...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)

specs/spec-000-rewrite/README.md

9-9: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

15-15: Bare URL used

(MD034, no-bare-urls)

19-19: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

23-23: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below