@meantjs/profile 0.1.0 → 0.3.0

package/src/analyze.mjs

@@ -7,8 +7,9 @@ import { parseAddress } from "./address.mjs";
 import { jcs } from "./util.mjs";
 import { TagIndex, LayeredTags, positions } from "./tags.mjs";
 import {
-  NUMERIC, METHOD_TAGS, STALE_CODES, VALUE_CONVERSION_TAGS,
-  checkApplicability, checkDynamic, parseTemplate, outcomeCoverage,
+  NUMERIC, METHOD_TAGS, CASE_TAGS, CONFIRM_KINDS, STALE_CODES, VALUE_CONVERSION_TAGS, EVM_LATER_TAGS,
+  checkApplicability, checkDynamic, parseTemplate, outcomeCoverage, caseTargetError, otherCase, overlap, defaultEffect,
+  tokenPathError,
 } from "./checks.mjs";
 
 /** Spec section 8, highest precedence first. */
@@ -107,6 +108,45 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
   // A pack applied to a service is allowed to differ from its fragment in the ways Candid subtyping allows, so an
   // annotation that no longer holds on this service is dropped with an info, not reported as an error in the pack.
   const dropped = new Set();
+  const caseEntries = []; // case intents and effects, checked against each other and their method after the loop
+
+  /** An effect against the method's mode (spec 5.3); for a case effect, the mode of the method it sits in. */
+  const checkEffectMode = (m, { kind, irreversible, replicated }, diag, at) => {
+    // A signed EIP-712 message (spec section 15.9) runs nothing when it is signed: any kind describes what it allows.
+    if (m.mode === "message") {
+      if (replicated === true) diag("error", "E_EFFECT_MODE", at, "replicated: true applies to update methods, not to a message");
+      return;
+    }
+    if (m.mode !== "update" && m.mode !== "oneway" && kind !== "read") diag("error", "E_EFFECT_MODE", at, `${m.mode} method cannot have effect kind "${kind}"`);
+    // A read-only update (D-038): a read sent as an update so that its answer goes through consensus.
+    if (replicated === true) {
+      if (m.mode !== "update") diag("error", "E_EFFECT_MODE", at, `replicated: true applies to update methods, not to a ${m.mode} method`);
+      if (kind !== "read" || irreversible !== false) diag("error", "E_EFFECT_MODE", at, `replicated: true needs kind "read" and irreversible: false, found kind "${kind}" and irreversible: ${irreversible}`);
+    }
+    const replicatedRead = replicated === true && m.mode === "update" && kind === "read" && irreversible === false;
+    if ((m.mode === "update" || m.mode === "oneway") && kind === "read" && !replicatedRead) {
+      diag("warning", "W_EFFECT_MODE", at, `${m.mode} method declared as read${m.mode === "update" && replicated !== true ? "; a read sent as an update says irreversible: false, replicated: true" : ""}`);
+    }
+  };
+
+  /** An intent template's placeholders (spec section 6); `caseAddr` is the case a case intent sits on. */
+  const checkTemplate = (item, methodName, template, diag, at, caseAddr) => {
+    const t = parseTemplate(template);
+    if (t.error) return diag("error", "E_TEMPLATE", at, t.error);
+    if (iface.chain === "evm" && t.segments) return diag("error", "E_TEMPLATE", at, "an EVM contract's template has no [ ] segments: an ABI value is never absent (spec section 15)");
+    for (const p of t.placeholders) {
+      const r = iface.resolveRel(methodName, "args", p.path);
+      if (r.error && item.apply && p.inOptional) { // absent in this service: the optional segment renders empty (spec section 6)
+        item.diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `intent: {${p.path}} is absent in this service (${r.error}); its optional segment renders empty`);
+        continue;
+      }
+      if (r.error) { diag("error", "E_TEMPLATE_PATH", at, `{${p.path}}: ${r.error}`); continue; }
+      const other = caseAddr && otherCase(iface, caseAddr, p.path);
+      if (other) { diag("error", "E_TEMPLATE_PATH", at, `{${p.path}}: ${other}`); continue; }
+      if (!p.inOptional && iface.node(r.ref).kind === "opt") diag("warning", "W_TEMPLATE_OPTIONAL", at, `{${p.path}} is optional but sits outside a [ ] segment`);
+    }
+  };
+
   const sets = new Map(); // names set -> { at, method, fields: { name, value, show?, kind? } } (spec 5.3, D-045)
   const named = []; // named positions, checked once every set is known
   for (const e of entries) {
@@ -118,22 +158,24 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
       item.diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `${a.tag} dropped: ${code}: ${message}`);
     };
     const at = a.at;
+    if (iface.chain === "evm" && EVM_LATER_TAGS.has(a.tag)) {
+      diag("error", "E_TAG_TARGET", at, `${a.tag} is not defined for EVM contracts yet: it needs receipts, nonces or reads that a later phase adds (spec section 15)`);
+      continue;
+    }
+    // intent and effect on a case of a variant in the arguments (spec 5.2, D-053)
+    if (CASE_TAGS.has(a.tag) && !res.method) {
+      const why = caseTargetError(iface, addr, res, a.tag);
+      if (why) { diag("error", "E_TAG_TARGET", at, why); continue; }
+      const m = iface.methods.get(addr.method);
+      if (a.tag === "effect") checkEffectMode(m, a.args, diag, at);
+      else checkTemplate(item, addr.method, a.args.template, diag, at, addr);
+      caseEntries.push({ e, diag });
+      continue;
+    }
     if (METHOD_TAGS.has(a.tag)) {
       const m = res.method;
       const methodName = addr.method;
-      if (a.tag === "effect") {
-        const { kind, irreversible, replicated } = a.args;
-        if (m.mode !== "update" && m.mode !== "oneway" && kind !== "read") diag("error", "E_EFFECT_MODE", at, `${m.mode} method cannot have effect kind "${kind}"`);
-        // A read-only update (D-038): a read sent as an update so that its answer goes through consensus.
-        if (replicated === true) {
-          if (m.mode !== "update") diag("error", "E_EFFECT_MODE", at, `replicated: true applies to update methods, not to a ${m.mode} method`);
-          if (kind !== "read" || irreversible !== false) diag("error", "E_EFFECT_MODE", at, `replicated: true needs kind "read" and irreversible: false, found kind "${kind}" and irreversible: ${irreversible}`);
-        }
-        const replicatedRead = replicated === true && m.mode === "update" && kind === "read" && irreversible === false;
-        if ((m.mode === "update" || m.mode === "oneway") && kind === "read" && !replicatedRead) {
-          diag("warning", "W_EFFECT_MODE", at, `${m.mode} method declared as read${m.mode === "update" && replicated !== true ? "; a read sent as an update says irreversible: false, replicated: true" : ""}`);
-        }
-      }
+      if (a.tag === "effect") checkEffectMode(m, a.args, diag, at);
       if (a.tag === "idempotency") {
         if (m.mode !== "update") diag("error", "E_IDEMPOTENCY_MODE", at, "idempotency applies to update methods");
         const r = iface.resolveRel(methodName, "args", a.args.stamp);
@@ -153,19 +195,7 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
         outcomeCoverage(iface, methodName, classes, diag, at, Boolean(a.args.default));
         if (doc.kind === "pack" && !a.args.default) diag("warning", "W_PACK_NO_DEFAULT", at, "pack outcome without default: result cases a matching canister adds (spec §7) would be unclassified");
       }
-      if (a.tag === "intent") {
-        const t = parseTemplate(a.args.template);
-        if (t.error) diag("error", "E_TEMPLATE", at, t.error);
-        else for (const p of t.placeholders) {
-          const r = iface.resolveRel(methodName, "args", p.path);
-          if (r.error && item.apply && p.inOptional) { // absent in this service: the optional segment renders empty (spec section 6)
-            item.diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `intent: {${p.path}} is absent in this service (${r.error}); its optional segment renders empty`);
-            continue;
-          }
-          if (r.error) { diag("error", "E_TEMPLATE_PATH", at, `{${p.path}}: ${r.error}`); continue; }
-          if (!p.inOptional && iface.node(r.ref).kind === "opt") diag("warning", "W_TEMPLATE_OPTIONAL", at, `{${p.path}} is optional but sits outside a [ ] segment`);
-        }
-      }
+      if (a.tag === "intent") checkTemplate(item, methodName, a.args.template, diag, at);
       if (a.tag === "names") {
         const effect = tags.methodTags(methodName).effect?.args;
         const replicatedRead = m.mode === "update" && effect?.kind === "read" && effect.irreversible === false && effect.replicated === true;
@@ -210,7 +240,10 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     const err = checkApplicability(iface, a.tag, res.ref);
     if (err) diag("error", "E_TAG_NOT_APPLICABLE", at, err);
     if (a.tag === "named") named.push({ a, res, diag, at });
-    if (a.tag === "amount") {
+    if (a.tag === "amount" && a.args.token !== undefined) {
+      const why = tokenPathError(iface, addr, a.args.token);
+      if (why) diag("error", "E_TOKEN_PATH", at, why);
+    } else if (a.tag === "amount") {
       checkDynamic(iface, a.args.decimals, "numeric", diag, at);
       checkDynamic(iface, a.args.symbol, "text", diag, at);
     }
@@ -234,6 +267,28 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     }
   }
 
+  // Tagged cases of one method must not overlap, and a case effect needs a method effect at least as strong
+  // (spec 5.2 and 5.3, D-053).
+  for (let j = 0; j < caseEntries.length; j++) {
+    const { e, diag } = caseEntries[j];
+    const { addr, ann: a } = e;
+    for (const { e: prev } of caseEntries.slice(0, j)) {
+      if (prev.ann.tag !== a.tag || prev.addr.method !== addr.method || prev.res.key === e.res.key) continue;
+      const why = overlap(iface, prev.addr, addr);
+      if (why) diag("error", "E_CASE_OVERLAP", a.at, `${a.tag} on "${prev.ann.at}" and on "${a.at}": one call can take both cases (${why})`);
+    }
+    if (a.tag !== "effect") continue;
+    const m = iface.methods.get(addr.method);
+    const declared = tags.methodTags(addr.method).effect?.args;
+    const method = declared ?? defaultEffect(m.mode);
+    const whose = `the method's effect is ${method.kind}${method.irreversible ? ", irreversible" : ""}${declared ? "" : " (the default)"}`;
+    if (CONFIRM_KINDS.has(a.args.kind) && !CONFIRM_KINDS.has(method.kind)) {
+      diag("error", "E_CASE_EFFECT", a.at, `case effect ${a.args.kind} needs a person's confirmation, but ${whose}; declare the method's effect as transfer, approve, admin or destroy, so that a consumer that reads only method tags confirms it too`);
+    } else if (a.args.irreversible === true && method.irreversible !== true) {
+      diag("error", "E_CASE_EFFECT", a.at, `case effect is irreversible, but ${whose}; a method with an irreversible case is irreversible`);
+    }
+  }
+
   // Dropping a value tag can leave an idempotency stamp without its timestamp tag: drop that idempotency too.
   if (dropped.size) {
     const without = buildLayers(entries, (e) => !dropped.has(e));
@@ -280,10 +335,11 @@ export function analyzeProfiles(iface, items, { attribute = true } = {}) {
     }
   }
 
-  // Coverage hint: numeric positions in update-method arguments with no meaning attached (merged view).
+  // Coverage hint: numeric positions in the arguments of update methods and EIP-712 messages with no meaning attached
+  // (merged view).
   const MEANING = ["amount", "timestamp", "duration", "describe", "range"];
   for (const [name, m] of iface.methods) {
-    if (m.mode !== "update") continue;
+    if (m.mode !== "update" && m.mode !== "message") continue;
     for (const pos of positions(iface, name, "args")) {
       const p = iface.prim(iface.unwrapOpt(pos.ref).ref);
       const t = final.at(pos, iface);

package/src/browser.d.mts

@@ -1,11 +1,11 @@
 // Types for @meantjs/profile/browser. Hand-written; the source is plain ES modules (src/*.mjs). The internal
 // graph classes (Iface, TagIndex, LayeredTags, SubtypeChecker) are declared opaquely.
 
-/** A Candid Profile document (docs/profile-v0.md): a canister profile or a pack. */
+/** A Candid Profile document (docs/profile-v0.md): a canister profile, a pack, or an EVM contract profile (section 15). */
 export interface ProfileDocument {
   format: "candid-profile";
   format_version: 0;
-  kind: "canister" | "pack";
+  kind: "canister" | "pack" | "contract";
   name: string;
   origin: "author" | "third_party" | "pack" | "inferred";
   annotations: { at: string; tag: string; args?: Record<string, unknown> }[];
@@ -17,6 +17,8 @@ export interface ResolvedForm {
   format: "candid-profile-resolved";
   format_version: 0;
   interface_id: string;
+  /** "evm" for an EVM contract's form (section 15.5); absent for a Candid service's. */
+  chain?: "evm";
   profiles: unknown[];
   methods: Record<string, unknown>;
   diagnostics: Diagnostic[];
@@ -54,14 +56,16 @@ export interface SchemaValidator {
 }
 
 export interface ResolveOptions {
-  /** Candid source of the service (exactly one of `did` and `envelope`). */
+  /** Candid source of the service (exactly one of `did`, `envelope` and `abi`). */
   did?: string;
   /** The service's candid-core ContractEnvelope. */
   envelope?: unknown;
+  /** An EVM contract's ABI: human-readable fragments or JSON ABI entries (section 15). */
+  abi?: readonly (string | Record<string, unknown>)[];
   didLabel?: string;
   /** Applied as given; a pack here must match. */
   profiles?: { doc: unknown; label?: string }[];
-  /** Tried by Candid subtyping; applied only if they match. */
+  /** Tried by Candid subtyping (an EVM pack by selector); applied only if they match. */
   packs?: { doc: unknown; label?: string }[];
   validateSchema: SchemaValidator;
 }

package/src/browser.mjs

@@ -10,6 +10,8 @@
 import schema from "../data/profile-v0.schema.json" with { type: "json" };
 import icrc1 from "../data/packs/icrc1.profile.json" with { type: "json" };
 import icrc2 from "../data/packs/icrc2.profile.json" with { type: "json" };
+import erc20 from "../data/packs/erc20.profile.json" with { type: "json" };
+import erc2612 from "../data/packs/erc2612.profile.json" with { type: "json" };
 import { compileSchema } from "./schema-core.mjs";
 
 export { init as initCompiler } from "@candid-core/cli";
@@ -31,8 +33,13 @@ export { readServedProfile, SERVED_SECTION, SERVED_METADATA, SERVED_MAX_BYTES }
 /** The profile schema (a copy of spec/profile-v0.schema.json). */
 export const PROFILE_SCHEMA = schema;
 
-/** The standard packs (copies of packs/*.profile.json), sorted by file name, in the shape `loadPacks` returns. */
+/**
+ * The standard packs (copies of packs/*.profile.json whose kind is "pack"), sorted by file name, in the shape
+ * `loadPacks` returns. The standard contract profiles there (Permit2, DAI's permit) are under `./packs/*` too.
+ */
 export const STANDARD_PACKS = Object.freeze([
+  { file: "erc20.profile.json", doc: erc20 },
+  { file: "erc2612.profile.json", doc: erc2612 },
   { file: "icrc1.profile.json", doc: icrc1 },
   { file: "icrc2.profile.json", doc: icrc2 },
 ]);

package/src/checks.mjs

@@ -1,29 +1,62 @@
 /**
  * Per-annotation semantic checks (spec sections 3 to 6). Moved verbatim from scripts/validate.mjs.
  */
-export const NUMERIC = new Set(["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64"]);
-export const TIMEISH = new Set(["nat", "int", "nat32", "nat64", "int64"]);
+import { parseRelPath } from "./address.mjs";
+
+/** EVM integer types (spec section 15): uint8 to uint256 and int8 to int256. int8 to int64 are also Candid's, with the same bounds. */
+const ABI_BITS = Array.from({ length: 32 }, (_, i) => 8 * (i + 1));
+export const NUMERIC = new Set(["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64", ...ABI_BITS.flatMap((b) => [`uint${b}`, `int${b}`])]);
+export const TIMEISH = new Set(["nat", "int", "nat32", "nat64", "int64", ...ABI_BITS.filter((b) => b >= 32).map((b) => `uint${b}`), ...ABI_BITS.filter((b) => b >= 64).map((b) => `int${b}`)]);
+/** Text: Candid's `text`, the ABI's `string`. */
+export const TEXT = new Set(["text", "string"]);
+/** Tags an EVM contract profile cannot use yet: they need receipts, nonces or reads that phase 2 adds (spec section 15). */
+export const EVM_LATER_TAGS = new Set(["idempotency", "outcome", "list", "names", "named"]);
 export const METHOD_TAGS = new Set(["intent", "effect", "idempotency", "outcome", "list", "names"]);
+/** Method tags that may also sit on a case of a variant in the arguments (spec 5.2, D-053). */
+export const CASE_TAGS = new Set(["intent", "effect"]);
+/** Effect kinds that need a person's confirmation (spec 5.3). */
+export const CONFIRM_KINDS = new Set(["transfer", "approve", "admin", "destroy"]);
 /** Tags that convert a value between its wire form and a human form; a stale profile must not supply them (spec section 7). */
 export const VALUE_CONVERSION_TAGS = new Set(["amount", "timestamp", "duration", "account", "subaccount", "bytes", "named"]);
-export const STALE_CODES = new Set(["E_ADDR_UNRESOLVED", "E_TYPE_NODE", "E_TAG_NOT_APPLICABLE", "E_REF_UNRESOLVED", "E_REF_NOT_QUERY", "E_REF_SHAPE", "E_REF_TYPE", "E_STAMP_UNTAGGED", "E_OUTCOME_NOT_CASE", "E_TEMPLATE_PATH", "E_TAG_TARGET", "E_NAMES_MODE", "E_NAMES_SHAPE", "E_NAMES_FIELD", "E_NAMED_SET", "E_NAMED_TYPE"]);
+export const STALE_CODES = new Set(["E_ADDR_UNRESOLVED", "E_TYPE_NODE", "E_TAG_NOT_APPLICABLE", "E_REF_UNRESOLVED", "E_REF_NOT_QUERY", "E_REF_SHAPE", "E_REF_TYPE", "E_STAMP_UNTAGGED", "E_OUTCOME_NOT_CASE", "E_TEMPLATE_PATH", "E_TAG_TARGET", "E_NAMES_MODE", "E_NAMES_SHAPE", "E_NAMES_FIELD", "E_NAMED_SET", "E_NAMED_TYPE", "E_CASE_OVERLAP", "E_CASE_EFFECT", "E_TOKEN_PATH"]);
 
 export function checkApplicability(iface, tag, ref) {
   const { ref: r } = iface.unwrapOpt(ref);
   const p = iface.prim(r);
+  if (iface.chain === "evm" && (tag === "account" || tag === "subaccount")) return `${tag} is an ICRC type; an EVM address needs no tag (it is shown with its EIP-55 checksum, spec section 15)`;
   switch (tag) {
     case "amount": return NUMERIC.has(p) ? null : `amount needs a numeric type, found ${iface.describeType(ref)}`;
     case "timestamp":
-    case "duration": return TIMEISH.has(p) ? null : `${tag} needs nat/int/nat32/nat64/int64, found ${iface.describeType(ref)}`;
+    case "duration": return TIMEISH.has(p) ? null : `${tag} needs ${iface.chain === "evm" ? "uint32 to uint256 or int64 to int256" : "nat/int/nat32/nat64/int64"}, found ${iface.describeType(ref)}`;
     case "account": return iface.isAccount(r) ? null : `account needs record { owner : principal; subaccount : opt blob }, found ${iface.describeType(ref)}`;
     case "subaccount":
-    case "bytes": return iface.isBlob(r) ? null : `${tag} needs blob, found ${iface.describeType(ref)}`;
-    case "text": return p === "text" ? null : `text needs text, found ${iface.describeType(ref)}`;
-    case "range": return NUMERIC.has(p) || p === "text" || iface.node(r).kind === "vec" ? null : `range needs numeric, text or vec, found ${iface.describeType(ref)}`;
+    case "bytes": return iface.isBlob(r) ? null : `${tag} needs ${iface.chain === "evm" ? "bytes or bytesN" : "blob"}, found ${iface.describeType(ref)}`;
+    case "text": return TEXT.has(p) ? null : `text needs ${iface.chain === "evm" ? "string" : "text"}, found ${iface.describeType(ref)}`;
+    case "range": return NUMERIC.has(p) || TEXT.has(p) || iface.node(r).kind === "vec" ? null : `range needs numeric, text or vec, found ${iface.describeType(ref)}`;
     default: return null;
   }
 }
 
+/**
+ * An amount's `token` (spec section 15.9): a path from the arguments of the same function or message to the `address`
+ * of the token the amount is in, through the same array elements as the amount. The reason it is wrong, or null.
+ */
+export function tokenPathError(iface, addr, token) {
+  if (iface.chain !== "evm") return "token names the address of an EVM token; a Candid amount's ledger cannot be named by a field yet (OQ-6)";
+  if (addr.kind !== "arg") return "an amount with a token sits in the arguments of a function or message, where the token's address is";
+  const p = parseRelPath(token);
+  const r = iface.resolveRel(addr.method, "args", token);
+  if (!p || r.error) return `token ${JSON.stringify(token)}: ${r.error ?? "not a relative path"}`;
+  if ((p.index ?? 0) !== addr.index) return `token ${JSON.stringify(token)} is in another argument than the amount`;
+  if (iface.prim(r.ref) !== "address") return `token ${JSON.stringify(token)} is ${iface.describeType(r.ref)}, not an address`;
+  const last = p.segs.findLastIndex((s) => s.kind === "elem");
+  const same = (a, b) => a.kind === b.kind && (a.kind === "elem" || a.id === b.id);
+  if (last >= 0 && (addr.segs.length <= last || !p.segs.slice(0, last + 1).every((s, i) => same(s, addr.segs[i])))) {
+    return `token ${JSON.stringify(token)} must be in the same array element as the amount: its path up to its last [] must be the amount's`;
+  }
+  return null;
+}
+
 export function checkDynamic(iface, value, want, diag, at) {
   if (!value || typeof value !== "object") return;
   const from = value.from;
@@ -39,17 +72,18 @@ export function checkDynamic(iface, value, want, diag, at) {
   else {
     const p = iface.prim(iface.unwrapOpt(m.results[0]).ref);
     if (want === "numeric" && !NUMERIC.has(p)) diag("error", "E_REF_TYPE", at, `"${from}" returns ${p}, expected a number`);
-    if (want === "text" && p !== "text") diag("error", "E_REF_TYPE", at, `"${from}" returns ${p}, expected text`);
+    if (want === "text" && !TEXT.has(p)) diag("error", "E_REF_TYPE", at, `"${from}" returns ${p}, expected text`);
   }
 }
 
 export function parseTemplate(t) {
   const placeholders = [];
   let depth = 0;
+  let segments = 0;
   for (let i = 0; i < t.length; i++) {
     const c = t[i];
     if ((c === "{" || c === "}" || c === "[" || c === "]") && t[i + 1] === c) { i++; continue; } // escaped
-    if (c === "[") { if (depth) return { error: "nested [ ] segments are not allowed in v0" }; depth = 1; }
+    if (c === "[") { if (depth) return { error: "nested [ ] segments are not allowed in v0" }; depth = 1; segments++; }
     else if (c === "]") { if (!depth) return { error: "unbalanced ]" }; depth = 0; }
     else if (c === "{") {
       const end = t.indexOf("}", i);
@@ -59,7 +93,7 @@ export function parseTemplate(t) {
     } else if (c === "}") return { error: "unbalanced }" };
   }
   if (depth) return { error: "unclosed [" };
-  return { placeholders };
+  return { placeholders, segments };
 }
 
 export function outcomeCoverage(iface, methodName, classes, diag, at, hasDefault) {
@@ -79,3 +113,62 @@ export function outcomeCoverage(iface, methodName, classes, diag, at, hasDefault
   };
   visit(m.results[0], "");
 }
+
+/** The effect a method has without an effect tag (spec 5.3): queries read, updates write irreversibly. */
+export function defaultEffect(mode) {
+  return mode === "query" || mode === "composite_query" ? { kind: "read", irreversible: false } : { kind: "write", irreversible: true };
+}
+
+/** Why an intent or effect at a value address is not on a case of an argument (spec 5.2, D-053), or null. */
+export function caseTargetError(iface, addr, res, tag) {
+  if (addr.kind === "type") return `${tag} sits on a method or on a case of a variant in its arguments, never at a type: address (it can reach several methods)`;
+  if (addr.kind === "result") return `${tag} sits on a method or on a case of a variant in its arguments, not in its results`;
+  if (addr.segs.some((s) => s.kind === "elem")) return `${tag} on a case cannot step into a vector element ([]): one call holds many elements`;
+  if (res.parent?.kind !== "variant") return `${tag} sits on a method or on a case of a variant in its arguments; this address ends on ${res.parent ? "a record field" : "a whole argument"}`;
+  return null;
+}
+
+/**
+ * Walk two segment lists of one method argument side by side. Returns where they part: { kind } of the container at
+ * the first differing step, with the two labels, or null when one is a prefix of the other.
+ */
+function part(iface, start, a, b) {
+  let cur = start;
+  for (let k = 0; k < Math.min(a.length, b.length); k++) {
+    cur = iface.unwrapOpt(cur).ref;
+    const n = iface.node(cur);
+    const x = a[k];
+    const y = b[k];
+    if (x.kind === "elem" || y.kind === "elem") {
+      if (x.kind === y.kind) { cur = n.inner; continue; }
+      return { kind: n.kind };
+    }
+    if (x.id !== y.id) return { kind: n.kind, a: x.label, b: y.label };
+    cur = n.fields.find((f) => f.id === x.id).type;
+  }
+  return null;
+}
+
+/**
+ * A case template's placeholder that selects another case of a variant the case address passes through, so it can
+ * never be present (spec section 6, D-053): the reason, or null. Both paths resolve; `rel` is a method-tuple relpath.
+ */
+export function otherCase(iface, caseAddr, rel) {
+  const p = parseRelPath(rel);
+  const index = p.index ?? 0;
+  if (index !== caseAddr.index) return null;
+  const m = iface.methods.get(caseAddr.method);
+  const at = part(iface, m.args[index], caseAddr.segs, p.segs);
+  return at?.kind === "variant" ? `selects case "${at.b}" of a variant where this intent's case takes "${at.a}", so it is never present` : null;
+}
+
+/**
+ * Whether one call can take two tagged cases of one method (spec 5.2, D-053): the reason, or null when they exclude
+ * each other (they part at a variant) or nest.
+ */
+export function overlap(iface, a, b) {
+  if (a.index !== b.index) return "they sit in different arguments";
+  const m = iface.methods.get(a.method);
+  const at = part(iface, m.args[a.index], a.segs, b.segs);
+  return at && at.kind !== "variant" ? "their paths part at a record field" : null;
+}

package/src/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * candid-profile resolve (<service.did> | --envelope <file>) [--profile p.json ...] [--packs] [--packs-dir dir]
+ * candid-profile resolve (<service.did> | --envelope <file> | --abi <file>) [--profile p.json ...] [--packs] [--packs-dir dir]
  *
  * Prints the resolved form (docs/profile-v0.md section 10) on stdout and a summary on stderr.
  * Exit code: 0 when no diagnostic is an error, 1 when one is (the resolved form is still printed when the service
@@ -13,9 +13,12 @@ import { resolveService } from "./resolve.mjs";
 
 export const USAGE = `usage: candid-profile resolve <service.did> [options] > resolved.json
        candid-profile resolve --envelope <file> [options] > resolved.json
+       candid-profile resolve --abi <file> [options] > resolved.json
 
   --envelope <file>   the service's candid-core ContractEnvelope (as \`candid-core-cli gen\` writes it), instead of
                       compiling a .did here
+  --abi <file>        an EVM contract's ABI, a JSON array of human-readable fragments or JSON ABI entries
+                      (experimental, spec section 15)
   --profile <file>    a profile to apply (repeatable). A pack given this way must match the service.
   --packs             try every pack in the packs directory; apply those that match
   --packs-dir <dir>   packs directory (default: the standard packs this package ships)
@@ -27,7 +30,7 @@ export const USAGE = `usage: candid-profile resolve <service.did> [options] > re
 class UsageError extends Error {}
 
 function parseArgs(argv) {
-  const opts = { did: null, envelope: null, profiles: [], packs: false, packsDir: DEFAULT_PACKS_DIR, verbose: false, quiet: false, help: false };
+  const opts = { did: null, envelope: null, abi: null, profiles: [], packs: false, packsDir: DEFAULT_PACKS_DIR, verbose: false, quiet: false, help: false };
   const args = [...argv];
   const value = (name, inline) => {
     if (inline !== undefined) return inline;
@@ -40,6 +43,7 @@ function parseArgs(argv) {
     const [flag, inline] = a.startsWith("--") && a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : [a, undefined];
     if (flag === "--profile") opts.profiles.push(value(flag, inline));
     else if (flag === "--envelope") opts.envelope = value(flag, inline);
+    else if (flag === "--abi") opts.abi = value(flag, inline);
     else if (flag === "--packs") opts.packs = true;
     else if (flag === "--packs-dir") opts.packsDir = value(flag, inline);
     else if (flag === "--verbose") opts.verbose = true;
@@ -73,10 +77,12 @@ export async function main(argv, io) {
     if (command !== "resolve") throw new UsageError(`unknown command ${command}`);
     const opts = parseArgs(rest);
     if (opts.help) { err(USAGE.trimEnd()); return 0; }
-    if (opts.did && opts.envelope) throw new UsageError("give <service.did> or --envelope, not both");
-    if (!opts.did && !opts.envelope) throw new UsageError("missing <service.did> (or --envelope <file>)");
+    const given = [opts.did, opts.envelope, opts.abi].filter((x) => x !== null).length;
+    if (given > 1) throw new UsageError("give only one of <service.did>, --envelope and --abi");
+    if (given === 0) throw new UsageError("missing <service.did> (or --envelope <file>, or --abi <file>)");
     const input = {};
     if (opts.envelope) input.envelope = await readJsonFile(opts.envelope, "envelope");
+    else if (opts.abi) input.abi = await readJsonFile(opts.abi, "ABI");
     else {
       try { input.did = await readFile(opts.did, "utf8"); } catch (e) { throw new UsageError(`cannot read ${opts.did}: ${e.message}`); }
     }
@@ -92,7 +98,7 @@ export async function main(argv, io) {
       for (const p of found) packs.push({ doc: p.doc, label: path.relative(process.cwd(), p.file) });
     }
 
-    const r = await resolveService({ ...input, didLabel: opts.did ?? opts.envelope, validateSchema, profiles, packs });
+    const r = await resolveService({ ...input, didLabel: opts.did ?? opts.envelope ?? opts.abi, validateSchema, profiles, packs });
     if (r.resolved) io.stdout.write(`${JSON.stringify(r.resolved, null, 2)}\n`);
     if (!opts.quiet) summary(r, opts, err);
     return r.ok ? 0 : 1;
@@ -104,7 +110,7 @@ export async function main(argv, io) {
 
 function summary(r, opts, err) {
   const count = (s) => r.diagnostics.filter((d) => d.severity === s).length;
-  if (r.resolved) err(`candid-profile: ${opts.did ?? opts.envelope}  ${r.resolved.interface_id}  [${Object.keys(r.resolved.methods).length} methods]`);
+  if (r.resolved) err(`candid-profile: ${opts.did ?? opts.envelope ?? opts.abi}  ${r.resolved.interface_id}  [${Object.keys(r.resolved.methods).length} methods]`);
   for (const p of r.profiles) err(`  ${p.status.padEnd(11)} ${String(p.name).padEnd(16)} ${String(p.origin ?? "?").padEnd(12)} ${p.profile_id ?? ""}`);
   err(`  ${count("error")} error, ${count("warning")} warning, ${count("info")} info`);
   for (const d of r.diagnostics) {

package/src/evm.d.mts

@@ -0,0 +1,101 @@
+// Types for @meantjs/profile/evm: the EVM helpers of spec section 15 (experimental), with no dependency, for a
+// browser bundle. Hand-written; the source is src/evm.mjs, src/abi.mjs and src/keccak.mjs.
+// test/types.test.mjs keeps the declared names equal to the runtime exports.
+
+/** An ABI type: `kind` is uint, int, address, bool, string, bytes, fixedbytes, array or tuple. */
+export type AbiType =
+  | { kind: "uint" | "int"; bits: number }
+  | { kind: "address" | "bool" | "string" | "bytes" }
+  | { kind: "fixedbytes"; size: number }
+  | { kind: "array"; element: AbiType; length: number | null }
+  | { kind: "tuple"; components: AbiParam[] };
+/** A parameter, output or tuple component; `name` is null when it has none. */
+export interface AbiParam {
+  name: string | null;
+  type: AbiType;
+}
+/** A function read from an ABI. */
+export interface AbiFunction {
+  name: string;
+  inputs: AbiParam[];
+  outputs: AbiParam[];
+  stateMutability: "pure" | "view" | "nonpayable" | "payable";
+  /** `transfer(address to,uint256 value)`: the ERC-7730 key, and a resolved form's `signature`. */
+  signature: string;
+  /** `transfer(address,uint256)`: what the selector hashes. */
+  typeSignature: string;
+  /** `0xa9059cbb` */
+  selector: string;
+  /** `function transfer(address to,uint256 value) returns (bool)` */
+  canonical: string;
+  /** Where it was read (`abi[3]`); parseSignature leaves it out. */
+  at?: string;
+}
+/** A decoded or encodable value: decimal strings (or bigints) for integers, EIP-55 text for addresses, Uint8Array for bytes. */
+export type AbiValue = string | bigint | boolean | Uint8Array | AbiValue[] | { [key: string]: AbiValue };
+export interface AbiLimits {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxElements?: number;
+}
+/** Every failure of the ABI helpers: E_ABI (a fragment), E_ABI_ENCODE, E_ABI_DECODE, E_EIP712, E_ADDRESS or E_ADDRESS_CHECKSUM. */
+export declare class AbiError extends Error {
+  constructor(code: string, message: string);
+  name: "AbiError";
+  code: string;
+}
+export interface TypedData {
+  domain: Record<string, unknown>;
+  types: Record<string, { name: string; type: string }[]>;
+  primaryType: string;
+  message: Record<string, unknown>;
+}
+
+/** Keccak-256 (Ethereum's, not NIST SHA3-256) of bytes or of a string's UTF-8 bytes. */
+export function keccak256(input: Uint8Array | string): Uint8Array;
+/** Keccak-256 as 64 lowercase hex digits, without `0x`. */
+export function keccak256Hex(input: Uint8Array | string): string;
+/** RFC 8785 canonical JSON. */
+export function jcs(value: unknown): string;
+export const DEFAULT_ABI_LIMITS: Readonly<Required<AbiLimits>>;
+/** Read an ABI (human-readable fragments or JSON ABI entries); only functions are read. Problems are listed, not thrown. */
+export function parseAbi(entries: unknown, label?: string): { functions: AbiFunction[]; errors: { at: string; message: string }[] };
+/** One function from its named signature, as a resolved form carries it. Throws AbiError. */
+export function parseSignature(signature: string, where?: string): AbiFunction;
+/**
+ * `candid-profile:evm-abi:v0:sha256:…`: SHA-256 over the JCS array of the canonical fragments and, when given EIP-712
+ * types, one `struct Name(type member,…)` line per type, sorted.
+ */
+export function abiInterfaceId(functions: readonly AbiFunction[], types?: Eip712Types): string;
+export function canonicalFragment(f: Pick<AbiFunction, "name" | "inputs" | "outputs" | "stateMutability">): string;
+export function namedSignature(f: Pick<AbiFunction, "name" | "inputs">): string;
+export function typeSignature(f: Pick<AbiFunction, "name" | "inputs">): string;
+export function selectorOf(f: Pick<AbiFunction, "name" | "inputs">): string;
+/** Canonical type text; with `names`, tuple components keep their names. */
+export function typeString(type: AbiType, names?: boolean): string;
+/** A tuple component's key in values and resolved forms: its name, else `#` and its position. */
+export function componentKey(param: AbiParam, index: number): string;
+/** ABI-encode a parameter list's values, keyed like a tuple. Throws AbiError (E_ABI_ENCODE). */
+export function encodeParams(params: readonly AbiParam[], values: Record<string, AbiValue>): Uint8Array;
+/** The selector followed by the encoded parameters. */
+export function encodeCall(f: AbiFunction, values: Record<string, AbiValue>): Uint8Array;
+/** Decode strictly: the bytes must be the canonical encoding of the values read. Throws AbiError (E_ABI_DECODE). */
+export function decodeParams(params: readonly AbiParam[], data: Uint8Array, limits?: AbiLimits): Record<string, AbiValue>;
+/** The EIP-55 checksummed form of `0x` and 40 hex digits. */
+export function toChecksumAddress(address: string): string;
+/** Read an address: mixed case must match its EIP-55 checksum. Returns the checksummed form. */
+export function readAddress(text: string): string;
+/** The EIP-712 digest a signer signs, as `0x` and 64 hex digits. */
+export function typedDataDigest(typed: TypedData): string;
+/** EIP-712 struct types: struct name to its members, in order. */
+export type Eip712Types = Record<string, { name: string; type: string }[]>;
+/**
+ * Read EIP-712 struct types (spec section 15.9): identifier names that are not ABI types, unique member names,
+ * canonical member types (`uint256`, never `uint`) or structs of the same map, and no struct that contains itself.
+ * Problems are listed, not thrown; `types` keeps the structs that read.
+ */
+export function parseEip712Types(types: unknown, label?: string): { types: Eip712Types; errors: { at: string; message: string }[] };
+/** EIP-712 `encodeType`: the struct with its members, then the structs it refers to, sorted by name. Throws AbiError (E_EIP712). */
+export function encodeType(types: Eip712Types, primary: string): string;
+/** EIP-712 `typeHash`: the Keccak-256 of `encodeType`, as `0x` and 64 hex digits. */
+export function eip712TypeHash(types: Eip712Types, primary: string): string;

package/src/evm.mjs

@@ -0,0 +1,32 @@
+/**
+ * `@meantjs/profile/evm`: the EVM helpers of spec section 15 (D-054), browser-safe and without dependencies.
+ * Keccak-256, ABI fragments (reading, canonical text, selectors, the interface identity), a strict ABI codec, EIP-55
+ * addresses, EIP-712 types (section 15.9: reading them, encodeType, type hashes) and digests. The consent package
+ * builds calldata display, typed-message display and the ERC-7730 export on them.
+ *
+ * test/evm.test.mjs checks the vectors; test/address-entry.test.mjs keeps this entry free of node:* imports.
+ */
+export { keccak256, keccak256Hex } from "./keccak.mjs";
+export {
+  AbiError,
+  DEFAULT_ABI_LIMITS,
+  abiInterfaceId,
+  canonicalFragment,
+  componentKey,
+  decodeParams,
+  eip712TypeHash,
+  encodeCall,
+  encodeParams,
+  encodeType,
+  namedSignature,
+  parseAbi,
+  parseEip712Types,
+  parseSignature,
+  readAddress,
+  selectorOf,
+  toChecksumAddress,
+  typeSignature,
+  typeString,
+  typedDataDigest,
+} from "./abi.mjs";
+export { jcs } from "./util.mjs";