@objectstack/core 17.1.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,201 @@
 # @objectstack/core
 
+## 17.2.0
+
+### Minor Changes
+
+- ee2ff45: `ObjectKernel` no longer pre-injects the in-memory `job` fallback for the `job` core-service slot — a fallback must not fake capability (#10746, maintainer ruling 2026-08-22). `createMemoryJob()`'s `schedule()` records a job and never fires it (it owns no timer), so pre-injecting it made every "prefer the platform job service, else own a timer" consumer take the job-service branch on a kernel without `@objectstack/service-job` and then silently never run: `plugin-reports` logged `dispatcher registered with job service` and dispatched nothing, ever.
+  
+  Behavior change, FROM → TO: on an `ObjectKernel` without a registered `job` service, `getService('job')` FROM resolving a non-scheduling in-memory registry TO throwing `Service 'job' not found`. Consumers' documented no-job-service paths take over (`plugin-reports` falls through to its own `setInterval` and scheduled reports actually dispatch; schedule triggers and declarative jobs warn loudly instead of scheduling into the void), and the kernel says the absence out loud at boot: `Core service missing, functionality may be degraded: job`.
+  
+  One-line fix if you relied on the old behavior: install `@objectstack/service-job` for real scheduling, or — if you deliberately want the manual-trigger in-memory registry — register it explicitly: `kernel.registerService('job', createMemoryJob())` (the factory is still exported from `@objectstack/core`).
+
+### Patch Changes
+
+- 3b2af5e: `resolveUserAuthzGrants` issues its five independent reads (sys_user, both sys_member reads, sys_user_position, sys_user_permission_set) concurrently (#10825) — 8 sequential round trips become 4 waves on the fullest path (2 on the lightest), with byte-identical rows, filters, limits and tenancy scoping, pinned by a differential golden suite captured from the sequential implementation. No caching; nothing survives a request; authorization semantics unchanged by construction.
+- 47cd3ec: The kernel's two `Promise.race` timeout guards — the startup guard around each
+  plugin's `init`/`start`, and the shutdown guard around `performShutdown()` —
+  now reclaim **both** halves of the guard when the race settles: the timer is
+  cleared *and* the losing promise is settled (#10604).
+  
+  Neither site settled its loser, so the timeout promise and the reaction
+  `Promise.race` held on it were retained for the life of the process — four
+  leaking promises per showcase test run under `vitest --detectAsyncLeaks`, now
+  zero. The two hand-rolled copies had also drifted into doing opposite halves of
+  the same cleanup: the startup site cleared its timer and never `unref`'d, the
+  shutdown site `unref`'d and never cleared. Both now go through one internal
+  `TimeoutGuard`, so they cannot drift apart again. No exported API changes.
+  
+  **Behaviour change, at the shutdown guard:** the shutdown timer is no longer
+  `unref()`d. Two consequences for an embedding host (CLI, auth-proxy, test
+  runner):
+  
+  - After a **successful** shutdown, no timer is left armed. Previously the guard
+    survived its own race and stayed scheduled to fire against a kernel already
+    `'stopped'`. That late rejection was *handled* — `Promise.race` had attached a
+    rejection handler to it — so this was never an unhandled-rejection risk; it
+    was retained work and a wakeup after teardown.
+  - When teardown **hangs**, the guard now actually fires. An unref'd timer does
+    not keep the event loop alive, so a process with nothing else to run could
+    exit silently — status 0, teardown incomplete — before `shutdownTimeout`
+    elapsed, leaving `Shutdown timed out — forcing exit` and its `exit(1)`
+    unreachable in exactly the case they exist for. Reclaiming on settle keeps the
+    guard ref'd exactly as long as the race is undecided, which is the guarantee
+    the startup guard already had (#4813).
+  
+  If your host relied on a hung `shutdown()` letting the process fall out of the
+  event loop on its own, it will now wait up to `shutdownTimeout` (default 60s)
+  and then hard-exit with status 1. Lower `shutdownTimeout` in the kernel config
+  to shorten that window.
+- 9d7d2de: `resolveLocalizationContext` now memoizes a FAILED read's fallback per `(ql, tenantId, userId)` for 30s (#10221).
+  
+  On a fresh environment whose `sys_setting` table hasn't been created/migrated yet, every authenticated request re-ran the same `sys_setting` localization read, and every one of those reads failed the same way ("no such table"). The `#2409` batching had already collapsed the three per-key reads a single request used to issue into one query, but that one query still repeated on every subsequent request, and `driver-sql`'s `backendStatementFault` logs a `[sql-driver] DATABASE_ERROR` warning on every failed read — so the identical warning printed once per request and buried real errors in between.
+  
+  Only the case where the underlying read genuinely fails (a backend fault, e.g. the missing table) is cached; a successful read — including a legitimate "nothing configured yet" empty result — is never cached and always re-reads on the next call, so a settings write takes effect immediately. (An earlier version of this fix cached every outcome, mirroring `packages/plugins/plugin-audit/src/audit-writers.ts`'s existing TTL cache of this same read — safe there because audit-trail enrichment is best-effort, but not safe for `@objectstack/rest`'s use of this function: analytics date-bucketing reads the org timezone on every query and `packages/qa/dogfood/test/analytics-timezone.dogfood.test.ts` — the #1982/#2018 golden regression — asserts the very next read reflects a just-written timezone.) The `UTC` / `en-US` fallback behavior itself is unchanged; this only stops the failing query — and its log line — from re-running every request. The cache is keyed on the `ql` engine instance first, so two environments/tenants sharing one process never share a cached outcome, and self-heals within one TTL window once `sys_setting` exists.
+- c815c50: `resolveLocalizationContext` prefers `settings.getMany` — one grouped namespace read instead of three per-key `get()`s (#10826); older services without `getMany` keep the three parallel gets, and a thrown `getMany` lands in the same direct `$in` fallback a thrown `get` did.
+- 795ea05: A lapsed `sys_member` row now confers no org role either — one row, one answer (#10982)
+  
+  `resolveUserAuthzGrants` reads `sys_member` once and derives two facts from it:
+  `accessible_org_ids` (the `group` posture's read reach, ADR-0105 D2) and the
+  org-administration role projection into `positions` (ADR-0095 D3). Only the
+  first applied the ADR-0091 validity window. A membership outside
+  `[valid_from, valid_until)` was therefore excluded from org access while still
+  projecting its better-auth role — two answers from one read, and with
+  `role: 'owner'` the role reaches the `organization_admin` capability that
+  `derivePosture` reads for `TENANT_ADMIN`.
+  
+  The role projection now drops out-of-window rows **before** the derivation, the
+  same shape `sys_user_permission_set` already had, so an expired membership can
+  no more yield `org_owner` than an expired `admin_full_access` can yield
+  `platform_admin`. Fail-closed per ADR-0091 D2. Maintainer ruling, 2026-08-22
+  live session (item 2): a lapsed membership is *no membership*, not merely *no
+  org access*.
+  
+  **Why `patch` and not a breaking bump, argued in the open.** This is a real
+  change of authorization semantics — a membership that used to confer a role
+  stops conferring it — so the direction is a tightening, and tightenings are the
+  kind of change that normally earns a major. It is nevertheless `patch` because
+  the population it can affect is provably empty: `sys_member` declares neither
+  `valid_from` nor `valid_until` (see `sys-member.object.ts`), and `isGrantActive`
+  reads an absent bound as unbounded, so **no row any deployment can currently
+  store is lapsed** and every existing membership resolves exactly as before. That
+  is asserted directly rather than reasoned about, in
+  `resolve-authz-context.test.ts` ("a membership with NO bounds is unbounded —
+  every shipped row is unaffected"), alongside the load-bearing leg that an
+  in-window membership still projects its role. Landing it now is the cheap
+  moment: once the columns exist, the same change becomes a migration carrying
+  live semantics.
+  
+  **Not in scope, and deliberately so.** This does not add the validity columns to
+  `sys_member`, and it does not reach into `sys_user_permission_set` rows that
+  plugin-security's `reconcileOrgAdminGrant` provisioned from a membership role.
+  Such a grant is standing authority in its own right with its own ADR-0091
+  window; the role is only its provisioning source (ADR-0095 D3). The boundary is
+  pinned as a measured fact rather than left as an assumption.
+- 504c8d5: Materialize the RBAC catalog **per organization**, so a walled deployment can
+  administer positions, permission sets and sharing rules again (#10103).
+  
+  On a walled deployment (`group` / `isolated`) every principal — an organization
+  owner and a platform admin alike — listed **zero** positions, permission sets
+  and sharing rules while the tables held rows. Nothing could be bound through
+  Setup, and a declared `hierarchy-security` could never be armed by an operator
+  however loudly an app declared it.
+  
+  Every row in those three tables was organization-less. plugin-security's Layer 0
+  composes a strict `organization_id = :tenant` for a walled posture and the
+  middleware ANDs it into the read AST over the driver's
+  `(organization_id = :tenant OR organization_id IS NULL)`; the conjunction of the
+  two is the strict equality alone, so the driver's null arm was annihilated on
+  every authenticated read.
+  
+  **The wall is not changed, at either layer.** The rows get an owner instead:
+  
+  - `bootstrapDeclaredPositions`, `bootstrapBuiltinRoles`,
+    `bootstrapDeclaredPermissions` (plugin-security) and
+    `bootstrapDeclaredSharingRules` (plugin-sharing) upsert by
+    `(name, organization_id)` and run **one pass per organization** under a walled
+    posture — the framework built-ins (`platform_admin`, `org_*`, `everyone`,
+    `guest`) included, matching `sys_user_position`, which is already
+    per-organization, and matching both objects' own `unique: 'organization'` name
+    index.
+  - Seeding also fires on **organization creation**, not only at `kernel:ready`, so
+    a tenant created after startup does not administer an empty catalog until the
+    next restart.
+  - `single` posture is **unchanged**: exactly one organization-less pass, which is
+    the correct shape there.
+  
+  An organization-less row is now invalid state under a walled posture. Nothing is
+  reaped — grants (`sys_user_position`, `sys_position_permission_set`,
+  `sys_user_permission_set`, `sys_record_share`) point at these rows by id, so
+  deleting them would revoke standing access with no signal at the moment of loss.
+  Instead a per-organization pass that meets pre-fix organization-less rows for
+  names it seeds **says so loudly**, naming the rows and the remedy, and still
+  creates that organization's own copies. The failure this closes is the silent
+  no-op: a tenant-threaded pass that sees the old row through the driver's
+  compatibility arm, reads the name as already represented, and creates nothing
+  while reporting success.
+  
+  Two enforcement-plane reads are scoped in the same change, because the exposure
+  they carry only exists once per-organization copies exist:
+  
+  - `resolveUserAuthzContext`'s position name-sweep (`@objectstack/core`) resolved
+    `sys_position` by name across **every** organization, so the junction read
+    behind it collected another organization's `everyone` binding — a cross-organization
+    grant bleed, and an O(organizations) read on the per-request path. It is now
+    threaded through the driver's tenant chokepoint, keeping per-request resolution
+    O(the caller's own organization's catalog).
+  - plugin-security's permission-set `dbLoader` resolved sets by name unscoped,
+    with a `limit` equal to the number of names — correct while one row existed per
+    name, a truncation the moment copies exist. It is now scoped to the caller's
+    organization and its bound widened.
+  
+  Boot reconciliation is O(changed declarations): each pass reads what its
+  organization already has and writes only where a declaration actually differs, so
+  the common boot performs no writes at all. Steady state rides the
+  organization-creation hook.
+  
+  Cross-links #10119 / PR #10422, whose criteria-sweep scoping makes per-organization
+  sharing rules cheaper than the unscoped sweep they replace.
+- Updated dependencies [6936d07]
+- Updated dependencies [59eb04d]
+- Updated dependencies [9f05b7d]
+- Updated dependencies [7d2d112]
+- Updated dependencies [5fa0d72]
+- Updated dependencies [02b3b07]
+- Updated dependencies [914c413]
+- Updated dependencies [55809a0]
+- Updated dependencies [52db1d1]
+- Updated dependencies [5649efb]
+- Updated dependencies [2306a76]
+- Updated dependencies [e5ea701]
+- Updated dependencies [a40dcc1]
+- Updated dependencies [def0d3e]
+- Updated dependencies [8d0bb79]
+- Updated dependencies [5acb58d]
+- Updated dependencies [2e3cf95]
+- Updated dependencies [4c93387]
+- Updated dependencies [a037f7c]
+- Updated dependencies [3ee8ddf]
+- Updated dependencies [16cef97]
+- Updated dependencies [a79bd35]
+- Updated dependencies [6ceaa4b]
+- Updated dependencies [15ea214]
+- Updated dependencies [de19489]
+- Updated dependencies [c684d00]
+- Updated dependencies [923c424]
+- Updated dependencies [1ec36b7]
+- Updated dependencies [5f2e54c]
+- Updated dependencies [189373b]
+- Updated dependencies [35ad101]
+- Updated dependencies [ceb33a9]
+- Updated dependencies [73d9795]
+- Updated dependencies [8012960]
+- Updated dependencies [f34f56b]
+- Updated dependencies [f399618]
+- Updated dependencies [75e9301]
+- Updated dependencies [2810695]
+  - @objectstack/spec@17.2.0
+
 ## 17.1.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -1494,35 +1494,6 @@ function createMemoryQueue() {
   };
 }
 
-// src/fallbacks/memory-job.ts
-function createMemoryJob() {
-  const jobs = /* @__PURE__ */ new Map();
-  return {
-    __serviceInfo: {
-      status: "degraded",
-      handlerReady: false,
-      message: "In-process job registry \u2014 trigger() runs handlers, but scheduled jobs never fire on their own (no timer). Register a job plugin (e.g. Agenda) for real scheduling."
-    },
-    _serviceName: "job",
-    async schedule(name, schedule, handler) {
-      jobs.set(name, { schedule, handler });
-    },
-    async cancel(name) {
-      jobs.delete(name);
-    },
-    async trigger(name, data) {
-      const job = jobs.get(name);
-      if (job?.handler) await job.handler({ jobId: name, data });
-    },
-    async getExecutions() {
-      return [];
-    },
-    async listJobs() {
-      return [...jobs.keys()];
-    }
-  };
-}
-
 // src/fallbacks/memory-i18n.ts
 var import_system = require("@objectstack/spec/system");
 function deepMerge(target, source) {
@@ -1750,6 +1721,35 @@ function createMemoryMetadata() {
   };
 }
 
+// src/fallbacks/memory-job.ts
+function createMemoryJob() {
+  const jobs = /* @__PURE__ */ new Map();
+  return {
+    __serviceInfo: {
+      status: "degraded",
+      handlerReady: false,
+      message: "In-process job registry \u2014 trigger() runs handlers, but scheduled jobs never fire on their own (no timer). Register a job plugin (e.g. Agenda) for real scheduling."
+    },
+    _serviceName: "job",
+    async schedule(name, schedule, handler) {
+      jobs.set(name, { schedule, handler });
+    },
+    async cancel(name) {
+      jobs.delete(name);
+    },
+    async trigger(name, data) {
+      const job = jobs.get(name);
+      if (job?.handler) await job.handler({ jobId: name, data });
+    },
+    async getExecutions() {
+      return [];
+    },
+    async listJobs() {
+      return [...jobs.keys()];
+    }
+  };
+}
+
 // src/fallbacks/authored-translation-sync.ts
 var import_system2 = require("@objectstack/spec/system");
 var OWNER_PROP = "__authoredTranslationSyncOwner";
@@ -1882,7 +1882,6 @@ var CORE_FALLBACK_FACTORIES = {
   metadata: createMemoryMetadata,
   cache: createMemoryCache,
   queue: createMemoryQueue,
-  job: createMemoryJob,
   i18n: createMemoryI18n
 };
 
@@ -1906,6 +1905,48 @@ function registerPluginByName(registry, plugin, logger) {
   return previous;
 }
 
+// src/timeout-guard.ts
+var TimeoutGuard = class {
+  constructor(timeoutMs, createTimeoutError) {
+    /**
+     * Settles `expiry` without a value. `Promise<never>` has no resolvable
+     * value in the type system, but settling it is the entire point: it is
+     * only ever called from `reclaim()`, i.e. after the race it guarded has
+     * already been decided, so the resolution is discarded by construction and
+     * can never become a race winner. The cast localises that argument here
+     * rather than pushing a lie into every caller's return type.
+     */
+    this.settleExpiry = () => {
+    };
+    this.expiry = new Promise((resolve, reject) => {
+      this.settleExpiry = resolve;
+      this.timer = setTimeout(() => reject(createTimeoutError()), timeoutMs);
+    });
+  }
+  /**
+   * Reclaim the guard once the race it protects has been decided. Both
+   * halves, always: the timer is cleared so it cannot fire against a
+   * lifecycle phase that is already over, and `expiry` is settled so neither
+   * it nor the race's reaction on it is retained.
+   *
+   * Idempotent — `clearTimeout` on a cleared handle and a second resolve on
+   * a settled promise are both no-ops.
+   */
+  reclaim() {
+    clearTimeout(this.timer);
+    this.timer = void 0;
+    this.settleExpiry();
+  }
+};
+async function raceWithTimeout(operation, timeoutMs, createTimeoutError) {
+  const guard = new TimeoutGuard(timeoutMs, createTimeoutError);
+  try {
+    return await Promise.race([operation, guard.expiry]);
+  } finally {
+    guard.reclaim();
+  }
+}
+
 // src/kernel.ts
 var ObjectKernel = class {
   constructor(config = {}) {
@@ -2176,14 +2217,11 @@ var ObjectKernel = class {
     this.logger.info("Graceful shutdown started");
     const shutdownTimeoutError = new Error("Shutdown timeout exceeded");
     try {
-      const shutdownPromise = this.performShutdown();
-      const timeoutPromise = new Promise((_, reject) => {
-        const t = setTimeout(() => {
-          reject(shutdownTimeoutError);
-        }, this.config.shutdownTimeout);
-        if (t.unref) t.unref();
-      });
-      await Promise.race([shutdownPromise, timeoutPromise]);
+      await raceWithTimeout(
+        this.performShutdown(),
+        this.config.shutdownTimeout,
+        () => shutdownTimeoutError
+      );
       this.state = "stopped";
       this.logger.info("\u2705 Graceful shutdown complete");
     } catch (error) {
@@ -2301,25 +2339,17 @@ var ObjectKernel = class {
    * as well: if the hook never settles and nothing else keeps the loop alive,
    * Node exits before the timer can fire and the timeout is never reported.
    * The guard has to stay ref'd exactly as long as the race is undecided,
-   * which is what `clearTimeout` in a `finally` expresses.
+   * which is what clearing on settle expresses.
    *
-   * `operation` is widened to `T | PromiseLike<T>` because the Plugin
-   * contract permits a synchronous hook (`init`/`start` return
-   * `void | Promise<void>`); such a hook wins the race immediately and the
-   * guard is reclaimed on the same turn.
+   * Clearing the timer was only half of it, though (#10604): the promise the
+   * race still holds a reaction on has to SETTLE, or it and that reaction are
+   * retained past the end of the run — two leaking promises per boot, which
+   * is what `vitest --detectAsyncLeaks` names here. Both halves now live in
+   * `TimeoutGuard.reclaim()`, shared with `shutdown()`, so the two sites
+   * cannot drift into doing one half each again.
    */
   async raceStartupTimeout(operation, timeout, message) {
-    let guard;
-    const timeoutPromise = new Promise((_, reject) => {
-      guard = setTimeout(() => {
-        reject(new Error(message));
-      }, timeout);
-    });
-    try {
-      return await Promise.race([operation, timeoutPromise]);
-    } finally {
-      clearTimeout(guard);
-    }
+    return raceWithTimeout(operation, timeout, () => new Error(message));
   }
   /**
    * Whether a service is resolvable on this kernel right now — direct
@@ -4530,10 +4560,11 @@ function safeJsonParse2(s, fallback) {
     return fallback;
   }
 }
-async function tryFind(ql, object, where, limit = 100) {
+async function tryFind(ql, object, where, limit = 100, organizationId) {
   if (!ql || typeof ql.find !== "function") return [];
   try {
-    let rows = await ql.find(object, { where, limit, context: { isSystem: true } });
+    const context = organizationId ? { isSystem: true, tenantId: organizationId } : { isSystem: true };
+    let rows = await ql.find(object, { where, limit, context });
     if (rows && rows.value) rows = rows.value;
     return Array.isArray(rows) ? rows : [];
   } catch {
@@ -4631,12 +4662,19 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
     }
     return userRow;
   };
+  const needsUserRow = !grants.email || !grants.permissions.includes("ai_seat");
+  const [, members, userPositionRows, orgMembersLeg, upsRowsAll] = await Promise.all([
+    needsUserRow ? getUserRow() : Promise.resolve(void 0),
+    tryFind(ql, "sys_member", { user_id: userId }, 200),
+    tryFind(ql, "sys_user_position", { user_id: userId }, 200),
+    tenantId ? tryFind(ql, "sys_member", { organization_id: tenantId }, 1e3) : Promise.resolve([]),
+    tryFind(ql, "sys_user_permission_set", { user_id: userId }, 100)
+  ]);
   if (!grants.email) {
     const u = await getUserRow();
     if (u?.email) grants.email = String(u.email);
   }
   const nowMs = opts.nowMs ?? Date.now();
-  const members = await tryFind(ql, "sys_member", { user_id: userId }, 200);
   const accessibleOrgIds = /* @__PURE__ */ new Set();
   for (const m of members) {
     if (!isGrantActive(m, nowMs)) continue;
@@ -4644,7 +4682,9 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
     if (typeof org === "string" && org) accessibleOrgIds.add(org);
   }
   grants.accessible_org_ids = Array.from(accessibleOrgIds);
-  const activeMembers = tenantId ? members.filter((m) => (m.organization_id ?? m.organizationId) === tenantId) : members;
+  const activeMembers = members.filter(
+    (m) => isGrantActive(m, nowMs) && (!tenantId || (m.organization_id ?? m.organizationId) === tenantId)
+  );
   for (const m of activeMembers) {
     if (m.role && typeof m.role === "string") {
       for (const raw of m.role.split(",").map((s) => s.trim()).filter(Boolean)) {
@@ -4653,7 +4693,6 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
       }
     }
   }
-  const userPositionRows = await tryFind(ql, "sys_user_position", { user_id: userId }, 200);
   for (const ur of userPositionRows) {
     const org = ur.organization_id ?? null;
     if (org && tenantId && org !== tenantId) continue;
@@ -4662,14 +4701,13 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
     if (typeof r === "string" && r && !grants.positions.includes(r)) grants.positions.push(r);
   }
   if (tenantId) {
-    const orgMembers = await tryFind(ql, "sys_member", { organization_id: tenantId }, 1e3);
+    const orgMembers = orgMembersLeg;
     const ids = new Set(
       orgMembers.map((m) => m.user_id ?? m.userId).filter((v) => typeof v === "string" && v.length > 0)
     );
     ids.add(userId);
     grants.org_user_ids = Array.from(ids);
   }
-  const upsRowsAll = await tryFind(ql, "sys_user_permission_set", { user_id: userId }, 100);
   const upsRows = upsRowsAll.filter((r) => isGrantActive(r, nowMs));
   const psIds = new Set(
     upsRows.filter((r) => {
@@ -4683,7 +4721,7 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
   let hasPlatformAdminGrant = false;
   if (!grants.positions.includes("everyone")) grants.positions.push("everyone");
   if (grants.positions.length > 0) {
-    const positionRows = await tryFind(ql, "sys_position", { name: { $in: grants.positions } }, 100);
+    const positionRows = await tryFind(ql, "sys_position", { name: { $in: grants.positions } }, 200, tenantId);
     const deactivatedNames = new Set(
       positionRows.filter((r) => !isRowActive(r)).map((r) => r.name).filter(Boolean)
     );
@@ -4761,34 +4799,89 @@ function coerceCurrency(value) {
   const s = typeof value === "string" ? value.trim().toUpperCase() : "";
   return /^[A-Z]{3}$/.test(s) ? s : void 0;
 }
+var LOCALIZATION_FAILURE_CACHE_TTL_MS = 3e4;
+var localizationFailureCache = /* @__PURE__ */ new WeakMap();
 async function resolveLocalizationContext(input) {
+  const { ql, tenantId, userId } = input;
+  const cacheKey = `${tenantId ?? ""}|${userId ?? ""}`;
+  if (ql && typeof ql === "object") {
+    const hit = localizationFailureCache.get(ql)?.get(cacheKey);
+    if (hit && hit.expiresAt > Date.now()) return hit.value;
+  }
+  const { value, failed } = await resolveLocalizationContextUncached(input);
+  if (failed && ql && typeof ql === "object") {
+    const bucket = localizationFailureCache.get(ql) ?? /* @__PURE__ */ new Map();
+    bucket.set(cacheKey, { value, expiresAt: Date.now() + LOCALIZATION_FAILURE_CACHE_TTL_MS });
+    localizationFailureCache.set(ql, bucket);
+  }
+  return value;
+}
+async function resolveLocalizationContextUncached(input) {
   const { ql, settings, tenantId, userId } = input;
+  let failed = false;
   try {
     if (settings && typeof settings.get === "function") {
       const sctx = { tenantId, userId };
-      const [tzRes, localeRes, currencyRes] = await Promise.all([
-        settings.get("localization", "timezone", sctx).catch(() => void 0),
-        settings.get("localization", "locale", sctx).catch(() => void 0),
-        settings.get("localization", "currency", sctx).catch(() => void 0)
-      ]);
+      let tzRes;
+      let localeRes;
+      let currencyRes;
+      if (typeof settings.getMany === "function") {
+        try {
+          const many = await settings.getMany("localization", ["timezone", "locale", "currency"], sctx);
+          tzRes = many.timezone;
+          localeRes = many.locale;
+          currencyRes = many.currency;
+        } catch {
+          failed = true;
+        }
+      } else {
+        [tzRes, localeRes, currencyRes] = await Promise.all([
+          settings.get("localization", "timezone", sctx).catch(() => {
+            failed = true;
+            return void 0;
+          }),
+          settings.get("localization", "locale", sctx).catch(() => {
+            failed = true;
+            return void 0;
+          }),
+          settings.get("localization", "currency", sctx).catch(() => {
+            failed = true;
+            return void 0;
+          })
+        ]);
+      }
       const tz = coerceTimeZone(tzRes?.value);
       const locale = coerceLocale(localeRes?.value);
       const currency = coerceCurrency(currencyRes?.value);
-      if (tz || locale || currency) return { timezone: tz ?? "UTC", locale: locale ?? "en-US", currency };
+      if (tz || locale || currency) {
+        return { value: { timezone: tz ?? "UTC", locale: locale ?? "en-US", currency }, failed: false };
+      }
     }
   } catch {
+    failed = true;
+  }
+  let rows = [];
+  if (ql && typeof ql.find === "function") {
+    try {
+      let result = await ql.find("sys_setting", {
+        where: { namespace: "localization", key: { $in: ["timezone", "locale", "currency"] }, scope: "tenant" },
+        limit: 10,
+        context: { isSystem: true }
+      });
+      if (result && result.value) result = result.value;
+      rows = Array.isArray(result) ? result : [];
+    } catch {
+      failed = true;
+    }
   }
-  const rows = await tryFind(
-    ql,
-    "sys_setting",
-    { namespace: "localization", key: { $in: ["timezone", "locale", "currency"] }, scope: "tenant" },
-    10
-  );
   const valueOf = (k) => rows.find((r) => r.key === k)?.value;
   return {
-    timezone: coerceTimeZone(valueOf("timezone")) ?? "UTC",
-    locale: coerceLocale(valueOf("locale")) ?? "en-US",
-    currency: coerceCurrency(valueOf("currency"))
+    value: {
+      timezone: coerceTimeZone(valueOf("timezone")) ?? "UTC",
+      locale: coerceLocale(valueOf("locale")) ?? "en-US",
+      currency: coerceCurrency(valueOf("currency"))
+    },
+    failed
   };
 }