jspurefix 5.3.0 → 5.5.4

package/BACKPORT_PLAN.md

@@ -215,11 +215,9 @@ Storm protection was largely wired during PR 3C/3D. Remaining gaps completed:
 
 | File | Action |
 |------|--------|
-| `src/config/js-fix-config.ts` | Add optional `resendGapFillOnly?: boolean` |
-| `src/store/fix-msg-ascii-store-resend.ts` | Early return path when enabled — always GapFill instead of replaying |
-| New: `src/test/store/resend-gap-fill-only.test.ts` | ~3 tests |
+### Status: **DONE**
 
-Can be done at **any time** — independent of all other PRs.
+Added `resendGapFillOnly` option to `StoreConfig`. When enabled, `FixMsgAsciiStoreResend` always returns a single GapFill instead of replaying stored messages — prevents accidental duplicate order execution for client/initiator sessions. 5 tests added.
 
 ---
 
@@ -250,17 +248,129 @@ PR 5B (ResendGapFillOnly) ──── independent, can be done anytime
 | 4C | Low | New file, tested with mocks — **DONE** (PR #120) |
 | 4D | Medium | Changes send path, store errors must not block sends — **DONE** |
 | 5A | Low | Wiring only, coordinator makes decisions — **DONE** |
-| 5B | None | Additive config option |
+| 5B | None | Additive config option — **DONE** |
 
 ---
 
-## Phase 6: Message Generator / XML Parser (Future)
+## Phase 6: QuickFix XML Parser Rework
+
+**Priority: Medium | Risk: HIGH | Scope: Large (multi-session)**
+
+### Background
+
+The C# QuickFix XML parser (`QuickFixXmlFileParser.cs`) is architecturally superior:
+- **DOM-based**: parses XML once into `XDocument`, then walks the tree
+- **Graph-based resolution**: nodes + edges + work queue, deterministic single logical pass
+- **Post-processor**: `IndexVisitor` + `ContainedFieldCollector` with memoisation ensures every `ContainedFieldSet` knows all tags below it
+- **Pre-parse validation**: `DictionaryValidator` catches missing fields, duplicates, undefined references with Levenshtein typo suggestions
+
+The TS parser uses SAX streaming with iterative N-pass (up to 5x) forward reference resolution. This works but is fragile, hard to reason about, and diverges from C#.
+
+**Scope**: Only the QuickFix parser chain needs rework. FIXML (XSD, already has include graph) and Repository (sequential file parsing) are fine as-is.
+
+### Strategy: SAX → In-Memory Tree → Graph Resolution
+
+Rather than replacing SAX with a new XML library, wrap SAX to build a lightweight in-memory element tree on a single pass. This tree then provides DOM-like random access for the graph resolver, without introducing new dependencies.
+
+```typescript
+interface XElement {
+  name: string
+  attributes: Record<string, string>
+  children: XElement[]
+  line?: number
+}
+```
+
+### Delivery: 6 PRs
+
+#### PR 6A: XElement tree builder (new files only, zero risk)
+
+### Status: **DONE** (PR #124)
+
+`XElement` interface + `XDocument`/`XNode` query wrappers + `SaxTreeBuilder` (single SAX pass → in-memory tree). 51 tests across all FIX dictionaries.
+
+#### PR 6B: DictionaryValidator (new files only, zero risk)
+
+### Status: **DONE**
+
+Three-pass validator ported from C#: collect definitions, validate references (with Levenshtein "did you mean" suggestions), check unused definitions. 40 tests including validation against all real FIX dictionaries.
+
+#### PR 6C: Graph-based parser + IndexVisitor (medium risk)
+
+### Status: **DONE**
+
+Verbatim port of C# `QuickFixXmlFileParser`: `GraphNode`/`Edge`/`NodeElementType` + work queue + field/component/group/message resolution. New parser sits alongside legacy parser for safe comparison testing.
+
+Includes `IndexVisitor` post-processor (originally PR 6D, merged into 6C because the parser doesn't work without it). Walks every message in post-order, clears aggregated tag indices on each set, and re-adds direct fields via `ContainedSetBuilder` so parents correctly know all descendant tags.
+
+**Comparison test results:** Graph parser produces a **superset** of legacy parser output for FIX50SP2 — correctly resolves deeply nested forward references (e.g., DividendFXTriggerDateBusinessCenter chain) that the legacy 5-pass iterative parser truncates. This is a correctness improvement.
+
+41 new tests including comparison against legacy parser for FIX 4.2, 4.3, 4.4, and 5.0SP2.
+
+#### PR 6E: Switch default parser (HIGH risk)
+
+### Status: **DONE**
+
+Added `QuickFixGraphFileParser` adapter that extends `FixParser` and matches the legacy parser's `(MakeDuplex, GetJsFixLogger)` constructor signature. `DefinitionFactory.getParser()` now instantiates the graph parser for QuickFix XML — all dictionary loading goes through the graph parser by default.
+
+The legacy `QuickFixXmlFileParser` remains exported for backward compatibility (anyone importing it directly still gets the old behaviour), but no production code in the project uses it.
+
+**Test fallout fixed:**
+- `src/test/env/data/fix5-mod.xml` had a redundant 215-line "admin fields" section that duplicated 62 fields already present in the canonical fields section. Plus the `HopGrp` and `MsgTypeGrp` components were defined twice. The legacy parser silently swallowed both classes of duplicate; the graph parser's validator correctly flags them as errors. Removed the redundant admin section (kept the unique `OTP` custom tag) and the duplicate component definitions.
+- `src/test/ascii/qf-50sp2-dict.test.ts` had two assertions where `Instrument` and `TrdCapRptSideGrp` were expected as `required=false` for TradeCaptureReport. The dictionary clearly says `required='Y'` for both. The legacy parser was producing `required=false` (a real bug); the graph parser correctly returns `true`. Updated the assertions.
+- Updated `getTrimDefinitions` in the same file to use `QuickFixGraphFileParser` instead of the legacy parser for consistency.
+
+All 533 tests pass with the graph parser as the default.
+
+Note: `parse-progress.ts`, `parse-state.ts`, and the legacy parser itself are NOT yet deleted — that's deferred to a follow-up cleanup PR after a release cycle to give downstream consumers time to migrate.
+
+#### PR 6F: Fix Trim function (medium risk)
+
+### Status: **DONE — TS trim was already correct**
+
+After investigation: the TS trim function (`QuickFixXmlFileBuilder`) is correct. The "bug" we suspected was actually introduced during the C# port — see C# commit `2ee4620c`. The original C# `WriteComponents` used a `foreach` over a snapshot of `_seenComponents`, dropping any components discovered during iteration. The C# fix added `ProcessComponentFields` for eager recursive collection.
+
+The TS version uses `while (components.length > 0) { components.pop() }` — a proper iterative discovery loop where newly-pushed components are processed in subsequent iterations. This pattern doesn't have the bug.
+
+**Added** comprehensive round-trip tests in `src/test/dictionary/trim-round-trip.test.ts`:
+- Trim → reparse with strict graph parser validation
+- Compare flattened tag sets at the message level
+- Deep nested-set comparison (every component/group in every message)
+- Worst case: trim ALL 116 FIX50SP2 messages and deep-compare every one
+
+All 9 tests pass. No code changes needed to `quick-fix-xml-file-builder.ts`.
+
+### Dependency Graph
+
+```
+PR 6A (XElement tree) ──────────┐
+                                 ├──→ PR 6C (Graph parser) ──→ PR 6E (Switch default)
+PR 6B (DictionaryValidator) ───┘                │
+                                                 ↓
+                                      PR 6D (IndexVisitor) ──→ PR 6E
+                                      
+PR 6F (Fix Trim) ──── after 6C is stable
+```
+
+### Risk Summary
+
+| PR | Risk | Reason |
+|----|------|--------|
+| 6A | None | New files only, SAX wrapper — **DONE** (PR #124) |
+| 6B | None | New files only, validation — **DONE** |
+| 6C | Medium | Graph parser + IndexVisitor — sits alongside legacy parser — **DONE** |
+| 6D | (merged into 6C) | IndexVisitor was needed for 6C to work correctly |
+| 6E | HIGH | Switches default parser — exposed 2 legacy parser bugs (now fixed) — **DONE** |
+| 6F | None | TS trim already correct — round-trip tests added — **DONE** |
+
+### Test Strategy
 
-**Priority: Low | Risk: Medium | Scope: Large**
+The parser is the foundation of the entire system. Test strategy must be comprehensive:
 
-- C# uses nested types for groups (sub-types) in generated code
-- QuickFix XML parser has improved design with better error tracking
-- Nice to align for maintenance but not critical
+1. **Comparison tests**: parse every FIX XML dictionary (4.2, 4.3, 4.4, 5.0SP2) with both old and new parser, diff the resulting `FixDefinitions`
+2. **Round-trip tests**: parse → trim → reparse, verify definitions match
+3. **Micro-dictionary tests** (future hardening): use Trim to create single-message dictionaries, then mutate them (remove fields, duplicate tags, etc.) to test validator edge cases
+4. **Regression anchor**: snapshot the `FixDefinitions` output for each FIX version before any changes — tests assert against snapshots
 
 ---
 

package/DEMO_PORT_PLAN.md

@@ -0,0 +1,286 @@
+# Demo Port Plan: cspurefix standalone-demo → jspf-demo
+
+## Background
+
+With Phase 6 of the cspurefix backport complete (jspurefix 5.5.0), jspurefix is at functional parity with cspurefix. The next major track is bringing `~/dev/ts/jspf-demo` up to the level of `~/dev/cs/purefix-standalone-demo` — the C# reference application that has been built up incrementally over months of soak testing.
+
+The C# standalone demo is the **golden source for "what production-grade jspurefix usage looks like"**, including all the bugs that surfaced during a 17-day continuous soak test (Jan 28–Feb 13, 2026: ~92 hours runtime, 12 transport disruptions, 100% recovery, zero manual intervention).
+
+This work follows the same incremental approach as the backport: small PRs, each independently mergeable, each adding a coherent feature and not trying to do everything at once.
+
+---
+
+## Current state of jspf-demo
+
+**What exists** (4 TypeScript files in `src/trade_capture/`):
+- `app.ts` — `AppLauncher extends SessionLauncher` boots client + server in same process
+- `trade-capture-client.ts` — initiator that sends `TradeCaptureReportRequest`, receives reports, hard-coded `done()` after 32s
+- `trade-capture-server.ts` — acceptor that responds with 5 trades + a `setInterval` for live trades
+- `trade-factory.ts` — synthetic trade generator (Gold, Silver, Platinum, Magnesium, Steel)
+
+**What's missing** (in rough order of importance):
+1. State reset on reconnect (timers, counters, caches all leak)
+2. Timer cleanup tracking (the "timer keeps running after disconnect" bug)
+3. CLI options (--client / --server / --skeleton / --store / --disconnect-after)
+4. Config-based scenarios (reset / recovery / broker-reset session configs)
+5. File store wiring and persistent sequence tests
+6. Multi-client support with session registry
+7. Sequence mismatch test scenarios
+8. Skeleton mode and soak-test scripts
+9. README + docs (current README is 3 lines of CI badges)
+10. Trade capture flow alignment with C# (sec def request → 5 securities → trade request → trades)
+
+---
+
+## Scope decisions
+
+**In scope**: everything that demonstrates jspurefix resilience and recovery features, plus the test scenario scripts that validate them. The goal is a reference app that shows how to use jspurefix correctly in production, with smoke tests that exercise the hard cases.
+
+**Out of scope (for now)**:
+- TLS support — nice-to-have, defer to a follow-up if there's demand
+- GC monitoring — .NET-specific; Node has different profiling tools (`--inspect`, V8 heap snapshots) that don't fit the same API
+- `--clients 1..5` multi-initiator support — soak-test scaffolding, not core feature; defer
+- Generated FIX types — `jspurefix` already has runtime parsing; the demo currently uses `ILooseObject`-style access which is fine for a demo
+
+These can become follow-up phases if/when needed.
+
+---
+
+## Lessons learned from C# git history
+
+These are real bugs that surfaced during soak testing in the C# demo. **Each one is a hazard for the TypeScript port.** The plan below explicitly addresses each.
+
+| Bug | Fix | Phase |
+|-----|-----|-------|
+| Unsolicited trade timer kept running after session disconnect — eventually multiple timers running concurrently | Track timer with cancellation token / clearable handle stored as instance field; cancel on `onStopped()` | **D2** |
+| Application state (counters, flags, caches) leaked across reconnects | Explicitly reset all state in `onReady()` | **D2** |
+| Duplicate trade requests sent on reconnect | Add guard flag (`hasSentTradeRequest`) and reset it in `onReady()` | **D2** |
+| Old transport handle still alive when client reconnected fast → multiple sessions for same CompID, each with its own timer | Session registry on acceptor: stop the old session when a new logon arrives with the same CompID | **D6** |
+| Shared parser instance across multiple concurrent sessions caused state corruption | Per-session parser instance via session factory | **D6** |
+| Wildcard `TargetCompID="*"` for multi-client acceptor was overwritten on first logon, breaking subsequent sessions | Store original CompID at factory init; restore on each clone | **D6** |
+| Buffer corruption when OS wakes from sleep mid-read | Already fixed in jspurefix Phase 2 (parser reset on disconnect) ✓ | done |
+| Sequence mismatch loops on reconnect | Already fixed in jspurefix Phase 3 (coordinator) ✓ | done |
+| Hard to debug multi-client logs without session tagging | Tag logs with SenderCompID | **D6** |
+
+The good news: many of the underlying engine bugs are already fixed in jspurefix. The demo-level bugs are application-layer hazards we need to avoid.
+
+---
+
+## Delivery: 9 PRs (D1 through D9)
+
+### PR D1: Hygiene + jspurefix bump (zero risk)
+
+**Goal**: Get the demo onto jspurefix 5.5.0 and modernise the project skeleton.
+
+| File | Action |
+|------|--------|
+| `package.json` | Bump `jspurefix` dependency to `^5.5.0`. Remove unused deps (`request`, `typings`). Add a real `test` script. |
+| `README.md` | Replace 3-line badge-only README with a basic intro that says what the demo does. Add "build / run" section. |
+| `.travis.yml` | Remove (Travis is gone, AppVeyor + GitHub Actions cover us). Keep `appveyor.yml`. |
+| `tslint.json` | Remove (eslint is the canonical linter now). |
+
+**Risk**: None. New deps and docs only.
+
+---
+
+### PR D2: Resilience fixes for the existing flow (low risk, high value)
+
+**Goal**: Fix the hard-won bugs from C# soak testing in the existing TS code, before we add anything new. These are real bugs that exist in the current `trade-capture-client.ts` and `trade-capture-server.ts`.
+
+| File | Action |
+|------|--------|
+| `src/trade_capture/trade-capture-server.ts` | Track the `setInterval` handle as a class field. Clear it in `onStopped()` AND at the start of any new request handler (defensive). Currently it's already cleared in `onStopped()` per the agent's read — verify and harden. |
+| `src/trade_capture/trade-capture-client.ts` | Add `onReady()` state reset: clear received trades map, reset any guard flags. Add a `hasSentTradeRequest` guard so reconnect doesn't double-send. The current `done()`-after-32s scheduler should also be guarded against firing twice on reconnect. |
+| `src/trade_capture/trade-capture-server.ts` | Same `onReady()` reset for any server-side state (next trade ID counter is OK to keep monotonic across reconnects but verify). |
+| New: `src/test/trade-capture-resilience.test.ts` | Smoke test: start server, connect client, force disconnect, reconnect, verify exactly one set of trades is exchanged (not two). |
+
+**Risk**: Low. We're hardening existing code, not changing observable behaviour in the happy path.
+
+**Critical**: This PR fixes the "timer keeps running" and "duplicate sends after reconnect" classes of bugs at the demo level. Even before we add CLI options or new features, the existing demo will be more correct.
+
+---
+
+### PR D3: Match the C# trade capture flow (low risk)
+
+**Goal**: Make the message flow match the C# reference: client requests securities first, then requests trades after receiving 5 security definitions.
+
+**Why**: Two reasons:
+1. It exercises more of the FIX surface (SecurityDefinition messages)
+2. It's the canonical flow the C# demo uses, which means test scripts written against C# can be ported with minimal changes
+
+| File | Action |
+|------|--------|
+| `src/trade_capture/trade-capture-client.ts` | In `onReady()`: send `SecurityDefinitionRequest` for `MarketID="20"` instead of going straight to `TradeCaptureReportRequest`. On receiving each `SecurityDefinition`, increment counter; once 5 received, send `TradeCaptureReportRequest`. |
+| `src/trade_capture/trade-capture-server.ts` | Add handler for `SecurityDefinitionRequest` that responds with 5 `SecurityDefinition` messages (Gold/Silver/Platinum/Copper/Steel — match C# names). Existing `TradeCaptureReportRequest` handler unchanged. |
+| `src/trade_capture/trade-factory.ts` | Add helper for `SecurityDefinition` message construction. |
+
+**Risk**: Low. New message handlers added, existing ones unchanged.
+
+---
+
+### PR D4: CLI options + mode switching (medium risk)
+
+**Goal**: Replace the hard-coded "boot client and server in same process" launcher with a real CLI that can run client-only, server-only, or both.
+
+| File | Action |
+|------|--------|
+| New: `src/cli/cli-options.ts` | Define CLI shape using `commander` or `yargs` (we should agree which — leaning `commander` for simplicity). Options: `--client`, `--server`, `--config <path>`, `--store <dir>`, `--disconnect-after <secs>`, `--timeout <secs>`, `--skeleton`, `--log`. |
+| New: `src/cli/cli-options-binder.ts` | Validate flags (mutually exclusive flags, range checks). |
+| `src/trade_capture/app.ts` | Refactor `AppLauncher` to accept `CliOptions`. Dispatch to `runClient()`, `runServer()`, or `runBoth()`. Preserve "run both" as the default for backward compat. |
+| New: `src/cli/index.ts` | Entry point that parses argv and calls the launcher. |
+| `package.json` | Update bin/scripts so `npm run tcp-tc` still works but new CLI is also available. |
+
+**Risk**: Medium. Touches the entry point and could break the existing `npm run tcp-tc` workflow if not done carefully. Mitigation: preserve the existing behaviour as the default mode.
+
+---
+
+### PR D5: File store + persistent scenario configs (medium risk)
+
+**Goal**: Wire up the `IFixSessionStore` (added in jspurefix Phase 4) to the demo so we can run reset / recovery / broker-reset scenarios. This is where persistence comes online.
+
+| File | Action |
+|------|--------|
+| New: `data/session/recovery-initiator.json` | File store, ResetSeqNumFlag=N, port 2345, store dir `store/initiator`. Mirrors C# `recovery-initiator.json`. |
+| New: `data/session/recovery-acceptor.json` | File store, ResetSeqNumFlag=N, port 2345, store dir `store/acceptor`. |
+| New: `data/session/broker-reset-initiator.json` | File store, client wants resume (reset=N), reconnectSeconds=10, store dir `store/broker-initiator`. |
+| New: `data/session/broker-reset-acceptor.json` | File store, server forces reset (reset=Y), store dir `store/broker-acceptor`. |
+| `src/trade_capture/app.ts` | Pick up `--store <dir>` from CLI to override store factory at runtime (matches C# behaviour). |
+| `data/session/test-initiator.json` / `test-acceptor.json` | Document them as the "reset mode (default)" configs. Keep their behaviour unchanged. |
+| New: `src/test/file-store-roundtrip.test.ts` | Smoke test: run a session with file store, kill it, restart, verify sequences resumed. |
+
+**Risk**: Medium. The file store API was added recently — needs careful testing in the demo context.
+
+---
+
+### PR D6: Multi-client + session registry (medium-high risk)
+
+**Goal**: Support multiple concurrent clients to the same acceptor without state corruption. This is where the hardest soak-test bugs lived in C#.
+
+**Note**: the C# `SessionRegistry` is itself work-in-progress (lost when leaving the hedge fund where the original was written). The broader vision is loading ~20 broker dictionaries and using first-message metadata to dispatch — that's a future expansion. For D6 we're building the **minimum viable registry** to fix the stale-transport bug.
+
+| File | Action |
+|------|--------|
+| New: `src/trade_capture/session-registry.ts` | A map from `(SenderCompID, TargetCompID)` to active session. On new logon, stop the old session for the same key before accepting. Designed so the broker-multiplex use case can be layered on later. |
+| `src/trade_capture/trade-capture-server.ts` | Use the registry to detect and stop stale sessions. |
+| `data/session/multi-client-acceptor.json` | New config with `TargetCompID="*"` (wildcard mode). |
+| `src/trade_capture/app.ts` | If `TargetCompID === "*"`, clone the description per session so each session has its own actual TargetCompID after logon. Store the original `*` value at factory init. |
+| Logging | Tag every log line with the session's SenderCompID so multi-client logs can be traced. |
+| New: `src/test/multi-client.test.ts` | Two clients connecting concurrently, both receive trades, no cross-talk, no duplicate timers. |
+
+**Risk**: Medium-high. This is where most of the C# soak-test bugs lived. The session registry is new code; the wildcard CompID handling is tricky.
+
+**Future expansion** (post-D6, not in scope here):
+- Load multiple broker dictionaries at startup
+- Inspect first message of incoming FIX file/connection to pick the right dictionary
+- Expose registry state to a React frontend (or any HTTP/SSE consumer)
+- This was the original use case at the hedge fund — capture it as a follow-up phase once the basic registry is solid.
+
+---
+
+### PR D7: Scenario test scripts (low risk, high value)
+
+**Goal**: Port the C# `test-scenarios.sh` to TypeScript-runnable scenarios. These are the smoke/soak tests that drove all the bug fixes.
+
+| File | Action |
+|------|--------|
+| New: `scripts/test-scenarios/seq-mismatch.ts` | Truncate client sequence, restart, verify mismatch recovery loop completes. |
+| New: `scripts/test-scenarios/server-bounce.ts` | Server timeout, restart, client should resume. |
+| New: `scripts/test-scenarios/client-bounce.ts` | Client timeout, restart, server should accept resumed client. |
+| New: `scripts/test-scenarios/broker-reset.ts` | First session establishes sequences, second session has server send `ResetSeqNumFlag=Y`, verify reset to 1. |
+| New: `scripts/test-scenarios/run-all.sh` | Wrapper that runs all scenarios in sequence, reports pass/fail. |
+| `package.json` | Add scripts: `npm run scenario:seq-mismatch`, `npm run scenario:all`, etc. |
+
+**Risk**: Low. These are test scripts that exercise the demo, not changes to production code. If they break, they break in obvious ways.
+
+**Implementation note**: prefer Node scripts over bash where possible — easier for cross-platform (Windows/macOS/Linux) and avoids the bash compatibility issues the C# demo has between `.sh` and `.ps1`.
+
+---
+
+### PR D8: Skeleton mode + long-running smoke test (low risk)
+
+**Goal**: Add skeleton mode (heartbeat-only handler) to enable long-running stability tests without trade traffic noise.
+
+| File | Action |
+|------|--------|
+| New: `src/trade_capture/skeleton-handler.ts` | Bare-bones session that accepts logon and exchanges heartbeats only. Does not subscribe to trades, does not handle app messages beyond logging. |
+| `src/trade_capture/app.ts` | Add `--skeleton` CLI flag that swaps in `SkeletonHandler` instead of full client/server. |
+| New: `scripts/soak-test.sh` | Mirror C# `soak-test.sh`: kill any running, start skeleton server + client, wait. |
+| New: `docs/soak-testing.md` | How to run the soak test, what to look for in heap snapshots, expected memory profile. |
+
+**Risk**: Low. New mode, doesn't touch existing code paths.
+
+---
+
+### PR D9: Documentation (zero risk)
+
+**Goal**: Real README + scenario docs so a new user can understand what the demo does and how to extend it.
+
+| File | Action |
+|------|--------|
+| `README.md` | Real intro: what the demo is, what it demonstrates, quickstart, CLI reference, scenario list. |
+| New: `docs/architecture.md` | Diagram of client/server flow, session lifecycle, state reset on reconnect. |
+| New: `docs/scenarios.md` | Each scenario script: what it tests, what it proves, how to run it, what success looks like. |
+| New: `docs/extending.md` | How to add new message handlers, how to wire your own application logic. |
+
+**Risk**: None. Docs only.
+
+---
+
+## Dependency graph
+
+```
+D1 (hygiene) ──→ D2 (resilience fixes) ──→ D3 (sec def flow) ──→ D4 (CLI)
+                                                                     │
+                                                                     ↓
+                                          D5 (file store) ──→ D6 (multi-client)
+                                                                     │
+                                                                     ↓
+                                                              D7 (scenarios)
+                                                                     │
+                                                                     ↓
+                                                              D8 (skeleton/soak)
+                                                                     │
+                                                                     ↓
+                                                              D9 (docs)
+```
+
+Most PRs are sequential because they build on each other (CLI → store → multi-client → scenarios). D1 and D9 can happen out of order if useful.
+
+---
+
+## Risk summary
+
+| PR | Risk | Reason |
+|----|------|--------|
+| D1 | None | Deps + docs |
+| D2 | Low | Hardens existing code, no new flows |
+| D3 | Low | New message handlers, existing ones unchanged |
+| D4 | Medium | Refactors entry point |
+| D5 | Medium | New persistence, depends on Phase 4 store API |
+| D6 | Medium-high | Concurrency, hard bugs lived here in C# |
+| D7 | Low | Test scripts only |
+| D8 | Low | Additive new mode |
+| D9 | None | Docs |
+
+---
+
+## General principles (reminder, same as backport plan)
+
+1. **Incremental PRs** — one PR per phase, smallest safe changes
+2. **Tests first** — write the smoke test before the fix
+3. **Maintain backward compat** — `npm run tcp-tc` should keep working through every PR
+4. **Each PR is independently mergeable and useful** — no half-finished features
+5. **Reference the C# demo when in doubt** — it's the golden source
+6. **Move slowly** — this is a lot of work and will span multiple sessions
+
+---
+
+## Decisions
+
+1. **CLI library**: either `commander` or `yargs` is fine — both are mature and well-supported. Pick whichever feels cleaner when we get to D4 (no strong preference).
+
+2. **Session registry**: this is application-level code, not in jspurefix itself. The concept comes from real-world hedge fund work where one server hosts ~20 broker dictionaries simultaneously and uses metadata from the first FIX message to pick the right one. The registry there fed into a React frontend for selecting brokers. **The C# `SessionRegistry` is itself a work-in-progress** — work that was lost when leaving the fund and needs re-adding. So in D6 we're not just porting an existing piece, we're collaboratively designing it. Keep it minimal in D6 (just enough to fix the multi-client stale-transport bug); the broader broker-multiplex use case is a future expansion.
+
+3. **TypeScript modernisation in jspf-demo**: defer. The existing TS in the demo is old, but stack-wide modernisation can wait until D1–D9 are done. We don't want to mix two refactors.
+
+4. **Test framework**: **jest**, for consistency with jspurefix and the user's other projects.

package/dist/dictionary/parser/quickfix/dictionary-validator.d.ts

@@ -0,0 +1,39 @@
+import { XDocument } from './x-element';
+import { ValidationError } from './validation-error';
+export declare class DictionaryValidator {
+    private readonly _errors;
+    private readonly fieldsByName;
+    private readonly fieldsByTag;
+    private readonly componentsByName;
+    private readonly messagesByName;
+    private readonly messagesByMsgType;
+    private readonly fieldNamesCaseInsensitive;
+    private readonly componentNamesCaseInsensitive;
+    private readonly referencedFields;
+    private readonly referencedComponents;
+    private readonly allFieldNames;
+    private readonly allComponentNames;
+    get errors(): ReadonlyArray<ValidationError>;
+    get hasErrors(): boolean;
+    get hasWarnings(): boolean;
+    validate(doc: XDocument): void;
+    throwIfErrors(): void;
+    private collectFieldDefinitions;
+    private validateFieldDefinition;
+    private validateFieldEnums;
+    private collectComponentDefinitions;
+    private validateComponentDefinition;
+    private collectMessageDefinitions;
+    private validateMessageDefinition;
+    private validateHeader;
+    private validateTrailer;
+    private validateComponentReferences;
+    private validateMessageReferences;
+    private validateFieldReferences;
+    private validateComponentReference;
+    private checkUnusedDefinitions;
+    private addError;
+    private addWarning;
+    static findSimilar(input: string, candidates: string[]): string | null;
+    static levenshteinDistance(s1: string, s2: string): number;
+}