@sqaoss/flowy 1.2.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
@@ -65,7 +65,6 @@
     "husky": "^9.1.7",
     "lint-staged": "^16.3.0",
     "semantic-release": "25.0.3",
-    "tdd-guard-vitest": "^0.1.6",
     "typescript": "^5",
     "vitest": "^4.1.2"
   },

package/server/src/db.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { createDb } from './db.ts'
+import { LATEST_VERSION } from './migrations.ts'
 
 describe('createDb', () => {
   it('creates nodes and edges tables', () => {
@@ -90,4 +91,51 @@ describe('createDb', () => {
 
     db.close()
   })
+
+  it('runs migrations to the latest user_version on a fresh DB', () => {
+    const db = createDb(':memory:')
+
+    const result = db.raw
+      .query<{ user_version: number }, []>('PRAGMA user_version')
+      .get()
+
+    expect(result?.user_version).toBe(LATEST_VERSION)
+
+    db.close()
+  })
+
+  it('has a writable metadata column on nodes', () => {
+    const db = createDb(':memory:')
+
+    const columns = db.raw
+      .query<{ name: string }, []>('PRAGMA table_info(nodes)')
+      .all()
+      .map((c) => c.name)
+    expect(columns).toContain('metadata')
+
+    expect(() =>
+      db.raw.run(
+        `INSERT INTO nodes (id, type, title, metadata) VALUES ('n1', 'task', 'T', '{"a":1}')`,
+      ),
+    ).not.toThrow()
+
+    db.close()
+  })
+
+  it('accepts the blocked and cancelled statuses', () => {
+    const db = createDb(':memory:')
+
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO nodes (id, type, title, status) VALUES ('n1', 'task', 'T', 'blocked')",
+      ),
+    ).not.toThrow()
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO nodes (id, type, title, status) VALUES ('n2', 'task', 'T', 'cancelled')",
+      ),
+    ).not.toThrow()
+
+    db.close()
+  })
 })

package/server/src/db.ts

@@ -1,4 +1,5 @@
 import { Database } from 'bun:sqlite'
+import { runMigrations } from './migrations.ts'
 
 export type FlowyDb = ReturnType<typeof createDb>
 
@@ -8,37 +9,7 @@ export function createDb(path: string) {
   db.run('PRAGMA journal_mode = WAL')
   db.run('PRAGMA foreign_keys = ON')
 
-  db.run(`
-    CREATE TABLE IF NOT EXISTS nodes (
-      id TEXT PRIMARY KEY,
-      type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
-      title TEXT NOT NULL,
-      description TEXT,
-      status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done', 'blocked', 'cancelled')),
-      metadata TEXT,
-      created_at TEXT NOT NULL DEFAULT (datetime('now')),
-      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
-    )
-  `)
-
-  db.run(`
-    CREATE TABLE IF NOT EXISTS edges (
-      source_id TEXT NOT NULL REFERENCES nodes(id),
-      target_id TEXT NOT NULL REFERENCES nodes(id),
-      relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
-      created_at TEXT NOT NULL DEFAULT (datetime('now')),
-      PRIMARY KEY (source_id, target_id, relation)
-    )
-  `)
-
-  db.run('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)')
-  db.run('CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status)')
-  db.run(
-    'CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id, relation)',
-  )
-  db.run(
-    'CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id, relation)',
-  )
+  runMigrations(db)
 
   return {
     raw: db,

package/server/src/index.errors.test.ts

@@ -94,4 +94,109 @@ describe('server error masking', () => {
     expect(error.message).not.toBe('Unexpected error.')
     expect(error.extensions?.code).toBe('CONFLICT')
   })
+
+  it('round-trips metadata through createNode and the node query', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation ($m: String!) { createNode(type: "task", title: "T", metadata: $m) { id metadata } }',
+      { m: '{"priority":"high"}' },
+    )) as { data: { createNode: { id: string; metadata: string } } }
+    expect(created.data.createNode.metadata).toBe('{"priority":"high"}')
+
+    const id = created.data.createNode.id
+    const fetched = (await gql(
+      'query ($id: String!) { node(id: $id) { metadata } }',
+      { id },
+    )) as { data: { node: { metadata: string } } }
+    expect(JSON.parse(fetched.data.node.metadata)).toEqual({ priority: 'high' })
+  })
+
+  it('updates title/description/status/metadata via updateNode', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "task", title: "Old") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const updated = (await gql(
+      `mutation ($id: String!) {
+        updateNode(id: $id, title: "New", description: "d", status: "in_progress", metadata: "{\\"k\\":1}") {
+          title description status metadata
+        }
+      }`,
+      { id },
+    )) as {
+      data: {
+        updateNode: {
+          title: string
+          description: string
+          status: string
+          metadata: string
+        }
+      }
+    }
+    expect(updated.data.updateNode.title).toBe('New')
+    expect(updated.data.updateNode.description).toBe('d')
+    expect(updated.data.updateNode.status).toBe('in_progress')
+    expect(JSON.parse(updated.data.updateNode.metadata)).toEqual({ k: 1 })
+  })
+
+  it('rejects non-JSON metadata with VALIDATION_ERROR over the wire', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const json = await gql(
+      'mutation { createNode(type: "task", title: "T", metadata: "not json") { id } }',
+    )
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('VALIDATION_ERROR')
+  })
+
+  it('deletes a leaf node via deleteNode', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "task", title: "T") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const del = (await gql('mutation ($id: String!) { deleteNode(id: $id) }', {
+      id,
+    })) as { data: { deleteNode: boolean } }
+    expect(del.data.deleteNode).toBe(true)
+
+    const fetched = (await gql(
+      'query ($id: String!) { node(id: $id) { id } }',
+      {
+        id,
+      },
+    )) as { data: { node: unknown } }
+    expect(fetched.data.node).toBeNull()
+  })
+
+  it('refuses to delete a parent with children (CONFLICT)', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const project = (await gql(
+      'mutation { createNode(type: "project", title: "P") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const feature = (await gql(
+      'mutation { createNode(type: "feature", title: "F") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    await gql(
+      'mutation ($s: String!, $t: String!) { createEdge(sourceId: $s, targetId: $t, relation: "part_of") { relation } }',
+      { s: feature.data.createNode.id, t: project.data.createNode.id },
+    )
+
+    const json = await gql('mutation ($id: String!) { deleteNode(id: $id) }', {
+      id: project.data.createNode.id,
+    })
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('CONFLICT')
+  })
 })

package/server/src/migrations.test.ts

@@ -0,0 +1,218 @@
+import { Database } from 'bun:sqlite'
+import { describe, expect, it } from 'vitest'
+import { LATEST_VERSION, rebuildTable, runMigrations } from './migrations.ts'
+
+function userVersion(db: Database): number {
+  const row = db
+    .query<{ user_version: number }, []>('PRAGMA user_version')
+    .get()
+  return row?.user_version ?? 0
+}
+
+function tableNames(db: Database): string[] {
+  return db
+    .query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
+    )
+    .all()
+    .map((r) => r.name)
+}
+
+function columnNames(db: Database, table: string): string[] {
+  return db
+    .query<{ name: string }, []>(`PRAGMA table_info(${table})`)
+    .all()
+    .map((r) => r.name)
+}
+
+describe('runMigrations', () => {
+  it('brings a fresh DB to the latest user_version', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    db.close()
+  })
+
+  it('creates the nodes and edges tables on a fresh DB', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    const tables = tableNames(db)
+    expect(tables).toContain('nodes')
+    expect(tables).toContain('edges')
+    db.close()
+  })
+
+  it('is a no-op when run twice (idempotent)', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    const versionAfterFirst = userVersion(db)
+    // second run must not throw and must not change the version
+    runMigrations(db)
+    expect(userVersion(db)).toBe(versionAfterFirst)
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    db.close()
+  })
+
+  it('upgrades an old-shaped DB forward without losing data', () => {
+    const db = new Database(':memory:')
+    // Simulate a March-era schema: nodes table WITHOUT a metadata column,
+    // and a CHECK constraint that does not yet allow newer vocabulary.
+    db.run(`
+      CREATE TABLE nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run(
+      "INSERT INTO nodes (id, type, title, description, status) VALUES ('proj_old', 'project', 'Legacy Project', 'from march', 'in_progress')",
+    )
+
+    runMigrations(db)
+
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    // metadata column now exists
+    expect(columnNames(db, 'nodes')).toContain('metadata')
+    // legacy row preserved
+    const row = db
+      .query<
+        { id: string; title: string; status: string; metadata: string | null },
+        []
+      >('SELECT id, title, status, metadata FROM nodes WHERE id = ?')
+      .get('proj_old') as {
+      id: string
+      title: string
+      status: string
+      metadata: string | null
+    }
+    expect(row.id).toBe('proj_old')
+    expect(row.title).toBe('Legacy Project')
+    expect(row.status).toBe('in_progress')
+    db.close()
+  })
+
+  it('after migration the new vocabulary (blocked, cancelled) is accepted', () => {
+    const db = new Database(':memory:')
+    // Old DB with a restrictive status CHECK (no blocked/cancelled)
+    db.run(`
+      CREATE TABLE nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run("INSERT INTO nodes (id, type, title) VALUES ('task_1', 'task', 'T')")
+
+    runMigrations(db)
+
+    // The CHECK rebuild should now permit 'cancelled'
+    expect(() =>
+      db.run("UPDATE nodes SET status = 'cancelled' WHERE id = 'task_1'"),
+    ).not.toThrow()
+  })
+
+  describe('rebuildTable helper', () => {
+    it('rebuilds a table with a new CHECK constraint, preserving rows', () => {
+      const db = new Database(':memory:')
+      db.run(`
+        CREATE TABLE widgets (
+          id TEXT PRIMARY KEY,
+          kind TEXT NOT NULL CHECK(kind IN ('a', 'b'))
+        )
+      `)
+      db.run("INSERT INTO widgets (id, kind) VALUES ('w1', 'a')")
+
+      rebuildTable(
+        db,
+        'widgets',
+        (tmp) => `
+          CREATE TABLE ${tmp} (
+            id TEXT PRIMARY KEY,
+            kind TEXT NOT NULL CHECK(kind IN ('a', 'b', 'c'))
+          )
+        `,
+        ['id', 'kind'],
+      )
+
+      // existing row preserved
+      const row = db
+        .query<{ id: string; kind: string }, []>(
+          'SELECT id, kind FROM widgets WHERE id = ?',
+        )
+        .get('w1') as { id: string; kind: string }
+      expect(row).toEqual({ id: 'w1', kind: 'a' })
+      // new value now allowed by the widened CHECK
+      expect(() =>
+        db.run("INSERT INTO widgets (id, kind) VALUES ('w2', 'c')"),
+      ).not.toThrow()
+      db.close()
+    })
+  })
+
+  it('preserves edges across a nodes CHECK-rebuild migration', () => {
+    const db = new Database(':memory:')
+    db.run(`
+      CREATE TABLE nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run(
+      "INSERT INTO nodes (id, type, title) VALUES ('proj_1', 'project', 'P')",
+    )
+    db.run(
+      "INSERT INTO nodes (id, type, title) VALUES ('feat_1', 'feature', 'F')",
+    )
+    db.run(
+      "INSERT INTO edges (source_id, target_id, relation) VALUES ('feat_1', 'proj_1', 'part_of')",
+    )
+
+    runMigrations(db)
+
+    const edgeCount = db
+      .query<{ c: number }, []>('SELECT COUNT(*) AS c FROM edges')
+      .get() as { c: number }
+    expect(edgeCount.c).toBe(1)
+    db.close()
+  })
+})

package/server/src/migrations.ts

@@ -0,0 +1,140 @@
+import type { Database } from 'bun:sqlite'
+
+/**
+ * Versioned schema migrations for the bundled local SQLite server.
+ *
+ * The schema version is tracked with SQLite's `PRAGMA user_version`. Each entry
+ * in `MIGRATIONS` is a step whose 1-based ordinal is the version it produces:
+ * step at index `i` upgrades the DB from `user_version = i` to `user_version = i + 1`.
+ * On startup we apply every step whose target version exceeds the current
+ * `user_version`, in order, each wrapped in its own transaction so a failure
+ * leaves the DB at a clean, consistent version. Re-running is a no-op.
+ */
+
+type Migration = (db: Database) => void
+
+/**
+ * Rebuild a table with a new schema, preserving its rows. SQLite cannot ALTER a
+ * CHECK constraint in place, so changing column constraints requires creating a
+ * new table, copying rows across the shared columns, dropping the old table, and
+ * renaming. The whole sequence runs inside a transaction.
+ */
+export function rebuildTable(
+  db: Database,
+  table: string,
+  createNewTableSql: (tmpName: string) => string,
+  columns: string[],
+): void {
+  const tmp = `${table}__migrate_tmp`
+  const cols = columns.join(', ')
+  db.run('PRAGMA foreign_keys = OFF')
+  db.transaction(() => {
+    db.run(createNewTableSql(tmp))
+    db.run(`INSERT INTO ${tmp} (${cols}) SELECT ${cols} FROM ${table}`)
+    db.run(`DROP TABLE ${table}`)
+    db.run(`ALTER TABLE ${tmp} RENAME TO ${table}`)
+  })()
+  db.run('PRAGMA foreign_keys = ON')
+}
+
+const MIGRATIONS: Migration[] = [
+  // 0 -> 1: base schema (nodes + edges + indexes). Uses IF NOT EXISTS so this
+  // step is harmless on a DB that predates user_version tracking but already
+  // has the tables (created by an old `CREATE TABLE IF NOT EXISTS` startup).
+  (db) => {
+    db.run(`
+      CREATE TABLE IF NOT EXISTS nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE IF NOT EXISTS edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)')
+    db.run('CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status)')
+    db.run(
+      'CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id, relation)',
+    )
+    db.run(
+      'CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id, relation)',
+    )
+  },
+
+  // 1 -> 2: (a) add a writable `metadata` TEXT column if it is missing, then
+  // (b) rebuild `nodes` to widen the status CHECK to include 'blocked' and
+  // 'cancelled'. Adding the column first lets the CHECK-rebuild copy a uniform
+  // set of columns regardless of the pre-existing shape.
+  (db) => {
+    const hasMetadata = db
+      .query<{ name: string }, []>('PRAGMA table_info(nodes)')
+      .all()
+      .some((c) => c.name === 'metadata')
+    if (!hasMetadata) {
+      db.run('ALTER TABLE nodes ADD COLUMN metadata TEXT')
+    }
+
+    rebuildTable(
+      db,
+      'nodes',
+      (tmp) => `
+        CREATE TABLE ${tmp} (
+          id TEXT PRIMARY KEY,
+          type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+          title TEXT NOT NULL,
+          description TEXT,
+          status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done', 'blocked', 'cancelled')),
+          metadata TEXT,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        )
+      `,
+      [
+        'id',
+        'type',
+        'title',
+        'description',
+        'status',
+        'metadata',
+        'created_at',
+        'updated_at',
+      ],
+    )
+
+    // Indexes are dropped with the old table; recreate them.
+    db.run('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)')
+    db.run('CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status)')
+  },
+]
+
+export const LATEST_VERSION = MIGRATIONS.length
+
+function getUserVersion(db: Database): number {
+  const row = db
+    .query<{ user_version: number }, []>('PRAGMA user_version')
+    .get()
+  return row?.user_version ?? 0
+}
+
+export function runMigrations(db: Database): void {
+  const current = getUserVersion(db)
+  MIGRATIONS.forEach((migration, index) => {
+    const targetVersion = index + 1
+    if (targetVersion <= current) return
+    migration(db)
+    // PRAGMA user_version does not accept bound parameters; the value is an
+    // integer derived from our own loop index, never user input.
+    db.run(`PRAGMA user_version = ${targetVersion}`)
+  })
+}

package/server/src/resolvers.test.ts

@@ -96,6 +96,59 @@ describe('createResolvers', () => {
       expect(typeof node.createdAt).toBe('string')
       expect(typeof node.updatedAt).toBe('string')
     })
+
+    it('persists metadata as JSON and reads it back unchanged', () => {
+      const created = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'With meta',
+        metadata: '{"priority":"high","effort":3}',
+      })
+      expect(created.metadata).toBe('{"priority":"high","effort":3}')
+      const found = find(resolvers, created.id)
+      expect(JSON.parse(found.metadata as string)).toEqual({
+        priority: 'high',
+        effort: 3,
+      })
+    })
+
+    it('accepts an explicit initial status', () => {
+      const node = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Started',
+        status: 'in_progress',
+      })
+      expect(node.status).toBe('in_progress')
+    })
+
+    it('rejects an invalid initial status with VALIDATION_ERROR', () => {
+      try {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: 'Bad',
+          status: 'bogus',
+        })
+        throw new Error('expected createNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.message).toContain('Invalid status: bogus')
+        expect(e.extensions?.code).toBe('VALIDATION_ERROR')
+      }
+    })
+
+    it('rejects non-JSON metadata with VALIDATION_ERROR', () => {
+      try {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: 'Bad meta',
+          metadata: 'not json',
+        })
+        throw new Error('expected createNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.message).toContain('metadata')
+        expect(e.extensions?.code).toBe('VALIDATION_ERROR')
+      }
+    })
   })
 
   describe('Query.node', () => {
@@ -161,6 +214,189 @@ describe('createResolvers', () => {
         }),
       ).toThrow('Node nonexistent not found')
     })
+
+    it('updates the title, leaving other fields untouched', () => {
+      const node = create(resolvers, {
+        type: 'task',
+        title: 'Old title',
+        description: 'keep me',
+      })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        title: 'New title',
+      })
+      expect(updated.title).toBe('New title')
+      expect(updated.description).toBe('keep me')
+      expect(updated.status).toBe('draft')
+    })
+
+    it('updates the description independently', () => {
+      const node = create(resolvers, {
+        type: 'task',
+        title: 'Title',
+        description: 'old desc',
+      })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        description: 'new desc',
+      })
+      expect(updated.description).toBe('new desc')
+      expect(updated.title).toBe('Title')
+    })
+
+    it('updates metadata independently and round-trips', () => {
+      const node = create(resolvers, { type: 'task', title: 'Title' })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        metadata: '{"source":"import","effort":5}',
+      })
+      expect(JSON.parse(updated.metadata as string)).toEqual({
+        source: 'import',
+        effort: 5,
+      })
+      const found = find(resolvers, node.id)
+      expect(JSON.parse(found.metadata as string)).toEqual({
+        source: 'import',
+        effort: 5,
+      })
+    })
+
+    it('updates several fields at once', () => {
+      const node = create(resolvers, { type: 'task', title: 'Title' })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        title: 'Renamed',
+        description: 'desc',
+        status: 'in_progress',
+        metadata: '{"k":"v"}',
+      })
+      expect(updated.title).toBe('Renamed')
+      expect(updated.description).toBe('desc')
+      expect(updated.status).toBe('in_progress')
+      expect(JSON.parse(updated.metadata as string)).toEqual({ k: 'v' })
+    })
+
+    it('rejects non-JSON metadata on update with VALIDATION_ERROR', () => {
+      const node = create(resolvers, { type: 'task', title: 'Title' })
+      try {
+        resolvers.Mutation.updateNode(null, {
+          id: node.id,
+          metadata: 'nope',
+        })
+        throw new Error('expected updateNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.message).toContain('metadata')
+        expect(e.extensions?.code).toBe('VALIDATION_ERROR')
+      }
+    })
+
+    it('not-found error carries the NOT_FOUND code', () => {
+      try {
+        resolvers.Mutation.updateNode(null, {
+          id: 'missing',
+          title: 'x',
+        })
+        throw new Error('expected updateNode to throw')
+      } catch (err) {
+        const e = err as { extensions?: { code?: string } }
+        expect(e.extensions?.code).toBe('NOT_FOUND')
+      }
+    })
+
+    it('rejects an empty title with VALIDATION_ERROR', () => {
+      const node = create(resolvers, { type: 'task', title: 'Title' })
+      try {
+        resolvers.Mutation.updateNode(null, { id: node.id, title: '   ' })
+        throw new Error('expected updateNode to throw')
+      } catch (err) {
+        const e = err as { extensions?: { code?: string } }
+        expect(e.extensions?.code).toBe('VALIDATION_ERROR')
+      }
+    })
+  })
+
+  describe('Mutation.deleteNode', () => {
+    it('deletes a leaf node and returns true', () => {
+      const node = create(resolvers, { type: 'task', title: 'Leaf' })
+      const result = resolvers.Mutation.deleteNode(null, { id: node.id })
+      expect(result).toBe(true)
+      expect(resolvers.Query.node(null, { id: node.id })).toBeNull()
+    })
+
+    it('removes incident blocks edges when deleting a leaf', () => {
+      const blocker = create(resolvers, { type: 'task', title: 'Blocker' })
+      const blocked = create(resolvers, { type: 'task', title: 'Blocked' })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: blocker.id,
+        targetId: blocked.id,
+        relation: 'blocks',
+      })
+
+      resolvers.Mutation.deleteNode(null, { id: blocked.id })
+
+      // the blocks edge that referenced the deleted node must be gone
+      const edges = db.raw
+        .query<{ c: number }, [string, string]>(
+          'SELECT COUNT(*) AS c FROM edges WHERE source_id = ? OR target_id = ?',
+        )
+        .get(blocked.id, blocked.id) as { c: number }
+      expect(edges.c).toBe(0)
+    })
+
+    it('deletes a node together with its part_of edge to its parent', () => {
+      const project = create(resolvers, { type: 'project', title: 'P' })
+      const feature = create(resolvers, { type: 'feature', title: 'F' })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: feature.id,
+        targetId: project.id,
+        relation: 'part_of',
+      })
+
+      const result = resolvers.Mutation.deleteNode(null, { id: feature.id })
+      expect(result).toBe(true)
+      // parent survives
+      expect(resolvers.Query.node(null, { id: project.id })).not.toBeNull()
+      // the part_of edge is gone
+      const edges = db.raw
+        .query<{ c: number }, [string]>(
+          'SELECT COUNT(*) AS c FROM edges WHERE source_id = ?',
+        )
+        .get(feature.id) as { c: number }
+      expect(edges.c).toBe(0)
+    })
+
+    it('refuses to delete a node that has children (CONFLICT)', () => {
+      const project = create(resolvers, { type: 'project', title: 'P' })
+      const feature = create(resolvers, { type: 'feature', title: 'F' })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: feature.id,
+        targetId: project.id,
+        relation: 'part_of',
+      })
+
+      try {
+        resolvers.Mutation.deleteNode(null, { id: project.id })
+        throw new Error('expected deleteNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.extensions?.code).toBe('CONFLICT')
+        expect(e.message).toContain('child')
+      }
+      // node not deleted
+      expect(resolvers.Query.node(null, { id: project.id })).not.toBeNull()
+    })
+
+    it('throws NOT_FOUND for a missing node', () => {
+      try {
+        resolvers.Mutation.deleteNode(null, { id: 'missing' })
+        throw new Error('expected deleteNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.extensions?.code).toBe('NOT_FOUND')
+        expect(e.message).toContain('missing')
+      }
+    })
   })
 
   describe('Mutation.approveNode', () => {

package/server/src/resolvers.ts

@@ -59,6 +59,30 @@ const VALID_STATUSES = new Set([
   'cancelled',
 ])
 
+function assertValidStatus(status: string): void {
+  if (!VALID_STATUSES.has(status)) {
+    throw validationError(
+      `Invalid status: ${status}. Must be one of: ${[...VALID_STATUSES].join(', ')}`,
+    )
+  }
+}
+
+/**
+ * Validate that `metadata` is a JSON string and return its canonical form.
+ * Metadata is stored as a JSON string (the column and the GraphQL field are
+ * both String); callers pass a JSON-encoded string. Non-JSON input is rejected
+ * with a VALIDATION_ERROR so agents can self-correct.
+ */
+function normalizeMetadata(metadata: string): string {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(metadata)
+  } catch {
+    throw validationError('Invalid metadata: must be a valid JSON string')
+  }
+  return JSON.stringify(parsed)
+}
+
 function generateId(type: string): string {
   const prefix = PREFIX_MAP[type] ?? type
   return `${prefix}_${nanoid(12)}`
@@ -206,49 +230,120 @@ export function createResolvers(db: Db) {
     Mutation: {
       createNode: (
         _: unknown,
-        args: { type: string; title: string; description?: string },
+        args: {
+          type: string
+          title: string
+          description?: string
+          status?: string
+          metadata?: string
+        },
       ): NodeGql => {
         if (!args.title.trim()) throw validationError('Title is required')
         if (args.description != null && !args.description.trim()) {
           throw validationError('Description cannot be empty')
         }
+        if (args.status != null) assertValidStatus(args.status)
+        const metadata =
+          args.metadata != null ? normalizeMetadata(args.metadata) : null
         const id = generateId(args.type)
         const now = new Date().toISOString()
         const description = args.description ?? null
+        const status = args.status ?? 'draft'
         db.raw.run(
           'INSERT INTO nodes (id, type, title, description, status, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
-          [id, args.type, args.title, description, 'draft', null, now, now],
+          [id, args.type, args.title, description, status, metadata, now, now],
         )
         return {
           id,
           type: args.type,
           title: args.title,
           description,
-          status: 'draft',
-          metadata: null,
+          status,
+          metadata,
           createdAt: now,
           updatedAt: now,
         }
       },
 
-      updateNode: (_: unknown, args: { id: string; status?: string }) => {
+      updateNode: (
+        _: unknown,
+        args: {
+          id: string
+          title?: string
+          description?: string
+          status?: string
+          metadata?: string
+        },
+      ) => {
         const existing = db.raw
           .query('SELECT * FROM nodes WHERE id = ?')
           .get(args.id) as NodeRow | null
         if (!existing) throw notFoundError(`Node ${args.id} not found`)
-        const newStatus = args.status ?? existing.status
-        if (args.status && !VALID_STATUSES.has(args.status)) {
-          throw validationError(
-            `Invalid status: ${args.status}. Must be one of: ${[...VALID_STATUSES].join(', ')}`,
-          )
+
+        if (args.title != null && !args.title.trim()) {
+          throw validationError('Title cannot be empty')
+        }
+        if (args.description != null && !args.description.trim()) {
+          throw validationError('Description cannot be empty')
+        }
+        if (args.status != null) assertValidStatus(args.status)
+
+        const next: NodeRow = {
+          ...existing,
+          title: args.title ?? existing.title,
+          description:
+            args.description !== undefined
+              ? args.description
+              : existing.description,
+          status: args.status ?? existing.status,
+          metadata:
+            args.metadata != null
+              ? normalizeMetadata(args.metadata)
+              : existing.metadata,
         }
         const now = new Date().toISOString()
-        db.raw.run('UPDATE nodes SET status = ?, updated_at = ? WHERE id = ?', [
-          newStatus,
-          now,
-          args.id,
-        ])
-        return rowToNode({ ...existing, status: newStatus, updated_at: now })
+        db.raw.run(
+          'UPDATE nodes SET title = ?, description = ?, status = ?, metadata = ?, updated_at = ? WHERE id = ?',
+          [
+            next.title,
+            next.description,
+            next.status,
+            next.metadata,
+            now,
+            args.id,
+          ],
+        )
+        return rowToNode({ ...next, updated_at: now })
+      },
+
+      deleteNode: (_: unknown, args: { id: string }): boolean => {
+        const existing = db.raw
+          .query('SELECT id FROM nodes WHERE id = ?')
+          .get(args.id) as { id: string } | null
+        if (!existing) throw notFoundError(`Node ${args.id} not found`)
+
+        // The hierarchy is client -> project -> feature -> task via `part_of`
+        // edges (source = child, target = parent). A node with children must
+        // not be orphaned; reject rather than cascade-delete the subtree.
+        const childCount = db.raw
+          .query(
+            'SELECT COUNT(*) AS c FROM edges WHERE target_id = ? AND relation = ?',
+          )
+          .get(args.id, 'part_of') as { c: number }
+        if (childCount.c > 0) {
+          throw conflictError(
+            `Cannot delete node ${args.id}: it has ${childCount.c} child node(s). Delete or re-link them first.`,
+          )
+        }
+
+        db.raw.transaction(() => {
+          db.raw.run('DELETE FROM edges WHERE source_id = ? OR target_id = ?', [
+            args.id,
+            args.id,
+          ])
+          db.raw.run('DELETE FROM nodes WHERE id = ?', [args.id])
+        })()
+        return true
       },
 
       approveNode: (_: unknown, args: { id: string }) => {

package/server/src/schema.test.ts

@@ -70,7 +70,7 @@ describe('schema', () => {
     expect(fields.tree).toBeUndefined()
   })
 
-  it('Mutation type has createNode, updateNode, approveNode, createEdge, removeEdge', () => {
+  it('Mutation type has createNode, updateNode, approveNode, deleteNode, createEdge, removeEdge', () => {
     const mutationType = schema.getType(
       'Mutation',
     ) as import('graphql').GraphQLObjectType
@@ -78,16 +78,50 @@ describe('schema', () => {
     expect(fields.createNode).toBeDefined()
     expect(fields.updateNode).toBeDefined()
     expect(fields.approveNode).toBeDefined()
+    expect(fields.deleteNode).toBeDefined()
     expect(fields.createEdge).toBeDefined()
     expect(fields.removeEdge).toBeDefined()
   })
 
-  it('Mutation type does not have deleteNode or deleteEdge', () => {
+  it('createNode accepts type, title, description, status, metadata args', () => {
     const mutationType = schema.getType(
       'Mutation',
     ) as import('graphql').GraphQLObjectType
-    const fields = mutationType.getFields()
-    expect(fields.deleteNode).toBeUndefined()
-    expect(fields.deleteEdge).toBeUndefined()
+    const args = mutationType.getFields().createNode.args.map((a) => a.name)
+    expect(args).toEqual(
+      expect.arrayContaining([
+        'type',
+        'title',
+        'description',
+        'status',
+        'metadata',
+      ]),
+    )
+  })
+
+  it('updateNode accepts id, title, description, status, metadata args', () => {
+    const mutationType = schema.getType(
+      'Mutation',
+    ) as import('graphql').GraphQLObjectType
+    const args = mutationType.getFields().updateNode.args.map((a) => a.name)
+    expect(args).toEqual(
+      expect.arrayContaining([
+        'id',
+        'title',
+        'description',
+        'status',
+        'metadata',
+      ]),
+    )
+  })
+
+  it('deleteNode returns Boolean and takes an id arg', () => {
+    const mutationType = schema.getType(
+      'Mutation',
+    ) as import('graphql').GraphQLObjectType
+    const deleteNode = mutationType.getFields().deleteNode
+    const args = deleteNode.args.map((a) => a.name)
+    expect(args).toEqual(expect.arrayContaining(['id']))
+    expect(String(deleteNode.type)).toContain('Boolean')
   })
 })

package/server/src/schema.ts

@@ -28,9 +28,22 @@ export const typeDefs = /* GraphQL */ `
   }
 
   type Mutation {
-    createNode(type: String!, title: String!, description: String): Node!
-    updateNode(id: String!, status: String): Node!
+    createNode(
+      type: String!
+      title: String!
+      description: String
+      status: String
+      metadata: String
+    ): Node!
+    updateNode(
+      id: String!
+      title: String
+      description: String
+      status: String
+      metadata: String
+    ): Node!
     approveNode(id: String!): Node!
+    deleteNode(id: String!): Boolean!
     createEdge(sourceId: String!, targetId: String!, relation: String!): Edge!
     removeEdge(sourceId: String!, targetId: String!, relation: String!): Boolean!
   }