@rubytech/create-realagent 1.0.829 → 1.0.830

package/payload/platform/plugins/memory/bin/conversation-archive-ingest.mjs

@@ -0,0 +1,541 @@
+#!/usr/bin/env node
+// =============================================================================
+// conversation-archive-ingest.mjs — in-process orchestrator for
+// conversation-archive-ingest.sh (Task 894 — supersedes whatsapp-import bin).
+//
+// Source-agnostic. The same pipeline runs for every conversation source;
+// `--source <enum>` selects the normaliser at the top of the pipeline:
+//
+//   normalise  → bind canonical senders → derive conversationIdentity
+//   → look up prior :ConversationArchive (delta cursor)
+//   → sessionize delta at gap-hours boundaries
+//   → for each session: classify (mode='chat') → collect chunks
+//   → memoryIngest(parentLabel='ConversationArchive', source=<enum>)
+//
+// Argv (positional): <archive-path>
+// Argv (flags):       --source <whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|other>
+//                     --owner-element-id <id>
+//                     --participant-person-ids <csv>
+//                     --scope <admin|public>
+//                     [--session-gap-hours <N>]   (default 12)
+//                     [--account-id <accountId>]
+//                     [--timezone <iana>]
+//                     [--date-format <DD/MM/YY|MM/DD/YY|DD/MM/YYYY|MM/DD/YYYY>]
+//                     [--session-id <id>]
+//
+// Stdout (success): one JSON line — counters the skill needs to formulate
+// the three operator-facing messages. See SKILL.md for the shape.
+// Stderr: one [conversation-archive] FAIL line on failure, exit non-zero.
+// =============================================================================
+
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// 1. Resolve dist paths.
+// ---------------------------------------------------------------------------
+const platformRoot =
+  process.env.MAXY_PLATFORM_ROOT?.trim() ||
+  resolve(__dirname, "..", "..", "..");
+
+const NORMALISERS_PATH = resolve(
+  platformRoot,
+  "plugins",
+  "memory",
+  "mcp",
+  "dist",
+  "lib",
+  "conversation-normalisers",
+  "index.js",
+);
+const PIPELINE_PATH = resolve(
+  platformRoot,
+  "plugins",
+  "memory",
+  "mcp",
+  "dist",
+  "lib",
+  "conversation-pipeline",
+);
+const NEO4J_LIB_PATH = resolve(
+  platformRoot,
+  "plugins",
+  "memory",
+  "mcp",
+  "dist",
+  "lib",
+  "neo4j.js",
+);
+const LLM_CLASSIFIER_PATH = resolve(
+  platformRoot,
+  "plugins",
+  "memory",
+  "mcp",
+  "dist",
+  "lib",
+  "llm-classifier.js",
+);
+const MEMORY_INGEST_PATH = resolve(
+  platformRoot,
+  "plugins",
+  "memory",
+  "mcp",
+  "dist",
+  "tools",
+  "memory-ingest.js",
+);
+
+// ---------------------------------------------------------------------------
+// 2. Logger
+// ---------------------------------------------------------------------------
+function log(line) {
+  process.stderr.write(`[conversation-archive] ${line}\n`);
+}
+function fail(phase, fields) {
+  const fieldStr = Object.entries(fields)
+    .map(([k, v]) =>
+      typeof v === "string" && (v.includes(" ") || v.includes("="))
+        ? `${k}="${v.replace(/"/g, '\\"')}"`
+        : `${k}=${v ?? "-"}`,
+    )
+    .join(" ");
+  process.stderr.write(`[conversation-archive] FAIL phase=${phase} ${fieldStr}\n`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// 3. Argv parsing
+// ---------------------------------------------------------------------------
+const VALID_SOURCES = new Set([
+  "whatsapp",
+  "telegram",
+  "signal",
+  "linkedin-messages",
+  "zoom-transcript",
+  "meeting-minutes",
+  "imessage",
+  "slack",
+  "other",
+]);
+
+function parseArgv(argv) {
+  const args = argv.slice(2);
+  let archive = null;
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("--")) {
+      if (archive == null) archive = a;
+      else fail("argv", { reason: `unexpected positional argument "${a}"` });
+      continue;
+    }
+    const key = a.slice(2);
+    const v = args[++i];
+    if (v == null) fail("argv", { reason: `flag --${key} requires a value` });
+    flags[camelCase(key)] = v;
+  }
+  if (!archive) fail("argv", { reason: "missing positional <archive>" });
+  if (!flags.source) fail("argv", { reason: "missing --source" });
+  if (!VALID_SOURCES.has(flags.source)) {
+    fail("argv", { reason: `invalid --source "${flags.source}" (whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|other)` });
+  }
+  if (!flags.ownerElementId) fail("argv", { reason: "missing --owner-element-id" });
+  if (!flags.participantPersonIds) {
+    fail("argv", {
+      reason: "missing --participant-person-ids (csv of operator-confirmed :Person/:AdminUser elementIds, owner excluded)",
+    });
+  }
+  if (!flags.scope) fail("argv", { reason: "missing --scope" });
+  if (flags.scope !== "admin" && flags.scope !== "public") {
+    fail("argv", { reason: `invalid --scope "${flags.scope}" (admin|public)` });
+  }
+  return { archive, flags };
+}
+function camelCase(s) {
+  return s.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+}
+
+// ---------------------------------------------------------------------------
+// 4. Archive resolution. WhatsApp ships zip-or-dir-or-_chat.txt; other
+//    sources pass a single file path that the normaliser interprets directly.
+// ---------------------------------------------------------------------------
+function resolveSourceFile(archivePath, source) {
+  const abs = resolve(archivePath);
+  if (!existsSync(abs)) fail("argv", { reason: `archive path not found: ${abs}` });
+  const st = statSync(abs);
+
+  if (source === "whatsapp") {
+    if (st.isFile() && abs.endsWith(".zip")) {
+      const tmp = mkdtempSync(join(tmpdir(), "conversation-archive-"));
+      const unzip = spawnSync("unzip", ["-q", "-o", abs, "-d", tmp], { encoding: "utf8" });
+      if (unzip.status !== 0) {
+        rmSync(tmp, { recursive: true });
+        fail("argv", {
+          reason: "unzip failed",
+          archive: abs,
+          stderr: (unzip.stderr || "").slice(0, 200),
+        });
+      }
+      const chat = findChatTxt(tmp);
+      if (!chat) {
+        rmSync(tmp, { recursive: true });
+        fail("argv", { reason: "_chat.txt not found in zip", archive: abs });
+      }
+      return { sourceFile: chat, cleanup: () => rmSync(tmp, { recursive: true }) };
+    }
+    if (st.isDirectory()) {
+      const chat = findChatTxt(abs);
+      if (!chat) fail("argv", { reason: "_chat.txt not found in directory", archive: abs });
+      return { sourceFile: chat, cleanup: () => {} };
+    }
+  }
+
+  if (st.isFile()) {
+    return { sourceFile: abs, cleanup: () => {} };
+  }
+  fail("argv", { reason: `unsupported archive shape for source=${source}: ${abs}` });
+  return { sourceFile: abs, cleanup: () => {} };
+}
+function findChatTxt(dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isFile() && e.name === "_chat.txt") return join(dir, e.name);
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      const nested = findChatTxt(join(dir, e.name));
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// 5. Account resolution (Phase 0 = single account)
+// ---------------------------------------------------------------------------
+function resolveAccountId(flags) {
+  if (flags.accountId && flags.accountId.trim()) return flags.accountId.trim();
+  const installDir = resolve(platformRoot, "..");
+  const accountsDir = join(installDir, "data", "accounts");
+  if (!existsSync(accountsDir)) {
+    fail("argv", { reason: `accounts dir not found: ${accountsDir}; pass --account-id explicitly` });
+  }
+  const dirs = readdirSync(accountsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => d.name);
+  if (dirs.length === 0) fail("argv", { reason: `no accounts found under ${accountsDir}` });
+  if (dirs.length > 1) {
+    fail("argv", {
+      reason: `multiple accounts under ${accountsDir} (${dirs.join(",")}); pass --account-id explicitly`,
+    });
+  }
+  return dirs[0];
+}
+
+// ---------------------------------------------------------------------------
+// 6. Main
+// ---------------------------------------------------------------------------
+async function main() {
+  const startedMs = Date.now();
+  const { archive, flags } = parseArgv(process.argv);
+  const source = flags.source;
+  const ownerElementId = flags.ownerElementId;
+  const participantElementIds = flags.participantPersonIds
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (participantElementIds.length === 0) {
+    fail("argv", { reason: "--participant-person-ids must list at least one elementId" });
+  }
+  const scope = flags.scope;
+  const accountId = resolveAccountId(flags);
+  const timezone = flags.timezone || "Europe/London";
+  const dateFormat = flags.dateFormat;
+  const sessionGapHours = flags.sessionGapHours
+    ? parseFloat(flags.sessionGapHours)
+    : 12;
+  if (!Number.isFinite(sessionGapHours) || sessionGapHours <= 0) {
+    fail("argv", { reason: `invalid --session-gap-hours "${flags.sessionGapHours}" (must be positive number)` });
+  }
+  const sessionId =
+    flags.sessionId ||
+    `conversation-archive:${source}:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`;
+
+  // Imports — fail loudly if any compiled dist missing
+  let getNormaliser;
+  let sessionize, toTurnText, findDeltaCursor;
+  let normaliseSenderName, deriveConversationIdentity, deriveMessageContentHash;
+  let bindCanonicalSenders;
+  let getSession, classifyDocument, memoryIngest;
+  try {
+    ({ getNormaliser } = await import(NORMALISERS_PATH));
+    ({ sessionize } = await import(join(PIPELINE_PATH, "sessionize.js")));
+    ({ toTurnText } = await import(join(PIPELINE_PATH, "to-turn-text.js")));
+    ({ findDeltaCursor } = await import(join(PIPELINE_PATH, "delta-cursor.js")));
+    ({ normaliseSenderName, deriveConversationIdentity, deriveMessageContentHash } =
+      await import(join(PIPELINE_PATH, "derive-keys.js")));
+    ({ bindCanonicalSenders } = await import(join(PIPELINE_PATH, "sender-bind.js")));
+    ({ getSession } = await import(NEO4J_LIB_PATH));
+    ({ classifyDocument } = await import(LLM_CLASSIFIER_PATH));
+    ({ memoryIngest } = await import(MEMORY_INGEST_PATH));
+  } catch (err) {
+    fail("import", {
+      reason: "failed to import compiled dist",
+      detail: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // 6a. Resolve source file
+  const { sourceFile, cleanup } = resolveSourceFile(archive, source);
+
+  // 6b. Run the source-specific normaliser
+  let normaliserResult;
+  try {
+    const normaliser = getNormaliser(source);
+    normaliserResult = await normaliser({
+      filePath: sourceFile,
+      accountId,
+      timezone,
+      opts: dateFormat ? { dateFormat } : undefined,
+    });
+  } catch (err) {
+    cleanup();
+    fail("parse", { reason: err instanceof Error ? err.message : String(err) });
+  }
+  const allLines = normaliserResult.parsedLines;
+  const archiveSha256 = normaliserResult.archiveSha256;
+  const archiveSourceFile = normaliserResult.archiveSourceFile;
+  log(
+    `source=${source} file=${archiveSourceFile} owner=${ownerElementId} participants=${participantElementIds.length} scope=${scope} accountId=${accountId} archiveSha256=${archiveSha256.slice(0, 12)} session-gap-hours=${sessionGapHours}`,
+  );
+  log(
+    `parsed lines=${normaliserResult.counters.parsed} media-skipped=${normaliserResult.counters.mediaSkipped} system-skipped=${normaliserResult.counters.systemSkipped}`,
+  );
+  if (allLines.length === 0) {
+    cleanup();
+    fail("parse", { reason: "zero parsed lines after walking archive" });
+  }
+
+  // 6c. Bind canonical senders against the confirmed set
+  const distinctSenderNames = Array.from(new Set(allLines.map((l) => l.senderName)));
+  const senderHistogram = computeSenderHistogram(allLines);
+  let session = getSession();
+  try {
+    await bindCanonicalSenders({
+      session,
+      accountId,
+      ownerElementId,
+      participantElementIds,
+      senderNames: distinctSenderNames,
+    });
+  } catch (err) {
+    await session.close().catch(() => {});
+    cleanup();
+    if (err && err.userFacing) {
+      process.stderr.write(`[conversation-archive] FAIL ${err.message}\n`);
+      process.exit(1);
+    }
+    fail("argv", { reason: err instanceof Error ? err.message : String(err) });
+  }
+
+  // 6d. Derive conversationIdentity and look up prior :ConversationArchive
+  const conversationIdentity = deriveConversationIdentity({
+    accountId,
+    participantElementIds: [ownerElementId, ...participantElementIds],
+  });
+  let priorArchive = null;
+  try {
+    const r = await session.run(
+      `MATCH (a:ConversationArchive { conversationIdentity: $cid })
+       RETURN elementId(a) AS elemId,
+              a.lastIngestedMessageHash AS lastHash,
+              a.lastIngestedMessageAt   AS lastAt LIMIT 1`,
+      { cid: conversationIdentity },
+    );
+    if (r.records[0]) {
+      priorArchive = {
+        elemId: r.records[0].get("elemId"),
+        lastHash: r.records[0].get("lastHash"),
+        lastAt: r.records[0].get("lastAt"),
+      };
+    }
+  } catch (err) {
+    await session.close().catch(() => {});
+    cleanup();
+    fail("delta-cursor-missing", { reason: `conversationArchive lookup failed: ${err instanceof Error ? err.message : String(err)}` });
+  }
+  await session.close().catch(() => {});
+
+  // 6e. Compute deltaStart
+  let deltaStart = 0;
+  let deltaKind = "first-ingest";
+  if (priorArchive && priorArchive.lastHash) {
+    const cursor = findDeltaCursor(allLines, priorArchive.lastHash);
+    if (cursor.kind === "missing") {
+      cleanup();
+      fail("delta-cursor-missing", {
+        reason: `prior cursor not found in re-export (operator deleted prior messages, or this is a different chat archive)`,
+        priorArchive: priorArchive.elemId,
+        lastIngestedMessageAt: priorArchive.lastAt,
+      });
+    }
+    if (cursor.kind === "empty") {
+      log(`noop reason="no new messages since ${priorArchive.lastAt}"`);
+      cleanup();
+      const totalMs = Date.now() - startedMs;
+      process.stdout.write(JSON.stringify({
+        archiveElementId: priorArchive.elemId,
+        conversationIdentity,
+        archiveSha256,
+        archiveSourceFile,
+        source,
+        parsed: normaliserResult.counters.parsed,
+        mediaSkipped: normaliserResult.counters.mediaSkipped,
+        systemSkipped: normaliserResult.counters.systemSkipped,
+        delta: { kind: "empty-delta", deltaStart: allLines.length, deltaMessages: 0 },
+        sessions: 0,
+        chunks: 0,
+        nextEdgesCreated: 0,
+        participantsLinked: 0,
+        dateRange: { first: allLines[0].dateSent, last: allLines[allLines.length - 1].dateSent },
+        senderHistogram,
+        topicKeywords: [],
+        ms: totalMs,
+        priorLastIngestedMessageAt: priorArchive.lastAt,
+      }) + "\n");
+      process.exit(0);
+    }
+    deltaStart = cursor.deltaStart;
+    deltaKind = "delta";
+  }
+  const deltaLines = allLines.slice(deltaStart);
+  log(
+    `delta cursor=${priorArchive ? priorArchive.lastHash.slice(0, 12) : "(first-ingest)"} cursor-line=${deltaStart} delta-messages=${deltaLines.length}`,
+  );
+
+  // 6f. Sessionize delta
+  const sessions = sessionize(deltaLines, sessionGapHours);
+  log(
+    `sessionize source=${source} archiveSha256=${archiveSha256.slice(0, 12)} messages=${deltaLines.length} sessions=${sessions.length} gap-hours=${sessionGapHours}`,
+  );
+
+  // 6g. Classify each session via Haiku (mode='chat')
+  const allChunks = [];
+  const allKeywords = new Set();
+  for (const s of sessions) {
+    const sessionStart = Date.now();
+    const text = toTurnText(s);
+    const result = await classifyDocument({
+      accountId,
+      mode: "chat",
+      anchorDescription: `Conversation transcript (${[ownerElementId, ...participantElementIds].length} participants, session ${s.index + 1} of ${sessions.length})`,
+      ontologyLabels: new Set([]),
+      naturalEdgeMap: "",
+      documentText: text,
+    });
+    if (result.kind === "fallback") {
+      cleanup();
+      fail("classify", { reason: `Haiku fallback on session ${s.index}: ${result.reason}` });
+    }
+    const chunkCount = result.output.sections.length;
+    log(
+      `classify-session sessionIndex=${s.index + 1}/${sessions.length} messages=${s.messages.length} chars=${text.length} chunks=${chunkCount} ms=${Date.now() - sessionStart}`,
+    );
+    if (chunkCount === 0 && s.messages.length > 0) {
+      cleanup();
+      fail("classify", {
+        reason: `session ${s.index} of ${s.messages.length} messages produced zero chunks (classifier-prompt regression)`,
+      });
+    }
+    for (const sec of result.output.sections) allChunks.push(sec);
+    for (const kw of result.output.documentKeywords) allKeywords.add(kw);
+  }
+
+  // 6h. Compute lastIngestedMessageHash from the last delta line
+  const lastLine = deltaLines[deltaLines.length - 1];
+  const lastIngestedMessageHash = deriveMessageContentHash({
+    dateSent: lastLine.dateSent,
+    senderName: lastLine.senderName,
+    body: lastLine.body,
+  });
+  const lastIngestedMessageAt = lastLine.dateSent;
+
+  // 6i. Aggregate document-level summary across sessions
+  const documentSummary = sessions.length === 1
+    ? `${deltaLines.length} messages in 1 session, ${allChunks.length} chunks.`
+    : `${deltaLines.length} messages in ${sessions.length} sessions, ${allChunks.length} chunks.`;
+
+  // 6j. Call memoryIngest with parentLabel='ConversationArchive'
+  let ingestResult;
+  const ingestStart = Date.now();
+  try {
+    ingestResult = await memoryIngest({
+      accountId,
+      attachmentId: conversationIdentity,
+      parentLabel: "ConversationArchive",
+      source,
+      documentSummary,
+      anchorNodeId: ownerElementId,
+      anchorLabel: "AdminUser",
+      sections: allChunks,
+      scope,
+      sessionId,
+      documentKeywords: Array.from(allKeywords),
+      archiveSha256,
+      archiveSourceFile,
+      lastIngestedMessageHash,
+      lastIngestedMessageAt,
+      participantElementIds: [ownerElementId, ...participantElementIds],
+    });
+  } catch (err) {
+    cleanup();
+    fail("memory-ingest", { reason: err instanceof Error ? err.message : String(err) });
+  }
+  log(
+    `source=${source} file=${archiveSourceFile} conversationIdentity=${conversationIdentity.slice(0, 12)} archiveElementId=${ingestResult.documentNodeId} chunks-written=${ingestResult.sectionCount} next-edges=${ingestResult.edgeBreakdown.NEXT ?? 0} participants=${ingestResult.edgeBreakdown.PARTICIPANT_IN ?? 0} ms=${Date.now() - ingestStart}`,
+  );
+
+  cleanup();
+  const totalMs = Date.now() - startedMs;
+  log(`done source=${source} conversationIdentity=${conversationIdentity.slice(0, 12)} total-ms=${totalMs} exit=0`);
+
+  process.stdout.write(JSON.stringify({
+    archiveElementId: ingestResult.documentNodeId,
+    conversationIdentity,
+    archiveSha256,
+    archiveSourceFile,
+    source,
+    parsed: normaliserResult.counters.parsed,
+    mediaSkipped: normaliserResult.counters.mediaSkipped,
+    systemSkipped: normaliserResult.counters.systemSkipped,
+    delta: { kind: deltaKind, deltaStart, deltaMessages: deltaLines.length },
+    sessions: sessions.length,
+    chunks: ingestResult.sectionCount,
+    nextEdgesCreated: ingestResult.edgeBreakdown.NEXT ?? 0,
+    participantsLinked: ingestResult.edgeBreakdown.PARTICIPANT_IN ?? 0,
+    dateRange: { first: allLines[0].dateSent, last: allLines[allLines.length - 1].dateSent },
+    senderHistogram,
+    topicKeywords: Array.from(allKeywords),
+    ms: totalMs,
+  }) + "\n");
+  process.exit(0);
+}
+
+function computeSenderHistogram(lines) {
+  const counts = new Map();
+  for (const l of lines) {
+    counts.set(l.senderName, (counts.get(l.senderName) ?? 0) + 1);
+  }
+  return Array.from(counts.entries())
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+main().catch((err) => {
+  fail("uncaught", { reason: err instanceof Error ? err.message : String(err) });
+});

package/payload/platform/plugins/memory/bin/conversation-archive-ingest.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# =============================================================================
+# conversation-archive-ingest.sh — single deterministic Bash entry for
+# conversation-archive ingestion (Task 894 — supersedes whatsapp-ingest.sh).
+#
+# Source-agnostic: WhatsApp `_chat.txt`, Telegram, Signal, LinkedIn DMs, Zoom
+# transcript, meeting minutes, iMessage, Slack — every source flows through
+# the same pipeline with `--source` selecting the normaliser.
+#
+# Pipeline: normalise (per source) → bind canonical sender set →
+# derive conversationIdentity → look up prior :ConversationArchive (delta
+# cursor) → sessionize delta at gap-hours boundary → classify each session
+# via Haiku (mode='chat') → memory-ingest with parentLabel='ConversationArchive'.
+#
+# Usage:
+#   bash conversation-archive-ingest.sh <archive-path>
+#         --source <whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|other>
+#         --owner-element-id <id>
+#         --participant-person-ids <csv>
+#         --scope <admin|public>
+#         [--session-gap-hours <N>]    (default 12)
+#         [--account-id <accountId>]
+#         [--timezone <iana-zone>]
+#         [--date-format <DD/MM/YY|MM/DD/YY|DD/MM/YYYY|MM/DD/YYYY>]   (whatsapp only)
+#
+# `--owner-element-id` + `--participant-person-ids` form the closed sender
+# set; any parsed senderName outside that set LOUD-FAILs with `parser-miss`
+# and exits non-zero.
+#
+# Exit 0  + JSON summary on stdout on success.
+# Exit !0 + one [conversation-archive] FAIL line on stderr on failure.
+# =============================================================================
+
+set -euo pipefail
+
+arg_fail() {
+  local reason="$1"
+  echo "[conversation-archive] FAIL phase=argv reason=\"${reason}\"" >&2
+  exit 1
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLATFORM_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+INGEST_MJS="$SCRIPT_DIR/conversation-archive-ingest.mjs"
+
+if [ ! -f "$INGEST_MJS" ]; then
+  arg_fail "conversation-archive-ingest.mjs not found at $INGEST_MJS — run from a built install"
+fi
+
+ARCHIVE=""
+HAS_SOURCE=0
+SOURCE_VAL=""
+HAS_OWNER=0
+OWNER_VAL=""
+HAS_PARTICIPANTS=0
+PARTICIPANTS_VAL=""
+HAS_SCOPE=0
+SCOPE_VAL=""
+
+ARGS=("$@")
+i=0
+while [ $i -lt ${#ARGS[@]} ]; do
+  a="${ARGS[$i]}"
+  case "$a" in
+    --source)                  HAS_SOURCE=1;       SOURCE_VAL="${ARGS[$((i + 1))]:-}";       i=$((i + 2)); continue ;;
+    --owner-element-id)        HAS_OWNER=1;        OWNER_VAL="${ARGS[$((i + 1))]:-}";        i=$((i + 2)); continue ;;
+    --participant-person-ids)  HAS_PARTICIPANTS=1; PARTICIPANTS_VAL="${ARGS[$((i + 1))]:-}"; i=$((i + 2)); continue ;;
+    --scope)                   HAS_SCOPE=1;        SCOPE_VAL="${ARGS[$((i + 1))]:-}";        i=$((i + 2)); continue ;;
+    --session-gap-hours|--account-id|--timezone|--date-format|--session-id) i=$((i + 2)); continue ;;
+    --*)                       i=$((i + 2)); continue ;;
+    *)
+      if [ -z "$ARCHIVE" ]; then ARCHIVE="$a"; fi
+      i=$((i + 1))
+      continue
+      ;;
+  esac
+done
+
+[ -n "$ARCHIVE" ]                                                || arg_fail "missing positional <archive>"
+[ "$HAS_SOURCE"       -eq 1 ] && [ -n "$SOURCE_VAL"       ]      || arg_fail "missing --source (whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|other)"
+[ "$HAS_OWNER"        -eq 1 ] && [ -n "$OWNER_VAL"        ]      || arg_fail "missing --owner-element-id (or empty value)"
+[ "$HAS_PARTICIPANTS" -eq 1 ] && [ -n "$PARTICIPANTS_VAL" ]      || arg_fail "missing --participant-person-ids (csv of operator-confirmed :Person/:AdminUser elementIds, owner excluded)"
+[ "$HAS_SCOPE"        -eq 1 ] && [ -n "$SCOPE_VAL"        ]      || arg_fail "missing --scope (or empty value)"
+case "$SCOPE_VAL" in
+  admin|public) : ;;
+  *) arg_fail "invalid --scope \"$SCOPE_VAL\" (admin|public)" ;;
+esac
+
+if [ -z "${NEO4J_PASSWORD:-}" ]; then
+  NEO4J_PASSWORD_FILE="$PLATFORM_ROOT/config/.neo4j-password"
+  if [ -f "$NEO4J_PASSWORD_FILE" ]; then
+    NEO4J_PASSWORD="$(cat "$NEO4J_PASSWORD_FILE")"
+    export NEO4J_PASSWORD
+  else
+    arg_fail "NEO4J_PASSWORD not in env and $NEO4J_PASSWORD_FILE not found"
+  fi
+fi
+
+if [ -z "${NEO4J_URI:-}" ]; then
+  arg_fail "NEO4J_URI not set (no default — set in env)"
+fi
+
+export NEO4J_USER="${NEO4J_USER:-neo4j}"
+export MAXY_PLATFORM_ROOT="$PLATFORM_ROOT"
+
+exec node "$INGEST_MJS" "$@"