@akagilnc/pi-workflow-roles 0.1.4204 → 0.1.4228

package/dist/ticket-provenance.js

@@ -1,246 +1,331 @@
 /**
- * 起居录 volume helpers — ADR 0075 / #582.
- * Write/read via sitian facade only; no parallel destination logic.
+ * 起居录 volume helpers — ADR 0075「2026-09-14 修订」/ #901。
+ * 一册＝一个文件：首行册子头，其后裸对话行。每轮按当前区间重投影是唯一机制；
+ * 无 append 水位、无 SitianRecord 外壳。目的地解析与读写经司天台唯一入口
+ * （ADR 0065 records-owner / record-entry；ADR 0081 入录经司天台）。
  */
-import { createHash } from "node:crypto";
-import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { resolveSitianRecordPath, sitianReport, readSitianRecords, } from "./sitian-facade.js";
+import { basename, dirname, join, resolve } from "node:path";
+import { resolveBookKeyFromGit } from "./activation-ledger-git.js";
+import { errnoCode, packageMachineHome, physicallyContainedIn, resolveActivationLedgerHome, } from "./activation-ledger-topology.js";
+import { readLedgerSessionJsonlLines, } from "./ledger-session-read.js";
 import { isSafePositiveTicketNumber } from "./run-ticket-number.js";
-import { TICKET_PROVENANCE_HUMAN_VIEW, TICKET_PROVENANCE_KIND, projectTicketProvenanceDiagnostic, projectTicketProvenanceEntry, } from "./ticket-provenance-contracts.js";
-/** Subject string for ticket-keyed volumes — history follows the ticket. */
-export function ticketProvenanceSubject(ticketNumber) {
-    if (!isSafePositiveTicketNumber(ticketNumber)) {
-        throw new Error(`ticket-provenance subject requires a positive ticket number, got ${String(ticketNumber)}`);
+import { adaptSessionDialogue, nativeEventId } from "./session-dialogue.js";
+import { ensureSitianVolume, readSitianVolumeText, resolveSitianVolume, rewriteSitianVolume, } from "./sitian-facade.js";
+import { TICKET_PROVENANCE_KIND, projectTicketProvenanceHeader, projectTicketProvenanceLine, } from "./ticket-provenance-contracts.js";
+/**
+ * Typed input failure for diarist bounds/session path (reask, not infrastructure).
+ * Accept hook discriminates with instanceof — never Error.message prefixes.
+ */
+export class TicketProvenanceInputError extends Error {
+    code = "ticket-provenance-input";
+    constructor(message, options) {
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "TicketProvenanceInputError";
     }
-    return String(ticketNumber);
 }
 /**
- * Deterministic entry identity for sitian entry-level idempotency.
- * Same ticket + source pointer + transcript → same identity → no re-append.
+ * Host-owned session source roots (ADR 0038 / ADR 0081 cross-host).
+ * Narrow directory identities — not whole `.pi` / whole `.ak-roles`.
+ */
+export function dialogueSessionSourceRoots(home) {
+    const machineHome = typeof home === "string" && home.trim() !== "" ? home : packageMachineHome();
+    return [
+        join(machineHome, ".claude", "projects"),
+        join(machineHome, ".codex", "sessions"),
+        join(machineHome, ".pi", "agent", "sessions"),
+    ];
+}
+/**
+ * True when path is a sitian role-run session volume:
+ * `<ledger>/books/.../session/session.jsonl` (basename + parent only — no body probe).
  */
-export function ticketProvenanceEntryIdentity(input) {
-    const ref = input.sourceRef;
-    const refKey = [
-        ref.sessionFile ?? "",
-        ref.entryId === undefined ? "" : String(ref.entryId),
-        ref.path ?? "",
-        ref.url ?? "",
-    ].join("\u0001");
-    const material = [
-        String(input.ticketNumber),
-        input.sourceKind,
-        refKey,
-        input.transcript,
-    ].join("\u0000");
-    return createHash("sha256").update(material, "utf8").digest("hex");
+function isLedgerRoleSessionFile(absolute, home) {
+    const machineHome = typeof home === "string" && home.trim() !== "" ? home : packageMachineHome();
+    const ledgerHome = resolveActivationLedgerHome(machineHome);
+    if (!physicallyContainedIn(ledgerHome, absolute))
+        return false;
+    return basename(absolute) === "session.jsonl" && basename(dirname(absolute)) === "session";
 }
-function identityFromPayload(ticketNumber, payload) {
-    if (typeof payload === "object"
-        && payload !== null
-        && !Array.isArray(payload)) {
-        const record = payload;
-        if (typeof record.sourceKind === "string" && typeof record.transcript === "string") {
-            const sourceRef = typeof record.sourceRef === "object" && record.sourceRef !== null && !Array.isArray(record.sourceRef)
-                ? record.sourceRef
-                : {};
-            return ticketProvenanceEntryIdentity({
-                ticketNumber,
-                sourceKind: record.sourceKind,
-                sourceRef,
-                transcript: record.transcript,
-            });
-        }
+/** Real I/O seam gate: only host session stores or sitian role-run session.jsonl. */
+function assertDialogueSessionSourcePath(path, home) {
+    const absolute = resolve(path);
+    for (const root of dialogueSessionSourceRoots(home)) {
+        if (physicallyContainedIn(root, absolute))
+            return;
     }
-    return createHash("sha256")
-        .update(`${String(ticketNumber)}\u0000${JSON.stringify(payload)}`, "utf8")
-        .digest("hex");
+    if (isLedgerRoleSessionFile(absolute, home))
+        return;
+    throw new TicketProvenanceInputError(`session unreadable: ${path} (outside authorized source roots)`);
 }
-/** Append one original row; returns existing pointer on identity hit. */
-export function appendTicketProvenanceEntry(input) {
-    const subject = ticketProvenanceSubject(input.ticketNumber);
-    const identity = identityFromPayload(input.ticketNumber, input.payload);
-    const record = typeof input.payload === "object" && input.payload !== null && !Array.isArray(input.payload)
-        ? input.payload
-        : undefined;
-    const sourceRef = record !== undefined && typeof record.sourceRef === "object" && record.sourceRef !== null && !Array.isArray(record.sourceRef)
-        ? record.sourceRef
-        : undefined;
-    return sitianReport({
-        level: "event",
-        kind: TICKET_PROVENANCE_KIND,
-        identity,
-        subject,
-        cwd: input.cwd,
-        sessionParent: input.sessionParent,
-        ...(input.home === undefined ? {} : { home: input.home }),
-        host: input.host ?? "diarist",
-        source: input.source ?? "diarist",
-        payload: input.payload,
-        raw: sourceRef !== undefined
-            && typeof sourceRef.sessionFile === "string"
-            && (typeof sourceRef.entryId === "string" || typeof sourceRef.entryId === "number")
-            ? {
-                sessionFile: sourceRef.sessionFile,
-                entryId: sourceRef.entryId,
-            }
-            : undefined,
-    });
+/** Subject string for ticket-keyed volumes — history follows the ticket. */
+export function ticketProvenanceSubject(ticketNumber) {
+    if (!isSafePositiveTicketNumber(ticketNumber)) {
+        throw new Error(`ticket-provenance subject requires a positive ticket number, got ${String(ticketNumber)}`);
+    }
+    return String(ticketNumber);
 }
-/** Resolve volume paths for a ticket without writing. */
-export function resolveTicketProvenanceVolume(ticketNumber, cwd, home) {
-    const path = resolveSitianRecordPath({
+/** Topology input only — no destination parameter (ADR 0065 record-entry). */
+function ticketProvenanceRecordInput(ticketNumber, cwd, home) {
+    return {
         level: "event",
         kind: TICKET_PROVENANCE_KIND,
         subject: ticketProvenanceSubject(ticketNumber),
         cwd,
         ...(home === undefined ? {} : { home }),
-    });
-    return {
-        recordFile: path.recordFile,
-        volumeDir: path.sessionDir,
-        humanViewFile: join(path.sessionDir, TICKET_PROVENANCE_HUMAN_VIEW),
     };
 }
-/** Read projected diary entries + diagnostics for a ticket (empty when volume absent). */
+/** Resolve volume paths for a ticket without writing. */
+export function resolveTicketProvenanceVolume(ticketNumber, cwd, home) {
+    return resolveSitianVolume(ticketProvenanceRecordInput(ticketNumber, cwd, home));
+}
+/** Read the unique diary file (empty/absent → no header, no lines). */
 export async function readTicketProvenance(ticketNumber, cwd, home) {
-    const { recordFile } = resolveTicketProvenanceVolume(ticketNumber, cwd, home);
-    const { records } = await readSitianRecords(recordFile);
-    const entries = [];
-    const unprojected = [];
-    const diagnostics = [];
-    let skipped = 0;
-    for (const record of records) {
-        if (record.kind !== TICKET_PROVENANCE_KIND) {
-            skipped += 1;
+    const { recordFile, text } = await readSitianVolumeText(ticketProvenanceRecordInput(ticketNumber, cwd, home));
+    if (text === undefined) {
+        return { header: undefined, lines: [], recordFile };
+    }
+    const physical = text.split("\n");
+    let header;
+    const lines = [];
+    let sawFirst = false;
+    for (let index = 0; index < physical.length; index += 1) {
+        const raw = physical[index];
+        if (!raw.trim())
             continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
         }
-        // Diagnostics first — same partition, separate projection (never body).
-        const diagnostic = projectTicketProvenanceDiagnostic(record.payload);
-        if (diagnostic !== undefined) {
-            diagnostics.push(diagnostic);
+        catch {
+            // Stock / damaged rows stay unprojected — no backfill, no guess.
             continue;
         }
-        const entry = projectTicketProvenanceEntry(record.payload);
-        if (entry === undefined) {
-            unprojected.push(record.payload);
-            continue;
+        if (!sawFirst) {
+            sawFirst = true;
+            header = projectTicketProvenanceHeader(parsed);
+            // First line that is not a header is treated as a body line (stock shapes).
+            if (header !== undefined)
+                continue;
         }
-        entries.push(entry);
+        const line = projectTicketProvenanceLine(parsed);
+        if (line !== undefined)
+            lines.push(line);
     }
-    return { entries, unprojected, diagnostics, records, recordFile, skipped };
+    return { header, lines, recordFile };
 }
 /**
- * Fence long enough that any backtick run inside `text` cannot close the block.
- * Presentation helper only — not a machine contract; not exported.
+ * Ensure the per-ticket directory + volume file exist (ADR 0075 ticket-provenance-file).
+ * Empty file is lawful (bound court with no dialogue yet). Does not forge entries.
  */
-function markdownFenceFor(text) {
-    let longest = 0;
-    const runs = text.match(/`+/g);
-    if (runs !== null) {
-        for (const run of runs) {
-            if (run.length > longest)
-                longest = run.length;
-        }
-    }
-    return "`".repeat(Math.max(3, longest + 1));
+export function ensureTicketProvenanceVolume(ticketNumber, cwd, home) {
+    return ensureSitianVolume(ticketProvenanceRecordInput(ticketNumber, cwd, home));
 }
 /**
- * Render a local human-read markdown view from entries.
- * Presentation only — machines bite JSONL. No wording lock for consumers.
+ * Resolve a bound endpoint against this round's session lines.
+ * id → first physical line carrying that native id; line → that 1-based line.
+ * Either missing from the volume → undefined (caller reasks).
  */
-export function renderTicketProvenanceMarkdown(input) {
-    const unprojected = input.unprojected ?? [];
-    const lines = [
-        `# 起居录 · #${input.ticketNumber}`,
-        "",
-        `条目数：${input.entries.length + unprojected.length}`,
-        "",
-    ];
-    let index = 0;
-    for (const entry of input.entries) {
-        index += 1;
-        const sourceKind = typeof entry.sourceKind === "string" ? entry.sourceKind : "未投影";
-        const timestamp = typeof entry.timestamp === "string" ? entry.timestamp : "";
-        lines.push(`## ${index}. ${sourceKind} · ${timestamp}`);
-        lines.push("");
-        const basis = entry.basis;
-        const method = typeof basis === "object" && basis !== null && !Array.isArray(basis) && typeof basis.method === "string"
-            ? basis.method
-            : "未投影";
-        lines.push(`- basis.method: \`${method}\``);
-        if (typeof basis === "object" &&
-            basis !== null &&
-            !Array.isArray(basis) &&
-            Array.isArray(basis.anchors) &&
-            basis.anchors.length > 0) {
-            lines.push(`- anchors: ${basis.anchors.map((a) => `\`${String(a)}\``).join(", ")}`);
+function resolveBoundIndex(bound, sessionLines) {
+    if (typeof bound.id === "string" && bound.id !== "") {
+        for (let index = 0; index < sessionLines.length; index += 1) {
+            const row = sessionLines[index].row;
+            if (row === undefined)
+                continue;
+            if (nativeEventId(row) === bound.id)
+                return index;
         }
-        if (typeof basis === "object" && basis !== null && !Array.isArray(basis) && basis.note !== undefined) {
-            lines.push(`- note: ${String(basis.note)}`);
+        return undefined;
+    }
+    if (typeof bound.line === "number") {
+        for (let index = 0; index < sessionLines.length; index += 1) {
+            if (sessionLines[index].line === bound.line)
+                return index;
         }
-        const sourceRef = typeof entry.sourceRef === "object" && entry.sourceRef !== null && !Array.isArray(entry.sourceRef)
-            ? entry.sourceRef
-            : {};
-        const refParts = [];
-        if (sourceRef.sessionFile !== undefined) {
-            refParts.push(`sessionFile=${String(sourceRef.sessionFile)}`);
+        return undefined;
+    }
+    return undefined;
+}
+function amendmentKey(s, line) {
+    return `${s}:${line}`;
+}
+/**
+ * Resolve submitted ranges against the session, then sort by source position and
+ * merge overlaps so each physical row is visited once (#901 source order).
+ */
+function normalizeResolvedRanges(ranges, sessionLines, sessionPath) {
+    const resolved = [];
+    for (const range of ranges) {
+        const fromIndex = resolveBoundIndex(range.from, sessionLines);
+        const toIndex = resolveBoundIndex(range.to, sessionLines);
+        if (fromIndex === undefined || toIndex === undefined) {
+            throw new TicketProvenanceInputError(`bound endpoint not found in ${sessionPath} (from=${JSON.stringify(range.from)} to=${JSON.stringify(range.to)})`);
         }
-        if (sourceRef.entryId !== undefined) {
-            refParts.push(`entryId=${String(sourceRef.entryId)}`);
+        if (fromIndex > toIndex) {
+            throw new TicketProvenanceInputError(`bound range inverted in ${sessionPath} (from index ${fromIndex} > to index ${toIndex})`);
         }
-        if (sourceRef.path !== undefined) {
-            refParts.push(`path=${String(sourceRef.path)}`);
+        resolved.push({ fromIndex, toIndex });
+    }
+    resolved.sort((left, right) => left.fromIndex - right.fromIndex || left.toIndex - right.toIndex);
+    const merged = [];
+    for (const range of resolved) {
+        const last = merged[merged.length - 1];
+        if (last !== undefined && range.fromIndex <= last.toIndex + 1) {
+            last.toIndex = Math.max(last.toIndex, range.toIndex);
+            continue;
         }
-        if (sourceRef.url !== undefined) {
-            refParts.push(`url=${String(sourceRef.url)}`);
+        merged.push({ fromIndex: range.fromIndex, toIndex: range.toIndex });
+    }
+    return merged;
+}
+/**
+ * Project one session's ranges into diary lines.
+ * Unusable bounds throw with a stable message the accept hook turns into reask.
+ */
+async function projectSessionRanges(input) {
+    assertDialogueSessionSourcePath(input.session.path, input.home);
+    let sessionLines;
+    try {
+        sessionLines = await readLedgerSessionJsonlLines(input.session.path);
+    }
+    catch (error) {
+        if (error instanceof TicketProvenanceInputError)
+            throw error;
+        // Only absence/path-shape misses are model input errors → reask.
+        // EISDIR = authorized-root path that is a directory, not a session file.
+        // EIO / EMFILE / EACCES / other runtime faults keep native identity + cause.
+        const code = errnoCode(error);
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new TicketProvenanceInputError(`session unreadable: ${input.session.path} (${detail})`, { cause: error });
         }
-        if (refParts.length > 0) {
-            lines.push(`- sourceRef: ${refParts.join(" · ")}`);
+        throw error;
+    }
+    const rows = sessionLines.map((entry) => entry.row);
+    const dialogue = adaptSessionDialogue(rows);
+    const seenIds = input.seenIds;
+    const lines = [];
+    const unparsable = [];
+    const ranges = normalizeResolvedRanges(input.session.ranges, sessionLines, input.session.path);
+    for (const range of ranges) {
+        for (let index = range.fromIndex; index <= range.toIndex; index += 1) {
+            const entry = sessionLines[index];
+            if (entry.row === undefined) {
+                const key = amendmentKey(input.s, entry.line);
+                const amendment = input.amendmentsByKey.get(key);
+                if (amendment !== undefined) {
+                    lines.push({
+                        speaker: amendment.speaker,
+                        s: input.s,
+                        line: entry.line,
+                        text: amendment.text,
+                    });
+                }
+                else {
+                    unparsable.push({ s: input.s, line: entry.line, raw: entry.raw });
+                }
+                continue;
+            }
+            for (const event of dialogue[index] ?? []) {
+                if (event.id !== undefined) {
+                    if (seenIds.has(event.id))
+                        continue;
+                    seenIds.add(event.id);
+                }
+                lines.push({
+                    speaker: event.speaker,
+                    s: input.s,
+                    line: entry.line,
+                    ...(event.id === undefined ? {} : { id: event.id }),
+                    text: event.text,
+                });
+            }
         }
-        lines.push("");
-        const transcript = typeof entry.transcript === "string" ? entry.transcript : JSON.stringify(entry);
-        const fence = markdownFenceFor(transcript);
-        lines.push(fence);
-        lines.push(transcript);
-        lines.push(fence);
-        lines.push("");
-    }
-    for (const payload of unprojected) {
-        index += 1;
-        lines.push(`## ${index}. 未投影`);
-        lines.push("");
-        const text = typeof payload === "string" ? payload : JSON.stringify(payload);
-        const fence = markdownFenceFor(text);
-        lines.push(fence);
-        lines.push(text);
-        lines.push(fence);
-        lines.push("");
-    }
-    return lines.join("\n");
+    }
+    return { lines, unparsable };
 }
 /**
- * Ensure the per-ticket JSONL volume partition exists (empty file OK).
- * Every bound-ticket court establishes the volume even with zero diary entries
- * (ADR 0075: 每票一份起居录送司天台). Does not forge entries.
+ * Reproject the unique diary file from the submitted bounds + optional amendments.
+ * Header + locating fields may change; dialogue text is taken from the source
+ * (or from a typed amendment). Does not append; the whole file is the projection.
+ * Persistence goes through the Sitian volume seam (rewriteSitianVolume).
  */
-export function ensureTicketProvenanceVolume(ticketNumber, cwd, home) {
-    const volume = resolveTicketProvenanceVolume(ticketNumber, cwd, home);
-    mkdirSync(volume.volumeDir, { recursive: true });
-    // Append-open creates an absent volume without ever truncating rows committed
-    // by a concurrent first writer.
-    appendFileSync(volume.recordFile, "", "utf8");
-    return volume;
-}
-/** Write the co-located human view next to the JSONL volume (derived, not dual-source).
- * Ensures volume dir exists so empty courts still get the md face. */
-export function writeTicketProvenanceHumanView(input) {
-    const volume = ensureTicketProvenanceVolume(input.ticketNumber, input.cwd, input.home);
-    const md = renderTicketProvenanceMarkdown({
-        ticketNumber: input.ticketNumber,
-        entries: input.entries,
-        ...(input.unprojected === undefined ? {} : { unprojected: input.unprojected }),
-    });
-    writeFileSync(volume.humanViewFile, md, "utf8");
-    return volume.humanViewFile;
+export async function reprojectTicketProvenance(input) {
+    const recordInput = ticketProvenanceRecordInput(input.ticketNumber, input.cwd, input.home);
+    const prior = await readTicketProvenance(input.ticketNumber, input.cwd, input.home);
+    const priorRaw = await readSitianVolumeText(recordInput);
+    const priorNonEmpty = priorRaw.text !== undefined && priorRaw.text.trim() !== "";
+    const amendments = input.amendments ?? [];
+    // Empty sessions: pure empty selection preserves non-empty volume. Amendments-only
+    // continuation reuses prior header sessions — never wash into accepted no-op.
+    let sessions = input.sessions;
+    if (sessions.length === 0) {
+        if (amendments.length > 0) {
+            const priorSessions = prior.header?.sessions;
+            if (priorSessions === undefined || priorSessions.length === 0) {
+                throw new TicketProvenanceInputError("amendments require sessions bounds (none submitted and no prior header sessions)");
+            }
+            sessions = priorSessions;
+        }
+        else if (priorNonEmpty) {
+            const now = new Date().toISOString();
+            const header = prior.header ??
+                {
+                    repo: resolveBookKeyFromGit(input.cwd),
+                    ticket: input.ticketNumber,
+                    createdAt: now,
+                    updatedAt: now,
+                    sessions: [],
+                };
+            return {
+                recordFile: prior.recordFile,
+                header,
+                lines: prior.lines,
+                unparsable: [],
+            };
+        }
+    }
+    const amendmentsByKey = new Map();
+    for (const amendment of amendments) {
+        amendmentsByKey.set(amendmentKey(amendment.s, amendment.line), amendment);
+    }
+    const lines = [];
+    const unparsable = [];
+    // First-seen native id across the whole reproject (rewritten session copies).
+    const seenIds = new Set();
+    for (let s = 0; s < sessions.length; s += 1) {
+        const projected = await projectSessionRanges({
+            s,
+            session: sessions[s],
+            amendmentsByKey,
+            seenIds,
+            ...(input.home === undefined ? {} : { home: input.home }),
+        });
+        lines.push(...projected.lines);
+        unparsable.push(...projected.unparsable);
+    }
+    const now = new Date().toISOString();
+    const header = {
+        repo: resolveBookKeyFromGit(input.cwd),
+        ticket: input.ticketNumber,
+        createdAt: prior.header?.createdAt ?? now,
+        updatedAt: now,
+        sessions,
+    };
+    // Still-open gaps → reask without publishing a partial/rejected projection.
+    if (unparsable.length > 0) {
+        return {
+            recordFile: prior.recordFile,
+            header,
+            lines,
+            unparsable,
+        };
+    }
+    const body = `${[JSON.stringify(header), ...lines.map((line) => JSON.stringify(line))].join("\n")}\n`;
+    const volume = await rewriteSitianVolume({ ...recordInput, body });
+    return {
+        recordFile: volume.recordFile,
+        header,
+        lines,
+        unparsable,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.4204",
+  "version": "0.1.4228",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/book-topology-migration.ts

@@ -44,12 +44,6 @@ export type BookTopologyMigrationContext = {
   readonly backupBooksDirectory: string;
   /** Fresh destination at the former books/ path. */
   readonly booksDirectory: string;
-  /**
-   * Ticket numbers whose records.jsonl grew during record-class placement.
-   * Human view is finalized once after all record-class migrators finish —
-   * never after ticket-provenance home alone (misplaced lines can still land).
-   */
-  readonly touchedTicketsByBook: Map<string, Set<number>>;
 };
 
 export type BookTopologyPartitionMigrator = {
@@ -203,7 +197,6 @@ export async function migrateBookTopology(input: {
   const context: BookTopologyMigrationContext = {
     backupBooksDirectory,
     booksDirectory,
-    touchedTicketsByBook: new Map(),
   };
   const partitions: MigrationPartitionReport[] = [];
   for (const migrator of input.migrators) {