Merge remote-tracking branch 'origin/main' into claude/issue-4793-batch-row-result-schema

Author: claude

.changeset/analytics-empty-group-fill-compare-seam.md

@@ -0,0 +1,50 @@
+---
+"@objectstack/service-analytics": minor
+---
+
+fix(service-analytics): a measure a query never reported reads 0 for a count/sum on every merge seam (#4708)
+
+A dataset measure carrying its own `filter` runs as a separate grouped
+sub-query and is merged back onto the selected dimensions. A `GROUP BY` over a
+filtered row set emits **no group at all** for a dimension value the filter
+excludes entirely, so the measure comes back **absent**, not `0` — and
+`computeDerived` treats an absent operand as unknowable, so every ratio over it
+goes null too. The cell then renders blank, which is visually identical to "no
+data for this row" and means the opposite.
+
+The bias runs the worst possible way: the rows that blank are the ones whose
+numerator matched nothing — the **worst-performing rows**. A `lead_source` that
+won nothing rendered as "no data" while one that won everything rendered fine.
+
+The empty-group value is now filled **by aggregate kind** into every measure
+column the assembled grid lists but no query reported:
+
+| aggregate | over an excluded group | why |
+|:---|:---|:---|
+| `count`, `count_distinct` | `0` | "how many rows matched" has an exact answer when the answer is none |
+| `sum` | `0` | the identity element of the empty set |
+| `avg`, `min`, `max` | stays `null` | genuinely undefined — there is nothing to average |
+
+Filling all five with `0` would trade this lie for its mirror image, reporting a
+measurement nobody made, so the kinds are judged separately (via
+`emptyGroupValueFor`, shared with the authoring-side coherence checks).
+
+**Only cells are filled, never rows.** A dimension value no query reported at
+all has genuinely no data and stays out of the grid.
+
+**What changes beyond the measure-scoped seam.** The fill previously ran before
+the `compareTo` merge, and that merge *appends* a row for every bucket the
+PREVIOUS window had and this one does not. Every base measure on those rows —
+including unfiltered ones — was absent, so a lead source that sold last month
+and nothing this month rendered as "no data" instead of `0`: the same worst-row
+bias, one merge later. The fill now runs after every merge and covers all base
+measures plus their `<measure>__compare` columns.
+
+Widgets that worked around this with `?? 0` in the consumer or a `coalesce` in
+the measure can drop it; the coercion belongs in the executor, which is the only
+layer that knows which aggregate produced the gap.
+
+**New export.** `fillEmptyGroups(rows, columnAggregates)` is exported from the
+package root beside `mergeByDimensions`, so a host assembling a grid outside
+`DatasetExecutor` can apply the same aggregate-kind rule rather than
+reimplementing it — which is what makes this a `minor` rather than a `patch`.

.changeset/approval-record-lock-predicate-updates.md

@@ -0,0 +1,57 @@
+---
+"@objectstack/plugin-approvals": patch
+---
+
+fix(approvals): the record lock now holds for predicate (`multi`) updates (#4778)
+
+The ADR-0019 record lock — "while a record has a pending `sys_approval_request`,
+block edits to it" — was enforced only for updates that reach the hook with an
+`input.id`. The engine extracts that id from a **scalar** `where.id` alone; an
+operator object (`{ $in: [...] }`) or any other predicate is a multi-row write
+that routes to `updateMany` and arrives with no id. The hook opened with
+`if (!id) return`, so it read *"no row was resolved"* as *"there is nothing to
+authorize"* when the truth was *"nothing was ever queried"*.
+
+Rewriting the very same edit as `multi: true` therefore walked straight past the
+lock:
+
+```ts
+// rec_1 carries a pending approval, lockRecord is not disabled
+await ql.update('crm_opportunity', { amount: 999 }, { where: { id: 'rec_1' } });                       // RECORD_LOCKED
+await ql.update('crm_opportunity', { amount: 999 }, { where: { id: { $in: ['rec_1'] } }, multi: true }); // went through
+await ql.update('crm_opportunity', { amount: 999 }, { where: { name: 'x' }, multi: true });              // went through
+```
+
+No privilege was needed for that bypass — not an `admin` role, not `isSystem`,
+not `lockRecord: false`, not a whitelisted `approvalStatusField`. Every caller
+shape that can spell a predicate (SDK, ObjectQL, a flow's `update_record`) could
+produce it. It is the same fail-open reasoning fixed for `sys_attachment`
+(#4757) and `sys_comment` (#4630), in the one place where it needed no
+privilege at all.
+
+**The hook now resolves the rows a write touches before deciding.** By-id writes
+are unchanged (the driver writes by primary key, so the rest of `where` must not
+narrow the verdict). A predicate write is decided by intersecting the caller's
+predicate with the records that are actually locked — which is also what keeps
+it cheap: the query is bounded by the object's **pending approvals**, never by
+the update's match set, so a mass update of 50 000 unlocked rows costs one
+bookkeeping probe and is allowed. An unscoped `multi` update over the whole
+table reaches every locked row of the object and is refused while any is held.
+
+**Fail-closed, both ways.** Past 1 000 locked records — the bound the attachment
+and comment guards use — or if the intersection query fails, the write is
+refused rather than allowed: the lock could not prove the write misses a locked
+row. The approvals bookkeeping being unreadable at all stays the one fail-open,
+as before: this hook is global over every object, so a kernel without
+`sys_approval_request` would otherwise refuse every update in the deployment.
+Both the bookkeeping and the match-set resolution are read under a **system**
+context — a guard's own input must never be narrowed by the caller's
+visibility, since a locked row you cannot read is still a row you may not write.
+
+**Every exemption moved with the guard**, which is the other way this class of
+fix goes wrong — a guard extended to more rows that carries only its deny rules
+turns a fail-open into a false-positive. `isSystem`, the `admin` override, the
+`approvalStatusField` status mirror, `lockRecord: false` and the owning run's
+`flowRunId` (#3456 / #3712) all decide a predicate write exactly as they decide
+a by-id write, each pinned by tests on both predicate shapes. Refusals now name
+the record and object that are locked.

.changeset/book-job-translation-app-authorwarn-keys-retired.md

@@ -39,8 +39,14 @@ Run `os migrate meta --from 16` to rewrite existing sources automatically.
   migration table steered retired `errors:` authors straight into it. **That
   guidance entry is rewritten here**: retiring one dead key by pointing at
   another is the defect, not the fix.
-- **`app.homePageId`** — *its own hedge*. "If not set, usually defaults to the
-  first navigation item" described the only behaviour there was.
+- **`app.homePageId`** — *a second source for one fact*. Not unread: objectui's
+  console consumed it in `resolveLandingRoute()` and it was the only thing
+  deciding where an app opened. (This entry first shipped saying otherwise;
+  corrected in #4709, which upheld the removal.) What condemns the key is its
+  shape — an ID cross-reference into `navigation` with no referential integrity,
+  falling back to the first item *silently* when the id dangled. If "land
+  somewhere other than first" is ever wanted again it belongs on the navigation
+  item itself, not on a pointer that can miss.
 - **`app.areas[].order`** — *the sibling that works*. Nav-item `order` really is
   sorted; area-level order never was, and both renderers iterate the array as
   authored.

.changeset/check-i18n-fails-on-undeclared-authoring-key.md

@@ -0,0 +1,45 @@
+---
+---
+
+chore(devx): `pnpm check:i18n` now FAILS on an undeclared authoring key, not just on bundle drift
+
+Releases nothing — the change is confined to `scripts/check-i18n-bundles.mjs` and
+the root `check:i18n` script. No package source, no published behaviour, and
+deliberately **not** the `os i18n extract` exit code (that would write an internal
+hygiene rule into the public CLI contract).
+
+#4736 cleaned nine `scripts/i18n-extract.config.ts` files that all opened their
+`defineStack({ … })` with the same undeclared `name:` key. Nine, because the same
+mistake was copied from the first one — and nothing stopped any of them. The
+#4167 unknown-authoring-key lint *saw* every single one: it printed
+`stack.name: 'name' is not a declared stack key, so its value is dropped at load`
+on stderr, once per package, on every run. But the CLI exited 0 and the gate only
+judged bundle drift, so those nine warnings appeared inside a **fully green**
+`check:i18n` and were read as noise nine times. A warning that nine authors
+filtered out is not a control; #4736 cleaned the symptom, this closes the hole.
+
+**What changed.** The gate now reads the extractor's **stderr** — which it
+previously let flow straight through to the terminal, seen by nobody and judged by
+nothing — and fails on the unknown-authoring-key signature. Coverage needs no
+manifest: `findConfigs` walks `packages/`, so the tenth config is gated the day it
+lands.
+
+**The two verdicts stay separate.** Bundle drift keeps its own section and its own
+remedy (`--write`); the new class gets its own, naming the package, the config
+path, the key, and the consequence that matters — *the value is dropped at load,
+so whatever it was meant to configure is not in effect and never was*.
+Regenerating bundles does not fix it, and the message says so.
+
+**The gate is proven able to go red**, not merely observed green — the failure
+mode of `check:react-declaration-parity` (#4690), which exited 0 with nothing to
+check. Two proofs: `node scripts/check-i18n-bundles.mjs --self-test` (now wired
+into `check:i18n`, ahead of the real run) drives both classifiers over recorded
+CLI output, including a case asserting neither verdict matches the other's output;
+and the gate was run against the nine configs restored from `ffab8033b^`, the
+commit before #4803 deleted the keys, where it reports all nine and exits 1.
+
+Fixing an offending config means deleting the key at the producer. If a key is
+genuinely wanted it gets declared in `packages/spec` deliberately — not
+accommodated by a consumer-side fallback, and not silenced by making
+`ObjectStackDefinitionSchema` strict (which would mute the lint itself; see
+`metadata-authoring-lint.ts`).

.changeset/homepageid-tombstone-premise-corrected.md

@@ -0,0 +1,34 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): `app.homePageId` 的墓碑说清真正的退役理由 —— 「no shell ever read it」是假的 (#4709)
+
+**改的是「为什么删」的表述,不是删本身。** `app.homePageId` 在 17.0.0 依旧退役
+(`retiredKey`:编译期 `never`、解析期报错),conversion `app-dead-authoring-keys-removed`
+的行为、baseline、`os migrate meta --from 16` 的处方一字未动。
+
+#4667 给出的理由是「no shell ever read it」。这句是**假的**,而且与本仓自己的记录直接
+矛盾 —— 2026-06 的 AppSchema liveness 审计
+(`docs/audits/2026-06-appschema-property-liveness.md`)把 `homePageId` 明确列在 LIVE
+一侧,因为 objectui console 的 `resolveLandingRoute()`
+(`packages/app-shell/src/console/AppContent.tsx`,objectui @785b8a5d)一直在读它,而且
+它是**唯一**决定「app 打开时落在哪」的地方。两份文档矛盾了两个月无人发现,直到有人做
+cloud pin 对账时先信了这句、再去核渲染器才发现不对(#4709)。
+
+真正让这个键该走的是它的**形状**,不是无人使用:它把落地页编码成指向 `navigation` 的
+ID 交叉引用,没有引用完整性 —— id 悬空时**静默**回退到第一项(objectui 的实现正是如此),
+于是同一件事有两个来源,而错的那个不出声。将来若要「落地页 ≠ 第一项」,正确形状是导航项
+自身的标记(`navigation[].landing`:单一来源、不可能悬空),并按 enforce-first 设计
+(先有渲染器与测试,再进 schema)。
+
+墓碑文案改为诚实版本后,作者看到的处方**保持不变**:删掉这个键;要改 app 从哪里打开就
+重排 `navigation` 让目标项排第一;根落地由 `isDefault` 决定。同步纠正:conversion 摘要
+(经 `gen:upgrade-guide` / `gen:spec-changes` 重生成到 `docs/protocol-upgrade-guide.md`
+与 `spec-changes.json`)、生成文档 `content/docs/references/ui/app.mdx`、
+`content/docs/ui/apps.mdx`、liveness ledger 的 `homePageId` note、`examples/app-showcase`
+里那句「has no console consumer yet」,并给 6 月审计补了一条指向 #4667/#4709 的后续注记
+(审计结论本身是对的,原文不动)。新增一条 pin 测试,防止「无人读过」这类假前提回潮。
+
+objectui 侧那段永远进不去的 `if (homePageId)` 死分支单独清理:
+`objectstack-ai/objectui#3264`。

.changeset/hook-condition-fail-loud.md

@@ -0,0 +1,86 @@
+---
+"@objectstack/objectql": major
+---
+
+feat(objectql)!: a hook `condition` the platform cannot evaluate now ABORTS the operation (#4775)
+
+**Breaking.** A declarative hook whose `condition` cannot be evaluated used to
+emit a `logger.warn` and `return false` — the hook simply did not fire. Existing
+hooks that have been getting by on that silent skip will now **fail the write**.
+That is the point of the change, not a side effect: those conditions were never
+enforcing anything, and the failure is how you find out.
+
+## What changed
+
+"The condition said no" and "the platform could not work out what the condition
+says" used to collapse into one outcome, and that one outcome carries **opposite**
+risks depending on the hook:
+
+- a `before*` guard ("hold this write when the condition is met") swallowed into
+  `false` **lets through** a write it was declared to stop;
+- an `after*` audit ("leave a trace when the condition is met") swallowed into
+  `false` **drops** a row nobody will go looking for, because nobody knows it
+  should exist.
+
+So an unevaluable condition is `declared ≠ enforced`, and it is now resolved the
+way #4649 already resolved it for validation predicates one module over: reject
+loudly, naming the hook and the key that would not resolve. The rejection is a
+`HookConditionError` (exported), carrying `hook` / `object` / `event` /
+`condition` / `reason` / `fault` / `missingKey` machine-readably.
+
+`before*` and `after*` take the **same** direction, knowingly: a typo in an
+`afterUpdate` audit condition fails the write it was only watching. One rule, one
+answer — the platform does not grow a hidden second rule that makes the failure
+direction depend on the event name.
+
+A condition that never **compiled** aborts too. Its old treatment
+(`condition ignored`) was the worse half of the swallow: the gate disappeared
+entirely, so a declared guard let every write through and an audit fired on all
+of them. It is reported at invocation rather than at bind time, so one broken
+hook cannot wedge boot for an app nobody is writing to.
+
+## What did NOT change
+
+- A condition that evaluates **FALSE** is still just a skip, and the write still
+  succeeds. Only *unevaluable* is new.
+- `onError` (`abort` / `log`) is untouched and is deliberately **not** in this
+  path. It governs a handler that threw; the condition gate runs before the
+  handler is ever reached. Routing a condition fault through it would let
+  `onError: 'log'` resurrect the exact silent skip this change abolishes, and
+  would mint a third set of semantics for one word. `retryPolicy` and `async`
+  are outside it for the same reason.
+
+## Predicate (`multi: true`) bulk writes (#4800)
+
+A bulk write matches N rows and fires the hook **once**, so `previous` is unbound
+and `record` is the bare payload — there is no single prior record, and
+materialising declared fields to `null` would state something false about all N.
+Fail loud takes **no exception** here, but the message is a diagnosis rather than
+a riddle: it names the hook, says *this is a predicate bulk write and there is no
+single prior record*, and gives the route that works (rewrite without `previous`,
+or target the write at one record by id).
+
+It deliberately does **not** offer "use a record-change flow trigger instead":
+that trigger subscribes to these same lifecycle hooks, so on a bulk write it
+fires once with `previous` undefined too — verified against
+`trigger-record-change` and the engine, not assumed. Pointing at it would have
+made this very message the next `declared ≠ delivered`.
+
+An **undeclared** key on a bulk write still gets the ordinary typo message — that
+one really is a misspelling, and calling it a batch problem would send the author
+to fix a field that is spelled correctly.
+
+## Migrating
+
+Run your app and watch for `HookConditionError`. Each one names the hook and the
+key. The usual causes, in order of frequency:
+
+- **a misspelled or retired field** — fix the condition, or declare the field;
+- **an unguarded `null` comparison** (`record.spent > record.budget`) — guard
+  with `!= null`. Note `has(x)` does **not** do this: a declared field holding
+  `null` is still PRESENT, so `has(x)` is `true` and the ordering comparison
+  still faults;
+- **`previous` on a bulk write** — rewrite without `previous`, or write by id;
+- **a bare identifier** (`done == true`) — hook conditions are `record`-scoped,
+  so write `record.done == true`. Flow/automation conditions, which flatten
+  fields to top level, are a different surface and are unaffected.

.changeset/host-app-resolver-shared.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/types": minor
+"@objectstack/verify": minor
+"@objectstack/cli": patch
+---
+
+fix(verify): resolve the enterprise organizations package from the HOST APP (#4700)
+
+`bootStack(app, { multiTenant: true })` — and therefore `objectstack verify
+--multi-tenant` — could never load `@objectstack/organizations`. Node ESM
+resolves a bare `import()` against the **importer's own realpath**, which for
+`packages/verify` is inside the framework workspace, while the enterprise
+package is cloud-private and only ever lives in the verified app's
+`node_modules`. Every real host app fell into the catch and was told to
+"Install/link it in this workspace" — about a package it had already installed.
+Same defect class as cloud#1013, which fixed `objectstack serve`; #4699 fixed
+that one call site and this issue tracked the two the sweep left behind.
+
+**New: `@objectstack/types/node`.** The host-app resolver (`createHostRequire` /
+`createHostImporter`) moved out of `packages/cli/src/utils/import-from-host.ts`
+— where `@objectstack/verify` and the dogfood suite could not import it without
+inverting the dependency direction — into a **node-only subpath export** of
+`@objectstack/types`. One behaviour, one source; the CLI now consumes it and its
+private copy is deleted.
+
+It is a subpath and **not** the root export because `@objectstack/types` is a
+dependency of `@objectstack/hono` ("edge-compatible REST API server for
+Cloudflare Workers, Deno, Bun, and Node") and of the plugin layer a `LiteKernel`
+boots on Workers. The root entry reaches zero `node:` builtins, and a Workers
+bundle breaks on `node:module` even when nothing calls it. `tsup` emits the two
+entries as separate self-contained bundles (`splitting: false`), and a test
+walks the root's import graph and fails on the first reachable `node:`
+specifier, so the isolation is enforced rather than merely intended. Same
+arrangement `@objectstack/metadata` already ships for its `./node` subpath.
+
+**New: `BootOptions.hostRoot`** (optional, defaults to `process.cwd()`) names
+the app whose `node_modules` supplies those optional packages — for a harness
+booting an app that is not the working directory.
+
+**The dogfood multi-org gates had never run.** Two suites probed availability
+with the same bare `import()` and so were **constant-false** — not "false
+because absent" but false by construction, in every environment including the
+cloud CI whose comment claimed it ran them. The #1994 cross-tenant RLS proof and
+the attachments cross-tenant isolation block had therefore never executed while
+the suite reported green (Prime Directive #10, test-suite edition). They now
+resolve like the runtime does, and `OS_TEST_MULTI_ORG_ENABLED=1` declares that a
+run is expected to ship the package — turning a silent skip into a loud failure,
+so a run can no longer pass by quietly not running the gates it exists for.