update session_memory - for refer to the passwork

2026-07-07 22:01:30 +07:00
parent d862d1f7f8
commit 3fbbca1eaa
17 changed files with 2784 additions and 0 deletions
--- a/session_memory/26_Jun_26/CODING-AGENT-INSTRUCTION-PHASE0-PHASE1.md
+++ b/session_memory/26_Jun_26/CODING-AGENT-INSTRUCTION-PHASE0-PHASE1.md
@@ -0,0 +1,159 @@
+# Coding Agent Instruction: Resolve 17 Remaining Structural Gaps in Phase 0 & Phase 1
+
+You have already fixed the TypeScript build failures. The 17 unchecked plan items below must be addressed structurally. Each item is a checklist entry in `.kilo/plans/35-figma-designs-implementation-plan.md`. Only mark an item `[x]` in that plan file after you have implemented it AND it compiles cleanly.
+
+## Reference Files
+- Implementation Plan: `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/.kilo/plans/35-figma-designs-implementation-plan.md`
+- Frontend root: `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend`
+- Severity rule: Do NOT mark `[x]` unless you have implemented the item AND verified it.
+
+## Work Order: Exact Sequence with Acceptance Tests
+
+### 0.1 Environment Tooling
+1. Configure ESLint + Prettier
+   - Add `.eslintrc.cjs` and `.prettierrc` (or extend recommended configs).
+   - Add scripts to `package.json`: `"lint": "eslint src --ext .ts,.tsx"`.
+   - Acceptance: `npm run lint` runs without failing on the current src tree (warnings OK, but no auto-fixable errors left hanging).
+
+2. Set up Husky
+   - Install `husky` + `lint-staged`.
+   - Add `prepare` script: `"prepare": "husky"`.
+   - Add `.husky/pre-commit` to run `lint-staged`.
+   - Acceptance: `git add src/ && git commit` triggers Husky and blocks on lint failure.
+
+3. Configure Vitest
+   - Install: `vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `jsdom`.
+   - Add `vitest.config.ts` with `test.environment = 'jsdom'` and `include: ['src/**/*.{test,spec}.{js,ts,jsx,tsx}']`.
+   - Add script: `"test": "vitest"`.
+   - Acceptance: `npx vitest run` executes (0 tests is OK for now; framework must be correct).
+
+4. Set up Playwright
+   - Install `@playwright/test`.
+   - Add `playwright.config.ts` with baseURL `http://localhost:5173` and webServer using `vite preview` or same.
+   - Add script: `"test:e2e": "playwright test"`.
+   - Acceptance: `npx playwright test --list` does not error (no tests yet is OK).
+
+5. Configure Storybook
+   - Install `@storybook/react-vite` and run `storybook init`.
+   - Add 1 story for `Button` atom and 1 story for `TopBar` organism.
+   - Acceptance: `npm run storybook` builds the UI and the 2 stories render.
+
+### 0.3 Component Inventory
+6. Analyze 35 Figma Files
+   - Inspect Figma paths under `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/Design_Material/` - section: `Figma Design Source Files`.
+   - Produce an inventory mapping file: `spec/figma-component-specs.md` is insufficient; append `spec/component-inventory.md` with:
+     - Unique screen count (should be 35).
+     - Reusable component list by atomic depth (atoms, molecules, organisms, templates).
+     - One dependency graph (Mermaid is fine).
+   - Acceptance: `spec/component-inventory.md` exists, has 35 distinct screens, and has a Mermaid dependency graph.
+
+7. Build Storybook Stories for Primitives
+   - Add stories for `Button`, `Input`, `Icon`, `Badge`, `Label`, `Toggle`, `Tooltip`.
+   - Acceptance: All primitives render in Storybook.
+
+### 0.4 API Contracts
+8. Cross-Reference API Contracts
+   - Open `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/Design_Material/API_docs/API_CONTRACT_DRAFT.md` & the `API spec from the backend-file` in `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/backend/spec/interface-contract.md` & the data-layer definition - check the reference from context in the dirrectory (a folder) at `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/data/spec`
+   - Cross-check each endpoint against `src/services/*.ts`.
+   - Acceptance: Each service file has JSDoc lists of endpoints it covers.
+
+9. Define TypeScript Interfaces
+   - Add `src/types/api.ts` with request/response interfaces for all 7 services.
+   - Acceptance: All 7 services import and use their types.
+
+10. Implement HTTP + MSW Adapters
+    - Add `src/services/adapters/httpAdapter.ts` and `src/services/adapters/mswAdapter.ts`.
+    - Each service file must use the adapter via `services/index.ts` seam.
+    - Acceptance: `tsc --noEmit` clean; `vitest run` can mock the adapter without touching prod code.
+
+11. Implement Auth/Logging Interceptors
+    - In `httpAdapter.ts`, add request interceptor that:
+      - Attaches `Authorization` header from a session token (mocked OK).
+      - Logs request method + URL.
+      - Normalizes errors to a `ServiceError` class.
+    - Acceptance: Interceptor exists and is imported only by `httpAdapter.ts` (no component imports).
+
+### 1.2 Zustand Slices
+12. Co-locate Slice Tests
+    - Create `src/store/sessionSlice.test.ts`, `src/store/dicomSlice.test.ts`, etc. (6 files).
+    - Each test imports the slice factory (`createSessionSlice`) and invokes the interface.
+    - Acceptance: `vitest run --coverage` shows coverage files for each slice.
+
+13. Create Domain Selectors
+    - In each slice file, export type-safe selectors via `create`.
+    - Acceptance: `TopBar` and `BottomBar` consume slice selectors instead of inline memoization.
+
+### 1.3 WebWorkers
+14. Create `src/workers/` Files
+    - `cv.worker.ts`: stub with `onmessage` and `postMessage` for `preprocess` msg type.
+    - `llm.worker.ts`: stub with `generate` msg type.
+    - `guardrail.worker.ts`: stub with `safetyCheck` msg type.
+    - Acceptance: `tsc --noEmit` clean; workers can be imported in a hook.
+
+15. Implement Worker Pool + Hooks
+    - `src/hooks/useWebWorker.ts`: generic hook accepting worker class + message schema.
+    - `src/hooks/useCVWorker.ts`, `useLLMWorker.ts`, `useGuardrailWorker.ts`: domain wrappers.
+    - Acceptance: Hooks can be instantiated without runtime errors in a test render.
+
+16. Transferable Message Protocols
+    - In each worker stub, explicitly show `Transferable` usage (pass `ImageBitmap` or `ArrayBuffer` in transfer list).
+    - Acceptance: TypeScript types enforce transferable contracts.
+
+17. Fallback to Main Thread
+    - Each hook exports `isSupported: boolean`. If `Worker` constructor not available, use a mock implementation on main thread.
+    - Acceptance: In jsdom test, `isSupported` is false and hook still resolves.
+
+### 1.4 Services Deepening
+18. Move `encryption.ts` Out of the Store
+    - Remove `import { encryptStorage } from '../utils/encryption'` from `src/store/index.ts`.
+    - Create `src/services/storageAdapter.ts` that exports `createSessionStorage` and `createEncryptedStorage`.
+    - `store/index.ts` must import `createJSONStorage(() => storageAdapter)` from `services/storageAdapter`.
+    - Acceptance: `grep encryptStorage src/store/index.ts` returns nothing in src/store/.
+
+### 1.5 Route-Aware Shell
+19. Implement `protected.tsx`
+    - Add `src/routes/protected.tsx` with a `<RequireAuth>` wrapper that redirects to `/login` when `!sessionId`.
+    - Wrap `/workspace` in `<RequireAuth>`.
+    - Acceptance: Visit `/workspace` when unauthenticated; browser redirects to `/login`.
+
+20. `WorkspaceShell` Owns 65/35 Split
+    - `WorkspaceShell.tsx` must render the 65/35 layout directly: `div.flex.h-screen` with `w-[65%]` ZoneA and `w-[35%]` ZoneB.
+    - `routes/index.tsx` `<DiagnosticWorkspace>` must only render `<WorkspaceShell />` without re-implementing the split.
+    - Acceptance: `grep "flex-1" src/components/templates/WorkspaceShell.tsx` finds exactly one instance; `grep "ZoneA" src/routes/index.tsx` finds zero (or just an import).
+
+21. Lift `initApp` Out of `App.tsx`
+    - Add `src/hooks/useAppInit.ts`.
+    - Move the `initApp` effect into this hook.
+    - `App.tsx` becomes: `<AppRoutes />` plus `<AppInit />` or composes it.
+    - Acceptance: `grep "initApp" src/App.tsx` finds nothing.
+
+22. `React.lazy` + `Suspense` in Routes
+    - Use `React.lazy(() => import('../components/organisms/ZoneA'))` and same for `ZoneB`.
+    - Wrap `<DiagnosticWorkspace>` children in `<Suspense fallback={<div>Loading...</div>}>`.
+    - Acceptance: `grep React.lazy src/routes/index.tsx` finds 2+ matches.
+
+### 1.6 Layout Responsiveness
+23. Responsive Breakpoints
+    - `WorkspaceShell.tsx` must use `@media` or Tailwind responsive classes so that on `< md` the 65/35 stack becomes a tabbed/toggle layout (Zone A | Zone B).
+    - Acceptance: Resize viewport to 375px; only one Zone visible at a time.
+
+24. 60fps Rendering Hints
+    - Add `will-change: transform` to animated containers.
+    - Add `contain: layout style paint` to the workspace root.
+    - Acceptance: `grep -E "will-change|contain:" src/components/templates/WorkspaceShell.tsx` finds both.
+
+## Strict Consequences
+- If you cannot complete a specific item within this prompt, do not leave it half-done. Leave the plan checkbox `[ ]` and add a comment in code explaining what is blocking you.
+- All code must keep `tsc --noEmit` clean after your changes.
+- Do NOT touch backend files or any file outside `/Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend` unless an item explicitly requires it.
+
+## Final Verification (YOU MUST RUN THESE)
+```bash
+cd /Users/davestran/Downloads/vkist_internship/PILOT_PROJECT/workspace/sprint_1_2/CODEBASE/frontend
+npx tsc --noEmit && npm run build
+npm run lint
+npx vitest run
+npx playwright test --list
+npm run storybook -- --headless 2>&1 | tail -20
+```
+Produce a summary of which commands passed/failed and why.
--- a/session_memory/26_Jun_26/Proj_context_26_Jun_26.md
+++ b/session_memory/26_Jun_26/Proj_context_26_Jun_26.md
@@ -0,0 +1,189 @@
+# SESSION MEMORY — 26 Jun 26
+
+## APP PURPOSE
+VKIST MSK Platform — air-gapped musculoskeletal ultrasound analysis. FR-25 Synovitis Grading (knee). Vietnamese NLP. RAG citations. HITL finalization. ≤150 MB bundle. ≤1.5s inference.
+
+## ARCHITECTURE (C4)
+
+### Context
+- **UP5** Radiologist: primary user — load scan, review grade, finalize, sign, view GradCAM, engage circuit breaker, review RAG evidence
+- **UP1** Senior Expert: clinical protocol validation, MOH guideline approval, threshold sign-off
+- **UP4** Support: registration, case queue
+- External: PACS (DICOM), EMR/HIS (HL7/FHIR), Triton (GPU inference), ladybugDB (ontology), pgvector (MOH guidelines HNSW), GemmaE2B/MedGemma (LLM), EmbeddingGemma (RAG embeddings)
+
+### Containers
+- **PWA** React 18 + TS + Zustand + LiteRT + MediaPipe + Dexie.js. DICOM canvas, GradCAM overlay, edge guardrail (Transformers.js BERT + OpenRedaction + pii-filter) in WebWorkers.
+- **NGINX + Keepalived** VIP failover ≤2s, SSL termination
+- **FastAPI** edge-inference-svc: DICOM ingest, ML pipeline orchestration, Grad-CAM, report assembly, SSE streaming
+- **FastAPI** rag-svc: pgvector top-k retrieval, ladybugDB ontology, LLM consult route, RAG-Referee
+- **Postgres + pgvector** HNSW index for MOH guidelines
+- **Redis** JWT sessions, rate-limit, consult_mode state
+- **MinIO** S3: DICOM, overlays, GradCAM heatmaps, reports
+- **Triton** gRPC :8001: 3-step ML pipeline + embeddings
+
+### 3-STEP ML PIPELINE (Triton)
+1. **Angle Classification** — ConvNeXt/DenseNet/ResNet/EfficientNet/Swin-V2. Classes: med-lat, post-trans, sup-trans-flex, sup-up-long
+2. **Inflammation Detection** — EfficientNet-B0 binary (post-trans, sup-up-long only)
+3. **Segmentation** — DeepLabV3-ResNet101 (post-trans) OR UNet3Plus-Attention/DeepLabV3 (sup-up-long). Classes: background, effusion, fat, femur, synovium, tendon
+4. **Measurement** — ROI middle 1/3 of bounding box. PIXEL_TO_MM = 45/655
+5. **Severity** — Combined: effusion 60% + synovium 40%. Grades 0-3: Rất nhẹ/Nhẹ/Trung bình/Nặng
+
+### GRADCAM
+- Zero extra clicks (auto on upload)
+- Base64 PNG from FastAPI
+- Canvas overlay, adjust opacity
+
+### WEB WORKER TOPOLOGY
+- `cv.worker.ts` — LiteRT WASM: CV inference (angle pre-classifier). Isolated WASM.
+- `llm.worker.ts` — WebLLM WASM: GemmaE2B local generation. NFR-4 1.5GB heap.
+- `guardrail.worker.ts` — Transformers.js WASM/WebGPU: BERT hallucination/mal-intention/scope-breach scoring.
+
+**Isolation:** No SharedArrayBuffer/Atomics. postMessage with structured clone only.
+
+## FRONTEND DESIGN (WS-25)
+
+### Layout: 65/35 split (Zone A: DICOM | Zone B: Results + Chat)
+
+```
+┌─ Top Bar (patient ID, back, sign) ──────────────────────┐
+├─ Zone A (65%) ────────┬─ Zone B (35%) ────────────────────┤
+│                       │ Phase Indicator (sticky)         │
+│  5 Canvas Layers:      │ Classification Card (grade,conf) │
+│  1. Background        │ Explanation Panel (GradCAM thumb) │
+│  2. GradCAM           │ Chat Panel (Socratic dialogue)    │
+│  3. Segmentation      │ Override Card (Phase 4)           │
+│  4. Annotations (SVG) │ Quick Actions                      │
+│  5. Viewport HUD       │                                    │
+│                        │                                    │
+│  Toolbar: pan/zoom/    │                                    │
+│  brush/eraser/caliper  │                                    │
+├───────────────────────┴───────────────────────────────────┤
+└─ Bottom Bar (NFR status, EMR sync, offline indicator) ─────┘
+```
+
+### Canvas Layers (z-index)
+- 0: Background DICOM (render once, never redraw on pan/zoom)
+- 10: GradCAM (CSS transform, no redraw)
+- 50: Segmentation overlay
+- 100: SVG Annotations (brush/caliper)
+- 200: Viewport HUD (text, mousemove redraw)
+- 900-999: System chrome (top/bottom bar)
+
+### Zustand Store Keys
+- `sessionId`, `patientId`, `currentPhase`
+- `dicomFrame: ImageBitmap | null` (GPU-friendly)
+- `dicomMetadata`, `mlResults` (single atomic object)
+- `clinicianGrade`, `isOverriding`, `overrideJustification`
+- `maskedRegions: MaskedRegion[]` (SVG path data, not raster)
+- `chatMessages` (pruned to 20, older → IndexedDB)
+- `driftScore`, `refereeIntervened`
+- `zoomLevel`, `panOffset` (not persisted, RAF updates)
+- `activeTool: pan|zoom|brush|eraser|caliper|pin`
+- `showGradCAM`, `showSegmentation`
+
+### 6-PHASE WORKFLOW
+1. **Classification** — ML grade, confidence bar
+2. **Explanation** — GradCAM visible, RAG evidence, LLM rationale
+3. **Negotiation** — Socratic dialogue, circuit breaker, BERT drift
+4. **Reconfiguration** — Override card, pixel activation inspector
+5. **Final Decision** — Summary, HITL signature
+6. **EMR Sync** — HL7/FHIR push, audit hash
+
+## KEY API CONTRACTS
+
+### Core Endpoints
+- `POST /api/v1/sessions` → create session
+- `POST /api/v1/sessions/{id}/frames` → upload DICOM (multipart)
+- `POST /api/v1/analysis-jobs` → trigger ML pipeline
+- `GET /api/v1/analysis-jobs/{id}` → get result (angle/inflammation/segmentation/measurement/severity)
+- `GET /api/v1/analysis-jobs/{id}/steps` → step-level status
+- `PATCH /api/v1/sessions/{id}/review` → clinician review (approve/correct/reject)
+- `POST /api/v1/reports` → generate report
+- `POST /api/v1/reports/{id}/sign` → HITL digital signature
+- `POST /api/v1/reports/{id}/emr-sync` → EMR push (outbox if offline)
+
+### Safety Endpoints
+- `POST /api/v1/sessions/{id}/explanations/gradcam` → GradCAM heatmap
+- `POST /api/v1/sessions/{id}/safety/circuit-breaker` → trigger circuit breaker
+- `POST /api/v1/sessions/{id}/chat/socratic` → Socratic dialogue (SSE streaming)
+- `POST /api/v1/sessions/{id}/drift/check` → BERT semantic drift
+- `POST /api/v1/sessions/{id}/rag/evidence` → RAG guideline arbitration
+- `POST /api/v1/feedback` → ground-truth override telemetry
+
+### ML Response Shape
+```json
+{
+  "result": {
+    "angle": { "class": "sup-up-long", "confidence": 0.9845 },
+    "inflammation": { "detected": true, "confidence": 0.942 },
+    "segmentation": { "mask_ref": "s3://...", "overlay_ref": "s3://...", "color_legend": {...} },
+    "measurement": { "thickness_mm": 6.87, "pixel_to_mm": 0.0687 },
+    "severity": { "level": 3, "label": "severe", "combined_score": 18.4 }
+  }
+}
+```
+
+## NFR SUMMARY
+
+| NFR | Target | Implementation |
+|-----|--------|----------------|
+| NFR-4 | ≤150 MB bundle | React PWA, tree-shake, split vendor chunk, Dexie.js |
+| NFR-5 | ≤1.5s inference | Triton ONNX/TensorRT, client memory ≤150MB |
+| NFR-7 | ≤200ms TTFT | SSE streaming, token chunking |
+| NFR-8 | Fault tolerance | IndexedDB cache, SW offline mode, session recovery |
+| NFR-13 | Grad-CAM zero-click | Auto on upload, no extra UI steps |
+| NFR-14 | No client GPU | LiteRT WASM, CPU fallback |
+| NFR-16 | Air-gapped primary | All inference + storage on-prem via K3s |
+| NFR-17 | Immutable audit | PostgreSQL WAL, no UPDATE/DELETE triggers |
+| NFR-18 | RAG citations | 100% LLM text cites MOH via pgvector HNSW |
+| NFR-19 | HITL signature | `signer_id != NULL` constraint before FINALIZED |
+
+## DECREE 13 / CIRCULAR 46
+- Client: Decree 13 regex scrubber (OpenRedaction + pii-filter + js-data-anonymizer) before network
+- Server: FastAPI `phi_scrub` middleware (Microsoft Presidio) as ground-check
+- PDF: Circular 46/2018 format, bilingual VI/EN, audit hash, signer block
+
+## SPRINT 1-2 DELIVERABLES
+
+### Sprint 1 (Jun 15–26) — "Fast PoC Baseline"
+- [ ] PWA shell: React + Zustand + PWA manifest + Service Worker + Dexie.js
+- [ ] DICOM canvas: Cornerstone.js + 5-layer canvas stack
+- [ ] FastAPI `/api/analyze` endpoint (sync 3-step pipeline)
+- [ ] Triton 3-step model ensemble + gRPC
+- [ ] NGINX + Keepalived VIP
+- [ ] Grad-CAM overlay on primary viewport
+- [ ] Circuit-breaker skeleton
+
+### Sprint 2 (Jun 29–Jul 10) — "Multi-Modal & NLP Integration"
+- [ ] GemmaE2B browser WebLLM + Cloud MedGemma Vertex AI
+- [ ] BERT drift monitor + RAG-Referee
+- [ ] Socratic dialogue (SSE streaming)
+- [ ] ladybugDB ontology traversal
+- [ ] Decree 13 scrubber (client + server)
+- [ ] Circular 46 PDF report generator
+- [ ] HITL signature gate
+- [ ] Immutable audit log
+- [ ] EMR/HIS HL7/FHIR push
+
+## KEY FILES
+- `/workspace/sprint_1_2/Design_Material/SPRINT_1_2_ARCHITECTURE_SPEC.md` — sprint-scoped architecture
+- `/PROJ_LEVEL_READING/ARCHITECT/SOFTWARE_ARCHITECTURE_SPEC.md` — full software architecture
+- `/workspace/sprint_1_2/Design_Material/API_docs/API_CONTRACT_DRAFT.md` — API contract v0.2.1
+- `/workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UI_Screen_Spec/Screen_Analysis_WS-25.md` — WS-25 screen analysis
+- `/workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/FR_25_UC_SPEC.md` — FR-25 use case spec
+- `/workspace/sprint_1_2/Design_Material/FR_25_UC_DESIGN/UC_CONTEXT.md` — use case context
+
+## PHASE SEQUENCE (ML Pipeline)
+```
+DICOM upload → CLAHE → Angle Classification → (if post-trans) Inflammation → Segmentation
+→ (if sup-up-long) Inflammation → Segmentation → Measurement → Severity (0-3)
+→ GradCAM overlay → LLM rationale (GemmaE2B/MedGemma + RAG) → Clinician review
+→ HITL sign → EMR push
+```
+
+## NEXT ACTIONS
+- Implement PWA shell (T1-E)
+- Set up FastAPI `/api/analyze` + `/api/consult/stream` (T2-B)
+- Configure Triton ensemble (T2-A)
+- Build WS-25 UI components (Zone A 5-layer canvas + Zone B scrollable panel)
+- Wire up edge guardrail WebWorkers (cv.worker.ts, llm.worker.ts, guardrail.worker.ts)