clawpowers 2.0.0 → 2.2.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to ClawPowers are documented here.
 
+## [2.2.0] - 2026-04-08
+
+### Added
+
+- **Full secp256k1 Ethereum wallet derivation** (MetaMask-compatible): private key → uncompressed public key (64 bytes) → Keccak-256 → last 20 bytes as EIP-55 checksummed address.
+- **Pure Rust `k256`** (RustCrypto) in `native/crates/evm-eth`, wired into **WASM** and **FFI** with exports: `deriveEthereumAddress`, `derivePublicKey`, `signEcdsa`, `verifyEcdsa`.
+- **TypeScript loader** (`src/native/index.ts`): `keccak256Digest`, `deriveEthereumAddress`, `derivePublicKey`, `signEcdsa`, `verifyEcdsa` (Tier 1 → Tier 2 → `null` / `false` as documented).
+- **`signMessage` overload**: `(privateKeyHex, message)` returns a 65-byte ECDSA signature hex (`r‖s‖v`); existing `(message, keyFile, passphrase)` unchanged in shape, now uses ECDSA+Keccak when tiers allow, else HMAC fallback.
+- **Tests**: `tests/wallet/secp256k1.test.ts` (Hardhat default account #0 vector).
+
+### Notes
+
+- **WASM**: `getrandom` 0.2 `js` feature enabled for `wasm32` so `k256` builds under `wasm-pack`.
+- **Loader**: If Tier 1 (native) loads, Tier 2 (WASM) is still initialized when available so newer exports (e.g. secp256k1) work when an older `.node` lacks them. `getActiveTier()` remains `native` when the addon is present.
+- Existing keyfiles still use the stored `address` field as the source of truth; newly generated/imported keys use real Ethereum addresses when native or WASM is loaded.
+
+## [2.1.0] - 2026-04-06
+
+### Added
+
+- **Native acceleration layer** (parity with ClawPowers-Agent): `native/` Rust workspace (wallet, tokens, policy, fee, x402, canonical, compression, index, verification, security, ffi, WASM crate, PyO3 bindings).
+- **Pre-built WASM** in `native/wasm/pkg-node` and `native/wasm/pkg` so npm installs work **without** `wasm-pack` or Rust.
+- **3-tier TypeScript loader** (`src/native/index.ts`): Tier 1 optional `.node` addon, Tier 2 WASM, Tier 3 pure TypeScript fallbacks. Exported from the package root (`getActiveTier`, `isNativeAvailable`, `isWasmAvailable`, `getCapabilitySummary`, `computeSha256`, `digestForWalletAddress`, `tokenAmountFromHuman`, `calculateFee`, `evaluateWriteFirewall`, etc.).
+- **Payment bridges** (`calculateTransactionFee`, `createPaymentHeader`, `generateWalletAddress`) and **memory bridges** (`getBestCanonicalStore`, `compressVector`, `evaluateWriteSecurity`, …) via `src/payments/native-bridge.ts` and `src/memory/native-store.ts`.
+- **npm scripts:** `build:native`, `build:wasm`.
+- **WASM / native Keccak-256** for wallet address digest when Tier 1 or Tier 2 is active; **SHA-256** remains the Tier 3 fallback only.
+
+### Notes
+
+- Tier 1 (native) is **optional**; building `native/ffi` requires Rust locally. Published tarballs focus on Tier 2 WASM + Tier 3 TS.
+- Backward compatible at the **API** level for v2.0.0 importers; wallet **address strings** for newly generated keys may differ from v2.0.0 when WASM/native is loaded (Keccak-256 vs former SHA-256-only digest). Existing keyfiles keep their stored `address` field.
+
 ## [2.0.0] - 2026-04-03
 
 ### Breaking Changes

package/COMPATIBILITY.md

@@ -0,0 +1,13 @@
+# Compatibility Matrix
+
+## Supported release line
+
+| clawpowers | Recommended consumer |
+| --- | --- |
+| 2.2.x | capability-library consumers and `clawpowers-agent` 1.1.x |
+
+## Notes
+
+- `clawpowers` is the capability library, not the stock OpenClaw wrapper runtime.
+- `clawpowers-agent` is the wrapper runtime that consumes this package.
+- When `clawpowers` ships updated skills or capability implementations, `clawpowers-agent` should pick them up through package updates and skill sync.

package/KNOWN_LIMITATIONS.md

@@ -0,0 +1,19 @@
+# Known Limitations
+
+## Production-ready
+
+- capability library APIs for payments, memory, RSI, wallet, swarm, and ITP
+- native plus WASM fallback packaging when shipped correctly
+- local validation commands: lint, typecheck, test, build, pack
+
+## Experimental or environment-dependent
+
+- prompt-cache economics in benchmark collateral remain modeled, not billed receipts
+- native acceleration availability depends on platform and install environment
+- some consumer behavior depends on the wrapper/runtime that integrates this package
+
+## Important operational notes
+
+- non-native environments depend on packaged WASM fallback artifacts for real wallet derivation
+- users should not assume modeled prompt-cache savings are direct provider billing results
+- downstream runtimes should validate their own integration behavior separately from this library

package/LICENSING.md

@@ -0,0 +1,10 @@
+# Licensing and Commercial Use
+
+`clawpowers` is released under **BSL-1.1**.
+
+## What this means in practice
+
+- this package is the core capability library
+- commercial users should review the BSL terms before deployment or redistribution
+- downstream runtimes such as `clawpowers-agent` may use different licenses for their own wrapper code
+- always evaluate the exact published version you plan to ship

package/README.md

@@ -1,6 +1,12 @@
 # ClawPowers
 
-**Skills library for AI agents — payments, memory, RSI, wallet.** Drop-in capability layer for any agent framework.
+**Launch surface:** `clawpowers` is the capability library. It is not the stock OpenClaw wrapper runtime. For the wrapper runtime, install `clawpowers-agent`.
+
+**Recommended pairing:** `clawpowers` 2.2.x with `clawpowers-agent` 1.1.x.
+
+**More docs:** [SECURITY](./SECURITY.md) · [Compatibility](./COMPATIBILITY.md) · [Known Limitations](./KNOWN_LIMITATIONS.md) · [Licensing](./LICENSING.md) · [Releasing](./RELEASING.md) · [Demo](./DEMO.md)
+
+**Skills library for AI agents — payments, memory, RSI, wallet, parallel swarm, ITP.** Drop-in capability layer for any agent framework.
 
 [![npm version](https://img.shields.io/npm/v/clawpowers)](https://www.npmjs.com/package/clawpowers)
 [![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-blue.svg)](LICENSE)
@@ -9,6 +15,34 @@
 npm install clawpowers
 ```
 
+## 60-Second Demo
+
+```bash
+npm install clawpowers
+node -e "
+const { generateWallet, detect402, SpendingPolicy, signMessage } = await import('clawpowers');
+
+// 1. Generate a real Ethereum wallet (MetaMask-compatible)
+const wallet = await generateWallet({ chain: 'base', dataDir: './demo-wallet' });
+console.log('Address:', wallet.address);
+
+// 2. Detect an x402 payment-required response
+const req = detect402({ status: 402, headers: {
+  'x-payment-amount': '0.10',
+  'x-payment-currency': 'USD',
+  'x-payment-recipient': '0xabc',
+  'x-payment-network': 'base'
+}});
+console.log('Payment required:', req);
+
+// 3. Enforce a spending policy
+const policy = new SpendingPolicy({ dailyLimitUsd: 25, allowedDomains: ['api.example.com'] });
+console.log('Allowed:', policy.checkTransaction(0.10, 'api.example.com').allowed);
+"
+```
+
+That's a real Ethereum wallet, real x402 detection, and a real spending policy check — all in 60 seconds, zero config, zero Rust toolchain. The `native/` Rust acceleration is optional; the WASM tier ships pre-built in the npm package.
+
 > **⚠️ Patent Pending:** The x402 payment detection, autonomous spending policy enforcement, and recursive self-improvement (RSI) systems described in this library are subject to pending patent applications. Use is governed by the BSL 1.1 license.
 
 ---
@@ -17,11 +51,64 @@ npm install clawpowers
 
 ClawPowers extracts the core capabilities from [ClawPowers-Agent](https://github.com/up2itnow0822/ClawPowers-Agent) into a standalone library. **No agent control loop** — bring your own agent framework and get:
 
+That separation is intentional:
+
+- **`clawpowers`** owns the shared capability implementation.
+- **`clawpowers-agent`** owns the stock OpenClaw wrapper runtime.
+- Downstream wrappers should consume this package rather than duplicating capability logic.
+
 - **x402 Payments** — Detect HTTP 402 responses, enforce spending policies, execute payments
 - **Three-Tier Memory** — Working, episodic, procedural memory with crash recovery
 - **RSI Engine** — Metrics collection, hypothesis generation, mutation, A/B testing
-- **Wallet** — Generate, import, and sign with Ethereum-compatible wallets
+- **Wallet** — Generate, import, and sign with **MetaMask-compatible** Ethereum addresses out of the box (secp256k1 + Keccak-256 via pre-built WASM, no Rust toolchain required)
 - **Skills** — Discover, load, and track skill execution outcomes
+- **Parallel Swarm** — Concurrent task execution with intelligent model routing and token budgeting
+- **ITP (Identical Twins Protocol)** — Context compression that eliminates redundant token usage across agent sessions
+
+## Native Acceleration
+
+ClawPowers ships the same optional **Rust + WASM + PyO3** stack as [ClawPowers-Agent](https://github.com/up2itnow0822/ClawPowers-Agent), exposed through a **3-tier loader** in TypeScript. **v2.2.0+:** when a native `.node` addon is present, the WASM bundle is still loaded if available so helpers such as secp256k1 stay available even if your local addon predates those exports; `getActiveTier()` remains `native` in that case.
+
+| Tier | Backend | When it loads |
+|------|---------|----------------|
+| **1 — Native** | `napi-rs` `.node` addon (`native/ffi`, built locally with Rust) | Fastest; optional — not required for npm installs |
+| **2 — WASM** | Pre-built `native/wasm/pkg-node` (and `pkg` for web) | **Default** for most Node.js installs — no `wasm-pack` or Rust needed |
+| **3 — TypeScript** | Pure JS / Node built-ins | Universal fallback when native and WASM are unavailable |
+
+Check status in code:
+
+```typescript
+import { getActiveTier, isNativeAvailable, isWasmAvailable, getCapabilitySummary } from 'clawpowers';
+
+console.log(getActiveTier()); // 'native' | 'wasm' | 'typescript'
+console.log(isNativeAvailable(), isWasmAvailable());
+console.log(getCapabilitySummary());
+```
+
+### Building native / WASM locally
+
+**Requirements (optional):** Rust (`rustc` 1.70+), `wasm-pack` for regenerating WASM bindings.
+
+```bash
+npm run build:native   # workspace `cargo build --release` (ignored if Rust missing)
+npm run build:wasm     # wasm-pack → native/wasm/pkg-node (optional)
+```
+
+`wasm-pack` may regenerate `pkg/.gitignore` / `pkg-node/.gitignore` that ignore all files in those folders — remove those ignore files if you need to commit refreshed WASM output.
+
+Pre-built `.wasm` artifacts are included in the package so consumers are **not** required to run `wasm-pack`.
+
+### Module coverage (aligned with ClawPowers-Agent)
+
+| Area | Tier 1 / 2 capability | TypeScript fallback |
+|------|------------------------|---------------------|
+| Payments | `JsFeeSchedule`, WASM fee math | Pure-TS fee formula |
+| Payments | `JsX402Client` | Base64 JSON header |
+| Payments | `JsAgentWallet` (native only) | TS wallet + WASM secp256k1 + Keccak for real Ethereum addresses |
+| Memory | `JsCanonicalStore`, `JsTurboCompressor`, `JsWriteFirewall` | File/JSONL memory; simplified firewall |
+| Wallet / secp256k1 | Native + WASM: `deriveEthereumAddress`, `derivePublicKey`, `signEcdsa`, `verifyEcdsa`, `computeKeccak256` / `keccak256Bytes` | Tier 3: legacy digest-based “address” + HMAC signing fallback only |
+
+Exported helpers include `calculateTransactionFee`, `createPaymentHeader`, `generateWalletAddress`, `compressVector`, `getBestCanonicalStore`, `digestForWalletAddress`, and the full loader API in `src/native/index.ts`.
 
 ## x402 Payment Flow
 
@@ -141,18 +228,35 @@ const result = ab.evaluateTest(test.testId);
 
 ### Wallet
 
+**v2.2.0+ produces real MetaMask-compatible Ethereum addresses** via the standard derivation chain: secp256k1 private key → uncompressed public key → Keccak-256 → last 20 bytes, with EIP-55 checksum case. Verified against the Hardhat default test vector (`0xac09...ff80` → `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`). Addresses are importable into MetaMask, Etherscan, and any EVM wallet.
+
+**Tier behavior:**
+- **Tier 1** (native `.node` addon, built locally with `cargo`): full secp256k1 + ECDSA + Keccak-256 via the `k256` Rust crate
+- **Tier 2** (pre-built WASM, ships in the npm package): same secp256k1 + ECDSA + Keccak-256 via `k256` compiled to WebAssembly
+- **Tier 3** (pure TypeScript, used only if Tier 1 AND Tier 2 both fail to load): legacy SHA-256 digest and HMAC signing — **not production-safe for on-chain use**
+
+Since Tier 2 WASM artifacts ship pre-built in the npm package, **every install gets real Ethereum wallets out of the box** — no Rust toolchain required.
+
 ```typescript
-import { WalletManager } from 'clawpowers';
+import { WalletManager, generateWallet, signMessage } from 'clawpowers';
 
+// High-level API
 const wallet = new WalletManager({
   chain: 'base',
   dataDir: '~/.clawpowers/wallet',
 });
 
 const info = await wallet.generate();
-console.log(info.address); // 0x...
+console.log(info.address); // 0x... — real Ethereum address, EIP-55 checksummed
+
+// Low-level API for direct key handling
+const sig = await signMessage(privateKeyHex, 'Hello, Ethereum');
+// Returns 65-byte ECDSA signature (r || s || recovery) as 0x-prefixed hex
+// Verifiable by any Ethereum node, ethers.js, viem, or MetaMask
 ```
 
+For production on-chain sending and transaction construction, you can still use [`viem`](https://viem.sh) or [`ethers`](https://docs.ethers.org) alongside ClawPowers — our wallet produces the same addresses they do.
+
 ## Memory Module
 
 | Layer | Storage | Purpose |
@@ -179,6 +283,81 @@ measure → hypothesize → mutate → A/B test → promote/rollback → repeat
 
 Safety invariants (spending limits, identity, RSI definitions, sandbox boundaries, credentials) can **NEVER** be modified by RSI.
 
+## Parallel Swarm
+
+Run multiple tasks concurrently with intelligent model routing, shared context, and token budget management.
+
+```typescript
+import { ConcurrencyManager, TokenPool, classifyHeuristic, selectModel } from 'clawpowers';
+
+const pool = new TokenPool({ totalBudget: 100000 });
+const concurrency = new ConcurrencyManager({ maxConcurrency: 5 });
+
+// Classify and route tasks to optimal models
+const complexity = classifyHeuristic('Build a distributed trading system');
+const model = selectModel(complexity); // → claude-opus-4-5
+
+// Allocate token budgets per task
+pool.allocate('task-1', 5000);
+```
+
+### Swarm vs Sequential Sessions
+
+Running N tasks as a single parallel swarm instead of N separate LLM sessions avoids reloading shared context (system prompt, workspace files, tool schemas) for every task.
+
+**Measured benefits:**
+- **Wall time:** parallel fan-out is significantly faster than sequential execution, scaling with task count and concurrency limit
+- **Token usage:** shared-context overhead is paid once per swarm run instead of once per task
+
+**Current measurement snapshot:**
+
+**Live ITP compression measurements:**
+- **25-message corpus:** 11 of 25 messages compressed, `862` to `759` estimated tokens, **11.95% token reduction**, **7.8 ms/message** round-trip
+- **5-task live swarm payload:** `183` to `133` task tokens, **27.32% payload reduction**, **5 of 5 tasks compressed**, **10.8 ms** average encode latency
+
+**Modeled prompt-cache economics on those same live prompt sizes:**
+
+| Scenario | Effective input units | Reduction vs baseline | Source type |
+|----------|-----------------------|-----------------------|-------------|
+| Baseline | 1902.00 | 0.00% | Derived from live prompt sizes |
+| ITP only | 1848.00 | 2.84% | Live ITP server compression applied to full prompts |
+| Prompt cache only | 752.95 | 60.41% | Anthropic cache-pricing model |
+| ITP + prompt cache | 698.95 | 63.25% | Hybrid result: live ITP compression + modeled cache pricing |
+
+- **Shared prompt prefix in swarm test:** 1,372 characters, about 343 estimated input tokens
+- **Three-set hybrid validation on a MacBook Pro (Apple M1, 16 GB RAM) with benchmark runner model `openai-codex/gpt-5.4`:** combined reduction ranged from **61.89%** to **63.25%**, with a **62.56%** mean and **0.56** standard deviation
+
+**Reproduce:**
+- `node benchmarks/itp-measurement.mjs` for the live ITP corpus benchmark
+- `node benchmarks/swarm-vs-sequential.mjs` for the structure-only swarm cost model
+- `node benchmarks/itp-cache-swarm-benchmark.mjs` for the hybrid benchmark (live ITP compression + modeled cache economics)
+- `node benchmarks/itp-cache-multi-swarm-benchmark.mjs` for the same hybrid methodology across three swarm sets
+
+## ITP (Identical Twins Protocol) - Experimental
+
+> **Status: Experimental.** ITP compression and latency numbers below are measured against the running server. Any prompt-cache numbers are modeled Anthropic cache economics applied to those same live prompt sizes.
+
+Context compression for multi-agent communication. When agents share similar context (same model, same workspace), ITP deduplicates the common payload before transmission. The library ships with a graceful passthrough fallback, so code using ITP works even when the ITP server is offline. Messages are simply forwarded unchanged.
+
+```typescript
+import { itpEncode, itpDecode, itpHealthCheck, encodeTaskDescription, decodeSwarmResult } from 'clawpowers';
+
+// Graceful fallback, works without ITP server running
+const encoded = await encodeTaskDescription('Analyze quarterly revenue data');
+const decoded = await decodeSwarmResult(result);
+
+// Health check
+const serverUp = await itpHealthCheck(); // false = passthrough mode
+```
+
+**Live ITP benchmark snapshot:**
+- **Codebook:** `v1.0.0`, 99 entries
+- **Corpus benchmark:** **11.95%** token reduction on 25 messages
+- **Swarm payload benchmark:** **27.32%** task-token reduction on a 5-task swarm
+- **Hybrid swarm benchmark:** **63.25%** effective input-cost reduction from live ITP compression plus modeled prompt caching
+
+ITP is most effective in parallel swarm scenarios where multiple tasks share the same model context. Prompt caching handles repeated prompt structure, and ITP reduces the changing task payload inside that structure. Cross-model savings can also compound because providers inject similar preambles across nearby model tiers.
+
 ## Fee Structure
 
 | Operation | Fee |
@@ -195,13 +374,15 @@ import subprocess
 import json
 
 # Call ClawPowers via Node.js subprocess
+# Note: use --input-type=module (or a .mjs file) because clawpowers is an ES module
 result = subprocess.run(
-    ['node', '-e', '''
+    ['node', '--input-type=module'],
+    input='''
     import { detect402, SpendingPolicy } from "clawpowers";
     const policy = new SpendingPolicy({ dailyLimit: 25, transactionLimit: 10, allowedDomains: [] });
     const decision = policy.checkTransaction(5.00, "api.example.com");
     console.log(JSON.stringify(decision));
-    '''],
+    ''',
     capture_output=True, text=True
 )
 decision = json.loads(result.stdout)
@@ -209,11 +390,17 @@ decision = json.loads(result.stdout)
 
 ## API Reference
 
+### Native acceleration
+- `getActiveTier()`, `isNativeAvailable()`, `isWasmAvailable()`, `getCapabilitySummary()` — Loader introspection
+- `computeSha256`, `digestForWalletAddress`, `tokenAmountFromHuman`, `calculateFee`, `evaluateWriteFirewall` — Routed helpers
+- `getNative()`, `getWasm()` — Low-level module access
+
 ### Payments
 - `detect402(response)` — Parse x402 headers from 402 response
 - `isPaymentRequired(error)` — Type guard for 402 errors
 - `SpendingPolicy` — Enforce daily/transaction/domain limits
 - `PaymentExecutor` — Execute payments via MCP client
+- `calculateTransactionFee`, `createPaymentHeader`, `generateWalletAddress` — Native/WASM-accelerated payment helpers (with TS fallbacks)
 
 ### Memory
 - `WorkingMemoryManager` — In-process context management
@@ -221,6 +408,7 @@ decision = json.loads(result.stdout)
 - `ProceduralMemory` — Skill effectiveness tracking
 - `CheckpointManager` — Crash recovery
 - `ContextInjector` — Memory-to-context selection
+- `getBestCanonicalStore`, `getWasmCanonicalStore`, `compressVector`, `decompressVector`, `evaluateWriteSecurity` — Optional native/WASM memory bridges
 
 ### RSI
 - `MetricsCollector` — Task/skill metrics in JSONL
@@ -236,10 +424,12 @@ decision = json.loads(result.stdout)
 - `SkillExecutor` — Execute skills with outcome tracking
 
 ### Wallet
+
 - `WalletManager` — High-level wallet operations
-- `generateWallet(config)` — Generate new wallet
-- `importWallet(key, config)` — Import existing wallet
-- `signMessage(msg, keyFile, passphrase)` — Sign a message
+- `generateWallet(config)` — Generate new wallet (**v2.2.0+**: standard Ethereum address via secp256k1 when Tier 1/2 is active)
+- `importWallet(key, config)` — Import existing wallet (same derivation)
+- `signMessage(message, keyFile, passphrase)` — Sign; uses **ECDSA (secp256k1) over Keccak-256(UTF-8 message)** when native/WASM provides crypto, else legacy HMAC
+- `signMessage(privateKeyHex, message)` — Same ECDSA path; returns `0x` + 130 hex chars (65-byte signature)
 
 ### Config
 - `loadConfig()` / `saveConfig()` — Zod-validated config CRUD
@@ -261,3 +451,5 @@ See [LICENSE](LICENSE) for full terms.
 ---
 
 Built by [AI Agent Economy](https://github.com/up2itnow0822) 🦅
+
+For commercial use, review [LICENSING.md](./LICENSING.md).

package/SECURITY.md

@@ -2,71 +2,51 @@
 
 ## Supported Versions
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 2.0.x   | ✅ Active support  |
-| < 2.0   | ❌ No support      |
+| Version | Supported |
+| ------- | --------- |
+| 2.2.x   | ✅ |
+| 2.1.x   | ✅ |
+| < 2.1.0 | ❌ |
 
 ## Reporting a Vulnerability
 
-**Do NOT open a public GitHub issue for security vulnerabilities.**
-
-Please report security vulnerabilities via email:
-
-📧 **security@ai-agent-economy.com**
+Please report security issues privately to **bill@ai-agent-economy.com**.
 
 Include:
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact assessment
-- Suggested fix (if any)
-
-## Response Timeline
-
-- **Acknowledgment:** Within 48 hours
-- **Initial Assessment:** Within 5 business days
-- **Fix Timeline:** Critical vulnerabilities within 7 days
+- affected version
+- reproduction steps
+- impact assessment
+- whether the issue affects native, WASM, or TypeScript fallback paths
 
-## Security Design Principles
+Please do not open public GitHub issues for unpatched vulnerabilities.
 
-### Spending Policy (Financial Safety)
-- **Fail-closed:** Any policy error results in payment rejection
-- **Never auto-retry:** Failed payments are logged but never automatically retried
-- **Daily limits:** Hard-enforced, cannot be overridden by RSI
-- **Domain allowlists:** When configured, only listed domains can receive payments
+## Response Expectations
 
-### RSI Safety Invariants
-The following can **NEVER** be modified by the RSI engine:
-1. Spending limits and SpendingPolicy configuration
-2. Core identity and directives
-3. RSI safety tier definitions
-4. Sandbox boundaries
-5. Authentication credentials
+- initial acknowledgement: within 3 business days
+- severity triage: within 5 business days
+- fix target: depends on impact and exploitability
 
-### T4 Gate
-T4 (Architecture Proposals) mutations **always** require human approval. The `'auto'` mode is rejected at the type system level and the validation layer.
+## Scope Notes
 
-### Wallet Security
-- Private keys are encrypted at rest using AES-256-GCM
-- Key derivation uses scrypt (N=16384, r=8, p=1)
-- Atomic file writes prevent corruption
-- Backup files created before overwrites
+ClawPowers ships wallet, payment, memory, and RSI primitives. Security-sensitive areas include:
+- private key generation and storage
+- payment policy enforcement
+- x402 header creation and parsing
+- native and WASM crypto fallbacks
+- local file-backed memory stores
 
-### Memory Integrity
-- Episodic memory is append-only (JSONL)
-- Procedural memory uses atomic writes with backup
-- Checkpoint files use write-to-temp-then-rename pattern
-- Corruption recovery is built into episodic memory
+## Data Handling
 
-## Dependencies
+ClawPowers is designed for local-first operation.
 
-This library has minimal runtime dependencies:
-- `zod` — Schema validation (no known vulnerabilities)
-- Node.js built-in `crypto` — For wallet operations
+- no telemetry is sent by the library itself
+- secrets are not intentionally exfiltrated by package code
+- payment, wallet, and memory data storage behavior depends on the consuming application configuration
 
-## Audit
+## Disclosure Policy
 
-The codebase enforces:
-- Zero `any` types in TypeScript
-- Strict mode enabled
-- All financial operations logged to audit trail
+We prefer coordinated disclosure. After a fix is available, we may publish:
+- affected versions
+- impact summary
+- remediation guidance
+- CVE or advisory references when applicable