README.md

# AGENTOS

**SOVEREIGN COMPUTE ORCHESTRATION HOST — THE SUBSTRATE THAT HOLDS THE SWARM TOGETHER.**

`agentos` is the production repository for the SnapKitty Agent OS: the packaging, runtime,
policy, and CI fabric that wraps the constellation of sovereign-compute repos. It hosts the
**Sovereign Daemon** (Go), the **agentos-frontend** (Next.js operator console), **Nix**
reproducible build modules, **Prolog** trust/policy gates, SBOM + WORM verification scripts,
and the GitHub Actions pipelines that gate every merge. The `AGENTS.md` in this repo is the
canonical articulation of the Agent OS philosophy — inverted skills memory, the P/NP swarm,
and the Bifrost WORM trust root.

## OVERVIEW

| Aspect | Value |
|--------|-------|
| Operator | Ahmad Ali Parr · SnapKitty Collective |
| Trust Root | Bifrost WORM Chain (audit `4b565498-9afc-4782-af4a-c6b11a5d0058`) |
| Logic Layer | TypeScript / WASM (deterministic, verifiable) |
| Solving Model | P/NP Swarm — claim → solve → submit → verify → converge |
| License | Apache-2.0 |

## WHAT IT IS

`agentos` is **not** an agent framework — it is the repo-as-substrate. Every other SnapKitty
repo (resonance-math, qec-discovery, math-skills, prism-skills, axiom-proof, …) is a solver
node that plugs into this constellation. This repo supplies the shared infrastructure:

- **Sovereign Daemon** (`src/sovereign-daemon`, Go) — a lightweight service exposing
  `/v1/env/validate`, `/v1/pipeline/execute`, `/v1/artifact/sign`, `/v1/daemon/status`, and
  model-catalog endpoints (`/v1/ollama/models`, `/v1/vllm/models`) over a Unix socket and
  localhost `:8080`. It is the runtime spine that validates environments and signs artifacts.
- **agentos-frontend** (Next.js 14 + React 18 + Tailwind) — the operator console that renders
  the sovereign state, memory buckets, and swarm status to humans.
- **Nix modules** (`nix/`) — reproducible packaging: `bifrost.nix`, `daemon.nix`,
  `prolog.nix`, `gitbash-meta.nix`, the `sovereign-overlay.nix`, and the
  `snapkitty-daemon` / `snapkitty-installer` packages.
- **Prolog policies** (`policies/`) — executable trust + supply-chain gates:
  `trust_deed.pl` (who is trusted), `snapkitty_bom.pl` (the Bill of Materials module that
  emits JSON for the MSYS2/MinGW/swi-prolog runtime), and `pipeline_policy.pl`.
- **Scripts** (`scripts/`) — `build-all.sh`, `generate-sbom.sh`, `verify-worm.sh`.
- **Workflows** (`workflows/`) — `verify.yml`, `extract.yml`, `pnp_verify.yml`, `audit.yml`.

## ARCHITECTURE / COMPONENTS

```
agentos/
├── src/sovereign-daemon/        # Go daemon: env validate, pipeline execute, artifact sign, model catalogs
│   ├── main.go                  # HTTP + unix-socket server, /v1/* endpoints
│   └── go.mod
├── agentos-frontend/            # Next.js 14 operator console (React 18, Tailwind 3, TS 5)
│   ├── pages/index.html
│   ├── app/ css/ js/ data/      # UI source, metadata.json
│   └── package.json
├── nix/                         # Reproducible Nix packaging
│   ├── lib/bom.nix
│   ├── modules/{bifrost,daemon,prolog,gitbash-meta}.nix
│   ├── overlays/sovereign-overlay.nix
│   └── packages/{snapkitty-daemon,snapkitty-installer}/default.nix
├── policies/                    # Prolog trust + supply-chain gates
│   ├── trust_deed.pl            # deed_trusted/1 facts
│   ├── snapkitty_bom.pl         # SWI-Prolog BoM module → JSON
│   ├── pipeline_policy.pl
│   └── metadata.json
├── scripts/                     # build-all.sh, generate-sbom.sh, verify-worm.sh
├── docs/                        # Generated static docs (html/js/css)
├── dotfiles/                    # .bashrc.d + home dotfiles for sovereign env
├── tests/agentos.test.mjs       # Node test suite (plasma gate, skills, pnp verifier)
├── workflows/                   # verify / extract / pnp_verify / audit CI
├── AGENTS.md                    # Canonical Agent OS spec (P/NP swarm, inverted skills)
├── package.json                 # npm scripts: verify:all, context:bootstrap, pnp:*
└── LICENSE                      # Apache-2.0
```

## HOW IT FITS THE CONSTELLATION

`agentos` is the **trust + delivery core** of the sovereign-compute constellation:

- **Bifrost WORM Chain** — the audit anchor (`4b565498…`) that every sealed artifact,
  memory bucket, and theorem references. `scripts/verify-worm.sh` expresses the WORM
  verification contract this repo enforces across sibling repos.
- **Plasma Gate / Ed25519** — `verify:plasma` and the test suite assert the Ed25519-enforced
  gate before any artifact is trusted; `metadata.json` files across the org carry
  `"plasma_gate": "Ed25519_Enforced"`.
- **P/NP Swarm** — `pnp_verify.yml` runs the P-time verifier over any `solution_pool` push.
  Agents claim problems, compute NP-hard witnesses, and the repo verifies in deterministic
  P-time before a problem converges and the universe-sum advances.
- **Inverted Skills Memory** — the `AGENTS.md` defines skills as sealed GitBucket memories
  with a `verifyFn`, not code; the test suite (`tests/agentos.test.mjs`) exercises
  `loadSkill`, `verifySkills`, and the ledger/borrow skills.
- **3-witness verification** — trust is established by Plasma Gate (Ed25519) + P/NP
  verifier + skill seal. `Ω ← TRUST ∧ CODE`: a node is trustworthy only when the
  cryptographic gate and the verified code agree.

## BUILD / USAGE / INSTALL

```bash
# Node tooling (verification gates, context, swarm client)
npm ci
npm test                      # agentos.test.mjs — plasma gate, skills, pnp verifier
npm run verify:all            # plasma + pnp + skills + apl/fortran source checks
npm run context:bootstrap     # load GitBucket memories into local index

# Sovereign Daemon (Go)
cd src/sovereign-daemon && go run . serve --socket /run/user/1000/snapkitty.sock
# → listens on unix socket + http://localhost:8080 (env validate, pipeline, sign, status)

# Frontend console (Next.js 14)
cd agentos-frontend && npm install && npm run dev      # http://localhost:3000

# Reproducible Nix build
nix build .#snapkitty-daemon
nix build .#snapkitty-installer

# Supply chain + WORM
bash scripts/generate-sbom.sh
bash scripts/verify-worm.sh
```

## KEY FILES REFERENCE

| File | Purpose |
|------|---------|
| `src/sovereign-daemon/main.go` | Sovereign Daemon: `/v1/*` endpoints, env/pipeline/sign/status + model catalogs |
| `agentos-frontend/package.json` | Next.js 14 operator console dependency set |
| `nix/modules/bifrost.nix` | Bifrost WORM trust-root Nix module |
| `nix/modules/daemon.nix` | Daemon packaging module |
| `policies/snapkitty_bom.pl` | SWI-Prolog Bill-of-Materials module → JSON |
| `policies/trust_deed.pl` | Trusted-operator/deed facts for the pipeline gate |
| `scripts/verify-worm.sh` | WORM chain append-only verification contract |
| `workflows/verify.yml` | CI: npm ci → test → verify:all on push/PR |
| `workflows/pnp_verify.yml` | CI: P-time verification of P/NP solution pool pushes |
| `workflows/audit.yml` | Scheduled full audit (build + verify:all + bootstrap) |
| `AGENTS.md` | Canonical SnapKitty Agent OS spec (P/NP swarm, inverted skills) |
| `package.json` | npm scripts: `verify:all`, `context:*`, `pnp:*`, `swarm` |

## LICENSE

Apache-2.0. Authored by Ahmad Ali Parr · SnapKitty Collective · the-49th-call SNAPKITTYWEST · 2026.