@objectstack/types 15.0.0 → 15.1.1

package/dist/index.d.mts

@@ -90,6 +90,33 @@ declare function isMcpServerEnabled(): boolean;
  * Deployments that let users self-create orgs SHOULD set a generous cap.
  */
 declare function resolveOrgLimit(): number | undefined;
+/**
+ * SINGLE decision point for "is pinyin search recall on?" (#2486).
+ *
+ * Pinyin search is a deployment/locale-level capability, not field metadata:
+ * Chinese deployments want it, pure-Japanese/English deployments don't. The
+ * flag gates the whole feature end-to-end — the SchemaRegistry's compile-time
+ * `__search` companion-column seam AND the `plugin-pinyin-search` populate
+ * hooks — so there is no half-state where a column exists but nobody fills it
+ * (ADR-0049: no declared-but-unenforced capability).
+ *
+ * Resolution:
+ *   1. An explicit `OS_SEARCH_PINYIN_ENABLED` always wins — truthy
+ *      (`1`/`true`/`on`/`yes`) enables, anything else disables.
+ *   2. When unset, the default derives from the deployment's configured
+ *      locales (`opts.locales`, e.g. the stack's `i18n.defaultLocale` +
+ *      `supportedLocales`): any `zh-*` locale turns it on.
+ *   3. No env var and no `zh-*` locale → off. OSS / non-Chinese deployments
+ *      never load `pinyin-pro` and pay zero compute cost.
+ *
+ * Hosts that know the stack's i18n config (the CLI `serve` boot path) resolve
+ * once with locales and stamp the decision back into the env, so downstream
+ * consumers constructed without config access (per-engine SchemaRegistry)
+ * read the same answer via the no-arg form.
+ */
+declare function resolveSearchPinyinEnabled(opts?: {
+    locales?: readonly string[];
+}): boolean;
 /**
  * Internal: clear the dedupe set. Test-only; exposed so suite-wide
  * deprecation warnings don't bleed between tests.
@@ -112,4 +139,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, isMcpServerEnabled, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveMultiOrgEnabled, resolveOrgLimit };
+export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, isMcpServerEnabled, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveMultiOrgEnabled, resolveOrgLimit, resolveSearchPinyinEnabled };

package/dist/index.d.ts

@@ -90,6 +90,33 @@ declare function isMcpServerEnabled(): boolean;
  * Deployments that let users self-create orgs SHOULD set a generous cap.
  */
 declare function resolveOrgLimit(): number | undefined;
+/**
+ * SINGLE decision point for "is pinyin search recall on?" (#2486).
+ *
+ * Pinyin search is a deployment/locale-level capability, not field metadata:
+ * Chinese deployments want it, pure-Japanese/English deployments don't. The
+ * flag gates the whole feature end-to-end — the SchemaRegistry's compile-time
+ * `__search` companion-column seam AND the `plugin-pinyin-search` populate
+ * hooks — so there is no half-state where a column exists but nobody fills it
+ * (ADR-0049: no declared-but-unenforced capability).
+ *
+ * Resolution:
+ *   1. An explicit `OS_SEARCH_PINYIN_ENABLED` always wins — truthy
+ *      (`1`/`true`/`on`/`yes`) enables, anything else disables.
+ *   2. When unset, the default derives from the deployment's configured
+ *      locales (`opts.locales`, e.g. the stack's `i18n.defaultLocale` +
+ *      `supportedLocales`): any `zh-*` locale turns it on.
+ *   3. No env var and no `zh-*` locale → off. OSS / non-Chinese deployments
+ *      never load `pinyin-pro` and pay zero compute cost.
+ *
+ * Hosts that know the stack's i18n config (the CLI `serve` boot path) resolve
+ * once with locales and stamp the decision back into the env, so downstream
+ * consumers constructed without config access (per-engine SchemaRegistry)
+ * read the same answer via the no-arg form.
+ */
+declare function resolveSearchPinyinEnabled(opts?: {
+    locales?: readonly string[];
+}): boolean;
 /**
  * Internal: clear the dedupe set. Test-only; exposed so suite-wide
  * deprecation warnings don't bleed between tests.
@@ -112,4 +139,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, isMcpServerEnabled, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveMultiOrgEnabled, resolveOrgLimit };
+export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, isMcpServerEnabled, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveMultiOrgEnabled, resolveOrgLimit, resolveSearchPinyinEnabled };

package/dist/index.js

@@ -25,7 +25,8 @@ __export(index_exports, {
   readEnvWithDeprecation: () => readEnvWithDeprecation,
   resolveAllowDegradedTenancy: () => resolveAllowDegradedTenancy,
   resolveMultiOrgEnabled: () => resolveMultiOrgEnabled,
-  resolveOrgLimit: () => resolveOrgLimit
+  resolveOrgLimit: () => resolveOrgLimit,
+  resolveSearchPinyinEnabled: () => resolveSearchPinyinEnabled
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -78,6 +79,13 @@ function resolveOrgLimit() {
   const n = Number.parseInt(String(raw), 10);
   return Number.isFinite(n) && n > 0 ? n : void 0;
 }
+function resolveSearchPinyinEnabled(opts) {
+  const raw = readEnvWithDeprecation("OS_SEARCH_PINYIN_ENABLED", [], { silent: true });
+  if (raw != null && String(raw).trim() !== "") {
+    return ["1", "true", "on", "yes"].includes(String(raw).trim().toLowerCase());
+  }
+  return (opts?.locales ?? []).some((l) => /^zh([-_]|$)/i.test(String(l ?? "").trim()));
+}
 function _resetEnvDeprecationWarnings() {
   _warnedKeys.clear();
 }
@@ -88,6 +96,7 @@ function _resetEnvDeprecationWarnings() {
   readEnvWithDeprecation,
   resolveAllowDegradedTenancy,
   resolveMultiOrgEnabled,
-  resolveOrgLimit
+  resolveOrgLimit,
+  resolveSearchPinyinEnabled
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/env.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport * from './env.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, which stays\n * opt-in (explicit `true` / `autoStart`): attaching a long-lived stdio\n * transport to every process is a side effect no default should impose,\n * while the HTTP surface is served 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 * 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 * 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"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBA,IAAM,cAAc,oBAAI,IAAY;AA0B7B,SAAS,uBACd,WACA,QACA,SACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,SAAS,UAAU,CAAC,YAAY,IAAI,SAAS,GAAG;AACnD,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAqBO,SAAS,yBAAkC;AAChD,QAAM,MAAM,uBAAuB,wBAAwB,CAAC,CAAC;AAC7D,SAAO,OAAO,OAAO,OAAO,EAAE,YAAY,MAAM;AAClD;AAaO,SAAS,8BAAuC;AACrD,QAAM,MAAM,uBAAuB,6BAA6B,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACpF,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,CAAC,KAAK,QAAQ,MAAM,KAAK,EAAE,SAAS,OAAO,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC;AAC7E;AAqBO,SAAS,qBAA8B;AAC5C,QAAM,MAAM,uBAAuB,yBAAyB,sBAAsB;AAAA,IAChF,QAAQ;AAAA,EACV,CAAC;AACD,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,CAAC,CAAC,KAAK,SAAS,OAAO,IAAI,EAAE,SAAS,IAAI,KAAK,EAAE,YAAY,CAAC;AACvE;AAcO,SAAS,kBAAsC;AACpD,QAAM,MAAM,uBAAuB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACvE,MAAI,OAAO,QAAQ,OAAO,GAAG,EAAE,KAAK,MAAM,GAAI,QAAO;AACrD,QAAM,IAAI,OAAO,SAAS,OAAO,GAAG,GAAG,EAAE;AACzC,SAAO,OAAO,SAAS,CAAC,KAAK,IAAI,IAAI,IAAI;AAC3C;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/env.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\nexport * from './env.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, which stays\n * opt-in (explicit `true` / `autoStart`): attaching a long-lived stdio\n * transport to every process is a side effect no default should impose,\n * while the HTTP surface is served 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 * 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 * 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"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmBA,IAAM,cAAc,oBAAI,IAAY;AA0B7B,SAAS,uBACd,WACA,QACA,SACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,SAAS,UAAU,CAAC,YAAY,IAAI,SAAS,GAAG;AACnD,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAqBO,SAAS,yBAAkC;AAChD,QAAM,MAAM,uBAAuB,wBAAwB,CAAC,CAAC;AAC7D,SAAO,OAAO,OAAO,OAAO,EAAE,YAAY,MAAM;AAClD;AAaO,SAAS,8BAAuC;AACrD,QAAM,MAAM,uBAAuB,6BAA6B,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACpF,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,CAAC,KAAK,QAAQ,MAAM,KAAK,EAAE,SAAS,OAAO,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC;AAC7E;AAqBO,SAAS,qBAA8B;AAC5C,QAAM,MAAM,uBAAuB,yBAAyB,sBAAsB;AAAA,IAChF,QAAQ;AAAA,EACV,CAAC;AACD,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,CAAC,CAAC,KAAK,SAAS,OAAO,IAAI,EAAE,SAAS,IAAI,KAAK,EAAE,YAAY,CAAC;AACvE;AAcO,SAAS,kBAAsC;AACpD,QAAM,MAAM,uBAAuB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACvE,MAAI,OAAO,QAAQ,OAAO,GAAG,EAAE,KAAK,MAAM,GAAI,QAAO;AACrD,QAAM,IAAI,OAAO,SAAS,OAAO,GAAG,GAAG,EAAE;AACzC,SAAO,OAAO,SAAS,CAAC,KAAK,IAAI,IAAI,IAAI;AAC3C;AA0BO,SAAS,2BAA2B,MAAiD;AAC1F,QAAM,MAAM,uBAAuB,4BAA4B,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACnF,MAAI,OAAO,QAAQ,OAAO,GAAG,EAAE,KAAK,MAAM,IAAI;AAC5C,WAAO,CAAC,KAAK,QAAQ,MAAM,KAAK,EAAE,SAAS,OAAO,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC;AAAA,EAC7E;AACA,UAAQ,MAAM,WAAW,CAAC,GAAG,KAAK,CAAC,MAAM,eAAe,KAAK,OAAO,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;AACtF;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}

package/dist/index.mjs

@@ -47,6 +47,13 @@ function resolveOrgLimit() {
   const n = Number.parseInt(String(raw), 10);
   return Number.isFinite(n) && n > 0 ? n : void 0;
 }
+function resolveSearchPinyinEnabled(opts) {
+  const raw = readEnvWithDeprecation("OS_SEARCH_PINYIN_ENABLED", [], { silent: true });
+  if (raw != null && String(raw).trim() !== "") {
+    return ["1", "true", "on", "yes"].includes(String(raw).trim().toLowerCase());
+  }
+  return (opts?.locales ?? []).some((l) => /^zh([-_]|$)/i.test(String(l ?? "").trim()));
+}
 function _resetEnvDeprecationWarnings() {
   _warnedKeys.clear();
 }
@@ -56,6 +63,7 @@ export {
   readEnvWithDeprecation,
   resolveAllowDegradedTenancy,
   resolveMultiOrgEnabled,
-  resolveOrgLimit
+  resolveOrgLimit,
+  resolveSearchPinyinEnabled
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/env.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, which stays\n * opt-in (explicit `true` / `autoStart`): attaching a long-lived stdio\n * transport to every process is a side effect no default should impose,\n * while the HTTP surface is served 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 * 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 * 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"],"mappings":";AAmBA,IAAM,cAAc,oBAAI,IAAY;AA0B7B,SAAS,uBACd,WACA,QACA,SACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,SAAS,UAAU,CAAC,YAAY,IAAI,SAAS,GAAG;AACnD,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAqBO,SAAS,yBAAkC;AAChD,QAAM,MAAM,uBAAuB,wBAAwB,CAAC,CAAC;AAC7D,SAAO,OAAO,OAAO,OAAO,EAAE,YAAY,MAAM;AAClD;AAaO,SAAS,8BAAuC;AACrD,QAAM,MAAM,uBAAuB,6BAA6B,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACpF,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,CAAC,KAAK,QAAQ,MAAM,KAAK,EAAE,SAAS,OAAO,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC;AAC7E;AAqBO,SAAS,qBAA8B;AAC5C,QAAM,MAAM,uBAAuB,yBAAyB,sBAAsB;AAAA,IAChF,QAAQ;AAAA,EACV,CAAC;AACD,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,CAAC,CAAC,KAAK,SAAS,OAAO,IAAI,EAAE,SAAS,IAAI,KAAK,EAAE,YAAY,CAAC;AACvE;AAcO,SAAS,kBAAsC;AACpD,QAAM,MAAM,uBAAuB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACvE,MAAI,OAAO,QAAQ,OAAO,GAAG,EAAE,KAAK,MAAM,GAAI,QAAO;AACrD,QAAM,IAAI,OAAO,SAAS,OAAO,GAAG,GAAG,EAAE;AACzC,SAAO,OAAO,SAAS,CAAC,KAAK,IAAI,IAAI,IAAI;AAC3C;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}
+{"version":3,"sources":["../src/env.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, which stays\n * opt-in (explicit `true` / `autoStart`): attaching a long-lived stdio\n * transport to every process is a side effect no default should impose,\n * while the HTTP surface is served 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 * 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 * 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"],"mappings":";AAmBA,IAAM,cAAc,oBAAI,IAAY;AA0B7B,SAAS,uBACd,WACA,QACA,SACoB;AACpB,QAAM,MAAO,WACV,SAAS;AACZ,MAAI,CAAC,IAAK,QAAO;AAEjB,QAAM,iBAAiB,IAAI,SAAS;AACpC,MAAI,mBAAmB,OAAW,QAAO;AAEzC,QAAM,aAAa,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;AAC3D,aAAW,cAAc,YAAY;AACnC,UAAM,cAAc,IAAI,UAAU;AAClC,QAAI,gBAAgB,QAAW;AAC7B,YAAM,YAAY,GAAG,SAAS,IAAI,UAAU;AAC5C,UAAI,CAAC,SAAS,UAAU,CAAC,YAAY,IAAI,SAAS,GAAG;AACnD,oBAAY,IAAI,SAAS;AACzB,cAAM,aAAc,WAA8D;AAClF,YAAI;AACF,sBAAY;AAAA,YACV,2BAA2B,UAAU,oCAAoC,SAAS;AAAA,UAEpF;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;AAqBO,SAAS,yBAAkC;AAChD,QAAM,MAAM,uBAAuB,wBAAwB,CAAC,CAAC;AAC7D,SAAO,OAAO,OAAO,OAAO,EAAE,YAAY,MAAM;AAClD;AAaO,SAAS,8BAAuC;AACrD,QAAM,MAAM,uBAAuB,6BAA6B,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACpF,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,CAAC,KAAK,QAAQ,MAAM,KAAK,EAAE,SAAS,OAAO,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC;AAC7E;AAqBO,SAAS,qBAA8B;AAC5C,QAAM,MAAM,uBAAuB,yBAAyB,sBAAsB;AAAA,IAChF,QAAQ;AAAA,EACV,CAAC;AACD,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,CAAC,CAAC,KAAK,SAAS,OAAO,IAAI,EAAE,SAAS,IAAI,KAAK,EAAE,YAAY,CAAC;AACvE;AAcO,SAAS,kBAAsC;AACpD,QAAM,MAAM,uBAAuB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACvE,MAAI,OAAO,QAAQ,OAAO,GAAG,EAAE,KAAK,MAAM,GAAI,QAAO;AACrD,QAAM,IAAI,OAAO,SAAS,OAAO,GAAG,GAAG,EAAE;AACzC,SAAO,OAAO,SAAS,CAAC,KAAK,IAAI,IAAI,IAAI;AAC3C;AA0BO,SAAS,2BAA2B,MAAiD;AAC1F,QAAM,MAAM,uBAAuB,4BAA4B,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;AACnF,MAAI,OAAO,QAAQ,OAAO,GAAG,EAAE,KAAK,MAAM,IAAI;AAC5C,WAAO,CAAC,KAAK,QAAQ,MAAM,KAAK,EAAE,SAAS,OAAO,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC;AAAA,EAC7E;AACA,UAAQ,MAAM,WAAW,CAAC,GAAG,KAAK,CAAC,MAAM,eAAe,KAAK,OAAO,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;AACtF;AAQO,SAAS,+BAAqC;AACnD,cAAY,MAAM;AACpB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/types",
-  "version": "15.0.0",
+  "version": "15.1.1",
   "license": "Apache-2.0",
   "description": "Shared interfaces describing the ObjectStack Runtime environment",
   "main": "dist/index.js",
@@ -13,7 +13,7 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "15.0.0"
+    "@objectstack/spec": "15.1.1"
   },
   "devDependencies": {
     "typescript": "^6.0.3",