@objectstack/objectql 9.2.0 → 9.4.0

package/dist/index.d.mts

@@ -98,6 +98,24 @@ interface SchemaRegistryOptions {
      * (useful in tests).
      */
     multiTenant?: boolean;
+    /**
+     * 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 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. 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';
 }
 /**
  * Augment a registered object with implicit system fields.
@@ -132,6 +150,8 @@ declare class SchemaRegistry {
     private _logLevel;
     /** Whether to auto-inject multi-tenant system fields. */
     private readonly multiTenant;
+    /** Cross-package base-layer collision policy (ADR-0048). */
+    private readonly collisionPolicy;
     constructor(options?: SchemaRegistryOptions);
     get logLevel(): RegistryLogLevel;
     set logLevel(level: RegistryLogLevel);
@@ -267,9 +287,55 @@ declare class SchemaRegistry {
      */
     unregisterItem(type: string, name: string): void;
     /**
-     * Universal Get Method
-     */
-    getItem<T>(type: string, name: string): T | undefined;
+     * 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, 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
+     * registered under the bare name SHADOWS the packaged artifact — this
+     * scans the composite (`<packageId>:<name>`) entries first and only
+     * returns an item whose `_packageId` marks a genuine code package
+     * (truthy and not the `'sys_metadata'` rehydration sentinel).
+     *
+     * This is what the protocol's lock/provenance resolution must use:
+     * the artifact's `_lock` envelope always wins over an overlay, and an
+     * overlay row hydrated into the plain key must never be able to mask
+     * 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, 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
+     * metadata reset path (`deleteMetaItem`): deleting the `sys_metadata`
+     * overlay row must also heal the in-memory registry, otherwise the
+     * stale overlay copy keeps shadowing the artifact until restart.
+     *
+     * Deliberately conservative: the plain-key entry is only deleted when a
+     * packaged artifact still exists under a composite key, so the name
+     * stays resolvable afterwards. A runtime-only item (no artifact
+     * backing) is left untouched. Note the plain entry's own `_packageId`
+     * is NOT consulted — the hydration path grafts the artifact envelope
+     * onto the shadow (ADR-0010 §3.3), so a stamped `_packageId` does not
+     * mean the plain entry IS the artifact registration; artifact loaders
+     * always register under a composite key.
+     */
+    removeRuntimeShadow(type: string, name: string): boolean;
     /**
      * Universal List Method
      */
@@ -290,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
@@ -621,6 +687,8 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 method?: "POST" | "PUT" | "DELETE" | "PATCH" | undefined;
                 bodyExtra?: Record<string, unknown> | undefined;
                 mode?: "custom" | "create" | "delete" | "edit" | undefined;
+                opensInNewTab?: boolean | undefined;
+                newTabUrl?: string | undefined;
                 timeout?: number | undefined;
                 aria?: {
                     ariaLabel?: string | undefined;
@@ -1244,6 +1312,26 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * stale schema into the registry.
      */
     private applyObjectRegistryMutation;
+    /**
+     * Heal the in-memory registry after a metadata reset (overlay-row
+     * delete) on control-plane kernels. Two layers:
+     *
+     *  1. Drop the plain-key runtime shadow so the packaged artifact
+     *     (registered under `<packageId>:<name>`) becomes the visible
+     *     value again. The shadow is written by the overlay-hydration
+     *     paths (`getMetaItems` / `loadMetaFromDb`) and — pre-fix —
+     *     survived the reset until restart, leaving stale overlay
+     *     content (and a stripped `_lock` envelope) in every
+     *     registry-direct read (ADR-0010 §3.3).
+     *  2. When no composite-key artifact exists, fall back to the
+     *     MetadataService baseline (FilesystemLoader-sourced types) and
+     *     re-register it, preserving the historical refresh behaviour
+     *     for items the SchemaRegistry never held as artifacts.
+     *
+     * Best-effort: a failure must never block the delete that already
+     * succeeded; the next full reload fixes the registry anyway.
+     */
+    private restoreArtifactRegistryView;
     /**
      * Ensure a just-PUBLISHED object's physical table exists so it is usable
      * for data CRUD immediately — without a server restart. Registering the
@@ -1748,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).
@@ -2894,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)
      */
@@ -2974,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;
@@ -2989,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

@@ -98,6 +98,24 @@ interface SchemaRegistryOptions {
      * (useful in tests).
      */
     multiTenant?: boolean;
+    /**
+     * 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 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. 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';
 }
 /**
  * Augment a registered object with implicit system fields.
@@ -132,6 +150,8 @@ declare class SchemaRegistry {
     private _logLevel;
     /** Whether to auto-inject multi-tenant system fields. */
     private readonly multiTenant;
+    /** Cross-package base-layer collision policy (ADR-0048). */
+    private readonly collisionPolicy;
     constructor(options?: SchemaRegistryOptions);
     get logLevel(): RegistryLogLevel;
     set logLevel(level: RegistryLogLevel);
@@ -267,9 +287,55 @@ declare class SchemaRegistry {
      */
     unregisterItem(type: string, name: string): void;
     /**
-     * Universal Get Method
-     */
-    getItem<T>(type: string, name: string): T | undefined;
+     * 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, 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
+     * registered under the bare name SHADOWS the packaged artifact — this
+     * scans the composite (`<packageId>:<name>`) entries first and only
+     * returns an item whose `_packageId` marks a genuine code package
+     * (truthy and not the `'sys_metadata'` rehydration sentinel).
+     *
+     * This is what the protocol's lock/provenance resolution must use:
+     * the artifact's `_lock` envelope always wins over an overlay, and an
+     * overlay row hydrated into the plain key must never be able to mask
+     * 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, 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
+     * metadata reset path (`deleteMetaItem`): deleting the `sys_metadata`
+     * overlay row must also heal the in-memory registry, otherwise the
+     * stale overlay copy keeps shadowing the artifact until restart.
+     *
+     * Deliberately conservative: the plain-key entry is only deleted when a
+     * packaged artifact still exists under a composite key, so the name
+     * stays resolvable afterwards. A runtime-only item (no artifact
+     * backing) is left untouched. Note the plain entry's own `_packageId`
+     * is NOT consulted — the hydration path grafts the artifact envelope
+     * onto the shadow (ADR-0010 §3.3), so a stamped `_packageId` does not
+     * mean the plain entry IS the artifact registration; artifact loaders
+     * always register under a composite key.
+     */
+    removeRuntimeShadow(type: string, name: string): boolean;
     /**
      * Universal List Method
      */
@@ -290,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
@@ -621,6 +687,8 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 method?: "POST" | "PUT" | "DELETE" | "PATCH" | undefined;
                 bodyExtra?: Record<string, unknown> | undefined;
                 mode?: "custom" | "create" | "delete" | "edit" | undefined;
+                opensInNewTab?: boolean | undefined;
+                newTabUrl?: string | undefined;
                 timeout?: number | undefined;
                 aria?: {
                     ariaLabel?: string | undefined;
@@ -1244,6 +1312,26 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      * stale schema into the registry.
      */
     private applyObjectRegistryMutation;
+    /**
+     * Heal the in-memory registry after a metadata reset (overlay-row
+     * delete) on control-plane kernels. Two layers:
+     *
+     *  1. Drop the plain-key runtime shadow so the packaged artifact
+     *     (registered under `<packageId>:<name>`) becomes the visible
+     *     value again. The shadow is written by the overlay-hydration
+     *     paths (`getMetaItems` / `loadMetaFromDb`) and — pre-fix —
+     *     survived the reset until restart, leaving stale overlay
+     *     content (and a stripped `_lock` envelope) in every
+     *     registry-direct read (ADR-0010 §3.3).
+     *  2. When no composite-key artifact exists, fall back to the
+     *     MetadataService baseline (FilesystemLoader-sourced types) and
+     *     re-register it, preserving the historical refresh behaviour
+     *     for items the SchemaRegistry never held as artifacts.
+     *
+     * Best-effort: a failure must never block the delete that already
+     * succeeded; the next full reload fixes the registry anyway.
+     */
+    private restoreArtifactRegistryView;
     /**
      * Ensure a just-PUBLISHED object's physical table exists so it is usable
      * for data CRUD immediately — without a server restart. Registering the
@@ -1748,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).
@@ -2894,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)
      */
@@ -2974,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;
@@ -2989,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>);