@unbrained/pm-cli 2026.8.26 → 2026.8.27

package/packages/pm-beads/extensions/beads/runtime.ts

@@ -11,7 +11,9 @@ import type {
   GlobalOptions,
   ItemStatus,
   ItemType,
+  LogNote,
   PmSettings,
+  StructuredJsonValue,
   ToImportLinkedArtifactsOptions,
   ToImportLinkedTestsOptions,
   ToImportLogEntriesOptions,
@@ -27,10 +29,16 @@ const UNSAFE_AUTO_DISCOVERY_FILES = [
   "sync_base.jsonl",
 ] as const;
 
+const AUTO_DISCOVERY_WARNINGS = new Map<string, string[]>([
+  ["issues.jsonl", ["beads_import_source_autodiscovered:issues.jsonl"]],
+]);
+
 /** Inputs that customize the beads import operation. */
 export interface BeadsImportOptions {
   /** Value that configures or reports file for this contract. */
   file?: string;
+  /** Path to a complete `bd backup` JSONL directory. */
+  backupDir?: string;
   /** Value that configures or reports author for this contract. */
   author?: string;
   /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -53,6 +61,36 @@ export interface BeadsImportResult {
   ids: string[];
   /** Value that configures or reports warnings for this contract. */
   warnings: string[];
+  /** Whether source and imported relational counts prove lossless parity. */
+  complete?: boolean;
+  /** Source rows counted across a portable backup. */
+  source_counts?: BeadsPortableCounts;
+  /** Rows attached to imported pm items from a portable backup. */
+  imported_counts?: BeadsPortableCounts;
+  /** Complete source-to-imported identity receipt when source IDs are preserved. */
+  id_mapping?: BeadsIdMapping[];
+}
+
+/** Relational row counts carried by a Beads portable-backup receipt. */
+export interface BeadsPortableCounts {
+  /** Issue rows in `issues.jsonl`. */
+  issues: number;
+  /** Event rows in `events.jsonl`. */
+  events: number;
+  /** Comment rows in `comments.jsonl`. */
+  comments: number;
+  /** Dependency rows in `dependencies.jsonl`. */
+  dependencies: number;
+  /** Label rows in `labels.jsonl`. */
+  labels: number;
+}
+
+/** One exact source-to-imported ID mapping. */
+export interface BeadsIdMapping {
+  /** Authoritative source identifier. */
+  source_id: string;
+  /** Identifier committed to pm storage. */
+  imported_id: string;
 }
 
 interface BeadsRecord extends Record<string, unknown> {
@@ -80,6 +118,12 @@ interface BeadsRecord extends Record<string, unknown> {
   design?: unknown;
   external_ref?: unknown;
   close_reason?: unknown;
+  resolution?: unknown;
+  expected_result?: unknown;
+  actual_result?: unknown;
+  parent?: unknown;
+  comment_count?: unknown;
+  source_events?: unknown;
   dependencies?: unknown;
   comments?: unknown;
   notes?: unknown;
@@ -96,6 +140,7 @@ interface BeadsImportRuntime {
     | "commitImportedItem"
     | "generateItemId"
     | "getItemPath"
+    | "listAllItemMetadataLight"
     | "locateItem"
     | "normalizeItemMetadata"
   >;
@@ -107,6 +152,19 @@ interface BeadsImportRuntime {
   message: string;
 }
 
+interface ResolvedBeadsSource {
+  source: string;
+  sourcePaths: string[];
+  raw: string;
+  warnings: string[];
+  records?: BeadsRecord[];
+  counts?: BeadsPortableCounts;
+}
+
+interface BeadsPortableBackupState {
+  counts?: Partial<BeadsPortableCounts> & { config?: number };
+}
+
 type BeadsImportLineResult =
   | { id: string; writeWarnings: string[] }
   | { warning: string };
@@ -120,7 +178,6 @@ const {
   getActiveExtensionRegistrations,
   isTimestampLiteral,
   normalizeItemId,
-  normalizeRawItemId,
   nowIso,
   pathExists,
   readSettings,
@@ -256,10 +313,24 @@ function normalizeImportedId(
   preserveSourceIds: boolean,
 ): string {
   return preserveSourceIds
-    ? normalizeRawItemId(id)
+    ? preserveBeadsSourceId(id)
     : normalizeItemId(id, prefix);
 }
 
+function preserveBeadsSourceId(id: string): string {
+  if (
+    id.length === 0 ||
+    id !== id.trim() ||
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(id)
+  ) {
+    throw new PmCliError(
+      `Beads source ID ${JSON.stringify(id)} cannot be preserved safely; IDs must contain only letters, digits, dots, underscores, and hyphens with no surrounding whitespace.`,
+      EXIT_CODE.USAGE,
+    );
+  }
+  return id;
+}
+
 function toDependencies(
   value: unknown,
   fallbackCreatedAt: string,
@@ -284,31 +355,39 @@ function toDependencies(
   return dependencies.length > 0 ? dependencies : undefined;
 }
 
-function toDependency(
-  value: unknown,
-  fallbackCreatedAt: string,
-  prefix: string,
-  preserveSourceIds: boolean,
-): Dependency | undefined {
+function toBeadsDependencyId(value: unknown): string | undefined {
   if (typeof value === "string") {
-    return toDependencyFromString(
-      value,
-      fallbackCreatedAt,
-      prefix,
-      preserveSourceIds,
-    );
+    return toNonEmptyString(value);
   }
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return undefined;
   }
   const candidate = value as Record<string, unknown>;
-  const id =
+  return (
+    toNonEmptyString(candidate.depends_on_id) ??
     toNonEmptyString(candidate.id) ??
-    toNonEmptyString(candidate.item_id) ??
-    toNonEmptyString(candidate.depends_on_id);
+    toNonEmptyString(candidate.item_id)
+  );
+}
+
+function toDependency(
+  value: unknown,
+  fallbackCreatedAt: string,
+  prefix: string,
+  preserveSourceIds: boolean,
+): Dependency | undefined {
+  const id = toBeadsDependencyId(value);
   if (!id) {
     return undefined;
   }
+  if (typeof value === "string") {
+    return {
+      id: normalizeImportedId(id, prefix, preserveSourceIds),
+      kind: "related",
+      created_at: fallbackCreatedAt,
+    };
+  }
+  const candidate = value as Record<string, unknown>;
   const dependencyKind = toDependencyKind(candidate.type ?? candidate.kind);
   return {
     id: normalizeImportedId(id, prefix, preserveSourceIds),
@@ -321,23 +400,6 @@ function toDependency(
   };
 }
 
-function toDependencyFromString(
-  value: string,
-  fallbackCreatedAt: string,
-  prefix: string,
-  preserveSourceIds: boolean,
-): Dependency | undefined {
-  const id = toNonEmptyString(value);
-  if (!id) {
-    return undefined;
-  }
-  return {
-    id: normalizeImportedId(id, prefix, preserveSourceIds),
-    kind: "related",
-    created_at: fallbackCreatedAt,
-  };
-}
-
 const selectAuthor = selectImportAuthor;
 const ensureInitHasRun = ensureTrackerInitialized;
 
@@ -365,17 +427,26 @@ async function readStdin(): Promise<string> {
   });
 }
 
-async function resolveBeadsSource(rawPath: string | undefined): Promise<{
-  source: string;
-  sourcePath?: string;
-  raw: string;
-  warnings: string[];
-}> {
+async function resolveBeadsSource(
+  rawPath: string | undefined,
+  rawBackupDir: string | undefined,
+): Promise<ResolvedBeadsSource> {
+  const backupDir = toNonEmptyString(rawBackupDir);
   const explicitSource = toNonEmptyString(rawPath);
+  if (backupDir && explicitSource) {
+    throw new PmCliError(
+      'Options "--file" and "--backup-dir" are mutually exclusive.',
+      EXIT_CODE.USAGE,
+    );
+  }
+  if (backupDir) {
+    return resolvePortableBackup(backupDir);
+  }
   if (explicitSource) {
     if (explicitSource === "-") {
       return {
         source: "-",
+        sourcePaths: [],
         raw: await readStdin(),
         warnings: [],
       };
@@ -390,7 +461,7 @@ async function resolveBeadsSource(rawPath: string | undefined): Promise<{
     }
     return {
       source: explicitSource,
-      sourcePath: explicitPath,
+      sourcePaths: [explicitPath],
       raw: await fs.readFile(explicitPath, "utf8"),
       warnings: [],
     };
@@ -401,12 +472,9 @@ async function resolveBeadsSource(rawPath: string | undefined): Promise<{
     if (await pathExists(candidatePath)) {
       return {
         source: candidate,
-        sourcePath: candidatePath,
+        sourcePaths: [candidatePath],
         raw: await fs.readFile(candidatePath, "utf8"),
-        warnings:
-          candidate === PRIMARY_AUTO_DISCOVERY_FILES[0]
-            ? []
-            : [`beads_import_source_autodiscovered:${candidate}`],
+        warnings: AUTO_DISCOVERY_WARNINGS.get(candidate) ?? [],
       };
     }
   }
@@ -427,6 +495,275 @@ async function resolveBeadsSource(rawPath: string | undefined): Promise<{
   );
 }
 
+async function readPortableJsonl(
+  backupPath: string,
+  filename: string,
+): Promise<{ path: string; records: Record<string, unknown>[] }> {
+  const filePath = path.join(backupPath, filename);
+  if (!(await pathExists(filePath))) {
+    throw new PmCliError(
+      `Beads portable backup is incomplete: missing ${filePath}. Run bd backup --force and pass its backup directory with --backup-dir.`,
+      EXIT_CODE.NOT_FOUND,
+    );
+  }
+  const records: Record<string, unknown>[] = [];
+  const lines = (await fs.readFile(filePath, "utf8")).split(/\r?\n/u);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!.trim();
+    if (line.length === 0) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line) as unknown;
+    } catch {
+      throw new PmCliError(
+        `Beads portable backup contains invalid JSON in ${filename}:${index + 1}.`,
+        EXIT_CODE.USAGE,
+      );
+    }
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
+      throw new PmCliError(
+        `Beads portable backup contains a non-record row in ${filename}:${index + 1}.`,
+        EXIT_CODE.USAGE,
+      );
+    }
+    records.push(parsed as Record<string, unknown>);
+  }
+  return { path: filePath, records };
+}
+
+function portableRelationIssueId(
+  record: Record<string, unknown>,
+  filename: string,
+): string {
+  const issueId = toNonEmptyString(record.issue_id);
+  if (!issueId) {
+    throw new PmCliError(
+      `Beads portable backup relation in ${filename} is missing issue_id.`,
+      EXIT_CODE.USAGE,
+    );
+  }
+  return issueId;
+}
+
+function attachPortableRelations(
+  issues: BeadsRecord[],
+  comments: Record<string, unknown>[],
+  events: Record<string, unknown>[],
+  dependencies: Record<string, unknown>[],
+  labels: Record<string, unknown>[],
+): void {
+  const byId = new Map<string, BeadsRecord>();
+  for (const issue of issues) {
+    const id = toNonEmptyString(issue.id);
+    if (!id) {
+      throw new PmCliError(
+        "Beads portable backup issue is missing id.",
+        EXIT_CODE.USAGE,
+      );
+    }
+    if (byId.has(id)) {
+      throw new PmCliError(
+        `Beads portable backup contains duplicate issue ID ${id}.`,
+        EXIT_CODE.CONFLICT,
+      );
+    }
+    if (!toNonEmptyString(issue.title)) {
+      throw new PmCliError(
+        `Beads portable backup issue ${id} is missing title.`,
+        EXIT_CODE.USAGE,
+      );
+    }
+    byId.set(id, issue);
+  }
+  attachPortableRelationRows(
+    byId,
+    comments,
+    "comments.jsonl",
+    "comments",
+    (row, issueId) => {
+      if (!toNonEmptyString(row.text)) {
+        throw new PmCliError(
+          `Beads portable backup comment for ${issueId} is missing text.`,
+          EXIT_CODE.USAGE,
+        );
+      }
+      return row;
+    },
+  );
+  attachPortableRelationRows(
+    byId,
+    events,
+    "events.jsonl",
+    "source_events",
+    (row, issueId) => {
+      if (!toNonEmptyString(row.event_type)) {
+        throw new PmCliError(
+          `Beads portable backup event for ${issueId} is missing event_type.`,
+          EXIT_CODE.USAGE,
+        );
+      }
+      return row;
+    },
+  );
+  attachPortableRelationRows(
+    byId,
+    dependencies,
+    "dependencies.jsonl",
+    "dependencies",
+    (row, issueId) => {
+      const targetId = toNonEmptyString(row.depends_on_id);
+      if (!targetId) {
+        throw new PmCliError(
+          `Beads portable backup dependency for ${issueId} is missing depends_on_id.`,
+          EXIT_CODE.USAGE,
+        );
+      }
+      if (!byId.has(targetId)) {
+        throw new PmCliError(
+          `Beads portable backup dependency for ${issueId} references missing target ${targetId}.`,
+          EXIT_CODE.CONFLICT,
+        );
+      }
+      return {
+        ...row,
+        id: undefined,
+        item_id: undefined,
+        depends_on_id: targetId,
+      };
+    },
+  );
+  attachPortableRelationRows(
+    byId,
+    labels,
+    "labels.jsonl",
+    "labels",
+    (row, issueId) => {
+      const label = toNonEmptyString(row.label);
+      if (!label) {
+        throw new PmCliError(
+          `Beads portable backup label for ${issueId} is missing label.`,
+          EXIT_CODE.USAGE,
+        );
+      }
+      return label;
+    },
+  );
+}
+
+function attachPortableRelationRows(
+  byId: ReadonlyMap<string, BeadsRecord>,
+  rows: Record<string, unknown>[],
+  filename: string,
+  field: "comments" | "dependencies" | "labels" | "source_events",
+  normalize: (row: Record<string, unknown>, issueId: string) => unknown,
+): void {
+  for (const row of rows) {
+    const issueId = portableRelationIssueId(row, filename);
+    const issue = byId.get(issueId);
+    if (!issue) {
+      throw new PmCliError(
+        `Beads portable backup ${filename} references missing issue ${issueId}.`,
+        EXIT_CODE.CONFLICT,
+      );
+    }
+    const current = Array.isArray(issue[field]) ? issue[field] : [];
+    issue[field] = [...current, normalize(row, issueId)];
+  }
+}
+
+function verifyPortableCounts(
+  expected: BeadsPortableBackupState["counts"],
+  actual: BeadsPortableCounts,
+): void {
+  if (!expected) {
+    throw new PmCliError(
+      "Beads portable backup_state.json is missing counts.",
+      EXIT_CODE.USAGE,
+    );
+  }
+  for (const key of Object.keys(actual) as Array<keyof BeadsPortableCounts>) {
+    if (expected[key] !== actual[key]) {
+      throw new PmCliError(
+        `Beads portable backup count mismatch for ${key}: backup_state=${String(expected[key])}, observed=${actual[key]}.`,
+        EXIT_CODE.CONFLICT,
+      );
+    }
+  }
+}
+
+async function resolvePortableBackup(
+  rawBackupDir: string,
+): Promise<ResolvedBeadsSource> {
+  const backupPath = resolveInputPath(rawBackupDir);
+  if (!(await pathExists(backupPath))) {
+    throw new PmCliError(
+      `Beads portable backup directory not found at ${backupPath}`,
+      EXIT_CODE.NOT_FOUND,
+    );
+  }
+  const [issuesFile, eventsFile, commentsFile, dependenciesFile, labelsFile] =
+    await Promise.all([
+      readPortableJsonl(backupPath, "issues.jsonl"),
+      readPortableJsonl(backupPath, "events.jsonl"),
+      readPortableJsonl(backupPath, "comments.jsonl"),
+      readPortableJsonl(backupPath, "dependencies.jsonl"),
+      readPortableJsonl(backupPath, "labels.jsonl"),
+    ]);
+  const statePath = path.join(backupPath, "backup_state.json");
+  if (!(await pathExists(statePath))) {
+    throw new PmCliError(
+      `Beads portable backup is incomplete: missing ${statePath}.`,
+      EXIT_CODE.NOT_FOUND,
+    );
+  }
+  let state: BeadsPortableBackupState;
+  try {
+    state = JSON.parse(
+      await fs.readFile(statePath, "utf8"),
+    ) as BeadsPortableBackupState;
+  } catch {
+    throw new PmCliError(
+      `Beads portable backup contains invalid JSON in ${statePath}.`,
+      EXIT_CODE.USAGE,
+    );
+  }
+  const records = issuesFile.records.map((record) => ({ ...record }));
+  attachPortableRelations(
+    records,
+    commentsFile.records,
+    eventsFile.records,
+    dependenciesFile.records,
+    labelsFile.records,
+  );
+  const counts: BeadsPortableCounts = {
+    issues: records.length,
+    events: eventsFile.records.length,
+    comments: commentsFile.records.length,
+    dependencies: dependenciesFile.records.length,
+    labels: labelsFile.records.length,
+  };
+  verifyPortableCounts(state.counts, counts);
+  return {
+    source: backupPath,
+    sourcePaths: [
+      issuesFile.path,
+      eventsFile.path,
+      commentsFile.path,
+      dependenciesFile.path,
+      labelsFile.path,
+      statePath,
+    ],
+    raw: "",
+    warnings: [],
+    records,
+    counts,
+  };
+}
+
 function parseBeadsLine(line: string, lineNumber: number): ParsedBeadsLine {
   const trimmed = line.trim();
   if (trimmed.length === 0) {
@@ -444,11 +781,144 @@ function parseBeadsLine(line: string, lineNumber: number): ParsedBeadsLine {
   return { record: parsed as BeadsRecord };
 }
 
+function parseBeadsRecords(source: ResolvedBeadsSource): {
+  records: Array<{ record: BeadsRecord; lineNumber: number }>;
+  warnings: string[];
+  skipped: number;
+} {
+  if (source.records) {
+    return {
+      records: source.records.map((record, index) => ({
+        record,
+        lineNumber: index + 1,
+      })),
+      warnings: [],
+      skipped: 0,
+    };
+  }
+  const records: Array<{ record: BeadsRecord; lineNumber: number }> = [];
+  const warnings: string[] = [];
+  let skipped = 0;
+  const lines = source.raw.split(/\r?\n/u);
+  for (let index = 0; index < lines.length; index += 1) {
+    const lineNumber = index + 1;
+    const parsed = parseBeadsLine(lines[index]!, lineNumber);
+    if (!parsed) continue;
+    if ("warning" in parsed) {
+      warnings.push(parsed.warning);
+      skipped += 1;
+    } else {
+      records.push({ record: parsed.record, lineNumber });
+    }
+  }
+  return { records, warnings, skipped };
+}
+
+function assertLosslessSourceFormat(
+  source: ResolvedBeadsSource,
+  records: Array<{ record: BeadsRecord }>,
+): void {
+  if (
+    source.counts === undefined &&
+    records.some(
+      ({ record }) =>
+        typeof record.comment_count === "number" && record.comment_count > 0,
+    )
+  ) {
+    throw new PmCliError(
+      "This Beads issue export advertises comment counts but omits the relational comment/event tables. Run `bd backup --force` and import the resulting directory with `pm beads import --backup-dir <path>`; no pm items were written.",
+      EXIT_CODE.USAGE,
+    );
+  }
+}
+
+function assertPreservedRelationshipIdSafety(record: BeadsRecord): void {
+  const parent = toNonEmptyString(record.parent);
+  if (parent) preserveBeadsSourceId(parent);
+  if (!Array.isArray(record.dependencies)) return;
+  for (const dependency of record.dependencies) {
+    const dependencyId = toBeadsDependencyId(dependency);
+    if (dependencyId) preserveBeadsSourceId(dependencyId);
+  }
+}
+
+async function assertPreservedIdSafety(
+  records: Array<{ record: BeadsRecord; lineNumber: number }>,
+  runtime: BeadsImportRuntime,
+): Promise<void> {
+  if (!runtime.preserveSourceIds) return;
+  const sourceByFoldedId = new Map<
+    string,
+    { id: string; lineNumber: number }
+  >();
+  for (const { record, lineNumber } of records) {
+    assertPreservedRelationshipIdSafety(record);
+    if (typeof record.id !== "string" || record.id.trim().length === 0) {
+      continue;
+    }
+    const id = preserveBeadsSourceId(record.id);
+    const folded = id.toLocaleLowerCase("en-US");
+    const previous = sourceByFoldedId.get(folded);
+    if (previous) {
+      throw new PmCliError(
+        `Beads preserve-source-ids case-insensitive ID collision: ${previous.id} (line ${previous.lineNumber}) conflicts with ${id} (line ${lineNumber}); no pm items were written.`,
+        EXIT_CODE.CONFLICT,
+      );
+    }
+    sourceByFoldedId.set(folded, { id, lineNumber });
+  }
+  const existingItems = await runtime.sdk.listAllItemMetadataLight(
+    runtime.pmRoot,
+    runtime.settings.item_format,
+    runtime.typeRegistry.type_to_folder,
+  );
+  const existingByFoldedId = new Map(
+    existingItems.map(({ id }) => [id.toLocaleLowerCase("en-US"), id]),
+  );
+  for (const { id } of sourceByFoldedId.values()) {
+    const existingId = existingByFoldedId.get(id.toLocaleLowerCase("en-US"));
+    if (existingId) {
+      throw new PmCliError(
+        `Beads preserve-source-ids target collision: source ${id} conflicts case-insensitively with existing pm item ${existingId}; no pm items were written.`,
+        EXIT_CODE.CONFLICT,
+      );
+    }
+  }
+}
+
+function countImportedPortableRelations(
+  records: Array<{ record: BeadsRecord }>,
+  importedSourceIds: ReadonlySet<string>,
+): BeadsPortableCounts {
+  const importedRecords = records
+    .map(({ record }) => record)
+    .filter(
+      (record) =>
+        typeof record.id === "string" && importedSourceIds.has(record.id),
+    );
+  const count = (field: keyof BeadsRecord): number =>
+    importedRecords.reduce(
+      (total, record) =>
+        total + (Array.isArray(record[field]) ? record[field].length : 0),
+      0,
+    );
+  return {
+    issues: importedRecords.length,
+    events: count("source_events"),
+    comments: count("comments"),
+    dependencies: count("dependencies"),
+    labels: count("labels"),
+  };
+}
+
 async function resolveBeadsImportId(
   record: BeadsRecord,
   runtime: BeadsImportRuntime,
 ): Promise<string> {
-  const rawId = toNonEmptyString(record.id);
+  const rawId =
+    typeof record.id === "string" && record.id.trim().length > 0
+      ? record.id
+      : undefined;
   return rawId
     ? normalizeImportedId(
         rawId,
@@ -461,6 +931,53 @@ async function resolveBeadsImportId(
       );
 }
 
+function toBeadsEventNotes(
+  value: unknown,
+  fallbackCreatedAt: string,
+  fallbackAuthor: string,
+): LogNote[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry): LogNote[] => {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      return [];
+    }
+    const record = entry as Record<string, unknown>;
+    const eventType = toNonEmptyString(record.event_type);
+    if (!eventType) {
+      return [];
+    }
+    const data = {
+      source: "beads-portable-backup",
+      ...record,
+    } as Record<string, StructuredJsonValue>;
+    return [
+      {
+        created_at: toIsoString(record.created_at) ?? fallbackCreatedAt,
+        author: toNonEmptyString(record.actor) ?? fallbackAuthor,
+        text: toNonEmptyString(record.comment) ?? eventType,
+        format: "json",
+        event_type: `beads:${eventType}`,
+        data,
+      },
+    ];
+  });
+}
+
+function collectBeadsNotes(
+  record: BeadsRecord,
+  createdAt: string,
+  author: string,
+): LogNote[] | undefined {
+  const notes =
+    toImportLogEntries(record.notes, {
+      ...BEADS_LOG_ENTRY_OPTIONS,
+      fallbackCreatedAt: createdAt,
+      fallbackAuthor: author,
+    }) ?? [];
+  notes.push(...toBeadsEventNotes(record.source_events, createdAt, author));
+  return notes.length > 0 ? notes : undefined;
+}
+
 function buildBeadsImportedBody(record: BeadsRecord): string {
   const rawBody = toNonEmptyString(record.body) ?? "";
   const design = toNonEmptyString(record.design);
@@ -486,21 +1003,66 @@ async function importBeadsRecord(
     return { warning: `beads_import_missing_title:${lineNumber}` };
   }
 
+  const id = await resolveBeadsImportId(record, runtime);
+  const itemMetadata = buildBeadsItemMetadata(record, id, title, runtime);
+  const afterDocument = runtime.sdk.canonicalDocument({
+    metadata: itemMetadata,
+    body: buildBeadsImportedBody(record),
+  });
+  const existing = await runtime.sdk.locateItem(
+    runtime.pmRoot,
+    id,
+    runtime.settings.id_prefix,
+    runtime.settings.item_format,
+    runtime.typeRegistry.type_to_folder,
+  );
+  if (existing) {
+    return { warning: `beads_import_item_exists:${id}` };
+  }
+  const itemPath = runtime.sdk.getItemPath(
+    runtime.pmRoot,
+    itemMetadata.type,
+    id,
+    "toon",
+    runtime.typeRegistry.type_to_folder,
+  );
+  const commit = await runtime.sdk.commitImportedItem({
+    pmRoot: runtime.pmRoot,
+    id,
+    itemPath,
+    document: afterDocument,
+    author: runtime.author,
+    message: runtime.message,
+    settings: runtime.settings,
+    conflictWarningPrefix: "beads_import_lock_conflict",
+  });
+  return commit.committed
+    ? { id, writeWarnings: commit.writeWarnings }
+    : { warning: commit.conflictWarning };
+}
+
+function buildBeadsItemMetadata(
+  record: BeadsRecord,
+  id: string,
+  title: string,
+  runtime: BeadsImportRuntime,
+): ReturnType<typeof pmSdk.normalizeItemMetadata> {
   const createdAt = toIsoString(record.created_at) ?? nowIso();
   const updatedAt = toIsoString(record.updated_at) ?? createdAt;
-  const id = await resolveBeadsImportId(record, runtime);
   const typeMapping = toItemType(record.issue_type ?? record.type);
   const type = typeMapping.type;
+  const status = toStatus(record.status);
   const closedAt = toIsoString(record.closed_at);
+  const closeReason = toNonEmptyString(record.close_reason);
   const assignee =
     toNonEmptyString(record.assignee) ?? toNonEmptyString(record.owner);
-  const itemMetadata = runtime.sdk.normalizeItemMetadata({
+  return runtime.sdk.normalizeItemMetadata({
     id,
     title,
     description: toNonEmptyString(record.description) ?? "",
     type,
     source_type: typeMapping.sourceType,
-    status: toStatus(record.status),
+    status,
     priority: toPriority(record.priority),
     tags: toTags(record.tags ?? record.labels),
     created_at: createdAt,
@@ -517,7 +1079,20 @@ async function importBeadsRecord(
     acceptance_criteria: toNonEmptyString(record.acceptance_criteria),
     design: toNonEmptyString(record.design),
     external_ref: toNonEmptyString(record.external_ref),
-    close_reason: toNonEmptyString(record.close_reason),
+    parent:
+      typeof record.parent === "string" && record.parent.trim().length > 0
+        ? normalizeImportedId(
+            record.parent,
+            runtime.settings.id_prefix,
+            runtime.preserveSourceIds,
+          )
+        : undefined,
+    close_reason: closeReason,
+    resolution:
+      toNonEmptyString(record.resolution) ??
+      (status === "closed" || status === "canceled" ? closeReason : undefined),
+    expected_result: toNonEmptyString(record.expected_result),
+    actual_result: toNonEmptyString(record.actual_result),
     dependencies: toDependencies(
       record.dependencies,
       createdAt,
@@ -529,11 +1104,7 @@ async function importBeadsRecord(
       fallbackCreatedAt: createdAt,
       fallbackAuthor: runtime.author,
     }),
-    notes: toImportLogEntries(record.notes, {
-      ...BEADS_LOG_ENTRY_OPTIONS,
-      fallbackCreatedAt: createdAt,
-      fallbackAuthor: runtime.author,
-    }),
+    notes: collectBeadsNotes(record, createdAt, runtime.author),
     learnings: toImportLogEntries(record.learnings, {
       ...BEADS_LOG_ENTRY_OPTIONS,
       fallbackCreatedAt: createdAt,
@@ -543,40 +1114,6 @@ async function importBeadsRecord(
     tests: toImportLinkedTests(record.tests, BEADS_TEST_OPTIONS),
     docs: toImportLinkedDocs(record.docs, BEADS_DOC_OPTIONS),
   });
-  const afterDocument = runtime.sdk.canonicalDocument({
-    metadata: itemMetadata,
-    body: buildBeadsImportedBody(record),
-  });
-  const existing = await runtime.sdk.locateItem(
-    runtime.pmRoot,
-    id,
-    runtime.settings.id_prefix,
-    runtime.settings.item_format,
-    runtime.typeRegistry.type_to_folder,
-  );
-  if (existing) {
-    return { warning: `beads_import_item_exists:${id}` };
-  }
-  const itemPath = runtime.sdk.getItemPath(
-    runtime.pmRoot,
-    type,
-    id,
-    "toon",
-    runtime.typeRegistry.type_to_folder,
-  );
-  const commit = await runtime.sdk.commitImportedItem({
-    pmRoot: runtime.pmRoot,
-    id,
-    itemPath,
-    document: afterDocument,
-    author: runtime.author,
-    message: runtime.message,
-    settings: runtime.settings,
-    conflictWarningPrefix: "beads_import_lock_conflict",
-  });
-  return commit.committed
-    ? { id, writeWarnings: commit.writeWarnings }
-    : { warning: commit.conflictWarning };
 }
 
 /** Executes the beads import operation through the package runtime. */
@@ -593,14 +1130,18 @@ export async function runBeadsImport(
     getActiveExtensionRegistrations(),
   );
   const preserveSourceIds = options.preserveSourceIds === true;
+  const resolvedSource = await resolveBeadsSource(
+    options.file,
+    options.backupDir,
+  );
   const {
     source,
-    sourcePath,
-    raw,
+    sourcePaths,
     warnings: sourceWarnings,
-  } = await resolveBeadsSource(options.file);
+    counts: sourceCounts,
+  } = resolvedSource;
   const warnings: string[] = [...sourceWarnings];
-  if (sourcePath) {
+  for (const sourcePath of sourcePaths) {
     warnings.push(
       ...(await runActiveOnReadHooks({
         path: sourcePath,
@@ -608,7 +1149,9 @@ export async function runBeadsImport(
       })),
     );
   }
-  const lines = raw.split(/\r?\n/);
+  const parsed = parseBeadsRecords(resolvedSource);
+  warnings.push(...parsed.warnings);
+  assertLosslessSourceFormat(resolvedSource, parsed.records);
   const author = selectAuthor(
     toNonEmptyString(options.author),
     settings.author_default,
@@ -616,8 +1159,10 @@ export async function runBeadsImport(
   const message =
     toNonEmptyString(options.message) ?? "Import from Beads JSONL";
   const ids: string[] = [];
+  const idMapping: BeadsIdMapping[] = [];
+  const importedSourceIds = new Set<string>();
   let imported = 0;
-  let skipped = 0;
+  let skipped = parsed.skipped;
   const runtime: BeadsImportRuntime = {
     sdk: pmSdk,
     pmRoot,
@@ -627,23 +1172,10 @@ export async function runBeadsImport(
     author,
     message,
   };
+  await assertPreservedIdSafety(parsed.records, runtime);
 
-  for (let index = 0; index < lines.length; index += 1) {
-    const lineNumber = index + 1;
-    const parsed = parseBeadsLine(lines[index], lineNumber);
-    if (!parsed) {
-      continue;
-    }
-    if ("warning" in parsed) {
-      warnings.push(parsed.warning);
-      skipped += 1;
-      continue;
-    }
-    const importedLine = await importBeadsRecord(
-      parsed.record,
-      lineNumber,
-      runtime,
-    );
+  for (const { record, lineNumber } of parsed.records) {
+    const importedLine = await importBeadsRecord(record, lineNumber, runtime);
     if ("warning" in importedLine) {
       warnings.push(importedLine.warning);
       skipped += 1;
@@ -651,9 +1183,22 @@ export async function runBeadsImport(
     }
     warnings.push(...importedLine.writeWarnings);
     ids.push(importedLine.id);
+    if (typeof record.id === "string" && record.id.trim().length > 0) {
+      importedSourceIds.add(record.id);
+      if (preserveSourceIds) {
+        idMapping.push({
+          source_id: record.id,
+          imported_id: importedLine.id,
+        });
+      }
+    }
     imported += 1;
   }
 
+  const importedCounts = sourceCounts
+    ? countImportedPortableRelations(parsed.records, importedSourceIds)
+    : undefined;
+
   return {
     ok: true,
     source,
@@ -661,5 +1206,19 @@ export async function runBeadsImport(
     skipped,
     ids,
     warnings,
+    ...(sourceCounts
+      ? {
+          complete:
+            skipped === 0 &&
+            Object.keys(sourceCounts).every(
+              (key) =>
+                sourceCounts[key as keyof BeadsPortableCounts] ===
+                importedCounts?.[key as keyof BeadsPortableCounts],
+            ),
+          source_counts: sourceCounts,
+          imported_counts: importedCounts,
+        }
+      : {}),
+    ...(preserveSourceIds ? { id_mapping: idMapping } : {}),
   };
 }