[W5.8] cli: the demo and ping binaries

Unit W5.8 of docs/PLAN.md.

The demo node and the ping node: the composition wiring as running code that documents it (§2). The ordered lists are assembled here and nowhere below.

Where the spec lives

The unit row: root docs/PLAN.md — the deliverable, the dependencies, the priority.
The frozen interfaces: root docs/ARCHITECTURE.md, §3 (the mechanisms) and §2 (this package).
The package's own docs: packages/cli/docs/ARCHITECTURE.md and its PLAN.md — read them first; they refine the root docs and never contradict them.
The reference: the spike branch, Main.lean and PingNode.lean (ARCHITECTURE §7). Read it before you implement. Port its tests, keep the wire bytes; the code shape follows §3, not the spike's internals (§7 preamble, §9).

Your freedom, and its cost

The docs govern, and they are yours to change. Where a better design exists, change it — and change the documents in the same pull request. A contract change starts at the root docs/ARCHITECTURE.md; the package docs follow it in the same change. Code that disagrees with the docs, or package docs that disagree with the root, does not merge.

Definition of done

The public surface follows ARCHITECTURE §4; the owned contracts hold.
The end-to-end demo over loopback: two hosts dial, ping, identify, and close through the full shutdown order.
The carried vector and property tests pass through the Tests suite.
lake build, lake test, and lake test -- +RTS -N1 -RTS are green; scripts/lint-imports.sh is green.
No sorry, no build warnings (CLAUDE.md, "Strict checking").
First submodule under your leaf? Widen the lib's globs in lakefile.toml in the same commit.

Depends on

[W5.7] libp2p/protocols: identify and ping #20 (W5.7) — blocking.

Every issue is claimable from day one; you build ahead of open dependencies against mocks of their frozen interfaces (RULES.md, "Working ahead of the tree").

Ground rules

Comment claim to take the issue; an organiser assigns it. One issue at a time.
A pull request within 8 hours of the assignment; drafts count. Link the issue (Closes #N). Miss the window, lose the claim.
Target the hackathon26 branch.
The license-acceptance line of the PR description stays ticked; commits carry no AI co-author trailers. Two guards fail the PR otherwise.
Prose register everywhere: CLAUDE.md, "Writing Style".
A contract question the docs do not settle: ask on this issue before you code past it.

The W4.2 pull request (#47) changes the TCP close discipline of root ARCHITECTURE §4.7, which the Connection of net/streams carries to every layer above it.

close sends a FIN when no write is in flight, and an RST when one is. On v4.34, a write to a peer that stops reading never completes. libuv's shutdown waits behind it, and the write request holds the socket and its descriptor. A C shim in net/streams ends such a connection, and the peer gets an RST. A failed write follows the same rule.
A read that meets the peer's RST answers none, the end-of-stream channel of §3.5. go-libp2p closes every TCP connection with an RST (linger 0, vendor/go-libp2p/p2p/transport/tcp/tcp.go, lines 278 to 281), so a session with a go node ends this way.

The Connection type and its fields stay the same. The net/streams ARCHITECTURE, "Decisions", records both rules with their sources.

claim

#60 (W5.9) touches two docs this unit builds on.

packages/libp2p/host/docs/ARCHITECTURE.md gains newStream (h : Host) (peer : PeerId) (protocols : List ProtocolId), the outbound stream call, answered with the selected id and the stream. With no live session, it dials the peer first. It is go-libp2p's host.NewStream (vendor/go-libp2p/core/host/host.go, lines 61 to 65). The demo and the ping node open their streams through it.
packages/cli/docs/ARCHITECTURE.md and PLAN.md gain the W5.9 parts: the Interop/* module rows, the RESP cap of contract 6, the mock section, three decisions on the interop harness, and the unit 2 milestones. The demo and pingnode contracts do not change.

The harness modules sit under their own Interop root, apart from the Cli module name that lean4-cli also uses, and the Cli lib now globs Interop.*.

#61 (W5.6) touches the docs of two packages this unit builds on, through the chain of root PLAN.

packages/libp2p/core/docs/ARCHITECTURE.md fixes the policy shapes, which the core surface left to the host: the gater's allowDial, allowInbound, and allowSecured; ResourceManager.openConnection with its ConnectionScope; and AddressRanker.rank over go-libp2p's AddrDelay schedule. No seam of SecurityProtocol, Muxer, MuxSession, or StreamHandler changes.
packages/libp2p/negotiate/docs/ARCHITECTURE.md gains upgradeWith, the upgrade with a checkpoint after the handshake, and negotiateStream, multistream-select over one muxed stream. upgrade keeps its signature.

The host surface also has newStream (#60 posted it). A unit that holds a Host opens its streams through it, and one that serves streams registers a StreamHandler, unchanged.

#62 (W4.3, yamux) touches docs this unit builds on. No existing signature changes.

Root ARCHITECTURE §3.3: "The loop blocks on one channel" now reads "The loop blocks only on channels its shutdown closes".
base/bytes gains Bytes.take? (with sliceAt?), which moves out of Streams.Framing, and Bytes.Blob, the wrapper that gives core data a Repr for its bytes.
net/streams gains Streams.readLoop, the reader task of a session: a credit from the loop before each read, a post per chunk, and a post for the end of the connection.
net/yamux lands its session: Session.new role conn leftover clock keepalive, openStream, acceptStream, close, and join, serving the Stream seam.

#63 (W5.1) lands libp2p/identity and touches docs and types this unit builds on. No existing signature changes.

Libp2p.Identity exports KeyType, PubKey, PrivKey, PeerId, and Identity.Error. The entry points are PubKey.unmarshal?, PrivKey.unmarshal?, PubKey.marshal, PubKey.verify, PrivKey.sign : ByteArray → ExceptT Error IO ByteArray, PrivKey.toPublic, PeerId.ofPubKey, PeerId.ofBytes?, PeerId.toBytes, and PeerId.ofString?.
PeerId derives BEq, DecidableEq, Hashable, Ord, and Repr, as root §3.2 asks. ToString prints the parsed text form. The derived == also compares that form, so code that asks "same peer?" compares a.hash == b.hash.
To make those classes derivable, Multiformats.Multihash now derives Hashable and Ord, and the generated multiformats enums (HashCode, ContentCodec, Protocol, Multibase.Base) derive Ord.
The peer shape rule stays Multiformats.Multiaddr.validPeerHash; PeerId carries its proof.

Interface change from W5.2: StreamHandler.handle now takes a StreamContext (the proved remotePeer and the connection's remoteAddr) before the stream. The reason and the full shape are on #15.

A handler value or a core mock in this unit's PR needs the new argument. A handler that needs neither field writes fun _ s => ….

PR #50 closed for inactivity, so the issue is claimable again. The claim clock runs from a fresh claim comment, 8 hours to a pull request. The base moved a long way since this unit opened: every dependency is merged now, so a claimant builds on the real stack with no mocks, and the seam issues #78, #55, #73, and #86 show the swap pattern the cli package follows. The deliverable is unchanged: the demo node and the ping node, with the loopback demo of the done-list (two hosts dial, ping, identify, and close through the full shutdown order).

Claim.

Navigation Menu

Repository navigation

[W5.8] cli: the demo and ping binaries #22

Where the spec lives

Your freedom, and its cost

Definition of done

Depends on

Ground rules

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[W5.8] cli: the demo and ping binaries #22

Description

Where the spec lives

Your freedom, and its cost

Definition of done

Depends on

Ground rules

Activity

IvanAnishchuk commented on Nov 4, 2026

irajgill commented on Nov 4, 2026

IvanAnishchuk commented on Nov 5, 2026

IvanAnishchuk commented on Nov 5, 2026

IvanAnishchuk commented on Nov 5, 2026

IvanAnishchuk commented on Nov 5, 2026

IvanAnishchuk commented on Nov 6, 2026

leolara commented on Nov 11, 2026

Mouzayan commented on Nov 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions