@objectstack/runtime 10.3.0 → 11.1.0

package/dist/index.cjs

@@ -1278,7 +1278,7 @@ var init_app_plugin = __esm({
             } catch (e) {
               ctx.logger.warn("[Seeder] Failed to register seed-datasets/seed-replayer service", { error: e?.message });
             }
-            const multiTenant = String((0, import_types.readEnvWithDeprecation)("OS_MULTI_ORG_ENABLED", "OS_MULTI_TENANT") ?? "false").toLowerCase() !== "false";
+            const multiTenant = (0, import_types.resolveMultiOrgEnabled)();
             if (multiTenant) {
               ctx.logger.info("[Seeder] multi-tenant mode \u2014 skipping inline seed; per-org replay will run on sys_organization insert");
             } else {
@@ -1575,7 +1575,7 @@ async function createStandaloneStack(config) {
   const environmentId = cfg.environmentId ?? process.env.OS_ENVIRONMENT_ID ?? "proj_local";
   const artifactPathInput = cfg.artifactPath ?? process.env.OS_ARTIFACT_PATH ?? (0, import_node_path3.resolve)(cwd, "dist/objectstack.json");
   const artifactPath = isHttpUrl(artifactPathInput) ? artifactPathInput : artifactPathInput.startsWith("/") ? artifactPathInput : (0, import_node_path3.resolve)(cwd, artifactPathInput);
-  const dbUrl = cfg.databaseUrl ?? (0, import_types2.readEnvWithDeprecation)("OS_DATABASE_URL", "DATABASE_URL")?.trim() ?? process.env.TURSO_DATABASE_URL?.trim() ?? (process.env.OS_HOME?.trim() ? `file:${(0, import_node_path3.resolve)(resolveObjectStackHome(), "data/standalone.db")}` : cfg.projectRoot ? `file:${(0, import_node_path3.resolve)(cfg.projectRoot, ".objectstack/data/standalone.db")}` : `file:${(0, import_node_path3.resolve)(resolveObjectStackHome(), "data/standalone.db")}`);
+  const dbUrl = cfg.databaseUrl ?? (0, import_types2.readEnvWithDeprecation)("OS_DATABASE_URL", "DATABASE_URL", { silent: true })?.trim() ?? process.env.TURSO_DATABASE_URL?.trim() ?? (process.env.OS_HOME?.trim() ? `file:${(0, import_node_path3.resolve)(resolveObjectStackHome(), "data/standalone.db")}` : cfg.projectRoot ? `file:${(0, import_node_path3.resolve)(cfg.projectRoot, ".objectstack/data/standalone.db")}` : `file:${(0, import_node_path3.resolve)(resolveObjectStackHome(), "data/standalone.db")}`);
   const explicitDriver = cfg.databaseDriver ?? process.env.OS_DATABASE_DRIVER?.trim();
   const dbDriver = explicitDriver ?? detectDriverFromUrl(dbUrl);
   let driverPlugin;
@@ -1736,7 +1736,7 @@ __export(index_exports, {
   NoopMetricsRegistry: () => import_observability.NoopMetricsRegistry,
   OBSERVABILITY_ERRORS_SERVICE: () => import_observability3.OBSERVABILITY_ERRORS_SERVICE,
   OBSERVABILITY_METRICS_SERVICE: () => import_observability3.OBSERVABILITY_METRICS_SERVICE,
-  ObjectKernel: () => import_core4.ObjectKernel,
+  ObjectKernel: () => import_core5.ObjectKernel,
   ObservabilityServicePlugin: () => ObservabilityServicePlugin,
   QuickJSScriptRunner: () => QuickJSScriptRunner,
   RUNTIME_METRICS: () => import_observability.RUNTIME_METRICS,
@@ -1778,7 +1778,7 @@ __export(index_exports, {
   resolveRequestId: () => resolveRequestId
 });
 module.exports = __toCommonJS(index_exports);
-var import_core4 = require("@objectstack/core");
+var import_core5 = require("@objectstack/core");
 
 // src/runtime.ts
 var import_core = require("@objectstack/core");
@@ -2050,7 +2050,7 @@ function safeGet(ctx, name) {
 }
 
 // src/http-dispatcher.ts
-var import_core3 = require("@objectstack/core");
+var import_core4 = require("@objectstack/core");
 var import_system = require("@objectstack/spec/system");
 var import_shared2 = require("@objectstack/spec/shared");
 init_package_state_store();
@@ -2084,10 +2084,8 @@ function checkApiExposure(def, action) {
   return { allowed: true };
 }
 
-// src/security/api-key.ts
-var import_core2 = require("@objectstack/core");
-
 // src/security/resolve-execution-context.ts
+var import_core2 = require("@objectstack/core");
 function toHeaders(input) {
   if (!input) return new Headers();
   if (typeof Headers !== "undefined" && input instanceof Headers) return input;
@@ -2103,212 +2101,44 @@ function toHeaders(input) {
   }
   return h;
 }
-function safeJsonParse2(s, fallback) {
-  try {
-    return JSON.parse(s);
-  } catch {
-    return fallback;
-  }
-}
-async function tryFind(ql, object, where, limit = 100) {
-  if (!ql || typeof ql.find !== "function") return [];
-  try {
-    let rows = await ql.find(object, { where, limit, context: { isSystem: true } });
-    if (rows && rows.value) rows = rows.value;
-    return Array.isArray(rows) ? rows : [];
-  } catch {
-    return [];
-  }
-}
-function isValidTimeZone(tz) {
-  try {
-    new Intl.DateTimeFormat("en-US", { timeZone: tz });
-    return true;
-  } catch {
-    return false;
-  }
-}
-function coerceTimeZone(value) {
-  const s = typeof value === "string" ? value.trim() : value != null ? String(value).trim() : "";
-  return s && isValidTimeZone(s) ? s : void 0;
-}
-function coerceLocale(value) {
-  const s = typeof value === "string" ? value.trim() : value != null ? String(value).trim() : "";
-  return s || void 0;
-}
-function coerceCurrency(value) {
-  const s = typeof value === "string" ? value.trim().toUpperCase() : "";
-  return /^[A-Z]{3}$/.test(s) ? s : void 0;
-}
-async function resolveLocalization(opts, ql, sctx) {
-  try {
-    const settings = await opts.getService("settings");
-    if (settings && typeof settings.get === "function") {
-      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)
-      ]);
-      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 };
-    }
-  } catch {
-  }
-  const tzRows = await tryFind(ql, "sys_setting", { namespace: "localization", key: "timezone", scope: "tenant" }, 1);
-  const localeRows = await tryFind(ql, "sys_setting", { namespace: "localization", key: "locale", scope: "tenant" }, 1);
-  const currencyRows = await tryFind(ql, "sys_setting", { namespace: "localization", key: "currency", scope: "tenant" }, 1);
-  return {
-    timezone: coerceTimeZone(tzRows[0]?.value) ?? "UTC",
-    locale: coerceLocale(localeRows[0]?.value) ?? "en-US",
-    currency: coerceCurrency(currencyRows[0]?.value)
-  };
-}
 async function resolveExecutionContext(opts) {
-  const headers = opts.request?.headers;
-  const ctx = {
-    roles: [],
-    permissions: [],
-    systemPermissions: [],
-    isSystem: false
-  };
-  let userId;
-  let tenantId;
-  const keyPrincipal = await (0, import_core2.resolveApiKeyPrincipal)(await opts.getQl(), headers);
-  if (keyPrincipal) {
-    userId = keyPrincipal.userId;
-    tenantId = keyPrincipal.tenantId;
-    for (const scope of keyPrincipal.scopes) {
-      if (!ctx.permissions.includes(scope)) ctx.permissions.push(scope);
-    }
-  }
-  if (!userId) {
+  const headers = toHeaders(opts.request?.headers);
+  const ql = await opts.getQl();
+  const getSession = async (h) => {
     try {
       const authService = await opts.getService("auth");
       let api = authService?.api;
-      if (!api && typeof authService?.getApi === "function") {
-        api = await authService.getApi();
-      }
-      const headersInstance = toHeaders(headers);
-      const sessionData = await api?.getSession?.({ headers: headersInstance });
-      userId = sessionData?.user?.id ?? sessionData?.session?.userId;
-      tenantId = tenantId ?? sessionData?.session?.activeOrganizationId;
-      ctx.accessToken = sessionData?.session?.token ?? ctx.accessToken;
-      if (sessionData?.user?.email) ctx.email = String(sessionData.user.email);
+      if (!api && typeof authService?.getApi === "function") api = await authService.getApi();
+      return await api?.getSession?.({ headers: h });
     } catch {
+      return void 0;
     }
-  }
-  if (userId) ctx.userId = userId;
-  if (tenantId) ctx.tenantId = tenantId;
-  if (!userId) return ctx;
-  const ql = await opts.getQl();
-  if (!ql) return ctx;
-  if (!ctx.email) {
-    const userRows = await tryFind(ql, "sys_user", { id: userId }, 1);
-    if (userRows[0]?.email) ctx.email = String(userRows[0].email);
-  }
-  const memberWhere = tenantId ? { user_id: userId, organization_id: tenantId } : { user_id: userId };
-  const members = await tryFind(ql, "sys_member", memberWhere, 50);
-  for (const m of members) {
-    if (m.role && typeof m.role === "string") {
-      for (const r of m.role.split(",").map((s) => s.trim()).filter(Boolean)) {
-        if (!ctx.roles.includes(r)) ctx.roles.push(r);
-      }
-    }
-  }
-  const userRoleRows = await tryFind(ql, "sys_user_role", { user_id: userId }, 200);
-  for (const ur of userRoleRows) {
-    const org = ur.organization_id ?? null;
-    if (org && tenantId && org !== tenantId) continue;
-    const r = ur.role;
-    if (typeof r === "string" && r && !ctx.roles.includes(r)) ctx.roles.push(r);
-  }
-  if (tenantId) {
-    const orgMembers = await tryFind(
-      ql,
-      "sys_member",
-      { organization_id: tenantId },
-      1e3
-    );
-    const orgUserIds = Array.from(
-      new Set(
-        orgMembers.map((m) => m.user_id ?? m.userId).filter((v) => typeof v === "string" && v.length > 0)
-      )
-    );
-    if (!orgUserIds.includes(userId)) orgUserIds.push(userId);
-    ctx.org_user_ids = orgUserIds;
-  } else {
-    ctx.org_user_ids = [userId];
-  }
-  const upsRows = await tryFind(ql, "sys_user_permission_set", { user_id: userId }, 100);
-  const psIds = new Set(
-    upsRows.filter((r) => {
-      const org = r.organization_id ?? r.organizationId ?? null;
-      return !(org && tenantId && org !== tenantId);
-    }).map((r) => r.permission_set_id ?? r.permissionSetId).filter(Boolean)
-  );
-  if (ctx.roles.length > 0) {
-    const roleRows = await tryFind(ql, "sys_role", { name: { $in: ctx.roles } }, 100);
-    const roleIds = roleRows.map((r) => r.id).filter(Boolean);
-    if (roleIds.length > 0) {
-      const rpsRows = await tryFind(
-        ql,
-        "sys_role_permission_set",
-        { role_id: { $in: roleIds } },
-        500
-      );
-      for (const r of rpsRows) {
-        const id = r.permission_set_id ?? r.permissionSetId;
-        if (id) psIds.add(id);
-      }
-    }
-  }
-  if (psIds.size > 0) {
-    const psRows = await tryFind(
+  };
+  const authz = await (0, import_core2.resolveAuthzContext)({ ql, headers, getSession });
+  const ctx = {
+    roles: authz.roles,
+    permissions: authz.permissions,
+    systemPermissions: authz.systemPermissions,
+    isSystem: false
+  };
+  if (authz.userId) ctx.userId = authz.userId;
+  if (authz.tenantId) ctx.tenantId = authz.tenantId;
+  if (authz.email) ctx.email = authz.email;
+  if (authz.accessToken) ctx.accessToken = authz.accessToken;
+  if (authz.tabPermissions) ctx.tabPermissions = authz.tabPermissions;
+  ctx.org_user_ids = authz.org_user_ids;
+  if (authz.userId) {
+    const settings = await Promise.resolve(opts.getService("settings")).catch(() => void 0);
+    const localization = await (0, import_core2.resolveLocalizationContext)({
       ql,
-      "sys_permission_set",
-      { id: { $in: Array.from(psIds) } },
-      500
-    );
-    const tabRank = {
-      hidden: 0,
-      default_off: 1,
-      default_on: 2,
-      visible: 3
-    };
-    const mergedTabs = {};
-    for (const ps of psRows) {
-      if (ps.name && !ctx.permissions.includes(ps.name)) {
-        ctx.permissions.push(ps.name);
-      }
-      const sysPerms = typeof ps.system_permissions === "string" ? safeJsonParse2(ps.system_permissions, []) : ps.system_permissions ?? ps.systemPermissions;
-      if (Array.isArray(sysPerms)) {
-        for (const p of sysPerms) {
-          if (typeof p === "string" && !ctx.systemPermissions.includes(p)) {
-            ctx.systemPermissions.push(p);
-          }
-        }
-      }
-      const tabs = typeof ps.tab_permissions === "string" ? safeJsonParse2(ps.tab_permissions, {}) : ps.tab_permissions ?? ps.tabPermissions;
-      if (tabs && typeof tabs === "object") {
-        for (const [app, val] of Object.entries(tabs)) {
-          if (typeof val !== "string" || !(val in tabRank)) continue;
-          const cur = mergedTabs[app];
-          if (!cur || tabRank[val] > tabRank[cur]) {
-            mergedTabs[app] = val;
-          }
-        }
-      }
-    }
-    if (Object.keys(mergedTabs).length > 0) {
-      ctx.tabPermissions = mergedTabs;
-    }
+      settings,
+      tenantId: authz.tenantId,
+      userId: authz.userId
+    });
+    ctx.timezone = localization.timezone;
+    ctx.locale = localization.locale;
+    if (localization.currency) ctx.currency = localization.currency;
   }
-  const localization = await resolveLocalization(opts, ql, { tenantId, userId });
-  ctx.timezone = localization.timezone;
-  ctx.locale = localization.locale;
-  if (localization.currency) ctx.currency = localization.currency;
   return ctx;
 }
 function isPermissionDeniedError(e) {
@@ -2317,6 +2147,9 @@ function isPermissionDeniedError(e) {
   return anyE.name === "PermissionDeniedError" || anyE.code === "PERMISSION_DENIED" || typeof anyE.message === "string" && anyE.message.startsWith("[Security] Access denied");
 }
 
+// src/security/api-key.ts
+var import_core3 = require("@objectstack/core");
+
 // src/http-dispatcher.ts
 function randomUUID() {
   if (globalThis.crypto && typeof globalThis.crypto.randomUUID === "function") {
@@ -2328,6 +2161,9 @@ function randomUUID() {
     return v.toString(16);
   });
 }
+function isSystemObjectName(name) {
+  return /^sys_/i.test(name);
+}
 var _HttpDispatcher = class _HttpDispatcher {
   /**
    * @param _envRegistryIgnored — RETIRED (ADR-0006 Phase 5). Environment
@@ -2445,7 +2281,10 @@ var _HttpDispatcher = class _HttpDispatcher {
       return extra ? { ...base, ...extra } : qlOpts ? base : void 0;
     };
     if (action === "create") {
-      if (ql) {
+      if (protocol && typeof protocol.createData === "function") {
+        return await protocol.createData({ object: params.object, data: params.data, ...scopeId ? { environmentId: scopeId } : {}, context: executionContext });
+      }
+      if (ql && typeof ql.insert === "function") {
         const res = await ql.insert(params.object, params.data, qlOpts);
         const record = { ...params.data, ...res };
         return { object: params.object, id: record.id, record };
@@ -2466,7 +2305,10 @@ var _HttpDispatcher = class _HttpDispatcher {
       throw { statusCode: 503, message: "Data service not available" };
     }
     if (action === "update") {
-      if (ql && params.id) {
+      if (protocol && typeof protocol.updateData === "function") {
+        return await protocol.updateData({ object: params.object, id: params.id, data: params.data, ...scopeId ? { environmentId: scopeId } : {}, context: executionContext });
+      }
+      if (ql && params.id && typeof ql.update === "function") {
         let all = await ql.find(params.object, findOpts({ where: { id: params.id }, limit: 1 }));
         if (all && all.value) all = all.value;
         if (!all) all = [];
@@ -2478,7 +2320,10 @@ var _HttpDispatcher = class _HttpDispatcher {
       throw { statusCode: 503, message: "Data service not available" };
     }
     if (action === "delete") {
-      if (ql) {
+      if (protocol && typeof protocol.deleteData === "function") {
+        return await protocol.deleteData({ object: params.object, id: params.id, ...scopeId ? { environmentId: scopeId } : {}, context: executionContext });
+      }
+      if (ql && typeof ql.delete === "function") {
         await ql.delete(params.object, findOpts({ where: { id: params.id } }));
         return { object: params.object, id: params.id, deleted: true };
       }
@@ -2670,9 +2515,269 @@ var _HttpDispatcher = class _HttpDispatcher {
       },
       create: async (object, data) => await callData("create", { object, data }, driver, envId, ec),
       update: async (object, id, data) => await callData("update", { object, id, data }, driver, envId, ec),
-      remove: async (object, id) => await callData("delete", { object, id }, driver, envId, ec)
+      remove: async (object, id) => await callData("delete", { object, id }, driver, envId, ec),
+      // ── Business-action surface (McpActionBridge) ──────────────
+      // Resolution + dispatch flow through the framework's own action
+      // mechanism (engine.executeAction / automation flow runner) bound to
+      // THIS request's ExecutionContext — the same permission + RLS path
+      // the REST `/actions/...` route uses. No `@objectstack/service-ai`.
+      listActions: async () => {
+        const meta = await getMeta();
+        const objs = await meta?.listObjects?.() ?? [];
+        const hasAutomation = Boolean(
+          await this.resolveService("automation", envId).catch(() => null)
+        );
+        const out = [];
+        for (const obj of objs) {
+          const objectName = obj?.name;
+          if (!objectName || isSystemObjectName(objectName)) continue;
+          const actions = Array.isArray(obj?.actions) ? obj.actions : [];
+          for (const action of actions) {
+            if (!action || typeof action.name !== "string") continue;
+            if (!this.isHeadlessInvokableAction(action, hasAutomation)) continue;
+            if (this.actionPermissionError(action, ec)) continue;
+            out.push(this.summarizeAction(action, obj, objectName));
+          }
+        }
+        return out;
+      },
+      runAction: async (name, input) => this.invokeBusinessAction(name, input ?? {}, { driver, envId, ec, getMeta, callData })
+    };
+  }
+  // ── MCP action bridge helpers ──────────────────────────────────────
+  /**
+   * [ADR-0066 D4] Shared capability gate for an action invocation. Returns a
+   * human-readable error string when the caller's `systemPermissions` don't
+   * cover the action's declared `requiredPermissions`, or `null` when allowed.
+   * System/engine self-invocation (`isSystem`) bypasses; an action without
+   * `requiredPermissions` is ungated. Single-sourced so the REST `/actions/...`
+   * route and the MCP `run_action` bridge enforce the SAME declaration.
+   */
+  actionPermissionError(actionDef, ec, objectName) {
+    const required = Array.isArray(actionDef?.requiredPermissions) ? actionDef.requiredPermissions : [];
+    if (required.length === 0) return null;
+    if (ec?.isSystem) return null;
+    const held = new Set(ec?.systemPermissions ?? []);
+    const missing = required.filter((perm) => !held.has(perm));
+    if (missing.length === 0) return null;
+    const on = objectName ? ` on '${objectName}'` : "";
+    return `Action '${actionDef?.name ?? "unknown"}'${on} requires capability [${required.join(", ")}] \u2014 caller is missing [${missing.join(", ")}]`;
+  }
+  /**
+   * Whether an action has a headless invocation path (so MCP can run it).
+   * Mirrors the supported-type set of the (now cloud-side) action-tools
+   * bridge: `script` needs a handler binding (`target`) or an inline `body`;
+   * `flow` needs a `target` and an automation service. UI-only types
+   * (`url`, `modal`, `form`) and `api` have no server dispatch here.
+   */
+  isHeadlessInvokableAction(action, hasAutomation) {
+    const type = action?.type ?? "script";
+    if (type === "script") return Boolean(action?.target || action?.body);
+    if (type === "flow") return Boolean(action?.target) && hasAutomation;
+    return false;
+  }
+  /** True when an action is destructive by author signal/heuristic (HITL hint). */
+  actionLooksDestructive(action) {
+    if (action?.ai?.requiresConfirmation !== void 0) return Boolean(action.ai.requiresConfirmation);
+    return Boolean(action?.confirmText || action?.mode === "delete" || action?.variant === "danger");
+  }
+  /** Project an action's declarative metadata into a lean MCP summary. */
+  summarizeAction(action, obj, objectName) {
+    const requiresRecord = Array.isArray(action?.locations) && action.locations.some(
+      (l) => l === "list_item" || l === "record_header" || l === "record_more" || l === "record_related"
+    );
+    const description = (typeof action?.ai?.description === "string" ? action.ai.description : void 0) ?? (typeof action?.label === "string" ? action.label : void 0);
+    const params = this.summarizeActionParams(action, obj);
+    return {
+      name: action.name,
+      objectName,
+      ...typeof action?.label === "string" ? { label: action.label } : {},
+      ...description ? { description } : {},
+      type: action?.type ?? "script",
+      requiresRecord: Boolean(requiresRecord),
+      requiresConfirmation: this.actionLooksDestructive(action),
+      ...params.length > 0 ? { params } : {}
+    };
+  }
+  /** Map an ObjectStack field type to a JSON-Schema primitive (conservative). */
+  jsonTypeOf(t) {
+    switch (t) {
+      case "number":
+      case "currency":
+      case "percent":
+      case "rating":
+      case "slider":
+      case "autonumber":
+        return "number";
+      case "boolean":
+      case "toggle":
+        return "boolean";
+      case "multiselect":
+      case "checkboxes":
+      case "tags":
+        return "array";
+      default:
+        return "string";
+    }
+  }
+  /** Resolve an action's params into LLM-facing summaries (field-backed types resolved). */
+  summarizeActionParams(action, obj) {
+    const fields = obj?.fields ?? {};
+    const out = [];
+    for (const p of Array.isArray(action?.params) ? action.params : []) {
+      const fieldRef = p?.field;
+      const field = fieldRef ? fields[fieldRef] : void 0;
+      const name = p?.name ?? fieldRef;
+      if (!name) continue;
+      const type = this.jsonTypeOf(p?.type ?? field?.type);
+      const label = typeof p?.label === "string" ? p.label : field?.label;
+      const help = p?.helpText ?? field?.description;
+      const description = [label, help].filter(Boolean).join(" \u2014 ") || void 0;
+      const optionSource = p?.options ?? field?.options;
+      const enumVals = Array.isArray(optionSource) ? optionSource.map((o) => typeof o === "string" ? o : o?.value).filter((v) => typeof v === "string") : [];
+      out.push({
+        name,
+        type,
+        required: Boolean(p?.required ?? field?.required ?? false),
+        ...description ? { description } : {},
+        ...enumVals.length > 0 ? { enum: enumVals } : {}
+      });
+    }
+    return out;
+  }
+  /** Slim engine facade matching the ActionContext.engine shape handlers expect. */
+  buildActionEngineFacade(ql) {
+    return {
+      async insert(object, data) {
+        const res = await ql.insert(object, data);
+        const id = (res && res.id) ?? data.id;
+        return { id };
+      },
+      async update(object, id, data) {
+        await ql.update(object, data, { where: { id } });
+      },
+      // Tolerant of both the single-id and array conventions handler suites
+      // use (CRM handlers pass one id; todo handlers pass an id array).
+      async delete(object, idOrIds) {
+        const ids = Array.isArray(idOrIds) ? idOrIds : [idOrIds];
+        for (const id of ids) {
+          if (id != null) await ql.delete(object, { where: { id } });
+        }
+      },
+      async find(object, query) {
+        const opts = query && Object.keys(query).length ? { where: query } : void 0;
+        const rows = await ql.find(object, opts);
+        return Array.isArray(rows) ? rows : rows?.value ?? [];
+      }
     };
   }
+  /**
+   * Resolve + invoke a business action by its declarative name for the MCP
+   * `run_action` tool. Enforces the ADR-0066 D4 capability gate and RLS as the
+   * caller, loads the subject record under RLS for row-context actions, and
+   * dispatches through the framework's `engine.executeAction` (script/body) or
+   * automation flow runner (flow). Throws on denial / not-found / handler
+   * failure so the tool surfaces a clean tool-error. No service-ai dependency.
+   */
+  async invokeBusinessAction(name, input, wiring) {
+    const { driver, envId, ec, getMeta, callData } = wiring;
+    const meta = await getMeta();
+    const params = input?.params && typeof input.params === "object" ? input.params : {};
+    const recordId = typeof input?.recordId === "string" && input.recordId.length > 0 ? input.recordId : void 0;
+    const resolved = await this.resolveActionByName(meta, name, input?.objectName);
+    if (!resolved) {
+      throw new Error(
+        input?.objectName ? `Action '${name}' not found on object '${input.objectName}'` : `Action '${name}' not found`
+      );
+    }
+    const { action, objectName } = resolved;
+    if (isSystemObjectName(objectName)) {
+      throw new Error(`Action '${name}' is on a system object and is not exposed via MCP`);
+    }
+    const hasAutomation = Boolean(await this.resolveService("automation", envId).catch(() => null));
+    if (!this.isHeadlessInvokableAction(action, hasAutomation)) {
+      throw new Error(
+        `Action '${name}' (type='${action?.type ?? "script"}') cannot be invoked via MCP`
+      );
+    }
+    const gateError = this.actionPermissionError(action, ec, objectName);
+    if (gateError) throw new Error(gateError);
+    let record = {};
+    if (recordId && objectName !== "global") {
+      try {
+        const got = await callData("get", { object: objectName, id: recordId }, driver, envId, ec);
+        if (got?.record) record = got.record;
+      } catch {
+      }
+    }
+    if (record && record.id == null && recordId) record.id = recordId;
+    const user = ec?.userId ? { id: ec.userId, name: ec.userName ?? ec.userDisplayName ?? ec.userId } : { id: "system", name: "system" };
+    if (action.type === "flow") {
+      const automation = await this.resolveService("automation", envId).catch(() => null);
+      if (!automation || typeof automation.execute !== "function") {
+        throw new Error(`Action '${name}' is a flow but no automation service is available`);
+      }
+      const result = await automation.execute(action.target, {
+        triggerData: { record, params, user, action: action.name }
+      });
+      if (result && typeof result === "object" && "success" in result && result.success === false) {
+        throw new Error(`Flow '${action.target}' failed: ${result.error ?? "unknown error"}`);
+      }
+      return { ok: true, action: action.name, objectName, ...recordId ? { recordId } : {}, result: result ?? null };
+    }
+    const ql = await this.getObjectQLService(envId);
+    if (!ql || typeof ql.executeAction !== "function") {
+      throw new Error("Data engine not available for action dispatch");
+    }
+    const actionContext = {
+      record,
+      user,
+      engine: this.buildActionEngineFacade(ql),
+      params: { ...params, recordId, objectName }
+    };
+    const primary = action.body ? action.name : action.target || action.name;
+    const candidates = [primary, action.target, action.name].filter(
+      (k, i, a) => typeof k === "string" && a.indexOf(k) === i
+    );
+    const notRegistered = (err) => /Action '.+' on object '.+' not found/i.test(String(err?.message ?? err));
+    for (const obj of [objectName, "*"]) {
+      for (const key of candidates) {
+        try {
+          const result = await ql.executeAction(obj, key, actionContext);
+          return { ok: true, action: action.name, objectName, ...recordId ? { recordId } : {}, result: result ?? null };
+        } catch (err) {
+          if (!notRegistered(err)) throw err;
+        }
+      }
+    }
+    throw new Error(`No handler registered for action '${name}' on '${objectName}'`);
+  }
+  /**
+   * Find an action's declarative definition by name across object metadata,
+   * optionally scoped to a single object. Returns the action plus its owning
+   * object name, or `null`. Throws when the name is ambiguous across objects
+   * and no `objectName` was supplied (so `run_action` can ask for one).
+   */
+  async resolveActionByName(meta, name, objectName) {
+    if (objectName) {
+      const def = await meta?.getObject?.(objectName);
+      const action = Array.isArray(def?.actions) ? def.actions.find((a) => a?.name === name) : void 0;
+      return action ? { action, objectName } : null;
+    }
+    const objs = await meta?.listObjects?.() ?? [];
+    const matches = [];
+    for (const obj of objs) {
+      if (!obj?.name) continue;
+      const action = Array.isArray(obj?.actions) ? obj.actions.find((a) => a?.name === name) : void 0;
+      if (action) matches.push({ action, objectName: obj.name });
+    }
+    if (matches.length === 0) return null;
+    if (matches.length > 1) {
+      const where = matches.map((m) => m.objectName).join(", ");
+      throw new Error(`Action '${name}' exists on multiple objects (${where}); pass objectName to disambiguate`);
+    }
+    return matches[0];
+  }
   /**
    * Generate a `sys_api_key` and return the raw secret EXACTLY ONCE
    * (`POST /keys`). This is the only mint path — the raw key is never stored
@@ -2719,7 +2824,7 @@ var _HttpDispatcher = class _HttpDispatcher {
     if (!ql || typeof ql.insert !== "function") {
       return { handled: true, response: this.error("Data service not available", 503) };
     }
-    const generated = (0, import_core2.generateApiKey)();
+    const generated = (0, import_core3.generateApiKey)();
     const row = {
       name,
       key: generated.hash,
@@ -2804,6 +2909,43 @@ var _HttpDispatcher = class _HttpDispatcher {
    * response object that callers should surface directly — no further
    * dispatch happens.
    */
+  /**
+   * ADR-0069 — returns a 403 response when the resolved session is blocked by
+   * an auth-policy gate (expired password / required MFA) on a non-allow-listed
+   * path, else null. Mirrors the REST `enforceAuth` seam so REST + dispatcher
+   * (MCP, GraphQL) enforce consistently. Fails open on any lookup error.
+   */
+  async enforceAuthGate(context, cleanPath) {
+    try {
+      if ((0, import_core4.isAuthGateAllowlisted)(cleanPath)) return null;
+      const authService = await this.resolveService("auth", context.environmentId);
+      if (!authService || typeof authService.isAuthGateActive !== "function" || !authService.isAuthGateActive()) {
+        return null;
+      }
+      let api = authService.api;
+      if (!api && typeof authService.getApi === "function") api = await authService.getApi();
+      if (!api?.getSession) return null;
+      const raw = context?.request?.headers;
+      let headers;
+      if (raw && typeof raw.get === "function") {
+        headers = raw;
+      } else if (raw && typeof raw === "object") {
+        headers = new globalThis.Headers();
+        for (const k of Object.keys(raw)) {
+          const v = raw[k];
+          if (v != null) headers.set(String(k), Array.isArray(v) ? v.join(",") : String(v));
+        }
+      } else {
+        return null;
+      }
+      const session = await api.getSession({ headers }).catch(() => void 0);
+      const gate = (0, import_core4.evaluateAuthGate)(session?.user, cleanPath);
+      if (!gate) return null;
+      return this.error(gate.message, 403, { code: gate.code });
+    } catch {
+      return null;
+    }
+  }
   async enforceProjectMembership(context, path) {
     if (!this.enforceMembership) return null;
     const skipPaths = ["/auth", "/cloud", "/health", "/ready", "/discovery"];
@@ -2961,7 +3103,7 @@ var _HttpDispatcher = class _HttpDispatcher {
     return {
       name: "ObjectOS",
       version: "1.0.0",
-      environment: (0, import_core3.getEnv)("NODE_ENV", "development"),
+      environment: (0, import_core4.getEnv)("NODE_ENV", "development"),
       routes,
       endpoints: routes,
       // Alias for backward compatibility with some clients
@@ -3466,7 +3608,7 @@ var _HttpDispatcher = class _HttpDispatcher {
       let translations = i18nService.getTranslations(locale);
       if (Object.keys(translations).length === 0) {
         const availableLocales = typeof i18nService.getLocales === "function" ? i18nService.getLocales() : [];
-        const resolved = (0, import_core3.resolveLocale)(locale, availableLocales);
+        const resolved = (0, import_core4.resolveLocale)(locale, availableLocales);
         if (resolved && resolved !== locale) {
           translations = i18nService.getTranslations(resolved);
           return { handled: true, response: this.success({ locale: resolved, requestedLocale: locale, translations }) };
@@ -3479,7 +3621,7 @@ var _HttpDispatcher = class _HttpDispatcher {
       let locale = parts[2] ? decodeURIComponent(parts[2]) : query?.locale;
       if (!locale) return { handled: true, response: this.error("Missing locale parameter", 400) };
       const availableLocales = typeof i18nService.getLocales === "function" ? i18nService.getLocales() : [];
-      const resolved = (0, import_core3.resolveLocale)(locale, availableLocales);
+      const resolved = (0, import_core4.resolveLocale)(locale, availableLocales);
       if (resolved) locale = resolved;
       if (typeof i18nService.getFieldLabels === "function") {
         const labels2 = i18nService.getFieldLabels(objectName, locale);
@@ -3653,6 +3795,61 @@ var _HttpDispatcher = class _HttpDispatcher {
         }
         return { handled: true, response: this.error("Draft discarding not supported", 501) };
       }
+      if (parts.length === 2 && parts[1] === "commits" && m === "GET") {
+        const id = decodeURIComponent(parts[0]);
+        const protocol = await this.resolveService("protocol");
+        if (protocol && typeof protocol.listCommits === "function") {
+          try {
+            const organizationId = await this.resolveActiveOrganizationId(_context);
+            const commits = await protocol.listCommits({
+              packageId: id,
+              ...organizationId ? { organizationId } : {}
+            });
+            return { handled: true, response: this.success({ commits }) };
+          } catch (e) {
+            return { handled: true, response: this.error(e.message, e.statusCode || 500) };
+          }
+        }
+        return { handled: true, response: this.error("Commit history not supported", 501) };
+      }
+      if (parts.length === 4 && parts[1] === "commits" && parts[3] === "revert" && m === "POST") {
+        const commitId = decodeURIComponent(parts[2]);
+        const protocol = await this.resolveService("protocol");
+        if (protocol && typeof protocol.revertCommit === "function") {
+          try {
+            const organizationId = await this.resolveActiveOrganizationId(_context);
+            const result = await protocol.revertCommit({
+              commitId,
+              ...organizationId ? { organizationId } : {},
+              ...body?.actor ? { actor: body.actor } : {}
+            });
+            return { handled: true, response: this.success(result) };
+          } catch (e) {
+            return { handled: true, response: this.error(e.message, e.statusCode || 500) };
+          }
+        }
+        return { handled: true, response: this.error("Commit revert not supported", 501) };
+      }
+      if (parts.length === 2 && parts[1] === "rollback" && m === "POST") {
+        const protocol = await this.resolveService("protocol");
+        if (protocol && typeof protocol.rollbackToPackageCommit === "function") {
+          if (!body?.commitId) {
+            return { handled: true, response: this.error("Body { commitId } is required", 400) };
+          }
+          try {
+            const organizationId = await this.resolveActiveOrganizationId(_context);
+            const result = await protocol.rollbackToPackageCommit({
+              commitId: String(body.commitId),
+              ...organizationId ? { organizationId } : {},
+              ...body?.actor ? { actor: body.actor } : {}
+            });
+            return { handled: true, response: this.success(result) };
+          } catch (e) {
+            return { handled: true, response: this.error(e.message, e.statusCode || 500) };
+          }
+        }
+        return { handled: true, response: this.error("Commit rollback not supported", 501) };
+      }
       if (parts.length === 2 && parts[1] === "revert" && m === "POST") {
         const id = decodeURIComponent(parts[0]);
         const metadataService = await this.getService(import_system.CoreServiceName.enum.metadata);
@@ -3670,6 +3867,49 @@ var _HttpDispatcher = class _HttpDispatcher {
         }
         return { handled: true, response: this.success(manifest) };
       }
+      if (parts.length === 2 && parts[1] === "adopt-orphans" && m === "POST") {
+        const id = decodeURIComponent(parts[0]);
+        const protocol = await this.resolveService("protocol");
+        if (!protocol || typeof protocol.reassignOrphanedMetadata !== "function") {
+          return { handled: true, response: this.error("Orphan adoption not supported", 501) };
+        }
+        try {
+          const organizationId = await this.resolveActiveOrganizationId(_context);
+          const result = await protocol.reassignOrphanedMetadata({
+            targetPackageId: id,
+            ...organizationId ? { organizationId } : {},
+            ...body?.actor ? { actor: body.actor } : {}
+          });
+          return { handled: true, response: this.success(result) };
+        } catch (e) {
+          return { handled: true, response: this.error(e.message, e.statusCode || 500) };
+        }
+      }
+      if (parts.length === 2 && parts[1] === "duplicate" && m === "POST") {
+        const id = decodeURIComponent(parts[0]);
+        const protocol = await this.resolveService("protocol");
+        if (!protocol || typeof protocol.duplicatePackage !== "function") {
+          return { handled: true, response: this.error("Package duplication not supported", 501) };
+        }
+        const targetPackageId = typeof body?.targetPackageId === "string" ? body.targetPackageId.trim() : "";
+        if (!targetPackageId) {
+          return { handled: true, response: this.error("Body { targetPackageId } is required", 400) };
+        }
+        try {
+          const organizationId = await this.resolveActiveOrganizationId(_context);
+          const result = await protocol.duplicatePackage({
+            sourcePackageId: id,
+            targetPackageId,
+            ...typeof body?.targetName === "string" ? { targetName: body.targetName } : {},
+            ...typeof body?.targetNamespace === "string" ? { targetNamespace: body.targetNamespace } : {},
+            ...organizationId ? { organizationId } : {},
+            ...body?.actor ? { actor: body.actor } : {}
+          });
+          return { handled: true, response: this.success(result) };
+        } catch (e) {
+          return { handled: true, response: this.error(e.message, e.statusCode || 500) };
+        }
+      }
       if (parts.length === 1 && m === "GET") {
         const id = decodeURIComponent(parts[0]);
         const pkg = registry.getPackage(id);
@@ -4073,8 +4313,12 @@ var _HttpDispatcher = class _HttpDispatcher {
             object: objectName,
             event: ctxBody.event ?? "manual"
           };
-          const userIdFromAuth = context?.user?.id ?? context?.userId;
+          const ec = context?.executionContext;
+          const userIdFromAuth = context?.user?.id ?? context?.userId ?? ec?.userId;
           if (userIdFromAuth) automationContext.userId = userIdFromAuth;
+          if (Array.isArray(ec?.roles) && ec.roles.length) automationContext.roles = ec.roles;
+          if (Array.isArray(ec?.permissions) && ec.permissions.length) automationContext.permissions = ec.permissions;
+          if (ec?.tenantId) automationContext.tenantId = ec.tenantId;
           const result = await automationService.execute(name, automationContext);
           return { handled: true, response: this.success(result) };
         }
@@ -4255,22 +4499,9 @@ var _HttpDispatcher = class _HttpDispatcher {
     try {
       const actionSchema = (typeof ql.getSchema === "function" ? ql.getSchema(objectName) : void 0) ?? ql.registry?.getObject?.(objectName);
       const actionDef = Array.isArray(actionSchema?.actions) ? actionSchema.actions.find((a) => a?.name === actionName) : void 0;
-      const required = Array.isArray(actionDef?.requiredPermissions) ? actionDef.requiredPermissions : [];
-      if (required.length > 0) {
-        const execCtx = _context?.executionContext;
-        if (!execCtx?.isSystem) {
-          const held = new Set(execCtx?.systemPermissions ?? []);
-          const missing = required.filter((perm) => !held.has(perm));
-          if (missing.length > 0) {
-            return {
-              handled: true,
-              response: this.error(
-                `Action '${actionName}' on '${objectName}' requires capability [${required.join(", ")}] \u2014 caller is missing [${missing.join(", ")}]`,
-                403
-              )
-            };
-          }
-        }
+      const gateError = this.actionPermissionError(actionDef, _context?.executionContext, objectName);
+      if (gateError) {
+        return { handled: true, response: this.error(gateError, 403) };
       }
     } catch {
     }
@@ -4613,11 +4844,31 @@ var _HttpDispatcher = class _HttpDispatcher {
     try {
       context.executionContext = await resolveExecutionContext({
         getService: (n) => this.resolveService(n, context.environmentId),
-        getQl: () => Promise.resolve(this.getObjectQLService(context.environmentId)),
+        // Resolve ObjectQL from the per-request kernel DIRECTLY. The scoped
+        // `resolveService('objectql', envId)` factory can return a different
+        // instance that doesn't see THIS env's rows (the gotcha
+        // `handleActions` works around) — which made the api-key lookup miss
+        // `sys_api_key` on the MCP path and reject valid keys with 401, while
+        // REST accepted them (rest-server resolves identity via
+        // `kernel.getServiceAsync('objectql')`). Resolving off `this.kernel`
+        // keeps REST + MCP identity resolution aligned; falls back to the
+        // scoped path when the kernel can't hand back an objectql directly.
+        getQl: async () => {
+          const k = this.kernel;
+          if (k && typeof k.getServiceAsync === "function") {
+            const ql = await k.getServiceAsync("objectql").catch(() => void 0);
+            if (ql && (ql.registry || typeof ql.find === "function")) return ql;
+          }
+          return this.getObjectQLService(context.environmentId);
+        },
         request: context.request
       });
     } catch {
     }
+    const authGated = await this.enforceAuthGate(context, cleanPath);
+    if (authGated) {
+      return { handled: true, response: authGated };
+    }
     const forbidden = await this.enforceProjectMembership(context, cleanPath);
     if (forbidden) {
       return { handled: true, response: forbidden };