Scenarios

Sprint 4 scenarios grounded in application dev at 01c423c. The process view contains the corresponding sequences and API reference defines access/error contracts.

Actors and Capabilities

Actor	Typical work	Boundary
Guest learner	Open examples, edit/run/export machines, solve catalog questions, play daily puzzles	Catalog progress is not recorded without login; daily progress belongs to browser cookie
Signed-in learner	Save documents, reopen solutions, record catalog progress, publish problems	Not automatically an owner/contributor/admin
Document owner	Rename/delete/version own files; send/cancel invites; remove contributors	File writes remain owner-only
Accepted contributor	Open shared documents and collaborate on code/tests/positions	Pending invite is not access; direct owned-file save is not granted
Problem author	Publish and remove own non-built-in problems; inspect own private cases	No general update endpoint; built-ins cannot be deleted
Daily admin	Preview, schedule, replace/remove dates, fill next seven days	Server checks account role='admin'
AI user	Request explanations/fixes/generated DSL and choose whether to apply it	Requires a user or server Groq key; source is sent to Groq

1. Build and Debug a Machine

1. Open a template or blank editor without signing in.
2. Create states by double-clicking the canvas, drag states to position them, and connect state ports. Use context actions for state/transition changes.
3. Switch to CODE to edit DSL; compiler diagnostics identify source problems. Valid source and diagram changes synchronize through the machine store.
4. Set input and Run, Pause, Step, or Reset while inspecting tape/head/state.
5. Define I/O tests; inspect failures and complexity measurements. In a nondeterministic variant, use TREE to inspect configurations.
6. Export JSON or PNG; sign in when saving a document is needed.

Expected outcome: one consistent machine across visual/source views. Invalid source must display diagnostics rather than silently replace the machine with a success-shaped partial result.

2. Save and Resume a Problem Solution

1. Browse /problems and open /problems/:slug.
2. Read the QUEST panel and public examples, edit the starter, and test locally.
3. SUBMIT runs server-held cases. Hidden-case verdicts omit tape details.
4. A guest sees unrecorded progress; a signed-in learner gets attempt/solved status on the catalog.
5. SAVE creates a separate document associated with problem_slug; reopening it can restore the question alongside the saved solution.

Expected outcome: learner code never mutates the catalog reference. Unbounded or malformed machines are rejected before grading.

3. Accept an Invitation and Collaborate

1. An owner saves a document and sends a pending invitation to another user.
2. The invitee accepts from the dashboard invitation area.
3. Acceptance atomically grants contributor access; the file appears under shared documents.
4. Both editors join the file-ID Yjs room and synchronize source, test DSL, state positions, and awareness.
5. The dedicated room server appends updates to PostgreSQL. An owner can separately save an explicit JSON version.

Expected outcome: pending/declined/cancelled invites grant no contributor relation. The UI's access gate should not be confused with WebSocket server authorization, which is not implemented in the inspected room service.

4. Infer the Black-Box Daily

1. Open /daily; the server chooses the date using its configured timezone.
2. Read the prediction inputs and spend probes on different valid inputs.
3. Enter final-tape and result predictions for each supplied input, then commit an answer.
4. Inspect feedback tiles, remaining budgets, and shareable result text.
5. After solving or exhausting answers, submission locks; reveal depends on policy. YOUR RUN shows browser-local identity's streak/history.

Expected outcome: reserved prediction inputs cannot be probed. Invalid requests do not spend quota; valid requests cannot exceed conditional SQL budgets. Clearing cookies can create another player identity.

5. Complete the Build Daily

1. /daily offers OPEN EDITOR for a build day.
2. A catalog-backed day opens its problem route; a generated day opens /daily/build with the projected starter and examples.
3. Edit missing rules/source and run local tests without spending answers.
4. QUEST's SUBMIT displays remaining graded attempts.
5. At lockout the editor stays usable, but further daily submissions are refused until rollover.

Expected outcome: local simulation is not proof of passing private cases; only the server daily verdict records a solved day.

6. Publish and Schedule Learning Content

An authenticated author fills /create-problem with slug/title, difficulty, variant/tape count, statement, optional starter, and public/private test DSL. Publication validates the definition and opens its problem page.

A daily admin uses /admin/daily to choose date, kind, budgets, reveal policy, and a catalog slug or reference source. CHECK returns errors, warnings, generated counts and transition reachability. Build authors can select which transitions are blank. PUBLISH schedules the draft; CALENDAR shows browser play/solve counts and REMOVE.

Expected outcome: preview does not write; publishing enforces server permissions and limits. Replacing an existing date retains previous attempts; authors must account for that history before changing live puzzle content.

7. Use Groq to Explain or Fix Code

1. Select AI in the existing right-hand inspector.
2. Optionally ADD KEY/MANAGE KEY; the key is stored in browser local storage. Without it the server may use GROQ_API_KEY.
3. Choose the model mode and send a prompt with current source context.
4. Inspect assistant text and recognized DSL code blocks.
5. Choose APPLY TO EDITOR to compile suggested source; inspect diagnostics and tests before trusting the result.

Expected outcome: source and recent messages are sent through the application's /api/ai/chat proxy to Groq. Provider/key errors are visible; no credentials are included in these docs. Generated code is not a verified solution or an automatic catalog submission.