@objectstack/objectql 9.2.0 → 9.3.0

package/dist/index.d.mts

@@ -98,6 +98,22 @@ interface SchemaRegistryOptions {
      * (useful in tests).
      */
     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)`.
+     *
+     * - `'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.
+     *
+     * 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.
+     */
+    collisionPolicy?: 'error' | 'warn';
 }
 /**
  * Augment a registered object with implicit system fields.
@@ -132,6 +148,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);
@@ -258,6 +276,15 @@ 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
      */
@@ -270,6 +297,38 @@ declare class SchemaRegistry {
      * Universal Get Method
      */
     getItem<T>(type: string, name: 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): 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
      */
@@ -621,6 +680,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 +1305,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

package/dist/index.d.ts

@@ -98,6 +98,22 @@ interface SchemaRegistryOptions {
      * (useful in tests).
      */
     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)`.
+     *
+     * - `'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.
+     *
+     * 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.
+     */
+    collisionPolicy?: 'error' | 'warn';
 }
 /**
  * Augment a registered object with implicit system fields.
@@ -132,6 +148,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);
@@ -258,6 +276,15 @@ 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
      */
@@ -270,6 +297,38 @@ declare class SchemaRegistry {
      * Universal Get Method
      */
     getItem<T>(type: string, name: 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): 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
      */
@@ -621,6 +680,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 +1305,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