@tiinex/core 0.1.1

package/src/tooling/portable/schema/lexical.shape.v1.js

@@ -0,0 +1,338 @@
+export const PORTABLE_LEXICAL_SHAPE_PROFILE_V1 = 'tiinex.lexical.shape.v1';
+
+const RESERVED_IDENTIFIERS = new Set(['SPACE', 'TAB', 'CR', 'LF', 'DIGIT', 'ASCII-LETTER', 'ANY', 'ANY-EXCEPT']);
+const SIMPLE_BUILTINS = new Set(['SPACE', 'TAB', 'CR', 'LF', 'DIGIT', 'ASCII-LETTER', 'ANY']);
+
+export function compileLexicalShapeV1(input = {}) {
+  const startRule = exact(input.startRule);
+  const grammarRules = Array.isArray(input.grammarRules) ? input.grammarRules.map(String) : [];
+  const findings = [];
+  const rules = [];
+  const byName = new Map();
+
+  if (!grammarRules.length) findings.push('At least one Grammar Rule is required.');
+  for (let index = 0; index < grammarRules.length; index += 1) {
+    const source = grammarRules[index];
+    try {
+      const parsed = parseGrammarRule(source);
+      if (RESERVED_IDENTIFIERS.has(parsed.name)) throw new GrammarError(`Grammar Rule identifier is reserved: ${parsed.name}.`);
+      if (byName.has(parsed.name)) throw new GrammarError(`Duplicate Grammar Rule identifier: ${parsed.name}.`);
+      const rule = { name: parsed.name, source, expression: parsed.expression };
+      byName.set(parsed.name, rule);
+      rules.push(rule);
+    } catch (error) {
+      findings.push(`Grammar Rule ${index + 1}: ${messageOf(error)}`);
+    }
+  }
+
+  if (!startRule) findings.push('Start Rule is required.');
+  else if (!byName.has(startRule)) findings.push(`Start Rule does not resolve to a declared Grammar Rule: ${startRule}.`);
+
+  if (!findings.length) {
+    for (const rule of rules) {
+      for (const reference of collectReferences(rule.expression)) {
+        if (!byName.has(reference)) findings.push(`Undefined local Grammar Rule reference: ${reference}.`);
+      }
+    }
+  }
+  if (!findings.length) findings.push(...detectCycles(rules));
+
+  const frozenRules = Object.freeze(rules.map((rule) => Object.freeze({
+    name: rule.name,
+    source: rule.source,
+    expression: freezeNode(rule.expression)
+  })));
+  return Object.freeze({
+    profile: PORTABLE_LEXICAL_SHAPE_PROFILE_V1,
+    qualification: findings.length ? 'structurally-invalid' : 'valid',
+    startRule,
+    grammarRules: frozenRules,
+    findings: Object.freeze(findings)
+  });
+}
+
+export function qualifyLexicalShapeV1(compiled = {}, value = '') {
+  if (compiled?.qualification !== 'valid') return Object.freeze({ qualification: 'unresolved' });
+  const rules = new Map((compiled.grammarRules || []).map((rule) => [rule.name, rule.expression]));
+  const start = rules.get(compiled.startRule);
+  if (!start) return Object.freeze({ qualification: 'unresolved' });
+  const scalars = [...String(value ?? '')];
+  const memo = new WeakMap();
+  const positions = matchNode(start, 0, scalars, rules, memo);
+  return Object.freeze({ qualification: positions.has(scalars.length) ? 'matched' : 'not-matched' });
+}
+
+function parseGrammarRule(source = '') {
+  const tokens = tokenizeGrammar(source);
+  const parser = new Parser(tokens);
+  const name = parser.takeIdentifier('Grammar Rule identifier');
+  parser.expect('=');
+  const expression = parser.parseExpression(new Set(['eof']));
+  parser.expect('eof');
+  return { name, expression };
+}
+
+function tokenizeGrammar(source = '') {
+  const text = String(source ?? '');
+  const tokens = [];
+  let index = 0;
+  while (index < text.length) {
+    const ch = text[index];
+    if (ch === ' ' || ch === '\t') { index += 1; continue; }
+    if (isForbiddenMetaWhitespace(ch)) throw new GrammarError(`Unsupported grammar-source whitespace U+${ch.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}.`);
+    if (ch === '"') {
+      const parsed = readQuotedLiteral(text, index);
+      tokens.push({ type: 'literal', value: parsed.value });
+      index = parsed.next;
+      continue;
+    }
+    if (/[A-Za-z]/.test(ch)) {
+      let end = index + 1;
+      while (end < text.length && /[A-Za-z0-9-]/.test(text[end])) end += 1;
+      tokens.push({ type: 'identifier', value: text.slice(index, end) });
+      index = end;
+      continue;
+    }
+    if ('?*+|(),='.includes(ch)) {
+      tokens.push({ type: ch, value: ch });
+      index += 1;
+      continue;
+    }
+    throw new GrammarError(`Unsupported grammar token: ${ch}.`);
+  }
+  tokens.push({ type: 'eof', value: '' });
+  return tokens;
+}
+
+function readQuotedLiteral(text, start) {
+  let index = start + 1;
+  let value = '';
+  while (index < text.length) {
+    const ch = text[index];
+    if (ch === '"') return { value, next: index + 1 };
+    if (ch !== '\\') {
+      value += ch;
+      index += 1;
+      continue;
+    }
+    if (index + 1 >= text.length) throw new GrammarError('Unterminated quoted-literal escape.');
+    const escaped = text[index + 1];
+    if (escaped === '"') value += '"';
+    else if (escaped === '\\') value += '\\';
+    else if (escaped === 't') value += '\t';
+    else if (escaped === 'r') value += '\r';
+    else if (escaped === 'n') value += '\n';
+    else throw new GrammarError(`Invalid quoted-literal escape: \\${escaped}.`);
+    index += 2;
+  }
+  throw new GrammarError('Unterminated quoted literal.');
+}
+
+class Parser {
+  constructor(tokens) { this.tokens = tokens; this.index = 0; }
+  peek() { return this.tokens[this.index] || { type: 'eof', value: '' }; }
+  take() { const token = this.peek(); this.index += 1; return token; }
+  expect(type) {
+    const token = this.peek();
+    if (token.type !== type) throw new GrammarError(`Expected ${display(type)} but found ${display(token.type)}.`);
+    return this.take();
+  }
+  takeIdentifier(label = 'identifier') {
+    const token = this.peek();
+    if (token.type !== 'identifier') throw new GrammarError(`Expected ${label}.`);
+    return this.take().value;
+  }
+  parseExpression(stops = new Set(['eof'])) {
+    if (stops.has(this.peek().type) || this.peek().type === '|') throw new GrammarError('Expression must not be empty.');
+    const alternatives = [this.parseConcatenation(stops)];
+    while (this.peek().type === '|') {
+      this.take();
+      if (stops.has(this.peek().type) || this.peek().type === '|') throw new GrammarError('Alternation sides must not be empty.');
+      alternatives.push(this.parseConcatenation(stops));
+    }
+    return alternatives.length === 1 ? alternatives[0] : { type: 'alternation', alternatives };
+  }
+  parseConcatenation(stops) {
+    const parts = [];
+    while (!stops.has(this.peek().type) && this.peek().type !== '|') parts.push(this.parsePostfix());
+    if (!parts.length) throw new GrammarError('Concatenation must not be empty.');
+    return parts.length === 1 ? parts[0] : { type: 'concatenation', parts };
+  }
+  parsePostfix() {
+    const atom = this.parseAtom();
+    let quantifier = '';
+    if (['?', '*', '+'].includes(this.peek().type)) quantifier = this.take().type;
+    if (['?', '*', '+'].includes(this.peek().type)) throw new GrammarError('A postfix-expression permits at most one postfix quantifier.');
+    return quantifier ? { type: 'repeat', quantifier, expression: atom } : atom;
+  }
+  parseAtom() {
+    const token = this.peek();
+    if (token.type === 'literal') { this.take(); return { type: 'literal', value: token.value }; }
+    if (token.type === '(') {
+      this.take();
+      if (this.peek().type === ')') throw new GrammarError('Parenthesized expression must not be empty.');
+      const expression = this.parseExpression(new Set([')']));
+      this.expect(')');
+      return expression;
+    }
+    if (token.type !== 'identifier') throw new GrammarError(`Expected expression atom but found ${display(token.type)}.`);
+    const name = this.take().value;
+    if (name === 'ANY-EXCEPT') return this.parseAnyExcept();
+    if (SIMPLE_BUILTINS.has(name)) return { type: 'builtin', name };
+    return { type: 'reference', name };
+  }
+  parseAnyExcept() {
+    this.expect('(');
+    const exclusions = [];
+    if (this.peek().type === ')') throw new GrammarError('ANY-EXCEPT requires one or more exclusions.');
+    while (true) {
+      const token = this.peek();
+      if (token.type === 'literal') {
+        this.take();
+        if ([...token.value].length !== 1) throw new GrammarError('ANY-EXCEPT quoted exclusions must contain exactly one Unicode scalar.');
+        exclusions.push(token.value);
+      } else if (token.type === 'identifier' && ['SPACE', 'TAB', 'CR', 'LF'].includes(token.value)) {
+        this.take();
+        exclusions.push(builtinScalar(token.value));
+      } else {
+        throw new GrammarError('ANY-EXCEPT exclusion must be a one-scalar quoted literal or SPACE/TAB/CR/LF.');
+      }
+      if (this.peek().type === ',') { this.take(); continue; }
+      break;
+    }
+    this.expect(')');
+    return { type: 'any-except', exclusions };
+  }
+}
+
+function matchNode(node, pos, scalars, rules, memo) {
+  let perNode = memo.get(node);
+  if (!perNode) { perNode = new Map(); memo.set(node, perNode); }
+  if (perNode.has(pos)) return perNode.get(pos);
+  const out = new Set();
+  perNode.set(pos, out);
+
+  if (node.type === 'literal') {
+    const literal = [...node.value];
+    if (matchesAt(scalars, pos, literal)) out.add(pos + literal.length);
+  } else if (node.type === 'builtin') {
+    if (pos < scalars.length && builtinMatches(node.name, scalars[pos])) out.add(pos + 1);
+  } else if (node.type === 'any-except') {
+    if (pos < scalars.length && !node.exclusions.includes(scalars[pos])) out.add(pos + 1);
+  } else if (node.type === 'reference') {
+    const target = rules.get(node.name);
+    if (target) addAll(out, matchNode(target, pos, scalars, rules, memo));
+  } else if (node.type === 'alternation') {
+    for (const alternative of node.alternatives) addAll(out, matchNode(alternative, pos, scalars, rules, memo));
+  } else if (node.type === 'concatenation') {
+    let positions = new Set([pos]);
+    for (const part of node.parts) {
+      const next = new Set();
+      for (const current of positions) addAll(next, matchNode(part, current, scalars, rules, memo));
+      positions = next;
+      if (!positions.size) break;
+    }
+    addAll(out, positions);
+  } else if (node.type === 'repeat') {
+    if (node.quantifier === '?') {
+      out.add(pos);
+      addAll(out, matchNode(node.expression, pos, scalars, rules, memo));
+    } else if (node.quantifier === '*') {
+      addAll(out, repetitionClosure(node.expression, new Set([pos]), scalars, rules, memo));
+    } else if (node.quantifier === '+') {
+      const first = matchNode(node.expression, pos, scalars, rules, memo);
+      addAll(out, repetitionClosure(node.expression, first, scalars, rules, memo));
+    }
+  }
+  return out;
+}
+
+function repetitionClosure(expression, seeds, scalars, rules, memo) {
+  const seen = new Set(seeds);
+  const queue = [...seeds];
+  while (queue.length) {
+    const pos = queue.shift();
+    for (const next of matchNode(expression, pos, scalars, rules, memo)) {
+      if (seen.has(next)) continue;
+      seen.add(next);
+      queue.push(next);
+    }
+  }
+  return seen;
+}
+
+function builtinMatches(name, scalar) {
+  if (name === 'SPACE') return scalar === ' ';
+  if (name === 'TAB') return scalar === '\t';
+  if (name === 'CR') return scalar === '\r';
+  if (name === 'LF') return scalar === '\n';
+  if (name === 'DIGIT') return /^[0-9]$/.test(scalar);
+  if (name === 'ASCII-LETTER') return /^[A-Za-z]$/.test(scalar);
+  if (name === 'ANY') return true;
+  return false;
+}
+
+function builtinScalar(name) {
+  if (name === 'SPACE') return ' ';
+  if (name === 'TAB') return '\t';
+  if (name === 'CR') return '\r';
+  if (name === 'LF') return '\n';
+  return '';
+}
+
+function matchesAt(scalars, pos, literal) {
+  if (pos + literal.length > scalars.length) return false;
+  for (let index = 0; index < literal.length; index += 1) if (scalars[pos + index] !== literal[index]) return false;
+  return true;
+}
+
+function collectReferences(node, out = new Set()) {
+  if (!node) return out;
+  if (node.type === 'reference') out.add(node.name);
+  else if (node.type === 'alternation') for (const child of node.alternatives) collectReferences(child, out);
+  else if (node.type === 'concatenation') for (const child of node.parts) collectReferences(child, out);
+  else if (node.type === 'repeat') collectReferences(node.expression, out);
+  return out;
+}
+
+function detectCycles(rules = []) {
+  const graph = new Map(rules.map((rule) => [rule.name, [...collectReferences(rule.expression)]]));
+  const visiting = new Set();
+  const visited = new Set();
+  const findings = [];
+  function visit(name, stack = []) {
+    if (visiting.has(name)) {
+      findings.push(`Cyclic Grammar Rule reference: ${[...stack, name].join(' -> ')}.`);
+      return;
+    }
+    if (visited.has(name)) return;
+    visiting.add(name);
+    for (const next of graph.get(name) || []) if (graph.has(next)) visit(next, [...stack, name]);
+    visiting.delete(name);
+    visited.add(name);
+  }
+  for (const name of graph.keys()) visit(name, []);
+  return unique(findings);
+}
+
+function freezeNode(node = {}) {
+  if (!node || typeof node !== 'object') return node;
+  if (node.type === 'alternation') return Object.freeze({ type: node.type, alternatives: Object.freeze(node.alternatives.map(freezeNode)) });
+  if (node.type === 'concatenation') return Object.freeze({ type: node.type, parts: Object.freeze(node.parts.map(freezeNode)) });
+  if (node.type === 'repeat') return Object.freeze({ type: node.type, quantifier: node.quantifier, expression: freezeNode(node.expression) });
+  if (node.type === 'any-except') return Object.freeze({ type: node.type, exclusions: Object.freeze([...node.exclusions]) });
+  return Object.freeze({ ...node });
+}
+
+function isForbiddenMetaWhitespace(ch) {
+  if (ch === '\r' || ch === '\n') return true;
+  if (ch === ' ' || ch === '\t') return false;
+  return /^\s$/u.test(ch);
+}
+
+function addAll(target, source) { for (const item of source || []) target.add(item); }
+function exact(value = '') { return String(value || '').trim(); }
+function display(type = '') { return type === 'eof' ? 'end of grammar rule' : `token ${type}`; }
+function messageOf(error) { return error instanceof Error ? error.message : String(error); }
+function unique(values = []) { return [...new Set(values)]; }
+class GrammarError extends Error {}

package/src/tooling/portable/schema/llm.companion.js

@@ -0,0 +1,108 @@
+import { portableFinding } from '../findings.js';
+
+export const PORTABLE_LLM_SCHEMA_COMPANION_SCHEMA_ID = 'tiinex.llm.schema-companion.v1';
+
+export function resolvePortableLlmCompanion({ schemaId = '', task = 'read', module = null, input = {}, options = {} } = {}) {
+  const findings = [];
+  const direct = input.llmCompanion || options.llmCompanion || null;
+  const collection = input.llmCompanions || options.llmCompanions || null;
+  const fromCollection = companionFromCollection(collection, schemaId);
+  const materialResult = companionFromMaterial(input.materials || input, schemaId);
+  findings.push(...materialResult.findings);
+  const raw = direct || fromCollection || materialResult.companion || module?.llmCompanion || module?.llm || null;
+  if (!raw) return Object.freeze({ companion: emptyCompanion(task), findings: Object.freeze(findings) });
+
+  const declaredSchemaId = String(raw.schemaId || '').trim();
+  if (declaredSchemaId && declaredSchemaId !== schemaId) {
+    findings.push(portableFinding('error', 'portable.schema-guide.llm-companion.schema-mismatch', 'Schema-specific LLM companion does not match the requested schema.', {
+      requestedSchemaId: schemaId,
+      companionSchemaId: declaredSchemaId
+    }));
+  }
+
+  const taskHints = raw.tasks?.[task] || raw[task] || {};
+  const companion = Object.freeze({
+    schema: String(raw.schema || PORTABLE_LLM_SCHEMA_COMPANION_SCHEMA_ID),
+    schemaId: declaredSchemaId || schemaId,
+    task,
+    available: true,
+    source: direct ? 'direct-request' : fromCollection ? 'supplied-collection' : materialResult.companion ? 'supplied-companion-data' : 'registered-schema-module',
+    version: String(raw.version || taskHints.version || '1'),
+    purpose: String(taskHints.purpose || raw.purpose || ''),
+    authoringSteps: normalizeList(taskHints.authoringSteps || taskHints.steps || []),
+    hardRules: normalizeList(taskHints.hardRules || taskHints.emphasis || raw.hardRules || []),
+    questions: normalizeList(taskHints.questions || []),
+    commonFailures: normalizeList(taskHints.commonFailures || []),
+    prioritySections: normalizeList(taskHints.prioritySections || taskHints.readFirst || []),
+    retrievalHints: normalizeList(taskHints.retrievalHints || taskHints.retrieve || [])
+  });
+
+  if (companion.schema !== PORTABLE_LLM_SCHEMA_COMPANION_SCHEMA_ID) {
+    findings.push(portableFinding('warning', 'portable.schema-guide.llm-companion.schema-unknown', 'LLM companion uses an unrecognized companion schema id; hints were preserved but not treated as canonical rules.', {
+      schemaId,
+      companionSchema: companion.schema
+    }));
+  }
+
+  return Object.freeze({ companion, findings: Object.freeze(findings) });
+}
+
+function companionFromMaterial(input = {}, schemaId = '') {
+  const findings = [];
+  const files = [
+    ...(Array.isArray(input.files) ? input.files : []),
+    ...(Array.isArray(input.records) ? input.records.map((record) => ({ path: record.path, content: record.markdown })) : [])
+  ];
+  const exactName = `${schemaId}.llm.json`.toLowerCase();
+  const candidates = files.filter((file) => {
+    const path = String(file?.path || file?.name || '').replace(/\\/g, '/').toLowerCase();
+    return path.endsWith(exactName) || path.endsWith('.llm.json') || path.endsWith('.llm-companion.json');
+  });
+  for (const file of candidates) {
+    const content = typeof file?.content === 'string' ? file.content : typeof file?.markdown === 'string' ? file.markdown : '';
+    if (!content) continue;
+    let parsed;
+    try { parsed = JSON.parse(content); }
+    catch (error) {
+      findings.push(portableFinding('warning', 'portable.schema-guide.llm-companion.invalid-json', 'Supplied LLM companion data could not be parsed as JSON and was ignored.', {
+        ref: file.path || file.name || '',
+        detail: String(error?.message || error)
+      }));
+      continue;
+    }
+    if (String(parsed?.schemaId || '').trim() !== schemaId) continue;
+    return Object.freeze({ companion: parsed, findings: Object.freeze(findings) });
+  }
+  return Object.freeze({ companion: null, findings: Object.freeze(findings) });
+}
+
+function companionFromCollection(collection, schemaId) {
+  if (!collection) return null;
+  if (Array.isArray(collection)) return collection.find((entry) => String(entry?.schemaId || '').trim() === schemaId) || null;
+  if (collection instanceof Map) return collection.get(schemaId) || null;
+  if (typeof collection === 'object') return collection[schemaId] || null;
+  return null;
+}
+
+function emptyCompanion(task) {
+  return Object.freeze({
+    schema: PORTABLE_LLM_SCHEMA_COMPANION_SCHEMA_ID,
+    schemaId: '',
+    task,
+    available: false,
+    source: 'generic-compiler',
+    version: 'generic',
+    purpose: '',
+    authoringSteps: Object.freeze([]),
+    hardRules: Object.freeze([]),
+    questions: Object.freeze([]),
+    commonFailures: Object.freeze([]),
+    prioritySections: Object.freeze([]),
+    retrievalHints: Object.freeze([])
+  });
+}
+
+function normalizeList(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return Object.freeze([...new Set(list.map((item) => String(item || '').trim()).filter(Boolean))]);
+}

package/src/tooling/portable/schema/named.declarations.js

@@ -0,0 +1,162 @@
+function normalizeKey(value = '') {
+  return String(value || '').toLowerCase().replace(/[`*_#]/g, '').replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function cleanToken(value = '') {
+  return String(value || '').trim().replace(/^`|`$/g, '').trim();
+}
+
+function categoryItems(group = {}, names = []) {
+  const wanted = new Set(names.map((name) => String(name || '').trim()));
+  return (group.categories || []).flatMap((category) => wanted.has(String(category.name || '').trim()) ? category.items : []);
+}
+
+function unique(values = []) {
+  return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
+}
+
+function headingTargetsFromRules(rules = []) {
+  const targets = [];
+  for (const rule of rules) {
+    const text = String(rule || '');
+    for (const match of text.matchAll(/(?:Entries|entry|declarations?|names)\s+under\s+`(#{2,6}\s+[^`]+)`/gi)) targets.push(match[1].trim());
+    for (const match of text.matchAll(/unique\s+within\s+`(#{2,6}\s+[^`]+)`/gi)) targets.push(match[1].trim());
+  }
+  return unique(targets);
+}
+
+export function compileNamedDeclarationContracts(contract = {}) {
+  const out = [];
+  for (const group of contract.groups || []) {
+    const entryShape = categoryItems(group, ['Entry Shape']).map(cleanToken);
+    const requiredFields = categoryItems(group, ['Required Fields']).map(cleanToken);
+    const optionalFields = categoryItems(group, ['Optional Fields']).map(cleanToken);
+    const declarationFields = categoryItems(group, ['Declaration Fields', 'Fields']).map(cleanToken);
+    const rules = categoryItems(group, ['Rules']);
+    const namedEntry = entryShape.some((item) => normalizeKey(item) === 'first level hyphen list item' || normalizeKey(item) === 'named declaration');
+    if (!namedEntry || !(requiredFields.length || optionalFields.length || declarationFields.length)) continue;
+    const targetHeadings = headingTargetsFromRules(rules);
+    out.push(Object.freeze({
+      group: group.name,
+      entryShape: Object.freeze(entryShape),
+      requiredFields: Object.freeze(unique(requiredFields.length ? requiredFields : declarationFields)),
+      optionalFields: Object.freeze(unique(optionalFields)),
+      declarationFields: Object.freeze(unique(declarationFields)),
+      allowedLabels: Object.freeze(unique(categoryItems(group, ['Allowed Labels']).map(cleanToken))),
+      allowedShapes: Object.freeze(unique(categoryItems(group, ['Allowed Shapes']).map(cleanToken))),
+      targetHeadings: Object.freeze(targetHeadings),
+      allowLiteralNone: rules.some((rule) => /literal(?:\s+first-level)?\s+entry\s+`none`|literal\s+`none`/i.test(rule)),
+      rules: Object.freeze(rules)
+    }));
+  }
+  return Object.freeze(out);
+}
+
+export function parseNamedDeclarationSection(markdown = '', heading = '', declarationContract = {}) {
+  const section = findExactSection(markdown, heading);
+  if (!section) return Object.freeze({ heading, present: false, entries: Object.freeze([]), findings: Object.freeze([]) });
+  const entries = [];
+  const findings = [];
+  let current = null;
+  let fenced = false;
+  for (let offset = 0; offset < section.lines.length; offset += 1) {
+    const rawLine = section.lines[offset];
+    const line = section.startIndex + offset + 1;
+    if (/^\s*```/.test(rawLine)) { fenced = !fenced; continue; }
+    if (fenced || !rawLine.trim()) continue;
+    const first = rawLine.match(/^-\s+(.+?)\s*$/);
+    if (first) {
+      current = { name: first[1].trim(), fields: {}, fieldOrder: [], raw: [rawLine], startLine: line, endLine: line };
+      entries.push(current);
+      continue;
+    }
+    const nested = rawLine.match(/^\s+-\s+([^:]+):\s*(.*?)\s*$/);
+    if (nested && current) {
+      const field = nested[1].trim();
+      const value = nested[2];
+      current.raw.push(rawLine);
+      current.endLine = line;
+      if (Object.prototype.hasOwnProperty.call(current.fields, field)) {
+        findings.push(Object.freeze({ code: 'portable.contract.declaration.field.duplicate', entry: current.name, field }));
+      } else {
+        current.fields[field] = value;
+        current.fieldOrder.push(field);
+      }
+      continue;
+    }
+    if (current && /^\s+\S/.test(rawLine)) {
+      current.raw.push(rawLine);
+      current.endLine = line;
+    }
+  }
+  const frozen = entries.map((entry) => Object.freeze({
+    name: entry.name,
+    fields: Object.freeze({ ...entry.fields }),
+    fieldOrder: Object.freeze([...entry.fieldOrder]),
+    raw: Object.freeze([...entry.raw]),
+    source: Object.freeze({ line: entry.startLine, endLine: entry.endLine })
+  }));
+  return Object.freeze({ heading, present: true, entries: Object.freeze(frozen), findings: Object.freeze(findings) });
+}
+
+export function parseDeclarationsAgainstContract(markdown = '', declarationContracts = []) {
+  const groups = [];
+  for (const contract of declarationContracts || []) {
+    const sections = contract.targetHeadings.map((heading) => parseNamedDeclarationSection(markdown, heading, contract));
+    groups.push(Object.freeze({ contract, sections: Object.freeze(sections) }));
+  }
+  return Object.freeze(groups);
+}
+
+export function declarationOwnershipRanges(parsedDeclarations = []) {
+  const ranges = [];
+  for (const parsedGroup of parsedDeclarations || []) {
+    for (const section of parsedGroup.sections || []) {
+      for (const entry of section.entries || []) {
+        const line = Number(entry.source?.line || 0);
+        const endLine = Number(entry.source?.endLine || line);
+        if (!line || endLine < line) continue;
+        ranges.push(Object.freeze({
+          line,
+          endLine,
+          group: String(parsedGroup.contract?.group || ''),
+          heading: String(section.heading || ''),
+          entry: String(entry.name || '')
+        }));
+      }
+    }
+  }
+  return Object.freeze(ranges);
+}
+
+function findExactSection(markdown = '', heading = '') {
+  const target = String(heading || '').trim();
+  const explicit = target.match(/^(#{1,6})\s+(.+)$/);
+  const wantedLevel = explicit ? explicit[1].length : null;
+  const wantedTitle = explicit ? explicit[2].trim() : target;
+  if (!wantedTitle) return null;
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  let fenced = false;
+  let start = -1;
+  let matchedLevel = wantedLevel;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^\s*```/.test(line)) { fenced = !fenced; continue; }
+    if (fenced) continue;
+    const match = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (!match) continue;
+    const level = match[1].length;
+    const title = match[2].trim();
+    if (start < 0 && (wantedLevel === null || level === wantedLevel) && title === wantedTitle) { start = index + 1; matchedLevel = level; continue; }
+    if (start >= 0 && level <= matchedLevel) return { lines: lines.slice(start, index), line: start + 1, endLine: index, startIndex: start, endIndex: index };
+  }
+  return start >= 0 ? { lines: lines.slice(start), line: start + 1, endLine: lines.length, startIndex: start, endIndex: lines.length } : null;
+}
+
+export function declarationTargetKey(value = '') {
+  return normalizeKey(String(value || '').replace(/^#{1,6}\s+/, ''))
+    .replace(/\broles\b/g, 'role')
+    .replace(/\bbindings\b/g, 'binding')
+    .replace(/\beffects\b/g, 'effect')
+    .replace(/\bplacements\b/g, 'placement');
+}