@meantjs/profile 0.0.0-stage → 0.2.0

package/src/browser.mjs

@@ -0,0 +1,52 @@
+/**
+ * `@meantjs/profile/browser`: the resolver without Node built-ins, for a browser bundle. The same functions as
+ * the main entry, except the ones that read files (`loadPacks`, the CLI, the default paths): the schema and the
+ * standard packs come in as the data this package ships, and `createSchemaValidator` takes a document, never a
+ * path. The Candid compiler is the `@candid-core/cli` wasm; it initializes itself on first use (fetched next to the
+ * module), or call `initCompiler(urlOrBytes)` first when a bundler moves the wasm file.
+ *
+ * test/browser-entry.test.mjs keeps the module graph free of node:* imports and checks the data against data/.
+ */
+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 { compileSchema } from "./schema-core.mjs";
+
+export { init as initCompiler } from "@candid-core/cli";
+export { idlHash, jcs, profileId } from "./util.mjs";
+export { parseAddress, parseRelPath } from "./address.mjs";
+export { Iface } from "./iface.mjs";
+export { TagIndex, LayeredTags, positions } from "./tags.mjs";
+export { schemaDiagnostics } from "./schema-core.mjs";
+export { compileInterface, interfaceFromEnvelope } from "./compile.mjs";
+export { validateProfile } from "./validate.mjs";
+export { resolveService } from "./resolve.mjs";
+export { matchPack } from "./pack-match.mjs";
+export { matchService, typeSubtype, SubtypeChecker } from "./subtype.mjs";
+export { analyzeProfiles, LAYERS } from "./analyze.mjs";
+export { resolvedForm, buildTree } from "./resolved.mjs";
+export { profileFromDocAttributes, DOC_ATTRIBUTES_VERSION } from "./doc-annotations.mjs";
+export { readServedProfile, SERVED_SECTION, SERVED_METADATA, SERVED_MAX_BYTES } from "./served.mjs";
+
+/** 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. */
+export const STANDARD_PACKS = Object.freeze([
+  { file: "erc20.profile.json", doc: erc20 },
+  { file: "icrc1.profile.json", doc: icrc1 },
+  { file: "icrc2.profile.json", doc: icrc2 },
+]);
+
+/**
+ * The validate function for the profile schema. The schema this package ships (the default, or any document equal to
+ * it) is compiled ahead of time and generates no code at run time, so it needs no 'unsafe-eval' in a page's
+ * Content-Security-Policy. Any other document is compiled by ajv with `new Function`, which does.
+ *
+ * @param doc the schema document (default: the copy this package ships)
+ */
+export async function createSchemaValidator(doc = schema) {
+  if (typeof doc === "string") throw new TypeError("createSchemaValidator: the browser entry takes the schema document, not a path");
+  return compileSchema(doc);
+}

package/src/checks.mjs

@@ -0,0 +1,154 @@
+/**
+ * Per-annotation semantic checks (spec sections 3 to 6). Moved verbatim from scripts/validate.mjs.
+ */
+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", "E_CASE_OVERLAP", "E_CASE_EFFECT"]);
+
+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 ${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 ${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;
+  }
+}
+
+export function checkDynamic(iface, value, want, diag, at) {
+  if (!value || typeof value !== "object") return;
+  const from = value.from;
+  if (from === "now" || from === "caller") {
+    if (want !== "any") diag("error", "E_DYNAMIC_KIND", at, `"${from}" is not valid here; expected query:<method> returning ${want}`);
+    return;
+  }
+  const name = from.slice("query:".length);
+  const m = iface.methods.get(name);
+  if (!m) return diag("error", "E_REF_UNRESOLVED", at, `dynamic ref "${from}": no method "${name}" in the interface`);
+  if (m.mode !== "query" && m.mode !== "composite_query") diag("error", "E_REF_NOT_QUERY", at, `dynamic ref "${from}" must be a query method`);
+  if (m.args.length !== 0 || m.results.length !== 1) diag("error", "E_REF_SHAPE", at, `dynamic ref "${from}" must take no arguments and return one value`);
+  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" && !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; segments++; }
+    else if (c === "]") { if (!depth) return { error: "unbalanced ]" }; depth = 0; }
+    else if (c === "{") {
+      const end = t.indexOf("}", i);
+      if (end < 0) return { error: "unclosed {" };
+      placeholders.push({ path: t.slice(i + 1, end), inOptional: depth === 1 });
+      i = end;
+    } else if (c === "}") return { error: "unbalanced }" };
+  }
+  if (depth) return { error: "unclosed [" };
+  return { placeholders, segments };
+}
+
+export function outcomeCoverage(iface, methodName, classes, diag, at, hasDefault) {
+  const m = iface.methods.get(methodName);
+  if (m.results.length !== 1) return;
+  const visit = (ref, prefix) => {
+    const { ref: r } = iface.unwrapOpt(ref);
+    const n = iface.node(r);
+    if (n.kind !== "variant") return;
+    for (const f of n.fields) {
+      const key = `${prefix}${iface.fieldName(r, f.id)}`;
+      if (classes[key]) continue;
+      const inner = iface.node(iface.unwrapOpt(f.type).ref);
+      if (inner.kind === "variant" && Object.keys(classes).some((k) => k.startsWith(`${key}.`))) visit(f.type, `${key}.`);
+      else diag(hasDefault ? "info" : "warning", "W_OUTCOME_UNCLASSIFIED", at, `result case "${key}" has no class${hasDefault ? " (falls back to default)" : ""}`);
+    }
+  };
+  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

@@ -0,0 +1,120 @@
+/**
+ * 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
+ * compiles), 2 for a usage or I/O problem.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createSchemaValidator } from "./schema.mjs";
+import { DEFAULT_PACKS_DIR, loadPacks } from "./packs.mjs";
+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)
+  --verbose           also list info diagnostics on stderr
+  --quiet             no summary on stderr
+  -h, --help          this text
+`;
+
+class UsageError extends Error {}
+
+function parseArgs(argv) {
+  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;
+    const v = args.shift();
+    if (v === undefined || v.startsWith("--")) throw new UsageError(`${name} needs a value`);
+    return v;
+  };
+  while (args.length) {
+    const a = args.shift();
+    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;
+    else if (flag === "--quiet") opts.quiet = true;
+    else if (flag === "-h" || flag === "--help") opts.help = true;
+    else if (a.startsWith("-")) throw new UsageError(`unknown option ${a}`);
+    else if (opts.did === null) opts.did = a;
+    else throw new UsageError(`unexpected argument ${a}`);
+  }
+  return opts;
+}
+
+async function readJsonFile(file, what) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch (e) {
+    throw new UsageError(`cannot read ${what} ${file}: ${e.message}`);
+  }
+}
+
+/**
+ * @param argv  arguments after the program name, starting with the command
+ * @param io    { stdout, stderr } with write(string)
+ * @returns the exit code
+ */
+export async function main(argv, io) {
+  const err = (s) => io.stderr.write(`${s}\n`);
+  try {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "-h" || command === "--help") { err(USAGE.trimEnd()); return command === undefined ? 2 : 0; }
+    if (command !== "resolve") throw new UsageError(`unknown command ${command}`);
+    const opts = parseArgs(rest);
+    if (opts.help) { err(USAGE.trimEnd()); return 0; }
+    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}`); }
+    }
+
+    const validateSchema = await createSchemaValidator();
+    const profiles = [];
+    for (const f of opts.profiles) profiles.push({ doc: await readJsonFile(f, "profile"), label: f });
+    const packs = [];
+    if (opts.packs) {
+      let found;
+      try { found = await loadPacks(opts.packsDir); } catch (e) { throw new UsageError(`cannot read packs from ${opts.packsDir}: ${e.message}`); }
+      if (!found.length) throw new UsageError(`no packs (*.profile.json of kind pack) in ${opts.packsDir}`);
+      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 ?? 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;
+  } catch (e) {
+    if (e instanceof UsageError) { err(`candid-profile: ${e.message}`); err(USAGE.trimEnd()); return 2; }
+    throw e;
+  }
+}
+
+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 ?? 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) {
+    if (d.severity === "info" && !opts.verbose) continue;
+    err(`  ${d.severity.padEnd(7)} ${d.code.padEnd(26)} ${d.profile ? `[${d.profile}] ` : ""}${d.at}  ${d.message}`);
+  }
+}

package/src/compile.mjs

@@ -0,0 +1,304 @@
+import { didToContract } from "@candid-core/cli";
+import { Iface } from "./iface.mjs";
+import { U32_MAX, idlHash } from "./idl.mjs";
+
+/**
+ * Compile Candid source text to an Iface with @candid-core/cli (wasm).
+ * @returns { iface } or { failure: [candid-core diagnostics] }
+ */
+export async function compileInterface(source, label = "interface") {
+  const env = await didToContract(source);
+  if (env.ok === false) return { failure: env.diagnostics };
+  return { iface: new Iface(env, label) };
+}
+
+/**
+ * An Iface from a candid-core ContractEnvelope another tool already wrote (the one `candid-core-cli gen` writes next
+ * to a generated module), without compiling the .did again. The envelope is checked for the shape the resolver reads;
+ * its identities are taken as written (nothing here can recompute them).
+ * @returns { iface } or { failure: [{ code, message }] }
+ */
+export function interfaceFromEnvelope(envelope, label = "interface") {
+  const fail = (message) => ({ failure: [{ code: "invalid_envelope", message }] });
+  if (envelope === null || typeof envelope !== "object" || Array.isArray(envelope)) return fail("not a JSON object");
+  const c = envelope.contract;
+  if (c === null || typeof c !== "object" || Array.isArray(c)) return fail("no `contract` object (is this a candid-core ContractEnvelope?)");
+  if (c.format !== "candid-core") return fail(`contract.format is ${JSON.stringify(c.format)}, expected "candid-core"`);
+  if (c.format_version !== 1) return fail(`contract.format_version is ${JSON.stringify(c.format_version)}, this resolver reads version 1`);
+  const id = c.identities?.interface;
+  if (typeof id !== "string" || !/^candid-core:interface:v1:sha256:[0-9a-f]{64}$/.test(id)) return fail("no contract.identities.interface of the form candid-core:interface:v1:sha256:<64 lowercase hex>");
+  // the Candid semantics and the canonical interning this resolver implements; the interface id covers both markers
+  if (c.semantics_profile !== "candid-1") return fail(`contract.semantics_profile is ${JSON.stringify(c.semantics_profile)}, this resolver implements "candid-1"`);
+  if (c.canonicalization_profile !== "candid-core-canon-1") return fail(`contract.canonicalization_profile is ${JSON.stringify(c.canonicalization_profile)}, this resolver implements "candid-core-canon-1"`);
+  if (!Array.isArray(c.types) || !Array.isArray(c.declarations)) return fail("contract.types and contract.declarations must be arrays");
+  const names = envelope.extensions?.["org.candid-core.field-names/v1"];
+  if (!Array.isArray(names)) return fail("no extensions[\"org.candid-core.field-names/v1\"] array: without it every field and case would be renamed to its id");
+  const bad = badGraph(c, names);
+  if (bad) return fail(bad);
+  try {
+    return { iface: new Iface(envelope, label) };
+  } catch (e) {
+    return fail(`the contract graph cannot be read: ${e.message}`);
+  }
+}
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const KINDS = new Set(["primitive", "opt", "vec", "record", "variant", "func", "service", "class"]);
+const MODES = new Set(["update", "query", "composite_query", "oneway"]);
+const PRIMITIVES = new Set([
+  "nat", "nat8", "nat16", "nat32", "nat64", "int", "int8", "int16", "int32", "int64",
+  "float32", "float64", "bool", "text", "null", "reserved", "empty", "principal",
+]);
+
+/**
+ * The first thing in the contract graph this resolver cannot read, as a readable sentence; null if none. Checked
+ * here, before anything walks the graph, so a malformed envelope is an E_ENVELOPE diagnostic and never a throw or a
+ * loop further in: every reference is an index into `types`, declaration names are distinct strings, every node has the fields its kind needs, a method is
+ * a `func` with a mode (a oneway one with no results) and an id that is its name's hash, declarations are named by
+ * Candid identifiers, a class appears only as the actor, an actor names a `service` or `class`, every node is reached from the actor
+ * or a declaration, no `opt` contains only itself, and every name in the field-names
+ * table is the name of a field its container has, with that id.
+ */
+function badGraph(c, names) {
+  const n = c.types.length;
+  const ok = (r) => Number.isInteger(r) && r >= 0 && r < n;
+  const isKind = (r, kind) => ok(r) && c.types[r]?.kind === kind;
+  const refs = (a) => Array.isArray(a) && a.every(ok);
+  const declNames = new Set();
+  for (const [i, d] of c.declarations.entries()) {
+    if (!ok(d?.type)) return `dangling type reference: declarations[${i}].type`;
+    if (typeof d.name !== "string" || !IDENT.test(d.name)) return `declarations[${i}] needs a Candid identifier as its name, got ${JSON.stringify(d.name)}`;
+    if (declNames.has(d.name)) return `declaration ${JSON.stringify(d.name)} is listed twice`;
+    declNames.add(d.name);
+  }
+  for (const [i, t] of c.types.entries()) {
+    const at = `types[${i}]`;
+    if (t === null || typeof t !== "object" || !KINDS.has(t.kind)) return `${at} has no known kind`;
+    switch (t.kind) {
+      case "primitive":
+        if (!PRIMITIVES.has(t.primitive)) return `${at}: ${JSON.stringify(t.primitive)} is not a Candid primitive`;
+        break;
+      case "opt":
+      case "vec":
+        if (!ok(t.inner)) return `dangling type reference: ${at}.inner`;
+        break;
+      case "record":
+      case "variant": {
+        if (!Array.isArray(t.fields)) return `${at}: a ${t.kind} needs fields`;
+        const ids = new Set();
+        for (const f of t.fields) {
+          if (!ok(f?.type)) return `dangling type reference: ${at}.fields`;
+          if (!Number.isInteger(f.id) || f.id < 0 || f.id > U32_MAX || ids.has(f.id)) return `${at}: field ids must be distinct u32 values`;
+          ids.add(f.id);
+        }
+        break;
+      }
+      case "func":
+        if (!refs(t.args) || !refs(t.results)) return `dangling type reference: ${at}.args or .results`;
+        if (!MODES.has(t.mode)) return `${at}: a func needs a mode (update, query, composite_query or oneway), got ${JSON.stringify(t.mode)}`;
+        if (t.mode === "oneway" && t.results.length > 0) return `${at}: a oneway func has no results`;
+        break;
+      case "service":
+        if (!Array.isArray(t.methods)) return `${at}: a service needs methods`;
+        const methodNames = new Set();
+        for (const m of t.methods) {
+          if (typeof m?.name !== "string" || m.name === "") return `${at}: every method needs a non-empty name`;
+          if (!Number.isInteger(m.id) || m.id < 0 || m.id > U32_MAX || m.id !== idlHash(m.name)) return `${at}: method ${JSON.stringify(m.name)} needs the id ${idlHash(m.name)} (the hash of its name), got ${JSON.stringify(m.id)}`;
+          if (methodNames.has(m.name)) return `${at}: method ${JSON.stringify(m.name)} is listed twice`;
+          methodNames.add(m.name);
+          if (!isKind(m.function, "func")) return `${at}: method ${JSON.stringify(m.name)} does not name a func type`;
+        }
+        break;
+      case "class":
+        if (!refs(t.init) || !isKind(t.service, "service")) return `${at}: a class needs init arguments and a service type`;
+        break;
+    }
+  }
+  // each opt is walked once: a chain already known to end in a non-opt is not walked again (linear in the graph)
+  const state = new Uint8Array(n); // 0 unseen, 1 on the chain being walked, 2 ends in a non-opt
+  for (const [i, t] of c.types.entries()) {
+    if (t.kind !== "opt" || state[i] !== 0) continue;
+    const chain = [];
+    let r = i;
+    for (; c.types[r].kind === "opt" && state[r] === 0; r = c.types[r].inner) {
+      state[r] = 1;
+      chain.push(r);
+    }
+    if (c.types[r].kind === "opt" && state[r] === 1) return `types[${i}]: an opt that contains only opts of itself`;
+    for (const q of chain) state[q] = 2;
+  }
+  // A class is valid only as the actor (contract-graph.md, validation checklist 5): no declaration or type refers to one.
+  const isClass = (r) => c.types[r].kind === "class";
+  if (c.declarations.some((d) => isClass(d.type))) return "a declaration names a class: a class is only the actor";
+  for (const [i, t] of c.types.entries()) {
+    if (childrenOf(t).some(isClass)) return `types[${i}] refers to a class: a class is only the actor`;
+  }
+  const a = c.actor;
+  if (a === null || typeof a !== "object") return "no actor: the envelope describes no service";
+  if (a.kind === "service" ? !isKind(a.service, "service") : a.kind === "class" ? !isKind(a.class, "class") : true) {
+    return "actor must name a service or a class type";
+  }
+  // Every node is reachable from the actor or a declaration (contract-graph.md, validation checklist 6): nothing the
+  // interface id does not cover rides along in an envelope this resolver accepts.
+  const reached = new Uint8Array(n);
+  const stack = [a.kind === "service" ? a.service : a.class, ...c.declarations.map((d) => d.type)];
+  for (const r of stack) reached[r] = 1;
+  while (stack.length > 0) {
+    for (const r of childrenOf(c.types[stack.pop()])) {
+      if (reached[r] === 0) {
+        reached[r] = 1;
+        stack.push(r);
+      }
+    }
+  }
+  const stray = reached.indexOf(0);
+  if (stray !== -1) return `types[${stray}] is reached from neither the actor nor a declaration`;
+  const named = new Set();
+  for (const [k, e] of names.entries()) {
+    if (!Array.isArray(e) || e.length !== 3) return `field-names entry ${k} is not [container, id, name]`;
+    const [container, id, name] = e;
+    const t = ok(container) ? c.types[container] : undefined;
+    if (t?.kind !== "record" && t?.kind !== "variant") return `field-names entry ${k} names no record or variant`;
+    if (typeof name !== "string" || !t.fields.some((f) => f.id === id) || idlHash(name) !== id) return `field-names entry ${k}: ${JSON.stringify(name)} is not the name of field ${id} of types[${container}]`;
+    // two names for one field (they can share a hash) would leave the name to the order of the entries
+    if (named.has(`${container}:${id}`)) return `field-names entry ${k} names field ${id} of types[${container}] a second time`;
+    named.add(`${container}:${id}`);
+  }
+  const twin = duplicateNodes(c.types);
+  if (twin) return `types[${twin[0]}] and types[${twin[1]}] are the same type: the graph is not interned as candid-core-canon-1 requires`;
+  // A field with no entry keeps its numeric label (`#n`, spec §3.2 rule 1): candid-core writes none for `1 : nat` or a tuple
+  // field, so a missing entry cannot be told from a numeric label and is not checked.
+  return null;
+}
+
+/**
+ * The references of a node, in a fixed order, reading only the properties its kind has (checked above): another
+ * property on the node, such as `fields` on a primitive, is ignored. Record and variant fields go by id, methods by name.
+ */
+function childrenOf(t) {
+  switch (t.kind) {
+    case "opt": case "vec": return [t.inner];
+    case "record": case "variant": return [...t.fields].sort((a, b) => a.id - b.id).map((f) => f.type);
+    case "func": return [...t.args, ...t.results];
+    case "service": return [...t.methods].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)).map((m) => m.function);
+    case "class": return [...t.init, t.service];
+    default: return [];
+  }
+}
+
+/** What a node is apart from its references: two nodes with equal keys are equal types if their references are. */
+function localKey(t) {
+  switch (t.kind) {
+    case "primitive": return JSON.stringify(["p", t.primitive]);
+    case "record": case "variant": return JSON.stringify([t.kind, t.fields.map((f) => f.id).sort((a, b) => a - b)]);
+    case "func": return JSON.stringify(["f", t.mode, t.args.length, t.results.length]);
+    case "service": return JSON.stringify(["s", t.methods.map((m) => m.name).sort()]);
+    case "class": return JSON.stringify(["c", t.init.length]);
+    default: return JSON.stringify([t.kind]);
+  }
+}
+
+/**
+ * Two indexes holding structurally equal types (recursion included), or null. candid-core-canon-1 interns every type
+ * once, and the resolver relies on it: an alias reaches a method position only through an equal reference (profile
+ * spec 3.2 rule 7). Equal types are the states a DFA minimization merges, so this is Hopcroft's partition refinement
+ * (O(k n log n) for n nodes with at most k references each): start from blocks of equal `localKey`, and split a block whenever its nodes' j-th
+ * references fall in different blocks, always queueing the smaller half. Two nodes still sharing a block are equal.
+ */
+function duplicateNodes(types) {
+  const n = types.length;
+  const succ = types.map(childrenOf);
+  const preds = types.map(() => new Map()); // preds[t].get(j): the nodes whose j-th reference is t
+  for (const [s, refs] of succ.entries()) {
+    for (const [j, t] of refs.entries()) {
+      const list = preds[t].get(j);
+      if (list) list.push(s);
+      else preds[t].set(j, [s]);
+    }
+  }
+  // blocks are segments [start, end) of `elems`; `where[i]` is i's index in `elems`
+  const elems = new Int32Array(n);
+  const where = new Int32Array(n);
+  const block = new Int32Array(n);
+  const start = [];
+  const end = [];
+  const groups = new Map();
+  for (const [i, t] of types.entries()) {
+    const k = localKey(t);
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k).push(i);
+  }
+  let fill = 0;
+  for (const members of groups.values()) {
+    start.push(fill);
+    for (const i of members) {
+      block[i] = start.length - 1;
+      where[i] = fill;
+      elems[fill++] = i;
+    }
+    end.push(fill);
+  }
+  const queued = new Set();
+  const work = [];
+  const queue = (b) => {
+    for (let x = start[b]; x < end[b]; x++) {
+      for (const j of preds[elems[x]].keys()) {
+        const key = `${b},${j}`;
+        if (!queued.has(key)) {
+          queued.add(key);
+          work.push([b, j]);
+        }
+      }
+    }
+  };
+  for (let b = 0; b < start.length; b++) queue(b);
+  const marked = [];
+  while (work.length > 0) {
+    const [b, j] = work.pop();
+    queued.delete(`${b},${j}`);
+    const touched = [];
+    // the splitter's members are copied first: marking moves nodes inside their blocks, the splitter's own included
+    for (const t of elems.slice(start[b], end[b])) {
+      for (const s of preds[t].get(j) ?? []) {
+        // s has one j-th reference, so it is marked at most once per splitter; marked nodes move to their block's front
+        const y = block[s];
+        if (marked[y] === undefined || marked[y] === 0) {
+          marked[y] = 0;
+          touched.push(y);
+        }
+        const to = start[y] + marked[y]++;
+        const other = elems[to];
+        elems[where[s]] = other;
+        where[other] = where[s];
+        elems[to] = s;
+        where[s] = to;
+      }
+    }
+    for (const y of touched) {
+      const m = marked[y];
+      marked[y] = 0;
+      const size = end[y] - start[y];
+      if (m === size) continue;
+      // the smaller part becomes the new block z; y keeps the rest (and any of its splitters already queued)
+      const z = start.length;
+      if (m <= size - m) {
+        start.push(start[y]);
+        end.push(start[y] + m);
+        start[y] += m;
+      } else {
+        start.push(start[y] + m);
+        end.push(end[y]);
+        end[y] = start[y] + m;
+      }
+      for (let x = start[z]; x < end[z]; x++) block[elems[x]] = z;
+      queue(z);
+    }
+  }
+  for (let b = 0; b < start.length; b++) {
+    if (end[b] - start[b] > 1) {
+      const pair = [elems[start[b]], elems[start[b] + 1]].sort((p, q) => p - q);
+      return pair;
+    }
+  }
+  return null;
+}