@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/dist/ticket-provenance.js

@@ -0,0 +1,340 @@
+/**
+ * 起居录 volume helpers — ADR 0075 / #582.
+ * 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 { join } from "node:path";
+import { resolveSitianRecordPath, sitianReport, readSitianRecords, } from "./sitian-facade.js";
+import { TICKET_PROVENANCE_HUMAN_VIEW, TICKET_PROVENANCE_KIND, TICKET_PROVENANCE_OFFERED_WATERMARK, TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC, projectTicketProvenanceDiagnostic, projectTicketProvenanceEntry, } from "./ticket-provenance-contracts.js";
+/** Subject string for ticket-keyed volumes — history follows the ticket. */
+export function ticketProvenanceSubject(ticketNumber) {
+    if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1) {
+        throw new Error(`ticket-provenance subject requires a positive ticket number, got ${String(ticketNumber)}`);
+    }
+    return String(ticketNumber);
+}
+/**
+ * Deterministic entry identity for sitian entry-level idempotency.
+ * Same ticket + source pointer + transcript → same identity → no re-append.
+ */
+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");
+}
+/** Append one transcribed block; returns existing pointer on identity hit. */
+export function appendTicketProvenanceEntry(input) {
+    const subject = ticketProvenanceSubject(input.ticketNumber);
+    const identity = ticketProvenanceEntryIdentity({
+        ticketNumber: input.ticketNumber,
+        sourceKind: input.entry.sourceKind,
+        sourceRef: input.entry.sourceRef,
+        transcript: input.entry.transcript,
+    });
+    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",
+        payload: input.entry,
+        raw: input.entry.sourceRef.sessionFile !== undefined &&
+            input.entry.sourceRef.entryId !== undefined
+            ? {
+                sessionFile: input.entry.sourceRef.sessionFile,
+                entryId: input.entry.sourceRef.entryId,
+            }
+            : undefined,
+    });
+}
+/** Resolve volume paths for a ticket without writing. */
+export function resolveTicketProvenanceVolume(ticketNumber, cwd, home) {
+    const path = resolveSitianRecordPath({
+        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),
+        offeredWatermarkFile: join(path.sessionDir, TICKET_PROVENANCE_OFFERED_WATERMARK),
+    };
+}
+/** Honest failure when the offered-identity watermark cannot be read as written. */
+export class TicketProvenanceWatermarkError extends Error {
+    code = "ticket-provenance-watermark";
+    reason;
+    constructor(reason, message, options) {
+        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, cwd, home) {
+    const { offeredWatermarkFile } = resolveTicketProvenanceVolume(ticketNumber, cwd, home);
+    if (!existsSync(offeredWatermarkFile))
+        return new Set();
+    let text;
+    try {
+        text = readFileSync(offeredWatermarkFile, "utf8");
+    }
+    catch (error) {
+        throw new TicketProvenanceWatermarkError("unreadable", `ticket-provenance offered watermark unreadable (${offeredWatermarkFile})`, { cause: error });
+    }
+    const seen = new Set();
+    const lines = text.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const trimmed = lines[index].trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        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.identity !== "string" ||
+            parsed.identity.length === 0) {
+            throw new TicketProvenanceWatermarkError("bad-shape", `ticket-provenance offered watermark bad shape at line ${index + 1} (${offeredWatermarkFile})`);
+        }
+        seen.add(parsed.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) {
+    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 = [];
+    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");
+}
+/** Read projected diary entries + diagnostics for a ticket (empty when volume absent). */
+export async function readTicketProvenance(ticketNumber, cwd, home) {
+    const { recordFile } = resolveTicketProvenanceVolume(ticketNumber, cwd, home);
+    const { records } = await readSitianRecords(recordFile);
+    const entries = [];
+    const diagnostics = [];
+    let skipped = 0;
+    for (const record of records) {
+        if (record.kind !== TICKET_PROVENANCE_KIND) {
+            skipped += 1;
+            continue;
+        }
+        // Diagnostics first — same partition, separate projection (never body).
+        const diagnostic = projectTicketProvenanceDiagnostic(record.payload);
+        if (diagnostic !== undefined) {
+            diagnostics.push(diagnostic);
+            continue;
+        }
+        const entry = projectTicketProvenanceEntry(record.payload);
+        if (entry === undefined) {
+            skipped += 1;
+            continue;
+        }
+        entries.push(entry);
+    }
+    return { entries, diagnostics, records, recordFile, skipped };
+}
+/**
+ * Fence long enough that any backtick run inside `text` cannot close the block.
+ * Presentation helper only — not a machine contract; not exported.
+ */
+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));
+}
+/**
+ * Render a local human-read markdown view from entries.
+ * Presentation only — machines bite JSONL. No wording lock for consumers.
+ */
+export function renderTicketProvenanceMarkdown(input) {
+    const lines = [
+        `# 起居录 · #${input.ticketNumber}`,
+        "",
+        `条目数：${input.entries.length}`,
+        "",
+    ];
+    let index = 0;
+    for (const entry of input.entries) {
+        index += 1;
+        lines.push(`## ${index}. ${entry.sourceKind} · ${entry.timestamp}`);
+        lines.push("");
+        lines.push(`- basis.method: \`${entry.basis.method}\``);
+        if (entry.basis.anchors !== undefined && entry.basis.anchors.length > 0) {
+            lines.push(`- anchors: ${entry.basis.anchors.map((a) => `\`${a}\``).join(", ")}`);
+        }
+        if (entry.basis.note !== undefined) {
+            lines.push(`- note: ${entry.basis.note}`);
+        }
+        const refParts = [];
+        if (entry.sourceRef.sessionFile !== undefined) {
+            refParts.push(`sessionFile=${entry.sourceRef.sessionFile}`);
+        }
+        if (entry.sourceRef.entryId !== undefined) {
+            refParts.push(`entryId=${String(entry.sourceRef.entryId)}`);
+        }
+        if (entry.sourceRef.path !== undefined) {
+            refParts.push(`path=${entry.sourceRef.path}`);
+        }
+        if (entry.sourceRef.url !== undefined) {
+            refParts.push(`url=${entry.sourceRef.url}`);
+        }
+        if (refParts.length > 0) {
+            lines.push(`- sourceRef: ${refParts.join(" · ")}`);
+        }
+        lines.push("");
+        const fence = markdownFenceFor(entry.transcript);
+        lines.push(fence);
+        lines.push(entry.transcript);
+        lines.push(fence);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * 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 ticket-provenance-file — 每票一份起居录). Does not forge entries.
+ */
+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;
+}
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    const volume = ensureTicketProvenanceVolume(input.ticketNumber, input.cwd, input.home);
+    const md = renderTicketProvenanceMarkdown({
+        ticketNumber: input.ticketNumber,
+        entries: input.entries,
+    });
+    writeFileSync(volume.humanViewFile, md, "utf8");
+    return volume.humanViewFile;
+}

package/extensions/role-runtime.ts

@@ -36,10 +36,15 @@ import {
   formatNavigatorRoleHelp,
 } from "../src/role-runtime.ts";
 import { createPiJudgeAuditor } from "../src/judge-auditor.ts";
+import { loadAuditorSoulFromSubjectInput } from "../src/auditor-soul.ts";
 import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "../src/session-opening-materials.ts";
 const extensionPath = fileURLToPath(import.meta.url);
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const navigatorRoutePlaybookPath = fileURLToPath(new URL("../resources/navigator-route-playbook.md", import.meta.url));
+// #675: nested public summons (gate/auditor/evidence-child) resolve root via env under jiti.
+if (process.env.AK_ROLE_PACKAGE_ROOT === undefined || process.env.AK_ROLE_PACKAGE_ROOT.trim() === "") {
+  process.env.AK_ROLE_PACKAGE_ROOT = packageRoot;
+}
 
 // Cold `pi -e <extension> --help` must cover installed-package process startup under CI load.
 // This bound is process-startup budget only — not settlement-to-visible presentation latency.
@@ -131,6 +136,8 @@ export default function roleRuntime(pi: ExtensionAPI): void {
     loadInspectorSoul: () => loadMainRoleSessionMaterials("inspector"),
     loadGatekeeperSoul: () => loadGatekeeperSessionMaterials("gatekeeper"),
     loadNavigatorSoul: () => loadMainRoleSessionMaterials("navigator"),
+    loadAuditorSoul: () => loadAuditorSoulFromSubjectInput(),
+    loadEvidenceChildSoul: () => loadMainRoleSessionMaterials("evidence-child"),
     loadNotarySourceRun: loadNotarySourceRunLocator,
     loadNavigatorWorkContext: (options) => loadNavigatorWorkContext(pi, options),
     createNavigatorAttendance: (options) => {

package/package.json

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

package/scripts/build-package.mjs

@@ -14,8 +14,9 @@ const entries = [
   // Navigator package-graph dependencies used by attendance settlement.
   // navigator-session-contracts is a static import of the published attendance root
   // (#590: published non-bundle graph must stay closed under its own relative edges).
-  "evidence-child-executor",
+  "navigator-public-session",
   "navigator-session-contracts",
+  "public-role-summons",
   "pi/in-process-session",
   "activation-ledger-git",
   "activation-ledger-topology",

package/souls/doctor-auditor.md

@@ -21,3 +21,4 @@
 冲突导致无法判断合规时，提交 `escalate` 并写明问题和可选项。
 
 输出调用 `ak_doctor_audit_decision`。
+

package/souls/evidence-child.md

@@ -0,0 +1 @@
+# 取证子

package/src/acp-host/production-host.ts

@@ -23,6 +23,7 @@ import { loadPackagedCanonicalSkillBinding } from "../package-resources/method-s
 import { createPerDispatchReviewerAgent } from "../reviewer-agent.ts";
 import { formatNavigatorRoleHelp, type RoleRuntimeDependencies } from "../role-runtime.ts";
 import { createReviewerPinnedGitReader } from "../reviewer-pinned-git.ts";
+import { loadAuditorSoulFromSubjectInput } from "../auditor-soul.ts";
 import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "../session-opening-materials.ts";
 import { acpStdioArgs, resolveAcpBinary, type AcpHostDescription } from "./description.ts";
 import { createComposedAcpRoleTurnHost } from "./role-envelope.ts";
@@ -61,6 +62,8 @@ export function createAcpRoleRuntimeDependencies(packageRoot: string): RoleRunti
     loadInspectorSoul: () => loadMainRoleSessionMaterials("inspector"),
     loadGatekeeperSoul: () => loadGatekeeperSessionMaterials("gatekeeper"),
     loadNavigatorSoul: () => loadMainRoleSessionMaterials("navigator"),
+    loadAuditorSoul: () => loadAuditorSoulFromSubjectInput(),
+    loadEvidenceChildSoul: () => loadMainRoleSessionMaterials("evidence-child"),
     loadNotarySoul: () => loadMainRoleSessionMaterials("notary"),
     loadCountersignSoul: () => loadMainRoleSessionMaterials("countersign"),
     loadGleanerLeftSoul: () => loadMainRoleSessionMaterials("gleaner-left"),

package/src/acp-host/role-envelope.ts

@@ -4,7 +4,7 @@ import { createServer, type Server, type Socket } from "node:net";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { requireGatekeeperPass } from "../gatekeeper-role.ts";
+import { requireGatekeeperPass } from "../gatekeeper-pass-envelope.ts";
 import type {
   HostContext,
   HostEventRegistration,
@@ -298,7 +298,7 @@ export async function prepareAcpRoleEnvelope(options: {
     if (record.kind === "role_infrastructure_failure") return;
     const code = typeof record.code === "string" && record.code.length > 0
       ? record.code
-      : record.status === "bounce" || record.status === "no_receipt"
+      : record.status === "bounce" || record.status === "no_receipt" || record.status === "unreadable"
         ? record.status
         : undefined;
     if (code === undefined) return;

package/src/acp-host/role-turn-host.ts

@@ -270,7 +270,15 @@ export function createAcpRoleTurnHost(config: AcpRoleTurnHostConfig): RoleTurnHo
             priorNativePaths !== undefined && priorNativePaths.length > 0
               ? `${prepared.prompt}\n${priorNativePaths.join("\n")}`
               : prepared.prompt;
-          const abortSignal = prepared.abortSignal;
+          // Envelope infra abort and parent cancellation (#675 nested summons) are
+          // the same race face here: either one ends the ACP round and the finally
+          // block cancels + closes the child session.
+          const abortSignal =
+            request.signal === undefined
+              ? prepared.abortSignal
+              : prepared.abortSignal === undefined
+                ? request.signal
+                : AbortSignal.any([prepared.abortSignal, request.signal]);
           const activeConnection = connection;
 
           /** Race ACP prompt against envelope abort so infra failInfrastructure cannot hang (#593). */

package/src/analyst-gate-cycles-read.ts

@@ -434,8 +434,34 @@ function pairGateRounds(
     .map((round, index) => ({ ...round, roundIndex: index + 1 }));
 }
 
+/** Resolve a direct-officer-run-pointer file to the officer session 正本 path. */
+async function resolveOfficerSessionFromPointerFile(
+  pointerPath: string,
+): Promise<string | undefined> {
+  const { readFile } = await import("node:fs/promises");
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await readFile(pointerPath, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `direct officer run pointer unreadable in ${pointerPath}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  if (!isRecord(raw) || raw.kind !== "direct-officer-run-pointer" || raw.version !== 1) {
+    throw new Error(`direct officer run pointer has unknown shape in ${pointerPath}`);
+  }
+  const sessionFile = raw.sessionFile;
+  if (typeof sessionFile !== "string" || sessionFile.trim() === "") {
+    throw new Error(`direct officer run pointer missing sessionFile in ${pointerPath}`);
+  }
+  return sessionFile;
+}
+
 /**
  * Read and pair gate-cycle rounds from one or more auditor-roles directories.
+ * Accepts historical nested JSONL volumes and #675 direct-officer-run-pointer
+ * files that name the independent officer session 正本.
  * ENOENT (directory truly absent) → []. ENOTDIR and other errors propagate
  * (failure honesty — damaged topology must not wash to zero rounds).
  *
@@ -456,7 +482,11 @@ export async function readAnalystGateCyclesFromAuditorRoles(
     try {
       const entries = await readdir(directory, { withFileTypes: true });
       names = entries
-        .filter((e) => e.isFile() && e.name.endsWith(".jsonl"))
+        .filter(
+          (e) =>
+            e.isFile()
+            && (e.name.endsWith(".jsonl") || e.name.endsWith(".pointer.json")),
+        )
         .map((e) => e.name)
         .sort();
     } catch (error) {
@@ -464,7 +494,12 @@ export async function readAnalystGateCyclesFromAuditorRoles(
       throw error;
     }
     for (const name of names) {
-      const classified = await classifyAuditorVolume(join(directory, name));
+      const path = join(directory, name);
+      const sessionPath = name.endsWith(".pointer.json")
+        ? await resolveOfficerSessionFromPointerFile(path)
+        : path;
+      if (sessionPath === undefined) continue;
+      const classified = await classifyAuditorVolume(sessionPath);
       for (const volume of classified) {
         if (
           options.parentSessionFile !== undefined &&

package/src/archivist-record-entry.ts

@@ -3,7 +3,7 @@
  * 调用方只声明自己是谁的什么；落点由候簿拓扑算出，签名不含任何落点/路径参数。
  * 「谁调了谁」复用 Pi parentSession + ADR 0047 correlation，不新增 caller 字段。
  */
-import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, resolve, join } from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 
@@ -224,3 +224,47 @@ export function createRecordSessionOpen(options: CreateRecordSessionOptions): Re
 export function createRecordSession(options: CreateRecordSessionOptions): SessionManager {
   return createRecordSessionOpen(options).session;
 }
+
+
+/** Typed parent-side pointer to an independent officer run 正本 (ADR 0079 / #675). */
+export const DIRECT_OFFICER_RUN_POINTER_KIND = "direct-officer-run-pointer" as const;
+
+export type DirectOfficerRunPointer = {
+  readonly version: 1;
+  readonly kind: typeof DIRECT_OFFICER_RUN_POINTER_KIND;
+  readonly officer: "inspector" | "notary";
+  /** Absolute path to the officer session.jsonl 正本. */
+  readonly sessionFile: string;
+  /** Officer run directory when known. */
+  readonly runDirectory?: string;
+};
+
+/**
+ * Book a typed pointer under parent session/auditor-roles (same nest owner as
+ * createRecordSession). Never fabricates user/assistant/toolResult rows (#675).
+ * Directory placement stays with the archivist record entry (ADR 0018 / 0065).
+ */
+export function bookDirectOfficerRunPointer(options: {
+  readonly parentSessionFile: string;
+  readonly officer: "inspector" | "notary";
+  readonly sessionFile: string;
+  readonly runDirectory?: string;
+}): DirectOfficerRunPointer {
+  const nest = join(dirname(options.parentSessionFile), "auditor-roles");
+  mkdirSync(nest, { recursive: true });
+  const pointer: DirectOfficerRunPointer = {
+    version: 1,
+    kind: DIRECT_OFFICER_RUN_POINTER_KIND,
+    officer: options.officer,
+    sessionFile: options.sessionFile,
+    ...(options.runDirectory !== undefined && options.runDirectory.trim() !== ""
+      ? { runDirectory: options.runDirectory }
+      : {}),
+  };
+  writeFileSync(
+    join(nest, `${options.officer}-${Date.now().toString(36)}.pointer.json`),
+    `${JSON.stringify(pointer)}\n`,
+    "utf8",
+  );
+  return pointer;
+}

package/src/audit-escalation.ts

@@ -175,6 +175,14 @@ export type ComplianceDecisionHandlers<T> = {
     facts: Extract<ComplianceDecision, { status: "no-receipt" }>,
     usageProjection: { usage?: Usage },
   ) => T | PromiseLike<T>;
+  /**
+   * Parent work stands with typed unreadable audit fact (ADR 0055 / §0).
+   * Must not collapse into ordinary pass (forged role decision).
+   */
+  unreadable?: (
+    facts: Extract<ComplianceDecision, { status: "unreadable" }>,
+    usageProjection: { usage?: Usage },
+  ) => T | PromiseLike<T>;
   revise: (violations: readonly unknown[]) => T | PromiseLike<T>;
   escalate: (result: AuditEscalationToolResult) => T | PromiseLike<T>;
 };
@@ -201,6 +209,15 @@ export async function disposeComplianceDecision<T>(
         decision,
         decision.usage === undefined ? {} : { usage: decision.usage },
       );
+    case "unreadable":
+      // Parent candidate stands; audit shape failure is a typed parallel fact — not pass.
+      if (handlers.unreadable === undefined) {
+        throw new Error("Compliance unreadable projection handler is unavailable");
+      }
+      return await handlers.unreadable(
+        decision,
+        decision.usage === undefined ? {} : { usage: decision.usage },
+      );
     case "revise":
       return await handlers.revise(decision.violations);
     case "escalate":

package/src/auditor-role.ts

@@ -0,0 +1,22 @@
+/**
+ * Public Auditor (审刑院) role — filed-officer envelope (#675).
+ */
+import {
+  AUDITOR_ACCEPTED_TEXT,
+  AUDITOR_OUTPUT_TOOL_NAME,
+  auditorOutputSchema,
+} from "./package-contracts/auditor-output.ts";
+
+export { AUDITOR_ACCEPTED_TEXT, AUDITOR_OUTPUT_TOOL_NAME };
+
+export type AuditorRuntimeDependencies = {
+  loadSoul(): Promise<string>;
+};
+
+export const AUDITOR_TOOL_SPEC = {
+  name: AUDITOR_OUTPUT_TOOL_NAME,
+  label: "审刑院输出",
+  description: "审刑院终局回执，状态为 pass、revise 或 escalate。",
+  promptSnippet: "审刑院终局回执",
+  parameters: auditorOutputSchema,
+} as const;