feat(spec,objectql): IObjectQLEngine —— objectql 槽的契约落地,类 implements 之,七个本地 stand-in 退场 (#4251 B3) (#4404)

* feat(spec,objectql): IObjectQLEngine -- the objectql slot's contract exists, the class implements it, the seven local stand-ins are deleted (#4251 B3)

The ledger can finally say what each of ObjectQL's two registration names
means: `data` stays IDataEngine (the data plane); `objectql` resolves to
IObjectQLEngine -- schema access (getSchema/getObject/registry), actions
(registerAction/removeActionsByPackage/executeAction), hook & middleware
seams (registerHook/unregisterHooksByPackage/registerFunction/
registerMiddleware/bindHooks), the first-wins default runners and hook
metrics, boot wiring (registerDriver/setDatasourceMapping/registerApp),
and ops probes (checkDriversHealth/wasDatastoreCreatedFromEmpty/
invalidateDataMigrationFlags). The ledger test pins the relation:
objectql strictly WIDENS data, deliberately no longer equal.

Why implements is the point: the honest state for two batches -- recorded
on DomainHandlerContext.getObjectQL -- was that the wider surface had no
contract, so seven consumer-local stand-ins accumulated
(AppEngineSurface, EngineRegistrySurface, EngineExtensionSurface,
SecurityEngineSurface, FreshDatastoreEngine, the dispatcher's inline
checkDriversHealth slice, getObjectQL: any). Each was honest and each was
an UNCHECKED claim: getService<Surface>() is an assertion, so an engine
rename would break every consumer at runtime with zero compile errors.
`ObjectQL implements IObjectQLEngine` turns all of them into one
compiler-verified claim; all seven are deleted, and getObjectQL is typed
Promise<IObjectQLEngine | null> end to end.

Evidence bar unchanged: every member has a cross-package consumer through
the slot; triggerHooks (cross-package only in tests) stays off.

_registry never leaves the engine package now: plugin-security's five
declared-metadata readers reached the private field through `any` -- the
same reach /me/apps had in B2 -- all migrated to the public getter the
contract declares, test doubles included.

IMetadataService gains subscribe?/loadMany? -- implemented by
MetadataManager beside watch all along, reached only via `any` by
ObjectQLPlugin's metadata bridge. With them declared, that bridge's six
lookups and metadata-protocol's objectql lookup carry contract types and
both files leave the grandfather list: baseline 167 -> 159 sites,
36 -> 34 files.

Verified: spec build + 7198/282; objectql build (the implements check) +
1464/89; runtime 1015/70; plugin-security 677/32; plugin-hono-server
135/12; plugin-auth 579/26; platform-objects 254/8; metadata 281/13;
metadata-protocol 136/21; all eight dts builds; ratchet holds 159/34
none new; eslint clean.

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

* fix(spec,objectql,plugin-security): CI round-trip fixes -- and the implements check caught a second spec-internal double (#4251 B3)

Three fixes, all caught by gates:

1. security-plugin:880 -- the contract's getSchema returns `unknown`;
   narrow to EngineOwnedSchemaLike at the guard call (CI Build Core; my
   local batch had been aborted by an earlier failure and I re-ran only
   the failed package -- the DEBT-package lesson, second verse).

2. objectql plugin.ts:1583 -- optional-member narrowing does not survive
   into a closure (TS2722); take a bound reference under the guard.

3. IMetadataService.subscribe -- the first draft reused `watch`'s
   callback type, and `MetadataManager implements IMetadataService`
   REJECTED it: subscribe relays the persistence-side MetadataWatchEvent
   (add/changed/deleted + path/stats), not watch's registration-level
   events. The check working exactly as intended, on its first day.
   Fixing it exposed that spec carries TWO types named MetadataWatchEvent
   with different shapes (system/metadata-persistence.zod vs
   kernel/metadata-loader.zod) -- the same double-source shape as the
   http-server shadow, both alive this time. Reported on #4251; merging
   them is its own change. The contract now imports the persistence one
   the implementation uses, with the trap documented at the import.

Verified: all nine touched packages' dts builds in ONE uninterrupted
batch; spec 7198/282, objectql 1464/89, metadata 281/13,
plugin-security 677/32; eslint clean.

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

* chore(spec): regenerate the api-surface snapshot for the two new contract exports (#4251 B3)

`check:api-surface` is spec's public-API snapshot gate, and it reported
exactly what this PR does: "0 breaking (removed/narrowed), 2 added". The
two are IObjectQLEngine and EngineSchemaRegistryView; the regenerated
snapshot diff is +2 lines, -0 -- purely additive, matching the gate's own
count.

Missed because I ran spec's build and tests but not its check:* gates.
#4361 ran all of them; this PR did not. All 16 now pass locally
(check:exported-any included -- the contract's deliberate `any`s at the
framework-handle and engine-local-shape edges are within its allowance).

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

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/objectql-engine-contract.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": patch
+"@objectstack/core": patch
+"@objectstack/runtime": patch
+"@objectstack/metadata-protocol": patch
+"@objectstack/platform-objects": patch
+"@objectstack/plugin-auth": patch
+"@objectstack/plugin-hono-server": patch
+"@objectstack/plugin-security": patch
+---
+
+feat(spec,objectql): `IObjectQLEngine` — the `objectql` slot's contract exists, the class `implements` it, and the seven consumer-local stand-ins are deleted (#4251 B3)
+
+ObjectQL registers one instance under two names, and the ledger can finally say
+what each name means: `data` stays `IDataEngine` (the data plane), `objectql`
+now resolves to **`IObjectQLEngine`** — the full engine: schema access
+(`getSchema` / `getObject` / `registry`), actions (`registerAction` /
+`removeActionsByPackage` / `executeAction`), the hook/middleware seams
+(`registerHook` / `unregisterHooksByPackage` / `registerFunction` /
+`registerMiddleware` / `bindHooks`), the first-wins default runners and hook
+metrics, boot wiring (`registerDriver` / `setDatasourceMapping` /
+`registerApp`), and the ops probes (`checkDriversHealth` /
+`wasDatastoreCreatedFromEmpty` / `invalidateDataMigrationFlags`). The ledger
+test pins the new relation: `objectql` strictly widens `data`, deliberately no
+longer equal.
+
+**Why now, and why `implements` is the point.** The honest state for two
+batches was recorded on `DomainHandlerContext.getObjectQL`: ObjectQL is wider
+than `IDataEngine`, the wider part had no contract, and typing it `IDataEngine`
+would be "the more comfortable-looking lie". The interim discipline — each
+consumer declares the narrow slice it uses — produced seven local surfaces
+(`AppEngineSurface`, `EngineRegistrySurface`, `EngineExtensionSurface`,
+`SecurityEngineSurface`, `FreshDatastoreEngine`, the dispatcher's inline
+`checkDriversHealth` slice, the `getObjectQL: any` itself). Each was honest and
+each was an UNCHECKED claim: `getService<Surface>('objectql')` is an assertion,
+so an engine rename would have broken every consumer at runtime with zero
+compile errors. `ObjectQL implements IObjectQLEngine` converts all of them into
+one compiler-verified claim. All seven stand-ins are deleted; consumers import
+the one declaration. `getObjectQL` is typed `Promise<IObjectQLEngine | null>`
+end to end, closing the oldest documented `any` in the dispatcher.
+
+**Evidence bar unchanged.** Every declared member has a cross-package consumer
+reaching it through the slot; engine members without one (e.g. `triggerHooks`,
+cross-package only in tests) stay off until a caller appears. The registry view
+(`EngineSchemaRegistryView`) declares exactly the eight members consumers use.
+
+**`_registry` never leaves the engine package now.** plugin-security's
+declared-metadata readers (`readDeclared`, permission-set projection, suggested
+audience bindings) reached ObjectQL's private `_registry` field through `any` —
+the same private reach `/me/apps` had in B2, five more times. All migrated to
+the public `registry` getter the contract declares, test doubles included.
+
+**`IMetadataService` gains `subscribe?` / `loadMany?`** — implemented by
+`MetadataManager` beside `watch` all along, reached through the slot only via
+`any` by ObjectQLPlugin's metadata bridge (the re-sync keeping runtime-authored
+hooks/actions live). With them declared, the bridge's six `metadata` lookups
+and metadata-protocol's `objectql` lookup carry contract types, and both files
+leave the grandfather list entirely: baseline **167 → 159 sites, 36 → 34
+files**.

packages/core/src/index.ts

@@ -53,5 +53,7 @@ export type {
     RouteHandler,
     Middleware,
     IDataEngine,
+    IObjectQLEngine,
+    EngineSchemaRegistryView,
     IDataDriver,
 } from '@objectstack/spec/contracts';

packages/metadata-protocol/src/plugin.ts

@@ -23,6 +23,7 @@
  */
 
 import type { Plugin, PluginContext } from '@objectstack/core';
+import type { IObjectQLEngine } from '@objectstack/spec/contracts';
 import {
     SysMetadataObject,
     SysMetadataHistoryObject,
@@ -51,7 +52,7 @@ export function createMetadataProtocolPlugin(options: MetadataProtocolPluginOpti
         dependencies: ['com.objectstack.engine.objectql'],
 
         init: async (ctx: PluginContext) => {
-            const ql: any = ctx.getService('objectql');
+            const ql = ctx.getService<IObjectQLEngine>('objectql');
 
             // Assembly-conflict guard: the engine plugin's built-in assembly
             // (registerProtocol !== false) already registered `protocol`.

packages/objectql/src/engine.ts

@@ -28,6 +28,7 @@ import { ExecutionContext, ExecutionContextInput, ExecutionContextSchema } from
 import {
   IDataDriver,
   IDataEngine,
+  type IObjectQLEngine,
   Logger,
   createLogger,
   withTransientRetry,
@@ -554,7 +555,12 @@ interface SummaryDescriptor {
   filter?: Record<string, unknown>;
 }
 
-export class ObjectQL implements IDataEngine {
+// `implements IObjectQLEngine` is the verification step of #4251 B3: every
+// member the `objectql` slot's contract declares is checked against this class
+// on every build, so the seven consumer-local surface declarations the contract
+// replaced can never silently drift from the engine again. IObjectQLEngine
+// extends IDataEngine, so the old claim rides along.
+export class ObjectQL implements IObjectQLEngine {
   /**
    * Ambient transaction store (ADR-0034). While a `transaction()` callback
    * runs, the active transaction handle lives here so that EVERY data

packages/objectql/src/plugin.ts

@@ -8,6 +8,7 @@ import { StorageNameMapping } from '@objectstack/spec/system';
 import { LifecycleService } from './lifecycle/lifecycle-service.js';
 import { lifecycleSettingsManifest } from './lifecycle/lifecycle-settings.js';
 import { runActionGovernanceInventory } from './action-governance.js';
+import type { IMetadataService } from '@objectstack/spec/contracts';
 
 export type { Plugin, PluginContext };
 
@@ -311,7 +312,7 @@ export class ObjectQLPlugin implements Plugin {
 
     // Sync from external metadata service (e.g. MetadataPlugin) if available
     try {
-        const metadataService = ctx.getService('metadata') as any;
+        const metadataService = ctx.getService<IMetadataService>('metadata');
         if (metadataService && typeof metadataService.loadMany === 'function' && this.ql) {
             await this.loadMetadataFromService(metadataService, ctx);
         }
@@ -1095,7 +1096,7 @@ export class ObjectQLPlugin implements Plugin {
    */
   private async bridgeObjectsToMetadataService(ctx: PluginContext): Promise<void> {
     try {
-      const metadataService = ctx.getService<any>('metadata');
+      const metadataService = ctx.getService<IMetadataService>('metadata');
       if (!metadataService || typeof metadataService.register !== 'function') {
         ctx.logger.debug('Metadata service unavailable for bridging, skipping');
         return;
@@ -1181,9 +1182,9 @@ export class ObjectQLPlugin implements Plugin {
     if (!packageId || !this.ql?.registry) return;
 
     try {
-      let metadataService: any;
+      let metadataService: IMetadataService | undefined;
       try {
-        metadataService = ctx.getService<any>('metadata');
+        metadataService = ctx.getService<IMetadataService>('metadata');
       } catch {
         return; // no metadata service on this kernel — nothing to bridge into
       }
@@ -1383,7 +1384,7 @@ export class ObjectQLPlugin implements Plugin {
 
     let serviceHooks: any[] | null = null;
     try {
-      const metadataService = ctx.getService('metadata') as any;
+      const metadataService = ctx.getService<IMetadataService>('metadata');
       if (metadataService && typeof metadataService.loadMany === 'function') {
         serviceHooks = (await metadataService.loadMany('hook')) ?? [];
       }
@@ -1577,9 +1578,10 @@ export class ObjectQLPlugin implements Plugin {
     if (!ql || typeof ql.listRegisteredActions !== 'function') return;
     let loadStandaloneActions: (() => Promise<any[]>) | undefined;
     try {
-      const meta: any = ctx.getService('metadata');
-      if (meta && typeof meta.loadMany === 'function') {
-        loadStandaloneActions = () => meta.loadMany('action');
+      const meta = ctx.getService<IMetadataService>('metadata');
+      const loadMany = meta?.loadMany;
+      if (meta && typeof loadMany === 'function') {
+        loadStandaloneActions = () => loadMany.call(meta, 'action');
       }
     } catch { /* no metadata service — registry objects still audit */ }
     this.lastGovernanceFingerprint = await runActionGovernanceInventory({
@@ -1638,7 +1640,7 @@ export class ObjectQLPlugin implements Plugin {
 
     let serviceActions: any[] | null = null;
     try {
-      const metadataService = ctx.getService('metadata') as any;
+      const metadataService = ctx.getService<IMetadataService>('metadata');
       if (metadataService && typeof metadataService.loadMany === 'function') {
         serviceActions = (await metadataService.loadMany('action')) ?? [];
       }

packages/platform-objects/src/plugin.ts

@@ -4,20 +4,9 @@ import { SetupAppTranslations } from './apps/translations/index.js';
 import { MetadataFormsTranslations } from './metadata-translations/index.js';
 import { SysMigration } from './system/sys-migration.object.js';
 import { SysSecret } from './system/sys-secret.object.js';
-import { attestFreshDatastore, type MigrationFlagEngine } from './system/migration-flag.js';
-import type { II18nService } from '@objectstack/spec/contracts';
+import { attestFreshDatastore } from './system/migration-flag.js';
+import type { II18nService, IObjectQLEngine } from '@objectstack/spec/contracts';
 
-/**
- * The `objectql` slot's fresh-datastore attestation seam.
- *
- * [#4251] Not on `IDataEngine` — these are ObjectQL's own migration-flag
- * accessors, and the probe at the call site is what runs when the slot holds an
- * engine without them. Declared narrow and named instead of erased to `any`.
- */
-interface FreshDatastoreEngine extends MigrationFlagEngine {
-  wasDatastoreCreatedFromEmpty?(): boolean;
-  invalidateDataMigrationFlags?(): void;
-}
 
 /**
  * `PlatformObjectsPlugin`
@@ -108,9 +97,7 @@ export class PlatformObjectsPlugin {
     // service-storage). A store that was found rather than created attests
     // nothing and keeps producing evidence by scan.
     ctx?.hook?.('kernel:ready', async () => {
-      // [#4251] The fresh-datastore attestation seam is ObjectQL's own, not
-      // `IDataEngine`'s; declared here rather than erased to `any`.
-      let engine: FreshDatastoreEngine | undefined;
+      let engine: IObjectQLEngine | undefined;
       try {
         engine = ctx.getService?.('objectql');
       } catch {

packages/plugins/plugin-auth/src/auth-plugin.ts

@@ -19,7 +19,7 @@ import {
 import { SysOrganizationDetailPage, SysUserDetailPage } from '@objectstack/platform-objects/pages';
 import { resolveTenancyPosture } from '@objectstack/types';
 import { postureEnforcesWall, type OrgScopingEntitlement } from '@objectstack/spec/security';
-import type { IDataEngine, IEmailService, ISmsService } from '@objectstack/spec/contracts';
+import type { IDataEngine, IEmailService, IObjectQLEngine, ISmsService } from '@objectstack/spec/contracts';
 import {
   AuthManager,
   resolveOidcProviderEnabled,
@@ -44,36 +44,6 @@ import {
   authPluginManifestHeader,
 } from './manifest.js';
 
-/**
- * The `objectql` slot BEYOND `IDataEngine` — the hook and middleware seams this
- * plugin installs on the engine.
- *
- * [#4251] The slot's ledger entry is `IDataEngine` and it covers every read and
- * write below; it does not cover `registerHook` / `registerMiddleware`, and no
- * contract has been written for the wider ObjectQL surface yet (the standing
- * record of why is on `getObjectQL` in `@objectstack/runtime`'s
- * `DomainHandlerContext`). Declared here, narrow and named, so the extension is
- * legible instead of hidden under `any` — and so it is deleted, not migrated,
- * when that contract lands.
- *
- * Both members are optional and every call site already guards with
- * `typeof … === 'function'`: the slot is satisfiable by engines that implement
- * neither (mock mode), and this plugin degrades rather than fails there.
- */
-interface EngineExtensionSurface {
-  registerHook?(
-    event: string,
-    handler: (context: any) => Promise<void> | void,
-    options?: { object?: string | string[]; priority?: number; packageId?: string },
-  ): void;
-  registerMiddleware?(
-    fn: (opCtx: any, next: () => Promise<void>) => Promise<void>,
-    options?: { object?: string },
-  ): void;
-}
-
-/** The engine as this plugin uses it: the data contract plus those two seams. */
-type AuthEngine = IDataEngine & EngineExtensionSurface;
 
 /**
  * The `settings` slot, as this plugin reads it.
@@ -764,7 +734,7 @@ export class AuthPlugin implements Plugin {
       // to platform admin" case where kernel:ready fired before any user
       // existed (same wiring the multi-org bootstrap uses).
       try {
-        const ql = ctx.getService<AuthEngine>('objectql');
+        const ql = ctx.getService<IObjectQLEngine>('objectql');
         if (ql && typeof ql.registerMiddleware === 'function') {
           ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
             await next();
@@ -841,7 +811,7 @@ export class AuthPlugin implements Plugin {
       try {
         // Use the kernel's ObjectQL engine (available + hookable at kernel:ready);
         // the auth manager's getDataEngine() is not yet wired this early.
-        const engine = ctx.getService<AuthEngine>('objectql');
+        const engine = ctx.getService<IObjectQLEngine>('objectql');
         if (!engine || typeof engine.registerHook !== 'function') return;
         const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] };
         engine.registerHook('afterInsert', async (hookCtx: any) => {
@@ -883,7 +853,7 @@ export class AuthPlugin implements Plugin {
     // bypass — see identity-write-guard.ts for the full contract.
     ctx.hook('kernel:ready', async () => {
       try {
-        const engine = ctx.getService<AuthEngine>('objectql');
+        const engine = ctx.getService<IObjectQLEngine>('objectql');
         if (!engine || typeof engine.registerHook !== 'function') return;
         registerManagedUpdateWhitelist(SystemObjectName.USER, SYS_USER_PROFILE_EDIT_FIELDS);
         // [ADR-0105 D7] Extension fields ObjectStack adds to better-auth-managed
@@ -910,7 +880,7 @@ export class AuthPlugin implements Plugin {
 
     // Register auth middleware on ObjectQL engine (if available)
     try {
-      const ql = ctx.getService<AuthEngine>('objectql');
+      const ql = ctx.getService<IObjectQLEngine>('objectql');
       if (ql && typeof ql.registerMiddleware === 'function') {
         ql.registerMiddleware(async (opCtx: any, next: () => Promise<void>) => {
           // If context already has userId or isSystem, skip auth resolution

packages/plugins/plugin-hono-server/src/current-user-endpoints.ts

@@ -45,7 +45,7 @@ import {
     type EnableLike,
 } from '@objectstack/spec/data';
 import type { ExecutionContext } from '@objectstack/spec/kernel';
-import type { IAuthService, IMetadataService, Logger } from '@objectstack/spec/contracts';
+import type { IAuthService, IMetadataService, IObjectQLEngine, Logger } from '@objectstack/spec/contracts';
 import { allowPerfDisclosure, isPerfDisclosurePrincipal } from '@objectstack/observability';
 
 /** API prefix these endpoints mount under unless the host overrides it. */
@@ -261,37 +261,6 @@ export function foldWildcardSuperUser(objects: Record<string, any>): void {
     }
 }
 
-/**
- * The `objectql` slot BEYOND `IDataEngine` — the schema registry these
- * endpoints read.
- *
- * [#4251] The slot's ledger entry is `IDataEngine` (ObjectQL registers the SAME
- * instance under `data` and `objectql`), and that covers the reads below. It
- * does NOT cover `registry` / `getSchema`, and the honest record of why lives
- * on `getObjectQL` in `@objectstack/runtime`'s `DomainHandlerContext`: ObjectQL
- * is genuinely wider than `IDataEngine`, nobody has written a contract for the
- * wider part, and typing the whole thing `IDataEngine` would be "the more
- * comfortable-looking lie". So the extra surface is declared here, named and
- * narrow, instead of the lookup being erased to `any` — the wider contract, when
- * someone writes it, absorbs this and the declaration is deleted.
- *
- * Every member is optional and every call site probes with `?.`: the slot is
- * satisfied by engines with no registry at all (test fakes, remote engines), and
- * these endpoints degrade rather than fail when it is absent.
- */
-interface EngineRegistrySurface {
-    /**
-     * The engine's schema registry — the PUBLIC accessor. ObjectQL exposes it as
-     * `get registry()` over the private `_registry` field; `_registry` is what
-     * `/me/apps` used to reach through `as any`, two handlers away from the
-     * `/auth/me/permissions` reach for the public one, for the same object.
-     */
-    readonly registry?: {
-        getAllObjects?(): ApiExposureSchemaLike[];
-        getAllApps?(): unknown[];
-    };
-    getSchema?(objectName: string): unknown;
-}
 
 /**
  * The `security.permissions` slot, as these two handlers use it.
@@ -769,7 +738,7 @@ export function registerCurrentUserEndpoints(
             // (created via the admin UI as `sys_permission_set`
             // rows) that aren't in metadata or bootstrap.
             const ql = (() => {
-                try { return ctx.getService<IDataEngine & EngineRegistrySurface>('objectql') ?? null; }
+                try { return ctx.getService<IObjectQLEngine>('objectql') ?? null; }
                 catch { return null; }
             })();
             const dbLoader = ql
@@ -897,9 +866,12 @@ export function registerCurrentUserEndpoints(
             // can attach their effective apiOperations. Guarded — a failure
             // here must never drop the whole response.
             try {
-                const allSchemas: ApiExposureSchemaLike[] = (() => {
-                    try { return ql?.registry?.getAllObjects?.() ?? []; }
-                    catch { return []; }
+                // The contract's registry view returns `unknown[]` (schema
+                // shape is engine-local); narrow to the slice this seeding
+                // reads, as the callers of getSchema below already do.
+                const allSchemas = (() => {
+                    try { return (ql?.registry?.getAllObjects?.() ?? []) as ApiExposureSchemaLike[]; }
+                    catch { return [] as ApiExposureSchemaLike[]; }
                 })();
                 seedSuperUserRestrictedObjects(objects, allSchemas);
             } catch (e: any) {
@@ -980,7 +952,7 @@ export function registerCurrentUserEndpoints(
                 // private `_registry` while `/auth/me/permissions` read the
                 // `registry` getter over the same field, on the same object,
                 // in the same file — visible only once both were typed.
-                const registry = ctx.getService<EngineRegistrySurface>('objectql')?.registry;
+                const registry = ctx.getService<IObjectQLEngine>('objectql')?.registry;
                 for (const app of registry?.getAllApps?.() ?? []) {
                     if ((app as { name?: unknown })?.name) byName.set(String((app as { name: unknown }).name), app);
                 }