Skip to main content
Version: Sprint 4

Logical View

Core abstractions in application dev at 01c423c (11 October 2026).

Machine and Execution Data​

MachineData is the editable/serialized machine; an engine TuringMachine also has a runtime tape field. State coordinates and optional transition ports describe diagram layout, not execution semantics. Optional createdBy fields support collaborative attribution.

Variants are single-tape, multi-tape, multi-step, multi-tape-multi-step, computational, and nondeterministic. Read/write/move arrays are per tape; move sequences support multi-step variants. Computational machines have explicit halt states. Nondeterministic machines can produce several next configurations and a bounded computation tree.

Compilation and Bidirectional Editing​

The compiler's label-based output is finalized into ID-based states and transitions. programMachine.ts is shared between browser machine editing and server authoring. It handles normalization, deduplication, tape alphabets, position lookup, and non-fatal well-formedness messages. The analyzer provides semantic diagnostics and quick-fix suggestions separately.

Code edits are debounced; existing layout is recovered by state label, with the shared Yjs position map taking priority during collaboration. Diagram mutations regenerate DSL and increment a diagram-edit epoch. Incoming collaborative text does not itself authorize overwriting the room with stale local source.

Learning Domain​

  • Problems: authored definitions include public and private cases. Non-authors receive public cases and a private-case count; authors can inspect their full case set. Submissions run against the server's authoritative cases. Verdicts omit hidden-case detail rather than returning expected outputs.
  • Validation/bounds: the submitted-machine validator bounds states, transitions, tapes, and alphabet sizes. The grader caps execution at 10,000 steps and checks required variants. Authoring permits at most 20 cases.
  • Black-box daily: players probe a hidden reference machine and predict tape/result outcomes for specified inputs. Feedback is graded as tiles.
  • Build daily: players complete a starter machine or solve a scheduled catalog problem. Generated starters remove selected reference transitions; authoring checks those hidden rules are reachable and self-grades the reference.
  • Identity: normal document/problem recording uses Better Auth users. Daily play uses the HttpOnly fla_daily UUID cookie, optionally linked to a signed-in user. It is a browser identity, not an account-enforced quota.
  • Clock/reveal: one server clock determines the puzzle date/countdown; default timezone is Africa/Johannesburg. lockout, archive_only, and never control reference disclosure. See API details for case projections.

Collaboration and AI​

A room is a Y.Doc with codemirror and tests texts and a statePositions map keyed by label. Awareness carries user information, editor selections, and diagramCursor positions. Live awareness is distinct from the persistent update log and from saved file versions.

The session waits for provider sync before seeding an empty room; a 1.5-second fallback permits local editing if sync does not arrive. isSynced therefore does not always prove a live server connection.

The AI panel keeps conversation UI state, reads current source for the prompt, renders Markdown/code, and offers code application through updateFromSource. The API selects its model from smartModel. The user's optional Groq key and model preference are stored in browser local storage; the server can instead use GROQ_API_KEY. AI output is assistance, not authoritative simulator or grader output.

See Database View for storage relationships and Development View for module locations.