@tiinex/core 0.31.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.31.0",
+  "version": "0.33.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": "54c359f5d721194579aec2089cae096643912f07",
+  "gitHead": "a317bd83e450d04e6e9b0a5229944d958b61eb91",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "54c359f5d721194579aec2089cae096643912f07",
-    "sourceTree": "fbf8219dabf97f9939544b63387372c2c705726e",
+    "sourceCommit": "a317bd83e450d04e6e9b0a5229944d958b61eb91",
+    "sourceTree": "7f7ff3bb4a7926eb901476d777630c3d536ebed2",
     "repository": "Tiinex/core",
-    "previousVersion": "0.30.0"
+    "previousVersion": "0.32.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/adapters/cli/cli.handoff-sibling-allocation.js

@@ -30,7 +30,26 @@ export function deriveHandoffSiblingAllocation({ parentInspection = null, select
     workspaceId: String(route.workspaceId || '').trim(),
     workspaceRelativeHandoffPath: String(route.workspaceRelativeHandoffPath || '').trim()
   }));
-  if (!routes.length) return blocked('qualified-parent-route-topology-empty');
+  if (!routes.length) {
+    const siblingIndex = 1;
+    if (explicit && explicit !== siblingIndex) return blocked('explicit-sibling-index-conflicts-with-qualified-pointerless-topology', { expectedSiblingIndex: siblingIndex });
+    return freeze({
+      state: 'qualified',
+      siblingIndex,
+      childDimension: parentDimension ? `${String(parentDimension).trim()}-${siblingIndex}` : '',
+      allocationMode: 'qualified-parent-pointerless-default',
+      explicitOverride: explicit ? 'matched-derived-value' : 'not-supplied',
+      reasonCode: '',
+      provenance: {
+        ...provenanceBase({ parentPackagePath, parentPackageSha256, parentDimension, explicitSiblingIndex: explicit }),
+        basis: 'qualified-parent-pointerless-default',
+        routeOrdinal: siblingIndex,
+        qualifiedRouteCount: 0,
+        pointerOrder: []
+      },
+      boundary: allocationBoundary()
+    });
+  }
 
   const qualified = [];
   const seenDimensions = new Set();

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/authoring.parent.js

@@ -2,6 +2,7 @@ import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
 import { auditPortableRecord } from '../audit/audit.capability.js';
 import { classifyParentRecoveryReference } from '../../../lineage/parentRecoveryReference.js';
 import { buildArtifactCreationContract } from '../../../schemas/creation.contracts.js';
+import { canonicalC14nV2SelfState } from '../../../integrity/integrity.c14nV2.js';
 
 export const PORTABLE_AUTHORING_PARENT_SCHEMA_ID = 'tiinex.portable.authoring-parent.v1';
 
@@ -12,8 +13,15 @@ export function projectPortableAuthoringParent(input = {}) {
   let parsed;
   try { parsed = parseArtifactMarkdown(record.markdown); }
   catch { return freeze({ schema: PORTABLE_AUTHORING_PARENT_SCHEMA_ID, status: 'blocked', parentRecord: null, findings: [{ severity: 'error', code: 'portable.authoring-parent.parse-failed', message: 'Selected Parent bytes are not a readable Tiinex artifact.' }], operationBoundary: boundary() }); }
-  const audit = auditPortableRecord({ ...record, title: parsed.title, schemaId: parsed.envelope?.current?.schema?.id, currentSchemaId: parsed.envelope?.current?.schema?.id, parent: parsed.envelope?.parent });
-  if (audit.status !== 'readable' || audit.qualification?.exact !== true || (audit.findings || []).some((item) => item.severity === 'error')) return freeze({ schema: PORTABLE_AUTHORING_PARENT_SCHEMA_ID, status: 'blocked', parentRecord: null, findings: [{ severity: 'error', code: 'portable.authoring-parent.unqualified', message: 'Selected Parent must pass exact shared audit before it can be used for native authoring.' }], operationBoundary: boundary() });
+  const audit = auditPortableRecord({ ...record, title: parsed.title, schemaId: parsed.envelope?.current?.schema?.id, currentSchemaId: parsed.envelope?.current?.schema?.id, parent: parsed.envelope?.parent }, { requireExactSchemaAuthority: true });
+  const auditErrors = (audit.findings || []).filter((item) => item.severity === 'error');
+  const historicalParentRecoveryDebt = auditErrors.length > 0 && auditErrors.every((item) => String(item.code || '') === 'root.parent.recovery.workspace-qualified.malformed');
+  const selfIntegrity = canonicalC14nV2SelfState(record.markdown || '');
+  const directParentUsableWithHistoricalDebt = historicalParentRecoveryDebt
+    && audit.qualification?.exact === true
+    && audit.schemaValidationAuthority?.state === 'qualified'
+    && selfIntegrity.state === 'verified';
+  if ((audit.status !== 'readable' && !directParentUsableWithHistoricalDebt) || audit.qualification?.exact !== true || (auditErrors.length && !directParentUsableWithHistoricalDebt)) return freeze({ schema: PORTABLE_AUTHORING_PARENT_SCHEMA_ID, status: 'blocked', parentRecord: null, findings: [{ severity: 'error', code: 'portable.authoring-parent.unqualified', message: 'Selected Parent must pass exact shared audit before it can be used for native authoring.' }], operationBoundary: boundary() });
   const schemaId = String(parsed.envelope?.current?.schema?.id || audit.schemaId || '');
   const schemaTarget = String(parsed.envelope?.current?.schema?.target || '');
   const createdAt = String(parsed.envelope?.current?.createdAt || audit.artifact?.createdAt || '');
@@ -36,9 +44,11 @@ export function projectPortableAuthoringParent(input = {}) {
       markdown: record.markdown, sourceMode: String(record.sourceMode || 'portable-node-local'),
       schemaReferenceAuthority
     },
-    findings: [],
+    findings: directParentUsableWithHistoricalDebt ? [{ severity: 'warning', code: 'portable.authoring-parent.historical-ancestor-recovery-debt', message: 'Selected Parent has historical malformed Workspace-qualified recovery references to its own ancestor. Direct child authoring is allowed from the Parent exact current bytes and verified self integrity; that ancestor debt is not repaired, inherited, or upgraded.' }] : [],
     operationBoundary: boundary(),
-    boundary: 'Projects exact supplied Parent bytes and declared current schema locator into shared draft-authoring input. A declared schema locator remains unresolved and is not upgraded to publication or canonical reference authority.'
+    boundary: directParentUsableWithHistoricalDebt
+      ? 'Projects exact supplied Parent current bytes for direct continuation while preserving unresolved historical ancestor-recovery debt on the Parent itself. The child does not inherit or repair that ancestor locator.'
+      : 'Projects exact supplied Parent bytes and declared current schema locator into shared draft-authoring input. A declared schema locator remains unresolved and is not upgraded to publication or canonical reference authority.'
   });
 }
 

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

@@ -5,6 +5,7 @@ import { integrityMethodReferenceAuthorityForCreation } from '../../../integrity
 import { inspectPortableLineageIntegrity } from '../lineage/lineage.integrity.plan.js';
 import { portableFinding } from '../findings.js';
 import { qualifyTiinexRouteArtifact } from '../handoff/routeArtifactConformance.js';
+import { classifyParentRecoveryReference } from '../../../lineage/parentRecoveryReference.js';
 
 export const PORTABLE_EDITOR_ASSISTANCE_SCHEMA_ID = 'tiinex.portable.editor-assistance.v1';
 
@@ -13,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,
@@ -24,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 || '');
@@ -49,9 +50,37 @@ function projectDocument(record = {}, records = [], lineageInspection = null) {
     diagnosticCodes: workspacePackagingRepair.diagnosticCodes,
     boundary: 'Repairs only a tiinex.workspace.v1 artifact whose replacement independently qualifies through the same exact registered Workspace contract and c14n-v2 self-integrity requirements used by Handoff package manufacture. Existing resolver-capable Current Schema references are preserved; permalink refresh is a separate resolution operation and must not be inferred from integrity repair.'
   }));
-  const integrityRepair = deterministicIntegrityHygieneRepair(markdown, audit.findings || []);
+  const referenceRepair = deterministicReferenceHygieneRepair(record, audit, markdown);
+  const referenceQualification = referenceRepair.state === 'ready'
+    ? qualifyReplacementAgainstSharedGuardrails(record, records, referenceRepair.markdown, {
+      allowQualifiedExternalParentUnresolved: true,
+      allowExistingWarningCodes: (audit.findings || []).filter((item) => item.severity === 'warning').map((item) => String(item.code || ''))
+    })
+    : { state: 'unavailable' };
+  if (referenceRepair.state === 'ready' && referenceRepair.markdown !== markdown && referenceQualification.state === 'qualified') actions.push(freeze({
+    id: 'repair-qualified-references-and-self-integrity',
+    title: referenceRepair.parentReferenceChanged && referenceRepair.schemaReferenceChanged
+      ? 'Repair Tiinex Parent/schema references and self integrity'
+      : referenceRepair.parentReferenceChanged
+        ? 'Repair Tiinex Parent references and self integrity'
+        : 'Repair Tiinex schema reference and self integrity',
+    kind: 'replace-document',
+    qualification: 'deterministic-shared-core',
+    sourceSha256: sha256Hex(new TextEncoder().encode(markdown)),
+    replacementMarkdown: referenceRepair.markdown,
+    diagnosticCodes: referenceRepair.diagnosticCodes,
+    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 referenceResolution = projectReferenceResolutionAssistance(markdown, referenceResolutions);
+  diagnostics.push(...referenceResolution.diagnostics);
+  actions.push(...referenceResolution.actions);
+
+  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',
@@ -117,25 +146,223 @@ function deterministicWorkspacePackagingRepair(record = {}, audit = {}, markdown
   return freeze({ state: 'ready', markdown: candidate, schemaReferenceChanged, diagnosticCodes });
 }
 
-function qualifyReplacementAgainstSharedGuardrails(record = {}, records = [], replacementMarkdown = '') {
+function qualifyReplacementAgainstSharedGuardrails(record = {}, records = [], replacementMarkdown = '', options = {}) {
   const focusPath = norm(record.path || record.id || '');
   if (!focusPath || !replacementMarkdown) return freeze({ state: 'unavailable', reason: 'replacement-or-focus-unavailable' });
   const replacedRecords = records.map((item) => norm(item.path || item.id || '') === focusPath ? { ...item, markdown: replacementMarkdown } : item);
   const replacementRecord = replacedRecords.find((item) => norm(item.path || item.id || '') === focusPath);
   if (!replacementRecord) return freeze({ state: 'unavailable', reason: 'focused-record-unavailable' });
   const replacementAudit = auditPortableRecord(replacementRecord, { requireExactSchemaAuthority: true });
-  const auditBlockers = [...(replacementAudit.findings || [])].filter((item) => item.severity === 'error' || item.severity === 'warning');
+  const allowedWarnings = new Set((options.allowExistingWarningCodes || []).map((item) => String(item || '')));
+  const auditBlockers = [...(replacementAudit.findings || [])].filter((item) => {
+    if (item.severity === 'error') return true;
+    if (item.severity !== 'warning') return false;
+    return !allowedWarnings.has(String(item.code || ''));
+  });
   if (auditBlockers.length) return freeze({ state: 'blocked', reason: 'replacement-shared-audit-not-clean', blockerCodes: auditBlockers.map((item) => String(item.code || '')) });
 
   const before = inspectPortableLineageIntegrity({ records });
   const after = inspectPortableLineageIntegrity({ records: replacedRecords });
   const beforeFocus = (before.artifacts || []).find((item) => norm(item.path || '') === focusPath);
   const affectedPaths = new Set([focusPath, ...((beforeFocus?.downstreamDescendants || []).map((item) => norm(item.path || '')).filter(Boolean))]);
-  const lineageBlockers = (after.artifacts || []).filter((item) => affectedPaths.has(norm(item.path || '')) && item.state !== 'healthy');
+  const lineageBlockers = (after.artifacts || []).filter((item) => {
+    if (!affectedPaths.has(norm(item.path || '')) || item.state === 'healthy') return false;
+    if (options.allowQualifiedExternalParentUnresolved === true && norm(item.path || '') === focusPath && item.state === 'parent-unresolved' && hasQualifiedWorkspaceParentReference(replacementMarkdown)) return false;
+    return true;
+  });
   if (lineageBlockers.length) return freeze({ state: 'blocked', reason: 'replacement-shared-lineage-not-clean', blockers: lineageBlockers.map((item) => ({ path: item.path, state: item.state })) });
   return freeze({ state: 'qualified', affectedPaths: [...affectedPaths] });
 }
 
+function deterministicReferenceHygieneRepair(record = {}, audit = {}, markdown = '') {
+  const source = String(markdown || '');
+  if (!source) return freeze({ state: 'unavailable' });
+  let candidate = source;
+  let parentReferenceChanged = false;
+  let schemaReferenceChanged = false;
+  const diagnosticCodes = [];
+
+  const lines = candidate.replace(/\r\n?/g, '\n').split('\n');
+  const parentStart = lines.findIndex((line) => /^\s*-\s+Parent\s*$/.test(line));
+  if (parentStart >= 0) {
+    let parentEnd = lines.length;
+    for (let index = parentStart + 1; index < lines.length; index += 1) {
+      if (/^-\s+\S/.test(lines[index])) { parentEnd = index; break; }
+    }
+    for (let index = parentStart + 1; index < parentEnd; index += 1) {
+      lines[index] = lines[index].replace(/\]\(([^)]+::[^)]+)\)/g, (whole, target) => {
+        const normalized = normalizeMalformedWorkspaceQualifiedTarget(target);
+        if (!normalized || normalized === target) return whole;
+        parentReferenceChanged = true;
+        return `](${normalized})`;
+      });
+    }
+  }
+  if (parentReferenceChanged) {
+    candidate = lines.join('\n');
+    const integrityLines = candidate.replace(/\r\n?/g, '\n').split('\n');
+    const integrityStart = integrityLines.findIndex((line) => line.trim() === '# Continuity Integrity');
+    if (integrityStart >= 0) {
+      for (let index = integrityStart + 1; index < integrityLines.length; index += 1) {
+        integrityLines[index] = integrityLines[index].replace(/\]\(([^)]+::[^)]+)\)/g, (whole, target) => {
+          const normalized = normalizeMalformedWorkspaceQualifiedTarget(target);
+          return normalized && normalized !== target ? `](${normalized})` : whole;
+        });
+      }
+      candidate = integrityLines.join('\n');
+    }
+    diagnosticCodes.push('root.parent.recovery.workspace-qualified.malformed', 'portable.lineage-integrity.parent-unresolved');
+  }
+
+  const exactTarget = String(audit?.schemaValidationAuthority?.currentReference?.target || '').trim();
+  const schemaId = String(audit?.schemaId || '').trim();
+  const schemaWarning = (audit?.findings || []).some((item) => String(item?.code || '') === 'schema.reference.exact-target-omitted');
+  if (schemaWarning && schemaId && exactTarget && audit?.schemaValidationAuthority?.currentReference?.state === 'qualified') {
+    const schemaLines = candidate.replace(/\r\n?/g, '\n').split('\n');
+    const index = schemaLines.findIndex((line) => /^\s*-\s+Current Schema:\s*/.test(line));
+    if (index >= 0) {
+      const match = schemaLines[index].match(/^(\s*-\s+Current Schema:\s*)([^\s].*)$/);
+      const raw = String(match?.[2] || '').trim();
+      if (match && raw === schemaId) {
+        schemaLines[index] = `${match[1]}[${schemaId}](${exactTarget})`;
+        candidate = schemaLines.join('\n');
+        schemaReferenceChanged = true;
+        diagnosticCodes.push('schema.reference.exact-target-omitted');
+      }
+    }
+  }
+
+  if (!parentReferenceChanged && !schemaReferenceChanged) return freeze({ state: 'unavailable' });
+  const sealed = sealC14nV2Self(candidate);
+  if (sealed.state !== 'sealed' && sealed.state !== 'unchanged') return freeze({ state: 'unavailable' });
+  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;
+  const stripped = raw.replace(/^(?:\.\.\/)+/, '').replace(/^\.\//, '');
+  return classifyParentRecoveryReference(stripped).kind === 'workspace-qualified' ? stripped : raw;
+}
+
+function hasQualifiedWorkspaceParentReference(markdown = '') {
+  const source = String(markdown || '');
+  const parentStart = source.split(/\r?\n/).findIndex((line) => /^\s*-\s+Parent\s*$/.test(line));
+  if (parentStart < 0) return false;
+  const lines = source.split(/\r?\n/);
+  let parentEnd = lines.length;
+  for (let index = parentStart + 1; index < lines.length; index += 1) if (/^-\s+\S/.test(lines[index])) { parentEnd = index; break; }
+  const targets = [];
+  for (let index = parentStart + 1; index < parentEnd; index += 1) {
+    for (const match of lines[index].matchAll(/\]\(([^)]+)\)/g)) targets.push(String(match[1] || ''));
+  }
+  return targets.some((target) => classifyParentRecoveryReference(target).kind === 'workspace-qualified');
+}
+
 function projectDiagnostic(finding = {}, markdown = '') {
   const located = locateFindingLine(finding, markdown);
   return freeze({
@@ -164,6 +391,25 @@ 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 resolving `field:Value` first would
+  // incorrectly anchor a self-integrity finding on the first Parent digest.
+  // Resolve semantically-owned integrity locations before generic field lookup.
+  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();
@@ -178,19 +424,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');
@@ -209,6 +451,20 @@ export function locateFindingLine(finding = {}, markdown = '') {
   return freeze({ state: 'unresolved', line: null, sourceRange: null, basis: 'shared-finding-has-no-deterministic-line-evidence' });
 }
 
+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 deterministicIntegrityHygieneRepair(markdown = '', findings = []) {
   const source = String(markdown || '');
   const codes = new Set((findings || []).map((item) => String(item?.code || '')));
@@ -240,7 +496,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)] });
 }