mustflow 2.116.1 → 2.116.2

package/templates/default/locales/en/.mustflow/skills/ui-dispatch-lifecycle-review/references/ui-affinity-event-loop-checklist.md

@@ -0,0 +1,277 @@
+# UI Affinity and Event Loop Checklist
+
+Use this checklist when UI ownership, native peer creation, object graphs, bound models, await
+continuations, synchronous marshaling, timers, deletion, or event-loop availability are in scope.
+Confirm toolkit behavior against the repository's actual framework and version.
+
+## Contents
+
+1. [Owner identity](#owner-identity)
+2. [Affinity creation](#affinity-creation)
+3. [Object graphs and bound models](#object-graphs-and-bound-models)
+4. [Worker transfer boundary](#worker-transfer-boundary)
+5. [Await and continuation context](#await-and-continuation-context)
+6. [Event-loop availability](#event-loop-availability)
+7. [Send, post, and timers](#send-post-and-timers)
+8. [Blocking and wait graphs](#blocking-and-wait-graphs)
+9. [Deletion and shutdown](#deletion-and-shutdown)
+10. [Responsiveness evidence](#responsiveness-evidence)
+11. [Fault matrix](#fault-matrix)
+12. [Invariants](#invariants)
+13. [Skill handoffs](#skill-handoffs)
+
+## Owner identity
+
+Do not collapse these concepts:
+
+- process entry or main thread;
+- toolkit UI event thread;
+- owner dispatcher, looper, actor or serial queue;
+- rendering or compositor thread;
+- worker thread and its event loop;
+- object instance affinity;
+- native handle or peer ownership.
+
+Ask which dispatcher or thread owns this exact instance. Two objects of the same class can have
+different owners.
+
+Use toolkit assertions or stored owner identity. Thread name, class name, generic synchronization
+context and “main” naming are not sufficient proof.
+
+## Affinity creation
+
+Identify when affinity becomes fixed:
+
+- object construction;
+- native handle or peer creation;
+- attachment to a scene, window or parent;
+- dispatcher or looper registration;
+- first property access that lazily realizes native state;
+- binding or event-source attachment.
+
+An early affinity predicate can be ambiguous before a handle exists. Prevent workers from touching
+properties that can create the handle or peer on the wrong thread.
+
+Create UI roots and native peers deliberately on their owner context before exposing them to workers.
+
+Treat recreation, reparenting, detach and reattach as new attachment generations.
+
+## Object graphs and bound models
+
+Affinity can cover an ownership graph:
+
+- parent and child controls;
+- timer and event source;
+- socket or notifier;
+- image, brush, font and native resource;
+- model or collection consumed by bindings;
+- layout, template and accessibility caches.
+
+Do not move only the root while children or resources remain owned elsewhere. Move a supported whole
+graph or recreate it on the destination.
+
+A plain model or collection becomes affinity-sensitive when the UI enumerates it or consumes its
+change events. Thread-safe container methods do not make one coherent rendering snapshot.
+
+Treat getters as potentially active. They can realize templates, create handles, calculate layout,
+populate caches, query native state or emit messages.
+
+## Worker transfer boundary
+
+Workers should return pure data:
+
+- bytes or immutable pixel buffers;
+- strings and numbers;
+- immutable DTOs;
+- immutable collection snapshots;
+- effect descriptions.
+
+Do not transfer mutable toolkit resources merely because construction finished. Use only
+framework-documented frozen, detached or transferable forms and prove the freeze happened before
+publication.
+
+After ownership transfer, the producer must not continue mutating the same graph.
+
+Publish one result snapshot with operation, view, attachment, edit and source versions.
+
+## Await and continuation context
+
+An async method starts on its caller until the first incomplete suspension. Continuation destination
+depends on the runtime, captured context, explicit executor or actor, and code path.
+
+At every suspension boundary ask:
+
+- which context is captured;
+- whether continuation is allowed to resume elsewhere;
+- whether the destination loop is alive;
+- whether the target owner and generation remain current;
+- whether locks or gates cross the wait;
+- whether terminal paths complete on success, failure and cancellation.
+
+A synchronization context is a scheduling address, not a universal UI-thread identity card. It can
+be absent during startup, custom in tests or hosts, and stale during shutdown.
+
+Complete promises or task sources outside locks when continuations can run inline. Prefer explicit
+asynchronous continuation scheduling for infrastructure primitives where supported.
+
+## Event-loop availability
+
+A thread's existence does not prove it consumes queued callbacks.
+
+Verify:
+
+- event loop was started;
+- correct context or dispatcher is active;
+- target object still has that affinity;
+- loop has not begun shutdown;
+- priority or mode permits the callback;
+- queued deletion and timers can run;
+- shutdown rejects or drains work observably.
+
+A queue post can succeed while no consumer ever executes it. Missing completion can be starvation or
+an absent terminal path, not a lock deadlock.
+
+Separate worker-thread controller objects from worker objects that actually live on the target
+thread. A thread wrapper instance can itself remain owned by the creator thread.
+
+## Send, post, and timers
+
+Classify delivery:
+
+| Delivery | Structure |
+| --- | --- |
+| direct call | same caller stack and immediate reentrancy |
+| synchronous send or invoke | caller waits for target completion |
+| asynchronous post | caller returns; target loop executes later |
+| timer | callback becomes eligible after a time condition; execution may be delayed or coalesced |
+| paint or layout invalidation | request is recorded and often merged for a later frame |
+
+Submitting synchronously to the same serial queue is self-deadlock. Cross-thread synchronous marshal
+can deadlock when UI waits for the caller or its lock.
+
+Asynchronous post is not parallel work. CPU-heavy code posted to the UI remains UI-thread work.
+
+Use monotonic elapsed time for animation or timeout decisions. Timer intervals do not guarantee
+exact execution times or tick counts.
+
+## Blocking and wait graphs
+
+Include these patterns:
+
+- UI waits synchronously for a continuation targeting UI;
+- worker synchronously invokes UI while UI joins worker;
+- serial queue synchronously submits to itself;
+- UI and model locks are acquired in opposite order;
+- a logical async gate is held across work that needs the same gate;
+- completion runs a continuation inline under a lock;
+- destination loop does not run queued completion;
+- one success-only completion source leaves failure or cancel waiting forever;
+- bounded queue producer waits for space while consumer waits for UI approval;
+- cleanup or native release needs the UI or STA context while UI waits for cleanup;
+- thread-pool workers are consumed by sync-over-async waits.
+
+Distinguish blocking deadlock, missing completion, loop starvation and pool starvation.
+
+Do not use manual pumping to make a synchronous wait appear responsive; route that case to the modal
+reentrancy review.
+
+## Deletion and shutdown
+
+Creation, timers, queued signals, native release and deletion can all require owner affinity.
+
+For deferred deletion record:
+
+- owner loop;
+- whether it has started;
+- shutdown state;
+- queued-delete identity;
+- outstanding callbacks and timers;
+- confirmation or observable terminal state.
+
+A deferred delete posted to a stopped loop is not cleanup.
+
+Shutdown sequence:
+
+1. stop new admissions;
+2. stop producers and timers;
+3. request cancellation;
+4. drain or reject queued callbacks;
+5. await owned tasks without blocking their completion context;
+6. release resources on required owners;
+7. delete object graphs;
+8. stop event loops and dispatchers;
+9. verify no queued lifetime work remains.
+
+A rendering thread or mutex does not authorize general UI-object access.
+
+## Responsiveness evidence
+
+Record:
+
+`created -> worker_started -> enqueued -> ui_started -> state_applied -> layout -> paint -> presented`
+
+Also retain:
+
+- target dispatcher and priority;
+- queue age and depth by priority;
+- event-loop heartbeat delay;
+- worker queue age and active pool size;
+- lock owner and hold duration;
+- allocation types before GC pauses;
+- invalidation origin and layout pass count;
+- damaged region and overdraw;
+- GPU fence, readback and upload waits;
+- synchronous external-process calls;
+- high-rate input and progress production.
+
+A low-CPU UI can be blocked. A high-CPU UI can be live but starve input and rendering.
+
+## Fault matrix
+
+| Fault | Required result |
+| --- | --- |
+| main thread is not toolkit UI thread | owner assertion routes correctly |
+| affinity checked before native handle exists | worker cannot create the handle |
+| child resource has another owner | graph audit rejects or recreates |
+| getter invoked from worker | affinity assertion catches active read |
+| bound collection mutates from worker | immutable snapshot boundary holds |
+| mutable image or font crosses thread | transfer contract rejects it |
+| continuation resumes after context change | application guard revalidates |
+| synchronization context is null or custom | owner identity does not depend on it |
+| target loop never started | queued work is rejected or diagnosed |
+| loop shuts down with queued deletion | cleanup remains observable and bounded |
+| synchronous invoke targets same queue | self-deadlock prevention fires |
+| UI waits while worker invokes UI | wait graph exposes the cycle |
+| completion runs inline under lock | continuation cannot reenter protected state |
+| one task path omits completion | terminal-path invariant fails |
+| bounded queue and UI approval cycle | protocol avoids circular backpressure |
+| timer fires late or coalesces | elapsed-time logic remains correct |
+| high-priority work floods dispatcher | lower-priority progress remains bounded |
+
+## Invariants
+
+Choose applicable invariants:
+
+- every UI or bound object has one known owner;
+- no worker creates a native UI peer accidentally;
+- every owned object graph has compatible affinity;
+- only pure or explicitly frozen data crosses worker-to-UI boundary;
+- every continuation has an observable destination and terminal path;
+- queued work requires a live consuming event loop;
+- no synchronous dispatch targets its current serial queue;
+- no wait cycle depends on a blocked UI context;
+- deletion and timer shutdown execute on required owners;
+- stopped loops retain no unaccounted queued lifetime work;
+- timer and dispatcher delay cannot masquerade as physical elapsed time;
+- affinity assertions remain enabled in development and representative tests.
+
+## Skill handoffs
+
+- Use `ui-dispatch-lifecycle-review` for freshness, view epochs, cancellation, closing and queue
+  pressure.
+- Use `modal-loop-reentrancy-review` for nested pumping and same-stack reentry.
+- Use `race-condition-review` for memory ordering and parallel interleavings.
+- Use `frame-render-performance-review` after delay is localized to layout, paint or GPU work.
+- Use `memory-lifetime-review` for raw pointer and native-resource lifetime.
+- Use the framework-specific skill when exact toolkit or runtime behavior determines the fix.
+

package/templates/default/locales/en/.mustflow/skills/ui-dispatch-lifecycle-review/references/ui-dispatch-lifecycle-checklist.md

@@ -0,0 +1,292 @@
+# UI Dispatch and Lifecycle Checklist
+
+Use this checklist when work is scheduled onto a UI affinity context and can outlive the operation,
+view, native peer, edit version, cancellation source, or queue budget that created it.
+
+## Contents
+
+1. [Authority model](#authority-model)
+2. [Application-time guard](#application-time-guard)
+3. [Immutable payloads](#immutable-payloads)
+4. [Ordering and ABA](#ordering-and-aba)
+5. [User edits and remote results](#user-edits-and-remote-results)
+6. [View and handle generations](#view-and-handle-generations)
+7. [Cancellation ownership](#cancellation-ownership)
+8. [Closing state machine](#closing-state-machine)
+9. [Subscriptions, gates, and shutdown](#subscriptions-gates-and-shutdown)
+10. [Queue pressure and progress](#queue-pressure-and-progress)
+11. [Responsiveness diagnosis](#responsiveness-diagnosis)
+12. [Deterministic fault matrix](#deterministic-fault-matrix)
+13. [Invariants](#invariants)
+14. [Skill handoffs](#skill-handoffs)
+
+## Authority model
+
+Keep these identities distinct:
+
+| Identity | Meaning |
+| --- | --- |
+| operation ID | one logical load, validation, synchronization or save |
+| attempt ID | one execution try |
+| view instance ID | one constructed UI owner |
+| attachment epoch | one native handle, peer, scene or window attachment |
+| operation generation | current winner among superseding work |
+| state version | UI state assumed by the result |
+| edit version | local user-edit state assumed by background work |
+| source version | server, file, device or model authority used for computation |
+| close request ID | one shared asynchronous close sequence |
+
+A dispatcher ensures only the scheduled execution context. It does not choose the current operation
+or view generation.
+
+## Application-time guard
+
+Validate inside the UI callback immediately before mutation:
+
+- owner is still open;
+- view instance matches;
+- attachment or handle epoch matches;
+- operation is still current;
+- cancellation has not become terminal;
+- expected state and edit versions still match;
+- target entity still exists;
+- result has not already applied;
+- terminal state does not forbid the transition.
+
+A check before enqueue is useful for avoiding obvious work but is not a correctness gate.
+
+Log rejection with stable reason such as `owner_closed`, `view_epoch_mismatch`,
+`operation_superseded`, `edit_conflict`, `canceled` or `terminal_state`.
+
+## Immutable payloads
+
+Construct one immutable result before enqueue. Include every field that must agree:
+
+- item collection and count;
+- ordering and grouping;
+- totals and derived values;
+- selected stable ID;
+- loading, error and completion state;
+- source and edit versions;
+- operation and view generations.
+
+Do not capture a mutable model, list, builder, iterator or child graph that a worker can continue
+changing. Copying only the outer object reference does not transfer ownership.
+
+Prefer one UI state replacement to several property notifications whose intermediate combinations
+can trigger bindings, converters, validation or commands.
+
+## Ordering and ABA
+
+A FIFO dispatcher orders enqueue operations, not background task start order or source causality.
+
+Give superseding work a monotonic generation. A repeated value does not prove the same generation:
+
+`A request 17 -> B request 18 -> A request 19`
+
+Result 17 must not pass merely because the current visible value is A.
+
+Define a terminal precedence table. Completion, cancellation, failure and progress must not regress
+each other. An obsolete progress callback cannot follow a terminal result.
+
+## User edits and remote results
+
+Capture:
+
+- edit version at background-work start;
+- source version;
+- target range or stable field identity;
+- composition or selection state when relevant;
+- local dirty or uncommitted status.
+
+At application choose one explicit policy:
+
+- local edit wins and remote result becomes stale;
+- merge by domain rule;
+- show conflict without overwriting;
+- restart computation against the current edit;
+- apply only untouched fields.
+
+Do not overwrite active composition, caret, selection or uncommitted text solely because a server
+response completed later.
+
+## View and handle generations
+
+Increment an attachment epoch on applicable events:
+
+- native handle recreation;
+- detach and reattach;
+- scene or window change;
+- owner or parent change;
+- view reuse;
+- close and reopen;
+- model replacement;
+- display or rendering-peer recreation.
+
+Object reference equality, same title, same entity ID or reused view model does not prove the same
+rendering lifetime.
+
+Callbacks carry both view instance and attachment epoch. A callback from a retired epoch cannot
+mutate the new peer.
+
+## Cancellation ownership
+
+Cancellation is a request to cooperate. It does not:
+
+- remove already queued UI callbacks;
+- prove the worker stopped;
+- authorize disposal of resources still in use;
+- clear an operation's busy state;
+- guarantee a callback runs later or on another thread.
+
+Each operation owns a local cancellation source. An old `finally` disposes only its captured source
+and clears shared fields only through compare-by-identity or generation.
+
+Treat cancellation callbacks as potentially synchronous at registration or cancel call. Keep them
+small, nonblocking and free of complex UI or lock reentry.
+
+For semaphores and gates, track acquisition locally. Release only after successful acquisition and
+only once. Prefer an owner-bearing lease for complex gates.
+
+## Closing state machine
+
+Use:
+
+`Open -> Closing -> Closed`
+
+When the framework close event is synchronous:
+
+1. first request cancels immediate destruction;
+2. atomically enter Closing and store one close task;
+3. reject new work and input admission;
+4. request cancellation from owned operations;
+5. await owned completion without blocking the UI affinity context;
+6. dispose lifetime subscriptions, timers and resources;
+7. flush required state;
+8. request final framework close once;
+9. enter Closed.
+
+Additional close requests during Closing return or join the same close task.
+
+Every continuation checks close state and view generation. Queued callbacks after Closing are
+rejected even if their worker succeeded.
+
+## Subscriptions, gates, and shutdown
+
+Bind event, timer, observable, message-bus, progress and global-service subscriptions to one lifetime
+container. Dispose the container at close, while retaining callback generation guards for work
+already queued.
+
+Zombie views are correctness bugs, not only leaks: a retained closed view can consume events and
+race a newly opened view.
+
+Order application shutdown:
+
+1. block new UI and background work;
+2. stop periodic and event-driven producers;
+3. request cancellation;
+4. drain owned tasks to a bounded deadline;
+5. persist required durable state;
+6. stop services in dependency order;
+7. destroy views and dispatch infrastructure;
+8. finalize diagnostics.
+
+Avoid relying on one long last-second save. Use normal-operation journaling or atomic persistence
+where durability matters.
+
+## Queue pressure and progress
+
+Record enqueue, start and apply time per callback. Queue delay is `start - enqueue`.
+
+Coalesce supersedable updates:
+
+- progress retains latest current-generation value;
+- pointer or high-rate input follows its semantic compaction policy;
+- status boundaries and terminal states are never discarded;
+- final completion invalidates older queued progress;
+- per-source update rate is bounded;
+- queue age and oldest useful work are bounded.
+
+Different dispatcher priorities can reorder visible outcomes. Include priority in the contract and
+trace.
+
+## Responsiveness diagnosis
+
+Correlate these stages:
+
+`created -> worker_started -> dispatch_enqueued -> ui_started -> state_applied -> layout -> paint -> presented`
+
+Classify delay:
+
+| Delay surface | Evidence |
+| --- | --- |
+| worker start | thread-pool queue age and worker availability |
+| UI queue | enqueue-to-start latency and priority |
+| lock or sync call | off-CPU wait and owner chain |
+| allocation or GC | allocation types before pause and stop timeline |
+| layout | invalidation source and pass fan-out |
+| paint | damage region, layers and overdraw |
+| GPU | fence, readback, upload and presentation waits |
+| external component | RPC, COM, IME, accessibility, clipboard, shell or driver wait |
+| input storm | event rate, work per event and starvation of render or idle |
+
+Low CPU can mean blocked or starved work. Short callbacks can still form a long queue.
+
+Use a UI heartbeat to retain traces when tail queue delay crosses a product threshold. Track tail
+and consecutive delays, not only averages.
+
+## Deterministic fault matrix
+
+Use a controllable dispatcher, virtual clock and explicit barriers:
+
+| Schedule or fault | Required result |
+| --- | --- |
+| old result completes after new result | old generation is rejected |
+| value A returns after A-B-A | ABA generation rejects first A |
+| view closes after enqueue before run | callback performs no mutation |
+| native peer recreates before run | old attachment epoch is rejected |
+| cancel occurs after enqueue | callback checks terminal cancellation |
+| mutable source changes after enqueue | immutable payload remains coherent |
+| progress backlog precedes completion | terminal state cannot regress |
+| old finally runs after new start | new owner state remains intact |
+| close requested twice | one close task and cleanup sequence |
+| cancellation callback runs inline | no lock or UI reentry corruption |
+| semaphore wait cancels before acquire | permit count remains correct |
+| subscription retains closed view | lifetime invariant detects leak |
+| thread pool is saturated | worker-start delay is visible |
+| layout or input storm floods queue | queue age and compaction show cause |
+| shutdown destroys service early | dependency-order invariant fails |
+
+Preserve schedule decisions and state transitions when a fixture fails.
+
+## Invariants
+
+Choose applicable invariants:
+
+- closed or retired views receive zero state mutations;
+- an old operation or attachment generation cannot apply;
+- UI state snapshots are internally coherent;
+- one current operation owns busy, cancellation and cleanup state;
+- a terminal state cannot transition back to progress or loaded work from an old generation;
+- cancellation request is not reported as completed cleanup;
+- no operation releases a gate it did not acquire;
+- every lifetime subscription returns to baseline after close;
+- Closing admits no new owned work;
+- shutdown destroys dependencies only after their owned users drain or reach a documented bound;
+- queue age and callback production remain bounded;
+- each interaction trace can distinguish worker, dispatcher, layout, paint and presentation delay.
+
+## Skill handoffs
+
+- Use `modal-loop-reentrancy-review` when nested pumping or a blocking dialog keeps the outer
+  callback stack active.
+- Use `race-condition-review` for general interleavings and happens-before evidence.
+- Use `frontend-state-ownership-review` for browser state duplication without native lifecycle.
+- Use `frame-render-performance-review` for layout, paint and compositing remediation after the
+  dispatch delay is localized.
+- Use `performance-measurement-integrity-review` for latency units, tail metrics, clock domains and
+  benchmark comparability.
+- Use `input-event-synchronization-review` for high-rate device-event compaction and input-session
+  epochs.
+- Use `state-machine-pattern` to implement close or operation lifecycle transitions.
+