Merge remote-tracking branch 'origin/main' into claude/issue-5696-transaction-contract

Author: claude

.changeset/analytics-query-declared-fault-withhold.md

@@ -0,0 +1,87 @@
+---
+"@objectstack/types": minor
+"@objectstack/runtime": minor
+"@objectstack/rest": patch
+---
+
+fix(runtime,types)!: `/analytics/query` no longer echoes RLS policy field names — the declared-server-fault withhold is shared by both HTTP boundaries (#5811)
+
+**Observable behaviour change — read this if you read, log, or assert on
+`error.message` from a dispatcher-plugin route.** An error that **declares a
+server fault** in the ADR-0112 envelope (`status >= 500` *and* a non-empty
+`code`) now leaves `dispatcher-plugin.errorResponseBase` with its message
+replaced by `"Internal server error"`. It previously reached the caller verbatim
+unless it happened to *sound* like a SQL/driver dump. This applies to every route
+that plugin mounts — `/analytics`, `/packages`, `/i18n`, `/automation`, `/auth`,
+`/notifications`, `/mcp`, … — not only the one that motivated it. Nothing a
+machine reads changed: the producer's `code` still arrives in the response
+(`error.code`, promoted there from `details` by the shared envelope builder,
+#3842), the status is untouched, and the full original text still goes to the
+server log and `errorReporter` via `__obsRecordedError`.
+
+## What was wrong
+
+#5367 (maintainer ruling 2026-08-06) made `read-scope-sql.ts`'s ten fail-closed
+RLS lowering refusals `READ_SCOPE_COMPILE_FAILED` / 500 and taught
+`POST /analytics/dataset/query` to withhold their message, because those messages
+name the field names and comparands of an **administrator's** sharing rule:
+
+```
+[read-scope-sql] unsafe field identifier "secret_policy_field" — refusing to
+build read scope (fail-closed).
+```
+
+The caller never wrote that field name and must not be able to read it out of an
+error body. But the **sibling** analytics face was never closed.
+`compileScopedFilterToSql` runs on both `NativeSQLStrategy.applyReadScope` and
+`ObjectQLStrategy`'s echoed SQL, both of which serve `POST /analytics/query`,
+which exits through `dispatcher-plugin.errorResponseBase`. That exit's only
+message guard was `looksLikeInternalErrorLeak` — a heuristic over SQL/driver
+*phrasing* — and all eleven read-scope message shapes return `false` from it.
+Measured at that boundary: **11 of 11 echoed verbatim**, at 500, with the policy
+content in `error.message`. A real reachable disclosure, not a theoretical one.
+
+## What changed
+
+- **`@objectstack/types` gains `declaresServerFault(err)`**, exported from
+  `error-leak.ts` beside `looksLikeInternalErrorLeak`. The heuristic asks whether
+  a message *sounds* internal; the declaration asks whether the producer *said
+  so*. `error-leak.ts`'s own file header already states the principle — "do not
+  ship driver internals to clients" is a property of the HTTP boundary, not of
+  one router — and this is the second predicate that principle asks for.
+- **Both boundaries read it.** `dispatcher-plugin.errorResponseBase` gains the
+  withhold (the fix); `rest-server.ts`'s `/analytics/dataset/query` catch drops
+  its in-line copy of the same test in favour of the shared one. #5808 wrote that
+  rule in-line on purpose — promoting a rule with one consumer is a speculative
+  surface — and this is the second consumer, so it was promoted rather than
+  duplicated (`#3843`/`#3867` paid for the two-implementations shape twice).
+  The REST face's verdict is unchanged in every case: same `status >= 500` plus
+  non-empty `code` test, over the same two fields.
+
+## What deliberately did NOT change
+
+- ⛔ **This is not "withhold every 5xx".** #5667 kept **undeclared** 5xx errors
+  legible on purpose: a bare `Error` from our own code ("no strategy can handle
+  query …") is the operator's own bug report, names nothing tenant-sensitive, and
+  still falls to `looksLikeInternalErrorLeak` alone. A 5xx carrying only half an
+  envelope (a status with no code) is likewise still readable — inventing the
+  withhold for it would be the consumer-side leniency Prime Directive #12 removes.
+- **4xx is untouched.** `declaresServerFault` requires `status >= 500`, so a
+  deliberate business/validation answer can never be swallowed by it.
+- **`statusCode` is not accepted as a substitute for `status`.** `status` is the
+  channel ADR-0112 declares; making a disclosure rule depend on which spelling a
+  producer reached for would be the same leniency in a different place.
+- **The heuristic was not taught to recognise `[read-scope-sql]`.** That would be
+  more prose sniffing — the mechanism #5352/#5367 exist to remove — and would only
+  ever cover the family someone remembered to add.
+
+Coverage: `analytics-query-read-scope-withhold.test.ts` (runtime) drives six RLS
+policy shapes end-to-end through a **real** `AnalyticsService` on the real
+native-SQL path and the real mounted route, asserting the 500, that the whole
+serialized body contains no policy detail, that `error.code` still carries
+`READ_SCOPE_COMPILE_FAILED`, and that the full text is still on the
+`__obsRecordedError` side-channel — plus a positive control and both sides of the
+declared-vs-undeclared tiering. `error-leak.test.ts` (types) pins the predicate
+directly, including that all eleven read-scope shapes stay invisible to the
+heuristic. The REST face's existing `analytics-read-scope-refusal-envelope.test.ts`
+is green before and after, unchanged, which is the pin on the refactor.

.changeset/defer-adr0104-attestation-while-seed-in-flight.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/platform-objects': patch
+'@objectstack/runtime': patch
+'@objectstack/objectql': patch
+'@objectstack/spec': patch
+---
+
+fix(platform-objects): 超预算后台 seed 期间不再空库自证 —— 一次启动不再跑两套契约
+
+#4769 已把 ADR-0104 的空库自证从 `kernel:ready` 挪到 `app:seeded`(本次启动自身数据的结算点),但保留 `kernel:ready` 作为「从不 seed 的内核」的兜底。剩下的窗口是这两个钩子**到达顺序可以颠倒**:`AppPlugin` 的 inline seed 超出软预算(`OS_INLINE_SEED_BUDGET_MS`,默认 8s)后转入后台,于是 `kernel:ready` 先到、兜底自证在 seed 仍在写的时候签发证书并把闸门翻到 strict——同一次 seed 运行的后半段撞上前半段从未见过的契约。showcase 冷启(`OS_INLINE_SEED_BUDGET_MS=1`)实测:自证发生在 +0.470s,seed 结算在 +3.617s,窗口 3.147s。
+
+现在两个钩子都先问一句「本次启动自己的 seed 落定了吗」,任一处报告仍有未结算的 seed 源就不签发。`app:seeded` 同样受这道检查约束——多 config app 的 bundle 会每个 app 触发一次,第一次并不是本次启动的结算点。
+
+新增 `seed-settlement` 契约(`@objectstack/spec/contracts`)承载这个信号,而不是让 platform-objects 去嗅 runtime 内部的 `seed-datasets` 服务:那个数组的存在只能说明「seed 源存在」,永远说明不了「已经落定」,而这两件事之间的差正是本 bug 的整个窗口。runtime 在选择分支之前先声明 seed 源,并在写入真正结束的同一刻结算它。
+
+**multi-tenant 与 `skipSeedData` 的 ADR-0104 姿态(2026-08-06 裁定,#4795)**:这两种部署会注册 seed 数据但在启动时并不写入(前者按 org 在 `sys_organization` insert 时重放,后者是 `os migrate` 的只读规划启动,#3917),`app:seeded` 永不触发。它们的姿态是**启动时不自证,等 `os migrate … --apply` 在真实扫描的证据上落笔**——由同一个判据自然得出,不需要单独分支。这是答案而不是缺口:在启动那一刻断言一次尚未发生的 per-org 重放不含违规值,正是 #4769 的同一个错误、只是引信更长;而停在 warn-first 是可恢复的方向,随时可由 `os migrate value-shapes --apply` / `os migrate files-to-references --apply` 关闭。
+
+`@objectstack/objectql` 侧只更新了 #4769 撤销机制的注释:「后台 seed 收尾晚于签发」不再是它要兜的场景(已在源头关闭),它对 `os dev` 热重载 seeder、运行期 marketplace 安装以及 lax 开关仍然有效。

.changeset/dev-watcher-restart-honesty.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `objectstack dev` restarts the server after each rebuild — the running server can no longer silently disagree with `dist/objectstack.json` (#5148)
+
+The dev watcher rebuilt `dist/objectstack.json` on every source change and
+printed `✓ recompiled — server will auto-reload`, but the running serve child
+only **partially** received the rebuilt artifact: MetadataPlugin's own
+artifact watcher re-ingests the metadata registry, syncs DDL + seeds for
+newly-appearing objects and broadcasts the SSE HMR event — while hook bodies
+and already-registered view metadata from the compiled bundle are applied at
+**boot only**. #5148 measured both staying stale: the old hook kept executing
+and `/api/v1/meta/views` kept serving the old view after a confirmed on-disk
+rebuild, with no error and no warning. That made every dev edit/verify loop
+capable of a false conclusion in either direction ("my fix doesn't work" /
+"this code isn't load-bearing").
+
+`objectstack dev` now supervises its serve child nodemon-style:
+
+- **Auto-restart (default-on).** After a rebuild lands on disk, the serve
+  child is SIGTERMed (the kernel shuts down gracefully), and a replacement is
+  spawned once it exits — boot-time load is the one path that applies the
+  whole artifact. Restarts coalesce (rapid saves produce one restart), a
+  child that ignores SIGTERM is force-killed after 8s, a replacement that
+  fails to come up is loud and exits dev, and parent SIGINT/SIGTERM is
+  forwarded to the child so no orphan server outlives dev.
+- **`--no-restart` opt-out.** The watcher then only rebuilds the artifact —
+  and every rebuild now says explicitly that the running server keeps the
+  build it booted with. The watch banner states the active mode instead of
+  implying a hot reload the runtime only partially performs.
+- **Boot-time staleness warning (#5148 startup variant).** When
+  `objectstack.config.ts` / `src/**` are newer than the artifact at boot
+  (edited while the server was down), dev warns loudly that the boot serves
+  the stale build, names the newest source file and the remedy
+  (`objectstack build`, `--compile`, or save a watched file). The boot is
+  never gated — the silence is removed, not the start.

.changeset/docs-gen-module-description-selection.md

@@ -0,0 +1,57 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): a reference page's opening paragraph is the module's own doc block, never a symbol's (#5059)
+
+`getFileDescription()` took the **first** doc block anywhere in a `*.zod.ts`
+file, verbatim, and published it as the page's opening paragraph. That is not a
+rule about descriptions — it is a rule about *ordering*: whichever declaration
+happened to sit at the top of the file donated its comment to a public
+document. Adding a helper above the first schema silently rewrote a published
+page, and no gate could see it. `check:docs` compares the generated page against
+the source and the page reproduced the wrong block faithfully, so there was no
+drift to report; the trap was written down when the generator was built and
+still landed on `main` twice.
+
+The measured victim surface was **six pages**. The Translation protocol
+reference opened with `Shared history sentence for every shape in this file
+(#4001).` — this repo's internal tightening-campaign narrative — and the Mapping
+page with its sibling. Four more had no history constant anywhere near them:
+`api/contract` published the doc of `ApiErrorSchema.code` (a comment *nested
+inside* an object literal), `api/realtime` published `Transport Protocol Enum`
+on a page documenting fourteen schemas, and `api/protocol` / `kernel/plugin` the
+same shape. Any future "move a helper to the top of the file" makes another.
+
+The selection now follows **TSDoc's own rule, read back**: a doc block belongs
+to the declaration it immediately precedes — which is exactly the text an editor
+shows when you hover that symbol. So a module description must be a block that
+
+- starts at column 0 (a block indented inside a declaration body documents a
+  property, never a module),
+- appears before the first declaration (imports and re-exports introduce no
+  symbol of their own and do not close the header zone), and
+- is not immediately followed by a declaration.
+
+When no block qualifies the page prints no description at all — 宁可缺,不要错.
+A confidently rendered internal note is a page that lies about its subject,
+which is worse for a reader (and for an AI author working from these pages) than
+a page that opens with its `Source:` pointer.
+
+**Twenty reference pages lost an opening paragraph**, each of which was a
+symbol's JSDoc rather than the module's: the six above plus `ai/solution-blueprint`,
+`ai/tool`, `api/error-code-ledger`, `api/router`, `automation/approval`,
+`cloud/template-manifest`, `data/driver-mysql`, `data/driver-postgres`,
+`data/driver-sqlite`, `kernel/manifest`, `shared/enums`, `system/doc`,
+`system/notification`, `ui/responsive`. **No page lost a real module header** —
+the other 178 pages with a `Source:` line keep their description byte for byte.
+A module that wants its opening paragraph back writes one block that documents
+no symbol; 178 sources already do.
+
+The rule is also the gate. The issue proposed failing on first sentences
+matching `#\d{3,}` / `Shared history`, but that recognises only the
+history-constant subclass, and only after publication — it would have caught two
+of the six. A selection rule that cannot pick a symbol's comment makes the whole
+class impossible instead. `scripts/lib/file-description.ts` (extracted from
+`build-docs.ts`, following `format-type.ts` #4912 and `escape-mdx.ts` #5452) and
+its pin suite `scripts/file-description.test.ts` carry it, corpus check included.

.changeset/docs-gen-numeric-literal-quoting.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): the reference generator quotes a literal by its `typeof`, so numeric literals stop being written down as strings (#5729)
+
+`formatType()`'s two literal branches wrapped every value in `'…'` without
+looking at its type — `prop.enum.map(e => `'${e}'`)` and
+`return `'${prop.const}'`` — so a **numeric** literal union was printed as a
+**string** one. `FormSection.columns` is the specimen the issue was filed from:
+it is declared
+
+```ts
+z.union([z.enum(['1', '2', '3', '4']), z.literal(1), z.literal(2), z.literal(3), z.literal(4)])
+```
+
+and `content/docs/references/ui/view.mdx` rendered it as
+`Enum<'1' | '2' | '3' | '4'> | '1' | '2' | '3' | '4'`, where the second half is
+those four `z.literal(<number>)` variants. The two halves came out
+indistinguishable, so the page claimed the key takes strings only — while the
+schema accepts both `2` and `'2'`.
+
+For these pages that is a contract error, not a typo. They are the authoritative
+input for an AI author (ADR-0033), and a literal union is a copy-the-spelling
+surface: whatever quoting the page shows is what gets written. #5611 paid for it
+directly — its `RecordDetailsProps.sections[].columns` was meant to be a numeric
+literal union, the generated reference said strings, and the PR abandoned the
+shape for `z.number().int().min(1).max(4)` to escape the contradiction. The
+generator was defining the contract backwards.
+
+Quoting is now decided per **value**, not per node, because JSON Schema states
+member types per value and an `enum` may mix them (`z.nativeEnum({ A: 1 })`
+emits a numeric `enum`): strings stay quoted, `number`/`boolean` render bare,
+and `null` renders as the keyword.
+
+Eight reference pages change, 11 lines, and in one direction only — quotes are
+removed from 18 non-string literals and no string literal loses its:
+`api/dispatcher`, `api/errors` (`success: false`), `data/data-engine`
+(`sort: Record< string, 1 | -1 >`), `data/driver-nosql` (`projection:
+Record< string, 0 | 1 >`), `data/object` (`systemFields` / `stageField: false`),
+`security/explain` (`version: 1`), `ui/dashboard` (`filterBindings`) and
+`ui/view` (`columns: … | 1 | 2 | 3 | 4`). Every `Enum<'a' | 'b'>` on those
+pages is untouched.

.changeset/eighty-months-obey.md

@@ -0,0 +1,29 @@
+---
+'@objectstack/spec': patch
+---
+
+ADR-0087 semantic-migration ledger: register the immediate retirement of the `ctx.user.roles` alias
+
+The `roles` alias on `ActorUser` — the `user` envelope an action body reads as `ctx.user` and an
+AI route handler reads as `req.user` — was removed outright in protocol 17 (#6011, runtime half in
+PR #6048): no deprecation window, no dual-emit. The retirement had shipped, but the ADR-0087
+migration ledger carried no entry for it, so it was invisible to `objectstack migrate meta`,
+`spec-changes.json` and the generated upgrade guide — while all three sibling faces of the same
+ADR-0090 rename (`data.hookContext.session.roles`, `ui.actionSession.roles`,
+`CEL/formula: current_user.roles`) were registered. This adds the missing entry
+(`actor-user-roles-to-positions`) and regenerates the artifacts projected from it.
+
+FROM `ctx.user.roles` / `req.user.roles` → TO `ctx.user.positions` / `req.user.positions`. The
+value is unchanged: both keys were filled from one assignment (`roles: core.positions`), so this is
+a pure key rename. Fix: rewrite the read. `roles.includes('admin')` used as an ACCESS CHECK is not
+renamed to `positions.includes('admin')` — ask the security service instead (ADR-0095); renaming
+that read migrates the defect rather than the code.
+
+Note this face has **no window**, unlike its neighbour `ctx.session.roles` (#5613), which still
+dual-emits for one release. `ctx.user.roles` is already absent in 17: a typed body fails `tsc` at
+the read, an untyped or sandboxed one silently sees `undefined` — so move the read as you upgrade,
+not after. `ctx.user` has never had a spec schema (it is a runtime TS interface), so no
+`retiredKey()` tombstone can carry the prescription; this ledger entry and the generated upgrade
+guide are the channel.
+
+Spec source change is the registry entry only — no schema, no export, and no authorable key moved.