@meantjs/profile 0.0.0-stage → 0.2.0

package/src/index.d.mts

@@ -0,0 +1,70 @@
+// Types for @meantjs/profile (the Node entry). Hand-written; the source is plain ES modules (src/*.mjs). The
+// declarations it shares with the browser entry live in browser.d.mts. test/types.test.mjs keeps the declared names
+// equal to the runtime exports, and `npm run types` compiles a consumer against them under strict TypeScript.
+import type { Pack, SchemaValidator } from "./browser.mjs";
+
+export type {
+  Address,
+  ContractNode,
+  Diagnostic,
+  DocDiagnostic,
+  Pack,
+  PathSegment,
+  Position,
+  ProfileDocument,
+  ProfileStatus,
+  ResolveOptions,
+  ResolveResult,
+  ResolvedForm,
+  SchemaValidator,
+  ValidateResult,
+} from "./browser.mjs";
+export {
+  DOC_ATTRIBUTES_VERSION,
+  Iface,
+  LAYERS,
+  LayeredTags,
+  SubtypeChecker,
+  TagIndex,
+  analyzeProfiles,
+  buildTree,
+  compileInterface,
+  idlHash,
+  interfaceFromEnvelope,
+  jcs,
+  matchPack,
+  matchService,
+  parseAddress,
+  parseRelPath,
+  positions,
+  profileFromDocAttributes,
+  profileId,
+  readServedProfile,
+  resolveService,
+  resolvedForm,
+  SERVED_MAX_BYTES,
+  SERVED_METADATA,
+  SERVED_SECTION,
+  typeSubtype,
+  validateProfile,
+} from "./browser.mjs";
+
+/** The schema this package ships (a copy of the repository's spec/profile-v0.schema.json). */
+export const DEFAULT_SCHEMA_PATH: string;
+/** The directory of the standard packs this package ships (copies of the repository's packs/). */
+export const DEFAULT_PACKS_DIR: string;
+
+/**
+ * The validate function for the profile schema. The shipped schema (the default, or a file or document equal to it) is
+ * compiled ahead of time; any other schema is compiled by ajv at run time, with `new Function`.
+ *
+ * @param schema a path to a schema file, or the schema document (default: the schema this package ships)
+ */
+export function createSchemaValidator(schema?: string | Record<string, unknown>): Promise<SchemaValidator>;
+/** Every `*.profile.json` of kind "pack" in a directory, sorted by file name (default: the packs this package ships). */
+export function loadPacks(dir?: string): Promise<Pack[]>;
+
+/** `candid-profile` as a function: the exit code (0 no error, 1 an error diagnostic, 2 usage or I/O). */
+export function runCli(argv: string[], io: { stdout: { write(text: string): unknown }; stderr: { write(text: string): unknown } }): Promise<0 | 1 | 2>;
+/** The CLI's help text. */
+export const USAGE: string;

package/src/index.mjs

@@ -0,0 +1,15 @@
+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 { createSchemaValidator, DEFAULT_SCHEMA_PATH } from "./schema.mjs";
+export { compileInterface, interfaceFromEnvelope } from "./compile.mjs";
+export { validateProfile } from "./validate.mjs";
+export { resolveService } from "./resolve.mjs";
+export { matchPack, loadPacks, DEFAULT_PACKS_DIR } from "./packs.mjs";
+export { matchService, typeSubtype, SubtypeChecker } from "./subtype.mjs";
+export { analyzeProfiles, LAYERS } from "./analyze.mjs";
+export { main as runCli, USAGE } from "./cli.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";

package/src/keccak.mjs

@@ -0,0 +1,108 @@
+// Keccak-256 in plain JavaScript, synchronous, as Ethereum uses it: the original Keccak padding (0x01), not the NIST
+// SHA3-256 one (0x06). For function selectors, EIP-55 checksums, ERC-8176 descriptor hashes and EIP-712 digests
+// (spec section 15, D-054). test/evm.test.mjs checks it against the known hashes of the empty string and of the
+// ERC-20 selectors, and against the ERC-8176 schema UID.
+//
+// The 1600-bit state is 25 lanes of 64 bits, each kept as two 32-bit halves: s[2i] the low half, s[2i + 1] the high.
+
+const RC = new Uint32Array([
+  // round constants, [low, high] per round
+  0x00000001, 0x00000000, 0x00008082, 0x00000000, 0x0000808a, 0x80000000, 0x80008000, 0x80000000,
+  0x0000808b, 0x00000000, 0x80000001, 0x00000000, 0x80008081, 0x80000000, 0x00008009, 0x80000000,
+  0x0000008a, 0x00000000, 0x00000088, 0x00000000, 0x80008009, 0x00000000, 0x8000000a, 0x00000000,
+  0x8000808b, 0x00000000, 0x0000008b, 0x80000000, 0x00008089, 0x80000000, 0x00008003, 0x80000000,
+  0x00008002, 0x80000000, 0x00000080, 0x80000000, 0x0000800a, 0x00000000, 0x8000000a, 0x80000000,
+  0x80008081, 0x80000000, 0x00008080, 0x80000000, 0x80000001, 0x00000000, 0x80008008, 0x80000000,
+]);
+// rotation offsets of the rho step, by lane index x + 5y
+const ROT = [0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14];
+// the lane the pi step moves lane x + 5y to: (y, 2x + 3y)
+const PI = ROT.map((_, i) => {
+  const x = i % 5;
+  const y = (i - x) / 5;
+  return y + 5 * ((2 * x + 3 * y) % 5);
+});
+const RATE = 136; // bytes: 1600 - 2 * 256 bits
+
+function permute(s) {
+  const c = new Uint32Array(10);
+  const b = new Uint32Array(50);
+  for (let round = 0; round < 24; round++) {
+    // theta
+    for (let x = 0; x < 5; x++) {
+      c[2 * x] = s[2 * x] ^ s[2 * x + 10] ^ s[2 * x + 20] ^ s[2 * x + 30] ^ s[2 * x + 40];
+      c[2 * x + 1] = s[2 * x + 1] ^ s[2 * x + 11] ^ s[2 * x + 21] ^ s[2 * x + 31] ^ s[2 * x + 41];
+    }
+    for (let x = 0; x < 5; x++) {
+      const next = (x + 1) % 5;
+      const prev = (x + 4) % 5;
+      const lo = c[2 * prev] ^ ((c[2 * next] << 1) | (c[2 * next + 1] >>> 31));
+      const hi = c[2 * prev + 1] ^ ((c[2 * next + 1] << 1) | (c[2 * next] >>> 31));
+      for (let y = 0; y < 25; y += 5) {
+        s[2 * (x + y)] ^= lo;
+        s[2 * (x + y) + 1] ^= hi;
+      }
+    }
+    // rho and pi
+    for (let i = 0; i < 25; i++) {
+      const lo = s[2 * i];
+      const hi = s[2 * i + 1];
+      const n = ROT[i];
+      const j = PI[i];
+      if (n === 0) {
+        b[2 * j] = lo;
+        b[2 * j + 1] = hi;
+      } else if (n < 32) {
+        b[2 * j] = (lo << n) | (hi >>> (32 - n));
+        b[2 * j + 1] = (hi << n) | (lo >>> (32 - n));
+      } else if (n === 32) {
+        b[2 * j] = hi;
+        b[2 * j + 1] = lo;
+      } else {
+        const m = n - 32;
+        b[2 * j] = (hi << m) | (lo >>> (32 - m));
+        b[2 * j + 1] = (lo << m) | (hi >>> (32 - m));
+      }
+    }
+    // chi
+    for (let y = 0; y < 25; y += 5) {
+      for (let x = 0; x < 5; x++) {
+        const i = x + y;
+        const i1 = ((x + 1) % 5) + y;
+        const i2 = ((x + 2) % 5) + y;
+        s[2 * i] = b[2 * i] ^ (~b[2 * i1] & b[2 * i2]);
+        s[2 * i + 1] = b[2 * i + 1] ^ (~b[2 * i1 + 1] & b[2 * i2 + 1]);
+      }
+    }
+    // iota
+    s[0] ^= RC[2 * round];
+    s[1] ^= RC[2 * round + 1];
+  }
+}
+
+/** Keccak-256 of a byte array (or a string, as its UTF-8 bytes), as 32 bytes. */
+export function keccak256(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const s = new Uint32Array(50);
+  const blocks = Math.floor(bytes.length / RATE) + 1;
+  const padded = new Uint8Array(blocks * RATE);
+  padded.set(bytes);
+  padded[bytes.length] ^= 0x01;
+  padded[padded.length - 1] ^= 0x80;
+  for (let off = 0; off < padded.length; off += RATE) {
+    for (let k = 0; k < RATE; k += 4) {
+      s[k >> 2] ^= padded[off + k] | (padded[off + k + 1] << 8) | (padded[off + k + 2] << 16) | (padded[off + k + 3] << 24);
+    }
+    permute(s);
+  }
+  const out = new Uint8Array(32);
+  for (let k = 0; k < 32; k++) out[k] = (s[k >> 2] >>> (8 * (k & 3))) & 0xff;
+  return out;
+}
+
+/** Keccak-256 as 64 lowercase hex digits, without `0x`. */
+export function keccak256Hex(input) {
+  let hex = "";
+  for (const b of keccak256(input)) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}

package/src/pack-match.mjs

@@ -0,0 +1,19 @@
+/**
+ * Pack matching (spec section 7, D-005, D-019): a pack applies to a canister whose service is a subtype of the
+ * Candid fragment in `binds.requires`, with result variants allowed to be wider. No file system here; packs.mjs adds
+ * reading packs from a directory.
+ */
+import { compileInterface } from "./compile.mjs";
+import { matchService } from "./subtype.mjs";
+
+/**
+ * @param canister an Iface (label "canister")
+ * @param pack     a parsed, schema-valid pack document
+ * @returns { matched, reasons, relaxed } or { error: [candid-core diagnostics] } when `requires` does not compile
+ */
+export async function matchPack(canister, pack, opts = {}) {
+  const compiled = await compileInterface(pack.binds.requires, "pack fragment");
+  if (compiled.failure) return { error: compiled.failure };
+  const r = matchService(canister, compiled.iface, { resultVariants: "relaxed", lossyOpt: false, ...opts });
+  return { matched: r.ok, reasons: r.reasons, relaxed: r.relaxed, fragment: compiled.iface };
+}

package/src/packs.mjs

@@ -0,0 +1,25 @@
+/** Reading packs from a directory (Node). Matching a pack to a service is pack-match.mjs. */
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export { matchPack } from "./pack-match.mjs";
+
+/**
+ * The standard packs this package ships (data/packs/), so the default works wherever the package is installed.
+ * They are copies of the repository's packs/ (W0's paths), regenerated by `npm run data -w packages/resolver`;
+ * test/data.test.mjs fails when a copy is stale.
+ */
+export const DEFAULT_PACKS_DIR = fileURLToPath(new URL("../data/packs", import.meta.url));
+
+/** Read every `*.profile.json` of kind "pack" in a directory, sorted by file name. Unparseable files are reported, not skipped. */
+export async function loadPacks(dir = DEFAULT_PACKS_DIR) {
+  const out = [];
+  for (const f of (await readdir(dir)).sort()) {
+    if (!f.endsWith(".profile.json")) continue;
+    const file = path.join(dir, f);
+    const doc = JSON.parse(await readFile(file, "utf8"));
+    if (doc?.kind === "pack") out.push({ file, doc });
+  }
+  return out;
+}

package/src/resolve.mjs

@@ -0,0 +1,167 @@
+/**
+ * Resolve a service with any number of profiles (spec sections 7, 8 and 10).
+ *
+ *   explicit profiles     applied as given: canister profiles are checked for binding (rebound/stale), packs must match;
+ *   candidate packs       tried by Candid subtyping against `binds.requires`; those that match are applied, the rest
+ *                         are reported and left out;
+ *   layers                author > third_party > pack > inferred, merged per tag per position (W_OVERRIDDEN, E_CONFLICT).
+ *
+ * New diagnostic codes introduced here (additive; proposed in docs/proposals/w1-resolved-form-additions.md):
+ *   I_PACK_MATCHED, I_PACK_NOT_MATCHED, E_PACK_NOT_MATCHED, I_PACK_ANNOTATION_SKIPPED; and an optional `profile`
+ *   field on diagnostics that come from a profile. E_ENVELOPE (an `envelope` input that is not a readable candid-core
+ *   ContractEnvelope) is proposed in docs/proposals/w1-envelope-input.md.
+ */
+import { profileId } from "./util.mjs";
+import { compileInterface, interfaceFromEnvelope } from "./compile.mjs";
+import { analyzeProfiles } from "./analyze.mjs";
+import { matchPack } from "./pack-match.mjs";
+import { abiInterface, checkDeployments } from "./abi-iface.mjs";
+import { matchAbiPack, translatePack } from "./abi-pack.mjs";
+import { abiInterfaceId, parseAbi } from "./abi.mjs";
+import { resolvedForm } from "./resolved.mjs";
+import { schemaDiagnostics } from "./schema-core.mjs";
+
+const describeReasons = (reasons) => {
+  const shown = reasons.slice(0, 3).map((r) => `${r.at}: ${r.message}`).join("; ");
+  return reasons.length > 3 ? `${shown}; and ${reasons.length - 3} more` : shown;
+};
+
+/**
+ * @param opts.did           Candid source of the service, compiled here; or
+ * @param opts.envelope      the service's candid-core ContractEnvelope, already compiled; or
+ * @param opts.abi           an EVM contract's ABI: fragments or JSON ABI entries (spec section 15; exactly one of the three)
+ * @param opts.didLabel      how E_CANDID (or E_ENVELOPE, E_ABI) names the input
+ * @param opts.profiles      [{ doc, label? }] explicit profiles, applied or rejected
+ * @param opts.packs         [{ doc, label? }] candidate packs, applied only if they match
+ * @param opts.validateSchema from createSchemaValidator()
+ * @returns { ok, resolved, diagnostics, profiles }  `resolved` is null when the service does not compile (or the
+ *          envelope cannot be read).
+ *          `profiles[i]` = { name, origin, kind, profile_id, status, explicit } with status one of
+ *          applied | rebound | stale | not_matched | invalid.
+ */
+export async function resolveService(opts) {
+  const fromEnvelope = opts.envelope !== undefined;
+  if ([opts.did, opts.envelope, opts.abi].filter((x) => x !== undefined).length !== 1) throw new TypeError("resolveService: give exactly one of `did`, `envelope` and `abi`");
+  if (opts.abi !== undefined) return resolveCompiled(opts, false);
+  if (!fromEnvelope) return resolveCompiled(opts, false);
+  // interfaceFromEnvelope checks the graph before anything walks it; anything it still misses in someone else's
+  // document is reported against the envelope rather than thrown.
+  try {
+    return await resolveCompiled(opts, true);
+  } catch (e) {
+    const at = opts.didLabel ?? "envelope";
+    return { ok: false, resolved: null, diagnostics: [{ severity: "error", code: "E_ENVELOPE", at, message: `the envelope's graph could not be resolved: ${e?.message ?? e}` }], profiles: [] };
+  }
+}
+
+async function resolveCompiled(opts, fromEnvelope) {
+  const diagnostics = [];
+  const statuses = [];
+  if (opts.abi !== undefined) {
+    const label = opts.didLabel ?? "abi";
+    const compiled = abiInterface(opts.abi, label);
+    if (compiled.failure) {
+      for (const d of compiled.failure) diagnostics.push({ severity: "error", code: "E_ABI", at: d.at, message: d.message });
+      return { ok: false, resolved: null, diagnostics, profiles: statuses };
+    }
+    return resolveWith(compiled.iface, opts, diagnostics, statuses);
+  }
+  const compiled = fromEnvelope ? interfaceFromEnvelope(opts.envelope, "canister") : await compileInterface(opts.did, "canister");
+  if (compiled.failure) {
+    const [code, at] = fromEnvelope ? ["E_ENVELOPE", opts.didLabel ?? "envelope"] : ["E_CANDID", opts.didLabel ?? "service.did"];
+    for (const d of compiled.failure) diagnostics.push({ severity: "error", code, at, message: `${d.code}: ${d.message}` });
+    return { ok: false, resolved: null, diagnostics, profiles: statuses };
+  }
+  return resolveWith(compiled.iface, opts, diagnostics, statuses);
+}
+
+/** A profile or pack for an EVM contract (spec section 15) rather than a Candid service. */
+const isEvmDoc = (doc) => doc.kind === "contract" || (doc.kind === "pack" && doc.binds.abi !== undefined);
+
+async function resolveWith(iface, opts, diagnostics, statuses) {
+  const evm = iface.chain === "evm";
+
+  const candidates = [
+    ...(opts.profiles ?? []).map((p, i) => ({ ...p, explicit: true, label: p.label ?? `profile #${i + 1}` })),
+    ...(opts.packs ?? []).map((p, i) => ({ ...p, explicit: false, label: p.label ?? `pack #${i + 1}` })),
+  ];
+  const items = [];
+  const taken = new Set();
+  for (const c of candidates) {
+    const name = c.doc?.name ?? c.label;
+    const note = (severity, code, at, message) => diagnostics.push({ severity, code, at, message, profile: name });
+    if (!opts.validateSchema(c.doc)) {
+      for (const d of schemaDiagnostics(opts.validateSchema)) diagnostics.push({ ...d, profile: name });
+      statuses.push({ name, origin: c.doc?.origin ?? null, kind: c.doc?.kind ?? null, profile_id: null, status: "invalid", explicit: c.explicit });
+      continue;
+    }
+    const doc = c.doc;
+    const pid = profileId(doc);
+    if (taken.has(pid)) continue; // the same document given twice (for example explicitly and through the pack search)
+    const status = { name: doc.name, origin: doc.origin, kind: doc.kind, profile_id: pid, status: "applied", explicit: c.explicit };
+    if (isEvmDoc(doc) !== evm) {
+      if (!c.explicit) continue; // a pack for the other kind of interface can never apply
+      const what = doc.kind === "pack" ? "this pack" : `a ${doc.kind} profile`;
+      note("error", "E_CHAIN", "kind", `${what} describes ${isEvmDoc(doc) ? "an EVM contract" : "a Candid service"}, but the interface is ${evm ? "an EVM contract's ABI" : "a Candid service"}`);
+      statuses.push({ ...status, status: "invalid" });
+      continue;
+    }
+    if (evm && doc.kind === "pack") {
+      const m = matchAbiPack(iface, doc);
+      if (m.error) {
+        for (const d of m.error) note("error", "E_ABI", d.at, d.message);
+        statuses.push({ ...status, status: "invalid" });
+        continue;
+      }
+      if (!m.matched) {
+        const why = describeReasons(m.reasons);
+        if (c.explicit) note("error", "E_PACK_NOT_MATCHED", doc.name, `the contract lacks functions of the pack's binds.abi: ${why}`);
+        else note("info", "I_PACK_NOT_MATCHED", doc.name, `pack does not apply: ${why}`);
+        statuses.push({ ...status, status: "not_matched" });
+        continue;
+      }
+      note("info", "I_PACK_MATCHED", doc.name, "the contract has every function of the pack's binds.abi (same selectors, outputs and kind of call)");
+      items.push({ doc: translatePack(doc, m.functions, iface), pid, rebinding: false, apply: true, status });
+    } else if (evm) {
+      const own = parseAbi(doc.binds.abi, "binds.abi");
+      if (own.errors.length) {
+        for (const d of own.errors) note("error", "E_ABI", d.at, d.message);
+        statuses.push({ ...status, status: "invalid" });
+        continue;
+      }
+      checkDeployments(doc, note);
+      items.push({ doc, pid, rebinding: abiInterfaceId(own.functions) !== iface.interfaceId, apply: false, status });
+    } else if (doc.kind === "pack") {
+      const m = await matchPack(iface, doc);
+      if (m.error) {
+        for (const d of m.error) note("error", "E_CANDID", "binds.requires", `${d.code}: ${d.message}`);
+        statuses.push({ ...status, status: "invalid" });
+        continue;
+      }
+      if (!m.matched) {
+        const why = describeReasons(m.reasons);
+        if (c.explicit) note("error", "E_PACK_NOT_MATCHED", doc.name, `the service is not a subtype of the pack's binds.requires: ${why}`);
+        else note("info", "I_PACK_NOT_MATCHED", doc.name, `pack does not apply: ${why}`);
+        statuses.push({ ...status, status: "not_matched" });
+        continue;
+      }
+      const wider = m.relaxed.map((r) => `${r.at} has extra cases ${r.cases.join(", ")}`);
+      note("info", "I_PACK_MATCHED", doc.name, `the service is a subtype of the pack's binds.requires${wider.length ? ` (result variants wider than the pack, D-019: ${wider.join("; ")})` : ""}`);
+      items.push({ doc, pid, rebinding: false, apply: true, status });
+    } else {
+      items.push({ doc, pid, rebinding: doc.binds.interface_id !== iface.interfaceId, apply: false, status });
+    }
+    taken.add(pid);
+  }
+
+  const analysis = analyzeProfiles(iface, items, { attribute: true });
+  diagnostics.push(...analysis.diagnostics);
+  for (const item of analysis.ordered) {
+    item.status.status = analysis.stale.has(item) ? "stale" : item.rebinding ? "rebound" : "applied";
+  }
+  // Report profiles in precedence order, then the ones that were left out.
+  const applied = analysis.ordered.map((i) => i.status);
+  const left = statuses.splice(0);
+  const resolved = resolvedForm(iface, analysis.ordered, analysis.layered, diagnostics);
+  return { ok: !diagnostics.some((d) => d.severity === "error"), resolved, diagnostics, profiles: [...applied, ...left] };
+}

package/src/resolved.mjs

@@ -0,0 +1,64 @@
+/**
+ * The resolved form (spec section 10): one tree per method with the effective tags attached to every position.
+ * buildTree is moved verbatim from scripts/validate.mjs. The shape is a shared contract (fixtures/*.resolved.json).
+ */
+import { positions } from "./tags.mjs";
+
+export function buildTree(iface, methodName, side, tags) {
+  const out = [];
+  const stack = []; // [node object, depth]
+  for (const pos of positions(iface, methodName, side)) {
+    const { ref: r, optional } = iface.unwrapOpt(pos.ref);
+    const n = iface.node(r);
+    const node = iface.chain === "evm" ? { abi: iface.abiType(r) } : { candid: n.kind === "primitive" ? n.primitive : iface.isBlob(r) ? "blob" : n.kind };
+    if (n.kind === "vec" && typeof n.length === "number") node.length = n.length; // an EVM fixed-size array, T[k]
+    if (optional) node.optional = true;
+    const t = tags.at(pos, iface);
+    if (t) node.tags = t;
+    if (pos.cyclic) node.recursive = true;
+    const depth = pos.key.split("|")[3] === "" ? 0 : pos.key.split("|")[3].split("/").length;
+    while (stack.length && stack[stack.length - 1].depth >= depth) stack.pop();
+    if (depth === 0) out.push(node);
+    else {
+      const parentNode = stack[stack.length - 1].node;
+      const last = pos.display.endsWith("[]") ? null : pos.display.slice(pos.display.lastIndexOf(".") + 1);
+      if (last === null) parentNode.element = node;
+      else {
+        const bucket = pos.parent.kind === "record" ? "fields" : "cases";
+        parentNode[bucket] ??= {};
+        parentNode[bucket][last] = node;
+      }
+    }
+    stack.push({ node, depth });
+  }
+  return out;
+}
+
+/**
+ * @param iface    the interface the tree is built over
+ * @param profiles every profile that contributes, highest precedence first: [{ doc, pid }]
+ * @param tags     a LayeredTags
+ */
+export function resolvedForm(iface, profiles, tags, diagnostics) {
+  const methods = {};
+  for (const [name, m] of [...iface.methods.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    const mt = { ...tags.methodTags(name) };
+    if (!mt.effect) {
+      mt.effect = m.mode === "update" || m.mode === "oneway"
+        ? { args: { kind: "write", irreversible: true }, origin: "default" }
+        : { args: { kind: "read", irreversible: false }, origin: "default" };
+    }
+    const f = iface.functions?.get(name); // an EVM function: what a consumer needs to match and decode calldata
+    const abi = f ? { selector: f.selector, signature: f.signature, state_mutability: f.stateMutability } : {};
+    methods[name] = { mode: m.mode, ...abi, tags: mt, args: buildTree(iface, name, "args", tags), results: buildTree(iface, name, "results", tags) };
+  }
+  return {
+    format: "candid-profile-resolved",
+    format_version: 0,
+    ...(iface.chain === "evm" ? { chain: "evm" } : {}),
+    interface_id: iface.contract.identities.interface ?? null,
+    profiles: profiles.map(({ doc, pid }) => ({ name: doc.name, origin: doc.origin, profile_id: pid, ...(doc.binds?.deployments ? { deployments: doc.binds.deployments } : {}) })),
+    methods,
+    diagnostics,
+  };
+}

package/src/schema-core.mjs

@@ -0,0 +1,45 @@
+// The schema checks without the file system: compile a schema document, report its errors. schema.mjs adds reading
+// the schema from a path (Node); the browser entry passes the document the package ships.
+//
+// The schema this package ships is compiled ahead of time (data/profile-v0.validate.mjs, ajv's standalone code,
+// written by scripts/data.mjs), so validating against it generates no code at run time and runs under a
+// Content-Security-Policy without 'unsafe-eval'. Any other schema document is compiled by ajv here, at run time, which
+// uses `new Function`; ajv is loaded only then.
+import shipped from "../data/profile-v0.schema.json" with { type: "json" };
+import { validate as precompiled } from "../data/profile-v0.validate.mjs";
+import { jcs } from "./util.mjs";
+
+const SHIPPED_JCS = jcs(shipped);
+
+/**
+ * Compile a profile schema document once; the result is a validate function with ajv's `errors`. A document equal
+ * to the shipped schema (as JSON, whatever its key order) gets the precompiled validator.
+ */
+export async function compileSchema(doc) {
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) throw new TypeError("createSchemaValidator: expected a path or a schema object");
+  if (doc === shipped || jcs(doc) === SHIPPED_JCS) return ownErrors(precompiled);
+  const { default: Ajv2020Module } = await import("ajv/dist/2020.js");
+  const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
+  return new Ajv2020({ allErrors: true, strict: true }).compile(doc);
+}
+
+/** A validate function with its own `errors`, as each run-time compile has, over the one shared precompiled one. */
+function ownErrors(validate) {
+  const own = (doc) => {
+    const ok = validate(doc);
+    own.errors = validate.errors;
+    return ok;
+  };
+  own.errors = null;
+  return own;
+}
+
+/** E_SCHEMA diagnostics for the errors of a failed validate call. */
+export function schemaDiagnostics(validateSchema) {
+  return validateSchema.errors.map((e) => ({
+    severity: "error",
+    code: "E_SCHEMA",
+    at: e.instancePath || "/",
+    message: `${e.message}${e.params ? ` ${JSON.stringify(e.params)}` : ""}`,
+  }));
+}

package/src/schema.mjs

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { compileSchema, schemaDiagnostics } from "./schema-core.mjs";
+
+export { schemaDiagnostics };
+
+/**
+ * The schema this package ships (data/profile-v0.schema.json), so the default works wherever the package is
+ * installed. It is a copy of the repository's spec/profile-v0.schema.json (W0's shared contract), regenerated by
+ * `npm run data -w packages/resolver`; test/data.test.mjs fails when the copy is stale.
+ */
+export const DEFAULT_SCHEMA_PATH = fileURLToPath(new URL("../data/profile-v0.schema.json", import.meta.url));
+
+/**
+ * The validate function for the profile schema, with ajv's `errors`. The shipped schema (the default, or a document or
+ * file equal to it) gets the validator compiled ahead of time; any other schema is compiled by ajv at run time.
+ *
+ * @param schema a path to the schema file (default: the copy this package ships), or the schema document itself
+ *               (`import schema from "@meantjs/profile/schema.json" with { type: "json" }` is the same copy).
+ */
+export async function createSchemaValidator(schema = DEFAULT_SCHEMA_PATH) {
+  return compileSchema(typeof schema === "string" ? JSON.parse(await readFile(schema, "utf8")) : schema);
+}

package/src/served.mjs

@@ -0,0 +1,59 @@
+/**
+ * A profile served by its canister (spec section 8.1, D-048): the public custom section `icp:public candid:profile`,
+ * read by a consumer through a certified `read_state` at `/canister/<id>/metadata/candid:profile`.
+ *
+ * This module reads the section's bytes; it does not fetch them, so the library keeps no agent dependency (the kit's
+ * `fetch` does the network part). What it checks is what only a served profile can get wrong: the bytes are UTF-8
+ * JSON of at most 1 MiB, the document is a `canister` profile of origin `author`, and its `binds.canister_id`, when
+ * given, is the canister that served it. Everything else (the schema, the binding to the interface the same canister
+ * serves as `candid:service`, every tag) is `resolveService`'s, as for any profile.
+ *
+ * New diagnostic code (spec section 13): E_SERVED.
+ */
+
+/** The name of the custom section a canister serves its profile in. */
+export const SERVED_SECTION = "icp:public candid:profile";
+/** The metadata name a consumer reads: `/canister/<id>/metadata/candid:profile`. */
+export const SERVED_METADATA = "candid:profile";
+/** The largest served profile read: the platform's limit for all of a canister's custom sections together. */
+export const SERVED_MAX_BYTES = 1024 * 1024;
+
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/**
+ * @param bytes          the content of the canister's `candid:profile` metadata (a Uint8Array)
+ * @param opts.canisterId the textual id of the canister that served it; null only before the module is installed
+ *                       anywhere (the kit's `embed`), which leaves `binds.canister_id` unchecked
+ * @param opts.label     how diagnostics name the input (default "candid:profile")
+ * @returns { ok, doc, diagnostics }  `doc` is the parsed profile, or null when it cannot be used (E_SERVED)
+ */
+export function readServedProfile(bytes, opts = {}) {
+  const at = opts.label ?? SERVED_METADATA;
+  const refuse = (message) => ({ ok: false, doc: null, diagnostics: [{ severity: "error", code: "E_SERVED", at, message }] });
+  if (opts.canisterId !== null && (typeof opts.canisterId !== "string" || opts.canisterId === "")) {
+    throw new TypeError("readServedProfile: give the serving canister's id as opts.canisterId (null before it is installed)");
+  }
+  if (!(bytes instanceof Uint8Array)) return refuse("the served profile is not bytes");
+  if (bytes.length > SERVED_MAX_BYTES) return refuse(`the served profile is ${bytes.length} bytes, over the ${SERVED_MAX_BYTES} a canister can serve`);
+  let text;
+  try {
+    text = decoder.decode(bytes);
+  } catch {
+    return refuse("the served profile is not UTF-8");
+  }
+  if (text.startsWith("")) return refuse("the served profile starts with a byte order mark");
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (e) {
+    return refuse(`the served profile is not JSON: ${e.message}`);
+  }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return refuse("the served profile is not a JSON object");
+  if (doc.kind !== "canister") return refuse(`a canister serves a profile of kind "canister", not ${JSON.stringify(doc.kind ?? null)}`);
+  if (doc.origin !== "author") return refuse(`a profile its canister serves is the author's: origin "author", not ${JSON.stringify(doc.origin ?? null)}`);
+  const bound = doc.binds?.canister_id;
+  if (bound !== undefined && opts.canisterId !== null && bound !== opts.canisterId) {
+    return refuse(`the served profile is bound to canister ${JSON.stringify(bound)}, but ${opts.canisterId} served it`);
+  }
+  return { ok: true, doc, diagnostics: [] };
+}

package/src/sha256.mjs

@@ -0,0 +1,59 @@
+// SHA-256 in plain JavaScript, synchronous, so that `profileId` needs no node:crypto (WebCrypto is asynchronous, and
+// profileId is called inside synchronous code). test/browser-entry.test.mjs compares it with node:crypto.
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+
+/** SHA-256 of a byte array, as 32 bytes. */
+export function sha256(bytes) {
+  const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+  const bitLength = bytes.length * 8;
+  const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) << 6);
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(bitLength / 2 ** 32), false);
+  view.setUint32(padded.length - 4, bitLength >>> 0, false);
+  const w = new Uint32Array(64);
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + 4 * i, false);
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h;
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + S1 + ch + K[i] + w[i]) | 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) | 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = (d + t1) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) | 0;
+    }
+    h[0] += a; h[1] += b; h[2] += c; h[3] += d; h[4] += e; h[5] += f; h[6] += g; h[7] += hh;
+  }
+  const out = new Uint8Array(32);
+  const ov = new DataView(out.buffer);
+  h.forEach((x, i) => ov.setUint32(4 * i, x, false));
+  return out;
+}
+
+/** Lowercase hex SHA-256 of a string's UTF-8 bytes. */
+export function sha256Hex(text) {
+  return Array.from(sha256(new TextEncoder().encode(text)), (b) => b.toString(16).padStart(2, "0")).join("");
+}