@akagilnc/pi-workflow-roles 0.1.3708 → 0.1.3712

package/src/ticket-provenance.ts

@@ -3,7 +3,7 @@
  * Write/read via sitian facade only; no parallel destination logic.
  */
 import { createHash } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import {
@@ -16,8 +16,6 @@ import {
 import {
   TICKET_PROVENANCE_HUMAN_VIEW,
   TICKET_PROVENANCE_KIND,
-  TICKET_PROVENANCE_OFFERED_WATERMARK,
-  TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC,
   projectTicketProvenanceDiagnostic,
   projectTicketProvenanceEntry,
   type TicketProvenanceDiagnostic,
@@ -102,7 +100,6 @@ export type TicketProvenanceVolumePath = {
   readonly recordFile: string;
   readonly volumeDir: string;
   readonly humanViewFile: string;
-  readonly offeredWatermarkFile: string;
 };
 
 /** Resolve volume paths for a ticket without writing. */
@@ -122,115 +119,9 @@ export function resolveTicketProvenanceVolume(
     recordFile: path.recordFile,
     volumeDir: path.sessionDir,
     humanViewFile: join(path.sessionDir, TICKET_PROVENANCE_HUMAN_VIEW),
-    offeredWatermarkFile: join(path.sessionDir, TICKET_PROVENANCE_OFFERED_WATERMARK),
   };
 }
 
-/** Typed cause of an offered-identity watermark read failure. */
-export type TicketProvenanceWatermarkReason =
-  | "unreadable"
-  | "malformed-json"
-  | "bad-shape";
-
-/** Honest failure when the offered-identity watermark cannot be read as written. */
-export class TicketProvenanceWatermarkError extends Error {
-  readonly code = "ticket-provenance-watermark" as const;
-  readonly reason: TicketProvenanceWatermarkReason;
-  constructor(
-    reason: TicketProvenanceWatermarkReason,
-    message: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options);
-    this.name = "TicketProvenanceWatermarkError";
-    this.reason = reason;
-  }
-}
-
-/**
- * Read identities already offered to the collector (append-only watermark).
- * Absent file → empty set. Any non-empty line that is not a JSON object with a
- * non-empty string `identity` throws TicketProvenanceWatermarkError (失败诚实：
- * never interpret corruption as "unseen" and silently re-offer).
- */
-export function readOfferedIdentities(
-  ticketNumber: number,
-  cwd: string,
-  home?: string,
-): ReadonlySet<string> {
-  const { offeredWatermarkFile } = resolveTicketProvenanceVolume(ticketNumber, cwd, home);
-  if (!existsSync(offeredWatermarkFile)) return new Set();
-  let text: string;
-  try {
-    text = readFileSync(offeredWatermarkFile, "utf8");
-  } catch (error) {
-    throw new TicketProvenanceWatermarkError(
-      "unreadable",
-      `ticket-provenance offered watermark unreadable (${offeredWatermarkFile})`,
-      { cause: error },
-    );
-  }
-  const seen = new Set<string>();
-  const lines = text.split("\n");
-  for (let index = 0; index < lines.length; index += 1) {
-    const trimmed = lines[index]!.trim();
-    if (!trimmed) continue;
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(trimmed);
-    } catch (error) {
-      throw new TicketProvenanceWatermarkError(
-        "malformed-json",
-        `ticket-provenance offered watermark malformed JSON at line ${index + 1} (${offeredWatermarkFile})`,
-        { cause: error },
-      );
-    }
-    if (
-      typeof parsed !== "object" ||
-      parsed === null ||
-      Array.isArray(parsed) ||
-      typeof (parsed as { identity?: unknown }).identity !== "string" ||
-      (parsed as { identity: string }).identity.length === 0
-    ) {
-      throw new TicketProvenanceWatermarkError(
-        "bad-shape",
-        `ticket-provenance offered watermark bad shape at line ${index + 1} (${offeredWatermarkFile})`,
-      );
-    }
-    seen.add((parsed as { identity: string }).identity);
-  }
-  return seen;
-}
-
-/**
- * Append offered identities after a successful collector pass (selected or not).
- * Idempotent per identity within the file (skip already-present). Creates volume
- * dir only when writing the first watermark row.
- */
-export function recordOfferedIdentities(input: {
-  readonly ticketNumber: number;
-  readonly cwd: string;
-  readonly home?: string;
-  readonly identities: readonly string[];
-}): void {
-  if (input.identities.length === 0) return;
-  const { volumeDir, offeredWatermarkFile } = resolveTicketProvenanceVolume(
-    input.ticketNumber,
-    input.cwd,
-    input.home,
-  );
-  const already = new Set(readOfferedIdentities(input.ticketNumber, input.cwd, input.home));
-  const rows: string[] = [];
-  for (const identity of input.identities) {
-    if (identity.length === 0 || already.has(identity)) continue;
-    rows.push(`${JSON.stringify({ identity })}\n`);
-    already.add(identity);
-  }
-  if (rows.length === 0) return;
-  mkdirSync(volumeDir, { recursive: true });
-  appendFileSync(offeredWatermarkFile, rows.join(""), "utf8");
-}
-
 export type ReadTicketProvenanceResult = {
   /** Readable diary body entries only. */
   readonly entries: readonly TicketProvenanceEntry[];
@@ -359,103 +250,6 @@ export function ensureTicketProvenanceVolume(
   return volume;
 }
 
-/**
- * Append a typed diagnostic onto the ticket-provenance volume (append-only).
- * Same sitian kind + subject partition as diary entries; payload uses recordClass
- * discriminator — never forged as a source entry. No sidecar / parallel ledger.
- */
-export function appendTicketProvenanceDiagnostic(input: {
-  readonly ticketNumber: number;
-  readonly cwd: string;
-  readonly home?: string;
-  readonly diagnostic: TicketProvenanceDiagnostic;
-  readonly host?: string;
-  readonly source?: string;
-}): RecordPointer {
-  const subject = ticketProvenanceSubject(input.ticketNumber);
-  // quote-verify: content-stable identity so mid-batch retry does not duplicate.
-  // collector/issue-source: recordedAt keeps per-court failure history.
-  const identityParts =
-    input.diagnostic.diagnosticKind === "quote-verify-failed"
-      ? [
-          subject,
-          input.diagnostic.recordClass,
-          input.diagnostic.diagnosticKind,
-          input.diagnostic.cause,
-          input.diagnostic.reason ?? "",
-        ]
-      : [
-          subject,
-          input.diagnostic.recordClass,
-          input.diagnostic.diagnosticKind,
-          input.diagnostic.recordedAt,
-          input.diagnostic.cause,
-          input.diagnostic.reason ?? "",
-        ];
-  const identity = createHash("sha256")
-    .update(identityParts.join("\u0000"), "utf8")
-    .digest("hex");
-  return sitianReport({
-    level: "event",
-    kind: TICKET_PROVENANCE_KIND,
-    identity,
-    subject,
-    cwd: input.cwd,
-    ...(input.home === undefined ? {} : { home: input.home }),
-    host: input.host ?? "diarist",
-    source: input.source ?? "diarist-diagnostic",
-    payload: input.diagnostic,
-  });
-}
-
-/** Issue-face source acquisition failure — typed diagnostic on the ticket volume. */
-export function appendIssueSourceFailureDiagnostic(input: {
-  readonly ticketNumber: number;
-  readonly cwd: string;
-  readonly home?: string;
-  readonly cause: string;
-  readonly reason: string;
-  readonly recordedAt?: string;
-}): RecordPointer {
-  const recordedAt = input.recordedAt ?? new Date().toISOString();
-  return appendTicketProvenanceDiagnostic({
-    ticketNumber: input.ticketNumber,
-    cwd: input.cwd,
-    ...(input.home === undefined ? {} : { home: input.home }),
-    source: "diarist-issue-source",
-    diagnostic: {
-      recordClass: TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC,
-      diagnosticKind: "issue-source-failed",
-      cause: input.cause,
-      recordedAt,
-      reason: input.reason,
-    },
-  });
-}
-
-/** Quote reverse-verify failure — single diagnostic expression (not a diary entry). */
-export function appendQuoteVerifyFailureDiagnostic(input: {
-  readonly ticketNumber: number;
-  readonly cwd: string;
-  readonly home?: string;
-  readonly cause: string;
-  readonly recordedAt?: string;
-}): RecordPointer {
-  const recordedAt = input.recordedAt ?? new Date().toISOString();
-  return appendTicketProvenanceDiagnostic({
-    ticketNumber: input.ticketNumber,
-    cwd: input.cwd,
-    ...(input.home === undefined ? {} : { home: input.home }),
-    source: "diarist-quote-verify",
-    diagnostic: {
-      recordClass: TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC,
-      diagnosticKind: "quote-verify-failed",
-      cause: input.cause,
-      recordedAt,
-    },
-  });
-}
-
 /** 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: {

package/dist/diarist-mechanical.js

@@ -1,411 +0,0 @@
-/**
- * 起居郎 mechanical safeguard band — ADR 0075 / #582.
- * Deterministic: source enum helpers, candidate anchors, dedup, notification
- * filter, and verbatim quote reverse-verify. Never a production relevance gate.
- */
-import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { homedir } from "node:os";
-import { pathContainedIn, physicallyContainedIn, } from "./activation-ledger-topology.js";
-export const DEFAULT_QUOTE_MIN = 6;
-export class DiaristSourceReadError extends Error {
-    code = "diarist-source-read";
-    reason;
-    sourcePath;
-    constructor(reason, sourcePath, message, options) {
-        super(message, options);
-        this.name = "DiaristSourceReadError";
-        this.reason = reason;
-        this.sourcePath = sourcePath;
-    }
-}
-/**
- * Extract 「」 quotes from ticket face text for mechanical anchors.
- * Only quotes meeting min length are kept.
- */
-export function extractCornerQuotes(text, minLength = DEFAULT_QUOTE_MIN) {
-    const out = [];
-    const re = /「([^」]+)」/g;
-    let match;
-    while ((match = re.exec(text)) !== null) {
-        const q = match[1].trim();
-        if (q.length >= minLength)
-            out.push(q);
-    }
-    return out;
-}
-/** Build the mechanical anchor set from ticket number + face body. */
-export function buildDiaristAnchors(input) {
-    const fromBody = input.ticketBody === undefined ? [] : extractCornerQuotes(input.ticketBody);
-    const quotes = [...fromBody, ...(input.extraQuotes ?? [])];
-    const seen = new Set();
-    const uniqueQuotes = [];
-    for (const q of quotes) {
-        if (seen.has(q))
-            continue;
-        seen.add(q);
-        uniqueQuotes.push(q);
-    }
-    return {
-        ticketNumber: input.ticketNumber,
-        quotes: uniqueQuotes,
-    };
-}
-/** Drop notification/system noise blocks (typed flags only — no prose match). */
-export function filterNotifications(blocks) {
-    return blocks.filter((b) => !b.isNotification);
-}
-function blockKey(block) {
-    const r = block.sourceRef;
-    return [
-        block.sourceKind,
-        r.sessionFile ?? "",
-        r.entryId === undefined ? "" : String(r.entryId),
-        r.path ?? "",
-        r.url ?? "",
-        createHash("sha256").update(block.transcript, "utf8").digest("hex").slice(0, 16),
-    ].join("|");
-}
-/** Dedup by source pointer + transcript digest (compression replay ×N). */
-export function dedupeSourceBlocks(blocks) {
-    const seen = new Set();
-    const out = [];
-    for (const block of blocks) {
-        const key = blockKey(block);
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        out.push(block);
-    }
-    return out;
-}
-export function verifyQuotesVerbatim(sourceText, quotes) {
-    const failed = [];
-    for (const q of quotes) {
-        if (q.length === 0)
-            continue;
-        if (!sourceText.includes(q))
-            failed.push(q);
-    }
-    if (failed.length === 0)
-        return { ok: true };
-    return { ok: false, failedQuotes: failed };
-}
-/**
- * Mechanical safeguard only — never a relevance gate (ADR 0075 / 锚定宪法).
- * filter notifications (typed) → dedupe. Semantic selection is LLM-only.
- */
-export function mechanicalSafeguardPipeline(blocks) {
-    return dedupeSourceBlocks(filterNotifications(blocks));
-}
-/** Claude Code project-dir encoding: abs path with / → -. */
-export function encodeClaudeProjectDir(cwd) {
-    const abs = cwd.startsWith("/") ? cwd : `/${cwd}`;
-    return abs.replace(/\//g, "-");
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function messageText(message) {
-    if (typeof message === "string")
-        return message;
-    if (!isRecord(message))
-        return "";
-    const content = message.content;
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    const parts = [];
-    for (const part of content) {
-        if (typeof part === "string") {
-            parts.push(part);
-            continue;
-        }
-        if (!isRecord(part))
-            continue;
-        if (typeof part.text === "string")
-            parts.push(part.text);
-        else if (typeof part.content === "string")
-            parts.push(part.content);
-    }
-    return parts.join("\n");
-}
-function isNotificationRow(type, text) {
-    if (type === "queue-operation" || type === "system" || type === "progress") {
-        return true;
-    }
-    if (type === "user") {
-        // Local command / meta noise common in cc transcripts.
-        if (text.startsWith("<command-name>") || text.startsWith("<local-command-")) {
-            return true;
-        }
-        if (text.startsWith("<command-message>") || text.startsWith("<command-args>")) {
-            return true;
-        }
-    }
-    return false;
-}
-/**
- * Enumerate cc session user/assistant turns and human queued-command attachments under Claude projects roots.
- * cc-sessions-first source family (ADR 0075).
- * Directory/file/non-empty JSONL line failures throw DiaristSourceReadError
- * (失败诚实：不得把未读懂洗成没有来源块).
- */
-export function readCcSessionBlocks(options) {
-    const root = options.projectsRoot ?? join(homedir(), ".claude", "projects");
-    if (!existsSync(root))
-        return [];
-    const blocks = [];
-    const dirs = new Set();
-    for (const cwd of options.cwds) {
-        dirs.add(join(root, encodeClaudeProjectDir(cwd)));
-    }
-    // Also accept already-encoded folder names passed as cwd (test convenience).
-    for (const cwd of options.cwds) {
-        if (cwd.includes("projects"))
-            continue;
-        const direct = join(root, cwd);
-        if (existsSync(direct))
-            dirs.add(direct);
-    }
-    for (const dir of dirs) {
-        if (!existsSync(dir))
-            continue;
-        let dirStat;
-        try {
-            dirStat = statSync(dir);
-        }
-        catch (error) {
-            throw new DiaristSourceReadError("readdir-failed", dir, `diarist cc session dir unstatable (${dir})`, { cause: error });
-        }
-        if (!dirStat.isDirectory())
-            continue;
-        let files;
-        try {
-            files = readdirSync(dir).filter((name) => name.endsWith(".jsonl"));
-        }
-        catch (error) {
-            throw new DiaristSourceReadError("readdir-failed", dir, `diarist cc session dir unreadable (${dir})`, { cause: error });
-        }
-        for (const name of files) {
-            const sessionFile = join(dir, name);
-            let text;
-            try {
-                text = readFileSync(sessionFile, "utf8");
-            }
-            catch (error) {
-                throw new DiaristSourceReadError("file-unreadable", sessionFile, `diarist cc session file unreadable (${sessionFile})`, { cause: error });
-            }
-            const lines = text.split("\n");
-            for (let lineNo = 0; lineNo < lines.length; lineNo += 1) {
-                const line = lines[lineNo];
-                if (!line.trim())
-                    continue;
-                let parsed;
-                try {
-                    parsed = JSON.parse(line);
-                }
-                catch (error) {
-                    throw new DiaristSourceReadError("jsonl-line-unparseable", sessionFile, `diarist cc session JSONL line ${lineNo + 1} unparseable (${sessionFile})`, { cause: error });
-                }
-                // Unknown row shape (not user/assistant or a human queued-command attachment) is ignored — not a read failure.
-                if (!isRecord(parsed))
-                    continue;
-                const type = typeof parsed.type === "string" ? parsed.type : "";
-                const queuedCommand = type === "attachment" &&
-                    isRecord(parsed.attachment) &&
-                    parsed.attachment.type === "queued_command" &&
-                    isRecord(parsed.attachment.origin) &&
-                    parsed.attachment.origin.kind === "human" &&
-                    typeof parsed.attachment.prompt === "string"
-                    ? parsed.attachment.prompt
-                    : undefined;
-                if (type !== "user" && type !== "assistant" && queuedCommand === undefined) {
-                    continue;
-                }
-                const transcript = queuedCommand ?? messageText(parsed.message ?? parsed);
-                if (transcript.trim() === "")
-                    continue;
-                const entryId = typeof parsed.uuid === "string"
-                    ? parsed.uuid
-                    : typeof parsed.id === "string"
-                        ? parsed.id
-                        : `${basename(sessionFile)}:${lineNo + 1}`;
-                const timestamp = typeof parsed.timestamp === "string"
-                    ? parsed.timestamp
-                    : new Date(0).toISOString();
-                const notification = isNotificationRow(type, transcript);
-                blocks.push({
-                    sourceKind: "cc-session",
-                    sourceRef: { sessionFile, entryId },
-                    transcript,
-                    timestamp,
-                    isUserTurn: type === "user" || queuedCommand !== undefined,
-                    isNotification: notification,
-                });
-            }
-        }
-    }
-    return blocks;
-}
-/**
- * Issue body + comments + 「」 decree spans as typed source blocks.
- * Each block keeps its own sourceRef (url / comment id) — never merge attachments here.
- */
-export function readIssueFaceBlocks(input) {
-    const fallbackTs = input.timestamp ?? new Date(0).toISOString();
-    const blocks = [];
-    const body = input.face.body;
-    if (body.trim() !== "") {
-        blocks.push({
-            sourceKind: "issue-body-comment",
-            sourceRef: { url: input.face.bodyUrl, entryId: "body" },
-            transcript: body,
-            timestamp: fallbackTs,
-            isUserTurn: true,
-            isNotification: false,
-        });
-        const quotes = extractCornerQuotes(body);
-        for (let i = 0; i < quotes.length; i += 1) {
-            const q = quotes[i];
-            blocks.push({
-                sourceKind: "ticket-decree-block",
-                sourceRef: { url: input.face.bodyUrl, entryId: `decree-${i + 1}` },
-                transcript: q,
-                timestamp: fallbackTs,
-                isUserTurn: true,
-                isNotification: false,
-            });
-        }
-    }
-    for (const comment of input.face.comments) {
-        if (comment.body.trim() === "")
-            continue;
-        blocks.push({
-            sourceKind: "issue-body-comment",
-            sourceRef: {
-                url: comment.htmlUrl,
-                entryId: comment.id,
-            },
-            transcript: comment.body,
-            timestamp: comment.createdAt || fallbackTs,
-            isUserTurn: true,
-            isNotification: false,
-        });
-    }
-    return blocks;
-}
-/** Relative root every ADR decision-key read must stay under (ADR 0038). */
-export const DIARIST_ADR_ROOT_REL = "docs/adr";
-/**
- * Read applicable ADR files as decision-key source blocks.
- * Real IO seam owns lexical + physical containment under cwd/docs/adr (ADR 0038).
- * Missing / unreadable / escape → typed DiaristSourceReadError (失败诚实).
- */
-export function readAdrDecisionKeyBlocks(input) {
-    const timestamp = input.timestamp ?? new Date(0).toISOString();
-    const blocks = [];
-    const cwdAbs = resolve(input.cwd);
-    const adrRootAbs = resolve(cwdAbs, DIARIST_ADR_ROOT_REL);
-    let adrRootReal;
-    try {
-        // Prefer the real ADR root when it exists; otherwise fall back to cwd real
-        // so physical checks still have a stable anchor before the first ADR file.
-        adrRootReal = existsSync(adrRootAbs)
-            ? realpathSync(adrRootAbs)
-            : resolve(realpathSync(cwdAbs), DIARIST_ADR_ROOT_REL);
-    }
-    catch (error) {
-        throw new DiaristSourceReadError("adr-unreadable", cwdAbs, `diarist ADR root is not resolvable (${adrRootAbs})`, { cause: error });
-    }
-    for (const rel of input.adrPaths) {
-        const segments = rel.split(/[/\\]/);
-        // Claimed path must sit under docs/adr/ with no traversal segments.
-        if (segments[0] !== "docs" ||
-            segments[1] !== "adr" ||
-            segments.length < 3 ||
-            segments.some((part) => part === "" || part === "." || part === "..")) {
-            throw new DiaristSourceReadError("adr-escape", resolve(cwdAbs, rel), `diarist referenced ADR escapes docs/adr (${rel})`);
-        }
-        const abs = resolve(cwdAbs, rel);
-        // Lexical containment under docs/adr before any read (ADR 0038).
-        if (abs !== adrRootAbs && !pathContainedIn(adrRootAbs, abs)) {
-            throw new DiaristSourceReadError("adr-escape", abs, `diarist referenced ADR escapes docs/adr (${rel})`);
-        }
-        if (!existsSync(abs)) {
-            throw new DiaristSourceReadError("adr-missing", abs, `diarist referenced ADR missing (${rel})`);
-        }
-        let realAbs;
-        try {
-            realAbs = realpathSync(abs);
-        }
-        catch (error) {
-            throw new DiaristSourceReadError("adr-unreadable", abs, `diarist ADR path is not resolvable (${abs})`, { cause: error });
-        }
-        if (realAbs !== adrRootReal && !physicallyContainedIn(adrRootReal, realAbs)) {
-            throw new DiaristSourceReadError("adr-escape", abs, `diarist referenced ADR escapes docs/adr physically (${rel})`);
-        }
-        let text;
-        try {
-            text = readFileSync(realAbs, "utf8");
-        }
-        catch (error) {
-            throw new DiaristSourceReadError("adr-unreadable", realAbs, `diarist ADR file unreadable (${realAbs})`, { cause: error });
-        }
-        if (text.trim() === "")
-            continue;
-        blocks.push({
-            sourceKind: "adr-decision-key",
-            sourceRef: { path: rel },
-            transcript: text,
-            timestamp,
-            isUserTurn: true,
-            isNotification: false,
-        });
-    }
-    return blocks;
-}
-/**
- * Build an llm-semantic entry after reverse-verify succeeds.
- * `quotes` are the LLM-claimed quotes that must be verbatim in transcript.
- * basis.anchors record ticket # + mechanical/claimed quotes for audit only.
- * Failure returns failedQuotes only — caller records a single diagnostic (not a
- * disguised diary entry / dead basis.method).
- */
-export function blockToLlmEntry(block, input) {
-    const verify = verifyQuotesVerbatim(block.transcript, input.quotes);
-    if (!verify.ok) {
-        return {
-            ok: false,
-            failedQuotes: verify.failedQuotes,
-            cause: `verbatim verify failed: ${verify.failedQuotes.join(" | ")}`,
-        };
-    }
-    // Ticket + mechanical face quotes + claimed quotes — reference/反验 only.
-    const anchorNotes = [`#${input.anchors.ticketNumber}`];
-    const seen = new Set(anchorNotes);
-    for (const q of [...input.anchors.quotes, ...input.quotes]) {
-        if (seen.has(q))
-            continue;
-        seen.add(q);
-        anchorNotes.push(q);
-        if (anchorNotes.length >= 12)
-            break;
-    }
-    return {
-        ok: true,
-        entry: {
-            basis: {
-                method: "llm-semantic",
-                anchors: anchorNotes,
-                ...(input.note === undefined ? {} : { note: input.note }),
-            },
-            sourceKind: block.sourceKind,
-            sourceRef: block.sourceRef,
-            transcript: block.transcript,
-            timestamp: block.timestamp,
-        },
-    };
-}