@akagilnc/pi-workflow-roles 0.1.5241 → 0.1.5252

package/src/collector-handbook.ts

@@ -1,194 +0,0 @@
-/**
- * Collector bot handbook — opaque working memory under the book topology.
- * Runtime stores and delivers UTF-8 text only; never parses free text into
- * code state rules (parent #673 D3 / #677).
- *
- * Placement reuses the machine ledger home (ADR 0048) when the admitted
- * session already sits under books/<bookKey>/ — no parallel persistence frame.
- */
-import { readFile } from "node:fs/promises";
-import { join, sep } from "node:path";
-
-import { writeFileAtomically } from "./atomic-write.ts";
-import {
-  activationBookDirectory,
-  assertLedgerFileInsideHome,
-  ensureRealDirectoryTree,
-  resolveActivationLedgerHomeForPath,
-} from "./activation-ledger-topology.ts";
-import { COLLECTOR_HANDBOOK_MAX_BYTES } from "./collector-tool-schemas.ts";
-
-export type CollectorHandbookScope = "general" | "repo";
-
-export type CollectorHandbookRead = {
-  readonly general: string;
-  readonly repo: string;
-  readonly generalSource: "book" | "seed" | "empty";
-  readonly repoSource: "book" | "empty";
-  readonly generalPath: string;
-  readonly repoPath: string;
-};
-
-export type CollectorHandbookWriteResult = {
-  readonly scope: CollectorHandbookScope;
-  readonly path: string;
-  readonly byteLength: number;
-};
-
-export type CollectorHandbookStore = {
-  readonly root: string;
-  readonly repositoryCanonical: string;
-  read(): Promise<CollectorHandbookRead>;
-  write(scope: CollectorHandbookScope, body: string): Promise<CollectorHandbookWriteResult>;
-};
-
-export type CollectorHandbookPlacement = {
-  readonly ledgerHome: string;
-  readonly bookKey: string;
-  readonly root: string;
-};
-
-/**
- * Derive handbook root from an admitted session/run path under
- * `.ak-roles/books/<bookKey>/...`. Fails closed when topology is absent.
- */
-export function resolveCollectorHandbookRoot(sessionPath: string): CollectorHandbookPlacement {
-  if (typeof sessionPath !== "string" || sessionPath.trim().length === 0) {
-    throw new Error("通进司手册要求非空 session 路径，且位于 books/<bookKey>/");
-  }
-  // Platform path segments only — never rewrite non-separator characters (POSIX `\\` is literal).
-  const segments = sessionPath.split(sep);
-  let bookKey: string | undefined;
-  for (let i = 0; i + 3 < segments.length; i += 1) {
-    if (segments[i] === ".ak-roles" && segments[i + 1] === "books") {
-      const candidate = segments[i + 2]!;
-      // Require a following segment so bookKey is a true path component under books/.
-      if (candidate.length > 0) {
-        bookKey = candidate;
-        break;
-      }
-    }
-  }
-  if (bookKey === undefined) {
-    throw new Error(
-      `通进司手册要求 session 位于 books/<bookKey>/；收到 ${sessionPath}`,
-    );
-  }
-  if (bookKey === "." || bookKey === "..") {
-    throw new Error(`通进司手册拒绝不安全 bookKey ${JSON.stringify(bookKey)}`);
-  }
-  const ledgerHome = resolveActivationLedgerHomeForPath(sessionPath);
-  const root = join(activationBookDirectory(ledgerHome, bookKey), "collector-handbook");
-  return { ledgerHome, bookKey, root };
-}
-
-/** Flat repo file name under handbook/repos/ — avoids nested owner/repo dirs. */
-function collectorHandbookRepoFileName(repositoryCanonical: string): string {
-  if (!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(repositoryCanonical)) {
-    throw new Error(
-      `通进司手册仓库文件要求规范 owner/repo，收到 ${JSON.stringify(repositoryCanonical)}`,
-    );
-  }
-  return `${repositoryCanonical.replaceAll("/", "__")}.md`;
-}
-
-export function createCollectorHandbookStore(input: {
-  readonly ledgerHome: string;
-  readonly handbookRoot: string;
-  readonly repositoryCanonical: string;
-  readonly seedGeneral?: string;
-}): CollectorHandbookStore {
-  const generalPath = join(input.handbookRoot, "general.md");
-  const repoDir = join(input.handbookRoot, "repos");
-  const repoPath = join(repoDir, collectorHandbookRepoFileName(input.repositoryCanonical));
-
-  /**
-   * ADR 0038: confine at the real read seam. Parent dirs must be physical under
-   * ledger home; the leaf must not be a pre-existing symlink (even in-home).
-   */
-  /** Sole UTF-8 budget seam — write and read share COLLECTOR_HANDBOOK_MAX_BYTES. */
-  const assertHandbookBudget = (body: string, label: string): number => {
-    const byteLength = Buffer.byteLength(body, "utf8");
-    if (byteLength > COLLECTOR_HANDBOOK_MAX_BYTES) {
-      throw new Error(
-        `通进司手册${label} UTF-8 至多 ${COLLECTOR_HANDBOOK_MAX_BYTES} 字节，收到 ${byteLength}`,
-      );
-    }
-    return byteLength;
-  };
-
-  const readOptional = async (path: string, parentDir: string): Promise<string | undefined> => {
-    ensureRealDirectoryTree(input.ledgerHome, parentDir);
-    assertLedgerFileInsideHome(path, input.ledgerHome);
-    try {
-      const body = await readFile(path, "utf8");
-      assertHandbookBudget(body, "正文");
-      return body;
-    } catch (error) {
-      if (isNotFound(error)) return undefined;
-      throw error;
-    }
-  };
-
-  return {
-    root: input.handbookRoot,
-    repositoryCanonical: input.repositoryCanonical,
-    async read() {
-      const bookGeneral = await readOptional(generalPath, input.handbookRoot);
-      const bookRepo = await readOptional(repoPath, repoDir);
-      if (bookGeneral !== undefined) {
-        return {
-          general: bookGeneral,
-          repo: bookRepo ?? "",
-          generalSource: "book",
-          repoSource: bookRepo === undefined ? "empty" : "book",
-          generalPath,
-          repoPath,
-        };
-      }
-      const seed = input.seedGeneral;
-      if (typeof seed === "string" && seed.length > 0) {
-        assertHandbookBudget(seed, "正文");
-        return {
-          general: seed,
-          repo: bookRepo ?? "",
-          generalSource: "seed",
-          repoSource: bookRepo === undefined ? "empty" : "book",
-          generalPath,
-          repoPath,
-        };
-      }
-      return {
-        general: "",
-        repo: bookRepo ?? "",
-        generalSource: "empty",
-        repoSource: bookRepo === undefined ? "empty" : "book",
-        generalPath,
-        repoPath,
-      };
-    },
-    async write(scope, body) {
-      // body string shape = collectorHandbookWriteArgsSchema; byte budget is business (UTF-8).
-      const byteLength = assertHandbookBudget(body, "正文");
-      ensureRealDirectoryTree(input.ledgerHome, input.handbookRoot);
-      const path = scope === "general" ? generalPath : repoPath;
-      if (scope === "repo") {
-        ensureRealDirectoryTree(input.ledgerHome, repoDir);
-      }
-      assertLedgerFileInsideHome(path, input.ledgerHome);
-      await writeFileAtomically(path, body);
-      return {
-        scope,
-        path,
-        byteLength,
-      };
-    },
-  };
-}
-
-function isNotFound(error: unknown): boolean {
-  return typeof error === "object"
-    && error !== null
-    && "code" in error
-    && (error as { code?: unknown }).code === "ENOENT";
-}

package/src/collector-identity.ts

@@ -1,151 +0,0 @@
-import type {
-  GitHubMachineIdentity,
-} from "./collector-github.ts";
-import type { CollectorEvidenceRecord, HeadRelation } from "./collector-evidence.ts";
-import { CorrectableSubmissionError } from "./submission-correctable-error.ts";
-
-export type CollectorMaterialRef = {
-  kind: "review" | "issue_comment" | "review_comment" | "reaction";
-  id: number;
-  /** 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 | 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;
-    commentId: number;
-    htmlUrl?: string;
-    authorLogin?: string;
-    kind: CollectorMaterialRef["kind"];
-    authoritativeTime?: string | null;
-    /** Corresponding commit when the evidence carries one. */
-    commitOid?: string | null;
-  };
-};
-
-export type CollectorIdentityGroup = {
-  identity: GitHubMachineIdentity | null;
-  /** Human-readable metadata only; never participates in grouping. */
-  displayLogin?: string;
-  attendance?: true;
-  findings?: CollectorFinding[];
-  materials: CollectorMaterialRef[];
-};
-
-export type ExtractedCollectorIdentityGroup = CollectorIdentityGroup & {
-  attendance: true;
-  findings: CollectorFinding[];
-};
-
-function identityKey(identity: GitHubMachineIdentity | null): string {
-  if (identity === null) return "unassigned";
-  // GitHub omits App metadata on some surfaces (notably review comments).
-  // The stable user ID is the grouping identity; richer observed structure is
-  // merged below and must not split one actor across transport surfaces.
-  return String(identity.userId);
-}
-
-function mergeMachineIdentity(
-  current: GitHubMachineIdentity | null,
-  observed: GitHubMachineIdentity | null,
-): GitHubMachineIdentity | null {
-  if (current === null) return observed;
-  if (observed === null) return current;
-  if (current.appId === undefined && observed.appId !== undefined) return observed;
-  if (current.appId !== undefined && observed.appId === undefined) return current;
-  return observed.userType < current.userType ? observed : current;
-}
-
-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. */
-export function extractCollectorEvidenceIdentityGroups(
-  records: readonly CollectorEvidenceRecord[],
-  targetHead: string,
-): ExtractedCollectorIdentityGroup[] {
-  const groups = new Map<string, ExtractedCollectorIdentityGroup>();
-  for (const record of records) {
-    if (record.kind !== "review" && record.kind !== "issue_comment" && record.kind !== "review_comment" && record.kind !== "reaction") continue;
-    if (record.githubId === undefined) continue;
-    const identity = record.machineIdentity ?? null;
-    const kind = record.kind;
-    const source: CollectorMaterialRef = {
-      kind,
-      id: record.githubId,
-      evidenceId: record.evidenceId,
-      headRelation: headRelationFor(record, targetHead),
-    };
-    const key = identityKey(identity);
-    let group = groups.get(key);
-    if (group === undefined) {
-      group = {
-        identity,
-        ...(record.authorLogin === undefined ? {} : { displayLogin: record.authorLogin }),
-        attendance: true,
-        findings: [],
-        materials: [],
-      };
-      groups.set(key, group);
-    } else {
-      group.identity = mergeMachineIdentity(group.identity, identity);
-    }
-    group.materials.push(source);
-  }
-  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";
-  }
-}
-
-/**
- * #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";
-  }
-}
-
-/** #678: wait window not open or already ended — bounce without latching fatal so materials still seal. */
-export class CollectorWaitWindowClosedError extends CorrectableSubmissionError {
-  constructor(action: "request" | "wait" | "wait-before-open") {
-    super(
-      action === "request"
-        ? "通进司请求不在资格截止前"
-        : action === "wait-before-open"
-          ? "通进司等待需要先在工作步骤开启等待窗（新建 PR 用创建成功时刻；已有 PR 在触发阶段结束后开启）"
-          : "通进司等待不在资格截止前",
-    );
-    this.name = "CollectorWaitWindowClosedError";
-  }
-}