opencode-courier 0.7.3 → 0.9.0

package/dist/memory/rpc.d.ts

@@ -0,0 +1,299 @@
+import { Schema } from "effect";
+/** A part's statuses, as `memory/domain.ts`'s `PART_STATUSES` has them; a unit test keeps the two equal. */
+export declare const PART_STATUSES: readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"];
+/** One session started in a tree, as its record keeps it: durations in milliseconds, context use a share of the model's window. */
+declare const Part: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly title: Schema.String;
+    /** 1 for a session the top started. */
+    readonly depth: Schema.Int;
+    readonly isolated: Schema.Boolean;
+    readonly group: Schema.optionalKey<Schema.String>;
+    readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"]>;
+    readonly duration: Schema.optionalKey<Schema.Number>;
+    readonly cost: Schema.optionalKey<Schema.Number>;
+    readonly context: Schema.optionalKey<Schema.Number>;
+    readonly refused: Schema.optionalKey<Schema.Int>;
+}>;
+/** The one line the tree's orchestrator wrote with courier_note: when, and from which depth when not the top's own. */
+declare const Lesson: Schema.Struct<{
+    readonly text: Schema.String;
+    readonly at: Schema.Number;
+    readonly depth: Schema.optionalKey<Schema.Int>;
+}>;
+/** A tree's record as `courier_recall` reads it, with the top session it is kept under; times in epoch milliseconds. */
+declare const Record: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly startedAt: Schema.Number;
+    readonly movedAt: Schema.Number;
+    readonly title: Schema.String;
+    readonly split: Schema.String;
+    readonly finished: Schema.Boolean;
+    readonly recalled: Schema.optionalKey<Schema.Struct<{
+        readonly at: Schema.optionalKey<Schema.Number>;
+        readonly calls: Schema.Int;
+    }>>;
+    readonly lesson: Schema.optionalKey<Schema.Struct<{
+        readonly text: Schema.String;
+        readonly at: Schema.Number;
+        readonly depth: Schema.optionalKey<Schema.Int>;
+    }>>;
+    /** How often other trees' courier_recall calls listed the record and gave it in full, and when one last did. */
+    readonly reads: Schema.optionalKey<Schema.Struct<{
+        readonly shown: Schema.Int;
+        readonly read: Schema.Int;
+        readonly at: Schema.Number;
+    }>>;
+    /** The person's pin, when; a pinned record is listed first and never swept. */
+    readonly pinned: Schema.optionalKey<Schema.Struct<{
+        readonly at: Schema.Number;
+    }>>;
+    readonly parts: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.String;
+        readonly title: Schema.String;
+        /** 1 for a session the top started. */
+        readonly depth: Schema.Int;
+        readonly isolated: Schema.Boolean;
+        readonly group: Schema.optionalKey<Schema.String>;
+        readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"]>;
+        readonly duration: Schema.optionalKey<Schema.Number>;
+        readonly cost: Schema.optionalKey<Schema.Number>;
+        readonly context: Schema.optionalKey<Schema.Number>;
+        readonly refused: Schema.optionalKey<Schema.Int>;
+    }>>;
+}>;
+/** The records of the project of the location asked, pinned first and then newest first; none, and `memory` false, when the option is off there. */
+declare const Records: Schema.Struct<{
+    readonly memory: Schema.Boolean;
+    readonly projectID: Schema.String;
+    readonly records: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.String;
+        readonly startedAt: Schema.Number;
+        readonly movedAt: Schema.Number;
+        readonly title: Schema.String;
+        readonly split: Schema.String;
+        readonly finished: Schema.Boolean;
+        readonly recalled: Schema.optionalKey<Schema.Struct<{
+            readonly at: Schema.optionalKey<Schema.Number>;
+            readonly calls: Schema.Int;
+        }>>;
+        readonly lesson: Schema.optionalKey<Schema.Struct<{
+            readonly text: Schema.String;
+            readonly at: Schema.Number;
+            readonly depth: Schema.optionalKey<Schema.Int>;
+        }>>;
+        /** How often other trees' courier_recall calls listed the record and gave it in full, and when one last did. */
+        readonly reads: Schema.optionalKey<Schema.Struct<{
+            readonly shown: Schema.Int;
+            readonly read: Schema.Int;
+            readonly at: Schema.Number;
+        }>>;
+        /** The person's pin, when; a pinned record is listed first and never swept. */
+        readonly pinned: Schema.optionalKey<Schema.Struct<{
+            readonly at: Schema.Number;
+        }>>;
+        readonly parts: Schema.$Array<Schema.Struct<{
+            readonly sessionID: Schema.String;
+            readonly title: Schema.String;
+            /** 1 for a session the top started. */
+            readonly depth: Schema.Int;
+            readonly isolated: Schema.Boolean;
+            readonly group: Schema.optionalKey<Schema.String>;
+            readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"]>;
+            readonly duration: Schema.optionalKey<Schema.Number>;
+            readonly cost: Schema.optionalKey<Schema.Number>;
+            readonly context: Schema.optionalKey<Schema.Number>;
+            readonly refused: Schema.optionalKey<Schema.Int>;
+        }>>;
+    }>>;
+}>;
+/** What a forget did: removed the record, dropped only its lesson, or found nothing to forget. */
+declare const Forgotten: Schema.Struct<{
+    readonly outcome: Schema.Literals<readonly ["record", "lesson", "none"]>;
+}>;
+/** What a pin did: pinned the record, unpinned it, or found no record to pin. */
+declare const Pinned: Schema.Struct<{
+    readonly outcome: Schema.Literals<readonly ["pinned", "unpinned", "none"]>;
+}>;
+export type MemoryRecord = typeof Record.Type;
+export type MemoryPart = typeof Part.Type;
+export type MemoryLesson = typeof Lesson.Type;
+export type MemoryReads = NonNullable<MemoryRecord["reads"]>;
+export type Records = typeof Records.Type;
+export type Forgotten = typeof Forgotten.Type;
+export type Pinned = typeof Pinned.Type;
+export declare const memoryRpc: {
+    readonly id: "courier-memory";
+    readonly methods: {
+        readonly records: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly memory: boolean;
+                readonly projectID: string;
+                readonly records: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parts: readonly {
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "gone" | "stalled" | "out";
+                        readonly sessionID: string;
+                        readonly title: string;
+                        readonly depth: number;
+                        readonly isolated: boolean;
+                        readonly group?: string | undefined;
+                        readonly duration?: number | undefined;
+                        readonly cost?: number | undefined;
+                        readonly context?: number | undefined;
+                        readonly refused?: number | undefined;
+                    }[];
+                    readonly startedAt: number;
+                    readonly movedAt: number;
+                    readonly split: string;
+                    readonly finished: boolean;
+                    readonly recalled?: {
+                        readonly calls: number;
+                        readonly at?: number | undefined;
+                    } | undefined;
+                    readonly lesson?: {
+                        readonly text: string;
+                        readonly at: number;
+                        readonly depth?: number | undefined;
+                    } | undefined;
+                    readonly reads?: {
+                        readonly shown: number;
+                        readonly read: number;
+                        readonly at: number;
+                    } | undefined;
+                    readonly pinned?: {
+                        readonly at: number;
+                    } | undefined;
+                }[];
+            }, {
+                readonly memory: boolean;
+                readonly projectID: string;
+                readonly records: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parts: readonly {
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "gone" | "stalled" | "out";
+                        readonly sessionID: string;
+                        readonly title: string;
+                        readonly depth: number;
+                        readonly isolated: boolean;
+                        readonly group?: string | undefined;
+                        readonly duration?: number | undefined;
+                        readonly cost?: number | undefined;
+                        readonly context?: number | undefined;
+                        readonly refused?: number | undefined;
+                    }[];
+                    readonly startedAt: number;
+                    readonly movedAt: number;
+                    readonly split: string;
+                    readonly finished: boolean;
+                    readonly recalled?: {
+                        readonly calls: number;
+                        readonly at?: number | undefined;
+                    } | undefined;
+                    readonly lesson?: {
+                        readonly text: string;
+                        readonly at: number;
+                        readonly depth?: number | undefined;
+                    } | undefined;
+                    readonly reads?: {
+                        readonly shown: number;
+                        readonly read: number;
+                        readonly at: number;
+                    } | undefined;
+                    readonly pinned?: {
+                        readonly at: number;
+                    } | undefined;
+                }[];
+            }> & Schema.Struct<{
+                readonly memory: Schema.Boolean;
+                readonly projectID: Schema.String;
+                readonly records: Schema.$Array<Schema.Struct<{
+                    readonly sessionID: Schema.String;
+                    readonly startedAt: Schema.Number;
+                    readonly movedAt: Schema.Number;
+                    readonly title: Schema.String;
+                    readonly split: Schema.String;
+                    readonly finished: Schema.Boolean;
+                    readonly recalled: Schema.optionalKey<Schema.Struct<{
+                        readonly at: Schema.optionalKey<Schema.Number>;
+                        readonly calls: Schema.Int;
+                    }>>;
+                    readonly lesson: Schema.optionalKey<Schema.Struct<{
+                        readonly text: Schema.String;
+                        readonly at: Schema.Number;
+                        readonly depth: Schema.optionalKey<Schema.Int>;
+                    }>>;
+                    /** How often other trees' courier_recall calls listed the record and gave it in full, and when one last did. */
+                    readonly reads: Schema.optionalKey<Schema.Struct<{
+                        readonly shown: Schema.Int;
+                        readonly read: Schema.Int;
+                        readonly at: Schema.Number;
+                    }>>;
+                    /** The person's pin, when; a pinned record is listed first and never swept. */
+                    readonly pinned: Schema.optionalKey<Schema.Struct<{
+                        readonly at: Schema.Number;
+                    }>>;
+                    readonly parts: Schema.$Array<Schema.Struct<{
+                        readonly sessionID: Schema.String;
+                        readonly title: Schema.String;
+                        /** 1 for a session the top started. */
+                        readonly depth: Schema.Int;
+                        readonly isolated: Schema.Boolean;
+                        readonly group: Schema.optionalKey<Schema.String>;
+                        readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"]>;
+                        readonly duration: Schema.optionalKey<Schema.Number>;
+                        readonly cost: Schema.optionalKey<Schema.Number>;
+                        readonly context: Schema.optionalKey<Schema.Number>;
+                        readonly refused: Schema.optionalKey<Schema.Int>;
+                    }>>;
+                }>>;
+            }>;
+        };
+        /** Forgets the record of the tree under `sessionID` in the project asked, or with `lesson` only its lesson, keeping the facts. */
+        readonly forget: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly lesson?: boolean | undefined;
+            }, {
+                readonly sessionID: string;
+                readonly lesson?: boolean | undefined;
+            }> & Schema.Struct<{
+                readonly sessionID: Schema.String;
+                readonly lesson: Schema.optionalKey<Schema.Boolean>;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly outcome: "lesson" | "record" | "none";
+            }, {
+                readonly outcome: "lesson" | "record" | "none";
+            }> & Schema.Struct<{
+                readonly outcome: Schema.Literals<readonly ["record", "lesson", "none"]>;
+            }>;
+        };
+        /** Pins the record of the tree under `sessionID` in the project asked, or with `pinned` false unpins it. */
+        readonly pin: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly pinned: boolean;
+            }, {
+                readonly sessionID: string;
+                readonly pinned: boolean;
+            }> & Schema.Struct<{
+                readonly sessionID: Schema.String;
+                readonly pinned: Schema.Boolean;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly outcome: "pinned" | "none" | "unpinned";
+            }, {
+                readonly outcome: "pinned" | "none" | "unpinned";
+            }> & Schema.Struct<{
+                readonly outcome: Schema.Literals<readonly ["pinned", "unpinned", "none"]>;
+            }>;
+        };
+    };
+    readonly events: {};
+};
+export type MemoryRpc = typeof memoryRpc;
+export {};

package/dist/memory/rpc.js

@@ -0,0 +1,71 @@
+/**
+ * The memory's RPC, the contract its TUI part, the memory view, and its server half share. Standard Schema values, as
+ * the tree's and the person's; imports only `@opencode/plugin/rpc` and `effect`.
+ */
+import { Rpc } from "@opencode/plugin/rpc";
+import { Schema } from "effect";
+const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/** A part's statuses, as `memory/domain.ts`'s `PART_STATUSES` has them; a unit test keeps the two equal. */
+export const PART_STATUSES = ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"];
+/** One session started in a tree, as its record keeps it: durations in milliseconds, context use a share of the model's window. */
+const Part = Schema.Struct({
+    sessionID: Schema.String,
+    title: Schema.String,
+    /** 1 for a session the top started. */
+    depth: Count,
+    isolated: Schema.Boolean,
+    group: Schema.optionalKey(Schema.String),
+    status: Schema.Literals(PART_STATUSES),
+    duration: Schema.optionalKey(Schema.Number),
+    cost: Schema.optionalKey(Schema.Number),
+    context: Schema.optionalKey(Schema.Number),
+    refused: Schema.optionalKey(Count),
+});
+/** The one line the tree's orchestrator wrote with courier_note: when, and from which depth when not the top's own. */
+const Lesson = Schema.Struct({ text: Schema.String, at: Schema.Number, depth: Schema.optionalKey(Count) });
+/** A tree's record as `courier_recall` reads it, with the top session it is kept under; times in epoch milliseconds. */
+const Record = Schema.Struct({
+    sessionID: Schema.String,
+    startedAt: Schema.Number,
+    movedAt: Schema.Number,
+    title: Schema.String,
+    split: Schema.String,
+    finished: Schema.Boolean,
+    recalled: Schema.optionalKey(Schema.Struct({ at: Schema.optionalKey(Schema.Number), calls: Count })),
+    lesson: Schema.optionalKey(Lesson),
+    /** How often other trees' courier_recall calls listed the record and gave it in full, and when one last did. */
+    reads: Schema.optionalKey(Schema.Struct({ shown: Count, read: Count, at: Schema.Number })),
+    /** The person's pin, when; a pinned record is listed first and never swept. */
+    pinned: Schema.optionalKey(Schema.Struct({ at: Schema.Number })),
+    parts: Schema.Array(Part),
+});
+/** The records of the project of the location asked, pinned first and then newest first; none, and `memory` false, when the option is off there. */
+const Records = Schema.Struct({
+    memory: Schema.Boolean,
+    projectID: Schema.String,
+    records: Schema.Array(Record),
+});
+/** What a forget did: removed the record, dropped only its lesson, or found nothing to forget. */
+const Forgotten = Schema.Struct({ outcome: Schema.Literals(["record", "lesson", "none"]) });
+/** What a pin did: pinned the record, unpinned it, or found no record to pin. */
+const Pinned = Schema.Struct({ outcome: Schema.Literals(["pinned", "unpinned", "none"]) });
+export const memoryRpc = Rpc.define({
+    id: "courier-memory",
+    methods: {
+        records: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({})),
+            output: Schema.toStandardSchemaV1(Records),
+        },
+        /** Forgets the record of the tree under `sessionID` in the project asked, or with `lesson` only its lesson, keeping the facts. */
+        forget: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String, lesson: Schema.optionalKey(Schema.Boolean) })),
+            output: Schema.toStandardSchemaV1(Forgotten),
+        },
+        /** Pins the record of the tree under `sessionID` in the project asked, or with `pinned` false unpins it. */
+        pin: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String, pinned: Schema.Boolean })),
+            output: Schema.toStandardSchemaV1(Pinned),
+        },
+    },
+    events: {},
+});

package/dist/memory/store.d.ts

@@ -0,0 +1,14 @@
+import { type Storage } from "../platform/storage.js";
+import { type TreeRecord } from "./domain.js";
+import type { MemoryStore } from "./ports.js";
+export declare const recordKey: (projectID: string, sessionID: string) => string;
+/** The key prefix of a project's records. */
+export declare const projectPrefix: (projectID: string) => string;
+/** The person's pin on a record, `{ at }`; the key's presence pins. */
+export declare const pinKey: (projectID: string, sessionID: string) => string;
+/** The reads of a record by the tree under `by`, `{ shown, read, at }`, written only by that tree's sessions. */
+export declare const readsKey: (projectID: string, sessionID: string, by: string) => string;
+/** A record as stored, or undefined for a value that is not one; its reads and pin lie beside it (`beside`). */
+export declare function readRecord(value: unknown): TreeRecord | undefined;
+/** The `MemoryStore` over the plugin's storage. */
+export declare function memoryStore(storage: Storage): MemoryStore;

package/dist/memory/store.js

@@ -0,0 +1,174 @@
+import { finite, num, obj, str } from "../platform/json.js";
+import { scanEntries } from "../platform/storage.js";
+import { isPartStatus, lessonText, MAX_REVISIONS, NOT_STATED, noteRead, sumReads, } from "./domain.js";
+// The memory's storage: the only file that knows its keys and layout. A record is read leniently, as one written by hand
+// with `e2e/kv.ts set` is; beside it, under its key and each with its own writer, lie the person's pin and each reader tree's reads.
+const PREFIX = "memory/";
+export const recordKey = (projectID, sessionID) => `${PREFIX}${projectID}/${sessionID}`;
+/** The key prefix of a project's records. */
+export const projectPrefix = (projectID) => `${PREFIX}${projectID}/`;
+/** The key prefix of what lies beside a record: its pin and its reads. */
+const besidePrefix = (projectID, sessionID) => `${recordKey(projectID, sessionID)}/`;
+/** The person's pin on a record, `{ at }`; the key's presence pins. */
+export const pinKey = (projectID, sessionID) => `${besidePrefix(projectID, sessionID)}pin`;
+/** The reads of a record by the tree under `by`, `{ shown, read, at }`, written only by that tree's sessions. */
+export const readsKey = (projectID, sessionID, by) => `${besidePrefix(projectID, sessionID)}reads/${by}`;
+function readPart(value) {
+    const given = obj(value);
+    const sessionID = str(given.sessionID);
+    if (sessionID === undefined)
+        return undefined;
+    const optional = (field) => {
+        const number = finite(given[field]);
+        return number === undefined ? {} : { [field]: number };
+    };
+    const group = str(given.group);
+    return {
+        sessionID,
+        title: str(given.title) ?? "",
+        depth: num(given.depth) ?? 1,
+        isolated: given.isolated === true,
+        ...(group ? { group } : {}),
+        status: isPartStatus(given.status) ? given.status : "out",
+        ...optional("duration"),
+        ...optional("cost"),
+        ...optional("context"),
+        ...optional("refused"),
+    };
+}
+function readRecalled(value) {
+    const given = obj(value);
+    const calls = num(given.calls);
+    if (calls === undefined)
+        return undefined;
+    const at = num(given.at);
+    return at === undefined ? { calls } : { at, calls };
+}
+/** A lesson as `{ text, at, depth }`, or as a bare string written by hand, dated `movedAt`; none for an empty text. */
+function readLesson(value, movedAt) {
+    const given = typeof value === "string" ? { text: value } : obj(value);
+    const { text } = lessonText(str(given.text) ?? "");
+    if (!text)
+        return undefined;
+    const depth = num(given.depth);
+    return { text, at: num(given.at) ?? movedAt, ...(depth !== undefined && Number.isInteger(depth) && depth > 0 ? { depth } : {}) };
+}
+/** The revisions as `{ text, at, parts }`, the newest `MAX_REVISIONS`, leaving out an entry without a text, a time or a count of parts. */
+function readRevisions(value) {
+    if (!Array.isArray(value))
+        return [];
+    const revisions = value.flatMap((entry) => {
+        const given = obj(entry);
+        const text = str(given.text)?.trim();
+        const at = num(given.at);
+        const parts = num(given.parts);
+        return text && at !== undefined && parts !== undefined && parts >= 0 ? [{ text, at, parts }] : [];
+    });
+    return revisions.slice(-MAX_REVISIONS);
+}
+/** A record as stored, or undefined for a value that is not one; its reads and pin lie beside it (`beside`). */
+export function readRecord(value) {
+    const given = obj(value);
+    if (!Array.isArray(given.parts))
+        return undefined;
+    const recalled = readRecalled(given.recalled);
+    const movedAt = num(given.movedAt) ?? num(given.startedAt) ?? 0;
+    const lesson = readLesson(given.lesson, movedAt);
+    const revisions = readRevisions(given.revisions);
+    return {
+        startedAt: num(given.startedAt) ?? 0,
+        movedAt,
+        title: str(given.title) ?? "",
+        split: str(given.split) ?? NOT_STATED,
+        ...(revisions.length ? { revisions } : {}),
+        finished: given.finished === true,
+        ...(recalled ? { recalled } : {}),
+        ...(lesson ? { lesson } : {}),
+        parts: given.parts.map(readPart).filter((part) => part !== undefined),
+    };
+}
+/** One tree's reads as `{ shown, read, at }`; a count missing is 0, an entry without a time is none. */
+function readReads(value) {
+    const given = obj(value);
+    const at = num(given.at);
+    if (at === undefined)
+        return undefined;
+    const count = (field) => Math.max(0, Math.floor(num(given[field]) ?? 0));
+    return { shown: count("shown"), read: count("read"), at };
+}
+/** The pin as `{ at }`: any value under the key pins, dated 0 when it says no time. */
+const readPinned = (value) => ({ at: num(obj(value).at) ?? 0 });
+/** A record with what lies beside it: its readers' reads as one, and its pin. */
+function beside(record, { pinned, reads }) {
+    const { parts, ...facts } = record;
+    const summed = sumReads(reads);
+    return { ...facts, ...(summed ? { reads: summed } : {}), ...(pinned ? { pinned } : {}), parts };
+}
+/** The key's path under `memory/`, split: `[projectID, sessionID]` a record, then `pin`, or `reads` and the reader. */
+const pathOf = (prefix, key) => `${prefix.slice(PREFIX.length)}${key}`.split("/");
+/** Sorts a scan's entries by record: the record's value, when the scan held it, and what lies beside it. */
+function group(prefix, entries) {
+    const groups = new Map();
+    const of = (projectID, sessionID) => {
+        const id = `${projectID}/${sessionID}`;
+        const found = groups.get(id) ?? { beside: { reads: [] } };
+        groups.set(id, found);
+        return found;
+    };
+    for (const { key, value } of entries) {
+        const [projectID, sessionID, kind, by] = pathOf(prefix, key);
+        if (!projectID || !sessionID)
+            continue;
+        if (kind === undefined)
+            of(projectID, sessionID).record = value;
+        else if (kind === "pin" && by === undefined)
+            of(projectID, sessionID).beside.pinned = readPinned(value);
+        else if (kind === "reads" && by) {
+            const reads = readReads(value);
+            if (reads)
+                of(projectID, sessionID).beside.reads.push(reads);
+        }
+    }
+    return [...groups].map(([id, found]) => {
+        const [projectID, sessionID] = id.split("/");
+        return { projectID, sessionID, ...found };
+    });
+}
+/** The `MemoryStore` over the plugin's storage. */
+export function memoryStore(storage) {
+    const scanned = async (prefix) => group(prefix, await scanEntries(storage, prefix));
+    const under = async (prefix) => (await scanned(prefix)).flatMap(({ projectID, sessionID, record: value, beside: others }) => {
+        const record = readRecord(value);
+        return record ? [{ ...beside(record, others), projectID, sessionID }] : [];
+    });
+    return {
+        async get(projectID, sessionID) {
+            const [value, others] = await Promise.all([storage.get(recordKey(projectID, sessionID)), scanned(besidePrefix(projectID, sessionID))]);
+            const record = readRecord(value);
+            return record && beside(record, others[0]?.beside ?? { reads: [] });
+        },
+        // What lies beside the record is never written with it, so no refresh or note can write over a pin or a count.
+        async put(projectID, sessionID, { reads: _reads, pinned: _pinned, ...record }) {
+            await storage.set(recordKey(projectID, sessionID), { ...record, parts: record.parts.map((part) => ({ ...part })) });
+        },
+        async remove(projectID, sessionID) {
+            const others = await scanEntries(storage, besidePrefix(projectID, sessionID));
+            await Promise.all([storage.remove(recordKey(projectID, sessionID)), ...others.map(({ key }) => storage.remove(`${besidePrefix(projectID, sessionID)}${key}`))]);
+        },
+        async noteRead(projectID, sessionID, by, kind, at) {
+            const key = readsKey(projectID, sessionID, by);
+            const reads = noteRead(readReads(await storage.get(key)), kind, at);
+            await storage.set(key, { ...reads });
+            return reads;
+        },
+        async pin(projectID, sessionID, pinned) {
+            if (pinned)
+                await storage.set(pinKey(projectID, sessionID), { ...pinned });
+            else
+                await storage.remove(pinKey(projectID, sessionID));
+        },
+        ofProject: (projectID) => under(projectPrefix(projectID)),
+        all: () => under(PREFIX),
+        strays: async () => (await scanned(PREFIX)).filter(({ record }) => record === undefined).map(({ projectID, sessionID }) => ({ projectID, sessionID })),
+    };
+}

package/dist/memory/sweep.d.ts

@@ -0,0 +1,7 @@
+import type { Storage } from "../platform/storage.js";
+import { type StoredRecord } from "./domain.js";
+/**
+ * On loading: drops, per project, the records `keep` does not at `now`, the pinned never among them, and the reads or
+ * pin left beside a record removed meanwhile. Returns the records dropped.
+ */
+export declare function sweepRecords(storage: Storage, now: number): Promise<StoredRecord[]>;

package/dist/memory/sweep.js

@@ -0,0 +1,16 @@
+import { keep } from "./domain.js";
+import { memoryStore } from "./store.js";
+/**
+ * On loading: drops, per project, the records `keep` does not at `now`, the pinned never among them, and the reads or
+ * pin left beside a record removed meanwhile. Returns the records dropped.
+ */
+export async function sweepRecords(storage, now) {
+    const store = memoryStore(storage);
+    const byProject = new Map();
+    for (const record of await store.all())
+        byProject.set(record.projectID, [...(byProject.get(record.projectID) ?? []), record]);
+    const dropped = [...byProject.values()].flatMap((records) => keep(records, now).dropped);
+    const strays = await store.strays();
+    await Promise.all([...dropped, ...strays].map((record) => store.remove(record.projectID, record.sessionID)));
+    return dropped;
+}

package/dist/memory/text.d.ts

@@ -0,0 +1,35 @@
+import { type Lesson, type StoredRecord } from "./domain.js";
+/** The tool's name, which the skill and the role part name too. */
+export declare const RECALL_TOOL = "courier_recall";
+/** The lesson tool's name, which the skill's last step names. */
+export declare const NOTE_TOOL = "courier_note";
+/** A duration in milliseconds as a model reads it: seconds under half a minute, else whole minutes, else hours and minutes. */
+export declare function duration(ms: number): string;
+/** How long ago a record last moved: a duration under a day, else whole days, which a record kept for months is read in. */
+export declare function age(ms: number): string;
+/** A lesson as the listing and the note's result show it: dated, and from which depth when a session below the top wrote it. */
+export declare function lessonLine(lesson: Lesson): string;
+/**
+ * One record as the listing shows it: its top, when it started, its title, its split line and its latest revision as prose,
+ * its parts, how long it ran, how long ago it last moved, what it cost, and whether the person pinned it.
+ */
+export declare function recordLine(record: StoredRecord, top: string, now: number): string;
+/** What courier_recall says when the memory option is off. */
+export declare const RECALL_OFF = "Memory is off: the plugin's memory option is false, so no record of a session tree is kept or listed in this project. Decide from the task alone.";
+/**
+ * The listing: every record of the project, the pinned first and then newest first, the caller's own tree marked, each
+ * aged against `now`.
+ */
+export declare function recallListText(records: ReadonlyArray<StoredRecord>, top: string, now: number): string;
+/** One record in full, as JSON: durations in milliseconds, times in epoch milliseconds, context use as a share of the model's window. */
+export declare function recallRecordText(record: StoredRecord): string;
+export declare const recallMissingText: (sessionID: string) => string;
+/** What courier_note says once the lesson is written: where, and what it replaced. */
+export declare function noteText(top: string, lesson: Lesson, replaced: Lesson | undefined): string;
+/** What courier_note says when the memory option is off. */
+export declare const NOTE_OFF = "Not noted: the plugin's memory option is false, so no record of a session tree is kept in this project to write a lesson on.";
+export declare const noteLeafRefusal: (depth: number, maxDepth: number) => string;
+export declare const NOTE_EMPTY = "Not noted: text is empty. Write one line, what the next orchestrator in this project should know about running a tree like this one, with the job it comes from and the reason, or nothing.";
+/** The refusal of a lesson longer than `LESSON_MAX` as one line: nothing is written, and the earlier lesson stays. */
+export declare const noteLongRefusal: (length: number) => string;
+export declare const noteUnrecordedRefusal: (top: string) => string;