agentweaver 0.1.14 → 0.1.16

package/dist/prompts.js

@@ -10,12 +10,12 @@ function strictSchemaInstruction(outputFileVar, schemaId) {
         STRUCTURED_JSON_LANGUAGE_INSTRUCTION +
         `Canonical schema:\n${renderStructuredArtifactSchema(schemaId)}\n`);
 }
-export const PLAN_PROMPT_TEMPLATE = "Review and analyze the task in {jira_task_file}. " +
-    "Be sure to analyze additional materials from Jira attachments manifest {jira_attachments_manifest_file} and text context {jira_attachments_context_file}; if an attachment contains more detailed requirements, constraints, file lists, migration strategy, or invariants, treat the attachment as source of truth for planning alongside the Jira issue. " +
+export const PLAN_PROMPT_TEMPLATE = "Review and analyze the normalized task context in {task_context_json_file}. " +
+    "Use planning answers from {planning_answers_json_file} when they exist and treat them as structured user clarifications. " +
     "First create structured JSON artifacts - they are the source of truth for subsequent flows. " +
     "Create human-readable markdown files as detailed derivative representations of these JSON artifacts for the user, not as brief summaries. " +
     "Markdown should not influence JSON structure: first determine the correct JSON types, then build markdown as a derivative representation. " +
-    "Do not collapse specifics from the task and attachments: preserve explicit files, methods, APIs, invariants, migration steps, DB constraints, business rules, and acceptance criteria. " +
+    "Do not collapse specifics from the task context: preserve explicit files, methods, APIs, invariants, migration steps, DB constraints, business rules, acceptance criteria, and constraints. " +
     "Develop a system design for the solution and write JSON to {design_json_file}, then markdown to {design_file}. " +
     strictSchemaInstruction("{design_json_file}", "implementation-design/v1") +
     "Develop a detailed implementation plan and write JSON to {plan_json_file}, then markdown to {plan_file}. " +
@@ -24,14 +24,31 @@ export const PLAN_PROMPT_TEMPLATE = "Review and analyze the task in {jira_task_f
     strictSchemaInstruction("{qa_json_file}", "qa-plan/v1") +
     "Format markdown for design and plan comprehensively, with separate sections for Summary, Current State, Target State, Affected Code, Decisions, Migration/DB Changes, Risks, Implementation Steps, Tests, Rollout. " +
     "JSON files must be valid and contain only JSON without markdown wrapping. ";
-export const PLAN_QUESTIONS_PROMPT_TEMPLATE = "Review and analyze the task in {jira_task_file}. " +
-    "Be sure to analyze additional materials from Jira attachments manifest {jira_attachments_manifest_file} and text context {jira_attachments_context_file}; if an attachment contains more detailed requirements, constraints, file lists, migration strategy, or invariants, treat the attachment as source of truth for planning alongside the Jira issue. " +
+export const PLAN_QUESTIONS_PROMPT_TEMPLATE = "Review and analyze the normalized task context in {task_context_json_file}. " +
     "Before final planning, determine if any clarifications are needed from the user. " +
     strictSchemaInstruction("{planning_questions_json_file}", "planning-questions/v1") +
     "Ask only questions without which the design/plan could be incorrect or too speculative. " +
     "Do not ask obvious, decorative, or duplicate questions. " +
     "Usually 1-5 questions are sufficient. " +
     "The JSON file must be valid and contain only JSON without markdown wrapping. ";
+export const TASK_CONTEXT_FROM_JIRA_PROMPT_TEMPLATE = "Normalize the Jira task context into a connector-agnostic task context. " +
+    "Use Jira issue JSON {jira_task_file} as the primary source of truth. " +
+    "Also analyze Jira attachments manifest {jira_attachments_manifest_file} and attachments text context {jira_attachments_context_file}; if attachments contain more specific requirements, constraints, file lists, migration strategy, or invariants, preserve them in the normalized result. " +
+    "Write the source-of-truth JSON to {task_context_json_file}. " +
+    strictSchemaInstruction("{task_context_json_file}", "task-context/v1") +
+    "Set source_type to 'jira'. " +
+    "Write the derivative markdown version to {task_context_file}. " +
+    "Do not invent metadata that is not supported by Jira content or attachments. " +
+    "Keep JSON semantic fields in English. JSON files must contain only JSON without markdown wrapping.";
+export const TASK_CONTEXT_FROM_MANUAL_PROMPT_TEMPLATE = "Normalize the manual task input into a connector-agnostic task context. " +
+    "Use the structured user input in {task_input_file}. " +
+    "Use values.task_description as the primary source of truth and values.additional_instructions as additional context when present. " +
+    "Do not reshape the input into Jira-like fields or invent Jira metadata. " +
+    "Write the source-of-truth JSON to {task_context_json_file}. " +
+    strictSchemaInstruction("{task_context_json_file}", "task-context/v1") +
+    "Set source_type to 'manual'. " +
+    "Write the derivative markdown version to {task_context_file}. " +
+    "Keep JSON semantic fields in English. JSON files must contain only JSON without markdown wrapping.";
 export const BUG_ANALYZE_PROMPT_TEMPLATE = "Review and analyze the bug in {jira_task_file}. " +
     "First create structured JSON artifacts - they are the source of truth for subsequent flows. " +
     "Create human-readable markdown files as brief derivative representations of these JSON artifacts for the user. " +
@@ -52,28 +69,52 @@ export const MR_DESCRIPTION_PROMPT_TEMPLATE = "Review the task in {jira_task_fil
     "Prepare a very brief intent description for the merge request without implementation details, file lists, or technical details. " +
     `First write the source-of-truth JSON to {mr_description_json_file}. ${strictSchemaInstruction("{mr_description_json_file}", "mr-description/v1")}Then write the derivative markdown version to {mr_description_file}. `;
 export const IMPLEMENT_PROMPT_TEMPLATE = "Use only structured artifacts as source of truth. " +
-    "Analyze the system design {design_json_file}, implementation plan {plan_json_file}, and proceed with implementation according to the plan. " +
-    "Markdown artifacts are intended only for human reading and should not define the implementation. ";
+    "Analyze the system design {design_json_file}, implementation plan {plan_json_file}, and QA plan {qa_json_file}, then proceed with implementation according to those artifacts. " +
+    "Treat the QA plan as the source of truth for the minimum required test scenarios, edge cases, regression checks, and validation behavior that the implementation must satisfy. " +
+    "When the repository contains automated tests, add or update tests for the key scenarios from the QA plan whenever it is practical in the current codebase. " +
+    "If some QA scenarios cannot be automated in the current change, still implement the code so those scenarios are satisfied and keep them explicit in your reasoning while editing. " +
+    "Markdown artifacts such as {design_file}, {plan_file}, and {qa_file} are intended only for human reading and should not define the implementation. ";
 export const REVIEW_PROMPT_TEMPLATE = "Conduct a code review of the current changes. " +
-    "Use only structured artifacts as source of truth: the task in {jira_task_file}, design in {design_json_file}, and plan in {plan_json_file}. " +
+    "Use only structured artifacts as source of truth. " +
+    "Required planning inputs: design markdown {design_file}, design JSON {design_json_file}, plan markdown {plan_file}, and plan JSON {plan_json_file}. " +
+    "Optional task context is provided through these variables and may contain the literal value 'not provided' when absent: normalized task context JSON {task_context_json_file}, Jira task JSON {jira_task_file}, instant-task input JSON {task_input_json_file}. " +
+    "When an optional variable is 'not provided', treat that source as unavailable and do not invent details from it. " +
+    "Evaluate the current code against the available task context and the structured planning artifacts. " +
+    "Use exactly one severity per finding from this list: blocker, critical, high, medium, low, info. " +
     `First write the structured result to {review_json_file}. ${strictSchemaInstruction("{review_json_file}", "review-findings/v1")}` +
+    "Then write the derivative markdown version to {review_file}. ";
+export const DESIGN_REVIEW_PROMPT_TEMPLATE = "Conduct a structured planning critique as a specification critic, not as an implementer. " +
+    "Use structured JSON artifacts as the source of truth for semantics. " +
+    "Required planning inputs: design markdown {design_file}, design JSON {design_json_file}, implementation plan markdown {plan_file}, implementation plan JSON {plan_json_file}. " +
+    "Review the markdown files as derivative human-readable renderings of the same planning run, but do not let markdown override the structured JSON. " +
+    "Optional supplemental context is provided through these variables and may contain the literal value 'not provided' when absent: normalized task context JSON {task_context_json_file}, QA markdown {qa_file}, QA JSON {qa_json_file}, Jira task JSON {jira_task_file}, Jira attachments manifest {jira_attachments_manifest_file}, Jira attachments context {jira_attachments_context_file}, planning answers JSON {planning_answers_json_file}, instant-task input JSON {task_input_json_file}. " +
+    "When an optional variable is 'not provided', treat that source as unavailable and do not invent details from it. " +
+    "Evaluate completeness, consistency, implementation readiness, risk coverage, QA coverage, and scope discipline across the available planning artifacts and optional context. " +
+    "Identify blocking findings, major non-blocking findings, warnings, missing information, consistency check results, QA coverage gaps, and concise recommended actions. " +
+    "Use exactly one status value: approved, approved_with_warnings, or needs_revision. " +
+    "Set status to needs_revision when any blocking finding exists or when required information is missing in a way that blocks safe implementation start. " +
+    "Set status to approved_with_warnings when there are no blocking findings, but there are major findings, warnings, non-blocking missing information items, QA coverage gaps, or non-blocking consistency issues. " +
+    "Set status to approved only when there are no unresolved blocking findings, major findings, warnings, missing information items, or QA coverage gaps. " +
+    `First write the structured design review to {review_json_file}. ${strictSchemaInstruction("{review_json_file}", "design-review/v1")}` +
     "Then write the derivative markdown version to {review_file}. " +
-    "If ready_to_merge=true and there are no blockers preventing merge - create the ready-to-merge.md file.";
+    "Create ready-to-merge.md only when status is approved or approved_with_warnings. " +
+    "Do not create ready-to-merge.md when status is needs_revision.";
 export const REVIEW_PROJECT_PROMPT_TEMPLATE = "Conduct a code review of current changes in the project without Jira context. " +
     "Evaluate the quality of changes based on current code, tests, regression risks, and overall engineering quality. " +
+    "Use exactly one severity per finding from this list: blocker, critical, high, medium, low, info. " +
     `First write the structured result to {review_json_file}. ${strictSchemaInstruction("{review_json_file}", "review-findings/v1")}` +
-    "Then write the derivative markdown version to {review_file}. " +
-    "If ready_to_merge=true and there are no blockers, create the {ready_to_merge_file} file.";
+    "Then write the derivative markdown version to {review_file}. ";
 export const GITLAB_DIFF_REVIEW_PROMPT_TEMPLATE = "Conduct a code review of the GitLab merge request diff. " +
     "Use the structured diff artifact {gitlab_diff_json_file} as source of truth, and markdown {gitlab_diff_file} only as a convenient human-readable representation. " +
     "Evaluate only the changes from the diff: correctness, regression risks, missing tests, dangerous edge cases, contract violations, and maintainability. " +
+    "Use exactly one severity per finding from this list: blocker, critical, high, medium, low, info. " +
     `First write the structured result to {review_json_file}. ${strictSchemaInstruction("{review_json_file}", "review-findings/v1")}` +
-    "Then write the derivative markdown version to {review_file}. " +
-    "If ready_to_merge=true and there are no blockers, create the {ready_to_merge_file} file.";
+    "Then write the derivative markdown version to {review_file}. ";
 export const GITLAB_REVIEW_PROMPT_TEMPLATE = "Validate GitLab merge request review comments. " +
     "Use the structured GitLab review artifact {gitlab_review_json_file} as source of truth, and markdown {gitlab_review_file} only as a convenient human-readable representation. " +
     "Determine which comments are valid actionable findings that should be addressed in the current code. " +
     "Ignore comments that are obsolete, already resolved, duplicates, purely conversational, or not actionable. " +
+    "Use exactly one severity per finding from this list: blocker, critical, high, medium, low, info. " +
     "Normalize the remaining actionable findings into the review findings schema with accurate severities, concise titles, and concrete descriptions. " +
     "For each remaining finding, assess whether the complaint is fair in the current code and propose a concrete fix. " +
     `First write the structured result to {review_json_file}. ${strictSchemaInstruction("{review_json_file}", "review-findings/v1")}` +
@@ -116,6 +157,34 @@ export const COMMIT_MESSAGE_PROMPT_TEMPLATE = "Generate a commit message for the
     "3) Include task key from Jira task. " +
     "4) Commit message language: English. " +
     "5) Write JSON to {commit_message_json_file}: {\"subject\": \"...\"}.";
+export const PLAN_REVISE_PROMPT_TEMPLATE = "Revise the planning artifacts based on the design-review verdict. " +
+    "Use structured JSON artifacts as the source of truth for semantics. " +
+    "First revise the structured JSON artifacts; only after the JSON is complete and schema-valid should you write the derivative markdown files. " +
+    "Markdown must not influence JSON structure or types. " +
+    "The design-review verdict JSON {review_json_file} is the primary source of revision instructions — treat its blocking findings, major findings, and recommended actions as mandatory revision targets. " +
+    "The design-review markdown {review_file} is a derivative rendering only and must not override the structured verdict. " +
+    "Required source planning inputs: design JSON {design_json_file}, design markdown {design_file}, plan JSON {plan_json_file}, plan markdown {plan_file}. " +
+    "Optional source QA inputs (may be 'not provided'): QA JSON {qa_json_file}, QA markdown {qa_file}. " +
+    "When QA inputs are 'not provided', synthesize a new QA plan from the revised design and plan. " +
+    "Optional supplemental context (may be 'not provided'): normalized task context JSON {task_context_json_file}, Jira task JSON {jira_task_file}, Jira attachments manifest {jira_attachments_manifest_file}, Jira attachments context {jira_attachments_context_file}, planning answers JSON {planning_answers_json_file}, instant-task input JSON {task_input_json_file}. " +
+    "When an optional variable is 'not provided', treat that source as unavailable and do not invent details from it. " +
+    "For every blocking finding and major finding in the verdict, address it directly in the revised artifacts. " +
+    "Preserve all content from the original artifacts that is not directly addressed by findings in the verdict — do not drop details, sections, or decisions that remain valid. " +
+    "Preserve semantics, not source formatting conventions from the verdict: do not copy verdict-style nested objects into fields whose schemas require plain strings. " +
+    "For implementation-design/v1 specifically, goals, non_goals, components, current_state, target_state, business_rules, migration_strategy, database_changes, api_changes, risks, acceptance_criteria, and open_questions must remain arrays of non-empty strings. " +
+    "Only affected_code and decisions may contain nested objects in implementation-design/v1. " +
+    "If you need to preserve extra detail such as mitigation, resolution, or answer text for a string-array field, fold that detail into a single English sentence string instead of creating an object. " +
+    "Produce the following revised outputs: " +
+    `revised design JSON to {revised_design_json_file}. ${strictSchemaInstruction("{revised_design_json_file}", "implementation-design/v1")}` +
+    "Revised design markdown to {revised_design_file}. " +
+    `revised plan JSON to {revised_plan_json_file}. ${strictSchemaInstruction("{revised_plan_json_file}", "implementation-plan/v1")}` +
+    "Revised plan markdown to {revised_plan_file}. " +
+    `revised QA JSON to {revised_qa_json_file}. ${strictSchemaInstruction("{revised_qa_json_file}", "qa-plan/v1")}` +
+    "Revised QA markdown to {revised_qa_file}. " +
+    "Create ready-to-merge.md only when all blocking findings from the verdict have been addressed in the revised artifacts. " +
+    "Do not create ready-to-merge.md if any blocking finding remains unresolved. " +
+    "JSON files must be valid and contain only JSON without markdown wrapping. " +
+    "Markdown files must be comprehensive derivative representations of the corresponding JSON artifacts.";
 export const AUTO_REVIEW_FIX_EXTRA_PROMPT = "Fix only blockers, criticals, and important issues";
 export function formatTemplate(template, values) {
     let result = template;

package/dist/review-severity.js

@@ -0,0 +1,45 @@
+import { TaskRunnerError } from "./errors.js";
+export const REVIEW_SEVERITIES = ["blocker", "critical", "high", "medium", "low", "info"];
+export const AGENTWEAVER_REVIEW_BLOCKING_SEVERITIES_ENV = "AGENTWEAVER_REVIEW_BLOCKING_SEVERITIES";
+export const DEFAULT_REVIEW_BLOCKING_SEVERITIES = ["blocker", "critical", "high"];
+const REVIEW_SEVERITY_SET = new Set(REVIEW_SEVERITIES);
+export function normalizeReviewSeverity(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase();
+    return REVIEW_SEVERITY_SET.has(normalized) ? normalized : null;
+}
+export function normalizeReviewSeverityList(values) {
+    const result = [];
+    for (const value of values) {
+        const normalized = normalizeReviewSeverity(value);
+        if (!normalized || result.includes(normalized)) {
+            continue;
+        }
+        result.push(normalized);
+    }
+    return result;
+}
+export function resolveBlockingReviewSeverities(values) {
+    const normalized = Array.isArray(values) ? normalizeReviewSeverityList(values) : [];
+    return normalized.length > 0 ? normalized : [...DEFAULT_REVIEW_BLOCKING_SEVERITIES];
+}
+export function parseReviewSeverityCsv(raw) {
+    const values = raw
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    const normalized = normalizeReviewSeverityList(values);
+    if (values.length === 0 || normalized.length !== values.length) {
+        throw new TaskRunnerError(`Invalid review severity list '${raw}'. Allowed values: ${REVIEW_SEVERITIES.join(", ")}.`);
+    }
+    return normalized;
+}
+export function resolveReviewBlockingSeveritiesFromEnv(env = process.env) {
+    const raw = env[AGENTWEAVER_REVIEW_BLOCKING_SEVERITIES_ENV]?.trim();
+    if (!raw) {
+        return [...DEFAULT_REVIEW_BLOCKING_SEVERITIES];
+    }
+    return parseReviewSeverityCsv(raw);
+}

package/dist/runtime/artifact-registry.js

@@ -0,0 +1,402 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { buildArtifactId, buildLogicalKeyForPayload, buildPublicationKey, createProducerSummary, diagnosticsForManifest, inferPayloadContract, parseArtifactReference, validateArtifactManifest, } from "../artifact-manifest.js";
+import { artifactIndexFile, artifactManifestSidecarPath, ensureScopeWorkspaceDir, scopeArtifactsDir, scopeWorkspaceDir, } from "../artifacts.js";
+import { TaskRunnerError } from "../errors.js";
+import { isArtifactPayloadSchemaId, validateArtifactPayload, } from "../structured-artifacts.js";
+function nowIso8601() {
+    return new Date().toISOString();
+}
+function historyDir(scopeKey) {
+    return path.join(scopeArtifactsDir(scopeKey), "manifest-history");
+}
+function historyManifestPath(scopeKey, artifactId) {
+    return path.join(historyDir(scopeKey), `${encodeURIComponent(artifactId)}.manifest.json`);
+}
+function scopeKeyFromPayloadPath(payloadPath) {
+    const scopeMarker = `${path.sep}.agentweaver${path.sep}scopes${path.sep}`;
+    const markerIndex = payloadPath.lastIndexOf(scopeMarker);
+    if (markerIndex < 0) {
+        return null;
+    }
+    const scopePart = payloadPath.slice(markerIndex + scopeMarker.length);
+    return scopePart.split(path.sep)[0] || null;
+}
+function writeJsonAtomic(filePath, value) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    renameSync(tempPath, filePath);
+}
+function computeContentHash(payloadPath) {
+    const hash = createHash("sha256");
+    hash.update(readFileSync(payloadPath));
+    return `sha256:${hash.digest("hex")}`;
+}
+function toIndexRecord(manifest) {
+    const producerSummary = manifest.producer.summary ?? createProducerSummary(manifest.producer);
+    return {
+        artifact_id: manifest.artifact_id,
+        logical_key: manifest.logical_key,
+        payload_path: manifest.payload_path,
+        manifest_path: manifest.manifest_path,
+        version: manifest.version,
+        status: manifest.status,
+        schema_id: manifest.schema_id,
+        schema_version: manifest.schema_version,
+        created_at: manifest.created_at,
+        content_hash: manifest.content_hash,
+        producer_summary: producerSummary,
+        ...(manifest.supersedes ? { supersedes: manifest.supersedes } : {}),
+        is_latest: manifest.status === "ready",
+    };
+}
+function tryLoadManifest(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        validateArtifactManifest(parsed, filePath);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function collectManifestFiles(rootDir) {
+    if (!existsSync(rootDir)) {
+        return [];
+    }
+    const queue = [rootDir];
+    const files = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            continue;
+        }
+        const entries = readdirSync(current, { withFileTypes: true })
+            .sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(fullPath);
+                continue;
+            }
+            if (entry.isFile() && fullPath.endsWith(".manifest.json")) {
+                files.push(fullPath);
+            }
+        }
+    }
+    return files;
+}
+function collectScopeManifests(scopeKey) {
+    const allPaths = [
+        ...collectManifestFiles(scopeWorkspaceDir(scopeKey)),
+        ...collectManifestFiles(historyDir(scopeKey)),
+    ];
+    const manifests = new Map();
+    for (const filePath of allPaths) {
+        const manifest = tryLoadManifest(filePath);
+        if (!manifest) {
+            continue;
+        }
+        manifests.set(manifest.artifact_id, manifest);
+    }
+    return Array.from(manifests.values()).sort((left, right) => {
+        if (left.logical_key !== right.logical_key) {
+            return left.logical_key.localeCompare(right.logical_key);
+        }
+        return left.version - right.version;
+    });
+}
+function writeManifestSidecar(manifest) {
+    writeJsonAtomic(manifest.manifest_path, manifest);
+}
+function writeManifestHistory(scopeKey, manifest) {
+    writeJsonAtomic(historyManifestPath(scopeKey, manifest.artifact_id), manifest);
+}
+function isRegistryTempFile(scopeKey, filePath) {
+    const relativePath = path.relative(scopeWorkspaceDir(scopeKey), filePath);
+    if (relativePath.startsWith("..")) {
+        return false;
+    }
+    if (/\.manifest\.json\.tmp-[^/\\]+$/.test(relativePath)) {
+        return true;
+    }
+    return relativePath.startsWith(`${path.join(".artifacts", path.basename(artifactIndexFile(scopeKey)))}.tmp-`);
+}
+function removeStaleTempFiles(scopeKey) {
+    const workspaceDir = scopeWorkspaceDir(scopeKey);
+    if (!existsSync(workspaceDir)) {
+        return;
+    }
+    const queue = [workspaceDir];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            continue;
+        }
+        const entries = readdirSync(current, { withFileTypes: true })
+            .sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(fullPath);
+                continue;
+            }
+            if (entry.isFile() && isRegistryTempFile(scopeKey, fullPath)) {
+                rmSync(fullPath, { force: true });
+            }
+        }
+    }
+}
+function indexRecordEquals(left, right) {
+    return left.artifact_id === right.artifact_id
+        && left.logical_key === right.logical_key
+        && left.payload_path === right.payload_path
+        && left.manifest_path === right.manifest_path
+        && left.version === right.version
+        && left.status === right.status
+        && left.schema_id === right.schema_id
+        && left.schema_version === right.schema_version
+        && left.created_at === right.created_at
+        && left.content_hash === right.content_hash
+        && left.producer_summary === right.producer_summary
+        && left.supersedes === right.supersedes
+        && left.is_latest === right.is_latest;
+}
+function selectLatestReadyManifest(manifests) {
+    return manifests
+        .filter((manifest) => manifest.status === "ready")
+        .sort((left, right) => right.version - left.version)[0] ?? null;
+}
+function selectNewestManifest(manifests) {
+    return manifests
+        .slice()
+        .sort((left, right) => right.version - left.version)[0] ?? null;
+}
+function buildScopeRecords(scopeKey, computeDiagnostics) {
+    const manifests = collectScopeManifests(scopeKey).map((manifest) => ({
+        ...manifest,
+        diagnostics: computeDiagnostics(manifest),
+    }));
+    const latestByLogicalKey = new Map();
+    for (const manifest of manifests) {
+        if (manifest.status === "ready") {
+            latestByLogicalKey.set(manifest.logical_key, manifest.artifact_id);
+        }
+    }
+    return manifests.map((manifest) => ({
+        ...toIndexRecord(manifest),
+        is_latest: latestByLogicalKey.get(manifest.logical_key) === manifest.artifact_id,
+        manifest,
+    }));
+}
+function readIndexProjection(scopeKey) {
+    const indexPath = artifactIndexFile(scopeKey);
+    if (!existsSync(indexPath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(indexPath, "utf8"));
+        return Array.isArray(parsed.records) ? parsed.records : null;
+    }
+    catch {
+        return null;
+    }
+}
+function syncIndexProjection(scopeKey, records) {
+    const projected = records.map(({ manifest: _manifest, ...record }) => record);
+    const current = readIndexProjection(scopeKey);
+    if (!current && projected.length === 0) {
+        return;
+    }
+    const needsRewrite = !current
+        || current.length !== projected.length
+        || current.some((record, index) => !indexRecordEquals(record, projected[index]));
+    if (!needsRewrite) {
+        return;
+    }
+    writeJsonAtomic(artifactIndexFile(scopeKey), {
+        scope: scopeKey,
+        generated_at: nowIso8601(),
+        records: projected,
+    });
+}
+export function createArtifactRegistry() {
+    return {
+        publish(input) {
+            ensureScopeWorkspaceDir(input.scopeKey);
+            removeStaleTempFiles(input.scopeKey);
+            const sidecarPath = artifactManifestSidecarPath(input.payloadPath);
+            const manifests = collectScopeManifests(input.scopeKey);
+            const logicalKey = input.logicalKey ?? buildLogicalKeyForPayload(input.scopeKey, input.payloadPath);
+            const publicationKey = buildPublicationKey({
+                runId: input.runId,
+                ...(input.publicationRunId ? { publicationRunId: input.publicationRunId } : {}),
+                flowId: input.flowId,
+                phaseId: input.phaseId,
+                stepId: input.stepId,
+                logicalKey,
+            });
+            const existing = manifests.find((candidate) => candidate.publication_key === publicationKey);
+            if (existing) {
+                if (existing.payload_path !== input.payloadPath) {
+                    throw new TaskRunnerError(`Manifest publication key collision for ${publicationKey}: ${existing.payload_path} and ${input.payloadPath} resolved to the same logical_key within one step.`);
+                }
+                return {
+                    ...toIndexRecord(existing),
+                    manifest: existing,
+                };
+            }
+            const contract = inferPayloadContract(input.scopeKey, input.payloadPath, {
+                ...(input.payloadFamily ? { payloadFamily: input.payloadFamily } : {}),
+                ...(input.schemaId ? { schemaId: input.schemaId } : {}),
+                ...(input.schemaVersion ? { schemaVersion: input.schemaVersion } : {}),
+            });
+            const versions = manifests
+                .filter((candidate) => candidate.logical_key === logicalKey)
+                .sort((left, right) => left.version - right.version);
+            const previousLatest = [...versions].reverse().find((candidate) => candidate.status === "ready") ?? versions.at(-1) ?? null;
+            const version = (versions.at(-1)?.version ?? 0) + 1;
+            const artifactId = buildArtifactId(input.scopeKey, logicalKey, version);
+            const manifest = {
+                artifact_id: artifactId,
+                logical_key: logicalKey,
+                scope: input.scopeKey,
+                run_id: input.runId,
+                flow_id: input.flowId,
+                phase_id: input.phaseId,
+                step_id: input.stepId,
+                kind: input.kind,
+                version,
+                payload_family: contract.payloadFamily,
+                schema_id: contract.schemaId,
+                schema_version: contract.schemaVersion,
+                created_at: nowIso8601(),
+                producer: {
+                    node: input.nodeKind,
+                    summary: createProducerSummary({
+                        node: input.nodeKind,
+                        ...(input.executor ? { executor: input.executor } : {}),
+                        ...(input.model ? { model: input.model } : {}),
+                    }),
+                    ...(input.executor ? { executor: input.executor } : {}),
+                    ...(input.model ? { model: input.model } : {}),
+                },
+                inputs: input.inputs,
+                content_hash: computeContentHash(input.payloadPath),
+                status: "ready",
+                payload_path: input.payloadPath,
+                manifest_path: sidecarPath,
+                publication_key: publicationKey,
+                ...(previousLatest ? { supersedes: previousLatest.artifact_id } : {}),
+            };
+            validateArtifactManifest(manifest, sidecarPath);
+            writeManifestHistory(input.scopeKey, manifest);
+            writeManifestSidecar(manifest);
+            if (previousLatest) {
+                const superseded = {
+                    ...previousLatest,
+                    status: "superseded",
+                    status_reason: `Superseded by ${artifactId}`,
+                };
+                writeManifestHistory(input.scopeKey, superseded);
+                if (previousLatest.manifest_path !== manifest.manifest_path) {
+                    writeManifestSidecar(superseded);
+                }
+            }
+            this.rebuildIndex(input.scopeKey);
+            return {
+                ...toIndexRecord(manifest),
+                manifest,
+            };
+        },
+        resolveArtifact(scopeKey, reference) {
+            removeStaleTempFiles(scopeKey);
+            const parsedReference = parseArtifactReference(reference);
+            if (!parsedReference) {
+                throw new TaskRunnerError(`Artifact reference '${reference}' is invalid. Expected an artifact_id or a logical reference in the form <logical_key>@latest or <logical_key>@vN.`);
+            }
+            const records = buildScopeRecords(scopeKey, this.computeDiagnostics);
+            syncIndexProjection(scopeKey, records);
+            const manifests = records.map((record) => record.manifest);
+            if (parsedReference.kind === "artifact-id") {
+                if (parsedReference.parsedId.scopeKey !== scopeKey) {
+                    throw new TaskRunnerError(`Artifact id '${reference}' belongs to scope '${parsedReference.parsedId.scopeKey}', expected '${scopeKey}'.`);
+                }
+                const manifest = manifests.find((candidate) => candidate.artifact_id === parsedReference.artifactId);
+                if (!manifest) {
+                    throw new TaskRunnerError(`Artifact '${reference}' was not found in scope '${scopeKey}'.`);
+                }
+                return manifest;
+            }
+            const candidates = manifests.filter((candidate) => candidate.logical_key === parsedReference.logicalKey);
+            if (parsedReference.version === "latest") {
+                const manifest = selectLatestReadyManifest(candidates);
+                if (!manifest) {
+                    throw new TaskRunnerError(`No ready artifact found for logical reference '${reference}' in scope '${scopeKey}'.`);
+                }
+                return manifest;
+            }
+            const manifest = candidates.find((candidate) => candidate.version === parsedReference.version);
+            if (!manifest) {
+                throw new TaskRunnerError(`Artifact reference '${reference}' was not found in scope '${scopeKey}'.`);
+            }
+            return manifest;
+        },
+        loadManifestByPayloadPath(payloadPath) {
+            const manifest = tryLoadManifest(artifactManifestSidecarPath(payloadPath));
+            const scopeKey = scopeKeyFromPayloadPath(payloadPath);
+            if (!scopeKey) {
+                return manifest;
+            }
+            removeStaleTempFiles(scopeKey);
+            const records = buildScopeRecords(scopeKey, this.computeDiagnostics);
+            syncIndexProjection(scopeKey, records);
+            const candidates = records
+                .map((record) => record.manifest)
+                .filter((candidate) => candidate.payload_path === payloadPath);
+            return selectLatestReadyManifest(candidates) ?? selectNewestManifest(candidates) ?? manifest;
+        },
+        listScopeArtifacts(scopeKey) {
+            removeStaleTempFiles(scopeKey);
+            const records = buildScopeRecords(scopeKey, this.computeDiagnostics);
+            syncIndexProjection(scopeKey, records);
+            return records;
+        },
+        rebuildIndex(scopeKey) {
+            removeStaleTempFiles(scopeKey);
+            const records = buildScopeRecords(scopeKey, this.computeDiagnostics);
+            syncIndexProjection(scopeKey, records);
+            return records;
+        },
+        resolveLineageInputFromPath(scopeKey, payloadPath) {
+            const manifest = this.loadManifestByPayloadPath(payloadPath);
+            if (!manifest) {
+                return {
+                    source: "external-path",
+                    path: payloadPath,
+                };
+            }
+            return {
+                source: "manifest",
+                path: payloadPath,
+                artifact_id: manifest.artifact_id,
+                logical_key: manifest.logical_key,
+                schema_id: manifest.schema_id,
+                schema_version: manifest.schema_version,
+            };
+        },
+        computeDiagnostics(manifest) {
+            return diagnosticsForManifest(manifest, (schemaId, payloadPath) => {
+                if (!isArtifactPayloadSchemaId(schemaId)) {
+                    throw new Error(`Structured artifact schema is not registered: ${schemaId}`);
+                }
+                validateArtifactPayload(payloadPath, schemaId);
+            });
+        },
+    };
+}