@akagilnc/pi-workflow-roles 0.1.1941 → 0.1.2004

package/src/run-terminal-artifacts.ts

@@ -0,0 +1,231 @@
+/**
+ * Canonical reader for run-directory typed terminal artifacts.
+ * Layout owner is settlement publish*Artifacts (report.json / error.json /
+ * audit-incomplete.json under artifacts/, plus the same publisher's durable
+ * failure fallbacks). This module only reads presence and structural
+ * readability — it does not re-derive role outcomes or invent a second
+ * candidate algorithm.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+export const RUN_TERMINAL_ARTIFACT_FILES = [
+  "report.json",
+  "error.json",
+  "audit-incomplete.json",
+] as const;
+
+export type RunTerminalArtifactFile = (typeof RUN_TERMINAL_ARTIFACT_FILES)[number];
+
+/**
+ * Fixed durable failure paths publishFailureArtifacts may settle when the
+ * conventional artifacts/error.json name cannot be written. Shared face so the
+ * reader follows the publisher — not a parallel search algorithm.
+ * Relative to the run directory.
+ */
+export const RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS = [
+  "artifacts/error.settlement.json",
+  "error.settlement.json",
+] as const;
+
+/** Unique open-ended failure names: error.<uuid>.json (publisher stem + uuid). */
+const UNIQUE_ERROR_FALLBACK_NAME =
+  /^error\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$/i;
+
+export type RunTerminalArtifactRead =
+  | { readonly status: "absent" }
+  | {
+      readonly status: "present";
+      readonly file: RunTerminalArtifactFile;
+      readonly path: string;
+      readonly body: Record<string, unknown>;
+    }
+  | {
+      readonly status: "unreadable";
+      readonly file: RunTerminalArtifactFile;
+      readonly path: string;
+      readonly reason: string;
+    };
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    error instanceof Error
+    && "code" in error
+    && (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Minimum producer-owned face shared by settlement terminal artifacts
+ * (report / error / audit-incomplete). Consumer-driven: enough to identify a
+ * usable typed terminal artifact; null, arrays, primitives, and role-less
+ * objects are unreadable (ADR 0043).
+ */
+function readUsableTerminalArtifactBody(
+  body: unknown,
+): { readonly ok: true; readonly body: Record<string, unknown> } | { readonly ok: false; readonly reason: string } {
+  if (body === null) {
+    return { ok: false, reason: "terminal artifact JSON value is null" };
+  }
+  if (!isRecord(body)) {
+    return {
+      ok: false,
+      reason: `terminal artifact JSON value is not a typed object (${Array.isArray(body) ? "array" : typeof body})`,
+    };
+  }
+  if (typeof body.role !== "string" || body.role.trim() === "") {
+    return {
+      ok: false,
+      reason: "terminal artifact missing nonblank producer-owned role field",
+    };
+  }
+  return { ok: true, body };
+}
+
+async function readTerminalArtifactAtPath(
+  path: string,
+  file: RunTerminalArtifactFile,
+): Promise<RunTerminalArtifactRead | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (isMissingPathError(error)) return undefined;
+    return {
+      status: "unreadable",
+      file,
+      path,
+      reason: errorText(error),
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      status: "unreadable",
+      file,
+      path,
+      reason:
+        error instanceof Error
+          ? error.message
+          : `terminal artifact JSON parse failed: ${String(error)}`,
+    };
+  }
+  const usable = readUsableTerminalArtifactBody(parsed);
+  if (!usable.ok) {
+    return {
+      status: "unreadable",
+      file,
+      path,
+      reason: usable.reason,
+    };
+  }
+  return { status: "present", file, path, body: usable.body };
+}
+
+async function listUniqueErrorFallbackPaths(
+  directories: readonly string[],
+): Promise<string[]> {
+  const found: string[] = [];
+  for (const dir of directories) {
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch (error) {
+      if (isMissingPathError(error)) continue;
+      throw error;
+    }
+    for (const name of names.sort((a, b) => a.localeCompare(b))) {
+      if (!UNIQUE_ERROR_FALLBACK_NAME.test(name)) continue;
+      found.push(join(dir, name));
+    }
+  }
+  return found;
+}
+
+/**
+ * Publisher run-directory face is `<runId>@<role>`. Parent-directory unique
+ * fallbacks are shared across sibling runs, so binding uses this runId only.
+ */
+function runIdFromRunDirectory(runDirectory: string): string | undefined {
+  const name = basename(runDirectory);
+  const at = name.lastIndexOf("@");
+  if (at <= 0 || at === name.length - 1) return undefined;
+  return name.slice(0, at);
+}
+
+/**
+ * Shared parent-directory unique fallback may be adopted only when the
+ * publisher-owned body.runId equals this run directory's runId. Same-run
+ * artifactsDir / runDirectory candidates keep path ownership and skip this.
+ */
+function presentUniqueFallbackBoundToRun(
+  body: Record<string, unknown>,
+  expectedRunId: string | undefined,
+): boolean {
+  if (expectedRunId === undefined) return false;
+  return typeof body.runId === "string" && body.runId === expectedRunId;
+}
+
+/**
+ * Read the first present typed terminal artifact for a run directory.
+ * Order:
+ * 1) conventional artifacts/{report,error,audit-incomplete}.json
+ * 2) publisher fixed failure fallbacks (error.settlement.json faces)
+ * 3) publisher unique error.<uuid>.json fallbacks under same-run dirs
+ * 4) shared parent-directory unique fallbacks bound by body.runId
+ *
+ * Absence of every known durable face is a valid no-receipt state (not unreadable).
+ * A present file that cannot be parsed as a usable typed JSON object is unreadable.
+ */
+export async function readRunTerminalArtifact(
+  runDirectory: string,
+): Promise<RunTerminalArtifactRead> {
+  const artifactsDir = join(runDirectory, "artifacts");
+  for (const file of RUN_TERMINAL_ARTIFACT_FILES) {
+    const path = join(artifactsDir, file);
+    const read = await readTerminalArtifactAtPath(path, file);
+    if (read !== undefined) return read;
+  }
+
+  // Publisher settled a durable failure outside the conventional error.json name.
+  for (const relative of RUN_TERMINAL_ERROR_FALLBACK_RELATIVE_PATHS) {
+    const path = join(runDirectory, relative);
+    const read = await readTerminalArtifactAtPath(path, "error.json");
+    if (read !== undefined) return read;
+  }
+
+  // Same-run unique faces: path ownership is the run itself — no cross-run risk.
+  for (const path of await listUniqueErrorFallbackPaths([artifactsDir, runDirectory])) {
+    const read = await readTerminalArtifactAtPath(path, "error.json");
+    if (read !== undefined) return read;
+  }
+
+  // Shared parent (runs/) unique faces: require publisher runId binding.
+  const expectedRunId = runIdFromRunDirectory(runDirectory);
+  for (const path of await listUniqueErrorFallbackPaths([dirname(runDirectory)])) {
+    const read = await readTerminalArtifactAtPath(path, "error.json");
+    if (read === undefined) continue;
+    if (read.status === "present") {
+      if (!presentUniqueFallbackBoundToRun(read.body, expectedRunId)) continue;
+      return read;
+    }
+    // Unreadable parent unique file cannot prove run identity — do not adopt.
+  }
+
+  return { status: "absent" };
+}
+
+/** Test/helper: basename face of a unique fallback path, if any. */
+export function isUniqueErrorFallbackName(name: string): boolean {
+  return UNIQUE_ERROR_FALLBACK_NAME.test(basename(name));
+}

package/src/taishi-cohort.ts

@@ -0,0 +1,232 @@
+/**
+ * Taishi cohort contrast aggregation (ADR 0068 / PRD #298 output ③ / #330 / #338).
+ *
+ * Query product — joins the library index, ensures each hit has a metrics page
+ * (compute-if-missing via caller-supplied sole issue kernel), then folds pages.
+ * No second ledger scan, no second parse kernel, no persistence of the contrast.
+ *
+ * Aggregation nails (ticket #330):
+ * - ratios (first-pass / success / rework): merge numerators & denominators
+ * - convergence rounds sample = one per lane×role (page byRole.convergenceRounds)
+ * - leg wall-clock median sample = one per leg (page legWallClock.ranking)
+ * - missing index row / zero denominator → typed 空缺 (LOC vacancy shape)
+ * - index hit + missing page → sync ensure (compute-if-missing); ensure failure is
+ *   typed terminal for this pull (never washed into absent/pending) — #338.
+ * - single-run unreadable on a page stays page-local exclusion, not whole failure.
+ */
+import {
+  findTaishiLibraryIndexRow,
+  readTaishiLibraryIndexPage,
+  type TaishiLibraryIndexPage,
+} from "./taishi-index.ts";
+import { medianNumber } from "./taishi-median.ts";
+import type { TaishiIssueMetricsPage } from "./taishi-page.ts";
+import type { TaishiRoleAcceptanceStats } from "./taishi-metric-families/acceptance-success-rework.ts";
+import type { TaishiLegWallClockSection } from "./taishi-metric-families/leg-wall-clock.ts";
+import type { TaishiAcceptanceSuccessReworkSection } from "./taishi-metric-families/acceptance-success-rework.ts";
+
+/**
+ * #338 page ensurer — read existing page or compute via sole issue kernel.
+ * Injected by the entry so cohort never opens a second compute route.
+ */
+export type TaishiIssuePageEnsuring = (input: {
+  readonly projectRoot: string;
+  readonly issueNumber: number;
+}) => Promise<TaishiIssueMetricsPage>;
+
+/** LOC-style optional metric — never encode absence as 0 or Infinity. */
+export type TaishiCohortOptionalMetric =
+  | { readonly status: "present"; readonly value: number }
+  | { readonly status: "absent" };
+
+export type TaishiCohortGroupInput = {
+  readonly groupLabel: string;
+  /** Issue numbers (caller typed); join key into the library index. */
+  readonly issues: readonly number[];
+};
+
+export type TaishiCohortModeInput = {
+  readonly mode: "cohort";
+  /** Exactly two groups side-by-side (before/after etc. — caller labels). */
+  readonly groups: readonly [TaishiCohortGroupInput, TaishiCohortGroupInput];
+};
+
+/** Per-issue join face: index hit + readable page → present; index miss → typed vacancy. */
+export type TaishiCohortIssueEntry =
+  | {
+      readonly issueNumber: number;
+      readonly status: "present";
+      readonly projectRoot: string;
+    }
+  | {
+      readonly issueNumber: number;
+      readonly status: "absent";
+    };
+
+/** Per-role contrast stats within one cohort group. */
+export type TaishiCohortRoleStats = {
+  readonly role: string;
+  /** Concatenated lane×role call-count samples across present issues. */
+  readonly convergenceRounds: readonly number[];
+  readonly convergenceRoundsMedian: TaishiCohortOptionalMetric;
+  readonly firstPassRate: TaishiCohortOptionalMetric;
+  readonly successRate: TaishiCohortOptionalMetric;
+};
+
+export type TaishiCohortGroupResult = {
+  readonly groupLabel: string;
+  /** One entry per input issue number, in input order (vacancy single-listed). */
+  readonly issues: readonly TaishiCohortIssueEntry[];
+  readonly byRole: readonly TaishiCohortRoleStats[];
+  readonly reworkRatio: TaishiCohortOptionalMetric;
+  readonly medianWallMs: TaishiCohortOptionalMetric;
+};
+
+export type TaishiCohortModeResult = {
+  readonly mode: "cohort";
+  readonly groups: readonly [TaishiCohortGroupResult, TaishiCohortGroupResult];
+};
+
+/** Issue page shape cohort actually reads (envelope + B-family sections). */
+type TaishiCohortSourcePage = TaishiIssueMetricsPage & {
+  readonly acceptanceSuccessRework?: TaishiAcceptanceSuccessReworkSection;
+  readonly legWallClock?: TaishiLegWallClockSection;
+};
+
+const ABSENT: TaishiCohortOptionalMetric = { status: "absent" };
+
+function presentMetric(value: number): TaishiCohortOptionalMetric {
+  return { status: "present", value };
+}
+
+function rateMetric(numerator: number, denominator: number): TaishiCohortOptionalMetric {
+  if (denominator === 0) return ABSENT;
+  return presentMetric(numerator / denominator);
+}
+
+function optionalMedian(values: readonly number[]): TaishiCohortOptionalMetric {
+  const median = medianNumber(values);
+  return median === undefined ? ABSENT : presentMetric(median);
+}
+
+type RoleAccum = {
+  convergenceRounds: number[];
+  firstPassLaneCount: number;
+  appearanceLaneCount: number;
+  successCount: number;
+  successEligibleCount: number;
+};
+
+function emptyRoleAccum(): RoleAccum {
+  return {
+    convergenceRounds: [],
+    firstPassLaneCount: 0,
+    appearanceLaneCount: 0,
+    successCount: 0,
+    successEligibleCount: 0,
+  };
+}
+
+function absorbRole(accum: RoleAccum, stats: TaishiRoleAcceptanceStats): void {
+  accum.convergenceRounds.push(...stats.convergenceRounds);
+  accum.firstPassLaneCount += stats.firstPassLaneCount;
+  accum.appearanceLaneCount += stats.appearanceLaneCount;
+  accum.successCount += stats.successCount;
+  accum.successEligibleCount += stats.successEligibleCount;
+}
+
+function finishRole(role: string, accum: RoleAccum): TaishiCohortRoleStats {
+  return {
+    role,
+    convergenceRounds: accum.convergenceRounds,
+    convergenceRoundsMedian: optionalMedian(accum.convergenceRounds),
+    firstPassRate: rateMetric(accum.firstPassLaneCount, accum.appearanceLaneCount),
+    successRate: rateMetric(accum.successCount, accum.successEligibleCount),
+  };
+}
+
+async function aggregateGroup(
+  index: TaishiLibraryIndexPage | undefined,
+  input: TaishiCohortGroupInput,
+  ensureIssuePage: TaishiIssuePageEnsuring,
+): Promise<TaishiCohortGroupResult> {
+  const issueEntries: TaishiCohortIssueEntry[] = [];
+  const roleAccums = new Map<string, RoleAccum>();
+  let reworkWallMs = 0;
+  let totalWallMs = 0;
+  let hasReworkSample = false;
+  const legWalls: number[] = [];
+
+  for (const issueNumber of input.issues) {
+    const row = findTaishiLibraryIndexRow(index, issueNumber);
+    if (row === undefined) {
+      // Only "index has no such row" is typed vacancy.
+      issueEntries.push({ issueNumber, status: "absent" });
+      continue;
+    }
+
+    // Index hit: ensure page via sole compute-if-missing kernel (read or compute).
+    // Ensure failure stays loud with issue identity — never washed to absent.
+    const page = (await ensureIssuePage({
+      projectRoot: row.projectRoot,
+      issueNumber,
+    })) as TaishiCohortSourcePage;
+
+    issueEntries.push({
+      issueNumber,
+      status: "present",
+      projectRoot: row.projectRoot,
+    });
+
+    const acceptance = page.acceptanceSuccessRework;
+    if (acceptance !== undefined) {
+      for (const roleStats of acceptance.byRole) {
+        const accum = roleAccums.get(roleStats.role) ?? emptyRoleAccum();
+        absorbRole(accum, roleStats);
+        roleAccums.set(roleStats.role, accum);
+      }
+      reworkWallMs += acceptance.rework.reworkWallMs;
+      totalWallMs += acceptance.rework.totalWallMs;
+      hasReworkSample = true;
+    }
+
+    const legWallClock = page.legWallClock;
+    if (legWallClock !== undefined) {
+      for (const leg of legWallClock.ranking) {
+        legWalls.push(leg.wallMs);
+      }
+    }
+  }
+
+  const byRole = [...roleAccums.keys()]
+    .sort((a, b) => a.localeCompare(b))
+    .map((role) => finishRole(role, roleAccums.get(role)!));
+
+  return {
+    groupLabel: input.groupLabel,
+    issues: issueEntries,
+    byRole,
+    reworkRatio: hasReworkSample ? rateMetric(reworkWallMs, totalWallMs) : ABSENT,
+    medianWallMs: optionalMedian(legWalls),
+  };
+}
+
+/**
+ * Run cohort contrast: join index by issueNumber, ensure pages (#338), fold,
+ * emit two side-by-side group results. Page writes happen only through the
+ * injected ensurer (sole issue kernel + existing writer) — cohort itself is
+ * not a second compute kernel or projection.
+ */
+export async function runTaishiCohortMode(
+  ledgerHome: string,
+  input: TaishiCohortModeInput,
+  ensureIssuePage: TaishiIssuePageEnsuring,
+): Promise<TaishiCohortModeResult> {
+  const index = await readTaishiLibraryIndexPage(ledgerHome);
+  const group0 = await aggregateGroup(index, input.groups[0], ensureIssuePage);
+  const group1 = await aggregateGroup(index, input.groups[1], ensureIssuePage);
+  return {
+    mode: "cohort",
+    groups: [group0, group1],
+  };
+}