feat: reads (read-only HTTP projections) + persist write-path hardening

[deligoez]

Summary

Adds reads — declarative, zero-write HTTP projections of a machine's current state — and hardens the persistence write path. Reads are the query side of a command/query split: endpoints: send events and write history; reads: only look.

Motivation

A frontend polling a machine's status was modelled as a targetless event. Every poll ran the full send() → persist() pipeline and appended ~4 rows to machine_events. A long-open screen bloated one machine's history to ~5,458 rows; persist() re-upserted the entire history each time, hit MySQL's 65,535-placeholder ceiling, threw QueryException, and wedged the machine (its status column committed but the events didn't — a desync). Reading state is a query, not an event — in both state-machine theory (you inspect the configuration) and CQRS (queries never produce events).

What's in this PR

reads concept (zero-write by construction)

• MachineRouter::register(['reads' => true | ['status' => null, 'resume' => [...]]]) → GET, machineId-bound routes.
• MachineController::handleSnapshot() — restores read-only and returns the standard envelope; never constructs an event, never calls send()/persist(), never locks, never writes a row.
• ReadDefinition value object (forms: null | string URI-shorthand | options array; validates keys & URI; rejects action/method/unknown).
• Output shaping reuses the endpoint output parsing (context-key filter / OutputBehavior / fallback).
• buildResponse() now honours includeAvailableEvents (false omits the key) — this also fixes endpoints, where it was a silent no-op.

Persist write-path hardening (independent of reads; fixes the incident's root cause)

• Incremental persist — upsert only the dirty slice (history[max(0, watermark-1)..]) instead of the whole history; O(new+1) writes regardless of history length. Watermark captured at restore, advanced after persist; root row stays full; last row keeps the full snapshot.
• Atomicity — for transactional events, persist() now runs inside the transition's DB::transaction, so a persist failure rolls back the action's committed DB writes (no state/log desync).
• Prune-safe sequencing — sequence_number from max()+1 of in-memory history, not the row count.
• Restore hardening — an idMap miss (foreign/wrong-class machineId) now throws RestoringStateException (single + parallel paths), so reads map it to a clean 404.

Docs & skill — new docs/laravel-integration/reads.md, persistence write-path-hardening notes, endpoints↔reads cross-links, and the agent-skill updates (concept, nav, anti-pattern) that ship via plugin-dist.

Testing

Full gate green: phpstan 0 errors, 2,659 tests pass, type coverage 100%. New coverage: ReadDefinition, read registration (forms/collision/duplicate/reads-only), snapshot envelope + zero-write + archived restore, output routing, available_events omission (reads and endpoints), 404 (unknown + wrong-class), incremental dirty-slice + bounded-upsert-at-scale + cross-restore round-trip, atomicity rollback and not-wedged recovery, prune-safe sequencing.

Review & audit

Spec converged over 5 adversarial review rounds (2 consecutive clean); implementation verified by a post-implementation audit (round 1 → 6 findings, all fixed; round 2 clean across implementation, engine, and docs/skill).

Notes

• Purely additive — absent reads, no new routes; persist hardening is backward-compatible (transparent for contiguous histories; atomicity only tightens an existing failure mode).
• The literal ≥5,462-row MySQL placeholder-ceiling regression is a MySQL-semantics concern (LocalQA); the unit suite proves the upsert stays bounded as history grows, which is what makes the ceiling unreachable.

https://claude.ai/code/session_01Jsh4xaG4TL8GAfCcqZk9PD

[cloudflare-workers-and-pages]

Deploying event-machine with    Cloudflare Pages

Latest commit:	bd20ab5
Status:	⚡️  Build in progress...

View logs