@akagilnc/pi-workflow-roles 0.1.1941 → 0.1.2004

package/src/taishi-metric-families/acceptance-success-rework.ts

@@ -0,0 +1,346 @@
+/**
+ * B3 metric family: acceptance terminal mapping, rework lens, first-pass / success rates.
+ *
+ * Consumes only A2 typed per-run facts (frame span + terminal face). Drop-in
+ * registration via taishi-metric-families/ discovery — no shared skeleton edits.
+ *
+ * Denominator contract (PRD #298 + ticket #327 票面补正):
+ * - first-pass rate den = appearance lanes (no-receipt first call stays in den)
+ * - success rate den = success-eligible accepted legs (no-receipt out; planned out)
+ * - planned = plan-duty acceptance; never success numerator or denominator
+ */
+import type { TaishiReadableRunFacts, TaishiRunTerminalFace } from "../taishi-ledger.ts";
+import { medianNumber } from "../taishi-median.ts";
+import type { TaishiMetricFamilyModule } from "../taishi-metric-family.ts";
+
+const WORKER_ROLES = new Set(["coder", "fixer"]);
+
+/** Lawful acceptance vocabulary by role (PRD 受理终态映射). */
+const ACCEPTED_STATUS: Readonly<Record<string, ReadonlySet<string>>> = {
+  coder: new Set(["completed", "refused", "partially_completed", "unfinished", "planned"]),
+  fixer: new Set(["completed", "refused", "partially_completed", "unfinished", "planned"]),
+  judge: new Set(["converged", "continue", "escalate"]),
+  reviewer: new Set(["completed", "refused"]),
+  doctor: new Set(["completed", "refused"]),
+  merger: new Set(["completed", "escalate"]),
+};
+
+/** Success vocabulary by role (PRD 成功集合). planned excluded for workers. */
+const SUCCESS_STATUS: Readonly<Record<string, ReadonlySet<string>>> = {
+  coder: new Set(["completed"]),
+  fixer: new Set(["completed"]),
+  // Judge: producing any of the three verdicts completes the duty.
+  judge: new Set(["converged", "continue", "escalate"]),
+  reviewer: new Set(["completed"]),
+  doctor: new Set(["completed"]),
+  merger: new Set(["completed"]),
+};
+
+export type TaishiTerminalMapLabel =
+  | "no-receipt"
+  | "non-accepted"
+  | "groups"
+  | string;
+
+export type TaishiAcceptanceLeg = {
+  readonly runId: string;
+  readonly book: string;
+  readonly role: string;
+  readonly startedAt: string;
+  readonly wallMs: number;
+  /** Mapped terminal label (status token, groups, no-receipt, non-accepted). */
+  readonly terminalLabel: TaishiTerminalMapLabel;
+  readonly accepted: boolean;
+  /** In success set (and therefore success numerator when eligible). */
+  readonly success: boolean;
+  /** In success-rate denominator (accepted ∧ ¬planned-duty). */
+  readonly successEligible: boolean;
+  readonly noReceipt: boolean;
+  /** 1-based ordinal among same lane+role ordered by startedAt. */
+  readonly ordinalInLaneRole: number;
+  readonly rework: boolean;
+};
+
+export type TaishiRoleAcceptanceStats = {
+  readonly role: string;
+  readonly acceptedCount: number;
+  readonly successEligibleCount: number;
+  readonly successCount: number;
+  readonly noReceiptCount: number;
+  /** successCount / successEligibleCount; undefined when denominator is 0. */
+  readonly successRate: number | undefined;
+  readonly appearanceLaneCount: number;
+  readonly firstPassLaneCount: number;
+  /** firstPassLaneCount / appearanceLaneCount; undefined when denominator is 0. */
+  readonly firstPassRate: number | undefined;
+  /** Per appearance-lane call counts (convergence rounds). */
+  readonly convergenceRounds: readonly number[];
+  readonly convergenceRoundsMedian: number | undefined;
+};
+
+export type TaishiReworkLens = {
+  readonly reworkWallMs: number;
+  readonly totalWallMs: number;
+  /** reworkWallMs / totalWallMs; undefined when totalWallMs is 0. */
+  readonly reworkRatio: number | undefined;
+  readonly reworkLegCount: number;
+  readonly totalLegCount: number;
+};
+
+export type TaishiAcceptanceSuccessReworkSection = {
+  readonly kind: "taishi-acceptance-success-rework";
+  readonly legs: readonly TaishiAcceptanceLeg[];
+  readonly byRole: readonly TaishiRoleAcceptanceStats[];
+  readonly rework: TaishiReworkLens;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function wallMsFromSpan(span: { readonly startedAt: string; readonly endedAt: string }): number {
+  return Date.parse(span.endedAt) - Date.parse(span.startedAt);
+}
+
+/** Locate collector groups array: receipt.groups or top-level groups. */
+function findCollectorGroups(body: Record<string, unknown>): unknown {
+  if (Array.isArray(body.groups)) return body.groups;
+  const receipt = body.receipt;
+  if (isRecord(receipt) && Array.isArray(receipt.groups)) return receipt.groups;
+  const outcome = body.outcome;
+  if (isRecord(outcome)) {
+    const facts = outcome.decisiveFacts;
+    if (isRecord(facts) && Array.isArray(facts.groups)) return facts.groups;
+  }
+  return undefined;
+}
+
+/** Extract role receipt status from canonical terminal body faces. */
+function extractStatus(body: Record<string, unknown>): string | undefined {
+  const outcome = body.outcome;
+  if (isRecord(outcome) && typeof outcome.status === "string" && outcome.status.trim() !== "") {
+    return outcome.status;
+  }
+  const receipt = body.receipt;
+  if (isRecord(receipt) && typeof receipt.status === "string" && receipt.status.trim() !== "") {
+    return receipt.status;
+  }
+  if (typeof body.status === "string" && body.status.trim() !== "") {
+    return body.status;
+  }
+  return undefined;
+}
+
+function mapTerminal(
+  role: string,
+  terminal: TaishiRunTerminalFace,
+): {
+  readonly terminalLabel: TaishiTerminalMapLabel;
+  readonly accepted: boolean;
+  readonly success: boolean;
+  readonly successEligible: boolean;
+  readonly noReceipt: boolean;
+} {
+  if (terminal.status === "absent") {
+    return {
+      terminalLabel: "no-receipt",
+      accepted: false,
+      success: false,
+      successEligible: false,
+      noReceipt: true,
+    };
+  }
+
+  const body = terminal.body;
+
+  // Collector: typed groups array presence is the sole acceptance discriminator.
+  if (role === "collector") {
+    const groups = findCollectorGroups(body);
+    if (Array.isArray(groups)) {
+      return {
+        terminalLabel: "groups",
+        accepted: true,
+        success: true,
+        successEligible: true,
+        noReceipt: false,
+      };
+    }
+    return {
+      terminalLabel: "non-accepted",
+      accepted: false,
+      success: false,
+      successEligible: false,
+      noReceipt: false,
+    };
+  }
+
+  const status = extractStatus(body);
+  if (status === undefined) {
+    return {
+      terminalLabel: "non-accepted",
+      accepted: false,
+      success: false,
+      successEligible: false,
+      noReceipt: false,
+    };
+  }
+
+  const acceptedSet = ACCEPTED_STATUS[role];
+  if (acceptedSet === undefined || !acceptedSet.has(status)) {
+    return {
+      terminalLabel: status,
+      accepted: false,
+      success: false,
+      successEligible: false,
+      noReceipt: false,
+    };
+  }
+
+  const plannedDuty = WORKER_ROLES.has(role) && status === "planned";
+  const successSet = SUCCESS_STATUS[role] ?? new Set<string>();
+  const success = !plannedDuty && successSet.has(status);
+  const successEligible = !plannedDuty;
+
+  return {
+    terminalLabel: status,
+    accepted: true,
+    success,
+    successEligible,
+    noReceipt: false,
+  };
+}
+
+function projectLegs(runs: readonly TaishiReadableRunFacts[]): TaishiAcceptanceLeg[] {
+  // Order within lane+role by startedAt (then runId) to assign ordinals / rework.
+  const sorted = [...runs].sort((a, b) => {
+    if (a.book !== b.book) return a.book.localeCompare(b.book);
+    if (a.role !== b.role) return a.role.localeCompare(b.role);
+    if (a.frameSpan.startedAt !== b.frameSpan.startedAt) {
+      return a.frameSpan.startedAt.localeCompare(b.frameSpan.startedAt);
+    }
+    return a.runId.localeCompare(b.runId);
+  });
+
+  const ordinalByKey = new Map<string, number>();
+  const legs: TaishiAcceptanceLeg[] = [];
+
+  for (const run of sorted) {
+    const key = `${run.book}\0${run.role}`;
+    const ordinal = (ordinalByKey.get(key) ?? 0) + 1;
+    ordinalByKey.set(key, ordinal);
+    const mapped = mapTerminal(run.role, run.terminal);
+    legs.push({
+      runId: run.runId,
+      book: run.book,
+      role: run.role,
+      startedAt: run.frameSpan.startedAt,
+      wallMs: wallMsFromSpan(run.frameSpan),
+      terminalLabel: mapped.terminalLabel,
+      accepted: mapped.accepted,
+      success: mapped.success,
+      successEligible: mapped.successEligible,
+      noReceipt: mapped.noReceipt,
+      ordinalInLaneRole: ordinal,
+      rework: ordinal >= 2,
+    });
+  }
+
+  // Stable page order: book, role, runId (match A1 leg sort).
+  return legs.sort((a, b) => {
+    if (a.book !== b.book) return a.book.localeCompare(b.book);
+    if (a.role !== b.role) return a.role.localeCompare(b.role);
+    return a.runId.localeCompare(b.runId);
+  });
+}
+
+function aggregateByRole(legs: readonly TaishiAcceptanceLeg[]): TaishiRoleAcceptanceStats[] {
+  const roles = [...new Set(legs.map((leg) => leg.role))].sort((a, b) => a.localeCompare(b));
+  return roles.map((role) => {
+    const roleLegs = legs.filter((leg) => leg.role === role);
+    const acceptedCount = roleLegs.filter((leg) => leg.accepted).length;
+    const successEligibleCount = roleLegs.filter((leg) => leg.successEligible).length;
+    const successCount = roleLegs.filter((leg) => leg.success).length;
+    const noReceiptCount = roleLegs.filter((leg) => leg.noReceipt).length;
+
+    // Appearance lanes + first-pass: first call by startedAt within each book.
+    const byBook = new Map<string, TaishiAcceptanceLeg[]>();
+    for (const leg of roleLegs) {
+      const list = byBook.get(leg.book) ?? [];
+      list.push(leg);
+      byBook.set(leg.book, list);
+    }
+    const books = [...byBook.keys()].sort((a, b) => a.localeCompare(b));
+    const convergenceRounds: number[] = [];
+    let firstPassLaneCount = 0;
+    for (const book of books) {
+      const laneLegs = [...byBook.get(book)!].sort((a, b) => {
+        if (a.startedAt !== b.startedAt) return a.startedAt.localeCompare(b.startedAt);
+        return a.runId.localeCompare(b.runId);
+      });
+      convergenceRounds.push(laneLegs.length);
+      const first = laneLegs[0]!;
+      if (first.accepted) firstPassLaneCount += 1;
+    }
+    const appearanceLaneCount = books.length;
+
+    return {
+      role,
+      acceptedCount,
+      successEligibleCount,
+      successCount,
+      noReceiptCount,
+      successRate:
+        successEligibleCount === 0 ? undefined : successCount / successEligibleCount,
+      appearanceLaneCount,
+      firstPassLaneCount,
+      firstPassRate:
+        appearanceLaneCount === 0 ? undefined : firstPassLaneCount / appearanceLaneCount,
+      convergenceRounds,
+      convergenceRoundsMedian: medianNumber(convergenceRounds),
+    };
+  });
+}
+
+function reworkLens(legs: readonly TaishiAcceptanceLeg[]): TaishiReworkLens {
+  let reworkWallMs = 0;
+  let totalWallMs = 0;
+  let reworkLegCount = 0;
+  for (const leg of legs) {
+    totalWallMs += leg.wallMs;
+    if (leg.rework) {
+      reworkWallMs += leg.wallMs;
+      reworkLegCount += 1;
+    }
+  }
+  return {
+    reworkWallMs,
+    totalWallMs,
+    reworkRatio: totalWallMs === 0 ? undefined : reworkWallMs / totalWallMs,
+    reworkLegCount,
+    totalLegCount: legs.length,
+  };
+}
+
+export function buildAcceptanceSuccessReworkSection(
+  runs: readonly TaishiReadableRunFacts[],
+): TaishiAcceptanceSuccessReworkSection | undefined {
+  if (runs.length === 0) return undefined;
+  const legs = projectLegs(runs);
+  return {
+    kind: "taishi-acceptance-success-rework",
+    legs,
+    byRole: aggregateByRole(legs),
+    rework: reworkLens(legs),
+  };
+}
+
+const acceptanceSuccessReworkFamily: TaishiMetricFamilyModule = {
+  id: "acceptance-success-rework",
+  contribute(input) {
+    const section = buildAcceptanceSuccessReworkSection(input.runs);
+    if (section === undefined) return undefined;
+    return { acceptanceSuccessRework: section };
+  },
+};
+
+export default acceptanceSuccessReworkFamily;

package/src/taishi-metric-families/b2-frame-buckets-actions.ts

@@ -0,0 +1,274 @@
+/**
+ * B2 metric family — two-bucket full partition + single-leg action board.
+ *
+ * Consumes A2 typed per-run facts only (frame span + tool intervals).
+ * Registers by drop-in under taishi-metric-families/ (A2 assembly discovery).
+ *
+ * Kernel (single frame-bounded interval core):
+ * - every closed tool interval is clipped to the leg frame [frameStart, frameEnd]
+ * - tool bucket = union duration of clipped intervals (no double-count)
+ * - model bucket = wall − tool bucket (mutual exclusion; sum ≡ wall)
+ * - actions = each clipped tool interval + every maximal continuous model gap
+ *   (frame complement of tool union, including pre-first and post-last tails),
+ *   sorted by duration descending
+ * - action median via shared medianNumber (even → mean of two middles)
+ * - tool observation: toolName + A2 bash first-line command summary (no re-parse)
+ */
+import type { SessionToolInterval } from "../ledger-session-read.ts";
+import { medianNumber } from "../taishi-median.ts";
+import type { TaishiReadableRunFacts } from "../taishi-ledger.ts";
+import type { TaishiMetricFamilyModule } from "../taishi-metric-family.ts";
+
+export type TaishiB2ToolAction = {
+  readonly kind: "tool";
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly durationMs: number;
+  readonly startedAt: string;
+  readonly endedAt: string;
+  /** A2 bash first-line command summary when present. */
+  readonly commandSummary?: string;
+};
+
+export type TaishiB2ModelAction = {
+  readonly kind: "model";
+  readonly durationMs: number;
+  readonly startedAt: string;
+  readonly endedAt: string;
+};
+
+export type TaishiB2Action = TaishiB2ToolAction | TaishiB2ModelAction;
+
+export type TaishiB2RunMetrics = {
+  readonly runId: string;
+  readonly book: string;
+  readonly role: string;
+  readonly wallMs: number;
+  readonly toolBucketMs: number;
+  readonly modelBucketMs: number;
+  readonly actions: readonly TaishiB2Action[];
+  readonly actionDurationMedianMs: number | undefined;
+};
+
+export type TaishiB2FrameBucketsActionsSection = {
+  readonly kind: "taishi-b2-frame-buckets-actions";
+  readonly runs: readonly TaishiB2RunMetrics[];
+};
+
+type ClosedTool = {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly startedAt: string;
+  readonly endedAt: string;
+  readonly startMs: number;
+  readonly endMs: number;
+  readonly command?: string;
+};
+
+function timestampMs(iso: string): number {
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms)) {
+    throw new Error(`unparseable timestamp: ${iso}`);
+  }
+  return ms;
+}
+
+function toIso(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+function closedTools(intervals: readonly SessionToolInterval[]): ClosedTool[] {
+  const out: ClosedTool[] = [];
+  for (const interval of intervals) {
+    if (interval.endedAt === undefined) continue;
+    const startMs = timestampMs(interval.startedAt);
+    const endMs = timestampMs(interval.endedAt);
+    if (endMs <= startMs) continue;
+    out.push({
+      toolCallId: interval.toolCallId,
+      toolName: interval.toolName,
+      startedAt: interval.startedAt,
+      endedAt: interval.endedAt,
+      startMs,
+      endMs,
+      ...(interval.command !== undefined ? { command: interval.command } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * Clip closed tools to the leg frame. Empty after clip are dropped.
+ * Bucket, complement, and tool actions all consume this same bounded set.
+ */
+function clipToolsToFrame(
+  tools: readonly ClosedTool[],
+  frameStartMs: number,
+  frameEndMs: number,
+): ClosedTool[] {
+  if (frameEndMs <= frameStartMs) return [];
+  const out: ClosedTool[] = [];
+  for (const tool of tools) {
+    const startMs = Math.max(tool.startMs, frameStartMs);
+    const endMs = Math.min(tool.endMs, frameEndMs);
+    if (endMs <= startMs) continue;
+    out.push({
+      toolCallId: tool.toolCallId,
+      toolName: tool.toolName,
+      startMs,
+      endMs,
+      startedAt: startMs === tool.startMs ? tool.startedAt : toIso(startMs),
+      endedAt: endMs === tool.endMs ? tool.endedAt : toIso(endMs),
+      ...(tool.command !== undefined ? { command: tool.command } : {}),
+    });
+  }
+  return out;
+}
+
+/** Merge overlapping/adjacent [start,end) intervals; return sorted disjoint union. */
+function mergeUnion(intervals: readonly { startMs: number; endMs: number }[]): {
+  startMs: number;
+  endMs: number;
+}[] {
+  if (intervals.length === 0) return [];
+  const sorted = [...intervals].sort(
+    (a, b) => a.startMs - b.startMs || a.endMs - b.endMs,
+  );
+  const merged: { startMs: number; endMs: number }[] = [
+    { startMs: sorted[0]!.startMs, endMs: sorted[0]!.endMs },
+  ];
+  for (let i = 1; i < sorted.length; i += 1) {
+    const cur = sorted[i]!;
+    const last = merged[merged.length - 1]!;
+    if (cur.startMs <= last.endMs) {
+      last.endMs = Math.max(last.endMs, cur.endMs);
+    } else {
+      merged.push({ startMs: cur.startMs, endMs: cur.endMs });
+    }
+  }
+  return merged;
+}
+
+/**
+ * Maximal continuous complement of (already frame-clipped) tool union
+ * inside [frameStart, frameEnd]. Includes leading and trailing gaps.
+ */
+function modelMaximalIntervals(
+  frameStartMs: number,
+  frameEndMs: number,
+  toolUnion: readonly { startMs: number; endMs: number }[],
+): { startMs: number; endMs: number }[] {
+  if (frameEndMs <= frameStartMs) return [];
+  const gaps: { startMs: number; endMs: number }[] = [];
+  let cursor = frameStartMs;
+  for (const interval of toolUnion) {
+    // Union is produced from frame-clipped tools, so bounds already lie in frame.
+    if (interval.startMs > cursor) {
+      gaps.push({ startMs: cursor, endMs: interval.startMs });
+    }
+    cursor = Math.max(cursor, interval.endMs);
+  }
+  if (cursor < frameEndMs) {
+    gaps.push({ startMs: cursor, endMs: frameEndMs });
+  }
+  return gaps;
+}
+
+function toolAction(tool: ClosedTool): TaishiB2ToolAction {
+  const action: TaishiB2ToolAction = {
+    kind: "tool",
+    toolCallId: tool.toolCallId,
+    toolName: tool.toolName,
+    durationMs: tool.endMs - tool.startMs,
+    startedAt: tool.startedAt,
+    endedAt: tool.endedAt,
+  };
+  // A2 already owns bash first-line summary; B2 only projects it.
+  if (tool.toolName === "bash" && tool.command !== undefined) {
+    return {
+      ...action,
+      commandSummary: tool.command,
+    };
+  }
+  return action;
+}
+
+function modelAction(gap: { startMs: number; endMs: number }): TaishiB2ModelAction {
+  return {
+    kind: "model",
+    durationMs: gap.endMs - gap.startMs,
+    startedAt: toIso(gap.startMs),
+    endedAt: toIso(gap.endMs),
+  };
+}
+
+function sortActionsDescending(actions: readonly TaishiB2Action[]): TaishiB2Action[] {
+  return [...actions].sort((a, b) => {
+    if (b.durationMs !== a.durationMs) return b.durationMs - a.durationMs;
+    // Stable tie-break: earlier start first, then kind/toolCallId for determinism.
+    if (a.startedAt !== b.startedAt) return a.startedAt.localeCompare(b.startedAt);
+    if (a.kind !== b.kind) return a.kind.localeCompare(b.kind);
+    if (a.kind === "tool" && b.kind === "tool") {
+      return a.toolCallId.localeCompare(b.toolCallId);
+    }
+    return 0;
+  });
+}
+
+/** Pure B2 kernel over one readable run's A2 facts. */
+export function computeTaishiB2RunMetrics(
+  facts: TaishiReadableRunFacts,
+): TaishiB2RunMetrics {
+  const frameStartMs = timestampMs(facts.frameSpan.startedAt);
+  const frameEndMs = timestampMs(facts.frameSpan.endedAt);
+  const wallMs = Math.max(0, frameEndMs - frameStartMs);
+
+  // Single frame-bounded core: clip → union once → bucket/complement/actions.
+  const tools = clipToolsToFrame(closedTools(facts.toolIntervals), frameStartMs, frameEndMs);
+  const toolUnion = mergeUnion(tools);
+  const toolBucketMs = toolUnion.reduce(
+    (sum, interval) => sum + (interval.endMs - interval.startMs),
+    0,
+  );
+  // Mutual exclusion: model is exact complement duration (no independent recount).
+  const modelBucketMs = wallMs - toolBucketMs;
+
+  const modelGaps = modelMaximalIntervals(frameStartMs, frameEndMs, toolUnion);
+  const actions = sortActionsDescending([
+    ...tools.map(toolAction),
+    ...modelGaps.map(modelAction),
+  ]);
+  const actionDurationMedianMs = medianNumber(actions.map((action) => action.durationMs));
+
+  return {
+    runId: facts.runId,
+    book: facts.book,
+    role: facts.role,
+    wallMs,
+    toolBucketMs,
+    modelBucketMs,
+    actions,
+    actionDurationMedianMs,
+  };
+}
+
+const b2FrameBucketsActionsFamily: TaishiMetricFamilyModule = {
+  id: "b2-frame-buckets-actions",
+  contribute(input) {
+    if (input.runs.length === 0) return undefined;
+    const runs = [...input.runs]
+      .map(computeTaishiB2RunMetrics)
+      .sort((a, b) => {
+        if (a.book !== b.book) return a.book.localeCompare(b.book);
+        if (a.role !== b.role) return a.role.localeCompare(b.role);
+        return a.runId.localeCompare(b.runId);
+      });
+    const section: TaishiB2FrameBucketsActionsSection = {
+      kind: "taishi-b2-frame-buckets-actions",
+      runs,
+    };
+    return { b2FrameBucketsActions: section };
+  },
+};
+
+export default b2FrameBucketsActionsFamily;

package/src/taishi-metric-families/leg-wall-clock.ts

@@ -0,0 +1,90 @@
+/**
+ * B1 leg wall-clock metric family (#325).
+ *
+ * Consumes A2 typed per-run frame spans only — no second ledger scan.
+ * Emits: per-leg wallMs, ranking by wall clock desc, median, total elapsed.
+ * Registers by file drop under taishi-metric-families/ (A2 discovery).
+ */
+import { medianNumber } from "../taishi-median.ts";
+import type { TaishiReadableRunFacts } from "../taishi-ledger.ts";
+import type { TaishiMetricFamilyModule } from "../taishi-metric-family.ts";
+
+/** One readable leg's session-frame wall clock (first usable → last usable). */
+export type TaishiLegWallClockEntry = {
+  readonly runId: string;
+  readonly book: string;
+  readonly role: string;
+  readonly wallMs: number;
+};
+
+/**
+ * Issue-page section: 腿墙钟 + 按墙钟降序腿总榜 + 中位数 + 完全耗时.
+ * Only readable in-scope runs (damaged already excluded by A1 scan).
+ */
+export type TaishiLegWallClockSection = {
+  readonly kind: "taishi-leg-wall-clock";
+  /** 腿总榜 — each row carries 腿墙钟; ordered by wallMs descending. */
+  readonly ranking: readonly TaishiLegWallClockEntry[];
+  /** 腿墙钟中位数 — even samples use shared mean-of-two-middles primitive. */
+  readonly medianWallMs: number;
+  /** 完全耗时 — Σ wallMs of every readable run on the board. */
+  readonly totalElapsedMs: number;
+};
+
+function frameSpanWallMs(span: {
+  readonly startedAt: string;
+  readonly endedAt: string;
+}): number {
+  return Date.parse(span.endedAt) - Date.parse(span.startedAt);
+}
+
+function projectEntry(facts: TaishiReadableRunFacts): TaishiLegWallClockEntry {
+  return {
+    runId: facts.runId,
+    book: facts.book,
+    role: facts.role,
+    wallMs: frameSpanWallMs(facts.frameSpan),
+  };
+}
+
+function compareRankingDesc(
+  a: TaishiLegWallClockEntry,
+  b: TaishiLegWallClockEntry,
+): number {
+  if (b.wallMs !== a.wallMs) return b.wallMs - a.wallMs;
+  if (a.book !== b.book) return a.book.localeCompare(b.book);
+  if (a.role !== b.role) return a.role.localeCompare(b.role);
+  return a.runId.localeCompare(b.runId);
+}
+
+/** Discovered by taishi-metric-families loader (default export). */
+const legWallClockFamily: TaishiMetricFamilyModule = {
+  id: "leg-wall-clock",
+  contribute(input) {
+    if (input.runs.length === 0) {
+      // No readable runs — omit section rather than invent zero metrics.
+      return undefined;
+    }
+
+    const ranking = input.runs.map(projectEntry).sort(compareRankingDesc);
+    const walls = ranking.map((leg) => leg.wallMs);
+    const medianWallMs = medianNumber(walls);
+    // runs.length > 0 ⇒ medianNumber returns a defined number.
+    if (medianWallMs === undefined) {
+      return undefined;
+    }
+
+    let totalElapsedMs = 0;
+    for (const wallMs of walls) totalElapsedMs += wallMs;
+
+    const section: TaishiLegWallClockSection = {
+      kind: "taishi-leg-wall-clock",
+      ranking,
+      medianWallMs,
+      totalElapsedMs,
+    };
+    return { legWallClock: section };
+  },
+};
+
+export default legWallClockFamily;