Merge remote-tracking branch 'origin/main' into claude/issue-4940-admin-audit-bypass-claim

Author: claude

.changeset/auth-database-hooks-middleware-claim-corrected.md

@@ -0,0 +1,12 @@
+---
+---
+
+docs(plugin-auth): the `databaseHooks` doc comment no longer claims better-auth's adapter bypasses the ObjectQL middleware chain (#4802). The option's JSDoc in `auth-manager.ts` (and its two sibling copies — the wiring comment beside `composeDatabaseHooks`, and `AuthPluginOptions.databaseHooks` in `auth-plugin.ts`) justified "use `databaseHooks`, not an ObjectQL middleware" with a mechanism claim that no longer holds: *better-auth's adapter goes through `dataEngine` directly, bypassing the `ql.registerMiddleware` chain*.
+
+Re-verified hop by hop against `main`: `ObjectQLPlugin` registers **one** engine instance under both service names (`registerService('objectql', this.ql)` and `registerService('data', this.ql)`, and nothing else in the repo registers `data`); `AuthPlugin` passes exactly that instance to `createObjectQLAdapterFactory`; the adapter writes with a plain `dataEngine.insert(objectName, …)` — there is no bypass or skip-middleware option to pass; and `ObjectQL.insert()` wraps its body in `executeWithMiddleware()`, whose only filter is the object name. So `ql.registerMiddleware(fn, { object: 'sys_user' })` **does** fire for better-auth's writes, and so do the engine's `beforeInsert`/`afterInsert` hooks — the SCIM identity-source stamp in `auth-plugin.ts` is built on precisely that.
+
+The **rule is unchanged** — user-lifecycle invariants still belong in `user.create.after`, not in a `sys_user` middleware — but the reason is now the one that is actually true: **ADR-0093 D2**, one owner for the invariant on the one seam every creation path already flows through (self-signup, admin create-user, import, SSO JIT). The narrower fact that survives is written down instead of the false one: adapter writes carry `context.isSystem: true` (`withSystemContext`, pinned by `objectql-adapter.test.ts`), so every *authorization* middleware — security, sharing, the ADR-0092 identity write guard — early-returns by design; a middleware that gates on `isSystem` sees nothing, one that does not, runs.
+
+The stale sentence is **refuted in place rather than deleted**, because it had been copied into cloud's agent-facing docs and had already killed the middleware option in two rounds of design work there (cloud#1012, handed over as cloud#1022). A reader arriving from one of those copies needs to see the claim named and corrected; a silent deletion would leave them assuming the framework comment is the stale one.
+
+Comments only — no runtime behaviour changes, nothing released.

.changeset/dead-scan-roots-hard-error-three-checks.md

@@ -0,0 +1,14 @@
+---
+---
+
+Tooling-only: three more `scripts/check-*.mjs` gates now fail, by name, when a declared scan root cannot be resolved (#4930). Releases nothing — no package changes.
+
+Same shape as #4916/#4934, in three more scripts: a walker that opens with `try { readdirSync(dir) } catch { return out; }` (or `catch { return []; }`) cannot distinguish "this root is clean" from "this root was never opened", because both produce zero findings. Each script now resolves every declared root up front and fails with the root's name and reason ("does not exist" / "exists but is not a directory") before drawing any conclusion from the scan, and the swallows inside the walks are gone — an error mid-walk means the corpus was only partly read, which must not print as a clean pass either.
+
+- `check-single-authz-resolver.mjs` — `SCAN_ROOTS` (`packages/`). The duplicate-resolver scan was genuinely vacuous on a dead root; the script only went red by luck, because both `DELEGATORS` happen to live under that same root, so it reported "Delegator missing" for the wrong cause. Move a delegator, or add a second scan root, and the vacuous scan goes fully silent.
+- `check-startup-registry-verdict.mjs` — the `packages/` scan root. The old `existsSync` guard accepted a *file* and then blamed the empty corpus; and one level in, a directory the walk could not stat shrank the corpus while `files.length` stayed non-zero, so the loud empty-corpus guard never fired.
+- `check-driver-conformance.mjs` — `DRIVERS_DIR`, `CASE_SETS_DIR`, and each driver's `src/`. DISCOVERED/CLASSIFIED did catch a dead root, but as a *consequence* naming the wrong cause: a renamed `packages/spec/src/data` printed five "CASE_SETS names X, which <file> no longer exports" errors, which reads as five deliberate deletions rather than one directory that moved.
+
+No whitelist and no `optional: true` flag in any of the three, deliberately — every one of these roots is a git-tracked directory with tracked files, so no checkout that can run these gates at the repo root is legitimately missing one. An optional marker would be a supported way to silence the failure instead of fixing the rename: the empty `catch {}`, spelled politely.
+
+Each proof is bidirectional and permanent rather than a one-off in the PR description: every script's `--self-test` now renames a root away mid-run and requires red naming that root (and not the survivors), replaces one with a file and requires the `not a directory` verdict, dangles a symlink inside the walk and requires the error rather than a smaller corpus, then restores everything and requires green again. `check-single-authz-resolver.mjs` had no self-test at all and gained one, with its two original invariants driven over a real temporary tree; `package.json` chains `--self-test &&` into `check:authz-resolver` to match the other ten `check:*` entries.

.changeset/engine-double-delete-contract.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/objectql": minor
+---
+
+feat(objectql): export the delete-dispatch contract so test doubles can be pinned to it (#4550)
+
+A test double that is **looser** than the implementation it replaces converts a
+green suite into no suite at all — silently, and on exactly the paths a double
+was introduced for, which are the paths that were hard to test, which are
+usually where the contract is densest. #4434 is the worked example:
+`DELETE /api/v1/sharing/rules/:idOrName` answered 500 for every rule and both
+address forms it advertises, from the day it was written, while
+`deleteRule drops rule + all its grants` asserted success against it the whole
+time — against a fake engine whose `delete` accepted the one call shape
+`ObjectQL.delete` refuses.
+
+`ObjectQL.delete`'s dispatch decision now lives in one exported place instead of
+being re-derived by every fake:
+
+```ts
+import { assertEngineDeleteDispatch } from '@objectstack/objectql';
+
+async delete(object: string, options?: any) {
+  assertEngineDeleteDispatch(options);   // refuses what a real server refuses
+  …
+}
+```
+
+New exports, all pure and side-effect free:
+
+- `resolveEngineDeleteDispatch(options)` → `{ kind: 'by-id', id }` |
+  `{ kind: 'multi' }` | `{ kind: 'reject', message }` — what the engine will do
+  with this call, without doing it.
+- `assertEngineDeleteDispatch(options)` — throws exactly what the engine throws
+  on `reject`, returns the dispatch otherwise. This is the line a fake engine's
+  `delete` opens with.
+- `scalarDeleteId(options)` — the SCALAR `where.id` or `undefined`. The half a
+  hand-written mirror drops: `where: { id: { $in: [...] } }` looks like an id
+  and is a multi-row predicate, so the engine rejects it without `multi`.
+- `ENGINE_DELETE_REJECT_MESSAGE`, `ENGINE_DELETE_DISPATCH_CASES` — the message
+  and the shared conformance case-set, the same role
+  `packages/spec/src/data/*-conformance.ts` plays for drivers.
+
+`ObjectQL.delete` itself reads `resolveEngineDeleteDispatch`, so a double that
+imports it cannot be looser than the engine, ever — that is the property, and
+it is the one a hand-mirrored `if` can only have until somebody edits one side.
+No runtime behaviour changes: the same three verdicts, over the same inputs,
+proved case-by-case against the real engine in
+`engine-delete-dispatch.test.ts`.
+
+Repo-side, `pnpm check:engine-double-contract` (wired into `lint.yml`) finds all
+39 fake ObjectQL engines in the repo, holds new ones to this predicate, and
+keeps the 30 not yet converted in a measured, shrink-only baseline.

.changeset/null-guard-surface-coverage.md

@@ -0,0 +1,62 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): null-guard 闸门覆盖 `requiredWhen`,其余各面按"绑定是否全量"逐一定案 (#4811)
+
+#4763 的 null-guard 闸门只接了两面(对象校验规则、生命周期 hook `condition`),
+其余各面留作"待定"。本次把"待定"收敛成一条**可判定的判据**,并按它逐面定案 ——
+一个只覆盖部分面、又没有任何东西说出这件事的闸门,正是这一族缺陷本身的形状。
+
+## 判据:记录绑定是否对已声明字段**全量**
+
+这不是口味问题,也不是"这个谓词是不是 CEL"。实测 `@marcbachmann/cel-js`,两种绑定
+下的语义**恰好相反**:
+
+| 谓词 | 全量绑定 `{a: null}` | 稀疏绑定 `{}` |
+|:--|:--|:--|
+| `has(record.a)` | `true` ← 陷阱 | `false` ← 真守卫 |
+| `record.a < record.b` | FAULT `no such overload` | FAULT `No such key: a` |
+| `record.a != null` | `false` ← **修法有效** | FAULT `No such key: a` |
+
+即:全量绑定下 `has()` 恒真而无用、`!= null` 是解药;稀疏绑定下 `has()` 恰恰是正确的
+守卫,而 `!= null` **自身就会 fault**。把闸门指向一个稀疏绑定的面,等于判红正确的元数据、
+并给出一个会把它改坏的"修法" —— 比不覆盖更糟。所以:**只有绑定全量的面才可以接入。**
+
+## 纳入:字段 `requiredWhen`
+
+议题没有列出这一面,而它恰恰是唯一满足判据的:`evaluateValidationRules` 用与对象校验
+规则**同一个** `materializeDeclaredFields` 合并记录来求值 `requiredWhen`。
+
+它也是几个已覆盖面里失败得最安静的一个:`requiredWhen` 谓词 fault 时是 **fail-open** ——
+`rule-validator.ts` 记一行 `failed to evaluate — skipped` 就跳过,字段于是**从未真正必填**,
+写入照常通过。校验规则至少自 #4761 起是 fail-closed 的拒绝。因此报错文案按面区分后果:
+"被跳过、字段从未必填"与"写入被 fail-closed 拒绝"是两个相反的故障,作者需要知道自己
+碰到的是哪一个。
+
+## 排除,且各自留下可引用的理由
+
+- **action `visible` / `disabled`**:谓词确实走真 CEL(裸串经 `ExpressionInputSchema`
+  规范成 `{dialect:'cel'}` 信封,渲染器保留它),fault 也确实 fail-closed —— 陷阱在这一面
+  是真的。但绑定是客户端已取到的那条记录(详情读取,或只带列表视图投影列的一行),
+  `objectui` 这条路径上不存在任何物化步骤。稀疏绑定下 `!= null` 是错的修法。要覆盖它,
+  得先决定是否把该绑定做成全量 —— 那是平台契约改动,不是 lint 改动。
+- **flow / edge `condition`**:议题记的理由(扁平作用域下裸标识符可能是 flow 变量)对本
+  模块**不成立** —— 它只解析 `record.<f>` / `previous.<f>`,从不解析裸标识符,而引擎无
+  条件绑定这两个根。真正的阻碍还是全量性:`record-change-trigger.ts` 把记录播种为
+  `{ ...inputDoc, ...after }`,没有 `materializeDeclaredFields`,所以写入未提及的已声明列
+  是**缺键**而非 null,`!= null` 会和它本要守卫的比较一样 fault。
+- **字段 `readonlyWhen`**:与 `requiredWhen` 同一个字段、相反的结论 —— 它由
+  `stripReadonlyWhenFields` 求值,那里合并的是 `{ ...previous, ...data }`,从不物化。
+- **`Field.formula`**:按产品判断排除,而非按本判据。formula 是 `value` 角色、天然可空,
+  `guard ? value : null` 是被祝福的写法(#3306)。是否强制守卫会改变"作者被允许写什么",
+  该由维护者决定,不是一个接线缺口。
+
+判据、实测表与逐面台账写在 `validate-null-guards.ts` 的模块注释里,每条排除在它对应的
+调用点也留了注释,并各配一条断言钉住。
+
+## 顺带修正:`field '?'`
+
+诊断的字段名此前走 `Object.values(fields)`,把**名字键**丢掉了 —— 而名字键正是
+`Field.text({…})` 这种(最常见的)写法产生的形状,于是这类对象上的每条字段级诊断都定位在
+`field '?'`。名字只出现在 `where` 里时还能忍;现在报错正文要告诉作者改哪个字段,就不能忍了。

.changeset/objectui-pin-freshness-gate.md

@@ -0,0 +1,4 @@
+---
+---
+
+ci(release): add the objectui pin-freshness gate (#3340 P0). `scripts/check-objectui-pin-fresh.mjs` fails when `.objectui-sha` is not objectui `main` (or a named `--ref`), naming the commits ahead and the `.changeset/*.md` files declared after the pin — the blind spot that dropped four frontend changes, two of them `minor` features, from the v16 release page. Wired as `Console Pin Freshness` in `.github/workflows/objectui-pin-freshness.yml`: it runs on every PR so the context can be required in branch protection, but blocks only on the Version Packages / release PR. Distinct from ci.yml's `Console Pin Gate` (#4290), which proves the pin still *builds* rather than that it is still *current*. Tooling and CI only; releases nothing.

.changeset/unknown-key-strictness-automation-node-config.md

@@ -0,0 +1,67 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: reject unknown keys on the flow-node config contracts (#4001 批 9)
+
+The first `automation/` wave of the 2026-08-03 "necessary-and-complete"
+ruling. Fourteen strip sites across three files close, and `automation/`'s
+remaining-strip count drops 67 → 53 (authorable 41 → 27).
+
+- **`automation/io-node-config.zod.ts`** — `NotifyConfigSchema`,
+  `HttpConfigSchema`.
+- **`automation/builtin-node-config.zod.ts`** — the CRUD quartet
+  (`get_record` / `create_record` / `update_record` / `delete_record`),
+  `ScreenConfigSchema`, `ScreenFieldConfigSchema` and its `options` item,
+  `MapConfigSchema`.
+- **`automation/schemaless-node-config.zod.ts`** — `ScriptConfigSchema`,
+  `SubflowConfigSchema`, `DecisionConfigSchema`, `DecisionConditionSchema`.
+
+The deliberately-open `FlowNodeSchema.config` SLOT is unchanged — ADR-0018
+keeps `node.type` open so plugins contribute their own executors, and closing
+the slot would close that extension point. What is closed is the per-node-type
+contract *inside* it.
+
+**Why the third file is different.** `registerFlow()` already hard-rejects
+undeclared config keys against a node's descriptor `configSchema` (#4277), and
+`script` / `subflow` / `decision` publish no descriptor `configSchema` — so
+that walk skips them by construction. Until now those three had **no**
+unknown-key enforcement at any layer. For them this is the first gate, not a
+second one.
+
+**Migration.** Every key now rejected was previously stripped and had no
+runtime effect, so removing or renaming one never changes behaviour. All three
+shipped example apps were re-validated after the change and no stored shape
+needed an ADR-0087 conversion (160 flow nodes walked, 52 carrying one of these
+contracts, 0 rejections). The rejections carry their own prescriptions:
+
+- `notify`: `to` → `recipients`, `subject` → `title`, `body` → `message`,
+  `url` → `actionUrl`, `source: { object, id }` → `sourceObject` + `sourceId`.
+- CRUD: `object` → `objectName`, `filters` → `filter`,
+  `fieldValues` → `fields`, `recordId` → a filter VALUE
+  (`filter: { id: '{record.id}' }` — no CRUD executor has ever read a
+  `recordId` key), and on `update_record` / `delete_record` `outputVariable`
+  is a documented absence, not a typo — read the row back with a following
+  `get_record`.
+- `screen`: `object` → `objectName`, and on a field item
+  `visibleIf` → `visibleWhen`.
+- `map` / `subflow`: `flow` → `flowName`. `subflow`'s `timeoutMs` belongs on
+  the NODE (`FlowNodeSchema.timeoutMs`), not in its config.
+- `script`: `functionName` → `function`, `input` → `inputs` (the singular
+  stays canonical on `connector_action`'s `connectorConfig.input` — do not
+  "fix" that one). The five `actionType`-branch keys keep their existing
+  `retiredKey()` tombstones.
+- `decision`: `config.condition` (singular) is **not** renamed to
+  `conditions`. Nothing reads it on a decision — it is the trigger gate on a
+  `start` node and inert everywhere else (#4414) — and declaring branches here
+  *and* on the out-edges is the double-declaration #4414 was filed for.
+  Branching lives on the out-edges. On a decision BRANCH the predicate slot is
+  `expression`, so `condition` → `expression` there.
+- decision branch `target`: a VIRTUAL designer column projected from the
+  node's out-edges, never stored — route by matching the branch `label` to an
+  out-edge `label`.
+
+For a key rewritten at load by an ADR-0087 D2 conversion, reaching this
+rejection means the config carries BOTH spellings: `renameConfigKey` leaves a
+shadowed alias in place rather than clobbering the canonical winner, so the
+retired twin is dead weight and should be deleted.

.github/workflows/lint.yml

@@ -289,6 +289,23 @@ jobs:
       - name: Published-files whitelist guard
         run: pnpm check:published-files
 
+      # Engine test-double contract gate (#4550, from #4434). A test double
+      # LOOSER than the implementation it replaces turns a green suite into no
+      # suite at all, silently, on exactly the paths a double was introduced
+      # for. #4434 is the worked example: DELETE /sharing/rules/:idOrName
+      # answered 500 for every rule and both address forms from the day it was
+      # written, while `deleteRule drops rule + all its grants` asserted success
+      # against a fake engine that accepted the one call shape ObjectQL.delete
+      # refuses. This holds every fake ObjectQL engine's `delete` to the real
+      # dispatch predicate — imported from @objectstack/objectql, not
+      # hand-mirrored, so it cannot drift — with the pre-existing fakes in a
+      # shrink-only, measured baseline. Static AST only, so it needs no build
+      # and belongs in this job. Runs its own --self-test first: the detector
+      # can be broken while every fake is fine, and a scan that quietly stops
+      # matching would report OK while reading nothing (#4868's family).
+      - name: Engine test-double contract gate
+        run: pnpm check:engine-double-contract
+
   typecheck:
     name: TypeScript Type Check
     runs-on: ubuntu-latest