@oj-bin/oj-x86_64-pc-windows-msvc 0.1.13 → 0.1.16

package/devkit/README.md

@@ -13,12 +13,13 @@
 ## 安装（业务项目）
 
 ```sh
-# agent 用：拷入项目的 Claude Code skill 目录
+# npm 安装（v0.1.13 起）：postinstall 把对应平台的 oj / plugins / devkit/ 落盘 <项目根>/bin/
+npm i @oj-bin/oj
 mkdir -p .claude/skills/oj-api-dev
-cp devkit/SKILL.md devkit/api-manual.md .claude/skills/oj-api-dev/
+cp bin/devkit/SKILL.md bin/devkit/api-manual.md .claude/skills/oj-api-dev/   # agent 用
+cp bin/devkit/global.d.ts .                                                  # 类型提示
 
-# 类型提示：拷进项目源码根（与 src/ 平级即可）
-cp devkit/global.d.ts .
+# 或从发行包解包后取 devkit/，路径同上
 ```
 
 安装后 agent 里说"用 oj-api-dev 开发 xxx 模块"，或 Claude Code 里 `/oj-api-dev` 触发。

package/devkit/SKILL.md

@@ -23,7 +23,7 @@ description: 在 oj (only-js) 框架业务项目中开发 API 模块时使用—
 ## 红线（不可违反）
 
 - **SQL 注入**：动态标识符（表名/列名）**只**来自 `db.table()` 查询构造器（白名单），
-  绝不来自 JS 字符串拼接；值**只**通过绑定参数（`db.query("... where id = ?", [id])`）。
+  绝不来自 JS 字符串拼接；值**只**通过绑定参数（`db.query("... where id = ?", [id])` 或构造器的 `value`）。
 - **方法名**：DELETE 的方法名是 `del`，不是 `delete`（`get/post/put/del/patch/head/options`）。
 - **信封**：业务响应只经 `json.ok(data)` / `json.fail(code, msg, data?)` 写回，
   HTTP 状态 = `code`（0→200）；标准协议端点（对外契约 JSON）可用 `json.raw(data)`
@@ -73,6 +73,10 @@ description: 在 oj (only-js) 框架业务项目中开发 API 模块时使用—
 | WS 路由 404（文件明明在） | 文件名必须小写 `ws.ts`/`ws.js`——`WS.ts` 无效（v0.1.5 约定） |
 | （v0.1.9 已消除）旧帧循环的 const 重复声明 | 新契约为生命周期钩子：模块每 Worker 预载一次——无需处理；可变跨帧状态放 `sess.state`（模块作用域只是只读缓存），见 api-manual §ws.ts |
 | WS 帧内 `bus.publish` 自己也收到 | 自回声语义：fan-out 不排除本连接——按字段客户端过滤或发布到别的 topic |
+| 查询被拦截 / 启动报 `tenant_id` 相关错（v0.1.15 sql_guard） | `sql_guard: "deny"` 拦截租户条件不匹配的查询（`"warn"` 只告警）：跨租户操作（对账/报表）走 `await db.asSystem()`（请求级 + 审计日志）；共享表须 schema.yaml `tenant: false` **且** config `tenant.shared_allow` 列出，双声明才豁免 |
+| 裸 SQL 被 deny 拦「遗漏 tenant_id」 | `db.query`/`db.exec` 的字面检查（best-effort）要求 SQL 显式带租户条件——优先改走 `db.table()` 构造器（自动注入），系统身份走 `db.asSystem()` |
+| WS 二进制帧 `http.body` 是 null | 设计如此（不做 UTF-8 有损转换）——取字节用 `await http.bodyBytes()`（v0.1.16） |
+| 回显二进制协议帧型变成 Text | `ws.send` 帧型由参数类型决定：Uint8Array → Binary(0x2)，string → Text(0x1)——别把字节 decode 成 string 再发 |
 
 ## 手册
 

package/devkit/api-manual.md

@@ -103,6 +103,8 @@ release（跑预构建 `.js`，不转译）；否则 dev（服务 `.ts` 源码
 **终端默认静默（`server.console_log` 缺省 false）**——启动时会打一行日志路径的提示，
 随后一切输出只落盘；需要终端同时输出时加 `--console-log` 或配 `server.console_log: true`。
 **例外**：启动失败的最终退出原因总是直写终端（console 关闭也不例外），便于立即调整。
+**后台运行**：加 `--daemon` 脱离终端（unix setsid / windows DETACHED_PROCESS），stdio 重定向
+空设备，父进程打印子 pid 后退出；日志照常落 `server.logs_dir`，停机用 `kill <pid>`。
 **准入门（三态，无静默默认）**：`--api-path` 与静态站点（`server.app_path` / `--app-path`）
 至少显式指定其一，否则退出；两者皆指定 → 都必须存在；仅指定其一 → 只启用对应功能。
 
@@ -292,7 +294,8 @@ runtime 会泵 event loop 直到所有 Promise 落定后再写回响应（摘自
 ```ts
 function get(): void {
   const id = Number(http.param("id", 0));
-  db.query("select id, name, role from account where id = ?", [id])
+  db.table("account").select(["id", "name", "role"]).where({ field: "id", op: "eq", value: id })
+    .all()
     .then((r) => json.ok(r))
     .catch((e) => json.fail(500, String(e)));
 }
@@ -323,6 +326,19 @@ const b = http.body as { name?: string };
 if (!b.name) { json.fail(400, "name required"); return; }
 ```
 
+**二进制帧（v0.1.16，仅 WS `message` 钩子）**：客户端发 Binary 帧时 `http.body` 为
+`null`（不做 UTF-8 有损转换），原始字节一律走 `http.bodyBytes()`（文本帧同样可用，
+返回原始帧字节）：
+
+```ts
+// ws.ts：二进制回显（可运行案例 sample/src/echo-bin/ws.ts）
+export default {
+  async message() {
+    ws.send(await http.bodyBytes()); // Uint8Array 原字节 → Binary 帧（0x2）
+  },
+};
+```
+
 ### 路由：目录镜像与 `.route` 参数路由
 
 URL = `{base}/{module}/{...path}/{feature}/` → `<dir>/{module}/{...path}/{feature}/api.ts|js`。
@@ -335,7 +351,8 @@ handler 函数挂 `.route` 属性即**替换**目录镜像路由，支持 matchi
 function detail(): void {
   const id = Number(http.param("id", 0));
   if (!(id > 0)) { json.fail(400, "id required"); return; }
-  db.query("select id, name, role from account where id = ?", [id])
+  db.table("account").select(["id", "name", "role"]).where({ field: "id", op: "eq", value: id })
+    .all()
     .then((r) => (r.length ? json.ok(r[0]) : json.fail(404, "no such account")))
     .catch((e) => json.fail(500, String(e)));
 }
@@ -547,7 +564,8 @@ json.header("X-Request-Id", "abc");
 | `http.method` | `string` | 请求方法（`GET`/`POST`/…） |
 | `http.query` | `Record<string, string>` | query 参数对象（form-urlencoded 解码：`+`→空格、`%XX`） |
 | `http.headers` | `Record<string, string>` | 请求头对象 |
-| `http.body` | `any` | 请求体（解析规则见第 4 章） |
+| `http.body` | `any` | 请求体（解析规则见第 4 章）；WS Binary 帧时为 `null` |
+| `http.bodyBytes` | `bodyBytes(): Promise<Uint8Array>` | 原始请求体字节（WS 帧场景 v0.1.16 起；HTTP 大体亦可经此取字节） |
 | `http.params` | `Record<string, string>` | 路径参数对象（已 percent-decode；目录镜像路由下恒空） |
 | `http.param` | `param(name: string, def?: unknown): any` | **路径参数优先，query 兜底**，均缺失返回 `def` 原值 |
 | `http.tenantId` | `string \| null` | 租户 id（`tenant.enable` 时从租户头提取；未启用为 `null`） |
@@ -568,7 +586,8 @@ const page = http.param("page", 1);       // 无路径参数 → query 兜底
 | `db.exec` | `exec(sql: string, params?: unknown[]): Promise<number>` | 参数化执行 → 受影响行数 |
 | `db.table` | `table(name: string): QueryBuilder` | 安全查询构造器（标识符白名单 + 参数化值） |
 | `db.tx` | `tx(fn: (tx: DBInstance) => unknown): Promise<unknown>` | 事务（语义见下） |
-| `DB(name)` | `(name: string) => DBInstance \| undefined` | 命名库实例；四方法与 `db` 同签名 |
+| `db.asSystem` | `asSystem(): DBInstance` | 本请求以系统身份绕过租户防护（v0.1.15，仅 tenant.sql_guard 活跃时有意义；请求级生效 + 审计日志，业务 handler 禁用） |
+| `DB(name)` | `(name: string) => DBInstance \| undefined` | 命名库实例；全部方法与 `db` 同签名 |
 
 **查询构造器**（流式、结构化；SQL 由服务端按库方言生成）：
 
@@ -583,14 +602,109 @@ const rows = await db.table("account")
   .all();                                          // → Promise<Json[]>
 ```
 
-- `WhereCond`：`{ field: string; op?: string; value?: unknown; and?; or? }`。
-  v0.2 服务端支持的操作符：`eq / ne / gt / gte / lt / lte / in（值须数组）/
-  like / isnull`；未知操作符直接报错；`and`/`or` 嵌套字段 v0.2 未展开（多 where 即 AND）。
+- `WhereCond`：`{ field: string; op?: string; value?: unknown }`。
+  操作符：`eq / ne / gt / gte / lt / lte / in（值须数组）/ like / isnull`；未知操作符直接报错。
 - `OrderByItem`：`{ field: string; dir?: "asc" | "desc" | null }`。
-- 表名/列名经 SchemaRegistry 白名单校验（启动内省所得）——未知表/列报错；
-  排序列另有可排序白名单。`limit` 缺省 100、硬上限 1000。
+- **红线**：标识符（表/列/别名）只来自 SchemaRegistry 白名单（启动内省所得），值一律经绑定参数——
+  SQL 注入面为零；未知表/列报错，排序列另有可排序白名单。`limit` 缺省 100、硬上限 1000。
 - 构造器自动按库方言出 SQL（sqlite/mysql/postgres），业务无需手写方言差异。
 
+**条件树（where 嵌套）**：
+
+```ts
+await db.table("account").where({
+  and: [
+    { field: "age", op: "gte", value: 18 },
+    { or: [
+      { field: "role", op: "eq", value: "admin" },
+      { field: "tag", op: "isnull" },
+    ]},
+  ],
+}).all();            // → WHERE age >= ? AND (role = ? OR tag IS NULL)
+```
+
+- 树节点四形：叶子 `{field, op, value?}`、`{and:[...]}`、`{or:[...]}`、`{not:{...}}`。
+- 深度上限 8、叶子数上限 64（超限报 `condition tree too deep/large`）；空 `and`/`or` 组直接拒绝。
+
+**条件对象（JS 侧组合/复用）**：`db.leaf(field, op, value)` / `db.and(...)` / `db.or(...)` /
+`db.not(c)` 工厂产出条件对象；`where`/`having` 同时接受条件对象或普通 JSON 树。
+
+```ts
+const scope = db.and(
+  db.leaf("tenant_id", "eq", tid),
+  db.leaf("deleted", "eq", 0),
+);
+const rows = await db.table("account").where(scope).all();
+if (!scope.has("tenant_id")) throw new Error("tenant scope required");  // 多租户守卫
+```
+
+- 条件对象**不可变**：`c.and(x)` / `c.or(x)` / `c.not()` 返回新对象，不改 `c`。
+- `.tree()` 取纯 JSON 树；`.fields()` 取去重字段名列表；`.has(f)` 判断是否涉及某字段。
+
+**join 联表**：
+
+```ts
+await db.table("account")
+  .join("user", [{ left: "account.user_id", right: "user.id" }], "left")
+  .select(["account.id", "user.name"])
+  .all();
+```
+
+- `on` 只支持列对列等值（`{left, right}` 数组，非空）；`kind` 省略为 `inner`，可选 `left`。
+- 列可写 `"表.列"`（表 ∈ 基表 ∪ join 表）或裸列名（**只解析基表**——歧义天然拒绝，联表查询建议全限定）。
+- join 表同样过租户/所有权守卫；**自 join 不支持**（无表别名）。
+
+**聚合 / groupBy / having / distinct**：
+
+```ts
+await db.table("order")
+  .select([
+    "user_id",
+    { fn: "sum", field: "amount", as: "total" },
+    { fn: "count" },                       // count(*) 可省 field
+  ])
+  .groupBy(["user_id"])
+  .having({ field: "total", op: "gt", value: 100 })
+  .all();
+```
+
+- 聚合列 `{ fn: "count"|"sum"|"avg"|"min"|"max", field?: string, as?: string }`；
+  别名形状 `^[A-Za-z_][A-Za-z0-9_]*$`（违例报 `illegal alias`）。
+- `having` 白名单列优先，未命中按 select 聚合别名展开（`unknown column '...' in having`）——
+  PG 不允许 HAVING 引用输出别名，展开消灭方言分叉；orderBy 不支持聚合别名（仍走列白名单）。
+- `.distinct()` 去重（仅 select）。
+
+**DML：insert / update / delete**（`.run()` 终执行，返回受影响行数；`.all()` 仅 select）：
+
+```ts
+await db.table("user").insert({ name: "neo", age: 1 }).run();        // 单行
+await db.table("user").insert([{ name: "a" }, { name: "b" }]).run(); // 多行（键集须一致）
+await db.table("user").update({ age: 2 }).where({ field: "id", op: "eq", value: 1 }).run();
+await db.table("user").delete().where({ field: "id", op: "in", value: [1, 2] }).run();
+```
+
+- **红线**：`update`/`delete` 必须带 where 且叶子数 ≥ 1。JS 链层早抛（`update requires where`），
+  op 侧同样强制——`fromJSON` 可完全绕过 JS 链层，故动词×字段矩阵为 **op 侧权威校验**。
+- 动词×字段矩阵：`insert` 拒 `where/orderBy/limit/offset/joins/distinct/groupBy/having`，
+  `values` 非空且多行键集一致；`update`/`delete` 拒 `joins/distinct/groupBy/having/limit/offset`，
+  `update` 的 `sets` 非空；`select` 拒 `values/sets`。违例报 `<verb> does not accept <field>`。
+- insert 键 / update 键均过白名单（`unknown column '<k>' in insert values / update sets`）。
+- `db.tx` 内构造的 DML 自动走事务同连接（见下）。
+
+**toSQL / toJSON / fromJSON**：
+
+```ts
+db.table("user").select(["id"]).where({ field: "age", op: "gt", value: 18 }).toSQL();
+// → { sql: "SELECT ... WHERE \"age\" > $1", params: [18] }  （占位符按目标库方言；不执行）
+
+const snap = db.table("user").select(["id"]).where(scope).toJSON(); // 纯 JSON 快照，可直接改
+snap.limit = 50;
+await db.fromJSON(snap).all();   // 复原后继续链/执行；tx 回调对象上同样有 fromJSON
+```
+
+- 快照里的 `db` 字段只是**创建时的 JS 可见名**；`fromJSON` 复原的实例绑定**复原方的 bound db**
+  （快照可跨模块传递而不泄漏源模块的库绑定）；tx 内执行自动走事务同连接。
+
 **事务 `db.tx`**：
 
 ```ts
@@ -602,12 +716,86 @@ await db.tx(async (tx) => {
 ```
 
 - 回调正常返回 → **提交**；throw / reject → **回滚**并把原错误抛给 handler。
-- `tx` 与 `db` 的 `query / exec / table` **同签名**——事务内自动走同一连接，
-  无需改写其余代码。
+- `tx` 与 `db` 的 `query / exec / table / fromJSON` 及条件工厂（`leaf/and/or/not`）
+  **同签名**——事务内自动走同一连接，无需改写其余代码（回调对象不含 `tx`——嵌套事务被拒）。
 - 每请求**至多一个**活跃事务：嵌套 `db.tx` 报错 `transaction already active`；
   事务未完结时访问其它库报错（先结当前事务）。
 - handler 忘记 `await` 或中途崩溃：请求结束时未完结事务**自动回滚**（服务端打 warn 日志）。
 
+**子查询 / exists**（where 与 having 通用）：
+
+```ts
+await db.table("user")
+  .select(["id", "name"])
+  .where({ field: "id", op: "in", subquery: db.table("order")
+      .select(["user_id"]).where({ field: "amount", op: "gt", value: 100 }) })
+  .all();          // → WHERE id IN (SELECT user_id FROM order WHERE amount > ?)
+
+await db.table("user").select(["id"]).where({
+  exists: db.table("order").select(["user_id"])
+    .where({ field: "amount", op: "gt", value: 100 }),
+}).all();          // → WHERE EXISTS (SELECT user_id FROM order WHERE amount > ?)（非关联）
+```
+
+- 叶子操作符 `in/eq/ne/gt/gte/lt/lte` 接受 `subquery`（builder 或纯 JSON 请求）：
+  `in` 渲染 `IN (SELECT ...)`，其余渲染标量子查询 `col = (SELECT ...)`。
+- `value` 与 `subquery` 互斥（`value and subquery are mutually exclusive`）；
+  `isnull`/`like` 不接受子查询。`{ exists: <子查询> }` 节点不得携带其他键。
+- 子查询同样过租户/所有权守卫；嵌套约束见下。
+
+**union / union all**（排序/分页仅顶层）：
+
+```ts
+await db.table("vip").select(["id", "name"])
+  .union(db.table("black").select(["id", "name"]))            // 缺省 distinct
+  .union(db.table("tmp").select(["id", "name"]), "all")       // union all
+  .orderBy([{ field: "id", dir: "asc" }])
+  .all();
+```
+
+- 主查询与成员都须**显式列**（`union requires explicit columns`）且列数一致；
+  成员禁 order_by/limit/offset（`union member does not accept order_by/limit/offset`）。
+- 成员同样过租户守卫；`intersect`/`except` 不做。
+
+**case 列 / 窗口函数列**（select 列的对象形）：
+
+```ts
+await db.table("account").select([
+  "id",
+  { case: { when: [
+      { cond: { field: "balance", op: "lt", value: 0 }, then: "debt" },
+      { cond: { field: "vip", op: "eq", value: 1 }, then: "vip" },
+    ], else: "normal" }, as: "level" },          // → CASE WHEN ... THEN ? ... ELSE ? END
+  { window: { fn: "row_number", partition_by: ["user_id"],
+      order_by: [{ field: "amount", dir: "desc" }] }, as: "rn" },
+]).all();
+```
+
+- case：searched case；`cond` 与 where 条件树同形；`then`/`else` **只允许 JSON 值**（绑定参数，
+  不接受列名/标识符）；`as` 必填过别名形状。
+- window：`fn ∈ row_number / rank / dense_rank`；`partition_by` 列过白名单；frame 不做；`as` 必填。
+
+**with CTE**（非递归，仅顶层）：
+
+```ts
+await db.table("rich")
+  .with("rich", ["user_id", "total"], db.table("order")
+    .select(["user_id", { fn: "sum", field: "amount", as: "total" }]).groupBy(["user_id"]))
+  .select(["user_id", "total"])
+  .all();          // → WITH rich(user_id, total) AS (SELECT ...) SELECT ... FROM rich
+```
+
+- `.with(name, columns, query)`：`name`/`columns` 过别名形状（`illegal alias '...'`）；
+  `columns` 必填非空（`cte needs non-empty columns`）——**声明的输出列即后续解析的白名单**。
+- 基表/join 表名命中 CTE 名时跳过 registry 表校验（CTE 无 owner）；CTE 查询递归过守卫。
+
+**嵌套通用约束**（子查询 / exists / union 成员 / CTE 一致）：
+
+- 层数上限 4（`<site>: nested select too deep`，site 为出错位置）；嵌套必须 select
+  （`<site>: nested select must be select`）；嵌套禁 with/unions
+  （`<site>: nested select does not accept with/unions (v1)`）。
+- 隐式默认 `limit 100` 只作用于**顶层**查询；嵌套/成员不隐式截断（显式 limit 一律生效）。
+
 ### kv / redis —— KV 存储
 
 | API | 签名 | 说明 |
@@ -666,7 +854,7 @@ Content-Type，s3 302 跳 presigned URL）。key 按 `/` 分段白名单校验
 
 | API | 签名 | 说明 |
 |---|---|---|
-| `bus.publish` | `publish(topic: string, data?: unknown): Promise<number>` | 广播 JSON 帧 `{"topic":…,"data":…}` 给订阅该 topic 的**全部 WS 会话**，返回接收方数（无订阅返回 0） |
+| `bus.publish` | `publish(topic: string, data?: unknown \| Uint8Array): Promise<number>` | 广播给订阅该 topic 的**全部 WS 会话**，返回接收方数（无订阅返回 0）：JSON 数据 → Text 帧 `{"topic":…,"data":…}`；Uint8Array/ArrayBuffer → **Binary 帧原字节**（不包信封，v0.1.16 起，wire 约定见第 13 章） |
 | `bus.subscribe` | `subscribe(topic: string): Promise<void>` | 当前 WS 会话订阅 topic（**HTTP 路径调用报错**——订阅对象是连接本身） |
 | `bus.kind` | `kind(): Promise<string>` | 活跃 broker 类型：`"local"` / `"kafka"` / `"rabbitmq"`（异步 op，判等须 `await`） |
 
@@ -734,7 +922,7 @@ if (r.ok) {
 
 | API | 签名 | 说明 |
 |---|---|---|
-| `ws.send` | `send(data: string): void` | 向当前连接发一帧（HTTP 路径下 no-op） |
+| `ws.send` | `send(data: string \| Uint8Array): void` | 向当前连接发一帧：string → Text 帧（0x1），Uint8Array → Binary 帧（0x2，v0.1.16 起）；HTTP 路径下 no-op |
 | `ws.close` | `close(): void` | 结束当前连接 |
 | `sess.id` | `number`（只读） | 当前连接 id（路由内自 1 递增） |
 | `sess.state` | 读写属性 | 连接会话状态（Rust 会话表持久，按连接隔离）；**必须可 JSON 序列化**——函数等不可序列化值静默丢失 |
@@ -884,11 +1072,13 @@ globalThis.APP_ENV = "prod";
 
 | 客户端 | 生产面 | 消费面（**仅任务上下文**） |
 |---|---|---|
-| `Kafka(name)` | `send(topic, {value, key?, headers?})` | `poll(topics, {max?, timeoutMs?})` → `{messages}`；`commit(m)`（按 m.offset+1 提交） |
-| `RabbitMQ(name)` | `publish(exchange, routingKey, value, {headers?})` | `poll(queues, {max?, timeoutMs?})`（= 循环 basic.get）；`ack(m)`；`nack(m, requeue?)` |
+| `Kafka(name)` | `send(topic, {value, key?, headers?})`；`value` 传 Uint8Array/ArrayBuffer → **base64 编码进 `value_b64`**，record 载荷 = 原始字节（v0.1.16） | `poll(topics, {max?, timeoutMs?})` → `{messages}`；`commit(m)`（按 m.offset+1 提交） |
+| `RabbitMQ(name)` | `publish(exchange, routingKey, value, {headers?})`（`value` 二进制语义同 Kafka） | `poll(queues, {max?, timeoutMs?})`（= 循环 basic.get）；`ack(m)`；`nack(m, requeue?)` |
 | 两者 | `kind()` / `metadata()` | —— |
 
-消息形状（`OjMqMessage`）：`{topic, partition?, offset?, key?, value, headers?, ts?}`。
+消息形状（`OjMqMessage`）：`{topic, partition?, offset?, key?, value, value_b64?, headers?, ts?}`。
+载荷为 UTF-8 时 `value` 是解析后的 JSON（解析失败为字符串）；**非 UTF-8 载荷** → `value` 为
+`null`、`value_b64` 为 base64 字符串（v0.1.16 起，自行 `atob`/解码还原字节）。
 
 **消费门禁（评审 M2）**：`poll/commit/ack/nack` 只在长任务上下文可用——HTTP/WS
 handler 里调用直接报错（消费会话归属任务实例，实例级单 poller，第二个并发 poll
@@ -1036,6 +1226,8 @@ export default {
 tenant:
   enable: true
   header_key: "X-TENANT-ID"   # 默认即此名
+  sql_guard: deny             # 多租户 SQL 防护：false（默认，不改写 SQL）| "warn" | "deny"/true
+  shared_allow: [dict]        # 共享表白名单（schema.yaml 里 tenant: false 的表须在此列出才生效）
 ```
 
 启用后所有 `{base}` 请求必须带该 header（缺失/空 → 400），值注入 `http.tenantId`
@@ -1043,8 +1235,15 @@ tenant:
 `/*`」形式，但 tenant 匹配是**严格一层**通配（更深路径需显式列出，如 `/idp/.well-known/*`；
 oj-auth 插件实现为多层前缀），豁免缺失 400——给 OIDC 302 跳转腿用（浏览器带不了自定义头）；
 已带的头仍照常注入。
-**框架不自动改写 SQL**——行级过滤归业务（自行在查询里带
-tenant 条件）。启用期间测试请求也必须带头（第 9 章两约束）。
+
+**`sql_guard`（v0.1.15 起）**：开 `enable` 只是识别租户头；`sql_guard` 才自动防护 SQL——
+`db.table()` 构造器查询自动注入 `tenant_id` 条件（join 进 ON、子查询递归）、insert 强制
+当前租户、update/delete 自动收窄、sets 显式改 tenant_id 拒绝；裸 SQL 查「完全遗漏 tenant_id」
+warn 告警 / deny 拦截。guard 非 Off 时 schema.yaml 声明的表必须有 `tenant_id` 列
+（共享表 `tenant: false` + `shared_allow` 双声明豁免），server 启动 / `oj build` /
+`oj migrate` 三处校验。跨租户操作（对账、运营报表）走 `db.asSystem()`（请求级、打审计日志）。
+新人向白话文档见 `docs/tenant-guide.md`；**注意租户头目前是客户端自报，防伪造需 JWT claims
+绑定（规划见设计文档 §7）**。
 
 ### auth_demo 走读（sample）
 
@@ -1118,6 +1317,7 @@ describe("user account", () => {
 |---|---|
 | `client.get/post/put/del/patch/head/options(path, opts?)` | 进程内派发；`opts = { headers?, body? }`，返回 `ClientResp { status, headers, body, upgrade }`；`path` 相对 base（如 `"/user/account"`） |
 | `client.login(username, password, headers?)` | POST 业务路由 `/auth/login`（sample/src/auth/）→ 返回 `access_token`（失败抛错；`headers` 透传，如租户头） |
+| `client.ws(path)`（v0.1.16） | WS 帧测试面：`send(string\|Uint8Array)` / `next(ms?) → {binary,data}\|{closed:true}\|null` / `close()`；首次使用惰性起 127.0.0.1:0 本地服务（真实路由 + 帧循环）。用例见 `sample/tests/ws-bin.test.ts` |
 | `describe(name, fn)` / `it(name, fn)` / `beforeEach(fn)` | vitest 风格子集 |
 | `expect(actual)` | `.toBe / .toEqual / .toBeTruthy / .toBeFalsy / .toContain` |
 | `finish()` | 标记会话结束 |
@@ -1141,7 +1341,7 @@ cd sample && npm run test:unit    # 统一入口（等价 cd unit && npm ci && n
 
 结构：`mocks/oj-globals.ts` 提供 `installGlobals(opts?)`（把 `db/json/http/bus/log`
 换成可控桩，返回响应捕获 `{code,msg,data}`；`lastPublished()` 取 `bus.publish` 记录，
-`lastSqlCalls()` 取 `db.query/exec` 的 SQL 与绑定参数——可断言 handler 走了哪个分支）；
+`lastSqlCalls()` 取 `db` 发出的 SQL（query/exec/构造器）与绑定参数——可断言 handler 走了哪个分支）；
 `invoke.ts` 提供 `invoke(handler, method, opts?)`（装桩 → 调 handler → flush 微任务 →
 返回 `{ ...capture, published }`）；`*.spec.ts` 直接 import 真实 `../src/.../api` 的 handler。
 
@@ -1297,7 +1497,9 @@ V8 runtime 按 Worker 数常驻；单帧超时只断该连接（毒化 Worker
 ### tenant / auth
 
 字段与语义见第 8 章（tenant 默认关闭、header 默认 `X-TENANT-ID`、`anonymous_paths`
-跳转腿豁免；auth 的 `jwt_secret`（空串启动 fail-fast，生产必改）、`signing_method`
+跳转腿豁免；v0.1.15 起增 `sql_guard`（false|"warn"|"deny"）与 `shared_allow` 共享表
+白名单——语义与建表要求见第 8 章与 `docs/tenant-guide.md`；auth 的 `jwt_secret`（空串
+启动 fail-fast，生产必改）、`signing_method`
 （HS256|HS384|HS512，默认 HS256）、`access_token_duration`（默认 60s）、
 `refresh_token_duration`（默认 720h）、`anonymous_paths`——无 `user_table` 配置，
 用户表是业务约定）。
@@ -1449,6 +1651,24 @@ vendored `node_modules/`（不打进 tgz）→ `./oj server -c config.yaml --api
 启动时把模块清单 + 路由表写入日志，可据此核对发布是否完整（终端默认静默：
 `tail -f logs/server-*.log`，或启动时加 `--console-log`）。
 
+### npm 分发（@oj-bin/*，v0.1.13）
+
+除 tarball 外还有 npm 渠道，最终布局与解包一致：
+
+```bash
+npm i @oj-bin/oj     # 主包；optionalDependencies 自动带平台子包 @oj-bin/oj-<triple>
+```
+
+- `postinstall` 按当前平台取子包内容落盘 `<项目根>/bin/`（`oj` / `plugins/<triple>/` /
+  `devkit/` / `lib`），原子替换（rename，可覆盖运行中的旧二进制）；**不支持全局安装**
+  （没有确定的项目根，装全局直接报错）。被 `--omit=optional` / `ignore-scripts` 排除
+  时 fail-fast 并提示。
+- 发布由仓库 `scripts/npm-publish.sh` 单一来源：装配 + 幂等（`npm view` 已发布即
+  skip）+ 门禁（tag 与 Cargo.toml 版本一致性、同 `(os,cpu)` 撞车、包根布局断言）+
+  发布后置信断言（os/cpu/tarball 文件清单）；`DRY_RUN=1` 只装配断言不发布，本地自检用。
+- npm 包不可撤回：CI 上 release 草稿期不发 npm（人工核对 release 后幂等补发），
+  版本一经发布不可复用——改代码必须递增版本。
+
 ## 12. 运维要点
 
 > 何时读我：服务跑起来之后的证书/日志/排障/升级。
@@ -1563,7 +1783,7 @@ RUST_LOG=oj=info ./oj server -c config.yaml --api-path dist
 
 - **动态标识符（表名/列名）只来自 `db.table()` 查询构造器**（SchemaRegistry 白名单），
   **绝不来自 JS 字符串**。
-- **值只通过绑定参数传递**（`db.query("... where id = ?", [id])`），**绝不字符串拼接**。
+- **值只通过绑定参数传递**（`db.query("... where id = ?", [id])` 或构造器的 `value`），**绝不字符串拼接**。
 
 ```ts
 // 正确：标识符走构造器，值走绑定参数
@@ -1603,6 +1823,8 @@ await db.query("select id from account where id = " + id, []);   // 禁止
 | release 下 WS URL 含版本段 | `…/news-0.1.0/ws`；客户端发现 WS 地址时注意拼版本段 |
 | `db.tx` 每请求至多一个；嵌套报错 | 合并事务回调 |
 | `bus` 缺省进程内，跨实例不互通 | 需要跨实例广播配 `broker.kind` |
+| bus 二进制 wire 约定（v0.1.16） | JSON → record/信封文本帧；字节 → record payload = 原始字节、投递为 Binary 帧。消费侧启发式：UTF-8 且为含 `topic`+`data` 的 JSON 对象才按文本信封，否则按二进制透传——**恰为该形状 JSON 的二进制载荷会以文本帧投递**（无害，自辨） |
+| WS 二进制状态（Yjs awareness 等）不进 `sess.state` | `sess.state` 必须可 JSON 序列化；二进制状态走 base64 字符串存 `sess.state`/kv，或分片放 kv |
 | `WhereCond.and/or` 嵌套未展开 | 多个 `where()` 即 AND；复杂条件用 `db.query` 参数化 SQL |
 | schema 回滚无自动机制 | 迁移只前向；破坏性变更前备份，反向变更写新 seq 迁移 |
 | fixtures/ 不进 release 产物 | 演示数据走 fixtures（oj test / oj fixture）；参考数据走模块 seed.sql |
@@ -1623,6 +1845,9 @@ await db.query("select id from account where id = " + id, []);   // 禁止
 - `redis.default` 配置即真连且 fail-fast——CI/离线环境注释掉该段即用内存 KV。
 - 每请求至多一个 `db.tx`；漏 await 会在请求结束时自动回滚并打 warn。
 - `beforeEach` 是单一全局钩子，跨 `describe` 被覆盖——多 describe 文件在各 `it` 内联准备。
+- WS Binary 帧 `http.body` 是 `null` 不是乱码——取字节用 `http.bodyBytes()`（v0.1.16）。
+- `ws.send` 的帧型由**参数类型**决定：string → Text、Uint8Array → Binary——回显二进制协议时
+  别把字节先 decode 成 string 再发（帧型就变了）。
 - `ext_boot.js` 里别写库/发广播/打外部接口——执行次数是「模块数 + `pool_size` + WS Worker 数
   （每路由 `ws.workers_per_route`）」，副作用按此放大；boot 只做全局装配。
 - `ext_boot.js` 顶层 `await` 忘了 `export {};` → 看起来莫名的 SyntaxError（CJS 启发式误判）。

package/devkit/global.d.ts

@@ -66,6 +66,8 @@ interface HttpApi {
   query: Record<string, string>;
   headers: Record<string, string>;
   body: any;
+  // WS Binary 帧时 body 为 null；原始帧字节走 bodyBytes()（v0.1.16，文本帧亦可用）。
+  bodyBytes(): Promise<Uint8Array>;
   // 取路由参数或 query 参数：路径参数优先，query 兜底，均缺失返回 def 原值。
   param(name: string, def?: unknown): any;
   // 租户 id（tenant 启用时从租户头提取；未启用为 null）。
@@ -113,8 +115,9 @@ interface KVApi {
 }
 
 // ws.* ：WebSocket 生命周期钩子内的主动发送/关闭控制（HTTP 路径 no-op）。
+// send 帧型由参数类型决定：string → Text 帧(0x1)；Uint8Array → Binary 帧(0x2)（v0.1.16）。
 interface WSApi {
-  send(data: string): void;
+  send(data: string | Uint8Array): void;
   close(): void;
 }
 
@@ -134,6 +137,7 @@ interface BlobApi {
 // bus.* ：主题广播。publish 广播给订阅 topic 的全部 WS 会话，返回接收方数；
 // subscribe 仅 WS 会话内可用（HTTP 路径报错）；kind 报告活跃 broker 类型。
 interface BusApi {
+  // data 为 Uint8Array/ArrayBuffer → Binary 帧原字节（不包信封，v0.1.16）；其余 → JSON 信封 Text 帧。
   publish(topic: string, data?: unknown): Promise<number>;
   subscribe(topic: string): Promise<void>;
   kind(): Promise<string>;
@@ -239,7 +243,19 @@ declare global {
     headers?: Record<string, string>;
     body?: string;
   }
+  // WS 帧测试面（v0.1.16）：path 形如 "/echo-bin/ws"（相对 base）。
+  interface TestWsFrame {
+    binary: boolean;
+    data: string | Uint8Array;
+  }
+  interface TestWs {
+    send(data: string | Uint8Array): Promise<void>;
+    // 下一帧：{binary, data}；对端关闭 {closed: true}；超时无帧 null（默认 1000ms）。
+    next(ms?: number): Promise<TestWsFrame | { closed: true } | null>;
+    close(): Promise<void>;
+  }
   interface Client {
+    ws(path: string): TestWs;
     get(path: string, opts?: ClientOptions): Promise<ClientResp>;
     post(path: string, opts?: ClientOptions): Promise<ClientResp>;
     put(path: string, opts?: ClientOptions): Promise<ClientResp>;
@@ -295,6 +311,9 @@ interface OjMqMessage {
   offset?: number;
   key?: string;
   value: any;
+  // 非 UTF-8 载荷时 value 为 null，value_b64 为 base64 字符串（v0.1.16）；生产侧传
+  // Uint8Array 亦编码进 value_b64（record 载荷 = 原始字节）。
+  value_b64?: string;
   headers?: Record<string, string>;
   ts?: number;
   delivery_tag?: number; // rabbit 专属：ack/nack 载荷原样回传

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oj-bin/oj-x86_64-pc-windows-msvc",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "description": "Prebuilt oj binary + plugins for x86_64-pc-windows-msvc. Optional platform package of @oj-bin/oj; do not install directly.",
   "homepage": "https://github.com/everpan/only-js",
   "repository": { "type": "git", "url": "git+https://github.com/everpan/only-js.git" },