sessionstream-systemlab

README

sessionstream-systemlab

sessionstream-systemlab is a separate app used to explain, exercise, and validate the public API boundaries of the sessionstream framework.

Goals:

• keep the playground separate from substrate code,
• consume only public sessionstream APIs,
• provide narrated labs for each implementation phase,
• make debugging and onboarding easier.

Boundary contract

Systemlab may:

• import github.com/go-go-golems/sessionstream/pkg/sessionstream public packages and sibling pkg/sessionstream/... subpackages,
• expose its own HTTP endpoints and UI shell,
• exercise the same public seams later transports will use.

Systemlab may not:

• import pkg/webchat internals,
• introduce SEM-specific substrate types into sessionstream,
• reach around the public Hub/store/transport seams.

Current phases implemented:

• Phase 0 foundations / status page
• Phase 1 command -> event -> projection lab
• Phase 2 ordering / ordinals lab
• Phase 3 hydration / reconnect lab
• Phase 4 chat demo lab
• Phase 5 persistence / restart lab

Current chapter coverage in Systemlab:

• Phase 0 through Phase 5 have long-form markdown chapters served by the app
• Phase 0 through Phase 5 are framework-oriented labs owned by the sessionstream repo
• The old Phase 6 cmd/web-chat migration console is intentionally not part of this extracted Systemlab because it remains a downstream pinocchio concern

Transport schema note

The websocket transport exercised by the labs now uses the public protobuf schema in proto/sessionstream/v1/transport.proto. Frames are sent as protobuf JSON ClientFrame / ServerFrame messages rather than ad-hoc JSON envelopes. Snapshot and UI payloads are carried as google.protobuf.Any, and ordinal fields are uint64 values that protojson renders as strings for JavaScript safety.

When adding or updating labs, prefer the protobuf field names used by the transport schema:

• sinceSnapshotOrdinal on subscribe requests;
• snapshotOrdinal on snapshot frames;
• createdOrdinal and lastEventOrdinal on snapshot entities;
• eventOrdinal on live UI event frames.

Frontend and chapter file layout

The Systemlab browser UI is intentionally split so future labs do not accumulate into one large inline HTML file, and the long-form intern chapters live as editable markdown beside the app:

• static/index.html — app shell only
• static/app.css — shared styling
• static/partials/*.html — page-level markup fragments
• static/js/main.js — bootstrap + navigation
• static/js/pages/*.js — per-page behavior
• static/js/api.js / static/js/dom.js — shared helpers
• chapters/*.md — long-form textbook chapters served by the app and rendered onto the matching phase pages

When adding a new lab, prefer adding:

• a new partial,
• a new page module,
• and, when needed, a matching markdown chapter in chapters/

instead of growing index.html or one global script.

Run locally:

make systemlab-run
# or directly:
go run ./cmd/sessionstream-systemlab serve --addr :8091

The binary uses a Glazed/Cobra CLI. The HTTP server is exposed as the serve verb, and Sessionstream's embedded help entries are available through the CLI:

go run ./cmd/sessionstream-systemlab help sessionstream-getting-started
go run ./cmd/sessionstream-systemlab help sessionstream-user-guide
go run ./cmd/sessionstream-systemlab help sessionstream-reference
go run ./cmd/sessionstream-systemlab help sessionstream-schema-vet-playbook

Validation helpers:

make test
make systemlab-build
make boundary-check

Then open:

• http://localhost:8091/