@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/src/sitian-appender.ts

@@ -5,7 +5,11 @@
  */
 import { randomUUID } from "node:crypto";
 import { appendFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+
+import { parseRunLeaf, sessionDirectoryOf } from "./role-run-placement.ts";
+import { RUN_HISTORY_FILE, RUN_HISTORY_KINDS, RUN_LOG_FILE, RUN_STATE_FILE, RUN_STATE_KINDS } from "./run-dossier-files.ts";
+import { ticketNumberFromSitianSubject } from "./run-ticket-number.ts";
 
 import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
@@ -39,20 +43,8 @@ export function appendSitianRecordBlock(input: SitianRecordInput, block: string)
   }
 }
 
-/** Authorized S4 submission ledger kinds that share a common run submission volume. */
-export const S4_SUBMISSION_LEDGER_KINDS = new Set([
-  "candidate",
-  "roundContext",
-  "outcome",
-  "sealed",
-  "post-seal-anomaly"
-]);
-
-/** Compute the volume partition key for directory placement. */
+/** Volume directory name for a record kind: the kind itself. */
 export function resolveSitianVolumeCategory(kind: string): string {
-  if (S4_SUBMISSION_LEDGER_KINDS.has(kind)) {
-    return "submission-ledger";
-  }
   return kind;
 }
 
@@ -65,6 +57,18 @@ type SitianRecordPath = {
 /** Sole records leaf under every sitian volume directory. */
 const SITIAN_RECORDS_LEAF = "records.jsonl" as const;
 
+export function sitianVolumeDirectory(sessionDirectory: string, category: string): string {
+  return join(sessionDirectory, category);
+}
+
+export function sitianRunVolumeDirectory(runDirectory: string, category: string): string {
+  return sitianVolumeDirectory(sessionDirectoryOf(runDirectory), category);
+}
+
+export function sitianVolumeRecordsFile(volumeDirectory: string): string {
+  return join(volumeDirectory, SITIAN_RECORDS_LEAF);
+}
+
 /**
  * Ticket-provenance under-book paths (docs/dossier-topology.md sole authority).
  * Writer ticket branch and owner-visible shape share this join — one code path.
@@ -75,7 +79,7 @@ function ticketProvenanceUnderBookPaths(
   ticketId: string,
 ): { sessionDir: string; recordFile: string } {
   const sessionDir = join(activationBookDirectory(ledgerHome, bookKey), ticketId);
-  return { sessionDir, recordFile: join(sessionDir, SITIAN_RECORDS_LEAF) };
+  return { sessionDir, recordFile: sitianVolumeRecordsFile(sessionDir) };
 }
 
 /** Pure topology owner shared by ambient writes and explicit-home submission reads. */
@@ -85,14 +89,7 @@ export function resolveSitianRecordPathInLedger(
 ): SitianRecordPath {
   const category = resolveSitianVolumeCategory(input.kind);
   const ticketNumber = category === "ticket-provenance"
-    ? typeof input.subject === "string" && /^[1-9][0-9]*$/.test(input.subject)
-      ? input.subject
-      : typeof input.subject === "object"
-        && typeof input.subject.ticketNumber === "number"
-        && Number.isSafeInteger(input.subject.ticketNumber)
-        && input.subject.ticketNumber > 0
-        ? String(input.subject.ticketNumber)
-        : undefined
+    ? ticketNumberFromSitianSubject(input.subject)
     : undefined;
 
   let sessionDir: string;
@@ -107,8 +104,10 @@ export function resolveSitianRecordPathInLedger(
     sessionDir = paths.sessionDir;
     recordFile = paths.recordFile;
   } else if (category === "ticket-provenance" && input.runDirectory !== undefined) {
+    // True-unbound diary staging: the run's history volume (#1161). Never a
+    // top-level run/records.jsonl — that leaf is only the ticket-root diary.
     sessionDir = input.runDirectory;
-    recordFile = join(sessionDir, SITIAN_RECORDS_LEAF);
+    recordFile = join(sessionDir, RUN_HISTORY_FILE);
   } else {
     if (
       input.sessionParent === undefined
@@ -117,8 +116,16 @@ export function resolveSitianRecordPathInLedger(
     ) {
       throw new Error("Sitian record ownership requires a parent session inside the ledger home");
     }
-    sessionDir = join(dirname(input.sessionParent), category);
-    recordFile = join(sessionDir, SITIAN_RECORDS_LEAF);
+    const sessionParentDir = dirname(input.sessionParent);
+    const runDirectory = dirname(sessionParentDir);
+    if (basename(sessionParentDir) === "session" && parseRunLeaf(basename(runDirectory)) !== undefined) {
+      // A role run's own session: every record kind shares the run's one log (#1161).
+      sessionDir = runDirectory;
+      recordFile = join(runDirectory, RUN_HISTORY_KINDS.has(input.kind) ? RUN_HISTORY_FILE : RUN_STATE_KINDS.has(input.kind) ? RUN_STATE_FILE : RUN_LOG_FILE);
+    } else {
+      sessionDir = sitianVolumeDirectory(sessionParentDir, category);
+      recordFile = sitianVolumeRecordsFile(sessionDir);
+    }
   }
   if (!physicallyContainedIn(ledgerHome, sessionDir)) {
     throw new Error("Sitian record ownership requires a directory inside the ledger home");

package/src/sitian-facade.ts

@@ -6,6 +6,7 @@
  * - sitianReport → appender (SitianRecord rows, append + identity claim)
  * Read paths: readSitianRecords (canonical rows).
  */
+import { sessionFileOf } from "./role-run-placement.ts";
 import { appendSitianRecord } from "./sitian-appender.ts";
 import type { RecordPointer, SitianRecordInput } from "./sitian-contracts.ts";
 
@@ -20,3 +21,24 @@ export * from "./sitian-reader.ts";
 export function sitianReport(input: SitianRecordInput): RecordPointer {
   return appendSitianRecord(input);
 }
+
+/**
+ * One record of a role run: history.jsonl for the history kinds and state.jsonl for the
+ * state kinds (see the appender), log.jsonl for the run's own diagnostics (host dossier pointers,
+ * dispatch / resume / post-admission faults, host stderr). Same single entry
+ * as every other record; the run is named, never a file path.
+ */
+export function reportRunRecord(
+  runDirectory: string,
+  kind: string,
+  payload: unknown,
+  source: string,
+): RecordPointer {
+  return appendSitianRecord({
+    level: "event",
+    kind,
+    sessionParent: sessionFileOf(runDirectory),
+    source,
+    payload,
+  });
+}

package/src/sitian-reader.ts

@@ -6,7 +6,6 @@
  * - Zero whitewashing, zero deduplication.
  * - Canonical rows after malformed lines are always reachable.
  */
-import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 import type {
@@ -15,46 +14,77 @@ import type {
   SitianRecord,
 } from "./sitian-contracts.ts";
 
-import { isRecord, errorText } from "./unknown-value.ts";
+import { isRecord, errorText, isEnoent } from "./unknown-value.ts";
 
-/** Read a Sitian record volume with full traversal and non-destructive diagnostics. */
-export async function readSitianRecords(recordFile: string): Promise<SitianReadResult> {
-  if (!existsSync(recordFile)) {
-    return { records: [], diagnostics: [] };
+/** One non-blank JSONL line through the sole Sitian decoder. Blank → undefined. */
+export type SitianLineDecode =
+  | { readonly ok: true; readonly record: SitianRecord }
+  | { readonly ok: false; readonly diagnostic: SitianMalformedDiagnostic };
+
+/**
+ * Decode one Sitian JSONL line. Callers that must keep original bytes use this
+ * with the source line; volume readers fold it into records + diagnostics.
+ */
+export function decodeSitianRecordLine(
+  line: string,
+  lineNumber: number,
+): SitianLineDecode | undefined {
+  if (!line.trim()) return undefined;
+  try {
+    const parsed = JSON.parse(line);
+    if (isRecord(parsed)) {
+      return { ok: true, record: parsed as unknown as SitianRecord };
+    }
+    const typeDesc = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
+    return {
+      ok: false,
+      diagnostic: {
+        kind: "malformed",
+        line: lineNumber,
+        raw: line,
+        error: `expected JSON object, got ${typeDesc}`,
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      diagnostic: {
+        kind: "malformed",
+        line: lineNumber,
+        raw: line,
+        error: errorText(error),
+      },
+    };
   }
+}
 
-  const text = await readFile(recordFile, "utf8");
+/**
+ * Sole decoder for one Sitian JSONL volume's text. Sync so the run-dossier
+ * renderer and the async file reader share one implementation.
+ */
+export function parseSitianRecordText(text: string): SitianReadResult {
   const lines = text.split("\n");
-
   const records: SitianRecord[] = [];
   const diagnostics: SitianMalformedDiagnostic[] = [];
 
   for (let index = 0; index < lines.length; index += 1) {
-    const line = lines[index]!;
-    if (!line.trim()) continue;
-
-    try {
-      const parsed = JSON.parse(line);
-      if (isRecord(parsed)) {
-        records.push(parsed as unknown as SitianRecord);
-      } else {
-        const typeDesc = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
-        diagnostics.push({
-          kind: "malformed",
-          line: index + 1,
-          raw: line,
-          error: `expected JSON object, got ${typeDesc}`,
-        });
-      }
-    } catch (error) {
-      diagnostics.push({
-        kind: "malformed",
-        line: index + 1,
-        raw: line,
-        error: errorText(error),
-      });
-    }
+    const decoded = decodeSitianRecordLine(lines[index]!, index + 1);
+    if (decoded === undefined) continue;
+    if (decoded.ok) records.push(decoded.record);
+    else diagnostics.push(decoded.diagnostic);
   }
 
   return { records, diagnostics };
 }
+
+/** Read a Sitian record volume with full traversal and non-destructive diagnostics. */
+export async function readSitianRecords(recordFile: string): Promise<SitianReadResult> {
+  // Direct read: only ENOENT is absence. EACCES/EPERM and other IO keep their cause
+  // (Node fs docs: do not existsSync/access before open — #1161 C3).
+  try {
+    return parseSitianRecordText(await readFile(recordFile, "utf8"));
+  } catch (error) {
+    if (isEnoent(error)) return { records: [], diagnostics: [] };
+    throw error;
+  }
+}

package/src/submission-gate.ts

@@ -91,7 +91,7 @@ export function createDefaultGateOfficerSummon(options: {
 }
 
 /**
- * Book a typed pointer under parent session/auditor-roles (archivist-owned write).
+ * Book a typed pointer in the parent run's current.json officers section.
  * Offline mocks without a real session leave no nested volume (lawful zero).
  */
 function bookDirectOfficerPointer(

package/src/submission-ledger.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { sessionFileIn, sessionFileOf } from "./role-run-placement.ts";
 
 import {
   resolveActivationLedgerHome,
@@ -133,7 +133,7 @@ async function submissionRecordFile(cwd: string, runId: string, scope: Submissio
   if (sessionParent === undefined) {
     const discoveredRun = await findRunDirectoryById(scope.home, runId);
     if (discoveredRun === undefined) return undefined;
-    sessionParent = join(discoveredRun, "session", "session.jsonl");
+    sessionParent = sessionFileOf(discoveredRun);
   }
   return resolveSitianRecordPathInLedger({
     level: "event",
@@ -432,12 +432,12 @@ async function restoreState(cwd: string, runId: string, scope: SubmissionLedgerR
 /** Sole HostContext-derived session parent for ledger restore/append (never process.env). */
 function sessionParentFromHostContext(context: HostContext): string | undefined {
   const runDirectory = runDirectoryFromHostContext(context);
-  if (runDirectory !== undefined) return join(runDirectory, "session", "session.jsonl");
+  if (runDirectory !== undefined) return sessionFileOf(runDirectory);
   const sessionFile = context.sessionManager.getSessionFile?.();
   if (typeof sessionFile === "string" && sessionFile.length > 0) return sessionFile;
   const sessionDir = context.sessionManager.getSessionDir?.();
   if (typeof sessionDir === "string" && sessionDir.length > 0) {
-    return join(sessionDir, "session.jsonl");
+    return sessionFileIn(sessionDir);
   }
   return undefined;
 }

package/src/ticket-provenance-contracts.ts

@@ -1,4 +1,6 @@
+import { parseTicketNumber } from "./run-ticket-number.ts";
 import { isRecord } from "./unknown-value.ts";
+
 /**
  * 起居录（ticket-provenance）typed 形状 —— ADR 0075 / ADR 0081 / #1090。
  *
@@ -63,12 +65,7 @@ export type TicketProvenanceLine = {
 };
 
 function positiveInteger(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) return value;
-  if (typeof value === "string" && /^[1-9][0-9]*$/.test(value)) {
-    const parsed = Number(value);
-    if (Number.isSafeInteger(parsed)) return parsed;
-  }
-  return undefined;
+  return parseTicketNumber(value);
 }
 
 function projectBound(value: unknown): TicketProvenanceBound | undefined {

package/src/ticket-provenance.ts

@@ -3,8 +3,8 @@
  * 一册＝一个追加式 records.jsonl。每轮新投影经司天台 appender 追加为不可变提交；
  * 纯追加、不回读历史去重、不折叠。
  */
-import { readFile, unlink } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 
 import {
   errnoCode,
@@ -17,6 +17,8 @@ import {
   type LedgerSessionLine,
 } from "./ledger-session-read.ts";
 import { isSafePositiveTicketNumber } from "./run-ticket-number.ts";
+import { runDirectoryOfSessionFile, sessionFileOf } from "./role-run-placement.ts";
+import { RUN_HISTORY_FILE } from "./run-dossier-files.ts";
 import { adaptSessionDialogue, nativeEventId } from "./session-dialogue.ts";
 import {
   appendSitianRecordBlock,
@@ -24,6 +26,7 @@ import {
   resolveSitianRecordPath,
   type SitianRecordInput,
 } from "./sitian-facade.ts";
+import { decodeSitianRecordLine } from "./sitian-reader.ts";
 import {
   TICKET_PROVENANCE_KIND,
   type TicketProvenanceBound,
@@ -76,10 +79,7 @@ function isLedgerRoleSessionFile(absolute: string, home?: string): boolean {
       : packageMachineHome();
   const ledgerHome = resolveActivationLedgerHome(machineHome);
   if (!physicallyContainedIn(ledgerHome, absolute)) return false;
-  return (
-    basename(absolute) === "session.jsonl" &&
-    basename(dirname(absolute)) === "session"
-  );
+  return sessionFileOf(runDirectoryOfSessionFile(absolute)) === absolute;
 }
 
 /** Real I/O seam gate: only host session stores or sitian role-run session.jsonl. */
@@ -152,16 +152,28 @@ export async function rehomeUnboundTicketProvenance(
   cwd: string,
   home: string,
 ): Promise<void> {
-  const source = join(runDirectory, "records.jsonl");
-  let content: string;
+  const ticketInput = ticketProvenanceRecordInput(ticketNumber, cwd, home);
+
+  // Live staging: ticket-provenance rows in the run's history.jsonl. Append-only
+  // history keeps the staging rows; the ticket-root diary is the home.
+  // Old run/records.jsonl is not a runtime input (#1161); only migration tools read it.
+  let history: string;
   try {
-    content = await readFile(source, "utf8");
+    history = await readFile(join(runDirectory, RUN_HISTORY_FILE), "utf8");
   } catch (error) {
     if (errnoCode(error) === "ENOENT") return;
     throw error;
   }
-  appendSitianRecordBlock(ticketProvenanceRecordInput(ticketNumber, cwd, home), content);
-  await unlink(source);
+  const block = history
+    .split("\n")
+    .flatMap((line, index) => {
+      const decoded = decodeSitianRecordLine(line, index + 1);
+      if (decoded === undefined || !decoded.ok) return [];
+      if (decoded.record.kind !== TICKET_PROVENANCE_KIND) return [];
+      return [`${line}\n`];
+    })
+    .join("");
+  if (block !== "") appendSitianRecordBlock(ticketInput, block);
 }
 
 /**

package/src/ticket-snapshot.ts

@@ -14,6 +14,7 @@
 import { createGhApiRunner, type GhApiRunner } from "./gh-api-runner.ts";
 
 import { isRecord } from "./unknown-value.ts";
+import { isPositiveTicketNumber } from "./run-ticket-number.ts";
 
 export type BookRepoBinding = {
   bookKey: string;
@@ -171,7 +172,7 @@ function parseClosedAt(raw: unknown, label: string): string | null {
 function parseTicketNode(raw: unknown, label: string): ParsedTicketNode {
   if (!isRecord(raw)) throw new Error(`${label} is not an object`);
   const number = raw.number;
-  if (typeof number !== "number" || !Number.isInteger(number) || number < 1) {
+  if (!isPositiveTicketNumber(number)) {
     throw new Error(`${label}.number invalid`);
   }
   if (typeof raw.title !== "string") throw new Error(`${label}.title missing`);
@@ -536,7 +537,7 @@ export function createGhTicketSnapshotTransport(
       const closedNumbers = [
         ...new Set(
           input.closedIssueNumbers.filter(
-            (n) => Number.isInteger(n) && n > 0 && !tickets.has(n),
+            (n) => isPositiveTicketNumber(n) && !tickets.has(n),
           ),
         ),
       ].sort((a, b) => a - b);