feat(objectql): ADR-0048 Phase 1+2 — namespace install gate + prefer-local resolution

Phase 1 — install-time namespace gate. `SchemaRegistry.installPackage` refuses
a package whose `manifest.namespace` is already owned by a DIFFERENT installed
package (new `NamespaceConflictError`), making explicit and early the constraint
the object/table layer already enforces implicitly (a duplicate
`CREATE TABLE <ns>_<obj>` fails at the DB). Same-package reinstall and shareable
platform namespaces (base/system/sys) are exempt; OS_METADATA_COLLISION=warn
downgrades to a warning.

Phase 2 — prefer-local (container-scoped) resolution. `getItem(type, name, ns?)`
resolves a bare name to the item owned by `ns`'s package before any
cross-package fallback, preserving ADR-0005 overlay precedence and remaining
backward compatible (param optional). `getApp` resolves prefer-local against its
own name (app.name ≡ namespace in v1). The per-item collision guard now narrows
to the cases prefer-local CANNOT disambiguate (shared/missing namespace), so two
DIFFERENT-namespace packages legitimately coexist on the same bare name — the
marketplace coexistence the revised ADR-0048 targets. Every existing collision
test still passes (namespace-less fixtures remain a hard error).

Tests: registry-namespace-install-gate.test.ts (7), registry-prefer-local-
resolution.test.ts (7). Full objectql suite green (600).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

packages/objectql/src/registry-namespace-install-gate.test.ts

@@ -0,0 +1,101 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * ADR-0048 Phase 1 — install-time namespace gate.
+ *
+ * A package's `manifest.namespace` is the mandatory object-name prefix and the
+ * container that scopes its UI metadata, so it must be unique per installation.
+ * `installPackage` refuses a package whose namespace is already owned by a
+ * *different* installed package. Same-package reinstall and shareable platform
+ * namespaces (`base`/`system`/`sys`) pass through; `OS_METADATA_COLLISION=warn`
+ * downgrades the refusal to a warning.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SchemaRegistry, NamespaceConflictError } from './registry';
+
+const manifest = (id: string, namespace: string) => ({
+  id,
+  name: id,
+  namespace,
+  version: '1.0.0',
+});
+
+describe('SchemaRegistry — namespace install gate (ADR-0048 Phase 1)', () => {
+  let registry: SchemaRegistry;
+
+  beforeEach(() => {
+    registry = new SchemaRegistry({ multiTenant: false, collisionPolicy: 'error' });
+    registry.logLevel = 'silent';
+  });
+
+  it('refuses a package whose namespace is already owned by a different package', () => {
+    registry.installPackage(manifest('com.acme.crm', 'crm') as any);
+    expect(() =>
+      registry.installPackage(manifest('com.beta.crm', 'crm') as any),
+    ).toThrowError(NamespaceConflictError);
+  });
+
+  it('error names both packages and the namespace', () => {
+    registry.installPackage(manifest('com.acme.crm', 'crm') as any);
+    try {
+      registry.installPackage(manifest('com.beta.crm', 'crm') as any);
+      throw new Error('expected a namespace conflict error');
+    } catch (e) {
+      expect(e).toBeInstanceOf(NamespaceConflictError);
+      const err = e as NamespaceConflictError;
+      expect(err.namespace).toBe('crm');
+      expect(err.existingPackageId).toBe('com.acme.crm');
+      expect(err.incomingPackageId).toBe('com.beta.crm');
+      expect(err.message).toContain('com.acme.crm');
+      expect(err.message).toContain('com.beta.crm');
+      expect(err.message).toContain('crm');
+    }
+    // The conflicting package must NOT have been recorded.
+    expect(registry.getPackage('com.beta.crm')).toBeUndefined();
+    expect(registry.getNamespaceOwners('crm')).toEqual(['com.acme.crm']);
+  });
+
+  it('allows the same package to reinstall/reload its own namespace', () => {
+    registry.installPackage(manifest('com.acme.crm', 'crm') as any);
+    expect(() =>
+      registry.installPackage(manifest('com.acme.crm', 'crm') as any),
+    ).not.toThrow();
+  });
+
+  it('allows two packages with distinct namespaces', () => {
+    registry.installPackage(manifest('com.acme.crm', 'crm') as any);
+    expect(() =>
+      registry.installPackage(manifest('com.acme.hr', 'hr') as any),
+    ).not.toThrow();
+  });
+
+  it('exempts shareable platform namespaces (base/system/sys)', () => {
+    for (const ns of ['base', 'system', 'sys']) {
+      registry.installPackage(manifest(`com.a.${ns}`, ns) as any);
+      expect(() =>
+        registry.installPackage(manifest(`com.b.${ns}`, ns) as any),
+      ).not.toThrow();
+    }
+  });
+
+  it('downgrades to a warning under collisionPolicy "warn"', () => {
+    const warnReg = new SchemaRegistry({ multiTenant: false, collisionPolicy: 'warn' });
+    warnReg.logLevel = 'silent';
+    warnReg.installPackage(manifest('com.acme.crm', 'crm') as any);
+    expect(() =>
+      warnReg.installPackage(manifest('com.beta.crm', 'crm') as any),
+    ).not.toThrow();
+    // Both packages are recorded; the namespace now has two owners.
+    expect(warnReg.getNamespaceOwners('crm').sort()).toEqual(['com.acme.crm', 'com.beta.crm']);
+  });
+
+  it('releases the namespace on uninstall, allowing a different package to claim it', () => {
+    registry.installPackage(manifest('com.acme.crm', 'crm') as any);
+    registry.uninstallPackage('com.acme.crm');
+    expect(() =>
+      registry.installPackage(manifest('com.beta.crm', 'crm') as any),
+    ).not.toThrow();
+    expect(registry.getNamespaceOwners('crm')).toEqual(['com.beta.crm']);
+  });
+});

packages/objectql/src/registry-prefer-local-resolution.test.ts

@@ -0,0 +1,79 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * ADR-0048 Phase 2 — prefer-local (container-scoped) resolution.
+ *
+ * With the install-time namespace gate (Phase 1) keeping namespaces distinct,
+ * two packages may legitimately ship the same bare name (e.g. `page/home`).
+ * They no longer collide at registration; instead `getItem(type, name, ns)`
+ * routes each caller to the item owned by its own namespace's package. The
+ * per-item collision guard now fires only where prefer-local CANNOT
+ * disambiguate (shared / missing namespace).
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SchemaRegistry } from './registry';
+
+const install = (reg: SchemaRegistry, id: string, namespace: string) =>
+  reg.installPackage({ id, name: id, namespace, version: '1.0.0' } as any);
+
+describe('SchemaRegistry — prefer-local resolution (ADR-0048 Phase 2)', () => {
+  let registry: SchemaRegistry;
+
+  beforeEach(() => {
+    registry = new SchemaRegistry({ multiTenant: false, collisionPolicy: 'error' });
+    registry.logLevel = 'silent';
+    install(registry, 'com.acme.crm', 'crm');
+    install(registry, 'com.acme.hr', 'hr');
+  });
+
+  it('lets two distinct-namespace packages coexist on the same bare name', () => {
+    registry.registerItem('page', { name: 'home', title: 'CRM Home' }, 'name', 'com.acme.crm');
+    expect(() =>
+      registry.registerItem('page', { name: 'home', title: 'HR Home' }, 'name', 'com.acme.hr'),
+    ).not.toThrow();
+  });
+
+  it('resolves prefer-local to the namespace owner', () => {
+    registry.registerItem('page', { name: 'home', title: 'CRM Home' }, 'name', 'com.acme.crm');
+    registry.registerItem('page', { name: 'home', title: 'HR Home' }, 'name', 'com.acme.hr');
+
+    expect(registry.getItem<any>('page', 'home', 'crm')?.title).toBe('CRM Home');
+    expect(registry.getItem<any>('page', 'home', 'hr')?.title).toBe('HR Home');
+  });
+
+  it('context-free getItem still returns one of the entries (legacy first-match fallback)', () => {
+    registry.registerItem('page', { name: 'home', title: 'CRM Home' }, 'name', 'com.acme.crm');
+    registry.registerItem('page', { name: 'home', title: 'HR Home' }, 'name', 'com.acme.hr');
+
+    const got = registry.getItem<any>('page', 'home');
+    expect(['CRM Home', 'HR Home']).toContain(got?.title);
+  });
+
+  it('keeps runtime/DB overlay (bare key) precedence over prefer-local (ADR-0005)', () => {
+    registry.registerItem('page', { name: 'home', title: 'CRM Home' }, 'name', 'com.acme.crm');
+    // Runtime-authored overlay under the bare key (no package provenance).
+    registry.registerItem('page', { name: 'home', title: 'overlay' }, 'name');
+
+    expect(registry.getItem<any>('page', 'home', 'crm')?.title).toBe('overlay');
+  });
+
+  it('falls back to first-match when the namespace owns no such item', () => {
+    registry.registerItem('page', { name: 'home', title: 'CRM Home' }, 'name', 'com.acme.crm');
+    // hr has no `home`; asking within hr's container falls back to the only entry.
+    expect(registry.getItem<any>('page', 'home', 'hr')?.title).toBe('CRM Home');
+  });
+
+  it('still fails loudly when two packages SHARE a namespace (unresolvable)', () => {
+    const reg = new SchemaRegistry({ multiTenant: false, collisionPolicy: 'error' });
+    reg.logLevel = 'silent';
+    // `sys` is a shareable platform namespace, exempt from the install gate, so
+    // two packages CAN both own it — but then a same-named item is ambiguous.
+    install(reg, 'com.a.sys', 'sys');
+    install(reg, 'com.b.sys', 'sys');
+    reg.registerItem('flow', { name: 'cleanup' }, 'name', 'com.a.sys');
+    expect(() =>
+      reg.registerItem('flow', { name: 'cleanup' }, 'name', 'com.b.sys'),
+    ).toThrow();
+  });
+});

packages/objectql/src/registry.ts

@@ -317,6 +317,17 @@ function isRealPackage(pkg: unknown): pkg is string {
   return typeof pkg === 'string' && pkg.length > 0 && pkg !== SYS_METADATA_OWNER;
 }
 
+/**
+ * Platform namespaces that multiple packages may legitimately share, so the
+ * install-time namespace-uniqueness gate (ADR-0048 Phase 1) must never fire on
+ * them: the FQN-exempt reserved namespaces (`base`, `system`) plus `sys`
+ * (system objects such as `sys_metadata` are contributed by many packages — see
+ * {@link SchemaRegistry.registerNamespace}, which is intentionally many-to-one).
+ */
+function isShareableNamespace(ns: string): boolean {
+  return RESERVED_NAMESPACES.has(ns) || ns === 'sys';
+}
+
 /**
  * Raised when two **different** code packages register a generic (non-object)
  * metadata item under the same `(type, name)` in the code-defined base layer
@@ -357,6 +368,43 @@ export class MetadataCollisionError extends Error {
   }
 }
 
+/**
+ * Raised when a package is installed whose `manifest.namespace` is already owned
+ * by a **different** installed package in this installation (ADR-0048 Phase 1).
+ *
+ * The namespace is the mandatory object-name prefix (`${namespace}_${shortName}`)
+ * and — once installed — the container that scopes a package's UI/automation
+ * metadata. Two packages sharing a namespace would collide at the object/table
+ * layer (a duplicate `CREATE TABLE crm_account` already fails loudly at the DB)
+ * and would make container-scoped resolution ambiguous. This gate refuses the
+ * install up front with an actionable error, instead of letting a half-applied
+ * install blow up later at table creation. Shareable platform namespaces
+ * (`base`/`system`/`sys`) are exempt.
+ */
+export class NamespaceConflictError extends Error {
+  readonly namespace: string;
+  readonly existingPackageId: string;
+  readonly incomingPackageId: string;
+
+  constructor(namespace: string, existingPackageId: string, incomingPackageId: string) {
+    super(
+      `Namespace conflict: namespace "${namespace}" is already owned by ` +
+        `package "${existingPackageId}", so package "${incomingPackageId}" ` +
+        `cannot be installed alongside it. A namespace is the mandatory prefix ` +
+        `of every object name (e.g. "${namespace}_account") and the container ` +
+        `that scopes a package's UI metadata, so it must be unique per ` +
+        `installation. Choose a different namespace for "${incomingPackageId}", ` +
+        `or uninstall "${existingPackageId}" first. If this is a deliberate ` +
+        `migration, set OS_METADATA_COLLISION=warn to downgrade to a warning. ` +
+        `See ADR-0048.`,
+    );
+    this.name = 'NamespaceConflictError';
+    this.namespace = namespace;
+    this.existingPackageId = existingPackageId;
+    this.incomingPackageId = incomingPackageId;
+  }
+}
+
 export class SchemaRegistry {
   // ==========================================
   // Logging control
@@ -837,7 +885,15 @@ export class SchemaRegistry {
     //     artifact-vs-DB warning below.
     if (isRealPackage(packageId)) {
       const conflictOwner = this.findOtherPackageOwner(collection, baseName, packageId);
-      if (conflictOwner) {
+      if (conflictOwner && !this.isPreferLocalDisambiguable(packageId, conflictOwner)) {
+        // ADR-0048 Phase 2 — the guard now only fires when prefer-local
+        // resolution (see getItem) CANNOT disambiguate the two owners: they
+        // share a namespace (possible only for shareable platform namespaces
+        // like `sys`, which the install gate exempts) or one lacks a namespace
+        // (legacy package with no container to scope by). Two packages in
+        // DIFFERENT namespaces legitimately coexist on the same bare name —
+        // the install-time namespace gate keeps their namespaces distinct and
+        // prefer-local routes each caller to its own container.
         const err = new MetadataCollisionError(type, baseName, conflictOwner, packageId);
         if (this.collisionPolicy === 'warn') {
           console.warn(`[Registry] ${err.message}`);
@@ -894,6 +950,21 @@ export class SchemaRegistry {
     return undefined;
   }
 
+  /**
+   * True when prefer-local resolution ({@link getItem}) can route callers in
+   * each owner's container to the right item — i.e. the two packages declare
+   * **distinct, non-empty namespaces** (ADR-0048 Phase 2). When it returns
+   * false (shared namespace, or a missing namespace on either side) a same
+   * `(type, name)` clash is genuinely unresolvable and the collision guard
+   * fires. Namespaces are read from the installed-package records, which the
+   * install path registers before a package's metadata is loaded.
+   */
+  private isPreferLocalDisambiguable(incoming: string, owner: string): boolean {
+    const incomingNs = this.getPackage(incoming)?.manifest?.namespace;
+    const ownerNs = this.getPackage(owner)?.manifest?.namespace;
+    return !!incomingNs && !!ownerNs && incomingNs !== ownerNs;
+  }
+
   /**
    * Validate Metadata against Spec Zod Schemas
    */
@@ -939,19 +1010,40 @@ export class SchemaRegistry {
   }
 
   /**
-   * Universal Get Method
+   * Universal Get Method.
+   *
+   * ADR-0048 Phase 2 — *prefer-local* resolution. When `currentNamespace` is
+   * given (the container the caller is resolving within), a bare name resolves
+   * to the item owned by *that namespace's* package before any cross-package
+   * fallback, so two packages shipping e.g. `page/home` no longer resolve by
+   * registration order (first-match-wins). Omitting `currentNamespace`
+   * preserves the legacy resolution exactly, so this is backward compatible.
+   *
+   * Precedence (highest first):
+   *   1. bare-key runtime/DB overlay (ADR-0005 sanctioned override) — unchanged
+   *   2. the `currentNamespace` owner's 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, currentNamespace?: string): T | undefined {
     // Special handling for 'object' and 'objects' types - use objectContributors
     if (type === 'object' || type === 'objects') {
       return this.getObject(name) as unknown as T | undefined;
     }
-    
+
     const collection = this.metadata.get(type);
     if (!collection) return undefined;
     const direct = collection.get(name);
     if (direct) return direct as T;
-    // Scan for composite keys
+
+    // Prefer-local: resolve within the caller's container (namespace) first.
+    if (currentNamespace) {
+      for (const owner of this.getNamespaceOwners(currentNamespace)) {
+        const local = collection.get(`${owner}:${name}`);
+        if (local) return local as T;
+      }
+    }
+
+    // Fallback: first composite key matching the bare name (legacy behaviour).
     for (const [key, item] of collection) {
       if (key.endsWith(`:${name}`)) {
         return item as T;
@@ -1080,6 +1172,30 @@ export class SchemaRegistry {
   // ==========================================
 
   installPackage(manifest: ObjectStackManifest, settings?: Record<string, any>): InstalledPackage {
+    // ADR-0048 Phase 1 — install-time namespace gate. Refuse a package whose
+    // namespace is already owned by a *different* installed package; this is
+    // the constraint the object/table layer enforces implicitly (a duplicate
+    // `CREATE TABLE <ns>_<obj>` fails at the DB), made explicit and early.
+    // Same-package reinstall/reload is excluded (owner === manifest.id), and
+    // shareable platform namespaces (base/system/sys) are exempt.
+    if (manifest.namespace && !isShareableNamespace(manifest.namespace)) {
+      const conflictOwner = this.getNamespaceOwners(manifest.namespace).find(
+        (owner) => owner !== manifest.id,
+      );
+      if (conflictOwner) {
+        if (this.collisionPolicy === 'warn') {
+          console.warn(
+            `[Registry] Namespace conflict (downgraded to warning via ` +
+              `OS_METADATA_COLLISION=warn): namespace "${manifest.namespace}" is ` +
+              `already owned by "${conflictOwner}"; installing "${manifest.id}" ` +
+              `anyway. See ADR-0048.`,
+          );
+        } else {
+          throw new NamespaceConflictError(manifest.namespace, conflictOwner, manifest.id);
+        }
+      }
+    }
+
     const now = new Date().toISOString();
     const disabled = this.initialDisabledPackageIds.has(manifest.id);
     const pkg: InstalledPackage = {
@@ -1175,7 +1291,10 @@ export class SchemaRegistry {
   }
 
   getApp(name: string): any {
-    const app = this.getItem('app', name);
+    // ADR-0048 (v1) — one app per package, with `app.name ≡ manifest.namespace`,
+    // so the app name *is* its own container: resolve prefer-local against it so
+    // two packages' apps never resolve by registration order.
+    const app = this.getItem('app', name, name);
     if (!app) return app;
     return this.applyNavContributions(app);
   }