Add nlink column to fs_inode for O(1) link count lookups

Previously, the link count was computed on-demand via:
  SELECT COUNT(*) FROM fs_dentry WHERE ino = ?

This query becomes expensive as the number of directory entries grows.
By storing nlink directly in the inode, we get O(1) lookups.

Author: penberg

SPEC.md

@@ -1,6 +1,6 @@
 # Agent Filesystem Specification
 
-**Version:** 0.1
+**Version:** 0.2
 
 ## Introduction
 
@@ -164,6 +164,7 @@ Stores file and directory metadata.
 CREATE TABLE fs_inode (
   ino INTEGER PRIMARY KEY AUTOINCREMENT,
   mode INTEGER NOT NULL,
+  nlink INTEGER NOT NULL DEFAULT 0,
   uid INTEGER NOT NULL DEFAULT 0,
   gid INTEGER NOT NULL DEFAULT 0,
   size INTEGER NOT NULL DEFAULT 0,
@@ -177,6 +178,7 @@ CREATE TABLE fs_inode (
 
 - `ino` - Inode number (unique identifier)
 - `mode` - File type and permissions (Unix mode bits)
+- `nlink` - Number of hard links pointing to this inode
 - `uid` - Owner user ID
 - `gid` - Owner group ID
 - `size` - Total file size in bytes
@@ -238,7 +240,7 @@ CREATE INDEX idx_fs_dentry_parent ON fs_dentry(parent_ino, name)
 
 - Root directory (ino=1) has no dentry (no parent)
 - Multiple dentries MAY point to the same inode (hard links)
-- Link count = `SELECT COUNT(*) FROM fs_dentry WHERE ino = ?`
+- Link count is stored in `fs_inode.nlink` and must be incremented/decremented when dentries are added/removed
 
 #### Table: `fs_data`
 
@@ -316,13 +318,17 @@ To resolve a path to an inode:
    INSERT INTO fs_dentry (name, parent_ino, ino)
    VALUES (?, ?, ?)
    ```
-5. Split data into chunks and insert each:
+5. Increment link count:
+   ```sql
+   UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?
+   ```
+6. Split data into chunks and insert each:
    ```sql
    INSERT INTO fs_data (ino, chunk_index, data)
    VALUES (?, ?, ?)
    ```
    Where `chunk_index` starts at 0 and increments for each chunk.
-6. Update inode size:
+7. Update inode size:
    ```sql
    UPDATE fs_inode SET size = ?, mtime = ? WHERE ino = ?
    ```
@@ -378,13 +384,18 @@ To read `length` bytes starting at byte offset `offset`:
    ```sql
    DELETE FROM fs_dentry WHERE parent_ino = ? AND name = ?
    ```
-3. Check if last link:
+3. Decrement link count:
+   ```sql
+   UPDATE fs_inode SET nlink = nlink - 1 WHERE ino = ?
+   ```
+4. Check if last link:
    ```sql
-   SELECT COUNT(*) FROM fs_dentry WHERE ino = ?
+   SELECT nlink FROM fs_inode WHERE ino = ?
    ```
-4. If count = 0, delete inode (CASCADE deletes data):
+5. If nlink = 0, delete inode and data:
    ```sql
    DELETE FROM fs_inode WHERE ino = ?
+   DELETE FROM fs_data WHERE ino = ?
    ```
 
 #### Creating a Hard Link
@@ -396,19 +407,19 @@ To read `length` bytes starting at byte offset `offset`:
    INSERT INTO fs_dentry (name, parent_ino, ino)
    VALUES (?, ?, ?)
    ```
+4. Increment link count:
+   ```sql
+   UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?
+   ```
 
 #### Reading File Metadata (stat)
 
 1. Resolve path to inode
-2. Query inode:
+2. Query inode (includes link count):
    ```sql
-   SELECT ino, mode, uid, gid, size, atime, mtime, ctime
+   SELECT ino, mode, nlink, uid, gid, size, atime, mtime, ctime
    FROM fs_inode WHERE ino = ?
    ```
-3. Count links:
-   ```sql
-   SELECT COUNT(*) as nlink FROM fs_dentry WHERE ino = ?
-   ```
 
 ### Initialization
 
@@ -419,13 +430,13 @@ When creating a new agent database, initialize the filesystem configuration and
 INSERT INTO fs_config (key, value) VALUES ('chunk_size', '4096');
 
 -- Initialize root directory
-INSERT INTO fs_inode (ino, mode, uid, gid, size, atime, mtime, ctime)
-VALUES (1, 16877, 0, 0, 0, unixepoch(), unixepoch(), unixepoch());
+INSERT INTO fs_inode (ino, mode, nlink, uid, gid, size, atime, mtime, ctime)
+VALUES (1, 16877, 1, 0, 0, 0, unixepoch(), unixepoch(), unixepoch());
 ```
 
 Where `16877` = `0o040755` (directory with rwxr-xr-x permissions)
 
-**Note:** The `chunk_size` value can be customized at filesystem creation time but MUST NOT be changed afterward.
+**Note:** The `chunk_size` value can be customized at filesystem creation time but MUST NOT be changed afterward. The root directory has `nlink=1` as it has no parent directory entry.
 
 ### Consistency Rules
 
@@ -633,6 +644,8 @@ Such extensions SHOULD use separate tables to maintain referential integrity.
 
 - Added Overlay Filesystem section with `fs_whiteout` table for copy-on-write semantics
 - Whiteout table includes `parent_path` column with index for efficient O(1) child lookups
+- Added `nlink` column to `fs_inode` table to store link count directly
+- Link count is now maintained in the inode rather than computed via COUNT(*) on `fs_dentry`
 
 ### Version 0.1
 

sdk/python/agentfs_sdk/filesystem.py

@@ -101,6 +101,7 @@ async def _initialize(self) -> None:
             CREATE TABLE IF NOT EXISTS fs_inode (
                 ino INTEGER PRIMARY KEY AUTOINCREMENT,
                 mode INTEGER NOT NULL,
+                nlink INTEGER NOT NULL DEFAULT 0,
                 uid INTEGER NOT NULL DEFAULT 0,
                 gid INTEGER NOT NULL DEFAULT 0,
                 size INTEGER NOT NULL DEFAULT 0,
@@ -161,8 +162,8 @@ async def _ensure_root(self) -> int:
             now = int(time.time())
             await self._db.execute(
                 """
-                INSERT INTO fs_inode (ino, mode, uid, gid, size, atime, mtime, ctime)
-                VALUES (?, ?, 0, 0, 0, ?, ?, ?)
+                INSERT INTO fs_inode (ino, mode, nlink, uid, gid, size, atime, mtime, ctime)
+                VALUES (?, ?, 1, 0, 0, 0, ?, ?, ?)
                 """,
                 (self._root_ino, DEFAULT_DIR_MODE, now, now, now),
             )
@@ -266,6 +267,11 @@ async def _create_dentry(self, parent_ino: int, name: str, ino: int) -> None:
             """,
             (name, parent_ino, ino),
         )
+        # Increment link count
+        await self._db.execute(
+            "UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?",
+            (ino,),
+        )
         await self._db.commit()
 
     async def _ensure_parent_dirs(self, path: str) -> None:
@@ -301,7 +307,7 @@ async def _ensure_parent_dirs(self, path: str) -> None:
 
     async def _get_link_count(self, ino: int) -> int:
         """Get link count for an inode"""
-        cursor = await self._db.execute("SELECT COUNT(*) FROM fs_dentry WHERE ino = ?", (ino,))
+        cursor = await self._db.execute("SELECT nlink FROM fs_inode WHERE ino = ?", (ino,))
         result = await cursor.fetchone()
         return result[0] if result else 0
 
@@ -477,6 +483,12 @@ async def delete_file(self, path: str) -> None:
             (parent_ino, name),
         )
 
+        # Decrement link count
+        await self._db.execute(
+            "UPDATE fs_inode SET nlink = nlink - 1 WHERE ino = ?",
+            (ino,),
+        )
+
         # Check if this was the last link to the inode
         link_count = await self._get_link_count(ino)
         if link_count == 0:
@@ -508,7 +520,7 @@ async def stat(self, path: str) -> Stats:
 
         cursor = await self._db.execute(
             """
-            SELECT ino, mode, uid, gid, size, atime, mtime, ctime
+            SELECT ino, mode, nlink, uid, gid, size, atime, mtime, ctime
             FROM fs_inode
             WHERE ino = ?
             """,
@@ -519,16 +531,14 @@ async def stat(self, path: str) -> Stats:
         if not row:
             raise ValueError(f"Inode not found: {ino}")
 
-        nlink = await self._get_link_count(ino)
-
         return Stats(
             ino=row[0],
             mode=row[1],
-            nlink=nlink,
-            uid=row[2],
-            gid=row[3],
-            size=row[4],
-            atime=row[5],
-            mtime=row[6],
-            ctime=row[7],
+            nlink=row[2],
+            uid=row[3],
+            gid=row[4],
+            size=row[5],
+            atime=row[6],
+            mtime=row[7],
+            ctime=row[8],
         )