Skip to content

Commit edc9655

Browse files
docs(architecture): 用现行单一提供者事实取代指向已删除 ADR-0001 的死链 (#6733) (#6869)
`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 检查 已验证(绿)。 Claude-Session: https://claude.ai/code/session_01F8q5J1MQyocgtNspb15fSn Co-authored-by: Claude <noreply@anthropic.com>
1 parent e5bd768 commit edc9655

2 files changed

Lines changed: 32 additions & 7 deletions

File tree

ARCHITECTURE.md

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -648,9 +648,31 @@ export type Field = z.infer<typeof FieldSchema>;
648648

649649
### Architecture Decision Records (ADRs)
650650

651-
Important architectural decisions are documented as ADRs in `docs/adr/`:
652-
653-
- [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
651+
Important architectural decisions are documented as ADRs in `docs/adr/`.
652+
653+
**Metadata service architecture.** This section used to link
654+
`docs/adr/0001-metadata-service-architecture.md`, deleted on 2026-02-11 in `9da8e3e72`
655+
(together with ADR-0002 and the ADR `README.md`). The link is deliberately not repointed
656+
at another record, because the decision it carried — *both ObjectQL and MetadataPlugin can
657+
provide the metadata service, MetadataPlugin taking precedence and ObjectQL acting as
658+
fallback* — is no longer what the code does. Today:
659+
660+
- **MetadataPlugin is the sole provider** of the `metadata` service
661+
(`packages/metadata/src/plugin.ts`). `ObjectQLPlugin` registers `objectql`, `data`,
662+
`manifest` and `lifecycle` — never `metadata`.
663+
- **ObjectQL is a consumer.** In `start()` it reads the `metadata` service, syncs
664+
definitions into its own registry and subscribes to metadata events, and degrades to
665+
that internal registry when no such service is present
666+
(`packages/objectql/src/plugin.ts`).
667+
- **The shared-interface principle survived, as a spec contract**: `IMetadataService` in
668+
`packages/spec/src/contracts/metadata-service.ts`, with the slot declared as
669+
`CoreServiceName 'metadata'` in `packages/spec/src/system/core-services.zod.ts`.
670+
- **Repository, change-log and subscription mechanics** are recorded in
671+
[ADR-0008: Metadata Repository, Change Log & Subscription](docs/adr/0008-metadata-repository-and-change-log.md).
672+
673+
The single-provider decision itself has **no ADR record today** — ADR-0001 was deleted and
674+
nothing replaced it. Re-homing it is a maintainer call; until then the contract and the two
675+
plugin files above are the live source of truth.
654676

655677
### Component-Specific Documentation
656678

scripts/check-adr-anchors.mjs

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -193,10 +193,13 @@ const UNRESOLVED_ADR_CITATIONS = [
193193
// Deleted 2026-02-11 (9da8e3e72) together with 0002-database-driven-metadata-
194194
// storage.md and docs/adr/README.md, in the permission-protocol rewrite.
195195
// Cited as history by `docs/adr/0002-...md` ("already discarded in v3.4's
196-
// ADR-0001"). ⚠️ ARCHITECTURE.md still carries a markdown LINK to the deleted
197-
// path — a genuinely broken pointer, not history, filed separately from
198-
// #6634; this entry keeps the gate honest about the number, it does not
199-
// bless that link.
196+
// ADR-0001"), which is what keeps this entry earning its place.
197+
// ARCHITECTURE.md used to carry a markdown LINK to the deleted path — a
198+
// genuinely broken pointer rather than history, filed separately from #6634
199+
// and fixed in #6733: that section now names the deleted path as plain text
200+
// and states the current single-provider architecture (MetadataPlugin is the
201+
// sole `metadata` provider; ObjectQL consumes it) instead of pointing at a
202+
// 404. This entry never blessed that link and does not bless any future one.
200203
why: 'record deleted 2026-02-11 (9da8e3e72); cited as history by ADR-0002',
201204
},
202205
{

0 commit comments

Comments
 (0)