@tiinex/core 0.1.1

package/src/tooling/portable/schema/contract.field-domain.js

@@ -0,0 +1,247 @@
+import { portableFinding } from '../findings.js';
+import { qualifyResolvedMachineShape } from './contract.machine-shape.js';
+
+export const PORTABLE_FIELD_DOMAIN_VALIDATION_SCHEMA_ID = 'tiinex.portable.field-domain-validation.v1';
+
+export function validatePortableFieldDomains(input = {}) {
+  const constraints = (input.constraints || []).filter((item) => item?.kind === 'field-domain');
+  const parsedDeclarations = input.parsedDeclarations || [];
+  const ordinary = input.ordinary || { groups: [] };
+  const findings = [];
+  const groups = [];
+
+  for (const constraint of constraints) {
+    const qualification = String(constraint.authorityQualification || constraint.declarationQualification || 'unresolved');
+    if (qualification === 'valid') continue;
+    const state = qualification === 'structurally-invalid' ? 'structurally-invalid' : 'unresolved';
+    findings.push(fieldDomainFinding(
+      state === 'structurally-invalid' ? 'error' : 'warning',
+      state === 'structurally-invalid'
+        ? 'portable.contract.field-domain.authority.invalid'
+        : 'portable.contract.field-domain.authority.unresolved',
+      `Field-domain authority is ${state} for ${constraint.sourceGroup || '(unknown group)'} / ${constraint.field || '(unknown field)'}.`,
+      state,
+      { constraint, reasons: constraint.authorityFindings || constraint.declarationFindings || [] }
+    ));
+  }
+
+  const valid = constraints.filter((item) => String(item.authorityQualification || item.declarationQualification || '') === 'valid' && item.targetGroup && item.field);
+  const byTarget = groupConstraints(valid);
+  for (const bucket of byTarget.values()) {
+    const conflict = detectDeterministicConflict(bucket.contributions);
+    if (conflict) {
+      findings.push(fieldDomainFinding(
+        'error',
+        'portable.contract.field-domain.authority.unsatisfiable',
+        `Field-domain authority is unsatisfiable for ${bucket.group}.${bucket.field}.`,
+        'contradictory',
+        { group: bucket.group, field: bucket.field, contributions: bucket.contributions, conflict }
+      ));
+    }
+
+    const occurrences = collectFieldOccurrences(bucket.group, bucket.field, parsedDeclarations, ordinary);
+    const projected = [];
+    for (const occurrence of occurrences) {
+      const results = bucket.contributions.map((contribution) => evaluateContribution(occurrence.value, contribution));
+      const qualification = summarizeContributionResults(results);
+      projected.push(Object.freeze({
+        owner: occurrence.owner,
+        value: occurrence.value,
+        qualification,
+        contributions: Object.freeze(results)
+      }));
+
+      if (qualification === 'invalid') {
+        findings.push(fieldDomainFinding(
+          'error',
+          'portable.contract.field-domain.value.invalid',
+          `Value is outside the allowed field domain for ${bucket.group}.${bucket.field}: ${occurrence.value}.`,
+          'structurally-invalid',
+          { group: bucket.group, field: bucket.field, value: occurrence.value, owner: occurrence.owner, contributions: results }
+        ));
+      } else if (qualification === 'extension-candidate') {
+        findings.push(fieldDomainFinding(
+          'warning',
+          'portable.contract.field-domain.extension.unresolved',
+          `Value is an unresolved extension candidate for ${bucket.group}.${bucket.field}: ${occurrence.value}.`,
+          'unresolved',
+          { group: bucket.group, field: bucket.field, value: occurrence.value, owner: occurrence.owner, contributions: results }
+        ));
+      } else if (qualification === 'authority-unresolved') {
+        findings.push(fieldDomainFinding(
+          'warning',
+          'portable.contract.field-domain.shape.unresolved',
+          `Field-domain shape authority cannot be fully evaluated for ${bucket.group}.${bucket.field}: ${occurrence.value}.`,
+          'unresolved',
+          { group: bucket.group, field: bucket.field, value: occurrence.value, owner: occurrence.owner, contributions: results }
+        ));
+      }
+    }
+
+    groups.push(Object.freeze({
+      group: bucket.group,
+      field: bucket.field,
+      contributions: Object.freeze(bucket.contributions),
+      authorityQualification: conflict ? 'contradictory' : 'valid',
+      occurrences: Object.freeze(projected)
+    }));
+  }
+
+  return Object.freeze({
+    schema: PORTABLE_FIELD_DOMAIN_VALIDATION_SCHEMA_ID,
+    constraints: Object.freeze([...constraints]),
+    groups: Object.freeze(groups),
+    findings: Object.freeze(findings)
+  });
+}
+
+function groupConstraints(constraints = []) {
+  const out = new Map();
+  for (const constraint of constraints) {
+    const key = `${exact(constraint.targetGroup)}\u0000${exact(constraint.field)}`;
+    if (!out.has(key)) out.set(key, { group: constraint.targetGroup, field: constraint.field, contributions: [] });
+    out.get(key).contributions.push(constraint);
+  }
+  return out;
+}
+
+function collectFieldOccurrences(groupName, fieldName, parsedDeclarations = [], ordinary = {}) {
+  const out = [];
+  const declarationGroup = (parsedDeclarations || []).find((item) => exact(item.contract?.group) === exact(groupName));
+  if (declarationGroup) {
+    for (const section of declarationGroup.sections || []) {
+      if (!section.present) continue;
+      for (const entry of section.entries || []) {
+        if (entry.name === 'none') continue;
+        if (!Object.prototype.hasOwnProperty.call(entry.fields || {}, fieldName)) continue;
+        const value = String(entry.fields[fieldName] ?? '');
+        if (!value) continue;
+        out.push(Object.freeze({
+          value,
+          owner: Object.freeze({ kind: 'declaration', group: groupName, heading: section.heading, entry: entry.name, field: fieldName })
+        }));
+      }
+    }
+    return out;
+  }
+
+  const ordinaryGroup = (ordinary.groups || []).find((item) => exact(item.group) === exact(groupName));
+  if (ordinaryGroup) {
+    const field = (ordinaryGroup.fields || []).find((item) => exact(item.label) === exact(fieldName));
+    for (const occurrence of field?.occurrences || []) {
+      out.push(Object.freeze({
+        value: String(occurrence.value ?? ''),
+        owner: Object.freeze({ kind: 'ordinary', group: groupName, heading: ordinaryGroup.target?.heading || '', field: fieldName, line: Number(occurrence.line || 0) })
+      }));
+    }
+  }
+  return out;
+}
+
+function evaluateContribution(value, contribution) {
+  const text = String(value ?? '');
+  const allowedValues = contribution.allowedValues || [];
+  const shapeAuthorities = contribution.allowedShapeAuthorities || [];
+  const literalMatch = allowedValues.some((candidate) => String(candidate) === text);
+  if (literalMatch) return contributionResult(contribution, 'core', 'allowed-value', 'matched');
+
+  // `unknown` is an uncertainty sentinel, never an extension escape hatch and never
+  // rescued by shape authority when it is not explicitly allowed by every contribution.
+  if (text === 'unknown') return contributionResult(contribution, 'invalid', 'unknown-not-allowed', 'not-matched');
+
+  let supportedShapeSeen = false;
+  let unresolvedShapeSeen = false;
+  const shapeResults = [];
+  for (const authority of shapeAuthorities) {
+    const result = qualifyResolvedMachineShape(text, authority);
+    shapeResults.push(Object.freeze({
+      shapeLabel: authority.shapeLabel || '',
+      qualification: result.qualification,
+      authorityQualification: authority.qualification || 'unresolved',
+      resolvedDefinitionProvenance: authority.resolvedDefinitionProvenance || null,
+      findings: authority.findings || Object.freeze([])
+    }));
+    if (result.qualification === 'matched') return contributionResult(contribution, 'core', 'allowed-shape', 'matched', authority.shapeLabel, shapeResults);
+    if (result.qualification === 'not-matched') supportedShapeSeen = true;
+    else unresolvedShapeSeen = true;
+  }
+
+  // A declared Allowed Shape with no compiled authority must never be treated as a
+  // closed no-match. This also protects callers carrying older/pre-resolution data.
+  if ((contribution.allowedShapes || []).length > shapeAuthorities.length) unresolvedShapeSeen = true;
+  if (unresolvedShapeSeen) return contributionResult(contribution, 'authority-unresolved', 'allowed-shape', 'unresolved', '', shapeResults);
+  if (contribution.domainPolicy === 'extension-authorized') return contributionResult(contribution, 'extension-candidate', 'extension-policy', 'unresolved', '', shapeResults);
+  return contributionResult(contribution, 'invalid', supportedShapeSeen ? 'allowed-shape' : 'allowed-value', 'not-matched', '', shapeResults);
+}
+
+function contributionResult(contribution, qualification, authority, match, shape = '', shapeResults = []) {
+  return Object.freeze({
+    qualification,
+    authority,
+    match,
+    matchedShape: shape,
+    shapeResults: Object.freeze([...shapeResults]),
+    sourceSchemaId: contribution.sourceSchemaId || '',
+    sourceGroup: contribution.sourceGroup || '',
+    targetGroup: contribution.targetGroup || '',
+    targetMode: contribution.targetMode || '',
+    targetOwnership: contribution.targetOwnership || '',
+    ownershipSourceSchemaIds: contribution.ownershipSourceSchemaIds || Object.freeze([]),
+    appliesToTarget: contribution.appliesToTarget || '',
+    field: contribution.field || '',
+    allowedValues: contribution.allowedValues || Object.freeze([]),
+    allowedShapes: contribution.allowedShapes || Object.freeze([]),
+    allowedShapeAuthorities: contribution.allowedShapeAuthorities || Object.freeze([]),
+    domainPolicy: contribution.domainPolicy || '',
+    declarationLine: Number(contribution.declarationLine || 0)
+  });
+}
+
+function summarizeContributionResults(results = []) {
+  if (results.some((item) => item.qualification === 'invalid')) return 'invalid';
+  if (results.some((item) => item.qualification === 'authority-unresolved')) return 'authority-unresolved';
+  if (results.some((item) => item.qualification === 'extension-candidate')) return 'extension-candidate';
+  return 'core';
+}
+
+function detectDeterministicConflict(contributions = []) {
+  const closed = contributions.filter((item) => item.domainPolicy === 'closed');
+  if (closed.length < 2) return null;
+
+  const literalCandidates = [...new Set(closed.flatMap((item) => item.allowedValues || []))];
+  for (const candidate of literalCandidates) {
+    const matches = closed.map((item) => coreMatch(candidate, item));
+    if (matches.every((item) => item === 'matched')) return null;
+    if (matches.some((item) => item === 'unresolved')) return null;
+  }
+
+  // Proving two arbitrary lexical languages disjoint is outside this bounded surface.
+  // If any contribution offers a machine shape, retain the obligations and validate
+  // concrete values instead of inventing an intersection theorem.
+  if (closed.some((item) => (item.allowedShapes || []).length)) return null;
+  return Object.freeze({
+    kind: 'empty-domain-intersection',
+    sourceGroups: Object.freeze(closed.map((item) => item.sourceGroup || ''))
+  });
+}
+
+function coreMatch(value, contribution) {
+  if ((contribution.allowedValues || []).some((candidate) => String(candidate) === String(value))) return 'matched';
+  let unresolved = false;
+  const authorities = contribution.allowedShapeAuthorities || [];
+  if ((contribution.allowedShapes || []).length > authorities.length) unresolved = true;
+  for (const authority of authorities) {
+    const result = qualifyResolvedMachineShape(value, authority);
+    if (result.qualification === 'matched') return 'matched';
+    if (result.qualification === 'unresolved') unresolved = true;
+  }
+  return unresolved ? 'unresolved' : 'not-matched';
+}
+
+function fieldDomainFinding(severity, code, message, state, extra = {}) {
+  return portableFinding(severity, code, message, { ...extra, state });
+}
+
+function exact(value = '') {
+  return String(value || '').trim();
+}

package/src/tooling/portable/schema/contract.field-shape.compile.js

@@ -0,0 +1,34 @@
+import { resolveFieldDomainShapeAuthoritiesAcrossChain } from './contract.machine-shape.js';
+
+export function compileFieldShapeRequirements(document = {}) {
+  const sourceSchemaId = String(document?.schemaId || '').trim();
+  const out = [];
+  for (const group of document?.validation?.groups || []) {
+    const allowedShapes = unique(categoryItems(group, ['Allowed Shapes']).map(cleanToken));
+    if (!allowedShapes.length) continue;
+    let fields = unique(categoryItems(group, ['Fields']).map(cleanToken));
+    if (!fields.length && /\s+Field$/u.test(String(group?.name || ''))) fields = [String(group.name).replace(/\s+Field$/u, '').trim()];
+    if (!fields.length) continue;
+    for (const field of fields) out.push(Object.freeze({ kind: 'field-shape', sourceSchemaId, group: String(group.name || ''), field, allowedShapes: Object.freeze(allowedShapes) }));
+  }
+  return Object.freeze(out);
+}
+
+export function resolveFieldShapeRequirements(requirements = [], compiledLineage = []) {
+  if (!requirements.length) return Object.freeze([]);
+  const faux = requirements.map((requirement) => Object.freeze({ ...requirement, kind: 'field-domain', policy: 'closed', allowedValues: Object.freeze([]) }));
+  const resolved = resolveFieldDomainShapeAuthoritiesAcrossChain(faux, compiledLineage);
+  return Object.freeze(resolved.map((item) => Object.freeze({
+    kind: 'field-shape', sourceSchemaId: item.sourceSchemaId, group: item.group, field: item.field,
+    allowedShapes: Object.freeze([...(item.allowedShapes || [])]),
+    allowedShapeAuthorities: Object.freeze([...(item.allowedShapeAuthorities || [])])
+  })));
+}
+
+function categoryItems(group = {}, names = []) {
+  const wanted = new Set(names.map(exactToken));
+  return (group.categories || []).flatMap((category) => wanted.has(exactToken(category.name)) ? category.items : []);
+}
+function cleanToken(value = '') { return String(value || '').trim().replace(/^`|`$/g, '').trim(); }
+function exactToken(value = '') { return String(value || '').trim(); }
+function unique(values = []) { return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))]; }

package/src/tooling/portable/schema/contract.inheritance.inline.js

@@ -0,0 +1,103 @@
+export const INLINE_INHERITANCE_OVERRIDE_CATEGORY = 'Inheritance Overrides';
+export const INLINE_INHERITANCE_OVERRIDE_REQUIRED_FIELDS = Object.freeze(['Merge Operation', 'Parent Schema', 'Parent Node', 'Child Node']);
+export const INLINE_INHERITANCE_OVERRIDE_OPTIONAL_FIELDS = Object.freeze(['Reason', 'Effective Result']);
+
+export function compileInlineSchemaInheritanceOverrides(document = {}) {
+  const sourceSchemaId = String(document?.schemaId || '').trim();
+  const declarations = [];
+  const findings = [];
+  const seenNames = new Set();
+
+  for (const group of document?.validation?.groups || []) {
+    const categories = (group?.categories || []).filter((category) => exact(category?.name) === INLINE_INHERITANCE_OVERRIDE_CATEGORY);
+    if (categories.length > 1) findings.push(`Inheritance Overrides category appears ${categories.length} times in contract group ${group?.name || '(unnamed)'}.`);
+    for (const category of categories) {
+      if (!(category?.nodes || []).length) findings.push(`Inheritance Overrides in contract group ${group?.name || '(unnamed)'} must contain at least one Named Declaration.`);
+      for (const node of category?.nodes || []) {
+        const parsed = parseOverrideDeclaration(node, { sourceSchemaId, sourceGroup: String(group?.name || '') });
+        if (seenNames.has(parsed.name)) findings.push(`Inheritance Overrides declaration name is duplicated in ${sourceSchemaId || '(unknown schema)'}: ${parsed.name || '(unnamed)'}.`);
+        seenNames.add(parsed.name);
+        findings.push(...parsed.findings);
+        declarations.push(parsed.declaration);
+      }
+    }
+  }
+
+  return Object.freeze({
+    schema: 'tiinex.portable.inline-schema-inheritance-overrides.v1',
+    sourceSchemaId,
+    state: findings.length ? 'unresolved' : declarations.length ? 'declared' : 'not-declared',
+    declarations: Object.freeze(declarations),
+    findings: Object.freeze(findings)
+  });
+}
+
+export function qualifyInlineInheritanceOverrideAuthority(rootCompiled = null) {
+  const findings = [];
+  if (!rootCompiled || String(rootCompiled.schemaId || '') !== 'tiinex.root.v1') return blockedAuthority('Compiled Root contract is unavailable for inline inheritance override authority.');
+  const syntax = exactGroups(rootCompiled?.validation?.groups || [], 'Contract Syntax');
+  if (syntax.length !== 1) findings.push(`Root Contract Syntax resolves to ${syntax.length} groups.`);
+  const known = syntax.length === 1 ? exactCategories(syntax[0], 'Known Category Labels') : [];
+  if (known.length !== 1) findings.push(`Root Known Category Labels resolves to ${known.length} categories.`);
+  if (known.length === 1 && !(known[0].items || []).some((item) => exact(item) === INLINE_INHERITANCE_OVERRIDE_CATEGORY)) findings.push('Root Known Category Labels does not declare Inheritance Overrides.');
+
+  const groups = exactGroups(rootCompiled?.validation?.groups || [], INLINE_INHERITANCE_OVERRIDE_CATEGORY);
+  if (groups.length !== 1) findings.push(`Root Inheritance Overrides authority resolves to ${groups.length} groups.`);
+  if (groups.length === 1) {
+    const group = groups[0];
+    const entryShape = categoryItems(group, 'Entry Shape');
+    const required = categoryItems(group, 'Required Fields');
+    const optional = categoryItems(group, 'Optional Fields');
+    if (!entryShape.includes('Named Declaration')) findings.push('Root Inheritance Overrides authority does not declare Entry Shape: Named Declaration.');
+    for (const field of INLINE_INHERITANCE_OVERRIDE_REQUIRED_FIELDS) if (!required.includes(field)) findings.push(`Root Inheritance Overrides authority is missing Required Field: ${field}.`);
+    for (const field of INLINE_INHERITANCE_OVERRIDE_OPTIONAL_FIELDS) if (!optional.includes(field)) findings.push(`Root Inheritance Overrides authority is missing Optional Field: ${field}.`);
+  }
+  return Object.freeze({ state: findings.length ? 'unresolved' : 'qualified', findings: Object.freeze(findings) });
+}
+
+function parseOverrideDeclaration(node = {}, context = {}) {
+  const name = exact(node?.value);
+  const findings = [];
+  const fields = {};
+  if (!name || /^.+:\s*/.test(name)) findings.push('Inheritance Overrides declaration must have one exact non-field declaration name.');
+  if (!(node?.children || []).length) findings.push(`Inheritance Overrides declaration ${name || '(unnamed)'} has no declaration fields.`);
+  for (const child of node?.children || []) {
+    if ((child?.children || []).length) findings.push(`Inheritance Overrides declaration ${name || '(unnamed)'} field nesting must be exactly one level.`);
+    const parsed = parseField(child?.value);
+    if (!parsed) {
+      findings.push(`Inheritance Overrides declaration ${name || '(unnamed)'} contains malformed field: ${exact(child?.value) || '(empty)'}.`);
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(fields, parsed.field)) findings.push(`Inheritance Overrides declaration ${name || '(unnamed)'} duplicates field ${parsed.field}.`);
+    fields[parsed.field] = parsed.value;
+  }
+  const allowed = new Set([...INLINE_INHERITANCE_OVERRIDE_REQUIRED_FIELDS, ...INLINE_INHERITANCE_OVERRIDE_OPTIONAL_FIELDS]);
+  for (const field of Object.keys(fields)) if (!allowed.has(field)) findings.push(`Inheritance Overrides declaration ${name || '(unnamed)'} uses undeclared field ${field}.`);
+  for (const field of INLINE_INHERITANCE_OVERRIDE_REQUIRED_FIELDS) if (!exact(fields[field])) findings.push(`Inheritance Overrides declaration ${name || '(unnamed)'} is missing ${field}.`);
+
+  const declaration = Object.freeze({
+    name,
+    sourceSchemaId: context.sourceSchemaId,
+    sourceGroup: context.sourceGroup,
+    declarationLine: Number(node?.line || 0),
+    operation: exact(fields['Merge Operation']),
+    parentSchemaId: exact(fields['Parent Schema']),
+    parentNode: exact(fields['Parent Node']),
+    childNode: exact(fields['Child Node']),
+    reason: exact(fields.Reason),
+    effectiveResult: exact(fields['Effective Result'])
+  });
+  return Object.freeze({ declaration, findings: Object.freeze(findings) });
+}
+
+function parseField(value = '') {
+  const match = String(value || '').match(/^([^:]+):\s*(.*?)\s*$/);
+  if (!match) return null;
+  return { field: exact(match[1]), value: exact(match[2]) };
+}
+
+function exactGroups(groups = [], name = '') { return (groups || []).filter((group) => exact(group?.name) === exact(name)); }
+function exactCategories(group = {}, name = '') { return (group?.categories || []).filter((category) => exact(category?.name) === exact(name)); }
+function categoryItems(group = {}, name = '') { return exactCategories(group, name).flatMap((category) => (category?.items || []).map(exact)); }
+function exact(value = '') { return String(value || '').trim(); }
+function blockedAuthority(message) { return Object.freeze({ state: 'unresolved', findings: Object.freeze([message]) }); }

package/src/tooling/portable/schema/contract.inheritance.js

@@ -0,0 +1,210 @@
+import { compileOrdinaryGroupContribution } from './ordinary.contract.js';
+import { qualifyInlineInheritanceOverrideAuthority } from './contract.inheritance.inline.js';
+import { parseStandaloneInheritanceRecord } from './contract.inheritance.record.js';
+
+export const PORTABLE_SCHEMA_INHERITANCE_RESOLUTION_SCHEMA_ID = 'tiinex.portable.schema-inheritance-resolution.v1';
+
+export function applySchemaInheritanceOverrides(compiled = [], artifacts = []) {
+  const baseComposition = Object.freeze([...compiled]);
+  const declarations = compiled.flatMap((item) => item?.inheritanceOverrides?.declarations || []);
+  const findings = compiled.flatMap((item) => item?.inheritanceOverrides?.findings || []);
+  const standaloneInputs = (Array.isArray(artifacts) ? artifacts : [artifacts]).filter(Boolean);
+  const corroborations = [];
+
+  if (declarations.length) {
+    const authority = qualifyInlineInheritanceOverrideAuthority(compiled.find((item) => String(item?.schemaId || '') === 'tiinex.root.v1'));
+    findings.push(...authority.findings);
+  }
+
+  const qualified = declarations.map((declaration) => qualifyOverrideDeclaration(declaration, compiled));
+  for (const item of qualified) findings.push(...item.findings);
+  findings.push(...competingOverrideFindings(qualified));
+  findings.push(...compareStandaloneRecords(standaloneInputs, declarations, corroborations));
+
+  if (findings.length) return result(baseComposition, 'unresolved', declarations, [], findings, corroborations);
+  if (!declarations.length) return result(baseComposition, 'not-declared', declarations, [], [], corroborations);
+
+  let composition = [...compiled];
+  const applications = [];
+  for (const item of qualified) {
+    const applied = applyQualifiedOverride(composition, item);
+    if (applied.state !== 'qualified') return result(baseComposition, 'unresolved', declarations, [], applied.findings, corroborations);
+    composition = [...applied.composition];
+    applications.push(applied.application);
+  }
+  return result(Object.freeze(composition), 'qualified', declarations, applications, [], corroborations);
+}
+
+function qualifyOverrideDeclaration(declaration = {}, composition = []) {
+  const findings = [];
+  if (String(declaration.operation || '') !== 'override') findings.push(`Inheritance Overrides declaration ${label(declaration)} must use Merge Operation: override.`);
+  const childSchemaId = String(declaration.sourceSchemaId || '');
+  const parentSchemaId = String(declaration.parentSchemaId || '');
+  const parentIndexes = exactSchemaIndexes(composition, parentSchemaId);
+  const childIndexes = exactSchemaIndexes(composition, childSchemaId);
+  if (parentIndexes.length !== 1) findings.push(`Inheritance Overrides Parent Schema ${parentSchemaId || '(missing)'} resolves to ${parentIndexes.length} supplied lineage positions.`);
+  if (childIndexes.length !== 1) findings.push(`Inheritance Overrides declaring Child Schema ${childSchemaId || '(missing)'} resolves to ${childIndexes.length} supplied lineage positions.`);
+  const parentIndex = parentIndexes[0] ?? -1;
+  const childIndex = childIndexes[0] ?? -1;
+  if (parentIndex >= 0 && childIndex >= 0 && childIndex <= parentIndex) findings.push('Inheritance Overrides Parent Schema must be an actual ancestor of the declaring child schema.');
+
+  const parentNode = parseContractNode(declaration.parentNode);
+  const childNode = parseContractNode(declaration.childNode);
+  if (!parentNode) findings.push(`Parent Node is not one exact Schema Validation Contract / group / category path: ${declaration.parentNode || '(missing)'}.`);
+  if (!childNode) findings.push(`Child Node is not one exact Schema Validation Contract / group / category path: ${declaration.childNode || '(missing)'}.`);
+
+  const parent = parentIndex >= 0 ? composition[parentIndex] : null;
+  const child = childIndex >= 0 ? composition[childIndex] : null;
+  const parentMatch = parentNode && parent ? exactCategoryMatch(parent.validation?.groups || [], parentNode) : null;
+  const childMatch = childNode && child ? exactCategoryMatch(child.validation?.groups || [], childNode) : null;
+  if (parentMatch?.state === 'unresolved') findings.push(`Parent Node must resolve exactly once in ${parentSchemaId}: ${declaration.parentNode}; observed ${parentMatch.count}.`);
+  if (childMatch?.state === 'unresolved') findings.push(`Child Node must resolve exactly once in ${childSchemaId}: ${declaration.childNode}; observed ${childMatch.count}.`);
+
+  let suppressedGroups = Object.freeze([]);
+  if (!findings.length && parentNode.category === 'Required Shape' && childNode.category === 'Required Shape') {
+    const structural = qualifyRequiredShapeStructuralDeactivation(parent, child, parentMatch.category, childMatch.category, composition);
+    findings.push(...structural.findings);
+    suppressedGroups = structural.suppressedGroups;
+  }
+
+  return Object.freeze({
+    state: findings.length ? 'unresolved' : 'qualified', findings: Object.freeze(findings), declaration,
+    parentSchemaId, childSchemaId, parentIndex, childIndex, parentNode, childNode,
+    parentContribution: parentMatch?.category || null, childContribution: childMatch?.category || null,
+    suppressedGroups
+  });
+}
+
+function qualifyRequiredShapeStructuralDeactivation(parent = {}, child = {}, parentCategory = {}, childCategory = {}, composition = []) {
+  void child;
+  const findings = [];
+  const parentHeadings = headingRequirements(parentCategory.items || []);
+  const childHeadings = headingRequirements(childCategory.items || []);
+  if (!parentHeadings.length) findings.push('Required Shape Parent Node has no machine-readable heading requirements.');
+  if (!childHeadings.length) findings.push('Required Shape Child Node has no machine-readable heading requirements.');
+  const rootAuthority = composition.find((item) => item?.validation?.ordinaryFieldAuthority?.state === 'available')?.validation?.ordinaryFieldAuthority || null;
+  const replacement = new Set(childHeadings.map((item) => headingKey(item.level, item.title)));
+  const removedSecondLevel = new Set(parentHeadings.filter((item) => item.level === 2 && !replacement.has(headingKey(item.level, item.title))).map((item) => item.title));
+  if (removedSecondLevel.size && !rootAuthority) findings.push('Root ordinary instance-field target authority is unavailable for Required Shape structural deactivation.');
+
+  const suppressed = [];
+  if (rootAuthority) {
+    for (const group of parent?.validation?.groups || []) {
+      const contribution = compileOrdinaryGroupContribution(group, rootAuthority);
+      if (!contribution) continue;
+      if (contribution.target?.qualification !== 'valid') {
+        findings.push(`Parent ordinary group ${group.name || '(unnamed)'} has unresolved Instance Target ownership during Required Shape override.`);
+        continue;
+      }
+      if (contribution.target.level === 2 && removedSecondLevel.has(contribution.target.title)) suppressed.push(group.name);
+    }
+  }
+  return Object.freeze({ state: findings.length ? 'unresolved' : 'qualified', findings: Object.freeze(findings), suppressedGroups: Object.freeze(unique(suppressed)) });
+}
+
+function competingOverrideFindings(qualified = []) {
+  const findings = [];
+  const byParent = new Map();
+  for (const item of qualified) {
+    if (item.state !== 'qualified') continue;
+    const key = `${item.parentSchemaId}\u0000${item.declaration.parentNode}`;
+    if (!byParent.has(key)) byParent.set(key, []);
+    byParent.get(key).push(item);
+  }
+  for (const items of byParent.values()) if (items.length > 1) findings.push(`Competing active Inheritance Overrides declarations target the same parent contribution: ${items.map((item) => label(item.declaration)).join(', ')}.`);
+  return findings;
+}
+
+function compareStandaloneRecords(inputs = [], declarations = [], corroborations = []) {
+  const findings = [];
+  for (const input of inputs) {
+    const record = parseStandaloneInheritanceRecord(input);
+    if (record.state !== 'qualified') { findings.push(...record.findings); continue; }
+    const matches = declarations.filter((declaration) => declaration.name === record.handle && declaration.sourceSchemaId === record.childSchemaId);
+    if (matches.length !== 1) {
+      findings.push(`Standalone inheritance record ${record.handle || '(unnamed)'} has ${matches.length} matching canonical inline declarations; standalone records cannot add schema-local override authority.`);
+      continue;
+    }
+    const declaration = matches[0];
+    for (const rule of record.rules) {
+      const exact = rule.operation === declaration.operation
+        && record.parentSchemaId === declaration.parentSchemaId
+        && record.childSchemaId === declaration.sourceSchemaId
+        && rule.parentNode === declaration.parentNode
+        && rule.childNode === declaration.childNode;
+      if (!exact) findings.push(`Standalone inheritance record ${record.handle} disagrees with the canonical inline declaration.`);
+      else corroborations.push(Object.freeze({ handle: record.handle, source: 'tiinex.schema.inheritance.v1', state: 'corroborating-record' }));
+    }
+  }
+  return findings;
+}
+
+function applyQualifiedOverride(composition = [], qualified = {}) {
+  const parent = composition[qualified.parentIndex];
+  const transformedParent = deactivateParentContribution(parent, qualified.parentNode, new Set(qualified.suppressedGroups || []));
+  const next = [...composition];
+  next[qualified.parentIndex] = transformedParent;
+  const declaration = qualified.declaration;
+  const application = Object.freeze({
+    handle: declaration.name,
+    declaration: Object.freeze({ sourceSchemaId: declaration.sourceSchemaId, sourceGroup: declaration.sourceGroup, name: declaration.name, line: declaration.declarationLine, reason: declaration.reason, effectiveResult: declaration.effectiveResult }),
+    operation: declaration.operation,
+    parentSchemaId: qualified.parentSchemaId,
+    childSchemaId: qualified.childSchemaId,
+    parentNode: declaration.parentNode,
+    childNode: declaration.childNode,
+    state: 'applied',
+    deactivatedContributions: Object.freeze([
+      Object.freeze({ sourceSchemaId: qualified.parentSchemaId, group: qualified.parentNode.group, category: qualified.parentNode.category, state: 'inactive', items: Object.freeze([...(qualified.parentContribution?.items || [])]), declarationName: declaration.name }),
+      ...(qualified.suppressedGroups || []).map((group) => Object.freeze({ sourceSchemaId: qualified.parentSchemaId, group, category: 'ordinary-instance-field-group', state: 'inactive', items: Object.freeze([]), declarationName: declaration.name }))
+    ]),
+    replacementContribution: Object.freeze({ sourceSchemaId: qualified.childSchemaId, group: qualified.childNode.group, category: qualified.childNode.category, state: 'active', items: Object.freeze([...(qualified.childContribution?.items || [])]), declarationName: declaration.name })
+  });
+  return Object.freeze({ state: 'qualified', findings: Object.freeze([]), composition: Object.freeze(next), application });
+}
+
+function deactivateParentContribution(parent = {}, node = {}, suppressedGroups = new Set()) {
+  const groups = (parent.validation?.groups || []).flatMap((group) => {
+    if (suppressedGroups.has(String(group.name || ''))) return [];
+    if (String(group.name || '') !== node.group) return [group];
+    const categories = (group.categories || []).filter((category) => String(category.name || '') !== node.category);
+    return [Object.freeze({ ...group, categories: Object.freeze(categories) })];
+  });
+  const declarationNames = new Set((parent.declarations || []).map((item) => String(item.group || '')));
+  return Object.freeze({
+    ...parent,
+    validation: Object.freeze({
+      ...parent.validation,
+      groups: Object.freeze(groups),
+      requiredSections: Object.freeze(requiredSectionsFromGroups(groups)),
+      requiredHeadings: Object.freeze(requiredHeadingsFromGroups(groups)),
+      optionalSections: Object.freeze(optionalSectionsFromGroups(groups)),
+      requiredFields: Object.freeze(fieldsFromGroups(groups, declarationNames, 'Required Fields', true)),
+      optionalFields: Object.freeze(fieldsFromGroups(groups, declarationNames, 'Optional Fields', false)),
+      requiredEntries: Object.freeze((parent.validation?.requiredEntries || []).map((item) => Object.freeze({ ...item, targetHeadings: Object.freeze((item.targetHeadings || []).filter((heading) => !suppressedGroups.has(stripHeading(heading)))) })))
+    })
+  });
+}
+
+function exactCategoryMatch(groups = [], node = {}) {
+  const groupMatches = (groups || []).filter((item) => String(item.name || '') === node.group);
+  if (groupMatches.length !== 1) return Object.freeze({ state: 'unresolved', count: groupMatches.length, category: null });
+  const categoryMatches = (groupMatches[0].categories || []).filter((item) => String(item.name || '') === node.category);
+  return categoryMatches.length === 1 ? Object.freeze({ state: 'qualified', count: 1, category: categoryMatches[0] }) : Object.freeze({ state: 'unresolved', count: categoryMatches.length, category: null });
+}
+function exactSchemaIndexes(composition = [], schemaId = '') { return composition.map((item, index) => String(item?.schemaId || '') === schemaId ? index : -1).filter((index) => index >= 0); }
+function parseContractNode(value = '') { const parts = String(value || '').split('/').map((item) => item.trim()).filter(Boolean); return parts.length === 3 && parts[0] === 'Schema Validation Contract' ? Object.freeze({ contract: parts[0], group: parts[1], category: parts[2] }) : null; }
+function result(composition, state, declarations, applications, findings, corroborations) { return Object.freeze({ composition, resolution: Object.freeze({ schema: PORTABLE_SCHEMA_INHERITANCE_RESOLUTION_SCHEMA_ID, state, declarations: Object.freeze((declarations || []).map((item) => Object.freeze({ ...item }))), applications: Object.freeze(applications), corroborations: Object.freeze(corroborations), findings: Object.freeze(findings) }) }); }
+function requiredSectionsFromGroups(groups = []) { return unique(groups.filter(unconditional).flatMap((group) => group.categories || []).flatMap((category) => structuralSections(category))); }
+function requiredHeadingsFromGroups(groups = []) { const seen = new Set(); return groups.filter(unconditional).flatMap((group) => group.categories || []).filter((category) => ['Required Shape', 'Required Heading'].includes(String(category.name || ''))).flatMap((category) => headingRequirements(category.items || [])).filter((item) => { const key = headingKey(item.level, item.title); if (seen.has(key)) return false; seen.add(key); return true; }).map((item) => Object.freeze({ ...item, source: item.source || '' })); }
+function optionalSectionsFromGroups(groups = []) { return unique(groups.flatMap((group) => group.categories || []).filter((category) => String(category.name || '') === 'Optional Sections').flatMap((category) => category.items || []).map(cleanSection)); }
+function structuralSections(category = {}) { const name = String(category.name || ''); if (['Required Sections', 'Header Sections', 'Footer Sections', 'Required Heading'].includes(name)) return (category.items || []).map(cleanSection); if (name === 'Required Shape') return headingRequirements(category.items || []).map((item) => item.title); return []; }
+function fieldsFromGroups(groups = [], declarationNames = new Set(), categoryName = '', unconditionalOnly = false) { return unique(groups.filter((group) => !declarationNames.has(String(group.name || '')) && (!unconditionalOnly || unconditional(group))).flatMap((group) => group.categories || []).filter((category) => String(category.name || '') === categoryName).flatMap((category) => category.items || []).map(cleanField)); }
+function headingRequirements(items = []) { return items.flatMap((value) => { const text = String(value || ''); const quoted = [...text.matchAll(/`(#{1,6})\s+([^`]+)`/g)].map((match) => ({ level: match[1].length, title: match[2].trim(), source: text })); if (quoted.length) return quoted; const plain = text.match(/^(#{1,6})\s+(.+)$/); return plain ? [{ level: plain[1].length, title: plain[2].trim(), source: text }] : []; }); }
+function unconditional(group = {}) { return !(group.requiredWhen || []).length; }
+function cleanSection(value = '') { return stripHeading(String(value || '').trim().replace(/^`|`$/g, '').replace(/\s+section$/i, '')); }
+function cleanField(value = '') { return String(value || '').trim().replace(/^`|`$/g, '').trim(); }
+function stripHeading(value = '') { return String(value || '').replace(/^#{1,6}\s+/, '').trim(); }
+function headingKey(level, title) { return `${Number(level || 0)}\u0000${String(title || '')}`; }
+function unique(values = []) { return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))]; }
+function label(declaration = {}) { return declaration.name || `${declaration.sourceSchemaId || '(unknown schema)'} declaration`; }