cabloy 5.1.248 → 5.1.250

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/analysis/controls.ts

@@ -0,0 +1,163 @@
+import z from 'zod';
+
+import type {
+  IAnalysisCapabilities,
+  IAnalysisPolicy,
+  IAnalysisSelection,
+  IResolvedAnalysis,
+  TypeAnalysisFunction,
+  TypeAnalysisMode,
+} from '../../types/analysis.ts';
+
+export const analysisFunctions = ['count', 'sum', 'avg', 'min', 'max'] as const;
+export const analysisReservedFields = new Set([
+  'groups',
+  'aggrs',
+  'where',
+  'joins',
+  'having',
+  'columns',
+  'orders',
+  'limit',
+  'offset',
+  'pageNo',
+  'pageSize',
+  'distinct',
+  'include',
+  'with',
+]);
+
+/** A deliberate validation/resource-bound error, also usable without an application context. */
+export class AnalysisError extends Error {
+  readonly code = 422;
+  readonly status = 422;
+}
+
+export function analysisFailure(message: string): never {
+  throw new AnalysisError(message);
+}
+
+function actionDefaults(policy: IAnalysisPolicy, mode: TypeAnalysisMode): IAnalysisSelection {
+  if (mode !== 'group' && mode !== 'aggregate') analysisFailure('Unknown analysis action');
+  const defaults = policy.defaults[mode];
+  if (!defaults) analysisFailure(`Analysis ${mode} action is not enabled`);
+  return defaults;
+}
+
+function columnArray(columns: readonly string[], max: number) {
+  return z
+    .array(z.enum([...columns]))
+    .min(1)
+    .max(max)
+    .superRefine((value, ctx) => {
+      if (new Set(value).size !== value.length) {
+        ctx.addIssue({ code: 'custom', message: 'Duplicate analysis columns are not allowed' });
+      }
+    });
+}
+
+/** Native array/object schemas preserve finite enums for query coercion and OpenAPI. */
+export function analysisControlSchemas(policy: IAnalysisPolicy, mode: TypeAnalysisMode) {
+  const defaults = actionDefaults(policy, mode);
+  const shape: Partial<Record<TypeAnalysisFunction, z.ZodType>> = {};
+  for (const fn of analysisFunctions) {
+    const columns = policy.aggrs[fn];
+    if (columns) shape[fn] = columnArray(columns, policy.limits.maxMetrics).optional();
+  }
+  const aggrs = z
+    .strictObject(shape)
+    .superRefine((value, ctx) => {
+      const count = Object.values(value).reduce<number>(
+        (total, columns) => total + (Array.isArray(columns) ? columns.length : 0),
+        0,
+      );
+      if (count === 0 || count > policy.limits.maxMetrics) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `Analysis requires 1 to ${policy.limits.maxMetrics} metrics`,
+        });
+      }
+    })
+    .default(() =>
+      Object.fromEntries(
+        Object.entries(defaults.aggrs).map(([fn, columns]) => [fn, [...columns!]]),
+      ),
+    );
+  const groups =
+    mode === 'group'
+      ? columnArray(policy.groups, policy.limits.maxGroups).default(() => [...defaults.groups!])
+      : undefined;
+  const selection = z.strictObject({ groups: groups ?? z.never().optional(), aggrs });
+  return { groups, aggrs, selection };
+}
+
+/** Validate controls independently of row filters and ignored list controls. */
+export function resolveAnalysis(
+  policy: IAnalysisPolicy,
+  mode: TypeAnalysisMode,
+  input?: unknown,
+): IResolvedAnalysis {
+  if (input !== undefined && (!input || typeof input !== 'object' || Array.isArray(input))) {
+    analysisFailure('Analysis parameters must be an object');
+  }
+  const params = (input ?? {}) as Record<string, unknown>;
+  for (const key of ['joins', 'having', 'distinct', 'include', 'with']) {
+    if (Object.hasOwn(params, key) && params[key] !== undefined) {
+      analysisFailure(`Analysis does not support ${key}`);
+    }
+  }
+  if (mode === 'aggregate' && Object.hasOwn(params, 'groups')) {
+    analysisFailure('Aggregate analysis does not support groups');
+  }
+  // The request context can enable generic query coercion. Direct service calls must
+  // still supply native arrays/objects, never JSON strings or coerced scalar items.
+  const assertNativeColumns = (columns: unknown) => {
+    if (!Array.isArray(columns) || columns.some(column => typeof column !== 'string')) {
+      analysisFailure('Analysis columns must be arrays of strings');
+    }
+  };
+  if (params.groups !== undefined) assertNativeColumns(params.groups);
+  if (params.aggrs !== undefined) {
+    if (!params.aggrs || typeof params.aggrs !== 'object' || Array.isArray(params.aggrs)) {
+      analysisFailure('Analysis metrics must be an object of column arrays');
+    }
+    for (const columns of Object.values(params.aggrs)) assertNativeColumns(columns);
+  }
+  const parsed = analysisControlSchemas(policy, mode).selection.safeParse({
+    ...(mode === 'group' ? { groups: params.groups } : {}),
+    aggrs: params.aggrs,
+  });
+  if (!parsed.success) analysisFailure(parsed.error.message);
+  const result: IResolvedAnalysis = { aggrs: {} };
+  if (mode === 'group') {
+    // Canonical policy order also stabilizes SQL/cache keys for equivalent selections.
+    const selected = parsed.data.groups as string[];
+    result.groups = policy.groups.filter(column => selected.includes(column));
+  }
+  for (const fn of analysisFunctions) {
+    const selected = parsed.data.aggrs[fn] as string[] | undefined;
+    if (selected) result.aggrs[fn] = policy.aggrs[fn]!.filter(column => selected.includes(column));
+  }
+  return result;
+}
+
+export function analysisCapabilities(
+  policy: IAnalysisPolicy,
+  mode: TypeAnalysisMode,
+): IAnalysisCapabilities {
+  const defaults = actionDefaults(policy, mode);
+  return {
+    mode,
+    groups: mode === 'group' ? [...policy.groups] : [],
+    aggrs: Object.fromEntries(
+      Object.entries(policy.aggrs).map(([fn, columns]) => [fn, [...columns!]]),
+    ),
+    defaults: {
+      ...(mode === 'group' ? { groups: [...defaults.groups!] } : {}),
+      aggrs: Object.fromEntries(
+        Object.entries(defaults.aggrs).map(([fn, columns]) => [fn, [...columns!]]),
+      ),
+    },
+    limits: { ...policy.limits },
+  };
+}

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/analysis/execute.ts

@@ -0,0 +1,49 @@
+import type {
+  IAnalysisPolicy,
+  TypeAnalysisAggregateParams,
+  TypeAnalysisAggregateResult,
+  TypeAnalysisGroupParams,
+  TypeAnalysisGroupResult,
+} from '../../types/analysis.ts';
+import type { TypeModelOfModelLike } from '../../types/relations.ts';
+import type { BeanModelCache } from '../bean.model/bean.model_cache.ts';
+
+import { analysisFailure, resolveAnalysis } from './controls.ts';
+
+function assertModel(model: object, policy: IAnalysisPolicy) {
+  if (!(model instanceof policy.modelClass))
+    analysisFailure('Analysis policy does not belong to this model');
+}
+
+/** Keep instance/soft-delete scope, caching and scalar normalization owned by the ORM. */
+export async function $executeAnalysisGroup<Policy extends IAnalysisPolicy>(
+  model: TypeModelOfModelLike<Policy['modelLike']>,
+  policy: Policy,
+  params?: TypeAnalysisGroupParams<Policy>,
+): Promise<TypeAnalysisGroupResult<Policy>[]> {
+  assertModel(model, policy);
+  const { groups, aggrs } = resolveAnalysis(policy, 'group', params);
+  const rows = await (model as unknown as BeanModelCache<any>).group({
+    where: params?.where,
+    groups: groups!,
+    aggrs,
+    orders: groups!.map(column => [column, 'asc']),
+    limit: policy.limits.maxGroupRows + 1,
+  });
+  if (rows.length > policy.limits.maxGroupRows)
+    analysisFailure(`Analysis exceeds ${policy.limits.maxGroupRows} group rows`);
+  return rows as TypeAnalysisGroupResult<Policy>[];
+}
+
+export async function $executeAnalysisAggregate<Policy extends IAnalysisPolicy>(
+  model: TypeModelOfModelLike<Policy['modelLike']>,
+  policy: Policy,
+  params?: TypeAnalysisAggregateParams<Policy>,
+): Promise<TypeAnalysisAggregateResult<Policy>> {
+  assertModel(model, policy);
+  const { aggrs } = resolveAnalysis(policy, 'aggregate', params);
+  return (await (model as unknown as BeanModelCache<any>).aggregate({
+    where: params?.where,
+    aggrs,
+  })) as TypeAnalysisAggregateResult<Policy>;
+}

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/analysis/index.ts

@@ -0,0 +1,3 @@
+export * from './controls.ts';
+export * from './execute.ts';
+export * from './policy.ts';

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/analysis/policy.ts

@@ -0,0 +1,140 @@
+import { ZodMetadata } from '@cabloy/zod-openapi';
+import { getTargetDecoratorRules } from 'vona-module-a-openapiutils';
+
+import type {
+  IAnalysisConfig,
+  IAnalysisPolicy,
+  TypeAnalysisAggrs,
+  TypeAnalysisAllowedAggrs,
+  TypeAnalysisEntity,
+  TypeAnalysisField,
+  TypeAnalysisFunction,
+  TypeAnalysisModelLike,
+  TypeAnalysisPolicy,
+} from '../../types/analysis.ts';
+
+import { getClassEntityFromClassModel, prepareClassModel } from '../../common/utils.ts';
+import { analysisFunctions, analysisReservedFields, resolveAnalysis } from './controls.ts';
+
+function invalid(message: string): never {
+  throw new TypeError(`Invalid analysis policy: ${message}`);
+}
+
+function assertColumns(
+  columns: unknown,
+  label: string,
+  allowEmpty = false,
+): asserts columns is string[] {
+  if (!Array.isArray(columns) || (!allowEmpty && columns.length === 0))
+    invalid(`${label} must be a nonempty column array`);
+  if (columns.some(column => typeof column !== 'string'))
+    invalid(`${label} columns must be strings`);
+  if (new Set(columns).size !== columns.length) invalid(`${label} contains duplicate columns`);
+}
+
+function copyAggrs(aggrs: TypeAnalysisAggrs): TypeAnalysisAggrs {
+  return Object.freeze(
+    Object.fromEntries(
+      Object.entries(aggrs).map(([fn, columns]) => [fn, Object.freeze([...columns!])]),
+    ),
+  );
+}
+
+/** Static model/entity metadata only: safe while DTO classes are being evaluated. */
+export function $defineAnalysis<
+  ModelLike extends TypeAnalysisModelLike,
+  const Groups extends readonly TypeAnalysisField<TypeAnalysisEntity<ModelLike>>[],
+  const Aggrs extends TypeAnalysisAllowedAggrs<TypeAnalysisEntity<ModelLike>>,
+>(
+  modelLike: ModelLike,
+  config: IAnalysisConfig<Groups, Aggrs> & {
+    aggrs: Aggrs & Record<Exclude<keyof Aggrs, TypeAnalysisFunction>, never>;
+  },
+): TypeAnalysisPolicy<ModelLike, Groups, Aggrs> {
+  const modelClass = prepareClassModel(modelLike as any);
+  const entityClass = getClassEntityFromClassModel(modelClass);
+  const rules = getTargetDecoratorRules(entityClass.prototype, true);
+  assertColumns(config.groups, 'groups', true);
+  const validateField = (column: string, numeric: boolean) => {
+    if (!/^[A-Z_]\w*$/i.test(column) || analysisReservedFields.has(column))
+      invalid(`unsupported column ${column}`);
+    if (!Object.hasOwn(rules, column)) invalid(`unknown entity column ${column}`);
+    const schema = ZodMetadata.unwrapChained(ZodMetadata.resolveLazySchema(rules[column]!));
+    if (numeric && (column === 'id' || column === 'iid' || schema.def.type !== 'number'))
+      invalid(`non-count metrics require numeric columns: ${column}`);
+  };
+  for (const column of config.groups) validateField(column, false);
+  if (!config.aggrs || typeof config.aggrs !== 'object' || Array.isArray(config.aggrs))
+    invalid('aggrs must be an object');
+  const aliases = new Set<string>(config.groups);
+  let metricCount = 0;
+  for (const [fn, columns] of Object.entries(config.aggrs)) {
+    if (!analysisFunctions.includes(fn as TypeAnalysisFunction))
+      invalid(`unsupported function ${fn}`);
+    assertColumns(columns, fn);
+    for (const column of columns) {
+      if (column !== '*' || fn !== 'count') validateField(column, fn !== 'count');
+      const alias = `${fn}_${column === '*' ? 'all' : column}`;
+      if (aliases.has(alias) || analysisReservedFields.has(alias))
+        invalid(`alias collision: ${alias}`);
+      aliases.add(alias);
+      metricCount++;
+    }
+  }
+  if (metricCount === 0) invalid('at least one allowed metric is required');
+  const limits = { maxGroups: 3, maxMetrics: 10, maxGroupRows: 1000, ...config.limits };
+  for (const [key, value] of Object.entries(limits)) {
+    if (
+      !['maxGroups', 'maxMetrics', 'maxGroupRows'].includes(key) ||
+      !Number.isSafeInteger(value) ||
+      value < 1 ||
+      value >= Number.MAX_SAFE_INTEGER
+    ) {
+      invalid(`invalid limit ${key}`);
+    }
+  }
+  if (
+    !config.defaults ||
+    Object.keys(config.defaults).some(key => key !== 'group' && key !== 'aggregate')
+  ) {
+    invalid('unknown or missing action defaults');
+  }
+  if (!config.defaults.group && !config.defaults.aggregate)
+    invalid('at least one action default is required');
+  const policy: IAnalysisPolicy = {
+    modelLike,
+    modelClass,
+    groups: Object.freeze([...config.groups]),
+    aggrs: copyAggrs(config.aggrs),
+    defaults: {},
+    limits: Object.freeze(limits),
+  };
+  const defaults: {
+    group?: IAnalysisPolicy['defaults']['group'];
+    aggregate?: IAnalysisPolicy['defaults']['aggregate'];
+  } = {};
+  for (const mode of ['group', 'aggregate'] as const) {
+    const input = config.defaults[mode];
+    if (!input) continue;
+    // Do not allow omitted defaults to expand authorization implicitly.
+    if (!Object.hasOwn(input, 'aggrs') || (mode === 'group' && !Object.hasOwn(input, 'groups')))
+      invalid(`incomplete ${mode} defaults`);
+    if (Object.keys(input).some(key => key !== 'aggrs' && !(mode === 'group' && key === 'groups')))
+      invalid(`unsupported ${mode} default control`);
+    const forValidation = { ...policy, defaults: { [mode]: input } } as IAnalysisPolicy;
+    try {
+      const resolved = resolveAnalysis(forValidation, mode, input);
+      const aggrs = copyAggrs(resolved.aggrs);
+      if (mode === 'group')
+        defaults.group = Object.freeze({ groups: Object.freeze(resolved.groups!), aggrs });
+      else defaults.aggregate = Object.freeze({ aggrs });
+    } catch (error) {
+      invalid(`${mode} defaults: ${(error as Error).message}`);
+    }
+  }
+  return Object.freeze({ ...policy, defaults: Object.freeze(defaults) }) as TypeAnalysisPolicy<
+    ModelLike,
+    Groups,
+    Aggrs
+  >;
+}

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/bean.model/bean.model_cache.ts

@@ -20,6 +20,7 @@ import type {
   IModelSelectAggrParams,
   IModelSelectCountParams,
   IModelSelectGroupParams,
+  IModelSelectGeneralParams,
   IModelSelectParams,
   IModelUpdateOptions,
   ITableRecord,
@@ -34,6 +35,7 @@ import type {
 } from '../../types/index.ts';
 
 import { getTargetColumnName } from '../../common/utils.ts';
+import { normalizeAggregateRows } from '../../lib/aggregateResult.ts';
 import { getCacheModelsClear } from '../../lib/const.ts';
 import { ServiceCacheEntity } from '../../service/cacheEntity_.ts';
 import { ServiceCacheQuery } from '../../service/cacheQuery_.ts';
@@ -425,7 +427,7 @@ export class BeanModelCache<TRecord extends {} = {}> extends BeanModelCrud<TReco
 
   private async __select_cache(
     table: keyof ITableRecord,
-    params?: IModelSelectParams<TRecord>,
+    params?: IModelSelectParams<TRecord> & Pick<IModelSelectGeneralParams<TRecord>, 'aggrs'>,
     options?: IModelMethodOptions,
   ): Promise<TRecord[]> {
     // check if cache
@@ -445,7 +447,7 @@ export class BeanModelCache<TRecord extends {} = {}> extends BeanModelCrud<TReco
       },
       db: this.db,
     });
-    return items;
+    return normalizeAggregateRows(items, params?.aggrs);
   }
 
   async get<T extends IModelGetOptions<TRecord>>(

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/bean.model/bean.model_crud_inner.ts

@@ -18,6 +18,7 @@ import type {
   TypeModelWhere,
 } from '../../types/index.ts';
 
+import { normalizeAggregateRows, normalizeAggregateValue } from '../aggregateResult.ts';
 import { BeanModelView } from './bean.model_view.ts';
 
 export class BeanModelCrudInner<TRecord extends {}> extends BeanModelView<TRecord> {
@@ -66,7 +67,8 @@ export class BeanModelCrudInner<TRecord extends {}> extends BeanModelView<TRecor
   }
 
   protected async _select<
-    T extends IModelSelectParams<TRecord> | IBuildModelSelectParams<TRecord, undefined, never>,
+    T extends (IModelSelectParams<TRecord> | IBuildModelSelectParams<TRecord, undefined, never>) &
+      Pick<IModelSelectGeneralParams<TRecord>, 'aggrs'>,
   >(
     table?: keyof ITableRecord,
     params?: T,
@@ -89,7 +91,10 @@ export class BeanModelCrudInner<TRecord extends {}> extends BeanModelView<TRecor
       }
       return `model.select: ${tip}, ${builder.toQuery()}`;
     });
-    return (await this.dialect.select(builder, datas, () => this.columns(table))) as TRecord[];
+    const rows = (await this.dialect.select(builder, datas, () =>
+      this.columns(table),
+    )) as TRecord[];
+    return normalizeAggregateRows(rows, params?.aggrs);
   }
 
   protected _select_buildParams<T extends IModelSelectGeneralParams<TRecord>>(
@@ -164,7 +169,7 @@ export class BeanModelCrudInner<TRecord extends {}> extends BeanModelView<TRecor
     // ready
     this.$loggerChild('model').debug(() => `model.count: ${builder.toQuery()}`);
     const res = await builder;
-    return this.extractFirstNumber(res);
+    return normalizeAggregateValue(this.extractFirstValue(res), 'count');
   }
 
   protected async _increment(

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/dto/dto.ts

@@ -1,4 +1,5 @@
 import { DtoAggregate } from './dtoAggregate.ts';
+import { DtoAnalysisAggregate, DtoAnalysisGroup } from './dtoAnalysis.ts';
 import { DtoCreate } from './dtoCreate.ts';
 import { DtoGet } from './dtoGet.ts';
 import { DtoGroup } from './dtoGroup.ts';
@@ -15,6 +16,8 @@ export const $Dto = {
   mutate: DtoMutate,
   get: DtoGet,
   aggregate: DtoAggregate,
+  analysisGroup: DtoAnalysisGroup,
+  analysisAggregate: DtoAnalysisAggregate,
   group: DtoGroup,
   query: DtoQuery,
   queryPage: DtoQueryPage,

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/dto/dtoAggregate.ts

@@ -56,7 +56,10 @@ export function _DtoAggregate_inner<
     if (!columns) continue;
     for (const column of columns) {
       const column2 = `${key}_${column === '*' ? 'all' : column}`;
-      Api.field(v.optional(), z.string())(classTarget.prototype, column2);
+      Api.field(v.optional(), key === 'count' ? z.string() : z.string().nullable())(
+        classTarget.prototype,
+        column2,
+      );
     }
   }
   return classTarget as any;

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/dto/dtoAnalysis.ts

@@ -0,0 +1,34 @@
+import type { Constructable } from 'vona';
+
+import { $Class } from 'vona';
+
+import type {
+  IAnalysisPolicy,
+  TypeAnalysisAggregateResult,
+  TypeAnalysisGroupResult,
+} from '../../types/analysis.ts';
+
+import { _DtoAggregate_inner } from './dtoAggregate.ts';
+import { DtoGroup } from './dtoGroup.ts';
+
+/** A finite optional superset: absent fields are unrequested, null retains SQL meaning. */
+export function DtoAnalysisGroup<Policy extends IAnalysisPolicy>(
+  policy: Policy,
+): Constructable<TypeAnalysisGroupResult<Policy>> {
+  if (!policy.defaults.group) throw new TypeError('Analysis group action is not enabled');
+  const base = DtoGroup(policy.modelLike as any, [...policy.groups] as any, policy.aggrs as any);
+  return $Class.partial(base) as Constructable<TypeAnalysisGroupResult<Policy>>;
+}
+
+export function DtoAnalysisAggregate<Policy extends IAnalysisPolicy>(
+  policy: Policy,
+): Constructable<TypeAnalysisAggregateResult<Policy>> {
+  if (!policy.defaults.aggregate) throw new TypeError('Analysis aggregate action is not enabled');
+  abstract class TargetClass {}
+  // Aggregate aliases deliberately do not copy field validators/renderers from source columns.
+  return _DtoAggregate_inner(
+    TargetClass as any,
+    policy.modelLike as any,
+    policy.aggrs as any,
+  ) as Constructable<TypeAnalysisAggregateResult<Policy>>;
+}

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/lib/index.ts

@@ -1,3 +1,4 @@
+export * from './analysis/index.ts';
 export * from './const.ts';
 export * from './databaseDialect.ts';
 export * from './dto/index.ts';

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/types/analysis.ts

@@ -0,0 +1,137 @@
+import type { Constructable } from 'vona';
+
+import type { BeanModelMeta } from '../lib/bean.model/bean.model_meta.ts';
+import type { TypeModelWhere } from './modelWhere.ts';
+import type { IModelClassRecord } from './onion/model.ts';
+import type { TypeModelOfModelLike, TypeSymbolKeyEntity } from './relations.ts';
+
+export type TypeAnalysisMode = 'group' | 'aggregate';
+export type TypeAnalysisFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+export type TypeAnalysisModelLike =
+  | Constructable<BeanModelMeta>
+  | (() => Constructable<BeanModelMeta>)
+  | keyof IModelClassRecord;
+export type TypeAnalysisEntity<ModelLike extends TypeAnalysisModelLike> =
+  TypeModelOfModelLike<ModelLike>[TypeSymbolKeyEntity];
+export type TypeAnalysisField<Entity> = Extract<keyof Entity, string>;
+export type TypeAnalysisNumericField<Entity> = Exclude<
+  {
+    [K in keyof Entity]-?: NonNullable<Entity[K]> extends number ? K : never;
+  }[keyof Entity],
+  'id' | 'iid'
+> &
+  string;
+
+export type TypeAnalysisAggrs = Partial<Record<TypeAnalysisFunction, readonly string[]>>;
+export type TypeAnalysisAllowedAggrs<Entity> = {
+  readonly count?: readonly ('*' | TypeAnalysisField<Entity>)[];
+} & {
+  readonly [
+    K in Exclude<TypeAnalysisFunction, 'count'>
+  ]?: readonly TypeAnalysisNumericField<Entity>[];
+};
+export type TypeAnalysisSelectionAggrs<Aggrs extends TypeAnalysisAggrs> = {
+  readonly [K in keyof Aggrs]?: NonNullable<Aggrs[K]> extends readonly string[]
+    ? readonly NonNullable<Aggrs[K]>[number][]
+    : never;
+};
+export interface IAnalysisLimits {
+  readonly maxGroups: number;
+  readonly maxMetrics: number;
+  readonly maxGroupRows: number;
+}
+export interface IAnalysisSelection {
+  readonly groups?: readonly string[];
+  readonly aggrs: TypeAnalysisAggrs;
+}
+
+/** Structural server-owned policy surface; model references must not be serialized. */
+export interface IAnalysisPolicy {
+  readonly modelLike: TypeAnalysisModelLike;
+  readonly modelClass: Constructable<BeanModelMeta>;
+  readonly groups: readonly string[];
+  readonly aggrs: TypeAnalysisAggrs;
+  readonly defaults: {
+    readonly group?: IAnalysisSelection & { readonly groups: readonly string[] };
+    readonly aggregate?: { readonly aggrs: TypeAnalysisAggrs };
+  };
+  readonly limits: IAnalysisLimits;
+}
+export type TypeAnalysisPolicy<
+  ModelLike extends TypeAnalysisModelLike,
+  Groups extends readonly string[],
+  Aggrs extends TypeAnalysisAggrs,
+> = Omit<IAnalysisPolicy, 'modelLike' | 'groups' | 'aggrs'> & {
+  readonly modelLike: ModelLike;
+  readonly groups: Groups;
+  readonly aggrs: Aggrs;
+};
+export interface IAnalysisConfig<
+  Groups extends readonly string[],
+  Aggrs extends TypeAnalysisAggrs,
+> {
+  readonly groups: Groups;
+  readonly aggrs: Aggrs;
+  readonly defaults: {
+    readonly group?: {
+      readonly groups: readonly NoInfer<Groups[number]>[];
+      readonly aggrs: TypeAnalysisSelectionAggrs<NoInfer<Aggrs>>;
+    };
+    readonly aggregate?: { readonly aggrs: TypeAnalysisSelectionAggrs<NoInfer<Aggrs>> };
+  };
+  readonly limits?: Partial<IAnalysisLimits>;
+}
+
+interface IAnalysisParams<Policy extends IAnalysisPolicy> {
+  where?: TypeModelWhere<TypeAnalysisEntity<Policy['modelLike']>>;
+  aggrs?: TypeAnalysisSelectionAggrs<Policy['aggrs']>;
+  // Existing list controls remain accepted but never drive analysis execution.
+  columns?: unknown;
+  orders?: unknown;
+  limit?: number;
+  offset?: number;
+  pageNo?: number;
+  pageSize?: number;
+  joins?: never;
+  having?: never;
+  distinct?: never;
+  include?: never;
+  with?: never;
+}
+export type TypeAnalysisGroupParams<Policy extends IAnalysisPolicy> = IAnalysisParams<Policy> & {
+  groups?: readonly Policy['groups'][number][];
+};
+export type TypeAnalysisAggregateParams<Policy extends IAnalysisPolicy> =
+  IAnalysisParams<Policy> & {
+    groups?: never;
+  };
+
+type TypeAnalysisAlias<Column extends string> = Column extends '*' ? 'all' : Column;
+export type TypeAnalysisAggregateResult<Policy extends IAnalysisPolicy> = {
+  -readonly [
+    Fn in keyof Policy['aggrs'] &
+      TypeAnalysisFunction as Policy['aggrs'][Fn] extends readonly string[]
+      ? `${Fn}_${TypeAnalysisAlias<Policy['aggrs'][Fn][number]>}`
+      : never
+  ]?: Fn extends 'count' ? string : string | null;
+};
+export type TypeAnalysisGroupResult<Policy extends IAnalysisPolicy> = Partial<
+  Pick<
+    TypeAnalysisEntity<Policy['modelLike']>,
+    Extract<Policy['groups'][number], keyof TypeAnalysisEntity<Policy['modelLike']>>
+  >
+> &
+  TypeAnalysisAggregateResult<Policy>;
+
+export interface IAnalysisCapabilities {
+  readonly mode: TypeAnalysisMode;
+  readonly groups: readonly string[];
+  readonly aggrs: TypeAnalysisAggrs;
+  readonly defaults: IAnalysisSelection;
+  readonly limits: IAnalysisLimits;
+}
+
+export interface IResolvedAnalysis {
+  groups?: string[];
+  aggrs: Partial<Record<TypeAnalysisFunction, string[]>>;
+}

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/types/index.ts

@@ -1,3 +1,4 @@
+export * from './analysis.ts';
 export * from './columns.ts';
 export * from './config.ts';
 export * from './database.ts';

package/vona/src/suite-vendor/a-vona/modules/a-orm/src/types/relationsAggr.ts

@@ -27,7 +27,7 @@ export type TypeUtilAggrPrepareColumns<TColumns> = TColumns extends string[]
     : undefined;
 export type TypeRecordAggrsValues<TRecord extends Record<string, any>> = TRecord[keyof TRecord];
 export type TypeRecordAggrsValuesToObject<AggrValues extends string> = {
-  [K in AggrValues]: string | undefined;
+  [K in AggrValues]: K extends `count_${string}` ? string | undefined : string | null | undefined;
 };
 
 export type TypeUtilGetAggrsFromRelationAndIncludeWrapper<