memorio 5.1.3 → 5.2.0

package/llms.txt

@@ -80,17 +80,41 @@ state.remove('items')
 state.removeAll()
 ```
 
-**Locking - VERIFY BEFORE PUBLISHING:** this library's own documents currently disagree on scope.
+**Locking:** `memorio` implements **both** lock scopes, using distinct method names.
 
-- One source describes **per-key** locking: `state.config.lock()` freezes only the `config` key; other keys remain writable.
-- Another source describes **global** locking: `state.lock()` / `state.unlock()` freezing the entire `state` object at once.
+- **Global lock** - `state.lock()` / `state.unlock()`: freezes the entire `state` surface at once. While locked, every write (top-level set, nested mutation, array mutation, and deletion) is rejected and the assignment throws in strict/ESM code; values are left unchanged. Use it for whole-tree immutability.
+- **Per-key lock** - `state.<key>.lock()` / `state.<key>.unlock()`: locks a single first-level node. While that node is locked, reassigning the key, mutating the node's own properties, calling mutating array methods on a locked array, and deleting the node's properties are all rejected. Only that key is affected; every other top-level key stays writable.
 
-These are materially different behaviors - confirm against the actual source which one (or both, with distinct method names) is implemented, then replace this note with the real signature(s). Do not ship a docs update, or generate code against this section, until this is resolved.
+```javascript
+state.lock()             // block all writes across state
+state.user = { name: 'Sara' }  // -> throws "Error: state is locked" while held
+state.unlock()           // resume writes
+
+state.myArray = [1, 2, 3]
+state.myArray.lock()     // lock only this key
+state.myArray.push(4)    // -> throws "Error: state is locked"
+state.myArray.unlock()   // resume writes to myArray only
+```
+
+Per-key locking is first-level only by design: locking `state.a` does not transitively lock `state.a.b`. Lock each descendant explicitly, or use the global lock for whole-subtree immutability.
 
 **Features:**
 - Automatic path tracking via `__path` property
 - Nested proxy support
 - Auto-dispatches events on changes
+- `state.persist(path)` mirrors state path to `store` and syncs writes (see "Getting Started" guide)
+
+#### `state.persist(path)`
+
+Creates a bidirectional mirror between `state` (live in-memory) and `store` (durable copy). Seeds the initial value from `store` if present, then every write to that path flows to `store` automatically.
+
+```javascript
+const stopPersisting = state.persist('state.user')
+state.user = { name: 'Sara' }
+// ... writes to state.user are mirrored to store
+
+stopPersisting() // stops mirroring; store value is preserved
+```
 
 ### `store` - localStorage Persistence
 
@@ -182,6 +206,61 @@ const value = cache['myKey']
 delete cache['myKey']
 ```
 
+### `memory` - Application Memory (confidence, TTL, tags, lifecycle)
+
+Structured key/value memory with confidence scoring, TTL, tagging, scope-based persistence, and full lifecycle (remember/update/supersede/forget).
+
+```javascript
+import { memory } from 'memorio'
+
+// Store with metadata
+await memory.remember('user.language', 'Italian', {
+  type: 'preference',
+  confidence: 0.92,
+  tags: ['user', 'ui'],
+  source: 'conversation'
+})
+
+// Retrieve by key (respects confidence threshold, TTL)
+const language = await memory.recall('user.language')
+
+// Update supersedes the old entry (history preserved)
+await memory.update('user.language', 'English', { confidence: 0.95 })
+
+// Ranked retrieval - rule-based (tags/type/confidence/recency), NOT embedding search
+const ctx = await memory.context({
+  tags: 'user',
+  types: ['preference', 'decision'],
+  minConfidence: 0.7,
+  maxEntries: 10,
+  scopes: ['local', 'durable']
+})
+```
+
+**Acquired Knowledge** - `memory.acquire()` stores structured knowledge claims that apply under specific conditions; `context({ acquired })` retrieves only the claims matching the current situation:
+
+Autonomous persistent acquisition is experimental and optional. Treat retrieved claims as evidence, not authority, and verify them against current reality. Acquire only non-obvious reusable experience supported by evidence—not repository facts—and keep observation, inference, verified result, and acquired experience distinct. Architecture rationale, evidenced user technical decisions, documentation interpretation, and verified fix consequences are the Phase 1 focus. `nothing worth acquiring` is always valid. See `markdown/MEMORY.md#guidance-for-autonomous-use` for safety guidance and the unresolved autonomous-memory-safety TODO.
+
+```javascript
+// Record a lesson that applies to CSS grid layout with min-content tracks
+await memory.acquire({
+  id: 'css.grid.min-content-margins',
+  knowledge: { guidance: 'min-content incorporates inner element margins; replacing with fixed width changes effective track width' },
+  applies: { area: 'css', component: 'layout', pattern: 'grid-min-content' },
+  evidence: [{ id: 'layout-debug-20260918', source: 'real-project' }]
+})
+
+// Later, retrieve only knowledge applicable to this specific situation
+const result = await memory.context({
+  acquired: { area: 'css', component: 'layout', pattern: 'grid-min-content', element: 'aside' }
+})
+// { knowledgeVersion, claims: [...] }
+```
+
+**Matching semantics:** a claim matches when every key in its `applicability` equals the corresponding key in the query context. When multiple claims match, the most specific (most applicability keys) wins - more specific claims act as overrides, general claims as fallbacks. Use `refines` to link a more-specific claim to a general one, or `supersedes` to replace an older claim entirely.
+
+Acquired knowledge persists to `.memorio/project.mem` in Node.js/Bun, or to `store` in browser/edge environments. Make experimental autonomous persistence visible to the user. `memory.clear()` destructively wipes all memories and acquired knowledge; tests must point persistence at an isolated temporary project directory and clean up only that data.
+
 ### `idb` - IndexedDB
 
 Structured, persistent, async database (browser-only). **Disabled in Node.js/Deno** - calls will warn and no-op; use `store` or `session` there instead.
@@ -534,6 +613,58 @@ Patch utilities convert mutations to RFC 6902-style patches for replay, sync, an
 import { mutationToPatch, diffToPatch, canMerge, mergePatches } from 'memorio'
 ```
 
+### `memorio.temporal` - Temporal Memory (Time-Travel Query)
+
+The temporal engine maintains an immutable log of every mutation with HLC timestamps, enabling point-in-time queries, diffing, and branching. Temporal tracking is **enabled by default** and independent from `enableHistory()`:
+
+```javascript
+import { state, memorio } from 'memorio'
+
+state.counter = 1
+state.counter = 2
+state.counter = 3
+
+// History: all mutations at a path, sorted chronologically
+const mutations = memorio.temporal.history('counter')
+
+// at(): point-in-time value lookup (returns deep clone, never mutates live state)
+const hlc1 = mutations[0].hlc
+memorio.temporal.at('counter', hlc1)      // 1
+memorio.temporal.at('counter', Date.now()) // 3
+
+// HLC strings include logical counter for precise per-mutation queries;
+// numeric timestamps include all mutations at the same physical millisecond.
+```
+
+```javascript
+// diff(): changes within a time range (from is exclusive, to is inclusive)
+const hlc2 = mutations[1].hlc
+memorio.temporal.diff('counter', hlc2, Date.now())
+// [{ path: 'counter', before: 2, after: 3, operation: 'set', hlc, timestamp }]
+
+// replay(): reconstruct full state at a point in time
+memorio.temporal.replay()                    // full history
+memorio.temporal.replay({ from: hlc1, to: hlc2 }) // time range
+
+// explain(): provenance metadata for a path
+const info = memorio.temporal.explain('user.role')
+// { path, currentValue, previousValue, history, createdAt, lastChangedAt, ... }
+
+// branch(): isolated temporal world (mutations don't affect live state)
+const branch = memorio.temporal.branch()
+branch.state.counter = 99
+memorio.temporal.at('counter', Date.now())  // still 3 in main state
+branch.discard()  // or branch.commit()
+
+// Configuration
+memorio.temporal.enable(false)      // stop recording
+memorio.temporal.isEnabled()        // false
+memorio.temporal.configure({ maxEntries: 50000 })
+memorio.temporal.stats()            // { total, byPath }
+memorio.temporal.size()             // mutation count
+memorio.temporal.clear()            // wipe log (does not affect live state)
+```
+
 ### `memorio.trace()` - Mutation Log
 
 ```javascript

package/markdown/EXTENSION_VSCODE_DESIGN.md

@@ -0,0 +1,410 @@
+# Memorio VSCode Extension - Technical Design
+
+## Status
+**Proposed** - Phase 1 (IntelliSense + Hover) ready for implementation.
+
+## 1. Architecture overview
+
+### 1.1 Recommended tooling
+
+| Concern | Tool | Rationale |
+|---|---|---|
+| Language/Runtime | TypeScript + Node.js (VSCode extension host) | VS Code extension API is Node-based; no Bun dependency in extension host |
+| Static analysis | **ts-morph** (not raw TS Compiler API) | 80% less boilerplate than raw TS API for AST traversal + pattern matching. `ts-morph` wraps the TS Compiler API with a friendlier query DSL (`getDescendantsOfKind`, `forEachDescendant`). Performance on large workspaces is acceptable with file-level caching (see 3.3). |
+| Webview UI | React + `reactflow` | Industry standard for interactive graph editors; tree-shakable; well-maintained |
+| Webview bundling | `esbuild` (via `vsce`) | Fast bundling for webview assets; `vsce` handles packaging |
+| State sharing | `vscode.Memento` (ExtensionContext.globalState) | Persists layout preferences per-session, not per-workspace |
+| Communication | `postMessage` + `onDidReceiveMessage` | Standard VS Code webview↔extension host pattern |
+
+### 1.2 Architecture decision: single analysis pipeline
+
+**Decision**: One AST analysis pass feeds both diagnostics and the graph view. Not two separate pipelines.
+
+```
+Workspace files
+  → ts-morph Project (file-level cache)
+    → MemorioCallScanner (extracts all memorio.* calls)
+      → DiagnosticProvider (writes to vscode.DiagnosticCollection)
+      → GraphBuilder (produces GraphSnapshot)
+        → StoreGraphPanel (webview)
+```
+
+**Rationale**: Both features need the same raw data - which memorio APIs are called, from which files, with which arguments. Running two traversals doubles startup cost on large workspaces. The scanner produces an intermediate `MemorioCall[]` structure; both consumers read from it.
+
+### 1.3 Performance strategy for large workspaces
+
+| Problem | Solution |
+|---|---|
+| Full AST scan on every keystroke | Debounce + file-level cache; only re-scan the changed file |
+| Workspace-wide scan blocks extension host | `vscode.workspace.createFileSystemWatcher` + incremental `TextDocument` change events; scan only open files unless `memorio: Analyze Workspace` is invoked manually |
+| Large files (>5000 lines) | Skip or use syntax-only scan (no type resolution) |
+| ts-morph Project memory | Dispose unused `SourceFile` objects; reuse single `Project` instance with `skipAddingFilesFromTsConfig` and explicit `addSourceFileAtOffset` |
+
+## 2. Project structure
+
+```
+extension/vscode/
+├── package.json              # Extension manifest (contributes, commands, views)
+├── tsconfig.json
+├── src/
+│   ├── extension.ts          # Entry point: register commands, providers, webview
+│   ├── analyzer/
+│   │   ├── MemorioCallScanner.ts     # AST traversal via ts-morph
+│   │   ├── callTypes.ts              # MemorioCall, CallKind, LocationInfo types
+│   │   ├── cache.ts                  # File-level result cache + debouncer
+│   │   └── patterns.ts              # Known memorio API patterns (import paths, call signatures)
+│   ├── graph/
+│   │   ├── GraphBuilder.ts          # Converts MemorioCall[] → GraphSnapshot
+│   │   ├── schema.ts                # GraphNode, GraphEdge, GraphSnapshot types
+│   │   └── nodeKinds.ts             # NodeKind enum + metadata defaults
+│   ├── diagnostics/
+│   │   ├── DiagnosticGenerator.ts   # Maps MemorioCall[] → vscode.Diagnostic[]
+│   │   ├── rules.ts                 # Heuristic rule definitions
+│   │   └── RuleSeverity.ts
+│   ├── webview/
+│   │   ├── StoreGraphPanel.ts       # WebviewPanel lifecycle, postMessage routing
+│   │   ├── assets/
+│   │   │   ├── index.html
+│   │   │   └── graph-view.tsx       # React + ReactFlow component (bundled)
+│   │   └── messageProtocol.ts       # Typed protocol: GraphSnapshot ↔ webview messages
+│   ├── lang/
+│   │   ├── memorioCompletion.ts     # TypeScript completions (monkeypatch vscode.languages)
+│   │   └── memorioHover.ts          # Hover documentation provider
+│   ├── snippets.ts                   # Snippet definitions
+│   └── utils/
+│       ├── assets.ts                # Icon/path helpers
+│       └── logger.ts                # Thin wrapper around vscode.OutputChannel
+└── media/
+    ├── memorio-icon-dark.svg        # Generated (no pre-existing assets in repo)
+    └── memorio-icon-light.svg
+```
+
+**No runtime injection**: All files under `analyzer/`, `graph/`, `diagnostics/` are pure read-only static analysis. They do not import from `memoro` - they pattern-match AST nodes against known API names. This ensures zero impact on user code.
+
+## 3. Schema dati del grafo
+
+### 3.1 Types
+
+```ts
+// --- Node kinds (each maps to a memorio concept) ---
+enum NodeKind {
+  State = 'state',          // import { state } from 'memorio'
+  Store = 'store',          // import { store } from 'memorio'
+  Session = 'session',
+  Cache = 'cache',
+  IDB = 'idb',
+  SQLite = 'sqlite',
+  Memory = 'memory',
+  Journal = 'journal',
+  Context = 'context',      // memorio.createContext(...)
+  ReduxBridge = 'redux-bridge', // createMemorioReduxBridge(...)
+  Observer = 'observer',    // observer('path', cb)
+  Schema = 'schema',        // registerSchema('name', schema)
+  SyncProvider = 'sync-provider', // memory.configure({ provider: {...} })
+}
+
+// --- Core node type ---
+interface GraphNode {
+  id: string              // Deterministic: `${filePath}:${callId}`
+  kind: NodeKind
+  label: string           // Derived: context name, store name, or kind
+  filePath: string        // Absolute path to source file
+  range: Range            // VS Code range for go-to-definition
+  meta: NodeMeta
+}
+
+interface NodeMeta {
+  persisted: boolean
+  encrypted: boolean      // true if encryptionKey on context/config
+  readonly: boolean       // true if only observed, never mutated
+  beta: boolean           // true for sqlite (alpha), journal (beta)
+  schemaRegistered?: string  // schema name if registerSchema used
+  sizeEstimate?: number   // byte estimate if computable
+  version?: string        // engine version (sqlite: bun:sqlite vs sql.js)
+}
+
+// --- Edge types (relationships) ---
+type EdgeKind =
+  | 'observes'        // observer → store/state
+  | 'syncs-to'        // memory → sync-provider (push)
+  | 'syncs-from'      // sync-provider → memory (pull)
+  | 'bridges-to'      // redux-bridge → redux store
+  | 'isolated-from'   // context → parent context
+  | 'uses-schema'     // state/store → schema
+  | 'persists-to'     // store/session → idb/sqlite
+
+interface GraphEdge {
+  id: string            // `${sourceId}->${targetId}:${kind}`
+  source: string        // source node id
+  target: string        // target node id
+  kind: EdgeKind
+  label?: string        // optional: conflict resolution strategy, sync direction
+  meta?: EdgeMeta
+}
+
+interface EdgeMeta {
+  resolution?: 'hlc' | 'custom' | 'remote-wins'  // sync edge only
+  direction?: 'push' | 'pull'    // sync edge only
+  path?: string                  // observes edge: observed path
+}
+
+// --- Complete graph snapshot ---
+interface GraphSnapshot {
+  version: string             // semver: "1.0"
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+  workspaceRoot: string
+  generatedAt: number         // epoch ms
+}
+```
+
+### 3.2 Edge examples (from real memorio patterns)
+
+```ts
+// Source file:
+const ctx = memorio.createContext('tenant:acme')
+const encryptedCtx = memorio.createContext('tenant:acme', { encryptionKey: key })
+ctx.store.set('user', { id: 1 })
+encryptedCtx.store.set('secret', { token: 'abc' })
+
+memorio.memory.configure({
+  provider: {
+    push: ops => fetch('/sync', { method: 'POST', body: JSON.stringify(ops) }),
+    pull: since => fetch(`/sync?since=${since}`).then(r => r.json())
+  },
+  resolveConflict: (local, remote) => local.confidence >= remote.confence ? local : remote
+})
+```
+
+Produces:
+```
+Nodes:
+  context[tenant:acme]           kind=Context      meta.persisted=false
+  context[tenant:acme#enc]       kind=Context      meta.encrypted=true
+  store[tenant:acme]             kind=Store        meta.persisted=false
+  store[tenant:acme#enc]         kind=Store        meta.encrypted=true
+  memory[default]                kind=Memory       meta.persisted=true
+
+Edges:
+  store[tenant:acme] → observes state              kind=observes
+  store[tenant:acme#enc] → isolated-from → context[tenant:acme]   kind=isolated-from
+  memory[default] → syncs-to → sync-provider       kind=syncs-to  label="custom"
+  memory[default] → syncs-from → sync-provider     kind=syncs-from label="custom"
+```
+
+### 3.3 Node metadata inference
+
+| Metadata | How inferred |
+|---|---|
+| `persisted` | File imports `store` or `session` or `idb` (not `state`/`cache`) |
+| `encrypted` | Presence of `encryptionKey` arg on `createContext`, or `store.config({ encryptionKey })` |
+| `beta` | `NodeKind.SQLite` → true; `NodeKind.Journal` → true; all others false |
+| `schemaRegistered` | `registerSchema(name, schema)` call detected in same file |
+| `sizeEstimate` | Computed from `store.db.size()` / `idb.db.size()` at runtime (if available); null otherwise |
+
+## 4. Webview component sketch
+
+### 4.1 React Flow node types
+
+```tsx
+// Custom node for store/context (badge shows persistence/encryption)
+function StoreNode({ data }: NodeProps<GraphNode>): JSX.Element {
+  const badge = (
+    <div className="badges">
+      {data.meta.encrypted && <span className="badge badge--encrypted">🔒</span>}
+      {data.meta.persisted && <span className="badge badge--persisted">💾</span>}
+      {data.meta.beta && <span className="badge badge--beta">β</span>}
+    </div>
+  )
+  return (
+    <div className="node store-node">
+      <div className="node__header">
+        <span className="node__icon">🗄️</span>
+        <span className="node__label">{data.label}</span>
+      </div>
+      {badge}
+      <div className="node__meta">
+        {data.meta.schemaRegistered && <SchemaTag schema={data.meta.schemaRegistered} />}
+      </div>
+    </div>
+  )
+}
+
+// Timeline node (undo/redo snapshot)
+function TimelineNode({ data }: NodeProps<TimelineNodeData>): JSX.Element {
+  return (
+    <div className="node timeline-node">
+      <div className="node__header">
+        <span className="node__icon">📸</span>
+        <span className="node__label">Snapshot #{data.snapshotId}</span>
+      </div>
+      <div className="node__detail">{data.mutationCount} mutations</div>
+    </div>
+  )
+}
+```
+
+### 4.2 Sidebar detail panel (click a node)
+
+```tsx
+function NodeDetailsPanel({ node }: { node: GraphNode | undefined }) {
+  if (!node) return <div className="details--empty">Select a node</div>
+
+  return (
+    <div className="details-panel">
+      <h3>{node.label}</h3>
+      <dl>
+        <dt>Layer</dt><dd>{node.kind}</dd>
+        <dt>File</dt><dd><a href={`vscode://file/${node.filePath}`}>{node.filePath}</a></dd>
+        <dt>Persisted</dt><dd>{node.meta.persisted ? 'Yes' : 'No'}</dd>
+        <dt>Encrypted</dt><dd>{node.meta.encrypted ? 'Yes' : 'No'}</dd>
+        {node.meta.schemaRegistered && <><dt>Schema</dt><dd>{node.meta.schemaRegistered}</dd></>}
+        {node.meta.beta && <><dt>Beta</dt><dd>Experimental API - expect changes</dd></>}
+      </dl>
+      <button onClick={() => openDefinition(node.filePath, node.range)}>
+        Go to definition
+      </button>
+    </div>
+  )
+}
+```
+
+### 4.3 Timeline toggle
+
+A `Toggle` button in the webview toolbar switches the graph from **Layer view** (default graph) to **Timeline view** (linear undo/redo history for the selected store). Timeline nodes are populated from `trace()` output if the user's code calls `memorio.trace()`.
+
+## 5. Commands and settings
+
+### 5.1 Commands (`package.json` `contributes.commands`)
+
+| Command ID | Title | When |
+|---|---|---|
+| `memorio.analyzeWorkspace` | Memorio: Analyze Workspace | editorTextFocus |
+| `memorio.toggleGraphView` | Memorio: Show Store Graph | view:memorioGraphView |
+| `memorio.refreshGraph` | Memorio: Refresh Graph | webviewFocused |
+| `memorio.toggleTimeline` | Memorio: Toggle Timeline | webviewFocused |
+| `memorio.openLogs` | Memorio: Open Logs | view:memorioGraphView |
+| `memorio.openExtensionSettings` | Memorio: Settings | view:memorioGraphView |
+
+### 5.2 View containers
+
+| View | Location | Type |
+|---|---|---|
+| `memorioGraphView` | `explorer` sidebar | WebviewView (graph panel in sidebar) |
+| `memorioTimelineView` | `memorioGraphView` tab | WebviewPanel (tabbed view in graph view) |
+
+### 5.3 Settings (`package.json` `contributes.configuration`)
+
+| Setting | Default | Description |
+|---|---|---|
+| `memorio.analysis.includePatterns` | `["**/*.{ts,tsx,js,jsx}"]` | Glob patterns for files to analyze |
+| `memorio.analysis.excludePatterns` | `["**/node_modules/**", "**/dist/**"]` | Glob patterns to skip |
+| `memorio.graph.autoRefresh` | `true` | Auto-refresh graph on file save |
+| `memorio.diagnostics.enable` | `true` | Enable real-time diagnostic warnings |
+| `memorio.graph.saveLayout` | `"session"` | `session` (reset on reload) / `workspace` (persist to .vscode) |
+
+### 5.4 Comparison with competitor
+
+| Feature | Competitor (Memorio) | This extension |
+|---|---|---|
+| IntelliSense | ✅ autocomplete on memorio imports | ✅ + hover docs with link to README sections |
+| Hover | Basic type info | ✅ Type + options + doc link + example |
+| Snippets | Template snippets only | ✅ + dynamic snippets based on context/schema |
+| Diagnostics | Warning for missing namespace | ✅ + risk pattern detection (__proto__, constructor) + hint on `includeObsolete` |
+| State Explorer | Static text tree | ✅ Interactive React Flow graph with node metadata |
+| - | - | ✅ Timeline view (undo/redo history) |
+| - | - | ✅ Conflict resolution strategy labels on sync edges |
+| - | - | ✅ Incremental workspace analysis (debounced, cached) |
+
+## 6. Diagnostic rules (heuristic, AST-based)
+
+**⚠️ Declaration**: These diagnostics are heuristic - based on AST pattern matching, not a TypeScript type-checker. They reduce false negatives but may produce false positives. They never block compilation or execution.
+
+| Rule ID | Severity | Trigger pattern | Message |
+|---|---|---|---|
+| `memorio-missing-store` | Hint | `observer('state.x', cb)` without prior `store`/`session` import in same file | "State observed but no persistence layer imported - changes won't survive reload" |
+| `memorio-include-obsolete-hint` | Information | `memory.recall(key)` without `{ includeObsolete: true }` | "Consider `includeObsolete: true` to see superseded values for this key" |
+| `memorio-prototype-pollution-risk` | Warning | `state[key] = value` where `key` is a variable (dynamic key on state proxy) | "Dynamic key assignment to state may cause prototype pollution - use literal keys or `typed<T>()`" |
+| `memorio-__proto-assignment` | Error | `state.__proto__` or `state.constructor` or `state.prototype` anywhere | "Assignment to `__proto__`/`constructor`/`prototype` can cause prototype pollution - use `typed<T>()` for schema-safe state" |
+| `memorio-unencrypted-store` | Hint | `store.set('token', value)` without `store.config({ encryptionKey })` | "Token stored without encryption - consider `store.config({ encryptionKey })`" |
+| `memorio-sqlite-beta` | Information | `sqlite` import in production file | "sqlite is beta - API may change in minor releases" |
+
+## 7. React Flow component architecture
+
+```
+StoreGraphView (React Flow Canvas)
+├── NodeTypes: StoreNode, ContextNode, MemoryNode, SchemaNode, ReduxBridgeNode, TimelineNode
+├── EdgeTypes: default (arrow), SyncEdge (dashed, labeled)
+├── Controls: MiniMap, Controls (zoom), Background (grid)
+├── Toolbar: FilterToggle, TimelineToggle, RefreshButton
+└── Sidebar: NodeDetailsPanel (conditional)
+
+FilterToggle → filters by NodeKind and meta flags (beta, encrypted)
+TimelineToggle → swaps edges/nodes to timeline view for selected store
+```
+
+## 8. Message protocol (extension host ↔ webview)
+
+```ts
+type WebviewMessage =
+  | { type: 'graphSnapshot'; data: GraphSnapshot }
+  | { type: 'nodeSelected'; nodeId: string }
+  | { type: 'goToDefinition'; filePath: string; range: Range }
+  | { type: 'refreshRequested' }
+  | { type: 'filterChanged'; nodeKinds: NodeKind[] }
+
+type HostMessage =
+  | { type: 'webviewReady' }
+  | { type: 'definitionRequested'; filePath: string; range: Range }
+  | { type: 'filterChanged'; nodeKinds: NodeKind[] }
+  | { type: 'timelineToggle' }
+```
+
+## 9. Roadmap a fasi
+
+### Fase 1 - IntelliSense + Hover (2-3 developer-days)
+- `memorioCompletion.ts`: autocomplete for `state.*`, `store.*`, `memorio.memory.*`, etc.
+- `memorioHover.ts`: hover shows type + options + doc link
+- Snippets: `ctx-enc` (createContext with encryption), `schema-array` (registerSchema), `memory-sync` (configure with provider)
+- **No graph view yet** - can ship independently, provides immediate value
+
+### Fase 2 - Diagnostica (1-2 developer-days)
+- `DiagnosticGenerator.ts` + `rules.ts`
+- `memorio-__proto-assignment`, `memorio-prototype-pollution-risk`, `memorio-missing-store`, `memorio-include-obsolete-hint`
+- Integrates into the MemorioCallScanner from Fase 1
+- **No webview needed**
+
+### Fase 3 - Graph view statica (5-7 developer-days)
+- `GraphBuilder.ts` + `StoreGraphPanel.ts`
+- React Flow webview with store/context/memory/sqlite nodes, edge rendering (observes, isolate, bridges)
+- Basic sidebar details (layer, file, persisted, encrypted, beta)
+- Go-to-definition integration
+- **No timeline yet**
+
+### Fase 4 - Timeline undo/redo (3-4 developer-days)
+- Toggle button in webview toolbar
+- Timeline nodes from `trace()` output
+- Linear temporal view of snapshots/operations per selected store
+- **Requires timeline node type + TimelineNode component**
+
+### Fase 5 - Aggiornamento incrementale + performance (2-3 developer-days)
+- File-level cache (`cache.ts`)
+- Debounced re-analysis on save
+- Large file skipping (syntax-only mode for files >5000 lines)
+- `globalState` (VSCode Memento) layout persistence with `session` mode (no disk writes per design constraint)
+
+### Out of scope (future)
+- Remote sync provider connection (would require user's backend integration)
+- Runtime state inspection (would require injecting code into user's process - violates the "no runtime injection" constraint)
+- Export graph to image/PNG (nice-to-have, no core value)
+
+## 10. Constraints honored
+
+| Constraint | How met |
+|---|---|
+| No security/compliance claims in marketing | Diagnostics use technical descriptions ("may cause prototype pollution"), not "security layer" language |
+| Diagnostics declared as heuristic | Explicit ⚠️ at top of §6, rule docs say "AST pattern matching, not type-checker" |
+| No changes to memorio public API | All analyzer modules are read-only AST pattern matching; no imports from `memorio` |
+| Honest naming | "Store Graph View" (not "State Explorer"), "Dependency graph" only if the graph shows dependencies (which it does: observes → syncs → bridges) |
+| Cross-runtime support | Extension is Node.js-only (VSCode extension host), but documents the cross-platform support for the underlying library |
+| No runtime injection | Static analysis only - zero code executed from analyzed files |

package/markdown/LOGIC.md

@@ -0,0 +1,100 @@
+# `memorio.logic`
+
+> **Status:** IMPLEMENTED and VERIFIED — PHASE 0 PASS
+> **Scope:** Current public runtime contract; not a PHASE 1 roadmap
+
+`memorio.logic` records structured situation/action/outcome experiences, selects applicable
+precedents, derives simple recommendations, and reports measurements. It reuses acquired-knowledge
+primitives; it is not an autonomous reasoning engine, truth engine, causal graph, or replacement for
+AI reasoning.
+
+## Public API
+
+```ts
+import { logic, LogicEngine } from 'memorio'
+
+await logic.experience({
+  id: 'exp.locking-1',
+  situation: { symptom: 'a nested write bypassed the intended guard' },
+  action: { correction: 'apply the node-level guard' },
+  outcome: { result: 'the contract test passes' },
+  evidence: [{ id: 'locking-contract', source: 'test-suite' }],
+  applicability: { layer: 'logic', topic: 'locking' },
+  epistemicType: 'verified'
+})
+
+const precedents = await logic.precedents({
+  context: { layer: 'logic', topic: 'locking' }
+})
+```
+
+The PHASE 0 surface is:
+
+- `experience(opts): Promise<void>` — append an immutable experience claim.
+- `precedents(query): Promise<AcquiredClaim[]>` — return selected active claims.
+- `context(query): Promise<AcquiredContext>` — return selected claims plus repository version.
+- `measure(query): Promise<LogicMeasurement>` — report all active Logic claims, selected claims,
+  selected IDs, repository version, and the current process-wide temporal mutation count.
+- `learn(query): Promise<LogicRule[]>` — project selected experiences into rules. The recommendation
+  is the stored `outcome`; confidence is a fixed mapping from epistemic type, not learned statistics.
+- `stats(): Promise<{ experiences: number; version: number }>` — count repository-level active claims.
+- `clear(): Promise<void>` — delete only the writable `logic.mem` source.
+- `configure({ disabled })` — make the singleton a no-op while disabled.
+
+`logic` is a singleton instance of `LogicEngine`. It is available as a named module export and as
+`globalThis.memorio.logic`; explicit global installation also includes `globalThis.logic`.
+
+## Persistence and isolation
+
+In Node.js/Bun, Logic uses `.memorio/logic/logic.mem`. Acquired project experience uses
+`.memorio/project.mem`.
+
+These are intentionally separate `MemDirectoryKnowledgeRepository` instances rooted in different
+directories. Each discovers, combines, locks, versions, clears, validates IDs, and validates revision
+references only within its own repository. Consequently:
+
+- Logic does not discover or clear `project.mem`.
+- Project memory does not discover or clear `logic.mem`.
+- Claim-ID uniqueness and `refines`/`supersedes`/`retracts` references are repository-local.
+- Cross-repository revision chains and unified provenance are not implemented.
+
+This isolation is a current architectural boundary, not evidence that cross-repository composition
+exists. When no working-directory runtime is available, Logic uses an in-memory repository. Unlike
+acquired project memory, PHASE 0 Logic does not use the browser `store` fallback.
+
+## Selection and the `_all` correction
+
+Logic context selection uses the same exact structured applicability and most-specific-wins semantics
+as acquired memory. PHASE 0 initially added an `_all` selector sentinel so `stats()` and `measure()`
+could count all claims. Focused design verification found that it violated the selector invariant,
+could collide with a real applicability key, and still selected only maximum-specificity candidates.
+
+The sentinel was removed. `stats()` and the `total` field of `measure()` now load the Logic repository
+and count `activeClaims(state)` directly. A regression test covers mixed applicability specificity.
+The chronology is retained in project history; this document describes the corrected current state.
+
+```text
+initial Logic implementation
+-> contract tests pass
+-> focused design verification
+-> `_all` selector problem discovered
+-> HI + AI decision
+-> `_all` removed
+-> stats()/measure() use repository.load() + activeClaims()
+-> mixed-specificity regression verification
+-> PHASE 0 PASS
+```
+
+The regression uses three active claims with three, two, and one applicability keys. The corrected
+result is `stats().experiences === 3`; the rejected wildcard approach could incorrectly return `1`.
+
+## Verification boundary
+
+The PHASE 0 contract test verifies the singleton, API surface, global exposure, experience selection,
+revision, measurement, rule projection, stats, disabled behavior, clearing, repository isolation, and
+the mixed-specificity regression. This verifies mechanics, not the truth of stored experience.
+
+## Not implemented
+
+PHASE 0 does not implement semantic similarity, autonomous acquisition, autonomous truth evaluation,
+causal inference, cross-repository composition, identity/authority policy, trust scoring, or PHASE 1.