@objectstack/objectql 4.2.0 → 5.1.0

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
 import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
+import * as _objectstack_metadata_core from '@objectstack/metadata-core';
+import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, DeleteOptions, DeleteResult, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } from '@objectstack/metadata-core';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 import { IFeedService, IRealtimeService } from '@objectstack/spec/contracts';
@@ -244,6 +246,21 @@ declare class SchemaRegistry {
         id: string;
         globs: string[];
     }[];
+    /**
+     * Invalidate the merged-schema cache for a single FQN (or short name).
+     *
+     * Call this from event-driven consumers (ADR-0008 M0 PR-7) when an
+     * upstream metadata change makes the cached merged definition stale.
+     * The contributor list is preserved — only the cached merge result is
+     * dropped, so the next `resolveObject(fqn)` recomputes from scratch.
+     *
+     * Accepts either an FQN (`acme__contact`) or a bare short name
+     * (`contact`); for the latter, all entries whose suffix matches the
+     * name are invalidated.
+     */
+    invalidate(fqnOrName: string): void;
+    /** Drop every entry from the merged-schema cache. */
+    invalidateAll(): void;
     /**
      * Clear all registry state. Use only for testing.
      */
@@ -263,7 +280,20 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * metadata even if several projects share the same physical database.
      */
     private projectId?;
+    /**
+     * Lazily-instantiated SysMetadataRepository per organization. Keyed by
+     * `${organizationId ?? '__env__'}`. Repositories are stateful — they
+     * carry the per-org `seqCounter` and watch subscribers — so we cache
+     * them rather than constructing one per call.
+     */
+    private overlayRepos;
     constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, projectId?: string);
+    /**
+     * Lazily obtain a SysMetadataRepository for the given organization.
+     * Env-wide overlays (organizationId == null) share a singleton under
+     * the `__env__` key.
+     */
+    private getOverlayRepo;
     /**
      * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
      * on `sys_metadata`. ADR-0005: scopes overlays by
@@ -561,14 +591,53 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private static readonly OVERLAY_ALLOWED_TYPES;
     /** Normalize plural→singular before consulting the allow-list. */
     private static isOverlayAllowed;
+    /**
+     * Mirror an object-type overlay write into the in-memory engine
+     * registry so subsequent CRUD finds the new schema. Idempotent and
+     * safe to call after a successful persistence call. For the legacy
+     * write path this is invoked BEFORE persistence (historical behavior
+     * preserved); for the PR-10d.3 repository path it is invoked only
+     * AFTER `put()` resolves successfully, so a failed write — DB error,
+     * optimistic-lock conflict, validation failure — never leaks a
+     * stale schema into the registry.
+     */
+    private applyObjectRegistryMutation;
     saveMetaItem(request: {
         type: string;
         name: string;
         item?: any;
         organizationId?: string;
+        parentVersion?: string | null;
+        actor?: string;
     }): Promise<{
         success: boolean;
+        version: string;
+        seq: number;
         message: string;
+    } | {
+        success: boolean;
+        message: string;
+        version?: undefined;
+        seq?: undefined;
+    }>;
+    /**
+     * Yield the durable change-log for a single metadata item — every
+     * put/delete recorded in `sys_metadata_history` for `(org, type, name)`,
+     * in event_seq order. Powers the Studio "History" tab and any
+     * client-side audit timeline.
+     *
+     * Returns `[]` for non-overlay-allowed types (the legacy raw-engine
+     * path doesn't record history) instead of throwing — callers can treat
+     * "no history" uniformly.
+     */
+    historyMetaItem(request: {
+        type: string;
+        name: string;
+        organizationId?: string;
+        sinceSeq?: number;
+        limit?: number;
+    }): Promise<{
+        events: _objectstack_metadata_core.MetadataEvent[];
     }>;
     /**
      * Remove a customization overlay row for the given metadata item, so the
@@ -580,10 +649,13 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         name: string;
         organizationId?: string;
+        parentVersion?: string | null;
+        actor?: string;
     }): Promise<{
         success: boolean;
         message?: string;
         reset?: boolean;
+        seq?: number;
     }>;
     /**
      * Hydrate SchemaRegistry from the database on startup.
@@ -614,6 +686,141 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     feedUnsubscribe(request: any): Promise<any>;
 }
 
+/**
+ * Sub-set of the ObjectQL engine shape we depend on. Kept narrow so
+ * tests can stub it with a plain mock. Mirrors the real engine's
+ * `options.context` pattern so transactions can thread through.
+ */
+interface SysMetadataEngine {
+    find(table: string, options: {
+        where: Record<string, unknown>;
+        limit?: number;
+        orderBy?: any;
+        context?: any;
+    }): Promise<any[]>;
+    findOne(table: string, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<any | null>;
+    insert(table: string, data: Record<string, unknown>, options?: {
+        context?: any;
+    }): Promise<{
+        id: string;
+    }>;
+    update(table: string, data: Record<string, unknown>, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(table: string, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Optional. Falls through to direct callback invocation if the
+     * underlying driver lacks ACID support (matches the real
+     * `ObjectQL.transaction` semantics). Repository code must not rely on
+     * rollback for correctness against in-memory drivers.
+     */
+    transaction?<T>(callback: (trxCtx: any) => Promise<T>, baseContext?: any): Promise<T>;
+}
+interface SysMetadataRepositoryOptions {
+    engine: SysMetadataEngine;
+    /**
+     * Tenancy scope. `null` writes to env-wide overlay rows; a string
+     * scopes to one organization (the supported shared-DB tenant model
+     * — see ADR-0005 amendment).
+     */
+    organizationId?: string | null;
+    /** Org label embedded in returned MetaRefs. Defaults to organizationId or `"system"`. */
+    orgLabel?: string;
+}
+declare class SysMetadataRepository implements MetadataRepository {
+    private readonly engine;
+    private readonly organizationId;
+    private readonly orgLabel;
+    /**
+     * Local seq counter for in-memory watch() event broadcasts. Mirrors
+     * the durable `event_seq` we write into `sys_metadata_history` on
+     * each successful put/delete — assigned AFTER the transaction commits
+     * so we never broadcast events that got rolled back.
+     */
+    private seqCounter;
+    private readonly watchers;
+    private closed;
+    /** Table name for the durable event log. */
+    private readonly historyTable;
+    constructor(opts: SysMetadataRepositoryOptions);
+    /**
+     * Run `cb` inside `engine.transaction(...)` if the engine supports it,
+     * otherwise fall through to a direct call. Matches the real
+     * `ObjectQL.transaction` semantics — in-memory drivers (and our test
+     * fakes) get no rollback, which is acceptable because production
+     * always runs on a SQL driver with real ACID.
+     */
+    private withTxn;
+    /**
+     * Read the current overlay row. Returns null if no row exists —
+     * callers (e.g. LayeredRepository) fall through to lower layers.
+     */
+    get(ref: MetaRef): Promise<MetadataItem | null>;
+    /**
+     * Resolve a historical version by content hash (ADR-0009).
+     *
+     * Looks up `sys_metadata_history` by `(organization_id, type, name,
+     * checksum)`. Returns null if no row matches. `executionPinned` types
+     * are guaranteed to find their body here because history GC skips
+     * them.
+     */
+    getByHash(ref: MetaRef, hash: string): Promise<MetadataItem | null>;
+    put(ref: MetaRef, spec: unknown, opts: PutOptions): Promise<PutResult>;
+    delete(ref: MetaRef, opts: DeleteOptions): Promise<DeleteResult>;
+    list(filter: ListFilter): AsyncIterable<MetadataItemHeader>;
+    /**
+     * Yield every history event for `(org, type?, name?)` from the
+     * durable log, ordered by per-(type,name) `version` ascending. When
+     * `filter.type`/`filter.name` are unset the consumer gets the full
+     * org-scoped event stream — still ordered by version within each
+     * (type,name) bucket, then by `recorded_at` across buckets (we sort
+     * client-side because the test engine doesn't honor `orderBy`).
+     */
+    history(ref: MetaRef, opts?: HistoryOptions): AsyncIterable<MetadataEvent>;
+    /**
+     * Live event stream. Fires for every successful put/delete on THIS
+     * instance — cross-replica fan-out is M1. Manual AsyncIterator (not
+     * an async generator) so we can deterministically tear down via
+     * `iter.return()`, matching the pattern used by InMemoryRepository.
+     */
+    watch(filter: WatchFilter, since?: number): AsyncIterable<MetadataEvent>;
+    /** Shut down all watch iterators. */
+    close(): void;
+    private assertOpen;
+    private assertAllowed;
+    private whereFor;
+    private fullRef;
+    private rowToItem;
+    private broadcast;
+    private matchesFilter;
+    /**
+     * Per-org monotonic event sequence. Reads `MAX(event_seq) + 1` from
+     * `sys_metadata_history` scoped by `organization_id`. MUST be called
+     * inside a transaction (the only caller is the put/delete txn body) —
+     * concurrent writers in the same org race otherwise.
+     */
+    private nextEventSeq;
+    /**
+     * Per-(org,type,name) lineage counter. Reads from history (not from
+     * `sys_metadata.version`) so delete + recreate continues incrementing
+     * instead of restarting at 1.
+     */
+    private nextItemVersion;
+    /** Lightweight UUID-ish id for history rows; sufficient for an audit log. */
+    private uuid;
+}
+
 type HookHandler = (context: HookContext) => Promise<void> | void;
 /**
  * Per-object hook entry with priority support
@@ -1515,9 +1722,25 @@ declare class ObjectQLPlugin implements Plugin {
     private hostContext?;
     private projectId?;
     private skipSchemaSync;
+    /** Unsubscribe handles for metadata-event subscriptions (ADR-0008 PR-7). */
+    private metadataUnsubscribes;
     constructor(qlOrOptions?: ObjectQL | ObjectQLPluginOptions, hostContext?: Record<string, any>);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
+    stop: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Subscribe to `object` metadata events from the metadata service and
+     * invalidate the SchemaRegistry merge cache on each event (ADR-0008
+     * PR-7). For create/update we also re-load the affected object from
+     * the metadata service so subsequent reads see the new definition;
+     * for delete we unregister it from every contributing package.
+     *
+     * Events are filtered to the canonical `object` type — view/dashboard
+     * /flow edits go through their own consumers (Studio SSE, REST cache).
+     *
+     * Stored unsubscribe handle is invoked from {@link stop}.
+     */
+    private subscribeToMetadataEvents;
     /**
      * Register built-in audit hooks for auto-stamping created_by/updated_by
      * and fetching previousData for update/delete operations. These are
@@ -1698,4 +1921,4 @@ declare function convertIntrospectedSchemaToObjects(introspectedSchema: Introspe
     skipSystemColumns?: boolean;
 }): ServiceObject[];
 
-export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, validateRecord, wrapDeclarativeHook };
+export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, validateRecord, wrapDeclarativeHook };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
 import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
+import * as _objectstack_metadata_core from '@objectstack/metadata-core';
+import { MetadataRepository, MetaRef, MetadataItem, PutOptions, PutResult, DeleteOptions, DeleteResult, ListFilter, MetadataItemHeader, HistoryOptions, MetadataEvent, WatchFilter } from '@objectstack/metadata-core';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
 import { IFeedService, IRealtimeService } from '@objectstack/spec/contracts';
@@ -244,6 +246,21 @@ declare class SchemaRegistry {
         id: string;
         globs: string[];
     }[];
+    /**
+     * Invalidate the merged-schema cache for a single FQN (or short name).
+     *
+     * Call this from event-driven consumers (ADR-0008 M0 PR-7) when an
+     * upstream metadata change makes the cached merged definition stale.
+     * The contributor list is preserved — only the cached merge result is
+     * dropped, so the next `resolveObject(fqn)` recomputes from scratch.
+     *
+     * Accepts either an FQN (`acme__contact`) or a bare short name
+     * (`contact`); for the latter, all entries whose suffix matches the
+     * name are invalidated.
+     */
+    invalidate(fqnOrName: string): void;
+    /** Drop every entry from the merged-schema cache. */
+    invalidateAll(): void;
     /**
      * Clear all registry state. Use only for testing.
      */
@@ -263,7 +280,20 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * metadata even if several projects share the same physical database.
      */
     private projectId?;
+    /**
+     * Lazily-instantiated SysMetadataRepository per organization. Keyed by
+     * `${organizationId ?? '__env__'}`. Repositories are stateful — they
+     * carry the per-org `seqCounter` and watch subscribers — so we cache
+     * them rather than constructing one per call.
+     */
+    private overlayRepos;
     constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, projectId?: string);
+    /**
+     * Lazily obtain a SysMetadataRepository for the given organization.
+     * Env-wide overlays (organizationId == null) share a singleton under
+     * the `__env__` key.
+     */
+    private getOverlayRepo;
     /**
      * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
      * on `sys_metadata`. ADR-0005: scopes overlays by
@@ -561,14 +591,53 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private static readonly OVERLAY_ALLOWED_TYPES;
     /** Normalize plural→singular before consulting the allow-list. */
     private static isOverlayAllowed;
+    /**
+     * Mirror an object-type overlay write into the in-memory engine
+     * registry so subsequent CRUD finds the new schema. Idempotent and
+     * safe to call after a successful persistence call. For the legacy
+     * write path this is invoked BEFORE persistence (historical behavior
+     * preserved); for the PR-10d.3 repository path it is invoked only
+     * AFTER `put()` resolves successfully, so a failed write — DB error,
+     * optimistic-lock conflict, validation failure — never leaks a
+     * stale schema into the registry.
+     */
+    private applyObjectRegistryMutation;
     saveMetaItem(request: {
         type: string;
         name: string;
         item?: any;
         organizationId?: string;
+        parentVersion?: string | null;
+        actor?: string;
     }): Promise<{
         success: boolean;
+        version: string;
+        seq: number;
         message: string;
+    } | {
+        success: boolean;
+        message: string;
+        version?: undefined;
+        seq?: undefined;
+    }>;
+    /**
+     * Yield the durable change-log for a single metadata item — every
+     * put/delete recorded in `sys_metadata_history` for `(org, type, name)`,
+     * in event_seq order. Powers the Studio "History" tab and any
+     * client-side audit timeline.
+     *
+     * Returns `[]` for non-overlay-allowed types (the legacy raw-engine
+     * path doesn't record history) instead of throwing — callers can treat
+     * "no history" uniformly.
+     */
+    historyMetaItem(request: {
+        type: string;
+        name: string;
+        organizationId?: string;
+        sinceSeq?: number;
+        limit?: number;
+    }): Promise<{
+        events: _objectstack_metadata_core.MetadataEvent[];
     }>;
     /**
      * Remove a customization overlay row for the given metadata item, so the
@@ -580,10 +649,13 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         name: string;
         organizationId?: string;
+        parentVersion?: string | null;
+        actor?: string;
     }): Promise<{
         success: boolean;
         message?: string;
         reset?: boolean;
+        seq?: number;
     }>;
     /**
      * Hydrate SchemaRegistry from the database on startup.
@@ -614,6 +686,141 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     feedUnsubscribe(request: any): Promise<any>;
 }
 
+/**
+ * Sub-set of the ObjectQL engine shape we depend on. Kept narrow so
+ * tests can stub it with a plain mock. Mirrors the real engine's
+ * `options.context` pattern so transactions can thread through.
+ */
+interface SysMetadataEngine {
+    find(table: string, options: {
+        where: Record<string, unknown>;
+        limit?: number;
+        orderBy?: any;
+        context?: any;
+    }): Promise<any[]>;
+    findOne(table: string, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<any | null>;
+    insert(table: string, data: Record<string, unknown>, options?: {
+        context?: any;
+    }): Promise<{
+        id: string;
+    }>;
+    update(table: string, data: Record<string, unknown>, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(table: string, options: {
+        where: Record<string, unknown>;
+        context?: any;
+    }): Promise<{
+        deleted: number;
+    }>;
+    /**
+     * Optional. Falls through to direct callback invocation if the
+     * underlying driver lacks ACID support (matches the real
+     * `ObjectQL.transaction` semantics). Repository code must not rely on
+     * rollback for correctness against in-memory drivers.
+     */
+    transaction?<T>(callback: (trxCtx: any) => Promise<T>, baseContext?: any): Promise<T>;
+}
+interface SysMetadataRepositoryOptions {
+    engine: SysMetadataEngine;
+    /**
+     * Tenancy scope. `null` writes to env-wide overlay rows; a string
+     * scopes to one organization (the supported shared-DB tenant model
+     * — see ADR-0005 amendment).
+     */
+    organizationId?: string | null;
+    /** Org label embedded in returned MetaRefs. Defaults to organizationId or `"system"`. */
+    orgLabel?: string;
+}
+declare class SysMetadataRepository implements MetadataRepository {
+    private readonly engine;
+    private readonly organizationId;
+    private readonly orgLabel;
+    /**
+     * Local seq counter for in-memory watch() event broadcasts. Mirrors
+     * the durable `event_seq` we write into `sys_metadata_history` on
+     * each successful put/delete — assigned AFTER the transaction commits
+     * so we never broadcast events that got rolled back.
+     */
+    private seqCounter;
+    private readonly watchers;
+    private closed;
+    /** Table name for the durable event log. */
+    private readonly historyTable;
+    constructor(opts: SysMetadataRepositoryOptions);
+    /**
+     * Run `cb` inside `engine.transaction(...)` if the engine supports it,
+     * otherwise fall through to a direct call. Matches the real
+     * `ObjectQL.transaction` semantics — in-memory drivers (and our test
+     * fakes) get no rollback, which is acceptable because production
+     * always runs on a SQL driver with real ACID.
+     */
+    private withTxn;
+    /**
+     * Read the current overlay row. Returns null if no row exists —
+     * callers (e.g. LayeredRepository) fall through to lower layers.
+     */
+    get(ref: MetaRef): Promise<MetadataItem | null>;
+    /**
+     * Resolve a historical version by content hash (ADR-0009).
+     *
+     * Looks up `sys_metadata_history` by `(organization_id, type, name,
+     * checksum)`. Returns null if no row matches. `executionPinned` types
+     * are guaranteed to find their body here because history GC skips
+     * them.
+     */
+    getByHash(ref: MetaRef, hash: string): Promise<MetadataItem | null>;
+    put(ref: MetaRef, spec: unknown, opts: PutOptions): Promise<PutResult>;
+    delete(ref: MetaRef, opts: DeleteOptions): Promise<DeleteResult>;
+    list(filter: ListFilter): AsyncIterable<MetadataItemHeader>;
+    /**
+     * Yield every history event for `(org, type?, name?)` from the
+     * durable log, ordered by per-(type,name) `version` ascending. When
+     * `filter.type`/`filter.name` are unset the consumer gets the full
+     * org-scoped event stream — still ordered by version within each
+     * (type,name) bucket, then by `recorded_at` across buckets (we sort
+     * client-side because the test engine doesn't honor `orderBy`).
+     */
+    history(ref: MetaRef, opts?: HistoryOptions): AsyncIterable<MetadataEvent>;
+    /**
+     * Live event stream. Fires for every successful put/delete on THIS
+     * instance — cross-replica fan-out is M1. Manual AsyncIterator (not
+     * an async generator) so we can deterministically tear down via
+     * `iter.return()`, matching the pattern used by InMemoryRepository.
+     */
+    watch(filter: WatchFilter, since?: number): AsyncIterable<MetadataEvent>;
+    /** Shut down all watch iterators. */
+    close(): void;
+    private assertOpen;
+    private assertAllowed;
+    private whereFor;
+    private fullRef;
+    private rowToItem;
+    private broadcast;
+    private matchesFilter;
+    /**
+     * Per-org monotonic event sequence. Reads `MAX(event_seq) + 1` from
+     * `sys_metadata_history` scoped by `organization_id`. MUST be called
+     * inside a transaction (the only caller is the put/delete txn body) —
+     * concurrent writers in the same org race otherwise.
+     */
+    private nextEventSeq;
+    /**
+     * Per-(org,type,name) lineage counter. Reads from history (not from
+     * `sys_metadata.version`) so delete + recreate continues incrementing
+     * instead of restarting at 1.
+     */
+    private nextItemVersion;
+    /** Lightweight UUID-ish id for history rows; sufficient for an audit log. */
+    private uuid;
+}
+
 type HookHandler = (context: HookContext) => Promise<void> | void;
 /**
  * Per-object hook entry with priority support
@@ -1515,9 +1722,25 @@ declare class ObjectQLPlugin implements Plugin {
     private hostContext?;
     private projectId?;
     private skipSchemaSync;
+    /** Unsubscribe handles for metadata-event subscriptions (ADR-0008 PR-7). */
+    private metadataUnsubscribes;
     constructor(qlOrOptions?: ObjectQL | ObjectQLPluginOptions, hostContext?: Record<string, any>);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
+    stop: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Subscribe to `object` metadata events from the metadata service and
+     * invalidate the SchemaRegistry merge cache on each event (ADR-0008
+     * PR-7). For create/update we also re-load the affected object from
+     * the metadata service so subsequent reads see the new definition;
+     * for delete we unregister it from every contributing package.
+     *
+     * Events are filtered to the canonical `object` type — view/dashboard
+     * /flow edits go through their own consumers (Studio SSE, REST cache).
+     *
+     * Stored unsubscribe handle is invoked from {@link stop}.
+     */
+    private subscribeToMetadataEvents;
     /**
      * Register built-in audit hooks for auto-stamping created_by/updated_by
      * and fetching previousData for update/delete operations. These are
@@ -1698,4 +1921,4 @@ declare function convertIntrospectedSchemaToObjects(introspectedSchema: Introspe
     skipSystemColumns?: boolean;
 }): ServiceObject[];
 
-export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, validateRecord, wrapDeclarativeHook };
+export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, type SysMetadataEngine, SysMetadataRepository, type SysMetadataRepositoryOptions, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, validateRecord, wrapDeclarativeHook };