Merge remote-tracking branch 'origin/main' into claude/issue-4756-sys-comment-dead-fields

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/hungry-donkeys-repeat.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/objectql': minor
+'@objectstack/cli': patch
+---
+
+修复:每个 `os migrate` 子命令关停后,#4551 悬空引用巡检都会把 `sys_metadata` / `sys_view_definition` 报成 `unreadableObjects`(#4747)
+
+一条**成功**的命令过去会在返回 JSON 之后打出两行 `ERROR Find operation failed` 和一份
+`unreadableObjects` 非空的巡检报告 —— 对抓 ERROR 的 CI 流水线是直接误报源,更要命的是它把
+`unreadableObjects` 变成了恒为真的告警:那个桶存在的意义正是区分「我没能检查」和「我检查了,
+没问题」,一个每次健康运行都非空的桶不再携带任何信息。
+
+两处静默空转叠出了这个结果:
+
+- `ObjectQLPlugin` 的关停逻辑写在 `stop()` 里,而内核的插件契约是 `init`/`start`/`destroy` ——
+  `stop()` 从来没有被任何人调用过,ADR-0057 巡检定时器因此在任何宿主上都不会被解除。改为
+  `destroy()`(与 `DefaultDatasourcePlugin` 一致)。
+- `bootSchemaStack().shutdown()` 调的是 `(runtime as any).stop?.()`,而 `Runtime` 根本没有
+  `stop` —— 可选调用把「没有关停」伪装成了「关停过了」。改为走内核自己的 `kernel.shutdown()`,
+  与 `os serve` 收到 SIGTERM 时同一条路径。
+
+同时 `LifecycleService.stop()` 不再只是清定时器:它还会把「引擎正在拆」这一位交给正在飞行中的
+sweep,巡检据此在读之前停手。因关停而失败的读**不再进入** `unreadableObjects` —— 那不是关于
+数据源的证据;报告改用新增的 `DanglingReferenceReport.aborted` 记录「这次没跑完」,所以不完整
+依然是响的,只是不再占用发现桶。
+
+**真正读不出来的对象(数据源故障)照旧进 `unreadableObjects`**,巡检在 CLI 场景也照旧运行 ——
+这里没有「一次性命令不跑巡检」的开关,只有「引擎活着才读」的生命周期边界。

.changeset/notification-orphan-template-schemas.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: `@objectstack/spec/system` no longer exports the orphan notification-template vocabulary — `EmailTemplate(Schema)`, `SMSTemplate(Schema)`, `PushNotification(Schema)`, `InAppNotification(Schema)` (#4616)
+
+These four schemas existed **only** as the member shapes of the
+`NotificationConfigSchema.template` union, and #4610 (#4535 C3) deleted that
+union. Since then they have been reachable from no parent schema and from no
+metadata-type root: nothing in framework, cloud or objectui parsed a document
+against them, so they declared delivery capability the runtime never read
+(ADR-0049 enforce-or-remove, resolved by REMOVE in the v17 breaking window).
+
+Migration — one line each, and in every case the replacement already exists:
+
+- FROM `import { EmailTemplateSchema, type EmailTemplate } from '@objectstack/spec/system'` →
+  TO `import { EmailTemplateDefinitionSchema, type EmailTemplateDefinition } from '@objectstack/spec/system'`.
+  **Shape change** — this is a different, richer contract, not a rename:
+  `EmailTemplateDefinitionSchema` is keyed `name` + `locale` (not `id`), splits
+  the body into `bodyHtml` / `bodyText` (not `body` + `bodyType`), and adds
+  `label` / `category` / `active` / `fromOverride` / `replyTo`. It is also a
+  `strictObject`, so the old keys are rejected loudly rather than stripped.
+  This is the schema the `email_template` metadata kind has resolved to since
+  spec **7.1.0**, which demoted `EmailTemplateSchema` when it fixed that Prime
+  Directive #8 double-declaration and kept it "only as an inline sub-shape
+  inside `Notification`" — #4610 removed that holder, and #4616 finishes the
+  job. If your code registers a client-side or publish-time validator for
+  `email_template`, it must point at `EmailTemplateDefinitionSchema`;
+  `BUILTIN_METADATA_TYPE_SCHEMAS` (`kernel/metadata-type-schemas.ts`) is the
+  authority.
+- FROM `import { SMSTemplateSchema, type SMSTemplate } from '@objectstack/spec/system'` →
+  TO: no spec replacement, and none is needed. SMS templates are
+  `sys_notification_template` rows resolved by `(topic, 'sms', locale)`
+  (`service-messaging/src/sms-channel.ts`) and rendered by
+  `template-renderer.ts`; the provider-side template is Aliyun's pre-registered
+  `TemplateCode` in `service-sms` — a vendor API shape, never a spec constant.
+- FROM `import { PushNotificationSchema, type PushNotification } from '@objectstack/spec/system'`
+  and FROM `import { InAppNotificationSchema, type InAppNotification } from '@objectstack/spec/system'` →
+  TO: no replacement. Neither channel has a delivery implementation (#3197):
+  the dispatcher dead-letters any message addressed to them, so these payload
+  shapes advertised a capability nothing delivers. The live delivery ingress is
+  `NotificationService.emit` (`INotificationService`,
+  `@objectstack/spec/contracts`); the in-app bell reads `./api`'s
+  `Notification(Schema)` inbox row; the presentation vocabulary is
+  `@objectstack/spec/ui` (`NotificationTypeSchema`, `NotificationSeveritySchema`,
+  `NotificationPositionSchema`, `NotificationActionSchema` — all unchanged).
+
+Unchanged and explicitly NOT part of this removal:
+`@objectstack/spec/system`'s `NotificationChannel(Schema)` (live — re-exported
+by `@objectstack/spec/contracts`, consumed by `service-messaging`),
+`EmailTemplateDefinition*`, and every `@objectstack/spec/ui` notification
+export.
+
+No ADR-0087 D2 conversion accompanies this change, deliberately: a conversion
+rewrites authored or stored sources, and these defs were reachable from no
+metadata-type root, so `os migrate meta` would have nothing to match. The
+removal is a TypeScript export-surface break only — same disposition as #4610
+in this very module. `json-schema.manifest.json` loses 4 keys and
+`authorable-surface.json` loses their 22 lines; both deletions are adjudicated
+by `gen:schema`'s #4650 route-3 check ("def no longer emitted by this build").

.changeset/pm-dispatch-domain-lanes.md

@@ -0,0 +1,16 @@
+---
+---
+
+docs(pm-dispatch): domain 车道协议 —— 按「修复落点的包」划域,支持同仓多 PM 并发 (#4819)
+
+`.claude/skills/pm-dispatch/SKILL.md` 新增「Domain lanes(同仓多 PM 并发)」一节:
+锚定规则(每个包恰好属于一个 domain,`domain:*` 标签取**修复落点所在包**的域,分诊时
+读代码后打,不从标题词汇猜 —— #4775 的 hook condition 概念属 automation,落点却是
+`packages/objectql/src/hook-wrappers.ts`,故归 `domain:engine`)、六域分类表、标签纪律
+(打标 ≠ 认领;未打标不得认领)、认领范围(在 #4604 登记 domain 集合)、跨域单与借单
+规则、选批时的全局在飞检查,以及合并队列仍是全体共享串行资源的提醒(flaky 税,#4796)。
+认领注释模板加「域」「文件面」两行(跨域与借单必填);Multi-repo coordination 规则 4 的
+「同队列多 PM 一律禁止」改为「仅在 domain 车道协议生效时允许」,repo 分片阶梯保留,
+domain 车道作为第三级。
+
+仅改内部 agent 协议文本,不发布任何包。

.claude/skills/pm-dispatch/SKILL.md

@@ -102,11 +102,13 @@ known case: accepting a `repo:objectui` PR ⇒ file a `pm:queue` issue in
 `objectstack` — "run `pnpm objectui:refresh` and land the console bump",
 referencing the merged PR, blocked-by it until it actually merges.
 
-**4. Multiple PM sessions shard by repo — never share one queue.** The
-claim protocol makes concurrent PMs *safe*, not *useful*: batch
-independence (file-disjointness) is only checked within one PM's view, so
-two PMs on the same queue can claim different issues that collide on
-shared files, and the merge queue is one lane regardless. Scaling order:
+**4. Multiple PM sessions shard by repo; one shared queue only under
+domain lanes.** The claim protocol makes concurrent PMs *safe*, not
+*useful* on its own: batch independence (file-disjointness) is only checked
+within one PM's view, so two PMs on the same queue can claim different
+issues that collide on shared files, and the merge queue is one lane
+regardless. Making that check **global** is exactly what the next section
+does. Scaling order:
 
 1. One PM, bigger batch (`batch:5` is the maintainer's chosen operating
    point, riding on the resource discipline above), heavy tasks via
@@ -115,7 +117,13 @@ shared files, and the merge queue is one lane regardless. Scaling order:
    repo** as its shard (`/pm-dispatch repo:objectstack-ai/objectui`) —
    file universes are disjoint by construction. A sharded PM states its
    shard in every claim comment and **never claims outside it**.
-3. Multiple PMs on the SAME queue: prohibited — all cost, no throughput.
+3. Multiple PMs on the SAME queue: **prohibited unless the Domain-lanes
+   protocol (next section) is active** — every PM in its own session and
+   its own container, domain sets registered in the registry issue, label
+   discipline observed, and the global in-flight check run at every batch
+   selection. Without that protocol the ban stands as written: all cost,
+   no throughput, and the collision stays invisible to both PMs until the
+   merge.
 
 **Shard ownership is registered, never assumed.** A registry issue in the
 main backlog (`[PM] 分片分工登记表`) records which session owns which
@@ -159,6 +167,81 @@ gives the maintainer a single view (filter by `repo:*` and `pm:*`). The PM
 maintains no tracking state outside GitHub — that invariant is what keeps
 the loop resumable and the board honest.
 
+## Domain lanes(同仓多 PM 并发)
+
+Rule 4's ladder ran out at one PM per repo because file-disjointness is only
+ever checked inside one PM's own view. Domain lanes are the **third rung**:
+one PM's triage verdict is cached as a `domain:*` label every other PM can
+read, so batch selection filters at the label layer instead of at the merge.
+Premise: each PM is its **own session in its own container** — adding a PM
+adds compute, not contention — and collisions are prevented by the
+domain→package mapping, not by hoping two PMs pick different work.
+
+**Anchoring rule.** The whole scheme rests on this one sentence:
+
+> Every package belongs to exactly **one** domain; an issue's `domain:*`
+> label is the domain of **the package the fix lands in**, decided at triage
+> by reading the code — **never guessed from the issue's title vocabulary**.
+
+The counter-example that makes it a rule: #4775 is a hook `condition`, which
+reads as automation, but the fix lands in
+`packages/objectql/src/hook-wrappers.ts` ⇒ `domain:engine`. Labeling by topic
+would have routed it to a different PM than the one already inside that
+package — the exact collision lanes exist to prevent. If you cannot say which
+file the fix touches, you have not triaged it yet, and it is not labelable.
+
+| 标签 | 包家族 |
+|:--|:--|
+| `domain:engine` | `packages/objectql`、`packages/metadata*`、`packages/platform-objects`、`packages/core`、`packages/plugins/driver-*` |
+| `domain:services` | `packages/services/*`、`packages/plugins/plugin-approvals`、`plugin-webhooks`、`packages/connectors/*` |
+| `domain:identity` | `packages/plugins/plugin-auth`、`plugin-security`、`plugin-sharing`、`plugin-audit` |
+| `domain:devx` | `packages/lint`、`skills/**`、`content/docs/**`、`scripts/`(门禁类) |
+| `domain:spec` | `packages/spec` 及其生成物(现 spec 车道不变) |
+| `domain:cli` | `packages/cli`、`runtime`、`verify`、`qa`、`types` |
+
+`examples/**` belongs to the subsystem it exercises; anything that fits
+nowhere is judged at triage by its principal landing site. A package missing
+from the table is classified the first time it is triaged and the table
+updated **by PR** — the taxonomy evolves deliberately, never per-claim.
+
+**Label discipline.** `domain:*` is applied during the backlog sweep (round
+loop step 0) by whichever PM triages the issue. **Labeling ≠ claiming**: any
+PM may label any issue, including ones it will never claim — the label is
+shared routing, not a reservation. An **unlabeled issue may not be claimed by
+anyone**: triage and label it first, or selection has silently gone back to
+happening inside one PM's private view.
+
+**Claim scope.** Each PM session registers its **domain set** in the registry
+issue (`[PM] 分片分工登记表`, #4604 — the same registry that records repo
+shards) and claims only issues whose label falls inside that set. A set, not
+a single domain: lanes are a routing table, not a job title.
+
+**Cross-domain issues.** Prefer the contract-first split of rule 2 — one
+sub-issue per domain, each carrying its own `domain:*` label, ordered with
+`Blocked-by:`. When a split costs more than it buys, a single PM claims the
+whole issue and **declares the full file surface** in its claim comment, so
+every other PM's in-flight check can see all of it.
+
+**Borrowing.** An idle PM may claim outside its registered set when all three
+hold: (a) that domain's PM has not claimed the issue, (b) the claim comment
+declares the file surface, (c) the global in-flight check below passes.
+Borrowing is a one-issue exception, not a lane transfer — the registry entry
+does not change, so nobody has to guess who owns the domain afterwards.
+
+**Global in-flight check — run it at batch selection (step 3).** List every
+`pm:dispatched` issue across the repo, read the file-surface declaration on
+each one's latest claim comment, and require your candidates to be disjoint
+from all of them. This is step 3's independence test raised from your batch
+to the whole repo; skip it and two individually-independent batches are
+jointly dependent, which is precisely the failure the same-queue ban was
+protecting against.
+
+**The merge queue is still one shared serial resource.** Lanes buy parallel
+authorship, not parallel landing: the flaky-test tax (#4796) scales linearly
+with the number of PMs, and a red queue blocks every lane at once. Queue
+health is therefore a shared duty — a PM that notices a flake fixes or files
+it rather than re-queuing past it, whichever lane it came from.
+
 ## The round loop
 
 ### 0. Backlog sweep — classification is a standing duty, not a request
@@ -280,6 +363,12 @@ execute atomically, in order:
    > 会话:`session_<id>`
    > 分支:`claude/issue-<n>-<slug>`
    > Worktree:`<repo>-issue-<n>`
+   > 域:`domain:<x>`
+   > 文件面:`<预计触碰的目录列表>`(越界即停,报告说明)
+
+   「文件面」is **required** for cross-domain and borrowed claims and
+   **recommended** for ordinary same-domain ones — it is the only input
+   another PM's global in-flight check has to read.
 3. **Race check**: assignment is idempotent, so two agents can both
    "succeed". Re-read the comments; if an earlier claim comment with a
    *different* session ID or branch name exists, you lost — touch nothing of