@fitlab-ai/agent-infra 0.9.13 → 0.9.15

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

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

@@ -0,0 +1,243 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { validateManualValidationReceipt } from './manual-validation-receipt.js';
+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_TRANSACTION_SCHEMA = 'agent-infra/manual-validation-transaction';
+const MANUAL_VALIDATION_TRANSACTION_VERSION = 1;
+const TRANSACTION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+function invalid(message) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_INVALID', message } };
+}
+function summaryPreimageDigest(body) {
+    return createHash('sha256').update(body, 'utf8').digest('hex');
+}
+function validateManualValidationTransaction(value, expected) {
+    if (!isRecord(value))
+        return invalid('transaction must be a JSON object');
+    const keys = ['schema', 'version', 'transactionId', 'taskId', 'prNumber', 'prHeadSha', 'evidenceDigest', 'summaryPreimage', 'pendingSummaryDigest', 'finalSummaryDigest', 'artifact', 'phase', 'committedReceipt', 'eventAppended', 'attempt', 'postWriteVerified', 'createdAt', 'updatedAt', 'error'];
+    const keyError = exactKeys(value, keys, 'transaction');
+    if (keyError)
+        return invalid(keyError);
+    if (value.schema !== MANUAL_VALIDATION_TRANSACTION_SCHEMA || value.version !== MANUAL_VALIDATION_TRANSACTION_VERSION)
+        return invalid('transaction schema or version is unsupported');
+    if (typeof value.transactionId !== 'string' || !TRANSACTION_ID.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');
+    if (typeof value.prHeadSha !== 'string' || !SHA40.test(value.prHeadSha))
+        return invalid('prHeadSha is invalid');
+    if (typeof value.evidenceDigest !== 'string' || !SHA64.test(value.evidenceDigest))
+        return invalid('evidenceDigest is invalid');
+    if (!isRecord(value.summaryPreimage))
+        return invalid('summaryPreimage is invalid');
+    const preimage = value.summaryPreimage;
+    const preimageKeyError = exactKeys(preimage, ['commentId', 'body', 'digest'], 'summaryPreimage');
+    if (preimageKeyError)
+        return invalid(preimageKeyError);
+    if (preimage.commentId !== null && typeof preimage.commentId !== 'number' && typeof preimage.commentId !== 'string')
+        return invalid('summaryPreimage.commentId is invalid');
+    if (typeof preimage.body !== 'string' || typeof preimage.digest !== 'string' || !SHA64.test(preimage.digest) || summaryPreimageDigest(preimage.body) !== preimage.digest)
+        return invalid('summaryPreimage digest is invalid');
+    for (const field of ['pendingSummaryDigest', 'finalSummaryDigest'])
+        if (typeof value[field] !== 'string' || !SHA64.test(value[field]))
+            return invalid(`${field} is invalid`);
+    if (typeof value.artifact !== 'string' || !ARTIFACT.test(value.artifact))
+        return invalid('artifact is invalid');
+    if (!['prepared', 'summary-staged', 'receipt-committed', 'final-promotion-in-progress', 'committed', 'aborted', 'recovery-required'].includes(value.phase))
+        return invalid('phase is invalid');
+    if (value.committedReceipt !== null && (typeof value.committedReceipt !== 'string' || !SHA64.test(value.committedReceipt)))
+        return invalid('committedReceipt is invalid');
+    if (typeof value.eventAppended !== 'boolean' || typeof value.postWriteVerified !== 'boolean')
+        return invalid('transaction completion flags are invalid');
+    const attempt = value.attempt;
+    if (!Number.isSafeInteger(attempt) || attempt < 1)
+        return invalid('attempt is invalid');
+    if (!validTimestamp(value.createdAt) || !validTimestamp(value.updatedAt))
+        return invalid('transaction timestamps are invalid');
+    if (value.error !== null && (typeof value.error !== 'string' || !value.error || /[\r\n]/u.test(value.error)))
+        return invalid('transaction error is invalid');
+    if (['receipt-committed', 'final-promotion-in-progress', 'committed'].includes(value.phase) && value.committedReceipt === null)
+        return invalid('receipt-backed phases require committedReceipt');
+    if (['final-promotion-in-progress', 'committed'].includes(value.phase) && !value.eventAppended)
+        return invalid('final promotion requires an appended completion event');
+    if (value.phase === 'committed' && !value.postWriteVerified)
+        return invalid('committed phase requires post-write verification');
+    const transaction = value;
+    if (expected && Object.entries(expected).some(([key, expectedValue]) => expectedValue !== undefined && transaction[key] !== expectedValue)) {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_IDENTITY_MISMATCH', message: 'transaction identity does not match the expected operation' } };
+    }
+    return { ok: true, value: transaction };
+}
+function createManualValidationTransaction(input) {
+    const transaction = {
+        schema: MANUAL_VALIDATION_TRANSACTION_SCHEMA,
+        version: MANUAL_VALIDATION_TRANSACTION_VERSION,
+        transactionId: input.transactionId ?? `mv-${randomUUID()}`,
+        taskId: input.taskId,
+        prNumber: input.prNumber,
+        prHeadSha: input.prHeadSha,
+        evidenceDigest: input.evidenceDigest,
+        summaryPreimage: input.summaryPreimage,
+        pendingSummaryDigest: input.pendingSummaryDigest,
+        finalSummaryDigest: input.finalSummaryDigest,
+        artifact: input.artifact,
+        phase: 'prepared',
+        committedReceipt: null,
+        eventAppended: false,
+        attempt: input.attempt,
+        postWriteVerified: false,
+        createdAt: input.createdAt,
+        updatedAt: input.updatedAt,
+        error: null
+    };
+    const checked = validateManualValidationTransaction(transaction);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    return checked.value;
+}
+const allowedTransitions = {
+    prepared: ['prepared', 'summary-staged', 'aborted', 'recovery-required'],
+    'summary-staged': ['summary-staged', 'receipt-committed', 'aborted', 'recovery-required'],
+    'receipt-committed': ['receipt-committed', 'final-promotion-in-progress', 'aborted', 'recovery-required'],
+    'final-promotion-in-progress': ['final-promotion-in-progress', 'committed', 'aborted', 'recovery-required'],
+    committed: ['committed'],
+    aborted: ['aborted', 'prepared'],
+    'recovery-required': ['recovery-required', 'prepared']
+};
+function transitionManualValidationTransaction(current, phase, patch = {}) {
+    if (!allowedTransitions[current.phase].includes(phase))
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: `cannot transition from ${current.phase} to ${phase}` } };
+    if (phase === 'final-promotion-in-progress' && (!current.eventAppended && patch.eventAppended !== true))
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'final promotion requires an appended completion event' } };
+    const next = {
+        ...current,
+        phase,
+        committedReceipt: patch.committedReceipt !== undefined ? patch.committedReceipt : current.committedReceipt,
+        eventAppended: patch.eventAppended ?? current.eventAppended,
+        postWriteVerified: patch.postWriteVerified ?? current.postWriteVerified,
+        attempt: patch.attempt ?? current.attempt,
+        error: patch.error !== undefined ? patch.error : current.error,
+        updatedAt: patch.updatedAt ?? new Date().toISOString()
+    };
+    const checked = validateManualValidationTransaction(next);
+    if (!checked.ok)
+        return checked;
+    return checked;
+}
+function retryManualValidationTransaction(current, now = new Date().toISOString()) {
+    if (!['aborted', 'recovery-required'].includes(current.phase))
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'only aborted or recovery-required transactions can be retried' } };
+    return transitionManualValidationTransaction(current, 'prepared', {
+        updatedAt: now,
+        error: null,
+        committedReceipt: null,
+        eventAppended: false,
+        postWriteVerified: false,
+        attempt: current.attempt + 1
+    });
+}
+function manualValidationTransactionPath(taskDir) {
+    return path.join(taskDir, '.manual-validation', 'transaction.json');
+}
+function manualValidationGenerationPaths(taskDir, transaction) {
+    const stateDir = path.join(taskDir, '.manual-validation');
+    const historyDir = path.join(stateDir, 'history');
+    return {
+        receipt: {
+            current: path.join(stateDir, 'receipt.json'),
+            history: path.join(historyDir, `receipt-${transaction.transactionId}-attempt-${transaction.attempt}.json`)
+        },
+        transaction: {
+            current: manualValidationTransactionPath(taskDir),
+            history: path.join(historyDir, `transaction-${transaction.transactionId}-attempt-${transaction.attempt}.json`)
+        }
+    };
+}
+function readReceiptAt(file, transaction) {
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 'missing';
+        throw new Error(`manual-validation receipt is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const checked = validateManualValidationReceipt(value, {
+        transactionId: transaction.transactionId,
+        taskId: transaction.taskId,
+        prNumber: transaction.prNumber,
+        prHeadSha: transaction.prHeadSha,
+        evidenceDigest: transaction.evidenceDigest,
+        artifact: transaction.artifact
+    });
+    if (!checked.ok)
+        throw new Error(`manual-validation receipt is invalid: ${checked.error.message}`);
+    if (transaction.committedReceipt !== null && checked.value.receiptDigest !== transaction.committedReceipt) {
+        throw new Error('manual-validation receipt does not match the committed transaction');
+    }
+    return 'valid';
+}
+function validateManualValidationGenerationArchive(taskDir, transaction, requireReceipt = false) {
+    const paths = manualValidationGenerationPaths(taskDir, transaction);
+    const currentTransaction = fs.existsSync(paths.transaction.current);
+    const archivedTransaction = fs.existsSync(paths.transaction.history);
+    if (currentTransaction && archivedTransaction)
+        throw new Error(`manual-validation archive has conflicting transaction files for ${transaction.transactionId}`);
+    if (!currentTransaction && !archivedTransaction)
+        throw new Error(`manual-validation archive source is missing: ${paths.transaction.current}`);
+    const currentReceipt = requireReceipt
+        ? readReceiptAt(paths.receipt.current, transaction)
+        : (fs.existsSync(paths.receipt.current) ? 'valid' : 'missing');
+    const archivedReceipt = requireReceipt
+        ? readReceiptAt(paths.receipt.history, transaction)
+        : (fs.existsSync(paths.receipt.history) ? 'valid' : 'missing');
+    if (requireReceipt && currentReceipt === 'missing' && archivedReceipt === 'missing') {
+        throw new Error(`manual-validation receipt is missing for transaction ${transaction.transactionId}`);
+    }
+    if (currentReceipt === 'valid' && archivedReceipt === 'valid') {
+        throw new Error(`manual-validation archive has conflicting receipt files for ${transaction.transactionId}`);
+    }
+}
+function archiveManualValidationGeneration(taskDir, transaction, requireReceipt = false, options = {}) {
+    const paths = manualValidationGenerationPaths(taskDir, transaction);
+    validateManualValidationGenerationArchive(taskDir, transaction, requireReceipt);
+    fs.mkdirSync(path.dirname(paths.receipt.history), { recursive: true });
+    const move = (source, target, required) => {
+        if (!fs.existsSync(source)) {
+            if (fs.existsSync(target) || !required)
+                return;
+            throw new Error(`manual-validation archive source is missing: ${source}`);
+        }
+        if (fs.existsSync(target))
+            throw new Error(`manual-validation archive target already exists: ${target}`);
+        fs.renameSync(source, target);
+    };
+    move(paths.receipt.current, paths.receipt.history, requireReceipt);
+    options.afterReceiptMove?.();
+    move(paths.transaction.current, paths.transaction.history, true);
+}
+function writeManualValidationTransactionAtomic(taskDir, transaction) {
+    const checked = validateManualValidationTransaction(transaction);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    const target = manualValidationTransactionPath(taskDir);
+    return writeJsonAtomic(target, transaction);
+}
+function readManualValidationTransaction(taskDir, expected) {
+    const file = manualValidationTransactionPath(taskDir);
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        return { ok: false, error: { code: error.code === 'ENOENT' ? 'MANUAL_VALIDATION_TRANSACTION_MISSING' : 'MANUAL_VALIDATION_TRANSACTION_INVALID', message: error instanceof Error ? error.message : String(error) } };
+    }
+    return validateManualValidationTransaction(value, expected);
+}
+export { MANUAL_VALIDATION_TRANSACTION_SCHEMA, MANUAL_VALIDATION_TRANSACTION_VERSION, archiveManualValidationGeneration, createManualValidationTransaction, manualValidationTransactionPath, validateManualValidationGenerationArchive, readManualValidationTransaction, retryManualValidationTransaction, summaryPreimageDigest, transitionManualValidationTransaction, validateManualValidationTransaction, writeManualValidationTransactionAtomic };
+//# sourceMappingURL=manual-validation-transaction.js.map

package/dist/lib/task/markdown.js

@@ -0,0 +1,47 @@
+const HEADING = /^ {0,3}(#{1,6})[ \t]+(.+?)\s*$/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})\s*$/;
+const ANCHOR = /^\s*<a\s+id=(['"])([^'"]+)\1\s*><\/a>\s*$/;
+function sourceLines(content) {
+    const lines = [];
+    let start = 0;
+    while (start < content.length) {
+        const newline = content.indexOf('\n', start);
+        const end = newline === -1 ? content.length : newline;
+        lines.push({ start, end, text: content.slice(start, end).replace(/\r$/, '') });
+        start = newline === -1 ? content.length : newline + 1;
+    }
+    return lines;
+}
+function scanVisibleMarkdown(content) {
+    const lines = sourceLines(content);
+    const visible = [];
+    const headings = [];
+    const anchors = [];
+    let fence = null;
+    for (const line of lines) {
+        if (fence) {
+            const close = line.text.match(FENCE_CLOSE);
+            if (close && close[1][0] === fence.character && close[1].length >= fence.length)
+                fence = null;
+            continue;
+        }
+        const open = line.text.match(FENCE_OPEN);
+        const marker = open?.[1];
+        const info = open?.[2] ?? '';
+        if (marker && !(marker[0] === '`' && info.includes('`'))) {
+            fence = { character: marker[0], length: marker.length };
+            continue;
+        }
+        visible.push(line);
+        const heading = line.text.match(HEADING);
+        if (heading)
+            headings.push({ ...line, level: heading[1].length, text: heading[2].trim() });
+        const anchor = line.text.match(ANCHOR);
+        if (anchor)
+            anchors.push({ ...line, id: anchor[2] });
+    }
+    return { lines: visible, headings, anchors, hasUnclosedFence: fence !== null };
+}
+export { scanVisibleMarkdown };
+//# sourceMappingURL=markdown.js.map