@muhkoo/connect 0.11.0-alpha.0 → 0.12.0-alpha.0

package/dist/server/index.js

@@ -3235,7 +3235,7 @@ function base64UrlDecode(s) {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-const VERSION = "0.11.0-alpha.0";
+const VERSION = "0.12.0-alpha.0";
 
 /**
  * `HttpClient` — the one place the unified {@link Client} talks to the
@@ -11655,6 +11655,16 @@ function newId() {
     return toBase64(randomBytes(16)).replace(/[+/=]/g, "").slice(0, 22);
 }
 /** The root key, derived from the master seed. The only key not stored in a parent. */
+/**
+ * The key a project's repository objects are sealed with.
+ *
+ * Per project, not one key for everything: commits, trees and refs describe a
+ * single project's history, and deriving per slug keeps that blast radius small
+ * if a key is ever shared to collaborate on one project.
+ */
+async function deriveRepoKey(seed, slug) {
+    return deriveBitsHkdf(seed, `${VFS_ROOT_INFO}:vcs:${slug}`, AES_KEY_BYTES);
+}
 async function deriveRootKey(seed) {
     return deriveBitsHkdf(seed, VFS_ROOT_INFO, AES_KEY_BYTES);
 }
@@ -11967,9 +11977,18 @@ class VfsNamespace {
                 return;
             if (!frame.key.startsWith("vfs/"))
                 return; // someone else's data on the shared feed
-            // Our own writes echo back. Dropping the cache is cheap and keeping a
-            // stale entry is not, so this does not try to filter them out.
-            this.cache.clear();
+            // Drop only the record that changed.
+            //
+            // Clearing everything looked cheap and is not: our own writes echo
+            // back, so a sync that writes a few hundred files emptied the cache
+            // a few hundred times, and every path resolution in flight went back
+            // to the network for the root and every directory below it. The key
+            // names the record, so there is no need to guess.
+            const id = frame.key.startsWith("vfs/d/") ? frame.key.slice("vfs/d/".length) : null;
+            if (id)
+                this.cache.delete(id);
+            else
+                this.cache.clear(); // a shape we do not recognise: be safe
             handler();
         });
     }
@@ -12017,6 +12036,68 @@ class VfsNamespace {
     async readText(path) {
         return new TextDecoder().decode(await this.readFile(path));
     }
+    /**
+     * A file's manifest — the handle itself, without reading the bytes.
+     *
+     * Version control records manifests rather than content, so a commit costs
+     * a hash and a reference, not a copy.
+     */
+    async statManifest(path) {
+        const entry = await this.expectFile(path);
+        return { manifest: entry.manifest, size: entry.size };
+    }
+    /**
+     * Read content by its manifest, wherever it came from.
+     *
+     * A merge needs the COMMON ANCESTOR's version of a file, which by definition
+     * is not in the working tree any more. The manifest is the whole capability,
+     * so no path lookup is involved.
+     */
+    async readByManifest(manifest) {
+        return this.deps.content.read(manifest);
+    }
+    /**
+     * Pin content that something other than the working tree depends on.
+     *
+     * A commit references a manifest, so it is an OWNER of that content — without
+     * a reference of its own, deleting the file from the working tree would free
+     * shards the history still needs, and checking out an older commit would find
+     * the content gone. (It did, in test.)
+     */
+    async retainManifest(manifest) {
+        await this.deps.content.retain(manifest);
+    }
+    /**
+     * Point a path at content that already exists.
+     *
+     * This is how a checkout restores a file: the bytes are in the shard store
+     * already, so nothing is uploaded or downloaded — only the directory record
+     * changes. Takes a reference, because a second path now depends on those
+     * shards.
+     */
+    async writeManifest(path, manifest, size) {
+        const target = this.resolve(path);
+        const name = basename(target);
+        assertValidName(name);
+        await this.mkdir(dirname(target), { recursive: true });
+        const parent = await this.openDir(dirname(target));
+        const prior = parent.node.entries[name];
+        if (prior?.kind === "dir")
+            throw new VfsConflictError(`${target} is a directory`);
+        await this.deps.content.retain(manifest);
+        const entry = {
+            kind: "file",
+            id: prior?.id ?? newId(),
+            manifest,
+            size,
+            mtime: Date.now(),
+            versions: prior?.versions ?? 0,
+        };
+        await this.mutate(parent, (node) => {
+            node.entries[name] = entry;
+        });
+        return toStat(target, name, entry);
+    }
     // ---- writes -------------------------------------------------------------
     /**
      * Create a directory. `recursive` creates missing parents and tolerates an
@@ -12079,7 +12160,14 @@ class VfsNamespace {
         });
         return toStat(target, name, entry);
     }
-    /** Delete a file, or a directory when `recursive`. */
+    /**
+     * Delete a file, or a directory when `recursive`.
+     *
+     * `keepContent` removes the entry WITHOUT releasing its shards. A checkout
+     * needs that: the file is leaving the working tree, but commits still
+     * reference the same manifest, and releasing would free content history
+     * depends on.
+     */
     async delete(path, opts = {}) {
         const target = this.resolve(path);
         if (target === "/")
@@ -12096,6 +12184,9 @@ class VfsNamespace {
                 throw new VfsConflictError(`${target} is not empty`);
             await this.purge(child);
         }
+        else if (opts.keepContent) {
+            await this.deps.store.delete(historyKey(entry.id)).catch(() => { });
+        }
         else {
             await this.releaseFile(parent, entry);
         }
@@ -12320,25 +12411,41 @@ class VfsNamespace {
         }
         return dir;
     }
-    async openDirById(id, key) {
+    openDirById(id, key) {
         const hit = this.cache.get(id);
         if (hit)
             return hit;
-        const raw = await this.deps.store.get(dirKey(id));
-        // An absent record is an EMPTY directory, not an error: the root exists
-        // before anything has been written to it, and a directory is created by
-        // its parent naming it rather than by its own record appearing.
-        const node = (await unseal(key, raw)) ?? { v: 1, entries: {}, mtime: Date.now() };
-        const open = { id, key, node };
-        this.cache.set(id, open);
-        return open;
+        // The PROMISE goes in the cache, not the resolved value.
+        //
+        // Reading a project means resolving hundreds of paths that share the
+        // same handful of directories. Caching only the settled value leaves
+        // every concurrent reader to miss and fire its own request for the same
+        // record — which is how loading one project turned into thousands of
+        // identical `vfs/d/<id>` fetches, most of them in flight at once.
+        const pending = (async () => {
+            const raw = await this.deps.store.get(dirKey(id));
+            // An absent record is an EMPTY directory, not an error: the root
+            // exists before anything has been written to it, and a directory is
+            // created by its parent naming it rather than by its own record
+            // appearing.
+            const node = (await unseal(key, raw)) ?? { v: 1, entries: {}, mtime: Date.now() };
+            return { id, key, node };
+        })().catch((err) => {
+            // A failed read must not be remembered, or one blip poisons the
+            // directory for the life of the session.
+            if (this.cache.get(id) === pending)
+                this.cache.delete(id);
+            throw err;
+        });
+        this.cache.set(id, pending);
+        return pending;
     }
     /** Apply an edit to a directory record and persist it. */
     async mutate(dir, edit) {
         edit(dir.node);
         dir.node.mtime = Date.now();
         await this.deps.store.put(dirKey(dir.id), await seal(dir.key, dir.node));
-        this.cache.set(dir.id, dir);
+        this.cache.set(dir.id, Promise.resolve(dir));
     }
     async createDir(parentPath, name) {
         assertValidName(name);
@@ -12381,7 +12488,7 @@ class VfsNamespace {
         }
         const open = { id: clone.id, key: fromBase64(clone.key), node };
         await this.deps.store.put(dirKey(open.id), await seal(open.key, node));
-        this.cache.set(open.id, open);
+        this.cache.set(open.id, Promise.resolve(open));
         return clone;
     }
     /**
@@ -12433,6 +12540,812 @@ function byDirsThenName(a, b) {
     return a.name.localeCompare(b.name);
 }
 
+/**
+ * Content addressing for repository objects.
+ *
+ * The hash must depend only on MEANING, never on serialisation accidents — two
+ * clients that build the same tree have to agree on its hash, or history forks
+ * for no reason. So keys are sorted and the encoding is fixed here rather than
+ * left to `JSON.stringify`'s insertion order.
+ */
+/** Canonical JSON: object keys sorted, recursively. */
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}
+/** SHA-256 of an object's canonical form, hex. */
+async function hashObject(value) {
+    const bytes = new TextEncoder().encode(canonical(value));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Three-way line merge.
+ *
+ * Given a common ancestor and two descendants, produce the combined text — or
+ * report the regions where both sides changed the same lines differently.
+ *
+ * The server cannot do any of this: it holds ciphertext and cannot compare
+ * versions, so merging is entirely a client concern and has to be exact here.
+ */
+/**
+ * Longest common subsequence, as a list of matched index pairs.
+ *
+ * Classic dynamic programming. Fine for source files; a file with hundreds of
+ * thousands of lines would want a smarter algorithm, and would also be a strange
+ * thing to merge.
+ */
+function lcs(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const table = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    const pairs = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            pairs.push([i, j]);
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    return pairs;
+}
+/**
+ * Lines of `base` that BOTH sides left untouched.
+ *
+ * These are the anchors the merge is built around: between two consecutive
+ * anchors, each side has some (possibly empty) replacement, and comparing those
+ * replacements is the entire decision.
+ */
+function stableAnchors(base, ours, theirs) {
+    const ourMatch = new Map(lcs(base, ours));
+    const theirMatch = new Map(lcs(base, theirs));
+    const anchors = [];
+    for (let b = 0; b < base.length; b++) {
+        const o = ourMatch.get(b);
+        const t = theirMatch.get(b);
+        if (o !== undefined && t !== undefined)
+            anchors.push([b, o, t]);
+    }
+    return anchors;
+}
+const same = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+/**
+ * Merge `ours` and `theirs` over their common ancestor `base`.
+ *
+ * A region where only one side changed takes that side. A region where both
+ * made the SAME change takes it once — two people fixing the same typo is not a
+ * conflict. Only genuinely divergent edits conflict.
+ */
+function merge3(base, ours, theirs) {
+    const anchors = stableAnchors(base, ours, theirs);
+    const out = [];
+    const conflicts = [];
+    let b = 0;
+    let o = 0;
+    let t = 0;
+    const settle = (ourSlice, theirSlice, baseSlice) => {
+        if (same(ourSlice, theirSlice)) {
+            out.push(...ourSlice); // identical edits, or no edit
+        }
+        else if (same(ourSlice, baseSlice)) {
+            out.push(...theirSlice); // only they changed it
+        }
+        else if (same(theirSlice, baseSlice)) {
+            out.push(...ourSlice); // only we changed it
+        }
+        else {
+            conflicts.push({ line: out.length + 1, ours: ourSlice, theirs: theirSlice });
+            out.push(...ourSlice); // markers are added by the caller
+        }
+    };
+    for (const [ab, ao, at] of anchors) {
+        settle(ours.slice(o, ao), theirs.slice(t, at), base.slice(b, ab));
+        out.push(base[ab]);
+        b = ab + 1;
+        o = ao + 1;
+        t = at + 1;
+    }
+    settle(ours.slice(o), theirs.slice(t), base.slice(b));
+    return { lines: out, conflicts };
+}
+/**
+ * Merge to text, writing conflict markers where the sides diverged.
+ *
+ * Markers rather than a bespoke format: they are what every developer already
+ * knows how to resolve, and resolving becomes ordinary editing.
+ */
+function merge3Text(base, ours, theirs, labels = { ours: "ours", theirs: "theirs" }) {
+    const split = (s) => (s === "" ? [] : s.split("\n"));
+    const anchors = stableAnchors(split(base), split(ours), split(theirs));
+    const B = split(base);
+    const O = split(ours);
+    const T = split(theirs);
+    const out = [];
+    let conflicted = false;
+    let b = 0;
+    let o = 0;
+    let t = 0;
+    const settle = (ourSlice, theirSlice, baseSlice) => {
+        if (same(ourSlice, theirSlice))
+            out.push(...ourSlice);
+        else if (same(ourSlice, baseSlice))
+            out.push(...theirSlice);
+        else if (same(theirSlice, baseSlice))
+            out.push(...ourSlice);
+        else {
+            conflicted = true;
+            out.push(`<<<<<<< ${labels.ours}`, ...ourSlice, "=======", ...theirSlice, `>>>>>>> ${labels.theirs}`);
+        }
+    };
+    for (const [ab, ao, at] of anchors) {
+        settle(O.slice(o, ao), T.slice(t, at), B.slice(b, ab));
+        out.push(B[ab]);
+        b = ab + 1;
+        o = ao + 1;
+        t = at + 1;
+    }
+    settle(O.slice(o), T.slice(t), B.slice(b));
+    return { text: out.join("\n"), conflicted };
+}
+
+/** Storage keys. Namespaced per project so repositories cannot collide. */
+const objectKey = (slug, hash) => `vcs/${slug}/obj/${hash}`;
+const refKey = (slug, name) => `vcs/${slug}/refs/${name}`;
+const headKey = (slug) => `vcs/${slug}/HEAD`;
+const refsIndexKey = (slug) => `vcs/${slug}/refs`;
+/** An in-progress merge: what to make the second parent when it is committed. */
+const mergeKey = (slug) => `vcs/${slug}/MERGE`;
+const DEFAULT_BRANCH = "main";
+class VcsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VcsError";
+    }
+}
+
+/** A project's repository. One per `/apps/<slug>`. */
+/**
+ * Types never worth attempting a three-way merge on.
+ *
+ * NOT application/octet-stream: that is the UNKNOWN case, which is what every
+ * extensionless text file gets labelled, so it must reach the content sniff
+ * rather than being rejected on the label.
+ */
+const BINARY_TYPE = /^(image|audio|video|font)\/|^application\/(wasm|zip|pdf|x-tar|gzip)/;
+/**
+ * Does this look like text a person could resolve conflict markers in?
+ *
+ * A NUL byte is the classic tell and the one git uses — no textual encoding we
+ * care about produces one. Invalid UTF-8 is the other: decoding it would
+ * corrupt the file on write-back even if the merge itself succeeded.
+ */
+function looksTextual(bytes) {
+    if (bytes.includes(0))
+        return false;
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Compare two path → entry maps into a change list. */
+function comparePaths(before, after) {
+    const changes = [];
+    for (const [path, entry] of after) {
+        const was = before.get(path);
+        if (!was)
+            changes.push({ path, kind: "added" });
+        else if (was.manifest.id !== entry.manifest.id)
+            changes.push({ path, kind: "modified" });
+    }
+    for (const path of before.keys())
+        if (!after.has(path))
+            changes.push({ path, kind: "removed" });
+    return changes.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+class Repo {
+    slug;
+    deps;
+    constructor(slug, deps) {
+        this.slug = slug;
+        this.deps = deps;
+    }
+    get root() {
+        return `/apps/${this.slug}`;
+    }
+    // ---- objects ------------------------------------------------------------
+    /** Store an object, returning its hash and whether it was new. */
+    async put(value) {
+        const hash = await hashObject(value);
+        // Content-addressed, so re-writing an identical object is a no-op —
+        // worth skipping because an unchanged directory is written on every
+        // commit that touches any of its siblings.
+        const existing = await this.deps.store.get(objectKey(this.slug, hash));
+        if (existing)
+            return { hash, created: false };
+        await this.deps.store.put(objectKey(this.slug, hash), await seal(await this.deps.key(), value));
+        return { hash, created: true };
+    }
+    async get(hash) {
+        const raw = await this.deps.store.get(objectKey(this.slug, hash));
+        const value = raw ? await unseal(await this.deps.key(), raw) : null;
+        if (!value)
+            throw new VcsError(`object ${hash.slice(0, 8)} is missing from this repository`);
+        return value;
+    }
+    // ---- refs ---------------------------------------------------------------
+    async head() {
+        const raw = await this.deps.store.get(headKey(this.slug));
+        const value = raw ? await unseal(await this.deps.key(), raw) : null;
+        return value ?? { branch: DEFAULT_BRANCH };
+    }
+    async setHead(head) {
+        await this.deps.store.put(headKey(this.slug), await seal(await this.deps.key(), head));
+    }
+    async readRef(name) {
+        const raw = await this.deps.store.get(refKey(this.slug, name));
+        return raw ? await unseal(await this.deps.key(), raw).then((v) => v?.commit ?? null) : null;
+    }
+    async writeRef(name, commit) {
+        await this.deps.store.put(refKey(this.slug, name), await seal(await this.deps.key(), { commit }));
+        // The personal space has no prefix listing, so branches are tracked in
+        // an index. Kept append-only-ish: losing a name here loses the branch.
+        const names = new Set(await this.branches());
+        names.add(name);
+        await this.deps.store.put(refsIndexKey(this.slug), await seal(await this.deps.key(), { names: [...names].sort() }));
+    }
+    /** Every branch name in this repository. */
+    async branches() {
+        const raw = await this.deps.store.get(refsIndexKey(this.slug));
+        const value = raw ? await unseal(await this.deps.key(), raw) : null;
+        return value?.names ?? [];
+    }
+    /** The commit HEAD resolves to, or null in an empty repository. */
+    async current() {
+        const head = await this.head();
+        return "detached" in head ? head.detached : this.readRef(head.branch);
+    }
+    // ---- commit -------------------------------------------------------------
+    /**
+     * Freeze the working tree as a commit.
+     *
+     * Trees are written bottom-up so a directory's hash is known before its
+     * parent references it. Nothing is written to the shard store: file entries
+     * carry the manifest the VFS already holds.
+     */
+    async commit(message, parents) {
+        if (!message.trim())
+            throw new VcsError("a commit needs a message");
+        const tree = await this.writeTree(this.root);
+        const parent = await this.current();
+        // Finish an interrupted merge: the recorded other side becomes the
+        // second parent. Losing this would produce a single-parent commit, and
+        // the merge would look as though it never happened — the branches would
+        // still appear diverged.
+        const pending = parents ? null : await this.pendingMerge();
+        const resolved = parents ?? (pending ? [parent, pending.theirs] : parent ? [parent] : []);
+        if (!parents && !pending && parent) {
+            const previous = await this.get(parent);
+            // An empty commit is almost always a mistake — the user believes
+            // they saved something they did not.
+            if (previous.tree === tree)
+                throw new VcsError("nothing to commit — the project is unchanged");
+        }
+        const commit = {
+            v: 1,
+            tree,
+            parents: resolved,
+            message: message.trim(),
+            author: this.deps.author(),
+            at: Date.now(),
+        };
+        const { hash } = await this.put(commit);
+        await this.advance(hash);
+        if (pending)
+            await this.deps.store.delete(mergeKey(this.slug)).catch(() => { });
+        return hash;
+    }
+    /** Move whatever HEAD points at onto a new commit. */
+    async advance(hash) {
+        const head = await this.head();
+        if ("detached" in head)
+            await this.setHead({ detached: hash });
+        else
+            await this.writeRef(head.branch, hash);
+    }
+    /** The other side of a merge that stopped for conflicts, if any. */
+    async pendingMerge() {
+        const raw = await this.deps.store.get(mergeKey(this.slug));
+        return raw ? await unseal(await this.deps.key(), raw) : null;
+    }
+    /** Write a directory and everything under it, returning the tree's hash. */
+    async writeTree(path) {
+        const entries = {};
+        for (const entry of await this.deps.vfs.list(path)) {
+            if (entry.kind === "dir") {
+                entries[entry.name] = { kind: "tree", hash: await this.writeTree(entry.path) };
+            }
+            else {
+                const stat = await this.deps.vfs.statManifest(entry.path);
+                entries[entry.name] = { kind: "file", manifest: stat.manifest, size: entry.size };
+            }
+        }
+        const { hash, created } = await this.put({ v: 1, entries });
+        // A NEW tree means this directory's contents are newly recorded, so the
+        // repository takes its own reference to their content. Without it, a
+        // later working-tree delete frees shards the commit still needs and the
+        // history becomes unreadable.
+        //
+        // Retaining per new tree rather than per changed FILE slightly
+        // over-retains — an unchanged file in a directory whose sibling changed
+        // gets a second reference. That errs towards keeping content, which is
+        // the correct direction to err in.
+        if (created) {
+            for (const entry of Object.values(entries)) {
+                if (entry.kind === "file")
+                    await this.deps.vfs.retainManifest(entry.manifest);
+            }
+        }
+        return hash;
+    }
+    // ---- history ------------------------------------------------------------
+    /** Commits reachable from HEAD, newest first. */
+    async log(limit = 50) {
+        const start = await this.current();
+        if (!start)
+            return [];
+        const out = [];
+        const seen = new Set();
+        // Breadth-first over parents so a merge's two sides both appear, and
+        // `seen` keeps a diamond from listing the shared history twice.
+        const queue = [start];
+        while (queue.length && out.length < limit) {
+            const hash = queue.shift();
+            if (seen.has(hash))
+                continue;
+            seen.add(hash);
+            const commit = await this.get(hash);
+            out.push({
+                hash,
+                message: commit.message,
+                author: commit.author,
+                at: commit.at,
+                parents: commit.parents,
+            });
+            queue.push(...commit.parents);
+        }
+        return out.sort((a, b) => b.at - a.at);
+    }
+    // ---- diff ---------------------------------------------------------------
+    /**
+     * What changed between two commits.
+     *
+     * Identical subtree hashes prune the walk: an untouched directory is one
+     * comparison regardless of how much is inside it. That is the payoff for
+     * content-addressing the trees.
+     */
+    async diff(fromHash, toHash) {
+        const from = fromHash ? (await this.get(fromHash)).tree : null;
+        const to = (await this.get(toHash)).tree;
+        const changes = [];
+        await this.diffTrees(from, to, "", changes);
+        return changes.sort((a, b) => (a.path < b.path ? -1 : 1));
+    }
+    async diffTrees(fromHash, toHash, prefix, out) {
+        if (fromHash === toHash)
+            return; // identical subtrees: nothing below can differ
+        const from = fromHash ? await this.get(fromHash) : { entries: {} };
+        const to = toHash ? await this.get(toHash) : { entries: {} };
+        for (const name of new Set([...Object.keys(from.entries), ...Object.keys(to.entries)])) {
+            const a = from.entries[name];
+            const b = to.entries[name];
+            const path = `${prefix}/${name}`;
+            if (a && b && a.kind === "tree" && b.kind === "tree") {
+                await this.diffTrees(a.hash, b.hash, path, out);
+            }
+            else if (a?.kind === "tree" || b?.kind === "tree") {
+                // A directory replaced by a file (or the reverse) — recurse both
+                // sides so every affected path is reported, not just the name.
+                await this.diffTrees(a?.kind === "tree" ? a.hash : null, b?.kind === "tree" ? b.hash : null, path, out);
+                if (a?.kind === "file")
+                    out.push({ path, kind: "removed" });
+                if (b?.kind === "file")
+                    out.push({ path, kind: "added" });
+            }
+            else if (!a && b) {
+                out.push({ path, kind: "added" });
+            }
+            else if (a && !b) {
+                out.push({ path, kind: "removed" });
+            }
+            else if (a?.kind === "file" && b?.kind === "file" && a.manifest.id !== b.manifest.id) {
+                out.push({ path, kind: "modified" });
+            }
+        }
+    }
+    // ---- checkout -----------------------------------------------------------
+    /**
+     * Replace the working tree with a commit's.
+     *
+     * Moves no file content: entries carry manifests the shard store already
+     * holds, so this rewrites directory records only.
+     */
+    /**
+     * What has changed since the last commit.
+     *
+     * Compares the WORKING TREE against HEAD without writing any objects: the
+     * common case is answering "anything to commit?", and a `status` that
+     * quietly stored a tree object every time would litter the repository with
+     * trees for states nobody chose to keep.
+     */
+    async status() {
+        const head = await this.current();
+        const before = head ? await this.filesOf(head) : new Map();
+        const after = await this.workingFiles();
+        return comparePaths(before, after);
+    }
+    /** The working tree as a path → entry map, mirroring `filesOf`. */
+    async workingFiles() {
+        const out = new Map();
+        for (const abs of await this.deps.vfs.walk(this.root)) {
+            const stat = await this.deps.vfs.statManifest(abs);
+            out.set(abs.slice(this.root.length), { kind: "file", manifest: stat.manifest, size: stat.size });
+        }
+        return out;
+    }
+    /**
+     * Turn what a person typed into a commit hash.
+     *
+     * Accepts a branch name, `HEAD`, a full or abbreviated hash, and trailing
+     * `^` / `~n` to walk back through parents — so `show abc123^` means "the
+     * commit before that one" the way anyone who has used git expects.
+     */
+    async resolve(rev) {
+        const m = /^(.*?)((?:\^|~\d+)*)$/.exec(rev.trim());
+        if (!m)
+            throw new VcsError(`cannot understand "${rev}"`);
+        const [, base, steps] = m;
+        let hash = null;
+        if (!base || base === "HEAD")
+            hash = await this.current();
+        else if (await this.readRef(base))
+            hash = await this.readRef(base);
+        else
+            hash = await this.expand(base);
+        if (!hash)
+            throw new VcsError(`no commit matches "${rev}"`);
+        for (const step of steps.match(/\^|~\d+/g) ?? []) {
+            const back = step === "^" ? 1 : Number(step.slice(1));
+            for (let i = 0; i < back; i++) {
+                const parents = (await this.get(hash)).parents;
+                if (!parents.length)
+                    throw new VcsError(`"${rev}" reaches past the first commit`);
+                hash = parents[0]; // first parent: the branch you were on
+            }
+        }
+        return hash;
+    }
+    /** A hash prefix a person typed → the one commit it names. */
+    async expand(prefix) {
+        if (!/^[0-9a-f]{4,}$/.test(prefix))
+            return null;
+        const keys = await this.deps.store.list();
+        const wanted = objectKey(this.slug, prefix);
+        const hits = keys.filter((k) => k.startsWith(wanted));
+        // Ambiguous is an error, not a coin toss — acting on the wrong commit
+        // is exactly the kind of mistake version control exists to prevent.
+        if (hits.length > 1)
+            throw new VcsError(`"${prefix}" matches ${hits.length} objects — use more characters`);
+        if (!hits.length)
+            return null;
+        const hash = hits[0].slice(objectKey(this.slug, "").length);
+        // Objects include trees; only a commit is a valid revision.
+        const object = await this.get(hash);
+        return object && "tree" in object ? hash : null;
+    }
+    /**
+     * Put one file back to the way it was in a commit.
+     *
+     * Scoped to a path on purpose — recovering one file you broke should not
+     * mean rewinding everything else you have done since.
+     */
+    async restore(path, rev = "HEAD") {
+        const hash = await this.resolve(rev);
+        const files = await this.filesOf(hash);
+        const key = path.startsWith(this.root) ? path.slice(this.root.length) : path.startsWith("/") ? path : `/${path}`;
+        const entry = files.get(key);
+        if (!entry)
+            throw new VcsError(`${key} is not in ${rev}`);
+        await this.deps.vfs.writeManifest(this.abs(key), entry.manifest, entry.size);
+    }
+    async checkout(commitHash, opts = {}) {
+        await this.guardWorkingTree(opts.discardChanges);
+        await this.materialise(commitHash);
+        // DETACHED on purpose: committing from a historical state must not
+        // silently rewrite whichever branch you happened to be on. `switchTo`
+        // is how you re-attach.
+        await this.setHead({ detached: commitHash });
+    }
+    /** Make the working tree match a commit, leaving HEAD alone. */
+    async materialise(commitHash) {
+        const commit = await this.get(commitHash);
+        const wanted = new Map();
+        await this.collect(commit.tree, "", wanted);
+        // Remove what the commit does not have BEFORE writing what it does —
+        // otherwise a file replaced by a directory of the same name collides.
+        for (const abs of await this.deps.vfs.walk(this.root)) {
+            const path = abs.slice(this.root.length);
+            // keepContent: history still references these manifests.
+            if (!wanted.has(path))
+                await this.deps.vfs.delete(abs, { keepContent: true }).catch(() => { });
+        }
+        for (const [path, entry] of wanted) {
+            await this.deps.vfs.writeManifest(this.abs(path), entry.manifest, entry.size);
+        }
+    }
+    /** Project-relative path → absolute VFS path. */
+    abs(path) {
+        return `${this.root}${path}`;
+    }
+    async collect(treeHash, prefix, out) {
+        const tree = await this.get(treeHash);
+        for (const [name, entry] of Object.entries(tree.entries)) {
+            const path = `${prefix}/${name}`;
+            if (entry.kind === "tree")
+                await this.collect(entry.hash, path, out);
+            else
+                out.set(path, entry);
+        }
+    }
+    // ---- branches -----------------------------------------------------------
+    /** Create a branch at a commit (HEAD by default). Does not switch to it. */
+    async branch(name, at) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._\/-]*$/.test(name))
+            throw new VcsError(`"${name}" is not a usable branch name`);
+        if (await this.readRef(name))
+            throw new VcsError(`branch "${name}" already exists`);
+        const commit = at ?? (await this.current());
+        if (!commit)
+            throw new VcsError("cannot branch an empty repository — commit something first");
+        await this.writeRef(name, commit);
+        return commit;
+    }
+    /**
+     * Move onto a branch, bringing the working tree with it.
+     *
+     * Unlike {@link checkout}, this ATTACHES head: later commits advance the
+     * branch. Checking out a bare commit deliberately does not, so that
+     * committing from a historical state cannot silently rewrite a branch.
+     */
+    async switchTo(name, opts = {}) {
+        const commit = await this.readRef(name);
+        if (!commit)
+            throw new VcsError(`no branch named "${name}"`);
+        await this.guardWorkingTree(opts.discardChanges);
+        await this.materialise(commit);
+        await this.setHead({ branch: name });
+    }
+    /**
+     * Refuse to overwrite work that was never recorded.
+     *
+     * Moving between commits REPLACES the working tree, so uncommitted edits
+     * are gone — and unlike an ordinary overwrite, the person did not ask for
+     * anything to be written. Naming the files is the point: "you have changes"
+     * with no list leaves them guessing what they are about to lose.
+     */
+    async guardWorkingTree(discard) {
+        if (discard)
+            return;
+        const pending = await this.status();
+        if (!pending.length)
+            return;
+        const names = pending.slice(0, 5).map((c) => c.path).join(", ");
+        const more = pending.length > 5 ? `, and ${pending.length - 5} more` : "";
+        throw new VcsError(`${pending.length} uncommitted change(s) would be lost: ${names}${more}. ` +
+            "Commit them first, or pass { discardChanges: true } to throw them away.");
+    }
+    /** The branch HEAD is on, or null when detached. */
+    async currentBranch() {
+        const head = await this.head();
+        return "detached" in head ? null : head.branch;
+    }
+    // ---- merge --------------------------------------------------------------
+    /**
+     * Merge another branch into the current one.
+     *
+     * Every part of this is client-side by necessity: the server holds
+     * ciphertext and cannot compare versions, so base, ours and theirs are all
+     * fetched and decrypted here.
+     */
+    async merge(name, opts = {}) {
+        const theirs = await this.readRef(name);
+        if (!theirs)
+            throw new VcsError(`no branch named "${name}"`);
+        // A merge writes to the working tree as freely as a switch does.
+        await this.guardWorkingTree(opts.discardChanges);
+        const ours = await this.current();
+        if (!ours)
+            throw new VcsError("nothing to merge into — commit something first");
+        if (ours === theirs)
+            return { kind: "up-to-date", conflicts: [] };
+        const base = await this.mergeBase(ours, theirs);
+        if (base === theirs)
+            return { kind: "up-to-date", conflicts: [] };
+        if (base === ours) {
+            // Fast-forward: our history is contained in theirs, so there is
+            // nothing to combine — just move.
+            await this.materialise(theirs);
+            await this.advance(theirs);
+            return { kind: "fast-forward", commit: theirs, conflicts: [] };
+        }
+        const [baseFiles, ourFiles, theirFiles] = await Promise.all([
+            base ? this.filesOf(base) : new Map(),
+            this.filesOf(ours),
+            this.filesOf(theirs),
+        ]);
+        const conflicts = [];
+        for (const path of new Set([...ourFiles.keys(), ...theirFiles.keys(), ...baseFiles.keys()])) {
+            const b = baseFiles.get(path);
+            const o = ourFiles.get(path);
+            const t = theirFiles.get(path);
+            const conflict = await this.settlePath(path, b, o, t);
+            if (conflict)
+                conflicts.push(conflict);
+        }
+        if (conflicts.length) {
+            // Record what to merge with, so finishing is just: fix the files,
+            // then commit. Losing this would silently produce a commit with one
+            // parent, and the merge would appear never to have happened.
+            await this.deps.store.put(mergeKey(this.slug), await seal(await this.deps.key(), { theirs, name }));
+            return { kind: "conflicted", conflicts };
+        }
+        const commit = await this.commit(`Merge ${name}`, [ours, theirs]);
+        return { kind: "merged", commit, conflicts: [] };
+    }
+    /** Decide one path. Returns a conflict when it cannot be settled. */
+    async settlePath(path, b, o, t) {
+        const id = (f) => f?.manifest.id;
+        if (id(o) === id(t))
+            return null; // already agree
+        if (!o && !b && t)
+            return this.take(path, t); // only they added it
+        if (!t && !b && o)
+            return null; // only we added it
+        if (id(o) === id(b)) { // only they touched it
+            if (!t) {
+                await this.deps.vfs.delete(this.abs(path), { keepContent: true }).catch(() => { });
+                return null;
+            }
+            return this.take(path, t);
+        }
+        if (id(t) === id(b))
+            return null; // only we touched it
+        // Both sides moved. A file one side deleted and the other edited is not
+        // a merge decision a tool should make silently.
+        if (!o || !t)
+            return { path, reason: "modify-delete" };
+        // Definitely-binary types are rejected WITHOUT reading them — merging
+        // bytes line-by-line produces corruption, not a result, and these files
+        // are exactly the large ones.
+        if (BINARY_TYPE.test(o.manifest.type ?? "") || BINARY_TYPE.test(t.manifest.type ?? "")) {
+            return { path, reason: "binary" };
+        }
+        const [baseBytes, ourBytes, theirBytes] = await Promise.all([
+            b ? this.deps.vfs.readByManifest(b.manifest) : Promise.resolve(new Uint8Array()),
+            this.deps.vfs.readByManifest(o.manifest),
+            this.deps.vfs.readByManifest(t.manifest),
+        ]);
+        // Then judge by CONTENT, not by the declared type.
+        //
+        // The type is a hint we do not own: a content store may omit it, and
+        // plenty of real text files carry no extension to derive one from
+        // (Makefile, LICENSE, .gitignore, .env). Trusting it alone turned every
+        // one of those into an unmergeable false conflict.
+        if (![ourBytes, theirBytes, baseBytes].every(looksTextual))
+            return { path, reason: "binary" };
+        const decode = (bytes) => new TextDecoder().decode(bytes);
+        const { text, conflicted } = merge3Text(decode(baseBytes), decode(ourBytes), decode(theirBytes));
+        await this.deps.vfs.writeFile(this.abs(path), text);
+        return conflicted ? { path, reason: "content" } : null;
+    }
+    async take(path, entry) {
+        await this.deps.vfs.writeManifest(this.abs(path), entry.manifest, entry.size);
+        return null;
+    }
+    /**
+     * The most recent commit reachable from both.
+     *
+     * Walks our ancestry into a set, then theirs breadth-first until it hits it —
+     * so the first match is the nearest, which is what a three-way merge needs.
+     */
+    async mergeBase(a, b) {
+        const ancestors = new Set();
+        const collect = async (start) => {
+            const queue = [start];
+            while (queue.length) {
+                const hash = queue.shift();
+                if (ancestors.has(hash))
+                    continue;
+                ancestors.add(hash);
+                queue.push(...(await this.get(hash)).parents);
+            }
+        };
+        await collect(a);
+        const queue = [b];
+        const seen = new Set();
+        while (queue.length) {
+            const hash = queue.shift();
+            if (seen.has(hash))
+                continue;
+            seen.add(hash);
+            if (ancestors.has(hash))
+                return hash;
+            queue.push(...(await this.get(hash)).parents);
+        }
+        return null;
+    }
+    /** Every file in a commit, by path. */
+    async filesOf(commitHash) {
+        const commit = await this.get(commitHash);
+        const out = new Map();
+        await this.collect(commit.tree, "", out);
+        return out;
+    }
+}
+/**
+ * Version control over the VFS.
+ *
+ * One repository per project, addressed by slug — the same slug the VFS stores
+ * that project's working tree under. `client.vcs.open("my-app")` is the whole
+ * entry point.
+ */
+class VcsNamespace {
+    deps;
+    repos = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The repository for one project. Cheap and cached; creates nothing. */
+    open(slug) {
+        let repo = this.repos.get(slug);
+        if (!repo) {
+            repo = new Repo(slug, {
+                vfs: this.deps.vfs,
+                store: this.deps.store,
+                key: async () => {
+                    const seed = this.deps.seed();
+                    if (!seed)
+                        throw new VcsError("client.vcs: no session — sign in first.");
+                    return deriveRepoKey(seed, slug);
+                },
+                author: this.deps.author,
+            });
+            this.repos.set(slug, repo);
+        }
+        return repo;
+    }
+}
+
 /**
  * `ChatKeyVault` — SDK-owned lifecycle for a member's long-lived ratchet/space
  * keypair (the connect `KeyStore` entry keyed by the member id / username).
@@ -13676,6 +14589,8 @@ class Client {
     storage;
     /** Filesystem over the personal space: directories, versions, real paths. */
     vfs;
+    /** Version control over the VFS: commits, branches, merges — per project. */
+    vcs;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     message;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
@@ -13863,6 +14778,15 @@ class Client {
                 },
             },
         });
+        // Sealed into the SAME personal store as the VFS metadata, so a project
+        // and its history live or die together — there is no way to end up with
+        // commits whose working tree is gone, or the reverse.
+        this.vcs = new VcsNamespace({
+            vfs: this.vfs,
+            store: personalStore,
+            seed: () => this.session.seed,
+            author: () => this.session.commitment ?? "unknown",
+        });
         // Group keys are cached in the user's PersonalSpace (encrypted at rest
         // by client.kv), so a returning member hydrates without a fresh keyring
         // round-trip. The server only ever sees ciphertext.
@@ -14801,5 +15725,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
     default: loadRsWasm
 });
 
-export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES$1 as AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_BASE_URL, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, DevicePairingError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReauthRequiredError, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VaultUnavailableError, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes, configureDeviceStore, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$2 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, loadDeviceIdentity, log, manifestToStat, materializeRow, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$2 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
+export { ACCESS_TOKEN_SCOPES, AES_GCM_IV_BYTES$1 as AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AccessTokensNamespace, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BlockEngine, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, ConnectivityManager, DEFAULT_BASE_URL, DEFAULT_BRANCH, DEFAULT_FN_HOST_SUFFIX, DEVICE_IDENTITY_STORAGE_KEY, DEVICE_KEY_DB_NAME, DbCache, DbNamespace, DbTable, DevicePairingError, DeviceStoreUnavailableError, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HLC, HashKnowledge, HostedAuth, HttpClient, HttpError, IndexedDbStore, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvCache, KvNamespace, LocalEngineHost, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, NoopStore, OfflineLockedError, OfflineManager, OutboundQueue, P2P_SUBJECT, PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PasskeyOriginError, PeerExchange, PeerNetwork, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReauthRequiredError, ReedSolomonCodec, Repo, Retry, Space as Room, SerializeMessage, SessionState, ShardCache, ShardClient, SharedSpaceClient, SnapshotNamespace, Space, SpaceCache, SpaceKeyring, SpaceNamespace, SpacePacketCipher, SpaceSignaler, StorageNamespace, SyncEngine, VERSION, VaultUnavailableError, VcsError, VcsNamespace, VfsLockedError, VfsNamespace, WSTransport, WebRtcTransport, WorkerEngineHost, ZERO_HLC, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, canonicalUserCode, clearDeviceIdentity, compareHlc, compilePrograms, concatBytes, configureDeviceStore, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deleteBeatsWrite, deleteRegister, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deriveIdentityFromSeed, deriveMasterSeedFromPassword, deserialize, deviceFingerprint, deviceIdentityIsEphemeral, deviceIdentityKey, ejectAgentPrompt, ejectAgentTools, emptyMap, emptyRegister, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, formatUserCode, fromBase64$2 as fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateDevicePairingKeypair, generateId, generatePkce, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, hasDeviceIdentity, initBn128Wasm, initRsWasm, initializeCircuits, isNewer, isNumber, isOfflineCapable, isP2pCapable, isProvisional, loadDeviceIdentity, log, manifestToStat, materializeRow, merge3, merge3Text, mergeMap, mergeMessage, mergeRegister, messageKey, pack, padHandle, pairingVerificationCode, passkeyUsableFromOrigin, persistDeviceIdentity, poseidonHash, protocol, provisionalHandle, quickVerify, randomBytes, randomState, rpIdUsableForOrigin, sealSeed, sealSeedToDevice, serialize, shardHash, signMessage, stableStringify, toBase64$2 as toBase64, toBase64Url, toField, toHex, tombstoneRow, unpack, unsealSeed, unsealSeedFromDevice, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase, writeBeatsTombstone, writeColumns, writeRegister };
 //# sourceMappingURL=index.js.map