feat(spec)!: an analytics cube member's sql is a column reference, and the showcase done rate moves to its dataset (#20943)

[objectstack-fleet]

Closes #20943
Clause-②: yes (narrowing)

Ruling D on #20943 (comment 5921156712, execution parameters), dispatched by the claim 5921298734: an analytics cube member's sql is a column reference, and a SQL expression there is refused at parse with a prescription naming the ADR-0021 dataset form. The showcase's one expression member, done_rate, moves to its dataset in the same PR.

What changes

@objectstack/spec, data/analytics.zod.ts

• MetricSchema.sql and DimensionSchema.sql (every member of a cube's measures and dimensions) admit exactly the accept set the execution parameters name: a bare identifier (amount), a dotted identifier path (account.amount, account.owner.region), and '*'. Any other value is refused at measures.METRIC.sql / dimensions.DIMENSION.sql with code invalid_format. That covers a CASE expression, an aggregate or a ratio of aggregates, a quoted or $-prefixed spelling, an empty string and a broken path. A column reference parses byte-identically to before.
• The identifier half is the pattern the readers already use to tell a column path from an expression: IDENTIFIER_PATH in native-sql-strategy.ts, and the field gate's bare-identifier / identifier-path pair. So the contract admits exactly the values those readers resolve to fields.
• The rule is a .regex(), not a refinement, so the published JSON Schema carries it as a pattern. A first cut used refinements, and the build's dropped-refinement gate refused it: a JSON-Schema-validated document would have been judged differently from the parse. The pattern closes that gap, and dropped-refinements.baseline.json is untouched.
• Each prescription opens with the contract sentence. It names the dataset form: a measure with its own structured filter for a conditional count or sum, and derived: { op, of: [...] } over named measures for a ratio, sum, difference or product. It also states the ratio's 0–1 scale. The dimension prescription says that a CASE bucket has no expression form in either layer.
• Neighbouring prescriptions no longer offer "fold the condition into the metric's own sql expression" as a live channel. This covers the retired metric filters guidance, the analytics query filters guidance, the metric-filters-removed conversion summary, its D3 entry cube-metric-filters-retired, and its step-18 rationale fragment. All of them are unreleased major-18 text.

ADR-0087. The D3 entry cube-member-sql-expression-retired (migrations/entries/semantic/) and its step-18 rationale fragment were written after merging a main that contains #20953, which landed as c6b3a01d5d. registry.ts was regenerated by gen:migration-registry, never edited by hand. There is no D2 conversion, because an expression has no mechanical rewrite into a dataset. There is no RETIRED_KEYS_BY_MAJOR row, because no key left the shape.

Liveness. The analytics_cube rows measures.sql and dimensions.sql stay live, re-verified 2026-09-30, with the narrowing recorded and the field gate's fieldsOfColumnSql added to the evidence.

Generated. Only content/docs/references/data/analytics.mdx moved. The authorable-surface, api-surface and json-schema.manifest ratchets are byte-identical, as expected for a value narrowing. spec-changes.json and the upgrade guide stay at protocol 17, so major-18 entries do not project yet, and both checks are green.

Showcase. The showcase_delivery cube loses done_rate. The showcase_task_metrics dataset gains done_count (aggregate: 'count', filter: { status: 'done' }) and done_rate (derived: { op: 'ratio', of: ['done_count', 'task_count'] }, format: '0.0%'), in the same shape as the existing paid_rate. No dashboard read the cube's done_rate, so there was nothing to re-pin there. test/gap-fill.test.ts is re-pinned: the cube's measure list, the parse of the shipped cube, and the dataset's filtered-count-over-count form plus its DatasetSchema parse.

@objectstack/service-analytics. One test and the README, nothing else:

• cube-authored-format-granularity.test.ts built its custom-SQL fixture with CubeSchema.parse, which now refuses it. The fixture is built unparsed instead, plus one assertion that the parse refuses it. The engine-path refusal it pins is unchanged.
• README.md no longer tells a reader to fold a per-metric condition into the metric's own sql expression. That text ships in the package, so it gets a patch line in the changeset. This file is outside the claim's declared surface; see the Acceptance notes.

The gate's stand-down branch in analytics-service.ts is not touched. #20965 remains open for it.

The fork clause

The fork clause did not fire. The one authored expression member in the tree is done_rate, and its structural equivalent exists and is measured (next section). A shape-level reading for the seat: a dimension CASE bucket has no dataset equivalent, because a dataset dimension names a field and its only bucketing is dateGranularity. No authored cube in the tree carries one. Two service-analytics gate fixtures do (dimension-source-field-gate.test.ts, where-source-field-gate.test.ts), but they are built without the parse to pin the runtime branch #20965 owns. Out-of-repo cubes are NOT MEASURED.

The measure-level filter, verified before relying on it

• Code path. compileDataset reads m.filter into measureFilters. DatasetExecutor splits filtered measures off with splitMeasuresByFilter and runs one supplementary query per filtered measure over the base filter combined with that measure's filter. It then evaluates derived on the merged row, with ratio as a / b and null on a zero denominator.
• Unit pins. The existing dataset-executor.test.ts cases cover a supplementary query for a measure-scoped filter and a derived measure over filtered and unfiltered dependencies, and dataset-compare-measure-filters.test.ts covers the number a reader sees. All are green in the service-analytics run below.
• Live. An ephemeral showcase boot on a private port (pnpm dev -- --fresh, torn down after) queried the task dataset through the analytics dataset door as the seeded admin. done_count and done_rate reconciled against the raw showcase_task rows in every priority bucket and in the ungrouped total. done_rate equalled done_count / task_count, and the column carried format: '0.0%' and percentScale: 'fraction'. The cube's meta listed its three remaining measures.

Tests (final head fa979c57ed unless stated)

• @objectstack/spec:
  • vitest run --project local src/: 544 files, 16268 passed, 1 todo.
  • --project local scripts/: 41 files, 950 passed, 1 skipped (at a32fd122dc; the second merge brought no scripts/ change under packages/spec).
  • The relevant --project repo files: 10 files, 300 passed. These are step18-rationale-merge, conversions-major18-merge, liveness/evidence, liveness/proof-registry, cube-member-inner-name-retirement, cube-refresh-key-retirement, retired-key-migrate-sentence, root-index, file-description and category-title.
  • typecheck exit 0.
• @objectstack/service-analytics: test gave 149 files and 3449 passed; typecheck exit 0, and the edited test is in its program (--listFiles).
• @objectstack/example-showcase: vitest run gave 29 files and 387 passed, after rebuilding its closure (60 tasks); typecheck exit 0, and the three edited files are in its program.
• Gates:
  • node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 116 families. All 116 were run, and --ran reconciled them as "116 derived, 116 run, 0 NOT-MEASURED, 0 UNRUN", each with an exit code.
  • 115 of them exited 0, including check:generated, check:liveness, check:adr-0087-registration (reads the new marker), check:changeset-no-major, check:empty-changeset, check:doc-authoring and check:nul-bytes.
  • The other one is pnpm check:platform-checklist, which exited 1 on an anchor this diff does not touch. areas/identity-auth.json cites plugin-auth/src/auth-plugin.ts#twoFactor, and that symbol is absent. This branch's bytes for packages/plugins/plugin-auth, docs/qa/platform-checklist, scripts/check-platform-checklist.mjs and scripts/symbol-anchors.mjs are identical to the merge base 05be352596, so it is main's state, not this diff's.
• Lint, a declared narrowing: eslint --no-inline-config --format json over the 10 changed lintable files gave 10 files, 0 errors and 0 warnings.
  • The population comes from eslint.config.mjs: the **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} block. The other changed files are .md, .mdx and .json.
  • The file count comes from the JSON output.
  • Invariance: the config never enables type-aware linting (no parserOptions.project, no typed rules), so this diff cannot move a verdict on an untouched file. The whole-repo pnpm lint is CI's.

Ablations (each from the committed state; disk-verified through scripts/ablation-replace.mjs; restore proven by blob hash equal to HEAD and an empty git diff HEAD)

leg	mutation	result under mutation	restored
A1	the member sql pattern admits anything	new spec pin: 9 failed / 6 passed (every refusal, door and pattern case red)	15 / 15 green
A2	the metric filters guidance offers the sql expression channel again	1 failed (the guidance case)	green
A3	the D3 id renamed in the generated registry region	1 failed (the registration case)	green
A4	the showcase done_count loses its filter	gap-fill: 1 failed (the dataset-form case)	green
A5	the pattern admits anything, then @objectstack/spec rebuilt	ablation-dist-preflight marker present in 20 built files; the service-analytics parse assertion failed (expected true to be false)	rebuilt; marker absent from all 230 files; tree clean; 14 / 14 green

The expected direction was "turns red" in all five, and that is what was observed. No ablation file is left in the tree.

Acceptance notes

• Surface breach, declared. packages/services/service-analytics/README.md is outside the claim's file surface. The dev contract's rule says published text this change makes false is fixed in the same round, and the dev contract outranks the dispatch words where they conflict. The edit is one paragraph, and the changeset carries '@objectstack/service-analytics': patch for it. The seat can drop both if it prefers service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965 to carry the fix.
• Not fixed here, governed (Tier H). skills/objectstack-ui/rules/dashboards.md still escalates past a dataset to "a hand-authored Cube (raw SQL / explicit joins)" (≈:78), and lists "any custom-SQL metric" as a dataset gap (≈:70). Both are now false: a cube member takes no SQL expression, and joins were already derived. The natural carrier is the separate Tier H docs PR the ruling names for ADR-0021's dated note. It is not mixed in here.
• Not fixed here, internal. docs/qa/platform-checklist/areas/dashboards.json (the cube meta item, ≈:976, :991, :1037) names done_rate among "exactly its four measures" and as a variant. The cube now declares three. No gate reads that text. Carrier: the checklist's next revision.
• Boundary, left as ruled. '*' is admitted on a dimension and on a non-count measure, because the execution parameters admit it on both members. Neither was ever a working query. Separately, the number / string / boolean measure types existed to carry an expression. With an identifier sql, the raw-SQL path emits the column unaggregated and the ObjectQL path refuses it, so retiring those three types is the natural follow-up. That is a decision for the seat, not something this PR does.
• Not added: a tree-scoped text pin. The narrowing is enforced at every parse door. The one authored cube in the tree is parsed at import (defineCube) and pinned by the showcase test. The tree's other expression members are deliberate unparsed runtime fixtures in service-analytics, owned by service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965's cleanup. A text scan would have needed a directory exclusion and a new cross-package radius.
• tsc does not catch an expression member, because sql is still string; the parse is the judge. Stored analytics_cube rows and built artifacts that carry an expression are NOT MEASURED here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-analytics, @objectstack/spec, touching 11 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/services/service-analytics/README.md, packages/spec/liveness/analytics_cube.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/api/data-api.mdx (via DimensionSchema (symbol, a top-level const), MetricSchema (symbol, a top-level const))
• content/docs/kernel/contracts/data-engine.mdx (via account.industry (literal, a string literal in DimensionSchema))
• content/docs/protocol/objectql/query-syntax.mdx (via account.industry (literal, a string literal in DimensionSchema))

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

• content/docs/releases/v17/17-2.mdx (via MetricSchema (symbol, a top-level const))
• content/docs/releases/v17/17-4.mdx (via AnalyticsQuerySchema (symbol, a top-level const))

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

• 2 changed file(s) yielded no anchor (packages/services/service-analytics/README.md, packages/spec/liveness/analytics_cube.json) — pages documenting those are invisible to this run
• 7 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 137 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 9b0de7de73699771b69649bf7b507fbd2a842260 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from b1178fecb78741ce96360f0cc1c7ecd023cbb108 — the merge of head ac70996345fd12a48696af01fbbb319bd593bf13 into base 9b0de7de73699771b69649bf7b507fbd2a842260, 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 b1178fecb78741ce96360f0cc1c7ecd023cbb108 && git checkout b1178fecb78741ce96360f0cc1c7ecd023cbb108
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9b0de7de73699771b69649bf7b507fbd2a842260 ac70996345fd12a48696af01fbbb319bd593bf13 && git checkout -B drift-repro 9b0de7de73699771b69649bf7b507fbd2a842260 && git merge --no-ff ac70996345fd12a48696af01fbbb319bd593bf13

node scripts/docs-audit/affected-docs.mjs --json 9b0de7de73699771b69649bf7b507fbd2a842260

⚠️ 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 9b0de7de73699771b69649bf7b507fbd2a842260 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: e6b66ecde531197df2027f40a0799b86e4c7460b
Local-runs: none

① Derived judgments

Read against main at the merge base 05be352596 (no file this PR touches has moved on main since) and ruling D's execution parameters (5921156712), which bind. Disclosure discipline held: nothing below restates a request, a field spelling or a value from the dev's private live measurement.

Accept set — right. CUBE_MEMBER_SQL admits *, or one [A-Za-z_][A-Za-z0-9_]* identifier followed by zero or more .-joined identifier hops, anchored at both ends, no whitespace. The identifier half is byte-equal to IDENTIFIER_PATH in native-sql-strategy.ts:126 and to the field gate's BARE_IDENTIFIER (/i) plus IDENTIFIER_PATH pair in analytics-service.ts:307,396, so every admitted non-wildcard value is one fieldsOfColumnSql (:416) attributes to a field the gate judges. No expression shape passes: parentheses, operators, quotes, whitespace, a leading digit, an empty string, a trailing dot and a doubled dot all fail the anchored pattern, and the JS $ anchor admits no trailing line. Quoted and $-prefixed spellings are not legitimate identifier forms: a field name is ^[a-z_][a-z0-9_]*$ (field.zod.ts:1113, object.zod.ts:1612), neither reader above admits them, and the one place that tolerated a leading $ — the ObjectQL strategy's replace(/^\$/, '') (objectql-strategy.ts:1462-1470) — is a consumer-side alias with no authored instance anywhere in the tree (docs, skills and examples grepped). Refusing them is the ruling's narrowing, not an over-reach. '*' on a dimension and on a non-count measure stays admitted, exactly as the parameters name it and the seat re-ruled (Q2, A).

Refusal and prescriptions — right, and every form they name works on main today. invalid_format at measures.METRIC.sql / dimensions.DIMENSION.sql (zod 4 .regex(), one issue per member); the published JSON Schema carries the same pattern, pinned through z.toJSONSchema. The dataset form the prescriptions name: a measure-scoped filter is DatasetMeasureSchema.filter (analyticsCarrierFilter, dataset.zod.ts:196), read by compileDataset into measureFilters (dataset-compiler.ts:701) and run by DatasetExecutor as one supplementary query per filtered measure (dataset-executor.ts:177,1274-1296); derived: { op: 'ratio', of } is computeDerived (dataset-executor.ts:271, a / b, null on a zero denominator); the ratio column is annotated percentScale: 'fraction' (analytics-service.ts:2430). The "0–1 fraction" sentence is true. The dimension prescription's "keep the bucket as a field of the object" is the formula-field route the dashboards skill already teaches. "retired in @objectstack/spec 17" is the house spelling for an unreleased step-18 retirement (twenty siblings in view.zod.ts, page.zod.ts, report.zod.ts, dashboard.zod.ts) and is true the moment the next 17.x minor ships; spec is at 17.5.0, PROTOCOL_VERSION 17.0.0.

Doors — right. getMetadataTypeSchema('analytics_cube') is CubeSchema (metadata-type-schemas.ts:283); defineStack raises STACK_SCHEMA_INVALID / 422 (stack.zod.ts); defineCube throws the prescription. All four are pinned in cube-member-sql-column-reference.test.ts with a CONTROL cube that passes every door. "tsc does not catch it" is stated and true: the key's type stays string.

Showcase migration — right. done_rate leaves showcase_delivery; showcase_task_metrics gains done_count (count, filter: { status: 'done' }) and done_rate (ratio of done_count over the dataset's existing unfiltered task_count, format: '0.0%') — the shape paid_rate already uses. Same numbers at display: the old cube column shipped points 0–100 with no percentScale (percentScaleOf answers one for a percent field only), so the pinned renderer (packages/core/src/utils/dataset-format.ts:420 at objectui db11afd49) fell back to percentDisplayValue, which leaves a value outside the open interval (−1, 1) as is; the new column is a fraction tagged 'fraction', multiplied by 100 — both print the same percentage for the same ratio, and the new one cannot be fooled at a rate under one point. Same format: 0.0% kept. The raw API number is divided by 100, disclosed in the changeset, the D3 entry, the rationale and the prescription. No dashboard, report or saved query named the cube's done_rate (grep of examples, packages, content, skills on main: the cube, its test, the checklist prose and one service-analytics fixture only). gap-fill.test.ts still tests something: the cube's measure keys, a CubeSchema re-parse of the shipped literal, the dataset's filter and derived shape with field absent on the count, and a full DatasetSchema parse through the cross-measure refinement. cube-authored-format-granularity.test.ts builds its expression fixture unparsed, adds the parse-refusal assertion, and keeps the engine-path refusal pin; ablation A5 is its direction proof.

ADR-0087 — right, and generator-produced where the generator owns it. 18.cube-member-sql-expression-retired.ts carries the four SemanticMigration fields, no backticks or pipes in surface. Its literal and leading comment appear verbatim, four-space indented, in the os-generated semantic:18 region sorted by id — after cube-member-inner-name-retired, before cube-metric-filters-retired — exactly as build-migration-registry.ts concatenates (order derived, never declared). The sequence holds: c6b3a01d5d (#20953) is an ancestor of the first merge 93d8e1f0e1, which precedes the regeneration commit a32fd122dc. STEP18_RATIONALE is hand-kept by design (its header: sorted by id, order one more than the highest); the fragment sits in its sorted slot with order: 53, the next after 52, and step18-rationale-merge holds that shape. No D2 conversion and no RETIRED_KEYS_BY_MAJOR row is right: no key left the shape, so the authorable-surface, api-surface and json-schema.manifest ratchets are byte-identical — the skill's enum-narrowing row, not a missed regeneration. The hand-kept conversions/registry.ts summary edit of metric-filters-removed (toMajor: 18) projects into neither spec-changes.json nor the upgrade guide at protocol 17, so no regeneration was owed. The edited cube-metric-filters-retired entry and fragment and the two filters guidances no longer offer the retired channel — pinned by the new test's negative matches.

Liveness ledger — one row earned, one row's note false. Both rows stay live, verifiedAt 2026-09-30, and every evidence anchor resolves on main (resolveMeasureSql :919, resolveDimensionSql :903, resolveFieldName :1462, fieldsOfColumnSql :416). The measures.sql note is accurate except that "'*' on a count measure" under-states the schema, which admits '*' on every measure type. The dimensions.sql note says "a SQL expression — a CASE bucket included — and '*' are refused at parse": FALSE at every moment, on main when this lands and after. The dimension uses the same CUBE_MEMBER_SQL; its TSDoc in the same diff says "'*' is admitted with the measure's accept set"; the PR body says so; and cube-member-sql-column-reference.test.ts pins '*' as ADMITTED on a dimension. The ledger note is the text the next auditor reads instead of re-measuring (the retirement skill's own rule), and it erases the very boundary the dev flagged as Q2 and the seat left for #21000 to narrow. BLOCKING. Fix: in packages/spec/liveness/analytics_cube.json, the dimension note reads that '*' is admitted (ruled; never a working query), and the measure note drops "on a count measure".

Other text, tested. The schema comment's "ObjectQLStrategy#resolveMeasureAggregation refused it" is over-broad: that arm (objectql-strategy.ts:1474) refuses the number / string / boolean partition only; an expression under an aggregate type was forwarded as a field name and failed downstream. "The two strategies never agreed" holds either way; not blocking. The .describe() strings, the regenerated analytics.mdx (Metric and Dimension rows, twice each), the showcase cube comment, the translations (datasets.NAME.measures.NAME.label is the declared bundle shape, translation.zod.ts:924,957, label optional on the dataset block; both claimed locales filled), the README paragraph, and the PR body's "Generated", "Showcase", "Tests" and "Acceptance notes" sections each read true against the tree. analytics-service.ts is not in the file list, so #20965's stand-down is untouched. Fork clause: no authored dimension CASE bucket exists; the two gate fixtures that carry one (dimension-source-field-gate.test.ts:503, where-source-field-gate.test.ts:713) are built without CubeSchema.parse. Out-of-repo cubes NOT MEASURED, as stated.

Check-runs on e6b66ecde5 (35, deduped by name keeping the newest started_at; none running): 33 success, 2 skipped — Console Pin Gate (no pin move) and Packed-tarball smoke (opt-in). Green include Spec property liveness, TypeScript Type Check (the eight spec artifacts, check:migration-registry, check:adr-0087-registration), Lint & Repo Gates, Check Changeset, Type Check · consumer gates (i18n coverage back to baseline after the patch round 5922922632), Test Core 6 of 6, Dogfood Regression Gate 3 of 3, Temporal Conformance. Combined status success (Vercel).

② Semver level

.changeset/20943-cube-member-sql-column-reference.md: @objectstack/spec: minor with the BREAKING banner, Clause-②: yes (narrowing), the FROM → TO migration, the one-line fix, and the adr-0087 registered marker naming cube-member-sql-expression-retired — a new id, so registered is the right arm. That matches the diff: an accept-set narrowing on a published schema with no export, key or def change, shipped minor under the launch-window convention (check-changeset-no-major; eight sibling changesets on main spell it the same way). @objectstack/service-analytics: patch is earned: README.md is in that package's files and this PR makes its old sentence false; no runtime byte changes, and the one edited test does not ship. example-showcase is private, no line owed. The PR body's Clause-②: yes (narrowing) is present and equal to the changeset's.

③ Boundary flags

• Dev report 5922668750 open_questions: Q1 (retire number / string / boolean) → seat A, filed as spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000, bare, Blocked-by: #20943 — verified open. Q2 ('*' on a dimension or a non-count measure) → A, as ruled — the ledger note above contradicts this answer; the note is corrected, not the schema. Q3 (README surface breach) → A, keep; the patch line is the price and is paid.
• Deviations: the declared file-surface breach (README) — declared in the report and the PR body, accepted by the seat. The refinement-to-regex cut — a self-correction the dropped-refinement gate forced; dropped-refinements.baseline.json untouched, right.
• out_of_scope_findings: skills/objectstack-ui/rules/dashboards.md :70 / :78 still teach a raw-SQL cube escape — verified on main; carried by the Tier H docs PR together with ADR-0021's dated note. docs/qa/platform-checklist/areas/dashboards.json :976 / :991 / :1037 count four measures with done_rate — verified; same carrier. CubeSchema.sql "Base SQL statement or Table Name" (analytics.zod.ts:493) — outside ruling D (members only); noted, unfiled. The twoFactor checklist anchor — main's, the watchdog's.
• i18n round 5922922632 out_of_scope: dispatch-gates --commands derived no check:i18n-coverage family for an examples/ source edit although CI runs it on every PR and it went red on this PR — carrier none. ESCALATED: a scripts/pm/dispatch-gates.mjs derivation card (an examples/ subtree watch hint, or the config import closure) is owed by the pm-tooling lane; not this PR's.
• Follow-up for the services lane (service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965 / spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000): the ObjectQL strategy's replace(/^\$/, '') on member sql is unreachable for any parsed cube and is a consumer-side alias of the Prime Directive Add comprehensive test suite for Zod schema validation #12 class — delete it with the stand-down.
• Not touched, right: the analytics-service.ts:409 stand-down (service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965); ADR-0021's dated note (Tier H docs PR). Stored analytics_cube rows carrying an expression are NOT MEASURED here; service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965's triage already rules the gate refuses, never passes, such a row.

Implemented-by: claude/issue-20943-cube-sql-identifiers
Reviewed-by: session_01Sfe5YjBLwB9J3y8fvm2xq1

VERDICT: FAIL

Adopted and posted by domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1) · 2026-10-01T01:59Z · rendered by the seat's at-tier review subagent on this head. The seat read its served tier family from the subagent transcript before posting. ⚠️ The disclosure discipline holds. FAIL accepted.

• Cut round (the dev, on this branch): packages/spec/liveness/analytics_cube.json.
  • The dimensions.sql note says '*' is "refused at parse". It is admitted, as the schema TSDoc, the PR body and the new pin all say. The note is corrected to say so.
  • The measures.sql note's "'*' on a count measure" is corrected to "on any measure", with the count-only boundary left to spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000, as ruled.
  • Optional, in the same round: the schema comment's over-broad "ObjectQLStrategy#resolveMeasureAggregation refused it" is narrowed to the number / string / boolean partition.
  • Nothing else changes, and the schema stays.
• The derivation gap is already filed as finding(pm): dispatch-gates never derives check:i18n-coverage for an edit under examples/ — the gate lints each example config, whose imports span the whole example tree, but its population roots are undeclared #21011, from the i18n round's report. The record's "carrier: none" predates that filing.
• Noted for service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965 / spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000: the ObjectQL replace(/^\$/, '') alias is now unreachable for parsed cubes.
• Next: a delta re-review at the new head.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: ac70996345fd12a48696af01fbbb319bd593bf13
Local-runs: none

① Derived judgments

Delta re-review of the cut round the adoption 5923211985 ordered on the prior FAIL at e6b66ecde5. Read against main at the merge base 05be352596 (no file this PR touches has moved on main since — git diff --stat over the 15 paths is empty; the two main commits since that touched service-analytics, 8d329f02ee and f8178ffece, leave every symbol cited below in place, and I read those symbols at the current origin/main 2f2fa11d75). Ruling D's execution parameters (5921156712) bind. Disclosure discipline held: nothing below restates a request, a field spelling or a value from the dev's private live measurement.

The delta is exactly the cut, and nothing else moved — right. One commit, two files, 6 insertions / 3 deletions: the two note strings in packages/spec/liveness/analytics_cube.json (measures.sql, dimensions.sql) and one paragraph of the block comment above CUBE_MEMBER_SQL in analytics.zod.ts. CUBE_MEMBER_SQL is byte-identical (^(?:\*|[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)$), and no .describe() string, prescription, guidance, test, generated artifact, D3 entry, registry region or changeset line changed. The edited comment sits on a non-exported const and is projected into no published or generated artifact (grepped packages/spec, content and json-schema at the head: the paragraph appears nowhere else), so no regeneration was owed and none is missing. The ledger note is free text no check scans (check-liveness.test.ts:451 says so), so each corrected sentence is this record's to judge, and I did.

measures.sql note, sentence by sentence — true now, on main when this lands. "'*', which the schema admits on any measure": MetricSchema.sql is z.string().regex(CUBE_MEMBER_SQL) with no refinement crossing type, so the wildcard parses under every AggregationMetricType; the pin parses the count fixture and asserts '*' against the published pattern independent of type. The pin does not cross '*' with a non-count type, and need not: the shape admits it by construction. "every admitted value other than '*' (which reads no field value) resolves to a field the gate can judge": fieldsOfColumnSql on main answers one field for a BARE_IDENTIFIER, the hop chain plus column for an IDENTIFIER_PATH, and an empty list for everything else, * named in its own comment; the where-gate's source === '*' arm treats it as no field too. The identifier half of CUBE_MEMBER_SQL is byte-equal to that pair, so every non-wildcard admitted value is attributed. This was the declared extra correction, and it fixes a sentence that was false for '*' in the prior wording — in scope of "corrected to what the schema admits". "the count-only boundary is #21000's" — see the pointer finding under ③; the schema half of the sentence is right.

dimensions.sql note — true now, on main when this lands. "'*', which the schema admits on a dimension too": DimensionSchema.sql uses the same CUBE_MEMBER_SQL; the pin parses '*' on a dimension (its comment: in the accept set for both members) and pins the two members' JSON-Schema pattern equal. "the accept set ruling D's execution parameters name for both members": the ruling's shape-after sentence names an identifier and '*' for measure and dimension sql alike. "it never made a working query": a reading of main, not a door measurement — NativeSQLStrategy#resolveDimensionSql hands * to qualifyAndRegisterJoin, which returns a non-IDENTIFIER_PATH verbatim, so the dimension column is a bare * in SELECT and GROUP BY; ObjectQLStrategy#resolveFieldName returns * as the group-by field, and no object can declare a field so spelled (^[a-z_][a-z0-9_]*$). For a non-count measure the same holds: AGGREGATE_SQL wraps SUM(*) / AVG(*) / MIN(*) / MAX(*) / COUNT(DISTINCT *), and the ObjectQL path forwards * as the aggregate field. NOT MEASURED through a door, and the note does not claim it was. "a SQL expression — a CASE bucket included — is refused at parse": pinned (invalid_format at dimensions.bucket.sql for a CASE, one issue per member).

Schema comment — true on main, and narrower than before, as the adoption allowed. "ObjectQLStrategy#resolveMeasureAggregation refuses only the number / string / boolean partition (EXPRESSION_METRIC_TYPES)": the resolver throws invalidMemberError if and only if EXPRESSION_METRIC_TYPES.has(direct.type), and that set is new Set(['number', 'string', 'boolean']) in native-sql-strategy.ts, imported by the ObjectQL strategy — one set, two strategies. "forwards an expression under an aggregate type as a field name, which fails downstream": the fall-through returns { field: direct.sql.replace(/^\$/, ''), method: type }, so an expression string becomes the engine aggregate's field; the strategy's own comment records the downstream outcome (the SQL driver's INVALID_QUERY / 400, the in-memory evaluator's null). The "two strategies never agreed" sentence that follows still holds. Internal code comment, AI-facing only in the tree; not projected.

Residual over-broad text, unchanged by the delta, the same reading the prior record made — not blocking. CUBE_MEMBER_SQL_RETIRED ("one ran it verbatim, the other refused it"), the changeset, the D3 entry's reason and the step-18 fragment still say the ObjectQL path "refused it". True for the number / string / boolean partition, which is what the changeset's FROM example (type: 'number') and the showcase's retired member used; for an aggregate-typed expression the ObjectQL path fails downstream rather than at the resolver. "never agreed" holds either way, the FROM → TO these texts exist for is unaffected, and the adoption scoped the cut to the ledger plus the optional comment. Noted, not re-raised.

Every other '*' sentence in the PR is consistent with the corrected notes — right. "or '*' for a count" (the measure .describe(), the measure prescription, the changeset, the D3 entry, the fragment, the regenerated analytics.mdx rows, the README) names the wildcard's use, not the accept set's boundary; none says '*' is refused on a dimension or count-only. The dimension TSDoc says "'*' is admitted with the measure's accept set". The PR body's "Boundary, left as ruled" bullet and both ledger notes now say the same thing.

Prior judgments the delta cannot reach — re-read, unchanged. Accept set (right: identifier half byte-equal to IDENTIFIER_PATH and the gate's BARE_IDENTIFIER / IDENTIFIER_PATH pair; no expression shape passes; quoted and $-prefixed spellings are not legitimate identifier forms). Refusal and prescriptions (right: invalid_format at measures.METRIC.sql / dimensions.DIMENSION.sql; the dataset form they name — a measure-scoped filter, derived: { op, of }, ratio as a 0–1 fraction annotated percentScale: 'fraction' — works on main today). Doors (CubeSchema, the analytics_cube write door, defineStack 422, defineCube; all pinned). Showcase migration (right: done_rate leaves the cube, done_count plus a ratio done_rate join the dataset in the paid_rate shape, same percentage at display, raw number divided by 100 and disclosed; gap-fill.test.ts re-pinned; cube-authored-format-granularity.test.ts builds its fixture unparsed and adds the parse-refusal assertion). ADR-0087 (right: D3 entry cube-member-sql-expression-retired in the generated semantic:18 region in sorted slot, fragment order: 53, registry regenerated after c6b3a01d5d, no D2, no RETIRED_KEYS_BY_MAJOR row, ratchets byte-identical). Liveness evidence anchors (#resolveMeasureSql, #resolveDimensionSql, #resolveFieldName, #fieldsOfColumnSql, #registerAll, #CAPABILITY_PROVIDERS) resolve on the current origin/main. Translations block, README paragraph, retired filters guidances, metric-filters-removed summary — each as the prior record read them.

PR body at this head — every sentence re-read; the bytes are the ones the prior record read (12555, unchanged). "What changes", "The fork clause", "The measure-level filter", "Ablations", "Acceptance notes": true against the tree. "Liveness … stay live, re-verified 2026-09-30, with the narrowing recorded": true, and truer than before. "Tests (final head fa979c57ed unless stated)": a scoped header; the two later commits (the translations block, this cut) are reported on the card (5922922632, 5923452954), not in the body, so a reader of the body alone does not learn the ledger notes were corrected. Not false; noted for the seat's merge-time edit if it wants the body to name the cut. #20965 remains open for it: true (open, pm:blocked, p2; its triage corrected "unreachable" to "fail closed on a stored expression member", which agrees with the ledger notes' "remain for a cube that reaches the service without meeting the parse" and the body's "stored rows NOT MEASURED here"). Closes #20943 and Clause-②: yes (narrowing) present.

Check-runs on ac70996345 (35 fetched, 35 distinct names, deduped by name keeping the newest started_at; none running): 33 success, 2 skipped — Console Pin Gate (no pin move) and Packed-tarball smoke (opt-in). Green include Spec property liveness (the ledger parses and its anchors resolve), TypeScript Type Check (the generated artifacts, check:migration-registry, check:adr-0087-registration), Lint & Repo Gates, Check Changeset, Type Check · consumer gates (i18n coverage at baseline), Test Core 6 of 6, Dogfood Regression Gate 3 of 3, Temporal Conformance, Build Core, Build Docs. Combined status success (Vercel).

② Semver level

Unchanged by the delta, and still right. .changeset/20943-cube-member-sql-column-reference.md: @objectstack/spec: minor with the BREAKING banner, Clause-②: yes (narrowing), the FROM → TO migration, the one-line fix and the adr-0087 registered marker naming cube-member-sql-expression-retired — an accept-set narrowing on a published schema with no export, key or def change, shipped minor under the launch-window convention (check-changeset-no-major green on this head). @objectstack/service-analytics: patch is earned by the README sentence this PR makes false; no runtime byte changes. The delta adds a code comment and two ledger notes — no published byte, no line owed. example-showcase is private. Clause-②: yes (narrowing) — the PR body and the changeset agree.

③ Boundary flags

• Cut-round report 5923452954: open_questions empty, out_of_scope_findings empty. One deviation, declared: the extra correction in the measures.sql note ("every admitted value other than '*'"). Judged true above and inside the adoption's "corrected to what the schema admits"; accepted.
• The adoption's three items: the dimensions.sql note no longer says '*' is refused — done, true; the measures.sql note no longer says count-only — done, true; the optional comment narrowing — done, true. "Nothing else changes, and the schema stays" — held (two files, the regex byte-identical).
• ESCALATED to the seat, not a byte of this PR: both corrected notes say the '*' count-only boundary "is spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000's". spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000's body (filed 2026-10-01T01:10Z) and its triage (5923362062, 02:14Z) carry the number / string / boolean retirement only; the '*' boundary reached spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000 through the seat's Q2 answer in 5922695050 ("can ride spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000 if triage wants it" — conditional) and the adoption ("left to spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000"), never through spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000's own text. The ledger note is what the next auditor reads instead of re-measuring, and today the pointer lands on a card that does not mention the thing pointed at. The seat owes one line on spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000 naming the '*'-on-a-dimension / non-count-measure boundary (or a card of its own if triage declines it there), so the two pointers resolve. The sentences are true the moment that line exists; the contract half of each sentence is true now.
• Prior ③ flags, re-read: Q1 (metric types) → spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000, open, triaged p3 domain:spec pm:blocked, direction an enum-value retirement with the EXPRESSION_METRIC_TYPES partition deleted in the same PR. Q2 ('*') → A as ruled; the ledger now agrees with the answer. Q3 (README) → kept, patch paid. README surface breach declared and accepted; refinement-to-regex self-correction right, dropped-refinements.baseline.json untouched. skills/objectstack-ui/rules/dashboards.md :70 / :78 and docs/qa/platform-checklist/areas/dashboards.json :976 / :991 / :1037 → the Tier H docs PR carrying ADR-0021's dated note (ADR-0021 on main carries no such note yet, as expected — never mixed in here). CubeSchema.sql description — outside ruling D, noted. The twoFactor checklist anchor — main's. The i18n derivation gap — filed as finding(pm): dispatch-gates never derives check:i18n-coverage for an edit under examples/ — the gate lints each example config, whose imports span the whole example tree, but its population roots are undeclared #21011 per the adoption. The ObjectQL replace(/^\$/, '') alias — unreachable for parsed cubes, service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965 / spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000's.
• Not touched, right: the analytics-service.ts stand-down (service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965, whose triage rules the gate fails closed on a stored expression member); ADR-0021's dated note. Stored analytics_cube rows carrying an expression and out-of-repo cubes are NOT MEASURED here, as the PR body states.

Implemented-by: claude/issue-20943-cube-sql-identifiers
Reviewed-by: session_01Sfe5YjBLwB9J3y8fvm2xq1

VERDICT: PASS

Adopted and posted by domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1) · 2026-10-01T02:33Z · rendered by the seat's at-tier review subagent on this head. The seat read its served tier family from the subagent transcript before posting. ⚠️ The disclosure discipline holds.

• The escalation is answered in this act: a line on spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000 names the '*' count-only boundary, so the ledger notes' "spec+service-analytics: retire the cube metric types number / string / boolean — they existed to carry a SQL expression, which #20943 retired from a member's sql #21000's" pointer resolves.
• The residual "the ObjectQL path refused it" in the D3 reason, changeset and step-18 fragment is true for the number / string / boolean partition the examples used, and "never agreed" holds either way. It is noted, not held.
• Not governed. needs:contract-review comes off the PR and [Decision] analytics field gate (#20917): an authored cube member whose sql is an expression — keep the stand-down, judge its identifiers, refuse it, or retire expressions #20943 in a separate act after this record reads back. Then the PR goes ready and into the merge queue.

---

Generated by Claude Code