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.

10. APL Fortran Module

Status: implemented as a verified source package; native C compilation is gated behind a Visual Studio developer shell.

The APL Fortran module provides Windows-compatible C bindings for the APL-to-Fortran compilation system. It enables APL expressions to be compiled and executed in Fortran runtime with full array operations, optimization passes, and cross-platform deployment.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                 APL Fortran C Bindings                      │
│                 (Windows Native)                            │
├─────────────────────────────────────────────────────────────┤
│              APL Expression Parser                          │
│                 • AST Construction                           │
│                 • Semantic Analysis                          │
├─────────────────────────────────────────────────────────────┤
│                APL Array Engine                              │
│                 • Array Operations                           │
│                 • Memory Management                         │
│                 • Array Manipulation                        │
├─────────────────────────────────────────────────────────────┤
│              APL Fortran Backend                             │
│                 • Fortran Code Generation                   │
│                 • Optimization Pipeline                      │
│                 • Compilation & Linking                      │
├─────────────────────────────────────────────────────────────┤
│                    Fortran Runtime                            │
│                 • BLAS/LAPACK Integration                    │
│                 • Parallel Processing                        │
│                 • Array Computations                        │
└─────────────────────────────────────────────────────────────┘

Core Components

10.1 Core Runtime (.agentos/runtime/apfortran.c)

• Windows-native C bindings with API compatibility
• Memory management and threading utilities
• Error handling and platform abstractions
• Initialization and cleanup routines

10.2 Expression Engine (.agentos/runtime/apfortran_expr.c)

• APL parser and AST construction (Expression types: LITERALS, BINARY, UNARY, ARRAY, SCALAR, ATOM, CALL, NOFREE)
• Expression evaluation and manipulation
• Ref-counted memory management
• Support for APL's array-oriented operations

10.3 Array Engine (.agentos/runtime/apfortran_array.c)

• APL array operations (shape, dtype, memory management)
• Array iteration and transformation (vectorization, parallelization)
• Integration with Fortran runtime
• Cache-optimized array processing

10.4 Fortran Backend (.agentos/runtime/apfortran_fortran.c)

• Fortran code generation from APL expressions
• Optimization pipeline (vectorization, fusion, tiling)
• Cross-platform compilation (Windows x64 native)
• Integration with BLAS/LAPACK

10.5 Build System (CMakeLists.txt)

• Windows Visual Studio 2022 support
• CMake configuration for Windows native builds
• Cross-platform compilation support
• Installation and packaging

Windows-Specific Features

Native Windows Integration

• Windows API integration via C bindings
• Win32 file I/O with UTF-8 support
• Windows threading primitives
• Memory allocation aligned for Fortran performance
• Compiler optimizations for Windows x64

API Compatibility

// Windows-native APL Fortran API
APL_API apl_error_t APL_CDECL apl_init(const apl_compiler_options_t* options);
APL_API apl_error_t APL_CDECL apl_compile(apl_expr_t* expr, apl_fortran_backend_t** backend);
APL_API apl_error_t APL_CDECL apl_execute(apl_fortran_backend_t* backend, apl_array_t* input, apl_array_t** output);
APL_API apl_error_t APL_CDECL apl_evaluate(const char* expression, apl_array_t** result);

Performance Optimization Targets

• SIMD vectorization hooks (SSE/AVX)
• Windows native threading hooks
• Cache-friendly tiling and blocking hooks
• Compiler optimization configuration (Release/RelWithDebInfo)

Integration with SnapKitty Agent OS

P/NP Swarm Integration

• APL Fortran backend for NP-hard problems involving array operations
• Matrix algebra and numerical computing for optimal scheduling
• Integration with gitbucket:extract for memory buckets
• Context compilation with context:compile

Workflow Integration

# Bootstrap APL Fortran components
npm run verify:all  # Verify: Plasma Gate, P/NP Proofs, Skills, APL Fortran
npm run context:bootstrap  # Load GitBucket memories

# Process APL Fortran problems
npm run pnp:claim optimal_borrow_schedule_2026_Q3

# Verify compilation artifacts
cmake --build build --config Release
./aplfortran_test

Runtime Architecture

Memory Management

• Ref-counted AST and array nodes
• Win32 aligned memory allocation
• Thread-safe array operations
• Memory leak detection and debugging

Execution Pipeline

1. Parse APL expression into AST
2. Generate array-based IR
3. Optimize with Win32-aware passes
4. Compile to native Fortran
5. Execute with BLAS/LAPACK acceleration

Windows Build Instructions

Visual Studio Build

# Navigate to snapkitty-agentos
cd C:\Users\jessi\IdeaProjects\SNAPKITTYWEST\snapkitty-agentos

# Configure with Visual Studio 2022
cmake -S . -B build -G "Visual Studio 17 2022" -A x64

# Build Release configuration
cmake --build build --config Release

# Run tests
ctest --test-dir build -C Release

CMake Build

# Create build directory
mkdir build && cd build

# Configure for Windows
cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release ..

# Build
cmake --build .

# Install to local prefix
cmake --install . --prefix ./install

API Documentation

Core Functions

// Initialization and lifecycle management
apl_error_t apl_init(const apl_compiler_options_t* options);
apl_error_t apl_cleanup(void);

// Expression handling
apl_error_t apl_parse(const char* source, apl_expr_t** expr);
apl_error_t apl_free_expr(apl_expr_t* expr);
apl_error_t apl_evaluate(const char* expression, apl_array_t** result);

// Array operations
apl_array_t* apl_array_create(int rank, const int64_t* shape, const char* dtype, size_t element_size, void* data);
apl_error_t apl_array_apply_to_all(apl_array_t* arr, apl_array_element_op op, void* context);

// Fortran backend
apl_error_t apl_compile(apl_expr_t* expr, apl_fortran_backend_t** backend);
apl_error_t apl_execute(apl_fortran_backend_t* backend, apl_array_t* input, apl_array_t** output);
apl_error_t apl_generate_f90(apl_fortran_backend_t* backend, const char* output_file);

// Optimization
apl_error_t apl_configure_backend(apl_fortran_backend_t* backend, apl_compiler_options_t* options);

Data Structures

// APL expression AST
typedef enum { APL_EXPR_LITERAL, APL_EXPR_BINARY, APL_EXPR_UNARY, APL_EXPR_ARRAY, APL_EXPR_SCALAR, APL_EXPR_ATOM, APL_EXPR_CALL } AplExprType;

struct apl_expr_t {
    AplExprType type;
    int ref_count;
    union { /* Expression-specific data */ } u;
};

// APL array container
struct apl_array_t {
    int rank;
    int64_t shape[APL_MAX_RANK];
    char dtype[32];
    size_t element_size;
    size_t total_elements;
    int64_t strides[APL_MAX_RANK];
    void* data;
    // Additional metadata and ref counting
};

Performance Characteristics

Verification Results

npm test                 -> AgentOS JS verification suite
npm run verify:all       -> Plasma Gate + P/NP + skills + APL/Fortran source package
npm run test:aplfortran  -> Windows source-package and environment checks

Native C compilation requires Visual Studio Build Tools or a Visual Studio developer shell. The checked-in verifier does not claim native BLAS performance until that build path is run.

Optimization Features

• SIMD vectorization (SSE/AVX)
• Loop fusion and tiling
• Parallel execution (OpenMP)
• Memory prefetch optimization
• Cache-aware data layout

Testing

Test Suite

# Run all tests
npm test

# Test APL Fortran source package
npm run test:aplfortran

# Verify all AgentOS gates
npm run verify:all

Troubleshooting

Common Issues

1. Windows Linking Errors

   Symptom: LINK : fatal error LNK2019: unresolved external symbol _main
   Solution: Ensure main entry point in Windows test executable
   

2. Memory Alignment Issues

   Symptom: Performance degradation on Windows
   Solution: Use Win32 aligned alloc: apl_win32_aligned_alloc(64, size)
   

3. Fortran Compiler Integration

   Symptom: APL_ERROR_F90 during compilation
   Solution: Ensure Fortran compiler is installed (MSVC Intel Fortran)
   

Debugging

Enable Windows debugging:

// Enable verbose debugging for Windows
apl_compiler_options_t opts = {0};
opts.enable_vectorization = true;
opts.enable_fusion = true;
opts.verbose = true;

apl_init(&opts);

// Enable memory leak detection
#ifdef _WIN32
apl_memory_dump("windows_memory_leak.log");
#endif

License

Apache 2.0