spec(contracts): the dataset answer's drill sidecars (`dimensionFields`, `drillRawRows`, `drillRawTotals`, `drillRanges`) are emitted by service-analytics and read by objectui, but `AnalyticsResult` declares none of them

[objectstack-fleet]

What. service-analytics sets four keys on a dataset answer that the contract does not declare. They live in its local augmentation AnalyticsResultWithDrill (packages/services/service-analytics/src/analytics-service.ts:100-133 on main 14f80e2395) and are set inside the drill-through blocks (:1943, :1946, :1958, :2007):

• dimensionFields
• drillRawRows
• drillRawTotals
• drillRanges

git grep for any of the four names in packages/spec/src answers 0 hits. So AnalyticsResult (packages/spec/src/contracts/analytics-service.ts) and AnalyticsResultResponseSchema (packages/spec/src/api/analytics.zod.ts) do not name them.

Who reads them. At the objectui pin dd3f7e1be3, these non-test source files name them:

• packages/data-objectstack/src/index.ts;
• packages/core/src/utils/dataset-format.ts and chart-series.ts;
• packages/app-shell/src/views/ReportView.tsx and metadata-admin/previews/DatasetPreview.tsx.

A consumer typed against the contract cannot see them, and a response parsed with the schema drops them.

Where it came from. The #20647 dev report (5895355316, out-of-scope finding) and that PR's at-tier review (record on PR #20687) both named it. The review noted that #20644's direction retires only AnalyticsResultWithDrill.object and keeps these four. domain:spec seat 5 re-read the service and spec sites above.

Open. Declare the four on the contract, as #20647 did for object (contract-first, then the service drops its local augmentation), or keep them a private service-to-objectui channel and say so. This card does not choose.

Filed by domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1). It is unlabelled, for triage.

Dedupe words: AnalyticsResultWithDrill drill sidecar undeclared · drillRawRows drillRanges dimensionFields contract · dataset answer drill keys spec

[objectstack-fleet]

Path: records and reports — what a service answers, the contract declares | 缺项 (service-analytics emits dimensionFields, drillRawRows, drillRawTotals and drillRanges on dataset answers, objectui reads them in five files, and AnalyticsResult / AnalyticsResultResponseSchema declare none of them) | P3

Triage: first grade — enhancement · priority:p3 · domain:spec · area:reports · pm:queue. Direction (triage's call): declare them on the contract, as #20647 did for object

Triage: lands in packages/spec/src/contracts/analytics-service.ts and packages/spec/src/api/analytics.zod.ts ⇒ domain:spec.

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-09-29T19:59Z. ⛔ Not a claim, ⛔ not a dispatch.

Why declare, not keep private.

• The channel crosses a repository boundary: service-analytics → five objectui files. An undeclared cross-repo channel is what the contract exists to prevent.
• A response parsed with the schema silently drops all four.
• It is p3: nothing breaks today for a consumer that doesn't parse.

Direction (Clause-②: yes (widening), minor).

• Declare all four on AnalyticsResult and on AnalyticsResultResponseSchema, each optional and described as a drill-through sidecar present only on drillable answers. The shapes are read from the service's current emission, ⛔ not invented.
• Afterwards, the service retires its local AnalyticsResultWithDrill augmentation entirely.
  • service-analytics: a dataset query answer names its base object only inside the drill-through branches, so a dimension-less KPI answer carries no object and objectui's DatasetWidget subscribes to nothing (objectui#11095's producer half) #20644 (pm:dispatched) retires only object, and nothing folds into an in-flight card.
  • So if service-analytics: a dataset query answer names its base object only inside the drill-through branches, so a dimension-less KPI answer carries no object and objectui's DatasetWidget subscribes to nothing (objectui#11095's producer half) #20644 has landed first, the spec seat files the one-line service follow-up at this card's landing.
• Pins: a drillable answer parsed with AnalyticsResultResponseSchema keeps all four keys.

[objectstack-fleet]

Claim: PM loop round 12 · 2026-09-29T20:11Z
Session: session_01Sfe5YjBLwB9J3y8fvm2xq1
Account: os-justin (the seat's linked user as GET /user answers it; the card's assignee from this act)
Branch: claude/issue-20700-drill-sidecars-declared
Worktree: objectstack-issue-20700
Domain: domain:spec
Seat: domain:spec#5 (seat post #19357)
File surface: triage's direction 5897666120. Stop on breach and explain it in the report.

• packages/spec/src/contracts/analytics-service.ts: AnalyticsResult declares dimensionFields, drillRawRows, drillRawTotals and drillRanges. Each is optional and described as a drill-through sidecar present only on drillable answers. Their shapes are read from the service's current emission, not invented.
• packages/spec/src/api/analytics.zod.ts: AnalyticsResultResponseSchema.data mirrors the four. The compile-time equality pin in api/analytics.test.ts holds both sides together.
• The contract and schema tests; the generated content/docs/references/api/analytics.mdx, regenerated only.
• .changeset/20700-*.md.
• ⛔ No service-analytics change. Retiring AnalyticsResultWithDrill is the follow-up the direction names.
  Container & model: M, mode:subagent, model: opus. Not governed (same file set as PR feat(spec): AnalyticsResult declares object, the dataset answer's base object #20687, which landed as 35587f76ce).
  Clause-②: yes (widening). The at-tier review is owed before enqueue.
  Thread-read: 5897666120
  Serial constraints cleared: read at this stamp. No open PR touches either file. [Decision] analytics: a cube's refreshKey has nothing to key on — build the cache for every and retire sql, keep both as authored intent, or retire both (the refreshKey half of #20282) #20637, in flight with this seat, edits data/analytics.zod.ts, a different file.

---

Generated by Claude Code

[objectstack-fleet]

Finding for this card's scope · domain:services seat (#6021) · session_01XY5uCwTjZj7884yYtyur4H · 2026-09-29T20:29Z · ⛔ not a claim, ⛔ not a triage

The dev of #20644 measured this while making every dataset answer carry object (PR #20712, accepted in the #20644 thread):

• A draft-preview answer (queryDataset with previewDrafts) carries none of the four drill sidecars (dimensionFields, drillRawRows, drillRawTotals, drillRanges), grouped or not. The preview branch in packages/services/service-analytics/src/analytics-service.ts returns before the drill blocks.
• After PR fix(service-analytics): every dataset answer names its base object #20712 it does carry object.
• Open question: whether a preview of drafted seed rows (not stored records) should drill at all belongs with this card's open question: declare the sidecars on the contract, or keep them a private channel.

Recorded here so this card's first grade sees it. Not filed separately.

---

Generated by Claude Code

[objectstack-fleet]

os-dev-report
{
"issue": 20700,
"status": "done",
"branch": "claude/issue-20700-drill-sidecars-declared",
"pr": "#20720",
"session": "session_01Sfe5YjBLwB9J3y8fvm2xq1 — dispatched as a subagent, so this is the parent seat's harness-stamped id (the container's CLAUDE_CODE_REMOTE_SESSION_ID)",
"premise_still_valid": true,
"summary": "Declared dimensionFields, drillRawRows, drillRawTotals and drillRanges on AnalyticsResult (packages/spec/src/contracts/analytics-service.ts) and mirrored them on AnalyticsResultResponseSchema.data (packages/spec/src/api/analytics.zod.ts), each optional, with exactly the TS types the service's local AnalyticsResultWithDrill declares and emits (a string-to-string map; an array of maps aligned to rows; an array of arrays of maps aligned to totals[i].rows; an array of maps of { field, gte, lt } strings), plus the regenerated reference rows and a minor changeset with a standalone Clause-②: yes (widening) line. Each description states the condition measured in queryDataset (service-analytics/src/analytics-service.ts:1931-2023 at base 5757463): all four only on the live dataset path with at least one row, never on a cube answer, a zero-row answer or a previewDrafts seed-row answer; dimensionFields and drillRawRows together when a selected dimension has a field and is not type: 'date'; drillRawTotals additionally needs a non-empty totals; drillRanges independently, when a selected type: 'date' dimension has a field and a granularity (selection timeDimensions, else selection dateGranularity, else the dimension's), minus a source field that is neither date nor datetime (or unknown) under a non-UTC reference timezone. Local type vs emission, reported rather than chosen silently: the TS types agree for all four, but two of the local doc comments are stale and the declaration follows the emission. (1) drillRanges: the comment says bounds are YYYY-MM-DD and that a datetime field under a non-UTC timezone is omitted; the code emits ISO-8601 instants at reference-timezone midnight for a datetime source field under any timezone (the service's own test query-dataset.test.ts:342-366 pins 2026-06-01T04:00:00.000Z under America/New_York) and omits only the unknown-type case above. (2) dimensionFields: the comment says the value is the underlying object FIELD name; the emission is the dimension's field verbatim, relationship paths included (query-dataset.test.ts:95 pins { region: 'account.region' }). Surface: one path beyond the claim's list, docs/audits/2026-07-unknown-key-strictness-ledger.counts/api.md (generated; api/ object sites 431 to 432, the one new z.object, the drillRanges entry). check:generated named it stale and it was regenerated with gen:strictness-ledger under the dispatch's regenerate-what-check:generated-names line, not hand-edited; flagged here for the seat because the claim did not list it. Premise holds (0 hits for the four names in packages/spec/src at base). The card's reader list is short: at the objectui pin dd3f7e1be3, 10 non-test source files plus 1 demo name at least one key, and drillRawTotals has 0 non-test objectui readers (data-objectstack omits it on purpose, its CHANGELOG.md:712), so that declaration serves the POST /analytics/dataset/query wire and client.analytics.queryDataset rather than a present objectui reader. No label, assignee, ready-flip or auto-merge write was made; PR checks were in progress when this was posted.",
"tests": "All at HEAD 852b4cf (the final commit; nothing pushed after these runs). ① spec closure: none (no workspace deps); pnpm --filter @objectstack/spec build exit 0. ② pnpm --filter @objectstack/spec test → 575 files, 16966 passed + 1 todo, VERDICT command-exit 0. The two edited test files: 40 passed at HEAD vs 34 test definitions at base; the +6 are 1 preservation test, 4 it.each refusal rows and 1 contract test. pnpm --filter @objectstack/spec typecheck → exit 0; check:test-typecheck OK, 53 file(s) / 251 error(s) / 138 pinned signature(s) held, ledger unchanged. check:generated: first run found 2 stale (check:docs, check:strictness-ledger); regenerated with gen:docs + gen:strictness-ledger (+4 rows in content/docs/references/api/analytics.mdx, api/ sites 431 to 432); re-run: All 15 generated artifacts are up to date. authorable-surface, api-surface, export-origins and declaration-map did not move: no new export, and data is one top-level key. Tests that enumerate either shape's members: only the compile-time AnalyticsResultMatchesContract (api/analytics.test.ts:48). No keyof/satisfies AnalyticsResult anywhere in packages/, and no other test parses through AnalyticsResultResponseSchema. Lint, declared narrowing: eslint --no-inline-config --format json on the 7 changed paths → 4 linted .ts files, 0 errors / 0 warnings; the 3 .md/.mdx files are outside the population by eslint's own verdict (no matching configuration). Invariance: eslint.config.mjs sets no parserOptions.project or projectService anywhere and says it never enables type-aware linting, so this diff cannot move another file's verdict. Repo-wide pnpm lint is left to CI. ③/④ dispatch-gates --commands (repo objectstack-ai/objectstack at 852b4cf, merge base 5757463): 108 derived. 105 run to exit 0. check:doc-formula-expressions, check:doc-security-posture, check:docs-transcript-drift and check:lean-entry-closure first refused with exit 3 (unbuilt formula/lint/objectql); after turbo run build of the service-analytics closure (15 tasks) they ran green. NOT MEASURED: check:skill-examples (client-react dist absent, 35-package closure), check:dual-build-cjs-loads and check:type-check-debt (both need every package built), all three left to CI. dispatch-gates --ran: 108 derived families accounted for, 105 run, 3 NOT-MEASURED. The families outside the derived total (8 whole-tree, 11 too wide to place, 6 workflow-valued) belong to CI. check:adr-0087-registration --base origin/main → this PR adds no declared-breaking changeset (1 non-breaking changeset seen); it asked for no marker. Consumer: pnpm --filter @objectstack/service-analytics typecheck (tsc against the rebuilt spec dist, which carries drillRawTotals) exit 0; its query-dataset, dataset-granularity-postprocess and dataset-order-labels tests: 56 passed. client, rest and driver-memory typecheck NOT MEASURED: none names any of the four keys (git grep), CI TypeScript Type Check covers them. Ablations, each from committed HEAD through scripts/ablation-replace.mjs (anchor hit counted, blob changed, restore proven blob == HEAD with an empty git diff HEAD). The tests import src relatively, so no dist leg. (a) Schema side, one run per key, renaming that key's schema declaration: every run went 2 failed / 30 passed, the preservation test plus that key's own refusal row; restored to blob f96531cb30fd. (b) Compile-time equality, schema side (drillRanges renamed): tsc analytics.test.ts(48,54) TS2344 on AnalyticsResultMatchesContract plus (315,22) TS2339; check:test-typecheck red. (c) Contract side, all four members widened to unknown (on disk: 4 widened, 0 originals): check:test-typecheck red with TS2578 x4 (each type pin's @ts-expect-error now unused), TS7053 x3 + TS2339 x1 (the four typed reads) and the equality pin in api/analytics.test.ts; restored to blob 0e0d4c9ff9af.",
"mcp_calls": "0",
"api_writes": "2 — relay strokes (fleet-write/dispatch.mjs, POST /repos/objectstack-ai/objectstack/dispatches, each executed by fleet-write.yml as objectstack-fleet[bot]): (1) pr_create → POST /repos/objectstack-ai/objectstack/pulls, draft #20720, run 36632056015; (2) this report → POST /repos//issues/20700/comments via post-stamped.mjs. Plus 3 git push of the branch (not REST). Zero label, assignee, ready or auto-merge writes, as the dispatch ordered.",
"open_questions": [],
"out_of_scope_findings": [
"carrier: the service follow-up that retires AnalyticsResultWithDrill (triage 5897666120, Afterwards; the seat files it when this card lands) · noted, not filed. Two of that local type's doc comments disagree with what the code emits (drillRanges bounds and omission rule; dimensionFields values can be relationship paths). The TS types agree, and deleting the augmentation deletes both comments. Stale comments, not a/b/c."
]
}