@akagilnc/pi-workflow-roles 0.1.1941 → 0.1.2004

package/src/taishi-metric-families/round-timeline.ts

@@ -0,0 +1,201 @@
+/**
+ * B4 round-timeline metric family (#328).
+ *
+ * per-lane (book) run sequence sorted by start time: role, wall clock,
+ * receipt status or death channel, judge classCount when present.
+ * Unreadable runs appear as placeholder rows sorted by A2 firstFrameAt when
+ * present; only when that fact is absent do they annotate absent and sort last.
+ *
+ * Consumes only A2 typed run facts + unreadable entries — no second scan.
+ */
+import type { TaishiReadableRunFacts } from "../taishi-ledger.ts";
+import type { TaishiMetricFamilyModule } from "../taishi-metric-family.ts";
+import type {
+  TaishiFirstFrameAt,
+  TaishiMissingSource,
+  TaishiUnreadableRun,
+} from "../taishi-page.ts";
+
+export type TaishiRoundTimelineTerminal =
+  | {
+      readonly kind: "receipt";
+      readonly status: string;
+      readonly classCount?: number;
+    }
+  | {
+      readonly kind: "death";
+      readonly channel: "no-receipt" | "error" | "audit-incomplete";
+    };
+
+export type TaishiRoundTimelineRunRow = {
+  readonly kind: "run";
+  readonly runId: string;
+  readonly book: string;
+  readonly role: string;
+  readonly startedAt: string;
+  readonly endedAt: string;
+  readonly wallMs: number;
+  readonly terminal: TaishiRoundTimelineTerminal;
+};
+
+export type TaishiRoundTimelineUnreadableRow = {
+  readonly kind: "unreadable";
+  readonly runId: string;
+  readonly book: string;
+  readonly missingSources: readonly TaishiMissingSource[];
+  readonly reason: string;
+  /**
+   * Projected from A2 unreadable.firstFrameAt. Present → sort by `at`;
+   * absent → lane tail.
+   */
+  readonly firstFrameAt: TaishiFirstFrameAt;
+};
+
+export type TaishiRoundTimelineRow =
+  | TaishiRoundTimelineRunRow
+  | TaishiRoundTimelineUnreadableRow;
+
+export type TaishiRoundTimelineLane = {
+  readonly lane: string;
+  readonly rows: readonly TaishiRoundTimelineRow[];
+};
+
+export type TaishiRoundTimelineSection = {
+  readonly kind: "taishi-round-timeline";
+  readonly lanes: readonly TaishiRoundTimelineLane[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function wallMsFromSpan(startedAt: string, endedAt: string): number {
+  return Date.parse(endedAt) - Date.parse(startedAt);
+}
+
+function readOutcomeStatus(body: Record<string, unknown>): string | undefined {
+  if (!isRecord(body.outcome)) return undefined;
+  const status = body.outcome.status;
+  if (typeof status !== "string" || status.trim() === "") return undefined;
+  return status;
+}
+
+function readClassCount(body: Record<string, unknown>): number | undefined {
+  if (!isRecord(body.outcome)) return undefined;
+  if (!isRecord(body.outcome.decisiveFacts)) return undefined;
+  const classCount = body.outcome.decisiveFacts.classCount;
+  if (typeof classCount !== "number" || !Number.isFinite(classCount)) {
+    return undefined;
+  }
+  return classCount;
+}
+
+function projectTerminal(facts: TaishiReadableRunFacts): TaishiRoundTimelineTerminal {
+  if (facts.terminal.status === "absent") {
+    return { kind: "death", channel: "no-receipt" };
+  }
+  if (facts.terminal.file === "error.json") {
+    return { kind: "death", channel: "error" };
+  }
+  if (facts.terminal.file === "audit-incomplete.json") {
+    return { kind: "death", channel: "audit-incomplete" };
+  }
+  // report.json — receipt face; classCount only when producer wrote a number.
+  const status = readOutcomeStatus(facts.terminal.body);
+  const classCount = readClassCount(facts.terminal.body);
+  const receiptStatus = status ?? "unparsed";
+  if (classCount === undefined) {
+    return { kind: "receipt", status: receiptStatus };
+  }
+  return { kind: "receipt", status: receiptStatus, classCount };
+}
+
+function projectRunRow(facts: TaishiReadableRunFacts): TaishiRoundTimelineRunRow {
+  const { startedAt, endedAt } = facts.frameSpan;
+  return {
+    kind: "run",
+    runId: facts.runId,
+    book: facts.book,
+    role: facts.role,
+    startedAt,
+    endedAt,
+    wallMs: wallMsFromSpan(startedAt, endedAt),
+    terminal: projectTerminal(facts),
+  };
+}
+
+function projectUnreadableRow(
+  entry: TaishiUnreadableRun,
+): TaishiRoundTimelineUnreadableRow {
+  return {
+    kind: "unreadable",
+    runId: entry.runId,
+    book: entry.book,
+    missingSources: entry.missingSources,
+    reason: entry.reason,
+    firstFrameAt: entry.firstFrameAt,
+  };
+}
+
+/** Sort key: startedAt / present firstFrameAt ascending; absent → +∞ (lane tail). */
+function rowSortStartedAt(row: TaishiRoundTimelineRow): string | undefined {
+  if (row.kind === "run") return row.startedAt;
+  if (row.firstFrameAt.status === "present") return row.firstFrameAt.at;
+  return undefined;
+}
+
+function compareRows(a: TaishiRoundTimelineRow, b: TaishiRoundTimelineRow): number {
+  const aStart = rowSortStartedAt(a);
+  const bStart = rowSortStartedAt(b);
+  if (aStart === undefined && bStart === undefined) {
+    return a.runId.localeCompare(b.runId);
+  }
+  if (aStart === undefined) return 1;
+  if (bStart === undefined) return -1;
+  if (aStart !== bStart) return aStart.localeCompare(bStart);
+  return a.runId.localeCompare(b.runId);
+}
+
+function buildLanes(
+  runs: readonly TaishiReadableRunFacts[],
+  unreadable: readonly TaishiUnreadableRun[],
+): readonly TaishiRoundTimelineLane[] {
+  const byLane = new Map<string, TaishiRoundTimelineRow[]>();
+
+  const push = (lane: string, row: TaishiRoundTimelineRow): void => {
+    const list = byLane.get(lane);
+    if (list === undefined) byLane.set(lane, [row]);
+    else list.push(row);
+  };
+
+  for (const facts of runs) {
+    push(facts.book, projectRunRow(facts));
+  }
+  for (const entry of unreadable) {
+    push(entry.book, projectUnreadableRow(entry));
+  }
+
+  return [...byLane.keys()]
+    .sort((a, b) => a.localeCompare(b))
+    .map((lane) => ({
+      lane,
+      rows: [...(byLane.get(lane) ?? [])].sort(compareRows),
+    }));
+}
+
+/** Discovered by taishi-metric-families loader (default export). */
+const roundTimelineFamily: TaishiMetricFamilyModule = {
+  id: "round-timeline",
+  contribute(input) {
+    if (input.runs.length === 0 && input.unreadable.length === 0) {
+      return undefined;
+    }
+    const section: TaishiRoundTimelineSection = {
+      kind: "taishi-round-timeline",
+      lanes: buildLanes(input.runs, input.unreadable),
+    };
+    return { roundTimeline: section };
+  },
+};
+
+export default roundTimelineFamily;

package/src/taishi-metric-families.ts

@@ -0,0 +1,36 @@
+/**
+ * Issue-mode metric-family registry (page composition point).
+ *
+ * B1–B4 families are statically imported so the public single-file bundle
+ * (`dist/public-cli/main.js`) carries them. Dynamic directory discovery cannot
+ * see sibling modules inside that bundle and must not be a second compute kernel.
+ *
+ * New issue-page families register by adding a static import + list entry here
+ * (same loader seam; no parallel assembly path).
+ */
+import type { TaishiMetricFamilyModule } from "./taishi-metric-family.ts";
+import acceptanceSuccessReworkFamily from "./taishi-metric-families/acceptance-success-rework.ts";
+import b2FrameBucketsActionsFamily from "./taishi-metric-families/b2-frame-buckets-actions.ts";
+import legWallClockFamily from "./taishi-metric-families/leg-wall-clock.ts";
+import roundTimelineFamily from "./taishi-metric-families/round-timeline.ts";
+
+/**
+ * Production issue-page family modules in stable id order.
+ * Static graph — reachable from source and from the public CLI bundle alike.
+ */
+const ISSUE_METRIC_FAMILIES: readonly TaishiMetricFamilyModule[] = [
+  acceptanceSuccessReworkFamily,
+  b2FrameBucketsActionsFamily,
+  legWallClockFamily,
+  roundTimelineFamily,
+].sort((a, b) => a.id.localeCompare(b.id));
+
+/**
+ * Load the registered issue-page metric families.
+ * Always resolves the static package registry (never readdir of a sibling tree).
+ */
+export async function loadTaishiIssueMetricFamilies(): Promise<
+  readonly TaishiMetricFamilyModule[]
+> {
+  return ISSUE_METRIC_FAMILIES;
+}

package/src/taishi-metric-family.ts

@@ -0,0 +1,41 @@
+/**
+ * Taishi issue-page metric-family registration seam (A2).
+ *
+ * Each B/C-wave family owns one module file under taishi-metric-families/
+ * and is listed in the static loader (taishi-metric-families.ts) so the
+ * public single-file bundle carries every family. Families only contribute
+ * optional page sections from typed run facts; they do not open a second
+ * scan, entry, or page writer.
+ */
+import type { TaishiReadableRunFacts } from "./taishi-ledger.ts";
+import type { TaishiUnreadableRun } from "./taishi-page.ts";
+
+export type TaishiMetricFamilyInput = {
+  readonly projectRoot: string;
+  readonly runs: readonly TaishiReadableRunFacts[];
+  readonly unreadable: readonly TaishiUnreadableRun[];
+};
+
+/** Optional top-level page sections contributed by one family module. */
+export type TaishiMetricFamilyContribution = {
+  readonly [sectionKey: string]: unknown;
+};
+
+export type TaishiMetricFamilyModule = {
+  readonly id: string;
+  contribute(input: TaishiMetricFamilyInput): TaishiMetricFamilyContribution | undefined;
+};
+
+/** Fold discovered family modules into one section bag (Object.assign order). */
+export function composeTaishiMetricFamilySections(
+  families: readonly TaishiMetricFamilyModule[],
+  input: TaishiMetricFamilyInput,
+): TaishiMetricFamilyContribution {
+  const sections: Record<string, unknown> = {};
+  for (const family of families) {
+    const piece = family.contribute(input);
+    if (piece === undefined) continue;
+    Object.assign(sections, piece);
+  }
+  return sections;
+}

package/src/taishi-model-groups.ts

@@ -0,0 +1,198 @@
+/**
+ * Taishi model-group mode kernel (PRD #298 output ④ / ticket #331).
+ *
+ * Per-leg raw model grouping (single | mixed:ordered-dedup whole-leg unit)
+ * over a caller-typed issue set. Combination mapping is display-alias only:
+ * raw group identity and denominators never merge.
+ *
+ * Acceptance / success faces reuse the B3 terminal map (受理≠成功, planned
+ * out of success den) — no second outcome kernel.
+ */
+import { buildAcceptanceSuccessReworkSection } from "./taishi-metric-families/acceptance-success-rework.ts";
+import type { TaishiReadableRunFacts } from "./taishi-ledger.ts";
+import { medianNumber } from "./taishi-median.ts";
+import type { TaishiUnreadableRun } from "./taishi-page.ts";
+
+/** One raw model group with rates over legs in that group. */
+export type TaishiModelGroupRow = {
+  /** Stable raw identity (single model id, or `mixed:a+b` ordered-dedup). */
+  readonly rawGroupKey: string;
+  /** Display label after optional alias map; equals rawGroupKey when unmapped. */
+  readonly displayName: string;
+  readonly legCount: number;
+  readonly acceptedCount: number;
+  /** acceptedCount / legCount; undefined when legCount is 0. */
+  readonly acceptanceRate: number | undefined;
+  readonly successCount: number;
+  /** Success-rate den (accepted ∧ ¬planned-duty), matching B3. */
+  readonly successEligibleCount: number;
+  /** successCount / successEligibleCount; undefined when den is 0. */
+  readonly successRate: number | undefined;
+  readonly noReceiptCount: number;
+  /** noReceiptCount / legCount; undefined when legCount is 0. */
+  readonly noReceiptRate: number | undefined;
+  /** Leg wall-clock median (ms); even count → mean of two middles. */
+  readonly wallClockMedianMs: number | undefined;
+};
+
+/** Typed model-group query output (not a persisted issue page). */
+export type TaishiModelGroupsPage = {
+  readonly kind: "taishi-model-groups";
+  readonly mode: "model-groups";
+  /** Caller-typed scope (physical identities), stable-sorted. */
+  readonly projectRoots: readonly string[];
+  readonly groups: readonly TaishiModelGroupRow[];
+  /** Model-bearing legs only (sum of group dens); model-absent listed under unreadable. */
+  readonly legCount: number;
+  readonly unreadableCount: number;
+  /** Scan damage + session-model vacancy (no empty-string group). */
+  readonly unreadable: readonly TaishiUnreadableRun[];
+};
+
+/**
+ * Build the raw group key for one leg from its ordered-unique model sequence.
+ * Empty sequence → undefined (no inventable group; caller lists as typed vacancy).
+ * One model → that raw id. Multi → `mixed:` + `+`-joined ordered uniques.
+ */
+export function taishiModelGroupKey(models: readonly string[]): string | undefined {
+  if (models.length === 0) return undefined;
+  if (models.length === 1) return models[0]!;
+  return `mixed:${models.join("+")}`;
+}
+
+function rate(numerator: number, denominator: number): number | undefined {
+  if (denominator === 0) return undefined;
+  return numerator / denominator;
+}
+
+function displayNameFor(
+  rawGroupKey: string,
+  combinationMapping: Readonly<Record<string, string>> | undefined,
+): string {
+  if (combinationMapping === undefined) return rawGroupKey;
+  const aliased = combinationMapping[rawGroupKey];
+  return aliased === undefined ? rawGroupKey : aliased;
+}
+
+function sortUnreadable(
+  unreadable: readonly TaishiUnreadableRun[],
+): TaishiUnreadableRun[] {
+  return [...unreadable].sort((a, b) => {
+    if (a.book !== b.book) return a.book.localeCompare(b.book);
+    return a.runId.localeCompare(b.runId);
+  });
+}
+
+/**
+ * Legs with no usable session model identity cannot join any model group.
+ * Reuse the typed unreadable path (locatable missing-source) — not an empty-key group.
+ */
+function modelIdentityAbsentEntry(run: TaishiReadableRunFacts): TaishiUnreadableRun {
+  return {
+    runId: run.runId,
+    book: run.book,
+    missingSources: ["session-model"],
+    reason: "session has no usable model identity",
+    firstFrameAt: { status: "present", at: run.frameSpan.startedAt },
+    // Readable legs already admitted a full span — retain end edge for lastActivityAt.
+    lastFrameAt: { status: "present", at: run.frameSpan.endedAt },
+  };
+}
+
+/**
+ * Aggregate readable runs into model groups.
+ * Stats identity is always the raw key; mapping only projects displayName.
+ * Model-identity vacancy is excluded from every group den and listed as unreadable.
+ */
+export function buildTaishiModelGroupsPage(input: {
+  readonly projectRoots: readonly string[];
+  readonly runs: readonly TaishiReadableRunFacts[];
+  readonly unreadable: readonly TaishiUnreadableRun[];
+  readonly combinationMapping?: Readonly<Record<string, string>>;
+}): TaishiModelGroupsPage {
+  // Split before B3 projection: only model-bearing legs enter group dens.
+  // Carry the non-empty raw key so aggregation need not re-check vacancy.
+  const groupedRuns: { run: TaishiReadableRunFacts; rawGroupKey: string }[] = [];
+  const modelAbsent: TaishiUnreadableRun[] = [];
+  for (const run of input.runs) {
+    const rawGroupKey = taishiModelGroupKey(run.models);
+    if (rawGroupKey === undefined) {
+      modelAbsent.push(modelIdentityAbsentEntry(run));
+    } else {
+      groupedRuns.push({ run, rawGroupKey });
+    }
+  }
+
+  const acceptance = buildAcceptanceSuccessReworkSection(
+    groupedRuns.map(({ run }) => run),
+  );
+  const legByRunId = new Map(
+    (acceptance?.legs ?? []).map((leg) => [leg.runId, leg] as const),
+  );
+
+  type Acc = {
+    acceptedCount: number;
+    successCount: number;
+    successEligibleCount: number;
+    noReceiptCount: number;
+    walls: number[];
+  };
+  const byRaw = new Map<string, Acc>();
+
+  for (const { run, rawGroupKey } of groupedRuns) {
+    const leg = legByRunId.get(run.runId);
+    if (leg === undefined) {
+      // Readable run must project through B3 map; missing is an invariant break.
+      throw new Error(
+        `taishi model-groups: missing acceptance projection for run ${run.runId}`,
+      );
+    }
+    let acc = byRaw.get(rawGroupKey);
+    if (acc === undefined) {
+      acc = {
+        acceptedCount: 0,
+        successCount: 0,
+        successEligibleCount: 0,
+        noReceiptCount: 0,
+        walls: [],
+      };
+      byRaw.set(rawGroupKey, acc);
+    }
+    if (leg.accepted) acc.acceptedCount += 1;
+    if (leg.success) acc.successCount += 1;
+    if (leg.successEligible) acc.successEligibleCount += 1;
+    if (leg.noReceipt) acc.noReceiptCount += 1;
+    acc.walls.push(leg.wallMs);
+  }
+
+  const rawKeys = [...byRaw.keys()].sort((a, b) => a.localeCompare(b));
+  const groups: TaishiModelGroupRow[] = rawKeys.map((rawGroupKey) => {
+    const acc = byRaw.get(rawGroupKey)!;
+    const legCount = acc.walls.length;
+    return {
+      rawGroupKey,
+      displayName: displayNameFor(rawGroupKey, input.combinationMapping),
+      legCount,
+      acceptedCount: acc.acceptedCount,
+      acceptanceRate: rate(acc.acceptedCount, legCount),
+      successCount: acc.successCount,
+      successEligibleCount: acc.successEligibleCount,
+      successRate: rate(acc.successCount, acc.successEligibleCount),
+      noReceiptCount: acc.noReceiptCount,
+      noReceiptRate: rate(acc.noReceiptCount, legCount),
+      wallClockMedianMs: medianNumber(acc.walls),
+    };
+  });
+
+  const unreadable = sortUnreadable([...input.unreadable, ...modelAbsent]);
+
+  return {
+    kind: "taishi-model-groups",
+    mode: "model-groups",
+    projectRoots: [...input.projectRoots].sort((a, b) => a.localeCompare(b)),
+    groups,
+    legCount: groupedRuns.length,
+    unreadableCount: unreadable.length,
+    unreadable,
+  };
+}