@chainlesschain/personal-data-hub 0.3.0 → 0.3.6

package/lib/adapters/social-xiaohongshu-adb/sign.js

@@ -0,0 +1,90 @@
+"use strict";
+
+/**
+ * Phase 3c (Xhs C 路径 — 2026-05-25): X-S signature generator (Node port).
+ *
+ * Byte-parity port of
+ * `android-app/.../pdh/social/xiaohongshu/XhsApiClient.kt`:computeXsXt.
+ *
+ * **Real xhs.js algorithm (open-source reverse-engineered, best-effort)**:
+ *   1. payload = "url=" + url_path_with_query + ("" or body_json)
+ *   2. raw = ts_ms + payload + a1_cookie
+ *   3. md5_hex = MD5(raw).hex()                — hex STRING (not bytes)
+ *   4. X-S = "XYW_" + base64(utf8_bytes(md5_hex))
+ *      Critical: base64 encodes the UTF-8 bytes of the hex STRING, not
+ *      the raw 16 MD5 bytes. This is what xhs.js does — it stringifies
+ *      the digest before base64-ing it.
+ *   5. X-T = ts_ms (as decimal string)
+ *
+ * **Real xhs.js does one more step after step 3** — XOR-rotate with a
+ * key derived from b1 cookie, then base64 with `=` padding. v0.2 we
+ * skip that step → ~60% GET hit rate, <30% POST hit rate. UI banner
+ * surfaces lastErrorCode=461 when xhs rejects our X-S; collector
+ * gracefully degrades to emptyList() per endpoint.
+ *
+ * Future Phase 3c-v0.3: a WebView-based bridge (see Android-side
+ * XhsSignBridge.kt — runs xhs's own JS in a hidden Electron BrowserView)
+ * would push the hit rate to ~100%. Out of scope for v0.2 Node port.
+ */
+
+const crypto = require("node:crypto");
+
+/** "XYW_" prefix — matches xhs.js output. */
+const XS_PREFIX = "XYW_";
+
+/**
+ * Compute X-S + X-T headers for a GET request.
+ *
+ * @param {string} urlPathWithQuery   url.pathname + url.search (path + "?" + query, encoded)
+ * @param {string|null} body          POST body as a JSON string, or null/empty for GET
+ * @param {string} a1                 a1 cookie value (anti-bot fingerprint)
+ * @param {{now?: () => number}} [opts]  test seam — inject `now: () => 1716383021000`
+ * @returns {{xs: string, xt: string}}
+ */
+function computeXsXt(urlPathWithQuery, body, a1, opts = {}) {
+  if (typeof urlPathWithQuery !== "string" || urlPathWithQuery.length === 0) {
+    throw new TypeError("computeXsXt: urlPathWithQuery must be non-empty string");
+  }
+  if (typeof a1 !== "string" || a1.length === 0) {
+    throw new TypeError("computeXsXt: a1 must be non-empty string");
+  }
+  const ts = (opts.now || Date.now)();
+  const bodyStr = typeof body === "string" ? body : "";
+  const payload = "url=" + urlPathWithQuery + bodyStr;
+  const raw = `${ts}${payload}${a1}`;
+  const md5Hex = crypto.createHash("md5").update(raw, "utf8").digest("hex");
+  // base64 encode the UTF-8 bytes of the hex STRING (32 chars → 32 bytes
+  // → 44-char base64 with padding). xhs.js NO_WRAP NO_PADDING flags
+  // mirror: replace = padding with "", remove newlines (default in
+  // Buffer.toString("base64") already no-newlines, only padding to strip).
+  const b64NoPad = Buffer.from(md5Hex, "utf8").toString("base64").replace(/=+$/, "");
+  return {
+    xs: XS_PREFIX + b64NoPad,
+    xt: String(ts),
+  };
+}
+
+/**
+ * Extract a1 cookie value from a Cookie header string.
+ *
+ *   "web_session=abc; a1=18d6e123abc; xsec_token=xxx" → "18d6e123abc"
+ *
+ * Returns null when a1 not present.
+ */
+function extractA1(cookie) {
+  if (typeof cookie !== "string") return null;
+  for (const part of cookie.split(";")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith("a1=")) {
+      const v = trimmed.substring(3);
+      return v.length > 0 ? v : null;
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  computeXsXt,
+  extractA1,
+  XS_PREFIX,
+};

package/lib/adapters/social-xiaohongshu-adb/snapshot-builder.js

@@ -0,0 +1,126 @@
+"use strict";
+
+/**
+ * Phase 3c (Xhs C 路径 — 2026-05-25): API responses → snapshot JSON.
+ *
+ * Matches the existing `social-xiaohongshu` adapter's snapshot mode
+ * schema (schemaVersion=1). Kinds: note / liked / follow.
+ *
+ * Note: xhs userId is a Base64-ish string (e.g. "5e8c8f7e..."), not a
+ * numeric Long. The account.uid in the snapshot is set to userId
+ * verbatim (string passthrough); consumers shouldn't expect numeric uid.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+const SNAPSHOT_SCHEMA_VERSION = 1;
+
+function buildSnapshot(input) {
+  if (!input || typeof input !== "object") {
+    throw new TypeError("buildSnapshot: input must be an object");
+  }
+  const userId = input.userId;
+  if (typeof userId !== "string" || userId.length === 0) {
+    throw new TypeError("buildSnapshot: input.userId must be a non-empty string");
+  }
+  const snapshottedAt =
+    Number.isFinite(input.snapshottedAt) && input.snapshottedAt > 0
+      ? input.snapshottedAt
+      : Date.now();
+  const account = {
+    userId, // xhs userId is a string, not numeric
+    nickname: typeof input.nickname === "string" ? input.nickname : "",
+  };
+  const events = [];
+
+  // notes
+  const notes = Array.isArray(input.notes) ? input.notes : [];
+  notes.forEach((n, idx) => {
+    if (!n || typeof n !== "object") return;
+    events.push({
+      kind: "note",
+      id: n.noteId ? `note-${n.noteId}` : `note-${idx}`,
+      capturedAt:
+        typeof n.createdAt === "number" && n.createdAt > 0
+          ? n.createdAt
+          : snapshottedAt,
+      noteId: n.noteId || null,
+      title: n.title || null,
+      desc: n.desc || null,
+      type: n.type || "normal",
+      likedCount: typeof n.likedCount === "number" ? n.likedCount : 0,
+      collectedCount:
+        typeof n.collectedCount === "number" ? n.collectedCount : 0,
+      commentCount: typeof n.commentCount === "number" ? n.commentCount : 0,
+    });
+  });
+
+  // liked
+  const liked = Array.isArray(input.liked) ? input.liked : [];
+  liked.forEach((l, idx) => {
+    if (!l || typeof l !== "object") return;
+    events.push({
+      kind: "liked",
+      id: l.noteId ? `liked-${l.noteId}` : `liked-${idx}`,
+      // xhs doesn't return liked_at — use snapshottedAt
+      capturedAt: snapshottedAt,
+      noteId: l.noteId || null,
+      title: l.title || null,
+      authorNickname: l.authorNickname || null,
+    });
+  });
+
+  // follows
+  const follows = Array.isArray(input.follows) ? input.follows : [];
+  follows.forEach((f, idx) => {
+    if (!f || typeof f !== "object") return;
+    events.push({
+      kind: "follow",
+      id: f.userId ? `follow-${f.userId}` : `follow-${idx}`,
+      capturedAt: snapshottedAt,
+      userId: f.userId || null,
+      nickname: f.nickname || null,
+      image: f.image || null,
+    });
+  });
+
+  return {
+    schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+    snapshottedAt,
+    account,
+    events,
+  };
+}
+
+function writeSnapshotJson(snapshot, opts = {}) {
+  const dir = opts.dir || os.tmpdir();
+  const fileName =
+    opts.fileName || `cc-xhs-snapshot-${crypto.randomUUID()}.json`;
+  if (fileName.includes("/") || fileName.includes("\\")) {
+    throw new Error(
+      "writeSnapshotJson: opts.fileName must be a basename, not a path",
+    );
+  }
+  const full = path.join(dir, fileName);
+  fs.writeFileSync(full, JSON.stringify(snapshot), "utf-8");
+  return full;
+}
+
+function cleanupSnapshotJson(filePath) {
+  if (!filePath) return;
+  try {
+    fs.unlinkSync(filePath);
+  } catch (_e) {
+    // ignore
+  }
+}
+
+module.exports = {
+  buildSnapshot,
+  writeSnapshotJson,
+  cleanupSnapshotJson,
+  SNAPSHOT_SCHEMA_VERSION,
+};

package/lib/adapters/system-data-android/adapter.js

@@ -28,13 +28,28 @@ const {
 } = require("../../constants");
 
 const NAME = "system-data-android";
+// v0.3.2 (2026-05-25): denormalise contact identifiers (phones/emails/
+//   organization/starred) and app version/install fields onto
+//   event.extra so the Vault Browser tap-to-detail sheet can render
+//   human-readable fields without joining back to the persons/items
+//   tables. Same content lives on the entity rows; events are now a
+//   convenience copy. Adds ~50-200 bytes per event but keeps the detail
+//   UI single-table.
+// v0.3.1 (2026-05-25): normalize() now emits a synthetic OTHER event per
+//   contact + per app. Snapshot mode previously only wrote persons/items;
+//   Vault Browser's `category=system` facet only counts events, so the
+//   chip showed (0) forever even after a successful sync. Synthetic event
+//   per entity (stable id, idempotent across re-syncs via UPSERT) lights
+//   up the chip with `total = #contacts + #apps`. occurredAt = capturedAt
+//   of the latest snapshot containing the entity. sms/call/media events
+//   were already emitted in v0.2 — unchanged.
 // v0.3.0 (2026-05-24): added kind="media-file" via bridge mode
 //   (host-adb-bridge media.list across 5 /sdcard categories). Metadata
 //   only — path/size/mtime/ext, no file content.
 // v0.2.0 (2026-05-24): added kind="sms" + kind="call" via bridge mode.
 //   Snapshot mode still v1 schema — sms/calls/media only land via
 //   bridge path until Android snapshot writer is updated to include them.
-const VERSION = "0.3.0";
+const VERSION = "0.3.2";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 
 // Stable per-source originalId — registry.putRawEvent rejects null originalId
@@ -391,8 +406,42 @@ class SystemDataAndroidAdapter {
       if (typeof p.photoUri === "string" && p.photoUri.length > 0) extra.photoUri = p.photoUri;
       if (Object.keys(extra).length > 0) person.extra = extra;
 
+      // v0.3.1 — synthesise an OTHER event so the snapshot contact shows up
+      // in the Vault Browser's `category=system` facet (which counts events,
+      // not persons). Stable id keyed on stableKey makes re-syncs idempotent
+      // via UPSERT; occurredAt floats forward to the latest snapshot time
+      // ("last time we saw this contact").
+      //
+      // v0.3.2 — duplicate the contact's identifying fields onto event.extra
+      // so the Vault Browser's tap-to-detail sheet can render them inline
+      // without joining back to the persons table. Phones/emails/relation/
+      // starred — same data shape as person.identifiers + person.relation
+      // + person.extra, just denormalised so a single events-table read
+      // suffices for the detail UI.
+      const eventExtra = { kind: "contact-snapshot" };
+      if (identifiers.phone && identifiers.phone.length > 0) {
+        eventExtra.phones = identifiers.phone;
+      }
+      if (identifiers.email && identifiers.email.length > 0) {
+        eventExtra.emails = identifiers.email;
+      }
+      if (typeof p.organization === "string" && p.organization.trim().length > 0) {
+        eventExtra.organization = p.organization.trim();
+      }
+      if (typeof p.starred === "boolean") eventExtra.starred = p.starred;
+      const event = {
+        id: `event-android-contact-${stableKey}`,
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.OTHER,
+        occurredAt: raw.capturedAt,
+        ingestedAt,
+        source: source(`android-contact:${stableKey}`),
+        content: { title: `联系人：${displayName}` },
+        extra: eventExtra,
+      };
+
       return {
-        events: [],
+        events: [event],
         persons: [person],
         places: [],
         items: [],
@@ -428,8 +477,33 @@ class SystemDataAndroidAdapter {
         },
       };
 
+      // v0.3.1 — same rationale as the contact branch: emit a synthetic
+      // OTHER event so installed apps show up in the system facet count.
+      // v0.3.2 — copy versioning/install fields onto event.extra so the
+      // detail sheet can render them inline.
+      const eventExtra = { kind: "app-snapshot", packageName: pkgName };
+      if (typeof a.versionName === "string" && a.versionName.length > 0) {
+        eventExtra.versionName = a.versionName;
+      }
+      if (Number.isInteger(a.versionCode)) eventExtra.versionCode = a.versionCode;
+      if (Number.isInteger(a.firstInstallTime)) {
+        eventExtra.firstInstallTime = a.firstInstallTime;
+      }
+      if (Number.isInteger(a.lastUpdateTime)) eventExtra.lastUpdateTime = a.lastUpdateTime;
+      if (typeof a.isSystem === "boolean") eventExtra.isSystem = a.isSystem;
+      const event = {
+        id: `event-android-app-${pkgName}`,
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.OTHER,
+        occurredAt: raw.capturedAt,
+        ingestedAt,
+        source: source(`android-app:${pkgName}`),
+        content: { title: `应用：${label}` },
+        extra: eventExtra,
+      };
+
       return {
-        events: [],
+        events: [event],
         persons: [],
         places: [],
         items: [item],

package/lib/adapters/travel-12306/index.js

@@ -1,18 +1,39 @@
 /**
- * Phase 9.2 — 12306 (China Railway) ticket adapter.
+ * §2.5 v0.2 — 12306 (China Railway) ticket adapter, dual-mode.
  *
- * Source format: 12306 doesn't have an official user export. We accept
- * two file formats:
- *   1. order-confirmation emails (already adapter-parsed by Phase 5 +
- *      Phase 5.4 travel template). Phase 9.2 reads those events back
- *      out of the vault and **re-normalizes** them into the
- *      adapter-neutral travel schema. This is the "rich vault →
- *      enrich" pattern.
- *   2. user-uploaded JSON dump (e.g. exported from a 3rd-party 12306
- *      scraper, or hand-curated). Optional.
+ *   1. snapshot mode (opts.inputPath): in-APK Android cc reads a snapshot
+ *      JSON produced by the phone's Kyfw12306LocalCollector. The collector
+ *      uses captured login cookie to hit kyfw.12306.cn `/otn/queryOrder/
+ *      queryMyOrder` + `/otn/queryOrder/queryMyOrderNoComplete` (cookie-only,
+ *      no signing), parses each ticket into a structured event, writes JSON.
+ *      Desktop-independent. account is OPTIONAL at construction.
  *
- * For v0.5 we focus on (2) since (1) is purely vault-side derivation
- * the AnalysisEngine can do at query time.
+ *   2. file-import mode (opts.dataPath, legacy v0.5): user-uploaded JSON
+ *      dump from a 3rd-party 12306 scraper or hand-curated. Preserved for
+ *      backward compat. account.username REQUIRED.
+ *
+ * Snapshot schema (mirrors Kyfw12306LocalCollector.SNAPSHOT_SCHEMA_VERSION):
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "snapshottedAt": <epoch-ms>,
+ *     "vendor": "12306",
+ *     "events": [
+ *       { "kind": "ticket", "id": "ticket-<seqNo>:<n>",  "capturedAt": <ms>,
+ *         "orderSequenceNo": "...", "ticketNumber": "...",
+ *         "passengerName": "张三", "passengerIdLast6": "123456",
+ *         "trainNumber": "G123",
+ *         "fromStation": "上海虹桥", "toStation": "北京南",
+ *         "departureMs": <ms>, "arrivalMs": <ms>,
+ *         "seatTypeName": "二等座", "coachNo": "05", "seatNo": "12A",
+ *         "ticketPrice": 553.5, "orderDateMs": <ms>, "orderTotalPrice": 553.5,
+ *         "isCompleted": true }
+ *     ]
+ *   }
+ *
+ * Sensitivity: medium — ticket history reveals travel patterns + 6 trailing
+ * digits of national ID (used for cross-source EntityResolver linking, never
+ * exposed in vault search). Snapshot file is purged after sync.
  */
 
 "use strict";
@@ -21,32 +42,75 @@ const fs = require("node:fs");
 const { normalizeTravelRecord, parseChineseDateTime } = require("../travel-base");
 
 const NAME = "travel-12306";
-const VERSION = "0.5.0";
+const VERSION = "0.6.0";
+const SNAPSHOT_SCHEMA_VERSION = 1;
+
+const KIND_TICKET = "ticket";
+const VALID_SNAPSHOT_KINDS = Object.freeze([KIND_TICKET]);
 
 class Train12306Adapter {
   constructor(opts = {}) {
-    if (!opts.account || !opts.account.username) {
-      throw new Error("Train12306Adapter: opts.account.username required (12306 user id)");
-    }
-    this.account = opts.account;
+    // §2.5 v0.2: account.username OPTIONAL — snapshot mode is stateless and
+    // doesn't need a pre-known username. file-import mode still requires it,
+    // checked at sync time, not construction.
+    this.account = opts.account || null;
     this._dataPath = opts.dataPath || null;
 
     this.name = NAME;
     this.version = VERSION;
-    this.capabilities = ["import:json", "parse:12306-orders"];
-    this.extractMode = "file-import";
+    this.capabilities = [
+      "sync:snapshot",
+      "import:json",
+      "parse:12306-orders",
+    ];
+    this.extractMode = "device-pull";
     this.rateLimits = {};
     this.dataDisclosure = {
       fields: [
-        "12306:orderId / passengerName / trainNumber / fromStation / toStation / departureTime / arrivalTime / seat / price",
+        "12306:orderSequenceNo / ticketNumber / passengerName / trainNumber / fromStation / toStation / departureMs / arrivalMs / seat / price",
       ],
       sensitivity: "medium",
       legalGate: false,
+      defaultInclude: {
+        ticket: true,
+      },
+    };
+
+    // _deps injection seam — vi.mock fs doesn't intercept inlined CJS require.
+    this._deps = {
+      fs,
     };
   }
 
-  async authenticate() {
-    return { ok: true, account: this.account.username };
+  async authenticate(ctx = {}) {
+    if (ctx && typeof ctx.inputPath === "string" && ctx.inputPath.length > 0) {
+      try {
+        this._deps.fs.accessSync(ctx.inputPath, this._deps.fs.constants.R_OK);
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "INPUT_PATH_UNREADABLE",
+          message: `snapshot not readable at ${ctx.inputPath}: ${err.message}`,
+        };
+      }
+      return { ok: true, mode: "snapshot-file" };
+    }
+    if (this._dataPath || (ctx && typeof ctx.dataPath === "string")) {
+      if (!this.account || !this.account.username) {
+        return {
+          ok: false,
+          reason: "NO_ACCOUNT_USERNAME",
+          message: "travel-12306.authenticate: file-import mode requires account.username",
+        };
+      }
+      return { ok: true, account: this.account.username, mode: "file-import" };
+    }
+    return {
+      ok: false,
+      reason: "NO_INPUT",
+      message:
+        "travel-12306.authenticate: needs opts.inputPath (snapshot mode) OR opts.dataPath (file-import mode)",
+    };
   }
 
   async healthCheck() {
@@ -54,14 +118,83 @@ class Train12306Adapter {
   }
 
   async *sync(opts = {}) {
+    if (typeof opts.inputPath === "string" && opts.inputPath.length > 0) {
+      yield* this._syncViaSnapshot(opts);
+      return;
+    }
     const dataPath = opts.dataPath || this._dataPath;
-    if (!dataPath || !fs.existsSync(dataPath)) return;
-    const buf = fs.readFileSync(dataPath, "utf-8");
+    if (dataPath) {
+      yield* this._syncViaFileImport({ ...opts, dataPath });
+      return;
+    }
+    throw new Error(
+      "travel-12306.sync: needs opts.inputPath (snapshot mode, Android in-APK cc) OR opts.dataPath (file-import mode, user-uploaded JSON)",
+    );
+  }
+
+  async *_syncViaSnapshot(opts) {
+    const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
+    const snapshot = JSON.parse(raw);
+    if (
+      !snapshot ||
+      typeof snapshot !== "object" ||
+      snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION
+    ) {
+      throw new Error(
+        `travel-12306.sync: snapshot schemaVersion mismatch (got ${snapshot && snapshot.schemaVersion}, expected ${SNAPSHOT_SCHEMA_VERSION})`,
+      );
+    }
+    const fallbackCapturedAt =
+      Number.isFinite(snapshot.snapshottedAt) && snapshot.snapshottedAt > 0
+        ? Math.floor(snapshot.snapshottedAt)
+        : Date.now();
+    const include = opts.include || {};
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+
+    const events = Array.isArray(snapshot.events) ? snapshot.events : [];
+    let emitted = 0;
+    for (const ev of events) {
+      if (emitted >= limit) return;
+      if (!ev || typeof ev !== "object") continue;
+      const kind = ev.kind;
+      if (!VALID_SNAPSHOT_KINDS.includes(kind)) continue;
+      if (include[kind] === false) continue;
+
+      const capturedAt =
+        (Number.isFinite(ev.capturedAt) && ev.capturedAt) ||
+        (Number.isFinite(ev.departureMs) && ev.departureMs) ||
+        fallbackCapturedAt;
+      const id =
+        (typeof ev.id === "string" && ev.id.length > 0 && ev.id) ||
+        ev.orderSequenceNo ||
+        null;
+
+      yield {
+        adapter: NAME,
+        kind,
+        originalId: stableOriginalId(id || `unknown-${emitted}`),
+        capturedAt,
+        payload: { ...ev, snapshot: true },
+      };
+      emitted += 1;
+    }
+  }
+
+  async *_syncViaFileImport(opts) {
+    if (!this.account || !this.account.username) {
+      throw new Error(
+        "travel-12306._syncViaFileImport: account.username required (set via new Train12306Adapter({ account: { username } }))",
+      );
+    }
+    const dataPath = opts.dataPath;
+    if (!dataPath || !this._deps.fs.existsSync(dataPath)) return;
+    const buf = this._deps.fs.readFileSync(dataPath, "utf-8");
     let records;
     try {
       records = parseRecords(buf);
     } catch (err) {
-      throw new Error(`Train12306Adapter: parse failed: ${err.message}`);
+      throw new Error(`travel-12306._syncViaFileImport: parse failed: ${err.message}`);
     }
     for (const r of records) {
       yield {
@@ -74,7 +207,18 @@ class Train12306Adapter {
   }
 
   normalize(raw) {
-    if (!raw || !raw.payload || !raw.payload.record) {
+    if (!raw || !raw.payload) {
+      throw new Error("Train12306Adapter.normalize: payload missing");
+    }
+    // Snapshot-mode payload is the parsed event directly; legacy file-import
+    // payload has `.record` (already normalized shape).
+    if (raw.payload.snapshot) {
+      return normalizeTravelRecord(snapshotEventToRecord(raw.payload), {
+        adapterName: NAME,
+        adapterVersion: VERSION,
+      });
+    }
+    if (!raw.payload.record) {
       throw new Error("Train12306Adapter.normalize: raw.payload.record missing");
     }
     return normalizeTravelRecord(raw.payload.record, {
@@ -84,8 +228,43 @@ class Train12306Adapter {
   }
 }
 
+function stableOriginalId(id) {
+  return `12306:ticket:${id}`;
+}
+
+/** Convert a v0.2 snapshot event into the adapter-neutral travel record
+ *  shape that [normalizeTravelRecord] expects. */
+function snapshotEventToRecord(ev) {
+  return {
+    vendorId: "12306",
+    recordId: String(ev.id || ev.orderSequenceNo || ev.ticketNumber),
+    vehicleType: "train",
+    from: { station: ev.fromStation },
+    to: { station: ev.toStation },
+    departureMs: ev.departureMs || null,
+    arrivalMs: ev.arrivalMs || null,
+    carrier: "12306",
+    vehicleNumber: ev.trainNumber,
+    totalCost:
+      Number.isFinite(ev.ticketPrice) && ev.ticketPrice > 0
+        ? { value: ev.ticketPrice, currency: "CNY" }
+        : null,
+    traveler: ev.passengerName,
+    confirmationCode: ev.ticketNumber || ev.orderSequenceNo,
+    bookedAt: ev.orderDateMs || null,
+    extras: {
+      seat: ev.seatTypeName,
+      coachNo: ev.coachNo,
+      seatNumber: ev.seatNo,
+      isCompleted: ev.isCompleted,
+      idLast6: ev.passengerIdLast6 || undefined,
+      orderTotalPrice: ev.orderTotalPrice || undefined,
+    },
+  };
+}
+
 /**
- * Parse a 12306 dump file. Accepts either:
+ * Parse a 12306 dump file (legacy v0.5 file-import mode). Accepts either:
  *   - JSON array of order objects
  *   - JSON object { orders: [...] }
  *   - JSONL (one order per line)
@@ -134,7 +313,7 @@ function orderToRecord(o) {
     extras: {
       seat: o.seat || o.seatType,
       seatNumber: o.seatNumber || o.seat_number,
-      idCardLast6: o.idLast6 || undefined, // for cross-source EntityResolver linking
+      idCardLast6: o.idLast6 || undefined,
     },
   };
 }
@@ -148,4 +327,11 @@ function numberOrParse(v) {
   return null;
 }
 
-module.exports = { Train12306Adapter, parseRecords, NAME, VERSION };
+module.exports = {
+  Train12306Adapter,
+  parseRecords,
+  NAME,
+  VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+  VALID_SNAPSHOT_KINDS,
+};