From eb8eb16bf3d082854e37529856d362f9d106ba1c Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 9 Aug 2026 01:53:16 +0000 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=E7=94=A8=E7=8E=B0?= =?UTF-8?q?=E8=A1=8C=E5=8D=95=E4=B8=80=E6=8F=90=E4=BE=9B=E8=80=85=E4=BA=8B?= =?UTF-8?q?=E5=AE=9E=E5=8F=96=E4=BB=A3=E6=8C=87=E5=90=91=E5=B7=B2=E5=88=A0?= =?UTF-8?q?=E9=99=A4=20ADR-0001=20=E7=9A=84=E6=AD=BB=E9=93=BE=20(#6733)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `ARCHITECTURE.md` 的 ADR 小节指向 `docs/adr/0001-metadata-service-architecture.md`, 该文件已于 2026-02-11 在 `9da8e3e72` 中随 ADR-0002 与 `docs/adr/README.md` 一并删除, 读者点进去是 404。 不做「换个 ADR 重指」的机械修复:该链接承载的论断——「ObjectQL 与 MetadataPlugin 都可以提供 metadata 服务,MetadataPlugin 优先、ObjectQL 兜底」——本身已经不成立。 按 origin/main 核对: - `packages/metadata/src/plugin.ts` 是唯一 `registerService('metadata', …)` 的地方; `packages/objectql/src/plugin.ts` 只注册 `objectql` / `data` / `manifest` / `lifecycle`, 没有 `metadata`。 - ObjectQL 已退为消费者:`start()` 里读 metadata 服务、同步定义、订阅事件, 取不到时退回自身内部 registry。 - ADR-0001 幸存的那一半(共享接口)如今是 spec 契约 `packages/spec/src/contracts/metadata-service.ts` 的 `IMetadataService`, 槽位声明在 `packages/spec/src/system/core-services.zod.ts`。 因此该小节改为:以纯文本(非链接)记下被删路径与删除出处,陈述现行单一提供者架构并 指向上述活的契约与实现文件,仓储/变更日志/订阅机制指向仍在的 ADR-0008。并明确写出 「单一提供者这个决策目前没有 ADR 归属」——重新立档是维护者的事(PD #14),本 PR 不碰 `docs/adr/**`。 顺带把 `scripts/check-adr-anchors.mjs` 中 `UNRESOLVED_ADR_CITATIONS` 的 `0001` 条注释 更新为事实:它原本写「ARCHITECTURE.md still carries a markdown LINK」,本 PR 之后这句 不再为真。条目本身保留——ADR-0002 的历史引用仍让它 earning its place,门禁的 stale 检查 已验证(绿)。 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01F8q5J1MQyocgtNspb15fSn --- ARCHITECTURE.md | 28 +++++++++++++++++++++++++--- scripts/check-adr-anchors.mjs | 11 +++++++---- 2 files changed, 32 insertions(+), 7 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 2776514839..87dee4152a 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -648,9 +648,31 @@ export type Field = z.infer; ### Architecture Decision Records (ADRs) -Important architectural decisions are documented as ADRs in `docs/adr/`: - -- [ADR-0001: Metadata Service Architecture](docs/adr/0001-metadata-service-architecture.md) - Explains why both ObjectQL and MetadataPlugin can provide metadata service and how they work together +Important architectural decisions are documented as ADRs in `docs/adr/`. + +**Metadata service architecture.** This section used to link +`docs/adr/0001-metadata-service-architecture.md`, deleted on 2026-02-11 in `9da8e3e72` +(together with ADR-0002 and the ADR `README.md`). The link is deliberately not repointed +at another record, because the decision it carried — *both ObjectQL and MetadataPlugin can +provide the metadata service, MetadataPlugin taking precedence and ObjectQL acting as +fallback* — is no longer what the code does. Today: + +- **MetadataPlugin is the sole provider** of the `metadata` service + (`packages/metadata/src/plugin.ts`). `ObjectQLPlugin` registers `objectql`, `data`, + `manifest` and `lifecycle` — never `metadata`. +- **ObjectQL is a consumer.** In `start()` it reads the `metadata` service, syncs + definitions into its own registry and subscribes to metadata events, and degrades to + that internal registry when no such service is present + (`packages/objectql/src/plugin.ts`). +- **The shared-interface principle survived, as a spec contract**: `IMetadataService` in + `packages/spec/src/contracts/metadata-service.ts`, with the slot declared as + `CoreServiceName 'metadata'` in `packages/spec/src/system/core-services.zod.ts`. +- **Repository, change-log and subscription mechanics** are recorded in + [ADR-0008: Metadata Repository, Change Log & Subscription](docs/adr/0008-metadata-repository-and-change-log.md). + +The single-provider decision itself has **no ADR record today** — ADR-0001 was deleted and +nothing replaced it. Re-homing it is a maintainer call; until then the contract and the two +plugin files above are the live source of truth. ### Component-Specific Documentation diff --git a/scripts/check-adr-anchors.mjs b/scripts/check-adr-anchors.mjs index 1356aa1a20..818ba84fc9 100644 --- a/scripts/check-adr-anchors.mjs +++ b/scripts/check-adr-anchors.mjs @@ -193,10 +193,13 @@ const UNRESOLVED_ADR_CITATIONS = [ // Deleted 2026-02-11 (9da8e3e72) together with 0002-database-driven-metadata- // storage.md and docs/adr/README.md, in the permission-protocol rewrite. // Cited as history by `docs/adr/0002-...md` ("already discarded in v3.4's - // ADR-0001"). ⚠️ ARCHITECTURE.md still carries a markdown LINK to the deleted - // path — a genuinely broken pointer, not history, filed separately from - // #6634; this entry keeps the gate honest about the number, it does not - // bless that link. + // ADR-0001"), which is what keeps this entry earning its place. + // ARCHITECTURE.md used to carry a markdown LINK to the deleted path — a + // genuinely broken pointer rather than history, filed separately from #6634 + // and fixed in #6733: that section now names the deleted path as plain text + // and states the current single-provider architecture (MetadataPlugin is the + // sole `metadata` provider; ObjectQL consumes it) instead of pointing at a + // 404. This entry never blessed that link and does not bless any future one. why: 'record deleted 2026-02-11 (9da8e3e72); cited as history by ADR-0002', }, {