@tiinex/core 0.1.1

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

@@ -0,0 +1,76 @@
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+
+export function parseStandaloneInheritanceRecord(input = '') {
+  const markdown = typeof input === 'string' ? input : String(input?.markdown || '');
+  let parsed;
+  try { parsed = parseArtifactMarkdown(markdown); }
+  catch { return blocked('Standalone inheritance record could not be parsed as a Tiinex artifact.'); }
+  if (String(parsed?.envelope?.current?.schema?.id || '') !== 'tiinex.schema.inheritance.v1') return blocked('Standalone inheritance record Current Schema must be tiinex.schema.inheritance.v1.');
+
+  const sections = secondLevelSections(markdown);
+  const identity = scalarFields(sections.get('Inheritance Identity') || '');
+  const parent = scalarFields(sections.get('Parent Contract') || '');
+  const child = scalarFields(sections.get('Child Contract') || '');
+  const mergeRules = repeatedRecords(sections.get('Merge Rules') || '');
+  const findings = [];
+  requireField(findings, identity, 'Inheritance Handle');
+  requireExact(findings, identity, 'Inheritance Kind', 'override');
+  requireField(findings, parent, 'Parent Schema');
+  requireField(findings, parent, 'Parent Contract Nodes');
+  requireExact(findings, parent, 'Parent Resolution State', 'resolved');
+  requireField(findings, child, 'Child Schema');
+  requireField(findings, child, 'Child Contract Nodes');
+  requireExact(findings, child, 'Child Resolution State', 'resolved');
+  if (!mergeRules.length) findings.push('Standalone inheritance record must declare at least one Merge Rules record.');
+
+  const rules = [];
+  for (const record of mergeRules) {
+    const operation = String(record.fields['Merge Operation'] || '').trim();
+    if (operation !== 'override') findings.push(`Merge Rules record ${record.name || '(unnamed)'} must use explicit Merge Operation: override.`);
+    for (const field of ['Applies To', 'Parent Node', 'Child Node']) if (!record.fields[field]) findings.push(`Merge Rules record ${record.name || '(unnamed)'} is missing ${field}.`);
+    if (record.fields['Parent Node'] && record.fields['Parent Node'] !== parent['Parent Contract Nodes']) findings.push(`Merge Rules record ${record.name || '(unnamed)'} Parent Node must exactly match Parent Contract Nodes.`);
+    if (record.fields['Child Node'] && record.fields['Child Node'] !== child['Child Contract Nodes']) findings.push(`Merge Rules record ${record.name || '(unnamed)'} Child Node must exactly match Child Contract Nodes.`);
+    rules.push(Object.freeze({ name: record.name, operation, parentNode: record.fields['Parent Node'] || '', childNode: record.fields['Child Node'] || '', appliesTo: record.fields['Applies To'] || '' }));
+  }
+  if (findings.length) return Object.freeze({ state: 'unresolved', findings: Object.freeze(findings), rules: Object.freeze([]) });
+  return Object.freeze({
+    state: 'qualified',
+    findings: Object.freeze([]),
+    handle: identity['Inheritance Handle'],
+    parentSchemaId: parent['Parent Schema'],
+    parentNode: parent['Parent Contract Nodes'],
+    childSchemaId: child['Child Schema'],
+    childNode: child['Child Contract Nodes'],
+    rules: Object.freeze(rules)
+  });
+}
+
+function secondLevelSections(markdown = '') {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const out = new Map(); let title = ''; let body = []; let fenced = false;
+  const flush = () => { if (title) out.set(title, body.join('\n').trim()); body = []; };
+  for (const line of lines) {
+    if (/^\s*```/.test(line)) { fenced = !fenced; if (title) body.push(line); continue; }
+    if (!fenced) { const match = line.match(/^##\s+(.+?)\s*$/); if (match) { flush(); title = match[1].trim(); continue; } }
+    if (title) body.push(line);
+  }
+  flush(); return out;
+}
+function scalarFields(text = '') {
+  const out = {};
+  for (const line of String(text || '').split('\n')) { const match = line.match(/^([A-Za-z][A-Za-z0-9 _+-]{0,80}):\s*(.*?)\s*$/); if (match) out[match[1].trim()] = match[2].trim(); }
+  return out;
+}
+function repeatedRecords(text = '') {
+  const records = []; let current = null;
+  const flush = () => { if (current) records.push(Object.freeze({ name: current.name, fields: Object.freeze({ ...current.fields }) })); current = null; };
+  for (const line of String(text || '').split('\n')) {
+    const top = line.match(/^-\s+(.+?)\s*$/); if (top) { flush(); current = { name: top[1].trim(), fields: {} }; continue; }
+    if (!current) continue;
+    const field = line.match(/^\s{2,}-\s*([A-Za-z][A-Za-z0-9 _+-]{0,80}):\s*(.*?)\s*$/); if (field) current.fields[field[1].trim()] = field[2].trim();
+  }
+  flush(); return records;
+}
+function requireField(findings, fields, name) { if (!String(fields?.[name] || '').trim()) findings.push(`Standalone inheritance record is missing ${name}.`); }
+function requireExact(findings, fields, name, expected) { if (String(fields?.[name] || '').trim() !== expected) findings.push(`Standalone inheritance record ${name} must be exactly ${expected}.`); }
+function blocked(message) { return Object.freeze({ state: 'unresolved', findings: Object.freeze([message]), rules: Object.freeze([]) }); }

package/src/tooling/portable/schema/contract.machine-shape.js

@@ -0,0 +1,309 @@
+import { compileLexicalShapeV1, qualifyLexicalShapeV1, PORTABLE_LEXICAL_SHAPE_PROFILE_V1 } from './lexical.shape.v1.js';
+
+export const PORTABLE_MACHINE_SHAPE_AUTHORITY_SCHEMA_ID = 'tiinex.portable.machine-shape-authority.v1';
+
+export function compileMachineShapeDefinitions(document = {}) {
+  const sourceSchemaId = String(document.schemaId || '');
+  const definitions = [];
+  for (const group of document.validation?.groups || []) {
+    for (const category of group.categories || []) {
+      if (exact(category.name) !== 'Machine Shape Definitions') continue;
+      for (const declaration of category.nodes || []) {
+        definitions.push(compileDefinition({ declaration, sourceSchemaId, sourceGroup: group.name }));
+      }
+    }
+  }
+  return Object.freeze(definitions);
+}
+
+export function resolveFieldDomainShapeAuthoritiesAcrossChain(constraints = [], compiledLineage = []) {
+  return Object.freeze((constraints || []).map((constraint) => {
+    if (constraint?.kind !== 'field-domain') return constraint;
+    const allowedShapes = constraint.allowedShapes || [];
+    if (!allowedShapes.length) return Object.freeze({ ...constraint, allowedShapeAuthorities: Object.freeze([]) });
+    const resolutions = allowedShapes.map((shape) => resolveShapeAtSourcePoint(shape, constraint.sourceSchemaId, compiledLineage));
+    return Object.freeze({ ...constraint, allowedShapeAuthorities: Object.freeze(resolutions) });
+  }));
+}
+
+export function summarizeMachineShapeAuthority(compiledLineage = []) {
+  const definitions = Object.freeze(compiledLineage.flatMap((item) => item.machineShapes?.definitions || []));
+  const leafSchemaId = String(compiledLineage.at(-1)?.schemaId || '');
+  const labels = unique(definitions.map((definition) => definition.shapeLabel));
+  const active = Object.freeze(labels.map((label) => resolveShapeAtSourcePoint(label, leafSchemaId, compiledLineage)));
+  const findings = [];
+  for (const definition of definitions) {
+    if (definition.definitionQualification === 'structurally-invalid') {
+      findings.push(Object.freeze({
+        state: 'structurally-invalid',
+        shapeLabel: definition.shapeLabel,
+        sourceSchemaId: definition.sourceSchemaId,
+        sourceGroup: definition.sourceGroup,
+        reasons: definition.definitionFindings
+      }));
+    }
+  }
+  for (const resolution of active) {
+    if (resolution.qualification === 'conflicting') findings.push(Object.freeze({
+      state: 'contradictory',
+      shapeLabel: resolution.shapeLabel,
+      reasons: resolution.findings
+    }));
+  }
+  return Object.freeze({
+    schema: PORTABLE_MACHINE_SHAPE_AUTHORITY_SCHEMA_ID,
+    definitions,
+    active,
+    findings: Object.freeze(findings)
+  });
+}
+
+export function projectMachineShapeSemanticIdentity(document = {}) {
+  const definitions = compileMachineShapeDefinitions(document).map(projectDefinitionSemanticIdentity);
+  definitions.sort(compareSemanticIdentity);
+  const categoryOccurrences = projectMachineShapeCategoryOccurrences(document);
+  return Object.freeze({
+    schema: PORTABLE_MACHINE_SHAPE_AUTHORITY_SCHEMA_ID,
+    categoryOccurrences,
+    definitions: Object.freeze(definitions)
+  });
+}
+
+function projectMachineShapeCategoryOccurrences(document = {}) {
+  const sourceSchemaId = String(document.schemaId || '');
+  const occurrences = [];
+  for (const group of document.validation?.groups || []) {
+    for (const category of group.categories || []) {
+      if (exact(category.name) !== 'Machine Shape Definitions') continue;
+      const definitions = (category.nodes || [])
+        .map((declaration) => compileDefinition({ declaration, sourceSchemaId, sourceGroup: group.name }))
+        .map(projectDefinitionSemanticIdentity)
+        .sort(compareSemanticIdentity);
+      occurrences.push(Object.freeze({
+        sourceSchemaId,
+        sourceGroup: String(group.name || ''),
+        category: 'Machine Shape Definitions',
+        definitions: Object.freeze(definitions)
+      }));
+    }
+  }
+  occurrences.sort(compareSemanticIdentity);
+  return Object.freeze(occurrences);
+}
+
+export function qualifyResolvedMachineShape(value = '', resolution = {}) {
+  if (resolution?.qualification !== 'evaluable' || !resolution.definition) return Object.freeze({ qualification: 'unresolved' });
+  const definition = resolution.definition;
+  if (definition.grammarProfile === PORTABLE_LEXICAL_SHAPE_PROFILE_V1) return qualifyLexicalShapeV1(definition.compiledGrammar, value);
+  return Object.freeze({ qualification: 'unresolved' });
+}
+
+function compileDefinition({ declaration = {}, sourceSchemaId = '', sourceGroup = '' } = {}) {
+  const shapeLabel = exact(declaration.value);
+  const profiles = [];
+  const startRules = [];
+  const grammarRules = [];
+  const humanMeanings = [];
+  const unknown = [];
+  const findings = [];
+
+  for (const child of declaration.children || []) {
+    const parsed = splitProperty(child.rawValue ?? child.value);
+    if (!parsed || (child.children || []).length) {
+      unknown.push(String(child.value || ''));
+      continue;
+    }
+    if (parsed.name === 'Grammar Profile') profiles.push(exact(parsed.value));
+    else if (parsed.name === 'Start Rule') startRules.push(exact(parsed.value));
+    else if (parsed.name === 'Grammar Rule') grammarRules.push(parsed.value);
+    else if (parsed.name === 'Human Meaning') humanMeanings.push(exact(parsed.value));
+    else unknown.push(String(child.value || ''));
+  }
+
+  if (!shapeLabel) findings.push('Machine Shape Definition has no exact shape label.');
+  if (profiles.length !== 1) findings.push(`Expected exactly one Grammar Profile; found ${profiles.length}.`);
+  if (startRules.length !== 1) findings.push(`Expected exactly one Start Rule; found ${startRules.length}.`);
+  if (!grammarRules.length) findings.push('Expected one or more Grammar Rule fields.');
+  if (humanMeanings.length !== 1) findings.push(`Expected exactly one Human Meaning; found ${humanMeanings.length}.`);
+  if (unknown.length) findings.push(`Unsupported Machine Shape Definition properties: ${unknown.join(', ')}.`);
+
+  const grammarProfile = profiles.length === 1 ? profiles[0] : '';
+  const startRule = startRules.length === 1 ? startRules[0] : '';
+  const humanMeaning = humanMeanings.length === 1 ? humanMeanings[0] : '';
+  let compiledGrammar = null;
+  let qualificationSupport = 'unavailable';
+
+  if (!findings.length && grammarProfile === PORTABLE_LEXICAL_SHAPE_PROFILE_V1) {
+    compiledGrammar = compileLexicalShapeV1({ startRule, grammarRules });
+    qualificationSupport = compiledGrammar.qualification === 'valid' ? 'available' : 'invalid';
+    if (compiledGrammar.qualification !== 'valid') findings.push(...compiledGrammar.findings);
+  } else if (findings.length) {
+    qualificationSupport = 'invalid';
+  }
+
+  return Object.freeze({
+    kind: 'machine-shape-definition',
+    shapeLabel,
+    sourceSchemaId,
+    sourceGroup,
+    declarationSource: Object.freeze({ line: Number(declaration.line || 0) }),
+    visibilityPolicy: 'lineage-prefix-ancestors-and-same-source',
+    grammarProfile,
+    startRule,
+    grammarRules: Object.freeze([...grammarRules]),
+    humanMeaning,
+    qualificationSupport,
+    definitionQualification: findings.length ? 'structurally-invalid' : 'valid',
+    definitionFindings: Object.freeze(findings),
+    declarationStructure: projectDeclarationStructure(declaration),
+    compiledGrammar
+  });
+}
+
+function projectDefinitionSemanticIdentity(definition = {}) {
+  const common = {
+    shapeLabel: String(definition.shapeLabel || ''),
+    sourceSchemaId: String(definition.sourceSchemaId || ''),
+    sourceGroup: String(definition.sourceGroup || ''),
+    grammarProfile: String(definition.grammarProfile || ''),
+    startRule: String(definition.startRule || ''),
+    humanMeaning: String(definition.humanMeaning || ''),
+    qualificationSupport: String(definition.qualificationSupport || ''),
+    definitionQualification: String(definition.definitionQualification || ''),
+    grammarRuleCount: (definition.grammarRules || []).length
+  };
+
+  if (definition.grammarProfile === PORTABLE_LEXICAL_SHAPE_PROFILE_V1 && definition.compiledGrammar?.qualification === 'valid') {
+    return Object.freeze({
+      ...common,
+      grammar: projectValidLexicalGrammar(definition.compiledGrammar)
+    });
+  }
+
+  return Object.freeze({
+    ...common,
+    structuralDeclaration: definition.declarationStructure || Object.freeze({ value: String(definition.shapeLabel || ''), children: Object.freeze([]) }),
+    grammar: Object.freeze({
+      qualification: String(definition.compiledGrammar?.qualification || definition.definitionQualification || ''),
+      rawRules: Object.freeze([...(definition.grammarRules || [])].map(String).sort(compareExactStrings))
+    })
+  });
+}
+
+function projectDeclarationStructure(node = {}, isRoot = true) {
+  const children = (node.children || []).map((child) => projectDeclarationStructure(child, false));
+  children.sort(compareSemanticIdentity);
+  return Object.freeze({
+    value: isRoot ? exact(node.value) : String(node.rawValue ?? node.value ?? ''),
+    children: Object.freeze(children)
+  });
+}
+
+function projectValidLexicalGrammar(compiled = {}) {
+  const rules = (compiled.grammarRules || []).map((rule) => Object.freeze({
+    name: String(rule.name || ''),
+    expression: canonicalExpression(rule.expression)
+  }));
+  rules.sort((left, right) => compareExactStrings(left.name, right.name) || compareSemanticIdentity(left, right));
+  return Object.freeze({
+    qualification: String(compiled.qualification || ''),
+    startRule: String(compiled.startRule || ''),
+    rules: Object.freeze(rules)
+  });
+}
+
+function canonicalExpression(node = {}) {
+  if (!node || typeof node !== 'object') return node;
+  if (node.type === 'alternation') {
+    const alternatives = (node.alternatives || []).map(canonicalExpression).sort(compareSemanticIdentity);
+    return Object.freeze({ type: 'alternation', alternatives: Object.freeze(alternatives) });
+  }
+  if (node.type === 'concatenation') {
+    return Object.freeze({ type: 'concatenation', parts: Object.freeze((node.parts || []).map(canonicalExpression)) });
+  }
+  if (node.type === 'repeat') {
+    return Object.freeze({ type: 'repeat', quantifier: String(node.quantifier || ''), expression: canonicalExpression(node.expression) });
+  }
+  if (node.type === 'any-except') {
+    return Object.freeze({ type: 'any-except', exclusions: Object.freeze([...(node.exclusions || [])].map(String).sort(compareExactStrings)) });
+  }
+  if (node.type === 'literal') return Object.freeze({ type: 'literal', value: String(node.value ?? '') });
+  if (node.type === 'builtin') return Object.freeze({ type: 'builtin', name: String(node.name || '') });
+  if (node.type === 'reference') return Object.freeze({ type: 'reference', name: String(node.name || '') });
+  return Object.freeze({ ...node });
+}
+
+function compareSemanticIdentity(left = {}, right = {}) {
+  return compareExactStrings(JSON.stringify(left), JSON.stringify(right));
+}
+
+function compareExactStrings(left = '', right = '') {
+  const a = String(left);
+  const b = String(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function resolveShapeAtSourcePoint(shapeLabel = '', sourceSchemaId = '', compiledLineage = []) {
+  const label = exact(shapeLabel);
+  const sourceMatches = compiledLineage
+    .map((item, index) => ({ item, index }))
+    .filter(({ item }) => String(item?.schemaId || '') === String(sourceSchemaId || ''));
+  if (sourceMatches.length !== 1) return resolution(label, 'unresolved', null, [
+    `Machine-shape use source schema ${sourceSchemaId || '(unknown schema)'} resolves to ${sourceMatches.length} lineage positions.`
+  ], [], sourceSchemaId, []);
+
+  const prefix = compiledLineage.slice(0, sourceMatches[0].index + 1);
+  const visibleSchemaIds = prefix.map((item) => String(item?.schemaId || '')).filter(Boolean);
+  const visible = prefix.flatMap((item) => (item.machineShapes?.definitions || []).filter((definition) => exact(definition.shapeLabel) === label));
+  if (!visible.length) return resolution(label, 'unresolved', null, [`No visible Machine Shape Definition exists for exact label ${label || '(empty)'}.`], [], sourceSchemaId, visibleSchemaIds);
+  if (visible.length > 1) return resolution(label, 'conflicting', null, [`Exact Machine Shape Definition label ${label} resolves to ${visible.length} active definitions at source point ${sourceSchemaId}.`], visible, sourceSchemaId, visibleSchemaIds);
+
+  const definition = visible[0];
+  if (definition.definitionQualification !== 'valid') return resolution(label, 'unresolved', definition, [
+    `Machine Shape Definition ${label} is structurally invalid.`,
+    ...(definition.definitionFindings || [])
+  ], visible, sourceSchemaId, visibleSchemaIds);
+  if (definition.qualificationSupport !== 'available') return resolution(label, 'unresolved', definition, [
+    `Machine Shape Definition ${label} uses unsupported or unavailable Grammar Profile ${definition.grammarProfile || '(none)'}.`
+  ], visible, sourceSchemaId, visibleSchemaIds);
+  return resolution(label, 'evaluable', definition, [], visible, sourceSchemaId, visibleSchemaIds);
+}
+
+function resolution(shapeLabel, qualification, definition, findings, visibleDefinitions, useSourceSchemaId = '', visibleSchemaIds = []) {
+  return Object.freeze({
+    shapeLabel,
+    qualification,
+    useSourceSchemaId: String(useSourceSchemaId || ''),
+    visibilityPolicy: 'lineage-prefix-ancestors-and-same-source',
+    visibleSchemaIds: Object.freeze([...visibleSchemaIds]),
+    definition: definition || null,
+    resolvedDefinitionProvenance: definition ? Object.freeze({
+      sourceSchemaId: definition.sourceSchemaId,
+      sourceGroup: definition.sourceGroup,
+      declarationSource: definition.declarationSource
+    }) : null,
+    visibleDefinitions: Object.freeze((visibleDefinitions || []).map((item) => Object.freeze({
+      shapeLabel: item.shapeLabel,
+      sourceSchemaId: item.sourceSchemaId,
+      sourceGroup: item.sourceGroup,
+      declarationSource: item.declarationSource,
+      grammarProfile: item.grammarProfile,
+      definitionQualification: item.definitionQualification,
+      qualificationSupport: item.qualificationSupport
+    }))),
+    findings: Object.freeze(findings || [])
+  });
+}
+
+function splitProperty(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);
+  if (!name || !exact(propertyValue)) return null;
+  return { name, value: propertyValue };
+}
+
+function exact(value = '') { return String(value || '').trim(); }
+function unique(values = []) { return [...new Set(values.map(exact).filter(Boolean))]; }

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

@@ -0,0 +1,81 @@
+import { compilePortableSchemaContract } from './contract.compile.js';
+import { validatePortableContractInstance } from './contract.validate.js';
+import { resolveClassificationAgreement } from './contract.semantic-resolution.js';
+
+export const PORTABLE_RESOLVED_INSTANCE_PROJECTION_SCHEMA_ID = 'tiinex.portable.resolved-contract-instance.v1';
+
+export function projectPortableContractInstance(input = {}, options = {}) {
+  if (Object.prototype.hasOwnProperty.call(input, 'validation')) {
+    throw new TypeError('projectPortableContractInstance owns validation; precomputed validation input is not accepted because authority context must remain coherent.');
+  }
+  const compiled = input.compiledContract || compilePortableSchemaContract(input.schemaMarkdown || input.schemaDocument || '');
+  const resolvers = input.resolvers || options.resolvers || {};
+  const validation = validatePortableContractInstance({
+    markdown: String(input.markdown || ''),
+    compiledContract: compiled,
+    resolvers
+  });
+  const constraintIndex = classificationConstraintsByGroup(compiled.constraints || []);
+  const declarations = [];
+
+  for (const parsedGroup of validation.declarations || []) {
+    const group = parsedGroup.contract.group;
+    const constraints = constraintIndex.get(exactToken(group)) || [];
+    if (!constraints.length) continue;
+    const sections = [];
+    for (const section of parsedGroup.sections || []) {
+      const entries = [];
+      for (const entry of section.entries || []) {
+        if (entry.name === 'none') continue;
+        const semantics = constraints.map((constraint) => resolveClassificationAgreement({ entry, constraint, resolvers }));
+        entries.push(Object.freeze({
+          name: entry.name,
+          declaredFields: entry.fields,
+          semantics: Object.freeze(semantics)
+        }));
+      }
+      sections.push(Object.freeze({
+        heading: section.heading,
+        present: Boolean(section.present),
+        entries: Object.freeze(entries)
+      }));
+    }
+    declarations.push(Object.freeze({
+      group,
+      targetHeadings: parsedGroup.contract.targetHeadings,
+      sections: Object.freeze(sections)
+    }));
+  }
+
+  return Object.freeze({
+    schema: PORTABLE_RESOLVED_INSTANCE_PROJECTION_SCHEMA_ID,
+    schemaId: compiled.schemaId,
+    validation,
+    ordinaryGroups: validation.ordinaryGroups || Object.freeze([]),
+    fieldDomains: validation.fieldDomains || Object.freeze({ groups: Object.freeze([]), findings: Object.freeze([]) }),
+    declarations: Object.freeze(declarations),
+    limitations: Object.freeze([
+      'Projection is read-only and preserves declared fields separately from resolved semantics.',
+      'Ordinary contract-instance fields are projected only through compiled Root/schema target authority; document-wide label fallback is not used.',
+      'Field-domain truth is projected from compiled Field Value Constraints contributions without reinterpreting Allowed Labels.',
+      'Schema assignability/ancestor matching is not inferred by this projection.'
+    ])
+  });
+}
+
+function classificationConstraintsByGroup(constraints = []) {
+  const out = new Map();
+  for (const constraint of constraints) {
+    if (constraint.kind !== 'classification-agreement') continue;
+    for (const group of constraint.groups || []) {
+      const key = exactToken(group);
+      if (!out.has(key)) out.set(key, []);
+      out.get(key).push(constraint);
+    }
+  }
+  return out;
+}
+
+function exactToken(value = '') {
+  return String(value || '').trim();
+}

package/src/tooling/portable/schema/contract.semantic-resolution.js

@@ -0,0 +1,82 @@
+export const PORTABLE_CONTRACT_SEMANTIC_RESOLUTION_SCHEMA_ID = 'tiinex.portable.contract-semantic-resolution.v1';
+
+const KNOWN_PARTICIPANT_CLASSIFICATIONS = new Set(['artifact', 'non-artifact']);
+
+export function resolveSchemaAuthority(schemaId, resolvers = {}) {
+  const id = String(schemaId || '').trim();
+  if (!id) return null;
+  if (typeof resolvers.resolveSchemaAuthority === 'function') return resolvers.resolveSchemaAuthority(id) || null;
+  return resolvers.schemaAuthorities?.[id] || null;
+}
+
+export function resolveClassificationAgreement(input = {}) {
+  const entry = input.entry || {};
+  const constraint = input.constraint || {};
+  const resolvers = input.resolvers || {};
+  const explicitField = String(constraint.explicitField || '').trim();
+  const schemaField = String(constraint.schemaField || '').trim();
+  const declared = fieldValue(entry, explicitField);
+  const schemaId = fieldValue(entry, schemaField);
+  const authority = resolveSchemaAuthority(schemaId, resolvers);
+  const authorityObserved = String(authority?.targetKind || '').trim();
+  const authorityResolved = KNOWN_PARTICIPANT_CLASSIFICATIONS.has(authorityObserved) ? authorityObserved : '';
+  const schemaConstraintQualification = !schemaId
+    ? 'absent'
+    : authorityResolved
+      ? 'resolved'
+      : 'unresolved';
+
+  const evidence = [];
+  if (declared) evidence.push(Object.freeze({ source: 'explicit-declaration', field: explicitField, value: declared }));
+  if (schemaId) evidence.push(Object.freeze({ source: 'schema-constraint', field: schemaField, schemaId, targetKind: authorityObserved, qualification: schemaConstraintQualification }));
+
+  let qualification = 'unresolved';
+  let resolved = '';
+  let authoritySource = '';
+
+  if (declared === 'unknown') {
+    qualification = 'preserved-unknown';
+    resolved = 'unknown';
+    authoritySource = 'explicit-declaration';
+  } else if (KNOWN_PARTICIPANT_CLASSIFICATIONS.has(declared) && authorityResolved) {
+    if (declared === authorityResolved) {
+      qualification = 'agreement';
+      resolved = declared;
+      authoritySource = 'explicit+schema-constraint';
+    } else {
+      qualification = 'contradictory';
+      resolved = '';
+      authoritySource = 'conflicting-authorities';
+    }
+  } else if (KNOWN_PARTICIPANT_CLASSIFICATIONS.has(declared)) {
+    qualification = 'explicit';
+    resolved = declared;
+    authoritySource = 'explicit-declaration';
+  } else if (!declared && authorityResolved) {
+    qualification = 'resolved-by-authority';
+    resolved = authorityResolved;
+    authoritySource = 'schema-constraint';
+  }
+
+  return Object.freeze({
+    schema: PORTABLE_CONTRACT_SEMANTIC_RESOLUTION_SCHEMA_ID,
+    kind: 'classification-agreement',
+    field: explicitField,
+    schemaField,
+    declared,
+    resolved,
+    qualification,
+    authority: authoritySource,
+    schemaConstraint: Object.freeze({
+      schemaId,
+      qualification: schemaConstraintQualification,
+      observedTargetKind: authorityObserved
+    }),
+    evidence: Object.freeze(evidence)
+  });
+}
+
+function fieldValue(entry = {}, field = '') {
+  if (!field || !Object.prototype.hasOwnProperty.call(entry.fields || {}, field)) return '';
+  return String(entry.fields[field] ?? '').trim();
+}