@gns-foundation/hive-worker 0.1.0

package/src/jobs.ts

@@ -0,0 +1,228 @@
+// ============================================================
+// HIVE WORKER — JOB QUEUE
+// Poll Supabase hive_jobs, claim atomically via FOR UPDATE
+// SKIP LOCKED (Postgres handles races — no app-level locking needed)
+// ============================================================
+
+const SUPABASE_URL = 'https://kaqwkxfaclyqjlfhxrmt.supabase.co';
+const SUPABASE_ANON = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImthcXdreGZhY2x5cWpsZmh4cm10Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI4MzU4NTAsImV4cCI6MjA4ODQxMTg1MH0.ClyWNGRxQjpKYzIROPZBqTXDsWvJioGe9pQymDOYBTc';
+
+const HEADERS = {
+  'apikey': SUPABASE_ANON,
+  'Authorization': `Bearer ${SUPABASE_ANON}`,
+  'Content-Type': 'application/json',
+};
+
+// ─── Types ────────────────────────────────────────────────────
+
+export interface HiveJob {
+  id: string;
+  h3_cell: string;
+  jurisdiction: string | null;
+  model_id: string;
+  model_url: string | null;
+  layer_start: number;
+  layer_end: number;
+  prompt: string;
+  max_tokens: number;
+  temperature: number;
+  status: 'pending' | 'assigned' | 'computing' | 'completed' | 'failed' | 'timed_out';
+  worker_pk: string | null;
+  assigned_at: string | null;
+  result_text: string | null;
+  tokens_generated: number | null;
+  tokens_per_second: number | null;
+  completed_at: string | null;
+  error_message: string | null;
+  gns_reward: number;
+  settled: boolean;
+  stellar_tx_hash: string | null;
+  submitter_pk: string;
+  created_at: string;
+  timeout_at: string;
+}
+
+export interface JobResult {
+  resultText: string;
+  tokensGenerated: number;
+  tokensPerSecond: number;
+  error?: string;
+}
+
+// ─── Claim (atomic via Postgres RPC) ─────────────────────────
+
+export async function claimJob(
+  workerPk: string,
+  h3Cell: string,
+  modelId?: string,
+): Promise<HiveJob | null> {
+  const resp = await fetch(
+    `${SUPABASE_URL}/rest/v1/rpc/claim_hive_job`,
+    {
+      method: 'POST',
+      headers: HEADERS,
+      body: JSON.stringify({
+        p_worker_pk: workerPk,
+        p_h3_cell:   h3Cell,
+        p_model_id:  modelId ?? null,
+      }),
+    },
+  );
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`claimJob RPC failed: ${resp.status} ${text}`);
+  }
+
+  const rows = await resp.json() as HiveJob[];
+  return rows[0] ?? null;
+}
+
+// ─── Mark computing ───────────────────────────────────────────
+
+export async function markComputing(jobId: string): Promise<void> {
+  await patchJob(jobId, { status: 'computing' });
+}
+
+// ─── Post result ──────────────────────────────────────────────
+
+export async function postResult(jobId: string, result: JobResult): Promise<void> {
+  await patchJob(jobId, {
+    status:           'completed',
+    result_text:      result.resultText,
+    tokens_generated: result.tokensGenerated,
+    tokens_per_second: result.tokensPerSecond,
+    completed_at:     new Date().toISOString(),
+    error_message:    null,
+  });
+}
+
+// ─── Post failure ─────────────────────────────────────────────
+
+export async function postFailure(jobId: string, errorMsg: string): Promise<void> {
+  await patchJob(jobId, {
+    status:        'failed',
+    error_message: errorMsg,
+    completed_at:  new Date().toISOString(),
+  });
+}
+
+// ─── Trigger timeout cleanup (call once per poll cycle) ───────
+
+export async function cleanupTimedOutJobs(): Promise<void> {
+  await fetch(`${SUPABASE_URL}/rest/v1/rpc/timeout_stale_jobs`, {
+    method: 'POST',
+    headers: HEADERS,
+    body: JSON.stringify({}),
+  });
+}
+
+// ─── Fetch a specific job (for status watch) ──────────────────
+
+export async function fetchJob(jobId: string): Promise<HiveJob | null> {
+  const resp = await fetch(
+    `${SUPABASE_URL}/rest/v1/hive_jobs?id=eq.${jobId}&select=*`,
+    { headers: HEADERS },
+  );
+  if (!resp.ok) return null;
+  const rows = await resp.json() as HiveJob[];
+  return rows[0] ?? null;
+}
+
+// ─── Fetch recent completed jobs for this worker ──────────────
+
+export async function fetchRecentCompletedJobs(
+  workerPk: string,
+  limit = 5,
+): Promise<HiveJob[]> {
+  const resp = await fetch(
+    `${SUPABASE_URL}/rest/v1/hive_jobs?worker_pk=eq.${workerPk}&status=eq.completed&order=completed_at.desc&limit=${limit}&select=*`,
+    { headers: HEADERS },
+  );
+  if (!resp.ok) return [];
+  return resp.json() as Promise<HiveJob[]>;
+}
+
+// ─── Patch helper ─────────────────────────────────────────────
+
+async function patchJob(jobId: string, fields: Partial<HiveJob>): Promise<void> {
+  const resp = await fetch(
+    `${SUPABASE_URL}/rest/v1/hive_jobs?id=eq.${jobId}`,
+    {
+      method: 'PATCH',
+      headers: { ...HEADERS, 'Prefer': 'return=minimal' },
+      body: JSON.stringify(fields),
+    },
+  );
+
+  if (!resp.ok && resp.status !== 204) {
+    const text = await resp.text();
+    throw new Error(`patchJob failed: ${resp.status} ${text}`);
+  }
+}
+
+// ─── Poll loop factory ────────────────────────────────────────
+// Returns a controller object so cli.ts can stop it cleanly
+
+export interface PollController {
+  stop: () => void;
+  isRunning: () => boolean;
+}
+
+export function startJobPoller(opts: {
+  workerPk:  string;
+  h3Cell:    string;
+  intervalMs: number;
+  onJobClaimed:   (job: HiveJob) => void;
+  onJobCompleted: (job: HiveJob, result: JobResult) => void;
+  onJobFailed:    (job: HiveJob, error: string) => void;
+  onLog:          (msg: string) => void;
+  executor:       (job: HiveJob) => Promise<JobResult>;
+}): PollController {
+  let running = true;
+  let busy = false;
+
+  const tick = async () => {
+    if (!running || busy) return;
+
+    try {
+      // Run cleanup once per cycle
+      await cleanupTimedOutJobs().catch(() => {});
+
+      const job = await claimJob(opts.workerPk, opts.h3Cell);
+      if (!job) return;
+
+      // Got one
+      busy = true;
+      opts.onJobClaimed(job);
+
+      try {
+        await markComputing(job.id);
+
+        const result = await opts.executor(job);
+
+        await postResult(job.id, result);
+        opts.onJobCompleted(job, result);
+      } catch (execErr) {
+        const errMsg = execErr instanceof Error ? execErr.message : String(execErr);
+        await postFailure(job.id, errMsg).catch(() => {});
+        opts.onJobFailed(job, errMsg);
+        opts.onLog(`Job ${job.id.slice(0, 8)} failed: ${errMsg}`);
+      } finally {
+        busy = false;
+      }
+    } catch (pollErr) {
+      opts.onLog(`Poll error: ${pollErr instanceof Error ? pollErr.message : String(pollErr)}`);
+    }
+  };
+
+  const timer = setInterval(tick, opts.intervalMs);
+
+  return {
+    stop: () => {
+      running = false;
+      clearInterval(timer);
+    },
+    isRunning: () => running,
+  };
+}

package/src/llama.ts

@@ -0,0 +1,79 @@
+// ============================================================
+// HIVE WORKER — LLAMA.CPP RPC SERVER
+// Start / stop the llama.cpp rpc-server process
+// Detects binary location, manages lifecycle
+// ============================================================
+
+import { spawn, type ChildProcess } from 'child_process';
+import { execSync } from 'child_process';
+import os from 'os';
+
+export const DEFAULT_RPC_PORT = 50052;
+
+export interface LlamaRpcHandle {
+  process: ChildProcess;
+  port: number;
+  pid: number;
+}
+
+const RPC_BINARY_CANDIDATES = [
+  'rpc-server',
+  'llama-rpc-server',
+  '/usr/local/bin/rpc-server',
+  `${os.homedir()}/llama.cpp/rpc-server`,
+  `${os.homedir()}/llama.cpp/build/bin/rpc-server`,
+  `${os.homedir()}/llama.cpp/build/rpc-server`,
+];
+
+export function findRpcBinary(): string | null {
+  for (const candidate of RPC_BINARY_CANDIDATES) {
+    try {
+      execSync(`which "${candidate}" 2>/dev/null || test -f "${candidate}"`, { timeout: 2000 });
+      return candidate;
+    } catch { }
+  }
+  try {
+    execSync('rpc-server --help 2>&1 | head -1', { timeout: 2000 });
+    return 'rpc-server';
+  } catch { }
+  return null;
+}
+
+export function isRpcServerAvailable(): boolean {
+  return findRpcBinary() !== null;
+}
+
+export function startRpcServer(
+  port: number = DEFAULT_RPC_PORT,
+  onLog?: (line: string) => void,
+): LlamaRpcHandle | null {
+  const binary = findRpcBinary();
+  if (!binary) return null;
+
+  const isAppleSilicon = os.platform() === 'darwin' && os.arch() === 'arm64';
+  const args = ['--host', '0.0.0.0', '--port', String(port)];
+  if (isAppleSilicon) args.push('-d', 'CPU');
+
+  const proc = spawn(binary, args, {
+    detached: false,
+    stdio: ['ignore', 'ignore', 'ignore'],
+  });
+
+  return { process: proc, port, pid: proc.pid ?? 0 };
+}
+
+export function stopRpcServer(handle: LlamaRpcHandle): void {
+  try {
+    handle.process.kill('SIGTERM');
+  } catch { }
+}
+
+export async function isPortFree(port: number): Promise<boolean> {
+  const net = await import('net');
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => { server.close(); resolve(true); });
+    server.listen(port, '127.0.0.1');
+  });
+}

package/src/registry.ts

@@ -0,0 +1,160 @@
+// ============================================================
+// HIVE WORKER — REGISTRY
+// Supabase swarm_nodes: register, heartbeat, deregister
+// Matches the schema built on March 25, 2026
+// ============================================================
+
+import type { HiveIdentity } from './identity.js';
+import type { HardwareProfile, GeoProfile } from './hardware.js';
+
+const SUPABASE_URL = 'https://kaqwkxfaclyqjlfhxrmt.supabase.co';
+const SUPABASE_ANON = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImthcXdreGZhY2x5cWpsZmh4cm10Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI4MzU4NTAsImV4cCI6MjA4ODQxMTg1MH0.ClyWNGRxQjpKYzIROPZBqTXDsWvJioGe9pQymDOYBTc';
+
+const HEADERS = {
+  'apikey': SUPABASE_ANON,
+  'Authorization': `Bearer ${SUPABASE_ANON}`,
+  'Content-Type': 'application/json',
+  'Prefer': 'resolution=merge-duplicates,return=minimal',
+};
+
+export type WorkerStatus = 'idle' | 'computing' | 'offline';
+
+export interface SwarmNode {
+  pk: string;
+  h3_cell: string;
+  handle: string | null;
+  hardware: HardwareProfile;
+  geo: GeoProfile;
+  status: WorkerStatus;
+  last_heartbeat: string;
+  tokens_earned: number;
+  rpc_port: number | null;
+  worker_version: string;
+}
+
+export interface RegistryStats {
+  totalNodes: number;
+  activeNodes: number;
+  totalTflops: number;
+}
+
+async function supabase(
+  method: string,
+  table: string,
+  body?: unknown,
+  query?: string,
+): Promise<Response> {
+  const url = `${SUPABASE_URL}/rest/v1/${table}${query ? '?' + query : ''}`;
+  return fetch(url, {
+    method,
+    headers: HEADERS,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+}
+
+// ─── Registration ─────────────────────────────────────────────
+
+export async function registerNode(
+  identity: HiveIdentity,
+  hw: HardwareProfile,
+  geo: GeoProfile,
+  handle: string | null,
+  rpcPort: number | null,
+): Promise<void> {
+  const node: SwarmNode = {
+    pk: identity.pk,
+    h3_cell: geo.h3Cell,
+    handle,
+    hardware: hw,
+    geo,
+    status: 'idle',
+    last_heartbeat: new Date().toISOString(),
+    tokens_earned: await getExistingTokens(identity.pk),
+    rpc_port: rpcPort,
+    worker_version: '0.1.0',
+  };
+
+  // Upsert — on conflict update everything except tokens_earned
+  const resp = await supabase(
+    'POST',
+    'swarm_nodes',
+    node,
+    'on_conflict=pk',
+  );
+
+  if (!resp.ok) {
+    const err = await resp.text();
+    throw new Error(`Registry registration failed: ${resp.status} ${err}`);
+  }
+}
+
+async function getExistingTokens(pk: string): Promise<number> {
+  try {
+    const resp = await supabase('GET', 'swarm_nodes', undefined, `pk=eq.${pk}&select=tokens_earned`);
+    if (!resp.ok) return 0;
+    const rows = await resp.json() as Array<{ tokens_earned: number }>;
+    return rows[0]?.tokens_earned ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+// ─── Heartbeat ─────────────────────────────────────────────
+
+export async function heartbeat(
+  pk: string,
+  status: WorkerStatus,
+): Promise<void> {
+  const resp = await supabase(
+    'PATCH',
+    'swarm_nodes',
+    { status, last_heartbeat: new Date().toISOString() },
+    `pk=eq.${pk}`,
+  );
+
+  if (!resp.ok && resp.status !== 204) {
+    throw new Error(`Heartbeat failed: ${resp.status}`);
+  }
+}
+
+// ─── Deregister (graceful shutdown) ─────────────────────────
+
+export async function deregisterNode(pk: string): Promise<void> {
+  await supabase(
+    'PATCH',
+    'swarm_nodes',
+    { status: 'offline', last_heartbeat: new Date().toISOString() },
+    `pk=eq.${pk}`,
+  );
+}
+
+// ─── Stats (for dashboard) ──────────────────────────────────
+
+export async function fetchSwarmStats(): Promise<RegistryStats> {
+  try {
+    const resp = await supabase('GET', 'swarm_nodes', undefined, 'select=pk,status,hardware');
+    if (!resp.ok) return { totalNodes: 0, activeNodes: 0, totalTflops: 0 };
+    const rows = await resp.json() as Array<{ status: string; hardware: HardwareProfile }>;
+    const totalNodes = rows.length;
+    const activeNodes = rows.filter(r => r.status !== 'offline').length;
+    const totalTflops = rows
+      .filter(r => r.status !== 'offline')
+      .reduce((sum, r) => sum + (r.hardware?.estimatedTflops ?? 0), 0);
+    return { totalNodes, activeNodes, totalTflops: Math.round(totalTflops * 10) / 10 };
+  } catch {
+    return { totalNodes: 0, activeNodes: 0, totalTflops: 0 };
+  }
+}
+
+// ─── Token balance ──────────────────────────────────────────
+
+export async function fetchTokenBalance(pk: string): Promise<number> {
+  try {
+    const resp = await supabase('GET', 'swarm_nodes', undefined, `pk=eq.${pk}&select=tokens_earned`);
+    if (!resp.ok) return 0;
+    const rows = await resp.json() as Array<{ tokens_earned: number }>;
+    return rows[0]?.tokens_earned ?? 0;
+  } catch {
+    return 0;
+  }
+}

package/src/settlement.ts

@@ -0,0 +1,145 @@
+// ============================================================
+// HIVE WORKER — SETTLEMENT
+// After a job completes, credit GNS to the worker's
+// tokens_earned balance in Supabase.
+//
+// Real Stellar settlement (the 60/25/10/5 split) runs
+// server-side in the orchestrator. The worker just reads
+// its credited balance here.
+//
+// This module:
+//   1. Increments tokens_earned in swarm_nodes (optimistic)
+//   2. Marks job.settled = true
+//   3. Polls for the actual Stellar TX hash from the orchestrator
+// ============================================================
+
+const SUPABASE_URL = 'https://kaqwkxfaclyqjlfhxrmt.supabase.co';
+const SUPABASE_ANON = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImthcXdreGZhY2x5cWpsZmh4cm10Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI4MzU4NTAsImV4cCI6MjA4ODQxMTg1MH0.ClyWNGRxQjpKYzIROPZBqTXDsWvJioGe9pQymDOYBTc';
+
+const HEADERS = {
+  'apikey': SUPABASE_ANON,
+  'Authorization': `Bearer ${SUPABASE_ANON}`,
+  'Content-Type': 'application/json',
+  'Prefer': 'return=minimal',
+};
+
+// GNS split ratios (matches whitepaper §8.1 and March 25 settlement)
+export const SPLIT = {
+  WORKER:     0.60,  // community node operators
+  PLATFORM:   0.25,  // GEIANT / ULISSY orchestration
+  HYDRATION:  0.10,  // hydration & resilience fund
+  SOVEREIGN:  0.05,  // BFT quorum coordinators
+} as const;
+
+export interface SettlementRecord {
+  jobId:        string;
+  workerPk:     string;
+  grossReward:  number;  // full gns_reward from hive_jobs
+  workerSlice:  number;  // 60% of gross
+  settledAt:    string;
+  stellarTxHash: string | null;
+}
+
+// ─── Credit worker (local optimistic update) ──────────────────
+// Increments tokens_earned in swarm_nodes by the 60% worker slice.
+// The orchestrator does the actual Stellar TX — we just reflect it here.
+
+export async function creditWorker(
+  workerPk: string,
+  jobId: string,
+  grossReward: number,
+): Promise<SettlementRecord> {
+  const workerSlice = Math.round(grossReward * SPLIT.WORKER * 1_000_000) / 1_000_000;
+
+  // Step 1: increment tokens_earned via Postgres RPC
+  await incrementTokens(workerPk, workerSlice);
+
+  // Step 2: mark job settled (tx hash comes from orchestrator async)
+  await markJobSettled(jobId, workerSlice);
+
+  // Step 3: poll for Stellar TX hash (up to 30s, non-blocking)
+  const stellarTxHash = await pollForTxHash(jobId);
+
+  return {
+    jobId,
+    workerPk,
+    grossReward,
+    workerSlice,
+    settledAt: new Date().toISOString(),
+    stellarTxHash,
+  };
+}
+
+// ─── Supabase RPC: atomic increment ──────────────────────────
+
+async function incrementTokens(workerPk: string, amount: number): Promise<void> {
+  // Use a raw SQL RPC to do atomic increment (no race condition)
+  const resp = await fetch(`${SUPABASE_URL}/rest/v1/rpc/increment_worker_tokens`, {
+    method: 'POST',
+    headers: HEADERS,
+    body: JSON.stringify({ p_worker_pk: workerPk, p_amount: amount }),
+  });
+
+  if (!resp.ok) {
+    // Fallback: PATCH with current + amount (non-atomic, acceptable for v0.1)
+    await fallbackIncrementTokens(workerPk, amount);
+  }
+}
+
+async function fallbackIncrementTokens(workerPk: string, amount: number): Promise<void> {
+  // Read current balance
+  const getResp = await fetch(
+    `${SUPABASE_URL}/rest/v1/swarm_nodes?pk=eq.${workerPk}&select=tokens_earned`,
+    { headers: HEADERS },
+  );
+  if (!getResp.ok) return;
+  const rows = await getResp.json() as Array<{ tokens_earned: number }>;
+  const current = rows[0]?.tokens_earned ?? 0;
+
+  // Write new total
+  await fetch(`${SUPABASE_URL}/rest/v1/swarm_nodes?pk=eq.${workerPk}`, {
+    method: 'PATCH',
+    headers: HEADERS,
+    body: JSON.stringify({ tokens_earned: current + amount }),
+  });
+}
+
+async function markJobSettled(jobId: string, workerSlice: number): Promise<void> {
+  await fetch(`${SUPABASE_URL}/rest/v1/hive_jobs?id=eq.${jobId}`, {
+    method: 'PATCH',
+    headers: HEADERS,
+    body: JSON.stringify({ settled: true }),
+  });
+}
+
+async function pollForTxHash(jobId: string, maxWaitMs = 30_000): Promise<string | null> {
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() < deadline) {
+    await sleep(3000);
+    const resp = await fetch(
+      `${SUPABASE_URL}/rest/v1/hive_jobs?id=eq.${jobId}&select=stellar_tx_hash`,
+      { headers: HEADERS },
+    );
+    if (!resp.ok) break;
+    const rows = await resp.json() as Array<{ stellar_tx_hash: string | null }>;
+    const hash = rows[0]?.stellar_tx_hash;
+    if (hash) return hash;
+  }
+  return null;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(res => setTimeout(res, ms));
+}
+
+// ─── SQL to add to supabase_migration.sql ────────────────────
+// (included here as a comment so it's easy to find)
+//
+// CREATE OR REPLACE FUNCTION increment_worker_tokens(
+//   p_worker_pk TEXT,
+//   p_amount    NUMERIC
+// ) RETURNS VOID AS $$
+//   UPDATE swarm_nodes
+//   SET tokens_earned = tokens_earned + p_amount
+//   WHERE pk = p_worker_pk;
+// $$ LANGUAGE SQL;

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}