get-tbd 0.1.29 → 0.2.0

package/dist/{id-mapping-CqrrLgeX.mjs → id-mapping-CtfTfGIh.mjs}

@@ -1,4 +1,4 @@
-import { _ as IdMappingYamlSchema } from "./schemas-C8mOQykE.mjs";
+import { b as IdMappingYamlSchema } from "./schemas-f0EcuAVu.mjs";
 import { i as parseYamlToleratingDuplicateKeys, r as hasMergeConflictMarkers, s as stringifyYaml } from "./yaml-utils-BPy991by.mjs";
 import { mkdir, readFile, rmdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -6,6 +6,149 @@ import { writeFile } from "atomically";
 import { monotonicFactory } from "ulid";
 import { randomBytes } from "node:crypto";
 
+//#region src/utils/lockfile.ts
+/**
+* Directory-based mutual exclusion for concurrent file access.
+*
+* Note: Despite the name "lockfile", this is NOT a POSIX file lock (flock/fcntl).
+* It uses mkdir to create a lock *directory* as a coordination convention — no
+* OS-level file locking syscalls are involved. This makes it portable across all
+* filesystems, including NFS and other network mounts where flock/fcntl locks
+* are unreliable or unsupported.
+*
+* This is the same strategy used by:
+*
+* - **Git** for ref updates (e.g., `.git/refs/heads/main.lock`)
+*   See: https://git-scm.com/docs/gitrepository-layout ("lockfile protocol")
+* - **npm** for package-lock.json concurrent access
+*
+* ## Why mkdir?
+*
+* `mkdir(2)` is atomic on all common filesystems (local and network): it either
+* creates the directory or returns EEXIST. Unlike `open(O_CREAT|O_EXCL)`,
+* a directory lock is trivially distinguishable from normal files.
+*
+* Node.js `fs.mkdir` maps directly to the mkdir(2) syscall, preserving
+* the atomicity guarantee:
+*   https://nodejs.org/api/fs.html#fsmkdirpath-options-callback
+*
+* ## Lock lifecycle
+*
+* 1. **Acquire**: `mkdir(lockDir)` — fails with EEXIST if held by another process
+* 2. **Hold**: Execute the critical section
+* 3. **Release**: `rmdir(lockDir)` — in a finally block
+* 4. **Stale detection**: If lock mtime exceeds a threshold, assume the holder
+*    crashed and break the lock. This is a heuristic — safe when the critical
+*    section is short-lived (sub-second for file I/O).
+*
+* ## Failure on timeout
+*
+* If the lock cannot be acquired within the timeout, a LockAcquisitionError is
+* thrown. This prevents the dangerous "degraded mode" where the critical section
+* runs without mutual exclusion, which can cause data loss (e.g., lost ID
+* mappings during concurrent `tbd create`).
+*
+* IMPORTANT: `timeoutMs` must be greater than `staleMs` so stale locks from
+* crashed processes are always detected and broken before the timeout expires.
+*/
+const DEFAULT_TIMEOUT_MS = 1e4;
+const DEFAULT_POLL_MS = 50;
+const DEFAULT_STALE_MS = 5e3;
+/**
+* Lock timing profile for shared data-sync operations.
+*
+* Issue sync can include fetch, merge, push, and outbox import work, so it must
+* not use the short stale window intended for single-file writes. `timeoutMs`
+* is kept just above `staleMs` so a crashed-process lock is always broken as
+* stale before the timeout expires, matching the invariant documented above.
+*
+* Accepted trade-off (no heartbeat): a live `tbd sync` that hangs longer than
+* `staleMs` (30 min) can have its lock broken by another process mid-operation.
+* For current data sizes this is acceptable — single-repo sync workloads
+* complete well under the window — and adding heartbeat metadata adds
+* cross-process state machinery without changing the common case. If sync
+* workloads grow or the lock-break race becomes observable in practice,
+* revisit by adding heartbeat metadata inside the lock directory (touch mtime
+* periodically; treat as stale only if heartbeat is older than `staleMs`).
+* See: plan-2026-05-17-shared-common-dir-sync-worktree.md §Post-Review
+* Hardening H6.
+*/
+const DATA_SYNC_LOCK_OPTIONS = {
+	timeoutMs: 35 * 6e4,
+	pollMs: 250,
+	staleMs: 30 * 6e4
+};
+/**
+* Error thrown when the lock cannot be acquired within the timeout.
+*/
+var LockAcquisitionError = class extends Error {
+	constructor(lockPath, timeoutMs) {
+		super(`Failed to acquire lock at ${lockPath} within ${timeoutMs}ms. Another process may be holding the lock. If this persists, delete the lock directory manually and retry.`);
+		this.name = "LockAcquisitionError";
+	}
+};
+/**
+* Execute `fn` while holding a lockfile.
+*
+* The lock is a directory at `lockPath` (typically `<target-file>.lock`).
+* Concurrent callers will wait up to `timeoutMs` for the lock, polling
+* every `pollMs`. Stale locks older than `staleMs` are broken automatically.
+*
+* If the lock cannot be acquired within the timeout, a LockAcquisitionError
+* is thrown. This ensures mutual exclusion is never silently bypassed, which
+* prevents data loss from concurrent writes.
+*
+* @param lockPath - Path to use as the lock directory (e.g., "/path/to/ids.yml.lock")
+* @param fn - Critical section to execute under the lock
+* @param options - Timing parameters for lock acquisition
+* @returns The return value of `fn`
+* @throws LockAcquisitionError if the lock cannot be acquired within the timeout
+*
+* @example
+* ```ts
+* await withLockfile('/path/to/ids.yml.lock', async () => {
+*   const data = await readFile('/path/to/ids.yml', 'utf-8');
+*   const updated = mergeEntries(data, newEntries);
+*   await writeFile('/path/to/ids.yml', updated);
+* });
+* ```
+*/
+async function withLockfile(lockPath, fn, options) {
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;
+	const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;
+	const deadline = Date.now() + timeoutMs;
+	let acquired = false;
+	while (Date.now() < deadline) try {
+		await mkdir(lockPath);
+		acquired = true;
+		break;
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		try {
+			const lockStat = await stat(lockPath);
+			if (Date.now() - lockStat.mtimeMs > staleMs) {
+				try {
+					await rmdir(lockPath);
+				} catch {}
+				continue;
+			}
+		} catch {
+			continue;
+		}
+		await new Promise((resolve) => setTimeout(resolve, pollMs));
+	}
+	if (!acquired) throw new LockAcquisitionError(lockPath, timeoutMs);
+	try {
+		return await fn();
+	} finally {
+		try {
+			await rmdir(lockPath);
+		} catch {}
+	}
+}
+
+//#endregion
 //#region src/lib/ids.ts
 /**
 * ID generation and validation utilities.
@@ -188,125 +331,6 @@ function formatDebugId(internalId, mapping, prefix = "tbd") {
 	return `${formatDisplayId(internalId, mapping, prefix)} (${internalId})`;
 }
 
-//#endregion
-//#region src/utils/lockfile.ts
-/**
-* Directory-based mutual exclusion for concurrent file access.
-*
-* Note: Despite the name "lockfile", this is NOT a POSIX file lock (flock/fcntl).
-* It uses mkdir to create a lock *directory* as a coordination convention — no
-* OS-level file locking syscalls are involved. This makes it portable across all
-* filesystems, including NFS and other network mounts where flock/fcntl locks
-* are unreliable or unsupported.
-*
-* This is the same strategy used by:
-*
-* - **Git** for ref updates (e.g., `.git/refs/heads/main.lock`)
-*   See: https://git-scm.com/docs/gitrepository-layout ("lockfile protocol")
-* - **npm** for package-lock.json concurrent access
-*
-* ## Why mkdir?
-*
-* `mkdir(2)` is atomic on all common filesystems (local and network): it either
-* creates the directory or returns EEXIST. Unlike `open(O_CREAT|O_EXCL)`,
-* a directory lock is trivially distinguishable from normal files.
-*
-* Node.js `fs.mkdir` maps directly to the mkdir(2) syscall, preserving
-* the atomicity guarantee:
-*   https://nodejs.org/api/fs.html#fsmkdirpath-options-callback
-*
-* ## Lock lifecycle
-*
-* 1. **Acquire**: `mkdir(lockDir)` — fails with EEXIST if held by another process
-* 2. **Hold**: Execute the critical section
-* 3. **Release**: `rmdir(lockDir)` — in a finally block
-* 4. **Stale detection**: If lock mtime exceeds a threshold, assume the holder
-*    crashed and break the lock. This is a heuristic — safe when the critical
-*    section is short-lived (sub-second for file I/O).
-*
-* ## Failure on timeout
-*
-* If the lock cannot be acquired within the timeout, a LockAcquisitionError is
-* thrown. This prevents the dangerous "degraded mode" where the critical section
-* runs without mutual exclusion, which can cause data loss (e.g., lost ID
-* mappings during concurrent `tbd create`).
-*
-* IMPORTANT: `timeoutMs` must be greater than `staleMs` so stale locks from
-* crashed processes are always detected and broken before the timeout expires.
-*/
-const DEFAULT_TIMEOUT_MS = 1e4;
-const DEFAULT_POLL_MS = 50;
-const DEFAULT_STALE_MS = 5e3;
-/**
-* Error thrown when the lock cannot be acquired within the timeout.
-*/
-var LockAcquisitionError = class extends Error {
-	constructor(lockPath, timeoutMs) {
-		super(`Failed to acquire lock at ${lockPath} within ${timeoutMs}ms. Another process may be holding the lock. If this persists, delete the lock directory manually and retry.`);
-		this.name = "LockAcquisitionError";
-	}
-};
-/**
-* Execute `fn` while holding a lockfile.
-*
-* The lock is a directory at `lockPath` (typically `<target-file>.lock`).
-* Concurrent callers will wait up to `timeoutMs` for the lock, polling
-* every `pollMs`. Stale locks older than `staleMs` are broken automatically.
-*
-* If the lock cannot be acquired within the timeout, a LockAcquisitionError
-* is thrown. This ensures mutual exclusion is never silently bypassed, which
-* prevents data loss from concurrent writes.
-*
-* @param lockPath - Path to use as the lock directory (e.g., "/path/to/ids.yml.lock")
-* @param fn - Critical section to execute under the lock
-* @param options - Timing parameters for lock acquisition
-* @returns The return value of `fn`
-* @throws LockAcquisitionError if the lock cannot be acquired within the timeout
-*
-* @example
-* ```ts
-* await withLockfile('/path/to/ids.yml.lock', async () => {
-*   const data = await readFile('/path/to/ids.yml', 'utf-8');
-*   const updated = mergeEntries(data, newEntries);
-*   await writeFile('/path/to/ids.yml', updated);
-* });
-* ```
-*/
-async function withLockfile(lockPath, fn, options) {
-	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-	const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;
-	const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;
-	const deadline = Date.now() + timeoutMs;
-	let acquired = false;
-	while (Date.now() < deadline) try {
-		await mkdir(lockPath);
-		acquired = true;
-		break;
-	} catch (error) {
-		if (error.code !== "EEXIST") throw error;
-		try {
-			const lockStat = await stat(lockPath);
-			if (Date.now() - lockStat.mtimeMs > staleMs) {
-				try {
-					await rmdir(lockPath);
-				} catch {}
-				continue;
-			}
-		} catch {
-			continue;
-		}
-		await new Promise((resolve) => setTimeout(resolve, pollMs));
-	}
-	if (!acquired) throw new LockAcquisitionError(lockPath, timeoutMs);
-	try {
-		return await fn();
-	} finally {
-		try {
-			await rmdir(lockPath);
-		} catch {}
-	}
-}
-
 //#endregion
 //#region src/lib/sort.ts
 /**
@@ -698,5 +722,5 @@ function resolveIdMappingConflicts(content) {
 }
 
 //#endregion
-export { formatDisplayId as _, hasShortId as a, normalizeIssueId as b, parseIdMappingFromYaml as c, resolveToInternalId as d, saveIdMapping as f, formatDebugId as g, extractUlidFromInternalId as h, generateUniqueShortId as i, reconcileMappings as l, extractShortId as m, calculateOptimalLength as n, loadIdMapping as o, extractPrefix as p, createShortIdMapping as r, mergeIdMappings as s, addIdMapping as t, resolveIdMappingConflicts as u, generateInternalId as v, validateIssueId as x, makeInternalId as y };
-//# sourceMappingURL=id-mapping-CqrrLgeX.mjs.map
+export { withLockfile as C, DATA_SYNC_LOCK_OPTIONS as S, formatDisplayId as _, hasShortId as a, normalizeIssueId as b, parseIdMappingFromYaml as c, resolveToInternalId as d, saveIdMapping as f, formatDebugId as g, extractUlidFromInternalId as h, generateUniqueShortId as i, reconcileMappings as l, extractShortId as m, calculateOptimalLength as n, loadIdMapping as o, extractPrefix as p, createShortIdMapping as r, mergeIdMappings as s, addIdMapping as t, resolveIdMappingConflicts as u, generateInternalId as v, validateIssueId as x, makeInternalId as y };
+//# sourceMappingURL=id-mapping-CtfTfGIh.mjs.map

package/dist/id-mapping-CtfTfGIh.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-mapping-CtfTfGIh.mjs","names":[],"sources":["../src/utils/lockfile.ts","../src/lib/ids.ts","../src/lib/sort.ts","../src/file/id-mapping.ts"],"sourcesContent":["/**\n * Directory-based mutual exclusion for concurrent file access.\n *\n * Note: Despite the name \"lockfile\", this is NOT a POSIX file lock (flock/fcntl).\n * It uses mkdir to create a lock *directory* as a coordination convention — no\n * OS-level file locking syscalls are involved. This makes it portable across all\n * filesystems, including NFS and other network mounts where flock/fcntl locks\n * are unreliable or unsupported.\n *\n * This is the same strategy used by:\n *\n * - **Git** for ref updates (e.g., `.git/refs/heads/main.lock`)\n *   See: https://git-scm.com/docs/gitrepository-layout (\"lockfile protocol\")\n * - **npm** for package-lock.json concurrent access\n *\n * ## Why mkdir?\n *\n * `mkdir(2)` is atomic on all common filesystems (local and network): it either\n * creates the directory or returns EEXIST. Unlike `open(O_CREAT|O_EXCL)`,\n * a directory lock is trivially distinguishable from normal files.\n *\n * Node.js `fs.mkdir` maps directly to the mkdir(2) syscall, preserving\n * the atomicity guarantee:\n *   https://nodejs.org/api/fs.html#fsmkdirpath-options-callback\n *\n * ## Lock lifecycle\n *\n * 1. **Acquire**: `mkdir(lockDir)` — fails with EEXIST if held by another process\n * 2. **Hold**: Execute the critical section\n * 3. **Release**: `rmdir(lockDir)` — in a finally block\n * 4. **Stale detection**: If lock mtime exceeds a threshold, assume the holder\n *    crashed and break the lock. This is a heuristic — safe when the critical\n *    section is short-lived (sub-second for file I/O).\n *\n * ## Failure on timeout\n *\n * If the lock cannot be acquired within the timeout, a LockAcquisitionError is\n * thrown. This prevents the dangerous \"degraded mode\" where the critical section\n * runs without mutual exclusion, which can cause data loss (e.g., lost ID\n * mappings during concurrent `tbd create`).\n *\n * IMPORTANT: `timeoutMs` must be greater than `staleMs` so stale locks from\n * crashed processes are always detected and broken before the timeout expires.\n */\n\nimport { mkdir, rmdir, stat } from 'node:fs/promises';\n\n/** Options for `withLockfile`. */\nexport interface LockfileOptions {\n  /** Maximum time (ms) to wait for the lock. Default: 10000 */\n  timeoutMs?: number;\n  /** Polling interval (ms) between acquisition attempts. Default: 50 */\n  pollMs?: number;\n  /** Age (ms) after which a lock is considered stale. Default: 5000 */\n  staleMs?: number;\n}\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_POLL_MS = 50;\nconst DEFAULT_STALE_MS = 5_000;\n\n/**\n * Lock timing profile for shared data-sync operations.\n *\n * Issue sync can include fetch, merge, push, and outbox import work, so it must\n * not use the short stale window intended for single-file writes. `timeoutMs`\n * is kept just above `staleMs` so a crashed-process lock is always broken as\n * stale before the timeout expires, matching the invariant documented above.\n *\n * Accepted trade-off (no heartbeat): a live `tbd sync` that hangs longer than\n * `staleMs` (30 min) can have its lock broken by another process mid-operation.\n * For current data sizes this is acceptable — single-repo sync workloads\n * complete well under the window — and adding heartbeat metadata adds\n * cross-process state machinery without changing the common case. If sync\n * workloads grow or the lock-break race becomes observable in practice,\n * revisit by adding heartbeat metadata inside the lock directory (touch mtime\n * periodically; treat as stale only if heartbeat is older than `staleMs`).\n * See: plan-2026-05-17-shared-common-dir-sync-worktree.md §Post-Review\n * Hardening H6.\n */\nexport const DATA_SYNC_LOCK_OPTIONS: Required<LockfileOptions> = {\n  timeoutMs: 35 * 60_000,\n  pollMs: 250,\n  staleMs: 30 * 60_000,\n};\n\n/**\n * Error thrown when the lock cannot be acquired within the timeout.\n */\nexport class LockAcquisitionError extends Error {\n  constructor(lockPath: string, timeoutMs: number) {\n    super(\n      `Failed to acquire lock at ${lockPath} within ${timeoutMs}ms. ` +\n        `Another process may be holding the lock. If this persists, ` +\n        `delete the lock directory manually and retry.`,\n    );\n    this.name = 'LockAcquisitionError';\n  }\n}\n\n/**\n * Execute `fn` while holding a lockfile.\n *\n * The lock is a directory at `lockPath` (typically `<target-file>.lock`).\n * Concurrent callers will wait up to `timeoutMs` for the lock, polling\n * every `pollMs`. Stale locks older than `staleMs` are broken automatically.\n *\n * If the lock cannot be acquired within the timeout, a LockAcquisitionError\n * is thrown. This ensures mutual exclusion is never silently bypassed, which\n * prevents data loss from concurrent writes.\n *\n * @param lockPath - Path to use as the lock directory (e.g., \"/path/to/ids.yml.lock\")\n * @param fn - Critical section to execute under the lock\n * @param options - Timing parameters for lock acquisition\n * @returns The return value of `fn`\n * @throws LockAcquisitionError if the lock cannot be acquired within the timeout\n *\n * @example\n * ```ts\n * await withLockfile('/path/to/ids.yml.lock', async () => {\n *   const data = await readFile('/path/to/ids.yml', 'utf-8');\n *   const updated = mergeEntries(data, newEntries);\n *   await writeFile('/path/to/ids.yml', updated);\n * });\n * ```\n */\nexport async function withLockfile<T>(\n  lockPath: string,\n  fn: () => Promise<T>,\n  options?: LockfileOptions,\n): Promise<T> {\n  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const pollMs = options?.pollMs ?? DEFAULT_POLL_MS;\n  const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;\n\n  const deadline = Date.now() + timeoutMs;\n  let acquired = false;\n\n  while (Date.now() < deadline) {\n    try {\n      // mkdir is atomic per POSIX.1-2017 — fails with EEXIST if already held\n      await mkdir(lockPath);\n      acquired = true;\n      break;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {\n        // Unexpected error (permissions, disk full, missing parent, etc.) —\n        // preserve the original failure instead of misreporting lock contention.\n        throw error;\n      }\n\n      // Lock exists — check if it's stale (holder likely crashed)\n      try {\n        const lockStat = await stat(lockPath);\n        if (Date.now() - lockStat.mtimeMs > staleMs) {\n          try {\n            await rmdir(lockPath);\n          } catch {\n            // Another process may have already broken/released it\n          }\n          continue; // Retry immediately after breaking stale lock\n        }\n      } catch {\n        // Lock was released between our mkdir and stat — retry immediately\n        continue;\n      }\n\n      // Lock is fresh — wait and retry\n      await new Promise((resolve) => setTimeout(resolve, pollMs));\n    }\n  }\n\n  if (!acquired) {\n    throw new LockAcquisitionError(lockPath, timeoutMs);\n  }\n\n  try {\n    return await fn();\n  } finally {\n    try {\n      await rmdir(lockPath);\n    } catch {\n      // Best-effort cleanup; stale lock detection handles the rest\n    }\n  }\n}\n","/**\n * ID generation and validation utilities.\n *\n * The system uses dual IDs for usability:\n * - Internal ID: is-{ulid} - ULID-based (26 lowercase chars), stored in files\n * - External ID: {prefix}-{short} - 4-5 base36 chars for CLI display/input\n *\n * For Beads compatibility, bd- prefix is accepted on input for external IDs.\n *\n * See: tbd-design.md §2.5 ID Generation\n */\n\nimport { monotonicFactory } from 'ulid';\nimport { randomBytes } from 'node:crypto';\n\n// Monotonic factory ensures ULIDs are strictly increasing even within the same\n// millisecond. This guarantees that lexicographic sort = creation order, which\n// is critical for deterministic list output (the tiebreaker sort is by ULID).\nconst ulid = monotonicFactory();\n\n// =============================================================================\n// Branded Types for Type-Safe ID Handling\n// =============================================================================\n\n/**\n * Branded type for internal issue IDs (is-{ulid} format).\n *\n * Internal IDs are stored in files and used as the canonical identifier.\n * Format: is-{26 lowercase alphanumeric chars}\n * Example: is-01hx5zzkbkactav9wevgemmvrz\n *\n * Use this type when:\n * - Reading/writing issue files\n * - Storing parent_id, dependencies, child_order_hints\n * - Passing IDs between internal functions\n */\ndeclare const InternalIssueIdBrand: unique symbol;\nexport type InternalIssueId = string & { [InternalIssueIdBrand]: never };\n\n/**\n * Branded type for display issue IDs ({prefix}-{short} format).\n *\n * Display IDs are shown to users and accepted as CLI input.\n * Format: {prefix}-{short} where short is typically 4 base36 chars\n * Example: tbd-a7k2, bd-100\n *\n * Use this type when:\n * - Formatting output for users\n * - Accepting user input (before resolution)\n * - Building tree views for display\n */\ndeclare const DisplayIssueIdBrand: unique symbol;\nexport type DisplayIssueId = string & { [DisplayIssueIdBrand]: never };\n\n/**\n * Cast a string to InternalIssueId after validation.\n * Use this when you've validated that a string is a valid internal ID.\n */\nexport function asInternalId(id: string): InternalIssueId {\n  return id as InternalIssueId;\n}\n\n/**\n * Cast a string to DisplayIssueId.\n * Use this when formatting an ID for display.\n */\nexport function asDisplayId(id: string): DisplayIssueId {\n  return id as DisplayIssueId;\n}\n\n/**\n * Prefix for internal IDs (ULID-based).\n * All internal IDs are formatted as: {INTERNAL_ID_PREFIX}-{ulid}\n */\nexport const INTERNAL_ID_PREFIX = 'is';\n\n/**\n * Length of internal ID prefix including the hyphen (e.g., \"is-\" = 3).\n */\nexport const INTERNAL_ID_PREFIX_LENGTH = INTERNAL_ID_PREFIX.length + 1;\n\n/**\n * Construct an internal ID from a ULID.\n *\n * @param ulidValue - The ULID (26 chars)\n * @returns Internal ID in format {prefix}-{ulid}\n */\nexport function makeInternalId(ulidValue: string): InternalIssueId {\n  return `${INTERNAL_ID_PREFIX}-${ulidValue.toLowerCase()}` as InternalIssueId;\n}\n\n/**\n * Generate a unique internal ID using ULID.\n * Format: is-{ulid} (26 lowercase alphanumeric chars)\n * Example: is-01hx5zzkbkactav9wevgemmvrz\n *\n * ULID provides:\n * - Time-ordered sorting (48-bit timestamp)\n * - 80-bit randomness (no collisions)\n * - Lexicographic sort = chronological order\n */\nexport function generateInternalId(): InternalIssueId {\n  return makeInternalId(ulid());\n}\n\n/**\n * Generate a short ID for external display.\n * Format: base36 characters (a-z, 0-9)\n * Example: a7k2\n *\n * @param length - Number of characters (default 4)\n */\nexport function generateShortId(length = 4): string {\n  const chars = '0123456789abcdefghijklmnopqrstuvwxyz';\n  let result = '';\n  const bytes = randomBytes(length);\n  for (let i = 0; i < length; i++) {\n    result += chars[bytes[i]! % 36];\n  }\n  return result;\n}\n\n// Regex pattern for validating internal IDs - built from prefix constant\nconst INTERNAL_ID_PATTERN = new RegExp(`^${INTERNAL_ID_PREFIX}-[0-9a-z]{26}$`);\n\n// Expected length of a full internal ID (prefix + hyphen + 26-char ULID)\nconst INTERNAL_ID_LENGTH = INTERNAL_ID_PREFIX_LENGTH + 26;\n\n/**\n * Validate an internal issue ID matches the ULID format.\n * Format: {prefix}-{26 lowercase alphanumeric chars}\n */\nexport function validateIssueId(id: string): boolean {\n  return INTERNAL_ID_PATTERN.test(id);\n}\n\n/**\n * Validate a short/external ID format.\n * Format: 1+ base36 characters (typically 4 for new IDs, but imports may preserve longer IDs).\n */\nexport function validateShortId(id: string): boolean {\n  return /^[0-9a-z]+$/.test(id);\n}\n\n/**\n * Check if an input looks like an internal ID (ULID-based).\n */\nexport function isInternalId(input: string): boolean {\n  const lower = input.toLowerCase();\n  // Check if it starts with the internal prefix and has correct length\n  const prefixWithHyphen = `${INTERNAL_ID_PREFIX}-`;\n  if (lower.startsWith(prefixWithHyphen) && lower.length === INTERNAL_ID_LENGTH) {\n    return INTERNAL_ID_PATTERN.test(lower);\n  }\n  return false;\n}\n\n/**\n * Check if an input looks like a short/external ID.\n * Returns true for IDs like \"a7k2\", \"bd-a7k2\", \"100\", \"tbd-100\".\n * Short IDs are 16 characters or less (ULIDs are 26 characters).\n */\nexport function isShortId(input: string): boolean {\n  const lower = input.toLowerCase();\n  // Strip prefix if present\n  const stripped = lower.replace(/^[a-z]+-/, '');\n  // Must be 1-16 alphanumeric chars (short IDs, not ULIDs which are 26 chars)\n  return /^[0-9a-z]+$/.test(stripped) && stripped.length >= 1 && stripped.length <= 16;\n}\n\n/**\n * Extract the short ID portion from an external ID.\n * Examples:\n *   \"tbd-100\" -> \"100\"\n *   \"bd-a7k2\" -> \"a7k2\"\n *   \"a7k2\" -> \"a7k2\"\n *   \"100\" -> \"100\"\n */\nexport function extractShortId(externalId: string): string {\n  return externalId.toLowerCase().replace(/^[a-z]+-/, '');\n}\n\n/**\n * Extract the prefix portion from an external ID.\n * Returns the prefix (letters before the hyphen) or null if no prefix found.\n * Examples:\n *   \"tbd-100\" -> \"tbd\"\n *   \"bd-a7k2\" -> \"bd\"\n *   \"TBD-100\" -> \"tbd\" (normalized to lowercase)\n *   \"a7k2\" -> null (no prefix)\n *   \"100\" -> null (no prefix)\n */\nexport function extractPrefix(externalId: string): string | null {\n  const match = /^([a-zA-Z]+)-/.exec(externalId);\n  return match?.[1]?.toLowerCase() ?? null;\n}\n\n/**\n * Extract the ULID portion from an internal ID.\n *\n * Internal IDs have the format: {prefix}-{ulid}\n * This function strips any prefix to return just the ULID.\n *\n * Examples:\n *   \"is-01hx5zzkbkactav9wevgemmvrz\" -> \"01hx5zzkbkactav9wevgemmvrz\"\n *   \"01hx5zzkbkactav9wevgemmvrz\" -> \"01hx5zzkbkactav9wevgemmvrz\" (no prefix)\n *\n * @param internalId - The internal ID (with or without prefix)\n * @returns The ULID portion without any prefix\n */\nexport function extractUlidFromInternalId(internalId: string): string {\n  // Strip any prefix in format {letters}- (e.g., \"is-\", \"bd-\")\n  return internalId.toLowerCase().replace(/^[a-z]+-/, '');\n}\n\n/** Prefix used in Beads for compatibility */\nconst BEADS_COMPAT_PREFIX = 'bd';\n\n/**\n * Normalize an internal issue ID.\n *\n * This function expects a full internal ID ({prefix}-{ulid}).\n * If given a short ID, it won't be able to resolve it without\n * access to the ID mapping.\n *\n * Handles:\n * - Uppercase (converts to lowercase)\n * - Ensures internal ID prefix\n * - Beads compatibility (bd- prefix)\n */\nexport function normalizeIssueId(input: string): string {\n  const lower = input.toLowerCase();\n  const internalPrefixWithHyphen = `${INTERNAL_ID_PREFIX}-`;\n  const beadsPrefixWithHyphen = `${BEADS_COMPAT_PREFIX}-`;\n\n  // If already a valid internal ID, return as-is\n  if (validateIssueId(lower)) {\n    return lower;\n  }\n\n  // If it starts with internal prefix but wrong length, might be corrupted\n  if (lower.startsWith(internalPrefixWithHyphen)) {\n    return lower; // Return as-is, let validation fail later\n  }\n\n  // If it starts with bd- (Beads compat), convert prefix\n  if (lower.startsWith(beadsPrefixWithHyphen)) {\n    const rest = lower.slice(beadsPrefixWithHyphen.length);\n    if (rest.length === 26) {\n      return makeInternalId(rest);\n    }\n    // Short ID - can't resolve without mapping\n    return lower;\n  }\n\n  // Bare ID without prefix\n  if (lower.length === 26 && /^[0-9a-z]{26}$/.test(lower)) {\n    return makeInternalId(lower);\n  }\n\n  // Can't normalize - return as-is\n  return lower;\n}\n\nimport type { IdMapping } from '../file/id-mapping.js';\n\n/**\n * Format an internal ID for display with the configured prefix.\n *\n * Uses the short ID (4 chars) from the mapping.\n * Throws an error if the mapping is missing or doesn't contain the ID.\n *\n * IMPORTANT: All user-facing output MUST use short IDs, never internal ULIDs.\n * If you see a ULID in user output, it's a bug.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - ID mapping for short ID lookup (required)\n * @param prefix - Display prefix (should come from config.display.id_prefix; defaults to 'tbd' as fallback)\n * @throws Error if mapping is missing or ID not found in mapping\n */\nexport function formatDisplayId(\n  internalId: InternalIssueId | string,\n  mapping: IdMapping,\n  prefix = 'tbd',\n): DisplayIssueId {\n  // Extract the ULID portion\n  const ulidPart = extractUlidFromInternalId(internalId);\n\n  // Get short ID from mapping\n  const shortId = mapping.ulidToShort.get(ulidPart);\n  if (!shortId) {\n    throw new Error(\n      `No short ID mapping found for internal ID: ${internalId}. ` +\n        `This is a bug - all issues must have a short ID mapping.`,\n    );\n  }\n\n  return `${prefix}-${shortId}` as DisplayIssueId;\n}\n\n/**\n * Format an ID for debug output, showing both public and internal IDs.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - ID mapping for short ID lookup\n * @param prefix - Display prefix (should come from config.display.id_prefix; defaults to 'tbd' as fallback)\n */\nexport function formatDebugId(\n  internalId: InternalIssueId | string,\n  mapping: IdMapping,\n  prefix = 'tbd',\n): string {\n  const displayId = formatDisplayId(internalId, mapping, prefix);\n  return `${displayId} (${internalId})`;\n}\n","/**\n * Natural sort utilities.\n *\n * Provides alphanumeric sorting where numeric portions are sorted numerically.\n * Similar to `sort -V` (version sort) or `sort -n` for numbers.\n *\n * Examples:\n *   [\"1\", \"2\", \"9\", \"10\", \"11\"] instead of [\"1\", \"10\", \"11\", \"2\", \"9\"]\n *   [\"a1\", \"a2\", \"a10\"] instead of [\"a1\", \"a10\", \"a2\"]\n *   [\"file1.txt\", \"file2.txt\", \"file10.txt\"] instead of [\"file1.txt\", \"file10.txt\", \"file2.txt\"]\n */\n\n/**\n * Split a string into alternating runs of digits and non-digits.\n * @param str - The string to split\n * @returns Array of [isNumeric, value] tuples\n */\nfunction splitIntoChunks(str: string): [boolean, string][] {\n  const chunks: [boolean, string][] = [];\n  let current = '';\n  let currentIsNumeric: boolean | null = null;\n\n  for (const char of str) {\n    const isDigit = char >= '0' && char <= '9';\n\n    if (currentIsNumeric === null) {\n      // First character\n      currentIsNumeric = isDigit;\n      current = char;\n    } else if (isDigit === currentIsNumeric) {\n      // Same type, continue accumulating\n      current += char;\n    } else {\n      // Type changed, push current chunk and start new one\n      chunks.push([currentIsNumeric, current]);\n      currentIsNumeric = isDigit;\n      current = char;\n    }\n  }\n\n  // Push final chunk\n  if (current) {\n    chunks.push([currentIsNumeric!, current]);\n  }\n\n  return chunks;\n}\n\n/**\n * Compare two strings using natural (alphanumeric) ordering.\n *\n * Numeric portions are compared numerically, non-numeric portions are\n * compared lexicographically (case-insensitive). Numbers sort before letters\n * when they appear at the same position in mixed comparisons, matching\n * the behavior of `sort -V` (version sort).\n *\n * @param a - First string\n * @param b - Second string\n * @returns Negative if a < b, positive if a > b, zero if equal\n */\nexport function naturalCompare(a: string, b: string): number {\n  // Handle empty strings\n  if (!a && !b) return 0;\n  if (!a) return -1;\n  if (!b) return 1;\n\n  const chunksA = splitIntoChunks(a);\n  const chunksB = splitIntoChunks(b);\n\n  const minLen = Math.min(chunksA.length, chunksB.length);\n\n  for (let i = 0; i < minLen; i++) {\n    const [isNumericA, valueA] = chunksA[i]!;\n    const [isNumericB, valueB] = chunksB[i]!;\n\n    if (isNumericA && isNumericB) {\n      // Both are numeric - compare as numbers\n      const numA = parseInt(valueA, 10);\n      const numB = parseInt(valueB, 10);\n      if (numA !== numB) {\n        return numA - numB;\n      }\n      // If numerically equal but different strings (e.g., \"01\" vs \"1\"),\n      // prefer shorter (fewer leading zeros)\n      if (valueA.length !== valueB.length) {\n        return valueA.length - valueB.length;\n      }\n    } else if (!isNumericA && !isNumericB) {\n      // Both are non-numeric - compare lexicographically (case-insensitive)\n      const lowerA = valueA.toLowerCase();\n      const lowerB = valueB.toLowerCase();\n      if (lowerA !== lowerB) {\n        return lowerA.localeCompare(lowerB);\n      }\n      // Same when lowercased - they're equal for sorting purposes\n    } else {\n      // Mixed: numeric comes before non-numeric\n      // (so \"1\" comes before \"a\" at the same position)\n      // This matches `sort -V` behavior\n      return isNumericA ? -1 : 1;\n    }\n  }\n\n  // All compared chunks are equal, shorter string comes first\n  return chunksA.length - chunksB.length;\n}\n\n/**\n * Sort an array of strings using natural (alphanumeric) ordering.\n *\n * @param arr - Array to sort\n * @returns New sorted array (does not mutate original)\n */\nexport function naturalSort(arr: readonly string[]): string[] {\n  return [...arr].sort(naturalCompare);\n}\n\n/**\n * Sort an array of objects by a string key using natural ordering.\n *\n * @param arr - Array to sort\n * @param keyFn - Function to extract the sort key from each element\n * @returns New sorted array (does not mutate original)\n */\nexport function naturalSortBy<T>(arr: readonly T[], keyFn: (item: T) => string): T[] {\n  return [...arr].sort((a, b) => naturalCompare(keyFn(a), keyFn(b)));\n}\n","/**\n * ID mapping management for short public IDs.\n *\n * Maps 4-char base36 short IDs to 26-char ULIDs.\n * Stored in .tbd/data-sync/mappings/ids.yml\n *\n * See: tbd-design.md §2.5 ID Generation\n */\n\nimport { readFile, mkdir } from 'node:fs/promises';\nimport { join, dirname } from 'node:path';\nimport { writeFile } from 'atomically';\n\nimport {\n  parseYamlToleratingDuplicateKeys,\n  stringifyYaml,\n  hasMergeConflictMarkers,\n} from '../utils/yaml-utils.js';\nimport { withLockfile } from '../utils/lockfile.js';\n\nimport {\n  generateShortId,\n  extractUlidFromInternalId,\n  makeInternalId,\n  isInternalId,\n  extractShortId,\n  asInternalId,\n  type InternalIssueId,\n} from '../lib/ids.js';\nimport { naturalSort } from '../lib/sort.js';\nimport { IdMappingYamlSchema } from '../lib/schemas.js';\n\n/**\n * ID mapping from short ID to ULID.\n * Format in ids.yml:\n *   a7k2: 01hx5zzkbkactav9wevgemmvrz\n *   b3m9: 01hx5zzkbkbctav9wevgemmvrz\n */\nexport interface IdMapping {\n  shortToUlid: Map<string, string>;\n  ulidToShort: Map<string, string>;\n}\n\n/**\n * Get the path to the ids.yml mapping file.\n */\nfunction getMappingPath(baseDir: string): string {\n  return join(baseDir, 'mappings', 'ids.yml');\n}\n\n/**\n * Load the ID mapping from disk.\n * Returns empty mapping if file doesn't exist.\n */\nexport async function loadIdMapping(baseDir: string): Promise<IdMapping> {\n  const filePath = getMappingPath(baseDir);\n\n  let content: string;\n  try {\n    content = await readFile(filePath, 'utf-8');\n  } catch {\n    // File doesn't exist - return empty mapping\n    return {\n      shortToUlid: new Map(),\n      ulidToShort: new Map(),\n    };\n  }\n\n  // Parse tolerating duplicate keys — this handles the case where a git merge\n  // conflict resolution kept entries from both sides, creating duplicate YAML keys.\n  // Without this, the yaml parser throws \"Map keys must be unique\".\n  const { data: rawData, duplicateKeys } = parseYamlToleratingDuplicateKeys<unknown>(\n    content,\n    filePath,\n  );\n  const data = rawData ?? {};\n\n  if (duplicateKeys.length > 0) {\n    console.warn(\n      `Warning: ${filePath} contains ${duplicateKeys.length} duplicate key(s): ${duplicateKeys.join(', ')}. ` +\n        `This usually happens after a git merge conflict resolution. ` +\n        `The file will be auto-fixed on next save.`,\n    );\n  }\n\n  // Validate with Zod schema - ensures all keys are valid short IDs and values are ULIDs\n  const parseResult = IdMappingYamlSchema.safeParse(data);\n  if (!parseResult.success) {\n    throw new Error(`Invalid ID mapping format in ${filePath}: ${parseResult.error.message}`);\n  }\n  const validData = parseResult.data;\n\n  const shortToUlid = new Map<string, string>();\n  const ulidToShort = new Map<string, string>();\n\n  for (const [shortId, ulid] of Object.entries(validData)) {\n    shortToUlid.set(shortId, ulid);\n    ulidToShort.set(ulid, shortId);\n  }\n\n  return { shortToUlid, ulidToShort };\n}\n\n/**\n * Save the ID mapping to disk with mutual exclusion.\n *\n * Uses a lockfile to serialize concurrent writers, then performs read-merge-write\n * inside the lock. This prevents the lost-update problem when multiple `tbd create`\n * commands run in parallel.\n *\n * The merge is safe because ID mappings are append-only — entries are never\n * intentionally removed. If the lock cannot be acquired within the timeout,\n * a LockAcquisitionError is thrown rather than proceeding without protection.\n */\nexport async function saveIdMapping(baseDir: string, mapping: IdMapping): Promise<void> {\n  const filePath = getMappingPath(baseDir);\n\n  // Ensure directory exists\n  await mkdir(dirname(filePath), { recursive: true });\n\n  await withLockfile(filePath + '.lock', async () => {\n    // Inside the lock: read current on-disk state, merge with our in-memory\n    // mapping, and write the result. Our entries take precedence for short ID\n    // conflicts (extremely unlikely with random 4-char base36 IDs).\n    let merged = mapping;\n    let onDiskSize = 0;\n    try {\n      const onDisk = await loadIdMappingRaw(filePath);\n      onDiskSize = onDisk.shortToUlid.size;\n      if (onDiskSize > 0) {\n        merged = mergeIdMappings(mapping, onDisk);\n      }\n    } catch {\n      // File doesn't exist or is unreadable — proceed with our mapping only\n    }\n\n    // Safety check: ID mappings are append-only. If the merged result has fewer\n    // entries than what's on disk, something went wrong. Refuse to write so the\n    // caller can investigate rather than silently destroying entries.\n    if (merged.shortToUlid.size < onDiskSize) {\n      throw new Error(\n        `Refusing to save ID mapping: would lose ${onDiskSize - merged.shortToUlid.size} entries ` +\n          `(on-disk: ${onDiskSize}, proposed: ${merged.shortToUlid.size}). ` +\n          `ID mappings are append-only — this indicates a bug.`,\n      );\n    }\n\n    const data: Record<string, string> = {};\n    const sortedKeys = naturalSort(Array.from(merged.shortToUlid.keys()));\n    for (const key of sortedKeys) {\n      data[key] = merged.shortToUlid.get(key)!;\n    }\n\n    const content = stringifyYaml(data);\n    await writeFile(filePath, content);\n  });\n}\n\n/**\n * Load an ID mapping directly from a file path (internal helper for save merging).\n * Separated from loadIdMapping to avoid coupling the save path to baseDir resolution.\n */\nasync function loadIdMappingRaw(filePath: string): Promise<IdMapping> {\n  const content = await readFile(filePath, 'utf-8');\n\n  const { data: rawData } = parseYamlToleratingDuplicateKeys<unknown>(content, filePath);\n  const data = rawData ?? {};\n\n  const parseResult = IdMappingYamlSchema.safeParse(data);\n  if (!parseResult.success) {\n    throw new Error(`Invalid ID mapping format in ${filePath}: ${parseResult.error.message}`);\n  }\n  const validData = parseResult.data;\n\n  const shortToUlid = new Map<string, string>();\n  const ulidToShort = new Map<string, string>();\n\n  for (const [shortId, ulid] of Object.entries(validData)) {\n    shortToUlid.set(shortId, ulid);\n    ulidToShort.set(ulid, shortId);\n  }\n\n  return { shortToUlid, ulidToShort };\n}\n\n/**\n * Calculate the optimal short ID length based on existing ID count.\n *\n * At 50K issues, switches from 4-char to 5-char IDs to keep\n * collision probability low (~3% per attempt with 4 chars at 50K).\n *\n * With 10 retries per length, actual failure probability is astronomically low.\n */\nexport function calculateOptimalLength(existingCount: number): number {\n  return existingCount < 50_000 ? 4 : 5;\n}\n\n/**\n * Generate a unique short ID that doesn't collide with existing ones.\n *\n * Calculates optimal length (4 or 5 chars) based on existing ID count,\n * then retries with the next length if collisions occur.\n *\n * @returns The new short ID\n * @throws If unable to generate a unique ID after max attempts\n */\nexport function generateUniqueShortId(mapping: IdMapping): string {\n  const ATTEMPTS_PER_LENGTH = 10;\n  const existingCount = mapping.shortToUlid.size;\n  const optimalLength = calculateOptimalLength(existingCount);\n\n  // Try optimal length first, then fall back to longer if needed\n  for (const length of [optimalLength, optimalLength + 1]) {\n    for (let attempt = 0; attempt < ATTEMPTS_PER_LENGTH; attempt++) {\n      const shortId = generateShortId(length);\n      if (!mapping.shortToUlid.has(shortId)) {\n        return shortId;\n      }\n    }\n  }\n\n  throw new Error(\n    `Failed to generate unique short ID after 20 attempts with ${existingCount} existing IDs. ` +\n      `This should be extremely rare - please report if you see this error.`,\n  );\n}\n\n/**\n * Register a new ID mapping.\n * @param ulid - The ULID (without is- prefix)\n * @param shortId - The short ID (4 chars)\n */\nexport function addIdMapping(mapping: IdMapping, ulid: string, shortId: string): void {\n  mapping.shortToUlid.set(shortId, ulid);\n  mapping.ulidToShort.set(ulid, shortId);\n}\n\n/**\n * Get the short ID for a ULID.\n * @param ulid - The ULID (without is- prefix)\n * @returns The short ID, or undefined if not found\n */\nexport function getShortId(mapping: IdMapping, ulid: string): string | undefined {\n  return mapping.ulidToShort.get(ulid);\n}\n\n/**\n * Get the ULID for a short ID.\n * @param shortId - The short ID\n * @returns The ULID (without is- prefix), or undefined if not found\n */\nexport function getUlid(mapping: IdMapping, shortId: string): string | undefined {\n  return mapping.shortToUlid.get(shortId);\n}\n\n/**\n * Check if a short ID exists in the mapping.\n */\nexport function hasShortId(mapping: IdMapping, shortId: string): boolean {\n  return mapping.shortToUlid.has(shortId);\n}\n\n/**\n * Create a short ID mapping for a new internal ID.\n * Generates a unique short ID and registers it in the mapping.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - The ID mapping to update\n * @returns The generated short ID\n */\nexport function createShortIdMapping(internalId: string, mapping: IdMapping): string {\n  // Extract ULID from internal ID (remove prefix)\n  const ulid = extractUlidFromInternalId(internalId);\n\n  // Check if already mapped\n  const existing = mapping.ulidToShort.get(ulid);\n  if (existing) {\n    return existing;\n  }\n\n  // Generate unique short ID\n  const shortId = generateUniqueShortId(mapping);\n\n  // Register mapping\n  addIdMapping(mapping, ulid, shortId);\n\n  return shortId;\n}\n\n/**\n * Resolve any ID input to an internal ID ({prefix}-{ulid}).\n *\n * Handles:\n * - Internal IDs: {prefix}-{ulid} -> {prefix}-{ulid}\n * - Short IDs: a7k2 -> {prefix}-{ulid from mapping}\n * - Prefixed short IDs: bd-a7k2 -> {prefix}-{ulid from mapping}\n *\n * @param input - The ID input (short ID, prefixed short ID, or internal ID)\n * @param mapping - The ID mapping for short ID resolution\n * @returns The internal ID ({prefix}-{ulid})\n * @throws If the short ID is not found in the mapping\n */\nexport function resolveToInternalId(input: string, mapping: IdMapping): InternalIssueId {\n  const lower = input.toLowerCase();\n\n  // If it's already an internal ID, return it\n  if (isInternalId(lower)) {\n    return asInternalId(lower);\n  }\n\n  // Extract the short ID portion (strips any prefix like \"bd-\" or \"is-\")\n  const shortId = extractShortId(lower);\n\n  // If it's a full ULID (26 chars), it might be a bare internal ID\n  if (shortId.length === 26 && /^[0-9a-z]{26}$/.test(shortId)) {\n    return makeInternalId(shortId);\n  }\n\n  // Must be a short ID - look it up in the mapping\n  const ulid = mapping.shortToUlid.get(shortId);\n  if (!ulid) {\n    throw new Error(`Unknown issue ID: ${input}. ` + `Short ID \"${shortId}\" not found in mapping.`);\n  }\n\n  return makeInternalId(ulid);\n}\n\n/**\n * Parse an ID mapping from raw YAML content.\n * Used for loading mappings from git show output during conflict resolution.\n *\n * @throws MergeConflictError if content contains merge conflict markers\n */\nexport function parseIdMappingFromYaml(content: string): IdMapping {\n  // Parse tolerating duplicate keys — handles post-merge-conflict duplicates\n  const { data: rawData, duplicateKeys } = parseYamlToleratingDuplicateKeys<unknown>(content);\n  const data = rawData ?? {};\n\n  if (duplicateKeys.length > 0) {\n    console.warn(\n      `Warning: ID mapping YAML contains ${duplicateKeys.length} duplicate key(s): ${duplicateKeys.join(', ')}. ` +\n        `Duplicates will be auto-resolved.`,\n    );\n  }\n\n  // Validate with Zod schema\n  const parseResult = IdMappingYamlSchema.safeParse(data);\n  if (!parseResult.success) {\n    throw new Error(`Invalid ID mapping format: ${parseResult.error.message}`);\n  }\n  const validData = parseResult.data;\n\n  const shortToUlid = new Map<string, string>();\n  const ulidToShort = new Map<string, string>();\n\n  for (const [shortId, ulid] of Object.entries(validData)) {\n    shortToUlid.set(shortId, ulid);\n    ulidToShort.set(ulid, shortId);\n  }\n\n  return { shortToUlid, ulidToShort };\n}\n\n/**\n * Ensure all given internal IDs have short ID mappings.\n * Creates missing mappings for any IDs without entries.\n *\n * This repairs state after git merges that may add issue files\n * without corresponding mapping entries (e.g., when outbox issues\n * are merged from a feature branch but ids.yml doesn't include them).\n *\n * When a `historicalMapping` is provided, the function will try to recover\n * the original short ID from that mapping before generating a new random one.\n * This preserves ID stability so that existing references (in docs, PRs,\n * conversations) remain valid.\n *\n * @param internalIds - Array of internal IDs (is-{ulid}) to reconcile\n * @param mapping - The ID mapping to update (mutated in-place)\n * @param historicalMapping - Optional mapping from prior state (e.g., git history) to recover original short IDs\n * @returns Object with `created` (IDs that got new random short IDs) and `recovered` (IDs restored from history)\n */\nexport function reconcileMappings(\n  internalIds: string[],\n  mapping: IdMapping,\n  historicalMapping?: IdMapping,\n): { created: string[]; recovered: string[] } {\n  const created: string[] = [];\n  const recovered: string[] = [];\n\n  for (const id of internalIds) {\n    const ulid = extractUlidFromInternalId(id);\n    if (mapping.ulidToShort.has(ulid)) {\n      continue; // Already has a mapping\n    }\n\n    // Try to recover original short ID from historical mapping\n    const historicalShortId = historicalMapping?.ulidToShort.get(ulid);\n    if (historicalShortId && !mapping.shortToUlid.has(historicalShortId)) {\n      // Recovered: restore the original short ID\n      addIdMapping(mapping, ulid, historicalShortId);\n      recovered.push(id);\n    } else {\n      // No history available or short ID conflicts — generate new random one\n      createShortIdMapping(id, mapping);\n      created.push(id);\n    }\n  }\n\n  return { created, recovered };\n}\n\n/**\n * Merge two ID mappings by combining all entries from both.\n * ID mappings are always additive (new IDs are only added, never removed),\n * so merging simply unions all key-value pairs.\n *\n * If the same short ID maps to different ULIDs in each mapping (a conflict),\n * the local mapping takes precedence (caller should log a warning).\n *\n * @param local - The local ID mapping\n * @param remote - The remote ID mapping\n * @returns Merged mapping with all entries from both\n */\nexport function mergeIdMappings(local: IdMapping, remote: IdMapping): IdMapping {\n  const merged: IdMapping = {\n    shortToUlid: new Map(local.shortToUlid),\n    ulidToShort: new Map(local.ulidToShort),\n  };\n\n  // Add all remote entries that don't conflict\n  for (const [shortId, ulid] of remote.shortToUlid) {\n    if (!merged.shortToUlid.has(shortId)) {\n      merged.shortToUlid.set(shortId, ulid);\n      merged.ulidToShort.set(ulid, shortId);\n    }\n    // If shortId already exists with different ulid, keep local (conflict resolution)\n  }\n\n  // Also check for ULIDs that exist in remote but not in local\n  // (different short ID for same ULID - shouldn't happen but handle gracefully)\n  for (const [ulid, shortId] of remote.ulidToShort) {\n    if (!merged.ulidToShort.has(ulid) && !merged.shortToUlid.has(shortId)) {\n      merged.shortToUlid.set(shortId, ulid);\n      merged.ulidToShort.set(ulid, shortId);\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Resolve merge conflicts in ids.yml content by extracting both sides and merging.\n *\n * ids.yml is a sorted key-value YAML map where entries are append-only.\n * The most common merge conflict is both sides adding non-overlapping keys,\n * which is trivially auto-resolvable by keeping all entries from both sides.\n *\n * @param content - Raw file content that may contain git merge conflict markers\n * @returns Merged IdMapping with entries from both sides\n */\nexport function resolveIdMappingConflicts(content: string): IdMapping {\n  if (!hasMergeConflictMarkers(content)) {\n    return parseIdMappingFromYaml(content);\n  }\n\n  const lines = content.split('\\n');\n  const oursLines: string[] = [];\n  const theirsLines: string[] = [];\n  let inConflict: 'none' | 'ours' | 'theirs' = 'none';\n\n  for (const line of lines) {\n    if (line.startsWith('<<<<<<< ')) {\n      inConflict = 'ours';\n      continue;\n    }\n    if (line === '=======' && inConflict === 'ours') {\n      inConflict = 'theirs';\n      continue;\n    }\n    if (line.startsWith('>>>>>>> ') && inConflict === 'theirs') {\n      inConflict = 'none';\n      continue;\n    }\n\n    if (inConflict === 'none') {\n      oursLines.push(line);\n      theirsLines.push(line);\n    } else if (inConflict === 'ours') {\n      oursLines.push(line);\n    } else {\n      theirsLines.push(line);\n    }\n  }\n\n  const oursMapping = parseIdMappingFromYaml(oursLines.join('\\n'));\n  const theirsMapping = parseIdMappingFromYaml(theirsLines.join('\\n'));\n\n  return mergeIdMappings(oursMapping, theirsMapping);\n}\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -226,6 +226,10 @@ declare const GitBranchName: z.ZodString;
  * Prevents shell injection in git commands.
  */
 declare const GitRemoteName: z.ZodString;
+/**
+ * Canonical local storage backend for issue sync machinery.
+ */
+declare const SyncStorage: z.ZodEnum<["git-common-dir-v1"]>;
 /**
  * Doc cache configuration - maps destination paths to source locations.
  *
@@ -300,12 +304,15 @@ declare const ConfigSchema: z.ZodObject<{
   sync: z.ZodDefault<z.ZodObject<{
     branch: z.ZodDefault<z.ZodString>;
     remote: z.ZodDefault<z.ZodString>;
+    storage: z.ZodDefault<z.ZodEnum<["git-common-dir-v1"]>>;
   }, "strip", z.ZodTypeAny, {
     branch: string;
     remote: string;
+    storage: "git-common-dir-v1";
   }, {
     branch?: string | undefined;
     remote?: string | undefined;
+    storage?: "git-common-dir-v1" | undefined;
   }>>;
   display: z.ZodObject<{
     id_prefix: z.ZodString;
@@ -371,6 +378,7 @@ declare const ConfigSchema: z.ZodObject<{
   sync: {
     branch: string;
     remote: string;
+    storage: "git-common-dir-v1";
   };
   display: {
     id_prefix: string;
@@ -393,6 +401,7 @@ declare const ConfigSchema: z.ZodObject<{
   sync?: {
     branch?: string | undefined;
     remote?: string | undefined;
+    storage?: "git-common-dir-v1" | undefined;
   } | undefined;
   settings?: {
     auto_sync?: boolean | undefined;
@@ -404,6 +413,41 @@ declare const ConfigSchema: z.ZodObject<{
     lookup_path?: string[] | undefined;
   } | undefined;
 }>;
+/**
+ * Local layout metadata stored in $GIT_COMMON_DIR/tbd/layout.yml.
+ *
+ * This uses the same tbd_format IDs as .tbd/config.yml so local checkout config
+ * and Git common-dir machinery advance together during layout migrations.
+ */
+declare const CommonDirLayoutSchema: z.ZodObject<{
+  tbd_format: z.ZodString;
+  sync_storage: z.ZodDefault<z.ZodEnum<["git-common-dir-v1"]>>;
+  data_sync_worktree: z.ZodDefault<z.ZodLiteral<"data-sync-worktree">>;
+  lock_profile: z.ZodDefault<z.ZodLiteral<"data-sync-v1">>;
+  created_at: z.ZodString;
+  updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  created_at: string;
+  updated_at: string;
+  tbd_format: string;
+  sync_storage: "git-common-dir-v1";
+  data_sync_worktree: "data-sync-worktree";
+  lock_profile: "data-sync-v1";
+}, {
+  created_at: string;
+  updated_at: string;
+  tbd_format: string;
+  sync_storage?: "git-common-dir-v1" | undefined;
+  data_sync_worktree?: "data-sync-worktree" | undefined;
+  lock_profile?: "data-sync-v1" | undefined;
+}>;
+/**
+ * Current schema version for synced payloads on the tbd-sync branch.
+ *
+ * This is intentionally separate from tbd_format, which tracks local checkout
+ * and Git common-dir layout compatibility.
+ */
+declare const DATA_SYNC_SCHEMA_VERSION = 1;
 /**
  * Shared metadata stored in .tbd/data-sync/meta.yml
  */
@@ -502,6 +546,10 @@ declare const ISSUE_FIELD_ORDER: readonly ["type", "id", "title", "kind", "statu
  * Canonical field order for config YAML.
  */
 declare const CONFIG_FIELD_ORDER: readonly ["tbd_format", "tbd_version", "display", "sync", "settings", "docs_cache"];
+/**
+ * Canonical field order for $GIT_COMMON_DIR/tbd/layout.yml.
+ */
+declare const COMMON_DIR_LAYOUT_FIELD_ORDER: readonly ["tbd_format", "sync_storage", "data_sync_worktree", "lock_profile", "created_at", "updated_at"];
 /**
  * Canonical field order for attic entry YAML.
  */
@@ -540,6 +588,10 @@ type DependencyType = z.infer<typeof Dependency>;
  * Project configuration.
  */
 type Config = z.infer<typeof ConfigSchema>;
+/**
+ * Git common-dir local layout metadata.
+ */
+type CommonDirLayout = z.infer<typeof CommonDirLayoutSchema>;
 /**
  * Shared metadata.
  */
@@ -658,5 +710,5 @@ declare function serializeIssue(issue: Issue): string;
  */
 declare const VERSION: string;
 //#endregion
-export { ATTIC_ENTRY_FIELD_ORDER, AtticEntry, AtticEntrySchema, BaseEntity, CONFIG_FIELD_ORDER, Config, ConfigSchema, CreateIssueOptions, Dependency, DependencyRelationType, DependencyType, DocCacheConfigSchema, DocSection, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, ISSUE_BODY_MAX_LENGTH, ISSUE_FIELD_ORDER, ISSUE_TITLE_MAX_LENGTH, IdMappingYamlSchema, Issue, IssueId, IssueKind, IssueKindType, IssueSchema, IssueStatus, IssueStatusType, IssueTitle, LOCAL_STATE_FIELD_ORDER, ListIssuesOptions, LocalState, LocalStateSchema, META_FIELD_ORDER, Meta, MetaSchema, OperationLogger, Priority, PriorityType, SearchIssuesOptions, ShortId, Timestamp, Ulid, UpdateIssueOptions, VERSION, Version, noopLogger, parseIssue, serializeIssue };
+export { ATTIC_ENTRY_FIELD_ORDER, AtticEntry, AtticEntrySchema, BaseEntity, COMMON_DIR_LAYOUT_FIELD_ORDER, CONFIG_FIELD_ORDER, CommonDirLayout, CommonDirLayoutSchema, Config, ConfigSchema, CreateIssueOptions, DATA_SYNC_SCHEMA_VERSION, Dependency, DependencyRelationType, DependencyType, DocCacheConfigSchema, DocSection, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, ISSUE_BODY_MAX_LENGTH, ISSUE_FIELD_ORDER, ISSUE_TITLE_MAX_LENGTH, IdMappingYamlSchema, Issue, IssueId, IssueKind, IssueKindType, IssueSchema, IssueStatus, IssueStatusType, IssueTitle, LOCAL_STATE_FIELD_ORDER, ListIssuesOptions, LocalState, LocalStateSchema, META_FIELD_ORDER, Meta, MetaSchema, OperationLogger, Priority, PriorityType, SearchIssuesOptions, ShortId, SyncStorage, Timestamp, Ulid, UpdateIssueOptions, VERSION, Version, noopLogger, parseIssue, serializeIssue };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as Ulid, C as LOCAL_STATE_FIELD_ORDER, D as Priority, E as MetaSchema, O as ShortId, S as IssueTitle, T as META_FIELD_ORDER, _ as IdMappingYamlSchema, a as ConfigSchema, b as IssueSchema, c as DocCacheConfigSchema, d as ExternalIssueIdInput, f as GitBranchName, g as ISSUE_TITLE_MAX_LENGTH, h as ISSUE_FIELD_ORDER, i as CONFIG_FIELD_ORDER, j as Version, k as Timestamp, l as DocsCacheSchema, m as ISSUE_BODY_MAX_LENGTH, n as AtticEntrySchema, o as Dependency, p as GitRemoteName, r as BaseEntity, s as DependencyRelationType, t as ATTIC_ENTRY_FIELD_ORDER, u as EntityType, v as IssueId, w as LocalStateSchema, x as IssueStatus, y as IssueKind } from "./schemas-C8mOQykE.mjs";
-import { c as noopLogger, i as serializeIssue, n as parseIssue, t as VERSION } from "./src-CJyVkC3V.mjs";
+import { A as Priority, C as IssueSchema, D as LocalStateSchema, E as LOCAL_STATE_FIELD_ORDER, F as Version, M as SyncStorage, N as Timestamp, O as META_FIELD_ORDER, P as Ulid, S as IssueKind, T as IssueTitle, _ as ISSUE_BODY_MAX_LENGTH, a as CONFIG_FIELD_ORDER, b as IdMappingYamlSchema, c as DATA_SYNC_SCHEMA_VERSION, d as DocCacheConfigSchema, f as DocsCacheSchema, g as GitRemoteName, h as GitBranchName, i as COMMON_DIR_LAYOUT_FIELD_ORDER, j as ShortId, k as MetaSchema, l as Dependency, m as ExternalIssueIdInput, n as AtticEntrySchema, o as CommonDirLayoutSchema, p as EntityType, r as BaseEntity, s as ConfigSchema, t as ATTIC_ENTRY_FIELD_ORDER, u as DependencyRelationType, v as ISSUE_FIELD_ORDER, w as IssueStatus, x as IssueId, y as ISSUE_TITLE_MAX_LENGTH } from "./schemas-f0EcuAVu.mjs";
+import { c as noopLogger, i as serializeIssue, n as parseIssue, t as VERSION } from "./src-rIE4xSVs.mjs";
 
-export { ATTIC_ENTRY_FIELD_ORDER, AtticEntrySchema, BaseEntity, CONFIG_FIELD_ORDER, ConfigSchema, Dependency, DependencyRelationType, DocCacheConfigSchema, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, ISSUE_BODY_MAX_LENGTH, ISSUE_FIELD_ORDER, ISSUE_TITLE_MAX_LENGTH, IdMappingYamlSchema, IssueId, IssueKind, IssueSchema, IssueStatus, IssueTitle, LOCAL_STATE_FIELD_ORDER, LocalStateSchema, META_FIELD_ORDER, MetaSchema, Priority, ShortId, Timestamp, Ulid, VERSION, Version, noopLogger, parseIssue, serializeIssue };
+export { ATTIC_ENTRY_FIELD_ORDER, AtticEntrySchema, BaseEntity, COMMON_DIR_LAYOUT_FIELD_ORDER, CONFIG_FIELD_ORDER, CommonDirLayoutSchema, ConfigSchema, DATA_SYNC_SCHEMA_VERSION, Dependency, DependencyRelationType, DocCacheConfigSchema, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, ISSUE_BODY_MAX_LENGTH, ISSUE_FIELD_ORDER, ISSUE_TITLE_MAX_LENGTH, IdMappingYamlSchema, IssueId, IssueKind, IssueSchema, IssueStatus, IssueTitle, LOCAL_STATE_FIELD_ORDER, LocalStateSchema, META_FIELD_ORDER, MetaSchema, Priority, ShortId, SyncStorage, Timestamp, Ulid, VERSION, Version, noopLogger, parseIssue, serializeIssue };

package/dist/{schemas-C8mOQykE.mjs → schemas-f0EcuAVu.mjs}

@@ -156,6 +156,10 @@ const GitBranchName = z.string().min(1).max(255).regex(/^[a-zA-Z0-9._/-]+$/, "In
 */
 const GitRemoteName = z.string().min(1).max(255).regex(/^[a-zA-Z0-9._-]+$/, "Invalid remote name: only alphanumeric, dots, underscores, and hyphens allowed");
 /**
+* Canonical local storage backend for issue sync machinery.
+*/
+const SyncStorage = z.enum(["git-common-dir-v1"]);
+/**
 * Doc cache configuration - maps destination paths to source locations.
 *
 * Keys are destination paths relative to .tbd/docs/ (e.g., "shortcuts/standard/code-review-and-commit.md")
@@ -206,7 +210,8 @@ const ConfigSchema = z.object({
 	tbd_version: z.string(),
 	sync: z.object({
 		branch: GitBranchName.default("tbd-sync"),
-		remote: GitRemoteName.default("origin")
+		remote: GitRemoteName.default("origin"),
+		storage: SyncStorage.default("git-common-dir-v1")
 	}).default({}),
 	display: z.object({ id_prefix: z.string().min(1).max(20) }),
 	settings: z.object({
@@ -217,6 +222,27 @@ const ConfigSchema = z.object({
 	docs_cache: DocsCacheSchema.optional()
 });
 /**
+* Local layout metadata stored in $GIT_COMMON_DIR/tbd/layout.yml.
+*
+* This uses the same tbd_format IDs as .tbd/config.yml so local checkout config
+* and Git common-dir machinery advance together during layout migrations.
+*/
+const CommonDirLayoutSchema = z.object({
+	tbd_format: z.string(),
+	sync_storage: SyncStorage.default("git-common-dir-v1"),
+	data_sync_worktree: z.literal("data-sync-worktree").default("data-sync-worktree"),
+	lock_profile: z.literal("data-sync-v1").default("data-sync-v1"),
+	created_at: Timestamp,
+	updated_at: Timestamp
+});
+/**
+* Current schema version for synced payloads on the tbd-sync branch.
+*
+* This is intentionally separate from tbd_format, which tracks local checkout
+* and Git common-dir layout compatibility.
+*/
+const DATA_SYNC_SCHEMA_VERSION = 1;
+/**
 * Shared metadata stored in .tbd/data-sync/meta.yml
 */
 const MetaSchema = z.object({
@@ -294,6 +320,17 @@ const CONFIG_FIELD_ORDER = [
 	"docs_cache"
 ];
 /**
+* Canonical field order for $GIT_COMMON_DIR/tbd/layout.yml.
+*/
+const COMMON_DIR_LAYOUT_FIELD_ORDER = [
+	"tbd_format",
+	"sync_storage",
+	"data_sync_worktree",
+	"lock_profile",
+	"created_at",
+	"updated_at"
+];
+/**
 * Canonical field order for attic entry YAML.
 */
 const ATTIC_ENTRY_FIELD_ORDER = [
@@ -319,5 +356,5 @@ const LOCAL_STATE_FIELD_ORDER = [
 ];
 
 //#endregion
-export { Ulid as A, LOCAL_STATE_FIELD_ORDER as C, Priority as D, MetaSchema as E, ShortId as O, IssueTitle as S, META_FIELD_ORDER as T, IdMappingYamlSchema as _, ConfigSchema as a, IssueSchema as b, DocCacheConfigSchema as c, ExternalIssueIdInput as d, GitBranchName as f, ISSUE_TITLE_MAX_LENGTH as g, ISSUE_FIELD_ORDER as h, CONFIG_FIELD_ORDER as i, Version as j, Timestamp as k, DocsCacheSchema as l, ISSUE_BODY_MAX_LENGTH as m, AtticEntrySchema as n, Dependency as o, GitRemoteName as p, BaseEntity as r, DependencyRelationType as s, ATTIC_ENTRY_FIELD_ORDER as t, EntityType as u, IssueId as v, LocalStateSchema as w, IssueStatus as x, IssueKind as y };
-//# sourceMappingURL=schemas-C8mOQykE.mjs.map
+export { Priority as A, IssueSchema as C, LocalStateSchema as D, LOCAL_STATE_FIELD_ORDER as E, Version as F, SyncStorage as M, Timestamp as N, META_FIELD_ORDER as O, Ulid as P, IssueKind as S, IssueTitle as T, ISSUE_BODY_MAX_LENGTH as _, CONFIG_FIELD_ORDER as a, IdMappingYamlSchema as b, DATA_SYNC_SCHEMA_VERSION as c, DocCacheConfigSchema as d, DocsCacheSchema as f, GitRemoteName as g, GitBranchName as h, COMMON_DIR_LAYOUT_FIELD_ORDER as i, ShortId as j, MetaSchema as k, Dependency as l, ExternalIssueIdInput as m, AtticEntrySchema as n, CommonDirLayoutSchema as o, EntityType as p, BaseEntity as r, ConfigSchema as s, ATTIC_ENTRY_FIELD_ORDER as t, DependencyRelationType as u, ISSUE_FIELD_ORDER as v, IssueStatus as w, IssueId as x, ISSUE_TITLE_MAX_LENGTH as y };
+//# sourceMappingURL=schemas-f0EcuAVu.mjs.map