@akagilnc/pi-workflow-roles 0.1.3758 → 0.1.3783

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

@@ -0,0 +1,424 @@
+/**
+ * Generic headless CLI RoleTurnHost (#645 / #752).
+ * One process per turn: spawn → read result envelope/exit → structured_output / MCP → envelope.
+ * No reads of the host's private home; session id is package-owned binding only.
+ * No permanent stdout/stderr/init probe copies — sitian + binding are the dossier.
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { RoleTurnHost, RoleTurnKnownFailure, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
+import {
+  renderAcpSystemPromptOverride,
+  type AcpPreparedTurn,
+  type AcpSessionIdentityAuthority,
+} from "../acp-host/role-turn-host.ts";
+import {
+  headlessMcpConfigDocument,
+  headlessTurnArgs,
+  type HeadlessHostDescription,
+} from "./description.ts";
+
+export type HeadlessRoleTurnHostConfig = Readonly<{
+  description: HeadlessHostDescription;
+  sessionIdentity: AcpSessionIdentityAuthority;
+  binary: string;
+  prepare(request: RoleTurnRequest): Promise<AcpPreparedTurn>;
+  env?: NodeJS.ProcessEnv;
+}>;
+
+function failure(
+  cause: "activation" | "session" | "output" | "provider",
+  name: string,
+  code: string,
+  details?: Readonly<Record<string, unknown>>,
+  diagnostic?: string,
+): RoleTurnResult {
+  return {
+    code: null,
+    stderr: "",
+    timedOut: false,
+    knownFailure: {
+      cause,
+      identity: { name, code },
+      ...(diagnostic === undefined ? {} : { diagnostic }),
+      ...(details === undefined ? {} : { details }),
+    },
+  };
+}
+
+/** One headless CLI result envelope (`--output-format json`). */
+export type HeadlessCliResult = Readonly<{
+  session_id?: string;
+  is_error?: boolean;
+  subtype?: string;
+  result?: unknown;
+  structured_output?: unknown;
+  errors?: unknown;
+  permission_denials?: unknown;
+  [key: string]: unknown;
+}>;
+
+/**
+ * Parse host stdout into the result envelope.
+ * Production uses `--output-format json` (one document). stream-json last-result
+ * parsing remains so a misconfigured description still yields a typed miss rather
+ * than a silent empty parse — not a permanent probe path.
+ */
+export function parseHeadlessCliStdout(stdout: string): HeadlessCliResult | undefined {
+  const trimmed = stdout.trim();
+  if (trimmed === "") return undefined;
+  try {
+    const single = JSON.parse(trimmed) as unknown;
+    if (typeof single === "object" && single !== null && !Array.isArray(single)) {
+      const record = single as HeadlessCliResult & { type?: unknown };
+      if (record.type === undefined || record.type === "result" || record.structured_output !== undefined) {
+        return record;
+      }
+    }
+  } catch {
+    // fall through
+  }
+  // Defensive: if a description still requests stream-json, keep only the result line.
+  let last: HeadlessCliResult | undefined;
+  for (const line of trimmed.split("\n")) {
+    const text = line.trim();
+    if (text === "") continue;
+    try {
+      const value = JSON.parse(text) as unknown;
+      if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+      const record = value as HeadlessCliResult & { type?: unknown };
+      if (record.type === "result" || record.structured_output !== undefined) {
+        last = record;
+      }
+    } catch {
+      // skip non-JSON noise lines
+    }
+  }
+  return last;
+}
+
+/** Bound stderr retained only for failure diagnostics (not a dossier copy). */
+const STDERR_DIAGNOSTIC_CAP = 16 * 1024;
+
+function clipDiagnostic(text: string): string {
+  if (text.length <= STDERR_DIAGNOSTIC_CAP) return text;
+  return `${text.slice(0, STDERR_DIAGNOSTIC_CAP)}\n…[stderr clipped]`;
+}
+
+function spawnHeadlessTurn(options: {
+  readonly binary: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}): Promise<{ code: number | null; stdout: string; stderr: string; timedOut: boolean }> {
+  return new Promise((resolve, reject) => {
+    if (options.signal?.aborted) {
+      reject(Object.assign(new Error("headless host aborted"), { code: "host-aborted" }));
+      return;
+    }
+    const child = spawn(options.binary, [...options.args], {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let timer: NodeJS.Timeout | undefined;
+    const settle = (code: number | null): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      resolve({ code, stdout, stderr, timedOut });
+    };
+    const onAbort = (): void => {
+      child.kill("SIGTERM");
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      reject(Object.assign(new Error("headless host aborted"), { code: "host-aborted" }));
+    };
+    child.stdout.setEncoding("utf8").on("data", (chunk: string) => { stdout += chunk; });
+    child.stderr.setEncoding("utf8").on("data", (chunk: string) => {
+      // Cap retained stderr: diagnostics only, not an unbounded transcript face.
+      if (stderr.length < STDERR_DIAGNOSTIC_CAP) {
+        stderr = clipDiagnostic(stderr + chunk);
+      }
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      reject(error);
+    });
+    child.on("close", (code) => settle(code));
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+      }, options.timeoutMs);
+    }
+  });
+}
+
+function cleanupErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * If dispose/cleanup failed: success becomes typed failure; existing failure keeps
+ * its primary cause and records the cleanup error in details (failure-honesty).
+ */
+function withCleanupFailure(outcome: RoleTurnResult, cleanupError: unknown): RoleTurnResult {
+  const message = cleanupErrorMessage(cleanupError);
+  if (outcome.knownFailure === undefined) {
+    return failure(
+      "session",
+      "HeadlessDisposeFailure",
+      "dispose-failed",
+      { cleanupError: message },
+      message,
+    );
+  }
+  return {
+    ...outcome,
+    knownFailure: {
+      ...outcome.knownFailure,
+      details: {
+        ...(outcome.knownFailure.details ?? {}),
+        cleanupError: message,
+      },
+    },
+  };
+}
+
+/**
+ * Main-session headless adapter. prepare() is the shared envelope boundary;
+ * this module owns only CLI spawn / parse / session-id bind / resume loop.
+ */
+export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig): RoleTurnHost {
+  let serial = Promise.resolve();
+  return {
+    executeTurn(request) {
+      const execution = serial.then(async (): Promise<RoleTurnResult> => {
+        const prepared = await config.prepare(request);
+        const systemPrompt = renderAcpSystemPromptOverride(prepared.systemPrompt);
+        let outcome: RoleTurnResult = failure("session", "HeadlessNoOutcome", "no-outcome");
+        try {
+          // Same-host resume reuses the bound native session id via --resume.
+          let sessionId = await config.sessionIdentity.load(request.principal);
+          let sessionKind: "new" | "resume" =
+            request.continuation.kind === "resume" && sessionId !== undefined && sessionId !== ""
+              ? "resume"
+              : "new";
+          if (sessionKind === "new") {
+            sessionId = randomUUID();
+            await config.sessionIdentity.bind(request.principal, sessionId);
+          }
+
+          // Cross-host handoff: prior-native paths ride the user prompt (DK-7).
+          const priorNativePaths =
+            request.continuation.kind === "resume"
+              ? request.hostTransition?.priorNativePaths
+              : undefined;
+          let prompt =
+            priorNativePaths !== undefined && priorNativePaths.length > 0
+              ? `${prepared.prompt}\n${priorNativePaths.join("\n")}`
+              : prepared.prompt;
+
+          const abortSignal =
+            request.signal === undefined
+              ? prepared.abortSignal
+              : prepared.abortSignal === undefined
+                ? request.signal
+                : AbortSignal.any([prepared.abortSignal, request.signal]);
+
+          // config.env is the production authority for package-root / host child env
+          // (see createProductionHeadlessRoleTurnHost). Do not re-override keys from
+          // process.env after the spread — that erased AK_PACKAGE_ROOT.
+          const env: NodeJS.ProcessEnv = {
+            ...process.env,
+            ...(config.env ?? {}),
+          };
+
+          // Materialize system prompt + MCP config once per prepare (stable across
+          // correctable retries). Paths live under the run directory we already own.
+          // Envelope always projects the AK MCP relay row; no empty-server branch.
+          const systemPromptPath = join(request.runDirectory, "headless-system-prompt.txt");
+          await writeFile(systemPromptPath, systemPrompt, "utf8");
+          const mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
+          await writeFile(
+            mcpConfigPath,
+            `${JSON.stringify(headlessMcpConfigDocument(prepared.mcpServers), null, 2)}\n`,
+            "utf8",
+          );
+
+          // No round cap on content review (#750); this bound is only for
+          // correctable mechanical resubmit (non-sole etc.), matching ACP's 8.
+          for (let attempt = 0; attempt < 8; attempt += 1) {
+            if (abortSignal?.aborted) {
+              const closure = await prepared.closeRound();
+              if ("failure" in closure) {
+                outcome = { code: null, stderr: "", timedOut: false, knownFailure: closure.failure };
+                break;
+              }
+              outcome = failure("session", "HostAborted", "host-aborted", { sessionId });
+              break;
+            }
+
+            const args = headlessTurnArgs({
+              description: config.description,
+              prompt,
+              systemPromptPath,
+              jsonSchema: prepared.jsonSchema,
+              mcpConfigPath,
+              ...(request.model?.model !== undefined ? { model: request.model.model } : {}),
+              ...(request.model?.thinking !== undefined ? { effort: request.model.thinking } : {}),
+              session: sessionKind === "new"
+                ? { kind: "new", id: sessionId! }
+                : { kind: "resume", id: sessionId! },
+            });
+
+            let spawned: { code: number | null; stdout: string; stderr: string; timedOut: boolean };
+            try {
+              spawned = await spawnHeadlessTurn({
+                binary: config.binary,
+                args,
+                cwd: request.cwd,
+                env,
+                ...(abortSignal === undefined ? {} : { signal: abortSignal }),
+                ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+              });
+            } catch (error) {
+              if (
+                typeof error === "object"
+                && error !== null
+                && (error as { code?: unknown }).code === "host-aborted"
+              ) {
+                const closure = await prepared.closeRound();
+                if ("failure" in closure) {
+                  outcome = { code: null, stderr: "", timedOut: false, knownFailure: closure.failure };
+                  break;
+                }
+                outcome = failure("session", "HostAborted", "host-aborted", { sessionId });
+                break;
+              }
+              const message = error instanceof Error ? error.message : String(error);
+              outcome = failure("activation", "HeadlessSpawnFailure", "spawn-failed", {
+                diagnostic: message,
+                binary: config.binary,
+              }, message);
+              break;
+            }
+
+            if (spawned.timedOut) {
+              outcome = {
+                code: spawned.code,
+                stderr: spawned.stderr,
+                timedOut: true,
+                knownFailure: {
+                  cause: "timeout",
+                  identity: { name: "HeadlessTimeout", code: "timeout" },
+                  details: { sessionId },
+                },
+              };
+              break;
+            }
+
+            const envelope = parseHeadlessCliStdout(spawned.stdout);
+            if (envelope === undefined) {
+              outcome = {
+                code: spawned.code,
+                stderr: spawned.stderr,
+                timedOut: false,
+                knownFailure: {
+                  cause: "output",
+                  identity: { name: "HeadlessEmptyOutput", code: "empty-stdout" },
+                  diagnostic: clipDiagnostic(spawned.stderr.trim() || "headless CLI produced no parseable result"),
+                  details: { sessionId, exitCode: spawned.code },
+                },
+              };
+              break;
+            }
+
+            // Bind the host-reported session id (authoritative for --resume).
+            if (typeof envelope.session_id === "string" && envelope.session_id !== "") {
+              sessionId = envelope.session_id;
+              await config.sessionIdentity.bind(request.principal, sessionId);
+            }
+
+            if (envelope.is_error === true || (typeof envelope.subtype === "string" && envelope.subtype.startsWith("error_"))) {
+              const errorCode =
+                typeof envelope.subtype === "string" && envelope.subtype.startsWith("error_")
+                  ? envelope.subtype
+                  : envelope.is_error === true
+                    ? "is_error"
+                    : "cli-error";
+              const diagnostic = typeof envelope.result === "string"
+                ? envelope.result
+                : Array.isArray(envelope.errors)
+                  ? envelope.errors.map(String).join("\n")
+                  : clipDiagnostic(spawned.stderr.trim() || "headless CLI reported is_error");
+              outcome = {
+                code: spawned.code,
+                stderr: spawned.stderr,
+                timedOut: false,
+                knownFailure: {
+                  cause: "output",
+                  identity: { name: "HeadlessCliError", code: errorCode },
+                  diagnostic,
+                  details: {
+                    sessionId,
+                    subtype: envelope.subtype,
+                    errors: envelope.errors,
+                    exitCode: spawned.code,
+                  },
+                },
+              };
+              break;
+            }
+
+            // Schema channel: host-native structured_output is the terminating receipt
+            // (#750). Intermediate tools may have already run via MCP during the process.
+            if (envelope.structured_output !== undefined) {
+              await prepared.ingestStructuredOutput(envelope.structured_output);
+            }
+            const closure = await prepared.closeRound();
+            if (closure.accepted) {
+              outcome = { code: 0, stderr: "", timedOut: false };
+              break;
+            }
+            if ("failure" in closure) {
+              outcome = { code: null, stderr: spawned.stderr, timedOut: false, knownFailure: closure.failure };
+              break;
+            }
+            // Correctable rejection → resume same session with plain resubmit prompt.
+            prompt = `The prior terminal submission was rejected (${closure.retry.code}). Resubmit it as the sole terminal structured output (or the sole terminating tool call). Rejected call ids: ${closure.retry.toolCallIds.join(", ") || "none"}.`;
+            sessionKind = "resume";
+            if (attempt === 7) {
+              outcome = failure("output", "HeadlessRoundLimit", "round-retry-limit", { sessionId });
+            }
+          }
+        } finally {
+          try {
+            await prepared.dispose?.();
+          } catch (cleanupError) {
+            outcome = withCleanupFailure(outcome, cleanupError);
+          }
+        }
+        return outcome;
+      });
+      serial = execution.then(() => undefined, () => undefined);
+      return execution;
+    },
+  };
+}

package/src/host-contracts.ts

@@ -103,7 +103,8 @@ export type RoleTurnActivation =
   | {
       readonly role: "collector";
       readonly repo: string;
-      readonly pr: string;
+      /** Bound PR when known at admission; omit when role will bind from materials. */
+      readonly pr?: string;
       readonly requestManifestPath?: string;
     }
   | { readonly role: "doctor"; readonly casePath: string }

package/src/host-descriptions.ts

@@ -1,10 +1,13 @@
 /**
- * Packaged host description table (#729 / #731).
- * Key = seat-table `host` value; the row is the generic ACP factory's input.
+ * Packaged host description tables (#729 / #731 / #645).
+ * Key = seat-table `host` value.
+ * - ACP family rows feed the generic ACP factory.
+ * - Headless CLI family rows feed the generic headless factory (#645; #646 codex next).
  * pi is the in-process default, not a row.
- * Unregistered names fail closed (#510); this table does not fallback.
+ * Unregistered names fail closed (#510); these tables do not fallback.
  */
 import type { AcpHostDescription } from "./acp-host/description.ts";
+import type { HeadlessHostDescription } from "./headless-host/description.ts";
 
 /** Grok CLI reads vendor-private compat surfaces unless each is disabled by name. */
 const PRIVATE_COMPAT_ENV = Object.fromEntries(
@@ -15,6 +18,8 @@ const PRIVATE_COMPAT_ENV = Object.fromEntries(
 
 export const DEFAULT_ROLE_TURN_HOST = "pi" as const;
 
+export type HostFamily = "acp" | "headless";
+
 export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = Object.freeze({
   /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
   "grok-build": Object.freeze({
@@ -60,17 +65,59 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
   }),
 });
 
+/**
+ * Headless CLI family (#645). Claude is the first row; codex (#646) adds another.
+ * fixedArgs: print mode, isolation without `--bare` (OAuth stays), full permissions.
+ * `--setting-sources` empty = load no user/project/local CLAUDE.md/hooks/skills
+ * (role envelope is delivered via `--system-prompt` wholesale replace).
+ * `--strict-mcp-config` with no `--mcp-config` drops operator MCP + claude.ai connectors.
+ */
+export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDescription>> = Object.freeze({
+  "claude": Object.freeze({
+    binaryFromHome: Object.freeze([".local", "bin", "claude"]),
+    sessionBindingFile: "claude-headless-session.json",
+    fixedArgs: Object.freeze([
+      // One result envelope (not stream-json): typed receipt only; no event-stream copy.
+      "--output-format", "json",
+      "--permission-mode", "bypassPermissions",
+      // Empty sources: no user/project/local operator surface (envelope owns materials).
+      "--setting-sources", "",
+      // With adapter-supplied --mcp-config only (AK relay); drops operator + claude.ai MCP.
+      "--strict-mcp-config",
+    ]),
+    promptFlag: "-p",
+    modelFlag: "--model",
+    effortFlag: "--effort",
+    // File path keeps large role envelopes off ARG_MAX.
+    systemPromptFlag: "--system-prompt-file",
+    jsonSchemaFlag: "--json-schema",
+    mcpConfigFlag: "--mcp-config",
+    sessionIdFlag: "--session-id",
+    resumeFlag: "--resume",
+  }),
+});
+
 export function lookupHostDescription(host: string): AcpHostDescription | undefined {
   return Object.hasOwn(HOST_DESCRIPTIONS, host) ? HOST_DESCRIPTIONS[host] : undefined;
 }
 
+export function lookupHeadlessHostDescription(host: string): HeadlessHostDescription | undefined {
+  return Object.hasOwn(HEADLESS_HOST_DESCRIPTIONS, host) ? HEADLESS_HOST_DESCRIPTIONS[host] : undefined;
+}
+
+export function lookupHostFamily(host: string): HostFamily | undefined {
+  if (lookupHostDescription(host) !== undefined) return "acp";
+  if (lookupHeadlessHostDescription(host) !== undefined) return "headless";
+  return undefined;
+}
+
 export function packagedExternalHostNames(): readonly string[] {
-  return Object.keys(HOST_DESCRIPTIONS);
+  return [...Object.keys(HOST_DESCRIPTIONS), ...Object.keys(HEADLESS_HOST_DESCRIPTIONS)];
 }
 
-/** Legal persistent/invocation host: default pi, or a table key. */
+/** Legal persistent/invocation host: default pi, or a table key (any family). */
 export function assertRegisteredHostName(host: string): string {
-  if (host === DEFAULT_ROLE_TURN_HOST || lookupHostDescription(host) !== undefined) {
+  if (host === DEFAULT_ROLE_TURN_HOST || lookupHostFamily(host) !== undefined) {
     return host;
   }
   throw new Error(`unregistered host: ${host}`);

package/src/package-contracts/collector-output.ts

@@ -59,10 +59,29 @@ export type CollectorEvidenceRecord = {
   authoritativeTime?: string | null;
 };
 
+/**
+ * #676 C: sole structured projection-fact type (builder + package leaf).
+ * Builder always emits the full object; package leaf keeps it optional so old
+ * volumes without the field stay readable — missing is unknown, never defaulted.
+ */
+export type CollectorSubmissionProjection = {
+  findingsSource: "absent" | "array" | "unreadable";
+  findingsProjectedCount: number;
+  findingsUnprojected: boolean;
+  unfinishedReasonsSource: "absent" | "array" | "unreadable";
+  unfinishedReasonsProjectedCount: number;
+  unfinishedReasonsUnprojected: boolean;
+};
+
 export type CollectorReceipt = {
   host: "github.com";
   repository: string;
   prNumber: number;
+  /**
+   * Final observed PR state; non-OPEN still delivers materials (#676 D6).
+   * Absent/unreadable on old volumes is unknown — never defaulted to OPEN.
+   */
+  prState?: string;
   manifestDigest: string;
   activationTime: string;
   deadlineTime: string;
@@ -70,6 +89,13 @@ export type CollectorReceipt = {
   finalSnapshotId: string;
   targetHead: string;
   groups: CollectorIdentityGroup[];
+  unfinishedReasons?: string[];
+  /**
+   * Distinguishes readable-empty from unprojected original submission content (#676 C).
+   * Package leaf may carry a partial projection when some sibling keys are unreadable —
+   * missing keys stay absent (never defaulted false/0/OPEN).
+   */
+  submissionProjection?: Partial<CollectorSubmissionProjection>;
   requestAttempts: CollectorRequestAttempt[];
   snapshots: CollectorSnapshot[];
   evidenceRecords: CollectorEvidenceRecord[];
@@ -97,10 +123,18 @@ export function validateAcceptedCollectorReceipt(value: unknown): CollectorRecei
     materials: records(safeGet(group, "materials")),
     findings: records(safeGet(group, "findings")),
   }));
+  const unfinishedRaw = safeGet(value, "unfinishedReasons");
+  const unfinishedReasons = strings(unfinishedRaw);
+  // #676 C: project readable submissionProjection fields independently — do not
+  // drop the whole block when one sibling key is the wrong type (left-拾遗1).
+  const submissionProjection = projectSubmissionProjection(safeGet(value, "submissionProjection"));
+  const prStateRaw = safeGet(value, "prState");
+  const prState = typeof prStateRaw === "string" ? prStateRaw : undefined;
   return {
     host: safeGet(value, "host") as "github.com",
     repository: safeGet(value, "repository") as string,
     prNumber: safeGet(value, "prNumber") as number,
+    ...(prState === undefined ? {} : { prState }),
     manifestDigest: safeGet(value, "manifestDigest") as string,
     activationTime: safeGet(value, "activationTime") as string,
     deadlineTime: safeGet(value, "deadlineTime") as string,
@@ -108,6 +142,8 @@ export function validateAcceptedCollectorReceipt(value: unknown): CollectorRecei
     finalSnapshotId: safeGet(value, "finalSnapshotId") as string,
     targetHead: safeGet(value, "targetHead") as string,
     groups,
+    ...(unfinishedReasons.length > 0 ? { unfinishedReasons } : {}),
+    ...(submissionProjection === undefined ? {} : { submissionProjection }),
     requestAttempts: records(safeGet(value, "requestAttempts")) as unknown as CollectorRequestAttempt[],
     snapshots: records(safeGet(value, "snapshots")).map((snapshot) => ({
       snapshotId: safeGet(snapshot, "snapshotId"), observedAt: safeGet(snapshot, "observedAt"), completedAt: safeGet(snapshot, "completedAt"), completedMono: safeGet(snapshot, "completedMono"), host: safeGet(snapshot, "host"), repository: safeGet(snapshot, "repository"), prNumber: safeGet(snapshot, "prNumber"), prState: safeGet(snapshot, "prState"), headOid: safeGet(snapshot, "headOid"), complete: safeGet(snapshot, "complete"), evidenceIds: strings(safeGet(snapshot, "evidenceIds")), pageDiagnostics: records(safeGet(snapshot, "pageDiagnostics")), normalizedByteLength: safeGet(snapshot, "normalizedByteLength"),
@@ -115,3 +151,39 @@ export function validateAcceptedCollectorReceipt(value: unknown): CollectorRecei
     evidenceRecords: records(safeGet(value, "evidenceRecords")).map((record) => ({ evidenceId: safeGet(record, "evidenceId"), kind: safeGet(record, "kind"), versionId: safeGet(record, "versionId"), contentDigest: safeGet(record, "contentDigest"), firstObservedAt: safeGet(record, "firstObservedAt"), githubId: safeGet(record, "githubId"), authorLogin: safeGet(record, "authorLogin"), htmlUrl: safeGet(record, "htmlUrl"), authoritativeTime: safeGet(record, "authoritativeTime") } as CollectorEvidenceRecord)),
   };
 }
+
+/** Readable projection facts only; omit keys that are the wrong type — never fabricate defaults. */
+function projectSubmissionProjection(
+  raw: unknown,
+): Partial<CollectorSubmissionProjection> | undefined {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const p = raw as Record<string, unknown>;
+  const out: Partial<CollectorSubmissionProjection> = {};
+  if (
+    p["findingsSource"] === "absent" ||
+    p["findingsSource"] === "array" ||
+    p["findingsSource"] === "unreadable"
+  ) {
+    out.findingsSource = p["findingsSource"];
+  }
+  if (typeof p["findingsProjectedCount"] === "number") {
+    out.findingsProjectedCount = p["findingsProjectedCount"];
+  }
+  if (typeof p["findingsUnprojected"] === "boolean") {
+    out.findingsUnprojected = p["findingsUnprojected"];
+  }
+  if (
+    p["unfinishedReasonsSource"] === "absent" ||
+    p["unfinishedReasonsSource"] === "array" ||
+    p["unfinishedReasonsSource"] === "unreadable"
+  ) {
+    out.unfinishedReasonsSource = p["unfinishedReasonsSource"];
+  }
+  if (typeof p["unfinishedReasonsProjectedCount"] === "number") {
+    out.unfinishedReasonsProjectedCount = p["unfinishedReasonsProjectedCount"];
+  }
+  if (typeof p["unfinishedReasonsUnprojected"] === "boolean") {
+    out.unfinishedReasonsUnprojected = p["unfinishedReasonsUnprojected"];
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}

package/src/package-contracts/terminating-infrastructure.ts

@@ -18,21 +18,32 @@ export const INFRASTRUCTURE_FAILURE_DECLARATION_KEY =
   "infrastructureFailure" as const;
 export const INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY = "diagnostic" as const;
 
-/** Shared typed declaration fragment: `infrastructureFailure.diagnostic` = non-empty string. */
+/**
+ * Shared declaration fragment for model guidance (#541 / #676 C / ADR 0057).
+ * Nested field declarations + descriptions only — host must not pure-shape-reject
+ * the envelope (第 0 条). Runtime `failOnInfrastructureFailureDeclaration` still
+ * recognizes a real non-empty diagnostic string as the failure declaration.
+ * No required/minLength/type host gates on the declaration fragment.
+ */
+const infrastructureFailureNested = Type.Object(
+  {
+    [INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY]: Type.Unknown({
+      description:
+        "非空基础设施失败诊断字符串。无失败时必须省略整个 infrastructureFailure。形状指引，非 schema 闸。",
+    }),
+  },
+  {
+    additionalProperties: true,
+    description:
+      "基础设施真实失败声明（如需）。规范形：{ diagnostic: 非空诊断字符串 }；无失败时必须省略。形状指引，非 schema 闸。",
+  },
+);
+// Open nested required so host cannot pure-shape-reject the declaration fragment.
+(infrastructureFailureNested as unknown as { required: string[] }).required = [];
+
 const infrastructureFailureDeclarationSchema = Type.Object(
   {
-    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]: Type.Object(
-      {
-        [INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY]: Type.String({
-          minLength: 1,
-          description: "非空基础设施失败诊断",
-        }),
-      },
-      {
-        additionalProperties: true,
-        description: "基础设施失败声明",
-      },
-    ),
+    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]: infrastructureFailureNested,
   },
   { additionalProperties: true },
 );