Archived simulation architecture (superseded)

Historical only. See current architecture for direct-origin FIPS.

Status: SQLite-only implementation with three simulated peers in the real board UI. The old xitdb runtime/data have been removed. Explicit title/details/status resolutions are implemented; real FIPS transport and deletion/hierarchy merge remain future work. See implementation progress, schema contracts and historical architecture.

Implementation owners

Owner Responsibility
init.ts Open A/B/C databases plus separate inbox, WAL/FULL durability, close resources
app.ts Parse/route commands and preserve captured actor/recipient context
definition.ts Aggregate command-owned definitions
commands/boards/{create,list,show}/ Board creation, navigation, focused real UI
commands/tasks/ Todo schemas, hierarchy queries, event/projection transactions, row menus, inline panels and scoped styles
commands/changes/ Typed semantic events, immutable SQL/history, causal/field classification and exhaustive summaries
commands/incoming/ Separate inbox, contextual review models, individual/explicit context acceptance and resolution transactions
commands/priority/ Private root order, branch snapshots, representative propagation, champion derivation and Keep/Pick UI
commands/peers/ Fixture identities, peer selector, removable simulated delivery
commands/common/ Reused schema/definition/WebNode primitives
db/ Peer schema composition and local settings helpers

Related code stays with its command owner. Task and review handlers take databases and actors, not a FIPS implementation or the fixture transport. No plugin-specific branches/types were added to core or the web renderer.

Physical state boundaries

Working → released → staged → accepted

  1. A local command creates a UUID event and updates the affected entity in one peer transaction. Creation attribution is stable; edits carry their own pubkey.
  2. Send updates assigns per-board publication positions to that peer's own unsent events. Received history authored by another peer is not forwarded as local origin.
  3. Sync reads released events directly from other simulated origins, validates origin/board/schema and commits raw proposals plus receipt cursors to the separate inbox. It does not copy DB files or write received source history into a peer store.
  4. Decline changes only inbox status. Pending/declined events remain received and are not fetched forever. Dependents still wait for their prerequisites.
  5. Accept checks prerequisites/context and current local state, then atomically inserts that event and applies its entity change in the target peer database.
  6. Mark the inbox decision after the peer commit. This is not cross-DB atomicity: an identical-event retry finishes the decision safely without reapplying changes.

Board creation is a proposal too; unknown boards can be inspected in the real show UI without creating a board row. Accept the board, then each todo/change individually. Source histories are immutable; an accepted change cannot be declined in place.

The simulation pulls up to 200 events per origin/board per Sync and displays 200 proposals per review page, with Previous/Next navigation and pending items first. No background pull or automatic acceptance occurs. Public board discovery reveals released board IDs only, not unsent board content.

Causality, hierarchy and conflicts

Stable entity IDs and event IDs are independent lowercase UUIDs. created_at is Unix milliseconds; FIPS pubkey identifies the actor, not a human signature. based_on describes edited context; requires encodes semantic prerequisites. Publication order does not imply dependency on every prior action.

Todos use same-board parent links with cycle/foreign-key guards. A child creation requires its parent creation; edits require their todo creation. New boards provide a creation event which new todos also require. Live children must be deleted before their parent. Missing/unaccepted context is not silently applied or marked declined.

Title/status acceptance compares causal field heads, not the most recently appended entity event. Independent fields and equal values combine; covered source history never rolls back a descendant. Local edits reference all accepted entity heads. Concurrent different values require an explicit todo.resolve (title, details or status), containing the chosen field/value and competing event IDs in data.resolves, based_on and requires. Resolution accepts the competing source plus the new local event/projection atomically, checks displayed heads for staleness and uses a stable resolution UUID for retry safety. The inbox decision follows the peer commit. Keeping the current value is still a resolution.

A receiving resolution can explicitly review staged edit prerequisites with individually unselected checkboxes. The exact selected context set is validated and all source records plus final projection commit together; no implicit prerequisite acceptance is introduced. Compatible other-field context is projected too; another-field conflicts roll back the whole transaction. Creation/hierarchy/unavailable context still waits for separate review. Source authors remain unchanged, and publication still releases only own-origin events. Delete/edit and parent/child conflicts, full rebuild and optional agreement remain planned.

Board polling computes released-but-unpulled counts without writing the inbox. Every local todo mutation and publication first Syncs, then refuses to proceed with pending board-local reviews or additional unpulled batches. Unsent local work remains intact. Known backlog disables edit/send controls; server preflight closes the stale-view gap. Explicit decline clears that proposal's gate without accepting it. Resolving Syncs first but permits remaining proposals to be reviewed subsequently before publication. This reduces conflicts at their source without removing third-peer resolution or claiming that freshness checks prevent simultaneous distributed edits.

List/board headers compose title, a native peer select and one ⋮ menu. The menu keeps Boards, manual Sync now (for board views) and both reset previews. Peer selection uses the generic select command-action contract, with peer mapped to command options. Outside the menu, Send updates (N) exists only for unsent own-origin events, Sync (N) only for available publications, and pending review text only for a nonzero total. Idle views have no extra action row or zero sync counters. Blocked Send explains the required review. commands/peers/web.ts owns this shared header and its scoped styles.

Identity and future FIPS integration

The selector chooses a real peer-local DB in the simulation. Actions capture their actor/recipient; polling reads the current selection without changing that captured target. Public fixtures and in-process transport are deliberately removable.

Local task commands commit directly to the captured peer and return its updated UI. Nonempty incoming review/page controls appear above local tasks. The bottom root-add control and row child/sibling/title actions reveal inline panels locally; the ⋮ menu and retro checkbox status menu follow personal Todo's generic UI primitives. An empty inbox stays hidden. Submitted commands use recordInTimeline: false; opening panels does not call a command or open its generic form. Mutation results focus the submitting peer and refresh actions explicitly capture it. Panel identities include peer/board/task. Incoming uses contextual one-line summaries and left-side ✓ / ✗ icon controls. Conflicts have red text and explicit labels on proposals/local todos. Review and edit/send actions return the updated captured-peer board directly, including inline errors; a follow-up refresh command cannot erase the error immediately. Pending rows across pages participate in concurrency marking, and total pending counts govern the preflight gate.

Replace them with authenticated direct-origin FIPS identity/delivery after UX settles. No application signatures, NIP-01/JCS format or app private keys are required. Validate claimed authors against the sender and derive human labels from verified bindings. Do not trust arbitrary forwarding or an imported claimed master key.

Real transport must preserve external staging and individual acceptance, bounded framing, origin streams/cursors, grant/membership checks, retries and reset detection. FIPS owns transport/owner grants, not Todo schemas or accepted-state policy. Guided invitations/owner approval and narrower board/peer reset remain future work.

Personal priorities

commands/priority/ stores preferences in the external control database, keyed by acting peer public key and board. They never enter source events, publication streams, acceptance state or shared todo rows. Future real identity integration can replace the fixture key provider without treating personal opinions as collaborative edits.

Root order is explicit and revision-checked; only active roots can move by pointer drag. Full stored order preserves inactive slots, new roots append, and completed roots render after active roots. Root moves never reparent children. Each branch winner is promoted for display only, preserving all other siblings' relative order and the personal root order. The champion path is accent-colored from root to leaf. Winner selection independently chooses one active child per branch; the champion follows the first active root's confirmed path. Single-child branches initially resolve automatically.

Scope fingerprints include candidate IDs/titles/statuses, accepted edit IDs and child representative tokens. Reverted edits still require review. Staged or declined proposals are absent from this context. A changed scope retains a valid previous winner for Keep; otherwise it requests a new choice. Review is bottom-up across the current root order. Fingerprints and representative versions are separate: Keep saves new context without changing the representative version, so unchanged winners do not cascade. An actual winner/path change increments that version and prompts the immediate parent, followed by the next ancestor only after confirmation. A first explicit Keep of an automatic single-child winner also preserves its representative version.

Pure reads derive scopes/champion without writing preferences. Local priority commands validate captured actor/board and current scope/order snapshots, write only preferences, and return the board without Sync or publication preflight. Ordinary shared edits retain their existing preflight/review gates. The shared renderer supplies generic keyed tree reordering; no priority semantics or fixture identities live in core/web components.

Picking is a read-only board-view mode (show --pick <parent>|off), preserved during polling. Automatic review starts with the next ready branch; manual entry on a blocked parent opens a pending descendant first. Keep/Pick buttons live on eligible candidate rows and carry the captured actor/parent/snapshot. Parent menu actions expand its ancestor path. Current branch/ancestor rows carry a review-specific expandOnceKey, so automatic entry opens saved collapsed branches additively without disturbing unrelated state or reopening manual collapses on polling. There is no active picking/Done panel. Selected titles are accent colored and the champion gets a trophy prefix; no winner/champion badges or dropdown.

Shared task details and Update modal

todos.details is optional text in the UI and nonnull empty text in storage. Startup adds the column to existing tables and extends the event operation CHECK transactionally, preserving source JSON/rowids, references and publication positions. Legacy create payloads read with empty details; no source history is rewritten or backfilled.

The Update/📝 modal uses one title/details form with captured peer and entity-head revision. Save validates both values, Sync-preflights, rejects stale forms and commits only changed todo.title/todo.details events in one local transaction. Empty details explicitly clears the field in the complete-form save contract; unchanged saves create no events. Validation, preflight and stale failures return the submitted draft with inline feedback. Save stays in the editor with a refreshed revision; Close uses the generic modal sequence to close and refresh the captured origin board. Creation metadata is a collapsed disclosure.

Details events participate in causal field comparisons, compatible independent-field acceptance and explicit resolution. Incoming summaries are concise, with expandable full content; details conflicts use a textarea and explicit Clear details action. Candidate details edits invalidate local winner review like title/status edits. Empty details on legacy entities preserves old priority fingerprints until an actual edit occurs.

Reset

reset previews the complete simulation scope; reset --confirm clears A/B/C and the inbox, publications, decisions, cursors and UI selection. Reset recreates the schemas transactionally per DB instead of bypassing immutability for ordinary writes. A durable inbox marker records intent before peer resets; startup retries an interrupted reset, and the final inbox reset clears that marker only after all peers are cleared. The four DB commits are not globally atomic, but reset is idempotent and recoverable. DB handles remain usable, selection returns to A, and old Sync cannot revive cleared data.

reset --peer b --confirm instead resets only B's database and recipient inbox, leaving B selected. Other peer DBs and previously received proposals are not recalled. The simulation coordinator clears receipt cursors involving B as recipient or origin, so remote origins can be pulled again and B's restarted publication positions work. Recipient-staged boards remain discoverable even if their origin's publications were cleared, so already-received proposals remain reviewable. Incoming replays still need acceptance. Own erased origin history is not recovered by forwarding from another peer. Scoped intent markers make this reset recoverable too. Both reset actions live in the header ⋮ menu and preview their scope before confirmation. Real FIPS must negotiate stream/reset identities rather than share a coordinator's cursor DB. FIPS pairing/identity and other apps are outside every reset scope. Board-local reset remains future work.