@jini-ai/core 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # @jini-ai/core
 
+## 0.4.1 — 2026-10-05
+
+- New `readToolLimit({ input, max, fallback }, { key })`: an absent limit is `fallback`, one above `max` is capped at `max`, and a non-integer or one below 1 throws `ToolInputError` ("'limit' must be an integer between 1 and <max>").
+- New `optionalOneOf({ input, key, values })`: a value outside `values` throws `ToolInputError` ("'<key>' must be one of: ..."). Both are additive.
+
 ## 0.4.0 — 2026-10-02
 
 ### BREAKING

package/dist/registration-kit.d.ts

@@ -167,6 +167,40 @@ export declare function optionalBoolean(requiredArgs: {
     input: Record<string, unknown>;
     key: string;
 }, optionalArgs?: Record<string, never>): boolean | undefined;
+/**
+ * Reads a list tool's page-size field. A list schema's `minimum: 1, maximum: <max>` is advice to the
+ * model, not enforcement: without this a `limit` of 0, -5 or 2.5 reached the query and came back as an
+ * empty or nonsensical page the model could not tell apart from "no rows".
+ *
+ * @param required.max The schema's documented cap; a larger request is capped to it, not refused,
+ *   because the schemas promise "server-capped at <max>".
+ * @param required.fallback Returned when the key is absent.
+ * @param _optional.key The field name, `limit` by default; it is also the name the error message uses.
+ * @returns An integer in `[1, max]`.
+ * @throws {ToolInputError} when the value is present but not an integer >= 1.
+ * @complexity O(1).
+ */
+export declare function readToolLimit(required: {
+    input: Record<string, unknown>;
+    max: number;
+    fallback: number;
+}, _optional?: {
+    key?: string;
+}): number;
+/**
+ * Reads an optional enum field (a list filter's `status`, say). An off-enum value is refused rather
+ * than passed through, because as a filter it silently matches nothing and reads as "no rows".
+ *
+ * @param required.values The schema's `enum`, in the order the error message lists them.
+ * @returns The value, or `undefined` when the key is absent.
+ * @throws {ToolInputError} naming every allowed value when the value is present but not listed.
+ * @complexity O(values).
+ */
+export declare function optionalOneOf<T extends string>(required: {
+    input: Record<string, unknown>;
+    key: string;
+    values: readonly T[];
+}, _optional?: Record<string, never>): T | undefined;
 /**
  * The reader for a parameterless tool: `ctx.input` may be omitted entirely or passed as `{}`,
  * nothing else. Refusing a populated object is deliberate — silently ignoring keys would teach a

package/dist/registration-kit.js

@@ -163,6 +163,49 @@ export function optionalBoolean(requiredArgs, optionalArgs = {}) {
         throw new ToolInputError({ message: `'${key}' must be a boolean` });
     return value;
 }
+/**
+ * Reads a list tool's page-size field. A list schema's `minimum: 1, maximum: <max>` is advice to the
+ * model, not enforcement: without this a `limit` of 0, -5 or 2.5 reached the query and came back as an
+ * empty or nonsensical page the model could not tell apart from "no rows".
+ *
+ * @param required.max The schema's documented cap; a larger request is capped to it, not refused,
+ *   because the schemas promise "server-capped at <max>".
+ * @param required.fallback Returned when the key is absent.
+ * @param _optional.key The field name, `limit` by default; it is also the name the error message uses.
+ * @returns An integer in `[1, max]`.
+ * @throws {ToolInputError} when the value is present but not an integer >= 1.
+ * @complexity O(1).
+ */
+export function readToolLimit(required, _optional = {}) {
+    const { input, max, fallback } = required;
+    const key = _optional.key ?? "limit";
+    const value = input[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new ToolInputError({ message: `'${key}' must be an integer between 1 and ${max}` });
+    }
+    return Math.min(value, max);
+}
+/**
+ * Reads an optional enum field (a list filter's `status`, say). An off-enum value is refused rather
+ * than passed through, because as a filter it silently matches nothing and reads as "no rows".
+ *
+ * @param required.values The schema's `enum`, in the order the error message lists them.
+ * @returns The value, or `undefined` when the key is absent.
+ * @throws {ToolInputError} naming every allowed value when the value is present but not listed.
+ * @complexity O(values).
+ */
+export function optionalOneOf(required, _optional = {}) {
+    const { input, key, values } = required;
+    const value = input[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !values.includes(value)) {
+        throw new ToolInputError({ message: `'${key}' must be one of: ${values.join(", ")}` });
+    }
+    return value;
+}
 /**
  * The reader for a parameterless tool: `ctx.input` may be omitted entirely or passed as `{}`,
  * nothing else. Refusing a populated object is deliberate — silently ignoring keys would teach a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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": {
@@ -79,7 +79,8 @@
     "!dist/**/*.test.js.map",
     "!dist/**/*.test.d.ts.map",
     "!dist/**/__tests__/**",
-    "!dist/**/*.typecheck.*"
+    "!dist/**/*.typecheck.*",
+    "!dist/**/*.map"
   ],
   "publishConfig": {
     "access": "public",

package/dist/internal.d.ts

@@ -1,41 +0,0 @@
-/**
- * @module @jini-ai/core/internal
- *
- * Package-internal entry point — NOT part of `@jini-ai/core`'s public
- * contract. Two unrelated escape hatches live here, each for its own
- * single intended consumer:
- *
- * - {@link authorizeToolInvocation} so `@jini-ai/daemon`'s `ToolExecutor` can
- *   resolve a registered tool and run its authorization gate — the tool's
- *   own `ToolPolicy`, then an optional transport-level veto — before ever
- *   receiving the handler. This is the security-sensitive one: it is a
- *   runtime *value* export, but unlike the `getToolRegistration` it
- *   replaced (2026-07-29 hardening pass), it only ever returns a handler
- *   closure alongside a `decision: 'allow'` — a denied or unauthorized call
- *   gets no handler at all, so the authorization gate cannot be bypassed by
- *   calling this export directly instead of going through `ToolExecutor`.
- * - `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` so `@jini-ai/server`'s
- *   `createLocalNodeDaemon` can re-derive `createDaemon`'s exact
- *   compile-time "missing binding" gate on its own wrapper config type,
- *   instead of either duplicating the type-level logic or losing the
- *   compile-time check through the wrapper. These are `import type`-only —
- *   erased at build time, carry no runtime capability, and are not a
- *   security boundary the way {@link authorizeToolInvocation} is.
- *
- * **Correction (2026-07-19 hardening pass):** a package.json `exports` map
- * subpath is NOT a language-level or per-consumer access modifier — Node's
- * module resolution will happily resolve `@jini-ai/core/internal` for *any*
- * package that depends on `@jini-ai/core`, not just the intended consumer.
- * Earlier revisions of this doc comment claimed this boundary was
- * "enforced" by the exports map; that was inaccurate and left the leak
- * undetected. The actual enforcement is `scripts/check-engine-boundaries.ts`'s
- * rule forbidding any *value* import from `@jini-ai/core/internal` outside
- * `packages/daemon/**` (type-only imports of the DI-token-derivation types
- * remain unrestricted, since they carry no runtime capability) — that guard
- * is wired in, but is a second, independent layer on top of the 2026-07-29
- * structural fix above, not a substitute for it.
- */
-export { authorizeToolInvocation } from './tool-registry.js';
-export type { ToolAuthorizationDelegate, ToolInvocationAuthorization } from './tool-registry.js';
-export type { AnyPack, MissingTokenIds, RequiredTokenIds } from './daemon.js';
-//# sourceMappingURL=internal.d.ts.map

package/dist/internal.js

@@ -1,39 +0,0 @@
-/**
- * @module @jini-ai/core/internal
- *
- * Package-internal entry point — NOT part of `@jini-ai/core`'s public
- * contract. Two unrelated escape hatches live here, each for its own
- * single intended consumer:
- *
- * - {@link authorizeToolInvocation} so `@jini-ai/daemon`'s `ToolExecutor` can
- *   resolve a registered tool and run its authorization gate — the tool's
- *   own `ToolPolicy`, then an optional transport-level veto — before ever
- *   receiving the handler. This is the security-sensitive one: it is a
- *   runtime *value* export, but unlike the `getToolRegistration` it
- *   replaced (2026-07-29 hardening pass), it only ever returns a handler
- *   closure alongside a `decision: 'allow'` — a denied or unauthorized call
- *   gets no handler at all, so the authorization gate cannot be bypassed by
- *   calling this export directly instead of going through `ToolExecutor`.
- * - `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` so `@jini-ai/server`'s
- *   `createLocalNodeDaemon` can re-derive `createDaemon`'s exact
- *   compile-time "missing binding" gate on its own wrapper config type,
- *   instead of either duplicating the type-level logic or losing the
- *   compile-time check through the wrapper. These are `import type`-only —
- *   erased at build time, carry no runtime capability, and are not a
- *   security boundary the way {@link authorizeToolInvocation} is.
- *
- * **Correction (2026-07-19 hardening pass):** a package.json `exports` map
- * subpath is NOT a language-level or per-consumer access modifier — Node's
- * module resolution will happily resolve `@jini-ai/core/internal` for *any*
- * package that depends on `@jini-ai/core`, not just the intended consumer.
- * Earlier revisions of this doc comment claimed this boundary was
- * "enforced" by the exports map; that was inaccurate and left the leak
- * undetected. The actual enforcement is `scripts/check-engine-boundaries.ts`'s
- * rule forbidding any *value* import from `@jini-ai/core/internal` outside
- * `packages/daemon/**` (type-only imports of the DI-token-derivation types
- * remain unrestricted, since they carry no runtime capability) — that guard
- * is wired in, but is a second, independent layer on top of the 2026-07-29
- * structural fix above, not a substitute for it.
- */
-export { authorizeToolInvocation } from './tool-registry.js';
-//# sourceMappingURL=internal.js.map