Source document: docs/project-brain/24-BRAIN-CONTRACT.md
Source version: 1.0.0
Generated time: 2026-07-06T14:59:24.327Z
Owner: Unassigned
Audience: Internal
Status: Approved

24 — BRAIN PUBLIC CONTRACT (v1.0.0)

Hợp đồng công khai của Brain v1.0.0 (brain-v1.0.0). Quy định chính xác cách các OMS version sau tiêu thụ Brain. Contract metadata only — không sửa brain/release/impl. Scope tag: OMS-2I.
Nền: 20-BRAIN-RELEASE · 22-BRAIN-FREEZE · 12-BRAIN-VERSIONING.

1. Supported Consumers

Consumer	Được dùng Brain thế nào
OMS-3	Consumer chính; load brain theo task qua router. Dùng `brain-v1.0.0` tới khi có release mới.
Future Claude sessions	Đọc 00-BRAIN-ROUTER đầu tiên → chỉ load brain router chỉ định.
Automation	Đọc snapshot + trỏ canonical; không suy diễn ngoài brain.
CI validation	Verify freeze (checksum/mtime), link-check, dependency DAG, version khớp 12.
Human contributors	Sửa canonical trước, rồi release brain mới (11-BRAIN-HANDOFF); không sửa brain frozen trực tiếp.

2. Public Brain API

Artifact được phép consume. Stability: Stable (public, ổn định) · Internal (record, không consume runtime) · Deprecated · Experimental.

Filename	Purpose	Stability
00-BRAIN-ROUTER.md	Entry point — map task→brain (rule-based)	Stable
01-BACKEND-BRAIN.md	Backend/Booking snapshot	Stable
02-PLATFORM-BRAIN.md	Platform/travel-os/engineering	Stable
03-BUSINESS-BRAIN.md	Business OS	Stable
04-FOUNDER-BRAIN.md	Founder portal	Stable
05-KNOWLEDGE-BRAIN.md	Knowledge index/OMS	Stable
06-DEPLOYMENT-BRAIN.md	Deployment	Stable
07-SECURITY-BRAIN.md	Security/RLS	Stable
08-ROADMAP-BRAIN.md	Roadmap/sprint	Stable
09-BRAIN-MANIFEST.md	Canonical map + owner + depends	Stable
10-BRAIN-DEPENDENCY.md	DAG load-order	Stable
20-BRAIN-RELEASE.md	Release metadata + manifest	Stable
21-BRAIN-CHANGELOG.md	Changelog by stage	Stable
22-BRAIN-FREEZE.md	Freeze declaration	Stable
24-BRAIN-CONTRACT.md	This contract	Stable
11-BRAIN-HANDOFF.md	Update process (contributors)	Internal
12-BRAIN-VERSIONING.md	Semver rules	Internal
00-SOURCE-AUDIT.md · 00-BRAIN-SCOPE.md	OMS-2A audit records	Internal
13–19 (verification/QA records)	OMS-2C→2G history	Internal
23-BRAIN-RELEASE-QA.md · 25-BRAIN-CONTRACT-QA.md	Release/contract QA	Internal
(none)	—	Deprecated: none · Experimental: none

Runtime consumption = Stable set. Internal records không cần load để làm task (tiết kiệm context budget).

3. Immutable Assets (frozen — cần release mới để đổi)

Brain Pack: 00-BRAIN-ROUTER, 01–08 domain, 09-MANIFEST, 10-DEPENDENCY, 11-HANDOFF, 12-VERSIONING.
Release records (append-only): 00-SOURCE-AUDIT, 00-BRAIN-SCOPE, 13–23, 24 (this), 25.

4. Mutable Assets (được tiến hoá, ngoài freeze)

Canonical sources (source-of-truth): docs/backend/*, travel-os/*, engineering/*, business-os/*, knowledge-index/*, operating-memory/*, packages/*, src/*.
Session tooling ngoài release (chưa verify): BRAIN-RELEASE.md, SESSION-BOOTSTRAP.md, NEW-SESSION.md, CLOSE-SESSION.md, PROJECT-EXECUTIVE-SUMMARY.md.
Future Brain Releases (v1.0.x / v1.1.0 / v2 …).

5. Compatibility Rules


Brain	v1.0.0
Compatible	OMS-3.x (mọi minor của OMS-3)
Incompatible	Old temporary HANDOFF workflow — bị thay thế; consumer không trộn 2 hệ. Brain + OMS (operating-memory) là hệ chính thức.
Minimum Brain Version	1.0.0

6. Breaking Change Rules

Theo semver 12-BRAIN-VERSIONING. Consumer chỉ chịu ảnh hưởng khi MAJOR đổi.

Brain v2.0.0 (MAJOR) — bắt buộc khi phá vỡ contract load của consumer:
Xoá/đổi tên một Brain Pack public (00–10) hoặc đổi ranh giới domain (gộp/tách brain).
Đổi output/format router (00) hoặc schema manifest (09 cột/nghĩa) hoặc ngữ nghĩa dependency (10).
State đảo chiều diện rộng làm snapshot cũ sai hàng loạt (vd RLS production bật → security/deployment brain đảo).
Brain v3.0.0 (MAJOR kế tiếp) — dịch chuyển bậc hai vượt v2:
Đổi hình thức tiêu thụ (markdown-snapshot → API máy-đọc/emit JSON contract).
Federation brain đa-repo, hoặc đổi entry model (bỏ router rule-based).
Mỗi MAJOR = Brain Release mới + migration note; consumer phải đọc lại.
MINOR/PATCH không phá contract (thêm brain/section, sửa typo/link/state tiến triển) — consumer cũ vẫn chạy.

7. Consumer Rules

MUST

Vào qua 00-BRAIN-ROUTER; chỉ load brain router chỉ định.
Coi brain là snapshot; source-of-truth = canonical mà brain trỏ.
Dùng brain-v1.0.0 cho tới khi có Brain Release mới (rollback 20 §6).

MUST NOT

Sửa brain frozen (00–12) trực tiếp.
Coi brain là source-of-truth / hardcode số gắn nhãn "best-known" (vd ~135 test).
Trộn với old HANDOFF workflow.
Bắt buộc load Internal records (13–19) để làm task.

SHOULD

Theo đường dẫn router → brain → canonical khi cần chi tiết (không đọc cả thư mục).
Tôn trọng context budget (OMS 08).
Báo drift qua 11-BRAIN-HANDOFF (sửa canonical → release brain), không vá brain lẻ.

8. Future Extension Policy

Thêm Brain Pack mới

Domain mới → kiểm nguồn tồn tại (00-BRAIN-SCOPE; pending: Product, Sales/GTM, CS).
Build snapshot (trỏ canonical, no copy) → verify (quy trình OMS-2C).
Cập nhật 09-MANIFEST + 10-DEPENDENCY (giữ DAG) + 12-VERSIONING.
Phát hành Brain Release MINOR (v1.1.0).

Gỡ/deprecate Brain Pack

Đánh dấu Deprecated ở manifest + contract (không xoá ngay).
Giữ tối thiểu 1 release cycle; cập nhật router rule + dependency.
Xoá ở MAJOR kế tiếp + migration note. Không auto-delete.

Mọi thay đổi trên đều qua Brain Release + version bump; freeze 22 chỉ mở theo unlock condition.

Nguồn sự thật (Source of Truth): docs/project-brain/24-BRAIN-CONTRACT.md · v1.0.0 · sinh tự động lúc 2026-07-06T14:59:24.327Z. Trang này là view suy dẫn — không sửa trực tiếp.