elementary-assertions 1.0.1

package/src/tools/cli.js

@@ -0,0 +1,158 @@
+const { runElementaryAssertions, runFromRelations } = require("../run");
+const { validateElementaryAssertions } = require("../validate");
+const { renderElementaryAssertions } = require("../render");
+const { arg, normalizeOptionalString, parseStrictBoolean, readUtf8, readUtf8WithFileSource, writeUtf8 } = require("./io");
+
+function loadYaml() {
+  try {
+    return require("js-yaml");
+  } catch (err) {
+    throw new Error("Unable to load js-yaml. Install dependencies before using CLI file commands.");
+  }
+}
+
+function usage() {
+  return [
+    "Usage:",
+    "  elementary-assertions run --text <string> | --in <path> | --relations <path> [--out <path>] [--timeout-ms <ms>] [--wti-endpoint <url>] [--wti-timeout-ms <ms]",
+    "  elementary-assertions validate --in <path>",
+    "  elementary-assertions render --in <path> [--out <path>] --format <txt|md> --layout <compact|readable|table|meaning>",
+  ].join("\n");
+}
+
+const DEV_DIAGNOSTIC_FLAGS = [
+  "--diagnose-wiki-upstream",
+  "--diagnose-wti-wiring",
+  "--diagnose-coverage-audit",
+];
+
+function enforceDevFlagPolicy(args) {
+  const hasDev = args.includes("--dev");
+  const usedDiagnostics = DEV_DIAGNOSTIC_FLAGS.filter((f) => args.includes(f));
+  if (usedDiagnostics.length === 0) return;
+  if (!hasDev) {
+    throw new Error(`Diagnostic flags require --dev: ${usedDiagnostics.join(", ")}`);
+  }
+  throw new Error(`Diagnostic flags are developer-only and not available in the public CLI: ${usedDiagnostics.join(", ")}`);
+}
+
+function parseRunInput(args) {
+  const text = arg(args, "--text");
+  const inPath = arg(args, "--in");
+  const relationsPath = arg(args, "--relations");
+  const hasText = typeof text === "string";
+  const hasIn = typeof inPath === "string";
+  const hasRelations = typeof relationsPath === "string";
+  const inputCount = Number(hasText) + Number(hasIn) + Number(hasRelations);
+  if (inputCount > 1) throw new Error("Exactly one of --text, --in, or --relations is required; multiple provided.");
+  if (inputCount < 1) throw new Error("Exactly one of --text, --in, or --relations is required; none provided.");
+  return { text, inPath, relationsPath };
+}
+
+async function runCommand(args) {
+  const { text, inPath, relationsPath } = parseRunInput(args);
+  const outPath = arg(args, "--out");
+  const timeoutMs = Number(arg(args, "--timeout-ms") || 0) || undefined;
+  const wtiTimeoutMs = Number(arg(args, "--wti-timeout-ms") || 0) || undefined;
+  const endpoint = normalizeOptionalString(arg(args, "--wti-endpoint") || process.env.WIKIPEDIA_TITLE_INDEX_ENDPOINT || "");
+
+  let doc;
+  if (typeof relationsPath === "string") {
+    const yaml = loadYaml();
+    const { text: raw, sourceInput } = readUtf8WithFileSource(relationsPath, "relations input file", "seed.relations.yaml");
+    const relationsDoc = yaml.load(raw);
+    doc = runFromRelations(relationsDoc, {
+      wtiEndpoint: endpoint,
+      sourceInputs: [sourceInput],
+      suppressDefaultRelationsSource: true,
+    });
+  } else if (typeof text === "string") {
+    doc = await runElementaryAssertions(text, {
+      services: { "wikipedia-title-index": { endpoint } },
+      timeoutMs,
+      wtiTimeoutMs,
+    });
+  } else {
+    const { text: source, sourceInput } = readUtf8WithFileSource(inPath, "input file", "seed.txt");
+    doc = await runElementaryAssertions(source, {
+      services: { "wikipedia-title-index": { endpoint } },
+      timeoutMs,
+      wtiTimeoutMs,
+      sourceInputs: [sourceInput],
+    });
+  }
+
+  const yaml = loadYaml();
+  const out = yaml.dump(doc, { lineWidth: -1 });
+  if (outPath) writeUtf8(outPath, out);
+  else process.stdout.write(out);
+}
+
+function validateCommand(args) {
+  const inPath = arg(args, "--in");
+  if (!inPath) throw new Error("validate requires --in <path>");
+  const yaml = loadYaml();
+  const raw = readUtf8(inPath, "input file");
+  const doc = yaml.load(raw);
+  validateElementaryAssertions(doc);
+  process.stdout.write("ok\n");
+}
+
+function renderCommand(args) {
+  const inPath = arg(args, "--in");
+  if (!inPath) throw new Error("render requires --in <path>");
+  const yaml = loadYaml();
+
+  const outPath = arg(args, "--out");
+  const format = arg(args, "--format") || "txt";
+  const layout = arg(args, "--layout") || "compact";
+
+  const raw = readUtf8(inPath, "input file");
+  const doc = yaml.load(raw);
+
+  const options = {
+    format,
+    layout,
+    segments: parseStrictBoolean(arg(args, "--segments") || "true", "--segments"),
+    mentions: parseStrictBoolean(arg(args, "--mentions") || "true", "--mentions"),
+    coverage: parseStrictBoolean(arg(args, "--coverage") || "true", "--coverage"),
+    debugIds: parseStrictBoolean(arg(args, "--debug-ids") || "false", "--debug-ids"),
+    normalizeDeterminers: parseStrictBoolean(arg(args, "--normalize-determiners") || "true", "--normalize-determiners"),
+    renderUncoveredDelta: parseStrictBoolean(arg(args, "--render-uncovered-delta") || "false", "--render-uncovered-delta"),
+  };
+
+  const rendered = renderElementaryAssertions(doc, options);
+  if (outPath) writeUtf8(outPath, rendered);
+  else process.stdout.write(rendered);
+}
+
+async function runCli(argv = process.argv.slice(2)) {
+  const [cmd, ...args] = argv;
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+
+  if (cmd === "run") {
+    enforceDevFlagPolicy(args);
+    await runCommand(args);
+    return;
+  }
+  if (cmd === "validate") {
+    enforceDevFlagPolicy(args);
+    validateCommand(args);
+    return;
+  }
+  if (cmd === "render") {
+    enforceDevFlagPolicy(args);
+    renderCommand(args);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${cmd}`);
+}
+
+module.exports = {
+  runCli,
+  usage,
+};

package/src/tools/index.js

@@ -0,0 +1,6 @@
+const { runCli, usage } = require("./cli");
+
+module.exports = {
+  runCli,
+  usage,
+};

package/src/tools/io.js

@@ -0,0 +1,55 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { normalizeOptionalString } = require("../core/strings");
+const { sha256Hex } = require("../core/determinism");
+
+function parseStrictBoolean(raw, name) {
+  const v = String(raw || "").trim().toLowerCase();
+  if (v === "true") return true;
+  if (v === "false") return false;
+  throw new Error(`Invalid value for ${name}: expected true|false.`);
+}
+
+function readUtf8(filePath, label) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch (err) {
+    throw new Error(`Error reading ${label}: ${err && err.message ? err.message : String(err)}`);
+  }
+}
+
+function readUtf8WithFileSource(filePath, label, artifact) {
+  const text = readUtf8(filePath, label);
+  const stat = fs.statSync(filePath);
+  return {
+    text,
+    sourceInput: {
+      artifact,
+      digest: sha256Hex(text),
+      origin: {
+        kind: "file",
+        path: path.resolve(filePath),
+        mtime_ms: Math.max(0, Math.trunc(stat.mtimeMs)),
+      },
+    },
+  };
+}
+
+function writeUtf8(filePath, text) {
+  fs.writeFileSync(filePath, text, "utf8");
+}
+
+function arg(args, name) {
+  const i = args.indexOf(name);
+  if (i < 0 || i + 1 >= args.length) return null;
+  return args[i + 1];
+}
+
+module.exports = {
+  normalizeOptionalString,
+  parseStrictBoolean,
+  readUtf8,
+  readUtf8WithFileSource,
+  writeUtf8,
+  arg,
+};

package/src/validate/ajv.js

@@ -0,0 +1,20 @@
+const Ajv2020 = require("ajv/dist/2020");
+const addFormats = require("ajv-formats");
+const schema = require("../schema/seed.elementary-assertions.schema.json");
+
+let cachedValidate = null;
+
+function getSchemaValidator() {
+  if (cachedValidate) return cachedValidate;
+  const ajv = new Ajv2020({
+    allErrors: true,
+    strict: false,
+  });
+  addFormats(ajv);
+  cachedValidate = ajv.compile(schema);
+  return cachedValidate;
+}
+
+module.exports = {
+  getSchemaValidator,
+};

package/src/validate/coverage.js

@@ -0,0 +1,215 @@
+const { ensureSortedStrings } = require("./determinism");
+const { failValidation } = require("./errors");
+
+function isContentPosTag(tag) {
+  if (typeof tag !== "string" || tag.length === 0) 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 buildExpectedCoveragePrimarySet(doc) {
+  const tokenById = new Map((doc.tokens || []).map((token) => [token.id, token]));
+  const expected = new Set();
+  for (const mention of doc.mentions || []) {
+    if (!mention || mention.is_primary !== true || typeof mention.id !== "string" || mention.id.length === 0) continue;
+    const headToken = tokenById.get(mention.head_token_id);
+    if (!headToken) continue;
+    const tag = headToken.pos && typeof headToken.pos.tag === "string" ? headToken.pos.tag : "";
+    if (!isContentPosTag(tag)) continue;
+    if (isPunctuationSurface(headToken.surface)) continue;
+    expected.add(mention.id);
+  }
+  return expected;
+}
+
+function validateCoverage(doc, mentionById, options = {}) {
+  const coverage = doc.coverage || {};
+  const primary = Array.isArray(coverage.primary_mention_ids) ? coverage.primary_mention_ids : [];
+  const covered = Array.isArray(coverage.covered_primary_mention_ids) ? coverage.covered_primary_mention_ids : [];
+  const uncovered = Array.isArray(coverage.uncovered_primary_mention_ids) ? coverage.uncovered_primary_mention_ids : [];
+  const unresolved = Array.isArray(coverage.unresolved) ? coverage.unresolved : [];
+  const tokenById = new Map((doc.tokens || []).map((token) => [token && token.id, token]));
+
+  ensureSortedStrings(primary, "coverage.primary_mention_ids must be sorted for determinism.");
+  ensureSortedStrings(covered, "coverage.covered_primary_mention_ids must be sorted for determinism.");
+  ensureSortedStrings(uncovered, "coverage.uncovered_primary_mention_ids must be sorted for determinism.");
+
+  const primarySet = new Set(primary);
+  const coveredSet = new Set(covered);
+  const uncoveredSet = new Set(uncovered);
+
+  for (const id of coveredSet) {
+    if (!primarySet.has(id)) {
+      failValidation("EA_VALIDATE_COVERAGE_NON_PRIMARY_COVERED", `Integrity error: coverage.covered_primary_mention_ids contains non-primary mention ${id}.`);
+    }
+  }
+  for (const id of uncoveredSet) {
+    if (!primarySet.has(id)) {
+      failValidation("EA_VALIDATE_COVERAGE_NON_PRIMARY_UNCOVERED", `Integrity error: coverage.uncovered_primary_mention_ids contains non-primary mention ${id}.`);
+    }
+  }
+  for (const id of primarySet) {
+    const isCovered = coveredSet.has(id);
+    const isUncovered = uncoveredSet.has(id);
+    if (isCovered === isUncovered) {
+      failValidation("EA_VALIDATE_COVERAGE_PARTITION", `Integrity error: primary mention ${id} must appear in exactly one of covered or uncovered.`);
+    }
+  }
+
+  const unresolvedMentionIds = [];
+  for (const item of unresolved) {
+    if (!item || typeof item.mention_id !== "string" || !mentionById.has(item.mention_id)) {
+      failValidation("EA_VALIDATE_COVERAGE_UNKNOWN_UNRESOLVED_MENTION", "Integrity error: coverage.unresolved references unknown mention.");
+    }
+    unresolvedMentionIds.push(item.mention_id);
+  }
+  if (new Set(unresolvedMentionIds).size !== unresolvedMentionIds.length) {
+    failValidation("EA_VALIDATE_COVERAGE_DUPLICATE_UNRESOLVED", "Integrity error: coverage.unresolved contains duplicate mention_id entries.");
+  }
+  if (unresolvedMentionIds.length !== uncoveredSet.size) {
+    failValidation("EA_VALIDATE_COVERAGE_UNRESOLVED_LENGTH", "Integrity error: coverage.unresolved length must match uncovered_primary_mention_ids length.");
+  }
+  for (const mentionId of unresolvedMentionIds) {
+    if (!uncoveredSet.has(mentionId)) {
+      failValidation("EA_VALIDATE_COVERAGE_UNRESOLVED_MEMBERSHIP", `Integrity error: coverage.unresolved mention ${mentionId} must be in uncovered_primary_mention_ids.`);
+    }
+  }
+
+  if (options && options.strict) {
+    for (const item of unresolved) {
+      const mentionId = String((item && item.mention_id) || "");
+      const unresolvedSegmentId = String((item && item.segment_id) || "");
+      const unresolvedMention = mentionById.get(mentionId);
+      if (unresolvedMention && unresolvedMention.segment_id !== unresolvedSegmentId) {
+        failValidation(
+          "EA_VALIDATE_STRICT_UNRESOLVED_SEGMENT_MISMATCH",
+          "Strict validation error: coverage.unresolved[*].segment_id must match referenced mention/token segments."
+        );
+      }
+      const mentionIds = Array.isArray(item && item.mention_ids) ? item.mention_ids : null;
+      if (!Array.isArray(mentionIds)) {
+        failValidation(
+          "EA_VALIDATE_STRICT_UNRESOLVED_MENTION_IDS",
+          "Strict validation error: coverage.unresolved[*].mention_ids must be an array."
+        );
+      }
+      const mentionIdSet = new Set();
+      let prevMentionRef = null;
+      for (const ref of mentionIds) {
+        if (typeof ref !== "string" || ref.length === 0) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_MENTION_IDS",
+            "Strict validation error: coverage.unresolved[*].mention_ids must contain non-empty string ids."
+          );
+        }
+        if (prevMentionRef !== null && prevMentionRef.localeCompare(ref) > 0) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_MENTION_IDS",
+            "Strict validation error: coverage.unresolved[*].mention_ids must be sorted."
+          );
+        }
+        if (mentionIdSet.has(ref)) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_MENTION_IDS",
+            "Strict validation error: coverage.unresolved[*].mention_ids must be unique."
+          );
+        }
+        const mention = mentionById.get(ref);
+        if (!mention) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_MENTION_REFERENCE",
+            "Strict validation error: coverage.unresolved[*].mention_ids must reference existing mentions."
+          );
+        }
+        if (mention.segment_id !== unresolvedSegmentId) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_SEGMENT_MISMATCH",
+            "Strict validation error: coverage.unresolved[*].segment_id must match referenced mention/token segments."
+          );
+        }
+        mentionIdSet.add(ref);
+        prevMentionRef = ref;
+      }
+      if (mentionId && !mentionIdSet.has(mentionId)) {
+        failValidation(
+          "EA_VALIDATE_STRICT_UNRESOLVED_MENTION_IDS",
+          "Strict validation error: coverage.unresolved[*].mention_ids must include mention_id."
+        );
+      }
+
+      const evidence = item && item.evidence && typeof item.evidence === "object" ? item.evidence : {};
+      const tokenIds = Array.isArray(evidence.token_ids) ? evidence.token_ids : [];
+      let prevTokenId = null;
+      for (const tokenId of tokenIds) {
+        if (typeof tokenId !== "string" || tokenId.length === 0) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_EVIDENCE_TOKEN_IDS",
+            "Strict validation error: coverage.unresolved[*].evidence.token_ids must contain non-empty string token ids."
+          );
+        }
+        const token = tokenById.get(tokenId);
+        if (!token) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_EVIDENCE_TOKEN_REFERENCE",
+            "Strict validation error: coverage.unresolved[*].evidence.token_ids must reference existing tokens."
+          );
+        }
+        if (token.segment_id !== unresolvedSegmentId) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_SEGMENT_MISMATCH",
+            "Strict validation error: coverage.unresolved[*].segment_id must match referenced mention/token segments."
+          );
+        }
+        if (prevTokenId !== null && prevTokenId.localeCompare(tokenId) > 0) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_EVIDENCE_TOKEN_IDS",
+            "Strict validation error: coverage.unresolved[*].evidence.token_ids must be sorted."
+          );
+        }
+        prevTokenId = tokenId;
+      }
+
+      const upstreamRelationIds = Array.isArray(evidence.upstream_relation_ids) ? evidence.upstream_relation_ids : [];
+      let prevUpstreamId = null;
+      for (const relationId of upstreamRelationIds) {
+        if (typeof relationId !== "string" || relationId.length === 0) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_UPSTREAM_RELATION_IDS",
+            "Strict validation error: coverage.unresolved[*].evidence.upstream_relation_ids must contain non-empty string ids."
+          );
+        }
+        if (prevUpstreamId !== null && prevUpstreamId.localeCompare(relationId) > 0) {
+          failValidation(
+            "EA_VALIDATE_STRICT_UNRESOLVED_UPSTREAM_RELATION_IDS",
+            "Strict validation error: coverage.unresolved[*].evidence.upstream_relation_ids must be sorted."
+          );
+        }
+        prevUpstreamId = relationId;
+      }
+    }
+
+    const expectedPrimary = buildExpectedCoveragePrimarySet(doc);
+    if (expectedPrimary.size !== primarySet.size) {
+      failValidation(
+        "EA_VALIDATE_STRICT_COVERAGE_PRIMARY_SET",
+        "Strict validation error: coverage.primary_mention_ids must equal the derived domain-primary mention set."
+      );
+    }
+    for (const mentionId of expectedPrimary) {
+      if (!primarySet.has(mentionId)) {
+        failValidation(
+          "EA_VALIDATE_STRICT_COVERAGE_PRIMARY_SET",
+          "Strict validation error: coverage.primary_mention_ids must equal the derived domain-primary mention set."
+        );
+      }
+    }
+  }
+}
+
+module.exports = {
+  validateCoverage,
+};

package/src/validate/determinism.js

@@ -0,0 +1,115 @@
+const { failValidation } = require("./errors");
+
+function isSortedStrings(arr) {
+  for (let i = 1; i < arr.length; i += 1) {
+    if (String(arr[i - 1]).localeCompare(String(arr[i])) > 0) return false;
+  }
+  return true;
+}
+
+function ensureSortedStrings(arr, message) {
+  if (!isSortedStrings(arr || [])) {
+    failValidation("EA_VALIDATE_DETERMINISM_SORT", `Integrity error: ${message}`);
+  }
+}
+
+function relationEvidenceSortKey(ev) {
+  return [
+    String((ev && ev.from_token_id) || ""),
+    String((ev && ev.to_token_id) || ""),
+    String((ev && ev.label) || ""),
+    String((ev && (ev.relation_id || ev.annotation_id)) || ""),
+    JSON.stringify(ev || {}),
+  ].join("|");
+}
+
+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 roleEntrySortKey(entry, priorityFn) {
+  const role = String((entry && entry.role) || "");
+  const mentionIds = Array.isArray(entry && entry.mention_ids) ? entry.mention_ids : [];
+  const evidence = entry && entry.evidence && typeof entry.evidence === "object" ? entry.evidence : {};
+  const relationIds = Array.isArray(evidence.relation_ids) ? evidence.relation_ids : [];
+  const tokenIds = Array.isArray(evidence.token_ids) ? evidence.token_ids : [];
+  const priority = String(priorityFn(role)).padStart(2, "0");
+  return `${priority}|${role}|${JSON.stringify(mentionIds)}|${JSON.stringify(relationIds)}|${JSON.stringify(tokenIds)}`;
+}
+
+function validateAssertionDeterminism(assertion, assertionId) {
+  const evidence = assertion && assertion.evidence && typeof assertion.evidence === "object" ? assertion.evidence : {};
+  const evidenceTokenIds = Array.isArray(evidence.token_ids) ? evidence.token_ids : [];
+  ensureSortedStrings(evidenceTokenIds, `assertion ${assertionId} evidence.token_ids must be sorted for determinism.`);
+
+  const relationEvidence = Array.isArray(evidence.relation_evidence) ? evidence.relation_evidence : [];
+  for (let i = 1; i < relationEvidence.length; i += 1) {
+    const prev = relationEvidenceSortKey(relationEvidence[i - 1]);
+    const cur = relationEvidenceSortKey(relationEvidence[i]);
+    if (prev.localeCompare(cur) > 0) {
+      failValidation("EA_VALIDATE_DETERMINISM_RELATION_EVIDENCE_ORDER", `Integrity error: assertion ${assertionId} evidence.relation_evidence must be sorted for determinism.`);
+    }
+  }
+
+  for (const entry of assertion.arguments || []) {
+    const mids = Array.isArray(entry && entry.mention_ids) ? entry.mention_ids : [];
+    ensureSortedStrings(mids, `assertion ${assertionId} arguments[*].mention_ids must be sorted for determinism.`);
+    const entryEvidence = entry && entry.evidence && typeof entry.evidence === "object" ? entry.evidence : {};
+    ensureSortedStrings(entryEvidence.relation_ids || [], `assertion ${assertionId} arguments[*].evidence.relation_ids must be sorted for determinism.`);
+    ensureSortedStrings(entryEvidence.token_ids || [], `assertion ${assertionId} arguments[*].evidence.token_ids must be sorted for determinism.`);
+  }
+
+  for (const entry of assertion.modifiers || []) {
+    const mids = Array.isArray(entry && entry.mention_ids) ? entry.mention_ids : [];
+    ensureSortedStrings(mids, `assertion ${assertionId} modifiers[*].mention_ids must be sorted for determinism.`);
+    const entryEvidence = entry && entry.evidence && typeof entry.evidence === "object" ? entry.evidence : {};
+    ensureSortedStrings(entryEvidence.relation_ids || [], `assertion ${assertionId} modifiers[*].evidence.relation_ids must be sorted for determinism.`);
+    ensureSortedStrings(entryEvidence.token_ids || [], `assertion ${assertionId} modifiers[*].evidence.token_ids must be sorted for determinism.`);
+  }
+
+  for (let i = 1; i < assertion.arguments.length; i += 1) {
+    const prev = roleEntrySortKey(assertion.arguments[i - 1], argumentRolePriority);
+    const cur = roleEntrySortKey(assertion.arguments[i], argumentRolePriority);
+    if (prev.localeCompare(cur) > 0) {
+      failValidation("EA_VALIDATE_DETERMINISM_ARGUMENT_ORDER", `Integrity error: assertion ${assertionId} arguments must be sorted for determinism.`);
+    }
+  }
+  for (let i = 1; i < assertion.modifiers.length; i += 1) {
+    const prev = roleEntrySortKey(assertion.modifiers[i - 1], modifierRolePriority);
+    const cur = roleEntrySortKey(assertion.modifiers[i], modifierRolePriority);
+    if (prev.localeCompare(cur) > 0) {
+      failValidation("EA_VALIDATE_DETERMINISM_MODIFIER_ORDER", `Integrity error: assertion ${assertionId} modifiers must be sorted for determinism.`);
+    }
+  }
+
+  for (const op of assertion.operators || []) {
+    const opEvidence = Array.isArray(op && op.evidence) ? op.evidence : [];
+    for (let i = 1; i < opEvidence.length; i += 1) {
+      const prev = relationEvidenceSortKey(opEvidence[i - 1]);
+      const cur = relationEvidenceSortKey(opEvidence[i]);
+      if (prev.localeCompare(cur) > 0) {
+        failValidation("EA_VALIDATE_DETERMINISM_OPERATOR_EVIDENCE_ORDER", `Integrity error: assertion ${assertionId} operators[*].evidence must be sorted for determinism.`);
+      }
+    }
+  }
+}
+
+module.exports = {
+  ensureSortedStrings,
+  relationEvidenceSortKey,
+  validateAssertionDeterminism,
+};