memorio 4.9.31 → 5.0.0

package/llms.txt

@@ -2,7 +2,7 @@
 
 ## Overview
 
-**Memorio** is a cross-platform state management library that provides reactive state, persistence, and observation capabilities with zero dependencies. It works in Node.js, Deno, browsers, and edge environments.
+**Memorio** is an application state intelligence runtime. It manages application state, remembers how it changed, understands causal relationships, enables deterministic replay, and can simulate the impact of future changes. It provides reactive state, persistence, and observation capabilities with zero dependencies. It works in Node.js, Deno, browsers, and edge environments.
 
 ```
 npm i memorio
@@ -26,8 +26,10 @@ Memorio provides 6 storage modules plus utilities:
 
 ## Quick Start
 
+Memorio does not expose APIs on `globalThis` by default. Use explicit named imports for normal application code:
+
 ```javascript
-import 'memorio'
+import { state, useObserver } from 'memorio'
 
 // Set reactive state
 state.user = { name: 'Sara', role: 'admin' }
@@ -40,6 +42,15 @@ useObserver(
 )
 ```
 
+```note
+To opt in to global access (state, store, session, cache, idb, sqlite, observer, useObserver on `globalThis`), use the explicit global entrypoint:
+
+```javascript
+import 'memorio/global'
+```
+
+This is independent of bundler environment detection (no `import.meta.env.DEV`, no `process.env.NODE_ENV` checks).
+
 ## API Reference
 
 ### `state` - Reactive State
@@ -238,7 +249,7 @@ observer.removeAll()
 Primary way to observe state changes in React components.
 
 ```jsx
-import 'memorio'
+import { useObserver, state } from 'memorio'
 import { useReducer } from 'react'
 
 function Counter() {
@@ -305,7 +316,7 @@ memorio.logger.exportLogs()   // JSON string of all history
 
 ## Platform Detection
 
-Access via `memorio.*` after `import 'memorio'`:
+Access via `memorio.*` after importing from `memorio`:
 
 ```javascript
 memorio.isBrowser()       // true in Chrome, Firefox, Safari
@@ -429,6 +440,63 @@ memorio.canRedo() // true
 
 ### `memorio.trace()` - Mutation Log
 
+Every mutation is recorded as a structured `Mutation` with a unique ID, HLC timestamp, operation, before/after values, source attribution, and optional transaction ID:
+
+```javascript
+memorio.enableHistory(true)
+state.user.name = 'Sara'
+
+const log = memorio.trace()
+// [{
+//   id: 'm_01h...', path: 'user.name', operation: 'set',
+//   before: undefined, after: 'Sara',
+//   timestamp: 1780000000, hlc: 'hlc:1780000000:00:abc1',
+//   action: 'set', newValue: 'Sara', previousValue: undefined,
+//   source: undefined, transactionId: undefined
+// }]
+```
+
+### Mutation Engine (Memorio 5)
+
+`memorio.mutate()` records a mutation with source attribution:
+
+```javascript
+import { memorio } from 'memorio'
+
+memorio.enableHistory(true)
+
+const m = memorio.mutate('state.user.role', 'admin', {
+  source: 'permissions.enableAdmin'
+})
+console.log(m.id)        // "m_01h4f2k7..."
+console.log(m.operation) // "set"
+console.log(m.before)    // undefined
+console.log(m.after)     // "admin"
+console.log(m.source)    // "permissions.enableAdmin"
+```
+
+Transactions group related mutations atomically:
+
+```javascript
+const tx = memorio.transaction('user.migration', 'Migrate to v2')
+
+state.user.role = 'admin'
+state.user.v2 = true
+
+memorio.commitTransaction()  // or memorio.abortTransaction() to roll back
+
+// Named imports for fine-grained control:
+import { beginTransaction, commitTransaction, abortTransaction, currentTransaction } from 'memorio'
+```
+
+Patch utilities convert mutations to RFC 6902-style patches for replay, sync, and simulation:
+
+```javascript
+import { mutationToPatch, diffToPatch, canMerge, mergePatches } from 'memorio'
+```
+
+### `memorio.trace()` - Mutation Log
+
 ```javascript
 memorio.trace()
 // [{ path, action, newValue, previousValue, timestamp }, ...]

package/markdown/AUDIT-REPORT.md

@@ -0,0 +1,135 @@
+> **Status:** Accepted
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: Security (NIST/OWASP/NSA), Performance, Reliability, Code Quality
+> **Standard**: NIST SP 800-53, OWASP ASVS, NSA Cybersecurity Guidelines
+>
+---
+# Audit Report - Memorio v4.9.5
+
+## 1. Security Audit
+
+### Findings
+
+| Severity | Issue | Status |
+|----------|-------|--------|
+| None | Secrets/credentials in source | ✅ Clean - all "token"/"secret" are in examples/test fixtures |
+| None | Dynamic code execution (`eval`, `new Function`) | ✅ Not present |
+| None | Prototype pollution (`__proto__`, `constructor.prototype`) | ✅ Not present |
+| None | XSS vectors (`innerHTML`, `document.write`) | ✅ Not present |
+| None | SQL injection (sqlite module) | ✅ Uses parameterized statements via sql.js `stmt.bind()` |
+| Low | `console.warn`/`console.error` used outside catch blocks | ⚠️ Present in `functions/state/index.ts` guard clauses (state locked/protected) |
+| None | Namespace isolation in memory system | ✅ Documented trust model with per-namespace storage keys |
+
+### Actions Taken
+- **Removed `__DEV__` references**: All bare `__DEV__` references removed from source code and documentation
+- **Updated comments**: Replaced `__DEV__` mentions in JSDoc comments with `DEV`/runtime detection references
+
+---
+
+## 2. Performance Audit
+
+### Findings
+
+| Issue | Impact | Status |
+|-------|--------|--------|
+| `wrapperCache` in `state/index.ts` uses `WeakMap` | ✅ No memory leak - GC cleans up orphaned wrappers |
+| `JSON.parse(JSON.stringify())` in 3 locations | Low - only for snapshot/list/inspect operations, not hot loops | ✅ Acceptable |
+| `setTimeout` in sqlite persistence | ✅ Async, doesn't block main thread |
+| No `console.log` in hot paths | ✅ All logging uses `console.debug` |
+
+### Actions Taken
+- **No performance changes needed**: Architecture is already optimized for the use case
+
+---
+
+## 3. Reliability Audit
+
+### Findings
+
+| Issue | Location | Risk | Status |
+|-------|----------|------|--------|
+| DevTools using `globalThis.state/store/session/cache` | `functions/devtools/index.ts` | High - fails when globals not initialized (prod mode) | ✅ Fixed |
+| `console.error` in non-catch contexts | `functions/state/index.ts:182,188,194,200` | Low - noisy console in strict mode | ⚠️ Deferred (UX choice) |
+
+### Actions Taken
+
+**DevTools module deduplication (critical fix)**:
+- Removed direct `globalThis.state/store/session/cache` access from `functions/devtools/index.ts`
+- Replaced with singleton access via private `globalThis` keys (`__memorio_state_instance__`, `__memorio_store_instance__`, `__memorio_session_instance__`, `__memorio_cache_instance__`)
+- These keys are the same ones used by the modules themselves for singleton deduplication
+- This also fixes a **circular import issue** that arose from naive direct imports (state → dispatch → ... → devtools cycle)
+- Access via private singleton keys is safe because they are set at module initialization, before `core/global.ts` runs
+- Updated 3 functions: `inspect()`, `stats()`, `exportData()`/`importData()`/`clear()`/`watch()`/`help()`
+- Removed emoji prefixes from console output for cleaner logs
+- Changed `console.error` to `console.debug` for consistency
+
+---
+
+## 4. Code Quality Audit
+
+### Findings
+
+| Issue | Status |
+|-------|--------|
+| Duplicate storage pattern in `store` and `session` | ✅ Pre-existing - same `_getPrefix/_prefixKey/_read/_write/_remove` pattern (acceptable) |
+| `console.warn` vs `console.debug` inconsistency in `state/index.ts` | ⚠️ Present - state lock/protected uses `console.error` |
+| JSDoc coverage on public functions | ✅ Complete |
+
+---
+
+## 5. Documentation Audit
+
+### Actions Taken
+- **Merged changelogs**: Combined `.project/CHANGELOG.md` (v4.9.5 detailed) into `.project/markdown/CHANGELOG.md`
+- **Updated version references**: Changed v3.0.2 → v4.9.5 throughout
+- **Updated stack**: Jest → vitest, `config/` → `core/`
+- **Removed `__DEV__` mentions**: All documentation comments updated
+- **Added "Module deduplication strategy"** section to `docs/README.md`
+- **Updated CHANGELOG** with v4.9.5 entry documenting all fixes
+
+---
+
+## 6. Lint & Build Verification
+
+```
+✅ oxlint: 0 warnings, 0 errors (60 files, 92 rules, 8 threads)
+✅ Production build: 0 __DEV__ references in dist/index.js and dist/index.cjs
+✅ Tests: 200 passed, 4 skipped, 1 todo (0 failures)
+✅ Files deployed to A:/Gitea/picla.app.examplepage/node_modules/memorio/
+```
+
+---
+
+## 7. Additional Code Quality Fixes
+
+| File | Issue | Fix |
+|------|-------|-----|
+| `functions/memory/journal.ts:62` | Unused `serialize` function | Removed |
+| `core/hlc.ts:83` | Unused `incoming` parameter | Renamed to `_incoming` |
+| `functions/memory/index.ts:553,556` | Unnecessary regex escapes `\.` | Changed to `.` |
+| `functions/devtools/index.ts` | Used `globalThis.state` instead of imports | Replaced with singleton keys |
+| `.oxlintrc.json` | Missing lint config | Created with ignore patterns + rule overrides |
+| All files | `__DEV__` references in comments | Removed/replaced |
+
+---
+
+## Summary of Files Modified
+
+| File | Change |
+|------|--------|
+| `core/env.ts` | Removed `__DEV__` from comments |
+| `core/global.ts` | Updated comments: `__DEV__` → runtime detection |
+| `functions/devtools/index.ts` | Fixed circular imports + globalThis access; removed `__DEV__`; use singleton keys |
+| `functions/memory/journal.ts` | Removed unused `serialize` function |
+| `core/hlc.ts` | Fixed unused parameter `_incoming` |
+| `functions/memory/index.ts` | Fixed regex escapes |
+| `functions/devtools/index.ts` | Fixed circular imports + globalThis access; use singleton keys |
+| `tests/vitest/vitest.config.ts` | Removed `__DEV__` from comments |
+| `types/env.d.ts` | Removed `__DEV__` from comments |
+| `.oxlintrc.json` | New lint configuration |
+| `tsup.config.ts` | Disabled minification + enabled sourcemaps to avoid socket.dev false positives |
+| `.project/markdown/CHANGELOG.md` | Merged changelogs, added v4.9.5 entry |
+| `.project/markdown/PROJECT.md` | Updated version, stack, structure (was memorio.md) |
+| `docs/README.md` | Added module deduplication strategy section |
+| `tests/scripts/update-node-modules-memorio.cjs` | New deploy script for user app |

package/markdown/CACHE.md

@@ -0,0 +1,100 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Cache - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Cache provides in-memory storage with a simple API. Data is lost on page refresh or process restart.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import { cache } from 'memorio';
+```
+
+> **Classic `import`**: `cache` is also available via the global entrypoint.
+> `import 'memorio/global'` exposes the same instance as `globalThis.cache`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save data
+cache.set('username', 'Mario');
+cache.set('score', 1500);
+
+// Read data
+console.debug(cache.get('username')); // "Mario"
+console.debug(cache.get('score'));    // 1500
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Store objects
+cache.set('user', { name: 'Luigi', level: 5 });
+const user = cache.get('user');
+console.debug(user.name); // "Luigi"
+
+// Remove single item
+cache.remove('username');
+
+// Clear all cache
+cache.removeAll();
+```
+
+---
+
+## API Reference
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `cache.get(name)` | `name: string` | `any` | Get value from cache |
+| `cache.set(name, value)` | `name: string, value: any` | `void` | Save value to cache |
+| `cache.remove(name)` | `name: string` | `boolean` | Remove single item |
+| `cache.removeAll()` | `none` | `boolean` | Clear all cache |
+
+---
+
+## Storage Comparison
+
+| Feature | Cache | Store | Session | IDB |
+|---------|-------|-------|---------|-----|
+| Platform Support | All (universal) | Browser/Edge | Browser/Edge | Browser only |
+| Lifetime | Until refresh | Forever | Until tab closes | Forever |
+| Capacity | Unlimited | ~5-10 MB | ~5-10 MB | 50+ MB |
+| Use case | Temporary data | User preferences | Auth tokens | Large data |
+
+---
+
+## Platform Support
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| Browser | ✅ Full | In-memory, lost on refresh |
+| Node.js | ✅ Full | In-memory, lost on restart |
+| Deno | ✅ Full | In-memory, lost on restart |
+| Edge Workers | ✅ Full | In-memory, lost on function cold start |
+
+---
+
+## Best Practices
+
+1. Use for temporary data that doesn't need persistence
+2. Great for computed values or API response caching
+3. Data is lost on page refresh - don't use for important data
+4. Clear with `cache.removeAll()` when no longer needed

package/markdown/CHANGELOG.md

@@ -0,0 +1,243 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team, BigLogic
+> **Scope**: Project Documentation
+> **Standard**: Memorio Documentation Standard v5
+>
+---
+# Changelog - Memorio
+
+All notable changes to this project will be documented in this file.
+
+---
+
+## Unreleased - Module Duplication Fix & Architecture Cleanup
+
+### 🐛 Bug Fixes
+
+- **Module duplication / state reset**: Fixed issue where importing memorio via different paths (ESM `dist/index.js`, CJS `index.cjs`, package name `memorio`, absolute file path) created separate module instances, each with its own empty proxy. This caused `globalThis.state` to be overwritten with a fresh empty proxy on second import, resetting all state data.
+  - All modules (`state`, `store`, `session`, `cache`) now use private `globalThis` singleton keys (`__memorio_state_instance__`, `__memorio_store_instance__`, `__memorio_session_instance__`, `__memorio_cache_instance__`) to guarantee a single shared instance across all import paths.
+  - `memorio.global()` in `core/global.ts` now guards with `if (!(key in globalThis))` to prevent overwriting existing dev globals - protecting against module duplication resetting state.
+- **Removed `__DEV__` build-time constant**: Replaced all bare `__DEV__` references with `DEV`/`PROD` from `core/env.ts` (runtime detection via `process.env.NODE_ENV`). Eliminates `ReferenceError: __DEV__ is not defined` in browser environments without bundler `define` config. Production builds now have **0** `__DEV__` references.
+
+### 🔧 Code Refactoring
+
+- **Script organization**: Moved debug/verification scripts from root to `tests/scripts/`:
+  - `check-dev-mode.mjs` → `tests/scripts/check-dev-mode.mjs`
+  - `update-node-modules-memorio.cjs` → `tests/scripts/update-node-modules-memorio.cjs`
+  - `test-state-persist.ts` → `tests/scripts/test-state-persist.ts`
+  - `tests/test-nav.mjs` → `tests/playwright/test-nav.mjs`
+
+### 📝 Documentation Updates
+
+- `docs/README.md`: Documented the singleton pattern and module deduplication strategy in the "How it works" section.
+
+### 🧹 Code Quality
+
+- **Removed dead code**: `serialize` function in `functions/memory/journal.ts` (unused)
+- **Fixed unused parameter**: `tick(incoming)` in `core/hlc.ts` renamed to `tick(_incoming)`
+- **Fixed regex escapes**: Removed unnecessary `\.` escapes in `functions/memory/index.ts` path regexes
+- **DevTools reliability**: Replaced `globalThis.state/store/session/cache` access with singleton instance keys (`__memorio_*_instance__`) to prevent `ReferenceError` in production and avoid circular imports
+- **Console consistency**: Changed `console.error` to `console.debug` in devtools error handling, removed emoji prefixes
+
+### 🔒 Security - Supply Chain
+
+- **Removed hardcoded CDN URL**: `functions/sqlite/tools/db.support.ts` no longer references `https://cdn.jsdelivr.net/npm/sql.js/dist/` hardcoded. SQLite now requires explicit loader configuration via `sqlite.config({ loader, scriptUrl })` or fails gracefully with a clear error message.
+- **Eliminated external script injection risk**: No external URL strings in the bundle - prevents socket.dev supply-chain warnings for "URL string literals"
+- **Added `browser` field** in `package.json` for explicit browser/Node resolution
+- **Added `.oxlintrc.json`**: Lint configuration with ignore patterns and rule overrides
+- **tsup config**: Disabled minification (`minifyWhitespace`, `minifyIdentifiers`, `minifySyntax` → `false`), enabled sourcemaps (`sourcemap: true`) and `keepNames: true` to produce readable bundles and eliminate socket.dev "minified code" false positives
+
+---
+
+## v4.9.0 - 2026-09-06
+
+### 🐛 Bug Fixes
+
+- **Module duplication / state reset across import paths**: Fixed issue where importing memorio via different paths (ESM `dist/index.js`, CJS `index.cjs`, package name `memorio`, absolute file path) created separate module instances, each with its own empty proxy. This caused `globalThis.state` to be overwritten with a fresh empty proxy on second import, resetting all state data.
+  - All modules (`state`, `store`, `session`, `cache`) now use private `globalThis` singleton keys (`__memorio_state_instance__`, `__memorio_store_instance__`, `__memorio_session_instance__`, `__memorio_cache_instance__`) to guarantee a single shared instance across all import paths.
+  - `memorio.global()` in `core/global.ts` now guards with `if (!(key in globalThis))` to prevent overwriting existing dev globals - protecting against module duplication resetting state.
+
+### 🔧 Code Refactoring
+
+- **Removed `__DEV__` build-time constant**: Replaced all bare `__DEV__` references with `DEV`/`PROD` from `core/env.ts` (runtime detection via `process.env.NODE_ENV`). Eliminates `ReferenceError: __DEV__ is not defined` in browser environments without bundler `define` config. Production builds verified to have **0** `__DEV__` references in both ESM and CJS outputs.
+  - `core/env.ts`: Rewrote from `__DEV__`-based to pure runtime detection. `DEV` = `process.env.NODE_ENV !== 'production'` (or `true` in browser without `process` polyfill).
+  - All `if (__DEV__)` guards across `core/global.ts`, `functions/state/`, `functions/store/`, `functions/session/`, `functions/cache/`, `functions/idb/`, `functions/sqlite/`, `functions/observer/`, `functions/useObserver/`, `functions/message/`, `functions/logger/`, and `functions/devtools/` now use `if (DEV)` with an explicit `import { DEV } from '../../core/env'`.
+  - `core/global.ts`: `memorio.global()` auto-call is gated behind `if (isDev)` (sourced from `DEV`), not `if (__DEV__)`.
+  - `tsup.config.ts`: Removed `'__DEV__'` from `define`. Only `process.env.NODE_ENV` is defined.
+  - `vitest.config.ts`: Removed `__DEV__: true` define. Uses `'process.env.NODE_ENV': '"development"'` instead.
+  - `types/env.d.ts`: Removed `declare const __DEV__: boolean`. Documents runtime `DEV`/`PROD` imports from `core/env.ts`.
+
+### ✨ API Additions
+
+- **`memorio.env.isDev` / `memorio.env.isProd`**: Runtime environment detection properties on the `memorio` namespace. Returns `true`/`false` based on `process.env.NODE_ENV` - no build-time `__DEV__` define required.
+- **`memorio.global()` method**: Manually sets dev-only globals (`state`, `store`, `session`, `cache`, `idb`, `sqlite`, `observer`, `useObserver`) on `globalThis`. Auto-called in development; idempotent and safe to call multiple times.
+
+### 🆕 API - Typed Stores & Schema Validation
+
+- **Typed Stores**: `memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, providing compile-time type safety, IntelliSense autocomplete, and static property checking on state access and mutation. Zero runtime cost - the returned object is the exact same Proxy as `globalThis.state`.
+- **Schema Validation**: `memorio.registerSchema(path, schema)` registers runtime validators for state paths. Writes that violate a registered schema are rejected before storage. Supports type checking, required fields, min/max, regex patterns, enums, nested property schemas, and custom validator functions. Includes `memorio.validate(path, value)`, `memorio.unregisterSchema(path)`, and `memorio.listSchemas()`.
+
+### 📝 Documentation Updates
+
+- `docs/README.md`: Added "Typed Stores" and "Schema Validation" sections. Updated "Is this for you?" to reference the new type-safe options.
+- `docs/llms.txt`: Added typed stores and schema validation sections.
+- `docs/SUMMARY.md`: Added links to new doc pages.
+
+---
+
+## v4.6.1 (Security Patch) - 2026-08-14 - CRITICAL Security Fix
+
+### 🔐 Security NOTICE (v4.6.0)
+
+**CRITICAL**: A Gitea Personal Access Token was accidentally committed to `.npmrc` in v4.6.0
+
+**Affected**: `v4.6.0` tag and all builds from that version
+
+**Action Required**:
+- **IMMEDIATE**: Revoke ALL tokens on Gitea Packages by admin access
+- **GENERATE**: Create new PAT with scope `write:package` only
+- **CONFIGURE**: Add as secret `PAT` in GitHub Actions or Gitea Actions
+- **UPGRADE**: Use v4.6.1 where the token is replaced with `${PAT}` environment variable
+
+The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed in v4.6.1.
+
+### 🐛 Bug Fixes
+
+- **SECURITY**: Removed hardcoded Gitea PAT from `.npmrc` (exposed token remediated)
+- Replaced with environment variable `${PAT}` for secure authentication
+
+### 📝 Documentation Updates
+
+- `.npmrc`: Token replaced with environment variable reference
+- `.gitea/workflows/npm.yml`: Configured to use secrets `GITEA_USER` and `PAT`
+
+---
+
+## v4.6.0 (Previous - SECURITY ISSUE) - 2026-08-13 - Refactoring & Documentation
+
+**⚠️ WARNING**: This version had a hardcoded PAT token that was later remediated in v4.6.1**
+
+### 🐛 Bug Fixes
+
+- Fixed circular import in `idb/index.ts` → `core/global`
+- Fixed dead `globalThis._propertyAccessLog` reference in `observer`
+- Fixed `dispatch.remove(f)` tuple bug in `functions/dispatch.ts`
+- Fixed `logger.isDebugEnabled` using wrong module reference
+- Removed dead `propertyAccessLog` / `pushPropertyAccess` from `core/internal.ts`
+- Removed duplicate path-tracking block in `state` get handler
+- Removed redundant `?? key` fallback in `state` set handler
+
+### 🔧 Code Refactoring
+
+- **Self-contained modules**: All modules now work independently without internal `globalThis.memorio.*` reads/writes
+- **Module-local state**: Created `core/internal.ts` for module-local singletons
+- **Bootstrap-only global**: `core/global.ts` now only publishes to `globalThis.memorio` at initialization
+- **Removed dead code**: `core/constructor.ts` deleted (unused)
+- **Extracted helpers**: `_read`/`_write`/`_remove` in `store` and `session` to eliminate duplication
+- **Fixed circular imports**: `dispatch` → `observer` via `globalThis.events`
+
+### 📝 Documentation Updates
+
+- `docs/README.md`: Added Classic `import { state } from 'memorio'` section, improved badges layout, enhanced "Why memorio?" comparison table
+- `docs/markdown/STORE.md`: Added classic import note
+- `docs/markdown/IMPORT.md`: New file for named export guide
+- `docs/SUMMARY.md`: Updated to include `IMPORT.md`
+- `README.md`: Badge corrections, header cleanup, removed unverified bundle size claims
+
+### 🆕 GitHub Actions / Gitea Workflows
+
+- Added `.gitea/workflows/npm.yml` for automatic npm package publishing to Gitea Packages on `v*` tags
+- Requires `GITEA_USER` and `PAT` secrets
+
+### 🧪 Tests
+
+- **Result: 9 suites · 101 passed · 4 skipped · 1 todo**
+- All lint and typecheck clean
+
+---
+
+## v3.0.2 - 2026-05-19 - Bug Fix, Security & API Expansion
+
+### 🐛 Bug Fixes
+
+- Removed dead code: `buildPathTracker` from `functions/state/index.ts` (unused Proxy builder, exported nowhere)
+- Removed double `delete` in state `removeAll` handler (redundant null-check + delete on same key)
+- Removed unbound `globalThis.state` reference in state init (would throw `ReferenceError` in strict mode)
+- Removed `Object.freeze(observer)` referencing undeclared variable (`ReferenceError` on module load)
+- Removed `confirm()` synchronous blocking call from `idb.db.delete` (library must not block main thread)
+
+### 🔒 Security Improvements
+
+- Removed `esbuild-sass-plugin` and `esbuild-scss-modules-plugin` from `devDependencies` (unnecessary for a library with no styles)
+- Removed `injectStyle: true`, `sassPlugin()` and `.css` loader from `tsup.config.ts`
+- Deleted `tsup.plugin.injectCss.ts` (code injection vector completely removed from build pipeline)
+- `console.error`/`console.warn` → `console.debug` in `devtools` and `idb` error handlers (consistent debug-only logging policy)
+- `store.set()` now blocks function values instead of silently logging and continuing
+- All `PRIVATE License` headers in `functions/idb/` replaced with `MIT License`
+
+### 🔧 Code Quality
+
+- Added JSDoc to `observerFunction` in `functions/observer/index.ts`
+- Added JSDoc to `cache` global in `functions/cache/index.ts`
+- `lint` and `tsc` pass clean - 0 vulnerabilities from `npm audit`
+
+### 🆕 API - New in 3.0.2
+
+| Function | Description |
+|----------|-------------|
+| `memorio.isBrowser()` | Returns `true` when running in a browser |
+| `memorio.isNode()` | Returns `true` when running in Node.js |
+| `memorio.isDeno()` | Returns `true` when running in Deno |
+| `memorio.isEdge()` | Returns `true` in Cloudflare Workers, Vercel Edge, etc. |
+| `memorio.getCapabilities()` | Full capabilities object (`platform`, `hasLocalStorage`, `hasIndexedDB`, …) |
+| `memorio.createContext(name?)` | Create multi-tenant isolated context |
+| `memorio.listContexts()` | List all active isolated contexts |
+| `memorio.deleteContext(id)` | Delete isolated context by ID |
+| `memorio.isolate(name?)` | Shorthand alias for `createContext` |
+
+### 🧪 Tests
+- **Result: 8 suites · 95 passed · 3 skipped · 0 failed**
+
+### 🗑️ Dependency Changes
+
+| Removed | Reason |
+|---------|--------|
+| `esbuild-sass-plugin@3.7.0` | No SCSS in a library |
+| `esbuild-scss-modules-plugin@1.1.1` | No SCSS in a library |
+| 36 transitive packages | Removed from `node_modules` |
+
+### 📝 Documentation Updates
+
+- `docs/README.md`: replaced `console.debug` with `console.debug` in usage examples; fixed `esbuild` badge → `tsup`
+- `.github/CHANGELOG.md`: restructured with fix / security / changed sections
+- `.github/HISTORY.md`: complete rewrite through v3.0.2
+- `.github/SECURITY.md`: NIST/NSA standard + OWASP Top 10 mapping
+- `.github/CITATION.cff`: license PRIVATE → MIT to match `package.json`
+- `.project/*`: all context documents updated to v3.0.2
+
+---
+
+## v2.9.0 - 2026-05-13
+
+### Added
+- DevTools - `memorio.devtools.inspect()`, `stats()`, `exportData()`
+- Logger with full history, stats and export
+- Platform detection (`isBrowser`, `isNode`, `isDeno`, `isEdge`, `getCapabilities`)
+- Session isolation via `crypto.randomUUID()`
+
+### Changed
+- Updated dependencies to latest versions
+- Improved cross-platform support (Deno, Edge Workers, Node.js)
+
+### Security
+- Secure random session IDs replaced `Math.random()`
+- Key validation (max 512 chars + character whitelist)
+
+---
+
+## v2.5.0 - 2026-02-17
+
+- Initial release of memorio (state, store, session, cache, idb)
+- Observer pattern (`observer`)
+- `useObserver` React hook