@open-mercato/cache 0.6.8-develop.6931.1.4a1e1c786b → 0.6.8-develop.6940.1.177ea30c6e

package/AGENTS.md

@@ -21,7 +21,7 @@ The memory strategy is bounded so a process-shared instance (`OM_BOOTSTRAP_CACHE
 
 ## Always
 
-1. **MUST resolve via DI** — always use `container.resolve('cacheService')`, never instantiate cache directly
+1. **MUST resolve via DI** — always use `container.resolve('cache')`, never instantiate cache directly. The DI token is `cache` (registered in `packages/core/src/bootstrap.ts`); there is no `cacheService` registration.
 2. **MUST scope to tenant** — include `tenantId` in cache keys or use `runWithCacheTenant()` for automatic scoping
 3. **MUST use tag-based invalidation** for CRUD side effects — tag entries so related data can be invalidated together
 
@@ -48,13 +48,18 @@ yarn workspace @open-mercato/cache build
 Use tags when cached data relates to a specific entity or scope. Invalidating a tag clears all entries with that tag.
 
 ```typescript
+const cache = container.resolve('cache')
+
 // When caching, attach tags
-await cacheService.set('key', value, { tags: ['tenant:123', 'customers'] })
+await cache.set('key', value, { tags: ['tenant:123', 'customers'] })
 
-// When data changes, invalidate by tag
-await cacheService.invalidateTag('customers')  // Clears all customer-related cache
+// When data changes, invalidate by tag — `deleteByTags` takes an ARRAY of tags
+// (any entry carrying ANY of them is dropped) and returns the number of deleted keys.
+await cache.deleteByTags(['customers'])  // Clears all customer-related cache
 ```
 
+`CacheStrategy` is the only cache surface: `get`, `set`, `has`, `delete`, `deleteByTags`, `clear`, `keys`, `stats`, plus optional `healthcheck`, `cleanup`, `close`. There is no `invalidateTag` — MUST NOT invent per-tag helpers in module code.
+
 ## Consistency vs commit timing
 
 Cache invalidation and query-index side effects (`emitCrudSideEffects`) MUST fire **after** the originating domain write commits — the same rule that keeps them OUTSIDE the `withAtomicFlush` block (see `packages/core/AGENTS.md` → "Entity Update Safety — `withAtomicFlush`"). Because invalidation runs post-commit and the query-index read-projection tail (search tokens, vectors, fulltext, coverage) converges asynchronously, reads can briefly see a short convergence window after a write.
@@ -63,7 +68,7 @@ The opt-in env flag `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` (default **OFF**, 100% b
 
 ## Adding Caching to a Module
 
-1. Resolve `cacheService` from DI in your service or route handler
+1. Resolve the `cache` service from DI (`container.resolve('cache')`) in your service or route handler
 2. Define cache keys with tenant scoping: `${tenantId}:${module}:${identifier}`
 3. Tag entries with entity type and tenant for targeted invalidation
 4. Add cache invalidation to CRUD side effects (`emitCrudSideEffects` with `cacheAliases`)
@@ -82,3 +87,4 @@ packages/cache/src/
 - Follow the strategy pattern — add new strategies in `strategies/` with the same interface
 - Run `yarn test` in `packages/cache` after changes
 - Verify tag invalidation works across all strategies when modifying invalidation logic
+- The DI token and method names quoted in this file and in `.ai/review-checklist.md` are pinned to the real sources by `src/__tests__/cache-di-contract-docs.test.ts` (it re-derives the token from `packages/core/src/bootstrap.ts` and the members from `CacheStrategy`). Renaming the token or a method MUST update both docs in the same change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cache",
-  "version": "0.6.8-develop.6931.1.4a1e1c786b",
+  "version": "0.6.8-develop.6940.1.177ea30c6e",
   "license": "MIT",
   "description": "Multi-strategy cache service with tag-based invalidation support",
   "type": "module",

package/src/__tests__/cache-di-contract-docs.test.ts

@@ -0,0 +1,160 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Cache DI-contract documentation audit.
+ *
+ * `packages/cache/AGENTS.md` and `.ai/review-checklist.md` are the two places an agent
+ * looks up how to reach the cache. Both had drifted away from the runtime: they told
+ * readers to resolve a `cacheService` DI token (nothing registers that name — the real
+ * token is `cache`, registered in `packages/core/src/bootstrap.ts`) and to invalidate a
+ * tag with `invalidateTag('customers')` (no such member exists — `CacheStrategy` exposes
+ * `deleteByTags(tags: string[])`). Both snippets throw at runtime, so the docs were
+ * actively producing broken module code.
+ *
+ * This audit re-derives the ground truth from the sources on every run — the registered
+ * token from the bootstrap registration, the callable members from the `CacheStrategy`
+ * type — and fails when either document quotes a token or a method that no longer exists.
+ * Renaming the token or a strategy method therefore breaks this test until the docs are
+ * updated in the same change.
+ */
+
+const repoRoot = join(__dirname, '..', '..', '..', '..')
+const bootstrapPath = join(repoRoot, 'packages', 'core', 'src', 'bootstrap.ts')
+const cacheTypesPath = join(repoRoot, 'packages', 'cache', 'src', 'types.ts')
+const cacheAgentsPath = join(repoRoot, 'packages', 'cache', 'AGENTS.md')
+const reviewChecklistPath = join(repoRoot, '.ai', 'review-checklist.md')
+
+function readSource(path: string): string {
+  return readFileSync(path, 'utf8')
+}
+
+/** The DI token `bootstrap()` registers the cache service under. */
+function registeredCacheToken(): string {
+  const source = readSource(bootstrapPath)
+  const match = source.match(/container\.register\(\{\s*([A-Za-z_$][\w$]*)\s*:\s*asValue\(cache\)\s*\}\)/)
+  if (!match) {
+    throw new Error(
+      '[internal] Could not locate the cache registration in packages/core/src/bootstrap.ts. ' +
+        'Update this audit if the registration shape changed.',
+    )
+  }
+  return match[1]
+}
+
+/** The body of the `CacheStrategy` type declaration. */
+function cacheStrategyBody(): string {
+  const source = readSource(cacheTypesPath)
+  const start = source.indexOf('export type CacheStrategy = {')
+  if (start === -1) throw new Error('[internal] CacheStrategy type not found in packages/cache/src/types.ts')
+  const rest = source.slice(start)
+  const endOffset = rest.search(/^\}/m)
+  if (endOffset === -1) throw new Error('[internal] CacheStrategy type body is not terminated')
+  return rest.slice(0, endOffset)
+}
+
+/** Every callable member of the `CacheStrategy` contract, optional ones included. */
+function cacheStrategyMembers(body: string): Set<string> {
+  const members = new Set<string>()
+  const memberPattern = /^ {2}([A-Za-z_$][\w$]*)\??\(/gm
+  let match = memberPattern.exec(body)
+  while (match) {
+    members.add(match[1])
+    match = memberPattern.exec(body)
+  }
+  return members
+}
+
+/** The member that performs tag-based invalidation — the one taking a `string[]` of tags. */
+function tagInvalidationMember(body: string): string {
+  const match = body.match(/^ {2}([A-Za-z_$][\w$]*)\??\(tags: string\[\]\)/m)
+  if (!match) throw new Error('[internal] CacheStrategy no longer declares a tags: string[] member')
+  return match[1]
+}
+
+/** Every `container.resolve('x')` / `resolve('x')` token quoted by a document. */
+function documentedResolveTokens(markdown: string): string[] {
+  const tokens: string[] = []
+  const pattern = /\bresolve\(\s*['"`]([^'"`]+)['"`]\s*\)/g
+  let match = pattern.exec(markdown)
+  while (match) {
+    tokens.push(match[1])
+    match = pattern.exec(markdown)
+  }
+  return tokens
+}
+
+/** Every method invoked on a cache-shaped identifier inside a document. */
+function documentedCacheMethodCalls(markdown: string): string[] {
+  const calls: string[] = []
+  const pattern = /\b([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)\(/g
+  let match = pattern.exec(markdown)
+  while (match) {
+    if (/cache/i.test(match[1])) calls.push(match[2])
+    match = pattern.exec(markdown)
+  }
+  return calls
+}
+
+/**
+ * The review checklist documents every subsystem, so only its Cache section is in scope —
+ * other sections legitimately quote other DI tokens.
+ */
+function cacheSectionOf(markdown: string): string {
+  const heading = markdown.match(/^## \d+\. Cache$/m)
+  if (!heading || heading.index === undefined) {
+    throw new Error('[internal] .ai/review-checklist.md no longer has a "## <n>. Cache" section')
+  }
+  const rest = markdown.slice(heading.index + heading[0].length)
+  const nextHeading = rest.search(/^## /m)
+  return nextHeading === -1 ? rest : rest.slice(0, nextHeading)
+}
+
+type AuditedDocument = { file: string; text: string }
+
+function auditedDocuments(): AuditedDocument[] {
+  return [
+    { file: 'packages/cache/AGENTS.md', text: readSource(cacheAgentsPath) },
+    { file: '.ai/review-checklist.md', text: cacheSectionOf(readSource(reviewChecklistPath)) },
+  ]
+}
+
+describe('cache DI contract documentation', () => {
+  const token = registeredCacheToken()
+  const strategyBody = cacheStrategyBody()
+  const members = cacheStrategyMembers(strategyBody)
+  const tagMember = tagInvalidationMember(strategyBody)
+  const documents = auditedDocuments()
+
+  it('derives the ground truth it audits against', () => {
+    expect(token).toBe('cache')
+    const required = ['get', 'set', 'has', 'delete', 'deleteByTags', 'clear', 'keys', 'stats']
+    expect(required.filter((member) => !members.has(member))).toEqual([])
+    expect(members.has('invalidateTag')).toBe(false)
+    expect(tagMember).toBe('deleteByTags')
+  })
+
+  it('every audited document resolves only the registered DI token', () => {
+    for (const { file, text } of documents) {
+      const quoted = documentedResolveTokens(text)
+      expect({ file, quotedCount: quoted.length > 0 }).toEqual({ file, quotedCount: true })
+      for (const quotedToken of quoted) {
+        expect({ file, quotedToken }).toEqual({ file, quotedToken: token })
+      }
+    }
+  })
+
+  it('every audited document only calls methods that exist on CacheStrategy', () => {
+    for (const { file, text } of documents) {
+      for (const method of documentedCacheMethodCalls(text)) {
+        expect({ file, method, exists: members.has(method) }).toEqual({ file, method, exists: true })
+      }
+    }
+  })
+
+  it('every audited document names tag invalidation by its real member', () => {
+    for (const { file, text } of documents) {
+      expect({ file, documented: text.includes(`${tagMember}(`) }).toEqual({ file, documented: true })
+    }
+  })
+})