@h-rig/server 0.0.6-alpha.0

package/dist/src/inspector/types.js

@@ -0,0 +1 @@
+// @bun

package/dist/src/inspector/upstream-sync.js

@@ -0,0 +1,479 @@
+// @bun
+// packages/server/src/inspector/upstream-sync.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+import { resolveMonorepoRoot as resolveMonorepoRoot2 } from "@rig/runtime/control-plane/native/utils";
+
+// packages/server/src/bootstrap.ts
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { RIG_DEFINITION_DIRNAME, resolveMonorepoRoot } from "@rig/runtime";
+function normalizeOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function resolveRigServerPaths(projectRoot) {
+  const taskWorkspace = normalizeOptionalString(process.env.RIG_TASK_WORKSPACE);
+  const explicitStateDir = normalizeOptionalString(process.env.RIG_STATE_DIR);
+  const explicitLogsDir = normalizeOptionalString(process.env.RIG_LOGS_DIR);
+  const explicitSessionFile = normalizeOptionalString(process.env.RIG_SESSION_FILE);
+  const hostStateRoot = resolve(projectRoot, ".rig");
+  const monorepoRoot = resolveMonorepoRoot(projectRoot);
+  const monorepoStateRoot = resolve(monorepoRoot, ".rig");
+  const stateRoot = taskWorkspace ? resolve(taskWorkspace, ".rig") : explicitStateDir ? dirname(resolve(explicitStateDir)) : explicitLogsDir ? dirname(resolve(explicitLogsDir)) : explicitSessionFile ? dirname(dirname(resolve(explicitSessionFile))) : existsSync(hostStateRoot) ? hostStateRoot : monorepoStateRoot;
+  const stateDir = explicitStateDir ? resolve(explicitStateDir) : resolve(stateRoot, "state");
+  const logsDir = explicitLogsDir ? resolve(explicitLogsDir) : resolve(stateRoot, "logs");
+  const taskConfigPath = taskWorkspace ? resolve(taskWorkspace, ".rig", "task-config.json") : existsSync(resolve(projectRoot, ".rig", "task-config.json")) ? resolve(projectRoot, ".rig", "task-config.json") : resolve(monorepoStateRoot, "task-config.json");
+  return {
+    stateRoot,
+    stateDir,
+    logsDir,
+    controlPlaneEventsFile: resolve(logsDir, "control-plane.events.jsonl"),
+    taskConfigPath,
+    notificationsFile: resolve(projectRoot, "rig", "notifications", "targets.json"),
+    keybindingsPath: resolve(projectRoot, "rig", "keybindings.json")
+  };
+}
+
+// packages/server/src/inspector/upstream-sync.ts
+var UPSTREAM_VALIDATION_DESCRIPTIONS = {
+  "integration:hg-auth-backport": "Preserves the upstream auth hardening cluster: nonce-backed node-client login, signature-aware JWT verification, shared-token onboarding semantics, and regression coverage.",
+  "integration:hg-core-security-backport": "Preserves the vendored core-app and backend security fixes for OTP validation, NoSQL/operator hardening, AES/encryption behavior, and rate-limit or redirect-state protections.",
+  "integration:hg-boundary-hardening": "Preserves boundary-safe CORS behavior and credential lookup error hygiene across the vendored backend and the extracted credentials-service analogue.",
+  "integration:hg-uudl-runtime": "Preserves the upstream uudl runtime/package fixes: production dependency placement, path-resolution/runtime bootstrap behavior, AWS/MSK environment detection, KMS coverage, and a compiling UUDL tree.",
+  "boundary:hg-auth-triage": "Requires a durable keep/adapt/reject triage record for the post-import auth policy and mobile-wallet SIWE commits so the watcher does not keep rediscovering the same ambiguity.",
+  "boundary:hg-upstream-triage": "Requires a durable keep/adapt/reject triage record for service-relevant upstream commits that do not match the current portable catalog, including commit hashes, touched paths, and follow-up routing decisions."
+};
+var CLUSTERS = {
+  "auth-hardening": {
+    classification: "portable-now",
+    title: "[HG-001] Preserve upstream auth and shared-token hardening across extracted auth work",
+    description: "Backport clearly portable auth changes introduced upstream after imported revision 58b56e15: 3196d5c (node-client login nonce), bb5b74f (JWT signature validation), and 92011ead (shared token verification for wallet signup onboarding). Apply them where they belong in this repo: hp-auth-service, hp-gateway if verification semantics surface there, and the upstream monorepo auth owner flows for the remaining wallet-login/shared-token work. This task must preserve the security behavior, not just copy code. It should explicitly reconcile with bd-k0y-10, bd-k0y-11, bd-k0y-12, and bd-k0y-13.",
+    acceptanceCriteria: "Map upstream commits 3196d5c, bb5b74f, and 92011ead to exact local targets; preserve nonce-backed node-client login, JWT signature validation, and shared-token verification behavior; add automated tests that fail without the hardening; document any deliberate non-ports.",
+    role: "extractor",
+    scope: [
+      "repos/spliter-monorepo/microservices/hp-auth-service/**",
+      "repos/spliter-monorepo/microservices/hp-gateway/**",
+      "repos/spliter-monorepo/humoongate/moongate/core-app/**"
+    ],
+    validation: ["integration:hg-auth-backport", "boundary:changed-files"],
+    validationDescriptions: {
+      "integration:hg-auth-backport": UPSTREAM_VALIDATION_DESCRIPTIONS["integration:hg-auth-backport"]
+    },
+    labels: ["upstream:monorepo", "kind:backport", "cluster:auth"]
+  },
+  "core-security": {
+    classification: "portable-now",
+    title: "[HG-002] Backport core-app and backend security fixes from post-import upstream",
+    description: "Backport the clearly portable security fixes from efdae709 (OTP validation bypass), f63830d (NoSQL operator injection hardening), d7f6919 (AES encryption), and af86ac16 (three critical/high vulnerabilities). Preserve the behavior in the vendored auth owner and the touched backend query surfaces instead of treating these as optional cleanups. The high-value touched files from af86ac16 must be reviewed and ported or consciously waived with rationale.",
+    acceptanceCriteria: "Review and port the exact security behaviors from efdae709, f63830d, d7f6919, and af86ac16; cover the listed core-app and backend touched files; add regression tests for OTP bypass, NoSQL operator injection, AES/encryption behavior, and rate-limit or redirect-state hardening; document any consciously waived upstream changes.",
+    role: "mechanic",
+    scope: [
+      "repos/spliter-monorepo/humoongate/moongate/core-app/**",
+      "repos/spliter-monorepo/humoongate/humanity/hp-backend-ts/**"
+    ],
+    validation: ["integration:hg-core-security-backport", "boundary:changed-files"],
+    validationDescriptions: {
+      "integration:hg-core-security-backport": UPSTREAM_VALIDATION_DESCRIPTIONS["integration:hg-core-security-backport"]
+    },
+    labels: ["upstream:monorepo", "kind:backport", "cluster:security"]
+  },
+  "boundary-hardening": {
+    classification: "portable-now",
+    title: "[HG-003] Backport request-boundary hardening for CORS and credential lookup flows",
+    description: "Backport the clearly portable boundary hardening from 083bbe4 (CORS config) and 36d52fba (credential lookup error hygiene). Preserve request-boundary behavior in the vendored backend and any analogous extracted credential-facing service seams so attackers cannot learn internals from credential lookup failures or exploit inconsistent CORS policy.",
+    acceptanceCriteria: "Port the exact request-boundary behavior from 083bbe4 and 36d52fba; preserve safe CORS policy and credential lookup error hygiene; add tests showing callers do not receive overly detailed credential lookup failures; document any extracted-service analogue that must mirror the behavior.",
+    role: "mechanic",
+    scope: [
+      "repos/spliter-monorepo/humoongate/humanity/hp-backend-ts/**",
+      "repos/spliter-monorepo/microservices/hp-credentials-service/**"
+    ],
+    validation: ["integration:hg-boundary-hardening", "boundary:changed-files"],
+    validationDescriptions: {
+      "integration:hg-boundary-hardening": UPSTREAM_VALIDATION_DESCRIPTIONS["integration:hg-boundary-hardening"]
+    },
+    labels: ["upstream:monorepo", "kind:backport", "cluster:boundary"]
+  },
+  "uudl-runtime": {
+    classification: "portable-now",
+    title: "[HG-004] Backport uudl runtime and packaging fixes from upstream",
+    description: "Backport the clearly portable uudl runtime fixes from 2141b4c, 1fa56d7, a9a0a99, 9fcfa6e, and ea5cb03. Preserve the runtime behavior rather than cherry-picking filenames: production dependency placement, tsconfig-paths resolution, aggregator cycle removal, AWS/MSK environment detection, and local KMS wiring all need to be reflected in whichever UUDL runtime this repo still owns.",
+    acceptanceCriteria: "Port the runtime behaviors from 2141b4c, 1fa56d7, a9a0a99, 9fcfa6e, and ea5cb03; preserve production dependency placement, tsconfig-paths runtime resolution, aggregator cycle removal, AWS/MSK environment detection, and local KMS configuration; add runtime-focused tests or smoke coverage for each preserved behavior.",
+    role: "extractor",
+    scope: ["repos/spliter-monorepo/humoongate/humanity/hp-uudl/**"],
+    validation: ["integration:hg-uudl-runtime", "boundary:changed-files"],
+    validationDescriptions: {
+      "integration:hg-uudl-runtime": UPSTREAM_VALIDATION_DESCRIPTIONS["integration:hg-uudl-runtime"]
+    },
+    labels: ["upstream:monorepo", "kind:backport", "cluster:uudl"]
+  },
+  "auth-triage": {
+    classification: "needs-human-triage",
+    title: "[HG-005] Triage post-import auth policy deltas and mobile-wallet SIWE changes",
+    description: "Review the upstream changes that are relevant but not safely auto-portable: 1262b75 (JWT_EXPIRES_IN 1d -> 7d), 15036424 (unlink-wallet endpoint and Wallet.default fix), and d4a47015 (unlink-wallet error handling). Produce an explicit keep/adapt/reject decision for each commit with rationale tied to the extracted auth plan, core-app ownership, and current threat model, and record the result in artifacts/bd-2ztk.5/decision-log.md so future agents do not silently re-litigate these decisions.",
+    acceptanceCriteria: "For 1262b75, 15036424, and d4a47015, produce explicit keep/adapt/reject decisions with rationale tied to auth ownership and threat model; record the decision in artifacts/bd-2ztk.5/decision-log.md; identify any follow-on implementation tasks if the answer is keep or adapt.",
+    role: "architect",
+    scope: ["artifacts/bd-2ztk.5/**", "docs/research/**"],
+    validation: ["boundary:hg-auth-triage"],
+    validationDescriptions: {
+      "boundary:hg-auth-triage": UPSTREAM_VALIDATION_DESCRIPTIONS["boundary:hg-auth-triage"]
+    },
+    labels: ["upstream:monorepo", "kind:backport", "cluster:triage"]
+  },
+  "generic-triage": {
+    classification: "needs-human-triage",
+    title: "[HG-007] Triage uncatalogued service-relevant upstream commits",
+    description: "Review future upstream commits that touch service-relevant paths but do not match the current portable-now catalog. For each commit or batch, produce keep/adapt/reject decisions with rationale, cite the touched paths and why they matter here, and either route them into an existing backport task or open a new follow-up task when they are worth preserving.",
+    acceptanceCriteria: "For each uncatalogued service-relevant upstream commit or batch, record keep/adapt/reject decisions with rationale in artifacts/bd-2ztk.7/decision-log.md; cite the commit hashes and touched paths; and either attach the work to an existing backport task or open a new follow-up task when preservation is warranted.",
+    role: "architect",
+    scope: ["artifacts/bd-2ztk.7/**", "docs/research/**"],
+    validation: ["boundary:hg-upstream-triage"],
+    validationDescriptions: {
+      "boundary:hg-upstream-triage": UPSTREAM_VALIDATION_DESCRIPTIONS["boundary:hg-upstream-triage"]
+    },
+    labels: ["upstream:monorepo", "kind:backport", "cluster:triage"]
+  }
+};
+var RELEVANT_PREFIXES = [
+  "humanity/hp-backend-ts/",
+  "humanity/hp-dev-api/",
+  "humanity/hp-uudl/",
+  "moongate/core-app/",
+  "moongate/models/",
+  "packages/",
+  "shared-migrations/"
+];
+var IGNORE_PATTERNS = [
+  /hp-next|dashboard|frontend/i,
+  /CODEOWNERS|CodeRabbit|security-workflow|workflow housekeeping/i,
+  /npm registry|workspace packages to npm/i,
+  /bulk event|organizer/i
+];
+function parseImportedUpstreamRevision(doc, upstreamName = "upstream") {
+  const sectionPattern = new RegExp(`##\\s+${upstreamName}\\b([\\s\\S]*?)(?:\\n##\\s+|$)`, "i");
+  const sectionMatch = doc.match(sectionPattern);
+  if (!sectionMatch) {
+    return null;
+  }
+  const revisionMatch = sectionMatch[1]?.match(/Imported revision:\s*`([0-9a-f]{40})`/i);
+  return revisionMatch?.[1] ?? null;
+}
+function normalizeGitResult(result) {
+  return {
+    exitCode: result.status ?? 1,
+    stdout: typeof result.stdout === "string" ? result.stdout : result.stdout?.toString("utf8") ?? "",
+    stderr: typeof result.stderr === "string" ? result.stderr : result.stderr?.toString("utf8") ?? ""
+  };
+}
+function defaultGitRunner(repoRoot, args) {
+  return normalizeGitResult(spawnSync("git", ["-C", repoRoot, ...args], {
+    encoding: "utf8"
+  }));
+}
+function upstreamStatePath(projectRoot, override) {
+  if (override) {
+    return resolve2(override);
+  }
+  return resolve2(resolveRigServerPaths(projectRoot).stateDir, "inspector", "upstream-sync.json");
+}
+function readUpstreamState(projectRoot, statePath) {
+  const path = upstreamStatePath(projectRoot, statePath);
+  if (!existsSync2(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeUpstreamState(projectRoot, state, statePath) {
+  const path = upstreamStatePath(projectRoot, statePath);
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+}
+function readImportedRevision(projectRoot, upstreamsDocPath) {
+  const monorepoRoot = resolveMonorepoRoot2(projectRoot);
+  const docPath = upstreamsDocPath ? resolve2(upstreamsDocPath) : resolve2(monorepoRoot, "docs", "UPSTREAMS.md");
+  if (!existsSync2(docPath)) {
+    throw new Error(`UPSTREAMS.md not found at ${docPath}`);
+  }
+  const docContent = readFileSync(docPath, "utf-8");
+  const revision = parseImportedUpstreamRevision(docContent, "upstream") ?? parseImportedUpstreamRevision(docContent, "humoongate");
+  if (!revision) {
+    throw new Error(`Failed to parse upstream imported revision from ${docPath}`);
+  }
+  return revision;
+}
+function resolveRemoteBranch(repoRoot, remote, gitRunner) {
+  const symbolic = gitRunner(repoRoot, ["symbolic-ref", `refs/remotes/${remote}/HEAD`]);
+  const symbolicRef = symbolic.stdout.trim();
+  if (symbolic.exitCode === 0 && symbolicRef.length > 0) {
+    return symbolicRef.replace(/^refs\/remotes\//, "");
+  }
+  for (const fallback of [`${remote}/main`, `${remote}/master`]) {
+    const showRef = gitRunner(repoRoot, ["show-ref", "--verify", `refs/remotes/${fallback}`]);
+    if (showRef.exitCode === 0) {
+      return fallback;
+    }
+  }
+  return null;
+}
+function isGitCheckout(path, gitRunner) {
+  if (!existsSync2(resolve2(path, ".git"))) {
+    return false;
+  }
+  const result = gitRunner(path, ["rev-parse", "--is-inside-work-tree"]);
+  return result.exitCode === 0 && result.stdout.trim() === "true";
+}
+function resolveUpstreamCheckout(projectRoot, explicitCheckout, gitRunner) {
+  const monorepoRoot = resolveMonorepoRoot2(projectRoot);
+  const candidates = [
+    explicitCheckout ? resolve2(explicitCheckout) : "",
+    process.env.UPSTREAM_CHECKOUT?.trim() ? resolve2(process.env.UPSTREAM_CHECKOUT.trim()) : "",
+    process.env.HUMOONGATE_UPSTREAM_CHECKOUT?.trim() ? resolve2(process.env.HUMOONGATE_UPSTREAM_CHECKOUT.trim()) : "",
+    resolve2(projectRoot, "..", "humoongate"),
+    resolve2(monorepoRoot, "..", "humoongate"),
+    resolve2(monorepoRoot, "humoongate")
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    if (isGitCheckout(candidate, gitRunner)) {
+      return candidate;
+    }
+  }
+  throw new Error(`Unable to locate an authoritative upstream checkout. Checked: ${candidates.join(", ")}`);
+}
+function parseCommitLog(output) {
+  const commits = [];
+  let current = null;
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "__COMMIT__") {
+      if (current) {
+        commits.push(current);
+      }
+      current = null;
+      continue;
+    }
+    if (!line) {
+      continue;
+    }
+    if (!current) {
+      const [sha, date, ...rest] = line.split("\t");
+      if (!sha || !date) {
+        continue;
+      }
+      current = {
+        sha,
+        date,
+        summary: rest.join("\t").trim(),
+        paths: []
+      };
+      continue;
+    }
+    current.paths.push(line);
+  }
+  if (current) {
+    commits.push(current);
+  }
+  return commits;
+}
+function relevantPaths(paths) {
+  return paths.filter((path) => RELEVANT_PREFIXES.some((prefix) => path.startsWith(prefix)));
+}
+function classifyCommit(commit) {
+  const summary = commit.summary.toLowerCase();
+  const paths = relevantPaths(commit.paths);
+  const pathText = paths.join(" ").toLowerCase();
+  const signature = `${summary}
+${pathText}`;
+  if (IGNORE_PATTERNS.some((pattern) => pattern.test(signature))) {
+    return { classification: "ignore", clusterKey: null };
+  }
+  if (/jwt_expires_in|unlink-wallet|mobile wallet|siwe endpoint/i.test(signature)) {
+    return { classification: "needs-human-triage", clusterKey: "auth-triage" };
+  }
+  if (/node-client login use nonce|jwt signature validation|shared token verification|wallet signup onboarding/i.test(signature)) {
+    return { classification: "portable-now", clusterKey: "auth-hardening" };
+  }
+  if (/otp validation bypass|otp queries|aes encryption|critical\/high vulnerabilities|redirect jwt steal/i.test(signature)) {
+    return { classification: "portable-now", clusterKey: "core-security" };
+  }
+  if (/cors config|credential lookup errors/i.test(signature)) {
+    return { classification: "portable-now", clusterKey: "boundary-hardening" };
+  }
+  if (paths.some((path) => path.startsWith("humanity/hp-uudl/")) && /tsconfig-paths|circular dependency|msk|kms port|runtime|production dependenc/i.test(signature)) {
+    return { classification: "portable-now", clusterKey: "uudl-runtime" };
+  }
+  if (paths.length > 0) {
+    return { classification: "needs-human-triage", clusterKey: "generic-triage" };
+  }
+  return { classification: "ignore", clusterKey: null };
+}
+function scanUpstream(options) {
+  const now = options.now ?? (() => new Date().toISOString());
+  const gitRunner = options.gitRunner ?? defaultGitRunner;
+  const remote = options.remote ?? "origin";
+  const baselineSha = options.baselineSha ?? readImportedRevision(options.projectRoot, options.upstreamsDocPath);
+  const checkoutPath = resolveUpstreamCheckout(options.projectRoot, options.explicitCheckout, gitRunner);
+  if (options.fetch !== false) {
+    const fetchResult = gitRunner(checkoutPath, ["fetch", remote]);
+    if (fetchResult.exitCode !== 0) {
+      throw new Error(`Failed to fetch ${remote} in ${checkoutPath}: ${fetchResult.stderr || fetchResult.stdout}`);
+    }
+  }
+  const branch = options.branch ?? resolveRemoteBranch(checkoutPath, remote, gitRunner);
+  if (!branch) {
+    throw new Error(`Failed to resolve tracked branch for remote ${remote} in ${checkoutPath}`);
+  }
+  const headResult = gitRunner(checkoutPath, ["rev-parse", branch]);
+  if (headResult.exitCode !== 0 || !headResult.stdout.trim()) {
+    throw new Error(`Failed to resolve latest upstream head for ${branch}: ${headResult.stderr || headResult.stdout}`);
+  }
+  const latestHeadSha = headResult.stdout.trim();
+  const state = readUpstreamState(options.projectRoot, options.statePath);
+  let sinceSha = state?.lastProcessedCommit || baselineSha;
+  const ancestorCheck = gitRunner(checkoutPath, ["merge-base", "--is-ancestor", sinceSha, branch]);
+  if (ancestorCheck.exitCode !== 0) {
+    sinceSha = baselineSha;
+  }
+  const logResult = gitRunner(checkoutPath, [
+    "log",
+    "--reverse",
+    "--date=short",
+    "--name-only",
+    "--pretty=format:__COMMIT__%n%H%x09%cs%x09%s",
+    `${sinceSha}..${branch}`
+  ]);
+  if (logResult.exitCode !== 0) {
+    throw new Error(`Failed to collect upstream commits: ${logResult.stderr || logResult.stdout}`);
+  }
+  const commits = parseCommitLog(logResult.stdout);
+  const grouped = new Map;
+  for (const commit of commits) {
+    const classification = classifyCommit(commit);
+    if (!classification.clusterKey) {
+      continue;
+    }
+    const existing = grouped.get(classification.clusterKey) ?? [];
+    existing.push(commit);
+    grouped.set(classification.clusterKey, existing);
+  }
+  const findings = Array.from(grouped.entries()).map(([clusterKey, clusterCommits]) => {
+    const definition = CLUSTERS[clusterKey];
+    const newestCommit = clusterCommits[clusterCommits.length - 1];
+    return {
+      key: `upstream:${definition.classification}:${clusterKey}:${newestCommit.sha}`,
+      summary: definition.title,
+      details: {
+        remote,
+        branch,
+        checkoutPath,
+        baselineSha,
+        sinceSha,
+        latestHeadSha,
+        classification: definition.classification,
+        clusterKey,
+        description: definition.description,
+        acceptanceCriteria: definition.acceptanceCriteria,
+        role: definition.role,
+        scope: definition.scope,
+        validation: definition.validation,
+        validationDescriptions: definition.validationDescriptions,
+        labels: definition.labels,
+        commits: clusterCommits.map((commit) => ({
+          sha: commit.sha,
+          date: commit.date,
+          summary: commit.summary,
+          paths: relevantPaths(commit.paths)
+        }))
+      }
+    };
+  });
+  const groupedCommitCount = Array.from(grouped.values()).reduce((sum, clusterCommits) => sum + clusterCommits.length, 0);
+  return {
+    baselineSha,
+    sinceSha,
+    latestHeadSha,
+    checkoutPath,
+    remote,
+    branch,
+    scannedCommitCount: commits.length,
+    ignoredCommitCount: Math.max(0, commits.length - groupedCommitCount),
+    findings,
+    statePath: upstreamStatePath(options.projectRoot, options.statePath)
+  };
+}
+async function runUpstreamSyncScan(options) {
+  const now = options.now ?? (() => new Date().toISOString());
+  const startedAt = now();
+  let followupCount = 0;
+  const createdTaskIds = [];
+  for (const finding of options.findings) {
+    const existingFollowup = options.journal.getFollowupByDedupeKey(finding.key);
+    if (!existingFollowup) {
+      const result = options.journal.appendFollowup({
+        id: `upstream-followup:${finding.key}`,
+        originRunId: null,
+        dedupeKey: finding.key,
+        taskId: null,
+        kind: "upstream-drift",
+        status: "proposed",
+        summary: finding.summary,
+        details: finding.details ?? null,
+        createdAt: startedAt
+      });
+      if (!result.ok) {
+        throw new Error(`Failed to record upstream follow-up ${finding.key}: ${result.error}`);
+      }
+      if (result.changed) {
+        followupCount += 1;
+      }
+    }
+    const followup = options.journal.getFollowupByDedupeKey(finding.key);
+    if (options.createTask && followup?.taskId == null) {
+      const created = await options.createTask(finding);
+      if (created.taskId) {
+        createdTaskIds.push(created.taskId);
+        const attachment = options.journal.attachFollowupTask({
+          dedupeKey: finding.key,
+          taskId: created.taskId,
+          status: "created",
+          details: finding.details && created.details ? { ...finding.details, followupTask: created.details } : created.details ?? finding.details ?? null
+        });
+        if (!attachment.ok) {
+          throw new Error(`Failed to attach task ${created.taskId} to upstream follow-up ${finding.key}: ${attachment.error}`);
+        }
+      }
+    }
+  }
+  const summary = options.findings.length === 0 ? "No upstream drift findings" : `Detected ${options.findings.length} upstream drift finding(s)`;
+  options.journal.appendUpstreamSyncScan({
+    id: options.scanId,
+    dedupeKey: options.scanId,
+    startedAt,
+    completedAt: startedAt,
+    status: "completed",
+    summary,
+    details: {
+      findingKeys: options.findings.map((finding) => finding.key),
+      followupCount,
+      createdTaskIds
+    }
+  });
+  return {
+    status: "completed",
+    summary,
+    followupCount,
+    createdTaskIds
+  };
+}
+export {
+  writeUpstreamState,
+  scanUpstream,
+  runUpstreamSyncScan,
+  readUpstreamState,
+  parseImportedUpstreamRevision,
+  classifyCommit
+};