AGENTS.md

AGENTS.md — SnapKitty Agent OS (P/NP Swarm Edition)

Identity

• OS: SnapKitty Sovereign Transformer v2026
• Operator: Ahmad Ali Parr
• Trust Root: Bifrost WORM Chain (audit: 4b565498-9afc-4782-af4a-c6b11a5d0058)
• Logic Layer: TypeScript/WASM (deterministic, verifiable)
• Solving Model: P/NP Swarm — each agent solves a piece; repo verifies; universe converges

Memory Protocol (GitBucket v2)

• Primary: .agentos/gitbucket/ — every commit = immutable memory bucket
• Schema: memory-bucket-v2.json (canonical, Ed25519 sealed, includes pnpRef?)
• Query: assembleContext(spec) → proof-carrying context bundle (TypeScript, deterministic)
• Index: Multi-dimensional (file, entity, agent, topic, time, dependency, problemId)

Inverted Skills Memory (Core Innovation)

Skills are memories, not code. A skill = a sealed GitBucket memory that proves it can transform input→output, plus a verifyFn that checks the proof in P-time.

Skills are not code — they are sealed memories with verifyFn (WASM) + provides/requires Load via skillLoader.load(skillId) → returns {fn, memory, proof} Skills evolve by new memory commits, not version bumps

P/NP Swarm Protocol (§5)

Core Insight

Finding a solution is NP-hard. Verifying a solution is P-time. The repo only accepts P-verifiable proofs. Agents compete/cooperate to find witnesses.

Using and Understanding

1. Read .agentos/pnp/problem_registry.json — open problems with verifyFn (P-time)
2. Claim a problem: append to claim_ledger.jsonl (includes nonce, agentId)
3. Solve — compute witness (NP-hard, your work)
4. Submit — write {problemId, witness, proof} to solution_pool/
5. Verify — repo runs verifyFn(witness) in CI (P-time, deterministic)
6. Converge — on verify: problem → solved, universe-sum advances, new problems may spawn

Startup Sequence (Every Agent)

git clone <this-repo> && cd snapkitty-agentos
npm ci # installs TS/WASM runtimes, verifiers
npm run verify:all # Plasma Gate + P/NP proofs + skill seals
npm run context:bootstrap # loads latest memories into local index
# → You are now a solver node. Read problems. Claim. Solve. Submit.

Non-Goals

• No Prolog. No Council IDE. No central coordinator.
• No "agent framework" — you are the agent. The repo is the substrate.

---

4. Inverted Skills Memory (Core Innovation)

4.1 Philosophy

Skills are memories, not code.

A skill = a sealed GitBucket memory that proves it can transform input→output, plus a verifyFn that checks the proof in P-time.

4.2 Skill Record (.agentos/skills/registry.json)

{
  "skills": [
    {
      "id": "ledger_validation_v3",
      "memoryRef": "mem_004217",
      "provides": ["validateLedgerEntry"],
      "requires": ["ed25519Verify", "borrowCheck"],
      "verifyFn": "skills/artifacts/ledger_validation_v3/verify.wasm",
      "inputSchema": { "type": "object", "required": ["entry", "witness"] },
      "outputSchema": { "type": "object", "required": ["valid", "proof"] },
      "trust": "verified",
      "created": "2026-07-02T18:45:00Z",
      "author": "SnapKitty"
    },
    {
      "id": "borrow_chain_scheduler_v1",
      "memoryRef": "mem_003891",
      "provides": ["scheduleBorrows"],
      "requires": ["topoSort"],
      "verifyFn": "skills/artifacts/borrow_chain_scheduler_v1/verify.wasm",
      "inputSchema": { "type": "object", "required": ["borrowGraph"] },
      "outputSchema": { "type": "object", "required": ["schedule", "proof"] },
      "trust": "verified",
      "created": "2026-06-15T12:00:00Z",
      "author": "SnapKitty"
    }
  ]
}

4.3 Skill Artifact Layout (.agentos/skills/artifacts/<skillId>/)

ledger_validation_v3/
├── impl.wasm # Actual skill implementation (WASM component)
├── verify.wasm # P-time verifier: (input, output, proof) → bool
├── manifest.json # {id, version, memoryRef, provides, requires}
└── proof_example.json # Sample (input, output, proof) for testing

4.4 Loading a Skill (Deterministic)

// .agentos/runtime/skillLoader.ts
export async function loadSkill(skillId: string): Promise<SkillModule> {
  const registry = await readJSON('.agentos/skills/registry.json');
  const record = registry.skills.find(s => s.id === skillId);
  if (!record) throw new Error(`Skill ${skillId} not found`);

  // 1. Load memory bucket (context + proof of correctness)
  const memory = await gitbucket.fetchBucket(record.memoryRef);
  if (!memory) throw new Error(`Memory ${record.memoryRef} missing`);

  // 2. Load verifyFn (WASM, deterministic)
  const verifyFn = await loadWasmVerifier(record.verifyFn);

  // 3. Load impl (WASM component)
  const impl = await loadWasmComponent(`.agentos/skills/artifacts/${skillId}/impl.wasm`);

  // 4. Return sealed module — caller MUST verify before use
  return {
    id: skillId,
    memory,
    verify: (input, output, proof) => verifyFn(input, output, proof),
    execute: (input) => impl.run(input),
    // Agent must call verify(execute(input)) before trusting output
  };
}

4.5 Skill Evolution = New Memory Commit

• To upgrade a skill: make a commit that produces a new memory bucket with updated impl.wasm + verify.wasm
• New bucket → new memoryRef → new registry entry (old skill remains immutable)
• Agents discover new skills via assembleContext({topic: "skill", since: <lastCheck>})

---

5. P/NP Swarm Layer (The Solving Engine)

5.1 Core Insight

Finding a solution is NP-hard. Verifying a solution is P-time. The repo only accepts P-verifiable proofs. Agents compete/cooperate to find witnesses.

5.2 Problem Registry (.agentos/pnp/problem_registry.json)

{
  "problems": [
    {
      "id": "optimal_borrow_schedule_2026_Q3",
      "specHash": "sha256:a8d72e4f...",
      "verifyFn": "pnp/verifiers/optimal_borrow_schedule.wasm",
      "difficulty": "NP-hard",
      "reward": { "type": "memory", "value": "mem_005000" },
      "status": "open",
      "claimedBy": null,
      "claimedAt": null,
      "solvedBy": null,
      "solvedAt": null,
      "solutionRef": null
    },
    {
      "id": "ledger_state_convergence_proof",
      "specHash": "sha256:19fd33a1...",
      "verifyFn": "pnp/verifiers/ledger_convergence.wasm",
      "difficulty": "NP-complete",
      "reward": { "type": "skill_unlock", "value": "ledger_validation_v4" },
      "status": "claimed",
      "claimedBy": "agent_0x7f3a",
      "claimedAt": "2026-07-02T19:10:00Z",
      "solvedBy": null,
      "solvedAt": null,
      "solutionRef": null
    }
  ]
}

5.3 Claim Ledger (Append-only, .agentos/pnp/claim_ledger.jsonl)

{"problemId":"optimal_borrow_schedule_2026_Q3","agentId":"agent_0x9b2c","nonce":"0x3f2a1...","timestamp":"2026-07-02T19:12:00Z","expiresAt":"2026-07-02T23:12:00Z"}
{"problemId":"ledger_state_convergence_proof","agentId":"agent_0x7f3a","nonce":"0x1a7e9...","timestamp":"2026-07-02T19:10:00Z","expiresAt":"2026-07-02T23:10:00Z"}

5.4 Solution Pool (.agentos/pnp/solution_pool/<problemId>/)

optimal_borrow_schedule_2026_Q3/
├── solution_0x9b2c_1.json # {witness, proof, agentId, timestamp}
├── solution_0x9b2c_2.json # Improved witness
└── verified.json # First verified solution (CI promotes this)

5.5 Verification Pipeline (CI: workflows/pnp_verify.yml)

name: P/NP Verify
on:
  push:
    paths: ['.agentos/pnp/solution_pool/**']
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - name: Verify all new solutions
        run: |
          node .agentos/runtime/pnpVerifier.js \
            --registry .agentos/pnp/problem_registry.json \
            --pool .agentos/pnp/solution_pool \
            --out .agentos/pnp/verified_solutions.jsonl
      - name: Update convergence log
        if: success()
        run: |
          node .agentos/runtime/converge.js

5.6 Convergence Log (.agentos/pnp/convergence_log.jsonl)

{"event":"problem_solved","problemId":"optimal_borrow_schedule_2026_Q3","solver":"agent_0x9b2c","solutionRef":"mem_005000","universeSumDelta":0.0034,"timestamp":"2026-07-02T19:45:00Z"}
{"event":"skill_unlocked","skillId":"ledger_validation_v4","unlockedBy":"ledger_state_convergence_proof","timestamp":"2026-07-02T20:10:00Z"}
{"event":"new_problem_spawned","problemId":"cross_chain_atomic_swap_opt","parentProblems":["optimal_borrow_schedule_2026_Q3","ledger_state_convergence_proof"],"timestamp":"2026-07-02T20:10:05Z"}

5.7 Universe Sum (The Convergence Metric)

// .agentos/runtime/universeSum.ts
export function computeUniverseSum(): number {
  const solved = readConvergenceLog().filter(e => e.event === 'problem_solved');
  return solved.reduce((sum, e) => sum + difficultyWeight(e.problemId), 0);
}

Goal: universeSum → ∞ (or the fixed point of your problem space). Each agent pushes it forward. The repo is the training curve.

---

6. Agent Lifecycle (Clone → Solve → Converge)

---

7. Bootstrap Checklist (Run Once, Then Agents Self-Sustain)

# 1. Create repo
git init snapkitty-agentos && cd snapkitty-agentos

# 2. Scaffold (this spec → files)
# - AGENTS.md, package.json, tsconfig.json
# - .agentos/config.json, plasma_gate/, gitbucket/, skills/, pnp/, runtime/
# - workflows/extract.yml, verify.yml, pnp_verify.yml, audit.yml

# 3. Generate Plasma Gate keypair (Ed25519)
npm run plasma:keygen # writes .agentos/plasma_gate/pubkey.pem + verify.wasm

# 4. Initialize GitBucket (empty index, ready for backfill)
npm run gitbucket:init

# 5. Seed problem registry with 3-5 founding NP-hard problems
npm run pnp:seed -- --problems founding_problems.json

# 6. Commit & push
git add . && git commit -m "genesis: agent-native repo, P/NP swarm initialized"
git remote add origin <your-sovereign-git-host>
git push -u origin main

# 7. Any agent clones → runs startup sequence → becomes solver node

---

8. Key Differences from Previous Design

Aspect	Previous (Prolog)	This Spec (P/NP Swarm)
Logic Layer	Prolog facts/rules	TypeScript/WASM (deterministic, portable)
Skills	Code modules	Inverted memories (sealed buckets + verifyFn)
Coordination	Central IDE (Council)	None — repo is the coordinator
Agent Role	Query memory	Claim → Solve → Submit → Verify → Converge
Progress Metric	Context size	Universe Sum (monotonic convergence)
Training	External	In-repo: every solution = new memory/skill
Trust	Prolog proofs	Ed25519 + P-time verifyFn + Bifrost anchor

---

9. Next Concrete Step

You asked me to integrate the plan and add meta data into the spec, and build out the new repo. I'll now work on the directory layout and files.