frontier-mcp 0.1.0 → 0.2.0

package/dist/storage/markdown/create.js

@@ -34,8 +34,8 @@ const CANDIDATE_HEADROOM = 1000;
  * write X. See ADR 0005.
  */
 export async function createTicketFiles(request) {
-    const { scratch, effort, dir, issues, drafts, rescan, validate, createEffort } = request;
-    const { reservations, tickets } = await reserve(scratch, drafts.length, rescan);
+    const { storage, effort, dir, issues, drafts, rescan, validate, createEffort } = request;
+    const { reservations, tickets } = await reserve(storage, drafts.length, rescan);
     try {
         const ids = reservations.map(entry => entry.id);
         // The last rule that can only be checked now: the ids are real, and nothing
@@ -65,10 +65,10 @@ export async function createTicketFiles(request) {
  * Hold exclusive id guards for `count` fresh ids, run `use`, then release.
  * Migration mints through this so a parallel create_tickets cannot collide.
  */
-export async function withIdReservations(scratch, count, rescan, use) {
+export async function withIdReservations(storage, count, rescan, use) {
     if (count === 0)
         return use([]);
-    const { reservations } = await reserve(scratch, count, rescan);
+    const { reservations } = await reserve(storage, count, rescan);
     try {
         return await use(reservations.map(entry => entry.id));
     }
@@ -172,9 +172,9 @@ async function writeAll(issues, files) {
         throw lost.reason;
     }
 }
-async function reserve(scratch, count, rescan, attempt = 1) {
+async function reserve(storage, count, rescan, attempt = 1) {
     const used = idsOf(await rescan());
-    const reservations = await claim(scratch, used, count, highestMinted(used) + 1, []);
+    const reservations = await claim(storage, used, count, highestMinted(used) + 1, []);
     let settled;
     try {
         settled = await rescan();
@@ -192,7 +192,7 @@ async function reserve(scratch, count, rescan, attempt = 1) {
         throw new Error(`Could not reserve ${String(count)} Ticket ids after ${String(MAX_ATTEMPTS)} attempts — ` +
             'another session is creating Tickets continuously. Retry in a moment.');
     }
-    return reserve(scratch, count, rescan, attempt + 1);
+    return reserve(storage, count, rescan, attempt + 1);
 }
 function release(reservations) {
     return Promise.allSettled(reservations.map(entry => unlink(entry.guard).catch(() => { })));
@@ -202,23 +202,23 @@ function release(reservations) {
  * each attempt depends on the one before it, and a bumped candidate is the
  * normal case rather than an error.
  */
-async function claim(scratch, used, count, candidate, taken) {
+async function claim(storage, used, count, candidate, taken) {
     if (taken.length === count)
         return taken;
     if (candidate > highestMinted(used) + CANDIDATE_HEADROOM + count) {
         await release(taken);
         throw new Error(`No free Ticket id within ${String(CANDIDATE_HEADROOM)} of the highest in use. ` +
-            'Sweep the abandoned .frontier-id-*.guard files under .scratch/.');
+            `Sweep the abandoned .frontier-id-*.guard files under ${storage}.`);
     }
     const id = `T${String(candidate)}`;
     if (used.has(id))
-        return claim(scratch, used, count, candidate + 1, taken);
-    const guard = guardFor(scratch, id);
+        return claim(storage, used, count, candidate + 1, taken);
+    const guard = guardFor(storage, id);
     // A guard we cannot take belongs to a session that is still allocating. Bump
     // rather than wait: an id may be skipped, never reused.
     if (!(await hold(guard)))
-        return claim(scratch, used, count, candidate + 1, taken);
-    return claim(scratch, used, count, candidate + 1, [...taken, { id, guard }]);
+        return claim(storage, used, count, candidate + 1, taken);
+    return claim(storage, used, count, candidate + 1, [...taken, { id, guard }]);
 }
 /**
  * Take a guard, or report that somebody else has it.
@@ -251,11 +251,11 @@ async function hold(guard) {
 /**
  * Beside the Efforts rather than inside one, because the counter is repo-global:
  * two sessions creating into different Efforts must still collide here. Hidden
- * and not `.md`, so no scan mistakes it for a Ticket, and `.scratch/` yields it
- * no Effort because it is not a directory.
+ * and not `.md`, so no scan mistakes it for a Ticket, and the storage scan
+ * yields it no Effort because it is not a directory.
  */
-function guardFor(scratch, id) {
-    return join(scratch, `.frontier-id-${id}.guard`);
+function guardFor(storage, id) {
+    return join(storage, `.frontier-id-${id}.guard`);
 }
 function idsOf(tickets) {
     return new Set(tickets.map(entry => entry.id).filter(id => id !== undefined));

package/dist/storage/markdown/create.js.map

@@ -1 +1 @@
-{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/storage/markdown/create.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/storage/markdown/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;GAIG;AACH,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,IAAI,CAAC;AA6BhC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAsB;IAC5D,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IACzF,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChD,4EAA4E;QAC5E,yEAAyE;QACzE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAEvB,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;QAErD,6EAA6E;QAC7E,0EAA0E;QAC1E,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,YAAY;gBAAE,MAAM,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACnD,MAAM,KAAK,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;YAAS,CAAC;QACT,6EAA6E;QAC7E,0EAA0E;QAC1E,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAe,EACf,KAAa,EACb,MAAc,EACd,GAA2C;IAE3C,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/D,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAyB,EAAE,KAAa;IACpE,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAExC,OAAO,GAAG,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;QAC1B,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChC,SAAS,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,EAAU,EAAE,KAAa;IACrE,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,MAAc;IACtD,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACpC,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AACnC,CAAC;AAOD;;;;GAIG;AACH,SAAS,QAAQ,CACf,MAAc,EACd,MAA8B,EAC9B,GAAsB,EACtB,OAAiC;IAEjC,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACjC,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;QACtB,IAAI,EAAE,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAE9F,MAAM,QAAQ,GAAG,YAAY,CAC3B;YACE,EAAE;YACF,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;SACxC,EACD,KAAK,CAAC,IAAI,CACX,CAAC;QAEF,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,UAAU,GAAG,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrF,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,QAAQ,CAAC,MAAc,EAAE,KAAyB;IAC/D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CACrC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAC,IAAI,EAAC,EAAE,CAAC,CAAC;QACvB,SAAS,EAAE,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC;QAClE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC;KACpC,CAAC,CAAC,CACJ,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7F,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;IACjE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACvE,MAAM,MAAM,CAAC,MAAe,CAAC;IAC/B,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CACtC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAC,KAAK,EAAC,EAAE;QACtB,0EAA0E;QAC1E,0EAA0E;QAC1E,2EAA2E;QAC3E,qEAAqE;QACrE,WAAW;QACX,MAAM,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5C,OAAO,KAAK,CAAC,MAAM,CAAC;IACtB,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;IAChE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,OAAO,CAAC,UAAU,CAAC;YACvB,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACnD,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;SAChD,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,MAAe,CAAC;IAC7B,CAAC;AACH,CAAC;AAQD,KAAK,UAAU,OAAO,CACpB,OAAe,EACf,KAAa,EACb,MAAc,EACd,OAAO,GAAG,CAAC;IAEX,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC;IACnC,MAAM,YAAY,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAEpF,IAAI,OAAiC,CAAC;IACtC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,MAAM,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;QAC5B,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IACpE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAEtE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5B,IAAI,OAAO,IAAI,YAAY,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,qBAAqB,MAAM,CAAC,KAAK,CAAC,qBAAqB,MAAM,CAAC,YAAY,CAAC,cAAc;YACvF,sEAAsE,CACzE,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,OAAO,CAAC,YAAoC;IACnD,OAAO,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5F,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,KAAK,CAClB,OAAe,EACf,IAAyB,EACzB,KAAa,EACb,SAAiB,EACjB,KAA6B;IAE7B,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzC,IAAI,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,kBAAkB,GAAG,KAAK,EAAE,CAAC;QACjE,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,4BAA4B,MAAM,CAAC,kBAAkB,CAAC,0BAA0B;YAC9E,wDAAwD,OAAO,GAAG,CACrE,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAE3E,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACpC,6EAA6E;IAC7E,wDAAwD;IACxD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAEnF,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,KAAK,UAAU,IAAI,CAAC,KAAa;IAC/B,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,KAAK,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAAsC,EAAE,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;QAC5E,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,OAAe,EAAE,EAAU;IAC3C,OAAO,IAAI,CAAC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,KAAK,CAAC,OAAiC;IAC9C,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,IAAyB;IAC9C,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACvC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,qFAAqF;AACrF,SAAS,SAAS,CAAC,OAAiC,EAAE,MAAc;IAClE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1F,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,GAAG,CAAC,KAAa;IACxB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,KAAa;IAC5B,MAAM,IAAI,GAAG,KAAK;SACf,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;SACZ,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAEtB,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC"}

package/dist/storage/markdown/driver.d.ts

@@ -1,7 +1,41 @@
 import type { StorageDriver } from '../driver.ts';
+export interface MarkdownDriverOptions {
+    /**
+     * The directory under `root` this driver keeps its Efforts in, relative to
+     * the workspace root and one segment deep. Defaults to `.scratch`.
+     *
+     * It is a parameter rather than a constant because it is this driver's answer
+     * to "what do you call your storage", which the seam exists to keep from
+     * being everybody's.
+     */
+    readonly storageDir?: string;
+    /** Debounce filesystem watcher events before dropping the scan. */
+    readonly watcherDebounceMs?: number;
+    /**
+     * When the watcher drops the scan unconditionally after attaching, to cover
+     * the events an `fs.watch` loses while it is still warming up — see
+     * {@link watchStorage}. It exists so a test can pin those moments and assert
+     * on them; the default schedule is the right one for real use.
+     */
+    readonly watcherSettleMs?: readonly number[];
+}
 /**
  * The markdown driver — the only driver in v1. Bound to `root`, the resolved
  * workspace, so that no path crosses the {@link StorageDriver} interface.
+ *
+ * It is the workspace *cached and live*: it holds the scan a Board is built
+ * from, drops it when it writes, and watches the storage directory so a change
+ * another process made drops it too. Both are markdown policy — a full scan is
+ * cheap enough to cache wholesale, and `node:fs.watch` is how this physical
+ * model learns it moved. A driver over a database would cache and notice
+ * neither the same way, which is why nothing above the seam does it for them.
+ * "Live" arrives slightly after construction, though: a watch is not delivering
+ * events the instant it is created, and what it misses in that window is gone
+ * rather than delayed, so the driver drops its scan a few times while the watch
+ * warms.
+ *
+ * Close it to stop the watcher; a process that keeps a workspace open forever
+ * never needs to.
  */
-export declare function createMarkdownDriver(root: string): StorageDriver;
+export declare function createMarkdownDriver(root: string, { storageDir, watcherDebounceMs, watcherSettleMs, }?: MarkdownDriverOptions): StorageDriver;
 //# sourceMappingURL=driver.d.ts.map

package/dist/storage/markdown/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../src/storage/markdown/driver.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAGV,aAAa,EAEd,MAAM,cAAc,CAAC;AAsCtB;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAsFhE"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../src/storage/markdown/driver.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAGV,aAAa,EAEd,MAAM,cAAc,CAAC;AAwCtB,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,EACE,UAAgC,EAChC,iBAAiB,EACjB,eAAe,GAChB,GAAE,qBAA0B,GAC5B,aAAa,CA+Hf"}

package/dist/storage/markdown/driver.js

@@ -6,11 +6,13 @@ import { migrateEffortFiles } from './migrate.js';
 import { applyEdit } from './serialize.js';
 import { currentRevision, GuardHeld, withGuard, writeAtomically } from './write.js';
 import { applyMapEdit, readMapDocument, readSection, readSpecOpening, scaffoldMap, SECTION_HEADINGS, } from './header-doc.js';
-import { parseTicket } from './ticket.js';
+import { parseTicketSummary, ticketBody } from './ticket.js';
+import { watchStorage } from './watcher.js';
 /**
- * The layout this driver serves, per AGENTS.md:
+ * The layout this driver serves, per AGENTS.md, under the storage directory it
+ * was constructed with:
  *
- *   .scratch/<effort>/
+ *   <storage>/<effort>/
  *   ├── map.md            # Header doc — wayfinder
  *   ├── spec.md           # Header doc — to-spec
  *   └── issues/
@@ -18,7 +20,7 @@ import { parseTicket } from './ticket.js';
  *
  * Anything else in an Effort directory is ignored, never an error.
  */
-const SCRATCH_DIR = '.scratch';
+const DEFAULT_STORAGE_DIR = '.scratch';
 const ISSUES_DIR = 'issues';
 const MAP_FILE = 'map.md';
 const SPEC_FILE = 'spec.md';
@@ -29,65 +31,112 @@ const HEADER_DOCS = [
 /**
  * The markdown driver — the only driver in v1. Bound to `root`, the resolved
  * workspace, so that no path crosses the {@link StorageDriver} interface.
+ *
+ * It is the workspace *cached and live*: it holds the scan a Board is built
+ * from, drops it when it writes, and watches the storage directory so a change
+ * another process made drops it too. Both are markdown policy — a full scan is
+ * cheap enough to cache wholesale, and `node:fs.watch` is how this physical
+ * model learns it moved. A driver over a database would cache and notice
+ * neither the same way, which is why nothing above the seam does it for them.
+ * "Live" arrives slightly after construction, though: a watch is not delivering
+ * events the instant it is created, and what it misses in that window is gone
+ * rather than delayed, so the driver drops its scan a few times while the watch
+ * warms.
+ *
+ * Close it to stop the watcher; a process that keeps a workspace open forever
+ * never needs to.
  */
-export function createMarkdownDriver(root) {
-    const scratch = join(root, SCRATCH_DIR);
+export function createMarkdownDriver(root, { storageDir = DEFAULT_STORAGE_DIR, watcherDebounceMs, watcherSettleMs, } = {}) {
+    const storage = join(root, storageDir);
     let writes = Promise.resolve();
     const walk = async () => {
         // A repo that has never used the tracker is a supported starting state,
         // not an error: it simply holds no Efforts.
-        const slugs = await readDirectories(scratch);
-        const scanned = await Promise.all(slugs.map(slug => readEffort(scratch, slug)));
+        const slugs = await readDirectories(storage);
+        const scanned = await Promise.all(slugs.map(slug => readEffort(storage, slug)));
         return scanned
             .filter((entry) => entry !== undefined)
             .toSorted((a, b) => a.effort.slug.localeCompare(b.effort.slug));
     };
     /**
-     * Both methods are always called together to build one index, and each walk
-     * reads every `issues/` directory. Sharing the in-flight walk makes that one
-     * pass instead of two.
+     * Hold the in-flight walk, not just its result, so concurrent callers share
+     * one scan instead of racing several. A failed scan is never cached as the
+     * answer.
      *
-     * The share lasts only as long as the walk itself — the driver holds no
-     * results, because deciding when a scan is stale belongs to the index above
-     * it and to the watcher T8 attaches there.
+     * The whole scan is one cache rather than one per method: `listEfforts` and
+     * `listTickets` are two readings of a single walk, and every caller that
+     * wants a Board wants both.
      */
-    let inFlight;
+    let cachedScan;
     const scan = () => {
-        inFlight ??= walk().finally(() => {
-            inFlight = undefined;
+        cachedScan ??= walk().catch((error) => {
+            cachedScan = undefined;
+            throw error;
         });
-        return inFlight;
+        return cachedScan;
     };
+    /** Drop the scan, so the next read rebuilds from disk. */
+    const invalidate = () => {
+        cachedScan = undefined;
+    };
+    /**
+     * A write moves the workspace on whether or not it succeeded partway, so the
+     * next read rebuilds rather than trusting a scan taken before it.
+     */
+    const moved = async (operation) => {
+        try {
+            return await operation();
+        }
+        finally {
+            invalidate();
+        }
+    };
+    const watcher = watchStorage(root, storageDir, invalidate, {
+        debounceMs: watcherDebounceMs,
+        settleMs: watcherSettleMs,
+    });
     return {
         async listEfforts() {
             return (await scan()).map(entry => entry.effort);
         },
         async listTickets() {
-            return (await scan()).flatMap(entry => entry.tickets);
+            return (await scan()).flatMap(entry => summariesOf(entry));
+        },
+        async readTickets(handles) {
+            // Deliberately the fresh walk rather than the cached one. A body is read
+            // for the few Tickets being worked, and reading it against a scan taken
+            // before another process wrote is exactly the staleness `get_tickets`
+            // exists not to serve. It costs a walk a concurrent Board would have
+            // shared — the price of an answer nothing can have staled underneath it.
+            return readBodies(storage, await walk(), handles);
         },
         updateTicket(handle, edit, expectedRevision) {
-            return serialized(() => write(scratch, handle, edit, expectedRevision));
+            return moved(() => serialized(() => write(storage, handle, edit, expectedRevision)));
         },
         createTickets(effort, drafts, options) {
-            // The scan is deliberately not the shared one: allocation re-reads under
-            // its own guards, and an in-flight walk started before them would defeat
-            // the check it exists to make.
-            return serialized(() => create(scratch, effort, drafts, options, walk));
+            // The scan is deliberately not the cached one: allocation re-reads under
+            // its own guards, and a walk started before them would defeat the check
+            // it exists to make.
+            return moved(() => serialized(() => create(storage, effort, drafts, options, walk)));
         },
         readMap(effort) {
-            return serialized(() => loadMap(scratch, effort));
+            return serialized(() => loadMap(storage, effort));
         },
         editMap(effort, edit, expectedRevision, options) {
-            return serialized(() => saveMap(scratch, effort, edit, expectedRevision, options));
+            return moved(() => serialized(() => saveMap(storage, effort, edit, expectedRevision, options)));
         },
         readSpec(effort) {
-            return serialized(() => loadSpec(scratch, effort));
+            return serialized(() => loadSpec(storage, effort));
         },
         putSpec(effort, body, expectedRevision, options) {
-            return serialized(() => saveSpec(scratch, effort, body, expectedRevision, options));
+            return moved(() => serialized(() => saveSpec(storage, effort, body, expectedRevision, options)));
         },
         migrateEffort(effort, options) {
-            return serialized(() => migrate(scratch, effort, options, walk));
+            return moved(() => serialized(() => migrate(storage, effort, options, walk)));
+        },
+        close() {
+            watcher.close();
+            invalidate();
         },
     };
     /**
@@ -104,15 +153,15 @@ export function createMarkdownDriver(root) {
         return next;
     }
 }
-async function migrate(scratch, effort, options, walk) {
-    const dir = join(scratch, effort);
-    if ((await readEffort(scratch, effort)) === undefined)
+async function migrate(storage, effort, options, walk) {
+    const dir = join(storage, effort);
+    if ((await readEffort(storage, effort)) === undefined)
         throw new NoSuchEffort(effort);
     const entries = await readTicketFiles(dir, effort);
-    const allTickets = (await walk()).flatMap(entry => entry.tickets);
+    const allTickets = (await walk()).flatMap(summariesOf);
     const issues = join(dir, ISSUES_DIR);
     return migrateEffortFiles({
-        scratch,
+        storage,
         effort,
         issues,
         entries,
@@ -121,24 +170,24 @@ async function migrate(scratch, effort, options, walk) {
         rename: options.rename,
         // Allocation must not share a walk started before the guards — same reason
         // createTickets builds its own rescan.
-        rescan: async () => (await walk()).flatMap(entry => entry.tickets),
+        rescan: async () => (await walk()).flatMap(summariesOf),
         readContents: filename => readFile(join(issues, filename), 'utf8'),
     });
 }
-async function create(scratch, effort, drafts, options, walk) {
-    const dir = join(scratch, effort);
-    const missing = (await readEffort(scratch, effort)) === undefined;
+async function create(storage, effort, drafts, options, walk) {
+    const dir = join(storage, effort);
+    const missing = (await readEffort(storage, effort)) === undefined;
     if (missing && !options.createEffort)
         throw new NoSuchEffort(effort);
     // The directory is made inside, after validation — an Effort created here and
     // then refused would show up in list_efforts as an empty one nobody asked for.
     const filenames = await createTicketFiles({
-        scratch,
+        storage,
         effort,
         dir,
         issues: join(dir, ISSUES_DIR),
         drafts,
-        rescan: async () => (await walk()).flatMap(entry => entry.tickets),
+        rescan: async () => (await walk()).flatMap(summariesOf),
         validate: options.validate ?? (() => { }),
         createEffort: missing,
     });
@@ -151,8 +200,8 @@ async function create(scratch, effort, drafts, options, walk) {
         return ticket;
     });
 }
-async function write(scratch, handle, edit, expectedRevision) {
-    const located = await locate(scratch, handle);
+async function write(storage, handle, edit, expectedRevision) {
+    const located = await locate(storage, handle);
     if (located === undefined)
         throw new NoSuchTicket(handle);
     const { dir, effort, filename, ticket } = located;
@@ -190,7 +239,7 @@ async function write(scratch, handle, edit, expectedRevision) {
     const warnings = [];
     if (edit.status === 'resolved' || edit.status === 'dropped') {
         try {
-            await refreshMapDerived(scratch, effort);
+            await refreshMapDerived(storage, effort);
         }
         catch {
             warnings.push('Decisions-so-far / dropped Out-of-scope may be stale — Map derived refresh failed after the Ticket write.');
@@ -198,15 +247,15 @@ async function write(scratch, handle, edit, expectedRevision) {
     }
     return { ticket: written, warnings };
 }
-async function loadMap(scratch, effort) {
-    const path = join(scratch, effort, MAP_FILE);
+async function loadMap(storage, effort) {
+    const path = join(storage, effort, MAP_FILE);
     const revision = await currentRevision(path);
     if (revision === undefined)
         throw new NoSuchMap(effort);
     return readMapDocument(await readFile(path, 'utf8'), revision);
 }
-async function saveMap(scratch, effort, edit, expectedRevision, options) {
-    const dir = join(scratch, effort);
+async function saveMap(storage, effort, edit, expectedRevision, options) {
+    const dir = join(storage, effort);
     const path = join(dir, MAP_FILE);
     const current = await currentRevision(path);
     const handle = `map:${effort}`;
@@ -214,7 +263,7 @@ async function saveMap(scratch, effort, edit, expectedRevision, options) {
         // createEffort only guards starting a new Effort. An Effort that already
         // holds a Spec or issues/ must be able to gain a Map without that flag —
         // that is wayfinder's handoff, not a mistyped slug.
-        if ((await readEffort(scratch, effort)) === undefined && !options.createEffort) {
+        if ((await readEffort(storage, effort)) === undefined && !options.createEffort) {
             throw new NoSuchEffort(effort);
         }
         await mkdir(join(dir, ISSUES_DIR), { recursive: true });
@@ -247,16 +296,16 @@ const DERIVED_REFRESH_ATTEMPTS = 16;
  * Invents the GENERATED-bearing headings when absent so a slim Map still gets
  * a truthful Decisions / Out-of-scope cache after resolve or drop.
  */
-async function refreshMapDerived(scratch, effort) {
-    return refreshMapDerivedOnce(scratch, effort, DERIVED_REFRESH_ATTEMPTS);
+async function refreshMapDerived(storage, effort) {
+    return refreshMapDerivedOnce(storage, effort, DERIVED_REFRESH_ATTEMPTS);
 }
-async function refreshMapDerivedOnce(scratch, effort, remaining) {
-    const path = join(scratch, effort, MAP_FILE);
+async function refreshMapDerivedOnce(storage, effort, remaining) {
+    const path = join(storage, effort, MAP_FILE);
     const revision = await currentRevision(path);
     if (revision === undefined)
         return;
     const contents = await readFile(path, 'utf8');
-    const entries = await readTicketFiles(join(scratch, effort), effort);
+    const entries = await readTicketFiles(join(storage, effort), effort);
     const updated = applyMapEdit(contents, {}, ticketPointers(entries, 'resolved'), ticketPointers(entries, 'dropped'), { ensureDerivedSections: true });
     if (updated === contents)
         return;
@@ -276,7 +325,7 @@ async function refreshMapDerivedOnce(scratch, effort, remaining) {
             throw new Error(`Could not refresh Map derived blocks for ${effort} after concurrent edits.`, { cause: error });
         }
         await new Promise(wait => setTimeout(wait, 10));
-        return refreshMapDerivedOnce(scratch, effort, remaining - 1);
+        return refreshMapDerivedOnce(storage, effort, remaining - 1);
     }
 }
 /** Internal signal: another writer changed the Map while we held its guard. */
@@ -286,15 +335,15 @@ class DerivedRefreshLost extends Error {
         this.name = 'DerivedRefreshLost';
     }
 }
-async function loadSpec(scratch, effort) {
-    const path = join(scratch, effort, SPEC_FILE);
+async function loadSpec(storage, effort) {
+    const path = join(storage, effort, SPEC_FILE);
     const revision = await currentRevision(path);
     if (revision === undefined)
         throw new NoSuchSpec(effort);
     return { body: await readFile(path, 'utf8'), revision };
 }
-async function saveSpec(scratch, effort, body, expectedRevision, options) {
-    const dir = join(scratch, effort);
+async function saveSpec(storage, effort, body, expectedRevision, options) {
+    const dir = join(storage, effort);
     const path = join(dir, SPEC_FILE);
     const current = await currentRevision(path);
     const handle = `spec:${effort}`;
@@ -303,7 +352,7 @@ async function saveSpec(scratch, effort, body, expectedRevision, options) {
     if (current === undefined) {
         // Same rule as Maps: createEffort starts an Effort; putting a Spec onto an
         // Effort that already has a Map needs no flag.
-        if ((await readEffort(scratch, effort)) === undefined && !options.createEffort) {
+        if ((await readEffort(storage, effort)) === undefined && !options.createEffort) {
             throw new NoSuchEffort(effort);
         }
         await mkdir(join(dir, ISSUES_DIR), { recursive: true });
@@ -354,14 +403,14 @@ function ticketPointers(entries, status) {
     });
 }
 /** Find the file backing a Ticket, by id or by its `<effort>#<order>` handle. */
-async function locate(scratch, handle) {
-    const slugs = await readDirectories(scratch);
-    const perEffort = await Promise.all(slugs.map(async (slug) => ({ slug, entries: await readTicketFiles(join(scratch, slug), slug) })));
+async function locate(storage, handle) {
+    const slugs = await readDirectories(storage);
+    const perEffort = await Promise.all(slugs.map(async (slug) => ({ slug, entries: await readTicketFiles(join(storage, slug), slug) })));
     for (const { slug, entries } of perEffort) {
         const found = entries.find(entry => entry.ticket.id === handle || entry.ticket.handle === handle);
         if (found !== undefined) {
             return {
-                dir: join(scratch, slug),
+                dir: join(storage, slug),
                 effort: slug,
                 filename: found.filename,
                 ticket: found.ticket,
@@ -381,10 +430,36 @@ function defaultsFor(ticket) {
         blockedBy: ticket.blockedBy,
     };
 }
+/** The Tickets of one scanned Effort, without the files behind them. */
+function summariesOf(scanned) {
+    return scanned.entries.map(entry => entry.ticket);
+}
 /**
- * Every Ticket in one Effort with the file behind it, in sort order. Paths never
- * cross the driver interface, so this pairing stays inside the driver — it is
- * how a write finds the file a Ticket came from.
+ * The named Tickets with their prose, read from disk now. The scan located the
+ * files; their bodies are read here rather than carried by every scan, so the
+ * cost is paid per Ticket worked instead of per Ticket in the workspace.
+ *
+ * A name matching nothing yields nothing — naming what was missing belongs to
+ * the caller, which is the only side that knows what it asked for.
+ */
+async function readBodies(storage, scanned, handles) {
+    const wanted = new Set(handles);
+    const found = scanned.flatMap(entry => entry.entries
+        .filter(({ ticket }) => wanted.has(ticket.handle) || (ticket.id !== undefined && wanted.has(ticket.id)))
+        .map(({ filename, ticket }) => ({
+        ticket,
+        path: join(storage, entry.effort.slug, ISSUES_DIR, filename),
+    })));
+    return Promise.all(found.map(async ({ ticket, path }) => withBody(ticket, ticketBody(await readText(path)))));
+}
+function withBody(ticket, body) {
+    return { ...ticket, body };
+}
+/**
+ * Every Ticket in one Effort with the file behind it, in sort order, each read
+ * for its fields and not for its prose. Paths never cross the driver interface,
+ * so this pairing stays inside the driver — it is how a write finds the file a
+ * Ticket came from, and how a body fetch finds the one it must open.
  */
 async function readTicketFiles(dir, effort) {
     const issues = join(dir, ISSUES_DIR);
@@ -403,15 +478,11 @@ async function readTicketFiles(dir, effort) {
         // sorted listing is the only order it has.
         return {
             filename,
-            ticket: parseTicket(effort, { filename, contents }, position + 1, revision ?? ''),
+            ticket: parseTicketSummary(effort, { filename, contents }, position + 1, revision ?? ''),
         };
     }));
     return withUniqueHandles(parsed.toSorted((a, b) => a.ticket.order - b.ticket.order));
 }
-/** Every Ticket in one Effort, in sort order. A missing `issues/` yields none. */
-async function readTickets(dir, effort) {
-    return (await readTicketFiles(dir, effort)).map(entry => entry.ticket);
-}
 /**
  * Two files can share an `NN-` prefix, which would give two id-less Tickets the
  * same `<effort>#<order>` handle and make one of them unfetchable. Later
@@ -434,29 +505,29 @@ function withUniqueHandles(entries) {
     });
 }
 /**
- * A directory under `.scratch/` is an Effort only once it holds something the
- * schema recognizes — a Header doc or an `issues/` directory. `.scratch/` is
- * also where these repos keep loose scratch output, and a directory of research
- * notes is not an empty Effort.
+ * A directory under the storage directory is an Effort only once it holds
+ * something the schema recognizes — a Header doc or an `issues/` directory.
+ * That directory is also where these repos keep loose scratch output, and a
+ * directory of research notes is not an empty Effort.
  */
-async function readEffort(scratch, slug) {
-    const dir = join(scratch, slug);
-    const entries = await readDir(dir);
-    const files = new Set(entries.filter(entry => entry.isFile()).map(entry => entry.name));
+async function readEffort(storage, slug) {
+    const dir = join(storage, slug);
+    const listing = await readDir(dir);
+    const files = new Set(listing.filter(entry => entry.isFile()).map(entry => entry.name));
     const headerDocs = HEADER_DOCS.filter(([, filename]) => files.has(filename)).map(([doc]) => doc);
-    const hasIssues = entries.some(entry => entry.isDirectory() && entry.name === ISSUES_DIR);
+    const hasIssues = listing.some(entry => entry.isDirectory() && entry.name === ISSUES_DIR);
     if (headerDocs.length === 0 && !hasIssues)
         return undefined;
-    const [tickets, destination, specOpening] = await Promise.all([
-        readTickets(dir, slug),
+    const [entries, destination, specOpening] = await Promise.all([
+        readTicketFiles(dir, slug),
         headerDocs.includes('map')
             ? readText(join(dir, 'map.md')).then(contents => readSection(contents, SECTION_HEADINGS.destination))
             : undefined,
         headerDocs.includes('spec') ? readText(join(dir, 'spec.md')).then(readSpecOpening) : undefined,
     ]);
     return {
-        effort: { slug, headerDocs, ticketCount: tickets.length, destination, specOpening },
-        tickets,
+        effort: { slug, headerDocs, ticketCount: entries.length, destination, specOpening },
+        entries,
     };
 }
 /** A file that vanished between the scan and the read is read as empty, not as a failure. */