agentic-drive 0.7.0 → 0.8.0

package/dist/{chunk-PJQ3CRVL.js → chunk-R2DUVOJT.js}

@@ -1,9 +1,34 @@
 // src/drive.ts
-import { EraseRefusedError, MAX_FOLDER_DEPTH, PRINCIPAL_KINDS, SUBJECT_KINDS } from "agentic-identity";
+import { EraseRefusedError, StoreConflictError, MAX_FOLDER_DEPTH, PRINCIPAL_KINDS, ROLES, SUBJECT_KINDS } from "agentic-identity";
 var ROOT_ID = "root";
 var NODES = "drive_nodes";
 var NAMES = "drive_names";
 var ACTOR_KINDS = PRINCIPAL_KINDS;
+var DECIDED = /* @__PURE__ */ Symbol("decided");
+var ERROR_STATUS = Object.freeze({
+  CROSS_DRIVE: 409,
+  INVALID_SHARE: 400,
+  TOO_MANY_ITEMS: 409,
+  TOO_DEEP: 400,
+  INVALID_EXPIRY: 400,
+  BUSY: 409,
+  BLOB_EXISTS: 500,
+  NOT_FOUND: 404,
+  NAME_TAKEN: 409,
+  INVALID_NAME: 400,
+  INVALID_PATH: 400,
+  INVALID_REF: 400,
+  NOT_A_FOLDER: 400,
+  NOT_A_FILE: 400,
+  MOVE_INTO_SELF: 409,
+  PARENT_GONE: 409,
+  TRASHED: 409,
+  NOT_TRASHED: 409,
+  IS_ROOT: 400,
+  FORBIDDEN: 403,
+  BLOB_MISSING: 500,
+  TOO_LARGE: 413
+});
 var DriveError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -59,6 +84,20 @@ function splitPath(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);
 }
+var Ask = class extends Error {
+  constructor(key, ctx, action, node) {
+    super("access answer needed");
+    this.key = key;
+    this.ctx = ctx;
+    this.action = action;
+    this.node = node;
+  }
+  key;
+  ctx;
+  action;
+  node;
+};
+var MAX_ASKS = 100;
 function batch() {
   const writes = [];
   const fresh = /* @__PURE__ */ new Set();
@@ -101,7 +140,24 @@ function createDrive(deps) {
   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 askCan = 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 can = async (ctx, action, node) => {
+    const held = ctx[DECIDED];
+    if (!held) return askCan(ctx, action, node);
+    const chain = [];
+    if (sharing) {
+      for (let id = await resourceOf(node), i = 0; id && i <= MAX_ITEM_DEPTH + 1; i++) {
+        const doc = await held.tx.get("resources", id);
+        chain.push(doc?.parentId ?? null);
+        id = typeof doc?.parentId === "string" ? doc.parentId : void 0;
+      }
+    }
+    const key = JSON.stringify([action, node.id, node.owner, node.parentId, node.updatedAt, node.trashed, chain, ctx.owner, ctx.actor, ctx.principal ?? null]);
+    const known = held.answers.get(key);
+    if (known !== void 0) return known;
+    const { [DECIDED]: _held, ...plain } = ctx;
+    throw new Ask(key, plain, action, node);
+  };
   const rootNode = (owner, by) => ({
     id: ROOT_ID,
     owner,
@@ -397,10 +453,30 @@ function createDrive(deps) {
     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.");
+      if (error instanceof StoreConflictError || error instanceof Error && /transaction kept conflicting/.test(error.message)) throw new DriveError("BUSY", "the drive changed at the same time. Try again.");
       throw error;
     }
   }
+  async function transactAs(ctx, fn) {
+    const answers = /* @__PURE__ */ new Map();
+    let runs = 0;
+    let asked = false;
+    for (; ; ) {
+      try {
+        return await transact((tx) => {
+          if (++runs > 2 * MAX_ASKS) throw new DriveError("BUSY", "the drive changed at the same time. Try again.");
+          if (runs > 1 && !asked) answers.clear();
+          asked = false;
+          return fn(tx, { ...ctx, [DECIDED]: { answers, tx } });
+        });
+      } catch (error) {
+        if (!(error instanceof Ask)) throw error;
+        asked = true;
+        if (answers.size >= MAX_ASKS) throw new DriveError("BUSY", "the drive needed too many access checks. Try again.");
+        answers.set(error.key, await askCan(error.ctx, error.action, error.node));
+      }
+    }
+  }
   function assertInPerson(ctx, what) {
     if (!isInPerson(ctx) || ctx.actor.kind !== "human") throw new DriveError("FORBIDDEN", `only the owner in person can ${what}`);
   }
@@ -550,15 +626,15 @@ function createDrive(deps) {
       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) => {
+      return transactAs(ctx, async (tx, ctx2) => {
         const w = batch();
-        const { parent, name } = await parentAndName(tx, w, ctx, path, opts.parents ?? false);
+        const { parent, name } = await parentAndName(tx, w, ctx2, 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}`);
+          if (!await can(ctx2, "read", existing)) throw new DriveError("NOT_FOUND", `no item ${path}`);
           return existing;
         }
-        const { node } = await insert(tx, w, ctx, parent, name, { kind: "folder" }, "fail");
+        const { node } = await insert(tx, w, ctx2, parent, name, { kind: "folder" }, "fail");
         await w.apply(tx);
         return node;
       });
@@ -575,10 +651,10 @@ function createDrive(deps) {
       if (!stored) throw new DriveError("BLOB_EXISTS", "a blob with this key already exists");
       let committed;
       try {
-        committed = await transact(async (tx) => {
+        committed = await transactAs(ctx, async (tx, ctx2) => {
           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");
+          const { parent, name } = await parentAndName(tx, w, ctx2, path, opts.parents ?? false);
+          const result = await insert(tx, w, ctx2, parent, name, { kind: "file", size: data.byteLength, mime, hash, blobKey }, opts.onConflict ?? "fail");
           await w.apply(tx);
           return result;
         });
@@ -592,10 +668,10 @@ function createDrive(deps) {
     /** 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) => {
+      return transactAs(ctx, async (tx, ctx2) => {
         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");
+        const { parent, name } = await parentAndName(tx, w, ctx2, path, opts.parents ?? false);
+        const { node } = await insert(tx, w, ctx2, parent, name, { kind: "ref", ref }, opts.onConflict === "replace" ? "fail" : opts.onConflict ?? "fail");
         await w.apply(tx);
         return node;
       });
@@ -629,35 +705,35 @@ function createDrive(deps) {
     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) => {
+      return transactAs(ctx, async (tx, ctx2) => {
         const w = batch();
-        const moved = await relocate(tx, w, ctx, await resolve(tx, ctx, src), destLoc, { ...opts, height });
+        const moved = await relocate(tx, w, ctx2, await resolve(tx, ctx2, src), destLoc, { ...opts, height });
         await w.apply(tx);
         return moved;
       });
     },
     async rename(ctx, loc, name) {
-      return transact(async (tx) => {
+      return transactAs(ctx, async (tx, ctx2) => {
         const w = batch();
-        const node = await resolve(tx, ctx, loc);
+        const node = await resolve(tx, ctx2, 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);
+        const parent = await rawNode(tx, node.parentId, node.owner, ctx2.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 });
+        const renamed = await relocate(tx, w, ctx2, 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);
+      return transactAs(ctx, async (tx, ctx2) => {
+        const node = await resolve(tx, ctx2, loc);
         if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot trash the root");
-        await need(ctx, "write", node);
+        await need(ctx2, "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) };
+        const trashed = { ...node, trashed: true, trashedAt: t, updatedAt: t, ...stamp(ctx2, node) };
         await tx.put(NODES, node.id, trashed);
         if (held?.nodeId === node.id) await tx.delete(NAMES, claim);
         return trashed;
@@ -671,6 +747,15 @@ function createDrive(deps) {
       for (const { data } of page.items) if (data.purging !== true) out.push(data);
       return out.sort((a, b) => (b.trashedAt ?? 0) - (a.trashedAt ?? 0));
     },
+    /** Everything that is in the trash, newest first, each with the path it had before. It reads the whole drive, so a big drive costs more than `listTrash`. */
+    async listTrashWithPaths(ctx) {
+      const all = await ownerNodes(ctx);
+      const byId = new Map(all.map((n) => [n.id, n]));
+      return all.filter((n) => n.trashed).sort((a, b) => (b.trashedAt ?? 0) - (a.trashedAt ?? 0)).flatMap((node) => {
+        const path = pathIn(byId, node, false);
+        return path === null ? [] : [{ node, path }];
+      });
+    },
     /** Puts a trashed item back. It needs a live parent folder. */
     async restore(ctx, id, opts = {}) {
       let height = 0;
@@ -679,20 +764,20 @@ function createDrive(deps) {
         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);
+      return transactAs(ctx, async (tx, ctx2) => {
+        const node = await fetch(tx, ctx2, 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)) {
+        await need(ctx2, "write", node);
+        const parent = opts.parentId === void 0 ? await rawNode(tx, node.parentId, node.owner, ctx2.actor) : await rawNode(tx, opts.parentId, ctx2.owner, ctx2.actor);
+        const visible = parent !== null && (opts.parentId === void 0 || await can(ctx2, "read", parent));
+        if (!parent || !visible || parent.kind !== "folder" || !await isLive(tx, ctx2, 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 need(ctx2, "write", parent);
+          await noClimb(ctx2, node, parent);
           await fitsUnder(tx, batch(), parent, height);
         }
         let { name, key } = parseName(node.name);
@@ -701,7 +786,7 @@ function createDrive(deps) {
           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) };
+        const restored = { ...node, parentId: parent.id, name, nameKey: key, trashed: false, trashedAt: null, updatedAt: now(), ...stamp(ctx2, 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));
@@ -803,6 +888,58 @@ function createDrive(deps) {
       }
       return api.putRef(ctx, dir.endsWith("/") ? `${dir}${input.name}` : `${dir}/${input.name}`, input.ref, { parents: true, onConflict: "rename" });
     },
+    /** The live references to `ref` in the caller's own drive that the caller can read, with their paths, sorted by path. */
+    async findByRef(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));
+      const hits = [];
+      const seen = /* @__PURE__ */ new Map();
+      const folder = async (id) => {
+        if (!seen.has(id)) seen.set(id, await rawNode(store, id, ctx.owner, ctx.actor));
+        return seen.get(id) ?? null;
+      };
+      for (const { data } of await allWhere(store, NODES, { owner: ctx.owner, ref })) {
+        const node = data;
+        if (node.kind !== "ref" || node.trashed || node.purging === true) continue;
+        const names = [node.name];
+        let up = node;
+        for (let depth = 0; up && up.parentId !== ROOT_ID && depth < maxDepth; depth++) {
+          up = await folder(up.parentId);
+          if (up === null || up.trashed) break;
+          names.push(up.name);
+        }
+        if (up === null || up.trashed || up.parentId !== ROOT_ID) continue;
+        if (await can(ctx, "read", node)) hits.push({ node, path: `/${names.reverse().join("/")}` });
+      }
+      return hits.sort((a, b) => a.path < b.path ? -1 : 1);
+    },
+    /**
+     * Puts a reference at `path` and gives `claim.subject` the role `claim.role` on it, as one step. If the
+     * grant fails (the caller is not an owner of the item, or the subject is invalid), the reference is
+     * deleted again and the error is thrown, so no half-made item stays. Needs `sharing`. Folders that
+     * `parents` made stay, `onConflict: "replace"` acts as `"fail"` (a rollback could not bring back a replaced item), and an invalid role or subject is refused before anything is written.
+     */
+    async claimRef(ctx, path, ref, claim, opts = {}) {
+      if (!sharing) throw new DriveError("INVALID_SHARE", "sharing is not set up");
+      if (!ctx.principal) throw new DriveError("FORBIDDEN", "sign in to share");
+      const subject = parseSubject(claim.subject);
+      if (!ROLES.includes(claim.role)) throw new DriveError("INVALID_SHARE", `a role is one of ${ROLES.join(", ")}`);
+      const node = await api.putRef(ctx, path, ref, opts);
+      try {
+        await viaSharing(ctx, (s, p) => s.grant(p, node.id, subject, claim.role));
+      } catch (error) {
+        let removed = 0;
+        let gone = false;
+        for (let i = 0; i < 3 && removed === 0 && !gone; i++) {
+          const current = await rawNode(store, node.id, node.owner, ctx.actor, true);
+          if (current === null) gone = true;
+          else removed = await removeNodes([current], void 0, ctx.principal).catch(() => 0);
+        }
+        if (removed === 0 && !gone) console.error(`claimRef could not remove ${node.id} after a failed share. Purge it.`);
+        throw error;
+      }
+      return node;
+    },
     /** 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)}`);
@@ -992,167 +1129,6 @@ function createDrive(deps) {
   return Object.fromEntries(Object.entries(api).map(([name, call]) => [name, open.has(name) ? call : guarded(call)]));
 }
 
-// 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/upload.ts
 var DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
 var SIGNATURES = [
@@ -1419,12 +1395,18 @@ function backfillResources(store, options = {}) {
 }
 
 // src/local.ts
-import { createHash as createHash2 } from "crypto";
-import { join as join2 } from "path";
+import { createHash } from "crypto";
+import { existsSync } from "fs";
+import { join } from "path";
 import { createSharing, isMachineMade, isScope, issueCredential, revokeCredential } from "agentic-identity";
-function openLocal(dir) {
-  const store = createFileStore(join2(dir, "db"));
-  return { store, drive: createDrive({ store, blobs: createFileBlobs(join2(dir, "blobs")), sharing: createSharing(store) }) };
+import { createFileBlobs, createFileStore } from "agentic-identity/file";
+function openLocal(dir, opts = {}) {
+  if (!opts.beforeImport && existsSync(join(dir, "db", "store.jsonl")) && !existsSync(join(dir, "store.json"))) {
+    throw new Error(`${dir} holds data from an older version. Run importLegacyLocal(dir, store, blobs) first: open it with openLocal(dir, { beforeImport: true }).`);
+  }
+  const store = createFileStore({ path: join(dir, "store.json") });
+  const blobs = createFileBlobs({ dir: join(dir, "blobs") });
+  return { store, blobs, drive: createDrive({ store, blobs, sharing: createSharing(store) }) };
 }
 async function ensureSharing(store) {
   if (await store.get("drive_meta", "sharing")) return;
@@ -1475,7 +1457,7 @@ async function issueKey(store, principalId, label) {
   return issueCredential(store, { principalId, kind: "api_key", ...label ? { label } : {} });
 }
 async function revokeKey(store, token) {
-  if (!await store.get("credentials", createHash2("sha256").update(token).digest("hex"))) throw new DriveError("NOT_FOUND", "no such key");
+  if (!await store.get("credentials", createHash("sha256").update(token).digest("hex"))) throw new DriveError("NOT_FOUND", "no such key");
   await revokeCredential(store, token, Date.now());
 }
 function publicNode(node, path) {
@@ -1487,6 +1469,7 @@ function publicNode(node, path) {
 export {
   ROOT_ID,
   ACTOR_KINDS,
+  ERROR_STATUS,
   DriveError,
   DEFAULT_URL_SECONDS,
   safeMime,
@@ -1494,8 +1477,6 @@ export {
   subjectKindOf,
   parseSubject,
   createDrive,
-  createFileStore,
-  createFileBlobs,
   DEFAULT_MAX_BYTES,
   sniffMime,
   upload,

package/dist/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import {
+  importLegacyLocal
+} from "./chunk-AB2RTTHJ.js";
 import {
   VERSION
-} from "./chunk-EFO5PSJL.js";
+} from "./chunk-6UQ6CDLJ.js";
 import {
   AuthError,
   DriveError,
@@ -17,7 +20,7 @@ import {
   revokeKey,
   revokePrincipal,
   upload
-} from "./chunk-PJQ3CRVL.js";
+} from "./chunk-R2DUVOJT.js";
 
 // src/cli.ts
 import { createReadStream, realpathSync, writeFileSync } from "fs";
@@ -38,13 +41,15 @@ Commands:
   download <remote> [out]      Save a file. Use "-" for stdout.
   mv <src> <folder>            Move an item. Use --name to rename it.
   rm <path|id>                 Move an item to the trash.
-  trash                        List the trash.
+  trash [--paths]              List the trash. With --paths, each item shows the path it had.
   restore <id>                 Put a trashed item back.
   purge <id>                   Delete a trashed item for good.
   search                       Find items. Flags: --name --mime --kind --min-size --max-size --created-by-kind --limit
   export <out.zip>             Write everything you own to a zip with a JSON manifest.
   home [--app <name>]          List files and app documents, newest change first.
   register <ref> <name>        Put an app document in the drive. Flag: --parent <folder>
+  find-ref <ref>               List the live items that point at an app document, with paths.
+  claim-ref <ref> <path> <subject>  Put a reference and give a role on it, or do neither. Flags: --role <r> --subject-kind <human|agent>
   forget <ref>                 Move the references to an app document to the trash.
   shares <path|id>             Show who can reach an item, and by which links and invites. Owner only.
   share <path|id> <subject>    Give a role to a person or agent. Flags: --role <r> --subject-kind <human|agent>
@@ -73,7 +78,7 @@ Flags:
 
 Exit codes: 0 done, 1 error, 2 bad usage, 3 no principal or an invalid key.
 `;
-var COMMANDS = ["ls", "stat", "mkdir", "upload", "download", "mv", "rm", "trash", "restore", "purge", "search", "export", "home", "register", "forget", "shares", "share", "unshare", "invite", "accept-invite", "link-create", "link-revoke", "delete-all", "mcp", "principal", "key"];
+var COMMANDS = ["ls", "stat", "mkdir", "upload", "download", "mv", "rm", "trash", "restore", "purge", "search", "export", "home", "register", "find-ref", "claim-ref", "forget", "shares", "share", "unshare", "invite", "accept-invite", "link-create", "link-revoke", "delete-all", "mcp", "principal", "key"];
 var UsageError = class extends Error {
 };
 var options = {
@@ -83,6 +88,7 @@ var options = {
   scope: { type: "string", multiple: true },
   label: { type: "string" },
   "on-conflict": { type: "string" },
+  paths: { type: "boolean" },
   parents: { type: "boolean", short: "p" },
   mime: { type: "string" },
   "max-bytes": { type: "string" },
@@ -136,7 +142,8 @@ async function runCli(argv, io) {
     const admin = command === "principal" || command === "key";
     const token = values.token ?? env.AGENTIC_DRIVE_TOKEN;
     if (!admin && !token) throw new AuthError(NO_TOKEN);
-    const { drive, store } = openLocal(dir);
+    const { drive, store, blobs } = openLocal(dir, { beforeImport: true });
+    await importLegacyLocal(dir, store, blobs);
     if (admin || command === "key") {
       const [sub, target] = args;
       const out = (value) => io.out(JSON.stringify(value));
@@ -195,7 +202,7 @@ async function runCli(argv, io) {
         print(publicNode(await drive.trash(ctx, args[0])));
         break;
       case "trash":
-        print((await drive.listTrash(ctx)).map((n) => publicNode(n)));
+        print(values.paths ? (await drive.listTrashWithPaths(ctx)).map((r) => publicNode(r.node, r.path)) : (await drive.listTrash(ctx)).map((n) => publicNode(n)));
         break;
       case "restore":
         need(1, "restore <id>");
@@ -232,6 +239,17 @@ async function runCli(argv, io) {
         need(2, "register <ref> <name>");
         print(publicNode(await drive.registerDocument(ctx, { ref: args[0], name: args[1], folder: values.parent })));
         break;
+      case "find-ref":
+        need(1, "find-ref <ref>");
+        print((await drive.findByRef(ctx, args[0])).map((r) => publicNode(r.node, r.path)));
+        break;
+      case "claim-ref":
+        need(3, "claim-ref <ref> <path> <subject> --role <r> --subject-kind <human|agent>");
+        print(publicNode(await drive.claimRef(ctx, args[1], args[0], {
+          subject: { kind: pick(values["subject-kind"], SUBJECT_KINDS, "subject-kind"), id: args[2] },
+          role: pick(values.role, ROLES, "role")
+        }, { parents: values.parents, onConflict })));
+        break;
       case "forget":
         need(1, "forget <ref>");
         print(await drive.forgetDocument(ctx, args[0]));

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { E as ErrorCode, N as Node, S as SearchQuery } from './drive-BtRyexUP.js';
+import { E as ErrorCode, N as Node, S as SearchQuery } from './drive-Dxy0gL0_.js';
 import 'agentic-identity';
 
 type Role = "viewer" | "commenter" | "editor" | "owner";
@@ -100,6 +100,19 @@ declare function createClient(options: ClientOptions): {
             app: string | null;
         })[];
     }>;
+    /** The live references to `ref`, with their paths. */
+    findByRef: (ref: string, o?: CallOptions) => Promise<PathItem[]>;
+    /** Items in the trash, newest first, each with the path it had before. */
+    listTrashWithPaths: (o?: CallOptions) => Promise<PathItem[]>;
+    /** Puts a reference and gives the subject a role on it, or does neither. Needs sharing. */
+    claimRef: (input: {
+        path: string;
+        ref: string;
+        subject: Subject;
+        role: Role;
+        parents?: boolean;
+        onConflict?: OnConflict;
+    }, o?: CallOptions) => Promise<Item>;
     registerDocument: (input: {
         ref: string;
         name: string;
@@ -173,4 +186,4 @@ declare function createClient(options: ClientOptions): {
 };
 type DriveClient = ReturnType<typeof createClient>;
 
-export { type ApiErrorCode, type CallOptions, type ClientErrorCode, type ClientOptions, type Downloaded, DriveApiError, type DriveClient, type Item, type OnConflict, type PathItem, type Role, type Subject, type SubjectKind, type UploadBody, createClient };
+export { type ApiErrorCode, type CallOptions, type ClientErrorCode, type ClientOptions, type Downloaded, DriveApiError, type DriveClient, ErrorCode, type Item, Node, type OnConflict, type PathItem, type Role, type Subject, type SubjectKind, type UploadBody, createClient };

package/dist/client.js

@@ -1,7 +1,7 @@
 import {
   DriveApiError,
   createClient
-} from "./chunk-S4AGCKXW.js";
+} from "./chunk-LELTSSZF.js";
 export {
   DriveApiError,
   createClient