@rse/ase 1.0.7 → 2.0.0

package/dst/ase-task-store-plugin-ase.js

@@ -0,0 +1,484 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { parse as parseYAML } from "yaml";
+import writeFileAtomic from "write-file-atomic";
+import lockfile from "proper-lockfile";
+import { watch } from "chokidar";
+import * as TaskFormat from "./ase-task-format.js";
+/*  the task file pattern and the per-project registry file  */
+const TASK_FILE_RE = /^TASK-([A-Za-z0-9#][A-Za-z0-9#_-]*)\.md$/;
+const PROJECT_FILE = "PROJECT.yaml";
+/*  check for the existence of a filesystem path (without blocking the event loop)  */
+const exists = (p) => fs.promises.access(p).then(() => true, () => false);
+/*  the built-in storage plugin: task plans persisted as "TASK-<id>.md"
+    files in the textual task format (see "ase-format-task.md"), either
+    flat in the base directory ("solo" mode, accepting any project id)
+    or below "<basedir>/<prjId>/", with the "PROJECT.yaml" file of the
+    directory serving as the project registry entry and carrying the
+    lifecycle model name, the task id scheme, and the sequence number
+    high-water mark  */
+class FileTaskStoragePlugin {
+    ctx;
+    name = "ase";
+    verbatim = true;
+    basedir;
+    solo;
+    lifecycle;
+    idscheme;
+    /*  the change detection state: the listener, the directory watcher, the
+        observed projects (onto their directories), the stamps of the task plan
+        files per directory, and the debounced, non-overlapping rescanning  */
+    listener = null;
+    watcher = null;
+    tracked = new Map();
+    stamps = new Map();
+    timer = null;
+    watching = false;
+    scanning = false;
+    pending = false;
+    constructor(ctx) {
+        this.ctx = ctx;
+        const options = ctx.options;
+        if (typeof options.basedir !== "string" || options.basedir === "")
+            throw new Error("task store: plugin \"ase\" requires the \"basedir\" option");
+        this.basedir = path.resolve(options.basedir);
+        this.solo = options.solo === true;
+        this.lifecycle = typeof options.lifecycle === "string" && options.lifecycle !== "" ? options.lifecycle : "solo";
+        this.idscheme = typeof options.idscheme === "string" && options.idscheme !== "" ? options.idscheme : "slug";
+        if (!Object.hasOwn(TaskFormat.taskLifecycles, this.lifecycle))
+            throw new Error(`task store: plugin "ase" received unknown lifecycle model "${this.lifecycle}"`);
+        if (TaskFormat.checkIdScheme(this.idscheme) !== "")
+            throw new Error(`task store: plugin "ase" received invalid task id scheme "${this.idscheme}"`);
+    }
+    /*  the storage lifecycle (the base directory is not created upfront,
+        but on demand once the first file is stored into it), watching
+        the base directory for changes while opened and observed  */
+    async open() {
+        if (this.listener !== null) {
+            this.watching = true;
+            this.arm();
+        }
+        this.ctx.log("debug", `opened base directory "${this.basedir}" ` +
+            `(storage: ${this.solo ? "single" : "multi"}, lifecycle: ${this.lifecycle})`);
+    }
+    async close() {
+        this.watching = false;
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.timer = null;
+        const watcher = this.watcher;
+        this.watcher = null;
+        await watcher?.close();
+        this.tracked.clear();
+        this.stamps.clear();
+    }
+    /*  the directory of a project  */
+    dir(prjId) {
+        return this.solo ? this.basedir : path.join(this.basedir, prjId);
+    }
+    /*  the cross-process lock of a project, taken beside its directory
+        (as "<dir>.lock"), as the directory itself is created on demand only;
+        parent directories created for the lock are removed again afterwards,
+        unless the operation stored something into them  */
+    async lock(prjId, op) {
+        const dir = this.dir(prjId);
+        const parent = path.resolve(path.dirname(dir));
+        let topmost;
+        const release = await lockfile.lock(dir, {
+            realpath: false,
+            retries: { retries: 50, minTimeout: 20, maxTimeout: 200 },
+            onCompromised: (err) => this.ctx.log("error", `lock of project "${prjId}" compromised: ${err.message}`),
+            fs: {
+                ...fs,
+                mkdir: (p, cb) => {
+                    const attempt = (tries) => {
+                        fs.mkdir(path.dirname(p), { recursive: true }, (err, made) => {
+                            if (err !== null)
+                                return cb(err);
+                            if (made !== undefined && (topmost === undefined || made.length < topmost.length))
+                                topmost = made;
+                            fs.mkdir(p, (error) => {
+                                /*  retry if a concurrent cleanup removed the parent directory meanwhile  */
+                                if (error?.code === "ENOENT" && tries > 0)
+                                    return attempt(tries - 1);
+                                cb(error);
+                            });
+                        });
+                    };
+                    attempt(3);
+                }
+            }
+        });
+        try {
+            return await op();
+        }
+        finally {
+            await release().catch((err) => this.ctx.log("warning", `unlock of project "${prjId}" failed: ${err.message}`));
+            if (topmost !== undefined)
+                for (let d = parent; d.length >= topmost.length; d = path.dirname(d))
+                    try {
+                        await fs.promises.rmdir(d);
+                    }
+                    catch {
+                        break;
+                    }
+        }
+    }
+    /*  read the registry entry of a project directory: its lifecycle model
+        name, its task id scheme, the high-water mark of its sequence numbers,
+        and (in "solo" mode only) the id it was first registered under (a
+        malformed file falls back to the defaults and is flagged as broken)  */
+    async projectOf(dir) {
+        const file = path.join(dir, PROJECT_FILE);
+        if (!await exists(file))
+            return { lifecycle: this.lifecycle, idscheme: this.idscheme, seqmark: 0 };
+        const text = await fs.promises.readFile(file, "utf8");
+        let doc;
+        try {
+            doc = parseYAML(text);
+        }
+        catch (err) {
+            this.ctx.log("warning", `malformed project file "${file}" ignored: ${err.message}`);
+            return { lifecycle: this.lifecycle, idscheme: this.idscheme, seqmark: 0, broken: true };
+        }
+        return {
+            ...(typeof doc?.id === "string" && TaskFormat.ID_RE.test(doc.id) ? { id: doc.id } : {}),
+            lifecycle: typeof doc?.lifecycle === "string" && doc.lifecycle !== "" ? doc.lifecycle : this.lifecycle,
+            idscheme: typeof doc?.idscheme === "string" && doc.idscheme !== "" ? doc.idscheme : this.idscheme,
+            seqmark: typeof doc?.seqmark === "number" && Number.isSafeInteger(doc.seqmark) && doc.seqmark > 0 ? doc.seqmark : 0
+        };
+    }
+    /*  write the registry entry of a project directory, where in "solo" mode the id
+        of the first registration is kept, as any project id is accepted and a
+        differing one must not cause a rewrite of the file (all strings are
+        quoted, as e.g. the task id scheme can contain "#" and ":")  */
+    async projectWrite(dir, id, lifecycle, idscheme, seqmark) {
+        await fs.promises.mkdir(dir, { recursive: true });
+        await writeFileAtomic(path.join(dir, PROJECT_FILE), (this.solo ? `id: ${JSON.stringify(id)}\n` : "") + `lifecycle: ${JSON.stringify(lifecycle)}\n` +
+            `idscheme: ${JSON.stringify(idscheme)}\n` +
+            (seqmark > 0 ? `seqmark: ${seqmark}\n` : ""), { encoding: "utf8" });
+    }
+    /*  the project registry  */
+    async projectList() {
+        const out = [];
+        if (this.solo) {
+            if (await exists(path.join(this.basedir, PROJECT_FILE))) {
+                const { id, lifecycle, idscheme, seqmark } = await this.projectOf(this.basedir);
+                out.push({ id: id ?? path.basename(this.basedir), lifecycle, idscheme, seqmark });
+            }
+        }
+        else if (await exists(this.basedir))
+            for (const entry of await fs.promises.readdir(this.basedir, { withFileTypes: true }))
+                if (entry.isDirectory() && TaskFormat.ID_RE.test(entry.name) && await exists(path.join(this.basedir, entry.name, PROJECT_FILE))) {
+                    const { lifecycle, idscheme, seqmark } = await this.projectOf(path.join(this.basedir, entry.name));
+                    out.push({ id: entry.name, lifecycle, idscheme, seqmark });
+                }
+        return out;
+    }
+    async projectGet(prjId) {
+        const dir = this.dir(prjId);
+        if (!await exists(path.join(dir, PROJECT_FILE)))
+            return null;
+        const { lifecycle, idscheme, seqmark } = await this.projectOf(dir);
+        await this.track(prjId);
+        return { id: prjId, lifecycle, idscheme, seqmark };
+    }
+    async projectSet(prjId, lifecycle, idscheme) {
+        const dir = this.dir(prjId);
+        const result = await exists(path.join(dir, PROJECT_FILE)) ? "updated" : "created";
+        const prev = await this.projectOf(dir);
+        if (result === "created" || prev.broken || prev.lifecycle !== lifecycle || prev.idscheme !== idscheme)
+            await this.projectWrite(dir, prev.id ?? prjId, lifecycle, idscheme, prev.seqmark);
+        await this.track(prjId);
+        return result;
+    }
+    async projectMark(prjId, seqmark) {
+        const dir = this.dir(prjId);
+        const prev = await this.projectOf(dir);
+        if (seqmark !== prev.seqmark)
+            await this.projectWrite(dir, prev.id ?? prjId, prev.lifecycle, prev.idscheme, seqmark);
+    }
+    async projectDelete(prjId) {
+        const dir = this.dir(prjId);
+        const file = path.join(dir, PROJECT_FILE);
+        if (!await exists(file))
+            return false;
+        this.untrack(prjId);
+        /*  unregister the project, but keep its directory as long as it still carries any files  */
+        await fs.promises.rm(file, { force: true });
+        if ((await fs.promises.readdir(dir)).length === 0)
+            await fs.promises.rmdir(dir);
+        return true;
+    }
+    /*  the task plan file of a project and the lifecycle model its
+        legacy content is normalized against  */
+    file(prjId, taskId) {
+        return path.join(this.dir(prjId), `TASK-${taskId}.md`);
+    }
+    async model(prjId) {
+        const name = (await this.projectOf(this.dir(prjId))).lifecycle;
+        return Object.hasOwn(TaskFormat.taskLifecycles, name) ? TaskFormat.taskLifecycles[name] : TaskFormat.taskLifecycles[this.lifecycle];
+    }
+    /*  the listing entry of a task plan file of a directory (null if missing or empty)  */
+    async entry(dir, taskId, lifecycle) {
+        const file = path.join(dir, `TASK-${taskId}.md`);
+        const st = await fs.promises.stat(file).catch(() => null);
+        if (st === null || !st.isFile())
+            return null;
+        const text = await fs.promises.readFile(file, "utf8");
+        if (text === "")
+            return null;
+        const plan = TaskFormat.parseTaskText(taskId, text, lifecycle);
+        return { id: taskId, title: TaskFormat.taskTitle(plan.body), header: plan.header, mtime: st.mtime };
+    }
+    /*  the task plans  */
+    async taskList(prjId) {
+        const dir = this.dir(prjId);
+        if (!await exists(dir))
+            return [];
+        const lifecycle = await this.model(prjId);
+        const out = [];
+        for (const entry of await fs.promises.readdir(dir)) {
+            const m = TASK_FILE_RE.exec(entry);
+            if (m === null)
+                continue;
+            const task = await this.entry(dir, m[1], lifecycle);
+            if (task !== null)
+                out.push(task);
+        }
+        return out;
+    }
+    async taskLoad(prjId, taskId) {
+        const file = this.file(prjId, taskId);
+        if (!await exists(file))
+            return null;
+        /*  an empty task file reads as no task (as before the task store)  */
+        const text = await fs.promises.readFile(file, "utf8");
+        if (text === "")
+            return null;
+        return TaskFormat.parseTaskText(taskId, text, await this.model(prjId));
+    }
+    async taskSave(prjId, taskId, plan) {
+        const file = this.file(prjId, taskId);
+        const result = await exists(file) ? "updated" : "created";
+        await fs.promises.mkdir(path.dirname(file), { recursive: true });
+        await writeFileAtomic(file, TaskFormat.formatTaskText(plan), { encoding: "utf8" });
+        await this.written(prjId, taskId);
+        return result;
+    }
+    async taskDelete(prjId, taskId) {
+        const file = this.file(prjId, taskId);
+        if (!await exists(file))
+            return false;
+        await fs.promises.rm(file, { force: true });
+        await this.written(prjId, taskId);
+        return true;
+    }
+    async taskRename(prjId, oldId, newId) {
+        const oldFile = this.file(prjId, oldId);
+        const newFile = this.file(prjId, newId);
+        if (!await exists(oldFile))
+            return false;
+        /*  move atomically first and rewrite the header afterwards, as a crash
+            in between is harmless: parsing takes the "Id" from the filename  */
+        await fs.promises.rename(oldFile, newFile);
+        const plan = TaskFormat.parseTaskText(newId, await fs.promises.readFile(newFile, "utf8"), await this.model(prjId));
+        await writeFileAtomic(newFile, TaskFormat.formatTaskText(plan), { encoding: "utf8" });
+        await this.written(prjId, oldId, newId);
+        return true;
+    }
+    /*  the referenced attachment files, confined to the project directory  */
+    async fileRead(prjId, file) {
+        const dir = await fs.promises.realpath(this.dir(prjId)).catch(() => null);
+        const full = dir !== null ? await fs.promises.realpath(path.resolve(dir, file)).catch(() => null) : null;
+        if (dir === null || full === null || !full.startsWith(dir + path.sep))
+            return null;
+        const st = await fs.promises.stat(full).catch(() => null);
+        if (st === null || !st.isFile())
+            return null;
+        return fs.promises.readFile(full);
+    }
+    /*  ==== change detection ====  */
+    /*  observe the changes of the task plan files made outside of this plugin instance  */
+    watch(listener) {
+        this.listener = listener;
+    }
+    /*  watch the base directory, or, as long as it does not exist yet, its
+        nearest existing ancestor for the creation of the next path step
+        towards it, re-arming once it appears (chokidar alone misses this)  */
+    arm() {
+        if (!this.watching)
+            return;
+        const dir = this.basedir;
+        let w;
+        if (fs.existsSync(dir)) {
+            w = watch(dir, {
+                ignoreInitial: true,
+                depth: this.solo ? 0 : 1,
+                ignored: (file, stats) => (file !== dir && file.endsWith(".lock"))
+                    || (stats?.isFile() === true && !TASK_FILE_RE.test(path.basename(file)))
+            });
+            w.on("all", () => this.schedule());
+        }
+        else {
+            let base = path.dirname(dir);
+            while (!fs.existsSync(base) && path.dirname(base) !== base)
+                base = path.dirname(base);
+            const next = path.join(base, path.relative(base, dir).split(path.sep)[0]);
+            w = watch(base, {
+                ignoreInitial: true,
+                depth: 0,
+                ignored: (file) => file !== base && file !== next
+            });
+            const rearm = () => {
+                if (this.watcher !== w)
+                    return;
+                this.watcher = null;
+                w.close().catch(() => { }).finally(() => {
+                    this.arm();
+                    this.schedule();
+                });
+            };
+            w.on("addDir", (file) => {
+                if (file === next)
+                    rearm();
+            });
+            w.on("ready", () => {
+                if (fs.existsSync(next))
+                    rearm();
+            });
+        }
+        w.on("error", (err) => {
+            this.ctx.log("warning", `watcher: ${err instanceof Error ? err.message : String(err)}`);
+        });
+        this.watcher = w;
+    }
+    /*  the stamp (modification time and size) of a non-empty task plan file (null if missing or empty)  */
+    async stamp(file) {
+        const st = await fs.promises.stat(file).catch(() => null);
+        return st !== null && st.isFile() && st.size > 0 ? `${st.mtimeMs}:${st.size}` : null;
+    }
+    /*  the stamps of the task plan files of a directory  */
+    async scan(dir) {
+        const stamps = new Map();
+        const entries = await fs.promises.readdir(dir).catch((err) => {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        });
+        for (const entry of entries) {
+            const m = TASK_FILE_RE.exec(entry);
+            if (m === null)
+                continue;
+            const stamp = await this.stamp(path.join(dir, entry));
+            if (stamp !== null)
+                stamps.set(m[1], stamp);
+        }
+        return stamps;
+    }
+    /*  start resp. stop observing a project, taking the initial stamps of its directory  */
+    async track(prjId) {
+        if (!this.watching || this.tracked.has(prjId))
+            return;
+        const dir = this.dir(prjId);
+        this.tracked.set(prjId, dir);
+        if (!this.stamps.has(dir))
+            this.stamps.set(dir, await this.scan(dir));
+    }
+    untrack(prjId) {
+        const dir = this.tracked.get(prjId);
+        this.tracked.delete(prjId);
+        if (dir !== undefined && ![...this.tracked.values()].includes(dir))
+            this.stamps.delete(dir);
+    }
+    /*  record the stamps of the task plan files written by this plugin instance,
+        so the change detection does not report them as external changes  */
+    async written(prjId, ...taskIds) {
+        const stamps = this.stamps.get(this.dir(prjId));
+        if (stamps === undefined)
+            return;
+        for (const taskId of taskIds) {
+            const stamp = await this.stamp(this.file(prjId, taskId));
+            if (stamp === null)
+                stamps.delete(taskId);
+            else
+                stamps.set(taskId, stamp);
+        }
+    }
+    /*  schedule a rescan of the observed projects, debounced  */
+    schedule() {
+        if (!this.watching)
+            return;
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.rescan().catch(() => { });
+        }, 100);
+        this.timer.unref();
+    }
+    /*  rescan the directories of the observed projects, never overlapping itself,
+        and report the task plan files whose stamps changed: as added if unknown
+        before, as deleted if gone, else as updated (to all projects of a directory)  */
+    async rescan() {
+        if (this.scanning) {
+            this.pending = true;
+            return;
+        }
+        this.scanning = true;
+        try {
+            const dirs = new Map();
+            for (const [prjId, dir] of this.tracked)
+                dirs.set(dir, [...(dirs.get(dir) ?? []), prjId]);
+            for (const [dir, prjIds] of dirs) {
+                try {
+                    const before = this.stamps.get(dir);
+                    if (before === undefined)
+                        continue;
+                    const after = await this.scan(dir);
+                    const lifecycle = await this.model(prjIds[0]);
+                    const change = { added: [], updated: [], deleted: [] };
+                    for (const [taskId, stamp] of after) {
+                        if (before.get(taskId) === stamp)
+                            continue;
+                        const entry = await this.entry(dir, taskId, lifecycle);
+                        if (entry !== null)
+                            (before.has(taskId) ? change.updated : change.added).push(entry);
+                    }
+                    for (const taskId of before.keys())
+                        if (!after.has(taskId))
+                            change.deleted.push(taskId);
+                    /*  update the stamps in place (and only of the reported task plans),
+                        as the own writes meanwhile already recorded theirs  */
+                    if (!this.watching || this.stamps.get(dir) !== before)
+                        continue;
+                    for (const entry of [...change.added, ...change.updated])
+                        before.set(entry.id, after.get(entry.id));
+                    for (const taskId of change.deleted)
+                        before.delete(taskId);
+                    if (this.listener !== null && (change.added.length > 0 || change.updated.length > 0 || change.deleted.length > 0))
+                        for (const prjId of prjIds)
+                            this.listener(prjId, change);
+                }
+                catch (err) {
+                    this.ctx.log("warning", `scanning directory "${dir}" failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        finally {
+            this.scanning = false;
+            if (this.pending) {
+                this.pending = false;
+                this.schedule();
+            }
+        }
+    }
+}
+/*  the plugin factory  */
+const factory = (ctx) => new FileTaskStoragePlugin(ctx);
+export default factory;

package/dst/ase-task-store-plugin-delegate.js

@@ -0,0 +1,137 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import PQueue from "p-queue";
+/*  the methods every storage plugin has to provide  */
+const pluginMethods = [
+    "open", "close",
+    "projectList", "projectGet", "projectSet", "projectDelete",
+    "taskList", "taskLoad", "taskSave", "taskDelete", "taskRename"
+];
+/*  the name of the default built-in storage plugin, and the modules of all built-in ones  */
+export const BUILTIN_PLUGIN = "ase";
+const builtinPlugins = {
+    ase: "./ase-task-store-plugin-ase.js",
+    github: "./ase-task-store-plugin-github.js",
+    gitlab: "./ase-task-store-plugin-gitlab.js",
+    gitea: "./ase-task-store-plugin-gitea.js"
+};
+/*  resolve a storage plugin name onto its module specifier: the name
+    "ase" (or no name) selects the default built-in plugin, "github", "gitlab", resp. "gitea"
+    the built-in GitHub, GitLab, resp. Gitea Issues plugin, any other plain name selects the NPM
+    package "ase-task-store-<name>", a relative or absolute path is taken
+    as a local module, and anything else is passed through as a module specifier  */
+export const resolveTaskStoragePlugin = (name) => {
+    if (name === null || name === "")
+        name = BUILTIN_PLUGIN;
+    if (Object.hasOwn(builtinPlugins, name))
+        return new URL(builtinPlugins[name], import.meta.url).href;
+    if (/^[A-Za-z0-9_-]+$/.test(name))
+        return `ase-task-store-${name}`;
+    if (name.startsWith(".") || path.isAbsolute(name))
+        return pathToFileURL(path.resolve(name)).href;
+    return name;
+};
+/*  load a storage plugin by name, instantiate it through its factory
+    with the given context, and verify it provides the plugin interface  */
+export const loadTaskStoragePlugin = async (name, ctx) => {
+    const specifier = resolveTaskStoragePlugin(name);
+    name ??= BUILTIN_PLUGIN;
+    let mod;
+    try {
+        mod = await import(specifier);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`task store: failed to load storage plugin "${name}" (module "${specifier}"): ${message}`, { cause: err });
+    }
+    const factory = mod?.default;
+    if (typeof factory !== "function")
+        throw new Error(`task store: storage plugin "${name}" (module "${specifier}") ` +
+            "does not default-export a plugin factory function");
+    let plugin;
+    try {
+        plugin = factory(ctx);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`task store: storage plugin "${name}" factory failed: ${message}`, { cause: err });
+    }
+    if (typeof plugin !== "object" || plugin === null)
+        throw new Error(`task store: storage plugin "${name}" factory did not return a plugin object`);
+    if (typeof plugin.name !== "string" || plugin.name === "")
+        throw new Error(`task store: storage plugin "${name}" lacks the "name" property`);
+    for (const method of pluginMethods)
+        if (typeof plugin[method] !== "function")
+            throw new Error(`task store: storage plugin "${name}" lacks the "${method}" method`);
+    for (const method of ["lock", "fileRead", "watch", "projectMark"])
+        if (plugin[method] !== undefined && typeof plugin[method] !== "function")
+            throw new Error(`task store: storage plugin "${name}" provides a non-function "${method}" property`);
+    return plugin;
+};
+/*  the storage delegate the REST API server operates on: it forwards
+    every persistence operation into the loaded storage plugin and
+    additionally serializes the operations per project, as the part
+    endpoints are read-modify-write cycles on entire plans  */
+export class TaskStore {
+    plugin;
+    queues = new Map();
+    constructor(plugin) {
+        this.plugin = plugin;
+    }
+    /*  the name of the underlying storage plugin  */
+    get name() {
+        return this.plugin.name;
+    }
+    /*  whether the underlying storage plugin stores task plans verbatim  */
+    get verbatim() {
+        return this.plugin.verbatim === true;
+    }
+    /*  run an operation of a project strictly serialized: in-process
+        queued in arrival order (hence not re-entrant) and additionally
+        under the cross-process lock of the storage plugin (if any)  */
+    async serialize(prjId, op) {
+        let queue = this.queues.get(prjId);
+        if (queue === undefined) {
+            queue = new PQueue({ concurrency: 1 });
+            queue.addEventListener("idle", () => this.queues.delete(prjId));
+            this.queues.set(prjId, queue);
+        }
+        return queue.add(() => this.plugin.lock !== undefined ? this.plugin.lock(prjId, op) : op());
+    }
+    /*  delegate the storage lifecycle, closing only after all queued operations settled  */
+    open() { return this.plugin.open(); }
+    async close() {
+        while (this.queues.size > 0)
+            await Promise.all(Array.from(this.queues.values(), (queue) => queue.onIdle()));
+        return this.plugin.close();
+    }
+    /*  delegate the project registry operations  */
+    projectList() { return this.plugin.projectList(); }
+    projectGet(prjId) { return this.plugin.projectGet(prjId); }
+    projectSet(prjId, lifecycle, idscheme) { return this.plugin.projectSet(prjId, lifecycle, idscheme); }
+    projectDelete(prjId) { return this.plugin.projectDelete(prjId); }
+    /*  delegate the optional high-water mark persistence (a no-op if unsupported)  */
+    projectMark(prjId, seqmark) {
+        return this.plugin.projectMark !== undefined ? this.plugin.projectMark(prjId, seqmark) : Promise.resolve();
+    }
+    /*  delegate the task plan operations  */
+    taskList(prjId) { return this.plugin.taskList(prjId); }
+    taskLoad(prjId, taskId) { return this.plugin.taskLoad(prjId, taskId); }
+    taskSave(prjId, taskId, plan) { return this.plugin.taskSave(prjId, taskId, plan); }
+    taskDelete(prjId, taskId) { return this.plugin.taskDelete(prjId, taskId); }
+    taskRename(prjId, oldId, newId) { return this.plugin.taskRename(prjId, oldId, newId); }
+    /*  delegate the optional observation of changes made outside of the plugin (a no-op if unsupported)  */
+    watch(listener) {
+        this.plugin.watch?.(listener);
+    }
+    /*  delegate the optional referenced file reading (null if unsupported)  */
+    get canReadFiles() { return this.plugin.fileRead !== undefined; }
+    fileRead(prjId, file) {
+        return this.plugin.fileRead !== undefined ? this.plugin.fileRead(prjId, file) : Promise.resolve(null);
+    }
+}