@sqaoss/flowy 1.8.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
@@ -50,6 +50,7 @@
     "check": "biome check --write .",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:e2e": "vitest run --config vitest.config.e2e.ts",
     "sdl": "bun scripts/print-sdl.ts",
     "typecheck": "tsc --noEmit",
     "prepare": "husky"

package/server/src/contract.test.ts

@@ -31,9 +31,11 @@
  *   - `rotateApiKey`    (key.ts)    — API key lifecycle; local has no keys.
  *   - `createCheckout`  (billing.ts)— Polar checkout; local has no billing.
  *
- * Conversely, the SaaS schema carries operations the local server lacks and the
- * CLI does not yet call against local: `auditLog`/`getAuditLog` (P1-2 will port
- * this to local), `ancestors`, and `nodes(status/limit/offset)` pagination.
+ * Conversely, the SaaS schema carries some operations the local server still
+ * lacks and the CLI does not yet call against local: `ancestors` and
+ * `nodes(status/limit/offset)` pagination. (`auditLog` was such a divergence
+ * until P1-2/F27 ported it to the bundled local server; it is now part of
+ * LOCAL_CONTRACT_OPERATIONS and exercised below.)
  * Status vocabulary and edge relations are shared (`part_of`, `blocks`); the
  * SaaS schema additionally recognises `epic`/`depends_on`/`informs` relations
  * the bundled server does not. The test below asserts the local server rejects
@@ -281,11 +283,44 @@ describe('CLI/local-server contract (P1-1)', () => {
     })
     expect(exportDescendants.descendants.length).toBeGreaterThan(0)
 
-    const subtree = await ok<{ subtree: Array<{ id: string }> }>(
-      LOCAL_CONTRACT_OPERATIONS.SUBTREE,
-      { nodeId: project.id, maxDepth: 10 },
-    )
-    expect(subtree.subtree.length).toBeGreaterThan(0)
+    // SUBTREE follows one relation (default part_of) and annotates each node
+    // with parentId/depth/relation. From the project, the part_of view is:
+    //   project -> feature (depth 1) -> {task, blocker, imported} (depth 2),
+    // all reached via part_of edges. The blocker -> task `blocks` edge must NOT
+    // change anyone's parent/relation: every returned node carries
+    // relation 'part_of' and its part_of parent, never the blocks linkage.
+    const subtree = await ok<{
+      subtree: Array<{
+        id: string
+        parentId: string
+        depth: number
+        relation: string
+      }>
+    }>(LOCAL_CONTRACT_OPERATIONS.SUBTREE, {
+      nodeId: project.id,
+      relation: 'part_of',
+      maxDepth: 10,
+    })
+    const subtreeById = new Map(subtree.subtree.map((n) => [n.id, n]))
+    expect(subtreeById.get(feature.id)).toMatchObject({
+      parentId: project.id,
+      depth: 1,
+      relation: 'part_of',
+    })
+    expect(subtreeById.get(task.id)).toMatchObject({
+      parentId: feature.id,
+      depth: 2,
+      relation: 'part_of',
+    })
+    // the blocker is reached via its part_of edge to the feature (depth 2),
+    // NOT via the blocks edge that points at the task — proving blocks edges
+    // do not leak into the hierarchy view.
+    expect(subtreeById.get(blocker.id)).toMatchObject({
+      parentId: feature.id,
+      depth: 2,
+      relation: 'part_of',
+    })
+    expect(subtree.subtree.every((n) => n.relation === 'part_of')).toBe(true)
 
     // task is blocked by an unfinished blocker, so readyTasks excludes it.
     const ready = await ok<{ readyTasks: Array<{ id: string }> }>(
@@ -331,6 +366,38 @@ describe('CLI/local-server contract (P1-1)', () => {
     )
     expect(search.search.some((n) => n.id === project.id)).toBe(true)
 
+    // auditLog (P1-2/F27): the task has accumulated a trail — a `create` on
+    // insert, a `status_change` to pending_review, an `approve`, plus the
+    // content `update`s. Entries come back newest-first and carry the
+    // SaaS-shaped fields.
+    const history = await ok<{
+      auditLog: Array<{
+        id: string
+        action: string
+        field: string | null
+        oldValue: string | null
+        newValue: string | null
+        snapshot: string | null
+        changedBy: string
+        createdAt: string
+      }>
+    }>(LOCAL_CONTRACT_OPERATIONS.AUDIT_LOG, { nodeId: task.id, limit: 50 })
+    const actions = history.auditLog.map((e) => e.action)
+    expect(actions).toContain('create')
+    expect(actions).toContain('status_change')
+    expect(actions).toContain('approve')
+    // changedBy default actor + ISO timestamps
+    expect(history.auditLog.every((e) => e.changedBy === 'local')).toBe(true)
+    expect(history.auditLog.every((e) => typeof e.createdAt === 'string')).toBe(
+      true,
+    )
+    // the status_change entry carries the field-level diff
+    const statusEntry = history.auditLog.find(
+      (e) => e.action === 'status_change',
+    )
+    expect(statusEntry?.field).toBe('status')
+    expect(statusEntry?.newValue).toBe('pending_review')
+
     // --- Edge removal + node deletion --------------------------------------
     const { removeEdge } = await ok<{ removeEdge: boolean }>(
       LOCAL_CONTRACT_OPERATIONS.UNBLOCK_TASK,
@@ -381,6 +448,7 @@ describe('CLI/local-server contract (P1-1)', () => {
       'EXPORT_PROJECT',
       'EXPORT_DESCENDANTS',
       'EXPORT_EDGES',
+      'AUDIT_LOG',
     ])
     expect(new Set(Object.keys(LOCAL_CONTRACT_OPERATIONS))).toEqual(exercised)
   })

package/server/src/migrations.test.ts

@@ -42,6 +42,67 @@ describe('runMigrations', () => {
     db.close()
   })
 
+  it('creates the audit_log table with SaaS-mirrored columns on a fresh DB', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    expect(tableNames(db)).toContain('audit_log')
+    const cols = columnNames(db, 'audit_log')
+    for (const c of [
+      'id',
+      'node_id',
+      'action',
+      'field',
+      'old_value',
+      'new_value',
+      'snapshot',
+      'changed_by',
+      'created_at',
+    ]) {
+      expect(cols).toContain(c)
+    }
+    db.close()
+  })
+
+  it('adds audit_log when upgrading an existing pre-audit DB', () => {
+    const db = new Database(':memory:')
+    // Simulate a DB already at the pre-audit version (nodes + edges + metadata,
+    // user_version = 2) that has never seen the audit migration.
+    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', 'blocked', 'cancelled')),
+        metadata TEXT,
+        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')")
+    db.run('PRAGMA user_version = 2')
+
+    expect(tableNames(db)).not.toContain('audit_log')
+    runMigrations(db)
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    expect(tableNames(db)).toContain('audit_log')
+    // existing data preserved across the upgrade
+    const row = db
+      .query<{ id: string }, []>('SELECT id FROM nodes WHERE id = ?')
+      .get('task_1') as { id: string }
+    expect(row.id).toBe('task_1')
+    db.close()
+  })
+
   it('is a no-op when run twice (idempotent)', () => {
     const db = new Database(':memory:')
     runMigrations(db)

package/server/src/migrations.ts

@@ -116,6 +116,33 @@ const MIGRATIONS: Migration[] = [
     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)')
   },
+
+  // 2 -> 3: add the `audit_log` table (F27). Mirrors the SaaS audit_log schema
+  // (id, node_id, action, field, old_value, new_value, snapshot, changed_by,
+  // created_at) so `flowy history` output is consistent across backends. The
+  // local server is single-tenant and has no users table, so `changed_by`
+  // carries a constant actor ('local') rather than a FK to a user. `node_id`
+  // is nullable and ON DELETE SET NULL so delete-audit rows survive the node.
+  // Uses IF NOT EXISTS so the step is idempotent on a DB that somehow already
+  // has the table.
+  (db) => {
+    db.run(`
+      CREATE TABLE IF NOT EXISTS audit_log (
+        id TEXT PRIMARY KEY,
+        node_id TEXT REFERENCES nodes(id) ON DELETE SET NULL,
+        action TEXT NOT NULL,
+        field TEXT,
+        old_value TEXT,
+        new_value TEXT,
+        snapshot TEXT,
+        changed_by TEXT NOT NULL DEFAULT 'local',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(
+      'CREATE INDEX IF NOT EXISTS idx_audit_log_node ON audit_log(node_id)',
+    )
+  },
 ]
 
 export const LATEST_VERSION = MIGRATIONS.length

package/server/src/resolvers.test.ts

@@ -580,7 +580,7 @@ describe('createResolvers', () => {
   })
 
   describe('Query.subtree', () => {
-    it('returns full tree traversal across all edge types', () => {
+    it('returns the part_of hierarchy by default', () => {
       const project = resolvers.Mutation.createNode(null, {
         type: 'project',
         title: 'Root',
@@ -608,6 +608,125 @@ describe('createResolvers', () => {
       expect(tree).toHaveLength(2)
     })
 
+    it('returns parentId, depth and relation for each node (default part_of)', () => {
+      const project = resolvers.Mutation.createNode(null, {
+        type: 'project',
+        title: 'Root',
+      })
+      const feature = resolvers.Mutation.createNode(null, {
+        type: 'feature',
+        title: 'F1',
+      })
+      const task = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'T1',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: feature.id,
+        targetId: project.id,
+        relation: 'part_of',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: task.id,
+        targetId: feature.id,
+        relation: 'part_of',
+      })
+
+      const tree = resolvers.Query.subtree(null, { nodeId: project.id })
+      const byId = new Map(tree.map((n) => [n.id, n]))
+
+      const featNode = byId.get(feature.id)
+      expect(featNode).toBeDefined()
+      expect(featNode?.depth).toBe(1)
+      expect(featNode?.parentId).toBe(project.id)
+      expect(featNode?.relation).toBe('part_of')
+
+      const taskNode = byId.get(task.id)
+      expect(taskNode).toBeDefined()
+      expect(taskNode?.depth).toBe(2)
+      expect(taskNode?.parentId).toBe(feature.id)
+      expect(taskNode?.relation).toBe('part_of')
+    })
+
+    it('excludes blocks edges from the default part_of view', () => {
+      const project = resolvers.Mutation.createNode(null, {
+        type: 'project',
+        title: 'Root',
+      })
+      const feature = resolvers.Mutation.createNode(null, {
+        type: 'feature',
+        title: 'F1',
+      })
+      const task = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'T1',
+      })
+      const blocker = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Blocker',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: feature.id,
+        targetId: project.id,
+        relation: 'part_of',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: task.id,
+        targetId: feature.id,
+        relation: 'part_of',
+      })
+      // blocker blocks task: source=blocker, target=task. A blocks edge must NOT
+      // pull the blocker into the project's part_of hierarchy view.
+      resolvers.Mutation.createEdge(null, {
+        sourceId: blocker.id,
+        targetId: task.id,
+        relation: 'blocks',
+      })
+
+      const tree = resolvers.Query.subtree(null, { nodeId: project.id })
+      const ids = tree.map((n) => n.id)
+      expect(ids).toContain(feature.id)
+      expect(ids).toContain(task.id)
+      expect(ids).not.toContain(blocker.id)
+      expect(tree.every((n) => n.relation === 'part_of')).toBe(true)
+    })
+
+    it('follows only the requested relation when overridden', () => {
+      const task = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Target',
+      })
+      const blocker = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Blocker',
+      })
+      const child = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Part of target',
+      })
+      // blocker blocks task (source=blocker, target=task)
+      resolvers.Mutation.createEdge(null, {
+        sourceId: blocker.id,
+        targetId: task.id,
+        relation: 'blocks',
+      })
+      // child is part_of task (source=child, target=task)
+      resolvers.Mutation.createEdge(null, {
+        sourceId: child.id,
+        targetId: task.id,
+        relation: 'part_of',
+      })
+
+      const blocks = resolvers.Query.subtree(null, {
+        nodeId: task.id,
+        relation: 'blocks',
+      })
+      expect(blocks.map((n) => n.id)).toEqual([blocker.id])
+      expect(blocks[0].relation).toBe('blocks')
+      expect(blocks[0].depth).toBe(1)
+      expect(blocks[0].parentId).toBe(task.id)
+    })
+
     it('respects maxDepth', () => {
       const project = resolvers.Mutation.createNode(null, {
         type: 'project',
@@ -638,6 +757,7 @@ describe('createResolvers', () => {
       })
       expect(shallow).toHaveLength(1)
       expect(shallow[0].id).toBe(feature.id)
+      expect(shallow[0].depth).toBe(1)
     })
   })
 
@@ -1295,4 +1415,144 @@ describe('createResolvers', () => {
       ).toEqual([])
     })
   })
+
+  describe('audit_log — recording + Query.auditLog', () => {
+    it('records a create audit entry on createNode', () => {
+      const node = create(resolvers, { type: 'task', title: 'Audited' })
+      const log = resolvers.Query.auditLog(null, { nodeId: node.id })
+      expect(log).toHaveLength(1)
+      expect(log[0]).toMatchObject({ nodeId: node.id, action: 'create' })
+      // snapshot is a JSON string mirroring the created node
+      expect(log[0]?.snapshot).toBeTypeOf('string')
+      expect(JSON.parse(log[0]?.snapshot as string)).toMatchObject({
+        id: node.id,
+        title: 'Audited',
+      })
+    })
+
+    it('shapes entries like the SaaS auditLog field', () => {
+      const node = create(resolvers, { type: 'task', title: 'Shape' })
+      const [entry] = resolvers.Query.auditLog(null, { nodeId: node.id })
+      expect(entry).toHaveProperty('id')
+      expect(entry).toHaveProperty('nodeId')
+      expect(entry).toHaveProperty('action')
+      expect(entry).toHaveProperty('field')
+      expect(entry).toHaveProperty('oldValue')
+      expect(entry).toHaveProperty('newValue')
+      expect(entry).toHaveProperty('snapshot')
+      expect(entry).toHaveProperty('changedBy')
+      expect(entry).toHaveProperty('createdAt')
+      expect(entry?.changedBy).toBe('local')
+      expect(entry?.createdAt).toBeTypeOf('string')
+    })
+
+    it('records field-level diffs on updateNode (status_change vs update)', () => {
+      const node = create(resolvers, { type: 'task', title: 'Orig' })
+      resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        title: 'Renamed',
+        status: 'in_progress',
+      })
+      const log = resolvers.Query.auditLog(null, { nodeId: node.id })
+      const actions = log.map((e) => e.action)
+      // create + a title update + a status_change
+      expect(actions).toContain('create')
+      expect(actions).toContain('update')
+      expect(actions).toContain('status_change')
+
+      const titleEntry = log.find((e) => e.field === 'title')
+      expect(titleEntry).toMatchObject({
+        action: 'update',
+        oldValue: 'Orig',
+        newValue: 'Renamed',
+      })
+      const statusEntry = log.find((e) => e.field === 'status')
+      expect(statusEntry).toMatchObject({
+        action: 'status_change',
+        oldValue: 'draft',
+        newValue: 'in_progress',
+      })
+    })
+
+    it('records an approve entry on approveNode', () => {
+      const node = create(resolvers, { type: 'task', title: 'Appr' })
+      resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      resolvers.Mutation.approveNode(null, { id: node.id })
+      const log = resolvers.Query.auditLog(null, { nodeId: node.id })
+      const approve = log.find((e) => e.action === 'approve')
+      expect(approve).toMatchObject({
+        field: 'status',
+        oldValue: 'pending_review',
+        newValue: 'approved',
+      })
+    })
+
+    it('records create_edge / remove_edge against the source node', () => {
+      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',
+      })
+      let log = resolvers.Query.auditLog(null, { nodeId: blocker.id })
+      const created = log.find((e) => e.action === 'create_edge')
+      expect(created).toMatchObject({
+        field: 'blocks',
+        newValue: blocked.id,
+      })
+
+      resolvers.Mutation.removeEdge(null, {
+        sourceId: blocker.id,
+        targetId: blocked.id,
+        relation: 'blocks',
+      })
+      log = resolvers.Query.auditLog(null, { nodeId: blocker.id })
+      const removed = log.find((e) => e.action === 'remove_edge')
+      expect(removed).toMatchObject({
+        field: 'blocks',
+        oldValue: blocked.id,
+      })
+    })
+
+    it('returns entries newest-first and respects limit', () => {
+      const node = create(resolvers, { type: 'task', title: 'Limit' })
+      resolvers.Mutation.updateNode(null, { id: node.id, title: 'A' })
+      resolvers.Mutation.updateNode(null, { id: node.id, title: 'B' })
+      const all = resolvers.Query.auditLog(null, { nodeId: node.id })
+      // create, then two title updates => 3 entries, newest first
+      expect(all.length).toBeGreaterThanOrEqual(3)
+      expect(all[0]?.action).not.toBe('create')
+      const limited = resolvers.Query.auditLog(null, {
+        nodeId: node.id,
+        limit: 1,
+      })
+      expect(limited).toHaveLength(1)
+    })
+
+    it('records a delete entry (node_id nulled, snapshot retained)', () => {
+      const node = create(resolvers, { type: 'task', title: 'Doomed' })
+      resolvers.Mutation.deleteNode(null, { id: node.id })
+      // node_id is set to null on delete (matching SaaS), so the row is no
+      // longer returned by auditLog(nodeId), but a delete row exists with the
+      // pre-delete snapshot.
+      const direct = db.raw
+        .query("SELECT action, snapshot FROM audit_log WHERE action = 'delete'")
+        .all() as Array<{ action: string; snapshot: string | null }>
+      expect(direct).toHaveLength(1)
+      expect(JSON.parse(direct[0]?.snapshot as string)).toMatchObject({
+        id: node.id,
+        title: 'Doomed',
+      })
+    })
+
+    it('returns [] for a node with no history', () => {
+      expect(
+        resolvers.Query.auditLog(null, { nodeId: 'task_nonexistent' }),
+      ).toEqual([])
+    })
+  })
 })

package/server/src/resolvers.ts

@@ -40,6 +40,53 @@ export interface NodeGql {
   updatedAt: string
 }
 
+/**
+ * An audit-log entry, shaped to match the SaaS `auditLog` GraphQL field
+ * (id, nodeId, action, field, oldValue, newValue, snapshot, changedBy,
+ * createdAt) so `flowy history` output is consistent across backends.
+ * `snapshot` is a JSON string (or null), mirroring SaaS.
+ */
+export interface AuditEntryGql {
+  id: string
+  nodeId: string | null
+  action: string
+  field: string | null
+  oldValue: string | null
+  newValue: string | null
+  snapshot: string | null
+  changedBy: string
+  createdAt: string
+}
+
+interface AuditRow {
+  id: string
+  node_id: string | null
+  action: string
+  field: string | null
+  old_value: string | null
+  new_value: string | null
+  snapshot: string | null
+  changed_by: string
+  created_at: string
+}
+
+/**
+ * A node returned from a subtree traversal, annotated with the edge that pulled
+ * it in: `parentId` (the node it descends from), `depth` (1 for the root's
+ * direct children), and `relation` (the relation of the linking edge).
+ */
+export interface SubtreeNodeGql extends NodeGql {
+  parentId: string
+  depth: number
+  relation: string
+}
+
+interface SubtreeRow extends NodeRow {
+  parent_id: string
+  depth: number
+  edge_relation: string
+}
+
 const NODE_COLS =
   'id, type, title, description, status, metadata, created_at, updated_at'
 
@@ -88,6 +135,57 @@ function generateId(type: string): string {
   return `${prefix}_${nanoid(12)}`
 }
 
+// The bundled local server is single-tenant and unauthenticated, so every
+// audit entry is attributed to a single constant actor. SaaS uses the user id.
+const LOCAL_ACTOR = 'local'
+
+interface AuditInput {
+  nodeId: string | null
+  action: string
+  field?: string | null
+  oldValue?: string | null
+  newValue?: string | null
+  snapshot?: Record<string, unknown> | null
+}
+
+/**
+ * Write one audit_log row. Call inside the same transaction as the mutation so
+ * the change and its audit trail commit (or roll back) together. SQLite's
+ * `datetime('now')` resolves to whole seconds, which is too coarse to order
+ * multiple entries written in the same call; we pass an explicit ISO timestamp
+ * with sub-second precision so `ORDER BY created_at DESC` is stable.
+ */
+function insertAudit(db: Db, input: AuditInput): void {
+  db.raw.run(
+    'INSERT INTO audit_log (id, node_id, action, field, old_value, new_value, snapshot, changed_by, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [
+      `audit_${nanoid(12)}`,
+      input.nodeId,
+      input.action,
+      input.field ?? null,
+      input.oldValue ?? null,
+      input.newValue ?? null,
+      input.snapshot != null ? JSON.stringify(input.snapshot) : null,
+      LOCAL_ACTOR,
+      new Date().toISOString(),
+    ],
+  )
+}
+
+function rowToAudit(row: AuditRow): AuditEntryGql {
+  return {
+    id: row.id,
+    nodeId: row.node_id,
+    action: row.action,
+    field: row.field,
+    oldValue: row.old_value,
+    newValue: row.new_value,
+    snapshot: row.snapshot,
+    changedBy: row.changed_by,
+    createdAt: row.created_at,
+  }
+}
+
 function rowToNode(row: NodeRow): NodeGql {
   return {
     id: row.id,
@@ -177,21 +275,39 @@ export function createResolvers(db: Db) {
         return selectNodes(rows)
       },
 
-      subtree: (_: unknown, args: { nodeId: string; maxDepth?: number }) => {
+      // Walk the part_of hierarchy (or another `relation`, default 'part_of')
+      // downward from `nodeId`, returning each reachable node annotated with the
+      // edge that pulled it in: parentId, depth (root's direct children = 1) and
+      // relation. Following a single relation keeps the hierarchy view clean —
+      // `blocks` dependency edges no longer leak into the part_of tree.
+      subtree: (
+        _: unknown,
+        args: { nodeId: string; relation?: string; maxDepth?: number },
+      ): SubtreeNodeGql[] => {
+        const relation = args.relation ?? 'part_of'
         const maxDepth = args.maxDepth ?? 100
         if (maxDepth === 0) return []
         const rows = db.raw
           .query(
-            `WITH RECURSIVE tree(id, depth) AS (
-              SELECT source_id, 1 FROM edges WHERE target_id = ?1
+            `WITH RECURSIVE tree(id, parent_id, depth) AS (
+              SELECT source_id, target_id, 1 FROM edges
+                WHERE target_id = ?1 AND relation = ?3
               UNION ALL
-              SELECT e.source_id, t.depth + 1 FROM edges e
-              JOIN tree t ON e.target_id = t.id WHERE t.depth < ?2
+              SELECT e.source_id, e.target_id, t.depth + 1 FROM edges e
+                JOIN tree t ON e.target_id = t.id
+                WHERE t.depth < ?2 AND e.relation = ?3
             )
-            SELECT DISTINCT ${prefixedCols()} FROM nodes n JOIN tree t ON n.id = t.id`,
+            SELECT ${prefixedCols()}, t.parent_id AS parent_id, t.depth AS depth, ?3 AS edge_relation
+            FROM nodes n JOIN tree t ON n.id = t.id
+            ORDER BY t.depth`,
           )
-          .all(args.nodeId, maxDepth) as NodeRow[]
-        return selectNodes(rows)
+          .all(args.nodeId, maxDepth, relation) as SubtreeRow[]
+        return rows.map((row) => ({
+          ...rowToNode(row),
+          parentId: row.parent_id,
+          depth: row.depth,
+          relation: row.edge_relation,
+        }))
       },
 
       // Nodes connected to `nodeId` by `relation`, following edges in the given
@@ -295,6 +411,24 @@ export function createResolvers(db: Db) {
           .all(...params, limit) as NodeRow[]
         return selectNodes(rows)
       },
+
+      // Audit history for a node, newest first. Shaped to match the SaaS
+      // `auditLog` field so `flowy history` output is consistent across
+      // backends. `delete` entries set node_id to null (the node is gone), so
+      // they are not returned here — the deletion is still recorded in the
+      // table with the pre-delete snapshot.
+      auditLog: (
+        _: unknown,
+        args: { nodeId: string; limit?: number },
+      ): AuditEntryGql[] => {
+        const limit = args.limit ?? 50
+        const rows = db.raw
+          .query(
+            'SELECT * FROM audit_log WHERE node_id = ? ORDER BY created_at DESC, rowid DESC LIMIT ?',
+          )
+          .all(args.nodeId, limit) as AuditRow[]
+        return rows.map(rowToAudit)
+      },
     },
 
     Mutation: {
@@ -319,11 +453,7 @@ export function createResolvers(db: Db) {
         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, status, metadata, now, now],
-        )
-        return {
+        const node: NodeGql = {
           id,
           type: args.type,
           title: args.title,
@@ -333,6 +463,27 @@ export function createResolvers(db: Db) {
           createdAt: now,
           updatedAt: now,
         }
+        db.raw.transaction(() => {
+          db.raw.run(
+            'INSERT INTO nodes (id, type, title, description, status, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+            [
+              id,
+              args.type,
+              args.title,
+              description,
+              status,
+              metadata,
+              now,
+              now,
+            ],
+          )
+          insertAudit(db, {
+            nodeId: id,
+            action: 'create',
+            snapshot: node as unknown as Record<string, unknown>,
+          })
+        })()
+        return node
       },
 
       updateNode: (
@@ -371,25 +522,77 @@ export function createResolvers(db: Db) {
               ? normalizeMetadata(args.metadata)
               : existing.metadata,
         }
+        // Field-level diffs, mirroring SaaS: title/description/metadata changes
+        // are 'update' entries; a status change is a 'status_change' entry.
+        const diffs: Array<{
+          field: string
+          action: string
+          oldValue: string | null
+          newValue: string | null
+        }> = []
+        if (next.title !== existing.title) {
+          diffs.push({
+            field: 'title',
+            action: 'update',
+            oldValue: existing.title,
+            newValue: next.title,
+          })
+        }
+        if (next.description !== existing.description) {
+          diffs.push({
+            field: 'description',
+            action: 'update',
+            oldValue: existing.description,
+            newValue: next.description,
+          })
+        }
+        if (next.status !== existing.status) {
+          diffs.push({
+            field: 'status',
+            action: 'status_change',
+            oldValue: existing.status,
+            newValue: next.status,
+          })
+        }
+        if (next.metadata !== existing.metadata) {
+          diffs.push({
+            field: 'metadata',
+            action: 'update',
+            oldValue: existing.metadata,
+            newValue: next.metadata,
+          })
+        }
+
         const now = new Date().toISOString()
-        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,
-          ],
-        )
+        db.raw.transaction(() => {
+          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,
+            ],
+          )
+          for (const d of diffs) {
+            insertAudit(db, {
+              nodeId: args.id,
+              action: d.action,
+              field: d.field,
+              oldValue: d.oldValue,
+              newValue: d.newValue,
+            })
+          }
+        })()
         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
+          .query(`SELECT ${NODE_COLS} FROM nodes WHERE id = ?`)
+          .get(args.id) as NodeRow | null
         if (!existing) throw notFoundError(`Node ${args.id} not found`)
 
         // The hierarchy is client -> project -> feature -> task via `part_of`
@@ -407,6 +610,15 @@ export function createResolvers(db: Db) {
         }
 
         db.raw.transaction(() => {
+          // Record the delete with the pre-delete snapshot BEFORE removing the
+          // node. node_id is null (the node is gone) to match SaaS. The FK's
+          // ON DELETE SET NULL also nulls node_id on the node's prior audit
+          // rows when the node row below is deleted.
+          insertAudit(db, {
+            nodeId: null,
+            action: 'delete',
+            snapshot: rowToNode(existing) as unknown as Record<string, unknown>,
+          })
           db.raw.run('DELETE FROM edges WHERE source_id = ? OR target_id = ?', [
             args.id,
             args.id,
@@ -427,11 +639,19 @@ export function createResolvers(db: Db) {
           )
         }
         const now = new Date().toISOString()
-        db.raw.run('UPDATE nodes SET status = ?, updated_at = ? WHERE id = ?', [
-          'approved',
-          now,
-          args.id,
-        ])
+        db.raw.transaction(() => {
+          db.raw.run(
+            'UPDATE nodes SET status = ?, updated_at = ? WHERE id = ?',
+            ['approved', now, args.id],
+          )
+          insertAudit(db, {
+            nodeId: args.id,
+            action: 'approve',
+            field: 'status',
+            oldValue: 'pending_review',
+            newValue: 'approved',
+          })
+        })()
         return rowToNode({ ...existing, status: 'approved', updated_at: now })
       },
 
@@ -461,10 +681,20 @@ export function createResolvers(db: Db) {
           throw validationError('A node cannot block itself')
         }
         const now = new Date().toISOString()
-        db.raw.run(
-          'INSERT INTO edges (source_id, target_id, relation, created_at) VALUES (?, ?, ?, ?)',
-          [args.sourceId, args.targetId, args.relation, now],
-        )
+        db.raw.transaction(() => {
+          db.raw.run(
+            'INSERT INTO edges (source_id, target_id, relation, created_at) VALUES (?, ?, ?, ?)',
+            [args.sourceId, args.targetId, args.relation, now],
+          )
+          // Record the edge against its source node so `auditLog(sourceId)`
+          // surfaces it. field = relation; newValue = the target it now links.
+          insertAudit(db, {
+            nodeId: args.sourceId,
+            action: 'create_edge',
+            field: args.relation,
+            newValue: args.targetId,
+          })
+        })()
         return {
           sourceId: args.sourceId,
           targetId: args.targetId,
@@ -477,11 +707,25 @@ export function createResolvers(db: Db) {
         _: unknown,
         args: { sourceId: string; targetId: string; relation: string },
       ) => {
-        const result = db.raw.run(
-          'DELETE FROM edges WHERE source_id = ? AND target_id = ? AND relation = ?',
-          [args.sourceId, args.targetId, args.relation],
-        )
-        return result.changes > 0
+        let changed = false
+        db.raw.transaction(() => {
+          const result = db.raw.run(
+            'DELETE FROM edges WHERE source_id = ? AND target_id = ? AND relation = ?',
+            [args.sourceId, args.targetId, args.relation],
+          )
+          changed = result.changes > 0
+          // Only audit an edge that actually existed. oldValue = the target the
+          // edge linked to before removal.
+          if (changed) {
+            insertAudit(db, {
+              nodeId: args.sourceId,
+              action: 'remove_edge',
+              field: args.relation,
+              oldValue: args.targetId,
+            })
+          }
+        })()
+        return changed
       },
     },
   }

package/server/src/schema.ts

@@ -19,14 +19,48 @@ export const typeDefs = /* GraphQL */ `
     createdAt: String!
   }
 
+  # An audit-log entry. Shaped to match the SaaS \`auditLog\` field so
+  # \`flowy history\` output is consistent across backends. \`snapshot\` is a
+  # JSON-encoded string (or null).
+  type AuditEntry {
+    id: String!
+    nodeId: String
+    action: String!
+    field: String
+    oldValue: String
+    newValue: String
+    snapshot: String
+    changedBy: String!
+    createdAt: String!
+  }
+
+  # A node returned from a subtree traversal, annotated with how it was reached:
+  # the parent it descends from (parentId), how many edges down the root it sits
+  # (depth, root's direct children are depth 1), and the relation of the edge
+  # that links it to its parent.
+  type SubtreeNode {
+    id: String!
+    type: String!
+    title: String!
+    description: String
+    status: String!
+    metadata: String
+    createdAt: String!
+    updatedAt: String!
+    parentId: String!
+    depth: Int!
+    relation: String!
+  }
+
   type Query {
     node(id: String!): Node
     nodes(type: String): [Node!]!
     descendants(nodeId: String!, relation: String, maxDepth: Int): [Node!]!
-    subtree(nodeId: String!, maxDepth: Int): [Node!]!
+    subtree(nodeId: String!, relation: String, maxDepth: Int): [SubtreeNode!]!
     edges(nodeId: String!, relation: String!, direction: String): [Node!]!
     readyTasks(projectId: String): [Node!]!
     search(query: String!, type: String, status: String, limit: Int): [Node!]!
+    auditLog(nodeId: String!, limit: Int): [AuditEntry!]!
   }
 
   type Mutation {

package/src/commands/history.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+describe('history command', () => {
+  test('exports a flat command with id argument and limit option', async () => {
+    const { historyCommand } = await import('./history.ts')
+    expect(historyCommand.name()).toBe('history')
+    expect(historyCommand.commands).toHaveLength(0)
+    const limitOpt = historyCommand.options.find((o) => o.long === '--limit')
+    expect(limitOpt).toBeDefined()
+  })
+
+  describe('action', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    afterEach(() => {
+      vi.restoreAllMocks()
+      vi.unstubAllEnvs()
+    })
+
+    test('sends the AUDIT_LOG op with the node id and prints results', async () => {
+      const calls: Array<{ query: string; variables: unknown }> = []
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async (query: string, variables: unknown) => {
+          calls.push({ query, variables })
+          return {
+            auditLog: [
+              {
+                id: 'audit_1',
+                action: 'create',
+                field: null,
+                oldValue: null,
+                newValue: null,
+                snapshot: '{"id":"task_1"}',
+                changedBy: 'local',
+                createdAt: '2026-06-13T00:00:00.000Z',
+              },
+            ],
+          }
+        }),
+      }))
+      const outputs: unknown[] = []
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn((data: unknown) => outputs.push(data)),
+        outputError: vi.fn(),
+      }))
+
+      const { AUDIT_LOG } = await import('../util/operations.ts')
+      const { historyCommand } = await import('./history.ts')
+      await historyCommand.parseAsync(['task_1'], { from: 'user' })
+
+      expect(calls).toHaveLength(1)
+      expect(calls[0]!.query).toBe(AUDIT_LOG)
+      expect(calls[0]!.variables).toMatchObject({ nodeId: 'task_1' })
+
+      const rendered = outputs[0] as Array<Record<string, unknown>>
+      expect(rendered[0]).toMatchObject({ id: 'audit_1', action: 'create' })
+    })
+
+    test('passes --limit through to the op', async () => {
+      const calls: Array<{ variables: unknown }> = []
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async (_query: string, variables: unknown) => {
+          calls.push({ variables })
+          return { auditLog: [] }
+        }),
+      }))
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn(),
+        outputError: vi.fn(),
+      }))
+
+      const { historyCommand } = await import('./history.ts')
+      await historyCommand.parseAsync(['task_1', '--limit', '5'], {
+        from: 'user',
+      })
+
+      expect(calls[0]!.variables).toMatchObject({ nodeId: 'task_1', limit: 5 })
+    })
+
+    test('reports errors via outputError', async () => {
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async () => {
+          throw new Error('boom')
+        }),
+      }))
+      const errors: unknown[] = []
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn(),
+        outputError: vi.fn((e: unknown) => errors.push(e)),
+      }))
+
+      const { historyCommand } = await import('./history.ts')
+      await historyCommand.parseAsync(['task_1'], { from: 'user' })
+      expect(errors).toHaveLength(1)
+    })
+  })
+})

package/src/commands/history.ts

@@ -0,0 +1,20 @@
+import { Command } from 'commander'
+import { graphql } from '../util/client.ts'
+import { output, outputError } from '../util/format.ts'
+import { AUDIT_LOG } from '../util/operations.ts'
+
+export const historyCommand = new Command('history')
+  .description('Show the audit history of a node (newest first)')
+  .argument('<id>', 'Node ID')
+  .option('--limit <n>', 'Limit results', '50')
+  .action(async (id: string, opts) => {
+    try {
+      const data = await graphql<{ auditLog: unknown[] }>(AUDIT_LOG, {
+        nodeId: id,
+        limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined,
+      })
+      output(data.auditLog)
+    } catch (error) {
+      outputError(error)
+    }
+  })

package/src/commands/tree.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'vitest'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 
 describe('tree command', () => {
   test('exports a flat command with id argument and depth option', async () => {
@@ -6,4 +6,92 @@ describe('tree command', () => {
     expect(treeCommand.name()).toBe('tree')
     expect(treeCommand.commands).toHaveLength(0)
   })
+
+  test('exposes a --relation option defaulting to part_of', async () => {
+    const { treeCommand } = await import('./tree.ts')
+    const relationOpt = treeCommand.options.find((o) => o.long === '--relation')
+    expect(relationOpt).toBeDefined()
+    expect(relationOpt?.defaultValue).toBe('part_of')
+  })
+
+  describe('action', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    afterEach(() => {
+      vi.restoreAllMocks()
+      vi.unstubAllEnvs()
+    })
+
+    test('sends the SUBTREE op with the relation filter and renders depth/relation', async () => {
+      const calls: Array<{ query: string; variables: unknown }> = []
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async (query: string, variables: unknown) => {
+          calls.push({ query, variables })
+          return {
+            subtree: [
+              {
+                id: 'feat_1',
+                type: 'feature',
+                title: 'F1',
+                status: 'draft',
+                parentId: 'proj_1',
+                depth: 1,
+                relation: 'part_of',
+              },
+            ],
+          }
+        }),
+      }))
+      const outputs: unknown[] = []
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn((data: unknown) => outputs.push(data)),
+        outputError: vi.fn(),
+      }))
+
+      const { SUBTREE } = await import('../util/operations.ts')
+      const { treeCommand } = await import('./tree.ts')
+      await treeCommand.parseAsync(['proj_1'], { from: 'user' })
+
+      expect(calls).toHaveLength(1)
+      expect(calls[0]!.query).toBe(SUBTREE)
+      expect(calls[0]!.variables).toMatchObject({
+        nodeId: 'proj_1',
+        relation: 'part_of',
+      })
+
+      const rendered = outputs[0] as Array<Record<string, unknown>>
+      expect(rendered[0]).toMatchObject({
+        id: 'feat_1',
+        parentId: 'proj_1',
+        depth: 1,
+        relation: 'part_of',
+      })
+    })
+
+    test('passes an overridden relation through to the op', async () => {
+      const calls: Array<{ variables: unknown }> = []
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async (_query: string, variables: unknown) => {
+          calls.push({ variables })
+          return { subtree: [] }
+        }),
+      }))
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn(),
+        outputError: vi.fn(),
+      }))
+
+      const { treeCommand } = await import('./tree.ts')
+      await treeCommand.parseAsync(['task_1', '--relation', 'blocks'], {
+        from: 'user',
+      })
+
+      expect(calls[0]!.variables).toMatchObject({
+        nodeId: 'task_1',
+        relation: 'blocks',
+      })
+    })
+  })
 })

package/src/commands/tree.ts

@@ -7,10 +7,16 @@ export const treeCommand = new Command('tree')
   .description('Show subtree from any entity')
   .argument('<id>', 'Root node ID')
   .option('--depth <n>', 'Max depth', '10')
+  .option(
+    '--relation <relation>',
+    'Edge relation to follow (e.g. part_of, blocks)',
+    'part_of',
+  )
   .action(async (id: string, opts) => {
     try {
       const data = await graphql<{ subtree: unknown[] }>(SUBTREE, {
         nodeId: id,
+        relation: opts.relation,
         maxDepth: Number.parseInt(opts.depth, 10),
       })
       output(data.subtree)

package/src/index.test.ts

@@ -30,6 +30,9 @@ vi.mock('./commands/task.ts', () => ({
 vi.mock('./commands/tree.ts', () => ({
   treeCommand: { name: () => 'tree' },
 }))
+vi.mock('./commands/history.ts', () => ({
+  historyCommand: { name: () => 'history' },
+}))
 vi.mock('./commands/whoami.ts', () => ({
   whoamiCommand: { name: () => 'whoami' },
 }))
@@ -96,4 +99,17 @@ describe('index.ts command registration', () => {
     expect(indexSource).toContain('program.addCommand(importCommand)')
     expect(indexSource).toContain('program.addCommand(exportCommand)')
   })
+
+  test('registers the history command', async () => {
+    const { readFileSync } = await import('node:fs')
+    const indexSource = readFileSync(
+      new URL('./index.ts', import.meta.url).pathname,
+      'utf-8',
+    )
+
+    expect(indexSource).toContain(
+      "import { historyCommand } from './commands/history.ts'",
+    )
+    expect(indexSource).toContain('program.addCommand(historyCommand)')
+  })
 })

package/src/index.ts

@@ -16,6 +16,7 @@ import { billingCommand } from './commands/billing.ts'
 import { clientCommand } from './commands/client.ts'
 import { exportCommand } from './commands/export.ts'
 import { featureCommand } from './commands/feature.ts'
+import { historyCommand } from './commands/history.ts'
 import { importCommand } from './commands/import.ts'
 import { initCommand } from './commands/init.ts'
 import { keyCommand } from './commands/key.ts'
@@ -46,6 +47,7 @@ program.addCommand(billingCommand)
 program.addCommand(keyCommand)
 program.addCommand(searchCommand)
 program.addCommand(treeCommand)
+program.addCommand(historyCommand)
 program.addCommand(whoamiCommand)
 program.addCommand(importCommand)
 program.addCommand(exportCommand)

package/src/util/operations.test.ts

@@ -81,6 +81,7 @@ describe('commands send canonical operations (no re-inlined queries)', () => {
     'approve.ts': ['APPROVE_NODE'],
     'search.ts': ['SEARCH'],
     'tree.ts': ['SUBTREE'],
+    'history.ts': ['AUDIT_LOG'],
     'whoami.ts': ['WHOAMI'],
     'billing.ts': ['CREATE_CHECKOUT'],
     'key.ts': ['ROTATE_API_KEY'],

package/src/util/operations.ts

@@ -15,7 +15,9 @@
  * field, or an argument the CLI uses, the contract test fails — catching drift
  * before it ships. See `server/src/contract.test.ts` for the documented list
  * of intentional local/SaaS divergences (SaaS-only `whoami`, `register`,
- * `rotateApiKey`, `createCheckout`, `auditLog`, `ancestors`).
+ * `rotateApiKey`, `createCheckout`). `auditLog` was a SaaS-only divergence
+ * until P1-2/F27 ported it to the bundled local server; it is now part of the
+ * shared LOCAL_CONTRACT_OPERATIONS set.
  */
 
 // --- Nodes: read --------------------------------------------------------------
@@ -76,10 +78,11 @@ export const LIST_TASKS = `query ListTasks($nodeId: String!, $relation: String!,
   }
 }`
 
-/** tree.ts — full subtree from any root. */
-export const SUBTREE = `query Subtree($nodeId: String!, $maxDepth: Int) {
-  subtree(nodeId: $nodeId, maxDepth: $maxDepth) {
-    id type title status
+/** tree.ts — subtree from any root, filtered to one relation (default part_of),
+ *  each node annotated with parentId/depth/relation. */
+export const SUBTREE = `query Subtree($nodeId: String!, $relation: String, $maxDepth: Int) {
+  subtree(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
+    id type title status parentId depth relation
   }
 }`
 
@@ -120,6 +123,18 @@ export const SEARCH = `query Search($query: String!, $type: String, $status: Str
   }
 }`
 
+/**
+ * history.ts — audit history for a node, newest first. Served by BOTH backends:
+ * the SaaS server (always) and, since P1-2/F27, the bundled local server. The
+ * selection set mirrors the SaaS `auditLog` query (flowy-saas
+ * `test/helpers/cli-queries.ts`) so output is identical across backends.
+ */
+export const AUDIT_LOG = `query AuditLog($nodeId: String!, $limit: Int) {
+  auditLog(nodeId: $nodeId, limit: $limit) {
+    id action field oldValue newValue snapshot changedBy createdAt
+  }
+}`
+
 // --- Nodes: write -------------------------------------------------------------
 
 /** project.ts `create`, init.ts — create a node by type/title. */
@@ -317,6 +332,7 @@ export const LOCAL_CONTRACT_OPERATIONS = {
   EXPORT_PROJECT,
   EXPORT_DESCENDANTS,
   EXPORT_EDGES,
+  AUDIT_LOG,
 } as const
 
 /**