@open-mercato/shared 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/src/lib/ai/opencode-tool-parts.ts

@@ -0,0 +1,80 @@
+/**
+ * Normalizes an OpenCode `message.part.updated` part into a tool-call lifecycle
+ * update, shielding callers from OpenCode's wire schema.
+ *
+ * OpenCode (Go server) streams MCP tool invocations as parts of `type: 'tool'`
+ * carrying a `callID`, the `tool` name, and a `state` machine
+ * (`state.status: pending|running|completed|error`, `state.input`,
+ * `state.output`/`state.error`). The same part id is re-emitted on each state
+ * transition, so a tool call surfaces as one or more `progress` updates followed
+ * by a single `finish` once the state reaches a terminal status.
+ *
+ * Older OpenCode builds emitted Anthropic-style `tool_use` / `tool_result`
+ * blocks instead; those are still recognized as a fallback so a downgrade does
+ * not silently drop traces again.
+ *
+ * Returns `null` for any part that is not a tool invocation (text, thinking,
+ * step markers, …) so callers can ignore it.
+ */
+export type OpenCodeToolPartUpdate =
+  | { phase: 'progress'; callId: string; toolName: string; input?: unknown }
+  | {
+      phase: 'finish'
+      callId: string
+      toolName?: string
+      input?: unknown
+      output?: unknown
+      status: 'ok' | 'error'
+    }
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {}
+}
+
+export function normalizeOpenCodeToolPart(rawPart: unknown): OpenCodeToolPartUpdate | null {
+  if (!rawPart || typeof rawPart !== 'object') return null
+  const part = rawPart as Record<string, unknown>
+  const type = asString(part.type)
+  if (!type) return null
+
+  // Native OpenCode tool part with a state machine.
+  if (type === 'tool') {
+    const callId = asString(part.callID) ?? asString(part.id)
+    const toolName = asString(part.tool)
+    if (!callId || !toolName) return null
+    const state = asRecord(part.state)
+    const status = asString(state.status)
+    const input = 'input' in state ? state.input : undefined
+    if (status === 'completed' || status === 'error') {
+      const output = status === 'error' ? state.error ?? state.output : state.output
+      return {
+        phase: 'finish',
+        callId,
+        toolName,
+        input,
+        output,
+        status: status === 'error' ? 'error' : 'ok',
+      }
+    }
+    return { phase: 'progress', callId, toolName, input }
+  }
+
+  // Legacy Anthropic-style parts (older OpenCode builds).
+  if (type === 'tool_use') {
+    const callId = asString(part.id)
+    const toolName = asString(part.name)
+    if (!callId || !toolName) return null
+    return { phase: 'progress', callId, toolName, input: part.input }
+  }
+  if (type === 'tool_result') {
+    const callId = asString(part.tool_use_id) ?? asString(part.id)
+    if (!callId) return null
+    return { phase: 'finish', callId, output: part.content, status: 'ok' }
+  }
+
+  return null
+}

package/src/lib/ai/token-count.ts

@@ -0,0 +1,21 @@
+import { encode } from 'gpt-tokenizer/encoding/o200k_base'
+
+/**
+ * Model-agnostic offline token estimate.
+ *
+ * Uses the `o200k_base` BPE encoding (GPT-4o / GPT-5 family) as a proxy. It is
+ * NOT exact for non-OpenAI models — notably Claude, whose tokenizer is not
+ * available offline — but it is deterministic, dependency-light, and a far
+ * closer estimate than a chars/4 heuristic. Treat the result as an estimate.
+ *
+ * Infrastructure only: this file knows nothing about any domain shape. Callers
+ * that need to break a structure down into elements assemble their own totals
+ * on top of this primitive.
+ */
+export function countTokens(text: string | null | undefined): number {
+  if (!text) return 0
+  return encode(text).length
+}
+
+/** The BPE encoding backing {@link countTokens}, surfaced so callers can label estimates. */
+export const TOKEN_ENCODING = 'o200k_base' as const

package/src/lib/bootstrap/dynamicLoader.ts

@@ -1,3 +1,4 @@
+import { asValue } from 'awilix'
 import type { BootstrapData } from './types'
 import type { AppDiRegistrar } from '../di/container'
 import { findAppRoot, type AppRoot } from './appResolver'
@@ -497,6 +498,21 @@ async function compileAndImport(
 }
 
 
+/**
+ * Registers an app-owned generated value on the request container.
+ *
+ * The app registers these statically from `src/di.ts`, which `createRequestContainer`
+ * reaches through the `@/` alias — and that alias only exists under the bundler.
+ * A CLI or MCP process runs plain Node, so the import fails, the failure is
+ * swallowed, and the value is simply absent with no diagnostic. Routing it through
+ * a registrar built from the same generated file keeps both processes in step.
+ */
+function appValueRegistrar(key: string, value: unknown): BootstrapData['diRegistrars'][number] {
+  return (container) => {
+    container.register({ [key]: asValue(value) })
+  }
+}
+
 /**
  * Load a generated registry that older apps may not have generated yet.
  *
@@ -716,6 +732,7 @@ async function loadBootstrapDataWithActiveEsbuild(appRoot?: string): Promise<Boo
     diModule,
     searchModule,
     commandLoadersModule,
+    webResearchModule,
     commandInterceptorsModule,
     workflowsModule,
   ] = await Promise.all([
@@ -724,6 +741,9 @@ async function loadBootstrapDataWithActiveEsbuild(appRoot?: string): Promise<Boo
     compileAndImport(path.join(generatedDir, 'di.generated.ts')),
     loadOptionalGeneratedModule(path.join(generatedDir, 'search.generated.ts'), { searchModuleConfigs: [] }),
     loadOptionalGeneratedModule(path.join(generatedDir, 'command-loaders.generated.ts'), { commandLoaderEntries: [] }),
+    loadOptionalGeneratedModule(path.join(generatedDir, 'web-research-adapters.generated.ts'), {
+      webResearchAdapterEntries: [],
+    }),
     loadOptionalGeneratedModule(path.join(generatedDir, 'command-interceptors.generated.ts'), {
       commandInterceptorEntries: [],
     }),
@@ -733,7 +753,10 @@ async function loadBootstrapDataWithActiveEsbuild(appRoot?: string): Promise<Boo
   return {
     modules: modulesModule.modules as BootstrapData['modules'],
     entities: entitiesModule.entities as BootstrapData['entities'],
-    diRegistrars: diModule.diRegistrars as BootstrapData['diRegistrars'],
+    diRegistrars: [
+      ...(diModule.diRegistrars as BootstrapData['diRegistrars']),
+      appValueRegistrar('webResearchAdapterEntries', webResearchModule.webResearchAdapterEntries ?? []),
+    ],
     entityIds: entityIdsModule.E as BootstrapData['entityIds'],
     // Search configs are needed by workers for indexing
     searchModuleConfigs: (searchModule.searchModuleConfigs ?? []) as BootstrapData['searchModuleConfigs'],

package/src/lib/commands/__tests__/command-bus.test.ts

@@ -298,6 +298,70 @@ describe('CommandBus', () => {
     )
   })
 
+  // Agent Identity & On-Behalf-Of (Wave 4 P2): when ctx.runAs is set the SAME
+  // audit path attributes the write to the agent principal on behalf of the human,
+  // sourced 'agent' — not a parallel audit route.
+  it('stamps actorUserId=agent + onBehalfOfUserId=human + source=agent when ctx.runAs is set', async () => {
+    const logMock = jest.fn(async () => ({ id: 'log-runas' }))
+    registerCommand({
+      id: 'test.command.runas',
+      execute: jest.fn(async () => ({ ok: true })),
+      buildLog: jest.fn(() => ({ actionLabel: 'Agent write', resourceKind: 'deal', resourceId: 'deal-9' })),
+    })
+
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      // The invoking human still carries the JWT auth, but runAs overrides the actor.
+      auth: { sub: 'human-1', tenantId: 'tenant-1', orgId: 'org-1' },
+      organizationScope: null,
+      selectedOrganizationId: 'org-1',
+      organizationIds: ['org-1'],
+      runAs: { actorUserId: 'agent-user-1', onBehalfOfUserId: 'human-1', source: 'agent' as const },
+    }
+
+    await bus.execute('test.command.runas', { input: {}, ctx })
+
+    expect(logMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        commandId: 'test.command.runas',
+        actorUserId: 'agent-user-1',
+        onBehalfOfUserId: 'human-1',
+        context: expect.objectContaining({ source: 'agent' }),
+      })
+    )
+  })
+
+  it('does not set onBehalfOfUserId for ordinary (non-runAs) human writes — additive default', async () => {
+    const logMock = jest.fn(async () => ({ id: 'log-plain' }))
+    registerCommand({
+      id: 'test.command',
+      execute: jest.fn(async () => ({ ok: true })),
+      buildLog: jest.fn(() => ({ actionLabel: 'Plain', resourceKind: 'test', resourceId: '7' })),
+    })
+
+    const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+    container.register({ actionLogService: asValue({ log: logMock }) })
+
+    const bus = new CommandBus()
+    const ctx = {
+      container,
+      auth: { sub: 'user-1', tenantId: 'tenant-1', orgId: null },
+      organizationScope: null,
+      selectedOrganizationId: null,
+      organizationIds: null,
+    }
+
+    await bus.execute('test.command', { input: {}, ctx })
+
+    const payload = logMock.mock.calls[0][0] as Record<string, unknown>
+    expect(payload.actorUserId).toBe('user-1')
+    expect(payload.onBehalfOfUserId).toBeUndefined()
+  })
+
   describe('interceptor rejections', () => {
     const blockingInterceptor = (result: Record<string, unknown>): CommandInterceptor => ({
       id: 'test.block',

package/src/lib/commands/__tests__/registry.test.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod'
 import { commandRegistry, registerCommand, registerCommandLoaders } from '@open-mercato/shared/lib/commands'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
@@ -104,6 +105,40 @@ describe('command registry registration', () => {
     expect(commandRegistry.list()).not.toContain('test:commands:fallback')
   })
 
+  it('returns the outputSchema for a registered handler that declares one and null otherwise', () => {
+    const outputSchema = z.object({ dealId: z.string().uuid() })
+
+    registerCommand({
+      id: 'test.command.with-output',
+      execute: jest.fn(),
+      outputSchema,
+    })
+    registerCommand({
+      id: 'test.command.without-output',
+      execute: jest.fn(),
+    })
+
+    expect(commandRegistry.outputSchemaOf('test.command.with-output')).toBe(outputSchema)
+    expect(commandRegistry.outputSchemaOf('test.command.without-output')).toBeNull()
+    expect(commandRegistry.outputSchemaOf('test.command.never-registered')).toBeNull()
+  })
+
+  it('does not trigger lazy loaders when resolving output schemas', () => {
+    const load = jest.fn(async () => {})
+
+    registerCommandLoaders([
+      {
+        moduleId: 'test',
+        id: 'test.command.lazy-output',
+        key: 'test:commands:lazy-output',
+        load,
+      },
+    ])
+
+    expect(commandRegistry.outputSchemaOf('test.command.lazy-output')).toBeNull()
+    expect(load).not.toHaveBeenCalled()
+  })
+
   it('loads sibling module command files with an exact lazy command', async () => {
     registerCommandLoaders([
       {

package/src/lib/commands/command-bus.ts

@@ -543,6 +543,7 @@ export class CommandBus {
       tenantId: secondary?.tenantId ?? primary?.tenantId ?? null,
       organizationId: secondary?.organizationId ?? primary?.organizationId ?? null,
       actorUserId: secondary?.actorUserId ?? primary?.actorUserId ?? null,
+      onBehalfOfUserId: secondary?.onBehalfOfUserId ?? primary?.onBehalfOfUserId ?? null,
       actionLabel: secondary?.actionLabel ?? primary?.actionLabel ?? null,
       resourceKind: secondary?.resourceKind ?? primary?.resourceKind ?? null,
       resourceId: secondary?.resourceId ?? primary?.resourceId ?? null,
@@ -582,7 +583,13 @@ export class CommandBus {
     const tenantId = metadata.tenantId ?? options.ctx.auth?.tenantId ?? null
     const organizationId =
       metadata.organizationId ?? options.ctx.selectedOrganizationId ?? options.ctx.auth?.orgId ?? null
-    const actorUserId = metadata.actorUserId ?? options.ctx.auth?.sub ?? null
+    // On-behalf-of attribution (Wave 4 P2): when `ctx.runAs` is set the actor is
+    // the agent principal and the human it acts for is recorded separately. This
+    // funnels agent writes through the SAME ActionLog path as a human's — only the
+    // attribution differs (actorUserId=agent, onBehalfOfUserId=human, source='agent').
+    const runAs = options.ctx.runAs ?? null
+    const actorUserId = runAs?.actorUserId ?? metadata.actorUserId ?? options.ctx.auth?.sub ?? null
+    const onBehalfOfUserId = runAs ? (runAs.onBehalfOfUserId ?? null) : (metadata.onBehalfOfUserId ?? null)
     const systemActorContext = !actorUserId && options.ctx.systemActor === true
       ? { systemActor: 'system:command' }
       : null
@@ -590,6 +597,7 @@ export class CommandBus {
       tenantId: tenantId ?? undefined,
       organizationId: organizationId ?? undefined,
       actorUserId: actorUserId ?? undefined,
+      onBehalfOfUserId: onBehalfOfUserId ?? undefined,
       commandId,
     }
 
@@ -613,6 +621,13 @@ export class CommandBus {
       }
     }
 
+    if (runAs) {
+      // Stamp the audit source so `deriveActionLogSource` projects `sourceKey='agent'`.
+      // Merge into any caller-provided context rather than replacing it.
+      const baseContext = asRecord(payload.context) ?? {}
+      payload.context = { ...baseContext, source: runAs.source }
+    }
+
     const redoEnvelope = wrapRedoPayload('commandPayload' in payload ? (payload.commandPayload as unknown) : undefined, options.input)
     payload.commandPayload = redoEnvelope
 

package/src/lib/commands/registry.ts

@@ -1,3 +1,4 @@
+import type { ZodTypeAny } from 'zod'
 import type { CommandHandler } from './types'
 import { createLogger } from '../logger'
 
@@ -78,6 +79,16 @@ class CommandRegistry {
     return this.handlers.has(id) || this.loadersById.has(id)
   }
 
+  /**
+   * Returns the `outputSchema` declared by an already-registered handler, or
+   * `null` when the handler declares none. Sync over registered handlers only:
+   * it never triggers lazy loaders, so a handler that is known but not yet
+   * loaded also yields `null` — call `load(id)` first when that matters.
+   */
+  outputSchemaOf(id: string): ZodTypeAny | null {
+    return this.get(id)?.outputSchema ?? null
+  }
+
   /**
    * List all known command IDs, including exact lazy loaders that have not
    * been imported yet.

package/src/lib/commands/types.ts

@@ -1,5 +1,6 @@
 import type { AwilixContainer } from 'awilix'
 import type { EntityManager } from '@mikro-orm/postgresql'
+import type { ZodTypeAny } from 'zod'
 import { randomUUID } from 'crypto'
 import type { AuthContext } from '../auth/server'
 import type { OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'
@@ -57,6 +58,28 @@ export type CommandRuntimeContext = {
    * surrounding work as a single atomic, single-locked operation.
    */
   transactionalEm?: EntityManager
+  /**
+   * On-behalf-of attribution for non-human principals (Agent Identity &
+   * On-Behalf-Of, Wave 4 P2). When an agent runs on behalf of a human, the
+   * orchestrator's `runAs` wrapper sets this so every `ActionLog` the command
+   * path writes records `actorUserId = runAs.actorUserId` (the agent principal's
+   * `auth.User` id), `onBehalfOfUserId = runAs.onBehalfOfUserId` (the invoking
+   * human, or null for system-invoked agents), and `sourceKey = runAs.source`
+   * (`'agent'`). Additive + optional: callers that omit it keep the existing
+   * `ctx.auth.sub`-derived attribution unchanged. This threads agent attribution
+   * through the SAME audited Command/CRUD path as a human action — not a parallel
+   * audit path.
+   */
+  runAs?: CommandRunAsContext
+}
+
+export type CommandRunAsContext = {
+  /** The actor stamped on every ActionLog this context produces (agent `auth.User` id). */
+  actorUserId: string
+  /** The human (or system) principal the actor acts on behalf of; null when system-invoked. */
+  onBehalfOfUserId?: string | null
+  /** The audit source key for the attributed writes; `'agent'` for agent runs. */
+  source: 'agent'
 }
 
 export type CommandLogMetadata = {
@@ -64,6 +87,7 @@ export type CommandLogMetadata = {
   tenantId?: string | null
   organizationId?: string | null
   actorUserId?: string | null
+  onBehalfOfUserId?: string | null
   actionLabel?: string | null
   resourceKind?: string | null
   resourceId?: string | null
@@ -129,6 +153,13 @@ export type CommandLogBuilderArgs<TInput, TResult> = {
 export interface CommandHandler<TInput = unknown, TResult = unknown> {
   readonly id: string
   readonly isUndoable?: boolean
+  /**
+   * Optional Zod schema describing the command's return value. Feeds the
+   * workflows context ledger so downstream activities can reason about the
+   * shape a command produces; when absent the ledger renders the output as
+   * unknown.
+   */
+  readonly outputSchema?: ZodTypeAny
   prepare?(input: TInput, ctx: CommandRuntimeContext): Promise<{ before?: unknown } | null> | { before?: unknown } | null
   execute(input: TInput, ctx: CommandRuntimeContext): Promise<TResult> | TResult
   buildLog?(args: CommandLogBuilderArgs<TInput, TResult>): Promise<CommandLogMetadata | null | undefined> | CommandLogMetadata | null | undefined

package/src/lib/di/__tests__/bootstrap-cache.test.ts

@@ -210,7 +210,7 @@ describe('bootstrap once-guard cache', () => {
     expect(bootstrapMock).toHaveBeenCalledTimes(2)
   })
 
-  it('memoizes tenantEncryptionService.isEnabled() across requests', async () => {
+  it('registers the encryption subscriber per request without consulting tenantEncryptionService.isEnabled()', async () => {
     process.env.OM_BOOTSTRAP_CACHE = '1'
     let isEnabledCalls = 0
     bootstrapMock.mockImplementationOnce(async (container: any) => {
@@ -229,8 +229,64 @@ describe('bootstrap once-guard cache', () => {
     await createRequestContainer()
     await createRequestContainer()
     await createRequestContainer()
-    // Called once during the first bootstrap, then cached on globalThis.
-    expect(isEnabledCalls).toBe(1)
+    // The registration decision reads the static config toggle (memoized on
+    // globalThis), never the service's health-sensitive isEnabled() — see #5948.
+    expect(isEnabledCalls).toBe(0)
     expect(subscriberRegistered).toHaveBeenCalledTimes(3)
   })
+
+  // Regression for issue #5948: `isEnabled()` is `config && kms.isHealthy()`, so
+  // memoizing it for the process lifetime pinned a transient Vault outage into a
+  // permanent "encryption off" verdict — the subscriber was never registered
+  // again on any later request, and every ORM write stayed plaintext until the
+  // process restarted.
+  it('keeps registering the encryption subscriber while the KMS is unhealthy', async () => {
+    process.env.OM_BOOTSTRAP_CACHE = '1'
+    bootstrapMock.mockImplementationOnce(async (container: any) => {
+      container.register({
+        cache: asValue({ __value: 'cache-value' }),
+        eventBus: asValue({ __value: 'event-bus-value' }),
+        // KMS is down for the whole run: isEnabled() never returns true.
+        tenantEncryptionService: asValue({ isEnabled: () => false }),
+      })
+    })
+    const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+    await createRequestContainer()
+    await createRequestContainer()
+
+    // Registration must not depend on live KMS health — the subscriber itself
+    // re-checks it per read/write, so it resumes encrypting on recovery.
+    expect(subscriberRegistered).toHaveBeenCalledTimes(2)
+  })
+
+  it('skips registration when the encryption service cannot report its enabled state', async () => {
+    process.env.OM_BOOTSTRAP_CACHE = '1'
+    bootstrapMock.mockImplementationOnce(async (container: any) => {
+      container.register({
+        cache: asValue({ __value: 'cache-value' }),
+        eventBus: asValue({ __value: 'event-bus-value' }),
+        // A DI override supplying a partial service: the subscriber would throw
+        // on every read/write calling isEnabled(), so it must not be registered.
+        tenantEncryptionService: asValue({ __value: 'no-isEnabled' }),
+      })
+    })
+    const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+    await createRequestContainer()
+    expect(subscriberRegistered).not.toHaveBeenCalled()
+  })
+
+  it('does not register the encryption subscriber when encryption is disabled by config', async () => {
+    process.env.OM_BOOTSTRAP_CACHE = '1'
+    const originalToggle = process.env.TENANT_DATA_ENCRYPTION
+    process.env.TENANT_DATA_ENCRYPTION = 'false'
+    try {
+      const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+      await createRequestContainer()
+      await createRequestContainer()
+      expect(subscriberRegistered).not.toHaveBeenCalled()
+    } finally {
+      if (originalToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+      else process.env.TENANT_DATA_ENCRYPTION = originalToggle
+    }
+  })
 })

package/src/lib/di/container.ts

@@ -9,6 +9,7 @@ import { applyDiOverridesToContainer } from '@open-mercato/shared/modules/overri
 import { createOptimisticLockGuardService } from '@open-mercato/shared/lib/crud/optimistic-lock'
 import { getAllOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 import { createCommandOptimisticLockGuardService } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isTenantDataEncryptionEnabled } from '../encryption/toggles'
 import { createLogger } from '../logger'
 
 const logger = createLogger('shared').child({ component: 'di' })
@@ -93,19 +94,18 @@ function harvestBootstrapCache(container: AwilixContainer): BootstrapCacheEntry
   return entry
 }
 
-type EncryptionEnabledProbe = { isEnabled?: () => boolean } | null | undefined
-
-function getCachedEncryptionEnabled(service: EncryptionEnabledProbe): boolean | null {
-  if (!service || typeof service.isEnabled !== 'function') return false
+// Caches the STATIC config toggle only. It deliberately does not consult
+// `tenantEncryptionService.isEnabled()`, which ANDs the toggle with the
+// volatile `kms.isHealthy()` — memoizing that for the process lifetime pinned a
+// transient Vault outage into a permanent "encryption off" verdict, so the
+// subscriber was never registered again until a restart (#5948). KMS health is
+// re-checked by the subscriber on every read/write instead.
+function getCachedEncryptionConfigured(): boolean {
   const cached = (globalThis as Record<string, unknown>)[ENCRYPTION_ENABLED_KEY]
   if (typeof cached === 'boolean') return cached
-  try {
-    const result = !!service.isEnabled()
-    ;(globalThis as Record<string, unknown>)[ENCRYPTION_ENABLED_KEY] = result
-    return result
-  } catch {
-    return null
-  }
+  const result = isTenantDataEncryptionEnabled()
+  ;(globalThis as Record<string, unknown>)[ENCRYPTION_ENABLED_KEY] = result
+  return result
 }
 
 function getGlobalRegistrars(): DiRegistrar[] | null {
@@ -319,15 +319,19 @@ export async function createRequestContainer(): Promise<AppContainer> {
     unregister: (key) => container.register({ [key]: asValue(undefined) }),
   })
   // Ensure tenant encryption subscriber is always registered on the fresh request-scoped EM
-  // Phase 5 — cache `tenantEncryptionService.isEnabled()` for the process
-  // lifetime. The result depends only on config that does not change at
-  // runtime, so reading it once skips a config lookup per request.
+  // Phase 5 — cache the tenant-encryption config toggle for the process
+  // lifetime. That toggle does not change at runtime, so reading it once skips
+  // a config lookup per request; KMS health is NOT part of this decision.
   try {
     const emForEnc = container.resolve('em') as any
     const tenantEncryptionService = container.hasRegistration('tenantEncryptionService')
       ? (container.resolve('tenantEncryptionService') as any)
       : null
-    if (emForEnc && tenantEncryptionService && getCachedEncryptionEnabled(tenantEncryptionService) === true) {
+    // The subscriber calls `service.isEnabled()` on every read/write, so a DI
+    // override supplying a service without it would throw per operation. Keep
+    // the shape check that the old health-probe helper performed.
+    const serviceCanReportEnabled = typeof tenantEncryptionService?.isEnabled === 'function'
+    if (emForEnc && serviceCanReportEnabled && getCachedEncryptionConfigured()) {
       const { registerTenantEncryptionSubscriber } = await import('@open-mercato/shared/lib/encryption/subscriber')
       registerTenantEncryptionSubscriber(emForEnc, tenantEncryptionService)
     }

package/src/lib/encryption/__tests__/subscriber.kms-recovery.test.ts

@@ -0,0 +1,112 @@
+// Regression coverage for issue #5948: registration of the tenant-encryption ORM
+// subscriber used to be gated on `kmsService.isHealthy()`, evaluated exactly once
+// at bootstrap. A KMS outage overlapping process startup therefore left the
+// subscriber unregistered — and at-rest encryption off — for the whole process
+// lifetime, recoverable only by a restart.
+//
+// The fix registers on the static config toggle alone and leans on the
+// subscriber's own per-operation `service.isEnabled()` check. These tests pin
+// that contract: a subscriber registered while the KMS is down must start
+// encrypting the moment the KMS recovers, with no re-registration, and must
+// leave an ongoing (throttled) signal while it is failing open.
+
+const warn = jest.fn()
+
+jest.mock('../../logger', () => {
+  const logger: Record<string, unknown> = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: (...args: unknown[]) => warn(...args),
+    error: jest.fn(),
+  }
+  logger.child = () => logger
+  return { createLogger: () => logger }
+})
+
+import { TenantEncryptionSubscriber, resetEncryptionPausedWarnThrottle } from '../subscriber'
+import { registerEntityIds } from '../entityIds'
+import type { TenantDataEncryptionService } from '../tenantDataEncryptionService'
+
+const META = {
+  className: 'Thing',
+  tableName: 'things',
+  properties: { secret: { name: 'secret', fieldName: 'secret' } },
+} as any
+
+function makeEm() {
+  return { getComparator: () => undefined, getMetadata: () => undefined }
+}
+
+// Mirrors the production service: `isEnabled()` ANDs the static config toggle
+// with the volatile KMS health flag, so it flips as Vault goes down and recovers.
+function makeService(kms: { healthy: boolean }): TenantDataEncryptionService {
+  return {
+    isEnabled: () => kms.healthy,
+    async encryptEntityPayload(_entityId: string, target: Record<string, unknown>) {
+      return { secret: `enc:${String(target.secret)}` }
+    },
+    async decryptEntityPayload() {
+      return {}
+    },
+  } as unknown as TenantDataEncryptionService
+}
+
+describe('TenantEncryptionSubscriber KMS recovery (issue #5948)', () => {
+  const originalToggle = process.env.TENANT_DATA_ENCRYPTION
+
+  beforeEach(() => {
+    delete process.env.TENANT_DATA_ENCRYPTION // default => encryption enabled
+    registerEntityIds({ test: { thing: 'test:thing' } })
+    resetEncryptionPausedWarnThrottle()
+    warn.mockClear()
+  })
+
+  afterEach(() => {
+    if (originalToggle === undefined) delete process.env.TENANT_DATA_ENCRYPTION
+    else process.env.TENANT_DATA_ENCRYPTION = originalToggle
+    jest.restoreAllMocks()
+  })
+
+  async function create(subscriber: TenantEncryptionSubscriber, entity: Record<string, unknown>) {
+    await subscriber.beforeCreate({ entity, meta: META, em: makeEm() } as any)
+  }
+
+  it('resumes encrypting after the KMS recovers, without re-registering the subscriber', async () => {
+    const kms = { healthy: false }
+    // The single subscriber instance a boot-time registration would have produced.
+    const subscriber = new TenantEncryptionSubscriber(makeService(kms))
+
+    const duringOutage: Record<string, unknown> = { tenantId: 't1', secret: 'plain' }
+    await create(subscriber, duringOutage)
+    expect(duringOutage.secret).toBe('plain')
+
+    // Vault comes back — the very same subscriber instance must start encrypting.
+    kms.healthy = true
+    const afterRecovery: Record<string, unknown> = { tenantId: 't1', secret: 'plain' }
+    await create(subscriber, afterRecovery)
+    expect(afterRecovery.secret).toBe('enc:plain')
+  })
+
+  it('warns while writes are failing open to plaintext, throttled to one line per window', async () => {
+    const subscriber = new TenantEncryptionSubscriber(makeService({ healthy: false }))
+
+    await create(subscriber, { tenantId: 't1', secret: 'a' })
+    await create(subscriber, { tenantId: 't1', secret: 'b' })
+    await create(subscriber, { tenantId: 't1', secret: 'c' })
+
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(warn.mock.calls[0][0]).toMatch(/KMS is unavailable/)
+    expect(warn.mock.calls[0][1]).toEqual({ entity: 'Thing' })
+  })
+
+  it('stays silent when encryption is deliberately disabled by config', async () => {
+    process.env.TENANT_DATA_ENCRYPTION = 'false'
+    const subscriber = new TenantEncryptionSubscriber(makeService({ healthy: false }))
+
+    const entity: Record<string, unknown> = { tenantId: 't1', secret: 'plain' }
+    await create(subscriber, entity)
+
+    expect(entity.secret).toBe('plain')
+    expect(warn).not.toHaveBeenCalled()
+  })
+})