@jini-ai/core 0.4.8 → 0.6.10

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.8",
+  "version": "0.6.10",
   "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