@piagent/platform 1.5.5 → 1.6.0

package/packages/piagent-core/extensions/acceptance-contract-semantics.js

@@ -1,7 +1,11 @@
 import path from "node:path";
 import { acceptanceBoundaryProofGuidance } from "./acceptance-boundary-guidance.js";
 import { evidenceTopLevelArguments, executableRejectionAssertions } from "./acceptance-executable-evidence.js";
-
+import { ERROR_CONSTRUCTORS, ERROR_CONSTRUCTOR_DISPLAY_NAMES, errorMappingsProveContract,
+  hasAmbiguousErrorClassIntent, rejectionStatementErrorClass, requestedErrorClasses, requestedErrorPartitionMapping } from "./acceptance-error-classes.js";
+import { statefulTerminalRejectionEvidence } from "./acceptance-state-machine-evidence.js";
+import { boundRejectionTestEvidence, callableAssertionMode } from "./acceptance-test-binding-evidence.js";
+import { regexCanStartAfterLexicalChunks } from "./javascript-regex-evidence.js";
 const INTEGER_TARGET_STOPWORDS = new Set([
   "and", "basis", "cents", "input", "inputs", "items", "money", "number", "numbers", "or", "points", "typeerror", "value", "values"
 ]);
@@ -19,6 +23,7 @@ function erasedLexeme(value) {
 
 function stringLiteralSentinel(value) {
   if (value.length === 0) return "__pi_empty_string_literal__";
+  if (value === '"') return "__pi_double_quote_string_literal__";
   if (/^(?:\s|\\[nrtvf0])+$/u.test(value)) return "__pi_whitespace_string_literal__";
   if (["assert", "assert/strict", "node:assert", "node:assert/strict"].includes(value.trim().toLowerCase())) {
     return "__pi_node_assert_module_literal__";
@@ -30,14 +35,6 @@ function stringLiteralSentinel(value) {
   return "__pi_string_literal__";
 }
 
-function regexCanStart(source, offset) {
-  const prefix = source.slice(0, offset).replace(/\s+$/u, "");
-  if (!prefix) return true;
-  const previous = prefix.at(-1);
-  if (/[([{,:;=!?&|+*%^~<>-]/u.test(previous)) return true;
-  return /\b(?:await|case|delete|do|else|in|instanceof|new|of|return|throw|typeof|void|yield)$/u.test(prefix);
-}
-
 /**
  * Return a bounded lexical evidence view of JavaScript/TypeScript source.
  *
@@ -118,7 +115,7 @@ function lexJavaScriptEvidence(value, bindStrings = false) {
       index = end;
       continue;
     }
-    if (current === "/" && next !== "=" && regexCanStart(source, index)) {
+    if (current === "/" && next !== "=" && regexCanStartAfterLexicalChunks(output)) {
       let end = index + 1;
       let inClass = false;
       let closed = false;
@@ -160,6 +157,7 @@ export function sanitizeJavaScriptEvidence(value) {
 function uniqueStrings(values) {
   return [...new Set((Array.isArray(values) ? values : []).filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()))];
 }
+function hasReservedEvidenceIdentifier(value) { return /\b__pi_[a-z0-9_]*\b/i.test(String(value ?? "")); }
 
 function escapeRegex(value) {
   return String(value ?? "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -207,8 +205,6 @@ function nullRejectingDefaultTargets(text, sourceText = "") {
   return uniqueTargets.filter((target) => new RegExp(`(?:\\.${escapeRegex(target)}\\b|\\b${escapeRegex(target)}\\b)\\s*\\?\\?`, "i").test(source));
 }
 
-const ERROR_CONSTRUCTORS = ["typeerror", "rangeerror", "syntaxerror", "referenceerror", "urierror", "evalerror", "aggregateerror", "error"];
-
 function evidenceBalancedEnd(text, openIndex, opening = "(", closing = ")", ceiling = 8_000) {
   if (text[openIndex] !== opening) return -1;
   let depth = 0;
@@ -219,13 +215,6 @@ function evidenceBalancedEnd(text, openIndex, opening = "(", closing = ")", ceil
   return -1;
 }
 
-function requestedErrorClasses(text) {
-  const value = normalizedText(text);
-  const specific = ERROR_CONSTRUCTORS.slice(0, -1).filter((name) => new RegExp(`\\b${name}\\b`).test(value));
-  if (specific.length > 0) return specific;
-  return /\b(?:throw(?:s|ing)?|reject(?:s|ed|ion)?)\b[^.\n]{0,80}\berror\b/.test(value) ? ["error"] : [];
-}
-
 function simpleConstantValue(raw) {
   let value = String(raw ?? "").trim();
   while (value.startsWith("(") && evidenceBalancedEnd(value, 0) === value.length) value = value.slice(1, -1).trim();
@@ -423,15 +412,24 @@ function namedTargetBindings(sourceEntries, testEntries, namedTargets) {
   return namedTargets.map((target) => {
     const matches = exports.filter((item) => item.contractName === target
       && sourceCallableBindingIsStable(sourceEntries.find((entry) => entryPath(entry?.path) === item.sourcePath), item.sourceName));
-    if (matches.length !== 1) return { target, sourcePath: null, sourceName: null, testNames: [] };
+    if (matches.length !== 1) return { target, sourcePath: null, sourceName: null, testNames: [], testBindings: [] };
     const exported = matches[0];
-    const testNames = [];
+    const testBindings = [];
     for (const binding of imports.filter((item) => importResolvesTo(item, exported.sourcePath))) {
       const testName = binding.importName === "*" ? `${binding.localName}.${exported.exportName}` : binding.localName;
       if ((binding.importName === exported.exportName || binding.importName === "*")
-        && !importedBindingIsShadowed(entries.get(binding.testPath), testName)) testNames.push(testName);
+        && !importedBindingIsShadowed(entries.get(binding.testPath), testName)) {
+        testBindings.push({ testName, testPath: binding.testPath });
+      }
     }
-    return { target, sourcePath: exported.sourcePath, sourceName: exported.sourceName, testNames: uniqueStrings(testNames) };
+    const uniqueBindings = [...new Map(testBindings.map((item) => [`${item.testPath}\u0000${item.testName}`, item])).values()];
+    return {
+      target,
+      sourcePath: exported.sourcePath,
+      sourceName: exported.sourceName,
+      testNames: uniqueStrings(uniqueBindings.map((item) => item.testName)),
+      testBindings: uniqueBindings
+    };
   });
 }
 
@@ -461,25 +459,23 @@ function formalParameterNames(parameters) {
 
 function callableBodies(code) {
   const bodies = new Map();
-  const addBraced = (name, parameters, open) => {
+  const addBraced = (name, parameters, open, asynchronous = false) => {
     const end = evidenceBalancedEnd(code, open, "{", "}");
     if (end !== -1 && !bodies.has(name)) bodies.set(name, {
       body: code.slice(open + 1, end - 1),
-      parameters: formalParameterNames(parameters),
-      sourceCode: code
+      parameters: formalParameterNames(parameters), sourceCode: code, asynchronous
     });
   };
-  for (const match of code.matchAll(/\bfunction\s+([a-z_$][a-z0-9_$]*)\s*\(([^)]*)\)\s*\{/gi)) addBraced(match[1].toLowerCase(), match[2], match.index + match[0].lastIndexOf("{"));
+  for (const match of code.matchAll(/\b(?:async\s+)?function\s+([a-z_$][a-z0-9_$]*)\s*\(([^)]*)\)\s*\{/gi)) addBraced(match[1].toLowerCase(), match[2], match.index + match[0].lastIndexOf("{"), /^async\b/i.test(match[0]));
   for (const match of code.matchAll(/^\s*(?:async\s+)?([a-z_$][a-z0-9_$]*)\s*\(([^)]*)\)\s*\{/gim)) {
-    if (!["catch", "for", "if", "switch", "while", "with"].includes(match[1].toLowerCase())) addBraced(match[1].toLowerCase(), match[2], match.index + match[0].lastIndexOf("{"));
+    if (!["catch", "for", "if", "switch", "while", "with"].includes(match[1].toLowerCase())) addBraced(match[1].toLowerCase(), match[2], match.index + match[0].lastIndexOf("{"), /^\s*async\b/i.test(match[0]));
   }
   for (const match of code.matchAll(/\b(?:const|let|var)\s+([a-z_$][a-z0-9_$]*)\s*=\s*(?:async\s*)?(?:\(([^)]*)\)|([a-z_$][a-z0-9_$]*))\s*=>\s*/gi)) {
     const start = match.index + match[0].length;
-    if (code[start] === "{") addBraced(match[1].toLowerCase(), match[2] ?? match[3], start);
+    if (code[start] === "{") addBraced(match[1].toLowerCase(), match[2] ?? match[3], start, /=\s*async\b/i.test(match[0]));
     else bodies.set(match[1].toLowerCase(), {
       body: code.slice(start, [code.indexOf(";", start), code.indexOf("\n", start)].filter((item) => item >= 0).sort((a, b) => a - b)[0] ?? code.length),
-      parameters: formalParameterNames(match[2] ?? match[3]),
-      sourceCode: code
+      parameters: formalParameterNames(match[2] ?? match[3]), sourceCode: code, asynchronous: /=\s*async\b/i.test(match[0])
     });
   }
   return bodies;
@@ -624,12 +620,6 @@ function validationConditionProof(condition, names, bodies) {
   return proof;
 }
 
-function rejectionStatementProves(text, requestedErrors) {
-  return requestedErrors.length === 0
-    ? /^\s*throw\s+(?:new\s+)?[a-z_$][a-z0-9_$]*(?:\s*\(|\b)/.test(text)
-    : requestedErrors.some((name) => new RegExp(`^\\s*throw\\s+(?:new\\s+)?${escapeRegex(name)}\\s*\\(`).test(text));
-}
-
 function exactHelperCall(text) {
   let value = String(text ?? "").trim();
   if (value.startsWith("{") && evidenceBalancedEnd(value, 0, "{", "}") === value.length) {
@@ -721,8 +711,8 @@ function inputNameWrittenBefore(callable, name, offset) {
   return new RegExp(`(?:\\+\\+|--)\\s*\\b${escaped}\\b`, "i").test(prefix);
 }
 
-function conditionalRejection(callable, requestedErrors, bodies) {
-  const proof = { generic: false, partitions: new Set() };
+function conditionalRejection(callable, requestedErrors, bodies, contractText = "", contractTarget = "") {
+  const proof = { generic: false, partitions: new Set(), errorMappings: [] };
   const names = inputDerivedNames(callable);
   for (const match of callable.body.matchAll(/\bif\s*\(/g)) {
     if (sourceBraceDepthAt(callable.body, match.index) !== 0 || priorUnconditionalExit(callable.body, match.index)) continue;
@@ -737,8 +727,11 @@ function conditionalRejection(callable, requestedErrors, bodies) {
     const consequent = callable.body.slice(consequentStart, consequentEnd === -1 ? callable.body.length : consequentEnd);
     const condition = callable.body.slice(conditionOpen + 1, conditionEnd - 1);
     const liveNames = names.filter((name) => !inputNameWrittenBefore(callable, name, match.index));
-    if (rejectionStatementProves(consequent.replace(/^\s*\{/, ""), requestedErrors)) {
-      mergeValidationProof(proof, validationConditionProof(condition, liveNames, bodies));
+    const consequentError = rejectionStatementErrorClass(consequent.replace(/^\s*\{/, ""), requestedErrors);
+    if (consequentError) {
+      const validation = validationConditionProof(condition, liveNames, bodies);
+      mergeValidationProof(proof, validation);
+      for (const partition of validation.partitions) proof.errorMappings.push({ partition, errorClass: consequentError });
       continue;
     }
     const throwingHelper = exactHelperCall(consequent);
@@ -749,18 +742,25 @@ function conditionalRejection(callable, requestedErrors, bodies) {
     }
     if (!/^\s*\{?\s*return\b/.test(consequent)) continue;
     const following = callable.body.slice(consequentEnd === -1 ? callable.body.length : consequentEnd);
-    if (rejectionStatementProves(following, requestedErrors)) {
-      mergeValidationProof(proof, positiveValidationConditionProof(condition, liveNames, bodies));
+    const followingError = rejectionStatementErrorClass(following, requestedErrors);
+    if (followingError) {
+      const validation = positiveValidationConditionProof(condition, liveNames, bodies);
+      mergeValidationProof(proof, validation);
+      for (const partition of validation.partitions) proof.errorMappings.push({ partition, errorClass: followingError });
     }
   }
+  proof.generic ||= statefulTerminalRejectionEvidence(callable.body, callable.parameters, requestedErrors, contractText, contractTarget, callable.sourceCode);
   return { ...proof, names };
 }
-
-function sourceCallableProof(bodies, name, requestedErrors, visited = new Set()) {
+function sourceCallableProvesErrorMapping(bodies, name, mapping) {
+  const observed = sourceCallableProof(bodies, name, []).errorMappings ?? [];
+  return errorMappingsProveContract(observed, mapping);
+}
+function sourceCallableProof(bodies, name, requestedErrors, visited = new Set(), contractText = "", contractTarget = name) {
   if (visited.has(name) || visited.size >= 12) return { generic: false, partitions: new Set() };
   const callable = bodies.get(name);
   if (!callable) return { generic: false, partitions: new Set() };
-  const proof = conditionalRejection(callable, requestedErrors, bodies);
+  const proof = conditionalRejection(callable, requestedErrors, bodies, contractText, contractTarget);
   const nextVisited = new Set(visited).add(name);
   for (const match of callable.body.matchAll(/\b([a-z_$][a-z0-9_$]*)\s*\(/gi)) {
     const helper = match[1].toLowerCase();
@@ -770,17 +770,17 @@ function sourceCallableProof(bodies, name, requestedErrors, visited = new Set())
     const argumentsText = end === -1 ? "" : callable.body.slice(open + 1, end - 1);
     if (!proof.names.some((candidate) => !inputNameWrittenBefore(callable, candidate, match.index)
       && new RegExp(`\\b${escapeRegex(candidate)}\\b`).test(argumentsText))) continue;
-    const helperProof = sourceCallableProof(bodies, helper, requestedErrors, nextVisited);
+    const helperProof = sourceCallableProof(bodies, helper, requestedErrors, nextVisited, contractText, contractTarget);
     proof.generic ||= helperProof.generic;
     for (const partition of helperProof.partitions) proof.partitions.add(partition);
   }
   return proof;
 }
-
-function sourceCallableProves(bodies, name, requestedErrors, requestedPartitions) {
-  const proof = sourceCallableProof(bodies, name, requestedErrors);
+function sourceCallableProves(bodies, name, requestedErrors, requestedPartitions, contractText = "") {
+  const proof = sourceCallableProof(bodies, name, requestedErrors, new Set(), contractText, name);
   return proof.generic && requestedPartitions.every((partition) => partitionCovered(partition, proof.partitions));
 }
+
 function evidenceCallableNames(sourceText) {
   const names = new Set();
   const ignored = new Set(["catch", "for", "if", "switch", "while", "with"]);
@@ -891,7 +891,12 @@ export function acceptanceInvalidInputEvidence(input = {}) {
   const sourceText = normalizedText(sanitizeJavaScriptEvidence(input.sourceText));
   const testText = normalizedText(sanitizeJavaScriptEvidence(input.testText));
   const requestedErrors = requestedErrorClasses(taskText);
+  const ambiguousErrorIntent = hasAmbiguousErrorClassIntent(taskText);
   const requestedPartitions = requestedInvalidPartitions(taskText);
+  // A constructor set alone cannot prove a mapping. Mixed-class evidence uses a narrow grammar;
+  // ambiguous prose or indirect source/test proof abstains fail-closed.
+  const requestedErrorMapping = requestedErrors.length > 1
+    ? requestedErrorPartitionMapping(taskText, requestedErrors, requestedPartitions) : null;
   const namedTargets = uniqueStrings(input.namedTargets).map((item) => item.toLowerCase());
   const provenanceTargets = new Set(uniqueStrings(input.provenanceTargets).map((item) => item.toLowerCase()));
   const sourceEntries = (Array.isArray(input.sourceEntries) ? input.sourceEntries : [])
@@ -900,8 +905,8 @@ export function acceptanceInvalidInputEvidence(input = {}) {
     .filter((entry) => entry && typeof entry.path === "string" && typeof entry.text === "string");
   const bodyMaps = new Map(sourceEntries.map((entry) => [entryPath(entry.path), callableBodies(normalizedText(sanitizeJavaScriptEvidence(entry.text)))]));
   if (sourceEntries.length === 0) bodyMaps.set("", callableBodies(sourceText));
-  const sourceLexicalOk = sourceEntries.length > 0 ? sourceEntries.every((entry) => lexicalEvidenceIsNonReflective(normalizedText(sanitizeJavaScriptEvidence(entry.text)))) : lexicalEvidenceIsNonReflective(sourceText);
-  const testLexicalOk = testEntries.length > 0 ? testEntries.every((entry) => lexicalEvidenceIsNonReflective(normalizedText(sanitizeJavaScriptEvidence(entry.text)))) : lexicalEvidenceIsNonReflective(testText);
+  const sourceLexicalOk = sourceEntries.length > 0 ? sourceEntries.every((entry) => !hasReservedEvidenceIdentifier(entry.text) && lexicalEvidenceIsNonReflective(normalizedText(sanitizeJavaScriptEvidence(entry.text)))) : !hasReservedEvidenceIdentifier(input.sourceText) && lexicalEvidenceIsNonReflective(sourceText);
+  const testLexicalOk = testEntries.length > 0 ? testEntries.every((entry) => !hasReservedEvidenceIdentifier(entry.text) && lexicalEvidenceIsNonReflective(normalizedText(sanitizeJavaScriptEvidence(entry.text)))) : !hasReservedEvidenceIdentifier(input.testText) && lexicalEvidenceIsNonReflective(testText);
   const sourceConstructorOk = requestedErrors.length === 0 || (sourceEntries.length > 0
     ? sourceEntries.every((entry) => intrinsicErrorBindingsUntampered(normalizedText(sanitizeJavaScriptEvidence(entry.text)), requestedErrors))
     : intrinsicErrorBindingsUntampered(sourceText, requestedErrors));
@@ -922,35 +927,44 @@ export function acceptanceInvalidInputEvidence(input = {}) {
         && (requestedErrors.length === 0 || requestedErrors.some((name) => assertion.errorClasses.includes(name))))
       .map((assertion) => ({ assertion, binding }));
   });
-  const testCallables = new Set([...bindings.flatMap((binding) => binding.testNames), ...structuralTargets.map((target) => `*.${target}`)]);
-  const namedAssertions = namedTargets.length > 0
-    ? executableRejectionAssertions(testText, testCallables).filter((assertion) => (
-        requestedErrors.length === 0 || requestedErrors.some((name) => assertion.errorClasses.includes(name))
-      ))
-    : [];
-  const assertions = namedTargets.length > 0 ? namedAssertions : inferredAssertions.map((item) => item.assertion);
-  const targetOk = assertions.length > 0 && (namedTargets.length === 0 || (
-    bindings.every((binding) => binding.testNames.length > 0 && binding.testNames.some((name) => assertions.some((assertion) => assertion.targets.includes(name))))
-    && structuralTargets.every((target) => assertions.some((assertion) => assertion.targets.includes(`*.${target}`)))
-  ));
+  const boundTestEvidence = boundRejectionTestEvidence({
+    bindings, structuralTargets, requestedErrors, requestedErrorMapping,
+    testCodeEntries: testEntries.map((entry) => ({ path: entryPath(entry.path), code: normalizedText(sanitizeJavaScriptEvidence(entry.text)) })),
+    fallbackTestCode: testText, bodyMaps
+  });
+  const assertions = namedTargets.length > 0 ? boundTestEvidence.assertions : inferredAssertions.map((item) => item.assertion);
+  const mappingTestOk = namedTargets.length > 0 ? boundTestEvidence.mappingOk : requestedErrors.length <= 1;
+  const targetOk = namedTargets.length > 0 ? boundTestEvidence.targetOk : assertions.length > 0;
   const sourceOk = sourceLexicalOk && sourceConstructorOk && (namedTargets.length > 0
     ? bindings.length === strictTargets.length
-      && bindings.every((binding) => Boolean(binding.sourcePath) && Boolean(binding.sourceName) && sourceCallableProves(bodyMaps.get(binding.sourcePath) ?? new Map(), binding.sourceName, requestedErrors, requestedPartitions))
+      && bindings.every((binding) => Boolean(binding.sourcePath) && Boolean(binding.sourceName) && sourceCallableProves(bodyMaps.get(binding.sourcePath) ?? new Map(), binding.sourceName, requestedErrors, requestedPartitions, taskText))
       && structuralTargets.every((target) => [...bodyMaps.values()].filter((bodies) => bodies.has(target)).length === 1
-        && [...bodyMaps.values()].some((bodies) => sourceCallableProves(bodies, target, requestedErrors, requestedPartitions)))
+        && [...bodyMaps.values()].some((bodies) => sourceCallableProves(bodies, target, requestedErrors, requestedPartitions, taskText)))
     : inferredAssertions.length > 0 && inferredAssertions.every(({ binding }) => (
-        sourceCallableProves(bodyMaps.get(binding.sourcePath) ?? new Map(), binding.sourceName, requestedErrors, requestedPartitions)
-      )));
+        sourceCallableProves(bodyMaps.get(binding.sourcePath) ?? new Map(), binding.sourceName, requestedErrors, requestedPartitions, taskText)
+      ))) && (requestedErrors.length <= 1 || Boolean(requestedErrorMapping && namedTargets.length > 0
+        && bindings.every((binding) => sourceCallableProvesErrorMapping(
+          bodyMaps.get(binding.sourcePath) ?? new Map(), binding.sourceName, requestedErrorMapping
+        ))
+        && structuralTargets.every((target) => [...bodyMaps.values()].filter((bodies) => bodies.has(target)).length === 1
+          && [...bodyMaps.values()].some((bodies) => sourceCallableProvesErrorMapping(bodies, target, requestedErrorMapping)))));
+  const assertionModeOk = namedTargets.length > 0 ? boundTestEvidence.modeOk
+    : inferredAssertions.length > 0 && inferredAssertions.every(({ assertion, binding }) => (
+        assertion.mode === callableAssertionMode(bodyMaps.get(binding.sourcePath) ?? new Map(), binding.sourceName)
+      ));
   const partitions = new Set(assertions.flatMap((assertion) => [...assertion.partitions]));
   const partitionOk = requestedPartitions.every((partition) => partitionCovered(partition, partitions));
-  return { sourceOk, testOk: testLexicalOk && testConstructorOk && targetOk && partitionOk };
+  return { sourceOk: sourceOk && !ambiguousErrorIntent,
+    testOk: testLexicalOk && testConstructorOk && targetOk && partitionOk && mappingTestOk && assertionModeOk && !ambiguousErrorIntent };
 }
 
 export function acceptanceContractProofGuidance(raw) {
   const value = normalizedText(raw);
   const guidance = [...acceptanceBoundaryProofGuidance(raw)];
   if (onlyUndefinedContract(raw)) guidance.push("Prove undefined falls through while null, false, 0, and empty string are each preserved at the highest-precedence position.");
-  if (/\btypeerror\b/.test(value)) guidance.push("Assert TypeError for every rejected partition named by the request; a different error class is not equivalent.");
+  const requestedSpecificErrors = hasAmbiguousErrorClassIntent(raw) ? [] : requestedErrorClasses(raw).map((errorClass) => ERROR_CONSTRUCTOR_DISPLAY_NAMES[errorClass]).filter(Boolean);
+  if (requestedSpecificErrors.length === 1) guidance.push(`Assert ${requestedSpecificErrors[0]} for every rejected partition named by the request; a different error class is not equivalent.`);
+  if (requestedSpecificErrors.length > 1) guidance.push(`Preserve the request's partition-to-error mapping: assert each rejected partition with its explicitly named class (${requestedSpecificErrors.join(", ")}); do not apply one class to every partition.`);
   const integerTargets = integerConstraintTargets(raw);
   if (integerTargets.length > 0) guidance.push(`Reject fractional values for every integer-constrained argument (${integerTargets.join(", ")}).`);
   const nullRejectingTargets = nullRejectingDefaultTargets(raw);

package/packages/piagent-core/extensions/acceptance-error-classes.js

@@ -0,0 +1,160 @@
+export const ERROR_CONSTRUCTORS = [
+  "typeerror",
+  "rangeerror",
+  "syntaxerror",
+  "referenceerror",
+  "urierror",
+  "evalerror",
+  "aggregateerror",
+  "error"
+];
+
+export const ERROR_CONSTRUCTOR_DISPLAY_NAMES = Object.freeze({
+  typeerror: "TypeError",
+  rangeerror: "RangeError",
+  syntaxerror: "SyntaxError",
+  referenceerror: "ReferenceError",
+  urierror: "URIError",
+  evalerror: "EvalError",
+  aggregateerror: "AggregateError",
+  error: "Error"
+});
+
+const ERROR_ACTION = String.raw`(?:throw(?:s|ing)?|rais(?:e|es|ed|ing)|reject(?:s|ed|ing)?|use(?:s|d|ing)?|return(?:s|ed|ing)?|emit(?:s|ted|ting)?|produc(?:e|es|ed|ing)|expect(?:s|ed|ing)?|requir(?:e|es|ed|ing))`;
+const ERROR_ACTION_MENTION = new RegExp(String.raw`\b(?:(?:(?:must|should|shall|do|does|did|can|could|may|might|will|would)\s+)?(?:not|never)\s+(?:ever\s+)?(${ERROR_ACTION})|(${ERROR_ACTION}))\b`, "g");
+const NEGATED_ERROR_PREFIX = /\b(?:never|rather\s+than|instead\s+of|as\s+opposed\s+to|except|other\s+than|(?:but\s+)?not|no)(?:\s+an?)?\s*$/;
+const NEGATED_ERROR_ACTION_PREFIX = /\b(?:without|avoid(?:s|ed|ing)?|prevent(?:s|ed|ing)?|suppress(?:es|ed|ing)?)\s+(?:ever\s+)?(?:throw(?:s|n|ing)?|rais(?:e|es|ed|ing)|reject(?:s|ed|ing)?|us(?:e|es|ed|ing)|return(?:s|ed|ing)?|emit(?:s|ted|ting)?|produc(?:e|es|ed|ing))?(?:\s+an?)?\s*$/;
+const NON_REQUEST_SOURCE_PREFIX = /\b(?:catch(?:es|ing)?|caught|handl(?:e|es|ed|ing)|observ(?:e|es|ed|ing)|receiv(?:e|es|ed|ing)|inspect(?:s|ed|ing)?|log(?:s|ged|ging)?|ignor(?:e|es|ed|ing)|swallow(?:s|ed|ing)?|convert(?:s|ed|ing)?|wrap(?:s|ped|ping)?|translat(?:e|es|ed|ing)|replac(?:e|es|ed|ing)|chang(?:e|es|ed|ing)|turn(?:s|ed|ing)?)\s+(?:an?)?\s*$/;
+const NEGATED_ERROR_SUFFIX = /^\s+(?:(?:must|should|shall|can|could|may|might|will|would)\s+)?(?:not|never)\s+be\s+(?:thrown|raised|used|returned|emitted|produced)\b|^\s+is\s+(?:not\s+(?:allowed|required|expected|acceptable|equivalent)|forbidden|disallowed|prohibited)\b/;
+const AFFIRMATIVE_ERROR_SUFFIX = /^\s+(?:(?:must|should|shall|can|could|may|might|will|would)\s+)?(?:be\s+)?(?:thrown|raised|used|returned|emitted|produced|required|expected)\b|^\s+is\s+(?:required|expected)\b/;
+const TRANSFORM_TARGET_PREFIX = /\b(?:convert(?:s|ed|ing)?|wrap(?:s|ped|ping)?|translat(?:e|es|ed|ing)|map(?:s|ped|ping)?|replac(?:e|es|ed|ing)|chang(?:e|es|ed|ing)|turn(?:s|ed|ing)?)\b[^.;!?\n]{0,96}\b(?:into|to|as)(?:\s+an?)?\s*$/;
+const RESULT_TARGET_PREFIX = /\b(?:result(?:s|ed|ing)?\s+in|resolve(?:s|d|ing)?\s+to)(?:\s+an?)?\s*$/;
+const MAPPED_PARTITION_SUFFIX = /^\s*`?\s+(?:for|with)\s+(?:an?\s+)?(?:negative|fractional|zero|null|empty[- ]string|whitespace-only|non-finite|unsafe[- ]integer|missing|undefined|non-array|non-string|arrays?|plain[- ]objects?|primitives?)\b/;
+const NEUTRAL_CONSTRUCTOR_SUFFIX = /^\s*`?\s*(?:from|reported\s+by|(?:is|was)\s+(?:caught|handled|logged|ignored|observed)|(?:is|was)\s+(?:not\s+allowed|forbidden|disallowed|prohibited))\b/;
+const ERROR_MAPPING_PARTITIONS = Object.freeze([
+  ["negative", /\bnegative\b/], ["fractional", /\bfractional\b/], ["zero", /\bzero\b/], ["null", /\bnull\b/],
+  ["empty-string", /\bempty[- ]string\b/], ["whitespace-string", /\bwhitespace-only\b/],
+  ["non-finite", /\bnon-finite\b/], ["unsafe-integer", /\bunsafe[- ]integer\b/],
+  ["missing", /\b(?:missing|undefined)\b/], ["non-array", /\bnon-array\b/], ["non-string", /\bnon-string\b/],
+  ["array", /\barrays?\b/], ["plain-object", /\bplain[- ]objects?\b/], ["primitive", /\bprimitives?\b/]
+]);
+
+function normalizedText(value) {
+  return String(value ?? "")
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/\b(is|are|was|were|do|does|did|should|would|could|must|will|shall)n['’]t\b/gi, "$1 not")
+    .replace(/\bcan['’]t\b/gi, "can not")
+    .toLowerCase();
+}
+
+function affirmativeErrorConstructorMention(value, name) {
+  for (const match of value.matchAll(new RegExp(`\\b${name}\\b`, "g"))) {
+    const start = match.index ?? 0;
+    const end = start + match[0].length;
+    const clauseStart = Math.max(value.lastIndexOf(".", start - 1), value.lastIndexOf(";", start - 1), value.lastIndexOf("!", start - 1), value.lastIndexOf("?", start - 1), value.lastIndexOf("\n", start - 1));
+    const followingBoundary = value.slice(end).search(/[.;!?\n]/);
+    const prefix = value.slice(clauseStart + 1, start).trimEnd();
+    const suffix = value.slice(end, followingBoundary < 0 ? value.length : end + followingBoundary);
+    if (NEGATED_ERROR_PREFIX.test(prefix) || NEGATED_ERROR_ACTION_PREFIX.test(prefix)
+      || NON_REQUEST_SOURCE_PREFIX.test(prefix) || NEGATED_ERROR_SUFFIX.test(suffix)) continue;
+    const conditional = prefix.match(/\b(?:when|if|after|once|while)\b[^,;]*$/i);
+    if (conditional && !new RegExp(`\\b(?:must|should|shall|will)\\s+${ERROR_ACTION}\\b`, "i").test(conditional[0])) continue;
+    let lastActionNegated = false;
+    let actionObserved = false;
+    for (const action of prefix.matchAll(ERROR_ACTION_MENTION)) {
+      actionObserved = true;
+      lastActionNegated = Boolean(action[1]);
+    }
+    if (actionObserved) {
+      if (lastActionNegated) continue;
+      return true;
+    }
+    if (AFFIRMATIVE_ERROR_SUFFIX.test(suffix) || TRANSFORM_TARGET_PREFIX.test(prefix)
+      || RESULT_TARGET_PREFIX.test(prefix)) return true;
+  }
+  return false;
+}
+
+function bareConstructorSegment(value, start, end) {
+  const before = value.slice(0, start);
+  const boundaries = [...before.matchAll(/(?:[;,.!?\n]|\b(?:and|but|whereas|or)\b)/g)];
+  const segmentStart = boundaries.at(-1)?.index + boundaries.at(-1)?.[0].length || 0;
+  const following = value.slice(end), boundary = following.search(/[;,.!?\n]|\b(?:and|but|whereas|or)\b/);
+  const prefix = value.slice(segmentStart, start), suffix = value.slice(end, boundary < 0 ? value.length : end + boundary);
+  return /^\s*`?\s*$/.test(prefix) ? { suffix } : null;
+}
+
+function ellipticalOrAmbiguousMention(value, name) {
+  let ambiguous = false;
+  for (const match of value.matchAll(new RegExp(`\\b${name}\\b`, "g"))) {
+    const segment = bareConstructorSegment(value, match.index ?? 0, (match.index ?? 0) + match[0].length);
+    if (!segment || NEUTRAL_CONSTRUCTOR_SUFFIX.test(segment.suffix)) continue;
+    if (MAPPED_PARTITION_SUFFIX.test(segment.suffix)) return { affirmative: true, ambiguous: false };
+    ambiguous = true;
+  }
+  return { affirmative: false, ambiguous };
+}
+
+export function requestedErrorClasses(text) {
+  const value = normalizedText(text);
+  const raw = String(text ?? ""), eligible = ERROR_CONSTRUCTORS.filter((name) => name !== "error" || /\bError\b/.test(raw));
+  return eligible.filter((name) => affirmativeErrorConstructorMention(value, name)
+    || ellipticalOrAmbiguousMention(value, name).affirmative);
+}
+
+export function hasAmbiguousErrorClassIntent(text) {
+  const value = normalizedText(text), raw = String(text ?? "");
+  return ERROR_CONSTRUCTORS.some((name) => (name !== "error" || /\bError\b/.test(raw))
+    && !affirmativeErrorConstructorMention(value, name)
+    && ellipticalOrAmbiguousMention(value, name).ambiguous);
+}
+
+export function requestedErrorPartitionMapping(text, requestedErrors, requestedPartitions) {
+  const wanted = new Set(requestedPartitions), mappings = new Map();
+  const segments = normalizedText(text).split(/(?:[.;!?\n]+|,\s*|\s+\b(?:and|but|whereas)\b\s+)/).filter(Boolean);
+  for (const segment of segments) {
+    const partitions = ERROR_MAPPING_PARTITIONS.filter(([partition, pattern]) => wanted.has(partition) && pattern.test(segment)).map(([partition]) => partition);
+    const classes = requestedErrors.filter((name) => new RegExp(`\\b${name}\\b`).test(segment));
+    if (partitions.length === 0 && classes.length === 0) continue;
+    if (partitions.length !== 1 || classes.length !== 1
+      || mappings.has(partitions[0]) && mappings.get(partitions[0]) !== classes[0]) return null;
+    mappings.set(partitions[0], classes[0]);
+  }
+  if (mappings.size !== wanted.size || requestedErrors.some((name) => ![...mappings.values()].includes(name))) return null;
+  return [...mappings].map(([partition, errorClass]) => ({ partition, errorClass }));
+}
+
+export function assertionsProveErrorMapping(assertions, targets, mapping) {
+  return mapping.every((expected) => {
+    const relevant = assertions.filter((assertion) => assertion.partitions.has(expected.partition)
+      && assertion.targets.some((target) => targets.includes(target)));
+    return relevant.length > 0 && relevant.every((assertion) => (
+      assertion.errorClasses.length === 1 && assertion.errorClasses[0] === expected.errorClass
+    ));
+  });
+}
+
+export function rejectionStatementErrorClass(text, requestedErrors) {
+  const match = text.match(/^\s*throw\s+(?:new\s+)?([a-z_$][a-z0-9_$]*)\s*\(/);
+  const errorClass = match?.[1]?.toLowerCase();
+  if (!errorClass || !ERROR_CONSTRUCTORS.includes(errorClass)) return null;
+  const open = match[0].lastIndexOf("(");
+  let depth = 0, close = -1;
+  for (let index = open; index < Math.min(text.length, open + 2_000); index += 1) {
+    if (text[index] === "(") depth += 1;
+    else if (text[index] === ")" && --depth === 0) { close = index + 1; break; }
+  }
+  if (close === -1) return null;
+  const argument = text.slice(open + 1, close - 1).trim();
+  if (argument && !/^__pi_(?:(?:empty|double_quote|whitespace)_string|string|node_assert_module|code_generation_module|module_loader_module|error_name_[a-z]+)_literal__$/i.test(argument)) return null;
+  if (!/^(?:[ \t]*;|[ \t]*(?:\}|$))/u.test(text.slice(close))) return null;
+  return requestedErrors.length === 0 || requestedErrors.includes(errorClass) ? errorClass : null;
+}
+
+export function errorMappingsProveContract(observed, mapping) {
+  return mapping.every((expected) => {
+    const matches = observed.filter((actual) => actual.partition === expected.partition);
+    return matches.length > 0 && matches.every((actual) => actual.errorClass === expected.errorClass);
+  });
+}

package/packages/piagent-core/extensions/acceptance-executable-evidence.js

@@ -243,7 +243,7 @@ function rejectionAssertionHelpers(testText, assertionCarriers) {
   for (const declaration of assertionHelperDeclarations(testText)) {
     if (/\b(?:if|for|while|switch|try|catch|return|throw|class|function)\b|\.(?:skip|todo)\b/.test(declaration.body)) continue;
     const parameters = [...declaration.parameters.matchAll(/[a-z_$][a-z0-9_$]*/gi)].map((match) => match[0].toLowerCase()).slice(0, 8);
-    for (const match of declaration.body.matchAll(/\b([a-z_$][a-z0-9_$]*)\.(?:throws|rejects)\s*\(/gi)) {
+    for (const match of declaration.body.matchAll(/\b([a-z_$][a-z0-9_$]*)\.(throws|rejects)\s*\(/gi)) {
       if (!assertionCarriers.has(match[1].toLowerCase())) continue;
       const open = declaration.body.indexOf("(", match.index);
       const end = balancedEnd(declaration.body, open);
@@ -254,7 +254,7 @@ function rejectionAssertionHelpers(testText, assertionCarriers) {
       const before = declaration.body.slice(0, match.index).replace(/^\s*\{?\s*(?:return\s+|await\s+)?/, "");
       const after = declaration.body.slice(end).replace(/;?\s*\}?\s*$/, "");
       if (errorClasses.length > 0 && directParameter && !before && !after) {
-        helpers.push({ ...declaration, errorClasses });
+        helpers.push({ ...declaration, errorClasses, mode: match[2].toLowerCase() });
         break;
       }
     }
@@ -283,7 +283,7 @@ function callbackBodyRange(text, argument) {
   return end === -1 || end > argument.end + 1 ? undefined : { start: bodyStart + 1, end: end - 1, braced: true };
 }
 
-export function executableRejectionAssertions(testText, callableNames) {
+export function executableRejectionAssertions(testText, callableNames, modeHintsOnly = false) {
   const assertions = [];
   const carrierBindings = assertionCarrierBindings(testText);
   const assertionCarriers = new Set((assertionEvidenceFileSupported(testText)
@@ -420,6 +420,7 @@ export function executableRejectionAssertions(testText, callableNames) {
     const forOf = header.match(/^\s*(?:const|let)\s+([a-z_$][a-z0-9_$]*)\s+of\s+([\s\S]+?)\s*$/i);
     const iterable = forOf && iterationLiteral(forOf[2], match.index);
     if (iterable) iterationRanges.push({ ...iterationBody, ...iterable, kind: "for-of", variable: forOf[1] });
+    else if (modeHintsOnly && forOf) iterationRanges.push({ ...iterationBody, kind: "for-of", variable: forOf[1] });
     else unsupportedControlRanges.push(body);
   }
   for (const match of testText.matchAll(/\.foreach\s*\(/g)) {
@@ -460,7 +461,7 @@ export function executableRejectionAssertions(testText, callableNames) {
     const prefix = testText.slice(range.start, start);
     return !new RegExp(`\\b(?:const|let|var|function|class)\\s+${escaped}\\b|\\b${escaped}\\b\\s*(?:\\+\\+|--|[+*/%&|^-]=|=(?!=|>))|(?:\\+\\+|--)\\s*\\b${escaped}\\b`, "i").test(prefix);
   };
-  const record = (start, end, errorClasses, operation) => {
+  const record = (start, end, errorClasses, operation, mode) => {
     if (end === -1) return;
     if ([...declarationRanges, ...skippedRanges, ...conditionalRanges, ...unsupportedControlRanges]
       .some((range) => start >= range.start && start < range.end)) return;
@@ -495,16 +496,17 @@ export function executableRejectionAssertions(testText, callableNames) {
     if (targets.length === 0) return;
     const partitions = evidencePartitionSignals(assertion);
     for (const range of referencedIterations) {
-      for (const signal of literalArrayPartitionSignals(range.literal)) partitions.add(signal);
+      if (range.literal) for (const signal of literalArrayPartitionSignals(range.literal)) partitions.add(signal);
     }
-    assertions.push({ targets, errorClasses, partitions });
+    assertions.push({ targets, errorClasses, partitions, mode });
   };
   for (const match of testText.matchAll(/\b([a-z_$][a-z0-9_$]*)\.(?:throws|rejects)\s*\(/gi)) {
     if (!assertionCarriers.has(match[1].toLowerCase())) continue;
     const open = testText.indexOf("(", match.index);
     const end = balancedEnd(testText, open);
     const argumentsList = end === -1 ? [] : topLevelArgumentRanges(testText, open, end);
-    record(match.index, end, evidenceErrorClasses(end === -1 ? "" : testText.slice(match.index, end)), argumentsList[0]?.text);
+    record(match.index, end, evidenceErrorClasses(end === -1 ? "" : testText.slice(match.index, end)), argumentsList[0]?.text,
+      /\.rejects\s*\(/i.test(match[0]) ? "rejects" : "throws");
   }
   for (const helper of rejectionAssertionHelpers(testText, assertionCarriers)) {
     for (const match of testText.matchAll(new RegExp(`\\b${escapeRegex(helper.name)}\\s*\\(`, "g"))) {
@@ -512,7 +514,7 @@ export function executableRejectionAssertions(testText, callableNames) {
       const open = testText.indexOf("(", match.index);
       const end = balancedEnd(testText, open);
       const argumentsList = end === -1 ? [] : topLevelArgumentRanges(testText, open, end);
-      record(match.index, end, helper.errorClasses, argumentsList[0]?.text);
+      record(match.index, end, helper.errorClasses, argumentsList[0]?.text, helper.mode);
     }
   }
   for (const match of testText.matchAll(/\bexpect\s*\(/g)) {
@@ -525,7 +527,8 @@ export function executableRejectionAssertions(testText, callableNames) {
     const throwOpen = testText.indexOf("(", expectEnd + chain.index);
     const end = balancedEnd(testText, throwOpen);
     const argumentsList = topLevelArgumentRanges(testText, open, expectEnd);
-    record(match.index, end, evidenceErrorClasses(end === -1 ? "" : testText.slice(match.index, end)), argumentsList[0]?.text);
+    record(match.index, end, evidenceErrorClasses(end === -1 ? "" : testText.slice(match.index, end)), argumentsList[0]?.text,
+      /\.rejects/i.test(chain[0]) ? "rejects" : "throws");
   }
   return assertions.slice(0, 64);
 }