feat(objectql): add lean @objectstack/objectql/core entry + D2 boundary 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>

Author: os-zhuang

.changeset/extract-metadata-protocol.md

@@ -12,3 +12,5 @@ The protocol no longer depends on the concrete `ObjectQL` class — it is typed
 **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).
+
+Also adds a lean **`@objectstack/objectql/core`** entry — the engine/registry/hooks/validation surface only, with no kernel plugin or metadata protocol — so a thin embedder can import just the engine and never pull `@objectstack/metadata-protocol` into its bundle. A boundary ratchet test guards the entry.

packages/objectql/package.json

@@ -10,10 +10,15 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.mjs",
+      "require": "./dist/core.js"
     }
   },
   "scripts": {
-    "build": "tsup --config ../../tsup.config.ts",
+    "build": "tsup",
     "test": "vitest run"
   },
   "dependencies": {

packages/objectql/src/core-boundary.ratchet.test.ts

@@ -0,0 +1,73 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0076 D2 boundary ratchet. The lean engine entry `@objectstack/objectql/core`
+// (src/core.ts) and its entire local import closure must NOT depend on the kernel
+// plugin, the kernel factory, or the metadata-management protocol — so a thin
+// embedder importing `@objectstack/objectql/core` never pulls
+// `@objectstack/metadata-protocol` (or its 268KB) into its graph.
+//
+// If this test fails, you added a forbidden import somewhere reachable from
+// core.ts. Keep metadata/plugin/kernel concerns out of the core closure.
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SRC = dirname(fileURLToPath(import.meta.url));
+
+const FORBIDDEN_PACKAGES = ['@objectstack/metadata-protocol'];
+const FORBIDDEN_LOCAL = ['plugin', 'kernel-factory'];
+
+function localImports(source: string): string[] {
+  const out: string[] = [];
+  const re = /(?:from|import)\s*\(?\s*['"](\.\.?\/[^'"]+)['"]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source))) out.push(m[1]);
+  return out;
+}
+
+function toTsPath(fromFile: string, spec: string): string {
+  const base = resolve(dirname(fromFile), spec.replace(/\.js$/, ''));
+  return base.endsWith('.ts') ? base : `${base}.ts`;
+}
+
+describe('ADR-0076 D2 — @objectstack/objectql/core boundary', () => {
+  it('core.ts closure pulls neither metadata-protocol nor plugin/kernel-factory', () => {
+    const entry = resolve(SRC, 'core.ts');
+    const visited = new Set<string>();
+    const violations: string[] = [];
+    const stack = [entry];
+
+    while (stack.length) {
+      const file = stack.pop()!;
+      if (visited.has(file)) continue;
+      visited.add(file);
+
+      let src: string;
+      try {
+        src = readFileSync(file, 'utf8');
+      } catch {
+        continue; // generated / non-existent; ignore
+      }
+
+      for (const pkg of FORBIDDEN_PACKAGES) {
+        if (new RegExp(`['"]${pkg.replace('/', '\\/')}['"]`).test(src)) {
+          violations.push(`${file} imports forbidden package ${pkg}`);
+        }
+      }
+
+      for (const spec of localImports(src)) {
+        const base = spec.replace(/\.js$/, '').split('/').pop();
+        if (FORBIDDEN_LOCAL.includes(base ?? '')) {
+          violations.push(`${file} imports forbidden local module ./${base}`);
+        }
+        stack.push(toTsPath(file, spec));
+      }
+    }
+
+    expect(violations, violations.join('\n')).toEqual([]);
+    // sanity: the engine itself IS in the closure
+    expect([...visited].some((f) => f.endsWith('/engine.ts'))).toBe(true);
+  });
+});

packages/objectql/src/core.ts

@@ -0,0 +1,78 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Lean engine entry (ADR-0076). Exposes the data engine surface — engine,
+// registry, hooks, validation, in-memory aggregation, utilities — WITHOUT the
+// kernel plugin (`ObjectQLPlugin`), the kernel factory, or any metadata
+// management (`@objectstack/metadata-protocol`). Embedders that want only the
+// engine (e.g. a thin gateway) import from `@objectstack/objectql/core` so the
+// 268KB metadata protocol is never pulled into their dependency graph.
+//
+// A boundary ratchet (ADR-0076 D2) keeps this entry free of protocol/plugin
+// imports; do not add `./plugin`, `./kernel-factory`, or `@objectstack/metadata-protocol`
+// re-exports here.
+
+// Registry
+export {
+  SchemaRegistry,
+  applySystemFields,
+  computeFQN,
+  parseFQN,
+  RESERVED_NAMESPACES,
+  DEFAULT_OWNER_PRIORITY,
+  DEFAULT_EXTENDER_PRIORITY,
+} from './registry.js';
+export type { ObjectContributor, SchemaRegistryOptions } from './registry.js';
+
+// Engine
+export { ObjectQL, ObjectRepository, ScopedContext } from './engine.js';
+export type { ObjectQLHostContext, HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js';
+
+// In-memory aggregation fallback
+export { applyInMemoryAggregation, bucketDateValue } from './in-memory-aggregation.js';
+
+// Hook binder & wrappers (declarative-metadata → engine glue)
+export { bindHooksToEngine } from './hook-binder.js';
+export type { BindHooksOptions, BindHooksResult } from './hook-binder.js';
+export { wrapDeclarativeHook } from './hook-wrappers.js';
+export type { WrapDeclarativeOptions } from './hook-wrappers.js';
+
+// Validation
+export { ValidationError, validateRecord } from './validation/record-validator.js';
+export type { FieldValidationError } from './validation/record-validator.js';
+export { evaluateValidationRules, needsPriorRecord, legalNextStates } from './validation/rule-validator.js';
+export type { EvaluateRulesOptions } from './validation/rule-validator.js';
+export {
+  InMemoryHookMetricsRecorder,
+  noopHookMetricsRecorder,
+} from './hook-metrics.js';
+export type {
+  HookMetricsRecorder,
+  HookMetricLabel,
+  HookMetricOutcome,
+  HookSkipReason,
+} from './hook-metrics.js';
+
+// MetadataFacade
+export { MetadataFacade } from './metadata-facade.js';
+
+// Secret-field channel helpers
+export {
+  SECRET_REF_PREFIX,
+  SECRET_MASK,
+  makeSecretRef,
+  isSecretRef,
+  parseSecretRef,
+  collectSecretFields,
+} from './secret-fields.js';
+
+// Utilities
+export {
+  toTitleCase,
+  convertIntrospectedSchemaToObjects,
+} from './util.js';
+export type {
+  IntrospectedColumn,
+  IntrospectedForeignKey,
+  IntrospectedTable,
+  IntrospectedSchema,
+} from './util.js';

packages/objectql/tsup.config.ts

@@ -0,0 +1,16 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  // `core` is the lean engine entry (ADR-0076) — engine/registry/hooks/validation
+  // only, no kernel plugin or @objectstack/metadata-protocol. `index` is the
+  // batteries-included barrel.
+  entry: ['src/index.ts', 'src/core.ts'],
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  dts: !process.env.OS_SKIP_DTS,
+  format: ['esm', 'cjs'],
+  target: 'es2020',
+});