crewly 1.20.302 → 1.20.303

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

@@ -0,0 +1,52 @@
+/**
+ * Append-only storage of ledger facts: one JSON object per line, one file per
+ * UTC month (`2026-10.jsonl`), plus `backfill.jsonl` for facts rebuilt from
+ * history. There is no update and no delete: a fact is written once.
+ *
+ * @module services/usage-ledger/usage-ledger.store
+ */
+import type { LedgerFact, LedgerFile } from './usage-ledger.types.js';
+/** Directory under CREWLY_HOME that holds the ledger. */
+export declare const LEDGER_DIR_NAME = "usage-ledger";
+/** File of facts rebuilt from history. */
+export declare const BACKFILL_FILE = "backfill.jsonl";
+/** Month file name of an ISO time (UTC). */
+export declare function monthFileFor(ts: string): string;
+/**
+ * The ledger's files. Writes are queued and applied in order.
+ */
+export declare class UsageLedgerStore {
+    readonly dir: string;
+    private chain;
+    private dirReady;
+    /**
+     * @param dir - Ledger directory (default `~/.crewly/usage-ledger`)
+     */
+    constructor(dir?: string);
+    /**
+     * Queue a fact. Never throws; a failed write is dropped (accounting must not
+     * break the harness).
+     *
+     * @param fact - The fact
+     * @param file - `live` (month file of the fact) or `backfill`
+     */
+    append(fact: LedgerFact, file?: LedgerFile): void;
+    /**
+     * Queue several facts as one write.
+     *
+     * @param facts - The facts
+     * @param file - Target
+     */
+    appendMany(facts: LedgerFact[], file?: LedgerFile): void;
+    /**
+     * Wait for every queued write.
+     */
+    flush(): Promise<void>;
+    /**
+     * The ledger's fact files.
+     *
+     * @returns File names (month files oldest first, then the backfill file)
+     */
+    listFiles(): Promise<string[]>;
+}
+//# sourceMappingURL=usage-ledger.store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.store.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEtE,yDAAyD;AACzD,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAC9C,0CAA0C;AAC1C,eAAO,MAAM,aAAa,mBAAmB,CAAC;AAE9C,4CAA4C;AAC5C,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAOhB,QAAQ,CAAC,GAAG,EAAE,MAAM;IANhC,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;OAEG;gBACkB,GAAG,GAAE,MAAwD;IAElF;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE,UAAmB,GAAG,IAAI;IAIzD;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,IAAI,GAAE,UAAmB,GAAG,IAAI;IAwBhE;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CASpC"}

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

@@ -0,0 +1,95 @@
+/**
+ * Append-only storage of ledger facts: one JSON object per line, one file per
+ * UTC month (`2026-10.jsonl`), plus `backfill.jsonl` for facts rebuilt from
+ * history. There is no update and no delete: a fact is written once.
+ *
+ * @module services/usage-ledger/usage-ledger.store
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+/** Directory under CREWLY_HOME that holds the ledger. */
+export const LEDGER_DIR_NAME = 'usage-ledger';
+/** File of facts rebuilt from history. */
+export const BACKFILL_FILE = 'backfill.jsonl';
+/** Month file name of an ISO time (UTC). */
+export function monthFileFor(ts) {
+    return `${/^\d{4}-\d{2}/.test(ts) ? ts.slice(0, 7) : new Date().toISOString().slice(0, 7)}.jsonl`;
+}
+/**
+ * The ledger's files. Writes are queued and applied in order.
+ */
+export class UsageLedgerStore {
+    dir;
+    chain = Promise.resolve();
+    dirReady = false;
+    /**
+     * @param dir - Ledger directory (default `~/.crewly/usage-ledger`)
+     */
+    constructor(dir = path.join(getCrewlyHomePath(), LEDGER_DIR_NAME)) {
+        this.dir = dir;
+    }
+    /**
+     * Queue a fact. Never throws; a failed write is dropped (accounting must not
+     * break the harness).
+     *
+     * @param fact - The fact
+     * @param file - `live` (month file of the fact) or `backfill`
+     */
+    append(fact, file = 'live') {
+        this.appendMany([fact], file);
+    }
+    /**
+     * Queue several facts as one write.
+     *
+     * @param facts - The facts
+     * @param file - Target
+     */
+    appendMany(facts, file = 'live') {
+        if (facts.length === 0)
+            return;
+        const byFile = new Map();
+        for (const fact of facts) {
+            const name = file === 'backfill' ? BACKFILL_FILE : monthFileFor(fact.ts);
+            const lines = byFile.get(name) ?? [];
+            lines.push(JSON.stringify(fact));
+            byFile.set(name, lines);
+        }
+        this.chain = this.chain.then(async () => {
+            try {
+                if (!this.dirReady) {
+                    await fs.mkdir(this.dir, { recursive: true });
+                    this.dirReady = true;
+                }
+                for (const [name, lines] of byFile) {
+                    await fs.appendFile(path.join(this.dir, name), `${lines.join('\n')}\n`, 'utf-8');
+                }
+            }
+            catch {
+                // dropped
+            }
+        });
+    }
+    /**
+     * Wait for every queued write.
+     */
+    async flush() {
+        await this.chain;
+    }
+    /**
+     * The ledger's fact files.
+     *
+     * @returns File names (month files oldest first, then the backfill file)
+     */
+    async listFiles() {
+        try {
+            const names = await fs.readdir(this.dir);
+            const months = names.filter((n) => /^\d{4}-\d{2}\.jsonl$/.test(n)).sort();
+            return names.includes(BACKFILL_FILE) ? [...months, BACKFILL_FILE] : months;
+        }
+        catch {
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=usage-ledger.store.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.store.js","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGjE,yDAAyD;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC;AAC9C,0CAA0C;AAC1C,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAE9C,4CAA4C;AAC5C,MAAM,UAAU,YAAY,CAAC,EAAU;IACtC,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;AACnG,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAOP;IANb,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IACzC,QAAQ,GAAG,KAAK,CAAC;IAEzB;;OAEG;IACH,YAAqB,MAAc,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,eAAe,CAAC;QAA7D,QAAG,GAAH,GAAG,CAA0D;IAAG,CAAC;IAEtF;;;;;;OAMG;IACH,MAAM,CAAC,IAAgB,EAAE,OAAmB,MAAM;QACjD,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,KAAmB,EAAE,OAAmB,MAAM;QACxD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC3C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YACjC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YACvC,IAAI,CAAC;gBACJ,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACpB,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC9C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;gBACtB,CAAC;gBACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;oBACpC,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAClF,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,UAAU;YACX,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACV,MAAM,IAAI,CAAC,KAAK,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS;QACd,IAAI,CAAC;YACJ,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC1E,OAAO,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,EAAE,CAAC;QACX,CAAC;IACF,CAAC;CACD"}

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

@@ -0,0 +1,127 @@
+/**
+ * Usage ledger types: the immutable facts behind per-ticket time and token
+ * accounting (specs/2026-10-11-usage-ledger.md).
+ *
+ * A "unit" is one trace (a ticket, a request, a work item thread, an owner
+ * conversation). Facts only ever get appended; every statistic (category,
+ * team, owner minutes) is computed from them at report time.
+ *
+ * @module services/usage-ledger/usage-ledger.types
+ */
+/** Schema version written on every fact. */
+export declare const LEDGER_VERSION = 1;
+/**
+ * How a fact was tied to its unit.
+ * - `recorded`: the harness knew the unit when it happened.
+ * - `inferred`: rebuilt afterwards from timestamps (history backfill).
+ */
+export type Attribution = 'recorded' | 'inferred';
+/** Id of the pseudo-unit that holds an agent's usage while it worked on no ticket. */
+export declare const UNTICKETED_PREFIX = "~none:";
+/** Fields every fact carries. */
+interface FactBase {
+    v: typeof LEDGER_VERSION;
+    /** ISO time of the thing that happened (the covered hour's start, for usage / busy) */
+    ts: string;
+}
+/** What is known about a unit. Several of these merge field by field, first value wins. */
+export interface UnitMetaFact extends FactBase {
+    kind: 'unit.meta';
+    unitId: string;
+    /** `TKT-12` or a project ticket id (`CE-7`) */
+    ticketId?: string;
+    requestId?: string;
+    /** What started the trace (`request`, `owner_message`, `ticket`, …) */
+    rootKind?: string;
+    title?: string;
+    /** The owner's words / the ticket description, cut */
+    excerpt?: string;
+    team?: string;
+    project?: string;
+    /** Where the request came from (`slack-dm`, `chat`, …) */
+    channel?: string;
+    /** Conversation thread the request lives in (Slack thread ref) */
+    threadRef?: string;
+    /** When the unit began */
+    openedAt?: string;
+    attribution: Attribution;
+}
+/** An agent worked on a unit (written once per agent and unit). */
+export interface UnitAgentFact extends FactBase {
+    kind: 'unit.agent';
+    unitId: string;
+    agent: string;
+    team?: string;
+    project?: string;
+    attribution: Attribution;
+}
+/** The unit reached a terminal status. */
+export interface UnitClosedFact extends FactBase {
+    kind: 'unit.closed';
+    unitId: string;
+    status: string;
+    attribution: Attribution;
+}
+/**
+ * Token usage of one agent on one unit within one hour (a delta: the sum of
+ * the facts is the total). `share` is the fraction of the underlying events
+ * this unit carries (1, or 1/n when the turn was about n tickets); token
+ * fields are the raw event sums, before the share.
+ */
+export interface UsageFact extends FactBase {
+    kind: 'usage';
+    unitId: string;
+    agent: string;
+    team?: string;
+    model: string;
+    runtime?: string;
+    events: number;
+    share: number;
+    /** Every input token, cached ones included (see eventTokens) */
+    input: number;
+    cachedInput: number;
+    output: number;
+    cacheWrite: number;
+    /** Cost-weighted tokens (see eventTokens) */
+    budget: number;
+    /** Estimated USD at the model's rate (cache-aware) */
+    costUsd: number;
+    attribution: Attribution;
+}
+/** Agent busy time on one unit within one hour (a delta, like {@link UsageFact}). */
+export interface BusyFact extends FactBase {
+    kind: 'busy';
+    unitId: string;
+    agent: string;
+    team?: string;
+    turns: number;
+    busyMs: number;
+    share: number;
+    attribution: Attribution;
+}
+/** The owner wrote to a unit (a message delivered to an agent on it). */
+export interface OwnerMessageFact extends FactBase {
+    kind: 'owner.message';
+    unitId: string;
+    attribution: Attribution;
+}
+/** Any ledger fact. */
+export type LedgerFact = UnitMetaFact | UnitAgentFact | UnitClosedFact | UsageFact | BusyFact | OwnerMessageFact;
+/** Where a fact is written. */
+export type LedgerFile = 'live' | 'backfill';
+/** One tokens + cost tally. */
+export interface Tally {
+    input: number;
+    cachedInput: number;
+    output: number;
+    cacheWrite: number;
+    /** Raw total: input (cached included) + output */
+    total: number;
+    /** Cost-weighted total */
+    budget: number;
+    costUsd: number;
+}
+/** A zeroed {@link Tally}. */
+export declare function emptyTally(): Tally;
+export {};
+//# sourceMappingURL=usage-ledger.types.d.ts.map

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

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

package/dist/backend/backend/src/services/usage-ledger/usage-ledger.types.js

@@ -0,0 +1,19 @@
+/**
+ * Usage ledger types: the immutable facts behind per-ticket time and token
+ * accounting (specs/2026-10-11-usage-ledger.md).
+ *
+ * A "unit" is one trace (a ticket, a request, a work item thread, an owner
+ * conversation). Facts only ever get appended; every statistic (category,
+ * team, owner minutes) is computed from them at report time.
+ *
+ * @module services/usage-ledger/usage-ledger.types
+ */
+/** Schema version written on every fact. */
+export const LEDGER_VERSION = 1;
+/** Id of the pseudo-unit that holds an agent's usage while it worked on no ticket. */
+export const UNTICKETED_PREFIX = '~none:';
+/** A zeroed {@link Tally}. */
+export function emptyTally() {
+    return { input: 0, cachedInput: 0, output: 0, cacheWrite: 0, total: 0, budget: 0, costUsd: 0 };
+}
+//# sourceMappingURL=usage-ledger.types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage-ledger.types.js","sourceRoot":"","sources":["../../../../../../backend/src/services/usage-ledger/usage-ledger.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAShC,sFAAsF;AACtF,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAmH1C,8BAA8B;AAC9B,MAAM,UAAU,UAAU;IACzB,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AAChG,CAAC"}

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

@@ -0,0 +1,124 @@
+/**
+ * Usage report: where the owner's time and the agents' tokens went, per
+ * category / team / project / agent / ticket.
+ *
+ * Everything is computed from the ledger facts at call time. Categories are
+ * applied here (see {@link UnitClassifier}) and never stored in the facts.
+ * Owner minutes follow the span heuristic of owner-spans.ts. Figures are
+ * summed per UTC hour, so a window edge is accurate to the hour.
+ *
+ * @module services/usage-ledger/usage-report.service
+ */
+import type { LedgerRollup } from './ledger-rollup.js';
+import type { TeamLookup } from './team-directory.js';
+import { type CategoryDef } from './usage-categories.store.js';
+import { UnitClassifier } from './unit-classifier.js';
+import { type Tally } from './usage-ledger.types.js';
+/** Ways to group a report. */
+export declare const REPORT_DIMENSIONS: readonly ["category", "team", "project", "agent", "ticket"];
+/** A grouping. */
+export type ReportDimension = (typeof REPORT_DIMENSIONS)[number];
+/** Request for a report. */
+export interface ReportQuery {
+    /** Window start (ms) */
+    sinceMs: number;
+    /** Window end (ms) */
+    untilMs: number;
+    by: ReportDimension;
+    /** Categories to use instead of the stored ones (ad hoc) */
+    categories?: CategoryDef[];
+    /** Keep only these groups (by name), e.g. two categories to compare */
+    only?: string[];
+    /** Groups returned (default 50) */
+    limit?: number;
+}
+/** One ticket in a group. */
+export interface TicketLine {
+    unitId: string;
+    ticketId?: string;
+    title: string;
+    team?: string;
+    ownerMinutes: number;
+    agentBusyMinutes: number;
+    tokens: number;
+    costUsd: number;
+    inferred: boolean;
+}
+/** One group of a report. */
+export interface ReportGroup {
+    key: string;
+    ownerMinutes: number;
+    agentBusyMinutes: number;
+    /** Token figures: `budget` is the cost-weighted headline, `total` the raw sum */
+    tokens: Tally;
+    costUsd: number;
+    ticketCount: number;
+    topTickets: TicketLine[];
+}
+/** A report. */
+export interface UsageReport {
+    window: {
+        since: string;
+        until: string;
+    };
+    by: ReportDimension;
+    categories: {
+        setId: string;
+        source: 'stored' | 'ad-hoc' | 'default';
+        names: string[];
+        llmClassified: number;
+        unclassified: number;
+    } | null;
+    totals: Omit<ReportGroup, 'key' | 'topTickets'>;
+    groups: ReportGroup[];
+    /** Voice / Slack friendly text */
+    summary: string;
+    notes: string[];
+}
+/** Where the report gets its inputs. */
+export interface ReportDeps {
+    rollup: LedgerRollup;
+    directory: TeamLookup;
+    classifier: UnitClassifier;
+    /** Stored category definitions */
+    categories: () => Promise<CategoryDef[]>;
+    /** Called before reading so buffered facts are on disk and in the rollup */
+    sync: () => Promise<void>;
+    now?: () => number;
+}
+/**
+ * Parse a window start.
+ *
+ * @param value - `7d`, `24h`, `2w`, `90m`, or an ISO date / time
+ * @param nowMs - Now (ms)
+ * @returns Epoch ms, or null when unreadable
+ */
+export declare function parseSince(value: string, nowMs: number): number | null;
+/**
+ * Format minutes for speech: `45m`, `2h10m`, `1d3h`.
+ *
+ * @param minutes - Minutes
+ * @returns Short text
+ */
+export declare function formatMinutes(minutes: number): string;
+/**
+ * Builds reports from the ledger.
+ */
+export declare class UsageReportService {
+    private readonly deps;
+    constructor(deps: ReportDeps);
+    /**
+     * Compute a report.
+     *
+     * @param query - Window, grouping, optional ad-hoc categories
+     * @returns The report
+     */
+    report(query: ReportQuery): Promise<UsageReport>;
+    private teamOf;
+    /** The team a ticket is credited to: the recorded one, else the team with the most spend. */
+    private primaryTeam;
+    private projectOf;
+    private labelOf;
+    private summarize;
+}
+//# sourceMappingURL=usage-report.service.d.ts.map

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

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