v1.2.0 — audit-driven release: withTransaction, JsonStore, migrate CLI, tool catalogue

The audit-driven release

An external code-and-architecture review of cortex-engine surfaced three credible critiques: missing concurrency primitives, no path between storage backends, and 27+ MCP tools competing for an LLM's attention with no disambiguation guidance. This release addresses all three as parallel implementation tracks, plus a fourth track that landed mid-flight when a user reported that CLI subcommands were silently dropping the agent namespace.

Added

• CortexStore.withTransaction(fn) — backend-native atomic-write primitive for composing multi-step writes. SQLite uses manual BEGIN IMMEDIATE / COMMIT / ROLLBACK with a per-store Promise-chained mutex (better-sqlite3's own db.transaction rejects Promise returns and does not survive await suspensions). Firestore wraps runTransaction with a FirestoreTxnProxy routing writes through the transaction handle. Full contract in docs/concurrency.md.
• CortexStore.upsertMemory(...) and siblings for Observation, Edge, OpsEntry, Signal, BeliefEntry — ID-preserving variants of put* for migration and restore. Implemented in SQLite, Firestore, JSON, and ScopedStore.
• CortexStore.getCapabilities() — { schemaVersion, embeddingDimension, categories, namespace, backend } snapshot used by migrate to refuse incompatible source/destination pairs before mutating data.
• JsonCortexStore — a third storage backend backed by a single JSON file with atomic temp+rename persistence. Intended for backup, restore, and migration staging — not a production server-side store.
• fozikio migrate --from <url> --to <url> — new CLI command that clones data between any pair of supported backends. Supports --namespace, --rename-namespace, --resume, --verify, --dry-run, --allow-merge, --batch-size. Idempotent (upsert-by-ID), checkpointed (.cortex-migrate-state.json), fails loudly on schema mismatch.
• fozikio tools — new CLI for browsing the cognitive tool catalogue by category.
• GET /tools and GET /tools/:name REST endpoints returning structured ToolMetadata.
• ToolDefinition.category + whenToUse + doNotUse — typed metadata on every tool. The MCP ListTools response composes these into the description string so the LLM has explicit disambiguation guidance.
• docs/concurrency.md, docs/tools-reference.md (auto-generated, 57 tools by category, regenerable via npm run docs:tools), docs/storage-backends.md.

Changed

• SQLite busy_timeout = 5000 is now set immediately after journal_mode = WAL. Concurrent writers ride out checkpoint contention for up to 5 seconds before surfacing SQLITE_BUSY.
• Multi-step write paths use withTransaction in cognition.ts, believe.ts, forget.ts, and observe.ts. A mid-sequence failure during dream consolidation no longer leaves orphan memories, edges, or unprocessed observations.
• All 57 tool descriptions rewritten to a consistent quality bar with whenToUse / doNotUse for disambiguation.
• wonder and speculate salience schema corrected from 1-10 (default: 5) to 0.0-1.0 (default: 0.5).

Fixed

• CLI subcommands no longer drop the agent namespace. fozikio health, vitals, anomalies, maintain fix, report, digest, and wander now resolve via src/bin/namespace-resolver.ts, honouring --namespace, --agent, then config default.
• Orphan-memory window during high-salience observation promotion — observe.ts wraps putMemory + markObservationProcessed in a transaction.
• Audit-trail gap during forget — forget.ts wraps updateMemory + putBelief.
• Confidence/definition split in hindsight review — cognition.ts:hindsightReview lands both in a single transaction.

Internal

• 73 new tests across six files; total suite is now 110 tests.

Note: A regression in this release's CLI namespace resolution was fixed in v1.2.1. If you set collections_prefix ending in _, upgrade to v1.2.1.

Full Changelog: v1.1.1...v1.2.0