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)

```bash
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`)

```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)

```typescript
// .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`)

```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`)

```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`)

```yaml
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`)

```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)

```typescript
// .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)

```bash
# 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
```c
// 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

```bash
# 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
```cmd
# 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
```bash
# 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
```c
// 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
```c
// 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
```text
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
```bash
# 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:
```c
// 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