@ccmsg/cli 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",
@@ -20,7 +20,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ccmsg/protocol": "1.13.0"
+    "@ccmsg/protocol": "1.14.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/sessions/items.ts

@@ -69,37 +69,69 @@ export function itemsRead(
   }
   const keep = selection(args.types === undefined ? {} : { types: args.types }, deps.presets);
   const { items } = select(within(classify(located(text)), args), keep);
-  const page = paged(items, args.limit);
+  const page = paged(items, args.limit, backwards(args));
   return {
     items: page.items,
     ...(page.next === undefined ? {} : { next: page.next }),
+    ...(page.prev === undefined ? {} : { prev: page.prev }),
     ...(keep.keeps(IDS) ? { ids: ledger(page.items) } : {}),
   };
 }
 
+/** Whether the range's end is the part to answer with.
+ *
+ * A caller that named where to start is reading forward from there; one that
+ * named only where to stop is looking at the newest of what it asked for, and
+ * answering with the oldest of that range would hand it the far side of a
+ * transcript it is walking back through. With neither bound the range is the
+ * whole transcript, which is read from its beginning. */
+function backwards(bounds: TranscriptItemsReadArgs): boolean {
+  const lower =
+    bounds.since_at !== undefined ||
+    bounds.since_uuid !== undefined ||
+    bounds.since_id !== undefined;
+  const upper =
+    bounds.until_at !== undefined ||
+    bounds.until_uuid !== undefined ||
+    bounds.until_id !== undefined;
+  return upper && !lower;
+}
+
 /** As much of the range as one answer carries, and where the next one starts.
  *
  * Two bounds, because either alone leaves a case unanswered: a count cannot
  * keep a page of long briefs inside what a connection should carry, and bytes
  * alone would answer with a number of items that varied with what was said in
- * them. Whichever is reached first ends the page, and the first item left out
- * is named so the caller resumes exactly where this stopped. */
+ * them. Whichever is reached first ends the page.
+ *
+ * Which end of the range is kept is the caller's, and the item named back is
+ * the one it continues from: reading forward, the first item left out, to be
+ * given as `since_id`; reading back, the first item answered, to be given as
+ * `until_id`. Either way the answer is oldest first, because that is the order
+ * a transcript has. */
 function paged(
   items: readonly Item[],
   limit: number | undefined,
-): { items: Item[]; next?: string } {
+  back: boolean,
+): { items: Item[]; next?: string; prev?: string } {
   const most = Math.min(limit ?? ITEMS_LIMIT, ITEMS_LIMIT);
   const kept: Item[] = [];
   let held = 0;
-  for (const item of items) {
+  for (let at = 0; at < items.length; at += 1) {
+    const item = items[back ? items.length - 1 - at : at];
+    if (item === undefined) continue;
     // A first item larger than the whole budget is still answered: a page of
     // nothing would leave the caller resuming at the item it just failed to
     // get, forever.
     if (kept.length > 0 && (kept.length >= most || held >= READ_LIMIT)) {
-      return { items: kept, next: item.id };
+      if (!back) return { items: kept, next: item.id };
+      kept.reverse();
+      const first = kept[0];
+      return first === undefined ? { items: kept } : { items: kept, prev: first.id };
     }
     kept.push(item);
     held += JSON.stringify(item).length;
   }
+  if (back) kept.reverse();
   return { items: kept };
 }

package/src/transcript/index.ts

@@ -13,4 +13,4 @@ export {
 } from "./fold.ts";
 export { READ_LIMIT, readSlice } from "./read.ts";
 export { type Appended, FOLD_TAIL_BYTES, TranscriptTail } from "./tail.ts";
-export { Transcripts, type TranscriptsDeps } from "./transcripts.ts";
+export { ITEMS_SNAPSHOT, Transcripts, type TranscriptsDeps } from "./transcripts.ts";

package/src/transcript/items/classify.ts

@@ -135,8 +135,12 @@ export class Classification {
   read(record: Row, source: { offset: number; bytes: number }): void {
     const type = str(record["type"]);
     if (type === undefined || NOT_ITEMS.has(type)) return;
-    const uuid = str(record["uuid"]) ?? "";
-    if (uuid === "") return;
+    // A record the harness wrote without an id of its own still happened, and
+    // an item is pointed at by the record it came from — so where the record
+    // stands in the file stands in for the id it lacks. The `@` says which of
+    // the two it is, since a reader that groups by record must not take an
+    // address for something the harness will write again.
+    const uuid = str(record["uuid"]) ?? `@${String(source.offset)}`;
     const at = instant(record["timestamp"]);
     // Where in its record an item stood. One record becomes the thinking, the
     // words and each call of a turn, and a link that named only the record

package/src/transcript/items/select.ts

@@ -149,13 +149,16 @@ export function select(
  * A record bound cuts at that record's position rather than at its clock, so
  * records sharing an instant stay on their own side of the cut — which is the
  * whole reason there are two kinds. An item bound is finer than either: it
- * resumes inside a record whose earlier items were already answered for. */
+ * cuts inside a record whose other items were already answered for, closed at
+ * the lower end where it resumes a read and open at the upper end where it
+ * stops short of what the caller already holds. */
 export interface Bounds {
   readonly since_at?: number;
   readonly since_uuid?: string;
   readonly since_id?: string;
   readonly until_at?: number;
   readonly until_uuid?: string;
+  readonly until_id?: string;
 }
 
 /** The bounds as stated, refused where they say two things at once.
@@ -170,8 +173,11 @@ export function bounded(bounds: Bounds): void {
   if (lower > 1) {
     throw new OpError("invalid_args", "a lower bound is a time, a record or an item, not several");
   }
-  if (bounds.until_at !== undefined && bounds.until_uuid !== undefined) {
-    throw new OpError("invalid_args", "an upper bound is a time or a record, not both");
+  const upper = [bounds.until_at, bounds.until_uuid, bounds.until_id].filter(
+    (one) => one !== undefined,
+  ).length;
+  if (upper > 1) {
+    throw new OpError("invalid_args", "an upper bound is a time, a record or an item, not several");
   }
 }
 
@@ -200,6 +206,9 @@ export function within(items: readonly Item[], bounds: Bounds): Item[] {
     }
     if (bounds.since_at !== undefined && item.at < bounds.since_at) continue;
     if (bounds.until_at !== undefined && item.at > bounds.until_at) break;
+    // An upper bound by item is open: it names an item the caller already
+    // holds, so the range ends before it rather than at it.
+    if (bounds.until_id !== undefined && item.id === bounds.until_id) break;
     kept.push(item);
     // An upper bound by record is inclusive and cuts after the last item that
     // record became, so the rest of the same record is still let through.

package/src/transcript/tail.ts

@@ -1,4 +1,4 @@
-import { type FSWatcher, statSync, watch } from "node:fs";
+import { closeSync, type FSWatcher, openSync, readSync, statSync, watch } from "node:fs";
 import { open, stat } from "node:fs/promises";
 import { CONFIRM_POLL_MS } from "../sessions/harness.ts";
 
@@ -86,11 +86,16 @@ export class TranscriptTail {
   }
 
   /** Begin following, seeding the fold from the end of what is already there.
-   * Resolves once the seed has been read, so a snapshot taken after it states
-   * a size the fold has caught up with. */
+   *
+   * The seed is read before this returns rather than awaited, for the reason
+   * the size is read in the constructor: a subscription's snapshot is answered
+   * in the same turn the tail is started, and what the seed settles — the
+   * fold's values, and the items a subscriber opens on — would otherwise be
+   * stated as empty and the whole existing end of the file would arrive later
+   * as though it had just been appended. */
   async start(): Promise<void> {
     if (this.running) return;
-    await this.#seed();
+    this.#seed();
     try {
       this.#watcher = watch(this.path, () => void this.refresh());
     } catch {
@@ -116,11 +121,11 @@ export class TranscriptTail {
     return this.#reading;
   }
 
-  async #seed(): Promise<void> {
+  #seed(): void {
     const size = this.#size;
     if (size === 0) return;
     const from = Math.max(0, size - FOLD_TAIL_BYTES);
-    const complete = whole(await this.#slice(from, size));
+    const complete = whole(this.#sliceSync(from, size));
     this.#offset = from + complete.byteLength;
     // The first line is half a record whenever the read began mid-file, so it
     // is dropped: what is read are whole records or nothing.
@@ -164,6 +169,26 @@ export class TranscriptTail {
    * arithmetic puts it, inside a character as readily as before one, and
    * decoding first would turn those bytes into a replacement character of a
    * different length and move every offset derived from it. */
+  /** The same range, read without yielding, which is what the seed is read
+   * through: the turn that starts a tail is the turn that answers a
+   * subscription, and it has to hold the end of the file by then. Bounded by
+   * `FOLD_TAIL_BYTES` however large the transcript is. */
+  #sliceSync(from: number, to: number): Buffer {
+    if (to <= from) return Buffer.alloc(0);
+    let handle: number;
+    try {
+      handle = openSync(this.path, "r");
+    } catch {
+      return Buffer.alloc(0);
+    }
+    try {
+      const buffer = Buffer.alloc(to - from);
+      return buffer.subarray(0, readSync(handle, buffer, 0, buffer.length, from));
+    } finally {
+      closeSync(handle);
+    }
+  }
+
   async #slice(from: number, to: number): Promise<Buffer> {
     if (to <= from) return Buffer.alloc(0);
     const handle = await open(this.path, "r").catch(() => undefined);