@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/dist/lib/task/artifact-operations.js

@@ -0,0 +1,474 @@
+import fs from 'node:fs';
+import { parseArtifactName } from './artifact-name.js';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { readStableFileSync } from '../host-control/secure-fs.js';
+import { scanVisibleMarkdown } from './markdown.js';
+import { hasOpenArtifactRound } from './artifact-lifecycle.js';
+import { readArtifactRepairIntent } from './artifact-repair-intent.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { getArtifactSchema, renderArtifactSkeleton } from './artifact-schema.js';
+import { withTaskExecutionLock } from './task-execution-lock.js';
+function sha256Content(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function lineNumber(content, offset) {
+    return content.slice(0, offset).split('\n').length;
+}
+function markerPattern(marker) {
+    return new RegExp(`<!--\\s*${escapeRegExp(marker)}\\s*-->`);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function markerEntries(content, scanned) {
+    const entries = [];
+    for (const line of scanned.lines) {
+        const match = line.text.match(/<!--\s*(artifact-section:[^\s>]+)\s*-->/g);
+        if (!match)
+            continue;
+        for (const raw of match) {
+            const marker = raw.match(/artifact-section:[^\s>]+/)[0];
+            const offset = line.text.indexOf(raw);
+            entries.push({
+                marker,
+                start: line.start + offset,
+                end: line.start + offset + raw.length,
+                line: lineNumber(content, line.start),
+                standalone: line.text.trim() === raw
+            });
+        }
+    }
+    return entries;
+}
+function sectionBodyBounds(content, heading, scanned) {
+    const next = scanned.headings.find((candidate) => candidate.start > heading.start && candidate.level <= 2);
+    return { start: heading.end, end: next?.start ?? content.length };
+}
+function stripHtmlComments(content) {
+    let result = '';
+    let cursor = 0;
+    while (cursor < content.length) {
+        const start = content.indexOf('<!--', cursor);
+        if (start < 0)
+            return result + content.slice(cursor);
+        result += content.slice(cursor, start);
+        const end = content.indexOf('-->', start + 4);
+        if (end < 0)
+            return result;
+        cursor = end + 3;
+    }
+    return result;
+}
+function diagnostic(code, message, sectionId, line, repairable = false, operation) {
+    return {
+        code, message, sectionId, line, repairable,
+        ...(operation ? { operation } : {})
+    };
+}
+function sectionHeadings(schema, section) {
+    return [section.headings.zh, section.headings.en];
+}
+function createHeadingRepair(content, section, heading) {
+    const to = heading.text.slice(0, -1);
+    return {
+        kind: 'replace-line',
+        sectionId: section.id,
+        line: lineNumber(content, heading.start),
+        from: heading.text,
+        to,
+        start: heading.start,
+        end: heading.end
+    };
+}
+function createSectionInsertionRepair(content, section, marker, locale) {
+    return {
+        kind: 'insert-section',
+        sectionId: section.id,
+        line: marker.line,
+        from: '',
+        to: `## ${section.headings[locale === 'en' ? 'en' : 'zh']}\n`,
+        start: marker.start,
+        end: marker.start
+    };
+}
+function applyRepairOperation(content, operation) {
+    if (operation.start < 0 || operation.end < operation.start || operation.end > content.length)
+        return null;
+    if (operation.kind === 'insert-section') {
+        if (operation.from !== '' || operation.start !== operation.end || !operation.to)
+            return null;
+        return `${content.slice(0, operation.start)}${operation.to}${content.slice(operation.end)}`;
+    }
+    const raw = content.slice(operation.start, operation.end);
+    const offset = raw.indexOf(operation.from);
+    if (!operation.from || offset < 0 || raw.indexOf(operation.from, offset + operation.from.length) >= 0)
+        return null;
+    return `${content.slice(0, operation.start)}${raw.slice(0, offset)}${operation.to}${raw.slice(offset + operation.from.length)}${content.slice(operation.end)}`;
+}
+function canonicalContent(content, operation = null) {
+    let normalized = content;
+    if (operation) {
+        normalized = applyRepairOperation(normalized, operation) ?? normalized;
+    }
+    normalized = normalized.replace(/\r\n/g, '\n');
+    normalized = normalized.replace(/^<!--\s*artifact-context:[^\n]+-->\s*\n?/gm, '');
+    normalized = normalized.replace(/^\s*<!--\s*artifact-section:[^\n]+-->\s*\n?/gm, '');
+    normalized = normalized.replace(/^\s*<!--\s*artifact-slot:empty\s*-->\s*\n?/gm, '');
+    return normalized;
+}
+function canonicalSemanticDigest(content, operation = null) {
+    return sha256Content(canonicalContent(content, operation));
+}
+function inspectArtifactStructure(content, schema) {
+    const diagnostics = [];
+    const scanned = scanVisibleMarkdown(content);
+    const repairCandidates = [];
+    if (!content.trim())
+        diagnostics.push(diagnostic('ARTIFACT_EMPTY', 'artifact is empty', null, null));
+    if (scanned.hasUnclosedFence)
+        diagnostics.push(diagnostic('ARTIFACT_UNCLOSED_FENCE', 'artifact contains an unclosed Markdown fence', null, null));
+    const headingsBySection = new Map();
+    for (const section of schema.sections) {
+        const aliases = sectionHeadings(schema, section);
+        const exact = scanned.headings.filter((heading) => heading.level === 2 && aliases.includes(heading.text));
+        const punctuated = scanned.headings.filter((heading) => heading.level === 2 && aliases.some((alias) => heading.text === `${alias}:` || heading.text === `${alias}：`));
+        headingsBySection.set(section.id, exact.length === 0 && punctuated.length === 1 ? punctuated : exact);
+        if (exact.length > 1 || punctuated.length > 0 && exact.length > 0 || punctuated.length > 1) {
+            const first = exact[1] ?? punctuated[0] ?? exact[0];
+            diagnostics.push(diagnostic('ARTIFACT_DUPLICATE_SECTION', `required section '${aliases[0]}' is duplicated or has an ambiguous punctuation variant`, section.id, first ? lineNumber(content, first.start) : null));
+        }
+        else if (exact.length === 0 && punctuated.length === 1) {
+            repairCandidates.push(createHeadingRepair(content, section, punctuated[0]));
+        }
+        else if (exact.length === 0) {
+            diagnostics.push(diagnostic('ARTIFACT_MISSING_SECTION', `required section '${aliases[0]}' is missing`, section.id, null));
+        }
+    }
+    const markers = markerEntries(content, scanned);
+    const englishHeadings = scanned.headings.filter((heading) => heading.level === 2 && schema.sections.some((section) => section.headings.en === heading.text)).length;
+    const chineseHeadings = scanned.headings.filter((heading) => heading.level === 2 && schema.sections.some((section) => section.headings.zh === heading.text)).length;
+    const locale = englishHeadings > chineseHeadings ? 'en' : 'zh-CN';
+    for (const section of schema.sections) {
+        const matches = markers.filter((entry) => entry.marker === section.marker);
+        if (matches.length === 0) {
+            diagnostics.push(diagnostic('ARTIFACT_MARKER_MISSING', `section marker '${section.marker}' is missing`, section.id, null));
+        }
+        else if (matches.length > 1) {
+            diagnostics.push(diagnostic('ARTIFACT_MARKER_DUPLICATE', `section marker '${section.marker}' is duplicated`, section.id, matches[1].line));
+        }
+        const marker = matches[0];
+        const heading = headingsBySection.get(section.id)?.[0];
+        if (marker && !marker.standalone) {
+            diagnostics.push(diagnostic('ARTIFACT_MARKER_MISMATCH', `section marker '${section.marker}' must occupy its own visible line`, section.id, marker.line));
+        }
+        if (marker && heading) {
+            const bounds = sectionBodyBounds(content, heading, scanned);
+            if (marker.start < bounds.start || marker.start >= bounds.end) {
+                diagnostics.push(diagnostic('ARTIFACT_MARKER_MISMATCH', `section marker '${section.marker}' is outside its section`, section.id, marker.line));
+            }
+            const body = stripHtmlComments(content.slice(bounds.start, bounds.end)).trim();
+            if (!body)
+                diagnostics.push(diagnostic('ARTIFACT_EMPTY_SECTION', `section '${section.headings.zh}' has no semantic body`, section.id, lineNumber(content, heading.start)));
+        }
+        if (marker && !heading && marker.standalone) {
+            const nextHeading = scanned.headings.find((candidate) => candidate.start > marker.start && candidate.level <= 2);
+            const body = stripHtmlComments(content.slice(marker.end, nextHeading?.start ?? content.length)).trim();
+            if (body && repairCandidates.length === 0) {
+                repairCandidates.push(createSectionInsertionRepair(content, section, marker, locale));
+            }
+            else if (!body) {
+                diagnostics.push(diagnostic('ARTIFACT_EMPTY_SECTION', `section '${section.headings.zh}' has no semantic body`, section.id, marker.line));
+            }
+        }
+    }
+    for (const marker of markers) {
+        if (!schema.sections.some((section) => markerPattern(section.marker).test(`<!-- ${marker.marker} -->`))) {
+            diagnostics.push(diagnostic('ARTIFACT_MARKER_MISMATCH', `unknown section marker '${marker.marker}'`, null, marker.line));
+        }
+    }
+    for (const candidate of repairCandidates) {
+        if (candidate.kind === 'replace-line') {
+            diagnostics.push(diagnostic('ARTIFACT_HEADING_TRAILING_PUNCTUATION', `visible required H2 '${candidate.from}' may be normalized to '${candidate.to}'`, candidate.sectionId, candidate.line, true, candidate));
+            continue;
+        }
+        const missing = diagnostics.findIndex((item) => item.code === 'ARTIFACT_MISSING_SECTION' && item.sectionId === candidate.sectionId);
+        if (missing >= 0) {
+            const section = schema.sections.find((item) => item.id === candidate.sectionId);
+            diagnostics.splice(missing, 1, diagnostic('ARTIFACT_MISSING_SECTION', `required section '${section.headings.zh}' is missing and can be inserted at its unique marker`, candidate.sectionId, candidate.line, true, candidate));
+        }
+    }
+    const orderedHeadings = schema.sections.flatMap((section) => {
+        const heading = headingsBySection.get(section.id)?.[0];
+        return heading ? [{ section, start: heading.start }] : [];
+    });
+    if (orderedHeadings.some((item, index) => index > 0 && item.start <= orderedHeadings[index - 1].start)) {
+        diagnostics.push(diagnostic('ARTIFACT_SECTION_ORDER_INVALID', 'required sections are not in schema order', null, null));
+    }
+    const orderedMarkers = schema.sections.flatMap((section) => {
+        const marker = markers.find((entry) => entry.marker === section.marker);
+        return marker ? [{ section, start: marker.start }] : [];
+    });
+    if (orderedMarkers.some((item, index) => index > 0 && item.start <= orderedMarkers[index - 1].start)) {
+        diagnostics.push(diagnostic('ARTIFACT_SECTION_ORDER_INVALID', 'section markers are not in schema order', null, null));
+    }
+    const repair = repairCandidates.length === 1 && (diagnostics.length === 0 ||
+        (diagnostics.length === 1 && diagnostics[0]?.operation?.kind === repairCandidates[0]?.kind)) ? repairCandidates[0] : null;
+    return {
+        ok: diagnostics.length === 0,
+        family: schema.family,
+        semanticDigest: canonicalSemanticDigest(content, repair),
+        diagnostics,
+        repair
+    };
+}
+function inspectArtifactPatterns(content, schema) {
+    const diagnostics = schema.requiredPatterns
+        .filter((pattern) => !new RegExp(pattern, 'm').test(content))
+        .map((pattern) => diagnostic('ARTIFACT_REQUIRED_PATTERN_MISSING', `artifact is missing required pattern '${pattern}'`, null, null));
+    return {
+        ok: diagnostics.length === 0,
+        family: schema.family,
+        semanticDigest: canonicalSemanticDigest(content),
+        diagnostics,
+        repair: null
+    };
+}
+function inspectArtifactContract(content, schema) {
+    const structure = inspectArtifactStructure(content, schema);
+    const patterns = inspectArtifactPatterns(content, schema);
+    const diagnostics = [...structure.diagnostics, ...patterns.diagnostics];
+    const repair = patterns.diagnostics.length === 0 ? structure.repair : null;
+    return {
+        ok: diagnostics.length === 0,
+        family: schema.family,
+        semanticDigest: canonicalSemanticDigest(content, repair),
+        diagnostics,
+        repair
+    };
+}
+function resultFailure(code, message) {
+    return { status: 'failed', changed: false, artifactSha256: null, semanticDigest: null, operation: null, error: { code, message } };
+}
+function resultNoOp(content) {
+    return {
+        status: 'no-op',
+        changed: false,
+        artifactSha256: sha256Content(content),
+        semanticDigest: canonicalSemanticDigest(content),
+        operation: null,
+        error: null
+    };
+}
+function validateRepairContext(request, content) {
+    const round = artifactRound(request.family, request.artifact);
+    if (round === null)
+        return { ok: false, code: 'ARTIFACT_REPAIR_CONTEXT_INVALID', message: 'artifact round is not canonical' };
+    const contextPattern = /^<!--\s*artifact-context:([^:\s]+):([^:\s]+):(\d+)\s*-->\s*$/;
+    const contexts = scanVisibleMarkdown(content).lines
+        .map((line) => line.text.trim().match(contextPattern))
+        .filter((match) => match !== null);
+    if (contexts.length !== 1
+        || contexts[0][1] !== request.taskId
+        || contexts[0][2] !== request.family
+        || Number(contexts[0][3]) !== round) {
+        return { ok: false, code: 'ARTIFACT_REPAIR_CONTEXT_INVALID', message: 'artifact context marker does not match the requested task, family, and round' };
+    }
+    let taskContent;
+    const resolved = resolveTaskRef(request.taskId, { repoRoot: request.repoRoot });
+    if (!resolved.ok)
+        return { ok: false, code: 'ARTIFACT_REPAIR_CONTEXT_INVALID', message: resolved.message };
+    try {
+        taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    }
+    catch (error) {
+        return { ok: false, code: 'ARTIFACT_REPAIR_CONTEXT_INVALID', message: `cannot read task lifecycle context: ${String(error)}` };
+    }
+    if (!hasOpenArtifactRound(taskContent, request.family, round)) {
+        return { ok: false, code: 'ARTIFACT_REPAIR_CONTEXT_INVALID', message: `artifact '${request.artifact}' does not have exactly one matching open started lifecycle event` };
+    }
+    let intent;
+    try {
+        intent = readArtifactRepairIntent(request.repoRoot, request.taskId, request.family, request.artifact);
+    }
+    catch (error) {
+        return { ok: false, code: 'ARTIFACT_REPAIR_PROVENANCE_INVALID', message: String(error) };
+    }
+    if (!intent || intent.state !== 'awaiting-repair') {
+        return { ok: false, code: 'ARTIFACT_REPAIR_PROVENANCE_INVALID', message: 'artifact has no awaiting-repair finalization provenance' };
+    }
+    if (intent.artifactSha256 !== request.expectedSha256 || intent.semanticDigest !== request.expectedSemanticDigest) {
+        return { ok: false, code: 'ARTIFACT_REPAIR_PROVENANCE_INVALID', message: 'repair request does not match the current finalization provenance' };
+    }
+    return { ok: true };
+}
+function artifactRound(family, artifact) {
+    const identity = parseArtifactName(artifact);
+    return identity?.family === family ? identity.round : null;
+}
+function validateTarget(taskDir, family, artifact) {
+    if (path.basename(artifact) !== artifact || artifactRound(family, artifact) === null || !artifact.endsWith('.md'))
+        return resultFailure('ARTIFACT_REPAIR_TARGET_INVALID', 'artifact must be a canonical top-level Markdown file');
+    if (!/^TASK-\d{8}-\d{6}$/.test(path.basename(path.resolve(taskDir))))
+        return resultFailure('ARTIFACT_REPAIR_TARGET_INVALID', 'target directory is not a task directory');
+    const target = path.join(taskDir, artifact);
+    if (path.dirname(path.resolve(target)) !== path.resolve(taskDir))
+        return resultFailure('ARTIFACT_REPAIR_TARGET_INVALID', 'artifact must be inside the current task directory');
+    let stat;
+    try {
+        stat = fs.lstatSync(target);
+    }
+    catch (error) {
+        return resultFailure('ARTIFACT_REPAIR_TARGET_INVALID', `artifact cannot be read: ${String(error)}`);
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        return resultFailure('ARTIFACT_REPAIR_TARGET_INVALID', 'artifact is not a regular file');
+    try {
+        fs.accessSync(target, fs.constants.R_OK | fs.constants.W_OK);
+    }
+    catch (error) {
+        return resultFailure('ARTIFACT_REPAIR_TARGET_INVALID', `artifact is not readable and writable: ${String(error)}`);
+    }
+    return { path: target };
+}
+function applyRepairUnlocked(request) {
+    const schema = getArtifactSchema(request.family);
+    if (!schema)
+        return resultFailure('ARTIFACT_FAMILY_UNKNOWN', `unknown artifact family '${request.family}'`);
+    const target = validateTarget(request.taskDir, request.family, request.artifact);
+    if ('status' in target)
+        return target;
+    let content;
+    try {
+        content = readStableFileSync(target.path, { maxBytes: 1024 * 1024 }).bytes.toString('utf8');
+    }
+    catch (error) {
+        return resultFailure('ARTIFACT_REPAIR_TARGET_INVALID', String(error));
+    }
+    const actualSha256 = sha256Content(content);
+    if (actualSha256 !== request.expectedSha256)
+        return resultFailure('ARTIFACT_REPAIR_BASELINE_MISMATCH', 'artifact SHA-256 does not match the expected repair baseline');
+    const context = validateRepairContext(request, content);
+    if (!context.ok)
+        return resultFailure(context.code, context.message);
+    const inspection = inspectArtifactStructure(content, schema);
+    if (!inspection.repair || inspection.diagnostics.length !== 1) {
+        return resultFailure('ARTIFACT_REPAIR_UNSAFE', inspection.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ') || 'no deterministic structural repair is available');
+    }
+    if (inspection.repair.kind !== request.operation.kind
+        || inspection.repair.sectionId !== request.operation.sectionId
+        || inspection.repair.from !== request.operation.from
+        || inspection.repair.to !== request.operation.to
+        || inspection.repair.start !== request.operation.start
+        || inspection.repair.end !== request.operation.end) {
+        return resultFailure('ARTIFACT_REPAIR_OPERATION_MISMATCH', 'repair operation does not match the current artifact structure');
+    }
+    if (inspection.semanticDigest !== request.expectedSemanticDigest)
+        return resultFailure('ARTIFACT_REPAIR_BASELINE_MISMATCH', 'artifact semantic digest does not match the expected repair baseline');
+    const transformed = applyRepairOperation(content, inspection.repair);
+    if (transformed === null)
+        return resultFailure('ARTIFACT_REPAIR_OPERATION_MISMATCH', 'repair operation does not match the current artifact bytes');
+    if (transformed === content)
+        return resultFailure('ARTIFACT_REPAIR_NO_PROGRESS', 'repair operation produced no byte change');
+    const tempPath = path.join(request.taskDir, `.${request.artifact}.repair-${process.pid}-${Date.now()}.tmp`);
+    let mode = 0o600;
+    try {
+        mode = fs.statSync(target.path).mode & 0o777;
+        fs.writeFileSync(tempPath, transformed, { encoding: 'utf8', mode, flag: 'wx' });
+        const currentStat = fs.lstatSync(target.path);
+        if (currentStat.isSymbolicLink() || !currentStat.isFile() || readStableFileSync(target.path, { maxBytes: 1024 * 1024 }).sha256 !== actualSha256) {
+            fs.unlinkSync(tempPath);
+            return resultFailure('ARTIFACT_REPAIR_CONFLICT', 'artifact changed or was replaced during repair');
+        }
+        fs.renameSync(tempPath, target.path);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tempPath);
+        }
+        catch { /* preserve primary error */ }
+        return resultFailure('ARTIFACT_REPAIR_WRITE_FAILED', String(error));
+    }
+    return {
+        status: 'applied',
+        changed: true,
+        artifactSha256: sha256Content(transformed),
+        semanticDigest: canonicalSemanticDigest(transformed),
+        operation: inspection.repair,
+        error: null
+    };
+}
+function applyArtifactRepair(request) {
+    try {
+        return withTaskExecutionLock(request.repoRoot, request.taskId, 'task-artifact.repair', () => applyRepairUnlocked(request));
+    }
+    catch (error) {
+        return resultFailure('ARTIFACT_REPAIR_LOCK_FAILED', String(error));
+    }
+}
+function initializeArtifactSkeleton(request) {
+    const schema = getArtifactSchema(request.family);
+    if (!schema)
+        return resultFailure('ARTIFACT_FAMILY_UNKNOWN', `unknown artifact family '${request.family}'`);
+    if (artifactRound(request.family, request.artifact) === null)
+        return resultFailure('ARTIFACT_INIT_TARGET_INVALID', 'artifact must be a canonical top-level Markdown file');
+    if (!/^TASK-\d{8}-\d{6}$/.test(path.basename(path.resolve(request.taskDir))) || path.basename(path.resolve(request.taskDir)) !== request.taskId)
+        return resultFailure('ARTIFACT_INIT_TARGET_INVALID', 'target directory is not the requested task directory');
+    const target = path.join(request.taskDir, request.artifact);
+    if (path.dirname(path.resolve(target)) !== path.resolve(request.taskDir))
+        return resultFailure('ARTIFACT_INIT_TARGET_INVALID', 'artifact must be inside the current task directory');
+    try {
+        return withTaskExecutionLock(request.repoRoot, request.taskId, 'task-artifact.init', () => {
+            try {
+                const existing = fs.lstatSync(target);
+                if (existing.isSymbolicLink() || !existing.isFile())
+                    return resultFailure('ARTIFACT_INIT_TARGET_INVALID', 'artifact target is not a regular file');
+                return resultNoOp(readStableFileSync(target, { maxBytes: 1024 * 1024 }).bytes.toString('utf8'));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    return resultFailure('ARTIFACT_INIT_TARGET_INVALID', String(error));
+            }
+            const content = renderArtifactSkeleton({
+                taskId: request.taskId,
+                family: request.family,
+                artifact: request.artifact,
+                ...(request.locale ? { locale: request.locale } : {})
+            });
+            const tempPath = path.join(request.taskDir, `.${request.artifact}.init-${process.pid}-${Date.now()}.tmp`);
+            try {
+                fs.writeFileSync(tempPath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+                try {
+                    fs.lstatSync(target);
+                    fs.unlinkSync(tempPath);
+                    return resultFailure('ARTIFACT_INIT_TARGET_EXISTS', 'artifact was created concurrently');
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                fs.renameSync(tempPath, target);
+            }
+            catch (error) {
+                try {
+                    fs.unlinkSync(tempPath);
+                }
+                catch { /* preserve primary error */ }
+                return resultFailure('ARTIFACT_INIT_WRITE_FAILED', String(error));
+            }
+            return {
+                status: 'applied',
+                changed: true,
+                artifactSha256: sha256Content(content),
+                semanticDigest: canonicalSemanticDigest(content),
+                operation: null,
+                error: null
+            };
+        });
+    }
+    catch (error) {
+        return resultFailure('ARTIFACT_INIT_LOCK_FAILED', String(error));
+    }
+}
+export { applyArtifactRepair, canonicalSemanticDigest, initializeArtifactSkeleton, inspectArtifactContract, inspectArtifactPatterns, inspectArtifactStructure, sha256Content };
+//# sourceMappingURL=artifact-operations.js.map

package/dist/lib/task/artifact-receipts.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { createHash } from 'node:crypto';
+import { parseArtifactName } from './artifact-name.js';
 import { extractSection, findSectionHeading, parseTable } from './sections.js';
 const RECEIPT_SECTION_ALIASES = ['产物生命周期收据', 'Artifact Lifecycle Receipts'];
 const RECEIPT_COLUMNS = ['event', 'output', 'input', 'input_sha256', 'completed_at'];
@@ -10,7 +11,6 @@ const RECEIPT_EVENTS = new Set([
     'code.completed'
 ]);
 const SHA256_RE = /^[a-f0-9]{64}$/;
-const ARTIFACT_NAME_RE = /^(analysis|review-analysis|plan|review-plan|code|review-code|manual-validation|validation-run|pr-review)(?:-r([2-9]|[1-9]\d+))?\.md$/;
 const RECEIPT_SHAPES = {
     'review-analysis.completed': { output: 'review-analysis', input: 'analysis' },
     'review-plan.completed': { output: 'review-plan', input: 'plan' },
@@ -30,21 +30,9 @@ function sha256Bytes(value) {
 function sha256File(filePath) {
     return sha256Bytes(fs.readFileSync(filePath));
 }
-function parseReceiptArtifactName(name) {
-    const match = ARTIFACT_NAME_RE.exec(name);
-    if (!match)
-        return null;
-    const roundText = match[2];
-    if (roundText !== undefined) {
-        const round = Number(roundText);
-        if (!Number.isSafeInteger(round) || String(round) !== roundText)
-            return null;
-    }
-    return { family: match[1] };
-}
 function validateReceiptShape(event, output, input) {
-    const outputIdentity = parseReceiptArtifactName(output);
-    const inputIdentity = parseReceiptArtifactName(input);
+    const outputIdentity = parseArtifactName(output);
+    const inputIdentity = parseArtifactName(input);
     if (!outputIdentity || !inputIdentity)
         throw new ArtifactReceiptError(`receipt artifact identity is invalid: ${output} -> ${input}`);
     const shape = RECEIPT_SHAPES[event];

package/dist/lib/task/artifact-repair-intent.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+function intentRoot(repoRoot) {
+    return path.join(repoRoot, '.agents', 'workspace', '.local-artifact-finalization-intents');
+}
+function intentPath(repoRoot, taskId, family, artifact) {
+    return path.join(intentRoot(repoRoot), `${taskId}-${family}-${artifact}.json`);
+}
+function validDigest(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+}
+function validTaskId(value) {
+    return typeof value === 'string' && /^TASK-\d{8}-\d{6}$/u.test(value);
+}
+function exactKeys(value, keys) {
+    return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+export function isArtifactRepairIntent(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const intent = value;
+    return exactKeys(intent, [
+        'artifact', 'artifactSha256', 'authorityDigest', 'baselineSemanticDigest', 'createdAt',
+        'family', 'phase', 'recoveryOperationId', 'requestId', 'semanticDigest', 'state',
+        'taskId', 'updatedAt', 'version'
+    ])
+        && intent.version === 2
+        && validTaskId(intent.taskId)
+        && typeof intent.family === 'string'
+        && ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(intent.family)
+        && typeof intent.artifact === 'string' && intent.artifact.length > 0
+        && ['awaiting-repair', 'finalize-ready', 'commit-started', 'passed', 'consumed'].includes(String(intent.state))
+        && (intent.baselineSemanticDigest === null || validDigest(intent.baselineSemanticDigest))
+        && validDigest(intent.artifactSha256)
+        && validDigest(intent.semanticDigest)
+        && (intent.recoveryOperationId === null || (typeof intent.recoveryOperationId === 'string' && /^[a-f0-9-]{16,64}$/u.test(intent.recoveryOperationId)))
+        && (intent.phase === null || ['orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'].includes(String(intent.phase)))
+        && (intent.authorityDigest === null || validDigest(intent.authorityDigest))
+        && typeof intent.requestId === 'string' && intent.requestId.length > 0 && !/[\r\n]/u.test(intent.requestId)
+        && Number.isSafeInteger(intent.createdAt) && Number.isSafeInteger(intent.updatedAt)
+        && (intent.state === 'awaiting-repair' ? intent.baselineSemanticDigest === intent.semanticDigest : true);
+}
+function readArtifactRepairIntent(repoRoot, taskId, family, artifact) {
+    const target = intentPath(repoRoot, taskId, family, artifact);
+    if (!fs.existsSync(target))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(target, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`);
+    }
+    if (!isArtifactRepairIntent(value) || value.taskId !== taskId || value.family !== family || value.artifact !== artifact) {
+        throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+    }
+    return value;
+}
+export function writeArtifactRepairIntent(repoRoot, value, options = {}) {
+    if (!isArtifactRepairIntent(value))
+        throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+    const directory = intentRoot(repoRoot);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const target = intentPath(repoRoot, value.taskId, value.family, value.artifact);
+    const lock = `${target}.lock`;
+    let descriptor;
+    try {
+        descriptor = fs.openSync(lock, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new Error('ARTIFACT_REPAIR_INTENT_CONFLICT: another provenance writer owns the intent');
+        }
+        throw error;
+    }
+    try {
+        const current = fs.existsSync(target)
+            ? readArtifactRepairIntent(repoRoot, value.taskId, value.family, value.artifact)
+            : null;
+        if (!isDeepStrictEqual(current, options.expected ?? null)) {
+            throw new Error('ARTIFACT_REPAIR_INTENT_CONFLICT: repair provenance changed during finalization');
+        }
+        const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+        fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        try {
+            fs.renameSync(temporary, target);
+        }
+        catch (error) {
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch { /* preserve primary error */ }
+            throw error;
+        }
+    }
+    finally {
+        fs.closeSync(descriptor);
+        try {
+            fs.unlinkSync(lock);
+        }
+        catch { /* preserve the primary result */ }
+    }
+}
+export function findArtifactRepairIntentsByOperation(repoRoot, operationId) {
+    if (!operationId || /[\r\n]/u.test(operationId)) {
+        throw new Error('ARTIFACT_REPAIR_OPERATION_INVALID: recovery operation id is invalid');
+    }
+    const directory = intentRoot(repoRoot);
+    if (!fs.existsSync(directory))
+        return Object.freeze([]);
+    return Object.freeze(fs.readdirSync(directory)
+        .filter((name) => name.endsWith('.json'))
+        .map((name) => {
+        const target = path.join(directory, name);
+        let value;
+        try {
+            value = JSON.parse(fs.readFileSync(target, 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`);
+        }
+        if (!isArtifactRepairIntent(value))
+            throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+        return value;
+    })
+        .filter((value) => value.recoveryOperationId === operationId));
+}
+export { readArtifactRepairIntent };
+//# sourceMappingURL=artifact-repair-intent.js.map