ltcai 4.0.0 → 4.0.1

package/README.md

@@ -56,10 +56,10 @@ workspace around the work itself:
   LM Studio; nothing leaves your machine unless you opt in.
 - **Use cloud models only when you choose** — bring an API key for cloud LLMs
   when you want them, not by default.
-- **Inspect every agent run** — the built-in runner persists plans, reviews,
-  retries, and results as replayable run records. Today that runner is
-  deterministic and does not call a model; LLM-driven execution is the v4
-  runtime, in progress.
+- **Inspect every agent run** — runs persist queued/running/final state, plans,
+  reviews, retries, cancellation, and replayable logs. With a loaded model the
+  v4 runner uses it; without one, deterministic simulation mode is explicitly
+  labeled and does not call a model.
 
 Lattice AI is not a clone of ChatGPT, Claude, Cursor, Obsidian, or Notion. It
 sits in a different place: a **workspace** that ties local/self-hosted AI, your
@@ -75,8 +75,8 @@ and workflows together — and runs on your own hardware.
   Knowledge Graph.
 - Run local models through MLX, Ollama, or LM Studio, and use cloud LLMs only when
   you want to.
-- Define agent workflows and replay their run records step by step (execution
-  is deterministic scaffolding today — it does not yet call a model).
+- Define agent workflows and replay their run records step by step, including
+  live tool execution, approval pauses, and cooperative cancellation.
 - Separate personal work from organization work.
 - Switch between Basic, Advanced, and Admin modes depending on your role.
 
@@ -115,9 +115,9 @@ connect — context that stays useful even when you switch models.
 ![Lattice AI agent run with roles, logs, review, and retry](docs/assets/v3.4.0/agent-run.png)
 
 The agent runner turns a goal into an inspectable, replayable run record — roles,
-logs, review, and retry — that you can read back step by step. The runner shown
-here is deterministic and LLM-free; real model-driven execution is the v4
-runtime, currently in progress.
+logs, review, retry, and cancellation state — that you can read back step by
+step. Runs execute asynchronously and use the loaded model when one is available;
+otherwise they are labeled as simulation.
 
 ### Extend with hooks and the local runtime
 
@@ -203,34 +203,34 @@ npm run dev
 
 ## Latest Release
 
-### v3.6.0 — Knowledge Graph First
-
-- **Unified ingestion pipeline** — one entrypoint normalizes every source
-  (file, folder, web URL, browser tab, text/markdown/code) into the graph,
-  idempotent by content hash and bracketed by the `pre_tool`/`post_tool` hook
-  lifecycle.
-- **Formalized entity/relationship model** — first-class `Source`, `Repository`,
-  `Meeting`, `Organization`, `Workflow`, `Agent` entities and `indexed_from`,
-  `modified_by`, `belongs_to_project`, `part_of`, `discussed_in`, `decided_by`,
-  `generated_by`, `used_by_agent` relationships.
-- **Browser & web ingestion** — `POST /api/browser/read-url` and
-  `/ingest-current-tab`, plus a local Manifest V3 extension that posts only to
-  `127.0.0.1`.
-- **Portability** — local Knowledge Graph export/import (versioned JSON) and
-  binary backup/restore (DB + blobs, integrity-checked). No cloud required.
-- **Provenance** — every node records where it came from; a queryable audit trail
-  makes the graph explainable.
-- **Knowledge Graph as the primary surface** — the view becomes your digital brain
-  with Status, Sources, Capture, and Backup tabs.
-
-See [RELEASE_NOTES_v3.6.0.md](RELEASE_NOTES_v3.6.0.md),
+### v4.0.1 — Digital Brain Platform Maintenance
+
+- **Brain store architecture** — `knowledge_graph.py` is now a compatibility
+  shim over focused `latticeai/brain/` modules.
+- **v2 write-mastered graph** — `nodes_v2` / `edges_v2` are authoritative;
+  legacy tables stay as a compatibility projection, with pre-flip backup and
+  DB-format guard.
+- **Durable memory and context** — conversations, decisions, experiences, and
+  context traces live in the brain database family.
+- **Real act/runtime foundation** — workflows execute governed tools, pause for
+  approval, run asynchronously with SSE progress/cancellation, and LLM-backed
+  agent runs fail closed instead of fabricating output.
+- **Durable workspace governance** — stable user UUIDs, enforced policy,
+  invitations, and SQLite-backed Workspace OS state preserve identity and
+  workspace history without destructive migration.
+- **Local sovereignty** — signed exports, device identity, scoped graph export,
+  and Brain Network peer exchange are implemented at the API layer.
+- **Post-v4 parity closure** — durable async runs, stable identity/workspace
+  state, and the complete `/app` SPA parity/legacy-retirement work are included
+  in this maintenance release.
+
+See [RELEASE_NOTES_v4.0.1.md](RELEASE_NOTES_v4.0.1.md),
 [docs/kg-schema.md](docs/kg-schema.md),
-[docs/RUNTIME_HOOK_COVERAGE_v3.6.0.md](docs/RUNTIME_HOOK_COVERAGE_v3.6.0.md), and
 [FEATURE_STATUS.md](FEATURE_STATUS.md).
 
 ## How it works — every source converges into the graph
 
-As of v3.6.0, all data sources flow through **one unified ingestion pipeline** into
+As of v4.0.1, data sources flow through the brain ingestion pipeline into
 the Knowledge Graph — no source bypasses it, none becomes an isolated silo:
 
 ```text
@@ -282,6 +282,8 @@ For the deeper design, see [ARCHITECTURE.md](ARCHITECTURE.md) and
 ### Releases
 
 - [RELEASE_NOTES.md](RELEASE_NOTES.md) — current release notes
+- [RELEASE_NOTES_v4.0.1.md](RELEASE_NOTES_v4.0.1.md)
+- [RELEASE_NOTES_v4.0.0.md](RELEASE_NOTES_v4.0.0.md)
 - [RELEASE_NOTES_v3.6.0.md](RELEASE_NOTES_v3.6.0.md)
 - [RELEASE_NOTES_v3.5.0.md](RELEASE_NOTES_v3.5.0.md)
 - [RELEASE_NOTES_v3.4.1.md](RELEASE_NOTES_v3.4.1.md)
@@ -292,7 +294,9 @@ For the deeper design, see [ARCHITECTURE.md](ARCHITECTURE.md) and
 
 | Version | Theme |
 | --- | --- |
-| **3.6.0** | Knowledge Graph First — unified ingestion pipeline, formalized entity/relationship model, browser/web ingestion, local export/import/backup, provenance, KG as the primary surface |
+| **4.0.1** | Digital Brain Platform maintenance — closes post-tag v4 gaps with durable async runs, stable identity/workspace state, full `/app` parity, and legacy UI retirement |
+| **4.0.0** | Digital Brain Platform — decomposed brain store, v2 write-mastered Knowledge Graph, durable memory/context, real workflow/agent foundations, signed brain exchange |
+| 3.6.0 | Knowledge Graph First — unified ingestion pipeline, formalized entity/relationship model, browser/web ingestion, local export/import/backup, provenance, KG as the primary surface |
 | 3.5.0 | Foundation stabilization & verification — OIDC verifier, trusted-proxy gating, runtime hook coverage, `tools/` package, reproducible artifacts |
 | 3.4.1 | Runtime completion — full hooks lifecycle, real Local Agent probes, Connect Folder and Folder Watch verified end-to-end |
 | 3.4.0 | Platform completion — hooks execution, uploads in Files, vision image input, agent run trigger, on-device Local Agent / Connect Folder / Folder Watch |

package/docs/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [4.0.1] - 2026-06-12
+
+> Digital Brain Platform maintenance release for commits on `main` after tag
+> `v4.0.0`. This release does not publish to PyPI, npm, the VS Code
+> Marketplace, or Open VSX; artifacts are built and attached to GitHub Release
+> `v4.0.1` only.
+
+### Added
+
+- Durable async run executor for agent/workflow runs, including persisted
+  queued/running/final states, realtime SSE progress, cooperative cancellation,
+  and startup reconciliation of orphaned active runs.
+- Stable user UUID migration, centralized policy enforcement, local invitation
+  tokens, and SQLite-backed Workspace OS state with JSON compatibility
+  mirroring.
+- Complete `/app` SPA parity surfaces for account/profile/password, workspace
+  and organization administration, invitations, snapshots/time-machine with
+  merge-restore, activity/presence, run approvals/cancellation, workflow
+  triggers, Brain Network pairing/push, chat context trace, and Knowledge Graph
+  provenance coverage.
+
+### Changed
+
+- Retired legacy static HTML/CSS/JS UI pages and legacy visual specs. Legacy GET
+  routes now redirect into the matching `/app` surface.
+- Added en/ko i18n runtime coverage for the shell, routes, and new parity views,
+  guarded by `scripts/lint_v3.mjs`.
+- Bumped synchronized package/runtime versions to `4.0.1`.
+
+### Expected Artifacts
+
+- `dist/ltcai-4.0.1-py3-none-any.whl`
+- `dist/ltcai-4.0.1.tar.gz`
+- `dist/ltcai-4.0.1.vsix`
+- `ltcai-4.0.1.tgz`
+
+## [4.0.0] - 2026-06-12
+
+> Digital Brain Platform. The Knowledge Graph is now the durable brain store
+> spine: focused `latticeai/brain/` modules own graph storage, schema, ingestion,
+> provenance, retrieval, and document structure, while root modules remain
+> compatibility shims.
+
+### Changed
+
+- Decomposed the monolithic Knowledge Graph implementation into focused
+  `latticeai/brain/` modules, with every new module kept below 1,500 lines.
+- Flipped graph writes to `nodes_v2` / `edges_v2` as the authoritative write
+  path; legacy tables are maintained as a compatibility projection.
+- Added one-time pre-flip SQLite backup, `PRAGMA user_version=4`, schema-version
+  reporting, and fail-closed protection for newer DB formats.
+- Added the durable async run executor for agent/workflow runs: persisted
+  queued/running/final states, realtime SSE progress, cooperative cancellation,
+  and startup reconciliation of orphaned active runs.
+- Added stable user UUID migration, centralized RBAC policy enforcement, local
+  invitation tokens, and SQLite-backed Workspace OS state with JSON compatibility
+  mirroring and no durable-history truncation.
+- Retired the legacy static UI pages in favor of the v4 `/app` SPA. Legacy GET
+  routes redirect into `/app`; new parity views cover token-native account,
+  workspace/org management, invitations, snapshots/time-machine with
+  merge-restore, activity/presence, run approvals/cancellation, workflow
+  triggers, Brain Network peer pairing/push, chat context trace, and Knowledge
+  Graph provenance coverage, with en/ko i18n gated by frontend lint.
+
 ## [3.6.0] - 2026-06-10
 
 > Knowledge Graph First. The Knowledge Graph becomes the primary architecture:

package/docs/REALTIME_COLLABORATION.md

@@ -41,7 +41,7 @@ The bus is **in-process** (one server, local-first) and fans events out to
 in-memory subscriber queues.
 
 > **Compatibility.** This subsystem is purely additive. It introduces new
-> `/realtime/*` endpoints and an `/activity` page, and it attaches to the
+> `/realtime/*` endpoints and an `/app#/activity` page, and it attaches to the
 > existing `WorkspaceOSStore` through an optional `event_sink` hook. No v1.x
 > data shape, API, or behavior changes. With zero subscribers the bus is a
 > no-op, so single-user local mode behaves exactly as before.
@@ -274,8 +274,8 @@ router is mounted in `server_app.py` with the live bus, the auth helpers, and
 
 ### `GET /activity`
 
-Serves the Activity UI page (`static/activity.html`). Returns `404` if the UI
-file or static directory is not available.
+Compatibility redirect to `/app#/activity`. The Activity UI is part of the v4
+SPA and reads `/realtime/feed`, `/realtime/presence`, and `/workspace/time-machine`.
 
 ### `GET /realtime/stream`
 

package/docs/V3_FRONTEND.md

@@ -6,9 +6,9 @@
 
 Entry point: **`/app`** (served by `latticeai/api/static_routes.py` →
 `static/v3/index.html`). Login, auto-login after registration, SSO callback, and
-the PWA manifest land on `/app`. The legacy multi-page screens (`/workspace`,
-`/chat`, `/graph`, `/admin`, …) remain reachable only as compatibility/debug
-routes; normal user workflows stay in `/app`.
+the PWA manifest land on `/app`. Legacy multi-page static screens have been
+deleted; compatibility routes (`/workspace`, `/chat`, `/graph`, `/admin`, …)
+redirect into their `/app#/...` views.
 
 ---
 
@@ -31,11 +31,12 @@ One declarative table (`static/v3/js/core/routes.js`) drives the nav rail, the
 command palette, the router, breadcrumbs, and lazy view loading.
 
 ```
-Workspace      Home · Chat
-Retrieval      Knowledge Graph · Hybrid Search
-Data           Files · Pipeline*
-Compute        Agents* · Models · My Computer*
-System         Settings
+Brain          Knowledge Graph · Hybrid Search · Memory
+Ask            Chat
+Capture        Files · Pipeline*
+Act            Agents* · Runs* · Workflows* · Planning* · Hooks*
+Library        Models · Skills* · MCP* · Marketplace*
+System         Overview · Account · Workspaces · Snapshots · Activity · Network* · Settings · My Computer*
 Administration Users · Permissions · Audit Logs · Security · Policies · Private VPC   (admin mode)
 ```
 

package/docs/V4_DIGITAL_BRAIN_RECOVERY.md

@@ -5,22 +5,36 @@
 > completed analysis. **Update this file before ending any phase and before any
 > likely session/context/usage limit.**
 >
-> Last updated: 2026-06-12 — RELEASE CANDIDATE PREPARED (Phase D complete; awaiting human review)
+> Last updated: 2026-06-12 — v4.0.1 maintenance release prep; T9 remainder remains closed
 
 ---
 
 ## 0. RC STATUS (final)
 
-**v4.0.0 release candidate is on `origin/feat/v4-digital-brain`.**
-Validation: 571 unit tests pass · ruff clean · check:python 186 modules ·
-lint_v3 all checks · installed-wheel smoke (19 modules from clean venv) ·
-release artifacts validated (wheel + sdist + npm tgz, 2.0MB).
-NO merge, NO tag, NO publish — awaiting review.
-Remaining gaps (labeled in FEATURE_STATUS.md §v4.0.0 + RELEASE_NOTES_v4.0.0.md):
-T3d decomposition/v2-flip, T7c async engine, T6 remainder (UUIDs/policy/
-invitations/SQLite state), T9 remainder (legacy deletion + parity views,
-login, i18n, T9b surfaces), pptx history rewrite (owner), consent-gated
-embedder provisioning. All contracts live in docs/V4_IMPLEMENTATION_PLAN.md.
+**v4.0.1 packages the `main` commits after tag `v4.0.0`; implementation gaps are empty.**
+Latest verified implementation milestone: T9 remainder closed with full unit coverage
+(`585 passed`), ruff, Python compile, `npm run lint`, `npm run build:assets`,
+Playwright v3 visual coverage, Python sdist/wheel build, installed-wheel smoke,
+and `npm pack --dry-run`.
+The v4.0.1 release process builds and validates artifacts for GitHub Release
+attachment only. It does not publish to PyPI, npm Registry, VS Code Marketplace,
+Open VSX, or production deployment targets.
+v4.0.1 validation completed: Python compile, ruff, 585 unit tests, 9 live
+integration tests, frontend lint, VS Code typecheck, 16 Playwright visual tests,
+Python wheel/sdist build, npm tgz build, VSIX build, release artifact
+validation, wheel smoke, and npm pack dry-run all passed.
+Remaining implementation gaps: **none**.
+Owner-only blockers: pptx history rewrite (requires force-push/owner decision)
+and consent-gated production embedder provisioning (silent default download is
+not permitted).
+
+## Remaining Gaps
+
+None. The T9 remainder was closed on main with legacy page deletion, `/app`
+parity views, token-native account UI, en/ko i18n, approval/run inbox,
+workflow-trigger controls, Brain Network UI, chat context-trace panel, and
+Knowledge Graph provenance coverage surfaced in the SPA. Owner-only blockers
+above are intentionally not implementation gaps.
 
 ## 1. Program Charter (from the user's v4.0.0 directive)
 
@@ -55,7 +69,7 @@ chat-history import added; garden = watched source; T9b UI track added;
 T7 owns workflow_engine.py + realtime.py with suspension/reconciliation
 specs; tracks run strictly serially). Review record:
 `docs/v4-audit/v4_design_review.json`.
-**Phase C (Implementation) — T1 COMPLETE; next: T2 (Packaging & app factory).**
+**Phase C (Implementation) — COMPLETE on main. Remaining implementation gaps are empty.**
 
 Track log (update at every track boundary):
 - **T2 DONE** (commit `5e8aa1b`, 74 files). Agent did ~90% then died on a
@@ -98,10 +112,15 @@ Track log (update at every track boundary):
     mark_superseded(). Suite 507.
   - **T3e DONE**: docs/kg-schema.md rewritten to match code (false API
     claims removed; FTS5/scope/temporal documented).
-  - RESEQUENCING DECISION: T3d (decomposition + write-mastering flip) is
-    agent-scale and limit-blocked until ~17:30 KST; T4 sub-units proceed
-    inline meanwhile — safe because T4 rewires *callers* onto public store
-    APIs which T3d preserves (suite-green gate).
+  - **T3d DONE**: `knowledge_graph.py` is now a root compatibility shim;
+    implementation moved under `latticeai/brain/` (`store`, `schema`,
+    `projection`, `write_master`, `discovery`, `ingest`, `provenance`,
+    `documents`, `retrieval`), with every module under 1,500 lines. v2 is
+    the authoritative write door; legacy tables are maintained as the
+    compatibility projection. Startup creates a one-time pre-flip SQLite
+    backup for existing graph data, stamps `PRAGMA user_version=4`, refuses
+    newer DB formats, and preserves legacy read/import compatibility.
+    Focused KG validation: 43 passed.
 - **T4.1 DONE** (commits `427d6a3` + `a2a1445`): chat (app_factory
   save_to_history), MCP (/mcp/call knowledge_graph_ingest), and uploads
   (upload_service) all route through IngestionPipeline — new
@@ -164,6 +183,16 @@ Track log (update at every track boundary):
   accept allowed_workspaces; search router scopes via _ScopedSearchService
   proxy + PLATFORM.allowed_scopes; ContextAssembler hybrid seam scoped per
   user. Legacy NULL rows machine-visible (documented). Suite 564.
+- **T6-remainder DONE**: users now carry stable `user:<uuid>` identities
+  with non-destructive `users.json` migration; sessions store UUID subjects
+  while preserving email compatibility; workspace memberships/owners and KG
+  identity columns migrate from email strings to UUIDs. `core/policy.py` is the
+  enforced role/capability map behind admin dependencies and `/admin/roles`.
+  Invitations are real local tokens (create/list/accept/expire) and accepted
+  workspace invites add UUID-keyed members. Workspace OS state imports once from
+  JSON into the same `knowledge_graph.sqlite`, mirrors JSON for compatibility,
+  writes transactionally, and no longer truncates durable history collections.
+  Suite: 583.
 - **T7d DONE** (commit 235f9b6): latticeai/services/triggers.py —
   interval scheduler (missed-while-down → recorded skip events, no
   catch-up) + brain_event triggers via visible post_tool hook on
@@ -171,29 +200,31 @@ Track log (update at every track boundary):
   status; started in app factory w/ idempotent hook registration. Suite 569.
 - **T7e DONE** (commit 014ca91): custom registry agents executable
   (config actually loaded; honest skip in simulation).
+- **T7c DONE**: `latticeai/services/run_executor.py` owns durable asyncio
+  server-loop tasks for agent/workflow runs. `/agents/api/run` and workflow
+  definition runs now persist queued rows, execute sync orchestrator/tool work
+  via `asyncio.to_thread`, update the same run row through running/final states,
+  publish progress through the existing realtime SSE feed, support cooperative
+  cancellation, and reconcile orphaned active runs to `interrupted` at startup
+  while preserving `awaiting_approval` pause cursors. `RealtimeBus.publish` is
+  thread-safe via subscriber-loop `call_soon_threadsafe`. Suite: 579.
 - **T9-canvas DONE** (commit 2fee077): force-directed canvas explorer
   (graph-canvas.js + Explore rewire; visual spec updated).
 - **T9-IA DONE** (commit 972d34c): brain-first nav (Brain/Ask/Capture/
   Act/Library/System); knowledge-graph is the default landing route.
-- **PHASE D DECISION**: moving to T10 RC prep. REMAINING GAPS (honest,
-  labeled, not faked): T3d brain decomposition + v2 write-mastering flip;
-  T7c async run engine/cancellation/SSE/startup reconciliation; T6
-  remainder (user UUIDs, enforced policy module, invitations, workspace
-  SQLite state); T9 remainder (legacy page deletion + parity views, login
-  rebuild, artifact ungitting, i18n, T9b approval/network/trace surfaces).
-  All have full contracts in docs/V4_IMPLEMENTATION_PLAN.md + amendments.
+- **T9 REMAINDER DONE**: legacy static pages and scripts deleted; legacy GET
+  routes redirect into `/app`; parity views added for account/profile,
+  workspaces/org members/invitations/activation, snapshots/time-machine with
+  merge-restore, activity/presence, run approvals/cancellation, workflow
+  trigger configuration/status, Brain Network pairing/push, chat context trace,
+  and KG provenance coverage. en/ko i18n runtime backs routes, shell, and new
+  parity views; `scripts/lint_v3.mjs` gates it. Visual coverage moved to the
+  v3 surface and legacy-page specs were retired.
 - T9-canvas agent left static/v3/js/views/graph-canvas.js (509 lines,
   node --check passes) but NEVER rewired knowledge-graph.js — file kept
   uncommitted in tree; integration outstanding.
-- NOTE: T3d + T9-canvas agents died instantly on session limits THREE times
-  (latest reset 4:10am KST)
-  (next reset 23:00 KST); both tasks remain queued with full contracts in
-  this file + the plan.
-  - **T3d** (agent task after limits reset 17:30 KST): latticeai/brain/
-    decomposition (store/discovery/ingest/provenance/documents/extraction,
-    ≤1,500 lines/module, no mixin god-object) + v2 write-mastering flip
-    (backup-first, re-entrant migrator keyed on data state, downgrade
-    marker via PRAGMA user_version, equivalence scoped to pre-flip data).
+- NOTE: The old T3d queue is closed. T9 parity surfaces remain active with
+  full contracts in this file + the plan.
   - **T3e**: docs/kg-schema.md regenerated from enums.
   - graph_curator decision moved to T4.
 - **T9 PARTIAL — vendoring half DONE** (commit `aa613ae`, parallel-safe per
@@ -201,9 +232,7 @@ Track log (update at every track boundary):
   Tabler icons, chart.js, marked.js vendored under static/vendor);
   --lt3-on-accent token added; sw.js rebuilt around the v3 manifest;
   lint_v3.mjs now mechanically enforces token/inline-style/CDN rules;
-  6 guard tests. REMAINING T9: canvas graph port (item 2), IA regroup (1),
-  legacy deletion + redirects (3, needs parity views), login rebuild,
-  artifact ungitting, i18n, T9b surfaces (after T7/T8).
+  6 guard tests. Closed later by T9-canvas, T9-IA, and T9 remainder.
 - **T1 DONE** (commits `1cddc67` frontend + `c574eb6` backend). All 7 items:
   by-id snapshot/memory authz via new WorkspaceService.authorize_record_read/
   authorize_memory_delete; /workspace/os leak removed (workspace_count
@@ -249,8 +278,9 @@ the canonical Phase A record.**
      services, 27 API routers + `server_app.py` at 1,554 lines). Legacy root
      modules ~6,720 lines incl. `knowledge_graph.py` **4,633 lines**,
      `kg_schema.py` 521, `llm_router.py` 775, `mcp_registry.py` 791.
-   - Frontend: `/app` v3 SPA (`static/v3/`, 22 views, token-native) is primary;
-     legacy static HTML pages (`static/*.html`) still shipped in parallel.
+   - Frontend: `/app` v3 SPA (`static/v3/`, token-native) is primary; legacy
+     static HTML pages were later removed and compatibility routes redirect
+     into `/app`.
    - Repo root clutter: ~30 `ltcai-*.tgz` tarballs, `ltcai-0.3.1/` extracted copy,
      logs, `chat_history.json`, 15MB pptx — most likely untracked; verify with
      `git ls-files` before cleaning.
@@ -495,15 +525,28 @@ retained for context only:
 
 ## 11. Branch Status
 
-- `feat/v4-digital-brain` exists locally, based on main @ 5889195 (v3.6.0).
-- Not yet pushed to origin. No implementation commits yet.
+- `main` contains the v4 implementation through T9 remainder closure and is
+  pushed to `origin/main` at every verified milestone.
+- No tag, package publish, release upload, production deployment, force-push, or
+  history rewrite has been performed.
 
 ## 12. Validation Status
 
-- main baseline: 455 unit pass / 9 pre-existing integration failures
-  (ConnectError, need live server). Nothing run on the branch yet beyond this.
+- Full unit suite: `.venv/bin/python -m pytest tests/unit -q` → **585 passed,
+  2 warnings**.
+- Focused T9 tests: `tests/unit/test_workspace_os.py`,
+  `tests/unit/test_static_release_hygiene.py`, and `tests/visual/v3.spec.js`
+  passed after the parity/legacy-retirement changes.
+- Static and code gates: `.venv/bin/python -m ruff check .`,
+  `.venv/bin/python scripts/check_python.py`, `npm run lint`,
+  `npm run build:assets`, and `node --check` on changed/new v3 JS passed.
+- Build/package gates: `.venv/bin/python -m build`,
+  `.venv/bin/python scripts/wheel_smoke.py`, and `npm pack --dry-run` passed.
 
 ## 13. Files Modified (branch vs main)
 
-- `docs/V4_DIGITAL_BRAIN_RECOVERY.md` (this file) — NEW.
-- (none else yet)
+- T9 remainder changed backend compatibility redirects and SPA-facing APIs,
+  Workspace OS snapshot restore, v3 shell/routing/store/i18n/API modules, new
+  parity views, asset manifests, package/static inclusion rules, unit and visual
+  tests, mocks, release/status documentation, and removed retired legacy static
+  pages/scripts/CSS/tests.

package/docs/kg-schema.md

@@ -205,8 +205,12 @@ provenance(source_type, source_uri, content_hash, captured_at, modified_at,
 `knowledge_graph.KnowledgeGraphStore` 가 열릴 때 v2 스키마를 생성/치유하고
 (`kg_schema.KGStoreV2.init_schema` — 추가 컬럼은 `ALTER` 로 in-place 치유,
 edges_v2 식별자 변경은 create→copy→swap 으로 재구축), legacy 데이터를
-v2 로 백필한다. 기존 `nodes` / `edges` 테이블은 건드리지 않는다 — v4 의
-write-mastering 전환(T3d) 전까지 legacy 가 쓰기 마스터다.
+v2 로 백필한다. 기존 `nodes` / `edges` 테이블은 삭제하지 않는다. v4 에서는
+`nodes_v2` / `edges_v2` 가 쓰기 마스터이며, legacy 테이블은 이전 import/API
+소비자를 위한 compatibility projection 으로 같은 트랜잭션에서 갱신된다.
+기존 그래프 데이터가 있는 DB는 전환 전 `backups/*.pre-v2-write-master.*.sqlite`
+스냅샷을 한 번 생성하고, `PRAGMA user_version=4` 와 `kg_meta.db_format_version=4`
+를 기록한다. 더 높은 포맷의 DB는 fail-closed 로 열리지 않는다.
 
 ---
 

package/docs/spec-vs-impl.md

@@ -9,7 +9,7 @@
 
 | 약속 | 목표 (PPT) | 현재 (repo) | 갭 |
 |------|-----------|-------------|----|
-| Cross-Platform Parity | Win·macOS·Linux·iOS·Android, 같은 디자인 토큰·컴포넌트 | Web(static) + VSCode ext + Telegram (브라우저 어디서나) | 네이티브 데스크탑/모바일 셸 없음 (PWA 부분 지원) |
+| Cross-Platform Parity | Win·macOS·Linux·iOS·Android, 같은 디자인 토큰·컴포넌트 | `/app` SPA + VSCode ext + Telegram (브라우저 어디서나) | 네이티브 데스크탑/모바일 셸 없음 (PWA 부분 지원) |
 | Zero-Config Auto Setup | PROBE → RECOMMEND → INSTALL → VERIFY → PRESET, 90초 내 | `LTCAI doctor` (의존성만 체크 = PROBE의 일부) | GPU/RAM 프로빙, 추천, 설치, 벤치마크, 프리셋 미구현 |
 | Everything is a Graph | 10 노드 타입 / 12 엣지 타입 / 임베딩 / 신뢰도+증거 | nodes·edges·chunks 테이블 + 한글 동사 엣지(EDGE_VERB) | 명시 enum·embedding·confidence/evidence·owner 결손 |
 
@@ -20,7 +20,7 @@
 PPT 명세는 "한 코드·다섯 화면" — Shared Core(Design Tokens, UI Components, Business Logic, AI/Graph Core) 위에서 Tauri(데스크탑) / Capacitor·RN(모바일) 렌더러가 같은 결과를 낸다.
 
 **현재 구현**
-- `static/chat.html`, `static/graph.html`, `static/admin.html`, `static/account.html` 4개 HTML — `static/css/tokens.css` 단일 토큰을 공유 (v2.2.1)
+- `static/v3/` `/app` SPA — 단일 토큰과 컴포넌트를 공유하며 legacy HTML 페이지는 v4에서 삭제됨
 - `vscode-extension/` — TypeScript VSCode 통합
 - `static/manifest.json` + `static/sw.js` — PWA 부분 지원 (iOS/Android 홈 화면 추가는 됨)
 - `telegram_bot.py` — Telegram 미러
@@ -28,11 +28,11 @@ PPT 명세는 "한 코드·다섯 화면" — Shared Core(Design Tokens, UI Comp
 **갭**
 - 데스크탑 네이티브 셸 (Tauri) 미구현
 - 모바일 네이티브 (Capacitor / RN) 미구현
-- 다국어(i18n) 시스템화 안 됨 (HTML에 한글 하드코딩)
+- `/app` SPA i18n(en/ko) 런타임은 구현됨; 네이티브 데스크탑/모바일 셸은 아직 없음
 
 **보강 결과물 (완료, v2.2.1)**
-- `static/css/tokens.css` — 4개 HTML이 공유하는 단일 진실 토큰 (`:root` = 라이트, `[data-lt-theme="dark"]` = 다크)
-- `static/css/responsive.css` + `static/scripts/ux.js` — 반응형 레이아웃 / 라이트·다크 토글 + OS 감지 + 지속화
+- `static/css/tokens.css` + `static/v3/css/` — `/app` SPA가 공유하는 단일 진실 토큰
+- `static/v3/js/core/store.js` + `shell.js` — 반응형 레이아웃 / 라이트·다크 토글 + OS 감지 + 지속화
 - 로드맵: `apps/desktop/` (Tauri 셸) · `apps/mobile/` (Capacitor 셸) 차후 단계
 
 ---
@@ -103,9 +103,9 @@ chunks ( id, source_node, text, metadata_json, created_at )
 | **PPT 명세** | `#FFFFFF` 또는 `#0B0B16` | `#6E4AE6` Lattice 보라 |
 
 **보강 결과물 (완료, v2.2.1)**
-- `static/css/tokens.css` — 단일 토큰을 모든 화면이 공유. `:root` 가 라이트 값,
+- `static/css/tokens.css` — 단일 토큰을 `/app` 화면이 공유. `:root` 가 라이트 값,
   `[data-lt-theme="dark"]` 가 다크 값을 정의하는 단일 진실 소스
-- 라이트/다크 토글 + OS 다크모드 감지 + 지속화는 `static/scripts/ux.js` 가 담당
+- 라이트/다크 토글 + OS 다크모드 감지 + 지속화는 `static/v3/js/core/store.js` 와 `shell.js` 가 담당
 
 ---
 
@@ -115,10 +115,10 @@ PPT 화면 1, 13 (login, security) 에 한국어 / Microsoft Entra ID / Okta SSO
 
 **현재**
 - `server.py` 의 `/auth/sso` 엔드포인트 존재 (architecture.md 언급) — Entra/Okta 둘 다 명시되어 있는지 확인 필요
-- 다국어 — HTML 하드코딩 (`lang="ko"`)
+- 다국어 — `/app` SPA en/ko 런타임(`static/v3/js/core/i18n.js`)과 언어 선택이 구현됨
 
 **갭 / 다음 단계**
-- i18n 사전 (`static/i18n/{ko,en,ja}.json`) 추출 → PPT 명세 그대로 토큰화
+- i18n 사전 런타임은 `static/v3/js/core/i18n.js` 로 구현됨; 추가 언어는 이 사전에 확장
 
 ---
 
@@ -127,7 +127,7 @@ PPT 화면 1, 13 (login, security) 에 한국어 / Microsoft Entra ID / Okta SSO
 | 순위 | 파일 | 무엇 |
 |------|------|------|
 | 1 | `docs/kg-schema.md`, `kg_schema.py` | KG 스키마 정식화 (10 노드 · 12 엣지 · embedding · confidence) |
-| 2 | `static/css/tokens.css` (+ `responsive.css`, `ux.js`) | 디자인 토큰 통합 + 라이트/다크 — v2.2.1 완료 |
+| 2 | `static/css/tokens.css` + `static/v3/` | 디자인 토큰 통합 + 라이트/다크 + en/ko i18n |
 | 3 | `auto_setup.py` | OS 프로빙 + 모델 추천 + 설치 어댑터 |
 | 4 | `docs/architecture.md` 보강 | 위 변경 반영 |
 | 5 | (차후) `apps/desktop`, `apps/mobile` 스캐폴딩 | Tauri/Capacitor |