schfs: snapshots

A snapshot is a tree root that is kept. The B-tree is copy-on-write, so
the blocks a committed root reaches are already immutable -- nothing
overwrites a block a committed tree can reach -- and retaining one costs
a record: (SNAP_OBJECTID, KEY_SNAP, id) -> struct schfs_snap.

The record names the root as it was *before* the record was added.
Inserting it rewrites the path under copy-on-write and produces a new
root, so a snapshot that included its own creation would name a block
nobody had written yet.

What makes it survive is the derivation. There is no free-space map on
disk; it is rebuilt at mount by walking the tree, and that walk now
covers every snapshot root as well as the live one. Without it a block
reachable only from a snapshot looks free, gets handed out, and
overwrites the data the snapshot exists to keep -- silently, surfacing
only when the snapshot is read. A snapshot's own tree may hold older
snapshot records; those are deliberately not followed, or deleting a
snapshot could be undone by an older one's memory of it.

Runtime frees are suspended while a snapshot exists. Knowing which freed
blocks a snapshot still needs requires per-extent reference counting,
which is a design and not a flag; until that exists the safe answer is to
free nothing and let the next mount's derivation reclaim what is
genuinely unreachable. Allocation is unaffected and stays correct -- it
works from the in-use bitmap the derivation filled. The running
free-blocks *counter* does drift from the truth while a snapshot is
present, which is cosmetic and is reported by the test rather than
asserted away.

Tested in schfs_objtest: after a snapshot, the live tree shows new
contents while the snapshot still shows the old ones; a file deleted from
the live tree is still readable through the snapshot; deleting the
snapshot removes the record and the space comes back at the next mount.

schfs-check passes including the round-trip; bootcheck 108 [ok].

Not yet: snapshots are not reachable by name from userspace -- there is
no mount-a-snapshot path, so this is the format and the mechanism, not
the feature a user sees.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

include/schfs.h

@@ -39,6 +39,7 @@
 #define SCHFS_KEY_ATTR    4   // (ino,   ATTR,   namehash)  -> attribute value
 #define SCHFS_KEY_INDEX   5   // (idxid, INDEX,  valuehash) -> objectid
 #define SCHFS_KEY_CSUM    6   // (CSUM,  CSUM,   diskblk)   -> uint32 CRC32c
+#define SCHFS_KEY_SNAP    7   // (SNAP,  SNAP,    id)        -> struct schfs_snap
 
 // Data-block checksums live under one reserved object id, exactly as btrfs
 // keeps a checksum tree. Tree nodes carry their checksum in their parent
@@ -46,6 +47,11 @@
 // records "end-to-end checksums" would only cover metadata, which is the part
 // least likely to rot.
 #define SCHFS_CSUM_OBJECTID  1ULL
+// Snapshots live under their own reserved objectid, as ordinary records in the
+// live tree. A snapshot is nothing more than a tree root that is kept: the
+// B-tree is copy-on-write, so the blocks a root reaches are already immutable
+// as long as nothing frees them. Keeping one costs a record.
+#define SCHFS_SNAP_OBJECTID  2ULL
 
 // Object ids below this are reserved; the root directory is the first real one.
 #define SCHFS_FIRST_OBJECTID 16ULL
@@ -122,6 +128,32 @@ struct schfs_item {
 #define SCHFS_VERSION     1
 #define SCHFS_LABEL_MAX   32
 
+// A retained tree root.
+//
+// The root a snapshot names is a *previous* version of the live tree, and it is
+// reached exactly as the live one is -- same node format, same checksums. What
+// makes it survive is schfs_space_scan walking it too, so its blocks are never
+// handed out again.
+//
+// The record is stored in the live tree, which means creating one rewrites the
+// path to it under copy-on-write and produces a new live root. That is correct
+// and is why the snapshot names the root as it was *before* the record was
+// added: a snapshot that included its own creation would have to refer to a
+// block that does not exist yet.
+#define SCHFS_SNAP_NAME_MAX 64
+
+// Set on a volume that has at least one snapshot. See schfs_space_free.
+#define SCHFS_SPACE_RETAIN_ALL 1
+
+struct schfs_snap {
+    uint64_t root;              // block number of the retained tree root
+    uint64_t root_generation;
+    uint32_t root_crc;          // checksum of that root block
+    uint32_t pad0;
+    uint64_t created;           // generation the snapshot was taken at
+    char     name[SCHFS_SNAP_NAME_MAX];
+};
+
 struct schfs_uberblock {
     uint32_t magic;             // SCHFS_MAGIC
     uint32_t crc;               // CRC32c of this struct, this field zeroed

kernel/fs/schfs/obj.c

@@ -138,6 +138,23 @@ schfs_inode_get(struct schfs_vol *v, struct schfs_cursor *c,
     return 0;
 }
 
+int
+schfs_snap_get(struct schfs_vol *v, struct schfs_cursor *c, uint64_t id,
+               struct schfs_snap *out)
+{
+    struct schfs_key k;
+    schfs_mkkey(&k, SCHFS_SNAP_OBJECTID, SCHFS_KEY_SNAP, id);
+
+    cur_bind(c, v);
+    unsigned len = sizeof(*out);
+    int r = schfs_btree_lookup_cur(c, &k, out, &len);
+    if (r != 0)
+        return r;
+    if (len != sizeof(*out))
+        return -2;
+    return 0;
+}
+
 /* ------------------------------------------------------------------ */
 /* Directories                                                         */
 /* ------------------------------------------------------------------ */

kernel/fs/schfs/objw.c

@@ -42,6 +42,76 @@ schfs_alloc_objectid(struct schfs_vol *v)
     return v->next_objectid++;
 }
 
+/* ------------------------------------------------------------------ */
+/* Snapshots                                                           */
+/*                                                                     */
+/* A snapshot is a tree root that is kept. Copy-on-write means the      */
+/* blocks that root reaches are already immutable -- nothing overwrites */
+/* a block a committed tree can reach -- so retaining one costs a       */
+/* record, and keeping it alive is entirely schfs_space_scan's job.     */
+/* ------------------------------------------------------------------ */
+
+// Take a snapshot of the volume as it is committed *now*.
+//
+// The root recorded is the one in v->tree before this call, which is the
+// committed state. It cannot be the root this call produces: adding the record
+// rewrites the path to it under copy-on-write, so that root does not exist
+// until afterwards, and a snapshot naming it would name a block nobody had
+// written yet.
+//
+// The caller commits. Until it does, the record is not on disk and the
+// snapshot does not exist -- which is the correct failure mode, because a
+// snapshot that survived a crash while the tree it names did not would be a
+// dangling root.
+int
+schfs_snap_create(struct schfs_vol *v, uint64_t id, const char *name,
+                  unsigned namelen)
+{
+    schfs_cache_invalidate();
+
+    if (namelen >= SCHFS_SNAP_NAME_MAX)
+        return -1;
+
+    struct schfs_snap sn;
+    memset(&sn, 0, sizeof sn);
+    sn.root            = v->tree.root;
+    sn.root_crc        = v->tree.root_crc;
+    sn.root_generation = v->tree.root_gen;
+    sn.created         = v->tree.generation;
+    for (unsigned i = 0; i < namelen; i++)
+        sn.name[i] = name[i];
+
+    struct schfs_key k;
+    schfs_mkkey(&k, SCHFS_SNAP_OBJECTID, SCHFS_KEY_SNAP, id);
+    int r = schfs_btree_insert(&v->tree, &v->ctx, &k, &sn, sizeof sn);
+    if (r == 0)
+        v->space.flags |= SCHFS_SPACE_RETAIN_ALL;
+    return r;
+}
+
+// Forget a snapshot. The blocks it was holding are not freed here: they stop
+// being reachable, and the next derivation at mount simply does not mark them.
+// That is the whole deletion -- there is no reference count to decrement,
+// because there never was one.
+int
+schfs_snap_delete(struct schfs_vol *v, uint64_t id)
+{
+    schfs_cache_invalidate();
+    struct schfs_key k;
+    schfs_mkkey(&k, SCHFS_SNAP_OBJECTID, SCHFS_KEY_SNAP, id);
+    int r = schfs_btree_delete(&v->tree, &v->ctx, &k);
+    if (r != 0)
+        return r;
+
+    // Stop retaining. If other snapshots remain, the next mount's derivation
+    // sets the flag again -- it is the walk that knows, not this function, and
+    // guessing here would mean keeping a second count to disagree with it.
+    // Until that mount the allocator is merely conservative, which is the safe
+    // direction.
+    v->space.flags &= ~(unsigned)SCHFS_SPACE_RETAIN_ALL;
+    return 0;
+}
+
 int
 schfs_inode_put(struct schfs_vol *v, uint64_t ino, const struct schfs_inode *in)
 {

kernel/fs/schfs/schfs_int.h

@@ -43,6 +43,8 @@ struct schfs_space {
     uint64_t  free_blocks;
     uint64_t  pending;                   // bits set in pend[], counted
     uint64_t  hint;                      // rotating search start
+    // SCHFS_SPACE_RETAIN_ALL while a snapshot exists -- see schfs_space_free.
+    unsigned  flags;
 };
 
 // A mounted (or under-construction) volume.
@@ -109,6 +111,15 @@ int schfs_vol_format(struct schfs_vol *v, struct schfs_bdev *dev,
 // discards it — which is exactly what makes the format crash-safe.
 int schfs_vol_commit(struct schfs_vol *v);
 
+// Snapshots. Create records the *committed* root; the caller commits after.
+// Lookup fills `out` for a given id. Deleting forgets the record, and the next
+// derivation stops marking what only it reached.
+int schfs_snap_create(struct schfs_vol *v, uint64_t id, const char *name,
+                      unsigned namelen);
+int schfs_snap_delete(struct schfs_vol *v, uint64_t id);
+int schfs_snap_get(struct schfs_vol *v, struct schfs_cursor *c, uint64_t id,
+                   struct schfs_snap *out);
+
 // Block allocation. Returns 0 when the volume is full.
 //
 // Not themselves schfs_bdev callbacks: a bdev has one ctx shared by all of its

kernel/fs/schfs/space.c

@@ -207,6 +207,23 @@ schfs_space_alloc(struct schfs_space *s)
 void
 schfs_space_free(struct schfs_space *s, uint64_t blk)
 {
+    // A snapshot exists, so this block may still be reachable from it.
+    //
+    // Copy-on-write frees the old block whenever one is rewritten, and that is
+    // exactly the block a snapshot is holding. Freeing it would hand it out
+    // again and overwrite the data the snapshot exists to keep -- silently,
+    // with the damage only visible later when the snapshot is read.
+    //
+    // Knowing *which* freed blocks a snapshot still needs requires reference
+    // counting per extent, which is a real design and not a flag. Until that
+    // exists, the safe answer is to free nothing while a snapshot is present:
+    // the free map is derived at mount anyway, so everything genuinely
+    // unreachable is reclaimed on the next mount rather than lost. Conservative
+    // in the only direction that is safe -- it can under-report free space, and
+    // can never hand out a block that is still in use.
+    if (s->flags & SCHFS_SPACE_RETAIN_ALL)
+        return;
+
     if (blk < SCHFS_FIRST_BLOCK || blk >= s->nblocks)
         return;
     if (!bit_test(s->inuse, blk))
@@ -261,6 +278,42 @@ mark_leaf_extents(struct schfs_space *s, const void *blk)
     }
 }
 
+// Snapshot roots found while walking, so they can be walked in turn.
+//
+// Collected rather than descended into immediately: the walk keeps one block
+// buffer and a path, and re-entering it from inside itself would need a second
+// of each.
+#define SNAP_ROOTS_MAX 64
+
+struct snap_roots {
+    int      n;
+    int      overflow;
+    uint64_t nr[SNAP_ROOTS_MAX];
+    uint32_t crc[SNAP_ROOTS_MAX];
+};
+
+static void
+collect_snap_roots(struct snap_roots *sr, const void *blk)
+{
+    const struct schfs_item *it = SCHFS_ITEMS(blk);
+    int n = SCHFS_HDR(blk)->nritems;
+
+    for (int i = 0; i < n; i++) {
+        if (it[i].key.type != SCHFS_KEY_SNAP)
+            continue;
+        if (it[i].size != sizeof(struct schfs_snap))
+            continue;
+        if ((int)it[i].offset + (int)it[i].size > SCHFS_BLKSIZE)
+            continue;
+        const struct schfs_snap *sn =
+            (const struct schfs_snap *)((const char *)blk + it[i].offset);
+        if (sr->n >= SNAP_ROOTS_MAX) { sr->overflow = 1; continue; }
+        sr->nr[sr->n]  = sn->root;
+        sr->crc[sr->n] = sn->root_crc;
+        sr->n++;
+    }
+}
+
 // Walk the whole tree, marking every block it reaches.
 //
 // Iterative, with one block buffer and a path of block numbers, for the same
@@ -268,8 +321,11 @@ mark_leaf_extents(struct schfs_space *s, const void *blk)
 // the kernel stack is one block in total. Climbing re-reads the parent, so an
 // internal node is read once per child — mount-time cost that the buffer cache
 // largely absorbs, in exchange for bounded memory.
-int
+// Walk one root, marking everything it reaches. Snapshot records encountered
-schfs_space_scan(struct schfs_vol *v)
+// on the way are collected into `sr` when it is non-null.
+static int
+scan_root(struct schfs_vol *v, uint64_t root, uint32_t root_crc,
+          struct snap_roots *sr)
 {
     struct schfs_space *s = &v->space;
     void *blk = v->ctx.a;
@@ -281,10 +337,10 @@ schfs_space_scan(struct schfs_vol *v)
     } path[SCHFS_MAX_LEVEL + 1];
 
     int d = 0;
-    path[0].nr  = v->tree.root;
+    path[0].nr  = root;
-    path[0].crc = v->tree.root_crc;
+    path[0].crc = root_crc;
     path[0].idx = 0;
-    schfs_space_mark(s, v->tree.root, 1);
+    schfs_space_mark(s, root, 1);
 
     for (;;) {
         if (schfs_node_read(&v->dev, path[d].nr, path[d].crc, blk) != 0)
@@ -292,6 +348,8 @@ schfs_space_scan(struct schfs_vol *v)
 
         if (SCHFS_HDR(blk)->level == 0) {
             mark_leaf_extents(s, blk);
+            if (sr)
+                collect_snap_roots(sr, blk);
             d--;
         } else if (path[d].idx < SCHFS_HDR(blk)->nritems) {
             struct schfs_kptr *kp = &SCHFS_KPTRS(blk)[path[d].idx];
@@ -312,3 +370,43 @@ schfs_space_scan(struct schfs_vol *v)
             return 0;
     }
 }
+
+// Walk the live tree, then every snapshot's tree.
+//
+// The snapshots have to be walked or the derivation is actively dangerous: a
+// block reachable only from a snapshot would look free, be handed out, and
+// overwrite the very data the snapshot exists to keep. Nothing would complain
+// at the time -- the corruption surfaces later, when the snapshot is read.
+//
+// The live tree is walked first because that is where the snapshot records
+// live; a snapshot's own tree may contain older snapshot records, which are
+// deliberately not followed. They name roots the live tree no longer keeps,
+// and a snapshot that was deleted should not be resurrected by an older
+// snapshot's memory of it.
+int
+schfs_space_scan(struct schfs_vol *v)
+{
+    struct snap_roots sr;
+    sr.n = 0;
+    sr.overflow = 0;
+
+    int r = scan_root(v, v->tree.root, v->tree.root_crc, &sr);
+    if (r != 0)
+        return r;
+
+    if (sr.n > 0)
+        v->space.flags |= SCHFS_SPACE_RETAIN_ALL;
+
+    for (int i = 0; i < sr.n; i++) {
+        r = scan_root(v, sr.nr[i], sr.crc[i], 0);
+        if (r != 0)
+            return r;
+    }
+
+    // Refusing is the only safe answer. Carrying on would mean deriving a free
+    // map that considers a live snapshot's blocks available.
+    if (sr.overflow)
+        return -2;
+
+    return 0;
+}

tools/schfs_objtest.c

@@ -552,6 +552,106 @@ main(void)
            "the tree survives being filled to the brim");
     }
 
+    /* ---- 8b. snapshots ---- */
+    {
+        // A snapshot is only worth anything if the data it names survives the
+        // live tree changing underneath it. So: write, snapshot, overwrite,
+        // and then read *through the snapshot's root* and expect the old bytes.
+        int r;
+        uint64_t ino = mkfile(VOL.root_objectid, "snapfile");
+        ok(ino != 0, "created a file to snapshot");
+
+        const char before[] = "BEFORE-THE-SNAPSHOT";
+        schfs_file_write(&VOL, ino, 0, before, sizeof before, DATABLK);
+        if (schfs_vol_commit(&VOL) != 0) { printf("  FAIL: commit\n"); failures++; }
+
+        // The snapshot names the committed root, which is the state just
+        // written -- not the root this call produces.
+        r = schfs_snap_create(&VOL, 1, "first", 5);
+        ok(r == 0, "took a snapshot");
+        if (schfs_vol_commit(&VOL) != 0) { printf("  FAIL: commit\n"); failures++; }
+
+        struct schfs_cursor c;
+        schfs_cursor_init(&c, &VOL.tree, CURBLK);
+        struct schfs_snap sn;
+        ok(schfs_snap_get(&VOL, &c, 1, &sn) == 0, "the snapshot record reads back");
+
+        // Change the live tree: overwrite the file completely.
+        const char after[] = "AFTER-THE-SNAPSHOT!";
+        schfs_file_write(&VOL, ino, 0, after, sizeof after, DATABLK);
+        if (schfs_vol_commit(&VOL) != 0) { printf("  FAIL: commit\n"); failures++; }
+
+        char buf[64];
+        memset(buf, 0, sizeof buf);
+        schfs_cursor_init(&c, &VOL.tree, CURBLK);
+        schfs_file_read(&VOL, &c, ino, 0, buf, sizeof after, DATABLK);
+        ok(memcmp(buf, after, sizeof after) == 0,
+           "the live tree shows the new contents");
+
+        // Read through the retained root. Same volume, same block device, a
+        // tree pointed at the old root -- which is all a snapshot is.
+        struct schfs_vol snapvol = VOL;
+        snapvol.tree.root     = sn.root;
+        snapvol.tree.root_crc = sn.root_crc;
+        snapvol.tree.root_gen = sn.root_generation;
+
+        memset(buf, 0, sizeof buf);
+        schfs_cursor_init(&c, &snapvol.tree, CURBLK);
+        long got = schfs_file_read(&snapvol, &c, ino, 0, buf, sizeof before, DATABLK);
+        ok(got == (long)sizeof before && memcmp(buf, before, sizeof before) == 0,
+           "the snapshot still shows the OLD contents");
+        if (memcmp(buf, before, sizeof before) != 0)
+            printf("        (snapshot read back \"%s\")\n", buf);
+
+        // And the blocks it holds must not be considered free, or they get
+        // handed out and the snapshot rots silently.
+        // Exact agreement is not the invariant once a snapshot exists, and the
+        // number is the only thing that drifts. Allocation works from the
+        // in-use bitmap, which the derivation filled by walking the snapshot
+        // too, so a snapshot's blocks are never handed out. The running
+        // counter is not corrected for them, so it and the derivation disagree
+        // until the next mount. Cosmetic, and reported rather than asserted
+        // away.
+        uint64_t claimed = remount();
+        if (claimed != VOL.free_blocks)
+            printf("        (note: counter %llu, derived %llu -- the counter "
+                   "drifts while a snapshot exists)\n",
+                   (unsigned long long)claimed,
+                   (unsigned long long)VOL.free_blocks);
+
+        // Deleting the file from the live tree must not disturb the snapshot.
+        schfs_dir_del(&VOL, VOL.root_objectid, "snapfile", 8);
+        schfs_object_free(&VOL, ino);
+        if (schfs_vol_commit(&VOL) != 0) { printf("  FAIL: commit\n"); failures++; }
+
+        memset(buf, 0, sizeof buf);
+        snapvol = VOL;
+        snapvol.tree.root     = sn.root;
+        snapvol.tree.root_crc = sn.root_crc;
+        snapvol.tree.root_gen = sn.root_generation;
+        schfs_cursor_init(&c, &snapvol.tree, CURBLK);
+        got = schfs_file_read(&snapvol, &c, ino, 0, buf, sizeof before, DATABLK);
+        ok(got == (long)sizeof before && memcmp(buf, before, sizeof before) == 0,
+           "a file deleted from the live tree is still in the snapshot");
+
+        // Drop it again, so what it was holding becomes reclaimable and the
+        // volume goes back to exact accounting for the checks that follow.
+        ok(schfs_snap_delete(&VOL, 1) == 0, "the snapshot can be deleted");
+        if (schfs_vol_commit(&VOL) != 0) { printf("  FAIL: commit\n"); failures++; }
+
+        schfs_cursor_init(&c, &VOL.tree, CURBLK);
+        ok(schfs_snap_get(&VOL, &c, 1, &sn) != 0,
+           "a deleted snapshot is gone");
+
+        // Deleting it makes what it held unreachable, and the derivation at
+        // the next mount is what reclaims it -- there is no refcount to
+        // decrement. So the derived figure must be at least what the stale
+        // counter believed; check 9 below then proves exact agreement is back.
+        claimed = remount();
+        ok(VOL.free_blocks >= claimed,
+           "space the snapshot held is reclaimed at the next mount");
+    }
+
     /* ---- 9. the map and its counter still agree ---- */
     {
         uint64_t claimed = remount();