@nmvuong92/fluxe 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# fluxe
+
+Khung fullstack **polyglot** dựa trên triết lý **RCA — Resolved Cell Architecture**:
+*logic chỉ phụ thuộc HỢP ĐỒNG; mọi quyết định vận hành (ngôn ngữ, render, transport,
+backend, scale) là **kết quả được GIẢI** bởi engine, không viết tay.*
+
+> Đổi backend từ TS → Go → Rust, đổi render static ↔ island, gộp nhiều backend trong một
+> app per-cell — tất cả chỉ sửa `app/profiles.ts`, **cell & frontend không đổi một dòng**.
+
+## Cài & dùng (npm)
+
+```bash
+npm i @nmvuong92/fluxe react react-dom zod
+```
+
+```ts
+import { defineCell, withInput, makeServer, createMemoryBackend } from "@nmvuong92/fluxe";
+import { useQuery, useMutation, Link, Nav, ThemeToggle } from "@nmvuong92/fluxe/react";
+import { rpc } from "@nmvuong92/fluxe/client";
+```
+
+| Import | Nội dung |
+|--------|----------|
+| `@nmvuong92/fluxe` | engine: defineCell, makeServer, resolver, auth, validate, backends, seo, broker, ratelimit, codegen… |
+| `@nmvuong92/fluxe/react` | useQuery, useMutation, Link, Nav, ThemeToggle, useTheme, DebugBar |
+| `@nmvuong92/fluxe/client` | rpc, RpcError, mutate, revalidate, subscribe |
+| `@nmvuong92/fluxe/jobs` · `/sqlite` | queue/dead-letter · SQLite backend (cần `--experimental-sqlite`) |
+
+## Chạy nhanh
+
+```bash
+npm install
+npm run fx -- build        # resolve + prerender + bundle (1 schema → TS/Go/Rust qua fx gen)
+npm run fx -- dev          # http://localhost:5180
+npm run test:all           # typecheck + 107 unit + 28 integration — TẤT CẢ XANH
+```
+
+`fx`: `gen · resolve · prerender · build · dev · test · jobs`.
+
+## Cấu trúc — ranh giới DEV vs ENGINE
+
+```
+app/        ← DEV sở hữu (sửa thoải mái) — Contract Plane
+  cells/        trang/feature (route + loader + view + action/head/layout/guard)
+  layouts/      layout dùng chung (nested)
+  profiles.ts   CHỌN backend per môi trường + per-cell (memory/go/rust)
+  contract.ts   schema → codegen TS/Go/Rust
+  env.ts        env có kiểu, validate fail-fast lúc boot
+  native/       service Go/Rust CỦA DEV (backend/host/hot/actor)
+
+src/        ← ENGINE (không đụng) — Resolution Plane
+  core/         resolver · router · errors · auth · validate · codegen · layouts ·
+                broker · presence · jobs · ratelimit · observe · panel · seo · cli · ...
+  server_factory.ts   runtime ráp cell + giải manifest
+```
+
+**Quy tắc:** "backend nào đang chạy" do `app/profiles.ts` (config) quyết, **không** do vị trí
+folder. Engine không bao giờ import ngược vào `app/`.
+
+## Tính năng (tất cả TDD + chạy thật)
+
+- **Render** — static (0 JS) · island hydrate · SPA nav (Inertia) · static-prerender (Go phục vụ thẳng) · API mode `?json=1`
+- **Routing** — động `[param]` → `ctx.input` · **nested layouts** · SEO (head/canonical/OG/JSON-LD per cell, `/sitemap.xml`, `/robots.txt`)
+- **Bảo mật (đầy đủ)** — input validation (Zod) · auth password **scrypt** · **RBAC** · **CSRF** double-submit · **rate-limit** token-bucket · error handling không-leak + structured
+- **Data** — backend polyglot per-cell · DB **SQLite thật** + adapter **Postgres** · **codegen contract** 1 schema → TS/Go/Rust
+- **Mutations DX** — `RpcError` có cấu trúc · `mutate()` optimistic + rollback · lỗi validation field-level
+- **Realtime (Trục 4g)** — **SSE channel** + pub/sub broker · live-update on action · **presence** (multi-tab) · **actor-Go** (BEAM-style: room=goroutine, supervisor restart)
+- **Async** — **job queue bền** (SQLite, retry → dead-letter)
+- **Observability** — request log + dashboard `/_fluxe` (RCA Resolution + Recent requests)
+- **Config** — env có kiểu, fail-fast lúc boot
+- **DX** — `fx` CLI · mock `Backend` test cực dễ · typecheck gate
+
+## Polyglot 4 tầng (Go/Rust thật, đã chạy)
+
+| Tầng | Ngôn ngữ | Demo |
+|------|----------|------|
+| **Backend** (Todo CRUD) | Go · Rust | `./run-native.sh` |
+| **Host/edge** (proxy + static) | Go | `./run-host.sh` |
+| **Hot compute** (search) | Rust | `./run-hot.sh` |
+| **Actor/realtime** (room+supervisor) | Go | `./run-actor.sh` |
+
+Engine viết bằng: **TS** (Resolver + SSR/cell) · **Go** (host/actor) · **Rust** (hot compute) —
+mỗi tầng đúng ngôn ngữ tối ưu, đúng §6d của [idea.md](idea.md).
+
+## Triết lý
+
+Toàn bộ định hướng, các trục chiến lược, tenets và nguyên lý RCA: xem **[idea.md](idea.md)**.
+Spec + plan: `docs/superpowers/`.

package/lib/backends/http.d.ts

@@ -0,0 +1,2 @@
+import type { Backend } from "./types";
+export declare function createHttpBackend(name: string, baseUrl: string): Backend;

package/lib/backends/http.js

@@ -0,0 +1,32 @@
+/* Backend #3/#4: gọi một service THẬT qua HTTP (Go hoặc Rust).
+ * Cùng interface Backend → cell + frontend KHÔNG đổi một dòng.
+ * Service chỉ cần tôn trọng "hợp đồng" 3 endpoint:
+ *   GET  /todos                 → Todo[]
+ *   POST /todos {title}         → Todo
+ *   POST /todos/{id}/toggle     → Todo[]
+ */
+export function createHttpBackend(name, baseUrl) {
+    const base = baseUrl.replace(/\/$/, "");
+    async function j(path, init) {
+        const r = await fetch(base + path, init);
+        if (!r.ok)
+            throw new Error(`${name} backend ${path} → HTTP ${r.status}`);
+        return (await r.json());
+    }
+    return {
+        name,
+        listTodos() {
+            return j("/todos");
+        },
+        addTodo(title) {
+            return j("/todos", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ title }),
+            });
+        },
+        toggleTodo(id) {
+            return j(`/todos/${encodeURIComponent(id)}/toggle`, { method: "POST" });
+        },
+    };
+}

package/lib/backends/memory.d.ts

@@ -0,0 +1,2 @@
+import type { Backend } from "./types";
+export declare function createMemoryBackend(): Backend;

package/lib/backends/memory.js

@@ -0,0 +1,21 @@
+/* Backend #1: in-memory. Đại diện cho "TS thuần". */
+export function createMemoryBackend() {
+    let todos = [
+        { id: "1", title: "Học kiến trúc fullstack", done: true },
+        { id: "2", title: "Dựng PoC switch backend", done: false },
+    ];
+    let seq = 3;
+    return {
+        name: "memory",
+        async listTodos() { return todos; },
+        async addTodo(title) {
+            const t = { id: String(seq++), title, done: false };
+            todos = [...todos, t];
+            return t;
+        },
+        async toggleTodo(id) {
+            todos = todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t));
+            return todos;
+        },
+    };
+}

package/lib/backends/postgres.d.ts

@@ -0,0 +1,7 @@
+import type { Backend } from "./types";
+export interface PgClientLike {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: any[];
+    }>;
+}
+export declare function createPostgresBackend(client: PgClientLike): Backend;

package/lib/backends/postgres.js

@@ -0,0 +1,28 @@
+// Nhận sẵn client (đã connect) để testable + không buộc import pg ở repo này.
+export function createPostgresBackend(client) {
+    const toTodo = (r) => ({ id: String(r.id), title: r.title, done: !!r.done });
+    return {
+        name: "postgres",
+        async listTodos() {
+            const { rows } = await client.query("SELECT * FROM todos ORDER BY id");
+            return rows.map(toTodo);
+        },
+        async addTodo(title) {
+            const { rows } = await client.query("INSERT INTO todos (title, done) VALUES ($1, false) RETURNING *", [title]);
+            return toTodo(rows[0]);
+        },
+        async toggleTodo(id) {
+            await client.query("UPDATE todos SET done = NOT done WHERE id = $1", [id]);
+            const { rows } = await client.query("SELECT * FROM todos ORDER BY id");
+            return rows.map(toTodo);
+        },
+    };
+}
+/* Cách dùng thật (khi có pg + server):
+ *   import { Client } from "pg";
+ *   const client = new Client(process.env.DATABASE_URL);
+ *   await client.connect();
+ *   await client.query(`CREATE TABLE IF NOT EXISTS todos (
+ *     id SERIAL PRIMARY KEY, title TEXT NOT NULL, done BOOLEAN NOT NULL DEFAULT false)`);
+ *   const backend = createPostgresBackend(client);
+ */

package/lib/backends/sqlite.d.ts

@@ -0,0 +1,2 @@
+import type { Backend } from "./types";
+export declare function createSqliteBackend(path?: string): Backend;

package/lib/backends/sqlite.js

@@ -0,0 +1,27 @@
+import { DatabaseSync } from "node:sqlite";
+/* Backend DB THẬT — SQLite qua node:sqlite (built-in, 0 dep, persist ra file).
+ * Chạy cần cờ: node --experimental-sqlite … Cùng interface Backend → switch như mọi backend. */
+export function createSqliteBackend(path = ":memory:") {
+    const db = new DatabaseSync(path);
+    db.exec(`CREATE TABLE IF NOT EXISTS todos (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    done INTEGER NOT NULL DEFAULT 0
+  )`);
+    const toTodo = (r) => ({ id: String(r.id), title: r.title, done: !!r.done });
+    const all = () => db.prepare("SELECT * FROM todos ORDER BY id").all().map(toTodo);
+    return {
+        name: "sqlite",
+        async listTodos() {
+            return all();
+        },
+        async addTodo(title) {
+            const info = db.prepare("INSERT INTO todos (title) VALUES (?)").run(title);
+            return toTodo(db.prepare("SELECT * FROM todos WHERE id = ?").get(info.lastInsertRowid));
+        },
+        async toggleTodo(id) {
+            db.prepare("UPDATE todos SET done = 1 - done WHERE id = ?").run(Number(id));
+            return all();
+        },
+    };
+}

package/lib/backends/types.d.ts

@@ -0,0 +1,11 @@
+export interface Todo {
+    id: string;
+    title: string;
+    done: boolean;
+}
+export interface Backend {
+    name: string;
+    listTodos(): Promise<Todo[]>;
+    addTodo(title: string): Promise<Todo>;
+    toggleTodo(id: string): Promise<Todo[]>;
+}

package/lib/backends/types.js

@@ -0,0 +1,7 @@
+/* ============================================================
+ * Backend Adapter — interface chuẩn để SWITCH backend.
+ * loader/action chỉ biết tới interface này, không biết
+ * dữ liệu đến từ memory, Postgres, hay một service Go từ xa.
+ * Đổi backend = thay một implementation, frontend & cell không đổi.
+ * ============================================================ */
+export {};

package/lib/core/auth.d.ts

@@ -0,0 +1,12 @@
+export interface Session {
+    user: string;
+    roles?: string[];
+    [k: string]: unknown;
+}
+export declare function hasRole(session: Session | null, role: string): boolean;
+export declare function signSession(payload: Session, secret: string): string;
+export declare function verifySession(token: string | undefined, secret: string): Session | null;
+export declare function hashPassword(password: string): string;
+export declare function verifyPassword(password: string, stored: string): boolean;
+export declare function newCsrfToken(): string;
+export declare function parseCookie(header: string | undefined): Record<string, string>;

package/lib/core/auth.js

@@ -0,0 +1,54 @@
+import { createHmac, timingSafeEqual, scryptSync, randomBytes } from "node:crypto";
+export function hasRole(session, role) {
+    return !!session?.roles?.includes(role);
+}
+export function signSession(payload, secret) {
+    const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+    const sig = createHmac("sha256", secret).update(body).digest("base64url");
+    return `${body}.${sig}`;
+}
+export function verifySession(token, secret) {
+    if (!token)
+        return null;
+    const [body, sig] = token.split(".");
+    if (!body || !sig)
+        return null;
+    const expected = createHmac("sha256", secret).update(body).digest("base64url");
+    const a = Buffer.from(sig), b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return null;
+    try {
+        return JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/* Password hashing — scrypt (built-in, memory-hard). Format: scrypt$salt$hash.
+ * (Production: Argon2id qua `npm i argon2`; scrypt là chuẩn built-in, an toàn.) */
+export function hashPassword(password) {
+    const salt = randomBytes(16);
+    const hash = scryptSync(password, salt, 32);
+    return `scrypt$${salt.toString("hex")}$${hash.toString("hex")}`;
+}
+export function verifyPassword(password, stored) {
+    const [algo, saltHex, hashHex] = stored.split("$");
+    if (algo !== "scrypt" || !saltHex || !hashHex)
+        return false;
+    const hash = scryptSync(password, Buffer.from(saltHex, "hex"), 32);
+    const expected = Buffer.from(hashHex, "hex");
+    return hash.length === expected.length && timingSafeEqual(hash, expected);
+}
+/* CSRF token (double-submit cookie): cookie csrf + header x-csrf-token phải khớp. */
+export function newCsrfToken() {
+    return randomBytes(24).toString("hex");
+}
+export function parseCookie(header) {
+    const out = {};
+    for (const part of (header ?? "").split(";")) {
+        const i = part.indexOf("=");
+        if (i > 0)
+            out[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim());
+    }
+    return out;
+}

package/lib/core/broker.d.ts

@@ -0,0 +1,7 @@
+export type Subscriber = (data: unknown) => void;
+export interface Broker {
+    subscribe(topic: string, fn: Subscriber): () => void;
+    publish(topic: string, data: unknown): void;
+    count(topic: string): number;
+}
+export declare function createBroker(): Broker;

package/lib/core/broker.js

@@ -0,0 +1,27 @@
+/* Broker pub/sub in-memory — nền của realtime channel (Trục 4g), bản 1-node.
+ * Bản distributed: thay bằng NATS/Redis fan-out (cùng interface). Bản stateful:
+ * actor-Go (app/native/actor-go). Đây là lõi đơn giản nhất, dependency-free. */
+export function createBroker() {
+    const subs = new Map();
+    return {
+        subscribe(topic, fn) {
+            let set = subs.get(topic);
+            if (!set) {
+                set = new Set();
+                subs.set(topic, set);
+            }
+            set.add(fn);
+            return () => {
+                set.delete(fn);
+                if (set.size === 0)
+                    subs.delete(topic);
+            };
+        },
+        publish(topic, data) {
+            subs.get(topic)?.forEach((fn) => fn(data));
+        },
+        count(topic) {
+            return subs.get(topic)?.size ?? 0;
+        },
+    };
+}

package/lib/core/chaos.d.ts

@@ -0,0 +1,5 @@
+export interface Chaos {
+    delayMs: number;
+    failRate: number;
+}
+export declare function parseChaos(header: string | undefined): Chaos;

package/lib/core/chaos.js

@@ -0,0 +1,11 @@
+export function parseChaos(header) {
+    const out = { delayMs: 0, failRate: 0 };
+    for (const part of (header ?? "").split(";")) {
+        const [k, v] = part.split("=");
+        if (k?.trim() === "delay")
+            out.delayMs = Math.max(0, Number(v) || 0);
+        if (k?.trim() === "fail")
+            out.failRate = Math.min(1, Math.max(0, Number(v) || 0));
+    }
+    return out;
+}

package/lib/core/cli.d.ts

@@ -0,0 +1,6 @@
+export interface Command {
+    desc: string;
+    shell: (args: string[]) => string;
+}
+export declare const COMMANDS: Record<string, Command>;
+export declare function renderUsage(): string;

package/lib/core/cli.js

@@ -0,0 +1,54 @@
+/* fx CLI — registry lệnh thuần (testable). bin/fx.ts dispatch + spawn. */
+const SYNC = "tsx scripts/sync.ts"; // auto-discovery: quét app/cells/* → app/app.ts
+const ESBUILD = "esbuild src/client.tsx --bundle --format=esm --outfile=dist/client.js --jsx=automatic --loader:.tsx=tsx";
+const p = (a) => a[0] ?? "dev"; // profile mặc định
+export const COMMANDS = {
+    init: {
+        desc: "Scaffold app/ mới (env, profiles, layout, cell home) — chỉ tạo file còn thiếu",
+        shell: () => `tsx scripts/init.ts`,
+    },
+    new: {
+        desc: "Tạo cell mới: fx new <id> [--island]  (auto-discovery tự đăng ký)",
+        shell: (a) => `tsx scripts/new-cell.ts ${a.join(" ")}`,
+    },
+    sync: {
+        desc: "Auto-discovery: quét app/cells/* → app/app.ts (dev/resolve tự gọi)",
+        shell: () => SYNC,
+    },
+    gen: {
+        desc: "Codegen contract → types TS/Go/Rust (.fluxe/gen)",
+        shell: () => `tsx scripts/codegen.ts`,
+    },
+    resolve: {
+        desc: "Sinh .fluxe/resolution.json từ profile",
+        shell: (a) => `${SYNC} && tsx scripts/resolve.ts ${p(a)}`,
+    },
+    jobs: {
+        desc: "Demo job queue (enqueue + worker drain + dead-letter)",
+        shell: () => `node --experimental-sqlite --import tsx scripts/jobs-demo.ts`,
+    },
+    bench: {
+        desc: "Benchmark RPS/QPS + latency p50/p99 + RAM/CPU",
+        shell: (a) => `${SYNC} && tsx scripts/resolve.ts dev && npm run --silent build:client && tsx scripts/bench.ts ${a.join(" ")}`,
+    },
+    prerender: {
+        desc: "Prerender cell static → .fluxe/static.json",
+        shell: (a) => `${SYNC} && tsx scripts/prerender.ts ${p(a)}`,
+    },
+    build: {
+        desc: "Build đầy đủ: sync + resolve + prerender + client bundle",
+        shell: (a) => `${SYNC} && tsx scripts/resolve.ts ${p(a)} && tsx scripts/prerender.ts ${p(a)} && ${ESBUILD}`,
+    },
+    dev: {
+        desc: "Sync + resolve + build client + chạy server",
+        shell: (a) => `${SYNC} && tsx scripts/resolve.ts ${p(a)} && ${ESBUILD} && tsx src/server.tsx`,
+    },
+    test: {
+        desc: "Sync + typecheck + unit + integration",
+        shell: () => `${SYNC} && tsc --noEmit && node --experimental-sqlite --import tsx --test '{src,app}/**/*.test.ts' && tsx src/selftest2.ts`,
+    },
+};
+export function renderUsage() {
+    const lines = Object.entries(COMMANDS).map(([n, c]) => `  fx ${n.padEnd(10)} ${c.desc}`);
+    return `fluxe CLI\n\nLệnh:\n${lines.join("\n")}\n`;
+}

package/lib/core/client.d.ts

@@ -0,0 +1,33 @@
+export declare class RpcError extends Error {
+    code: string;
+    status: number;
+    details?: unknown;
+    constructor(code: string, message: string, status: number, details?: unknown);
+}
+export declare function parseRpcError(status: number, body: string): RpcError;
+export declare const setChaos: (v: string) => void;
+export declare const getChaos: () => string;
+export declare const setDevBackend: (v: string) => void;
+export declare const getDevBackend: () => string;
+export interface RpcMeta {
+    resolution?: string;
+    serverMs?: number;
+    clientMs?: number;
+}
+export declare const lastRpcMeta: () => RpcMeta;
+export declare function rpc<T = any>(cell: string, action: string, input: unknown): Promise<T>;
+export declare function mutate<T>(opts: {
+    optimistic?: () => void;
+    run: () => Promise<T>;
+    rollback?: () => void;
+}): Promise<T>;
+export declare function fetchPageProps(url: string): Promise<{
+    cell: string;
+    data: unknown;
+    layout?: string;
+}>;
+export declare function revalidate(): Promise<{
+    cell: string;
+    data: unknown;
+}>;
+export declare function subscribe(topic: string, onData: (data: any) => void): () => void;

package/lib/core/client.js

@@ -0,0 +1,108 @@
+/* ============================================================
+ * Client runtime — Inertia-style + mutations DX.
+ * - rpc(): gọi action, ném RpcError CÓ CẤU TRÚC (code/message/details) khi lỗi.
+ * - mutate(): optimistic + rollback khi lỗi.
+ * - revalidate(): refetch props trang hiện tại sau khi mutate.
+ * ============================================================ */
+export class RpcError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status, details) {
+        super(message);
+        this.name = "RpcError";
+        this.code = code;
+        this.status = status;
+        this.details = details;
+    }
+}
+// Pure: dựng RpcError từ status + body trả về (server trả {error:{code,message,details}}).
+export function parseRpcError(status, body) {
+    try {
+        const e = JSON.parse(body)?.error;
+        if (e?.code)
+            return new RpcError(e.code, e.message ?? "Lỗi", status, e.details);
+    }
+    catch {
+        /* không phải JSON */
+    }
+    return new RpcError("http", `HTTP ${status}`, status);
+}
+function cookie(name) {
+    if (typeof document === "undefined")
+        return "";
+    const m = document.cookie.match(new RegExp("(?:^|; )" + name + "=([^;]*)"));
+    return m ? decodeURIComponent(m[1]) : "";
+}
+/* DevTools config (chỉ ảnh hưởng dev): chaos injection + live backend swap. DebugBar set. */
+let _chaos = ""; // vd "delay=600;fail=0.3"
+let _devBackend = ""; // vd "go" | "rust" | "memory"
+export const setChaos = (v) => { _chaos = v; };
+export const getChaos = () => _chaos;
+export const setDevBackend = (v) => { _devBackend = v; };
+export const getDevBackend = () => _devBackend;
+let _lastMeta = {};
+export const lastRpcMeta = () => _lastMeta;
+export async function rpc(cell, action, input) {
+    const t0 = typeof performance !== "undefined" ? performance.now() : 0;
+    const headers = { "content-type": "application/json", "x-csrf-token": cookie("csrf") };
+    if (_chaos)
+        headers["x-fluxe-chaos"] = _chaos; // #1 chaos
+    if (_devBackend)
+        headers["x-fluxe-backend"] = _devBackend; // #5 live swap
+    let res;
+    try {
+        res = await fetch(`/__action/${cell}/${action}`, { method: "POST", headers, body: JSON.stringify(input) });
+    }
+    catch {
+        _lastMeta = {};
+        throw new RpcError("network", "Mất kết nối máy chủ", 0);
+    }
+    const hget = (k) => res.headers?.get?.(k) ?? null;
+    _lastMeta = {
+        resolution: hget("x-fluxe-resolution") ?? undefined,
+        serverMs: Number(hget("x-fluxe-server-ms")) || undefined,
+        clientMs: Math.round((typeof performance !== "undefined" ? performance.now() : 0) - t0),
+    };
+    if (!res.ok)
+        throw parseRpcError(res.status, await res.text());
+    return res.json();
+}
+// Optimistic update: chạy optimistic() ngay, run() ngầm; lỗi → rollback() + ném lại.
+export async function mutate(opts) {
+    opts.optimistic?.();
+    try {
+        return await opts.run();
+    }
+    catch (e) {
+        opts.rollback?.();
+        throw e;
+    }
+}
+/* SPA navigation kiểu Inertia: lấy props JSON rồi để runtime render lại */
+export async function fetchPageProps(url) {
+    const res = await fetch(url, { headers: { "x-fluxe": "1" } });
+    if (!res.ok)
+        throw new Error(`fetchPageProps ${url} → ${res.status}`);
+    const ct = res.headers.get("content-type") ?? "";
+    if (!ct.includes("application/json"))
+        throw new Error("không phải trang cell"); // file tĩnh → hard nav
+    return res.json();
+}
+/* Revalidate: refetch props trang hiện tại (gọi sau mutate để đồng bộ data). */
+export async function revalidate() {
+    return fetchPageProps(location.pathname + location.search);
+}
+/* Realtime: subscribe topic qua SSE. Trả hàm hủy. (Trục 4g) */
+export function subscribe(topic, onData) {
+    if (typeof EventSource === "undefined")
+        return () => { };
+    const es = new EventSource(`/__sse/${encodeURIComponent(topic)}`);
+    es.onmessage = (e) => {
+        try {
+            onData(JSON.parse(e.data));
+        }
+        catch { /* ignore */ }
+    };
+    return () => es.close();
+}

package/lib/core/codegen.d.ts

@@ -0,0 +1,7 @@
+export type FieldType = "string" | "bool" | "int";
+export interface Schema {
+    types: Record<string, Record<string, FieldType>>;
+}
+export declare function genTS(s: Schema): string;
+export declare function genGo(s: Schema, pkg?: string): string;
+export declare function genRust(s: Schema): string;

package/lib/core/codegen.js

@@ -0,0 +1,28 @@
+/* Codegen contract polyglot — MỘT schema → types TS + Go + Rust (chữ ký RCA:
+ * type-safe xuyên ngôn ngữ). Thuần (string-in/string-out), dễ test. */
+const pascal = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+const TS = { string: "string", bool: "boolean", int: "number" };
+const GO = { string: "string", bool: "bool", int: "int" };
+const RS = { string: "String", bool: "bool", int: "i64" };
+export function genTS(s) {
+    return Object.entries(s.types)
+        .map(([name, fields]) => `export interface ${name} {\n` +
+        Object.entries(fields).map(([f, t]) => `  ${f}: ${TS[t]};`).join("\n") +
+        `\n}`)
+        .join("\n\n") + "\n";
+}
+export function genGo(s, pkg = "contract") {
+    return `package ${pkg}\n\n` +
+        Object.entries(s.types)
+            .map(([name, fields]) => `type ${name} struct {\n` +
+            Object.entries(fields).map(([f, t]) => `\t${pascal(f)} ${GO[t]} \`json:"${f}"\``).join("\n") +
+            `\n}`)
+            .join("\n\n") + "\n";
+}
+export function genRust(s) {
+    return Object.entries(s.types)
+        .map(([name, fields]) => `#[derive(Clone, Debug)]\npub struct ${name} {\n` +
+        Object.entries(fields).map(([f, t]) => `    pub ${f}: ${RS[t]},`).join("\n") +
+        `\n}`)
+        .join("\n\n") + "\n";
+}

package/lib/core/engine.d.ts

@@ -0,0 +1,28 @@
+import type { ComponentType } from "react";
+import type { Backend } from "../backends/types";
+import type { HeadMeta } from "./seo";
+import type { Session } from "./auth";
+export interface Ctx<I> {
+    input: I;
+    backend: Backend;
+    session?: Session | null;
+}
+export type Loader<I, O> = (ctx: Ctx<I>) => Promise<O>;
+export type Action<I, O> = (ctx: Ctx<I>) => Promise<O>;
+export type Hydration = "static" | "island";
+export interface CellDef<I, O> {
+    id: string;
+    route: string;
+    hydration?: Hydration;
+    loader: Loader<I, O>;
+    view: ComponentType<{
+        data: O;
+    }>;
+    actions?: Record<string, Action<any, any>>;
+    head?: (data: O) => HeadMeta;
+    layout?: string;
+    requireAuth?: boolean;
+    requireRole?: string;
+    cache?: boolean;
+}
+export declare function defineCell<I, O>(c: CellDef<I, O>): CellDef<I, O>;

package/lib/core/engine.js

@@ -0,0 +1 @@
+export function defineCell(c) { return c; }

package/lib/core/env.d.ts

@@ -0,0 +1,2 @@
+import type { ZodType } from "zod";
+export declare function loadEnv<T>(schema: ZodType<T>, source?: Record<string, string | undefined>): T;

package/lib/core/env.js

@@ -0,0 +1,10 @@
+/* Config/env có kiểu (4k) — validate process.env theo schema, FAIL-FAST lúc boot
+ * (thiếu/sai biến → chặn ngay, không chết giữa prod). Coerce string→number/bool qua Zod. */
+export function loadEnv(schema, source = process.env) {
+    const r = schema.safeParse(source);
+    if (!r.success) {
+        const issues = r.error.issues.map((i) => `  ${i.path.join(".") || "(env)"}: ${i.message}`).join("\n");
+        throw new Error(`Cấu hình env không hợp lệ (fail-fast lúc boot):\n${issues}`);
+    }
+    return r.data;
+}