dsh-continual-evolve 0.15.5 → 0.15.7

package/lib/store-apply.js

@@ -11,13 +11,14 @@ function recordOf(row) {
         sourceSession: row.source_session,
         sourceSeqs: row.source_seqs,
         sourceRun: row.source_run,
+        corrects: row.corrects ?? null,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
     };
 }
-const INSERT_SQL = "INSERT INTO memories (workspace_id, id, type, title, description, body, status, source_session, source_seqs, source_run, created_at, updated_at) " +
-    "VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)";
-const UPDATE_SQL = "UPDATE memories SET type = ?, title = ?, description = ?, body = ?, updated_at = ? WHERE workspace_id = ? AND id = ?";
+const INSERT_SQL = "INSERT INTO memories (workspace_id, id, type, title, description, body, status, source_session, source_seqs, source_run, corrects, created_at, updated_at) " +
+    "VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?)";
+const UPDATE_SQL = "UPDATE memories SET type = ?, title = ?, description = ?, body = ?, corrects = COALESCE(?, corrects), updated_at = ? WHERE workspace_id = ? AND id = ?";
 const DELETE_SQL = "DELETE FROM memories WHERE workspace_id = ? AND id = ?";
 const FTS_DROP_SQL = "DELETE FROM memories_fts WHERE rowid IN (SELECT rowid FROM memories_fts WHERE workspace_id = ? AND id = ?)";
 const FTS_INSERT_SQL = "INSERT INTO memories_fts (workspace_id, id, title, description, body) " +
@@ -99,6 +100,10 @@ function applyOne(db, ctx, proposal, stmts, files) {
     if ("reason" in fields) {
         return fail(proposal, fields.reason);
     }
+    const link = checkCorrects(stmts.get, ctx.workspaceId, proposal, id);
+    if ("reason" in link) {
+        return fail(proposal, link.reason);
+    }
     const reasons = fieldGateReasons(fields.fields);
     if (reasons.length > 0) {
         return fail(proposal, reasons[0] ?? "invalid record");
@@ -108,7 +113,7 @@ function applyOne(db, ctx, proposal, stmts, files) {
             return fail(proposal, `memory "${id}" already exists — update it instead of creating a duplicate`);
         }
         const now = db.now();
-        stmts.insert.run(ctx.workspaceId, id, fields.fields.type, fields.fields.title, fields.fields.description, fields.fields.body, ctx.sessionId ?? null, proposal.sourceSeqs ?? null, ctx.runId ?? (ctx.trigger === "explicit" ? "explicit" : null), now, now);
+        stmts.insert.run(ctx.workspaceId, id, fields.fields.type, fields.fields.title, fields.fields.description, fields.fields.body, ctx.sessionId ?? null, proposal.sourceSeqs ?? null, ctx.runId ?? (ctx.trigger === "explicit" ? "explicit" : null), link.value, now, now);
         syncFts(db, ctx.workspaceId, id);
         files.push({
             id,
@@ -122,7 +127,7 @@ function applyOne(db, ctx, proposal, stmts, files) {
     if (existing === undefined) {
         return fail(proposal, `no memory "${id}" to update — create it instead`);
     }
-    stmts.update.run(fields.fields.type, fields.fields.title, fields.fields.description, fields.fields.body, db.now(), ctx.workspaceId, id);
+    stmts.update.run(fields.fields.type, fields.fields.title, fields.fields.description, fields.fields.body, link.value, db.now(), ctx.workspaceId, id);
     syncFts(db, ctx.workspaceId, id);
     files.push({ id, action, before: existing, after: recordOf(stmts.get.get(ctx.workspaceId, id)) });
     return { id, action, ok: true };
@@ -131,6 +136,36 @@ function applyOne(db, ctx, proposal, stmts, files) {
 function fail(proposal, reason) {
     return { id: proposal.id ?? "", action: proposal.action, ok: false, reason };
 }
+/**
+ * Resolve the correction link: absent (or explicitly empty-checked) proposals
+ * carry `null`, which keeps an existing link on update and stores null on
+ * create. A named target must be a well-formed id in the same workspace,
+ * must exist, must be active, and must not be the row itself.
+ */
+function checkCorrects(get, workspaceId, proposal, id) {
+    const raw = proposal.corrects;
+    if (raw === undefined) {
+        return { value: null };
+    }
+    const target = raw.trim();
+    if (target.length === 0) {
+        return { reason: "corrects must not be empty — omit it instead" };
+    }
+    if (!isValidMemoryId(target)) {
+        return { reason: `malformed corrects target "${target}"` };
+    }
+    if (target === id) {
+        return { reason: `memory "${id}" cannot correct itself` };
+    }
+    const row = get.get(workspaceId, target);
+    if (row === undefined) {
+        return { reason: `no memory "${target}" to correct` };
+    }
+    if (row.status !== "active") {
+        return { reason: `memory "${target}" is not active and cannot be corrected` };
+    }
+    return { value: target };
+}
 /** The proposal id, derived from the title (slug, CJK-hash fallback) on create. */
 function idFor(proposal) {
     if (proposal.id !== undefined && proposal.id.trim().length > 0) {

package/lib/store.d.ts

@@ -43,6 +43,58 @@ export interface SkillFileWarning {
     id: string;
     warning: string;
 }
+/** Aggregate consumption of one skill (the V2 usage loop's only counter). */
+export interface SkillUse {
+    useCount: number;
+    /** ISO instant of the last counted use, `null` when never consumed. */
+    lastUsedAt: string | null;
+}
+/** One per-item content-review verdict (the `item-review` account's row). */
+export interface ReviewLogEntry {
+    runId?: string | undefined;
+    workspaceId?: string | undefined;
+    itemKind: "memory" | "skill";
+    itemId: string;
+    verdict: "keep" | "rewrite" | "quarantine" | "skip";
+    reason?: string | undefined;
+    /** Normalized usage JSON of the cheap gate call, `undefined` when skipped before any call. */
+    cheapUsage?: unknown;
+    /** Normalized usage JSON of the evolve call, `undefined` unless rewritten. */
+    evolveUsage?: unknown;
+    /** Whether the rewrite landed (1) or the row is verdict-only (0). */
+    applied?: number | undefined;
+    /** How many times this item has evolved including this run. */
+    evolveCount?: number | undefined;
+}
+/** One day of the hard-cap account (UTC `YYYY-MM-DD`, budget = 100). */
+export interface DailyStats {
+    day: string;
+    budget: number;
+    reviewed: number;
+    newItems: number;
+    requeued: number;
+    approved: number;
+    applied: number;
+    cheapToken: number;
+    evolveToken: number;
+    backlog: number;
+    dropped: number;
+    /** JSON array of the top skip reasons, `null` when none. */
+    skipTop: string | null;
+}
+/** Additive counters merged into today's rollup by one run. */
+export interface DailyDelta {
+    newItems?: number | undefined;
+    requeued?: number | undefined;
+    approved?: number | undefined;
+    applied?: number | undefined;
+    cheapToken?: number | undefined;
+    evolveToken?: number | undefined;
+    /** Queue depth after the run (set, not added). */
+    backlog?: number | undefined;
+    dropped?: number | undefined;
+    skipReasons?: string[] | undefined;
+}
 /** One stored memory record (snake_case columns camelCased). */
 export interface MemoryRecord {
     workspaceId: string;
@@ -58,6 +110,8 @@ export interface MemoryRecord {
     sourceSeqs: string | null;
     /** The extraction run that wrote it; `'explicit'` for tool writes. */
     sourceRun: string | null;
+    /** Id of the memory this row corrects/supersedes in the same workspace, `null` when standalone. */
+    corrects: string | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -71,7 +125,7 @@ export interface LedgerEntry {
     runId?: string | undefined;
     sessionId?: string | undefined;
     workspaceId?: string | undefined;
-    trigger: "turn-debounce" | "compaction" | "close-drain" | "explicit" | "import";
+    trigger: "turn-debounce" | "compaction" | "close-drain" | "explicit" | "import" | "item-review";
     decision?: string | undefined;
     skipReason?: string | undefined;
     status?: string | undefined;
@@ -173,6 +227,48 @@ export interface MemoryStore {
     };
     /** Partitions holding active skills (the card's skill fence). */
     listSkillWorkspaces(): WorkspaceSummary[];
+    /**
+     * Record one real skill consumption (a body served by id, never a list
+     * or search hit). Accounting never fails the read — failures degrade
+     * silently, exactly like file sync never fails a write batch.
+     */
+    recordSkillUse(workspaceId: string, skillId: string, scope: string): void;
+    /** Aggregate usage for one skill, undefined when never consumed. */
+    getSkillUse(workspaceId: string, skillId: string, scope: string): SkillUse | undefined;
+    /**
+     * Record one real memory consumption (a body served by id, never a list
+     * or search hit). Same heartbeat discipline as skill usage: accounting
+     * never fails the read it rides on.
+     */
+    recordMemoryUse(workspaceId: string, memoryId: string): void;
+    /** Aggregate usage for one memory, undefined when never consumed. */
+    getMemoryUse(workspaceId: string, memoryId: string): SkillUse | undefined;
+    /** Append one per-item content-review verdict (the `item-review` account). */
+    logReview(entry: ReviewLogEntry): void;
+    /**
+     * Atomically consume one unit of today's review budget: returns the
+     * remaining budget after consumption, or -1 when the day is exhausted
+     * (the caller drops the low-priority item and counts it as dropped).
+     */
+    consumeReviewBudget(day: string, budget: number): number;
+    /** Today's rollup row, undefined when nothing ran yet today. */
+    getDaily(day: string): DailyStats | undefined;
+    /** Merge one run's counters into today's rollup row (upsert, additive). */
+    mergeDaily(day: string, budget: number, delta: DailyDelta): void;
+    /**
+     * Soft-isolate one item (review quarantine verdict): hidden from
+     * injection and reads, never deleted — the ledger keeps the before
+     * snapshot for undo. Returns false when the row is absent.
+     */
+    quarantine(workspaceId: string, kind: "memory" | "skill", id: string): boolean;
+    /**
+     * The review history of one item: last verdict instant and landed
+     * rewrite count, undefined when never reviewed (a new item).
+     */
+    reviewStateOf(workspaceId: string, kind: "memory" | "skill", id: string): {
+        lastTs: string | null;
+        evolveCount: number;
+    } | undefined;
 }
 /** Default database location: `$DSH_HOME/evolve/memory.db`, else `~/.dsh/…`. */
 export declare function defaultStorePath(): string;

package/lib/store.js

@@ -51,6 +51,7 @@ PRAGMA busy_timeout=5000;CREATE TABLE IF NOT EXISTS memories (
   source_session TEXT,
   source_seqs TEXT,
   source_run TEXT,
+  corrects TEXT,
   created_at TEXT NOT NULL,
   updated_at TEXT NOT NULL,
   PRIMARY KEY (workspace_id, id)
@@ -66,7 +67,7 @@ CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
 -- patrol() reconciles any residue.
 CREATE TABLE IF NOT EXISTS extraction_log (
   run_id TEXT, ts TEXT NOT NULL, session_id TEXT, workspace_id TEXT,
-  trigger TEXT CHECK (trigger IN ('turn-debounce','compaction','close-drain','explicit','import')),
+  trigger TEXT CHECK (trigger IN ('turn-debounce','compaction','close-drain','explicit','import','item-review')),
   decision TEXT, skip_reason TEXT,
   status TEXT, duration_ms INTEGER, model TEXT, usage TEXT,
   files TEXT, occurrences INTEGER NOT NULL DEFAULT 1
@@ -100,6 +101,55 @@ CREATE TABLE IF NOT EXISTS skill_log (
   run_id TEXT, ts TEXT NOT NULL, session_id TEXT, workspace_id TEXT,
   trigger TEXT, decision TEXT, status TEXT, files TEXT, warnings TEXT
 );
+-- Skill usage counters (V2 usage loop): one aggregate row per skill, never a
+-- per-hit ledger, so the table cannot grow without bound and needs no prune.
+CREATE TABLE IF NOT EXISTS skill_usage (
+  workspace_id TEXT NOT NULL,
+  skill_id TEXT NOT NULL,
+  scope TEXT NOT NULL CHECK (scope IN ('project','global')),
+  use_count INTEGER NOT NULL DEFAULT 0,
+  last_used_at TEXT,
+  PRIMARY KEY (workspace_id, skill_id, scope)
+) STRICT;
+-- Memory usage counters (content-quality loop): one aggregate row per memory,
+-- the same presence-heartbeat discipline as skill_usage — a body served by id
+-- counts, search/list hits stay uncounted.
+CREATE TABLE IF NOT EXISTS memory_usage (
+  workspace_id TEXT NOT NULL,
+  memory_id TEXT NOT NULL,
+  use_count INTEGER NOT NULL DEFAULT 0,
+  last_used_at TEXT,
+  PRIMARY KEY (workspace_id, memory_id)
+) STRICT;
+-- Per-item content-review verdicts (the item-review trigger's account):
+-- one row per reviewed item per run. Pruned with the ledgers.
+CREATE TABLE IF NOT EXISTS review_log (
+  run_id TEXT, ts TEXT NOT NULL, workspace_id TEXT,
+  item_kind TEXT NOT NULL CHECK (item_kind IN ('memory','skill')),
+  item_id TEXT NOT NULL,
+  verdict TEXT NOT NULL CHECK (verdict IN ('keep','rewrite','quarantine','skip')),
+  reason TEXT,
+  cheap_usage TEXT, evolve_usage TEXT,
+  applied INTEGER NOT NULL DEFAULT 0,
+  evolve_count INTEGER NOT NULL DEFAULT 0
+);
+-- One rollup row per UTC day: the hard-cap account (budget vs reviewed vs
+-- backlog vs dropped) plus the token account split by cheap/evolve purpose.
+CREATE TABLE IF NOT EXISTS review_daily (
+  day TEXT NOT NULL PRIMARY KEY,
+  budget INTEGER NOT NULL,
+  reviewed INTEGER NOT NULL DEFAULT 0,
+  new_items INTEGER NOT NULL DEFAULT 0,
+  requeued INTEGER NOT NULL DEFAULT 0,
+  approved INTEGER NOT NULL DEFAULT 0,
+  applied INTEGER NOT NULL DEFAULT 0,
+  cheap_token INTEGER NOT NULL DEFAULT 0,
+  evolve_token INTEGER NOT NULL DEFAULT 0,
+  backlog INTEGER NOT NULL DEFAULT 0,
+  dropped INTEGER NOT NULL DEFAULT 0,
+  skip_top TEXT,
+  skip_counts TEXT
+) STRICT;
 `;
 /** Default database location: `$DSH_HOME/evolve/memory.db`, else `~/.dsh/…`. */
 export function defaultStorePath() {
@@ -118,6 +168,7 @@ function recordOf(row) {
         sourceSession: row.source_session,
         sourceSeqs: row.source_seqs,
         sourceRun: row.source_run,
+        corrects: row.corrects ?? null,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
     };
@@ -248,6 +299,7 @@ export async function openMemoryStore(explicitPath) {
     }
     database.exec(DDL);
     ensureLedgerOccurrences(database);
+    ensureMemoriesCorrects(database);
     const stmts = {
         get: database.prepare("SELECT * FROM memories WHERE workspace_id = ? AND id = ?"),
         list: database.prepare(`SELECT * FROM memories WHERE workspace_id = ? AND status = 'active' ${LIST_ORDER}`),
@@ -296,6 +348,25 @@ export async function openMemoryStore(explicitPath) {
         skillActiveRows: database.prepare("SELECT * FROM skills WHERE status = 'active'"),
         skillQuarantine: database.prepare("UPDATE skills SET status = 'quarantined' WHERE workspace_id = ? AND id = ?"),
         skillWorkspaces: database.prepare("SELECT workspace_id, COUNT(*) AS n, MAX(updated_at) AS u FROM skills WHERE status = 'active' GROUP BY workspace_id ORDER BY u DESC"),
+        skillUseGet: database.prepare("SELECT use_count, last_used_at FROM skill_usage WHERE workspace_id = ? AND skill_id = ? AND scope = ?"),
+        skillUseUpsert: database.prepare("INSERT INTO skill_usage (workspace_id, skill_id, scope, use_count, last_used_at) VALUES (?, ?, ?, 1, ?) " +
+            "ON CONFLICT (workspace_id, skill_id, scope) DO UPDATE SET use_count = use_count + 1, last_used_at = excluded.last_used_at"),
+        memUseGet: database.prepare("SELECT use_count, last_used_at FROM memory_usage WHERE workspace_id = ? AND memory_id = ?"),
+        memUseUpsert: database.prepare("INSERT INTO memory_usage (workspace_id, memory_id, use_count, last_used_at) VALUES (?, ?, 1, ?) " +
+            "ON CONFLICT (workspace_id, memory_id) DO UPDATE SET use_count = use_count + 1, last_used_at = excluded.last_used_at"),
+        reviewLog: database.prepare("INSERT INTO review_log (run_id, ts, workspace_id, item_kind, item_id, verdict, reason, cheap_usage, evolve_usage, applied, evolve_count) " +
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"),
+        reviewLast: database.prepare("SELECT ts, applied FROM review_log WHERE workspace_id IS ? AND item_kind = ? AND item_id = ? ORDER BY rowid DESC LIMIT 1"),
+        reviewEvolved: database.prepare("SELECT COUNT(*) AS n FROM review_log WHERE workspace_id IS ? AND item_kind = ? AND item_id = ? AND applied = 1"),
+        reviewPrune: database.prepare("DELETE FROM review_log WHERE ts < ?"),
+        dailyGet: database.prepare("SELECT * FROM review_daily WHERE day = ?"),
+        dailyUpsert: database.prepare("INSERT INTO review_daily (day, budget, reviewed, new_items, requeued, approved, applied, cheap_token, evolve_token, backlog, dropped, skip_top, skip_counts) " +
+            "VALUES (?, ?, 0, 0, 0, 0, 0, 0, 0, 0, 0, NULL, NULL) " +
+            "ON CONFLICT (day) DO UPDATE SET budget = excluded.budget"),
+        dailyConsume: database.prepare("UPDATE review_daily SET reviewed = reviewed + 1 WHERE day = ? AND reviewed < budget"),
+        dailyMerge: database.prepare("UPDATE review_daily SET new_items = new_items + ?, requeued = requeued + ?, " +
+            "approved = approved + ?, applied = applied + ?, cheap_token = cheap_token + ?, evolve_token = evolve_token + ?, " +
+            "backlog = ?, dropped = dropped + ?, skip_top = ?, skip_counts = ? WHERE day = ?"),
     };
     // LIKE fallback: one OR-triplet per token, every token required. Statements
     // are cached by token count — the query set repeats, the counts don't grow.
@@ -710,7 +781,8 @@ export async function openMemoryStore(explicitPath) {
         pruneLedger(beforeIso) {
             const memory = Number(stmts.prune.run(beforeIso).changes);
             const skills = Number(stmts.skillPrune.run(beforeIso).changes);
-            return memory + skills;
+            const reviews = Number(stmts.reviewPrune.run(beforeIso).changes);
+            return memory + skills + reviews;
         },
         close() {
             database.close();
@@ -787,6 +859,108 @@ export async function openMemoryStore(explicitPath) {
                 updatedAt: row.u,
             }));
         },
+        recordSkillUse(workspaceId, skillId, scope) {
+            try {
+                stmts.skillUseUpsert.run(workspaceId, skillId, scope, new Date().toISOString());
+            }
+            catch {
+                // Accounting never fails the read it rides on.
+            }
+        },
+        getSkillUse(workspaceId, skillId, scope) {
+            try {
+                const row = stmts.skillUseGet.get(workspaceId, skillId, scope);
+                if (row === undefined) {
+                    return undefined;
+                }
+                return { useCount: row.use_count, lastUsedAt: row.last_used_at };
+            }
+            catch {
+                return undefined;
+            }
+        },
+        recordMemoryUse(workspaceId, memoryId) {
+            try {
+                stmts.memUseUpsert.run(workspaceId, memoryId, new Date().toISOString());
+            }
+            catch {
+                // Accounting never fails the read it rides on.
+            }
+        },
+        getMemoryUse(workspaceId, memoryId) {
+            try {
+                const row = stmts.memUseGet.get(workspaceId, memoryId);
+                if (row === undefined) {
+                    return undefined;
+                }
+                return { useCount: row.use_count, lastUsedAt: row.last_used_at };
+            }
+            catch {
+                return undefined;
+            }
+        },
+        logReview(entry) {
+            stmts.reviewLog.run(entry.runId ?? null, new Date().toISOString(), entry.workspaceId ?? null, entry.itemKind, entry.itemId, entry.verdict, entry.reason ?? null, entry.cheapUsage === undefined ? null : JSON.stringify(entry.cheapUsage), entry.evolveUsage === undefined ? null : JSON.stringify(entry.evolveUsage), entry.applied ?? 0, entry.evolveCount ?? 0);
+        },
+        consumeReviewBudget(day, budget) {
+            stmts.dailyUpsert.run(day, budget);
+            const result = stmts.dailyConsume.run(day);
+            if (Number(result.changes) === 0) {
+                return -1;
+            }
+            const row = stmts.dailyGet.get(day);
+            if (row === undefined) {
+                return -1;
+            }
+            return row.budget - row.reviewed;
+        },
+        getDaily(day) {
+            const row = stmts.dailyGet.get(day);
+            if (row === undefined) {
+                return undefined;
+            }
+            return {
+                day: row.day, budget: row.budget, reviewed: row.reviewed, newItems: row.new_items,
+                requeued: row.requeued, approved: row.approved, applied: row.applied,
+                cheapToken: row.cheap_token, evolveToken: row.evolve_token,
+                backlog: row.backlog, dropped: row.dropped, skipTop: row.skip_top,
+            };
+        },
+        mergeDaily(day, budget, delta) {
+            stmts.dailyUpsert.run(day, budget);
+            const row = stmts.dailyGet.get(day);
+            const counts = parseCounts(row.skip_counts);
+            for (const reason of delta.skipReasons ?? []) {
+                counts[reason] = (counts[reason] ?? 0) + 1;
+            }
+            const entries = Object.entries(counts)
+                .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+                .slice(0, 3)
+                .map(([reason]) => reason);
+            stmts.dailyMerge.run(delta.newItems ?? 0, delta.requeued ?? 0, delta.approved ?? 0, delta.applied ?? 0, delta.cheapToken ?? 0, delta.evolveToken ?? 0, delta.backlog ?? row.backlog, delta.dropped ?? 0, entries.length > 0 ? JSON.stringify(entries) : row.skip_top, Object.keys(counts).length > 0 ? JSON.stringify(counts) : null, day);
+        },
+        quarantine(workspaceId, kind, id) {
+            try {
+                const result = (kind === "memory" ? stmts.quarantine : stmts.skillQuarantine).run(workspaceId, id);
+                return Number(result.changes) > 0;
+            }
+            catch {
+                return false;
+            }
+        },
+        reviewStateOf(workspaceId, kind, id) {
+            try {
+                const last = stmts.reviewLast.get(workspaceId, kind, id);
+                if (last === undefined) {
+                    return undefined;
+                }
+                const evolved = stmts.reviewEvolved.get(workspaceId, kind, id);
+                return { lastTs: last.ts, evolveCount: Number(evolved.n) };
+            }
+            catch {
+                return undefined;
+            }
+        },
     };
     return store;
 }
@@ -802,6 +976,40 @@ function ensureLedgerOccurrences(database) {
     }
     database.exec(`ALTER TABLE extraction_log ADD COLUMN ${LEDGER_OCCURRENCES} INTEGER NOT NULL DEFAULT 1`);
 }
+/**
+ * Add the memories `corrects` link column to a store created before the
+ * correction-linking field existed. Same single-migration discipline as the
+ * ledger occurrences column above.
+ */
+function ensureMemoriesCorrects(database) {
+    const columns = database.prepare("SELECT name FROM pragma_table_info('memories')").all();
+    if (columns.some((column) => column.name === "corrects")) {
+        return;
+    }
+    database.exec("ALTER TABLE memories ADD COLUMN corrects TEXT");
+}
+/** Parse the daily skip-counts map; corrupt payloads degrade to empty. */
+function parseCounts(raw) {
+    if (raw === null) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return {};
+        }
+        const counts = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+                counts[key] = Math.floor(value);
+            }
+        }
+        return counts;
+    }
+    catch {
+        return {};
+    }
+}
 /** JSON-encode the optional ledger fields and insert the row (never throws past a warn). */
 function writeLedger(stmt, entry) {
     stmt.run(entry.runId ?? null, new Date().toISOString(), entry.sessionId ?? null, entry.workspaceId ?? null, entry.trigger, entry.decision ?? null, entry.skipReason ?? null, entry.status ?? null, entry.durationMs ?? null, entry.model ?? null, entry.usage === undefined ? null : JSON.stringify(entry.usage), entry.files === undefined ? null : JSON.stringify(entry.files));

package/lib/token-usage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The single accounting entry for direct LLM calls (the `token-usage.ts`
+ * the coding standard names). Observed provider payloads disagree on keys —
+ * `inputTokens`/`outputTokens` are usual, `totalTokens`, `cacheReadTokens`,
+ * `cacheWriteTokens`, and `reasoningTokens` come and go — so every call site
+ * normalizes through {@link normalizeUsage} and aggregates with
+ * {@link sumUsage}. Nothing here touches the store: per-day aggregation over
+ * ledger rows lives in the review daily rollup, which stays read-only and
+ * bounded (one row per day).
+ */
+/** Token counts for one LLM call, every field present, zeros when unknown. */
+export interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    reasoning: number;
+    total: number;
+}
+/** The zero value: no signal, not a failure. */
+export declare function zeroUsage(): UsageTotals;
+/**
+ * Normalize one provider usage payload to full totals. Returns `null` when
+ * the payload carries no usable numeric signal at all (not an object, or an
+ * object with no recognized numeric field) — callers treat that as "no
+ * accounting for this run", never as zeros that would dilute real totals.
+ */
+export declare function normalizeUsage(raw: unknown): UsageTotals | null;
+/** Pure field-wise sum; either side may be a zero value. */
+export declare function sumUsage(a: UsageTotals, b: UsageTotals): UsageTotals;
+//# sourceMappingURL=token-usage.d.ts.map

package/lib/token-usage.js

@@ -0,0 +1,59 @@
+/**
+ * The single accounting entry for direct LLM calls (the `token-usage.ts`
+ * the coding standard names). Observed provider payloads disagree on keys —
+ * `inputTokens`/`outputTokens` are usual, `totalTokens`, `cacheReadTokens`,
+ * `cacheWriteTokens`, and `reasoningTokens` come and go — so every call site
+ * normalizes through {@link normalizeUsage} and aggregates with
+ * {@link sumUsage}. Nothing here touches the store: per-day aggregation over
+ * ledger rows lives in the review daily rollup, which stays read-only and
+ * bounded (one row per day).
+ */
+/** The zero value: no signal, not a failure. */
+export function zeroUsage() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, total: 0 };
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+/**
+ * Normalize one provider usage payload to full totals. Returns `null` when
+ * the payload carries no usable numeric signal at all (not an object, or an
+ * object with no recognized numeric field) — callers treat that as "no
+ * accounting for this run", never as zeros that would dilute real totals.
+ */
+export function normalizeUsage(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        return null;
+    }
+    const payload = raw;
+    const input = num(payload.inputTokens);
+    const output = num(payload.outputTokens);
+    const cacheRead = num(payload.cacheReadTokens);
+    const cacheWrite = num(payload.cacheWriteTokens);
+    const reasoning = num(payload.reasoningTokens);
+    const recognized = [input, output, cacheRead, cacheWrite, reasoning].some((n) => n > 0);
+    const totalRaw = num(payload.totalTokens);
+    if (!recognized && totalRaw === 0) {
+        return null;
+    }
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        reasoning,
+        total: totalRaw > 0 ? totalRaw : input + output,
+    };
+}
+/** Pure field-wise sum; either side may be a zero value. */
+export function sumUsage(a, b) {
+    return {
+        input: a.input + b.input,
+        output: a.output + b.output,
+        cacheRead: a.cacheRead + b.cacheRead,
+        cacheWrite: a.cacheWrite + b.cacheWrite,
+        reasoning: a.reasoning + b.reasoning,
+        total: a.total + b.total,
+    };
+}
+//# sourceMappingURL=token-usage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-continual-evolve",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "description": "ZCode-style workspace memory for DeepSeek Harness: one central SQLite store partitioned by workspace, index injection, and sole-writer gated writes.",
   "license": "MIT",
   "repository": {