@sigrun/sigrun 0.4.1 → 0.5.0

package/dist/curation/store.js

@@ -0,0 +1,444 @@
+import { randomUUID } from "node:crypto";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { curationDir, learnedSkillsDir } from "./paths.js";
+import { validSkillName } from "./names.js";
+import { scanContent } from "./scan.js";
+const VERSIONS = 10;
+const FEED_ENTRIES = 500;
+const SUPPORT_ROOTS = ["references", "templates", "scripts", "assets"];
+const locks = new Map();
+async function withUserLock(user, fn) {
+    const previous = locks.get(user) ?? Promise.resolve();
+    const current = previous.then(fn, fn);
+    const tail = current.then(() => undefined, () => undefined);
+    locks.set(user, tail);
+    try {
+        return await current;
+    }
+    finally {
+        if (locks.get(user) === tail)
+            locks.delete(user);
+    }
+}
+function requireUser(options) {
+    if (!options.userExists())
+        throw new Error("user removed");
+}
+function skillName(name) {
+    if (!validSkillName(name))
+        throw new Error(`invalid skill name: ${name}`);
+}
+function supportFile(file) {
+    if (file.includes("\\") || file.startsWith("/") || file.includes("\0")) {
+        throw new Error("support file must be a relative path");
+    }
+    const parts = file.split("/");
+    if (parts.length < 2 || !SUPPORT_ROOTS.includes(parts[0]) || parts.some((part) => part === "" || part === "." || part === "..")) {
+        throw new Error("support file must be under references/, templates/, scripts/ or assets/");
+    }
+    return join(...parts);
+}
+function frontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (match === null)
+        throw new Error("SKILL.md frontmatter is required");
+    const fields = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const field = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (field !== null)
+            fields[field[1]] = field[2].trim().replace(/^(["'])(.*)\1$/, "$2");
+    }
+    if (!fields.name)
+        throw new Error("SKILL.md frontmatter name is required");
+    if (!fields.description)
+        throw new Error("SKILL.md frontmatter description is required");
+    return { name: fields.name, description: fields.description };
+}
+function checkContent(text) {
+    const result = scanContent(text);
+    if (!result.ok)
+        throw new Error(`content scan refused line ${result.line}: ${result.rule}`);
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function copyTree(source, target) {
+    const info = await lstat(source);
+    if (info.isSymbolicLink())
+        throw new Error(`symlinks are not allowed: ${source}`);
+    if (info.isDirectory()) {
+        await mkdir(target, { recursive: true });
+        for (const entry of await readdir(source))
+            await copyTree(join(source, entry), join(target, entry));
+    }
+    else if (info.isFile()) {
+        await cp(source, target);
+    }
+    else
+        throw new Error(`unsupported file type: ${source}`);
+}
+async function assertNoSymlinks(root, file) {
+    const parts = file.split("/");
+    let path = root;
+    for (const part of parts) {
+        path = join(path, part);
+        try {
+            if ((await lstat(path)).isSymbolicLink())
+                throw new Error("symlinks are not allowed in skill files");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+    }
+}
+async function readState(dir) {
+    try {
+        const value = JSON.parse(await readFile(join(dir, "state.json"), "utf8"));
+        return { pins: value.pins ?? {}, archived: value.archived ?? [], createdAt: value.createdAt ?? {} };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { pins: {}, archived: [], createdAt: {} };
+        throw error;
+    }
+}
+async function writeState(dir, state) {
+    await mkdir(dir, { recursive: true });
+    await writeFileAtomic(join(dir, "state.json"), `${JSON.stringify(state, null, 2)}\n`);
+}
+async function writeFileAtomic(path, text) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temp, text);
+    await rename(temp, path);
+}
+async function readFeed(dir) {
+    try {
+        const text = await readFile(join(dir, "feed.jsonl"), "utf8");
+        return text.split("\n").filter(Boolean).map((line) => JSON.parse(line)).reverse();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function nextVersion(dir, name) {
+    const root = join(dir, "versions", name);
+    let entries = [];
+    try {
+        entries = await readdir(root);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const highest = entries.reduce((max, entry) => Math.max(max, /^v(\d+)$/.exec(entry)?.[1] === undefined ? 0 : Number(/^v(\d+)$/.exec(entry)[1])), 0);
+    return `v${highest + 1}`;
+}
+async function versionLocation(version) {
+    try {
+        return (await readFile(join(version, ".location"), "utf8")).trim() === "archive" ? "archive" : "skills";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export class SkillStore {
+    options;
+    root;
+    skills;
+    archive;
+    constructor(options) {
+        this.options = options;
+        this.root = curationDir(options.userArea);
+        this.skills = learnedSkillsDir(options.userArea);
+        this.archive = join(this.root, "archive");
+    }
+    async list() {
+        requireUser(this.options);
+        const state = await readState(this.root);
+        const names = new Set();
+        for (const root of [this.skills, join(this.root, "archive")]) {
+            try {
+                for (const entry of await readdir(root, { withFileTypes: true })) {
+                    if (entry.isDirectory() && validSkillName(entry.name))
+                        names.add(entry.name);
+                }
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        const result = [];
+        for (const name of [...names].sort()) {
+            const archived = state.archived.includes(name);
+            const path = join(archived ? join(this.root, "archive") : this.skills, name, "SKILL.md");
+            try {
+                const text = await readFile(path, "utf8");
+                const meta = frontmatter(text);
+                result.push({ name, description: meta.description, archived, pinned: state.pins[name] === true, bytes: Buffer.byteLength(text), createdAt: state.createdAt[name] ?? (await stat(path)).birthtime.toISOString() });
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        return result;
+    }
+    async view(name, file = "SKILL.md") {
+        requireUser(this.options);
+        skillName(name);
+        const path = file === "SKILL.md" ? file : supportFile(file);
+        await assertNoSymlinks(join(this.skills, name), path);
+        return readFile(join(this.skills, name, path), "utf8");
+    }
+    async apply(name, change, meta) {
+        requireUser(this.options);
+        return withUserLock(this.options.user, async () => {
+            requireUser(this.options);
+            skillName(name);
+            const state = await readState(this.root);
+            const archived = state.archived.includes(name);
+            const root = join(archived ? this.archive : this.skills, name);
+            if (change.kind === "create") {
+                if (await exists(root))
+                    throw new Error(`skill already exists: ${name}`);
+                const taken = await this.options.nameTakenElsewhere(name);
+                if (taken !== undefined)
+                    throw new Error(`skill name ${name} is already used by ${taken}; use overlay instead`);
+                checkContent(change.content);
+                if (frontmatter(change.content).name !== name)
+                    throw new Error(`frontmatter name must match the directory ${name}`);
+                await mkdir(root, { recursive: true });
+                await writeFile(join(root, "SKILL.md"), change.content);
+                state.createdAt[name] = this.options.now().toISOString();
+                return this.commit(name, "create", meta, state, undefined, root);
+            }
+            if (!(await exists(root)))
+                throw new Error(`unknown skill: ${name}`);
+            if (change.kind === "archive") {
+                if (archived)
+                    throw new Error(`skill is archived: ${name}`);
+                return this.commit(name, "archive", meta, state, root, join(this.root, "archive", name), change.absorbedInto);
+            }
+            if (change.kind === "restore") {
+                if (!archived)
+                    throw new Error(`skill is not archived: ${name}`);
+                const version = change.version === undefined ? undefined : join(this.root, "versions", name, change.version);
+                if (version !== undefined && !(await exists(version)))
+                    throw new Error(`unknown version: ${change.version}`);
+                return this.commit(name, "restore", meta, state, root, join(this.skills, name), undefined, version);
+            }
+            if (archived)
+                throw new Error(`skill is archived: ${name}`);
+            if (change.kind !== "patch" && change.kind !== "write_file" && change.kind !== "remove_file")
+                throw new Error("unsupported skill change");
+            return this.commit(name, change.kind, meta, state, root, root, undefined, undefined, async () => {
+                if (change.kind === "patch") {
+                    const file = change.file === undefined ? "SKILL.md" : supportFile(change.file);
+                    await assertNoSymlinks(root, file);
+                    const oldText = await readFile(join(root, file), "utf8");
+                    const first = oldText.indexOf(change.old);
+                    if (first < 0 || oldText.indexOf(change.old, first + 1) >= 0 || change.old === "")
+                        throw new Error("patch old text must be a unique span");
+                    const text = oldText.slice(0, first) + change.new + oldText.slice(first + change.old.length);
+                    checkContent(text);
+                    if (file === "SKILL.md" && frontmatter(text).name !== name)
+                        throw new Error(`frontmatter name must match the directory ${name}`);
+                    await writeFile(join(root, file), text);
+                }
+                else if (change.kind === "write_file") {
+                    const file = supportFile(change.file);
+                    await assertNoSymlinks(root, file);
+                    checkContent(change.content);
+                    await mkdir(join(root, file, ".."), { recursive: true });
+                    await writeFile(join(root, file), change.content);
+                }
+                else {
+                    const file = supportFile(change.file);
+                    await assertNoSymlinks(root, file);
+                    await rm(join(root, file));
+                }
+            });
+        });
+    }
+    async pin(name, pinned) {
+        requireUser(this.options);
+        await withUserLock(this.options.user, async () => {
+            requireUser(this.options);
+            skillName(name);
+            const state = await readState(this.root);
+            if (!(await this.list()).some((skill) => skill.name === name))
+                throw new Error(`unknown skill: ${name}`);
+            state.pins[name] = pinned;
+            await writeState(this.root, state);
+            await this.appendFeed({ id: randomUUID(), at: this.options.now().toISOString(), actor: "user", action: pinned ? "pin" : "unpin", skill: name });
+        });
+    }
+    async feed(limit, before) {
+        requireUser(this.options);
+        const entries = await readFeed(this.root);
+        const start = before === undefined ? 0 : entries.findIndex((entry) => entry.id === before);
+        if (start < 0)
+            return [];
+        return entries.slice(start + (before === undefined ? 0 : 1), start + (before === undefined ? 0 : 1) + Math.max(0, limit));
+    }
+    async undo(entryIds) {
+        requireUser(this.options);
+        return withUserLock(this.options.user, async () => {
+            requireUser(this.options);
+            const all = await readFeed(this.root);
+            const selected = all.filter((entry) => entryIds.includes(entry.id) && entry.before !== undefined);
+            const earliest = new Map();
+            for (const entry of selected) {
+                const previous = earliest.get(entry.skill);
+                if (previous === undefined || all.indexOf(entry) > all.indexOf(previous))
+                    earliest.set(entry.skill, entry);
+            }
+            // The create-undo companion: an undone CREATE has no before
+            // snapshot (nothing existed) — reverting it means REMOVING the
+            // skill (archive, never hard delete; restorable from versions).
+            const createdOnly = all.filter((entry) => entryIds.includes(entry.id) && entry.before === undefined && entry.action === "create");
+            for (const entry of createdOnly) {
+                if (!earliest.has(entry.skill))
+                    earliest.set(entry.skill, entry);
+            }
+            const result = [];
+            const state = await readState(this.root);
+            for (const entry of earliest.values()) {
+                if (entry.before === undefined) {
+                    // Undo of a create: archive the skill (the no-delete
+                    // rule — `restore` brings it back from versions).
+                    if (state.archived.includes(entry.skill))
+                        continue;
+                    const from = join(this.skills, entry.skill);
+                    if (!(await exists(from)))
+                        continue;
+                    const next = await this.commit(entry.skill, "undo", { actor: "user" }, state, from, join(this.root, "archive", entry.skill));
+                    result.push(next);
+                    continue;
+                }
+                const current = join(state.archived.includes(entry.skill) ? this.archive : this.skills, entry.skill);
+                const previous = join(this.root, "versions", entry.skill, entry.before);
+                if (!(await exists(previous)) || !(await exists(current)))
+                    continue;
+                const location = await versionLocation(previous);
+                if (location === undefined)
+                    throw new Error(`unknown version location: ${entry.before}`);
+                const destination = join(location === "archive" ? this.archive : this.skills, entry.skill);
+                const next = await this.commit(entry.skill, "undo", { actor: "user" }, state, current, destination, undefined, previous);
+                result.push(next);
+            }
+            return result;
+        });
+    }
+    /**
+     * Append one feed entry verbatim — the A5 overlay seam. OverlayStore
+     * owns its files but records every change in the SAME per-user feed
+     * (action `"overlay"`), so retention, the per-user lock and the P8
+     * view hold for overlay changes too. Entry ids/at values are the
+     * caller's.
+     */
+    async appendFeedEntry(entry) {
+        requireUser(this.options);
+        await withUserLock(this.options.user, async () => {
+            requireUser(this.options);
+            await this.appendFeed(entry);
+        });
+    }
+    /**
+     * Persists a change: snapshots the before state, applies the mutation,
+     * snapshots the after state, records the feed entry and runs retention.
+     * Every version directory carries a `.location` file recording where its
+     * content lived (skills or archive) when the snapshot was taken, so undo
+     * can pick the right destination and retention removes the metadata with
+     * the snapshot it belongs to.
+     */
+    async commit(name, action, meta, state, beforeRoot, afterRoot, absorbedInto, restoreFrom, mutate) {
+        const versionRoot = join(this.root, "versions", name);
+        let before;
+        if (beforeRoot !== undefined && await exists(beforeRoot)) {
+            before = await nextVersion(this.root, name);
+            await copyTree(beforeRoot, join(versionRoot, before));
+            await writeFile(join(versionRoot, before, ".location"), beforeRoot.startsWith(this.archive + "/") ? "archive" : "skills");
+        }
+        if (mutate !== undefined)
+            await mutate();
+        if (action === "archive") {
+            await mkdir(this.archive, { recursive: true });
+            await rename(beforeRoot, afterRoot);
+            state.archived = [...new Set([...state.archived, name])];
+        }
+        else if (action === "restore") {
+            await mkdir(this.skills, { recursive: true });
+            if (restoreFrom === undefined) {
+                await rename(beforeRoot, afterRoot);
+            }
+            else {
+                const staged = await this.stageVersion(restoreFrom);
+                await rm(beforeRoot, { recursive: true, force: true });
+                await rename(staged, afterRoot);
+            }
+            state.archived = state.archived.filter((item) => item !== name);
+        }
+        else if (action === "undo") {
+            // A create-undo (no restoreFrom): the move alone archives the
+            // skill; an edit-undo stages the before-snapshot into place.
+            if (restoreFrom !== undefined) {
+                const staged = await this.stageVersion(restoreFrom);
+                await rm(beforeRoot, { recursive: true, force: true });
+                await mkdir(dirname(afterRoot), { recursive: true });
+                await rename(staged, afterRoot);
+            }
+            else {
+                await mkdir(dirname(afterRoot), { recursive: true });
+                await rename(beforeRoot, afterRoot);
+            }
+            if (afterRoot.startsWith(this.archive + "/"))
+                state.archived = [...new Set([...state.archived, name])];
+            else
+                state.archived = state.archived.filter((item) => item !== name);
+        }
+        let after;
+        if (action !== "archive") {
+            after = await nextVersion(this.root, name);
+            const current = afterRoot ?? beforeRoot;
+            await copyTree(current, join(versionRoot, after));
+            await writeFile(join(versionRoot, after, ".location"), state.archived.includes(name) ? "archive" : "skills");
+        }
+        await writeState(this.root, state);
+        const entry = { id: randomUUID(), at: this.options.now().toISOString(), actor: meta.actor, action, skill: name, ...(absorbedInto === undefined && meta.reason === undefined ? {} : { reason: absorbedInto ?? meta.reason }), ...(meta.reviewId === undefined ? {} : { reviewId: meta.reviewId }), ...(meta.conversationId === undefined ? {} : { conversationId: meta.conversationId }), ...(before === undefined ? {} : { before }), ...(after === undefined ? {} : { after }) };
+        await this.appendFeed(entry);
+        const versions = (await readdir(versionRoot)).filter((entry) => /^v\d+$/.test(entry)).sort((a, b) => Number(b.slice(1)) - Number(a.slice(1)));
+        for (const old of versions.slice(VERSIONS))
+            await rm(join(versionRoot, old), { recursive: true, force: true });
+        return entry;
+    }
+    /** Copies a version snapshot to a staging directory, minus the `.location` metadata file. */
+    async stageVersion(version) {
+        const staged = join(this.root, `.staged-${randomUUID()}`);
+        await copyTree(version, staged);
+        await rm(join(staged, ".location"), { force: true });
+        return staged;
+    }
+    async appendFeed(entry) {
+        await mkdir(this.root, { recursive: true });
+        const entries = (await readFeed(this.root)).reverse();
+        entries.push(entry);
+        await writeFileAtomic(join(this.root, "feed.jsonl"), entries.slice(-FEED_ENTRIES).map((item) => JSON.stringify(item)).join("\n") + "\n");
+    }
+}

package/dist/curation/targets.js

@@ -0,0 +1,77 @@
+/**
+ * The curation-target registry (curator P7, spec §6.5): the boot-built
+ * view over every loaded extension's `curationTargets` declaration.
+ *
+ * The loader validates each declaration (a target without `undo`, a
+ * tool the extension does not register, or a duplicate qualified id
+ * quarantines the WHOLE extension before anything is collected); boot
+ * folds the surviving bindings into ONE {@link CurationRegistry} and
+ * exposes it on the opened harness.
+ *
+ * `isCurationTool` is the A8 wrapping feed: `true` for `skill_manage`
+ * and every LISTED target tool, `false` for everything else — an
+ * extension's unlisted direct write tools (a "remember this" path the
+ * extension owns itself) are never intercepted, never gated, never
+ * undone by the curator.
+ */
+/**
+ * The registered tool names that are curation tools by core ownership.
+ * Exported for the A8 wrap feed's seed (the feed starts with the core
+ * set and grows as the loader validates target tools).
+ */
+export const CORE_CURATION_TOOLS = new Set([
+    "skill_manage",
+]);
+/** The boot-built registry over the loaded curation targets. */
+export class CurationRegistry {
+    #targets;
+    #tools;
+    constructor(targets) {
+        this.#targets = [...targets];
+        const tools = new Set(CORE_CURATION_TOOLS);
+        for (const target of this.#targets) {
+            for (const tool of target.tools)
+                tools.add(tool);
+        }
+        this.#tools = tools;
+    }
+    /** Every registered target, in load order. */
+    targets() {
+        return this.#targets;
+    }
+    /** The target a tool belongs to, or `undefined` when it is none. */
+    byTool(tool) {
+        return this.#targets.find((target) => target.tools.includes(tool));
+    }
+    /**
+     * Whether a tool is a curation tool: `skill_manage` and every listed
+     * target tool — the A8 wrapping feed. An extension's unlisted tools
+     * are never curation tools.
+     */
+    isCurationTool(tool) {
+        return this.#tools.has(tool);
+    }
+}
+/**
+ * Fold per-extension curation-target bindings into one registry. The
+ * loader quarantined every invalid declaration, so this pass only
+ * attributes: each target gains its qualified id (`<slug>:<name>`) and
+ * the extension slug. A duplicate qualified id here is a loader bug
+ * (the load-time check already rejected it) — it fails loud rather
+ * than shadowing.
+ */
+export function buildCurationRegistry(bindings) {
+    const targets = [];
+    const seen = new Set();
+    for (const binding of bindings) {
+        for (const target of binding.targets) {
+            const id = `${binding.extension}:${target.name}`;
+            if (seen.has(id)) {
+                throw new Error(`duplicate curation target id "${id}" — the loader already rejected this; a second arrival is a boot bug`);
+            }
+            seen.add(id);
+            targets.push({ ...target, id, extension: binding.extension });
+        }
+    }
+    return new CurationRegistry(targets);
+}

package/dist/curation/usage.js

@@ -0,0 +1,124 @@
+/**
+ * Usage telemetry (curator P4, spec §6.4): per-user counters of how the
+ * owner's skills are USED — `load_skill` calls, `/skill:` expansions
+ * and core `read`-tool reads inside the learned root. The curator's
+ * ranking input (what to keep, what to archive: a skill nobody loads is
+ * a candidate; a `load_skill`-heavy, `read`-light skill is healthy).
+ *
+ * Storage: `curationDir/usage.json`, one `{skill: {load, expand, read,
+ * lastUsed}}` record per skill, written at most once per 10 s per user
+ * (the data is advisory — no reason to hammer the disk on every load).
+ * `bump` accumulates in memory; `flush` merges the pending bumps over
+ * the file's current contents and writes, so a fresh process (a restart,
+ * a second server) keeps counting from what was flushed.
+ *
+ * Known gap (documented): `bash cat` of a learned file does NOT count —
+ * the shell path never sees a skill-shaped read. Only the three
+ * model-facing seams bump.
+ */
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { curationDir } from "./paths.js";
+/** The flush interval: writes at most once per 10 s per user. */
+const FLUSH_INTERVAL_MS = 10_000;
+const KINDS = ["load", "expand", "read"];
+/**
+ * The per-user usage counters. `bump` is in-memory bookkeeping; `flush`
+ * persists to `curationDir/usage.json`, a no-op inside the 10 s window
+ * since the last successful write. The counting seams bump and flush
+ * opportunistically (the throttle keeps it cheap); a process exit loses
+ * at most the last window's advisory data — accepted.
+ */
+export class UsageCounters {
+    options;
+    /** Bumps since the last successful flush (per skill). */
+    pending = new Map();
+    /** The last flushed state, as far as this instance knows. */
+    flushed = {};
+    lastFlush;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Count one use of one skill. */
+    bump(skill, kind) {
+        const at = this.now().toISOString();
+        const current = this.pending.get(skill);
+        const next = current === undefined
+            ? { load: 0, expand: 0, read: 0, lastUsed: at }
+            : { ...current, lastUsed: at };
+        next[kind] += 1;
+        this.pending.set(skill, next);
+    }
+    /** The skill's most recent use, ISO 8601; `undefined` when never. */
+    lastUsed(skill) {
+        void this.options.user;
+        const pending = this.pending.get(skill);
+        if (pending !== undefined)
+            return pending.lastUsed;
+        return this.flushed[skill]?.lastUsed;
+    }
+    /**
+     * Persist the pending bumps, merged over the file's CURRENT contents
+     * (a concurrent or earlier process's counts survive). A no-op inside
+     * the 10 s window since the last successful write.
+     */
+    async flush() {
+        const at = this.now().getTime();
+        if (this.lastFlush !== undefined &&
+            at - this.lastFlush < FLUSH_INTERVAL_MS) {
+            return;
+        }
+        // Fail closed for a removed user (deletion's Review Focus): the
+        // cached counters stay resolvable after `removeUserCuration`, so an
+        // in-flight seam's late flush would recreate the deleted directory
+        // as orphan state. Drop SILENTLY — telemetry must never throw into
+        // the void-and-forget counting seams — including the
+        // deadline-forced path. The gate sits AFTER the in-memory throttle
+        // (it reads the live directory synchronously, and the seams call
+        // flush opportunistically on every counted read — the cheap check
+        // must come first) but BEFORE any disk op, so nothing lands for a
+        // user who is gone. A dropped flush neither clears `pending` nor
+        // arms `lastFlush`: a later call re-checks the gate, so if the user
+        // somehow exists again the counting simply resumes.
+        if (this.options.userExists !== undefined && !this.options.userExists()) {
+            return;
+        }
+        const disk = await this.readDisk();
+        const merged = { ...disk };
+        for (const [skill, bumps] of this.pending) {
+            const previous = disk[skill];
+            const record = { ...(previous ?? {}) };
+            for (const kind of KINDS) {
+                if (bumps[kind] > 0) {
+                    record[kind] = (previous?.[kind] ?? 0) + bumps[kind];
+                }
+            }
+            record.lastUsed = bumps.lastUsed;
+            merged[skill] = record;
+        }
+        const path = join(curationDir(this.options.userArea), "usage.json");
+        await mkdir(join(path, ".."), { recursive: true });
+        const temp = `${path}.${randomUUID()}.tmp`;
+        await writeFile(temp, `${JSON.stringify(merged, null, 2)}\n`);
+        await rename(temp, path);
+        this.pending.clear();
+        this.flushed = merged;
+        this.lastFlush = at;
+    }
+    now() {
+        return this.options.now?.() ?? new Date();
+    }
+    /** Read the file's current contents; `{}` when absent or unreadable. */
+    async readDisk() {
+        try {
+            const text = await readFile(join(curationDir(this.options.userArea), "usage.json"), "utf8");
+            const parsed = JSON.parse(text);
+            return parsed;
+        }
+        catch {
+            return {};
+        }
+    }
+}