memorio 5.1.4 → 5.2.0

package/SUMMARY.md

@@ -1,59 +1,55 @@
-# Riepilogo dei file - memorio examples & markdown
-
-## 📁 examples/ (20 file)
-
-| File | Cosa mostra |
-|---|---|
-| `basic.ts` | Tour introduttivo: platform detection, `state`, `store`, `session` in un unico script. |
-| `cache.ts` | Uso base della cache in-memory: set/get, oggetti complessi, cleanup. |
-| `cross-platform-guards.ts` | Come usare `getCapabilities()` invece di `isBrowser()`/`isNode()` per gestire in modo esplicito gli ambienti dove `store`/`session`/`idb` non sono durevoli. |
-| `history.ts` *(nuovo)* | State Intelligence: `snapshot()`/`diff()`/`rollback()` per il pattern "prova → ispeziona → conferma o annulla", undo/redo passo-passo, trace log con export/replay. |
-| `idb.ts` | CRUD completo su IndexedDB: database, tabelle, record, info (size/version/exist). |
-| `multi-tenant-context.ts` | Isolamento dati per richiesta/tenant con `memorio.createContext()` in un handler server-side, incluso cleanup. |
-| `node-server.ts` | Memorio lato server: cache in-memory, fallback di `store`/`session`, contesti multi-tenant, più snippet commentati (Express, WebSocket, job queue, CLI). |
-| `observer.ts` | Pattern observer: singolo valore, oggetti interi, più observer sullo stesso path, cleanup. |
-| `platform.ts` | Platform detection dettagliata + isolamento contesti per server multi-tenant, con verifica esplicita dell'isolamento tra due utenti. |
-| `react-app.tsx` | App React completa (header, profilo, cart, notifiche, settings, login/logout) costruita solo su `state`/`store`/`useObserver`. |
-| `react-observer.tsx` | `useObserver` in due modalità (auto-discovery vs deps espliciti) combinato con `typed<T>()` e `registerSchema()`. |
-| `semantic-memory.ts` | Memoria applicativa per un'app LLM-backed: remember/update con confidence e source, retrieval con `memory.context()` - con nota esplicita che non è ricerca semantica per embedding. |
-| `session-advanced.ts` | Uso avanzato di `session`: auth token, bozza di form, carrello, dimensione dello storage. |
-| `sqlite-batched-writes.ts` | Con il journal+checkpoint, i write sono incrementali ma i checkpoint (snapshot completo) sono costosi: batch di insert seguito da un solo flush. |
-| `state-advanced.ts` | Stato annidato, array, locking di un valore (`.lock()`), path tracking, rimozione stato. |
-| `store-advanced.ts` | `store` avanzato: persistenza, quota, alias dei metodi, gestione errori, serializzazione di vari tipi. |
-| `sync.ts` *(nuovo)* | Local-first sync: configurazione di un `SyncProvider` (push/pull/resolve), scope `device`/`user`/`shared`, ispezione e replay del journal. |
-| `typed-and-schema.ts` | Tutti gli snippet di `TYPED.md` e `SCHEMA.md` in un unico file TypeScript funzionante: typed state + validazione runtime combinati. |
-| `useObserver.tsx` | Guida step-by-step all'hook `useObserver`: dipendenza singola, multiple, auto-discovery, sync con `useState`, mini to-do app. |
-| `browser-vanilla.html` | Demo HTML/JS pura (nessun bundler) con UI per state, store, session, cache, observer e platform info. |
-
-## 📁 markdown/ (24 file)
-
-| File | Cosa documenta |
-|---|---|
-| `AUDIT-REPORT.md` | Audit di sicurezza/performance/affidabilità/qualità del codice per la v5.1.0 (datato 2026-09-06), con azioni correttive già applicate. |
-| `CACHE.md` | Reference della cache in-memory: API, quando usarla, limiti. |
-| `CHANGELOG.md` | Storico versioni dalla v2.5.0 alla `Unreleased`, con bugfix, refactoring e note di sicurezza per ogni release. |
-| `DEVTOOLS.md` | Strumenti di debug da console del browser per ispezionare/gestire lo stato di Memorio. |
-| `DISPATCH.md` | Sistema di eventi pub/sub per app vanilla JS (alternativa a `useObserver` fuori da React). |
-| `HISTORY.md` | Reference completa di time-travel: enable/snapshot/diff/undo/redo/rollback/trace, con "how it works" e best practice. |
-| `IDB.md` | Reference IndexedDB: creazione DB/tabelle, CRUD, info sul database. |
-| `IMPORT.md` | I due stili di import (named vs `memorio/global`) e perché condividono la stessa istanza. |
-| `INSPECT.md` | Utility di introspezione per scoprire/verificare la forma dello `state` a runtime - utile per agenti AI. |
-| `LOGGER.md` | Middleware di logging automatico per tracciare le modifiche di stato in console. |
-| `MEMORY-ATTACHMENT.md` | Sistema di "attachment" tra elementi di memoria - estensione opzionale della memoria semantica. |
-| `MEMORY.md` | Reference del layer di memoria semantica: remember/update/context, TTL, confidence, tag, scope. |
-| `OBSERVER.md` | Reference del pattern observer per reagire ai cambi di stato. |
-| `PLATFORM.md` | Platform detection + sistema di context isolation per applicazioni multi-tenant server-side. |
-| `PROJECT.md` | Scheda di progetto interna: versione, team, moduli inclusi, stack tecnologico, target. |
-| `SCHEMA.md` | Validazione runtime dei percorsi di stato: schema oggetto/array/enum/funzione custom. |
-| `SECURITY.md` | Postura di sicurezza del progetto (minacce coperte, cosa NON fa Memorio, come viene gestito l'accesso ai dati). |
-| `SESSION.md` | Reference di `session` (sessionStorage) con fallback in-memory fuori dal browser. |
-| `SQLITE.md` | Reference del layer SQLite via `sql.js`/`bun:sqlite`: caricamento lazy, persistenza journal+checkpoint, query. |
-| `STATE.md` | Reference dello stato reattivo basato su Proxy - il layer centrale di Memorio. |
-| `STORE.md` | Reference di `store` (localStorage) con fallback in-memory fuori dal browser. |
-| `SYNC.md` | Sincronizzazione local-first opzionale: scope, journal, conflict resolution, strategie avanzate per multi-device (HLC, tombstones, fractional indexing). |
-| `TYPED.md` | `memorio.typed<T>()` per la sicurezza dei tipi a compile-time sullo stesso proxy di `state`. |
-| `USEOBSERVER.md` | Reference dell'hook React `useObserver`: modalità auto-discovery vs deps espliciti, tutte le forme di `deps` supportate. |
-
----
-
-**Nota di copertura:** ogni doc in `markdown/` ha ora almeno un esempio corrispondente in `examples/`, **tranne** `DEVTOOLS.md`, `DISPATCH.md`, `INSPECT.md`, `LOGGER.md` e `MEMORY-ATTACHMENT.md` - utile saperlo se in futuro vuoi completare anche quelli.
+# Documentation map
+
+This index points to the current public documentation shipped with Memorio 5.2.0. Historical and
+proposed documents remain labelled so that design chronology is not confused with current behavior.
+
+## Start here
+
+| Document | Purpose |
+| --- | --- |
+| [`README.md`](./README.md) | Product overview, first examples, limitations, and reading paths. |
+| [`CURRENT_PROJECT_CHECKPOINT.md`](./CURRENT_PROJECT_CHECKPOINT.md) | Verified state at the 5.2.0 release boundary. |
+| [`CHANGELOG.md`](./CHANGELOG.md) | User-visible release history. |
+| [`SECURITY.md`](./SECURITY.md) | Security model, encryption, and epistemic boundaries. |
+| [`SECURITY-HARDENING.md`](./SECURITY-HARDENING.md) | Deployment and operational hardening guidance. |
+
+## Memory, MEM, and Logic
+
+| Document | Status and purpose |
+| --- | --- |
+| [`markdown/MEMORY.md`](./markdown/MEMORY.md) | Current memory API, including Acquire → Discover → Project and separate exact applicability selection. |
+| [`markdown/MEM_FORMAT.md`](./markdown/MEM_FORMAT.md) | Current `.mem` ZIP/JSON package, MAP/DATA, integrity, signatures, inspection, and compatibility. |
+| [`markdown/LOGIC.md`](./markdown/LOGIC.md) | Implemented and verified Logic PHASE 0 contract and repository isolation. |
+| [`markdown/MEMORY-ATTACHMENT.md`](./markdown/MEMORY-ATTACHMENT.md) | Proposed attachment design; not implemented. |
+| [`examples/acquired-knowledge.ts`](./examples/acquired-knowledge.ts) | Rerunnable production workflow example with acquisition, discovery, projection, exact selection, refinement, superseding, and current-reality verification. |
+| [`examples/semantic-memory.ts`](./examples/semantic-memory.ts) | Key/value application memory; despite its historical filename, it is not embedding/vector search. |
+
+## API references
+
+- Core: [`STATE.md`](./markdown/STATE.md), [`OBSERVER.md`](./markdown/OBSERVER.md),
+  [`DISPATCH.md`](./markdown/DISPATCH.md), [`HISTORY.md`](./markdown/HISTORY.md), and
+  [`TEMPORAL.md`](./markdown/TEMPORAL.md).
+- Storage: [`STORE.md`](./markdown/STORE.md), [`SESSION.md`](./markdown/SESSION.md),
+  [`CACHE.md`](./markdown/CACHE.md), [`IDB.md`](./markdown/IDB.md), and
+  [`SQLITE.md`](./markdown/SQLITE.md).
+- Integration and runtime: [`IMPORT.md`](./markdown/IMPORT.md), [`PLATFORM.md`](./markdown/PLATFORM.md),
+  [`TYPED.md`](./markdown/TYPED.md), [`SCHEMA.md`](./markdown/SCHEMA.md),
+  [`USEOBSERVER.md`](./markdown/USEOBSERVER.md), [`REDUX.md`](./markdown/REDUX.md), and
+  [`SYNC.md`](./markdown/SYNC.md).
+- Operations: [`INSPECT.md`](./markdown/INSPECT.md), [`DEVTOOLS.md`](./markdown/DEVTOOLS.md), and
+  [`LOGGER.md`](./markdown/LOGGER.md).
+
+## Decisions and historical material
+
+- [`adr/README.md`](./adr/README.md) classifies every ADR as CURRENT or OPEN while retaining its
+  original lifecycle status and text.
+- [`markdown/AUDIT-REPORT.md`](./markdown/AUDIT-REPORT.md) is a historical internal 5.1.0 audit, not a
+  third-party audit and not the current release checkpoint.
+- [`markdown/EXTENSION_VSCODE_DESIGN.md`](./markdown/EXTENSION_VSCODE_DESIGN.md) records extension
+  design material; it is not the authority for the core 5.2.0 runtime.
+
+## Examples
+
+The [`examples/`](./examples/) directory contains runnable examples for the major public layers. Use
+isolated state for examples that persist data. In particular, do not point examples at a real
+`.memorio/project.mem` or `.memorio/logic/logic.mem` merely for cleanup or demonstration.

package/adr/002-observer-semantics.md

@@ -1,6 +1,6 @@
 # ADR-002: Observer Semantics
 
-> **Status:** Proposed
+> **Status:** Accepted (CURRENT; compliance suite verified 2026-09-23)
 > **Date:** 2026-09-12
 
 ## Context

package/adr/003-deep-mutation-semantics.md

@@ -1,6 +1,6 @@
 # ADR-003: Deep Mutation Semantics
 
-> **Status:** Proposed
+> **Status:** Accepted (CURRENT; compliance suite verified 2026-09-23)
 > **Date:** 2026-09-12
 
 ## Context

package/adr/004-array-mutation-semantics.md

@@ -1,6 +1,6 @@
 # ADR-004: Array Mutation Semantics
 
-> **Status:** Proposed
+> **Status:** Accepted (CURRENT; compliance suite verified 2026-09-23)
 > **Date:** 2026-09-12
 
 ## Context

package/adr/010-logic-phase-0.md

@@ -0,0 +1,42 @@
+# ADR 010: Logic PHASE 0 Repository Boundary
+
+**Status:** Accepted
+
+## Context
+
+`memorio.logic` needs to persist and select situation/action/outcome experience while reusing the
+existing immutable acquired-claim, revision, MEM package, and selection machinery. Project acquired
+experience already persists in `.memorio/project.mem`. Mixing both domains would couple clearing,
+claim identities, revision validation, and discovery before cross-domain behavior has been designed.
+
+PHASE 0 also needs totals across all active Logic claims. A first implementation added `_all` to the
+general selector, but focused verification showed that the sentinel violated exact applicability
+matching, collided with the applicability namespace, and interacted incorrectly with specificity.
+
+## Decision
+
+- Persist Logic in its own `MemDirectoryKnowledgeRepository` rooted at `.memorio/logic`, with
+  `logic.mem` as its writable source.
+- Keep `.memorio/project.mem` and `.memorio/logic/logic.mem` as independent repositories and runtime
+  instances.
+- Keep claim identity, provenance, and revision validation repository-local. Do not imply or emulate
+  cross-repository revision relationships.
+- Preserve exact structured applicability matching in the shared selector.
+- Compute Logic totals by loading its repository and counting `activeClaims(state)`, not through a
+  wildcard query.
+- Expose the PHASE 0 singleton through named exports and `globalThis.memorio.logic`.
+
+## Consequences
+
+Logic cannot accidentally discover or clear project memory, and project acquired memory cannot
+discover or clear Logic. The shared selector retains one meaning. Totals include active claims at all
+applicability specificities.
+
+There is no unified query, revision chain, provenance graph, or composition behavior across the two
+repositories. Adding any of those is a future design decision, not an implied PHASE 0 capability.
+
+## Verification
+
+`tests/vitest/tests/contracts/adr-010-logic.test.ts` is the compliance suite. It includes the
+mixed-specificity regression added after `_all` was removed. The detailed investigation and
+chronology remain in `.project/phase0-design-verification.md` and `.project/project_history.md`.

package/adr/README.md

@@ -17,17 +17,22 @@ Decision Records) format. Each decision record answers four questions:
 
 ## Numbering
 
-| ADR | Title | Status |
-|-----|-------|--------|
-| [001](001-state-proxy-model.md) | State Proxy Model | Accepted |
-| [002](002-observer-semantics.md) | Observer Semantics | Proposed |
-| [003](003-deep-mutation-semantics.md) | Deep Mutation Semantics | Proposed |
-| [004](004-array-mutation-semantics.md) | Array Mutation Semantics | Proposed |
-| [005](005-scheduler-contract.md) | Scheduler Contract | Proposed |
-| [006](006-context-isolation.md) | Context Isolation Model | Accepted |
-| [007](007-mutation-records.md) | Mutation Records | Accepted |
-| [008](008-transactions.md) | Transactions | Accepted |
-| [009](009-history-model.md) | History Model (Snapshot/Delta) | Proposed |
+| ADR | Title | Lifecycle status | 5.2.0 classification |
+|-----|-------|------------------|----------------------|
+| [001](001-state-proxy-model.md) | State Proxy Model | Accepted | **CURRENT** |
+| [002](002-observer-semantics.md) | Observer Semantics | Accepted | **CURRENT** |
+| [003](003-deep-mutation-semantics.md) | Deep Mutation Semantics | Accepted | **CURRENT** |
+| [004](004-array-mutation-semantics.md) | Array Mutation Semantics | Accepted | **CURRENT** |
+| [005](005-scheduler-contract.md) | Scheduler Contract | Proposed | **OPEN** — only the documented current microtask behavior is implemented; the configurable scheduler is not |
+| [006](006-context-isolation.md) | Context Isolation Model | Accepted | **CURRENT** |
+| [007](007-mutation-records.md) | Mutation Records | Accepted | **CURRENT** |
+| [008](008-transactions.md) | Transactions | Accepted | **CURRENT** |
+| [009](009-history-model.md) | History Model (Snapshot/Delta) | Proposed | **OPEN** — the document preserves the implemented flat baseline and a future commit model |
+| [010](010-logic-phase-0.md) | Logic PHASE 0 Repository Boundary | Accepted | **CURRENT** |
+
+No ADR is classified as **SUPERSEDED** or **HISTORICAL** at this checkpoint. Historical intermediate
+implementation details (notably Logic's rejected `_all` sentinel) remain in the relevant ADR and
+project history, while the accepted decision describes current behavior.
 
 ## Lifecycle
 

package/bin/cli.js

@@ -1,68 +1,90 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import path from 'node:path';
-import fs from 'node:fs';
-import os from 'node:os';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-const args = process.argv.slice(2);
-const command = args[0];
-
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import fs from 'node:fs'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const args = process.argv.slice(2)
+const command = args[0]
+
 if (command === 'install-extension') {
-  installExtension();
+  installExtension()
+} else if (command === 'inspect') {
+  inspectMemory(args[1])
 } else {
-  console.log('Usage: npx memorio install-extension');
-  process.exit(command ? 1 : 0);
+  console.info('Usage: npx memorio <install-extension|inspect FILE.mem>')
+  process.exit(command ? 1 : 0)
 }
 
-function installExtension() {
-  const vsixPath = path.join(__dirname, '..', 'vsix', 'memorio.vsix');
-
-  if (!fs.existsSync(vsixPath)) {
-    console.error(`VSIX file not found at ${vsixPath}.`);
-    console.error('The npm package may be corrupted, or the build did not copy the .vsix into vsix/.');
-    process.exit(1);
+async function inspectMemory(file) {
+  if (!file) {
+    console.error('Usage: npx memorio inspect FILE.mem')
+    process.exitCode = 1
+    return
   }
-
-  const candidates = candidateBinaries();
-  const found = candidates.find((bin) => isAvailable(bin));
-
-  if (!found) {
-    console.error('No compatible editor found in PATH (tried: ' + candidates.join(', ') + ').');
-    console.error('Manual installation:');
-    console.error('  1. Open your editor (VSCodium/VSCode)');
-    console.error('  2. Command Palette -> "Extensions: Install from VSIX..."');
-    console.error(`  3. Select: ${vsixPath}`);
-    process.exit(1);
+  try {
+    const [{ inspectMem }, bytes] = await Promise.all([
+      import('../index.js'),
+      fs.promises.readFile(path.resolve(file))
+    ])
+    const result = await inspectMem(bytes)
+    console.info(JSON.stringify(result, null, 2))
+    if (result.status !== 'valid') process.exitCode = 2
+  } catch (error) {
+    console.error(`Unable to inspect ${file}: ${error instanceof Error ? error.message : String(error)}`)
+    process.exitCode = 1
   }
-
-  console.log(`Editor detected: ${found}. Installing memorio extension...`);
-  const result = spawnSync(found, ['--install-extension', vsixPath], {
-    stdio: 'inherit',
-    shell: os.platform() === 'win32',
-  });
-
-  if (result.status !== 0) {
-    console.error('Installation failed. Try manually:');
-    console.error(`  ${found} --install-extension "${vsixPath}"`);
-    process.exit(result.status || 1);
-  }
-
-  console.log('Memorio extension installed successfully.');
-}
-
-function candidateBinaries() {
-  const names = ['codium', 'vscodium', 'code', 'code-insiders'];
-  if (os.platform() === 'win32') {
-    return names.map((n) => `${n}.cmd`);
-  }
-  return names;
-}
-
-function isAvailable(bin) {
-  const checkCmd = os.platform() === 'win32' ? 'where' : 'which';
-  const result = spawnSync(checkCmd, [bin], { stdio: 'ignore', shell: true });
-  return result.status === 0;
 }
+
+function installExtension() {
+  const vsixPath = path.join(__dirname, '..', 'vsix', 'memorio.vsix')
+
+  if (!fs.existsSync(vsixPath)) {
+    console.error(`VSIX file not found at ${vsixPath}.`)
+    console.error('The npm package may be corrupted, or the build did not copy the .vsix into vsix/.')
+    process.exit(1)
+  }
+
+  const candidates = candidateBinaries()
+  const found = candidates.find((bin) => isAvailable(bin))
+
+  if (!found) {
+    console.error('No compatible editor found in PATH (tried: ' + candidates.join(', ') + ').')
+    console.error('Manual installation:')
+    console.error('  1. Open your editor (VSCodium/VSCode)')
+    console.error('  2. Command Palette -> "Extensions: Install from VSIX..."')
+    console.error(`  3. Select: ${vsixPath}`)
+    process.exit(1)
+  }
+
+  console.info(`Editor detected: ${found}. Installing memorio extension...`)
+  const result = spawnSync(found, ['--install-extension', vsixPath], {
+    stdio: 'inherit',
+    shell: os.platform() === 'win32',
+  })
+
+  if (result.status !== 0) {
+    console.error('Installation failed. Try manually:')
+    console.error(`  ${found} --install-extension "${vsixPath}"`)
+    process.exit(result.status || 1)
+  }
+
+  console.info('Memorio extension installed successfully.')
+}
+
+function candidateBinaries() {
+  const names = ['codium', 'vscodium', 'code', 'code-insiders']
+  if (os.platform() === 'win32') {
+    return names.map((n) => `${n}.cmd`)
+  }
+  return names
+}
+
+function isAvailable(bin) {
+  const checkCmd = os.platform() === 'win32' ? 'where' : 'which'
+  const result = spawnSync(checkCmd, [bin], { stdio: 'ignore', shell: true })
+  return result.status === 0
+}

package/examples/acquired-knowledge.ts

@@ -0,0 +1,174 @@
+/**
+ * acquired-knowledge.ts
+ *
+ * Scenario: an AI agent working on a real project needs to record lessons it
+ * learns during development so that future sessions can recall them instead
+ * of re-discovering the same issues.
+ *
+ * The complete workflow preserves an experience with `acquire()`, finds
+ * plausible prior experience from ordinary situation text with `discover()`,
+ * and prepares bounded untrusted context for an AI with `project()`.
+ * `context({ acquired })` remains the separate exact applicability selector.
+ *
+ * Run: npx tsx docs/examples/acquired-knowledge.ts
+ */
+import { memorio } from 'memorio'
+
+const mem = memorio.memory
+
+async function main() {
+  // ============================================
+  // 1. Check exact current state before acquiring this fixed demo identity.
+  //    This keeps the example safe to run again without duplicating claim IDs.
+  // ============================================
+
+  console.debug('=== Checking for Existing Knowledge ===\n')
+
+  const existing = await mem.context({
+    acquired: { area: 'css', component: 'layout', pattern: 'grid-min-content' }
+  })
+
+  if (existing.claims.length > 0) {
+    console.debug(`Found ${existing.claims.length} relevant claim(s):`)
+    for (const claim of existing.claims) {
+      console.debug(`  - [${claim.id}]`, JSON.stringify(claim.knowledge))
+      console.debug(`    Evidence:`, claim.evidence)
+      if (claim.revision) {
+        console.debug(`    Revision:`, claim.revision)
+      }
+    }
+    console.debug('')
+  } else {
+    console.debug('No prior knowledge found for this context. Proceeding fresh.\n')
+  }
+
+  // ============================================
+  // 2. Acquire knowledge after learning it
+  // ============================================
+
+  console.debug('=== Acquiring Knowledge When Missing ===\n')
+
+  // Lesson learned: a CSS grid track sized with min-content also incorporates
+  // the inner element's margins. Replacing it with a fixed width changes the
+  // effective rendered track.
+  if (existing.claims.length === 0) await mem.acquire({
+    id: 'css.grid.min-content-margins',
+    knowledge: {
+      guidance: 'Replacing a min-content grid track with the inner element fixed width changes the effective rendered track width because min-content sizing incorporates the inner element margins.',
+      impact: 'Layout shifted when a fixed-width aside replaced a min-content grid track.'
+    },
+    applies: { area: 'css', component: 'layout', pattern: 'grid-min-content' },
+    evidence: [{
+      id: 'layout-debug-20260918',
+      source: 'real-project',
+      observedAt: '2026-09-18T12:30:00Z'
+    }],
+    epistemicType: 'observed',
+    provenance: { source: 'example-project', detail: 'Observed during layout debugging.' }
+  })
+  console.debug(existing.claims.length === 0
+    ? 'Acquired: css.grid.min-content-margins\n'
+    : 'The demo already has active general knowledge; acquisition skipped.\n')
+
+  // ============================================
+  // 3. Discover from ordinary situation text, then project for AI transfer
+  // ============================================
+
+  console.debug('=== Discovering and Projecting Prior Experience ===\n')
+
+  const found = await mem.discover(
+    'An aside layout shifted after changing CSS grid track sizing and margins.'
+  )
+  const projected = mem.project(found, { maxCandidates: 3, maxCharacters: 4_000 })
+
+  console.debug('Discovered candidates:', found.candidates.map(candidate => candidate.claim.id))
+  console.debug('Projected candidates:', projected.experiences.map(experience => experience.id))
+  console.debug('Omitted candidates:', projected.omittedCandidates)
+  console.debug('AI context (prior experience, not current truth):\n', projected.text)
+  console.debug('Verify projected experience against the current project before acting.\n')
+
+  // ============================================
+  // 4. Use exact applicability selection when the context is known
+  // ============================================
+
+  console.debug('=== Selecting Exact Acquired Context ===\n')
+
+  const context = await mem.context({
+    acquired: { area: 'css', component: 'layout', pattern: 'grid-min-content' }
+  })
+
+  console.debug('Knowledge version:', context.knowledgeVersion)
+  for (const claim of context.claims) {
+    console.debug(`Claim: ${claim.id}`)
+    console.debug('  Knowledge:', JSON.stringify(claim.knowledge))
+    console.debug('  Applies:', JSON.stringify(claim.applicability))
+    console.debug('  Evidence:', JSON.stringify(claim.evidence))
+  }
+
+  // ============================================
+  // 5. Refine with more specific knowledge
+  // ============================================
+
+  console.debug('\n=== Refining with More Specific Knowledge ===\n')
+
+  let specific = await mem.context({
+    acquired: { area: 'css', component: 'layout', pattern: 'grid-min-content', element: 'aside' }
+  })
+  const hasSpecificDemo = specific.claims.some(claim => claim.id === 'css.grid.aside-min-content')
+  if (!hasSpecificDemo) await mem.acquire({
+    id: 'css.grid.aside-min-content',
+    knowledge: {
+      guidance: 'For aside elements in a grid with min-content tracks, retain min-content and set max-width on the inner content instead of replacing the track sizing.',
+    },
+    applies: { area: 'css', component: 'layout', pattern: 'grid-min-content', element: 'aside' },
+    evidence: [{ id: 'layout-debug-20260918' }],
+    refines: 'css.grid.min-content-margins'
+  })
+  if (!hasSpecificDemo) {
+    console.debug('Acquired refinement: css.grid.aside-min-content\n')
+    specific = await mem.context({
+      acquired: { area: 'css', component: 'layout', pattern: 'grid-min-content', element: 'aside' }
+    })
+  }
+
+  // Query the specific context - gets only the more specific claim
+  console.debug('Specific context claims:', specific.claims.map(c => c.id))
+
+  // Query the general context - gets only the general claim
+  const general = await mem.context({
+    acquired: { area: 'css', component: 'layout', pattern: 'grid-min-content' }
+  })
+  console.debug('General context claims:', general.claims.map(c => c.id))
+
+  // ============================================
+  // 6. Supersede outdated knowledge
+  // ============================================
+
+  console.debug('\n=== Superseding Outdated Knowledge ===\n')
+
+  if (!general.claims.some(claim => claim.id === 'css.grid.min-content-margins.v2')) await mem.acquire({
+    id: 'css.grid.min-content-margins.v2',
+    knowledge: {
+      guidance: 'Prefer explicit track sizing (fr units) over min-content for predictable layouts. Min-content still incorporates margins; use this understanding when explicit control is needed.',
+    },
+    applies: { area: 'css', component: 'layout', pattern: 'grid-min-content' },
+    evidence: [{ id: 'layout-debug-20260918' }],
+    supersedes: 'css.grid.min-content-margins'
+  })
+  console.debug(general.claims.some(claim => claim.id === 'css.grid.min-content-margins.v2')
+    ? 'The demo replacement is already current; supersede skipped.\n'
+    : 'Superseded old claim with v2.\n')
+
+  const afterSupersede = await mem.context({
+    acquired: { area: 'css', component: 'layout', pattern: 'grid-min-content' }
+  })
+  console.debug('After supersede, claims:', afterSupersede.claims.map(c => c.id))
+
+  // Acquired knowledge is intentionally persistent. Do not call clear() as
+  // routine cleanup: in a real project it would erase unrelated memory too.
+}
+
+main().catch(err => {
+  console.error('ERROR:', err)
+  process.exit(1)
+})