@objectstack/core 16.1.0 → 17.0.0-rc.1

package/dist/index.js

@@ -10,6 +10,89 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/plugin-order.ts
+function resolvePluginOrder(plugins) {
+  const resolved = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const visit = (pluginName) => {
+    if (visited.has(pluginName)) return;
+    if (visiting.has(pluginName)) {
+      throw new Error(`[Kernel] Circular dependency detected: ${pluginName}`);
+    }
+    const plugin = plugins.get(pluginName);
+    if (!plugin) {
+      throw new Error(`[Kernel] Plugin '${pluginName}' not found`);
+    }
+    visiting.add(pluginName);
+    for (const dep of plugin.dependencies ?? []) {
+      if (!plugins.has(dep)) {
+        throw new Error(
+          `[Kernel] Dependency '${dep}' not found for plugin '${pluginName}'`
+        );
+      }
+      visit(dep);
+    }
+    for (const dep of plugin.optionalDependencies ?? []) {
+      if (plugins.has(dep)) visit(dep);
+    }
+    visiting.delete(pluginName);
+    visited.add(pluginName);
+    resolved.push(plugin);
+  };
+  for (const pluginName of plugins.keys()) {
+    visit(pluginName);
+  }
+  return resolved;
+}
+function validateInitServiceContract(ordered, isServiceRegistered) {
+  const providerSlot = /* @__PURE__ */ new Map();
+  ordered.forEach((plugin, slot) => {
+    for (const service of plugin.providesServices ?? []) {
+      if (!providerSlot.has(service)) {
+        providerSlot.set(service, { plugin: plugin.name, slot });
+      }
+    }
+  });
+  const violations = [];
+  ordered.forEach((plugin, slot) => {
+    for (const service of plugin.requiresServices ?? []) {
+      if (isServiceRegistered(service)) continue;
+      const provider = providerSlot.get(service);
+      if (provider && provider.slot > slot) {
+        violations.push(
+          `'${plugin.name}' requires service '${service}' during init, but '${service}' is provided by '${provider.plugin}', which initializes later (slot ${provider.slot} vs ${slot}). Registration order is not a contract \u2014 declare '${provider.plugin}' in '${plugin.name}'.dependencies (hard) or .optionalDependencies (order-if-present) so the kernel hoists it.`
+        );
+      }
+    }
+  });
+  if (violations.length > 0) {
+    throw new Error(
+      `[Kernel] Plugin ordering contract violated (#4131):
+  - ${violations.join("\n  - ")}`
+    );
+  }
+}
+function describeInitOrderFault(currentlyInitializing, plugins, serviceName) {
+  if (!currentlyInitializing) return "";
+  let providerHint = "";
+  for (const plugin of plugins) {
+    if (plugin.providesServices?.includes(serviceName)) {
+      providerHint = ` '${serviceName}' is provided by composed plugin '${plugin.name}', which has not initialized yet \u2014 declare it in the requiring plugin's dependencies/optionalDependencies.`;
+      break;
+    }
+  }
+  return ` (while plugin '${currentlyInitializing}' was initializing \u2014 a composition/ordering fault, #4131.${providerHint})`;
+}
+function assertInitServiceRequirements(plugin, isServiceRegistered) {
+  for (const service of plugin.requiresServices ?? []) {
+    if (isServiceRegistered(service)) continue;
+    throw new Error(
+      `[Kernel] Plugin '${plugin.name}' requires service '${service}' at init, but no such service is registered at this point of the boot. No composed plugin that initializes earlier provides it \u2014 compose a provider (and, if it initializes later without declaring '${service}' in providesServices, order it ahead via this plugin's dependencies/optionalDependencies) (#4131).`
+    );
+  }
+}
+
 // src/kernel-base.ts
 var ObjectKernelBase = class {
   constructor(logger) {
@@ -60,7 +143,9 @@ var ObjectKernelBase = class {
         if (this.services instanceof Map) {
           const service = this.services.get(name);
           if (!service) {
-            throw new Error(`[Kernel] Service '${name}' not found`);
+            throw new Error(
+              `[Kernel] Service '${name}' not found${this.describeInitOrderFault(name)}`
+            );
           }
           return service;
         } else {
@@ -111,40 +196,37 @@ var ObjectKernelBase = class {
     };
   }
   /**
-   * Resolve plugin dependencies using topological sort
+   * Resolve plugin dependencies using topological sort — `dependencies`
+   * hard, `optionalDependencies` order-if-present (ADR-0116, #4131). One
+   * implementation shared with ObjectKernel via `plugin-order.ts`.
    * @returns Ordered list of plugins (dependencies first)
    */
   resolveDependencies() {
-    const resolved = [];
-    const visited = /* @__PURE__ */ new Set();
-    const visiting = /* @__PURE__ */ new Set();
-    const visit = (pluginName) => {
-      if (visited.has(pluginName)) return;
-      if (visiting.has(pluginName)) {
-        throw new Error(`[Kernel] Circular dependency detected: ${pluginName}`);
-      }
-      const plugin = this.plugins.get(pluginName);
-      if (!plugin) {
-        throw new Error(`[Kernel] Plugin '${pluginName}' not found`);
-      }
-      visiting.add(pluginName);
-      const deps = plugin.dependencies || [];
-      for (const dep of deps) {
-        if (!this.plugins.has(dep)) {
-          throw new Error(
-            `[Kernel] Dependency '${dep}' not found for plugin '${pluginName}'`
-          );
-        }
-        visit(dep);
-      }
-      visiting.delete(pluginName);
-      visited.add(pluginName);
-      resolved.push(plugin);
-    };
-    for (const pluginName of this.plugins.keys()) {
-      visit(pluginName);
-    }
-    return resolved;
+    return resolvePluginOrder(this.plugins);
+  }
+  /**
+   * Whether a service is registered on this kernel right now. Backs the
+   * init-service contract checks (#4131).
+   */
+  hasRegisteredService(name) {
+    return this.services.has(name);
+  }
+  /**
+   * Pre-Phase-1 ordering validation (ADR-0116, #4131): a plugin whose
+   * `requiresServices` names a service provided only by a LATER plugin is
+   * a named boot error before any init side effects.
+   */
+  validateInitServices(ordered) {
+    validateInitServiceContract(ordered, (name) => this.hasRegisteredService(name));
+  }
+  /**
+   * When a getService miss happens while a plugin's init() is running,
+   * append the structural diagnosis (#4131): which plugin was initializing,
+   * and — when a composed plugin declares the service — who provides it.
+   * Empty string outside Phase 1, so non-boot messages stay unchanged.
+   */
+  describeInitOrderFault(serviceName) {
+    return describeInitOrderFault(this.currentlyInitializing, this.plugins.values(), serviceName);
   }
   /**
    * Run plugin init phase
@@ -153,12 +235,16 @@ var ObjectKernelBase = class {
   async runPluginInit(plugin) {
     const pluginName = plugin.name;
     this.logger.info(`Initializing plugin: ${pluginName}`);
+    assertInitServiceRequirements(plugin, (name) => this.hasRegisteredService(name));
+    this.currentlyInitializing = pluginName;
     try {
       await plugin.init(this.context);
       this.logger.info(`Plugin initialized: ${pluginName}`);
     } catch (error) {
       this.logger.error(`Plugin init failed: ${pluginName}`, error);
       throw error;
+    } finally {
+      this.currentlyInitializing = void 0;
     }
   }
   /**
@@ -1011,7 +1097,11 @@ function createMemoryCache() {
   let hits = 0;
   let misses = 0;
   return {
-    _fallback: true,
+    __serviceInfo: {
+      status: "degraded",
+      handlerReady: false,
+      message: "In-process Map cache \u2014 not shared across instances, lost on restart. Register a cache plugin (e.g. Redis) for a real one."
+    },
     _serviceName: "cache",
     async get(key) {
       const entry = store.get(key);
@@ -1046,7 +1136,11 @@ function createMemoryQueue() {
   const handlers = /* @__PURE__ */ new Map();
   let msgId = 0;
   return {
-    _fallback: true,
+    __serviceInfo: {
+      status: "degraded",
+      handlerReady: false,
+      message: "Synchronous in-process delivery \u2014 no durability, retry, or cross-instance fan-out. Register a queue plugin (e.g. BullMQ) for a real one."
+    },
     _serviceName: "queue",
     async publish(queue, data) {
       const id = `fallback-msg-${++msgId}`;
@@ -1073,7 +1167,11 @@ function createMemoryQueue() {
 function createMemoryJob() {
   const jobs = /* @__PURE__ */ new Map();
   return {
-    _fallback: true,
+    __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 });
@@ -1152,7 +1250,15 @@ function createMemoryI18n() {
     return void 0;
   }
   return {
-    _fallback: true,
+    // [#4058] `degraded` (ADR-0076 D12): translations, locale fallback and
+    // interpolation are all real — what is missing is persistence and the
+    // authoring surface service-i18n adds. `handlerReady` left at the
+    // `degraded` default (true): the dispatcher's `/i18n` domain does serve
+    // this implementation.
+    __serviceInfo: {
+      status: "degraded",
+      message: "In-memory translations \u2014 real lookup and locale fallback, but nothing is persisted. Register I18nServicePlugin from @objectstack/service-i18n for the full implementation."
+    },
     _serviceName: "i18n",
     t(key, locale, params) {
       const data = resolveTranslations(locale) ?? mergedLocale(defaultLocale);
@@ -1209,7 +1315,14 @@ function createMemoryMetadata() {
     return map;
   }
   return {
-    _fallback: true,
+    // [#4058] `degraded` (ADR-0076 D12): the registry is real — everything
+    // registered is listable and readable back — it simply never reaches disk
+    // or a database. `handlerReady` keeps the `degraded` default (true): the
+    // dispatcher's `/meta` domain serves this implementation.
+    __serviceInfo: {
+      status: "degraded",
+      message: "In-memory metadata registry \u2014 real reads and writes, no persistence (lost on restart). Register MetadataPlugin for a persisted registry."
+    },
     _serviceName: "metadata",
     async register(type, name, data) {
       getTypeMap(type).set(name, data);
@@ -1252,6 +1365,7 @@ function createMemoryMetadata() {
 }
 
 // src/fallbacks/authored-translation-sync.ts
+import { LEGACY_OBJECT_FIRST_KEYS } from "@objectstack/spec/system";
 var OWNER_PROP = "__authoredTranslationSyncOwner";
 var LOCALE_LIKE = /^[a-z]{2,3}([_-]([A-Za-z]{4}|[A-Za-z]{2}|[0-9]{3}))?$/;
 async function readAuthoredTranslationLayer(engine, logger) {
@@ -1281,14 +1395,32 @@ async function readAuthoredTranslationLayer(engine, logger) {
       continue;
     }
     if (!data || typeof data !== "object") continue;
-    const locale = typeof data?._meta?.locale === "string" && data._meta.locale || typeof data?.locale === "string" && data.locale || (typeof row?.name === "string" && LOCALE_LIKE.test(row.name) ? row.name : void 0) || void 0;
+    const legacyKeys = LEGACY_OBJECT_FIRST_KEYS.filter((key) => data[key] !== void 0);
+    if (legacyKeys.length > 0) {
+      logger?.warn?.(
+        `[i18n] authored translation '${row?.name}' uses the retired object-first shape (${legacyKeys.join(", ")}) \u2014 nothing resolves from it; re-author it under 'objects.<object_name>' with a top-level 'locale' \u2014 skipped`
+      );
+      continue;
+    }
+    const locale = typeof data?.locale === "string" && data.locale || (typeof row?.name === "string" && LOCALE_LIKE.test(row.name) ? row.name : void 0) || void 0;
     if (!locale) {
       logger?.warn?.(
-        `[i18n] authored translation '${row?.name}' has no resolvable locale (set _meta.locale, or name the item after its BCP-47 locale) \u2014 skipped`
+        `[i18n] authored translation '${row?.name}' has no resolvable locale (set the top-level 'locale', or name the item after its BCP-47 locale) \u2014 skipped`
       );
       continue;
     }
-    const { name: _n, locale: _l, _packageId: _p, _provenance: _pr, _lock: _lk, ...payload } = data;
+    const {
+      name: _n,
+      locale: _l,
+      _packageId: _p,
+      _packageVersion: _pv,
+      _provenance: _pr,
+      _lock: _lk,
+      _lockReason: _lr,
+      _lockDocsUrl: _ld,
+      _lockSource: _ls,
+      ...payload
+    } = data;
     byLocale[locale] = deepMerge(byLocale[locale] ?? {}, payload);
   }
   return byLocale;
@@ -1406,24 +1538,12 @@ var ObjectKernel = class {
           this.services.set(name, loaderService);
           return loaderService;
         }
-        try {
-          const service2 = this.pluginLoader.getService(name);
-          if (service2 instanceof Promise) {
-            service2.catch(() => {
-            });
-            throw new Error(`Service '${name}' is async - use await`);
-          }
-          return service2;
-        } catch (error) {
-          if (error.message?.includes("is async")) {
-            throw error;
-          }
-          const isNotFoundError = error.message === `Service '${name}' not found`;
-          if (!isNotFoundError) {
-            throw error;
-          }
-          throw new Error(`[Kernel] Service '${name}' not found`);
+        if (!this.pluginLoader.hasService(name)) {
+          throw new Error(
+            `[Kernel] Service '${name}' not found${this.describeInitOrderFault(name)}`
+          );
         }
+        throw new Error(`Service '${name}' is async - use await`);
       },
       replaceService: (name, implementation) => {
         const hasService = this.services.has(name) || this.pluginLoader.hasService(name);
@@ -1582,6 +1702,7 @@ var ObjectKernel = class {
         this.logger.warn("Circular service dependencies detected:", { cycles });
       }
       const orderedPlugins = this.resolveDependencies();
+      validateInitServiceContract(orderedPlugins, (name) => this.hasAnyService(name));
       this.logger.info("Phase 1: Init plugins");
       for (const plugin of orderedPlugins) {
         await this.initPluginWithTimeout(plugin);
@@ -1727,13 +1848,36 @@ var ObjectKernel = class {
   async initPluginWithTimeout(plugin) {
     const timeout = plugin.startupTimeout || this.config.defaultStartupTimeout;
     this.logger.debug(`Init: ${plugin.name}`, { plugin: plugin.name });
-    const initPromise = plugin.init(this.context);
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => {
-        reject(new Error(`Plugin ${plugin.name} init timeout after ${timeout}ms`));
-      }, timeout);
-    });
-    await Promise.race([initPromise, timeoutPromise]);
+    assertInitServiceRequirements(plugin, (name) => this.hasAnyService(name));
+    this.currentlyInitializing = plugin.name;
+    try {
+      const initPromise = plugin.init(this.context);
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`Plugin ${plugin.name} init timeout after ${timeout}ms`));
+        }, timeout);
+      });
+      await Promise.race([initPromise, timeoutPromise]);
+    } finally {
+      this.currentlyInitializing = void 0;
+    }
+  }
+  /**
+   * Whether a service is resolvable on this kernel right now — direct
+   * registration or a loader-registered factory. Backs the init-service
+   * contract checks (#4131).
+   */
+  hasAnyService(name) {
+    return this.services.has(name) || this.pluginLoader.hasService(name);
+  }
+  /**
+   * When a getService miss happens while a plugin's init() is running,
+   * append the structural diagnosis (#4131): which plugin was initializing,
+   * and — when a composed plugin declares the service — who provides it.
+   * Empty string outside Phase 1, so non-boot messages stay unchanged.
+   */
+  describeInitOrderFault(serviceName) {
+    return describeInitOrderFault(this.currentlyInitializing, this.plugins.values(), serviceName);
   }
   async startPluginWithTimeout(plugin) {
     if (!plugin.start) {
@@ -1807,35 +1951,13 @@ var ObjectKernel = class {
       }
     }
   }
+  /**
+   * Topological order over `dependencies` (hard) + `optionalDependencies`
+   * (order-if-present) — ADR-0116, #4131. One implementation shared with
+   * LiteKernel via `plugin-order.ts`.
+   */
   resolveDependencies() {
-    const resolved = [];
-    const visited = /* @__PURE__ */ new Set();
-    const visiting = /* @__PURE__ */ new Set();
-    const visit = (pluginName) => {
-      if (visited.has(pluginName)) return;
-      if (visiting.has(pluginName)) {
-        throw new Error(`[Kernel] Circular dependency detected: ${pluginName}`);
-      }
-      const plugin = this.plugins.get(pluginName);
-      if (!plugin) {
-        throw new Error(`[Kernel] Plugin '${pluginName}' not found`);
-      }
-      visiting.add(pluginName);
-      const deps = plugin.dependencies || [];
-      for (const dep of deps) {
-        if (!this.plugins.has(dep)) {
-          throw new Error(`[Kernel] Dependency '${dep}' not found for plugin '${pluginName}'`);
-        }
-        visit(dep);
-      }
-      visiting.delete(pluginName);
-      visited.add(pluginName);
-      resolved.push(plugin);
-    };
-    for (const pluginName of this.plugins.keys()) {
-      visit(pluginName);
-    }
-    return resolved;
+    return resolvePluginOrder(this.plugins);
   }
   registerShutdownSignals() {
     const signals = ["SIGINT", "SIGTERM", "SIGQUIT"];
@@ -1901,6 +2023,7 @@ var LiteKernel = class extends ObjectKernelBase {
     this.state = "initializing";
     this.logger.info("Bootstrap started");
     const orderedPlugins = this.resolveDependencies();
+    this.validateInitServices(orderedPlugins);
     this.logger.info("Phase 1: Init plugins");
     for (const plugin of orderedPlugins) {
       await this.runPluginInit(plugin);
@@ -2501,6 +2624,11 @@ function createApiRegistryPlugin(config = {}) {
   } = config;
   return {
     name: "com.objectstack.core.api-registry",
+    /**
+     * Services init() registers on every path (ADR-0116, #4131) — lets the
+     * kernel name this plugin when a consumer requires one before it inits.
+     */
+    providesServices: ["api-registry"],
     type: "standard",
     version: "1.0.0",
     init: async (ctx) => {
@@ -4212,7 +4340,7 @@ import {
   mapMembershipRole,
   BUILTIN_IDENTITY_PLATFORM_ADMIN,
   ADMIN_FULL_ACCESS,
-  ORGANIZATION_ADMIN
+  ORGANIZATION_ADMIN_GRANTS
 } from "@objectstack/spec";
 
 // src/security/grant-validity.ts
@@ -4320,7 +4448,8 @@ async function resolveAuthzContext(input) {
     positions: [],
     permissions: [],
     systemPermissions: [],
-    org_user_ids: []
+    org_user_ids: [],
+    accessible_org_ids: []
   };
   let userId;
   let tenantId;
@@ -4356,6 +4485,7 @@ async function resolveAuthzContext(input) {
   ctx.permissions = grants.permissions;
   ctx.systemPermissions = grants.systemPermissions;
   ctx.org_user_ids = grants.org_user_ids;
+  ctx.accessible_org_ids = grants.accessible_org_ids;
   if (grants.tabPermissions) ctx.tabPermissions = grants.tabPermissions;
   if (grants.posture) ctx.posture = grants.posture;
   if (grants.email && !ctx.email) ctx.email = grants.email;
@@ -4367,7 +4497,8 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
     positions: [],
     permissions: Array.isArray(opts.seedPermissions) ? [...opts.seedPermissions] : [],
     systemPermissions: [],
-    org_user_ids: [userId]
+    org_user_ids: [userId],
+    accessible_org_ids: []
   };
   if (opts.seedEmail) grants.email = opts.seedEmail;
   if (!ql || typeof ql.find !== "function") return grants;
@@ -4385,9 +4516,17 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
     const u = await getUserRow();
     if (u?.email) grants.email = String(u.email);
   }
-  const memberWhere = tenantId ? { user_id: userId, organization_id: tenantId } : { user_id: userId };
-  const members = await tryFind(ql, "sys_member", memberWhere, 50);
+  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;
+    const org = m.organization_id ?? m.organizationId;
+    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;
+  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)) {
         const r = mapMembershipRole(raw);
@@ -4395,7 +4534,6 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
       }
     }
   }
-  const nowMs = opts.nowMs ?? Date.now();
   const userPositionRows = await tryFind(ql, "sys_user_position", { user_id: userId }, 200);
   for (const ur of userPositionRows) {
     const org = ur.organization_id ?? null;
@@ -4467,7 +4605,9 @@ async function resolveUserAuthzGrants(ql, userId, opts = {}) {
   }
   grants.posture = derivePosture({
     isPlatformAdmin: hasPlatformAdminGrant,
-    isTenantAdmin: grants.permissions.includes(ORGANIZATION_ADMIN)
+    // [ADR-0105 D4] Either org-admin capability set resolves the rung — the
+    // wall-less variant differs only by withholding the superuser bits.
+    isTenantAdmin: ORGANIZATION_ADMIN_GRANTS.some((n) => grants.permissions.includes(n))
   });
   if (!grants.permissions.includes("ai_seat")) {
     const aiAccess = (await getUserRow())?.ai_access;
@@ -4556,14 +4696,13 @@ function evaluateAuthGate(sessionUser, path) {
 
 // src/security/anonymous-deny.ts
 var ANONYMOUS_DENY_STATUS = 401;
-var ANONYMOUS_DENY_CODE = "unauthenticated";
+var ANONYMOUS_DENY_CODE = "UNAUTHENTICATED";
 var ANONYMOUS_DENY_MESSAGE = "Authentication is required to access this endpoint.";
 var ANONYMOUS_DENY_BODY = {
   error: ANONYMOUS_DENY_CODE,
   message: ANONYMOUS_DENY_MESSAGE
 };
 function shouldDenyAnonymous(input) {
-  if (!input.requireAuth) return false;
   if (typeof input.method === "string" && input.method.toUpperCase() === "OPTIONS") {
     return false;
   }
@@ -4575,6 +4714,7 @@ function shouldDenyAnonymous(input) {
 }
 
 // src/utils/datetime.ts
+import { nextUtcCalendarDay, utcInstantMs } from "@objectstack/spec/data";
 function calendarPartsInTz(d, tz) {
   const parts = new Intl.DateTimeFormat("en-US", {
     timeZone: tz,
@@ -4598,8 +4738,8 @@ function calendarPartsInTzOrUtc(d, tz) {
     day: d.getUTCDate()
   };
 }
-function zonedDateStartToUtcMs(ymd, tz) {
-  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(ymd);
+function zonedDateStartToUtcMs(ymd2, tz) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(ymd2);
   const wallAsUtc = m ? Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])) : NaN;
   if (!tz || tz === "UTC" || Number.isNaN(wallAsUtc)) return wallAsUtc;
   try {
@@ -4815,6 +4955,212 @@ async function bulkWrite(rows, opts) {
   return results;
 }
 
+// src/utils/filter-tokens.ts
+import {
+  classifyFilterToken,
+  parseDateMacroParam
+} from "@objectstack/spec/data";
+var UnknownFilterTokenError = class extends Error {
+  constructor(token, suggestion) {
+    super(
+      `Unresolvable filter placeholder "{${token}}". ` + (suggestion ? `Did you mean "{${suggestion}}"? ` : "Resolvable placeholders are the context tokens ({current_user_id}, {current_org_id}) and the date macros ({today}, {current_quarter_start}, {30_days_ago}, \u2026). ") + "Sending it to the data engine verbatim would compare it as a literal string and match nothing, which is indistinguishable from an empty result."
+    );
+    this.status = 400;
+    this.code = "FILTER_TOKEN_UNKNOWN";
+    this.name = "UnknownFilterTokenError";
+    this.token = token;
+    this.suggestion = suggestion;
+  }
+};
+var UnresolvedFilterTokenError = class extends Error {
+  constructor(token, detail) {
+    super(`Filter placeholder "{${token}}" cannot be resolved: ${detail}`);
+    /** 400, not 500 — see {@link UnknownFilterTokenError}. */
+    this.status = 400;
+    this.code = "FILTER_TOKEN_UNRESOLVED";
+    this.name = "UnresolvedFilterTokenError";
+    this.token = token;
+  }
+};
+function ymd(year, month, day) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${year}-${p(month)}-${p(day)}`;
+}
+function proxyDay(now, timezone) {
+  const { year, month, day } = calendarPartsInTzOrUtc(now, timezone);
+  return new Date(Date.UTC(year, month - 1, day));
+}
+var asYmd = (d) => ymd(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
+function startOfPeriod(kind, d) {
+  const r = new Date(d.getTime());
+  switch (kind) {
+    case "week": {
+      const dow = (r.getUTCDay() + 6) % 7;
+      r.setUTCDate(r.getUTCDate() - dow);
+      return r;
+    }
+    case "month":
+      return new Date(Date.UTC(r.getUTCFullYear(), r.getUTCMonth(), 1));
+    case "quarter":
+      return new Date(Date.UTC(r.getUTCFullYear(), Math.floor(r.getUTCMonth() / 3) * 3, 1));
+    case "year":
+      return new Date(Date.UTC(r.getUTCFullYear(), 0, 1));
+  }
+}
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+function addMonthsClamped(d, n) {
+  const year = d.getUTCFullYear();
+  const month = d.getUTCMonth() + n;
+  const targetYear = year + Math.floor(month / 12);
+  const targetMonth = (month % 12 + 12) % 12;
+  const day = Math.min(d.getUTCDate(), daysInMonth(targetYear, targetMonth));
+  return new Date(Date.UTC(
+    targetYear,
+    targetMonth,
+    day,
+    d.getUTCHours(),
+    d.getUTCMinutes(),
+    d.getUTCSeconds(),
+    d.getUTCMilliseconds()
+  ));
+}
+function addPeriods(kind, d, n) {
+  switch (kind) {
+    case "week": {
+      const r = new Date(d.getTime());
+      r.setUTCDate(r.getUTCDate() + n * 7);
+      return r;
+    }
+    case "month":
+      return addMonthsClamped(d, n);
+    case "quarter":
+      return addMonthsClamped(d, n * 3);
+    case "year":
+      return addMonthsClamped(d, n * 12);
+  }
+}
+function addUnits(unit, d, n) {
+  const r = new Date(d.getTime());
+  switch (unit) {
+    case "minute":
+      r.setUTCMinutes(r.getUTCMinutes() + n);
+      return r;
+    case "hour":
+      r.setUTCHours(r.getUTCHours() + n);
+      return r;
+    case "day":
+      r.setUTCDate(r.getUTCDate() + n);
+      return r;
+    case "week":
+      r.setUTCDate(r.getUTCDate() + n * 7);
+      return r;
+    // Month/year steps clamp rather than overflow — see addMonthsClamped.
+    case "month":
+      return addMonthsClamped(d, n);
+    case "year":
+      return addMonthsClamped(d, n * 12);
+  }
+}
+var PERIOD_RE = /^(?:(current|last|next)_)?(week|month|quarter|year)_(start|end)$/;
+function resolvePeriodToken(token, today) {
+  const m = PERIOD_RE.exec(token);
+  if (!m) return void 0;
+  const rel = m[1] ?? "current";
+  const kind = m[2];
+  const bound = m[3];
+  const offset = rel === "last" ? -1 : rel === "next" ? 1 : 0;
+  const periodStart = startOfPeriod(kind, addPeriods(kind, startOfPeriod(kind, today), offset));
+  if (bound === "start") return asYmd(periodStart);
+  const next = addPeriods(kind, periodStart, 1);
+  next.setUTCDate(next.getUTCDate() - 1);
+  return asYmd(next);
+}
+function resolveFilterToken(token, ctx = {}) {
+  const now = ctx.now ?? /* @__PURE__ */ new Date();
+  if (token === "current_user_id") {
+    if (!ctx.userId) {
+      throw new UnresolvedFilterTokenError(
+        token,
+        "the request has no authenticated user. A filter scoped to the signed-in user cannot run for an anonymous or system caller \u2014 gate the surface on authentication, or drop the token from the filter."
+      );
+    }
+    return ctx.userId;
+  }
+  if (token === "current_org_id") {
+    if (!ctx.orgId) {
+      throw new UnresolvedFilterTokenError(
+        token,
+        "the request carries no active organization (ExecutionContext.tenantId is unset). Set the active org on the request, or drop the token from the filter."
+      );
+    }
+    return ctx.orgId;
+  }
+  const today = proxyDay(now, ctx.timezone);
+  switch (token) {
+    case "now":
+      return now.toISOString();
+    case "today":
+      return asYmd(today);
+    case "yesterday":
+      return asYmd(addUnits("day", today, -1));
+    case "tomorrow":
+      return asYmd(addUnits("day", today, 1));
+  }
+  const period = resolvePeriodToken(token, today);
+  if (period !== void 0) return period;
+  const param = parseDateMacroParam(token);
+  if (param) {
+    const sign = param.direction === "ago" ? -1 : 1;
+    if (param.unit === "minute" || param.unit === "hour") {
+      return addUnits(param.unit, now, sign * param.n).toISOString();
+    }
+    return asYmd(addUnits(param.unit, today, sign * param.n));
+  }
+  return void 0;
+}
+function hasFilterToken(node) {
+  if (typeof node === "string") return classifyFilterToken(node) !== null;
+  if (Array.isArray(node)) return node.some(hasFilterToken);
+  if (node && typeof node === "object" && !(node instanceof Date)) {
+    return Object.values(node).some(hasFilterToken);
+  }
+  return false;
+}
+function resolveFilterTokens(filter, ctx = {}) {
+  if (filter == null) return filter;
+  if (!hasFilterToken(filter)) return filter;
+  const pinned = { ...ctx, now: ctx.now ?? /* @__PURE__ */ new Date() };
+  const walk = (node) => {
+    if (typeof node === "string") {
+      const cls = classifyFilterToken(node);
+      if (!cls) return node;
+      if (cls.kind === "unknown") throw new UnknownFilterTokenError(cls.token, cls.suggestion);
+      const resolved = resolveFilterToken(cls.token, pinned);
+      if (resolved === void 0) throw new UnknownFilterTokenError(cls.token);
+      return resolved;
+    }
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === "object") {
+      if (node instanceof Date) return node;
+      const out = {};
+      for (const [k, v] of Object.entries(node)) out[k] = walk(v);
+      return out;
+    }
+    return node;
+  };
+  return walk(filter);
+}
+function filterTokenContextFrom(execCtx, now) {
+  return {
+    now,
+    timezone: execCtx?.timezone,
+    userId: execCtx?.userId,
+    orgId: execCtx?.tenantId
+  };
+}
+
 // src/health-monitor.ts
 var PluginHealthMonitor = class {
   constructor(logger) {
@@ -5759,6 +6105,9 @@ export {
   SecurePluginContext,
   SemanticVersionManager,
   ServiceLifecycle,
+  UnknownFilterTokenError,
+  UnresolvedFilterTokenError,
+  assertInitServiceRequirements,
   bucketKeyToCalendarRange,
   buildPermissionsFromGrants,
   bulkWrite,
@@ -5777,8 +6126,10 @@ export {
   deepMerge,
   defaultIsTransientError,
   derivePosture,
+  describeInitOrderFault,
   evaluateAuthGate,
   extractApiKey,
+  filterTokenContextFrom,
   generateApiKey,
   generateEd25519KeyPair,
   getEnv,
@@ -5789,18 +6140,24 @@ export {
   isGrantActive,
   isGrantExpired,
   isNode,
+  nextUtcCalendarDay,
   parseScopes,
   parseSignature,
   postureVisibleRows,
   readAuthoredTranslationLayer,
   resolveApiKeyPrincipal,
   resolveAuthzContext,
+  resolveFilterToken,
+  resolveFilterTokens,
   resolveLocale,
   resolveLocalizationContext,
+  resolvePluginOrder,
   resolveUserAuthzGrants,
   safeExit,
   shouldDenyAnonymous,
   signPayload,
+  utcInstantMs,
+  validateInitServiceContract,
   verifyPayload,
   verifyPlatformSignature,
   verifyPluginArtifact,