Merge origin/main (批 10 #4973) into claude/issue-4001-automation-batch11

Second serial sync. One conflict, the same `automation/` section as last time,
and it arrived exactly as 批 10 predicted in the paragraph it left there.

Resolution — both waves' rows kept, header and subtotal recomputed from the
SURVIVING rows rather than resolved in favour of a side:

  surviving rows  execution 13 · etl 10 · flow 1 · bpmn-interop 5 · node-executor 4
  header          44 (HEAD) / 42 (main)  ->  33 strip of 75
  subtotal        18 (HEAD) / 16 (main)  ->  7 authorable of 33

Both incoming numbers were right against their own branch and wrong against the
merge: mine counted 批 10's deletions as still present, main's counted mine.
That is the third instance in one day of the shape 批 10 wrote down — the header
CONFLICTS and gets attention, while the subtotal line conflicts with nothing and
merges clean while being wrong on both sides. The paragraph is rewritten as a
per-wave table plus the rule stated mechanically, so the next batch does not
have to rediscover it a fourth time. `check:strictness-ledger` arbitrates, and
passes.

Milestone worth noting in the ledger prose: with 批 9 + 批 10 + 批 11 merged,
`automation/`'s authorable strip is **etl.zod.ts alone** (7 sites). The other 26
are wire — including `flow.zod.ts`'s last site `FlowVersionHistorySchema`, which
is why that file still has a row while having 0 authorable left and must not be
read as unfinished work.

os-regen four-step ran in full. The driver deferred `authorable-surface.json`
and `references/integration/connector.mdx` this time (recorded in
os-regen-pending) rather than text-merging them. checkout origin/main for every
`merge=os-regen` path -> install + rebuild spec -> `check:generated --fix`
(regenerated `content/docs/references/**` only) -> assert BOTH waves survive:
批 10's control-flow/state-machine reference pages and its 21
TryCatch/Loop/StateNode/Transition authorable-surface entries coexist with this
branch's `automation/Webhook:_packageId` / `:protection` and its two pages.
The only deletions in the merged artifacts belong to main's own
`connector.rateLimitConfig` retirement (#4911/#4947), not to either batch.

Verification on the merged tree:
  check:generated 8/8 · all 8 pure audits PASS
  check:strictness-ledger: 42 open file(s) / 289 strip site(s) — counts match
  @objectstack/spec 297 files / 7474 tests · tsc --noEmit clean

Part of #4001

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ehu85kbvMcrNTUJjwxvLJ9

Author: claude

.changeset/approvals-engineless-resume-gap.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/plugin-approvals": patch
+---
+
+fix(approvals): an approval decision can no longer strand a flow run silently when no automation engine is attached (#4420)
+
+#4420's fix closed every path by which a decision could be recorded while its
+flow stayed parked — except one, and it is the one where none of the new guards
+could run. Every guard it added (`assertRunResumable`'s pre-flight, the
+`RESUME_TARGET_LOST` refusal, the `RESUME_FAILED` throw) hangs off the
+automation engine. In a process where **no engine is attached**, all of them
+were skipped by the same `typeof this.automation?.resume === 'function'`
+condition that wrapped the resume itself — so the decision was written, the
+mirrored status field advanced, and the call answered HTTP 200 with
+`resumed: false` and **nothing logged at all**. That is #4420's reported
+symptom exactly, reproduced in the one composition its fix could not see.
+
+The composition is reachable the same way the original bug was: a flow parks at
+an `approval` node in a process that has the automation service, and the
+decision arrives in one that does not (the plugin failed to init, or the host
+was recomposed between releases). The request row still carries a
+`flow_run_id` — which is the row's own declaration that a run is parked on this
+decision.
+
+**What changes.** The decision still stands. Rolling it back is not on the
+table (a human really decided, and the row is durable by then), and refusing
+every such call would break the standalone approvals compositions the
+pre-flight deliberately protects — so `finalized` and `resumed` are unchanged
+for every existing caller. What changes is that the gap is no longer silent:
+
+- it is logged at **`error`**, per the durability rule in `AGENTS.md` —
+  persisted state and runtime state disagree while nothing looks broken from
+  the outside, which is the class that rule exists for;
+- the response carries **`resumeError`**, so `resumed: false` arrives with its
+  reason and the stranded run's id instead of leaving the caller to guess
+  whether a resume was even attempted.
+
+It reuses the already-registered `RESUME_FAILED` code and the existing resume
+message shape rather than introducing a new vocabulary — the fact being
+reported (an outcome recorded whose run did not advance) is the same one.
+
+Applied at all five sites that resume a recorded outcome: `decide`, the
+revision-limit auto-rejection, `sendBack`, `resubmit`, and both branches of
+`recall` (whose revise-window path needs `cancelRun` rather than `resume`).
+
+A request that names **no** run is unaffected and stays quiet — there is
+nothing parked on it, and reporting one there would be the mirror-image
+failure that trains operators to skim `error`.

.changeset/connector-rate-limit-config-removed.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/spec": major
+---
+
+refactor(spec)!: remove `connector.rateLimitConfig` and the whole outbound rate-limit shape — the engine never existed (#4911, ADR-0049)
+
+`ConnectorSchema.rateLimitConfig` let an author declare an outbound throttle for
+their connector — `strategy`, `maxRequests`, `windowSeconds`, `burstCapacity`,
+`respectUpstreamLimits`, `rateLimitHeaders` — and nothing anywhere applied it.
+This is not the ordinary declared-but-unread case; it is a step worse:
+**there is no outbound rate-limiting engine to wire it to.** The only token
+bucket the platform owns is `packages/runtime/src/security/rate-limit.ts`, and it
+is INBOUND — the dispatcher calls `consume(key)` on a request fingerprint and
+answers 429. No connector provider (`connector-rest`, `connector-openapi`,
+`connector-mcp`, `connector-slack`) reads the key, and no seam exists that could.
+
+So a well-formed, schema-validated block told the author they had capped their
+call rate against a third party's quota, and capped nothing — the false-compliance
+class ADR-0049 exists for. With no implementation and no committed roadmap,
+`experimental` would be a promise nobody made; **absent** is the honest
+disposition. The vocabulary comes back *with* the engine, in one change
+(implementation-first — the #4834 / PR #4878 ruling for the plugin-runtime family).
+
+FROM → TO:
+
+| Removed | Replacement |
+| :--- | :--- |
+| `connector.rateLimitConfig` (key) | **none** — delete it; throttle at the connector provider or upstream gateway |
+| `ConnectorRateLimitConfigSchema` / `ConnectorRateLimitConfig` | **none** — importing either is TS2305 in v17 |
+| `RateLimitStrategySchema` / `RateLimitStrategy` | **none** — the enum had no other consumer |
+
+**Do NOT substitute `shared`'s `RateLimitConfig`.** That is the INBOUND limiter
+(`enabled` / `windowMs` / `maxRequests`) and caps the calls others make to *us* —
+the opposite direction. #4684 split the two names for exactly this confusion; the
+conversion deliberately does not rewrite one into the other, because that would
+silently change behaviour rather than losing a no-op.
+
+The retirement kit:
+
+- **Tombstone.** `ConnectorSchema` is not `.strict()`, so a plain delete would be
+  a silent strip (ADR-0104). `retiredKey()` makes the removal audible in the two
+  channels an upgrading author hits — `tsc` (the key types `never`) and the parse
+  (the prescription itself). It reaches `stack.connectors[]` and
+  `DeclarativeConnectorEntry`, which is `ConnectorSchema.superRefine(…)`.
+- **ADR-0087 D2 conversion + D3 chain step** (`connector-rate-limit-config-removed`,
+  `retiredFromLoadPath`): `os migrate meta --from 16` deletes the key from author
+  sources and stored rows replay clean. A lossless delete — the block never had an
+  effect to lose.
+- **The shape goes with the key.** `ConnectorRateLimitConfigSchema` and the
+  `RateLimitStrategySchema` enum it embedded had no other consumer, and an
+  exported schema with no consumer reads as a capability to whoever finds it
+  (#3950).
+- **#4684's rename is absorbed.** `integration/RateLimitConfig` →
+  `integration/ConnectorRateLimitConfig` and this retirement landed in the same
+  unreleased major; composed they are a plain delete, so the `RENAMED_DEFS` entry
+  is removed rather than pointing at a def this build no longer emits.
+- Baselines updated deliberately: `json-schema.manifest.json` (−2 defs),
+  `authorable-surface.json` (−6 def lines; `Connector` /
+  `DeclarativeConnectorEntry` gain `… [RETIRED]`), `api-surface.json` (−4
+  exports). `api-surface-signatures.json` is unchanged by construction — it hashes
+  each `defineX` parameter as TypeScript *prints* it, a reference
+  (`z.input<typeof ConnectorSchema >`), so key-level narrowing never reaches it.
+
+No runtime behaviour changes — that impossibility is the reason for the removal.

.changeset/health-monitor-timeout-guard-cleared.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/core': patch
+---
+
+fix(core): 健康检查的超时守卫在 race 落定时被清除,周期性检查不再堆积孤儿定时器 (#4875)
+
+`PluginHealthMonitor.performHealthCheck()` 里那条 race 的守卫由 `timeout()` armed 之后就被
+扔掉:插件的 `checkMethod` 赢下 race 之后,那根 `setTimeout` 既没 `clearTimeout` 也没
+`unref()`,带着 ref 一直挂满整个 `config.timeout`。这与 #4813 修掉的两处(内核 init/start
+守卫,PR #4874)是同一种漏法。
+
+差别在于**健康检查是周期性的**:内核那两处是启动时一次性的固定份额(4 个插件 = 8 根),这里
+则是**每个插件每一轮各留一根**,`interval` 越密、`timeout` 越长,堆得越高 —— 一个
+`interval: 30s` / `timeout: 5s` 的插件在任意时刻都挂着若干根本该在毫秒级就回收的定时器。
+今天这条还没发作,只是因为 `startMonitoring()` 目前没有被内核启动流程调用;一旦健康监控被接进
+宿主,它就是 #4813 的放大版。
+
+修法与 #4874 同形:`timeout()` 换成私有 helper `raceCheckTimeout()`,`try { await
+Promise.race(...) } finally { clearTimeout(guard) }`。
+
+**为什么是 `clearTimeout` 而不是 `unref()`。** `unref()` 让定时器不再钉住事件循环的同时,
+也让它不再是一个守卫 —— 若检查永不 settle 且没有别的东西撑着事件循环,Node 会在定时器触发
+之前退出,超时被静默吞掉。守卫必须在 race 未决期间保持 ref'd、在落定那一刻被回收,这正是
+`finally { clearTimeout(guard) }` 表达的语义。回归测试因此是三条:守卫赢不了时不留 ref'd
+定时器、连跑多轮不累积(fake timers 下计数,能识破 `unref()` 式的假修复)、以及检查真的挂住时
+超时照常上报。
+
+超时时长(`config.timeout`)一个都没动 —— 问题从来不在时长,而在没人回收。

.changeset/merge-dimension-key-unambiguous.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(service-analytics): 维度合并键不再把「未分配」并进「空白」,并改为长度前缀消歧 (#4821)
+
+`mergeByDimensions` 是每一份多查询 dataset 结果的装配缝:主查询与每个带 `filter`
+的 measure 的补充子查询在这里对齐,`compareTo` 窗口自 #4870 起也按 measure 扇出后
+经由同一个缝合并回来。这里一次键碰撞不会报错 —— 一个分组静默吸走另一个分组的数字,
+网格仍然保持看起来合理的行数和列数。
+
+**#4821 报告的机制与实际的缺陷不完全一致,先把这一点说清楚。** 原键是
+`String(row[d] ?? '')` 以一个**直接写进源码的裸 U+0001 字节**相连。裸控制字符渲染
+为空,所以 issue 正文读到的是 `join('')`,其头号复现(`['ab','c']` 与 `['a','bc']`
+同键为 `"abc"`)其实并不成立 —— 分隔符一直在,只是看不见。真正咬人的是另外两条:
+
+- `?? ''` 让**真正为 null** 的维度与**空字符串**维度键成同一个值。于是「未分配」被
+  并进「空白」:一行吞掉另一行的 measure,另一行的列则整个缺失 —— 而 #4708 的空组
+  填充随后会给它填上一个理直气壮的 `0`。一个真实计数为 3 的分组因此显示为 0。
+- 单字符分隔符只在「没有任何维度**值**包含该字符」时才无歧义。维度值是用户数据
+  (文本字段、导入记录),所以那是一个假设而非保证,且一旦不成立同样静默。
+
+**改法:长度前缀 + 显式空值哨兵。** 每段编码为 `<长度>:<值>`,`2:ab1:c` 与
+`1:a2:bc` 对任意输入都不同,不再保留任何字符、也不再有看不见的字节留给下一个读者
+误读(本 issue 正是这样被误读出来的)。null/undefined 单独走一个哨兵段,与消歧这件
+事解耦。
+
+**逐段的 `String()` 强制被刻意保留**,这与一文件之隔的 `cross-object-rebucket.ts`
+的 JSON 键不是同一笔交易:后者重新分桶的是**同一个查询**的行,一列只有一种类型,
+JSON 在那里免费且能换来真实的区分(空桶 `null` vs 字面量字符串 `"null"`)。本函数
+做的是相反的事 —— 跨**不同查询**对齐行,而驱动确实会对同一个分组返回不同的 JS 类型
+(本文件 `compareValues` 的注释即记着 "numeric strings, which is how some drivers
+return SUM results")。改用 `JSON.stringify` 会把 `1` 与 `"1"` 渲染成两个键,让今天
+能正确合并的行不再合并 —— 用一个新的静默缺陷换掉旧的,不算修好。该行为已有回归钉
+测试锁住。
+
+仅影响内部合并键,响应中的任何值都不改变。

.changeset/schema-drift-runtime-managed-index.md

@@ -0,0 +1,54 @@
+---
+"@objectstack/driver-sql": patch
+---
+
+fix(driver-sql): a fresh database no longer boots "drifted", and the drift
+detector never points `--allow-destructive` at an index the framework created
+(#4884)
+
+Booting `examples/app-showcase` on a brand-new empty SQLite file printed two
+`[schema-drift]` warnings before the server was even ready, both about the
+ADR-0048 overlay indexes the same boot had just created. Both were false, and
+one of them was dangerous:
+
+> `[schema-drift] sys_metadata: index 'idx_sys_metadata_overlay_draft' UNIQUE
+> (type, name, organization_id) carries ObjectStack's generated naming but
+> matches no declared index (orphaned) — "os migrate apply --allow-destructive"
+> to drop it.`
+
+`idx_sys_metadata_overlay_draft` is the unique index enforcing **draft-overlay
+uniqueness**. An operator following our own boot advice would have dropped a
+live data-integrity guarantee to fix a problem that did not exist — and, worse,
+learned to treat `--allow-destructive` as routine boot hygiene, which is exactly
+what makes the *next*, real drift warning dangerous.
+
+Three fixes, in the driver's detector only (no metadata declaration changed —
+`sys-metadata.object.ts` documents its four-column `indexes[]` entry as *the
+fallback shape for drivers without the runtime migration*, and that contract
+still holds for the drivers that rely on it):
+
+- **The index key is now read as written.** Introspection took the key from each
+  dialect's per-column catalogue view (`PRAGMA index_info`, `pg_attribute`,
+  `STATISTICS.COLUMN_NAME`), which describes an expression key as a NULL column
+  and nothing else. The canonical
+  `(type, name, organization_id, COALESCE(package_id,''))` overlay index
+  therefore arrived as three columns and was reported as a mismatch against its
+  own four-column declaration. SQLite and Postgres now parse the index
+  definition (`sqlite_master.sql` / `pg_get_indexdef`), MySQL reads
+  `STATISTICS.EXPRESSION` where the server has it, and `COALESCE(col, <literal>)`
+  is recognised as keying on `col` — which is what ADR-0048 uses it for: a plain
+  UNIQUE index treats NULLs as distinct, so package-less globals would not be
+  unique among themselves.
+- **Partial predicates are captured.** A `WHERE`-restricted index is something
+  `syncDeclaredIndexes` can neither create nor rebuild, so the detector no
+  longer claims authorship of one, no longer calls it orphaned, and never
+  proposes a remedy it could not undo.
+- **The driver keeps a ledger of the index DDL it executed.** An index this
+  process created through raw `execute()` — how `metadata-protocol`'s
+  `ensureOverlayIndex` issues its migration — is the framework's to manage. This
+  also covers the plain-index fallback the same migration takes on dialects that
+  reject partial indexes.
+
+Genuine drift is unaffected: an orphaned generated index, a redefined declared
+index and the #3696 legacy-unique replacement are all still detected, still
+categorised exactly as before, and still remediable through `os migrate`.

.changeset/strict-automation-control-flow-state-machine.md

@@ -0,0 +1,72 @@
+---
+'@objectstack/spec': major
+---
+
+**BREAKING** — `automation/control-flow` and `automation/state-machine` reject unknown keys (#4001 批 10, ADR-0078)
+
+Eleven authoring shapes that silently discarded undeclared keys now refuse them with a
+named surface, the offending key echoed back, and a rename or prescription. Metadata that
+used to parse "successfully" while losing the key you wrote now returns 422.
+
+**`automation/control-flow.zod.ts`** — `FlowRegionSchema`, `LoopConfigSchema`,
+`ParallelBranchSchema`, `ParallelConfigSchema`, `TryCatchConfigSchema`.
+
+**`automation/state-machine.zod.ts`** — `ActionRefSchema` (object branch),
+`GuardRefSchema` (object branch), `TransitionSchema`, `StateNodeSchema`, its `meta` block,
+and `StateMachineSchema`.
+
+## What was actually being lost
+
+A `state_machine` on an agent's `lifecycle` with `onn` where `on` was meant parsed clean
+and came back with **no transitions at all** — the declaration whose entire purpose is to
+deny undeclared transitions, silently emptied and reported valid. A `loop` config with
+`maxIteration` (singular) came back uncapped. A `parallel` branch with `label` instead of
+`name` came back unnamed.
+
+## Migration — FROM → TO
+
+Renames the rejection now suggests for you:
+
+| you wrote | write instead | on |
+|---|---|---|
+| `guard` | `cond` | a state transition (XState v5 renamed it the other way; this protocol kept `cond`) |
+| `action` | `actions` | a state transition |
+| `itemVariable` | `iteratorVariable` | a `loop` config |
+| `maxIteration` | `maxIterations` | a `loop` config |
+| `label` | `name` | a `parallel` branch |
+| `onn` / `entery` / typos | `on` / `entry` | a state node |
+
+Keys with no replacement, and what to do instead:
+
+- **`finally` on `try_catch`** — there is no `finally` region. The node's ordinary
+  out-edges run whichever way the protected region went; put the always-run steps in the
+  nodes **after** the container.
+- **`join` / `joinGateway` on `parallel`** — the join is implicit; the block continues once
+  when every branch completes. `join_gateway` is a BPMN interop node type, never a
+  `parallel` config key.
+- **`flowName` on `loop`** — that key belongs to the `map` node, which runs a subflow per
+  item. A `loop` runs an inline region: move the steps into `config.body`, or change the
+  node `type` to `map`.
+- **`name` / `label` on a region** — a `loop` body, a `try` region and a `catch` region are
+  not named; only a `parallel` branch carries a `name`.
+- **`transitions` on a state node** — a state node declares transitions as `on`, keyed by
+  event type. `transitions` is the key on the object-level `state_machine` **validation
+  rule** (`validations[].transitions`), a different declaration.
+- **`context` on a state machine** — this protocol declares only the context SHAPE, as
+  `contextSchema`. There is no key for seeding initial values, so the two are not a rename
+  of each other.
+
+## Two notes for upgraders
+
+`ActionRef` / `GuardRef` are unions, so a rejected key on their object branch surfaces as
+zod's `invalid_union` (`"Invalid input"`) with the real prescription nested one level down
+in `issue.errors[]` rather than in the top-level message. The prescription is present in
+`ZodError.message` and in REST error bodies; single-line formatters drop it.
+
+`StateNodeSchema.meta` is **closed**, not a passthrough bag. XState treats `meta` as open,
+but the hand-written `StateNodeConfig` type here declares exactly `label` / `description` /
+`color` / `aiInstructions`, nothing in the platform reads any other key, and the previous
+behaviour was not openness but strip — an authored `meta` arrived as `{}`.
+
+All three example apps (`app-showcase`, `app-crm`, `app-todo`) validate unchanged, so no
+ADR-0087 conversion accompanies this change.

content/docs/references/automation/control-flow.mdx

@@ -73,6 +73,44 @@ interop node types (`parallel_gateway` / `join_gateway` / `boundary_event`),
 
 which remain author-invisible interchange representations.
 
+## Unknown keys are rejected (#4001 / ADR-0078)
+
+Every shape below is `strictObject`. Before that they were plain `z.object`,
+
+so zod's default `.strip` applied and a key this file does not declare was
+
+**discarded in silence** — the container still parsed, still registered, and
+
+still ran, with the author's configuration simply absent. On these five
+
+shapes that silence is unusually expensive, because each one carries
+
+*control* rather than data: a swallowed `maxIterations` is an uncapped loop,
+
+a swallowed branch key is a branch that runs without what it was given.
+
+### How this relates to `validateControlFlow`
+
+`validateControlFlow` is a **sibling guard, not a key gate** — it answers
+
+"is this region single-entry / single-exit / acyclic", which no amount of
+
+key strictness can answer. The two do not overlap and cannot fight: the
+
+schema rejects undeclared KEYS, the analysis rejects malformed STRUCTURE.
+
+They do now meet at one seam, deliberately — `validateControlFlow`
+
+`safeParse`s each region slot before analyzing it, so from #4001 that parse
+
+is also where a region's undeclared key surfaces, reported as
+
+`<where>: invalid region — <the strictObject message>`. Nothing was
+
+duplicated and nothing was removed; the structural prose this guard exists
+
+for is untouched, and it simply stopped silently repairing its own input.
+
 <Callout type="info">
 **Source:** `packages/spec/src/automation/control-flow.zod.ts`
 </Callout>