flying-jib/living_docs/PROGRESS.md

Flying Jib — Progress Log

Append-only chronological log of decisions, blockers, and wins. Newest entries at the top.

---

2026-07-30 — Phase 3 chat/presence + standalone binary

Wins

• lib/peer-session.js — Hyperswarm + Protomux (flying-jib/presence|chat|control)
• CLI host/join: stdin chat, /peers, --name display name
• Peer chat integration test
• scripts/bare-standalone.cjs peardock-style pack; standalone binary runs Squid on 127.0.0.1 with PATH without Node
• Postinstall patches: static Squid plugins, log.js bare-pack fixes, events polyfill vendor

Notes

• Standalone ~500MB; size optimization later
• Dev path bare-runtime/bin/bare bin.mjs remains preferred for iteration

Next

• Multi-host make:standalone:all in CI
• Phase 4 mesh
• Java multiplayer playtest

---

2026-07-30 — Phase 2 core: HyperDHT tunnel + fj1. invites

Wins

• lib/world-tunnel.js — host/client HyperDHT TCP pipes with capability header (FJ1C||cap)
• lib/invite.js — fj1. z32 JSON invites (ADR-0009)
• lib/tunnel-keys.js — per-world tunnel seed/cap on disk (mode 0600)
• CLI: host (Squid + share) and join (client tunnel)
• Tests: invite codec + tunnel integration (10/10)
• Bare CLI smoke: host prints invite; guest binds 127.0.0.1; both listen

Next

• bare-build standalone
• Java Edition multiplayer playtest
• Phase 3 presence/chat

---

2026-07-30 — Phase 1: Bare CLI + Flying Squid on loopback

Wins

• Scaffolded Bare app: bin.mjs, app.js, lib/*, plugins/fj-bind-guard.js, pear worker stub, package.json imports.
• CLI: create, list, start, status with --storage.
• Flying Squid runs under Bare (node_modules/bare-runtime/bin/bare) listening on 127.0.0.1 (verified via lsof).
• Also verified under Node for local iteration.
• Unit tests for bind-guard + worlds pass.
• Bare interop tooling: scripts/patch-engines-for-bare.js, scripts/generate-squid-imports.js, shims for events (callable EE) and readline.

Decisions

• Squid in main Bare process (not Node child) per ADR-0013.
• Use bare-runtime from node_modules for dev when system bare is too old.

Next

• bare-build standalone package smoke
• Java Edition join playtest
• Phase 2 tunnel

---

2026-07-30 — ADR-0013: Bare/Pear-only runtime and single-executable distribution

Wins

• Accepted ADR-0013: production runtime is Bare only; no system Node.js; no Node child for Squid.
• Superseded ADR-0004 (Electron + Node Squid child) and primary Electron Forge path in ADR-0011.
• Amended ADR-0002: Flying Squid loads via bare-node-runtime inside Bare.
• Updated living, developer, user, and agent docs for hello-pear-bare + bare-build --standalone + Pear OTA.
• Added open question Q15 (Squid/Bare compatibility spike).

Decisions

• CI product = single standalone Bare executables + pear stage/seed OTA.
• Electron is not the default shell; Node is build-time tooling only where unavoidable.

Next

• Phase 1: scaffold hello-pear-bare; Bare Squid spike.

---

2026-07-30 — Phase 0 complete: research + architecture + docs scaffold

Wins

• Inventoried Holepunch mirror at holepunchto_repos (~680 packages); selected stack versions for hyperswarm, hyperdht, corestore, autobase, protomux, pear-runtime, etc.
• Assessed Flying Squid (createMCServer, plugins, Anvil, versions through 1.21.4) as embeddable local authority — not global multi-peer sim.
• Studied peardock (control plane + invites) and holesail (TCP tunnel pattern); decided Apache-2.0 HyperDHT tunnel instead of AGPL Holesail dependency.
• Locked architecture: Local Authority + Capability Tunnel + Federated Regions.
• Product name: Flying Jib.
• Scaffolded full living_docs/, developer_docs/, user_docs/, agent/ including ADRs 0000–0012 (later extended by 0013).

Decisions

• No master/central servers ever; discovery only via Hyperswarm/HyperDHT.
• Squid always binds 127.0.0.1 (explicit; minecraft-protocol default is all interfaces).
• Process model initially hybrid; revised same day to Bare/Pear-only (ADR-0013).
• Private worlds: HyperDHT byte pipe; invites fj1..
• Mesh: Autobase region registry; border = session migration, not global block CRDT.
• License: Apache-2.0.

Blockers

• None for Phase 0 docs.

Next

• Phase 1: Bare app shell + Squid on bare-node-runtime.

---

2026-07-30 — Investigation kickoff

• Empty repo flying-jib initialized as documentation-first project.
• Primary references: Prismarine flying-squid, full Holepunch ecosystem, local peardock/holesail experience.