feat: dark-forest standalone package, agent protocol enhancements, spec-centric docs

- Extract dark-forest SDK into standalone @taskforest/dark-forest package
- Add TDX quote verifier and attestation envelope builder
- Add session stores (memory + localStorage) for MPP metering
- Enhance taskforest program: disputes, compressed state, privacy levels
- Enhance taskforest-payments: TEE attestation, ZK settlement compression
- Update SDK types, tests, and taskforest client
- Add spec-centric roadmap and architecture docs
- Add e2e and devnet test scripts
- Update README

Author: jimmdd

.gitignore

@@ -1,6 +1,7 @@
 # Rust / Anchor
 /target
 .anchor/
+/test-ledger
 
 # Dependencies
 node_modules/

Anchor.toml

@@ -23,4 +23,11 @@ wallet = "keys/taskforest.json"
 [scripts]
 test = "npx ts-mocha -p ./tsconfig.json -t 1000000 tests/taskforest.ts"
 test-payments = "npx ts-mocha -p ./tsconfig.json -t 1000000 tests/taskforest-payments.ts"
+test-compress-settlement = "npx ts-mocha -p ./tsconfig.json -t 120000 tests/compress-settlement.ts"
 test-er = "npx ts-mocha -p ./tsconfig.json -t 120000 tests/er-devnet.ts"
+test-payments-er = "npx ts-mocha -p ./tsconfig.json -t 120000 tests/payments-er-devnet.ts"
+light = "light test-validator --stop && light test-validator --validator-args '--upgradeable-program Fgiye795epSDkytp6a334Y2AwjqdGDecWV24yc2neZ4s target/deploy/taskforest.so keys/taskforest.json --upgradeable-program 4hNP2tU5r5GgyASTrou84kWHbCwdyXVJJN4mve99rjgs target/deploy/taskforest_payments.so keys/taskforest.json'"
+light-stop = "light test-validator --stop"
+light-test-payments = "ANCHOR_PROVIDER_URL=http://127.0.0.1:8899 ANCHOR_WALLET=keys/taskforest.json npx ts-mocha -p ./tsconfig.json -t 1000000 tests/taskforest-payments.ts"
+light-test-compress-settlement = "ANCHOR_PROVIDER_URL=http://127.0.0.1:8899 ANCHOR_WALLET=keys/taskforest.json npx ts-mocha -p ./tsconfig.json -t 120000 tests/compress-settlement.ts"
+light-test-local = "./scripts/test-local.sh"

Cargo.lock

@@ -8,12 +8,38 @@
 
 ## What is TaskForest?
 
-TaskForest is a decentralized protocol where humans and AI agents post tasks, stake SOL, and settle with cryptographic proof — all on-chain.
+TaskForest is a decentralized protocol where humans and AI agents post tasks, stake SOL, and settle with cryptographic proof on Solana.
+
+TaskForest also supports PMPP, our term for Private Machine Payment Protocol.
+Standard MPP is useful for metered machine payments, but fully public payment trails leak strategy.
+PMPP extends that model with private execution, private metering, and on-chain final settlement.
 
 - **Agent Router** — intelligent matchmaking that auto-assigns jobs to the best available agent
 - **Verification Layer** — execution receipt DAGs, TEE attestation, dispute resolution, verifier panels
 - **Escrow + Settlement** — trustless SOL escrow with on-chain settlement and slash mechanics
 
+## Privacy Model
+
+TaskForest privacy comes from three layers:
+
+- **Private execution** — jobs and payment flow can delegate into MagicBlock Ephemeral Rollups
+- **Private metering** — intermediate machine-payment activity does not need to be exposed on public Solana
+- **Minimized settlement footprint** — only the final settlement boundary and compressed commitments need to land on-chain
+
+This matters because public payment trails can reveal:
+
+- request frequency
+- endpoint usage
+- routing decisions
+- counterparties
+- spend curves
+
+For production, the trust model is:
+
+- Solana verifies escrow, settlement, and program state transitions
+- the on-chain payments program verifies signed attestation results bound to escrow and session state
+- full TDX quote parsing, certificate-chain validation, and collateral checks belong off-chain in a verifier service
+
 ---
 
 ## Architecture
@@ -31,6 +57,7 @@ TaskForest is a decentralized protocol where humans and AI agents post tasks, st
 ┌──────────────────┴──────────────────────────┐
 │      MagicBlock Ephemeral Rollup             │
 │  place_bid → gasless, <50ms                  │
+│  PMPP metering → private machine payments    │
 │  close_bidding → select winner, commit to L1 │
 └─────────────────────────────────────────────┘
 ```
@@ -91,26 +118,50 @@ npm install @taskforest/sdk
 ```
 
 ```typescript
-import { TaskForest } from '@taskforest/sdk'
+import { TaskForest, SpecBuilder } from '@taskforest/sdk'
 
 const tf = new TaskForest({ rpc: '...', wallet: agentKeypair, network: 'devnet' })
 
-// Post a task
-await tf.postTask({ ttd: 'code-review-v1', input: {...}, reward: 0.5, privacy: 'encrypted' })
-
-// Router: hire an agent automatically
-await tf.hireAgent({ problem: 'Review my code', maxBudget: 1.0, deadline: '2h' })
+const spec = new SpecBuilder('Review my code')
+  .description('Review the repository and return a markdown report.')
+  .criterion('ac-1', 'Cover the requested scope', 'coverage', { required: true, weight: 50 })
+  .criterion('ac-2', 'Return the report in markdown', 'output', { required: true, weight: 50 })
+  .input('url', 'Repository URL')
+  .output('file', 'Audit report', { format: 'markdown' })
+  .judgeMode('Score each criterion from 0-100.', 70)
+  .build()
+
+// Post a funded job from the approved spec
+await tf.postTask({
+  title: spec.metadata.title,
+  input: { repo_url: 'https://github.com/example/repo' },
+  spec,
+  reward: 0.5,
+  deadline: '2h',
+  privacy: 'encrypted',
+})
+
+// Workers or verifiers can then act against the same spec commitment
+const tasks = await tf.searchTasks({ minReward: 0.1, status: 'open' })
+await tf.bid(tasks[0].pubkey, { stake: 0.05 })
 
 // Disputes
 await tf.openDispute({ jobPubkey, disputedThread: 0, stakeLamports: 50000000, ... })
 
 // Verifier panel voting
 await tf.castVote({ disputePubkey, verdict: 1 })
-await tf.tallyPanel(disputePubkey)
+await tf.tallyPanel(jobPubkey, disputePubkey, challengerPubkey, votePubkeys)
 ```
 
 See [`sdk/README.md`](sdk/README.md) for full API reference.
 
+Dark Forest payment helpers are not part of `@taskforest/sdk`.
+Keep the core SDK lean and use `@taskforest/dark-forest` for PMPP, PER delegation, attestation, and private settlement helpers.
+
+```bash
+npm install @taskforest/dark-forest
+```
+
 ---
 
 ## Repo Structure
@@ -125,6 +176,7 @@ taskforest-protocol/          ← this repo (public)
 │       ├── types.ts          ← type definitions
 │       ├── receipts.ts       ← Merkle DAG receipt builder
 │       └── index.ts          ← exports
+├── dark-forest/              ← Dark Forest payments package (@taskforest/dark-forest)
 ├── tests/                    ← Anchor integration tests
 ├── docs/                     ← protocol design docs
 └── scripts/                  ← deployment scripts