mumpix 1.0.19 → 1.0.29

package/CHANGELOG.md

@@ -1,16 +1,28 @@
 # Changelog
 
-## 1.0.19 - 2026-04-13
-
-### Internal & Sync
-- Synchronized latest temporal engine and operator scripts from core module into the package tree.
-- Configured embedded GGUF agent context window ceilings (8K) to prevent VRAM memory allocation conflicts with local LLMs (e.g., `mumpix-mlc-llm`).
-
-## 1.0.18 - 2026-03-30
-- General performance and sync updates
-
-## 1.0.17 - 2026-03-24
-- Core temporal sync patches
+## 1.0.29 - 2026-06-14
+
+### Production package
+- Removed benchmark harnesses and dated benchmark artifacts from the npm package allowlist so production installs only include the runtime library, CLI, examples, scripts, README, changelog, and license.
+- Kept the pure-code vector retrieval optimization in the production runtime: packed `Float32Array` vector storage, lazy index construction, and metadata equality candidate narrowing before exact cosine scoring.
+- Preserved the public vector sidecar API while improving domain-scoped retrieval performance for embedders using MumpixDB as a general-purpose AI memory store.
+
+## 1.0.28 - 2026-06-14
+
+### Performance and retrieval
+- Promoted the pure-code MumpixDB recall update into the bundled runtime package.
+- Added persistent inverted-index recall candidates with hash re-verification, preserving the existing trust boundary while avoiding full scans.
+- Added WAL writer policy support for coalesced eventual-mode flushes while keeping strict and verified durability paths on per-record fsync semantics.
+- Added `rememberAll()` batch persistence and index maintenance so large promotion bursts do not require per-record main-file rewrites.
+- Exported `WalWriter` and `InvertedIndex` from the package entrypoint for runtime diagnostics and tests.
+
+### Benchmark record
+- Added a scale benchmark covering write throughput, randomized reads, reopen reads, and mixed read/write pressure.
+- At 100k records, indexed retrieval measured about 24ms p95 on reopen versus about 631ms p95 for full scan.
+- Under a 5k concurrent-promotion burst, indexed retrieval stayed under 50ms p95 while full scan was about 1.29s p95.
+- Reopen p95 tracked hot p95, confirming the index is persisted and reused after load instead of acting as an in-process cache.
+- Added a pgvector RLP retrieval comparison harness that measures domain-scoped vector retrieval against an independent exact flat cosine oracle.
+- Documented MumpixDB vector retrieval as exact flat cosine today, pgvector exact scan as the default peer, pgvector HNSW as an explicit opt-in approximate mode, and FAISS-flat as the optional million-scale oracle.
 
 ## 1.0.11 - 2026-03-03
 
@@ -28,7 +40,24 @@
 - Clarified that `strict`/`verified` are tier-gated capabilities (SDK and CLI).
 - Added `verify:claims` usage to the examples section.
 
-## Unreleased
+## 1.0.22 - 2026-06-12
+
+### Truth and verification
+- Tightened README claims to match implementation exactly.
+- Clarified local recall as exact substring, TF-IDF recall, and optional custom embedding recall.
+- Clarified mandatory runtime usage sync fields and local ML-DSA event verification payloads.
+- Fixed `npm run verify:claims` so it uses a writable local Mumpix config directory during tests.
+
+## 1.0.21 - 2026-06-12
+
+### Publish hardening
+- Prepared the npm package above the published `1.0.20` line.
+- Kept install side effects out of `npm install`; account linking now happens through explicit CLI auth commands.
+- Kept runtime usage sync mandatory for billing reconciliation and license enforcement, with local queuing for failed sends.
+- Added ML-DSA-44 device identities, signed usage events, and hash-chain continuity for air-gapped reconciliation.
+- Added `mumpix auth device-id` for device-bound license issuance.
+- Tightened package files so generated `.mumpix` artifacts are not included in npm tarballs.
+- Updated smoke examples to await `Mumpix.open(...)` and run in free `eventual` mode by default.
 
 ### Licensing (offline/air-gapped)
 - Added monthly tier capability mapping for paid durability modes (`eventual`, `strict`) while active.
@@ -41,8 +70,7 @@
 - Added local account auth state support in `src/core/auth.js`.
 - Added CLI auth commands: `mumpix auth login|status|logout`.
 - Added automatic local-license loading in `MumpixDB.open()` when `licenseKey` is not passed explicitly.
-- Added install-time auth script (`postinstall`) that prompts for account sign-in in interactive terminals.
-- Added browser-open device flow on install; skip path remains `eventual` only.
+- Added explicit device login flow through `mumpix auth login`; free installs remain in `eventual` mode until linked.
 
 ## 1.0.9 - 2026-03-02
 

package/README.md

@@ -32,9 +32,9 @@ MumpixDB gives you:
 
 - local-first storage in a `.mumpix` file
 - append-oriented durable state
-- strict and verified execution modes
+- license-gated strict and verified execution modes
 - replayable memory and audit surfaces
-- semantic recall and exact recall
+- exact substring recall, local TF-IDF recall, and optional custom embedding recall
 - a structured API for long-running assistants, workflows, and applications
 
 ## Quickstart
@@ -77,7 +77,8 @@ Options:
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `consistency` | `string` | `'eventual'` | `'eventual'`, `'strict'`, or `'verified'` |
-| `embedFn` | `async function` | — | Custom embedding function for semantic recall |
+| `embedFn` | `async function` | — | Custom embedding function for embedding-based recall |
+| `telemetry` | `boolean` | `false` | Opt in to signed license heartbeat telemetry for verified licenses |
 
 ### Core methods
 
@@ -158,6 +159,72 @@ Temporal records support scoped metadata on write:
 - `source`
 - `ts`
 
+### Behavioral Reasoning Primitives
+
+The package includes the BRP, RLP, and computational-collapse utilities from the MumpixDB papers as built-in modules. They are pure local APIs and do not add another npm package.
+
+```js
+const { brp, rlp, collapse } = require('mumpix');
+
+const gene = brp.normalizeBRP({
+  domain: 'browser',
+  trigger_signature: 'login page asks for workspace slug',
+  executable_payload: {
+    intent: 'DO',
+    sequence: [
+      { verb: 'input-text', args: { selector: '#workspace', value: 'acme' } },
+      { verb: 'click-element', args: { selector: 'button[type=submit]' } },
+    ],
+  },
+});
+
+const boundary = rlp.validateActionBoundary(gene);
+const economics = collapse.analyzeCollapse({
+  stages: [
+    { name: 'INDEX', token_cost: 200 },
+    { name: 'SCAN', token_cost: 2400 },
+    { name: 'DEBATE', token_cost: 7200 },
+    { name: 'EXECUTE', token_cost: 2050 },
+  ],
+  retrievalCost: 150,
+  promotionCost: 35550,
+  hits: 3,
+});
+
+console.log(gene.payload_type); // DO
+console.log(boundary.ok); // true
+console.log(economics.savingsPerHit); // 11700
+```
+
+Available BRP APIs:
+
+- `brp.normalizeBRP(candidate)`
+- `brp.validateBRP(candidate)`
+- `brp.validatePayload(payload)`
+- `brp.parseExecutablePayload(payload)`
+- `brp.updateSplitConfidence(brp, event)`
+- `brp.transitionStatus(brp, status, reason)`
+- `brp.structuralPrefilter(brps, query)`
+- `brp.twoStageMatch(brps, query, { k })`
+- `brp.VerbRegistry`
+
+Available RLP APIs:
+
+- `rlp.REQUIRED_MECHANISMS`
+- `rlp.FAILURE_MODES`
+- `rlp.ARCHITECTURAL_LAWS`
+- `rlp.gap(numberOrId)`
+- `rlp.validateActionBoundary(record)`
+- `rlp.mechanismChecklist(system)`
+
+Available computational-collapse APIs:
+
+- `collapse.graphCost(stages)`
+- `collapse.collapseSavings(stages, opts)`
+- `collapse.breakEvenReuseThreshold(promotionCost, cycleCost)`
+- `collapse.beta(promotionCost, cycleCost)`
+- `collapse.analyzeCollapse(input)`
+
 ### Consistency modes
 
 | Mode | Behavior | Use case |
@@ -166,6 +233,43 @@ Temporal records support scoped metadata on write:
 | `strict` | stronger durability path | production agents and application state |
 | `verified` | durability + audit surfaces | regulated, auditable, or compliance-heavy workloads |
 
+### Upgrades, licenses, and billing
+
+Free installs run in `eventual` mode. Users upgrade by linking an account or installing a signed license:
+
+```bash
+mumpix auth login
+mumpix auth login --token=<account-token>
+mumpix auth login --license=<signed-license-key>
+mumpix auth status
+mumpix auth device-id
+```
+
+The account backend exchanges an authenticated user session or account token for a signed license key. The package stores that license locally in the user's Mumpix config directory and validates it before allowing paid modes.
+
+Paid monthly licenses should be issued as short leases. The recommended policy is:
+
+- `monthly`, `developer`, `standard`, or `teams` unlock `strict`
+- `compliance`, `enterprise`, `government`, `verified`, or `pro` unlock `verified`
+- monthly leases expire and refresh through the account backend
+- canceled or unpaid subscriptions stop receiving refreshed leases, so paid modes downgrade or block after expiry
+
+License telemetry is opt-in and is used only as a signed license-verification heartbeat. By default, opening and closing a database performs no telemetry network call. To allow license heartbeat telemetry for a verified signed license, pass `telemetry: true` to `Mumpix.open()` or set `MUMPIX_TELEMETRY=1`. Free or unlicensed use stays local even when telemetry is enabled. When a verified license is present and telemetry is enabled, Mumpix sends account tier, machine/platform metadata, database stats, timestamp, the license fingerprint, and the license key transport header to the Mumpix usage endpoint on database close. Database filesystem paths are not included in telemetry events. If the endpoint is temporarily unavailable, license heartbeat events are queued locally and retried on later opted-in closes. Billing state should remain server-side in the account/subscription system; license telemetry is a reconciliation signal, not the source of truth for customer entitlement.
+
+For air-gapped installs, Mumpix creates a local ML-DSA-44 device identity. Usage events are signed with that device key and linked in a hash chain before being queued or uploaded. The event payload includes the device public key, signature, event hash, and previous hash so a reconciliation service can verify device signature, event hash, and chain continuity when the system reconnects. License issuers can bind a lease to a device by including the device public-key fingerprint from `mumpix auth device-id`.
+
+This is tamper-evident hardening for editable JavaScript packages: it makes gaps, edits, and device changes visible during reconciliation without adding cryptographic work to normal read/write paths.
+
+### Release hardening
+
+Published builds can be staged with build-time obfuscation:
+
+```bash
+npm run release:pack:obfuscated
+```
+
+This creates `.release/obfuscated` and packs from that staged tree. Runtime files under `src/` and `bin/` are minified and identifier-mangled with Terser, while examples and tests remain readable. The transform avoids control-flow flattening, eval wrappers, string-array indirection, and runtime loaders, so the package still runs as normal Node.js code with no runtime obfuscation dependency.
+
 ### Verified mode methods
 
 ```js
@@ -178,13 +282,13 @@ await db.exportAudit();
 
 ## Developer SDK
 
-This package also includes a developer client for Mumpix-backed services.
+This package also includes a small HTTP client for Mumpix-compatible services that expose the endpoints listed below.
 
 ```js
 const { MumpixDevClient } = require('mumpix');
 
 const client = new MumpixDevClient({
-  baseUrl: 'https://mumpixdb.com/benchmark'
+  baseUrl: 'http://127.0.0.1:3012'
 });
 
 const health = await client.health();
@@ -212,10 +316,83 @@ Available client methods:
 
 ## Integrations
 
-This package includes adapters for:
+This package includes two integration layers:
+
+- official peer-backed subclasses for LangChain and LlamaIndex
+- zero-dependency compatibility adapters with LangChain/LlamaIndex-shaped methods
+
+For official subclassing, install the optional peer package you need:
+
+```bash
+npm install mumpix @langchain/core
+npm install mumpix llamaindex
+```
+
+Official LangChain exports:
+
+```js
+const {
+  MumpixLangChainVectorStore,
+  MumpixLangChainRetriever,
+  MumpixLangChainMemory,
+} = require('mumpix/src/integrations/langchain-official');
+```
+
+These classes subclass LangChain's `VectorStore`, `BaseRetriever`, and `BaseMemory` from `@langchain/core`. The vector store persists embeddings in a `.vectors.json` sidecar next to the `.mumpix` file and supports `addDocuments`, `addVectors`, `addTexts`, `delete`, `similaritySearch`, `similaritySearchWithScore`, `similaritySearchVectorWithScore`, `maxMarginalRelevanceSearch`, and `save`.
+
+Official LlamaIndex exports:
+
+```js
+const {
+  MumpixLlamaIndexVectorStore,
+  MumpixLlamaIndexRetriever,
+} = require('mumpix/src/integrations/llamaindex-official');
+```
+
+These classes subclass LlamaIndex's `BaseVectorStore` and `BaseRetriever`. The vector store persists embeddings in the same `.vectors.json` sidecar and supports `client`, `get`, `add`, `delete`, `query`, and `persist`.
+
+Zero-dependency LangChain-shaped exports:
+
+These do not import `@langchain/core` and do not subclass LangChain base classes. They expose common document, retriever, and memory-shaped methods while using MumpixDB's local recall internally.
+
+```js
+const {
+  MumpixVectorStore,
+  MumpixChatMemory,
+  MumpixRetriever,
+} = require('mumpix/src/integrations/langchain');
+```
+
+Available methods:
+
+- `MumpixVectorStore.similaritySearch(query, k)`
+- `MumpixVectorStore.similaritySearchWithScore(query, k)`
+- `MumpixVectorStore.addDocuments(docs)`
+- `MumpixVectorStore.addTexts(texts, metadatas)`
+- `MumpixChatMemory.loadMemoryVariables(values)`
+- `MumpixChatMemory.saveContext(inputs, outputs)`
+- `MumpixChatMemory.clear()`
+- `MumpixRetriever.getRelevantDocuments(query)`
+
+Zero-dependency LlamaIndex-shaped exports:
+
+These do not import `llamaindex` and do not subclass LlamaIndex base classes.
+
+```js
+const {
+  MumpixIndex,
+  MumpixIndexRetriever,
+  MumpixReader,
+} = require('mumpix/src/integrations/llamaindex');
+```
+
+Available methods:
 
-- LangChain
-- LlamaIndex
+- `MumpixIndex.asRetriever({ topK })`
+- `MumpixIndex.insert(node)`
+- `MumpixIndex.insertMany(nodes)`
+- `MumpixIndexRetriever.retrieve(queryBundle)`
+- `MumpixReader.loadData()`
 
 Examples: