crewly 1.20.302 → 1.20.304

package/dist/backend/backend/src/services/usage-ledger/unit-classifier.js

@@ -0,0 +1,263 @@
+/**
+ * Puts tickets into categories at report time.
+ *
+ * Order of attempts, cheapest first:
+ * 1. Deterministic: keywords (or the comma-separated phrases of the
+ *    description), team and project hints.
+ * 2. Only for tickets nothing matched, and only when a model is available: one
+ *    small batched question to the default cheap model.
+ * 3. Otherwise `other`.
+ *
+ * With no definitions the category is the ticket's team (else its project).
+ *
+ * Results are cached per (category-set id, ticket); a fallback `other` that
+ * came from having no model is not cached, so it is retried later. The cache
+ * lives beside the ledger and is never part of the ticket facts.
+ *
+ * @module services/usage-ledger/unit-classifier
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { atomicWriteJson } from '../../utils/file-io.utils.js';
+import { categorySetId } from './usage-categories.store.js';
+/** Category of tickets that match nothing. */
+export const OTHER_CATEGORY = 'other';
+/** Category of usage that belongs to no ticket. */
+export const NO_TICKET_CATEGORY = '(no ticket)';
+/** File with the classification cache. */
+export const CLASSIFICATION_CACHE_FILE = 'classification-cache.json';
+/** Sets kept in the cache (oldest dropped). */
+const MAX_CACHED_SETS = 6;
+/** Tickets sent to the model in one call, and calls per report. */
+const LLM_BATCH = 25;
+const LLM_MAX_CALLS = 2;
+/** Default classification (no user categories): the ticket's team, else its project. */
+export function defaultCategory(unit) {
+    return unit.team?.trim() || unit.project?.trim() || OTHER_CATEGORY;
+}
+/**
+ * Keywords of a definition: its explicit keywords, else the comma / semicolon
+ * separated phrases of its description (so "Xiaohongshu, Substack, LinkedIn"
+ * works as typed).
+ *
+ * @param def - Category definition
+ * @returns Lower-case keywords
+ */
+export function keywordsOf(def) {
+    const explicit = def.keywords ?? [];
+    const phrases = explicit.length > 0
+        ? []
+        : (def.description ?? '')
+            .split(/[,;，；、\n]+/)
+            .map((p) => p.trim())
+            .filter((p) => p.length >= 2 && p.length <= 40);
+    return [...new Set([...explicit, ...phrases].map((k) => k.toLowerCase()))];
+}
+/**
+ * Whether a lower-case text contains a keyword. Short ASCII keywords must
+ * match whole words ("ai" must not match "email").
+ */
+function hasKeyword(text, keyword) {
+    if (/^[a-z0-9 ]+$/.test(keyword) && keyword.length <= 3) {
+        return new RegExp(`(^|[^a-z0-9])${keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^a-z0-9]|$)`).test(text);
+    }
+    return text.includes(keyword);
+}
+/**
+ * Best category by keyword / team / project hints.
+ *
+ * @param unit - The ticket
+ * @param defs - Definitions
+ * @returns Category name, or null when nothing matched
+ */
+export function matchCategory(unit, defs) {
+    const text = [unit.title, unit.excerpt, unit.ticketId, unit.team, unit.project].filter(Boolean).join(' \n ').toLowerCase();
+    const team = (unit.team ?? '').toLowerCase();
+    const project = (unit.project ?? '').toLowerCase();
+    let best = null;
+    for (const def of defs) {
+        let score = 0;
+        for (const k of keywordsOf(def))
+            if (hasKeyword(text, k))
+                score += 1;
+        if (team && def.teams?.some((t) => t.toLowerCase() === team))
+            score += 2;
+        if (project && def.projects?.some((p) => p.toLowerCase() === project))
+            score += 2;
+        if (score > 0 && (!best || score > best.score))
+            best = { name: def.name, score };
+    }
+    return best?.name ?? null;
+}
+/**
+ * Classifies tickets for reports.
+ */
+export class UnitClassifier {
+    llm;
+    cacheFile;
+    cache = null;
+    /**
+     * @param dir - Ledger directory
+     * @param llm - Optional model (null: deterministic only)
+     */
+    constructor(dir, llm = null) {
+        this.llm = llm;
+        this.cacheFile = path.join(dir, CLASSIFICATION_CACHE_FILE);
+    }
+    async loadCache() {
+        if (this.cache)
+            return this.cache;
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.cacheFile, 'utf-8'));
+            this.cache = parsed && typeof parsed.sets === 'object' && parsed.sets ? parsed : { sets: {} };
+        }
+        catch {
+            this.cache = { sets: {} };
+        }
+        return this.cache;
+    }
+    /**
+     * Classify tickets.
+     *
+     * @param units - Tickets (never the "(no ticket)" pseudo-units)
+     * @param defs - The user's categories; empty means the default (team / project)
+     * @returns Category per ticket
+     */
+    async classify(units, defs) {
+        const categories = new Map();
+        if (defs.length === 0) {
+            for (const u of units)
+                categories.set(u.unitId, defaultCategory(u));
+            return { categories, llmClassified: 0, unclassified: 0 };
+        }
+        const setId = categorySetId(defs);
+        const cache = await this.loadCache();
+        const cached = cache.sets[setId] ?? {};
+        const fresh = {};
+        const unmatched = [];
+        for (const u of units) {
+            const known = cached[u.unitId];
+            if (known) {
+                categories.set(u.unitId, known);
+                continue;
+            }
+            const hit = matchCategory(u, defs);
+            if (hit) {
+                categories.set(u.unitId, hit);
+                fresh[u.unitId] = hit;
+            }
+            else {
+                unmatched.push(u);
+            }
+        }
+        let llmClassified = 0;
+        let unclassified = 0;
+        const answers = this.llm ? await this.askModel(unmatched, defs) : new Map();
+        for (const u of unmatched) {
+            const answer = answers.get(u.unitId);
+            if (answer) {
+                categories.set(u.unitId, answer);
+                fresh[u.unitId] = answer;
+                if (answer !== OTHER_CATEGORY)
+                    llmClassified += 1;
+            }
+            else {
+                categories.set(u.unitId, OTHER_CATEGORY);
+                unclassified += 1;
+            }
+        }
+        if (Object.keys(fresh).length > 0)
+            await this.saveCache(setId, fresh);
+        return { categories, llmClassified, unclassified };
+    }
+    async saveCache(setId, fresh) {
+        const cache = await this.loadCache();
+        const merged = { ...(cache.sets[setId] ?? {}), ...fresh };
+        delete cache.sets[setId];
+        cache.sets[setId] = merged;
+        for (const key of Object.keys(cache.sets).slice(0, Math.max(0, Object.keys(cache.sets).length - MAX_CACHED_SETS)))
+            delete cache.sets[key];
+        try {
+            await fs.mkdir(path.dirname(this.cacheFile), { recursive: true });
+            await atomicWriteJson(this.cacheFile, cache);
+        }
+        catch {
+            // the cache is an optimisation
+        }
+    }
+    /**
+     * Ask the model about tickets nothing matched.
+     *
+     * @returns Ticket → category (only tickets the model answered validly)
+     */
+    async askModel(units, defs) {
+        const out = new Map();
+        if (!this.llm || units.length === 0)
+            return out;
+        const names = new Map(defs.map((d) => [d.name.toLowerCase(), d.name]));
+        const catalogue = defs.map((d) => `- ${d.name}${d.description ? `: ${d.description}` : ''}`).join('\n');
+        for (let call = 0; call < LLM_MAX_CALLS; call++) {
+            const batch = units.slice(call * LLM_BATCH, (call + 1) * LLM_BATCH);
+            if (batch.length === 0)
+                break;
+            const list = batch
+                .map((u, i) => `${i + 1}. ${[u.title, u.excerpt && u.excerpt !== u.title ? u.excerpt.slice(0, 160) : '', u.team ? `(team ${u.team})` : ''].filter(Boolean).join(' | ')}`)
+                .join('\n');
+            const prompt = `Assign each work item to exactly one category, or "${OTHER_CATEGORY}" if none fits.\n\nCategories:\n${catalogue}\n\nWork items:\n${list}\n\n` +
+                `Reply with only a JSON object mapping the item number to the category name, for example {"1":"${defs[0].name}","2":"${OTHER_CATEGORY}"}.`;
+            let reply = null;
+            try {
+                reply = await this.llm(prompt);
+            }
+            catch {
+                reply = null;
+            }
+            if (!reply)
+                break;
+            const json = /\{[\s\S]*\}/.exec(reply)?.[0];
+            if (!json)
+                continue;
+            try {
+                const parsed = JSON.parse(json);
+                batch.forEach((u, i) => {
+                    const value = parsed[String(i + 1)];
+                    if (typeof value !== 'string')
+                        return;
+                    const name = value.trim().toLowerCase();
+                    if (name === OTHER_CATEGORY)
+                        out.set(u.unitId, OTHER_CATEGORY);
+                    else if (names.has(name))
+                        out.set(u.unitId, names.get(name));
+                });
+            }
+            catch {
+                // unparseable answer: those tickets stay unclassified
+            }
+        }
+        return out;
+    }
+}
+/**
+ * The default cheap model: a small Anthropic model when `ANTHROPIC_API_KEY`
+ * is set; none otherwise.
+ *
+ * @returns A question function, or null
+ */
+export function defaultCategoryLlm() {
+    if (!process.env.ANTHROPIC_API_KEY)
+        return null;
+    return async (prompt) => {
+        const { generateText } = await import('ai');
+        const { anthropic } = await import('@ai-sdk/anthropic');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const result = await generateText({ model: anthropic('claude-haiku-4-5'), prompt, abortSignal: controller.signal, maxOutputTokens: 600 });
+            return result.text;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+//# sourceMappingURL=unit-classifier.js.map

package/dist/backend/backend/src/services/usage-ledger/unit-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-classifier.js","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/unit-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAoB,MAAM,6BAA6B,CAAC;AAE9E,8CAA8C;AAC9C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AACtC,mDAAmD;AACnD,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEhD,0CAA0C;AAC1C,MAAM,CAAC,MAAM,yBAAyB,GAAG,2BAA2B,CAAC;AAErE,+CAA+C;AAC/C,MAAM,eAAe,GAAG,CAAC,CAAC;AAC1B,mEAAmE;AACnE,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,aAAa,GAAG,CAAC,CAAC;AA6BxB,wFAAwF;AACxF,MAAM,UAAU,eAAe,CAAC,IAAsB;IACrD,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,cAAc,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,GAAgB;IAC1C,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,MAAM,OAAO,GACZ,QAAQ,CAAC,MAAM,GAAG,CAAC;QAClB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC;aACtB,KAAK,CAAC,YAAY,CAAC;aACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,IAAY,EAAE,OAAe;IAChD,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,MAAM,CAAC,gBAAgB,OAAO,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAsB,EAAE,IAAmB;IACxE,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3H,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7C,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACnD,IAAI,IAAI,GAA2C,IAAI,CAAC;IACxD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC;YAAE,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;gBAAE,KAAK,IAAI,CAAC,CAAC;QACrE,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC;QACzE,IAAI,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC;QAClF,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;YAAE,IAAI,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IAClF,CAAC;IACD,OAAO,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,cAAc;IAUR;IATD,SAAS,CAAS;IAC3B,KAAK,GAAqB,IAAI,CAAC;IAEvC;;;OAGG;IACH,YACC,GAAW,EACM,MAA0B,IAAI;QAA9B,QAAG,GAAH,GAAG,CAA2B;QAE/C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;IAC5D,CAAC;IAEO,KAAK,CAAC,SAAS;QACtB,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QAClC,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAc,CAAC;YACnF,IAAI,CAAC,KAAK,GAAG,MAAM,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAC/F,CAAC;QAAC,MAAM,CAAC;YACR,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAyB,EAAE,IAAmB;QAC5D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,IAAI,KAAK;gBAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;QAC1D,CAAC;QACD,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAA2B,EAAE,CAAC;QACzC,MAAM,SAAS,GAAuB,EAAE,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC/B,IAAI,KAAK,EAAE,CAAC;gBACX,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;gBAChC,SAAS;YACV,CAAC;YACD,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YACnC,IAAI,GAAG,EAAE,CAAC;gBACT,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;gBAC9B,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACP,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACnB,CAAC;QACF,CAAC;QACD,IAAI,aAAa,GAAG,CAAC,CAAC;QACtB,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAkB,CAAC;QAC5F,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACrC,IAAI,MAAM,EAAE,CAAC;gBACZ,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBACjC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;gBACzB,IAAI,MAAM,KAAK,cAAc;oBAAE,aAAa,IAAI,CAAC,CAAC;YACnD,CAAC;iBAAM,CAAC;gBACP,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;gBACzC,YAAY,IAAI,CAAC,CAAC;YACnB,CAAC;QACF,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACtE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;IACpD,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,KAA6B;QACnE,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;QAC3B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1I,IAAI,CAAC;YACJ,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAClE,MAAM,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACR,+BAA+B;QAChC,CAAC;IACF,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,QAAQ,CAAC,KAAyB,EAAE,IAAmB;QACpE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxG,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC;YACjD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;YACpE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM;YAC9B,MAAM,IAAI,GAAG,KAAK;iBAChB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;iBACxK,IAAI,CAAC,IAAI,CAAC,CAAC;YACb,MAAM,MAAM,GACX,sDAAsD,cAAc,mCAAmC,SAAS,oBAAoB,IAAI,MAAM;gBAC9I,iGAAiG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,cAAc,KAAK,CAAC;YAC5I,IAAI,KAAK,GAAkB,IAAI,CAAC;YAChC,IAAI,CAAC;gBACJ,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACR,KAAK,GAAG,IAAI,CAAC;YACd,CAAC;YACD,IAAI,CAAC,KAAK;gBAAE,MAAM;YAClB,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAC5C,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;gBAC3D,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;oBACtB,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACpC,IAAI,OAAO,KAAK,KAAK,QAAQ;wBAAE,OAAO;oBACtC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;oBACxC,IAAI,IAAI,KAAK,cAAc;wBAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;yBAC1D,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;wBAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAW,CAAC,CAAC;gBACxE,CAAC,CAAC,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACR,sDAAsD;YACvD,CAAC;QACF,CAAC;QACD,OAAO,GAAG,CAAC;IACZ,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IACjC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,KAAK,EAAE,MAAc,EAAE,EAAE;QAC/B,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;QACxD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC,CAAC;YAC1I,OAAO,MAAM,CAAC,IAAI,CAAC;QACpB,CAAC;gBAAS,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACF,CAAC,CAAC;AACH,CAAC"}

package/dist/backend/backend/src/services/usage-ledger/usage-categories.store.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The owner's own categories for usage reports ("self-media", "book", …).
+ *
+ * Categories are optional and never written into ticket facts: they only
+ * decide how a report groups tickets. Each definition has a natural-language
+ * description and optional hints (keywords, team names, project names). The
+ * set carries a version that changes whenever a definition changes; the
+ * classification cache is keyed on it.
+ *
+ * @module services/usage-ledger/usage-categories.store
+ */
+/** File holding the definitions. */
+export declare const CATEGORIES_FILE = "categories.json";
+/** One user-defined category. */
+export interface CategoryDef {
+    /** Short label shown in reports */
+    name: string;
+    /** What belongs here, in plain words (also read by the language model) */
+    description?: string;
+    /** Words or phrases that put a ticket here (case-insensitive) */
+    keywords?: string[];
+    /** Team names that belong here */
+    teams?: string[];
+    /** Project names that belong here */
+    projects?: string[];
+}
+/**
+ * Validate and normalise a definition.
+ *
+ * @param input - Candidate
+ * @returns The definition, or an error text
+ */
+export declare function normalizeCategory(input: unknown): CategoryDef | string;
+/**
+ * Identity of a set of definitions: the same definitions always give the same
+ * id, so a classification cache survives a set being re-entered unchanged.
+ *
+ * @param defs - Definitions
+ * @returns `default` for none, else a short hash
+ */
+export declare function categorySetId(defs: CategoryDef[]): string;
+/**
+ * File-backed category definitions.
+ */
+export declare class UsageCategoriesStore {
+    readonly dir: string;
+    private readonly file;
+    /**
+     * @param dir - Ledger directory (default `~/.crewly/usage-ledger`)
+     */
+    constructor(dir?: string);
+    private read;
+    private write;
+    /**
+     * The current definitions.
+     *
+     * @returns Version, set id and definitions
+     */
+    list(): Promise<{
+        version: number;
+        setId: string;
+        updatedAt: string;
+        categories: CategoryDef[];
+    }>;
+    /**
+     * Add or replace one category (matched by name, case-insensitive).
+     *
+     * @param input - The definition
+     * @returns The new state, or an error text
+     */
+    set(input: unknown): Promise<{
+        version: number;
+        categories: CategoryDef[];
+    } | string>;
+    /**
+     * Replace every definition.
+     *
+     * @param inputs - The new set (empty clears it)
+     * @returns The new state, or an error text
+     */
+    replaceAll(inputs: unknown[]): Promise<{
+        version: number;
+        categories: CategoryDef[];
+    } | string>;
+    /**
+     * Remove one category.
+     *
+     * @param name - Its name (case-insensitive)
+     * @returns The new state, or null when there was no such category
+     */
+    remove(name: string): Promise<{
+        version: number;
+        categories: CategoryDef[];
+    } | null>;
+}
+//# sourceMappingURL=usage-categories.store.d.ts.map

package/dist/backend/backend/src/services/usage-ledger/usage-categories.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-categories.store.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-categories.store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,oCAAoC;AACpC,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC3B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AA0BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,MAAM,CAiBtE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,MAAM,CAIzD;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAMpB,QAAQ,CAAC,GAAG,EAAE,MAAM;IALhC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B;;OAEG;gBACkB,GAAG,GAAE,MAAwD;YAIpE,IAAI;YAYJ,KAAK;IAOnB;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC;IAKvG;;;;;OAKG;IACG,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,WAAW,EAAE,CAAA;KAAE,GAAG,MAAM,CAAC;IAU3F;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,WAAW,EAAE,CAAA;KAAE,GAAG,MAAM,CAAC;IAYrG;;;;;OAKG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,WAAW,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;CAO1F"}

package/dist/backend/backend/src/services/usage-ledger/usage-categories.store.js

@@ -0,0 +1,166 @@
+/**
+ * The owner's own categories for usage reports ("self-media", "book", …).
+ *
+ * Categories are optional and never written into ticket facts: they only
+ * decide how a report groups tickets. Each definition has a natural-language
+ * description and optional hints (keywords, team names, project names). The
+ * set carries a version that changes whenever a definition changes; the
+ * classification cache is keyed on it.
+ *
+ * @module services/usage-ledger/usage-categories.store
+ */
+import { createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { atomicWriteJson } from '../../utils/file-io.utils.js';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+import { LEDGER_DIR_NAME } from './usage-ledger.store.js';
+/** File holding the definitions. */
+export const CATEGORIES_FILE = 'categories.json';
+/** Longest name / description / hint accepted. */
+const MAX_TEXT = 400;
+const MAX_HINTS = 60;
+const MAX_CATEGORIES = 40;
+/**
+ * Clean a list of hints.
+ *
+ * @param value - Candidate list
+ * @returns Trimmed, de-duplicated strings (empty list becomes undefined)
+ */
+function cleanList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [...new Set(value.filter((v) => typeof v === 'string').map((v) => v.trim().slice(0, 120)).filter(Boolean))];
+    return out.length > 0 ? out.slice(0, MAX_HINTS) : undefined;
+}
+/**
+ * Validate and normalise a definition.
+ *
+ * @param input - Candidate
+ * @returns The definition, or an error text
+ */
+export function normalizeCategory(input) {
+    if (!input || typeof input !== 'object')
+        return 'category must be an object';
+    const raw = input;
+    const name = typeof raw.name === 'string' ? raw.name.trim().slice(0, 60) : '';
+    if (!name)
+        return 'category needs a name';
+    if (name.toLowerCase() === 'other')
+        return '"other" is reserved for tickets that match nothing';
+    const description = typeof raw.description === 'string' && raw.description.trim() ? raw.description.trim().slice(0, MAX_TEXT) : undefined;
+    const keywords = cleanList(raw.keywords);
+    const teams = cleanList(raw.teams);
+    const projects = cleanList(raw.projects);
+    return {
+        name,
+        ...(description ? { description } : {}),
+        ...(keywords ? { keywords } : {}),
+        ...(teams ? { teams } : {}),
+        ...(projects ? { projects } : {}),
+    };
+}
+/**
+ * Identity of a set of definitions: the same definitions always give the same
+ * id, so a classification cache survives a set being re-entered unchanged.
+ *
+ * @param defs - Definitions
+ * @returns `default` for none, else a short hash
+ */
+export function categorySetId(defs) {
+    if (defs.length === 0)
+        return 'default';
+    const canonical = defs.map((d) => [d.name.toLowerCase(), d.description ?? '', d.keywords ?? [], d.teams ?? [], d.projects ?? []]);
+    return createHash('sha1').update(JSON.stringify(canonical)).digest('hex').slice(0, 10);
+}
+/**
+ * File-backed category definitions.
+ */
+export class UsageCategoriesStore {
+    dir;
+    file;
+    /**
+     * @param dir - Ledger directory (default `~/.crewly/usage-ledger`)
+     */
+    constructor(dir = path.join(getCrewlyHomePath(), LEDGER_DIR_NAME)) {
+        this.dir = dir;
+        this.file = path.join(dir, CATEGORIES_FILE);
+    }
+    async read() {
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.file, 'utf-8'));
+            const categories = (Array.isArray(parsed.categories) ? parsed.categories : [])
+                .map(normalizeCategory)
+                .filter((c) => typeof c !== 'string');
+            return { version: Number(parsed.version) || 0, updatedAt: parsed.updatedAt ?? '', categories };
+        }
+        catch {
+            return { version: 0, updatedAt: '', categories: [] };
+        }
+    }
+    async write(categories, previousVersion) {
+        const next = { version: previousVersion + 1, updatedAt: new Date().toISOString(), categories };
+        await fs.mkdir(this.dir, { recursive: true });
+        await atomicWriteJson(this.file, next);
+        return next;
+    }
+    /**
+     * The current definitions.
+     *
+     * @returns Version, set id and definitions
+     */
+    async list() {
+        const file = await this.read();
+        return { version: file.version, setId: categorySetId(file.categories), updatedAt: file.updatedAt, categories: file.categories };
+    }
+    /**
+     * Add or replace one category (matched by name, case-insensitive).
+     *
+     * @param input - The definition
+     * @returns The new state, or an error text
+     */
+    async set(input) {
+        const def = normalizeCategory(input);
+        if (typeof def === 'string')
+            return def;
+        const file = await this.read();
+        const rest = file.categories.filter((c) => c.name.toLowerCase() !== def.name.toLowerCase());
+        if (rest.length >= MAX_CATEGORIES)
+            return `at most ${MAX_CATEGORIES} categories`;
+        const written = await this.write([...rest, def], file.version);
+        return { version: written.version, categories: written.categories };
+    }
+    /**
+     * Replace every definition.
+     *
+     * @param inputs - The new set (empty clears it)
+     * @returns The new state, or an error text
+     */
+    async replaceAll(inputs) {
+        const defs = [];
+        for (const input of inputs.slice(0, MAX_CATEGORIES)) {
+            const def = normalizeCategory(input);
+            if (typeof def === 'string')
+                return def;
+            defs.push(def);
+        }
+        const file = await this.read();
+        const written = await this.write(defs, file.version);
+        return { version: written.version, categories: written.categories };
+    }
+    /**
+     * Remove one category.
+     *
+     * @param name - Its name (case-insensitive)
+     * @returns The new state, or null when there was no such category
+     */
+    async remove(name) {
+        const file = await this.read();
+        const rest = file.categories.filter((c) => c.name.toLowerCase() !== name.trim().toLowerCase());
+        if (rest.length === file.categories.length)
+            return null;
+        const written = await this.write(rest, file.version);
+        return { version: written.version, categories: written.categories };
+    }
+}
+//# sourceMappingURL=usage-categories.store.js.map

package/dist/backend/backend/src/services/usage-ledger/usage-categories.store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-categories.store.js","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-categories.store.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.backfill.d.ts

@@ -0,0 +1,90 @@
+/**
+ * One-time rebuild of the ledger for the time before it existed.
+ *
+ * Sources: the token ledger (usage events) and the run traces (ticket roots,
+ * deliveries, busy turns, status changes). The traces expire after 90 days,
+ * the ledger does not, so this keeps what they know.
+ *
+ * Attribution of a usage event:
+ * - it already carries a trace id (the harness stamped it): `recorded`;
+ * - otherwise it goes to the trace the session's latest delivery named,
+ *   when that delivery was at most {@link INFER_MAX_GAP_MS} before the event:
+ *   `inferred`;
+ * - otherwise it lands in the agent's "(no ticket)" unit.
+ *
+ * Only facts older than the cutoff (the moment live recording began) are
+ * written, so history and live facts never overlap. The result goes to
+ * `backfill.jsonl`; the run is recorded in `state.json` and never repeats.
+ *
+ * @module services/usage-ledger/usage-ledger.backfill
+ */
+import { type TokenUsageEvent } from '../monitoring/token-usage.service.js';
+import type { TeamLookup } from './team-directory.js';
+import type { UsageLedgerStore } from './usage-ledger.store.js';
+/** An unticketed event this soon after a delivery is credited to the delivery's trace. */
+export declare const INFER_MAX_GAP_MS: number;
+/** File with the ledger's own bookkeeping. */
+export declare const STATE_FILE = "state.json";
+/** Bookkeeping persisted beside the facts. */
+export interface LedgerState {
+    /** When live recording began (the backfill cutoff) */
+    liveSince?: string;
+    backfill?: {
+        doneAt: string;
+        cutoff: string;
+        facts: number;
+        usageEvents: number;
+        inferredEvents: number;
+    };
+}
+/** Where history comes from. */
+export interface BackfillSources {
+    /** Usage events of every session */
+    forEachUsage: (visit: (session: string, event: TokenUsageEvent) => void) => void;
+    /** The traces directory (index.json + `<id>.jsonl`) */
+    traceDir: string;
+    directory: TeamLookup;
+}
+/** What a backfill did. */
+export interface BackfillResult {
+    ran: boolean;
+    reason?: string;
+    facts: number;
+    usageEvents: number;
+    inferredEvents: number;
+    traces: number;
+}
+/**
+ * Read the ledger bookkeeping.
+ *
+ * @param dir - Ledger directory
+ * @returns State (empty when none)
+ */
+export declare function readLedgerState(dir: string): Promise<LedgerState>;
+/**
+ * Write the ledger bookkeeping.
+ *
+ * @param dir - Ledger directory
+ * @param state - State
+ */
+export declare function writeLedgerState(dir: string, state: LedgerState): Promise<void>;
+/**
+ * Note when live recording began (once).
+ *
+ * @param dir - Ledger directory
+ * @param now - Now (ms)
+ * @returns The cutoff
+ */
+export declare function ensureLiveSince(dir: string, now?: number): Promise<string>;
+/**
+ * Rebuild history into `backfill.jsonl`.
+ *
+ * @param store - Ledger store
+ * @param sources - Where history comes from
+ * @param opts.cutoffMs - Only facts before this time are written
+ * @returns What happened
+ */
+export declare function runBackfill(store: UsageLedgerStore, sources: BackfillSources, opts: {
+    cutoffMs: number;
+}): Promise<BackfillResult>;
+//# sourceMappingURL=usage-ledger.backfill.d.ts.map

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.backfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.backfill.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAGvG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAE9D,8CAA8C;AAC9C,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC3B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1G;AAED,gCAAgC;AAChC,MAAM,WAAW,eAAe;IAC/B,oCAAoC;IACpC,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,IAAI,KAAK,IAAI,CAAC;IACjF,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,UAAU,CAAC;CACtB;AAED,2BAA2B;AAC3B,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAMvE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrF;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5F;AAUD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAsMxI"}