weifuwu 0.94.0 → 0.95.0

package/dist/level0/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 '../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 {};

package/dist/level0/db/shape.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 { z, type ZodType, type Infer, type ZodRawShape, type ZodMeta, ZodOptional, ZodNullable, ZodDefault } from '../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]
+
+/** body 字段是否可缺省（nullable/optional/default 包装或 meta default 键——对齐 insertSchema 规则） */
+type IsBodyOptional<T extends ZodType> = T extends ZodOptional<any>
+  ? true
+  : T extends ZodNullable<any>
+    ? true
+    : T extends ZodDefault<any, any>
+      ? true
+      : T extends { metaInfo: infer M }
+        ? (M extends { default: unknown } ? true : false)
+        : false
+
+/** 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>>
+}
+
+/** DB 字段 meta 装饰快捷（zod schema 上挂 meta——db 列语义） */
+function withMeta<T extends ZodType, M extends ZodMeta>(t: T, m: M): WithMeta<T, M> {
+  return t.meta(m) as WithMeta<T, M>
+}
+
+export function shape<S extends ZodRawShape>(def: {
+  table: string
+  fields: S
+}): Shape<S> {
+  const dbFields: Record<string, FieldDbMeta> = {}
+  let pkField: string | undefined
+  for (const [name, schema] of Object.entries(def.fields)) {
+    const m = (schema.metaInfo ?? {}) as FieldDbMeta
+    dbFields[name] = {
+      column: m.column ?? name,
+      ...(m.pk ? { pk: true } : {}),
+      ...(m.unique ? { unique: true } : {}),
+      ...(m.notNull ? { notNull: true } : {}),
+      ...(m.default !== undefined ? { default: m.default } : {}),
+      ...(m.references ? { references: m.references } : {}),
+      ...(m.onDelete ? { onDelete: m.onDelete } : {}),
+    }
+    if (m.pk) pkField = name
+  }
+  const sig = { table: def.table, fields: def.fields, dbFields, pkField } as Shape<S>
+  // 变体派生：insert = omit(auto 字段（pk+random/now 默认——DB 侧生成））
+  // update = 全字段 optional（部分更新面——null 与缺失区分由调用边界）
+  // auto 列 = 默认值 DB 侧生成（random/now——insert/update 时省略——不论是否 pk）
+  const isAuto = (name: string): boolean => {
+    const m = dbFields[name]
+    return m?.default === 'random' || m?.default === 'now'
+  }
+  ;(sig as unknown as { insertSchema: (o?: { omit?: string[] }) => ZodType<BodyOf<S>> }).insertSchema = (o = {}) => {
+    const entries: Record<string, unknown> = {}
+    for (const [name, field] of Object.entries(def.fields)) {
+      if (isAuto(name)) continue
+      // W4：系统列 omit（租户/服务端注入面——不校验不要求——注入面权威）
+      if (o.omit?.includes(name)) continue
+      // DB 侧默认值列（default 显式存在）→ 可缺省（省略走 DB 默认）
+      // nullable 列 → 可缺省（键缺 = DB NULL——nullable 语义即可选）
+      const v = field as ZodType
+      const isNullable = (v as { _typeName?: () => string })._typeName?.() === 'nullable'
+      entries[name] = dbFields[name]?.default !== undefined || isNullable ? v.optional() : v
+    }
+    return cleanUndefined(z.object(entries as S)) as unknown as ZodType<BodyOf<S>>
+  }
+  ;(sig as unknown as { toDb: (r: object) => Record<string, unknown> }).toDb = (record: object) => {
+    const out: Record<string, unknown> = {}
+    const rec = record as Record<string, unknown>
+    for (const [k, v] of Object.entries(rec)) {
+      const meta = dbFields[k]
+      out[meta?.column ?? k] = v
+    }
+    return out
+  }
+  ;(sig as unknown as { fromDb: (r: object) => Record<string, unknown> }).fromDb = (record: object) => {
+    const out: Record<string, unknown> = {}
+    const rec = record as Record<string, unknown>
+    for (const [name, meta] of Object.entries(dbFields)) {
+      if (rec[(meta as FieldDbMeta).column ?? name] !== undefined) out[name] = rec[(meta as FieldDbMeta).column ?? name]
+    }
+    // 未映射列（select 额外列如 member_count）原键保留——join/聚合面不丢
+    for (const k of Object.keys(rec)) {
+      const mapped = Object.values(dbFields).some((m) => (m as FieldDbMeta).column === k)
+      if (!mapped && !(k in out)) out[k] = rec[k]
+    }
+    return out
+  }
+  ;(sig as unknown as { updateSchema: (o?: { omit?: string[] }) => ZodType<PatchOf<S>> }).updateSchema = (o = {}) => {
+    const optionalized: Record<string, ZodType> = {}
+    for (const [name, s] of Object.entries(def.fields)) {
+      if (isAuto(name)) continue
+      if (o.omit?.includes(name)) continue
+      optionalized[name] = (s as ZodType).optional()
+    }
+    return cleanUndefined(z.object(optionalized)) as unknown as ZodType<PatchOf<S>>
+  }
+  return sig
+}
+
+/** 变体 parse 产物清洗：undefined 键删除（optional 缺省——不产生写入面 null 污染） */
+function cleanUndefined<T extends import('../zod.ts').ZodType>(t: T): T {
+  return t.transform((v: unknown) => {
+    if (typeof v !== 'object' || v === null) return v
+    return Object.fromEntries(Object.entries(v as Record<string, unknown>).filter(([, x]) => x !== undefined))
+  }) as unknown as T
+}
+
+/** 字段 meta 快捷方法（shape 定义侧手感的统一入口） */
+export const f = {
+  /** 主键（random uuid 默认） */
+  pk: <T extends ZodType>(t: T): WithMeta<T, { pk: true; default: 'random' }> => withMeta(t, { pk: true, default: 'random' }),
+  /** NOT NULL */
+  req: <T extends ZodType>(t: T): WithMeta<T, { notNull: true }> => withMeta(t, { notNull: true }),
+  /** 列名映射 */
+  col: <T extends ZodType>(t: T, column: string): WithMeta<T, { column: string }> => withMeta(t, { column }),
+  /** 默认 now */
+  now: <T extends ZodType>(t: T): WithMeta<T, { default: 'now' }> => withMeta(t, { default: 'now' }),
+  /** 唯一 */
+  unique: <T extends ZodType>(t: T): WithMeta<T, { unique: true }> => 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 }> => withMeta(t, { default: v }),
+}

package/dist/level0/router/chain.ts

@@ -0,0 +1,30 @@
+/**
+ * 中间件链执行（SHARED-TRIE-EXCELLENCE B0——2027-10 自 server/core/chain.ts
+ * 移入 shared——**前端获得 middleware 能力**（机制就位——路由内核
+ * dispatchRouter 的 resolveHandler 钩子消费））
+ *
+ * next() 重复调用守卫在案（called 标志——server 路由测试锁定 500 语义）。
+ */
+import type { SharedHandler, SharedMiddleware } from './types.ts'
+
+export async function runChain<TCtx>(
+  mws: SharedMiddleware<TCtx>[],
+  finalHandler: SharedHandler<TCtx>,
+  req: Request,
+  ctx: TCtx,
+): Promise<Response> {
+  if (mws.length === 0) return finalHandler(req, ctx)
+  let i = 0
+  const dispatch: SharedHandler<TCtx> = (r, c) => {
+    if (i >= mws.length) return Promise.resolve(finalHandler(r, c))
+    const mw = mws[i++]
+    let called = false
+    const next: SharedHandler<TCtx> = (r2, c2) => {
+      if (called) throw new Error('[router] next() called more than once in middleware')
+      called = true
+      return dispatch(r2, c2)
+    }
+    return Promise.resolve(mw(r, c, next))
+  }
+  return dispatch(req, ctx)
+}

package/dist/level0/router/context.ts

@@ -0,0 +1,67 @@
+/**
+ * 请求目标解析 + ctx 注入纯函数（SHARED-TRIE-EXCELLENCE B1——2027-10）
+ *
+ * **双端重复面收敛**（盘点实证：URL→segments 三处重复、query 注入
+ * 双端同式、params fresh 语义等价实现分散）——单一实现源：
+ * - server：handler() / serve.ts createRequest
+ * - client：UIRouter.resolve / has
+ *
+ * **URIError 防御双端统一**：param 段 decodeURIComponent 对非法编码
+ * （%zz）抛 URIError——非法编码 URL 是客户端错误 → 400 信号
+ * （server C3 修复迁移至此——client 同享——双端 400 语义一致）。
+ */
+
+/** 解析结果——ok=false 时 reason 分类（400 响应由调用方构造） */
+export type RequestTarget =
+  | { ok: true; segments: string[]; pathname: string; query: Record<string, string> }
+  | { ok: false; reason: 'malformed-encoding' | 'invalid-url' }
+
+/**
+ * Request → 匹配输入（segments/pathname/query 一次拿全——零二次解析）。
+ * URIError（非法 percent-encoding）→ { ok: false, reason: 'malformed-encoding' }
+ * ——**不抛出**（调用方按 400 分类——双端统一语义）。
+ */
+export function parseRequestTarget(req: Request): RequestTarget {
+  let url: URL
+  try {
+    url = new URL(req.url)
+  } catch {
+    return { ok: false, reason: 'invalid-url' }
+  }
+  const query = parseQuery(url)
+  // **param 段 decode 的 URIError 提前捕获**：trieMatch 内 exactDfs 对
+  // param 槽 decodeURIComponent——非法编码在此暴露（pathname 预检）
+  try {
+    decodeURI(url.pathname)
+  } catch {
+    return { ok: false, reason: 'malformed-encoding' }
+  }
+  // 段级检测（%zz 在段中——decodeURI 不抛（只检保留字），段 decode 才抛
+  // ——逐段预检与 exactDfs 的 decodeURIComponent 行为对齐）
+  for (const seg of splitSegments(url.pathname)) {
+    try {
+      decodeURIComponent(seg)
+    } catch {
+      return { ok: false, reason: 'malformed-encoding' }
+    }
+  }
+  return { ok: true, segments: splitSegments(url.pathname), pathname: url.pathname, query }
+}
+
+/** 路径分段（trie splitPath 同源逻辑——空段过滤） */
+function splitSegments(pathname: string): string[] {
+  return pathname.split('/').filter(Boolean)
+}
+
+/** fresh params（match.params 克隆——**不残留旧路由键**——client 契约
+ *  语义（params 每次渲染替换）单一实现源） */
+export function freshParams(
+  match?: { params: Record<string, string> } | null,
+): Record<string, string> {
+  return match ? { ...match.params } : {}
+}
+
+/** query 提取（Object.fromEntries(searchParams)——双端同一实现源） */
+export function parseQuery(url: URL): Record<string, string> {
+  return Object.fromEntries(url.searchParams)
+}

package/dist/level0/router/ctx-fields.ts

@@ -0,0 +1,42 @@
+/**
+ * ctx 字段注册表（SHARED-TRIE-EXCELLENCE B0'——2027-10）
+ *
+ * **ctx 扩展机制双端统一**（用户论证：「前后端都是通过扩展 ctx.xxx
+ * 提供新能力，只是扩展的能力不一样」）——middleware 声明 injects（注入
+ * 字段）/depends（依赖字段）——依赖未注册抛错（含注册引导文案）。
+ *
+ * - server：Router._checkMiddlewareMeta 迁移消费（行为零变化——
+ *   global/route/mount 三位置检查语义保留）
+ * - client：获得同一机制（UIContext declare module 类型增强的运行时
+ *   对应——未来前端中间件声明 injects 同样受检）——类型/运行时双层对齐
+ */
+
+export interface CtxFieldRegistry {
+  /** 登记注入字段（injects——provider 中间件先行注册） */
+  register(injects: string[]): void
+  /** 依赖检查（depends——未注册抛错，含 app.use(xxx()) 引导） */
+  check(depends: string[], location: string): void
+  has(field: string): boolean
+}
+
+export function createCtxFieldRegistry(): CtxFieldRegistry {
+  const fields = new Set<string>()
+  return {
+    register(injects: string[]) {
+      for (const f of injects) fields.add(f)
+    },
+    check(depends: string[], location: string) {
+      for (const dep of depends) {
+        if (!fields.has(dep)) {
+          throw new Error(
+            `[weifuwu] Middleware at "${location}" depends on ctx.${dep} but it hasn't been registered.\n` +
+            `  Register the provider before this middleware: app.use(${dep}())`,
+          )
+        }
+      }
+    },
+    has(field: string) {
+      return fields.has(field)
+    },
+  }
+}

package/dist/level0/router/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * weifuwu/shared/router — 前后端唯一共享模块（trie/pipeline/context/chain/ctx-fields）
+ *
+ * 五件单源：URL 路由匹配（trie）· 请求→响应管道（pipeline）· 上下文组装（context）·
+ * 链式执行（chain）· 上下文字段注册表（ctx-fields）——前后端同一实现
+ * （server Router / client UIRouter 消费——src 相对引用 + dist 导出双通道）。
+ */
+export { createTrie } from './trie.ts';
+export type { TrieNode } from './trie.ts';
+export { dispatchRouter } from './pipeline.ts';
+export type { RouterPipeline, RouteMatch } from './pipeline.ts';
+export { parseRequestTarget } from './context.ts';
+export type { RequestTarget } from './context.ts';
+export { createCtxFieldRegistry } from './ctx-fields.ts';
+export type { CtxFieldRegistry } from './ctx-fields.ts';
+export { runChain } from './chain.ts';
+export { freshParams, parseQuery } from './context.ts';

package/dist/level0/router/index.js

@@ -0,0 +1,2 @@
+function x(){return{children:new Map}}function d(r,e,t,n,o="value"){if(t===e.length){let s=o==="value"?r.value:r.wildcardValue;return s!==void 0?{value:s,params:{...n},node:r}:null}let i=e[t],l=r.children.get(i);if(l){let s=d(l,e,t+1,n,o);if(s)return s}let a=r.children.get(":");if(a?.param){let s={...n,[a.param]:decodeURIComponent(i)},u=d(a,e,t+1,s,o);if(u)return u}return null}function f(r,e){let t=d(r,e,0,{});if(t){let n=t.node.wildcardValue!==void 0;return{value:t.value,params:n?{...t.params,"*":""}:t.params,wildcard:!1}}return w(r,e,e.length)}function w(r,e,t){for(let n=0;n<=t;n++){let o=d(r,e.slice(0,n),0,{},"wildcard");if(o)return{value:o.value,params:{...o.params,"*":e.slice(n).join("/")},wildcard:!0}}return null}function c(r){let e;try{e=new URL(r.url)}catch{return{ok:!1,reason:"invalid-url"}}let t=T(e);try{decodeURI(e.pathname)}catch{return{ok:!1,reason:"malformed-encoding"}}for(let n of h(e.pathname))try{decodeURIComponent(n)}catch{return{ok:!1,reason:"malformed-encoding"}}return{ok:!0,segments:h(e.pathname),pathname:e.pathname,query:t}}function h(r){return r.split("/").filter(Boolean)}function p(r){return r?{...r.params}:{}}function T(r){return Object.fromEntries(r.searchParams)}function C(r){return Response.json({error:"Bad Request",reason:r},{status:400})}async function v(r,e,t,n){let o=c(t);if(!o.ok)return C(o.reason);let i=f(r,o.segments),l=i?{value:i.value,params:p(i),wildcard:i.wildcard}:null;e.enrichCtx?.(n,l,o.pathname,o.query);try{if(!l)return await e.onNotFound(t,n,o.pathname);let a=e.resolveHandler(l,t,n);if(a.kind==="not-found")return await e.onNotFound(t,n,o.pathname);if(a.kind==="not-allowed")return e.onMethodNotAllowed?await e.onMethodNotAllowed(a.methods,t,n,o.pathname):new Response("Method Not Allowed",{status:405,headers:{Allow:a.methods.join(", ")}});let s=await a.run();return e.onRouteSuccess?.(t,n,o.pathname),s}catch(a){if(e.onError)return e.onError(a,t,n,o.pathname);throw a}}function N(){let r=new Set;return{register(e){for(let t of e)r.add(t)},check(e,t){for(let n of e)if(!r.has(n))throw new Error(`[weifuwu] Middleware at "${t}" depends on ctx.${n} but it hasn't been registered.
+  Register the provider before this middleware: app.use(${n}())`)},has(e){return r.has(e)}}}async function y(r,e,t,n){if(r.length===0)return e(t,n);let o=0,i=(l,a)=>{if(o>=r.length)return Promise.resolve(e(l,a));let s=r[o++],u=!1,g=(m,R)=>{if(u)throw new Error("[router] next() called more than once in middleware");return u=!0,i(m,R)};return Promise.resolve(s(l,a,g))};return i(t,n)}export{N as createCtxFieldRegistry,x as createTrie,v as dispatchRouter,p as freshParams,T as parseQuery,c as parseRequestTarget,y as runChain};

package/dist/level0/router/index.ts

@@ -0,0 +1,17 @@
+/**
+ * weifuwu/shared/router — 前后端唯一共享模块（trie/pipeline/context/chain/ctx-fields）
+ *
+ * 五件单源：URL 路由匹配（trie）· 请求→响应管道（pipeline）· 上下文组装（context）·
+ * 链式执行（chain）· 上下文字段注册表（ctx-fields）——前后端同一实现
+ * （server Router / client UIRouter 消费——src 相对引用 + dist 导出双通道）。
+ */
+export { createTrie } from './trie.ts'
+export type { TrieNode } from './trie.ts'
+export { dispatchRouter } from './pipeline.ts'
+export type { RouterPipeline, RouteMatch } from './pipeline.ts'
+export { parseRequestTarget } from './context.ts'
+export type { RequestTarget } from './context.ts'
+export { createCtxFieldRegistry } from './ctx-fields.ts'
+export type { CtxFieldRegistry } from './ctx-fields.ts'
+export { runChain } from './chain.ts'
+export { freshParams, parseQuery } from './context.ts'

package/dist/level0/router/pipeline.ts

@@ -0,0 +1,130 @@
+/**
+ * 路由内核——流程骨架 + 差异钩子（SHARED-TRIE-EXCELLENCE B0——2027-10）
+ *
+ * **机制公用、实现不一样**（用户论证采纳——handler 签名双端同构 +
+ * 流程 6 步中 3 步完全同构、3 步是差异点而非不同流程）：
+ *
+ * ```
+ * dispatchRouter 流程骨架（单一实现源——改一处双端生效）：
+ *   1. parseRequestTarget（URIError → 400 信号——双端统一防御）
+ *   2. trieMatch（shared Trie——静态/param/通配——回溯语义在案）
+ *   3. enrichCtx（ctx 扩展——机制一致能力不同）
+ *   4. resolveHandler（verb 差异点：server method 表 / client 直调）
+ *   5. run → onRouteSuccess（恢复清出）| catch → onError
+ *   6. 404/405 兜底（形态差异钩子化）
+ * ```
+ *
+ * **双端类 API 零变化**：Router.handler() / UIRouter.resolve() 内部
+ * 换 dispatchRouter——405/Allow/去重收敛 serverPipeline；route 注入/
+ * 前端 404 收敛 clientPipeline；serve（Request/Response 编解码边界）
+ * 留双端——pipeline 不关心。
+ */
+import { trieMatch, type TrieNode } from './trie.ts'
+import { parseRequestTarget, freshParams } from './context.ts'
+
+/** 匹配结果（trieMatch 返回 + verb 分类的输入载荷） */
+export interface RouteMatch<TValue> {
+  value: TValue
+  params: Record<string, string>
+  wildcard: boolean
+}
+
+export interface RouterPipeline<TValue, TCtx> {
+  /**
+   * **verb 差异点**（负载 → 实际执行闭包）：
+   * - server：value 是 method 表——method 查找 + HEAD fallback（mw 联动）
+   *   + 405 分类 + runChain 链组装（globalMws + routeMws）
+   * - client：value 是 PageHandler——直调闭包
+   */
+  resolveHandler(
+    m: RouteMatch<TValue>, req: Request, ctx: TCtx,
+  ):
+    | { kind: 'route'; run: () => Response | Promise<Response> }
+    /** method 表分类（405 Allow 头）——server 独有 */
+    | { kind: 'not-allowed'; methods: string[] }
+    /** 通配命中但 method 落空 → 404（通配不产生 405——探针实证锁死） */
+    | { kind: 'not-found' }
+
+  /** 404 兜底（server: JSON + globalMws 链；client: notFound ?? null body） */
+  onNotFound(req: Request, ctx: TCtx, path: string): Response | Promise<Response>
+
+  /** 405 兜底（server 实现——globalMws 链 + Allow 头；client 不实现） */
+  onMethodNotAllowed?(
+    methods: string[], req: Request, ctx: TCtx, path: string,
+  ): Response | Promise<Response>
+
+  /** 错误语义（server: onError 优先/HttpError/去重计数；client 可缺省直抛） */
+  onError?(e: unknown, req: Request, ctx: TCtx, path: string): Response | Promise<Response>
+
+  /** 路由成功完成（server: 恢复清出错误状态——再错再报；client 可缺省） */
+  onRouteSuccess?(req: Request, ctx: TCtx, path: string): void
+
+  /**
+   * **ctx 扩展钩子**（机制一致能力不同）：
+   * - server：params merge 进既有 ctx.params（Object.assign 语义）
+   * - client：params fresh + query + ctx.route 三面注入
+   * - 404（m null）时也执行——client notFound handler 收到空 params +
+   *   query + route（原语义精确保留）
+   */
+  enrichCtx?(
+    ctx: TCtx, m: RouteMatch<TValue> | null, pathname: string, query: Record<string, string>,
+  ): void
+}
+
+/** 400 响应（URIError 信号统一形态——双端一致） */
+function badRequest(reason: string): Response {
+  return Response.json({ error: 'Bad Request', reason }, { status: 400 })
+}
+
+/**
+ * **路由分发流程骨架**——双端 Router 的内核（机制公用、实现不一样）。
+ * 差异全部在 pipeline 钩子——骨架只编排顺序与错误边界。
+ */
+export async function dispatchRouter<TValue, TCtx>(
+  root: TrieNode<TValue>,
+  pipeline: RouterPipeline<TValue, TCtx>,
+  req: Request,
+  ctx: TCtx,
+): Promise<Response> {
+  // 1. 解析（非法编码/非法 URL → 400 信号——双端统一防御）
+  const target = parseRequestTarget(req)
+  if (!target.ok) return badRequest(target.reason)
+
+  // 2. Trie 匹配（静态/param 回溯/通配兜底——语义在 trie.ts）
+  const m = trieMatch(root, target.segments)
+  const match: RouteMatch<TValue> | null = m
+    ? { value: m.value, params: freshParams(m), wildcard: m.wildcard }
+    : null
+
+  // 3. ctx 扩展（enrichCtx 恒执行——404 时也注入——client notFound 语义保留）
+  pipeline.enrichCtx?.(ctx, match, target.pathname, target.query)
+
+  try {
+    // 4. 无匹配 → 404 兜底
+    if (!match) return await pipeline.onNotFound(req, ctx, target.pathname)
+
+    // 5. verb 差异点（负载 → 执行闭包）
+    const resolved = pipeline.resolveHandler(match, req, ctx)
+    if (resolved.kind === 'not-found') {
+      return await pipeline.onNotFound(req, ctx, target.pathname)
+    }
+    if (resolved.kind === 'not-allowed') {
+      if (pipeline.onMethodNotAllowed) {
+        return await pipeline.onMethodNotAllowed(resolved.methods, req, ctx, target.pathname)
+      }
+      return new Response('Method Not Allowed', {
+        status: 405,
+        headers: { Allow: resolved.methods.join(', ') },
+      })
+    }
+
+    // 6. 执行 + 成功钩子
+    const res = await resolved.run()
+    pipeline.onRouteSuccess?.(req, ctx, target.pathname)
+    return res
+  } catch (e) {
+    // 错误边界（onError 缺省时直抛——serve 层兜底）
+    if (pipeline.onError) return pipeline.onError(e, req, ctx, target.pathname)
+    throw e
+  }
+}