@sqaoss/flowy 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.9.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
@@ -364,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,
@@ -414,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

@@ -1415,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,36 @@ 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
@@ -105,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,
@@ -330,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: {
@@ -354,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,
@@ -368,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: (
@@ -406,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`
@@ -442,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,
@@ -462,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 })
       },
 
@@ -496,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,
@@ -512,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,6 +19,21 @@ 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
@@ -45,6 +60,7 @@ export const typeDefs = /* GraphQL */ `
     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/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 --------------------------------------------------------------
@@ -121,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. */
@@ -318,6 +332,7 @@ export const LOCAL_CONTRACT_OPERATIONS = {
   EXPORT_PROJECT,
   EXPORT_DESCENDANTS,
   EXPORT_EDGES,
+  AUDIT_LOG,
 } as const
 
 /**