agentic-drive 0.0.0-stage → 0.2.0

package/dist/chunk-6CWBHSJ7.js

@@ -0,0 +1,1351 @@
+// src/drive.ts
+import { MAX_FOLDER_DEPTH } from "agentic-identity";
+var ROOT_ID = "root";
+var NODES = "drive_nodes";
+var NAMES = "drive_names";
+var ACTOR_KINDS = ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
+var DriveError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DriveError";
+  }
+  code;
+};
+var MAX_PATH_SEGMENTS = 64;
+var DEFAULT_MAX_DEPTH = 256;
+var CHUNK = 25;
+var SHARED_CHUNK = 10;
+var HEIGHT_BUDGET = 200;
+var DEFAULT_URL_SECONDS = 900;
+var MAX_URL_SECONDS = 3600;
+var OPAQUE = "application/octet-stream";
+var MIME_SHAPE = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,63}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,63}$/;
+var ACTIVE_TYPES = /* @__PURE__ */ new Set([
+  "text/html",
+  "application/xhtml+xml",
+  "image/svg+xml",
+  "text/xml",
+  "application/xml",
+  "text/javascript",
+  "application/javascript",
+  "application/x-javascript",
+  "text/ecmascript",
+  "application/ecmascript",
+  "text/css"
+]);
+function safeMime(claimed) {
+  const type = (claimed ?? "").trim().toLowerCase();
+  return MIME_SHAPE.test(type) && !ACTIVE_TYPES.has(type) ? type : OPAQUE;
+}
+async function sha256Hex(data) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", data);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var REF = /^[a-z][a-z0-9_-]*:[^\s/]+$/;
+function parseName(raw) {
+  const name = raw.normalize("NFC");
+  if (name.trim() === "" || /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/.test(name) || name === "." || name === ".." || /[/\u0000-\u001f\u007f]/.test(name) || new TextEncoder().encode(name).length > 255) {
+    throw new DriveError("INVALID_NAME", `invalid name ${JSON.stringify(raw)}`);
+  }
+  return { name, key: name.toLowerCase() };
+}
+function splitPath(path) {
+  if (!path.startsWith("/")) throw new DriveError("INVALID_PATH", `path must start with "/": ${path}`);
+  const rest = path.replace(/\/$/, "").slice(1);
+  if (rest === "") return [];
+  const parts = rest.split("/");
+  if (parts.includes("")) throw new DriveError("INVALID_PATH", `empty segment in path: ${path}`);
+  if (parts.length > MAX_PATH_SEGMENTS) throw new DriveError("TOO_DEEP", `a path has at most ${MAX_PATH_SEGMENTS} segments`);
+  return parts.map(parseName);
+}
+function batch() {
+  const writes = [];
+  const fresh = /* @__PURE__ */ new Set();
+  const depths = /* @__PURE__ */ new Map();
+  return {
+    fresh,
+    depths,
+    put: (collection, id, doc) => void writes.push({ collection, id, doc }),
+    remove: (collection, id) => void writes.push({ collection, id, doc: null }),
+    async apply(ops) {
+      for (const w of writes) await (w.doc ? ops.put(w.collection, w.id, w.doc) : ops.delete(w.collection, w.id));
+    }
+  };
+}
+var claimId = (owner, parentId, key) => sha256Hex(new TextEncoder().encode(`${owner}\0${parentId}\0${key}`));
+var rootResource = async (owner) => `drive-root-${(await sha256Hex(new TextEncoder().encode(owner))).slice(0, 32)}`;
+var ACTION_TO_IDENTITY = { read: "read", write: "write", delete: "admin" };
+var MAX_ITEM_DEPTH = MAX_FOLDER_DEPTH - 1;
+var VISITOR = { id: "", kind: "human" };
+var appOf = (node) => node.kind === "ref" && node.ref ? node.ref.split(":")[0] : null;
+var ERASED = "erased";
+var SHARE_ERROR = /^(invalid|give an|expiresAt|expiresInMs|resource exists|the last owner)/;
+function createDrive(deps) {
+  const { store, blobs } = deps;
+  const now = deps.now ?? Date.now;
+  const newId = deps.newId ?? (() => globalThis.crypto.randomUUID());
+  const maxDepth = deps.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const onOrphan = deps.onOrphan ?? ((key, error) => console.error(`orphan blob ${key}: ${error instanceof Error ? error.name : "delete failed"}`));
+  const sharing = deps.sharing;
+  const resourceOf = async (node) => node.id === ROOT_ID ? rootResource(node.owner) : node.id;
+  const can = deps.can ?? (sharing ? async (ctx, action, node) => ctx.principal !== void 0 && (await sharing.can(ctx.principal, ACTION_TO_IDENTITY[action], await resourceOf(node))).allowed : (ctx, _action, node) => node.owner === ctx.owner);
+  const rootNode = (owner, by) => ({
+    id: ROOT_ID,
+    owner,
+    parentId: "",
+    kind: "folder",
+    name: "",
+    nameKey: "",
+    size: 0,
+    mime: null,
+    hash: null,
+    ref: null,
+    blobKey: null,
+    createdAt: 0,
+    updatedAt: 0,
+    createdBy: by,
+    updatedBy: by,
+    createdById: by.id,
+    updatedById: by.id,
+    trashed: false,
+    trashedAt: null,
+    purging: false
+  });
+  const who = (ctx) => ({ id: ctx.actor.id, kind: ctx.actor.kind });
+  const stamp = (ctx, node) => ({ createdById: node.createdById ?? node.createdBy.id, updatedBy: who(ctx), updatedById: ctx.actor.id });
+  const resourceDoc = async (node, parent) => ({ id: node.id, type: "drive", parentId: await resourceOf(parent) });
+  async function rawNode(ops, id, owner, by, withMarked = false) {
+    const node = id === ROOT_ID ? rootNode(owner, by) : await ops.get(NODES, id);
+    return node && (withMarked || node.purging !== true) ? node : null;
+  }
+  async function fetch(ops, ctx, id, purgeAgain = false) {
+    const node = await rawNode(ops, id, ctx.owner, ctx.actor, purgeAgain);
+    return node && await can(ctx, "read", node) ? node : null;
+  }
+  async function need(ctx, action, node) {
+    if (!await can(ctx, action, node)) throw new DriveError("FORBIDDEN", `not allowed to ${action} ${node.id}`);
+  }
+  async function children(ops, owner, parentId, extra = {}) {
+    const out = [];
+    for (let cursor; ; ) {
+      const page = await ops.query(NODES, { where: { owner, parentId, ...extra }, limit: 100, cursor });
+      out.push(...page.items.map((item) => item.data));
+      if (!page.nextCursor) return out;
+      cursor = page.nextCursor;
+    }
+  }
+  async function claimed(ops, owner, parentId, key) {
+    const claim = await ops.get(NAMES, await claimId(owner, parentId, key));
+    const found = claim ? await ops.get(NODES, claim.nodeId) : null;
+    const node = found && !found.trashed && found.purging !== true && found.parentId === parentId && found.nameKey === key ? found : null;
+    return { taken: claim !== null, node };
+  }
+  const liveChild = async (ops, folder, key) => (await claimed(ops, folder.owner, folder.id, key)).node;
+  async function isLive(ops, ctx, node) {
+    for (let n = node, depth = 0; n && depth < maxDepth; depth++) {
+      if (n.trashed) return false;
+      if (n.id === ROOT_ID) return true;
+      n = await rawNode(ops, n.parentId, n.owner, ctx.actor);
+    }
+    return false;
+  }
+  async function depthOf(ops, w, node) {
+    let depth = 0;
+    for (let n = node; n && n.id !== ROOT_ID; ) {
+      const known = w.depths.get(n.id);
+      if (known !== void 0) return depth + known;
+      if (++depth > MAX_ITEM_DEPTH) return depth;
+      n = await rawNode(ops, n.parentId, n.owner, node.createdBy);
+      if (n === null) return MAX_ITEM_DEPTH + 1;
+    }
+    return depth;
+  }
+  async function heightOf(ops, folder) {
+    let level = [folder];
+    let queries = 0;
+    for (let height = 1; height <= MAX_ITEM_DEPTH; height++) {
+      const next = [];
+      for (const f of level) {
+        for (let cursor; ; ) {
+          if (++queries > HEIGHT_BUDGET) throw new DriveError("TOO_MANY_ITEMS", `${folder.name} has too many folders to count. Move its parts one by one.`);
+          const page = await ops.query(NODES, { where: { owner: f.owner, parentId: f.id, kind: "folder" }, limit: 100, cursor });
+          next.push(...page.items.map((item) => item.data));
+          if (!page.nextCursor) break;
+          cursor = page.nextCursor;
+        }
+      }
+      if (next.length === 0) return height;
+      level = next;
+    }
+    return MAX_ITEM_DEPTH + 1;
+  }
+  async function heightFor(ctx, node, dest) {
+    if (!sharing || node.kind !== "folder") return 0;
+    const target = typeof dest === "string" ? await resolve(store, ctx, dest) : dest;
+    if (target.id === node.parentId) return 0;
+    const w = batch();
+    if (await depthOf(store, w, target) + 1 <= await depthOf(store, w, node)) return 0;
+    return heightOf(store, node);
+  }
+  async function noClimb(ctx, node, dest) {
+    const person = ctx.principal ? { ...ctx, principal: { ...ctx.principal, scopes: ["drive:admin"] } } : ctx;
+    if (await can(person, "delete", dest) && !await can(person, "delete", node)) {
+      throw new DriveError("FORBIDDEN", "moving into a folder you own needs owner on the item");
+    }
+  }
+  async function fitsUnder(ops, w, dest, height) {
+    if (sharing && await depthOf(ops, w, dest) + 1 + height > MAX_ITEM_DEPTH) {
+      throw new DriveError("TOO_DEEP", `an item can sit at most ${MAX_ITEM_DEPTH} folders deep`);
+    }
+  }
+  async function startOf(ops, ctx, loc) {
+    if (loc.startsWith("/")) {
+      const start = rootNode(ctx.owner, ctx.actor);
+      if (!await can(ctx, "read", start)) throw new DriveError("NOT_FOUND", `no item ${loc}`);
+      return { start, segs: splitPath(loc) };
+    }
+    const slash = loc.indexOf("/");
+    const base = await resolve(ops, ctx, loc.slice(0, slash));
+    if (base.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${base.name} is not a folder`);
+    return { start: base, segs: splitPath(`/${loc.slice(slash + 1)}`) };
+  }
+  async function resolve(ops, ctx, loc) {
+    if (!loc.includes("/")) {
+      const node2 = await fetch(ops, ctx, loc);
+      if (!node2) throw new DriveError("NOT_FOUND", `no item ${loc}`);
+      if (!await isLive(ops, ctx, node2)) throw new DriveError("TRASHED", `${loc} is in the trash`);
+      return node2;
+    }
+    const { start, segs } = await startOf(ops, ctx, loc);
+    let node = start;
+    for (const seg of segs) {
+      if (node.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${node.name} is not a folder`);
+      const next = await liveChild(ops, node, seg.key);
+      if (!next) throw new DriveError("NOT_FOUND", `no item ${loc}`);
+      node = next;
+    }
+    if (!await can(ctx, "read", node)) throw new DriveError("NOT_FOUND", `no item ${loc}`);
+    return node;
+  }
+  async function freeName(ops, owner, parentId, name) {
+    const dot = name.lastIndexOf(".");
+    const [base, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ""];
+    for (let n = 2; ; n++) {
+      const candidate = `${base} (${n})${ext}`;
+      if (!(await claimed(ops, owner, parentId, parseName(candidate).key)).taken) return candidate;
+    }
+  }
+  async function folderAt(ops, w, ctx, start, segs, create) {
+    let node = start;
+    for (const seg of segs) {
+      if (node.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${node.name} is not a folder`);
+      let next = w.fresh.has(node.id) ? null : await liveChild(ops, node, seg.key);
+      if (!next) {
+        if (!create) throw new DriveError("NOT_FOUND", `no folder ${seg.name}`);
+        next = (await insert(ops, w, ctx, node, seg.name, { kind: "folder" }, "fail")).node;
+        w.fresh.add(next.id);
+      }
+      node = next;
+    }
+    if (node.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${node.name} is not a folder`);
+    return node;
+  }
+  async function insert(ops, w, ctx, parent, rawName, fields, onConflict) {
+    let { name, key } = parseName(rawName);
+    const empty = w.fresh.has(parent.id);
+    if (!empty) await need(ctx, "write", parent);
+    const slot = empty ? null : await claimed(ops, parent.owner, parent.id, key);
+    if (slot?.taken) {
+      if (onConflict === "replace" && slot.node?.kind === "file" && fields.kind === "file") {
+        const node2 = { ...slot.node, ...fields, updatedAt: now(), ...stamp(ctx, slot.node) };
+        w.put(NODES, node2.id, node2);
+        return { node: node2, replacedBlob: slot.node.blobKey };
+      }
+      if (onConflict !== "rename") throw new DriveError("NAME_TAKEN", `"${name}" already exists`);
+      name = await freeName(ops, parent.owner, parent.id, name);
+      key = parseName(name).key;
+    }
+    const id = newId();
+    if (sharing) {
+      const depth = await depthOf(ops, w, parent) + 1;
+      if (depth > MAX_ITEM_DEPTH) throw new DriveError("TOO_DEEP", `an item can sit at most ${MAX_ITEM_DEPTH} folders deep`);
+      w.depths.set(id, depth);
+    }
+    const t = now();
+    const node = {
+      id,
+      owner: parent.owner,
+      parentId: parent.id,
+      kind: "file",
+      name,
+      nameKey: key,
+      size: 0,
+      mime: null,
+      hash: null,
+      ref: null,
+      blobKey: null,
+      createdAt: t,
+      updatedAt: t,
+      createdBy: who(ctx),
+      updatedBy: who(ctx),
+      createdById: ctx.actor.id,
+      updatedById: ctx.actor.id,
+      trashed: false,
+      trashedAt: null,
+      purging: false,
+      ...fields
+    };
+    w.put(NODES, node.id, node);
+    w.put(NAMES, await claimId(parent.owner, parent.id, key), { nodeId: node.id, owner: parent.owner, parentId: parent.id });
+    if (sharing) w.put("resources", node.id, await resourceDoc(node, parent));
+    return { node, replacedBlob: null };
+  }
+  async function parentAndName(ops, w, ctx, path, parents) {
+    const { start, segs } = await startOf(ops, ctx, path);
+    const last = segs.pop();
+    if (!last) throw start.id === ROOT_ID ? new DriveError("IS_ROOT", "the root already exists") : new DriveError("INVALID_PATH", "name an item inside the folder");
+    return { parent: await folderAt(ops, w, ctx, start, segs, parents), name: last.name };
+  }
+  async function relocate(ops, w, ctx, node, destLoc, opts) {
+    if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot change the root");
+    const dest = typeof destLoc === "string" ? await resolve(ops, ctx, destLoc) : destLoc;
+    if (dest.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${dest.name} is not a folder`);
+    if (dest.owner !== node.owner) throw new DriveError("CROSS_DRIVE", "an item cannot move into another person's drive");
+    for (let n = dest, depth = 0; n.id !== ROOT_ID; depth++) {
+      if (n.id === node.id) throw new DriveError("MOVE_INTO_SELF", `cannot move ${node.name} into itself`);
+      if (depth >= maxDepth) throw new DriveError("TOO_DEEP", `the destination is deeper than ${maxDepth} folders`);
+      const parent = await rawNode(ops, n.parentId, n.owner, ctx.actor);
+      if (!parent) throw new DriveError("NOT_FOUND", `a parent folder of ${dest.name} is missing`);
+      n = parent;
+    }
+    await need(ctx, "write", node);
+    if (dest.id !== node.parentId) {
+      await need(ctx, "write", dest);
+      await noClimb(ctx, node, dest);
+      await fitsUnder(ops, w, dest, opts.height ?? 0);
+    }
+    let { name, key } = parseName(opts.name ?? node.name);
+    const slot = await claimed(ops, dest.owner, dest.id, key);
+    if (slot.taken && slot.node?.id !== node.id) {
+      if (opts.onConflict !== "rename") throw new DriveError("NAME_TAKEN", `"${name}" already exists`);
+      name = await freeName(ops, dest.owner, dest.id, name);
+      key = parseName(name).key;
+    }
+    const moved = { ...node, parentId: dest.id, name, nameKey: key, updatedAt: now(), ...stamp(ctx, node) };
+    w.put(NODES, moved.id, moved);
+    const [from, to] = [await claimId(node.owner, node.parentId, node.nameKey), await claimId(dest.owner, dest.id, key)];
+    if (from !== to) {
+      if ((await ops.get(NAMES, from))?.nodeId === node.id) w.remove(NAMES, from);
+      w.put(NAMES, to, { nodeId: moved.id, owner: dest.owner, parentId: dest.id });
+    }
+    if (sharing && dest.id !== node.parentId) w.put("resources", moved.id, await resourceDoc(moved, dest));
+    return moved;
+  }
+  async function isUnreferenced(blobKey) {
+    try {
+      return (await store.query(NODES, { where: { blobKey }, limit: 1 })).items.length === 0;
+    } catch (error) {
+      onOrphan(blobKey, error);
+      return false;
+    }
+  }
+  async function dropBlob(key) {
+    try {
+      await blobs.delete(key);
+    } catch (error) {
+      onOrphan(key, error);
+    }
+  }
+  async function rawOwnerNodes(owner, withMarked) {
+    const out = [];
+    for (let cursor; ; ) {
+      const page = await store.query(NODES, { where: { owner }, limit: 100, cursor });
+      out.push(...page.items.map((item) => item.data).filter((node) => withMarked || node.purging !== true));
+      if (!page.nextCursor) return out;
+      cursor = page.nextCursor;
+    }
+  }
+  async function ownerNodes(ctx, withMarked = false) {
+    if (!await can(ctx, "read", rootNode(ctx.owner, ctx.actor))) throw new DriveError("FORBIDDEN", "not allowed to read this drive");
+    return rawOwnerNodes(ctx.owner, withMarked);
+  }
+  function pathIn(byId, node, liveOnly) {
+    const names = [];
+    for (let n = node, depth = 0; depth < 1e3; depth++) {
+      if (!n) return liveOnly ? null : `/(orphan)/${names.reverse().join("/")}`;
+      if (liveOnly && n.trashed) return null;
+      names.push(n.name);
+      if (n.parentId === ROOT_ID) return `/${names.reverse().join("/")}`;
+      n = byId.get(n.parentId);
+    }
+    return null;
+  }
+  async function transact(fn) {
+    try {
+      return await store.transaction(fn);
+    } catch (error) {
+      if (error instanceof Error && /transaction kept conflicting/.test(error.message)) throw new DriveError("BUSY", "the drive changed at the same time. Try again.");
+      throw error;
+    }
+  }
+  function assertInPerson(ctx, what) {
+    if (!isInPerson(ctx) || ctx.actor.kind !== "human") throw new DriveError("FORBIDDEN", `only the owner in person can ${what}`);
+  }
+  const subjectOf = (ctx) => ({ id: ctx.owner, kind: ctx.principal?.chain[0]?.kind ?? (isInPerson(ctx) ? ctx.actor.kind : null) });
+  async function allWhere(ops, collection, where, orderBy) {
+    const out = [];
+    for (let cursor; ; ) {
+      const page = await ops.query(collection, { where, ...orderBy ? { orderBy } : {}, limit: 100, cursor });
+      out.push(...page.items);
+      if (!page.nextCursor) return out;
+      cursor = page.nextCursor;
+    }
+  }
+  const isInPerson = (ctx) => ctx.principal === void 0 ? ctx.actor.kind === "human" && ctx.actor.id === ctx.owner : ctx.principal.kind === "human" && ctx.principal.chain.length === 1 && ctx.actor.id === ctx.owner;
+  const MAX_ACTORS = 1e3;
+  async function actorsOf(ops, id) {
+    const ownedAgents = (await allWhere(ops, "principals", { ownerId: id })).map((p) => p.id);
+    const actors = [id, ...ownedAgents];
+    for (let depth = 0, from = 0; from < actors.length && depth < 8; depth++) {
+      const next = actors.length;
+      for (; from < next; from++) for (const child of await allWhere(ops, "principals", { parentId: actors[from] })) if (!actors.includes(child.id)) actors.push(child.id);
+      if (actors.length > MAX_ACTORS) throw new DriveError("TOO_MANY_ITEMS", `a person can have at most ${MAX_ACTORS} agents here`);
+    }
+    return { actors, ownedAgents };
+  }
+  async function madeBy(ops, actors) {
+    const made = /* @__PURE__ */ new Map();
+    for (const actor of actors) for (const field of ["createdById", "updatedById"]) for (const { data } of await allWhere(ops, NODES, { [field]: actor })) made.set(data.id, data);
+    return [...made.values()];
+  }
+  async function eraseDrive(owner) {
+    let removed = 0;
+    for (let pass = 0; pass < 5; pass++) {
+      const all = await rawOwnerNodes(owner, true);
+      if (all.length === 0) {
+        const rootId = await rootResource(owner);
+        await transact(async (tx) => {
+          const shares = sharing ? await sharesOf(tx, rootId) : [];
+          for (const share of shares) await tx.delete(share.collection, share.id);
+          if (sharing) await tx.delete("resources", rootId);
+        });
+        return removed;
+      }
+      removed += await removeNodes(all);
+    }
+    throw new DriveError("BUSY", "the drive kept changing while it was deleted. Run it again.");
+  }
+  async function sharesOf(ops, resourceId) {
+    const out = [];
+    for (const collection of ["grants", "links", "invites"]) {
+      for (let cursor; ; ) {
+        const page = await ops.query(collection, { where: { resourceId }, limit: 100, cursor });
+        out.push(...page.items.map((item) => ({ collection, id: item.id })));
+        if (!page.nextCursor) break;
+        cursor = page.nextCursor;
+      }
+    }
+    return out;
+  }
+  async function removeNodes(nodes, top) {
+    const unchanged = (now2, seen) => now2 !== null && now2.trashed === seen.trashed && now2.parentId === seen.parentId && now2.updatedAt === seen.updatedAt;
+    const size = sharing ? SHARED_CHUNK : CHUNK;
+    const marked = [];
+    const markedIds = /* @__PURE__ */ new Set();
+    for (let i = 0; i < nodes.length; i += size) {
+      const slice = nodes.slice(i, i + size);
+      for (const node of slice) {
+        if (node.purging === true) {
+          marked.push(node);
+          markedIds.add(node.id);
+        }
+      }
+      const found = await transact(async (tx) => {
+        const out = [];
+        const ids = new Set(markedIds);
+        for (const node of slice) {
+          if (node.purging === true) continue;
+          if (top && node.id !== top.id && !ids.has(node.parentId)) continue;
+          const current = await tx.get(NODES, node.id);
+          if (unchanged(current, node)) {
+            out.push(current);
+            ids.add(node.id);
+          }
+        }
+        for (const node of out) await tx.put(NODES, node.id, { ...node, purging: true });
+        return out;
+      });
+      for (const node of found) {
+        marked.push(node);
+        markedIds.add(node.id);
+      }
+      if (top && i === 0 && !markedIds.has(top.id)) throw new DriveError("BUSY", `${top.name} changed during the purge. Nothing was deleted.`);
+    }
+    const rows = marked.reverse();
+    for (let i = 0; i < rows.length; i += size) {
+      const chunk = rows.slice(i, i + size);
+      for (const node of chunk) if (node.blobKey) await blobs.delete(node.blobKey);
+      await transact(async (tx) => {
+        const held = [];
+        for (const node of chunk) {
+          const claim = node.trashed ? null : await claimId(node.owner, node.parentId, node.nameKey);
+          const shares = sharing ? await sharesOf(tx, node.id) : [];
+          held.push({ node, claim, owns: claim !== null && (await tx.get(NAMES, claim))?.nodeId === node.id, shares });
+        }
+        for (const { node, claim, owns, shares } of held) {
+          await tx.delete(NODES, node.id);
+          if (claim && owns) await tx.delete(NAMES, claim);
+          if (sharing) await tx.delete("resources", node.id);
+          for (const share of shares) await tx.delete(share.collection, share.id);
+        }
+      });
+    }
+    return marked.length;
+  }
+  async function openShared(principal, id, linkToken) {
+    if (!sharing) throw new DriveError("INVALID_SHARE", "sharing is not set up");
+    const node = await rawNode(store, id, "", VISITOR);
+    if (!node || node.id === ROOT_ID) throw new DriveError("NOT_FOUND", `no item ${id}`);
+    const decision = await sharing.can(principal, "read", id, linkToken === void 0 ? {} : { linkToken });
+    if (!decision.allowed) throw new DriveError("NOT_FOUND", `no item ${id}`);
+    if (!await isLive(store, { owner: node.owner, actor: node.createdBy }, node)) throw new DriveError("TRASHED", `${id} is in the trash`);
+    return node;
+  }
+  const api = {
+    async stat(ctx, loc) {
+      return resolve(store, ctx, loc);
+    },
+    /** Live children, sorted by name. */
+    async list(ctx, loc = "/") {
+      const folder = await resolve(store, ctx, loc);
+      if (folder.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${folder.name} is not a folder`);
+      return (await children(store, folder.owner, folder.id)).filter((n) => !n.trashed && n.purging !== true).sort((a, b) => a.nameKey < b.nameKey ? -1 : a.nameKey > b.nameKey ? 1 : a.name < b.name ? -1 : 1);
+    },
+    async mkdir(ctx, path, opts = {}) {
+      return transact(async (tx) => {
+        const w = batch();
+        const { parent, name } = await parentAndName(tx, w, ctx, path, opts.parents ?? false);
+        const existing = w.fresh.has(parent.id) ? null : await liveChild(tx, parent, parseName(name).key);
+        if (opts.parents && existing?.kind === "folder") {
+          if (!await can(ctx, "read", existing)) throw new DriveError("NOT_FOUND", `no item ${path}`);
+          return existing;
+        }
+        const { node } = await insert(tx, w, ctx, parent, name, { kind: "folder" }, "fail");
+        await w.apply(tx);
+        return node;
+      });
+    },
+    /**
+     * Stores one blob and one node. The blob is written first. The new node commits before
+     * any old blob goes. A failed old-blob delete leaves an orphan and never undoes the commit.
+     */
+    async putFile(ctx, path, data, opts = {}) {
+      const mime = opts.mime === void 0 ? null : safeMime(opts.mime);
+      const hash = await sha256Hex(data);
+      const blobKey = `blobs/${newId()}`;
+      const stored = await blobs.put(blobKey, data, { ifNoneMatch: "*", ...mime ? { contentType: mime } : {} });
+      if (!stored) throw new DriveError("BLOB_EXISTS", "a blob with this key already exists");
+      let committed;
+      try {
+        committed = await transact(async (tx) => {
+          const w = batch();
+          const { parent, name } = await parentAndName(tx, w, ctx, path, opts.parents ?? false);
+          const result = await insert(tx, w, ctx, parent, name, { kind: "file", size: data.byteLength, mime, hash, blobKey }, opts.onConflict ?? "fail");
+          await w.apply(tx);
+          return result;
+        });
+      } catch (error) {
+        if (await isUnreferenced(blobKey)) await dropBlob(blobKey);
+        throw error;
+      }
+      if (committed.replacedBlob) await dropBlob(committed.replacedBlob);
+      return committed.node;
+    },
+    /** A reference points at a document in another app, such as `docs:<id>`. */
+    async putRef(ctx, path, ref, opts = {}) {
+      if (!REF.test(ref)) throw new DriveError("INVALID_REF", `a reference looks like "docs:<id>", got ${JSON.stringify(ref)}`);
+      return transact(async (tx) => {
+        const w = batch();
+        const { parent, name } = await parentAndName(tx, w, ctx, path, opts.parents ?? false);
+        const { node } = await insert(tx, w, ctx, parent, name, { kind: "ref", ref }, opts.onConflict === "replace" ? "fail" : opts.onConflict ?? "fail");
+        await w.apply(tx);
+        return node;
+      });
+    },
+    async read(ctx, loc) {
+      const node = await resolve(store, ctx, loc);
+      if (node.kind !== "file" || !node.blobKey) throw new DriveError("NOT_A_FILE", `${node.name} is not a file`);
+      const blob = await blobs.get(node.blobKey);
+      if (!blob) throw new DriveError("BLOB_MISSING", `the bytes of ${node.name} are missing`);
+      return { node, ...blob };
+    },
+    /**
+     * A time-limited URL to fetch the bytes. The URL signs an attachment header and the stored
+     * type, so the link holder cannot change how the bytes are served. Trashing an item does
+     * not revoke a link already issued.
+     */
+    async downloadUrl(ctx, loc, expiresInSeconds = DEFAULT_URL_SECONDS) {
+      if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > MAX_URL_SECONDS) {
+        throw new DriveError("INVALID_EXPIRY", `a link lasts 1 to ${MAX_URL_SECONDS} seconds`);
+      }
+      const node = await resolve(store, ctx, loc);
+      if (node.kind !== "file" || !node.blobKey) throw new DriveError("NOT_A_FILE", `${node.name} is not a file`);
+      const disposition = `attachment; filename*=UTF-8''${encodeURIComponent(node.name).replace(/['()*]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+      return blobs.signedUrl(node.blobKey, {
+        method: "GET",
+        expiresInSeconds,
+        responseContentDisposition: disposition.length <= 1024 ? disposition : "attachment",
+        responseContentType: node.mime ?? "application/octet-stream"
+      });
+    },
+    async move(ctx, src, destLoc, opts = {}) {
+      const probe = sharing ? await resolve(store, ctx, src) : null;
+      const height = probe ? await heightFor(ctx, probe, destLoc) : 0;
+      return transact(async (tx) => {
+        const w = batch();
+        const moved = await relocate(tx, w, ctx, await resolve(tx, ctx, src), destLoc, { ...opts, height });
+        await w.apply(tx);
+        return moved;
+      });
+    },
+    async rename(ctx, loc, name) {
+      return transact(async (tx) => {
+        const w = batch();
+        const node = await resolve(tx, ctx, loc);
+        if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot change the root");
+        const parent = await rawNode(tx, node.parentId, node.owner, ctx.actor);
+        if (!parent) throw new DriveError("NOT_FOUND", `the folder of ${node.name} is missing`);
+        const renamed = await relocate(tx, w, ctx, node, parent, { name });
+        await w.apply(tx);
+        return renamed;
+      });
+    },
+    /** Hides an item and, for a folder, everything under it. Nothing else changes. */
+    async trash(ctx, loc) {
+      return transact(async (tx) => {
+        const node = await resolve(tx, ctx, loc);
+        if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot trash the root");
+        await need(ctx, "write", node);
+        const claim = await claimId(node.owner, node.parentId, node.nameKey);
+        const held = await tx.get(NAMES, claim);
+        const t = now();
+        const trashed = { ...node, trashed: true, trashedAt: t, updatedAt: t, ...stamp(ctx, node) };
+        await tx.put(NODES, node.id, trashed);
+        if (held?.nodeId === node.id) await tx.delete(NAMES, claim);
+        return trashed;
+      });
+    },
+    /** Items trashed on their own, newest first. */
+    async listTrash(ctx) {
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
+      const page = await store.query(NODES, { where: { owner: ctx.owner, trashed: true }, limit: 1e3 });
+      const out = [];
+      for (const { data } of page.items) if (data.purging !== true) out.push(data);
+      return out.sort((a, b) => (b.trashedAt ?? 0) - (a.trashedAt ?? 0));
+    },
+    /** Puts a trashed item back. It needs a live parent folder. */
+    async restore(ctx, id, opts = {}) {
+      let height = 0;
+      if (sharing && opts.parentId !== void 0) {
+        const probe = await fetch(store, ctx, id);
+        const target = await rawNode(store, opts.parentId, ctx.owner, ctx.actor);
+        if (probe?.trashed && target && await can(ctx, "read", target)) height = await heightFor(ctx, probe, target);
+      }
+      return transact(async (tx) => {
+        const node = await fetch(tx, ctx, id);
+        if (!node || node.id === ROOT_ID) throw new DriveError("NOT_FOUND", `no item ${id}`);
+        if (!node.trashed) throw new DriveError("NOT_TRASHED", `${node.name} is not in the trash`);
+        await need(ctx, "write", node);
+        const parent = opts.parentId === void 0 ? await rawNode(tx, node.parentId, node.owner, ctx.actor) : await rawNode(tx, opts.parentId, ctx.owner, ctx.actor);
+        const visible = parent !== null && (opts.parentId === void 0 || await can(ctx, "read", parent));
+        if (!parent || !visible || parent.kind !== "folder" || !await isLive(tx, ctx, parent)) {
+          throw new DriveError("PARENT_GONE", `the folder of ${node.name} is gone or in the trash`);
+        }
+        if (parent.owner !== node.owner) throw new DriveError("CROSS_DRIVE", "an item cannot move into another person's drive");
+        if (parent.id !== node.parentId) {
+          await need(ctx, "write", parent);
+          await noClimb(ctx, node, parent);
+          await fitsUnder(tx, batch(), parent, height);
+        }
+        let { name, key } = parseName(node.name);
+        if ((await claimed(tx, parent.owner, parent.id, key)).taken) {
+          if (opts.onConflict !== "rename") throw new DriveError("NAME_TAKEN", `"${name}" already exists`);
+          name = await freeName(tx, parent.owner, parent.id, name);
+          key = parseName(name).key;
+        }
+        const restored = { ...node, parentId: parent.id, name, nameKey: key, trashed: false, trashedAt: null, updatedAt: now(), ...stamp(ctx, node) };
+        await tx.put(NODES, restored.id, restored);
+        await tx.put(NAMES, await claimId(parent.owner, parent.id, key), { nodeId: restored.id, owner: parent.owner, parentId: parent.id });
+        if (sharing && parent.id !== node.parentId) await tx.put("resources", restored.id, await resourceDoc(restored, parent));
+        return restored;
+      });
+    },
+    /** Live items that match every field given, sorted by path. */
+    async search(ctx, q = {}) {
+      const limit = q.limit ?? 100;
+      if (!Number.isInteger(limit) || limit < 1) throw new RangeError("limit must be an integer of 1 or more");
+      const all = await ownerNodes(ctx);
+      const byId = new Map(all.map((n) => [n.id, n]));
+      const needle = q.name?.normalize("NFC").toLowerCase();
+      const hits = [];
+      for (const node of all) {
+        const path = pathIn(byId, node, true);
+        if (path === null || node.purging) continue;
+        if (needle !== void 0 && !node.nameKey.includes(needle)) continue;
+        if (q.kind && node.kind !== q.kind) continue;
+        if (q.mime && !(q.mime.endsWith("/*") ? node.mime?.startsWith(q.mime.slice(0, -1)) : node.mime === q.mime)) continue;
+        if (q.minSize !== void 0 && node.size < q.minSize) continue;
+        if (q.maxSize !== void 0 && node.size > q.maxSize) continue;
+        if (q.createdByKind && node.createdBy.kind !== q.createdByKind) continue;
+        if (q.app !== void 0 && appOf(node) !== q.app) continue;
+        hits.push({ node, path });
+      }
+      return hits.sort((a, b) => a.path < b.path ? -1 : 1).slice(0, limit);
+    },
+    /** Every item of the owner, trashed or not, with its original path and bytes. For export. */
+    async exportData(ctx) {
+      const all = await ownerNodes(ctx);
+      const byId = new Map(all.map((n) => [n.id, n]));
+      const out = [];
+      for (const node of all.sort((a, b) => a.id < b.id ? -1 : 1)) {
+        const blob = node.blobKey ? await blobs.get(node.blobKey) : null;
+        out.push({ node, path: pathIn(byId, node, false), data: blob?.data ?? null, missing: node.blobKey !== null && !blob });
+      }
+      return out;
+    },
+    /** Deletes every item and blob of the owner for good. Only the owner may do this, never an agent for them. A failed call can run again. */
+    async deleteAll(ctx) {
+      assertInPerson(ctx, "delete the whole drive");
+      await need(ctx, "delete", rootNode(ctx.owner, ctx.actor));
+      return { removed: await eraseDrive(ctx.owner) };
+    },
+    /** Deletes a trashed item for good, with everything under it and all their bytes. */
+    async purge(ctx, id) {
+      const top = await fetch(store, ctx, id, true);
+      if (!top || top.id === ROOT_ID) throw new DriveError("NOT_FOUND", `no item ${id}`);
+      if (!top.trashed) throw new DriveError("NOT_TRASHED", `${top.name} is not in the trash`);
+      await need(ctx, "delete", top);
+      const nodes = [];
+      for (const queue = [top]; queue.length; ) {
+        const node = queue.pop();
+        nodes.push(node);
+        if (node.kind === "folder") queue.push(...await children(store, node.owner, node.id));
+      }
+      return { removed: await removeNodes(nodes, top) };
+    },
+    /**
+     * What the home view shows: every file and every reference to an app's document, newest change first.
+     * `apps` counts references per app, and `files` counts plain files, before `app` and `limit` apply.
+     */
+    async home(ctx, q = {}) {
+      const limit = q.limit ?? 100;
+      if (!Number.isInteger(limit) || limit < 1) throw new RangeError("limit must be an integer of 1 or more");
+      const all = await ownerNodes(ctx);
+      const byId = new Map(all.map((n) => [n.id, n]));
+      const apps = {};
+      let files = 0;
+      const items = [];
+      for (const node of all) {
+        const path = pathIn(byId, node, true);
+        if (path === null || node.kind === "folder") continue;
+        const app = appOf(node);
+        if (app === null) files++;
+        else apps[app] = (apps[app] ?? 0) + 1;
+        if (q.app === void 0 || app === q.app) items.push({ node, path, app });
+      }
+      items.sort((x, y) => y.node.updatedAt - x.node.updatedAt || (x.path < y.path ? -1 : 1));
+      return { items: items.slice(0, limit), apps, files };
+    },
+    /**
+     * An app puts one of its documents in this drive, as a reference such as `docs:<id>`. A document that is
+     * already in the drive comes back as it is, so an app can register again. The reference sits in `folder`
+     * (a path or a folder id, "/" by default) under `name`, and gets a free name when that one is taken.
+     */
+    async registerDocument(ctx, input) {
+      if (!REF.test(input.ref)) throw new DriveError("INVALID_REF", `a reference looks like "docs:<id>", got ${JSON.stringify(input.ref)}`);
+      parseName(input.name);
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
+      const dir = input.folder ?? "/";
+      const owner = dir.startsWith("/") ? ctx.owner : (await resolve(store, ctx, dir.split("/")[0])).owner;
+      for (const { data } of await allWhere(store, NODES, { owner, ref: input.ref })) {
+        const node = data;
+        if (node.kind === "ref" && !node.trashed && node.purging !== true && await isLive(store, ctx, node) && await can(ctx, "read", node)) return node;
+      }
+      return api.putRef(ctx, dir.endsWith("/") ? `${dir}${input.name}` : `${dir}/${input.name}`, input.ref, { parents: true, onConflict: "rename" });
+    },
+    /** An app deleted a document. Its references in this drive go to the trash. Returns how many. */
+    async forgetDocument(ctx, ref) {
+      if (!REF.test(ref)) throw new DriveError("INVALID_REF", `a reference looks like "docs:<id>", got ${JSON.stringify(ref)}`);
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
+      let trashed = 0;
+      for (const { data } of await allWhere(store, NODES, { owner: ctx.owner, ref })) {
+        if (data.kind !== "ref" || data.trashed || data.purging === true) continue;
+        try {
+          await api.trash(ctx, data.id);
+          trashed++;
+        } catch (error) {
+          if (!(error instanceof DriveError && error.code === "TRASHED")) throw error;
+        }
+      }
+      return { trashed };
+    },
+    /**
+     * What drive holds about the person behind a call, besides their own drive (`exportData` has that). It is
+     * only for the person in person: an agent gets `partial: true` and nothing else. It holds the ids of the
+     * items they or their agents made or changed in other drives (no names, and nothing of the people who own
+     * them), the shares they hold, the invites they sent, and the audit entries of what they and their agents
+     * did. Invitee emails and link tokens are not in it.
+     */
+    async exportPerson(ctx) {
+      await need(ctx, "read", rootNode(ctx.owner, ctx.actor));
+      const subject = subjectOf(ctx);
+      if (!isInPerson(ctx)) return { subject, partial: true, authored: [], agents: [], shares: { held: [], invitesCreated: [] }, audit: [] };
+      const { actors, ownedAgents } = await actorsOf(store, subject.id);
+      const authored = (await madeBy(store, actors)).filter((n) => n.owner !== subject.id && n.purging !== true).map((n) => ({
+        id: n.id,
+        kind: n.kind,
+        created: actors.includes(n.createdById),
+        updated: actors.includes(n.updatedById),
+        createdAt: actors.includes(n.createdById) ? n.createdAt : null,
+        updatedAt: actors.includes(n.updatedById) ? n.updatedAt : null,
+        by: [...new Set([actors.includes(n.createdById) ? n.createdBy : null, actors.includes(n.updatedById) ? n.updatedBy : null].filter((a) => a !== null).map((a) => JSON.stringify(a)))].map((a) => JSON.parse(a))
+      })).sort((x, y) => x.id < y.id ? -1 : 1);
+      const held = [];
+      for (const actor of actors) for (const g of await allWhere(store, "grants", { subjectId: actor })) held.push({ subjectId: g.data.subjectId, resourceId: g.data.resourceId, role: g.data.role });
+      const agents = [];
+      for (const agent of ownedAgents) {
+        const items = (await rawOwnerNodes(agent, false)).map((n) => ({ id: n.id, kind: n.kind, name: n.name, size: n.size, mime: n.mime, createdAt: n.createdAt, updatedAt: n.updatedAt, trashed: n.trashed }));
+        agents.push({ id: agent, items });
+      }
+      const invitesCreated = [];
+      const audit = [];
+      for (const actor of actors) {
+        for (const i of await allWhere(store, "invites", { createdBy: actor })) {
+          invitesCreated.push({ id: i.data.id, resourceId: i.data.resourceId, role: i.data.role, expiresAt: i.data.expiresAt ?? null, accepted: i.data.acceptedAt !== void 0 });
+        }
+        for (const e of await allWhere(store, "audit", { principalId: actor }, { field: "at" })) {
+          audit.push({ at: e.data.at, action: e.data.action, resourceId: e.data.resourceId ?? null, outcome: e.data.outcome, principalId: e.data.principalId, principalKind: e.data.principalKind, machineMade: e.data.machineMade });
+        }
+      }
+      audit.sort((x, y) => x.at - y.at);
+      return { subject, partial: false, authored, agents, shares: { held, invitesCreated }, audit };
+    },
+    /**
+     * Erases a person for good. Only the person in person may. Their drive and its shares go. So do the shares
+     * they hold and the invites they or their agents sent, on drive items only: the grants of other apps stay for
+     * those apps and for identity. What they or their agents made in other drives stays, because it belongs to
+     * those drives: the id becomes "erased", and the kind stays, so machine-made work keeps its label. The audit
+     * trail stays: it holds ids and kinds only. A failed call can run again.
+     */
+    async erasePerson(ctx) {
+      assertInPerson(ctx, "erase a person");
+      const { id } = subjectOf(ctx);
+      const { actors, ownedAgents } = await actorsOf(store, id);
+      let { removed } = await api.deleteAll(ctx);
+      for (const agent of ownedAgents) removed += await eraseDrive(agent);
+      const ofDrive = async (docs) => {
+        const out = [];
+        for (const doc of docs) if ((await store.get("resources", doc.data.resourceId))?.type === "drive") out.push({ id: doc.id });
+        return out;
+      };
+      const sweep = async (docs, collection) => {
+        for (let i = 0; i < docs.length; i += 100) {
+          await transact(async (tx) => {
+            for (const doc of docs.slice(i, i + 100)) await tx.delete(collection, doc.id);
+          });
+        }
+        return docs.length;
+      };
+      let grants = 0;
+      let invites = 0;
+      for (const actor of actors) grants += await sweep(await ofDrive(await allWhere(store, "grants", { subjectId: actor })), "grants");
+      for (const actor of actors) invites += await sweep(await ofDrive(await allWhere(store, "invites", { createdBy: actor })), "invites");
+      const todo = await madeBy(store, actors);
+      for (let i = 0; i < todo.length; i += CHUNK) {
+        await transact(async (tx) => {
+          const current = [];
+          for (const node of todo.slice(i, i + CHUNK)) {
+            const found = await tx.get(NODES, node.id);
+            if (found) current.push(found);
+          }
+          for (const node of current) {
+            const next = { ...node };
+            if (actors.includes(node.createdById ?? node.createdBy.id)) Object.assign(next, { createdBy: { id: ERASED, kind: node.createdBy.kind }, createdById: ERASED });
+            if (actors.includes(node.updatedById ?? node.updatedBy.id)) Object.assign(next, { updatedBy: { id: ERASED, kind: node.updatedBy.kind }, updatedById: ERASED });
+            await tx.put(NODES, node.id, next);
+          }
+        });
+      }
+      return { removed, grants, invites, anonymized: todo.length };
+    },
+    /** Gives a person or an agent a role on an item and everything under it. Only an owner may. */
+    async shareWith(ctx, loc, subjectId, role) {
+      const resource = await resourceOf(await resolve(store, ctx, loc));
+      await viaSharing(ctx, (s, p) => s.grant(p, resource, subjectId, role));
+    },
+    async unshare(ctx, loc, subjectId) {
+      const resource = await resourceOf(await resolve(store, ctx, loc));
+      await viaSharing(ctx, (s, p) => s.revokeGrant(p, resource, subjectId));
+    },
+    /** Invite by `email` (a person) or `handle` (an agent). The invite lasts `expiresInMs`, if given. It sends no message. */
+    async invite(ctx, loc, input) {
+      const resource = await resourceOf(await resolve(store, ctx, loc));
+      return viaSharing(ctx, (s, p) => s.createInvite(p, resource, input));
+    },
+    /** `identity` is the verified email of a person, or the handle of an agent. */
+    async acceptInvite(ctx, inviteId, identity) {
+      await viaSharing(ctx, (s, p) => s.acceptInvite(p, inviteId, identity));
+    },
+    /** The token comes back once. Only its hash is stored. */
+    async createLink(ctx, loc, input) {
+      const resource = await resourceOf(await resolve(store, ctx, loc));
+      return viaSharing(ctx, (s, p) => s.createLink(p, resource, input));
+    },
+    async revokeLink(ctx, linkId) {
+      await viaSharing(ctx, (s, p) => s.revokeLink(p, linkId));
+    },
+    /** Who can reach an item, and by which links and invites. Only an owner may look. Link tokens are never shown. */
+    async shares(ctx, loc) {
+      const node = await resolve(store, ctx, loc);
+      await need(ctx, "delete", node);
+      const where = { resourceId: await resourceOf(node) };
+      const rows = async (collection) => (await store.query(collection, { where, limit: 100 })).items.map((item) => item.data);
+      return {
+        grants: (await rows("grants")).map((g) => ({ subjectId: g.subjectId, role: g.role })),
+        links: (await rows("links")).map((l) => ({ id: l.id, role: l.role, signedInOnly: l.signedInOnly === true, expiresAt: l.expiresAt ?? null, revoked: l.revokedAt != null })),
+        invites: (await rows("invites")).map((i) => ({ id: i.id, role: i.role, email: i.email ?? null, handle: i.handle ?? null, expiresAt: i.expiresAt ?? null, accepted: i.acceptedAt !== void 0 }))
+      };
+    },
+    openShared,
+    /** Live children of a folder that a link visitor or a signed-in person may read, sorted by name. */
+    async listShared(principal, id, linkToken) {
+      const folder = await openShared(principal, id, linkToken);
+      if (folder.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${folder.name} is not a folder`);
+      return (await children(store, folder.owner, folder.id)).filter((n) => !n.trashed && n.purging !== true).sort((x, y) => x.nameKey < y.nameKey ? -1 : x.nameKey > y.nameKey ? 1 : x.name < y.name ? -1 : 1);
+    },
+    async readShared(principal, id, linkToken) {
+      const node = await openShared(principal, id, linkToken);
+      if (node.kind !== "file" || !node.blobKey) throw new DriveError("NOT_A_FILE", `${node.name} is not a file`);
+      const blob = await blobs.get(node.blobKey);
+      if (!blob) throw new DriveError("BLOB_MISSING", `the bytes of ${node.name} are missing`);
+      return { node, ...blob };
+    }
+  };
+  async function viaSharing(ctx, fn) {
+    if (!sharing) throw new DriveError("INVALID_SHARE", "sharing is not set up");
+    if (!ctx.principal) throw new DriveError("FORBIDDEN", "sign in to share");
+    try {
+      return await fn(sharing, ctx.principal);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "";
+      if (message === "forbidden") throw new DriveError("FORBIDDEN", "not allowed to share this item");
+      if (SHARE_ERROR.test(message)) throw new DriveError("INVALID_SHARE", message);
+      throw error;
+    }
+  }
+  async function prepare(ctx) {
+    if (!sharing || ctx.principal === void 0) return;
+    if (ctx.principal.chain[0]?.id !== ctx.owner) throw new DriveError("FORBIDDEN", "the caller does not own this drive");
+    const id = await rootResource(ctx.owner);
+    if ((await store.get("resources", id))?.type === "drive") return;
+    try {
+      await sharing.createResource(ctx.principal, { id, type: "drive" });
+    } catch {
+    }
+  }
+  const guarded = (call) => async (ctx, ...args) => {
+    await prepare(ctx);
+    return call(ctx, ...args);
+  };
+  const open = /* @__PURE__ */ new Set(["openShared", "listShared", "readShared"]);
+  return Object.fromEntries(Object.entries(api).map(([name, call]) => [name, open.has(name) ? call : guarded(call)]));
+}
+
+// src/zip.ts
+var CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+  return c >>> 0;
+});
+function crc32(data) {
+  let crc = 4294967295;
+  for (const byte of data) crc = CRC_TABLE[(crc ^ byte) & 255] ^ crc >>> 8;
+  return (crc ^ 4294967295) >>> 0;
+}
+function safeEntryName(name) {
+  if (name === "" || /[\\\u0000]/.test(name) || name.startsWith("/") || /^[a-zA-Z]:/.test(name)) return false;
+  return name.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+function writeZip(entries, at) {
+  for (const { name } of entries) if (!safeEntryName(name)) throw new Error(`zip: unsafe entry name ${JSON.stringify(name)}`);
+  const d = new Date(at);
+  const time = d.getUTCHours() << 11 | d.getUTCMinutes() << 5 | d.getUTCSeconds() >> 1;
+  const date = Math.max(d.getUTCFullYear(), 1980) - 1980 << 9 | d.getUTCMonth() + 1 << 5 | d.getUTCDate();
+  const parts = [];
+  const central = [];
+  let offset = 0;
+  const u16 = (v, o, n) => v.setUint16(o, n, true);
+  const u32 = (v, o, n) => v.setUint32(o, n, true);
+  for (const entry of entries) {
+    const name = new TextEncoder().encode(entry.name);
+    const crc = crc32(entry.data);
+    if (entry.data.byteLength >= 4294967295 || offset >= 4294967295 || entries.length >= 65535) throw new Error("zip: export is too large for a plain zip");
+    const local = new DataView(new ArrayBuffer(30));
+    u32(local, 0, 67324752);
+    u16(local, 4, 20);
+    u16(local, 6, 2048);
+    u16(local, 8, 0);
+    u16(local, 10, time);
+    u16(local, 12, date);
+    u32(local, 14, crc);
+    u32(local, 18, entry.data.byteLength);
+    u32(local, 22, entry.data.byteLength);
+    u16(local, 26, name.length);
+    u16(local, 28, 0);
+    const head = new DataView(new ArrayBuffer(46));
+    u32(head, 0, 33639248);
+    u16(head, 4, 20);
+    u16(head, 6, 20);
+    u16(head, 8, 2048);
+    u16(head, 10, 0);
+    u16(head, 12, time);
+    u16(head, 14, date);
+    u32(head, 16, crc);
+    u32(head, 20, entry.data.byteLength);
+    u32(head, 24, entry.data.byteLength);
+    u16(head, 28, name.length);
+    u32(head, 42, offset);
+    parts.push(new Uint8Array(local.buffer), name, entry.data);
+    central.push(new Uint8Array(head.buffer), name);
+    offset += 30 + name.length + entry.data.byteLength;
+  }
+  const size = central.reduce((n, p) => n + p.byteLength, 0);
+  const end = new DataView(new ArrayBuffer(22));
+  u32(end, 0, 101010256);
+  u16(end, 8, entries.length);
+  u16(end, 10, entries.length);
+  u32(end, 12, size);
+  u32(end, 16, offset);
+  const all = [...parts, ...central, new Uint8Array(end.buffer)];
+  const out = new Uint8Array(all.reduce((n, p) => n + p.byteLength, 0));
+  let at2 = 0;
+  for (const p of all) {
+    out.set(p, at2);
+    at2 += p.byteLength;
+  }
+  return out;
+}
+function readZip(bytes) {
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let end = bytes.byteLength - 22;
+  while (end >= 0 && v.getUint32(end, true) !== 101010256) end--;
+  if (end < 0) throw new Error("zip: no end signature");
+  const count = v.getUint16(end + 10, true);
+  const out = /* @__PURE__ */ new Map();
+  for (let i = 0, at = v.getUint32(end + 16, true); i < count; i++) {
+    if (v.getUint32(at, true) !== 33639248) throw new Error("zip: bad central signature");
+    if (v.getUint16(at + 10, true) !== 0) throw new Error("zip: compressed entries are not supported");
+    const crc = v.getUint32(at + 16, true);
+    const size = v.getUint32(at + 24, true);
+    const nameLen = v.getUint16(at + 28, true);
+    const local = v.getUint32(at + 42, true);
+    const name = new TextDecoder().decode(bytes.subarray(at + 46, at + 46 + nameLen));
+    if (v.getUint32(local, true) !== 67324752) throw new Error("zip: bad local signature");
+    const start = local + 30 + v.getUint16(local + 26, true) + v.getUint16(local + 28, true);
+    const data = bytes.slice(start, start + size);
+    if (crc32(data) !== crc) throw new Error(`zip: crc mismatch in ${name}`);
+    out.set(name, data);
+    at += 46 + nameLen + v.getUint16(at + 30, true) + v.getUint16(at + 32, true);
+  }
+  return out;
+}
+
+// src/export.ts
+async function buildExport(drive, ctx, now = Date.now) {
+  const entries = [];
+  const items = (await drive.exportData(ctx)).map(({ node, path, data, missing }) => {
+    const file = data ? `files/${node.id}` : null;
+    if (data && file) entries.push({ name: file, data });
+    return {
+      id: node.id,
+      owner: node.owner,
+      path,
+      parentId: node.parentId,
+      kind: node.kind,
+      name: node.name,
+      size: node.size,
+      mime: node.mime,
+      hash: node.hash,
+      ref: node.ref,
+      createdAt: node.createdAt,
+      updatedAt: node.updatedAt,
+      createdBy: node.createdBy,
+      updatedBy: node.updatedBy,
+      trashed: node.trashed,
+      trashedAt: node.trashedAt,
+      file,
+      ...missing ? { missing: true } : {}
+    };
+  });
+  const person = await drive.exportPerson(ctx);
+  const manifest = { format: "agentic-drive-export", version: 2, exportedAt: now(), owner: ctx.owner, subject: person.subject, partial: person.partial, items, authored: person.authored, agents: person.agents, shares: person.shares, audit: person.audit };
+  return writeZip([{ name: "manifest.json", data: new TextEncoder().encode(JSON.stringify(manifest, null, 2)) }, ...entries], now());
+}
+
+// src/adapters/fs.ts
+import { createHash } from "crypto";
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, truncateSync, writeFileSync, writeSync } from "fs";
+import { join } from "path";
+import { assertBlobPutOptions, assertResponseHeaders, createMemoryStore, parseRegion } from "agentic-identity";
+function createFileStore(dir, options = {}) {
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, "store.jsonl");
+  const inner = createMemoryStore(options);
+  const ready = (async () => {
+    if (!existsSync(file)) return;
+    const text = readFileSync(file, "utf8");
+    const lines = text.split("\n");
+    const tail = lines.pop();
+    const apply = async (changes2) => {
+      for (const [collection, id, doc] of changes2) await (doc ? inner.put(collection, id, doc) : inner.delete(collection, id));
+    };
+    for (const [i, line] of lines.entries()) {
+      if (line === "") continue;
+      try {
+        await apply(JSON.parse(line));
+      } catch {
+        throw new Error(`the journal ${file} has a bad line ${i + 1}`);
+      }
+    }
+    if (tail === "") return;
+    let changes;
+    try {
+      changes = JSON.parse(tail);
+    } catch {
+      truncateSync(file, Buffer.byteLength(text) - Buffer.byteLength(tail));
+      return;
+    }
+    try {
+      await apply(changes);
+    } catch {
+      throw new Error(`the journal ${file} has a bad last line`);
+    }
+    appendFileSync(file, "\n");
+  })();
+  let failed;
+  const keep = (changes) => {
+    if (changes.length === 0) return;
+    try {
+      const fd = openSync(file, "a");
+      try {
+        const line = Buffer.from(`${JSON.stringify(changes)}
+`);
+        for (let done = 0; done < line.length; ) {
+          const wrote = writeSync(fd, line, done);
+          if (wrote <= 0) throw new Error("the journal write stopped short");
+          done += wrote;
+        }
+        fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+    } catch (error) {
+      failed = error;
+      throw error;
+    }
+  };
+  const open = async () => {
+    await ready;
+    if (failed !== void 0) throw new Error("the journal could not be written, so the store is closed. Open it again.");
+  };
+  const recording = (ops, changes) => ({
+    ...ops,
+    put: async (collection, id, doc) => {
+      await ops.put(collection, id, doc);
+      changes.push([collection, id, doc]);
+    },
+    delete: async (collection, id) => {
+      await ops.delete(collection, id);
+      changes.push([collection, id, null]);
+    }
+  });
+  return {
+    region: inner.region,
+    get: async (c, id) => (await open(), inner.get(c, id)),
+    query: async (c, q) => (await open(), inner.query(c, q)),
+    async put(collection, id, doc) {
+      await open();
+      await inner.put(collection, id, doc);
+      keep([[collection, id, doc]]);
+    },
+    async delete(collection, id) {
+      await open();
+      await inner.delete(collection, id);
+      keep([[collection, id, null]]);
+    },
+    async transaction(fn) {
+      await open();
+      let changes = [];
+      const result = await inner.transaction((tx) => {
+        changes = [];
+        return fn(recording(tx, changes));
+      });
+      keep(changes);
+      return result;
+    }
+  };
+}
+var versionOf = (data) => createHash("sha256").update(data).digest("hex");
+function createFileBlobs(dir, options = {}) {
+  mkdirSync(dir, { recursive: true });
+  const path = (key) => join(dir, createHash("sha256").update(key).digest("hex"));
+  const need = (key) => {
+    if (key === "") throw new Error("blob key must not be empty");
+  };
+  const now = options.now ?? Date.now;
+  return {
+    region: options.region === void 0 ? "unknown" : parseRegion(options.region),
+    async put(key, data, opts) {
+      need(key);
+      assertBlobPutOptions(opts);
+      const current = existsSync(path(key)) ? versionOf(readFileSync(path(key))) : void 0;
+      if (opts?.ifNoneMatch === "*" && current !== void 0 || opts?.ifMatch !== void 0 && current !== opts.ifMatch) return null;
+      const tmp = `${path(key)}.tmp`;
+      writeFileSync(tmp, data);
+      if (opts?.contentType) writeFileSync(`${path(key)}.type`, opts.contentType);
+      else rmSync(`${path(key)}.type`, { force: true });
+      renameSync(tmp, path(key));
+      return { version: versionOf(data) };
+    },
+    async get(key) {
+      need(key);
+      if (!existsSync(path(key))) return null;
+      const type = existsSync(`${path(key)}.type`) ? readFileSync(`${path(key)}.type`, "utf8") : void 0;
+      const data = new Uint8Array(readFileSync(path(key)));
+      return { data, version: versionOf(data), ...type ? { contentType: type } : {} };
+    },
+    async head(key) {
+      need(key);
+      if (!existsSync(path(key))) return null;
+      const type = existsSync(`${path(key)}.type`) ? readFileSync(`${path(key)}.type`, "utf8") : void 0;
+      const data = readFileSync(path(key));
+      return { size: data.length, version: versionOf(data), ...type ? { contentType: type } : {} };
+    },
+    async delete(key) {
+      need(key);
+      rmSync(path(key), { force: true });
+      rmSync(`${path(key)}.type`, { force: true });
+    },
+    /** A local path with its expiry. Nothing serves or checks it: it exists so the port is whole. */
+    async signedUrl(key, opts) {
+      need(key);
+      const { method, expiresInSeconds } = opts;
+      assertResponseHeaders(opts);
+      if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > 604800) {
+        throw new RangeError("expiresInSeconds must be an integer from 1 to 604800");
+      }
+      const extra = [
+        opts.responseContentDisposition === void 0 ? "" : `&disposition=${encodeURIComponent(opts.responseContentDisposition)}`,
+        opts.responseContentType === void 0 ? "" : `&type=${encodeURIComponent(opts.responseContentType)}`
+      ].join("");
+      return `file://${path(key)}?method=${method}&expires=${now() + expiresInSeconds * 1e3}${extra}`;
+    }
+  };
+}
+
+// src/local.ts
+import { join as join2 } from "path";
+function openLocal(options) {
+  const kind = options.kind ?? "human";
+  if (!ACTOR_KINDS.includes(kind)) throw new Error(`unknown actor kind "${kind}"`);
+  return {
+    drive: createDrive({ store: createFileStore(join2(options.dir, "db")), blobs: createFileBlobs(join2(options.dir, "blobs")) }),
+    ctx: { owner: options.owner, actor: { id: options.actor ?? options.owner, kind } }
+  };
+}
+function publicNode(node, path) {
+  const { nameKey: _nameKey, blobKey: _blobKey, purging: _purging, ...rest } = node;
+  return path === void 0 ? rest : { path, ...rest };
+}
+
+// src/upload.ts
+var DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+var SIGNATURES = [
+  [[137, 80, 78, 71, 13, 10, 26, 10], "image/png"],
+  [[255, 216, 255], "image/jpeg"],
+  [[71, 73, 70, 56], "image/gif"],
+  [[37, 80, 68, 70, 45], "application/pdf"],
+  [[80, 75, 3, 4], "application/zip"],
+  [[31, 139], "application/gzip"]
+];
+function sniffMime(head) {
+  const hit = SIGNATURES.find(([sig]) => sig.every((byte, i) => head[i] === byte));
+  if (hit) return hit[1];
+  const isWebp = [..."RIFF"].every((c, i) => head[i] === c.charCodeAt(0)) && [..."WEBP"].every((c, i) => head[8 + i] === c.charCodeAt(0));
+  return isWebp ? "image/webp" : null;
+}
+function looksLikeText(head) {
+  if (head.includes(0)) return false;
+  for (let cut = 0; cut < 4 && cut <= head.length; cut++) {
+    try {
+      new TextDecoder("utf-8", { fatal: true }).decode(head.subarray(0, head.length - cut));
+      return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+async function* iterate(source) {
+  if (Symbol.asyncIterator in source) {
+    yield* source;
+    return;
+  }
+  const reader = source.getReader();
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function upload(drive, ctx, path, source, opts = {}) {
+  const max = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const parts = [];
+  let size = 0;
+  for await (const chunk of iterate(source)) {
+    size += chunk.byteLength;
+    if (size > max) throw new DriveError("TOO_LARGE", `upload is over the limit of ${max} bytes`);
+    parts.push(chunk);
+  }
+  const data = new Uint8Array(size);
+  for (let at = 0, i = 0; i < parts.length; at += parts[i].byteLength, i++) data.set(parts[i], at);
+  const head = data.subarray(0, 512);
+  const mime = sniffMime(head) ?? (opts.mime !== void 0 ? safeMime(opts.mime) : looksLikeText(head) ? "text/plain" : "application/octet-stream");
+  return drive.putFile(ctx, path, data, { mime, parents: opts.parents, onConflict: opts.onConflict });
+}
+
+export {
+  ROOT_ID,
+  ACTOR_KINDS,
+  DriveError,
+  DEFAULT_URL_SECONDS,
+  safeMime,
+  parseName,
+  rootResource,
+  createDrive,
+  writeZip,
+  readZip,
+  buildExport,
+  createFileStore,
+  createFileBlobs,
+  openLocal,
+  publicNode,
+  DEFAULT_MAX_BYTES,
+  sniffMime,
+  upload
+};