elementary-assertions 1.0.1

package/src/core/output.js

@@ -0,0 +1,296 @@
+const { normalizeIds } = require("./determinism");
+const { normalizeWikiSurface } = require("./mentions");
+const { getTokenWikipediaEvidence, getTokenMetadataProjection } = require("./tokens");
+
+function mentionSurfaceText(mention, tokenById, canonicalText) {
+  if (!mention) return "";
+  if (mention.span && typeof mention.span.start === "number" && typeof mention.span.end === "number") {
+    return String(canonicalText || "").slice(mention.span.start, mention.span.end);
+  }
+  const tokens = (mention.token_ids || []).map((id) => tokenById.get(id)).filter(Boolean).sort((a, b) => a.i - b.i);
+  return tokens.map((t) => t.surface).join(" ");
+}
+
+function mergeWikiTitlesInto(target, evidence) {
+  if (!target || !evidence || typeof evidence !== "object") return;
+  const exactTitles = Array.isArray(evidence.exact_titles) ? evidence.exact_titles : [];
+  const prefixTitles = Array.isArray(evidence.prefix_titles) ? evidence.prefix_titles : [];
+  for (const title of exactTitles) {
+    if (typeof title !== "string") continue;
+    if (!target._exactSeen.has(title)) {
+      target._exactSeen.add(title);
+      target.exact_titles.push(title);
+    }
+  }
+  for (const title of prefixTitles) {
+    if (typeof title !== "string") continue;
+    if (!target._prefixSeen.has(title)) {
+      target._prefixSeen.add(title);
+      target.prefix_titles.push(title);
+    }
+  }
+}
+
+function buildWikiTitleEvidenceFromUpstream({ mentions, assertions, tokenById, canonicalText }) {
+  const mentionById = new Map((mentions || []).map((m) => [m.id, m]));
+  const primaryMentionIds = (mentions || []).filter((m) => m && m.is_primary).map((m) => m.id);
+  const predicateMentionIds = (assertions || []).map((a) => a && a.predicate && a.predicate.mention_id).filter(Boolean);
+  const targetMentionIds = normalizeIds(primaryMentionIds.concat(predicateMentionIds));
+
+  const byMention = [];
+  for (const mentionId of targetMentionIds) {
+    const mention = mentionById.get(mentionId);
+    if (!mention) continue;
+    const aggregate = {
+      exact_titles: [],
+      prefix_titles: [],
+      _exactSeen: new Set(),
+      _prefixSeen: new Set(),
+    };
+    const lexiconEvidence =
+      mention.provenance &&
+      mention.provenance.lexicon_evidence &&
+      typeof mention.provenance.lexicon_evidence === "object"
+        ? mention.provenance.lexicon_evidence
+        : null;
+    if (lexiconEvidence && lexiconEvidence.mwe && typeof lexiconEvidence.mwe === "object") {
+      mergeWikiTitlesInto(aggregate, lexiconEvidence.mwe);
+    }
+    const tokenEvidence = lexiconEvidence && Array.isArray(lexiconEvidence.tokens) ? lexiconEvidence.tokens : [];
+    for (const entry of tokenEvidence) {
+      if (!entry || !entry.evidence || typeof entry.evidence !== "object") continue;
+      mergeWikiTitlesInto(aggregate, entry.evidence);
+    }
+    const surface = mentionSurfaceText(mention, tokenById, canonicalText);
+    byMention.push({
+      mention_id: mentionId,
+      normalized_surface: normalizeWikiSurface(surface),
+      exact_titles: aggregate.exact_titles,
+      prefix_titles: aggregate.prefix_titles,
+    });
+  }
+  byMention.sort((a, b) => a.mention_id.localeCompare(b.mention_id));
+
+  const byAssertion = [];
+  const byMentionMap = new Map(byMention.map((x) => [x.mention_id, x]));
+  for (const a of assertions || []) {
+    if (!a || typeof a.id !== "string") continue;
+    const m = byMentionMap.get(a.predicate && a.predicate.mention_id);
+    if (!m) continue;
+    byAssertion.push({
+      assertion_id: a.id,
+      predicate_mention_id: a.predicate.mention_id,
+      exact_titles: Array.isArray(m.exact_titles) ? m.exact_titles : [],
+      prefix_titles: Array.isArray(m.prefix_titles) ? m.prefix_titles : [],
+    });
+  }
+  byAssertion.sort((a, b) => a.assertion_id.localeCompare(b.assertion_id));
+
+  return {
+    normalization: {
+      unicode_form: "NFKC",
+      punctuation_map: { apostrophes: "['\\u2018\\u2019\\u02bc]->'", dashes: "[\\u2010-\\u2015]->-" },
+      whitespace: "collapse_spaces_trim",
+      casefold: "toLowerCase",
+    },
+    mention_matches: byMention,
+    assertion_predicate_matches: byAssertion,
+  };
+}
+
+function isContentPosTag(tag) {
+  if (!tag || typeof tag !== "string") return false;
+  return /^(NN|NNS|NNP|NNPS|VB|VBD|VBG|VBN|VBP|VBZ|JJ|JJR|JJS|RB|RBR|RBS|CD|PRP|PRP\$|FW|UH)$/.test(tag);
+}
+
+function isPunctuationSurface(surface) {
+  if (typeof surface !== "string" || surface.length === 0) return false;
+  return /^[\p{P}\p{S}]+$/u.test(surface);
+}
+
+function buildCoverageDomainMentionIds(mentions, tokenById) {
+  const ids = [];
+  for (const m of mentions || []) {
+    if (!m.is_primary) continue;
+    const headTok = tokenById.get(m.head_token_id);
+    if (!headTok) continue;
+    const tag = headTok.pos && typeof headTok.pos.tag === "string" ? headTok.pos.tag : "";
+    if (!isContentPosTag(tag)) continue;
+    if (isPunctuationSurface(headTok.surface)) continue;
+    ids.push(m.id);
+  }
+  return normalizeIds(ids);
+}
+
+function buildOutput({
+  schemaVersion,
+  relationsSeed,
+  mentions,
+  assertions,
+  coveredMentions,
+  unresolved,
+  sourceInputs,
+  pipelineTrace,
+  acceptedAnnotations,
+  diagnostics,
+  projectedBuild,
+  wikiTitleEvidence,
+}) {
+  const tokenById = new Map((relationsSeed.tokens || []).map((t) => [t.id, t]));
+  const coverageDomain = new Set(buildCoverageDomainMentionIds(mentions, tokenById));
+  const primary = normalizeIds(Array.from(coverageDomain));
+  const covered = normalizeIds(Array.from(coveredMentions || []).filter((id) => coverageDomain.has(id)));
+  const uncovered = primary.filter((id) => !(coveredMentions || new Set()).has(id));
+
+  const normalizedSegments = (relationsSeed.segments || []).map((s) => ({
+    id: s.id,
+    span: { start: s.span.start, end: s.span.end },
+    token_range: {
+      start: s.token_range && typeof s.token_range.start === "number" ? s.token_range.start : 0,
+      end: s.token_range && typeof s.token_range.end === "number" ? s.token_range.end : 0,
+    },
+  }));
+
+  const normalizedTokens = (relationsSeed.tokens || []).map((t) => {
+    const wikiEvidence = getTokenWikipediaEvidence(t);
+    const tokenMeta = getTokenMetadataProjection(t);
+    return {
+      id: t.id,
+      i: t.i,
+      segment_id: t.segment_id,
+      span: { start: t.span.start, end: t.span.end },
+      surface: t.surface,
+      ...(t.pos && typeof t.pos.tag === "string"
+        ? { pos: { tag: t.pos.tag, ...(typeof t.pos.coarse === "string" ? { coarse: t.pos.coarse } : {}) } }
+        : {}),
+      ...tokenMeta,
+      ...(wikiEvidence ? { lexicon: { wikipedia_title_index: wikiEvidence } } : {}),
+    };
+  });
+
+  const out = {
+    seed_id: relationsSeed.seed_id,
+    stage: "elementary_assertions",
+    index_basis: { text_field: "canonical_text", span_unit: "utf16_code_units" },
+    canonical_text: relationsSeed.canonical_text,
+    segments: normalizedSegments,
+    tokens: normalizedTokens,
+    mentions,
+    assertions,
+    relation_projection: {
+      all_relations: projectedBuild.all || [],
+      projected_relations: (projectedBuild.projected || []).map((r) => ({
+        relation_id: r.relation_id,
+        label: r.label,
+        segment_id: r.segment_id,
+        head_token_id: r.head_token_id,
+        dep_token_id: r.dep_token_id,
+        head_mention_id: r.head_mention_id,
+        dep_mention_id: r.dep_mention_id,
+      })),
+      dropped_relations: projectedBuild.dropped || [],
+    },
+    accepted_annotations: acceptedAnnotations,
+    wiki_title_evidence: wikiTitleEvidence,
+    diagnostics,
+    coverage: {
+      primary_mention_ids: primary,
+      covered_primary_mention_ids: covered,
+      uncovered_primary_mention_ids: uncovered,
+      unresolved,
+    },
+    sources: {
+      inputs: sourceInputs,
+      pipeline: pipelineTrace,
+    },
+  };
+  if (typeof schemaVersion === "string" && schemaVersion.length > 0) {
+    out.schema_version = schemaVersion;
+  }
+  return out;
+}
+
+function buildCoverageAudit(output) {
+  const mentions = Array.isArray(output && output.mentions) ? output.mentions : [];
+  const coverage = ((output || {}).coverage) || {};
+  const primaryIds = normalizeIds(Array.isArray(coverage.primary_mention_ids) ? coverage.primary_mention_ids : []);
+  const coveredIds = new Set(normalizeIds(Array.isArray(coverage.covered_primary_mention_ids) ? coverage.covered_primary_mention_ids : []));
+  const assertions = Array.isArray(output && output.assertions) ? output.assertions : [];
+  const unresolved = Array.isArray(coverage.unresolved) ? coverage.unresolved : [];
+  const suppressed = Array.isArray((((output || {}).diagnostics) || {}).suppressed_assertions)
+    ? output.diagnostics.suppressed_assertions
+    : [];
+
+  const unresolvedByMention = new Map();
+  for (const u of unresolved) {
+    if (!u || typeof u.mention_id !== "string") continue;
+    unresolvedByMention.set(u.mention_id, String(u.reason || "other"));
+  }
+
+  const coveredBy = new Map();
+  function addMechanism(mid, mechanism) {
+    if (!mid || !mechanism) return;
+    if (!coveredBy.has(mid)) coveredBy.set(mid, new Set());
+    coveredBy.get(mid).add(mechanism);
+  }
+
+  for (const a of assertions) {
+    if (!a || typeof a !== "object") continue;
+    if (Object.prototype.hasOwnProperty.call(a, "slots")) {
+      throw new Error("Invalid input: legacy assertions[*].slots is not supported.");
+    }
+    const argEntries = Array.isArray(a.arguments) ? a.arguments : [];
+    const modEntries = Array.isArray(a.modifiers) ? a.modifiers : [];
+    for (const entry of argEntries) for (const mid of entry.mention_ids || []) addMechanism(mid, "slot");
+    for (const entry of modEntries) for (const mid of entry.mention_ids || []) addMechanism(mid, "slot");
+
+    for (const op of a.operators || []) {
+      const tid = String((op && op.token_id) || "");
+      if (!tid) continue;
+      for (const m of mentions) {
+        if (!m || !primaryIds.includes(m.id)) continue;
+        if ((m.token_ids || []).includes(tid)) addMechanism(m.id, "operator");
+      }
+    }
+
+    const evTokenIds = normalizeIds((((a || {}).evidence) || {}).token_ids || []);
+    if (evTokenIds.length > 0) {
+      for (const m of mentions) {
+        if (!m || !primaryIds.includes(m.id)) continue;
+        const hasEvidence = (m.token_ids || []).some((tid) => evTokenIds.includes(tid));
+        if (hasEvidence) addMechanism(m.id, "evidence");
+      }
+    }
+  }
+
+  for (const s of suppressed) {
+    for (const mid of s.transferred_mention_ids || []) addMechanism(mid, "transfer");
+  }
+
+  const primaryMentions = mentions
+    .filter((m) => m && primaryIds.includes(m.id))
+    .slice()
+    .sort((a, b) => String(a.id || "").localeCompare(String(b.id || "")));
+
+  return primaryMentions.map((m) => {
+    const mechanisms = normalizeIds(Array.from(coveredBy.get(m.id) || []));
+    const covered = coveredIds.has(m.id);
+    return {
+      mention_id: m.id,
+      covered,
+      covered_by: covered ? mechanisms : [],
+      uncovered_reason: covered ? null : (unresolvedByMention.get(m.id) || "other"),
+    };
+  });
+}
+
+module.exports = {
+  mentionSurfaceText,
+  mergeWikiTitlesInto,
+  buildWikiTitleEvidenceFromUpstream,
+  isContentPosTag,
+  isPunctuationSurface,
+  buildCoverageDomainMentionIds,
+  buildOutput,
+  buildCoverageAudit,
+};

package/src/core/projection.js

@@ -0,0 +1,192 @@
+const { deepCloneJson, sha256Hex, normalizeIds } = require('./determinism');
+const { chooseBestMentionForToken, compareMentionProjectionPriority, mentionHasLexiconEvidence } = require('./mentions');
+const { annotationHasSource, collectStep11Relations } = require('./upstream');
+const { getTokenWikipediaEvidence, buildTokenWikiById, getTokenMetadataProjection } = require('./tokens');
+const { getMweHeadEvidence, getMweLexiconEvidence } = require('./mention-materialization');
+const { toAnnotationSummary, buildAcceptedAnnotationsInventory } = require('./accepted-annotations');
+const { buildChunkHeadMaps, buildDependencyObservationMaps, posFallbackHead, resolveMentionHead } = require('./mention-head-resolution');
+const { buildMentionLexiconEvidence, buildAssertionWikiSignals } = require('./mention-evidence');
+const { buildMentions } = require('./mention-builder');
+
+function buildProjectedRelations(relations, tokenToMention, tokenToAllMentions, mentionById, tokenById) {
+  function mentionKindRank(kind) {
+    if (kind === 'token') return 0;
+    if (kind === 'mwe') return 1;
+    if (kind === 'chunk') return 2;
+    return 9;
+  }
+
+  function chooseMentionId(candidates, preferPrimary, excludeId) {
+    const ids = (candidates || [])
+      .filter((id) => typeof id === 'string' && mentionById.has(id) && id !== excludeId)
+      .slice();
+    ids.sort((a, b) => {
+      const ma = mentionById.get(a);
+      const mb = mentionById.get(b);
+      const pa = ma && ma.is_primary ? 0 : 1;
+      const pb = mb && mb.is_primary ? 0 : 1;
+      if (preferPrimary && pa !== pb) return pa - pb;
+      if (!preferPrimary && pa !== pb) return pb - pa;
+      const ka = mentionKindRank(ma ? ma.kind : '');
+      const kb = mentionKindRank(mb ? mb.kind : '');
+      if (ka !== kb) return ka - kb;
+      if (ma && mb && ma.segment_id !== mb.segment_id) return ma.segment_id.localeCompare(mb.segment_id);
+      if (ma && mb && ma.span.start !== mb.span.start) return ma.span.start - mb.span.start;
+      if (ma && mb && ma.span.end !== mb.span.end) return ma.span.end - mb.span.end;
+      return a.localeCompare(b);
+    });
+    return ids.length > 0 ? ids[0] : null;
+  }
+
+  const out = [];
+  const unresolved = [];
+  const dropped = [];
+  const all = [];
+  for (const r of relations) {
+    const headMentionIds = tokenToAllMentions.get(r.head_token_id) || [];
+    const depMentionIds = tokenToAllMentions.get(r.dep_token_id) || [];
+    const headTok = tokenById.get(r.head_token_id);
+    const depTok = tokenById.get(r.dep_token_id);
+    const segmentId = headTok.segment_id;
+
+    let headMentionId = tokenToMention.get(r.head_token_id);
+    let depMentionId = tokenToMention.get(r.dep_token_id);
+
+    if (!headMentionId) {
+      headMentionId = chooseMentionId(headMentionIds, true, null);
+    }
+    if (!depMentionId) {
+      depMentionId = chooseMentionId(depMentionIds, true, null);
+    }
+    if (headMentionId && depMentionId && headMentionId === depMentionId) {
+      const depAlt = chooseMentionId(depMentionIds, false, headMentionId);
+      if (depAlt) {
+        depMentionId = depAlt;
+      } else {
+        const headAlt = chooseMentionId(headMentionIds, false, depMentionId);
+        if (headAlt) headMentionId = headAlt;
+      }
+    }
+    all.push({
+      relation_id: r.id,
+      label: r.label,
+      segment_id: segmentId,
+      head_token_id: r.head_token_id,
+      dep_token_id: r.dep_token_id,
+      head_primary_mention_id: headMentionId || null,
+      dep_primary_mention_id: depMentionId || null,
+      head_mention_ids: headMentionIds,
+      dep_mention_ids: depMentionIds,
+    });
+    if (!depTok || depTok.segment_id !== segmentId) continue;
+    if (!headMentionId || !depMentionId) {
+      if (depMentionId) unresolved.push({ kind: 'unresolved_attachment', segment_id: segmentId, mention_id: depMentionId, reason: 'missing_primary_projection', relation: r });
+      dropped.push({
+        relation_id: r.id,
+        label: r.label,
+        segment_id: segmentId,
+        reason: 'missing_primary_projection',
+        head_token_id: r.head_token_id,
+        dep_token_id: r.dep_token_id,
+        head_primary_mention_id: headMentionId || null,
+        dep_primary_mention_id: depMentionId || null,
+      });
+      continue;
+    }
+    if (headMentionId === depMentionId) {
+      dropped.push({
+        relation_id: r.id,
+        label: r.label,
+        segment_id: segmentId,
+        reason: 'self_loop_after_primary_projection',
+        head_token_id: r.head_token_id,
+        dep_token_id: r.dep_token_id,
+        head_primary_mention_id: headMentionId,
+        dep_primary_mention_id: depMentionId,
+      });
+      continue;
+    }
+    const headMention = mentionById.get(headMentionId);
+    const depMention = mentionById.get(depMentionId);
+    if (!headMention || !depMention) continue;
+    if (headMention.segment_id !== depMention.segment_id) continue;
+    out.push({
+      relation_id: r.id,
+      label: r.label,
+      head_token_id: r.head_token_id,
+      dep_token_id: r.dep_token_id,
+      head_mention_id: headMentionId,
+      dep_mention_id: depMentionId,
+      segment_id: headMention.segment_id,
+      evidence: r.evidence || {},
+    });
+  }
+  out.sort((a, b) => {
+    const ta = tokenById.get(a.head_token_id);
+    const tb = tokenById.get(b.head_token_id);
+    if (a.segment_id !== b.segment_id) return a.segment_id.localeCompare(b.segment_id);
+    if (ta.span.start !== tb.span.start) return ta.span.start - tb.span.start;
+    const da = tokenById.get(a.dep_token_id);
+    const db = tokenById.get(b.dep_token_id);
+    if (da.span.start !== db.span.start) return da.span.start - db.span.start;
+    if (a.label !== b.label) return a.label.localeCompare(b.label);
+    return a.relation_id.localeCompare(b.relation_id);
+  });
+  dropped.sort((a, b) => {
+    if (a.segment_id !== b.segment_id) return a.segment_id.localeCompare(b.segment_id);
+    if (a.head_token_id !== b.head_token_id) return a.head_token_id.localeCompare(b.head_token_id);
+    if (a.dep_token_id !== b.dep_token_id) return a.dep_token_id.localeCompare(b.dep_token_id);
+    if (a.label !== b.label) return a.label.localeCompare(b.label);
+    return (a.relation_id || '').localeCompare(b.relation_id || '');
+  });
+  all.sort((a, b) => {
+    if (a.segment_id !== b.segment_id) return a.segment_id.localeCompare(b.segment_id);
+    if (a.head_token_id !== b.head_token_id) return a.head_token_id.localeCompare(b.head_token_id);
+    if (a.dep_token_id !== b.dep_token_id) return a.dep_token_id.localeCompare(b.dep_token_id);
+    if (a.label !== b.label) return a.label.localeCompare(b.label);
+    return (a.relation_id || '').localeCompare(b.relation_id || '');
+  });
+  return { projected: out, unresolved, dropped, all };
+}
+
+function buildCoordinationGroups(projected) {
+  const edges = projected.filter((p) => p.label === 'coordination');
+  const graph = new Map();
+  for (const e of edges) {
+    if (!graph.has(e.head_mention_id)) graph.set(e.head_mention_id, new Set());
+    if (!graph.has(e.dep_mention_id)) graph.set(e.dep_mention_id, new Set());
+    graph.get(e.head_mention_id).add(e.dep_mention_id);
+    graph.get(e.dep_mention_id).add(e.head_mention_id);
+  }
+  const seen = new Set();
+  const groups = new Map();
+  for (const node of graph.keys()) {
+    if (seen.has(node)) continue;
+    const comp = [];
+    const q = [node];
+    seen.add(node);
+    while (q.length > 0) {
+      const cur = q.shift();
+      comp.push(cur);
+      for (const n of graph.get(cur) || []) {
+        if (seen.has(n)) continue;
+        seen.add(n);
+        q.push(n);
+      }
+    }
+    comp.sort((a, b) => a.localeCompare(b));
+    const gid = `cg:${sha256Hex(comp.join('|')).slice(0, 12)}`;
+    for (const m of comp) groups.set(m, gid);
+  }
+  return groups;
+}
+
+
+module.exports = {
+  annotationHasSource,
+  collectStep11Relations,
+  buildProjectedRelations,
+  buildCoordinationGroups,
+};
+
+

package/src/core/roles.js

@@ -0,0 +1,164 @@
+const { normalizeIds } = require('./determinism');
+const { isSubjectRoleLabel } = require('./mentions');
+
+function argumentRolePriority(role) {
+  const r = String(role || '');
+  if (r === 'actor') return 0;
+  if (r === 'patient') return 1;
+  if (r === 'location') return 2;
+  if (r === 'theme') return 3;
+  if (r === 'attribute') return 4;
+  if (r === 'topic') return 5;
+  return 10;
+}
+
+function modifierRolePriority(role) {
+  const r = String(role || '');
+  if (r === 'recipient') return 0;
+  if (r === 'modifier') return 1;
+  return 10;
+}
+
+function canonicalizeRoleEntries(entries, priorityFn) {
+  return (entries || [])
+    .map((entry) => ({
+      role: String((entry && entry.role) || ''),
+      mention_ids: normalizeIds(Array.isArray(entry && entry.mention_ids) ? entry.mention_ids : []),
+      evidence: {
+        relation_ids: normalizeIds(
+          Array.isArray(entry && entry.evidence && entry.evidence.relation_ids)
+            ? entry.evidence.relation_ids
+            : []
+        ),
+        token_ids: normalizeIds(
+          Array.isArray(entry && entry.evidence && entry.evidence.token_ids)
+            ? entry.evidence.token_ids
+            : []
+        ),
+      },
+    }))
+    .filter((entry) => entry.role.length > 0 && entry.mention_ids.length > 0)
+    .sort((a, b) => {
+      const pa = priorityFn(a.role);
+      const pb = priorityFn(b.role);
+      if (pa !== pb) return pa - pb;
+      if (a.role !== b.role) return a.role.localeCompare(b.role);
+      const am = JSON.stringify(a.mention_ids);
+      const bm = JSON.stringify(b.mention_ids);
+      if (am !== bm) return am.localeCompare(bm);
+      const ae = JSON.stringify(a.evidence);
+      const be = JSON.stringify(b.evidence);
+      return ae.localeCompare(be);
+    });
+}
+
+function collectEntryTokenIds(mentionIds, mentionById) {
+  const tokenIds = [];
+  for (const mentionId of mentionIds || []) {
+    const mention = mentionById.get(mentionId);
+    if (!mention) continue;
+    for (const tokenId of mention.token_ids || []) tokenIds.push(tokenId);
+  }
+  return normalizeIds(tokenIds);
+}
+
+function slotToRoleEntries(slots, mentionById) {
+  const source = slots || {};
+  const argumentsOut = [];
+  const modifiersOut = [];
+
+  const coreMappings = [
+    { slot: 'actor', role: 'actor' },
+    { slot: 'theme', role: 'theme' },
+    { slot: 'attr', role: 'attribute' },
+    { slot: 'topic', role: 'topic' },
+    { slot: 'location', role: 'location' },
+  ];
+
+  for (const mapping of coreMappings) {
+    const mentionIds = normalizeIds(Array.isArray(source[mapping.slot]) ? source[mapping.slot] : []);
+    if (mentionIds.length === 0) continue;
+    argumentsOut.push({
+      role: mapping.role,
+      mention_ids: mentionIds,
+      evidence: {
+        relation_ids: [],
+        token_ids: collectEntryTokenIds(mentionIds, mentionById),
+      },
+    });
+  }
+
+  for (const entry of Array.isArray(source.other) ? source.other : []) {
+    const role = String((entry && entry.role) || '').trim();
+    const mentionIds = normalizeIds(Array.isArray(entry && entry.mention_ids) ? entry.mention_ids : []);
+    if (!role || mentionIds.length === 0) continue;
+    modifiersOut.push({
+      role,
+      mention_ids: mentionIds,
+      evidence: {
+        relation_ids: [],
+        token_ids: collectEntryTokenIds(mentionIds, mentionById),
+      },
+    });
+  }
+
+  return {
+    arguments: canonicalizeRoleEntries(argumentsOut, argumentRolePriority),
+    modifiers: canonicalizeRoleEntries(modifiersOut, modifierRolePriority),
+  };
+}
+
+function collectAssertionMentionRefs(assertion) {
+  const out = new Set();
+  for (const entry of assertion && Array.isArray(assertion.arguments) ? assertion.arguments : []) {
+    for (const mentionId of entry.mention_ids || []) out.add(mentionId);
+  }
+  for (const entry of assertion && Array.isArray(assertion.modifiers) ? assertion.modifiers : []) {
+    for (const mentionId of entry.mention_ids || []) out.add(mentionId);
+  }
+  return out;
+}
+
+function projectRolesToSlots(assertion) {
+  const slots = { actor: [], theme: [], attr: [], topic: [], location: [], other: [] };
+  for (const entry of assertion && Array.isArray(assertion.arguments) ? assertion.arguments : []) {
+    const role = String((entry && entry.role) || '');
+    const mentionIds = normalizeIds(Array.isArray(entry && entry.mention_ids) ? entry.mention_ids : []);
+    if (mentionIds.length === 0) continue;
+    if (role === 'actor' || isSubjectRoleLabel(role)) slots.actor = normalizeIds(slots.actor.concat(mentionIds));
+    else if (role === 'theme') slots.theme = normalizeIds(slots.theme.concat(mentionIds));
+    else if (role === 'attribute') slots.attr = normalizeIds(slots.attr.concat(mentionIds));
+    else if (role === 'topic') slots.topic = normalizeIds(slots.topic.concat(mentionIds));
+    else if (role === 'location') slots.location = normalizeIds(slots.location.concat(mentionIds));
+    else slots.other.push({ role, mention_ids: mentionIds });
+  }
+  for (const entry of assertion && Array.isArray(assertion.modifiers) ? assertion.modifiers : []) {
+    const role = String((entry && entry.role) || '');
+    const mentionIds = normalizeIds(Array.isArray(entry && entry.mention_ids) ? entry.mention_ids : []);
+    if (!role || mentionIds.length === 0) continue;
+    slots.other.push({ role, mention_ids: mentionIds });
+  }
+  slots.other = slots.other
+    .map((entry) => ({ role: entry.role, mention_ids: normalizeIds(entry.mention_ids || []) }))
+    .filter((entry) => entry.mention_ids.length > 0)
+    .sort((a, b) => {
+      if (a.role !== b.role) return a.role.localeCompare(b.role);
+      return JSON.stringify(a.mention_ids).localeCompare(JSON.stringify(b.mention_ids));
+    });
+  return slots;
+}
+
+function collectMentionIdsFromRoles(assertion) {
+  return normalizeIds(Array.from(collectAssertionMentionRefs(assertion)));
+}
+
+module.exports = {
+  argumentRolePriority,
+  modifierRolePriority,
+  canonicalizeRoleEntries,
+  collectEntryTokenIds,
+  slotToRoleEntries,
+  collectAssertionMentionRefs,
+  projectRolesToSlots,
+  collectMentionIdsFromRoles,
+};

package/src/core/strings.js

@@ -0,0 +1,7 @@
+function normalizeOptionalString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+module.exports = {
+  normalizeOptionalString,
+};