weifuwu 0.94.0 → 0.95.0

package/dist/level0/ai/types.ts

@@ -0,0 +1,164 @@
+/**
+ * weifuwu AI 协议共享类型 —— 与 docs/server.md 规范一一对应
+ *
+ * 纯类型，零运行时成本。两端同源：
+ *   - 后端：从 weifuwu 主包导入（src/index.ts re-export）
+ *   - 前端：从 weifuwu/client/vdom 导入（src/level6/client/vdom/index.ts re-export）
+ *
+ * 修改本文件 = 修改协议，需同步更新 docs/server.md。
+ */
+
+// ── 事件（下行 SSE，event: wf:*）────────────────────────
+
+export interface WfMessageStart {
+  id: string
+}
+
+export interface WfToken {
+  /** 增量文本，前端直接 append */
+  text: string
+}
+
+export interface WfUsage {
+  prompt_tokens: number
+  completion_tokens: number
+  total_tokens?: number
+}
+
+export interface WfDone {
+  content: string
+  usage?: WfUsage
+  /** thinking 模式的推理过程（reasoning_content），收尾时一次性下发（v1 不进流式） */
+  reasoning?: string
+}
+
+export type WfErrorCode =
+  | 'auth_failed'
+  | 'rate_limited'
+  | 'context_length'
+  | 'timeout'
+  | 'provider_error'
+  | 'invalid_request'
+  | 'unsupported'
+  | 'aborted'
+
+export interface WfError {
+  code: WfErrorCode
+  message: string
+}
+
+export interface WfToolCall {
+  /** 工具调用 id（provider 给 / 后端生成），聚合完成后才发 */
+  id: string
+  /** 工具名（app 定义的业务语义，协议不解释） */
+  name: string
+  /** 完整参数 */
+  args: Record<string, unknown>
+}
+
+export interface WfToolResult {
+  id: string
+  ok: boolean
+  output?: unknown
+  /** ok:false 时：rejected（人工拒绝）/ timeout（审批超时）/ tool_error / app 自定义 */
+  error?: { code: string; message: string }
+}
+
+export interface WfToolProgress {
+  toolCallId: string
+  step: number
+  total: number
+  message?: string
+  status: 'running' | 'error' | 'done'
+}
+
+export interface WfStep {
+  type: 'llm' | 'tool'
+  content?: string
+  toolCallId?: string
+  name?: string
+  /** 工具调用参数（JSON 字符串——前端工具卡片展示） */
+  args?: string
+}
+
+export interface WfApprovalRequest {
+  id: string
+  toolCallId: string
+  name: string
+  args: Record<string, unknown>
+  reason?: string
+  /** 审批超时；到期按 rejected 处理（error.code: 'timeout'） */
+  expiresAt?: number
+}
+
+export type WfApprovalDecision = 'approved' | 'rejected' | 'modified'
+
+/** 上行 POST 载荷（非 SSE 事件） */
+export interface WfApprovalResponse {
+  id: string
+  decision: WfApprovalDecision
+  /** 仅 modified：按修改后的参数执行 */
+  modifiedArgs?: Record<string, unknown>
+  /** 进 agent 上下文 */
+  note?: string
+}
+
+/** 所有框架事件联合类型（前端 switch 收窄用） */
+export type WfStreamEvent =
+  | { name: 'wf:message_start'; data: WfMessageStart }
+  | { name: 'wf:token'; data: WfToken }
+  | { name: 'wf:usage'; data: WfUsage }
+  | { name: 'wf:done'; data: WfDone }
+  | { name: 'wf:error'; data: WfError }
+  | { name: 'wf:tool_call'; data: WfToolCall }
+  | { name: 'wf:tool_result'; data: WfToolResult }
+  | { name: 'wf:tool_progress'; data: WfToolProgress }
+  | { name: 'wf:step'; data: WfStep }
+  | { name: 'wf:approval_request'; data: WfApprovalRequest }
+
+// ── 对话消息（回传 provider 的形状，与 wf: 事件无关）────
+
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
+
+export interface ChatMessage {
+  role: MessageRole
+  content: string
+  /** DeepSeek thinking mode：前一轮的 reasoning_content 必须回传 */
+  reasoning_content?: string
+  tool_call_id?: string
+  tool_calls?: ToolCall[]
+  name?: string
+}
+
+export interface ToolCall {
+  id: string
+  type: 'function'
+  function: {
+    name: string
+    arguments: string
+  }
+}
+
+export interface ToolDefinition {
+  type: 'function'
+  function: {
+    name: string
+    description: string
+    parameters: Record<string, unknown>
+  }
+}
+
+export interface ChatParams {
+  model?: string
+  /** BYOK：per-call 覆盖全局 apiKey（租户自带模型 Key——商业化 G4） */
+  apiKey?: string
+  /** BYOK：per-call 覆盖全局端点（OpenAI 兼容任意服务商） */
+  baseUrl?: string
+  messages: ChatMessage[]
+  temperature?: number
+  max_tokens?: number
+  stream?: boolean
+  tools?: ToolDefinition[]
+  tool_choice?: 'auto' | 'none' | 'required'
+  stop?: string[]
+}

package/dist/level0/db/contracts.d.ts

@@ -0,0 +1,98 @@
+/**
+ * weifuwu/db — 自研数据库引擎契约层（接口与实现分离）
+ *
+ * 三个接口族：消费方只依赖接口类型，自研引擎（src/db/postgres|redis 的 class）实现：
+ *
+ *   PoolConnection     通用连接（pg/redis 池中连接项：生命周期 + 健康）
+ *     ├─ PostgresPoolConnection  特化：参数化查询（PgConnection 实现）
+ *     └─ RedisPoolConnection     特化：命令执行（RedisClient 实现）
+ *   Redis（+Pipeline/Subscriber）  Redis 命令面（ctx.redis）——命令面封闭无 parser
+ *   DbAdapter / Orm               ORM AST 协议层（业务唯一数据入口——ctx.orm）
+ *
+ * 变更纪律（ 协议层）：改契约须 TDD 先行 + 真库验证（CS-04/CS-05）。
+ */
+import type { RespError } from './errors.ts';
+/**
+ * RESP 值（协议层数据面——实现/编解码见 db/redis/resp.ts）。
+ * 定义于契约层：消费方（ctx.redis/内存替身）不依赖线协议实现。
+ */
+export type RespValue = string | number | null | RespError | RespValue[] | Uint8Array;
+/**
+ * Redis 订阅者面（Pub/Sub 独立连接——messager 跨进程广播消费）。
+ * 结构化接口：RedisSubscriber（真库）与替身均满足。
+ */
+export interface RedisSubscriberFace {
+    connect(): Promise<void>;
+    subscribe(channel: string, fn: (channel: string, message: string) => void): Promise<void>;
+    psubscribe(pattern: string, fn: (channel: string, message: string) => void): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Pipeline 面（S5——SERVER-PERF-PLAN 波次 2）：批量命令单次网络往返发送。
+ * 结果按命令顺序；错误命令对应位置为 Error 实例，其余命令不受影响。
+ *
+ * 结构化接口：RedisPipeline（真库）与 MemoryPipeline（内存）均满足。
+ * 与并发 command() 同连接交错安全（连接层 FIFO pending——按序匹配）。
+ */
+export interface RedisPipelineFace {
+    set(key: string, value: string | number, ttl?: number): RedisPipelineFace;
+    get(key: string): RedisPipelineFace;
+    del(...keys: string[]): RedisPipelineFace;
+    incr(key: string): RedisPipelineFace;
+    expire(key: string, seconds: number): RedisPipelineFace;
+    ttl(key: string): RedisPipelineFace;
+    /** 任意命令透传（不加 keyPrefix——对齐 pool.command 语义） */
+    raw(name: string, ...args: (string | number)[]): RedisPipelineFace;
+    /** 一次往返执行所有命令；exec 后可复用（cmds 清空） */
+    exec(): Promise<RespValue[]>;
+}
+/**
+ * 连接池中的连接项（Postgres/Redis 通用）：生命周期 + 健康状态。
+ * 各库特化（PostgresPoolConnection / RedisPoolConnection）扩展执行能力。
+ */
+export interface PoolConnection {
+    /** 连接是否可用（就绪且未关闭） */
+    readonly connected: boolean;
+    /** 关闭连接（幂等——重复 close 安全） */
+    close(): Promise<void>;
+}
+export interface Row {
+    [col: string]: unknown;
+}
+/** 查询结果：行数组 + 影响行数（INSERT/UPDATE/DELETE/MERGE 的 CommandComplete tag） */
+export interface QueryResult<T = Row> extends Array<T> {
+    affectedRows?: number;
+}
+/** Postgres 连接（PoolConnection 特化：参数化查询） */
+export interface PostgresPoolConnection extends PoolConnection {
+    query(sql: string, params?: unknown[]): Promise<QueryResult>;
+}
+/** Redis 连接（PoolConnection 特化：命令执行） */
+export interface RedisPoolConnection extends PoolConnection {
+    command(name: string, ...args: (string | number)[]): Promise<RespValue>;
+}
+/**
+ * Redis 客户端（ctx.redis）：命令执行面（YAGNI 精简——消费方经 command 原始命令）。
+ * 便捷方法（get/set/…）在需要时按需加回接口（MemoryRedis 保留完整实现供测试）。
+ * 阻塞命令（BLPOP 等）在 commandTimeoutMs 超时时 resolve(null)（命令超时契约）。
+ */
+export interface Redis {
+    /**
+     * 创建独立连接（阻塞命令 / 专用通道——不占池连接，调用方负责 close）。
+     * 引擎实现（RedisPool）用自身配置派生，无需调用方传 url/选项。
+     */
+    createConnection(): Promise<RedisPoolConnection>;
+    /** 原始命令（RespValue 返回值——RESP 协议层；阻塞命令超时 resolve(null)） */
+    command(name: string, ...args: (string | number)[]): Promise<RespValue>;
+    /**
+     * 创建 pipeline（S5）：批量命令单次往返。池实现取轮询连接——
+     * 与并发命令交错安全（FIFO pending）。
+     */
+    pipeline(): Promise<RedisPipelineFace>;
+    /** 创建订阅者（Pub/Sub，独立连接——messager 跨进程广播用） */
+    createSubscriber(): RedisSubscriberFace;
+    /** 发布消息到频道（订阅者回调触发） */
+    publish(channel: string, message: string | number): Promise<number>;
+    /** 关闭（幂等） */
+    close(): Promise<void>;
+}

package/dist/level0/db/contracts.ts

@@ -0,0 +1,113 @@
+/**
+ * weifuwu/db — 自研数据库引擎契约层（接口与实现分离）
+ *
+ * 三个接口族：消费方只依赖接口类型，自研引擎（src/db/postgres|redis 的 class）实现：
+ *
+ *   PoolConnection     通用连接（pg/redis 池中连接项：生命周期 + 健康）
+ *     ├─ PostgresPoolConnection  特化：参数化查询（PgConnection 实现）
+ *     └─ RedisPoolConnection     特化：命令执行（RedisClient 实现）
+ *   Redis（+Pipeline/Subscriber）  Redis 命令面（ctx.redis）——命令面封闭无 parser
+ *   DbAdapter / Orm               ORM AST 协议层（业务唯一数据入口——ctx.orm）
+ *
+ * 变更纪律（ 协议层）：改契约须 TDD 先行 + 真库验证（CS-04/CS-05）。
+ */
+import type { RespError } from './errors.ts'
+
+/**
+ * RESP 值（协议层数据面——实现/编解码见 db/redis/resp.ts）。
+ * 定义于契约层：消费方（ctx.redis/内存替身）不依赖线协议实现。
+ */
+export type RespValue = string | number | null | RespError | RespValue[] | Uint8Array
+
+/**
+ * Redis 订阅者面（Pub/Sub 独立连接——messager 跨进程广播消费）。
+ * 结构化接口：RedisSubscriber（真库）与替身均满足。
+ */
+export interface RedisSubscriberFace {
+  connect(): Promise<void>
+  subscribe(channel: string, fn: (channel: string, message: string) => void): Promise<void>
+  psubscribe(pattern: string, fn: (channel: string, message: string) => void): Promise<void>
+  close(): Promise<void>
+}
+
+/**
+ * Pipeline 面（S5——SERVER-PERF-PLAN 波次 2）：批量命令单次网络往返发送。
+ * 结果按命令顺序；错误命令对应位置为 Error 实例，其余命令不受影响。
+ *
+ * 结构化接口：RedisPipeline（真库）与 MemoryPipeline（内存）均满足。
+ * 与并发 command() 同连接交错安全（连接层 FIFO pending——按序匹配）。
+ */
+export interface RedisPipelineFace {
+  set(key: string, value: string | number, ttl?: number): RedisPipelineFace
+  get(key: string): RedisPipelineFace
+  del(...keys: string[]): RedisPipelineFace
+  incr(key: string): RedisPipelineFace
+  expire(key: string, seconds: number): RedisPipelineFace
+  ttl(key: string): RedisPipelineFace
+  /** 任意命令透传（不加 keyPrefix——对齐 pool.command 语义） */
+  raw(name: string, ...args: (string | number)[]): RedisPipelineFace
+  /** 一次往返执行所有命令；exec 后可复用（cmds 清空） */
+  exec(): Promise<RespValue[]>
+}
+
+// ── 通用连接契约（pg/redis 共用） ─────────────────────────
+
+/**
+ * 连接池中的连接项（Postgres/Redis 通用）：生命周期 + 健康状态。
+ * 各库特化（PostgresPoolConnection / RedisPoolConnection）扩展执行能力。
+ */
+export interface PoolConnection {
+  /** 连接是否可用（就绪且未关闭） */
+  readonly connected: boolean
+  /** 关闭连接（幂等——重复 close 安全） */
+  close(): Promise<void>
+}
+
+// ── Postgres 契约 ──────────────────────────────────────────
+
+export interface Row {
+  [col: string]: unknown
+}
+
+/** 查询结果：行数组 + 影响行数（INSERT/UPDATE/DELETE/MERGE 的 CommandComplete tag） */
+export interface QueryResult<T = Row> extends Array<T> {
+  affectedRows?: number
+}
+
+/** Postgres 连接（PoolConnection 特化：参数化查询） */
+export interface PostgresPoolConnection extends PoolConnection {
+  query(sql: string, params?: unknown[]): Promise<QueryResult>
+}
+
+// ── Redis 契约 ─────────────────────────────────────────────
+
+/** Redis 连接（PoolConnection 特化：命令执行） */
+export interface RedisPoolConnection extends PoolConnection {
+  command(name: string, ...args: (string | number)[]): Promise<RespValue>
+}
+
+/**
+ * Redis 客户端（ctx.redis）：命令执行面（YAGNI 精简——消费方经 command 原始命令）。
+ * 便捷方法（get/set/…）在需要时按需加回接口（MemoryRedis 保留完整实现供测试）。
+ * 阻塞命令（BLPOP 等）在 commandTimeoutMs 超时时 resolve(null)（命令超时契约）。
+ */
+export interface Redis {
+  /**
+   * 创建独立连接（阻塞命令 / 专用通道——不占池连接，调用方负责 close）。
+   * 引擎实现（RedisPool）用自身配置派生，无需调用方传 url/选项。
+   */
+  createConnection(): Promise<RedisPoolConnection>
+  /** 原始命令（RespValue 返回值——RESP 协议层；阻塞命令超时 resolve(null)） */
+  command(name: string, ...args: (string | number)[]): Promise<RespValue>
+  /**
+   * 创建 pipeline（S5）：批量命令单次往返。池实现取轮询连接——
+   * 与并发命令交错安全（FIFO pending）。
+   */
+  pipeline(): Promise<RedisPipelineFace>
+  /** 创建订阅者（Pub/Sub，独立连接——messager 跨进程广播用） */
+  createSubscriber(): RedisSubscriberFace
+  /** 发布消息到频道（订阅者回调触发） */
+  publish(channel: string, message: string | number): Promise<number>
+  /** 关闭（幂等） */
+  close(): Promise<void>
+}

package/dist/level0/db/errors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * weifuwu/db — 统一错误模型
+ *
+ * 自研 postgres/redis 客户端共享的错误类型体系。
+ * 目标：错误语义统一 → 业务层 catch 可编程（按 kind/code 决策）。
+ *
+ *   kind:          connection | protocol | timeout | validation | retryable
+ *   code:          PG 错误码（如 23505 唯一冲突）或协议码
+ */
+export type DbErrorKind = 'connection' | 'protocol' | 'timeout' | 'validation' | 'retryable';
+export declare class DbError extends Error {
+    readonly kind: DbErrorKind;
+    readonly code?: string;
+    readonly cause?: unknown;
+    constructor(kind: DbErrorKind, message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+/** 明确不支持的协议能力（诚实裁剪）：COPY 二进制、逻辑复制、集群、哨兵等 */
+export declare class ProtocolError extends DbError {
+    constructor(feature: string, message?: string);
+}
+/** 连接失败（含重连尝试次数） */
+export declare class ConnectionError extends DbError {
+    readonly attempts: number;
+    constructor(message: string, attempts?: number, cause?: unknown);
+}
+/** 可重试错误：序列化失败/死锁（PG 40P01/40001）等 */
+export declare class RetryableError extends DbError {
+    constructor(message: string, code?: string, cause?: unknown);
+}
+/** 超时：statement_timeout / connect_timeout / idle 等 */
+export declare class TimeoutError extends DbError {
+    readonly operation: string;
+    readonly ms: number;
+    constructor(operation: string, ms: number);
+}
+/** 写前校验失败（schema 注册 → 脏数据拦截） */
+export declare class ValidationError extends DbError {
+    constructor(message: string);
+}
+/** 判断错误是否可安全重试（事务层用） */
+export declare function isRetryable(err: unknown): boolean;
+/**
+ * RESP 协议错误值（服务器 -ERR ...——协议层纯数据类，L0）。
+ * 定义于错误族（db/redis/resp.ts 重出兼容旧导入路径）。
+ */
+export declare class RespError extends DbError {
+    constructor(message: string);
+}

package/dist/level0/db/errors.ts

@@ -0,0 +1,89 @@
+/**
+ * weifuwu/db — 统一错误模型
+ *
+ * 自研 postgres/redis 客户端共享的错误类型体系。
+ * 目标：错误语义统一 → 业务层 catch 可编程（按 kind/code 决策）。
+ *
+ *   kind:          connection | protocol | timeout | validation | retryable
+ *   code:          PG 错误码（如 23505 唯一冲突）或协议码
+ */
+
+export type DbErrorKind = 'connection' | 'protocol' | 'timeout' | 'validation' | 'retryable'
+
+export class DbError extends Error {
+  readonly kind: DbErrorKind
+  readonly code?: string
+  readonly cause?: unknown
+
+  constructor(kind: DbErrorKind, message: string, options?: { code?: string; cause?: unknown }) {
+    super(message)
+    this.name = 'DbError'
+    this.kind = kind
+    this.code = options?.code
+    this.cause = options?.cause
+  }
+}
+
+/** 明确不支持的协议能力（诚实裁剪）：COPY 二进制、逻辑复制、集群、哨兵等 */
+export class ProtocolError extends DbError {
+  constructor(feature: string, message?: string) {
+    super('protocol', message ?? `${feature} is not supported by weifuwu/db`, { code: 'UNSUPPORTED' })
+    this.name = 'ProtocolError'
+  }
+}
+
+/** 连接失败（含重连尝试次数） */
+export class ConnectionError extends DbError {
+  readonly attempts: number
+
+  constructor(message: string, attempts = 1, cause?: unknown) {
+    super('connection', message, { cause })
+    this.name = 'ConnectionError'
+    this.attempts = attempts
+  }
+}
+
+/** 可重试错误：序列化失败/死锁（PG 40P01/40001）等 */
+export class RetryableError extends DbError {
+  constructor(message: string, code?: string, cause?: unknown) {
+    super('retryable', message, { code, cause })
+    this.name = 'RetryableError'
+  }
+}
+
+/** 超时：statement_timeout / connect_timeout / idle 等 */
+export class TimeoutError extends DbError {
+  readonly operation: string
+  readonly ms: number
+
+  constructor(operation: string, ms: number) {
+    super('timeout', `${operation} timed out after ${ms}ms`)
+    this.name = 'TimeoutError'
+    this.operation = operation
+    this.ms = ms
+  }
+}
+
+/** 写前校验失败（schema 注册 → 脏数据拦截） */
+export class ValidationError extends DbError {
+  constructor(message: string) {
+    super('validation', message)
+    this.name = 'ValidationError'
+  }
+}
+
+/** 判断错误是否可安全重试（事务层用） */
+export function isRetryable(err: unknown): boolean {
+  return err instanceof RetryableError
+}
+
+/**
+ * RESP 协议错误值（服务器 -ERR ...——协议层纯数据类，L0）。
+ * 定义于错误族（db/redis/resp.ts 重出兼容旧导入路径）。
+ */
+export class RespError extends DbError {
+  constructor(message: string) {
+    super('protocol', message, { code: 'RESP' })
+    this.name = 'RespError'
+  }
+}

package/dist/level0/db/filter.ts

@@ -0,0 +1,65 @@
+/**
+ * filterToWhere —— filter 对象 → WhereExpr 共享转换（命名契约 W0）
+ *
+ * 协议面（gql filter 输入 / rest query 参数）的数据面声明式过滤 → 查询 AST
+ * 的 WhereExpr——**一处实现三面用**（gql/rest/typedQuery 数据面语义一致）。
+ *
+ * 契约（与 query.ts WhereExpr 对齐）：
+ *   - 字段名 → 列名映射（shapeDef.dbFields[field].column）
+ *   - and/or 递归组（{ and: [...], or: [...] }）
+ *   - 算子集：eq/ne/gt/gte/lt/lte/in/notIn/isNull + contains/startsWith/endsWith
+ *     （→ ilike 转义——% _ 反斜杠转义）
+ *   - 单 eq 特判（{ col: { eq: v } } 直接 { col: { eq: v } }——组合式 path）
+ *   - undefined 值显式拒绝（W2 定案——不静默跳过——省略键或显式 isNull）
+ *   - 租户注入是调用侧拼装（协议策略——不在此函数内）
+ */
+import type { Shape } from './shape.ts'
+import { ValidationError } from './errors.ts'
+
+/** 列映射面（shapeDef.dbFields——字段→DB 列） */
+export interface FilterShapeFields {
+  dbFields: Record<string, { column?: string }>
+}
+
+/** filter 对象 → WhereExpr（字段→列名映射 + 算子转译 + 组合递归） */
+export function filterToWhere(
+  filter: Record<string, unknown> | null | undefined,
+  shapeDef: Pick<Shape<Record<string, never>>, 'dbFields'> | FilterShapeFields,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  if (!filter) return out
+  for (const [fname, fval] of Object.entries(filter)) {
+    if (fname === 'and' || fname === 'or') {
+      const groups = (Array.isArray(fval) ? fval : [fval]).map((f: Record<string, unknown>) => filterToWhere(f, shapeDef))
+      out[fname] = groups
+      continue
+    }
+    if (fval === null || typeof fval !== 'object') continue
+    const col = shapeDef.dbFields[fname]?.column ?? fname
+    const v = fval as Record<string, unknown>
+    // I1（W1——O1 对齐）：`{ eq: null }` = 判空——编译 isNull（真库 `= NULL` 恒假已废）
+    if (v.eq === null && Object.keys(v).length === 1) {
+      out[col] = { isNull: true }
+      continue
+    }
+    // 单 eq 特判（组合式 path——{ col: { eq: v } } 直接输出——非对象值）
+    if (Object.keys(v).some((k) => k === 'eq') && Object.keys(v).length === 1 && typeof v.eq !== 'object') {
+      out[col] = { eq: v.eq as unknown }
+      continue
+    }
+    const ops: Record<string, unknown> = {}
+    for (const [op, val] of Object.entries(v)) {
+      // W2（定案）：undefined 值显式拒绝——不静默跳过（跳过=过滤被静默放宽——与
+      // 「声明了就有行为」冲突；I1 eq:null 同型）。缺条件请省略键；判空用 isNull
+      if (val === undefined) throw new ValidationError(`filter 值不能为 undefined（列 ${col} 算子 ${op}）——省略该键或显式 isNull`)
+      if (val === null) { if (op === 'eq') { ops.isNull = true; continue } continue }
+      if (op === 'eq' && val === null) continue
+      if (op === 'contains') { ops.ilike = `%${String(val).replace(/([%_])/g, '\\$1')}%`; continue }
+      if (op === 'startsWith') { ops.ilike = `${String(val).replace(/([%_])/g, '\\$1')}%`; continue }
+      if (op === 'endsWith') { ops.ilike = `%${String(val).replace(/([%_])/g, '\\$1')}`; continue }
+      ops[op] = val
+    }
+    if (Object.keys(ops).length) out[col] = ops
+  }
+  return out
+}

package/dist/level0/db/generator-contracts.d.ts

@@ -0,0 +1,56 @@
+/**
+ * weifuwu/db — 生成器契约层（L0 纯类型）
+ *
+ * `orm.gql`/`orm.rest` 的选项与输出类型单源定义于此：
+ * - 消费方（core orm / 业务）不依赖生成器实现
+ * - 实现（`gql-from-shape.ts`/`rest-from-shape.ts`——装备面）导入并重出
+ *
+ * 纪律：改契约 = 改这里（实现不得私藏同名接口）。
+ */
+export interface GqlShapeOptions {
+    /** 生成类型名（默认表名 PascalCase） */
+    name?: string;
+    /** 执行面取数（默认 ctx.orm——协议层 = AST；orm.gql 内部绑定 ormBase） */
+    sql?: (ctx: unknown) => unknown;
+    /** 租户 scope：字段名 + 上下文取值（自动注入 where/insert——跨租户隔离；
+     *  与 OrmTenant.value 同签名——undefined=无值（不注入） */
+    tenant?: {
+        field: string;
+        value: (ctx: unknown) => string | undefined;
+    };
+    /** 默认分页上限（默认 100） */
+    maxLimit?: number;
+    /** 字段策略（命名契约 W0——fieldPolicy 首版）：敏感列豁免——
+     *  SDL 不生成（字段/Filter/Sort/Insert/Patch 全不出现）+ resolver 不返回 */
+    hidden?: string[];
+}
+export interface GqlShapeOutput {
+    typeDefs: string;
+    resolvers: Record<string, Record<string, (...args: any[]) => any>>;
+}
+export interface RestHooks {
+    beforeList?: (req: Request, ctx: unknown) => Promise<void> | void;
+    afterList?: (rows: Record<string, unknown>[], req: Request, ctx: unknown) => Record<string, unknown>[] | Promise<Record<string, unknown>[]>;
+    beforeInsert?: (data: Record<string, unknown>, req: Request, ctx: unknown) => Promise<void> | void;
+    beforeUpdate?: (id: string, patch: Record<string, unknown>, req: Request, ctx: unknown) => Promise<void> | void;
+    beforeDelete?: (id: string, req: Request, ctx: unknown) => Promise<void> | void;
+}
+export interface RestShapeOptions {
+    /** 资源名（默认表名——仅元数据） */
+    name?: string;
+    /** 默认分页上限（默认 100） */
+    maxLimit?: number;
+    /** 字段策略（fieldPolicy——敏感列豁免：列表/单查/返回不出现；写入面保留） */
+    hidden?: string[];
+    /** 业务接缝（hooks——分层纪律：业务 handler 插点） */
+    hooks?: RestHooks;
+}
+export interface RestShapeOutput {
+    /** 挂载面（app.get/post/patch/delete 注册——`/api/agents` 等 base） */
+    mount: (app: {
+        get: (p: string, h: (req: Request, ctx: never) => Promise<Response>) => unknown;
+        post: (p: string, h: (req: Request, ctx: never) => Promise<Response>) => unknown;
+        patch: (p: string, h: (req: Request, ctx: never) => Promise<Response>) => unknown;
+        delete: (p: string, h: (req: Request, ctx: never) => Promise<Response>) => unknown;
+    }, base: string) => void;
+}