Merge remote-tracking branch 'origin/main' into claude/issue-4657-activation-events-retirement

Author: claude

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

content/docs/protocol/kernel/http-protocol.mdx

@@ -19,51 +19,148 @@ The **HTTP API** defines how ObjectStack maps data operations to RESTful HTTP en
 
 ## API Discovery
 
-### Discovery Endpoint
+Before making any API calls, clients should request a discovery endpoint to learn about
+available services. **Two endpoints answer that question, and in a stack that mounts
+`@objectstack/rest` they do not return the same shape** — they are built by different
+packages. Read the one that matches your composition; do not mix their fields.
 
-Before making any API calls, clients should request the discovery endpoint to learn about available services:
+### `GET /api/v1` (and `GET /api/v1/discovery`)
 
-**Request:**
-```http
-GET /.well-known/objectstack HTTP/1.1
-Host: api.acme.com
-```
+Returns the full discovery manifest. `@objectstack/rest` registers **one handler at both
+paths** — the API base path and `<basePath>/discovery` — so the two are the same document,
+not a redirect and not two shapes. In a REST-less composition the runtime dispatcher
+registers `<basePath>/discovery` as the fallback owner instead, and then serves its own
+`/.well-known/objectstack` payload there (see below); when `@objectstack/rest` is mounted
+the dispatcher cedes the route to it, so a single owner answers it (ADR-0076 D11).
 
-`/.well-known/objectstack` and the versioned `/api/v1/discovery` route both return the
-discovery document directly — there is no HTTP redirect between them:
+**Request:**
 ```http
 GET /api/v1/discovery HTTP/1.1
+Host: api.acme.com
 ```
 
 **Response:**
 ```json
 {
-  "name": "Acme CRM Production",
-  "version": "2.1.0",
-  "environment": "production",
+  "version": "v1",
+  "apiName": "ObjectStack API",
   "routes": {
     "data": "/api/v1/data",
-    "metadata": "/api/v1/meta",
-    "packages": "/api/v1/packages",
-    "auth": "/api/v1/auth",
-    "ui": "/api/v1/ui",
-    "storage": "/api/v1/storage"
+    "metadata": "/api/v1/meta"
   },
   "services": {
-    "data": { "enabled": true, "status": "available", "route": "/api/v1/data", "provider": "objectql" },
-    "metadata": { "enabled": true, "status": "available", "route": "/api/v1/meta", "provider": "objectql" },
-    "auth": { "enabled": true, "status": "available", "route": "/api/v1/auth", "provider": "@objectstack/plugin-auth" },
+    "metadata": { "enabled": true, "status": "available", "handlerReady": true, "route": "/api/v1/meta", "provider": "objectql" },
+    "data": { "enabled": true, "status": "available", "handlerReady": true, "route": "/api/v1/data", "provider": "objectql" },
     "search": { "enabled": false, "status": "unavailable", "message": "No implementation ships for the 'search' slot — register a service under it to enable" },
     "ai": { "enabled": false, "status": "unavailable", "message": "Provided by @objectstack/service-ai in ObjectStack Cloud/Enterprise — no implementation ships in the open framework" }
   },
-  "locale": {
-    "default": "en-US",
-    "supported": ["en-US", "zh-CN", "es-ES", "fr-FR"],
-    "timezone": "America/Los_Angeles"
+  "capabilities": {
+    "cron": { "enabled": false },
+    "automation": { "enabled": false },
+    "search": { "enabled": false },
+    "transactionalBatch": { "enabled": true, "description": "Atomic cross-object batch endpoint (POST {basePath}/batch)…" }
+  },
+  "scoping": {
+    "enabled": false,
+    "resolution": "auto",
+    "scoped": false
+  }
+}
+```
+
+Three things about this body are worth stating explicitly, because they are what the
+`/.well-known/objectstack` document below does *not* share:
+
+- **`version` is the configured API version, not a product version.** The handler
+  overwrites the protocol's value with `api.version` — the same string that forms the
+  path segment (`"v1"`). It is never a semantic version like `2.1.0`.
+- **There is no `name`, `environment` or `locale` here.** Those are dispatcher fields
+  (see below). A client that initialises i18n from `locale` must read
+  `/.well-known/objectstack`, not this response.
+- **`scoping` is added by the REST server**, so clients can detect dual-mode routing;
+  `environmentId` is present only on the environment-scoped mount
+  (`/api/v1/environments/:environmentId/...`).
+
+Disabled/uninstalled route keys are omitted from `routes` entirely rather than set to
+`null`; check `services` to tell "not installed" apart from "installed but not yet mounted
+here." `capabilities` is a flat map of platform feature flags (`comments`, `automation`,
+`cron`, `search`, `export`, `chunkedUpload`, `transactionalBatch`), each derived from what
+is actually registered — never hardcoded. See
+[API → Discovery](/docs/api#discovery) for the field-by-field reference.
+
+### `GET /.well-known/objectstack`
+
+Served by the runtime dispatcher (`@objectstack/runtime`), not `@objectstack/rest` — its
+body is wrapped as `{ "data": { ... } }` and includes fields (`name`, `environment`,
+`features`, `locale`) that the `@objectstack/rest`-served `/api/v1` response above does
+not. This path is unconditionally dispatcher-owned: no other plugin registers it, so it
+answers with this shape whether or not REST is mounted. The client SDK's `connect()` tries
+`/api/v1/discovery` first and falls back to this endpoint, unwrapping either `body.data` or
+the bare `body`.
+
+**Request:**
+```http
+GET /.well-known/objectstack HTTP/1.1
+Host: api.acme.com
+```
+
+**Response:**
+```json
+{
+  "data": {
+    "name": "ObjectOS",
+    "version": "1.0.0",
+    "environment": "production",
+    "routes": {
+      "data": "/api/v1/data",
+      "metadata": "/api/v1/meta",
+      "packages": "/api/v1/packages",
+      "auth": "/api/v1/auth",
+      "ui": "/api/v1/ui",
+      "i18n": "/api/v1/i18n"
+    },
+    "features": {
+      "search": false,
+      "websockets": false,
+      "files": false,
+      "analytics": false,
+      "ai": false,
+      "notifications": false,
+      "i18n": true
+    },
+    "services": {
+      "metadata": { "enabled": true, "status": "available", "handlerReady": true, "route": "/api/v1/meta", "provider": "kernel" },
+      "data": { "enabled": true, "status": "available", "handlerReady": true, "route": "/api/v1/data", "provider": "kernel" },
+      "auth": { "enabled": true, "status": "available", "handlerReady": true, "route": "/api/v1/auth" },
+      "search": { "enabled": false, "status": "unavailable", "handlerReady": false, "message": "No implementation ships for the 'search' slot — register a service under it to enable" }
+    },
+    "locale": {
+      "default": "en-US",
+      "supported": ["en-US", "zh-CN"],
+      "timezone": "UTC"
+    }
   }
 }
 ```
 
+`name` and `version` are the dispatcher's own build identity, not your app's name — they
+are fixed strings, so do not display them as the deployment's title. `environment` is the
+process `NODE_ENV`. `locale` is derived from the registered i18n service (`getDefaultLocale()`
+/ `getLocales()`); with no i18n service it degrades to `{ "default": "en", "supported":
+["en"], "timezone": "UTC" }`. The body also repeats `routes` under an `endpoints` key as a
+backward-compatibility alias, and carries **no** `capabilities` map — that one exists only
+on the REST-served response above.
+
+<Callout type="warn">
+**"Both paths return the same document" holds only in a REST-less composition.** There, the
+dispatcher owns `/api/v1/discovery` as the fallback registrant, so that path and
+`/.well-known/objectstack` both answer with the dispatcher payload above (the bare
+`/api/v1` is registered by `@objectstack/rest` alone and is not served at all). As soon as
+`@objectstack/rest` is mounted it takes `/api/v1/discovery` under the single-owner rule
+(ADR-0076 D11) and the two paths answer different shapes. Never write a client that reads
+`locale` or `environment` off `/api/v1/discovery`.
+</Callout>
+
 **Why discovery matters:**
 - **Environment agnostic:** Works across dev, staging, production without hardcoding URLs
 - **Version tolerance:** API routes can change without breaking clients