Merge remote-tracking branch 'origin/main' into claude/issue-4793-batch-row-result-schema-work

Author: claude

.changeset/database-loader-ddl-failure-loud.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/metadata": patch
+---
+
+fix(metadata): `sys_metadata` 的 DDL 失败不再被静默吞掉 —— 只有「表已存在」这一种原因可以静音 (#4728)
+
+`DatabaseLoader.ensureSchema()` 过去用一个空 `catch` 吞掉 **全部** DDL 失败,并且照样把
+`schemaReady` 置为 `true`:
+
+```ts
+} catch {
+  // If syncSchema fails (e.g. table already exists), mark ready and continue
+  this.schemaReady = true;
+}
+```
+
+注释里的免责理由只覆盖了失败原因中最良性的一种,却用它为**所有**原因开脱。真实的失败
+(权限不足、数据源根本没连上、列类型冲突)之后,表或新列压根不存在,而进程的状态与成功
+路径**逐字节相同**,启动日志里一行痕迹都没有 —— 这正是 #4420 的形态:声称已持久化、实
+际没落盘、系统看起来完全健康。#4632 把它定成规则(AGENTS.md → "Degradation log levels"),
+机械检查 `pnpm check:durability-log-level` 已经能发现这一处。
+
+现在按**错误类型**判别,而不是按注释里的乐观假设:
+
+- **良性的「已存在」**(SQLite 的 `table … already exists` / `duplicate column name`、
+  Postgres 的 SQLSTATE `42P07`/`42701`/`42710`、MySQL 的 `ER_TABLE_EXISTS_ERROR` 等及其
+  `errno`,并跟随 `cause` 链)—— 表确实已就绪,当作 no-op 静默通过,并照常执行后续的
+  `project_id → environment_id` 迁移与 ADR-0005 索引。
+- **其余一切失败** —— 以 `console.error` 上报,文案同时说清**后果**(`sys_metadata` 的表/
+  列未创建,后续每一次元数据写入都会报错、或在宽松驱动上悄悄丢列,而服务器仍报告健康)
+  与**修复动作**(修掉下面那条驱动/数据源错误后重启)。只说**一次**,不是每次写入都刷屏。
+- `schemaReady` **不再**在真实失败后置 `true`。启动依旧不被阻断(该方法不抛),但 loader
+  不再声称一个它并不具备的就绪状态,下一次元数据操作会重试 —— 数据源只是还在连接这类瞬
+  时故障因此可以自愈,恢复时补一条 `info`。
+
+`ensureHistorySchema()` 按同一规则对齐:良性「已存在」不再每次写入都打一条 `error`(过度
+使用 `error` 是镜像失败),真实失败则同样只响亮一次并保持重试。
+
+无 API / schema 变更;新增内部工具 `isSchemaAlreadyExistsError()`(未从包入口导出)。
+`scripts/durability-degradation.baseline.json` 中指向本单的条目随之删除(该文件 shrink-only)。

.changeset/http-protocol-discovery-two-shapes.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(protocol): `protocol/kernel/http-protocol` 的 API Discovery 一节拆成两段式 —— `@objectstack/rest` 服务的 `/api/v1`(与 `/api/v1/discovery`)与 dispatcher 服务的 `/.well-known/objectstack` 各给一份真实响应形状,不再共用一份混合示例。Docs-only;releases nothing.

.changeset/lint-searchable-fields-type-validation.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): 视图 `searchableFields` 按运行时同一套判定做构建期校验 —— 一个 lookup 笔误不再等到 400 才暴露 (#4830)
+
+视图(list view)的 `searchableFields` 会被客户端逐字回显为 `$searchFields` 覆盖参数,而
+REST 入口闸(#4254)会用 `resolveSearchFieldResolution`(`@objectstack/spec/data`)判定
+该对象的可搜索集合 —— 声明一个 lookup 等「不可搜索」字段,运行时会把**整条查询** 400
+(`INVALID_FIELD`),列表工具栏搜索对全体角色彻底不可用。此前 `compile`/`validate` 只查
+字段**存在性**,这类笔误全绿放行,只能靠人肉点搜索框发现。
+
+新增规则 `searchable-field-unsearchable`(error 级,新导出常量同名):对每个视图级
+narrowing(对象内建 `listViews`、`defineView` 的 `list`/`listViews`、react 页面的
+`<ListView searchableFields>`)按**运行时同一个函数**(`resolveSearchFieldResolution`,
+非复制的类型清单,杜绝再度漂移)判定 declared = enforced:
+
+- 对象未声明 `searchableFields`(auto 源):视图里出现 lookup/json/hidden/审计列等
+  auto-default 拒绝的字段 → 构建期 error,信息含类型与 400 后果,lookup 给出「镜像到本
+  对象 text/formula 字段」的处方;
+- 对象已声明(declared 源):视图条目超出对象声明集合 → 构建期 error(视图只能收窄、
+  不能放宽,ADR-0061);
+- 对象自身的 `searchableFields`(canonical)维持**只查存在性**:运行时 declared 分支按
+  存在过滤、不按类型过滤,声明即被引擎执行,构建期拒绝会误伤运行时接受的元数据
+  (ADR-0072 D1);
+- 注册表注入的系统列在 narrowing 中跳过判定(其运行时元数据对 linter 不可见,宁可漏报
+  不可误报)。
+
+内部核心 `checkSearchableFieldList` / `indexObjectSearchTargets`(模块级导出,未入包
+barrel)签名有变:索引值从 `Set<string> | null` 变为 `ObjectSearchTarget | null`,并新增
+可选 `role: 'canonical' | 'narrowing'`(默认 `'narrowing'`)参数。

.changeset/retire-activation-events.md

@@ -0,0 +1,65 @@
+---
+"@objectstack/spec": major
+---
+
+refactor(spec)!: remove `activationEvents` (both keys) and the `ActivationEventSchema` vocabulary — lazy activation that no runtime ever implemented (#4657, ADR-0049)
+
+`activationEvents` promised lazy plugin activation ("plugins remain dormant
+until an activation event fires") on two authorable surfaces —
+`DynamicLoadRequest.activationEvents` (`@objectstack/spec/kernel`) and
+`StudioPluginManifest.activationEvents` (`@objectstack/spec/studio`, the
+`defineStudioPlugin` input) — and **no runtime in objectstack / cloud /
+cloud-v1 / objectui ever read either key** (four-repo bare-name scan in #4657,
+re-verified at implementation time). Every plugin has always activated
+immediately on load/registration; cloud-v1's own ROADMAP recorded lazy
+activation as ❌ unimplemented (planned v0.4.0). That is ADR-0049's
+declared ≠ enforced shape in the semantically-lying direction: an author
+writing `activationEvents: [{ type: 'onMetadataType', pattern: 'flow' }]`
+expected deferral and got eager activation with a clean parse.
+
+#4653 had just converged the two `ActivationEventSchema` declarations onto one
+structured `{ type, pattern }` form inside this same unreleased major; with the
+enforce-or-remove ruling landing on **remove**, that converged vocabulary
+retires before ever shipping. Composed across the two changes, a v16 author
+simply deletes the key in whichever form they carried.
+
+Migration (FROM → TO):
+
+- `activationEvents` in a `defineStudioPlugin` input / `StudioPluginManifest`
+  value — v16 string form (`['*']`, `['onMetadataType:flow']`) or v17-rc
+  structured form (`[{ type: 'onStartup', pattern: '*' }]`) alike →
+  **delete the key**. There is no replacement value: eager activation is the
+  only behaviour there has ever been, and `activate()` still runs at
+  registration time. The strict manifest parse rejects the key (and its former
+  VS Code-flavoured aliases `activation` / `events` / `onActivate`) with this
+  prescription.
+- `activationEvents` in a `DynamicLoadRequest` value → **delete the key**.
+  Tombstoned, not silently stripped — `DynamicLoadRequestSchema` is not
+  `.strict()`, so a `retiredKey()` tombstone makes authoring it a `tsc` error
+  and a parse error carrying the prescription.
+- `import { ActivationEventSchema, ActivationEvent } from '@objectstack/spec/kernel'`
+  (or `/studio`) → **no replacement export** (TS2305 after upgrade). Nothing
+  consumed the vocabulary; an exported schema with no consumer is read as a
+  capability by whoever finds it (#3950), so the orphaned def goes with the
+  keys.
+- Lazy activation is a **new capability**: if it is ever built it returns via
+  the enforce route of ADR-0049 through a new ADR — executor first, vocabulary
+  second — not by re-declaring inert keys.
+
+Self-check (#4535 §5): TS2305 — yes, two removed exports on two entries;
+metadata migration — none possible or needed (`StudioPluginManifest` is TS
+configuration parsed by `defineStudioPlugin`, a root schema never stored in
+`sys_metadata`; `DynamicLoadRequest` is a runtime request shape with no
+caller — no stored row exists for a D2 conversion to rewrite, so the change is
+one ADR-0087 D3 semantic record, `plugin-activation-events-retired`); shape
+change — two keys removed, zero behaviour change (eager activation before and
+after, byte-identical).
+
+The retirement kit: `retiredKey()` tombstone on the non-strict kernel schema;
+strict-parse `guidance` prescriptions on the studio manifest (including the
+three former aliases); ADR-0087 D3 semantic migration; baselines
+(`authorable-surface.json` — one `[RETIRED]` line, five lines dropped
+deliberately with the defs; `json-schema.manifest.json` — `kernel/ActivationEvent`
+and `studio/ActivationEvent` def removals; `api-surface.json`) regenerated
+deliberately; compiler-API export pin (`activation-events-retirement.test.ts`,
+zero holders across every public entry) — sabotage-verified.

.changeset/startup-registry-verdict-guard.md

@@ -0,0 +1,10 @@
+---
+---
+
+Tooling-only: `pnpm check:startup-registry-verdict` — startup registry reads may not record a verdict the boot can still contradict (#4777). Adds `scripts/check-startup-registry-verdict.mjs` + the shrink-only `scripts/startup-registry-verdict.baseline.json` (empty on landing), a `Lint & Type Check` step, and an AGENTS.md section. Releases nothing — no package changes.
+
+One showcase cold start on 2026-08-03 produced three instances of one shape in three unrelated subsystems written by three people at three times: ask a registry "is X there?" while the boot is still filling it, treat the "no" as final, and **record** it — cached on the instance (#4772 plugin-auth), asserted in a `warn` (#4771 service-automation), or written to the database (#4769 objectql). The provider registers a moment later and nothing undoes the record. All three are fixed; this is what stops the class from coming back.
+
+The gate matches the three-part shape, and part 3 is what makes it a rule rather than noise — a read-only probe stays completely legal, and the cures are never flagged: a probe deferred into a lazy accessor or a `kernel:ready` hook, a probe whose ordering an ADR-0116 declaration (`dependencies` / `optionalDependencies` / `requiresServices`) has already made final, and a verdict drawn at a declared seal (`sealNodeTypeVocabulary()`) all pass.
+
+Its reach is stated rather than implied: it under-matches on purpose. `getService('cache')` is visible, a `resolveCacheOrFallback()` three layers down another package is not, and #4769 is invisible to it entirely — that "registry" is the `sys_migration` table in a database. This stops the bleeding; it does not cure. Whether the kernel contract should be tightened further is #4776.

.changeset/sys-comment-retire-visibility-reply-count.md

@@ -0,0 +1,68 @@
+---
+"@objectstack/plugin-audit": minor
+---
+
+feat(plugin-audit)!: retire `sys_comment.visibility` and `sys_comment.reply_count` (#4756, ADR-0049)
+
+Both fields were modelled with **zero** runtime consumers — nothing in this repo,
+in `objectui`, or in `cloud` ever read or maintained either one. ADR-0049
+enforce-or-remove; maintainer decision: remove both. Same disposition, and for
+the same stated reason, as `sys_attachment.share_type` / `sys_attachment.visibility`
+in #2755 ("attachment access is derived from the parent record").
+
+**REMOVED — `sys_comment.visibility`** (`'public' | 'internal' | 'private'`,
+defaulted `'public'`).
+
+This one is a **security-looking key with no gate behind it**, which is the
+primary reason it goes rather than stays. No code path consulted it: not
+`enforceFeedsCapability`, not the record-level gates added in #4630, not the
+REST layer, not objectui's discussion panel. A comment an author marked
+`private` was visible to exactly the same people as a `public` one — an app
+author (or an AI authoring metadata) reading the field list would reasonably
+believe otherwise, and get a silent security failure instead of an error. That
+is the Prime Directive #10 trap in its textbook shape.
+
+There is **no replacement key**: after #4630, who can see a comment is decided
+by the record-level permissions of the record its `thread_id` names — one
+coherent rule. A per-row enum layered on top would be a second source of truth
+for the same question. The enum's only genuinely missing meaning ("hidden from
+external/portal principals") depends on external principals existing at all,
+which waits on ADR-0090 D11's `externalSharingModel`; today there is nobody to
+hide a comment from. This does not foreclose that design — when portals land,
+a visibility key can return **enforce-first**, with a real gate and tests.
+
+**FROM → TO:** stop sending `visibility` on `sys_comment` writes; to restrict
+who sees a discussion, restrict who can read the record `thread_id` points at.
+
+**REMOVED — `sys_comment.reply_count`** (`number`, `defaultValue: 0`,
+`readonly: true`).
+
+Never incremented anywhere, and `readonly` meant an author could not set it by
+hand either, so every row read `0` forever — a UI binding an "N replies" badge
+to it rendered `0` for every thread. Deliberately **not** replaced by an
+`afterInsert`/`afterDelete` roll-up: the predicate/bulk write-hook gaps tracked
+by #4770 / #4778 / #4779 (a hook that returns early without a single-record id
+lets the whole bulk operation through) are exactly where a hook-maintained
+counter drifts — a bulk delete of replies would never decrement it. A counter
+that drifts is worse than no counter, because both the UI and an AI reading the
+record trust it. If a badge needs the number, aggregate `parent_id` children at
+read time; a designed roll-up can be revisited once #4775's family has settled
+bulk-hook semantics.
+
+**FROM → TO:** replace reads of `reply_count` with a count of `sys_comment` rows
+whose `parent_id` is the comment's id.
+
+**Stored data.** Existing databases keep both columns as **unmanaged leftovers**
+— no migration, matching #2755. What changes where:
+
+- **Reads are loud everywhere.** The read-axis gates (#4134 / #4226) resolve
+  field names from the object schema, not from the table, so a filter, sort,
+  `select` or `expand` naming `visibility` / `reply_count` now answers
+  `400 INVALID_FIELD` on every deployment, leftover column or not. A "0 replies"
+  badge that silently lied becomes an error that names itself.
+- **Writes are loud on new databases only.** A database provisioned after this
+  change has no such column, so the write fails at the driver and is mapped to
+  the same `400 INVALID_FIELD` envelope. On a pre-existing database the leftover
+  column still accepts a value nothing will ever read — record validation does
+  not reject undeclared keys. Dropping the two columns is an optional manual
+  cleanup, not a requirement.

.github/workflows/lint.yml

@@ -204,6 +204,24 @@ jobs:
       - name: Durability-degradation log-level guard
         run: pnpm check:durability-log-level
 
+      # Startup registry-verdict guard (#4777). One showcase cold start produced
+      # three instances of one shape in three unrelated subsystems: ask a
+      # registry "is X there?" while the boot is still filling it, treat the
+      # "no" as final, and RECORD it — cached on the instance (#4772
+      # plugin-auth), asserted in a warn (#4771 service-automation), or written
+      # to the database (#4769 objectql). The provider registers a moment later
+      # and nothing undoes the record. This gate walks the AST for that
+      # three-part shape: a pre-ready registry read (init()/constructor, or an
+      # ADR-0018 open capability registry before its seal) whose absent verdict
+      # is recorded. Reading is legal and must stay legal — a probe licensed by
+      # an ADR-0116 declaration, or one deferred into a closure/kernel:ready
+      # hook, is exactly the fix and is never flagged. Deliberately narrow: it
+      # cannot see a probe behind an indirection in another package, and it
+      # cannot see #4769 at all (that "registry" is a database table). Runs its
+      # own --self-test first.
+      - name: Startup registry-verdict guard
+        run: pnpm check:startup-registry-verdict
+
       # Release-notes drift guard: the platform is one version-locked train, so
       # every released @objectstack/spec major must have a curated, navigable
       # release page at content/docs/releases/v<major>.mdx. Catches the gap that