Merge remote-tracking branch 'origin/main' into claude/issue-4834-plugin-runtime-family-retire

# Conflicts:
#	packages/spec/src/migrations/registry.ts

Author: claude

.changeset/analytics-compare-measure-filters.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(service-analytics): `compareTo` applies measure-scoped filters, so `<measure>__compare` is the same measure as the column beside it (#4820)
+
+A dataset measure declared with its own `filter` is scoped by running a
+supplementary grouped sub-query — `combineFilters(baseFilter, measureFilters[m])`
+— and merging it back by dimension key. The `compareTo` pass did not: it issued
+**one** shifted query over every base measure with only the base filter as its
+`where`, and never consulted `compiled.measureFilters` at all.
+
+For a dataset like
+
+```ts
+measures: [
+  { name: 'revenue',   aggregate: 'sum',   field: 'amount' },
+  { name: 'won_count', aggregate: 'count', filter: { stage: 'closed_won' } },
+]
+```
+
+the current-period column was scoped and the comparison column was not — two
+different measures rendered side by side under one label:
+
+| # | measures | where | |
+|:---|:---|:---|:---|
+| 1 | `revenue` | — | current |
+| 2 | `won_count` | `{"stage":"closed_won"}` | current |
+| 3 | `revenue`, `won_count` | **absent** | shifted |
+
+`won_count__compare` was therefore a count of **every** opportunity in the
+previous window, inflated by exactly the rows the measure exists to exclude.
+The error runs one way: the comparison period always looks better, so a "won
+deals vs. last month" tile reads as a collapse when nothing went wrong. Only
+filter-scoped measures were affected — the unfiltered ones next to them compared
+correctly, which is what made it survive.
+
+The comparison window now runs the **same pass** as the current period —
+unfiltered measures in one shifted query plus one shifted sub-query per
+filter-scoped measure, merged by dimension key — through a single shared
+implementation, so the two paths cannot re-diverge at the next change. The
+dataset filter, the presentation's `runtimeFilter` and the measure's own filter
+compose identically in both windows; the only difference between them is the
+shifted `dateRange`.
+
+Numbers reported by existing dashboards change where a filtered measure was
+compared: with 3 won deals this month against 1 won of 5 opportunities last
+month, `won_count__compare` was `5` and is now `1`.
+
+Cost: one extra query per filter-scoped measure when `compareTo` is set.
+Selections whose measures carry no filter are untouched and still compare in a
+single shifted query.
+
+The empty-group fill (#4708) covers the new seam: a group the measure's filter
+empties in the *previous* window now reports `0` for a `count`/`sum` compare
+column rather than blanking it, exactly as it already did for the current period.

.changeset/batch-row-error-codes-registered.md

@@ -0,0 +1,26 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): register `ROLLED_BACK` / `NOT_ATTEMPTED` batch-row error codes; record the batch-row shape migration (#4793)
+
+Support for the `@objectstack/metadata-protocol` v17 batch-row migration
+(#4793 — see its major changeset for the wire change itself):
+
+- `ERROR_CODE_LEDGER` registers two codes under `@objectstack/metadata-protocol`:
+  `ROLLED_BACK` (atomic data-batch row was written, then undone by the batch
+  rollback) and `NOT_ATTEMPTED` (row never ran — an earlier row's failure
+  aborted the batch). They are the structured, `ApiError.code`-level form of
+  the message-string prefixes #4620 introduced; `ApiErrorSchema.code` now
+  accepts them and clients branch on the code instead of regexing messages.
+- The ADR-0087 migration registry gains the protocol-17 semantic entry
+  `batch-row-result-schema-shape` (a RESPONSE surface — nothing stored to
+  rewrite, so it is a documented TODO for readers of the legacy `row.error` /
+  `row.record` keys), and `docs/protocol-upgrade-guide.md` is regenerated
+  with it.
+- `BatchOptionsSchema.atomic` / `BatchOperationResultSchema.errors` describe
+  strings now document the code-based rollback marking (reference docs
+  regenerated).
+
+No schema *shape* changes: `BatchOperationResultSchema` already declared
+`errors` / `data` / `index` — the runtime caught up to it.

.changeset/batch-row-result-schema-shape.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/metadata-protocol": major
+---
+
+fix(metadata-protocol)!: batch per-row results now deliver the declared `BatchOperationResultSchema` shape (#4793)
+
+**Breaking wire change** on the per-row `results` entries of the three
+bulk-write endpoints — `POST /data/:object/batch`, `/updateMany`,
+`/deleteMany`. The rows had drifted from the schema that declares them:
+`BatchOperationResultSchema`, the client SDK's exported `BatchOperationResult`
+type and the reference docs all said `errors: ApiError[]` / `data` / `index`,
+while the wire carried `error: string` / `record` and never sent `index`. A
+TypeScript consumer written against the published type compiled, validated,
+and read `undefined` at runtime. The wire now delivers exactly what is
+declared (a conformance pin parses every emitted row against the schema, so
+the two cannot silently fork again).
+
+**FROM → TO, per row:**
+
+| Before (legacy wire) | After (declared schema) | Your fix |
+| --- | --- | --- |
+| `row.error` (string) | `row.errors` (`ApiError[]`) | read `row.errors?.[0]?.message`; branch on `row.errors?.[0]?.code` |
+| `row.record` | `row.data` | rename the read |
+| — (never sent) | `row.index` (number) | new — the row's position in the request array; use it to correlate failure rows that carry no `id` |
+| `row.droppedFields` | `row.droppedFields` | unchanged |
+
+**Rollback marking is structured now.** The `ROLLED_BACK:` /
+`NOT_ATTEMPTED:` message-string prefixes that #4620 introduced (see the
+`many-data-atomic-real-or-refused` changeset — its description of those
+markers is superseded by this entry) are promoted to first-class
+`ApiError.code` values, registered in the spec's ERROR_CODE_LEDGER:
+
+- `errors[0].code === 'ROLLED_BACK'` — the row was written, then undone by the
+  atomic batch rollback; `message` carries the causal row's index and error.
+- `errors[0].code === 'NOT_ATTEMPTED'` — the row never ran; an earlier row's
+  failure aborted the batch.
+- the causal row keeps its own error code (e.g. `RECORD_NOT_FOUND`,
+  `VALIDATION_FAILED`; an unclassified engine throw maps to `INTERNAL_ERROR`,
+  with `httpStatus` mirrored when the error carried one).
+
+Branch on the code — do **not** regex message prefixes; the prefixes are gone.
+
+**Who is affected:** only readers of the *legacy* keys — which were never in
+the schema or the SDK types, so they were reachable only via `as any` or bare
+JS. Code written against `BatchOperationResult` (the published contract) needed
+this change to start working and needs no migration. There is no
+dual-emission or compatibility fallback: this is a hard cut inside the v17
+major window, and the old keys simply no longer exist on the wire.

.changeset/ci-merge-queue-throughput.md

@@ -0,0 +1,4 @@
+---
+---
+
+CI-only (#4859): Test Core / Dogfood 各 2→3 分片 + merge-queue 失败自动分诊评论 workflow。仅 `.github/workflows/**`，不发布任何包。

.changeset/hook-body-crypto-hash-retired.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": major
+"@objectstack/cli": major
+"@objectstack/runtime": major
+---
+
+refactor(spec,cli,runtime)!: 退役 `crypto.hash` 能力 —— 声明了四层、构建期还自动推断,沙箱从没实现(#4391,ADR-0049 enforce-or-remove)
+
+`crypto.hash` 是四层声明、零层实现:`HookBodyCapability` 枚举收它、枚举旁的文档表列它、CLI 提取器**自动推断**它、`ScriptContext.crypto.hash` 还写了签名 —— 而 `installCtx` 只往 VM 的 `ctx.crypto` 上装了 `randomUUID`。于是这个 token 唯一授权的那次调用,**每一次都在 VM 里抛**。
+
+这比普通的 declared ≠ enforced 更毒一档,坏就坏在**构建期推断**:作者(尤其是 AI 作者)写下 `ctx.crypto.hash(...)`,提取器就替他把能力加进 `capabilities`,`os build` 因此全绿 —— 系统亲手把人送进一条必炸的死路,而唯一诚实的记录是文档表格里一句 `_(not yet wired)_`,没有作者会先读表格再写 body。
+
+**裁决是 remove,不是实现**(维护者 2026-08-02):从未实现、调用即抛、**零投诉** —— 对一个每次使用都抛错的能力来说,这本身就是最强的活性证据,没人需要它。在沙箱里实现 crypto 会扩大沙箱的能力面与安全审查面,那是长期成本而非一次性工时,无业务拉动不做。真需要哈希时按能力准入流程重提:**实现先行,声明随实现走**(ADR-0049 的 enforce 腿留给有实现的那天)。
+
+## FROM → TO
+
+| 写了什么 | 现在怎么办 |
+| :--- | :--- |
+| `capabilities: ['crypto.hash']` | **删掉这个 token**。它从未授权成任何东西 |
+| `await ctx.crypto.hash(algo, data)` | **删掉这次调用**。它从未返回过值 —— 今天能跑的代码没有一行依赖它 |
+| 确实需要哈希 | 在 host 侧做(Connector recipe,或引擎侧 hook)。沙箱内哈希须走能力准入流程重开,实现先行 |
+
+一句话修法:**两个都删**。`os migrate meta --from 16` 会自动帮你剥掉 token;那行**死调用是你自己要删的** —— 转换层刻意不改 body 源码(见下)。
+
+## 定级理由(逐条自证,未照抄前例)
+
+三问按 #4535 §5 逐条走:
+
+1. **会不会 TS2305 / TS2339?** 会,两处。`HookBodyCapability` 是 public 导出类型,把它当**字面量联合**用的代码(`const c: HookBodyCapability = 'crypto.hash'`、对 token 做穷举 switch)现在编译失败;`ScriptContext.crypto.hash` 的调用点以 TS2339 失败。实测三仓(objectstack / cloud / objectui)裸名扫描 `crypto.hash` / `ctx.crypto.hash` / `'crypto.hash'` —— **两个兄弟仓零命中**,本仓命中全在本 PR 内清理。
+2. **有没有元数据迁移?** 有。token 是写在作者源 hook/action body `capabilities: []` 数组里的**值**,也会躺在已存的 `sys_metadata` 行里 —— 故注册了 ADR-0087 D2 转换 `hook-body-crypto-hash-removed`(D3 挂 protocol-17)。这是与 #4767 / #4783 / #4616 的分界:那三单退役的是**导出名 / 运行时描述符**,没有作者源可改写;本单有,和 `object-enable-trash-mru-removed` / #4734 同侧。
+3. **形状变更?** 是**枚举值收窄**(6 → 5),不是 key 移除。故**没有 `retiredKey()` 墓碑** —— `capabilities` 这个 key 本身依然活着、依然被强制。处方改由枚举自己的 error map 承载,并按 `object.managedBy: 'system'` 的先例**以 `issue.input` 为键**:只有「曾经合法」的那个拼写会被告知「was removed」,写错成 `crypto.hsah` 的作者拿到的仍是 zod 自己那条列出合法 token 的消息 —— 告诉他「你的值被退役了」属于误导。
+
+`@objectstack/cli` 与 `@objectstack/runtime` 同定 **major**:前者 `ExtractedBody.capabilities` 的公开联合类型收窄(赋值给它的代码 TS2322),后者 `ScriptContext.crypto` 少一个成员(TS2339)。
+
+## 门禁实报
+
+枚举值收窄对四张 ratchet **全部不可见**,这一点值得单独记一笔:`authorable-surface.json` 记到 key 级(`data/ScriptBody:capabilities`),`json-schema.manifest.json` 记 def 名(`data/HookBodyCapability` 仍在),`packages/spec/json-schema/` 本身 gitignore。所以 `check:authorable-surface` / `check:api-surface` 实跑**零变化**,`check:liveness` / `check:empty-state` 同样 PASS(`capabilities` key 仍活,不产生台账行变更)。
+
+也就是说:**本次移除没有任何一张基线能自动兜住它** —— 兜住它的只有本 PR 新增的 pin 测试(spec / cli / runtime 各一组,已 sabotage 实跑验证复活即红)。`check:generated` 8/8 绿,移动的是 `spec-changes.json`、`docs/protocol-upgrade-guide.md` 与两页生成参考文档(`data/hook-body.mdx`、`ui/action.mdx`,枚举选项随之少一项)。
+
+## 转换刻意不做的事
+
+`hook-body-crypto-hash-removed` 只从 `body.capabilities` 里剥掉死 token,**不碰** body 源码里那行 `ctx.crypto.hash(...)`。这是有意的:那行调用从未返回过值,剥掉授权不会让任何还能跑的东西变坏;但把它一并「修好」会让作者失去唯一一个还在提醒他「这里有段死代码」的信号。`retiredFromLoadPath: true` —— 枚举当场拒绝,活作者在 parse 时就被教育,转换存在的意义是让已存的 16.x / 17-rc 行重放干净(否则永远被打成 `metadata_spec_invalid`,把链上历史误标成当期违约)以及让 `os migrate meta --from 16` 改写作者源。

.github/workflows/ci.yml

@@ -75,11 +75,13 @@ jobs:
               - '.github/workflows/ci.yml'
 
   test:
-    # Sharded 2-way BY PACKAGE: a core-touching PR ran the affected suite
-    # ~11½ min on one 4-vCPU runner — the longest pole in the whole workflow.
-    # scripts/partition-test-shards.mjs splits the package list into two
-    # deterministic, test-file-count-balanced halves (573/572 at the time of
-    # writing) and each shard runs its half through turbo. NOT the dogfood
+    # Sharded 3-way BY PACKAGE: a core-touching PR ran the affected suite
+    # ~11½ min on one 4-vCPU runner — the longest pole in the whole workflow —
+    # and at 2 shards the slower shard still ran ~10 min, keeping merge-queue
+    # builds at ~11 min end-to-end (#4859).
+    # scripts/partition-test-shards.mjs splits the package list into three
+    # deterministic, test-file-count-balanced thirds and each shard runs its
+    # slice through turbo. NOT the dogfood
     # job's vitest --shard passthrough, deliberately: that works for dogfood
     # because it is ONE package with ~60 files, but applied workspace-wide,
     # vitest 4 hard-fails every package with fewer test files than the shard
@@ -90,13 +92,13 @@ jobs:
     # Branch protection requires the bare "Test Core" context, which a matrix
     # can never publish again — the test-gate job below carries that name
     # (the #3622 lesson; see dogfood-gate).
-    name: Test Core (${{ matrix.shard }}/2)
+    name: Test Core (${{ matrix.shard }}/3)
     needs: filter
     if: needs.filter.outputs.core == 'true'
     runs-on: ubuntu-latest
     # Backstop only — the stall guard on the test steps is the primary
     # detector for a #4250-style hang and fires well before this. 30 min is
-    # ~4× a normal sharded run (~6-7 min), with margin for a cold Turbo cache;
+    # ~5× a normal sharded run (~4-6 min), with margin for a cold Turbo cache;
     # the old 45 left a hung job "running" for half an hour past any plausible
     # healthy finish.
     timeout-minutes: 30
@@ -105,7 +107,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2]
+        shard: [1, 2, 3]
 
     steps:
       - name: Checkout repository
@@ -190,7 +192,7 @@ jobs:
             pnpm exec turbo ls --output=json > "$RUNNER_TEMP/turbo-ls.json"
           fi
           node scripts/partition-test-shards.mjs "$RUNNER_TEMP/turbo-ls.json" \
-            --shard ${{ matrix.shard }}/2 --exclude @objectstack/dogfood \
+            --shard ${{ matrix.shard }}/3 --exclude @objectstack/dogfood \
             > "$RUNNER_TEMP/shard-packages.txt"
           echo "Packages on this shard:"
           cat "$RUNNER_TEMP/shard-packages.txt"
@@ -499,18 +501,19 @@ jobs:
               test
 
   dogfood:
-    # Sharded 2-way: the suite is ~60 independent test files, each booting its
-    # own in-process app, and a single 4-vCPU runner needed ~7½ minutes for the
-    # lot — the longest pole in the whole workflow. vitest partitions the file
-    # list deterministically across shards; both shards must pass. If branch
-    # protection lists "Dogfood Regression Gate" as a required check, it must be
-    # updated to the two sharded check names.
-    name: Dogfood Regression Gate (${{ matrix.shard }}/2)
+    # Sharded 3-way: the suite is ~60 independent test files, each booting its
+    # own in-process app; a single 4-vCPU runner needed ~7½ minutes for the
+    # lot, and at 2 shards each half still ran ~7 min — the longest pole left
+    # once Test Core went 3-way (#4859). vitest partitions the file list
+    # deterministically across shards; all shards must pass. Branch protection
+    # requires only the bare "Dogfood Regression Gate" context, carried by the
+    # dogfood-gate job below — the shard count can change without touching it.
+    name: Dogfood Regression Gate (${{ matrix.shard }}/3)
     needs: filter
     if: needs.filter.outputs.core == 'true'
     runs-on: ubuntu-latest
     # Backstop only — the stall guard on the test step is the primary detector
-    # for a #4250-style hang (see Test Core). 30 min is ~4× a shard (~7 min;
+    # for a #4250-style hang (see Test Core). 30 min is ~6× a shard (~5 min;
     # the verify-CLI pass that used to ride shard 1 is its own parallel job
     # now — dogfood-verify below).
     timeout-minutes: 30
@@ -519,7 +522,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2]
+        shard: [1, 2, 3]
 
     steps:
       - name: Checkout repository
@@ -552,7 +555,10 @@ jobs:
       # Shard-scoped key: the turbo test hash differs per shard (pass-through
       # args are part of the task hash). Restore-only on PRs — see the Restore
       # Turbo cache comment in the test job; the save step at the end of this
-      # job seeds from main only.
+      # job seeds from main only. The job-level catch-all (same as Test Core's)
+      # is what keeps a NEW shard number warm before main has ever saved it:
+      # turbo's cache is content-addressed per task, so another shard's entries
+      # replay the shared build closure even when the test slice differs.
       - name: Restore Turbo cache
         uses: actions/cache/restore@v6
         with:
@@ -561,6 +567,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-${{ github.ref_name }}-
             ${{ runner.os }}-turbo-${{ github.job }}-${{ matrix.shard }}-
+            ${{ runner.os }}-turbo-${{ github.job }}-
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -585,7 +592,7 @@ jobs:
           mkdir -p "$RUNNER_TEMP/stall-reports"
           node scripts/run-with-stall-guard.mjs --log "$RUNNER_TEMP/dogfood.log" --stall-minutes 10 \
             --report-dir "$RUNNER_TEMP/stall-reports" -- \
-            pnpm turbo run test --filter=@objectstack/dogfood -- --shard=${{ matrix.shard }}/2
+            pnpm turbo run test --filter=@objectstack/dogfood -- --shard=${{ matrix.shard }}/3
 
       # Dogfood boots real apps in-process, so a native/OOM abort is likelier
       # here than in the unit suites — and a shard that dies silently looks like