Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 25 additions & 3 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -648,9 +648,31 @@ export type Field = z.infer<typeof FieldSchema>;

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

Expand Down
11 changes: 7 additions & 4 deletions scripts/check-adr-anchors.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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',
},
{
Expand Down
Loading