@objectstack/objectql 9.3.0 → 9.4.0

package/dist/index.d.mts

@@ -99,19 +99,21 @@ interface SchemaRegistryOptions {
      */
     multiTenant?: boolean;
     /**
-     * Policy for cross-package base-layer metadata collisions (ADR-0048) — two
-     * different code packages registering a bare-named generic item under the
-     * same `(type, name)`.
+     * Policy for the install-time namespace gate (ADR-0048 Phase 1) — installing
+     * a package whose `manifest.namespace` is already owned by a *different*
+     * installed package.
      *
-     * - `'error'` (default): throw {@link MetadataCollisionError} at registration
-     *   time, naming both packages and the type/name. Makes the otherwise-silent
-     *   last-write-wins shadowing a loud, actionable failure.
-     * - `'warn'`: log a warning and let the registration proceed. For deliberate
-     *   migrations where a collision is temporarily expected.
+     * - `'error'` (default): throw {@link NamespaceConflictError} at install time,
+     *   naming both packages. Makes the namespace land-grab a loud, early failure
+     *   instead of a mid-install `CREATE TABLE` blow-up.
+     * - `'warn'`: log a warning and let the install proceed. For deliberate
+     *   migrations where the conflict is temporarily expected.
      *
      * Sourced from `OS_METADATA_COLLISION` (`warn` to downgrade) when not set
-     * explicitly. Legitimate runtime/DB overlays and same-package reloads are
-     * never treated as collisions regardless of this setting.
+     * explicitly. Same-package reinstall and shareable platform namespaces
+     * (`base`/`system`/`sys`) are never treated as conflicts. (The per-item
+     * cross-package collision throw was retired in ADR-0048 §3.4 — distinct
+     * package ids are always disambiguable by package-scoped resolution.)
      */
     collisionPolicy?: 'error' | 'warn';
 }
@@ -276,15 +278,6 @@ declare class SchemaRegistry {
      * Universal Register Method for non-object metadata.
      */
     registerItem<T>(type: string, item: T, keyField?: keyof T, packageId?: string): void;
-    /**
-     * Find a code package OTHER than `incoming` that already owns `baseName` in
-     * `collection` (ADR-0048 cross-package collision detection). Scans the live
-     * collection — like {@link getItem} / {@link unregisterItem} — so it always
-     * reflects current state with no parallel index to drift across
-     * reset/unregister. Returns the conflicting owner's package id, or undefined
-     * when the name is free or only held by the same package / a runtime overlay.
-     */
-    private findOtherPackageOwner;
     /**
      * Validate Metadata against Spec Zod Schemas
      */
@@ -294,9 +287,23 @@ declare class SchemaRegistry {
      */
     unregisterItem(type: string, name: string): void;
     /**
-     * Universal Get Method
+     * Universal Get Method.
+     *
+     * ADR-0048 §3.3 — *package-scoped* resolution. When `currentPackageId` is
+     * given (the package the caller is resolving within — known from the route /
+     * `activeApp._packageId`), a bare name resolves to *that package's* item
+     * before any cross-package fallback, so two packages shipping e.g.
+     * `page/home` no longer resolve by registration order (first-match-wins).
+     * Because package ids are globally unique this is unambiguous. Omitting
+     * `currentPackageId` preserves the legacy resolution exactly (backward
+     * compatible) and is best-effort: it returns the first match.
+     *
+     * Precedence (highest first):
+     *   1. bare-key runtime/DB overlay (ADR-0005 sanctioned override) — unchanged
+     *   2. the `currentPackageId` composite entry (prefer-local)
+     *   3. first composite match (legacy first-registered-wins fallback)
      */
-    getItem<T>(type: string, name: string): T | undefined;
+    getItem<T>(type: string, name: string, currentPackageId?: string): T | undefined;
     /**
      * Artifact-only lookup (ADR-0010 §3.3). Unlike {@link getItem} — which
      * returns the plain-key entry first, so a runtime/DB-rehydrated row
@@ -311,7 +318,7 @@ declare class SchemaRegistry {
      * it (that masking is exactly the "registry pollution" bug where a
      * locked app's `_lock` read back as undefined after a PUT+GET).
      */
-    getArtifactItem<T>(type: string, name: string): T | undefined;
+    getArtifactItem<T>(type: string, name: string, currentPackageId?: string): T | undefined;
     /**
      * Remove a plain-key runtime shadow so the packaged artifact registered
      * under a composite key becomes the visible value again. Used by the
@@ -349,7 +356,7 @@ declare class SchemaRegistry {
     enablePackage(id: string): InstalledPackage | undefined;
     disablePackage(id: string): InstalledPackage | undefined;
     registerApp(app: any, packageId?: string): void;
-    getApp(name: string): any;
+    getApp(name: string, currentPackageId?: string): any;
     getAllApps(): any[];
     /**
      * Register a navigation contribution — a package injecting nav items into
@@ -1829,6 +1836,7 @@ declare class SysMetadataRepository implements MetadataRepository {
      */
     get(ref: MetaRef, opts?: {
         state?: OverlayState;
+        packageId?: string | null;
     }): Promise<MetadataItem | null>;
     /**
      * Resolve a historical version by content hash (ADR-0009).
@@ -2975,9 +2983,15 @@ declare class MetadataFacade {
      */
     register(type: string, name: string, data: any): Promise<void>;
     /**
-     * Get a metadata item by type and name
+     * Get a metadata item by type and name.
+     *
+     * `currentPackageId` (ADR-0048) opts into package-scoped resolution: when two
+     * installed packages ship an item of the same `type`/`name`, the registry
+     * prefers the one owned by `currentPackageId` (composite key
+     * `${packageId}:${name}`) before falling back to first-match. Omit it for the
+     * legacy context-free lookup.
      */
-    get(type: string, name: string): Promise<any>;
+    get(type: string, name: string, currentPackageId?: string): Promise<any>;
     /**
      * Get the raw entry (with metadata wrapper)
      */
@@ -3055,6 +3069,28 @@ interface ObjectQLPluginOptions {
      * code change.
      */
     skipSchemaSync?: boolean;
+    /**
+     * Hydrate the SchemaRegistry from this kernel's local `sys_metadata`
+     * even when `environmentId` is set.
+     *
+     * By default Phase-2 hydration in `start()` is gated on
+     * `environmentId === undefined`, because the original multi-environment
+     * model assumed project kernels source metadata from a remote artifact /
+     * control-plane proxy and have NO local `sys_metadata` to read. That is
+     * NOT true for an isolated, proxy-free project kernel that persists its
+     * OWN `sys_metadata` locally (e.g. the cloud single-env tenant runtime on
+     * Turso): objects CREATED AT RUNTIME there — not present in the boot
+     * artifact manifest — would otherwise never re-enter the registry after a
+     * restart, so `registry.getObject(name)` returns nothing for them and any
+     * registry consumer (the unknown-`$select` guard, hooks, relationships)
+     * silently degrades.
+     *
+     * Set this ONLY when the kernel's registry is per-instance isolated AND
+     * `sys_metadata` lives on the kernel's own local driver (no control-plane
+     * proxy) — hydrating a proxied kernel would read the wrong database.
+     * Safe to leave unset: hydration tolerates a missing table.
+     */
+    hydrateMetadataFromDb?: boolean;
 }
 declare class ObjectQLPlugin implements Plugin {
     name: string;
@@ -3070,6 +3106,7 @@ declare class ObjectQLPlugin implements Plugin {
     private hostContext?;
     private environmentId?;
     private skipSchemaSync;
+    private hydrateMetadataFromDb;
     /** Unsubscribe handles for metadata-event subscriptions (ADR-0008 PR-7). */
     private metadataUnsubscribes;
     constructor(qlOrOptions?: ObjectQL | ObjectQLPluginOptions, hostContext?: Record<string, any>);

package/dist/index.d.ts

@@ -99,19 +99,21 @@ interface SchemaRegistryOptions {
      */
     multiTenant?: boolean;
     /**
-     * Policy for cross-package base-layer metadata collisions (ADR-0048) — two
-     * different code packages registering a bare-named generic item under the
-     * same `(type, name)`.
+     * Policy for the install-time namespace gate (ADR-0048 Phase 1) — installing
+     * a package whose `manifest.namespace` is already owned by a *different*
+     * installed package.
      *
-     * - `'error'` (default): throw {@link MetadataCollisionError} at registration
-     *   time, naming both packages and the type/name. Makes the otherwise-silent
-     *   last-write-wins shadowing a loud, actionable failure.
-     * - `'warn'`: log a warning and let the registration proceed. For deliberate
-     *   migrations where a collision is temporarily expected.
+     * - `'error'` (default): throw {@link NamespaceConflictError} at install time,
+     *   naming both packages. Makes the namespace land-grab a loud, early failure
+     *   instead of a mid-install `CREATE TABLE` blow-up.
+     * - `'warn'`: log a warning and let the install proceed. For deliberate
+     *   migrations where the conflict is temporarily expected.
      *
      * Sourced from `OS_METADATA_COLLISION` (`warn` to downgrade) when not set
-     * explicitly. Legitimate runtime/DB overlays and same-package reloads are
-     * never treated as collisions regardless of this setting.
+     * explicitly. Same-package reinstall and shareable platform namespaces
+     * (`base`/`system`/`sys`) are never treated as conflicts. (The per-item
+     * cross-package collision throw was retired in ADR-0048 §3.4 — distinct
+     * package ids are always disambiguable by package-scoped resolution.)
      */
     collisionPolicy?: 'error' | 'warn';
 }
@@ -276,15 +278,6 @@ declare class SchemaRegistry {
      * Universal Register Method for non-object metadata.
      */
     registerItem<T>(type: string, item: T, keyField?: keyof T, packageId?: string): void;
-    /**
-     * Find a code package OTHER than `incoming` that already owns `baseName` in
-     * `collection` (ADR-0048 cross-package collision detection). Scans the live
-     * collection — like {@link getItem} / {@link unregisterItem} — so it always
-     * reflects current state with no parallel index to drift across
-     * reset/unregister. Returns the conflicting owner's package id, or undefined
-     * when the name is free or only held by the same package / a runtime overlay.
-     */
-    private findOtherPackageOwner;
     /**
      * Validate Metadata against Spec Zod Schemas
      */
@@ -294,9 +287,23 @@ declare class SchemaRegistry {
      */
     unregisterItem(type: string, name: string): void;
     /**
-     * Universal Get Method
+     * Universal Get Method.
+     *
+     * ADR-0048 §3.3 — *package-scoped* resolution. When `currentPackageId` is
+     * given (the package the caller is resolving within — known from the route /
+     * `activeApp._packageId`), a bare name resolves to *that package's* item
+     * before any cross-package fallback, so two packages shipping e.g.
+     * `page/home` no longer resolve by registration order (first-match-wins).
+     * Because package ids are globally unique this is unambiguous. Omitting
+     * `currentPackageId` preserves the legacy resolution exactly (backward
+     * compatible) and is best-effort: it returns the first match.
+     *
+     * Precedence (highest first):
+     *   1. bare-key runtime/DB overlay (ADR-0005 sanctioned override) — unchanged
+     *   2. the `currentPackageId` composite entry (prefer-local)
+     *   3. first composite match (legacy first-registered-wins fallback)
      */
-    getItem<T>(type: string, name: string): T | undefined;
+    getItem<T>(type: string, name: string, currentPackageId?: string): T | undefined;
     /**
      * Artifact-only lookup (ADR-0010 §3.3). Unlike {@link getItem} — which
      * returns the plain-key entry first, so a runtime/DB-rehydrated row
@@ -311,7 +318,7 @@ declare class SchemaRegistry {
      * it (that masking is exactly the "registry pollution" bug where a
      * locked app's `_lock` read back as undefined after a PUT+GET).
      */
-    getArtifactItem<T>(type: string, name: string): T | undefined;
+    getArtifactItem<T>(type: string, name: string, currentPackageId?: string): T | undefined;
     /**
      * Remove a plain-key runtime shadow so the packaged artifact registered
      * under a composite key becomes the visible value again. Used by the
@@ -349,7 +356,7 @@ declare class SchemaRegistry {
     enablePackage(id: string): InstalledPackage | undefined;
     disablePackage(id: string): InstalledPackage | undefined;
     registerApp(app: any, packageId?: string): void;
-    getApp(name: string): any;
+    getApp(name: string, currentPackageId?: string): any;
     getAllApps(): any[];
     /**
      * Register a navigation contribution — a package injecting nav items into
@@ -1829,6 +1836,7 @@ declare class SysMetadataRepository implements MetadataRepository {
      */
     get(ref: MetaRef, opts?: {
         state?: OverlayState;
+        packageId?: string | null;
     }): Promise<MetadataItem | null>;
     /**
      * Resolve a historical version by content hash (ADR-0009).
@@ -2975,9 +2983,15 @@ declare class MetadataFacade {
      */
     register(type: string, name: string, data: any): Promise<void>;
     /**
-     * Get a metadata item by type and name
+     * Get a metadata item by type and name.
+     *
+     * `currentPackageId` (ADR-0048) opts into package-scoped resolution: when two
+     * installed packages ship an item of the same `type`/`name`, the registry
+     * prefers the one owned by `currentPackageId` (composite key
+     * `${packageId}:${name}`) before falling back to first-match. Omit it for the
+     * legacy context-free lookup.
      */
-    get(type: string, name: string): Promise<any>;
+    get(type: string, name: string, currentPackageId?: string): Promise<any>;
     /**
      * Get the raw entry (with metadata wrapper)
      */
@@ -3055,6 +3069,28 @@ interface ObjectQLPluginOptions {
      * code change.
      */
     skipSchemaSync?: boolean;
+    /**
+     * Hydrate the SchemaRegistry from this kernel's local `sys_metadata`
+     * even when `environmentId` is set.
+     *
+     * By default Phase-2 hydration in `start()` is gated on
+     * `environmentId === undefined`, because the original multi-environment
+     * model assumed project kernels source metadata from a remote artifact /
+     * control-plane proxy and have NO local `sys_metadata` to read. That is
+     * NOT true for an isolated, proxy-free project kernel that persists its
+     * OWN `sys_metadata` locally (e.g. the cloud single-env tenant runtime on
+     * Turso): objects CREATED AT RUNTIME there — not present in the boot
+     * artifact manifest — would otherwise never re-enter the registry after a
+     * restart, so `registry.getObject(name)` returns nothing for them and any
+     * registry consumer (the unknown-`$select` guard, hooks, relationships)
+     * silently degrades.
+     *
+     * Set this ONLY when the kernel's registry is per-instance isolated AND
+     * `sys_metadata` lives on the kernel's own local driver (no control-plane
+     * proxy) — hydrating a proxied kernel would read the wrong database.
+     * Safe to leave unset: hydration tolerates a missing table.
+     */
+    hydrateMetadataFromDb?: boolean;
 }
 declare class ObjectQLPlugin implements Plugin {
     name: string;
@@ -3070,6 +3106,7 @@ declare class ObjectQLPlugin implements Plugin {
     private hostContext?;
     private environmentId?;
     private skipSchemaSync;
+    private hydrateMetadataFromDb;
     /** Unsubscribe handles for metadata-event subscriptions (ADR-0008 PR-7). */
     private metadataUnsubscribes;
     constructor(qlOrOptions?: ObjectQL | ObjectQLPluginOptions, hostContext?: Record<string, any>);