gh-inari 0.7.0 → 0.9.0

package/dist/artifact.js

@@ -1,14 +1,18 @@
-import { SemanticValidationError, validateSemanticInput, } from "./contract/validation.js";
+import { repairPartialSemanticInput, SemanticValidationError, validatePartialSemanticInput, validateSemanticInput, } from "./contract/validation.js";
+import { createArtifactDiagnostic, createArtifactDiagnosticReport, createFieldEvidence, MAX_ARTIFACT_DIAGNOSTICS, } from "./diagnostics.js";
 import { assertCanonicalContract, } from "./contract/ir.js";
+import { EMPTY_ISSUE_DEPENDENCIES, validateIssueDependencies, } from "./contract/issue-reference.js";
 import { createValidatedRenderedIssueArtifact, createValidatedRenderedPullRequestArtifact, } from "./github/capability.js";
 export class ArtifactInputError extends Error {
     code;
     path;
-    constructor(code, message, path = "$") {
+    details;
+    constructor(code, message, path = "$", details) {
         super(message);
         this.name = "ArtifactInputError";
         this.code = code;
         this.path = path;
+        this.details = details;
     }
 }
 /** Stable failures raised before a mutation-capable artifact is created. */
@@ -19,10 +23,134 @@ export class ArtifactPreparationError extends Error {
         super(message);
         this.name = "ArtifactPreparationError";
         this.code = code;
-        this.diagnostics = diagnostics;
+        this.diagnostics = createArtifactDiagnosticReport(diagnostics.slice(0, MAX_ARTIFACT_DIAGNOSTICS)).diagnostics;
     }
 }
 const GITHUB_NO_RESPONSE = "_No response_";
+/** Explicit empty strings need a representation distinct from omitted values. */
+const EXPLICIT_EMPTY_STRING_MARKER = "\u200B";
+/**
+ * Bounded invisible template identity marker embedded in newly rendered
+ * artifacts. It is the primary template-selection signal for governed
+ * read/repair/validation; legacy artifacts without a marker (or with one
+ * that cannot be trusted) fall back to deterministic structural matching.
+ * The marker is metadata only: it never substitutes for the authoritative
+ * repository governance/provenance that resolves the actual contract.
+ */
+export const TEMPLATE_IDENTITY_MARKER_VERSION = "1";
+const TEMPLATE_IDENTITY_MARKER_PREFIX = "<!-- inari:template ";
+const TEMPLATE_IDENTITY_MARKER_SUFFIX = " -->";
+const TEMPLATE_IDENTITY_MARKER_LINE_PATTERN = /^<!-- inari:template (\{.*\}) -->$/u;
+const TEMPLATE_IDENTITY_MARKER_MAX_LENGTH = 512;
+export const ISSUE_DEPENDENCY_MARKER_VERSION = "1";
+const ISSUE_DEPENDENCY_MARKER_PREFIX = "<!-- inari:issue-dependencies ";
+const ISSUE_DEPENDENCY_MARKER_SUFFIX = " -->";
+const ISSUE_DEPENDENCY_MARKER_LINE_PATTERN = /^<!-- inari:issue-dependencies (\{.*\}) -->$/u;
+const ISSUE_DEPENDENCY_MARKER_MAX_LENGTH = 8_192;
+function renderTemplateIdentityMarker(contract) {
+    const marker = {
+        version: TEMPLATE_IDENTITY_MARKER_VERSION,
+        kind: contract.artifactKind,
+        path: contract.templateIdentity.path,
+    };
+    return `${TEMPLATE_IDENTITY_MARKER_PREFIX}${JSON.stringify(marker)}${TEMPLATE_IDENTITY_MARKER_SUFFIX}`;
+}
+function renderIssueDependencyMarker(dependencies) {
+    return `${ISSUE_DEPENDENCY_MARKER_PREFIX}${JSON.stringify({
+        version: ISSUE_DEPENDENCY_MARKER_VERSION,
+        dependencies,
+    })}${ISSUE_DEPENDENCY_MARKER_SUFFIX}`;
+}
+/**
+ * Read only the reserved trailing dependency marker emitted by Inari.  No
+ * ordinary Markdown is interpreted as a relationship declaration.
+ */
+export function extractIssueDependencyMarker(body) {
+    const source = normalizeSource(body);
+    const lines = source.split("\n");
+    let end = lines.length;
+    while (end > 0 && (lines[end - 1] ?? "").trim().length === 0)
+        end -= 1;
+    const candidate = end > 0 ? (lines[end - 1] ?? "").trim() : undefined;
+    if (candidate === undefined || !candidate.startsWith(ISSUE_DEPENDENCY_MARKER_PREFIX)) {
+        return { status: "absent", body: source };
+    }
+    const remaining = lines.slice(0, end - 1);
+    while (remaining.at(-1) !== undefined && (remaining.at(-1) ?? "").trim().length === 0)
+        remaining.pop();
+    const strippedBody = remaining.length === 0 ? "" : `${remaining.join("\n")}\n`;
+    if (candidate.length > ISSUE_DEPENDENCY_MARKER_MAX_LENGTH || !candidate.endsWith(ISSUE_DEPENDENCY_MARKER_SUFFIX)) {
+        return { status: "malformed", body: strippedBody };
+    }
+    const match = ISSUE_DEPENDENCY_MARKER_LINE_PATTERN.exec(candidate);
+    if (match === null)
+        return { status: "malformed", body: strippedBody };
+    let payload;
+    try {
+        payload = JSON.parse(match[1]);
+    }
+    catch {
+        return { status: "malformed", body: strippedBody };
+    }
+    if (!isRecord(payload) || payload.version !== ISSUE_DEPENDENCY_MARKER_VERSION) {
+        return { status: "unsupported-version", body: strippedBody };
+    }
+    if (!Object.prototype.hasOwnProperty.call(payload, "dependencies")) {
+        return { status: "malformed", body: strippedBody };
+    }
+    return { status: "valid", dependencies: payload.dependencies, body: strippedBody };
+}
+/**
+ * Recognize and remove a trailing template identity marker line without
+ * applying semantic parsing. Only a line starting with the exact reserved
+ * marker prefix is treated as a marker attempt at all; ordinary trailing
+ * HTML comments (e.g. PR template scaffolding) are left untouched here and
+ * handled by the existing comment-stripping path. Once the reserved prefix
+ * is detected, the line is never silently ignored as "absent" again: an
+ * oversized, truncated, or otherwise broken marker attempt fails closed as
+ * "malformed" instead of falling through to structural matching.
+ */
+export function extractTemplateIdentityMarker(body) {
+    const source = normalizeSource(body);
+    const lines = source.split("\n");
+    let end = lines.length;
+    while (end > 0 && (lines[end - 1] ?? "").trim().length === 0)
+        end -= 1;
+    const candidate = end > 0 ? (lines[end - 1] ?? "").trim() : undefined;
+    if (candidate === undefined || !candidate.startsWith(TEMPLATE_IDENTITY_MARKER_PREFIX)) {
+        return { status: "absent", body: source };
+    }
+    const remaining = lines.slice(0, end - 1);
+    while (remaining.at(-1) !== undefined && (remaining.at(-1) ?? "").trim().length === 0)
+        remaining.pop();
+    const strippedBody = remaining.length === 0 ? "" : `${remaining.join("\n")}\n`;
+    if (candidate.length > TEMPLATE_IDENTITY_MARKER_MAX_LENGTH || !candidate.endsWith(TEMPLATE_IDENTITY_MARKER_SUFFIX)) {
+        return { status: "malformed", body: strippedBody };
+    }
+    const match = TEMPLATE_IDENTITY_MARKER_LINE_PATTERN.exec(candidate);
+    if (match === null)
+        return { status: "malformed", body: strippedBody };
+    let payload;
+    try {
+        payload = JSON.parse(match[1]);
+    }
+    catch {
+        return { status: "malformed", body: strippedBody };
+    }
+    if (!isTemplateIdentityMarkerShape(payload))
+        return { status: "malformed", body: strippedBody };
+    if (payload.version !== TEMPLATE_IDENTITY_MARKER_VERSION) {
+        return { status: "unsupported-version", marker: payload, body: strippedBody };
+    }
+    return { status: "valid", marker: payload, body: strippedBody };
+}
+function isTemplateIdentityMarkerShape(value) {
+    return (isRecord(value) &&
+        typeof value.version === "string" &&
+        (value.kind === "issue" || value.kind === "pull_request") &&
+        typeof value.path === "string" &&
+        value.path.trim().length > 0);
+}
 /** Parse the documented JSON input envelope while keeping field semantics adapter-independent. */
 export function parseArtifactInputDocument(input) {
     if (!isRecord(input))
@@ -36,10 +164,15 @@ export function parseArtifactInputDocument(input) {
             if (input[key] !== undefined)
                 metadata[key] = input[key];
         }
-        const unknown = Object.keys(input).filter((key) => key !== "fields" && !Object.prototype.hasOwnProperty.call(metadata, key));
+        const dependencies = parseInputDependencies(input.dependencies);
+        const unknown = Object.keys(input).filter((key) => key !== "fields" && key !== "dependencies" && !Object.prototype.hasOwnProperty.call(metadata, key));
         if (unknown.length > 0)
             throw new ArtifactInputError("INPUT_DOCUMENT_INVALID", `Unknown input property "${unknown[0]}".`, `$.${unknown[0]}`);
-        return { fields: input.fields, metadata: parseMetadata(metadata) };
+        return {
+            fields: input.fields,
+            metadata: parseMetadata(metadata),
+            ...(dependencies === undefined ? {} : { dependencies }),
+        };
     }
     const reservedInBare = Object.keys(input).find((key) => metadataKeys.includes(key));
     if (reservedInBare !== undefined) {
@@ -47,24 +180,256 @@ export function parseArtifactInputDocument(input) {
     }
     return { fields: input, metadata: {} };
 }
+function parseInputDependencies(input) {
+    if (input === undefined)
+        return undefined;
+    const result = validateIssueDependencies(input);
+    if (!result.valid) {
+        const first = result.violations[0];
+        const violations = result.violations.map((violation) => ({
+            ...violation,
+            path: prefixDependencyPath(violation.path),
+        }));
+        throw new ArtifactInputError("INPUT_DEPENDENCIES_INVALID", first?.message ?? "Issue dependencies are invalid.", prefixDependencyPath(first?.path ?? "$.dependencies"), violations);
+    }
+    return result.dependencies;
+}
+/** Prefix dependency violations when they cross the public input envelope boundary. */
+function prefixDependencyPath(path) {
+    if (path === "$")
+        return "$.dependencies";
+    return path.startsWith("$.") ? `$.dependencies${path.slice(1)}` : "$.dependencies";
+}
+/** Adapt a parsed JSON envelope without granting it canonical status. */
+export function adaptJsonArtifactCandidate(input) {
+    const document = parseArtifactInputDocument(input);
+    return { ...document, source: "json" };
+}
+/** Adapt internal structured fields to the same candidate shape as JSON. */
+export function adaptFieldArtifactCandidate(fields, metadata = {}) {
+    if (!isRecord(fields)) {
+        throw new ArtifactInputError("INPUT_DOCUMENT_INVALID", "Candidate fields must be an object.", "$.fields");
+    }
+    return { fields, metadata, source: "fields" };
+}
+/** Alias used by command adapters that call this input the CLI field path. */
+export const adaptCliFieldCandidate = adaptFieldArtifactCandidate;
+/** Generic adapter spelling for callers that already hold structured fields. */
+export const adaptArtifactCandidate = adaptFieldArtifactCandidate;
+/** Adapt an existing native artifact body through the repository parser. */
+export function adaptMarkdownArtifactCandidate(contractInput, body) {
+    assertCanonicalContract(contractInput);
+    const contract = contractInput;
+    const parse = contract.artifactKind === "issue"
+        ? parseExistingIssueArtifact(contract, body)
+        : parseExistingPullRequestArtifact(contract, body);
+    if (!parse.parsed)
+        return { parsed: false, diagnostics: parse.diagnostics };
+    return {
+        parsed: true,
+        candidate: { fields: parse.values, metadata: {}, source: "markdown", dependencies: parse.dependencies },
+        diagnostics: parse.diagnostics,
+    };
+}
+/** Existing GitHub bodies use the same native Markdown adapter by design. */
+export function adaptExistingArtifactCandidate(contractInput, body) {
+    const adapted = adaptMarkdownArtifactCandidate(contractInput, body);
+    return adapted.candidate === undefined
+        ? adapted
+        : { ...adapted, candidate: { ...adapted.candidate, source: "existing" } };
+}
+/**
+ * Reload a candidate against the selected canonical contract.  Complete input
+ * takes the normal one-pass validator (and therefore may materialize contract
+ * defaults); incomplete/invalid input uses the bounded partial contract and
+ * exposes only accepted semantic values.
+ */
+export function loadCanonicalArtifact(contractInput, candidateInput) {
+    assertCanonicalContract(contractInput);
+    const candidate = normalizeArtifactCandidate(candidateInput);
+    const dependencyValidation = contractInput.artifactKind === "issue"
+        ? validateIssueDependencies(candidate.dependencies)
+        : candidate.dependencies === undefined
+            ? { valid: true, dependencies: EMPTY_ISSUE_DEPENDENCIES, violations: [] }
+            : {
+                valid: false,
+                dependencies: EMPTY_ISSUE_DEPENDENCIES,
+                violations: [
+                    {
+                        code: "DEPENDENCIES_UNKNOWN_PROPERTY",
+                        path: "$.dependencies",
+                        message: "Issue dependencies are supported only for Issue artifacts.",
+                    },
+                ],
+            };
+    if (!dependencyValidation.valid) {
+        throw new ArtifactInputError("INPUT_DEPENDENCIES_INVALID", dependencyValidation.violations[0]?.message ?? "Issue dependencies are invalid.", dependencyValidation.violations[0]?.path ?? "$.dependencies", dependencyValidation.violations);
+    }
+    const validation = validateSemanticInput(contractInput, candidate.fields);
+    if (validation.valid) {
+        const acceptedFields = Object.keys(validation.values)
+            .sort(compareStrings)
+            .map((field) => `$.fields.${field}`);
+        const diagnostics = createArtifactDiagnosticReport([], acceptedFields);
+        return {
+            valid: true,
+            complete: true,
+            canonical: validation.values,
+            canonicalJson: validation.values,
+            values: validation.values,
+            candidate,
+            acceptedFields,
+            missingFields: [],
+            invalidFields: [],
+            diagnostics,
+            violations: [],
+            dependencies: dependencyValidation.dependencies,
+        };
+    }
+    const partial = validatePartialSemanticInput(contractInput, candidate.fields);
+    // Partial classification intentionally asks repair callers for explicit
+    // values, including fields whose defaults can complete a full input.  The
+    // loader's missingFields output instead describes why the complete
+    // validation failed, so default-backed fields must only appear when the
+    // full validator actually reports them as required and absent.
+    const missingFields = partial.missingFields.filter((issue) => validation.violations.some((violation) => violation.code === "INPUT_REQUIRED" && violation.path === `$.${issue.field}`));
+    const missingFieldPaths = new Set(missingFields.map((issue) => issue.path));
+    const diagnostics = createArtifactDiagnosticReport(partial.diagnostics.diagnostics.filter((diagnostic) => diagnostic.state !== "missing" || (diagnostic.path !== undefined && missingFieldPaths.has(diagnostic.path))), partial.acceptedFields);
+    return {
+        valid: false,
+        complete: false,
+        canonical: partial.values,
+        canonicalJson: partial.values,
+        values: partial.values,
+        candidate,
+        acceptedFields: partial.acceptedFields,
+        missingFields,
+        invalidFields: partial.invalidFields,
+        diagnostics,
+        violations: validation.violations,
+        dependencies: dependencyValidation.dependencies,
+    };
+}
+/** Explicitly named alias for callers that pass a candidate object. */
+export const loadCanonicalCandidate = loadCanonicalArtifact;
+/** Load a JSON representation through the canonical contract boundary. */
+export function loadCanonicalJsonArtifact(contractInput, input) {
+    return loadCanonicalArtifact(contractInput, adaptJsonArtifactCandidate(input));
+}
+/** Load native Markdown through the same parser and canonical contract. */
+export function loadCanonicalMarkdownArtifact(contractInput, body) {
+    const adapted = adaptMarkdownArtifactCandidate(contractInput, body);
+    if (!adapted.parsed || adapted.candidate === undefined) {
+        const candidate = { fields: {}, metadata: {}, source: "markdown" };
+        const diagnostics = markdownDiagnostics(adapted.diagnostics);
+        return {
+            valid: false,
+            complete: false,
+            canonical: {},
+            canonicalJson: {},
+            values: {},
+            candidate,
+            acceptedFields: [],
+            missingFields: [],
+            invalidFields: [],
+            diagnostics,
+            violations: [],
+        };
+    }
+    return loadCanonicalArtifact(contractInput, adapted.candidate);
+}
+/** Existing-body spelling retained so read/repair callers share one boundary. */
+export function loadCanonicalExistingArtifact(contractInput, body) {
+    const adapted = adaptExistingArtifactCandidate(contractInput, body);
+    if (!adapted.parsed || adapted.candidate === undefined) {
+        const candidate = { fields: {}, metadata: {}, source: "existing" };
+        const diagnostics = markdownDiagnostics(adapted.diagnostics);
+        return {
+            valid: false,
+            complete: false,
+            canonical: {},
+            canonicalJson: {},
+            values: {},
+            candidate,
+            acceptedFields: [],
+            missingFields: [],
+            invalidFields: [],
+            diagnostics,
+            violations: [],
+        };
+    }
+    return loadCanonicalArtifact(contractInput, adapted.candidate);
+}
+function normalizeArtifactCandidate(input) {
+    if (isArtifactCandidate(input))
+        return input;
+    if (isRecord(input) && input.parsed === true && isArtifactCandidate(input.candidate))
+        return input.candidate;
+    if (isArtifactInputDocument(input))
+        return { ...input, source: "json" };
+    return adaptJsonArtifactCandidate(input);
+}
+function isArtifactCandidate(input) {
+    return (isRecord(input) &&
+        (input.source === "json" ||
+            input.source === "markdown" ||
+            input.source === "existing" ||
+            input.source === "fields") &&
+        Object.prototype.hasOwnProperty.call(input, "fields") &&
+        isRecord(input.metadata));
+}
+function isArtifactInputDocument(input) {
+    return isRecord(input) && Object.prototype.hasOwnProperty.call(input, "fields") && isRecord(input.metadata);
+}
+function markdownDiagnostics(diagnostics) {
+    const projected = diagnostics.slice(0, 32).map((diagnostic) => createArtifactDiagnostic({
+        state: "unsupported",
+        code: "FIELD_UNSUPPORTED",
+        detailCode: diagnostic.code === "EXISTING_AMBIGUOUS_TEMPLATE" ? "TEMPLATE_AMBIGUOUS" : "TEMPLATE_UNPARSEABLE",
+        reason: "unsupported",
+        path: diagnostic.path,
+        message: diagnostic.message,
+        recovery: [
+            {
+                action: diagnostic.code === "EXISTING_AMBIGUOUS_TEMPLATE" ? "select-template" : "retry",
+                path: diagnostic.path,
+            },
+        ],
+    }));
+    return createArtifactDiagnosticReport(projected, []);
+}
+/** Classify an artifact input envelope without applying semantic defaults. */
+export function validatePartialArtifactInput(contractInput, input) {
+    assertCanonicalContract(contractInput);
+    return validatePartialSemanticInput(contractInput, parseArtifactInputDocument(input).fields);
+}
+/** Terminology alias for callers that treat validation as classification. */
+export const classifyPartialArtifactInput = validatePartialArtifactInput;
+/** Merge only a targeted field patch into a prior stateless partial result. */
+export function repairPartialArtifactInput(contractInput, previous, patch) {
+    assertCanonicalContract(contractInput);
+    return repairPartialSemanticInput(contractInput, previous, patch);
+}
+/** Terminology alias for callers that describe targeted repair as a merge. */
+export const mergePartialArtifactInput = repairPartialArtifactInput;
 export function renderIssueArtifact(contractInput, input) {
     assertCanonicalContract(contractInput);
     if (contractInput.artifactKind !== "issue")
         throw new ArtifactInputError("INPUT_DOCUMENT_INVALID", "An Issue contract is required.");
-    const validation = validateSemanticInput(contractInput, input);
-    if (!validation.valid)
-        throw new SemanticValidationError(validation.violations);
-    return renderIssueBody(contractInput, validation.values);
+    const loaded = loadCanonicalArtifact(contractInput, input);
+    if (!loaded.valid)
+        throw new SemanticValidationError(loaded.violations);
+    return renderIssueBody(contractInput, loaded.canonical, loaded.dependencies);
 }
 export function renderPullRequestArtifact(contractInput, input) {
     assertCanonicalContract(contractInput);
     if (contractInput.artifactKind !== "pull_request") {
         throw new ArtifactInputError("INPUT_DOCUMENT_INVALID", "A pull request contract is required.");
     }
-    const validation = validateSemanticInput(contractInput, input);
-    if (!validation.valid)
-        throw new SemanticValidationError(validation.violations);
-    return renderPullRequestBody(contractInput, validation.values);
+    const loaded = loadCanonicalArtifact(contractInput, input);
+    if (!loaded.valid)
+        throw new SemanticValidationError(loaded.violations);
+    return renderPullRequestBody(contractInput, loaded.canonical);
 }
 /** Construct the only values accepted by the GitHub mutation adapter. */
 export function prepareIssueArtifact(contractInput, input) {
@@ -72,13 +437,18 @@ export function prepareIssueArtifact(contractInput, input) {
     if (contractInput.artifactKind !== "issue")
         throw new ArtifactInputError("INPUT_DOCUMENT_INVALID", "An Issue contract is required.");
     requireTrustedProvenance(contractInput);
-    const validation = validateSemanticInput(contractInput, input.fields);
-    if (!validation.valid)
-        throw new SemanticValidationError(validation.violations);
-    const title = requiredMetadataString(input.metadata.title ?? contractInput.nativeMetadata.title, "title");
+    const loaded = loadCanonicalArtifact(contractInput, input);
+    if (!loaded.valid)
+        throw new SemanticValidationError(loaded.violations);
+    const title = requiredCreateTitle(input.metadata.title, contractInput.nativeMetadata.title);
     const labels = mergeIssueLabels(contractInput.nativeMetadata.labels, input.metadata.labels);
-    const body = renderIssueBody(contractInput, validation.values);
-    verifyRenderedRoundTrip(contractInput, validation.values, body, "issue");
+    const expectedMetadata = {
+        title,
+        ...(labels === undefined ? {} : { labels: [...labels] }),
+        ...(input.metadata.assignees === undefined ? {} : { assignees: [...input.metadata.assignees] }),
+    };
+    const body = renderIssueBody(contractInput, loaded.canonical, loaded.dependencies);
+    verifyRenderedRoundTrip(contractInput, loaded.canonical, body, "issue", loaded.dependencies);
     const artifact = createValidatedRenderedIssueArtifact({
         kind: "issue",
         title,
@@ -87,7 +457,8 @@ export function prepareIssueArtifact(contractInput, input) {
         ...(labels === undefined ? {} : { labels }),
         ...(input.metadata.assignees === undefined ? {} : { assignees: input.metadata.assignees }),
     });
-    return { input, validation, artifact };
+    verifyIssueMetadataRoundTrip(expectedMetadata, artifact);
+    return { input, validation: semanticValidationFromLoad(loaded), artifact };
 }
 export function preparePullRequestArtifact(contractInput, input) {
     assertCanonicalContract(contractInput);
@@ -95,14 +466,14 @@ export function preparePullRequestArtifact(contractInput, input) {
         throw new ArtifactInputError("INPUT_DOCUMENT_INVALID", "A pull request contract is required.");
     }
     requireTrustedProvenance(contractInput);
-    const validation = validateSemanticInput(contractInput, input.fields);
-    if (!validation.valid)
-        throw new SemanticValidationError(validation.violations);
-    const title = requiredMetadataString(input.metadata.title, "title");
+    const loaded = loadCanonicalArtifact(contractInput, input);
+    if (!loaded.valid)
+        throw new SemanticValidationError(loaded.violations);
+    const title = requiredCreateTitle(input.metadata.title, contractInput.nativeMetadata.title);
     const head = requiredMetadataString(input.metadata.head, "head");
     const base = requiredMetadataString(input.metadata.base, "base");
-    const body = renderPullRequestBody(contractInput, validation.values);
-    verifyRenderedRoundTrip(contractInput, validation.values, body, "pull_request");
+    const body = renderPullRequestBody(contractInput, loaded.canonical);
+    verifyRenderedRoundTrip(contractInput, loaded.canonical, body, "pull_request");
     const artifact = createValidatedRenderedPullRequestArtifact({
         kind: "pull_request",
         title,
@@ -115,7 +486,8 @@ export function preparePullRequestArtifact(contractInput, input) {
             ? {}
             : { maintainerCanModify: input.metadata.maintainerCanModify }),
     });
-    return { input, validation, artifact };
+    verifyPullRequestMetadataRoundTrip(input.metadata, artifact);
+    return { input, validation: semanticValidationFromLoad(loaded), artifact };
 }
 export function parseExistingIssueArtifact(contractInput, body) {
     assertCanonicalContract(contractInput);
@@ -130,10 +502,66 @@ export function parseExistingPullRequestArtifact(contractInput, body) {
     }
     return parseRenderedBody(contractInput, body ?? "", undefined, true);
 }
-export function validateExistingIssueArtifact(contractInput, body) {
+/**
+ * Recover field values from a malformed or wrong-template body without
+ * weakening the strict existing-artifact parser. The section boundaries and
+ * field decoding are the same parser primitives used by strict parsing; only
+ * the order/complete-structure requirement is relaxed for an explicitly
+ * selected repair target.
+ */
+export function recoverExistingArtifactValues(contractInput, body) {
+    assertCanonicalContract(contractInput);
+    const contract = contractInput;
+    const strict = contract.artifactKind === "issue"
+        ? parseExistingIssueArtifact(contract, body)
+        : parseExistingPullRequestArtifact(contract, body);
+    if (strict.parsed)
+        return { values: strict.values, dependencies: strict.dependencies, diagnostics: strict.diagnostics };
+    const dependencyMarker = contract.artifactKind === "issue" ? extractIssueDependencyMarker(body ?? "") : undefined;
+    const markerFreeBody = extractTemplateIdentityMarker(dependencyMarker?.body ?? body ?? "").body;
+    const stripComments = contract.artifactKind === "pull_request";
+    const source = normalizeSource(stripComments ? removeHtmlComments(markerFreeBody) : markerFreeBody);
+    const blocks = headingBlocks(source);
+    const values = {};
+    const expectedTitles = new Map();
+    for (const section of contract.sections) {
+        if (section.kind !== "input")
+            continue;
+        const field = section.fields[0];
+        const title = section.title ?? field?.label;
+        if (field === undefined || title === undefined)
+            continue;
+        const expectedTitle = escapeHeading(title);
+        expectedTitles.set(expectedTitle, (expectedTitles.get(expectedTitle) ?? 0) + 1);
+    }
+    for (const section of contract.sections) {
+        if (section.kind !== "input")
+            continue;
+        const field = section.fields[0];
+        const title = section.title ?? field?.label;
+        if (field === undefined || title === undefined)
+            continue;
+        const expectedTitle = escapeHeading(title);
+        if (expectedTitles.get(expectedTitle) !== 1)
+            continue;
+        const candidates = blocks.filter((block) => block.title === expectedTitle);
+        if (candidates.length !== 1)
+            continue;
+        const block = candidates[0];
+        const parsed = parseFieldLines(field, block.body, `$.${field.id}`, stripComments, contract.artifactKind === "issue");
+        // parseFieldLines may retain known checklist selections alongside a
+        // bounded structural diagnostic. The canonical loader below decides
+        // whether such a partial value is semantically usable.
+        if (parsed.value !== undefined)
+            values[field.id] = parsed.value;
+    }
+    const dependencies = dependencyMarker?.dependencies;
+    return { values, dependencies, diagnostics: strict.diagnostics };
+}
+export function validateExistingIssueArtifact(contractInput, body, subject) {
     assertCanonicalContract(contractInput);
     const parse = parseExistingIssueArtifact(contractInput, body);
-    return validateParsedArtifact(contractInput, parse);
+    return validateParsedArtifact(contractInput, parse, subject);
 }
 export function validateExistingPullRequestArtifact(contractInput, body) {
     assertCanonicalContract(contractInput);
@@ -147,6 +575,7 @@ export function projectExistingArtifact(result) {
         projection: result.valid ? "canonical" : "unavailable",
         classification: result.classification,
         ...(result.valid ? { fields: result.parse.values } : {}),
+        ...(result.valid && result.parse.dependencies !== undefined ? { dependencies: result.parse.dependencies } : {}),
         diagnostics: result.parse.diagnostics,
         ...(result.classification === "semantic" ? { violations: result.violations } : {}),
         ...(result.attemptedTemplates === undefined ? {} : { attemptedTemplates: result.attemptedTemplates }),
@@ -210,7 +639,11 @@ export function validateRequiredMetadataString(value, key) {
 }
 export async function validateExistingIssueFromAdapter(reader, contract, issueNumber) {
     const issue = await reader.getIssue(issueNumber);
-    return { number: issueNumber, url: issue.url, result: validateExistingIssueArtifact(contract, issue.body) };
+    return {
+        number: issueNumber,
+        url: issue.url,
+        result: validateExistingIssueArtifact(contract, issue.body, issueReferenceFromUrl(issue.url, issueNumber, issue.repositoryId, issue.repositoryHost)),
+    };
 }
 export async function validateExistingPullRequestFromAdapter(reader, contract, pullRequestNumber) {
     const pullRequest = await reader.getPullRequest(pullRequestNumber);
@@ -220,83 +653,292 @@ export async function validateExistingPullRequestFromAdapter(reader, contract, p
         result: validateExistingPullRequestArtifact(contract, pullRequest.body),
     };
 }
-function validateParsedArtifact(contract, parse) {
+function validateParsedArtifact(contract, parse, subject) {
     if (!parse.parsed) {
         const classification = parse.diagnostics.some((diagnostic) => diagnostic.code === "EXISTING_WRONG_TEMPLATE")
             ? "wrong-template"
             : "unparseable";
         return { valid: false, classification, parse, violations: parse.diagnostics };
     }
-    const semantic = validateSemanticInput(contract, parse.values);
+    const dependencyInput = parse.dependencyInput ?? parse.dependencies;
+    const dependencyValidation = contract.artifactKind === "issue" ? validateIssueDependencies(dependencyInput, subject) : undefined;
+    if (dependencyValidation !== undefined && !dependencyValidation.valid) {
+        return {
+            valid: false,
+            classification: "semantic",
+            parse,
+            violations: dependencyValidation.violations.map((violation) => ({
+                code: "INPUT_DEPENDENCY",
+                path: prefixDependencyPath(violation.path),
+                message: violation.message,
+            })),
+        };
+    }
+    const normalizedParse = dependencyValidation === undefined
+        ? parse
+        : { ...parse, dependencies: dependencyValidation.dependencies, dependencyInput: undefined };
+    const semantic = loadCanonicalArtifact(contract, {
+        fields: parse.values,
+        metadata: {},
+        source: "existing",
+        dependencies: dependencyValidation?.dependencies ?? parse.dependencies,
+    });
     return {
         valid: semantic.valid,
         classification: semantic.valid ? "valid" : "semantic",
-        parse,
+        parse: normalizedParse,
         violations: semantic.violations,
     };
 }
 function requireTrustedProvenance(contract) {
     if (contract.provenance === undefined) {
         throw new ArtifactPreparationError("ARTIFACT_PROVENANCE_MISSING", "Mutation preparation requires a contract bound to trusted repository governance.", [
-            {
-                code: "ROUND_TRIP_PARSE",
+            createArtifactDiagnostic({
+                state: "unrecoverable",
+                code: "ARTIFACT_UNRECOVERABLE",
+                reason: "unrecoverable",
                 path: "$.provenance",
                 message: "The compiled contract has no trusted repository/ref provenance.",
-            },
+                recovery: [{ action: "retry", path: "$.provenance" }],
+            }),
         ]);
     }
 }
-function verifyRenderedRoundTrip(contract, expectedValues, body, kind) {
+function verifyPullRequestMetadataRoundTrip(input, artifact) {
+    const expected = {
+        title: input.title,
+        head: input.head,
+        base: input.base,
+        ...(input.draft === undefined ? {} : { draft: input.draft }),
+        ...(input.maintainerCanModify === undefined ? {} : { maintainerCanModify: input.maintainerCanModify }),
+    };
+    const actual = {
+        title: artifact.title,
+        head: artifact.head,
+        base: artifact.base,
+        ...(artifact.draft === undefined ? {} : { draft: artifact.draft }),
+        ...(artifact.maintainerCanModify === undefined ? {} : { maintainerCanModify: artifact.maintainerCanModify }),
+    };
+    const mismatches = [];
+    for (const key of Object.keys(expected).sort(compareStrings)) {
+        const path = `$.metadata.${key}`;
+        if (stableValue(expected[key]) === stableValue(actual[key]))
+            continue;
+        mismatches.push(createArtifactDiagnostic({
+            state: "conflicting",
+            code: "FIELD_CONFLICT",
+            detailCode: "FIELD_VALUE_CONFLICT",
+            reason: "conflict",
+            path,
+            message: "Prepared pull request metadata changed before the mutation boundary.",
+            expected: createFieldEvidence(path, expected[key]),
+            actual: createFieldEvidence(path, actual[key]),
+            recovery: [{ action: "repair", path, hint: "Repair the pull request metadata projection." }],
+        }));
+    }
+    if (mismatches.length > 0) {
+        throw new ArtifactPreparationError("ARTIFACT_ROUND_TRIP_INVALID", "Prepared pull request metadata did not preserve its validated values.", mismatches);
+    }
+}
+/** @internal Validate the canonical Issue metadata handoff before mutation. */
+export function verifyIssueMetadataRoundTrip(expected, artifact) {
+    const actual = {
+        title: artifact.title,
+        ...(artifact.labels === undefined ? {} : { labels: artifact.labels }),
+        ...(artifact.assignees === undefined ? {} : { assignees: artifact.assignees }),
+    };
+    const mismatches = [];
+    const keys = [...new Set([...Object.keys(expected), ...Object.keys(actual)])].sort(compareStrings);
+    for (const key of keys) {
+        const expectedPresent = Object.prototype.hasOwnProperty.call(expected, key);
+        const actualPresent = Object.prototype.hasOwnProperty.call(actual, key);
+        const path = `$.metadata.${key}`;
+        if (expectedPresent && actualPresent && stableValue(expected[key]) === stableValue(actual[key]))
+            continue;
+        mismatches.push(createArtifactDiagnostic({
+            state: "conflicting",
+            code: "FIELD_CONFLICT",
+            detailCode: "FIELD_VALUE_CONFLICT",
+            reason: "conflict",
+            path,
+            message: "Prepared issue metadata changed before the mutation boundary.",
+            expected: createFieldEvidence(path, expectedPresent ? expected[key] : undefined),
+            actual: createFieldEvidence(path, actualPresent ? actual[key] : undefined),
+            recovery: [{ action: "repair", path, hint: "Repair the issue metadata projection." }],
+        }));
+    }
+    if (mismatches.length > 0) {
+        throw new ArtifactPreparationError("ARTIFACT_ROUND_TRIP_INVALID", "Prepared issue metadata did not preserve its validated values.", mismatches);
+    }
+}
+function verifyRenderedRoundTrip(contract, expectedValues, body, kind, expectedDependencies = undefined) {
     const parsed = kind === "issue" ? parseExistingIssueArtifact(contract, body) : parseExistingPullRequestArtifact(contract, body);
     if (!parsed.parsed) {
-        throw new ArtifactPreparationError("ARTIFACT_ROUND_TRIP_INVALID", `Rendered ${kind} artifact did not reparse under the compiled contract.`, parsed.diagnostics.map((diagnostic) => ({
-            code: "ROUND_TRIP_PARSE",
-            path: diagnostic.path,
-            message: diagnostic.message,
-        })));
+        throw new ArtifactPreparationError("ARTIFACT_ROUND_TRIP_INVALID", `Rendered ${kind} artifact did not reparse under the compiled contract.`, roundTripParseDiagnostics(contract, expectedValues, parsed.diagnostics));
     }
     const reconstructed = validateSemanticInput(contract, parsed.values);
     if (!reconstructed.valid) {
-        throw new ArtifactPreparationError("ARTIFACT_ROUND_TRIP_INVALID", `Rendered ${kind} artifact failed semantic validation after reparsing.`, reconstructed.violations.map((violation) => ({
-            code: "ROUND_TRIP_SEMANTIC",
-            path: violation.path,
-            message: violation.message,
-        })));
+        throw new ArtifactPreparationError("ARTIFACT_ROUND_TRIP_INVALID", `Rendered ${kind} artifact failed semantic validation after reparsing.`, roundTripSemanticDiagnostics(contract, expectedValues, parsed.values, reconstructed.violations));
+    }
+    const mismatches = [...compareMaterializedValues(expectedValues, reconstructed.values)];
+    if (kind === "issue") {
+        const actualDependencies = parsed.dependencies ?? EMPTY_ISSUE_DEPENDENCIES;
+        const expected = expectedDependencies ?? EMPTY_ISSUE_DEPENDENCIES;
+        if (stableValue(expected) !== stableValue(actualDependencies)) {
+            mismatches.push(createArtifactDiagnostic({
+                state: "conflicting",
+                code: "FIELD_CONFLICT",
+                detailCode: "FIELD_VALUE_CONFLICT",
+                reason: "conflict",
+                path: "$.dependencies",
+                message: "Rendered artifact changed its Issue dependency semantics.",
+                expected: createFieldEvidence("$.dependencies", expected),
+                actual: createFieldEvidence("$.dependencies", actualDependencies),
+                recovery: [{ action: "repair", path: "$.dependencies" }],
+            }));
+        }
     }
-    const mismatches = compareMaterializedValues(expectedValues, reconstructed.values);
     if (mismatches.length > 0) {
         throw new ArtifactPreparationError("ARTIFACT_ROUND_TRIP_INVALID", `Rendered ${kind} artifact did not preserve its validated semantic values.`, mismatches);
     }
 }
+function roundTripParseDiagnostics(contract, expectedValues, diagnostics) {
+    const projected = diagnostics.slice(0, MAX_ARTIFACT_DIAGNOSTICS).map((diagnostic) => {
+        const fieldId = semanticFieldId(contract, diagnostic.path);
+        const path = fieldId === undefined ? semanticDiagnosticPath(contract, diagnostic.path) : fieldPath(fieldId);
+        return createArtifactDiagnostic({
+            state: "unsupported",
+            code: "FIELD_UNSUPPORTED",
+            detailCode: "TEMPLATE_UNPARSEABLE",
+            reason: "unsupported",
+            ...(path === undefined ? {} : { path }),
+            message: roundTripParseMessage(diagnostic.code),
+            ...(fieldId === undefined
+                ? {}
+                : {
+                    expected: createFieldEvidence(fieldPath(fieldId), expectedValues[fieldId]),
+                    actual: createFieldEvidence(fieldPath(fieldId), undefined),
+                }),
+            recovery: path === undefined ? [{ action: "retry" }] : [{ action: "repair", path }],
+        });
+    });
+    return projected.length > 0
+        ? projected
+        : [
+            createArtifactDiagnostic({
+                state: "unrecoverable",
+                code: "ARTIFACT_UNRECOVERABLE",
+                reason: "unrecoverable",
+                message: "Rendered artifact could not be reparsed under the compiled contract.",
+                recovery: [{ action: "retry" }],
+            }),
+        ];
+}
+function roundTripSemanticDiagnostics(contract, expectedValues, actualValues, violations) {
+    const projected = violations.slice(0, MAX_ARTIFACT_DIAGNOSTICS).map((violation) => {
+        const fieldId = semanticFieldId(contract, violation.path);
+        const path = fieldId === undefined ? semanticDiagnosticPath(contract, violation.path) : fieldPath(fieldId);
+        const evidencePath = fieldId === undefined ? path : fieldPath(fieldId);
+        return createArtifactDiagnostic({
+            state: "invalid",
+            code: "FIELD_INVALID",
+            detailCode: violation.code === "INPUT_TYPE" ? "FIELD_TYPE_MISMATCH" : "FIELD_CONSTRAINT_VIOLATION",
+            reason: violation.code === "INPUT_TYPE" ? "type" : "constraint",
+            ...(path === undefined ? {} : { path }),
+            message: violation.code === "INPUT_TYPE"
+                ? "Reparsed semantic value has an unsupported type."
+                : "Reparsed semantic value violates a compiled constraint.",
+            ...(evidencePath === undefined
+                ? {}
+                : {
+                    expected: createFieldEvidence(evidencePath, fieldId === undefined ? undefined : expectedValues[fieldId]),
+                    actual: createFieldEvidence(evidencePath, fieldId === undefined ? undefined : actualValues[fieldId]),
+                }),
+            recovery: path === undefined ? [{ action: "repair" }] : [{ action: "repair", path }],
+        });
+    });
+    return projected.length > 0
+        ? projected
+        : [
+            createArtifactDiagnostic({
+                state: "unrecoverable",
+                code: "ARTIFACT_UNRECOVERABLE",
+                reason: "unrecoverable",
+                message: "Reparsed artifact failed semantic validation under the compiled contract.",
+                recovery: [{ action: "retry" }],
+            }),
+        ];
+}
 function compareMaterializedValues(expected, actual) {
     const keys = [...new Set([...Object.keys(expected), ...Object.keys(actual)])].sort(compareStrings);
     const diagnostics = [];
     for (const key of keys) {
         const expectedPresent = Object.prototype.hasOwnProperty.call(expected, key);
         const actualPresent = Object.prototype.hasOwnProperty.call(actual, key);
-        const path = `$.${key}`;
+        const path = fieldPath(key);
         if (!expectedPresent || !actualPresent) {
-            diagnostics.push({
-                code: "ROUND_TRIP_MISMATCH",
+            diagnostics.push(createArtifactDiagnostic({
+                state: "conflicting",
+                code: "FIELD_CONFLICT",
+                detailCode: "FIELD_VALUE_CONFLICT",
+                reason: "conflict",
                 path,
-                message: "Rendered artifact changed whether a semantic field was materialized.",
-                ...(expectedPresent ? { expected: expected[key] } : {}),
-                ...(actualPresent ? { actual: actual[key] } : {}),
-            });
+                message: "Rendered artifact changed whether this semantic field was materialized.",
+                expected: createFieldEvidence(path, expectedPresent ? expected[key] : undefined),
+                actual: createFieldEvidence(path, actualPresent ? actual[key] : undefined),
+                recovery: [{ action: "repair", path, hint: "Repair the renderer/parser mapping for this field." }],
+            }));
             continue;
         }
         if (stableValue(expected[key]) !== stableValue(actual[key])) {
-            diagnostics.push({
-                code: "ROUND_TRIP_MISMATCH",
+            diagnostics.push(createArtifactDiagnostic({
+                state: "conflicting",
+                code: "FIELD_CONFLICT",
+                detailCode: "FIELD_VALUE_CONFLICT",
+                reason: "conflict",
                 path,
-                message: "Rendered artifact changed a materialized semantic value.",
-                expected: expected[key],
-                actual: actual[key],
-            });
+                message: "Rendered artifact changed this materialized semantic value.",
+                expected: createFieldEvidence(path, expected[key]),
+                actual: createFieldEvidence(path, actual[key]),
+                recovery: [{ action: "repair", path, hint: "Repair the renderer/parser mapping for this field." }],
+            }));
         }
     }
     return diagnostics;
 }
+function fieldPath(fieldId) {
+    return `$.fields.${fieldId}`;
+}
+function semanticFieldId(contract, path) {
+    const fields = contract.sections.flatMap((section) => section.fields);
+    for (const field of fields) {
+        if (path === `$.${field.id}` || path.startsWith(`$.${field.id}[`))
+            return field.id;
+    }
+    const sectionId = /^\$\.sections\.([^.[\]]+)/u.exec(path)?.[1];
+    return sectionId === undefined
+        ? undefined
+        : contract.sections.find((section) => section.id === sectionId)?.fields[0]?.id;
+}
+function semanticDiagnosticPath(contract, path) {
+    const sectionId = /^\$\.sections\.([^.[\]]+)/u.exec(path)?.[1];
+    if (sectionId !== undefined && contract.sections.some((section) => section.id === sectionId)) {
+        return `$.sections.${sectionId}`;
+    }
+    return path === "$" ? undefined : path.startsWith("$.artifact") ? undefined : path;
+}
+function roundTripParseMessage(code) {
+    switch (code) {
+        case "EXISTING_UNKNOWN_CHECKLIST_ITEM":
+            return "Rendered artifact contains an undeclared checklist item.";
+        case "EXISTING_EXTRA_CONTENT":
+            return "Rendered artifact contains content outside the compiled template structure.";
+        case "EXISTING_WRONG_TEMPLATE":
+            return "Rendered artifact does not match the compiled template structure.";
+        default:
+            return "Rendered artifact does not match the compiled field representation.";
+    }
+}
 function stableValue(value) {
     if (value === undefined)
         return "undefined";
@@ -310,7 +952,18 @@ function stableValue(value) {
         .map((key) => `${JSON.stringify(key)}:${stableValue(record[key])}`)
         .join(",")}}`;
 }
-function renderIssueBody(contract, values) {
+function issueReferenceFromUrl(url, number, repositoryId, repositoryHost) {
+    const match = /^https?:\/\/([^/]+)\/([^/]+)\/([^/]+)\/issues\/[1-9][0-9]*$/u.exec(url);
+    if (match === null || repositoryId === undefined)
+        return undefined;
+    return {
+        repositoryHost: (repositoryHost ?? match[1]).toLocaleLowerCase("en-US"),
+        repositoryId,
+        repository: `${match[2]}/${match[3]}`.toLocaleLowerCase("en-US"),
+        number,
+    };
+}
+function renderIssueBody(contract, values, dependencies = undefined) {
     const blocks = [];
     for (let sectionIndex = 0; sectionIndex < contract.sections.length; sectionIndex += 1) {
         const section = contract.sections[sectionIndex];
@@ -329,7 +982,11 @@ function renderIssueBody(contract, values) {
             .join("\n\n");
         blocks.push([`### ${escapeHeading(title)}`, body].filter((part) => part.length > 0).join("\n\n"));
     }
-    return `${blocks.join("\n\n")}\n`;
+    const marker = renderTemplateIdentityMarker(contract);
+    const dependencyMarker = dependencies !== undefined && (dependencies.blockedBy.length > 0 || dependencies.blocks.length > 0)
+        ? `\n${renderIssueDependencyMarker(dependencies)}`
+        : "";
+    return `${blocks.join("\n\n")}\n\n${marker}${dependencyMarker}\n`;
 }
 function renderPullRequestBody(contract, values) {
     const blocks = [];
@@ -350,7 +1007,7 @@ function renderPullRequestBody(contract, values) {
             .filter(Boolean);
         blocks.push([`${"#".repeat(level)} ${escapeHeading(title)}`, ...rendered].join("\n\n"));
     }
-    return `${blocks.join("\n\n")}\n`;
+    return `${blocks.join("\n\n")}\n\n${renderTemplateIdentityMarker(contract)}\n`;
 }
 function renderDocumentation(section, content) {
     const level = section.render.headingLevel ?? section.nativeMetadata.headingLevel;
@@ -360,10 +1017,16 @@ function renderDocumentation(section, content) {
 }
 function renderFieldValue(field, value, kind) {
     if (field.type === "string" || field.type === "enum") {
+        if (typeof value === "string" && value.length === 0) {
+            return field.nativeMetadata.render === undefined
+                ? EXPLICIT_EMPTY_STRING_MARKER
+                : renderCodeBlock(EXPLICIT_EMPTY_STRING_MARKER, field.nativeMetadata.render);
+        }
         if (typeof value === "string" && (kind !== "issue" || value.trim().length > 0)) {
+            const renderedValue = kind === "issue" ? issueNativeValue(field, value) : value;
             return field.nativeMetadata.render === undefined
-                ? escapeMarkdownValue(value)
-                : renderCodeBlock(value, field.nativeMetadata.render);
+                ? escapeMarkdownValue(renderedValue)
+                : renderCodeBlock(renderedValue, field.nativeMetadata.render);
         }
         if (kind === "pull_request")
             return field.nativeMetadata.placeholder ?? "";
@@ -376,20 +1039,53 @@ function renderFieldValue(field, value, kind) {
             return kind === "issue" ? GITHUB_NO_RESPONSE : "";
         if (value.length === 0)
             return kind === "issue" ? GITHUB_NO_RESPONSE : "";
+        const renderedValues = kind === "issue"
+            ? value.map((entry) => (typeof entry === "string" ? issueNativeValue(field, entry) : String(entry)))
+            : value.map((entry) => String(entry));
         if (field.nativeMetadata.multiple === true)
-            return value.map((entry) => escapeMarkdownValue(String(entry))).join(", ");
-        return value.map((entry) => `- ${escapeMarkdownValue(String(entry))}`).join("\n");
+            return renderedValues.map((entry) => escapeMarkdownValue(entry)).join(", ");
+        return renderedValues.map((entry) => `- ${escapeMarkdownValue(entry)}`).join("\n");
     }
     const selected = new Set(Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : []);
     const placeholder = kind === "pull_request" ? field.nativeMetadata.placeholder : undefined;
     const lines = field.items.map((item) => `- [${selected.has(item.id) ? "x" : " "}] ${escapeMarkdownValue(item.label)}`);
     return [placeholder === undefined ? "" : placeholder, lines.join("\n")].filter(Boolean).join("\n\n");
 }
+/** Map canonical Issue semantic values to the labels shown by GitHub Issue Forms. */
+function issueNativeValue(field, value) {
+    if (field.type === "enum")
+        return field.options.find((option) => option.value === value)?.label ?? value;
+    if (field.type === "array")
+        return field.items.options?.find((option) => option.value === value)?.label ?? value;
+    return value;
+}
+/** Map GitHub Issue Form labels back to canonical semantic values. */
+function issueSemanticValue(field, value) {
+    if (value === undefined)
+        return undefined;
+    if (field.type === "enum")
+        return field.options.find((option) => option.label === value)?.value ?? value;
+    if (field.type === "array")
+        return field.items.options?.find((option) => option.label === value)?.value ?? value;
+    return value;
+}
 function parseRenderedBody(contract, body, issueHeadingLevel, stripComments) {
-    const source = normalizeSource(stripComments ? removeHtmlComments(body) : body);
+    const dependencyMarker = contract.artifactKind === "issue" ? extractIssueDependencyMarker(body) : { status: "absent", body };
+    const markerFreeBody = extractTemplateIdentityMarker(dependencyMarker.body).body;
+    const source = normalizeSource(stripComments ? removeHtmlComments(markerFreeBody) : markerFreeBody);
     const lines = source.split("\n");
     const values = {};
     const diagnostics = [];
+    const dependencies = contract.artifactKind === "issue" ? (dependencyMarker.dependencies ?? EMPTY_ISSUE_DEPENDENCIES) : undefined;
+    if (dependencyMarker.status === "malformed" || dependencyMarker.status === "unsupported-version") {
+        diagnostics.push({
+            code: "EXISTING_UNPARSEABLE",
+            path: "$.dependencies",
+            message: dependencyMarker.status === "unsupported-version"
+                ? "Issue dependency marker uses an unsupported version."
+                : "Issue dependency marker is malformed or semantically invalid.",
+        });
+    }
     let cursor = 0;
     for (let sectionIndex = 0; sectionIndex < contract.sections.length; sectionIndex += 1) {
         const section = contract.sections[sectionIndex];
@@ -467,7 +1163,7 @@ function parseRenderedBody(contract, body, issueHeadingLevel, stripComments) {
             }
         }
         const fieldLines = trimLineRange(lines.slice(contentStart, fieldEnd));
-        const parsed = parseFieldLines(field, fieldLines, `$.${field.id}`, stripComments);
+        const parsed = parseFieldLines(field, fieldLines, `$.${field.id}`, stripComments, issueHeadingLevel !== undefined);
         diagnostics.push(...parsed.diagnostics);
         if (parsed.value !== undefined)
             values[field.id] = parsed.value;
@@ -485,9 +1181,39 @@ function parseRenderedBody(contract, body, issueHeadingLevel, stripComments) {
     }
     if (diagnostics.length > 0)
         return { parsed: false, values: {}, diagnostics };
-    return { parsed: true, values, diagnostics: [] };
+    return {
+        parsed: true,
+        values,
+        dependencies,
+        ...(dependencyMarker.status === "valid" ? { dependencyInput: dependencyMarker.dependencies } : {}),
+        diagnostics: [],
+    };
+}
+function headingBlocks(source) {
+    const lines = source.split("\n");
+    const starts = [];
+    let openFence;
+    lines.forEach((line, index) => {
+        const fenceMatch = /^(`{3,})/u.exec(line);
+        if (openFence === undefined && fenceMatch !== null) {
+            openFence = fenceMatch[1];
+            return;
+        }
+        if (openFence !== undefined) {
+            if (fenceMatch !== null && fenceMatch[1] === openFence)
+                openFence = undefined;
+            return;
+        }
+        const match = /^ {0,3}#{1,6}[ \t]+(.+?)[ \t]*$/u.exec(line);
+        if (match !== null)
+            starts.push({ index, title: match[1] });
+    });
+    return starts.map((start, position) => {
+        const next = starts[position + 1]?.index ?? lines.length;
+        return { title: start.title, body: trimLineRange(lines.slice(start.index + 1, next)) };
+    });
 }
-function parseFieldLines(field, lines, path, stripComments) {
+function parseFieldLines(field, lines, path, stripComments, issueBody) {
     const diagnostics = [];
     const filtered = stripComments ? lines.filter((line) => line.trim().length > 0) : lines;
     if (filtered.length === 1 && filtered[0]?.trim() === GITHUB_NO_RESPONSE) {
@@ -496,15 +1222,17 @@ function parseFieldLines(field, lines, path, stripComments) {
         return { value: field.type === "array" ? [] : undefined, diagnostics };
     }
     if (field.type === "string" || field.type === "enum") {
-        const value = field.nativeMetadata.render === undefined
+        const parsedValue = field.nativeMetadata.render === undefined
             ? trimBlankLines(unescapeMarkdownValue(filtered.join("\n")))
             : parseRenderedCodeBlock(filtered, field.nativeMetadata.render, path, diagnostics);
+        if (parsedValue === EXPLICIT_EMPTY_STRING_MARKER)
+            return { value: "", diagnostics };
         const placeholder = stripComments
             ? removeHtmlComments(field.nativeMetadata.placeholder ?? "")
             : (field.nativeMetadata.placeholder ?? "");
-        if (stripComments && value !== undefined && value === trimBlankLines(placeholder))
+        if (stripComments && parsedValue !== undefined && parsedValue === trimBlankLines(placeholder))
             return { value: undefined, diagnostics };
-        return { value, diagnostics };
+        return { value: issueBody ? issueSemanticValue(field, parsedValue) : parsedValue, diagnostics };
     }
     if (field.type === "array") {
         if (field.nativeMetadata.multiple === true) {
@@ -517,7 +1245,7 @@ function parseFieldLines(field, lines, path, stripComments) {
                 .filter((entry) => entry.length > 0);
             if (values.length === 0)
                 return { value: undefined, diagnostics };
-            return { value: values, diagnostics };
+            return { value: issueBody ? values.map((value) => issueSemanticValue(field, value)) : values, diagnostics };
         }
         const values = filtered
             .map((line) => {
@@ -644,10 +1372,35 @@ function parseMetadata(input) {
 }
 function requiredMetadataString(value, key) {
     const violation = validateRequiredMetadataString(value, key);
-    if (violation !== undefined)
-        throw new ArtifactInputError(violation.code, violation.message, violation.path);
+    if (violation !== undefined) {
+        throwMetadataInputError(value, key, violation.message, value === undefined ? "missing" : "invalid", value === undefined ? `Provide a value for ${key}.` : `Provide a non-empty string for ${key}.`);
+    }
     return value;
 }
+function requiredCreateTitle(value, nativeTitle) {
+    const title = requiredMetadataString(value, "title");
+    const nativePrefix = nativeTitle?.trim();
+    if (nativePrefix !== undefined && nativePrefix.length > 0 && title.trim() === nativePrefix) {
+        throwMetadataInputError(title, "title", "title must contain content beyond the fixed native template prefix.", "invalid", "Provide a title containing caller content beyond the fixed native template prefix.");
+    }
+    return title;
+}
+function throwMetadataInputError(value, key, message, state, hint) {
+    const path = `$.${key}`;
+    const diagnostic = createArtifactDiagnostic({
+        state,
+        code: state === "missing" ? "FIELD_MISSING" : "FIELD_INVALID",
+        detailCode: state === "missing" ? "FIELD_REQUIRED" : "FIELD_CONSTRAINT_VIOLATION",
+        reason: state === "missing" ? "required" : "constraint",
+        path,
+        message,
+        ...(state === "missing" || value === undefined ? {} : { actual: createFieldEvidence(path, value) }),
+        recovery: [{ action: "provide", path, hint }],
+    });
+    throw new ArtifactInputError("INPUT_METADATA_INVALID", message, path, {
+        diagnostics: createArtifactDiagnosticReport([diagnostic]),
+    });
+}
 function stringArray(value, key) {
     if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
         throw new ArtifactInputError("INPUT_METADATA_INVALID", `${key} must be an array of non-empty strings.`, `$.${key}`);
@@ -735,4 +1488,7 @@ function isRecord(value) {
 function compareStrings(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }
+function semanticValidationFromLoad(loaded) {
+    return { valid: loaded.valid, violations: loaded.violations, values: loaded.canonical };
+}
 //# sourceMappingURL=artifact.js.map