Merge remote-tracking branch 'origin/main' into claude/issue-6259-batch-alias-row-retirement

Author: claude

.changeset/action-descriptor-is-async-retired.md

@@ -0,0 +1,48 @@
+---
+'@objectstack/spec': major
+'@objectstack/service-automation': patch
+'@objectstack/plugin-approvals': patch
+---
+
+refactor(spec)!: retire `ActionDescriptor.isAsync` — a second spelling of `supportsPause` that nothing ever read (#6748, ADR-0049)
+
+<!-- adr-0087: registered action-descriptor-is-async-retired -->
+
+**FROM → TO:** `isAsync: true` → delete the key; declare `supportsPause: true` (plus the
+`resumeAuthority` its pauses need) and return `suspend: true` from `execute()`.
+`isAsync: false` → delete the key; there was never anything to preserve.
+
+`ActionDescriptor.isAsync` declared "suspends the flow awaiting an external reply" and no
+execution path read it. Measured fresh before removal across all three repos — objectstack,
+objectui and cloud — with zero property reads: every hit was the declaration itself, a
+generated baseline, one of five shipped descriptors WRITING it, a fixture pinning the
+shape, or prose. Declaring it never made a node suspend; omitting it never stopped one.
+
+This is the remove leg of the ADR-0049 disposition its sibling took the other way. The two
+keys said the same thing — "this node type can suspend the run" — and #6667 split them by
+evidence: `supportsPause` became an enforced fact (`AutomationEngine` now refuses a
+suspension whose type does not declare it, at the one seam every suspension passes
+through), while `isAsync` had no consumer to grow into. Keeping both would leave the
+platform publishing two names for one capability with only one of them honoured — and
+`screen` declared BOTH, so a plugin author copying it had no way to tell which.
+
+The retirement kit:
+
+- **Tombstone, not deletion** (`retiredKey()`): `ActionDescriptorSchema` is not `.strict()`,
+  so a plain delete would let existing descriptors parse clean and lose the key in silence
+  (the ADR-0104 shape). Authoring `isAsync` now fails `tsc` at the descriptor literal and
+  fails the parse inside `defineActionDescriptor()` — with the prescription in the message.
+- **ADR-0087 D3 `SemanticMigration`** (`action-descriptor-is-async-retired`) plus the exact
+  `RETIRED_KEYS_BY_MAJOR` entry. No D2 conversion, deliberately: a descriptor is published
+  from an executor's TypeScript and never stored in stack metadata, so there is no source
+  for `os migrate meta` to rewrite — the `EnhancedApiError.fieldErrors` disposition.
+- The five shipped writers stop writing it (`screen`, `map`, `wait`, `approval`,
+  `approval_revise`); the descriptors they publish lose the key, which is why the two
+  runtime packages appear here.
+- Generated baselines (`authorable-surface/automation.json` gains `[RETIRED]`,
+  `authorable-defaults/automation.json` loses the default line), `spec-changes.json`, the
+  upgrade guide and the reference docs regenerated.
+
+No runtime behaviour changes — that impossibility is the reason for the removal. The same
+commit also corrects `supportsPause`'s TSDoc, which still described itself as a declaration
+no execution path reads; #6667 made that false (#6749).

.changeset/api-endpoint-schema-strict.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/spec": minor
+---
+
+<!-- adr-0087: not-required (no-migration-prescription) this change retires NO key. The endpoint vocabulary is byte-identical and only the unknown-key POSTURE moves, from strip to reject. Nothing exists for `objectstack migrate meta` to rewrite, because an undeclared key was never honoured in the first place: it was dropped at parse and so never reached storage, the matcher or the executor. No stored shape carries one, and no authored shape that ever WORKED becomes invalid. There is also no single FROM/TO rule a ledger entry could state, since what is now refused is an open set of author typos rather than a renamed key. The upgrade channel is the schema rejection itself, which is strictly more specific than any ledger line: it names the offending key at the author's own path and carries either the canonical spelling or a wrong-layer pointer at the surface that really owns the key. The one ADR-0087 entry that DOES govern this surface, `declarative-apis-endpoints-live`, is already registered for protocol 17 and is updated by this PR rather than duplicated. Measured blast radius: 0 affected entries across `examples/*` (2 endpoints) and the `cloud` repo (0 endpoints). -->
+
+`ApiEndpointSchema` rejects undeclared keys (#5384), and the author-state type is named on the upgrade path (#5227)
+
+`api` became a registered metadata type at #5312, which made
+`packages/spec/src/api/endpoint.zod.ts` an AUTHORING surface — `defineStack({ apis })`,
+the Studio metadata-admin form, and `PUT /meta/api/:name`'s 422 — while it was still a
+plain open `z.object`. An undeclared key was therefore dropped on every path: a
+`cacheTTL` / `objectParam` / `outputMappings` typo parsed green, published green, and the
+endpoint then served without the policy or projection its author wrote. That direction is
+fail-safe for `authRequired` alone (an unrecognized spelling leaves the default `true`
+standing); it was never fail-safe for the mapping, cache and rate-limit blocks.
+
+The shape is now `strictObject`, so an undeclared key is a named rejection carrying the
+surface, the offending key and a rename. Two curated wrong-layer prescriptions ship with
+it:
+
+- **`namespace`** — ADR-0121 D2 derives the namespace segment of `path` from
+  `manifest.namespace`; it has never been per-endpoint, so the rejection points at the
+  manifest instead of suggesting a rename.
+- **the six stored-envelope bookkeeping keys** (`packageId`, `state`, `version`,
+  `published*`) — written onto the stored ROW by `register` / `publishPackage`, never onto
+  a declaration.
+
+**The order this landed in is the part worth keeping.** Closing the shape was measured and
+REFUSED first: the same schema parsed STORED rows at `buildEndpointIndex` and
+`gateApiItemsForPublish`, so a naked `strictObject` failed every row with
+`unrecognized_keys: ['packageId', 'state']` — the load-time backstop excluded the endpoint
+(404) and the publish gate reported a schema error in place of the ADR-0121 D6 verdict it
+exists to give. The debt was real and it was not in this vocabulary, so #5309 (PR #6576)
+paid it at the layer that owned it (`peelStoredEnvelope`). `ApiEndpointSchema` never
+learned a bookkeeping key.
+
+**Breaking for metadata that was already silently broken.** An `apis:` entry carrying an
+undeclared key now fails `objectstack validate`, `objectstack build` and the metadata write
+path instead of publishing with the key discarded. Measured before landing: the example
+corpus (2 endpoints) and the `cloud` repository (0 endpoints) carry zero undeclared keys,
+so nothing in-tree changes verdict.
+
+`api` also leaves the #4001 campaign's `STILL_STRIP` list — closed registered types 24 → 25
+of 26, with `view` the only entry left — and the CLI metadata gate's row moves from
+`NOT_YET_CLOSED` into `GATED_AT`.
+
+**#5227** — no schema change. `ApiEndpoint` already denotes the AUTHOR state after ADR-0122
+phase 2, so omitting `authRequired` compiles; what was missing was anywhere saying so. The
+`declarative-apis-endpoints-live` upgrade-guide entry, whose whole safety argument is that
+"an omission is SAFE", now carries the type annotation that makes the omission writable:
+annotate declarations `ApiEndpoint`, hold parse results as `ApiEndpointParsed`.

.changeset/authored-row-write-verdict.md

@@ -0,0 +1,41 @@
+---
+'@objectstack/spec': minor
+'@objectstack/plugin-security': minor
+---
+
+security: add a fail-closed authored-row-write verdict to `ISecurityService`
+
+`ISecurityService` gains an optional, verdict-shaped, by-id method:
+
+```ts
+checkAuthoredRowWrite?(
+  object: string,
+  recordId: string,
+  operation: AuthoredRowWriteOperation, // 'update' | 'delete'
+  context?: SecurityContext,
+): Promise< AuthoredRowWriteVerdict >;  // 'admit' | 'abstain'
+```
+
+It answers one question no existing surface could: does an **app-authored**
+row-level security policy admit this row for this write, on its own, with the
+platform's ownership floor taken out by provenance?
+
+Every other method reports the **composed** RLS verdict, and sitting inside that
+composition is the platform's own wildcard write floor (`created_by ==
+current_user.id`, shipped on the `member_default` baseline every authenticated
+member resolves additively). So "the composed RLS admits this row" is true for
+the row's CREATOR whether or not any app policy mentions it — which makes it a
+measurably different question, not a cheaper spelling of the same one. A caller
+deferring to the composed answer would hand transferred records back to their
+former creators.
+
+`admit` iff at least one applicable, non-floor policy matches the row for the
+operation. `abstain` in every other case — no authored policy, no match, an
+unreadable or cross-tenant row, a principal-less or on-behalf-of context, or any
+internal failure. The method never throws outward, and it is **optional**: a
+deployment whose security service omits it behaves byte-for-byte as before,
+because callers feature-detect and read absence as `abstain`.
+
+`@objectstack/plugin-security` implements it on the registered `security`
+service, reading the verdict off the same layered RLS computation the middleware
+enforces with — no second RLS evaluator.

.changeset/d3-resume-authority-supportspause-enforced.md

@@ -0,0 +1,34 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): D3 迁移账本里 `resumeAuthority` 那条的验收标准不再要求手工排查 `supportsPause` 不一致 —— #6746 之后引擎自己会拒绝 (#6844)
+
+`MIGRATIONS_BY_MAJOR[17].semantic` 中 `action-descriptor-resume-authority-default-flip`
+一条的 `acceptanceCriteria`,结尾的 ⚠️ 子句写的是:
+
+> `supportsPause` is a declaration nothing enforces (#5703), so an executor whose
+> `execute()` returns `suspend: true` while leaving `supportsPause` false is warned
+> about by NEITHER channel — check those by hand against the same rule.
+
+写下时属实,PR #6746(#6667,2026-08-08 合入)之后不再属实:
+`AutomationEngine.refuseUndeclaredSuspension` 正是拒绝这一类执行器的,拒绝点在
+`executeNode` 里每个 `result.suspend === true` 都要经过的那一个接缝
+(`packages/services/service-automation/src/engine.ts`)。于是一个 v17 升级者被告知
+去手工审计一类引擎已经自己拒绝的错误,而且被告知这个不一致「没有声音」,实际上它很响。
+
+这不是内部注释:该字符串被 `gen:upgrade-guide` 逐字投影进
+`docs/protocol-upgrade-guide.md` 的 "Done when" 行,而那正是升级作者(依 ADR-0033,
+往往是 AI)读的那一行,所以本 PR 一并提交了重新生成的产物。
+
+**改后的说法,以及为什么不是「什么都不用查了」**:两条告警通道(启动告警、
+`check:resume-authority-declared`)确实仍然都以 `supportsPause: true` 为触发条件,
+所以「不被任何告警通道覆盖」这半句保留;变化的是它现在会在运行时被拒绝,且属于
+guard-class —— `fault` 边路由不了(`refuseNode` 打的是 `errorClass: 'guard'`,
+`executeNode` 在 `errorClass === 'guard'` 时不去找 `fault` 边)。同时刻意没有过度
+更正:该守卫明确不判「完全没有注册描述符」的执行器(engine.ts 中
+"What it does NOT judge → Silence",由 `supports-pause-runtime-enforcement.test.ts`
+的 descriptor-less 用例钉住),这类执行器的暂停照样会被创建,只在 resume 路由上才
+被拒绝,所以这一条作为仍需留意的残留被写进了新文案。
+
+受理面(schema 接受什么)逐字节未变 —— 本条只动账本散文与其生成产物。

.changeset/groupby-alias-multi-face.md

@@ -0,0 +1,101 @@
+---
+"@objectstack/driver-sql": minor
+"@objectstack/driver-turso": minor
+"@objectstack/driver-sqlite-wasm": minor
+"@objectstack/spec": minor
+"@objectstack/objectql": patch
+---
+
+feat(drivers,spec)!: `GroupByNode.alias` is honoured by the SQL faces — one aggregate, one column key (#6401)
+
+`GroupByNodeSchema` has declared `alias` ("Alias for the projected group
+value", defaulting to `field`) for as long as the structured `groupBy` entry has
+existed. Exactly one execution path read it. The result: the SAME query came
+back with a different result-column key depending on which path the engine
+happened to take.
+
+```ts
+groupBy: [{ field: 'closed_at', dateGranularity: 'month', alias: 'qtr' }]
+```
+
+- pushed down to a driver ⇒ rows keyed **`closed_at`**
+- run through the in-memory fallback ⇒ rows keyed **`qtr`**
+
+And the choice between them is `engine.ts`'s
+`allStructuredSupported && !tzRequiresInMemory` — a driver capability bit and a
+`timezone`, neither of which the caller can see. That is the multi-face
+consistency invariant broken in its quietest form: both answers are valid rows,
+so nothing throws and nothing looks wrong.
+
+**Resolved to ENFORCE**, and the leg was chosen by measurement rather than
+taste. ADR-0049 splits on whether the feature already exists: a *dangling*
+promise is removed, a *live* one with a missing gate is enforced. `alias` is
+live — three consumers read it and change behaviour
+(`in-memory-aggregation.ts`, `MemoryDriver.performAggregation`, and
+`chartAggregateCategoryKey`), and the publish gate *compels* it:
+`validate-react-page-props.ts` errors `REACT_CHART_AXIS_UNKNOWN` unless a
+chart's category axis is bound to `alias ?? field`, telling the author in so
+many words to "bind it to" the alias. A key the build gate makes you write is
+not a dangling promise. The count of real non-test producers is **zero**, which
+is what makes enforcing safe rather than what argues against it: no shipped
+payload changes its result keys.
+
+**What changed, on every SQL face at once** — a fix landing on one and not its
+twin is the #6203 shape, and `TursoDriver` picks its face from `url`:
+
+- **`driver-sql`** — both limbs of the structured `groupBy` branch project
+  `alias ?? field`: the date-bucket limb aliases the bucket expression to it,
+  and the plain limb emits `?? as ??` (only when the name actually moves — an
+  alias equal to the field emits no self-rename). `presentedOutput` is now keyed
+  by the OUTPUT column, matching how the aggregation branch beside it has always
+  worked; an aliased group value went unpresented before.
+- **`driver-turso` REMOTE** — the same projection, `"field" AS "alias"`. The
+  alias reaches the statement as a quoted identifier and is therefore held to
+  `assertSafeIdentifier`, exactly like `field`.
+- **`driver-sqlite-wasm`** — inherits `SqlDriver`'s compiler; covered by its own
+  conformance suite rather than by assumption.
+
+**GROUP BY still keys on the FIELD** on every face. Only the projection is
+renamed, so the buckets are unchanged. This is deliberate and pinned: SQLite
+resolves output names in `GROUP BY`, so a face that grouped by the alias would
+look correct here and diverge on a dialect that does not.
+
+`having` needed no change and now means one thing: it is applied over the
+aggregated row's own columns, so a filter on a group projection references the
+alias on every path — previously the alias on one path and the field on the
+other.
+
+**Conformance.** `AGGREGATION_CASES` (#6409) gains a `groupByAlias` axis and two
+cases. Their VALUES are an existing case verbatim — only the key moves — so they
+can fail only on the key, which is the point: every wrong answer in this area is
+a valid query returning plausible rows. `objectql`'s in-memory fallback is now
+**enrolled** as a fourth face, answering #6409's open question ②: it is the face
+the SQL three were converged onto, so the new behaviour would otherwise be
+pinned against nothing, and reaching it needs no engine at all —
+`applyInMemoryAggregation` is a pure function of rows and an AST.
+
+**Reverse verification**, predicted before running. Reverting the in-memory face
+to `g.field`: only the two alias cases move and only ONE fails — the degenerate
+`alias === field` case stays green, which is why both are in the table.
+Reverting the harness to read `c.groupBy` instead of `c.groupByAlias ?? c.groupBy`
+— the copied-neighbour mistake: everything passes on an unmodified face, a false
+GREEN, which is the failure mode that would have made the axis vacuous.
+
+**Frozen drivers (#5499), measured from source, not flipped.** `driver-memory`
+already returned `{ field, alias: node.alias ?? node.field }` and projects under
+the alias — it had independently reached the enforce answer, so it needed no
+alignment. `driver-mongodb` is a recorded DEBT row and the defect is wider than
+`alias`: `buildAggregationPipeline` types `groupBy` as `string[]` and builds
+`groupId[field] = '$' + field`, so a structured node — aliased or not — becomes
+the literal key `"[object Object]"`. It cannot take a structured `GroupByNode`
+at all; `mongodb-driver.ts` passes `(query as any).groupBy`, which is why `tsc`
+never saw it. Tracked on #6814.
+
+**Compatibility.** A caller who writes `alias` and reads the result under
+`field` on a pushdown path will now find the value under `alias` — which is what
+the key has always meant on the fallback path, and what the chart gate already
+required. Callers who never write `alias` are unaffected: the emitted SQL is
+byte-identical.
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing is retired: `GroupByNodeSchema.alias` keeps its declaration, its spelling and its type — it starts being HONOURED by three faces that parsed and ignored it. There is no tombstone to write and no authored metadata to rewrite, so there is no mechanical transform a migration could prescribe: every stack that validated before validates after, unchanged. The behaviour change is in the RESULT of a runtime query (a result-column key moves from `field` to `alias` on the pushdown path, converging on what the in-memory path and the chart publish gate already required), which the ledger has no channel for and no upgrader could apply a codemod to. The bang is on the changeset because callers who read that column by the field name must move, and the measured non-test producer count for the key is zero. -->
+

.changeset/import-job-max-rows-single-definition.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/rest': patch
+---
+
+rest 的异步导入行数上限改为直接读取 spec 的 `IMPORT_JOB_MAX_ROWS` 导出，不再自己声明一份同值字面量（#6535）。
+
+**行为没有任何变化**：两处此前都是 `50_000`，改后仍是 `50_000`，上限、`413` 文案、拒绝边界全部不动。
+这是一次一致性收敛，不是缺陷修复——因此按 patch 计。
+
+收敛掉的是一处漂移面：`packages/spec/src/api/export.zod.ts` 的那份导出带着 TSDoc，是这个
+上限的**对外说明**（喂给生成的 reference 表面）；而真正执行拒绝的是 `packages/rest`，它此前
+读的是自己那份本地 `const`，两者之间只有一句 "mirrors spec" 注释相连。没有任何 gate 比较这
+两个数——`api-surface/api.json` 只记下 `"IMPORT_JOB_MAX_ROWS (const)"` 这个**名字**，不记它的
+**值**——所以把 spec 那份改成 20_000、执行侧纹丝不动，`pnpm test` 与全部 `check:*` 依然全绿
+（本 PR 实测过）。失效方向是文档说一套、系统做一套，而 `413` 文案里内插的又是 rest 那一份，
+连报错都会自洽地说谎。现在一处定义、两处读点（`maxRows:` 与 `413` 文案）同源。