Skip to content

refactor(objectql): extract metadata-protocol + add lean ./core entry (ADR-0076 Step 1) - #2415

Merged
os-zhuang merged 3 commits into
mainfrom
feat/extract-metadata-protocol
Jun 28, 2026
Merged

os-zhuang merged 3 commits into
mainfrom
feat/extract-metadata-protocol

Conversation

@os-zhuang

@os-zhuang os-zhuang commented Jun 28, 2026

Copy link
Copy Markdown
Contributor

What

ADR-0076 — makes @objectstack/objectql cleanly embeddable, in two non-breaking parts:

1. Relocate metadata management → @objectstack/metadata-protocol

protocol.ts (ObjectStackProtocol impl — sys_metadata CRUD, draft/publish, locks, package ownership, diagnostics) plus sys-metadata-repository, metadata-diagnostics, seed-loader, build-probes were metadata-domain code living in objectql for historical reasons. They now live in a new @objectstack/metadata-protocol package. The protocol is typed against an injected MetadataHostEngine interface (engine still injected at runtime), so dependency is one-way (objectql → metadata-protocol), no cycle. Non-breaking: objectql re-exports every previously public symbol.

2. Lean @objectstack/objectql/core entry

A thin embedder (e.g. the objectbase gateway) imports @objectstack/objectql/core to get the engine/registry/hooks/validation surface with no kernel plugin, kernel factory, or metadata protocol — so @objectstack/metadata-protocol (268KB) never enters its bundle. A boundary ratchet test walks core.ts's full import closure and fails if anything reachable imports the protocol/plugin/kernel.

Why

  • protocol.ts co-changes with engine.ts only ~6% of the time but with metadata-core/metadata/spec ~43% — it belongs in the metadata layer.
  • Splitting the engine itself into its own repo/package is not pursued: 88% of recent engine.ts/registry.ts commits are cross-package (engine API still co-evolving), and cloud boots ObjectQLPlugin directly in ~8 places — a breaking boot-contract change isn't worth it now. The ./core entry delivers the lean-embed goal without any of that cost.

Verification

  • ✅ Full turbo build green incl. DTS; dist/core.* has 0 references to metadata-protocol (vs 5 in index); runtime smoke confirms ObjectQL exported, ObjectQLPlugin/protocol not.
  • @objectstack/objectql suite: 58 files / 719 tests (incl. real-engine protocol integration + the new boundary ratchet).
  • ✅ Downstream runtime + rest + metadata (25 pkgs) build clean — public surface intact.

🤖 Generated with Claude Code

…adata-protocol (ADR-0076 Step 1)

protocol.ts (ObjectStackProtocol impl — sys_metadata CRUD, draft/publish,
locks, package ownership, diagnostics) plus its sys-metadata-repository,
metadata-diagnostics, seed-loader and build-probes helpers were metadata-domain
code living inside @objectstack/objectql for historical reasons. They now live
in a new @objectstack/metadata-protocol package.

- protocol no longer references the concrete ObjectQL class; it is typed against
  an injected MetadataHostEngine interface (engine still injected at runtime).
- Dependency is one-way (objectql -> metadata-protocol); no cycle.
- Non-breaking: objectql re-exports every previously public symbol
  (ObjectStackProtocolImplementation, SysMetadataRepository, SysMetadataEngine,
  SeedLoaderService, runBuildProbes, ...), so existing imports keep working.
- metadata-protocol added to the fixed version group.

Verified: full turbo build green (incl. DTS) across the chain; objectql suite
57 files / 718 tests pass (incl. real-engine protocol integration tests);
runtime + rest + metadata downstream (25 pkgs) build clean.

This is Step 1 of ADR-0076. A later step turns the protocol into a capability
plugin so objectql itself stops depending on it (lean engine by construction).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@vercel

vercel Bot commented Jun 28, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
spec Ready Ready Preview, Comment Jun 28, 2026 7:04am

Request Review

@github-actions github-actions Bot added documentation Improvements or additions to documentation dependencies Pull requests that update a dependency file tests tooling labels Jun 28, 2026
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/metadata-protocol, @objectstack/objectql.

14 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

  • content/docs/concepts/core/services.mdx (via @objectstack/objectql)
  • content/docs/concepts/implementation-status.mdx (via @objectstack/objectql)
  • content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
  • content/docs/concepts/packages.mdx (via @objectstack/objectql)
  • content/docs/guides/authentication.mdx (via @objectstack/objectql)
  • content/docs/guides/deployment-vercel.mdx (via @objectstack/objectql)
  • content/docs/guides/formula.mdx (via packages/objectql)
  • content/docs/guides/kernel-services.mdx (via @objectstack/objectql)
  • content/docs/guides/objectql-migration.mdx (via @objectstack/objectql)
  • content/docs/guides/packages.mdx (via @objectstack/objectql)
  • content/docs/guides/plugins.mdx (via @objectstack/objectql)
  • content/docs/protocol/objectos/index.mdx (via @objectstack/objectql)
  • content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
  • content/docs/releases/v9.mdx (via @objectstack/objectql)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

…dary ratchet (ADR-0076)

A thin embedder (e.g. the objectbase gateway) can import `@objectstack/objectql/core`
to get the engine/registry/hooks/validation surface with NO kernel plugin, kernel
factory, or metadata protocol — so `@objectstack/metadata-protocol` (and its 268KB)
never enters its bundle/graph.

- New src/core.ts lean barrel; objectql now builds two entries (index + core) via a
  local tsup config; package.json gains the `./core` export.
- New core-boundary ratchet test walks core.ts's full import closure and fails if
  anything reachable imports @objectstack/metadata-protocol / ./plugin / ./kernel-factory.

Verified: build emits dist/core.{mjs,js,d.ts} with 0 references to metadata-protocol
(vs 5 in index); runtime smoke confirms ObjectQL is exported and ObjectQLPlugin /
ObjectStackProtocolImplementation are not; objectql suite 58 files / 719 tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@os-zhuang os-zhuang changed the title refactor(objectql): extract metadata management into @objectstack/metadata-protocol (ADR-0076 Step 1) refactor(objectql): extract metadata-protocol + add lean ./core entry (ADR-0076 Step 1) Jun 28, 2026
`@objectstack/metadata-protocol` had a `test` script but no test files, so
`vitest run` exited non-zero and failed CI's Test Core (`turbo run test`).
Adds a smoke that imports the package and asserts its public exports + pure
helpers without needing a data engine (protocol behavior is covered e2e by the
objectql suite). Full `turbo run test` now green (126/126 tasks).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@os-zhuang
os-zhuang merged commit 13dbcf2 into main Jun 28, 2026
17 checks passed
@os-zhuang
os-zhuang deleted the feat/extract-metadata-protocol branch June 28, 2026 07:07
akarma-synetal pushed a commit to akarma-synetal/framework that referenced this pull request Aug 23, 2026
…claim (objectstack-ai#9803) (objectstack-ai#9909)

The `@objectstack/objectql/core` entry comment sold the ADR-0076 D2 boundary
with a hard byte figure ("the 268KB metadata protocol"). It is not merely
stale - it never had a stated unit, and no refresh can supply one.

Provenance, re-derivable with `git cat-file -s <rev>:<path>`:

    268,886 B  packages/objectql/src/protocol.ts           @ d9fe95f
    268,921 B  packages/metadata-protocol/src/protocol.ts  @ 13dbcf2 (objectstack-ai#2415)
  1,054,749 B  packages/metadata-protocol/src/protocol.ts  @ HEAD

The figure was raw source bytes of ONE file - what ADR-0076's premise paragraph
counted on 2026-06-28 (268,886 B = 268.9 decimal KB). It was then re-pointed at
a whole package ("the 268KB metadata-management layer"), a unit it never had.

There is also no single right number to write instead. Measured today:

    169,718 B  dist/index.js, gzipped        (LESS than the quoted figure)
    591,087 B  dist/index.js, raw
  1,054,749 B  src/protocol.ts               (the quoted figure's own unit)
  1,513,973 B  src/**/*.ts, excluding tests
  3,637,237 B  src/**/*.ts

A 21x spread straddling "268KB" in both directions, before an embedder's own
bundler and tree-shaking are considered. So the figure goes rather than getting
refreshed: exclusion is the load-bearing claim and the D2 ratchet already pins
it. Removed from core.ts and both embed-objectql sites; the provenance above is
recorded, commit-pinned, in the ratchet test header.

Adds a second assertion to that existing ratchet test so core.ts cannot quote a
byte figure for the excluded weight again. It is a content assertion on one
file, not a size ratchet: no threshold, and it can only fire on a KB/MB figure
written into core.ts. Replayed over all 14 states of core.ts since the file was
created: red at 13 (every one of them this same line), green only at this fix.

docs/adr/0076-objectql-core-tiering.md keeps its three uses: governed surface,
and historically accurate there - it describes protocol.ts the file.


Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

Co-authored-by: os-steve <steve@objectstack.ai>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file documentation Improvements or additions to documentation size/m tests tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant