@akagilnc/pi-workflow-roles 0.1.3648 → 0.1.3652

package/dist/activation-ledger-session.js

@@ -0,0 +1,105 @@
+import { lstatSync, realpathSync, statSync, writeFileSync, } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { errnoCode, errorText, } from "./activation-ledger-topology.js";
+/**
+ * Typed missing durable session principal. Callers discriminate with instanceof/code;
+ * never by parsing message prose. Original filesystem causes are retained.
+ */
+export class ActivationSessionFileMissingError extends Error {
+    code = "AK_ACTIVATION_SESSION_FILE_MISSING";
+    path;
+    constructor(path, options) {
+        super(`Workflow role activation durable session file does not exist: ${path}`, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "ActivationSessionFileMissingError";
+        this.path = path;
+    }
+}
+function materializeDeferredSessionFile(sessionManager, resolvedFile) {
+    const header = sessionManager.getHeader?.();
+    if (header === null || header === undefined || header.type !== "session") {
+        throw new ActivationSessionFileMissingError(resolvedFile);
+    }
+    // Activation does not own record placement (ADR 0065 / #221). Parent directory is the
+    // SessionManager principal's own dir — write the header in place; do not pull ledgerHome
+    // containment or ensureRealDirectoryTree back onto this admission path.
+    try {
+        writeFileSync(resolvedFile, `${JSON.stringify(header)}\n`, { flag: "wx" });
+    }
+    catch (error) {
+        if (errnoCode(error) !== "EEXIST") {
+            throw new Error(`Workflow role activation failed to materialize durable session file (${resolvedFile}): ${errorText(error)}`, { cause: error });
+        }
+        // Lost a create race — validate the winner below.
+    }
+    // Rebind full SessionManager so subsequent Pi appends use O_APPEND (flushed=true)
+    // instead of exclusive wx create against the file we just wrote.
+    if (typeof sessionManager.setSessionFile === "function") {
+        sessionManager.setSessionFile(resolvedFile);
+    }
+}
+/**
+ * Admit a durable Pi session file principal (ADR 0048/0065).
+ * Requires an existing regular file at admission (or a live SessionManager header that
+ * can be materialized onto the same path). Rejects relative paths, directories,
+ * non-files, and nonexistent paths that cannot be materialized. Original filesystem
+ * causes are retained.
+ *
+ * Record-placement (session must live under the ledger book) is NOT enforced here —
+ * that check lives on the archivist record entry (createRecordSession). Activation only
+ * binds the durable principal identity for the role run.
+ *
+ * Upstream Pi defers exclusive create until the first assistant message. When the path
+ * is the live SessionManager principal and only the header is in memory, admission
+ * materializes that header onto the same path before the fact is written so the role
+ * fact never points at a session that may be created later.
+ */
+export function durableSessionPointer(sessionManager) {
+    const file = sessionManager.getSessionFile?.();
+    if (typeof file !== "string" || file.length === 0) {
+        throw new Error("Workflow role activation requires a durable Pi session file principal (getSessionFile); directory-only or --no-session invocations are rejected");
+    }
+    if (!isAbsolute(file)) {
+        throw new Error(`Workflow role activation requires an absolute durable session file path; got relative path: ${file}`);
+    }
+    const resolvedFile = resolve(file);
+    try {
+        lstatSync(resolvedFile);
+    }
+    catch (error) {
+        if (errnoCode(error) !== "ENOENT") {
+            throw new Error(`Workflow role activation failed to stat durable session file (${resolvedFile}): ${errorText(error)}`, { cause: error });
+        }
+        try {
+            materializeDeferredSessionFile(sessionManager, resolvedFile);
+        }
+        catch (materializeError) {
+            // Missing principal: rethrow typed missing-file identity with the original ENOENT cause.
+            // Other materialize failures keep their own typed/native identity.
+            if (materializeError instanceof ActivationSessionFileMissingError) {
+                throw new ActivationSessionFileMissingError(resolvedFile, { cause: error });
+            }
+            throw materializeError;
+        }
+    }
+    let realFile;
+    try {
+        realFile = realpathSync(resolvedFile);
+    }
+    catch (error) {
+        throw new ActivationSessionFileMissingError(resolvedFile, { cause: error });
+    }
+    let info;
+    try {
+        info = statSync(realFile);
+    }
+    catch (error) {
+        throw new Error(`Workflow role activation failed to stat durable session file (${realFile}): ${errorText(error)}`, { cause: error });
+    }
+    if (info.isDirectory()) {
+        throw new Error(`Workflow role activation durable session principal must be a file, not a directory: ${realFile}`);
+    }
+    if (!info.isFile()) {
+        throw new Error(`Workflow role activation durable session principal is not a regular file: ${realFile}`);
+    }
+    return { kind: "session-file", path: realFile };
+}

package/dist/activation-ledger.js

@@ -0,0 +1,139 @@
+import { constants, closeSync, fstatSync, openSync, writeSync, } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { ActivationLedgerError, activationWaitingLedgerPath, assertLedgerFileInsideHome, ensureRealDirectoryTree, errorText, } from "./activation-ledger-topology.js";
+/** Private open flags: O_NOFOLLOW closes the lstat→open TOCTOU window. */
+const ACTIVATION_LEDGER_APPEND_OPEN_FLAGS = constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | constants.O_NOFOLLOW;
+export { ActivationGitRepositoryRequiredError, resolveBookKeyFromGit, } from "./activation-ledger-git.js";
+export { ActivationSessionFileMissingError, durableSessionPointer, } from "./activation-ledger-session.js";
+export { ActivationLedgerError, activationBookDirectory, activationWaitingLedgerPath, resolveActivationLedgerHome, } from "./activation-ledger-topology.js";
+export const ACCEPTED_ACTIVATION_EVENT = "accepted-activation";
+/**
+ * Package-owned index-only top-level keys for accepted-activation facts (ADR 0049).
+ * Sole machine key contract: projection and tests consume this descriptor — not prose markers.
+ */
+export const ACCEPTED_ACTIVATION_FACT_KEYS = Object.freeze([
+    "event",
+    "role",
+    "observedAt",
+    "bookKey",
+    "session",
+    "correlation",
+]);
+const _acceptedActivationFactKeysMatch = true;
+void _acceptedActivationFactKeysMatch;
+/**
+ * Host correlation channel (not a CLI flag): a non-blank AK_CORRELATION_ID carries
+ * the caller id verbatim; missing/blank/whitespace-only yields the typed absent identity.
+ */
+export function correlationIdentityFromEnv(env = process.env) {
+    const raw = env.AK_CORRELATION_ID;
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        return { kind: "caller", id: raw };
+    }
+    return { kind: "absent" };
+}
+/**
+ * Descriptor-driven top-level pick: only ACCEPTED_ACTIVATION_FACT_KEYS leave this boundary.
+ * Nested session/correlation are rebuilt closed before the pick (ADR 0049 zero-content by construction).
+ */
+function projectAcceptedActivationFact(input) {
+    const closed = {
+        event: ACCEPTED_ACTIVATION_EVENT,
+        role: input.role,
+        observedAt: input.observedAt,
+        bookKey: input.bookKey,
+        session: { kind: "session-file", path: input.session.path },
+        correlation: input.correlation.kind === "caller"
+            ? { kind: "caller", id: input.correlation.id }
+            : { kind: "absent" },
+    };
+    // Descriptor is the sole top-level emission contract (typed pick; no content keys).
+    return Object.fromEntries(ACCEPTED_ACTIVATION_FACT_KEYS.map((key) => [key, closed[key]]));
+}
+/** Construct the closed fact from trusted typed inputs only (descriptor projection — no content keys). */
+export function buildAcceptedActivationFact(input) {
+    return projectAcceptedActivationFact(input);
+}
+/** Serialize only the closed index fields (descriptor projection — no content keys). */
+export function serializeAcceptedActivationFact(fact) {
+    return `${JSON.stringify(projectAcceptedActivationFact(fact))}\n`;
+}
+/**
+ * Bare O_APPEND write of one complete line under an absolute ledger home.
+ * Private helper: production-bound to writeSync; owns open/write/close honesty only.
+ * Close failure cannot mask open/write; simultaneous close is nested evidence.
+ */
+function appendActivationLedgerLine(ledgerPath, line, options) {
+    if (!isAbsolute(options.ledgerHome)) {
+        throw new ActivationLedgerError(`activation ledger home must be absolute: ${options.ledgerHome}`);
+    }
+    const resolvedLedger = resolve(ledgerPath);
+    const resolvedHome = resolve(options.ledgerHome);
+    const parent = dirname(resolvedLedger);
+    ensureRealDirectoryTree(resolvedHome, parent);
+    assertLedgerFileInsideHome(resolvedLedger, resolvedHome);
+    // Fail-closed guard (same shape as PR #418's publication seam): on platforms
+    // without O_NOFOLLOW (e.g. Windows, nodejs/node#41590) the JS bitwise-or in
+    // ACTIVATION_LEDGER_APPEND_OPEN_FLAGS would silently drop the flag and the
+    // lstat→open TOCTOU anti-symlink protection would vanish while the comment
+    // above still claims it. Refuse loudly via the existing typed ledger failure
+    // channel instead of appending unprotected; never silently degrade.
+    if (typeof constants.O_NOFOLLOW !== "number") {
+        throw new ActivationLedgerError("activation ledger append requires O_NOFOLLOW open-flag support (anti-symlink TOCTOU protection must not be silently dropped); refusing to append");
+    }
+    const bytes = Buffer.isBuffer(line) ? line : Buffer.from(line);
+    let ledgerFd;
+    let primaryFailure;
+    try {
+        try {
+            ledgerFd = openSync(resolvedLedger, ACTIVATION_LEDGER_APPEND_OPEN_FLAGS, 0o644);
+        }
+        catch (error) {
+            // Native ELOOP/filesystem cause retained; no errno dispatch.
+            throw new ActivationLedgerError(`activation ledger failed to open ledger file (${resolvedLedger}): ${errorText(error)}`, { cause: error });
+        }
+        let opened;
+        try {
+            opened = fstatSync(ledgerFd);
+        }
+        catch (error) {
+            throw new ActivationLedgerError(`activation ledger failed to fstat ledger file (${resolvedLedger}): ${errorText(error)}`, { cause: error });
+        }
+        if (!opened.isFile()) {
+            throw new ActivationLedgerError(`activation ledger is not a regular file: ${resolvedLedger}`);
+        }
+        const written = writeSync(ledgerFd, bytes, 0, bytes.length, null);
+        if (written !== bytes.length) {
+            throw new ActivationLedgerError(`activation ledger short write: wrote ${written} of ${bytes.length} bytes to ${resolvedLedger}`);
+        }
+    }
+    catch (error) {
+        primaryFailure = error;
+    }
+    if (ledgerFd !== undefined) {
+        try {
+            closeSync(ledgerFd);
+        }
+        catch (closeFailure) {
+            if (primaryFailure !== undefined) {
+                throw new AggregateError([primaryFailure, closeFailure], "activation ledger operation and close failed", { cause: primaryFailure });
+            }
+            throw closeFailure;
+        }
+    }
+    if (primaryFailure !== undefined)
+        throw primaryFailure;
+}
+/**
+ * Append one complete JSONL record with one O_APPEND write of the full record.
+ * Shared-ledger contract: concurrent successful append-only producers cannot
+ * overwrite one another. A short write is an honest infrastructure failure
+ * (ADR 0049) — no non-append rollback/truncate. Close failure cannot mask the
+ * primary write cause; simultaneous close evidence is retained.
+ */
+export function appendAcceptedActivationFact(ledgerPath, fact, options) {
+    appendActivationLedgerLine(ledgerPath, Buffer.from(serializeAcceptedActivationFact(fact), "utf8"), { ledgerHome: options.ledgerHome });
+}
+export function appendAcceptedActivationToBook(options) {
+    appendAcceptedActivationFact(activationWaitingLedgerPath(options.ledgerHome, options.fact.bookKey), options.fact, { ledgerHome: options.ledgerHome });
+}

package/dist/activation-trace.js

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+const causeSchema = Type.Object({
+    identity: Type.String({ minLength: 1 }),
+    name: Type.String({ minLength: 1 }),
+    message: Type.String(),
+    evidenceId: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+export const activationTraceRecordSchema = Type.Object({
+    role: Type.String({ minLength: 1 }),
+    stageId: Type.String({ pattern: "^[a-z][a-z0-9-]*$" }),
+    status: Type.Literal("failed"),
+    timestamp: Type.String({ format: "date-time" }),
+    cause: causeSchema,
+}, { additionalProperties: false });
+let activationCauseEvidence = 0;
+const retainedActivationCauses = new Map();
+export function namedActivationCause(error) {
+    const evidenceId = `activation-cause-${++activationCauseEvidence}`;
+    retainedActivationCauses.set(evidenceId, error);
+    if (error instanceof Error) {
+        const code = error.code;
+        const name = error.name || "Error";
+        return { identity: typeof code === "string" && code.length > 0 ? code : name, name, message: error.message, evidenceId };
+    }
+    let message;
+    try {
+        message = typeof error === "string" ? error : JSON.stringify(error) ?? String(error);
+        return { identity: "UnknownThrownCause", name: "UnknownThrownCause", message, evidenceId };
+    }
+    catch {
+        return { identity: "UnknownThrownCause", name: "UnknownThrownCause", message: String(error), evidenceId };
+    }
+}

package/dist/agent-start-materials.js

@@ -0,0 +1,11 @@
+/**
+ * Sole production fold of typed agent-start materials into provider-visible
+ * system-prompt bytes. Pi adapter and Grok ACP adapter both call this at the
+ * send boundary; structured materials are the authority, this string is the
+ * provider wire form.
+ */
+export function renderAgentStartMaterials(body, materials) {
+    if (materials.length === 0)
+        return body;
+    return [body, ...materials.map((material) => JSON.stringify(material))].join("\n\n");
+}

package/dist/auditor-role.js

@@ -0,0 +1,12 @@
+/**
+ * Public Auditor (审刑院) role — filed-officer envelope (#675).
+ */
+import { AUDITOR_ACCEPTED_TEXT, AUDITOR_OUTPUT_TOOL_NAME, auditorOutputSchema, } from "./package-contracts/auditor-output.js";
+export { AUDITOR_ACCEPTED_TEXT, AUDITOR_OUTPUT_TOOL_NAME };
+export const AUDITOR_TOOL_SPEC = {
+    name: AUDITOR_OUTPUT_TOOL_NAME,
+    label: "审刑院输出",
+    description: "审刑院终局回执，状态为 pass、bounce 或 escalate。",
+    promptSnippet: "审刑院终局回执",
+    parameters: auditorOutputSchema,
+};

package/dist/canonical-skill-binding.js

@@ -0,0 +1,64 @@
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { stripFrontmatter } from "@earendil-works/pi-coding-agent";
+export function captureCanonicalSkillExpansion(name, snapshot, configuredPath, evidence, originalRequest) {
+    const matchedPath = evidence?.location === configuredPath
+        ? configuredPath
+        : evidence?.location === snapshot.path
+            ? snapshot.path
+            : undefined;
+    const expectedContent = matchedPath === undefined
+        ? undefined
+        : `References are relative to ${dirname(matchedPath)}.\n\n${snapshot.body}`;
+    if (evidence?.name !== name
+        || matchedPath === undefined
+        || evidence.content !== expectedContent
+        || evidence.userMessage !== originalRequest) {
+        return undefined;
+    }
+    return Object.freeze({ ...evidence, name });
+}
+export class CanonicalSkillUnavailableError extends Error {
+    skillName;
+    code = "canonical-skill-unavailable";
+    constructor(skillName, path, cause) {
+        super(`Canonical ${skillName} Skill is unavailable at ${path}`, { cause });
+        this.skillName = skillName;
+        this.name = "CanonicalSkillUnavailableError";
+    }
+}
+export async function loadCanonicalSkillBinding(name) {
+    const configuredPath = resolve(homedir(), `.agents/skills/${name}/SKILL.md`);
+    let path;
+    let raw;
+    try {
+        path = await realpath(configuredPath);
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new CanonicalSkillUnavailableError(name, configuredPath, error);
+    }
+    const body = stripFrontmatter(raw).trim();
+    if (body.length === 0) {
+        throw new Error(`Canonical ${name} Skill is empty at ${path}`);
+    }
+    const snapshot = Object.freeze({
+        raw,
+        path,
+        baseDir: dirname(path),
+        body,
+        snapshotIdentity: Object.freeze({ text: raw }),
+    });
+    const binding = {
+        name,
+        snapshot,
+        invocation(originalRequest) {
+            return `/skill:${name} ${originalRequest}`;
+        },
+        captureExpansion(evidence, originalRequest) {
+            return captureCanonicalSkillExpansion(name, snapshot, configuredPath, evidence, originalRequest);
+        },
+    };
+    return Object.freeze(binding);
+}

package/dist/collector-identity.js

@@ -0,0 +1,151 @@
+import { CorrectableSubmissionError } from "./submission-correctable-error.js";
+function identityKey(identity) {
+    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, observed) {
+    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, targetHead) {
+    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, targetHead) {
+    const groups = new Map();
+    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 = {
+            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) {
+        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) {
+        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) {
+    const candidate = input.candidate;
+    if (candidate === undefined || candidate === null)
+        return;
+    if (typeof candidate !== "object" || Array.isArray(candidate)) {
+        throw new CollectorFindingsValidationError("通进司交件参数必须为对象");
+    }
+    const rawFindings = candidate.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.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.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/dist/collector-receipt.js

@@ -0,0 +1,95 @@
+import { COLLECTOR_HOST } from "./collector-config.js";
+import { enrichCollectorFindings, extractCollectorEvidenceIdentityGroups, } from "./collector-identity.js";
+import { validateAcceptedCollectorReceipt } from "./package-contracts/collector-output.js";
+export { validateAcceptedCollectorReceipt };
+function fail(message) { throw new Error(message); }
+/** Runtime output assembles findings pointers from the model submission into the typed receipt. */
+export function buildCollectorReceipt(ledger, candidateRaw, clock) {
+    ledger.assertNotFatal();
+    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 (clock !== undefined)
+        ledger.assertOutputObservationLaw(clock);
+    else if (ledger.observedGeneration !== ledger.mutationGeneration ||
+        (ledger.finalObservationRequired && !ledger.finalObservationCompleted)) {
+        fail("Collector output requires a complete observe after the latest request/wait mutation");
+    }
+    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");
+    const evidenceRecords = [...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]));
+    if (evidenceIndex.size !== evidenceRecords.length)
+        fail("Collector receipt evidenceId collision");
+    if (snapshotIndex.size !== snapshots.length)
+        fail("Collector receipt snapshotId collision");
+    for (const id of evidenceIndex.keys())
+        if (snapshotIndex.has(id))
+            fail(`Collector receipt id "${id}" is ambiguous`);
+    if (!snapshotIndex.has(finalSnapshot.snapshotId))
+        fail("Collector receipt lacks final snapshot");
+    for (const snapshot of snapshots) {
+        for (const id of snapshot.evidenceIds)
+            if (!evidenceIndex.has(id))
+                fail(`Collector snapshot ref "${id}" does not resolve`);
+    }
+    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) {
+            if (material.evidenceId === undefined || !evidenceIndex.has(material.evidenceId))
+                fail("Collector material lacks a receipt-local evidence ref");
+        }
+        for (const finding of group.findings) {
+            if (finding.source.evidenceId === undefined || !evidenceIndex.has(finding.source.evidenceId))
+                fail("Collector finding lacks a receipt-local evidence ref");
+        }
+    }
+    return {
+        host: COLLECTOR_HOST,
+        repository: ledger.config.repository.canonical,
+        prNumber: ledger.config.prNumber,
+        manifestDigest: ledger.config.manifest.digest,
+        activationTime: ledger.activationTime.toISOString(),
+        deadlineTime: ledger.deadlineTime.toISOString(),
+        finalObservationTime: finalSnapshot.completedAt ?? finalSnapshot.observedAt,
+        finalSnapshotId: finalSnapshot.snapshotId,
+        targetHead: finalSnapshot.headOid,
+        groups,
+        requestAttempts: [...ledger.requestAttempts()],
+        snapshots,
+        evidenceRecords: evidenceRecords.map(toReceiptEvidenceRecord),
+    };
+}
+function toReceiptEvidenceRecord(record) {
+    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 }),
+    };
+}