@akagilnc/pi-workflow-roles 0.1.3236 → 0.1.3256

package/souls/quality-law.md

@@ -8,17 +8,21 @@
 
 取舍位次：过测试 → 显意图 → 无重复 → 最少元素。
 
+尺子锚定仓内已接受的现状：与紧邻已并入代码同款的写法，不单独判新增行为缺陷；要判就按类判全仓。
+
 ## 测试对行为负责
 
-测试从真实入口进入，沿真实行为执行，在外部可见结果上断言。每个独立行为契约保留一条最短可信的主干测试；边界和失败场景放在最低但仍能真实证明行为的层级。
+测试只保**调用输入正确**的最短确定性案：从真实入口进入，在外部可见的结构化结果上断言，秒级完成。涉真实宿主、真实 LLM、真实并发、真实网络的行为，不写测试；以真跑为证。
+
+修复的证明是**变异真跑**：装回旧逻辑，真实入口秒级报红；恢复后绿。命令与输出原文记入回执。不为证明修复造测试；拆掉的证明性测试不得换形再造。
 
-测试向 spec 负责，不向实现妥协。不得靠放松断言、删除失败路径或 mock 被测行为使测试变绿。缺陷修复应能证明修复前失败、修复后通过。
+测试向 spec 负责，不向实现妥协：不得靠放松断言、删除失败路径或 mock 被测行为使测试变绿。
 
 盯生成物一律禁止：不得对自由文本、LLM 产出内容、图片像素等任何生成产物建立机械依赖——锁措辞、锁句式、锁模板、数条数、埋哨兵、比像素，都算。契约断言只落在结构化字段上；生成物只可特征化观察，不可约束。
 
 已有测试能表达真实行为的，修改或复用，不另建平行测试。只锁定内部结构、非契约文本、重复结论、失效行为或单纯覆盖率的测试，应当删除。
 
-生产代码和测试代码都计算复杂度。新增任何机制或测试，都必须证明它提供了现有体系没有的必要价值。
+生产代码和测试代码都计算复杂度。新增任何测试，都必须证明它提供了现有体系没有的必要价值。
 
 ## 测试分级
 

package/src/collector-identity.ts

@@ -1,29 +1,36 @@
-import {
-  type GitHubIssueComment,
-  type GitHubMachineIdentity,
-  type GitHubPullRequestReaction,
-  type GitHubReview,
-  type GitHubReviewComment,
+import type {
+  GitHubMachineIdentity,
 } from "./collector-github.ts";
 import type { CollectorEvidenceRecord, HeadRelation } from "./collector-evidence.ts";
-
-export type GitHubIdentityMaterial = GitHubReview | GitHubIssueComment | GitHubReviewComment | GitHubPullRequestReaction;
+import { CorrectableSubmissionError } from "./submission-correctable-error.ts";
 
 export type CollectorMaterialRef = {
   kind: "review" | "issue_comment" | "review_comment" | "reaction";
   id: number;
-  /** Original review body, retained as uninterpreted material. */
-  body?: string;
   /** Receipt-local immutable source reference. */
   evidenceId?: string;
   headRelation?: HeadRelation | "unbound";
 };
 
+/**
+ * #641 chain①: a receipt finding is a model-classified unit (splitting stays
+ * with the collector LLM) whose source pointer resolves against the stored
+ * evidence and whose machine locator (repo/PR/comment id/url/author/kind/时间)
+ * is enriched by the runtime from the same record — never transcribed bodies.
+ */
 export type CollectorFinding = {
-  identity: GitHubMachineIdentity;
+  identity: GitHubMachineIdentity | null;
   source: CollectorMaterialRef;
-  category: "inline";
-  body: string;
+  category?: string;
+  pointer: {
+    repository: string;
+    prNumber: number;
+    commentId: number;
+    htmlUrl?: string;
+    authorLogin?: string;
+    kind: CollectorMaterialRef["kind"];
+    authoritativeTime?: string | null;
+  };
 };
 
 export type CollectorIdentityGroup = {
@@ -35,12 +42,10 @@ export type CollectorIdentityGroup = {
   materials: CollectorMaterialRef[];
 };
 
-function materialKind(material: GitHubIdentityMaterial): CollectorIdentityGroup["materials"][number]["kind"] {
-  if ("pullRequestReviewId" in material) return "review_comment";
-  if ("state" in material) return "review";
-  if ("content" in material) return "reaction";
-  return "issue_comment";
-}
+export type ExtractedCollectorIdentityGroup = CollectorIdentityGroup & {
+  attendance: true;
+  findings: CollectorFinding[];
+};
 
 function identityKey(identity: GitHubMachineIdentity | null): string {
   if (identity === null) return "unassigned";
@@ -61,60 +66,10 @@ function mergeMachineIdentity(
   return observed.userType < current.userType ? observed : current;
 }
 
-/** Group observed GitHub materials only by API machine identity fields. */
-export function groupGitHubMaterialsByIdentity(
-  materials: readonly GitHubIdentityMaterial[],
-): CollectorIdentityGroup[] {
-  const groups = new Map<string, CollectorIdentityGroup>();
-  for (const material of materials) {
-    const identity = material.machineIdentity ?? null;
-    const key = identityKey(identity);
-    let group = groups.get(key);
-    if (group === undefined) {
-      group = {
-        identity,
-        ...(material.userLogin === null ? {} : { displayLogin: material.userLogin }),
-        materials: [],
-      };
-      groups.set(key, group);
-    } else {
-      group.identity = mergeMachineIdentity(group.identity, identity);
-    }
-    const kind = materialKind(material);
-    group.materials.push({
-      kind,
-      id: material.id,
-      ...(kind === "review" && "body" in material ? { body: material.body } : {}),
-    });
-  }
-  return [...groups.values()];
-}
-
-const CODEX_USER_ID = 199175422;
-const CODERABBIT_USER_ID = 136622811;
-export type ExtractedCollectorIdentityGroup = CollectorIdentityGroup & {
-  attendance: true;
-  findings: CollectorFinding[];
-};
-
-/** Extract attendance and provider findings without using login/display text as identity. */
-export function extractGitHubIdentityGroups(materials: readonly GitHubIdentityMaterial[]): ExtractedCollectorIdentityGroup[] {
-  const groups = groupGitHubMaterialsByIdentity(materials);
-  const byKey = new Map(groups.map((group) => [identityKey(group.identity), group]));
-  for (const group of groups) {
-    group.attendance = true;
-    group.findings = [];
-  }
-  for (const material of materials) {
-    const identity = material.machineIdentity ?? null;
-    const group = byKey.get(identityKey(identity))!;
-    if (identity === null) continue;
-    const source = { kind: materialKind(material), id: material.id };
-    if (source.kind === "review_comment" && "body" in material && (identity.userId === CODEX_USER_ID || identity.userId === CODERABBIT_USER_ID)) {
-      group.findings!.push({ identity, source, category: "inline", body: material.body });
-    }
-  }
-  return groups as ExtractedCollectorIdentityGroup[];
+function headRelationFor(record: CollectorEvidenceRecord, targetHead: string): HeadRelation | "unbound" {
+  return record.commitOid === undefined || record.commitOid === null
+    ? "unbound"
+    : record.commitOid === targetHead ? "current" : "prior";
 }
 
 /** Receipt adapter consuming the typed facts retained by transport normalization. */
@@ -131,11 +86,8 @@ export function extractCollectorEvidenceIdentityGroups(
     const source: CollectorMaterialRef = {
       kind,
       id: record.githubId,
-      ...(kind === "review" && record.body !== undefined ? { body: record.body } : {}),
       evidenceId: record.evidenceId,
-      headRelation: record.commitOid === undefined || record.commitOid === null
-        ? "unbound"
-        : record.commitOid === targetHead ? "current" : "prior",
+      headRelation: headRelationFor(record, targetHead),
     };
     const key = identityKey(identity);
     let group = groups.get(key);
@@ -152,10 +104,105 @@ export function extractCollectorEvidenceIdentityGroups(
       group.identity = mergeMachineIdentity(group.identity, identity);
     }
     group.materials.push(source);
-    if (identity === null || record.body === undefined) continue;
-    if (kind === "review_comment" && (identity.userId === CODEX_USER_ID || identity.userId === CODERABBIT_USER_ID)) {
-      group.findings.push({ identity, source: { ...source }, category: "inline", body: record.body });
-    }
   }
   return [...groups.values()];
 }
+
+/**
+ * #641 chain①: pointer-open failures are model misuse, not host failures. The
+ * seat rejects them as correctable so the model can retry with a stored
+ * evidenceId — on Pi and Grok/ACP alike (第 0 条: 模型提交方式可纠正).
+ */
+export class CollectorUnknownEvidenceError extends CorrectableSubmissionError {
+  constructor(evidenceId: string) {
+    super(`未在本局已观测材料中找到 evidenceId ${evidenceId}；请用 observe 返回的指针重试。`);
+    this.name = "CollectorUnknownEvidenceError";
+  }
+}
+
+/**
+ * #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.
+ */
+export class CollectorFindingsValidationError extends CorrectableSubmissionError {
+  constructor(message: string) {
+    super(message);
+    this.name = "CollectorFindingsValidationError";
+  }
+}
+
+/**
+ * #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.
+ */
+export function enrichCollectorFindings(input: {
+  candidate: unknown;
+  records: readonly CollectorEvidenceRecord[];
+  groups: readonly ExtractedCollectorIdentityGroup[];
+  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("通进司交件参数必须为对象");
+  }
+  const rawFindings = (candidate as { findings?: unknown }).findings;
+  if (rawFindings === undefined) return;
+  if (!Array.isArray(rawFindings)) {
+    throw new CollectorFindingsValidationError("通进司 findings 必须为数组");
+  }
+  const byEvidenceId = new Map(input.records.map((record) => [record.evidenceId, record]));
+  for (const raw of rawFindings) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new CollectorFindingsValidationError("通进司 finding 必须为对象");
+    }
+    const evidenceId = (raw as { evidenceId?: unknown }).evidenceId;
+    if (typeof evidenceId !== "string" || evidenceId.length === 0) {
+      throw new CollectorFindingsValidationError("通进司 finding 缺少可解析的 evidenceId 指针");
+    }
+    const record = byEvidenceId.get(evidenceId);
+    if (record === 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 (record.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 group = input.groups.find((candidateGroup) => identityKey(candidateGroup.identity) === identityKey(identity));
+    if (group === undefined) {
+      throw new CollectorFindingsValidationError(`通进司 finding 指针证据 ${evidenceId} 无归属身份组`);
+    }
+    group.findings.push({
+      identity,
+      source: {
+        kind: record.kind,
+        id: record.githubId,
+        evidenceId: record.evidenceId,
+        headRelation: headRelationFor(record, input.targetHead),
+      },
+      ...(category === undefined ? {} : { category: category.trim() }),
+      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,
+      },
+    });
+  }
+}

package/src/collector-ledger.ts

@@ -16,6 +16,8 @@ import {
   type CollectorClock,
   type CollectorEvidenceRecord,
   type CollectorSnapshot,
+  type HeadRelation,
+  type WindowRelation,
 } from "./collector-evidence.ts";
 import {
   buildCollectorRequestBody,
@@ -26,22 +28,92 @@ import {
 import {
   collectorObserveArgsSchema,
   collectorOutputArgsSchema,
+  collectorReadArgsSchema,
   collectorRequestArgsSchema,
   collectorWaitArgsSchema,
 } from "./collector-tool-schemas.ts";
 import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.ts";
 
 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";
 export { COLLECTOR_OUTPUT_TOOL };
 
 export const COLLECTOR_OPERATIONAL_TOOLS = [
   COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
 ] as const;
 
+/**
+ * #641 chain①: observe context projects at most this many bytes of each
+ * material body; the full body stays reachable via the record pointer
+ * (evidenceId + htmlUrl) and is preserved in the volume, never unconditionally
+ * transcribed into model context or receipt.
+ */
+export const COLLECTOR_OBSERVE_BODY_HEAD_BYTES = 512;
+
+function utf8SafePrefix(text: string, maxBytes: number): string {
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+  const bytes = Buffer.from(text, "utf8");
+  let end = maxBytes;
+  while (end > 0 && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return `${bytes.subarray(0, end).toString("utf8")}…`;
+}
+
+export type ObserveEvidenceEntry = {
+  evidenceId: string;
+  kind: string;
+  authorLogin?: string | undefined;
+  state?: string | undefined;
+  body?: string | undefined;
+  commitOid?: string | null | undefined;
+  htmlUrl?: string | undefined;
+  path?: string | undefined;
+  line?: number | null | undefined;
+  side?: string | null | undefined;
+  authoritativeTime?: string | null | undefined;
+  windowRelation?: WindowRelation | undefined;
+  pullRequestReviewId?: number | null | undefined;
+};
+
+export type ObserveModelView = {
+  snapshotId: string;
+  observedAt: string;
+  completedAt: string;
+  prState: string;
+  headOid: string;
+  complete: boolean;
+  evidence: ObserveEvidenceEntry[];
+  requestAttempts: Array<{
+    attemptId: string;
+    requestId: string;
+    observedHead: string;
+    status: string;
+    marker: string;
+    recoverySnapshotId?: string | undefined;
+  }>;
+};
+
+/**
+ * #641 chain① model-context projection: identical shape to the volume view,
+ * with every material body bounded to a head preview. Full bodies remain
+ * pointer-reachable (evidenceId/htmlUrl) and stay in the ledger volume
+ * (collector-side; provider-visible observe details carry only this bounded
+ * projection), never unconditionally transcribed into model context.
+ */
+export function projectObserveContextView(modelView: ObserveModelView): ObserveModelView {
+  return {
+    ...modelView,
+    evidence: modelView.evidence.map((entry) =>
+      entry.body === undefined
+        ? entry
+        : { ...entry, body: utf8SafePrefix(entry.body, COLLECTOR_OBSERVE_BODY_HEAD_BYTES) }),
+  };
+}
+
 export type CollectorOperationalTool = (typeof COLLECTOR_OPERATIONAL_TOOLS)[number];
 
 export type CollectorRequestAttempt = {
@@ -117,7 +189,7 @@ export type CollectorLedger = {
     signal?: AbortSignal,
   ): Promise<{
     snapshot: CollectorSnapshot;
-    modelView: unknown;
+    contextView: ObserveModelView;
   }>;
 
   request(
@@ -157,6 +229,8 @@ export function collectorToolArgumentsValid(
   switch (name) {
     case COLLECTOR_OBSERVE_TOOL:
       return Value.Check(collectorObserveArgsSchema, args);
+    case COLLECTOR_READ_TOOL:
+      return Value.Check(collectorReadArgsSchema, args);
     case COLLECTOR_REQUEST_TOOL:
       return Value.Check(collectorRequestArgsSchema, args);
     case COLLECTOR_WAIT_TOOL:
@@ -566,7 +640,7 @@ export function createCollectorLedger(config: CollectorConfigState): CollectorLe
         attempts,
       });
 
-      return { snapshot, modelView };
+      return { snapshot, contextView: projectObserveContextView(modelView) };
     },
 
     async request(input, transport, clock, signal) {
@@ -780,12 +854,35 @@ export function createCollectorLedger(config: CollectorConfigState): CollectorLe
   return ledger;
 }
 
+/**
+ * #641 chain①: single authoritative evidence-record projection shared by the
+ * observe model view and the pointer-open read tool.
+ */
+export function projectEvidenceEntryView(record: CollectorEvidenceRecord): ObserveEvidenceEntry {
+  return {
+    evidenceId: record.evidenceId,
+    kind: record.kind,
+    authorLogin: record.authorLogin,
+    state: record.state,
+    body: record.body,
+    commitOid: record.commitOid,
+    htmlUrl: record.htmlUrl,
+    path: record.path,
+    // Single display fallback: current line, else originalLine.
+    line: record.line ?? record.originalLine,
+    side: record.side,
+    authoritativeTime: record.authoritativeTime,
+    windowRelation: record.windowRelation,
+    pullRequestReviewId: record.pullRequestReviewId,
+  };
+}
+
 function buildObserveModelView(input: {
   snapshot: CollectorSnapshot;
   records: readonly CollectorEvidenceRecord[];
   requesterLogin: string | undefined;
   attempts: readonly CollectorRequestAttempt[];
-}): unknown {
+}): ObserveModelView {
   const relevant = input.records;
   return {
     snapshotId: input.snapshot.snapshotId,
@@ -794,22 +891,7 @@ function buildObserveModelView(input: {
     prState: input.snapshot.prState,
     headOid: input.snapshot.headOid,
     complete: input.snapshot.complete,
-    evidence: relevant.map((record) => ({
-      evidenceId: record.evidenceId,
-      kind: record.kind,
-      authorLogin: record.authorLogin,
-      state: record.state,
-      body: record.body,
-      commitOid: record.commitOid,
-      htmlUrl: record.htmlUrl,
-      path: record.path,
-      // Single display fallback: current line, else originalLine.
-      line: record.line ?? record.originalLine,
-      side: record.side,
-      authoritativeTime: record.authoritativeTime,
-      windowRelation: record.windowRelation,
-      pullRequestReviewId: record.pullRequestReviewId,
-    })),
+    evidence: relevant.map((record): ObserveEvidenceEntry => projectEvidenceEntryView(record)),
     requestAttempts: input.attempts.map((attempt) => ({
       attemptId: attempt.attemptId,
       requestId: attempt.requestId,

package/src/collector-receipt.ts

@@ -1,11 +1,22 @@
 import { COLLECTOR_HOST } from "./collector-config.ts";
 import type { CollectorClock, CollectorEvidenceRecord, CollectorSnapshot } from "./collector-evidence.ts";
 import type { CollectorLedger, CollectorRequestAttempt } from "./collector-ledger.ts";
-import { extractCollectorEvidenceIdentityGroups, type ExtractedCollectorIdentityGroup } from "./collector-identity.ts";
-import { validateAcceptedCollectorReceipt } from "./package-contracts/collector-output.ts";
+import {
+  enrichCollectorFindings,
+  extractCollectorEvidenceIdentityGroups,
+  type ExtractedCollectorIdentityGroup,
+} from "./collector-identity.ts";
+import { validateAcceptedCollectorReceipt, type CollectorEvidenceRecord as ReceiptEvidenceRecord } from "./package-contracts/collector-output.ts";
 
 export { validateAcceptedCollectorReceipt };
 
+/**
+ * #641 chain① receipt-local evidence projection: machine identity, integrity
+ * digest and resolvable pointer fields only. Bodies/raw stay in the volume
+ * (observe details + GitHub pointer); they are never transcribed into the receipt.
+ */
+export type CollectorReceiptEvidenceRecord = ReceiptEvidenceRecord;
+
 export type CollectorReceipt = {
   host: "github.com";
   repository: string;
@@ -19,15 +30,15 @@ export type CollectorReceipt = {
   groups: ExtractedCollectorIdentityGroup[];
   requestAttempts: CollectorRequestAttempt[];
   snapshots: CollectorSnapshot[];
-  evidenceRecords: CollectorEvidenceRecord[];
+  evidenceRecords: CollectorReceiptEvidenceRecord[];
 };
 
 function fail(message: string): never { throw new Error(message); }
 
-/** Runtime output is intentionally empty: observed typed groups are the sole receipt source. */
+/** Runtime output assembles findings pointers from the model submission into the typed receipt. */
 export function buildCollectorReceipt(
   ledger: CollectorLedger,
-  _candidateRaw: unknown,
+  candidateRaw: unknown,
   clock?: CollectorClock,
 ): CollectorReceipt {
   ledger.assertNotFatal();
@@ -46,7 +57,7 @@ export function buildCollectorReceipt(
   if (finalSnapshot === undefined || !finalSnapshot.complete) fail("Collector final snapshot is incomplete");
   if (finalSnapshot.prState !== "OPEN") fail("Collector final snapshot PR state is not OPEN");
 
-  const evidenceRecords = [...ledger.allEvidence()];
+  const evidenceRecords: CollectorEvidenceRecord[] = [...ledger.allEvidence()];
   const snapshots = [...ledger.allSnapshots()];
   const evidenceIndex = new Map(evidenceRecords.map((record) => [record.evidenceId, record]));
   const snapshotIndex = new Map(snapshots.map((snapshot) => [snapshot.snapshotId, snapshot]));
@@ -59,6 +70,16 @@ 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({
+    candidate: candidateRaw,
+    records: evidenceRecords,
+    groups,
+    targetHead: finalSnapshot.headOid,
+    repository: ledger.config.repository.canonical,
+    prNumber: ledger.config.prNumber,
+  });
   for (const group of groups) {
     if (group.attendance !== true) fail("Collector group lacks attendance");
     for (const material of group.materials) {
@@ -82,6 +103,20 @@ export function buildCollectorReceipt(
     groups,
     requestAttempts: [...ledger.requestAttempts()],
     snapshots,
-    evidenceRecords,
+    evidenceRecords: evidenceRecords.map(toReceiptEvidenceRecord),
+  };
+}
+
+function toReceiptEvidenceRecord(record: CollectorEvidenceRecord): CollectorReceiptEvidenceRecord {
+  return {
+    evidenceId: record.evidenceId,
+    kind: record.kind,
+    versionId: record.versionId,
+    contentDigest: record.contentDigest,
+    firstObservedAt: record.firstObservedAt,
+    ...(record.githubId === undefined ? {} : { githubId: record.githubId }),
+    ...(record.authorLogin === undefined ? {} : { authorLogin: record.authorLogin }),
+    ...(record.htmlUrl === undefined ? {} : { htmlUrl: record.htmlUrl }),
+    ...(record.authoritativeTime === undefined ? {} : { authoritativeTime: record.authoritativeTime }),
   };
 }