Merge remote-tracking branch 'origin/main' into claude/issue-4775-hook-condition-fail-loud

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/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/lint-searchable-fields-type-validation.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): 视图 `searchableFields` 按运行时同一套判定做构建期校验 —— 一个 lookup 笔误不再等到 400 才暴露 (#4830)
+
+视图(list view)的 `searchableFields` 会被客户端逐字回显为 `$searchFields` 覆盖参数,而
+REST 入口闸(#4254)会用 `resolveSearchFieldResolution`(`@objectstack/spec/data`)判定
+该对象的可搜索集合 —— 声明一个 lookup 等「不可搜索」字段,运行时会把**整条查询** 400
+(`INVALID_FIELD`),列表工具栏搜索对全体角色彻底不可用。此前 `compile`/`validate` 只查
+字段**存在性**,这类笔误全绿放行,只能靠人肉点搜索框发现。
+
+新增规则 `searchable-field-unsearchable`(error 级,新导出常量同名):对每个视图级
+narrowing(对象内建 `listViews`、`defineView` 的 `list`/`listViews`、react 页面的
+`<ListView searchableFields>`)按**运行时同一个函数**(`resolveSearchFieldResolution`,
+非复制的类型清单,杜绝再度漂移)判定 declared = enforced:
+
+- 对象未声明 `searchableFields`(auto 源):视图里出现 lookup/json/hidden/审计列等
+  auto-default 拒绝的字段 → 构建期 error,信息含类型与 400 后果,lookup 给出「镜像到本
+  对象 text/formula 字段」的处方;
+- 对象已声明(declared 源):视图条目超出对象声明集合 → 构建期 error(视图只能收窄、
+  不能放宽,ADR-0061);
+- 对象自身的 `searchableFields`(canonical)维持**只查存在性**:运行时 declared 分支按
+  存在过滤、不按类型过滤,声明即被引擎执行,构建期拒绝会误伤运行时接受的元数据
+  (ADR-0072 D1);
+- 注册表注入的系统列在 narrowing 中跳过判定(其运行时元数据对 linter 不可见,宁可漏报
+  不可误报)。
+
+内部核心 `checkSearchableFieldList` / `indexObjectSearchTargets`(模块级导出,未入包
+barrel)签名有变:索引值从 `Set<string> | null` 变为 `ObjectSearchTarget | null`,并新增
+可选 `role: 'canonical' | 'narrowing'`(默认 `'narrowing'`)参数。

.changeset/retire-activation-events.md

@@ -0,0 +1,65 @@
+---
+"@objectstack/spec": major
+---
+
+refactor(spec)!: remove `activationEvents` (both keys) and the `ActivationEventSchema` vocabulary — lazy activation that no runtime ever implemented (#4657, ADR-0049)
+
+`activationEvents` promised lazy plugin activation ("plugins remain dormant
+until an activation event fires") on two authorable surfaces —
+`DynamicLoadRequest.activationEvents` (`@objectstack/spec/kernel`) and
+`StudioPluginManifest.activationEvents` (`@objectstack/spec/studio`, the
+`defineStudioPlugin` input) — and **no runtime in objectstack / cloud /
+cloud-v1 / objectui ever read either key** (four-repo bare-name scan in #4657,
+re-verified at implementation time). Every plugin has always activated
+immediately on load/registration; cloud-v1's own ROADMAP recorded lazy
+activation as ❌ unimplemented (planned v0.4.0). That is ADR-0049's
+declared ≠ enforced shape in the semantically-lying direction: an author
+writing `activationEvents: [{ type: 'onMetadataType', pattern: 'flow' }]`
+expected deferral and got eager activation with a clean parse.
+
+#4653 had just converged the two `ActivationEventSchema` declarations onto one
+structured `{ type, pattern }` form inside this same unreleased major; with the
+enforce-or-remove ruling landing on **remove**, that converged vocabulary
+retires before ever shipping. Composed across the two changes, a v16 author
+simply deletes the key in whichever form they carried.
+
+Migration (FROM → TO):
+
+- `activationEvents` in a `defineStudioPlugin` input / `StudioPluginManifest`
+  value — v16 string form (`['*']`, `['onMetadataType:flow']`) or v17-rc
+  structured form (`[{ type: 'onStartup', pattern: '*' }]`) alike →
+  **delete the key**. There is no replacement value: eager activation is the
+  only behaviour there has ever been, and `activate()` still runs at
+  registration time. The strict manifest parse rejects the key (and its former
+  VS Code-flavoured aliases `activation` / `events` / `onActivate`) with this
+  prescription.
+- `activationEvents` in a `DynamicLoadRequest` value → **delete the key**.
+  Tombstoned, not silently stripped — `DynamicLoadRequestSchema` is not
+  `.strict()`, so a `retiredKey()` tombstone makes authoring it a `tsc` error
+  and a parse error carrying the prescription.
+- `import { ActivationEventSchema, ActivationEvent } from '@objectstack/spec/kernel'`
+  (or `/studio`) → **no replacement export** (TS2305 after upgrade). Nothing
+  consumed the vocabulary; an exported schema with no consumer is read as a
+  capability by whoever finds it (#3950), so the orphaned def goes with the
+  keys.
+- Lazy activation is a **new capability**: if it is ever built it returns via
+  the enforce route of ADR-0049 through a new ADR — executor first, vocabulary
+  second — not by re-declaring inert keys.
+
+Self-check (#4535 §5): TS2305 — yes, two removed exports on two entries;
+metadata migration — none possible or needed (`StudioPluginManifest` is TS
+configuration parsed by `defineStudioPlugin`, a root schema never stored in
+`sys_metadata`; `DynamicLoadRequest` is a runtime request shape with no
+caller — no stored row exists for a D2 conversion to rewrite, so the change is
+one ADR-0087 D3 semantic record, `plugin-activation-events-retired`); shape
+change — two keys removed, zero behaviour change (eager activation before and
+after, byte-identical).
+
+The retirement kit: `retiredKey()` tombstone on the non-strict kernel schema;
+strict-parse `guidance` prescriptions on the studio manifest (including the
+three former aliases); ADR-0087 D3 semantic migration; baselines
+(`authorable-surface.json` — one `[RETIRED]` line, five lines dropped
+deliberately with the defs; `json-schema.manifest.json` — `kernel/ActivationEvent`
+and `studio/ActivationEvent` def removals; `api-surface.json`) regenerated
+deliberately; compiler-API export pin (`activation-events-retirement.test.ts`,
+zero holders across every public entry) — sabotage-verified.

.changeset/seed-env-enforced.md

@@ -0,0 +1,40 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(seed): enforce `Seed.env` — environment-scoped datasets no longer seed everywhere
+
+`Seed.env` was authorable, defaulted and type-checked, but inert. `SeedLoaderService`
+filtered on the **loader config's** `env`, and none of the six call sites that build a
+`SeedLoaderRequest` (app boot, per-org replay, hot reload, package apply, draft publish,
+marketplace install) ever passed one — so `config.env` was always `undefined`, the filter
+short-circuited, and `dataset.env` was never read. A dataset marked `env: ['dev']` seeded
+into production exactly as if it were marked `['prod']`, which is the dangerous direction:
+the rows most likely to carry that marking are demo users, fake customers and seeded
+credentials.
+
+The loader now resolves the environment itself, at the one funnel every seeding path goes
+through:
+
+- **Source is `NODE_ENV`** — the environment source this repo already uses everywhere
+  (`os start` defaults it to `production`, `os dev` / `serve --dev` set `development`,
+  vitest sets `test`). No new environment variable and no new authorable key. `production`
+  / `development` / `test` and the seed-enum spellings `prod` / `dev` are accepted,
+  case-insensitively.
+- **An explicit `config.env` still wins**, so a host can seed "as" another environment.
+- **A dataset that declares no `env`** (the schema default `['prod','dev','test']`) seeds
+  in every environment, exactly as before — no existing deployment loses rows.
+- **When the environment cannot be determined** (NODE_ENV unset, or a value like
+  `staging`), the loader stays permissive and seeds everything — but logs a **warning**
+  naming each environment-scoped dataset, the accepted `NODE_ENV` values and the
+  `config.env` escape hatch. Fail-open is deliberate: fail-closed would also drop an
+  `env: ['prod']` dataset on a production host that merely forgot to export `NODE_ENV`,
+  a silent data-loss regression worse than the over-seeding it prevents.
+- **Skipped datasets are always named** in an `info` log, so "my demo rows are missing" is
+  one log line to answer rather than a mystery.
+
+The resolved environment is also what seed CEL expressions now bind `env` to, so a seed's
+`env` and the loader's filter can no longer disagree.
+
+No API or schema change: `Seed.env` and `SeedLoaderConfig.env` are unchanged, and no
+package export was added.

.changeset/startup-registry-verdict-guard.md

@@ -0,0 +1,10 @@
+---
+---
+
+Tooling-only: `pnpm check:startup-registry-verdict` — startup registry reads may not record a verdict the boot can still contradict (#4777). Adds `scripts/check-startup-registry-verdict.mjs` + the shrink-only `scripts/startup-registry-verdict.baseline.json` (empty on landing), a `Lint & Type Check` step, and an AGENTS.md section. Releases nothing — no package changes.
+
+One showcase cold start on 2026-08-03 produced three instances of one shape in three unrelated subsystems written by three people at three times: ask a registry "is X there?" while the boot is still filling it, treat the "no" as final, and **record** it — cached on the instance (#4772 plugin-auth), asserted in a `warn` (#4771 service-automation), or written to the database (#4769 objectql). The provider registers a moment later and nothing undoes the record. All three are fixed; this is what stops the class from coming back.
+
+The gate matches the three-part shape, and part 3 is what makes it a rule rather than noise — a read-only probe stays completely legal, and the cures are never flagged: a probe deferred into a lazy accessor or a `kernel:ready` hook, a probe whose ordering an ADR-0116 declaration (`dependencies` / `optionalDependencies` / `requiresServices`) has already made final, and a verdict drawn at a declared seal (`sealNodeTypeVocabulary()`) all pass.
+
+Its reach is stated rather than implied: it under-matches on purpose. `getService('cache')` is visible, a `resolveCacheOrFallback()` three layers down another package is not, and #4769 is invisible to it entirely — that "registry" is the `sys_migration` table in a database. This stops the bleeding; it does not cure. Whether the kernel contract should be tightened further is #4776.