cabloy 5.1.248 → 5.1.250

package/repo-agent-governance/tools/spec-charts/generate-implementation-charts.test.mjs

@@ -155,7 +155,7 @@ test('creates a mixed-status model with deferred scope separated', () => {
   assert.doesNotMatch(renderGantt(model, 'Demo'), /--teal:/);
 });
 
-test('planning completion requires an explicit task mode and preserves verified-only metrics', () => {
+test('planning completion requires an explicit task mode and reduces only unfinished scope', () => {
   const wbs = files['pdp-wbs.md'].replace(
     '#### WBS-10-01: Freeze the baseline',
     '#### WBS-10-01: Freeze the baseline\n\nCompletion mode: planning-only.',
@@ -179,13 +179,16 @@ test('planning completion requires an explicit task mode and preserves verified-
   });
   assert.equal(model.tasks[0].completionMode, 'planning-only');
   assert.equal(model.verified, 0);
+  assert.equal(model.planningComplete, 1);
+  assert.equal(model.completed, 1);
+  assert.equal(model.remaining, 1);
   const gantt = renderGantt(model, 'Demo');
   assert.match(gantt, /Planning complete/);
   assert.match(gantt, /--teal:#087f83/);
-  assert.doesNotMatch(renderBurndown(model, 'Demo'), /--teal:/);
+  assert.match(renderBurndown(model, 'Demo'), /--teal:#087f83/);
   assert.match(gantt, /class="caption" x="96" y="195">WBS-20-01: Deliver/);
   assert.doesNotMatch(gantt, /class="caption" x="96" y="195">WBS-10-01/);
-  assert.match(renderBurndown(model, 'Demo'), />2 remaining · 0 verified</);
+  assert.match(renderBurndown(model, 'Demo'), />1 remaining · 0 verified · 1 planning complete</);
   const blocked = createChartModel({
     readme: files['README.md'],
     wbs,
@@ -201,7 +204,91 @@ test('planning completion requires an explicit task mode and preserves verified-
     testPlan: files['test-plan.md'],
   });
   assert.match(renderGantt(chinese, '示例'), /规划完成/);
-  assert.match(renderBurndown(chinese, '示例'), /2 剩余 · 0 已核验/);
+  assert.match(renderBurndown(chinese, '示例'), /1 剩余 · 0 已核验 · 1 规划完成/);
+});
+
+test('verified and planning closure finish scope without conflating acceptance', () => {
+  for (const [readme, suite] of [
+    [files['README.md'], 'Demo'],
+    ['# 中文规划\n完整中文记录。', '示例'],
+  ]) {
+    const model = createChartModel({
+      readme,
+      wbs: files['pdp-wbs.md'].replace(
+        '#### WBS-10-01: Freeze the baseline',
+        '#### WBS-10-01: Freeze the baseline\nCompletion mode: planning-only.',
+      ),
+      progress: files['progress.md']
+        .replace('`not-started`', '`planning-complete`')
+        .replace('`in-progress`', '`verified`'),
+      testPlan: files['test-plan.md'],
+    });
+    assert.equal(model.activeTasks.length, 2);
+    assert.equal(model.deferredTasks.length, 1);
+    assert.equal(model.verified, 1);
+    assert.equal(model.planningComplete, 1);
+    assert.equal(model.completed, 2);
+    assert.equal(model.remaining, 0);
+    const svg = renderBurndown(model, suite);
+    assert.match(svg, /<circle cx="910\.0" cy="650\.0" r="14"/);
+    if (model.language === 'en') {
+      assert.match(svg, />0 remaining · 1 verified · 1 planning complete</);
+      assert.match(svg, /remaining = active scope − verified − planning complete/);
+      assert.match(
+        svg,
+        /aria-label="Phase 10: 1 active; 0 verified; 1 planning complete; 0 remaining"/,
+      );
+      assert.match(
+        svg,
+        /aria-label="Phase 20: 1 active; 1 verified; 0 planning complete; 0 remaining"/,
+      );
+      assert.match(svg, /<text class="small" x="1228" y="832">Planning complete</);
+    } else {
+      assert.match(svg, />0 剩余 · 1 已核验 · 1 规划完成</);
+      assert.match(svg, /剩余 = 活跃范围 − 已核验 − 规划完成/);
+      assert.match(svg, /aria-label="阶段 10：1 项活跃；0 项已核验；1 项规划完成；0 项剩余"/);
+      assert.match(svg, /<text class="small" x="1228" y="832">规划完成</);
+    }
+  }
+});
+
+test('unfinished statuses remain unfinished and mixed phase counts agree with scope', () => {
+  const statuses = [
+    'verified',
+    'planning-complete',
+    'not-started',
+    'in-progress',
+    'implementation-complete',
+    'blocked',
+    'waived',
+    'deferred',
+  ];
+  const model = createChartModel({
+    readme: files['README.md'],
+    wbs: `### Phase 10: Mixed closure\nDependencies: none.\n${statuses
+      .map(
+        (status, index) =>
+          `#### WBS-MIX-${index}: Work ${index}\n${status === 'planning-complete' ? 'Completion mode: planning-only.\n' : ''}`,
+      )
+      .join('\n')}`,
+    progress: `| WBS ID | Status |\n| --- | --- |\n${statuses.map((status, index) => `| WBS-MIX-${index} | ${status} |`).join('\n')}`,
+    testPlan: '',
+  });
+  assert.equal(model.activeTasks.length, 7);
+  assert.equal(model.deferredTasks.length, 1);
+  assert.equal(model.verified, 1);
+  assert.equal(model.planningComplete, 1);
+  assert.equal(model.completed, 2);
+  assert.equal(model.remaining, 5);
+  const svg = renderBurndown(model, 'Demo');
+  assert.match(
+    svg,
+    /aria-label="Phase 10: 7 active; 1 verified; 1 planning complete; 5 remaining"/,
+  );
+  assert.match(svg, />5 remaining · 1 verified · 1 planning complete</);
+  assert.match(svg, /<circle cx="395\.7" cy="478\.6" r="8"/);
+  assert.match(svg, /width="60" height="12" rx="6" fill="var\(--aqua\)"/);
+  assert.doesNotMatch(svg, /r="14" fill="var\(--aqua\)"/);
 });
 
 test('completion mode must be unique, supported and task-local', () => {
@@ -325,7 +412,7 @@ test('renders partial burndown progress at its remaining-count position', async
   t.after(() => removeFixture(directory));
   const result = await generateCharts(directory);
   const burndown = result.artifacts.get('implementation-burndown.svg');
-  assert.match(burndown, />1 remaining · 1 verified</);
+  assert.match(burndown, />1 remaining · 1 verified · 0 planning complete</);
   assert.match(burndown, />2 remaining</);
   assert.doesNotMatch(burndown, />0 \/ 2</);
   assert.match(
@@ -348,7 +435,7 @@ test('renders a completion marker only when no WBS items remain', async t => {
   });
   t.after(() => removeFixture(directory));
   const burndown = (await generateCharts(directory)).artifacts.get('implementation-burndown.svg');
-  assert.match(burndown, />0 remaining · 2 verified</);
+  assert.match(burndown, />0 remaining · 2 verified · 0 planning complete</);
   assert.match(burndown, /<line x1="190" y1="410" x2="910\.0" y2="650\.0"/);
   assert.match(burndown, /<circle cx="910\.0" cy="650\.0" r="14"/);
   assert.match(burndown, /M904\.0 650\.0 L908\.0 654\.0 L916\.0 645\.0/);
@@ -755,7 +842,7 @@ test('Chinese descriptions, tooltips, aria labels, and fallback copy contain no
   assert.match(gantt, /aria-label="WBS-ZH-01: 示例工作; 依赖: 无; 受阻"/);
   assert.match(gantt, /<title>WBS-ZH-01: 示例工作; 依赖: 无; 受阻<\/title>/);
   assert.match(gantt, /没有已记录的依赖就绪 WBS 候选项/);
-  assert.match(burndown, /aria-label="阶段 10：0 \/ 1 项已核验"/);
+  assert.match(burndown, /aria-label="阶段 10：1 项活跃；0 项已核验；0 项规划完成；1 项剩余"/);
   assert.match(gantt, /依赖就绪不代表实施批准/);
   assert.match(burndown, /已记录 WBS 范围/);
 });
@@ -833,6 +920,10 @@ test('writes deterministic XML-escaped artifacts and detects stale output', asyn
     /implementation-gantt\.svg/,
   );
   const second = await generateCharts(directory);
+  assert.equal(
+    second.artifacts.get('implementation-burndown.svg'),
+    first.artifacts.get('implementation-burndown.svg'),
+  );
   assert.equal(
     second.artifacts.get('implementation-gantt.svg'),
     first.artifacts.get('implementation-gantt.svg'),

package/repo-docs/ai/playbook-spec-execution.md

@@ -132,7 +132,7 @@ Use status precisely:
 - `implementation-complete` — source work is complete, but required ATP or release proof remains
 - `verified` — all applicable WBS checks and ATPs have durable, linked, redacted observed evidence
 
-`planning-complete` satisfies a predecessor dependency edge but does not unblock a task still recorded `blocked` or grant an execution dossier. Charts count only `verified` toward verified/remaining metrics. A successful build, generation command, hook, manual walkthrough, screenshot, or unrelated test run is not by itself `verified` unless the authoritative test plan defines it as sufficient retained proof. Evidence is revision- and authority-scoped; mark old proof superseded or requiring rerun when relevant source or authority changes.
+`planning-complete` satisfies a predecessor dependency edge but does not unblock a task still recorded `blocked` or grant an execution dossier. Charts count only `verified` toward verified totals and show eligible `planning-complete` closure separately. The burndown calculates remaining = active scope − verified − eligible planning-complete; deferred scope is separate, and all other active statuses remain unfinished. Documentary closure is not runtime ATP verification. A successful build, generation command, hook, manual walkthrough, screenshot, or unrelated test run is not by itself `verified` unless the authoritative test plan defines it as sufficient retained proof. Evidence is revision- and authority-scoped; mark old proof superseded or requiring rerun when relevant source or authority changes.
 
 ## Refresh derived charts last
 

package/repo-docs/backend/crud-workflow.md

@@ -28,6 +28,97 @@ npm run vona :tools:crudBasic student -- --module=training-student
 
 This is important because the repo already encodes both the full CRUD thread and a lighter CRUD-basic workflow in the CLI surface.
 
+## Grouping and statistics
+
+The Basic and Start CRUD generators provide `group` and `aggregate` read actions by default, alongside ordinary `select`:
+
+```bash
+npm run vona :tools:crud report -- --module=demo-report
+```
+
+The direct `:tools:crudBasic` and `:tools:crudStart` commands use the same default. There are no `--aggregate` or `--groupBy` options; edit the generated policy to configure analysis capabilities.
+
+| Generated action | Default result                           |
+| ---------------- | ---------------------------------------- |
+| `GET select`     | Resource records and pagination metadata |
+| `GET group`      | One row per name, with `count_all`       |
+| `GET aggregate`  | One object with `count_all`              |
+
+The generator exports one shared analysis policy in `src/lib/<resourceName>Analysis.ts`:
+
+```typescript
+export const reportAnalysis = $defineAnalysis(() => ModelReport, {
+  groups: ['name'],
+  aggrs: { count: ['*'] },
+  defaults: {
+    group: { groups: ['name'], aggrs: { count: ['*'] } },
+    aggregate: { aggrs: { count: ['*'] } },
+  },
+  limits: { maxGroups: 3, maxMetrics: 10, maxGroupRows: 1000 },
+});
+```
+
+Default API generation does not expose every Entity field. The initial allowlist contains only `name` and `count('*')`; it does not automatically allow `description`, identity fields, timestamps, or numeric metrics. Callers can select combinations only within that backend-owned policy, not arbitrary model columns or SQL expressions. No analysis capability fields are added to the Entity.
+
+Fresh CRUD entities contain `name`, so name grouping provides a runnable starting point, not a universal business default. Refine the policy to use meaningful dimensions such as status, category, or level as the resource evolves. Choose dimensions with suitable cardinality: grouping by a nearly unique name can return almost as many groups as records. Generated group actions do not provide group pagination or a group-count total.
+
+These commands create new resources and refuse an existing controller. Do not rerun them against the existing `training-student` resource to add actions. For an existing resource, define its policy and reuse it in the request DTO, response DTOs, and service; the Student reference uses its already-defined `level` field.
+
+### Query and response boundaries
+
+`select`, `group`, and `aggregate` remain separate contracts:
+
+- `select` returns resource records and existing pagination metadata.
+- `group` returns group keys and metrics, not nested lists of resource records.
+- `aggregate` returns metrics over all matching source records, not the current select page.
+
+The actions reuse the resource's `SelectReq`; no separate `AnalysisReq` is generated. `@Dto({ analysis: resourceAnalysis })` attaches the shared policy, and `@Arg.filter(SelectReq, { mode: 'group' })` or `{ mode: 'aggregate' }` derives that action's controls without adding them to ordinary select. Select rejects explicit analysis controls. The service uses `$executeAnalysisGroup(model, policy, params)` or `$executeAnalysisAggregate(model, policy, params)`, which also revalidate controls for direct service callers.
+
+A group request may select `groups: string[]` and `aggrs: { count?: string[]; sum?: string[]; avg?: string[]; min?: string[]; max?: string[] }`; an aggregate request accepts only `aggrs`. Every function and column must be allowed by the policy. Omitted controls independently use the action's defaults. Explicit empty selections, duplicates, unsupported functions/columns, and `groups` on aggregate fail validation rather than falling back or being stripped.
+
+Named local business filters and raw `where` retain their existing semantics. A raw predicate for a field takes precedence over that field's named-filter transformation. List projection, ordering, and pagination controls are still parsed and validated, but do not change analysis: statistics cover all matching source rows, not the current select page. Filters that require joins are rejected for analysis; ordinary select can still use its existing joined filters. Client `having`, joins, expressions, and custom aliases are not analysis controls. Keep server-side instance, soft-delete, and business authorization scope; caller-supplied predicates are not an authorization boundary.
+
+The default policy limits are 3 selected dimensions, 10 selected metric aliases, and 1000 group-result rows; a policy may set explicit limits. Group execution reads at most the row cap plus one and returns a deliberate `422` validation/resource-limit error on overflow, not a silently truncated result. These bounds do not limit the database work needed to scan or aggregate the matching population.
+
+Response DTOs use `$Dto.analysisGroup(policy)` / `$Dto.analysisAggregate(policy)` to describe a finite **optional superset** of allowed keys. Each response includes only requested dimensions and aliases. Optional means unrequested; nullable means a real SQL null. If a business-specific policy adds a nullable dimension, preserve both optionality and nullability in its response contract and never synthesize an unrequested key.
+
+Count aliases are decimal strings, normalized by the ORM query/cache boundary; non-count metrics are strings or SQL `null`. Services need no count-conversion helper. An empty group query returns `[]`; an empty aggregate count returns `"0"`. Missing dimension values are not synthesized into zero-valued groups.
+
+### Student policy and GET controls
+
+The Student reference exports this policy in `src/lib/studentAnalysis.ts`:
+
+```typescript
+export const studentAnalysis = $defineAnalysis(() => ModelStudent, {
+  groups: ['level'],
+  aggrs: { count: ['*', 'imageId'] },
+  defaults: {
+    group: { groups: ['level'], aggrs: { count: ['*'] } },
+    aggregate: { aggrs: { count: ['*', 'imageId'] } },
+  },
+});
+```
+
+Its default `GET /api/training/student/group` counts by `level`, ordered by level. Its default `GET /api/training/student/aggregate` returns `count_all` and `count_imageId` (students with a non-null image reference). A caller can request only `count_imageId`, without receiving `count_all` as an extra field. `name`, mobile, and raw timestamps are not allowed dimensions merely because the Entity contains them.
+
+For GET requests, encode array/object controls as JSON query values using the existing `combineQueries` convention. Generated API methods accept structured controls and handle that encoding. The equivalent raw request is:
+
+```bash
+curl --get 'http://localhost:7102/api/training/student/group' \
+  --data-urlencode 'groups=["level"]' \
+  --data-urlencode 'aggrs={"count":["imageId"]}'
+```
+
+Use the normal authenticated session for this protected action. Do not send comma-separated dimensions or JavaScript object text. Malformed JSON is invalid input. The existing `summary/:id` remains an individual Student summary, not population statistics.
+
+Action request schemas expose finite enums and `filter.capabilities.analysis` with the public allowlist, action defaults, mode, and effective limits, including on emitted `groups` / `aggrs` parameter schemas. Model/class references are not public capabilities. See [DTO Infer and Generation](/backend/dto-infer-generation#aggregate-and-group-dto-inference), [Validation Guide](/backend/validation-guide#analysis-action-modes), and [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide).
+
+### Authorization and source scope
+
+The generated analysis actions inherit the `select` RBAC policy. Policy inheritance does not apply row filtering or copy data-scope options. Normal model instance and soft-delete predicates remain active.
+
+For a resource that supports department/owner data scope, explicitly configure that scope and combine `rbacScopeCurrent.where(params.where)` **before** grouping or aggregation. Filtering group results afterward is not an authorization boundary. Do not enable ownership scope for Student or another resource that lacks the corresponding ownership fields. See [RBAC Authorization](/backend/rbac-authorization).
+
 ## Generated structure
 
 The generator creates a connected set of files, typically including:
@@ -45,7 +136,7 @@ This is exactly why this generator should be the default starting point. It give
 
 ### Generated authorization default
 
-The standard generated CRUD actions (`create`, `select`, `view`, `update`, and `delete`) each use `@Passport.systemAdmin()`. This is an explicit administrative whitelist for the generated Admin resource API, matching the generated SSR menu's `systemAdmin` visibility policy.
+The standard generated CRUD actions (`create`, `select`, `view`, `update`, and `delete`) each use `@Passport.rbac()`. Bulk delete inherits the `delete` policy. These guards authorize API execution independently of the generated SSR menu's visibility policy.
 
 The guard is attached to individual actions rather than the controller class. When you add a custom action later, no local Passport guard intentionally means the global authenticated-and-activated baseline applies; it does not mean the action is public. Use `@Passport.public()` to intentionally allow anonymous access, or add a role/domain guard when an action needs stronger restriction.
 

package/repo-docs/backend/dto-guide.md

@@ -124,11 +124,12 @@ Choose the scene from the API contract, not from the particular screen that happ
 
 ## DTO options
 
-Three especially important DTO option areas are:
+Important DTO option areas include:
 
 - `independent`
 - `openapi`
 - `fields`
+- `analysis` for backend-controlled, client-selectable group/aggregate contracts
 
 These options make DTOs configurable as reusable schema objects, not just local TypeScript classes.
 
@@ -138,6 +139,20 @@ A useful ownership rule is:
 - app config can still override broader DTO behavior
 - inference tools can reduce how much hand-authored DTO code is needed
 
+### DTO-owned analysis policy
+
+For client-selectable grouping or metrics, attach a shared backend policy with `@Dto({ analysis: studentAnalysis })`. Define it with `$defineAnalysis(() => ModelStudent, config)`, not Entity capability flags. `groups` allows physical dimensions; `aggrs` allows columns separately for each function (`count`, `sum`, `avg`, `min`, `max`). Count may allow `'*'`; non-count metrics require numeric columns. The model identity remains explicit even when the filter DTO's projection omits a legitimate metric column, such as Student `imageId`.
+
+Reuse that same exported policy in three places:
+
+- the filter DTO's `analysis` option and action-aware `@Arg.filter` modes
+- named response wrappers based on `$Dto.analysisGroup(policy)` / `$Dto.analysisAggregate(policy)`
+- service execution through `$executeAnalysisGroup(model, policy, params)` / `$executeAnalysisAggregate(model, policy, params)`
+
+Do not create a separate AnalysisReq or add analysis controls to ordinary select. The policy owns function/column allowlists, action defaults, and execution limits; response inference describes the finite optional field superset, while execution returns selected fields only. Optional is not nullable: an unrequested metric is absent, while a selected non-count metric can be SQL `null`.
+
+The derived action schemas publish frontend-readable `filter.capabilities.analysis` without model/class references. After changing the policy, regenerate affected OpenAPI/SDK consumers rather than duplicating the allowlist in frontend code. See [CRUD Workflow](/backend/crud-workflow#grouping-and-statistics), [DTO Infer and Generation](/backend/dto-infer-generation#aggregate-and-group-dto-inference), and [Validation Guide](/backend/validation-guide#analysis-action-modes) for the connected contract.
+
 ## App-config override support
 
 DTO options can also be configured through app config.

package/repo-docs/backend/dto-infer-generation.md

@@ -444,14 +444,32 @@ The test suite also shows the behavioral difference from a one-off `columns` sel
 
 ## Aggregate and group DTO inference
 
-Summary-oriented ORM queries often benefit from inferred DTOs because the result shape is driven by `aggrs`, `groups`, and relation configuration.
+Summary-oriented ORM queries often benefit from inferred DTOs because the result shape is driven by `aggrs`, `groups`, and relation configuration. For fixed server-authored query shapes, use `$Dto.aggregate(...)` / `$Dto.group(...)` and wrap a reused contract in a named DTO.
 
-A practical rule is:
+For a backend allowlist with client-selectable combinations, infer from one shared `$defineAnalysis` policy instead:
+
+```typescript
+@Dto({ analysis: studentAnalysis })
+export class DtoStudentSelectReq extends $Dto.queryPage(EntityStudent, [
+  'name',
+  'level',
+  'createdAt',
+]) {}
+
+@Dto()
+export class DtoStudentGroupResItem extends $Dto.analysisGroup(studentAnalysis) {}
+
+@Dto()
+export class DtoStudentAggregateRes extends $Dto.analysisAggregate(studentAnalysis) {}
+```
+
+These are abbreviated declarations; keep existing request field refinements such as Student's date-range transform. The policy explicitly identifies the Model, allowed dimensions, function-specific metric columns, per-action defaults, and limits. It can therefore allow `count('imageId')` even though `imageId` is not a named filter in SelectReq. No analysis capability flags belong on the Entity, and no separate AnalysisReq is needed.
+
+The response schema is a finite optional superset of all policy-permitted dimension and metric keys, not an unrestricted property map. Execution returns **requested keys only**, with fixed ORM aliases such as `count_all` and `count_imageId`. Group keys retain their column types; count aliases are decimal strings; non-count aliases are strings or SQL `null`. An optional property is unrequested, not a substitute for nullable. If refining a nullable description dimension, preserve both optionality and nullability (`description?: string | null`) and do not synthesize it when absent from the result.
 
-- if the summary shape comes directly from ORM query structure, inference is often the cleanest option
-- if the same summary contract is reused broadly, wrap the inferred DTO into a named DTO class
+Select, group, and aggregate remain separate action schemas. Attach the policy to SelectReq, then use `@Arg.filter(DtoStudentSelectReq, { mode: 'group' })` or `{ mode: 'aggregate' }` on the analysis action; ordinary select remains unchanged and rejects explicit analysis controls. The named wrappers keep response references distinct, while public action capabilities and enums come from the same policy.
 
-For the query side of this topic, also see [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide).
+See [CRUD Workflow](/backend/crud-workflow#grouping-and-statistics) for the Student policy, GET JSON controls, and generator workflow; [Validation Guide](/backend/validation-guide#analysis-action-modes) for defaults, validation, and limits; and [ORM Aggregate and Group Guide](/backend/orm-aggregate-group-guide) for the underlying model operations.
 
 ## How DTOs surface in generated metadata
 

package/repo-docs/backend/orm-aggregate-group-guide.md

@@ -92,6 +92,38 @@ A practical result-shape distinction is:
 - `aggregate` returns one summary object
 - `group` returns grouped rows keyed by the chosen group columns and aggregate aliases
 
+## Aggregate result values
+
+The ORM adapts database-driver aggregate scalars before returning model results or storing query-cache entries. Cached results and relation aggregates follow the same contract; business services do not need their own normalization helper.
+
+| Result                             | Runtime value and inferred type                                                                        |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `count_*`                          | Decimal string, with existing `undefined` optionality                                                  |
+| `sum_*`, `avg_*`, `min_*`, `max_*` | String when populated; SQL `null` for empty/all-null inputs; existing `undefined` optionality retained |
+| Group dimensions                   | Their ordinary column types and dialect conversion, not aggregate strings                              |
+
+Aliases follow `${function}_${column}`, with `*` mapped to `all`, for example `count_all` and `avg_stars`. Adaptation uses the requested `aggrs`, not a prefix scan of arbitrary column names. Non-count functions currently accept numeric columns; this does not extend `min` or `max` to text/date columns.
+
+An empty group query returns `[]`. An aggregate over no matching rows returns `"0"` for counts and `null` for non-count metrics. Missing relation objects retain their existing absence semantics rather than being synthesized into zero-valued summaries. `$Dto.aggregate` and `$Dto.group` reflect these scalar contracts, including nullable non-count fields.
+
+`count()` also returns a string (or its existing `undefined` absence value). In `selectAndCount()`, `total` is a string; `pageCount`, `pageSize`, and `pageNo` remain numbers. Convert explicitly at a business arithmetic boundary only when the application's numeric range permits it.
+
+Driver strings are preserved exactly, including large integers and decimal precision. Supported finite numeric/bigint scalars are converted to strings; numeric counts must be nonnegative safe integers. Unsupported values and unsafe numeric counts are rejected. Conversion cannot restore precision already lost by a driver; configure driver precision deliberately when that matters. The ORM does not parse decimal strings through JavaScript `Number`.
+
+**Compatibility:** drivers that previously leaked native numeric aggregate values now return strings, matching the existing declared string contract. Untyped code that depended on native numbers must adapt deliberately. Non-count TypeScript and DTO fields now explicitly admit SQL `null`; callers must handle it rather than assuming a populated value.
+
+## Bounded, client-selectable analysis APIs
+
+Raw `model.group()` / `model.aggregate()` remain server-authored ORM operations. Do not expose their full parameter objects directly to clients. For an API that lets clients choose dimensions and metrics, define one `$defineAnalysis(modelLike, config)` policy and attach it to the resource SelectReq DTO with `@Dto({ analysis: policy })`.
+
+Use `@Arg.filter(SelectReq, { mode: 'group' })` or `{ mode: 'aggregate' }`, infer finite optional response fields with `$Dto.analysisGroup(policy)` / `$Dto.analysisAggregate(policy)`, and execute through `$executeAnalysisGroup(model, policy, params)` / `$executeAnalysisAggregate(model, policy, params)`. The same policy supplies field allowlists, per-action defaults, limits, request enums and public `filter.capabilities.analysis` metadata. It is an API boundary, not an Entity-wide permission flag.
+
+These helpers deliberately expose less than the raw ORM: no joins, relation loading, `having`, custom expressions or aliases. A named filter that requires joins is rejected for analysis rather than silently dropped. Ordinary select retains its existing joined-filter behavior. Projection, order and pagination controls are validated but do not drive analysis execution; dimension ordering and the result cap are server-owned.
+
+The default limits are 3 dimensions, 10 function/column metric pairs and 1000 grouped rows. Group execution reads at most the configured row cap plus one and fails with 422 on overflow instead of returning a silently truncated result. This bounds materialized/returned rows, not database scan or aggregation cost. Existing instance scope, soft-delete handling, query caching and scalar normalization remain owned by the ORM.
+
+See [CRUD Workflow](/backend/crud-workflow#grouping-and-statistics) for the Student policy, JSON query transport and default CLI analysis generation.
+
 ## `having` and grouped ordering
 
 Grouped queries often need filtering and ordering on derived fields.

package/repo-docs/backend/validation-guide.md

@@ -96,9 +96,45 @@ For query parameters, that distinction matters because plain optional values sti
 
 ## `@Arg.filter`
 
-The validation layer also supports more advanced query-style inputs through `@Arg.filter`, which ties into DTO/query helper structures.
+The validation layer supports query-style inputs through `@Arg.filter`, which ties DTO/query helpers to named filters, raw `where`, transformations, and list controls.
 
-This is a good example of validation being connected to higher-level query semantics, not only primitive field checks.
+### Analysis action modes
+
+A DTO can attach one shared `$defineAnalysis` policy through `@Dto({ analysis: studentAnalysis })`. Select, group, and aggregate still have separate contracts:
+
+```typescript
+async select(
+  @Arg.filter(DtoStudentSelectReq) params: IQueryParams<ModelStudent>,
+) {
+  return await this.scope.service.student.select(params);
+}
+
+async group(
+  @Arg.filter(DtoStudentSelectReq, { mode: 'group' })
+  params: TypeAnalysisGroupParams<typeof studentAnalysis>,
+) {
+  return await this.scope.service.student.group(params);
+}
+
+async aggregate(
+  @Arg.filter(DtoStudentSelectReq, { mode: 'aggregate' })
+  params: TypeAnalysisAggregateParams<typeof studentAnalysis>,
+) {
+  return await this.scope.service.student.aggregate(params);
+}
+```
+
+Group mode derives `groups` and `aggrs` controls from the policy; aggregate mode derives `aggrs` only. Each action receives its own schema reference and finite enums without mutating the base SelectReq schema. An ordinary select request explicitly containing analysis controls is rejected before unknown-key stripping can hide them. This does not enable strict unknown-key rejection for every unrelated filter.
+
+For GET, array/object controls are JSON query values: `groups=["level"]` and `aggrs={"count":["imageId"]}` before URL encoding. Generated API calls accept structured values and encode them through the existing `combineQueries` convention. Malformed JSON, empty arrays/metric objects, duplicate fields, unsupported functions/columns, or any `groups` on aggregate are invalid. Omitted `groups` and `aggrs` independently use the action defaults; explicit empty input never means “use the default.”
+
+The policy owns a dimension allowlist and function-specific column allowlists. Clients cannot introduce custom aliases, expressions, joins, or `having`. A named filter that requires a join also fails for analysis, rather than silently dropping the join or changing aggregate multiplicity; ordinary select joined filters remain supported. Named local filters, transforms, and raw-`where` precedence retain their existing behavior.
+
+List controls such as `columns`, `orders`, `pageNo`, and `pageSize` remain validated but do not project, sort, or paginate analysis results. For example, invalid `pageSize: 0` still fails, while valid page 2 does not remove matching source rows from the aggregate population. Server-side instance, soft-delete, and business scope must still constrain `where` before execution.
+
+`$executeAnalysisGroup(model, policy, params)` and `$executeAnalysisAggregate(model, policy, params)` revalidate analysis controls for direct service callers. The default effective limits are `maxGroups: 3`, `maxMetrics: 10`, and `maxGroupRows: 1000`; policies can deliberately override them. Group execution uses deterministic dimension ordering and reads cap+1 rows to detect overflow. Invalid analysis selections and group-row overflow produce deliberate `422` errors, not generic server failures or silently truncated results. The row cap is not a limit on database scan/aggregation cost.
+
+The derived schemas expose public `filter.capabilities.analysis` (mode, allowlists, defaults, limits), including on flattened `groups` / `aggrs` query parameter schemas. They do not publish model/class references. See [CRUD Workflow](/backend/crud-workflow#grouping-and-statistics) and [DTO Infer and Generation](/backend/dto-infer-generation#aggregate-and-group-dto-inference) for policy authoring and requested-only response fields.
 
 ## Tool groups
 

package/repo-e2e/specs/cabloy-basic.spec.ts

@@ -138,7 +138,10 @@ function installStudentCreateResponseCapture(page: Page) {
 const studentDraftCreatePath = '/admin/rest/resource/training-student%3Astudent/create';
 
 function studentDraftNameInput(page: Page) {
-  return page.getByRole('group', { name: 'Student Name *', exact: true }).getByRole('textbox');
+  return page
+    .locator('[role="tabpanel"]:not([hidden]):visible')
+    .getByRole('group', { name: 'Student Name *', exact: true })
+    .getByRole('textbox');
 }
 
 function studentDraftBanner(page: Page) {
@@ -1535,7 +1538,10 @@ test(
         await expect(page).toHaveURL(
           new RegExp(`/training-student(?:%3A|:)student/${students[index]!.id}/edit(?:[?#]|$)`),
         );
-        await expect(studentDraftNameInput(page)).toHaveValue(titles[index]!);
+        const input = studentDraftNameInput(page);
+        // Navigation can finish before the outgoing task's transition.
+        await expect(input).toHaveCount(1);
+        await expect(input).toHaveValue(titles[index]!);
         await expect(task(index)).toHaveAttribute('aria-selected', 'true');
       };
       const expectStrip = async (compact: boolean, count: number) => {
@@ -1733,6 +1739,7 @@ test(
       await expect(more).toBeFocused();
       await openMenu([0, 2], 0);
       await close(0);
+      await expect(studentDraftNameInput(page)).toHaveCount(1);
       await expect(studentDraftNameInput(page)).toHaveValue(titles[2]!);
       await expect(task(2)).toHaveAttribute('aria-selected', 'true');
       await openMenu([2], 2);

package/vona/package.original.json

@@ -37,19 +37,13 @@
     "format": "oxfmt --check",
     "format:fix": "oxfmt --write",
     "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "docs:fix": "textlint --fix ./packages-docs/**/*.md"
+    "lint:fix": "oxlint --fix"
   },
   "dependencies": {
     "vona": "workspace:^"
   },
   "devDependencies": {
     "@cabloy/lint": "workspace:^",
-    "textlint": "^15.7.0",
-    "textlint-rule-en-no-mixed-period": "^3.0.2",
-    "textlint-rule-ja-no-mixed-period": "^3.0.2",
-    "textlint-rule-ja-space-between-half-and-full-width": "^2.4.2",
-    "textlint-rule-period-in-list-item": "^1.0.1",
     "oxfmt": "^0.74.0",
     "oxlint": "^1.89.0"
   }

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.176",
+  "version": "1.1.177",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudAnalysis/aggregate/src/dto/{{resourceName}}AggregateRes.tsx_

@@ -0,0 +1,11 @@
+import type { IDecoratorDtoOptions } from 'vona-module-a-web';
+
+import { $Dto } from 'vona-module-a-orm';
+import { Dto } from 'vona-module-a-web';
+
+import { <%=argv.resourceName%>Analysis } from '../lib/<%=argv.resourceName%>Analysis.ts';
+
+export interface IDtoOptions<%=argv.resourceNameCapitalize%>AggregateRes extends IDecoratorDtoOptions {}
+
+@Dto<IDtoOptions<%=argv.resourceNameCapitalize%>AggregateRes>()
+export class Dto<%=argv.resourceNameCapitalize%>AggregateRes extends $Dto.analysisAggregate(<%=argv.resourceName%>Analysis) {}

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudAnalysis/common/src/lib/{{resourceName}}Analysis.ts_

@@ -0,0 +1,14 @@
+import { $defineAnalysis } from 'vona-module-a-orm';
+
+import { Model<%=argv.resourceNameCapitalize%> } from '../model/<%=argv.resourceName%>.ts';
+
+// One allowlist drives request controls, response fields, and bounded execution.
+export const <%=argv.resourceName%>Analysis = $defineAnalysis(() => Model<%=argv.resourceNameCapitalize%>, {
+  groups: ['name'],
+  aggrs: { count: ['*'] },
+  defaults: {
+    group: { groups: ['name'], aggrs: { count: ['*'] } },
+    aggregate: { aggrs: { count: ['*'] } },
+  },
+  limits: { maxGroups: 3, maxMetrics: 10, maxGroupRows: 1000 },
+});

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudAnalysis/common/test/{{resourceName}}Analysis.test.ts_

@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import { describe, it } from 'node:test';
+import { app } from 'vona-mock';
+
+import { <%=argv.resourceName%>Analysis } from '../src/lib/<%=argv.resourceName%>Analysis.ts';
+
+describe('<%=argv.resourceName%>Analysis.test.ts', { concurrency: false }, () => {
+  it('returns default and requested-only string counts with validated controls', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const scope = app.scope('<%=argv.moduleInfo.relativeName%>');
+      const name = `__analysis_${randomUUID()}`;
+      const fixture = await scope.model.<%=argv.resourceName%>.insert({ name });
+      try {
+        await app.bean.passport.signinMock();
+        const queries = [
+          { name },
+          // List controls are validated but do not paginate the analysis population.
+          { where: { id: fixture.id }, columns: ['id'], orders: 'name,desc', pageNo: 2, pageSize: 1 },
+        ];
+        for (const query of queries) {
+          const groups = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/group', { query });
+          assert.deepEqual(groups, [{ name, count_all: '1' }]);
+          assert.deepEqual(await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/group', {
+            query: { ...query, groups: JSON.stringify(['name']), aggrs: JSON.stringify({ count: ['*'] }) },
+          }), groups);
+          assert.deepEqual(await scope.service.<%=argv.resourceName%>.group({
+            where: { id: fixture.id }, groups: ['name'], aggrs: { count: ['*'] },
+          }), groups);
+          const aggregate = await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/aggregate', { query });
+          assert.deepEqual(aggregate, { count_all: '1' });
+          assert.deepEqual(await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/aggregate', {
+            query: { ...query, aggrs: JSON.stringify({ count: ['*'] }) },
+          }), aggregate);
+          assert.deepEqual(await scope.service.<%=argv.resourceName%>.aggregate({
+            where: { id: fixture.id }, aggrs: { count: ['*'] },
+          }), aggregate);
+        }
+        for (const action of ['group', 'aggregate'] as const) {
+          for (const controls of [
+            { pageNo: 2, pageSize: 0 },
+            { aggrs: JSON.stringify({}) },
+            { aggrs: JSON.stringify({ count: ['*', '*'] }) },
+            { aggrs: JSON.stringify({ count: ['unknown'] }) },
+            { aggrs: '{invalid-json' },
+          ]) {
+            await assert.rejects(() => app.bean.executor.performAction('get', `<%=argv.moduleActionPathRaw%>/${action}`, {
+              query: { name, ...controls },
+            }));
+          }
+        }
+        // The shared policy does not enable analysis controls on ordinary select.
+        await assert.rejects(() => app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>', {
+          query: { name, aggrs: JSON.stringify({ count: ['*'] }) },
+        }));
+        for (const groups of [[], ['name', 'name'], ['description'], ['unknown']]) {
+          await assert.rejects(() => app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/group', {
+            query: { name, groups: JSON.stringify(groups) },
+          }));
+        }
+        await assert.rejects(() => scope.service.<%=argv.resourceName%>.group({ aggrs: { count: [] } }));
+        assert.deepEqual(<%=argv.resourceName%>Analysis.defaults.group, {
+          groups: ['name'], aggrs: { count: ['*'] },
+        });
+        await assert.rejects(() => app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/aggregate', {
+          query: { name, groups: JSON.stringify(['name']) },
+        }));
+        await assert.rejects(() => scope.service.<%=argv.resourceName%>.aggregate({ aggrs: { count: [] } }));
+        assert.deepEqual(<%=argv.resourceName%>Analysis.defaults.aggregate, { aggrs: { count: ['*'] } });
+        await scope.model.<%=argv.resourceName%>.deleteById(fixture.id);
+        for (const query of queries) {
+          assert.deepEqual(await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/group', { query }), []);
+          assert.deepEqual(await app.bean.executor.performAction('get', '<%=argv.moduleActionPathRaw%>/aggregate', { query }), { count_all: '0' });
+        }
+      } finally {
+        await scope.model.<%=argv.resourceName%>.deleteById(fixture.id, { disableDeleted: true });
+        await app.bean.passport.signout();
+      }
+    });
+  });
+});

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudAnalysis/group/src/dto/{{resourceName}}GroupResItem.tsx_

@@ -0,0 +1,11 @@
+import type { IDecoratorDtoOptions } from 'vona-module-a-web';
+
+import { $Dto } from 'vona-module-a-orm';
+import { Dto } from 'vona-module-a-web';
+
+import { <%=argv.resourceName%>Analysis } from '../lib/<%=argv.resourceName%>Analysis.ts';
+
+export interface IDtoOptions<%=argv.resourceNameCapitalize%>GroupResItem extends IDecoratorDtoOptions {}
+
+@Dto<IDtoOptions<%=argv.resourceNameCapitalize%>GroupResItem>()
+export class Dto<%=argv.resourceNameCapitalize%>GroupResItem extends $Dto.analysisGroup(<%=argv.resourceName%>Analysis) {}