okengine 0.10.3 → 0.11.0

package/src/full.ts

@@ -0,0 +1,248 @@
+/**
+ * `okengine/full` — deprecated mega-barrel (pre-thin-root surface).
+ *
+ * Prefer `okengine` (thin) or `okengine/http` for new apps. This entry keeps
+ * the historical re-export graph for one minor line.
+ *
+ * @module
+ */
+
+export {
+  oke,
+  on,
+  flow,
+  http,
+  every,
+  internal,
+  table,
+  fail,
+  createFx,
+  isFlow,
+  isFlowFailure,
+  plugin,
+  isPlugin,
+  bootApplication,
+  mintCapabilities,
+  gateDenialFailure,
+  journey,
+  unit,
+  rateLimit,
+  Redacted,
+  isRedacted,
+  maskRedactedDeep,
+  REDACTED_PLACEHOLDER,
+  PluginNeedsError,
+  assertPluginNeeds,
+  freezePrincipal,
+  installGracefulShutdown,
+  releaseInstanceLeases,
+  type OkeApp,
+  type OkeOptions,
+  type ReadyState,
+  type FlowDef,
+  type FlowFailure,
+  type FlowErrorValue,
+  type Fx,
+  type FxPrincipal,
+  type Binding,
+  type PluginDef,
+  type PluginCapabilities,
+  type BootOptions,
+  type BootResult,
+  type ElementRuntimes,
+  type JourneyDecl,
+  type UnitBag,
+} from "./kernel/index.ts";
+
+export {
+  store,
+  classify,
+  id,
+  now,
+  defineTable,
+  field,
+  defineSeed,
+  normalizeSeedFns,
+  resolveSeedCategory,
+  createStoreRuntime,
+  type StoreDecl,
+  type StoreRuntime,
+  type SqlStoreHandle,
+  type TableHandle,
+  type SchemaTableDecl,
+  type SchemaColumnDecl,
+  type SeedDef,
+  type SeedFn,
+  type SeedFns,
+  type SeedCategory,
+  type UpsertResult,
+  type UpsertStatus,
+} from "./elements/store.ts";
+
+export {
+  signal,
+  createSignalRuntime,
+  type SignalDecl,
+  type SignalOptions,
+  type SignalRuntime,
+} from "./elements/signal.ts";
+
+export {
+  clock,
+  createClockRuntime,
+  createTestClockRuntime,
+  createTimeTravel,
+  runDurable,
+  reconcileClocks,
+  detectDstAmbiguity,
+  type ClockDecl,
+  type ClockRuntime,
+  type TimeTravel,
+  type DurableResult,
+} from "./elements/clock.ts";
+
+export {
+  gate,
+  GATE_PUBLIC_NAME,
+  GateBootError,
+  assertHttpGatePosture,
+  createGateRuntime,
+  resolveGateConfig,
+  takeRate,
+  deriveModuleActions,
+  ALL_RATE_STRATEGIES,
+  type GateDecl,
+  type GateOptions,
+  type GatePostureGap,
+  type GateRuntime,
+  type RateOptions,
+  type ResolvedGateConfig,
+} from "./elements/gate.ts";
+
+export {
+  vault,
+  fromDocker,
+  FROM_DOCKER_PREFIX,
+  createVaultRuntime,
+  VaultBootError,
+  SECRET_MASK,
+  type VaultSecretDecl,
+  type VaultRuntime,
+} from "./elements/vault.ts";
+
+export {
+  channel,
+  createChannelRuntime,
+  createConsentStore,
+  createSuppressionStore,
+  createReceiptLedger,
+  type ChannelTemplateDecl,
+  type ChannelRuntime,
+} from "./elements/channel.ts";
+
+export {
+  ai,
+  createAiRuntime,
+  assertAllowPiiForAsk,
+  AiPiiBuildError,
+  AiSchemaValidationError,
+  runPromptEvals,
+  parseEvalJsonl,
+  type AiModelDecl,
+  type AiPromptDecl,
+  type AiAgentDecl,
+  type AiRuntime,
+} from "./elements/ai.ts";
+
+export {
+  createJournal,
+  createMemoryJournalStore,
+  createFileJournalStore,
+  hasJournalLease,
+  isJournalLeaseBusy,
+  JournalLeaseBusy,
+  JOURNAL_DEFAULT_LEASE_MS,
+  type Journal,
+  type JournalLeaseOptions,
+  type JournalLeaseStore,
+  type JournalStore,
+  type JournalRun,
+} from "./kernel/journal.ts";
+
+export {
+  validate,
+  isStandardSchema,
+  fromTypeBox,
+  VALIDATION_ERROR_CODE,
+  type StandardSchemaV1,
+  type SchemaInput,
+  type ValidationErrorData,
+} from "./validation/index.ts";
+
+export {
+  compileAot,
+  compileDynamic,
+  compileRoute,
+  sucrose,
+  type CompiledRoute,
+  type ContextInference,
+} from "./compiler/index.ts";
+
+export {
+  defineLocale,
+  defineMessages,
+  flattenMessages,
+  formatMessage,
+  getMessageCatalogs,
+  interpolateMessage,
+  isRtlLocale,
+  matchConfiguredLocale,
+  parseAcceptLanguage,
+  resolveFailureMessage,
+  resolveLocale,
+  runWithLocale,
+  translate,
+  type AppMessageKey,
+  type FlattenKeys,
+  type LocaleContext,
+  type MessageCatalog,
+  type MessageCatalogs,
+  type MessageTree,
+  type MessageValue,
+  type MessageValues,
+  type MessagesFor,
+  type Register,
+} from "./i18n/index.ts";
+
+export {
+  createBunRuntime,
+  createWebStandardRuntime,
+  APP_PORT,
+  CONSOLE_PORT,
+  MCP_PORT,
+  type Runtime,
+  type ServeOptions,
+} from "./runtime/index.ts";
+export {
+  createRunsRuntime,
+  collectWideEvent,
+  createRunTelemetry,
+  explainOutliers,
+  seedOutlierDataset,
+  privacyErase,
+  createMemorySubjectKeys,
+  subjectKeysFromVault,
+  archiveFields,
+  revealArchived,
+  eraseSubject,
+  SHREDDED,
+  filesRunsDriver,
+  memoryRunsDriver,
+  postgresRunsDriver,
+  clickhouseRunsDriver,
+  type RunsRuntime,
+  type WideEvent,
+  type CreateRunsRuntimeOptions,
+  type OutlierFinding,
+  type SubjectKeyVault,
+} from "./runs/index.ts";

package/src/http.ts

@@ -0,0 +1,41 @@
+/**
+ * `okengine/http` — slim HTTP app surface.
+ *
+ * Prefer this entry for HTTP-only apps so cold graphs stay on the edge
+ * router and avoid the mega-barrel (`okengine/full`).
+ *
+ * @example
+ * ```ts
+ * import { on, flow, http, gate, oke, createBunRuntime } from "okengine/http";
+ *
+ * on(http.get("/").gate(gate.public), flow("ping", { do: () => "Hi" }));
+ * const app = oke({ name: "ping" });
+ * createBunRuntime().serve(app);
+ * ```
+ *
+ * @module
+ */
+
+export { on, listBindings, resetBindings, type Binding } from "./kernel/on.ts";
+export { flow, isFlow, type FlowDef } from "./kernel/flow.ts";
+export { http, every, internal } from "./kernel/triggers.ts";
+export { gate, GATE_PUBLIC_NAME } from "./elements/gate/declare.ts";
+export { fail, type FlowFailure } from "./kernel/errors.ts";
+export { isFlowFailure } from "./kernel/hooks.ts";
+export { plugin, isPlugin, type PluginDef } from "./kernel/plugin.ts";
+export { createBunRuntime, APP_PORT, type Runtime, type ServeOptions } from "./runtime/index.ts";
+export type { OkeApp, OkeOptions, ReadyState } from "./kernel/app.ts";
+
+import { oke as okeCore, type OkeApp, type OkeOptions } from "./kernel/app.ts";
+
+/**
+ * Create an HTTP-oriented app — defaults `router` to `"edge"` when omitted.
+ *
+ * @param options - Application options
+ */
+export function oke(options: OkeOptions): OkeApp {
+  return okeCore({
+    ...options,
+    router: options.router ?? "edge",
+  });
+}

package/src/i18n/interpolate-simple.ts

@@ -0,0 +1,37 @@
+/**
+ * Zero-dependency message interpolation for the cold path.
+ *
+ * Handles plain strings and simple `{name}` placeholders. ICU plural /
+ * select / rich-text go through {@link formatMessage} (FormatJS) when needed.
+ */
+
+import type { MessageValues } from "./types.ts";
+
+/** True when the template needs ICU MessageFormat (plural/select/rich tags). */
+export function needsIcuFormat(message: string): boolean {
+  // plural/select: `{count, plural, …}` or `{gender, select, …}`
+  if (/\{[^{}]+,\s*(?:plural|select|selectordinal)\b/.test(message)) return true;
+  // rich-text tags: `<tag>…</tag>` or self-closing
+  if (/<\/?[A-Za-z][\w-]*/.test(message)) return true;
+  // number/date skeleton: `{n, number}` / `{d, date}`
+  if (/\{[^{}]+,\s*(?:number|date|time)\b/.test(message)) return true;
+  return false;
+}
+
+/**
+ * Replace simple `{name}` placeholders without FormatJS.
+ *
+ * @param message - Template
+ * @param values - Interpolation values
+ */
+export function interpolateSimple(message: string, values?: MessageValues): string {
+  // Catalogs use ICU apostrophe escaping (`''` → `'`) even on the simple path.
+  const base = message.replaceAll("''", "'");
+  if (!values) return base;
+  return base.replace(/\{(\w+)\}/g, (match, name: string) => {
+    const value = values[name];
+    if (value === undefined || value === null) return match;
+    if (typeof value === "function") return match;
+    return String(value);
+  });
+}

package/src/i18n/messages.ts

@@ -9,11 +9,58 @@
  * present; app keys override built-ins for the same locale/key.
  */
 
+import { createRequire } from "node:module";
 import { builtinAr } from "./catalogs/ar.ts";
 import { builtinEn } from "./catalogs/en.ts";
-import { formatMessage } from "./format.ts";
+import { interpolateSimple, needsIcuFormat } from "./interpolate-simple.ts";
 import type { MessageTree, MessageValues } from "./types.ts";
 
+const requireFormat = createRequire(import.meta.url);
+
+/** Cached FormatJS formatter (loaded on first ICU message). */
+let formatMessageFn:
+  | ((message: string, locale: string, values?: MessageValues) => string)
+  | undefined;
+let formatMessagePromise: Promise<typeof formatMessageFn> | undefined;
+
+/**
+ * Ensure FormatJS {@link formatMessage} is loaded (call from boot when catalogs exist).
+ */
+export async function preloadMessageFormat(): Promise<void> {
+  if (formatMessageFn) return;
+  formatMessagePromise ??= import("./format.ts").then((m) => {
+    formatMessageFn = m.formatMessage;
+    return formatMessageFn;
+  });
+  await formatMessagePromise;
+}
+
+/**
+ * Load FormatJS synchronously on the first ICU message (tests / pre-boot).
+ */
+function ensureFormatMessageSync(): NonNullable<typeof formatMessageFn> {
+  if (formatMessageFn) return formatMessageFn;
+  const mod = requireFormat("./format.ts") as {
+    formatMessage: NonNullable<typeof formatMessageFn>;
+  };
+  formatMessageFn = mod.formatMessage;
+  return formatMessageFn;
+}
+
+/**
+ * Format a resolved message — simple `{name}` on the cold path; ICU via FormatJS.
+ *
+ * @param message - Template
+ * @param locale - BCP 47 locale
+ * @param values - Interpolation values
+ */
+function formatResolved(message: string, locale: string, values?: MessageValues): string {
+  if (!needsIcuFormat(message)) {
+    return interpolateSimple(message, values);
+  }
+  return ensureFormatMessageSync()(message, locale, values);
+}
+
 export type { MessageTree, MessageValues } from "./types.ts";
 
 /** Flat key → message map after {@link flattenMessages}. */
@@ -62,7 +109,7 @@ export function defineMessages<const T extends MessageTree>(messages: T): T {
 /**
  * Register (or replace) messages for a locale.
  *
- * Side-effect import from `src/locales/<locale>.ts` before boot.
+ * Load locale modules before boot (starter: `core.ts` → `@/locales`).
  * Prefer `as const` / {@link defineMessages} on the default locale, then
  * `satisfies MessagesFor<typeof en>` on translations so keys stay aligned.
  *
@@ -134,10 +181,10 @@ export function translate(options: TranslateOptions): string {
   const { locale, defaultLocale, catalogs, key } = options;
   const values = options.values ?? options.params;
   const primary = catalogs[locale]?.[key];
-  if (primary !== undefined) return formatMessage(primary, locale, values);
+  if (primary !== undefined) return formatResolved(primary, locale, values);
   if (locale !== defaultLocale) {
     const fallback = catalogs[defaultLocale]?.[key];
-    if (fallback !== undefined) return formatMessage(fallback, defaultLocale, values);
+    if (fallback !== undefined) return formatResolved(fallback, defaultLocale, values);
   }
   if (values === undefined) return key;
   return `${key}:${JSON.stringify(values)}`;

package/src/i18n-entry.ts

@@ -0,0 +1,7 @@
+/**
+ * `okengine/i18n` — ICU catalogs and locale helpers.
+ *
+ * @module
+ */
+
+export * from "./i18n/index.ts";

package/src/index.ts

@@ -1,12 +1,12 @@
 /**
- * `okengine` public entry — kernel surface used by apps and examples.
+ * `okengine` public entry — ten exports + HTTP runtime essentials.
  *
- * Full ten-export surface lands as elements ship; this entry exposes the
- * executable core (oke · on · flow · http · fx · contracts).
+ * Heavy surfaces live on subpaths: `okengine/full`, `okengine/runs`,
+ * `okengine/i18n`, `okengine/compiler`, `okengine/journal`, `okengine/http`.
  *
  * @example
  * ```ts
- * import { oke, on, flow, http } from "okengine";
+ * import { oke, on, flow, http, gate } from "okengine";
  *
  * export const app = oke({ name: "notes" });
  * ```
@@ -14,52 +14,28 @@
  * @module
  */
 
+export { oke, type OkeApp, type OkeOptions, type ReadyState } from "./kernel/app.ts";
+export { on, type Binding } from "./kernel/on.ts";
+export { flow, isFlow, type FlowDef } from "./kernel/flow.ts";
+export { http, every, internal, table } from "./kernel/triggers.ts";
+export { fail, type FlowFailure, type FlowErrorValue } from "./kernel/errors.ts";
+export { isFlowFailure } from "./kernel/hooks.ts";
+export { plugin, isPlugin, type PluginDef, type PluginCapabilities } from "./kernel/plugin.ts";
+export type { Fx, FxPrincipal, StepOptions } from "./kernel/fx.ts";
+
 export {
-  oke,
-  on,
-  flow,
-  http,
-  every,
-  internal,
-  table,
-  fail,
-  createFx,
-  isFlow,
-  isFlowFailure,
-  plugin,
-  isPlugin,
-  bootApplication,
-  mintCapabilities,
-  gateDenialFailure,
-  journey,
-  unit,
-  rateLimit,
-  Redacted,
-  isRedacted,
-  maskRedactedDeep,
-  REDACTED_PLACEHOLDER,
-  PluginNeedsError,
-  assertPluginNeeds,
-  freezePrincipal,
-  installGracefulShutdown,
-  releaseInstanceLeases,
-  type OkeApp,
-  type OkeOptions,
-  type ReadyState,
-  type FlowDef,
-  type FlowFailure,
-  type FlowErrorValue,
-  type Fx,
-  type FxPrincipal,
-  type Binding,
-  type PluginDef,
-  type PluginCapabilities,
-  type BootOptions,
-  type BootResult,
-  type ElementRuntimes,
-  type JourneyDecl,
-  type UnitBag,
-} from "./kernel/index.ts";
+  defineLocale,
+  defineMessages,
+  flattenMessages,
+  getMessageCatalogs,
+  matchConfiguredLocale,
+  translate,
+  type MessageCatalog,
+  type MessageCatalogs,
+} from "./i18n/messages.ts";
+export type { AppMessageKey, MessageTree, MessageValues, MessagesFor } from "./i18n/types.ts";
+export { runWithLocale, type LocaleContext } from "./i18n/locale-context.ts";
+export { isRtlLocale, parseAcceptLanguage, resolveLocale } from "./elements/channel/locale.ts";
 
 export {
   store,
@@ -111,20 +87,16 @@ export {
 export {
   gate,
   GATE_PUBLIC_NAME,
-  GateBootError,
-  assertHttpGatePosture,
-  createGateRuntime,
-  resolveGateConfig,
-  takeRate,
-  deriveModuleActions,
-  ALL_RATE_STRATEGIES,
   type GateDecl,
-  type GateOptions,
-  type GatePostureGap,
-  type GateRuntime,
   type RateOptions,
+} from "./elements/gate/declare.ts";
+export {
+  resolveGateConfig,
+  type GateOptions,
   type ResolvedGateConfig,
-} from "./elements/gate.ts";
+} from "./elements/gate/config.ts";
+export { GateBootError, assertHttpGatePosture, type GatePostureGap } from "./elements/gate/boot.ts";
+export { DEFAULT_RATE_STRATEGY, ALL_RATE_STRATEGIES } from "./elements/gate/constants.ts";
 
 export {
   vault,
@@ -133,6 +105,9 @@ export {
   createVaultRuntime,
   VaultBootError,
   SECRET_MASK,
+  listRequiredEnvNames,
+  resetRequiredEnvNames,
+  type VaultEnvApi,
   type VaultSecretDecl,
   type VaultRuntime,
 } from "./elements/vault.ts";
@@ -161,95 +136,10 @@ export {
   type AiRuntime,
 } from "./elements/ai.ts";
 
-export {
-  createJournal,
-  createMemoryJournalStore,
-  createFileJournalStore,
-  hasJournalLease,
-  isJournalLeaseBusy,
-  JournalLeaseBusy,
-  JOURNAL_DEFAULT_LEASE_MS,
-  type Journal,
-  type JournalLeaseOptions,
-  type JournalLeaseStore,
-  type JournalStore,
-  type JournalRun,
-} from "./kernel/journal.ts";
-
-export {
-  validate,
-  isStandardSchema,
-  fromTypeBox,
-  VALIDATION_ERROR_CODE,
-  type StandardSchemaV1,
-  type SchemaInput,
-  type ValidationErrorData,
-} from "./validation/index.ts";
-
-export {
-  compileAot,
-  compileDynamic,
-  compileRoute,
-  sucrose,
-  type CompiledRoute,
-  type ContextInference,
-} from "./compiler/index.ts";
-
-export {
-  defineLocale,
-  defineMessages,
-  flattenMessages,
-  formatMessage,
-  getMessageCatalogs,
-  interpolateMessage,
-  isRtlLocale,
-  matchConfiguredLocale,
-  parseAcceptLanguage,
-  resolveFailureMessage,
-  resolveLocale,
-  runWithLocale,
-  translate,
-  type AppMessageKey,
-  type FlattenKeys,
-  type LocaleContext,
-  type MessageCatalog,
-  type MessageCatalogs,
-  type MessageTree,
-  type MessageValue,
-  type MessageValues,
-  type MessagesFor,
-  type Register,
-} from "./i18n/index.ts";
-
 export {
   createBunRuntime,
   createWebStandardRuntime,
   APP_PORT,
-  CONSOLE_PORT,
-  MCP_PORT,
   type Runtime,
   type ServeOptions,
 } from "./runtime/index.ts";
-export {
-  createRunsRuntime,
-  collectWideEvent,
-  createRunTelemetry,
-  explainOutliers,
-  seedOutlierDataset,
-  privacyErase,
-  createMemorySubjectKeys,
-  subjectKeysFromVault,
-  archiveFields,
-  revealArchived,
-  eraseSubject,
-  SHREDDED,
-  filesRunsDriver,
-  memoryRunsDriver,
-  postgresRunsDriver,
-  clickhouseRunsDriver,
-  type RunsRuntime,
-  type WideEvent,
-  type CreateRunsRuntimeOptions,
-  type OutlierFinding,
-  type SubjectKeyVault,
-} from "./runs/index.ts";

package/src/journal-entry.ts

@@ -0,0 +1,20 @@
+/**
+ * `okengine/journal` — durable-run journal stores.
+ *
+ * @module
+ */
+
+export {
+  createJournal,
+  createMemoryJournalStore,
+  createFileJournalStore,
+  hasJournalLease,
+  isJournalLeaseBusy,
+  JournalLeaseBusy,
+  JOURNAL_DEFAULT_LEASE_MS,
+  type Journal,
+  type JournalLeaseOptions,
+  type JournalLeaseStore,
+  type JournalStore,
+  type JournalRun,
+} from "./kernel/journal.ts";