weifuwu 0.90.0 → 0.91.0

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

@@ -0,0 +1,110 @@
+import type { Query } from './query.ts';
+import type { QueryResult } from './contracts.ts';
+import type { ZodRawShape } from '../../shared/zod.ts';
+import { type GqlShapeOptions, type GqlShapeOutput } from './gql-from-shape.ts';
+import type { SelectBuilder, InsertBuilder, UpdateBuilder, DeleteBuilder, QueryBuilder } from './query.ts';
+import type { Infer } from '../../shared/zod.ts';
+export interface DbAdapter {
+    /** Query AST 执行（业务主路） */
+    executeQuery(q: Query): Promise<QueryResult>;
+    /** 事务（同连接执行 fn——postgres 真事务；memory 无事务面（no-op 等价标注） */
+    transaction?<T>(fn: (execute: (q: Query) => Promise<QueryResult>) => Promise<T>): Promise<T>;
+}
+/** 行类型（shape 字段名 → zod Infer——编译期类型安全） */
+export type RowOf<S extends ZodRawShape> = {
+    [K in keyof S]: Infer<S[K]>;
+};
+export interface OrmTable<S extends ZodRawShape> {
+    /** 列引用表（类型收窄：eq(Agent.c.type, 'ai')——值类型绑定列类型·编译期） */
+    c: {
+        [K in keyof S]: {
+            ref: string;
+            readonly __out: import('../../shared/zod.ts').Infer<S[K]>;
+        };
+    };
+    /** 查询入口（select(cols?)——builder 链·行类型 RowOf<S>） */
+    select(...cols: string[]): SelectBuilder<RowOf<S>>;
+    /** 插入入口（values 单行或数组——shape 校验/列名翻译 orm 内部接线） */
+    insert(values: Record<string, unknown> | Record<string, unknown>[]): InsertBuilder<RowOf<S>>;
+    /** 更新入口（patch 部分更新） */
+    update(patch: Record<string, unknown>): UpdateBuilder<RowOf<S>>;
+    /** 删除入口（必须 where——builder 层防护） */
+    delete(): DeleteBuilder<RowOf<S>>;
+    /** 存在检查（isMember 样板收口——limit 1 短路） */
+    exists(where: import('./query.ts').WhereExpr): Promise<boolean>;
+    /** 列表模式（count+list 双查收口——平台列表面样板） */
+    paginate(opts: {
+        filter?: import('./query.ts').WhereExpr;
+        /** W3：sort 字段类型化（keyof S——字面量多余键编译红） */
+        sort?: {
+            field: keyof S & string;
+            dir?: 'asc' | 'desc';
+        }[];
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        rows: RowOf<S>[];
+        total: number;
+    }>;
+    /** shape 定义（元数据/变体/校验——业务类型注入） */
+    shapeDef: S;
+    /** 内部 shape 实体（gql 元数据消费） */
+    readonly __shape: import('./shape.ts').Shape<S>;
+}
+/** 租户 scope 配置（withCtx 自动注入面——平台 47 处手写 app_id 过滤收口） */
+export interface OrmTenant {
+    /** scope 字段（shape 字段名） */
+    field: string;
+    /** 上下文取值（每请求 appId 等） */
+    value: (ctx: unknown) => string | undefined;
+}
+export interface CtxOrm extends Orm {
+    /** 租户 scope 表（自动 where/注入）——派生面 table(name) 免 shapeDef */
+    ctxTable<S extends ZodRawShape>(name: string, shapeDef: S): OrmTable<S>;
+    ctxTable(name: string): OrmTable<ZodRawShape>;
+}
+/**
+ * 租户绑定视图：ctx.orm = orm.withCtx(ctx)——表操作自动 scope
+ * （select/update/delete 预置 where·insert 注入 field——与用户条件 AND 合并）
+ */
+export interface Orm {
+    /** 表注册（shape 驱动——列引用/校验/变体）——同名表幂等返回；
+     *  派生面（tx/ctx）用 table(name) 免 shapeDef（共享 registry） */
+    table<S extends ZodRawShape>(name: string, shapeDef: S): OrmTable<S>;
+    table(name: string): OrmTable<ZodRawShape>;
+    /** 租户绑定视图（ctx→自动 scope——select/insert/update/delete 预置 tenant 条件） */
+    withCtx(ctx: unknown): CtxOrm;
+    /** 兜底查询面（复杂 JOIN/嵌套——builder 原生） */
+    query: QueryBuilder;
+    /** GraphQL 生成（shape → SDL + resolvers——内置链路输入） */
+    gql<S extends ZodRawShape>(table: OrmTable<S>, opts?: GqlShapeOptions): GqlShapeOutput;
+    /** RESTful 面（W4——restFromShape 入口对称：`rest = orm.rest(table); rest.mount(app, base)`） */
+    rest<S extends ZodRawShape>(table: OrmTable<S>, opts?: import('./rest-from-shape.ts').RestShapeOptions): import('./rest-from-shape.ts').RestShapeOutput;
+    /** 事务（fn 内同连接执行——commit 可见/rollback 撤销；memory 单线程 no-op 等价） */
+    transaction<T>(fn: (tx: Orm) => Promise<T>): Promise<T>;
+    /** AST 执行面（协议层 = AST——Query 纯数据可序列化；测试播种/嵌入执行入口） */
+    execute(q: Query): Promise<QueryResult>;
+    /** 注册表枚举（state-machine 透明化——checkConsistency 输入面/诊断可见） */
+    tables(): {
+        name: string;
+        fields: Record<string, unknown>;
+        dbFields: Record<string, {
+            column?: string;
+        }>;
+    }[];
+}
+export declare function createOrm(adapter: DbAdapter, tenant?: OrmTenant): Orm;
+/** postgres adapter：Query AST → compileQuery（参数化 SQL）→ 服务器（PG wire） */
+export declare function postgresAdapter(pool: {
+    query: (sql: string, params?: unknown[]) => Promise<QueryResult>;
+}, compile: (q: Query) => {
+    sql: string;
+    params: unknown[];
+}): DbAdapter;
+/** memory adapter：Query AST → 内存引擎直执行（fuzz 对账保证与 PG 等价） */
+export declare function memoryAdapter(engine: {
+    executeQuery(q: Query): QueryResult;
+    /** 事务快照/回滚（MemorySql 提供——无则 no-op 等价标注） */
+    snapshot?(): unknown;
+    restore?(snap: unknown): void;
+}): DbAdapter;

package/dist/server/db/query-builder.d.ts

@@ -10,8 +10,10 @@
  * await sql.query.insert('users').values({ email: 'a@b.c' }).returning('id').run()
  * ```
  */
-import type { Sql, Row } from './contracts.ts';
+import type { Row } from './contracts.ts';
 import { type Query, type QueryBuilder } from './query.ts';
 type Executor = (q: Query) => Promise<Row[]>;
-export declare function createQueryBuilder(sql: Sql, exec: Executor): QueryBuilder;
+export declare function createQueryBuilder(exec: Executor): QueryBuilder;
+/** AST 构建工厂（协议层 = AST——无执行：toQuery() 产出纯数据 Query 供传输/嵌入执行） */
+export declare function buildQuery(): QueryBuilder;
 export {};

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

@@ -5,12 +5,18 @@ export interface RawSql {
 }
 /** 逃生舱：`sql.raw\`created_at > NOW() - interval '7 days'\`` */
 export declare function rawSql(sql: string, params?: unknown[]): RawSql;
+/** 算子值标量（列条件值——不允许裸标量/数组/null 形态直接做 WhereField） */
 export type WhereScalar = string | number | boolean | null;
-/** 列级条件操作符 */
+/**
+ * 列级条件操作符（唯一形态——算子模式）：列 = 算子对象。
+ * 约定（2027-10 表达清理）：值形态不再接受标量/数组/null——等值用 `{ eq: v }`·
+ * IN 用 `{ in: [...] }`·NULL 判定用 `{ isNull: true/false }`——语义显式无歧义
+ * （旧歧义：数组既是 IN 又是 jsonb 数组值；`= NULL` 恒假 vs 内存判 true）。
+ */
 export interface ColOps {
     /** 列引用（非字面量）：`{ 'u.email': { col: 'o.user_id' } }` → u.email = o.user_id */
     col?: string;
-    /** 等值（同列合并形态：scalar 进 ColOps——parser 同列 = 合并 / builder scalar×ops 合并产出） */
+    /** 等值 */
     eq?: WhereScalar;
     gt?: WhereScalar;
     gte?: WhereScalar;
@@ -25,7 +31,10 @@ export interface ColOps {
     isNull?: boolean;
     between?: [WhereScalar, WhereScalar];
 }
-export type WhereField = WhereScalar | WhereScalar[] | RawSql | ColOps;
+/** 算子键集（jsonb 深度等值判定：无任一算子键的对象 → 按值深度比较） */
+export declare const COL_OPS_KEYS: readonly ["col", "eq", "gt", "gte", "lt", "lte", "ne", "in", "notIn", "like", "ilike", "isNull", "between"];
+/** 列条件值（唯一形态）：算子对象 | jsonb 值对象（无算子键——深度等值）——raw where 已删（W3a） */
+export type WhereField = ColOps | Record<string, unknown>;
 /**
  * WHERE 表达式：列条件 AND 连接。
  * 结构键：`or: WhereExpr[]`（OR 组——组间 AND）、`and: WhereExpr[]`（AND 组——
@@ -74,16 +83,16 @@ export interface SelectQuery {
         fn: 'count' | 'sum' | 'avg' | 'min' | 'max';
         col: string;
         as: string;
+        filter?: WhereExpr;
     }[];
     /** count(*) 聚合（SQL parser 产出——SELECT count(*) FROM t）——结果为单行 { count } */
     count?: boolean;
-    /** 内存执行扩展：常量投影/UNION 行（SQL parser 产出——无表查询） */
-    unionRows?: Row[];
-    /** 内存执行扩展：派生表（FROM (SELECT ...) alias——parser 产出） */
-    derived?: {
-        innerSql: string;
-        alias?: string;
-        where?: string;
+    /** pgvector 相似度排序（列投影：`1 - (col <=> vec) as as` + ORDER BY col <=> vec）——
+     *  平台知识检索唯一向量面（业务零 SQL——向量为 pgvector 特化存储） */
+    vector?: {
+        col: string;
+        vec: number[];
+        as: string;
     };
 }
 export interface InsertQuery {
@@ -91,10 +100,14 @@ export interface InsertQuery {
     table: string;
     rows: Row[];
     returning?: string[] | '*';
-    /** upsert：ON CONFLICT (col) DO UPDATE SET col=EXCLUDED.col；col 省略 = 任意唯一冲突 DO NOTHING */
+    /** upsert：ON CONFLICT (col) DO UPDATE SET col=EXCLUDED.col；col 省略 = 任意唯一冲突 DO NOTHING
+     *  col 可为数组（复合唯一目标（department_id, agent_id）等——平台 7 处）
+     *  merge：冲突列覆盖表达式（__jsonbAppend 追加 / __inc 自增 / RawSql / 标量）——
+     *  jsonb `||` / hits+1 等表达更新面（业务零 SQL——经标量编码） */
     onConflict?: {
-        col?: string;
+        col?: string | string[];
         update?: boolean;
+        merge?: Record<string, unknown>;
     };
 }
 export interface UpdateQuery {
@@ -110,10 +123,10 @@ export interface DeleteQuery {
     where?: WhereExpr;
     returning?: string[] | '*';
 }
-/** DDL 语句（SQL parser 产出——内存执行提取约束；真库走 raw 字符串） */
+/** DDL 语句（协议层 = DDL AST——memory 直执行；真库 ddlToSql 单向编译输出 SQL） */
 export interface DdlQuery {
     kind: 'ddl';
-    op: 'createTable' | 'dropTable' | 'createIndex' | 'alter';
+    op: 'createTable' | 'dropTable' | 'dropEnum' | 'createIndex' | 'alter' | 'alterAddColumn' | 'createEnum' | 'alterEnumAddValue' | 'createExtension' | 'doBlock';
     table?: string;
     ifNotExists?: boolean;
     /** 列定义（createTable）——约束提取（PK/UNIQUE/DEFAULT now） */
@@ -124,14 +137,47 @@ export interface DdlQuery {
         unique: boolean;
         defaultNow: boolean;
         defaultUuid: boolean;
+        defaultVal?: unknown;
+        constraintCols?: string[];
+        nullable?: boolean;
+        ref?: {
+            table: string;
+            col?: string;
+            onDelete?: string;
+        };
     }[];
+    /** createTable 表级 CHECK（声明枚举 IN 约束——ddlToSql 重建；内存 no-op 语义同 parser 面） */
+    checks?: {
+        col: string;
+        vals: string[];
+    }[];
+    /** createIndex：索引声明（ddlToSql 重建；内存索引 no-op） */
+    index?: {
+        name: string;
+        cols: string;
+        unique: boolean;
+        using?: string;
+        opclass?: string;
+        with?: string;
+        where?: string;
+    };
+    /** alter：DROP NOT NULL（老库升级——内存 no-op） */
+    dropNotNull?: string[];
+    /** createEnum：枚举值清单 */
+    enumValues?: string[];
+    /** alterAddColumn：增量列（列名/类型/默认值——对齐声明式迁移 ADD COLUMN IF NOT EXISTS） */
+    column?: string;
+    columnType?: string;
+    defaultVal?: unknown;
+    /** 列可空性（alterAddColumn/createTable 列——NOT NULL 重建面） */
+    nullable?: boolean;
 }
 export type Query = SelectQuery | InsertQuery | UpdateQuery | DeleteQuery | DdlQuery;
 export interface QueryResultWithAffected<T = Row> extends Array<T> {
     affectedRows?: number;
 }
 /** builder 链：方法返回 this；.run()/.one() 执行 */
-export interface SelectBuilder {
+export interface SelectBuilder<T = Row> {
     distinct(): this;
     select(...cols: (string | RawSql)[]): this;
     join(table: string, on: JoinClause['on'], opts?: {
@@ -139,39 +185,49 @@ export interface SelectBuilder {
         type?: 'inner' | 'left';
     }): this;
     where(expr: WhereExpr): this;
-    whereRaw(sql: string, params?: unknown[]): this;
     /** IN/EXISTS 子查询 */
     in(col: string, query: SelectQuery, not?: boolean): this;
     exists(query: SelectQuery, not?: boolean): this;
     groupBy(...cols: string[]): this;
     having(expr: WhereExpr): this;
-    count(col?: string, as?: string): this;
-    sum(col: string, as?: string): this;
+    count(col?: string, as?: string, filter?: WhereExpr): this;
+    sum(col: string, as?: string, filter?: WhereExpr): this;
+    avg(col: string, as?: string, filter?: WhereExpr): this;
+    min(col: string, as?: string, filter?: WhereExpr): this;
+    max(col: string, as?: string, filter?: WhereExpr): this;
     orderBy(col: string, dir?: 'asc' | 'desc'): this;
+    /** pgvector 相似度：注入投影 `1 - (col <=> vec) as as` + `ORDER BY col <=> vec`（知识检索面） */
+    vectorScore(col: string, vec: number[], as: string): this;
     limit(n: number): this;
     offset(n: number): this;
-    run(): Promise<QueryResult<Row>>;
-    one(): Promise<Row | undefined>;
+    run(): Promise<QueryResult<T>>;
+    one(): Promise<T | undefined>;
+    /** AST 面：返回纯数据 Query（协议层 = AST——可序列化传输/嵌入执行） */
+    toQuery(): SelectQuery;
 }
-export interface InsertBuilder {
+export interface InsertBuilder<T = Row> {
     values(row: Row): this;
     rows(rows: Row[]): this;
     returning(...cols: (string | '*')[]): this;
-    onConflict(col?: string, update?: boolean): this;
-    run(): Promise<QueryResult<Row>>;
+    onConflict(col?: string | string[], update?: boolean, merge?: Record<string, unknown>): this;
+    run(): Promise<QueryResult<T>>;
+    /** AST 面：返回纯数据 Query（协议层 = AST——可序列化传输/嵌入执行） */
+    toQuery(): InsertQuery;
 }
-export interface UpdateBuilder {
+export interface UpdateBuilder<T = Row> {
     set(sets: Row): this;
     where(expr: WhereExpr): this;
-    whereRaw(sql: string, params?: unknown[]): this;
     returning(...cols: (string | '*')[]): this;
-    run(): Promise<QueryResult<Row>>;
+    run(): Promise<QueryResult<T>>;
+    /** AST 面：返回纯数据 Query（协议层 = AST——可序列化传输/嵌入执行） */
+    toQuery(): UpdateQuery;
 }
-export interface DeleteBuilder {
+export interface DeleteBuilder<T = Row> {
     where(expr: WhereExpr): this;
-    whereRaw(sql: string, params?: unknown[]): this;
     returning(...cols: (string | '*')[]): this;
-    run(): Promise<QueryResult<Row>>;
+    run(): Promise<QueryResult<T>>;
+    /** AST 面：返回纯数据 Query（协议层 = AST——可序列化传输/嵌入执行） */
+    toQuery(): DeleteQuery;
 }
 export interface QueryBuilder {
     from(table: string, alias?: string): SelectBuilder;
@@ -187,9 +243,9 @@ interface Compiled {
 export declare function compileSelect(q: SelectQuery): Compiled;
 /** 编译 INSERT（多行 + RETURNING + ON CONFLICT） */
 export declare function compileInsert(q: InsertQuery): Compiled;
-/** 编译 UPDATE */
+/** 编译 UPDATE —— 无 where 拒绝（防全表更新——一处防护覆盖真库/memory/gql） */
 export declare function compileUpdate(q: UpdateQuery): Compiled;
-/** 编译 DELETE */
+/** 编译 DELETE —— 无 where 拒绝（防全表误删——一处防护覆盖真库/memory/gql） */
 export declare function compileDelete(q: DeleteQuery): Compiled;
 /** 统一编译入口 */
 export declare function compileQuery(q: Query): Compiled;
@@ -197,7 +253,7 @@ export declare function compileQuery(q: Query): Compiled;
  * 同列条件对象级合并（AND 语义）。不可合并返回 null（调用方 and 包装）：
  *   ColOps × ColOps → 不相交操作符键 spread（{gt:15}+{lt:35} 并存）
  *   scalar × ColOps → { eq: scalar, ...ops }（eq 登记——编译/执行双端认识）
- *   数组（IN）/ raw / scalar × scalar / 同键冲突 / null 标量 → null
+ *   数组（IN）/ scalar × scalar / 同键冲突 / null 标量 → null
  */
 export declare function mergeWhereField(prev: WhereField, next: WhereField): WhereField | null;
 /**
@@ -207,4 +263,6 @@ export declare function mergeWhereField(prev: WhereField, next: WhereField): Whe
 export declare function addWhereCond(expr: WhereExpr, col: string, field: WhereField): void;
 /** where 表达式合并（builder 链式追加——AND 语义，不覆盖） */
 export declare function mergeWhere(prev: WhereExpr, next: WhereExpr): WhereExpr;
+/** update/upsert merge 表达式编译（__jsonbAppend/__inc 标量编码——业务零 SQL） */
+export declare function compileMergeVal(col: string, v: unknown, params: unknown[], table: string): string;
 export {};

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

@@ -0,0 +1,56 @@
+/**
+ * weifuwu/rest —— restFromShape：shape → RESTful 路由组（纯函数）
+ *
+ * 命名契约（W0）：`restFromShape(shapeDef, opts)` / `orm.rest(Table)` 入口对称
+ * （orm.gql/gqlFromShape 同构）。
+ *
+ * 生成面（W4 首版——分层纪律：协议面 + 样板 handler；业务走 hooks/覆盖）：
+ *   - GET    {base}            list（query 参数：eq 直排 `?col=v` + sort
+ *     `?sort=-created_at,name`（-前缀 desc·逗号多字段）+ limit/offset——
+ *     eq 直排经 filterToWhere 与 gql filter 同核语义）
+ *   - GET    {base}/:id        one（404）
+ *   - POST   {base}            insert（201 + insertSchema 校验 400）
+ *   - PATCH  {base}/:id        update（404/400）
+ *   - DELETE {base}/:id        delete（404/204）
+ *
+ * 内置承诺：
+ *   - query 参数 schema 从 shape 派生（枚举白名单——`?type=robot` → 400 ·
+ *     sort 字段白名单 · limit clamp）
+ *   - 敏感列 fieldPolicy.hidden（SDL/返回双面不出现——与 gql 同策略）
+ *   - 租户 scope：ctx.orm (CtxOrm) 的 ctxTable——与 orm 单源（无独立 tenant
+ *     配置面）
+ *   - hooks 接缝（before/after——权限守卫/响应增强——业务 handler 插点）
+ *
+ * 判负（首版——后续再议）：嵌套资源路由（/dept/:id/members）· 全算子 query
+ * 参数（in/gt/contains——rest 参数 flat 面只 eq 直排——复杂过滤走
+ * orm.table/gql）· 批量/upsert · 自定义错误形状
+ */
+import type { ZodRawShape } from '../../shared/zod.ts';
+import type { Shape } from './shape.ts';
+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;
+}
+export declare function restFromShape<S extends ZodRawShape>(shapeDef: Shape<S>, opts?: RestShapeOptions): RestShapeOutput;

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

@@ -0,0 +1,78 @@
+/**
+ * weifuwu/db — 声明式 Schema（DDL 算子化）
+ *
+ * 业务零 SQL 字符串：表结构 = 声明（ZodRawShape 列 + 表级索引/约束/FK 元数据）→
+ * compileSchemaDDL 在框架内部生成 CREATE/ALTER/INDEX 语句（字符串不外泄）→
+ * pg.runMigration(name, ddl) 执行（幂等记录）· MemorySql.applySchema 直构造元数据。
+ *
+ * 声明来源：列 = shape（类型映射 z.string→TEXT / z.number().int→INT / z.number→DOUBLE
+ * PRECISION / z.boolean→BOOLEAN / z.date→TIMESTAMPTZ / z.uuid→UUID / z.json·z.array·
+ * z.object→JSONB / z.enum→TEXT+CHECK）+ f 修饰（f.pk/f.req/f.now/f.unique/f.default/
+ * f.col）；表级 = TableDecl（复合唯一/refs FK/indexes/columnTypes 注解）。
+ *
+ * 升级路径：每个表产出 CREATE TABLE IF NOT EXISTS（全列——新库）+ 每列
+ * ALTER TABLE ADD COLUMN IF NOT EXISTS（老库增量——幂等）+ CREATE INDEX IF NOT EXISTS。
+ */
+import type { ZodType } from '../../shared/zod.ts';
+import type { DdlQuery } from './query.ts';
+export interface IndexDecl {
+    /** 列（可带 DESC——`{ col: 'created_at', desc: true }`） */
+    cols: (string | {
+        col: string;
+        desc?: boolean;
+    })[];
+    /** 索引名（缺省 idx_<table>_<cols>） */
+    name?: string;
+    unique?: boolean;
+    /** 访问方法（'ivfflat'/'brin'…） */
+    using?: string;
+    /** 操作符类（'vector_cosine_ops'） */
+    opclass?: string;
+    /** WITH 参数文本（'lists = 100'） */
+    with?: string;
+    /** 部分索引条件（AND 等值/不等/IS NULL 面——声明值内联（非用户输入）） */
+    where?: {
+        col: string;
+        eq?: string;
+        ne?: string;
+        isNull?: boolean;
+    }[];
+}
+export interface TableDecl {
+    name: string;
+    columns: Record<string, unknown>;
+    /** 复合唯一组（列级 f.unique 之外） */
+    uniques?: string[][];
+    /** 列 → 外键引用（schema REFERENCES 面；跨边界不声明 refs——应用层保证） */
+    refs?: Record<string, {
+        table: string;
+        col?: string;
+        onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action';
+    }>;
+    /** 列型注解（shape 默认映射外：'FLOAT8'/'vector(1024)'/'BIGSERIAL'/…） */
+    columnTypes?: Record<string, string>;
+    /** CHECK 枚举（非 z.enum 列的 IN 约束：列 → 允许值） */
+    checks?: Record<string, string[]>;
+    /** 老库升级：去掉 NOT NULL（ALTER COLUMN DROP NOT NULL——如 SSO 无密码） */
+    dropNotNull?: string[];
+    indexes?: IndexDecl[];
+}
+export interface EnumDecl {
+    name: string;
+    values: string[];
+}
+export interface SchemaModule {
+    /** 扩展（'vector' 等——CREATE EXTENSION IF NOT EXISTS 前置） */
+    extensions?: string[];
+    /** PG 枚举类型（CREATE TYPE + 值补增——列型用 columnTypes: { col: 'enum名' } 引用） */
+    enums?: EnumDecl[];
+    tables: TableDecl[];
+}
+export declare function zodTypeOf(t: ZodType): string;
+export declare function enumValuesOf(t: ZodType): string[] | undefined;
+/** 声明模块 → DDL AST（封闭面：memory executeDdl 直执行——零 parse） */
+export declare function compileSchemaDdl(mod: SchemaModule): DdlQuery[];
+/** DDL AST → SQL（真库单向输出——封闭：AST 永远是输入，SQL 只有流出） */
+export declare function ddlToSql(stmts: DdlQuery[]): string;
+/** @deprecated 兼容面——W3 删除；真库面统一 ddlToSql(compileSchemaDdl(mod)) */
+export declare function compileSchemaDDL(mod: SchemaModule): string;

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

@@ -26,5 +26,3 @@ export interface DBServer {
 }
 export { MemoryRedisServer } from './redis-server.ts';
 export type { RedisServerOptions } from './redis-server.ts';
-export { MemoryPostgresServer } from './postgres-server.ts';
-export type { PostgresServerOptions } from './postgres-server.ts';

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

@@ -0,0 +1,131 @@
+/**
+ * weifuwu/shape —— 形状层（shape+operator 架构的形状基座）
+ *
+ * shape = zod schema（数据形状单源）+ db 元数据（meta——表/列语义）
+ * 派生面（与 zod 天然——零生成）：
+ *   - 校验：shape.parse（API 边界）
+ *   - 类型：z.infer
+ *   - 变体：insertSchema/updateSchema（省略自动列）
+ *   - db 元数据：dbMeta（建表/算子类型收窄——后续 W3 消费）
+ *
+ * 用法：
+ *   const Agent = shape({
+ *     table: 'agents',
+ *     fields: {
+ *       id: z.uuid().meta({ pk: true, default: 'random' }),
+ *       appId: z.string().meta({ column: 'app_id', notNull: true }),
+ *       type: z.enum(['ai','user','webhook']).meta({ notNull: true }),
+ *       name: z.string().meta({ notNull: true }),
+ *       createdAt: z.date().meta({ column: 'created_at', default: 'now' }),
+ *     },
+ *   })
+ */
+import { type ZodType, type Infer, type ZodRawShape, type ZodMeta } from '../../shared/zod.ts';
+/** meta 类型保留面：withMeta 返回交叉（meta 字面量类型不坍缩——BodyOf 推导的根基） */
+export type WithMeta<T extends ZodType, M extends ZodMeta> = T & {
+    metaInfo: M & ZodMeta;
+};
+/** auto 字段（DB 侧生成——insert/update 时省略：default 'random'/'now'）——从 meta 字面量推导 */
+export type AutoFieldOf<S extends ZodRawShape> = {
+    [K in keyof S]: S[K] extends {
+        metaInfo: infer M;
+    } ? (M extends {
+        default: infer D;
+    } ? (D extends 'random' | 'now' ? K : never) : never) : never;
+}[keyof S];
+/** insert 输入行类型（省略 auto 列——字段精确·全字段键级可选——
+ * required/optional 精确性由运行时权威（insertSchema 校验）承载——字段名/
+ * 值类型/枚举编译期精确（核心价值）） */
+export type BodyOf<S extends ZodRawShape> = {
+    [K in keyof S as K extends AutoFieldOf<S> ? never : K]?: Infer<S[K]>;
+};
+/** update/patch 输入行类型（省略 auto 列 · 全字段可缺省——与 updateSchema 运行时一致） */
+type PatchValueOf<T extends ZodType> = T extends ZodType<infer Out> ? Out : never;
+export type PatchOf<S extends ZodRawShape> = {
+    [K in keyof S as K extends AutoFieldOf<S> ? never : K]?: PatchValueOf<S[K]>;
+};
+/** 字段级 db 元数据（shape 层语义——建表/算子/校验收窄的驱动面） */
+export interface FieldDbMeta extends ZodMeta {
+    /** 列名（默认 = 字段名） */
+    column?: string;
+    /** 主键 */
+    pk?: boolean;
+    /** 唯一 */
+    unique?: boolean;
+    /** NOT NULL（校验面 optional 之外——DB 层约束） */
+    notNull?: boolean;
+    /** 默认值（'random'=gen_random_uuid · 'now'=NOW() · 字面量（string/number/boolean）） */
+    default?: 'random' | 'now' | string | number | boolean;
+    /** 外键（references 表.列——关系面） */
+    references?: string;
+    /** 级联（ON DELETE） */
+    onDelete?: 'cascade' | 'set null' | 'restrict';
+}
+export interface DbField {
+    name: string;
+    schema: ZodType;
+    meta: FieldDbMeta;
+    /** 输出类型（z.infer 快捷） */
+    type: unknown;
+}
+/** 形状（表级） */
+export interface Shape<S extends ZodRawShape = ZodRawShape> {
+    /** 表/集合名 */
+    table: string;
+    /** 字段表（原始 zod shape） */
+    fields: S;
+    /** 字段元数据展平（name → FieldDbMeta） */
+    dbFields: Record<string, FieldDbMeta>;
+    /** 主键字段名（pk meta） */
+    pkField?: string;
+    /** infers */
+    output: {
+        [K in keyof S]: Infer<S[K]>;
+    };
+    /** 插入变体（省略 auto 列：pk+random/now 默认——类型面 = 输入行 BodyOf） */
+    insertSchema(opts?: {
+        omit?: string[];
+    }): ZodType<BodyOf<S>>;
+    /** 字段名 → 列名翻译（写入面：shape 字段名 → db 列名） */
+    toDb(record: object): Record<string, unknown>;
+    /** 列名 → 字段名翻译（读取面：db 行 → shape 字段名——GraphQL/API 输出） */
+    fromDb(record: object): Record<string, unknown>;
+    /** 更新变体（全字段 optional——部分更新面——类型面 = PatchOf） */
+    updateSchema(opts?: {
+        omit?: string[];
+    }): ZodType<PatchOf<S>>;
+}
+export declare function shape<S extends ZodRawShape>(def: {
+    table: string;
+    fields: S;
+}): Shape<S>;
+/** 字段 meta 快捷方法（shape 定义侧手感的统一入口） */
+export declare const f: {
+    /** 主键（random uuid 默认） */
+    pk: <T extends ZodType>(t: T) => WithMeta<T, {
+        pk: true;
+        default: "random";
+    }>;
+    /** NOT NULL */
+    req: <T extends ZodType>(t: T) => WithMeta<T, {
+        notNull: true;
+    }>;
+    /** 列名映射 */
+    col: <T extends ZodType>(t: T, column: string) => WithMeta<T, {
+        column: string;
+    }>;
+    /** 默认 now */
+    now: <T extends ZodType>(t: T) => WithMeta<T, {
+        default: "now";
+    }>;
+    /** 唯一 */
+    unique: <T extends ZodType>(t: T) => WithMeta<T, {
+        unique: true;
+    }>;
+    /** 字面量默认值（DB 侧默认——body 可缺省——meta 类型保留；值域任意字面量（jsonb
+     *  默认 [] 等）——default 值的语义由 shape/DDL 面消费（string/number/boolean 主流）） */
+    dflt: <T extends ZodType, V>(t: T, v: V) => WithMeta<T, {
+        default: V;
+    }>;
+};
+export {};