Document every public function; fix a real gap the audit found

Cross-checked every function declared in include/packfs.h against
nm -D libpackfs.so.0 as the starting point for a full documentation
pass, per the request to document literally everything rather than
just the parts already covered.

That check found a genuine bug, not just a documentation gap:
backend_pack_new was declared in the public header and named in
CLAUDE.md's architecture map, but never implemented in src/pack.c —
any caller would fail at link time. Implemented it as a standalone,
read-only `pack` Backend (every mutating call returns VFS_ERR_PERM,
consistent with concept.md Section 2.1 listing `pack` as its own
backend kind distinct from the overlay), covered it with a new test
case, and verified it under -fsanitize=undefined per CLAUDE.md's
sanitizer rule.

Added a doc comment to every previously-undocumented function and
struct field in packfs.h and internal.h (vfs_open/read/write/close/
stat/readdir/mkdir/unlink/rename, every upper_* structural/content
function, pfs_dir_*, pfs_fnv1a64, PackIndexEntry/Pack fields). Updated
README and CLAUDE.md to mention backend_pack_new and to stop gesturing
at zip/tar as though import/export exists.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqJpkdJ6Njnt1pw3CbghzB

src/pack.c

@@ -302,3 +302,140 @@ int pack_write(const char *path, const PackBuildEntry *in, size_t count, int *er
     if (rename(tmp_path, path) < 0) { unlink(tmp_path); if (err) *err = VFS_ERR_IO; return -1; }
     return 0;
 }
+
+/*
+ * ---- standalone read-only pack Backend (Section 2.1, 3.1) ----
+ *
+ * `backend_overlay_new` is how a pack is normally made writable (Sections
+ * 4-5), but Section 2.1's architecture diagram lists `pack` as its own
+ * backend kind too — "one file, indexed, read-only" — for the case where
+ * no writable upper layer is wanted at all, e.g. mounting a shipped asset
+ * pack somewhere a program never intends to write. This wraps the same
+ * `Pack` load/lookup/range machinery used by the overlay as a plain,
+ * read-only Backend: every mutating operation returns VFS_ERR_PERM rather
+ * than being silently absorbed.
+ */
+
+typedef struct PackFile {
+    const Pack *pack;
+    const PackIndexEntry *entry;
+    pfs_usize pos;
+} PackFile;
+
+static int packbe_open(Backend *b, const char *path, int flags, VfsFile **out) {
+    Pack *p = (Pack *)b->state;
+    if (flags & (VFS_O_WRONLY | VFS_O_RDWR | VFS_O_CREAT | VFS_O_TRUNC)) return VFS_ERR_PERM;
+
+    const PackIndexEntry *e;
+    if (!pack_find(p, path, &e)) return VFS_ERR_NOENT;
+    if (e->mode & PFS_MODE_DIR) return VFS_ERR_ISDIR;
+
+    PackFile *pf = (PackFile *)calloc(1, sizeof(PackFile));
+    pf->pack = p;
+    pf->entry = e;
+    VfsFile *f = (VfsFile *)calloc(1, sizeof(VfsFile));
+    f->backend = b;
+    f->state = pf;
+    *out = f;
+    return VFS_OK;
+}
+
+static pfs_isize packbe_read(VfsFile *f, void *buf, pfs_usize n) {
+    PackFile *pf = (PackFile *)f->state;
+    pfs_usize size = pf->entry->size;
+    pfs_usize avail = pf->pos < size ? size - pf->pos : 0;
+    pfs_usize to_copy = n < avail ? n : avail;
+    if (to_copy) memcpy(buf, (const char *)pack_entry_data(pf->pack, pf->entry) + pf->pos, to_copy);
+    pf->pos += to_copy;
+    return (pfs_isize)to_copy;
+}
+
+static pfs_isize packbe_write(VfsFile *f, const void *buf, pfs_usize n) {
+    (void)f; (void)buf; (void)n;
+    return VFS_ERR_PERM;
+}
+
+static int packbe_close(VfsFile *f) {
+    free(f->state);
+    free(f);
+    return VFS_OK;
+}
+
+static int packbe_stat(Backend *b, const char *path, VfsStat *out) {
+    Pack *p = (Pack *)b->state;
+    const PackIndexEntry *e;
+    if (pack_find(p, path, &e)) {
+        out->size = e->size;
+        out->mtime = e->mtime;
+        out->kind = (e->mode & PFS_MODE_DIR) ? VFS_KIND_DIR : VFS_KIND_FILE;
+        return VFS_OK;
+    }
+    char prefix[PFS_PATH_MAX];
+    if (strcmp(path, "/") == 0) strcpy(prefix, "/"); else snprintf(prefix, sizeof(prefix), "%s/", path);
+    size_t lo, hi;
+    pack_range(p, prefix, &lo, &hi);
+    if (hi > lo || strcmp(path, "/") == 0) {
+        out->size = 0; out->mtime = 0; out->kind = VFS_KIND_DIR;
+        return VFS_OK;
+    }
+    return VFS_ERR_NOENT;
+}
+
+static int packbe_readdir(Backend *b, const char *path, VfsDir *out) {
+    Pack *p = (Pack *)b->state;
+    char prefix[PFS_PATH_MAX];
+    if (strcmp(path, "/") == 0) strcpy(prefix, "/"); else snprintf(prefix, sizeof(prefix), "%s/", path);
+    size_t plen = strlen(prefix);
+
+    size_t lo, hi;
+    pack_range(p, prefix, &lo, &hi);
+    if (lo == hi && strcmp(path, "/") != 0) {
+        const PackIndexEntry *e;
+        if (!pack_find(p, path, &e)) return VFS_ERR_NOENT;
+        if (!(e->mode & PFS_MODE_DIR)) return VFS_ERR_NOTDIR;
+    }
+
+    VfsDirEntry *entries = NULL;
+    pfs_usize count = 0, cap = 0;
+    for (size_t i = lo; i < hi; i++) {
+        const char *name = pack_entry_name(p, &p->entries[i]);
+        const char *restp = name + plen;
+        const char *slash = strchr(restp, '/');
+        size_t clen = slash ? (size_t)(slash - restp) : strlen(restp);
+        if (clen == 0 || clen >= sizeof(entries[0].name)) continue;
+        if (count > 0 && strncmp(entries[count - 1].name, restp, clen) == 0 &&
+            entries[count - 1].name[clen] == '\0') continue; /* sorted -> dup is adjacent */
+        if (count == cap) { cap = cap ? cap * 2 : 8; entries = (VfsDirEntry *)realloc(entries, cap * sizeof(VfsDirEntry)); }
+        memcpy(entries[count].name, restp, clen);
+        entries[count].name[clen] = '\0';
+        entries[count].kind = slash ? VFS_KIND_DIR : ((p->entries[i].mode & PFS_MODE_DIR) ? VFS_KIND_DIR : VFS_KIND_FILE);
+        count++;
+    }
+    out->entries = entries;
+    out->count = count;
+    return VFS_OK;
+}
+
+static int packbe_mkdir(Backend *b, const char *path) { (void)b; (void)path; return VFS_ERR_PERM; }
+static int packbe_unlink(Backend *b, const char *path) { (void)b; (void)path; return VFS_ERR_PERM; }
+static int packbe_rename(Backend *b, const char *from, const char *to) { (void)b; (void)from; (void)to; return VFS_ERR_PERM; }
+static int packbe_sync(Backend *b) { (void)b; return VFS_ERR_PERM; }
+
+static void packbe_free(Backend *b) {
+    pack_close((Pack *)b->state);
+    free(b);
+}
+
+static const BackendOps PACK_OPS = {
+    packbe_open, packbe_read, packbe_write, packbe_close, packbe_stat,
+    packbe_readdir, packbe_mkdir, packbe_unlink, packbe_rename, packbe_sync, packbe_free
+};
+
+Backend *backend_pack_new(const char *pack_path, int *err) {
+    Pack *p;
+    if (pack_load(pack_path, &p, err) < 0) return NULL;
+    Backend *b = (Backend *)calloc(1, sizeof(Backend));
+    b->ops = &PACK_OPS;
+    b->state = p;
+    return b;
+}