@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/docs/graph/performance/2026-06-18-phase-1-4-disposable-validation-gate.md

@@ -0,0 +1,97 @@
+# Phase 1.4 Disposable Validation Gate
+
+Date: 2026-06-18
+Branch: `codex/large-graph-performance-experience`
+Task: `1.4`
+
+## Purpose
+
+This note closes the Phase 1 validation gate before product behavior changes. It records how generated large graphs are measured, how real graph snapshots should be handled, which browser environment is usable, what stress limits are realistic, and which assumptions must stay portable for a future desktop app.
+
+## Validation Result
+
+The current offline graph entry can load generated large graph shapes without new product-code integration. The dedicated runner builds temporary offline HTML from generated graph data, opens it in Playwright Chromium, records fixed-schema measurements, and writes artifacts outside git.
+
+Evidence:
+
+- `tests/browser/graph-large-performance.ts`
+- `tests/graph-browser-large-performance.regression-1.sh`
+- `/tmp/llm-wiki-graph-large-perf-task-1-2/large-graph-performance-results.json`
+- `/tmp/llm-wiki-graph-large-perf-task-1-3/large-graph-performance-results.json`
+- `docs/graph/performance/2026-06-18-phase-1-3-dom-svg-large-baseline.md`
+
+## Real Graph Source And Privacy Policy
+
+Generated fixtures are the default reproducible source for Phase 1 and should remain committed only as generator code, not as large JSON outputs.
+
+A real graph snapshot may be added later only as an uncommitted or sanitized artifact:
+
+- Owner: the developer running the benchmark exports it from a local knowledge base.
+- Location: `/tmp/llm-wiki-real-graph-snapshot-<date>/graph-data.json` or another ignored local path.
+- Git policy: real snapshots are excluded from git unless explicitly anonymized and reviewed.
+- Privacy handling: remove source paths, personal names, private project names, raw content, and unique file-system paths before sharing or committing.
+- Reproduction: record node/edge/community counts, largest community size, search-hit count, Pin count, export command, hash of sanitized data, and benchmark artifact path.
+- If the real graph contains private data and cannot be anonymized, use the generated `real-snapshot-proxy` shape instead.
+
+## Edge Count Caps
+
+The stress goal is to measure product-like behavior, not arbitrary impossible graphs. Current caps for this plan:
+
+| Shape | Node cap | Edge cap | Reason |
+|---|---:|---:|---|
+| 1000 sparse | 1000 | 1400 | Baseline navigation and interaction. |
+| 1000 dense | 1000 | 12000 | Dense local relation pressure while still fitting current visible edge budget. |
+| 5000 sparse | 5000 | 6500 | Large global map with realistic sparse connectivity. |
+| 5000 dense | 5000 | 60000 | Stress candidate, not default runner path. |
+| 10000 aggregation | 10000 | 14000 | Target global browsing shape. |
+| 10000 high-edge | 10000 | 90000 | Stress candidate for renderer trials, not required for every smoke run. |
+| oversized-community | 3000 | 7000 | Tests one oversized community without pretending all cards can stay visible. |
+
+The current DOM/SVG renderer visibly caps rendered edges at 1000 in the measured global view. That is useful evidence, but it is not a final large-graph solution.
+
+## Browser Environment
+
+Measured browser environment is available. Performance phases are not blocked.
+
+- Runner command: `GRAPH_LARGE_PERF_ARTIFACT_DIR=/tmp/llm-wiki-graph-large-perf-task-1-3 bash tests/graph-browser-large-performance.regression-1.sh`
+- Browser package path: resolved through `npx --yes -p playwright`.
+- Executable path: `/Users/kangjiaqi/Library/Caches/ms-playwright/chromium-1228/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing`.
+- Local ports: not required for the offline generated graph runner. Workbench browser checks may still need local ports in later phases.
+- Browser plugin fallback: allowed only for functional visual checks when scriptable checks fail; it cannot replace performance artifacts.
+
+## Trial Dependency Path
+
+No production dependency was added in Phase 1. Playwright was used through temporary `npx --yes -p playwright` resolution and local browser cache for measurement.
+
+For Phase 6:
+
+- Sigma/Graphology and vis-network may be installed only for isolated renderer trials when the current task requires them.
+- Any package change must be recorded in the progress decision log before it lands.
+- Production adoption remains blocked until the Phase 6 route decision.
+- At most one production global graph route may survive. Aggregation-first may be a staged chosen route, but it must not become a second parallel global graph product.
+
+## Oversized Community Semantics
+
+For Phase 4 tests, "complete community presence" must not mean rendering every internal item as a full card at once. It may mean:
+
+- A visible community container or outline.
+- Representative core nodes as cards.
+- Remaining members as points, count badges, or an internal list in the drawer.
+- Search hits, selected objects, and pinned objects remain visible or explicitly represented.
+- A clear action to drill into a bounded community reading surface.
+
+The oversized-community fixture has 3000 nodes, 7000 edges, 15 communities, and one 1800-node community. Current DOM/SVG behavior exposes too many card-like nodes for this shape and recorded slow entry/return behavior in Phase 1.3.
+
+## Desktop-App Compatibility Guardrails
+
+Graph semantics must remain reusable if the product later moves into a desktop shell. Avoid binding product logic to browser-only assumptions:
+
+- Do not store graph semantics only in DOM attributes. DOM attributes may mirror state for rendering/tests, but graph identity, selection, search, Pin, filter, and community rules belong in shared graph-engine data structures.
+- Do not make `window`, `document`, `localStorage`, URL routing, or CSS selectors the source of truth for graph behavior.
+- Keep file-system paths and workspace paths behind host adapters; shared graph semantics should use object ids, community ids, and wiki-relative ids.
+- Renderer candidates may use Canvas/WebGL/browser APIs, but semantic contracts must stay independent enough to run behind a desktop webview or native shell bridge.
+- Persisted Pin/layout state should stay serializable and portable, not tied to one browser storage implementation.
+
+## Throwaway Code Policy
+
+Phase 1 did not leave throwaway validation code in product paths. The generated graph runner became a deliberate test harness under `tests/browser/`; temporary graph HTML and JSON artifacts remain under `/tmp` and are not committed.

package/skills/llm-wiki-skill/docs/graph/performance/2026-06-18-phase-2-4-global-renderer-trial-matrix.md

@@ -0,0 +1,168 @@
+# Phase 2.4 Global Renderer Trial Matrix
+
+Date: 2026-06-18
+Branch: `codex/large-graph-performance-experience`
+Task: `2.4`
+
+## Purpose
+
+This note defines the trial boundary before any global large-graph renderer candidate is installed, measured, or wired into the product. The project will compare WebGL, Canvas, and no-new-dependency aggregation with the same data, semantics, graph shapes, and performance records. It will ship at most one production global graph route.
+
+Current DOM/SVG remains the known route for small graphs, community reading, offline detail, and UI-rich cards. It is not assumed to be the final 10000+ global route.
+
+## Non-Negotiable Route Rule
+
+Only one production global large-graph route may survive the decision phase.
+
+- Candidate trials may coexist only in isolated harness code and measurement artifacts.
+- The workbench must not expose multiple global graph experiences as parallel product modes.
+- Aggregation-first may be selected as a staged production route if it wins the decision, but it must not become a permanent second route next to a WebGL or Canvas global renderer.
+- DOM/SVG can remain for community/detail surfaces even if a different route wins for the global map.
+
+## Shared Trial Inputs
+
+Every candidate must consume the Phase 2 shared renderer adapter contract before product-specific behavior is evaluated.
+
+Required semantic inputs:
+
+- Object ids: node id, community id, aggregation id.
+- State: selected object, search hits, Pin hints, focused community, filters.
+- Aggregation metadata: contained node ids, selected internal node ids, search-hit ids, pinned ids, total count.
+- Drawer targets: node summary, community summary, excluded aggregation object.
+- Commands: enter community, show object, clear temporary object, open detail/read, set fixed position.
+
+Required graph shapes:
+
+| Shape | Nodes | Edge cap | Required in Phase 6? | Purpose |
+|---|---:|---:|---|---|
+| real-snapshot-proxy | 1000 | 1600 | yes | Proxy for a realistic medium wiki graph. |
+| nodes-1000-sparse | 1000 | 1400 | yes | Baseline interaction and correctness. |
+| nodes-1000-dense | 1000 | 12000 | yes | Dense local relation pressure. |
+| nodes-5000-sparse | 5000 | 6500 | yes | First large global target. |
+| nodes-5000-dense | 5000 | 60000 | yes | Edge-heavy 5000-node pressure. |
+| nodes-10000-aggregation | 10000 | 14000 | yes | Primary 10000+ global target. |
+| nodes-10000-high-edge | 10000 | 90000 | yes | Extreme edge pressure for the renderer decision. |
+| oversized-community | 3000 | 7000 | yes | One huge community without full-card rendering. |
+| many-small-communities | 5000 | 6000 | yes | Many tiny communities and legend/container pressure. |
+| many-search-hits | 5000 | 7000 | yes | Search highlight pressure. |
+| many-pin-nodes | 5000 | 7000 | yes | Pin/selected preservation pressure. |
+
+## Candidate Matrix
+
+| Candidate | Technology | Trial role | Strength to prove | Main rejection reasons | Dependency status |
+|---|---|---|---|---|---|
+| Sigma/Graphology | WebGL + graph model | First global renderer candidate | 5000/10000 point map remains smooth while preserving llm-wiki selection/search/Pin/drawer semantics | Semantic contract cannot be preserved, desktop webview risk is too high, memory grows across cycles, integration forces a second product logic path, performance does not beat aggregation enough | Requires explicit trial dependency approval before package changes. |
+| vis-network | Canvas | Strong comparison candidate | Canvas path handles large global interactions with less integration cost than WebGL | Built-in interaction model fights llm-wiki drawer/community/search semantics, layout ownership becomes opaque, Pin/fixed-position behavior is unstable, performance or memory falls below WebGL/aggregation | Requires explicit trial dependency approval before package changes. |
+| Aggregation fallback | Current stack, no new dependency | No-new-dependency fallback or staged route | 10000+ global map is useful by showing communities, skeleton edges, selected/search/Pin markers, and overflow lists without full node detail | Users lose too much spatial context, search/Pin/selected objects are not discoverable, container interactions feel like a separate product, oversized communities remain slow | No dependency approval required. |
+
+## Required Metrics
+
+Every measured candidate must produce fixed-schema artifacts comparable to the Phase 1 DOM/SVG baseline.
+
+Required action records:
+
+- initial render
+- wheel zoom FPS and p95 frame time
+- pan
+- hover or nearest-object inspect
+- search highlight
+- point select
+- container select
+- drawer open
+- enter community
+- return global
+- repeated cycle memory growth for every required shape
+
+Required metadata fields:
+
+- renderer id
+- candidate version and package versions, if any
+- graph shape
+- node count
+- edge count
+- community count
+- largest community size
+- search hit count
+- Pin count
+- visible object count
+- browser environment
+- artifact path
+- pass/fail
+- failure class and detail
+
+## Provisional Acceptance Table
+
+These thresholds are comparison gates, not final product promises.
+
+| Metric | 1000 nodes | 5000 nodes | 10000 nodes | Notes |
+|---|---:|---:|---:|---|
+| Initial render | <= 1500 ms | <= 5000 ms | <= 8000 ms | Current DOM/SVG exceeded the 10000 target. |
+| Wheel zoom | >= 30 FPS | >= 30 FPS | >= 30 FPS | Lower result must record `fps_below_floor`. |
+| Pan | <= 300 ms | <= 500 ms | <= 800 ms | Timeout is a blocking failure for a candidate route. |
+| Search highlight | <= 500 ms | <= 800 ms | <= 1200 ms | Search must update highlight/markers without full graph relayout. |
+| Point select | <= 800 ms | <= 1500 ms | <= 2000 ms | Must open lightweight summary target, not full reading by default. |
+| Container select | <= 1000 ms | <= 2000 ms | <= 2500 ms | Community/aggregation selection must keep global context. |
+| Drawer open | <= 1000 ms | <= 2500 ms | <= 3000 ms | Long content rendering is not part of global lightweight drawer. |
+| Return global | <= 3500 ms | <= 5000 ms | <= 5000 ms | Route must not rebuild unnecessary detail. |
+| Repeated cycle memory growth | <= 50 MB | <= 75 MB | <= 100 MB | If the browser cannot expose memory, record that explicitly instead of silently passing. |
+
+## Browser Verification Boundary
+
+Scripted browser trials remain the route-decision evidence because they generate repeatable JSON artifacts across all graph shapes and actions.
+
+The Codex Browser plugin is an approved fallback for human-like visual and interaction checks when a local Playwright package or Chrome path is unavailable. It can validate that a page opens, visible graph controls respond, and the lightweight drawer flow matches user expectations. It must not replace the fixed-schema performance artifacts for renderer selection, because route decisions need comparable records across WebGL, Canvas, and aggregation fallback candidates.
+
+## Desktop-App Compatibility Checks
+
+The later desktop app direction means a candidate cannot win by hiding product logic in browser-only surfaces.
+
+Required checks:
+
+- Graph meaning remains in graph-engine data, not DOM attributes or renderer internals.
+- Host integration can be driven by ids, serializable state, and commands.
+- Pin/layout state remains portable and wiki-relative.
+- Candidate-specific event handling does not own product decisions such as open detail, enter community, or selected object policy.
+- The route can run inside a desktop webview or be wrapped behind a native shell bridge without rewriting graph semantics.
+
+## Trial Harness Boundary
+
+Allowed in Phase 6:
+
+- Isolated candidate harness modules.
+- Temporary renderer pages or browser fixtures under `tests/browser/`.
+- Measurement reports under `docs/graph/performance/`.
+- Trial dependencies after explicit approval is recorded.
+
+Not allowed before the route decision:
+
+- Switching the workbench production global view to a candidate renderer.
+- Adding a production dependency for the final app route.
+- Leaving multiple candidate renderers active as user-facing modes.
+- Recomputing graph product semantics inside candidate-specific code.
+
+## Dependency Approval Record Needed
+
+If Phase 6 needs trial packages, the progress decision log must record exact approval before package changes land.
+
+Expected approval entry format:
+
+```text
+Task 6.x dependency approval: install <package names and versions> only for isolated renderer trial harness; no production adoption until Phase 6.4 route decision.
+```
+
+Expected package classes:
+
+- Sigma/Graphology trial: `sigma`, `graphology`, and any narrowly required layout/helper package.
+- vis-network trial: `vis-network` or the maintained package name selected at trial time.
+- Aggregation fallback: no package expected.
+
+## Decision Output
+
+Phase 6.4 must produce one of these outcomes:
+
+- Integrate Sigma/Graphology as the single global large-graph route in a future implementation plan.
+- Integrate vis-network as the single global large-graph route in a future implementation plan.
+- Ship aggregation-first as the single staged global route, with explicit limits and follow-up research.
+- Reject all candidates and continue renderer research with recorded failure reasons.
+
+The decision report must include accepted route, rejected alternatives, evidence artifact paths, unresolved risks, and whether community/detail DOM/SVG remains unchanged.

package/skills/llm-wiki-skill/docs/graph/performance/2026-06-19-phase-6-1-sigma-graphology-trial.md

@@ -0,0 +1,71 @@
+# Phase 6.1 Sigma/Graphology WebGL Trial
+
+Date: 2026-06-19
+Branch: `codex/large-graph-performance-experience`
+Task: `6.1`
+Renderer: isolated Sigma/Graphology WebGL trial
+
+## Scope
+
+This report evaluates Sigma/Graphology as the first global large-graph renderer candidate. It does not switch the production workbench graph path. Current DOM/SVG remains the rich small-graph and community-reading path until the Phase 6.4 route decision.
+
+The trial uses the shared graph adapter contract so object ids, community ids, search hits, Pin hints, selected objects, and aggregation markers remain portable across later browser or desktop shells.
+
+## Commands
+
+- `git log --oneline -15`
+- `npm run test --workspace=@llm-wiki/graph-engine`
+- `npm install -w @llm-wiki/graph-engine -D sigma@3.0.3 graphology@0.26.0`
+- `node --import tsx --check tests/browser/graph-sigma-graphology-trial.ts`
+- `node --import tsx --test packages/graph-engine/test/sigma-trial-adapter.test.ts`
+- `GRAPH_SIGMA_TRIAL_ARTIFACT_DIR=/tmp/llm-wiki-graph-sigma-trial-task-6-1 bash tests/graph-sigma-graphology-trial.regression-1.sh`
+
+## Artifacts
+
+Machine-readable result:
+
+- `/tmp/llm-wiki-graph-sigma-trial-task-6-1/sigma-graphology-trial-results.json`
+
+The artifact contains 47 fixed-schema records across 5 graph shapes.
+
+## Post-Review Harness Hardening
+
+The original result table below is now treated as a historical isolation baseline. After review, the Sigma trial harness was hardened so a run fails when any action record fails, any failure class is present, any required action is missing, any requested shape is missing, or the wrapper only produced a JSON file without valid contents.
+
+The default shape set was expanded from 5 shapes to the full 11-shape stress matrix: realistic proxy, 1000 sparse/dense, 5000 sparse/dense, 10000 aggregation/high-edge, oversized community, many small communities, many search hits, and many Pin nodes. Repeated interaction/memory cycles now run on every requested shape instead of only 1000-node shapes.
+
+Interaction timing now waits for visible render completion after scripted actions. Sigma uses animation-frame completion checks after search, selection, drawer, community, and return-global actions. A hardened rerun is required before using these numbers as final production-integration evidence.
+
+## Result Table
+
+| Shape | Nodes | Edges | DOM nodes | Initial | Wheel | Pan | Search | Point | Container | Drawer | Community | Return | Cycle |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| nodes-1000-sparse | 1000 | 1400 | 18 | pass (146.2 ms) | pass (60.2 FPS) | pass (274.0 ms) | pass (9.4 ms) | pass (2.9 ms) | pass (4.5 ms) | pass (0.7 ms) | pass (7.6 ms) | pass (2.1 ms) | pass (0 MB growth) |
+| nodes-1000-dense | 1000 | 12000 | 18 | pass (116.7 ms) | pass (60.6 FPS) | pass (268.1 ms) | pass (11.5 ms) | pass (8.3 ms) | pass (6.7 ms) | pass (0.5 ms) | pass (9.0 ms) | pass (7.1 ms) | pass (0 MB growth) |
+| nodes-5000-sparse | 5000 | 6500 | 18 | pass (175.3 ms) | pass (60.5 FPS) | pass (269.3 ms) | pass (23.4 ms) | pass (13.0 ms) | pass (8.5 ms) | pass (0.6 ms) | pass (11.8 ms) | pass (12.0 ms) | not run |
+| nodes-10000-aggregation | 10000 | 14000 | 18 | pass (289.1 ms) | pass (60.9 FPS) | pass (272.5 ms) | pass (40.9 ms) | pass (14.6 ms) | pass (18.5 ms) | pass (0.5 ms) | pass (19.0 ms) | pass (13.0 ms) | not run |
+| oversized-community | 3000 | 7000 | 18 | pass (140.6 ms) | pass (60.7 FPS) | pass (268.2 ms) | pass (14.7 ms) | pass (6.9 ms) | pass (6.9 ms) | pass (0.5 ms) | pass (8.7 ms) | pass (6.0 ms) | not run |
+
+## Comparison To Current DOM/SVG Baseline
+
+| Shape | DOM/SVG initial | Sigma initial | DOM/SVG wheel | Sigma wheel | DOM/SVG notable failure |
+|---|---:|---:|---:|---:|---|
+| nodes-1000-sparse | 900.4 ms | 146.2 ms | 60.0 FPS | 60.2 FPS | none |
+| nodes-1000-dense | 1008.4 ms | 116.7 ms | 59.6 FPS | 60.6 FPS | none |
+| nodes-5000-sparse | 4615.6 ms | 175.3 ms | 51.3 FPS | 60.5 FPS | none |
+| nodes-10000-aggregation | 8836.0 ms | 289.1 ms | 36.8 FPS | 60.9 FPS | pan and node click timeout |
+| oversized-community | 15788.6 ms | 140.6 ms | 12.9 FPS | 60.7 FPS | near unusable wheel FPS |
+
+## Interpretation
+
+Sigma/Graphology is a strong candidate for the global browsing route. The trial keeps DOM output constant, handles 10000 nodes without the DOM/SVG timeout classes, and preserves the shared semantic contract.
+
+This is still not the final route decision. Phase 6 must also compare vis-network Canvas and the no-new-dependency aggregation fallback before selecting one production global renderer path. The trial also uses a minimal drawer and simple visual update model; production integration still needs design-fit, input semantics, theming, accessibility, and desktop packaging checks.
+
+## Acceptance Evidence
+
+- Historical shapes measured: 1000 sparse, 1000 dense, 5000 sparse, 10000 aggregation, and oversized-community.
+- Hardened default shapes now include the full 11-shape stress matrix.
+- Required actions are now enforced for every requested shape: initial render, pan, zoom, search highlight, point select, container select, drawer open, enter community, return global, and repeated memory cycle.
+- Behavior parity test passed: `node --import tsx --test packages/graph-engine/test/sigma-trial-adapter.test.ts`.
+- No production workbench renderer path was switched.

package/skills/llm-wiki-skill/docs/graph/performance/2026-06-19-phase-6-2-vis-network-trial.md

@@ -0,0 +1,78 @@
+# Phase 6.2 vis-network Canvas Trial
+
+Date: 2026-06-19
+Branch: `codex/large-graph-performance-experience`
+Task: `6.2`
+Renderer: isolated vis-network Canvas trial
+
+## Scope
+
+This report evaluates vis-network as the Canvas comparison candidate. It does not switch the production workbench graph path. Current DOM/SVG remains the rich small-graph and community-reading path until the Phase 6.4 route decision.
+
+The trial uses the same graph shapes and interaction actions as the Sigma/Graphology trial. It also uses a shared graph-engine adapter contract so object ids, community ids, search hits, Pin hints, selected objects, and aggregation markers remain portable.
+
+## Commands
+
+- `git log --oneline -15`
+- `npm run test --workspace=@llm-wiki/graph-engine`
+- `npm install -w @llm-wiki/graph-engine -D vis-network`
+- `node --import tsx --check tests/browser/graph-vis-network-trial.ts`
+- `node --import tsx --test packages/graph-engine/test/vis-network-trial-adapter.test.ts`
+- `GRAPH_VIS_TRIAL_ARTIFACT_DIR=/tmp/llm-wiki-graph-vis-trial-task-6-2 bash tests/graph-vis-network-trial.regression-1.sh`
+
+## Artifacts
+
+Machine-readable result:
+
+- `/tmp/llm-wiki-graph-vis-trial-task-6-2/vis-network-trial-results.json`
+
+The artifact contains 47 fixed-schema records across 5 graph shapes.
+
+## Post-Review Harness Hardening
+
+The original result table below is now treated as a historical isolation baseline. After review, the vis-network trial harness was hardened so a run fails when any action record fails, any failure class is present, any required action is missing, any requested shape is missing, or the wrapper only produced a JSON file without valid contents.
+
+The default shape set was expanded from 5 shapes to the full 11-shape stress matrix: realistic proxy, 1000 sparse/dense, 5000 sparse/dense, 10000 aggregation/high-edge, oversized community, many small communities, many search hits, and many Pin nodes. Repeated interaction/memory cycles now run on every requested shape instead of only 1000-node shapes.
+
+Interaction timing now waits for visible render completion after scripted actions. vis-network uses `afterDrawing` completion checks for render-affecting actions; the earlier timeout-based ready fallback was removed so a page cannot be marked ready without a completed draw. A hardened rerun is required before using these numbers as final production-integration evidence.
+
+## Result Table
+
+| Shape | Nodes | Edges | DOM nodes | Initial | Wheel | Pan | Search | Point | Container | Drawer | Community | Return | Cycle |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| nodes-1000-sparse | 1000 | 1400 | 20 | pass (117.6 ms) | pass (60.4 FPS) | pass (266.4 ms) | pass (28.0 ms) | pass (18.1 ms) | pass (9.3 ms) | pass (0.6 ms) | pass (7.3 ms) | pass (2.4 ms) | pass (0 MB growth) |
+| nodes-1000-dense | 1000 | 12000 | 20 | pass (215.2 ms) | pass (60.4 FPS) | pass (292.0 ms) | pass (40.8 ms) | pass (49.4 ms) | pass (24.7 ms) | pass (0.6 ms) | pass (24.5 ms) | pass (8.4 ms) | pass (0 MB growth) |
+| nodes-5000-sparse | 5000 | 6500 | 20 | pass (263.0 ms) | pass (60.2 FPS) | pass (274.3 ms) | pass (81.7 ms) | pass (66.3 ms) | pass (33.3 ms) | pass (0.4 ms) | pass (32.5 ms) | pass (9.8 ms) | not run |
+| nodes-10000-aggregation | 10000 | 14000 | 20 | pass (456.5 ms) | pass (60.9 FPS) | pass (331.6 ms) | pass (148.0 ms) | pass (138.3 ms) | pass (91.0 ms) | pass (5.2 ms) | pass (94.6 ms) | pass (19.3 ms) | not run |
+| oversized-community | 3000 | 7000 | 20 | pass (216.5 ms) | pass (60.5 FPS) | pass (270.5 ms) | pass (63.1 ms) | pass (46.4 ms) | pass (27.1 ms) | pass (0.5 ms) | pass (25.8 ms) | pass (7.0 ms) | not run |
+
+## Comparison To Sigma And DOM/SVG
+
+| Shape | DOM/SVG initial | Sigma initial | vis-network initial | Sigma search | vis-network search | Sigma point | vis-network point |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| nodes-1000-sparse | 900.4 ms | 146.2 ms | 117.6 ms | 9.4 ms | 28.0 ms | 2.9 ms | 18.1 ms |
+| nodes-1000-dense | 1008.4 ms | 116.7 ms | 215.2 ms | 11.5 ms | 40.8 ms | 8.3 ms | 49.4 ms |
+| nodes-5000-sparse | 4615.6 ms | 175.3 ms | 263.0 ms | 23.4 ms | 81.7 ms | 13.0 ms | 66.3 ms |
+| nodes-10000-aggregation | 8836.0 ms | 289.1 ms | 456.5 ms | 40.9 ms | 148.0 ms | 14.6 ms | 138.3 ms |
+| oversized-community | 15788.6 ms | 140.6 ms | 216.5 ms | 14.7 ms | 63.1 ms | 6.9 ms | 46.4 ms |
+
+Both candidate renderers remove the current DOM/SVG bottleneck class for global browsing. vis-network keeps wheel zoom near 60 FPS on all required shapes, but it is slower than Sigma/Graphology for search, point selection, and container/community updates in this isolated harness.
+
+## Integration Risks
+
+- vis-network owns more of the interaction and selection model by default. The trial disables physics and routes selection through explicit shared commands to avoid fighting llm-wiki drawer/community/search semantics.
+- Layout ownership can become opaque if production integration enables vis-network physics or stabilization. Pin and fixed-position behavior should remain owned by graph-engine, not by vis-network runtime state.
+- The Canvas route depends on DataSet mutation patterns. Search and selection are still acceptable in this trial, but they scale worse than the Sigma candidate on the same data.
+- Desktop packaging is plausible because the semantic layer remains outside the renderer, but production integration would need a strict adapter boundary to prevent product logic from moving into vis-network callbacks.
+
+## Interpretation
+
+vis-network is a viable Canvas comparison candidate, but this trial does not currently beat Sigma/Graphology on the important semantic-update actions. It remains in the Phase 6 comparison set until the aggregation fallback and final route decision are recorded.
+
+## Acceptance Evidence
+
+- Historical shapes measured: 1000 sparse, 1000 dense, 5000 sparse, 10000 aggregation, and oversized-community.
+- Hardened default shapes now include the full 11-shape stress matrix.
+- Required actions are now enforced for every requested shape: initial render, pan, zoom, search highlight, point select, container select, drawer open, enter community, return global, and repeated memory cycle.
+- Behavior parity test passed: `node --import tsx --test packages/graph-engine/test/vis-network-trial-adapter.test.ts`.
+- No production workbench renderer path was switched.

package/skills/llm-wiki-skill/docs/graph/performance/2026-06-19-phase-6-3-aggregation-fallback-trial.md

@@ -0,0 +1,72 @@
+# Phase 6.3 Aggregation Fallback Trial
+
+Date: 2026-06-19
+Branch: `codex/large-graph-performance-experience`
+Task: `6.3`
+Renderer: no-new-dependency aggregation fallback trial
+
+## Scope
+
+This report evaluates the no-new-dependency fallback route using the current graph-engine budget and aggregation semantics. It does not switch the production workbench graph path.
+
+The trial renders lightweight global points, capped skeleton edges, capped labels, aggregation containers, and a lightweight drawer. It intentionally does not render global cards. This tests whether the current stack can provide a fast structural overview without pretending it is a full 10000+ detailed renderer.
+
+## Commands
+
+- `git log --oneline -15`
+- `npm run test --workspace=@llm-wiki/graph-engine`
+- `node --import tsx --check tests/browser/graph-aggregation-fallback-trial.ts`
+- `node --import tsx --test packages/graph-engine/test/aggregation-fallback-trial-adapter.test.ts`
+- `GRAPH_AGGREGATION_TRIAL_ARTIFACT_DIR=/tmp/llm-wiki-graph-aggregation-trial-task-6-3 bash tests/graph-aggregation-fallback-trial.regression-1.sh`
+
+## Artifacts
+
+Machine-readable result:
+
+- `/tmp/llm-wiki-graph-aggregation-trial-task-6-3/aggregation-fallback-trial-results.json`
+
+The artifact contains 47 fixed-schema records across 5 graph shapes.
+
+## Post-Review Harness Hardening
+
+The original result table below is now treated as a historical isolation baseline. After review, the aggregation fallback trial harness was hardened so a run fails when any action record fails, any failure class is present, any required action is missing, any requested shape is missing, or the wrapper only produced a JSON file without valid contents.
+
+The default shape set was expanded from 5 shapes to the full 11-shape stress matrix: realistic proxy, 1000 sparse/dense, 5000 sparse/dense, 10000 aggregation/high-edge, oversized community, many small communities, many search hits, and many Pin nodes. Repeated interaction/memory cycles now run on every requested shape instead of only 1000-node shapes.
+
+Interaction timing now waits for animation-frame completion after scripted actions. The aggregation fallback still uses internal `zoomBy` and `panBy` helpers for zoom and pan, so its zoom/pan numbers are useful for current-stack fallback pressure but are not directly equivalent to the real mouse-input measurements in the Sigma and vis-network trials.
+
+## Result Table
+
+| Shape | Nodes | Edges | DOM nodes | Visible nodes | Visible edges | Labels | Cards | Initial | Wheel | Search | Hidden interaction objects |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| nodes-1000-sparse | 1000 | 1400 | 2053 | 1000 | 1000 | 40 | 0 | pass (71.7 ms) | pass (60.2 FPS) | pass (12.0 ms) | 34 |
+| nodes-1000-dense | 1000 | 12000 | 2053 | 1000 | 1000 | 40 | 0 | pass (66.1 ms) | pass (60.1 FPS) | pass (11.4 ms) | 34 |
+| nodes-5000-sparse | 5000 | 6500 | 6103 | 5000 | 1000 | 40 | 0 | pass (136.4 ms) | pass (60.7 FPS) | pass (64.2 ms) | 4034 |
+| nodes-10000-aggregation | 10000 | 14000 | 11153 | 10000 | 1000 | 40 | 0 | pass (185.9 ms) | pass (60.6 FPS) | pass (184.6 ms) | 9034 |
+| oversized-community | 3000 | 7000 | 4068 | 3000 | 1000 | 40 | 0 | pass (92.2 ms) | pass (60.2 FPS) | pass (40.6 ms) | 2034 |
+
+## Comparison To Renderer Candidates
+
+| Shape | Sigma initial | vis-network initial | Aggregation initial | Sigma search | vis-network search | Aggregation search |
+|---|---:|---:|---:|---:|---:|---:|
+| nodes-1000-sparse | 146.2 ms | 117.6 ms | 71.7 ms | 9.4 ms | 28.0 ms | 12.0 ms |
+| nodes-1000-dense | 116.7 ms | 215.2 ms | 66.1 ms | 11.5 ms | 40.8 ms | 11.4 ms |
+| nodes-5000-sparse | 175.3 ms | 263.0 ms | 136.4 ms | 23.4 ms | 81.7 ms | 64.2 ms |
+| nodes-10000-aggregation | 289.1 ms | 456.5 ms | 185.9 ms | 40.9 ms | 148.0 ms | 184.6 ms |
+| oversized-community | 140.6 ms | 216.5 ms | 92.2 ms | 14.7 ms | 63.1 ms | 40.6 ms |
+
+## Product Interpretation
+
+Aggregation fallback is fast enough for a structural global overview. It keeps global cards at zero, caps labels at 40, caps visible edges at 1000, and preserves selected/search/Pin/container semantics through the shared adapter.
+
+It is not equivalent to a full global renderer. At 10000 nodes it hides 9034 interaction-time objects and depends on the drawer/list layer to expose omitted detail. That is acceptable as a fallback or staged route, but not enough by itself for rich 10000+ exploration if the product wants direct large-map inspection with full relation density.
+
+## Acceptance Evidence
+
+- Historical shapes measured: 1000 sparse, 1000 dense, 5000 sparse, 10000 aggregation, and oversized-community.
+- Hardened default shapes now include the full 11-shape stress matrix.
+- Required actions are now enforced for every requested shape: initial render, pan, zoom, search highlight, point select, container select, drawer open, enter community, return global, and repeated memory cycle.
+- Required fallback elements present: aggregation containers, skeleton edges, selected/search/Pin markers, and lightweight drawer overflow path.
+- Behavior parity test passed: `node --import tsx --test packages/graph-engine/test/aggregation-fallback-trial-adapter.test.ts`.
+- No new dependency was added for this task.
+- No production workbench renderer path was switched.

package/skills/llm-wiki-skill/docs/graph/performance/2026-06-19-phase-6-4-global-renderer-route-decision.md

@@ -0,0 +1,94 @@
+# Phase 6.4 Global Renderer Route Decision
+
+Date: 2026-06-19
+Branch: `codex/large-graph-performance-experience`
+Task: `6.4`
+
+## Decision
+
+Select Sigma/Graphology WebGL as the future single global large-graph renderer integration route.
+
+This task records the route decision only. It does not switch the production workbench renderer, add a production renderer path, or remove the current DOM/SVG renderer. Current DOM/SVG remains the rich small-graph and community-reading path.
+
+Post-review status: this remains the current route preference, not a final production integration proof. The original Phase 6 tables were produced by the first isolated harness. The hardened harness now requires the full 11-shape matrix, complete action coverage, failed-record detection, large-shape repeated cycles, and render-completion waits. The next production integration plan must rerun the hardened trials before treating the Sigma choice as locked.
+
+## Why Sigma/Graphology Wins
+
+Sigma/Graphology is the best fit for the product goal: smooth 5000+ / 10000+ global browsing while preserving llm-wiki graph semantics outside the renderer.
+
+Measured evidence:
+
+| Shape | Sigma initial | Sigma wheel | Sigma search | Sigma point select | Sigma container select |
+|---|---:|---:|---:|---:|---:|
+| nodes-1000-sparse | 146.2 ms | 60.2 FPS | 9.4 ms | 2.9 ms | 4.5 ms |
+| nodes-1000-dense | 116.7 ms | 60.6 FPS | 11.5 ms | 8.3 ms | 6.7 ms |
+| nodes-5000-sparse | 175.3 ms | 60.5 FPS | 23.4 ms | 13.0 ms | 8.5 ms |
+| nodes-10000-aggregation | 289.1 ms | 60.9 FPS | 40.9 ms | 14.6 ms | 18.5 ms |
+| oversized-community | 140.6 ms | 60.7 FPS | 14.7 ms | 6.9 ms | 6.9 ms |
+
+The historical trial also kept DOM output constant at 18 nodes, passed behavior parity for object ids, community ids, search hits, Pin hints, selected objects, and aggregation markers, and did not switch the production renderer path.
+
+## Rejected Alternatives
+
+### vis-network Canvas
+
+vis-network is viable, but it is not the chosen route.
+
+Reasons:
+
+- It was slower than Sigma/Graphology on semantic updates that matter to llm-wiki: search, point select, and container/community updates.
+- On the 10000-node shape, vis-network search took 148.0 ms versus Sigma/Graphology at 40.9 ms.
+- On the 10000-node shape, vis-network point select took 138.3 ms versus Sigma/Graphology at 14.6 ms.
+- vis-network owns more built-in selection, physics, stabilization, and interaction behavior. That creates higher risk that product semantics drift into renderer callbacks instead of staying in `packages/graph-engine/`.
+
+vis-network remains a measured fallback candidate if a future Sigma integration hits a hard blocker, but it should not be integrated in parallel.
+
+### Aggregation-Only Fallback
+
+Aggregation-only is not enough to become the full global large-graph route.
+
+Reasons:
+
+- It is very fast for a structural overview, including 185.9 ms initial render and 60.6 FPS wheel zoom on the 10000-node shape.
+- It intentionally caps visible edges at 1000, labels at 40, cards at 0, and hides thousands of interaction-time objects at large sizes.
+- On the 10000-node shape it hid 9034 interaction-time objects, so it depends on drawer/list overflow to expose omitted detail.
+
+Aggregation remains a required degradation strategy inside the future global route: keep global cards at zero, cap labels and edges, preserve selected/search/Pin objects, and use drawer overflow for omitted detail. It must not become a second permanent global graph product beside Sigma/Graphology.
+
+### Current DOM/SVG As Global Renderer
+
+Current DOM/SVG is rejected as the final 5000+ / 10000+ global renderer.
+
+Reasons:
+
+- The Phase 1 baseline showed 10000-node initial render at 8836.0 ms, wheel zoom at 36.8 FPS, and pan/node-click timeout classes.
+- Oversized-community DOM/SVG wheel zoom was 12.9 FPS.
+- DOM/SVG remains appropriate for small graphs, scoped community reading, offline detail, and UI-rich card surfaces.
+
+## Integration Boundary For The Next Plan
+
+The next implementation plan should integrate Sigma/Graphology only for global large-graph browsing, behind the shared renderer adapter boundary.
+
+Required boundaries:
+
+- `packages/graph-engine/` remains the owner of object ids, community ids, search, filters, Pin, selection, aggregation, budgets, and drawer command semantics.
+- Sigma/Graphology owns only global drawing, viewport interaction, and renderer-level hit projection through a shared adapter.
+- Workbench receives the same lightweight node summary, community summary, open-detail, enter-community, return-global, and unavailable/excluded payloads it receives today.
+- Community reading continues to use the current DOM/SVG rich path unless a later plan proves a different scoped renderer.
+- Desktop compatibility remains a guardrail: renderer integration may use browser/WebGL APIs internally, but graph semantics must stay serializable and portable across a desktop webview or shell bridge.
+- Aggregation budgets remain active in the global route so 10000+ views do not reintroduce full-card or unlimited-edge rendering.
+
+## Next Plan Direction
+
+The next plan should integrate Sigma/Graphology as the single production global renderer route only after a hardened rerun confirms the full 11-shape matrix. DOM/SVG should remain the community-reading renderer.
+
+It should not integrate vis-network or ship a separate aggregation-only global product in parallel. If Sigma/Graphology integration fails on a hard blocker, the plan should stop and record the blocker before considering vis-network or aggregation-first as a replacement route.
+
+## Acceptance Evidence
+
+- Sigma/Graphology historically measured the first 5 graph shapes with 47 fixed-schema records and 0 errors.
+- vis-network historically measured the same first 5 shapes and was rejected with semantic update and ownership-risk evidence.
+- Aggregation fallback historically measured the same first 5 shapes and was retained only as degradation strategy and fallback evidence, not as a full global renderer.
+- Post-review harness now requires the full 11-shape matrix and blocks failed records instead of accepting result-file existence.
+- No production renderer path was added or switched.
+- No unapproved production dependency was adopted by this task.