@lynx-go/ui-kit 0.0.0-stage → 0.1.0

package/src/adapters/transport.ts

@@ -0,0 +1,262 @@
+import type { ApiError, Cursor, FrameSource, Transport } from "../kernel";
+
+/**
+ * 通用传输适配器（kernel Transport 契约 → fetch 流）。
+ *
+ * 终态分诊裁决落点（design.md §2.3）：NDJSON-over-fetch 的"收流"与"中断"
+ * 在传输层不可严格区分——真终态判据是帧内容，由消费方经 isEnded 上报；
+ * body 结束而不满足 isEnded ⇒ 抛错（引擎按退避重连）。SSE 同理：具名 endEvent
+ * 是唯一"服务端收流"判据，连接断开一律按传输中断处理。
+ * 票据/base64/protojson 的帧解码归消费方（decode 参数）。
+ */
+
+type UrlBuilder = string | ((cursor: Cursor | null) => string);
+
+function buildUrl(url: UrlBuilder, cursor: Cursor | null): string {
+  if (typeof url === "function") return url(cursor);
+  if (cursor === null) return url;
+  const join = url.includes("?") ? "&" : "?";
+  return `${url}${join}cursor=${encodeURIComponent(cursor)}`;
+}
+
+async function fetchOrApiError(
+  url: string,
+  init: RequestInit,
+  fetchImpl: typeof fetch,
+): Promise<Response> {
+  let response: Response;
+  try {
+    response = await fetchImpl(url, init);
+  } catch (cause) {
+    throw { kind: "network", cause } satisfies ApiError;
+  }
+  if (!response.ok) {
+    if (response.status === 401) throw { kind: "auth" } satisfies ApiError;
+    if (response.status === 403) throw { kind: "forbidden" } satisfies ApiError;
+    if (response.status === 404) throw { kind: "not-found" } satisfies ApiError;
+    let message: string | undefined;
+    try {
+      const body = (await response.json()) as { message?: unknown; error?: { message?: unknown } };
+      if (typeof body.message === "string") message = body.message;
+      else if (typeof body.error?.message === "string") message = body.error.message;
+    } catch {
+      // 非 JSON 错误体
+    }
+    throw {
+      kind: "server",
+      status: response.status,
+      ...(message ? { message } : {}),
+    } satisfies ApiError;
+  }
+  return response;
+}
+
+class TransportInterrupt extends Error {
+  constructor(detail: string) {
+    super(`fleet-ui: transport interrupted (${detail})`);
+  }
+}
+
+function releaseReader(reader: ReadableStreamDefaultReader<Uint8Array>): void {
+  try {
+    reader.releaseLock();
+  } catch {
+    // 流已出错/关闭——无需解锁
+  }
+}
+
+/** 收流即取消（含释放锁）；已结束/已中断的流上 cancel 可能拒绝，静默。 */
+async function cancelReader(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void> {
+  try {
+    await reader.cancel();
+  } catch {
+    releaseReader(reader);
+  }
+}
+
+// ============ ndjsonTransport（fleetly 日志流方言） ============
+
+export interface NdjsonTransportOptions<F> {
+  url: UrlBuilder;
+  /** 缺省 JSON.parse；票据/base64/protojson 行解码在消费方 */
+  decode?: (line: string) => F;
+  /** fetch 注入（测试/demo）；缺省 globalThis.fetch */
+  fetchImpl?: typeof fetch;
+  headers?: Record<string, string>;
+  /**
+   * 收流判据：body 正常结束且最后一帧满足 ⇒ closeReason "ended"（部署终态、日志关窗）；
+   * 缺省恒 false——body 结束一律按传输中断（引擎重连）。
+   */
+  isEnded?: (lastFrame: F) => boolean;
+}
+
+export function ndjsonTransport<F>(options: NdjsonTransportOptions<F>): Transport<F> {
+  const decode = options.decode ?? ((line: string) => JSON.parse(line) as F);
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  return {
+    open(cursor: Cursor | null, signal: AbortSignal): FrameSource<F> {
+      let closeReason: FrameSource<F>["closeReason"] = "transport";
+
+      const self = {
+        get closeReason() {
+          return closeReason;
+        },
+        async *[Symbol.asyncIterator](): AsyncIterator<F> {
+          const response = await fetchOrApiError(
+            buildUrl(options.url, cursor),
+            { headers: options.headers, signal },
+            fetchImpl,
+          );
+          if (response.body === null) throw new TransportInterrupt("no body");
+          const reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          let buffer = "";
+          let lastFrame: F | undefined;
+          try {
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              buffer += decoder.decode(value, { stream: true });
+              let newline = buffer.indexOf("\n");
+              while (newline >= 0) {
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (line.length > 0) {
+                  lastFrame = decode(line);
+                  yield lastFrame;
+                }
+                newline = buffer.indexOf("\n");
+              }
+            }
+            const tail = (buffer + decoder.decode()).trim();
+            if (tail.length > 0) {
+              lastFrame = decode(tail);
+              yield lastFrame;
+            }
+          } finally {
+            await cancelReader(reader);
+          }
+          // body 结束：真终态判据是帧内容（§2.3 裁决），否则按中断抛错交引擎重连
+          if (lastFrame !== undefined && options.isEnded?.(lastFrame) === true) {
+            closeReason = "ended";
+            return;
+          }
+          throw new TransportInterrupt("ndjson body ended without end frame");
+        },
+      };
+      return self;
+    },
+  };
+}
+
+// ============ sseTransport（具名事件方言） ============
+
+export interface SseMessage {
+  event: string;
+  data: string;
+  /** 最后一次 id: 字段——SSE 的原生续订游标 */
+  id?: string;
+}
+
+export interface SseTransportOptions<F> {
+  url: UrlBuilder;
+  /** 缺省 JSON.parse(data)；消费方可按 event 分派类型化帧 */
+  decode?: (message: SseMessage) => F;
+  fetchImpl?: typeof fetch;
+  headers?: Record<string, string>;
+  /** 收流判据：收到该具名事件 ⇒ closeReason "ended"；缺省无（断开一律重连） */
+  endEvent?: string;
+}
+
+export function sseTransport<F>(options: SseTransportOptions<F>): Transport<F> {
+  const decode =
+    options.decode ?? ((message: SseMessage) => JSON.parse(message.data) as unknown as F);
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  return {
+    open(cursor: Cursor | null, signal: AbortSignal): FrameSource<F> {
+      let closeReason: FrameSource<F>["closeReason"] = "transport";
+
+      const self = {
+        get closeReason() {
+          return closeReason;
+        },
+        async *[Symbol.asyncIterator](): AsyncIterator<F> {
+          const response = await fetchOrApiError(
+            buildUrl(options.url, cursor),
+            { headers: { Accept: "text/event-stream", ...options.headers }, signal },
+            fetchImpl,
+          );
+          if (response.body === null) throw new TransportInterrupt("no body");
+          const reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          let buffer = "";
+          let ended = false;
+
+          /** 解析一个 SSE 块（行集合）；endEvent 命中时置 ended。 */
+          const dispatch = (block: string, out: F[]): void => {
+            const message: SseMessage = { event: "message", data: "" };
+            const dataLines: string[] = [];
+            for (const rawLine of block.split("\n")) {
+              const line = rawLine.replace(/\r$/, "");
+              if (line === "" || line.startsWith(":")) continue;
+              const colon = line.indexOf(":");
+              const field = colon < 0 ? line : line.slice(0, colon);
+              let value = colon < 0 ? "" : line.slice(colon + 1);
+              if (value.startsWith(" ")) value = value.slice(1);
+              if (field === "data") dataLines.push(value);
+              else if (field === "event") message.event = value;
+              else if (field === "id") message.id = value;
+            }
+            if (options.endEvent !== undefined && message.event === options.endEvent) {
+              ended = true; // 无 data 载荷的收流事件也成立（endEvent 判定先于 data 必有检查）
+              return;
+            }
+            if (dataLines.length === 0) return;
+            message.data = dataLines.join("\n");
+            out.push(decode(message));
+          };
+
+          /** 按 \n\n 切块；final=true 时处理无尾空行的末块；ended 后停止分派。 */
+          const emitBlocks = (chunk: string, final: boolean): F[] => {
+            buffer += chunk;
+            const frames: F[] = [];
+            let boundary = buffer.indexOf("\n\n");
+            while (boundary >= 0 && !ended) {
+              dispatch(buffer.slice(0, boundary), frames);
+              buffer = buffer.slice(boundary + 2);
+              boundary = buffer.indexOf("\n\n");
+            }
+            if (final && !ended && buffer.trim().length > 0) {
+              dispatch(buffer, frames);
+              buffer = "";
+            }
+            return frames;
+          };
+
+          try {
+            while (!ended) {
+              const { done, value } = await reader.read();
+              if (done) {
+                for (const frame of emitBlocks(decoder.decode(), true)) yield frame;
+                break;
+              }
+              for (const frame of emitBlocks(decoder.decode(value, { stream: true }), false)) {
+                yield frame;
+              }
+            }
+          } finally {
+            await cancelReader(reader);
+          }
+          if (ended) {
+            closeReason = "ended";
+            return;
+          }
+          throw new TransportInterrupt("sse stream closed without end event");
+        },
+      };
+      return self;
+    },
+  };
+}

package/src/kernel/algebra.ts

@@ -0,0 +1,153 @@
+import type { CollectionQuery, FieldValue, Order, Predicate, QueryWindow, Segment } from "./types";
+
+// ============ 谓词求值（纯函数） ============
+
+function fieldOf(row: unknown, field: string): unknown {
+  return (row as Record<string, unknown>)[field];
+}
+
+function compare(a: unknown, b: unknown): number {
+  if (a === b) return 0;
+  if (a === undefined || a === null) return -1;
+  if (b === undefined || b === null) return 1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+  return String(a).localeCompare(String(b));
+}
+
+function contains(value: unknown, needle: FieldValue): boolean {
+  return String(value ?? "")
+    .toLowerCase()
+    .includes(String(needle).toLowerCase());
+}
+
+export function evalPredicate(predicate: Predicate | undefined, row: unknown): boolean {
+  if (predicate === undefined) return true;
+  if ("all" in predicate) return predicate.all.every((p) => evalPredicate(p, row));
+  if ("any" in predicate) return predicate.any.some((p) => evalPredicate(p, row));
+  const value = fieldOf(row, predicate.field as string);
+  switch (predicate.op) {
+    case "eq":
+      return value === predicate.value;
+    case "ne":
+      return value !== predicate.value;
+    case "contains":
+      return contains(value, predicate.value);
+    case "in":
+      return Array.isArray(predicate.value) && predicate.value.includes(value as string);
+    case "gt":
+      return compare(value, predicate.value) > 0;
+    case "lt":
+      return compare(value, predicate.value) < 0;
+    case "gte":
+      return compare(value, predicate.value) >= 0;
+    case "lte":
+      return compare(value, predicate.value) <= 0;
+    case "exists":
+      return value !== undefined && value !== null;
+  }
+}
+
+/** 文本搜索谓词：q 在白名单字段上的 contains 之 OR（FilterBar/schema 工厂共用）。 */
+export function textPredicate(fields: ReadonlyArray<string>, q: string): Predicate | undefined {
+  if (!q.trim() || fields.length === 0) return undefined;
+  return {
+    any: fields.map((field) => ({ field, op: "contains" as const, value: q.trim() })),
+  };
+}
+
+// ============ 客户端伪造游标（客户端求值方言） ============
+// "游标进 URL、历史即分页栈"在整取方言上的兑现：offset 编进不透明 token。
+
+export function encodeClientCursor(offset: number): string {
+  return `c${offset.toString(36)}`;
+}
+
+export function decodeClientCursor(cursor: string): number | null {
+  if (!cursor.startsWith("c")) return null;
+  const n = Number.parseInt(cursor.slice(1), 36);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+function offsetOf(window: QueryWindow): number {
+  if (window.cursor !== undefined) return decodeClientCursor(window.cursor) ?? 0;
+  return window.range?.offset ?? 0;
+}
+
+// ============ 客户端求值（派生概念的纯函数核心） ============
+
+/**
+ * evaluate(CollectionQuery, rows) —— 求值策略，非概念。
+ * window.cursor 存在时保持游标模式（伪造 token）；否则暴露 total（range/客户端翻页用）。
+ */
+export function evaluateQuery<T>(query: CollectionQuery, rows: ReadonlyArray<T>): Segment<T> {
+  const filtered = query.predicate
+    ? rows.filter((row) => evalPredicate(query.predicate, row))
+    : [...rows];
+  const ordered = query.order?.length
+    ? [...filtered].sort((a, b) => {
+        for (const o of query.order ?? []) {
+          const c = compare(fieldOf(a, o.field as string), fieldOf(b, o.field as string));
+          if (c !== 0) return o.dir === "desc" ? -c : c;
+        }
+        return 0;
+      })
+    : filtered;
+
+  const w = query.window;
+  const offset = offsetOf(w);
+  const slice = ordered.slice(offset, offset + w.size);
+  const segment: Segment<T> = { rows: slice };
+
+  if (w.cursor !== undefined) {
+    if (offset + w.size < ordered.length) {
+      segment.nextCursor = encodeClientCursor(offset + w.size);
+    }
+  } else {
+    segment.total = ordered.length;
+  }
+  return segment;
+}
+
+// ============ 游标代数 ============
+
+/**
+ * 游标推进。返回 null = 不可算：
+ * - keyset（服务端不透明游标 / leaderboards 型 token+total）的 prev 走浏览器历史；
+ * - 唯一能本地算 prev 的是 offset 方言与客户端求值方言（伪造游标含 offset）。
+ */
+export function advance(
+  window: QueryWindow,
+  segment: Segment<unknown>,
+  dir: "next" | "prev",
+): QueryWindow | null {
+  if (dir === "next") {
+    // 服务端续读令牌优先（keyset 无 total / leaderboards 型 token+total）；
+    // 客户端求值的 range 模式不产 nextCursor，自然落回 range 分支。
+    if (segment.nextCursor !== undefined) {
+      return { ...window, cursor: segment.nextCursor };
+    }
+    if (window.cursor !== undefined) {
+      return null; // 游标模式下无令牌 = 到底
+    }
+    const offset = offsetOf(window);
+    const next = offset + window.size;
+    if (segment.total !== undefined && next >= segment.total) return null;
+    return { ...window, range: { offset: next } };
+  }
+  const offset = offsetOf(window);
+  if (offset < window.size) return null;
+  const prev = { ...window };
+  if (window.cursor !== undefined) prev.cursor = encodeClientCursor(offset - window.size);
+  else prev.range = { offset: offset - window.size };
+  return prev;
+}
+
+export function orderEquals(a?: ReadonlyArray<Order>, b?: ReadonlyArray<Order>): boolean {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  return a.every((o, i) => {
+    const other = b[i];
+    return !!other && o.field === other.field && o.dir === other.dir;
+  });
+}

package/src/kernel/index.ts

@@ -0,0 +1,4 @@
+export * from "./algebra";
+export * from "./keys";
+export * from "./resource";
+export * from "./types";

package/src/kernel/keys.ts

@@ -0,0 +1,99 @@
+import type {
+  CommandsRecord,
+  QuerySelector,
+  Resource,
+  ResourceScope,
+  SubsRecord,
+} from "./resource";
+import { scopeOf } from "./resource";
+import type { CollectionQuery } from "./types";
+
+// ============ 查询键（queryKey 单源；失效选择器在此匹配） ============
+
+/** 键形：[kind, resourceName, scope, ...detail]——前缀与 predicate 失效都依赖此结构。 */
+export type QueryKind = "collection" | "record" | "batch";
+
+function canonicalScope(scope: ResourceScope): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const key of Object.keys(scope).sort()) {
+    const value = scope[key];
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+function normPredicate(p: CollectionQuery["predicate"]): unknown {
+  return p ?? null;
+}
+
+function normWindow(w: CollectionQuery["window"]): unknown {
+  return { size: w.size, cursor: w.cursor ?? null, offset: w.range?.offset ?? null };
+}
+
+export function collectionKey<T, ID, C extends CommandsRecord<ID>, S extends SubsRecord>(
+  resource: Resource<T, ID, C, S>,
+  query: CollectionQuery,
+): readonly unknown[] {
+  return [
+    "collection",
+    resource.name,
+    canonicalScope(scopeOf(resource)),
+    normPredicate(query.predicate),
+    query.order ?? null,
+    normWindow(query.window),
+  ];
+}
+
+export function recordKey<T, ID, C extends CommandsRecord<ID>, S extends SubsRecord>(
+  resource: Resource<T, ID, C, S>,
+  id: ID,
+): readonly unknown[] {
+  return ["record", resource.name, canonicalScope(scopeOf(resource)), id];
+}
+
+export function batchKey<T, ID, C extends CommandsRecord<ID>, S extends SubsRecord>(
+  resource: Resource<T, ID, C, S>,
+  ids: ReadonlyArray<ID>,
+): readonly unknown[] {
+  const unique = [...new Set(ids)];
+  return ["batch", resource.name, canonicalScope(scopeOf(resource)), unique];
+}
+
+// ============ 失效匹配（scope 交运算在此） ============
+
+const FLEET_KINDS = new Set(["collection", "record", "batch"]);
+
+export function isFleetKey(key: readonly unknown[]): boolean {
+  return typeof key[0] === "string" && FLEET_KINDS.has(key[0]);
+}
+
+/**
+ * selector 匹配：默认与命令执行的 ctx scope 相交（project A 的命令不清 project B 的缓存）；
+ * allScopes: true 显式逃逸。
+ */
+export function selectorMatches(
+  selector: QuerySelector,
+  key: readonly unknown[],
+  commandScope: ResourceScope,
+): boolean {
+  const [kind, name, keyScope] = key;
+  if (selector.kind !== undefined && selector.kind !== kind) return false;
+  if (selector.resource !== name) return false;
+  if (!selector.allScopes) {
+    if (JSON.stringify(keyScope) !== JSON.stringify(canonicalScope(commandScope))) return false;
+  }
+  if (selector.kind === "record" && selector.id !== undefined) {
+    if (key[3] !== selector.id) return false;
+  }
+  return true;
+}
+
+/** 绑定层把 invalidates 声明编译成 TanStack Query 的 predicate 过滤器。 */
+export function invalidationPredicate(
+  selectors: ReadonlyArray<QuerySelector>,
+  commandScope: ResourceScope,
+): (query: { queryKey: readonly unknown[] }) => boolean {
+  return (query) =>
+    isFleetKey(query.queryKey) &&
+    selectors.some((s) => selectorMatches(s, query.queryKey, commandScope));
+}

package/src/kernel/resource.ts

@@ -0,0 +1,181 @@
+import type {
+  CollectionQuery,
+  CommandResult,
+  Segment,
+  SubscriptionPolicy,
+  Transport,
+} from "./types";
+import { isApiError } from "./types";
+
+// ============ 交互面：Resource ============
+
+/** branded 资源名——QuerySelector 收 branded 类型，拼错编译期爆炸。 */
+declare const resourceBrand: unique symbol;
+export type ResourceName = string & { readonly [resourceBrand]?: "ResourceName" };
+
+export type ResourceScope = Readonly<Record<string, string | undefined>>;
+
+export interface CommandDescriptor<Input, Payload, ID = never> {
+  run(input: Input, ctx: ResourceScope): Promise<CommandResult<Payload>>;
+  /** ID 类型线程锚：CommandsRecord 依资源 id 类型定位（optional 永不出现，
+   *  运行时无形状——发布 .ts 源码时消费方 noUnusedLocals 会穿透检查 kit，
+   *  未使用的类型参数必须锚定）。 */
+  readonly __id?: ID;
+  /** 跨资源失效声明（纯数据）；默认与命令执行的 ctx scope 相交 */
+  invalidates?: ReadonlyArray<QuerySelector>;
+  /** 结果覆写钩子：命令作者裁决协议层状态的领域语义（delete 已删 → 幂等 ok 等） */
+  treatAs?: Partial<Record<"not-found" | "forbidden", CommandResult<Payload>>>;
+  /**
+   * @internal 归属资源名——defineResource 注入；缺省 invalidates 时的默认失效目标
+   * （内置动词同资源失效，跨资源声明走 invalidates）。
+   */
+  __resource?: ResourceName;
+}
+
+export interface SubscriptionDescriptor<Params, Frame> {
+  open(params: Params, ctx: ResourceScope): Transport<Frame>;
+  /** 流属性默认在资源侧声明；调用点可覆盖 */
+  policy?: SubscriptionPolicy;
+}
+
+export type CommandsRecord<ID> = Record<string, CommandDescriptor<any, any, ID>>;
+
+/** defineResource 注入 __resource 后的命令映射（逐键保留具体 Input/Payload 类型） */
+export type AttachedCommands<C> = {
+  [K in keyof C]: C[K] & { __resource?: ResourceName };
+};
+export type SubsRecord = Record<string, SubscriptionDescriptor<any, any>>;
+
+export interface ResourceSpec<
+  T,
+  ID = string,
+  C extends CommandsRecord<ID> = Record<string, never>,
+  S extends SubsRecord = Record<string, never>,
+> {
+  name: string;
+  /** 可选——command-only/流式资源无 id 语义；DataTable/绑定的 getRowId 显式传入 */
+  getId?: (row: T) => ID;
+  /** scope 键名（如 ["projectId"]），scoped() 约定用 */
+  scope?: ReadonlyArray<string>;
+
+  collection?: (
+    q: CollectionQuery,
+    ctx: ResourceScope,
+    signal?: AbortSignal,
+  ) => Promise<Segment<T>>;
+  record?: (id: ID, ctx: ResourceScope, signal?: AbortSignal) => Promise<T>;
+  batch?: (
+    ids: ReadonlyArray<ID>,
+    ctx: ResourceScope,
+    signal?: AbortSignal,
+  ) => Promise<ReadonlyArray<T>>;
+
+  commands?: C;
+  subscriptions?: S;
+}
+
+export interface Resource<
+  T,
+  ID = string,
+  C extends CommandsRecord<ID> = Record<string, never>,
+  S extends SubsRecord = Record<string, never>,
+> {
+  readonly name: ResourceName;
+  readonly getId?: (row: T) => ID;
+  readonly scope?: ReadonlyArray<string>;
+
+  readonly collection?: (
+    q: CollectionQuery,
+    ctx: ResourceScope,
+    signal?: AbortSignal,
+  ) => Promise<Segment<T>>;
+  readonly record?: (id: ID, ctx: ResourceScope, signal?: AbortSignal) => Promise<T>;
+  readonly batch?: (
+    ids: ReadonlyArray<ID>,
+    ctx: ResourceScope,
+    signal?: AbortSignal,
+  ) => Promise<ReadonlyArray<T>>;
+
+  readonly commands?: AttachedCommands<C>;
+  readonly subscriptions?: S;
+  /** scoped() 注入的作用域值（内部约定，勿直接读写） */
+  readonly __scopeValues?: ResourceScope;
+}
+
+/**
+ * 定义一个实体/流族的交互面（三原语各自可选）。
+ * 泛型 C/S 逐键保留具体 CommandDescriptor/SubscriptionDescriptor——不被擦成 any。
+ */
+export function defineResource<
+  T,
+  ID,
+  C extends CommandsRecord<ID> = Record<string, never>,
+  S extends SubsRecord = Record<string, never>,
+>(spec: ResourceSpec<T, ID, C, S>): Resource<T, ID, C, S> {
+  if (!/^[a-z][a-z0-9-]*$/.test(spec.name)) {
+    throw new Error(
+      `fleet-ui: resource name "${spec.name}" must be kebab-case (it lives in query keys and URL diagnostics)`,
+    );
+  }
+  const commands = spec.commands
+    ? (Object.fromEntries(
+        Object.entries(spec.commands).map(([verb, descriptor]) => [
+          verb,
+          { ...descriptor, __resource: spec.name as ResourceName },
+        ]),
+      ) as AttachedCommands<C>)
+    : undefined;
+  return { ...spec, commands, name: spec.name as ResourceName };
+}
+
+/**
+ * runCommand —— 命令执行的单源入口（绑定层与命令式编排共用）。
+ * treatAs 在此裁决：协议层失败（not-found/forbidden）被命令作者覆写为结果分支；
+ * 其余失败（网络/401/5xx）原样出界走错误通道。
+ */
+export async function runCommand<Input, Payload, ID>(
+  descriptor: CommandDescriptor<Input, Payload, ID>,
+  input: Input,
+  ctx: ResourceScope,
+): Promise<CommandResult<Payload>> {
+  try {
+    return await descriptor.run(input, ctx);
+  } catch (error) {
+    if (isApiError(error)) {
+      const remap = descriptor.treatAs?.[error.kind as "not-found" | "forbidden"];
+      if (remap) return remap;
+    }
+    throw error;
+  }
+}
+
+/**
+ * scoped 约定（派生，非框架轴）：queryKey 嵌入 scope 段 + 适配器 ctx 注入。
+ * 适配器可在 http 实例上把 ctx 注入 header（torchwood X-Torchwood-Project）。
+ */
+export function scoped<T, ID, C extends CommandsRecord<ID>, S extends SubsRecord>(
+  resource: Resource<T, ID, C, S>,
+  values: ResourceScope,
+): Resource<T, ID, C, S> {
+  return {
+    ...resource,
+    __scopeValues: { ...(resource.__scopeValues ?? {}), ...values },
+  };
+}
+
+export function scopeOf<T, ID, C extends CommandsRecord<ID>, S extends SubsRecord>(
+  resource: Resource<T, ID, C, S>,
+): ResourceScope {
+  return resource.__scopeValues ?? {};
+}
+
+// ============ 失效选择器（kernel 纯数据；执行在绑定层） ============
+
+export interface QuerySelector {
+  resource: ResourceName;
+  /** 缺省 = 该资源全部查询形态 */
+  kind?: "collection" | "record" | "batch";
+  id?: unknown;
+  /** 显式跨作用域失效（罕见；默认与命令 ctx scope 相交） */
+  allScopes?: boolean;
+}