@meantjs/profile 0.0.0-stage → 0.2.0

package/src/address.d.mts

@@ -0,0 +1,30 @@
+// Types for @meantjs/profile/address: the address grammar (spec section 3) and the Candid field-name hash, with
+// no dependency, for a browser bundle. Hand-written; the source is src/address.mjs and src/idl.mjs.
+// test/types.test.mjs keeps the declared names equal to the runtime exports.
+
+export interface PathSegment {
+  kind: "field" | "elem";
+  /** The field name, or `#<id>` for a numeric id. */
+  label?: string;
+  id?: number;
+}
+
+export type Address =
+  | { kind: "type"; decl: string; segs: PathSegment[] }
+  | { kind: "arg" | "result"; method: string; index: number; segs: PathSegment[] }
+  | { kind: "method"; method: string; segs: [] };
+
+/** The largest Candid field id. */
+export const U32_MAX: 4294967295;
+/** The Candid field-name hash. */
+export function idlHash(label: string): number;
+/** `.amount.e8s`, `.#5`, `[]` to segments; null when the path does not parse. */
+export function parsePath(path: string): PathSegment[] | null;
+/** `send(0).to`, `balance->(0)`, `type:Tokens.e8s` or a method name; null when the address does not parse. */
+export function parseAddress(at: string): Address | null;
+/** A path relative to a method: `(0).to.owner`, `to.owner` or `Ok`; `index` is null without `(n)`. */
+export function parseRelPath(rel: string): { index: number | null; segs: PathSegment[] } | null;
+/** The resolver's key of a method position. */
+export function methodKey(method: string, side: "arg" | "res", index: number, segs: PathSegment[]): string;
+/** The resolver's key of a `type:` edge. */
+export function edgeKey(parent: { container: number; kind: string; id?: number }): string;

package/src/address.mjs

@@ -0,0 +1,62 @@
+/**
+ * Address grammar (spec section 3). Addresses are compared by their resolved form, never as strings (D-011):
+ *   method positions  -> "m:<method>|<arg|res>|<index>|<id>/<id>/[]..."
+ *   type: edges       -> "e:<container>:<id or []>"   (applies wherever the edge is reached)
+ *   type: whole decl  -> "n:<node>"                   (records and variants only, E_TYPE_NODE otherwise)
+ *
+ * Browser-safe: this module and idl.mjs import nothing else, and the package exports them as
+ * `@meantjs/profile/address` (test/address-entry.test.mjs keeps it that way).
+ */
+import { idlHash, U32_MAX } from "./idl.mjs";
+
+export { idlHash, U32_MAX };
+
+const IDENT = "[A-Za-z_][A-Za-z0-9_]*";
+const NUMID = "#(?:0|[1-9][0-9]{0,9})";
+const SEG_RE = new RegExp(`\\.(${IDENT}|${NUMID})|\\[\\]`, "y");
+
+export function parsePath(str) {
+  const segs = [];
+  let i = 0;
+  while (i < str.length) {
+    SEG_RE.lastIndex = i;
+    const m = SEG_RE.exec(str);
+    if (!m) return null;
+    if (m[0] === "[]") segs.push({ kind: "elem" });
+    else if (m[1].startsWith("#")) {
+      const id = Number(m[1].slice(1));
+      if (id > U32_MAX) return null;
+      segs.push({ kind: "field", label: m[1], id });
+    } else segs.push({ kind: "field", label: m[1], id: idlHash(m[1]) });
+    i = SEG_RE.lastIndex;
+  }
+  return segs;
+}
+
+export function parseAddress(at) {
+  let m = new RegExp(`^type:(${IDENT})(.*)$`).exec(at);
+  if (m) {
+    const segs = parsePath(m[2]);
+    return segs && { kind: "type", decl: m[1], segs };
+  }
+  m = new RegExp(`^(${IDENT})(?:\\((\\d+)\\)|->\\((\\d+)\\))?(.*)$`).exec(at);
+  if (!m) return null;
+  const segs = parsePath(m[4]);
+  if (!segs) return null;
+  if (m[2] !== undefined) return { kind: "arg", method: m[1], index: Number(m[2]), segs };
+  if (m[3] !== undefined) return { kind: "result", method: m[1], index: Number(m[3]), segs };
+  if (segs.length) return null;
+  return { kind: "method", method: m[1], segs: [] };
+}
+
+export function parseRelPath(rel) {
+  const m = /^(?:\((\d+)\))?(.*)$/.exec(rel);
+  let rest = m[2];
+  if (rest && !rest.startsWith(".") && !rest.startsWith("[")) rest = `.${rest}`;
+  const segs = parsePath(rest);
+  return segs && { index: m[1] === undefined ? null : Number(m[1]), segs };
+}
+
+const segKey = (s) => (s.kind === "elem" ? "[]" : String(s.id));
+export const methodKey = (method, side, index, segs) => `m:${method}|${side}|${index}|${segs.map(segKey).join("/")}`;
+export const edgeKey = (parent) => `e:${parent.container}:${parent.kind === "vec" ? "[]" : parent.id}`;

package/src/analyze.mjs

@@ -0,0 +1,344 @@
+/**
+ * The semantic engine: index every annotation of every contributing profile by canonical position, merge the layers
+ * (spec section 8) and run the per-annotation checks. For a single profile this is exactly the old
+ * scripts/validate.mjs `validateFile` core, in the same order, with the same diagnostics.
+ */
+import { parseAddress } from "./address.mjs";
+import { jcs } from "./util.mjs";
+import { TagIndex, LayeredTags, positions } from "./tags.mjs";
+import {
+  NUMERIC, METHOD_TAGS, CASE_TAGS, CONFIRM_KINDS, STALE_CODES, VALUE_CONVERSION_TAGS, EVM_LATER_TAGS,
+  checkApplicability, checkDynamic, parseTemplate, outcomeCoverage, caseTargetError, otherCase, overlap, defaultEffect,
+} from "./checks.mjs";
+
+/** Spec section 8, highest precedence first. */
+export const LAYERS = ["author", "third_party", "pack", "inferred"];
+const rank = (origin) => LAYERS.indexOf(origin);
+
+function buildLayers(entries, keep = () => true) {
+  const byLayer = new Map();
+  for (const e of entries) {
+    if (!keep(e)) continue;
+    const layer = e.item.doc.origin;
+    if (!byLayer.has(layer)) byLayer.set(layer, new TagIndex());
+    byLayer.get(layer).add(e.res.key, e.ann.tag, e.entry);
+  }
+  return new LayeredTags(LAYERS.filter((l) => byLayer.has(l)).map((name) => ({ name, index: byLayer.get(name) })));
+}
+
+/**
+ * @param iface  the interface every address resolves against
+ * @param items  [{ doc, pid, rebinding, apply }]; `apply` marks a pack that matched a service and is applied to it
+ * @param opts.attribute  add `profile` to each diagnostic (multi-profile output)
+ * @returns { diagnostics, layered, ordered, stale }  `ordered` is items by precedence; `stale` the stale items
+ */
+export function analyzeProfiles(iface, items, { attribute = true } = {}) {
+  const diagnostics = [];
+  const ordered = items.map((item) => ({ ...item, diags: [] })).sort((a, b) => rank(a.doc.origin) - rank(b.doc.origin));
+  for (const item of ordered) {
+    item.diag = (severity, code, at, message) => {
+      const d = { severity, code, at, message };
+      if (attribute) d.profile = item.doc.name;
+      diagnostics.push(d);
+      item.diags.push(d);
+    };
+  }
+  const interfaceId = iface.interfaceId;
+
+  for (const item of ordered) {
+    if (item.rebinding) {
+      item.diag("warning", "W_REBOUND", "binds.interface_id", `profile is bound to ${item.doc.binds.interface_id} but the given interface is ${interfaceId}; checking whether every address still resolves`);
+    }
+  }
+
+  // Pass 1: resolve every address and index tags by canonical key, one TagIndex per layer.
+  const seenByLayer = new Map();
+  const entries = [];
+  const meta = new WeakMap(); // tag entry -> { item, at } (kept out of the entry so the resolved form stays unchanged)
+  for (const item of ordered) {
+    const { doc, diag } = item;
+    if (!seenByLayer.has(doc.origin)) seenByLayer.set(doc.origin, new Map());
+    const seen = seenByLayer.get(doc.origin);
+    for (const original of doc.annotations) {
+      let a = original;
+      const at = a.at;
+      const addr = parseAddress(at);
+      if (!addr) { diag("error", "E_ADDR_SYNTAX", at, "address does not parse"); continue; }
+      if (doc.kind === "pack" && addr.kind === "type") { diag("error", "E_PACK_TYPE_REF", at, "packs must use method addresses (declaration names are not standardized)"); continue; }
+      const res = iface.resolve(addr);
+      if (res.error) {
+        // A pack applied to a service that is a narrower subtype (fewer result cases, fewer optional fields) cannot
+        // address what is not there. That is expected, not an error in the pack.
+        if (item.apply) diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `${a.tag}: ${res.error}`);
+        else diag("error", res.code ?? "E_ADDR_UNRESOLVED", at, res.error);
+        continue;
+      }
+      if (addr.kind === "type") {
+        const others = (iface.aliases.get(iface.decls.get(addr.decl)) ?? []).filter((n) => n !== addr.decl);
+        if (others.length) diag("warning", "W_STRUCTURAL_ALIAS", at, `declaration "${addr.decl}" is structurally identical to ${others.map((n) => `"${n}"`).join(", ")}; the tag reaches every one of them`);
+      }
+      const dupKey = `${a.tag}@${res.key}`;
+      if (seen.has(dupKey)) {
+        const prev = seen.get(dupKey);
+        const where = prev.item === item ? `"${prev.a.at}"` : `profile "${prev.item.doc.name}" "${prev.a.at}"`;
+        if (jcs(prev.a.args) === jcs(a.args)) diag("warning", "W_DUPLICATE", at, `duplicate ${a.tag} (same position as ${where})`);
+        else if (prev.item === item) diag("error", "E_CONFLICT", at, `two different ${a.tag} annotations at the same position ("${prev.a.at}" and "${at}")`);
+        else diag("error", "E_CONFLICT", at, `two different ${a.tag} annotations at the same position (profile "${prev.item.doc.name}" "${prev.a.at}" and profile "${doc.name}" "${at}")`);
+        continue;
+      }
+      if (item.apply && a.tag === "outcome" && a.args.classes) {
+        const kept = {};
+        for (const [k, v] of Object.entries(a.args.classes)) {
+          const r = iface.resolveRel(addr.method, "results", k);
+          if (r.error || r.parent?.kind !== "variant") diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `outcome "${k}": ${r.error ?? "not a variant case"}`);
+          else kept[k] = v;
+        }
+        a = { ...a, args: { ...a.args, classes: kept } };
+      }
+      seen.set(dupKey, { a, item });
+      const entry = { args: a.args, origin: doc.origin, profile: doc.name };
+      meta.set(entry, { item, at });
+      entries.push({ item, ann: a, addr, res, entry });
+    }
+  }
+  const tags = buildLayers(entries);
+
+  // Pass 2: per-annotation checks (needs the merged index for stamp lookups).
+  // 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) => {
+    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) {
+    const { item, ann: a, addr, res } = e;
+    const { doc } = item;
+    const diag = !item.apply ? item.diag : (severity, code, at, message) => {
+      if (severity !== "error") return item.diag(severity, code, at, message);
+      dropped.add(e);
+      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") 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);
+        if (r.error) diag("error", "E_ADDR_UNRESOLVED", at, `stamp: ${r.error}`);
+        else {
+          if (iface.node(r.ref).kind !== "opt") diag("warning", "W_STAMP_REQUIRED", at, "stamp field is not optional; the tool layer must always fill it");
+          if (!tags.at(r, iface)?.timestamp) diag("error", "E_STAMP_UNTAGGED", at, `stamp field "${a.args.stamp}" needs a timestamp annotation`);
+        }
+      }
+      if (a.tag === "outcome") {
+        const classes = a.args.classes ?? {}; // left out: every reply is the default's class (spec 5.3, D-049)
+        for (const k of Object.keys(classes)) {
+          const r = iface.resolveRel(methodName, "results", k);
+          if (r.error) diag("error", "E_ADDR_UNRESOLVED", at, `outcome "${k}": ${r.error}`);
+          else if (r.parent?.kind !== "variant") diag("error", "E_OUTCOME_NOT_CASE", at, `outcome "${k}" must select a variant case`);
+        }
+        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") 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;
+        if (m.mode !== "query" && m.mode !== "composite_query" && !replicatedRead) {
+          diag("error", "E_NAMES_MODE", at, `names needs a query, a composite query or a read-only update (D-038); "${methodName}" is ${m.mode}`);
+        }
+        if (m.args.length !== 0) diag("error", "E_NAMES_SHAPE", at, `names needs a method without arguments; "${methodName}" takes ${m.args.length}`);
+        const items = iface.resolveRel(methodName, "results", a.args.items);
+        const vec = items.error ? undefined : iface.unwrapOpt(items.ref).ref;
+        if (items.error) diag("error", "E_ADDR_UNRESOLVED", at, `names.items: ${items.error}`);
+        else if (iface.node(vec).kind !== "vec" || iface.isBlob(vec) || iface.node(iface.unwrapOpt(iface.node(vec).inner).ref).kind !== "record") {
+          diag("error", "E_NAMES_SHAPE", at, `names.items must be a vec of records, found ${iface.describeType(items.ref)}`);
+        } else {
+          const fields = {};
+          for (const k of ["name", "value", "show", "kind"]) {
+            if (a.args[k] === undefined) continue;
+            const r = iface.resolveRel(methodName, "results", `${a.args.items}[].${a.args[k]}`);
+            if (r.error) diag("error", "E_ADDR_UNRESOLVED", at, `names.${k}: ${r.error}`);
+            else fields[k] = r.ref;
+          }
+          if (fields.name !== undefined && iface.prim(iface.unwrapOpt(fields.name).ref) !== "text") {
+            diag("error", "E_NAMES_FIELD", at, `names.name must be text, found ${iface.describeType(fields.name)}`);
+          } else if (fields.name !== undefined && fields.value !== undefined) {
+            const prev = sets.get(a.args.set);
+            if (prev) diag("error", "E_NAMES_SET_DUPLICATE", at, `names set "${a.args.set}" is already declared at "${prev.at}"`);
+            else sets.set(a.args.set, { at, method: methodName, fields });
+          }
+        }
+      }
+      if (a.tag === "list") {
+        for (const [k, side] of [["cursor", "args"], ["next", "results"], ["items", "results"]]) {
+          const r = iface.resolveRel(methodName, side, a.args[k]);
+          if (r.error) diag("error", "E_ADDR_UNRESOLVED", at, `list.${k}: ${r.error}`);
+        }
+      }
+      continue;
+    }
+    if (res.method) {
+      if (a.tag !== "describe") diag("error", "E_TAG_TARGET", at, `${a.tag} is a value tag; address a value, not a method`);
+      continue;
+    }
+    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") {
+      checkDynamic(iface, a.args.decimals, "numeric", diag, at);
+      checkDynamic(iface, a.args.symbol, "text", diag, at);
+    }
+    if (a.tag === "default") {
+      if (a.args.value === "null" && iface.node(res.ref).kind !== "opt") diag("error", "E_DEFAULT_NULL", at, "default null on a non-optional value");
+      if (typeof a.args.value === "object") checkDynamic(iface, a.args.value, "any", diag, at);
+    }
+  }
+
+  // A named position needs its set, and the type of the field that fills it (spec 5.3, D-045).
+  for (const { a, res, diag, at } of named) {
+    const set = sets.get(a.args.set);
+    const by = a.args.by ?? "value";
+    if (!set) { diag("error", "E_NAMED_SET", at, `no names tag declares the set "${a.args.set}"`); continue; }
+    const field = set.fields[by];
+    if (field === undefined) { diag("error", "E_NAMED_SET", at, `names set "${a.args.set}" has no ${by} field`); continue; }
+    if (iface.unwrapOpt(res.ref).ref !== iface.unwrapOpt(field).ref) {
+      diag("error", "E_NAMED_TYPE", at, `named: the position is ${iface.describeType(res.ref)}, but the ${by} of set "${a.args.set}" is ${iface.describeType(field)}`);
+    } else if (iface.prim(iface.unwrapOpt(res.ref).ref) === "text" && tags.at(res, iface)?.text?.args?.pattern === undefined) {
+      diag("warning", "W_NAMED_UNPATTERNED", at, `named text without a text.pattern: every input is looked up as a name first, so a name could stand in for a value (spec 5.3)`);
+    }
+  }
+
+  // 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));
+    for (const e of entries) {
+      if (!e.item.apply || e.ann.tag !== "idempotency" || dropped.has(e)) continue;
+      const r = iface.resolveRel(e.addr.method, "args", e.ann.args.stamp);
+      if (!r.error && !without.at(r, iface)?.timestamp) {
+        dropped.add(e);
+        e.item.diag("info", "I_PACK_ANNOTATION_SKIPPED", e.ann.at, `idempotency dropped: the stamp field "${e.ann.args.stamp}" has no timestamp tag in this service`);
+      }
+    }
+  }
+
+  // Binding (spec section 7): a canister profile whose interface changed is stale when anything no longer holds.
+  const stale = new Set(ordered.filter((item) => item.rebinding && item.diags.some((d) => STALE_CODES.has(d.code))));
+  // A stale profile must not supply value-conversion tags, and a dropped pack annotation is not applied: keep both
+  // out of the merged result.
+  const keep = (e) => !dropped.has(e) && !(stale.has(e.item) && VALUE_CONVERSION_TAGS.has(e.ann.tag));
+  const final = stale.size || dropped.size ? buildLayers(entries, keep) : tags;
+
+  // Overrides: the same tag at the same position in a lower layer (W_OVERRIDDEN, spec section 8).
+  if (final.layers.length > 1) {
+    const overrides = new Map();
+    const note = (cands, display) => {
+      for (const [tag, list] of Object.entries(cands)) {
+        const winner = list[0];
+        for (const loser of list.slice(1)) {
+          const w = meta.get(winner);
+          const l = meta.get(loser);
+          const key = `${tag}|${l.item.doc.name}|${l.at}|${w.item.doc.name}|${w.at}`;
+          const o = overrides.get(key);
+          if (o) o.positions++;
+          else overrides.set(key, { tag, winner, loser, w, l, positions: 1, first: display });
+        }
+      }
+    };
+    for (const [name] of iface.methods) {
+      note(final.candidatesAtMethod(name), name);
+      for (const side of ["args", "results"]) for (const pos of positions(iface, name, side)) note(final.candidates(pos, iface), pos.display);
+    }
+    for (const o of overrides.values()) {
+      const where = o.positions > 1 ? `${o.positions} positions, first ${o.first}` : o.first;
+      o.l.item.diag("warning", "W_OVERRIDDEN", o.l.at, `${o.tag} from profile "${o.l.item.doc.name}" (${o.loser.origin}) is overridden by profile "${o.w.item.doc.name}" (${o.winner.origin}) at "${o.w.at}" [${where}]`);
+    }
+  }
+
+  // Coverage hint: numeric positions in update-method arguments 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;
+    for (const pos of positions(iface, name, "args")) {
+      const p = iface.prim(iface.unwrapOpt(pos.ref).ref);
+      const t = final.at(pos, iface);
+      if (NUMERIC.has(p) && !MEANING.some((x) => t?.[x])) diagnostics.push({ severity: "info", code: "I_UNTAGGED_NUMERIC", at: pos.display, message: `${p} argument without amount/timestamp/duration/describe` }); // about the merged interface, so no profile
+    }
+  }
+
+  for (const item of stale) {
+    item.diag("error", "E_STALE", "binds.interface_id", "the interface changed and some annotations no longer hold; value-conversion tags must not be used (the resolved form omits this profile's value-conversion tags)");
+  }
+  return { diagnostics, layered: final, ordered, stale };
+}

package/src/browser.d.mts

@@ -0,0 +1,212 @@
+// 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, a pack, or an EVM contract profile (section 15). */
+export interface ProfileDocument {
+  format: "candid-profile";
+  format_version: 0;
+  kind: "canister" | "pack" | "contract";
+  name: string;
+  origin: "author" | "third_party" | "pack" | "inferred";
+  annotations: { at: string; tag: string; args?: Record<string, unknown> }[];
+  [key: string]: unknown;
+}
+
+/** A candid-profile-resolved v0 document (docs/profile-v0.md section 10). */
+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[];
+  [key: string]: unknown;
+}
+
+export interface Diagnostic {
+  severity: "error" | "warning" | "info";
+  code: string;
+  /** A JSON pointer for E_SCHEMA, an address (`send(0).to`, `type:Tokens.e8s`) or a document path (`binds.interface_id`). */
+  at: string;
+  message: string;
+  /** The profile's name, when the diagnostic comes from one. */
+  profile?: string;
+}
+
+export interface ProfileStatus {
+  name: string;
+  origin: string | null;
+  kind: string | null;
+  profile_id: string | null;
+  status: "applied" | "rebound" | "stale" | "not_matched" | "invalid";
+  explicit: boolean;
+}
+
+export interface Pack {
+  file: string;
+  doc: ProfileDocument;
+}
+
+/** An Ajv validate function for the profile schema. */
+export interface SchemaValidator {
+  (doc: unknown): boolean;
+  errors?: { instancePath: string; message?: string; params?: Record<string, unknown> }[] | null;
+}
+
+export interface ResolveOptions {
+  /** 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 (an EVM pack by selector); applied only if they match. */
+  packs?: { doc: unknown; label?: string }[];
+  validateSchema: SchemaValidator;
+}
+
+export interface ResolveResult {
+  ok: boolean;
+  /** null when the service does not compile (or the envelope cannot be read). */
+  resolved: ResolvedForm | null;
+  diagnostics: Diagnostic[];
+  profiles: ProfileStatus[];
+}
+
+export interface ValidateResult {
+  ok: boolean;
+  profile_id?: string;
+  interface_id?: string;
+  methods?: number;
+  annotations?: number;
+  diagnostics: Diagnostic[];
+  resolved?: ResolvedForm;
+}
+
+import type { Address, PathSegment } from "./address.mjs";
+export type { Address, PathSegment } from "./address.mjs";
+
+/** A node of the candid-core Contract graph (`kind` is primitive, opt, vec, record, variant, func, service, ...). */
+export interface ContractNode {
+  kind: string;
+  primitive?: string;
+  inner?: number;
+  fields?: { id: number; type: number }[];
+  [key: string]: unknown;
+}
+
+/** A compiled interface: the Contract graph with the lookups the resolver uses. */
+export declare class Iface {
+  constructor(envelope: unknown, label?: string);
+  label: string;
+  /** Method name -> mode and the type refs of its argument and result tuples. */
+  methods: Map<string, { mode: string; args: number[]; results: number[] }>;
+  /** Declaration name -> type ref. */
+  decls: Map<string, number>;
+  get interfaceId(): string | null;
+  node(ref: number): ContractNode;
+  unwrapOpt(ref: number): { ref: number; optional: boolean };
+  fieldName(container: number, id: number): string;
+  isBlob(ref: number): boolean;
+  isAccount(ref: number): boolean;
+  /** `nat64`, `opt blob`, `record`, ... */
+  describeType(ref: number): string;
+}
+
+/** One value position of a method side, as `positions` yields it. */
+export interface Position {
+  ref: number;
+  parent: { container: number; kind: string; id?: number } | null;
+  key: string;
+  /** The position's address, `send(0).amount.e8s` or `balance->(0)`. */
+  display: string;
+  /** The walk stopped here (a cycle or the depth bound). */
+  cyclic: boolean;
+}
+export declare class TagIndex {
+  [key: string]: unknown;
+}
+export declare class LayeredTags {
+  [key: string]: unknown;
+}
+export declare class SubtypeChecker {
+  [key: string]: unknown;
+}
+
+/** The profile schema (a copy of spec/profile-v0.schema.json). */
+export const PROFILE_SCHEMA: Record<string, unknown>;
+/** The standard packs (copies of packs/*.profile.json), sorted by file name. */
+export const STANDARD_PACKS: readonly Pack[];
+export const LAYERS: readonly ["author", "third_party", "pack", "inferred"];
+
+/** Initialize the cli's wasm compiler; optional, for a bundler that moves the wasm file. */
+export function initCompiler(input?: BufferSource | URL | string | Response): Promise<void>;
+/**
+ * The validate function for the profile schema. The shipped schema (the default, or a document equal to it) is
+ * compiled ahead of time and needs no CSP 'unsafe-eval'; any other document is compiled by ajv with `new Function`.
+ */
+export function createSchemaValidator(doc?: Record<string, unknown>): Promise<SchemaValidator>;
+export function schemaDiagnostics(validateSchema: SchemaValidator): Diagnostic[];
+export function resolveService(opts: ResolveOptions): Promise<ResolveResult>;
+export function validateProfile(doc: unknown, opts: { validateSchema: SchemaValidator; did?: string | null; didLabel?: string; resolved?: boolean }): Promise<ValidateResult>;
+
+export function idlHash(label: string): number;
+/** RFC 8785 (JCS) canonical JSON. */
+export function jcs(value: unknown): string;
+/** `candid-profile:v0:sha256:<hex>` over the JCS form of the document. */
+export function profileId(doc: unknown): string;
+export function parseAddress(at: string): Address | null;
+export function parseRelPath(rel: string): { index: number | null; segs: PathSegment[] } | null;
+
+export function compileInterface(source: string, label?: string): Promise<{ iface: Iface } | { failure: { code: string; message: string }[] }>;
+export function interfaceFromEnvelope(envelope: unknown, label?: string): { iface: Iface } | { failure: { code: string; message: string }[] };
+export function matchPack(canister: Iface, pack: unknown, opts?: Record<string, unknown>): Promise<{ matched: boolean; reasons: { at: string; message: string }[]; relaxed: unknown; fragment: Iface } | { error: { code: string; message: string }[] }>;
+export function matchService(canister: Iface, fragment: Iface, opts?: Record<string, unknown>): { ok: boolean; reasons: { at: string; message: string }[]; relaxed: unknown };
+export function typeSubtype(S: Iface, s: unknown, T: Iface, t: unknown, opts?: Record<string, unknown>): unknown;
+export function positions(iface: Iface, methodName: string, side: "args" | "results", maxDepth?: number): Generator<Position>;
+export function analyzeProfiles(iface: Iface, items: unknown[], opts?: { attribute?: boolean }): { diagnostics: Diagnostic[]; layered: LayeredTags; ordered: unknown[]; stale: Set<unknown> };
+export function resolvedForm(iface: Iface, profiles: unknown[], tags: LayeredTags, diagnostics: Diagnostic[]): ResolvedForm;
+export function buildTree(iface: Iface, methodName: string, side: "args" | "results", tags: LayeredTags): unknown;
+
+/** The doc attributes version `profileFromDocAttributes` reads (candid-core `docs/doc-attributes.md`). */
+export const DOC_ATTRIBUTES_VERSION: 1;
+/** A diagnostic about a doc comment: `at` is the item's address once it has one, else its SourceInfo path. */
+export interface DocDiagnostic extends Diagnostic {
+  /** The documented item's SourceInfo occurrence path (`actor.methods[2]`, `type:Tokens.fields[0]`). */
+  path?: string;
+  /** The source file the comment is in, as candid-core names it (`memory:/service.did`). */
+  source?: string;
+}
+/**
+ * An author canister profile from the tags written as doc comments in a `.did` (spec section 9). `response` is what
+ * `didToDocAttributes(sources)` of `@candid-core/cli` returns; a failed response is passed through as diagnostics.
+ * `doc` is null when the comments hold no tag. The profile still goes through `resolveService`, which checks the tags.
+ */
+export function profileFromDocAttributes(
+  response: unknown,
+  opts?: { name?: string; origin?: "author" | "third_party"; language?: string; canisterId?: string },
+): { ok: boolean; doc: ProfileDocument | null; diagnostics: DocDiagnostic[] };
+
+/** The custom section a canister serves its profile in (spec section 8.1): `"icp:public candid:profile"`. */
+export const SERVED_SECTION: "icp:public candid:profile";
+/** The metadata name a consumer reads through `read_state`: `/canister/<id>/metadata/candid:profile`. */
+export const SERVED_METADATA: "candid:profile";
+/** The largest served profile `readServedProfile` reads, in bytes (1 MiB, the platform's custom section limit). */
+export const SERVED_MAX_BYTES: number;
+/**
+ * A profile its canister serves (spec section 8.1), from the bytes of the canister's `candid:profile` metadata. Refused
+ * with E_SERVED when the bytes are not UTF-8 JSON of at most 1 MiB, the document is not a `canister` profile of origin
+ * `author`, or its `binds.canister_id` names another canister. The profile still goes through `resolveService`, which
+ * checks the schema, the binding (against the same canister's `candid:service`) and the tags.
+ */
+export function readServedProfile(
+  bytes: Uint8Array,
+  /** `canisterId`: the canister that served it; null only to check a profile before its module is installed. */
+  opts: { canisterId: string | null; label?: string },
+): { ok: boolean; doc: ProfileDocument | null; diagnostics: Diagnostic[] };
+