refactor(objectql): extract metadata management into @objectstack/metadata-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>

Author: os-zhuang

.changeset/config.json

@@ -21,6 +21,7 @@
       "@objectstack/metadata-core",
       "@objectstack/metadata-fs",
       "@objectstack/objectql",
+      "@objectstack/metadata-protocol",
       "@objectstack/observability",
       "@objectstack/formula",
       "@objectstack/lint",

.changeset/extract-metadata-protocol.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/objectql': minor
+'@objectstack/metadata-protocol': minor
+---
+
+Extract metadata management into `@objectstack/metadata-protocol` (ADR-0076)
+
+`protocol.ts` (the `ObjectStackProtocol` implementation — 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 that lived inside `@objectstack/objectql` for historical reasons. They now live in a dedicated **`@objectstack/metadata-protocol`** package.
+
+The protocol no longer depends on the concrete `ObjectQL` class — it is typed against an injected `MetadataHostEngine` interface (the engine is still injected at runtime). Dependency direction is now one-way (`objectql → metadata-protocol`); there is no cycle.
+
+**Non-breaking**: `@objectstack/objectql` re-exports every previously public symbol (`ObjectStackProtocolImplementation`, `SysMetadataRepository`, `SysMetadataEngine`, `SeedLoaderService`, `runBuildProbes`, …), so existing imports keep working.
+
+This is Step 1 of ADR-0076. A later step turns the protocol into a capability plugin so `objectql` itself stops depending on it (making the engine lean by construction).

packages/metadata-protocol/README.md

@@ -0,0 +1,7 @@
+# @objectstack/metadata-protocol
+
+The ObjectStack metadata-management protocol, extracted from `@objectstack/objectql` per [ADR-0076](../../docs/adr/0076-objectql-core-tiering.md).
+
+Implements `ObjectStackProtocol`: `sys_metadata` CRUD, draft/publish lifecycle, write locks, package ownership/installation, metadata diagnostics, seed application, and build probes.
+
+It uses a data engine purely as storage + schema registry, injected at runtime via the `MetadataHostEngine` interface — so this package does **not** depend on `@objectstack/objectql`.

packages/metadata-protocol/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@objectstack/metadata-protocol",
+  "version": "11.0.0",
+  "license": "Apache-2.0",
+  "description": "ObjectStack metadata management protocol: sys_metadata CRUD, draft/publish, locks, package ownership, diagnostics (ADR-0076).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "objectstack",
+    "metadata",
+    "protocol",
+    "sys-metadata"
+  ],
+  "dependencies": {
+    "@objectstack/core": "workspace:*",
+    "@objectstack/formula": "workspace:*",
+    "@objectstack/metadata-core": "workspace:*",
+    "@objectstack/spec": "workspace:*",
+    "@objectstack/types": "workspace:*",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/metadata-protocol"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

packages/objectql/src/build-probes.ts …es/metadata-protocol/src/build-probes.tspackages/objectql/src/build-probes.ts renamed to packages/metadata-protocol/src/build-probes.ts packages/objectql/src/build-probes.ts renamed to packages/metadata-protocol/src/build-probes.ts

@@ -0,0 +1,25 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { IDataEngine } from '@objectstack/core';
+
+/**
+ * The engine surface the metadata protocol needs from its host (ADR-0076).
+ *
+ * The protocol uses the data engine purely as storage + a schema registry; it
+ * is injected a concrete engine at runtime (today `@objectstack/objectql`'s
+ * `ObjectQL`). Typing against this interface — instead of the concrete class —
+ * is what lets `@objectstack/metadata-protocol` avoid a dependency on
+ * `@objectstack/objectql` (which would otherwise form a cycle, since the
+ * ObjectQL plugin constructs the protocol).
+ */
+export interface MetadataHostEngine extends IDataEngine {
+  /** Schema registry (listItems/getItem/registerItem/getObject/registerObject/installPackage/...). */
+  registry: any;
+  /** DDL: create/sync the physical table for an object schema. */
+  syncObjectSchema(...args: any[]): Promise<any>;
+  /** DDL: drop the physical table for an object schema. */
+  dropObjectSchema(...args: any[]): Promise<any>;
+  // Protocol accesses additional engine members structurally; keep it permissive
+  // for this relocation (behavior unchanged — the concrete engine is injected).
+  [key: string]: any;
+}

packages/metadata-protocol/src/host-engine.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { ObjectStackProtocolImplementation, ConcurrentUpdateError, normalizeViewMetadata } from './protocol.js';
+
+export { SysMetadataRepository, resetEnvWritableMetadataTypes } from './sys-metadata-repository.js';
+export type {
+  SysMetadataEngine,
+  SysMetadataRepositoryOptions,
+  OverlayState,
+  ExtendedOperation,
+} from './sys-metadata-repository.js';
+
+export {
+  computeMetadataDiagnostics,
+  computeViewReferenceDiagnostics,
+  decorateMetadataItem,
+  decorateMetadataItems,
+} from './metadata-diagnostics.js';
+export type { MetadataDiagnostics } from './metadata-diagnostics.js';
+
+export type { MetadataHostEngine } from './host-engine.js';
+
+export { SeedLoaderService } from './seed-loader.js';
+export { runBuildProbes } from './build-probes.js';
+export type {
+  RuntimeBuildIssue,
+  BuildProbeReport,
+  RunBuildProbesOptions,
+  ProbeEngine,
+  ProbeAnalytics,
+} from './build-probes.js';

packages/metadata-protocol/src/index.ts

@@ -3,7 +3,7 @@
 import { ObjectStackProtocol } from '@objectstack/spec/api';
 import { IDataEngine } from '@objectstack/core';
 import { readEnvWithDeprecation } from '@objectstack/types';
-import type { ObjectQL } from './engine.js';
+import type { MetadataHostEngine } from './host-engine.js';
 import { SysMetadataRepository, type SysMetadataEngine } from './sys-metadata-repository.js';
 import { ConflictError } from '@objectstack/metadata-core';
 import type {
@@ -667,7 +667,7 @@ function detectDestructiveObjectChanges(prev: any, next: any): Array<{
 }
 
 export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
-    private engine: ObjectQL;
+    private engine: MetadataHostEngine;
     private getServicesRegistry?: () => Map<string, any>;
     private getFeedService?: () => IFeedService | undefined;
     /**
@@ -694,7 +694,7 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         getFeedService?: () => IFeedService | undefined,
         environmentId?: string,
     ) {
-        this.engine = engine as ObjectQL;
+        this.engine = engine as MetadataHostEngine;
         this.getServicesRegistry = getServicesRegistry;
         this.getFeedService = getFeedService;
         this.environmentId = environmentId;