Merge remote-tracking branch 'origin/main' into claude/issue-5273-hook-input-contract-prose

Author: claude

.changeset/client-delete-result-success.md

@@ -0,0 +1,98 @@
+---
+"@objectstack/client": major
+"@objectstack/cli": patch
+---
+
+fix(client)!: `DeleteDataResult` declares the schema it names — `success`, not `deleted` (#5638)
+
+`DeleteDataResult` — the return type of `client.data.delete()` and of the
+project-scoped `client.project(id).data.delete()` — carried the comment
+`Spec: DeleteDataResponseSchema` above a declaration that contradicted it:
+
+```ts
+/** Spec: DeleteDataResponseSchema */
+export interface DeleteDataResult {
+  object: string;
+  id: string;
+  deleted: boolean;   // ← the schema declares `success`
+}
+```
+
+`DeleteDataResponseSchema` (`packages/spec/src/api/protocol.zod.ts`) declares
+`{ object, id, success }`. `deleted` has never been declared by any schema, and
+no server path has ever returned it on `/data/:object/:id`.
+
+**The old key was never readable at runtime — this rename reveals a defect, it
+does not break working code.** Both `delete` surfaces are pure `unwrapResponse`
+/ `_unwrap` passthroughs: the SDK returns the server's body untouched, so this
+interface is a *claim* about the wire, never a rewrite of it. The claim was
+false in the one direction that matters — the compiler endorsed the wrong
+spelling:
+
+```ts
+const r = await client.data.delete('task', id);
+if (r.deleted) { … }   // compiled; `undefined` at runtime; branch never taken
+if (r.success) { … }   // rejected by the compiler; correct on the wire
+```
+
+## What to change
+
+`r.deleted` → `r.success`. That is the whole migration. Nothing about the
+request, the route, the status codes or the error shapes changes, and no server
+needs upgrading: the value you are now allowed to read is the one that was
+already arriving.
+
+⛔ **Do not write `r.success ?? r.deleted`.** There is one producer shape, and a
+consumer that accepts two spellings is the shape contract-first exists to
+prevent — the same ruling #5581 applied on the producer side. No deprecated
+`deleted?: boolean` transition key ships for the same reason; a transition
+period is for keys that *worked*, and this one never did.
+
+## Why the type was wrong on every deployment, not just some
+
+The protocol path (`deleteData`) has always answered `success`. #5581 / PR
+#5641 brought the ObjectQL fallback — the path a slim assembly without
+`MetadataPlugin` takes — to the same shape. So before that fix the declaration
+was wrong on ordinary deployments and accidentally right on slim ones; after
+it, both paths answer `{ object, id, success }` and the declaration was simply
+wrong everywhere. The consumer-side correction had to follow the producer, not
+lead it.
+
+## `os data delete` was reading the phantom key too
+
+`packages/cli/src/commands/data/delete.ts` built its `--format json` / `--format
+yaml` payload with `deleted: result.deleted`. That evaluated to `undefined`, and
+`JSON.stringify` drops undefined values — so the `deleted` key the command has
+always declared **never appeared in a single run**. It now carries
+`result.success`, the server's own verdict.
+
+Observable change: `os data delete --format json` gains `deleted: true` (YAML
+likewise) on a successful delete. The key name stays `deleted` deliberately —
+it is the CLI's output key, not the protocol's, and the payload's top-level
+`success` already means something different (the CLI envelope's "the command
+completed"). Conflating the two is the hazard #5641 called out when it noted
+that `body.success` and `body.data.success` are different facts. Scripts
+reading `.deleted` from this command were reading `undefined` before and get a
+boolean now; nothing that worked stops working.
+
+## Downstream
+
+`objectui`'s `ObjectStackDataSource.delete()` is a live victim of the old
+declaration — it guards `emitMutation` on `result.deleted`, so the delete
+mutation event has never fired against a real server and the method returns
+`undefined` where it declares `boolean`. Its own suite stayed green because the
+fixture mocks `{ deleted: true }`, a body no server produces. Filed as
+objectstack-ai/objectui#3412, which is blocked on this package publishing —
+its fix is a type unblock, not a behaviour change, since `success` is already
+what arrives.
+
+## Pins
+
+`packages/client/src/data-delete-result-shape.test.ts` asserts mutual
+assignability between `DeleteDataResult` and the spec's `DeleteDataResponse`,
+so a rename on either side (or a re-added optional `deleted`) fails
+`check:test-typecheck`. `client.hono.test.ts` gains the delete case this live
+server suite never had: a real DELETE over HTTP whose body is read as
+`deleted.success` and whose key set is asserted literally — `z.object` strips
+unknown keys, so a passing parse alone cannot prove no stray `deleted` rode
+along.

.changeset/connector-degrade-cause.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/service-automation": patch
+---
+
+fix(service-automation): connector 降级路径的两条日志改用结构化 `meta`,message 保持单行 (#5636)
+
+## 接缝
+
+`degradeConnectorInstance`(#3017 的降级/重试路径)有两条记录报告的是**外来**失败,却把
+它插进了日志 message —— 与 #5048(flow 绑定)、#5575(`reconcileDeclaredConnectors` 的
+`fail()`)同一类,是那两单范围之外的第三个接缝:
+
+- **husk 注册失败**(`warn`):`err` 来自 `engine.registerDegradedConnector` →
+  `ConnectorSchema.parse`,catch 自己的注释就写着「the entry's def no longer parses」,
+  也就是说这里预期接到的正是 `ZodError` —— 它的 `.message` 是 issue 数组的多行 JSON
+  dump,第一行只有一个 `[`。
+- **降级公告**(`error`):文本是 `ConnectorUpstreamUnavailableError.message`,由第三方
+  provider factory 构造(ADR-0097 明确鼓励第三方去写)。spec 只定义错误类、不约束文本,
+  所以上游 SDK 的多行失败会原样落在这里。
+
+## 危害:这条 `warn` 的下游与 #5575 的 `error` 不同(实测)
+
+`ObjectLogger` 把 `warn` 送 stdout、`error`/`fatal` 送 stderr,而 `serve` 的启动静默窗口
+只包了 `process.stdout.write`。#5575 的接缝全是 `error`,所以那一单的结论是「启动缓冲根本
+看不到」;这一条不同,而且差别是**测出来**的,不是推的:
+
+- 它是 `warn` → stdout,缓冲**确实**看得到;
+- 它在**冷启动**就会跑 —— `materializeDeclaredConnectors(ctx, { fatal: true })` 遇到上游
+  不可达是降级、不是抛错 —— 而窗口此时正开着(`serve` 在 config 加载前接管 stdout,直到
+  banner 打印才恢复);
+- `BootLogCapture.offer()` 只在 `classifyBootLogLine` 能在该物理行上找到 `<ts> <LEVEL>`
+  头时才保留它,所以插值 dump 的每一条续行是被**直接丢弃**,不只是难解析。
+
+对一份 13 行的插值 ZodError 实测:写出 13 行物理行,缓冲保留 **1** 行(那条止于 Zod `[`
+的头行)、丢弃 **12** 行 —— 唯一被留下的那行不含任何事实。这正是 cloud#971 的原始形态。
+`error` 那一条走 stderr,不经缓冲,危害是 #5575 那一串按行消费者(文件 sink、
+`docker logs`/journald 送采集、`grep ERROR`):一条诊断散成 N 个无法归属的碎片。
+
+## 改法
+
+两条都复用同包 `thrown-cause-diagnostics.ts` 的 `describeThrownForLog`(#5572/#5575 落地):
+message 是不含换行的自足句子,cause 走 logger 的结构化 meta。位置按 `Logger` 契约区分,
+并且是核对源码后确认的而非照抄:`warn(message, meta?)` 没有 `Error` 位,cause 就在**第二**
+参;`error(message, error?, meta?)` 的 cause 在**第三**参(第二参塞原始 error 会让每次重试
+的记录都附带完整堆栈)。
+
+## 刻意没有改的一件事
+
+`degradedReason` —— `GET /connectors` 展示的、以及 `connector_action` 被拒时引用的那段文本
+—— 仍然逐字保留 provider 自己的 message,包含换行。它是人透过 JSON 读的字段,不经按行切分
+的消费者;重塑它属于另一次契约变更。因此调用点同时传 `reason`(那段文本)与 `cause`(抛出值
+本身):前者喂 husk 与重试簿记,后者只喂日志记录。测试双向钉住了这个分离。

.changeset/doctor-optional-package-load-boundary.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os doctor` no longer treats a broken `@objectstack/cloud-connection` install as "not installed" (#5644)
+
+`readInstalledPackageEntries()` reached the installed-package ledger through a
+dynamic `import('@objectstack/cloud-connection')` whose `catch` meant "the
+optional package is not installed". That is right for one of the two things it
+caught:
+
+- **The specifier does not resolve** — the optional package really is not
+  there. Silence is correct and unchanged: `os doctor` must run to completion in
+  a checkout that never had it.
+- **The package is installed and will not load** — a pruned or unbuilt `dist/`,
+  an interrupted install, an artefact that throws while it evaluates, a
+  transitive dependency missing under it. It threw too, so it was answered with
+  the same silence.
+
+The ADR-0120 D5e unique-scope advisory then saw "no installed packages", found
+nothing to report, and the run printed:
+
+```
+  ✓ Unique scope          No unconfirmed installation-wide uniques for this 'isolated' environment
+```
+
+Measured: with the package present-but-unloadable and a ledger declaring an
+installation-wide `unique`, that line was printed and the finding appeared
+nowhere, `--verbose` included. It is the same false PASS #5412 removed at the
+`readdir` boundary and #5413 at the entry boundary, one boundary further up —
+and `os serve`, loading the same package in the same directory, has always named
+the failure out loud.
+
+The two states are now separated by **resolution**, not by the `import()` having
+thrown (`isModuleNotFoundError()` first — an error that is not a module-not-found
+error came from the package itself, so it is present by definition; then
+`import.meta.resolve()`, which answers "is the package there" without stating its
+entry file, unlike `createRequire().resolve()`). Only the genuinely-absent half
+is silent. The other prints an ordinary `HealthCheckResult` through the same
+renderer every other check uses:
+
+```
+  ⚠ Unique scope          Could not load the installed-package ledger reader (installed packages
+                          NOT checked for installation-wide uniques) — Cannot find module …
+```
+
+**Warning, not error**, and the exit code is unchanged, matching its two
+siblings: the environment still runs; what broke is doctor's ability to see part
+of it. The cause is quoted from the thrower, and `--verbose` expands it together
+with the remedy — reinstall, or build the package in a monorepo checkout.
+
+The row is **not** conditional on `.objectstack/installed-packages/` existing.
+Doctor cannot honestly say a ledger is absent when the constant naming the
+ledger's location is an export of the package that would not load.
+
+One consequence worth stating: in a monorepo checkout where
+`packages/cloud-connection` has not been built, `os doctor` under the `isolated`
+posture now prints this warning instead of a clean bill. That state is exactly
+what sent #5612 chasing a report face that had never regressed.

.changeset/flow-time-relative-descriptor-lint.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): report a `config.timeRelative` descriptor the sweep will refuse, at authoring time (#5496)
+
+A flow start node declaring `config.timeRelative` got **zero** authoring-time
+diagnostics when its descriptor could not parse. The two rules that look at the
+slot each looked at something else: `lint-flow-patterns` decides "this is a
+time-relative flow" from `timeRelative != null` alone (never the shape), and
+`validate-flow-trigger-readiness`'s existing check reads only
+`timeRelative.object`, to compare it against the stack's objects. So
+
+```ts
+config: { timeRelative: { object: 'task', field: 'due_at', offsetDays: -1 } }
+```
+
+— three separate schema violations: `dateField` missing, `offsetDays` declared
+as an int **array** and written as a scalar, and `field` an unrecognized key —
+passed `os validate` silently. `TimeRelativeTriggerSchema` does reject it, but
+the only place that schema ran was **bind time**, inside
+`TimeRelativeTriggerPlugin.start()`, which warns and returns: the sweep is never
+installed, the flow reports itself armed, and the author's sole feedback is one
+line in a server log. For an AI author that line is outside the feedback loop
+entirely; `os validate` is what it reads.
+
+**New rule — `flow-time-relative-descriptor-invalid` (warning).** A start node
+whose `config.timeRelative` is present runs that same schema at authoring time,
+and a failure is reported naming `config.timeRelative` with the schema's own
+issue list forwarded — so the diagnostic carries the missing key, the wrong type,
+and, for an unrecognized key, the "did you mean" the schema already computes
+(`field` → `dateField`) plus its wrong-layer guidance (a `schedule` written
+*inside* the descriptor is told it belongs beside it). The list is rendered
+exactly as the bind-time warning renders it, so the two channels tell one story.
+
+Nothing is shifted except **when** the schema runs. No shape knowledge is
+re-implemented in the rule and no consumer-side tolerance is added: the verdict
+and every word of its wording remain `TimeRelativeTriggerSchema`'s, so the rule
+tracks the descriptor's contract as it evolves instead of drifting from a second
+copy of it.
+
+The rule and the existing object-name check decide different facts and cannot
+report the same one twice — only the stack knows whether an object name exists,
+and only the schema knows the descriptor's shape. A descriptor wrong in both ways
+gets both findings, at their own paths. Canonical descriptors are unaffected:
+every one shipped in the repo (the showcase `Task Due Reminder`, the
+`content/docs` examples) parses, so this adds no diagnostic to existing apps.

.changeset/flow-unbounded-bulk-write-lint.md

@@ -0,0 +1,70 @@
+---
+"@objectstack/lint": patch
+---
+
+feat(lint): warn when a `multi: true` delete/update is bounded by nothing — the declared whole-object write (#5482)
+
+A `delete_record` / `update_record` node that declares `multi: true` with no
+`filter` (or an empty one) writes the **whole object**: the executor forwards
+`where: {}` plus the bulk intent, the data engine classifies that as a legal
+`multi` call, and it lands on `driver.deleteMany` / `driver.updateMany` with no
+predicate. Every row, every run.
+
+That path only became authorable with #5393, which gave these nodes a bulk
+declaration at all — before it the executor never passed `options.multi`, so the
+engine refused every predicate write (`Delete requires an ID or
+options.multi=true`) and "empty filter + bulk intent" was not a reachable shape.
+Since then it has been reachable and **silent**: `filter` is optional, `multi` is
+optional, nothing related the two, and the author's only feedback was the step's
+`acted` row count — reported after the rows were gone. The common way to get
+here is not malice but an omission: declaring the bulk intent and forgetting the
+constraint.
+
+`os validate` / `os build` now report `flow-multi-write-unfiltered` for it:
+
+```
+flow 'nightly_purge' · node 'purge' (delete_record)
+  declares `multi: true` with no `filter` key — this is a WHOLE-OBJECT write,
+  by declaration: every row of 'lead' is deleted on every run. …
+```
+
+**A warning, not a gate.** An explicit whole-object purge is something the
+platform grants on purpose — the data engine's own dispatch case-set lists "bulk
+intent with no predicate at all" as a valid call — so the shape has a legitimate
+reading and the run-time path stays open. What was missing was only that the
+author hears about it *before* the rows go. For the same reason the fix is not a
+schema `refine`: forbidding the shape would delete an intent the engine grants.
+
+Two ways to satisfy the warning: write the constraint you mean into `filter`
+(the bounded-bulk reference shape is app-showcase's `showcase_inquiry_purge`), or
+confirm that emptying the object is the intent and keep it.
+
+**It does not duplicate the #3810 run-time guard, which judges a different
+fact.** That guard refuses a node when a condition the author *wrote*
+interpolated to nothing (`{record.ownr}` — a typo — leaving `{}`), and it is
+deliberately keyed on "a written condition is gone" rather than on "the filter is
+empty", because losing one of two conditions also widens the blast radius. So:
+
+| fact                          | judged by          | when      | verdict |
+|-------------------------------|--------------------|-----------|---------|
+| a written condition vanished  | #3810 filter guard | run time  | refuse  |
+| no condition was ever written | this rule          | authoring | warn    |
+
+A node with `filter: { owner: '{record.ownr}' }` is silent for this rule (a
+condition *is* written) and refused by that one; a node with no `filter` at all
+is warned about here and — correctly — allowed there. The diagnostic names the
+run-time guard so the two are not mistaken for one check.
+
+Reported at every nesting depth, which matters because a scheduled sweep whose
+per-item work sits in a `loop` body is the standard janitor shape: a finding
+inside a region carries the region scope (`flow 'x' · loop 'sweep' body · node
+'purge' (delete_record)`), on the traversal #5383/#5635 added to this family.
+
+Deliberately out of range: an empty **combinator** array (`{ $and: [] }`,
+`{ $or: [] }`). #5322/#5134 ruled those and every driver implements the ruling —
+empty `$and` is TRUE (so it *is* a whole-object write), empty `$or` is FALSE (so
+it matches nothing and must never be warned about) — but telling them apart
+requires the boolean-identity reduction, which already exists producer-side in
+each driver. A hand-written fourth copy inside a linter is how a scan and a
+validator come to answer with two different predicates, so that case is tracked
+separately instead.