@tiinex/core 0.1.1

package/src/tooling/portable/schema/contract.envelope.validate.js

@@ -0,0 +1,177 @@
+import { portableFinding } from '../findings.js';
+import { qualifyResolvedMachineShape } from './contract.machine-shape.js';
+import { qualifyReferenceShape } from '../../../schemas/reference.shapes.js';
+
+export function validatePortableEnvelopeContract(markdown = '', compiled = {}) {
+  const findings = [];
+  const envelope = parseContinuityEnvelopeTree(markdown);
+  validateConditionalRequirements(compiled, envelope, findings);
+  validateFieldShapeRequirements(compiled, envelope, findings);
+  return Object.freeze({ summary: envelope.summary, findings: Object.freeze(findings) });
+}
+
+function validateConditionalRequirements(compiled = {}, envelope = {}, findings = []) {
+  for (const requirement of compiled.validation?.conditionalRequirements || []) {
+    const conditions = (requirement.requiredWhen || []).map(parseExistsCondition);
+    if (!conditions.length || conditions.some((condition) => !condition)) continue;
+    const triggered = conditions.every((condition) => envelope.nodes.some((node) => node.label === condition.label));
+    if (!triggered) continue;
+
+    const scopes = envelope.nodes.filter((node) => node.path.join(' ') === String(requirement.name || ''));
+    if (scopes.length !== 1) {
+      findings.push(finding('error', scopes.length ? 'portable.contract.conditional.target.ambiguous' : 'portable.contract.conditional.target.missing', `${requirement.name} is required by ${requirement.requiredWhen.join('; ')} but its exact envelope target ${scopes.length ? 'is ambiguous' : 'is missing'}.`, scopes.length ? 'structurally-invalid' : 'incomplete', { group: requirement.name, occurrenceCount: scopes.length }));
+      continue;
+    }
+    const scope = scopes[0];
+    for (const field of requirement.requiredFields || []) {
+      const occurrences = scope.children.filter((child) => child.label === field);
+      if (!occurrences.length) findings.push(finding('error', 'portable.contract.conditional.field.required.missing', `Required field is missing from ${requirement.name}: ${field}.`, 'incomplete', { group: requirement.name, field }));
+      else if (occurrences.length > 1) findings.push(finding('error', 'portable.contract.conditional.field.duplicate', `Required field occurs more than once in ${requirement.name}: ${field}.`, 'structurally-invalid', { group: requirement.name, field, occurrenceCount: occurrences.length }));
+    }
+
+    const allowedLabels = new Set((requirement.allowedLabels || []).map(exactToken));
+    if (allowedLabels.size) {
+      for (const child of scope.children) {
+        if (allowedLabels.has(exactToken(child.label))) continue;
+        findings.push(finding('preserve', 'portable.contract.conditional.label.unknown.preserved', `Unknown or extension label is preserved in ${requirement.name}: ${child.label}.`, 'preserve', { group: requirement.name, field: child.label }));
+      }
+    }
+
+    validateConditionalEntryShapes(requirement, scope, compiled, findings);
+    validateConditionalOrdering(requirement, scope, findings);
+  }
+}
+
+function validateConditionalEntryShapes(requirement = {}, scope = {}, compiled = {}, findings = []) {
+  const requested = (requirement.entryShapes || []).map(exactToken).filter(Boolean);
+  if (!requested.length || !scope.children.length) return;
+  const active = compiled.machineShapes?.active || [];
+  const resolutions = requested.map((shapeLabel) => active.find((item) => exactToken(item.shapeLabel) === shapeLabel)).filter(Boolean);
+  if (!resolutions.length) return;
+  for (const child of scope.children) {
+    const results = resolutions.map((resolution) => qualifyResolvedMachineShape(child.rawValue, resolution));
+    if (results.some((result) => result.qualification === 'matched')) continue;
+    if (results.some((result) => result.qualification === 'unresolved')) {
+      findings.push(finding('warning', 'portable.contract.conditional.entry-shape.unresolved', `Entry shape cannot be fully qualified in ${requirement.name}: ${child.rawValue}.`, 'unresolved', { group: requirement.name, field: child.label, requestedShapes: requested }));
+      continue;
+    }
+    findings.push(finding('error', 'portable.contract.conditional.entry-shape.no-match', `Entry does not satisfy the declared shape in ${requirement.name}: ${child.rawValue}.`, 'structurally-invalid', { group: requirement.name, field: child.label, requestedShapes: requested }));
+  }
+}
+
+function validateConditionalOrdering(requirement = {}, scope = {}, findings = []) {
+  const ordering = (requirement.ordering || []).map(exactToken).filter(Boolean);
+  if (!ordering.length) return;
+  const rank = new Map(ordering.map((label, index) => [label, index]));
+  let previous = -1;
+  for (const child of scope.children) {
+    if (!rank.has(exactToken(child.label))) continue;
+    const current = rank.get(exactToken(child.label));
+    if (current < previous) {
+      findings.push(finding('error', 'portable.contract.conditional.order.invalid', `Entry ordering in ${requirement.name} does not follow the declared Ordering contract.`, 'structurally-invalid', { group: requirement.name, ordering }));
+      return;
+    }
+    previous = current;
+  }
+}
+
+function validateFieldShapeRequirements(compiled = {}, envelope = {}, findings = []) {
+  for (const requirement of compiled.validation?.fieldShapes || []) {
+    const occurrences = envelope.nodes.filter((node) => node.label === requirement.field && node.value !== null);
+    if (!occurrences.length) continue;
+    for (const occurrence of occurrences) {
+      const authorities = requirement.allowedShapeAuthorities || [];
+      const evaluations = (requirement.allowedShapes || []).map((shapeLabel) => {
+        const authority = authorities.find((item) => exactToken(item.shapeLabel) === exactToken(shapeLabel));
+        const machine = authority ? qualifyResolvedMachineShape(occurrence.value, authority) : Object.freeze({ qualification: 'unresolved' });
+        return machine.qualification === 'unresolved' ? qualifyReferenceShape(shapeLabel, occurrence.value) : machine;
+      });
+      if (evaluations.some((item) => item.qualification === 'matched')) continue;
+      const unresolved = evaluations.some((item) => item.qualification === 'unresolved');
+      if (unresolved) {
+        findings.push(finding('warning', 'portable.contract.field-shape.unresolved', `${requirement.field} does not match a currently evaluable allowed shape and at least one declared shape authority is unresolved.`, 'unresolved', { group: requirement.group, field: requirement.field, value: occurrence.value, allowedShapes: requirement.allowedShapes || [] }));
+      } else {
+        findings.push(finding('error', 'portable.contract.field-shape.no-match', `${requirement.field} does not satisfy any declared allowed shape.`, 'structurally-invalid', { group: requirement.group, field: requirement.field, value: occurrence.value, allowedShapes: requirement.allowedShapes || [] }));
+      }
+    }
+  }
+}
+
+function parseExistsCondition(value = '') {
+  const match = String(value || '').match(/^(.+?) exists$/u);
+  if (!match) return null;
+  const label = exactToken(match[1]);
+  return label ? Object.freeze({ kind: 'exists', label }) : null;
+}
+
+function parseContinuityEnvelopeTree(markdown = '') {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const heading = lines.findIndex((line) => line === '# Continuity Context');
+  if (heading < 0) return Object.freeze({ nodes: Object.freeze([]), roots: Object.freeze([]), summary: Object.freeze({ available: false, nodeCount: 0 }) });
+  let end = lines.length;
+  for (let index = heading + 1; index < lines.length; index += 1) {
+    if (lines[index] === '---' || /^#\s+/.test(lines[index])) { end = index; break; }
+  }
+  const roots = [];
+  const nodes = [];
+  const stack = [];
+  for (let index = heading + 1; index < end; index += 1) {
+    const match = lines[index].match(/^(\s*)-\s+(.+?)\s*$/u);
+    if (!match) continue;
+    const indent = indentationWidth(match[1]);
+    const parsed = parseEnvelopeItem(match[2]);
+    while (stack.length && stack.at(-1).indent >= indent) stack.pop();
+    const parent = stack.at(-1) || null;
+    const node = {
+      label: parsed.label,
+      value: parsed.value,
+      rawValue: parsed.rawValue,
+      form: parsed.form,
+      indent,
+      line: index + 1,
+      parent,
+      children: [],
+      path: Object.freeze([...(parent?.path || []), parsed.label])
+    };
+    if (parent) parent.children.push(node); else roots.push(node);
+    nodes.push(node);
+    stack.push(node);
+  }
+  const freezeNode = (node) => Object.freeze({
+    label: node.label,
+    value: node.value,
+    rawValue: node.rawValue,
+    form: node.form,
+    indent: node.indent,
+    line: node.line,
+    path: node.path,
+    children: Object.freeze(node.children.map(freezeNode))
+  });
+  const frozenRoots = Object.freeze(roots.map(freezeNode));
+  const flattened = [];
+  const visit = (node) => { flattened.push(node); for (const child of node.children) visit(child); };
+  for (const root of frozenRoots) visit(root);
+  return Object.freeze({ nodes: Object.freeze(flattened), roots: frozenRoots, summary: Object.freeze({ available: true, nodeCount: flattened.length }) });
+}
+
+function parseEnvelopeItem(value = '') {
+  const rawValue = String(value || '').trim();
+  const link = rawValue.match(/^\[([^\]]+)\]\(([^)]+)\)$/u);
+  if (link) return Object.freeze({ label: link[1], value: link[2], rawValue, form: 'markdown-link-entry' });
+  const separator = rawValue.indexOf(':');
+  if (separator >= 0) {
+    const label = rawValue.slice(0, separator).trim();
+    const fieldValue = rawValue.slice(separator + 1).trim();
+    return Object.freeze({ label, value: fieldValue, rawValue: fieldValue, form: fieldValue ? 'field' : 'block' });
+  }
+  return Object.freeze({ label: rawValue, value: null, rawValue, form: 'block' });
+}
+
+function indentationWidth(value = '') {
+  let width = 0;
+  for (const char of String(value || '')) width += char === '\t' ? 4 : 1;
+  return width;
+}
+
+function exactToken(value = '') { return String(value || '').trim(); }
+function finding(severity, code, message, state, extra = {}) { return portableFinding(severity, code, message, { ...extra, state }); }

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

@@ -0,0 +1,399 @@
+export function compileFieldValueConstraints(document = {}) {
+  const groups = document.validation?.groups || [];
+  const sourceSchemaId = String(document.schemaId || '');
+  const groupIndex = new Map();
+  for (const group of groups) {
+    const key = exactToken(group.name);
+    if (!groupIndex.has(key)) groupIndex.set(key, []);
+    groupIndex.get(key).push(group);
+  }
+
+  const constraints = [];
+  for (const group of groups) {
+    const category = (group.categories || []).find((item) => exactToken(item.name) === 'Field Value Constraints');
+    if (!category) continue;
+
+    for (const declaration of category.nodes || []) {
+      const field = exactToken(declaration.value);
+      const parsed = parseFieldValueConstraintDeclaration(declaration);
+      const local = ownedFields(group).has(field);
+      const base = {
+        kind: 'field-domain',
+        sourceSchemaId,
+        sourceGroup: group.name,
+        field,
+        allowedValues: Object.freeze(parsed.allowedValues),
+        allowedShapes: Object.freeze(parsed.allowedShapes),
+        domainPolicy: parsed.domainPolicy,
+        declarationLine: Number(declaration.line || 0),
+        declarationQualification: parsed.qualification,
+        declarationFindings: Object.freeze(parsed.findings)
+      };
+
+      if (!field) {
+        constraints.push(Object.freeze({
+          ...base,
+          targetMode: 'unresolved',
+          targetOwnership: 'unresolved',
+          targetGroup: '',
+          authorityQualification: 'structurally-invalid',
+          authorityFindings: Object.freeze(['Field Value Constraints declaration has no exact field label.'])
+        }));
+        continue;
+      }
+
+      if (local) {
+        constraints.push(Object.freeze({
+          ...base,
+          targetMode: 'local',
+          targetOwnership: 'source-local',
+          ownershipSourceSchemaIds: Object.freeze(sourceSchemaId ? [sourceSchemaId] : []),
+          targetGroup: group.name,
+          appliesToTarget: '',
+          authorityQualification: parsed.qualification,
+          authorityFindings: Object.freeze(parsed.findings)
+        }));
+        continue;
+      }
+
+      const appliesTo = unique(categoryItems(group, ['Applies To']).map(cleanToken).filter(Boolean));
+      const failures = [];
+      const resolvedTargets = [];
+      if (!appliesTo.length) failures.push(`Field ${field} is not owned locally and the declaring group has no Applies To targets.`);
+      for (const targetName of appliesTo) {
+        const matches = groupIndex.get(exactToken(targetName)) || [];
+        if (matches.length !== 1) {
+          failures.push(`Applies To target ${targetName} resolves to ${matches.length} contract groups.`);
+          continue;
+        }
+        if (!ownedFields(matches[0]).has(field)) {
+          failures.push(`Applies To target ${targetName} does not own exact field ${field} under Required Fields or Optional Fields.`);
+          continue;
+        }
+        resolvedTargets.push(matches[0]);
+      }
+
+      if (failures.length || resolvedTargets.length !== appliesTo.length) {
+        constraints.push(Object.freeze({
+          ...base,
+          targetMode: 'shared',
+          targetOwnership: 'unresolved',
+          targetGroup: '',
+          appliesToTargets: Object.freeze([...appliesTo]),
+          authorityQualification: parsed.qualification === 'valid' ? 'unresolved' : parsed.qualification,
+          authorityFindings: Object.freeze([...parsed.findings, ...failures])
+        }));
+        continue;
+      }
+
+      for (const target of resolvedTargets) {
+        constraints.push(Object.freeze({
+          ...base,
+          targetMode: 'shared',
+          targetOwnership: 'shared-applies-to',
+          targetGroup: target.name,
+          appliesToTarget: target.name,
+          appliesToTargets: Object.freeze([...appliesTo]),
+          targetOwnershipSourceSchemaIds: Object.freeze(sourceSchemaId ? [sourceSchemaId] : []),
+          authorityQualification: parsed.qualification,
+          authorityFindings: Object.freeze(parsed.findings)
+        }));
+      }
+    }
+  }
+  return Object.freeze(constraints);
+}
+
+export function resolveFieldDomainConstraintsAcrossChain(constraints = [], groups = [], compiledLineage = []) {
+  const groupIndex = new Map((groups || []).map((group) => [exactToken(group.name), group]));
+  const out = [];
+  for (const constraint of constraints || []) {
+    if (constraint.kind !== 'field-domain' || constraint.targetGroup || constraint.declarationQualification !== 'valid') {
+      out.push(constraint);
+      continue;
+    }
+
+    // Root local ownership is lineage-aware: a descendant contribution may narrow a field
+    // inherited by the same contract group without restating Required/Optional Fields.
+    // Full-chain composition is the first point where that ownership can be proven.
+    const declaringGroup = groupIndex.get(exactToken(constraint.sourceGroup));
+    const inheritedLocal = compiledLineage?.length
+      ? lineageLocalOwnershipAtSourcePoint(constraint, compiledLineage)
+      : lineageLocalOwnershipFromMergedGroup(declaringGroup, constraint.field, constraint.sourceSchemaId);
+    if (inheritedLocal.ambiguous) {
+      out.push(Object.freeze({
+        ...constraint,
+        targetOwnership: 'unresolved',
+        targetGroup: '',
+        authorityQualification: 'unresolved',
+        authorityFindings: inheritedLocal.findings
+      }));
+      continue;
+    }
+    if (inheritedLocal.owned) {
+      out.push(Object.freeze({
+        ...constraint,
+        targetMode: 'local',
+        targetOwnership: 'inherited-local',
+        ownershipSourceSchemaIds: inheritedLocal.sourceSchemaIds,
+        targetGroup: constraint.sourceGroup || declaringGroup?.name || '',
+        appliesToTarget: '',
+        authorityQualification: 'valid',
+        authorityFindings: Object.freeze([])
+      }));
+      continue;
+    }
+
+    const targetsWanted = unique(constraint.appliesToTargets || []);
+    if (!targetsWanted.length) {
+      out.push(Object.freeze({
+        ...constraint,
+        targetOwnership: 'unresolved',
+        authorityQualification: 'unresolved',
+        authorityFindings: Object.freeze([
+          `Field ${constraint.field} is not owned by declaring group ${constraint.sourceGroup || '(unknown group)'} in the supplied contract chain and no Applies To targets are available.`
+        ])
+      }));
+      continue;
+    }
+
+    const shared = compiledLineage?.length
+      ? resolveSharedTargetsAtSourcePoint(constraint, targetsWanted, compiledLineage)
+      : resolveSharedTargetsFromMergedGroups(constraint, targetsWanted, groupIndex);
+
+    if (!shared.resolved) {
+      out.push(Object.freeze({
+        ...constraint,
+        targetOwnership: 'unresolved',
+        authorityQualification: 'unresolved',
+        authorityFindings: shared.findings
+      }));
+      continue;
+    }
+
+    for (const target of shared.targets) {
+      out.push(Object.freeze({
+        ...constraint,
+        targetMode: 'shared',
+        targetOwnership: 'shared-applies-to',
+        targetGroup: target.name,
+        appliesToTarget: target.name,
+        targetOwnershipSourceSchemaIds: target.sourceSchemaIds,
+        authorityQualification: 'valid',
+        authorityFindings: Object.freeze([])
+      }));
+    }
+  }
+  return Object.freeze(out);
+}
+
+function resolveSharedTargetsAtSourcePoint(constraint = {}, targetsWanted = [], compiledLineage = []) {
+  const sourceSchemaId = String(constraint.sourceSchemaId || '');
+  const sourceMatches = compiledLineage
+    .map((item, index) => ({ item, index }))
+    .filter(({ item }) => String(item?.schemaId || '') === sourceSchemaId);
+
+  if (sourceMatches.length !== 1) {
+    return Object.freeze({
+      resolved: false,
+      targets: Object.freeze([]),
+      findings: Object.freeze([
+        `Field-domain source schema ${sourceSchemaId || '(unknown schema)'} resolves to ${sourceMatches.length} supplied lineage positions.`
+      ])
+    });
+  }
+
+  const sourceIndex = sourceMatches[0].index;
+  const prefix = compiledLineage.slice(0, sourceIndex + 1);
+  const failures = [];
+  const targets = [];
+
+  for (const targetName of targetsWanted) {
+    const occurrences = [];
+    let ambiguous = false;
+    for (const compiled of prefix) {
+      const matches = (compiled.validation?.groups || []).filter((group) => exactToken(group.name) === exactToken(targetName));
+      if (matches.length > 1) {
+        failures.push(`Applies To target ${targetName} resolves to ${matches.length} contract groups in source schema ${compiled.schemaId || '(unknown schema)'} at contribution source point ${sourceSchemaId || '(unknown schema)'}.`);
+        ambiguous = true;
+        break;
+      }
+      if (matches.length === 1) occurrences.push({ group: matches[0], sourceSchemaId: String(compiled.schemaId || '') });
+    }
+    if (ambiguous) continue;
+    if (!occurrences.length) {
+      failures.push(`Applies To target ${targetName} is unavailable at contribution source point ${sourceSchemaId || '(unknown schema)'}.`);
+      continue;
+    }
+
+    const owners = occurrences.filter(({ group }) => ownedFields(group).has(constraint.field));
+    if (!owners.length) {
+      failures.push(`Applies To target ${targetName} does not own exact field ${constraint.field} under Required Fields or Optional Fields at contribution source point ${sourceSchemaId || '(unknown schema)'}.`);
+      continue;
+    }
+
+    targets.push(Object.freeze({
+      name: occurrences.at(-1).group.name,
+      sourceSchemaIds: Object.freeze(unique(owners.map((item) => item.sourceSchemaId).filter(Boolean)))
+    }));
+  }
+
+  if (failures.length || targets.length !== targetsWanted.length) {
+    return Object.freeze({
+      resolved: false,
+      targets: Object.freeze([]),
+      findings: Object.freeze(failures)
+    });
+  }
+
+  return Object.freeze({ resolved: true, targets: Object.freeze(targets), findings: Object.freeze([]) });
+}
+
+function resolveSharedTargetsFromMergedGroups(constraint = {}, targetsWanted = [], groupIndex = new Map()) {
+  const failures = [];
+  const targets = [];
+  for (const targetName of targetsWanted) {
+    const target = groupIndex.get(exactToken(targetName));
+    if (!target) {
+      failures.push(`Applies To target ${targetName} is unavailable in the supplied contract chain.`);
+      continue;
+    }
+    if (!ownedFields(target).has(constraint.field)) {
+      failures.push(`Applies To target ${targetName} does not own exact field ${constraint.field} under Required Fields or Optional Fields in the supplied contract chain.`);
+      continue;
+    }
+    targets.push(Object.freeze({
+      name: target.name,
+      sourceSchemaIds: Object.freeze(unique((target.contributors || [])
+        .filter((item) => ownedFields(item).has(constraint.field))
+        .map((item) => String(item.sourceSchemaId || ''))
+        .filter(Boolean)))
+    }));
+  }
+  if (failures.length || targets.length !== targetsWanted.length) {
+    return Object.freeze({ resolved: false, targets: Object.freeze([]), findings: Object.freeze(failures) });
+  }
+  return Object.freeze({ resolved: true, targets: Object.freeze(targets), findings: Object.freeze([]) });
+}
+
+
+function lineageLocalOwnershipAtSourcePoint(constraint = {}, compiledLineage = []) {
+  const sourceSchemaId = String(constraint.sourceSchemaId || '');
+  const sourceMatches = compiledLineage
+    .map((item, index) => ({ item, index }))
+    .filter(({ item }) => String(item?.schemaId || '') === sourceSchemaId);
+  if (sourceMatches.length !== 1) return Object.freeze({
+    owned: false,
+    ambiguous: true,
+    sourceSchemaIds: Object.freeze([]),
+    findings: Object.freeze([`Field-domain source schema ${sourceSchemaId || '(unknown schema)'} resolves to ${sourceMatches.length} supplied lineage positions.`])
+  });
+
+  const prefix = compiledLineage.slice(0, sourceMatches[0].index + 1);
+  const owners = [];
+  for (const compiled of prefix) {
+    const matches = (compiled.validation?.groups || []).filter((group) => exactToken(group.name) === exactToken(constraint.sourceGroup));
+    if (matches.length > 1) return Object.freeze({
+      owned: false,
+      ambiguous: true,
+      sourceSchemaIds: Object.freeze([]),
+      findings: Object.freeze([
+        `Inherited local contract group ${constraint.sourceGroup || '(unknown group)'} resolves to ${matches.length} exact groups in source schema ${compiled.schemaId || '(unknown schema)'} at contribution source point ${sourceSchemaId || '(unknown schema)'}.`
+      ])
+    });
+    if (matches.length === 1 && ownedFields(matches[0]).has(constraint.field)) owners.push(String(compiled.schemaId || ''));
+  }
+  return Object.freeze({
+    owned: owners.length > 0,
+    ambiguous: false,
+    sourceSchemaIds: Object.freeze(unique(owners.filter(Boolean))),
+    findings: Object.freeze([])
+  });
+}
+
+function lineageLocalOwnershipFromMergedGroup(group = null, field = '', sourceSchemaId = '') {
+  if (!group || !sourceSchemaId) return Object.freeze({ owned: false, ambiguous: false, sourceSchemaIds: Object.freeze([]), findings: Object.freeze([]) });
+  const contributors = group.contributors?.length ? group.contributors : [group];
+  const sourceIndex = contributors.findIndex((item) => String(item.sourceSchemaId || '') === String(sourceSchemaId || ''));
+  if (sourceIndex < 0) return Object.freeze({ owned: false, ambiguous: false, sourceSchemaIds: Object.freeze([]), findings: Object.freeze([]) });
+  const prefix = contributors.slice(0, sourceIndex + 1);
+  const duplicateSources = unique(prefix.map((item) => String(item.sourceSchemaId || '')).filter(Boolean))
+    .filter((schemaId) => prefix.filter((item) => String(item.sourceSchemaId || '') === schemaId).length > 1);
+  if (duplicateSources.length) return Object.freeze({
+    owned: false,
+    ambiguous: true,
+    sourceSchemaIds: Object.freeze([]),
+    findings: Object.freeze(duplicateSources.map((schemaId) => `Inherited local contract group ${group.name || '(unknown group)'} is duplicated in source schema ${schemaId}.`))
+  });
+  const owners = prefix.filter((item) => ownedFields(item).has(field));
+  return Object.freeze({
+    owned: owners.length > 0,
+    ambiguous: false,
+    sourceSchemaIds: Object.freeze(unique(owners.map((item) => String(item.sourceSchemaId || '')).filter(Boolean))),
+    findings: Object.freeze([])
+  });
+}
+
+function parseFieldValueConstraintDeclaration(node = {}) {
+  const allowedValues = [];
+  const allowedShapes = [];
+  const policies = [];
+  const findings = [];
+  const unknownChildren = [];
+
+  for (const child of node.children || []) {
+    const parsed = splitConstraintProperty(child.value);
+    if (!parsed) {
+      unknownChildren.push(String(child.value || ''));
+      continue;
+    }
+    if ((child.children || []).length) {
+      unknownChildren.push(`${String(child.value || '')} -> nested declaration content`);
+      continue;
+    }
+    if (parsed.name === 'Allowed Value') allowedValues.push(parsed.value);
+    else if (parsed.name === 'Allowed Shape') allowedShapes.push(parsed.value);
+    else if (parsed.name === 'Domain Policy') policies.push(parsed.value);
+    else unknownChildren.push(String(child.value || ''));
+  }
+
+  if (policies.length !== 1) findings.push(`Expected exactly one Domain Policy; found ${policies.length}.`);
+  const domainPolicy = policies.length === 1 ? policies[0] : '';
+  if (domainPolicy && domainPolicy !== 'closed' && domainPolicy !== 'extension-authorized') findings.push(`Unsupported Domain Policy: ${domainPolicy}.`);
+  if (!allowedValues.length && !allowedShapes.length) findings.push('At least one Allowed Value or Allowed Shape is required.');
+  if (unknownChildren.length) findings.push(`Unsupported Field Value Constraints declaration properties: ${unknownChildren.join(', ')}.`);
+
+  return Object.freeze({
+    allowedValues: Object.freeze([...allowedValues]),
+    allowedShapes: Object.freeze([...allowedShapes]),
+    domainPolicy,
+    qualification: findings.length ? 'structurally-invalid' : 'valid',
+    findings: Object.freeze(findings)
+  });
+}
+
+function splitConstraintProperty(value = '') {
+  const text = String(value || '');
+  const separator = text.indexOf(':');
+  if (separator <= 0) return null;
+  const name = text.slice(0, separator).trim();
+  const propertyValue = text.slice(separator + 1).trim();
+  if (!name || !propertyValue) return null;
+  return { name, value: propertyValue };
+}
+
+function ownedFields(group = {}) {
+  return new Set([
+    ...categoryItems(group, ['Required Fields']),
+    ...categoryItems(group, ['Optional Fields'])
+  ].map(cleanToken).filter(Boolean));
+}
+
+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))]; }