Merge remote-tracking branch 'origin/main' into claude/issue-4769-adr0104-attest-after-seed

Author: claude

.changeset/action-location-dual-source-c17.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": major
+---
+
+BREAKING(spec): `@objectstack/spec/studio` 改名 `ActionLocationSchema` → `ActionContributionLocationSchema`;裸名 `ActionLocation(Schema)` 现在全包唯一地指 `@objectstack/spec/ui` 的应用 UI 位置词表 (#4737, #4535 C17)
+
+`ActionLocationSchema` 曾由 `./studio` 与 `./ui` 各自导出一个声明 —— 同名、词表完全互斥的**两个概念**(#4411 陷阱):
+
+| 入口 | 词表 | 语义 | 处置 |
+|:--|:--|:--|:--|
+| `./studio`(**改名**) | `toolbar` / `contextMenu` / `commandPalette`(3 值) | Studio IDE 外壳里插件 action contribution 出现的位置(唯一嵌入方 `ActionContributionSchema.location`) | → `ActionContributionLocationSchema`,枚举值逐字不变;新增 `ActionContributionLocation` 类型导出(旧 const 从无 type 导出) |
+| `./ui`(**一字不动**) | `list_toolbar` / `list_item` / `record_header` / `record_more` / `record_related` / `record_section` / `global_nav`(7 值) | 运行中应用的 UI 上 action 渲染的位置,docblock 自宣全平台唯一真源 | 裸名唯一归属(objectui 按引用钉住 `ACTION_LOCATIONS` 并 re-export 类型族) |
+
+## FROM → TO
+
+```ts
+// FROM —— 编译期起以 TS2305 失败(实测 objectstack / cloud / objectui 三仓零外部 importer,预期无人受影响)
+import { ActionLocationSchema } from '@objectstack/spec/studio';
+
+// TO —— 同一声明、同一词表,名字点明它唯一的语义
+import {
+  ActionContributionLocationSchema,
+  type ActionContributionLocation,
+} from '@objectstack/spec/studio';
+```
+
+**要的是应用 UI 的 action 位置?** `import { ActionLocationSchema, type ActionLocation } from '@objectstack/spec/ui'` —— 本次未动。
+
+不保留旧名别名:在 `./studio` 上 re-export 任何一侧的 `ActionLocationSchema` 都会重开本次关闭的陷阱(要么复活双源,要么把应用 UI 词表谎报成 Studio 清单词表)。
+
+## 零元数据迁移
+
+本次只动 TS 导出名与内部 JSON Schema def 名(`studio/ActionLocation` → `studio/ActionContributionLocation`,走 `RENAMED_DEFS` 承接表,0-key carry —— 枚举 def 无 authorable properties)。作者在 Studio 插件清单里写的 `contributes.actions[].location` 取值域(`toolbar` / `contextMenu` / `commandPalette`)逐字节不变,已有清单原样解析。无 tombstone(没有 key 退役)、无 ADR-0087 conversion —— `StudioPluginManifestSchema` 是根 schema,不在 stack 树上,conversion walker 到不了它(`converge-activation-event-schema` 先例论证)。发布的 JSON Schema `$id` 随之移动:`…/studio/ActionLocation.json` → `…/studio/ActionContributionLocation.json`。

.changeset/attachment-unscoped-multi-delete.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/service-storage": patch
+---
+
+fix(service-storage): an UNSCOPED multi-delete of `sys_attachment` is refused instead of authorized (#4757)
+
+`installAttachmentAccessHooks`'s `beforeDelete` gate resolved the rows a delete
+matches in two ways — by `input.id`, or by `input.options.where` — and then
+short-circuited with `if (!rows.length) return`. A delete carrying **neither**
+an id **nor** a `where` took neither branch, so `rows` stayed empty and the gate
+returned *allow*. That is not "nothing matched": nothing was ever queried.
+
+The engine reads the same call as a bulk delete over everything — with no
+single id it seeds the delete AST as `{ object }` and hands that to
+`driver.deleteMany` — so `ql.delete('sys_attachment', { multi: true })` emptied
+the whole attachment table with the record-level gate having authorized exactly
+zero rows. Neither layer underneath catches it: plugin-sharing composes no
+row-scoping predicate for an object with no owner field (`sys_attachment`'s
+provenance column is `uploaded_by`), and plugin-security only refuses callers
+whose grants lack the delete bit on `sys_attachment` — an app shipping the
+domain grant the attachments panel requires passes RBAC and lands here.
+
+The gate now fails **closed** on that shape: no id and no `where` is refused
+with 403 `ATTACHMENT_DELETE_DENIED` ("Refusing an unscoped multi-delete of
+attachments — scope the delete to the rows you mean"), the posture #4630 gave
+`sys_comment` in `resolveTargetRows`. "Nothing to authorize" and "nothing was
+ever queried" are different verdicts, and reading the second as the first is
+fail-open.
+
+Scoped deletes are unchanged: an id-bound delete, a `where`-bound multi-delete,
+and even `where: {}` (which matches every row but is a real query) still resolve
+their rows and authorize each one uploader-or-parent-editor as before — a delete
+that legitimately matches no row still passes. Only the predicate-less call is
+newly refused. If you were relying on `ql.delete('sys_attachment', { multi:
+true })` to clear the table, pass a predicate (`{ multi: true, where: {} }`
+authorizes row-by-row) or perform the sweep under a system context, which
+bypasses the gate as before.

.changeset/hook-condition-merged-record.md

@@ -0,0 +1,59 @@
+---
+'@objectstack/objectql': minor
+---
+
+**A declarative hook `condition` is now evaluated against the RECORD — the stored row overlaid with this write's payload — not against the update payload alone (#4770).**
+
+⚠️ **Behaviour change — read this before upgrading.** The condition gate used to evaluate
+against `ctx.input.data`: only the fields the current write happened to carry.
+`ctx.previous` sat behind it, unreachable, and the two were never merged. So a condition
+could reference only a field the update *happened* to touch; referencing anything else
+aborted the CEL expression with `No such key` — which the gate swallowed into `false`,
+leaving one WARN line as the sole trace.
+
+For a guard-style hook that reads as "let it through"; for an audit-style hook it reads as
+"do not record it". `condition: "record.done == true"` on an audit hook therefore did NOT
+run on the most ordinary updates there are — change the status, change the assignee —
+because `done` was not in the payload.
+
+The record a condition reads is now built the same way a validation predicate's is
+(#1871 / #4649, via one shared helper so the two cannot drift):
+
+- **stored ⊕ payload** — the prior record overlaid with this write's data, so a condition
+  may reference any field of the record, not just the changed ones. The payload still
+  wins for the fields it carries.
+- **total over the object's DECLARED fields** — `null` for a declared field present in
+  neither, so a driver that stores only the columns it wrote no longer decides whether an
+  expression is evaluable.
+- **declared fields only** — an undeclared or typo'd key (`record.stauts`) stays
+  unevaluable and is still reported, exactly as before.
+
+Materialisation happens only when the persisted state is actually in hand — an insert, or
+an update whose prior row was fetched. A predicate (`multi: true`) bulk update carries no
+prior row, so its payload is left as it is rather than gaining `null`s that would
+contradict the stored rows. No code path fetches a record it did not already load.
+
+**What you may see after upgrading**
+
+- **Conditions that never fired start firing.** A hook gated on a field the payload rarely
+  carried was silently skipped; it now evaluates. This is the declaration finally being
+  honoured, but expect hooks to run on writes where they previously did not.
+- **A condition is now about the record's STATE, not about this write's diff.**
+  `record.done == true` fires on every update of a task that *is* done, not only on the
+  update that set it. A condition cannot express a transition today — the CEL scope binds
+  `record` only.
+- **Conditions guarded with `has(...)` need `!= null`.** `has(x)` asks whether the key is
+  **present**, and a declared field holding `null` is present — so
+  `has(a) && has(b) && a > b` still faults on `null > null`. Same lesson as #4649:
+
+  ```diff
+  - condition: 'has(record.spent) && has(record.budget) && record.spent > record.budget'
+  + condition: 'record.spent != null && record.budget != null && record.spent > record.budget'
+  ```
+
+  `has()` remains correct for asking whether an **undeclared** key exists.
+
+**Unchanged, deliberately:** what happens when a condition is *still* unevaluable after
+merging — it is logged at WARN and treated as `false`, as before. Whether that fallback
+should differ by hook category (a guard fails open, an audit fails silent) is a separate
+decision, tracked on its own issue.

content/docs/references/studio/action.mdx

@@ -1,7 +1,6 @@
 {
   "title": "Studio Protocol",
   "pages": [
-    "action",
     "flow-builder",
     "object-designer",
     "plugin",

content/docs/references/studio/meta.json

@@ -100,8 +100,8 @@ modes: ['preview', 'design', 'data'],
 ## TypeScript Usage
 
 ```typescript
-import { ActionContributionSchema, CommandContributionSchema, MetadataIconContributionSchema, MetadataViewerContributionSchema, PanelContributionSchema, PanelLocationSchema, SidebarGroupContributionSchema, StudioPluginContributionsSchema, StudioPluginManifestSchema, ViewModeSchema } from '@objectstack/spec/studio';
-import type { ActionContribution, CommandContribution, MetadataIconContribution, MetadataViewerContribution, PanelContribution, SidebarGroupContribution, StudioPluginContributions, StudioPluginManifest, ViewMode } from '@objectstack/spec/studio';
+import { ActionContributionSchema, ActionContributionLocationSchema, CommandContributionSchema, MetadataIconContributionSchema, MetadataViewerContributionSchema, PanelContributionSchema, PanelLocationSchema, SidebarGroupContributionSchema, StudioPluginContributionsSchema, StudioPluginManifestSchema, ViewModeSchema } from '@objectstack/spec/studio';
+import type { ActionContribution, ActionContributionLocation, CommandContribution, MetadataIconContribution, MetadataViewerContribution, PanelContribution, SidebarGroupContribution, StudioPluginContributions, StudioPluginManifest, ViewMode } from '@objectstack/spec/studio';
 
 // Validate data
 const result = ActionContributionSchema.parse(data);
@@ -122,6 +122,17 @@ const result = ActionContributionSchema.parse(data);
 | **metadataTypes** | `string[]` | ✅ | Applicable metadata types |
 
 
+---
+
+## ActionContributionLocation
+
+### Allowed Values
+
+* `toolbar`
+* `contextMenu`
+* `commandPalette`
+
+
 ---
 
 ## CommandContribution

content/docs/references/studio/plugin.mdx

@@ -63,11 +63,15 @@ export const WarnOverBudgetHook = {
   label: 'Warn On Over-Budget Project',
   object: 'showcase_project',
   events: ['afterUpdate'] as LifecycleEvent[],
-  // Guard with has(): an afterUpdate fired by a partial write (e.g. the
-  // task-rollup that only touches task_count) carries a record WITHOUT
-  // spent/budget, and CEL throws "No such key" on a bare `record.spent`.
-  // has() is the missing-key-safe macro — the hook simply skips those.
-  condition: "has(record.spent) && has(record.budget) && record.spent > record.budget",
+  // Guard with `!= null`, NOT with `has()` (#4770, same lesson as #4649). A
+  // condition is evaluated against the STORED record overlaid with this
+  // write's payload, made total over the object's declared fields — so a
+  // partial write (the task-rollup that only touches task_count) still sees
+  // spent/budget, and `has(record.spent)` is uniformly TRUE for a declared
+  // field, including one holding null. Only `!= null` actually keeps
+  // `null > null` — which CEL has no overload for — from aborting the
+  // expression.
+  condition: "record.spent != null && record.budget != null && record.spent > record.budget",
   body: {
     language: 'js' as const,
     source: "var r = ctx.result || ctx.input || {}; ctx.log.warn('project over budget: ' + (r.name || r.id || 'unknown') + ' (' + r.spent + ' / ' + r.budget + ')');",

examples/app-showcase/src/data/hooks/index.ts

@@ -0,0 +1,58 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Make a record TOTAL over an object's DECLARED fields.
+ *
+ * Shared by the two places that evaluate a CEL expression against "the
+ * record": object-level validation predicates
+ * (`validation/rule-validator.ts`, #1871 / #4649) and declarative hook
+ * `condition`s (`hook-wrappers.ts`, #4770). They used to disagree — a
+ * predicate saw a total record while a hook condition saw only the fields the
+ * current write happened to carry — which is precisely the drift this module
+ * exists to prevent: an author cannot be expected to know that the same
+ * `record.done == true` means two different things depending on which surface
+ * reads it.
+ *
+ * CEL is strict about missing keys: `record.x` on a record that does not carry
+ * the key `x` aborts the whole expression with `No such key`, which is NOT the
+ * same as reading `null`. Whether a key is carried is a property of the DRIVER
+ * (a driver that stores only written columns returns a record missing every
+ * column the write never touched), not of the data — so without this an
+ * expression's evaluability depends on storage internals the author cannot
+ * see.
+ *
+ * Scope is deliberately the object's **declared fields only**. Materialising
+ * every key an expression happens to name would paper over author typos: a
+ * `record.stauts` must stay unevaluable so it is reported (fail-closed for
+ * validation, #4649) rather than silently read as `null` and quietly answered
+ * "no violation" / "condition false".
+ *
+ * `undefined` counts as absent (not just a missing key): CEL treats an own key
+ * holding `undefined` exactly as it treats no key at all.
+ *
+ * ## Only ever call this when the record's persisted state is IN HAND
+ *
+ * On insert there is nothing to know — absence genuinely means "no value". On
+ * update it is knowable only when the prior row was actually fetched. Without
+ * it, defaulting a declared field to `null` would not be materialising an
+ * absent value, it would be FABRICATING one that contradicts the stored row.
+ * Callers decide; this function only applies the rule.
+ *
+ * ## Consequence worth knowing before writing an expression
+ *
+ * Because a declared field is always present afterwards, `has(record.<declared
+ * field>)` is uniformly TRUE (a materialised `null` is a present key holding
+ * null — CEL's own rule). `has()` therefore guards against an UNDECLARED key,
+ * not against an empty value; test emptiness with `record.x != null`.
+ */
+export function materializeDeclaredFields<T extends Record<string, unknown>>(
+  record: T,
+  fields: Record<string, unknown> | undefined | null,
+): T {
+  if (!fields || typeof fields !== 'object') return record;
+  const target = record as Record<string, unknown>;
+  for (const name of Object.keys(fields)) {
+    if (target[name] === undefined) target[name] = null;
+  }
+  return record;
+}