weifuwu 0.90.0 → 0.91.0

package/dist/server/ai/memory-server.d.ts

@@ -0,0 +1,50 @@
+import { type MemoryAiOptions } from './memory.ts';
+import type { AiClient } from './client.ts';
+export interface MemoryAiServerOptions extends MemoryAiOptions {
+    /** 监听端口（0 = 随机——默认）。 */
+    port?: number;
+    /** 自定义后端（默认 createMemoryAi(options)——决策注入透传） */
+    ai?: AiClient;
+    /** 请求级注入（测试对 HTTP 面全控——替代自建 fake server）：
+     *  undefined = 走默认 handler（onChat/onEmbed 决策）
+     *  { status, body } = 故障注入（401/429/5xx）
+     *  { sse } = 原始 SSE 字节行（tool_calls 分片/坏流/半流）
+     *  { hang } = 挂起（不响应——首 token 超时/abort 测试） */
+    respond?: (req: MemoryAiRequest) => MemoryAiRespond | undefined;
+}
+/** 已接收请求（断言传输细节——路径/认证/体） */
+export interface MemoryAiRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+}
+/** 注入响应描述 */
+export type MemoryAiRespond = {
+    status: number;
+    body?: unknown;
+} | {
+    sse: string[];
+} | {
+    hang: true;
+} | {
+    sse: string[];
+    hang: true;
+};
+/** 正名构造（new MemoryAiServer() / MemoryAiServer() / createMemoryAiServer() 等价——async 返回 Handle） */
+export interface MemoryAiServer {
+    new (options?: MemoryAiServerOptions): Promise<MemoryAiServerHandle>;
+}
+export interface MemoryAiServerHandle {
+    port: number;
+    /** 完整 base URL（http://127.0.0.1:{port}——给 baseUrl 指向） */
+    url: string;
+    /** 已接收请求记录（断言用——含 respond 注入的请求） */
+    requests: MemoryAiRequest[];
+    /** 强制断开所有连接（hang 场景清理） */
+    closeAllConnections(): void;
+    close(): Promise<void>;
+}
+/** 工厂（= MemoryAiServer 正名——createMemoryAiServer 兼容别名） */
+export declare const createMemoryAiServer: typeof MemoryAiServer;
+export declare function MemoryAiServer(options?: MemoryAiServerOptions): Promise<MemoryAiServerHandle>;

package/dist/server/ai/memory.d.ts

@@ -0,0 +1,46 @@
+import { type AiClientModule } from './assemble.ts';
+import type { StreamFinishResult } from './client.ts';
+import type { ChatParams, ToolCall } from './types.ts';
+import type { ImageGenRequest, ImageGenResult, VideoGenRequest, VideoGenStatus } from './contracts.ts';
+/** MemoryAi 决策注入选项（= MemorySql 的「解析器」——注入方决定回什么） */
+export interface MemoryAiOptions {
+    /**
+     * 决策注入：chat 请求 → 响应内容。不注入 = 默认 echo（末条 user 消息）。
+     * 返回 shape：{ content, toolCalls?, reasoning_content?, usage? }
+     *   （工具决策：e2e 测试注入 tool_calls 序列——无需真实 LLM）
+     */
+    onChat?: (params: ChatParams) => Promise<{
+        content: string;
+        toolCalls?: ToolCall[];
+        reasoning_content?: string;
+        usage?: StreamFinishResult['usage'];
+    }> | {
+        content: string;
+        toolCalls?: ToolCall[];
+        reasoning_content?: string;
+        usage?: StreamFinishResult['usage'];
+    };
+    /** 嵌入注入（返回值需 text 长度 = 输入顺序）；默认 djb2 哈希向量（确定性） */
+    onEmbed?: (texts: string[]) => Promise<number[][]> | number[][];
+    /** 图片生成注入（测试断言生成面）；默认 1×1 透明 PNG data URL（确定性占位） */
+    onImage?: (req: ImageGenRequest) => Promise<ImageGenResult> | ImageGenResult;
+    /** 视频任务注入（onVideoSubmit: 提交→taskId；onVideoStatus: 查询→状态）——默认立即完成 */
+    onVideoSubmit?: (req: VideoGenRequest) => Promise<{
+        taskId: string;
+    }> | {
+        taskId: string;
+    };
+    onVideoStatus?: (taskId: string) => Promise<VideoGenStatus> | VideoGenStatus;
+    /** 默认模型名（响应回显——对齐真实 provider 行为） */
+    defaultModel?: string;
+    /** 审批超时 ms（默认 5 分钟——对齐 OpenAI transport） */
+    approvalTimeoutMs?: number;
+}
+/** 模块构造（new MemoryAi() / MemoryAi() / createMemoryAi() 等价——同 ai() 返回形态：
+ *  AiClientModule——app.use 注入 ctx.ai + 全能力）。参考 MemorySql 的工厂包装 */
+export interface MemoryAi {
+    new (options?: MemoryAiOptions): MemoryAi;
+}
+export declare function MemoryAi(options?: MemoryAiOptions): AiClientModule;
+/** 工厂别名（= MemoryAi——与 createMemorySql 命名对称；主包导出） */
+export declare const createMemoryAi: typeof MemoryAi;

package/dist/server/ai/multimodal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * weifuwu AI — 多模态 provider（DashScope 百炼)——拆分为独立工厂：
+ *
+ *   createDashscopeImage(opts?)   → 图片生成（generateImage——独立 baseUrl/apiKey/model）
+ *   createDashscopeVideo(opts?)   → 视频任务（createVideoTask + videoStatus——独立配置）
+ *
+ * 与 embedding 平级（AiClientOptions.image / .video 各自独立——可不同端点/不同 key/
+ * 不同模型——方便后续配置不同供应商）。参数归一在 provider 层单源：
+ *   图片：size 白名单（N*N 形态）；视频：RESOLUTIONS/RATIOS 白名单 + duration 夹紧
+ *   3-15 + watermark 默认 true。
+ *
+ * 配置：显式参数 > env（DASHSCOPE_API_KEY / DASHSCOPE_MAAS_API_URL / DASHSCOPE_IMAGE_MODEL /
+ * DASHSCOPE_VIDEO_MODEL——URL 均为完整 https 前缀——不做协议补全）。
+ */
+import type { ImageGenRequest, ImageGenResult, VideoGenRequest, VideoGenStatus } from './contracts.ts';
+/** 图片生成 provider 配置（独立于视频——可不同端点/键/模型） */
+export interface ImageGenOptions {
+    apiKey?: string;
+    /** 完整 URL（https 开头——默认 DASHSCOPE_MAAS_API_URL；测试环境可 http） */
+    baseUrl?: string;
+    /** 默认 DASHSCOPE_IMAGE_MODEL ?? 'z-image-turbo' */
+    model?: string;
+}
+/** 视频生成 provider 配置（独立于图片） */
+export interface VideoGenOptions {
+    apiKey?: string;
+    /** 完整 URL（https 开头——默认 DASHSCOPE_MAAS_API_URL；测试环境可 http） */
+    baseUrl?: string;
+    /** 默认 DASHSCOPE_VIDEO_MODEL ?? 'happyhorse-1.1-t2v' */
+    model?: string;
+}
+export declare const DEFAULT_IMAGE_MODEL = "z-image-turbo";
+export declare const DEFAULT_VIDEO_MODEL = "happyhorse-1.1-t2v";
+export interface ImageGenClient {
+    generateImage(req: ImageGenRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<ImageGenResult>;
+}
+export interface VideoGenClient {
+    createVideoTask(req: VideoGenRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        taskId: string;
+    }>;
+    videoStatus(taskId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<VideoGenStatus>;
+}
+/** 图片生成客户端（独立配置——不同端点/键/模型） */
+export declare function createDashscopeImage(opts?: ImageGenOptions): ImageGenClient;
+/** 视频任务客户端（独立配置） */
+export declare function createDashscopeVideo(opts?: VideoGenOptions): VideoGenClient;

package/dist/server/ai/openai.d.ts

@@ -0,0 +1,16 @@
+/**
+ * weifuwu AI — OpenAi provider 构造（new OpenAi() / OpenAi() ——同 ai() 返回模块）
+ *
+ * 参考 openai 兼容实现（client.ts——Chat/Agent 引擎）+ 多模态（multimodal.ts）——
+ * env 读取（DEEPSEEK_*）与模块组装（assemble）在这里汇合：
+ *   new OpenAi(opts) → AiClientModule（app.use 注入 ctx.ai——全能力）
+ * ai() 工厂的默认分支 = OpenAi（provider 选择器——正门构造对称 MemoryAi）。
+ */
+import { type AiClientOptions } from './client.ts';
+import { type AiClientModule } from './assemble.ts';
+/** OpenAi 构造选项（同 AiClientOptions——见 client.ts） */
+export type OpenAiOptions = AiClientOptions;
+export interface OpenAi {
+    new (options?: OpenAiOptions): OpenAi;
+}
+export declare function OpenAi(options?: OpenAiOptions): AiClientModule;

package/dist/server/db/body.d.ts

@@ -0,0 +1,31 @@
+/**
+ * weifuwu/db — bodyOf（shape → body 校验——handler 样板消失）
+ *
+ * 开发者动线（W0 体验提升）：shape 已知全部字段——handler 的 body 不再
+ * 手写类型/必填/枚举校验。parseBody 复用 insertSchema/updateSchema 变体
+ * （auto 列省略 · nullable/default 可缺省 · enum 校验）——与 orm 单源。
+ *
+ * 用法（手写 route——与 gql/rest 协议面同源）：
+ *   const body = await bodyOf(req, agents)            // BodyOf<typeof agents>
+ *   const patch = await bodyOf(req, agents, { variant: 'patch' })  // PatchOf
+ *
+ * 错误语义：ValidationError（400 面——错误消息含字段路径/期望——errorOf
+ * 映射；校验失败不抛原始 ZodError 噪音——可读优先）。
+ */
+import type { ZodRawShape } from '../../shared/zod.ts';
+import type { Shape, BodyOf } from './shape.ts';
+export interface BodyOfOptions {
+    /** insert（缺省——裸行 body——省略 auto）· patch（全可选——部分更新） */
+    variant?: 'insert' | 'patch';
+    /** 系统列（租户/服务端注入面）——校验前剔除（不变式：注入列声明面权威——
+     *  body 传该键被忽略而非校验——W4 试点（agents app_id）实证） */
+    omit?: string[];
+}
+type ShapeLike<S extends ZodRawShape> = Shape<S> | {
+    __shape: import('./shape.ts').Shape<S>;
+};
+/** 请求体 → 类型化输入行（shape 变体校验——enum/必填/nullable/auto 省略）。
+ *  命名纪律：parseBody（request.ts）是通用 JSON 解析——bodyOf 是 shape 校验面（一个词一个概念） */
+export declare function bodyOf<S extends ZodRawShape>(req: Request, shapeDef: ShapeLike<S>, opts?: BodyOfOptions): Promise<BodyOf<S>>;
+/** body 输入行类型快捷（parseBody 返回面——语义对等导出） */
+export type { BodyOf, PatchOf } from './shape.ts';

package/dist/server/db/consistency.d.ts

@@ -0,0 +1,28 @@
+export interface ConsistencyIssue {
+    level: 'error' | 'warn';
+    kind: string;
+    table: string;
+    column?: string;
+    expected?: string;
+    found?: string;
+}
+export interface DeclaredTable {
+    name: string;
+    fields: Record<string, unknown>;
+    dbFields: Record<string, {
+        column?: string;
+    }>;
+}
+export interface LiveTable {
+    name: string;
+    columns: {
+        name: string;
+        type: string;
+    }[];
+}
+/** PG 类型名归一（宽等价组——声明 DDL 名 vs 库 data_type 对齐；组内不误报） */
+export declare function normalizeType(t: string): string;
+export declare function diffConsistency(decl: DeclaredTable[], live: LiveTable[]): {
+    ok: boolean;
+    issues: ConsistencyIssue[];
+};

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

@@ -1,14 +1,13 @@
 /**
  * weifuwu/db — 自研数据库引擎契约层（接口与实现分离）
  *
- * 三个接口：消费方（ctx.sql / ctx.redis / 业务模块）只依赖接口类型，
- * 自研引擎（src/db/postgres|redis 的 class）实现它们：
+ * 三个接口族：消费方只依赖接口类型，自研引擎（src/db/postgres|redis 的 class）实现：
  *
  *   PoolConnection     通用连接（pg/redis 池中连接项：生命周期 + 健康）
  *     ├─ PostgresPoolConnection  特化：参数化查询（PgConnection 实现）
  *     └─ RedisPoolConnection     特化：命令执行（RedisClient 实现）
- *   Sql                 SQL 标签模板（ctx.sql）——makeSql(PgPool) 实现
- *   Redis               Redis 命令面（ctx.redis）——RedisPool 实现
+ *   Redis（+Pipeline/Subscriber）  Redis 命令面（ctx.redis）——命令面封闭无 parser
+ *   DbAdapter / Orm               ORM AST 协议层（业务唯一数据入口——ctx.orm）
  *
  * 变更纪律（ 协议层）：改契约须 TDD 先行 + 真库验证（CS-04/CS-05）。
  */
@@ -54,29 +53,6 @@ export interface QueryResult<T = Row> extends Array<T> {
 export interface PostgresPoolConnection extends PoolConnection {
     query(sql: string, params?: unknown[]): Promise<QueryResult>;
 }
-/**
- * SQL 标签模板（ctx.sql）：`sql\`SELECT * FROM t WHERE id = ${id}\`` + 方法面。
- * 事务能力走中间件面 `pg.transaction`（PostgresClient）——不在 Sql 接口。
- *
- * 三条执行路径（同一契约双实现）：
- *   标签模板 / unsafe —— 原生 SQL 字符串（Postgres 生态面、DDL、复杂原生查询）
- *   query —— Query Language（结构化对象 → 真库编译 SQL / 内存直执行 AST）
- */
-export interface Sql {
-    (strings: TemplateStringsArray, ...values: unknown[]): Promise<Row[]>;
-    /** 原生 SQL（DDL / 动态表名）；$1 占位符 + 参数 */
-    unsafe(sql: string, params?: unknown[]): Promise<Row[]>;
-    /** Query Language 入口：`sql.query.from('users').where({...}).run()` */
-    query: import('../db/query.ts').QueryBuilder;
-    /** raw 逃生舱：`sql.raw\`NOW() - interval '7 days'\``——真库透传/内存裁剪 */
-    raw(strings: TemplateStringsArray, ...values: unknown[]): import('../db/query.ts').RawSql;
-    /** PG 数组参数：`ANY(\${sql.array(ids)}::uuid[])`——默认数组插值是 jsonb 语义
-     *  （object → JSON），PG 数组语义需显式标记（两义并存零破坏——2027-10 批量审批实证） */
-    array(values: unknown[]): {
-        __pgArray: unknown[];
-    };
-    close(): Promise<void>;
-}
 /** Redis 连接（PoolConnection 特化：命令执行） */
 export interface RedisPoolConnection extends PoolConnection {
     command(name: string, ...args: (string | number)[]): Promise<RespValue>;

package/dist/server/db/filter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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';
+/** 列映射面（shapeDef.dbFields——字段→DB 列） */
+export interface FilterShapeFields {
+    dbFields: Record<string, {
+        column?: string;
+    }>;
+}
+/** filter 对象 → WhereExpr（字段→列名映射 + 算子转译 + 组合递归） */
+export declare function filterToWhere(filter: Record<string, unknown> | null | undefined, shapeDef: Pick<Shape<Record<string, never>>, 'dbFields'> | FilterShapeFields): Record<string, unknown>;

package/dist/server/db/gql-from-shape.d.ts

@@ -0,0 +1,42 @@
+/**
+ * weifuwu/gql —— gqlFromShape：shape → GraphQL 生成器（纯函数）
+ *
+ * shape（数据"是什么"）→ SDL 字符串 + resolver 桥（filter 参数 → WhereExpr 算子）
+ * 输出即内置接口输入（graphql() 的 schema/resolvers——makeExecutableSchema 链路）
+ *
+ * 生成面（W6 首版·诚实边界见 plan 判负记录）：
+ *   - Query:  list(filter/sort/limit/offset) · one(filter)
+ *   - Mutation: insert(data) · update(id,patch) · delete(id)
+ *   - 类型：string/uuid→String·number→Float·boolean→Boolean·date→String(ISO)·
+ *     enum/literal→GraphQL enum·array→[T!]·optional→可空
+ *   - Filter：每字段输入对象（eq/ne/gt/gte/lt/lte/in/notIn/isNull/contains/ilike/
+ *     startsWith/endsWith——按列类型裁剪）+ and/or 组合
+ *   - Sort：[{ field: enum!, dir: enum }]
+ *   - 租户 scope：tenant 配置自动注入 where/insert（上下文 appId）
+ * 判负（后续再议）：关系面（JOIN/嵌套对象——非 W6）·json 字段（String 序列化）·
+ *   复杂 mutation（批量/upsert/事务）·uuid→ID 映射（String 面）
+ */
+import { type Shape } from './shape.ts';
+import { type ZodRawShape } from '../../shared/zod.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 declare function gqlFromShape<S extends ZodRawShape>(shapeDef: Shape<S>, opts?: GqlShapeOptions): GqlShapeOutput;

package/dist/server/db/http.d.ts

@@ -0,0 +1,38 @@
+/**
+ * weifuwu/db — http（协议面 helpers——handler 样板消失第二刀）
+ *
+ * listQuery：URL query → { filter, sort, limit, offset }（rest 私有解析提取——
+ *   手写 route 的 32 处 searchParams 解析收口）——枚举白名单/sort 字段校验/
+ *   limit clamp（默认 20 · max 100）与 rest 行为等价。
+ * errorResponse：错误 → Response（状态码映射——DbError validation→400 ·
+ *   唯一冲突 23505→409 · 显式 status 优先（业务守卫 403 等））——catch 样板收口。
+ */
+import type { ZodRawShape } from '../../shared/zod.ts';
+import type { Shape } from './shape.ts';
+export interface ListQueryOptions {
+    /** limit 上限（缺省 100） */
+    maxLimit?: number;
+    /** limit 缺省（缺省 20） */
+    defaultLimit?: number;
+}
+/**
+ * URL query → 列表参数（eq 直排 · sort `-field,field2` 多字段 · limit/offset clamp）。
+ *
+ * 校验失败（枚举值白名单/未知 sort 字段）→ 抛错（调用方 errorResponse——400）。
+ * filter 键 = shape 字段名（未知列由 orm 面校验兜底——42P01 显式）。
+ */
+export declare function listQuery(url: URL, shapeDef: Shape<ZodRawShape>, opts?: ListQueryOptions): {
+    filter: Record<string, unknown>;
+    sort: {
+        field: string;
+        dir: 'asc' | 'desc';
+    }[];
+    limit: number;
+    offset: number;
+};
+/**
+ * 错误 → Response（状态码映射——catch 样板收口）。
+ * - 显式 status 优先（业务守卫抛错 403 等——调用方定语义）
+ * - DbError：validation → 400 · 23505 唯一冲突 → 409 · 其余 → 400（缺省）
+ */
+export declare function errorResponse(e: unknown, status?: number): Response;

package/dist/server/db/memory-sql.d.ts

@@ -1,7 +1,8 @@
-import type { Sql, Row, QueryResult } from './contracts.ts';
+import type { Row, QueryResult } from './contracts.ts';
 import type { Query } from './query.ts';
 /** 事务快照表条目（rows + 元数据副本——restore 需复活事务内 DROP 掉的表） */
 export interface MemorySnapshotEntry {
+    state: 'declared' | 'observed';
     rows: Row[];
     nextId: number;
     columns: string[];
@@ -11,26 +12,71 @@ export interface MemorySnapshotEntry {
         defaultUuid: boolean;
     };
     uniques: string[];
+    groups: string[][];
     defaultNow: string[];
+    defaultVals: Record<string, unknown>;
 }
 export type MemorySnapshot = Map<string, MemorySnapshotEntry>;
 export declare class MemorySql {
+    /** 客户端路径列校验开关（wire 服务器端关闭——它是 PG 替身：列错由真库语义 42703 报） */
+    private opts;
+    constructor(opts?: {
+        validateCols?: boolean;
+    });
     private tables;
-    /** 派生表 AST 缓存（同 innerSql 不重复 parse——执行路径热缓存） */
-    private derivedAstCache;
-    /** 标签模板 → 参数化 SQL（values 顺序即 $1..$n） */
-    tag(strings: TemplateStringsArray, values: unknown[]): Promise<Row[]>;
-    unsafe(sql: string, params?: unknown[]): Promise<Row[]>;
+    /** CREATE TYPE AS ENUM 注册（幂等——DO 块 EXCEPTION duplicate_object 语义） */
+    private enums;
+    /** 标签模板 → 参数化 SQL（values 顺序即 $1..$n）——W3c：文本面删净——仅 AST 执行 */
     close(): Promise<void>;
     /** 执行结构化查询（真库编译 SQL / 内存直操作表） */
     executeQuery(q: Query): QueryResult<Row>;
+    /** jsonb 列读取解码（对齐真库驱动 convertValue(114/3802) → JSON.parse）
+     * 状态机行为矩阵（W3）：
+     *  - declared：columnTypes 判定（jsonb 列解码——确定）
+     *  - observed：行键值启发（JSON 可解析且结果为对象/数组 → 解码——列型未知的
+     *    诚实降级；text 列存 '[..]' 字符串会被解码——透明注记在 inspectTable） */
+    private jsonDecodeRows;
+    /** 合法列集：DDL columns ∪ 观测行键（insert 建表无 DDL——行键即事实列） */
+    private tableCols;
+    /** W1 列校验：where/join-on/投影/orderBy/groupBy 纯列引用 ∈ 表列集（未知列不再静默） */
+    private assertKnownCols;
     private execSelect;
     private execInsert;
     private execUpdate;
     private execDelete;
+    private assertTableExists;
+    /** 状态机获取：absent 访问显式拒绝（42P01——对齐真库——join 未注册表不再静默空表） */
     private table;
+    /** 状态机唯一创建点：absent → 空表（state 由调用方转换——declare 或 observe） */
+    private obtain;
+    /** 状态机转换：declared（声明态——applySchema/executeDdl(createTable) 调用） */
+    private toDeclared;
     /** 表是否存在（PG 服务器 42P01 检查——内存惰性建表 vs 真库报错） */
     hasTable(table: string): boolean;
+    /** 状态可见面（W3 状态机——透明契约）：状态 + 列集 + 类型 + 约束快照——测试断言用 */
+    inspectTable(table: string): {
+        state: 'declared' | 'observed';
+        columns: string[];
+        columnTypes: Record<string, string>;
+        constraints: {
+            pk?: {
+                col: string;
+                defaultUuid: boolean;
+            };
+            uniques: string[];
+            groups: string[][];
+            defaultNow: string[];
+            defaultVals: Record<string, unknown>;
+        };
+    };
+    /** 全表快照（W3 一致性诊断——schemaSnapshot：表/列/类型——透明面） */
+    schemaSnapshot(): {
+        name: string;
+        columns: {
+            name: string;
+            type: string;
+        }[];
+    }[];
     /** PG 服务器 Describe：列类型 → OID 推断辅助 */
     getColumnType(table: string, col: string): string | undefined;
     /** PG 服务器 Parse：INSERT VALUES 列序 → 类型列表 */
@@ -39,8 +85,20 @@ export declare class MemorySql {
     snapshot(): MemorySnapshot;
     /** 恢复快照（ROLLBACK）——全量还原（含复活事务内 DROP 掉的表）；快照后新建的表清空 */
     restore(snap: MemorySnapshot): void;
+    /** 声明式 Schema 应用（applySchema——SchemaModule → 元数据直构造；与 DDL 解析器同落点） */
+    applySchema(mod: import('./schema.ts').SchemaModule): void;
     /** DDL 执行（parser 产出 DdlQuery）——约束提取到表元数据 */
     private executeDdl;
 }
-/** MemorySql 工厂：类不可 callable——工厂包装为 callable Sql（与 makeSql(PgPool) 同构） */
-export declare function createMemorySql(): Sql;
+/** 余弦相似度（pgvector `1 - (a <=> b)` 等价——cosine distance 变体） */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export declare function resolveExprValue(_col: string, cur: unknown, expr: unknown, row: Record<string, unknown>): unknown;
+export declare function isMergeExpr(v: unknown): boolean;
+/** 日期表达式值求值（where 值面：__interval/__monthStart——编码即语义） */
+export declare function dateExprValue(v: unknown): unknown;
+/** 内存 ORM（测试装配——orm 面直执行；close 释放） */
+export declare function createMemoryOrm(engine?: MemorySql): {
+    orm: import('./orm.ts').Orm;
+    mem: MemorySql;
+    close: () => Promise<void>;
+};

package/dist/server/db/ops.d.ts

@@ -0,0 +1,70 @@
+/**
+ * weifuwu/ops —— operator 契约（shape+operator 架构的查询行为层）
+ *
+ * 算子（drizzle 式）→ WhereExpr（MemorySql 已验证执行面——零新执行代码）
+ * 类型收窄：ColRef<T> phantom——eq 值类型绑定列类型·ilike 仅 string 列（编译期）
+ *
+ * 用法：
+ *   const agents = cols('agents', { id: z.uuid(), type: z.enum(['ai','user']), name: z.string() })
+ *   where(and(eq(agents.type, 'ai'), ilike(agents.name, '%张%')))
+ *   → { type: 'ai', name: { ilike: '%张%' } }（and 为顶层 AND 合并——单列同键覆盖场景除外）
+ */
+import type { WhereExpr } from './query.ts';
+/** 列引用（phantom：输出类型 T 绑定列类型——算子值收窄） */
+export interface ColRef<T = unknown> {
+    /** 列名（dsl 引用名——通常即字段名/别名.字段名） */
+    readonly ref: string;
+    /** 输出类型 phantom */
+    readonly __out: T;
+}
+/** 形状驱动的列引用表（keys 与 shape 字段一致——类型面） */
+export type ShapeCols<S extends Record<string, unknown>> = {
+    [K in keyof S]: ColRef<S[K]>;
+};
+/** 从字段定义构建列引用（形状驱动——类型从 shape 类型参数推导） */
+export declare function cols<S extends Record<string, unknown>>(_prefix: string, _shape?: S): ShapeCols<S>;
+/** 等值算子（算子模式唯一形态：`{ [col]: { eq: value } }`——裸标量形态已移除） */
+export declare const eq: <T>(col: ColRef<T>, value: T) => WhereExpr;
+export declare const ne: <T>(col: ColRef<T>, value: T) => WhereExpr;
+export declare const gt: <T>(col: ColRef<T>, value: T) => WhereExpr;
+export declare const gte: <T>(col: ColRef<T>, value: T) => WhereExpr;
+export declare const lt: <T>(col: ColRef<T>, value: T) => WhereExpr;
+export declare const lte: <T>(col: ColRef<T>, value: T) => WhereExpr;
+export declare const inArray: <T>(col: ColRef<T>, values: T[]) => WhereExpr;
+export declare const notInArray: <T>(col: ColRef<T>, values: T[]) => WhereExpr;
+export declare const between: <T>(col: ColRef<T>, lo: T, hi: T) => WhereExpr;
+export declare const like: (col: ColRef<string>, pattern: string) => WhereExpr;
+export declare const ilike: (col: ColRef<string>, pattern: string) => WhereExpr;
+/** contains（%v%——ILIKE 语义——内部模糊搜索面） */
+export declare const contains: (col: ColRef<string>, v: string) => WhereExpr;
+export declare const startsWith: (col: ColRef<string>, v: string) => WhereExpr;
+export declare const endsWith: (col: ColRef<string>, v: string) => WhereExpr;
+/** 列对列等式（join on 面：`eqCol(dm.departmentId, d.id)` → `{ 'dm.department_id': { col: 'd.id' } }`） */
+export declare const eqCol: (left: ColRef<unknown>, right: ColRef<unknown>) => WhereExpr;
+export declare const isNull: (col: ColRef<unknown>) => WhereExpr;
+export declare const isNotNull: (col: ColRef<unknown>) => WhereExpr;
+/** NOW()（时间戳 SET——`col = NOW()`） */
+export declare const now: () => unknown;
+/** NOW() + INTERVAL 'n unit'（n 负 = 过去——`NOW() - INTERVAL 'n unit'`） */
+export declare function nowInterval(n: number, unit?: 'day' | 'hour' | 'minute'): unknown;
+/** NOW() - INTERVAL 'n unit'（时间窗查询——记忆/审计等） */
+export declare function nowAgo(n: number, unit?: 'day' | 'hour' | 'minute'): unknown;
+/** DATE_TRUNC('month', NOW())（月起始——计量/账单窗口） */
+export declare const monthStart: () => unknown;
+/** 列引用 SET（`col = other_col`——messages.content = ai_draft 等） */
+export declare const colRef: (name: string) => unknown;
+/**
+ * AND 组合（顶层列合并——同键（eq 两次）后者覆盖的边界：显式传入 and 数组时
+ * 以数组语义（逐条）执行——见 MemorySql 'and' 分支）
+ */
+/** 条件安全组合：空对象/联合条件（`q ? {...} : {}` 样板）直接收——空对象恒真（AND 无约束/OR 恒真符合直觉） */
+export type CondWhere = WhereExpr | Record<string, never>;
+export declare function and(...conds: CondWhere[]): WhereExpr;
+export declare function or(...conds: CondWhere[]): WhereExpr;
+export declare function not(cond: WhereExpr): WhereExpr;
+/** jsonb 数组追加（`col = col || $n::jsonb`）——agent_run_states.steps 等 */
+export declare function mergeAppend(val: unknown): unknown;
+/** 数值自增（`col = col + n`）——answer_cache.hits 等 */
+export declare function mergeInc(n?: number): unknown;
+/** 时间戳（`NOW()`）——updated_at 等（与 ops.now 同编码） */
+export declare const mergeNow: () => unknown;