mustflow 2.116.0 → 2.116.2

package/templates/default/locales/en/.mustflow/skills/input-boundary-validation-review/references/input-boundary-security-checklist.md

@@ -0,0 +1,319 @@
+# Input Boundary Security Checklist
+
+Use this reference after selecting `input-boundary-validation-review`. It supplies ledgers and
+format-specific review prompts; the skill remains the procedure and command-authority boundary.
+
+## Contents
+
+1. Representation ledger
+2. Field identity policy
+3. Decoder and transport policy
+4. Parser and schema policy
+5. Unicode and identifier policy
+6. Structured sink policy
+7. Format-specific parser limits
+8. Shared resource budget
+9. Boundary test matrix
+10. Primary anchors
+
+## 1. Representation ledger
+
+Record every representation that can affect meaning, identity, authority, cost, or execution.
+
+| Stage | Representation | Owner | Operation | Rejected conditions | Limit and unit | Forwarded value |
+| --- | --- | --- | --- | --- | --- | --- |
+| Transport | wire bytes | server or protocol adapter | framing and content coding | malformed framing, unsupported coding | wire bytes | bounded body stream |
+| Expansion | decoded bytes | decompressor or container adapter | decompression or extraction | checksum, ratio, size, nesting | expanded bytes and ratio | bounded byte stream |
+| Character | Unicode scalars | strict decoder | charset decode | malformed UTF-8, BOM, surrogate | scalar and byte counts | immutable text |
+| Component | component text | URL, form, or escape decoder | one component decode | malformed or recursive escape | decoded component bytes | decoded field |
+| Identity | canonical key | field policy | normalization and folding | disallowed script or control | code points and graphemes | canonical key plus display value |
+| Syntax | parsed value | one parser | full parse | duplicate, trailing data, recovery | tokens, nodes, depth | immutable tree or DTO |
+| Semantics | domain value | domain validator | range and relation checks | invalid state or combination | domain-specific | validated value |
+| Authority | authorized operation | policy owner | actor-resource-action decision | deny, missing context, stale version | decision deadline | bound decision |
+| Effect | structured sink input | repository or adapter | bind or compile | unmapped grammar slot | query, argv, path, output budget | side effect |
+
+For every row, answer:
+
+- Can another layer repeat the operation?
+- Can a raw or earlier representation bypass the forwarded value?
+- Can the operation change length, equality, separators, grammar characters, or resource identity?
+- Does failure reject, repair, replace, truncate, ignore, choose a default, or continue with a
+  warning?
+- Does validation inspect the exact immutable value later authorized and executed?
+
+A matching function name in two services does not prove matching behavior. Compare library,
+version, options, locale, Unicode data, collation, duplicate policy, and error handling.
+
+## 2. Field identity policy
+
+Define policy by field role rather than applying one global sanitizer.
+
+| Field role | Raw retained? | Normalization | Case policy | Script or character policy | Uniqueness owner | Display policy |
+| --- | --- | --- | --- | --- | --- | --- |
+| Opaque server id | normally no client normalization | none beyond format | exact | narrow protocol alphabet | database or registry | canonical id |
+| Username or handle | audit raw only if policy permits | declared NFC or NFKC profile | declared full fold or exact | identifier profile, mixed-script rule | canonical-key unique index | original safe display |
+| Human name | preserve | normally NFC | locale-aware display only | broad text with control policy | no identity inference | escaped and bidi-isolated |
+| Email-like identity | product-specific profile | component-specific | domain and local rules differ | explicit internationalization policy | canonical-key constraint | preserve meaningful spelling |
+| Hostname | optional raw for audit | selected IDNA or UTS #46 profile | profile-owned | label and script checks | canonical ASCII A-label | safe Unicode display separately |
+| Filename label | preserve as metadata | platform-independent display policy | do not infer storage identity | control, separator, bidi policy | server storage key | encoded download label |
+| Enum or sort field | no | none | exact unless contract says otherwise | closed application enum | code map | localized label |
+| Free text | preserve | usually NFC only if required | preserve | reject only unsafe controls for the context | not an identity key | output-context encoding |
+
+Check these invariants:
+
+- Canonicalization is deterministic and idempotent.
+- The canonical key is computed before uniqueness, cache lookup, authorization, signing, and storage
+  decisions that depend on equality.
+- Compatibility normalization is restricted to fields whose semantics permit distinctions to be
+  erased.
+- Confusable skeletons are collision or review signals, not replacement usernames.
+- Default-ignorable, joining, variation, and bidi characters are governed by field and language
+  context rather than globally deleted.
+- Database collation, application comparison, cache keys, and downstream services agree or use the
+  same stored canonical key.
+
+## 3. Decoder and transport policy
+
+Inventory all possible decoders:
+
+- HTTP framing and chunking;
+- content transfer and content coding;
+- compression and archive layers;
+- declared or default charset;
+- UTF-8 or UTF-16 decoding;
+- percent, form, JSON, XML, HTML, shell, or language escapes;
+- base64, quoted-printable, multipart, protobuf, and custom envelopes;
+- URL component parsing and IDNA conversion.
+
+For each decoder:
+
+1. Name the exact input and output type.
+2. Reject malformed encoding rather than replacing, skipping, or guessing.
+3. Decide whether BOM is permitted and where.
+4. Bound input, output, ratio, nesting, and work before materialization.
+5. Reject trailing bytes or concatenated streams unless the format explicitly supports them.
+6. Prevent a later proxy, router, framework, database, filesystem, or client from decoding the value
+   again under another policy.
+
+Test malformed percent escapes, encoded separators, mixed separators, double encoding, invalid UTF-8,
+overlong forms, truncated multibyte sequences, unexpected BOMs, embedded NUL, lone surrogate input,
+and a chunk boundary inside each multibyte or escaped sequence.
+
+## 4. Parser and schema policy
+
+Use one row per externally controlled format.
+
+| Concern | Required decision |
+| --- | --- |
+| Parser | implementation, version, dialect, and option source |
+| Full consumption | EOF required, document count, trailing whitespace policy |
+| Recovery | disabled, or exact compatible cases that remain external-contract safe |
+| Duplicate names | reject before map binding; explicitly model genuine multi-value fields |
+| Unknown fields | reject, preserve, or ignore under one versioned forward-compatibility contract |
+| Coercion | exact accepted input types and every permitted conversion |
+| Numbers | lexical length, integer and fraction digits, exponent, finite range, precision model |
+| Strings | raw bytes, decoded scalar count, normalized length, allowed controls |
+| Containers | maximum depth, keys, elements, attributes, aliases, and total nodes |
+| Polymorphism | closed discriminator map; no client-selected runtime class |
+| External resources | resolver, include, schema, entity, import, and network policy |
+| Side effects | none until complete syntax and semantic acceptance |
+
+Danger signs:
+
+- gateway validates the first duplicate while the application uses the last;
+- query parser turns one occurrence into a scalar and two into an array;
+- schema validator coerces a string but business code reads the original raw value;
+- security gate uses strict JSON while a downstream service accepts comments, trailing commas, or
+  multiple documents;
+- a generic map erases duplicate names before the validator sees them;
+- unknown enum or schema version becomes `DEFAULT`;
+- validation timeout or parser warning falls through to an allow path;
+- deserialization chooses a runtime class from `$type`, `@class`, tag, or user-owned discriminator;
+- a parsed DTO is discarded and the raw string is reparsed for execution.
+
+## 5. Unicode and identifier policy
+
+Review these as separate dimensions:
+
+| Dimension | Questions |
+| --- | --- |
+| Encoding | Is the external charset fixed? Are malformed sequences rejected? |
+| Scalar validity | Are lone surrogates, noncharacters when relevant, and NUL handled explicitly? |
+| Normalization | Is NFC, NFD, NFKC, or NFKD selected per field and applied before validation? |
+| Case | Is exact comparison, locale-independent full folding, or locale display casing intended? |
+| Scripts | Are permitted scripts, mixed-script cases, and digit-set mixing explicit? |
+| Confusables | Is collision detection separate from stored identity? |
+| Ignorables | Are joining controls, variation selectors, soft hyphen, and BOM contextually handled? |
+| Bidi | Are identifiers restricted and displayed text isolated? Are logs escaped visibly? |
+| Length | Which limits use bytes, code points, grapheme clusters, display width, or normalized form? |
+| IDNA | Which profile and version produce the canonical ASCII hostname? |
+
+Keep storage and network protection limits in bytes and code points. Use grapheme clusters only for
+user-visible character counts. Bound combining sequences and post-normalization growth separately
+when they affect cost or storage.
+
+Do not use a visual rendering, lowercase call, or normalization form as an authorization proof.
+Bind authority to the stored canonical identity produced by the declared field policy.
+
+## 6. Structured sink policy
+
+### SQL
+
+- Bind every data value through the driver.
+- Map table, column, sort direction, operator, function, and grouping choice from a closed application
+  enum to fixed code.
+- Reject generic "safe SQL fragment" strings and review ORM raw, native-query, string predicate,
+  relation-path, and order-clause escape hatches.
+- Scope authorization in the query or repository operation, not as a format check before an
+  unscoped lookup.
+
+### NoSQL, search, and expression engines
+
+- Accept a bounded business DTO, not a client-owned query object or DSL.
+- Construct operator trees server-side from a closed mapping.
+- Reject unexpected nested objects, operator-prefixed keys, scripts, unbounded regular expressions,
+  raw aggregation stages, and arbitrary field selection.
+- Bound clause count, array size, date range, regex length, sort fields, result count, and query cost.
+
+### Processes
+
+- Prefer a library API.
+- Fix executable, subcommand, options, environment, working directory, privilege, network policy,
+  time, and output limits.
+- Use an argument array without a shell, but still reject or terminate option parsing for operands
+  that can begin with `-`.
+- Prefer stdin or an already-open file handle for large data. Close inherited file descriptors and
+  terminate descendants on timeout.
+
+### Filesystem and URL resources
+
+- Prefer opaque server-owned resource IDs.
+- Parse URLs into components and compare the canonical host under one IDNA policy.
+- Resolve filesystem access relative to a trusted opened directory or equivalent capability.
+- Treat symlinks, junctions, reparse points, case folding, device namespaces, alternate data streams,
+  trailing dots or spaces, short-name aliases, and time-of-check/time-of-use races as platform
+  concerns, not string-normalization details.
+- Carry the opened handle or verified capability forward rather than reopening a checked string.
+
+### Templates and rendered output
+
+- Treat template source, include names, expressions, and filter selection as deployed code.
+- Copy only inert values into the template context; do not expose request, ORM, configuration,
+  classes, functions, or capability-bearing objects.
+- Encode for the final output context. HTML escaping does not secure JavaScript, CSS, URL, CSV,
+  shell, or template grammar.
+- Bound template CPU, memory, recursion, and output even when a sandbox is enabled.
+
+## 7. Format-specific parser limits
+
+### JSON
+
+- Reject duplicate names, trailing garbage, multiple top-level values, invalid escapes, and lone
+  surrogate values that cannot satisfy the selected interoperability profile.
+- Bound number text before arbitrary-precision conversion: total digits, fraction digits, exponent,
+  and domain range.
+- Disable untrusted polymorphic type selection and bind into a closed DTO.
+
+### XML
+
+- Reject `DOCTYPE` when the contract does not require it.
+- Disable external general and parameter entities, external DTDs, XInclude, network and filesystem
+  resolvers, schema imports, and transformation-time external access.
+- Bound entity expansion, element depth, attribute count, namespace declarations, name length,
+  text-node length, total nodes, and total decoded characters.
+- Treat "secure processing" as a starting configuration whose effective provider limits must be
+  verified, not a magic flag.
+
+### YAML
+
+- Use a safe data loader and a restricted schema. Disable runtime object construction, custom tags,
+  class lookup, and function invocation.
+- Decide whether anchors, aliases, merge keys, directives, and multiple documents are needed; reject
+  them otherwise.
+- Bound alias count, expansion work, depth, nodes, scalar size, and code points before object
+  construction.
+- Validate the loaded data against an explicit DTO or schema after syntax parsing.
+
+### CSV and spreadsheet export
+
+- Use a real CSV parser with fixed charset, delimiter, quote, escape, and newline policy.
+- Bound rows, columns, record length, field length, total decoded bytes, and parse errors.
+- Treat spreadsheet formula interpretation as a separate output sink. CSV quoting is not formula
+  neutralization; prefer a format with explicit text cell types when possible.
+- Do not commit imported rows to production state until the complete bounded import validates.
+
+### Regular expressions
+
+- Prefer a linear-time engine or a structurally safe subset for untrusted text.
+- Require whole-string matching for field validation and check host-language anchor semantics.
+- Bound pattern length, input length, captures, and execution work. Do not accept arbitrary
+  user-supplied patterns unless a dedicated constrained language owns them.
+- Treat a timeout as a last stop, not the proof that a backtracking pattern is safe.
+
+## 8. Shared resource budget
+
+Use one budget or bounded child views across transformations. Do not reset counters at decoder,
+parser, nested-document, or subservice boundaries.
+
+| Counter | Charged when | Typical failure class |
+| --- | --- | --- |
+| `wireBytes` | bytes arrive | request too large |
+| `decodedBytes` | transfer or charset output is produced | decoded input too large |
+| `expandedBytes` | decompression, entity, alias, or archive output is produced | expansion limit |
+| `codePoints` | scalar values are decoded | text limit |
+| `numberDigits` | numeric token is scanned | numeric complexity limit |
+| `tokenCount` | token is accepted | syntax work limit |
+| `nodeCount` | node allocation is attempted | structure limit |
+| `maxDepth` | nested container is entered | nesting limit |
+| `containerItems` | key, value, element, attribute, or row is accepted | breadth limit |
+| `workUnits` | scan, comparison, normalization, regex, or recovery work occurs | complexity limit |
+| `outputBytes` | result, log, rendered text, or child output is produced | output limit |
+| deadline | bounded operation checks time | deadline exceeded |
+
+Charge before allocation or effect. Report the stage, observed amount, configured limit, and stable
+error class without echoing the hostile payload.
+
+## 9. Boundary test matrix
+
+Minimum lanes:
+
+1. Smallest valid value and representative normal values.
+2. Empty, missing, null, wrong scalar type, wrong container type, and scalar-versus-array cases.
+3. Exact lower and upper business bounds plus one step outside.
+4. Whole-string mismatch, trailing newline, trailing garbage, and multiple-document cases.
+5. Duplicate key or parameter with equal values, conflicting values, and order reversal.
+6. Unknown field, enum, discriminator, and schema version.
+7. Invalid UTF-8, truncated escape, NUL, unexpected BOM, and invalid scalar sequence.
+8. NFC/NFD equivalents, NFKC-changing forms, case-fold expansion, mixed scripts, confusables,
+   default ignorables, bidi controls, and combining-mark growth.
+9. Raw, decoded, normalized, parsed, and output limits immediately below, at, and above the cap.
+10. Deep, wide, long-scalar, huge-number, alias, entity, regex, compression, and output-cost cases.
+11. Dynamic SQL identifier, NoSQL operator, process option, path separator, URL host, template
+    expression, and spreadsheet-formula attempts at the exact grammar boundary.
+12. Valid identifier without ownership, tenant membership, state permission, or action permission.
+13. Gateway-versus-application and application-versus-database differential cases.
+14. No side effect after every rejection, timeout, parser warning, and exhausted budget.
+
+For accepted inputs, assert the canonical typed value and final structured sink shape. For rejected
+inputs, assert the earliest stable rejection stage, error code, bounded work, and absence of side
+effects or permissive defaults.
+
+## 10. Primary anchors
+
+- [OWASP Input Validation Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html): syntactic versus semantic validation, early validation, allowlists, whole-string regular expressions, and the boundary between input validation and injection defenses.
+- [WHATWG URL Standard](https://url.spec.whatwg.org/): component parsing, percent encoding and decoding, host processing, UTF-8 behavior, and URL validation errors.
+- [RFC 3629](https://www.rfc-editor.org/rfc/rfc3629): UTF-8 validity, shortest-form encoding, scalar range, and decoder security considerations.
+- [RFC 8259](https://www.rfc-editor.org/rfc/rfc8259): JSON grammar, interoperability, duplicate member names, numbers, strings, and parser behavior.
+- [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785): JSON canonicalization input constraints and deterministic serialization requirements.
+- [Unicode Standard Annex #15](https://www.unicode.org/reports/tr15/): canonical and compatibility normalization forms, stability, idempotence, and the warning against blindly applying compatibility normalization to arbitrary text.
+- [Unicode Technical Standard #39](https://www.unicode.org/reports/tr39/): identifier profiles, restriction levels, mixed scripts, confusables, and security mechanisms.
+- [Unicode Technical Standard #46](https://www.unicode.org/reports/tr46/): IDNA compatibility processing and Unicode-to-ASCII domain mapping.
+- [Unicode Standard Annex #29](https://www.unicode.org/reports/tr29/): grapheme-cluster segmentation for user-visible character counts.
+- [OWASP SQL Injection Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html): parameter binding and fixed mappings for dynamic SQL identifiers.
+- [OWASP NoSQL Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/NoSQL_Security_Cheat_Sheet.html): server-owned query construction, operator control, and query resource limits.
+- [OWASP OS Command Injection Defense Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html): avoiding OS commands, data and command separation, argument injection, and option termination.
+- [OWASP XML External Entity Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/XML_External_Entity_Prevention_Cheat_Sheet.html): DTD, entity, XInclude, resolver, and secure-processing controls.
+- [YAML 1.2.2](https://yaml.org/spec/1.2.2/): YAML representation, serialization, presentation, schema, tag, anchor, alias, and document semantics.
+- [RFC 4180](https://www.rfc-editor.org/rfc/rfc4180): CSV quoting, embedded delimiters, and embedded line breaks.
+- [OWASP ReDoS](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS): catastrophic backtracking and regular-expression denial-of-service risk.
+

package/templates/default/locales/en/.mustflow/skills/input-event-synchronization-review/SKILL.md

@@ -0,0 +1,306 @@
+---
+mustflow_doc: skill.input-event-synchronization-review
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: input-event-synchronization-review
+description: Apply this skill when keyboard, mouse, pointer, touch, pen, wheel, gamepad, raw-input, remote desktop, cloud gaming, remote KVM, focus, capture, IME, clipboard, surface switching, frame or tick input, coalesced events, or input replay code is created, changed, reviewed, debugged, or reported and event loss, duplication, reordering, delay, feedback loops, cancellation, multi-owner state, or stale-session delivery can leave controls stuck or apply input inconsistently.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.input-event-synchronization-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Input Event Synchronization Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review input as a lossy, session-scoped state-reconstruction protocol rather than a complete ledger
+of hardware actions.
+
+The review question is not "did every down receive an up?" It is "when delivery is coalesced,
+duplicated, reordered, dropped, routed elsewhere, or terminated by lifecycle change, can one
+authoritative reducer produce a bounded current state in which every active control ends by release
+or cancel?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code handles keyboard, mouse, pointer, touch, pen, wheel, gamepad, raw device, remote desktop,
+  browser, desktop shell, game engine, canvas, drawing, drag, shortcut, text input, or replay events.
+- Focus, visibility, suspend, resume, device connection, pointer capture, pointer lock, coordinate
+  transforms, frame or simulation ticks, event queues, source sequence, event dedupe, coalescing,
+  modifier state, key repeat, IME composition, or multi-device ownership changes.
+- A bug reports stuck keys, stuck buttons, ghost drags, duplicate clicks, doubled movement, missing
+  movement, wrong shortcuts, input after focus return, capture theft, wheel target changes, or
+  nondeterministic input replay.
+- Code or docs claim that timestamps preserve input order, down and up are paired, FIFO prevents
+  loss, polling repairs every gap, cancellation equals release, or one boolean represents current
+  modifier or button state.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task validates hostile bytes, text, paths, uploads, fields, or decoded payloads; use
+  `input-boundary-validation-review`.
+- The task is ordinary form, query, URL, cache, optimistic, persisted, or server-state ownership
+  without device-event lifecycle; use `frontend-state-ownership-review`.
+- The task is keyboard accessibility, focus order, semantic activation, drag alternatives, or ARIA
+  behavior; use `frontend-accessibility-tree-review`.
+- The main problem is a general shared-memory, lock, atomic, database, or distributed race rather
+  than input-session reconstruction; use `race-condition-review` or
+  `concurrency-invariant-review`.
+- The task is only motion design, animation interruption, or visual gesture feedback; use
+  `motion-system-contract-review`.
+- The code consumes an already normalized immutable input snapshot and does not own ingress,
+  lifecycle, reduction, cursor, capture, or replay semantics.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Source ledger: platform APIs, event producers, polling sources, synthesized or compatibility
+  events, source clock domains, threading boundaries, and the one source authoritative for each
+  control or movement mode.
+- Envelope contract: source, device, control, pointer, session epoch, source sequence, event ID,
+  physical identity, logical meaning, repeat, composition and synthesis flags, modifier snapshot,
+  button bitmask, coordinates, deltas, transform generation, native time, and ingress time.
+- Lifecycle ledger: focus, visibility, suspend, resume, device add or remove, source reset, queue
+  overrun, capture gain or loss, pointer cancel or lock change, and session-generation changes.
+- State model: per-device held controls, derived aggregate modifiers, `Up`, `Down`, `Canceled`,
+  `Press`, `Repeat`, `Release`, `Cancel`, drag phases, wheel ownership, and suppressed
+  recovery state.
+- Delivery model: dedupe identity, source-order rule, reorder window, sequence-gap behavior,
+  snapshot or reset recovery, immutable batch boundary, journal retention, and consumer cursors.
+- Pointer and text evidence: absolute or relative mode, coordinate spaces, transform generation,
+  coalesced-sample choice, capture owner, button semantics, wheel units, AltGraph, layout, IME, and
+  composition paths.
+- Test and observability evidence: invariants, fault cases, bounded input journal, redaction,
+  deterministic fixtures, replay contract, and configured command intents.
+- Remote interaction ledger: session, surface, path and focus epochs; root and parent event lineage;
+  semantic reliability class; deadline and supersession; receive, apply and present acknowledgments;
+  prediction authority; local and remote owners; injection provenance; focus, composition, selection,
+  clipboard and transform versions; state digests; repair ownership; and capture-to-present stages.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked.
+- Platform and source semantics are identified from current code or authoritative documentation, or
+  unknown behavior is reported instead of guessed.
+- Existing ingress, device identity, reducer, frame batch, capture, IME, replay, and diagnostics
+  patterns have been searched before adding new shapes.
+- External specification text is reference evidence only; repository-native contracts own the
+  implementation.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten a single normalization ingress, immutable event envelopes, per-source epochs and
+  sequence, stable event IDs, bounded reorder and dedupe windows, gap recovery, cancel events,
+  per-device control sets, pure reducers, immutable tick batches, consumer cursors, capture tokens,
+  coordinate generations, diagnostics, and focused input fixtures.
+- Separate physical control identity from logical key or text meaning, held state from edge
+  transitions, release from cancel, momentary modifiers from toggles and latches, and raw movement
+  from framework-synthesized compatibility events.
+- Add source-specific compaction rules that preserve non-droppable transitions.
+- Add semantic transport classes, state snapshots, application acknowledgments, lineage-preserving
+  loop guards, owner leases, reconnect neutralization barriers, versioned interaction contexts,
+  bounded causal telemetry, virtual-clock replay, and repair events for remote-input paths.
+- Do not invent a global event order across independent clock or source domains.
+- Do not use timestamps, sleeps, focus polling, process-local booleans, or input queue names as
+  correctness proof.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Map every producer and choose one authoritative ingress for each input mode.
+   - Event handlers normalize and enqueue; they do not directly mutate gameplay, command, drag, or
+     business state.
+   - When raw and synthesized paths describe the same action, name one state-producing source and
+     keep the other diagnostic or compatibility-only.
+2. Freeze an immutable envelope at ingress.
+   - Preserve source, device, epoch, source sequence or earliest-ingress sequence, event identity,
+     physical and logical control data, snapshots, coordinates, transform generation, and
+     provenance flags.
+   - Use timestamps for latency and diagnostics, not causal order across clock domains.
+3. Treat events as deltas, not current-state proof.
+   - Detect duplicate identity, old epoch, out-of-window order, and sequence gaps before reduction.
+   - On a gap, stop applying untrusted deltas. Requery an authoritative device snapshot when the
+     platform supports it; otherwise cancel active state for that source and start a new epoch.
+4. Make lifecycle loss a terminal input event.
+   - Focus loss, visibility loss, suspend, device removal, queue overrun, capture loss, pointer
+     cancel, and source reset flow through one ordered `CancelAll(reason, oldEpoch)` path.
+   - Reject late events from the old epoch. Do not wait forever for a release routed elsewhere.
+5. Reduce physical state per source and device.
+   - Pair press and release by physical control identity, not translated text.
+   - Track holders as a set of devices or pointers. Derive aggregate Shift, Control, Alt, Meta, or
+     button state instead of overwriting one boolean.
+6. Separate persistent state from edge records.
+   - Held state is reducer output. Press, repeat, release, and cancel are immutable transition
+     records.
+   - Duplicate down while already down becomes repeat or diagnostic duplicate; release while up is
+     harmless and observable rather than a negative counter.
+7. Classify keyboard semantics.
+   - Use physical identity for held controls and gameplay bindings; use logical meaning and text
+     composition for text.
+   - Treat auto-repeat as policy input, not another press. Define hold, repeat, and one-shot commands
+     separately.
+   - Derive left and right modifiers independently. Distinguish momentary, toggle, and latch state.
+   - Give AltGraph and composition paths precedence over ordinary character shortcuts when the
+     platform reports them. Keep command handling separate from IME text commitment.
+8. Recover focus without synthesizing commands.
+   - If current device state can be queried, represent controls already held at return as
+     suppressed held state until a real release and new press occur.
+   - Use polling only as a bounded recovery snapshot. Do not use ambiguous edge bits or sampled
+     state to manufacture missed presses.
+9. Cut one immutable batch per frame or simulation tick.
+   - Do not let mid-tick arrivals mutate the snapshot already visible to earlier systems.
+   - Keep the journal immutable and give UI, gameplay, shortcuts, replay, and diagnostics separate
+     cursors or projections. One consumer must not destructively steal another's edge.
+10. Apply compaction by semantic class.
+    - Never drop or merge press, release, cancel, focus, capture, epoch, device, or mode transitions.
+    - Sum relative camera deltas, retain ordered drawing samples, keep the latest absolute hover
+      position, and accumulate wheel precision according to the consumer contract.
+    - Choose either the representative coalesced event or its original samples for one path, never
+      both.
+11. Keep coordinate and movement modes explicit.
+    - Do not derive relative movement from clamped absolute coordinates.
+    - Invalidate old absolute baselines on mode changes and mark warp-generated samples.
+    - Freeze the coordinate space and transform generation used at ingress so a later window, DPI,
+      viewport, zoom, or canvas change cannot reinterpret history.
+12. Model gestures and capture as state machines.
+    - Use explicit idle, armed, dragging, clicked or released, and canceled states. Measure drag
+      thresholds from the original anchor.
+    - Bind capture to pointer, generation, and owner. Confirm acquisition and loss events; only the
+      current owner token can release current capture.
+    - Reconcile current button bitmasks with internal state without inventing a new press when the
+      gesture never observed one.
+13. Model wheel delivery as a gesture transaction.
+    - Preserve unit or mode and fractional precision.
+    - Hold one wheel owner for the platform transaction or bounded idle phase. Do not assume pointer
+      capture owns wheel routing.
+14. For remote input, classify preservation semantics before choosing transport behavior.
+    - Treat absolute state as supersedable, relative movement as range-summed, pen or touch as a
+      path, press and release as idempotent boundaries, and focus, composition, clipboard, or
+      surface changes as ordered interaction transactions.
+    - Carry session, surface and path epochs, source and root identity, sequence, deadline, state
+      version, and reliability class. Transport receipt is not application acceptance.
+    - Separate receive, reducer-apply, and displayed-frame acknowledgments. Bound queues by oldest
+      still-useful input age and preserve boundary events under pressure.
+15. Prevent local-to-remote feedback loops by provenance, not timing guesses.
+    - Preserve origin, root event, parent event, apply context, hop path, and propagation policy
+      through adapters and derived commands.
+    - Keep capture and remote-apply paths separate. Exclude a dedicated injected source or exact
+      session marker at ingress; do not suppress similar local input inside a time window.
+    - Track held controls by owner and press identity. Use resource-specific arbitration for shared
+      modifiers, exclusive drags or composition, cursor control, clipboard, and local takeover.
+16. Version the remote interaction context.
+    - Separate operating-system activation, document visibility, active remote surface, and editing
+      focus. Make focus a request, application, and confirmed-generation protocol.
+    - Choose exactly one IME authority. Version composition, text, selection and target ranges;
+      close composition before focus or surface generation changes.
+    - Treat clipboard as a versioned multi-representation object with origin and content policy.
+      Advertise metadata before transferring selected content on a lower-priority path.
+    - Neutralize held state, capture, drag and composition before admitting a reconnect or new
+      surface epoch. Resume only after state and transform acknowledgment.
+17. Make remote-input failures replayable without logging user content.
+    - Link capture, normalize, queue, send, receive, validate, dedupe, apply, render, present, drop,
+      acknowledge and repair stages by event, root, frame, epoch and state hashes.
+    - Preserve source occurrence and component observation times separately. Use sequence and parent
+      relationships for causality; use clock estimates only for latency.
+    - Record high-frequency summaries in a bounded low-overhead ring, snapshot at semantic
+      boundaries, replay normalized events under a virtual monotonic clock, and compare the first
+      state-hash divergence.
+18. Read [Input Session State Checklist](references/input-session-state-checklist.md) for the
+    detailed envelope, transition, compaction, recovery, and fault matrices.
+19. Read [Remote Input Transport and Interaction Checklist](references/remote-input-transport-interaction-checklist.md) when input crosses a process, host, network, injected-device, or rendered-frame boundary.
+20. Require adversarial evidence.
+    - Inject duplicate, gap, reordering, coalescing, focus loss, device removal, capture theft,
+      suspend, mode change, multi-device holds, repeat, AltGraph, composition, and tick-boundary
+      arrival.
+    - Assert that every active control terminates by release or cancel, aggregate state equals its
+      holders, old epochs cannot mutate current state, one source action is not applied twice, and
+      every consumer sees one immutable batch.
+    - If configured proof is unavailable, report the static invariant gap instead of approving the
+      path.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Source authority, envelope, identity, epoch, ordering, gap recovery, lifecycle cancellation,
+  physical and logical key model, device ownership, reducer, immutable batch, consumer cursors,
+  compaction, coordinates, capture, wheel, IME, diagnostics, and test evidence are explicit.
+- Missing release, duplicate down, old-session delivery, queue loss, timestamp sorting, global-order
+  invention, destructive edge reads, raw-plus-synthesized duplication, modifier collapse, repeat
+  commands, composition leakage, stale capture release, doubled coalesced movement, transform drift,
+  and unowned wheel gestures are fixed or reported.
+- Input synchronization claims are backed by configured tests, replayable fixtures, platform
+  evidence matched to current code, or labeled as static review risk.
+- Remote-input claims also expose semantic delivery class, loop prevention, ownership arbitration,
+  interaction-context versions, acknowledgment layer, causal trace, repair path, and
+  capture-to-present evidence.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured intent that covers the changed input boundary and synchronized
+template surfaces. Do not infer raw device tools, live input recorders, browser sessions, game
+loops, watchers, accessibility tools, or platform diagnostics outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the authoritative source, device identity, epoch, or gap recovery rule cannot be named, report
+  that current input state is not reconstructable.
+- If safe recovery requires platform state queries, native integration, device fixtures, or a replay
+  harness outside scope, keep cancel-and-new-epoch behavior fail-safe and report the missing proof.
+- If privacy-sensitive key or text content would enter diagnostics, keep physical identities,
+  lifecycle, sequence, and invariant counters while redacting text and user content.
+- If a configured command fails, preserve the failing input invariant and fixture before editing
+  again.
+- If deterministic input proof is not configured, report the missing manual or integration evidence
+  and defer rather than inventing a raw command.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Input synchronization boundary reviewed
+- Source authority and envelope
+- Epoch, sequence, dedupe, gap, lifecycle, reducer, physical/logical key, modifier, repeat, IME,
+  batch, cursor, compaction, coordinate, gesture, capture, wheel, remote transport, lineage, loop,
+  arbitration, focus, clipboard, surface, acknowledgment, observability, replay, and test findings
+- Input synchronization fixes made or recommended
+- Evidence level: configured-test evidence, platform evidence, replay fixture, static review risk,
+  manual-only, missing, or not applicable
+- Command intents run
+- Skipped input diagnostics and reasons
+- Remaining input-event synchronization risk