@akagilnc/pi-workflow-roles 0.1.5797 → 0.1.5820

package/dist/ticket-trajectory.js

@@ -0,0 +1,843 @@
+/**
+ * Single-ticket trajectory tracer (factory board S1).
+ *
+ * Mechanism, not a role: deterministic scan → HTML. Unique seam:
+ *   (ledgerDir, ticketSnapshot, now) → HTML
+ *
+ * Station resolution (four-layer fallback):
+ *   1) terminating tool name inside the session (ak_<role>_output)
+ *   2) current.json invocation role
+ *   3) run-directory name heuristic
+ *   4) unknown (still listed; never dropped)
+ *
+ * Receipt trust: only successful toolResults that pass typed contract
+ * validation count as round results. Prior rejected attempts stay attempts.
+ *
+ * Page lifecycle: startTicketTrajectoryPage owns refresh regeneration to an
+ * explicit output path outside the ledger and declares the bound; one-shot
+ * write does not advertise refresh. Regeneration faults surface the original
+ * cause via handle.closed / stop(). Caller stops the handle.
+ */
+import { readSectionSync } from "./run-dossier.js";
+import { lstat, mkdir, readdir, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { writeFileAtomically } from "./atomic-write.js";
+import { errnoCode, pathContainedIn, physicalPathIdentity, } from "./activation-ledger-topology.js";
+import { formatDurationZh, formatLocalDateTime, formatTokensCompact, formatUsdPrecise, } from "./human-format.js";
+import { listBookRunDirectories, sessionDirectoryOf } from "./role-run-placement.js";
+import { sitianVolumeDirectory } from "./sitian-appender.js";
+import { isPositiveTicketNumber, readRunTicketNumber } from "./run-ticket-number.js";
+import { extractSessionTimestampSpan, readLedgerSessionJsonl, } from "./ledger-session-read.js";
+export { readLedgerSessionJsonl } from "./ledger-session-read.js";
+import { AcceptedDetailsContractError, acceptedFacts, isTerminatingToolName, validateAcceptedDetails, } from "./package-contracts/terminating-tools.js";
+import { LEGACY_REVIEW_OUTPUT_ROLES, PACKAGED_ROLE_REGISTRY } from "./packaged-role-registry.js";
+import { isRecord, isMissingPathError } from "./unknown-value.js";
+/** Declared refresh bound for the same viewing surface (seconds). */
+export const DEFAULT_REFRESH_BOUNDARY_SECONDS = 30;
+/** realpath when the node exists; lexical path only for recognized absence — never for other errors. */
+async function realpathOrLexicalIfMissing(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return path;
+        throw error;
+    }
+}
+const TOOL_TO_ROLE = new Map([
+    ...PACKAGED_ROLE_REGISTRY.filter((entry) => entry.outputTool !== "ak_submission_output")
+        .map((entry) => [entry.outputTool, entry.role]),
+    ...LEGACY_REVIEW_OUTPUT_ROLES,
+]);
+const NAME_PREFIX_ROLES = PACKAGED_ROLE_REGISTRY.map((entry) => entry.role);
+function roleFromToolName(toolName) {
+    return TOOL_TO_ROLE.get(toolName);
+}
+function roleFromRunName(runId) {
+    const base = runId.split("@")[0] ?? runId;
+    const lower = base.toLowerCase();
+    // plan-court / *-court* → judge (ticket-court family)
+    if (/(^|[-_])court([-_]|$)/.test(lower) || lower.startsWith("plan-court"))
+        return "judge";
+    for (const role of NAME_PREFIX_ROLES) {
+        if (lower === role || lower.startsWith(`${role}-`) || lower.startsWith(`${role}_`))
+            return role;
+    }
+    // review-* shorthand used heavily in the home ledger
+    if (lower.startsWith("review"))
+        return "reviewer";
+    return undefined;
+}
+function escapeHtml(text) {
+    return text
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function attr(value) {
+    return escapeHtml(value);
+}
+function extractModelFields(rows) {
+    let model = "";
+    let provider = "";
+    let thinking = "";
+    for (const row of rows) {
+        if (row.type === "model_change") {
+            if (typeof row.provider === "string" && row.provider)
+                provider = row.provider;
+            if (typeof row.modelId === "string" && row.modelId)
+                model = row.modelId;
+        }
+        if (row.type === "thinking_level_change" && typeof row.thinkingLevel === "string" && row.thinkingLevel) {
+            thinking = row.thinkingLevel;
+        }
+        const message = isRecord(row.message) ? row.message : undefined;
+        if (message?.role === "assistant") {
+            if (typeof message.model === "string" && message.model)
+                model = message.model;
+            if (typeof message.provider === "string" && message.provider)
+                provider = message.provider;
+        }
+    }
+    return { model, provider, thinking };
+}
+/** Sum budget dollars and tokens from message.usage on session rows. */
+function extractUsageTotals(rows) {
+    let costUsd = 0;
+    let totalTokens = 0;
+    for (const row of rows) {
+        const message = isRecord(row.message) ? row.message : undefined;
+        const usage = message && isRecord(message.usage) ? message.usage : isRecord(row.usage) ? row.usage : undefined;
+        if (!usage)
+            continue;
+        if (typeof usage.totalTokens === "number" && Number.isFinite(usage.totalTokens)) {
+            totalTokens += usage.totalTokens;
+        }
+        const cost = isRecord(usage.cost) ? usage.cost : undefined;
+        if (cost && typeof cost.total === "number" && Number.isFinite(cost.total)) {
+            costUsd += cost.total;
+        }
+    }
+    return { costUsd, totalTokens };
+}
+function wallMsBetween(startedAt, endedAt) {
+    if (!startedAt || !endedAt)
+        return 0;
+    const start = Date.parse(startedAt);
+    const end = Date.parse(endedAt);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end < start)
+        return 0;
+    return end - start;
+}
+function extractTerminatingLifecycle(rows) {
+    let callAttempts = 0;
+    let resultAttempts = 0;
+    const toolNames = [];
+    let hasResult = false;
+    let resultStatus = "";
+    for (const row of rows) {
+        const message = isRecord(row.message) ? row.message : undefined;
+        if (!message)
+            continue;
+        if (message.role === "assistant" && Array.isArray(message.content)) {
+            for (const part of message.content) {
+                if (!isRecord(part) || part.type !== "toolCall")
+                    continue;
+                const name = part.name;
+                if (typeof name === "string" && isTerminatingToolName(name)) {
+                    callAttempts += 1;
+                    toolNames.push(name);
+                }
+            }
+        }
+        if (message.role === "toolResult" && typeof message.toolName === "string" && isTerminatingToolName(message.toolName)) {
+            resultAttempts += 1;
+            toolNames.push(message.toolName);
+            if (message.isError === true)
+                continue;
+            if (!isRecord(message.details))
+                continue;
+            try {
+                const details = validateAcceptedDetails(message.toolName, message.details);
+                const facts = acceptedFacts(message.toolName, details);
+                hasResult = true;
+                resultStatus = facts.status ?? "";
+            }
+            catch (error) {
+                if (error instanceof AcceptedDetailsContractError)
+                    continue;
+                throw error;
+            }
+        }
+    }
+    // Prefer toolCall count; fall back to toolResult count when calls were clipped away.
+    const attemptCount = callAttempts > 0 ? callAttempts : resultAttempts;
+    return { attemptCount, toolNames, hasResult, resultStatus };
+}
+async function readInvocation(runDir) {
+    try {
+        const parsed = readSectionSync(runDir, "invocation");
+        if (parsed === undefined)
+            return undefined;
+        const info = {};
+        if (typeof parsed.role === "string" && parsed.role.trim())
+            info.role = parsed.role.trim();
+        if (typeof parsed.thinking === "string" && parsed.thinking.trim())
+            info.thinking = parsed.thinking.trim();
+        if (typeof parsed.provider === "string" && parsed.provider.trim()) {
+            info.provider = parsed.provider.trim();
+        }
+        if (typeof parsed.model === "string" && parsed.model.trim()) {
+            const rawModel = parsed.model.trim();
+            if (rawModel.includes("/")) {
+                const slash = rawModel.indexOf("/");
+                // Combined provider/model form (legacy pages).
+                if (info.provider === undefined)
+                    info.provider = rawModel.slice(0, slash);
+                info.model = rawModel.slice(slash + 1);
+            }
+            else {
+                info.model = rawModel;
+            }
+        }
+        if (typeof parsed.correlationId === "string" && parsed.correlationId.trim() !== "") {
+            info.correlationId = parsed.correlationId;
+        }
+        // Display placement: board pages first, then migration-derived (never forges board).
+        const ticketNumber = await readRunTicketNumber(runDir);
+        if (ticketNumber !== undefined)
+            info.ticketNumber = ticketNumber;
+        return info;
+    }
+    catch (error) {
+        // Only genuine absence activates the invocation fallback. Malformed JSON and
+        // unexpected IO failures retain their cause — never relabeled as "no invocation."
+        if (isMissingPathError(error))
+            return undefined;
+        throw error;
+    }
+}
+function resolveStation(input) {
+    if (input.invocationRole && input.toolNames.includes("ak_submission_output")) {
+        return { station: input.invocationRole, stationSource: "invocation" };
+    }
+    for (const toolName of input.toolNames) {
+        const role = roleFromToolName(toolName);
+        if (role)
+            return { station: role, stationSource: "tool" };
+    }
+    // Also accept tool names observed only via accepted results order
+    if (input.invocationRole) {
+        return { station: input.invocationRole, stationSource: "invocation" };
+    }
+    const byName = roleFromRunName(input.runId);
+    if (byName)
+        return { station: byName, stationSource: "name" };
+    return { station: "unknown", stationSource: "unknown" };
+}
+async function listSessionFiles(sessionDir) {
+    try {
+        const entries = await readdir(sessionDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+            .map((entry) => join(sessionDir, entry.name))
+            .sort();
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return [];
+        throw error;
+    }
+}
+/** Reviewer parallel axis-leg sessions live under session/reviewer-legs/. */
+async function listAxisLegSessionFiles(sessionDir) {
+    return listSessionFiles(sitianVolumeDirectory(sessionDir, "reviewer-legs"));
+}
+async function maxMtimeMs(paths) {
+    let max = 0;
+    for (const path of paths) {
+        try {
+            const st = await lstat(path);
+            const ms = st.mtimeMs;
+            if (Number.isFinite(ms) && ms > max)
+                max = ms;
+        }
+        catch (error) {
+            if (isMissingPathError(error))
+                continue;
+            throw error;
+        }
+    }
+    return max;
+}
+async function parseRunDirectory(runDir, ledgerCoord) {
+    const runId = basename(runDir);
+    const evidenceTarget = await realpathOrLexicalIfMissing(runDir);
+    const evidenceHref = pathToFileURL(evidenceTarget).href;
+    const sessionDir = sessionDirectoryOf(runDir);
+    const sessionFiles = await listSessionFiles(sessionDir);
+    const axisLegFiles = await listAxisLegSessionFiles(sessionDir);
+    const rows = [];
+    for (const file of sessionFiles) {
+        rows.push(...(await readLedgerSessionJsonl(file)));
+    }
+    // Prefer explicit session header timestamp as start; else first record.
+    let startedAt;
+    for (const row of rows) {
+        if (row.type === "session" && typeof row.timestamp === "string") {
+            startedAt = row.timestamp;
+            break;
+        }
+        if (!startedAt && typeof row.timestamp === "string")
+            startedAt = row.timestamp;
+    }
+    const parentSpan = extractSessionTimestampSpan(rows);
+    if (startedAt === undefined)
+        startedAt = parentSpan.startedAt;
+    const endedAt = parentSpan.endedAt;
+    const parentUsage = extractUsageTotals(rows);
+    let costUsd = parentUsage.costUsd;
+    let totalTokens = parentUsage.totalTokens;
+    let axisWallMs = 0;
+    // Newest content activity across parent + axis (not parent-only endedAt).
+    let lastActivityAt = parentSpan.endedAt;
+    for (const file of axisLegFiles) {
+        const legRows = await readLedgerSessionJsonl(file);
+        const legUsage = extractUsageTotals(legRows);
+        costUsd += legUsage.costUsd;
+        totalTokens += legUsage.totalTokens;
+        const legSpan = extractSessionTimestampSpan(legRows);
+        axisWallMs += wallMsBetween(legSpan.startedAt, legSpan.endedAt);
+        if (legSpan.endedAt !== undefined &&
+            (lastActivityAt === undefined || legSpan.endedAt > lastActivityAt)) {
+            lastActivityAt = legSpan.endedAt;
+        }
+    }
+    const mtimeMs = await maxMtimeMs([...sessionFiles, ...axisLegFiles]);
+    const lifecycle = extractTerminatingLifecycle(rows);
+    const models = extractModelFields(rows);
+    const invocation = await readInvocation(runDir);
+    const { station, stationSource } = resolveStation({
+        toolNames: lifecycle.toolNames,
+        runId,
+        ...(invocation?.role !== undefined ? { invocationRole: invocation.role } : {}),
+    });
+    // Session mechanical fields win; the invocation section fills gaps only.
+    let { model, provider, thinking } = models;
+    if (invocation) {
+        if (!thinking && invocation.thinking)
+            thinking = invocation.thinking;
+        if (!provider && invocation.provider)
+            provider = invocation.provider;
+        if (!model && invocation.model)
+            model = invocation.model;
+    }
+    return {
+        runId,
+        ledgerCoord,
+        evidenceHref,
+        ...(startedAt !== undefined ? { startedAt } : {}),
+        ...(endedAt !== undefined ? { endedAt } : {}),
+        ...(lastActivityAt !== undefined ? { lastActivityAt } : {}),
+        mtimeMs,
+        costUsd,
+        totalTokens,
+        axisWallMs,
+        station,
+        stationSource,
+        attemptCount: lifecycle.attemptCount,
+        hasResult: lifecycle.hasResult,
+        resultStatus: lifecycle.resultStatus,
+        model,
+        provider,
+        thinking,
+    };
+}
+async function parseRun(ledgerDir, issueNumber, runId) {
+    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, issueNumber) {
+    const runsDir = join(ledgerDir, "issues", String(issueNumber), "runs");
+    try {
+        const entries = await readdir(runsDir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return [];
+        throw error;
+    }
+}
+function sortRuns(runs) {
+    return [...runs].sort((a, b) => {
+        const at = a.startedAt ?? "";
+        const bt = b.startedAt ?? "";
+        if (at !== bt)
+            return at.localeCompare(bt);
+        return a.runId.localeCompare(b.runId);
+    });
+}
+/**
+ * Render station/run blocks from already-loaded S1 runs.
+ * Shared by the single-ticket page and the S2 factory board (no second receipt parser).
+ */
+function formatUsd(value) {
+    // Full precision mechanical string — presentation may round; machines parse the attr.
+    return Number.isFinite(value) ? String(value) : "0";
+}
+function parentWallMs(run) {
+    if (typeof run.wallMs === "number" && Number.isFinite(run.wallMs) && run.wallMs >= 0) {
+        return run.wallMs;
+    }
+    return wallMsBetween(run.startedAt, run.endedAt);
+}
+export function renderTicketTrajectoryStationHtml(runs) {
+    const stationOrder = [];
+    const byStation = new Map();
+    const sortedRuns = sortRuns(runs);
+    for (const run of sortedRuns) {
+        if (!byStation.has(run.station)) {
+            byStation.set(run.station, []);
+            stationOrder.push(run.station);
+        }
+        byStation.get(run.station).push(run);
+    }
+    return stationOrder
+        .map((station) => {
+        const rounds = byStation.get(station);
+        const stationLabel = station === "unknown" ? "未知站" : station;
+        let stationCost = 0;
+        let stationTokens = 0;
+        let stationWall = 0;
+        for (const run of rounds) {
+            stationCost += run.costUsd;
+            stationTokens += run.totalTokens;
+            // Station wall = each run's (possibly now-extended) wall + axis legs folded in.
+            stationWall += parentWallMs(run) + run.axisWallMs;
+        }
+        const roundHtml = rounds
+            .map((run) => {
+            const resultDisplay = run.hasResult
+                ? run.resultStatus ||
+                    run.resultStatus
+                : "";
+            // Machine channel: space-separated closed-enum tokens (no custom status dialect).
+            const wall = parentWallMs(run);
+            return [
+                `<article class="run"`,
+                ` data-run-id="${attr(run.runId)}"`,
+                ` data-station="${attr(run.station)}"`,
+                ` data-station-source="${attr(run.stationSource)}"`,
+                ` data-ledger-coord="${attr(run.ledgerCoord)}"`,
+                ` data-attempt-count="${attr(String(run.attemptCount))}"`,
+                ` data-has-result="${run.hasResult ? "true" : "false"}"`,
+                ` data-result-status="${attr(run.resultStatus)}"`,
+                ` data-model="${attr(run.model)}"`,
+                ` data-provider="${attr(run.provider)}"`,
+                ` data-thinking="${attr(run.thinking)}"`,
+                run.startedAt ? ` data-started-at="${attr(run.startedAt)}"` : "",
+                run.endedAt ? ` data-ended-at="${attr(run.endedAt)}"` : "",
+                ` data-mtime-ms="${attr(String(run.mtimeMs))}"`,
+                ` data-cost-usd="${attr(formatUsd(run.costUsd))}"`,
+                ` data-total-tokens="${attr(String(run.totalTokens))}"`,
+                ` data-wall-ms="${attr(String(wall))}"`,
+                ` data-axis-wall-ms="${attr(String(run.axisWallMs))}"`,
+                `>`,
+                `<header class="run-head">`,
+                `<span class="run-id">${escapeHtml(run.runId)}</span>`,
+                run.model || run.provider || run.thinking
+                    ? `<span class="run-model">${escapeHtml([run.provider, run.model].filter(Boolean).join("/"))}${run.thinking ? ` · ${escapeHtml(run.thinking)}` : ""}</span>`
+                    : "",
+                `</header>`,
+                `<p class="run-meta">`,
+                `<span class="attempts">attempts: ${run.attemptCount}</span>`,
+                run.hasResult
+                    ? `<span class="result">result: ${escapeHtml(resultDisplay)}</span>`
+                    : `<span class="result">result: (none — attempts only)</span>`,
+                `<span class="cost">$${escapeHtml(formatUsdPrecise(run.costUsd))} · ${escapeHtml(formatTokensCompact(run.totalTokens))} tok</span>`,
+                `<span class="wall">墙钟 ${escapeHtml(formatDurationZh(wall))}</span>`,
+                `</p>`,
+                `<p class="ledger"><a data-ledger-link="${attr(run.ledgerCoord)}" href="${attr(run.evidenceHref)}">${escapeHtml(run.ledgerCoord)}</a></p>`,
+                `</article>`,
+            ].join("");
+        })
+            .join("\n");
+        return [
+            `<section class="station" data-station-block="${attr(station)}" data-round-count="${rounds.length}" data-station-cost-usd="${attr(formatUsd(stationCost))}" data-station-total-tokens="${attr(String(stationTokens))}" data-station-wall-ms="${attr(String(stationWall))}">`,
+            `<h2 class="station-title">${escapeHtml(stationLabel)} · ${rounds.length} 轮 · $${escapeHtml(formatUsdPrecise(stationCost))} · ${escapeHtml(formatTokensCompact(stationTokens))} tok · 墙钟 ${escapeHtml(formatDurationZh(stationWall))}</h2>`,
+            roundHtml,
+            `</section>`,
+        ].join("\n");
+    })
+        .join("\n");
+}
+function renderHtml(input) {
+    const refreshActive = input.refreshBoundarySeconds !== undefined &&
+        Number.isFinite(input.refreshBoundarySeconds) &&
+        input.refreshBoundarySeconds > 0;
+    const refreshBoundarySeconds = refreshActive ? input.refreshBoundarySeconds : undefined;
+    const sortedRuns = sortRuns(input.runs);
+    const stationBlocks = renderTicketTrajectoryStationHtml(sortedRuns);
+    const lifecycleAttrs = refreshActive
+        ? ` data-lifecycle="refresh" data-refresh-boundary-seconds="${attr(String(refreshBoundarySeconds))}"`
+        : ` data-lifecycle="oneshot"`;
+    const refreshMeta = refreshActive
+        ? `
+<meta http-equiv="refresh" content="${attr(String(refreshBoundarySeconds))}"/>`
+        : "";
+    const refreshNote = refreshActive
+        ? `\n    · refresh ≤ ${escapeHtml(String(refreshBoundarySeconds))}s`
+        : "";
+    return `<!DOCTYPE html>
+<html lang="zh-CN"
+  data-issue="${attr(String(input.issueNumber))}"
+  data-generated-at="${attr(input.generatedAt)}"${lifecycleAttrs}
+>
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>${refreshMeta}
+<title>Ticket #${escapeHtml(String(input.issueNumber))} trajectory</title>
+<style>
+  :root { color-scheme: light dark; font-family: system-ui, sans-serif; line-height: 1.45; }
+  body { margin: 0 auto; padding: 1rem; max-width: 52rem; }
+  header.page { margin-bottom: 1rem; }
+  .generated { font-size: 0.9rem; opacity: 0.8; }
+  .station { border: 1px solid color-mix(in srgb, CanvasText 20%, Canvas); border-radius: 0.5rem; padding: 0.75rem; margin: 0.75rem 0; }
+  .station-title { margin: 0 0 0.5rem; font-size: 1.1rem; }
+  .run { padding: 0.5rem 0; border-top: 1px solid color-mix(in srgb, CanvasText 12%, Canvas); }
+  .run:first-of-type { border-top: 0; }
+  .run-head { display: flex; flex-wrap: wrap; gap: 0.5rem 1rem; justify-content: space-between; }
+  .run-id { font-family: ui-monospace, monospace; font-size: 0.9rem; word-break: break-all; }
+  .run-model { font-size: 0.85rem; opacity: 0.85; }
+  .run-meta { margin: 0.25rem 0; font-size: 0.9rem; display: flex; flex-wrap: wrap; gap: 0.75rem; }
+  .ledger { margin: 0.25rem 0 0; font-size: 0.8rem; word-break: break-all; }
+  @media (max-width: 640px) {
+    body { padding: 0.75rem; }
+    .run-head { flex-direction: column; }
+  }
+</style>
+</head>
+<body>
+<header class="page">
+  <h1>Ticket #${escapeHtml(String(input.issueNumber))} · 驿传轨迹</h1>
+  <p class="generated">生成于 <time datetime="${attr(input.generatedAt)}">${escapeHtml(formatLocalDateTime(input.generatedAt))}</time>${refreshNote}</p>
+</header>
+<main data-run-count="${sortedRuns.length}">
+${stationBlocks || "<p data-empty=\"true\">no runs</p>"}
+</main>
+</body>
+</html>
+`;
+}
+export async function buildTicketTrajectoryBookIndex(ledgerDir) {
+    const root = resolve(ledgerDir);
+    const runsByTicket = new Map();
+    const unboundRuns = [];
+    for (const runDir of await listBookRunDirectories(root)) {
+        const invocation = await readInvocation(runDir);
+        const rel = relative(root, runDir).split(sep).join("/");
+        const binding = {
+            runDir,
+            runFolder: basename(runDir),
+            ledgerCoord: rel,
+            ...(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 };
+}
+/**
+ * Load unbound flat runs for the board unknown seam.
+ * Never joins any ticket. Built from the book index (once).
+ */
+export async function loadUnboundTrajectoryRuns(ledgerDir, bookIndex) {
+    const root = resolve(ledgerDir);
+    const index = bookIndex ?? (await buildTicketTrajectoryBookIndex(root));
+    const out = [];
+    for (const binding of index.unboundRuns) {
+        const run = await parseRunDirectory(binding.runDir, binding.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, issueNumber, bookIndex) {
+    if (!isPositiveTicketNumber(issueNumber)) {
+        throw new Error("issueNumber must be a positive integer");
+    }
+    const root = resolve(ledgerDir);
+    const index = bookIndex ?? (await buildTicketTrajectoryBookIndex(root));
+    const runs = [];
+    const seenRunDirs = new Set();
+    // Legacy hand-dispatch path: issues/<N>/runs (read-only compatibility).
+    const runIds = await listRunIds(root, issueNumber);
+    for (const runId of runIds) {
+        const parsed = await parseRun(root, issueNumber, runId);
+        const legacyDir = join(root, "issues", String(issueNumber), "runs", runId);
+        seenRunDirs.add(resolve(legacyDir));
+        runs.push(parsed);
+    }
+    // Book runs (flat + subject-tree) bound by typed invocation 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);
+        runs.push(await parseRunDirectory(binding.runDir, binding.ledgerCoord));
+    }
+    return runs;
+}
+/**
+ * Unique production seam: pure scan of the ledger + snapshot + now → HTML.
+ * Read-only against the ledger. Snapshot is the S1 minimal stub.
+ */
+export async function renderTicketTrajectoryHtml(ledgerDir, ticketSnapshot, now, options) {
+    if (!isRecord(ticketSnapshot) || !isPositiveTicketNumber(ticketSnapshot.issueNumber)) {
+        throw new Error("ticketSnapshot.issueNumber must be a positive integer");
+    }
+    const issueNumber = ticketSnapshot.issueNumber;
+    const runs = await loadTicketTrajectoryRuns(ledgerDir, issueNumber);
+    const generatedAt = now.toISOString();
+    // One-shot by default: only an explicit positive bound declares self-refresh,
+    // and only callers that actually regenerate (startTicketTrajectoryPage) pass it.
+    return renderHtml({
+        issueNumber,
+        generatedAt,
+        runs,
+        ...(options?.refreshBoundarySeconds !== undefined
+            ? { refreshBoundarySeconds: options.refreshBoundarySeconds }
+            : {}),
+    });
+}
+function landsInLedger(ledgerRoot, candidate) {
+    // mkdir may have materialized a previously dangling ledger alias since the first gate.
+    const physicalRoot = physicalPathIdentity(ledgerRoot);
+    const lexical = resolve(candidate);
+    const physical = physicalPathIdentity(candidate);
+    const inside = (id) => physicalRoot === id || pathContainedIn(physicalRoot, id);
+    return inside(lexical) || inside(physical);
+}
+/**
+ * Prospective output must stay outside every ledger root.
+ * Equality counts as inside. Symlink parents are followed by physical identity.
+ */
+export async function assertOutputOutsideLedgers(ledgerDirs, outputPath, refusalMessage) {
+    const outputAbsolute = resolve(outputPath);
+    const prospectiveReal = physicalPathIdentity(outputAbsolute);
+    const ledgerRoots = [];
+    for (const ledgerDir of ledgerDirs) {
+        const ledgerResolved = resolve(ledgerDir);
+        let ledgerRoot;
+        try {
+            ledgerRoot = await realpath(ledgerResolved);
+        }
+        catch (error) {
+            if (!isMissingPathError(error))
+                throw error;
+            ledgerRoot = physicalPathIdentity(ledgerResolved);
+        }
+        ledgerRoots.push(ledgerRoot);
+        if (landsInLedger(ledgerRoot, prospectiveReal) || landsInLedger(ledgerRoot, outputAbsolute)) {
+            throw new Error(refusalMessage);
+        }
+    }
+    return { ledgerRoots, outputAbsolute, prospectiveReal };
+}
+/**
+ * Write HTML outside the ledgers. Temp+rename does not open an existing inode.
+ * An existing symlink whose target is inside a ledger is refused.
+ */
+export async function writePageOutsideLedgers(ledgerRoots, outputAbsolute, html, refusalMessage) {
+    const parent = dirname(outputAbsolute);
+    await mkdir(parent, { recursive: true });
+    const parentReal = await realpath(parent);
+    const destinationReal = resolve(parentReal, basename(outputAbsolute));
+    for (const root of ledgerRoots) {
+        if (landsInLedger(root, parentReal) || landsInLedger(root, destinationReal)) {
+            throw new Error(refusalMessage);
+        }
+    }
+    try {
+        const existing = await lstat(outputAbsolute);
+        if (existing.isSymbolicLink()) {
+            const target = await realpath(outputAbsolute);
+            for (const root of ledgerRoots) {
+                if (landsInLedger(root, target))
+                    throw new Error(refusalMessage);
+            }
+        }
+    }
+    catch (error) {
+        if (errnoCode(error) !== "ENOENT" && errnoCode(error) !== "ENOTDIR")
+            throw error;
+    }
+    await writeFileAtomically(outputAbsolute, html);
+    return realpath(outputAbsolute);
+}
+const TRAJECTORY_OUTPUT_REFUSAL = "ticket trajectory outputPath must be outside the ledger directory";
+/**
+ * Resolve the prospective on-disk target of outputPath and refuse any landing
+ * inside the ledger — including when the path, a parent, or a trailing segment
+ * is a symlink into the ledger tree.
+ */
+export async function assertTrajectoryOutputOutsideLedger(ledgerDir, outputPath) {
+    const gate = await assertOutputOutsideLedgers([ledgerDir], outputPath, TRAJECTORY_OUTPUT_REFUSAL);
+    return {
+        ledgerRoot: gate.ledgerRoots[0],
+        outputAbsolute: gate.outputAbsolute,
+        prospectiveReal: gate.prospectiveReal,
+    };
+}
+/**
+ * Page write seam: render via the unique seam and write ONLY to an explicit
+ * path outside the ledger. Caller owns output location.
+ */
+export async function writeTicketTrajectoryPage(input) {
+    const gate = await assertTrajectoryOutputOutsideLedger(input.ledgerDir, input.outputPath);
+    const html = await renderTicketTrajectoryHtml(input.ledgerDir, input.ticketSnapshot, input.now, input.refreshBoundarySeconds !== undefined
+        ? { refreshBoundarySeconds: input.refreshBoundarySeconds }
+        : undefined);
+    const outputPath = await writePageOutsideLedgers([gate.ledgerRoot], gate.outputAbsolute, html, TRAJECTORY_OUTPUT_REFUSAL);
+    return { outputPath, html };
+}
+const defaultScheduler = {
+    every(ms, tick) {
+        const timer = setInterval(tick, ms);
+        // Allow the process to exit naturally if the caller forgets stop in scripts.
+        timer.unref?.();
+        return () => clearInterval(timer);
+    },
+};
+/**
+ * Production page lifecycle: write immediately, then regenerate on the declared
+ * refresh boundary so the same viewing surface observes new runs / generated-at.
+ * Stop cancels further regeneration. A post-start regeneration failure faults the
+ * lifecycle with the original cause (no silent continuation). Ledger remains read-only.
+ */
+export function startTicketTrajectoryPage(input) {
+    const refreshBoundarySeconds = input.refreshBoundarySeconds ?? DEFAULT_REFRESH_BOUNDARY_SECONDS;
+    if (!(refreshBoundarySeconds > 0) || !Number.isFinite(refreshBoundarySeconds)) {
+        throw new Error("refreshBoundarySeconds must be a positive finite number");
+    }
+    const clock = input.clock ?? (() => new Date());
+    const scheduler = input.scheduler ?? defaultScheduler;
+    let stopped = false;
+    let cancel;
+    let inFlight;
+    let lastRejection;
+    let closedSettled = false;
+    let resolveClosed;
+    let rejectClosed;
+    const closed = new Promise((resolve, reject) => {
+        resolveClosed = resolve;
+        rejectClosed = reject;
+    });
+    // Prevent unhandled-rejection crashes when callers only await stop()/started.
+    void closed.catch(() => undefined);
+    const fault = (error) => {
+        if (lastRejection !== undefined)
+            return;
+        lastRejection = error;
+        stopped = true;
+        cancel?.();
+        cancel = undefined;
+        if (!closedSettled) {
+            closedSettled = true;
+            rejectClosed(error);
+        }
+    };
+    const settleClean = () => {
+        if (closedSettled)
+            return;
+        closedSettled = true;
+        resolveClosed();
+    };
+    const writeOnce = async () => {
+        if (stopped && lastRejection === undefined) {
+            throw new Error("ticket trajectory page lifecycle already stopped");
+        }
+        if (lastRejection !== undefined)
+            throw lastRejection;
+        return writeTicketTrajectoryPage({
+            ledgerDir: input.ledgerDir,
+            ticketSnapshot: input.ticketSnapshot,
+            now: clock(),
+            outputPath: input.outputPath,
+            refreshBoundarySeconds,
+        });
+    };
+    const queueWrite = () => {
+        if (stopped || lastRejection !== undefined)
+            return;
+        inFlight = (inFlight ?? Promise.resolve()).then(async () => {
+            if (stopped || lastRejection !== undefined)
+                return;
+            try {
+                await writeOnce();
+            }
+            catch (error) {
+                fault(error);
+            }
+        });
+    };
+    const started = writeOnce()
+        .then((first) => {
+        if (stopped || lastRejection !== undefined)
+            return first;
+        const intervalMs = Math.max(1, Math.round(refreshBoundarySeconds * 1000));
+        cancel = scheduler.every(intervalMs, () => {
+            queueWrite();
+        });
+        return first;
+    })
+        .catch((error) => {
+        fault(error);
+        throw error;
+    });
+    // Capture output path from the absolute resolution even before first write settles.
+    const outputPath = resolve(input.outputPath);
+    return {
+        outputPath,
+        started,
+        closed,
+        async stop() {
+            stopped = true;
+            cancel?.();
+            cancel = undefined;
+            await started.catch(() => undefined);
+            if (inFlight)
+                await inFlight.catch(() => undefined);
+            if (lastRejection !== undefined) {
+                // closed already rejected with the original cause
+                throw lastRejection;
+            }
+            settleClean();
+        },
+    };
+}