nebula-ai-core 0.1.0

package/src/skills/scanner.ts

@@ -0,0 +1,257 @@
+import type { Dirent } from 'node:fs'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { agentPaths } from '../paths'
+import type { SkillFrontmatter, SkillRef, SkillSource } from './types'
+
+/**
+ * Scan the canonical skill locations and return parsed SkillRefs. Skips paths
+ * that don't exist or aren't directories so callers can register all sources
+ * eagerly without needing to probe individually.
+ */
+export interface SkillScannerOptions {
+  /** Whether to scan ~/.claude/skills/ + ~/.claude/plugins/cache/. Default true. */
+  importsClaudeCode?: boolean
+  /** Override for ~/.nebula/skills/ (test seam). Defaults to agentPaths.skills. */
+  nebulaSkillsRoot?: string
+  /** Override for ~/.nebula/plugins/ (test seam). Defaults to agentPaths.plugins. */
+  nebulaPluginsRoot?: string
+  /** Override for ~/.claude/skills/ (test seam). Defaults to ~/.claude/skills. */
+  claudeSkillsRoot?: string
+  /** Override for ~/.claude/plugins/cache/ (test seam). Defaults to ~/.claude/plugins/cache. */
+  claudePluginsCacheRoot?: string
+}
+
+export async function scanSkills(opts: SkillScannerOptions = {}): Promise<SkillRef[]> {
+  const importsClaudeCode = opts.importsClaudeCode ?? true
+  const nebulaSkillsRoot = opts.nebulaSkillsRoot ?? agentPaths.skills
+  const nebulaPluginsRoot = opts.nebulaPluginsRoot ?? agentPaths.plugins
+  const claudeSkillsRoot = opts.claudeSkillsRoot ?? join(homedir(), '.claude', 'skills')
+  const claudePluginsCacheRoot =
+    opts.claudePluginsCacheRoot ?? join(homedir(), '.claude', 'plugins', 'cache')
+
+  const refs: SkillRef[] = []
+  await collectSimple(nebulaSkillsRoot, 'nebula', refs)
+  await collectNebulaPluginSkills(nebulaPluginsRoot, refs)
+  if (importsClaudeCode) {
+    await collectSimple(claudeSkillsRoot, 'claude-code', refs)
+    await collectClaudePluginCacheSkills(claudePluginsCacheRoot, refs)
+  }
+  return refs
+}
+
+async function dirEntries(path: string): Promise<Dirent[] | null> {
+  try {
+    const s = await stat(path)
+    if (!s.isDirectory()) return null
+  } catch {
+    return null
+  }
+  try {
+    return (await readdir(path, { withFileTypes: true })) as Dirent[]
+  } catch {
+    return null
+  }
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    const s = await stat(path)
+    return s.isFile()
+  } catch {
+    return false
+  }
+}
+
+async function collectSimple(
+  root: string,
+  source: Extract<SkillSource, 'nebula' | 'claude-code'>,
+  out: SkillRef[],
+): Promise<void> {
+  const entries = await dirEntries(root)
+  if (!entries) return
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const skillPath = join(root, entry.name, 'SKILL.md')
+    if (!(await fileExists(skillPath))) continue
+    const ref = await loadSkill(skillPath, entry.name, source)
+    if (ref) out.push(ref)
+  }
+}
+
+async function collectNebulaPluginSkills(pluginsRoot: string, out: SkillRef[]): Promise<void> {
+  const plugins = await dirEntries(pluginsRoot)
+  if (!plugins) return
+  for (const plugin of plugins) {
+    if (!plugin.isDirectory()) continue
+    const skillsRoot = join(pluginsRoot, plugin.name, 'skills')
+    const skills = await dirEntries(skillsRoot)
+    if (!skills) continue
+    for (const skill of skills) {
+      if (!skill.isDirectory()) continue
+      const skillPath = join(skillsRoot, skill.name, 'SKILL.md')
+      if (!(await fileExists(skillPath))) continue
+      const ref = await loadSkill(skillPath, `${plugin.name}:${skill.name}`, 'nebula-plugin')
+      if (ref) out.push(ref)
+    }
+  }
+}
+
+async function collectClaudePluginCacheSkills(cacheRoot: string, out: SkillRef[]): Promise<void> {
+  const marketplaces = await dirEntries(cacheRoot)
+  if (!marketplaces) return
+  for (const marketplace of marketplaces) {
+    if (!marketplace.isDirectory()) continue
+    const marketDir = join(cacheRoot, marketplace.name)
+    const plugins = await dirEntries(marketDir)
+    if (!plugins) continue
+    for (const plugin of plugins) {
+      if (!plugin.isDirectory()) continue
+      // Layer 1: <market>/<plugin>/<version>/skills/<skill>/SKILL.md
+      // Layer 2: <market>/<plugin>/skills/<skill>/SKILL.md (no version dir)
+      // Try the version layer first; fall back to direct.
+      const versions = await dirEntries(join(marketDir, plugin.name))
+      if (!versions) continue
+      for (const versionEntry of versions) {
+        if (!versionEntry.isDirectory()) continue
+        const versionDir = join(marketDir, plugin.name, versionEntry.name)
+        // Two valid shapes; both checked.
+        await collectClaudeSkillsFromVersion(
+          versionDir,
+          marketplace.name,
+          plugin.name,
+          versionEntry.name,
+          out,
+        )
+      }
+    }
+  }
+}
+
+async function collectClaudeSkillsFromVersion(
+  versionDir: string,
+  marketplace: string,
+  plugin: string,
+  version: string,
+  out: SkillRef[],
+): Promise<void> {
+  const skillsDir = join(versionDir, 'skills')
+  const direct = await fileExists(join(versionDir, 'SKILL.md'))
+  if (direct) {
+    const ref = await loadSkill(
+      join(versionDir, 'SKILL.md'),
+      `${marketplace}:${plugin}`,
+      'claude-plugin',
+    )
+    if (ref) {
+      ref.pluginCoord = { marketplace, plugin, version }
+      out.push(ref)
+    }
+  }
+  const skills = await dirEntries(skillsDir)
+  if (!skills) return
+  for (const skill of skills) {
+    if (!skill.isDirectory()) continue
+    const skillPath = join(skillsDir, skill.name, 'SKILL.md')
+    if (!(await fileExists(skillPath))) continue
+    const id = `${marketplace}:${plugin}:${skill.name}`
+    const ref = await loadSkill(skillPath, id, 'claude-plugin')
+    if (ref) {
+      ref.pluginCoord = { marketplace, plugin, version }
+      out.push(ref)
+    }
+  }
+}
+
+async function loadSkill(
+  path: string,
+  fallbackId: string,
+  source: SkillSource,
+): Promise<SkillRef | null> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return null
+  }
+  const fm = parseFrontmatter(raw)
+  // Skills without YAML frontmatter are still surfaced; we derive name from
+  // the directory and description from the first heading or paragraph so the
+  // brain can find them via `skills.list`.
+  const name = fm.name ?? fallbackId
+  const description = fm.description ?? deriveDescription(raw)
+  return {
+    id: `${source}:${fallbackId}`,
+    name,
+    description,
+    path,
+    source,
+    frontmatter: { name, description, ...fm },
+  }
+}
+
+function deriveDescription(raw: string): string {
+  const body = raw.startsWith('---') ? raw.slice(raw.indexOf('\n---', 4) + 4) : raw
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    if (trimmed.startsWith('#')) continue
+    return trimmed.slice(0, 200)
+  }
+  return ''
+}
+
+const KEY_RE = /^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/
+
+/**
+ * Minimal YAML frontmatter parser (top-level + one nested level for `metadata:`).
+ * We avoid pulling in a full YAML lib because skills only need a tiny subset and
+ * scan time runs on every chat boot.
+ */
+export function parseFrontmatter(raw: string): Partial<SkillFrontmatter> {
+  if (!raw.startsWith('---')) return {}
+  const end = raw.indexOf('\n---', 4)
+  if (end === -1) return {}
+  const block = raw.slice(4, end)
+  const out: Partial<SkillFrontmatter> = {}
+  let inMetadata = false
+  for (const rawLine of block.split('\n')) {
+    if (rawLine.trim() === '') {
+      inMetadata = false
+      continue
+    }
+    const indented = rawLine.startsWith('  ') || rawLine.startsWith('\t')
+    const trimmed = rawLine.trim()
+    if (!indented) {
+      inMetadata = false
+      const m = trimmed.match(KEY_RE)
+      if (!m?.[1]) continue
+      const key = m[1]
+      const value = unquote(m[2] ?? '')
+      if (key === 'name') out.name = value
+      else if (key === 'description') out.description = value
+      else if (key === 'version') out.version = value
+      else if (key === 'license') out.license = value
+      else if (key === 'argument-hint' || key === 'argumentHint') out.argumentHint = value
+      else if (key === 'metadata') inMetadata = true
+      continue
+    }
+    if (!inMetadata) continue
+    const m = trimmed.match(KEY_RE)
+    if (!m?.[1]) continue
+    const key = m[1]
+    const value = unquote(m[2] ?? '')
+    if (key === 'filePattern') out.filePattern = value
+    else if (key === 'bashPattern') out.bashPattern = value
+  }
+  return out
+}
+
+function unquote(s: string): string {
+  const t = s.trim()
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1)
+  }
+  return t
+}

package/src/skills/triggers.ts

@@ -0,0 +1,78 @@
+import type { SkillRef } from './types'
+
+/**
+ * Match a comma-separated glob list (`*.test.ts,*.spec.ts`) against an
+ * absolute path. Globs are matched against the basename and against the
+ * trailing path segment (e.g. `tests/foo.spec.ts` matches `tests/*.spec.ts`).
+ */
+export function matchFilePattern(pattern: string, absPath: string): boolean {
+  const globs = pattern
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean)
+  if (globs.length === 0) return false
+  const basename = absPath.split('/').pop() ?? absPath
+  for (const g of globs) {
+    if (globToRegex(g).test(basename) || globToRegex(g).test(absPath)) return true
+  }
+  return false
+}
+
+export function matchBashPattern(pattern: string, command: string): boolean {
+  try {
+    return new RegExp(pattern).test(command)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Find skills whose triggers match the given tool call. Returns the matched
+ * skills paired with the reason (so the brain sees "auto-loaded by file
+ * pattern" or "auto-loaded by bash pattern" in the injected context).
+ */
+export interface SkillTriggerMatch {
+  skill: SkillRef
+  reason: 'filePattern' | 'bashPattern'
+}
+
+export function matchTriggers(
+  call: { name: string; args: unknown },
+  skills: readonly SkillRef[],
+): SkillTriggerMatch[] {
+  const args = (call.args ?? {}) as { path?: unknown; command?: unknown }
+  const matches: SkillTriggerMatch[] = []
+  if (
+    typeof args.path === 'string' &&
+    (call.name === 'fs.read' || call.name === 'fs.write' || call.name === 'fs.patch')
+  ) {
+    for (const skill of skills) {
+      const fp = skill.frontmatter.filePattern
+      if (fp && matchFilePattern(fp, args.path)) {
+        matches.push({ skill, reason: 'filePattern' })
+      }
+    }
+  }
+  if (typeof args.command === 'string' && call.name === 'shell.run') {
+    for (const skill of skills) {
+      const bp = skill.frontmatter.bashPattern
+      if (bp && matchBashPattern(bp, args.command)) {
+        matches.push({ skill, reason: 'bashPattern' })
+      }
+    }
+  }
+  return matches
+}
+
+function globToRegex(glob: string): RegExp {
+  let pat = ''
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]
+    if (c === '*') pat += '.*'
+    else if (c === '?') pat += '.'
+    else if (c === '.') pat += '\\.'
+    else if (c === '/') pat += '/'
+    else pat += c
+  }
+  return new RegExp(`^${pat}$`)
+}

package/src/skills/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Phase 9.1 skills surface. Mirrors Claude Code's SKILL.md frontmatter so
+ * imports.claudeCode picks up the entire ~/.claude ecosystem free.
+ */
+export type SkillSource = 'nebula' | 'nebula-plugin' | 'claude-code' | 'claude-plugin'
+
+export interface SkillFrontmatter {
+  /** Unique name used by the brain to reference this skill. Required. */
+  name: string
+  /** One-line summary the brain sees in the skill index. Required. */
+  description: string
+  version?: string
+  license?: string
+  /** Comma-separated globs (e.g. `*.test.ts,*.spec.ts`) that auto-trigger the skill on fs.* paths. */
+  filePattern?: string
+  /** Regex (string) that auto-triggers the skill on shell.run commands. */
+  bashPattern?: string
+  /**
+   * Claude Code commands set this to distinguish slash-only invocations from
+   * model-invokable skills. Skills omit it; commands set it (any value).
+   */
+  argumentHint?: string
+}
+
+export interface SkillRef {
+  /** `<source-prefix>:<dir-name>` (e.g. `nebula:dogfood`, `claude-code:tmux`). */
+  id: string
+  /** Display name from frontmatter (falls back to directory name). */
+  name: string
+  description: string
+  /** Absolute path to SKILL.md. */
+  path: string
+  source: SkillSource
+  /** When set, marketplace > plugin > version triple from `~/.claude/plugins/cache/...` paths. */
+  pluginCoord?: { marketplace: string; plugin: string; version: string }
+  frontmatter: SkillFrontmatter
+}

package/src/storage/encryption.ts

@@ -0,0 +1,87 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto'
+
+const SCRYPT_N = 1 << 15
+const SCRYPT_R = 8
+const SCRYPT_P = 1
+const SCRYPT_MAXMEM = 64 * 1024 * 1024
+const KEY_LEN = 32
+const IV_LEN = 12
+const TAG_LEN = 16
+const SALT_LEN = 16
+
+/**
+ * AES-256-GCM symmetric encryption, scrypt-derived key from a passphrase.
+ * MVP pattern: each agent has one symmetric key derived from the operator
+ * passphrase. Same scrypt parameters as the wallet keystore for consistency.
+ *
+ * Post-MVP: replace with TEE-sealed key for /agent/ partition + ECIES to
+ * operator pubkey for /user/ partition (section 22 wallet architecture).
+ */
+
+export interface EncryptedEnvelope {
+  /** Random 16-byte salt used to derive the symmetric key. */
+  salt: Uint8Array
+  /** Random 12-byte GCM IV. */
+  iv: Uint8Array
+  /** 16-byte GCM auth tag. */
+  tag: Uint8Array
+  /** Ciphertext. */
+  ciphertext: Uint8Array
+}
+
+export function encrypt(plaintext: Uint8Array, passphrase: string): EncryptedEnvelope {
+  const salt = randomBytes(SALT_LEN)
+  const iv = randomBytes(IV_LEN)
+  const key = scryptSync(passphrase, salt, KEY_LEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: SCRYPT_MAXMEM,
+  })
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()])
+  const tag = cipher.getAuthTag()
+  return {
+    salt,
+    iv,
+    tag: new Uint8Array(tag),
+    ciphertext: new Uint8Array(ciphertext),
+  }
+}
+
+export function decrypt(envelope: EncryptedEnvelope, passphrase: string): Uint8Array {
+  const key = scryptSync(passphrase, envelope.salt, KEY_LEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: SCRYPT_MAXMEM,
+  })
+  const decipher = createDecipheriv('aes-256-gcm', key, envelope.iv)
+  decipher.setAuthTag(envelope.tag)
+  const plaintext = Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()])
+  return new Uint8Array(plaintext)
+}
+
+/** Pack envelope into a single byte buffer for storage: salt || iv || tag || ciphertext. */
+export function packEnvelope(envelope: EncryptedEnvelope): Uint8Array {
+  const total = SALT_LEN + IV_LEN + TAG_LEN + envelope.ciphertext.length
+  const out = new Uint8Array(total)
+  out.set(envelope.salt, 0)
+  out.set(envelope.iv, SALT_LEN)
+  out.set(envelope.tag, SALT_LEN + IV_LEN)
+  out.set(envelope.ciphertext, SALT_LEN + IV_LEN + TAG_LEN)
+  return out
+}
+
+/** Unpack a packed envelope back into its fields. */
+export function unpackEnvelope(packed: Uint8Array): EncryptedEnvelope {
+  if (packed.length < SALT_LEN + IV_LEN + TAG_LEN) {
+    throw new Error('envelope shorter than header')
+  }
+  return {
+    salt: packed.slice(0, SALT_LEN),
+    iv: packed.slice(SALT_LEN, SALT_LEN + IV_LEN),
+    tag: packed.slice(SALT_LEN + IV_LEN, SALT_LEN + IV_LEN + TAG_LEN),
+    ciphertext: packed.slice(SALT_LEN + IV_LEN + TAG_LEN),
+  }
+}

package/src/storage/factory.ts

@@ -0,0 +1,31 @@
+import { join } from 'node:path'
+import { agentPaths } from '../paths'
+import { SqliteStorage } from './sqlite'
+import type { Storage } from './types'
+
+let singleton: SqliteStorage | null = null
+
+/**
+ * Shared, content-addressed local store at `~/.nebula/storage.sqlite`.
+ * Blobs are addressed by their `0x`+sha256 CID, so a single store serves all
+ * agents (a blob put by one is fetchable by hash from any). KV/log entries are
+ * namespaced by streamId. Replaces the prior decentralized storage backend.
+ */
+export function getStorage(): Storage {
+  if (!singleton) {
+    singleton = new SqliteStorage(join(agentPaths.root, 'storage.sqlite'))
+  }
+  return singleton
+}
+
+/**
+ * Back-compat shim for the old "download blob by on-chain root hash" call.
+ * Blobs are content-addressed (rootHash === CID), so this is just `getBlob`.
+ * The network arg is ignored; kept so existing call sites need no reshaping.
+ */
+export async function downloadBlobByRoot(
+  _network: unknown,
+  rootHash: string,
+): Promise<Uint8Array | null> {
+  return getStorage().getBlob(rootHash)
+}

package/src/storage/index.ts

@@ -0,0 +1,11 @@
+export type { Storage } from './types'
+export { LocalStubStorage } from './local-stub'
+export { SqliteStorage } from './sqlite'
+export { getStorage, downloadBlobByRoot } from './factory'
+export {
+  encrypt,
+  decrypt,
+  packEnvelope,
+  unpackEnvelope,
+  type EncryptedEnvelope,
+} from './encryption'

package/src/storage/local-stub.ts

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto'
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Storage } from './types'
+
+/**
+ * Local-disk Storage stub. Layout under `${root}/storage-stub`:
+ *   kv/<streamId>/<url-encoded-key>         — latest value
+ *   log/<streamId>.jsonl                    — append-only JSONL
+ *   blob/<cid>                              — immutable by content hash
+ */
+export class LocalStubStorage implements Storage {
+  constructor(private readonly root: string) {}
+
+  private kvPath(stream: string, key: string): string {
+    return join(this.root, 'storage-stub', 'kv', stream, encodeURIComponent(key))
+  }
+
+  private logPath(stream: string): string {
+    return join(this.root, 'storage-stub', 'log', `${stream}.jsonl`)
+  }
+
+  private blobPath(cid: string): string {
+    return join(this.root, 'storage-stub', 'blob', cid)
+  }
+
+  async putKV(stream: string, key: string, value: Uint8Array): Promise<void> {
+    const p = this.kvPath(stream, key)
+    await mkdir(join(p, '..'), { recursive: true })
+    await writeFile(p, value)
+  }
+
+  async getKV(stream: string, key: string): Promise<Uint8Array | null> {
+    return await readOrNull(this.kvPath(stream, key))
+  }
+
+  async appendLog(stream: string, entry: Uint8Array): Promise<string> {
+    const p = this.logPath(stream)
+    await mkdir(join(p, '..'), { recursive: true })
+    const cid = cidOf(entry)
+    const line = JSON.stringify({ cid, hex: Buffer.from(entry).toString('hex'), ts: Date.now() })
+    await appendFile(p, `${line}\n`)
+    return cid
+  }
+
+  async putBlob(bytes: Uint8Array): Promise<string> {
+    const cid = cidOf(bytes)
+    const p = this.blobPath(cid)
+    await mkdir(join(p, '..'), { recursive: true })
+    await writeFile(p, bytes)
+    return cid
+  }
+
+  async getBlob(cid: string): Promise<Uint8Array | null> {
+    return await readOrNull(this.blobPath(cid))
+  }
+}
+
+async function readOrNull(path: string): Promise<Uint8Array | null> {
+  try {
+    return new Uint8Array(await readFile(path))
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw e
+  }
+}
+
+function cidOf(bytes: Uint8Array): string {
+  return `0x${createHash('sha256').update(bytes).digest('hex')}`
+}

package/src/storage/sqlite.ts

@@ -0,0 +1,95 @@
+import { Database } from 'bun:sqlite'
+import { createHash } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { Storage } from './types'
+
+/**
+ * SQLite-backed Storage (via `bun:sqlite`). Replaces the prior decentralized
+ * blob backend with a local, zero-infra store — ideal for the agent's
+ * encrypted memory and easy to demo. Implements the same three primitives:
+ *   - KV:   mutable value per (stream, key)
+ *   - Log:  append-only entries, each addressed by content CID
+ *   - Blob: immutable, content-addressed bytes
+ *
+ * CID convention matches LocalStubStorage: `0x` + sha256(bytes) hex.
+ */
+export class SqliteStorage implements Storage {
+  private readonly db: Database
+
+  /** @param path SQLite file path (defaults to in-memory). Parent dir is created. */
+  constructor(path = ':memory:') {
+    if (path !== ':memory:') {
+      mkdirSync(dirname(path), { recursive: true })
+    }
+    this.db = new Database(path, { create: true })
+    this.db.run('PRAGMA journal_mode = WAL;')
+    this.db.run(
+      `CREATE TABLE IF NOT EXISTS kv (
+         stream TEXT NOT NULL,
+         key    TEXT NOT NULL,
+         value  BLOB NOT NULL,
+         PRIMARY KEY (stream, key)
+       );`,
+    )
+    this.db.run(
+      `CREATE TABLE IF NOT EXISTS log (
+         id     INTEGER PRIMARY KEY AUTOINCREMENT,
+         stream TEXT NOT NULL,
+         cid    TEXT NOT NULL,
+         entry  BLOB NOT NULL,
+         ts     INTEGER NOT NULL
+       );`,
+    )
+    this.db.run('CREATE INDEX IF NOT EXISTS log_stream_idx ON log (stream, id);')
+    this.db.run(
+      `CREATE TABLE IF NOT EXISTS blob (
+         cid   TEXT PRIMARY KEY,
+         bytes BLOB NOT NULL
+       );`,
+    )
+  }
+
+  async putKV(stream: string, key: string, value: Uint8Array): Promise<void> {
+    this.db
+      .query('INSERT OR REPLACE INTO kv (stream, key, value) VALUES (?, ?, ?)')
+      .run(stream, key, value)
+  }
+
+  async getKV(stream: string, key: string): Promise<Uint8Array | null> {
+    const row = this.db
+      .query('SELECT value FROM kv WHERE stream = ? AND key = ?')
+      .get(stream, key) as { value: Uint8Array } | null
+    return row ? new Uint8Array(row.value) : null
+  }
+
+  async appendLog(stream: string, entry: Uint8Array): Promise<string> {
+    const cid = cidOf(entry)
+    this.db
+      .query('INSERT INTO log (stream, cid, entry, ts) VALUES (?, ?, ?, ?)')
+      .run(stream, cid, entry, Date.now())
+    return cid
+  }
+
+  async putBlob(bytes: Uint8Array): Promise<string> {
+    const cid = cidOf(bytes)
+    this.db.query('INSERT OR IGNORE INTO blob (cid, bytes) VALUES (?, ?)').run(cid, bytes)
+    return cid
+  }
+
+  async getBlob(cid: string): Promise<Uint8Array | null> {
+    const row = this.db.query('SELECT bytes FROM blob WHERE cid = ?').get(cid) as {
+      bytes: Uint8Array
+    } | null
+    return row ? new Uint8Array(row.bytes) : null
+  }
+
+  /** Close the underlying database handle. */
+  close(): void {
+    this.db.close()
+  }
+}
+
+function cidOf(bytes: Uint8Array): string {
+  return `0x${createHash('sha256').update(bytes).digest('hex')}`
+}

package/src/storage/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Storage interface abstracting Mantle Storage's three primitives as used by nebula:
+ *   - KV: mutable key→value per namespace
+ *   - Log: append-only, returns CID per entry
+ *   - Blob: immutable bytes, content-addressed
+ *
+ * Phase 1 ships a local-disk stub. Phase 5 ships the real @0gfoundation/0g-ts-sdk
+ * backend + on-chain-event replay for KV reads (per verified architecture).
+ */
+export interface Storage {
+  /** Put a value into a named stream under a key. */
+  putKV(streamId: string, key: string, value: Uint8Array): Promise<void>
+  /** Get the latest value for (streamId, key) or null. */
+  getKV(streamId: string, key: string): Promise<Uint8Array | null>
+  /** Append an entry to a stream's log. Returns CID (rootHash) of the entry. */
+  appendLog(streamId: string, entry: Uint8Array): Promise<string>
+  /** Upload immutable bytes, returns content CID. */
+  putBlob(bytes: Uint8Array): Promise<string>
+  /** Retrieve bytes by CID. */
+  getBlob(cid: string): Promise<Uint8Array | null>
+}