@objectstack/types 16.0.0 → 17.0.0-rc.0

package/dist/index.d.mts

@@ -1,3 +1,56 @@
+import { TenancyPosture } from '@objectstack/spec/security';
+
+/**
+ * Degraded-boot reporting, shared by every subsystem that can be told to boot
+ * without a datasource it needs.
+ *
+ * Two of them exist today and they opt in through the *same* operator flag
+ * (`OS_ALLOW_DRIVER_CONNECT_FAILURE`, see {@link resolveAllowDriverConnectFailure}):
+ *
+ *  - `ObjectQLEngine.init()` — a boot-registered driver whose `connect()`
+ *    rejected (framework#3741).
+ *  - `DatasourceConnectionService` — a declared datasource that objects bind to
+ *    explicitly, or an `external` one with `validation.onMismatch:'fail'`,
+ *    that could not be connected (framework#3758).
+ *
+ * They live in different packages but owe the operator the same thing: the
+ * degraded state must be impossible to miss.
+ */
+/**
+ * Emit the degraded-boot banner on a channel the host cannot accidentally
+ * silence.
+ *
+ * `OS_ALLOW_DRIVER_CONNECT_FAILURE` only justifies itself if the state it opts
+ * into is impossible to miss — and a logger-only banner is missable: `os serve`
+ * swallows ALL of stdout while the kernel boots (its "boot-quiet" capture), and
+ * `Logger` routes `warn` to stdout, so the one message that matters would be
+ * invisible in exactly the situation it exists for. Writing to stderr as well
+ * is the same belt-and-braces the kernel already uses for plugin startup
+ * failures.
+ *
+ * Best-effort and never throws: falls back to `console.error`, then to silence
+ * on runtimes that have neither (the logger still carries the structured
+ * record either way).
+ */
+declare function emitDegradedBootBanner(message: string): void;
+
+/**
+ * Environment-variable helpers shared across `@objectstack/*` packages.
+ *
+ * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md
+ * "Environment Variables" section). Some historical names predate this
+ * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …
+ *
+ * To migrate without breaking user `.env` files mid-release, call
+ * {@link readEnvWithDeprecation} at every legacy read site:
+ *
+ *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');
+ *
+ * If only the legacy name is set, the value is still returned but a
+ * one-shot `console.warn` fires (per-process per-variable) telling
+ * operators to rename it.
+ */
+
 /**
  * Read an env var, preferring the canonical `OS_*` name and falling
  * back to one or more legacy aliases.
@@ -45,6 +98,28 @@ declare function readEnvWithDeprecation(preferred: string, legacy: string | read
  * result must be stable for the process lifetime.
  */
 declare function resolveMultiOrgEnabled(): boolean;
+/**
+ * [ADR-0105 D1] Resolve the deployment's REQUESTED tenancy posture —
+ * `single` | `group` | `isolated`.
+ *
+ * `OS_TENANCY_POSTURE` is the canonical knob and generalizes the boolean
+ * `OS_MULTI_ORG_ENABLED` it supersedes:
+ *
+ * - set → that posture (the legacy spelling `multi` normalizes to `isolated`)
+ * - unset → derived from `OS_MULTI_ORG_ENABLED`: `true` ⇒ `isolated`, else `single`
+ *
+ * so every existing deployment keeps its current posture with no config change.
+ *
+ * An unrecognized value THROWS rather than falling back. A typo'd posture that
+ * quietly resolved to `single` would silently remove the organization wall —
+ * the deployment-layer form of the "declared but unenforced" defect ADR-0049
+ * forbids, and the same reasoning behind ADR-0093 D5's refusal to boot into
+ * undeclared degradation.
+ *
+ * This resolves what the operator ASKED FOR. Whether the posture is actually
+ * enforced is the `tenancy` service's answer (`isolationActive` / `degraded`).
+ */
+declare function resolveTenancyPosture(): TenancyPosture;
 /**
  * Escape hatch for the degraded-tenancy boot guard (ADR-0093 D5).
  *
@@ -57,6 +132,26 @@ declare function resolveMultiOrgEnabled(): boolean;
  * an unset flag means "fail fast".
  */
 declare function resolveAllowDegradedTenancy(): boolean;
+/**
+ * Escape hatch for the driver-connect boot guard (framework#3741).
+ *
+ * `ObjectQLEngine.init()` connects every boot-registered driver and, by
+ * default, refuses to boot when any of them fails — a server whose database is
+ * unreachable must not report itself started and then 500 every request with an
+ * error that reads nothing like "the database is down". Failing there is also
+ * what gives a driver the ability to REFUSE STARTUP at all: any fatal startup
+ * check a driver wants to run (licence, server version, incompatible
+ * configuration, missing capability) can simply throw from `connect()`.
+ *
+ * Setting this to a truthy value (`true`/`1`/`on`/`yes`, case-insensitive)
+ * boots anyway, in an explicitly degraded state that is logged loudly at
+ * startup. Every query routed to a failed driver fails until the datasource
+ * becomes reachable — the underlying clients do re-establish connections on
+ * their own (framework#3759) — but the boot-time schema sync those drivers
+ * missed is never re-run, so their tables may simply not exist afterwards.
+ * Defaults OFF — an unset flag means "fail fast".
+ */
+declare function resolveAllowDriverConnectFailure(): boolean;
 /**
  * SINGLE decision point for "is the MCP HTTP surface (`/api/v1/mcp`) on?".
  *
@@ -184,6 +279,50 @@ declare function resolveSandboxTimeoutMs(kind: 'hook' | 'action' | 'wallCeiling'
  */
 declare function _resetEnvDeprecationWarnings(): void;
 
+/**
+ * Shared "does this error message leak server internals?" heuristic (#3867).
+ *
+ * ObjectStack has more than one HTTP boundary. `@objectstack/rest` guards the
+ * REST data routes inside `mapDataError`; the dispatcher-plugin routes
+ * (`/analytics`, `/packages`, `/i18n`, `/storage`, `/automation`, …) exit
+ * through `errorResponseBase`. Before #3867 only the first of those sanitised
+ * anything, so a driver error raised under `/analytics/query` reached the
+ * client verbatim — a real SQL statement in the response body:
+ *
+ * ```
+ * {"success":false,"error":{"message":"SELECT  FROM \"sqlite_sequence\" - near \"FROM\": syntax error","code":500}}
+ * ```
+ *
+ * "Do not ship driver internals to clients" is a property of the HTTP
+ * boundary, not of one router, so the predicate lives here — the package both
+ * `@objectstack/rest` and `@objectstack/runtime` already depend on — and each
+ * boundary applies it in its own envelope. One heuristic, one place to widen
+ * when a new dialect's phrasing shows up.
+ *
+ * Deliberately a *heuristic over the message*, not a driver taxonomy: these
+ * errors arrive as plain `Error`s from a half-dozen dialects with no shared
+ * shape. It is applied only where the outcome is already a 5xx, so a false
+ * positive costs a caller nothing but detail on a response that was a server
+ * fault anyway — while the full text still reaches server logs and the
+ * error reporter.
+ */
+/** Generic replacement text for a message that trips {@link looksLikeInternalErrorLeak}. */
+declare const INTERNAL_ERROR_MESSAGE = "Internal server error";
+/**
+ * Whether `message` looks like a raw SQL statement or driver/engine dump that
+ * must not be returned to an API client.
+ *
+ * Matches: dialect error codes (`SQLSTATE`, `sqlite_*`), bare statements
+ * (a message that *starts* as `SELECT`/`INSERT INTO`/`UPDATE`/`DELETE FROM` —
+ * drivers prefix the offending SQL to their message), and constraint-violation
+ * dumps, which name physical tables and columns.
+ *
+ * Does NOT match ordinary business or validation messages, which is why the
+ * statement forms are anchored with `startsWith`: a legitimate message may
+ * *mention* "update" without being one.
+ */
+declare function looksLikeInternalErrorLeak(message: string | undefined | null): boolean;
+
 /**
  * True when a dynamic `import()` / `require.resolve()` failed because the
  * module is simply NOT INSTALLED — as opposed to the module being present but
@@ -214,4 +353,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, isMcpServerEnabled, isModuleNotFoundError, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled };
+export { type IKernel, INTERNAL_ERROR_MESSAGE, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, emitDegradedBootBanner, isMcpServerEnabled, isModuleNotFoundError, looksLikeInternalErrorLeak, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture };

package/dist/index.d.ts

@@ -1,3 +1,56 @@
+import { TenancyPosture } from '@objectstack/spec/security';
+
+/**
+ * Degraded-boot reporting, shared by every subsystem that can be told to boot
+ * without a datasource it needs.
+ *
+ * Two of them exist today and they opt in through the *same* operator flag
+ * (`OS_ALLOW_DRIVER_CONNECT_FAILURE`, see {@link resolveAllowDriverConnectFailure}):
+ *
+ *  - `ObjectQLEngine.init()` — a boot-registered driver whose `connect()`
+ *    rejected (framework#3741).
+ *  - `DatasourceConnectionService` — a declared datasource that objects bind to
+ *    explicitly, or an `external` one with `validation.onMismatch:'fail'`,
+ *    that could not be connected (framework#3758).
+ *
+ * They live in different packages but owe the operator the same thing: the
+ * degraded state must be impossible to miss.
+ */
+/**
+ * Emit the degraded-boot banner on a channel the host cannot accidentally
+ * silence.
+ *
+ * `OS_ALLOW_DRIVER_CONNECT_FAILURE` only justifies itself if the state it opts
+ * into is impossible to miss — and a logger-only banner is missable: `os serve`
+ * swallows ALL of stdout while the kernel boots (its "boot-quiet" capture), and
+ * `Logger` routes `warn` to stdout, so the one message that matters would be
+ * invisible in exactly the situation it exists for. Writing to stderr as well
+ * is the same belt-and-braces the kernel already uses for plugin startup
+ * failures.
+ *
+ * Best-effort and never throws: falls back to `console.error`, then to silence
+ * on runtimes that have neither (the logger still carries the structured
+ * record either way).
+ */
+declare function emitDegradedBootBanner(message: string): void;
+
+/**
+ * Environment-variable helpers shared across `@objectstack/*` packages.
+ *
+ * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md
+ * "Environment Variables" section). Some historical names predate this
+ * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …
+ *
+ * To migrate without breaking user `.env` files mid-release, call
+ * {@link readEnvWithDeprecation} at every legacy read site:
+ *
+ *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');
+ *
+ * If only the legacy name is set, the value is still returned but a
+ * one-shot `console.warn` fires (per-process per-variable) telling
+ * operators to rename it.
+ */
+
 /**
  * Read an env var, preferring the canonical `OS_*` name and falling
  * back to one or more legacy aliases.
@@ -45,6 +98,28 @@ declare function readEnvWithDeprecation(preferred: string, legacy: string | read
  * result must be stable for the process lifetime.
  */
 declare function resolveMultiOrgEnabled(): boolean;
+/**
+ * [ADR-0105 D1] Resolve the deployment's REQUESTED tenancy posture —
+ * `single` | `group` | `isolated`.
+ *
+ * `OS_TENANCY_POSTURE` is the canonical knob and generalizes the boolean
+ * `OS_MULTI_ORG_ENABLED` it supersedes:
+ *
+ * - set → that posture (the legacy spelling `multi` normalizes to `isolated`)
+ * - unset → derived from `OS_MULTI_ORG_ENABLED`: `true` ⇒ `isolated`, else `single`
+ *
+ * so every existing deployment keeps its current posture with no config change.
+ *
+ * An unrecognized value THROWS rather than falling back. A typo'd posture that
+ * quietly resolved to `single` would silently remove the organization wall —
+ * the deployment-layer form of the "declared but unenforced" defect ADR-0049
+ * forbids, and the same reasoning behind ADR-0093 D5's refusal to boot into
+ * undeclared degradation.
+ *
+ * This resolves what the operator ASKED FOR. Whether the posture is actually
+ * enforced is the `tenancy` service's answer (`isolationActive` / `degraded`).
+ */
+declare function resolveTenancyPosture(): TenancyPosture;
 /**
  * Escape hatch for the degraded-tenancy boot guard (ADR-0093 D5).
  *
@@ -57,6 +132,26 @@ declare function resolveMultiOrgEnabled(): boolean;
  * an unset flag means "fail fast".
  */
 declare function resolveAllowDegradedTenancy(): boolean;
+/**
+ * Escape hatch for the driver-connect boot guard (framework#3741).
+ *
+ * `ObjectQLEngine.init()` connects every boot-registered driver and, by
+ * default, refuses to boot when any of them fails — a server whose database is
+ * unreachable must not report itself started and then 500 every request with an
+ * error that reads nothing like "the database is down". Failing there is also
+ * what gives a driver the ability to REFUSE STARTUP at all: any fatal startup
+ * check a driver wants to run (licence, server version, incompatible
+ * configuration, missing capability) can simply throw from `connect()`.
+ *
+ * Setting this to a truthy value (`true`/`1`/`on`/`yes`, case-insensitive)
+ * boots anyway, in an explicitly degraded state that is logged loudly at
+ * startup. Every query routed to a failed driver fails until the datasource
+ * becomes reachable — the underlying clients do re-establish connections on
+ * their own (framework#3759) — but the boot-time schema sync those drivers
+ * missed is never re-run, so their tables may simply not exist afterwards.
+ * Defaults OFF — an unset flag means "fail fast".
+ */
+declare function resolveAllowDriverConnectFailure(): boolean;
 /**
  * SINGLE decision point for "is the MCP HTTP surface (`/api/v1/mcp`) on?".
  *
@@ -184,6 +279,50 @@ declare function resolveSandboxTimeoutMs(kind: 'hook' | 'action' | 'wallCeiling'
  */
 declare function _resetEnvDeprecationWarnings(): void;
 
+/**
+ * Shared "does this error message leak server internals?" heuristic (#3867).
+ *
+ * ObjectStack has more than one HTTP boundary. `@objectstack/rest` guards the
+ * REST data routes inside `mapDataError`; the dispatcher-plugin routes
+ * (`/analytics`, `/packages`, `/i18n`, `/storage`, `/automation`, …) exit
+ * through `errorResponseBase`. Before #3867 only the first of those sanitised
+ * anything, so a driver error raised under `/analytics/query` reached the
+ * client verbatim — a real SQL statement in the response body:
+ *
+ * ```
+ * {"success":false,"error":{"message":"SELECT  FROM \"sqlite_sequence\" - near \"FROM\": syntax error","code":500}}
+ * ```
+ *
+ * "Do not ship driver internals to clients" is a property of the HTTP
+ * boundary, not of one router, so the predicate lives here — the package both
+ * `@objectstack/rest` and `@objectstack/runtime` already depend on — and each
+ * boundary applies it in its own envelope. One heuristic, one place to widen
+ * when a new dialect's phrasing shows up.
+ *
+ * Deliberately a *heuristic over the message*, not a driver taxonomy: these
+ * errors arrive as plain `Error`s from a half-dozen dialects with no shared
+ * shape. It is applied only where the outcome is already a 5xx, so a false
+ * positive costs a caller nothing but detail on a response that was a server
+ * fault anyway — while the full text still reaches server logs and the
+ * error reporter.
+ */
+/** Generic replacement text for a message that trips {@link looksLikeInternalErrorLeak}. */
+declare const INTERNAL_ERROR_MESSAGE = "Internal server error";
+/**
+ * Whether `message` looks like a raw SQL statement or driver/engine dump that
+ * must not be returned to an API client.
+ *
+ * Matches: dialect error codes (`SQLSTATE`, `sqlite_*`), bare statements
+ * (a message that *starts* as `SELECT`/`INSERT INTO`/`UPDATE`/`DELETE FROM` —
+ * drivers prefix the offending SQL to their message), and constraint-violation
+ * dumps, which name physical tables and columns.
+ *
+ * Does NOT match ordinary business or validation messages, which is why the
+ * statement forms are anchored with `startsWith`: a legitimate message may
+ * *mention* "update" without being one.
+ */
+declare function looksLikeInternalErrorLeak(message: string | undefined | null): boolean;
+
 /**
  * True when a dynamic `import()` / `require.resolve()` failed because the
  * module is simply NOT INSTALLED — as opposed to the module being present but
@@ -214,4 +353,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, isMcpServerEnabled, isModuleNotFoundError, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled };
+export { type IKernel, INTERNAL_ERROR_MESSAGE, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, emitDegradedBootBanner, isMcpServerEnabled, isModuleNotFoundError, looksLikeInternalErrorLeak, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture };

package/dist/index.js

@@ -20,20 +20,43 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  INTERNAL_ERROR_MESSAGE: () => INTERNAL_ERROR_MESSAGE,
   _resetEnvDeprecationWarnings: () => _resetEnvDeprecationWarnings,
+  emitDegradedBootBanner: () => emitDegradedBootBanner,
   isMcpServerEnabled: () => isMcpServerEnabled,
   isModuleNotFoundError: () => isModuleNotFoundError,
+  looksLikeInternalErrorLeak: () => looksLikeInternalErrorLeak,
   readEnvWithDeprecation: () => readEnvWithDeprecation,
   resolveAllowDegradedTenancy: () => resolveAllowDegradedTenancy,
+  resolveAllowDriverConnectFailure: () => resolveAllowDriverConnectFailure,
   resolveMcpStdioAutoStart: () => resolveMcpStdioAutoStart,
   resolveMultiOrgEnabled: () => resolveMultiOrgEnabled,
   resolveOrgLimit: () => resolveOrgLimit,
   resolveSandboxTimeoutMs: () => resolveSandboxTimeoutMs,
-  resolveSearchPinyinEnabled: () => resolveSearchPinyinEnabled
+  resolveSearchPinyinEnabled: () => resolveSearchPinyinEnabled,
+  resolveTenancyPosture: () => resolveTenancyPosture
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/degraded-boot.ts
+function emitDegradedBootBanner(message) {
+  const proc = globalThis.process;
+  try {
+    if (typeof proc?.stderr?.write === "function") {
+      proc.stderr.write(`${message}
+`);
+      return;
+    }
+  } catch {
+  }
+  try {
+    globalThis.console?.error?.(message);
+  } catch {
+  }
+}
+
 // src/env.ts
+var import_security = require("@objectstack/spec/security");
 var _warnedKeys = /* @__PURE__ */ new Set();
 function readEnvWithDeprecation(preferred, legacy, options) {
   const env = globalThis.process?.env;
@@ -64,11 +87,29 @@ function resolveMultiOrgEnabled() {
   const raw = readEnvWithDeprecation("OS_MULTI_ORG_ENABLED", []);
   return String(raw ?? "false").toLowerCase() !== "false";
 }
+function resolveTenancyPosture() {
+  const raw = globalThis.process?.env?.OS_TENANCY_POSTURE;
+  if (raw != null && String(raw).trim() !== "") {
+    const posture = (0, import_security.normalizeTenancyPosture)(raw);
+    if (!posture) {
+      throw new Error(
+        `Invalid OS_TENANCY_POSTURE=${JSON.stringify(String(raw))}. Expected one of: ${import_security.TENANCY_POSTURES.join(", ")} (or the legacy alias 'multi' = 'isolated'). Refusing to boot rather than silently falling back to a posture with no organization wall.`
+      );
+    }
+    return posture;
+  }
+  return resolveMultiOrgEnabled() ? "isolated" : "single";
+}
 function resolveAllowDegradedTenancy() {
   const raw = readEnvWithDeprecation("OS_ALLOW_DEGRADED_TENANCY", [], { silent: true });
   if (raw == null) return false;
   return ["1", "true", "on", "yes"].includes(String(raw).trim().toLowerCase());
 }
+function resolveAllowDriverConnectFailure() {
+  const raw = readEnvWithDeprecation("OS_ALLOW_DRIVER_CONNECT_FAILURE", [], { silent: true });
+  if (raw == null) return false;
+  return ["1", "true", "on", "yes"].includes(String(raw).trim().toLowerCase());
+}
 function isMcpServerEnabled() {
   const raw = readEnvWithDeprecation("OS_MCP_SERVER_ENABLED", "MCP_SERVER_ENABLED", {
     silent: true
@@ -111,6 +152,14 @@ function _resetEnvDeprecationWarnings() {
   _warnedKeys.clear();
 }
 
+// src/error-leak.ts
+var INTERNAL_ERROR_MESSAGE = "Internal server error";
+function looksLikeInternalErrorLeak(message) {
+  if (!message) return false;
+  const lower = String(message).toLowerCase();
+  return lower.includes("sqlite_") || lower.includes("sqlstate") || lower.startsWith("insert into ") || lower.startsWith("update ") || lower.startsWith("select ") || lower.startsWith("delete from ") || lower.includes("constraint failed") || lower.includes("unique constraint") || lower.includes("foreign key");
+}
+
 // src/module-not-found.ts
 function isModuleNotFoundError(err) {
   const code = err?.code;
@@ -120,15 +169,20 @@ function isModuleNotFoundError(err) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  INTERNAL_ERROR_MESSAGE,
   _resetEnvDeprecationWarnings,
+  emitDegradedBootBanner,
   isMcpServerEnabled,
   isModuleNotFoundError,
+  looksLikeInternalErrorLeak,
   readEnvWithDeprecation,
   resolveAllowDegradedTenancy,
+  resolveAllowDriverConnectFailure,
   resolveMcpStdioAutoStart,
   resolveMultiOrgEnabled,
   resolveOrgLimit,
   resolveSandboxTimeoutMs,
-  resolveSearchPinyinEnabled
+  resolveSearchPinyinEnabled,
+  resolveTenancyPosture
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/env.ts","../src/module-not-found.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport * from './env.js';\nexport * from './module-not-found.js';\n\n// Placeholder for Kernel interface to avoid circular dependency\n// The actual Kernel implementation will satisfy this interface.\nexport interface IKernel {\n    // We can add specific methods here that plugins are allowed to call\n    // forcing a stricter contract than exposing the whole class.\n    ql?: any; // ObjectQL instance (optional to support initialization phase)\n    start(): Promise<void>;\n    // ... expose other needed public methods\n    [key: string]: any; \n}\n\nexport interface RuntimeContext {\n    engine: IKernel;\n}\n\nexport interface RuntimePlugin {\n    name: string;\n    install?: (ctx: RuntimeContext) => void | Promise<void>;\n    onStart?: (ctx: RuntimeContext) => void | Promise<void>;\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @param options    Optional behaviour flags. Set `silent: true` for aliases\n *                   that remain accepted conventions rather than true legacy\n *                   names — e.g. `PORT`, which PaaS platforms (Render, Railway,\n *                   Heroku, Fly, …) inject automatically. Warning on those\n *                   would nag operators about env they never set.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n  options?: { silent?: boolean },\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!options?.silent && !_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve whether the deployment runs in multi-org (a.k.a. multi-tenant) mode.\n *\n * Single source of truth for the `OS_MULTI_ORG_ENABLED` flag. Resolution: the\n * canonical `OS_MULTI_ORG_ENABLED`; else `false`. Any value other than a\n * case-insensitive `'false'` enables it. (The legacy `OS_MULTI_TENANT` alias was\n * removed in 11.0.)\n *\n * Every site that needs to know \"is this multi-org?\" — the SQL driver's\n * tenant-audit gate, the auth manager's `/auth/config` feature flag and\n * org-create guard, the CLI / dev / runtime org-scoping plugin wiring — MUST\n * call this instead of re-reading the env, so the driver, the security layer,\n * and the UI can never disagree about the mode. Previously each site inlined\n * its own `String(... ?? 'false').toLowerCase() !== 'false'` (and the SQL\n * driver read `process.env` directly, skipping the deprecation warning).\n *\n * Reads `process.env` live on each call; memoise at the call site if the\n * result must be stable for the process lifetime.\n */\nexport function resolveMultiOrgEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MULTI_ORG_ENABLED', []);\n  return String(raw ?? 'false').toLowerCase() !== 'false';\n}\n\n/**\n * Escape hatch for the degraded-tenancy boot guard (ADR-0093 D5).\n *\n * When `OS_MULTI_ORG_ENABLED=true` but the enterprise `@objectstack/organizations`\n * package cannot provide tenant isolation, the platform refuses to boot — a\n * deployment that asked for tenant isolation must not serve traffic pretending\n * to have it (ADR-0049 at the deployment layer). Setting this to a truthy value\n * (`true`/`1`/`on`/`yes`, case-insensitive) boots anyway in an explicitly\n * *degraded* state that is branded everywhere an operator looks. Defaults OFF —\n * an unset flag means \"fail fast\".\n */\nexport function resolveAllowDegradedTenancy(): boolean {\n  const raw = readEnvWithDeprecation('OS_ALLOW_DEGRADED_TENANCY', [], { silent: true });\n  if (raw == null) return false;\n  return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n}\n\n/**\n * SINGLE decision point for \"is the MCP HTTP surface (`/api/v1/mcp`) on?\".\n *\n * MCP is a core platform capability and defaults ON: an unset\n * `OS_MCP_SERVER_ENABLED` means the surface is served. Operators opt OUT with\n * an explicit falsy value (`false`/`0`/`off`/`no`, case-insensitive); any\n * other value — including the historical `true` — keeps it on.\n *\n * Every consumer of the flag — the runtime dispatcher's `/mcp` route gate,\n * the CLI's MCP plugin auto-load, the REST `/discovery` advertisement, and\n * the auth service's OAuth/DCR follow-defaults — MUST call this instead of\n * re-reading the env, so the served route, the advertised route, and the\n * authorization track can never disagree.\n *\n * Note the asymmetry with the MCP plugin's *stdio* auto-start\n * ({@link resolveMcpStdioAutoStart}), which stays opt-in and is gated by a\n * SEPARATE switch: attaching a long-lived stdio transport to every process is\n * a side effect no default should impose, while the HTTP surface is served\n * statelessly per-request.\n */\nexport function isMcpServerEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MCP_SERVER_ENABLED', 'MCP_SERVER_ENABLED', {\n    silent: true,\n  });\n  if (raw == null) return true;\n  return !['0', 'false', 'off', 'no'].includes(raw.trim().toLowerCase());\n}\n\n/**\n * SINGLE decision point for \"should the MCP plugin auto-start a long-lived\n * (stdio) transport?\" — distinct from {@link isMcpServerEnabled}, which governs\n * the stateless HTTP surface.\n *\n * The stdio transport is a different, stricter posture: the plugin bridges the\n * RAW metadata service + data engine onto the long-lived server with NO\n * per-request principal (unscoped — see the `mcp-stdio-authority` conformance\n * row), so it is safe only as a single-operator LOCAL tool and MUST stay\n * opt-in. It defaults OFF.\n *\n * Canonical switch: `OS_MCP_STDIO_ENABLED` (truthy). The plugin also starts it\n * when constructed with `{ autoStart: true }` (that path is checked by the\n * caller, not here).\n *\n * DEPRECATED alias: `OS_MCP_SERVER_ENABLED=true` historically ALSO started\n * stdio — overloading the very var that gates the HTTP surface, so an operator\n * setting it to \"make sure MCP is on\" silently attached an unscoped transport.\n * That trigger still works (with a one-time warning from the caller) for one\n * release; prefer the dedicated var. Note `OS_MCP_SERVER_ENABLED=false` only\n * ever gated the HTTP surface and never started stdio, so it is unaffected.\n *\n * @returns `enabled` — whether stdio auto-start is requested by the env; and\n *   `viaDeprecatedAlias` — whether it came through the legacy\n *   `OS_MCP_SERVER_ENABLED=true` trigger (so the caller can warn once).\n */\nexport function resolveMcpStdioAutoStart(): { enabled: boolean; viaDeprecatedAlias: boolean } {\n  const stdio = readEnvWithDeprecation('OS_MCP_STDIO_ENABLED', [], { silent: true });\n  if (stdio != null && ['1', 'true', 'on', 'yes'].includes(stdio.trim().toLowerCase())) {\n    return { enabled: true, viaDeprecatedAlias: false };\n  }\n  // Legacy trigger: only the literal `true` ever started stdio (preserved\n  // exactly). `OS_MCP_SERVER_ENABLED=false`/other values never did.\n  const legacy = readEnvWithDeprecation('OS_MCP_SERVER_ENABLED', 'MCP_SERVER_ENABLED', { silent: true });\n  if (legacy != null && legacy.trim().toLowerCase() === 'true') {\n    return { enabled: true, viaDeprecatedAlias: true };\n  }\n  return { enabled: false, viaDeprecatedAlias: false };\n}\n\n/**\n * Maximum number of organizations a single user may CREATE, from `OS_ORG_LIMIT`.\n * The auth plugin forwards this as better-auth's `organizationLimit` in function\n * form, counting only the caller's `role=owner` memberships — so it caps\n * self-created orgs (each of which can auto-provision a free environment on the\n * cloud control plane) without penalising a user invited into many orgs.\n *\n * Only meaningful when multi-org is enabled ({@link resolveMultiOrgEnabled}).\n * Returns `undefined` when unset or non-positive → no limit (better-auth treats\n * an absent `organizationLimit` as unlimited), preserving self-host behaviour.\n * Deployments that let users self-create orgs SHOULD set a generous cap.\n */\nexport function resolveOrgLimit(): number | undefined {\n  const raw = readEnvWithDeprecation('OS_ORG_LIMIT', [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return undefined;\n  const n = Number.parseInt(String(raw), 10);\n  return Number.isFinite(n) && n > 0 ? n : undefined;\n}\n\n/**\n * SINGLE decision point for \"is pinyin search recall on?\" (#2486).\n *\n * Pinyin search is a deployment/locale-level capability, not field metadata:\n * Chinese deployments want it, pure-Japanese/English deployments don't. The\n * flag gates the whole feature end-to-end — the SchemaRegistry's compile-time\n * `__search` companion-column seam AND the `plugin-pinyin-search` populate\n * hooks — so there is no half-state where a column exists but nobody fills it\n * (ADR-0049: no declared-but-unenforced capability).\n *\n * Resolution:\n *   1. An explicit `OS_SEARCH_PINYIN_ENABLED` always wins — truthy\n *      (`1`/`true`/`on`/`yes`) enables, anything else disables.\n *   2. When unset, the default derives from the deployment's configured\n *      locales (`opts.locales`, e.g. the stack's `i18n.defaultLocale` +\n *      `supportedLocales`): any `zh-*` locale turns it on.\n *   3. No env var and no `zh-*` locale → off. OSS / non-Chinese deployments\n *      never load `pinyin-pro` and pay zero compute cost.\n *\n * Hosts that know the stack's i18n config (the CLI `serve` boot path) resolve\n * once with locales and stamp the decision back into the env, so downstream\n * consumers constructed without config access (per-engine SchemaRegistry)\n * read the same answer via the no-arg form.\n */\nexport function resolveSearchPinyinEnabled(opts?: { locales?: readonly string[] }): boolean {\n  const raw = readEnvWithDeprecation('OS_SEARCH_PINYIN_ENABLED', [], { silent: true });\n  if (raw != null && String(raw).trim() !== '') {\n    return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n  }\n  return (opts?.locales ?? []).some((l) => /^zh([-_]|$)/i.test(String(l ?? '').trim()));\n}\n\n/**\n * SINGLE decision point for a sandbox script-runner DEFAULT (ms), resolved from\n * the environment (framework#3259 / ADR-0102).\n *\n * The QuickJS sandbox meters each hook/action invocation against a per-invocation\n * budget. Two dimensions are env-tunable:\n *   - the **CPU-time budget** for hooks / actions — how much *VM-active* time a\n *     body may burn (built-in 250ms hooks / 5000ms actions); and\n *   - the **wall-clock ceiling** — the backstop bounding a body parked forever on\n *     a host call that never settles (built-in 30_000ms).\n *\n * The built-in defaults suit a warm, idle host; a heavily loaded or slow host\n * (an oversubscribed CI runner, constrained production hardware) may need a\n * higher floor. This lets an operator raise it once, deployment-wide, instead of\n * re-tuning every call site.\n *\n * Canonical vars (OS_{DOMAIN}_{NAME}, DOMAIN=SANDBOX):\n *   - hook        → `OS_SANDBOX_HOOK_TIMEOUT_MS`\n *   - action      → `OS_SANDBOX_ACTION_TIMEOUT_MS`\n *   - wallCeiling → `OS_SANDBOX_WALL_CEILING_MS`\n *\n * Only a positive integer is honored; unset / empty / non-numeric / non-positive\n * falls back to `fallback`, so behaviour is byte-for-byte unchanged when the var\n * is absent. This is a FALLBACK default ONLY: an explicit constructor option\n * still wins over it, and (for the CPU budget) a body's own declared `timeoutMs`\n * still wins over the resolved default per the runner's resolution rule.\n */\nexport function resolveSandboxTimeoutMs(\n  kind: 'hook' | 'action' | 'wallCeiling',\n  fallback: number,\n): number {\n  const name =\n    kind === 'hook'\n      ? 'OS_SANDBOX_HOOK_TIMEOUT_MS'\n      : kind === 'action'\n        ? 'OS_SANDBOX_ACTION_TIMEOUT_MS'\n        : 'OS_SANDBOX_WALL_CEILING_MS';\n  const raw = readEnvWithDeprecation(name, [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return fallback;\n  const n = Number.parseInt(String(raw).trim(), 10);\n  return Number.isFinite(n) && n > 0 ? n : fallback;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * True when a dynamic `import()` / `require.resolve()` failed because the\n * module is simply NOT INSTALLED — as opposed to the module being present but\n * throwing while it loads (a real crash). Checking `err.code` FIRST matters:\n * ESM reports a missing package as `err.code === 'ERR_MODULE_NOT_FOUND'` with\n * the human message `Cannot find package '...'`; matching only the older\n * `Cannot find module` string mis-classifies that as a crash (framework#1595).\n *\n * Single shared owner for this classification (framework#3265): the CLI's\n * optional-plugin guards and `requires` capability resolver delegate here, and\n * cloud's `objectos-runtime` capability loader is expected to adopt it at its\n * next framework pin bump — so the parallel loaders cannot drift apart and\n * re-introduce the #1595 false-alarm class.\n */\nexport function isModuleNotFoundError(err: unknown): boolean {\n  const code = (err as { code?: string } | null | undefined)?.code;\n  if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') return true;\n  const msg = err instanceof Error ? err.message : String(err);\n  return msg.includes('Cannot find module') || msg.includes('Cannot find package');\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/degraded-boot.ts","../src/env.ts","../src/error-leak.ts","../src/module-not-found.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport * from './degraded-boot.js';\nexport * from './env.js';\nexport * from './error-leak.js';\nexport * from './module-not-found.js';\n\n// Placeholder for Kernel interface to avoid circular dependency\n// The actual Kernel implementation will satisfy this interface.\nexport interface IKernel {\n    // We can add specific methods here that plugins are allowed to call\n    // forcing a stricter contract than exposing the whole class.\n    ql?: any; // ObjectQL instance (optional to support initialization phase)\n    start(): Promise<void>;\n    // ... expose other needed public methods\n    [key: string]: any; \n}\n\nexport interface RuntimeContext {\n    engine: IKernel;\n}\n\nexport interface RuntimePlugin {\n    name: string;\n    install?: (ctx: RuntimeContext) => void | Promise<void>;\n    onStart?: (ctx: RuntimeContext) => void | Promise<void>;\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Degraded-boot reporting, shared by every subsystem that can be told to boot\n * without a datasource it needs.\n *\n * Two of them exist today and they opt in through the *same* operator flag\n * (`OS_ALLOW_DRIVER_CONNECT_FAILURE`, see {@link resolveAllowDriverConnectFailure}):\n *\n *  - `ObjectQLEngine.init()` — a boot-registered driver whose `connect()`\n *    rejected (framework#3741).\n *  - `DatasourceConnectionService` — a declared datasource that objects bind to\n *    explicitly, or an `external` one with `validation.onMismatch:'fail'`,\n *    that could not be connected (framework#3758).\n *\n * They live in different packages but owe the operator the same thing: the\n * degraded state must be impossible to miss.\n */\n\n/**\n * Emit the degraded-boot banner on a channel the host cannot accidentally\n * silence.\n *\n * `OS_ALLOW_DRIVER_CONNECT_FAILURE` only justifies itself if the state it opts\n * into is impossible to miss — and a logger-only banner is missable: `os serve`\n * swallows ALL of stdout while the kernel boots (its \"boot-quiet\" capture), and\n * `Logger` routes `warn` to stdout, so the one message that matters would be\n * invisible in exactly the situation it exists for. Writing to stderr as well\n * is the same belt-and-braces the kernel already uses for plugin startup\n * failures.\n *\n * Best-effort and never throws: falls back to `console.error`, then to silence\n * on runtimes that have neither (the logger still carries the structured\n * record either way).\n */\nexport function emitDegradedBootBanner(message: string): void {\n  const proc = (globalThis as {\n    process?: { stderr?: { write?: (chunk: string) => unknown } };\n  }).process;\n  try {\n    if (typeof proc?.stderr?.write === 'function') {\n      proc.stderr.write(`${message}\\n`);\n      return;\n    }\n  } catch {\n    /* stderr unavailable / closed — fall through to console */\n  }\n  try {\n    (globalThis as { console?: { error?: (msg: string) => void } }).console?.error?.(message);\n  } catch {\n    /* no output channel at all — the logger record is the remaining trace */\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nimport {\n  normalizeTenancyPosture,\n  TENANCY_POSTURES,\n  type TenancyPosture,\n} from '@objectstack/spec/security';\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @param options    Optional behaviour flags. Set `silent: true` for aliases\n *                   that remain accepted conventions rather than true legacy\n *                   names — e.g. `PORT`, which PaaS platforms (Render, Railway,\n *                   Heroku, Fly, …) inject automatically. Warning on those\n *                   would nag operators about env they never set.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n  options?: { silent?: boolean },\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!options?.silent && !_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve whether the deployment runs in multi-org (a.k.a. multi-tenant) mode.\n *\n * Single source of truth for the `OS_MULTI_ORG_ENABLED` flag. Resolution: the\n * canonical `OS_MULTI_ORG_ENABLED`; else `false`. Any value other than a\n * case-insensitive `'false'` enables it. (The legacy `OS_MULTI_TENANT` alias was\n * removed in 11.0.)\n *\n * Every site that needs to know \"is this multi-org?\" — the SQL driver's\n * tenant-audit gate, the auth manager's `/auth/config` feature flag and\n * org-create guard, the CLI / dev / runtime org-scoping plugin wiring — MUST\n * call this instead of re-reading the env, so the driver, the security layer,\n * and the UI can never disagree about the mode. Previously each site inlined\n * its own `String(... ?? 'false').toLowerCase() !== 'false'` (and the SQL\n * driver read `process.env` directly, skipping the deprecation warning).\n *\n * Reads `process.env` live on each call; memoise at the call site if the\n * result must be stable for the process lifetime.\n */\nexport function resolveMultiOrgEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MULTI_ORG_ENABLED', []);\n  return String(raw ?? 'false').toLowerCase() !== 'false';\n}\n\n/**\n * [ADR-0105 D1] Resolve the deployment's REQUESTED tenancy posture —\n * `single` | `group` | `isolated`.\n *\n * `OS_TENANCY_POSTURE` is the canonical knob and generalizes the boolean\n * `OS_MULTI_ORG_ENABLED` it supersedes:\n *\n * - set → that posture (the legacy spelling `multi` normalizes to `isolated`)\n * - unset → derived from `OS_MULTI_ORG_ENABLED`: `true` ⇒ `isolated`, else `single`\n *\n * so every existing deployment keeps its current posture with no config change.\n *\n * An unrecognized value THROWS rather than falling back. A typo'd posture that\n * quietly resolved to `single` would silently remove the organization wall —\n * the deployment-layer form of the \"declared but unenforced\" defect ADR-0049\n * forbids, and the same reasoning behind ADR-0093 D5's refusal to boot into\n * undeclared degradation.\n *\n * This resolves what the operator ASKED FOR. Whether the posture is actually\n * enforced is the `tenancy` service's answer (`isolationActive` / `degraded`).\n */\nexport function resolveTenancyPosture(): TenancyPosture {\n  // Read through `globalThis` like `readEnvWithDeprecation` does — this package\n  // targets non-Node runtimes too, where a bare `process` reference throws.\n  const raw = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env?.OS_TENANCY_POSTURE;\n  if (raw != null && String(raw).trim() !== '') {\n    const posture = normalizeTenancyPosture(raw);\n    if (!posture) {\n      throw new Error(\n        `Invalid OS_TENANCY_POSTURE=${JSON.stringify(String(raw))}. ` +\n          `Expected one of: ${TENANCY_POSTURES.join(', ')} (or the legacy alias 'multi' = 'isolated'). ` +\n          'Refusing to boot rather than silently falling back to a posture with no organization wall.',\n      );\n    }\n    return posture;\n  }\n  return resolveMultiOrgEnabled() ? 'isolated' : 'single';\n}\n\n/**\n * Escape hatch for the degraded-tenancy boot guard (ADR-0093 D5).\n *\n * When `OS_MULTI_ORG_ENABLED=true` but the enterprise `@objectstack/organizations`\n * package cannot provide tenant isolation, the platform refuses to boot — a\n * deployment that asked for tenant isolation must not serve traffic pretending\n * to have it (ADR-0049 at the deployment layer). Setting this to a truthy value\n * (`true`/`1`/`on`/`yes`, case-insensitive) boots anyway in an explicitly\n * *degraded* state that is branded everywhere an operator looks. Defaults OFF —\n * an unset flag means \"fail fast\".\n */\nexport function resolveAllowDegradedTenancy(): boolean {\n  const raw = readEnvWithDeprecation('OS_ALLOW_DEGRADED_TENANCY', [], { silent: true });\n  if (raw == null) return false;\n  return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n}\n\n/**\n * Escape hatch for the driver-connect boot guard (framework#3741).\n *\n * `ObjectQLEngine.init()` connects every boot-registered driver and, by\n * default, refuses to boot when any of them fails — a server whose database is\n * unreachable must not report itself started and then 500 every request with an\n * error that reads nothing like \"the database is down\". Failing there is also\n * what gives a driver the ability to REFUSE STARTUP at all: any fatal startup\n * check a driver wants to run (licence, server version, incompatible\n * configuration, missing capability) can simply throw from `connect()`.\n *\n * Setting this to a truthy value (`true`/`1`/`on`/`yes`, case-insensitive)\n * boots anyway, in an explicitly degraded state that is logged loudly at\n * startup. Every query routed to a failed driver fails until the datasource\n * becomes reachable — the underlying clients do re-establish connections on\n * their own (framework#3759) — but the boot-time schema sync those drivers\n * missed is never re-run, so their tables may simply not exist afterwards.\n * Defaults OFF — an unset flag means \"fail fast\".\n */\nexport function resolveAllowDriverConnectFailure(): boolean {\n  const raw = readEnvWithDeprecation('OS_ALLOW_DRIVER_CONNECT_FAILURE', [], { silent: true });\n  if (raw == null) return false;\n  return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n}\n\n/**\n * SINGLE decision point for \"is the MCP HTTP surface (`/api/v1/mcp`) on?\".\n *\n * MCP is a core platform capability and defaults ON: an unset\n * `OS_MCP_SERVER_ENABLED` means the surface is served. Operators opt OUT with\n * an explicit falsy value (`false`/`0`/`off`/`no`, case-insensitive); any\n * other value — including the historical `true` — keeps it on.\n *\n * Every consumer of the flag — the runtime dispatcher's `/mcp` route gate,\n * the CLI's MCP plugin auto-load, the REST `/discovery` advertisement, and\n * the auth service's OAuth/DCR follow-defaults — MUST call this instead of\n * re-reading the env, so the served route, the advertised route, and the\n * authorization track can never disagree.\n *\n * Note the asymmetry with the MCP plugin's *stdio* auto-start\n * ({@link resolveMcpStdioAutoStart}), which stays opt-in and is gated by a\n * SEPARATE switch: attaching a long-lived stdio transport to every process is\n * a side effect no default should impose, while the HTTP surface is served\n * statelessly per-request.\n */\nexport function isMcpServerEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MCP_SERVER_ENABLED', 'MCP_SERVER_ENABLED', {\n    silent: true,\n  });\n  if (raw == null) return true;\n  return !['0', 'false', 'off', 'no'].includes(raw.trim().toLowerCase());\n}\n\n/**\n * SINGLE decision point for \"should the MCP plugin auto-start a long-lived\n * (stdio) transport?\" — distinct from {@link isMcpServerEnabled}, which governs\n * the stateless HTTP surface.\n *\n * The stdio transport is a different, stricter posture: the plugin bridges the\n * RAW metadata service + data engine onto the long-lived server with NO\n * per-request principal (unscoped — see the `mcp-stdio-authority` conformance\n * row), so it is safe only as a single-operator LOCAL tool and MUST stay\n * opt-in. It defaults OFF.\n *\n * Canonical switch: `OS_MCP_STDIO_ENABLED` (truthy). The plugin also starts it\n * when constructed with `{ autoStart: true }` (that path is checked by the\n * caller, not here).\n *\n * DEPRECATED alias: `OS_MCP_SERVER_ENABLED=true` historically ALSO started\n * stdio — overloading the very var that gates the HTTP surface, so an operator\n * setting it to \"make sure MCP is on\" silently attached an unscoped transport.\n * That trigger still works (with a one-time warning from the caller) for one\n * release; prefer the dedicated var. Note `OS_MCP_SERVER_ENABLED=false` only\n * ever gated the HTTP surface and never started stdio, so it is unaffected.\n *\n * @returns `enabled` — whether stdio auto-start is requested by the env; and\n *   `viaDeprecatedAlias` — whether it came through the legacy\n *   `OS_MCP_SERVER_ENABLED=true` trigger (so the caller can warn once).\n */\nexport function resolveMcpStdioAutoStart(): { enabled: boolean; viaDeprecatedAlias: boolean } {\n  const stdio = readEnvWithDeprecation('OS_MCP_STDIO_ENABLED', [], { silent: true });\n  if (stdio != null && ['1', 'true', 'on', 'yes'].includes(stdio.trim().toLowerCase())) {\n    return { enabled: true, viaDeprecatedAlias: false };\n  }\n  // Legacy trigger: only the literal `true` ever started stdio (preserved\n  // exactly). `OS_MCP_SERVER_ENABLED=false`/other values never did.\n  const legacy = readEnvWithDeprecation('OS_MCP_SERVER_ENABLED', 'MCP_SERVER_ENABLED', { silent: true });\n  if (legacy != null && legacy.trim().toLowerCase() === 'true') {\n    return { enabled: true, viaDeprecatedAlias: true };\n  }\n  return { enabled: false, viaDeprecatedAlias: false };\n}\n\n/**\n * Maximum number of organizations a single user may CREATE, from `OS_ORG_LIMIT`.\n * The auth plugin forwards this as better-auth's `organizationLimit` in function\n * form, counting only the caller's `role=owner` memberships — so it caps\n * self-created orgs (each of which can auto-provision a free environment on the\n * cloud control plane) without penalising a user invited into many orgs.\n *\n * Only meaningful when multi-org is enabled ({@link resolveMultiOrgEnabled}).\n * Returns `undefined` when unset or non-positive → no limit (better-auth treats\n * an absent `organizationLimit` as unlimited), preserving self-host behaviour.\n * Deployments that let users self-create orgs SHOULD set a generous cap.\n */\nexport function resolveOrgLimit(): number | undefined {\n  const raw = readEnvWithDeprecation('OS_ORG_LIMIT', [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return undefined;\n  const n = Number.parseInt(String(raw), 10);\n  return Number.isFinite(n) && n > 0 ? n : undefined;\n}\n\n/**\n * SINGLE decision point for \"is pinyin search recall on?\" (#2486).\n *\n * Pinyin search is a deployment/locale-level capability, not field metadata:\n * Chinese deployments want it, pure-Japanese/English deployments don't. The\n * flag gates the whole feature end-to-end — the SchemaRegistry's compile-time\n * `__search` companion-column seam AND the `plugin-pinyin-search` populate\n * hooks — so there is no half-state where a column exists but nobody fills it\n * (ADR-0049: no declared-but-unenforced capability).\n *\n * Resolution:\n *   1. An explicit `OS_SEARCH_PINYIN_ENABLED` always wins — truthy\n *      (`1`/`true`/`on`/`yes`) enables, anything else disables.\n *   2. When unset, the default derives from the deployment's configured\n *      locales (`opts.locales`, e.g. the stack's `i18n.defaultLocale` +\n *      `supportedLocales`): any `zh-*` locale turns it on.\n *   3. No env var and no `zh-*` locale → off. OSS / non-Chinese deployments\n *      never load `pinyin-pro` and pay zero compute cost.\n *\n * Hosts that know the stack's i18n config (the CLI `serve` boot path) resolve\n * once with locales and stamp the decision back into the env, so downstream\n * consumers constructed without config access (per-engine SchemaRegistry)\n * read the same answer via the no-arg form.\n */\nexport function resolveSearchPinyinEnabled(opts?: { locales?: readonly string[] }): boolean {\n  const raw = readEnvWithDeprecation('OS_SEARCH_PINYIN_ENABLED', [], { silent: true });\n  if (raw != null && String(raw).trim() !== '') {\n    return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n  }\n  return (opts?.locales ?? []).some((l) => /^zh([-_]|$)/i.test(String(l ?? '').trim()));\n}\n\n/**\n * SINGLE decision point for a sandbox script-runner DEFAULT (ms), resolved from\n * the environment (framework#3259 / ADR-0102).\n *\n * The QuickJS sandbox meters each hook/action invocation against a per-invocation\n * budget. Two dimensions are env-tunable:\n *   - the **CPU-time budget** for hooks / actions — how much *VM-active* time a\n *     body may burn (built-in 250ms hooks / 5000ms actions); and\n *   - the **wall-clock ceiling** — the backstop bounding a body parked forever on\n *     a host call that never settles (built-in 30_000ms).\n *\n * The built-in defaults suit a warm, idle host; a heavily loaded or slow host\n * (an oversubscribed CI runner, constrained production hardware) may need a\n * higher floor. This lets an operator raise it once, deployment-wide, instead of\n * re-tuning every call site.\n *\n * Canonical vars (OS_{DOMAIN}_{NAME}, DOMAIN=SANDBOX):\n *   - hook        → `OS_SANDBOX_HOOK_TIMEOUT_MS`\n *   - action      → `OS_SANDBOX_ACTION_TIMEOUT_MS`\n *   - wallCeiling → `OS_SANDBOX_WALL_CEILING_MS`\n *\n * Only a positive integer is honored; unset / empty / non-numeric / non-positive\n * falls back to `fallback`, so behaviour is byte-for-byte unchanged when the var\n * is absent. This is a FALLBACK default ONLY: an explicit constructor option\n * still wins over it, and (for the CPU budget) a body's own declared `timeoutMs`\n * still wins over the resolved default per the runner's resolution rule.\n */\nexport function resolveSandboxTimeoutMs(\n  kind: 'hook' | 'action' | 'wallCeiling',\n  fallback: number,\n): number {\n  const name =\n    kind === 'hook'\n      ? 'OS_SANDBOX_HOOK_TIMEOUT_MS'\n      : kind === 'action'\n        ? 'OS_SANDBOX_ACTION_TIMEOUT_MS'\n        : 'OS_SANDBOX_WALL_CEILING_MS';\n  const raw = readEnvWithDeprecation(name, [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return fallback;\n  const n = Number.parseInt(String(raw).trim(), 10);\n  return Number.isFinite(n) && n > 0 ? n : fallback;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Shared \"does this error message leak server internals?\" heuristic (#3867).\n *\n * ObjectStack has more than one HTTP boundary. `@objectstack/rest` guards the\n * REST data routes inside `mapDataError`; the dispatcher-plugin routes\n * (`/analytics`, `/packages`, `/i18n`, `/storage`, `/automation`, …) exit\n * through `errorResponseBase`. Before #3867 only the first of those sanitised\n * anything, so a driver error raised under `/analytics/query` reached the\n * client verbatim — a real SQL statement in the response body:\n *\n * ```\n * {\"success\":false,\"error\":{\"message\":\"SELECT  FROM \\\"sqlite_sequence\\\" - near \\\"FROM\\\": syntax error\",\"code\":500}}\n * ```\n *\n * \"Do not ship driver internals to clients\" is a property of the HTTP\n * boundary, not of one router, so the predicate lives here — the package both\n * `@objectstack/rest` and `@objectstack/runtime` already depend on — and each\n * boundary applies it in its own envelope. One heuristic, one place to widen\n * when a new dialect's phrasing shows up.\n *\n * Deliberately a *heuristic over the message*, not a driver taxonomy: these\n * errors arrive as plain `Error`s from a half-dozen dialects with no shared\n * shape. It is applied only where the outcome is already a 5xx, so a false\n * positive costs a caller nothing but detail on a response that was a server\n * fault anyway — while the full text still reaches server logs and the\n * error reporter.\n */\n\n/** Generic replacement text for a message that trips {@link looksLikeInternalErrorLeak}. */\nexport const INTERNAL_ERROR_MESSAGE = 'Internal server error';\n\n/**\n * Whether `message` looks like a raw SQL statement or driver/engine dump that\n * must not be returned to an API client.\n *\n * Matches: dialect error codes (`SQLSTATE`, `sqlite_*`), bare statements\n * (a message that *starts* as `SELECT`/`INSERT INTO`/`UPDATE`/`DELETE FROM` —\n * drivers prefix the offending SQL to their message), and constraint-violation\n * dumps, which name physical tables and columns.\n *\n * Does NOT match ordinary business or validation messages, which is why the\n * statement forms are anchored with `startsWith`: a legitimate message may\n * *mention* \"update\" without being one.\n */\nexport function looksLikeInternalErrorLeak(message: string | undefined | null): boolean {\n  if (!message) return false;\n  const lower = String(message).toLowerCase();\n  return (\n    lower.includes('sqlite_') ||\n    lower.includes('sqlstate') ||\n    lower.startsWith('insert into ') ||\n    lower.startsWith('update ') ||\n    lower.startsWith('select ') ||\n    lower.startsWith('delete from ') ||\n    lower.includes('constraint failed') ||\n    lower.includes('unique constraint') ||\n    lower.includes('foreign key')\n  );\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * True when a dynamic `import()` / `require.resolve()` failed because the\n * module is simply NOT INSTALLED — as opposed to the module being present but\n * throwing while it loads (a real crash). Checking `err.code` FIRST matters:\n * ESM reports a missing package as `err.code === 'ERR_MODULE_NOT_FOUND'` with\n * the human message `Cannot find package '...'`; matching only the older\n * `Cannot find module` string mis-classifies that as a crash (framework#1595).\n *\n * Single shared owner for this classification (framework#3265): the CLI's\n * optional-plugin guards and `requires` capability resolver delegate here, and\n * cloud's `objectos-runtime` capability loader is expected to adopt it at its\n * next framework pin bump — so the parallel loaders cannot drift apart and\n * re-introduce the #1595 false-alarm class.\n */\nexport function isModuleNotFoundError(err: unknown): boolean {\n  const code = (err as { code?: string } | null | undefined)?.code;\n  if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') return true;\n  const msg = err instanceof Error ? err.message : String(err);\n  return msg.includes('Cannot find module') || msg.includes('Cannot find package');\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -1,4 +1,25 @@
+// src/degraded-boot.ts
+function emitDegradedBootBanner(message) {
+  const proc = globalThis.process;
+  try {
+    if (typeof proc?.stderr?.write === "function") {
+      proc.stderr.write(`${message}
+`);
+      return;
+    }
+  } catch {
+  }
+  try {
+    globalThis.console?.error?.(message);
+  } catch {
+  }
+}
+
 // src/env.ts
+import {
+  normalizeTenancyPosture,
+  TENANCY_POSTURES
+} from "@objectstack/spec/security";
 var _warnedKeys = /* @__PURE__ */ new Set();
 function readEnvWithDeprecation(preferred, legacy, options) {
   const env = globalThis.process?.env;
@@ -29,11 +50,29 @@ function resolveMultiOrgEnabled() {
   const raw = readEnvWithDeprecation("OS_MULTI_ORG_ENABLED", []);
   return String(raw ?? "false").toLowerCase() !== "false";
 }
+function resolveTenancyPosture() {
+  const raw = globalThis.process?.env?.OS_TENANCY_POSTURE;
+  if (raw != null && String(raw).trim() !== "") {
+    const posture = normalizeTenancyPosture(raw);
+    if (!posture) {
+      throw new Error(
+        `Invalid OS_TENANCY_POSTURE=${JSON.stringify(String(raw))}. Expected one of: ${TENANCY_POSTURES.join(", ")} (or the legacy alias 'multi' = 'isolated'). Refusing to boot rather than silently falling back to a posture with no organization wall.`
+      );
+    }
+    return posture;
+  }
+  return resolveMultiOrgEnabled() ? "isolated" : "single";
+}
 function resolveAllowDegradedTenancy() {
   const raw = readEnvWithDeprecation("OS_ALLOW_DEGRADED_TENANCY", [], { silent: true });
   if (raw == null) return false;
   return ["1", "true", "on", "yes"].includes(String(raw).trim().toLowerCase());
 }
+function resolveAllowDriverConnectFailure() {
+  const raw = readEnvWithDeprecation("OS_ALLOW_DRIVER_CONNECT_FAILURE", [], { silent: true });
+  if (raw == null) return false;
+  return ["1", "true", "on", "yes"].includes(String(raw).trim().toLowerCase());
+}
 function isMcpServerEnabled() {
   const raw = readEnvWithDeprecation("OS_MCP_SERVER_ENABLED", "MCP_SERVER_ENABLED", {
     silent: true
@@ -76,6 +115,14 @@ function _resetEnvDeprecationWarnings() {
   _warnedKeys.clear();
 }
 
+// src/error-leak.ts
+var INTERNAL_ERROR_MESSAGE = "Internal server error";
+function looksLikeInternalErrorLeak(message) {
+  if (!message) return false;
+  const lower = String(message).toLowerCase();
+  return lower.includes("sqlite_") || lower.includes("sqlstate") || lower.startsWith("insert into ") || lower.startsWith("update ") || lower.startsWith("select ") || lower.startsWith("delete from ") || lower.includes("constraint failed") || lower.includes("unique constraint") || lower.includes("foreign key");
+}
+
 // src/module-not-found.ts
 function isModuleNotFoundError(err) {
   const code = err?.code;
@@ -84,15 +131,20 @@ function isModuleNotFoundError(err) {
   return msg.includes("Cannot find module") || msg.includes("Cannot find package");
 }
 export {
+  INTERNAL_ERROR_MESSAGE,
   _resetEnvDeprecationWarnings,
+  emitDegradedBootBanner,
   isMcpServerEnabled,
   isModuleNotFoundError,
+  looksLikeInternalErrorLeak,
   readEnvWithDeprecation,
   resolveAllowDegradedTenancy,
+  resolveAllowDriverConnectFailure,
   resolveMcpStdioAutoStart,
   resolveMultiOrgEnabled,
   resolveOrgLimit,
   resolveSandboxTimeoutMs,
-  resolveSearchPinyinEnabled
+  resolveSearchPinyinEnabled,
+  resolveTenancyPosture
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/env.ts","../src/module-not-found.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @param options    Optional behaviour flags. Set `silent: true` for aliases\n *                   that remain accepted conventions rather than true legacy\n *                   names — e.g. `PORT`, which PaaS platforms (Render, Railway,\n *                   Heroku, Fly, …) inject automatically. Warning on those\n *                   would nag operators about env they never set.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n  options?: { silent?: boolean },\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!options?.silent && !_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve whether the deployment runs in multi-org (a.k.a. multi-tenant) mode.\n *\n * Single source of truth for the `OS_MULTI_ORG_ENABLED` flag. Resolution: the\n * canonical `OS_MULTI_ORG_ENABLED`; else `false`. Any value other than a\n * case-insensitive `'false'` enables it. (The legacy `OS_MULTI_TENANT` alias was\n * removed in 11.0.)\n *\n * Every site that needs to know \"is this multi-org?\" — the SQL driver's\n * tenant-audit gate, the auth manager's `/auth/config` feature flag and\n * org-create guard, the CLI / dev / runtime org-scoping plugin wiring — MUST\n * call this instead of re-reading the env, so the driver, the security layer,\n * and the UI can never disagree about the mode. Previously each site inlined\n * its own `String(... ?? 'false').toLowerCase() !== 'false'` (and the SQL\n * driver read `process.env` directly, skipping the deprecation warning).\n *\n * Reads `process.env` live on each call; memoise at the call site if the\n * result must be stable for the process lifetime.\n */\nexport function resolveMultiOrgEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MULTI_ORG_ENABLED', []);\n  return String(raw ?? 'false').toLowerCase() !== 'false';\n}\n\n/**\n * Escape hatch for the degraded-tenancy boot guard (ADR-0093 D5).\n *\n * When `OS_MULTI_ORG_ENABLED=true` but the enterprise `@objectstack/organizations`\n * package cannot provide tenant isolation, the platform refuses to boot — a\n * deployment that asked for tenant isolation must not serve traffic pretending\n * to have it (ADR-0049 at the deployment layer). Setting this to a truthy value\n * (`true`/`1`/`on`/`yes`, case-insensitive) boots anyway in an explicitly\n * *degraded* state that is branded everywhere an operator looks. Defaults OFF —\n * an unset flag means \"fail fast\".\n */\nexport function resolveAllowDegradedTenancy(): boolean {\n  const raw = readEnvWithDeprecation('OS_ALLOW_DEGRADED_TENANCY', [], { silent: true });\n  if (raw == null) return false;\n  return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n}\n\n/**\n * SINGLE decision point for \"is the MCP HTTP surface (`/api/v1/mcp`) on?\".\n *\n * MCP is a core platform capability and defaults ON: an unset\n * `OS_MCP_SERVER_ENABLED` means the surface is served. Operators opt OUT with\n * an explicit falsy value (`false`/`0`/`off`/`no`, case-insensitive); any\n * other value — including the historical `true` — keeps it on.\n *\n * Every consumer of the flag — the runtime dispatcher's `/mcp` route gate,\n * the CLI's MCP plugin auto-load, the REST `/discovery` advertisement, and\n * the auth service's OAuth/DCR follow-defaults — MUST call this instead of\n * re-reading the env, so the served route, the advertised route, and the\n * authorization track can never disagree.\n *\n * Note the asymmetry with the MCP plugin's *stdio* auto-start\n * ({@link resolveMcpStdioAutoStart}), which stays opt-in and is gated by a\n * SEPARATE switch: attaching a long-lived stdio transport to every process is\n * a side effect no default should impose, while the HTTP surface is served\n * statelessly per-request.\n */\nexport function isMcpServerEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MCP_SERVER_ENABLED', 'MCP_SERVER_ENABLED', {\n    silent: true,\n  });\n  if (raw == null) return true;\n  return !['0', 'false', 'off', 'no'].includes(raw.trim().toLowerCase());\n}\n\n/**\n * SINGLE decision point for \"should the MCP plugin auto-start a long-lived\n * (stdio) transport?\" — distinct from {@link isMcpServerEnabled}, which governs\n * the stateless HTTP surface.\n *\n * The stdio transport is a different, stricter posture: the plugin bridges the\n * RAW metadata service + data engine onto the long-lived server with NO\n * per-request principal (unscoped — see the `mcp-stdio-authority` conformance\n * row), so it is safe only as a single-operator LOCAL tool and MUST stay\n * opt-in. It defaults OFF.\n *\n * Canonical switch: `OS_MCP_STDIO_ENABLED` (truthy). The plugin also starts it\n * when constructed with `{ autoStart: true }` (that path is checked by the\n * caller, not here).\n *\n * DEPRECATED alias: `OS_MCP_SERVER_ENABLED=true` historically ALSO started\n * stdio — overloading the very var that gates the HTTP surface, so an operator\n * setting it to \"make sure MCP is on\" silently attached an unscoped transport.\n * That trigger still works (with a one-time warning from the caller) for one\n * release; prefer the dedicated var. Note `OS_MCP_SERVER_ENABLED=false` only\n * ever gated the HTTP surface and never started stdio, so it is unaffected.\n *\n * @returns `enabled` — whether stdio auto-start is requested by the env; and\n *   `viaDeprecatedAlias` — whether it came through the legacy\n *   `OS_MCP_SERVER_ENABLED=true` trigger (so the caller can warn once).\n */\nexport function resolveMcpStdioAutoStart(): { enabled: boolean; viaDeprecatedAlias: boolean } {\n  const stdio = readEnvWithDeprecation('OS_MCP_STDIO_ENABLED', [], { silent: true });\n  if (stdio != null && ['1', 'true', 'on', 'yes'].includes(stdio.trim().toLowerCase())) {\n    return { enabled: true, viaDeprecatedAlias: false };\n  }\n  // Legacy trigger: only the literal `true` ever started stdio (preserved\n  // exactly). `OS_MCP_SERVER_ENABLED=false`/other values never did.\n  const legacy = readEnvWithDeprecation('OS_MCP_SERVER_ENABLED', 'MCP_SERVER_ENABLED', { silent: true });\n  if (legacy != null && legacy.trim().toLowerCase() === 'true') {\n    return { enabled: true, viaDeprecatedAlias: true };\n  }\n  return { enabled: false, viaDeprecatedAlias: false };\n}\n\n/**\n * Maximum number of organizations a single user may CREATE, from `OS_ORG_LIMIT`.\n * The auth plugin forwards this as better-auth's `organizationLimit` in function\n * form, counting only the caller's `role=owner` memberships — so it caps\n * self-created orgs (each of which can auto-provision a free environment on the\n * cloud control plane) without penalising a user invited into many orgs.\n *\n * Only meaningful when multi-org is enabled ({@link resolveMultiOrgEnabled}).\n * Returns `undefined` when unset or non-positive → no limit (better-auth treats\n * an absent `organizationLimit` as unlimited), preserving self-host behaviour.\n * Deployments that let users self-create orgs SHOULD set a generous cap.\n */\nexport function resolveOrgLimit(): number | undefined {\n  const raw = readEnvWithDeprecation('OS_ORG_LIMIT', [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return undefined;\n  const n = Number.parseInt(String(raw), 10);\n  return Number.isFinite(n) && n > 0 ? n : undefined;\n}\n\n/**\n * SINGLE decision point for \"is pinyin search recall on?\" (#2486).\n *\n * Pinyin search is a deployment/locale-level capability, not field metadata:\n * Chinese deployments want it, pure-Japanese/English deployments don't. The\n * flag gates the whole feature end-to-end — the SchemaRegistry's compile-time\n * `__search` companion-column seam AND the `plugin-pinyin-search` populate\n * hooks — so there is no half-state where a column exists but nobody fills it\n * (ADR-0049: no declared-but-unenforced capability).\n *\n * Resolution:\n *   1. An explicit `OS_SEARCH_PINYIN_ENABLED` always wins — truthy\n *      (`1`/`true`/`on`/`yes`) enables, anything else disables.\n *   2. When unset, the default derives from the deployment's configured\n *      locales (`opts.locales`, e.g. the stack's `i18n.defaultLocale` +\n *      `supportedLocales`): any `zh-*` locale turns it on.\n *   3. No env var and no `zh-*` locale → off. OSS / non-Chinese deployments\n *      never load `pinyin-pro` and pay zero compute cost.\n *\n * Hosts that know the stack's i18n config (the CLI `serve` boot path) resolve\n * once with locales and stamp the decision back into the env, so downstream\n * consumers constructed without config access (per-engine SchemaRegistry)\n * read the same answer via the no-arg form.\n */\nexport function resolveSearchPinyinEnabled(opts?: { locales?: readonly string[] }): boolean {\n  const raw = readEnvWithDeprecation('OS_SEARCH_PINYIN_ENABLED', [], { silent: true });\n  if (raw != null && String(raw).trim() !== '') {\n    return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n  }\n  return (opts?.locales ?? []).some((l) => /^zh([-_]|$)/i.test(String(l ?? '').trim()));\n}\n\n/**\n * SINGLE decision point for a sandbox script-runner DEFAULT (ms), resolved from\n * the environment (framework#3259 / ADR-0102).\n *\n * The QuickJS sandbox meters each hook/action invocation against a per-invocation\n * budget. Two dimensions are env-tunable:\n *   - the **CPU-time budget** for hooks / actions — how much *VM-active* time a\n *     body may burn (built-in 250ms hooks / 5000ms actions); and\n *   - the **wall-clock ceiling** — the backstop bounding a body parked forever on\n *     a host call that never settles (built-in 30_000ms).\n *\n * The built-in defaults suit a warm, idle host; a heavily loaded or slow host\n * (an oversubscribed CI runner, constrained production hardware) may need a\n * higher floor. This lets an operator raise it once, deployment-wide, instead of\n * re-tuning every call site.\n *\n * Canonical vars (OS_{DOMAIN}_{NAME}, DOMAIN=SANDBOX):\n *   - hook        → `OS_SANDBOX_HOOK_TIMEOUT_MS`\n *   - action      → `OS_SANDBOX_ACTION_TIMEOUT_MS`\n *   - wallCeiling → `OS_SANDBOX_WALL_CEILING_MS`\n *\n * Only a positive integer is honored; unset / empty / non-numeric / non-positive\n * falls back to `fallback`, so behaviour is byte-for-byte unchanged when the var\n * is absent. This is a FALLBACK default ONLY: an explicit constructor option\n * still wins over it, and (for the CPU budget) a body's own declared `timeoutMs`\n * still wins over the resolved default per the runner's resolution rule.\n */\nexport function resolveSandboxTimeoutMs(\n  kind: 'hook' | 'action' | 'wallCeiling',\n  fallback: number,\n): number {\n  const name =\n    kind === 'hook'\n      ? 'OS_SANDBOX_HOOK_TIMEOUT_MS'\n      : kind === 'action'\n        ? 'OS_SANDBOX_ACTION_TIMEOUT_MS'\n        : 'OS_SANDBOX_WALL_CEILING_MS';\n  const raw = readEnvWithDeprecation(name, [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return fallback;\n  const n = Number.parseInt(String(raw).trim(), 10);\n  return Number.isFinite(n) && n > 0 ? n : fallback;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * True when a dynamic `import()` / `require.resolve()` failed because the\n * module is simply NOT INSTALLED — as opposed to the module being present but\n * throwing while it loads (a real crash). Checking `err.code` FIRST matters:\n * ESM reports a missing package as `err.code === 'ERR_MODULE_NOT_FOUND'` with\n * the human message `Cannot find package '...'`; matching only the older\n * `Cannot find module` string mis-classifies that as a crash (framework#1595).\n *\n * Single shared owner for this classification (framework#3265): the CLI's\n * optional-plugin guards and `requires` capability resolver delegate here, and\n * cloud's `objectos-runtime` capability loader is expected to adopt it at its\n * next framework pin bump — so the parallel loaders cannot drift apart and\n * re-introduce the #1595 false-alarm class.\n */\nexport function isModuleNotFoundError(err: unknown): boolean {\n  const code = (err as { code?: string } | null | undefined)?.code;\n  if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') return true;\n  const msg = err instanceof Error ? err.message : String(err);\n  return msg.includes('Cannot find module') || msg.includes('Cannot find package');\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/degraded-boot.ts","../src/env.ts","../src/error-leak.ts","../src/module-not-found.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Degraded-boot reporting, shared by every subsystem that can be told to boot\n * without a datasource it needs.\n *\n * Two of them exist today and they opt in through the *same* operator flag\n * (`OS_ALLOW_DRIVER_CONNECT_FAILURE`, see {@link resolveAllowDriverConnectFailure}):\n *\n *  - `ObjectQLEngine.init()` — a boot-registered driver whose `connect()`\n *    rejected (framework#3741).\n *  - `DatasourceConnectionService` — a declared datasource that objects bind to\n *    explicitly, or an `external` one with `validation.onMismatch:'fail'`,\n *    that could not be connected (framework#3758).\n *\n * They live in different packages but owe the operator the same thing: the\n * degraded state must be impossible to miss.\n */\n\n/**\n * Emit the degraded-boot banner on a channel the host cannot accidentally\n * silence.\n *\n * `OS_ALLOW_DRIVER_CONNECT_FAILURE` only justifies itself if the state it opts\n * into is impossible to miss — and a logger-only banner is missable: `os serve`\n * swallows ALL of stdout while the kernel boots (its \"boot-quiet\" capture), and\n * `Logger` routes `warn` to stdout, so the one message that matters would be\n * invisible in exactly the situation it exists for. Writing to stderr as well\n * is the same belt-and-braces the kernel already uses for plugin startup\n * failures.\n *\n * Best-effort and never throws: falls back to `console.error`, then to silence\n * on runtimes that have neither (the logger still carries the structured\n * record either way).\n */\nexport function emitDegradedBootBanner(message: string): void {\n  const proc = (globalThis as {\n    process?: { stderr?: { write?: (chunk: string) => unknown } };\n  }).process;\n  try {\n    if (typeof proc?.stderr?.write === 'function') {\n      proc.stderr.write(`${message}\\n`);\n      return;\n    }\n  } catch {\n    /* stderr unavailable / closed — fall through to console */\n  }\n  try {\n    (globalThis as { console?: { error?: (msg: string) => void } }).console?.error?.(message);\n  } catch {\n    /* no output channel at all — the logger record is the remaining trace */\n  }\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Environment-variable helpers shared across `@objectstack/*` packages.\n *\n * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md\n * \"Environment Variables\" section). Some historical names predate this\n * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …\n *\n * To migrate without breaking user `.env` files mid-release, call\n * {@link readEnvWithDeprecation} at every legacy read site:\n *\n *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');\n *\n * If only the legacy name is set, the value is still returned but a\n * one-shot `console.warn` fires (per-process per-variable) telling\n * operators to rename it.\n */\n\nimport {\n  normalizeTenancyPosture,\n  TENANCY_POSTURES,\n  type TenancyPosture,\n} from '@objectstack/spec/security';\n\nconst _warnedKeys = new Set<string>();\n\n/**\n * Read an env var, preferring the canonical `OS_*` name and falling\n * back to one or more legacy aliases.\n *\n * When only a legacy alias is set, emits a one-shot deprecation warning.\n * The warning is process-wide deduplicated: identical (preferred, legacy)\n * pairs will only warn once even if read from multiple call sites.\n *\n * Legacy aliases are checked in order; the first one with a defined\n * value wins (and triggers the warning for that specific alias).\n *\n * Safe to call from environments where `process` is unavailable (returns\n * `undefined`); the warning is suppressed when running outside Node-like\n * runtimes that lack `console.warn`.\n *\n * @param preferred  Canonical OS_*-prefixed env var name.\n * @param legacy     Older name (or array of older names) to fall back on.\n * @param options    Optional behaviour flags. Set `silent: true` for aliases\n *                   that remain accepted conventions rather than true legacy\n *                   names — e.g. `PORT`, which PaaS platforms (Render, Railway,\n *                   Heroku, Fly, …) inject automatically. Warning on those\n *                   would nag operators about env they never set.\n * @returns The resolved value, or `undefined` if neither is set.\n */\nexport function readEnvWithDeprecation(\n  preferred: string,\n  legacy: string | readonly string[],\n  options?: { silent?: boolean },\n): string | undefined {\n  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env;\n  if (!env) return undefined;\n\n  const preferredValue = env[preferred];\n  if (preferredValue !== undefined) return preferredValue;\n\n  const legacyList = typeof legacy === 'string' ? [legacy] : legacy;\n  for (const legacyName of legacyList) {\n    const legacyValue = env[legacyName];\n    if (legacyValue !== undefined) {\n      const dedupeKey = `${preferred}|${legacyName}`;\n      if (!options?.silent && !_warnedKeys.has(dedupeKey)) {\n        _warnedKeys.add(dedupeKey);\n        const consoleRef = (globalThis as { console?: { warn?: (msg: string) => void } }).console;\n        try {\n          consoleRef?.warn?.(\n            `[ObjectStack] Env var \\`${legacyName}\\` is deprecated; rename it to \\`${preferred}\\`. ` +\n            `The legacy name still works for now but will be removed in a future major release.`,\n          );\n        } catch {\n          /* `console.warn` unavailable (exotic runtime) — ignore */\n        }\n      }\n      return legacyValue;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve whether the deployment runs in multi-org (a.k.a. multi-tenant) mode.\n *\n * Single source of truth for the `OS_MULTI_ORG_ENABLED` flag. Resolution: the\n * canonical `OS_MULTI_ORG_ENABLED`; else `false`. Any value other than a\n * case-insensitive `'false'` enables it. (The legacy `OS_MULTI_TENANT` alias was\n * removed in 11.0.)\n *\n * Every site that needs to know \"is this multi-org?\" — the SQL driver's\n * tenant-audit gate, the auth manager's `/auth/config` feature flag and\n * org-create guard, the CLI / dev / runtime org-scoping plugin wiring — MUST\n * call this instead of re-reading the env, so the driver, the security layer,\n * and the UI can never disagree about the mode. Previously each site inlined\n * its own `String(... ?? 'false').toLowerCase() !== 'false'` (and the SQL\n * driver read `process.env` directly, skipping the deprecation warning).\n *\n * Reads `process.env` live on each call; memoise at the call site if the\n * result must be stable for the process lifetime.\n */\nexport function resolveMultiOrgEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MULTI_ORG_ENABLED', []);\n  return String(raw ?? 'false').toLowerCase() !== 'false';\n}\n\n/**\n * [ADR-0105 D1] Resolve the deployment's REQUESTED tenancy posture —\n * `single` | `group` | `isolated`.\n *\n * `OS_TENANCY_POSTURE` is the canonical knob and generalizes the boolean\n * `OS_MULTI_ORG_ENABLED` it supersedes:\n *\n * - set → that posture (the legacy spelling `multi` normalizes to `isolated`)\n * - unset → derived from `OS_MULTI_ORG_ENABLED`: `true` ⇒ `isolated`, else `single`\n *\n * so every existing deployment keeps its current posture with no config change.\n *\n * An unrecognized value THROWS rather than falling back. A typo'd posture that\n * quietly resolved to `single` would silently remove the organization wall —\n * the deployment-layer form of the \"declared but unenforced\" defect ADR-0049\n * forbids, and the same reasoning behind ADR-0093 D5's refusal to boot into\n * undeclared degradation.\n *\n * This resolves what the operator ASKED FOR. Whether the posture is actually\n * enforced is the `tenancy` service's answer (`isolationActive` / `degraded`).\n */\nexport function resolveTenancyPosture(): TenancyPosture {\n  // Read through `globalThis` like `readEnvWithDeprecation` does — this package\n  // targets non-Node runtimes too, where a bare `process` reference throws.\n  const raw = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n    .process?.env?.OS_TENANCY_POSTURE;\n  if (raw != null && String(raw).trim() !== '') {\n    const posture = normalizeTenancyPosture(raw);\n    if (!posture) {\n      throw new Error(\n        `Invalid OS_TENANCY_POSTURE=${JSON.stringify(String(raw))}. ` +\n          `Expected one of: ${TENANCY_POSTURES.join(', ')} (or the legacy alias 'multi' = 'isolated'). ` +\n          'Refusing to boot rather than silently falling back to a posture with no organization wall.',\n      );\n    }\n    return posture;\n  }\n  return resolveMultiOrgEnabled() ? 'isolated' : 'single';\n}\n\n/**\n * Escape hatch for the degraded-tenancy boot guard (ADR-0093 D5).\n *\n * When `OS_MULTI_ORG_ENABLED=true` but the enterprise `@objectstack/organizations`\n * package cannot provide tenant isolation, the platform refuses to boot — a\n * deployment that asked for tenant isolation must not serve traffic pretending\n * to have it (ADR-0049 at the deployment layer). Setting this to a truthy value\n * (`true`/`1`/`on`/`yes`, case-insensitive) boots anyway in an explicitly\n * *degraded* state that is branded everywhere an operator looks. Defaults OFF —\n * an unset flag means \"fail fast\".\n */\nexport function resolveAllowDegradedTenancy(): boolean {\n  const raw = readEnvWithDeprecation('OS_ALLOW_DEGRADED_TENANCY', [], { silent: true });\n  if (raw == null) return false;\n  return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n}\n\n/**\n * Escape hatch for the driver-connect boot guard (framework#3741).\n *\n * `ObjectQLEngine.init()` connects every boot-registered driver and, by\n * default, refuses to boot when any of them fails — a server whose database is\n * unreachable must not report itself started and then 500 every request with an\n * error that reads nothing like \"the database is down\". Failing there is also\n * what gives a driver the ability to REFUSE STARTUP at all: any fatal startup\n * check a driver wants to run (licence, server version, incompatible\n * configuration, missing capability) can simply throw from `connect()`.\n *\n * Setting this to a truthy value (`true`/`1`/`on`/`yes`, case-insensitive)\n * boots anyway, in an explicitly degraded state that is logged loudly at\n * startup. Every query routed to a failed driver fails until the datasource\n * becomes reachable — the underlying clients do re-establish connections on\n * their own (framework#3759) — but the boot-time schema sync those drivers\n * missed is never re-run, so their tables may simply not exist afterwards.\n * Defaults OFF — an unset flag means \"fail fast\".\n */\nexport function resolveAllowDriverConnectFailure(): boolean {\n  const raw = readEnvWithDeprecation('OS_ALLOW_DRIVER_CONNECT_FAILURE', [], { silent: true });\n  if (raw == null) return false;\n  return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n}\n\n/**\n * SINGLE decision point for \"is the MCP HTTP surface (`/api/v1/mcp`) on?\".\n *\n * MCP is a core platform capability and defaults ON: an unset\n * `OS_MCP_SERVER_ENABLED` means the surface is served. Operators opt OUT with\n * an explicit falsy value (`false`/`0`/`off`/`no`, case-insensitive); any\n * other value — including the historical `true` — keeps it on.\n *\n * Every consumer of the flag — the runtime dispatcher's `/mcp` route gate,\n * the CLI's MCP plugin auto-load, the REST `/discovery` advertisement, and\n * the auth service's OAuth/DCR follow-defaults — MUST call this instead of\n * re-reading the env, so the served route, the advertised route, and the\n * authorization track can never disagree.\n *\n * Note the asymmetry with the MCP plugin's *stdio* auto-start\n * ({@link resolveMcpStdioAutoStart}), which stays opt-in and is gated by a\n * SEPARATE switch: attaching a long-lived stdio transport to every process is\n * a side effect no default should impose, while the HTTP surface is served\n * statelessly per-request.\n */\nexport function isMcpServerEnabled(): boolean {\n  const raw = readEnvWithDeprecation('OS_MCP_SERVER_ENABLED', 'MCP_SERVER_ENABLED', {\n    silent: true,\n  });\n  if (raw == null) return true;\n  return !['0', 'false', 'off', 'no'].includes(raw.trim().toLowerCase());\n}\n\n/**\n * SINGLE decision point for \"should the MCP plugin auto-start a long-lived\n * (stdio) transport?\" — distinct from {@link isMcpServerEnabled}, which governs\n * the stateless HTTP surface.\n *\n * The stdio transport is a different, stricter posture: the plugin bridges the\n * RAW metadata service + data engine onto the long-lived server with NO\n * per-request principal (unscoped — see the `mcp-stdio-authority` conformance\n * row), so it is safe only as a single-operator LOCAL tool and MUST stay\n * opt-in. It defaults OFF.\n *\n * Canonical switch: `OS_MCP_STDIO_ENABLED` (truthy). The plugin also starts it\n * when constructed with `{ autoStart: true }` (that path is checked by the\n * caller, not here).\n *\n * DEPRECATED alias: `OS_MCP_SERVER_ENABLED=true` historically ALSO started\n * stdio — overloading the very var that gates the HTTP surface, so an operator\n * setting it to \"make sure MCP is on\" silently attached an unscoped transport.\n * That trigger still works (with a one-time warning from the caller) for one\n * release; prefer the dedicated var. Note `OS_MCP_SERVER_ENABLED=false` only\n * ever gated the HTTP surface and never started stdio, so it is unaffected.\n *\n * @returns `enabled` — whether stdio auto-start is requested by the env; and\n *   `viaDeprecatedAlias` — whether it came through the legacy\n *   `OS_MCP_SERVER_ENABLED=true` trigger (so the caller can warn once).\n */\nexport function resolveMcpStdioAutoStart(): { enabled: boolean; viaDeprecatedAlias: boolean } {\n  const stdio = readEnvWithDeprecation('OS_MCP_STDIO_ENABLED', [], { silent: true });\n  if (stdio != null && ['1', 'true', 'on', 'yes'].includes(stdio.trim().toLowerCase())) {\n    return { enabled: true, viaDeprecatedAlias: false };\n  }\n  // Legacy trigger: only the literal `true` ever started stdio (preserved\n  // exactly). `OS_MCP_SERVER_ENABLED=false`/other values never did.\n  const legacy = readEnvWithDeprecation('OS_MCP_SERVER_ENABLED', 'MCP_SERVER_ENABLED', { silent: true });\n  if (legacy != null && legacy.trim().toLowerCase() === 'true') {\n    return { enabled: true, viaDeprecatedAlias: true };\n  }\n  return { enabled: false, viaDeprecatedAlias: false };\n}\n\n/**\n * Maximum number of organizations a single user may CREATE, from `OS_ORG_LIMIT`.\n * The auth plugin forwards this as better-auth's `organizationLimit` in function\n * form, counting only the caller's `role=owner` memberships — so it caps\n * self-created orgs (each of which can auto-provision a free environment on the\n * cloud control plane) without penalising a user invited into many orgs.\n *\n * Only meaningful when multi-org is enabled ({@link resolveMultiOrgEnabled}).\n * Returns `undefined` when unset or non-positive → no limit (better-auth treats\n * an absent `organizationLimit` as unlimited), preserving self-host behaviour.\n * Deployments that let users self-create orgs SHOULD set a generous cap.\n */\nexport function resolveOrgLimit(): number | undefined {\n  const raw = readEnvWithDeprecation('OS_ORG_LIMIT', [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return undefined;\n  const n = Number.parseInt(String(raw), 10);\n  return Number.isFinite(n) && n > 0 ? n : undefined;\n}\n\n/**\n * SINGLE decision point for \"is pinyin search recall on?\" (#2486).\n *\n * Pinyin search is a deployment/locale-level capability, not field metadata:\n * Chinese deployments want it, pure-Japanese/English deployments don't. The\n * flag gates the whole feature end-to-end — the SchemaRegistry's compile-time\n * `__search` companion-column seam AND the `plugin-pinyin-search` populate\n * hooks — so there is no half-state where a column exists but nobody fills it\n * (ADR-0049: no declared-but-unenforced capability).\n *\n * Resolution:\n *   1. An explicit `OS_SEARCH_PINYIN_ENABLED` always wins — truthy\n *      (`1`/`true`/`on`/`yes`) enables, anything else disables.\n *   2. When unset, the default derives from the deployment's configured\n *      locales (`opts.locales`, e.g. the stack's `i18n.defaultLocale` +\n *      `supportedLocales`): any `zh-*` locale turns it on.\n *   3. No env var and no `zh-*` locale → off. OSS / non-Chinese deployments\n *      never load `pinyin-pro` and pay zero compute cost.\n *\n * Hosts that know the stack's i18n config (the CLI `serve` boot path) resolve\n * once with locales and stamp the decision back into the env, so downstream\n * consumers constructed without config access (per-engine SchemaRegistry)\n * read the same answer via the no-arg form.\n */\nexport function resolveSearchPinyinEnabled(opts?: { locales?: readonly string[] }): boolean {\n  const raw = readEnvWithDeprecation('OS_SEARCH_PINYIN_ENABLED', [], { silent: true });\n  if (raw != null && String(raw).trim() !== '') {\n    return ['1', 'true', 'on', 'yes'].includes(String(raw).trim().toLowerCase());\n  }\n  return (opts?.locales ?? []).some((l) => /^zh([-_]|$)/i.test(String(l ?? '').trim()));\n}\n\n/**\n * SINGLE decision point for a sandbox script-runner DEFAULT (ms), resolved from\n * the environment (framework#3259 / ADR-0102).\n *\n * The QuickJS sandbox meters each hook/action invocation against a per-invocation\n * budget. Two dimensions are env-tunable:\n *   - the **CPU-time budget** for hooks / actions — how much *VM-active* time a\n *     body may burn (built-in 250ms hooks / 5000ms actions); and\n *   - the **wall-clock ceiling** — the backstop bounding a body parked forever on\n *     a host call that never settles (built-in 30_000ms).\n *\n * The built-in defaults suit a warm, idle host; a heavily loaded or slow host\n * (an oversubscribed CI runner, constrained production hardware) may need a\n * higher floor. This lets an operator raise it once, deployment-wide, instead of\n * re-tuning every call site.\n *\n * Canonical vars (OS_{DOMAIN}_{NAME}, DOMAIN=SANDBOX):\n *   - hook        → `OS_SANDBOX_HOOK_TIMEOUT_MS`\n *   - action      → `OS_SANDBOX_ACTION_TIMEOUT_MS`\n *   - wallCeiling → `OS_SANDBOX_WALL_CEILING_MS`\n *\n * Only a positive integer is honored; unset / empty / non-numeric / non-positive\n * falls back to `fallback`, so behaviour is byte-for-byte unchanged when the var\n * is absent. This is a FALLBACK default ONLY: an explicit constructor option\n * still wins over it, and (for the CPU budget) a body's own declared `timeoutMs`\n * still wins over the resolved default per the runner's resolution rule.\n */\nexport function resolveSandboxTimeoutMs(\n  kind: 'hook' | 'action' | 'wallCeiling',\n  fallback: number,\n): number {\n  const name =\n    kind === 'hook'\n      ? 'OS_SANDBOX_HOOK_TIMEOUT_MS'\n      : kind === 'action'\n        ? 'OS_SANDBOX_ACTION_TIMEOUT_MS'\n        : 'OS_SANDBOX_WALL_CEILING_MS';\n  const raw = readEnvWithDeprecation(name, [], { silent: true });\n  if (raw == null || String(raw).trim() === '') return fallback;\n  const n = Number.parseInt(String(raw).trim(), 10);\n  return Number.isFinite(n) && n > 0 ? n : fallback;\n}\n\n/**\n * Internal: clear the dedupe set. Test-only; exposed so suite-wide\n * deprecation warnings don't bleed between tests.\n *\n * @internal\n */\nexport function _resetEnvDeprecationWarnings(): void {\n  _warnedKeys.clear();\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Shared \"does this error message leak server internals?\" heuristic (#3867).\n *\n * ObjectStack has more than one HTTP boundary. `@objectstack/rest` guards the\n * REST data routes inside `mapDataError`; the dispatcher-plugin routes\n * (`/analytics`, `/packages`, `/i18n`, `/storage`, `/automation`, …) exit\n * through `errorResponseBase`. Before #3867 only the first of those sanitised\n * anything, so a driver error raised under `/analytics/query` reached the\n * client verbatim — a real SQL statement in the response body:\n *\n * ```\n * {\"success\":false,\"error\":{\"message\":\"SELECT  FROM \\\"sqlite_sequence\\\" - near \\\"FROM\\\": syntax error\",\"code\":500}}\n * ```\n *\n * \"Do not ship driver internals to clients\" is a property of the HTTP\n * boundary, not of one router, so the predicate lives here — the package both\n * `@objectstack/rest` and `@objectstack/runtime` already depend on — and each\n * boundary applies it in its own envelope. One heuristic, one place to widen\n * when a new dialect's phrasing shows up.\n *\n * Deliberately a *heuristic over the message*, not a driver taxonomy: these\n * errors arrive as plain `Error`s from a half-dozen dialects with no shared\n * shape. It is applied only where the outcome is already a 5xx, so a false\n * positive costs a caller nothing but detail on a response that was a server\n * fault anyway — while the full text still reaches server logs and the\n * error reporter.\n */\n\n/** Generic replacement text for a message that trips {@link looksLikeInternalErrorLeak}. */\nexport const INTERNAL_ERROR_MESSAGE = 'Internal server error';\n\n/**\n * Whether `message` looks like a raw SQL statement or driver/engine dump that\n * must not be returned to an API client.\n *\n * Matches: dialect error codes (`SQLSTATE`, `sqlite_*`), bare statements\n * (a message that *starts* as `SELECT`/`INSERT INTO`/`UPDATE`/`DELETE FROM` —\n * drivers prefix the offending SQL to their message), and constraint-violation\n * dumps, which name physical tables and columns.\n *\n * Does NOT match ordinary business or validation messages, which is why the\n * statement forms are anchored with `startsWith`: a legitimate message may\n * *mention* \"update\" without being one.\n */\nexport function looksLikeInternalErrorLeak(message: string | undefined | null): boolean {\n  if (!message) return false;\n  const lower = String(message).toLowerCase();\n  return (\n    lower.includes('sqlite_') ||\n    lower.includes('sqlstate') ||\n    lower.startsWith('insert into ') ||\n    lower.startsWith('update ') ||\n    lower.startsWith('select ') ||\n    lower.startsWith('delete from ') ||\n    lower.includes('constraint failed') ||\n    lower.includes('unique constraint') ||\n    lower.includes('foreign key')\n  );\n}\n","// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * True when a dynamic `import()` / `require.resolve()` failed because the\n * module is simply NOT INSTALLED — as opposed to the module being present but\n * throwing while it loads (a real crash). Checking `err.code` FIRST matters:\n * ESM reports a missing package as `err.code === 'ERR_MODULE_NOT_FOUND'` with\n * the human message `Cannot find package '...'`; matching only the older\n * `Cannot find module` string mis-classifies that as a crash (framework#1595).\n *\n * Single shared owner for this classification (framework#3265): the CLI's\n * optional-plugin guards and `requires` capability resolver delegate here, and\n * cloud's `objectos-runtime` capability loader is expected to adopt it at its\n * next framework pin bump — so the parallel loaders cannot drift apart and\n * re-introduce the #1595 false-alarm class.\n */\nexport function isModuleNotFoundError(err: unknown): boolean {\n  const code = (err as { code?: string } | null | undefined)?.code;\n  if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') return true;\n  const msg = err instanceof Error ? err.message : String(err);\n  return msg.includes('Cannot find module') || msg.includes('Cannot find package');\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/types",
-  "version": "16.0.0",
+  "version": "17.0.0-rc.0",
   "license": "Apache-2.0",
   "description": "Shared interfaces describing the ObjectStack Runtime environment",
   "main": "dist/index.js",
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "16.0.0"
+    "@objectstack/spec": "17.0.0-rc.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
@@ -28,11 +28,11 @@
   "author": "ObjectStack",
   "repository": {
     "type": "git",
-    "url": "https://github.com/objectstack-ai/framework.git",
+    "url": "https://github.com/objectstack-ai/objectstack.git",
     "directory": "packages/types"
   },
   "homepage": "https://objectstack.ai/docs",
-  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "bugs": "https://github.com/objectstack-ai/objectstack/issues",
   "publishConfig": {
     "access": "public"
   },
@@ -41,7 +41,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",