@jini-ai/core 0.4.9 → 0.6.11

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @jini-ai/core
 
+## 0.6.11
+
+### Patch Changes
+
+- OAuth accepts a parent protected-resource identifier and forwards the refresh resource; settings definitions are filtered; scope selectors are never id shorthand; secret-named URL parameters are masked by default in redaction.
+- Tool inputs apply a sole near-miss and declared input aliases; plugin-load outcomes are reported; `web_fetch` reads SVG/JS as text; `content_read` suggests its resource first; the browser falls back to system Chrome.
+
+## 0.6.10
+
+### Patch Changes
+
+- 22f0619: Export baseline agent-failure token patterns, credential-directory deny
+  segments, and local-owner proxy markers for reuse by consumers.
+  Preserve existing vocabulary and redaction behavior.
+- 82ed2d3: Expose the React-free fetch-query contracts/cache at @jini-ai/core/fetch; UI keeps deprecated direct type re-exports. Build core before UI and publish before consumers adopt the subpath.
+- 5a3de86: Add optional `expectedRevisionSeq` options to settings `set(required, options)` and
+  `clear(required, options)`. Compare the addressed scope's stored value revision under
+  the existing transaction's ledger lock, throwing `SettingsRevisionConflictError`
+  with expected and actual sequences on mismatch and rolling back the write and revision.
+  Revision 0 represents a missing row; cleared rows retain their revision. Omitting
+  the option preserves unconditional writes. Available through `@jini-ai/core/settings`
+  and the existing `@jini-ai/cms/settings` compatibility re-export.
+
 ## 0.4.9 — 2026-10-22
 
 - 2026-10-22: Provider registry, ObjectStore contract with object_store registry and deferObjectStore, default-on batch tool eligibility, coverage.
@@ -56,7 +79,6 @@
 - Move the domain-independent catalog/input/schema/risk/confirmation registration kit into the root entry, with its behavior contracts. Domain-specific authorization and denial errors remain outside the kernel.
 - Use the existing named argument surface directly; primitive, Result and tool catalog types remain canonical in core.
 
-
 ### Shared kernel
 
 - Add `./primitives` with canonical time, ID, JSON, HTTP, logger and result contracts,
@@ -80,7 +102,6 @@
 - Origin diagnostics use `Pick<Logger, 'warn'>` rather than a duplicate logger interface.
   The alias name `OriginValidationLoggerPort` remains available with the shared shape.
 
-
 - Add transport-neutral gated mutations with required token generation/TTL and async
   authorization, identity and token-store ports; preserve verified-plan handoff and
   single-use redemption, with atomic explicit expiry and duplicate-issuance rejection.

package/README.md

@@ -44,6 +44,11 @@ peer used only by `@jini-ai/core/settings/express`; install it in hosts mounting
 
 ## Usage
 
+The root exports baseline security vocabulary: `AGENT_FAILURE_SECRET_SHAPE_RE`,
+`CREDENTIAL_FILE_DENY_SEGMENTS`, `LOCAL_OWNER_PROXY_MARKER_PREFIXES`, and
+`LOCAL_OWNER_PROXY_MARKER_HEADERS`. Consumers apply these in their existing failure-redaction,
+guarded-file, and local-owner admission policies; the existing redactors are unchanged.
+
 ```ts
 import { bindings, definePack, createDaemon, token, createToolRegistry, registerPackTools } from '@jini-ai/core';
 

package/dist/redact.d.ts

@@ -38,6 +38,34 @@ export interface SecretShapePattern {
 }
 export declare const PEM_PATTERN_NAME = "PEM private key block";
 export declare const SECRET_SHAPE_PATTERNS: readonly SecretShapePattern[];
+/** Broad token shapes for agent-failure text; consumers retain their plain [REDACTED] pipeline. */
+export declare const AGENT_FAILURE_SECRET_SHAPE_RE: RegExp;
+/**
+ * Exact path SEGMENT names refused at any depth, matched case-insensitively against each segment
+ * of the caller-supplied path (never a substring — a directory named `not-secrets-actually` is not
+ * a match). `secrets` is the owner's explicit example: whatever a site or app tree names its
+ * credentials folder (`sites/**\/secrets/`, `apps/admin/**\/secrets/`, or anywhere else), it never
+ * becomes reachable through this domain. A denied segment is refused by the guarded reader
+ * AND skipped entirely by the `fs_list_files` walk — its contents are never even enumerated,
+ * not merely refused once named. Besides `secrets`, the set names the
+ * well-known credential-store directories a home-directory `custom` root can expose: `.aws`
+ * (`credentials`), `.docker` (`config.json` with registry auth), `.kube` (`config`), and
+ * `gcloud`/`gh` for `.config/gcloud/application_default_credentials.json` and
+ * `.config/gh/hosts.yml`. Denied by SEGMENT rather than by leaf filename on purpose: `config`,
+ * `config.json`, and `hosts.yml` are generic names that appear harmlessly elsewhere, so denying the
+ * directory is the narrower of the two mistakes.
+ *
+ * A host's install-wide site-key directory (2026-09-24) needs the same protection; the host appends it.
+ * Production stores it beside individual site folders on a durable volume; local/dev stores
+ * it below the home directory, reachable through an operator-set `custom` root. Its key backs
+ * site-key administration, webhook/newsletter signing secrets, and permission checks, so the
+ * agent must never read it from disk. Denying the whole directory segment, rather than only
+ * a generated key filename, also prevents `fs_list_files` from enumerating its contents — the
+ * same "never even advertise it" property `secrets` gets above.
+ */
+export declare const CREDENTIAL_FILE_DENY_SEGMENTS: readonly string[];
+export declare const LOCAL_OWNER_PROXY_MARKER_PREFIXES: readonly string[];
+export declare const LOCAL_OWNER_PROXY_MARKER_HEADERS: readonly string[];
 export interface SecretRedactionPattern {
     name: string;
     regex: RegExp;

package/dist/redact.js

@@ -52,6 +52,40 @@ export const SECRET_SHAPE_PATTERNS = [
     { name: "Fastmail app password (fm2_)", pattern: /(?<![A-Za-z0-9+/=])fm2_[A-Za-z0-9+/=]{20,}/ },
     { name: PEM_PATTERN_NAME, pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
 ];
+/** Broad token shapes for agent-failure text; consumers retain their plain [REDACTED] pipeline. */
+export const AGENT_FAILURE_SECRET_SHAPE_RE = /\b(?:AIza[\w-]+|AQ\.[\w.\/-]+|sk-[\w.-]+|gh[pousr]_[\w]+|github_pat_[\w]+|ya29\.[\w.-]+|eyJ[\w-]+\.[\w-]+(?:\.[\w-]+)?)/g;
+/**
+ * Exact path SEGMENT names refused at any depth, matched case-insensitively against each segment
+ * of the caller-supplied path (never a substring — a directory named `not-secrets-actually` is not
+ * a match). `secrets` is the owner's explicit example: whatever a site or app tree names its
+ * credentials folder (`sites/**\/secrets/`, `apps/admin/**\/secrets/`, or anywhere else), it never
+ * becomes reachable through this domain. A denied segment is refused by the guarded reader
+ * AND skipped entirely by the `fs_list_files` walk — its contents are never even enumerated,
+ * not merely refused once named. Besides `secrets`, the set names the
+ * well-known credential-store directories a home-directory `custom` root can expose: `.aws`
+ * (`credentials`), `.docker` (`config.json` with registry auth), `.kube` (`config`), and
+ * `gcloud`/`gh` for `.config/gcloud/application_default_credentials.json` and
+ * `.config/gh/hosts.yml`. Denied by SEGMENT rather than by leaf filename on purpose: `config`,
+ * `config.json`, and `hosts.yml` are generic names that appear harmlessly elsewhere, so denying the
+ * directory is the narrower of the two mistakes.
+ *
+ * A host's install-wide site-key directory (2026-09-24) needs the same protection; the host appends it.
+ * Production stores it beside individual site folders on a durable volume; local/dev stores
+ * it below the home directory, reachable through an operator-set `custom` root. Its key backs
+ * site-key administration, webhook/newsletter signing secrets, and permission checks, so the
+ * agent must never read it from disk. Denying the whole directory segment, rather than only
+ * a generated key filename, also prevents `fs_list_files` from enumerating its contents — the
+ * same "never even advertise it" property `secrets` gets above.
+ */
+// Generic credential-store segments only. A host adds its own product-specific key directory
+// (e.g. its install-wide site-key folder) when it builds its deny-list; core stays product-neutral.
+export const CREDENTIAL_FILE_DENY_SEGMENTS = ["secrets", ".aws", ".docker", ".kube", "gcloud", "gh"];
+// A local tunnel has a loopback socket and may rewrite Host; refuse marker presence, even empty.
+export const LOCAL_OWNER_PROXY_MARKER_PREFIXES = ["x-forwarded-", "x-envoy-", "x-ms-"];
+export const LOCAL_OWNER_PROXY_MARKER_HEADERS = [
+    "forwarded", "x-real-ip", "via", "cf-connecting-ip", "true-client-ip", "x-original-host",
+    "x-client-ip", "x-cluster-client-ip", "fastly-client-ip", "tailscale-user-login", "x-original-forwarded-for",
+];
 // Order matters: list specific rules before more general ones. Langfuse
 // keys (`sk-lf-...`) would otherwise be eaten by the generic `sk-...`
 // rule and labeled as a generic OpenAI-style key.
@@ -147,7 +181,8 @@ function isLuhnValid(digits) {
 // correlation ID uses uppercase hex and is meant to reach the model and be quoted to an
 // operator; delegated-tool-calls is the route segment named in delegated tool failures.
 // Matching the ENTIRE run keeps a secret glued onto either spelling redactable.
-export const LABELED_SECRET_RE = /\b(authorization|bearer|api[-_]?key|access[-_]?token|refresh[-_]?token|client[-_]?secret|password|secret|cookie)\b\s*[:=]\s*\S+/gi;
+const SECRET_LABELS = 'authorization|bearer|api[-_]?key|access[-_]?token|refresh[-_]?token|client[-_]?secret|password|secret|cookie';
+export const LABELED_SECRET_RE = new RegExp(`\\b(${SECRET_LABELS})\\b\\s*[:=]\\s*\\S+`, 'gi');
 export const OPAQUE_TOKEN_RE = /[A-Za-z0-9_-]{20,}/g;
 export const NON_SECRET_TOKEN_RE = /^(?:ERR-[0-9A-F]{4}(?:-[0-9A-F]{4}){3}|delegated-tool-calls|[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)$/;
 // Runtime markers must survive a second pass; the bounded sanitizer deliberately retains
@@ -164,6 +199,15 @@ const PROVIDER_API_KEY_QUERY = /([?&]key=)([^&\s]+)/gi;
 // readable for debugging without exposing credentials that authorize access to the resource.
 const URL_CREDENTIALS_RE = /(\b[a-z][a-z0-9+.-]*:\/\/)([^/\s?#@]+)@/gi;
 const SIGNED_QUERY_RE = /([?&](?:signature|sig|x-amz-signature|x-goog-signature|access_token|refresh_token)=)([^&#\s,;"']+)/gi;
+// A secret word must END a name segment (split at . _ - or the name's end): api_key, apiKey,
+// authtoken, X-Amz-Signature and custom.Token-value are masked, while author, keyword, design,
+// signup and page stay readable. Names that merely end in a secret word (zipcode, error_code,
+// monkey) are masked too; over-masking a URL value is the cheaper failure. Empty values stay.
+// Match through a trailing fragment; only '&', quotes, parentheses or whitespace end the value.
+// Both name runs are bounded so a long separator-free run costs linear time, not quadratic.
+const URL_SECRET_PARAM_RE = /[?&#;]([\w.-]{0,128}?(?:token|key|secret|signature|sig|code|password|passwd|pwd|auth|authorization|credential)s?(?=[._=-])[\w.-]{0,128})=[^&\s"'<>()]+/gi;
+// A parameter the labeled rule already names (password, client_secret, ...) keeps that category.
+const LABELED_URL_PARAM_NAME_RE = new RegExp(`(?:^|[.-])(?:${SECRET_LABELS})$`, 'i');
 // Only an entire marker is already masked. A secret glued onto marker-like text still needs
 // masking; a substring check would preserve credential suffixes in echoed header/query values.
 function isMaskedValue(value) {
@@ -267,6 +311,9 @@ function redactKeyedCredentials({ text, marker }) {
     out = out.replace(API_KEY_QUERY, (match, prefix) => isMaskedValue(match.slice(prefix.length)) ? match : `${prefix}${marker('api_key_query')}`);
     out = out.replace(SHORT_BEARER_RE, () => marker('bearer_token'));
     out = out.replace(PROVIDER_API_KEY_HEADER, (match, name, value) => isMaskedValue(value) ? match : `${name}: ${marker('api_key_header')}`);
+    // Sweep other URL parameters before the general labeled rule can consume harmless
+    // neighboring parameters (`password=x&page=2` used to lose `&page=2`).
+    out = redactUrlSecretParams({ text: out, marker });
     return out.replace(MASK_AWARE_LABELED_SECRET_RE, (match, _label, value) => {
         // Replace only the captured value, retaining labels even when no whitespace separates
         // them. Glued credential suffixes fail the complete-marker check and remain maskable.
@@ -275,6 +322,16 @@ function redactKeyedCredentials({ text, marker }) {
         return `${match.slice(0, -value.length)}${marker('labeled_secret')}`;
     });
 }
+/** Secret-named URL query/fragment values; values already masked above keep their category. */
+function redactUrlSecretParams({ text, marker }) {
+    return text.replace(URL_SECRET_PARAM_RE, (match, name) => {
+        const separator = match.indexOf('=') + 1;
+        if (isMaskedValue(match.slice(separator)))
+            return match;
+        const category = LABELED_URL_PARAM_NAME_RE.test(name) ? 'labeled_secret' : 'url_secret_param';
+        return `${match.slice(0, separator)}${marker(category)}`;
+    });
+}
 /** Email/IPv4/phone rules, then Luhn-checked card candidates. */
 function redactPii({ text, marker }) {
     return applyPatterns({ text, marker, patterns: PII_PATTERNS }).replace(CARD_CANDIDATE, (match) => {

package/dist/settings/agent-tools.js

@@ -49,13 +49,16 @@ import { AGENT_WRITABLE_PREFERENCE_IDS, AGENT_WRITABLE_PREFERENCES } from "./age
    * write entries this file documents but never wires (see file header) carry no schema at all,
    * since one is never published for a tool the model never sees.
    *
- * No arguments — `settings_list_definitions` takes none; it always enumerates the caller's own
- * (boot-wired) workspace's site-owned partition plus the shared platform partition. */
-const NO_INPUT_SCHEMA = {
+ * Optional filters narrow the caller's own (boot-wired) workspace's site-owned partition plus
+ * the shared platform partition; they never select a different workspace. */
+const LIST_DEFINITIONS_SCHEMA = {
     type: "object",
     additionalProperties: false,
     required: [],
-    properties: {},
+    properties: {
+        search: { type: "string", description: "Case-insensitive text filter over the full 'namespace.key' name." },
+        namespace: { type: "string", description: "Only definitions in this exact namespace." },
+    },
 };
 /** Shared by `settings_get_effective`/`settings_get_raw`: naming a DIFFERENT principal than the
  * caller requires `settings.user.read` (checked by the handler, not expressed in this schema). */
@@ -138,10 +141,10 @@ export function getSettingsAgentToolCatalog() {
     return [
         {
             name: "settings_list_definitions",
-            description: "Lists every active setting definition visible to this workspace (platform core/theme definitions plus this workspace's own site-owned definitions): namespace, key, owner kind, scope bitmask, status, version, schema, agentWritable and confirmationRequired. Use before writing a setting. Metadata only — never a value.",
+            description: "Lists active setting definitions visible to this workspace (platform core/theme definitions plus this workspace's own site-owned definitions), optionally filtered by search text and exact namespace: namespace, key, owner kind, scope bitmask, status, version, schema, agentWritable and confirmationRequired. Use before writing a setting. Metadata only — never a value.",
             sideEffects: "none",
             authorization: { permission: "settings.read.definitions" },
-            inputSchema: NO_INPUT_SCHEMA,
+            inputSchema: LIST_DEFINITIONS_SCHEMA,
         },
         {
             name: "settings_get_effective",

package/dist/settings/errors.d.ts

@@ -18,6 +18,19 @@ export declare class SecretNotSupportedError extends Error {
 }
 export declare class ValueValidationFailedError extends Error {
 }
+/**
+ * A scoped value changed since the caller's snapshot; read again before retrying.
+ * Both sequences refer to the addressed value row, never the ledger's global watermark.
+ * @example if (error instanceof SettingsRevisionConflictError) await refreshSnapshot();
+ */
+export declare class SettingsRevisionConflictError extends Error {
+    readonly expectedRevisionSeq: number;
+    readonly actualRevisionSeq: number;
+    constructor(required: {
+        expectedRevisionSeq: number;
+        actualRevisionSeq: number;
+    }, optional?: ErrorOptions);
+}
 export declare class RenameRetypeConflictError extends Error {
 }
 export declare class AliasDepthExceededError extends Error {

package/dist/settings/errors.js

@@ -18,6 +18,21 @@ export class SecretNotSupportedError extends Error {
 }
 export class ValueValidationFailedError extends Error {
 }
+/**
+ * A scoped value changed since the caller's snapshot; read again before retrying.
+ * Both sequences refer to the addressed value row, never the ledger's global watermark.
+ * @example if (error instanceof SettingsRevisionConflictError) await refreshSnapshot();
+ */
+export class SettingsRevisionConflictError extends Error {
+    expectedRevisionSeq;
+    actualRevisionSeq;
+    constructor(required, optional = {}) {
+        super(`Setting revision changed: expected ${required.expectedRevisionSeq}, found ${required.actualRevisionSeq}.`, optional);
+        this.name = "SettingsRevisionConflictError";
+        this.expectedRevisionSeq = required.expectedRevisionSeq;
+        this.actualRevisionSeq = required.actualRevisionSeq;
+    }
+}
 export class RenameRetypeConflictError extends Error {
 }
 export class AliasDepthExceededError extends Error {

package/dist/settings/index.d.ts

@@ -11,11 +11,11 @@
  * `SettingsRepoPort` this barrel exports.
  */
 export { SCOPE_BIT, type SettingScope, type SettingOwnerKind, type DefinitionStatus, type ValueState, type RevisionEntityKind, type RevisionOp, type SettingValueSchema, type SettingDefinitionRecord, type SettingValueRecord, type SettingRevisionRecord, type SettingScopeContext, } from "./types.js";
-export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
+export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, SettingsRevisionConflictError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
 export type { SettingsRepoPort } from "./ports.js";
 export { InMemorySettingsRepo } from "./repo.memory.js";
 export { type DefinitionInput, validateDefinitionInput, validateValueAgainstSchema, registerCoercer, invalidateDefinitionNamespaceCache, invalidateWorkspaceSettingsCache, resolveDefinitionRaw, resolveDefinition, type ResolvedSetting, getEffective, } from "./settings.js";
-export { type AuthorizeFn, type SettingsWriteServiceDeps, deriveRequiredPermission, type RegisterDefinitionsRequired, registerDefinitions, type SetValueRequired, set, type ClearValueRequired, clear, type ResetNamespaceRequired, resetNamespace, type RenameDefinitionRequired, renameDefinition, type RetypeDefinitionRequired, retypeDefinition, type ReconcileDefinitionDefaultRequired, reconcileDefinitionDefault, type DeprecateDefinitionRequired, deprecateDefinition, type TombstoneDefinitionRequired, tombstoneDefinition, } from "./write-service.js";
+export { type AuthorizeFn, type SettingsWriteServiceDeps, deriveRequiredPermission, type RegisterDefinitionsRequired, registerDefinitions, type SetValueRequired, type SettingsValueWriteOptions, set, type ClearValueRequired, clear, type ResetNamespaceRequired, resetNamespace, type RenameDefinitionRequired, renameDefinition, type RetypeDefinitionRequired, retypeDefinition, type ReconcileDefinitionDefaultRequired, reconcileDefinitionDefault, type DeprecateDefinitionRequired, deprecateDefinition, type TombstoneDefinitionRequired, tombstoneDefinition, } from "./write-service.js";
 export { type PurgeServiceDeps, type PurgeTenantSettingsRequired, purgeTenantSettings, } from "./purge-service.js";
 export { type ChangeFeedViewer, isRevisionVisibleTo, type ChangeFeedBatch, collectChangedNamespaces, } from "./change-feed.js";
 export { type DefinitionOpRequestItem, type DefinitionOpContext, type DefinitionOpHandler, NON_REGISTER_DEFINITION_OP_NAMES, type NonRegisterDefinitionOp, parseNonRegisterDefinitionOp, NON_REGISTER_DEFINITION_OPS, } from "./definitions-dispatch.js";

package/dist/settings/index.js

@@ -11,7 +11,7 @@
  * `SettingsRepoPort` this barrel exports.
  */
 export { SCOPE_BIT, } from "./types.js";
-export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
+export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, SettingsRevisionConflictError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
 export { InMemorySettingsRepo } from "./repo.memory.js";
 export { validateDefinitionInput, validateValueAgainstSchema, registerCoercer, invalidateDefinitionNamespaceCache, invalidateWorkspaceSettingsCache, resolveDefinitionRaw, resolveDefinition, getEffective, } from "./settings.js";
 export { deriveRequiredPermission, registerDefinitions, set, clear, resetNamespace, renameDefinition, retypeDefinition, reconcileDefinitionDefault, deprecateDefinition, tombstoneDefinition, } from "./write-service.js";

package/dist/settings/ports.d.ts

@@ -68,7 +68,13 @@ export interface SettingsRepoPort {
         principalId: UUID;
         settingId: UUID;
     }): Promise<void>;
-    /** Appends a revision and returns its assigned `seq` (used to stamp the paired value row). */
+    /**
+     * Appends a revision and returns its assigned `seq` (used to stamp the paired value row).
+     * Inside a transaction, serialize revision writers until that enclosing transaction ends:
+     * `set`/`clear` compare the stored value's seq AFTER this call, so the lock must cover the
+     * comparison and value save too. SQLite's write transaction and Postgres's transaction-scoped
+     * ledger lock provide this; memory refuses overlapping transactions.
+     */
     appendRevision(record: Omit<SettingRevisionRecord, "seq">): Promise<number>;
     listRevisions(required: {
         settingId: UUID;

package/dist/settings/tool-registrations.js

@@ -1,7 +1,7 @@
 import { adaptLegacyAuthorize } from "../tool-permissions.js";
 import { agentWriteRules, buildSettingsValueWriteHandler, toWriteDeps } from "./agent-value-write-tools.js";
 import { findAgentWriteRule } from "./agent-write-denylist.js";
-import { buildDomainRegistrations, indexCatalogById, optionalString, requireInputRecord, requireNoInput, requireString, withSchemaOnRejection } from "../registration-kit.js";
+import { buildDomainRegistrations, indexCatalogById, optionalString, requireInputRecord, requireString, withSchemaOnRejection } from "../registration-kit.js";
 import { ToolInputError } from "../tool-registry.js";
 import { requireToolPermission } from "../tool-permissions.js";
 import { getSettingsAgentToolCatalog } from "./agent-tools.js";
@@ -140,15 +140,21 @@ export function buildSettingsRegistrations(routeDeps) {
         settings_set_value: buildSettingsValueWriteHandler(routeDeps, "settings_set_value"),
         settings_clear_value: buildSettingsValueWriteHandler(routeDeps, "settings_clear_value"),
         settings_list_definitions: async (ctx) => {
-            requireNoInput({ input: ctx.input });
+            const input = requireInputRecord({ input: ctx.input === undefined ? {} : ctx.input });
+            const search = optionalString({ input, key: "search" })?.toLowerCase();
+            const namespace = optionalString({ input, key: "namespace" });
             await routeDeps.settingsReady;
             await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "settings.read.definitions" }, { entityType: "setting-definition" });
             const [platformDefs, siteDefs] = await Promise.all([
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: null }),
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: routeDeps.workspaceId }),
             ]);
+            // Filter only authorized workspace rows, before alias lookups; never search stored values.
+            const definitions = [...platformDefs, ...siteDefs]
+                .filter((def) => namespace === undefined || def.namespace === namespace)
+                .filter((def) => !search || `${def.namespace}.${def.key}`.toLowerCase().includes(search));
             const rules = agentWriteRules(routeDeps);
-            const data = (await Promise.all([...platformDefs, ...siteDefs].map((def) => describeDefinitionForAgent(routeDeps, rules, def))))
+            const data = (await Promise.all(definitions.map((def) => describeDefinitionForAgent(routeDeps, rules, def))))
                 .sort((a, b) => a.namespace.localeCompare(b.namespace) || a.key.localeCompare(b.key));
             return { data };
         },

package/dist/settings/write-service.d.ts

@@ -110,8 +110,21 @@ export interface SetValueRequired {
         requiredPermissionOverride?: string | undefined;
     };
 }
-/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export declare function set(required: SetValueRequired): Promise<{
+/** Optional concurrency guard shared by `set` and `clear`. */
+export interface SettingsValueWriteOptions {
+    /** Compare the addressed layer's stored seq, including cleared rows; 0 means no stored row.
+     * Omission preserves unconditional writes. Defaults, inherited values and definition revisions
+     * do not count. A mismatch throws SettingsRevisionConflictError and rolls back the write.
+     */
+    readonly expectedRevisionSeq?: number | undefined;
+}
+/**
+ * Authorize -> validate -> value + revision in one transaction. An optional expectedRevisionSeq
+ * refuses a stale scoped value and rolls back its revision; omission keeps unconditional writes.
+ * @example await set({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function set(required: SetValueRequired, optional?: SettingsValueWriteOptions): Promise<{
     value: JsonValue;
     revisionSeq: number;
 }>;
@@ -135,8 +148,14 @@ export interface ClearValueRequired {
         authWorkspaceId?: UUID | undefined;
     };
 }
-/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export declare function clear(required: ClearValueRequired): Promise<{
+/**
+ * Authorize -> cleared value + revision in one transaction; the optional concurrency guard has
+ * the same semantics as `set`. With skipTransaction, the enclosing caller must propagate errors
+ * so its transaction rolls back the appended revision on conflict.
+ * @example await clear({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function clear(required: ClearValueRequired, optional?: SettingsValueWriteOptions): Promise<{
     revisionSeq: number;
 }>;
 export interface ResetNamespaceRequired {

package/dist/settings/write-service.js

@@ -1,5 +1,5 @@
 import { nowIso as kernelNowIso } from "../primitives/index.js";
-import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, ValueValidationFailedError, } from "./errors.js";
+import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, SettingsRevisionConflictError, ValueValidationFailedError, } from "./errors.js";
 import { invalidateDefinitionNamespaceCache, resolveDefinitionRaw, validateDefinitionInput, validateValueAgainstSchema, } from "./settings.js";
 import { SCOPE_BIT } from "./types.js";
 /**
@@ -148,8 +148,33 @@ async function assertTargetPrincipalInWorkspace(deps, input) {
         throw new PrincipalNotFoundError(`principal '${input.principalId}' was not found in workspace '${input.workspaceId}'`, input.principalId, input.workspaceId);
     }
 }
-/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export async function set(required) {
+/**
+ * Check the addressed value after appendRevision has taken the ledger lock. On Postgres, a read
+ * before that lock can see the same old seq in two READ COMMITTED transactions and lose an update.
+ * The caller's enclosing transaction rolls the appended revision back on conflict.
+ * @complexity At most one scoped value read; no reads when the option is omitted.
+ */
+async function assertExpectedRevision(required, optional = {}) {
+    if (optional.expectedRevisionSeq === undefined)
+        return;
+    const { repo, settingId, input } = required;
+    const current = input.scope === "global"
+        ? await repo.getGlobalValue(settingId)
+        : input.scope === "workspace"
+            ? await repo.getWorkspaceValue({ workspaceId: input.workspaceId, settingId })
+            : await repo.getUserValue({ workspaceId: input.workspaceId, principalId: input.principalId ?? input.callerPrincipalId, settingId });
+    const actualRevisionSeq = current?.seq ?? 0;
+    if (actualRevisionSeq !== optional.expectedRevisionSeq) {
+        throw new SettingsRevisionConflictError({ expectedRevisionSeq: optional.expectedRevisionSeq, actualRevisionSeq });
+    }
+}
+/**
+ * Authorize -> validate -> value + revision in one transaction. An optional expectedRevisionSeq
+ * refuses a stale scoped value and rolls back its revision; omission keeps unconditional writes.
+ * @example await set({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export async function set(required, optional = {}) {
     const { deps, input } = required;
     const permission = input.requiredPermissionOverride ??
         deriveRequiredPermission({
@@ -190,6 +215,7 @@ export async function set(required) {
             changeSetId: null,
             createdAt: now,
         });
+        await assertExpectedRevision({ repo: deps.repo, settingId: definition.settingId, input }, optional);
         const base = {
             settingId: definition.settingId,
             scope: input.scope,
@@ -222,8 +248,14 @@ export async function set(required) {
     });
     return result;
 }
-/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export async function clear(required) {
+/**
+ * Authorize -> cleared value + revision in one transaction; the optional concurrency guard has
+ * the same semantics as `set`. With skipTransaction, the enclosing caller must propagate errors
+ * so its transaction rolls back the appended revision on conflict.
+ * @example await clear({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export async function clear(required, optional = {}) {
     const { deps, input } = required;
     if (!input.skipAuthorize) {
         const permission = deriveRequiredPermission({
@@ -262,6 +294,7 @@ export async function clear(required) {
             changeSetId: null,
             createdAt: now,
         });
+        await assertExpectedRevision({ repo: deps.repo, settingId: definition.settingId, input }, optional);
         const base = {
             settingId: definition.settingId,
             scope: input.scope,

package/dist/tool-input-normalization.d.ts

@@ -8,8 +8,8 @@ export interface NormalizedToolInput {
 export type ToolInputNormalizer = (required: {
     input: Readonly<Record<string, unknown>>;
 }, optional?: Record<string, never>) => NormalizedToolInput | Promise<NormalizedToolInput>;
-/** Canonicalize one batch layer before merging; preserve values and domain aliases for the
- * final normalization. Throws ToolInputError for collisions within this layer, never across
+/** Canonicalize one batch layer (including declared aliases) before merging; leave value conversion
+ * and domain hooks for final normalization. Throws ToolInputError for collisions within this layer, never across
  * layers. Uses the same bounded schema walk as normalizeToolInput.
  * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
  */
@@ -20,7 +20,8 @@ export declare function canonicalizeToolInputKeys({ input, schema }: {
     input: Record<string, unknown>;
     notes: readonly string[];
 };
-/** Normalize before policy, confirmation and handler validation. Domain hooks own semantic aliases.
+/** Normalize before policy, confirmation and handler validation. Schema properties may declare
+ * `aliases: ['search', 'query']`; domain hooks own transformations beyond declared key aliases.
  * Never changes the caller's object or includes values in notes. Invalid/ambiguous input remains
  * a ToolInputError; ordinary domain/schema validation still belongs to the registered handler.
  * @complexity Two bounded schema walks plus the optional domain hook's cost.

package/dist/tool-input-normalization.js

@@ -15,11 +15,16 @@ function sameLengthNearMiss({ left, right, index }) {
     return left.slice(index + 1) === right.slice(index + 1)
         || (left[index] === right[index + 1] && left[index + 1] === right[index] && left.slice(index + 2) === right.slice(index + 2));
 }
-/** Whether either key is the generic id shorthand for the other's id suffix; hints only. */
+/** Scope selectors name a container, never the resource: guessing `workspaceId` as `id` (or the
+ * reverse) would silently drop or invent a scope. Only a declared name or alias may accept one. */
+const SCOPE_SELECTORS = new Set(['workspaceid', 'siteid']);
+/** Whether either key is the generic id shorthand for the other's id suffix; never for a scope selector. */
 function isIdShorthand({ left, right }, _options = {}) {
+    if (SCOPE_SELECTORS.has(left) || SCOPE_SELECTORS.has(right))
+        return false;
     return (left === 'id' && right.endsWith('id')) || (right === 'id' && left.endsWith('id'));
 }
-/** Detect id shorthand or one insertion, deletion, substitution or transposition, for hints only. */
+/** Detect id shorthand or one insertion, deletion, substitution or transposition. */
 function nearMiss({ left, right }, _options = {}) {
     if (left.length > 128 || right.length > 128)
         return false;
@@ -53,6 +58,19 @@ function coerceString({ value, types, path, notes }) {
     }
     return coerceNumber({ value, types, path, notes });
 }
+/** Unwrap only a singleton string array; refuse malformed arrays without exposing values.
+ * Keys-only batch layers preserve values until the final merged input is normalized.
+ * @complexity O(t) time for t allowed schema types, O(1) space; array contents are not scanned.
+ */
+function unwrapStringArray({ value, types, step }) {
+    if (step.walk.keysOnly || !Array.isArray(value) || !types.includes('string'))
+        return value;
+    if (value.length !== 1 || typeof value[0] !== 'string') {
+        throw new ToolInputError({ message: `${step.path}: send one value as a string or a one-element string array.` });
+    }
+    step.walk.notes.push(`${step.path}: one-item string array→string`);
+    return value[0];
+}
 function normalizeArray({ value, schema, step }) {
     const { path, depth, walk } = step;
     let list = value;
@@ -65,12 +83,30 @@ function normalizeArray({ value, schema, step }) {
         return list;
     return list.map((item, index) => normalizeValue({ value: item, schema: schema.items, step: { path: `${path}[${index}]`, depth: depth + 1, walk } }));
 }
-/** The declared property a supplied key names, or undefined; refuses a key that names two. */
+/** Match a canonical spelling or its property's declared string aliases, ignoring case/separators.
+ * Malformed alias annotations confer no alternate names; exact property names still win.
+ * @complexity O(a) comparisons for a aliases on this property; no input mutation or effects.
+ */
+function matchesDeclaredKey({ key, name, schema }, _options = {}) {
+    if (keyShape(name) === keyShape(key))
+        return true;
+    if (!object(schema) || !Array.isArray(schema.aliases))
+        return false;
+    return schema.aliases.some(alias => typeof alias === 'string' && keyShape(alias) === keyShape(key));
+}
+/** Exact names, then case/separator variants and declared aliases, then a sole hint; ambiguous hints stay unresolved
+ * for the domain hook or closed-schema refusal. Never choose one of several candidates.
+ * Hints apply only where a closed schema would refuse the key: an open schema accepts it as data.
+ * @complexity O(p + a) comparisons for p properties and a declared aliases; O(p) space.
+ */
 function canonicalKey({ key, location, shape }) {
-    const candidates = Object.hasOwn(shape.properties, key) ? [key] : shape.names.filter(name => keyShape(name) === keyShape(key));
+    const candidates = Object.hasOwn(shape.properties, key) ? [key] : shape.names.filter(name => matchesDeclaredKey({ key, name, schema: shape.properties[name] }));
     if (candidates.length > 1)
         throw new ToolInputError({ message: `Ambiguous input '${location}': matches ${candidates.join(', ')}. Use exactly one canonical property name.` });
-    return candidates[0];
+    if (candidates.length === 1 || shape.schema.additionalProperties !== false)
+        return candidates[0];
+    const hints = shape.names.filter(name => nearMiss({ left: keyShape(key), right: keyShape(name) }));
+    return hints.length === 1 ? hints[0] : undefined;
 }
 /** Describe the local schema and likely names without choosing a name or exposing input values.
  * Target and permission fields must be declared in the tool schema before callers can use them.
@@ -111,7 +147,7 @@ function normalizeObject({ value, schema, step }) {
     return Object.fromEntries(Object.entries(value).map(([key, raw]) => normalizeEntry({ key, raw, shape, sources, step })));
 }
 /** Schema-guided copies only: unconstrained data and unsupported schema dialects stay untouched.
- * Cost is O(k*p) per object with k supplied keys and p schema properties; recursion is bounded
+ * Cost is O(k*(p+a)) comparisons per object with k supplied keys, p properties and a aliases; recursion is bounded
  * to 64 levels so a hostile input/schema cannot exhaust the execution gate's stack.
  */
 function normalizeValue({ value, schema, step }) {
@@ -126,14 +162,15 @@ function normalizeValue({ value, schema, step }) {
     }
     if (types.includes('array'))
         return normalizeArray({ value, schema, step });
-    return object(value) ? normalizeObject({ value, schema, step }) : value;
+    const unwrapped = unwrapStringArray({ value, types, step });
+    return object(unwrapped) ? normalizeObject({ value: unwrapped, schema, step }) : unwrapped;
 }
 /** A walk from the root of one input. */
 function walkRoot({ input, schema, notes, validateClosed, keysOnly }) {
     return normalizeValue({ value: input, schema, step: { path: '', depth: 0, walk: { notes, validateClosed, keysOnly } } });
 }
-/** Canonicalize one batch layer before merging; preserve values and domain aliases for the
- * final normalization. Throws ToolInputError for collisions within this layer, never across
+/** Canonicalize one batch layer (including declared aliases) before merging; leave value conversion
+ * and domain hooks for final normalization. Throws ToolInputError for collisions within this layer, never across
  * layers. Uses the same bounded schema walk as normalizeToolInput.
  * @example canonicalizeToolInputKeys({ input: { max_chars: '1000' }, schema });
  */
@@ -141,7 +178,8 @@ export function canonicalizeToolInputKeys({ input, schema }, _options = {}) {
     const notes = [];
     return { input: walkRoot({ input, schema, notes, validateClosed: false, keysOnly: true }), notes };
 }
-/** Normalize before policy, confirmation and handler validation. Domain hooks own semantic aliases.
+/** Normalize before policy, confirmation and handler validation. Schema properties may declare
+ * `aliases: ['search', 'query']`; domain hooks own transformations beyond declared key aliases.
  * Never changes the caller's object or includes values in notes. Invalid/ambiguous input remains
  * a ToolInputError; ordinary domain/schema validation still belongs to the registered handler.
  * @complexity Two bounded schema walks plus the optional domain hook's cost.

package/dist/tool-registry.d.ts

@@ -46,6 +46,9 @@ export interface ToolDescriptor {
      * JSON-Schema-shaped description of this tool's accepted input, carried as `unknown` because the
      * 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.
+     * Each property may declare `aliases: readonly string[]` (e.g. contains: { type: 'string',
+     * aliases: ['search', 'query'] }). The gate treats these like case variants, rejects ambiguous
+     * or conflicting names, and reports the rename in normalization notes.
      *
      * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.4.9",
+  "version": "0.6.11",
   "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": {