Add Vietnam e-commerce compliance causal pack

README.md

@@ -15,8 +15,11 @@ data/
 └── insights.json      # Recurring causal patterns
 
 packs/
-└── worldcup-2026/     # Optional vertical pack for live causal timelines
+├── worldcup-2026/                  # Live sports/event intelligence
+└── vn-ecommerce-compliance-2026/   # Regulation → control → evidence timeline
     ├── README.md
+    ├── manifest.json               # Optional pack metadata
+    ├── views.json                  # Optional Canvas/audience projections
     ├── events.json
     ├── links.json
     └── insights.json
@@ -94,8 +97,9 @@ Current packs:
 | Pack | Purpose |
 |------|---------|
 | [`worldcup-2026`](packs/worldcup-2026/) | Proof of concept for live sports/event intelligence using World Cup 2026 results, causal implications, and watchpoints |
+| [`vn-ecommerce-compliance-2026`](packs/vn-ecommerce-compliance-2026/) | Evidence-first timeline connecting Vietnamese legal changes to role-owned controls and proof of execution |
 
-See [docs/PACKS.md](docs/PACKS.md) for pack structure and quality guidelines.
+See [docs/PACKS.md](docs/PACKS.md) for pack structure and quality guidelines, and [docs/PACK-VIEWS.md](docs/PACK-VIEWS.md) for optional Canvas and teaching projections.
 
 ## Relationship types
 

docs/PACK-VIEWS.md

@@ -0,0 +1,153 @@
+# Pack Manifests and Canvas Views
+
+Causari packs contain a canonical causal graph and may optionally contain presentation metadata.
+
+The separation is deliberate:
+
+```text
+canonical graph data
++ audience/view projection
+= timeline, canvas, lesson, recap, or decision workflow
+```
+
+## Canonical files
+
+Every pack continues to use:
+
+```text
+events.json
+links.json
+insights.json
+```
+
+These files must remain portable across the MCP server, Canvas, static imports, runtime fetches, and future consumers.
+
+## Optional files
+
+A pack may add:
+
+```text
+manifest.json
+views.json
+```
+
+### `manifest.json`
+
+The manifest describes the pack rather than changing graph semantics.
+
+Recommended fields:
+
+```json
+{
+  "id": "pack-id",
+  "version": "0.1.0",
+  "title": "Pack title",
+  "description": "Purpose and scope",
+  "language": "en",
+  "defaultLocale": "vi",
+  "jurisdiction": "VN",
+  "temporalMode": "effective-date-timeline",
+  "graphMode": "instrument-to-control-to-evidence",
+  "updateCadence": "event-driven",
+  "asOf": "2026-07-30",
+  "files": {
+    "events": "events.json",
+    "links": "links.json",
+    "insights": "insights.json",
+    "views": "views.json"
+  },
+  "canvas": {
+    "defaultView": "executive-impact",
+    "recommendedLayout": "timeline-lanes",
+    "laneField": "lane",
+    "nodeTypeField": "nodeType"
+  }
+}
+```
+
+Consumers must treat unknown manifest fields as optional.
+
+### `views.json`
+
+A view is a projection over the graph. It may define:
+
+- audience
+- guiding question
+- included or focused event ids
+- lane definitions
+- highlighted causal paths
+- story steps
+- teaching notes
+
+A view must not duplicate canonical events or links.
+
+Example:
+
+```json
+[
+  {
+    "id": "teaching-causal-chain",
+    "title": "Teach the causal chain",
+    "audiences": ["teacher", "student"],
+    "projection": {
+      "trigger": ["instrument", "effective-date"],
+      "response": ["action"],
+      "adaptation": ["control"],
+      "observableOutcome": ["evidence"]
+    }
+  }
+]
+```
+
+## Why views are generic
+
+A compliance pack may use:
+
+```text
+law → implementation → control → evidence
+```
+
+A World War I lesson pack may use:
+
+```text
+structural cause → trigger → escalation → outcome → source evidence
+```
+
+A World Cup pack may use:
+
+```text
+match result → table implication → affected team → next watchpoint
+```
+
+The domains differ, but all are narrative projections over event-and-link data.
+
+## Design rule: data is canonical, views are disposable
+
+Do not encode a lecturer's slide order, an executive dashboard filter, or one UI layout into the causal graph itself.
+
+Instead:
+
+1. Curate events and links once.
+2. Add provenance and honest confidence.
+3. Create multiple views for different jobs.
+4. Allow consumers to ignore view metadata entirely.
+
+This avoids three common failures:
+
+- duplicating nodes for each audience
+- coupling data packs to one frontend
+- weakening causal semantics to satisfy a presentation layout
+
+## Suggested Canvas behavior
+
+A Canvas consumer may:
+
+1. Load `manifest.json` when present.
+2. Load the canonical graph.
+3. Offer the view list from `views.json`.
+4. Filter or emphasize nodes according to the selected view.
+5. Render lanes from event metadata such as `lane`.
+6. Enter story mode using `highlightPaths` or `storySteps`.
+7. Always preserve access to sources and confidence.
+
+Views should degrade gracefully. A consumer that only understands `events.json`, `links.json`, and `insights.json` must still load the pack successfully.

docs/PACKS.md

@@ -18,11 +18,15 @@ Examples:
 ```text
 packs/{pack-id}/
 ├── README.md       # pack purpose, audience, curation notes
+├── manifest.json   # optional pack metadata and consumer hints
+├── views.json      # optional Canvas, audience, and teaching projections
 ├── events.json     # CKGEvent-compatible events
 ├── links.json      # CausalLink-compatible relationships
 └── insights.json   # recurring patterns found inside this pack
 ```
 
+`events.json`, `links.json`, and `insights.json` are canonical. Optional manifest and view files must not be required by older consumers. See [PACK-VIEWS.md](PACK-VIEWS.md) for the projection model.
+
 ## Compatibility
 
 Pack files should remain compatible with the existing Causari schemas:
@@ -44,13 +48,16 @@ For live or short-horizon timelines, packs may use the following optional event
 
 These optional fields let a pack model live event intelligence without changing the core schema.
 
+Domain packs may also add optional fields such as `nodeType`, `lane`, `audiences`, `normativeStatus`, or `lifecycleStatus`. Consumers must ignore unknown optional fields and preserve the canonical event/link semantics.
+
 ## Graph modeling rules (required for clean loading)
 
 A pack is a causal graph. To load cleanly into any Causari consumer (the visual explorer, the MCP store, an agent), it must follow the same structural rules as the core dataset:
 
 - **Links connect events to events.** A `CausalLink`'s `fromEvent` and `toEvent` must both be `id`s of events **in the same pack**. Never point a link at an insight id or at a node that isn't defined — that produces dangling edges in the visual.
 - **Insights attach to links, not the other way around.** An `Insight.instances` array lists the `CausalLink` ids that demonstrate the pattern. Insights are not graph nodes and are never link endpoints.
 - **Upcoming fixtures are events with `status: "scheduled"`.** Model a "watchpoint" (a match that hasn't happened yet) as a real scheduled event, then link the completed result to it. This keeps `nextWatchpoints` (free-text hints) separate from the actual graph edges.
+- **Operational controls must not masquerade as completed work.** For action/control/evidence nodes, use a domain-specific field such as `lifecycleStatus`; reserve the core `status` field for event state.
 - **Ids are kebab-case and globally unique** (e.g. `wc2026-brazil-draws-morocco`). Avoid `--` inside an event id so the link id `{from}--{rel}-->{to}` stays unambiguous.
 
 Run `node scripts/validate-pack.mjs <pack-id>` before every commit — it enforces all of the above (referential integrity, id format, enums, 0–1 ranges) and is wired into CI.
@@ -117,4 +124,6 @@ A visual explorer can then render:
 Event → causal link → affected entity → next watchpoint
 ```
 
+When `manifest.json` and `views.json` exist, a Canvas consumer may add lane layouts, audience filters, highlighted paths, or teaching story mode while still loading the same canonical graph.
+
 See [LIVE-UPDATES.md](LIVE-UPDATES.md) for the daily match-day update workflow.

packs/vn-ecommerce-compliance-2026/README.md

@@ -0,0 +1,179 @@
+# Vietnam E-commerce Compliance 2026
+
+> An evidence-first causal pack connecting legal change to operational control and proof of execution.
+
+This pack is an initial research preview for Vietnamese e-commerce, social commerce, livestream selling, household-business tax operations, electronic invoices, and cybersecurity.
+
+It does **not** try to summarize every law effective from July 1, 2026. It models a narrower, testable wedge:
+
+```text
+legal instrument
+→ effective rule
+→ role-owned action
+→ operating control
+→ evidence
+```
+
+## Why this pack exists
+
+SMEs usually do not fail because they cannot download legal documents. They fail because they cannot quickly determine:
+
+- whether a rule applies to their business model
+- which team owns the response
+- which product or operating process must change
+- what evidence proves the control actually ran
+- what changed after the last review
+
+The pack turns those questions into a causal graph that can be used by humans, AI agents, and timeline/canvas interfaces.
+
+## Scope
+
+The initial version focuses on:
+
+- E-Commerce Law No. 122/2025/QH15
+- Decree No. 248/2026/NĐ-CP
+- Tax Administration Law No. 108/2025/QH15
+- Decree No. 252/2026/NĐ-CP
+- Decree No. 254/2026/NĐ-CP on electronic invoices and documents
+- Cybersecurity Law No. 116/2025/QH15
+- derived operating controls for seller governance, livestream identity and product claims, transaction-to-invoice reconciliation, access and incident auditability, and evidence management
+
+Out of scope for this first version:
+
+- a complete inventory of all laws, decrees, and circulars effective in 2026
+- organization-specific legal conclusions
+- penalty calculations
+- automated legal advice
+- replacing review by qualified legal, tax, or accounting professionals
+
+## Files
+
+```text
+packs/vn-ecommerce-compliance-2026/
+├── README.md
+├── manifest.json
+├── views.json
+├── events.json
+├── links.json
+└── insights.json
+```
+
+The three canonical graph files remain compatible with the existing Causari pack loader:
+
+- `events.json`
+- `links.json`
+- `insights.json`
+
+`manifest.json` and `views.json` are optional projection metadata for Canvas, teaching, role-based filtering, and story mode.
+
+## Node model
+
+Every node is still a Causari event, but optional fields describe how a consumer may project it:
+
+| Field | Meaning |
+|---|---|
+| `nodeType` | `instrument`, `effective-date`, `action`, `control`, or `evidence` |
+| `lane` | `law`, `implementation`, `operations`, or `evidence` |
+| `normativeStatus` | `binding`, `derived-control`, or `recommended-practice` |
+| `lifecycleStatus` | Current operating state for non-legal nodes, such as `active` |
+| `audiences` | Roles that should see the node |
+| `sources` | Provenance for factual or binding claims |
+
+The distinction between `normativeStatus` values is essential:
+
+- **binding**: directly represents an enacted legal instrument or effective provision
+- **derived-control**: an operational interpretation grounded in an official summary
+- **recommended-practice**: a Causari implementation recommendation, not a direct quotation of law
+
+## Canvas timeline
+
+The recommended Canvas layout uses four lanes:
+
+```text
+Law
+  ↓
+Implementation
+  ↓
+Operations
+  ↓
+Evidence
+```
+
+`views.json` provides reusable projections:
+
+- executive impact
+- tax and accounting operations
+- e-commerce and livestream
+- IT and security
+- teaching causal chain
+
+A consumer should load the canonical graph once, then apply a view without copying or rewriting the underlying data.
+
+## Relation to teaching packs such as WWI
+
+The same view abstraction can power a historical lesson:
+
+```text
+historical trigger
+→ institutional response
+→ military/political adaptation
+→ observable outcome
+→ primary-source evidence
+```
+
+For compliance, the equivalent is:
+
+```text
+legal trigger
+→ implementation rule
+→ organizational adaptation
+→ operating evidence
+```
+
+This means `views.json` is not a legal-specific UI configuration. It is a generic narrative projection layer over a causal graph. A WWI pack might define views such as:
+
+- long-term causes
+- July Crisis escalation
+- alliance propagation
+- fronts and turning points
+- consequences and counterfactuals
+
+The data remains canonical; lecturers, executives, analysts, and AI agents see different paths through it.
+
+## Intended users
+
+### SME leaders
+
+Understand which changes deserve budget, ownership, and sequencing.
+
+### Tax, legal, and operations teams
+
+Move from document reading to an executable backlog and evidence register.
+
+### Software and platform teams
+
+Translate regulation into identity, workflow, logging, reconciliation, and retention requirements.
+
+### Lecturers and facilitators
+
+Use story mode to explain how a trigger propagates through a system.
+
+### AI agents
+
+Answer questions such as:
+
+- Which binding event led to this control?
+- Is this node law, derived guidance, or a recommendation?
+- Which roles are affected?
+- What evidence should exist?
+- Which source supports the claim?
+
+## Quality and safety
+
+- Binding events must use official government or ministry sources.
+- Derived controls must never be presented as verbatim legal requirements.
+- Every update must preserve an `asOf` date.
+- Applicability must be evaluated for each organization.
+- High-risk interpretations should be reviewed by qualified professionals.
+
+> This pack is a research and operational-design aid, not legal or tax advice.

packs/vn-ecommerce-compliance-2026/insights.json

@@ -0,0 +1 @@
+[{"id":"pattern--regulation-control-evidence-chain","pattern":"Regulation → Control → Evidence","pattern_vi":"Quy định → Kiểm soát → Bằng chứng","description":"A legal instrument has little operational value until it is translated into a control with an owner and then into recurring evidence. This pattern works beyond compliance: a history-teaching pack can similarly project trigger → response → outcome → source evidence.","description_vi":"Văn bản pháp luật có ít giá trị vận hành nếu chưa được chuyển thành kiểm soát có người phụ trách và bằng chứng lặp lại. Mẫu này cũng dùng được ngoài compliance: pack giảng dạy lịch sử có thể chiếu theo chuỗi tác nhân → phản ứng → kết quả → bằng chứng nguồn.","instances":["vnce-decree-ecommerce-248-effective--enabled-->vnce-platform-seller-governance-control","vnce-platform-seller-governance-control--enabled-->vnce-compliance-evidence-register","vnce-decree-einvoice-254-effective--enabled-->vnce-transaction-invoice-reconciliation-control","vnce-transaction-invoice-reconciliation-control--enabled-->vnce-compliance-evidence-register","vnce-law-cybersecurity-116-passed--enabled-->vnce-cybersecurity-audit-control","vnce-cybersecurity-audit-control--enabled-->vnce-compliance-evidence-register"],"predictiveValue":0.91,"domains":["systems","economy","technology"]},{"id":"pattern--platforms-become-governance-infrastructure","pattern":"Platforms Become Governance Infrastructure","pattern_vi":"Nền tảng trở thành hạ tầng quản trị","description":"As regulation assigns identity, information, complaint, retention, and violation-handling duties to platforms, product architecture becomes part of the enforcement surface rather than a neutral transaction layer.","description_vi":"Khi quy định giao cho nền tảng trách nhiệm về định danh, thông tin, khiếu nại, lưu giữ và xử lý vi phạm, kiến trúc sản phẩm trở thành một phần của bề mặt thực thi thay vì chỉ là lớp giao dịch trung lập.","instances":["vnce-law-ecommerce-122-passed--enabled-->vnce-decree-ecommerce-248-effective","vnce-decree-ecommerce-248-effective--enabled-->vnce-platform-seller-governance-control","vnce-decree-ecommerce-248-effective--enabled-->vnce-livestream-identity-content-control"],"predictiveValue":0.87,"domains":["technology","systems","economy"]},{"id":"pattern--compliance-debt-is-data-debt","pattern":"Compliance Debt Is Often Data Debt","pattern_vi":"Nợ tuân thủ thường là nợ dữ liệu","description":"When orders, payments, invoices, returns, identities, and logs cannot be reconciled, the organization cannot reliably prove compliance. Standardized data and exception workflows reduce both operational and legal uncertainty.","description_vi":"Khi đơn hàng, thanh toán, hóa đơn, hoàn trả, danh tính và nhật ký không thể đối soát, tổ chức không thể chứng minh tuân thủ một cách đáng tin cậy. Dữ liệu chuẩn hóa và quy trình ngoại lệ làm giảm cả bất định vận hành lẫn pháp lý.","instances":["vnce-household-tax-einvoice-rules-effective--accelerated-->vnce-transaction-invoice-reconciliation-control","vnce-decree-einvoice-254-effective--enabled-->vnce-transaction-invoice-reconciliation-control","vnce-transaction-invoice-reconciliation-control--enabled-->vnce-compliance-evidence-register"],"predictiveValue":0.89,"domains":["systems","economy","technology"]}]