@akagilnc/pi-workflow-roles 0.1.1941 → 0.1.2004

package/src/taishi-entry.ts

@@ -0,0 +1,429 @@
+/**
+ * 太史 sole entry (ADR 0068 / PRD #298).
+ * Deterministic analysis seat: read ledger records, write sibling metrics pages.
+ * A1/A2: issue-mode typed input; C1 adds sweep mode on this same seam.
+ * A2: scan retains typed per-run facts; page builder folds registered metric families.
+ * C1: sweep = merged PR list + LOC → backfill issue pages + maintain library index.
+ * C2: cohort = two issue-number groups → join library index → contrast query output.
+ * C3: model-groups = caller issue set → scan union → per-leg model aggregate.
+ * #338: retrieval compute-if-missing — sync wait for sole kernel, then full result.
+ * Whole-compute failure is typed terminal for this pull (no pending envelope).
+ * "Unobtrusive / non-blocking" binds #337 merge auto-trigger only, not user query.
+ */
+import { readFile } from "node:fs/promises";
+import { Type, type Static } from "typebox";
+
+import { physicalPathIdentity, resolveActivationLedgerHome } from "./activation-ledger-topology.ts";
+import {
+  runTaishiCohortMode,
+  type TaishiCohortModeInput,
+  type TaishiCohortModeResult,
+} from "./taishi-cohort.ts";
+import {
+  scanTaishiIssueRuns,
+  type TaishiReadableRunFacts,
+  type TaishiScopedRunScan,
+} from "./taishi-ledger.ts";
+import {
+  mergeTaishiLibraryIndexRows,
+  rowFromIssueMetricsPage,
+  type TaishiLibraryIndexPage,
+} from "./taishi-index.ts";
+import {
+  buildTaishiModelGroupsPage,
+  type TaishiModelGroupsPage,
+} from "./taishi-model-groups.ts";
+import {
+  assertTaishiChangedLinesInput,
+  buildTaishiIssueMetricsPage,
+  taishiIssuePagePath,
+  writeTaishiIssueMetricsPage,
+  type TaishiIssueMetricsPage,
+  type TaishiUnreadableRun,
+} from "./taishi-page.ts";
+
+/** #338 compute-if-missing failure — issue identity + real cause (CLI → ControlledFailure). */
+export class TaishiIssueComputeError extends Error {
+  readonly code = "taishi-issue-compute-failed" as const;
+  readonly projectRoot: string;
+  readonly issueNumber?: number;
+
+  constructor(input: {
+    readonly projectRoot: string;
+    readonly issueNumber?: number;
+    readonly cause: unknown;
+  }) {
+    const root = physicalPathIdentity(input.projectRoot);
+    const causeText =
+      input.cause instanceof Error
+        ? input.cause.message || input.cause.name
+        : String(input.cause);
+    const issueFace =
+      input.issueNumber === undefined
+        ? `projectRoot ${root}`
+        : `issue ${input.issueNumber} (projectRoot ${root})`;
+    super(`taishi compute failed for ${issueFace}: ${causeText}`, {
+      cause: input.cause,
+    });
+    this.name = "TaishiIssueComputeError";
+    this.projectRoot = root;
+    if (input.issueNumber !== undefined) {
+      this.issueNumber = input.issueNumber;
+    }
+  }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    error instanceof Error
+    && "code" in error
+    && (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}
+
+/** Issue-mode typed input — single-issue scope via projectRoot mechanical key. */
+export type TaishiIssueModeInput = {
+  readonly mode: "issue";
+  readonly projectRoot: string;
+  /**
+   * C4: caller typed ticket face (#176). When set, issue 圈定 prefers matching
+   * invocation.ticketNumber; runs without ticketNumber fall back to projectRoot.
+   */
+  readonly ticketNumber?: number;
+  /**
+   * Losing caller projectRoot when typed ticket/index root already won
+   * (public CLI dual-param: --ticket index hit over concurrent --project-root).
+   * When set and identity-distinct from projectRoot, page records the C4
+   * typed-ticketNumber-over-projectRoot fact for this call — no ledger alien run required.
+   */
+  readonly conflictingProjectRoot?: string;
+  /**
+   * 排除后改动行数 — optional caller typed input.
+   * Omit or 0 → page retains typed 空缺 for LOC and 耗时/千行.
+   */
+  readonly changedLines?: number;
+  /**
+   * Caller typed issue number — retained on the metrics page for cohort index join.
+   * Page addressing remains projectRoot (ADR 0068); issueNumber is not the key.
+   * When present, issue mode also maintains the unique issueNumber→projectRoot index row.
+   */
+  readonly issueNumber?: number;
+};
+
+/**
+ * Sole sweep-mode input contract (#298/#329/#337).
+ * Schema is the single definition; TS types are derived (no parallel hand shape).
+ * projectRoot = string (not nonempty); changedLines optional finite non-negative;
+ * 0 remains typed 空缺; no extra keys.
+ */
+export const taishiSweepModeInputSchema = Type.Object(
+  {
+    mode: Type.Literal("sweep"),
+    mergedPullRequests: Type.Array(
+      Type.Object(
+        {
+          projectRoot: Type.String(),
+          /** 排除后改动行数 — omit or 0 → typed 空缺; finite ≥ 0 only. */
+          changedLines: Type.Optional(
+            Type.Number({ minimum: 0, maximum: Number.MAX_VALUE }),
+          ),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+/** Sweep-mode typed input — 已并 PR 清单 + LOC → 补算缺页 + 维护全库索引. */
+export type TaishiSweepModeInput = Static<typeof taishiSweepModeInputSchema>;
+
+/** One merged-PR / issue entry for sweep-mode typed input. */
+export type TaishiMergedPullRequest =
+  TaishiSweepModeInput["mergedPullRequests"][number];
+
+/**
+ * Model-groups mode typed input — caller-supplied issue set (+ optional alias map).
+ * Scope is never guessed; empty projectRoots → empty groups.
+ */
+export type TaishiModelGroupsModeInput = {
+  readonly mode: "model-groups";
+  /** Issue set (projectRoot mechanical keys) defining the stats scope. */
+  readonly projectRoots: readonly string[];
+  /**
+   * Optional combination mapping: raw group key → display alias only.
+   * Must not merge groups or change denominators; unmapped keys keep raw name.
+   */
+  readonly combinationMapping?: Readonly<Record<string, string>>;
+};
+
+export type TaishiInput =
+  | TaishiIssueModeInput
+  | TaishiSweepModeInput
+  | TaishiCohortModeInput
+  | TaishiModelGroupsModeInput;
+
+export type TaishiIssueModeResult = {
+  readonly mode: "issue";
+  readonly page: TaishiIssueMetricsPage;
+  readonly pagePath: string;
+};
+
+export type TaishiSweepModeResult = {
+  readonly mode: "sweep";
+  /** Per-issue page results in input order (duplicates collapse on disk by key). */
+  readonly issuePages: readonly TaishiIssueModeResult[];
+  readonly index: TaishiLibraryIndexPage;
+  readonly indexPath: string;
+};
+
+export type TaishiModelGroupsModeResult = {
+  readonly mode: "model-groups";
+  /** Query output — not persisted (PRD ④ is on-demand typed output). */
+  readonly page: TaishiModelGroupsPage;
+};
+
+export type TaishiResult =
+  | TaishiIssueModeResult
+  | TaishiSweepModeResult
+  | TaishiCohortModeResult
+  | TaishiModelGroupsModeResult;
+
+/**
+ * #338 retrieval primitive (sync): use persisted page when present; otherwise
+ * await the sole issue compute kernel (runTaishiIssueMode) which writes via the
+ * existing page entry, then return the full result. No pending/async envelope.
+ * Compute failures throw TaishiIssueComputeError (issue identity + real cause)
+ * and terminate this pull — never washed to absent/partial success.
+ * Single-run unreadable/damaged stays page-local exclusion (PRD #298), not a
+ * whole-compute failure. Sweep / explicit recompute still use runTaishiIssueMode.
+ */
+/**
+ * Cached page may be reused only under bidirectional ticket-scope equality.
+ * - requested ticket present: page.issueNumber must equal it
+ * - requested ticket absent: only reuse a page that also lacks issueNumber
+ *   (a narrower ticket page must not stand in for the full root page)
+ * projectRoot path alone is not scope identity either direction.
+ */
+function cachedPageMatchesRequestedScope(
+  page: TaishiIssueMetricsPage,
+  input: TaishiIssueModeInput,
+): boolean {
+  const requestedTicket = input.ticketNumber ?? input.issueNumber;
+  if (requestedTicket === undefined) {
+    return page.issueNumber === undefined;
+  }
+  return page.issueNumber === requestedTicket;
+}
+
+export async function readOrComputeTaishiIssuePage(
+  input: TaishiIssueModeInput,
+): Promise<TaishiIssueModeResult> {
+  const ledgerHome = resolveActivationLedgerHome();
+  const projectRoot = physicalPathIdentity(input.projectRoot);
+  const pagePath = taishiIssuePagePath(ledgerHome, projectRoot);
+
+  try {
+    const raw = await readFile(pagePath, "utf8");
+    const page = JSON.parse(raw) as TaishiIssueMetricsPage;
+    if (cachedPageMatchesRequestedScope(page, input)) {
+      return { mode: "issue", page, pagePath };
+    }
+    // Existing page is for a different / absent ticket scope — same kernel recompute.
+  } catch (error) {
+    if (!isMissingPathError(error)) {
+      // Corrupt / blocked page path — loud with issue identity, not absent.
+      throw new TaishiIssueComputeError({
+        projectRoot,
+        ...(input.issueNumber === undefined ? {} : { issueNumber: input.issueNumber }),
+        cause: error,
+      });
+    }
+  }
+
+  try {
+    return await runTaishiIssueMode(input);
+  } catch (error) {
+    if (error instanceof TaishiIssueComputeError) throw error;
+    throw new TaishiIssueComputeError({
+      projectRoot,
+      ...(input.issueNumber === undefined ? {} : { issueNumber: input.issueNumber }),
+      cause: error,
+    });
+  }
+}
+
+async function runTaishiIssueMode(
+  input: TaishiIssueModeInput | TaishiMergedPullRequest,
+  /** Caller-supplied scan facts — skip a second ledger walk when already scanned. */
+  precomputedScan?: TaishiScopedRunScan,
+): Promise<TaishiIssueModeResult> {
+  // Programmatic issue/sweep entry boundary — same finite non-negative rule as attach schema.
+  assertTaishiChangedLinesInput(input.changedLines);
+  const ledgerHome = resolveActivationLedgerHome();
+  const projectRoot = input.projectRoot;
+  // Sweep entries carry projectRoot only; issue mode may add ticketNumber (C4).
+  const ticketNumber =
+    "ticketNumber" in input ? input.ticketNumber : undefined;
+
+  const scan = precomputedScan ??
+    (ticketNumber === undefined
+      ? await scanTaishiIssueRuns({ projectRoot })
+      : await scanTaishiIssueRuns({ projectRoot, ticketNumber }));
+
+  // exactOptionalPropertyTypes: only pass optional faces when caller supplied them.
+  const issueNumber =
+    "issueNumber" in input ? input.issueNumber : undefined;
+  const conflictingProjectRoot =
+    "conflictingProjectRoot" in input ? input.conflictingProjectRoot : undefined;
+
+  // Caller dual-param conflict (ticket/index root already won): record C4 fact
+  // from the call faces themselves — independent of ledger alien runs.
+  const scopeConflicts = [...scan.scopeConflicts];
+  if (conflictingProjectRoot !== undefined && ticketNumber !== undefined) {
+    const losingRoot = physicalPathIdentity(conflictingProjectRoot);
+    const winningRoot = physicalPathIdentity(projectRoot);
+    if (losingRoot !== winningRoot) {
+      scopeConflicts.push({
+        ticketNumber,
+        projectRoot: losingRoot,
+        fact: "typed-ticketNumber-over-projectRoot",
+      });
+    }
+  }
+
+  // Page build discovers metric families first — missing tree fails before write.
+  const page = await buildTaishiIssueMetricsPage({
+    projectRoot,
+    runs: scan.runs,
+    unreadable: scan.unreadable,
+    scopeConflicts,
+    ...(input.changedLines === undefined ? {} : { changedLines: input.changedLines }),
+    ...(issueNumber === undefined ? {} : { issueNumber }),
+  });
+
+  const pagePath = await writeTaishiIssueMetricsPage(ledgerHome, page);
+
+  // Issue number present → maintain the unique issueNumber→projectRoot index row
+  // so cohort can join without a second addressing kernel (ADR 0068 page key unchanged).
+  // Row carries C1 efficiency columns from the page (single index shape, no second kernel).
+  // Locked read→upsert→write so concurrent issue/sweep CLI writers do not drop rows.
+  if (issueNumber !== undefined) {
+    await mergeTaishiLibraryIndexRows(ledgerHome, [
+      rowFromIssueMetricsPage(page),
+    ]);
+  }
+
+  return { mode: "issue", page, pagePath };
+}
+
+async function runTaishiSweepMode(
+  input: TaishiSweepModeInput,
+): Promise<TaishiSweepModeResult> {
+  const ledgerHome = resolveActivationLedgerHome();
+
+  const issuePages: TaishiIssueModeResult[] = [];
+  for (const entry of input.mergedPullRequests) {
+    issuePages.push(await runTaishiIssueMode(entry));
+  }
+
+  const upserts = issuePages.map((result) => rowFromIssueMetricsPage(result.page));
+  const { index, indexPath } = await mergeTaishiLibraryIndexRows(ledgerHome, upserts);
+
+  return { mode: "sweep", issuePages, index, indexPath };
+}
+
+async function runTaishiModelGroupsMode(
+  input: TaishiModelGroupsModeInput,
+): Promise<TaishiModelGroupsModeResult> {
+  const ledgerHome = resolveActivationLedgerHome();
+
+  const runs: TaishiReadableRunFacts[] = [];
+  const unreadable: TaishiUnreadableRun[] = [];
+  // Dedupe scope roots by physical identity while preserving caller order for scan.
+  const seen = new Set<string>();
+  const projectRoots: string[] = [];
+  for (const root of input.projectRoots) {
+    const identity = physicalPathIdentity(root);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    projectRoots.push(identity);
+  }
+
+  // One ledger scan per root — shared by #338 ensure-page and model-group aggregate.
+  // No second scan pass; sole issue kernel + existing writer when page is missing.
+  for (const projectRoot of projectRoots) {
+    const scan = await scanTaishiIssueRuns({ projectRoot });
+    runs.push(...scan.runs);
+    unreadable.push(...scan.unreadable);
+
+    const pagePath = taishiIssuePagePath(ledgerHome, projectRoot);
+    try {
+      const raw = await readFile(pagePath, "utf8");
+      JSON.parse(raw); // present page must parse (same loud face as readOrCompute)
+    } catch (error) {
+      if (!isMissingPathError(error)) {
+        throw new TaishiIssueComputeError({ projectRoot, cause: error });
+      }
+      try {
+        // Reuse this root's scan facts — no second ledger walk on compute-if-missing.
+        await runTaishiIssueMode({ mode: "issue", projectRoot }, scan);
+      } catch (computeError) {
+        if (computeError instanceof TaishiIssueComputeError) throw computeError;
+        throw new TaishiIssueComputeError({ projectRoot, cause: computeError });
+      }
+    }
+  }
+
+  // exactOptionalPropertyTypes: only pass mapping when caller supplied it.
+  const page = input.combinationMapping === undefined
+    ? buildTaishiModelGroupsPage({ projectRoots, runs, unreadable })
+    : buildTaishiModelGroupsPage({
+        projectRoots,
+        runs,
+        unreadable,
+        combinationMapping: input.combinationMapping,
+      });
+
+  return { mode: "model-groups", page };
+}
+
+/**
+ * Sole taishi entry.
+ * - Issue mode: scope → scan (typed facts) → family compose → atomic replace.
+ *   When issueNumber present, also upsert library index (C2 cohort join face).
+ * - Sweep mode: for each merged PR entry run issue kernel, upsert library index.
+ * - Cohort mode: join library index by issueNumber → ensure pages (#338) → contrast.
+ * - Model-groups mode: issue-set scope → one scan/root (ensure page #338 + aggregate).
+ * Metric-family kernels (B/C waves) drop a module under taishi-metric-families/
+ * and consume scan facts without opening a second entry or second parse kernel.
+ * Machine home is package-owned (ADR 0048) — never an invocation field.
+ * Retrieval compute-if-missing is readOrComputeTaishiIssuePage (not a second kernel).
+ */
+export async function runTaishi(input: TaishiIssueModeInput): Promise<TaishiIssueModeResult>;
+export async function runTaishi(input: TaishiSweepModeInput): Promise<TaishiSweepModeResult>;
+export async function runTaishi(input: TaishiCohortModeInput): Promise<TaishiCohortModeResult>;
+export async function runTaishi(
+  input: TaishiModelGroupsModeInput,
+): Promise<TaishiModelGroupsModeResult>;
+export async function runTaishi(input: TaishiInput): Promise<TaishiResult>;
+export async function runTaishi(input: TaishiInput): Promise<TaishiResult> {
+  if (input.mode === "sweep") {
+    return runTaishiSweepMode(input);
+  }
+  if (input.mode === "cohort") {
+    const ledgerHome = resolveActivationLedgerHome();
+    return runTaishiCohortMode(ledgerHome, input, async ({ projectRoot, issueNumber }) => {
+      const ensured = await readOrComputeTaishiIssuePage({
+        mode: "issue",
+        projectRoot,
+        issueNumber,
+      });
+      return ensured.page;
+    });
+  }
+  if (input.mode === "model-groups") {
+    return runTaishiModelGroupsMode(input);
+  }
+  return runTaishiIssueMode(input);
+}

package/src/taishi-index.ts

@@ -0,0 +1,269 @@
+/**
+ * Taishi library index page (ADR 0068 / PRD #298 output ②).
+ *
+ * Sweep mode maintains one self-sufficient row per issue:
+ * 完全耗时 / 排除后改动行数 / 耗时每千行 / 末次活动时间戳.
+ * Rows carry their own sort keys — readers choose order (Story 6/8).
+ *
+ * Cross-book one row per issue. C2 joins cohort groups by issueNumber →
+ * projectRoot page reference (ADR 0068 mechanical key). Missing row =
+ * typed vacancy entry — never silent skip, never live recompute.
+ *
+ * Multi-process issue/sweep writers coordinate the whole read→upsert→write
+ * on one exclusive lock next to the index (atomic rename still prevents torn
+ * JSON; the lock prevents lost-update across concurrent CLI processes).
+ */
+import { open, readFile, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { writeFileAtomically } from "./atomic-write.ts";
+import {
+  assertLedgerFileInsideHome,
+  ensureRealDirectoryTree,
+} from "./activation-ledger-topology.ts";
+import type {
+  TaishiIssueMetricsPage,
+  TaishiOptionalMetricNumber,
+  TaishiOptionalTimestamp,
+} from "./taishi-page.ts";
+
+const LIBRARY_INDEX_LOCK_NAME = ".library-index.lock";
+const LIBRARY_INDEX_LOCK_TIMEOUT_MS = 30_000;
+const LIBRARY_INDEX_LOCK_RETRY_MS = 15;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Exclusive create lock for the library-index read→upsert→write critical section.
+ * Same-directory sibling of the index file; not a second index and not a daemon.
+ */
+async function withTaishiLibraryIndexLock<T>(
+  ledgerHome: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const indexPath = taishiLibraryIndexPath(ledgerHome);
+  ensureRealDirectoryTree(ledgerHome, dirname(indexPath));
+  const lockPath = join(dirname(indexPath), LIBRARY_INDEX_LOCK_NAME);
+  assertLedgerFileInsideHome(lockPath, ledgerHome);
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      const handle = await open(lockPath, "wx");
+      try {
+        await handle.writeFile(`${process.pid}\n`, "utf8");
+        return await fn();
+      } finally {
+        await handle.close().catch(() => undefined);
+        await unlink(lockPath).catch(() => undefined);
+      }
+    } catch (error) {
+      const code =
+        error instanceof Error && "code" in error
+          ? (error as NodeJS.ErrnoException).code
+          : undefined;
+      if (code !== "EEXIST") throw error;
+      if (Date.now() - startedAt > LIBRARY_INDEX_LOCK_TIMEOUT_MS) {
+        throw new Error(
+          `taishi library-index lock timeout after ${LIBRARY_INDEX_LOCK_TIMEOUT_MS}ms: ${lockPath}`,
+        );
+      }
+      await sleep(LIBRARY_INDEX_LOCK_RETRY_MS);
+    }
+  }
+}
+
+/**
+ * One issue row on the cross-book library index.
+ * projectRoot = page addressing key (ADR 0068).
+ * issueNumber = optional caller typed field retained for cohort join.
+ * C1 four columns make the row self-sufficient for cross-issue listing.
+ */
+export type TaishiLibraryIndexRow = {
+  readonly projectRoot: string;
+  /** Caller typed issue number — present when issue-mode supplied it for cohort join. */
+  readonly issueNumber?: number;
+  /** 完全耗时 — Σ readable leg wall clocks. */
+  readonly totalElapsedMs: number;
+  /** 排除后改动行数 — caller typed input; may be typed 空缺. */
+  readonly changedLines: TaishiOptionalMetricNumber;
+  /** 耗时/千行 — absent when LOC absent/0 (never 0 or ∞ stand-in). */
+  readonly msPerKLines: TaishiOptionalMetricNumber;
+  /** 末次活动时间戳 — max end-frame across ALL runs (incl. unreadable available). */
+  readonly lastActivityAt: TaishiOptionalTimestamp;
+};
+
+/**
+ * Library index page — unique true source for cross-issue listing / cohort join.
+ * No md second projection; render on demand.
+ */
+export type TaishiLibraryIndexPage = {
+  readonly kind: "taishi-library-index";
+  readonly rows: readonly TaishiLibraryIndexRow[];
+};
+
+export function taishiLibraryIndexPath(ledgerHome: string): string {
+  return join(ledgerHome, "taishi", "library-index.json");
+}
+
+export function rowFromIssueMetricsPage(
+  page: TaishiIssueMetricsPage,
+): TaishiLibraryIndexRow {
+  return {
+    projectRoot: page.projectRoot,
+    // exactOptionalPropertyTypes: only materialize when page carries it.
+    ...(page.issueNumber === undefined ? {} : { issueNumber: page.issueNumber }),
+    totalElapsedMs: page.totalElapsedMs,
+    changedLines: page.changedLines,
+    msPerKLines: page.msPerKLines,
+    lastActivityAt: page.lastActivityAt,
+  };
+}
+
+function sortRows(
+  rows: readonly TaishiLibraryIndexRow[],
+): TaishiLibraryIndexRow[] {
+  // Stable projectRoot sort (C1 listing). Cohort join is by issueNumber find,
+  // not row order — issueNumber secondary keeps C2 rows deterministic too.
+  return [...rows].sort((a, b) => {
+    const byRoot = a.projectRoot.localeCompare(b.projectRoot);
+    if (byRoot !== 0) return byRoot;
+    const aNum = a.issueNumber;
+    const bNum = b.issueNumber;
+    if (aNum === undefined && bNum === undefined) return 0;
+    if (aNum === undefined) return 1;
+    if (bNum === undefined) return -1;
+    return aNum - bNum;
+  });
+}
+
+/** Build a fresh index from the given rows (stable projectRoot, then issueNumber). */
+export function buildTaishiLibraryIndexPage(
+  rows: readonly TaishiLibraryIndexRow[],
+): TaishiLibraryIndexPage {
+  return {
+    kind: "taishi-library-index",
+    rows: sortRows(rows),
+  };
+}
+
+/**
+ * Look up the first index row for an issue number.
+ * Absence is a lawful cohort vacancy signal — not an error.
+ */
+export function findTaishiLibraryIndexRow(
+  index: TaishiLibraryIndexPage | undefined,
+  issueNumber: number,
+): TaishiLibraryIndexRow | undefined {
+  if (index === undefined) return undefined;
+  return index.rows.find((row) => row.issueNumber === issueNumber);
+}
+
+/**
+ * Upsert issue rows into an existing index (or empty).
+ * - One row per projectRoot — re-sweep overwrites that issue's row only (C1).
+ * - When issueNumber is present, also unique per issueNumber — re-issue
+ *   overwrites that number's row only (C2 issueNumber→projectRoot join).
+ */
+export function upsertTaishiLibraryIndexRows(
+  existing: TaishiLibraryIndexPage | undefined,
+  upserts: readonly TaishiLibraryIndexRow[],
+): TaishiLibraryIndexPage {
+  const byRoot = new Map<string, TaishiLibraryIndexRow>();
+  const rootByIssue = new Map<number, string>();
+
+  const ingest = (row: TaishiLibraryIndexRow): void => {
+    // C2 uniqueness: one row per issueNumber — drop prior root if number moved.
+    if (row.issueNumber !== undefined) {
+      const priorRoot = rootByIssue.get(row.issueNumber);
+      if (priorRoot !== undefined && priorRoot !== row.projectRoot) {
+        byRoot.delete(priorRoot);
+      }
+    }
+    // C1 uniqueness: one row per projectRoot — drop prior issue map if root reused.
+    const prior = byRoot.get(row.projectRoot);
+    if (
+      prior !== undefined
+      && prior.issueNumber !== undefined
+      && prior.issueNumber !== row.issueNumber
+    ) {
+      rootByIssue.delete(prior.issueNumber);
+    }
+    byRoot.set(row.projectRoot, row);
+    if (row.issueNumber !== undefined) {
+      rootByIssue.set(row.issueNumber, row.projectRoot);
+    }
+  };
+
+  if (existing !== undefined) {
+    for (const row of existing.rows) {
+      ingest(row);
+    }
+  }
+  for (const row of upserts) {
+    ingest(row);
+  }
+  return buildTaishiLibraryIndexPage([...byRoot.values()]);
+}
+
+/**
+ * Read existing library index, or undefined when absent.
+ * Single typed producer writes this file — JSON.parse failure is loud;
+ * no bespoke shape validator on the self-read path.
+ */
+export async function readTaishiLibraryIndexPage(
+  ledgerHome: string,
+): Promise<TaishiLibraryIndexPage | undefined> {
+  const path = taishiLibraryIndexPath(ledgerHome);
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (
+      error instanceof Error
+      && "code" in error
+      && (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+  return JSON.parse(raw) as TaishiLibraryIndexPage;
+}
+
+/**
+ * Atomically replace the library index page.
+ * Directory creation goes through ledger home physical containment.
+ * Prefer {@link mergeTaishiLibraryIndexRows} for multi-writer updates — bare
+ * write has no read→merge coordination.
+ */
+export async function writeTaishiLibraryIndexPage(
+  ledgerHome: string,
+  page: TaishiLibraryIndexPage,
+): Promise<string> {
+  const path = taishiLibraryIndexPath(ledgerHome);
+  ensureRealDirectoryTree(ledgerHome, dirname(path));
+  assertLedgerFileInsideHome(path, ledgerHome);
+  await writeFileAtomically(path, `${JSON.stringify(page, null, 2)}\n`);
+  return path;
+}
+
+/**
+ * Sole multi-writer coordination seam for library-index updates.
+ * Holds one exclusive lock across read → upsert → atomic write so concurrent
+ * issue/sweep CLI processes cannot drop each other's new rows.
+ */
+export async function mergeTaishiLibraryIndexRows(
+  ledgerHome: string,
+  upserts: readonly TaishiLibraryIndexRow[],
+): Promise<{ readonly index: TaishiLibraryIndexPage; readonly indexPath: string }> {
+  return withTaishiLibraryIndexLock(ledgerHome, async () => {
+    const existing = await readTaishiLibraryIndexPage(ledgerHome);
+    const index = upsertTaishiLibraryIndexRows(existing, upserts);
+    const indexPath = await writeTaishiLibraryIndexPage(ledgerHome, index);
+    return { index, indexPath };
+  });
+}