@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/dist/submission-ledger.js

@@ -0,0 +1,388 @@
+import { resolveActivationLedgerHome, tryHomeFromAkRolesPath, } from "./activation-ledger-topology.js";
+import { isAuditEscalationProjection, projectAuditEscalation } from "./audit-escalation.js";
+import { GatekeeperEscalationError } from "./gatekeeper-role.js";
+import { acceptedFacts, isTerminatingToolName, } from "./package-contracts/terminating-tools.js";
+import { runIdFromRunDirectory } from "./run-terminal-artifacts.js";
+import { readSitianRecords, resolveSitianRecordPathInLedger, sitianReport } from "./sitian-facade.js";
+import { isCorrectableExecuteError } from "./submission-correctable-error.js";
+import { failOnInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
+/**
+ * Admitted run identity for the ledger subject.
+ * Prefer AK_ROLE_RUN_DIR via sole runDirectory→runId parser (public-CLI correlation);
+ * otherwise session header id. Never a shared "unbound" bucket.
+ * Session-path layout fallback omitted: bare Pi and public CLI both expose header id
+ * when a session exists; missing both is infrastructure, not a third guess.
+ */
+function runIdentity(context) {
+    const directory = process.env.AK_ROLE_RUN_DIR;
+    if (typeof directory === "string" && directory.length > 0) {
+        const fromDir = runIdFromRunDirectory(directory);
+        if (fromDir !== undefined)
+            return fromDir;
+    }
+    const headerId = context.sessionManager.getHeader?.()?.id;
+    if (typeof headerId === "string" && headerId.length > 0)
+        return headerId;
+    throw new Error("提交账需要已受理的 run 身份");
+}
+/**
+ * Court-turn attempt identity (#637 same-ticket re-summons).
+ * AK_ROLE_COURT_ATTEMPT is injected only for a new court turn on an already-retained
+ * run (forceContinuation / summons). Manual resume and first mint omit it so the
+ * session-stable id keeps sole-final + sealed-idempotent semantics.
+ */
+export const COURT_ATTEMPT_ENV = "AK_ROLE_COURT_ATTEMPT";
+function attemptIdentity(context, runId) {
+    const courtAttempt = process.env[COURT_ATTEMPT_ENV];
+    if (typeof courtAttempt === "string" && courtAttempt.length > 0)
+        return courtAttempt;
+    return context.sessionManager.getHeader?.()?.id ?? context.sessionManager.getLeafId?.() ?? `${runId}:initial`;
+}
+function isAcceptedProjection(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return candidate.kind === "accepted" && typeof candidate.role === "string" && typeof candidate.status === "string" && typeof candidate.decisiveFacts === "object" && candidate.decisiveFacts !== null;
+}
+function isAuditEscalationTerminalProjection(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (candidate.kind === "audit_escalation" &&
+        typeof candidate.role === "string" &&
+        candidate.status === "audit_escalation" &&
+        typeof candidate.decisiveFacts === "object" &&
+        candidate.decisiveFacts !== null);
+}
+function submissionRecordFile(cwd, runId, home) {
+    const ledgerHome = resolveActivationLedgerHome(home);
+    return resolveSitianRecordPathInLedger({
+        level: "event",
+        kind: "candidate",
+        subject: { runId },
+        cwd,
+    }, ledgerHome).recordFile;
+}
+async function readOwnedSubmissionRecords(cwd, runId, home) {
+    const file = submissionRecordFile(cwd, runId, home);
+    const { records } = await readSitianRecords(file);
+    return {
+        file,
+        owned: records.filter((record) => typeof record.subject === "object" && record.subject !== null && record.subject.runId === runId),
+    };
+}
+function resolveReadScope(homeOrScope) {
+    if (homeOrScope === undefined)
+        return {};
+    if (typeof homeOrScope === "string")
+        return { home: homeOrScope };
+    return homeOrScope;
+}
+function recordAttemptId(record) {
+    if (typeof record.subject === "object" && record.subject !== null) {
+        const fromSubject = record.subject.attemptId;
+        if (typeof fromSubject === "string" && fromSubject.length > 0)
+            return fromSubject;
+    }
+    if (typeof record.payload === "object" && record.payload !== null) {
+        const fromPayload = record.payload.attemptId;
+        if (typeof fromPayload === "string" && fromPayload.length > 0)
+            return fromPayload;
+    }
+    return undefined;
+}
+function recordsForAttempt(owned, attemptId) {
+    if (attemptId === undefined)
+        return owned;
+    return owned.filter((record) => recordAttemptId(record) === attemptId);
+}
+/** Settlement read seam: typed sealed projection only, never host session JSONL.
+ * Omit attemptId for run-scoped latest sealed (manual resume idempotent).
+ * Pass attemptId for the current court turn so a prior seal cannot wash this turn. */
+export async function readSealedSubmission(cwd, runId, homeOrScope) {
+    const scope = resolveReadScope(homeOrScope);
+    const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope.home);
+    const scoped = recordsForAttempt(owned, scope.attemptId);
+    for (let index = scoped.length - 1; index >= 0; index -= 1) {
+        const record = scoped[index];
+        if (record?.kind === "post-seal-anomaly")
+            return undefined;
+        if (record?.kind !== "sealed")
+            continue;
+        const payload = record.payload;
+        if (payload?.type === "sealed" && isAcceptedProjection(payload.projection))
+            return payload.projection;
+    }
+    return undefined;
+}
+/** Non-final audit-escalation projection written by the submission ledger. */
+export async function readAuditEscalationSubmission(cwd, runId, homeOrScope) {
+    const scope = resolveReadScope(homeOrScope);
+    const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope.home);
+    const scoped = recordsForAttempt(owned, scope.attemptId);
+    for (let index = scoped.length - 1; index >= 0; index -= 1) {
+        const record = scoped[index];
+        if (record?.kind !== "outcome")
+            continue;
+        const payload = record.payload;
+        if (payload?.type !== "outcome" || payload.outcome !== "audit-escalation")
+            continue;
+        if (isAuditEscalationTerminalProjection(payload.projection))
+            return payload.projection;
+    }
+    return undefined;
+}
+/** Latest non-final outcome on the run ledger (settlement residual precedence). */
+export async function readLatestSubmissionOutcome(cwd, runId, homeOrScope) {
+    const scope = resolveReadScope(homeOrScope);
+    const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope.home);
+    const scoped = recordsForAttempt(owned, scope.attemptId);
+    for (let index = scoped.length - 1; index >= 0; index -= 1) {
+        const record = scoped[index];
+        if (record?.kind !== "outcome")
+            continue;
+        const payload = record.payload;
+        if (payload?.type === "outcome" && typeof payload.outcome === "string") {
+            return payload;
+        }
+    }
+    return undefined;
+}
+function sealedAttemptIdFromRecord(record) {
+    if (record.kind !== "sealed")
+        return undefined;
+    const payload = record.payload;
+    return payload?.type === "sealed" && typeof payload.attemptId === "string" && payload.attemptId.length > 0
+        ? payload.attemptId
+        : undefined;
+}
+async function restoreState(cwd, runId, home) {
+    const { file, owned } = await readOwnedSubmissionRecords(cwd, runId, home);
+    const last = owned.at(-1);
+    const sealedAttemptIds = new Set();
+    for (const record of owned) {
+        const attemptId = sealedAttemptIdFromRecord(record);
+        if (attemptId !== undefined)
+            sealedAttemptIds.add(attemptId);
+    }
+    return {
+        ...(last === undefined ? {} : { prior: { identity: last.identity, recordFile: file, kind: last.kind, level: last.level } }),
+        sealedAttemptIds,
+        sequence: owned.reduce((maximum, record) => {
+            const payload = record.payload;
+            return payload?.type === "candidate" && typeof payload.sequence === "number" ? Math.max(maximum, payload.sequence) : maximum;
+        }, 0),
+    };
+}
+/** Pipeline-owned sole-final state and durable projection. */
+export function createSubmissionLedgerHost(host, outputTools, failInfrastructure = (error) => { throw error; }, projectClosure = () => undefined, options) {
+    const states = new Map();
+    const rounds = new Map();
+    const resolveHomeFromContext = (context) => {
+        if (options?.home !== undefined)
+            return options.home;
+        const sessionFile = context.sessionManager.getSessionFile?.() || context.sessionManager.getSessionDir?.();
+        return typeof sessionFile === "string" && sessionFile.length > 0
+            ? tryHomeFromAkRolesPath(sessionFile)
+            : undefined;
+    };
+    const stateFor = (context, runId) => states.get(runId) ?? (() => {
+        const home = resolveHomeFromContext(context);
+        const pending = restoreState(context.cwd, runId, home);
+        states.set(runId, pending);
+        return pending;
+    })();
+    const appendFor = (state, context, runId, attemptId, event) => {
+        // Home only — must match submissionRecordFile topology (cwd + runId hash under
+        // ledger home). Do not pass sessionParent: that nests under the session dir and
+        // breaks restoreState reads which resolve the hash path without sessionParent.
+        const home = resolveHomeFromContext(context);
+        const pointer = sitianReport({
+            level: "event",
+            kind: event.type,
+            subject: { runId, attemptId },
+            ...(state.prior === undefined ? {} : { priorEventId: state.prior.identity }),
+            payload: event,
+            source: "role-runtime",
+            cwd: context.cwd,
+            ...(home !== undefined ? { home } : {}),
+        });
+        state.prior = pointer;
+        return pointer;
+    };
+    host.on("tool_execution_start", async ({ toolCallId, toolName }, context) => {
+        try {
+            const runId = runIdentity(context);
+            const attemptId = attemptIdentity(context, runId);
+            const state = await stateFor(context, runId);
+            if (state.sealedAttemptIds.has(attemptId)) {
+                appendFor(state, context, runId, attemptId, { type: "post-seal-anomaly", attemptId, toolCallId, toolName });
+            }
+        }
+        catch (error) {
+            failInfrastructure(error, context);
+        }
+    });
+    host.on("turn_end", async (event, context) => {
+        try {
+            const runId = runIdentity(context);
+            const attemptId = attemptIdentity(context, runId);
+            const candidates = rounds.get(attemptId);
+            if (candidates === undefined)
+                return;
+            rounds.delete(attemptId);
+            const state = await stateFor(context, runId);
+            const calls = event.calls.map(({ toolCallId: id, toolName: name }) => ({ id, name }));
+            appendFor(state, context, runId, attemptId, { type: "roundContext", attemptId, calls });
+            const sole = calls.length === 1 && candidates.length === 1 && calls[0]?.id === candidates[0]?.toolCallId;
+            if (!sole) {
+                for (const candidate of candidates)
+                    appendFor(state, context, runId, attemptId, { type: "outcome", attemptId, toolCallId: candidate.toolCallId, outcome: "correctable-rejection", code: "non-sole-round" });
+                if (host.deliverSubmissionRejection === undefined) {
+                    throw new Error("宿主未提供模型可见的交卷封驳接缝");
+                }
+                context.abort();
+                await host.deliverSubmissionRejection({
+                    kind: "correctable-rejection",
+                    code: "non-sole-round",
+                    toolCallIds: candidates.map(({ toolCallId }) => toolCallId),
+                });
+                return;
+            }
+            const candidate = candidates[0];
+            if (candidate.auditProjection !== undefined) {
+                appendFor(state, context, runId, attemptId, { type: "outcome", attemptId, toolCallId: candidate.toolCallId, outcome: "audit-escalation", projection: candidate.auditProjection });
+                await projectClosure(candidate.auditProjection, context);
+                context.abort();
+                return;
+            }
+            const details = typeof candidate.result.details === "object" && candidate.result.details !== null ? candidate.result.details : {};
+            const status = acceptedFacts(candidate.toolName, details).status;
+            if (typeof status !== "string" || status.length === 0)
+                throw new Error("提交账封账缺少 acceptedFacts.status");
+            const projection = { kind: "accepted", role: candidate.role, status, decisiveFacts: details };
+            appendFor(state, candidate.context, runId, attemptId, { type: "sealed", attemptId, toolCallId: candidate.toolCallId, accepted: candidate.result.details, projection });
+            state.sealedAttemptIds.add(attemptId);
+            await projectClosure(projection, context);
+            context.abort();
+        }
+        catch (error) {
+            failInfrastructure(error, context);
+        }
+    });
+    return {
+        ...host,
+        registerTool(tool) {
+            const role = outputTools.get(tool.name);
+            if (role === undefined)
+                return host.registerTool(tool);
+            host.registerTool({
+                ...tool,
+                async execute(toolCallId, params, signal, update, context) {
+                    const runId = runIdentity(context);
+                    const attemptId = attemptIdentity(context, runId);
+                    const state = await stateFor(context, runId);
+                    const append = (event) => appendFor(state, context, runId, attemptId, event);
+                    if (state.sealedAttemptIds.has(attemptId))
+                        throw new Error("提交账已封账");
+                    // #541 / #575: shared infra-declaration fail lives on the ledger seam,
+                    // before any role execute or sole-final work (one owner for every seat).
+                    // #641 chain②: seats may opt into bouncing a machine-verified normal
+                    // completion misdeclared as infrastructure failure — the bounce throws a
+                    // correctable error from the declaration call, so it lands in the same
+                    // correctable-rejection path as execute-thrown rejections below. The
+                    // candidate is booked first so the bounced attempt stays observable.
+                    append({ type: "candidate", attemptId, toolCallId, toolName: tool.name, sequence: ++state.sequence });
+                    const projectOfficerEscalation = (officer, original, deliveredOutput = original) => projectAuditEscalation({
+                        ...original,
+                        status: "escalate",
+                        officer,
+                        reason: original.reason === undefined
+                            ? `门下省${officer}上呈（原卷未附 reason）`
+                            : original.reason,
+                    }, deliveredOutput);
+                    let result;
+                    try {
+                        failOnInfrastructureFailureDeclaration(params, {
+                            failInfrastructure(error, ctx) {
+                                failInfrastructure(error, ctx);
+                            },
+                        }, context, toolCallId, tool.bounceInfrastructureDeclaration);
+                        result = await tool.execute(toolCallId, params, signal, update, context);
+                    }
+                    catch (error) {
+                        if (error instanceof GatekeeperEscalationError) {
+                            const decision = error.gatekeeper;
+                            result = projectOfficerEscalation(error.gatekeeper.officer, decision, params);
+                        }
+                        else if (isCorrectableExecuteError(error)) {
+                            append({
+                                type: "outcome",
+                                attemptId,
+                                toolCallId,
+                                outcome: "correctable-rejection",
+                                code: "typed-bounce",
+                                diagnostic: error instanceof Error ? error.message : String(error),
+                            });
+                            throw error;
+                        }
+                        else {
+                            append({
+                                type: "outcome",
+                                attemptId,
+                                toolCallId,
+                                outcome: "infrastructure",
+                                diagnostic: error instanceof Error ? error.message : String(error),
+                            });
+                            throw error;
+                        }
+                    }
+                    if ((role === "inspector" || role === "notary") &&
+                        typeof result.details === "object" &&
+                        result.details !== null &&
+                        !Array.isArray(result.details) &&
+                        result.details.status === "escalate") {
+                        const details = result.details;
+                        result = projectOfficerEscalation(role, details);
+                    }
+                    if (isAuditEscalationProjection(result.details)) {
+                        const candidates = rounds.get(attemptId) ?? [];
+                        candidates.push({
+                            toolCallId,
+                            toolName: tool.name,
+                            role,
+                            result,
+                            context,
+                            auditProjection: {
+                                kind: "audit_escalation",
+                                role,
+                                status: "audit_escalation",
+                                decisiveFacts: result.details,
+                            },
+                        });
+                        rounds.set(attemptId, candidates);
+                        return {
+                            content: [],
+                            details: { submissionDisposition: "pending-round-closure" },
+                        };
+                    }
+                    if (result.terminate !== true) {
+                        append({ type: "outcome", attemptId, toolCallId, outcome: "correctable-rejection", code: "non-terminate" });
+                        return result;
+                    }
+                    if (!isTerminatingToolName(tool.name)) {
+                        append({ type: "outcome", attemptId, toolCallId, outcome: "infrastructure", diagnostic: `non-terminating tool ${tool.name}` });
+                        throw new Error("提交账只受理终止工具");
+                    }
+                    const candidates = rounds.get(attemptId) ?? [];
+                    candidates.push({ toolCallId, toolName: tool.name, role, result, context });
+                    rounds.set(attemptId, candidates);
+                    return {
+                        content: [],
+                        details: { submissionDisposition: "pending-round-closure" },
+                    };
+                },
+            });
+        },
+    };
+}

package/dist/ticket-provenance-contracts.js

@@ -0,0 +1,115 @@
+/**
+ * 起居录（ticket-provenance）typed contracts — ADR 0075 / #582.
+ * JSONL is the sole authority; md is a derived human face.
+ */
+/** Sitian kind for per-ticket court diary volumes. */
+export const TICKET_PROVENANCE_KIND = "ticket-provenance";
+/** Human-read view filename co-located with the JSONL volume. */
+export const TICKET_PROVENANCE_HUMAN_VIEW = "起居录.md";
+/**
+ * Incremental watermark: identities already offered to the collector this ticket
+ * (selected or not). Process state next to the volume — not a diary dual-source.
+ */
+export const TICKET_PROVENANCE_OFFERED_WATERMARK = "offered-identities.jsonl";
+/** Payload discriminator: diagnostic residue (not a diary body entry). */
+export const TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC = "diagnostic";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const SOURCE_KINDS = new Set([
+    "cc-session",
+    "issue-body-comment",
+    "adr-decision-key",
+    "ticket-decree-block",
+]);
+const BASIS_METHODS = new Set(["llm-semantic"]);
+const DIAGNOSTIC_KINDS = new Set([
+    "collector-failed",
+    "issue-source-failed",
+    "quote-verify-failed",
+]);
+/**
+ * Project a typed diagnostic payload (recordClass discriminator only).
+ * Disguised diary-entry shapes are not diagnostics — no branch-intermediate compat.
+ */
+export function projectTicketProvenanceDiagnostic(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (value.recordClass !== TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC) {
+        return undefined;
+    }
+    if (typeof value.diagnosticKind !== "string" ||
+        !DIAGNOSTIC_KINDS.has(value.diagnosticKind)) {
+        return undefined;
+    }
+    if (typeof value.cause !== "string" || value.cause.length === 0) {
+        return undefined;
+    }
+    if (typeof value.recordedAt !== "string" || value.recordedAt.length === 0) {
+        return undefined;
+    }
+    return {
+        recordClass: TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC,
+        diagnosticKind: value.diagnosticKind,
+        cause: value.cause,
+        recordedAt: value.recordedAt,
+        ...(typeof value.reason === "string" ? { reason: value.reason } : {}),
+    };
+}
+/**
+ * Project a lawful diary entry from unknown payload bytes.
+ * Shape is not an admission gate for role output; this is the diarist/write seam
+ * self-check so garbage does not enter the volume.
+ * Diagnostics (recordClass discriminator) are not entries.
+ */
+export function projectTicketProvenanceEntry(value) {
+    if (!isRecord(value))
+        return undefined;
+    // Diagnostics are a separate projection — never body entries.
+    if (value.recordClass === TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC) {
+        return undefined;
+    }
+    if (!isRecord(value.basis))
+        return undefined;
+    if (typeof value.basis.method !== "string" || !BASIS_METHODS.has(value.basis.method)) {
+        return undefined;
+    }
+    if (typeof value.sourceKind !== "string" || !SOURCE_KINDS.has(value.sourceKind)) {
+        return undefined;
+    }
+    if (!isRecord(value.sourceRef))
+        return undefined;
+    if (typeof value.transcript !== "string" || value.transcript.length === 0) {
+        return undefined;
+    }
+    if (typeof value.timestamp !== "string" || value.timestamp.length === 0) {
+        return undefined;
+    }
+    const basis = {
+        method: value.basis.method,
+        ...(Array.isArray(value.basis.anchors)
+            ? {
+                anchors: value.basis.anchors.filter((item) => typeof item === "string"),
+            }
+            : {}),
+        ...(typeof value.basis.note === "string" ? { note: value.basis.note } : {}),
+    };
+    const sourceRef = {
+        ...(typeof value.sourceRef.sessionFile === "string"
+            ? { sessionFile: value.sourceRef.sessionFile }
+            : {}),
+        ...(typeof value.sourceRef.entryId === "string" ||
+            typeof value.sourceRef.entryId === "number"
+            ? { entryId: value.sourceRef.entryId }
+            : {}),
+        ...(typeof value.sourceRef.path === "string" ? { path: value.sourceRef.path } : {}),
+        ...(typeof value.sourceRef.url === "string" ? { url: value.sourceRef.url } : {}),
+    };
+    return {
+        basis,
+        sourceKind: value.sourceKind,
+        sourceRef,
+        transcript: value.transcript,
+        timestamp: value.timestamp,
+    };
+}