@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/dist/lib/task/local-artifact-finalization.js

@@ -1,29 +1,47 @@
 import fs from 'node:fs';
-import { inspectDecisionDetailDuplicates, scanVisibleMarkdown } from './decision-details.js';
-import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { inspectDecisionDetailDuplicates } from './decision-details.js';
+import { scanVisibleMarkdown } from './markdown.js';
+import { parseArtifactName } from './artifact-name.js';
+import { hasOpenArtifactRound, validateArtifactPublication, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.js';
 import { canonicalSemanticDigest, inspectArtifactPatterns, inspectArtifactStructure, sha256Content } from './artifact-operations.js';
 import { getArtifactSchema } from './artifact-schema.js';
 import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.js';
+import { consumeLifecycleRecoveryAttestation, lifecycleRecoveryAttestationDigest, validateLifecycleRecoveryAttestation } from './control-authority.js';
 const LOCAL_ARTIFACT_REQUIRED_SECTIONS = {
     analysis: getArtifactSchema('analysis').sections.map((section) => section.headings.zh),
     plan: getArtifactSchema('plan').sections.map((section) => section.headings.zh),
     code: getArtifactSchema('code').sections.map((section) => section.headings.zh)
 };
-function readLocalArtifactFinalizationIntent(repoRoot, taskId, family, artifact) {
-    return readArtifactRepairIntent(repoRoot, taskId, family, artifact);
+function authorityDigest(authority) {
+    return lifecycleRecoveryAttestationDigest(authority);
 }
-function writeLocalArtifactFinalizationIntent(repoRoot, value) {
-    writeArtifactRepairIntent(repoRoot, value);
+function validFinalizerAuthority(authority, request, taskId) {
+    if (!authority)
+        return false;
+    try {
+        validateLifecycleRecoveryAttestation(authority);
+    }
+    catch {
+        return false;
+    }
+    return authority.version === 1
+        && authority.phase === 'artifact.finalize-local'
+        && authority.taskId === taskId
+        && authority.family === request.family
+        && authority.artifact === request.artifact
+        && authority.round === (parseArtifactName(request.artifact)?.round ?? 0)
+        && authority.requestId.length > 0
+        && authority.operationId.length > 0;
 }
 function consumeLocalArtifactFinalizationIntent(repoRoot, intent) {
     if (intent.state === 'consumed')
         return intent;
     if (intent.state !== 'passed')
         throw new Error('LOCAL_FINALIZATION_INTENT_INVALID: only passed provenance can be consumed');
-    const consumed = { ...intent, state: 'consumed' };
-    writeLocalArtifactFinalizationIntent(repoRoot, consumed);
+    const consumed = { ...intent, state: 'consumed', updatedAt: Date.now() };
+    writeArtifactRepairIntent(repoRoot, consumed, { expected: intent });
     return consumed;
 }
 function localDiagnosticCode(code) {
@@ -120,180 +138,137 @@ function failedFinalization(request, error, extra = {}) {
         repairable: false, diagnostics: [], error, ...extra
     };
 }
-function provenanceFailure(request, resolved, content, artifactSha256, semanticDigestValue, code, message) {
-    return failedFinalization(request, { code, message }, {
-        taskId: resolved.taskId,
-        taskDir: resolved.taskDir,
-        artifactSha256,
-        semanticDigest: semanticDigestValue,
-        diagnostics: [{ code, message, repairable: false, line: null }]
+/** Read and validate once; callers publish this content before committing provenance. */
+function prepareLocalArtifact(request, candidate, authority) {
+    const failed = (code, message) => ({
+        result: failedFinalization(request, { code, message }), content: candidate ?? ''
     });
-}
-function finalizeLocalArtifact(request) {
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: request.repoRoot });
     if (!resolved.ok)
-        return failedFinalization(request, { code: resolved.code, message: resolved.message });
+        return failed(resolved.code, resolved.message);
     const parsed = parseArtifactName(request.artifact);
-    if (!parsed || parsed.family !== request.family) {
-        return failedFinalization(request, {
-            code: 'ARTIFACT_IDENTITY_INVALID',
-            message: `artifact '${request.artifact}' does not match ${request.family}`
-        }, { taskId: resolved.taskId, taskDir: resolved.taskDir });
-    }
-    const validated = validateCompletedArtifact(resolved.taskDir, request.family, request.artifact, parsed.round);
-    if (!validated.ok) {
-        return failedFinalization(request, validated.error, { taskId: resolved.taskId, taskDir: resolved.taskDir });
-    }
+    if (!parsed || parsed.family !== request.family)
+        return failed('ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${request.family}`);
     let content;
-    try {
-        content = fs.readFileSync(validated.artifact.path, 'utf8');
-    }
-    catch (error) {
-        return failedFinalization(request, { code: 'ARTIFACT_NOT_READABLE', message: String(error) }, {
-            taskId: resolved.taskId, taskDir: resolved.taskDir
-        });
-    }
     let taskContent;
     try {
         taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+        if (candidate !== undefined) {
+            const error = validateArtifactPublication(resolved.taskDir, request.family, request.artifact);
+            if (error)
+                return failed(error.code, error.message);
+            if (resolved.state !== 'active' || !hasOpenArtifactRound(taskContent, request.family, parsed.round)) {
+                return failed('ARTIFACT_IDENTITY_INVALID', 'candidate must match one open started round in an active task');
+            }
+            content = candidate;
+        }
+        else {
+            const validated = validateCompletedArtifact(resolved.taskDir, request.family, request.artifact, parsed.round);
+            if (!validated.ok)
+                return failed(validated.error.code, validated.error.message);
+            content = fs.readFileSync(validated.artifact.path, 'utf8');
+        }
     }
     catch (error) {
-        return failedFinalization(request, { code: 'TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error) }, {
-            taskId: resolved.taskId, taskDir: resolved.taskDir
-        });
+        return failed('ARTIFACT_NOT_READABLE', String(error));
     }
-    const result = validateLocalArtifact(content, {
-        family: request.family,
-        requiredSections: request.requiredSections,
-        taskContent,
-        artifact: request.artifact
+    const validation = validateLocalArtifact(content, {
+        family: request.family, requiredSections: request.requiredSections, taskContent, artifact: request.artifact
     });
     const artifactSha256 = sha256Content(content);
+    const { semanticDigest, repairable, diagnostics } = validation;
+    const result = failedFinalization(request, {
+        code: 'LOCAL_ARTIFACT_INVALID', message: diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
+    }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest, repairable, diagnostics });
+    const preparedBase = { result, content, repoRoot: resolved.repoRoot };
+    if (authority !== undefined && !validFinalizerAuthority(authority, request, resolved.taskId)) {
+        return {
+            ...preparedBase,
+            result: { ...result, repairable: false, error: {
+                    code: 'LOCAL_EXECUTION_AUTHORITY_INVALID',
+                    message: 'finalizer authority does not match the artifact tuple'
+                }, diagnostics: [] }
+        };
+    }
+    const reject = (code, message) => ({
+        ...prepared, result: { ...result, repairable: false, error: { code, message },
+            diagnostics: [{ code, message, repairable: false, line: null }] }
+    });
     let intent;
     try {
-        intent = readLocalArtifactFinalizationIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
+        intent = readArtifactRepairIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
     }
     catch (error) {
-        return failedFinalization(request, {
-            code: 'LOCAL_FINALIZATION_INTENT_INVALID',
-            message: error instanceof Error ? error.message : String(error)
-        }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
+        return { ...preparedBase, result: { ...result, repairable: false, diagnostics: [],
+                error: { code: 'LOCAL_FINALIZATION_INTENT_INVALID', message: String(error) } } };
     }
-    if (result.repairable) {
-        if (intent && (intent.state !== 'awaiting-repair' || intent.baselineSemanticDigest !== result.semanticDigest)) {
-            return provenanceFailure(request, resolved, content, artifactSha256, result.semanticDigest, 'LOCAL_REPAIR_PROVENANCE_CONFLICT', 'a different local repair baseline is already recorded for this artifact');
-        }
-        if (!intent) {
-            try {
-                writeLocalArtifactFinalizationIntent(resolved.repoRoot, {
-                    version: 1,
-                    taskId: resolved.taskId,
-                    family: request.family,
-                    artifact: request.artifact,
-                    state: 'awaiting-repair',
-                    baselineSemanticDigest: result.semanticDigest,
-                    artifactSha256,
-                    semanticDigest: result.semanticDigest
-                });
-            }
-            catch (error) {
-                return failedFinalization(request, {
-                    code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED',
-                    message: error instanceof Error ? error.message : String(error)
-                }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
-            }
-        }
-        return {
-            status: 'failed',
-            changed: false,
-            taskId: resolved.taskId,
-            taskDir: resolved.taskDir,
-            family: request.family,
-            artifact: request.artifact,
-            artifactSha256,
-            semanticDigest: result.semanticDigest,
-            repairable: true,
-            diagnostics: result.diagnostics,
-            error: {
-                code: 'LOCAL_ARTIFACT_INVALID',
-                message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
-            }
-        };
-    }
-    if (!result.ok) {
-        return {
-            status: 'failed',
-            changed: false,
-            taskId: resolved.taskId,
-            taskDir: resolved.taskDir,
-            family: request.family,
-            artifact: request.artifact,
-            artifactSha256,
-            semanticDigest: result.semanticDigest,
-            repairable: false,
-            diagnostics: result.diagnostics,
-            error: {
-                code: 'LOCAL_ARTIFACT_INVALID',
-                message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
-            }
-        };
-    }
-    if (intent?.state === 'awaiting-repair' && intent.baselineSemanticDigest !== result.semanticDigest) {
-        return provenanceFailure(request, resolved, content, artifactSha256, result.semanticDigest, 'LOCAL_REPAIR_BASELINE_MISMATCH', 'the repaired artifact semantic digest does not match the recorded repair baseline');
+    const prepared = { ...preparedBase, expectedIntent: intent };
+    if (intent && intent.recoveryOperationId !== null
+        && (!authority || intent.recoveryOperationId !== authority.operationId)) {
+        return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'local repair provenance is owned by another recovery operation');
     }
-    if ((intent?.state === 'passed' || intent?.state === 'consumed')
-        && (intent.artifactSha256 !== artifactSha256 || intent.semanticDigest !== result.semanticDigest)) {
-        return provenanceFailure(request, resolved, content, artifactSha256, result.semanticDigest, 'LOCAL_REPAIR_PROVENANCE_CONFLICT', 'the artifact changed after its finalization provenance was recorded');
+    if (repairable) {
+        if (intent && (intent.state !== 'awaiting-repair' || intent.baselineSemanticDigest !== semanticDigest)) {
+            return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'a different local repair baseline is already recorded for this artifact');
+        }
+        if (intent && !authority)
+            return prepared;
     }
-    if (intent?.state === 'consumed') {
-        return {
-            status: 'passed',
-            changed: false,
-            taskId: resolved.taskId,
-            taskDir: resolved.taskDir,
-            family: request.family,
-            artifact: request.artifact,
-            artifactSha256,
-            semanticDigest: result.semanticDigest,
-            repairable: false,
-            diagnostics: result.diagnostics,
-            error: null
-        };
+    else {
+        if (!validation.ok)
+            return prepared;
+        if (intent?.state === 'awaiting-repair' && intent.baselineSemanticDigest !== semanticDigest) {
+            return reject('LOCAL_REPAIR_BASELINE_MISMATCH', 'the repaired artifact semantic digest does not match the recorded repair baseline');
+        }
+        if ((intent?.state === 'passed' || intent?.state === 'consumed')
+            && (intent.artifactSha256 !== artifactSha256 || intent.semanticDigest !== semanticDigest)) {
+            return reject('LOCAL_REPAIR_PROVENANCE_CONFLICT', 'the artifact changed after its finalization provenance was recorded');
+        }
+        prepared.result = { ...result, status: 'passed', error: null };
+        if (intent?.state === 'consumed')
+            return prepared;
     }
+    const timestamp = Date.now();
+    return { ...prepared, provenance: {
+            version: 2, taskId: resolved.taskId, family: request.family, artifact: request.artifact,
+            state: repairable ? 'awaiting-repair' : 'passed',
+            baselineSemanticDigest: repairable ? semanticDigest : intent?.baselineSemanticDigest ?? null,
+            artifactSha256, semanticDigest,
+            recoveryOperationId: authority?.operationId ?? intent?.recoveryOperationId ?? null,
+            phase: authority?.phase ?? intent?.phase ?? null,
+            authorityDigest: authority ? authorityDigest(authority) : intent?.authorityDigest ?? null,
+            requestId: authority?.lifecycleRequestId ?? intent?.requestId ?? `local-finalize:${resolved.taskId}`,
+            createdAt: intent?.createdAt ?? timestamp,
+            updatedAt: timestamp
+        } };
+}
+function commitLocalArtifactProvenance(prepared) {
     try {
-        writeLocalArtifactFinalizationIntent(resolved.repoRoot, {
-            version: 1,
-            taskId: resolved.taskId,
-            family: request.family,
-            artifact: request.artifact,
-            state: 'passed',
-            baselineSemanticDigest: intent?.baselineSemanticDigest ?? null,
-            artifactSha256,
-            semanticDigest: result.semanticDigest
-        });
+        if (prepared.provenance) {
+            writeArtifactRepairIntent(prepared.repoRoot, prepared.provenance, { expected: prepared.expectedIntent ?? null });
+        }
+        return prepared.result;
     }
     catch (error) {
-        return failedFinalization(request, {
-            code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED',
-            message: error instanceof Error ? error.message : String(error)
-        }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
+        return { ...prepared.result, status: 'failed', error: {
+                code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED', message: String(error)
+            } };
     }
-    return {
-        status: result.ok ? 'passed' : 'failed',
-        changed: false,
-        taskId: resolved.taskId,
-        taskDir: resolved.taskDir,
-        family: request.family,
-        artifact: request.artifact,
-        artifactSha256,
-        semanticDigest: result.semanticDigest,
-        repairable: result.repairable,
-        diagnostics: result.diagnostics,
-        error: result.ok ? null : {
-            code: 'LOCAL_ARTIFACT_INVALID',
-            message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
+}
+function finalizeLocalArtifact(request, authority, options = {}) {
+    const result = commitLocalArtifactProvenance(prepareLocalArtifact(request, undefined, authority));
+    if (authority && !options.deferLifecycleRecoveryConsumption && result.status === 'passed') {
+        try {
+            consumeLifecycleRecoveryAttestation(authority);
         }
-    };
+        catch (error) {
+            return { ...result, status: 'failed', error: {
+                    code: 'LOCAL_EXECUTION_AUTHORITY_CONSUME_FAILED',
+                    message: error instanceof Error ? error.message : String(error)
+                } };
+        }
+    }
+    return result;
 }
-export { LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, finalizeLocalArtifact, readLocalArtifactFinalizationIntent, canonicalSemanticDigest as semanticDigest, sha256Content, validateLocalArtifact };
+export { LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, finalizeLocalArtifact, prepareLocalArtifact, commitLocalArtifactProvenance, readArtifactRepairIntent as readLocalArtifactFinalizationIntent, canonicalSemanticDigest as semanticDigest, sha256Content, validateLocalArtifact };
 //# sourceMappingURL=local-artifact-finalization.js.map

package/dist/lib/task/manual-validation-completion.js

@@ -0,0 +1,26 @@
+import { readManualValidationReceipt } from './manual-validation-receipt.js';
+import { readManualValidationTransaction } from './manual-validation-transaction.js';
+function readManualValidationCompletion(taskDir, expected = {}) {
+    const { receiptDigest: expectedReceiptDigest, ...receiptIdentity } = expected;
+    const receipt = readManualValidationReceipt(taskDir, receiptIdentity);
+    if (!receipt.ok)
+        return receipt;
+    if (expectedReceiptDigest !== undefined && receipt.value.receiptDigest !== expectedReceiptDigest) {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_RECEIPT_IDENTITY_MISMATCH', message: 'receipt digest does not match the expected completion' } };
+    }
+    const transaction = readManualValidationTransaction(taskDir, {
+        transactionId: receipt.value.transactionId,
+        taskId: receipt.value.taskId,
+        prNumber: receipt.value.prNumber,
+        prHeadSha: receipt.value.prHeadSha,
+        artifact: receipt.value.artifact
+    });
+    if (!transaction.ok)
+        return transaction;
+    if (transaction.value.committedReceipt !== receipt.value.receiptDigest) {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'completion transaction is not bound to the canonical receipt' } };
+    }
+    return { ok: true, value: { receipt: receipt.value, transaction: transaction.value } };
+}
+export { readManualValidationCompletion };
+//# sourceMappingURL=manual-validation-completion.js.map

package/dist/lib/task/manual-validation-evidence.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { MANUAL_VALIDATION_SHA40 as SHA40, MANUAL_VALIDATION_TASK_ID as TASK_ID, exactKeys, isRecord, validTimestamp } from './manual-validation-shared.js';
+const MANUAL_VALIDATION_EVIDENCE_SCHEMA = 'agent-infra/branch-only-validation-evidence';
+const MANUAL_VALIDATION_EVIDENCE_VERSION = 1;
+function invalid(message) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_EVIDENCE_INVALID', message } };
+}
+function validateShape(value) {
+    if (!isRecord(value))
+        return invalid('evidence must be a JSON object');
+    const topError = exactKeys(value, ['schema', 'version', 'mode', 'taskId', 'branch', 'commit', 'recoverable', 'source', 'result'], 'evidence');
+    if (topError)
+        return invalid(topError);
+    if (value.schema !== MANUAL_VALIDATION_EVIDENCE_SCHEMA || value.version !== MANUAL_VALIDATION_EVIDENCE_VERSION) {
+        return invalid('evidence schema or version is unsupported');
+    }
+    if (value.mode !== 'task-bound' && value.mode !== 'branch-only')
+        return invalid('mode must be task-bound or branch-only');
+    if (value.taskId !== null && (typeof value.taskId !== 'string' || !TASK_ID.test(value.taskId)))
+        return invalid('taskId must be a TASK identifier or null');
+    if (typeof value.branch !== 'string' || !value.branch.trim() || /[\r\n]/u.test(value.branch))
+        return invalid('branch must be a non-empty single line');
+    if (typeof value.commit !== 'string' || !SHA40.test(value.commit))
+        return invalid('commit must be a 40-character lowercase hexadecimal SHA');
+    if (typeof value.recoverable !== 'boolean')
+        return invalid('recoverable must be boolean');
+    if (value.source !== 'run-manual-validation')
+        return invalid('source is unsupported');
+    if (value.mode === 'branch-only' && (value.taskId !== null || value.recoverable !== false))
+        return invalid('branch-only evidence must be non-recoverable and task-free');
+    if (value.mode === 'task-bound' && (value.taskId === null || value.recoverable !== true))
+        return invalid('task-bound evidence must identify a recoverable task');
+    if (!isRecord(value.result))
+        return invalid('result must be a JSON object');
+    const result = value.result;
+    const resultError = exactKeys(result, ['scope', 'command', 'startedAt', 'completedAt', 'exitCode', 'signal', 'cleanup'], 'result');
+    if (resultError)
+        return invalid(resultError);
+    if (result.scope !== 'snapshot' && result.scope !== 'inplace')
+        return invalid('result.scope is invalid');
+    if (typeof result.command !== 'string' || !result.command || /[\\/\r\n]/u.test(result.command))
+        return invalid('result.command must be a basename');
+    if (!validTimestamp(result.startedAt) || !validTimestamp(result.completedAt) || Date.parse(result.completedAt) < Date.parse(result.startedAt))
+        return invalid('result timestamps are invalid');
+    const exitCode = result.exitCode;
+    if (!Number.isSafeInteger(exitCode) || exitCode < 0)
+        return invalid('result.exitCode must be a non-negative integer');
+    if (result.signal !== null && (typeof result.signal !== 'string' || !result.signal || /[\r\n]/u.test(result.signal)))
+        return invalid('result.signal must be a string or null');
+    if (!['completed', 'pending', 'failed', 'not-created'].includes(result.cleanup))
+        return invalid('result.cleanup is invalid');
+    return { ok: true, value: value };
+}
+function createManualValidationEvidence(input) {
+    const value = {
+        schema: MANUAL_VALIDATION_EVIDENCE_SCHEMA,
+        version: MANUAL_VALIDATION_EVIDENCE_VERSION,
+        mode: input.mode,
+        taskId: input.taskId,
+        branch: input.branch,
+        commit: input.commit,
+        recoverable: input.recoverable,
+        source: 'run-manual-validation',
+        result: {
+            scope: input.scope,
+            command: input.command,
+            startedAt: input.startedAt,
+            completedAt: input.completedAt,
+            exitCode: input.exitCode,
+            signal: input.signal,
+            cleanup: input.cleanup
+        }
+    };
+    const checked = validateShape(value);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    return checked.value;
+}
+function manualValidationEvidenceSummary(evidence) {
+    return {
+        version: 1,
+        taskId: evidence.taskId,
+        branch: evidence.branch,
+        scope: evidence.result.scope,
+        commit: evidence.commit,
+        command: evidence.result.command,
+        startedAt: evidence.result.startedAt,
+        completedAt: evidence.result.completedAt,
+        exitCode: evidence.result.exitCode,
+        signal: evidence.result.signal,
+        cleanup: evidence.result.cleanup
+    };
+}
+function validateManualValidationEvidence(value, expected) {
+    const shape = validateShape(value);
+    if (!shape.ok)
+        return shape;
+    const evidence = shape.value;
+    if (evidence.result.exitCode !== 0 || evidence.result.signal !== null || evidence.result.cleanup !== 'completed') {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_EVIDENCE_UNSUCCESSFUL', message: 'validation must exit 0 without a signal and complete cleanup' } };
+    }
+    if (expected) {
+        if (evidence.taskId !== expected.taskId || evidence.branch !== expected.branch) {
+            return { ok: false, error: { code: 'MANUAL_VALIDATION_EVIDENCE_IDENTITY_MISMATCH', message: 'evidence task or branch does not match the expected identity' } };
+        }
+        if (expected.commit !== undefined && evidence.commit !== expected.commit) {
+            return { ok: false, error: { code: 'MANUAL_VALIDATION_EVIDENCE_STALE', message: 'evidence commit does not match the current head' } };
+        }
+    }
+    return shape;
+}
+function readManualValidationEvidence(file, expected) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        const code = error.code === 'ENOENT'
+            ? 'MANUAL_VALIDATION_EVIDENCE_MISSING'
+            : 'MANUAL_VALIDATION_EVIDENCE_INVALID';
+        return { ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } };
+    }
+    return validateManualValidationEvidence(parsed, expected);
+}
+function manualValidationEvidenceDigest(evidence) {
+    return createHash('sha256').update(JSON.stringify(evidence), 'utf8').digest('hex');
+}
+export { MANUAL_VALIDATION_EVIDENCE_SCHEMA, MANUAL_VALIDATION_EVIDENCE_VERSION, createManualValidationEvidence, manualValidationEvidenceSummary, manualValidationEvidenceDigest, readManualValidationEvidence, validateManualValidationEvidence };
+//# sourceMappingURL=manual-validation-evidence.js.map

package/dist/lib/task/manual-validation-receipt.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { MANUAL_VALIDATION_ARTIFACT as ARTIFACT, MANUAL_VALIDATION_SHA40 as SHA40, MANUAL_VALIDATION_SHA64 as SHA64, MANUAL_VALIDATION_TASK_ID as TASK_ID, exactKeys, isRecord, validTimestamp, writeJsonAtomic } from './manual-validation-shared.js';
+const MANUAL_VALIDATION_RECEIPT_SCHEMA = 'agent-infra/manual-validation-receipt';
+const MANUAL_VALIDATION_RECEIPT_VERSION = 1;
+function invalid(message) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_RECEIPT_INVALID', message } };
+}
+function canonicalPayload(receipt) {
+    return {
+        schema: MANUAL_VALIDATION_RECEIPT_SCHEMA,
+        version: MANUAL_VALIDATION_RECEIPT_VERSION,
+        transactionId: receipt.transactionId,
+        taskId: receipt.taskId,
+        prNumber: receipt.prNumber,
+        prHeadSha: receipt.prHeadSha,
+        evidenceDigest: receipt.evidenceDigest,
+        artifact: receipt.artifact,
+        artifactSha256: receipt.artifactSha256,
+        pendingSummaryDigest: receipt.pendingSummaryDigest,
+        finalSummaryDigest: receipt.finalSummaryDigest,
+        committedAt: receipt.committedAt
+    };
+}
+function manualValidationReceiptDigest(receipt) {
+    return createHash('sha256').update(JSON.stringify(canonicalPayload(receipt)), 'utf8').digest('hex');
+}
+function manualValidationFinalSummaryDigest(body) {
+    const heading = /^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/mu.exec(body);
+    const projection = heading ? body.slice(heading.index).replace(/\s+$/u, '') : body;
+    const preimage = projection.replace(/receipt=(?:[a-f0-9]{64}|<receipt>)/gu, 'receipt=<receipt>');
+    return createHash('sha256').update(preimage, 'utf8').digest('hex');
+}
+function manualValidationFinalSummaryProjectionMatches(body, receipt) {
+    const identity = `transaction=${receipt.transactionId}; receipt=${receipt.receiptDigest}; evidence=${receipt.evidenceDigest}; head=${receipt.prHeadSha}`;
+    return body.includes(identity) && manualValidationFinalSummaryDigest(body) === receipt.finalSummaryDigest;
+}
+function validateManualValidationReceipt(value, expected) {
+    if (!isRecord(value))
+        return invalid('receipt must be a JSON object');
+    const keys = ['schema', 'version', 'transactionId', 'taskId', 'prNumber', 'prHeadSha', 'evidenceDigest', 'artifact', 'artifactSha256', 'pendingSummaryDigest', 'finalSummaryDigest', 'committedAt', 'receiptDigest'];
+    const keyError = exactKeys(value, keys, 'receipt');
+    if (keyError)
+        return invalid(keyError);
+    if (value.schema !== MANUAL_VALIDATION_RECEIPT_SCHEMA || value.version !== MANUAL_VALIDATION_RECEIPT_VERSION)
+        return invalid('receipt schema or version is unsupported');
+    if (typeof value.transactionId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value.transactionId))
+        return invalid('transactionId is invalid');
+    if (typeof value.taskId !== 'string' || !TASK_ID.test(value.taskId))
+        return invalid('taskId is invalid');
+    const prNumber = value.prNumber;
+    if (!Number.isSafeInteger(prNumber) || prNumber <= 0)
+        return invalid('prNumber is invalid');
+    for (const [name, pattern] of [['prHeadSha', SHA40], ['evidenceDigest', SHA64], ['artifactSha256', SHA64], ['pendingSummaryDigest', SHA64], ['finalSummaryDigest', SHA64], ['receiptDigest', SHA64]]) {
+        if (typeof value[name] !== 'string' || !pattern.test(value[name]))
+            return invalid(`${name} is invalid`);
+    }
+    if (typeof value.artifact !== 'string' || !ARTIFACT.test(value.artifact))
+        return invalid('artifact is not a canonical manual-validation artifact');
+    if (!validTimestamp(value.committedAt))
+        return invalid('committedAt is invalid');
+    const receipt = value;
+    if (manualValidationReceiptDigest(receipt) !== receipt.receiptDigest)
+        return invalid('receiptDigest does not match receipt contents');
+    if (expected && Object.entries(expected).some(([key, expectedValue]) => expectedValue !== undefined && receipt[key] !== expectedValue)) {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_RECEIPT_IDENTITY_MISMATCH', message: 'receipt identity does not match the expected transaction' } };
+    }
+    return { ok: true, value: receipt };
+}
+function createManualValidationReceipt(input) {
+    const payload = canonicalPayload(input);
+    const receipt = { ...payload, receiptDigest: manualValidationReceiptDigest(input) };
+    const checked = validateManualValidationReceipt(receipt);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    return checked.value;
+}
+function manualValidationReceiptPath(taskDir) {
+    return path.join(taskDir, '.manual-validation', 'receipt.json');
+}
+function writeManualValidationReceiptAtomic(taskDir, receipt) {
+    const checked = validateManualValidationReceipt(receipt);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    const target = manualValidationReceiptPath(taskDir);
+    return writeJsonAtomic(target, receipt);
+}
+function readManualValidationReceipt(taskDir, expected) {
+    const file = manualValidationReceiptPath(taskDir);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        return { ok: false, error: { code: error.code === 'ENOENT' ? 'MANUAL_VALIDATION_RECEIPT_MISSING' : 'MANUAL_VALIDATION_RECEIPT_INVALID', message: error instanceof Error ? error.message : String(error) } };
+    }
+    return validateManualValidationReceipt(value, expected);
+}
+export { MANUAL_VALIDATION_RECEIPT_SCHEMA, MANUAL_VALIDATION_RECEIPT_VERSION, createManualValidationReceipt, manualValidationFinalSummaryDigest, manualValidationFinalSummaryProjectionMatches, manualValidationReceiptDigest, manualValidationReceiptPath, readManualValidationReceipt, validateManualValidationReceipt, writeManualValidationReceiptAtomic };
+//# sourceMappingURL=manual-validation-receipt.js.map

package/dist/lib/task/manual-validation-shared.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+const MANUAL_VALIDATION_TASK_ID = /^TASK-\d{8}-\d{6}$/u;
+const MANUAL_VALIDATION_SHA40 = /^[a-f0-9]{40}$/u;
+const MANUAL_VALIDATION_SHA64 = /^[a-f0-9]{64}$/u;
+const MANUAL_VALIDATION_ARTIFACT = /^manual-validation(?:-r[2-9]|-r[1-9]\d+)?.md$/u;
+const MANUAL_VALIDATION_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function exactKeys(value, keys, label) {
+    const allowed = new Set(keys);
+    const unknown = Object.keys(value).find((key) => !allowed.has(key));
+    if (unknown)
+        return `${label} contains unknown field '${unknown}'`;
+    const missing = keys.find((key) => !Object.hasOwn(value, key));
+    return missing ? `${label} is missing '${missing}'` : null;
+}
+function validTimestamp(value) {
+    return typeof value === 'string' && MANUAL_VALIDATION_TIMESTAMP.test(value) && Number.isFinite(Date.parse(value));
+}
+function writeJsonAtomic(file, value) {
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+        fs.renameSync(temporary, file);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* best effort cleanup of our own temp file */ }
+        throw error;
+    }
+    return file;
+}
+export { MANUAL_VALIDATION_ARTIFACT, MANUAL_VALIDATION_SHA40, MANUAL_VALIDATION_SHA64, MANUAL_VALIDATION_TASK_ID, MANUAL_VALIDATION_TIMESTAMP, exactKeys, isRecord, validTimestamp, writeJsonAtomic };
+//# sourceMappingURL=manual-validation-shared.js.map