@open-mercato/shared 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

package/dist/modules/search.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/modules/search.ts"],
-  "sourcesContent": ["import type { EntityId } from './entities'\n\n// =============================================================================\n// Strategy Identifiers\n// =============================================================================\n\n/**\n * Built-in strategy identifiers plus extensible string for third-party strategies.\n */\nexport type SearchStrategyId = 'tokens' | 'vector' | 'fulltext' | (string & Record<string, never>)\n\n// =============================================================================\n// Result Types\n// =============================================================================\n\n/**\n * Presenter metadata for displaying search results in UI (Cmd+K, global search).\n */\nexport type SearchResultPresenter = {\n  title: string\n  subtitle?: string\n  icon?: string\n  badge?: string\n}\n\n/**\n * Deep link rendered next to a search result.\n */\nexport type SearchResultLink = {\n  href: string\n  label: string\n  kind?: 'primary' | 'secondary'\n}\n\n/**\n * A single search result returned by a strategy.\n */\nexport type SearchResult = {\n  /** Entity type identifier, e.g., 'customers:customer_person_profile' */\n  entityId: EntityId\n  /** Record primary key */\n  recordId: string\n  /** Relevance score (normalized 0-1 range preferred, but RRF scores may exceed 1) */\n  score: number\n  /** Which strategy produced this result */\n  source: SearchStrategyId\n  /** Optional presenter for quick display */\n  presenter?: SearchResultPresenter\n  /** Primary URL when result is clicked */\n  url?: string\n  /** Additional action links */\n  links?: SearchResultLink[]\n  /** Extra metadata from the strategy */\n  metadata?: Record<string, unknown>\n  /** Organization scope of the result, when known by the strategy. */\n  organizationId?: string | null\n}\n\n// =============================================================================\n// Search Options\n// =============================================================================\n\n/**\n * Options passed to SearchService.search()\n */\nexport type SearchOptions = {\n  /** Tenant isolation - required */\n  tenantId: string\n  /**\n   * Optional organization filter.\n   * - `string` restricts results to that organization only.\n   * - `undefined` or `null` means no organization filter (tenant-wide).\n   */\n  organizationId?: string | null\n  /**\n   * Optional organization allowlist.\n   * - Non-empty array restricts results to one of those organizations.\n   * - Empty array means no organizations are visible and should return no results.\n   * - `undefined` or `null` means no organization filter (tenant-wide).\n   *\n   * `organizationId` takes precedence when both are provided.\n   */\n  organizationIds?: string[] | null\n  /** Filter to specific entity types */\n  entityTypes?: EntityId[]\n  /** Use only specific strategies (defaults to all available) */\n  strategies?: SearchStrategyId[]\n  /** Maximum results per strategy before merging */\n  limit?: number\n  /** Offset for pagination */\n  offset?: number\n  /** How to combine results: 'or' merges all, 'and' requires match in all strategies */\n  combineMode?: 'or' | 'and'\n}\n\n// =============================================================================\n// Indexable Record\n// =============================================================================\n\n/**\n * A record prepared for indexing across all strategies.\n */\nexport type IndexableRecord = {\n  /** Entity type identifier */\n  entityId: EntityId\n  /** Record primary key */\n  recordId: string\n  /** Tenant for isolation */\n  tenantId: string\n  /** Optional organization for additional filtering */\n  organizationId?: string | null\n  /** All fields from the record (strategies will filter based on their needs) */\n  fields: Record<string, unknown>\n  /** Optional presenter for result display */\n  presenter?: SearchResultPresenter\n  /** Primary URL for the record */\n  url?: string\n  /** Additional action links */\n  links?: SearchResultLink[]\n  /** Text content for embedding (from buildSource, used by vector strategy) */\n  text?: string | string[]\n  /** Source object for checksum calculation (change detection) */\n  checksumSource?: unknown\n}\n\n// =============================================================================\n// Strategy Interface\n// =============================================================================\n\n/**\n * Interface that all search strategies must implement.\n * Following the cache module's strategy pattern.\n */\nexport interface SearchStrategy {\n  /** Unique strategy identifier */\n  readonly id: SearchStrategyId\n\n  /** Human-readable name for debugging/logging */\n  readonly name: string\n\n  /** Priority for result merging (higher = more prominent in results) */\n  readonly priority: number\n\n  /** Check if strategy is available and configured */\n  isAvailable(): Promise<boolean>\n\n  /** Initialize strategy resources (lazy, called on first use) */\n  ensureReady(): Promise<void>\n\n  /** Execute a search query */\n  search(query: string, options: SearchOptions): Promise<SearchResult[]>\n\n  /** Index a record */\n  index(record: IndexableRecord): Promise<void>\n\n  /** Delete a record from the index */\n  delete(entityId: EntityId, recordId: string, tenantId: string): Promise<void>\n\n  /** Bulk index multiple records (optional optimization) */\n  bulkIndex?(records: IndexableRecord[]): Promise<void>\n\n  /** Purge all records for an entity type (optional) */\n  purge?(entityId: EntityId, tenantId: string): Promise<void>\n}\n\n// =============================================================================\n// Service Configuration\n// =============================================================================\n\n/**\n * Configuration for result merging across strategies.\n */\nexport type ResultMergeConfig = {\n  /** How to handle duplicate results: 'highest_score' | 'first' | 'merge_scores' */\n  duplicateHandling: 'highest_score' | 'first' | 'merge_scores'\n  /** Weight multipliers per strategy (e.g., { meilisearch: 1.2, tokens: 0.8 }) */\n  strategyWeights?: Record<SearchStrategyId, number>\n  /** Minimum score threshold to include in results */\n  minScore?: number\n}\n\n/**\n * Callback function to enrich search results with presenter data.\n * Used to load presenter from database when not available from search strategy.\n */\nexport type PresenterEnricherFn = (\n  results: SearchResult[],\n  tenantId: string,\n  organizationId?: string | null,\n) => Promise<SearchResult[]>\n\n/**\n * Options for creating a SearchService instance.\n */\nexport type SearchServiceOptions = {\n  /** Array of strategy instances */\n  strategies?: SearchStrategy[]\n  /** Default strategies to use when not specified in search options */\n  defaultStrategies?: SearchStrategyId[]\n  /** Fallback strategy when others fail */\n  fallbackStrategy?: SearchStrategyId\n  /** Configuration for merging results from multiple strategies */\n  mergeConfig?: ResultMergeConfig\n  /** Callback to enrich results with presenter data from database */\n  presenterEnricher?: PresenterEnricherFn\n  /** TTL (ms) for the per-strategy availability cache. Defaults to 2_000. */\n  availabilityCacheTtlMs?: number\n}\n\n// =============================================================================\n// Module Configuration (for modules defining searchable entities)\n// =============================================================================\n\n/**\n * Context passed to buildSource, formatResult, resolveUrl, and resolveLinks.\n */\nexport type SearchBuildContext = {\n  /** The record being indexed */\n  record: Record<string, unknown>\n  /** Custom fields for the record */\n  customFields: Record<string, unknown>\n  /** Organization ID if applicable */\n  organizationId?: string | null\n  /** Tenant ID */\n  tenantId?: string | null\n  /** DI container for resolving dependencies */\n  container?: unknown\n  /** Query engine for loading related records (optional, used by buildSource for entity hydration) */\n  queryEngine?: unknown\n}\n\n/**\n * Source data for indexing a record.\n */\nexport type SearchIndexSource = {\n  /** Text content for keyword/fuzzy search (single string or array of chunks) */\n  text: string | string[]\n  /** Optional structured fields for filtering */\n  fields?: Record<string, unknown>\n  /** Presenter for quick display in search results */\n  presenter?: SearchResultPresenter\n  /** Deep links for the result */\n  links?: SearchResultLink[]\n  /** Source object used for checksum calculation (change detection) */\n  checksumSource?: unknown\n}\n\n/**\n * Policy defining how fields should be handled for search indexing.\n */\nexport type SearchFieldPolicy = {\n  /** Fields safe to send to external providers (fuzzy searchable) */\n  searchable?: string[]\n  /** Fields for hash-based search only (encrypted/sensitive) */\n  hashOnly?: string[]\n  /** Fields to exclude from all search */\n  excluded?: string[]\n}\n\n/**\n * Configuration for a single searchable entity within a module.\n */\nexport type SearchEntityConfig = {\n  /** Entity identifier, e.g., 'customers:customer_person_profile' */\n  entityId: EntityId\n  /** Enable/disable search for this entity (default: true) */\n  enabled?: boolean\n  /** Override strategies for this specific entity */\n  strategies?: SearchStrategyId[]\n  /** Priority for result ordering (higher = more prominent) */\n  priority?: number\n  /** Build searchable content from record */\n  buildSource?: (ctx: SearchBuildContext) => Promise<SearchIndexSource | null> | SearchIndexSource | null\n  /** Format result for display in Cmd+K */\n  formatResult?: (ctx: SearchBuildContext) => Promise<SearchResultPresenter | null> | SearchResultPresenter | null\n  /** Resolve primary URL when result is clicked */\n  resolveUrl?: (ctx: SearchBuildContext) => Promise<string | null> | string | null\n  /** Resolve additional action links */\n  resolveLinks?: (ctx: SearchBuildContext) => Promise<SearchResultLink[] | null> | SearchResultLink[] | null\n  /** Define which fields are searchable vs hash-only */\n  fieldPolicy?: SearchFieldPolicy\n}\n\n/**\n * Module-level search configuration (defined in search.ts files).\n */\nexport type SearchModuleConfig = {\n  /** Default strategies for all entities in this module */\n  defaultStrategies?: SearchStrategyId[]\n  /** Entity configurations */\n  entities: SearchEntityConfig[]\n}\n\n// =============================================================================\n// Event Payloads (for indexer events)\n// =============================================================================\n\n/**\n * Payload for search.index_record events.\n */\nexport type SearchIndexPayload = {\n  entityId: EntityId\n  recordId: string\n  tenantId: string\n  organizationId?: string | null\n  record: Record<string, unknown>\n  customFields?: Record<string, unknown>\n}\n\n/**\n * Payload for search.delete_record events.\n */\nexport type SearchDeletePayload = {\n  entityId: EntityId\n  recordId: string\n  tenantId: string\n}\n\n// =============================================================================\n// Global Registry for Search Module Configs\n// =============================================================================\n\nlet _searchModuleConfigs: SearchModuleConfig[] | null = null\n\n/**\n * Register search module configurations globally.\n * Called during app bootstrap with configs from search.generated.ts.\n */\nexport function registerSearchModuleConfigs(configs: SearchModuleConfig[]): void {\n  if (_searchModuleConfigs !== null && process.env.NODE_ENV === 'development') {\n    console.debug('[Bootstrap] Search module configs re-registered (this may occur during HMR)')\n  }\n  _searchModuleConfigs = configs\n}\n\n/**\n * Get registered search module configurations.\n * Returns empty array if not registered (search module may not be enabled).\n */\nexport function getSearchModuleConfigs(): SearchModuleConfig[] {\n  return _searchModuleConfigs ?? []\n}\n"],
-  "mappings": "AAkUA,IAAI,uBAAoD;AAMjD,SAAS,4BAA4B,SAAqC;AAC/E,MAAI,yBAAyB,QAAQ,QAAQ,IAAI,aAAa,eAAe;AAC3E,YAAQ,MAAM,6EAA6E;AAAA,EAC7F;AACA,yBAAuB;AACzB;AAMO,SAAS,yBAA+C;AAC7D,SAAO,wBAAwB,CAAC;AAClC;",
+  "sourcesContent": ["import type { EntityId } from './entities'\n\n// =============================================================================\n// Strategy Identifiers\n// =============================================================================\n\n/**\n * Built-in strategy identifiers plus extensible string for third-party strategies.\n */\nexport type SearchStrategyId = 'tokens' | 'vector' | 'fulltext' | (string & Record<string, never>)\n\n// =============================================================================\n// Result Types\n// =============================================================================\n\n/**\n * Presenter metadata for displaying search results in UI (Cmd+K, global search).\n */\nexport type SearchResultPresenter = {\n  title: string\n  subtitle?: string\n  icon?: string\n  badge?: string\n}\n\n/**\n * Deep link rendered next to a search result.\n */\nexport type SearchResultLink = {\n  href: string\n  label: string\n  kind?: 'primary' | 'secondary'\n}\n\n/**\n * A single search result returned by a strategy.\n */\nexport type SearchResult = {\n  /** Entity type identifier, e.g., 'customers:customer_person_profile' */\n  entityId: EntityId\n  /** Record primary key */\n  recordId: string\n  /** Relevance score (normalized 0-1 range preferred, but RRF scores may exceed 1) */\n  score: number\n  /** Which strategy produced this result */\n  source: SearchStrategyId\n  /** Optional presenter for quick display */\n  presenter?: SearchResultPresenter\n  /** Primary URL when result is clicked */\n  url?: string\n  /** Additional action links */\n  links?: SearchResultLink[]\n  /** Extra metadata from the strategy */\n  metadata?: Record<string, unknown>\n  /** Organization scope of the result, when known by the strategy. */\n  organizationId?: string | null\n}\n\n// =============================================================================\n// Search Options\n// =============================================================================\n\n/**\n * Options passed to SearchService.search()\n */\nexport type SearchOptions = {\n  /** Tenant isolation - required */\n  tenantId: string\n  /**\n   * Optional organization filter.\n   * - `string` restricts results to that organization only.\n   * - `undefined` or `null` means no organization filter (tenant-wide).\n   */\n  organizationId?: string | null\n  /**\n   * Optional organization allowlist.\n   * - Non-empty array restricts results to one of those organizations.\n   * - Empty array means no organizations are visible and should return no results.\n   * - `undefined` or `null` means no organization filter (tenant-wide).\n   *\n   * `organizationId` takes precedence when both are provided.\n   */\n  organizationIds?: string[] | null\n  /** Filter to specific entity types */\n  entityTypes?: EntityId[]\n  /** Use only specific strategies (defaults to all available) */\n  strategies?: SearchStrategyId[]\n  /** Maximum results per strategy before merging */\n  limit?: number\n  /** Offset for pagination */\n  offset?: number\n  /** How to combine results: 'or' merges all, 'and' requires match in all strategies */\n  combineMode?: 'or' | 'and'\n}\n\n// =============================================================================\n// Indexable Record\n// =============================================================================\n\n/**\n * A record prepared for indexing across all strategies.\n */\nexport type IndexableRecord = {\n  /** Entity type identifier */\n  entityId: EntityId\n  /** Record primary key */\n  recordId: string\n  /** Tenant for isolation */\n  tenantId: string\n  /** Optional organization for additional filtering */\n  organizationId?: string | null\n  /** All fields from the record (strategies will filter based on their needs) */\n  fields: Record<string, unknown>\n  /** Optional presenter for result display */\n  presenter?: SearchResultPresenter\n  /** Primary URL for the record */\n  url?: string\n  /** Additional action links */\n  links?: SearchResultLink[]\n  /** Text content for embedding (from buildSource, used by vector strategy) */\n  text?: string | string[]\n  /** Source object for checksum calculation (change detection) */\n  checksumSource?: unknown\n}\n\n// =============================================================================\n// Strategy Interface\n// =============================================================================\n\n/**\n * Interface that all search strategies must implement.\n * Following the cache module's strategy pattern.\n */\nexport interface SearchStrategy {\n  /** Unique strategy identifier */\n  readonly id: SearchStrategyId\n\n  /** Human-readable name for debugging/logging */\n  readonly name: string\n\n  /** Priority for result merging (higher = more prominent in results) */\n  readonly priority: number\n\n  /** Check if strategy is available and configured */\n  isAvailable(): Promise<boolean>\n\n  /** Initialize strategy resources (lazy, called on first use) */\n  ensureReady(): Promise<void>\n\n  /** Execute a search query */\n  search(query: string, options: SearchOptions): Promise<SearchResult[]>\n\n  /** Index a record */\n  index(record: IndexableRecord): Promise<void>\n\n  /** Delete a record from the index */\n  delete(entityId: EntityId, recordId: string, tenantId: string): Promise<void>\n\n  /** Bulk index multiple records (optional optimization) */\n  bulkIndex?(records: IndexableRecord[]): Promise<void>\n\n  /** Purge all records for an entity type (optional) */\n  purge?(entityId: EntityId, tenantId: string): Promise<void>\n}\n\n// =============================================================================\n// Service Configuration\n// =============================================================================\n\n/**\n * Configuration for result merging across strategies.\n */\nexport type ResultMergeConfig = {\n  /** How to handle duplicate results: 'highest_score' | 'first' | 'merge_scores' */\n  duplicateHandling: 'highest_score' | 'first' | 'merge_scores'\n  /** Weight multipliers per strategy (e.g., { meilisearch: 1.2, tokens: 0.8 }) */\n  strategyWeights?: Record<SearchStrategyId, number>\n  /** Minimum score threshold to include in results */\n  minScore?: number\n}\n\n/**\n * Callback function to enrich search results with presenter data.\n * Used to load presenter from database when not available from search strategy.\n */\nexport type PresenterEnricherFn = (\n  results: SearchResult[],\n  tenantId: string,\n  organizationId?: string | null,\n) => Promise<SearchResult[]>\n\n/**\n * Options for creating a SearchService instance.\n */\nexport type SearchServiceOptions = {\n  /** Array of strategy instances */\n  strategies?: SearchStrategy[]\n  /** Default strategies to use when not specified in search options */\n  defaultStrategies?: SearchStrategyId[]\n  /** Fallback strategy when others fail */\n  fallbackStrategy?: SearchStrategyId\n  /** Configuration for merging results from multiple strategies */\n  mergeConfig?: ResultMergeConfig\n  /** Callback to enrich results with presenter data from database */\n  presenterEnricher?: PresenterEnricherFn\n  /** TTL (ms) for the per-strategy availability cache. Defaults to 2_000. */\n  availabilityCacheTtlMs?: number\n}\n\n// =============================================================================\n// Module Configuration (for modules defining searchable entities)\n// =============================================================================\n\n/**\n * Context passed to buildSource, formatResult, resolveUrl, and resolveLinks.\n */\nexport type SearchBuildContext = {\n  /** The record being indexed */\n  record: Record<string, unknown>\n  /** Custom fields for the record */\n  customFields: Record<string, unknown>\n  /** Organization ID if applicable */\n  organizationId?: string | null\n  /** Tenant ID */\n  tenantId?: string | null\n  /** DI container for resolving dependencies */\n  container?: unknown\n  /** Query engine for loading related records (optional, used by buildSource for entity hydration) */\n  queryEngine?: unknown\n}\n\n/**\n * Source data for indexing a record.\n */\nexport type SearchIndexSource = {\n  /** Text content for keyword/fuzzy search (single string or array of chunks) */\n  text: string | string[]\n  /** Optional structured fields for filtering */\n  fields?: Record<string, unknown>\n  /** Presenter for quick display in search results */\n  presenter?: SearchResultPresenter\n  /** Deep links for the result */\n  links?: SearchResultLink[]\n  /** Source object used for checksum calculation (change detection) */\n  checksumSource?: unknown\n}\n\n/**\n * Policy defining how fields should be handled for search indexing.\n */\nexport type SearchFieldPolicy = {\n  /** Fields safe to send to external providers (fuzzy searchable) */\n  searchable?: string[]\n  /** Fields for hash-based search only (encrypted/sensitive) */\n  hashOnly?: string[]\n  /** Fields to exclude from all search */\n  excluded?: string[]\n}\n\n/**\n * Configuration for a single searchable entity within a module.\n */\nexport type SearchEntityConfig = {\n  /** Entity identifier, e.g., 'customers:customer_person_profile' */\n  entityId: EntityId\n  /** Enable/disable search for this entity (default: true) */\n  enabled?: boolean\n  /** Override strategies for this specific entity */\n  strategies?: SearchStrategyId[]\n  /** Priority for result ordering (higher = more prominent) */\n  priority?: number\n  /** Build searchable content from record */\n  buildSource?: (ctx: SearchBuildContext) => Promise<SearchIndexSource | null> | SearchIndexSource | null\n  /** Format result for display in Cmd+K */\n  formatResult?: (ctx: SearchBuildContext) => Promise<SearchResultPresenter | null> | SearchResultPresenter | null\n  /** Resolve primary URL when result is clicked */\n  resolveUrl?: (ctx: SearchBuildContext) => Promise<string | null> | string | null\n  /** Resolve additional action links */\n  resolveLinks?: (ctx: SearchBuildContext) => Promise<SearchResultLink[] | null> | SearchResultLink[] | null\n  /** Define which fields are searchable vs hash-only */\n  fieldPolicy?: SearchFieldPolicy\n  /**\n   * Per-entity view feature(s) required to read this entity's records through\n   * data-returning surfaces (e.g. the `search_get` / `search_aggregate` AI tools).\n   * These tools must NOT rely on the search-administration `search.view` feature\n   * to gate record reads \u2014 callers must additionally hold the owning module's\n   * `<entity>.view` feature(s) declared here. When omitted, those tools fail\n   * closed (deny) so an entity is never exposed without an explicit grant.\n   */\n  aclFeatures?: string[]\n}\n\n/**\n * Module-level search configuration (defined in search.ts files).\n */\nexport type SearchModuleConfig = {\n  /** Default strategies for all entities in this module */\n  defaultStrategies?: SearchStrategyId[]\n  /** Entity configurations */\n  entities: SearchEntityConfig[]\n}\n\n// =============================================================================\n// Event Payloads (for indexer events)\n// =============================================================================\n\n/**\n * Payload for search.index_record events.\n */\nexport type SearchIndexPayload = {\n  entityId: EntityId\n  recordId: string\n  tenantId: string\n  organizationId?: string | null\n  record: Record<string, unknown>\n  customFields?: Record<string, unknown>\n}\n\n/**\n * Payload for search.delete_record events.\n */\nexport type SearchDeletePayload = {\n  entityId: EntityId\n  recordId: string\n  tenantId: string\n}\n\n// =============================================================================\n// Global Registry for Search Module Configs\n// =============================================================================\n\nlet _searchModuleConfigs: SearchModuleConfig[] | null = null\n\n/**\n * Register search module configurations globally.\n * Called during app bootstrap with configs from search.generated.ts.\n */\nexport function registerSearchModuleConfigs(configs: SearchModuleConfig[]): void {\n  if (_searchModuleConfigs !== null && process.env.NODE_ENV === 'development') {\n    console.debug('[Bootstrap] Search module configs re-registered (this may occur during HMR)')\n  }\n  _searchModuleConfigs = configs\n}\n\n/**\n * Get registered search module configurations.\n * Returns empty array if not registered (search module may not be enabled).\n */\nexport function getSearchModuleConfigs(): SearchModuleConfig[] {\n  return _searchModuleConfigs ?? []\n}\n"],
+  "mappings": "AA2UA,IAAI,uBAAoD;AAMjD,SAAS,4BAA4B,SAAqC;AAC/E,MAAI,yBAAyB,QAAQ,QAAQ,IAAI,aAAa,eAAe;AAC3E,YAAQ,MAAM,6EAA6E;AAAA,EAC7F;AACA,yBAAuB;AACzB;AAMO,SAAS,yBAA+C;AAC7D,SAAO,wBAAwB,CAAC;AAClC;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.4-develop.4382.1.6b4f656b77",
+  "version": "0.6.4",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -89,16 +89,16 @@
     }
   },
   "dependencies": {
-    "@mikro-orm/core": "^7.1.3",
-    "@mikro-orm/decorators": "^7.1.3",
-    "@mikro-orm/postgresql": "^7.1.3",
-    "@open-mercato/cache": "0.6.4-develop.4382.1.6b4f656b77",
+    "@mikro-orm/core": "^7.1.4",
+    "@mikro-orm/decorators": "^7.1.4",
+    "@mikro-orm/postgresql": "^7.1.4",
+    "@open-mercato/cache": "0.6.4",
     "dotenv": "^17.4.2",
-    "rate-limiter-flexible": "^11.1.0",
+    "rate-limiter-flexible": "^11.1.1",
     "re2js": "2.8.3",
     "reflect-metadata": "^0.2.2",
     "sanitize-html": "^2.17.4",
-    "undici": "^8.3.0"
+    "undici": "^8.4.1"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -113,6 +113,5 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/shared"
-  },
-  "stableVersion": "0.6.3"
+  }
 }

package/src/lib/auth/__tests__/apiKeyAuthCache.test.ts

@@ -114,4 +114,39 @@ describe('createApiKeyAuthCache', () => {
     cache.setMiss('')
     expect(cache.get('')).toBeUndefined()
   })
+
+  it('never retains the plaintext secret as a cache key (success and miss paths)', () => {
+    const clock = fakeClock()
+    const cache = createApiKeyAuthCache({ successTtlMs: 60_000, negativeTtlMs: 5_000, now: clock.now })
+    const liveSecret = 'sk_live_0123456789abcdef'
+    const badGuess = 'sk_live_brute_force_guess'
+
+    cache.setSuccess(liveSecret, sampleAuth, null)
+    cache.setMiss(badGuess)
+
+    expect(cache.get(liveSecret)).toEqual(sampleAuth)
+    expect(cache.get(badGuess)).toBeNull()
+
+    const storedKeys = cache.inspectEntryKeysForTests()
+    expect(storedKeys.length).toBe(2)
+    for (const key of storedKeys) {
+      expect(key).not.toContain(liveSecret)
+      expect(key).not.toContain(badGuess)
+      expect(key).toMatch(/^[0-9a-f]{32}$/)
+    }
+  })
+
+  it('uses an independent per-cache key so the same secret fingerprints differently across caches', () => {
+    const clock = fakeClock()
+    const secret = 'sk_live_shared_secret'
+    const cacheA = createApiKeyAuthCache({ successTtlMs: 60_000, now: clock.now })
+    const cacheB = createApiKeyAuthCache({ successTtlMs: 60_000, now: clock.now })
+
+    cacheA.setSuccess(secret, sampleAuth, null)
+    cacheB.setSuccess(secret, sampleAuth, null)
+
+    expect(cacheA.get(secret)).toEqual(sampleAuth)
+    expect(cacheB.get(secret)).toEqual(sampleAuth)
+    expect(cacheA.inspectEntryKeysForTests()[0]).not.toBe(cacheB.inspectEntryKeysForTests()[0])
+  })
 })

package/src/lib/auth/apiKeyAuthCache.ts

@@ -1,7 +1,15 @@
+import { createHmac, randomBytes } from 'node:crypto'
+
 const DEFAULT_SUCCESS_TTL_MS = 30_000
 const DEFAULT_NEGATIVE_TTL_MS = 5_000
 const DEFAULT_LAST_USED_WRITE_INTERVAL_MS = 60_000
 const DEFAULT_MAX_ENTRIES = 1_000
+const FINGERPRINT_BYTES = 16
+
+function createSecretFingerprinter(): (secret: string) => string {
+  const key = randomBytes(32)
+  return (secret) => createHmac('sha256', key).update(secret, 'utf8').digest('hex').slice(0, FINGERPRINT_BYTES * 2)
+}
 
 export type CachedApiKeyAuth = Record<string, unknown> | null
 
@@ -27,6 +35,7 @@ export type ApiKeyAuthCache = {
   shouldWriteLastUsed(keyId: string): boolean
   clear(): void
   size(): number
+  inspectEntryKeysForTests(): string[]
 }
 
 function resolveTtlEnv(name: string, fallback: number): number {
@@ -46,6 +55,7 @@ export function createApiKeyAuthCache(options: ApiKeyAuthCacheOptions = {}): Api
   )
   const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES
   const now = options.now ?? (() => Date.now())
+  const fingerprint = createSecretFingerprinter()
 
   const entries = new Map<string, CachedEntry>()
   const lastUsedWrites = new Map<string, number>()
@@ -68,12 +78,13 @@ export function createApiKeyAuthCache(options: ApiKeyAuthCacheOptions = {}): Api
   return {
     get(secret) {
       if (!secret) return undefined
-      const entry = entries.get(secret)
+      const key = fingerprint(secret)
+      const entry = entries.get(key)
       if (!entry) return undefined
       const currentMs = now()
-      if (purgeStale(secret, entry, currentMs)) return undefined
-      entries.delete(secret)
-      entries.set(secret, entry)
+      if (purgeStale(key, entry, currentMs)) return undefined
+      entries.delete(key)
+      entries.set(key, entry)
       return entry.auth
     },
     setSuccess(secret, auth, expiresAtMs) {
@@ -83,13 +94,13 @@ export function createApiKeyAuthCache(options: ApiKeyAuthCacheOptions = {}): Api
       const ttlEnd = currentMs + successTtlMs
       const effectiveExpiry = expiresAtMs != null ? Math.min(ttlEnd, expiresAtMs) : ttlEnd
       if (effectiveExpiry <= currentMs) return
-      touch(secret, { auth, cachedAtMs: currentMs, expiresAtMs: effectiveExpiry })
+      touch(fingerprint(secret), { auth, cachedAtMs: currentMs, expiresAtMs: effectiveExpiry })
     },
     setMiss(secret) {
       if (!secret) return
       if (negativeTtlMs <= 0) return
       const currentMs = now()
-      touch(secret, { auth: null, cachedAtMs: currentMs, expiresAtMs: currentMs + negativeTtlMs })
+      touch(fingerprint(secret), { auth: null, cachedAtMs: currentMs, expiresAtMs: currentMs + negativeTtlMs })
     },
     invalidateByKeyId(keyId) {
       if (!keyId) return
@@ -117,6 +128,9 @@ export function createApiKeyAuthCache(options: ApiKeyAuthCacheOptions = {}): Api
     size() {
       return entries.size
     },
+    inspectEntryKeysForTests() {
+      return Array.from(entries.keys())
+    },
   }
 }
 

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

@@ -61,6 +61,8 @@ describe('CommandBus cache invalidation for sales documents', () => {
       actionLogService: asValue({
         log: logMock,
         findByUndoToken: jest.fn(async () => logRecord),
+        claimForUndo: jest.fn(async () => true),
+        releaseUndoClaim: jest.fn(async () => true),
         markUndone: jest.fn(async () => {}),
       }),
       dataEngine: asValue({ flushOrmEntityChanges: jest.fn() }),

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

@@ -42,6 +42,8 @@ describe('CommandBus undo audit trace', () => {
             lastName: { from: 'Before', to: 'After' },
           },
         })),
+        claimForUndo: jest.fn(async () => true),
+        releaseUndoClaim: jest.fn(async () => true),
         markUndone: markUndoneMock,
       }),
       dataEngine: asValue({ flushOrmEntityChanges: jest.fn(async () => undefined) }),

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

@@ -0,0 +1,122 @@
+import { asValue, createContainer, InjectionMode } from 'awilix'
+import { CommandBus, registerCommand, unregisterCommand } from '@open-mercato/shared/lib/commands'
+
+type ActionLogServiceMock = {
+  findByUndoToken: jest.Mock
+  claimForUndo: jest.Mock
+  releaseUndoClaim: jest.Mock
+  markUndone: jest.Mock
+}
+
+function buildContainer(service: ActionLogServiceMock) {
+  const container = createContainer({ injectionMode: InjectionMode.CLASSIC })
+  container.register({
+    actionLogService: asValue(service),
+    dataEngine: asValue({ flushOrmEntityChanges: jest.fn(async () => undefined) }),
+  })
+  return container
+}
+
+function buildLogStub() {
+  return {
+    id: 'log-1',
+    commandId: 'customers.people.update',
+    actionLabel: 'Update person',
+    actorUserId: 'user-1',
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    resourceKind: 'customers.person',
+    resourceId: 'person-1',
+    parentResourceKind: null,
+    parentResourceId: null,
+    relatedResourceKind: null,
+    relatedResourceId: null,
+    commandPayload: { id: 'person-1' },
+    snapshotBefore: { id: 'person-1', lastName: 'Before' },
+    snapshotAfter: { id: 'person-1', lastName: 'After' },
+    changesJson: null,
+  }
+}
+
+const ctx = {
+  container: null as unknown,
+  auth: { sub: 'user-2', tenantId: 'tenant-1', orgId: 'org-1' },
+  organizationScope: null,
+  selectedOrganizationId: 'org-1',
+  organizationIds: null,
+}
+
+describe('CommandBus.undo TOCTOU race guard', () => {
+  afterEach(() => {
+    unregisterCommand('customers.people.update')
+  })
+
+  it('claims the row atomically before invoking the undo handler', async () => {
+    const callOrder: string[] = []
+    const undoMock = jest.fn(async () => {
+      callOrder.push('undo')
+    })
+    registerCommand({ id: 'customers.people.update', execute: jest.fn(), undo: undoMock })
+
+    const service: ActionLogServiceMock = {
+      findByUndoToken: jest.fn(async () => buildLogStub()),
+      claimForUndo: jest.fn(async () => {
+        callOrder.push('claim')
+        return true
+      }),
+      releaseUndoClaim: jest.fn(async () => true),
+      markUndone: jest.fn(async () => null),
+    }
+
+    const bus = new CommandBus()
+    await bus.undo('undo-token', { ...ctx, container: buildContainer(service) } as never)
+
+    expect(service.claimForUndo).toHaveBeenCalledWith('log-1')
+    expect(undoMock).toHaveBeenCalledTimes(1)
+    expect(callOrder).toEqual(['claim', 'undo'])
+    expect(service.markUndone).toHaveBeenCalledTimes(1)
+    expect(service.releaseUndoClaim).not.toHaveBeenCalled()
+  })
+
+  it('does not run the undo handler when the claim is lost to a concurrent request', async () => {
+    const undoMock = jest.fn(async () => {})
+    registerCommand({ id: 'customers.people.update', execute: jest.fn(), undo: undoMock })
+
+    const service: ActionLogServiceMock = {
+      findByUndoToken: jest.fn(async () => buildLogStub()),
+      claimForUndo: jest.fn(async () => false),
+      releaseUndoClaim: jest.fn(async () => true),
+      markUndone: jest.fn(async () => null),
+    }
+
+    const bus = new CommandBus()
+    await expect(
+      bus.undo('undo-token', { ...ctx, container: buildContainer(service) } as never),
+    ).rejects.toThrow('Undo token already consumed')
+
+    expect(undoMock).not.toHaveBeenCalled()
+    expect(service.markUndone).not.toHaveBeenCalled()
+  })
+
+  it('releases the claim when the undo handler fails so the action stays retryable', async () => {
+    const undoMock = jest.fn(async () => {
+      throw new Error('handler boom')
+    })
+    registerCommand({ id: 'customers.people.update', execute: jest.fn(), undo: undoMock })
+
+    const service: ActionLogServiceMock = {
+      findByUndoToken: jest.fn(async () => buildLogStub()),
+      claimForUndo: jest.fn(async () => true),
+      releaseUndoClaim: jest.fn(async () => true),
+      markUndone: jest.fn(async () => null),
+    }
+
+    const bus = new CommandBus()
+    await expect(
+      bus.undo('undo-token', { ...ctx, container: buildContainer(service) } as never),
+    ).rejects.toThrow('handler boom')
+
+    expect(service.markUndone).not.toHaveBeenCalled()
+    expect(service.releaseUndoClaim).toHaveBeenCalledWith('log-1')
+  })
+})

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

@@ -19,9 +19,12 @@ function createFakeEm(overrides?: { inTransaction?: boolean }): FakeEntityManage
 }
 
 describe('withAtomicFlush', () => {
-  it('runs phases in order and flushes once at the end', async () => {
+  it('runs phases in order and flushes after each phase (SPEC-018 boundaries)', async () => {
     const em = createFakeEm()
     const calls: string[] = []
+    em.flush.mockImplementation(async () => {
+      calls.push('flush')
+    })
 
     await withAtomicFlush(em as any, [
       async () => {
@@ -37,14 +40,23 @@ describe('withAtomicFlush', () => {
       },
     ])
 
-    expect(calls).toEqual(['phase1-start', 'phase1-end', 'phase2', 'phase3'])
-    expect(em.flush).toHaveBeenCalledTimes(1)
+    // Each phase is flushed before the next begins — the interleaved-read guard.
+    expect(calls).toEqual([
+      'phase1-start',
+      'phase1-end',
+      'flush',
+      'phase2',
+      'flush',
+      'phase3',
+      'flush',
+    ])
+    expect(em.flush).toHaveBeenCalledTimes(3)
     expect(em.begin).not.toHaveBeenCalled()
     expect(em.commit).not.toHaveBeenCalled()
     expect(em.rollback).not.toHaveBeenCalled()
   })
 
-  it('lets a later phase observe state a prior phase mutated', async () => {
+  it('flushes a phase before a later phase observes its mutation', async () => {
     const em = createFakeEm()
     const state: { value: number } = { value: 0 }
     let observed: number | null = null
@@ -59,7 +71,8 @@ describe('withAtomicFlush', () => {
     ])
 
     expect(observed).toBe(42)
-    expect(em.flush).toHaveBeenCalledTimes(1)
+    // Two phases → flushed at each boundary.
+    expect(em.flush).toHaveBeenCalledTimes(2)
   })
 
   it('wraps phases in begin/commit when transaction option is true', async () => {
@@ -93,25 +106,31 @@ describe('withAtomicFlush', () => {
     expect(em.rollback).toHaveBeenCalledTimes(1)
   })
 
-  it('propagates a thrown error and does NOT flush when a phase throws (non-transactional)', async () => {
+  it('propagates a thrown error and stops at the failing phase (non-transactional, per-phase flush)', async () => {
     const em = createFakeEm()
     const failure = new Error('phase-failure')
+    let thirdPhaseRan = false
 
     await expect(
       withAtomicFlush(em as any, [
         () => {
-          // ok
+          // ok — its changeset is flushed at the phase boundary before phase 2 runs
         },
         () => {
           throw failure
         },
         () => {
-          throw new Error('should-not-run')
+          thirdPhaseRan = true
         },
       ]),
     ).rejects.toBe(failure)
 
-    expect(em.flush).not.toHaveBeenCalled()
+    // Non-transactional: the first phase flushed independently before phase 2
+    // threw; the failing phase's own flush and every later phase are skipped.
+    // (This independent-commit risk is exactly why mutating commands pass
+    // `{ transaction: true }`, where the whole sequence rolls back instead.)
+    expect(em.flush).toHaveBeenCalledTimes(1)
+    expect(thirdPhaseRan).toBe(false)
   })
 
   it('is a true no-op when phases is empty — no flush, no transaction', async () => {
@@ -220,6 +239,88 @@ describe('withAtomicFlush', () => {
     expect(em.begin).toHaveBeenCalledWith(undefined)
   })
 
+  describe('commit-boundary pending-changes guard', () => {
+    type UowEm = FakeEntityManager & {
+      getUnitOfWork: jest.Mock<{ computeChangeSets: jest.Mock; getChangeSets: jest.Mock }, []>
+    }
+
+    function createUowEm(pendingChangeSets: unknown[], opts?: { inTransaction?: boolean }): UowEm {
+      const computeChangeSets = jest.fn()
+      const getChangeSets = jest.fn().mockReturnValue(pendingChangeSets)
+      return {
+        ...createFakeEm(opts),
+        getUnitOfWork: jest.fn().mockReturnValue({ computeChangeSets, getChangeSets }),
+      }
+    }
+
+    it('flushes once more when a change set lingers past the last phase flush', async () => {
+      // One managed entity is still dirty at the commit boundary (a phase mutated
+      // after its own flush). The guard must persist it instead of letting the
+      // transaction commit the work-in-progress silently.
+      const em = createUowEm([{ entity: 'lingering' }], { inTransaction: false })
+      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      try {
+        await withAtomicFlush(em as any, [() => {}], { transaction: true, label: 'demo.command' })
+      } finally {
+        warn.mockRestore()
+      }
+
+      // 1 per-phase flush + 1 defensive guard flush, all inside the same transaction.
+      expect(em.flush).toHaveBeenCalledTimes(2)
+      expect(em.commit).toHaveBeenCalledTimes(1)
+      expect(em.rollback).not.toHaveBeenCalled()
+    })
+
+    it('warns (dev) and names the label when the guard has to act', async () => {
+      const em = createUowEm([{ a: 1 }, { b: 2 }])
+      const previousEnv = process.env.NODE_ENV
+      process.env.NODE_ENV = 'development'
+      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      let warnCallCount = 0
+      let warnMessage = ''
+      try {
+        await withAtomicFlush(em as any, [() => {}], { label: 'sales.update_shipment' })
+        // Capture BEFORE mockRestore — restore() resets mock.calls.
+        warnCallCount = warn.mock.calls.length
+        warnMessage = String(warn.mock.calls[0]?.[0] ?? '')
+      } finally {
+        warn.mockRestore()
+        process.env.NODE_ENV = previousEnv
+      }
+
+      expect(warnCallCount).toBe(1)
+      expect(warnMessage).toContain('sales.update_shipment')
+      expect(warnMessage).toContain('2 pending change-set(s)')
+    })
+
+    it('does NOT flush again when the UnitOfWork is clean at the boundary', async () => {
+      const em = createUowEm([])
+      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      try {
+        await withAtomicFlush(em as any, [() => {}, () => {}])
+      } finally {
+        warn.mockRestore()
+      }
+
+      // 2 phases → 2 per-phase flushes; the clean guard adds nothing.
+      expect(em.flush).toHaveBeenCalledTimes(2)
+      expect(warn).not.toHaveBeenCalled()
+    })
+
+    it('never throws when the UnitOfWork probe itself fails', async () => {
+      const em: any = {
+        ...createFakeEm(),
+        getUnitOfWork: jest.fn(() => {
+          throw new Error('uow unavailable')
+        }),
+      }
+
+      await expect(withAtomicFlush(em, [() => {}])).resolves.toBeUndefined()
+      // Probe failure → unknown → no defensive flush beyond the per-phase one.
+      expect(em.flush).toHaveBeenCalledTimes(1)
+    })
+  })
+
   it('opens its own transaction when the EM does not implement isInTransaction (partial/mock EM)', async () => {
     // Many command unit tests mock an EntityManager with begin/commit/rollback/flush
     // but no isInTransaction. The re-entrancy probe must not throw on such EMs — it