@objectstack/objectql 5.1.0 → 6.0.0

package/dist/index.d.mts

@@ -274,12 +274,12 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     /**
      * Project scope applied to sys_metadata reads/writes. When undefined
      * (single-kernel deployments), rows land in / come from the
-     * platform-global bucket (`project_id IS NULL`). When set, every
+     * platform-global bucket (`environment_id IS NULL`). When set, every
      * saveMetaItem insert/update and loadMetaFromDb query is filtered by
-     * `project_id = projectId`, so per-project kernels see only their own
+     * `environment_id = environmentId`, so per-project kernels see only their own
      * metadata even if several projects share the same physical database.
      */
-    private projectId?;
+    private environmentId?;
     /**
      * Lazily-instantiated SysMetadataRepository per organization. Keyed by
      * `${organizationId ?? '__env__'}`. Repositories are stateful — they
@@ -287,7 +287,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * them rather than constructing one per call.
      */
     private overlayRepos;
-    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, projectId?: string);
+    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, environmentId?: string);
     /**
      * Lazily obtain a SysMetadataRepository for the given organization.
      * Env-wide overlays (organizationId == null) share a singleton under
@@ -297,7 +297,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     /**
      * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
      * on `sys_metadata`. ADR-0005: scopes overlays by
-     * `(type, name, organization_id, project_id, scope)` for active rows only.
+     * `(type, name, organization_id, environment_id, scope)` for active rows only.
      * Idempotent SQL — safe to attempt on every protocol instance.
      *
      * Inlined here (rather than importing from @objectstack/metadata/migrations)
@@ -309,7 +309,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * Exposes the project scope the protocol is bound to. Consumers like
      * the HTTP dispatcher use this to decide whether to trust the process-
      * wide SchemaRegistry or whether they must route a read through the
-     * protocol's project_id-filtered lookup.
+     * protocol's environment_id-filtered lookup.
      */
     getProjectId(): string | undefined;
     private requireFeedService;
@@ -664,7 +664,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      *
      * Per ADR-0005, project-kernel mode ALSO hydrates from sys_metadata —
      * customization overlay rows must survive restart. Scope filter
-     * (`project_id = this.projectId ?? null`) keeps tenants isolated.
+     * (`environment_id = this.environmentId ?? null`) keeps tenants isolated.
      */
     loadMetaFromDb(): Promise<{
         loaded: number;
@@ -899,7 +899,7 @@ declare class ObjectQL implements IDataEngine {
      * Expose the SchemaRegistry for plugins to register metadata.
      *
      * Returns the per-engine instance, NOT the class. Each ObjectQL engine
-     * owns its registry so multi-project kernels remain isolated.
+     * owns its registry so multi-environment kernels remain isolated.
      */
     get registry(): SchemaRegistry;
     /**
@@ -1667,11 +1667,11 @@ declare class MetadataFacade {
 /**
  * Options for ObjectQLPlugin.
  *
- * `projectId` scopes all metadata writes + reads to a specific project.
- * When set, `protocol.saveMetaItem` stamps `project_id = <projectId>` on
+ * `environmentId` scopes all metadata writes + reads to a specific project.
+ * When set, `protocol.saveMetaItem` stamps `environment_id = <environmentId>` on
  * new sys_metadata rows, and `protocol.loadMetaFromDb` filters by the same
  * column. Leave undefined in single-kernel / self-hosted mode — rows land
- * in the platform-global scope (project_id IS NULL).
+ * in the platform-global scope (environment_id IS NULL).
  */
 interface ObjectQLPluginOptions {
     /** Optional pre-built engine. When absent, one is lazily created in init. */
@@ -1679,7 +1679,7 @@ interface ObjectQLPluginOptions {
     /** Passed to `new ObjectQL(...)` when `ql` is not supplied. */
     hostContext?: Record<string, any>;
     /** Scope sys_metadata reads/writes to this project. */
-    projectId?: string;
+    environmentId?: string;
     /**
      * Override the kernel's default plugin-start timeout for this plugin.
      * Defaults to 120000 (120s). Schema sync to a remote SQL backend
@@ -1720,7 +1720,7 @@ declare class ObjectQLPlugin implements Plugin {
     startupTimeout: number;
     private ql;
     private hostContext?;
-    private projectId?;
+    private environmentId?;
     private skipSchemaSync;
     /** Unsubscribe handles for metadata-event subscriptions (ADR-0008 PR-7). */
     private metadataUnsubscribes;

package/dist/index.d.ts

@@ -274,12 +274,12 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     /**
      * Project scope applied to sys_metadata reads/writes. When undefined
      * (single-kernel deployments), rows land in / come from the
-     * platform-global bucket (`project_id IS NULL`). When set, every
+     * platform-global bucket (`environment_id IS NULL`). When set, every
      * saveMetaItem insert/update and loadMetaFromDb query is filtered by
-     * `project_id = projectId`, so per-project kernels see only their own
+     * `environment_id = environmentId`, so per-project kernels see only their own
      * metadata even if several projects share the same physical database.
      */
-    private projectId?;
+    private environmentId?;
     /**
      * Lazily-instantiated SysMetadataRepository per organization. Keyed by
      * `${organizationId ?? '__env__'}`. Repositories are stateful — they
@@ -287,7 +287,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * them rather than constructing one per call.
      */
     private overlayRepos;
-    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, projectId?: string);
+    constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, environmentId?: string);
     /**
      * Lazily obtain a SysMetadataRepository for the given organization.
      * Env-wide overlays (organizationId == null) share a singleton under
@@ -297,7 +297,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     /**
      * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
      * on `sys_metadata`. ADR-0005: scopes overlays by
-     * `(type, name, organization_id, project_id, scope)` for active rows only.
+     * `(type, name, organization_id, environment_id, scope)` for active rows only.
      * Idempotent SQL — safe to attempt on every protocol instance.
      *
      * Inlined here (rather than importing from @objectstack/metadata/migrations)
@@ -309,7 +309,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * Exposes the project scope the protocol is bound to. Consumers like
      * the HTTP dispatcher use this to decide whether to trust the process-
      * wide SchemaRegistry or whether they must route a read through the
-     * protocol's project_id-filtered lookup.
+     * protocol's environment_id-filtered lookup.
      */
     getProjectId(): string | undefined;
     private requireFeedService;
@@ -664,7 +664,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      *
      * Per ADR-0005, project-kernel mode ALSO hydrates from sys_metadata —
      * customization overlay rows must survive restart. Scope filter
-     * (`project_id = this.projectId ?? null`) keeps tenants isolated.
+     * (`environment_id = this.environmentId ?? null`) keeps tenants isolated.
      */
     loadMetaFromDb(): Promise<{
         loaded: number;
@@ -899,7 +899,7 @@ declare class ObjectQL implements IDataEngine {
      * Expose the SchemaRegistry for plugins to register metadata.
      *
      * Returns the per-engine instance, NOT the class. Each ObjectQL engine
-     * owns its registry so multi-project kernels remain isolated.
+     * owns its registry so multi-environment kernels remain isolated.
      */
     get registry(): SchemaRegistry;
     /**
@@ -1667,11 +1667,11 @@ declare class MetadataFacade {
 /**
  * Options for ObjectQLPlugin.
  *
- * `projectId` scopes all metadata writes + reads to a specific project.
- * When set, `protocol.saveMetaItem` stamps `project_id = <projectId>` on
+ * `environmentId` scopes all metadata writes + reads to a specific project.
+ * When set, `protocol.saveMetaItem` stamps `environment_id = <environmentId>` on
  * new sys_metadata rows, and `protocol.loadMetaFromDb` filters by the same
  * column. Leave undefined in single-kernel / self-hosted mode — rows land
- * in the platform-global scope (project_id IS NULL).
+ * in the platform-global scope (environment_id IS NULL).
  */
 interface ObjectQLPluginOptions {
     /** Optional pre-built engine. When absent, one is lazily created in init. */
@@ -1679,7 +1679,7 @@ interface ObjectQLPluginOptions {
     /** Passed to `new ObjectQL(...)` when `ql` is not supplied. */
     hostContext?: Record<string, any>;
     /** Scope sys_metadata reads/writes to this project. */
-    projectId?: string;
+    environmentId?: string;
     /**
      * Override the kernel's default plugin-start timeout for this plugin.
      * Defaults to 120000 (120s). Schema sync to a remote SQL backend
@@ -1720,7 +1720,7 @@ declare class ObjectQLPlugin implements Plugin {
     startupTimeout: number;
     private ql;
     private hostContext?;
-    private projectId?;
+    private environmentId?;
     private skipSchemaSync;
     /** Unsubscribe handles for metadata-event subscriptions (ADR-0008 PR-7). */
     private metadataUnsubscribes;

package/dist/index.js

@@ -1241,7 +1241,7 @@ var SERVICE_CONFIG = {
   search: { route: "/api/v1/search", plugin: "plugin-search" }
 };
 var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementation {
-  constructor(engine, getServicesRegistry, getFeedService, projectId) {
+  constructor(engine, getServicesRegistry, getFeedService, environmentId) {
     /**
      * Lazily-instantiated SysMetadataRepository per organization. Keyed by
      * `${organizationId ?? '__env__'}`. Repositories are stateful — they
@@ -1252,7 +1252,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     /**
      * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
      * on `sys_metadata`. ADR-0005: scopes overlays by
-     * `(type, name, organization_id, project_id, scope)` for active rows only.
+     * `(type, name, organization_id, environment_id, scope)` for active rows only.
      * Idempotent SQL — safe to attempt on every protocol instance.
      *
      * Inlined here (rather than importing from @objectstack/metadata/migrations)
@@ -1262,7 +1262,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     this.engine = engine;
     this.getServicesRegistry = getServicesRegistry;
     this.getFeedService = getFeedService;
-    this.projectId = projectId;
+    this.environmentId = environmentId;
   }
   /**
    * Lazily obtain a SysMetadataRepository for the given organization.
@@ -1330,10 +1330,10 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * Exposes the project scope the protocol is bound to. Consumers like
    * the HTTP dispatcher use this to decide whether to trust the process-
    * wide SchemaRegistry or whether they must route a read through the
-   * protocol's project_id-filtered lookup.
+   * protocol's environment_id-filtered lookup.
    */
   getProjectId() {
-    return this.projectId;
+    return this.environmentId;
   }
   requireFeedService() {
     const svc = this.getFeedService?.();
@@ -1446,7 +1446,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
   async getMetaItems(request) {
     const { packageId } = request;
     let items = [];
-    if (this.projectId === void 0) {
+    if (this.environmentId === void 0) {
       items = [...this.engine.registry.listItems(request.type, packageId)];
       if (items.length === 0) {
         const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
@@ -1498,7 +1498,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           if (data && typeof data === "object" && "name" in data) {
             byName.set(data.name, data);
           }
-          if (this.projectId === void 0) {
+          if (this.environmentId === void 0) {
             this.engine.registry.registerItem(request.type, data, "name");
           }
         }
@@ -2506,7 +2506,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (!request.item) {
       throw new Error("Item data is required");
     }
-    if (this.projectId !== void 0 && !_ObjectStackProtocolImplementation.isOverlayAllowed(request.type)) {
+    if (this.environmentId !== void 0 && !_ObjectStackProtocolImplementation.isOverlayAllowed(request.type)) {
       const allowed = Array.from(_ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES).join(", ");
       const err = new Error(
         `[not_overridable] Metadata type '${request.type}' has not opted into per-org overlay writes. Set allowOrgOverride: true on its DEFAULT_METADATA_TYPE_REGISTRY entry to enable. Currently allowed: ${allowed}. See docs/adr/0005-metadata-customization-overlay.md.`
@@ -2673,7 +2673,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * with {@link saveMetaItem}.
    */
   async deleteMetaItem(request) {
-    if (this.projectId !== void 0 && !_ObjectStackProtocolImplementation.isOverlayAllowed(request.type)) {
+    if (this.environmentId !== void 0 && !_ObjectStackProtocolImplementation.isOverlayAllowed(request.type)) {
       const err = new Error(
         `[not_overridable] Metadata type '${request.type}' has not opted into per-org overlay writes. See docs/adr/0005-metadata-customization-overlay.md.`
       );
@@ -2706,7 +2706,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           actor: request.actor ?? "system",
           source: "protocol.deleteMetaItem"
         });
-        if (this.projectId === void 0) {
+        if (this.environmentId === void 0) {
           try {
             const services = this.getServicesRegistry?.();
             const metadataService = services?.get("metadata");
@@ -2756,7 +2756,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         };
       }
       await this.engine.delete("sys_metadata", { where: { id: existing.id } });
-      if (this.projectId === void 0) {
+      if (this.environmentId === void 0) {
         try {
           const services = this.getServicesRegistry?.();
           const metadataService = services?.get("metadata");
@@ -2787,7 +2787,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    *
    * Per ADR-0005, project-kernel mode ALSO hydrates from sys_metadata —
    * customization overlay rows must survive restart. Scope filter
-   * (`project_id = this.projectId ?? null`) keeps tenants isolated.
+   * (`environment_id = this.environmentId ?? null`) keeps tenants isolated.
    */
   async loadMetaFromDb() {
     let loaded = 0;
@@ -3759,7 +3759,7 @@ var _ObjectQL = class _ObjectQL {
     // Per-engine SchemaRegistry instance.
     //
     // Historically SchemaRegistry was a process-wide singleton of static state,
-    // which broke multi-project servers: a project kernel would inherit every
+    // which broke multi-environment servers: a project kernel would inherit every
     // object registered by the control plane (e.g. sys_metadata), and
     // getDriver()'s owner lookup would route CRUD to the wrong database. Each
     // engine now owns its registry so kernels are fully isolated.
@@ -3790,7 +3790,7 @@ var _ObjectQL = class _ObjectQL {
    * Expose the SchemaRegistry for plugins to register metadata.
    *
    * Returns the per-engine instance, NOT the class. Each ObjectQL engine
-   * owns its registry so multi-project kernels remain isolated.
+   * owns its registry so multi-environment kernels remain isolated.
    */
   get registry() {
     return this._registry;
@@ -5576,7 +5576,7 @@ var ObjectQLPlugin = class {
         this.ql,
         () => ctx.getServices ? ctx.getServices() : /* @__PURE__ */ new Map(),
         void 0,
-        this.projectId
+        this.environmentId
       );
       ctx.registerService("protocol", protocolShim);
       ctx.logger.info("Protocol service registered");
@@ -5638,7 +5638,7 @@ var ObjectQLPlugin = class {
       } else {
         await this.syncRegisteredSchemas(ctx);
       }
-      if (this.projectId === void 0) {
+      if (this.environmentId === void 0) {
         await this.restoreMetadataFromDb(ctx);
       } else {
         ctx.logger.info("Project kernel \u2014 skipping sys_metadata hydration (metadata sourced from artifact)");
@@ -5646,7 +5646,7 @@ var ObjectQLPlugin = class {
       if (!this.skipSchemaSync) {
         await this.syncRegisteredSchemas(ctx);
       }
-      if (this.projectId === void 0) {
+      if (this.environmentId === void 0) {
         await this.bridgeObjectsToMetadataService(ctx);
       }
       this.registerAuditHooks(ctx);
@@ -5675,7 +5675,7 @@ var ObjectQLPlugin = class {
       this.ql = opts.ql;
     }
     this.hostContext = opts.hostContext ?? hostContext;
-    this.projectId = opts.projectId;
+    this.environmentId = opts.environmentId;
     if (typeof opts.startupTimeout === "number" && opts.startupTimeout > 0) {
       this.startupTimeout = opts.startupTimeout;
     }