Merge remote-tracking branch 'origin/main' into claude/issue-4001-strictness-remeasure

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/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

AGENTS.md

@@ -601,6 +601,72 @@ shrink-only.
 
 ---
 
+## Startup registry reads — never record a verdict the boot can still contradict
+
+A boot fills its registries incrementally. Asking a registry "is X there?" while
+it is still filling is fine — the answer is simply not final yet. Turning that
+not-yet into a **verdict and recording the verdict** is the defect, because the
+provider registers a moment later and nothing goes back to undo the record.
+
+Decide with **one question**, the counterpart of the degradation-log-level one:
+
+> **At the moment this code concludes "X is not registered", can a provider
+> still register X during this same boot? And is that conclusion RECORDED
+> anywhere that outlives the moment?**
+> **Yes and yes → defect.**
+
+Three parts, all three or it is not a finding:
+
+1. a read of a registry that is still filling — the service registry during
+   `init()`, or a plugin-extensible capability registry before it is sealed;
+2. a terminal conclusion drawn from "absent";
+3. that conclusion **recorded** — cached in an instance field or module binding,
+   asserted in a `warn`, or persisted.
+
+Part 3 is what makes this a rule and not noise. **A read-only probe is
+completely legal**: `AutomationEngine.getUnknownNodeTypeAudit()` reads the
+executor registry on every call, records nothing, and is correct.
+
+**Why this is a rule and not a preference.** One showcase cold start on
+2026-08-03 produced three instances, in three unrelated subsystems, written by
+three people at three times: plugin-auth froze an `undefined` cache handle into
+its config for the life of the process, so rate-limit counters never reached the
+shared store and the printed warning sent operators to provision Redis for a
+problem they did not have (#4772); service-automation asserted that eight
+approval flows "will fail at execution time" 0.8s before the executor that runs
+them was registered, and a deployment that genuinely lacked the plugin emitted
+the identical eight, so the signal could not tell the two apart (#4771); objectql
+wrote an ADR-0104 attestation into `sys_migration` during the same boot that was
+still seeding rows contradicting it, so the next restart rejected its
+predecessor's data (#4769). Whether the kernel contract itself should be
+tightened further is #4776.
+
+**The three cures, in preference order:**
+
+1. **Resolve where it is used, not where you start.** A lazy accessor or a
+   `kernel:ready` hook sees a provider that registered later —
+   `createLazyCacheRateLimitStorage()` in plugin-auth is the reference.
+2. **Declare the ordering (ADR-0116).** `dependencies` / `optionalDependencies`
+   / `requiresServices` make the kernel hoist the provider ahead or assert it
+   registered, which makes "absent" a *fact*. Tolerance belongs in the plugin's
+   own declaration, where the kernel enforces it — not in a checker's ledger.
+3. **Seal the vocabulary, then judge.** For a registry that is open by contract
+   (ADR-0018 flow node types), the host declares the moment it can no longer
+   grow — `AutomationEngine.sealNodeTypeVocabulary()`, called at
+   `kernel:bootstrapped` — and only then is an absence worth reporting.
+
+**It has teeth**: `pnpm check:startup-registry-verdict` walks the AST for that
+three-part shape and fails on it; accepted exceptions live in the shrink-only,
+hand-edited `scripts/startup-registry-verdict.baseline.json`. Like
+`check:durability-log-level` it is deliberately narrow — it cannot *discover* a
+new seam, only stop known ones from regressing, and it under-matches on purpose
+rather than risk a false positive: `getService('cache')` is visible, a
+`resolveCacheOrFallback()` three layers down another package is not, and #4769's
+"registry" is a database table it can never see. Found a new open registry? Add
+it to `OPEN_CAPABILITY_REGISTRIES` in the same PR that fixes it.
+
+---
+
 ## Post-Task Checklist
 
 1. `pnpm test` — verify nothing broke. Touched a type-check-covered package? `pnpm typecheck` too.