@ascenda-one/history-import 0.1.12

package/dist/ship.js

@@ -0,0 +1,208 @@
+/**
+ * Ships normalized historical events over the existing batch wire
+ * (`POST /v1/tool-events/batch`), authenticated with the same event write
+ * token the live hooks use — the import is just another paired tool speaking
+ * the same protocol, backdated.
+ *
+ * Three deliberate choices:
+ *
+ * - **Own fetch, not tool-kit's `postToolEventsBatch`.** The hook path
+ *   collapses the response to accepted/failed because a hook can't do
+ *   anything with detail. An importer can: the batch response carries
+ *   per-item accepted/rejected with reasons, and surfacing "9,741 accepted,
+ *   3 rejected (validation_failed)" is the difference between a verifiable
+ *   import and a shrug.
+ * - **Stable `importKey` per event.** sha256 over
+ *   (store|sessionRef|eventKind|occurredAt|ordinal) — identical on every
+ *   re-run of the same store. Since 19 Aug 2026 this is what the backend
+ *   dedups on: `(pairedUser, toolInstallation, importKey)` is unique, a
+ *   replayed event is reported as `duplicate` and writes nothing, and the
+ *   key is *required* on anything carrying a historical provenance. Note it
+ *   dedups on this key alone, NOT on `(extractionId, importKey)` — an
+ *   extraction id is fresh per run, so including it would dedup nothing.
+ *
+ *   `ordinal` used to be the event's index in the whole shipped array, which
+ *   made the key stable only while the store was. A later run extracting a
+ *   different *set* — Claude Code's 30-day purge having eaten the oldest
+ *   days — shifted every subsequent ordinal, so unchanged records re-keyed
+ *   and dedup silently stopped working on exactly the re-run it exists for.
+ *   That is no longer a position: `importOrdinals` numbers an event only
+ *   among events sharing its whole identity (store, session, kind, instant),
+ *   so it disambiguates genuine duplicates and nothing else. Deleting a day,
+ *   a session, or an entire store leaves every surviving key untouched.
+ * - **Raw local refs are hashed at the wire, not before.** The normalized
+ *   file in staging keeps the real cwd (local, never leaves the machine);
+ *   `workspaceHash`/`projectHash` go out as the same machine-salted 16-hex
+ *   hashes the live hooks send, so historical and live events for the same
+ *   repo correlate server-side without the server ever learning the path.
+ */
+import { createHash } from "node:crypto";
+import { hashWithMachineSalt, readTokenFile, defaultTokenFilePath, utcOffsetMinutesAt } from "@ascenda-one/tool-kit";
+import { EXTRACTION_EPOCH_KIND, HISTORICAL_CONSENT_SCOPE, STORE_SOURCE } from "./types.js";
+export const DEFAULT_API_BASE_URL = "https://api.ascenda.one";
+/** Mirrors tool-kit's loadCliAgentConfig, minus the hook-only pieces. */
+export function loadShipConfig() {
+    const apiBaseUrl = (process.env.ASCENDA_API_BASE_URL ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+    const idRaw = process.env.ASCENDA_TOOL_INSTALLATION_ID;
+    if (!idRaw) {
+        throw new Error("Missing ASCENDA_TOOL_INSTALLATION_ID — the importer ships as the machine's paired tool; pair it first");
+    }
+    const toolInstallationId = idRaw.trim().includes(":") ? idRaw.trim() : `claude_code:${idRaw.trim()}`;
+    const tokenFilePath = process.env.ASCENDA_EVENT_WRITE_TOKEN_FILE ?? defaultTokenFilePath(toolInstallationId);
+    const eventWriteToken = readTokenFile(tokenFilePath) ?? process.env.ASCENDA_EVENT_WRITE_TOKEN;
+    if (!eventWriteToken) {
+        throw new Error(`No event write token at ${tokenFilePath} (or ASCENDA_EVENT_WRITE_TOKEN)`);
+    }
+    return { apiBaseUrl, toolInstallationId, eventWriteToken };
+}
+/**
+ * Per-event ordinals for a batch, positionally aligned with `events`.
+ *
+ * The ordinal exists only to separate events that are otherwise identical on
+ * the wire — same store, same session, same kind, same instant. Claude Code
+ * really does emit these: one prompt can produce several events sharing a
+ * millisecond, and without a tiebreak they would collapse to one key and the
+ * backend would dedup away real records.
+ *
+ * Counting within that identity rather than across the array is what makes
+ * the key survive a changing store. Two runs over stores that differ by
+ * whole days still agree on every record they share, because nothing outside
+ * an event's own identity group can move its number. Within a group the
+ * assignment order is irrelevant: the members are indistinguishable by
+ * definition, so any consistent numbering pairs them up.
+ */
+export function importOrdinals(events) {
+    const seen = new Map();
+    return events.map((event) => {
+        const identity = [event.store, event.sessionRef ?? "", event.eventKind, event.occurredAt].join("|");
+        const ordinal = seen.get(identity) ?? 0;
+        seen.set(identity, ordinal + 1);
+        return ordinal;
+    });
+}
+export function importKeyOf(event, ordinal) {
+    return createHash("sha256")
+        .update([event.store, event.sessionRef ?? "", event.eventKind, event.occurredAt, String(ordinal)].join("|"))
+        .digest("hex")
+        .slice(0, 16);
+}
+export function toWirePayload(event, ordinal, toolInstallationId) {
+    const metadata = {
+        importKey: importKeyOf(event, ordinal),
+        extractionId: event.extractionId,
+        importSchema: 1
+    };
+    if (event.sourceVersion)
+        metadata.sourceVersion = event.sourceVersion;
+    for (const [key, value] of Object.entries(event.metrics)) {
+        metadata[key] = value;
+    }
+    // gitBranch is a metric locally but a name on the wire — hash it like the
+    // repo path. Branch names leak project vocabulary ("feature/acme-migration").
+    if (typeof metadata.gitBranch === "string") {
+        metadata.gitBranchHash = hashWithMachineSalt(metadata.gitBranch) ?? "";
+        delete metadata.gitBranch;
+    }
+    const workspaceHash = event.repoRef ? hashWithMachineSalt(event.repoRef) : null;
+    return {
+        toolInstallationId,
+        source: STORE_SOURCE[event.store],
+        // Always a canonical catalog type. `eventKind` is typed against the
+        // contract union and the epoch marker is filtered out upstream in
+        // `shippableEvents`, so no cast is needed here — and an off-catalog name
+        // cannot reach the wire to be silently bucketed as `unclassified`.
+        eventType: event.eventKind,
+        occurredAt: event.occurredAt,
+        // The offset in force WHEN THE EVENT HAPPENED, not when the import ran.
+        // A nine-month backfill crosses DST boundaries; stamping today's
+        // offset on all of it would shift a whole season by an hour.
+        utcOffsetMinutes: utcOffsetMinutesAt(new Date(event.occurredAt)),
+        severity: "low",
+        sessionId: event.sessionRef,
+        workspaceHash,
+        projectHash: workspaceHash,
+        // A real contract ToolConsentScope now, and a real gate: the backend
+        // requires an active historical-import consent lease for anything carrying
+        // one of the provenance classes below, and decides that on the provenance
+        // rather than on this string — sending `ide_telemetry` here would not buy
+        // the event a way in.
+        consentScope: HISTORICAL_CONSENT_SCOPE,
+        provenance: event.provenance,
+        privacyMode: "metadata_only",
+        metadata
+    };
+}
+const BATCH_SIZE = 200;
+/**
+ * The events that belong on the wire: everything except the extraction epoch
+ * marker, which is local bookkeeping about the read itself rather than an
+ * observation of anyone's work (see `EXTRACTION_EPOCH_KIND`). Exported so the
+ * CLI can report the same count it is about to send.
+ */
+export function shippableEvents(events) {
+    return events.filter((e) => e.eventKind !== EXTRACTION_EPOCH_KIND);
+}
+export async function shipEvents(events, config, onProgress) {
+    const result = {
+        sent: 0,
+        accepted: 0,
+        duplicate: 0,
+        rejected: 0,
+        rejectionReasons: {},
+        httpFailures: 0
+    };
+    const wireEvents = shippableEvents(events);
+    // Ordinals are assigned across the whole shipment before it is cut into
+    // batches: an identity group split by a chunk boundary must still number
+    // continuously, or the same record would key differently depending on
+    // where the batching happened to fall.
+    const ordinals = importOrdinals(wireEvents);
+    for (let offset = 0; offset < wireEvents.length; offset += BATCH_SIZE) {
+        const chunk = wireEvents.slice(offset, offset + BATCH_SIZE);
+        const payloads = chunk.map((event, i) => toWirePayload(event, ordinals[offset + i], config.toolInstallationId));
+        let response;
+        try {
+            response = await fetch(`${config.apiBaseUrl}/v1/tool-events/batch`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${config.eventWriteToken}`
+                },
+                body: JSON.stringify({ events: payloads })
+            });
+        }
+        catch {
+            result.httpFailures += 1;
+            continue; // Transport failure: skip this chunk, keep going — the stable
+            // importKey makes a later re-run of just the gaps safe to reconcile.
+        }
+        result.sent += chunk.length;
+        if (!response.ok) {
+            result.httpFailures += 1;
+            if (response.status === 401 || response.status === 403) {
+                throw new Error(`Ingest refused (${response.status}) — token invalid/revoked or consent missing; aborting rather than burning ${wireEvents.length - offset} more events`);
+            }
+            continue;
+        }
+        try {
+            const body = (await response.json());
+            result.accepted += body.accepted ?? 0;
+            result.duplicate += body.duplicate ?? 0;
+            result.rejected += body.rejected ?? 0;
+            for (const item of body.results ?? []) {
+                // Duplicates have their own counter; bucketing them as rejection
+                // reasons too would report the same events twice under two headings.
+                if (item.status !== "accepted" && item.status !== "duplicate") {
+                    const reason = item.reason ?? "unknown";
+                    result.rejectionReasons[reason] = (result.rejectionReasons[reason] ?? 0) + 1;
+                }
+            }
+        }
+        catch {
+            result.httpFailures += 1;
+        }
+        onProgress?.(Math.min(offset + BATCH_SIZE, wireEvents.length), wireEvents.length);
+    }
+    return result;
+}
+//# sourceMappingURL=ship.js.map

package/dist/ship.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship.js","sourceRoot":"","sources":["../src/ship.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EAExB,YAAY,EACb,MAAM,YAAY,CAAC;AAQpB,MAAM,CAAC,MAAM,oBAAoB,GAAG,yBAAyB,CAAC;AAE9D,yEAAyE;AACzE,MAAM,UAAU,cAAc;IAC5B,MAAM,UAAU,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,oBAAoB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACjG,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC;IACvD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,uGAAuG,CACxG,CAAC;IACJ,CAAC;IACD,MAAM,kBAAkB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;IACrG,MAAM,aAAa,GACjB,OAAO,CAAC,GAAG,CAAC,8BAA8B,IAAI,oBAAoB,CAAC,kBAAkB,CAAC,CAAC;IACzF,MAAM,eAAe,GAAG,aAAa,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IAC9F,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,2BAA2B,aAAa,iCAAiC,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmC;IAChE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,IAAI,CAC5F,GAAG,CACJ,CAAC;QACF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAgC,EAAE,OAAe;IAC3E,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CACL,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAC5F,GAAG,CACJ,CACF;SACA,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAAkF,EAClF,OAAe,EACf,kBAA0B;IAE1B,MAAM,QAAQ,GAA8C;QAC1D,SAAS,EAAE,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC;QACtC,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,YAAY,EAAE,CAAC;KAChB,CAAC;IACF,IAAI,KAAK,CAAC,aAAa;QAAE,QAAQ,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IACtE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC;IACD,0EAA0E;IAC1E,8EAA8E;IAC9E,IAAI,OAAO,QAAQ,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3C,QAAQ,CAAC,aAAa,GAAG,mBAAmB,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACvE,OAAO,QAAQ,CAAC,SAAS,CAAC;IAC5B,CAAC;IACD,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChF,OAAO;QACL,kBAAkB;QAClB,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAA2B;QAC3D,oEAAoE;QACpE,kEAAkE;QAClE,yEAAyE;QACzE,mEAAmE;QACnE,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,wEAAwE;QACxE,iEAAiE;QACjE,6DAA6D;QAC7D,gBAAgB,EAAE,kBAAkB,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAChE,QAAQ,EAAE,KAAK;QACf,SAAS,EAAE,KAAK,CAAC,UAAU;QAC3B,aAAa;QACb,WAAW,EAAE,aAAa;QAC1B,qEAAqE;QACrE,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,sBAAsB;QACtB,YAAY,EAAE,wBAAwB;QACtC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EAAE,eAAe;QAC5B,QAAQ;KACT,CAAC;AACJ,CAAC;AAoBD,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAmC;IAEnC,OAAO,MAAM,CAAC,MAAM,CAClB,CAAC,CAAC,EAAoF,EAAE,CACtF,CAAC,CAAC,SAAS,KAAK,qBAAqB,CACxC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAmC,EACnC,MAAkB,EAClB,UAAkD;IAElD,MAAM,MAAM,GAAe;QACzB,IAAI,EAAE,CAAC;QACP,QAAQ,EAAE,CAAC;QACX,SAAS,EAAE,CAAC;QACZ,QAAQ,EAAE,CAAC;QACX,gBAAgB,EAAE,EAAE;QACpB,YAAY,EAAE,CAAC;KAChB,CAAC;IACF,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAC3C,wEAAwE;IACxE,yEAAyE;IACzE,sEAAsE;IACtE,uCAAuC;IACvC,MAAM,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAC5C,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,IAAI,UAAU,EAAE,CAAC;QACtE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CACtC,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,kBAAkB,CAAC,CACtE,CAAC;QACF,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,CAAC,UAAU,uBAAuB,EAAE;gBAClE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,aAAa,EAAE,UAAU,MAAM,CAAC,eAAe,EAAE;iBAClD;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;aAC3C,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;YACzB,SAAS,CAAC,8DAA8D;YACxE,qEAAqE;QACvE,CAAC;QACD,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;YACzB,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACvD,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,CAAC,MAAM,8EAA8E,UAAU,CAAC,MAAM,GAAG,MAAM,cAAc,CACzJ,CAAC;YACJ,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAKlC,CAAC;YACF,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;YACtC,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;YACxC,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;YACtC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACtC,iEAAiE;gBACjE,qEAAqE;gBACrE,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;oBAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,SAAS,CAAC;oBACxC,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;gBAC/E,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;QAC3B,CAAC;QACD,UAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/staging.js

@@ -0,0 +1,121 @@
+/**
+ * Copy-then-parse.
+ *
+ * Every store is a live file another process is writing: Claude Code appends
+ * to the transcript mid-session, Cursor's db is WAL-mode with a hot journal.
+ * Parsing in place risks torn reads AND ties extraction time to purge time —
+ * a Claude cleanup running mid-extract would delete lines under the parser.
+ * So extraction always runs against a snapshot, stamped with an extraction id
+ * that every emitted event carries (it is also the natural idempotency key
+ * for backend dedup).
+ */
+import * as fs from "node:fs/promises";
+import { constants } from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+/** Clone-on-write when the filesystem supports it (APFS does): a 2.3 GB
+ * store snapshots in milliseconds and costs no disk until the live files
+ * diverge. NOT `FICLONE_FORCE` — on filesystems without reflinks this must
+ * degrade to a real copy, not an error. */
+const CLONE = constants.COPYFILE_FICLONE;
+/** Default staging root. Local, never synced, never shipped — raw records
+ * (including UNPARSED ones) stay here on the machine. */
+export function defaultStagingRoot(home) {
+    return path.join(home, ".ascenda", "history-import", "staging");
+}
+export async function createStagingArea(stagingRoot) {
+    const extractionId = `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`;
+    const root = path.join(stagingRoot, extractionId);
+    await fs.mkdir(root, { recursive: true });
+    return { extractionId, root };
+}
+/**
+ * Snapshot a file or directory into the staging area. For SQLite stores pass
+ * the db path — the `-wal` and `-shm` siblings are picked up automatically,
+ * because a WAL db copied without its journal silently loses the newest
+ * transactions (the most recent sessions: exactly the ones a user would
+ * notice missing).
+ */
+export async function snapshotPath(area, sourcePath, label) {
+    const dest = path.join(area.root, label);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    const st = await fs.stat(sourcePath);
+    if (st.isDirectory()) {
+        await fs.cp(sourcePath, dest, {
+            recursive: true,
+            errorOnExist: false,
+            force: true,
+            mode: CLONE
+        });
+    }
+    else {
+        await fs.copyFile(sourcePath, dest, CLONE);
+        for (const suffix of ["-wal", "-shm"]) {
+            try {
+                await fs.copyFile(sourcePath + suffix, dest + suffix, CLONE);
+            }
+            catch {
+                // No journal sibling — a checkpointed or non-WAL db. Fine.
+            }
+        }
+    }
+    return dest;
+}
+/**
+ * Surgical snapshot of `Code/User/workspaceStorage` for the VS Code
+ * extractor: only `workspace.json` (workspace identity) and
+ * `chatSessions/*.json` and `chatSessions/*.jsonl` (Copilot sessions) per
+ * hash directory, never the
+ * rest — `state.vscdb`, `state.vscdb.backup`, extension caches and other
+ * per-workspace artifacts live alongside those two and can run to gigabytes
+ * across dozens of workspaces, none of it needed by this extractor. A plain
+ * `snapshotPath` recursive copy would drag all of it into staging for
+ * nothing; this walks the hash directories itself and copies only what the
+ * extractor reads.
+ */
+export async function snapshotVsCodeWorkspaceStorage(area, sourceRoot, label) {
+    const dest = path.join(area.root, label);
+    await fs.mkdir(dest, { recursive: true });
+    let hashDirs = [];
+    try {
+        hashDirs = (await fs.readdir(sourceRoot, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return dest; // No workspaceStorage on this machine — an empty snapshot, not an error.
+    }
+    for (const hash of hashDirs) {
+        const destHashDir = path.join(dest, hash);
+        const workspaceJson = path.join(sourceRoot, hash, "workspace.json");
+        try {
+            await fs.mkdir(destHashDir, { recursive: true });
+            await fs.copyFile(workspaceJson, path.join(destHashDir, "workspace.json"), CLONE);
+        }
+        catch {
+            // No workspace.json for this hash — common, and chatSessions below may
+            // still exist and be worth copying.
+        }
+        const chatSessionsDir = path.join(sourceRoot, hash, "chatSessions");
+        let sessionFiles = [];
+        try {
+            // Both on-disk shapes: `.json` (pre-Feb-2026) and `.jsonl` (the delta-log
+            // format VS Code migrated to). Filtering to `.json` here is what kept
+            // seven months of sessions out of staging entirely — the extractor never
+            // saw them, so it could not even report them as unread.
+            sessionFiles = (await fs.readdir(chatSessionsDir)).filter((f) => f.endsWith(".json") || f.endsWith(".jsonl"));
+        }
+        catch {
+            continue; // Most workspaces have no chatSessions dir — the norm.
+        }
+        if (sessionFiles.length === 0)
+            continue;
+        const destSessionsDir = path.join(destHashDir, "chatSessions");
+        await fs.mkdir(destSessionsDir, { recursive: true });
+        for (const file of sessionFiles) {
+            await fs.copyFile(path.join(chatSessionsDir, file), path.join(destSessionsDir, file), CLONE);
+        }
+    }
+    return dest;
+}
+//# sourceMappingURL=staging.js.map

package/dist/staging.js.map

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

package/dist/stores.js

@@ -0,0 +1,25 @@
+/**
+ * Where each store lives on disk. Resolution is centralised here because the
+ * paths are the reverse-engineered part of the whole design: every one of
+ * them (except git) is an undocumented internal of someone else's product,
+ * and when an upstream release moves a store, this file is where the fix
+ * lands.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+export function resolveStorePaths(home = os.homedir()) {
+    const appSupport = path.join(home, "Library", "Application Support");
+    return {
+        home,
+        claudeRoot: path.join(home, ".claude"),
+        claudeProjects: path.join(home, ".claude", "projects"),
+        claudeSettings: path.join(home, ".claude", "settings.json"),
+        cursorStateDb: path.join(appSupport, "Cursor", "User", "globalStorage", "state.vscdb"),
+        cursorSearchDb: path.join(appSupport, "Cursor", "User", "globalStorage", "conversation-search.db"),
+        vscodeHistory: path.join(appSupport, "Code", "User", "History"),
+        vscodeWorkspaceStorage: path.join(appSupport, "Code", "User", "workspaceStorage"),
+        devRoot: path.join(home, "Dev"),
+        zshHistory: path.join(home, ".zsh_history")
+    };
+}
+//# sourceMappingURL=stores.js.map

package/dist/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.js","sourceRoot":"","sources":["../src/stores.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAsBlC,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,CAAC,OAAO,EAAE;IAC3D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,qBAAqB,CAAC,CAAC;IACrE,OAAO;QACL,IAAI;QACJ,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;QACtC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC;QACtD,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,eAAe,CAAC;QAC3D,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC;QACtF,cAAc,EAAE,IAAI,CAAC,IAAI,CACvB,UAAU,EACV,QAAQ,EACR,MAAM,EACN,eAAe,EACf,wBAAwB,CACzB;QACD,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC;QAC/D,sBAAsB,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC;QACjF,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC;QAC/B,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/dist/types.js

@@ -0,0 +1,74 @@
+/**
+ * Shared shapes for the retrospective import.
+ *
+ * The design rules these encode come from the research note in the Flow
+ * workspace (`docs/HISTORICAL_TELEMETRY_IMPORT.md`): copy-then-parse,
+ * per-record schema sniffing, UNPARSED over guessing, and provenance class
+ * carried as data on every event so downstream charts can render HISTORICAL
+ * bars distinctly from LIVE ones.
+ */
+import { ASCENDA_HISTORICAL_CONSENT_SCOPE } from "@ascenda-one/tool-contract";
+/** The stores this importer knows how to read. Ordered by evaporation risk:
+ * Claude Code's 30-day rolling purge deletes a day of baseline every day the
+ * importer hasn't run, so it always extracts first. */
+export const HISTORY_STORES = ["claude_code", "cursor", "vscode", "git"];
+/** How each store's events identify on the existing telemetry wire. */
+export const STORE_SOURCE = {
+    claude_code: "claude_code",
+    cursor: "cursor_mcp",
+    vscode: "vscode_extension",
+    git: "code_forge"
+};
+/**
+ * Provenance classes for imported events. Live events carry
+ * `ASCENDA_PROVENANCE` ("ai_work_telemetry"); everything this package emits
+ * carries one of these instead, so no historical number can masquerade as a
+ * live observation.
+ *
+ * - `direct`: read verbatim from a store record (a timestamp, a token count).
+ * - `derived`: computed across records (session length, gap analysis).
+ * - `unparsed`: the record's self-labelled schema version was unknown; the
+ *   raw record is retained in staging and nothing was inferred from it.
+ */
+export const HISTORICAL_PROVENANCE = {
+    direct: "historical_direct",
+    derived: "historical_derived",
+    unparsed: "historical_unparsed"
+};
+/**
+ * The consent scope imported events must carry. A real `ToolConsentScope`
+ * (re-exported from tool-contract rather than restated here, so the two
+ * cannot drift): consenting to prospective `ide_telemetry` is not consenting
+ * to a read of nine months of history.
+ *
+ * **The backend does not enforce this yet, and this package must not ship as
+ * if it did.** `ConsentType.HistoricalImport` (507), the `historical_import`
+ * scope mapping and the provenance override are implemented on the asc-core-be
+ * branch `claude/historical-import-dedup-and-consent`, and are absent from
+ * `origin/main` — verified 19 Aug 2026, zero occurrences of `HistoricalImport`
+ * in `Services/` or `Models/` there.
+ *
+ * Until that branch merges, `ResolveConsentType` does not recognise
+ * `historical_import` and takes its default arm, `ConsentType.AiDataProcessing`
+ * — the lease a user already granted for ordinary live IDE telemetry. So
+ * against main today, nine months of retrospective history would ingest under
+ * a consent the user gave for something else, which is the precise outcome the
+ * separate scope exists to prevent.
+ *
+ * Sending this scope is still correct: it is what the enforcing backend keys
+ * on, and it makes the intent explicit in the audit record either way. What is
+ * not correct is publishing this package while a reader of this file would
+ * conclude the protection is live.
+ */
+export const HISTORICAL_CONSENT_SCOPE = ASCENDA_HISTORICAL_CONSENT_SCOPE;
+/**
+ * The extraction-window marker every extractor emits once per store. It is
+ * **not** a work event: it carries no session, no repo, and its metrics are
+ * statistics about the extraction run itself (observed window, unparsed file
+ * counts). It exists so `scan`/`import` can report the window and so the
+ * handoff can bound its own data, and the shipper drops it before the wire —
+ * there is no canonical telemetry type for "here is what I read", and
+ * inventing one would put extraction bookkeeping into the work catalog.
+ */
+export const EXTRACTION_EPOCH_KIND = "extraction_epoch";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAG9E;;uDAEuD;AACvD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAU,CAAC;AAGlF,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAiD;IACxE,WAAW,EAAE,aAAa;IAC1B,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,kBAAkB;IAC1B,GAAG,EAAE,YAAY;CAClB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,MAAM,EAAE,mBAAmB;IAC3B,OAAO,EAAE,oBAAoB;IAC7B,QAAQ,EAAE,qBAAqB;CACvB,CAAC;AAIX;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,gCAAgC,CAAC;AAoBzE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAA2B,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "publishConfig": { "access": "public" },
+  "name": "@ascenda-one/history-import",
+  "version": "0.1.12",
+  "description": "Retrospective AI-usage import for Ascenda work telemetry — extracts the baseline already sitting in Claude Code, Cursor and VS Code stores.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ascendaone-com/ai-engineer-tools.git",
+    "directory": "ascenda-history-import"
+  },
+  "type": "module",
+  "files": ["dist"],
+  "bin": {
+    "ascenda-history-import": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p ./ && npm run bundle",
+    "watch": "tsc -w -p ./",
+    "bundle": "esbuild src/cli.ts --bundle --platform=node --format=esm --banner:js=\"import { createRequire as __cr } from 'node:module'; const require = __cr(import.meta.url);\" --outfile=dist/cli.js",
+    "test": "node --test"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "typescript": "^5.5.0",
+    "@ascenda-one/tool-contract": "*",
+    "@ascenda-one/tool-kit": "*"
+  }
+}