@jini-ai/core 0.4.7 → 0.4.9

package/dist/tool-metadata-types.d.ts

@@ -0,0 +1,26 @@
+/** Domain registrations own these declarations; projections never infer risk or authorization. */
+export interface ToolApprovalMetadata {
+    readonly class: 'read' | 'edit' | 'trash' | 'delete' | 'restore-over-existing' | 'publish' | 'replace-secret' | 'escalation';
+    readonly confirmation: 'direct' | 'policy' | 'plan';
+    readonly input?: 'human-form';
+    /** Host-owned input classification rule, separate from the declared side effects. */
+    readonly rule?: string;
+}
+export interface ToolMetadata<A extends ToolApprovalMetadata = ToolApprovalMetadata> {
+    /** Installed guidance capabilities needed by a writer; independent of permission and risk. */
+    readonly guidanceCapabilities?: readonly string[];
+    readonly search?: {
+        readonly keywords?: string;
+        readonly queries?: readonly string[];
+    };
+    readonly approval?: A;
+    readonly mcpUi?: {
+        readonly redeemable?: boolean;
+        readonly exchangeOnly?: boolean;
+        readonly secretField?: {
+            readonly secret: true;
+        };
+    };
+}
+export type ToolMetadataById<A extends ToolApprovalMetadata = ToolApprovalMetadata> = Readonly<Record<string, ToolMetadata<A>>>;
+//# sourceMappingURL=tool-metadata-types.d.ts.map

package/dist/tool-metadata-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-metadata-types.js.map

package/dist/tool-metadata.d.ts

@@ -1,26 +1,5 @@
-/** Domain registrations own these declarations; projections never infer risk or authorization. */
-export interface ToolApprovalMetadata {
-    readonly class: 'read' | 'edit' | 'trash' | 'delete' | 'restore-over-existing' | 'publish' | 'replace-secret' | 'escalation';
-    readonly confirmation: 'direct' | 'policy' | 'plan';
-    readonly input?: 'human-form';
-    /** Host-owned input classification rule, separate from the declared side effects. */
-    readonly rule?: string;
-}
-export interface ToolMetadata<A extends ToolApprovalMetadata = ToolApprovalMetadata> {
-    readonly search?: {
-        readonly keywords?: string;
-        readonly queries?: readonly string[];
-    };
-    readonly approval?: A;
-    readonly mcpUi?: {
-        readonly redeemable?: boolean;
-        readonly exchangeOnly?: boolean;
-        readonly secretField?: {
-            readonly secret: true;
-        };
-    };
-}
-export type ToolMetadataById<A extends ToolApprovalMetadata = ToolApprovalMetadata> = Readonly<Record<string, ToolMetadata<A>>>;
+import type { ToolApprovalMetadata, ToolMetadata, ToolMetadataById } from './tool-metadata-types.js';
+export type { ToolApprovalMetadata, ToolMetadata, ToolMetadataById } from './tool-metadata-types.js';
 /** Own-property lookup: inherited object keys can never declare a tool's approval or callback access. */
 export declare function toolMetadataFor({ toolId, metadata }: {
     toolId: string;

package/dist/tool-registry.d.ts

@@ -26,7 +26,9 @@
  * `archived provenance ledger` for the 2026-07-29 hardening note.
  */
 import type { Principal } from './principal.js';
-import type { ToolMetadata } from './tool-metadata.js';
+import type { AgentToolSideEffect } from './agent-tools.js';
+import type { ToolMetadata } from './tool-metadata-types.js';
+import { type ToolInputNormalizer } from './tool-input-normalization.js';
 /** A structural run reference — anything with a stable `id` satisfies this (e.g. `@jini-ai/protocol`'s `RunStatus`). No import needed to satisfy it; see the module doc. */
 export interface RunRef {
     readonly id: string;
@@ -42,8 +44,8 @@ export interface ToolDescriptor {
     readonly description?: string;
     /**
      * JSON-Schema-shaped description of this tool's accepted input, carried as `unknown` because the
-     * kernel neither parses nor validates it — a schema dialect is a consumer concern, and taking a
-     * validator dependency here would put one in every package that touches a registry.
+     * gate reads common property/type fields for input normalization but leaves validation and
+     * schema dialects to the handler; no validator dependency belongs in every registry consumer.
      *
      * It exists because *every* discovery mechanism needs it and nothing else in the kernel can
      * supply it: a caller that can enumerate `ToolRegistry.list({})` still cannot tell an agent what
@@ -74,6 +76,8 @@ export interface ToolDescriptor {
      * would admit every unclassified write, which is the exact failure the flag exists to prevent.
      */
     readonly readOnly?: boolean;
+    /** Independently checked domain risk, retained for discovery; never grants permission. */
+    readonly sideEffects?: AgentToolSideEffect;
 }
 /**
  * The single read-only determination: may this tool run through a surface that has promised its
@@ -90,6 +94,17 @@ export interface ToolDescriptor {
 export declare function isReadOnlyTool({ descriptor }: {
     descriptor: ToolDescriptor | undefined;
 }): boolean;
+/** Project registration risk for discovery using the same read-only decision as execution.
+ * Missing classification stays unknown; discovery never grants execution authority.
+ * @returns Explicit readOnly and sideEffects fields for a registry descriptor.
+ * @complexity O(1); no effects.
+ */
+export declare function toolDiscoveryMetadata({ descriptor }: {
+    descriptor: Pick<ToolDescriptor, 'id' | 'readOnly' | 'sideEffects'> | undefined;
+}, _options?: {}): {
+    readOnly: boolean;
+    sideEffects: AgentToolSideEffect | 'unknown';
+};
 /**
  * One human-facing message a handler pushes out mid-call.
  *
@@ -145,27 +160,21 @@ export interface ToolExecutionContext {
 /** Optional handler ports supplied by the invoking transport. */
 export interface ToolExecutionOptions {
     readonly emitSurface?: SurfaceEmitter;
+    /** Invoke through the same executor, retaining this call's principal, run, cancellation and
+     * transport gates. Rejects on denial, failed confirmation, validation or execution failure.
+     * A composition-owned registry may retain a source registration behind a derived catalog card.
+     * Batch wrappers use this port for each final merged input; every supplied registry is gated.
+     */
+    readonly invokeTool?: (required: {
+        toolId: string;
+        input: unknown;
+    }, optional?: {
+        registry?: ToolRegistry;
+    }) => Promise<unknown>;
 }
 /** Runs the tool's actual side effect. Only ever invoked by `ToolExecutor`, never called directly by a route/agent holding the registry. */
 export type ToolHandler = (required: ToolExecutionContext, optional?: ToolExecutionOptions) => Promise<unknown>;
-/**
- * Thrown by a `ToolHandler` (or a validator it calls, e.g. the kernel's `registration-kit.ts`
- * `requireString`/`requireInputRecord`/etc.) to mean "the caller's input was malformed or missing a
- * required field" — a fact about the CALL, not the server. `@jini-ai/daemon`'s `ToolExecutor.execute`
- * tags a handler rejection's `ToolExecutionResult.errorKind` as `'validation'` when the thrown error
- * is `instanceof ToolInputError`, and every HTTP-facing mapping of a `'failed'` execution (today:
- * `@jini-ai/http-kit`'s `delegated-tools.ts`) uses that tag to answer with a 4xx instead of folding
- * it into the same redacted 500 an actual internal/infrastructure failure gets.
- *
- * Deliberately a plain marker with no extra fields: the message itself is already caller-actionable
- * (`withSchemaOnRejection` appends the tool's own input schema to it), so nothing beyond "this IS one
- * of these" needs to survive the `instanceof` check.
- */
-export declare class ToolInputError extends Error {
-    constructor({ message }: {
-        message: string;
-    }, optional?: ErrorOptions);
-}
+export { ToolInputError } from './tool-input-errors.js';
 export type AuthorizationDecision = 'allow' | 'deny';
 export interface ToolAuthorizationContext {
     readonly principal: Principal;
@@ -185,13 +194,18 @@ export interface ToolPolicy {
     authorize(ctx: ToolAuthorizationContext): AuthorizationDecision | Promise<AuthorizationDecision>;
 }
 export interface ToolRegistration {
+    /** Optional execution-only schema, e.g. authenticated form callbacks. Never published by discovery;
+     * the handler must retain callback authentication and authorization. Defaults to descriptor.inputSchema. */
+    readonly invocationSchema?: unknown;
+    /** Domain-owned aliases, read by the single execution gate before validation/authorization. */
+    readonly normalizeInput?: ToolInputNormalizer;
     readonly descriptor: ToolDescriptor;
     readonly handler: ToolHandler;
     readonly policy: ToolPolicy;
 }
 /** The public registration/enumeration surface. See the module doc for why `handler`/`policy` never appear here. */
 export interface ToolRegistry {
-    /** @throws If `registration.descriptor.id` is already registered — re-registration must be explicit (unregister is not exposed; this registry is append-only by design, matching the kernel's "tools are registered once at composition time" model). */
+    /** @throws If the policy has no callable `authorize` or `registration.descriptor.id` is already registered — re-registration must be explicit (unregister is not exposed; this registry is append-only by design, matching the kernel's "tools are registered once at composition time" model). */
     register(registration: ToolRegistration): void;
     has(required: {
         toolId: string;
@@ -242,6 +256,8 @@ export type ToolInvocationAuthorization = {
     readonly descriptor: ToolDescriptor;
     readonly decision: 'allow';
     readonly handler: ToolHandler;
+    readonly input: unknown;
+    readonly normalizationNotes: readonly string[];
 } | {
     readonly descriptor: ToolDescriptor;
     readonly decision: 'deny';

package/dist/tool-registry.js

@@ -1,3 +1,4 @@
+import { normalizeToolInput } from './tool-input-normalization.js';
 /**
  * The single read-only determination: may this tool run through a surface that has promised its
  * caller it only reads?
@@ -13,28 +14,31 @@
 export function isReadOnlyTool({ descriptor }) {
     return descriptor?.readOnly === true;
 }
-/**
- * Thrown by a `ToolHandler` (or a validator it calls, e.g. the kernel's `registration-kit.ts`
- * `requireString`/`requireInputRecord`/etc.) to mean "the caller's input was malformed or missing a
- * required field" — a fact about the CALL, not the server. `@jini-ai/daemon`'s `ToolExecutor.execute`
- * tags a handler rejection's `ToolExecutionResult.errorKind` as `'validation'` when the thrown error
- * is `instanceof ToolInputError`, and every HTTP-facing mapping of a `'failed'` execution (today:
- * `@jini-ai/http-kit`'s `delegated-tools.ts`) uses that tag to answer with a 4xx instead of folding
- * it into the same redacted 500 an actual internal/infrastructure failure gets.
- *
- * Deliberately a plain marker with no extra fields: the message itself is already caller-actionable
- * (`withSchemaOnRejection` appends the tool's own input schema to it), so nothing beyond "this IS one
- * of these" needs to survive the `instanceof` check.
+/** Project registration risk for discovery using the same read-only decision as execution.
+ * Missing classification stays unknown; discovery never grants execution authority.
+ * @returns Explicit readOnly and sideEffects fields for a registry descriptor.
+ * @complexity O(1); no effects.
  */
-export class ToolInputError extends Error {
-    constructor({ message }, optional = {}) {
-        super(message, optional);
-        this.name = 'ToolInputError';
-    }
+export function toolDiscoveryMetadata({ descriptor }, _options = {}) {
+    const readOnly = isReadOnlyTool({ descriptor });
+    return { readOnly, sideEffects: descriptor?.sideEffects ?? (readOnly ? 'none' : 'unknown') };
 }
+export { ToolInputError } from './tool-input-errors.js';
 const registrationsByRegistry = new WeakMap();
+/** Refuse malformed runtime contributions before either registration path changes the registry. */
+function assertAuthorizationPolicy({ registration }, _optional = {}) {
+    if (typeof registration.policy?.authorize !== 'function') {
+        throw new Error(`ToolRegistry: tool "${registration.descriptor.id}" must declare an authorization policy`);
+    }
+}
 // Static register() remains append-only; scoped host contributions below explicitly own removal.
 const registryRevisions = new WeakMap();
+/** Advance a core registry's revision. `createToolRegistry` seeds 0 together with the registry's
+ * `registrationsByRegistry` entry, and only such registries reach `register()` or a scope's
+ * `replace()` (a scope refuses any other registry), so the seeded entry is always present. */
+function bumpRegistryRevision(registry) {
+    registryRevisions.set(registry, registryRevisions.get(registry) + 1);
+}
 /** A host can invalidate its disposable discovery snapshot without exposing handlers. */
 export function toolRegistryRevision(required, _optional = {}) {
     return registryRevisions.get(required.registry);
@@ -53,6 +57,7 @@ export function createToolRegistrationScope(required, _optional = {}) {
         replace({ registrations: next }, _optional = {}) {
             const ids = new Set();
             for (const registration of next) {
+                assertAuthorizationPolicy({ registration });
                 const id = registration.descriptor.id;
                 if (ids.has(id) || (registrations.has(id) && !owned.has(id)))
                     throw new Error(`ToolRegistry: tool "${id}" is already registered`);
@@ -71,7 +76,7 @@ export function createToolRegistrationScope(required, _optional = {}) {
                     },
                 });
             owned = ids;
-            registryRevisions.set(required.registry, (registryRevisions.get(required.registry) ?? 0) + 1);
+            bumpRegistryRevision(required.registry);
         },
     };
 }
@@ -89,11 +94,12 @@ export function createToolRegistry(_required) {
     const registrations = new Map();
     const registry = {
         register(registration) {
+            assertAuthorizationPolicy({ registration });
             if (registrations.has(registration.descriptor.id)) {
                 throw new Error(`ToolRegistry: tool "${registration.descriptor.id}" is already registered`);
             }
             registrations.set(registration.descriptor.id, registration);
-            registryRevisions.set(registry, (registryRevisions.get(registry) ?? 0) + 1);
+            bumpRegistryRevision(registry);
         },
         has({ toolId }) {
             return registrations.has(toolId);
@@ -106,6 +112,10 @@ export function createToolRegistry(_required) {
     registryRevisions.set(registry, 0);
     return registry;
 }
+/** Whether a registration has no schema or domain input-normalization hook. O(1), no effects. */
+function isSchemaFreeRegistration({ descriptor, registration }, _options = {}) {
+    return descriptor.inputSchema === undefined && registration.invocationSchema === undefined && registration.normalizeInput === undefined;
+}
 /**
  * Package-internal escape hatch: resolves `toolId` in `registry` and runs
  * its authorization gate — the tool's own {@link ToolPolicy}, then an
@@ -133,10 +143,15 @@ export async function authorizeToolInvocation({ registry, toolId, principal, run
         return undefined;
     }
     const { descriptor, handler, policy } = registration;
+    // Schema-free tools have nothing to normalize; preserve their authorization/confirmation timing.
+    const normalized = isSchemaFreeRegistration({ descriptor, registration })
+        ? { input, notes: [] }
+        : await normalizeToolInput({ input, registration });
+    input = normalized.input;
     let decision = await policy.authorize({ principal, run, tool: descriptor, input });
     if (decision === 'allow' && delegate?.onAuthorize) {
         decision = await delegate.onAuthorize({ principal, run, tool: descriptor, input });
     }
-    return decision === 'allow' ? { descriptor, decision, handler } : { descriptor, decision: 'deny' };
+    return decision === 'allow' ? { descriptor, decision, handler, input, normalizationNotes: normalized.notes } : { descriptor, decision: 'deny' };
 }
 //# sourceMappingURL=tool-registry.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "The Jini kernel: typed DI tokens, pack composition and lifecycle, the tool registry, redaction, and origin/API-token auth primitives. Zero dependencies.",
   "license": "Apache-2.0",
   "repository": {
@@ -18,6 +18,8 @@
       "./gated-mutations": "universal",
       "./model-facing-tool-errors": "universal",
       "./contribution-registry": "universal",
+      "./provider-registry": "universal",
+      "./object-store": "universal",
       "./naming": "universal",
       "./records": "universal",
       "./primitives": "universal",
@@ -32,7 +34,9 @@
         "./primitives": "core",
         "./fetch": "fetch",
         "./settings": "settings",
-        "./settings/express": "settings"
+        "./settings/express": "settings",
+        "./provider-registry": "providers",
+        "./object-store": "providers"
       },
       "domains": {
         "fetch": [
@@ -40,6 +44,10 @@
         ],
         "settings": [
           "src/settings"
+        ],
+        "providers": [
+          "src/provider-registry.ts",
+          "src/object-store.ts"
         ]
       },
       "shared": [
@@ -98,6 +106,16 @@
       "import": "./dist/contribution-registry.js",
       "default": "./dist/contribution-registry.js"
     },
+    "./provider-registry": {
+      "types": "./dist/provider-registry.d.ts",
+      "import": "./dist/provider-registry.js",
+      "default": "./dist/provider-registry.js"
+    },
+    "./object-store": {
+      "types": "./dist/object-store.d.ts",
+      "import": "./dist/object-store.js",
+      "default": "./dist/object-store.js"
+    },
     "./naming": {
       "types": "./dist/naming.d.ts",
       "import": "./dist/naming.js",

package/plugin-directory.js

@@ -8,6 +8,34 @@ const LEGACY_NAME_PATTERN = /^[a-z0-9.-]+$/;
 const CAPABILITY_PATTERN = new RegExp(`^${SEGMENT}(?::${SEGMENT})?$`);
 const object = value => typeof value === 'object' && value !== null && !Array.isArray(value);
 
+/** A declared id is malformed when it is not a bounded publisher/name string. */
+const malformedId = id => typeof id !== 'string' || id.length > 129 || !ID_PATTERN.test(id);
+const validCapability = p => typeof p === 'string' && p.length <= 129 && CAPABILITY_PATTERN.test(p);
+const legacyIdFor = localName => `unknown/${localName}`;
+
+/** The first shape error that stops identity validation before any field is interpreted. */
+function structuralError({ manifest, namespace }) {
+  if (!object(manifest)) return 'Plugin manifest must be an object.';
+  if (manifest.extensions !== undefined && !object(manifest.extensions)) return 'Plugin extensions must be an object.';
+  const extension = manifest.extensions?.[namespace];
+  if (extension !== undefined && !object(extension)) return 'Plugin identity extension must be an object.';
+  return undefined;
+}
+
+/** Errors for a declared id; an absent id is a legacy identity, not an error. */
+function idErrors({ id }) {
+  if (id === undefined) return [];
+  if (malformedId(id)) return ['Plugin id must have the form publisher/name (lowercase letters, digits, dots and hyphens).'];
+  // Only the host may infer a legacy identity; a publisher cannot claim its upgrade exemption.
+  return id.startsWith('unknown/') ? ["Plugin publisher 'unknown' is reserved for legacy identities."] : [];
+}
+
+/** Errors for a declared provides list; one malformed entry rejects the list rather than being dropped. */
+function providesErrors({ provides }) {
+  const valid = provides === undefined || (Array.isArray(provides) && provides.every(validCapability));
+  return valid ? [] : ['Plugin provides must be an array of capability names.'];
+}
+
 /** Collects identity errors without mutating the portable manifest. Absent metadata is legacy.
  * @param {{manifest: unknown, namespace: string}} required
  * @param {Record<string, never>} [optional]
@@ -15,22 +43,11 @@ const object = value => typeof value === 'object' && value !== null && !Array.is
  * @complexity O(k + p) in keyword and provides entries; no I/O.
  */
 export function validatePluginIdentity({ manifest, namespace }, optional = {}) {
-  const errors = [];
-  if (!object(manifest)) return { errors: ['Plugin manifest must be an object.'] };
-  if (manifest.extensions !== undefined && !object(manifest.extensions)) return { errors: [...errors, 'Plugin extensions must be an object.'] };
+  const structural = structuralError({ manifest, namespace });
+  if (structural !== undefined) return { errors: [structural] };
   const extension = manifest.extensions?.[namespace];
-  if (extension === undefined) return { errors };
-  if (!object(extension)) return { errors: [...errors, 'Plugin identity extension must be an object.'] };
-  if (extension.id !== undefined && (typeof extension.id !== 'string' || extension.id.length > 129 || !ID_PATTERN.test(extension.id))) {
-    errors.push('Plugin id must have the form publisher/name (lowercase letters, digits, dots and hyphens).');
-  } else if (typeof extension.id === 'string' && extension.id.startsWith('unknown/')) {
-    // Only the host may infer a legacy identity; a publisher cannot claim its upgrade exemption.
-    errors.push("Plugin publisher 'unknown' is reserved for legacy identities.");
-  }
-  if (extension.provides !== undefined && (!Array.isArray(extension.provides) || !extension.provides.every(p => typeof p === 'string' && p.length <= 129 && CAPABILITY_PATTERN.test(p)))) {
-    errors.push('Plugin provides must be an array of capability names.');
-  }
-  return { errors };
+  if (extension === undefined) return { errors: [] };
+  return { errors: [...idErrors({ id: extension.id }), ...providesErrors({ provides: extension.provides })] };
 }
 
 /** Resolves one identity; warns on missing ids and refuses malformed declarations.
@@ -45,20 +62,33 @@ export function readPluginIdentity({ manifest, namespace, name }, optional = {})
   const { errors } = validatePluginIdentity({ manifest, namespace });
   if (errors.length) throw new TypeError(errors.join(' '));
   const extension = manifest.extensions?.[namespace];
+  const declaredId = extension?.id;
   const localName = name ?? manifest.name;
-  if (extension?.id === undefined && (typeof localName !== 'string' || !LEGACY_NAME_PATTERN.test(localName))) {
+  const id = declaredId ?? legacyIdentity({ localName });
+  const keywords = normalizeKeywords({ raw: manifest.keywords });
+  const warnings = declaredId === undefined ? [`Plugin '${localName}' has no publisher-qualified id; using '${id}'.`] : [];
+  return { id, keywords, provides: [...(extension?.provides ?? [])], warnings: [...warnings, ...keywordWarnings({ raw: manifest.keywords, keywords })] };
+}
+
+/** The host-inferred `unknown/<name>` id, refusing a name the legacy grammar never accepted. */
+function legacyIdentity({ localName }) {
+  if (typeof localName !== 'string' || !LEGACY_NAME_PATTERN.test(localName)) {
     throw new TypeError('A valid plugin name is required for a legacy identity.');
   }
-  const id = extension?.id ?? `unknown/${localName}`;
-  // Keywords are advisory portable metadata: older manifests accepted mixed or non-array values.
-  // The portable parser's coercion (non-string entries dropped, non-arrays ignored) lives here
-  // so validation and lookup normalize advisory metadata through the same owner.
-  const keywords = Array.isArray(manifest.keywords) ? manifest.keywords.filter(k => typeof k === 'string' && k.trim().length > 0) : [];
-  const warnings = extension?.id === undefined ? [`Plugin '${localName}' has no publisher-qualified id; using '${id}'.`] : [];
-  if (manifest.keywords !== undefined && (!Array.isArray(manifest.keywords) || keywords.length !== manifest.keywords.length)) {
-    warnings.push('Plugin keywords must be an array of nonempty strings; invalid keywords were ignored.');
-  }
-  return { id, keywords, provides: [...(extension?.provides ?? [])], warnings };
+  return legacyIdFor(localName);
+}
+
+/** Keywords are advisory portable metadata: older manifests accepted mixed or non-array values.
+ * The portable parser's coercion (non-string entries dropped, non-arrays ignored) lives here
+ * so validation and lookup normalize advisory metadata through the same owner. */
+function normalizeKeywords({ raw }) {
+  return Array.isArray(raw) ? raw.filter(k => typeof k === 'string' && k.trim().length > 0) : [];
+}
+
+/** One warning when normalization ignored any declared keyword (or a non-array value). */
+function keywordWarnings({ raw, keywords }) {
+  const ignored = raw !== undefined && (!Array.isArray(raw) || keywords.length !== raw.length);
+  return ignored ? ['Plugin keywords must be an array of nonempty strings; invalid keywords were ignored.'] : [];
 }
 
 /** Rejects id reuse and publisher changes at an existing storage slot. Legacy metadata may
@@ -72,16 +102,25 @@ export function readPluginIdentity({ manifest, namespace, name }, optional = {})
 export function assertPluginIdentityAvailable({ candidate, installed }, optional = {}) {
   for (const plugin of installed) {
     const sameSlot = plugin.family === candidate.family && plugin.localId === candidate.localId;
-    if (sameSlot) {
-      if (plugin.id !== candidate.id && plugin.id !== `unknown/${candidate.localId}`) {
-        throw new Error(`Plugin '${candidate.localId}' belongs to a different publisher identity.`);
-      }
-    } else if (plugin.id === candidate.id && !(plugin.family !== candidate.family && candidate.id === `unknown/${candidate.localId}` && plugin.id === `unknown/${plugin.localId}`)) {
-      throw new Error(`Duplicate plugin id '${candidate.id}'.`);
-    }
+    const conflict = sameSlot ? sameSlotConflict({ plugin, candidate }) : otherSlotConflict({ plugin, candidate });
+    if (conflict !== undefined) throw new Error(conflict);
   }
 }
 
+/** A provider already in the candidate's slot may only be the same identity or its legacy fallback. */
+function sameSlotConflict({ plugin, candidate }) {
+  const compatible = plugin.id === candidate.id || plugin.id === legacyIdFor(candidate.localId);
+  return compatible ? undefined : `Plugin '${candidate.localId}' belongs to a different publisher identity.`;
+}
+
+/** A provider in another slot may not reuse the candidate's id, except equal legacy fallback ids,
+ * which are family-scoped and so name distinct plugins in different families. */
+function otherSlotConflict({ plugin, candidate }) {
+  if (plugin.id !== candidate.id) return undefined;
+  const crossFamilyLegacy = plugin.family !== candidate.family && candidate.id === legacyIdFor(candidate.localId) && plugin.id === legacyIdFor(plugin.localId);
+  return crossFamilyLegacy ? undefined : `Duplicate plugin id '${candidate.id}'.`;
+}
+
 /** Restricts an SDK handle at runtime, not just through a TypeScript interface. A host may carry
  * lifecycle mutation ports, but a plugin's discovery surface exposes only these metadata reads.
  * @param {{lookup: import('./plugin-directory.js').PluginLookupPort}} required