docs(adr): the AI answers business questions through the dataset semantic layer (#31503) (#31535)

<!-- claude-projects-attribution: {"github_login":"marchtian"} -->
_Requested by **田騏** · [project
thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSiALL9T9A18MoMEX2M9mrzhP)_
Fixes #31503

Clause-②: no
Metadata-protocol: none

## 维护者速读

- **改了什么**：新增 ADR-0149 草案（Proposed）：让 AI 通过 ADR-0021 的 dataset
语义层回答业务问题——指标与维度加 `synonyms`（同义词）和 `description`（一句业务定义）；新增
`list_datasets` / `query_dataset` 两个工具，一份定义同时给 MCP
和产品内问数；术语命中即用指标、多命中就反问、无命中退回对象查询并标明「非指标口径」；权限结论、评测钩子、实施拆卡。只动
`docs/adr/**`（含重生成的索引）。
- **为什么改**：cloud#3825 待裁 2 已裁「同意放
objectstack」。今天报表、仪表盘按管理员定义的指标取数，AI（问数和
MCP）却直接查对象、靠关键词猜字段，同一个「营收」各处不是同一个数。本卡让 AI 以 dataset 指标为准。
- **风险与回滚**：ADR 不改任何运行时行为，无发布面变化；回滚即删文件并重生成索引。设计风险集中在三项待裁：M1 给 AI
看的说明放哪个键、M2 无命中时的回退姿态、M3 认证指标 / 已验证问法是否本轮做。
- **先看**：`## Decisions for the maintainer`（M1–M3，各 2–3 个选项，带推荐与后果，四轴权重
长远合理性 50%），再看 D1（新键）与 D2（两个工具）。
- **两分钟验证**：在仓库根目录跑 `node scripts/check-adr-symbol-anchors.mjs && node
scripts/check-adr-links.mjs && node scripts/adr-index.mjs
--check`，三条全绿；全文无行号引用、无 HTML 注释。
- **需要你做的**：对 M1 / M2 / M3 各选一项（推荐 A / A / A）。裁定后座位拆实施卡；本 PR 是 Tier
H，由治理审批人 APPROVE 后方可 ready。

## What changes

- New
`docs/adr/0149-ai-answers-business-questions-through-the-dataset-semantic-layer.md`
(status Proposed). It measures `origin/main` (the dataset schema and its
member-description guidance, the `callCtx` gate chain and the three
strategy faces, the ADR-0021 Correction's unexecuted set, the
`McpDataBridge` seam and `MCPServerRuntime.bridgeTools`), surveys seven
platforms with primary sources, writes the contract (D1 keys, D2 tools,
D3 selection rule and provenance, D4 permissions, D5 evaluation hook, D6
enforce-or-remove table, D7 child-card split), lists what precedent
settles, and puts three genuine forks under `## Decisions for the
maintainer`.
- `docs/adr/README.md` regenerated by `node scripts/adr-index.mjs` (150
records, Proposed 5).

## Why

Card #31503 rests on the maintainer's ruling on
objectstack-ai/cloud#3825 待裁 2 (option A: the business semantic layer is
a platform capability built in objectstack; cloud's 问数 is its first
consumer). The semantic layer exists and is shipped; the AI does not
read it. This record designs the keys and the tools that close that gap,
binds the AI path to what the runtime executes, and names only the forks
the maintainer must settle.

## Tests

None added: a decision record. The ADR gates below are the tests. The
child cards named in D7 carry the unit tests (normalization and term
matching), the four-face permission parity test, and the liveness rows.

## Acceptance notes

- Tier H governed surface (`docs/adr/**`): needs an APPROVED review from
a governed approver before it is readied. The seat does not ready it.
- `skip-changeset`: an ADR moves no published surface; the keys it
designs land in child cards with their own declarations.
- Code positions measured on `origin/main` at f4b1f9e, kept out of the
record because the record cites symbols (maintainer ruling on #13556):
`packages/spec/src/ui/dataset.zod.ts` 155 / 346 / 622 (the three
schemas), 182-183 and 394-395 (the member `description` guidance),
636-637 (dataset `label` / `description`);
`packages/services/service-analytics/src/analytics-service.ts` 1865
(`callCtx`), 2121 / 2143 / 2333 / 2427 (the four assert doors), 2727 /
2749 / 2797 / 3601 / 3733; `packages/mcp/src/mcp-http-tools.ts` 110
(`McpDataBridge`), 213, 1620, 1776, 2131;
`packages/mcp/src/mcp-server-runtime.ts` 1413 / 1454;
`packages/mcp/src/types.ts` 16;
`packages/spec/src/contracts/ai-service.ts` 159;
`packages/spec/src/contracts/analytics-service.ts` 409 / 428 / 455;
`packages/spec/src/ai/mcp.zod.ts` 128.
- Permission measurement (card item 4): no dataset grouping path was
found that skips row-, field- or sharing-level enforcement; no finding
card is filed.
- An independent Fable review of the whole diff runs in the card thread;
its verdict is posted as a comment on this PR and its id is quoted in
the os-dev-report on the card.

## Verification

- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack <the two files>` derived 21 families. All 21
run; 21 green; `--ran` reconciliation: 21 derived, 21 run, 0
NOT-MEASURED, 0 UNRUN. One family (`check:doc-formula-expressions`)
first exited 3 for a missing build; built with `pnpm exec turbo run
build --filter=@objectstack/formula --filter=@objectstack/lint` and
rerun to 0.
- `origin/main` merged once before opening (merge commit c6e1072);
`adr-index --check`, `check-adr-links`, `check-adr-symbol-anchors` and
`check-commit-card-trailers --range origin/main..HEAD` re-run green
after the merge.
- Prior rulings read: cloud#3825 待裁 2 (option A); ADR-0021 D1, D-A, D-C
and the Correction of 2026-05-31; ADR-0049; ADR-0071; ADR-0078; ADR-0090
D10; ADR-0110 D3; #13556 (symbol anchors, no line numbers in ADRs);
#2698 (OAuth scopes map to tool families); #6504 (no count that is not a
fact); #27113 and #29145 (signature placement).

## Human Minimum

Each item is one rule from
[CONTRIBUTING.md › Human
Minimum](https://github.com/objectstack-ai/objectstack/blob/main/CONTRIBUTING.md#human-minimum),
which links the AGENTS.md text that states it.

- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(No schema changes in this PR.)
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes. (No package touched; the
derived doc gates ran instead.)
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset. (Nothing
publishes; `skip-changeset`.)
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed. (Not touched.)
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English. (The `维护者速读` block is
Chinese by the os-dev rule; the maintainer's ruling quotes are
verbatim.)
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_017ihL2d7Am3rsfrw4SBYwU2
<!-- signed: domain:spec#4 · marchtian ·
session_017ihL2eAG5J8aqAyPZif4BJ -->

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]