@akagilnc/pi-workflow-roles 0.1.3758 → 0.1.3783

package/src/collector-identity.ts

@@ -2,8 +2,11 @@ import type {
   GitHubMachineIdentity,
 } from "./collector-github.ts";
 import type { CollectorEvidenceRecord, HeadRelation } from "./collector-evidence.ts";
+import type { CollectorSubmissionProjection } from "./package-contracts/collector-output.ts";
 import { CorrectableSubmissionError } from "./submission-correctable-error.ts";
 
+export type { CollectorSubmissionProjection };
+
 export type CollectorMaterialRef = {
   kind: "review" | "issue_comment" | "review_comment" | "reaction";
   id: number;
@@ -21,7 +24,10 @@ export type CollectorMaterialRef = {
 export type CollectorFinding = {
   identity: GitHubMachineIdentity | null;
   source: CollectorMaterialRef;
+  /** Short classification label; not the finding summary. */
   category?: string;
+  /** Finding summary for the caller; not a body transcription. */
+  summary?: string;
   pointer: {
     repository: string;
     prNumber: number;
@@ -30,6 +36,8 @@ export type CollectorFinding = {
     authorLogin?: string;
     kind: CollectorMaterialRef["kind"];
     authoritativeTime?: string | null;
+    /** Corresponding commit when the evidence carries one. */
+    commitOid?: string | null;
   };
 };
 
@@ -121,9 +129,9 @@ export class CollectorUnknownEvidenceError extends CorrectableSubmissionError {
 }
 
 /**
- * #641 chain①: any malformed findings submission is a model misuse the model
- * can correct and resubmit — a branded correctable rejection on every supported
- * engine, never a round infrastructure failure.
+ * Evidence-binding failure for a finding pointer that resolves to the wrong kind
+ * of stored record, lacks a GitHub locator, or has no identity group — not a
+ * free-shape gate on the submission envelope.
  */
 export class CollectorFindingsValidationError extends CorrectableSubmissionError {
   constructor(message: string) {
@@ -133,11 +141,45 @@ export class CollectorFindingsValidationError extends CorrectableSubmissionError
 }
 
 /**
- * #641 chain①: turn model-submitted finding pointer refs into receipt findings.
- * Each pointer must resolve to a stored text-bearing evidence record; the
- * machine locator is enriched from the same record so receipt and volume agree
- * (指针可解析、开卷相符) by construction. Throws branded correctable
- * (non-fatal, model-visible) errors for unresolvable or mis-typed findings.
+ * #676 D6: non-OPEN targets keep collected materials and must not fire new review
+ * requests. Bounce the request as correctable so the seat can still seal output.
+ */
+export class CollectorNonOpenRequestError extends CorrectableSubmissionError {
+  constructor(prState: string) {
+    super(`通进司请求要求 OPEN 状态的 PR 快照；当前为 ${prState}，不再触发新评审，请直接交回已有材料`);
+    this.name = "CollectorNonOpenRequestError";
+  }
+}
+
+function candidateRecord(candidate: unknown): Record<string, unknown> | undefined {
+  if (candidate === undefined || candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+    return undefined;
+  }
+  return candidate as Record<string, unknown>;
+}
+
+/** Canonical top-level keys the collector output projection understands. */
+const COLLECTOR_OUTPUT_CANONICAL_KEYS = new Set([
+  "findings",
+  "unfinishedReasons",
+  "infrastructureFailure",
+]);
+
+/** Non-canonical own keys mean content was present but not under a projectable key. */
+function hasNonCanonicalOwnKeys(record: Record<string, unknown>): boolean {
+  for (const key of Object.keys(record)) {
+    if (!COLLECTOR_OUTPUT_CANONICAL_KEYS.has(key)) return true;
+  }
+  return false;
+}
+
+/**
+ * #641 chain① / #676: turn model-submitted finding pointer refs into receipt findings.
+ * Binds resolvable evidence references only — no pure shape rejection of the
+ * candidate envelope. Unknown refs, wrong kinds, missing GitHub locator, and
+ * missing identity group stay as binding failures. Unreadable findings content
+ * is not washed into "zero findings": projection facts record the gap so
+ * downstream can open the session 正本 (第 0 条 / #676 C).
  */
 export function enrichCollectorFindings(input: {
   candidate: unknown;
@@ -146,63 +188,129 @@ export function enrichCollectorFindings(input: {
   targetHead: string;
   repository: string;
   prNumber: number;
-}): void {
-  const candidate = input.candidate;
-  if (candidate === undefined || candidate === null) return;
-  if (typeof candidate !== "object" || Array.isArray(candidate)) {
-    throw new CollectorFindingsValidationError("通进司交件参数必须为对象");
+}): {
+  findingsSource: CollectorSubmissionProjection["findingsSource"];
+  findingsProjectedCount: number;
+  findingsUnprojected: boolean;
+} {
+  // Candidate present but not a record — content existed, none projected (#676 C).
+  if (input.candidate !== undefined && input.candidate !== null && candidateRecord(input.candidate) === undefined) {
+    return { findingsSource: "unreadable", findingsProjectedCount: 0, findingsUnprojected: true };
+  }
+  const record = candidateRecord(input.candidate);
+  if (record === undefined) {
+    return { findingsSource: "absent", findingsProjectedCount: 0, findingsUnprojected: false };
   }
-  const rawFindings = (candidate as { findings?: unknown }).findings;
-  if (rawFindings === undefined) return;
+  if (!Object.hasOwn(record, "findings")) {
+    // Non-canonical top-level content is not "absent" — record the projection gap (#676 C).
+    if (hasNonCanonicalOwnKeys(record)) {
+      return { findingsSource: "unreadable", findingsProjectedCount: 0, findingsUnprojected: true };
+    }
+    return { findingsSource: "absent", findingsProjectedCount: 0, findingsUnprojected: false };
+  }
+  const rawFindings = record["findings"];
   if (!Array.isArray(rawFindings)) {
-    throw new CollectorFindingsValidationError("通进司 findings 必须为数组");
+    // Key present but not an array — content exists, none projected. No shape bounce.
+    return { findingsSource: "unreadable", findingsProjectedCount: 0, findingsUnprojected: true };
   }
-  const byEvidenceId = new Map(input.records.map((record) => [record.evidenceId, record]));
+
+  const byEvidenceId = new Map(input.records.map((evidence) => [evidence.evidenceId, evidence]));
+  let projected = 0;
+  let unprojected = false;
   for (const raw of rawFindings) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-      throw new CollectorFindingsValidationError("通进司 finding 必须为对象");
+      unprojected = true;
+      continue;
     }
-    const evidenceId = (raw as { evidenceId?: unknown }).evidenceId;
+    const item = raw as Record<string, unknown>;
+    const evidenceId = item.evidenceId;
     if (typeof evidenceId !== "string" || evidenceId.length === 0) {
-      throw new CollectorFindingsValidationError("通进司 finding 缺少可解析的 evidenceId 指针");
+      // Present item without a bindable pointer — keep gap fact, do not fabricate.
+      unprojected = true;
+      continue;
     }
-    const record = byEvidenceId.get(evidenceId);
-    if (record === undefined) {
+    const evidence = byEvidenceId.get(evidenceId);
+    if (evidence === undefined) {
       throw new CollectorUnknownEvidenceError(evidenceId);
     }
-    if (record.kind !== "review" && record.kind !== "issue_comment" && record.kind !== "review_comment") {
-      throw new CollectorFindingsValidationError(`通进司 finding 指针指向不可承 finding 的证据种类 ${record.kind}`);
+    if (evidence.kind !== "review" && evidence.kind !== "issue_comment" && evidence.kind !== "review_comment") {
+      throw new CollectorFindingsValidationError(`通进司 finding 指针指向不可承 finding 的证据种类 ${evidence.kind}`);
     }
-    if (record.githubId === undefined) {
+    if (evidence.githubId === undefined) {
       throw new CollectorFindingsValidationError(`通进司 finding 指针证据 ${evidenceId} 缺少 GitHub id`);
     }
-    const category = (raw as { category?: unknown }).category;
-    if (category !== undefined && (typeof category !== "string" || category.trim().length === 0)) {
-      throw new CollectorFindingsValidationError("通进司 finding category 必须为非空字符串");
-    }
-    const identity = record.machineIdentity ?? null;
+    const identity = evidence.machineIdentity ?? null;
     const group = input.groups.find((candidateGroup) => identityKey(candidateGroup.identity) === identityKey(identity));
     if (group === undefined) {
       throw new CollectorFindingsValidationError(`通进司 finding 指针证据 ${evidenceId} 无归属身份组`);
     }
+    // Bound finding keeps pointer; non-string category/summary are unprojected field gaps
+    // (pointer success ≠ full content projection) — #676 C / 3939511832.
+    const category = item.category;
+    const summary = item.summary;
+    if (Object.hasOwn(item, "category") && typeof category !== "string") unprojected = true;
+    if (Object.hasOwn(item, "summary") && typeof summary !== "string") unprojected = true;
     group.findings.push({
       identity,
       source: {
-        kind: record.kind,
-        id: record.githubId,
-        evidenceId: record.evidenceId,
-        headRelation: headRelationFor(record, input.targetHead),
+        kind: evidence.kind,
+        id: evidence.githubId,
+        evidenceId: evidence.evidenceId,
+        headRelation: headRelationFor(evidence, input.targetHead),
       },
-      ...(category === undefined ? {} : { category: category.trim() }),
+      ...(typeof category === "string" ? { category } : {}),
+      ...(typeof summary === "string" ? { summary } : {}),
       pointer: {
         repository: input.repository,
         prNumber: input.prNumber,
-        commentId: record.githubId,
-        ...(record.htmlUrl === undefined ? {} : { htmlUrl: record.htmlUrl }),
-        ...(record.authorLogin === undefined ? {} : { authorLogin: record.authorLogin }),
-        kind: record.kind,
-        authoritativeTime: record.authoritativeTime ?? null,
+        commentId: evidence.githubId,
+        ...(evidence.htmlUrl === undefined ? {} : { htmlUrl: evidence.htmlUrl }),
+        ...(evidence.authorLogin === undefined ? {} : { authorLogin: evidence.authorLogin }),
+        kind: evidence.kind,
+        authoritativeTime: evidence.authoritativeTime ?? null,
+        ...(evidence.commitOid === undefined ? {} : { commitOid: evidence.commitOid }),
       },
     });
+    projected += 1;
+  }
+  return {
+    findingsSource: "array",
+    findingsProjectedCount: projected,
+    findingsUnprojected: unprojected,
+  };
+}
+
+/**
+ * #676 D6/C: optional unfinished reasons from the model submission.
+ * Project readable strings; record when original content could not fully project
+ * (do not wash unreadable unfinishedReasons into "none").
+ */
+export function extractCollectorUnfinishedReasons(candidate: unknown): {
+  reasons: string[] | undefined;
+  source: CollectorSubmissionProjection["unfinishedReasonsSource"];
+  unprojected: boolean;
+} {
+  if (candidate !== undefined && candidate !== null && candidateRecord(candidate) === undefined) {
+    return { reasons: undefined, source: "unreadable", unprojected: true };
+  }
+  const record = candidateRecord(candidate);
+  if (record === undefined) {
+    return { reasons: undefined, source: "absent", unprojected: false };
   }
+  if (!Object.hasOwn(record, "unfinishedReasons")) {
+    // unfinishedReasons absent is fine when only findings (or nothing) present.
+    // Non-canonical keys alone are recorded on the findings projection path.
+    return { reasons: undefined, source: "absent", unprojected: false };
+  }
+  const raw = record["unfinishedReasons"];
+  if (!Array.isArray(raw)) {
+    return { reasons: undefined, source: "unreadable", unprojected: true };
+  }
+  const reasons = raw.filter((item): item is string => typeof item === "string");
+  const unprojected = reasons.length !== raw.length;
+  return {
+    reasons: reasons.length > 0 ? reasons : undefined,
+    source: "array",
+    unprojected,
+  };
 }

package/src/collector-ledger.ts

@@ -25,6 +25,7 @@ import {
   type GitHubPageDiagnostics,
   type GitHubPullRequest,
 } from "./collector-github.ts";
+import { CollectorNonOpenRequestError } from "./collector-identity.ts";
 import {
   collectorObserveArgsSchema,
   collectorOutputArgsSchema,
@@ -38,9 +39,12 @@ export const COLLECTOR_OBSERVE_TOOL = "ak_collector_observe";
 export const COLLECTOR_READ_TOOL = "ak_collector_read";
 export const COLLECTOR_REQUEST_TOOL = "ak_collector_request";
 export const COLLECTOR_WAIT_TOOL = "ak_collector_wait";
+/** #676 A: role-decided target bind — business tool, ledger-booked. */
+export const COLLECTOR_BIND_TARGET_TOOL = "ak_collector_bind_target";
 export { COLLECTOR_OUTPUT_TOOL };
 
 export const COLLECTOR_OPERATIONAL_TOOLS = [
+  COLLECTOR_BIND_TARGET_TOOL,
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
@@ -157,7 +161,8 @@ export type CollectorTransportFailure = {
 
 export type CollectorConfigState = {
   repository: CollectorRepository;
-  prNumber: number;
+  /** Bound PR target; undefined until explicit flag, admission bind, or role bind-target tool. */
+  prNumber: number | undefined;
   manifest: CollectorManifest;
 };
 
@@ -195,6 +200,8 @@ export type CollectorLedger = {
   assertNotFatal(): void;
   recordActivation(clock: CollectorClock): void;
   recordOutputCandidate(): void;
+  /** #676 A: role-decided unique PR bind (business fact on the ledger). */
+  bindTarget(prNumber: number): void;
   beginOperational(toolName: string, toolCallId: string): void;
   completeOperational(toolCallId: string): void;
   noteCutoffObserved(): void;
@@ -326,6 +333,15 @@ export function createCollectorLedger(
   const prIdentity = (pr: GitHubPullRequest): string =>
     `${pr.state}|${pr.headOid}|${pr.updatedAt ?? ""}`;
 
+  const requireBoundPr = (): number => {
+    if (config.prNumber === undefined) {
+      throw new Error(
+        "Collector PR target is unbound; call ak_collector_bind_target with the role-decided issue/PR or pass --pr",
+      );
+    }
+    return config.prNumber;
+  };
+
   const fetchObserveSurfaces = async (
     transport: CollectorGitHubTransport,
     observedAt: string,
@@ -333,7 +349,7 @@ export function createCollectorLedger(
   ) => {
     const owner = config.repository.owner;
     const repo = config.repository.repo;
-    const prNumber = config.prNumber;
+    const prNumber = requireBoundPr();
     const signalOpt = signal === undefined ? {} : { signal };
     const user = await transport.getAuthenticatedUser(signalOpt);
     const prInitial = await transport.getPullRequest({
@@ -653,6 +669,26 @@ export function createCollectorLedger(
       outputCandidate = true;
     },
 
+    bindTarget(prNumber) {
+      assertNotFatal();
+      if (outputCandidate || pendingOutputCallId !== undefined) {
+        throw new Error("通进司已产出输出候选，本局不再受理目标绑定");
+      }
+      if (!Number.isSafeInteger(prNumber) || prNumber < 1) {
+        throw new Error("Collector bind target requires a positive safe-integer PR number");
+      }
+      if (config.prNumber !== undefined && config.prNumber !== prNumber) {
+        throw new Error(
+          `Collector target already bound to PR ${config.prNumber}; cannot rebind to ${prNumber}`,
+        );
+      }
+      config.prNumber = prNumber;
+      appendJournal("ak-collector-target-bound", {
+        prNumber,
+        repository: config.repository.canonical,
+      });
+    },
+
     beginOperational(toolName, toolCallId) {
       assertNotFatal();
       if (
@@ -833,7 +869,7 @@ export function createCollectorLedger(
         completedMono,
         host: "github.com",
         repository: config.repository.canonical,
-        prNumber: config.prNumber,
+        prNumber: requireBoundPr(),
         prState: pr.state,
         headOid: pr.headOid,
         complete: true,
@@ -875,10 +911,6 @@ export function createCollectorLedger(
       if (activationTime === undefined || deadlineTime === undefined) {
         throw latchFatal("通进司请求需要激活");
       }
-      if (pastCutoff(clock)) {
-        finalObservationRequired = true;
-        throw latchFatal("通进司请求不在资格截止前");
-      }
       if (ledger.unresolvedTransportFailure) {
         throw latchFatal("通进司请求时存在未恢复的传输失败");
       }
@@ -896,7 +928,12 @@ export function createCollectorLedger(
         throw new Error("通进司请求要求最新完整快照");
       }
       if (snapshot.prState !== "OPEN") {
-        throw latchFatal("通进司请求要求 OPEN 状态的 PR 快照");
+        // #676 D6: non-OPEN keeps materials; bounce before cutoff fatal so post-deadline materials still seal.
+        throw new CollectorNonOpenRequestError(snapshot.prState);
+      }
+      if (pastCutoff(clock)) {
+        finalObservationRequired = true;
+        throw latchFatal("通进司请求不在资格截止前");
       }
 
       const { body, marker } = buildCollectorRequestBody({
@@ -918,9 +955,10 @@ export function createCollectorLedger(
         );
       }
 
+      const boundPr = requireBoundPr();
       const attemptKey = [
         config.repository.canonical,
-        String(config.prNumber),
+        String(boundPr),
         snapshot.headOid,
         request.id,
       ].join("|");
@@ -951,7 +989,7 @@ export function createCollectorLedger(
       const result = await transport.createIssueComment({
         owner: config.repository.owner,
         repo: config.repository.repo,
-        prNumber: config.prNumber,
+        prNumber: boundPr,
         body,
         ...(signal === undefined ? {} : { signal }),
       });

package/src/collector-receipt.ts

@@ -4,11 +4,18 @@ import type { CollectorLedger, CollectorRequestAttempt } from "./collector-ledge
 import {
   enrichCollectorFindings,
   extractCollectorEvidenceIdentityGroups,
+  extractCollectorUnfinishedReasons,
   type ExtractedCollectorIdentityGroup,
 } from "./collector-identity.ts";
-import { validateAcceptedCollectorReceipt, type CollectorEvidenceRecord as ReceiptEvidenceRecord } from "./package-contracts/collector-output.ts";
+import {
+  validateAcceptedCollectorReceipt,
+  type CollectorEvidenceRecord as ReceiptEvidenceRecord,
+  type CollectorReceipt as PackageCollectorReceipt,
+  type CollectorSubmissionProjection,
+} from "./package-contracts/collector-output.ts";
 
 export { validateAcceptedCollectorReceipt };
+export type { CollectorSubmissionProjection };
 
 /**
  * #641 chain① receipt-local evidence projection: machine identity, integrity
@@ -17,17 +24,15 @@ export { validateAcceptedCollectorReceipt };
  */
 export type CollectorReceiptEvidenceRecord = ReceiptEvidenceRecord;
 
-export type CollectorReceipt = {
-  host: "github.com";
-  repository: string;
-  prNumber: number;
-  manifestDigest: string;
-  activationTime: string;
-  deadlineTime: string;
-  finalObservationTime: string;
-  finalSnapshotId: string;
-  targetHead: string;
+/**
+ * #676 C: single authority for receipt shape is package-contracts/collector-output.
+ * Production builder always emits the full projection object and concrete prState;
+ * package leaf keeps those optional so old volumes stay readable.
+ */
+export type CollectorReceipt = PackageCollectorReceipt & {
+  prState: string;
   groups: ExtractedCollectorIdentityGroup[];
+  submissionProjection: CollectorSubmissionProjection;
   requestAttempts: CollectorRequestAttempt[];
   snapshots: CollectorSnapshot[];
   evidenceRecords: CollectorReceiptEvidenceRecord[];
@@ -45,6 +50,9 @@ export function buildCollectorReceipt(
   if (ledger.unresolvedTransportFailure) fail("Collector cannot output while a transport failure is unrecovered");
   if (ledger.latestCompleteSnapshotId === undefined) fail("Collector output requires a complete final snapshot");
   if (ledger.activationTime === undefined || ledger.deadlineTime === undefined) fail("Collector output requires activation timeline");
+  if (ledger.config.prNumber === undefined) {
+    fail("Collector output requires a bound PR target; call ak_collector_bind_target first or pass --pr");
+  }
 
   if (clock !== undefined) ledger.assertOutputObservationLaw(clock);
   else if (ledger.observedGeneration !== ledger.mutationGeneration ||
@@ -54,7 +62,7 @@ export function buildCollectorReceipt(
 
   const finalSnapshot = ledger.getSnapshot(ledger.latestCompleteSnapshotId);
   if (finalSnapshot === undefined || !finalSnapshot.complete) fail("Collector final snapshot is incomplete");
-  if (finalSnapshot.prState !== "OPEN") fail("Collector final snapshot PR state is not OPEN");
+  // #676 D6: closed/merged still deliver collected materials; status is a fact on the receipt.
 
   const evidenceRecords: CollectorEvidenceRecord[] = [...ledger.allEvidence()];
   const snapshots = [...ledger.allSnapshots()];
@@ -71,7 +79,7 @@ export function buildCollectorReceipt(
   const groups = extractCollectorEvidenceIdentityGroups(evidenceRecords, finalSnapshot.headOid);
   // #641 chain①: the collector LLM submits findings as pointer refs; the runtime
   // enriches each with the machine locator from the same stored record.
-  enrichCollectorFindings({
+  const findingsProjection = enrichCollectorFindings({
     candidate: candidateRaw,
     records: evidenceRecords,
     groups,
@@ -80,7 +88,6 @@ export function buildCollectorReceipt(
     prNumber: ledger.config.prNumber,
   });
   for (const group of groups) {
-    if (group.attendance !== true) fail("Collector group lacks attendance");
     for (const material of group.materials) {
       if (material.evidenceId === undefined || !evidenceIndex.has(material.evidenceId)) fail("Collector material lacks a receipt-local evidence ref");
     }
@@ -88,11 +95,21 @@ export function buildCollectorReceipt(
       if (finding.source.evidenceId === undefined || !evidenceIndex.has(finding.source.evidenceId)) fail("Collector finding lacks a receipt-local evidence ref");
     }
   }
+  const unfinished = extractCollectorUnfinishedReasons(candidateRaw);
+  const submissionProjection: CollectorSubmissionProjection = {
+    findingsSource: findingsProjection.findingsSource,
+    findingsProjectedCount: findingsProjection.findingsProjectedCount,
+    findingsUnprojected: findingsProjection.findingsUnprojected,
+    unfinishedReasonsSource: unfinished.source,
+    unfinishedReasonsProjectedCount: unfinished.reasons?.length ?? 0,
+    unfinishedReasonsUnprojected: unfinished.unprojected,
+  };
 
   return {
     host: COLLECTOR_HOST,
     repository: ledger.config.repository.canonical,
     prNumber: ledger.config.prNumber,
+    prState: finalSnapshot.prState,
     manifestDigest: ledger.config.manifest.digest,
     activationTime: ledger.activationTime.toISOString(),
     deadlineTime: ledger.deadlineTime.toISOString(),
@@ -100,6 +117,8 @@ export function buildCollectorReceipt(
     finalSnapshotId: finalSnapshot.snapshotId,
     targetHead: finalSnapshot.headOid,
     groups,
+    ...(unfinished.reasons === undefined ? {} : { unfinishedReasons: unfinished.reasons }),
+    submissionProjection,
     requestAttempts: [...ledger.requestAttempts()],
     snapshots,
     evidenceRecords: evidenceRecords.map(toReceiptEvidenceRecord),