Skip to content

Commit a30c4f4

Browse files
docs(spec): the blueprint widget aggregate describes say a widget with a measure and no aggregate may be refused, not defaulted (#30942)
<!-- claude-projects-attribution: {"github_login":"os-tesla"} --> _Requested by **Tesla** · [project thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoQE5JiKcyDY5fdamKwvANk5)_ Fixes #30667 Clause-②: no Metadata-protocol: none Describe text only; both schemas accept exactly what they accepted before. Rulings carried verbatim from the card and triage 6683636257: "Both describes say what a reader may do when `aggregate` is absent on a widget that names a measure: it may refuse the widget. They must not promise a default." · "The strict mirror's `null` stays legal for a count widget, and the describe says so." · "Describe text only. No schema change, so no ledger row moves." ## 维护者速读 - **改了什么**:蓝图看板组件 `aggregate` 键的两处说明(宽松 schema 与设计模型实际读取的严格镜像)不再说"不写就用读取方自己的默认值",改为同一句共享规则:写了 `measure` 却没写 `aggregate` 的组件不完整,读取方可以拒收,不承诺任何默认聚合;只有不写 `measure` 的计数组件可以不写。严格版补一句 `null` 对计数组件仍合法。参考页随之再生成。 - **为什么改**:按你在 cloud#3607 的裁决 B,cloud 已拒收这种组件;而 cloud 的设计模型正对着严格版说明生成蓝图,旧文字会教它写出会被拒收的组件。 - **风险与回滚**:零运行时、零 schema 改动,接受集不变;回滚即 revert。 - **先看**:`packages/spec/src/ai/solution-blueprint.zod.ts` 新常量 `WIDGET_AGGREGATE_UNSET_RULE` 及两条 `aggregate` describe;`solution-blueprint.test.ts` 新增的一条 pin。 - **两分钟验证**:`pnpm --filter @objectstack/spec exec vitest run src/ai/solution-blueprint.test.ts`,预期 98/98 通过,其中新 pin 断言两边都不再出现"默认"承诺、都写明"may refuse it"、严格版写明计数组件可为 null。 - **需要你做的**:无,席位落地。 ## What changes - **One shared rule, read on both sides.** A new constant `WIDGET_AGGREGATE_UNSET_RULE` in `packages/spec/src/ai/solution-blueprint.zod.ts`, beside `WIDGET_AGGREGATE_MEANING` and in the voice of `WIDGET_MEASURE_RULE`: "SET it on every widget that names a `measure`: a widget that names a `measure` and leaves this unset is incomplete, and a reader may refuse it; no default aggregation is promised. Only a count widget, which names no `measure`, may leave it unset." - Lenient widget `aggregate`: was "…SET it on every widget that aggregates; omitted, the reader falls back to a default of its own, which may not be the average or extreme a widget means." Now `MEANING` + the shared rule. - Strict mirror `aggregate`: was "How the widget aggregates its records, or null for the reader's own default. … Write it, never null, on every widget that aggregates." Now "How the widget aggregates its records, or null on a count widget whose `measure` is null." + `MEANING` + the shared rule. - **Pin**, in the existing `blueprint widget aggregate and calendar view startDateField` describe of `solution-blueprint.test.ts` (shared-harness rule: a new top-level `it`, no new file): neither `aggregate` describe matches the default promise (`reader's own default`, `default of its own`, `falls back`), both say "may refuse it", and the strict one says "null on a count widget". The strict describe is the text the design model generates against, so its wording is what the consumer reads. - **Regenerated**: `content/docs/references/ai/solution-blueprint.mdx` (1 line, the lenient row), by `gen:docs` after `check:generated` named it stale; not hand-edited. The strict mirror is not exported, so it has no reference row. - **Changeset** `.changeset/30667-blueprint-widget-aggregate-unset-may-refuse.md`: `@objectstack/spec` patch, both declaration lines at line start. Other copies of the promise on `origin/main` 26c965c: `grep -rn "reader's own default\|reader falls back to a default of its own" packages skills content` → the two describes and the generated reference row only. Nothing under `skills/**`, so the PR stays default tier, not governed. ## Tests - `pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/ai/solution-blueprint.test.ts`: `Tests 98 passed (98)`. - Reverse verification of the new pin, fix committed first: `solution-blueprint.zod.ts` restored tree-only from `origin/main` 26c965c (old wording 1 hit, `WIDGET_AGGREGATE_UNSET_RULE` 0 hits on disk), same run under the lock → VERDICT command-exit 1, `Tests 1 failed | 97 passed (98)`, the failing test being the new pin. Restored with `git checkout HEAD -- PATH`: `git hash-object` equals the HEAD blob, `git diff HEAD` and `git status --porcelain` empty. - `pnpm --filter @objectstack/spec typecheck` under the lock: VERDICT command-exit 0. - `pnpm --filter @objectstack/spec test` under the lock: VERDICT command-exit 0, `Test Files 818 passed (818)`, `Tests 25839 passed | 1 todo (25840)`. `test:repo` (the vitest `repo` project) is CI's run (`Test Core`), not run here. ## Verification - `pnpm --filter @objectstack/spec build` (dts 38/38 emitted), then `check:generated`: 1 artifact stale (`content/docs/references/**`), regenerated with `gen:docs`; rerun → "All 14 generated artifacts are up to date", exit 0. The first `check:generated` run also reported `check:test-typecheck` as "tsc failed without diagnostics" under the default heap; `check:test-typecheck` alone with `--max-old-space-size=4096` → exit 0 ("52 file(s) / 240 error(s) / 131 pinned signature(s) held"), and the rerun of `check:generated` with that heap is the green one above. Nothing was re-recorded. - Gate families derived against the actual diff with `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` at 0e0ae5d (the final commit): 103 lines, every one run with stdin from /dev/null, exit codes landed on disk before any pipe, reconciled with `--ran`: `103 derived, 103 run, 0 NOT-MEASURED, 0 UNRUN`, every line exit 0 on the final tree. Seven lines first exited 3 (PREREQUISITE NOT MET, nothing measured): `check-plugin-teardown-shape.mjs --self-test` (shallow clone; fetched its control commit, rerun exit 0, 48 cases) and six that read built output (`check:doc-formula-expressions`, `check:doc-security-posture`, `check:skill-examples`, `check:docs-transcript-drift`, `check:dual-build-cjs-loads`, `check:lean-entry-closure`); after `turbo run build --concurrency=2` under the lock (VERDICT command-exit 0, 119/119 tasks) each reran exit 0. - Tier: `dispatch-gates.mjs --tier` → no path-derived mandate; not a governed surface. Changed lines 37 (+34 / -3, generated included), under the 3,000 threshold. ## Acceptance notes - The cloud consumer (`blueprintWidgetRefusals`, rule `aggregate_missing`, objectstack-ai/cloud#3639) is quoted only as the card states it; this repo cannot read cloud. The card scopes that refusal to a non-table widget; the spec text says "may refuse", which a reader that exempts table widgets satisfies, so the describe names no chart kind. - The `BLUEPRINT_WIDGET_AGGREGATES` docblock still says that before the key existed "the reader picked the aggregation from the field type". That is history of why the key was added, not a promise about an unset key, and is left as is. - `measure:"count"` (the legacy record-count spelling) with `aggregate` unset is a widget that names a `measure`; the shared rule says a reader may refuse it. Whether cloud refuses that exact shape is not stated on the card and was not measured. ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` is CI's run. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: its generated artifacts are regenerated and committed. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English. - [x] The *Before Submitting* list in CONTRIBUTING.md is done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01L9qibvcm8KFrmrjzi8KaKZ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 1b3e22f commit a30c4f4

4 files changed

Lines changed: 34 additions & 3 deletions

File tree

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@objectstack/spec': patch
3+
---
4+
5+
docs(spec): the solution-blueprint widget `aggregate` describes, on the lenient schema and its strict mirror, no longer promise "the reader's own default" when the key is unset. Both now read one shared rule: a widget that names a `measure` and leaves `aggregate` unset is incomplete, and a reader may refuse it; no default aggregation is promised. Only a count widget, which names no `measure`, may leave it unset, and the strict mirror's `null` stays legal there, as its describe now says. Describe text only: the accepted set of both schemas is unchanged.
6+
7+
Clause-②: no
8+
Metadata-protocol: none

‎content/docs/references/ai/solution-blueprint.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ const result = BlueprintAppSchema.parse(data);
9292
| **object** | `string` | optional | Source object for the widget |
9393
| **chart** | `Enum<'metric' \| 'bar' \| 'line' \| 'pie' \| 'table'>` | optional | Widget visualization |
9494
| **measure** | `string` | optional | The field this widget aggregates (e.g. "amount", "score"), or "count" to count records. Name the FIELD, not "total_amount" or "avg_score": how it is aggregated is what `aggregate` says, never this key. A "total revenue" widget sets measure:"amount" with aggregate:"sum"; an "average interview score" widget sets measure:"score" with aggregate:"avg"; a "number of deals" widget sets aggregate:"count" and needs no measure. measure:"count" is the legacy spelling of a record count: write aggregate:"count" instead. Beside "sum", "avg", "min" or "max", measure:"count" names no field to aggregate, so that widget is incomplete: a reader must refuse it, never sum, average or rank a record count. Omit for a count widget. |
95-
| **aggregate** | `Enum<'sum' \| 'avg' \| 'min' \| 'max' \| 'count'>` | optional | How the widget aggregates its records: "sum" = the total of the `measure` field; "avg" = its average; "min" / "max" = its smallest / largest value; "count" = the number of records the widget covers (after its `condition`). "sum", "avg", "min" and "max" need `measure` to name a numeric field of the widget's object. "count" needs no `measure` field: it counts records, and a field named in `measure` beside it is not read. Say what the widget computes: an average → "avg", a total → "sum", a highest / lowest value → "max" / "min", a number of records → "count". SET it on every widget that aggregates; omitted, the reader falls back to a default of its own, which may not be the average or extreme a widget means. |
95+
| **aggregate** | `Enum<'sum' \| 'avg' \| 'min' \| 'max' \| 'count'>` | optional | How the widget aggregates its records: "sum" = the total of the `measure` field; "avg" = its average; "min" / "max" = its smallest / largest value; "count" = the number of records the widget covers (after its `condition`). "sum", "avg", "min" and "max" need `measure` to name a numeric field of the widget's object. "count" needs no `measure` field: it counts records, and a field named in `measure` beside it is not read. Say what the widget computes: an average → "avg", a total → "sum", a highest / lowest value → "max" / "min", a number of records → "count". SET it on every widget that names a `measure`: a widget that names a `measure` and leaves this unset is incomplete, and a reader may refuse it; no default aggregation is promised. Only a count widget, which names no `measure`, may leave it unset. |
9696
| **groupBy** | `string` | optional | The field to break the widget down by — the category or time axis (e.g. "stage", "created_at"). A "by status" chart MUST set this to the status field; the title and this field MUST name the SAME field. Omit for a single-number metric. |
9797
| **condition** | `{ field: string; op: Enum<'lt' \| 'lte' \| 'gt' \| 'gte' \| 'eq' \| 'ne'>; value: number \| string \| boolean }` | optional | Restrict WHICH records the widget counts/aggregates when its title implies a threshold or status (e.g. "stock below 10" → `{field:"stock_quantity", op:"lt", value:10}`; "open tickets" → `{field:"status", op:"eq", value:"open"}`). Without it the widget covers ALL records — so a "低于10的备件预警" / "overdue" card would wrongly count everything. Omit when the widget genuinely spans every record. |
9898

‎packages/spec/src/ai/solution-blueprint.test.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1260,6 +1260,21 @@ describe('blueprint widget `aggregate` and calendar view `startDateField`', () =
12601260
}
12611261
});
12621262

1263+
it('no aggregate describe promises a default when it is unset; both read the one refusal rule', () => {
1264+
// Ruling B on cloud#3607: a reader may refuse a widget that names a
1265+
// `measure` and leaves `aggregate` unset, so neither side may tell the
1266+
// design model that a default stands in for it.
1267+
const widgetShape = (root: any) => root.shape.dashboards.unwrap().element.shape.widgets.unwrap().element.shape;
1268+
const [lenient, strict]: string[] = [SolutionBlueprintSchema, SolutionBlueprintStrictSchema]
1269+
.map((root) => widgetShape(root).aggregate.description);
1270+
for (const text of [lenient, strict]) {
1271+
expect(text).not.toMatch(/reader's own default|default of its own|falls back/i);
1272+
expect(text).toMatch(/may refuse it/);
1273+
}
1274+
// The strict mirror's null stays legal for a count widget, and says so.
1275+
expect(strict).toMatch(/null on a count widget/);
1276+
});
1277+
12631278
it('accepts startDateField on a calendar view on both sides', () => {
12641279
expect(SolutionBlueprintStrictSchema.parse(strictView({ startDateField: 'interview_date' })).views?.[0].startDateField)
12651280
.toBe('interview_date');

‎packages/spec/src/ai/solution-blueprint.zod.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -337,6 +337,14 @@ const BLUEPRINT_WIDGET_AGGREGATES = ['sum', 'avg', 'min', 'max', 'count'] as con
337337
/** What each {@link BLUEPRINT_WIDGET_AGGREGATES} value means — one sentence, read on both sides. */
338338
const WIDGET_AGGREGATE_MEANING = '"sum" = the total of the `measure` field; "avg" = its average; "min" / "max" = its smallest / largest value; "count" = the number of records the widget covers (after its `condition`). "sum", "avg", "min" and "max" need `measure` to name a numeric field of the widget\'s object. "count" needs no `measure` field: it counts records, and a field named in `measure` beside it is not read. Say what the widget computes: an average → "avg", a total → "sum", a highest / lowest value → "max" / "min", a number of records → "count".';
339339

340+
/**
341+
* What an unset widget `aggregate` means, read on both sides (ruling B on
342+
* cloud#3607): beside a `measure` it makes the widget incomplete, and the
343+
* reader may refuse it. No default aggregation is promised; a count widget,
344+
* which names no `measure`, is the one widget that may leave it unset.
345+
*/
346+
const WIDGET_AGGREGATE_UNSET_RULE = 'SET it on every widget that names a `measure`: a widget that names a `measure` and leaves this unset is incomplete, and a reader may refuse it; no default aggregation is promised. Only a count widget, which names no `measure`, may leave it unset.';
347+
340348
/** The widget `measure` rule, read on both sides: it names a field, never an aggregation. */
341349
const WIDGET_MEASURE_RULE = 'Name the FIELD, not "total_amount" or "avg_score": how it is aggregated is what `aggregate` says, never this key. A "total revenue" widget sets measure:"amount" with aggregate:"sum"; an "average interview score" widget sets measure:"score" with aggregate:"avg"; a "number of deals" widget sets aggregate:"count" and needs no measure. measure:"count" is the legacy spelling of a record count: write aggregate:"count" instead. Beside "sum", "avg", "min" or "max", measure:"count" names no field to aggregate, so that widget is incomplete: a reader must refuse it, never sum, average or rank a record count.';
342350

@@ -420,7 +428,7 @@ export const BlueprintDashboardSchema = lazySchema(() => z.object({
420428
measure: z.string().regex(SNAKE_CASE).optional()
421429
.describe(`The field this widget aggregates (e.g. "amount", "score"), or "count" to count records. ${WIDGET_MEASURE_RULE} Omit for a count widget.`),
422430
aggregate: z.enum(BLUEPRINT_WIDGET_AGGREGATES).optional()
423-
.describe(`How the widget aggregates its records: ${WIDGET_AGGREGATE_MEANING} SET it on every widget that aggregates; omitted, the reader falls back to a default of its own, which may not be the average or extreme a widget means.`),
431+
.describe(`How the widget aggregates its records: ${WIDGET_AGGREGATE_MEANING} ${WIDGET_AGGREGATE_UNSET_RULE}`),
424432
groupBy: z.string().regex(SNAKE_CASE).optional()
425433
.describe('The field to break the widget down by — the category or time axis (e.g. "stage", "created_at"). A "by status" chart MUST set this to the status field; the title and this field MUST name the SAME field. Omit for a single-number metric.'),
426434
condition: BlueprintWidgetConditionSchema.optional()
@@ -695,7 +703,7 @@ const StrictDashboard = z.object({
695703
// cloud#3607 row 2): with it on the lenient side only, the design model
696704
// could never say "average". The widget key-parity pin fails if it goes.
697705
aggregate: z.enum(BLUEPRINT_WIDGET_AGGREGATES).nullable()
698-
.describe(`How the widget aggregates its records, or null for the reader's own default. ${WIDGET_AGGREGATE_MEANING} Write it, never null, on every widget that aggregates.`),
706+
.describe(`How the widget aggregates its records, or null on a count widget whose \`measure\` is null. ${WIDGET_AGGREGATE_MEANING} ${WIDGET_AGGREGATE_UNSET_RULE}`),
699707
groupBy: strictIdentOrNull('The field to break the widget down by — the category or time axis (e.g. "stage", "created_at"), or null for a single-number metric. A "by status" chart MUST set this to the status field; the title and this field MUST name the SAME field.'),
700708
condition: z.object({
701709
field: strictIdent('Field on the widget object to filter by (e.g. "stock_quantity", "status")'),

0 commit comments

Comments
 (0)