@objectstack/plugin-approvals 17.0.0-rc.0 → 17.0.0-rc.2

package/CHANGELOG.md

@@ -1,5 +1,868 @@
 # @objectstack/plugin-approvals
 
+## 17.0.0-rc.2
+
+### Minor Changes
+
+- 2826d1e: fix(automation,approvals): an approval decision can no longer succeed while its flow stays parked (#4420)
+
+  A flow paused at an `approval` node, a deploy, then an approver clicking
+  Approve: the request row flipped to `approved`, the UI toasted success — and
+  the flow never moved. No next-stage request, no error, the record's mirrored
+  status frozen mid-workflow. Approval flows pause for days by design, so a
+  restart mid-flight is the normal case: every release could quietly zombify
+  every in-flight approval, with the approvers none the wiser.
+
+  Durable suspended runs (#1518) had shipped and were not the missing piece. Two
+  other things were.
+
+  **The wiring could enable a store over a table nobody had created.** Object
+  registration and store activation resolve different services in different
+  phases — `manifest` at `init()`, `objectql` at `start()` — and the plugin
+  declared no ordering. Composed ahead of ObjectQL, `init()` found no `manifest`,
+  warned, and continued; `start()` then attached the DB-backed store anyway. Every
+  suspend failed with `no such table: sys_automation_run` into a log line nobody
+  read, pauses silently stayed in memory, and the next restart lost them all.
+  Now: `AutomationServicePlugin` declares `optionalDependencies:
+['com.objectstack.engine.objectql']` (order-if-present, per ADR-0116 — an
+  engine-less kernel must still boot); a registration missed at `init()` is
+  retried at `start()`, which still lands before ObjectQL's schema sync; the
+  store is never attached when registration did not happen, and says so at
+  **error** level instead of warning; the table is probed once at boot so a
+  broken setup surfaces there rather than one failed write at a time; and a
+  failed durable write of a paused run is logged at error — it is data loss in
+  waiting, not a warning.
+
+  **A reported resume failure read as success.** `AutomationEngine.resume()`
+  answers a lost run by _returning_ `{ success: false }`, never by throwing.
+  `ApprovalService` discarded that return value, and `decide()` counted only a
+  thrown error as failure — so a decision against a dead run came back
+  `resumed: true`, HTTP 200. Resume failures are now classified
+  (`RUN_NOT_FOUND`, `STORE_UNAVAILABLE`, `RESUME_IN_PROGRESS`, joining
+  `PERMISSION_DENIED` / `INVALID_SIGNAL`), so a run that is gone for good is
+  distinguishable from a store that is merely unreachable, and the raw resume
+  route maps them to 404 / 503 / 409.
+
+  Approvals acts on them. A new `AutomationEngine.hasSuspendedRun(runId)` — which
+  reads the suspension store, unlike `getRun()`, and throws rather than answering
+  `false` when the store is unreadable — pre-flights every flow-advancing
+  operation (`decide`, `sendBack`, `resubmit`) **before its first write**, so the
+  zombie half-state is never created rather than merely reported: the decision
+  fails with `RESUME_TARGET_LOST` (HTTP 409) and the request stays actionable. A
+  resume that fails after the decision is durable can no longer be undone, but it
+  now throws `RESUME_FAILED` (HTTP 500) naming the stranded run instead of
+  reporting success. A concurrent duplicate resume stays benign — the engine's
+  idempotency guard is doing its job — and reports through the new optional
+  `resumeError` field. Recall and revise-window cancellation stay non-fatal by
+  design (they abandon the request), but log at error with the reason instead of
+  swallowing it. Compositions with no automation engine attached are unaffected.
+
+  Existing zombie requests from affected deployments (already `approved`, run
+  stranded) are not repaired by this change — `releaseDeadRunRequests` only
+  sweeps requests that are still `pending`.
+
+- 0848bea: feat(spec)!: retire the overloaded `managedBy: 'system'` bucket — the residue becomes `system-data` (#3355)
+
+  **FROM → TO: `managedBy: 'system'` → `managedBy: 'system-data'`.** One-line fix:
+  rename the value. Nothing else about the object changes. `os migrate meta --from 16`
+  rewrites it for you; stored metadata is CONVERTED by the ADR-0087 entry
+  `object-managed-by-system-to-system-data`, never silently reinterpreted.
+
+  ADR-0103 split the overloaded `system` bucket in v16, and it split it
+  **additively**: the 20 engine-owned objects moved to the new explicit
+  `engine-owned`, while the 8 admin/user-writable ones — the RBAC link tables
+  (`sys_user_position`, `sys_user_permission_set`, `sys_position_permission_set`),
+  `sys_user_preference`, `sys_approval_delegation`, and the three messaging config
+  grids — stayed behind on `system`. That was the right move for a v16 that could
+  not break authors, but it left the enum in a state where the surviving value
+  names the half that had already moved out: `system` sitting on precisely the
+  objects a user writes.
+
+  That is not a cosmetic complaint. An author choosing between `system` and
+  `engine-owned` had nothing in the vocabulary to choose _on_, so the bucket was
+  re-overloadable by anyone reading the name in good faith — a model author most
+  of all, since "system table" reads as "the engine owns this" in every other
+  codebase. `system-data` states both boundaries explicitly: the **schema** is the
+  platform's (versus `platform`, which is tenant-modelled), the **data** is the
+  admin's or the user's (versus `engine-owned`, where the engine owns both).
+
+  Because v16 already drained the engine side, the conversion is a **one-to-one
+  mechanical value rename** with no judgement call — by construction every
+  remaining `system` declaration is writable platform data.
+
+  **One deliberate consequence — the affordance default flips.** `system` defaulted
+  LOCKED and each of the 8 objects re-opened its writes with a
+  `userActions: { create: true, edit: true, delete: true }` block. `system-data`
+  defaults **WRITABLE** (full CRUD), because a bucket that exists to say "the data
+  is yours" should not make every member ask for it back. Those blocks are now
+  redundant and have been deleted from the 8 platform objects; keep `userActions`
+  only to **NARROW**. If you converted an object that carried no `userActions`, it
+  gains the generic affordances — the honest reading of the bucket it moved into.
+
+  **No enforcement moves.** The engine write guard, the `DelegatedAdminGate`, RLS
+  and permission sets all adjudicate off resolved affordances and the principal,
+  never off the bucket name. `system-data` simply joins `platform` / `config` as a
+  bucket the fail-closed guard does not cover, because a writable default has
+  nothing to close on. The 8 objects passed that guard before (via `userActions`)
+  and pass it now (via the bucket default), for the same resolved-affordance
+  reason.
+
+  `'system'` is **retired from the load path**: the enum rejects it with a
+  prescription naming `system-data` and the one-line fix. Absorbing it silently at
+  load would leave every author still writing the name this rename exists to
+  unteach.
+
+### Patch Changes
+
+- 5a84d41: fix(approvals): record an admin override of a staffed approver slate AS an override (#4466)
+
+  An admin who is not in a request's `pending_approvers` may still act on it — the
+  `#3424` privileged-override path exists so a request routed to an unstaffed
+  position, or to approvers who have all left, is not undecidable forever. The
+  override is defensible; what was not is what the audit trail recorded.
+
+  `sys_approval_action` had no override column at all. So an admin overriding a
+  properly-staffed slate wrote a row **byte-for-byte identical** to the designated
+  approver approving normally: a reader of the timeline saw `approve` by the admin
+  and could not tell whether the admin _was_ an approver or _overrode_ the ones who
+  were, and the bypassed approver's later `409 INVALID_STATE` was the only trace —
+  existing only if they happened to try. The platform knows at decision time (it
+  took the `isOverrideActor` branch to admit the call at all), so this was dropped
+  information, not unavailable information. The whole point of an approval record
+  is to answer "who authorized this, and were they entitled to?".
+
+  `sys_approval_action` now carries **`via_override`** (boolean, optional), set on
+  exactly the actions admitted by that branch — `decideNode`'s approve/reject and
+  `reassign`'s admin rescue. It is surfaced on `ApprovalActionRow.via_override`
+  (`@objectstack/spec/contracts`), returned by `listActions`, and added to the
+  object's `highlightFields` and two grid list views so a timeline can say
+  "overrode the approver slate" instead of rendering it as an ordinary approval.
+
+  Three distinctions the column keeps apart deliberately:
+
+  - **`true`** — the actor held no slot in the slate and was admitted only by the
+    override branch.
+  - **`false`** — checked, and it was not an override. An admin who _is_ a
+    designated approver is approving normally and records `false`: the marker is
+    about which branch admitted the call, not about whether the actor holds admin
+    rights.
+  - **absent** — a row written before this column existed. "Not recorded" is not
+    the same claim as "not an override", so `rowFromAction` maps `null` to
+    `undefined` rather than to `false`.
+
+  Additive and nullable, so this needs no data migration: existing rows keep
+  working and simply read as unrecorded. Levelled `patch` rather than `minor`
+  because nothing an author writes changes — but note it _is_ an observable
+  behaviour change on a read surface: `listActions` responses and the
+  `sys_approval_action` grid views now carry a field consumers did not see before,
+  and `sys_approval_action` gains a column on next schema sync.
+
+- 0b795da: 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.
+
+- c2a1134: fix(approvals): find the zombie requests nothing was looking at (#4469)
+
+  #4460 stopped new zombies being produced; the rows already stuck had no mechanism
+  to find or release them. The failure shape (#4420) is a request flipped to
+  `approved` / `rejected` / `returned` whose `flow_run_id` points at a run that no
+  longer exists — the decision landed, the flow never moved. Any deployment on
+  17.0.0-rc.1 that hit the wiring hole and crossed a restart mid-approval can be
+  carrying these rows.
+
+  `releaseDeadRunRequests` could not see them, and the reason is worth stating
+  plainly: it scans `status: 'pending'`, and the very step that zombifies a request
+  is the one that takes it OUT of `pending`. The act of breaking it removed it from
+  the only sweeper's field of view — a large part of why this class of failure
+  stayed silent. It could not have answered the question even if it had looked: its
+  liveness oracle is `getRun`, which reads the execution LOG and returns `null` for
+  a perfectly ALIVE suspended run after a restart. It treats `null` as alive
+  (conservative, and correct for what it does) — which is exactly why it has no way
+  to say "this run is really gone".
+
+  Adds `ApprovalService.inspectStrandedRequests()`, which uses BOTH oracles and
+  reports only rows that fail both:
+
+  - `hasSuspendedRun(runId) === false` — the suspension store itself says no live
+    pause exists. It THROWS when the store cannot be read, and that case is
+    SKIPPED and counted as `undetermined`, never condemned: an unreadable store
+    means "unknown", and a storage outage must not be published as a lost run.
+  - `getRun(runId) == null` — no terminal history row either. A run that merely
+    finished is not stranded; a request whose run neither waits nor ever completed
+    is.
+
+  **It reports; it never rewrites.** No status is changed and no run is cancelled.
+  The decision genuinely happened — a human approved or rejected — and silently
+  rolling it back would make the audit trail disagree with the facts. The report
+  carries what an operator needs to decide: which requests are stuck at which step,
+  and what the mirrored status field on the business record still reads (usually
+  the stale value the user is staring at). Whether to re-run the downstream actions
+  or re-open the approval is a judgement call this cannot make.
+
+  It rides the existing escalation/dead-run sweep clock, so the finding surfaces in
+  the logs without an operator knowing to go looking for it. `recalled` is
+  deliberately out of scope: a recall abandons its run on purpose, and reporting
+  those would bury the real findings under expected ones.
+
+  New export: `StrandedApprovalRequest` (the report row shape).
+
+- 25784cf: fix(automation,approvals): 节点类型校验推迟到插件贡献完成之后 —— approval flow 不再被误报"运行时会失败" (#4771)
+
+  showcase 每次冷启都打印 8 条断言:这些 flow "will fail at execution time"。8 条全是假的。
+  `AutomationServicePlugin.start()` 从 ObjectQL registry 拉起 flow 并**当场**校验节点类型,而
+  `ApprovalsServicePlugin.start()` 在 0.8 秒后才注册 `approval` 执行器 —— 校验器在词汇表还没
+  成型的时候就下了结论。
+
+  真正的代价不是噪音,是信号丢失:**真的没装 approvals 插件**的部署会得到一模一样的 8 条告警,
+  所以这条 warn 无法区分"健康"和"坏掉",信噪比为 0。
+
+  ADR-0018 明确把节点词汇表定义为**开放、可运行时扩展**的(插件通过
+  `registerNodeExecutor(type)` 贡献类型)。因此校验只在词汇表**封闭**的那一刻才成立:
+
+  - `AutomationEngine.sealNodeTypeVocabulary()` —— 宣告词汇表封闭,对**所有**已注册 flow 跑一次
+    权威校验,每个有问题的 flow warn 一条。`AutomationServicePlugin` 在 `kernel:bootstrapped`
+    调用它(严格晚于每个插件的 `start()` 和每个 `kernel:ready` handler —— 本插件自己的
+    `kernel:ready` 还会再注册一批 flow,别的插件也可能在它的 `kernel:ready` 里贡献执行器)。
+  - `AutomationEngine.getUnknownNodeTypeAudit(): UnknownNodeTypeAuditEntry[]` —— 同一发现的
+    **状态**形态,供 host(CLI 启动摘要、健康检查)直接读,而不是去 grep 日志。与
+    `getTriggerBindingAudit()` 同一套路。
+  - 封闭之后 `registerFlow` **恢复即时告警**:Studio 发布 / dev reload 进正在运行的服务器时,
+    词汇表确实是完整的,那句断言此时为真。所以这是时序修复,不是把告警静音。
+
+  告警文案也随之改成它现在能承诺的事:"Every plugin has started, so nothing will register them
+  now — these nodes fail at execution time with NO_EXECUTOR",并给出补救动作。
+
+  一并修掉同一缺陷类的另一半:`ApprovalsServicePlugin` 在**拿不到 automation 引擎**时,把
+  "`approval` 节点没注册"记成 `info` —— 而 dev 的默认日志级别是 `warn`,于是**真降级发生时反而
+  看不见**(#4632:静默降级必须响亮)。现在是 `warn`,写明后果(该部署里每个 ADR-0019 approval
+  flow 都会以 NO_EXECUTOR 失败)和补救(装 `@objectstack/service-automation`)。`catch` 同时收窄
+  到"服务查找"这一步,`registerApprovalNode` 内部真出错时会以自己的身份抛出,而不再被贴上
+  "no automation engine" 的错误标签;`automation` 服务存在但不接受节点执行器的分支从前**一条日志
+  都不打**,现在同样 warn。
+
+  **嵌入式 host 注意**:直接 `new AutomationEngine()` 而不经过 `AutomationServicePlugin` 的宿主,
+  需要在自己的插件都装好之后调用一次 `sealNodeTypeVocabulary()`,才能拿到这条告警(以及之后的
+  即时校验)。
+
+- Updated dependencies [430dcc2]
+- Updated dependencies [e6ac4bd]
+- Updated dependencies [80334c7]
+- Updated dependencies [ce5242c]
+- Updated dependencies [a7163ea]
+- Updated dependencies [e6e9379]
+- Updated dependencies [98877c9]
+- Updated dependencies [98877c9]
+- Updated dependencies [c44dd5e]
+- Updated dependencies [e6b1b69]
+- Updated dependencies [ad047d2]
+- Updated dependencies [2826d1e]
+- Updated dependencies [5a84d41]
+- Updated dependencies [20b1a9e]
+- Updated dependencies [203a449]
+- Updated dependencies [ac37fc6]
+- Updated dependencies [4820f55]
+- Updated dependencies [462d9c4]
+- Updated dependencies [7d21581]
+- Updated dependencies [f2445c9]
+- Updated dependencies [23338c3]
+- Updated dependencies [5b843fb]
+- Updated dependencies [b4487aa]
+- Updated dependencies [65ca83a]
+- Updated dependencies [67bf2e2]
+- Updated dependencies [c6d1cb4]
+- Updated dependencies [36030ff]
+- Updated dependencies [6117f7b]
+- Updated dependencies [e533b0b]
+- Updated dependencies [cdf4d9a]
+- Updated dependencies [aee1806]
+- Updated dependencies [c13350b]
+- Updated dependencies [c13350b]
+- Updated dependencies [9ca2d85]
+- Updated dependencies [c13350b]
+- Updated dependencies [891d345]
+- Updated dependencies [a52e2ef]
+- Updated dependencies [5293114]
+- Updated dependencies [20bc357]
+- Updated dependencies [5966c2a]
+- Updated dependencies [2382580]
+- Updated dependencies [d9fa683]
+- Updated dependencies [3c7bcc0]
+- Updated dependencies [4b6cac7]
+- Updated dependencies [7631964]
+- Updated dependencies [ac471a0]
+- Updated dependencies [60ae58e]
+- Updated dependencies [ce92674]
+- Updated dependencies [9f601e8]
+- Updated dependencies [51c5227]
+- Updated dependencies [a4a85c8]
+- Updated dependencies [07a4e26]
+- Updated dependencies [ec975f1]
+- Updated dependencies [eb4204b]
+- Updated dependencies [4f13be2]
+- Updated dependencies [61cc079]
+- Updated dependencies [0e96e46]
+- Updated dependencies [b25a116]
+- Updated dependencies [d52d4fe]
+- Updated dependencies [742cebb]
+- Updated dependencies [ce92674]
+- Updated dependencies [cf2c9b7]
+- Updated dependencies [833b512]
+- Updated dependencies [0f9faa2]
+- Updated dependencies [7cf42fe]
+- Updated dependencies [5966c2a]
+- Updated dependencies [f78dd83]
+- Updated dependencies [a2cd18a]
+- Updated dependencies [4638aaa]
+- Updated dependencies [0222d3c]
+- Updated dependencies [071d0dc]
+- Updated dependencies [0a936ea]
+- Updated dependencies [023c00b]
+- Updated dependencies [155507e]
+- Updated dependencies [7bba90b]
+- Updated dependencies [7e05d8e]
+- Updated dependencies [061406d]
+- Updated dependencies [c1f344b]
+- Updated dependencies [9c93465]
+- Updated dependencies [ebb209c]
+- Updated dependencies [65f184b]
+- Updated dependencies [63b33e6]
+- Updated dependencies [2a44c1d]
+- Updated dependencies [695cfbd]
+- Updated dependencies [7445149]
+- Updated dependencies [071d0dc]
+- Updated dependencies [0848bea]
+- Updated dependencies [d51bed2]
+- Updated dependencies [b8b3c64]
+- Updated dependencies [0c0fbd9]
+- Updated dependencies [f3141d8]
+- Updated dependencies [5a84d41]
+- Updated dependencies [fd3013a]
+- Updated dependencies [21676eb]
+- Updated dependencies [e336549]
+- Updated dependencies [d40f43a]
+- Updated dependencies [e5e7ee0]
+- Updated dependencies [a2ebea2]
+- Updated dependencies [800bdb0]
+- Updated dependencies [04f1182]
+- Updated dependencies [5647006]
+- Updated dependencies [38f7e4f]
+- Updated dependencies [c57f3cf]
+- Updated dependencies [97faca3]
+- Updated dependencies [ad5fe25]
+- Updated dependencies [ea90179]
+- Updated dependencies [ce92674]
+- Updated dependencies [5ef0b5b]
+- Updated dependencies [48fbacb]
+- Updated dependencies [355e951]
+- Updated dependencies [dadb43f]
+  - @objectstack/spec@17.0.0-rc.2
+  - @objectstack/platform-objects@17.0.0-rc.2
+  - @objectstack/core@17.0.0-rc.2
+  - @objectstack/types@17.0.0-rc.2
+  - @objectstack/metadata-core@17.0.0-rc.2
+  - @objectstack/formula@17.0.0-rc.2
+
+## 17.0.0-rc.1
+
+### Minor Changes
+
+- f5a4ef0: refactor!: ADR-0112 batch 2 — sweep the lowercase error-code emitters (#4003)
+
+  Continues #3841 per ADR-0112. Batch 1 (#3988) settled the vocabulary and closed
+  the set; this batch moves the emitters that still spoke lowercase `snake_case`
+  onto it.
+
+  **Wire-visible change.** Error codes on these surfaces change spelling. Generic
+  conditions collapse onto the standard catalog rather than keeping a synonym:
+  `unauthorized`/`unauthenticated` → `UNAUTHENTICATED`, `forbidden` →
+  `PERMISSION_DENIED`, `not_found` → `RESOURCE_NOT_FOUND`, `internal` →
+  `INTERNAL_ERROR`, `unavailable` → `SERVICE_UNAVAILABLE`, `not_supported` →
+  `NOT_IMPLEMENTED`, `bad_request` → `INVALID_REQUEST`. Domain conditions get codes
+  registered in `ERROR_CODE_LEDGER` (`MARKETPLACE_STORAGE_FAILED`,
+  `PLUGIN_MANIFEST_INVALID`, `ITEM_LOCKED`, `DELIVERY_NOT_ELIGIBLE`, …). Swept:
+  `cloud-connection`, `plugin-auth`, `hono`, `metadata-protocol`, `rest`,
+  `service-messaging`, `service-automation`, `trigger-api`.
+
+  Branch on `error.code` values rather than pattern-matching their case: the
+  console's fix for the same rename (objectui#2977) reads codes case-insensitively
+  for exactly this reason, and that is the pattern to copy in your own consumers if
+  you support servers on both sides of the change.
+
+  **Four routes stop putting a code in the message slot.** The webhook redeliver
+  route, the API-trigger webhook, and two `rest` routes answered
+  `{ success: false, error: '<code>', message }` — the code occupying `error`, the
+  declared object envelope nowhere. They now emit `error: { code, message }`, and
+  three API-trigger branches gained a message they never had. Clients reading
+  `body.error` as a string on those routes must read `body.error.code`.
+
+  **`ConnectorErrorCategory` / `ConnectorRetryStrategy`** (ADR-0112 D9a):
+  `@objectstack/spec` exported two mutually incompatible `ErrorCategory` types and
+  two `RetryStrategy` types. The connector-side pair is renamed; importers of the
+  `integration` subpath update the name. Side effect: the api-side `ErrorCategory`
+  and `RetryStrategy` now appear in the generated API reference at all — the name
+  collision had been silently dropping them.
+
+  **`OAUTH_REGISTER_FAILED` replaces an unbounded code source.** The OAuth client
+  registration route put better-auth's arbitrary `body.error` string straight into
+  `error.code`. The code is now ours and the upstream discriminator moved to
+  `details.upstreamError`.
+
+  **Not swept, deliberately.** `sys_metadata_audit.code` keeps its lowercase values
+  (ADR-0112 D6b): it is persisted audit history, and the same column holds
+  non-error outcomes (`ok`, `lock_override`). Diagnostics records that ship inside a
+  200 keep theirs (D6c), as do field-level codes (D6, #3977) and the CLI's
+  `--json` output contract.
+
+  A `check:error-code-casing` CI guard now fails on a new lowercase literal in a
+  code position, since the ledger's casing rule can only police codes that someone
+  registers.
+
+- 91f4c78: feat(approvals,spec): structured reassign hand-off parties on `sys_approval_action` (#4365)
+
+  A reassign's audit row used to encode "who handed the slot to whom" only inside
+  a default free-text comment — `"<from_id> → <to_id>"`, two raw user ids — which
+  clients could neither parse reliably nor render readably, so the approvals
+  timeline showed opaque identifier soup for the single most important fact of
+  the entry.
+
+  - `sys_approval_action` gains `reassign_from` / `reassign_to`
+    (`lookup('sys_user')`), written by `ApprovalService.reassign()`.
+  - `comment` is pure user input again: nothing is invented when the actor
+    supplies none.
+  - `listActions()` resolves both parties' display names into
+    `reassign_from_name` / `reassign_to_name`, alongside the existing
+    `actor_name`, so timelines can render "from A to B" without extra lookups.
+  - `ApprovalActionRow` (spec contract) declares the four new fields.
+
+  Pre-existing rows keep their legacy comment; clients should prefer the
+  structured fields when present and fall back to `comment` otherwise.
+
+- cd6b9f2: `decisionOutputs` entries may now be declared `required` (objectui#2955). A typed entry `{ key, label?, type?, multiple?, required?: true }` tells the runtime — not just the decision UI — that an approver must supply the value: an **approve** carrying no value, or a blank one (`''`, whitespace, `[]`, an array of blanks), is rejected with `VALIDATION_FAILED` before any write, so the audit row and the request are untouched and the run can never resume past the node with the key missing.
+
+  That gap is what the flag closes. `decisionOutputs` exists so a decision can route the next step (`approvers: [{ type: 'expression', value: 'vars.lead_review.next_reviewers' }]`), but nothing made the approver actually answer: a skipped output resumed the run with the key absent, and the next node either faulted with `EXPRESSION_FAILED` or resolved an empty slate and stalled on `onEmptyApprovers: 'admin_rescue'` — long after the one person who could have filled it in had moved on. `onEmptyApprovers` was the only backstop, and it is a recovery mechanism, not a contract.
+
+  **Reject never requires them.** The run leaves down the `reject` edge, where nothing reads the outputs — demanding routing data to say "no" would trap the rejection. Outputs still ride a reject when the approver filled them in.
+
+  **No elevation bypass.** A one-click email action link and an `auto_approve` SLA escalation both fail the same way rather than advancing into a node that would resolve nobody; the escalation sweep already isolates a throwing request, so that decision stays pending and visibly overdue instead of silently breaking the run downstream. Enforcement is per decision, so on a `unanimous` / `quorum` node every approver supplies the required outputs and the finalizing decision's values are what the flow resumes with.
+
+  `required` rides `normalizeDecisionOutputs`, so it reaches clients on `decision_output_defs` — a decision UI marks the field required and blocks locally instead of round-tripping to a 400. The console side ships in objectui#2955.
+
+### Patch Changes
+
+- 820eff9: fix(spec,plugin-approvals): the two approval vocabularies are derived, not hand-matched (#3786)
+
+  `sys_approval_request.status` and `sys_approval_action.action` spelled their
+  option lists out — five values and twelve — each under a "Keep in sync with
+  `ApprovalStatus` / `ApprovalActionKind` (spec/contracts)" comment, while the
+  contract held the same sets as bare type unions. Seventeen strings matched by
+  hand across a package boundary, with nothing checking them. They did all still
+  agree; the sweep that found them (#3786) verified that verbatim before changing
+  anything.
+
+  Agreeing is not the same as being held, and both directions of drift are quiet:
+
+  - a value the **column** accepts and the contract omits is invisible to every
+    consumer typed against the contract — the row exists and nothing can narrow it;
+  - a value the **contract** declares and the column rejects surfaces only at write
+    time, on whichever tenant first reaches that transition.
+
+  An audit vocabulary is a bad place for either. So the contract now publishes the
+  lists as values — `APPROVAL_STATUSES` and `APPROVAL_ACTION_KINDS` — with
+  `ApprovalStatus` / `ApprovalActionKind` derived from them via
+  `(typeof X)[number]`, and the two columns spread the constants. The per-entry
+  rationale (which action kinds move the flow, which are thread-only, why
+  `returned` differs from `recalled`) moved onto the constants, where the values
+  live.
+
+  **New exports, no behaviour change.** The emitted option lists are byte-identical
+  — verified against the built artifact before and after. Existing imports of the
+  two types are unaffected; the types resolve to the same unions.
+
+  `approval-vocabularies.test.ts` pins the qualifier that derivation alone cannot:
+  the columns agree with the contract _while the spread is there_, and the test
+  fails if either is re-inlined as a literal that has drifted. It also guards the
+  guard (an unresolvable import would compare two empty lists and pass) and asserts
+  the two vocabularies stay distinct, since a copy-paste pointing one column at the
+  other constant would satisfy "derived from the contract" while being the wrong
+  vocabulary entirely.
+
+  Verified by mutation in both directions: adding a value to `APPROVAL_STATUSES`
+  propagates into the built `sys_approval_request.status` options (the derivation
+  is live, not a stale build), and re-inlining a drifted literal fails
+  `sys_approval_request.status offers exactly the contract statuses, in order`.
+
+- 2e836de: chore(packaging): CHANGELOG.md ships in every npm tarball (#4261)
+
+  The AGENTS.md post-task checklist requires breaking changesets to carry their
+  FROM → TO migration because "this text ships to consumers as `CHANGELOG.md`
+  inside the npm package and is what an upgrading agent greps after the tombstone
+  error." That delivery path was severed for 68 of the 69 publishable packages:
+  npm packs `package.json` / `README*` / `LICENSE*` unconditionally but — unlike
+  older npm versions — not `CHANGELOG.md`, and the canonical
+  `"files": ["dist", "README.md"]` whitelist never named it. Measured on npm
+  10.9.7: `npm pack --dry-run` on `@objectstack/types` shipped 3 files while its
+  70KB `CHANGELOG.md` stayed behind. Only `@objectstack/spec` listed it
+  explicitly.
+
+  The tombstone-error scenario is precisely the one where the repo is out of
+  reach — the upgrading agent has `node_modules` and nothing else — so the
+  migration text has to ride in the tarball. Every publishable package now
+  declares `CHANGELOG.md` in `files`, and the canonical whitelist is
+  `["dist", "README.md", "CHANGELOG.md"]`.
+
+  The other half is the gate: `check:published-files` gains a fifth invariant,
+  COMPLETE — a whitelist that fails to cover `CHANGELOG.md` fails the
+  always-required lint job, so the next package cannot silently sever the path
+  again. `@objectstack/spec`'s per-package EXTRA_ENTRIES exemption dissolves
+  into the canonical set.
+
+  Consumer-visible change: one more file per install (the package's changelog,
+  e.g. 70.8KB for `@objectstack/types`), and `grep -r "removed key"
+node_modules/@objectstack/*/CHANGELOG.md` now finds the migration it was
+  promised.
+
+- b5f9397: fix(sharing,runtime): a `sort` passed straight to the engine never ordered anything; migrate every in-repo engine call to canonical QueryAST keys (#4346)
+
+  Two changes with different weights, from one sweep of every in-repo engine
+  call site that still speaks a deprecated alias.
+
+  **The bug — three dropped sorts.** #4346 made the engine fold `filter`→`where`
+  and `top`→`limit` on all six methods. The other four pairs in
+  `RPC_QUERY_ALIAS_SLOTS` (`select`, `sort`, `skip`, `populate`) are folded at
+  the RPC/wire layer only — their values need shape lowering that belongs to
+  those layers — and a **direct `engine.find()` never crosses that layer**. Three
+  call sites passed `sort` there, so it rode onto the AST untouched, every
+  driver's `Array.isArray(query.orderBy)` guard declined to emit an ORDER BY, and
+  the query returned an ordinary-looking, arbitrarily-ordered result:
+
+  | call site                           | asked for                                         | actually got                |
+  | ----------------------------------- | ------------------------------------------------- | --------------------------- |
+  | `share-link-routes.ts`              | shared AI conversation messages, `created_at asc` | messages in arbitrary order |
+  | `runtime/domains/share-links.ts`    | same route, runtime-domain copy                   | same                        |
+  | `share-link-service.ts` `listLinks` | the 200 most recent share links                   | an arbitrary 200            |
+
+  All three combine the dropped sort with a `limit` — the "latest N" shape whose
+  failure #4226 spelled out: an unapplied sort returns rows in arbitrary order,
+  which `limit` then slices into an arbitrary page. #4226 fixed that in the wire
+  normalizer; these calls sit one layer below it. `listLinks` had no test at all,
+  which is why it went unnoticed. Now pinned — on the option bag the engine
+  receives, not on row order, because the failure is that the key never becomes
+  `orderBy` and a fake engine honouring either spelling would pass either way.
+
+  **The cleanup — 27 no-op renames.** Every remaining in-repo engine call passing
+  `filter` now passes `where` (approvals 5, auth 2, reports 6, sharing 11,
+  webhooks 2, plus the one `filters` in a spec doc example). These are strict
+  no-ops since #4346 folds the alias — the point is that the framework stops
+  depending on a spelling it asks users to migrate off, which is a prerequisite
+  for ever retiring the aliases. Service-level `filter` PARAMETERS (each
+  service's own public API, e.g. `listRequests(filter)`) are deliberately
+  untouched — those are not engine option bags.
+
+  Two of the renamed calls were live victims of the #4346 bug rather than
+  cosmetic: `auth-manager`'s `stampIdentitySource` read the table's first row via
+  `findOne({filter})` and counted the whole table via `count({filter})`, so a
+  federated sign-in never stamped `source: 'idp_provisioned'`. #4346 already
+  corrected the behaviour; this makes the call say what it means.
+
+- 9881074: fix(batch): the background walks seek instead of counting, so they stop skipping rows (#4363)
+
+  #4363 made a single paged read a partition of its result set. It could not make
+  a _walk_ one: seven background scans paged with a growing `offset` while writing
+  to the very rows they were reading, and an offset counts into a set those writes
+  are changing. Rows slide past the cursor and are never visited.
+
+  That is not a slow page in any of these — it is a wrong answer wearing the shape
+  of a clean run:
+
+  - **`rebuildApproverIndex`** built its desired state by walking
+    `sys_approval_request WHERE status = 'pending'` with no `orderBy` at all, then
+    **deleted** every index row that state did not explain. A skipped request
+    meant an approver silently dropped from someone's queue. (The loop beside it
+    ordered by `created_at` — not unique, so its pages were never a partition
+    either.)
+  - **`verifyFileReferences`** decides which files nothing references. A record it
+    never visits is reported as an unreferenced file.
+  - **`backfillFileReferences`** and the **pinyin companion backfill** rewrite
+    each row they read, so their own writes were shifting the set out from under
+    the cursor. Records were left unconverted and unsearchable by a run that
+    reported success.
+  - **`scanValueShapes`** exists to vouch that no stored value is off-shape, and
+    it opens a migration gate on that evidence.
+
+  All of them now go through `keysetWalk` (`@objectstack/types`): order by a
+  unique key, and seek past the last one instead of counting from the start. A
+  row's key does not move when the row is updated, and cannot be shifted when
+  another is deleted, so the walk is stable under exactly the mutation these
+  functions perform. It is also O(n) rather than O(n²/page) — measured on
+  Postgres over 2M rows, deep pages cost ~1.1 s by offset against ~0.09 s by seek.
+
+  One deliberate non-conversion: the REST **export** stream keeps its offset. It
+  honors a caller-chosen sort, and a keyset walk would have to re-order the export
+  by `id` to seek — changing what the user asked for to fix a cost. Its pages are
+  already a partition since #4363; only the depth cost remains.
+
+  `keysetWalk` merges the cursor with `$and` rather than spreading it into the
+  caller's filter, so a walk whose own `where` constrains the key column
+  (`{ id: { $in: [...] } }`) keeps that constraint instead of having it silently
+  overwritten. When a `max` cap is set it reads one row beyond the cap to tell
+  "the cap stopped us" from "the source ended exactly there" — without that, a
+  walk that read everything still reports `truncated`, and a caller acting on it
+  goes looking for rows that were never withheld.
+
+  The storage suites' fake engines now **throw** on an `offset` instead of serving
+  one, so the conversion is pinned rather than merely passing.
+
+- cc2de0e: chore(packaging): 20 packages stop publishing their sources, tests and build tooling (#4248)
+
+  These 20 packages declared no `files` field, so npm fell back to packing the
+  whole package directory. `npm pack --dry-run` on `@objectstack/plugin-webhooks`
+  listed **21 files** — 15 under `src/`, three of them unit tests
+  (`auto-enqueuer.test.ts`, `bootstrap-declared-webhooks.test.ts`, …), plus the
+  build-time `scripts/i18n-extract.config.ts`. `dist/` lands on top of that at
+  publish time rather than instead of it, so consumers were installing the
+  TypeScript sources and the test suite alongside the artifact they asked for.
+
+  Each now declares `"files": ["dist", "README.md"]`, matching the 29 packages
+  that already did. Nothing a consumer imports moves: every `main` / `types` /
+  `exports` target in all 20 already resolved inside `dist/`, which the new
+  `check:published-files` guard verifies rather than assumes. The visible change
+  is a smaller install and a smaller dependency-scanning surface — `npm pack` on
+  `@objectstack/plugin-webhooks` now yields 2 files plus `dist/`.
+
+  The other half of the fix is the gate. Half the packages declaring `files` and
+  half not was the #3786 shape — a hand-copied convention with nothing enforcing
+  it, where whoever forgets the line gets no signal at all. `check:published-files`
+  (new, wired into the always-required `lint` job) holds every non-private
+  workspace package to four invariants: `files` is **declared**; it is
+  **sufficient** (covers every entry point, so tightening a whitelist cannot ship
+  a package that fails to resolve); it is **minimal** (admits no test, test-harness
+  config or build script); and anything beyond `dist` + `README.md` is
+  **registered** with a reason, reconciled in both directions so a stale exemption
+  is an error rather than dead text. `@objectstack/spec` is the one package with
+  registered extras — its `.zod.ts` sources, JSON Schemas, liveness ledgers and
+  `CHANGELOG.md` are product, not build input.
+
+  This also closes an assumption #4206 was resting on. Excluding `<pkg>/scripts/**`
+  from the docs-drift implementation test is sound only while no package publishes
+  `scripts/` as runtime code; that held, but it held because someone read all three
+  offenders by hand. It is now checked on every PR.
+
+- Updated dependencies [6a67d7a]
+- Updated dependencies [0ecc656]
+- Updated dependencies [06772eb]
+- Updated dependencies [270650f]
+- Updated dependencies [3aef718]
+- Updated dependencies [1ea6bce]
+- Updated dependencies [c1dcacd]
+- Updated dependencies [ad303ed]
+- Updated dependencies [32ccb23]
+- Updated dependencies [f5a4ef0]
+- Updated dependencies [2d3e255]
+- Updated dependencies [7d7521f]
+- Updated dependencies [5dc4d02]
+- Updated dependencies [05154a1]
+- Updated dependencies [9b6fe7c]
+- Updated dependencies [8c711fb]
+- Updated dependencies [09e4547]
+- Updated dependencies [91f4c78]
+- Updated dependencies [820eff9]
+- Updated dependencies [8d895ff]
+- Updated dependencies [f6472d7]
+- Updated dependencies [78caf51]
+- Updated dependencies [62a789b]
+- Updated dependencies [789ad63]
+- Updated dependencies [2af1988]
+- Updated dependencies [0af50a3]
+- Updated dependencies [2e836de]
+- Updated dependencies [12a19a8]
+- Updated dependencies [41dcda3]
+- Updated dependencies [c8124e5]
+- Updated dependencies [a1a4140]
+- Updated dependencies [c20b875]
+- Updated dependencies [2a37694]
+- Updated dependencies [217e2e6]
+- Updated dependencies [86a71d1]
+- Updated dependencies [d5c75e2]
+- Updated dependencies [03d26f7]
+- Updated dependencies [4384921]
+- Updated dependencies [3c628ce]
+- Updated dependencies [7cb922e]
+- Updated dependencies [1d22114]
+- Updated dependencies [b5f9397]
+- Updated dependencies [ed77493]
+- Updated dependencies [58a03d2]
+- Updated dependencies [dc530b4]
+- Updated dependencies [e59786e]
+- Updated dependencies [bcf1112]
+- Updated dependencies [9774b78]
+- Updated dependencies [b07d829]
+- Updated dependencies [a648e96]
+- Updated dependencies [a47ac06]
+- Updated dependencies [e4c61a7]
+- Updated dependencies [cc60165]
+- Updated dependencies [081aa6f]
+- Updated dependencies [91f4c78]
+- Updated dependencies [e8d0c21]
+- Updated dependencies [45dc446]
+- Updated dependencies [c1d44f7]
+- Updated dependencies [ab9fb5c]
+- Updated dependencies [f985b3f]
+- Updated dependencies [9a4932a]
+- Updated dependencies [f9fc874]
+- Updated dependencies [011b386]
+- Updated dependencies [9881074]
+- Updated dependencies [7777e8f]
+- Updated dependencies [507b92a]
+- Updated dependencies [7309c81]
+- Updated dependencies [20bc1ec]
+- Updated dependencies [90c2b15]
+- Updated dependencies [39eb01b]
+- Updated dependencies [42eeb7d]
+- Updated dependencies [01e124d]
+- Updated dependencies [7ce02eb]
+- Updated dependencies [a13827e]
+- Updated dependencies [7733604]
+- Updated dependencies [40e420f]
+- Updated dependencies [d13004a]
+- Updated dependencies [be7360c]
+- Updated dependencies [cc2de0e]
+- Updated dependencies [5b47ab5]
+- Updated dependencies [b09d8d9]
+- Updated dependencies [b09d8d9]
+- Updated dependencies [8675db6]
+- Updated dependencies [b09d8d9]
+- Updated dependencies [3eb1b2b]
+- Updated dependencies [59b85c0]
+- Updated dependencies [6e357ed]
+- Updated dependencies [d6938bf]
+- Updated dependencies [31e0be9]
+- Updated dependencies [4bfd455]
+- Updated dependencies [ffd2ce2]
+- Updated dependencies [62f8017]
+- Updated dependencies [a831df1]
+- Updated dependencies [f752ee3]
+- Updated dependencies [a1b61e0]
+- Updated dependencies [cd6b9f2]
+- Updated dependencies [2cb6d3c]
+- Updated dependencies [af2a095]
+- Updated dependencies [ec796d5]
+- Updated dependencies [e87fea1]
+- Updated dependencies [c65e529]
+- Updated dependencies [3ca34c1]
+- Updated dependencies [239c3a3]
+- Updated dependencies [94a0bbc]
+- Updated dependencies [d6bfb3d]
+- Updated dependencies [a2266a6]
+- Updated dependencies [d25a0ec]
+- Updated dependencies [667b83e]
+- Updated dependencies [627b188]
+- Updated dependencies [8d4eae7]
+- Updated dependencies [857a6cf]
+- Updated dependencies [65a3a84]
+- Updated dependencies [d5749d7]
+- Updated dependencies [ccd9397]
+- Updated dependencies [bca935b]
+- Updated dependencies [d92c72d]
+- Updated dependencies [c54c822]
+- Updated dependencies [8dcc0f5]
+- Updated dependencies [75b9e51]
+- Updated dependencies [0a2f233]
+- Updated dependencies [8621cdd]
+- Updated dependencies [6f23667]
+- Updated dependencies [5d21a48]
+- Updated dependencies [19365b7]
+- Updated dependencies [b7ed26d]
+- Updated dependencies [68dea0b]
+- Updated dependencies [64f8cbe]
+- Updated dependencies [b3a3d83]
+- Updated dependencies [7a55913]
+- Updated dependencies [35accbf]
+- Updated dependencies [6038de7]
+- Updated dependencies [eb95d97]
+- Updated dependencies [e4c2dc8]
+- Updated dependencies [1bd2795]
+- Updated dependencies [8186a70]
+- Updated dependencies [a329cca]
+- Updated dependencies [6eec18c]
+- Updated dependencies [4d7bebf]
+- Updated dependencies [821ac7a]
+- Updated dependencies [8f81731]
+- Updated dependencies [4965bfa]
+- Updated dependencies [8b50cb3]
+- Updated dependencies [8c2db68]
+- Updated dependencies [22b5e54]
+- Updated dependencies [0166bd5]
+- Updated dependencies [9b702dc]
+- Updated dependencies [ab16331]
+  - @objectstack/spec@17.0.0-rc.1
+  - @objectstack/platform-objects@17.0.0-rc.1
+  - @objectstack/core@17.0.0-rc.1
+  - @objectstack/metadata-core@17.0.0-rc.1
+  - @objectstack/formula@17.0.0-rc.1
+  - @objectstack/types@17.0.0-rc.1
+
 ## 17.0.0-rc.0
 
 ### Minor Changes