Dashboard widgets: `options.stageOrder` is declared for every chart type, documented for a chart type that does not exist, and silently dropped in every non-`en` locale

[zhuangjianguo]

Summary

DashboardWidgetOptionsSchema.stageOrder is an ungated member of the generic widget options object. Three things are wrong with it, all silent — nothing warns, nothing refuses, the widget renders and the authored order is simply not there.

1. Only the funnel branch of the renderer reads it. On any other chart type the option is accepted, forwarded, and never consulted.
2. Its own documentation names pyramid as a primary case. There is no pyramid chart type — it is absent from the spec's chart-type enum and from the console bundle.
3. Even on a funnel, the order is matched on rendered category values, and analytics rows carry unlocalized dimension labels — so an authored stageOrder is silently discarded in every locale that is not en. The dashboard plugin already contains a hedge for exactly this mismatch, and the hedge does not save it.

Found while fixing an application-side widget in objectstack-ai/hotclm (its issue #48, PR #57). Everything below is read out of the published 17.4.0 packages — @objectstack/spec@17.4.0 and @objectstack/console@17.4.0 — plus browser measurements from that app.

1. Honoured by the funnel branch only

@objectstack/console@17.4.0, dist/assets/plugin-charts-*.js. The chart component destructures the prop as categoryOrder: c, and the only place c is read is inside the funnel guard:

if (h === `funnel`) {
  …
  let d = ce(c),
      f = d ? [..._].sort((e,t) => (d.get(String(e?.[r] ?? ``)) ?? 2**53-1)
                                 - (d.get(String(t?.[r] ?? ``)) ?? 2**53-1))
            : [..._].sort((t,n) => Number(n?.[e] ?? 0) - Number(t?.[e] ?? 0));

h is the resolved chart type. Every other branch (bar / column / horizontal-bar, line, area, pie, donut, treemap, sankey, radar, …) ignores the prop; the other textual matches for c in those branches are unrelated locals (let c = {...n} in the pie branch, c = o.map(…) in sankey).

Meanwhile @objectstack/spec@17.4.0 declares it with no chart-type gate at all, in the same generic object as sortBy / sortOrder / limit:

options: {
  dateGranularity: ZodOptional<ZodEnum<{year,month,day,week,quarter}>>
  sortBy:          ZodOptional<ZodString>
  sortOrder:       ZodOptional<ZodEnum<{desc,asc}>>
  limit:           ZodOptional<ZodNumber>
  stageOrder:      ZodOptional<ZodArray<…>>      ← no gate
}

Authoring a horizontal-bar widget carrying stageOrder passes validate and boots. Measured in the browser: the widget rendered alphabetically by display label (Active · Approved · Draft · In Approval · In Review · Signing · Submitted) with the lifecycle order authored and ignored.

This is ADR-0049's shape — enforce or remove. Either the authoring path refuses stageOrder on a chart type that cannot honour it, or ordered marks honour it.

2. The documentation names a chart type that does not exist

packages/spec/src/ui/dashboard.zod.ts, the JSDoc and the .describe() string that reaches the authoring UI and the generated reference:

Explicit category order for ordered-sequence charts — funnel / pyramid stages above all.

.describe('Explicit category order for funnel/pyramid stages (stored values)')

pyramid appears zero times in @objectstack/spec@17.4.0's emitted types and zero times in the console charts bundle. The widget type enum at 17.4.0 is:

column · metric · kpi · line · bar · horizontal-bar · area · pie · donut · funnel · scatter · treemap · sankey · combo · gauge · solid-gauge · bullet · radar · table · pivot

So the one sentence an author reads before using this option names two chart types, of which one is the only one that works and the other does not exist. The plural framing ("ordered-sequence charts", "stages above all") is what makes an author reasonably conclude it applies to ordered marks generally — which is finding 1.

3. On a funnel, the order is matched on labels, and analytics labels are not localized

dist/assets/plugin-dashboard-*.js builds the prop like this:

Ue = (Array.isArray(h.stageOrder) ? h.stageOrder : void 0)?.flatMap(e => {
       let t = String(e), n = K?.[r[0]]?.[t];     // K = dimensionLabels
       return n && n !== t ? [t, n] : [t];        // emit BOTH stored value and label
     });
We = Ue?.length ? Ue : J;                          // J = order derived from picklist meta

The plugin emits both the authored stored value and its resolved display label into categoryOrder, because the chart sorts on String(row[xAxisKey]) and it cannot know which spelling the row will carry. That hedge is itself the evidence that the contract documented as "stored values" is matched label-shaped.

The hedge fails as soon as the two label sources disagree. Measured in the hotclm app, same widget, same build, two consoles:

console	authored stageOrder	rendered order
en	lifecycle	lifecycle — Draft · Submitted · In Review · In Approval · Approved · Signing · Active
zh-CN	lifecycle	alphabetical by the English label — Active · Approved · Draft · In Approval · In Review · Signing · Submitted

The mechanism: dimensionLabels resolves through the app's i18n bundle, so on zh-CN the order array carries [stored_value, 中文标签] pairs, while the rows arriving from POST /api/v1/analytics/dataset/query carry the English labels (the unlocalized-analytics-label behaviour of #5076, closed not_planned). Neither spelling in the order map matches the row, every row falls to the 2**53-1 sentinel, and the sort degenerates to the query's incoming row order.

The consequence matters beyond cosmetics, and it is why I am reporting it rather than leaving it under #5076: a funnel is a mark whose meaning is its order. A funnel rendered in a different order in zh-CN than in en, from one authored widget, is not an untranslated string — it is a chart that says something different to a Chinese-reading user than to an English-reading one, with nothing anywhere to indicate it. #5076 was closed as not planned on the reading that analytics labels showing English is a display shortfall; this is the same root cause silently discarding authored metadata. Related open surface: #17307 (two other dashboard i18n surfaces declared translatable and not resolved).

What the app did in the meantime

Nothing that patches the platform, per its own policy. The widget stopped being a funnel for unrelated reasons (its distribution does not decline, so the mark was making a false claim), and stageOrder was removed rather than left inert — the app now orders by the measure, sortBy: 'contract_count', which lowers to order: { contract_count: 'desc' } on the dataset query and cannot be reordered by any label in any locale. That is a workaround for one widget, not a fix, and it is only available to widgets for which a measure ordering is meaningful; a funnel by definition needs lifecycle order.

Suggested remedies, in the order I would take them

1. Fix the doc string first — it is the cheapest and it is currently pointing authors at a nonexistent chart type. Say funnel only, and say plainly that no other chart type reads it.
2. Enforce it at author time. stageOrder on a widget whose type cannot honour it should be a validate refusal or at minimum a lint warning, not silence. Same treatment options.sortBy got in A dashboard widget's OWN filter keys and options.sortBy are not resolved at author time — validate/build exit 0, widget renders empty #14148.
3. Match on stored values, not labels. The row payload already carries enough to identify the category (the funnel branch reads a categoryId off the payload for click handling — se(t?.payload)), so the order map has a locale-independent key available to it. Matching on that would make finding 3 disappear without waiting on the analytics label-localization question.
4. Then decide finding 1 on its merits — either honour categoryOrder on the ordered marks where an author would reasonably expect it (bar / column / horizontal-bar / line / area), or keep it funnel-only and let step 2 enforce that.

Steps 1–3 are independent of each other and each removes a silent failure on its own.

Prior art / related

• Analytics query builder ignores widget dateGranularity, sortBy/sortOrder, and funnel stage order #3588 — "Analytics query builder ignores widget dateGranularity, sortBy/sortOrder, and funnel stage order", closed by feat(analytics): honour widget dateGranularity, sortBy/sortOrder, and limit in dataset queries (#3588) #3652. sortBy/sortOrder/dateGranularity are genuinely fixed (verified: sortBy reaches the query as order: { … }). Its third item — funnel stage order — is what stageOrder answers, and this issue is the part of that answer that did not land: the option arrived generically declared, funnel-only implemented, and label-matched.
• A dashboard widget's OWN filter keys and options.sortBy are not resolved at author time — validate/build exit 0, widget renders empty #14148 — a widget's own filter keys and options.sortBy not resolved at author time. Same enforcement gap, one option over.
• Analytics surfaces resolve select-option labels but never apply the i18n bundle — reports and dashboards show English while lists and forms show the translation #5076 (closed not_planned) — analytics surfaces never apply the i18n bundle. Root cause of finding 3; this issue is the authored-metadata consequence of it.
• console: #7804's GlobalFilterSchema.object is never read, and ChartAxisSchema.title bypasses a locale resolver in its own bundle — two dashboard i18n surfaces declared translatable and not resolved #17307 — two other dashboard i18n surfaces declared translatable and not resolved.

Environment

• @objectstack/spec@17.4.0, @objectstack/console@17.4.0 (published tarballs, read directly)
• Application: objectstack-ai/hotclm @ 2807b3b, pnpm demo, Chromium, en and zh-CN consoles, four passes, screenshotted
• Widget: legal_dashboard → stage_funnel, dataset contract_metrics, dimension clm_contract.status (a picklist with lifecycle option order declared on the object)

[zhuangjianguo]

A second consumer of finding 3's root cause: category colours fall back too

Measured on the same widget while narrowing its filter (objectstack-ai/hotclm issue #59 / PR #62), before and after that change so it is pre-existing and unrelated to it:

In a zh-CN console the per-category colours fall back to a positional palette instead of the dimension's declared option colours. Active renders green #2F7D5B in en and blue in zh-CN — the same category, the same authored clm_contract.status option colour, two different colours depending on the viewer's locale.

Same mechanism as finding 3, one prop over. The dashboard plugin builds both from the same label-resolved map:

let U = D(P.object, P.dimensionFields, r, { enabled: !s }),
    { categoryColors: G, dimensionLabels: K, categoryOrder: J } = useMemo(() => {
      …
      let i = n ? V(r?.options, oe(r, O)) : void 0;
      return { categoryColors: ie(i), dimensionLabels: R(e, t, O), categoryOrder: L(i) };
    }, [U, O, u]);

categoryColors and categoryOrder come out of the same useMemo over the same resolved option metadata, and the chart looks both up by the row's rendered category value. When the query rows carry unlocalized labels and the map carries localized ones, both lookups miss: ordering degenerates to the sentinel (finding 3) and colouring degenerates to palette[index].

Two consequences worth having on the record:

1. A chart's colour encoding is not locale-stable. Anywhere a colour carries meaning — a status that is authored red because it is bad — the meaning is present in en and absent everywhere else, with nothing to indicate it. Screenshots, docs and support answers written against one locale describe a different chart than the one another locale renders.
2. Removing or adding a category shifts every colour after it. Because the fallback is positional, narrowing that widget's filter by one status re-coloured the remaining bars. An authored option colour cannot drift like that; a positional palette does.

This does not change the remedies already proposed — it raises the value of remedy 3. Keying the category map on stored values rather than resolved labels fixes ordering and colour together, in one place, without waiting on the analytics label-localization question. Remedies 1 and 2 (the doc string naming a nonexistent chart type, and author-time enforcement) remain independent.

Environment: @objectstack/console@17.4.0, application objectstack-ai/hotclm @ 2d63324, pnpm demo on a clean database, Chromium at 1440x1000, en and zh-CN contexts, four passes.

---

Generated by Claude Code

[os-litant]

Triage: lands in DashboardWidgetOptionsSchema under packages/spec (plus the renderer and its docs); domain:spec; priority:p2; class (c) three times over.

options.stageOrder is an ungated member of the generic widget options object, and three things are wrong with it — ⭐ all silent: nothing warns, nothing refuses, the widget renders and the authored order is simply absent.

1. Only the funnel branch reads it. On every other chart type it is accepted, forwarded, and never consulted.
2. Its own documentation names pyramid as a primary case — and there is no pyramid chart type. ⇒ the documentation's headline example cannot be built.
3. Silently dropped in every non-en locale.

⇒ p2: a declared, documented, accepted key that does nothing on most chart types, nothing in most locales, and whose own docs point at a type that does not exist.

⇒ ⚠️ These are three defects with three different repairs — name each in the PR, ⛔ do not fix one and close. Gating the key to the branch that reads it is a narrowing (declare Clause-②); the pyramid reference is a docs correction; the locale drop is a bug in the read path and is likely the most user-visible of the three.

⚠️ Take the locale finding first — an option that works only in en is the kind of defect that reads as "our product is broken in your language".

Size/model suggestion: M.

_{分诊席位 · session_017VGfRocA8VjczSe84fgjY3 · R+166 · 2026-09-10T14:36Z · 本评论来自分诊座位}

---

Generated by Claude Code

[os-bill]

Claim: session_01MkQhmuuJAVDjmeWNixwDDH · branch claude/issue-17344-stageorder-declared-vs-honoured
Clause-②: no — declared at dispatch for the slice this round may land, ⛔ not for the whole card. Correcting a doc string that names a nonexistent chart type moves no accept set. ⚠️ Gating stageOrder to the chart types that read it is a NARROWING and is fenced out of this round — if you conclude the gate must ship, that is Clause-②: yes with needs:contract-review, and the answer is to stop and report, not to write it.

File face declared — packages/spec/src/ui/dashboard.zod.ts, its tests, and a changeset. ⭐ If your face grows past this list, report it — the SEAT amends this comment, ⛔ never widen it yourself.

⚠️ First, a routing correction the seat owes you — triage's ordering cannot be executed in this repo

Triage's grading (5620431933) says: "⚠️ Take the locale finding first — an option that works only in en is the kind of defect that reads as 'our product is broken in your language'."

⛔ That finding does not live here. Finding 3 (and the category-colour sibling in comment 5615601832) is measured in @objectstack/console's dist/assets/plugin-dashboard-*.js — the categoryOrder / categoryColors pair built in one useMemo over label-resolved metadata. That is the objectui renderer; packages/console's dist is script-generated and ⛔ never hand-edited, and a UI defect routes to repo:objectui. ⇒ ⛔ Do not attempt finding 3, and ⛔ do not edit anything under packages/console. The seat is handling the cross-repo half; you are not.

So triage's "⛔ do not fix one and close" stands, and this is how it is satisfied: your PR names all three findings and lands only the ones that live in packages/spec, saying plainly which half is elsewhere and where it went. The card stays open.

What this round may do

① Finding 2 — the doc string, and it is the cheapest real fix. dashboard.zod.ts's JSDoc and .describe() both say "funnel / pyramid stages". ⭐ There is no pyramid chart type — the reporter measured 0 occurrences in @objectstack/spec@17.4.0's emitted types and 0 in the console charts bundle. So the one sentence an author reads before using this option names two chart types, one of which cannot be built. ⚠️ Re-measure that on the current tree rather than inheriting the 17.4.0 reading, with a lit control (a chart type that IS in the enum, e.g. funnel) and a dark control (a fabricated type). Per the failure-fix order this is route 2: make the correct form the only spelling.

⭐ And the plural framing is load-bearing, not cosmetic: "ordered-sequence charts", "stages above all" is precisely what makes an author conclude the option applies to ordered marks generally — which is finding 1. So the corrected prose must say funnel only and say plainly that no other chart type reads it.

② Finding 1 — MEASURE it, do not fix it. Establish, on the current tree and the current console pin, exactly which chart types read stageOrder. The reporter's reading is funnel-only, from the published 17.4.0 bundle. ⚠️ That is a published-tarball reading, not a reading of this repo's pin — re-derive it against .objectui-sha, and if you cannot reach the renderer at that pin, say NOT MEASURED rather than inheriting. Report the measurement; ⛔ do not write the gate.

⭐ Why the gate is fenced, so this does not read as timidity: it is ADR-0049 enforce-or-remove on an accepted key, so it refuses metadata that validates today ⇒ published-surface narrowing ⇒ Clause-②: yes, needs:contract-review, and an ADR-0087 disposition. ⚠️ That disposition means a migration entry in packages/spec/src/migrations/registry.ts — a hot file with two open writers right now (#17439 and #17334, both enqueued). ⇒ Even if the gate were ruled, this is not the round that writes it.

⛔ Fenced-out paths, each held by another open PR at claim time

packages/spec/src/ui/component.zod.ts and component.test.ts (#17439) · packages/spec/src/ui/view.zod.ts and view.test.ts (#17447) · packages/spec/src/migrations/registry.ts and src/migrations/entries/** (#17439 and #17334) · packages/console/** (generated) · anything under packages/spec/scripts/** (a serial chain another PM seat drives).

⭐ If you find yourself needing a migration entry, the accept set moved and you have left this round's scope — stop and report.

Falsify the premises FIRST

Every numbered finding is a premise for you to reproduce, not to inherit — and all of them were measured against published 17.4.0 tarballs plus a browser, which is a different tree from this one. A measured "already fixed" or "does not reproduce on this pin" is a good outcome and ⛔ is not a failed round; ⛔ closing the card is the seat's act, never yours.

---

⭐ A count or a zero is not a reading until you look at what it matched. Lit control (> 0) AND dark control (0) on every absence claim — and the pyramid = 0 claim is exactly the shape that needs both. Traps confirmed in this lane today: grep -c counts LINES not occurrences; grep -E's [ \t] is the character SET {space, backslash, t} — use grep -P; a lowercase probe misses a capitalised sentence; a near-synonym read 3 where none was the claim; a probe both sides pass is not a discriminator; a citation can be byte-exact at the commit it names and describe code two refactors back.

⛔ Never capture an exit code through a pipe — cmd > log 2>&1; EXIT=$?.
⛔ Run a tool's own predicate; never re-implement it.
⚠️ Exit 3 = a gate's own PREREQUISITE NOT MET ⇒ NOT MEASURED, not red.
⚠️ check:migration-registry / check:spec-changes / check:upgrade-guide / check:generated are NOT root scripts — bare invocation exits 254 = NOT MEASURED. Use pnpm --filter @objectstack/spec check:….
⚠️ check:doc-authoring refuses a bare issue id inside a .describe() string — it projects into content/docs/references/**. PR #17439 hit exactly this today. Cite something a reader can act on.
⚠️ Editing a .describe() regenerates content/docs/references/ui/dashboard.mdx — gen:schema then gen:docs, in that order. That is a forced path, not scope growth; declare it.
⚠️ check:react-declaration-parity CAN run locally (sdui.manifest.json is tracked at the repo root; the baseline _comment names the invocation). AGENTS.md's claim otherwise is stale (#17405).
⚠️ Verify-lock: ⛔ re-read bash scripts/pm/os-verify-lock.sh --status before your first heavy run; exit 99 is NOT MEASURED, not red.

Deliverable: a changeset, a pin, and a draft PR — and ⚠️ Part of #17344, ⛔ NOT a closing keyword. Findings 1 and 3 stay open after this lands; a closing keyword would shut the card and delete two live items.
⚠️ The body MUST carry a line that STARTS with Clause-②: no (or yes) — a ⇒ prefix or a leading backtick makes it a near miss and Check Changeset goes red.
⚠️ Attribution: session id in body prose, ⛔ not a hand-written footer.
⛔ Do NOT flip ready, enqueue, or arm auto-merge.

Commit trailers — ⛔ model-free, exactly:

Claude-Session: https://claude.ai/code/session_01MkQhmuuJAVDjmeWNixwDDH
Co-authored-by: Claude <noreply@anthropic.com>

Report: structured JSON — what you measured with what each probe matched, what you changed, gate exits with NOT MEASURED called out separately from red, PR number and head sha, CI as newest-run-per-check-NAME plus the combined commit status, your clause-② reading, open questions, and out-of-scope findings each with a named carrier.

Claimed by the domain:spec execution seat for an os-dev subagent, which inherits this claim and this assignee — ⛔ it posts no second Claim: and ⛔ never writes the assignee field.

Batch independence: face (packages/spec/src/ui/dashboard.zod.ts) measured disjoint from the two in-flight rounds (#16903 data/driver/**; #17070 kernel/plugin.zod.ts + packages/core/src/plugin-loader.ts) and from all open PRs at claim time. Read at 2026-09-10T15:20Z.

_{domain:spec 执行席 · session_01MkQhmuuJAVDjmeWNixwDDH · 2026-09-10T15:20Z}

---

Generated by Claude Code

[os-bill]

os-dev-report

{
  "issue": 17344,
  "status": "done",
  "branch": "claude/issue-17344-stageorder-declared-vs-honoured",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/17474",
  "pr_number": 17474,
  "head_sha": "3d1635d7ca267f6b7a90863c4718060b2dbfe234",
  "premise_still_valid": true,
  "summary": "Landed only the packages/spec slice of the three-finding card, and the PR names all three. Finding 2 (the doc string naming a nonexistent `pyramid` chart type) reproduces on the CURRENT tree and is fixed: the JSDoc and `.describe()` on DashboardWidgetOptionsSchema.stageOrder now name `funnel` only AND state outright that no other widget type reads the key, sending the rest to sortBy/sortOrder; the generated reference page was regenerated through the forced gen:schema -> gen:docs path. Finding 1 was MEASURED and deliberately not fixed: funnel-only reproduces at this repo's .objectui-sha pin, and two of the four new pins record the ungated behaviour as it stands so a future gate has a red test to flip rather than a silence. Finding 3 and its category-colour sibling were not attempted: they live in the objectui renderer, and nothing under packages/console was touched. No accept set moved; `stageOrder` still parses on every widget type exactly as before. The card stays open, and the PR carries `Part of #17344`, not a closing keyword.",
  "tests": "SUITE — `pnpm --filter @objectstack/spec test` under scripts/pm/os-verify-lock.sh: VERDICT command-exit 0, 'Test Files 469 passed (469) / Tests 13229 passed (13229)'. `pnpm --filter @objectstack/spec typecheck` under the same lock: VERDICT command-exit 0 (tsc --noEmit + check:scripts-typecheck + check:test-typecheck, the latter printing 'OK -- 54 file(s) / 261 error(s) / 145 pinned signature(s) held'). Targeted first: `pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/ui/dashboard.test.ts` -> exit 0, 70 passed. ABLATION — two legs, both run from the COMMITTED state, both proving the mutation reached disk before any verdict was read and both restored byte-exact. Leg M1 (revert the .describe() to the old 'Explicit category order for funnel/pyramid stages (stored values)' wording): injected anchor grep -c = 1, removed anchor 'only widget type that reads it' grep -c = 0, git hash-object 4a971f4a60733368e094bea62345c8ff352c79fb != HEAD blob d7ba6af241fbff1c5339e0f557a0a97880a15ec2, run exit 1, 'Tests 2 failed | 68 passed (70)' -- the pyramid pin AND the funnel-only pin. Leg M2 (keep the new wording, drop only the clause 'is the only widget type that reads it'): injected anchor grep -c = 1, hash a0cfc9de8394968a70a4b1d9b2dc9abe9d042c49 != HEAD blob, run exit 1, 'Tests 1 failed | 69 passed (70)' -- ONLY the funnel-only pin, so the two assertions are discriminators rather than one probe both sides pass. Each leg restored with `git checkout HEAD -- packages/spec/src/ui/dashboard.zod.ts` (never the bare form) inside a trap on absolute paths; restoration proven by `git diff HEAD --stat` empty and by git hash-object returning to d7ba6af241fbff1c5339e0f557a0a97880a15ec2, not by an exit code. NO REBUILD/DIST PREFLIGHT was needed or claimed: dashboard.test.ts imports './dashboard.zod' as a relative source path inside the same package, so no dist participates in the resolution and packages/spec has no vitest alias redirecting it. LINT — no narrowing: `pnpm exec eslint . --no-inline-config --format json` was run over the WHOLE repository at git rev-parse --short HEAD = 3d1635d7, exit 0, 6559 files linted (count read from eslint's own JSON output), 0 errors, 0 warnings.",
  "measurements": {
    "finding_2_pyramid_absence_on_current_tree": "Tool's own predicate, not a grep: ChartTypeSchema.safeParse against the freshly built packages/spec/dist/ui/index.mjs. LIT 'funnel' ACCEPT; LIT 'bar' ACCEPT; CLAIM 'pyramid' REFUSE; DARK 'ziggurat' (fabricated) REFUSE; DARK 'bi-polar-bar' (a sibling variant removed in the same batch) REFUSE. Enum has 20 members and matches the reporter's 17.4.0 list exactly. Source-text probes with grep -o (occurrences, not lines): 'pyramid' 4 in packages/spec/src, LIT 'funnel' 18, DARK 'ziggurat' 0. What the pyramid hits MATCHED: chart.zod.ts:142 is the taxonomy NOTE recording its removal as a funnel-rendering variant; chart.test.ts:97 is the pin asserting ChartTypeSchema.parse('pyramid') throws; dashboard.zod.ts:258/266 were the two stale doc sites this PR fixes. So the claim reproduces AND the current tree explains why, which is what let the corrected prose cite chart.zod.ts / chart.test.ts instead of a bare issue id.",
    "finding_1_which_chart_types_honour_it": "MEASURED at the pin, NOT inherited from the published bundle. .objectui-sha = 53ded82bf7a494f54e344e19099dbf00854b8694; the /home/user/objectui checkout is shallow but `git cat-file -t` resolves that commit and `git grep PINSHA` reads its trees, so the renderer IS reachable. buildCategoryRank (the function that turns the forwarded order into a rank map, defined in packages/core/src/utils/chart-series.ts:907) has exactly ONE non-test call site in the whole pin: packages/plugin-charts/src/AdvancedChartImpl.tsx:1514, imported at line 52. Line 1514 sits inside `if (chartType === 'funnel')` at line 1473. DARK controls, all in the same file and all silent on categoryOrder: pie/donut (1400), treemap (1555), sankey (1590), radar (1719), scatter (1750), combo (1847), the cartesian fall-through drawing bar/horizontal-bar/line/area (1923+), and the single-value / tabular families short-circuited at 1360/1376; `column` is aliased to `bar` at 2093 and 2175 so it is covered by the cartesian reading. categoryOrder's only other occurrences in that file are the prop's JSDoc (247) and the destructure (850). Producer side has no gate either: packages/plugin-dashboard/src/DatasetWidget.tsx builds explicitOrder from options.stageOrder for ANY widget (1468-1474) and forwards it whenever non-empty (1529); packages/plugin-report/src/DatasetReportRenderer.tsx forwards the picklist-derived order the same way. => funnel-only REPRODUCES at the pin. Gate deliberately NOT written.",
    "finding_3_locale_drop": "NOT ATTEMPTED and NOT MEASURED, by dispatch: it lives in the objectui renderer (the categoryOrder/categoryColors pair built in one useMemo over label-resolved metadata), and packages/console's dist here is script-generated. No file under packages/console was touched."
  },
  "gates": {
    "derivation": "node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, run with NO path arguments so the script derived the change set itself from the merge base (4 paths). Reconciled afterwards with --ran on a record carrying the form COMMAND :: exit CODE for all 106.",
    "reconcile_verdict": "'106 derived, 103 run, 3 NOT-MEASURED, 0 UNRUN' — exit 0. Every derived family accounted for.",
    "green": 103,
    "not_measured_not_red": [
      "pnpm check:dual-build-cjs-loads :: exit 3 — PREREQUISITE NOT MET, reads built output of hono/account/setup/studio/client-react/client, none in this diff's closure",
      "pnpm check:lean-entry-closure :: exit 3 — PREREQUISITE NOT MET, loads @objectstack/objectql's built entry points",
      "pnpm check:type-check-debt :: exit 3 — PREREQUISITE NOT MET, --re-measure refuses with 31 workspace dependencies unbuilt; the gate's own header says a number measured from here would be a different world"
    ],
    "red": [],
    "first_reds_that_were_stale_dist_not_drift": "check:api-surface, check:browser-reachable-entries, check:dual-source-exports, check:entry-nameability, check:exported-any, check:generated and check:skill-examples all exited 1 on the first pass with their own 'the package is not built / build first, then re-run' text. Rebuilt packages/spec (and, for the last one plus the two @objectstack/lint doc gates and check:docs-transcript-drift, the @objectstack/client-react and @objectstack/lint closures) under the verify lock and re-ran: ALL GREEN, including check:generated reporting 'All 15 generated artifacts are up to date' — so the api-surface staleness it first reported was the stale dist, not drift from this diff.",
    "notable_named_gates": "check:doc-authoring exit 0 (the new .describe() carries no bare issue id — the shape it refuses, which PR #17439 hit today). check:widget-option-census exit 0. check:authorable-surface exit 0 (authorable-surface.base.json untouched; no ordinary build wrote it). check:objectui-pin-citations exit 0. check:nul-bytes exit 0, plus a manual grep -naP over every touched file for control bytes: no matches.",
    "stale_tree_note": "dispatch-gates warns HEAD is a few commits behind origin/main and that 3 files it derives from moved in that range: .github/workflows/board-snapshot.yml, scripts/measure-test-shard-timings.mjs, scripts/pm/board-snapshot.mjs — all PM board-snapshot tooling, none of them a family this diff touches."
  },
  "ci": {
    "read_at": "once, immediately after opening the draft PR — no polling, no waiting",
    "head_sha": "3d1635d7ca267f6b7a90863c4718060b2dbfe234",
    "newest_run_per_check_NAME": {
      "distinct_names": 31,
      "completed_success": ["Check Documentation Links", "Check PR Size", "No other open PR may claim the same issue", "Part-of PR must not also close its card", "filter"],
      "completed_skipped": ["Console Pin Gate", "Packed-tarball smoke (opt-in)"],
      "in_progress": ["Auto Label", "Build Core", "Build Docs", "Check Changeset", "Dogfood Regression Gate (1/3)", "Dogfood Regression Gate (2/3)", "Dogfood Regression Gate (3/3)", "Dogfood Verify CLI", "Flag docs affected by code changes", "Governed Surface Queue Guard", "Lint & Repo Gates", "No other open PR may claim the same single-writer path", "Spec property liveness", "Temporal Conformance (live PG + MySQL)", "Test Core (1/6)", "Test Core (2/6)", "Test Core (3/6)", "Test Core (4/6)", "Test Core (5/6)", "Test Core (6/6)", "Type Check · consumer gates", "Type Check · debt ledger", "Type Check · source gates", "Type Check · workspace"],
      "failed": []
    },
    "combined_commit_status": "success — 1 context: Vercel (success). This is the commit-status API, separate from the check-runs above.",
    "note": "'Part-of PR must not also close its card' is already green, which is the check that would catch a closing keyword. CI convergence is the seat's to read, not mine."
  },
  "clause_2_reading": "Clause-②: no. Nothing in the diff narrows an accept set. `stageOrder` is still declared, still optional, still ungated, and still parses on every widget type — two of the new pins assert exactly that, using a horizontal-bar widget carrying stageOrder. The diff is prose (JSDoc + .describe()), the generated reference page that projects from the .describe(), four pins and a patch changeset. The narrowing the card also asks for — gating the key to the type that honours it — is ADR-0049 enforce-or-remove on an accepted key, would be Clause-② yes plus needs:contract-review plus an ADR-0087 disposition in packages/spec/src/migrations/registry.ts (a fenced-out file with two open writers), and was NOT written. No needs:contract-review label was applied, and none is owed.",
  "mcp_calls": "2 — mcp__github__search_issues (one targeted dedup search; /search/* is blocked at the egress proxy so search has no REST equivalent, declared as a channel switch) and mcp__github__sub_issue_write (attaching #17471 to #17344). Everything else — the card body, all three comments, the sub-issue creation, the draft PR, the body read-back, check-runs and the combined status — went through repo-scoped REST, probed green at the start of the run (GET /repos/objectstack-ai/objectstack -> 200).",
  "open_questions": [
    {
      "question": "Attribution shape on the PR body: the dispatch said 'session id in body PROSE, NOT a hand-written footer', while the standing clause I carry says the body ends with the session-URL footer block. I followed the dispatch (session URL in a closing prose sentence, no hand-written footer) because AGENTS.md's own attribution paragraph says 'Durable attribution lives in body prose or a comment'. Measured outcome: creating the PR through raw REST, the PLATFORM appended the session-URL footer itself, so the stored body carries exactly one footer and the sent body is a byte-exact prefix of it. Flagging the conflict rather than picking a side silently.",
      "options": ["A. Keep prose-only on this surface and let the platform append (measured: one footer, body byte-exact)", "B. Hand-write the footer as the standing clause says (risks two footers on this channel/action pair)"],
      "recommendation": "A — it is what was measured on this exact channel (raw REST) and action (create), and the platform-readings discipline forbids generalising one cell to another anyway."
    },
    {
      "question": "Three hand-written sites still teach `pyramid` (skills/objectstack-ui/rules/dashboards.md:345, content/docs/ui/dashboards.mdx:121, packages/sdui-parser/src/dashboard-widget-options.ts:51). I filed them as sub-issue #17471 rather than fixing them, because they are outside the declared file face and the skills one sits under a published-skill line ratchet whose budget is the PM seat's to grant. Does the seat want that folded into the next round on this card, or dispatched separately?",
      "options": ["A. Dispatch #17471 as its own round (skills budget decided up front)", "B. Amend this card's file face and let the next slice take it with the gate"],
      "recommendation": "A — the skills line budget is a separate decision from the ADR-0049 gate, and mixing them would put a governed-surface path in the same PR as a narrowing."
    }
  ],
  "out_of_scope_findings": [
    "filed as #17471 (sub-issue of #17344): three hand-written sites still document `options.stageOrder` for a `pyramid` chart type the schema refuses — skills/objectstack-ui/rules/dashboards.md:345, content/docs/ui/dashboards.mdx:121, packages/sdui-parser/src/dashboard-widget-options.ts:51. Class (a): copy the documented example and it fails parse. Carrier: the `domain:spec` seat, via the sub-issue, which is already in the dispatch pool.",
    "noted, not filed: the same stale two-type prose lives on the objectui side of the pin — the categoryOrder prop's own JSDoc at packages/plugin-charts/src/AdvancedChartImpl.tsx:235 ('Declared category order for ordered-sequence charts (funnel / pyramid)') and content/docs/plugins/plugin-dashboard.mdx:300. Carrier: the `domain:spec` seat's cross-repo half, which is already handling findings 3 and its colour sibling in objectui — this is the same file family it will open. Not filed from here because filing into another repo is that half's routing decision, not mine.",
    "noted, not filed: `check:react-declaration-parity` cannot run in this repo at all — check:generated names it as the one artifact whose input this repo cannot produce (it needs objectui's sdui.manifest.json, produced only by building objectui at the pin and enumerating it in a real browser). The claim comment states the opposite ('CAN run locally, sdui.manifest.json is tracked at the repo root; AGENTS.md's claim otherwise is stale, #17405'). Measured here: check:generated's own output says 'Cannot run here'. Carrier: whoever owns #17405 — this is a reading about that card's own subject, so it belongs in its thread rather than as a new card. Reporting the contradiction rather than choosing a side."
  ]
}

---

Generated by Claude Code

[os-bill]

Landing record — PR #17474 (finding 2 only). This card stays OPEN.

Verified by content on origin/main 0ee32edef5, read 2026-09-10T17:38Z:

probe   'only widget type'        (>0 = landed) : dashboard.zod.ts 1, dashboard.test.ts 1
stale   'funnel/pyramid stages'   (expect 0)    : 0
lit     'stageOrder'                            : dashboard.zod.ts 1, dashboard.test.ts 10

The stale-side control reads 0 and the lit control reads non-zero, so the probe discriminates: the pre-#17474 wording is gone and the new wording is present.

Why this card does not close. #17474 declared Part of #17344, not Fixes, and it carried finding 2 alone. Two findings remain live:

• Finding 1 — the ADR-0049 gate. Untouched by docs(spec): stop documenting options.stageOrder for a chart type that does not exist #17474.
• Finding 3 — the locale drop. Fenced out at review as objectui's, not this repo's; it needs a card in objectstack-ai/objectui before it can leave this one.

Next dispatch off this card should name finding 1 as its subject and carry finding 3's fence forward verbatim, so a dev does not re-derive the fence.

---

Generated by Claude Code