@tiinex/core 0.32.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Shared host-neutral Tiinex implementation core for artifacts, schemas, validation, lineage, grounding, Handoffs, provenance and deterministic workflows.",
   "type": "module",
   "sideEffects": true,
@@ -173,12 +173,12 @@
     "type": "git",
     "url": "git+https://github.com/Tiinex/core.git"
   },
-  "gitHead": "036df699dd3a0455f849c4c4e421fee7c969e85a",
+  "gitHead": "873ac202d2f12a6fbf43437c61b198a85dd7afb3",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "036df699dd3a0455f849c4c4e421fee7c969e85a",
-    "sourceTree": "540c88695f9de86c928a737e1ea2c51b5be5cd82",
+    "sourceCommit": "873ac202d2f12a6fbf43437c61b198a85dd7afb3",
+    "sourceTree": "90fab47ce492c14411836043f221511212b5471e",
     "repository": "Tiinex/core",
-    "previousVersion": "0.31.0"
+    "previousVersion": "0.33.0"
   }
 }

package/src/schemas/creation.contracts.js

@@ -10,6 +10,7 @@ import { projectPortableValidationContractWithQualifiedLocalRoot } from '../tool
 import { qualifyRootCreationRepresentation, qualifyContinuationCreationRepresentation } from './creation.representation.js';
 import { qualifyCreationSchemaReferences, schemaReferenceAuthoritiesForCreation } from './creation.schemaReferences.js';
 import { qualifySchemaReferenceValue } from './schema.reference.js';
+import { qualifiedCreationAuthorityFromSchemaSource } from './schema.source.js';
 import { C14N_V2_METHOD_ID, integrityMethodReferenceAuthorityForCreation } from '../integrity/integrity.methodReference.js';
 
 export const ARTIFACT_CREATION_CONTRACT_SCHEMA_ID = 'tiinex.artifact.creation.contract.v1';
@@ -39,16 +40,7 @@ export function buildArtifactCreationContract(input = {}, options = {}) {
   const transitionType = String(input.transitionType || options.transitionType || 'create-artifact').trim();
   const creationCapability = qualifyArtifactCreationCapability(module, transitionType);
   const creationAuthority = creationCapability.authority?.compiledContract?.creation || {};
-  const creation = Object.freeze({
-    requiredInputs: list(creationAuthority.requiredInputs),
-    optionalInputs: list(creationAuthority.optionalInputs),
-    requiredSections: list(creationAuthority.requiredSections),
-    representationSections: list(creationAuthority.representationSections),
-    toolingConfigurationFields: list(creationAuthority.toolingConfigurationFields),
-    inputBindings: list(creationAuthority.inputBindings),
-    supplementalRequiredFields: list(creationAuthority.supplementalRequiredFields),
-    requiredShape: list(creationAuthority.requiredShape)
-  });
+  const creation = composeCreationAuthority(module, creationCapability.authority, creationAuthority);
   const renderer = creationCapability.implementation?.state === 'implemented'
     ? { status: CapabilityStatus.implemented, ...(creationCapability.implementation.renderer || {}) }
     : { status: CapabilityStatus.unavailable, id: '', scope: transitionType };
@@ -203,6 +195,96 @@ export function validateArtifactCreationResult(draft = {}, parentRecord = {}, op
 
 
 
+
+function composeCreationAuthority(module = null, authority = {}, localCreation = {}) {
+  const validationContract = authority?.compiledContract?.validationContract || null;
+  const lineage = Array.isArray(validationContract?.lineage) && validationContract.lineage.length
+    ? validationContract.lineage
+    : [String(module?.id || authority?.schemaId || '')].filter(Boolean);
+  const creationAuthorities = [];
+  for (const schemaId of lineage) {
+    const lineageModule = schemaRegistry.byId?.get(schemaId) || null;
+    if (!lineageModule) continue;
+    const qualified = qualifiedCreationAuthorityFromSchemaSource(lineageModule);
+    if (qualified.state !== 'qualified' || !qualified.compiledContract?.creation) continue;
+    creationAuthorities.push({ schemaId, creation: qualified.compiledContract.creation });
+  }
+  if (!creationAuthorities.length) creationAuthorities.push({ schemaId: String(module?.id || ''), creation: localCreation });
+
+  const requiredHeadingOrder = [...(validationContract?.validation?.requiredHeadings || [])]
+    .filter((item) => Number(item?.level || 0) === 2 && String(item?.title || '').trim())
+    .map((item) => String(item.title).trim());
+  const requiredHeadingSet = new Set(requiredHeadingOrder);
+  const bindingByInput = new Map();
+  const requiredInputSet = new Set();
+  const optionalInputSet = new Set();
+  const toolingFields = [];
+  const supplementalByKey = new Map();
+  const shapeByKey = new Map();
+
+  for (const entry of creationAuthorities) {
+    const creation = entry.creation || {};
+    for (const value of creation.requiredInputs || []) requiredInputSet.add(String(value || '').trim());
+    for (const value of creation.optionalInputs || []) optionalInputSet.add(String(value || '').trim());
+    for (const value of creation.toolingConfigurationFields || []) pushUnique(toolingFields, String(value || '').trim());
+    for (const item of creation.inputBindings || []) {
+      const input = String(item?.input || '').trim();
+      if (!input) continue;
+      const section = String(item?.section || '').trim();
+      if (section && requiredHeadingSet.size && !requiredHeadingSet.has(section)) continue;
+      bindingByInput.set(input, item);
+    }
+    for (const item of creation.supplementalRequiredFields || []) {
+      const section = String(item?.section || '').trim();
+      if (section && requiredHeadingSet.size && !requiredHeadingSet.has(section)) continue;
+      const key = `${section}\u0000${String(item?.field || '')}`;
+      supplementalByKey.set(key, item);
+    }
+    for (const item of creation.requiredShape || []) {
+      const primitive = item?.primitive || {};
+      const section = String(primitive?.section || '').trim();
+      if (section && requiredHeadingSet.size && !requiredHeadingSet.has(section)) continue;
+      const key = `${String(primitive?.kind || '')}\u0000${String(primitive?.input || '')}\u0000${section}\u0000${String(primitive?.position || '')}`;
+      shapeByKey.set(key, item);
+    }
+  }
+
+  const bindings = [];
+  for (const item of bindingByInput.values()) if (!String(item?.section || '').trim()) bindings.push(item);
+  for (const section of requiredHeadingOrder) {
+    for (const item of bindingByInput.values()) if (String(item?.section || '').trim() === section && !bindings.includes(item)) bindings.push(item);
+  }
+  for (const item of bindingByInput.values()) if (!bindings.includes(item)) bindings.push(item);
+
+  const boundInputs = new Set(bindings.map((item) => String(item?.input || '').trim()).filter(Boolean));
+  const requiredInputs = [...requiredInputSet].filter((input) => input && boundInputs.has(input));
+  const optionalInputs = [...optionalInputSet].filter((input) => input && boundInputs.has(input) && !requiredInputSet.has(input));
+  const requiredSections = requiredHeadingOrder.length
+    ? requiredHeadingOrder.filter((section) => bindings.some((item) => String(item?.section || '').trim() === section))
+    : uniqueStrings(creationAuthorities.flatMap((entry) => entry.creation?.requiredSections || []));
+  const representationSections = requiredSections.length
+    ? requiredSections
+    : uniqueStrings(bindings.map((item) => String(item?.section || '').trim()).filter(Boolean));
+
+  return Object.freeze({
+    requiredInputs: Object.freeze(requiredInputs),
+    optionalInputs: Object.freeze(optionalInputs),
+    requiredSections: Object.freeze(requiredSections),
+    representationSections: Object.freeze(representationSections),
+    toolingConfigurationFields: Object.freeze(toolingFields),
+    inputBindings: Object.freeze(bindings),
+    supplementalRequiredFields: Object.freeze([...supplementalByKey.values()]),
+    requiredShape: Object.freeze([...shapeByKey.values()])
+  });
+}
+
+function uniqueStrings(values = []) {
+  const out = [];
+  for (const value of values || []) pushUnique(out, String(value || '').trim());
+  return out;
+}
+function pushUnique(values, value) { if (value && !values.includes(value)) values.push(value); }
+
 function validateParentTargetIntegrity(parsed = {}, parentRecord = {}, expectedTarget = '') {
   const entries = (parsed?.integrity?.entries || []).filter((entry) => entry?.method === C14N_V2_METHOD_ID && String(entry?.towards || '') !== 'self');
   if (entries.length !== 1) return [];

package/src/schemas/creation.renderer.js

@@ -38,7 +38,7 @@ export function renderArtifactCreationDraftMarkdown(contract = {}, input = {}) {
   const lines = [
     '# Continuity Context', '',
     `- Envelope Schema: ${envelopeSchemaReference}`,
-    ...(parent ? renderParent(parent) : []),
+    ...(parent ? renderParent(parent, { preserveUnqualifiedSchemaReference: input.preserveUnqualifiedParentSchemaReference === true }) : []),
     '- Current',
     `  - Current Schema: ${currentSchemaReference}`,
     `  - Created At: ${createdAt}`,
@@ -69,10 +69,10 @@ export const genericArtifactCreationImplementation = Object.freeze({
   execute: renderArtifactCreationDraftMarkdown
 });
 
-function renderParent(parent) {
+function renderParent(parent, options = {}) {
   return [
     '- Parent',
-    `  - Parent Schema: ${renderSchemaReference(parent.schemaReferenceAuthority)}`,
+    `  - Parent Schema: ${renderParentSchemaReference(parent.schemaReferenceAuthority, options.preserveUnqualifiedSchemaReference === true)}`,
     ...(parent.createdAt ? [`  - Created At: ${parent.createdAt}`] : []),
     `  - Trace: [${parent.traceLabel}](${parent.traceReference})`,
     '  - Origin:',
@@ -81,6 +81,13 @@ function renderParent(parent) {
   ];
 }
 
+function renderParentSchemaReference(authority = {}, preserveUnqualified = false) {
+  const schemaId = String(authority?.schemaId || '').trim();
+  const preferredTarget = String(authority?.preferredTarget || authority?.target || '').trim();
+  if (preserveUnqualified && schemaId && preferredTarget) return `[${schemaId}](${preferredTarget})`;
+  return renderSchemaReference(authority);
+}
+
 function contractDrivenBodyMarkdown(contract = {}, { title = '', values = {} } = {}) {
   const creation = contract?.creation || {};
   const bindings = Array.isArray(creation.inputBindings) ? creation.inputBindings : [];

package/src/tooling/portable/adapters/cli/cli.editor-assistance.js

@@ -2,10 +2,13 @@ import { readFile } from 'node:fs/promises';
 
 export async function prepareEditorAssistanceCliInput(material = {}, flags = {}) {
   const focusPath = norm(flags.focus || flags.path || '');
-  if (!focusPath || !flags.overlay) return { input: { ...material, focusPath }, options: {} };
+  const referenceResolutions = flags['reference-resolutions']
+    ? JSON.parse(await readFile(String(flags['reference-resolutions']), 'utf8'))
+    : [];
+  if (!focusPath || !flags.overlay) return { input: { ...material, focusPath, referenceResolutions }, options: {} };
   const overlayMarkdown = await readFile(String(flags.overlay), 'utf8');
   const files = (material.files || []).map((file) => norm(file.path || '') === focusPath ? { ...file, content: overlayMarkdown } : file);
-  const input = { ...material, files, focusPath };
+  const input = { ...material, files, focusPath, referenceResolutions };
   if (Array.isArray(material.records)) input.records = material.records.map((record) => norm(record.path || record.id || '') === focusPath ? { ...record, markdown: overlayMarkdown } : record);
   return { input, options: {} };
 }

package/src/tooling/portable/draft/draft.exact.js

@@ -78,7 +78,7 @@ export function renderQualifiedPortableExactDraft({ contract = {}, schemaId = ''
 }
 
 export function renderPortableLocalContinuityDraft({ contract = {}, schemaId = '', transitionType = 'continue-from-record', parentSnapshot = {}, rendererInput = {} } = {}) {
-  const markdown = renderArtifactCreationCandidateMarkdown(contract, { ...rendererInput, parentRecord: parentSnapshot, currentSchemaId: schemaId });
+  const markdown = renderArtifactCreationCandidateMarkdown(contract, { ...rendererInput, parentRecord: parentSnapshot, currentSchemaId: schemaId, preserveUnqualifiedParentSchemaReference: true });
   if (!markdown) return Object.freeze({ state: 'unqualified', reason: 'local-continuity-renderer-empty', markdown: '', validation: null, parentRepresentation: null });
   const parentRepresentation = qualifyPortableRenderedParentRepresentation(markdown, parentSnapshot, transitionType, rendererInput.childPath || '', { allowUnpublishedLocalParent: true });
   if (parentRepresentation.state !== 'qualified') return Object.freeze({ state: 'unqualified', reason: parentRepresentation.reason || 'local-continuity-parent-representation-mismatch', markdown: '', validation: null, parentRepresentation });

package/src/tooling/portable/editor/editor.assistance.js

@@ -14,7 +14,7 @@ export function projectPortableEditorAssistance(input = {}) {
   const focusPath = norm(input.focusPath || input.focus || '');
   const selectedRecords = focusPath ? records.filter((record) => norm(record.path || record.id || '') === focusPath) : records;
   const lineageInspection = inspectPortableLineageIntegrity({ records });
-  const documents = selectedRecords.map((record) => projectDocument(record, records, lineageInspection));
+  const documents = selectedRecords.map((record) => projectDocument(record, records, lineageInspection, referenceResolutionsForRecord(input.referenceResolutions || [], record)));
   const diagnostics = documents.flatMap((item) => item.diagnostics);
   return freeze({
     schema: PORTABLE_EDITOR_ASSISTANCE_SCHEMA_ID,
@@ -25,7 +25,7 @@ export function projectPortableEditorAssistance(input = {}) {
   });
 }
 
-function projectDocument(record = {}, records = [], lineageInspection = null) {
+function projectDocument(record = {}, records = [], lineageInspection = null, referenceResolutions = []) {
   const audit = auditPortableRecord(record, { requireExactSchemaAuthority: true });
   const markdown = String(record.markdown || '');
   const recordPath = norm(record.path || record.id || '');
@@ -72,9 +72,33 @@ function projectDocument(record = {}, records = [], lineageInspection = null) {
     boundary: 'Repairs only deterministically malformed Workspace-qualified Parent recovery locators and/or a bare Current Schema id when exact qualified current-schema source authority exists; reseals self integrity and exposes the replacement only after shared audit and loaded-descendant guardrails re-qualify it. External Parent availability is not invented.'
   }));
 
-  const integrityRepair = deterministicIntegrityHygieneRepair(markdown, audit.findings || []);
+  const referenceResolution = projectReferenceResolutionAssistance(markdown, referenceResolutions);
+  diagnostics.push(...referenceResolution.diagnostics);
+  actions.push(...referenceResolution.actions);
+
+  const lineageArtifact = (lineageInspection?.artifacts || []).find((item) => norm(item?.path || '') === recordPath) || null;
+  const parentIntegrityRepair = deterministicParentIntegrityRepair(markdown, lineageArtifact);
+  const parentRepairQualification = parentIntegrityRepair.state === 'ready'
+    ? qualifyReplacementAgainstSharedGuardrails(record, records, parentIntegrityRepair.markdown, {
+      allowExistingWarningCodes: sharedFindings.filter((item) => item.severity === 'warning').map((item) => String(item.code || ''))
+    })
+    : { state: 'unavailable' };
+  if (parentIntegrityRepair.state === 'ready' && parentIntegrityRepair.markdown !== markdown && parentRepairQualification.state === 'qualified') actions.push(freeze({
+    id: 'refresh-parent-integrity-and-self-seal',
+    title: 'Refresh Tiinex Parent integrity and self seal',
+    kind: 'replace-document',
+    qualification: 'deterministic-shared-core',
+    sourceSha256: sha256Hex(new TextEncoder().encode(markdown)),
+    replacementMarkdown: parentIntegrityRepair.markdown,
+    diagnosticCodes: ['portable.lineage-integrity.parent-target-mismatch', 'integrity.c14n-v2.mismatch', 'portable.lineage-integrity.child-self-mismatch'],
+    boundary: 'Refreshes only an existing Parent integrity digest whose declared locator already matches the exact resolved Parent and whose verified Parent self digest is available locally; the focused artifact is resealed and the action is withheld when loaded descendants would become inconsistent.'
+  }));
+
+  const integrityRepair = deterministicIntegrityHygieneRepair(markdown, sharedFindings);
   const repairQualification = integrityRepair.state === 'ready'
-    ? qualifyReplacementAgainstSharedGuardrails(record, records, integrityRepair.markdown)
+    ? qualifyReplacementAgainstSharedGuardrails(record, records, integrityRepair.markdown, {
+      allowExistingWarningCodes: sharedFindings.filter((item) => item.severity === 'warning').map((item) => String(item.code || ''))
+    })
     : { state: 'unavailable' };
   if (integrityRepair.state === 'ready' && integrityRepair.markdown !== markdown && repairQualification.state === 'qualified') actions.push(freeze({
     id: 'refresh-primary-self-integrity',
@@ -232,6 +256,110 @@ function deterministicReferenceHygieneRepair(record = {}, audit = {}, markdown =
   return freeze({ state: 'ready', markdown: String(sealed.markdown || candidate), parentReferenceChanged, schemaReferenceChanged, diagnosticCodes: [...new Set(diagnosticCodes)] });
 }
 
+function referenceResolutionsForRecord(resolutions = [], record = {}) {
+  const recordPath = norm(record.path || record.id || '');
+  return (Array.isArray(resolutions) ? resolutions : []).filter((item) => {
+    const itemPath = norm(item?.path || '');
+    return !itemPath || itemPath === recordPath;
+  });
+}
+
+function projectReferenceResolutionAssistance(markdown = '', resolutions = []) {
+  const source = String(markdown || '');
+  if (!source || !Array.isArray(resolutions) || !resolutions.length) return freeze({ diagnostics: [], actions: [] });
+  const byTarget = new Map(resolutions.map((item) => [String(item?.target || '').trim(), item]).filter(([target]) => Boolean(target)));
+  const references = versionBearingGitHubReferences(source).filter((item) => byTarget.has(item.target));
+  const diagnostics = [];
+  const actions = [];
+  for (const reference of references) {
+    const fact = byTarget.get(reference.target) || {};
+    const exact = fact.exact || {};
+    const latest = fact.latest || {};
+    const exactState = String(exact.state || 'unavailable');
+    const latestState = String(latest.state || 'unavailable');
+    const exactSha = String(exact.sha256 || '');
+    const latestSha = String(latest.sha256 || '');
+    const latestTarget = String(latest.target || '').trim();
+    let diagnostic = null;
+    let actionTitle = '';
+    if (exactState === 'missing') {
+      diagnostic = {
+        severity: 'error',
+        code: 'reference.permalink.unresolved',
+        message: `${reference.field} permalink does not resolve at its declared revision.`,
+        params: { field: reference.field, line: reference.line }
+      };
+      if (latestState === 'resolved' && latestTarget) actionTitle = `Repair ${reference.field} permalink to latest`;
+    } else if (exactState === 'unavailable') {
+      diagnostic = {
+        severity: 'warning',
+        code: 'reference.permalink.verification-unavailable',
+        message: `${reference.field} permalink could not be verified from the current host.`,
+        params: { field: reference.field, line: reference.line }
+      };
+      if (latestState === 'resolved' && latestTarget) actionTitle = `Use latest ${reference.field} permalink`;
+    } else if (exactState === 'resolved' && latestState === 'resolved' && exactSha && latestSha && exactSha !== latestSha) {
+      diagnostic = {
+        severity: 'warning',
+        code: 'reference.permalink.stale',
+        message: `${reference.field} permalink resolves, but master contains different bytes.`,
+        params: { field: reference.field, line: reference.line }
+      };
+      if (latestTarget) actionTitle = `Upgrade ${reference.field} permalink to latest`;
+    }
+    if (diagnostic) diagnostics.push(projectDiagnostic(diagnostic, source));
+    if (!actionTitle || !latestTarget || latestTarget === reference.target) continue;
+    const replacement = replaceReferenceTargetAtLine(source, reference, latestTarget);
+    if (!replacement || replacement === source) continue;
+    const sealed = sealIfSelfIntegrityPresent(replacement);
+    if (sealed.state === 'blocked') continue;
+    const replacementMarkdown = sealed.markdown;
+    actions.push(freeze({
+      id: `upgrade-permalink-${reference.field.toLowerCase().replace(/[^a-z0-9]+/g, '-')}-${reference.line}`,
+      title: actionTitle,
+      kind: 'replace-document',
+      qualification: 'deterministic-shared-core+explicit-host-resolution',
+      sourceSha256: sha256Hex(new TextEncoder().encode(source)),
+      replacementMarkdown,
+      diagnosticCodes: diagnostic ? [diagnostic.code] : [],
+      boundary: 'Uses explicit host-provided resolution evidence for the exact declared GitHub permalink and master candidate. A newer master revision is only offered as an operator-selected Quick Fix; it does not silently replace version-bearing source authority.'
+    }));
+  }
+  return freeze({ diagnostics, actions });
+}
+
+function versionBearingGitHubReferences(markdown = '') {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const refs = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = String(lines[index] || '');
+    const fieldMatch = line.match(/^\s*-\s+(Envelope Schema|Parent Schema|Current Schema)\s*:\s*\[[^\]]+\]\((https:\/\/github\.com\/[^)]+\/blob\/[^)]+)\)\s*$/i);
+    if (fieldMatch) refs.push({ field: fieldMatch[1], target: fieldMatch[2], line: index + 1 });
+    if (/^\s*-\s+\[sha256-base64url-c14n-v2\]\(/.test(line)) {
+      const methodMatch = line.match(/^\s*-\s+\[sha256-base64url-c14n-v2\]\((https:\/\/github\.com\/[^)]+\/blob\/[^)]+)\)\s*$/i);
+      if (methodMatch) refs.push({ field: 'Integrity method', target: methodMatch[1], line: index + 1 });
+    }
+  }
+  return refs;
+}
+
+function replaceReferenceTargetAtLine(markdown = '', reference = {}, latestTarget = '') {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const index = Number(reference.line || 0) - 1;
+  if (index < 0 || index >= lines.length) return '';
+  if (!lines[index].includes(reference.target)) return '';
+  lines[index] = lines[index].replace(reference.target, latestTarget);
+  return lines.join('\n');
+}
+
+function sealIfSelfIntegrityPresent(markdown = '') {
+  const state = canonicalC14nV2SelfState(markdown);
+  if (state.state === 'unavailable') return freeze({ state: 'ready', markdown: String(markdown || '') });
+  if (!['verified', 'mismatch', 'prepared'].includes(state.state)) return freeze({ state: 'blocked', markdown: String(markdown || '') });
+  const sealed = sealC14nV2Self(markdown);
+  return sealed.state === 'sealed' ? freeze({ state: 'ready', markdown: sealed.markdown }) : freeze({ state: 'blocked', markdown: String(markdown || '') });
+}
+
 function normalizeMalformedWorkspaceQualifiedTarget(value = '') {
   const raw = String(value || '').trim();
   if (classifyParentRecoveryReference(raw).kind !== 'malformed-workspace-qualified') return raw;
@@ -281,6 +409,28 @@ function locatedLine(lines = [], index = -1, state = 'deterministic', basis = ''
 export function locateFindingLine(finding = {}, markdown = '') {
   const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
   const params = finding.params || finding;
+  const code = String(finding.code || '');
+
+  // Integrity findings often carry the generic field name `Value`. That field
+  // appears once per integrity relation, so resolve semantically-owned relation
+  // locations before generic field lookup.
+  if (code === 'portable.lineage-integrity.parent-target-mismatch') {
+    const parentValueIndex = primaryParentIntegrityValueLine(lines);
+    if (parentValueIndex >= 0) return locatedLine(lines, parentValueIndex, 'deterministic', 'continuity-integrity-primary-parent-value');
+  }
+  if (code === 'integrity.c14n-v2.mismatch' || code === 'integrity.c14n-v2.ambiguous' || code === 'portable.lineage-integrity.child-self-mismatch' || code === 'portable.lineage-integrity.child-self-unavailable') {
+    const selfValueIndex = primarySelfIntegrityValueLine(lines);
+    if (selfValueIndex >= 0) return locatedLine(lines, selfValueIndex, 'deterministic', 'continuity-integrity-primary-self-value');
+  }
+  if (code === 'integrity.method-reference.unqualified') {
+    const headingIndex = lines.findIndex((line) => line.trim() === '# Continuity Integrity');
+    const methodIndex = lines.findIndex((line, index) => index > headingIndex && /^\s*-\s+\[sha256-base64url-c14n-v2\]\([^)]+\)\s*$/.test(line));
+    if (methodIndex >= 0) return locatedLine(lines, methodIndex, 'deterministic', 'continuity-integrity-method-reference');
+  }
+
+  const explicitLine = Number(params.line || 0);
+  if (Number.isInteger(explicitLine) && explicitLine > 0) return locatedLine(lines, explicitLine - 1, 'deterministic', 'explicit-resolution-line');
+
   const field = String(params.field || '').trim();
   const section = String(params.section || '').trim();
   const heading = String(params.heading || '').replace(/^#{1,6}\s+/, '').trim();
@@ -295,19 +445,15 @@ export function locateFindingLine(finding = {}, markdown = '') {
     const envelopeIndex = lines.findIndex((line) => new RegExp(`^\\s*-\\s+${escapeRegExp(owner)}(?:\\s*:.*)?\\s*$`, 'i').test(line));
     if (envelopeIndex >= 0) return locatedLine(lines, envelopeIndex, 'deterministic-anchor', `envelope-owner:${owner}`);
   }
-  const code = String(finding.code || '');
   if (code.includes('schema.') || code.endsWith('.schema.mismatch') || code === 'audit.schema-authority.unqualified') {
     const index = lines.findIndex((line) => /^\s*-\s+Current Schema\s*:/.test(line));
     if (index >= 0) return locatedLine(lines, index, 'deterministic', 'current-schema-field');
   }
-  if (code === 'integrity.method-reference.unqualified') {
-    const headingIndex = lines.findIndex((line) => line.trim() === '# Continuity Integrity');
-    const methodIndex = lines.findIndex((line, index) => index > headingIndex && /^\s*-\s+\[sha256-base64url-c14n-v2\]\([^)]+\)\s*$/.test(line));
-    if (methodIndex >= 0) return locatedLine(lines, methodIndex, 'deterministic', 'continuity-integrity-method-reference');
-  }
   if (code.includes('integrity') || /integrity|checksum|digest/i.test(String(finding.message || ''))) {
     const headingIndex = lines.findIndex((line) => line.trim() === '# Continuity Integrity');
     if (headingIndex >= 0) {
+      const selfValueIndex = primarySelfIntegrityValueLine(lines);
+      if (selfValueIndex >= 0 && /self-integrity|canonical artifact bytes|child-self/i.test(String(finding.message || ''))) return locatedLine(lines, selfValueIndex, 'deterministic', 'continuity-integrity-primary-self-value');
       const index = lines.findIndex((line, i) => i > headingIndex && /^\s+-\s+Value\s*:/.test(line));
       if (index >= 0) return locatedLine(lines, index, 'deterministic', 'continuity-integrity-value');
       return locatedLine(lines, headingIndex, 'deterministic-anchor', 'continuity-integrity-heading');
@@ -326,6 +472,75 @@ export function locateFindingLine(finding = {}, markdown = '') {
   return freeze({ state: 'unresolved', line: null, sourceRange: null, basis: 'shared-finding-has-no-deterministic-line-evidence' });
 }
 
+function primaryParentIntegrityValueLine(lines = []) {
+  const headingIndex = lines.findIndex((line) => String(line || '').trim() === '# Continuity Integrity');
+  if (headingIndex < 0) return -1;
+  let parentTowards = -1;
+  for (let index = headingIndex + 1; index < lines.length; index += 1) {
+    const line = String(lines[index] || '');
+    if (index > headingIndex + 1 && /^#\s+/.test(line)) break;
+    const towards = line.match(/^\s+-\s+Towards\s*:\s*(.+?)\s*$/i);
+    if (towards) {
+      parentTowards = String(towards[1] || '').trim().toLowerCase() === 'self' ? -1 : index;
+      continue;
+    }
+    if (parentTowards >= 0 && /^\s+-\s+Value\s*:/.test(line)) return index;
+    if (parentTowards >= 0 && /^-\s+/.test(line)) parentTowards = -1;
+  }
+  return -1;
+}
+
+function primarySelfIntegrityValueLine(lines = []) {
+  const headingIndex = lines.findIndex((line) => String(line || '').trim() === '# Continuity Integrity');
+  if (headingIndex < 0) return -1;
+  let selfTowards = -1;
+  for (let index = headingIndex + 1; index < lines.length; index += 1) {
+    const line = String(lines[index] || '');
+    if (index > headingIndex + 1 && /^#\s+/.test(line)) break;
+    if (/^\s+-\s+Towards\s*:\s*self\s*$/i.test(line)) { selfTowards = index; continue; }
+    if (selfTowards >= 0 && /^\s+-\s+Value\s*:/.test(line)) return index;
+    if (selfTowards >= 0 && /^-\s+/.test(line)) selfTowards = -1;
+  }
+  return -1;
+}
+
+function deterministicParentIntegrityRepair(markdown = '', artifact = null) {
+  const source = String(markdown || '');
+  if (!source || !artifact || artifact.state !== 'parent-target-mismatch') return freeze({ state: 'unavailable' });
+  if (String(artifact?.parentTarget?.reason || '') !== 'target-self-digest-mismatch') return freeze({ state: 'unavailable' });
+  if (artifact?.parentAvailability?.state !== 'resolved' || artifact?.parentPrimarySelf?.state !== 'verified') return freeze({ state: 'unavailable' });
+  const declaredTarget = String(artifact?.parentTarget?.declaredTarget || '').trim();
+  const expectedTarget = String(artifact?.exactParent?.expectedIntegrityTarget || '').trim();
+  const digest = String(artifact?.repairCandidate?.candidateTargetDigest || artifact?.parentPrimarySelf?.value || '').trim();
+  if (!declaredTarget || !expectedTarget || declaredTarget !== expectedTarget || !digest) return freeze({ state: 'unavailable' });
+
+  const lines = source.replace(/\r\n?/g, '\n').split('\n');
+  const headingIndex = lines.findIndex((line) => String(line || '').trim() === '# Continuity Integrity');
+  if (headingIndex < 0) return freeze({ state: 'unavailable' });
+  let targetMatched = false;
+  let changed = false;
+  for (let index = headingIndex + 1; index < lines.length; index += 1) {
+    const line = String(lines[index] || '');
+    if (index > headingIndex + 1 && /^#\s+/.test(line)) break;
+    const towards = line.match(/^\s+-\s+Towards\s*:\s*(?:\[[^\]]+\]\(([^)]+)\)|(\S.*))\s*$/i);
+    if (towards) {
+      const value = String(towards[1] || towards[2] || '').trim();
+      targetMatched = value === declaredTarget;
+      continue;
+    }
+    if (targetMatched && /^(\s+-\s+Value\s*:\s*)(.*)$/.test(line)) {
+      const match = line.match(/^(\s+-\s+Value\s*:\s*)(.*)$/);
+      lines[index] = `${match?.[1] || '  - Value: '}${digest}`;
+      changed = String(match?.[2] || '').trim() !== digest;
+      break;
+    }
+  }
+  if (!changed) return freeze({ state: 'unavailable' });
+  const sealed = sealC14nV2Self(lines.join('\n'));
+  if (sealed.state !== 'sealed' && sealed.state !== 'unchanged') return freeze({ state: 'unavailable' });
+  return freeze({ state: 'ready', markdown: String(sealed.markdown || lines.join('\n')) });
+}
+
 function deterministicIntegrityHygieneRepair(markdown = '', findings = []) {
   const source = String(markdown || '');
   const codes = new Set((findings || []).map((item) => String(item?.code || '')));
@@ -357,7 +572,9 @@ function deterministicIntegrityHygieneRepair(markdown = '', findings = []) {
   const diagnosticCodes = [
     ...(methodReferenceChanged ? ['integrity.method-reference.unqualified'] : []),
     'integrity.c14n-v2.mismatch',
-    'integrity.c14n-v2.ambiguous'
+    'integrity.c14n-v2.ambiguous',
+    'portable.lineage-integrity.child-self-mismatch',
+    'portable.lineage-integrity.child-self-unavailable'
   ];
   return freeze({ state: 'ready', markdown: sealed.markdown, methodReferenceChanged, diagnosticCodes: [...new Set(diagnosticCodes)] });
 }

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

@@ -223,11 +223,15 @@ function choosePrimaryState({ parentResolution, parentSchema, parentPrimarySelf,
     || consider(parentSchema.state !== 'verified', 'parent-schema-unavailable', parentSchema.reason)
     || consider(parentPrimarySelf.state === 'mismatch', 'parent-self-mismatch', parentPrimarySelf.reason)
     || consider(parentPrimarySelf.state !== 'verified', 'parent-self-unavailable', parentPrimarySelf.reason)
-    || consider(childSelf.state === 'mismatch', 'child-self-mismatch', childSelf.reason)
-    || consider(childSelf.state !== 'verified', 'child-self-unavailable', childSelf.reason)
+    // Parent-target corruption is more specific than the consequential child-self
+    // mismatch caused by changing footer bytes. Surface the owned Parent relation
+    // first so editors can locate and repair the actual mutated digest.
     || consider(targetInspection.state === 'missing', 'parent-target-missing', targetInspection.reason)
     || consider(targetInspection.state === 'mismatch', 'parent-target-mismatch', targetInspection.reason)
-    || consider(targetInspection.state !== 'verified', targetInspection.state === 'ambiguous' ? 'parent-target-ambiguous' : 'unsupported', targetInspection.reason)
+    || consider(targetInspection.state === 'ambiguous', 'parent-target-ambiguous', targetInspection.reason)
+    || consider(childSelf.state === 'mismatch', 'child-self-mismatch', childSelf.reason)
+    || consider(childSelf.state !== 'verified', 'child-self-unavailable', childSelf.reason)
+    || consider(targetInspection.state !== 'verified', 'unsupported', targetInspection.reason)
     || consider(publicationOrigin.state === 'contradictory', 'publication-origin-contradictory', publicationOrigin.reason)
     || consider(publicationOrigin.state === 'stale', 'publication-origin-stale', publicationOrigin.reason)
     || consider(publicationOrigin.state === 'unresolved', 'publication-origin-unresolved', publicationOrigin.reason)