@tiinex/core 0.1.1

package/src/tooling/portable/lineage/lineage.integrity.apply.js

@@ -0,0 +1,306 @@
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+import { canonicalC14nV2SelfState, validatedC14nV2PrimarySelfDigest } from '../../../integrity/integrity.c14nV2.js';
+import { C14N_V2_METHOD_ID } from '../../../integrity/integrity.methodReference.js';
+import { resolveLineage } from '../../../lineage/lineage.resolve.js';
+import { normalizePortableInput } from '../input/portable.input.js';
+import { portableFinding } from '../findings.js';
+import { buildLineagePostRepairAudit } from './lineage.integrity.apply.audit.js';
+import { normalizePublicationProviderReceipts } from './lineage.publicationProviderReceipts.js';
+import { applyStructureAwareLineageMutation } from './lineage.integrity.apply.structure.js';
+import { providerMaterialMatches, targetAuthorizedByDeclaredParent } from './lineage.integrity.apply.evidence.js';
+
+export const PORTABLE_LINEAGE_INTEGRITY_APPLY_SCHEMA_ID = 'tiinex.portable.lineage-integrity-repair-application.v1';
+export const PORTABLE_LINEAGE_INTEGRITY_RECEIPT_SCHEMA_ID = 'tiinex.portable.lineage-integrity-repair-receipt.v1';
+
+const APPROVED = new Set(['approved', 'accepted']);
+const SEMANTIC_DISPOSITIONS = new Set(['representation-only', 'harmless-representation-only', 'qualified-semantic-decision']);
+const PLAN_ACTIONS = new Set(['backfill-parent-target-v2', 'review-parent-target-mismatch', 'update-parent-origin-permalink', 'no-change', 'resolve-lineage-integrity-blocker']);
+
+export function applyPortableLineageIntegrityRepair(input = {}, options = {}) {
+  const material = normalizePortableInput(input.materials || input);
+  const records = (material.records || []).filter((record) => record?.path && typeof record.markdown === 'string');
+  const repairPlan = input.repairPlan || input.plan || null;
+  const providerEvidence = normalizePublicationProviderReceipts(input);
+  const findings = [...(material.findings || []), ...(providerEvidence.findings || [])];
+  const planValidation = validatePlan(repairPlan);
+  if (!planValidation.ok) return resultEnvelope({ status: 'blocked', records, receipts: [blockedReceipt('', '', 'plan-validation', planValidation.reasons)], findings: findingsWith(findings, 'error', 'portable.lineage-integrity-apply.plan-invalid', planValidation.reasons.join(', ')) });
+
+  const approvals = normalizeApprovals(input.approvals || input.artifactApprovals || input.dispositions || []);
+  const recordByPath = new Map(records.map((record) => [normalizePath(record.path), Object.freeze({ ...record, path: normalizePath(record.path) })]));
+  const stepByPath = new Map((repairPlan.steps || []).map((step) => [normalizePath(step?.artifact?.path), step]));
+  const lineage = resolveLineage(records, { depth: options.depth || 'portable-lineage-integrity-repair-application' });
+  const graph = buildParentGraph(lineage, recordByPath);
+  const order = topologicalPaths(recordByPath, graph.parentByChild, graph.childrenByParent);
+  const working = new Map(recordByPath);
+  const changedPaths = new Set();
+  const receipts = [];
+  const branchStops = new Set();
+
+  for (const path of order) {
+    const record = working.get(path);
+    if (!record) continue;
+    const step = stepByPath.get(path) || null;
+    const approval = approvals.get(path) || null;
+    const parentPath = graph.parentByChild.get(path) || '';
+    const parentChanged = Boolean(parentPath && changedPaths.has(parentPath));
+    const parentBranchStopped = Boolean(parentPath && branchStops.has(parentPath));
+    const directAction = Boolean(step && step.action && step.action !== 'no-change' && step.action !== 'resolve-lineage-integrity-blocker');
+
+    if (parentBranchStopped) {
+      branchStops.add(path);
+      continue;
+    }
+    if (!directAction && !parentChanged) continue;
+
+    const classification = classifyRepair({ path, record, step, approval, parentPath, parentChanged, working, providerEvidence });
+    if (!classification.ok) {
+      receipts.push(blockedReceipt(path, record.id || '', classification.repairClass, classification.blockers, { descendantsConsidered: descendantPaths(path, graph.childrenByParent) }));
+      if (parentChanged) branchStops.add(path);
+      findings.push(portableFinding('warning', 'portable.lineage-integrity-apply.blocked', `Lineage repair application blocked for ${path}.`, { ref: path, reason: classification.blockers.join(', ') }));
+      continue;
+    }
+
+    const parentRecord = parentPath ? working.get(parentPath) : null;
+    const applied = applyOne({ record, parentRecord, step, approval, repairClass: classification.repairClass, desiredTarget: classification.desiredTarget, parentChanged });
+    receipts.push(applied.receipt);
+    if (applied.status === 'blocked') {
+      if (parentChanged) branchStops.add(path);
+      findings.push(portableFinding('error', 'portable.lineage-integrity-apply.representation-guard', `Representation-preserving repair failed closed for ${path}.`, { ref: path, reason: applied.receipt.remainingBlockers.join(', ') }));
+      continue;
+    }
+    if (applied.status === 'changed') {
+      changedPaths.add(path);
+      working.set(path, Object.freeze({ ...record, markdown: applied.markdown }));
+    }
+  }
+
+  const resultingRecords = [...working.values()];
+  const changedRecords = [...changedPaths].map((path) => working.get(path)).filter(Boolean);
+  const blocked = receipts.some((receipt) => receipt.status === 'blocked');
+  const changed = changedRecords.length > 0;
+  const status = blocked ? (changed ? 'partial-blocked' : 'blocked') : changed ? 'changed' : 'no-op';
+  return resultEnvelope({ status, records: resultingRecords, changedRecords, receipts, findings });
+}
+
+function classifyRepair({ path, record, step, approval, parentPath, parentChanged, working, providerEvidence }) {
+  const repairClass = directRepairClass(step, parentChanged);
+  const blockers = [];
+  if (!approval || !APPROVED.has(String(approval.state || approval.disposition || '').toLowerCase())) blockers.push('per-artifact-approval-required');
+  if (step && !PLAN_ACTIONS.has(String(step.action || ''))) blockers.push(`unsupported-plan-action:${step.action || ''}`);
+  if (step?.approval?.disposition === 'blocked' && !canQualifyBlockedPlan(step, approval)) blockers.push(...(step.approval.blockers || ['plan-step-blocked']));
+  if (step?.action === 'review-parent-target-mismatch') {
+    if (!SEMANTIC_DISPOSITIONS.has(String(approval?.semanticDisposition || ''))) blockers.push('qualified-semantic-disposition-required');
+    if (!String(approval?.semanticAuthority || '').trim()) blockers.push('semantic-authority-reference-required');
+    for (const blocker of step?.approval?.blockers || []) if (!blockerSatisfied(blocker, approval)) blockers.push(blocker);
+  }
+  if (step?.action === 'backfill-parent-target-v2' && step?.approval?.disposition !== 'proposed') blockers.push(`backfill-plan-disposition-not-proposed:${step?.approval?.disposition || 'missing'}`);
+  if (step?.action === 'update-parent-origin-permalink') {
+    if (!Array.from(step?.expectedMutation?.headerFields || []).includes('Parent.Origin.browse+git')) blockers.push('plan-header-origin-update-not-authorized');
+    if (!String(step?.candidateParentOrigin || '').trim()) blockers.push('plan-candidate-parent-origin-missing');
+    if (approval?.publicationDisposition !== 'qualified-exact-publication') blockers.push('qualified-exact-publication-disposition-required');
+  }
+  if (parentChanged && !parentPath) blockers.push('cascade-parent-unresolved');
+  if (parentChanged && step?.action === 'resolve-lineage-integrity-blocker') blockers.push('blocked-descendant-cannot-cascade');
+  const currentSelf = canonicalC14nV2SelfState(record.markdown || '');
+  if (currentSelf.state !== 'verified') blockers.push(`child-self-${currentSelf.state || 'unavailable'}`);
+  const parentRecord = parentPath ? working.get(parentPath) : null;
+  if ((directNeedsParent(step) || parentChanged) && !parentRecord) blockers.push('exact-parent-material-required');
+  let parentSelf = null;
+  if (parentRecord) {
+    parentSelf = validatedC14nV2PrimarySelfDigest(parentRecord.markdown || '');
+    if (parentSelf.state !== 'verified') blockers.push(`parent-self-${parentSelf.state || 'unavailable'}`);
+    if (directNeedsParent(step) && !parentChanged && step?.candidateTargetDigest && parentSelf.state === 'verified' && step.candidateTargetDigest !== parentSelf.value) blockers.push('plan-candidate-parent-digest-stale');
+  }
+  const desiredTarget = desiredParentTarget(step, approval, record);
+  if ((directNeedsParent(step) || parentChanged) && !desiredTarget) blockers.push('parent-target-locator-unavailable');
+  if (directNeedsParent(step) && desiredTarget && !targetAuthorizedByDeclaredParent(record, step, approval, desiredTarget)) blockers.push('desired-parent-target-not-authorized-by-declared-parent');
+  if (parentRecord && step?.action === 'backfill-parent-target-v2') {
+    const evidenceTarget = String(step?.publicationLocator || step?.exactParentTarget?.publicationLocator || desiredTarget || '');
+    if (!providerMaterialMatches(providerEvidence, evidenceTarget, parentRecord.markdown || '', false)) blockers.push('accepted-exact-provider-material-required');
+  }
+  if (parentRecord && step?.action === 'review-parent-target-mismatch') {
+    const evidenceTarget = String(step?.publicationLocator || step?.exactParentTarget?.publicationLocator || '');
+    const historical = approval?.targetDisposition === 'repaired-local-parent' && approval?.originDisposition === 'historical-pre-repair-origin-retained';
+    if (!providerMaterialMatches(providerEvidence, evidenceTarget, parentRecord.markdown || '', historical)) blockers.push(historical ? 'accepted-historical-provider-material-required' : 'accepted-exact-provider-material-required');
+  }
+  if (parentRecord && step?.action === 'update-parent-origin-permalink') {
+    if (!providerMaterialMatches(providerEvidence, desiredTarget, parentRecord.markdown || '', false)) blockers.push('accepted-exact-provider-material-required');
+  }
+  return Object.freeze({ ok: blockers.length === 0, repairClass, desiredTarget, blockers: Object.freeze(unique(blockers)) });
+}
+
+function canQualifyBlockedPlan(step, approval) {
+  if (step?.action !== 'review-parent-target-mismatch') return false;
+  return (step?.approval?.blockers || []).every((blocker) => blockerSatisfied(blocker, approval));
+}
+
+function blockerSatisfied(blocker, approval = {}) {
+  if (blocker === 'existing-target-mismatch-is-not-refresh-authority') return SEMANTIC_DISPOSITIONS.has(String(approval.semanticDisposition || '')) && Boolean(String(approval.semanticAuthority || '').trim());
+  if (blocker === 'publication-origin-stale' || blocker === 'publication-origin-contradictory') return approval.targetDisposition === 'repaired-local-parent' && approval.originDisposition === 'historical-pre-repair-origin-retained' && SEMANTIC_DISPOSITIONS.has(String(approval.semanticDisposition || ''));
+  return false;
+}
+
+function directNeedsParent(step) { return ['backfill-parent-target-v2', 'review-parent-target-mismatch', 'update-parent-origin-permalink'].includes(step?.action); }
+function directRepairClass(step, parentChanged) {
+  if (step?.action === 'backfill-parent-target-v2') return 'missing-parent-target-backfill';
+  if (step?.action === 'review-parent-target-mismatch') return 'mismatching-parent-target-refresh';
+  if (step?.action === 'update-parent-origin-permalink') return 'qualified-parent-origin-update';
+  return parentChanged ? 'descendant-cascade-reseal' : 'no-change';
+}
+function desiredParentTarget(step, approval, record) {
+  if (step?.action === 'review-parent-target-mismatch' && approval?.targetDisposition === 'repaired-local-parent') return String(step?.exactParentTarget?.trace || '').trim();
+  if (step?.action === 'update-parent-origin-permalink') return String(step?.candidateParentOrigin || '').trim();
+  if (step?.exactParentTarget?.expectedIntegrityTarget) return String(step.exactParentTarget.expectedIntegrityTarget).trim();
+  const parsed = safeParse(record?.markdown || '');
+  const existing = (parsed?.integrity?.entries || []).find((entry) => entry?.method === C14N_V2_METHOD_ID && String(entry?.towards || '') !== 'self');
+  return String(existing?.towards || '').trim();
+}
+
+
+function applyOne({ record, parentRecord, step, approval, repairClass, desiredTarget }) {
+  const original = String(record.markdown || '');
+  const oldParsed = safeParse(original);
+  if (!oldParsed) return blockedApply(record, repairClass, ['artifact-parse-failed']);
+  const oldSelf = canonicalC14nV2SelfState(original);
+  if (oldSelf.state !== 'verified') return blockedApply(record, repairClass, [`child-self-${oldSelf.state || 'unavailable'}`]);
+  const oldParentEntries = (oldParsed?.integrity?.entries || []).filter((entry) => entry?.method === C14N_V2_METHOD_ID && String(entry?.towards || '') !== 'self');
+  const oldParentEntry = oldParentEntries.length === 1 ? oldParentEntries[0] : null;
+  const oldHeaderTarget = browseGitOrigin(oldParsed);
+  const parentSelf = parentRecord ? validatedC14nV2PrimarySelfDigest(parentRecord.markdown || '') : null;
+  const desiredDigest = parentSelf?.state === 'verified' ? parentSelf.value : String(step?.candidateTargetDigest || '');
+  if (!desiredDigest) return blockedApply(record, repairClass, ['candidate-parent-digest-unavailable']);
+
+  const desiredHeaderTarget = step?.action === 'update-parent-origin-permalink' ? String(step.candidateParentOrigin || '') : oldHeaderTarget;
+  const alreadyDesired = oldParentEntries.length === 1 && oldParentEntry && oldParentEntry.towards === desiredTarget && oldParentEntry.value === desiredDigest && oldHeaderTarget === desiredHeaderTarget;
+  if (alreadyDesired) return noOpApply(record, repairClass, oldHeaderTarget, oldParentEntry, oldSelf, descendantList(step));
+
+  const structured = applyStructureAwareLineageMutation({
+    markdown: original,
+    target: desiredTarget,
+    digest: desiredDigest,
+    parentPath: parentRecord?.path || step?.exactParentTarget?.path || '',
+    parentOriginTarget: step?.action === 'update-parent-origin-permalink' && oldHeaderTarget !== desiredHeaderTarget ? desiredHeaderTarget : ''
+  });
+  if (!structured.ok) return blockedApply(record, repairClass, structured.blockers);
+  const next = structured.markdown;
+  const newParsed = safeParse(next);
+  const newSelf = canonicalC14nV2SelfState(next);
+  if (!newParsed || newSelf.state !== 'verified') return blockedApply(record, repairClass, [`post-repair-self-${newSelf.state || 'unavailable'}`]);
+  const newParentEntry = parentIntegrityEntry(newParsed);
+  if (!newParentEntry || newParentEntry.towards !== desiredTarget || newParentEntry.value !== desiredDigest) return blockedApply(record, repairClass, ['post-repair-parent-target-verification-failed']);
+
+  const receipt = repairReceipt({
+    status: next === original ? 'no-op' : 'changed', record, repairClass,
+    reason: String(approval?.reason || approval?.semanticDisposition || step?.currentState || repairClass),
+    oldHeaderTarget, newHeaderTarget: browseGitOrigin(newParsed),
+    oldParentTarget: oldParentEntry, newParentTarget: newParentEntry,
+    oldSelfDigest: oldSelf.declaredValue || '', newSelfDigest: newSelf.declaredValue || '',
+    descendantsConsidered: descendantList(step), mutationSurfaces: structured.mutationSurfaces,
+    bodyPreserved: structured.bodyPreserved,
+    siblingFooterEntriesPreserved: structured.siblingFooterEntriesPreserved,
+    remainingBlockers: []
+  });
+  return Object.freeze({ status: receipt.status, markdown: next, receipt });
+}
+
+function buildParentGraph(lineage, recordByPath) {
+  const pathById = new Map((lineage.nodes || []).map((node) => [String(node.id || ''), normalizePath(node.path || node.record?.path || '')]));
+  const parentByChild = new Map();
+  const childrenByParent = new Map();
+  for (const edge of lineage.edges || []) {
+    if (edge.kind !== 'parent' || !edge.from || !edge.to || edge.status === 'missing') continue;
+    const parent = pathById.get(String(edge.from)) || '';
+    const child = pathById.get(String(edge.to)) || '';
+    if (!parent || !child || !recordByPath.has(parent) || !recordByPath.has(child)) continue;
+    if (parentByChild.has(child) && parentByChild.get(child) !== parent) continue;
+    parentByChild.set(child, parent);
+    const children = childrenByParent.get(parent) || [];
+    children.push(child);
+    childrenByParent.set(parent, unique(children).sort());
+  }
+  return Object.freeze({ parentByChild, childrenByParent });
+}
+
+function topologicalPaths(recordByPath, parentByChild, childrenByParent) {
+  const indegree = new Map([...recordByPath.keys()].map((path) => [path, parentByChild.has(path) ? 1 : 0]));
+  const queue = [...indegree].filter(([, degree]) => degree === 0).map(([path]) => path).sort();
+  const out = [];
+  while (queue.length) {
+    const path = queue.shift();
+    out.push(path);
+    for (const child of childrenByParent.get(path) || []) {
+      indegree.set(child, Math.max(0, (indegree.get(child) || 0) - 1));
+      if (indegree.get(child) === 0) { queue.push(child); queue.sort(); }
+    }
+  }
+  for (const path of [...recordByPath.keys()].sort()) if (!out.includes(path)) out.push(path);
+  return out;
+}
+
+function descendantPaths(path, childrenByParent) {
+  const out = [];
+  const queue = [...(childrenByParent.get(path) || [])].map((child) => ({ path: child, depth: 1 }));
+  const seen = new Set();
+  while (queue.length) {
+    const current = queue.shift();
+    if (!current || seen.has(current.path)) continue;
+    seen.add(current.path);
+    out.push(Object.freeze({ path: current.path, depth: current.depth }));
+    for (const child of childrenByParent.get(current.path) || []) queue.push({ path: child, depth: current.depth + 1 });
+  }
+  return Object.freeze(out);
+}
+
+function validatePlan(plan) {
+  const reasons = [];
+  if (!plan || typeof plan !== 'object') reasons.push('explicit-repair-plan-required');
+  if (plan?.schema !== 'tiinex.portable.repair-plan.v1') reasons.push(`repair-plan-schema-unsupported:${plan?.schema || 'missing'}`);
+  if (plan?.mode !== 'lineage-integrity-inspection') reasons.push(`repair-plan-mode-unsupported:${plan?.mode || 'missing'}`);
+  if (!Array.isArray(plan?.steps)) reasons.push('repair-plan-steps-required');
+  if (plan?.boundary?.automaticRewrite !== false) reasons.push('repair-plan-automatic-rewrite-boundary-invalid');
+  return Object.freeze({ ok: reasons.length === 0, reasons: Object.freeze(reasons) });
+}
+
+function normalizeApprovals(value) {
+  const out = new Map();
+  if (Array.isArray(value)) {
+    for (const item of value) { const path = normalizePath(item?.path || item?.artifact?.path || ''); if (path) out.set(path, Object.freeze({ ...item, path })); }
+  } else if (value && typeof value === 'object') {
+    for (const [key, item] of Object.entries(value)) { const path = normalizePath(item?.path || key); if (path) out.set(path, Object.freeze({ ...(item || {}), path })); }
+  }
+  return out;
+}
+
+function resultEnvelope({ status, records, changedRecords = [], receipts = [], findings = [] }) {
+  const frozenReceipts = Object.freeze(receipts.map((receipt) => Object.freeze(receipt)));
+  const humanReceipt = frozenReceipts.map((receipt) => humanReceiptLine(receipt)).join('\n');
+  const reAudit = buildLineagePostRepairAudit(records, changedRecords);
+  return Object.freeze({
+    schema: PORTABLE_LINEAGE_INTEGRITY_APPLY_SCHEMA_ID,
+    status,
+    changeset: Object.freeze({ schema: 'tiinex.portable.local-lineage-repair-changeset.v1', records: Object.freeze(changedRecords.map((record) => Object.freeze({ ...record }))), changedPaths: Object.freeze(changedRecords.map((record) => record.path)), sourceMutation: false, remoteWrite: false, publicationMutation: false }),
+    receipts: frozenReceipts,
+    humanReceipt,
+    reAudit,
+    boundary: Object.freeze({ explicitRepairPlanRequired: true, perArtifactApprovalRequired: true, structureAwareEditing: true, bodyMutationAuthorized: false, sourceMutation: false, remoteWrite: false, publicationMutation: false, representationDiffFailClosed: true, postRepairReAuditRequired: true, sharedAuditCapability: true }),
+    inputRecordCount: records.length,
+    findings: Object.freeze(findings)
+  });
+}
+
+function repairReceipt({ status, record, repairClass, reason, oldHeaderTarget, newHeaderTarget, oldParentTarget, newParentTarget, oldSelfDigest, newSelfDigest, descendantsConsidered, mutationSurfaces, bodyPreserved, siblingFooterEntriesPreserved, remainingBlockers }) {
+  return Object.freeze({ schema: PORTABLE_LINEAGE_INTEGRITY_RECEIPT_SCHEMA_ID, status, artifact: Object.freeze({ id: String(record.id || ''), path: normalizePath(record.path || '') }), repairClass, reason, oldHeaderTargets: Object.freeze({ parentOriginBrowseGit: oldHeaderTarget || '' }), newHeaderTargets: Object.freeze({ parentOriginBrowseGit: newHeaderTarget || '' }), oldParentTarget: Object.freeze({ locator: oldParentTarget?.towards || '', digest: oldParentTarget?.value || '' }), newParentTarget: Object.freeze({ locator: newParentTarget?.towards || '', digest: newParentTarget?.value || '' }), oldSelfDigest: oldSelfDigest || '', newSelfDigest: newSelfDigest || '', descendantsConsidered: Object.freeze([...(descendantsConsidered || [])]), mutationSurface: Object.freeze([...(mutationSurfaces || [])]), bodyPreservationCheck: bodyPreserved ? 'byte-identical' : 'failed', siblingFooterPreservationCheck: siblingFooterEntriesPreserved ? 'byte-identical' : 'failed', remainingBlockers: Object.freeze([...(remainingBlockers || [])]) });
+}
+function blockedReceipt(path, id, repairClass, blockers, extra = {}) { return repairReceipt({ status: 'blocked', record: { path, id }, repairClass, reason: 'blocked', oldHeaderTarget: '', newHeaderTarget: '', oldParentTarget: null, newParentTarget: null, oldSelfDigest: '', newSelfDigest: '', descendantsConsidered: extra.descendantsConsidered || [], mutationSurfaces: [], bodyPreserved: true, siblingFooterEntriesPreserved: true, remainingBlockers: unique(blockers) }); }
+function blockedApply(record, repairClass, blockers) { return Object.freeze({ status: 'blocked', markdown: record.markdown || '', receipt: blockedReceipt(record.path || '', record.id || '', repairClass, blockers) }); }
+function noOpApply(record, repairClass, header, parentEntry, self, descendants) { return Object.freeze({ status: 'no-op', markdown: record.markdown || '', receipt: repairReceipt({ status: 'no-op', record, repairClass, reason: 'already-repaired', oldHeaderTarget: header, newHeaderTarget: header, oldParentTarget: parentEntry, newParentTarget: parentEntry, oldSelfDigest: self.declaredValue || '', newSelfDigest: self.declaredValue || '', descendantsConsidered: descendants, mutationSurfaces: [], bodyPreserved: true, siblingFooterEntriesPreserved: true, remainingBlockers: [] }) }); }
+function humanReceiptLine(receipt) { const path = receipt.artifact?.path || '(plan)'; const blockers = receipt.remainingBlockers?.length ? ` blockers=${receipt.remainingBlockers.join(',')}` : ''; return `${receipt.status.toUpperCase()} ${path} ${receipt.repairClass}${blockers}`; }
+function findingsWith(findings, severity, code, message) { return [...findings, portableFinding(severity, code, message, {})]; }
+
+function parentIntegrityEntry(parsed) { return (parsed?.integrity?.entries || []).find((entry) => entry?.method === C14N_V2_METHOD_ID && String(entry?.towards || '') !== 'self') || null; }
+function browseGitOrigin(parsed) { return String((parsed?.envelope?.parent?.originEntries || []).find((entry) => entry.label === 'browse + git')?.target || ''); }
+function descendantList(step) { return Object.freeze([...(step?.descendantImpact || [])]); }
+function safeParse(markdown) { try { return parseArtifactMarkdown(markdown); } catch { return null; } }
+
+function normalizePath(value) { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, ''); }
+function unique(values) { return [...new Set((values || []).map(String).filter(Boolean))]; }

package/src/tooling/portable/lineage/lineage.integrity.apply.structure.js

@@ -0,0 +1,178 @@
+import { canonicalC14nV2SelfState } from '../../../integrity/integrity.c14nV2.js';
+import { C14N_V2_METHOD_ID } from '../../../integrity/integrity.methodReference.js';
+
+export function applyStructureAwareLineageMutation({ markdown = '', target = '', digest = '', parentPath = '', parentOriginTarget = '' } = {}) {
+  const before = structuralSnapshots(markdown);
+  if (!before.ok) return before;
+  let next = String(markdown || '');
+  const mutationSurfaces = [];
+  if (parentOriginTarget) {
+    const header = updateParentBrowseGit(next, parentOriginTarget);
+    if (!header.ok) return header;
+    next = header.markdown;
+    mutationSurfaces.push('Continuity Context/Parent/Origin/browse + git');
+  }
+  const footer = upsertParentIntegrity(next, { target, digest, parentPath });
+  if (!footer.ok) return footer;
+  next = footer.markdown;
+  mutationSurfaces.push('Continuity Integrity/Parent-target c14n-v2');
+  const resealed = resealSelfPreservingRepresentation(next);
+  if (!resealed.ok) return resealed;
+  next = resealed.markdown;
+  mutationSurfaces.push('Continuity Integrity/primary self Value');
+  const after = structuralSnapshots(next);
+  const guard = representationGuard(before, after, { headerUpdate: Boolean(parentOriginTarget) });
+  if (!guard.ok) return guard;
+  return Object.freeze({ ok: true, markdown: next, mutationSurfaces: Object.freeze(mutationSurfaces), bodyPreserved: before.body === after.body, siblingFooterEntriesPreserved: guard.siblingFooterEntriesPreserved });
+}
+
+function upsertParentIntegrity(markdown, { target, digest, parentPath }) {
+  const model = scanIntegrity(markdown);
+  if (!model.ok) return model;
+  if (model.selfEntries.length !== 1) return fail('primary-self-entry-not-exactly-one');
+  if (model.parentEntries.length > 1) return fail('parent-target-entry-ambiguous');
+  const lines = model.lines.slice();
+  if (model.parentEntries.length === 1) {
+    const entry = model.parentEntries[0];
+    if (entry.towardsLine < 0 || entry.valueLine < 0) return fail('parent-target-entry-malformed');
+    lines[entry.towardsLine] = replaceFieldLine(lines[entry.towardsLine], 'Towards', renderTowards(entry.towardsRaw, target));
+    lines[entry.valueLine] = replaceFieldLine(lines[entry.valueLine], 'Value', digest);
+    return Object.freeze({ ok: true, markdown: joinLines(lines) });
+  }
+  const self = model.selfEntries[0];
+  const methodRaw = self.methodRaw || C14N_V2_METHOD_ID;
+  const eol = model.preferredEol;
+  const label = basename(parentPath) || basename(target) || 'parent';
+  const insert = [
+    makeLine(`- ${methodRaw}`, eol),
+    makeLine(`  - Towards: [${label}](${target})`, eol),
+    makeLine(`  - Value: ${digest}`, eol),
+    makeLine('', eol)
+  ];
+  lines.splice(self.start, 0, ...insert);
+  return Object.freeze({ ok: true, markdown: joinLines(lines) });
+}
+
+function resealSelfPreservingRepresentation(markdown) {
+  const state = canonicalC14nV2SelfState(markdown);
+  if (!['verified', 'mismatch', 'prepared'].includes(state.state)) return fail(`self-seal-${state.reason || state.state}`);
+  const model = scanIntegrity(markdown);
+  if (!model.ok || model.selfEntries.length !== 1) return fail('primary-self-entry-not-exactly-one');
+  const self = model.selfEntries[0];
+  if (self.valueLine < 0) return fail('self-value-field-missing');
+  const lines = model.lines.slice();
+  lines[self.valueLine] = replaceFieldLine(lines[self.valueLine], 'Value', state.computedValue);
+  const next = joinLines(lines);
+  const verified = canonicalC14nV2SelfState(next);
+  if (verified.state !== 'verified') return fail(`self-seal-postcondition-${verified.state}`);
+  return Object.freeze({ ok: true, markdown: next, value: verified.declaredValue });
+}
+
+function updateParentBrowseGit(markdown, target) {
+  if (!/^https:\/\/github\.com\/[^/]+\/[^/]+\/blob\/[0-9a-f]{40}\//.test(String(target || ''))) return fail('parent-origin-target-not-immutable-github-blob');
+  const lines = splitLines(markdown);
+  const rule = firstRuleIndex(lines);
+  if (rule < 0) return fail('continuity-envelope-divider-missing');
+  const parent = topLevelBlock(lines, '- Parent', rule);
+  if (!parent) return fail('parent-envelope-block-missing');
+  const originIndex = findInRange(lines, parent.start + 1, parent.end, /^\s{2}-\s+Origin:\s*$/);
+  if (originIndex < 0) return fail('parent-origin-block-missing');
+  const nestedEnd = nestedListEnd(lines, originIndex + 1, parent.end, 2);
+  const browse = findInRange(lines, originIndex + 1, nestedEnd, /^\s{4}-\s+\[browse \+ git\]\([^)]+\)\s*$/);
+  if (browse >= 0) {
+    const raw = lines[browse].content;
+    lines[browse] = { ...lines[browse], content: raw.replace(/\[browse \+ git\]\([^)]+\)/, `[browse + git](${target})`) };
+  } else {
+    const eol = preferredEol(lines);
+    lines.splice(nestedEnd, 0, makeLine(`    - [browse + git](${target})`, eol));
+  }
+  return Object.freeze({ ok: true, markdown: joinLines(lines) });
+}
+
+function scanIntegrity(markdown) {
+  const lines = splitLines(markdown);
+  const headings = [];
+  for (let i = 0; i < lines.length; i += 1) if (/^# Continuity Integrity[ \t]*$/.test(lines[i].content)) headings.push(i);
+  if (headings.length !== 1) return fail(headings.length ? 'multiple-integrity-footers' : 'integrity-footer-missing');
+  const heading = headings[0];
+  const entries = [];
+  let current = null;
+  const finish = (end) => { if (current) { current.end = end; entries.push(Object.freeze(current)); current = null; } };
+  for (let i = heading + 1; i < lines.length; i += 1) {
+    const line = lines[i].content;
+    if (/^#\s+/.test(line)) { finish(i); break; }
+    const top = line.match(/^-\s+(.+?)\s*$/);
+    if (top) {
+      finish(i);
+      current = { start: i, end: lines.length, methodRaw: top[1].trim(), method: stripLink(top[1].trim()), towards: '', towardsRaw: '', towardsLine: -1, value: '', valueLine: -1 };
+      continue;
+    }
+    if (!current) continue;
+    const towards = line.match(/^\s+-\s+Towards:\s*(.*?)\s*$/);
+    if (towards) { current.towardsRaw = towards[1].trim(); current.towards = linkTargetOrText(current.towardsRaw); current.towardsLine = i; }
+    const value = line.match(/^\s+-\s+Value:\s*(.*?)\s*$/);
+    if (value) { current.value = value[1].trim(); current.valueLine = i; }
+  }
+  finish(lines.length);
+  const c14n = entries.filter((entry) => entry.method === C14N_V2_METHOD_ID);
+  return Object.freeze({ ok: true, lines, heading, entries: Object.freeze(entries), selfEntries: Object.freeze(c14n.filter((entry) => entry.towards === 'self')), parentEntries: Object.freeze(c14n.filter((entry) => entry.towards && entry.towards !== 'self')), preferredEol: preferredEol(lines) });
+}
+
+function structuralSnapshots(markdown) {
+  const lines = splitLines(markdown);
+  const rule = firstRuleIndex(lines);
+  const footer = lines.findIndex((line) => /^# Continuity Integrity[ \t]*$/.test(line.content));
+  if (rule < 0 || footer < 0 || footer <= rule) return Object.freeze({ ok: false, blockers: Object.freeze(['artifact-structure-boundaries-unavailable']) });
+  const envelope = joinLines(lines.slice(0, rule));
+  const body = joinLines(lines.slice(rule, footer));
+  const integrity = scanIntegrity(markdown);
+  if (!integrity.ok) return Object.freeze({ ok: false, blockers: integrity.blockers });
+  const siblingEntries = integrity.entries.filter((entry) => entry.method !== C14N_V2_METHOD_ID).map((entry) => joinLines(lines.slice(entry.start, entry.end)));
+  const repairs = envelopeBlockRaw(lines, rule, '- Repairs:');
+  return Object.freeze({ ok: true, envelope, body, repairs, siblingEntries: Object.freeze(siblingEntries) });
+}
+
+function representationGuard(before, after, { headerUpdate = false } = {}) {
+  const blockers = [];
+  if (!after.ok) blockers.push(...(after.blockers || ['post-repair-structure-unavailable']));
+  if (before.body !== after.body) blockers.push('body-representation-changed');
+  if (!headerUpdate && before.envelope !== after.envelope) blockers.push('unapproved-header-representation-changed');
+  if (before.repairs !== after.repairs) blockers.push('repairs-provenance-changed');
+  const siblingFooterEntriesPreserved = JSON.stringify(before.siblingEntries) === JSON.stringify(after.siblingEntries);
+  if (!siblingFooterEntriesPreserved) blockers.push('unapproved-sibling-footer-entry-changed');
+  return Object.freeze({ ok: blockers.length === 0, blockers: Object.freeze(unique(blockers)), siblingFooterEntriesPreserved });
+}
+
+function splitLines(text) {
+  const out = [];
+  const source = String(text || '');
+  const re = /([^\r\n]*)(\r\n|\n|\r|$)/g;
+  let match;
+  while ((match = re.exec(source)) && (match[0] || re.lastIndex === 0)) {
+    if (match[0] === '' && re.lastIndex >= source.length) break;
+    out.push({ content: match[1], eol: match[2] });
+    if (!match[2]) break;
+  }
+  if (!out.length) out.push({ content: '', eol: '' });
+  return out;
+}
+function joinLines(lines) { return lines.map((line) => `${line.content}${line.eol}`).join(''); }
+function makeLine(content, eol) { return { content, eol }; }
+function preferredEol(lines) { return lines.find((line) => line.eol)?.eol || '\n'; }
+function replaceFieldLine(line, label, value) {
+  const match = line.content.match(new RegExp(`^(\\s+-\\s+${escapeRegExp(label)}:)([ \\t]*)(.*)$`));
+  if (!match) return line;
+  return { ...line, content: `${match[1]}${match[2]}${value}` };
+}
+function renderTowards(raw, target) { const match = String(raw || '').match(/^\[([^\]]+)\]\([^)]+\)$/); return match ? `[${match[1]}](${target})` : target; }
+function stripLink(value) { const match = String(value || '').match(/^\[([^\]]+)\]\([^)]+\)$/); return (match ? match[1] : String(value || '')).trim(); }
+function linkTargetOrText(value) { const match = String(value || '').match(/^\[[^\]]+\]\(([^)]+)\)$/); return (match ? match[1] : String(value || '')).trim(); }
+function firstRuleIndex(lines) { return lines.findIndex((line) => /^---[ \t]*$/.test(line.content)); }
+function topLevelBlock(lines, marker, limit) { const start = lines.findIndex((line, index) => index < limit && line.content === marker); if (start < 0) return null; let end = limit; for (let i = start + 1; i < limit; i += 1) if (/^-\s+\S/.test(lines[i].content)) { end = i; break; } return { start, end }; }
+function findInRange(lines, start, end, regex) { for (let i = start; i < end; i += 1) if (regex.test(lines[i].content)) return i; return -1; }
+function nestedListEnd(lines, start, end, parentIndent) { for (let i = start; i < end; i += 1) { const indent = (lines[i].content.match(/^\s*/) || [''])[0].length; if (/^\s*-\s+\S/.test(lines[i].content) && indent <= parentIndent) return i; } return end; }
+function envelopeBlockRaw(lines, rule, marker) { const start = lines.findIndex((line, index) => index < rule && line.content === marker); if (start < 0) return ''; let end = rule; for (let i = start + 1; i < rule; i += 1) if (/^-\s+\S/.test(lines[i].content)) { end = i; break; } return joinLines(lines.slice(start, end)); }
+function basename(value) { const clean = String(value || '').replace(/[?#].*$/, '').replace(/\/+$/, ''); return clean.split('/').pop() || ''; }
+function unique(values) { return [...new Set((values || []).map(String).filter(Boolean))]; }
+function escapeRegExp(value) { return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function fail(...blockers) { return Object.freeze({ ok: false, blockers: Object.freeze(unique(blockers.flat())) }); }