Analytics widgets report "capability not installed" for a 401/dataset-not-found answer — misdiagnosis sends operators to the wrong fix

[os-zhuang]

Observed live on os-2gv9x5.objectos.ai (prod tenant), HotCRM Executive Overview: every analytics widget shows

Analytics capability is not installed on this deployment — POST /analytics/dataset/query is unavailable. Install @objectstack/service-analytics and mount AnalyticsServicePlugin to enable it. (server said: Dataset "opportunity_metrics" not found.)

The banner's own parenthetical contradicts its headline. Verified against the live environment:

POST /api/v1/analytics/dataset/query → 401 UNAUTHENTICATED (not 404)

The route is mounted and answering; the analytics capability IS installed. The real condition was the named dataset does not exist in this environment — the installed app.objectstack.hotcrm was 1.3.0 while the datasets (opportunity_metrics, account_metrics, contact_metrics, lead_metrics) ship in 2.2.2. The fix for the environment is a package upgrade; the banner sends an operator to install a server plugin instead — the opposite corner of the system.

The defect

The widget's error mapping collapses two distinct server answers into the capability-missing message:

• route absent (ROUTE_NOT_FOUND / 404) → "capability not installed" is correct;
• route present, dataset unknown → should say "Dataset 'X' is not defined in this environment — the installed app may be outdated", ideally naming the app when the dashboard metadata knows it.

The evidence was in the payload the whole time — the code even prints the server's message in parentheses while overriding its meaning in the headline. Same failure shape the cloud-side epic kept finding: a diagnostic that does not observe its own subject.

Where to look

The analytics widget error path in the dashboard plugin (plugin-dashboard / analytics adapter) — wherever the "capability is not installed" copy is chosen. Map by the server's error code/status, not by the endpoint having errored.

[huangyiirene]

Triage first-touch (bare-card sweep): queued pm:queue (bug + domain:ui stand), size S. Prod-observed misdiagnosis with the evidence in its own parenthetical — the fix is the card's own sentence: map by the server's error code/status, never by "the endpoint errored". Route absent (404/ROUTE_NOT_FOUND) keeps the capability-missing copy; route present + dataset unknown gets the dataset-not-defined copy (naming the app when dashboard metadata knows it); and the measured live case — 401 UNAUTHENTICATED — is a third branch, not either of those (an auth problem mislabeled as a missing capability is the same defect again). Pin one fixture per branch. i18n keys per the pack conventions.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 17
Session: session_01EuPCi56cnGyykygi3z9w4m
Branch: claude/issue-5663-analytics-error-branch-mapping
Worktree: objectui-issue-5663
Domain: domain:ui
File surface: packages/data-objectstack/src/** and its tests, plus the @object-ui/i18n locale packs if new keys are added (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus
Clause-②: no
Serial constraints cleared: no in-flight card shares packages/data-objectstack. ⚠️ See the fence note below — one referencing file sits inside the package #5619 holds. #5710/PR #5713 and #5637/PR #5714 merged at 20:42Z / 20:43Z.

Tier basis. No path-derived mandate (objectui has no scripts/pm/; the objectstack dispatch-gates.mjs is the wrong tree and is not used). Content judgement: this re-maps diagnostic copy by server status — no contract accept/reject behaviour moves and no public surface widens. Clause ② does not trip. Size follows triage's S; tier at the default judgement档 because the branch taxonomy and the i18n key conventions both carry judgement.

⚠️ Premise correction measured before dispatch — the card's "Where to look" is wrong. The card says "the analytics widget error path in the dashboard plugin (plugin-dashboard / analytics adapter)". Measured on origin/main 190fbd01d, the copy is not in plugin-dashboard. It is in:

• packages/data-objectstack/src/index.ts:577 — the live mapping site: `Analytics capability is not installed on this deployment — ${surface} is unavailable. `
• packages/data-objectstack/src/queryDataset.test.ts — its existing tests
• packages/app-shell/src/views/metadata-admin/previews/DatasetPreview.test.tsx:103 — constructs the string as a fixture

Re-measure rather than trusting this list, but do not start from the card's pointer.

⛔ Fence note, and it is load-bearing this round. packages/app-shell/src/views/** is held by in-flight sibling #5619. DatasetPreview.test.tsx only constructs the capability-missing string as a fixture, so if your change leaves that branch's copy intact the file needs no edit at all — the likely case. If it does need to change, stop and report rather than editing it; the PM will sequence it behind #5619. ⛔ Do not touch anything else under packages/app-shell/**.

Triage's ruling is binding and its third branch is the one the card under-states. Map by the server's error code/status, never by "the endpoint errored": route absent (404 / ROUTE_NOT_FOUND) keeps the capability-missing copy; route present + dataset unknown gets the dataset-not-defined copy, naming the app when dashboard metadata knows it; and the measured live case — 401 UNAUTHENTICATED — is a third branch, not either of those. An auth failure reported as a missing capability is the same defect wearing a different mask. Pin one fixture per branch. i18n keys per the pack conventions.

Worth carrying into the fix: the original banner printed the server's real message in its own parenthetical while contradicting it in the headline. A diagnostic that quotes its subject and then overrides its meaning is worse than one that says nothing — whatever copy you land, the headline and the parenthetical must not be able to disagree.

---

Generated by Claude Code

[os-zhuang]

os-dev-report

Card body read in full and it is not truncated — it ends with the "Where to look" section, as stated in the dispatch. Both comments read: triage's first-touch (2026-08-22T13:25Z, binding) and the PM claim comment (2026-08-22T20:47Z).

Which server signal each branch keys on

Every signature below was established by reading the framework at /home/user/objectstack, not inferred from the client code under repair.

branch	keys on	evidence (framework source)
capability not installed	code === 'NOT_IMPLEMENTED' or code === 'ROUTE_NOT_FOUND'	packages/rest/src/rest-server.ts registerAnalyticsEndpoints: res.status(501).json({ code: 'NOT_IMPLEMENTED', message: 'Analytics dataset query is not available on this deployment (no analytics service with queryDataset).' }). Route-absent: packages/runtime/src/http-dispatcher.ts routeNotFound() and packages/runtime/src/dispatcher-plugin.ts, both emitting DispatcherErrorCode.enum.ROUTE_NOT_FOUND at httpStatus 404, in the wrapped { success: false, error: { code, message } } envelope.
dataset not defined	code === 'NOT_FOUND'	Same route, the body.datasetName lookup miss: return res.status(404).json({ code: 'NOT_FOUND', message: \Dataset "${body.datasetName}" not found.` });` — flat envelope. This is the exact string the reported banner quoted in its parenthetical.
not authenticated	code === 'UNAUTHENTICATED'	rest-server.ts enforceAuth → res.status(ANONYMOUS_DENY_STATUS).json(ANONYMOUS_DENY_BODY), from packages/core/src/security/anonymous-deny.ts: ANONYMOUS_DENY_STATUS = 401, ANONYMOUS_DENY_CODE = 'UNAUTHENTICATED', body { error: 'UNAUTHENTICATED', code: 'UNAUTHENTICATED', message: 'Authentication is required to access this endpoint.' } — flat, with error carrying the code, not the message.
residual (no code at all)	status only, and only after all three above decline	404/501 → capability-missing; 401 → unauthenticated; everything else keeps the generic error. Safe here precisely because the route's own NOT_FOUND always ships a code, so a code-less 404 cannot be the unknown-dataset case.

The collision that caused the incident is 404 ROUTE_NOT_FOUND vs 404 NOT_FOUND — two unrelated conditions, one status, and the old mapping tested only the status.

Premise corrections (both measured, neither invalidates the card's core defect)

1. The card's "Where to look" is false — the PM's correction is confirmed. The copy is not in plugin-dashboard. plugin-dashboard/src/DatasetWidget.tsx:530 does setState({ status: 'error', … error: String((e as Error)?.message ?? e) }) — it prints .message and chooses no copy at all. The banner text is authored entirely in packages/data-objectstack/src/index.ts, in the AnalyticsNotInstalledError constructor, and selected at the !res.ok branch of queryDataset. The PM's three-file list re-measured correct.

2. The card's causal reading of the 401 is false. The card records POST /api/v1/analytics/dataset/query → 401 UNAUTHENTICATED (not 404) and treats it as the response that produced the banner. It cannot have been: under the pre-fix code a 401 falls past res.status === 501 || res.status === 404 into the generic Dataset query failed: 401 Unauthorized string. The banner's own parenthetical quoted Dataset "opportunity_metrics" not found., which is the 404 NOT_FOUND body verbatim. So the browser session's request was answered 404 NOT_FOUND, and the recorded 401 was a separate, unauthenticated probe of the same url. This does not change the fix — triage independently ruled 401 a third branch, and it is implemented and pinned — but the card's "the measured live case is 401" should not be carried forward as the mechanism.

Fence

packages/app-shell/** not touched. DatasetPreview.tsx:89 matches code === 'ANALYTICS_NOT_INSTALLED' and its test constructs that same string as a fixture; the capability-missing branch keeps its code and its copy verbatim, so neither needed editing — the outcome the PM predicted as likely. No sdui-parser, auth, console, components, content/docs or apps/site edits either.

Report

{
 "issue": 5663,
 "status": "done",
 "branch": "claude/issue-5663-analytics-error-branch-mapping",
 "pr": "https://github.com/objectstack-ai/objectui/pull/5723",
 "premise_still_valid": true,
 "premise_corrections": [
 "Card's 'Where to look' (plugin-dashboard / analytics adapter) is measured FALSE; the copy is authored in packages/data-objectstack/src/index.ts. PM's pre-dispatch correction confirmed.",
 "Card's claim that the live 401 was the response behind the banner is measured FALSE; a 401 could not reach the capability-missing branch in the pre-fix code, and the banner quoted the 404 NOT_FOUND body verbatim. The 401 was a separate unauthenticated probe."
 ],
 "summary": "queryDataset mapped a failed dataset query by HTTP status, and 404 is answered by two unrelated conditions on that url — the dispatcher's ROUTE_NOT_FOUND when the route is unmounted, and the route's own NOT_FOUND when the named dataset does not exist — so every unknown dataset produced the capability-missing banner. The mapping now branches on the ADR-0112 code, giving three conditions three answers: NOT_IMPLEMENTED/ROUTE_NOT_FOUND keep the existing AnalyticsNotInstalledError and copy, NOT_FOUND throws the new AnalyticsDatasetNotFoundError naming the dataset and the app-version remedy, and UNAUTHENTICATED throws the new AnalyticsUnauthenticatedError. Status is consulted only as a residual when the answer declares no code. The headline is now a pure function of code and the parenthetical a verbatim quote of message off the same response, so the banner can no longer quote its subject and contradict it; a parameterised test walks every branch asserting each message carries its own headline and none of the others'. Change is additive: AnalyticsNotInstalledError keeps its code, copy and arity.",
 "tests": "All at branch head 5c2376387. `pnpm exec vitest run --maxWorkers=2 packages/data-objectstack/` -> 'Test Files 42 passed (42) · Tests 576 passed (576)' (545 before, 31 new). `pnpm --filter @object-ui/data-objectstack type-check` -> tsc --noEmit exit 0 (script name echoed in output, so not a zero-match no-op). `pnpm exec eslint .` in the package -> '✖ 368 problems (0 errors, 368 warnings)', all pre-existing no-explicit-any. ABLATION: restored the pre-fix `res.status === 501 || res.status === 404` mapping; mutation confirmed on disk by counting BOTH the injected marker (1) and the deleted branch text (0, and 0 for `AnalyticsDatasetNotFoundError({`), not by an editor exit code; 9 of the 31 new tests turned red — predicted direction, turn-red — covering all four branch pins, the incident replay, the dataset-unknown and not-signed-in headline/parenthetical pins, the bare-401 residual and the unrecognised-404 pin, while the route-absent headline pin correctly stayed green because the ablation does not move that branch's verdict. NO REBUILD NEEDED for the ablation: the test imports './index' by relative source path (queryDataset.test.ts:25), so dist staleness cannot make it falsely green. Restore leg ran under a `trap ... EXIT INT TERM` and was verified byte-identical to the commit (`git diff --stat HEAD` empty), then re-measured green at 576/576. CROSS-PACKAGE TYPE CHECK against the rebuilt dist/index.d.ts (rebuilt in the same run: 'DTS Build success', dist/index.d.ts 123.91 KB): a consumer calling the pre-existing 2-arg `new AnalyticsNotInstalledError(surface, detail)` compiles, exit 0; reverse leg passing `datasetName: 404` fails with 'TS2322: Type number is not assignable to type string', proving the declarations read are the rebuilt ones and not a cache.",
 "gates_run": [
 "vitest packages/data-objectstack/ -> 'Test Files 42 passed (42) | Tests 576 passed (576)' PASS",
 "@object-ui/data-objectstack type-check (tsc --noEmit) -> exit 0 PASS",
 "eslint . in packages/data-objectstack -> '✖ 368 problems (0 errors, 368 warnings)' PASS (0 errors; lint script has no --max-warnings)",
 "check:control-bytes -> '✅ check-control-bytes: OK (scanned 4768 tracked text file(s); skipped 85 binary).' PASS",
 "check:i18n-keys -> '✅ Every in-scope call-site key resolves against the en pack (2924 keys), every literal inline defaultValue matches the value the pack serves…' PASS",
 "check:i18n-drift -> '✅ No en value changed in this range.' PASS",
 "check:phantom-deps -> exit 0 PASS",
 "check:self-import -> exit 0 PASS",
 "check:esm-specifiers -> exit 0 PASS",
 "check-changeset-presence.mjs -> '✅ 2 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s): .changeset/analytics-error-branch-mapping-5663.md.' PASS",
 "check-changeset-no-major.mjs -> '✅ No changeset declares a major bump.' PASS",
 "check-changeset-fixed.mjs -> '✅ All workspace packages are in the changeset fixed group.' PASS",
 "check:i18n-dead-keys -> NOT RUN; report-only by its own header and wired into no CI workflow, and this diff adds no pack keys",
 "DECLARED NARROWING: repo-wide `pnpm test` / `pnpm type-check` / `pnpm lint` (all `turbo run …`) left to CI. The lint narrowing is a measurement: population from eslint's own config resolution via `eslint .` in the package (the exact command turbo invokes for it), file count 48 read from --format json, and eslint.config.js enables no type-aware linting (tseslint.configs.recommended, no parserOptions.project / projectService) so this diff cannot move a verdict in any file it does not edit. Diff touches 2 files, both in this one package.",
 "NOT USED: scripts/pm/dispatch-gates.mjs — it lives in objectstack and its gate names do not exist here, per the dispatch. Gate list derived from objectui's own .github/workflows/ and root package.json."
 ],
 "files_changed": [
 "packages/data-objectstack/src/index.ts",
 "packages/data-objectstack/src/queryDataset.test.ts",
 ".changeset/analytics-error-branch-mapping-5663.md"
 ],
 "open_questions": [
 {
 "question": "Triage's ruling ends 'i18n keys per the pack conventions', but no key can be added where this copy lives. @object-ui/data-objectstack is a transport adapter with no @object-ui/i18n dependency and no t()/tt() call sites; it throws Error subclasses whose .message both live renderers print verbatim (plugin-dashboard/src/DatasetWidget.tsx:530 and app-shell DatasetPreview). Landing pack keys here would be keys with no call site — dead on arrival, and the reverse-sweep gate exists precisely to find that class. Localising this copy means moving the branch mapping into a renderer.",
 "options": [
 "A — ship as-is (what landed): the adapter classifies, its .message stays English, no pack keys. The operator-facing defect is fixed today and no dead keys are created.",
 "B — follow-up card in plugin-dashboard: DatasetWidget reads err.code and renders translated copy per branch, with keys in all ten packs. The adapter's structured fields (code, serverCode, serverMessage, datasetName) are already the inputs that needs; app-shell's DatasetPreview would want the same and is currently held by #5619.",
 "C — add @object-ui/i18n to the adapter and translate at throw time. Rejected on measurement: a new adapter -> React-i18n dependency edge, and the adapter has no locale context to resolve against."
 ],
 "recommendation": "A now, B as a separate card once #5619 clears app-shell. Triage's i18n clause is conditional on keys being added and the fence states it the same way ('only if you add keys'), so this is not treated as a breach of the ruling — but flagging it rather than silently choosing."
 }
 ],
 "out_of_scope_findings": [
 "filed as #5721: classifyAnalyticsFailure (same file, the /analytics/query face) tests `status === 404` BEFORE the code and short-circuits it, so service-analytics' CUBE_NOT_FOUND (404, assertInferableCube) is warned as a missing capability and then SILENTLY degraded to a client-side aggregate. Not fixed in this PR: different route face, different envelope family (dispatcher-wrapped), and it moves degradation behaviour rather than copy, so it needs its own measurement and pins. Unassigned, no pm:queue label. Duplicate search run first (keyword + file path over open issues): none."
 ]
}

---

Generated by Claude Code

[os-zhuang]

ACCEPT — PR #5723 · reviewer of record, domain:ui seat, round 17

Gates read by name at head 5c2376387: 19 success + 3 skipped = 22. Green, all four shards included. Fence clean: 3 files, all packages/data-objectstack/** + changeset — packages/app-shell/** untouched, as predicted.

The real defect is sharper than the card states, and the dev found it by reading the framework rather than the broken client. Every branch signature was established from /home/user/objectstack source, not inferred from the code under repair:

404 ROUTE_NOT_FOUND vs 404 NOT_FOUND — two unrelated conditions answering on one status, and the old mapping tested only the status.

That is the whole bug in one line, and it is not the line the card wrote. ROUTE_NOT_FOUND (dispatcher, wrapped envelope) means the route is unmounted; NOT_FOUND (the route's own dataset lookup, flat envelope) means the dataset does not exist. Mapping on status alone cannot separate them, so every unknown dataset produced the capability-missing banner.

⚠️ The card's causal account of the incident is wrong, and this correction should not be lost

The card records POST /api/v1/analytics/dataset/query → 401 UNAUTHENTICATED (not 404) and treats that 401 as the response that produced the banner. It cannot have been. Under the pre-fix code a 401 falls straight past res.status === 501 || res.status === 404 into the generic Dataset query failed: 401 Unauthorized string — it could never reach the capability-missing copy. Meanwhile the banner's own parenthetical quoted Dataset "opportunity_metrics" not found., which is the 404 NOT_FOUND body verbatim. So the browser session's request was answered 404 NOT_FOUND, and the recorded 401 was a separate, unauthenticated probe of the same URL.

The fix is unaffected — triage independently ruled 401 a third branch and it is implemented and pinned — but "the measured live case is 401" must not be carried forward as the mechanism. A prod incident report whose causal claim is wrong is exactly the kind of authoritative-looking artefact this lane keeps getting bitten by. Worth noting the diagnosis was reached the same way the fix was: by checking whether the evidence could actually have produced the observed output.

The design constraint held

The dispatch required that the headline and the parenthetical never be able to disagree. Delivered: the headline is now a pure function of code, and the parenthetical a verbatim quote of message off the same response — so the structural possibility of quoting your subject and contradicting it is gone, not merely avoided in the current copy. A parameterised test walks every branch asserting each message carries its own headline and none of the others'. The change is additive: AnalyticsNotInstalledError keeps its code, copy and arity, which is why DatasetPreview.tsx:89 (matching code === 'ANALYTICS_NOT_INSTALLED') needed no edit and packages/app-shell/** stayed out of the diff.

The residual branch is safe for a stated reason rather than by hope: status is consulted only when the answer declares no code at all, and the route's own NOT_FOUND always ships a code — so a code-less 404 cannot be the unknown-dataset case.

Ablation confirmed the mutation on disk in both directions (injected marker = 1, deleted branch text = 0, and 0 for AnalyticsDatasetNotFoundError({) rather than trusting an editor exit code; 9 of 31 new tests turned red in the predicted direction, while the route-absent headline pin correctly stayed green because the ablation does not move that branch's verdict. Restore under trap … EXIT INT TERM, verified byte-identical. The cross-package type check ran against a rebuilt dist/index.d.ts with a reverse leg (datasetName: 404 → TS2322) proving the declarations read were the rebuilt ones and not a cache.

Ruling on the open question: option A, and it is not a breach of triage's clause

Triage's ruling ends "i18n keys per the pack conventions". The dev measured that no key can be added where this copy lives: @object-ui/data-objectstack is a transport adapter with no @object-ui/i18n dependency and no t()/tt() call sites; it throws Error subclasses whose .message both live renderers print verbatim. Landing pack keys there would create keys with no call site — dead on arrival, which is precisely the class the reverse-sweep gate exists to catch. This lane has filed cards about dead locale keys repeatedly; manufacturing more to satisfy a conditional clause would be the wrong kind of compliance.

Ruled A (ship as landed: the adapter classifies, its .message stays English, no pack keys). Triage's clause reads "i18n keys per the pack conventions" — conditional on keys being added — and my fence stated it the same way ("only if you add keys"), so no clause is breached. Option C (add i18n to the adapter) is rejected on the dev's measurement: a new adapter → React-i18n dependency edge, and the adapter has no locale context to resolve against.

Option B is real work and is not being dropped: DatasetWidget reading err.code and rendering translated copy per branch, with keys in all ten packs. The adapter's structured fields (code, serverCode, serverMessage, datasetName) are already the inputs that needs — the landed change makes B possible, which it was not before. app-shell's DatasetPreview wants the same treatment; it was held by #5619, which merged at 22:42Z, so that hold is released. Carried to the seat post as a round-18 candidate rather than left in this thread.

Out-of-scope finding verified: #5721 — and it is the more serious one. classifyAnalyticsFailure (same file, the /analytics/query face) tests status === 404 before the code and short-circuits it, so service-analytics' CUBE_NOT_FOUND is warned as a missing capability and then silently degraded to a client-side aggregate. That moves behaviour, not copy — a wrong answer rendered as if it were right. Correctly not folded in (different route face, different envelope family, needs its own pins). Dedupe-searched first.

Flipped ready, auto-merge SQUASH. Closes on merge via Fixes #5663.

---

Generated by Claude Code