@deepexi/datasense-connector 3.0.1 → 3.1.0

package/src/types.ts

@@ -0,0 +1,329 @@
+/**
+ * 连接器 SDK 的运行时类型：`ctx` 的各项能力、数据流产出、推送与连接器操作的实现形状，以及平台连接上的声明类型
+ * （`TableDeclaration` / `ScalarType` 等，connector 数据面在用）。
+ *
+ * 连接器的元数据写在连接器描述里（见 `descriptor.ts`），代码只写实现（见 `define.ts`）。连接器打包后在 `node:vm` 里执行，
+ * `ctx` 由 SDK 的 guest 运行时提供，所以这里不引用任何 Node / Bun 内置模块。
+ *
+ * 文件来源（`ctx.files`）不在本期：`ctx.files` 的类型是 `never`，访问时抛 `errors.NotAvailable('ctx.files')`。
+ */
+
+export type ScalarKind = 'string' | 'integer' | 'decimal' | 'boolean' | 'date' | 'instant' | 'json';
+
+export interface ScalarType {
+  readonly kind: ScalarKind;
+  readonly precision?: number;
+  readonly scale?: number;
+  readonly title?: string;
+  /** 作为表列时是列说明。 */
+  readonly description?: string;
+  readonly placeholder?: string;
+  readonly optional?: boolean;
+}
+
+/** 凭证字段。只能出现在连接配置的顶层；脚本里拿到的是句柄，`exposeToScript` 时可取明文。 */
+export interface SecretType {
+  readonly kind: 'secret';
+  readonly exposeToScript?: boolean;
+  readonly title?: string;
+  readonly description?: string;
+  readonly placeholder?: string;
+  readonly optional?: boolean;
+}
+
+export interface ObjectType {
+  readonly kind: 'object';
+  readonly shape: Readonly<Record<string, SdkType>>;
+  readonly title?: string;
+  readonly description?: string;
+  readonly optional?: boolean;
+}
+
+export interface ArrayType {
+  readonly kind: 'array';
+  readonly item: SdkType;
+  readonly title?: string;
+  readonly description?: string;
+  readonly optional?: boolean;
+}
+
+export type SdkType = ScalarType | SecretType | ObjectType | ArrayType;
+
+export interface TableDeclaration {
+  columns: Record<string, ScalarType>;
+  primaryKey: string[];
+  retention?: { column: string; days: number };
+  purgeColumns?: { tenant?: string; user?: string };
+  indexes?: string[][];
+  /** 表的显示名，≤ 40 字符。 */
+  title?: string;
+  /** 表说明，≤ 200 字符。 */
+  description?: string;
+}
+
+export type SyncMode = 'full' | 'incremental';
+
+// ---------------------------------------------------------------------------
+// 数据流产出
+
+export interface StreamInput<S = unknown> {
+  mode: SyncMode;
+  /** 上次提交的断点；首次为 undefined。 */
+  state: S | undefined;
+  streamConfig: Readonly<Record<string, unknown>>;
+}
+
+export interface RecordItem {
+  readonly __ontos: 'record';
+  table: string;
+  row: Record<string, unknown>;
+}
+
+export interface RemoveItem {
+  readonly __ontos: 'remove';
+  table: string;
+  key: Record<string, unknown>;
+}
+
+export interface CheckpointItem {
+  readonly __ontos: 'checkpoint';
+  state: unknown;
+}
+
+export type StreamItem = RecordItem | RemoveItem | CheckpointItem;
+
+export type StreamFunction = (ctx: PullContext, input: StreamInput) => AsyncIterable<StreamItem>;
+
+// ---------------------------------------------------------------------------
+// ctx.http
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+
+export interface HttpResponse<T = unknown> {
+  status: number;
+  /** 最终地址（跟随重定向之后）。 */
+  url: string;
+  headers: Record<string, string>;
+  /** `content-type` 为 JSON 时是解析后的值，否则同 `text`。 */
+  data: T;
+  text: string;
+}
+
+/** 登录换来的会话：附加的请求头与相对路径的基址。 */
+export interface HttpAuth {
+  headers?: Record<string, string>;
+  baseUrl?: string;
+}
+
+export interface HttpOptions {
+  headers?: Record<string, string>;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  auth?: HttpAuth;
+  timeoutMs?: number;
+  /** 为 true 时不按状态码抛错、不解析 JSON，原样返回。 */
+  raw?: boolean;
+  /**
+   * 上游 502 / 503 / 504 与网关超时是否自动重试（请求可能已被上游处理）。
+   * 缺省只对幂等方法（GET / HEAD / PUT / DELETE）重试；POST / PATCH 需显式传 `true`，传 `false` 则一律不重试。
+   * 网关限流与上游 429（请求未被处理）不受影响，总会等待后重发。
+   */
+  retry?: boolean;
+}
+
+export interface HttpClient {
+  get<T = unknown>(url: string, options?: HttpOptions): Promise<HttpResponse<T>>;
+  post<T = unknown>(url: string, options?: HttpOptions): Promise<HttpResponse<T>>;
+  put<T = unknown>(url: string, options?: HttpOptions): Promise<HttpResponse<T>>;
+  patch<T = unknown>(url: string, options?: HttpOptions): Promise<HttpResponse<T>>;
+  delete<T = unknown>(url: string, options?: HttpOptions): Promise<HttpResponse<T>>;
+  request<T = unknown>(method: HttpMethod, url: string, options?: HttpOptions): Promise<HttpResponse<T>>;
+}
+
+// ---------------------------------------------------------------------------
+// ctx.paginate
+
+/** 分页迭代产出的一页。 */
+export interface Page<Row = unknown> {
+  rows: Row[];
+  /** 本页各行取值的最大值（字符串按字典序、数字按大小）；空页为 undefined。 */
+  maxOf<V>(fn: (row: Row) => V): V | undefined;
+}
+
+/** 按页码翻页。没有 `totalPages` 时翻到空页为止。 */
+export interface PagePaginateOptions<Res, Row> {
+  /** 缺省 1。 */
+  firstPage?: number;
+  request(page: number): Promise<HttpResponse<Res>>;
+  rows(res: HttpResponse<Res>): Row[];
+  totalPages?(res: HttpResponse<Res>): number;
+}
+
+/** 按偏移量翻页。没有 `total` 时翻到不满一页为止。 */
+export interface OffsetPaginateOptions<Res, Row> {
+  limit: number;
+  /** 缺省 0。 */
+  startOffset?: number;
+  request(offset: number, limit: number): Promise<HttpResponse<Res>>;
+  rows(res: HttpResponse<Res>): Row[];
+  total?(res: HttpResponse<Res>): number;
+}
+
+/** 按游标翻页。`nextCursor` 返回空值时结束。 */
+export interface CursorPaginateOptions<Res, Row> {
+  request(cursor: string | undefined): Promise<HttpResponse<Res>>;
+  rows(res: HttpResponse<Res>): Row[];
+  nextCursor(res: HttpResponse<Res>): string | null | undefined;
+}
+
+/** 按下一页链接翻页。缺省取响应头 `Link` 里 `rel="next"` 的地址。 */
+export interface LinkPaginateOptions<Res, Row> {
+  url: string;
+  options?: HttpOptions;
+  rows(res: HttpResponse<Res>): Row[];
+  next?(res: HttpResponse<Res>): string | null | undefined;
+}
+
+/** 数据库按键分页：`query` 以上一页最后一行的键（首页为 undefined）查下一页，返回空页时结束。 */
+export interface KeysetPaginateOptions<Row, Key> {
+  query(last: Key | undefined): AsyncIterable<Row>;
+  key(row: Row): Key;
+}
+
+export interface Paginate {
+  page<Res = unknown, Row = unknown>(options: PagePaginateOptions<Res, Row>): AsyncIterable<Page<Row>>;
+  offset<Res = unknown, Row = unknown>(options: OffsetPaginateOptions<Res, Row>): AsyncIterable<Page<Row>>;
+  cursor<Res = unknown, Row = unknown>(options: CursorPaginateOptions<Res, Row>): AsyncIterable<Page<Row>>;
+  link<Res = unknown, Row = unknown>(options: LinkPaginateOptions<Res, Row>): AsyncIterable<Page<Row>>;
+  keyset<Row = Record<string, unknown>, Key = unknown>(options: KeysetPaginateOptions<Row, Key>): AsyncIterable<Page<Row>>;
+}
+
+// ---------------------------------------------------------------------------
+// ctx 的其余成员
+
+export interface ConnectorDb {
+  /** 一次查询一个只读事务；只接受参数化查询（`$1`、`$2`…），一条语句。 */
+  query<R = Record<string, unknown>>(sql: string, params?: unknown[]): AsyncIterable<R>;
+}
+
+export interface ConnectorCache {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string, ttlSeconds: number): Promise<void>;
+  getOrSet(key: string, ttlSeconds: number, fn: () => Promise<string>): Promise<string>;
+}
+
+export type HmacAlgorithm = 'sha1' | 'sha256' | 'sha512';
+export type SignAlgorithm = 'rsa-sha256';
+export type HashAlgorithm = 'md5' | 'sha1' | 'sha256' | 'sha512';
+export type DigestEncoding = 'hex' | 'base64';
+
+/** `key` 可以是凭证句柄（`ctx.secrets.<字段>`），由网关代算。 */
+export interface ConnectorCrypto {
+  hmac(algorithm: HmacAlgorithm, key: string, data: string, encoding?: DigestEncoding): Promise<string>;
+  sign(algorithm: SignAlgorithm, key: string, data: string, encoding?: DigestEncoding): Promise<string>;
+  hash(algorithm: HashAlgorithm, data: string, encoding?: DigestEncoding): Promise<string>;
+  base64Encode(text: string): string;
+  base64Decode(b64: string): string;
+}
+
+export interface ConnectorTime {
+  /** 当前时间，ISO 8601 UTC。 */
+  now(): string;
+  /** 把来源给的本地时间文本按时区换成 ISO 8601 UTC。 */
+  toUtc(local: string, timeZone: string, format?: string): string;
+}
+
+export interface ConnectorSignal {
+  readonly aborted: boolean;
+  onAbort(fn: () => void): void;
+}
+
+export interface ConnectorLog {
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, data?: Record<string, unknown>): void;
+}
+
+export interface PullContext {
+  readonly config: Readonly<Record<string, unknown>>;
+  /** 凭证句柄（`ontos:secret:<字段>`）；`exposeToScript` 字段是明文。 */
+  readonly secrets: Readonly<Record<string, string>>;
+  readonly http: HttpClient;
+  readonly paginate: Paginate;
+  readonly db: ConnectorDb;
+  /** 保留名字；访问即抛 `errors.NotAvailable('ctx.files')`。 */
+  readonly files: never;
+  map<T, R>(items: readonly T[], fn: (item: T) => Promise<R>, options?: { concurrency?: number }): Promise<R[]>;
+  readonly cache: ConnectorCache;
+  readonly crypto: ConnectorCrypto;
+  readonly time: ConnectorTime;
+  record(table: string, row: Record<string, unknown>): RecordItem;
+  remove(table: string, key: Record<string, unknown>): RemoveItem;
+  checkpoint(state: unknown): CheckpointItem;
+  readonly log: ConnectorLog;
+  readonly signal: ConnectorSignal;
+}
+
+export type CheckContext = Omit<PullContext, 'record' | 'remove' | 'checkpoint'>;
+
+// ---------------------------------------------------------------------------
+// 推送
+
+export interface PushRequest {
+  readonly id: string;
+  readonly receivedAt: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  json<T = unknown>(): T;
+}
+
+export interface PushContext {
+  readonly config: Readonly<Record<string, unknown>>;
+  record(table: string, row: Record<string, unknown>): void;
+  remove(table: string, key: Record<string, unknown>): void;
+  readonly log: ConnectorLog;
+  readonly time: { now(): string };
+}
+
+export interface PushHandler {
+  verify?(ctx: PushContext, req: PushRequest): void | Promise<void>;
+  map(ctx: PushContext, req: PushRequest): void | Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// 连接器操作
+
+/** 连接器操作的 `ctx`：只有出站请求、凭证、加密、缓存、时间与日志，没有 `record`、`db`。 */
+export interface OperationContext {
+  readonly config: Readonly<Record<string, unknown>>;
+  /** 凭证句柄（`ontos:secret:<字段>`）；`exposeToScript` 字段是明文。 */
+  readonly secrets: Readonly<Record<string, string>>;
+  readonly http: HttpClient;
+  readonly crypto: ConnectorCrypto;
+  readonly cache: ConnectorCache;
+  readonly time: ConnectorTime;
+  readonly log: ConnectorLog;
+}
+
+/** `lookup` 的回答：`applied` 带输出（按 `output` 声明校验）；抛错按 `unknown` 处理。 */
+export type LookupResult<O> = { status: 'applied'; output: O } | { status: 'not_applied' } | { status: 'unknown' };
+
+export type ConnectorOperationEffect = 'create' | 'update' | 'delete';
+export type ConnectorOperationRisk = 'low' | 'medium' | 'high' | 'critical';
+
+/**
+ * 一个连接器操作的实现（契约写在 `operations/<名>/operation.yaml` 里）：
+ * - `idempotency: 'supported'`：外部系统按 `idempotencyKey` 去重，平台超时后可用同一个键重发；
+ * - `idempotency: 'unsupported'`：平台不重发，结果不明时调 `lookup` 查询，所以必须实现 `lookup`；
+ * - `simulate` 是纯函数（拿不到 `ctx`），推演与试运行时代替 `run` 返回模拟输出。
+ */
+export interface OperationHandlers<I = Record<string, unknown>, O = Record<string, unknown>> {
+  run(ctx: OperationContext, params: I, meta: { idempotencyKey: string }): O | Promise<O>;
+  lookup?(ctx: OperationContext, input: { idempotencyKey: string; params: I }): LookupResult<O> | Promise<LookupResult<O>>;
+  simulate?(params: I): O;
+}
+
+export interface ConnectorRateLimit {
+  perSecond: number;
+  concurrency: number;
+}

package/src/validate.ts

@@ -0,0 +1,267 @@
+/**
+ * 名字规则、展示文字的长度上限，以及按连接器描述校验的值：连接配置（`validateConfig`）、连接器操作的入参与输出
+ * （`validateOperationValue`）、`suggestColumns` 的建议列（`validateSuggestedColumns`）。
+ * 输入可能来自 vm 里的不可信代码或租户数据，所以按 unknown 逐层检查，只返回问题列表、不抛异常。
+ *
+ * 连接器描述本身的校验（YAML 解析、必填说明、跨文件规则）在平台（shared）里，SDK 不重复。
+ */
+import type { ColumnType, ConfigField, SuggestedColumn, ValueField } from './descriptor';
+
+/** 表名、连接器名、数据流名与推送名的规则，与 shared 的 DATA_FOUNDATION_NAME_PATTERN 一致。 */
+export const SDK_NAME_PATTERN: RegExp = /^[a-z][a-z0-9_]{0,27}$/;
+
+/** 保留的推送名：`dev` 会和接收地址的 `/dev` 后缀冲突。与 shared 同值，SDK 不依赖 shared，自己定义。 */
+export const RESERVED_PUSH_NAMES: readonly string[] = Object.freeze(['dev']);
+
+/** 缺省推送名（接收地址不带推送名后缀时对应它）。 */
+export const DEFAULT_PUSH_NAME = 'default';
+
+/** 连接器操作名的规则。 */
+export const OPERATION_NAME_PATTERN: RegExp = /^[a-z][a-z0-9_]{0,62}$/;
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const INSTANT_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
+const DECIMAL_TEXT_PATTERN = /^-?\d+(?:\.\d+)?$/;
+const COLUMN_TYPES: ReadonlySet<string> = new Set<ColumnType>(['string', 'integer', 'decimal', 'boolean', 'date', 'instant', 'json']);
+/** 建议列（将成为扩展列）的名字：不得以 `_` 开头（`_ontos_` 前缀留给平台系统列），最长 63（PostgreSQL 标识符上限）。 */
+const SUGGESTED_COLUMN_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,62}$/;
+/** 一次建议最多的列数。 */
+export const SUGGESTED_COLUMNS_MAX = 1000;
+
+/**
+ * 展示文字的长度上限（字符数按 Unicode 码点计，字节数按解码后的字节计；多语言文字每种语言分别计）。
+ * `title` / `description` / `readmeBytes` / `iconBytes` / `iconMinPx` 是连接器本身（标题、说明、README.md、图标）的上限；
+ * 其余是配置项、字段、表与列的上限。连接器描述的校验在 shared 里，沿用这里的值。
+ */
+export const PRESENTATION_LIMITS: {
+  readonly title: 40;
+  readonly description: 120;
+  readonly readmeBytes: 65536;
+  readonly iconBytes: 262144;
+  readonly iconMinPx: 128;
+  readonly fieldTitle: 40;
+  readonly fieldDescription: 200;
+  readonly placeholder: 100;
+  readonly tableTitle: 40;
+  readonly tableDescription: 200;
+} = Object.freeze({
+  title: 40,
+  description: 120,
+  readmeBytes: 65536,
+  iconBytes: 262144,
+  iconMinPx: 128,
+  fieldTitle: 40,
+  fieldDescription: 200,
+  placeholder: 100,
+  tableTitle: 40,
+  tableDescription: 200,
+});
+
+export interface DeclarationIssue {
+  path: string;
+  message: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isValidDate(text: string): boolean {
+  if (!DATE_PATTERN.test(text)) return false;
+  const date = new Date(`${text}T00:00:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === text;
+}
+
+/** `http(s)://` + 非空主机（可带用户信息与端口）+ 可选的路径、查询、片段；用正则判断，guest 的 vm 里没有 `URL`。 */
+const HTTP_URL_PATTERN = /^https?:\/\/(?:[^\s@/?#]*@)?(?:[^\s:/?#@[\]]+|\[[0-9a-f:.]+\])(?::\d{1,5})?(?:[/?#]\S*)?$/i;
+
+function isHttpUrl(text: string): boolean {
+  return HTTP_URL_PATTERN.test(text);
+}
+
+/** 标量值是否符合类型；不符合时返回期望的说明。 */
+function scalarProblem(type: string, value: unknown): string | null {
+  switch (type) {
+    case 'string':
+      return typeof value === 'string' ? null : 'a string';
+    case 'integer':
+      return typeof value === 'number' && Number.isSafeInteger(value) ? null : 'an integer';
+    case 'decimal':
+      return (typeof value === 'number' && Number.isFinite(value)) || (typeof value === 'string' && DECIMAL_TEXT_PATTERN.test(value)) ? null : 'a decimal number';
+    case 'boolean':
+      return typeof value === 'boolean' ? null : 'a boolean';
+    case 'date':
+      return typeof value === 'string' && isValidDate(value) ? null : 'a date like 2026-01-31';
+    case 'instant':
+      return typeof value === 'string' && INSTANT_PATTERN.test(value) && !Number.isNaN(Date.parse(value)) ? null : 'an ISO 8601 timestamp with time zone';
+    case 'json':
+      return null;
+    default:
+      return `of a known type (got ${type})`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 连接配置
+
+function configProblem(field: ConfigField, value: unknown): string | null {
+  switch (field.type) {
+    case 'url':
+      return typeof value === 'string' && isHttpUrl(value) ? null : 'an http or https URL';
+    case 'enum': {
+      const values = Array.isArray(field.values) ? field.values : [];
+      return typeof value === 'string' && values.includes(value) ? null : `one of ${values.map((item) => JSON.stringify(item)).join(', ')}`;
+    }
+    default:
+      return scalarProblem(field.type, value);
+  }
+}
+
+/**
+ * 按描述的配置项校验连接配置（或数据流参数）的值，路径是配置项名。
+ * - 缺省或为 null 的值：`optional: true` 或有 `default` 的项可以缺省，其余报 `<名> is required`；
+ * - `url` 只接受 http / https，`enum` 只接受列出的取值；
+ * - `secret` 项的值走 Secret 引用，不在配置值里，出现了也忽略；
+ * - 没有声明的键报错。
+ */
+export function validateConfig(fields: Record<string, ConfigField>, value: Record<string, unknown>): Array<{ path: string; message: string }> {
+  if (!isRecord(value)) return [{ path: '', message: 'config must be an object' }];
+  const declared = isRecord(fields) ? fields : {};
+  const issues: DeclarationIssue[] = [];
+  for (const [name, field] of Object.entries(declared)) {
+    if (!isRecord(field)) continue;
+    if (field.type === 'secret') continue;
+    const item = value[name];
+    if (item === undefined || item === null) {
+      if (field.optional !== true && field.default === undefined) issues.push({ path: name, message: `${name} is required` });
+      continue;
+    }
+    const problem = configProblem(field, item);
+    if (problem) issues.push({ path: name, message: `${name} must be ${problem}` });
+  }
+  for (const name of Object.keys(value)) {
+    if (!Object.hasOwn(declared, name)) issues.push({ path: name, message: `${name} is not declared` });
+  }
+  return issues;
+}
+
+// ---------------------------------------------------------------------------
+// 连接器操作的入参与输出
+
+function validateValue(path: string, field: ValueField, value: unknown, issues: DeclarationIssue[]): void {
+  if (!isRecord(field) || typeof field.type !== 'string') {
+    issues.push({ path, message: `${path} has an invalid field declaration` });
+    return;
+  }
+  if (field.type === 'object') {
+    if (!isRecord(value)) {
+      issues.push({ path, message: `${path} must be an object` });
+      return;
+    }
+    validateFields(path, isRecord(field.fields) ? field.fields : {}, value, issues);
+    return;
+  }
+  if (field.type === 'array') {
+    if (!Array.isArray(value)) {
+      issues.push({ path, message: `${path} must be an array` });
+      return;
+    }
+    value.forEach((item: unknown, i) => {
+      const itemPath = `${path}[${i}]`;
+      if (item === undefined || item === null) issues.push({ path: itemPath, message: `${itemPath} is required` });
+      else if (field.item) validateValue(itemPath, field.item, item, issues);
+    });
+    return;
+  }
+  const problem = scalarProblem(field.type, value);
+  if (problem) issues.push({ path, message: `${path} must be ${problem}` });
+}
+
+function validateFields(path: string, fields: Record<string, ValueField>, value: Record<string, unknown>, issues: DeclarationIssue[]): void {
+  for (const [name, field] of Object.entries(fields)) {
+    const fieldPath = `${path}.${name}`;
+    const item = value[name];
+    if (item === undefined || item === null) {
+      if (isRecord(field) && field.optional === true) continue;
+      // json 字段的 null 是合法值。
+      if (!(isRecord(field) && field.type === 'json' && item === null)) issues.push({ path: fieldPath, message: `${fieldPath} is required` });
+      continue;
+    }
+    validateValue(fieldPath, field, item, issues);
+  }
+  for (const name of Object.keys(value)) {
+    if (!Object.hasOwn(fields, name)) issues.push({ path: `${path}.${name}`, message: `${path}.${name} is not declared` });
+  }
+}
+
+/**
+ * 按连接器操作的 `input` / `output` 字段校验一个值（`path` 为 `input` 或 `output`）：
+ * `optional: true` 的字段可缺省或为 null，其余必填；没有声明的字段报错。
+ */
+export function validateOperationValue(fields: Record<string, ValueField>, value: unknown, path: 'input' | 'output'): DeclarationIssue[] {
+  if (!isRecord(value)) return [{ path, message: `${path} must be an object` }];
+  const issues: DeclarationIssue[] = [];
+  validateFields(path, isRecord(fields) ? fields : {}, value, issues);
+  return issues;
+}
+
+// ---------------------------------------------------------------------------
+// 建议列
+
+/**
+ * 校验 `suggestColumns` 的返回值（租户代码产出，按 unknown 处理）：必须是数组、不超过 `SUGGESTED_COLUMNS_MAX` 项；
+ * 每项 `name` 符合扩展列名规则、不重复，`type` 是列类型（`decimal` 要给 precision / scale），`title` 非空，`description` 可选。
+ * 合法时返回复制出的干净列表。
+ */
+export function validateSuggestedColumns(value: unknown): { ok: true; columns: SuggestedColumn[] } | { ok: false; issues: DeclarationIssue[] } {
+  if (!Array.isArray(value)) return { ok: false, issues: [{ path: '', message: 'suggestColumns must return an array of columns' }] };
+  if (value.length > SUGGESTED_COLUMNS_MAX) return { ok: false, issues: [{ path: '', message: `suggestColumns returned more than ${SUGGESTED_COLUMNS_MAX} columns` }] };
+  const issues: DeclarationIssue[] = [];
+  const columns: SuggestedColumn[] = [];
+  const seen = new Set<string>();
+  value.forEach((item: unknown, i) => {
+    const path = `[${i}]`;
+    if (!isRecord(item)) {
+      issues.push({ path, message: `${path} must be an object` });
+      return;
+    }
+    const { name, type, precision, scale, title, description } = item;
+    if (typeof name !== 'string' || !SUGGESTED_COLUMN_NAME_PATTERN.test(name) || name.toLowerCase().startsWith('_ontos_')) {
+      issues.push({ path: `${path}.name`, message: `column name must match ${SUGGESTED_COLUMN_NAME_PATTERN.source}` });
+      return;
+    }
+    if (seen.has(name)) {
+      issues.push({ path: `${path}.name`, message: `column ${name} is suggested more than once` });
+      return;
+    }
+    seen.add(name);
+    if (typeof type !== 'string' || !COLUMN_TYPES.has(type)) {
+      issues.push({ path: `${path}.type`, message: `column ${name} must have a column type (string, integer, decimal, boolean, date, instant or json)` });
+      return;
+    }
+    if (typeof title !== 'string' || title.trim() === '') {
+      issues.push({ path: `${path}.title`, message: `column ${name} needs a non-empty title` });
+      return;
+    }
+    if (description !== undefined && typeof description !== 'string') {
+      issues.push({ path: `${path}.description`, message: `column ${name} description must be a string` });
+      return;
+    }
+    const column: SuggestedColumn = { name, type: type as ColumnType, title };
+    if (type === 'decimal') {
+      const validPrecision = typeof precision === 'number' && Number.isInteger(precision) && precision > 0;
+      if (!validPrecision || typeof scale !== 'number' || !Number.isInteger(scale) || scale < 0 || scale > precision) {
+        issues.push({ path, message: `column ${name}: decimal needs an integer precision > 0 and an integer scale between 0 and precision` });
+        return;
+      }
+      column.precision = precision;
+      column.scale = scale;
+    } else if (precision !== undefined || scale !== undefined) {
+      issues.push({ path, message: `column ${name}: precision and scale are only allowed on decimal columns` });
+      return;
+    }
+    if (description !== undefined) column.description = description;
+    columns.push(column);
+  });
+  return issues.length > 0 ? { ok: false, issues } : { ok: true, columns };
+}