@svadmin/core 0.53.0 → 0.54.0

package/src/index.ts

@@ -1,4 +1,6 @@
 // Core barrel exports
+export { decodeApprovalRecord, decodeApprovalList, decodeApprovalTransition, decodeApprovalReceipt, ApprovalContractError } from './approval-contract';
+export type { ApprovalRecord, ApprovalTransition, ApprovalList, ApprovalReceipt, ApprovalProvider } from './approval-contract';
 
 export {
   setDataProvider, getDataProvider, getDataProviderForResource, getDataProviderNames,
@@ -114,6 +116,12 @@ export {
 export type { NotificationParams } from './notification.svelte';
 export { t, setLocale, getLocale, getAvailableLocales, addTranslations, useTranslation, setI18nProvider, getI18nProvider, createI18nScope, provideI18nScope, getI18nScope, resetI18n } from './i18n.svelte';
 export type { I18nProvider, I18nScope, I18nScopeOptions } from './i18n.svelte';
+export { buildPivot, buildPivotCacheKey, buildPivotDrilldown, buildPivotExportRequest, decodePivotResult, snapshotPivotQuery, snapshotPivotExportTaskResult, formatPivotValue, PIVOT_LIMITS } from './pivot';
+export type { PivotAggregation, PivotCache, PivotDimension, PivotDimensionValue, PivotOptions, PivotPayload, PivotProvider, PivotQuery, PivotResult, PivotDrilldown, PivotExportRequest, PivotExportTaskResult } from './pivot';
+export { civilDateTimeToInstant, parseDateTimeInstant, formatCivilDateTime } from './date-time';
+export type { DateTimeValueMode, DateTimeDisambiguation } from './date-time';
+export { validateGantt, GANTT_LIMITS } from './gantt';
+export type { GanttTaskShape, GanttValidationError } from './gantt';
 export { audit, auditWithProvider, writeAuditEntry, recordMutationRollback, setAuditHandler, setAuditLogProvider, getAuditLogProvider, withValidatedAuditProvider, AuditError } from './audit';
 export type { AuditLogProvider, AuditLogTransport, AuditCreateParams, AuditQueryParams, AuditDraft } from './audit';
 export { TaskError } from './task-contract';
@@ -143,7 +151,17 @@ export type {
   WebhookSummary,
 } from './enterprise';
 export { assertEnterpriseRequestContext, createEnterpriseRequestContext } from './enterprise';
+export {
+  DashboardContractError, decodeDashboardQuery, decodeDashboardSnapshot,
+  type DashboardMetric, type DashboardProvider, type DashboardQuery, type DashboardSnapshot, type DashboardWidget,
+} from './dashboard-contract';
 export { setChatProvider, getChatProvider, setChatContext, getChatContext, setAgentProvider, getAgentProvider, registerApproval, resolveApproval, hasPendingApprovals, resetChatProvider, defineAdminTool, decodeAdminToolArgs, executeAdminTool, projectAdminToolSchema } from './chatProvider.svelte';
+export { ENTERPRISE_MATURITY, enterpriseMaturityFor } from './enterprise-maturity';
+export type {
+  EnterpriseMaturityEntry,
+  EnterpriseMaturityStatus,
+  EnterpriseMaturityTier,
+} from './enterprise-maturity';
 export type {
   ChatProvider, ChatMessage, ChatMessagePart, ChatContext, ChatAttachment, ChatSource,
   MessageStatus, ToolState, AgentProvider, AgentEvent, AgentOptions, ApprovalResponseOptions,
@@ -175,7 +193,7 @@ export type {
   DeleteManyParams, DeleteManyResult,
   Pagination, Sort, Filter, Identity,
   ResourceDefinition, ResourceProviderConfig, ResourceTransportConfig, ResourceAdapterConfig,
-  FieldDefinition, MenuItem,
+  FieldDefinition, DateInputOptions, MenuItem,
   AuthActionResult, CheckResult,
   ResourceTypeMap, ResourceInputMap, ResourceInputOperation, InferResourceInput, KnownResources, InferData,
   BaseRecord, Role, AuditLog
@@ -190,9 +208,26 @@ export { createCaslAccessControl } from './adapters/casl';
 export { createCasbinAccessControl } from './adapters/casbin';
 export type { CasbinAdapterOptions } from './adapters/casbin';
 export { downloadData, toCsv, toJson, toXlsx, parseCSV } from './data-transfer.svelte';
+export { parseSpreadsheetClipboard, serializeSpreadsheetClipboard } from './spreadsheet-clipboard';
+export { parseSpreadsheetWorkbook, serializeSpreadsheetWorkbook, snapshotSpreadsheetWorkbook, SPREADSHEET_WORKBOOK_LIMITS } from './spreadsheet-workbook';
+export type { SpreadsheetCellFormat, SpreadsheetSheet, SpreadsheetWorkbook } from './spreadsheet-workbook';
+export { FILTER_COLLECTION_LIMIT, isNumericFilterField, isCollectionFilterOperator,
+  filterOperatorsForField, isFilterScalarValue, isFilterCollectionValue } from './filter-values';
+export {
+  assertSchemaFormSchema, prepareSchemaFormValue, readSchemaFormPath,
+  matchesSchemaFormCondition, isSchemaFormNodeVisible, validateSchemaFormValue,
+} from './schema-form';
+export type {
+  SchemaFormScalar, SchemaFormCondition, SchemaFormSchema, SchemaFormValidationError,
+} from './schema-form';
 export { useExport } from './export-hooks.svelte';
+export { snapshotExportTaskResult, downloadExportArtifact, safeArtifactUrl } from './export-format';
+export type { ExportTaskResult } from './export-format';
 export type { UseExportOptions } from './export-hooks.svelte';
 export { useImport } from './import-hooks.svelte';
+export type { ImportArtifact, ImportArtifactProvider, ImportTaskResult } from './import-contract';
+export { snapshotImportArtifact, snapshotImportTaskResult } from './import-contract';
+export { IMPORT_LIMITS } from './import-contract';
 export type { UseImportOptions, ImportProgress, ImportResult } from './import-hooks.svelte';
 export type { ExportFormat } from './data-transfer.svelte';
 export {

package/src/pivot.ts

@@ -0,0 +1,367 @@
+import type { Filter } from './types';
+import { snapshotPlainData } from './plain-data';
+import { snapshotListParams } from './query-snapshot';
+import { snapshotExportTaskResult, type ExportFormat, type ExportTaskResult } from './export-format';
+
+export type PivotAggregation = 'sum' | 'count' | 'avg' | 'min' | 'max';
+export type PivotDimensionValue = string | number | boolean | null;
+export interface PivotDimension {
+  key: string;
+  value: PivotDimensionValue;
+  label: string;
+}
+export interface PivotOptions {
+  rowField: string;
+  columnField: string;
+  valueField: string;
+  aggregator?: PivotAggregation;
+}
+export interface PivotResult {
+  error?: 'invalidData' | 'limit' | 'invalidNumber' | 'overflow';
+  rows: PivotDimension[];
+  columns: PivotDimension[];
+  cells: Map<string, Map<string, number | null>>;
+  rowTotals: Map<string, number | null>;
+  columnTotals: Map<string, number | null>;
+  grandTotal: number | null;
+}
+
+export interface PivotQuery extends PivotOptions {
+  resource: string;
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+}
+
+export interface PivotDrilldown {
+  resource: string;
+  scopeKey: string;
+  rowField: string;
+  columnField: string;
+  valueField: string;
+  aggregator: PivotAggregation;
+  row: PivotDimension;
+  column: PivotDimension;
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+}
+
+export interface PivotProvider {
+  aggregate: (query: PivotQuery) => Promise<unknown>;
+}
+
+export interface PivotCache {
+  /** 相同缓存中的不同数据源必须使用不同命名空间。 */
+  providerKey: string;
+  get: (key: string) => Promise<unknown | undefined> | unknown | undefined;
+  set: (key: string, value: unknown) => Promise<void> | void;
+}
+
+export function buildPivotCacheKey(query: unknown, scopeKey: unknown, providerKey: unknown): string | undefined {
+  const snapshot = snapshotPivotQuery(query);
+  if (!snapshot || typeof scopeKey !== 'string' || !scopeKey.trim() || scopeKey.length > 4000
+    || typeof providerKey !== 'string' || !providerKey.trim() || providerKey.length > 4000) return;
+  return JSON.stringify({ protocolVersion: 1, providerKey, scopeKey, query: snapshot });
+}
+
+export interface PivotExportRequest {
+  protocolVersion: 1;
+  kind: 'pivot';
+  scopeKey: string;
+  format: ExportFormat;
+  query: PivotQuery;
+  requestFingerprint: string;
+}
+
+export interface PivotExportTaskResult extends ExportTaskResult {
+  kind: 'pivot';
+  taskName: string;
+  idempotencyKey: string;
+  scopeKey: string;
+  requestFingerprint: string;
+}
+
+/** 只生成服务端导出请求，不将当前页或预聚合单元格当作原始记录导出。 */
+export function buildPivotExportRequest(query: unknown, scopeKey: unknown, format: unknown = 'csv'): PivotExportRequest | undefined {
+  const snapshot = snapshotPivotQuery(query);
+  if (!snapshot || typeof scopeKey !== 'string' || !scopeKey.trim() || scopeKey.length > 4000
+    || (format !== 'csv' && format !== 'json' && format !== 'xlsx')) return;
+  const request: Omit<PivotExportRequest, 'requestFingerprint'> = { protocolVersion: 1, kind: 'pivot', scopeKey, format, query: snapshot };
+  return { ...request, requestFingerprint: JSON.stringify(request) };
+}
+
+export function snapshotPivotExportTaskResult(value: unknown, expected: {
+  taskName: string; idempotencyKey: string; request: PivotExportRequest;
+}): PivotExportTaskResult | undefined {
+  try {
+    const plain = snapshotPlainData(value);
+    if (!isRecord(plain)) return;
+    const { kind, taskName, idempotencyKey, scopeKey, requestFingerprint, ...artifact } = plain;
+    const result = snapshotExportTaskResult(artifact);
+    if (!result || kind !== 'pivot' || taskName !== expected.taskName
+      || idempotencyKey !== expected.idempotencyKey || scopeKey !== expected.request.scopeKey
+      || requestFingerprint !== expected.request.requestFingerprint
+      || result.format !== expected.request.format) return;
+    return { ...result, kind: 'pivot', taskName: expected.taskName,
+      idempotencyKey: expected.idempotencyKey, scopeKey: expected.request.scopeKey,
+      requestFingerprint: expected.request.requestFingerprint };
+  } catch { return; }
+}
+
+/** 保留原条件树的顶层 AND 语义，不能把维度约束塞入已有 OR 组。 */
+export function buildPivotDrilldown(query: unknown, scopeKey: unknown, row: unknown, column: unknown): PivotDrilldown | undefined {
+  try {
+    const snapshot = snapshotPivotQuery(query);
+    if (!snapshot || typeof scopeKey !== 'string' || !scopeKey.trim() || scopeKey.length > 4000) return;
+    const rowSnapshot = wireDimension(snapshotPlainData(row));
+    const columnSnapshot = wireDimension(snapshotPlainData(column));
+    if (!rowSnapshot || !columnSnapshot) return;
+    const constraints: Filter[] = [
+      { field: snapshot.rowField, operator: rowSnapshot.value === null ? 'null' : 'eq', value: rowSnapshot.value },
+      { field: snapshot.columnField, operator: columnSnapshot.value === null ? 'null' : 'eq', value: columnSnapshot.value },
+    ];
+    const narrowed = snapshotPivotQuery({ ...snapshot, filters: [...snapshot.filters ?? [], ...constraints] });
+    if (!narrowed) return;
+    return {
+      resource: narrowed.resource,
+      rowField: narrowed.rowField,
+      columnField: narrowed.columnField,
+      valueField: narrowed.valueField,
+      aggregator: narrowed.aggregator ?? 'sum',
+      scopeKey,
+      row: rowSnapshot,
+      column: columnSnapshot,
+      ...(narrowed.filters ? { filters: narrowed.filters } : {}),
+      ...(narrowed.meta ? { meta: narrowed.meta } : {}),
+    };
+  } catch {
+    return;
+  }
+}
+
+/** 服务端计算所有汇总值；客户端不能对预聚合结果再次求平均或计数。 */
+export interface PivotPayload {
+  rows: PivotDimension[];
+  columns: PivotDimension[];
+  cells: Array<{ rowKey: string; columnKey: string; value: number | null }>;
+  rowTotals: Array<{ key: string; value: number | null }>;
+  columnTotals: Array<{ key: string; value: number | null }>;
+  grandTotal: number | null;
+}
+
+export function snapshotPivotQuery(value: unknown): PivotQuery | undefined {
+  try {
+    const plain = snapshotPlainData(value);
+    if (!isRecord(plain)) return;
+    const { rowField, columnField, valueField, aggregator = 'sum', ...base } = plain;
+    if (![rowField, columnField, valueField].every(field => typeof field === 'string'
+      && field.trim().length > 0 && field.length <= PIVOT_LIMITS.dimensionLength)
+      || typeof aggregator !== 'string' || !['sum', 'count', 'avg', 'min', 'max'].includes(aggregator)) return;
+    const query = snapshotListParams(base);
+    if (Object.keys(base).some(key => !['resource', 'filters', 'meta'].includes(key))) return;
+    return {
+      ...query, rowField: rowField as string, columnField: columnField as string,
+      valueField: valueField as string, aggregator: aggregator as PivotAggregation,
+    };
+  } catch {
+    return;
+  }
+}
+
+export const PIVOT_LIMITS = Object.freeze({
+  records: 10_000,
+  rows: 200,
+  columns: 200,
+  cells: 40_000,
+  dimensionLength: 1000,
+});
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+interface Aggregate {
+  count: number;
+  value: number;
+}
+
+function dimension(value: unknown): PivotDimension | undefined {
+  if (value == null) return { key: 'null:', value: null, label: '—' };
+  if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') return;
+  if (typeof value === 'number' && !Number.isFinite(value)) return;
+  if (typeof value === 'string' && value.length > PIVOT_LIMITS.dimensionLength) return;
+  return { key: `${typeof value}:${value}`, value, label: String(value) };
+}
+
+function sortedDimensions(values: Map<string, PivotDimension>): PivotDimension[] {
+  const labels = new Map<string, number>();
+  for (const item of values.values()) labels.set(item.label, (labels.get(item.label) ?? 0) + 1);
+  // 同一轴存在歧义时统一转义所有文本，避免加引号后与另一个原始标签重名。
+  const quoteStrings = [...labels.values()].some(count => count > 1) || values.has('string:');
+  return [...values.values()].sort((a, b) => a.label < b.label ? -1 : a.label > b.label ? 1 : a.key < b.key ? -1 : 1)
+    .map(item => ({
+      ...item,
+      label: quoteStrings && typeof item.value === 'string'
+        ? JSON.stringify(item.value) : item.label,
+    }));
+}
+
+function result(error?: PivotResult['error']): PivotResult {
+  return {
+    ...(error === undefined ? {} : { error }),
+    rows: [], columns: [], cells: new Map(), rowTotals: new Map(), columnTotals: new Map(), grandTotal: null,
+  };
+}
+
+function wireDimension(value: unknown): PivotDimension | undefined {
+  if (!isRecord(value) || typeof value['key'] !== 'string' || typeof value['label'] !== 'string') return;
+  const dimensionValue = value['value'];
+  if (dimensionValue !== null && typeof dimensionValue !== 'string'
+    && typeof dimensionValue !== 'number' && typeof dimensionValue !== 'boolean') return;
+  if (typeof dimensionValue === 'number' && !Number.isFinite(dimensionValue)) return;
+  if (!value['key'].trim() || !value['label'].trim()
+    || value['key'].length > PIVOT_LIMITS.dimensionLength || value['label'].length > PIVOT_LIMITS.dimensionLength
+    || (typeof dimensionValue === 'string' && dimensionValue.length > PIVOT_LIMITS.dimensionLength)) return;
+  return { key: value['key'], value: dimensionValue, label: value['label'] };
+}
+
+function wireNumber(value: unknown): number | null | undefined {
+  if (value === null) return null;
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function wireTotals(value: unknown, keys: Set<string>): Map<string, number | null> | undefined {
+  if (!Array.isArray(value) || value.length !== keys.size) return;
+  const result = new Map<string, number | null>();
+  for (const item of value) {
+    if (!isRecord(item) || typeof item['key'] !== 'string' || !keys.has(item['key']) || result.has(item['key'])) return;
+    const number = wireNumber(item['value']);
+    if (number === undefined) return;
+    result.set(item['key'], number);
+  }
+  return result;
+}
+
+/** 服务端汇总回执必须是有界纯数据，不能包含访问器或未知维度引用。 */
+export function decodePivotResult(value: unknown): PivotResult {
+  try {
+    const plain = snapshotPlainData(value);
+    if (!isRecord(plain) || !Array.isArray(plain['rows']) || !Array.isArray(plain['columns'])
+      || !Array.isArray(plain['cells'])) return result('invalidData');
+    if (plain['rows'].length > PIVOT_LIMITS.rows || plain['columns'].length > PIVOT_LIMITS.columns
+      || plain['cells'].length > PIVOT_LIMITS.cells) return result('limit');
+    const rows: PivotDimension[] = [];
+    const columns: PivotDimension[] = [];
+    const rowKeys = new Set<string>();
+    const columnKeys = new Set<string>();
+    for (const item of plain['rows']) {
+      const dimension = wireDimension(item);
+      if (!dimension || rowKeys.has(dimension.key)) return result('invalidData');
+      rowKeys.add(dimension.key);
+      rows.push(dimension);
+    }
+    for (const item of plain['columns']) {
+      const dimension = wireDimension(item);
+      if (!dimension || columnKeys.has(dimension.key)) return result('invalidData');
+      columnKeys.add(dimension.key);
+      columns.push(dimension);
+    }
+    if (rows.length * columns.length > PIVOT_LIMITS.cells) return result('limit');
+    const cells = new Map<string, Map<string, number | null>>();
+    for (const item of plain['cells']) {
+      if (!isRecord(item) || typeof item['rowKey'] !== 'string' || typeof item['columnKey'] !== 'string'
+        || !rowKeys.has(item['rowKey']) || !columnKeys.has(item['columnKey'])) return result('invalidData');
+      if (cells.get(item['rowKey'])?.has(item['columnKey'])) return result('invalidData');
+      const number = wireNumber(item['value']);
+      if (number === undefined) return result('invalidNumber');
+      let row = cells.get(item['rowKey']);
+      if (!row) { row = new Map(); cells.set(item['rowKey'], row); }
+      row.set(item['columnKey'], number);
+    }
+    const rowTotals = wireTotals(plain['rowTotals'], rowKeys);
+    const columnTotals = wireTotals(plain['columnTotals'], columnKeys);
+    const grandTotal = wireNumber(plain['grandTotal']);
+    if (!rowTotals || !columnTotals || grandTotal === undefined) return result('invalidData');
+    return { rows, columns, cells, rowTotals, columnTotals, grandTotal };
+  } catch {
+    return result('invalidData');
+  }
+}
+
+function add(aggregate: Aggregate, value: number, operator: PivotAggregation): boolean {
+  aggregate.count++;
+  switch (operator) {
+    case 'count': aggregate.value = aggregate.count; break;
+    case 'sum': aggregate.value += value; break;
+    // 分别缩放两项，避免有限输入的均值因中间求和溢出。
+    case 'avg': aggregate.value = aggregate.value * ((aggregate.count - 1) / aggregate.count) + value / aggregate.count; break;
+    case 'min': aggregate.value = aggregate.count === 1 ? value : Math.min(aggregate.value, value); break;
+    case 'max': aggregate.value = aggregate.count === 1 ? value : Math.max(aggregate.value, value); break;
+  }
+  return Number.isFinite(aggregate.value);
+}
+
+function valueOf(aggregate: Aggregate): number | null {
+  return aggregate.count ? aggregate.value : null;
+}
+
+/** 有界的记录聚合；不把分页数据解释为整个资源的统计结果。 */
+export function buildPivot(data: readonly Record<string, unknown>[], options: PivotOptions): PivotResult {
+  const operator = options.aggregator ?? 'sum';
+  if (!Array.isArray(data) || !['sum', 'count', 'avg', 'min', 'max'].includes(operator)
+    || ![options.rowField, options.columnField, options.valueField].every(field => typeof field === 'string' && field.length > 0)) {
+    return result('invalidData');
+  }
+  if (data.length > PIVOT_LIMITS.records) return result('limit');
+  const rows = new Map<string, PivotDimension>();
+  const columns = new Map<string, PivotDimension>();
+  const cells = new Map<string, Map<string, Aggregate>>();
+  const rowTotals = new Map<string, Aggregate>();
+  const columnTotals = new Map<string, Aggregate>();
+  const grand: Aggregate = { count: 0, value: 0 };
+  for (const record of data) {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return result('invalidData');
+    const own = (field: string) => Object.hasOwn(record, field) ? record[field] : undefined;
+    const row = dimension(own(options.rowField));
+    const column = dimension(own(options.columnField));
+    if (!row || !column) return result('invalidData');
+    rows.set(row.key, row);
+    columns.set(column.key, column);
+    if (rows.size > PIVOT_LIMITS.rows || columns.size > PIVOT_LIMITS.columns
+      || rows.size * columns.size > PIVOT_LIMITS.cells) return result('limit');
+    if (!rowTotals.has(row.key)) rowTotals.set(row.key, { count: 0, value: 0 });
+    if (!columnTotals.has(column.key)) columnTotals.set(column.key, { count: 0, value: 0 });
+    let rowCells = cells.get(row.key);
+    if (!rowCells) { rowCells = new Map(); cells.set(row.key, rowCells); }
+    let cell = rowCells.get(column.key);
+    if (!cell) { cell = { count: 0, value: 0 }; rowCells.set(column.key, cell); }
+    const raw = operator === 'count' ? 1 : own(options.valueField);
+    if (raw == null) continue;
+    if (typeof raw !== 'number' || !Number.isFinite(raw)) return result('invalidNumber');
+    const rowTotal = rowTotals.get(row.key);
+    const columnTotal = columnTotals.get(column.key);
+    if (!rowTotal || !columnTotal) return result('invalidData');
+    const targets = [cell, rowTotal, columnTotal, grand];
+    for (const target of targets) {
+      if (!add(target, raw, operator)) return result('overflow');
+    }
+  }
+  return {
+    rows: sortedDimensions(rows),
+    columns: sortedDimensions(columns),
+    cells: new Map([...cells].map(([key, values]) => [key, new Map([...values].map(([col, agg]) => [col, valueOf(agg)]))])),
+    rowTotals: new Map([...rowTotals].map(([key, agg]) => [key, valueOf(agg)])),
+    columnTotals: new Map([...columnTotals].map(([key, agg]) => [key, valueOf(agg)])),
+    grandTotal: valueOf(grand),
+  };
+}
+
+/** 空格和异常格式化器不能把一个有值的单元格伪装为空值。 */
+export function formatPivotValue(value: number | null | undefined, formatter: (value: number) => string): string {
+  if (value == null) return '—';
+  try {
+    const formatted = formatter(value);
+    return typeof formatted === 'string' && formatted.trim() ? formatted : String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/query-session.svelte.ts

@@ -183,10 +183,15 @@ export function createQuerySession<O extends QuerySessionOptions>(context: Admin
       }
     });
   }
+  // 清理微任务只读取普通快照，不访问已经销毁或退出动画中的派生状态。
+  let lastQueryKey: QueryKey | undefined;
+  $effect(() => { lastQueryKey = options.queryKey; });
   $effect(() => () => {
     disposed = true;
+    const queryKey = lastQueryKey;
+    if (!queryKey) return;
     queueMicrotask(() => {
-      const query = client.getQueryCache().find({ queryKey: options.queryKey, exact: true });
+      const query = client.getQueryCache().find({ queryKey, exact: true });
       if (query?.getObserversCount() === 0) void query.cancel();
     });
   });

package/src/schema-form.ts

@@ -0,0 +1,204 @@
+import { Type, type TSchema } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+
+export type SchemaFormScalar = string | number | boolean | null;
+
+/** 条件路径从表单根开始，只能引用无条件的标量字段。 */
+export interface SchemaFormCondition {
+  path: readonly string[];
+  equals?: SchemaFormScalar;
+  notEquals?: SchemaFormScalar;
+  exists?: boolean;
+}
+
+export interface SchemaFormSchema {
+  type?: string;
+  title?: string;
+  description?: string;
+  properties?: Record<string, SchemaFormSchema>;
+  items?: SchemaFormSchema;
+  enum?: SchemaFormScalar[];
+  default?: unknown;
+  required?: string[];
+  visibleWhen?: SchemaFormCondition;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minimum?: number;
+  maximum?: number;
+  minItems?: number;
+  maxItems?: number;
+}
+
+const keys = new Set([
+  'type', 'title', 'description', 'properties', 'items', 'enum', 'default', 'required',
+  'visibleWhen', 'minLength', 'maxLength', 'pattern', 'minimum', 'maximum', 'minItems', 'maxItems',
+]);
+const scalar = (value: unknown): value is SchemaFormScalar => value === null ||
+  typeof value === 'string' || typeof value === 'boolean' ||
+  (typeof value === 'number' && Number.isFinite(value));
+const fail = (): never => { throw new TypeError('Invalid schema form configuration.'); };
+
+/** Schema 来自可信宿主，但仍拒绝未知关键字、循环、错误约束和超限结构。 */
+export function assertSchemaFormSchema(schema: SchemaFormSchema): void {
+  let visited = 0;
+  const active = new Set<object>();
+  function visit(node: SchemaFormSchema, depth: number): void {
+    if (!node || typeof node !== 'object' || Array.isArray(node) ||
+        ++visited > 1000 || depth > 32 || active.has(node)) fail();
+    if (Object.keys(node).some(key => !keys.has(key))) fail();
+    active.add(node);
+    const kind = node.type ?? (node.properties ? 'object' : undefined);
+    if (kind !== undefined && !['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'].includes(kind)) fail();
+    if (node.properties !== undefined) {
+      if (kind !== 'object' || !node.properties || typeof node.properties !== 'object' || Array.isArray(node.properties)) fail();
+      for (const child of Object.values(node.properties)) visit(child, depth + 1);
+    }
+    if (node.items !== undefined) {
+      if (kind !== 'array') fail();
+      visit(node.items, depth + 1);
+      if (node.items.visibleWhen !== undefined) fail();
+    }
+    if (node.required !== undefined && (kind !== 'object' || !Array.isArray(node.required) ||
+        node.required.some(key => typeof key !== 'string' || !Object.hasOwn(node.properties ?? {}, key)))) fail();
+    if (node.enum !== undefined && (!Array.isArray(node.enum) || node.enum.length === 0 ||
+        node.enum.length > 1000 || !node.enum.every(scalar) || kind === 'object' || kind === 'array')) fail();
+    for (const key of ['minLength', 'maxLength', 'minItems', 'maxItems'] as const) {
+      const limit = node[key];
+      if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0 ||
+          (key.endsWith('Length') ? kind !== 'string' : kind !== 'array'))) fail();
+    }
+    for (const key of ['minimum', 'maximum'] as const) {
+      if (node[key] !== undefined && (!Number.isFinite(node[key]) || (kind !== 'number' && kind !== 'integer'))) fail();
+    }
+    if (node.pattern !== undefined) {
+      if (kind !== 'string' || typeof node.pattern !== 'string' || node.pattern.length > 1000) fail();
+      try { new RegExp(node.pattern); } catch { fail(); }
+    }
+    for (const [min, max] of [[node.minLength, node.maxLength], [node.minItems, node.maxItems], [node.minimum, node.maximum]]) {
+      if (min !== undefined && max !== undefined && min > max) fail();
+    }
+    const condition = node.visibleWhen;
+    if (condition !== undefined) {
+      if (!condition || typeof condition !== 'object' || Array.isArray(condition) ||
+          !Array.isArray(condition.path) || condition.path.length === 0 || condition.path.length > 32 ||
+          condition.path.some(part => typeof part !== 'string') ||
+          Object.keys(condition).some(key => !['path', 'equals', 'notEquals', 'exists'].includes(key)) ||
+          !['equals', 'notEquals', 'exists'].some(key => Object.hasOwn(condition, key))) fail();
+      if ((Object.hasOwn(condition, 'equals') && !scalar(condition.equals)) ||
+          (Object.hasOwn(condition, 'notEquals') && !scalar(condition.notEquals)) ||
+          (Object.hasOwn(condition, 'exists') && typeof condition.exists !== 'boolean')) fail();
+      let controller = schema;
+      for (const part of condition.path) {
+        if (controller.visibleWhen || !controller.properties || !Object.hasOwn(controller.properties, part)) fail();
+        const next = controller.properties?.[part];
+        if (!next) return fail();
+        controller = next;
+      }
+      if (controller.visibleWhen || controller.properties || controller.type === 'object' || controller.type === 'array') fail();
+    }
+    active.delete(node);
+  }
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema) ||
+      (schema.type !== 'object' && !schema.properties) || schema.visibleWhen) fail();
+  visit(schema, 0);
+}
+
+export function readSchemaFormPath(value: unknown, path: readonly string[]): unknown {
+  return path.reduce<unknown>((current, key) => (
+    current !== null && typeof current === 'object' && Object.hasOwn(current, key)
+      ? (current as Record<string, unknown>)[key] : undefined
+  ), value);
+}
+
+export function matchesSchemaFormCondition(condition: SchemaFormCondition | undefined, value: unknown): boolean {
+  if (!condition) return true;
+  const current = readSchemaFormPath(value, condition.path);
+  if (condition.exists !== undefined && (current !== undefined) !== condition.exists) return false;
+  if (Object.hasOwn(condition, 'equals') && !Object.is(current, condition.equals)) return false;
+  if (Object.hasOwn(condition, 'notEquals') && Object.is(current, condition.notEquals)) return false;
+  return true;
+}
+
+export function isSchemaFormNodeVisible(schema: SchemaFormSchema, rootValue: unknown): boolean {
+  return matchesSchemaFormCondition(schema.visibleWhen, rootValue);
+}
+
+export interface SchemaFormValidationError {
+  /** JSON 数组路径，不混淆字段名中的点、斜杠和数组索引。 */
+  path: string;
+  code: 'invalid';
+  message: string;
+}
+
+/** 不编译代码、不转换类型；值约束复用 TypeBox 的解释型校验。 */
+export function prepareSchemaFormValue(schema: SchemaFormSchema, value: unknown): {
+  data: Record<string, unknown>;
+  errors: SchemaFormValidationError[];
+} {
+  assertSchemaFormSchema(schema);
+  const errors: SchemaFormValidationError[] = [];
+  let visited = 0;
+  const invalid = (path: string[]) => {
+    if (errors.length < 50) errors.push({ path: JSON.stringify(path), code: 'invalid', message: 'Invalid value.' });
+  };
+  function visit(node: SchemaFormSchema, current: unknown, path: string[], required: boolean): unknown {
+    if (++visited > 1000 || path.length > 32) throw new TypeError('Schema form data limit exceeded.');
+    if (current === undefined && !required) return undefined;
+    const kind = node.type ?? (node.properties ? 'object' : node.enum ? undefined : 'string');
+    let check: TSchema;
+    switch (kind) {
+      case 'object': check = Type.Object({}); break;
+      case 'array': check = Type.Array(Type.Unknown(), {
+        ...(node.minItems === undefined ? {} : { minItems: node.minItems }),
+        ...(node.maxItems === undefined ? {} : { maxItems: node.maxItems }),
+      }); break;
+      case 'number': check = Type.Number({
+        ...(node.minimum === undefined ? {} : { minimum: node.minimum }),
+        ...(node.maximum === undefined ? {} : { maximum: node.maximum }),
+      }); break;
+      case 'integer': check = Type.Integer({
+        minimum: Math.max(Number.MIN_SAFE_INTEGER, node.minimum ?? Number.MIN_SAFE_INTEGER),
+        maximum: Math.min(Number.MAX_SAFE_INTEGER, node.maximum ?? Number.MAX_SAFE_INTEGER),
+      }); break;
+      case 'boolean': check = Type.Boolean(); break;
+      case 'null': check = Type.Null(); break;
+      case 'string': check = Type.String({
+        ...(node.minLength === undefined ? {} : { minLength: node.minLength }),
+        ...(node.maxLength === undefined ? {} : { maxLength: node.maxLength }),
+        ...(node.pattern === undefined ? {} : { pattern: node.pattern }),
+      }); break;
+      default: check = Type.Unknown();
+    }
+    if (node.enum) check = Type.Intersect([check, Type.Union(node.enum.map(item => item === null ? Type.Null() : Type.Literal(item)))]);
+    if (!Value.Check(check, current)) invalid(path);
+    if (kind === 'array' && Array.isArray(current)) {
+      if (current.length > 1000 - visited) throw new TypeError('Schema form data limit exceeded.');
+      return current.map((item, index) => visit(node.items ?? { type: 'string' }, item, [...path, String(index)], true));
+    }
+    if (kind === 'object' && current !== null && typeof current === 'object' && !Array.isArray(current)) {
+      const source = current as Record<string, unknown>;
+      const result: Record<string, unknown> = {};
+      for (const key of Object.keys(source)) {
+        if (!Object.hasOwn(node.properties ?? {}, key)) invalid([...path, key]);
+      }
+      for (const [key, child] of Object.entries(node.properties ?? {})) {
+        if (!isSchemaFormNodeVisible(child, value)) continue;
+        const own = Object.hasOwn(source, key);
+        const next = visit(child, own ? source[key] : undefined, [...path, key], node.required?.includes(key) ?? false);
+        if (own || next !== undefined) Object.defineProperty(result, key, { value: next, enumerable: true, writable: true, configurable: true });
+      }
+      return result;
+    }
+    return current;
+  }
+  const projected = visit(schema, value, [], true);
+  return {
+    data: projected !== null && typeof projected === 'object' && !Array.isArray(projected) ? projected as Record<string, unknown> : {},
+    errors,
+  };
+}
+
+export function validateSchemaFormValue(schema: SchemaFormSchema, value: unknown): SchemaFormValidationError[] {
+  return prepareSchemaFormValue(schema, value).errors;
+}