cameron.stream / thought-stream
A local-first event pipeline for independent agents, built on Jazz.
Star
Fork 0
Watch
thought-stream spec courses.md
5.2 kB
Markdown
at document-workbench

Private interactive courses #

Purpose #

The authenticated inspector can host private instructional surfaces that combine reviewed static course material with receipt-backed questions. The first course is post-training-model-factory. It starts with one executable capability contract, reconstructs Machine's Project Euler experiment, and then covers data, environments, supervised fine-tuning, preferences, reinforcement learning, evaluation, and lab-scale model factories.

Course content lives in repository source. The server computes one SHA-256 revision over the complete course body and returns that revision with every read. A browser question must bind to the current revision and one known lesson. Stale, unknown, or oversized requests fail before event insertion.

The Machine lesson pins the exact public Project Euler guide revision used for its gate and result claims. Updating one of those claims requires checking a new public revision, which also changes the course revision.

Read surface #

GET /api/courses/post-training returns the reviewed course structure, current revision, lessons, workshops, glossary, and primary references. The route reads no private events and performs no external request.

The inspector renders the course under the Learn destination. Each lesson contains:

  • one capability or systems objective;
  • mechanism-first explanation;
  • a bounded interactive exercise;
  • primary references;
  • previous and next navigation.

The client stores no server credentials. Lesson progress is browser-local. The tab session retains only bounded opaque pending-question receipts so a reload can resume exact status polling; it does not persist question or answer text.

Question event #

stream.thought.source.course.question@1 is one authenticated operator question.

  • The source is exactly web-course:post-training-model-factory.
  • sourceKind is web, the actor is operator:cameron, and privacy is sensitive.
  • The strict payload contains a caller-generated request id, course id and revision, lesson identity, optional section identity, bounded question text, and server-selected lesson context.
  • The browser cannot supply or widen lesson context. The inspector derives it from the current repository course.
  • The event is self-rooted. Idempotency binds the exact request id. Reuse with different content fails closed.

The event grants no publication, file, channel, tool, training, or model-selection authority.

Tutor execution #

post-training-course-tutor@1 subscribes only to the exact question type and source with replay: now. It receives one projected source event, runs in strict-JSON mode, emits one canonical private observation, and has no tools, proposals, or external actions.

The consumer, not the inspector, owns inference. The POST request returns after the source event settles. The browser polls one exact question route. A completed answer is returned only when the output joins to one completed run for the tutor declaration through the canonical observation lineage contract. Failure responses expose a bounded status, not provider errors or model output that failed validation.

Questions are single-turn in the first release. The browser may display several question and answer cards, but the model does not receive client-authored transcript history. Multi-turn course history requires a separate event and context contract.

Deployment must restart the consumer process after installing the tutor declaration. The consumer credential compartment must provide the configured Tinker profile. Restarting only the inspector and proxy creates an accepted question path with no answer producer, which fails activation.

Authenticated write path #

POST /inspector/api/courses/post-training/questions is the only course mutation route.

  • Basic authentication remains read-only.
  • An allowlisted OAuth browser session must provide its session CSRF token.
  • The proxy and inspector share one course-chat capability that is separate from the Review capability.
  • The proxy signs the exact method, normalized route, body digest, timestamp, and one-time nonce.
  • The inspector verifies that envelope before parsing the fixed request schema and appending the event.
  • Nginx admits only POST on the exact route and applies an independent request-size and rate limit.

Course chat cannot append arbitrary events, address another declaration, alter the tutor model, read another question by request id, or deliver a response outside the authenticated inspector.

Privacy and evidence #

Questions, lesson context, model answers, runs, and traces remain sensitive. They are excluded from public routes, Telegram delivery, automatic training export, and public knowledge projection. Inspector list endpoints do not return a transcript. The exact status route requires the event id generated by the source receipt and validates the event family before returning an answer.

Test proof uses temporary Jazz databases and deterministic run fixtures. Live proof requires one user-authored question after deployment, then source event, tutor run, output, terminal settlement, and authenticated readback receipts from one causal chain.