@jini-ai/core 0.4.1 → 0.4.2

package/dist/settings/settings.d.ts

@@ -0,0 +1,139 @@
+import type { JsonValue } from "../primitives/index.js";
+import { DefinitionInvalidError, SecretNotSupportedError } from "./errors.js";
+import type { SettingsRepoPort } from "./ports.js";
+import { type SettingDefinitionRecord, type SettingOwnerKind, type SettingScopeContext, type SettingValueSchema } from "./types.js";
+/**
+ * @file The settings resolver + pure definition-registration validation
+ * ("one evaluator").
+ *
+ * Purpose:
+ * `validateDefinitionInput` is pure (no I/O) — the write-side chokepoint in
+ * `write-service.ts` calls it before persisting. `getEffective`/`getLayer`/
+ * `resolveDefinition` are read-only against `SettingsRepoPort`. Neither
+ * mutates anything; every mutation goes through `write-service.ts`.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export interface DefinitionInput {
+    namespace: string;
+    key: string;
+    ownerKind: SettingOwnerKind;
+    workspaceId: string | null;
+    ownerId?: string | null | undefined;
+    schema: SettingValueSchema;
+    defaultValue: JsonValue | null;
+    scopes: number;
+    secret: boolean;
+}
+/**
+ * — the pure half of `registerDefinitions`.
+ * Never throws; returns a discriminated result so the chokepoint decides how
+ * to surface the failure (matches `ValueValidationFailedError`'s pattern of
+ * keeping I/O out of validation).
+ *
+ * @complexity O(1) per definition.
+ * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function validateDefinitionInput(input: DefinitionInput): {
+    valid: true;
+} | {
+    valid: false;
+    error: DefinitionInvalidError | SecretNotSupportedError;
+};
+export declare function validateValueAgainstSchema(schema: SettingValueSchema, value: JsonValue): boolean;
+export declare function registerCoercer({ tag, fn }: {
+    tag: string;
+    fn: (required: {
+        value: JsonValue;
+    }) => JsonValue;
+}, _optional?: Record<string, never>): void;
+/**
+ * Bumps the namespace's definition-cache epoch (lazy invalidation) — every
+ * previously-cached definition-cache entry for this
+ * namespace (across every workspace) becomes unreachable on the next read,
+ * without needing to enumerate tenants. Call after any write that changes a
+ * definition's identity/shape/status in this namespace: register, rename
+ * (both the old and new namespace), retype, deprecate, tombstone.
+ */
+export declare function invalidateDefinitionNamespaceCache(repo: SettingsRepoPort, namespace: string): void;
+/**
+ * Purge support — now a no-op, deliberately kept rather than deleted.
+ *
+ * This cleared the workspace- and user-scope layer-cache entries a tenant/principal teardown
+ * invalidated, because a purge deletes an unbounded number of value rows across an unknown set of
+ * namespaces and per-namespace single-key invalidation was not practical for it. With the layer
+ * cache gone (see this module's cache header) there is nothing left to clear: the rows are deleted,
+ * and the next read goes to the repo and sees them gone.
+ *
+ * Kept as an explicit no-op instead of removed because of what it guards. `purge-service.ts` calls
+ * it as the last step of deleting a tenant's settings, and its correctness question — "can a purged
+ * value still be read back?" — is exactly the kind that must be answered again if anyone
+ * reintroduces caching. Deleting the call site would remove the place that question is asked. A
+ * cache added without restoring a purge hook is a tenant-teardown leak, so this stays as the seam.
+ */
+export declare function invalidateWorkspaceSettingsCache(_required: {
+    repo: SettingsRepoPort;
+    workspaceId: string;
+}, _optional?: {
+    principalId?: string | undefined;
+}): void;
+/**
+ * Follows an alias marker (depth <=1) to the current row and returns it as
+ * stored — status intact, including `tombstone`. `resolveDefinition` (below)
+ * is the read-path wrapper that collapses tombstone to typed-absent;
+ * `write-service.ts` uses this raw form directly so it can report
+ * `DEFINITION_TOMBSTONED` distinctly from "not found".
+ * Malformed alias targets, cycles and chains deeper than one fail closed as absent.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function resolveDefinitionRaw(deps: {
+    repo: SettingsRepoPort;
+}, input: {
+    namespace: string;
+    key: string;
+    workspaceId: string | null;
+}): Promise<SettingDefinitionRecord | null>;
+/**
+ * The read-path resolver: typed-absent (`null`) for a tombstoned or
+ * missing key. Cached — keyed by
+ * `(workspaceId, namespace, key, namespace-epoch)`, so it is workspace-
+ * qualified by construction and invalidated wholesale by
+ * `invalidateDefinitionNamespaceCache` on any definition-lifecycle write
+ * (register/rename/retype/deprecate/tombstone). `resolveDefinitionRaw`
+ * itself stays uncached — the write chokepoint (`write-service.ts`) calls it
+ * directly so authorization/validation decisions are always made against
+ * live data, never a cached read.
+ */
+export declare function resolveDefinition(deps: {
+    repo: SettingsRepoPort;
+}, input: {
+    namespace: string;
+    key: string;
+    workspaceId: string | null;
+}): Promise<SettingDefinitionRecord | null>;
+export interface ResolvedSetting {
+    value: JsonValue | null;
+    sourceLayer: "user" | "workspace" | "global" | "default";
+    defVersion: number;
+}
+/**
+ * — total for a live key: never throws, never returns
+ * undefined. Precedence `user ?? workspace ?? global ?? default`. A
+ * `cleared` row is treated as absent at that layer (behavior.spec §1.2).
+ *
+ * Per-layer reads go straight to the repo (see this module's cache header for
+ * why the per-layer value cache that used to wrap these three calls does not
+ * exist here).
+ *
+ * @complexity O(1) — up to 3 layer reads + 1 definition read.
+ * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function getEffective(deps: {
+    repo: SettingsRepoPort;
+}, input: {
+    namespace: string;
+    key: string;
+    scopeContext: SettingScopeContext;
+}): Promise<ResolvedSetting | null>;
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings/settings.js

@@ -0,0 +1,259 @@
+import { DefinitionInvalidError, SecretNotSupportedError } from "./errors.js";
+import { SCOPE_BIT, } from "./types.js";
+const NAMESPACE_FENCE = {
+    core: (input) => input.namespace.startsWith("core.") && input.workspaceId === null,
+    theme: (input) => input.namespace.startsWith("theme.") && input.workspaceId === null,
+    site: (input) => input.namespace.startsWith("site.") && input.workspaceId !== null,
+};
+/**
+ * — the pure half of `registerDefinitions`.
+ * Never throws; returns a discriminated result so the chokepoint decides how
+ * to surface the failure (matches `ValueValidationFailedError`'s pattern of
+ * keeping I/O out of validation).
+ *
+ * @complexity O(1) per definition.
+ * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export function validateDefinitionInput(input) {
+    if (input.secret) {
+        return {
+            valid: false,
+            error: new SecretNotSupportedError({
+                // See docs/decisions/DR-003-settings-ledger-invariants.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+                message: "secret:true definitions are not supported in the core-only subset",
+            }),
+        };
+    }
+    if (!NAMESPACE_FENCE[input.ownerKind](input)) {
+        return {
+            valid: false,
+            error: new DefinitionInvalidError(
+            // See docs/decisions/DR-003-settings-ledger-invariants.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+            `namespace '${input.namespace}' does not match the owner fence for owner_kind '${input.ownerKind}'`),
+        };
+    }
+    if (input.scopes < 1 || input.scopes > 7) {
+        return {
+            valid: false,
+            error: new DefinitionInvalidError(`scopes bitmask ${input.scopes} is out of range 1..7`),
+        };
+    }
+    // a site-owned def (workspace_id NOT NULL) may never declare the global scope bit. See docs/decisions/DR-003-settings-ledger-invariants.md.
+    if (input.workspaceId !== null && (input.scopes & SCOPE_BIT.global) !== 0) {
+        return {
+            valid: false,
+            error: new DefinitionInvalidError(
+            // See docs/decisions/DR-003-settings-ledger-invariants.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+            "a site-owned definition may not declare the global scope bit"),
+        };
+    }
+    // Totality (behavior.spec §3): every non-secret def needs a non-null default so
+    // getEffective is always total and factory-reset is provably bootable. See docs/decisions/DR-003-settings-ledger-invariants.md.
+    if (input.defaultValue === null) {
+        return {
+            valid: false,
+            error: new DefinitionInvalidError(
+            // See docs/decisions/DR-003-settings-ledger-invariants.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+            "non-secret definitions require a non-null default_json (totality)"),
+        };
+    }
+    return { valid: true };
+}
+export function validateValueAgainstSchema(schema, value) {
+    if (value === null)
+        return schema.nullable === true;
+    switch (schema.type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number";
+        case "boolean":
+            return typeof value === "boolean";
+        case "enum":
+            return typeof value === "string" && schema.values.includes(value);
+        case "json":
+            // Any JSON value is accepted; internal shape/length validation is the
+            // registering feature's own write-path job — see
+            // docs/decisions/settings-json-schema-variant.md.
+            return true;
+    }
+}
+/** Identity-registry of total coercers keyed by `coercionTag`. `"identity"` is always registered. See docs/decisions/DR-003-settings-ledger-invariants.md. */
+const coercers = new Map([["identity", ({ value }) => value]]);
+export function registerCoercer({ tag, fn }, _optional = {}) {
+    coercers.set(tag, fn);
+}
+const cacheByRepo = new WeakMap();
+function getCacheStore(repo) {
+    let store = cacheByRepo.get(repo);
+    if (!store) {
+        store = { definitions: new Map(), epoch: new Map() };
+        cacheByRepo.set(repo, store);
+    }
+    return store;
+}
+function namespaceEpoch(store, namespace) {
+    return store.epoch.get(namespace) ?? 0;
+}
+function workspaceCachePart(workspaceId) {
+    return workspaceId ?? "platform";
+}
+function definitionCacheKey(workspaceId, namespace, key, epoch) {
+    return `def:${workspaceCachePart(workspaceId)}:${namespace}:${key}:e${epoch}`;
+}
+/**
+ * Bumps the namespace's definition-cache epoch (lazy invalidation) — every
+ * previously-cached definition-cache entry for this
+ * namespace (across every workspace) becomes unreachable on the next read,
+ * without needing to enumerate tenants. Call after any write that changes a
+ * definition's identity/shape/status in this namespace: register, rename
+ * (both the old and new namespace), retype, deprecate, tombstone.
+ */
+export function invalidateDefinitionNamespaceCache(repo, namespace) {
+    const store = getCacheStore(repo);
+    store.epoch.set(namespace, namespaceEpoch(store, namespace) + 1);
+}
+/**
+ * Purge support — now a no-op, deliberately kept rather than deleted.
+ *
+ * This cleared the workspace- and user-scope layer-cache entries a tenant/principal teardown
+ * invalidated, because a purge deletes an unbounded number of value rows across an unknown set of
+ * namespaces and per-namespace single-key invalidation was not practical for it. With the layer
+ * cache gone (see this module's cache header) there is nothing left to clear: the rows are deleted,
+ * and the next read goes to the repo and sees them gone.
+ *
+ * Kept as an explicit no-op instead of removed because of what it guards. `purge-service.ts` calls
+ * it as the last step of deleting a tenant's settings, and its correctness question — "can a purged
+ * value still be read back?" — is exactly the kind that must be answered again if anyone
+ * reintroduces caching. Deleting the call site would remove the place that question is asked. A
+ * cache added without restoring a purge hook is a tenant-teardown leak, so this stays as the seam.
+ */
+export function invalidateWorkspaceSettingsCache(_required, _optional = {}) {
+    // Intentionally empty — see doc above. Do not delete without re-reading `purge-service.ts`.
+}
+/**
+ * Follows an alias marker (depth <=1) to the current row and returns it as
+ * stored — status intact, including `tombstone`. `resolveDefinition` (below)
+ * is the read-path wrapper that collapses tombstone to typed-absent;
+ * `write-service.ts` uses this raw form directly so it can report
+ * `DEFINITION_TOMBSTONED` distinctly from "not found".
+ * Malformed alias targets, cycles and chains deeper than one fail closed as absent.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export async function resolveDefinitionRaw(deps, input) {
+    // Namespace fencing makes `site.*` (non-null workspace_id) and. See docs/decisions/DR-003-settings-ledger-invariants.md.
+    // `core.*`/`theme.*` (null workspace_id) disjoint by construction, so a
+    // caller resolving inside a workspace context may still be asking for a
+    // platform definition. Try the caller's own partition first, then fall
+    // back to the platform (null) partition.
+    const visited = new Set();
+    let cursor = input;
+    for (let depth = 0; depth <= 1; depth++) {
+        const address = JSON.stringify([cursor.workspaceId, cursor.namespace, cursor.key]);
+        if (visited.has(address))
+            return null;
+        visited.add(address);
+        const found = (await deps.repo.findActiveDefinition(cursor)) ??
+            (cursor.workspaceId !== null
+                ? await deps.repo.findActiveDefinition({ ...cursor, workspaceId: null })
+                : null);
+        if (!found)
+            return null;
+        if (found.status !== "alias")
+            return found;
+        if (depth === 1 || found.aliasOfNamespace == null || found.aliasOfKey == null)
+            return null;
+        cursor = {
+            namespace: found.aliasOfNamespace,
+            key: found.aliasOfKey,
+            workspaceId: input.workspaceId,
+        };
+    }
+    return null;
+}
+/**
+ * The read-path resolver: typed-absent (`null`) for a tombstoned or
+ * missing key. Cached — keyed by
+ * `(workspaceId, namespace, key, namespace-epoch)`, so it is workspace-
+ * qualified by construction and invalidated wholesale by
+ * `invalidateDefinitionNamespaceCache` on any definition-lifecycle write
+ * (register/rename/retype/deprecate/tombstone). `resolveDefinitionRaw`
+ * itself stays uncached — the write chokepoint (`write-service.ts`) calls it
+ * directly so authorization/validation decisions are always made against
+ * live data, never a cached read.
+ */
+export async function resolveDefinition(deps, input) {
+    const store = getCacheStore(deps.repo);
+    const epoch = namespaceEpoch(store, input.namespace);
+    const cacheKey = definitionCacheKey(input.workspaceId, input.namespace, input.key, epoch);
+    if (store.definitions.has(cacheKey))
+        return store.definitions.get(cacheKey);
+    const found = await resolveDefinitionRaw(deps, input);
+    const resolved = !found || found.status === "tombstone" ? null : found;
+    store.definitions.set(cacheKey, resolved);
+    return resolved;
+}
+/**
+ * — total for a live key: never throws, never returns
+ * undefined. Precedence `user ?? workspace ?? global ?? default`. A
+ * `cleared` row is treated as absent at that layer (behavior.spec §1.2).
+ *
+ * Per-layer reads go straight to the repo (see this module's cache header for
+ * why the per-layer value cache that used to wrap these three calls does not
+ * exist here).
+ *
+ * @complexity O(1) — up to 3 layer reads + 1 definition read.
+ * @overallScore 100
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export async function getEffective(deps, input) {
+    const definition = await resolveDefinition(deps, {
+        namespace: input.namespace,
+        key: input.key,
+        workspaceId: input.scopeContext.workspaceId ?? null,
+    });
+    if (!definition)
+        return null;
+    const coerce = (value, defVersion) => {
+        if (defVersion === definition.version)
+            return value;
+        const coercer = coercers.get(definition.coercionTag ?? "identity") ?? coercers.get("identity");
+        return coercer({ value });
+    };
+    // Every layer read below goes straight to the repo. See this module's cache header for why there
+    // is no per-layer cache wrapping these three calls.
+    if (input.scopeContext.workspaceId && input.scopeContext.principalId) {
+        const workspaceId = input.scopeContext.workspaceId;
+        const principalId = input.scopeContext.principalId;
+        const userValue = await deps.repo.getUserValue({ workspaceId, principalId, settingId: definition.settingId });
+        if (userValue && userValue.state === "set") {
+            return {
+                value: coerce(userValue.valueJson, userValue.defVersion),
+                sourceLayer: "user",
+                defVersion: definition.version,
+            };
+        }
+    }
+    if (input.scopeContext.workspaceId) {
+        const workspaceId = input.scopeContext.workspaceId;
+        const workspaceValue = await deps.repo.getWorkspaceValue({ workspaceId, settingId: definition.settingId });
+        if (workspaceValue && workspaceValue.state === "set") {
+            return {
+                value: coerce(workspaceValue.valueJson, workspaceValue.defVersion),
+                sourceLayer: "workspace",
+                defVersion: definition.version,
+            };
+        }
+    }
+    const globalValue = await deps.repo.getGlobalValue(definition.settingId);
+    if (globalValue && globalValue.state === "set") {
+        return {
+            value: coerce(globalValue.valueJson, globalValue.defVersion),
+            sourceLayer: "global",
+            defVersion: definition.version,
+        };
+    }
+    return { value: definition.defaultValue, sourceLayer: "default", defVersion: definition.version };
+}
+//# sourceMappingURL=settings.js.map

package/dist/settings/tool-registrations.d.ts

@@ -0,0 +1,54 @@
+import type { IdGenerator } from "../primitives/index.js";
+import type { Clock } from "../primitives/index.js";
+/**
+ * @file Settings tools: three reads and three bounded value writes. Bulk reset and definition
+ * registration stay unwired. The generic tools reuse write-service authorization/validation and
+ * return the previous override. Key policy and the optional host confirmation port enforce the
+ * owner's 2026-10-01 decision: privacy/instructions/self-configuration require a human card.
+ * Direct reads supply their own permission checks; writes pre-check before reading undo values
+ * and the service repeats authorization at mutation time. No host HTTP/runtime imports.
+ */
+import type { LegacyToolAuthorizeFn as AuthorizeFn } from "../tool-permissions.js";
+import { type SettingsWriteConfirmation } from "./agent-value-write-tools.js";
+import { type AgentSettingWriteRule } from "./agent-write-denylist.js";
+import { type DerivedRiskByToolId } from "../registration-kit.js";
+import type { ToolExecutionOptions, ToolRegistration } from "../tool-registry.js";
+import type { SettingsPrincipalLookupPort } from "./principal-lookup.js";
+import type { SettingsRepoPort } from "./ports.js";
+import { set as setSettingValue } from "./write-service.js";
+/**
+ * The exact slice of a host's route-deps bag Settings' tool handlers read. Declared structurally
+ * (rather than importing any host's own route-deps type) so this module carries no back-edge into
+ * a host's composition root. A host satisfies this structurally by passing its existing route deps
+ * object after binding kernel clock/IDs and an active, workspace-scoped principal lookup.
+ */
+export interface SettingsToolDeps {
+    authorize: AuthorizeFn;
+    workspaceId: string;
+    clock: Clock;
+    idGen: IdGenerator;
+    settingsReady: Promise<void>;
+    settingsUiTabsReady: Promise<void>;
+    settingsRepo: SettingsRepoPort;
+    principalRepo: SettingsPrincipalLookupPort;
+    /** Host extensions: explicit deny or human-confirmation rules, never agent inputs. */
+    extraDeniedSettings?: readonly AgentSettingWriteRule[];
+    extraConfirmationSettings?: readonly AgentSettingWriteRule[];
+    /** Host policy replaces the package defaults; extensions still add explicit protected keys. */
+    confirmationSettings?: readonly AgentSettingWriteRule[];
+    /** Must obtain an authenticated human card decision; absent means protected keys fail closed.
+     * `options` is the invoking transport's execution options (its `emitSurface`), forwarded from the
+     * tool handler's second argument: the card can only reach a human through that seam. */
+    confirmWrite?: (request: SettingsWriteConfirmation, options?: ToolExecutionOptions) => Promise<boolean>;
+    /** Host's validation wrapper; defaults to the package's existing set chokepoint. */
+    setValue?: typeof setSettingValue;
+}
+/**
+ * This wiring layer's OWN risk classification, authored from what each handler below actually
+ * calls. See `DerivedRiskByToolId` in the kit for why it is independent of the catalog's own
+ * `sideEffects` declaration — and note that the two excluded bulk/schema writes appear NOWHERE here, which is
+ * itself the strongest of the guards: an unclassified id cannot be wired at all.
+ */
+export declare const settingsDerivedRisk: DerivedRiskByToolId;
+export declare function buildSettingsRegistrations(routeDeps: SettingsToolDeps): ToolRegistration[];
+//# sourceMappingURL=tool-registrations.d.ts.map