Merge remote-tracking branch 'origin/main' into claude/issue-6860-database-driver-allowlist

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/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/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` 文案）同源。

.changeset/publish-payload-namespace.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": minor
+---
+
+feat(spec,cli): carry the package namespace on the publish payload (#6760)
+
+ADR-0048's addendum defines a publish-time namespace exclusivity registry
+(`namespace → publisher`), so a cross-vendor namespace collision is caught while
+exactly one party can still fix it cheaply — the publisher, before anything ships
+— instead of surfacing at install time, where the tenant who suffers it can do
+nothing. That gate is enterprise-side (Phase A2), and it could not be built
+because the namespace never left the artifact: `PackageSchema` had no
+`namespace` field at all, `CreatePackageRequestSchema` did not accept one, and
+`objectstack package publish` transmitted `manifest_id` only. This is Phase A1,
+the open-side half that gives the gate an input.
+
+**`PackageSchema` and `CreatePackageRequestSchema` gain an optional
+`namespace`.** It mirrors `manifest.namespace` exactly — same 2-20 character
+rule (`/^[a-z][a-z0-9_]{1,19}$/`), same optionality — so the publish payload and
+the artifact manifest cannot disagree about what a namespace is. Optional is the
+ruled shape, not a convenience: the addendum's algorithm opens with
+`if (namespace is absent) -> allow`, and a package that declares no namespace
+makes no reservation and is not gated. A parity test judges both fields against
+one table of values, so a change to either side fails.
+
+**`objectstack package publish` sends it, read off the compiled artifact's
+`manifest.namespace`** — the same place the command already reads
+`manifest.id`. Three behaviours, matching the addendum's algorithm:
+
+- namespace present → it travels on the `POST /cloud/packages` body as
+  `namespace`, and is echoed in the publish summary;
+- namespace absent → the key is omitted entirely (not `null`, not `''`), so
+  "declares no namespace" never becomes a value the gate has to interpret;
+- namespace malformed → the publish is refused before any network call, naming
+  the rule and the fix.
+
+The namespace is deliberately **not** overridable by a flag or by
+`objectstack.manifest.json`, unlike `manifestId`: a reservation is only
+meaningful if it names the object-name prefix the package actually ships, and a
+second declaration surface would let a publisher reserve `foo` while installing
+`bar_*` objects. For the same reason `TemplateManifestSchema` omits the field
+rather than inheriting it.
+
+Nothing about install-time behaviour changes. The in-process install gate,
+`NamespaceConflictError`, the shareable `base`/`system`/`sys` set and the
+`OS_METADATA_COLLISION=warn` downgrade are untouched, and the install path
+acquires no network dependency.