@akagilnc/pi-workflow-roles 0.1.1751

package/src/compliance-transport.ts

@@ -0,0 +1,130 @@
+import type { Api, AssistantMessage, Model, Usage } from "@earendil-works/pi-ai";
+import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  executeAuditorChild,
+  type AuditorCompletion,
+} from "./evidence-child-executor.ts";
+import { createAuditorDossierTool } from "./auditor-dossier-tool.ts";
+import type { DossierObservation } from "./dossier-resolution.ts";
+
+export type ComplianceCompletion = AuditorCompletion;
+export type ComplianceArgumentRootType = "null" | "array" | "undefined" | "string" | "number" | "boolean" | "bigint" | "symbol" | "function";
+export type ComplianceAuditObservation =
+  | { kind: "non-object-arguments"; type: ComplianceArgumentRootType }
+  | { kind: "object-status-unreadable"; status: "missing" | "unknown" }
+  | DossierObservation;
+export type ComplianceAuditIncomplete = { status: "audit-incomplete"; observation: ComplianceAuditObservation; candidate: unknown; usage?: Usage };
+export type ComplianceDecision = { status: "pass"; usage?: Usage } | { status: "revise"; violations: readonly unknown[]; usage?: Usage } | { status: "escalate"; conflicts?: unknown; decisionGate?: unknown; usage?: Usage } | ComplianceAuditIncomplete;
+export type ComplianceDispatch = { model: Model<Api>; auth: { apiKey?: string; headers?: Record<string, string | null>; env?: Record<string, string> } };
+
+/** Zero-projection kickoff — soul already carries dossier-fetch duty; no hand-delivered materials. */
+export const AUDITOR_DOSSIER_PROMPT = "Audit the current run dossier." as const;
+
+const nonblank = Type.String({ minLength: 1, pattern: "\\S" });
+const decisionGateSchema = Type.Object({ question: nonblank, options: Type.Array(nonblank, { minItems: 1 }) }, { additionalProperties: false });
+// Transport must retain malformed candidates so they can settle as typed
+// audit-incomplete outcomes; status values are guidance, not a schema gate.
+export const complianceDecisionSchema = Type.Object({ status: Type.Unknown({ description: "Auditor decision status." }), violations: Type.Array(nonblank, { description: "Observed compliance violations." }), conflicts: Type.Array(nonblank, { description: "Unresolved authority or execution conflicts." }), decisionGate: Type.Union([decisionGateSchema, Type.Null()], { description: "Escalation question and available options." }) }, { additionalProperties: true, required: [] });
+
+export function createComplianceDecisionTool(name: string, description: string) {
+  return { name, description, parameters: complianceDecisionSchema, async execute(_id: string, params: unknown): Promise<AgentToolResult<unknown>> { return { content: [{ type: "text", text: "Compliance decision received" }], details: params, terminate: true }; } };
+}
+
+export async function prepareComplianceDispatch(model: Model<Api>, context: ExtensionContext, label: string): Promise<ComplianceDispatch> {
+  const resolution = await context.modelRegistry.getProviderAuth(model.provider).catch((error: unknown) => { throw new Error(`${label} authentication failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); });
+  if (resolution === undefined) throw new Error(`${label} authentication failed: provider is not configured: ${model.provider}`);
+  const auth = await context.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok) throw new Error(`${label} authentication failed: ${auth.error}`);
+  const env = auth.env ?? resolution.env;
+  return { model: resolution.auth.baseUrl ? { ...model, baseUrl: resolution.auth.baseUrl } : model, auth: { ...(auth.apiKey === undefined ? {} : { apiKey: auth.apiKey }), ...(auth.headers === undefined ? {} : { headers: auth.headers }), ...(env === undefined ? {} : { env }) } };
+}
+
+export const COMPLIANCE_RESPONSE_ENTRY_TYPE = "ak_compliance_response" as const;
+export const AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE = "ak_auditor_parent_attempt_binding" as const;
+export const AUDITOR_COMPLIANCE_FAILURE_ENTRY_TYPE = "ak_auditor_compliance_failure" as const;
+
+export type AuditorParentAttemptBinding = {
+  readonly version: 1;
+  readonly parent: {
+    readonly sessionId?: string;
+    readonly sessionFile?: string;
+    readonly attemptEntryId?: string;
+  };
+};
+export class ComplianceResponseRetentionError extends Error {
+  constructor(message: string, options?: ErrorOptions) { super(message, options); this.name = "ComplianceResponseRetentionError"; }
+}
+export type ActiveSessionResponseAppender = { appendCustomEntry(customType: string, data?: unknown): string };
+/** Unique owner for session custom-entry append with availability check and typed failure. */
+export function appendActiveSessionCustomEntry(
+  context: ExtensionContext,
+  customType: string,
+  data?: unknown,
+  labels: { unavailable?: string; failed?: string } = {},
+): string {
+  const manager = context.sessionManager as unknown as Partial<ActiveSessionResponseAppender> | undefined;
+  if (typeof manager?.appendCustomEntry !== "function") {
+    throw new ComplianceResponseRetentionError(
+      labels.unavailable ?? "session custom entry append is unavailable",
+    );
+  }
+  try {
+    return manager.appendCustomEntry(customType, data);
+  } catch (error) {
+    throw new ComplianceResponseRetentionError(
+      labels.failed ?? "session custom entry append failed",
+      { cause: error },
+    );
+  }
+}
+function retainComplianceResponse(context: ExtensionContext, response: AssistantMessage): void {
+  appendActiveSessionCustomEntry(
+    context,
+    COMPLIANCE_RESPONSE_ENTRY_TYPE,
+    { version: 1, response },
+    {
+      unavailable: "compliance response retention is unavailable",
+      failed: "compliance response retention failed",
+    },
+  );
+}
+function readListField(value: unknown): readonly unknown[] { return Array.isArray(value) ? value : value === undefined ? [] : [value]; }
+export function readComplianceCandidate(arguments_: unknown, usage?: Usage): ComplianceDecision {
+  if (typeof arguments_ !== "object" || arguments_ === null || Array.isArray(arguments_)) return { status: "audit-incomplete", observation: { kind: "non-object-arguments", type: arguments_ === null ? "null" : Array.isArray(arguments_) ? "array" : typeof arguments_ as ComplianceArgumentRootType }, candidate: arguments_, ...(usage === undefined ? {} : { usage }) };
+  const args = arguments_ as Record<string, unknown>; const status = args.status;
+  if (status === "pass") return { status, ...(usage === undefined ? {} : { usage }) };
+  if (status === "revise") return { status, violations: readListField(args.violations), ...(usage === undefined ? {} : { usage }) };
+  if (status === "escalate") return { status, ...(Object.hasOwn(args, "conflicts") ? { conflicts: args.conflicts } : {}), ...(Object.hasOwn(args, "decisionGate") ? { decisionGate: args.decisionGate } : {}), ...(usage === undefined ? {} : { usage }) };
+  return { status: "audit-incomplete", observation: { kind: "object-status-unreadable", status: status === undefined ? "missing" : "unknown" }, candidate: arguments_, ...(usage === undefined ? {} : { usage }) };
+}
+
+export type RunComplianceAuditOptions = {
+  tool: ReturnType<typeof createComplianceDecisionTool>;
+  systemPrompt: string;
+  /** @deprecated Fixer-lane hand-delivery only (#242 retires). Prefer omitting for zero-projection auditors. */
+  serializedInput?: string;
+  roleLabel: string;
+  invalidDecisionLabel: string;
+  runCompletion?: ComplianceCompletion;
+  context: ExtensionContext;
+  /** Exact machine-owned run binding; never sourced from AK_ROLE_RUN_DIR. */
+  runDirectory?: string | undefined;
+  signal?: AbortSignal;
+};
+
+export async function runComplianceAudit(options: RunComplianceAuditOptions): Promise<ComplianceDecision> {
+  const prompt = options.serializedInput ?? AUDITOR_DOSSIER_PROMPT;
+  const receipt = await executeAuditorChild({
+    tool: options.tool,
+    dossierTool: createAuditorDossierTool(options.runDirectory),
+    systemPrompt: options.systemPrompt,
+    prompt,
+    roleLabel: options.roleLabel,
+    context: options.context,
+    retainResponse: (response) => retainComplianceResponse(options.context, response),
+    ...(options.runCompletion === undefined ? {} : { runCompletion: options.runCompletion }),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  });
+  return readComplianceCandidate(receipt.decision, receipt.response.usage);
+}

package/src/doctor-auditor.ts

@@ -0,0 +1,53 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { auditorRunDirectory } from "./auditor-dossier-tool.ts";
+import { loadAuditorSoul } from "./auditor-soul.ts";
+import {
+  createComplianceDecisionTool,
+  runComplianceAudit,
+  type ComplianceCompletion,
+  type ComplianceDecision,
+} from "./compliance-transport.ts";
+import {
+  readDoctorAuditSubjects,
+  resolveAuditDossier,
+  toAuditIncomplete,
+} from "./dossier-resolution.ts";
+
+export const DOCTOR_AUDIT_TOOL_NAME = "ak_doctor_audit_decision";
+
+export type DoctorAuditOptions = {
+  context: ExtensionContext;
+  signal?: AbortSignal;
+};
+
+const tool = createComplianceDecisionTool(
+  DOCTOR_AUDIT_TOOL_NAME,
+  "Return whether the proposed Doctor testimony demonstrably follows the Doctor Soul and frozen evidence record from the dossier. Completed receipts are later augmented with runtime-owned cost; empty findings are valid.",
+);
+
+/**
+ * Doctor auditor: zero hand-delivered materials.
+ * Candidate testimony must already be on the parent-session books.
+ */
+export function createPiDoctorAuditor(
+  runCompletion?: ComplianceCompletion,
+): (options: DoctorAuditOptions) => Promise<ComplianceDecision> {
+  return async (options) => {
+    const dossier = resolveAuditDossier();
+    if (dossier.status === "incomplete") return toAuditIncomplete(dossier.observation);
+    const subjects = readDoctorAuditSubjects(options.context);
+    if (subjects.status === "incomplete") return toAuditIncomplete(subjects.observation);
+
+    return runComplianceAudit({
+      tool,
+      systemPrompt: await loadAuditorSoul("doctor"),
+      roleLabel: "Doctor Soul compliance audit",
+      invalidDecisionLabel: "invalid Doctor audit decision",
+      context: options.context,
+      ...(auditorRunDirectory(options.context) === undefined ? {} : { runDirectory: auditorRunDirectory(options.context) }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+      ...(runCompletion === undefined ? {} : { runCompletion }),
+    });
+  };
+}

package/src/doctor-contracts.ts

@@ -0,0 +1,166 @@
+import { Type } from "typebox";
+import { canonicalJson } from "./canonical-json.ts";
+import { openToolObjectFromUnion } from "./open-tool-schema.ts";
+
+export const DOCTOR_EVIDENCE_TOOL_NAME = "ak_doctor_evidence";
+export const DOCTOR_OUTPUT_TOOL_NAME = "ak_doctor_output";
+export const DOCTOR_OUTPUT_TOOL_DESCRIPTION = "Submit the sole final typed single-case testimony. Use completed when findings is empty or contains only non-prescriptive case observations. The runtime adds its derived case cost to the accepted receipt. Refuse only when the evidence cannot support even truthful case testimony; unavailable reusable-asset or bounded-bite evidence blocks only the corresponding asset prescription.";
+export const DOCTOR_TARGET_KINDS = ["law", "gate", "template", "station", "seat"] as const;
+export type DoctorTargetKind = typeof DOCTOR_TARGET_KINDS[number];
+export type DoctorCaseIdentity = { issueNumber: number; runsPath: string };
+export type DoctorSessionCost =
+  | { source: string; startedAt: string; endedAt: string; wallMilliseconds: number; completion: "accepted" }
+  | { source: string; startedAt?: string; endedAt?: string; wallMilliseconds?: number; completion: "incomplete"; degradationReason?: string };
+export type DoctorCount = { count: number; sources: string[] };
+export type DoctorCaseCost = {
+  invocations: DoctorCount; legs: DoctorCount; modelApiTurns: DoctorCount; outputTokens: DoctorCount; toolCalls: DoctorCount;
+  retries: DoctorCount & { evidence: "literal run-dir naming" };
+  statuses: Array<{ source: string; status: string }>;
+  commits: Array<{ source: string; commit: string }>;
+  sessions: DoctorSessionCost[];
+  outputBytes: DoctorCount & { payload: "raw JSONL bytes"; providerWireBytes: "unavailable" };
+};
+export type DoctorGuardrailAnswer = { answer: boolean; evidenceIds: string[]; explanation: string };
+export type DoctorLastRealBite =
+  | { kind: "actual"; targetKey: string; evidenceId: string }
+  | { kind: "noRealBite"; targetKey: string; eligibleEvidenceIds: string[] };
+type DoctorFindingBody = {
+  evidenceIds: string[]; disposition: "keep" | "thin" | "delete";
+  guardrails: { reproducibleFailure: DoctorGuardrailAnswer; owningSeamOrInvariant: DoctorGuardrailAnswer; deletionOrSimplificationSuffices: DoctorGuardrailAnswer };
+  prescription: { kind: "retain" | "delete" | "simplify" | "patch" | "addMechanism"; recommendation: string; necessityExplanation?: string };
+  lastRealBite: DoctorLastRealBite;
+};
+type DoctorAssetKind = DoctorTargetKind;
+export type DoctorFinding =
+  | { targetKey: string; observation: string; evidenceIds: string[] }
+  | (DoctorFindingBody & { targetKey: string; targetKind: DoctorAssetKind; assetEvidence: { targetKey: string; targetKind: DoctorAssetKind; evidenceId: string } });
+export type DoctorSubmission =
+  | { status: "completed"; case: DoctorCaseIdentity; findings: DoctorFinding[] }
+  | { status: "refused"; reason: string; missingEvidence: Array<{ need: string; targetKeys: string[] }> };
+export type DoctorOutput =
+  | { status: "completed"; case: DoctorCaseIdentity; findings: DoctorFinding[]; cost: DoctorCaseCost }
+  | Extract<DoctorSubmission, { status: "refused" }>;
+export type DoctorEvidenceEntry = { id: string; kind: "session" | "stderr"; byteLength: number; contentLength: number; sha256: string; content: string };
+export type DoctorCase = { version: 1; identity: DoctorCaseIdentity; evidence: DoctorEvidenceEntry[]; cost: DoctorCaseCost };
+
+const nonblank = Type.String({ minLength: 1, pattern: "\\S" });
+const count = Type.Object({ count: Type.Integer({ minimum: 0 }), sources: Type.Array(nonblank) }, { additionalProperties: false });
+const evidenceIds = Type.Array(nonblank, { minItems: 1 });
+const guardrail = Type.Object({ answer: Type.Boolean(), evidenceIds, explanation: nonblank }, { additionalProperties: false });
+const lastRealBite = Type.Union([
+  Type.Object({ kind: Type.Literal("actual"), targetKey: nonblank, evidenceId: nonblank }, { additionalProperties: false }),
+  Type.Object({ kind: Type.Literal("noRealBite"), targetKey: nonblank, eligibleEvidenceIds: evidenceIds }, { additionalProperties: false }),
+]);
+const assetKinds = DOCTOR_TARGET_KINDS;
+const findingBody = {
+  evidenceIds, disposition: Type.Union([Type.Literal("keep"), Type.Literal("thin"), Type.Literal("delete")]),
+  guardrails: Type.Object({ reproducibleFailure: guardrail, owningSeamOrInvariant: guardrail, deletionOrSimplificationSuffices: guardrail }, { additionalProperties: true }),
+  prescription: Type.Object({ kind: Type.Union([Type.Literal("retain"), Type.Literal("delete"), Type.Literal("simplify"), Type.Literal("patch"), Type.Literal("addMechanism")]), recommendation: nonblank, necessityExplanation: Type.Optional(nonblank) }, { additionalProperties: false }), lastRealBite,
+};
+const finding = Type.Union([
+  Type.Object({ targetKey: nonblank, observation: nonblank, evidenceIds }, { additionalProperties: false }),
+  Type.Object({ targetKey: nonblank, targetKind: Type.Union(assetKinds.map((kind) => Type.Literal(kind))), assetEvidence: Type.Object({ targetKey: nonblank, targetKind: Type.Union(assetKinds.map((kind) => Type.Literal(kind))), evidenceId: nonblank }, { additionalProperties: false }), ...findingBody }, { additionalProperties: false }),
+]);
+const caseIdentity = Type.Object({ issueNumber: Type.Integer({ minimum: 1 }), runsPath: nonblank }, { additionalProperties: false });
+const cost = Type.Object({
+  invocations: count, legs: count, modelApiTurns: count, outputTokens: count, toolCalls: count,
+  retries: Type.Object({ count: Type.Integer({ minimum: 0 }), sources: Type.Array(nonblank), evidence: Type.Literal("literal run-dir naming") }, { additionalProperties: false }),
+  statuses: Type.Array(Type.Object({ source: nonblank, status: nonblank }, { additionalProperties: false })),
+  commits: Type.Array(Type.Object({ source: nonblank, commit: nonblank }, { additionalProperties: false })),
+  sessions: Type.Array(Type.Union([
+    Type.Object({ source: nonblank, startedAt: nonblank, endedAt: nonblank, wallMilliseconds: Type.Number({ minimum: 0 }), completion: Type.Literal("accepted") }, { additionalProperties: false }),
+    Type.Object({ source: nonblank, startedAt: Type.Optional(nonblank), endedAt: Type.Optional(nonblank), wallMilliseconds: Type.Optional(Type.Number({ minimum: 0 })), completion: Type.Literal("incomplete"), degradationReason: Type.Optional(nonblank) }, { additionalProperties: false }),
+  ])),
+  outputBytes: Type.Object({ count: Type.Integer({ minimum: 0 }), sources: Type.Array(nonblank), payload: Type.Literal("raw JSONL bytes"), providerWireBytes: Type.Literal("unavailable") }, { additionalProperties: false }),
+}, { additionalProperties: false });
+const doctorSubmissionVariants = Type.Union([
+  Type.Object({
+    status: Type.Literal("completed", { description: "Truthful single-case testimony was completed; the runtime adds derived cost to the receipt." }),
+    case: Type.Unsafe({ ...caseIdentity, description: "Identity of the retained Doctor case." }),
+    findings: Type.Array(finding, { description: "May be empty or contain non-prescriptive case observations. Missing reusable-asset or bounded-bite evidence excludes only the corresponding asset prescription." }),
+  }, { additionalProperties: false, description: "Single-case testimony, without requiring any prescription or reusable finding." }),
+  Type.Object({
+    status: Type.Literal("refused", { description: "Reserved for inability to support truthful case testimony, not for an unavailable prescription axis." }),
+    reason: Type.String({ minLength: 1, description: "Reason evidence is insufficient for truthful testimony." }),
+    missingEvidence: Type.Array(Type.Object({ need: nonblank, targetKeys: Type.Array(nonblank, { minItems: 1 }) }, { additionalProperties: false }), { minItems: 1, description: "Evidence required before truthful testimony is possible." }),
+  }, { additionalProperties: false, description: "Evidence is insufficient for truthful case testimony." }),
+]);
+export const doctorSubmissionSchema = openToolObjectFromUnion(doctorSubmissionVariants);
+export const doctorOutputSchema = Type.Union([
+  Type.Object({ status: Type.Literal("completed"), case: caseIdentity, findings: Type.Array(finding), cost }, { additionalProperties: false }),
+  doctorSubmissionVariants.anyOf[1]!,
+]);
+export const doctorEvidenceReadSchema = Type.Object({ evidenceId: Type.String({ minLength: 1, description: "Identifier of the retained evidence to read." }), offset: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based byte offset at which to begin reading." })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 4096, description: "Maximum number of bytes to return." })) }, { additionalProperties: false });
+export class DoctorSubmissionContractError extends Error { override readonly name = "DoctorSubmissionContractError"; }
+function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function read(value: unknown, key: string): unknown { if (!isRecord(value)) return undefined; try { return value[key]; } catch { return undefined; } }
+export function validateDoctorSubmissionShape(value: unknown): DoctorSubmission {
+  const status = read(value, "status");
+  if (status !== "completed" && status !== "refused") throw new DoctorSubmissionContractError("Doctor submission has no recognized execution status");
+  return value as DoctorSubmission;
+}
+export function validateRecordedDoctorOutput(value: unknown): DoctorOutput {
+  const output = validateDoctorSubmissionShape(value);
+  if (read(output, "status") === "completed" && read(output, "cost") === undefined) throw new Error("Completed Doctor receipt has no runtime-owned cost testimony");
+  return output as DoctorOutput;
+}
+
+export class DoctorEvidenceStore {
+  readonly entries: Map<string, DoctorEvidenceEntry>; private readonly coverage = new Map<string, Array<[number, number]>>();
+  constructor(readonly patient: DoctorCase) { this.entries = new Map(patient.evidence.map((entry) => [entry.id, entry])); }
+  read(evidenceId: string, offset = 0, limit = 4096) { const entry = this.entries.get(evidenceId); if (!entry) throw new Error(`Evidence ID is not admitted: ${evidenceId}`); if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 4096) throw new Error("Invalid evidence pagination"); if (offset > entry.contentLength) throw new Error("Evidence offset exceeds content"); const end = Math.min(entry.contentLength, offset + limit); const ranges = [...(this.coverage.get(evidenceId) ?? []), [offset, end] as [number, number]].sort((a, b) => a[0] - b[0]); const merged: Array<[number, number]> = []; for (const range of ranges) { const prior = merged.at(-1); if (prior && range[0] <= prior[1]) prior[1] = Math.max(prior[1], range[1]); else merged.push([...range]); } this.coverage.set(evidenceId, merged); return { evidenceId, kind: entry.kind, offset, content: entry.content.slice(offset, end), nextOffset: end < entry.contentLength ? end : null, contentLength: entry.contentLength, byteLength: entry.byteLength, sha256: entry.sha256 }; }
+  hasRead(id: string) { const entry = this.entries.get(id); const ranges = this.coverage.get(id); return !!entry && ranges?.length === 1 && ranges[0]![0] === 0 && ranges[0]![1] === entry.contentLength; }
+  readRecord() { return [...this.coverage.keys()].sort().map((evidenceId) => ({ evidenceId, fullyRead: this.hasRead(evidenceId) })); }
+}
+export function validateDoctorOutput(value: unknown, patient: DoctorCase, store: DoctorEvidenceStore): DoctorSubmission {
+  const output = validateDoctorSubmissionShape(value);
+  const lawfulTargets = new Set(["case", ...patient.cost.invocations.sources]);
+  const assertTarget = (targetKey: unknown) => { if (typeof targetKey === "string" && !lawfulTargets.has(targetKey)) throw new Error(`Target key is not a lawful case target: ${targetKey}`); };
+  const readCitations = (ids: unknown, label: string) => { if (!Array.isArray(ids)) return; for (const id of ids) if (typeof id === "string" && (!store.entries.has(id) || !store.hasRead(id))) throw new Error(`${label} must cite admitted/read evidence: ${id}`); };
+  if (read(output, "status") === "refused") {
+    const missingEvidence = read(output, "missingEvidence");
+    if (Array.isArray(missingEvidence)) for (const missing of missingEvidence) {
+      const targets = read(missing, "targetKeys");
+      if (Array.isArray(targets)) for (const target of targets) assertTarget(target);
+    }
+    return output;
+  }
+  const identity = read(output, "case");
+  const issueNumber = read(identity, "issueNumber");
+  const runsPath = read(identity, "runsPath");
+  if ((issueNumber !== undefined && issueNumber !== patient.identity.issueNumber) || (runsPath !== undefined && runsPath !== patient.identity.runsPath)) throw new Error("Doctor submission case must equal the activated case identity");
+  const findings = read(output, "findings");
+  if (!Array.isArray(findings)) return output;
+  for (const finding of findings) {
+    const targetKey = read(finding, "targetKey");
+    readCitations(read(finding, "evidenceIds"), "finding");
+    const assetEvidence = read(finding, "assetEvidence");
+    if (!isRecord(assetEvidence)) { assertTarget(targetKey); continue; }
+    const assetTargetKey = read(assetEvidence, "targetKey");
+    const assetTargetKind = read(assetEvidence, "targetKind");
+    const assetEvidenceId = read(assetEvidence, "evidenceId");
+    if (typeof assetTargetKey === "string" && assetTargetKey !== targetKey) throw new Error("Typed asset evidence must establish the finding target key");
+    if (typeof assetTargetKind === "string" && assetTargetKind !== read(finding, "targetKind")) throw new Error("Typed asset evidence must establish the finding target kind");
+    if (typeof assetEvidenceId === "string") readCitations([assetEvidenceId], "asset evidence");
+    const guardrails = read(finding, "guardrails");
+    for (const key of ["reproducibleFailure", "owningSeamOrInvariant", "deletionOrSimplificationSuffices"]) readCitations(read(read(guardrails, key), "evidenceIds"), "guardrail");
+    const bite = read(finding, "lastRealBite");
+    const biteKind = read(bite, "kind");
+    if (biteKind !== "actual" && biteKind !== "noRealBite") continue;
+    if (read(bite, "targetKey") !== targetKey) throw new Error("lastRealBite target mismatch");
+    if (biteKind === "actual") {
+      const evidenceId = read(bite, "evidenceId");
+      const entry = typeof evidenceId === "string" ? store.entries.get(evidenceId) : undefined;
+      if (!entry || entry.kind !== "session" || !store.hasRead(entry.id)) throw new Error("actual bite must cite an admitted/read retained session");
+    } else {
+      const eligible = patient.evidence.map((entry) => entry.id).sort();
+      const ids = read(bite, "eligibleEvidenceIds");
+      if (Array.isArray(ids)) {
+        const claimed = ids.filter((id): id is string => typeof id === "string").sort();
+        if (canonicalJson(claimed) !== canonicalJson(eligible)) throw new Error("noRealBite must prove the complete eligible single-case evidence population");
+        readCitations(eligible, "noRealBite");
+      }
+    }
+  }
+  return output;
+}

package/src/doctor-evidence.ts

@@ -0,0 +1,47 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import { sha256Hex } from "./sha256.ts";
+import type { DoctorCase, DoctorCaseCost, DoctorCount, DoctorEvidenceEntry } from "./doctor-contracts.ts";
+import { AcceptedDetailsContractError, acceptedFacts, isTerminatingToolName, validateAcceptedDetails } from "./package-contracts/terminating-tools.ts";
+
+function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+async function discoverCaseFiles(root: string): Promise<string[]> { const found: string[] = []; async function walk(dir: string, depth: number) { for (const item of await readdir(dir, { withFileTypes: true })) { const path = resolve(dir, item.name); if (item.isDirectory()) await walk(path, depth + 1); else if (item.isFile() && (item.name.endsWith(".jsonl") || (item.name === "stderr.log" && depth === 1))) found.push(path); } } await walk(root, 0); return found.sort(); }
+function sourceList(count: number, sources: string[]) { return { count, sources: [...new Set(sources)].sort() }; }
+function accumulate(metric: DoctorCount, value: number, source: string) { metric.count += value; if (value) metric.sources.push(source); }
+function timestamp(row: Record<string, unknown>) { return typeof row.timestamp === "string" && Number.isFinite(Date.parse(row.timestamp)) ? row.timestamp : undefined; }
+function isMissingPathError(error: unknown): boolean { return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR"); }
+async function stableRunsIdentity(root: string): Promise<string> { let cursor = root; while (true) { try { const git = await stat(resolve(cursor, ".git")); if (git.isDirectory() || git.isFile()) return relative(cursor, root).split(sep).join("/"); } catch (error) { if (!isMissingPathError(error)) throw error; } const parent = dirname(cursor); if (parent === cursor) return root; cursor = parent; } }
+
+type SessionDerivation = { session: DoctorCaseCost["sessions"][number]; turns: number; calls: number; tokens: number; statuses: DoctorCaseCost["statuses"]; commits: DoctorCaseCost["commits"] };
+function deriveSession(content: string, id: string): SessionDerivation {
+  const rows: Record<string, unknown>[] = []; const degradationReasons: string[] = [];
+  for (const line of content.split("\n")) if (line.trim()) { try { const row: unknown = JSON.parse(line); if (!record(row)) { degradationReasons.push(`non-object session row in ${id}`); break; } rows.push(row); } catch (error) { if (error instanceof SyntaxError) { degradationReasons.push(`malformed JSON tail in ${id}: ${error.message}`); break; } throw error; } }
+  const started = rows.find((row) => row.type === "session"); const startedAt = started && timestamp(started); if (!startedAt) degradationReasons.push(`Pi session header is missing: ${id}`);
+  let accepted: Record<string, unknown> | undefined, observedCommit: string | undefined, turns = 0, calls = 0, tokens = 0;
+  const statuses: DoctorCaseCost["statuses"] = [], commits: DoctorCaseCost["commits"] = [];
+  for (const row of rows) {
+    const message = record(row.message) ? row.message : undefined;
+    if (message?.role === "assistant") { for (const part of Array.isArray(message.content) ? message.content : []) if (record(part) && part.type === "toolCall") calls++; if (typeof message.responseId === "string") { turns++; const usage = record(message.usage) ? message.usage : undefined; if (usage && typeof usage.output === "number") tokens += usage.output; } }
+    if (message?.role === "toolResult" && message.isError !== true && typeof message.toolName === "string" && isTerminatingToolName(message.toolName) && record(message.details)) { let details; try { details = validateAcceptedDetails(message.toolName, message.details); } catch (error) { // Contract: README.md#Doctor — non-accepted terminating receipts are expected-negative evidence and are skipped; all other validation failures propagate with their cause.
+        if (error instanceof AcceptedDetailsContractError) continue; throw error; } accepted = row; const facts = acceptedFacts(message.toolName, details); if (facts.commit && facts.commit !== observedCommit) { commits.push({ source: id, commit: facts.commit }); observedCommit = facts.commit; } statuses.length = 0; if (facts.status !== undefined) { statuses.push({ source: id, status: facts.status }); } else { statuses.push({ source: id, status: "terminating receipt has no receipt-level status" }); } }
+  }
+  const acceptedAt = accepted && timestamp(accepted); const final = acceptedAt ? accepted! : rows.at(-1); const endedAt = final && timestamp(final); const wall = startedAt && endedAt ? Date.parse(endedAt) - Date.parse(startedAt) : undefined;
+  if (wall !== undefined && wall < 0) degradationReasons.push(`non-monotonic session timestamps in ${id}`);
+  const degradationReason = degradationReasons.length ? degradationReasons.join("; ") : undefined;
+  const complete = !!acceptedAt && !degradationReason && wall !== undefined && wall >= 0;
+  const session = complete
+    ? { source: id, startedAt: startedAt!, endedAt: endedAt!, wallMilliseconds: wall!, completion: "accepted" as const }
+    : { source: id, ...(startedAt ? { startedAt } : {}), ...(endedAt ? { endedAt } : {}), ...(wall !== undefined && wall >= 0 ? { wallMilliseconds: wall } : {}), completion: "incomplete" as const, ...(degradationReason ? { degradationReason } : {}) };
+  return { session, turns, calls, tokens, statuses, commits };
+}
+
+/** Read Pi's retained session directory as the sole raw material for one case. */
+export async function loadDoctorCase(runsPath: string): Promise<DoctorCase> {
+  const root = await realpath(runsPath); const match = root.split(sep).join("/").match(/\/\.ak-roles\/books\/[^/]+\/issues\/([1-9]\d*)\/runs$/); if (!match) throw new Error("Doctor case must be an .ak-roles/books/<book>/issues/<n>/runs directory");
+  const evidence: DoctorEvidenceEntry[] = [], sessions: DoctorCaseCost["sessions"] = [], statuses: DoctorCaseCost["statuses"] = [], commits: DoctorCaseCost["commits"] = [];
+  const turns: DoctorCount = { count: 0, sources: [] }, calls: DoctorCount = { count: 0, sources: [] }, tokens: DoctorCount = { count: 0, sources: [] };
+  for (const path of await discoverCaseFiles(root)) { const id = relative(root, path).split(sep).join("/"); const bytes = await readFile(path); const content = bytes.toString("utf8"); const kind = id.endsWith(".jsonl") ? "session" : "stderr"; evidence.push({ id, kind, byteLength: bytes.byteLength, contentLength: content.length, sha256: sha256Hex(bytes), content }); if (kind === "stderr") continue; const result = deriveSession(content, id); sessions.push(result.session); statuses.push(...result.statuses); commits.push(...result.commits); accumulate(turns, result.turns, id); accumulate(calls, result.calls, id); accumulate(tokens, result.tokens, id); }
+  const runDirs = (await readdir(root, { withFileTypes: true })).filter((item) => item.isDirectory()).map((item) => item.name).sort(); const legs = evidence.filter((entry) => entry.kind === "session").map((entry) => entry.id); const retryDirs = runDirs.filter((name) => /(?:^|[-_])retry(?:[-_]|$)/i.test(name)); const rawBytes = evidence.filter((entry) => entry.kind === "session").reduce((sum, entry) => sum + entry.byteLength, 0);
+  const cost: DoctorCaseCost = { invocations: sourceList(runDirs.length, runDirs), legs: sourceList(legs.length, legs), modelApiTurns: sourceList(turns.count, turns.sources), outputTokens: sourceList(tokens.count, tokens.sources), toolCalls: sourceList(calls.count, calls.sources), retries: { ...sourceList(retryDirs.length, retryDirs), evidence: "literal run-dir naming" }, statuses, commits, sessions, outputBytes: { ...sourceList(rawBytes, legs), payload: "raw JSONL bytes", providerWireBytes: "unavailable" } };
+  return { version: 1, identity: { issueNumber: Number(match[1]), runsPath: await stableRunsIdentity(root) }, evidence, cost };
+}

package/src/doctor-role.ts

@@ -0,0 +1,18 @@
+import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { disposeComplianceDecision } from "./audit-escalation.ts";
+import { appendActiveSessionCustomEntry, type ComplianceDecision } from "./compliance-transport.ts";
+import { DOCTOR_CANDIDATE_ENTRY_TYPE } from "./dossier-resolution.ts";
+import { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_DESCRIPTION, DOCTOR_OUTPUT_TOOL_NAME, DoctorEvidenceStore, doctorEvidenceReadSchema, doctorSubmissionSchema, validateDoctorOutput, type DoctorCase } from "./doctor-contracts.ts";
+
+export { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME };
+export const DOCTOR_CASE_FLAG = { name: "ak-doctor-case", definition: { description: "Retained .ak-roles/books/<book>/issues/<n>/runs directory", type: "string" as const } } as const;
+export type DoctorRoleDependencies = { loadSoul(): Promise<string>; loadCase(path: string): Promise<DoctorCase>; auditCompliance(options: { context: ExtensionContext; signal?: AbortSignal }): Promise<ComplianceDecision> };
+function singleton(toolCallId: string, ctx: ExtensionContext) { const leaf = ctx.sessionManager.getLeafEntry(); if (leaf?.type !== "message" || leaf.message.role !== "assistant") throw new Error("Doctor output must be the sole final tool call"); const calls = leaf.message.content.filter((part) => part.type === "toolCall"); if (calls.length !== 1 || calls[0]?.id !== toolCallId || calls[0]?.name !== DOCTOR_OUTPUT_TOOL_NAME) throw new Error("Doctor output must be the sole final tool call"); }
+export function createDoctorRoleRuntime(pi: ExtensionAPI, dependencies: DoctorRoleDependencies, host: { failInfrastructure(error: unknown, ctx: ExtensionContext, toolCallId?: string): never }) {
+  let activation: { soul: string; patient: DoctorCase; store: DoctorEvidenceStore } | undefined; let registered = false; pi.registerFlag(DOCTOR_CASE_FLAG.name, DOCTOR_CASE_FLAG.definition);
+  return { async activate() { const path = pi.getFlag(DOCTOR_CASE_FLAG.name); if (typeof path !== "string" || !path.trim()) throw new Error("Doctor requires --ak-doctor-case"); const soul = (await dependencies.loadSoul()).trim(); if (!soul) throw new Error("Doctor soul is empty"); const patient = await dependencies.loadCase(path); activation = { soul, patient, store: new DoctorEvidenceStore(patient) };
+    if (!registered) { registered = true; pi.registerTool({ name: DOCTOR_EVIDENCE_TOOL_NAME, label: "Doctor Evidence", description: "Read retained Pi session bytes with bounded pagination.", parameters: doctorEvidenceReadSchema, async execute(_id, params: { evidenceId: string; offset?: number; limit?: number }) { if (!activation) throw new Error("Doctor is not activated"); const details = activation.store.read(params.evidenceId, params.offset, params.limit); return { content: [{ type: "text" as const, text: JSON.stringify(details) }], details }; } });
+      pi.registerTool({ name: DOCTOR_OUTPUT_TOOL_NAME, label: "Doctor Output", description: DOCTOR_OUTPUT_TOOL_DESCRIPTION, parameters: doctorSubmissionSchema, async execute(id, params, signal, _update, ctx): Promise<AgentToolResult<unknown>> { if (!activation) throw new Error("Doctor is not activated"); singleton(id, ctx); const testimony = validateDoctorOutput(params, activation.patient, activation.store); try { appendActiveSessionCustomEntry(ctx, DOCTOR_CANDIDATE_ENTRY_TYPE, { version: 1, testimony, readRecord: activation.store.readRecord(), patientIdentity: activation.patient.identity }, { unavailable: "doctor candidate retention is unavailable", failed: "doctor candidate retention failed" }); } catch (error) { host.failInfrastructure(error, ctx, id); } let audit: ComplianceDecision; try { audit = await dependencies.auditCompliance(signal === undefined ? { context: ctx } : { context: ctx, signal }); } catch (error) { host.failInfrastructure(error, ctx, id); } const details = testimony.status === "completed" ? { ...testimony, cost: activation.patient.cost } : testimony; return disposeComplianceDecision<AgentToolResult<unknown>>(audit, { pass: (usage) => ({ content: [{ type: "text" as const, text: "Doctor output accepted" }], details, terminate: true as const, ...(usage === undefined ? {} : { usage }) }), revise: (violations) => { throw new Error(`Doctor output violates its soul: ${violations.join("; ")}`); }, escalate: (result) => result, auditIncomplete: (result) => result }, details); } });
+      pi.on("before_agent_start", (event) => { if (!activation) throw new Error("Doctor is not activated"); const catalog = { version: activation.patient.version, identity: activation.patient.identity, admittedMetrics: { provenance: "runtime-derived from retained session bytes and sealed into the accepted receipt", cost: activation.patient.cost }, lawfulTargetKeys: ["case", ...activation.patient.cost.invocations.sources], evidence: activation.patient.evidence.map(({ id, kind, sha256, byteLength, contentLength }) => ({ id, kind, sha256, byteLength, contentLength })) }; return { systemPrompt: `${event.systemPrompt}\n\n<doctor_soul>\n${activation.soul}\n</doctor_soul>\n\n<doctor_case>\n${JSON.stringify(catalog)}\n</doctor_case>` }; }); }
+    const required = [DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME]; const names = pi.getAllTools().map((tool) => tool.name); for (const name of required) if (names.filter((item) => item === name).length !== 1) throw new Error(`Doctor required tool collision or missing: ${name}`); pi.setActiveTools(required); const active = pi.getActiveTools?.() ?? required; if (active.length !== 2 || !required.every((name) => active.includes(name))) throw new Error("Doctor active tool narrowing failed"); } };
+}

package/src/dossier-resolution.ts

@@ -0,0 +1,137 @@
+/**
+ * Unique dossier-resolution seam for 审刑院 (#233).
+ * Machine pointers only: cwd + AK_ROLE_RUN_DIR. No latest-run / mtime / global scan.
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { JUDGE_OUTPUT_TOOL_NAME as JUDGE_OUTPUT_TOOL } from "./package-contracts/judge-output.ts";
+
+export const JUDGE_OUTPUT_TOOL_NAME = JUDGE_OUTPUT_TOOL;
+export const AUDIT_RUN_DIR_ENV = "AK_ROLE_RUN_DIR" as const;
+export const REVIEWER_CANDIDATE_ENTRY_TYPE = "ak_reviewer_audit_candidate" as const;
+export const DOCTOR_CANDIDATE_ENTRY_TYPE = "ak_doctor_audit_candidate" as const;
+
+export type MissingDossierObservation = { readonly kind: "missing-dossier" };
+export type MissingSubjectObservation = {
+  readonly kind: "missing-subject";
+  readonly subject: "assignment" | "candidate-verdict" | "candidate-receipt" | "candidate-testimony" | string;
+};
+export type DossierObservation = MissingDossierObservation | MissingSubjectObservation;
+
+export type DossierOk = {
+  readonly status: "ok";
+  /** Present only when public CLI injected a validated AK_ROLE_RUN_DIR. */
+  readonly runDirectory?: string;
+};
+export type DossierIncomplete = {
+  readonly status: "incomplete";
+  readonly observation: DossierObservation;
+};
+export type DossierResolution = DossierOk | DossierIncomplete;
+
+export type SubjectOk = { readonly status: "ok" };
+export type SubjectIncomplete = {
+  readonly status: "incomplete";
+  readonly observation: MissingSubjectObservation;
+};
+export type SubjectResolution = SubjectOk | SubjectIncomplete;
+
+/**
+ * Resolve the per-run dossier pointer injected by the public CLI.
+ *
+ * Absent pointer = bare Pi internal seam (ADR 0052): audit proceeds; the model
+ * self-locates the dossier from its own fall-volume position per soul. Public CLI
+ * always injects the pointer — only then does the machine validate the path.
+ * Concurrent runs stay isolated because a present pointer is per-process.
+ */
+export function resolveAuditDossier(env: NodeJS.ProcessEnv = process.env): DossierResolution {
+  const raw = env[AUDIT_RUN_DIR_ENV];
+  // Bare Pi activation seam: no machine gate when the pointer was never injected.
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return { status: "ok" };
+  }
+  const runDirectory = resolve(raw);
+  try {
+    if (!existsSync(runDirectory) || !statSync(runDirectory).isDirectory()) {
+      return { status: "incomplete", observation: { kind: "missing-dossier" } };
+    }
+  } catch {
+    return { status: "incomplete", observation: { kind: "missing-dossier" } };
+  }
+  return { status: "ok", runDirectory };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Judge subjects must already be on the parent session books before audit starts:
+ * assignment (user message) + candidate verdict (sole judge output tool call).
+ */
+export function readJudgeAuditSubjects(context: ExtensionContext): SubjectResolution {
+  const entries = context.sessionManager.getEntries?.() ?? [];
+  let hasAssignment = false;
+  let hasCandidate = false;
+  for (const entry of entries) {
+    if (entry.type !== "message") continue;
+    const message = entry.message;
+    if (message.role === "user") {
+      const text = typeof message.content === "string"
+        ? message.content
+        : Array.isArray(message.content)
+          ? message.content.map((part) => (part.type === "text" ? part.text : "")).join("")
+          : "";
+      if (text.trim().length > 0) hasAssignment = true;
+    }
+    if (message.role === "assistant" && Array.isArray(message.content)) {
+      for (const part of message.content) {
+        if (part.type === "toolCall" && part.name === JUDGE_OUTPUT_TOOL_NAME && isRecord(part.arguments)) {
+          hasCandidate = true;
+        }
+      }
+    }
+  }
+  if (!hasAssignment) {
+    return { status: "incomplete", observation: { kind: "missing-subject", subject: "assignment" } };
+  }
+  if (!hasCandidate) {
+    return { status: "incomplete", observation: { kind: "missing-subject", subject: "candidate-verdict" } };
+  }
+  return { status: "ok" };
+}
+
+/**
+ * Reviewer candidate receipt must be recorded before audit (first-record-then-audit).
+ */
+export function readReviewerAuditSubjects(context: ExtensionContext): SubjectResolution {
+  const entries = context.sessionManager.getEntries?.() ?? [];
+  for (const entry of entries) {
+    if (entry.type === "custom" && entry.customType === REVIEWER_CANDIDATE_ENTRY_TYPE) {
+      return { status: "ok" };
+    }
+  }
+  return { status: "incomplete", observation: { kind: "missing-subject", subject: "candidate-receipt" } };
+}
+
+/**
+ * Doctor candidate testimony must be recorded before audit.
+ */
+export function readDoctorAuditSubjects(context: ExtensionContext): SubjectResolution {
+  const entries = context.sessionManager.getEntries?.() ?? [];
+  for (const entry of entries) {
+    if (entry.type === "custom" && entry.customType === DOCTOR_CANDIDATE_ENTRY_TYPE) {
+      return { status: "ok" };
+    }
+  }
+  return { status: "incomplete", observation: { kind: "missing-subject", subject: "candidate-testimony" } };
+}
+
+export function toAuditIncomplete<TObservation extends DossierObservation>(
+  observation: TObservation,
+): { status: "audit-incomplete"; observation: TObservation; candidate: undefined } {
+  return { status: "audit-incomplete", observation, candidate: undefined };
+}