@nimbus-sh/core 0.1.0

package/src/substrate/lifo/kernel/storage/BlobStore.ts

@@ -0,0 +1,114 @@
+// Content-addressable blob storage using FNV-1a hashing.
+// No external dependencies.
+
+// ---------------------------------------------------------------------------
+// FNV-1a 64-bit hash
+// ---------------------------------------------------------------------------
+
+// FNV-1a 64-bit offset basis: 0xcbf29ce484222325
+const FNV_OFFSET_HIGH = 0xcbf29ce4;
+const FNV_OFFSET_LOW = 0x84222325;
+
+// FNV-1a 64-bit prime: 0x00000100000001b3
+const FNV_PRIME_LOW = 0x000001b3;
+const FNV_PRIME_HIGH_BYTE = 0x01; // the 0x100 component that lands in the high word
+
+/**
+ * Compute a 64-bit FNV-1a hash of the given bytes and return it as a
+ * 16-character lowercase hex string.
+ *
+ * We split the 64-bit state into two 32-bit halves (high, low) and apply
+ * the FNV-1a algorithm byte-by-byte: xor then multiply by the prime.
+ */
+export function hashBytes(data: Uint8Array): string {
+  let high = FNV_OFFSET_HIGH;
+  let low = FNV_OFFSET_LOW;
+
+  for (let i = 0; i < data.length; i++) {
+    // XOR the byte into the low 32 bits of the hash state
+    low ^= data[i];
+
+    // Multiply the 64-bit state by the 64-bit prime 0x00000100_000001b3.
+    //
+    // The prime has two non-zero components:
+    //   - 0x000001b3 in the low word
+    //   - 0x100 that shifts the old low word into the high word
+    //
+    // Full product (only lower 64 bits kept):
+    //   new_low  = (low * 0x1b3) & 0xFFFFFFFF
+    //   new_high = (high * 0x1b3) + (low * 0x100) + carry_from_low_multiply
+
+    // Split low into 16-bit halves for precise integer multiplication.
+    const a = low & 0xFFFF;
+    const b = (low >>> 16) & 0xFFFF;
+
+    const aTimesPrime = a * FNV_PRIME_LOW;
+    const bTimesPrime = b * FNV_PRIME_LOW;
+
+    const newLowLo = aTimesPrime & 0xFFFF;
+    const mid = (aTimesPrime >>> 16) + (bTimesPrime & 0xFFFF);
+    const newLowHi = mid & 0xFFFF;
+    const carry = (mid >>> 16) + (bTimesPrime >>> 16);
+
+    const newLow = ((newLowHi << 16) | newLowLo) >>> 0;
+
+    // high word contribution:
+    //   high * prime_low   (only lower 32 bits matter)
+    // + low  * 0x100       (the prime's high component shifts low into high)
+    // + carry              (from the low multiplication above)
+    const newHigh =
+      ((Math.imul(high, FNV_PRIME_LOW) + Math.imul(low, FNV_PRIME_HIGH_BYTE << 8) + carry) |
+        0) >>>
+      0;
+
+    low = newLow;
+    high = newHigh;
+  }
+
+  const highHex = high.toString(16).padStart(8, '0');
+  const lowHex = low.toString(16).padStart(8, '0');
+  return highHex + lowHex;
+}
+
+// ---------------------------------------------------------------------------
+// BlobStore interface
+// ---------------------------------------------------------------------------
+
+export interface BlobStore {
+  get(hash: string): Promise<Uint8Array | null>;
+  put(data: Uint8Array): Promise<string>;
+  delete(hash: string): Promise<void>;
+  has(hash: string): Promise<boolean>;
+}
+
+// ---------------------------------------------------------------------------
+// MemoryBlobStore
+// ---------------------------------------------------------------------------
+
+export class MemoryBlobStore implements BlobStore {
+  private blobs = new Map<string, Uint8Array>();
+
+  async get(hash: string): Promise<Uint8Array | null> {
+    const data = this.blobs.get(hash);
+    if (!data) return null;
+    // Return a copy so callers cannot mutate internal state.
+    return new Uint8Array(data);
+  }
+
+  async put(data: Uint8Array): Promise<string> {
+    const hash = hashBytes(data);
+    if (!this.blobs.has(hash)) {
+      // Store a copy so the caller cannot mutate what we hold.
+      this.blobs.set(hash, new Uint8Array(data));
+    }
+    return hash;
+  }
+
+  async delete(hash: string): Promise<void> {
+    this.blobs.delete(hash);
+  }
+
+  async has(hash: string): Promise<boolean> {
+    return this.blobs.has(hash);
+  }
+}

package/src/substrate/lifo/kernel/storage/ContentStore.ts

@@ -0,0 +1,150 @@
+/**
+ * Synchronous, in-memory content-addressable store with LRU eviction.
+ *
+ * The VFS API is fully synchronous, so we need a sync cache for file content.
+ * Large files (>= CHUNK_THRESHOLD) are split into fixed-size chunks and stored
+ * here, keeping INodes lightweight (metadata-only, no inline data).
+ *
+ * The LRU eviction removes least-recently-accessed entries when the total
+ * stored bytes exceed the configured budget.
+ */
+
+import { hashBytes } from './BlobStore.js';
+
+// ─── Constants ───
+
+/** Files at or above this size are chunked rather than stored inline.
+ *  Set high to avoid LRU eviction silently losing file data during npm install
+ *  (many packages installed back-to-back can exceed the ContentStore budget). */
+export const CHUNK_THRESHOLD = 50 * 1024 * 1024; // 50 MB
+
+/** Size of each chunk for large files. */
+export const CHUNK_SIZE = 256 * 1024; // 256 KB
+
+// ─── Chunk descriptor ───
+
+export interface ChunkRef {
+  hash: string;
+  size: number;
+}
+
+// ─── ContentStore ───
+
+interface CacheEntry {
+  data: Uint8Array;
+  lastAccess: number; // monotonic counter, NOT wall-clock
+}
+
+export class ContentStore {
+  private cache = new Map<string, CacheEntry>();
+  private accessCounter = 0;
+  private totalBytes = 0;
+  private maxBytes: number;
+
+  constructor(maxBytes: number = 64 * 1024 * 1024) { // 64 MB default
+    this.maxBytes = maxBytes;
+  }
+
+  /** Retrieve a blob by hash. Returns null if not in cache. */
+  get(hash: string): Uint8Array | null {
+    const entry = this.cache.get(hash);
+    if (!entry) return null;
+    entry.lastAccess = ++this.accessCounter;
+    return entry.data;
+  }
+
+  /** Store a blob. Returns its content hash. Deduplicates by hash. */
+  put(data: Uint8Array): string {
+    const hash = hashBytes(data);
+    if (this.cache.has(hash)) {
+      this.cache.get(hash)!.lastAccess = ++this.accessCounter;
+      return hash;
+    }
+    this.cache.set(hash, { data, lastAccess: ++this.accessCounter });
+    this.totalBytes += data.byteLength;
+    this.evict();
+    return hash;
+  }
+
+  /** Remove a blob from the cache. */
+  delete(hash: string): void {
+    const entry = this.cache.get(hash);
+    if (entry) {
+      this.totalBytes -= entry.data.byteLength;
+      this.cache.delete(hash);
+    }
+  }
+
+  /** Check if a hash exists in the cache. */
+  has(hash: string): boolean {
+    return this.cache.has(hash);
+  }
+
+  /** Current total bytes in cache. */
+  get size(): number {
+    return this.totalBytes;
+  }
+
+  /** Number of entries in cache. */
+  get count(): number {
+    return this.cache.size;
+  }
+
+  // ─── Chunking helpers ───
+
+  /**
+   * Split data into chunks, store each, and return the chunk manifest.
+   */
+  storeChunked(data: Uint8Array): ChunkRef[] {
+    const chunks: ChunkRef[] = [];
+    for (let offset = 0; offset < data.byteLength; offset += CHUNK_SIZE) {
+      const end = Math.min(offset + CHUNK_SIZE, data.byteLength);
+      const chunk = data.subarray(offset, end);
+      const hash = this.put(chunk);
+      chunks.push({ hash, size: chunk.byteLength });
+    }
+    return chunks;
+  }
+
+  /**
+   * Reassemble data from a chunk manifest.
+   * Returns null if any chunk is missing from cache.
+   */
+  loadChunked(chunks: ChunkRef[]): Uint8Array | null {
+    const totalSize = chunks.reduce((sum, c) => sum + c.size, 0);
+    const result = new Uint8Array(totalSize);
+    let offset = 0;
+    for (const chunk of chunks) {
+      const data = this.get(chunk.hash);
+      if (!data) return null;
+      result.set(data, offset);
+      offset += chunk.size;
+    }
+    return result;
+  }
+
+  /**
+   * Remove all chunks in a manifest from the cache.
+   */
+  deleteChunked(chunks: ChunkRef[]): void {
+    for (const chunk of chunks) {
+      this.delete(chunk.hash);
+    }
+  }
+
+  // ─── LRU eviction ───
+
+  private evict(): void {
+    if (this.totalBytes <= this.maxBytes) return;
+
+    // Sort entries by lastAccess (oldest first) and evict until under budget
+    const entries = Array.from(this.cache.entries())
+      .sort((a, b) => a[1].lastAccess - b[1].lastAccess);
+
+    for (const [hash, entry] of entries) {
+      if (this.totalBytes <= this.maxBytes) break;
+      this.totalBytes -= entry.data.byteLength;
+      this.cache.delete(hash);
+    }
+  }
+}

package/src/substrate/lifo/kernel/storage/index.ts

@@ -0,0 +1,5 @@
+export { hashBytes } from './BlobStore.js';
+export type { BlobStore } from './BlobStore.js';
+export { MemoryBlobStore } from './BlobStore.js';
+export { ContentStore, CHUNK_THRESHOLD, CHUNK_SIZE } from './ContentStore.js';
+export type { ChunkRef } from './ContentStore.js';

package/src/substrate/lifo/kernel/unit-parser.ts

@@ -0,0 +1,95 @@
+/**
+ * INI-style unit file parser for systemd-like service definitions.
+ */
+
+export interface UnitFile {
+  Unit: {
+    Description?: string;
+  };
+  Service: {
+    ExecStart?: string;
+    ExecStop?: string;
+    Type?: 'simple' | 'oneshot';
+    Restart?: 'no' | 'always' | 'on-failure';
+    RestartSec?: number;
+    Environment?: Record<string, string>;
+    WorkingDirectory?: string;
+  };
+  Install: {
+    WantedBy?: string;
+  };
+}
+
+export function parseUnitFile(content: string): UnitFile {
+  const unit: UnitFile = {
+    Unit: {},
+    Service: {},
+    Install: {},
+  };
+
+  let currentSection: keyof UnitFile | null = null;
+
+  for (const raw of content.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+
+    const sectionMatch = line.match(/^\[(\w+)\]$/);
+    if (sectionMatch) {
+      const name = sectionMatch[1] as keyof UnitFile;
+      if (name in unit) {
+        currentSection = name;
+      }
+      continue;
+    }
+
+    if (!currentSection) continue;
+
+    const eqIdx = line.indexOf('=');
+    if (eqIdx === -1) continue;
+
+    const key = line.slice(0, eqIdx).trim();
+    const value = line.slice(eqIdx + 1).trim();
+
+    switch (currentSection) {
+      case 'Unit':
+        if (key === 'Description') unit.Unit.Description = value;
+        break;
+      case 'Service':
+        switch (key) {
+          case 'ExecStart': unit.Service.ExecStart = value; break;
+          case 'ExecStop': unit.Service.ExecStop = value; break;
+          case 'Type':
+            if (value === 'simple' || value === 'oneshot') unit.Service.Type = value;
+            break;
+          case 'Restart':
+            if (value === 'no' || value === 'always' || value === 'on-failure') unit.Service.Restart = value;
+            break;
+          case 'RestartSec':
+            unit.Service.RestartSec = parseInt(value, 10) || 0;
+            break;
+          case 'Environment': {
+            if (!unit.Service.Environment) unit.Service.Environment = {};
+            // Parse KEY=VALUE pairs (space-separated)
+            for (const pair of value.split(/\s+/)) {
+              const pairEq = pair.indexOf('=');
+              if (pairEq !== -1) {
+                const k = pair.slice(0, pairEq);
+                const v = pair.slice(pairEq + 1).replace(/^"|"$/g, '');
+                unit.Service.Environment[k] = v;
+              }
+            }
+            break;
+          }
+          case 'WorkingDirectory':
+            unit.Service.WorkingDirectory = value;
+            break;
+        }
+        break;
+      case 'Install':
+        if (key === 'WantedBy') unit.Install.WantedBy = value;
+        break;
+    }
+  }
+
+  return unit;
+}