Repository navigation
Commit a30c4f4
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
- .changeset
- content/docs/references/ai
- packages/spec/src/ai
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
92 | 92 | | |
93 | 93 | | |
94 | 94 | | |
95 | | - | |
| 95 | + | |
96 | 96 | | |
97 | 97 | | |
98 | 98 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1260 | 1260 | | |
1261 | 1261 | | |
1262 | 1262 | | |
| 1263 | + | |
| 1264 | + | |
| 1265 | + | |
| 1266 | + | |
| 1267 | + | |
| 1268 | + | |
| 1269 | + | |
| 1270 | + | |
| 1271 | + | |
| 1272 | + | |
| 1273 | + | |
| 1274 | + | |
| 1275 | + | |
| 1276 | + | |
| 1277 | + | |
1263 | 1278 | | |
1264 | 1279 | | |
1265 | 1280 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
337 | 337 | | |
338 | 338 | | |
339 | 339 | | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
| 347 | + | |
340 | 348 | | |
341 | 349 | | |
342 | 350 | | |
| |||
420 | 428 | | |
421 | 429 | | |
422 | 430 | | |
423 | | - | |
| 431 | + | |
424 | 432 | | |
425 | 433 | | |
426 | 434 | | |
| |||
695 | 703 | | |
696 | 704 | | |
697 | 705 | | |
698 | | - | |
| 706 | + | |
699 | 707 | | |
700 | 708 | | |
701 | 709 | | |
| |||
0 commit comments