@akagilnc/pi-workflow-roles 0.1.1883 → 0.1.1918

package/src/ticket-trajectory.ts

@@ -38,6 +38,7 @@ import {
 } from "./package-contracts/terminating-tools.ts";
 import { PACKAGED_ROLE_REGISTRY } from "./packaged-role-registry.ts";
 
+
 /** Declared refresh bound for the same viewing surface (seconds). */
 export const DEFAULT_REFRESH_BOUNDARY_SECONDS = 30;
 
@@ -328,6 +329,8 @@ type InvocationInfo = {
   model?: string;
   provider?: string;
   thinking?: string;
+  ticketNumber?: number;
+  correlationId?: string;
 };
 
 async function readInvocation(runDir: string): Promise<InvocationInfo | undefined> {
@@ -348,6 +351,16 @@ async function readInvocation(runDir: string): Promise<InvocationInfo | undefine
         info.model = rawModel;
       }
     }
+    if (
+      typeof parsed.ticketNumber === "number" &&
+      Number.isInteger(parsed.ticketNumber) &&
+      parsed.ticketNumber >= 1
+    ) {
+      info.ticketNumber = parsed.ticketNumber;
+    }
+    if (typeof parsed.correlationId === "string" && parsed.correlationId.trim() !== "") {
+      info.correlationId = parsed.correlationId;
+    }
     return info;
   } catch (error) {
     // Only genuine absence activates the invocation fallback. Malformed JSON and
@@ -408,9 +421,8 @@ async function maxMtimeMs(paths: readonly string[]): Promise<number> {
   return max;
 }
 
-async function parseRun(ledgerDir: string, issueNumber: number, runId: string): Promise<ParsedRun> {
-  const runDir = join(ledgerDir, "issues", String(issueNumber), "runs", runId);
-  const ledgerCoord = ["issues", String(issueNumber), "runs", runId].join("/");
+async function parseRunDirectory(runDir: string, ledgerCoord: string): Promise<ParsedRun> {
+  const runId = basename(runDir);
   const evidenceTarget = await realpathOrLexicalIfMissing(runDir);
   const evidenceHref = pathToFileURL(evidenceTarget).href;
   const sessionDir = join(runDir, "session");
@@ -496,6 +508,12 @@ async function parseRun(ledgerDir: string, issueNumber: number, runId: string):
   };
 }
 
+async function parseRun(ledgerDir: string, issueNumber: number, runId: string): Promise<ParsedRun> {
+  const runDir = join(ledgerDir, "issues", String(issueNumber), "runs", runId);
+  const ledgerCoord = ["issues", String(issueNumber), "runs", runId].join("/");
+  return parseRunDirectory(runDir, ledgerCoord);
+}
+
 async function listRunIds(ledgerDir: string, issueNumber: number): Promise<string[]> {
   const runsDir = join(ledgerDir, "issues", String(issueNumber), "runs");
   try {
@@ -686,20 +704,142 @@ ${stationBlocks || "<p data-empty=\"true\">no runs</p>"}
 /**
  * Load one ticket's runs via the S1 tracer path (read-only ledger scan).
  * Factory board reuses this — no parallel receipt parser.
+ *
+ * Flat-run attribution (#176 option A): read typed `ticketNumber` from each
+ * `runs/<run>@<role>/invocation.json`. Legacy `issues/<N>/runs` remains a
+ * read-only compatibility entrance. Unbound flat runs never join a ticket.
+ */
+
+/** One flat run's typed binding projection from invocation.json. */
+export type FlatRunTicketBinding = {
+  readonly runDir: string;
+  readonly runFolder: string;
+  readonly ticketNumber?: number;
+  readonly role?: string;
+  readonly correlationId?: string;
+};
+
+/**
+ * Book-level flat-run index built once per lane/render and reused per ticket.
+ * Pure derived view of flat runs' invocation.json files — not a parallel ledger.
+ */
+export type TicketTrajectoryBookIndex = {
+  /** ticket number → flat runs bound via invocation.json ticketNumber. */
+  readonly runsByTicket: ReadonlyMap<number, readonly FlatRunTicketBinding[]>;
+  /** Flat runs with no typed ticketNumber (unknown/unbound seam). */
+  readonly unboundRuns: readonly FlatRunTicketBinding[];
+};
+
+async function listFlatRunDirectories(ledgerDir: string): Promise<string[]> {
+  const runsDir = join(resolve(ledgerDir), "runs");
+  try {
+    const entries = await readdir(runsDir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(runsDir, entry.name))
+      .sort();
+  } catch (error) {
+    if (isMissingPathError(error)) return [];
+    throw error;
+  }
+}
+
+export async function buildTicketTrajectoryBookIndex(
+  ledgerDir: string,
+): Promise<TicketTrajectoryBookIndex> {
+  const root = resolve(ledgerDir);
+  const runsByTicket = new Map<number, FlatRunTicketBinding[]>();
+  const unboundRuns: FlatRunTicketBinding[] = [];
+  for (const runDir of await listFlatRunDirectories(root)) {
+    const invocation = await readInvocation(runDir);
+    const binding: FlatRunTicketBinding = {
+      runDir,
+      runFolder: basename(runDir),
+      ...(invocation?.ticketNumber !== undefined
+        ? { ticketNumber: invocation.ticketNumber }
+        : {}),
+      ...(invocation?.role !== undefined ? { role: invocation.role } : {}),
+      ...(invocation?.correlationId !== undefined
+        ? { correlationId: invocation.correlationId }
+        : {}),
+    };
+    if (binding.ticketNumber !== undefined) {
+      const list = runsByTicket.get(binding.ticketNumber) ?? [];
+      list.push(binding);
+      runsByTicket.set(binding.ticketNumber, list);
+    } else {
+      unboundRuns.push(binding);
+    }
+  }
+  return { runsByTicket, unboundRuns };
+}
+
+export type UnboundTrajectoryRun = {
+  readonly run: TicketTrajectoryRun;
+  readonly role: string;
+  readonly observedAt: string;
+  readonly correlationId?: string;
+};
+
+/**
+ * Load unbound flat runs for the board unknown seam.
+ * Never joins any ticket. Built from the book index (once).
  */
+export async function loadUnboundTrajectoryRuns(
+  ledgerDir: string,
+  bookIndex?: TicketTrajectoryBookIndex,
+): Promise<readonly UnboundTrajectoryRun[]> {
+  const root = resolve(ledgerDir);
+  const index = bookIndex ?? (await buildTicketTrajectoryBookIndex(root));
+  const out: UnboundTrajectoryRun[] = [];
+  for (const binding of index.unboundRuns) {
+    const ledgerCoord = ["runs", binding.runFolder].join("/");
+    const run = await parseRunDirectory(binding.runDir, ledgerCoord);
+    out.push({
+      run,
+      role: binding.role ?? run.station,
+      observedAt: run.startedAt ?? run.lastActivityAt ?? "",
+      ...(binding.correlationId === undefined
+        ? {}
+        : { correlationId: binding.correlationId }),
+    });
+  }
+  return out;
+}
+
 export async function loadTicketTrajectoryRuns(
   ledgerDir: string,
   issueNumber: number,
+  bookIndex?: TicketTrajectoryBookIndex,
 ): Promise<TicketTrajectoryRun[]> {
   if (!Number.isInteger(issueNumber) || issueNumber < 1) {
     throw new Error("issueNumber must be a positive integer");
   }
   const root = resolve(ledgerDir);
-  const runIds = await listRunIds(root, issueNumber);
+  const index = bookIndex ?? (await buildTicketTrajectoryBookIndex(root));
+
   const runs: ParsedRun[] = [];
+  const seenRunDirs = new Set<string>();
+
+  // Legacy hand-dispatch path: issues/<N>/runs (read-only compatibility).
+  const runIds = await listRunIds(root, issueNumber);
   for (const runId of runIds) {
-    runs.push(await parseRun(root, issueNumber, runId));
+    const parsed = await parseRun(root, issueNumber, runId);
+    const legacyDir = join(root, "issues", String(issueNumber), "runs", runId);
+    seenRunDirs.add(resolve(legacyDir));
+    runs.push(parsed);
   }
+
+  // Flat runs bound by typed invocation.json ticketNumber.
+  const flatBindings = index.runsByTicket.get(issueNumber) ?? [];
+  for (const binding of flatBindings) {
+    const resolvedRunDir = resolve(binding.runDir);
+    if (seenRunDirs.has(resolvedRunDir)) continue;
+    seenRunDirs.add(resolvedRunDir);
+    const ledgerCoord = ["runs", binding.runFolder].join("/");
+    runs.push(await parseRunDirectory(binding.runDir, ledgerCoord));
+  }
+
   return runs;
 }
 

package/src/typed-provider-http.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared durable typed-provider HTTP observation owner.
+ * Published with both public-cli and navigator-attendance entries.
+ */
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const TYPED_HTTP_FILE = "typed-provider-http.json";
+
+export type TypedProviderHttpObservation = {
+  readonly httpStatus: number;
+  readonly provider: string;
+};
+
+function typedProviderHttpPath(runDirectory: string): string {
+  return join(runDirectory, TYPED_HTTP_FILE);
+}
+
+/**
+ * Clear any prior attempt's typed provider HTTP observation.
+ * Each initial/resume dispatch must start without inherited 429 evidence so
+ * only the current attempt can qualify v1 resume.
+ */
+export async function clearTypedProviderHttpObservation(
+  runDirectory: string,
+): Promise<void> {
+  try {
+    await unlink(typedProviderHttpPath(runDirectory));
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as { code?: unknown }).code === "ENOENT"
+    ) {
+      return;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Record a typed provider HTTP status observation for the admitted run.
+ * Only non-success HTTP statuses are persisted (authorized error evidence).
+ * A 2xx response clears any prior observation so success cannot leave stale
+ * error evidence. Never inspects diagnostic prose.
+ */
+export async function recordTypedProviderHttpStatus(
+  runDirectory: string,
+  observation: { readonly httpStatus: number; readonly provider: string },
+): Promise<void> {
+  if (observation.httpStatus >= 200 && observation.httpStatus < 300) {
+    await clearTypedProviderHttpObservation(runDirectory);
+    return;
+  }
+  const body: TypedProviderHttpObservation = {
+    httpStatus: observation.httpStatus,
+    provider: observation.provider,
+  };
+  await writeFile(
+    typedProviderHttpPath(runDirectory),
+    `${JSON.stringify(body)}\n`,
+    "utf8",
+  );
+}
+
+/**
+ * Read the latest durable typed provider HTTP observation, if any.
+ * Only ENOENT means absence (undefined). Read/parse/shape failures preserve the
+ * real cause for the existing controlled-failure chain — never laundered as absence.
+ */
+export async function readLatestTypedProviderHttpObservation(
+  runDirectory: string,
+): Promise<TypedProviderHttpObservation | undefined> {
+  let text: string;
+  try {
+    text = await readFile(typedProviderHttpPath(runDirectory), "utf8");
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as { code?: unknown }).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+  const raw: unknown = JSON.parse(text);
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("typed provider HTTP observation must be a JSON object");
+  }
+  const record = raw as Record<string, unknown>;
+  if (typeof record.httpStatus !== "number") {
+    throw new Error("typed provider HTTP observation missing numeric httpStatus");
+  }
+  if (typeof record.provider !== "string" || record.provider.trim() === "") {
+    throw new Error("typed provider HTTP observation missing non-empty provider");
+  }
+  return { httpStatus: record.httpStatus, provider: record.provider };
+}

package/src/upstream-error-testimony.ts

@@ -0,0 +1,45 @@
+/**
+ * Single authority for upstream-error testimony (#307).
+ * Non-2xx HTTP or non-empty SDK diagnostics = upstream testimony.
+ * body/code/errno project only from a confirmed-remote node.
+ * Seams keep their own shape/cause-chain reading and wrap via these primitives.
+ */
+
+/** True when value is a numeric HTTP status outside 2xx. */
+export function isNonSuccessHttpStatus(status: unknown): status is number {
+  return typeof status === "number" && (status < 200 || status >= 300);
+}
+
+/**
+ * Upstream testimony is a directly observed HTTP response or SDK-structured
+ * remote error. Pi stopReason, selected provider/model names, silent stream
+ * death, errorMessage prose (e.g. "500: …"), and locally synthesized errors
+ * are not testimony.
+ */
+export function hasUpstreamErrorTestimony(input: {
+  readonly httpStatus?: number;
+  readonly diagnostics?: unknown;
+}): boolean {
+  if (isNonSuccessHttpStatus(input.httpStatus)) return true;
+  return Array.isArray(input.diagnostics) && input.diagnostics.length > 0;
+}
+
+/**
+ * Project body/code/errno only when the caller already confirmed remote testimony
+ * on the same node. Plain local Error.code is never provider testimony.
+ */
+export function projectConfirmedRemotePayload(input: {
+  readonly body?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
+}): {
+  readonly body?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
+} {
+  return {
+    ...(input.body === undefined ? {} : { body: input.body }),
+    ...(input.code === undefined ? {} : { code: input.code }),
+    ...(input.errno === undefined ? {} : { errno: input.errno }),
+  };
+}