fix(lint)!: os validate refuses an analyticsCubes sum / avg / min / max measure over a column the cube door refuses — every cube measure is judged by the aggregate × field-type table

[objectstack-fleet]

Fixes #21419
Clause-②: no (narrowing)

What changes

@objectstack/lint's dataset-member rule (packages/lint/src/validate-dataset-measure-aggregates.ts) now judges every analyticsCubes measure through acceptsDeclaration, the verdict a dataset measure already gets. Until now the cube leg judged count_distinct only, so a cube sum / avg / min / max over a column the cube door refuses passed os validate.

• A cube measure's type is its aggregate. Every type that is a row of AGGREGATE_FIELD_TYPE_COMPATIBILITY is judged on the column the door reads. That column is the cube's object, or, for a relationship path, the last hop's declared join, else the lookup's reference (the resolution PR fix(lint)!: os validate refuses an analyticsCubes member the analytics door refuses — a dimension over a JSON-stored column, and count_distinct over one #21416 added, unchanged).
• count reads no value and is accepted on every type, as on a dataset.
• A type outside the table (number / string / boolean, the expression metric types) is skip 5, as on a dataset. Neither cube door judges it either.
• The row wildcard '*' is still skipped. Whether it belongs on a non-count measure is the question analytics: '*' runs only under count, but a cube measure's or dimension's sql and a dataset measure's field admit it under any aggregate — a summed '*' answers 500 at the dataset door (split from #21000) #21409 owns; nothing here refuses it.
• No second table and no parallel copy. The change in the rule body is one guard: if (aggregate !== 'count_distinct') continue; becomes if (!aggregate) continue;, and the existing skip 5 (ACCEPTED_TYPES_BY_AGGREGATE.get) now does the vocabulary work it does for a dataset. The finding id (measure-aggregate-field-type-refused), its location (analyticsCubes[N].measures.KEY.type) and its words are the ones the cube count_distinct leg already emits.

Text this PR makes false, corrected in it: the rule's module note and the validate-dataset-measure-aggregates.ts docblock, and the cube paragraph in §6 of content/docs/deployment/validating-metadata.mdx. Both said a cube's other measure types were not judged. The landed .changeset/21082-cube-member-json-stored-refused.md is released history and is left as it is.

Files changed (4): the rule, its test file, the docs paragraph, one changeset. index.ts, runtime.ts, package.json and service-analytics are untouched.

The cube door's verdict, pair for pair

The enumeration pin in the test file crosses every cube measure type (AggregationMetricType, which holds every row of the table) with every FieldType, flagged multiple: true and not. It checks each pair against the two cube doors' rules as their modules state them:

• count / sum / avg / min / max: cube-measure-field-type-door.ts. The row is checked on the declared TYPE, and the multiple flag is not read.
• count_distinct: structured-json-dimension-door.ts. The row is checked, and so is isMultiValueField.

Per-type floors hold on both sides.

As a one-off proof against the real door rather than its stated rule, a scratch script was run and not committed. For each case it built a real AnalyticsService with sourceFieldMeta, relationshipResolver and getObjectFieldNames wired. Then it called generateSql on one measure, which goes through ensureCube to both doors. It compared the refusal (INVALID_FIELD with the door's own words) against the lint verdict. The cases were every AggregationMetricType × every FieldType × multiple {false, true} × three column positions: bare, reference-tier path and join-tier path.

lint rule	pairs	agree	lint refuses	door refuses	mismatches
HEAD 1de24da8fb (the rule's blob is 0d56d08213 since 1236c5a4b7)	2646	2646	1008	1008	0
BASE 39a912ea73 (control)	2646	1716	78	1008	930, all lint=false door=true

No pair diverges, so there is nothing to report as a door/table disagreement.

os validate, before and after

Fixtures fx_ledger + one cube fx_cube were measured with the CLI built from this tree. Before is the same tree with the guard reverted through scripts/ablation-replace.mjs. The lint dist/ was rebuilt, and ablation-dist-preflight confirmed the marker present in 4 built files. After is the restored tree, rebuilt, with the marker confirmed absent from all 8 built files and the tree clean against HEAD.

fixture	before	after
oos-cube-sum-text (sum over name, text), the card's measured instance	exit 0	exit 1 at analyticsCubes[0].measures.sum_name.type
avg over text	exit 0	exit 1
max over text	exit 0	exit 1
min over a single select	exit 0	exit 1
avg over datetime	exit 0	exit 1
sum over account.name, reference tier (fx_account, text)	exit 0	exit 1
sum over account.revenue, join tier (joins.account reaches fx_branch, where it is text)	exit 0	exit 1, naming fx_branch
scalar control	exit 0	exit 0

The scalar control holds sum and avg over number, max and min over datetime, count and count_distinct over text, sum over account.revenue by reference (number), and sum over '*'.

Census

The census covers examples/**, packages/** (fixtures included) and the platform objects. It found one authored cube in the shipped corpus: showcase's showcase_delivery, with count over '*' and sum / avg over estimate_hours (number). It stays clean. Every other analyticsCubes or defineCube site is a spec, service-analytics, runtime, objectql or driver test, and none of them runs a lint rule.

At HEAD 1de24da8fb, os validate exits 0 on examples/app-showcase, app-crm and app-todo, with 0 findings of either cube id.

Clause-②: the measured arm

• node scripts/pm/check-widening-tells.mjs --declaration no --diff on the final diff (git diff 39a912ea73...HEAD) exits 0. All 4 files are NOT MEASURED (no declared surface covers them), so it decided nothing.
• Export census: the diff adds 0 and removes 0 export lines in packages/lint/src, tests excluded. The positive control 5e470f8c1c adds 1. index.ts, runtime.ts and package.json are unchanged.
• So no export is added, and the arm is no (narrowing). The changeset is still BREAKING, because metadata that passed os validate can now fail.

Changeset

.changeset/21419-cube-measure-aggregate-field-type-refused.md: @objectstack/lint minor, fix(lint)!, a BREAKING banner, Clause-②: no (narrowing), and exactly one ADR-0087 marker: not-required (no-migration-prescription). check-adr-0087-registration accepts it and reads it as [BREAKING+bang+clause-②-narrowing].

Tests

src/validate-dataset-measure-aggregates.test.ts gains 6 tests in a new block, and 1 test is rewritten.

• The rewritten test is the [finding] os validate passes an analyticsCubes member the analytics door refuses: lint reads no cube, so a cube dimension over a JSON-stored field passes authoring and is refused 400 at query time #21082 test that pinned "judges only count_distinct". It now pins that count over a json column is accepted and sum / avg / min / max over it are refused.
• The 6 new tests cover:
  • the measured instance and its control;
  • per-row refusals and acceptances over text and datetime;
  • the enumeration pin;
  • the reference tier and the join tier giving opposite verdicts on one path;
  • the skips: expression types, a prototype key, no or non-string type, '*', an unresolved column, an unfollowable hop, an untyped column, a cube naming no object;
  • report order, and runAuthoringRules on all three commands.

Runs at 1de24da8fb, the final commit, which includes the merge of origin/main 68c5ab7eba:

• pnpm --filter @objectstack/lint exec vitest run --maxWorkers=2: 119 files, 5592 tests passed.
• pnpm --filter @objectstack/lint typecheck: exit 0. tsc -p tsconfig.test.json --listFiles includes the test file.
• eslint, narrowed and proven: the population is the 2 changed .ts files. The .mdx and .md fall outside the config's **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} glob, and --print-config resolves a config for both .ts files. --format json reports 2 files, 0 errors and 0 warnings. eslint.config.mjs enables no type-aware linting (no parserOptions.project), so this diff cannot move a verdict on an untouched file.

Ablations ran on the committed tree through scripts/ablation-replace.mjs. Each restore was proven by its blob hash matching HEAD and an empty git diff HEAD.

ablation	result
A1: the guard reverted to count_distinct only	7 red / 45 green: the 6 new tests and the rewritten one
A2: the max row dropped on cube measures	4 red / 48 green, including the enumeration pin on cube max(text)

Gates

• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at 1de24da8fb derived 90 commands, and all 90 were run.
  • check:skill-examples first exited 3: PREREQUISITE NOT MET, because client-react had no .d.ts.
  • check:dual-build-cjs-loads first exited 3: 7 packages had no dist.
  • check:dts-closure first exited 1, because of this worktree's own OS_SKIP_DTS builds.
  • After those packages were built with declarations, all three exit 0.
• --ran reconciliation: 90 derived, 90 run, 0 NOT-MEASURED (a derived zero: every line recorded its exit code), 0 UNRUN.
• Also run, as the roster gates under a changed path: check-changeset-fixed, check:authz-resolver, check:error-code-casing and check:filter-alias-parity. All exit 0.
• main moved 5 commits after the merge (3a6d92f78b). None of them touches packages/lint, the docs page or either cube door. The one service-analytics change is the NativeSQL boolean-comparand door. CI's merge ref tests the combined state.

Acceptance notes

• ADR-0087 disposition: the two landed precedents disagree. The query-time cube door's changeset declared not-required (already-registered dataset-measure-selecting-aggregate-field-type-refused, dataset-measure-aggregate-field-type-refused) for these same pairs. This rule's own cube leg declared no-migration-prescription, on the ground that those two entries describe DatasetMeasureSchema rows. This PR follows the rule's own leg. Either marker passes the gate; if the seat prefers the other, the change is the one comment line.
• A field type outside FieldType. acceptsDeclaration is fail-closed on vocabulary, so the lint would refuse even count over such a column, where both cube doors stand down. os validate cannot reach that case: defineStack refuses the field first (measured: objects.0.fields.amount.type: Invalid field type 'integer', exit 1, no author-time rule runs). The dataset leg has the same shape.
• The field-consumer advisory does not credit a relationship-path leaf (validate-field-consumers.ts). This was seen while measuring and is reported to the seat, not fixed here. os validate on the scalar control flags fx_account.revenue and fx_ledger.account as "inert — no site of any kind names it". That is wrong: the cube measure sum_rev reads account.revenue. A dataset measure over account.revenue with include: ['account'] gets the same inert verdict on fx_account.revenue.
• Runtime write door, unchanged. The runtime analytics_cube write door still dispatches no authoring rule, as PR fix(lint)!: os validate refuses an analyticsCubes member the analytics door refuses — a dimension over a JSON-stored column, and count_distinct over one #21416 recorded. Read from code, not measured. Carrier: none.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 2 documentable anchor(s).

6 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/ai/natural-language-queries.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))
• content/docs/data-modeling/queries.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))
• content/docs/deployment/validating-metadata.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))
• content/docs/kernel/contracts/data-engine.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))
• content/docs/protocol/objectql/query-syntax.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))
• content/docs/ui/dashboards.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))

⛔ 4 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v15.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))
• content/docs/releases/v17/17-0.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))
• content/docs/releases/v17/17-5.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))
• content/docs/releases/v17/17-6.mdx (via count_distinct (literal, a string literal in cubeMemberFindings))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 3a6d92f78bb6a160b762dfee0738fd3b0b7ae6c2 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 37796ee7bf9b75f04bf074c0a009545bd361ca42 — the merge of head 1de24da8fb3447429901f228dde1673c505e5325 into base 3a6d92f78bb6a160b762dfee0738fd3b0b7ae6c2, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 37796ee7bf9b75f04bf074c0a009545bd361ca42 && git checkout 37796ee7bf9b75f04bf074c0a009545bd361ca42
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 3a6d92f78bb6a160b762dfee0738fd3b0b7ae6c2 1de24da8fb3447429901f228dde1673c505e5325 && git checkout -B drift-repro 3a6d92f78bb6a160b762dfee0738fd3b0b7ae6c2 && git merge --no-ff 1de24da8fb3447429901f228dde1673c505e5325

node scripts/docs-audit/affected-docs.mjs --json 3a6d92f78bb6a160b762dfee0738fd3b0b7ae6c2

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 3a6d92f78bb6a160b762dfee0738fd3b0b7ae6c2 → pass the list as
args.docs, on the commit named under Which tree this was computed on.