docs/reference/KNOWN_FAILURE_MODES.md

Known Failure Modes

Severity

• Critical: có thể xóa/lộ dữ liệu diện rộng, vượt ranh giới project hoặc làm mất khả năng phục hồi.
• High: chặn journey chính, gây mất artifact/job hoặc tạo output sai mà người dùng dễ tin là đúng.
• Medium: làm một capability suy giảm, gây nhầm lẫn hoặc cần thao tác thủ công để phục hồi.
• Low: chủ yếu là maintainability, observability hoặc polish.

Đây là rủi ro SOURCE_VERIFIED và NOT_RUNTIME_VERIFIED, không khẳng định mọi lỗi đã xảy ra trên production và không phải kết quả exploit/PoC. Nguồn audit: 595ccdfaf45ff83473f2da8fd2c71d491828e5f5.

Critical

ID	Failure mode	Điều kiện/kết quả	Bằng chứng	Hướng xử lý ở Oloka
C-01	Project path operations thiếu containment resolver thống nhất	Các đường project select, detail, diagnostics, bulk delete, delete, clone, thumbnail và mutation favorite/posted ghép hoặc resolve project ID/path tại route. Source inspection cho thấy các đường này không cùng sử dụng một containment resolver thống nhất. Đây là risk traceability từ source, không khẳng định đã khai thác được.	routes/projects.js; đối chiếu resolver trong services/projectService.js	Dùng opaque ID, resolver duy nhất, containment check và authorization cho mọi filesystem operation; thêm regression test traversal
C-02	Xóa project không có trash/transaction/restore	DB delete và recursive filesystem delete là hai side effect tách rời; lỗi DB đôi khi bị bỏ qua trước khi xóa filesystem. Không có trash, restore hoặc shared transaction; bulk delete có thể trả partial success. Không chạy destructive PoC trong Phase 0.	routes/projects.js, services/projectService.js	Soft delete + retention, immutable object versions, transaction/outbox, audit và explicit purge riêng

High

ID	Failure mode	Điều kiện/kết quả	Bằng chứng	Hướng xử lý ở Oloka
H-01	DB, meta.json, disk và RAM lệch nhau	Ghi metadata rồi DB upsert bất đồng bộ; list/status có nhiều fallback. UI có thể thấy project/job khác artifact thật.	services/projectService.js, routes/projects.js, services/jobStore.js	Một canonical DB state; object store chỉ giữ bytes; reconcile bằng event/outbox
H-02	Job đang chạy/xếp hàng mất khi server restart	Queue, abort controller và process handles ở RAM; startup đánh running/queued thành failed.	services/jobRuntimeService.js, services/jobStore.js, services/projectService.js	Durable queue/state machine, lease/heartbeat, idempotent step resume
H-03	Progress giả hoặc không đồng bộ	UI nhận SSE, polling, DB projection và progress suy ra từ step/log; queued DB write từng có nguy cơ ghi đè running.	routes/forge.js, services/jobRuntimeService.js, services/forgeStatusPayload.js, public/app.js	Server event sequence monotonic, persisted progress, one read model
H-04	Preview khác render	Preview static/child process và render local/Modal có môi trường, font, registry, browser và asset bundle khác nhau.	server.js, services/renderProviders.js, deploy/modal-renderer/app.py, services/renderFonts.js	Cùng container/runtime contract; preflight bundle; golden frame comparison
H-05	Registry block thiếu nhưng phát hiện muộn	Composition tham chiếu sub-composition chưa materialize có thể qua preview rồi fail trước/final render.	services/templateRegistryService.js, services/forgePipelineService.js, routes/render.js	Resolve dependency graph ngay khi save/generate; artifact manifest immutable
H-06	TTS job treo/cold-start/invalid response	Omnivoice có retry nhưng tổng thời gian dài; một scene lỗi chặn narration; alignment có thể thiếu.	services/omnivoiceSceneTts.js, services/ttsMediaService.js	Durable per-scene jobs, deadline tổng, circuit breaker, resume từ scene
H-07	LLM trả rỗng/sai JSON hoặc schema không đạt	Call có thể chờ 10 phút; pipeline phụ thuộc JSON lớn và nhiều repair loop; retry có thể tốn token nhưng không bảo đảm determinism.	server.js, services/llmStreamingService.js, services/forgePipelineService.js, services/jsonUtils.js	Typed schema, bounded output, checkpoint immutable, idempotency, token budget
H-08	Modal timeout/version/bundle mismatch	Client timeout 15 phút, function 30 phút; base64 bundle có giới hạn; HyperFrames version có thể drift.	services/renderProviders.js, deploy/modal-renderer/app.py, package.json	Versioned render protocol, object-store bundle, aligned deadline, capability handshake
H-09	Output delivery trỏ object chưa có hoặc stale	Signed URL được sinh theo path dự kiến; app không upload riêng mà dựa vào /data mount; current output bị ghi đè và cache qua nhiều URL/version.	services/hfBucketDelivery.js, routes/media.js, services/videoDelivery.js, services/projectService.js	Render output immutable + checksum + availability state trước khi publish URL
H-10	Shared asset library không cô lập tenant	Library dùng chung; regular user đọc/use, admin quản lý; BGM mutation routes không áp dụng cùng admin guard; static /assets được phục vụ trước auth.	server.js, routes/assets.js, routes/bgm.js, services/assetLibraryStore.js	Asset owner/visibility trong DB; signed URLs; policy thống nhất mọi mutation
H-11	Secret lưu plaintext hoặc đi qua URL/browser	Shared provider/social secrets là JSON trong SQLite; localStorage giữ key local; direct TTS status nhận token query.	services/sharedConfig.js, public/app.js, routes/tts.js	Secret manager/encryption, server-side credential reference, không token trong URL
H-12	Social publish không durable	Upload chạy trong request; không có retry queue, token refresh hay reconciliation/poll platform status.	routes/socialPublish.js, public/app.js	Publish job durable riêng, per-platform adapter/idempotency/status polling
H-13	Cloudflare deployment drift/không tái tạo được	Scripts/package trỏ tới Worker source/config không có trong snapshot; smoke contract khác Express.	package.json, scripts/*cloudflare*, tracked file inventory	Remove khỏi MVP hoặc phục hồi thành repo/module versioned có contract tests
H-14	Schema thay đổi khi startup	App import DB tự tạo bảng và ALTER TABLE; failure giữa startup có thể để schema nửa chừng, không có rollback/version ledger.	scripts/db.js	Versioned migrations chạy riêng, backup/rollback và startup chỉ verify

Medium

ID	Failure mode	Điều kiện/kết quả	Bằng chứng	Hướng xử lý ở Oloka
M-01	Project ID/workspace không nhất quán	workspace, workspace-<user>, projects/<id> và bare ID cùng xuất hiện; middleware còn logic rewrite/proxy cũ.	server.js, routes/projects.js, services/projectService.js, public/app.js	Opaque UUID; Workspace Oloka UNDECIDED, Phase 1 chọn entity độc lập hoặc project list, tuyệt đối không alias
M-02	Upload lớn làm đầy RAM hoặc request timeout	JSON global 50 MB; raw upload 25/50/100 MB; Modal bundle base64 đọc toàn bộ file.	server.js, routes/assets.js, routes/composition.js, services/renderProviders.js	Direct multipart/object upload streaming, quotas, checksum, resumable upload
M-03	Upload asset kết thúc nhưng analysis pending/failed	Upload trả metadata mock/fallback rồi background analysis; UI phải poll toàn library; analysis state có thể kẹt.	routes/assets.js, services/assetAnalysisService.js, public/app.js	Asset ingestion state machine + event per asset + explicit retry
M-04	DAM báo thành công nhưng không tạo file	Tách nền dùng timer và alert mô phỏng; tìm similar chỉ đổi query; individual duplicate detect là heuristic client.	public/app.js	Gỡ UI khỏi MVP hoặc nối vào job thật; không hiển thị success khi không có artifact
M-05	Collections/shared/trash/AI-generated là navigation UI hơn là domain thật	Không có entity/route tương ứng cho phần lớn view; metadata collection chỉ là string sidecar.	private/dashboard-shell.html, public/app.js, routes/assets.js	Chỉ ship library/filter cơ bản; thiết kế collection/trash sau
M-06	Font endpoint không hoạt động qua app	routes/fonts.js tồn tại và frontend gọi /api/fonts, nhưng server.js không import/mount router.	routes/fonts.js, public/app.js, server.js	Contract test route mount; bundle font manifest ở build time
M-07	Endpoint legacy tạo hành vi khác Forge	/generate, /tts, /compile, /render tồn tại nhưng dashboard dùng /forge; fix có thể chỉ cập nhật một đường.	routes/generate.js, routes/tts.js, routes/compile.js, routes/render.js, public/app.js	Xóa đường legacy; một orchestration API/version
M-08	Encoding tiếng Việt/mojibake	Source có guard/repair và check riêng, cho thấy dữ liệu/file cũ có thể sai encoding; tên workspace bootstrap còn text không dấu.	services/encodingGuard.js, scripts/check-encoding.js, routes/projects.js, server.js	UTF-8 end-to-end, normalize ở boundary, fixture tiếng Việt trong test
M-09	Activity audit mất continuity	Activity DB có thể chuyển sang temp fallback; event insert bị catch và bỏ qua để không chặn request.	services/activityEventDatabase.js, server.js, scripts/db.js	Durable audit sink hoặc outbox; surface degraded state
M-10	Quality report không có vision nhưng UI có thể hiểu là pass	QA có technical checks và optional vision; flags quyết định có block completion hay không.	services/videoQualityService.js, services/forgeQualityService.js, routes/quality.js	Tách technical_pass, visual_reviewed, approved; không dùng một boolean mơ hồ
M-11	Render history record còn nhưng file mất	History là JSON + copied files, không có FK/checksum/transaction.	services/projectService.js	RenderOutput entity immutable với object existence verification
M-12	OAuth/network request không có deadline thống nhất	Google/GitHub token/profile calls không có timeout/retry explicit.	auth.js	Shared HTTP client với deadline, retry safe và telemetry
M-13	Permission policy không đồng nhất	Một số route tự kiểm admin bằng env/role, một số chỉ dựa global middleware; local auth disabled coi mọi request là admin.	server.js, auth.js, routes/assets.js, routes/bgm.js, routes/projects.js	Deny-by-default policy middleware và authorization matrix tests
M-14	Admin analytics là projection từ nguồn không đồng nhất	Jobs, users, activity, pricing và disk-derived history được kết hợp; deleted users có placeholder.	routes/admin.js, auth.js, services/admin*.js	Event/data warehouse projection có version và freshness indicator

Low

ID	Failure mode	Kết quả	Bằng chứng	Hướng xử lý ở Oloka
L-01	Frontend monolithic	public/app.js, CSS, HTML shell và generated editor bundle rất lớn; thay đổi khó review/test.	public/app.js, public/style.css, private/dashboard-shell.html, public/studio-editor.js	Module theo feature, typed API client, component tests
L-02	Forge service monolithic	Pipeline create/edit lặp nhiều nhánh và checkpoint logic; blast radius lớn.	services/forgePipelineService.js	Step handlers nhỏ, state machine, shared contracts
L-03	Duplicate storage abstractions chưa dùng	Local blob/project store và object key helpers không có consumer production.	services/storage/localBlobStore.js, services/storage/localProjectStore.js, services/storage/projectObjectKeys.js	Chọn một interface và wire thật hoặc xóa
L-04	Security scan phạm vi hẹp	Scanner chỉ so secret cụ thể từ .env với một số thư mục; không thay thế secret scanning chuẩn.	scripts/security-scan-secrets.mjs	Gitleaks/secret scanning CI + dependency/SAST policy
L-05	Route tồn tại nhưng không được mount	Font router là bằng chứng rõ; file name không đủ chứng minh feature active.	routes/fonts.js, server.js	Route registry generated + reachability tests

Critical/High cần chặn trước MVP

1. Opaque project IDs và containment tuyệt đối cho mọi file operation.
2. Soft-delete/restore và durable storage versioning.
3. Một canonical project/job state model; không suy luận state từ log.
4. Durable queue với lease, retry, cancel và resume idempotent.
5. Secret manager + tenant-aware asset authorization.
6. Immutable render artifact và provider protocol versioned.
7. Chỉ một deployment topology và một orchestration API.