From 4f32ad430c95d82d7fd61c8afdcd304bbadfc5b3 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Sun, 28 Jun 2026 23:37:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(adr):=20ADR-0076=20rev.8=20=E2=80=94=20res?= =?UTF-8?q?olve=20Open=20Question=20#7=20(keep=20the=20metadata-protocol?= =?UTF-8?q?=20name;=20no=20rename)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per maintainer decision: keep the already-published `@objectstack/metadata-protocol` package name. Renaming churns downstream for ~0 benefit. The `protocol` suffix is a deliberate, low-cost naming exception — the real contract lives in `@objectstack/spec/api`, not the impl package. - D10: replace the "rename → metadata-runtime" clause with "name retained; content converges to the metadata-management impl". - Open Question #7: resolved (keep the name; README note to clarify impl-vs-contract). - Status: rev.8; notes D9 step-1 (interface segmentation) shipped in #2429. Docs only; empty changeset. Co-Authored-By: Claude Opus 4.8 --- .changeset/adr-0076-rev8.md | 4 ++++ docs/adr/0076-objectql-core-tiering.md | 6 +++--- 2 files changed, 7 insertions(+), 3 deletions(-) create mode 100644 .changeset/adr-0076-rev8.md diff --git a/.changeset/adr-0076-rev8.md b/.changeset/adr-0076-rev8.md new file mode 100644 index 0000000000..0b326a1e78 --- /dev/null +++ b/.changeset/adr-0076-rev8.md @@ -0,0 +1,4 @@ +--- +--- + +docs(adr): ADR-0076 rev.8 — keep metadata-protocol name (OQ#7 resolved). Docs only. diff --git a/docs/adr/0076-objectql-core-tiering.md b/docs/adr/0076-objectql-core-tiering.md index 5c636526d6..354699bcc4 100644 --- a/docs/adr/0076-objectql-core-tiering.md +++ b/docs/adr/0076-objectql-core-tiering.md @@ -1,6 +1,6 @@ # ADR-0076: objectql is the data engine — relocate metadata management (protocol) out of it; enforce the boundary; defer the engine repo-split -**Status**: Proposed (2026-06-28, rev. 7 — kernel review concluded: dissolve the `ObjectStackProtocol` union (D9 refinement; discovery `services` + shared spine already provide unification); transport stays a framework-agnostic port with per-domain normalized handlers (D11)) — v12 assessment +**Status**: Proposed (2026-06-28, rev. 8) — D1–D11 below. D9 step-1 (interface segmentation) shipped in #2429. Open Question #7 resolved: keep the published `@objectstack/metadata-protocol` name (no rename). — v12 assessment **Deciders**: ObjectStack Protocol Architects **Builds on**: [ADR-0005](./0005-metadata-customization-overlay.md) (sys_metadata overlay substrate), [ADR-0025](./0025-plugin-package-distribution.md) (plugin package distribution), [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (open-core boundary), [ADR-0048](./0048-cross-package-metadata-collision.md) (package id is the addressing unit), [ADR-0066](./0066-unified-authorization-model.md) (secure-by-default, posture-gated bypass) **Consumers**: **new** `@objectstack/metadata-protocol` (receives `protocol` + `sys-metadata-repository` + `metadata-diagnostics`), `@objectstack/objectql` (loses protocol → becomes a lean data engine; keeps a back-compat re-export), `@objectstack/metadata-core` (gains the `SysMetadataEngine` interface), `@objectstack/plugin-security`, `@objectstack/plugin-sharing`, `@objectstack/spec`, and out-of-tree embedders — notably `../objectbase` (its `gateway`). @@ -111,7 +111,7 @@ A single `ObjectStackProtocolImplementation` facade — and any `*-protocol` *im Target end-state: - **"protocol" names ONLY the contract** — the segmented interfaces in `@objectstack/spec/api` (D9). There is **no `*-protocol` implementation package**. - **`DataProtocol`** impl → engine-adjacent / transport (thin wire-normalizers). -- **`MetadataProtocol`** impl → a metadata-**domain** package; rename `@objectstack/metadata-protocol` → e.g. `@objectstack/metadata-runtime` (it owns `sys_metadata` — a legitimate business domain, not "protocol"). +- **`MetadataProtocol`** impl → stays in **`@objectstack/metadata-protocol`** (name **retained** — already published; renaming churns downstream for ~0 benefit). The package's *content* converges to the metadata-management impl (it owns `sys_metadata`). The `protocol` in the name is a deliberate, low-cost naming exception from being published — the real contract lives in `@objectstack/spec/api`, not here. (Open Question #7, resolved.) - **Analytics / Feed / Realtime / Notification / …** → their existing service packages; **delete the facade's duplicated `analyticsQuery` + feed wrappers** and the `ObjectQLPlugin` `'analytics'` adapter (let `service-analytics` own the `'analytics'` service). - **The transport/dispatcher routes each contract-slice to the owning service** (it already resolves services by name) — no central facade class. @@ -181,7 +181,7 @@ import { SecurityPlugin } from '@objectstack/plugin-security'; 4. **`trusted` profile** — two-key (build-time absence + explicit runtime assertion), prod env-allowlisted. 5. **D7 trigger threshold** — what cross-package ratio (from 88%) over what window signals "extract the engine"? Track in CI; set on first review. 6. **Data-facade home** — does the `DataProtocol` impl live in the engine-adjacent transport layer / `rest`, or a small `@objectstack/protocol-data`? (It is thin and transport-shaped.) -7. **Metadata package name (post-segmentation)** — keep `@objectstack/metadata-protocol` for the `MetadataProtocol` impl, or rename (`@objectstack/protocol-metadata` / `@objectstack/metadata-runtime`)? +7. **Metadata package name (post-segmentation)** — **Resolved: keep `@objectstack/metadata-protocol`** (already published; renaming has ~0 benefit and real churn). The `protocol` suffix is a low-cost naming exception — the contract is in `@objectstack/spec/api`; a README note in the package should clarify impl-vs-contract. 8. **Per-domain versioning** — once segmented, do capability protocols get independent version markers / a `getCapabilities()` discovery method? 9. **dispatcher vs rest-server overlap** — are `runtime/http-dispatcher` (~3.8k) and `rest/rest-server` (~5.1k) redundant central transport layers? Consolidate or delineate (D11). 10. **Validate multi-adapter** — write a second `IHttpServer` adapter (thin Workers/Express) to prove the port is free of Hono-isms before relying on it (D11).