@meantjs/profile 0.0.0-stage → 0.1.0

package/src/resolve.mjs

@@ -0,0 +1,114 @@
+/**
+ * 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 { 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 (exactly one of the two)
+ * @param opts.didLabel      how E_CANDID (or E_ENVELOPE) 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 (fromEnvelope === (opts.did !== undefined)) throw new TypeError("resolveService: give exactly one of `did` and `envelope`");
+  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 = [];
+  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 };
+  }
+  const { iface } = compiled;
+
+  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 (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,60 @@
+/**
+ * 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 = { candid: n.kind === "primitive" ? n.primitive : iface.isBlob(r) ? "blob" : n.kind };
+    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" };
+    }
+    methods[name] = { mode: m.mode, tags: mt, args: buildTree(iface, name, "args", tags), results: buildTree(iface, name, "results", tags) };
+  }
+  return {
+    format: "candid-profile-resolved",
+    format_version: 0,
+    interface_id: iface.contract.identities.interface ?? null,
+    profiles: profiles.map(({ doc, pid }) => ({ name: doc.name, origin: doc.origin, profile_id: pid })),
+    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("");
+}

package/src/subtype.mjs

@@ -0,0 +1,271 @@
+/**
+ * Structural Candid subtyping over candid-core Contract graphs, with the pack-matching relaxation of D-019.
+ *
+ * No existing checker could be reused (see README.md, "Subtyping"): @dfinity/didc 0.0.4 exports only
+ * getServiceMethods/encode/decode, and @candid-core/cli 0.2.0 exported only didToContract/didToModule/init (surveyed 2026-10-09; 0.3.0, pinned since D-037, adds
+ * projectDid and checkCompatible, not checked here).
+ * candid-core's service-level check (b3hr4d/candid-core#247) is an open issue, not code. So this is our own
+ * implementation of the rules in the Candid specification, section "Upgrading and Subtyping > Rules"
+ * (https://github.com/dfinity/candid/blob/c7659ca/spec/Candid.md), checked against the Rust crate
+ * candid 0.10.37 (src/types/subtype.rs).
+ *
+ * `S <: T` ("S is a subtype of T") is decided between two Contract graphs (`Iface`), because a canister and a pack
+ * fragment are compiled separately. Rules implemented, with the spec subsection each comes from:
+ *
+ *   Primitive types   t <: t;  nat <: int;  any <: reserved;  empty <: any.
+ *   Vectors           vec S <: vec T            if S <: T.  (`blob` is `vec nat8`, so it needs no rule of its own.)
+ *   Options           opt S <: opt T            if S <: T;
+ *                     null <: opt T;
+ *                     S <: opt T                if S <: T and T is not null, reserved or opt  (the "constituent" rule).
+ *                     Optional, off by default (`lossyOpt`): the two "unusual" rules that make opt S <: opt T hold
+ *                     even when S and T are unrelated (the value decodes as null). The spec says they exist only
+ *                     to keep subtyping transitive, and that tools should warn when they are used. For pack matching
+ *                     they would let `fee : opt text` match a pack that says `fee : opt nat`, so they are rejected.
+ *   Records           record S <: record T      if every field of T is in S with S_f <: T_f, or is missing from S and
+ *                                               has an optional type (null <: T_f, that is opt, null or reserved).
+ *                                               Extra fields in S are ignored.
+ *   Variants          variant S <: variant T    if every case of S is in T with S_c <: T_c. (S may have fewer cases.)
+ *   Functions         func(A) -> (R) m <: func(A') -> (R') m'   if the modes are equal, tuple(A') <: tuple(A)
+ *                                               (arguments contravariant) and tuple(R) <: tuple(R') (results covariant);
+ *                                               tuples follow the record rule with positional ids 0, 1, ...
+ *   Services          service S <: service T    if every method of T is in S and its function type is a subtype.
+ *                                               Extra methods in S are ignored. (Init args of a service class are ignored.)
+ *   Recursion         Coinductive: a pair under test is assumed to hold when met again.
+ *
+ * Not implemented, on purpose: the Rust crate's catch-all that accepts `S <: opt T` for any S with only a warning
+ * (not a rule of the spec); `service <: principal` (not in the spec revision above).
+ *
+ * D-019 relaxation (`mode: "relaxed"`, spec profile-v0 section 7): when matching a pack, a variant reached through a
+ * method *result* may have cases that the pack fragment lacks. Reached through means descending from the result by
+ * record fields, opt, vec and variant payloads only, with covariant polarity; entering any func or service type
+ * (where polarity can flip) resets to strict. Argument positions are always strict.
+ *
+ * Bounded work (profile-v0 section 11.6): depth and step limits fail closed to "not a subtype".
+ */
+
+const DEFAULT_MAX_DEPTH = 256;
+const DEFAULT_MAX_STEPS = 2_000_000;
+
+const isNullLike = (iface, ref) => {
+  const n = iface.types[ref];
+  return n.kind === "opt" || (n.kind === "primitive" && (n.primitive === "null" || n.primitive === "reserved"));
+};
+
+/** A short rendering of a type for messages. Bounded in depth and width. */
+export function show(iface, ref, depth = 2, seen = new Set()) {
+  const n = iface.types[ref];
+  if (n.kind === "primitive") return n.primitive;
+  if (iface.isBlob(ref)) return "blob";
+  if (n.kind === "opt") return `opt ${show(iface, n.inner, depth, seen)}`;
+  if (n.kind === "vec") return `vec ${show(iface, n.inner, depth, seen)}`;
+  if (depth <= 0 || seen.has(ref)) return n.kind;
+  const next = new Set(seen).add(ref);
+  if (n.kind === "record" || n.kind === "variant") {
+    const parts = n.fields.slice(0, 4).map((f) => {
+      const label = iface.fieldName(ref, f.id);
+      const inner = iface.types[f.type];
+      return n.kind === "variant" && inner.kind === "primitive" && inner.primitive === "null" ? label : `${label} : ${show(iface, f.type, depth - 1, next)}`;
+    });
+    return `${n.kind} { ${parts.join("; ")}${n.fields.length > 4 ? "; ..." : ""} }`;
+  }
+  if (n.kind === "func") return `func (${n.args.map((a) => show(iface, a, depth - 1, next)).join(", ")}) -> (${n.results.map((a) => show(iface, a, depth - 1, next)).join(", ")}) ${n.mode}`;
+  return n.kind;
+}
+
+export class SubtypeChecker {
+  /**
+   * @param opts.lossyOpt  apply the spec's two "unusual" opt rules (default false)
+   * @param opts.maxDepth  nesting limit, fails closed (default 256)
+   * @param opts.maxSteps  pair-evaluation budget, fails closed (default 2,000,000)
+   */
+  constructor(opts = {}) {
+    this.lossyOpt = Boolean(opts.lossyOpt);
+    this.maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    this.maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
+    this.gamma = new Set();
+    this.relaxed = [];
+    this.steps = 0;
+    this.depth = 0;
+    this.ids = new Map();
+  }
+
+  #id(iface) {
+    if (!this.ids.has(iface)) this.ids.set(iface, this.ids.size);
+    return this.ids.get(iface);
+  }
+
+  /** Start a new top-level query: assumptions from an earlier (possibly failed) query must not leak. */
+  fresh() {
+    this.gamma = new Set();
+    this.depth = 0;
+  }
+
+  /**
+   * Decide S <: T for `s` in iface S and `t` in iface T.
+   * @param mode "strict" or "relaxed" (D-019, variants only)
+   * @param path address-like path segments, for diagnostics
+   * @returns null when it holds, else { path, message } for the first failure
+   */
+  sub(S, s, T, t, mode = "strict", path = []) {
+    if (S === T && s === t) return null;
+    const key = `${this.#id(S)}:${s}<:${this.#id(T)}:${t}|${mode}`;
+    if (this.gamma.has(key)) return null; // coinductive assumption
+    if (++this.steps > this.maxSteps) return { path: [...path], message: "step budget exceeded; treated as not a subtype" };
+    if (this.depth >= this.maxDepth) return { path: [...path], message: "type nesting exceeds the depth limit; treated as not a subtype" };
+    this.gamma.add(key);
+    this.depth++;
+    const err = this.#rules(S, s, T, t, mode, path);
+    this.depth--;
+    if (err) this.gamma.delete(key);
+    return err;
+  }
+
+  #rules(S, s, T, t, mode, path) {
+    const ns = S.types[s];
+    const nt = T.types[t];
+    const fail = (message) => ({ path: [...path], message });
+    const mismatch = () => fail(`${show(S, s)} (${S.label}) is not a subtype of ${show(T, t)} (${T.label})`);
+    const sp = ns.kind === "primitive" ? ns.primitive : null;
+    const tp = nt.kind === "primitive" ? nt.primitive : null;
+
+    if (tp === "reserved") return null; // <datatype> <: reserved
+    if (sp === "empty") return null; // empty <: <datatype>
+
+    if (nt.kind === "opt") {
+      if (ns.kind === "opt") {
+        const e = this.sub(S, ns.inner, T, nt.inner, mode, path); // opt S <: opt T if S <: T
+        if (!e) return null;
+        return this.lossyOpt ? null : e; // the two unusual rules, only when asked for
+      }
+      if (sp === "null") return null; // null <: opt T
+      if (isNullLike(T, nt.inner)) return mismatch(); // S <: opt T needs not (null <: T)
+      return this.sub(S, s, T, nt.inner, mode, path); // S <: opt T if S <: T
+    }
+    if (ns.kind === "opt") return mismatch(); // opt S is never a subtype of a non-opt T (T = reserved handled above)
+
+    if (sp !== null || tp !== null) {
+      if (sp !== null && tp !== null && (sp === tp || (sp === "nat" && tp === "int"))) return null;
+      return mismatch();
+    }
+    if (ns.kind !== nt.kind) return mismatch();
+
+    switch (ns.kind) {
+      case "vec":
+        return this.sub(S, ns.inner, T, nt.inner, mode, [...path, "[]"]);
+      case "record": {
+        const have = new Map(ns.fields.map((f) => [f.id, f.type]));
+        for (const f of nt.fields) {
+          const label = T.fieldName(t, f.id);
+          if (have.has(f.id)) {
+            const e = this.sub(S, have.get(f.id), T, f.type, mode, [...path, `.${label}`]);
+            if (e) return e;
+          } else if (!isNullLike(T, f.type)) {
+            return fail(`field "${label}" (${show(T, f.type)}) is required by the ${T.label} but missing from the ${S.label}`);
+          }
+        }
+        return null;
+      }
+      case "variant": {
+        const have = new Map(nt.fields.map((f) => [f.id, f.type]));
+        const extra = [];
+        for (const f of ns.fields) {
+          const label = S.fieldName(s, f.id);
+          if (!have.has(f.id)) {
+            if (mode === "relaxed") { extra.push(label); continue; } // D-019
+            return fail(`variant case "${label}" is in the ${S.label} but not in the ${T.label}`);
+          }
+          const e = this.sub(S, f.type, T, have.get(f.id), mode, [...path, `.${label}`]);
+          if (e) return e;
+        }
+        if (extra.length) this.relaxed.push({ at: pathString(path), cases: extra.sort() });
+        return null;
+      }
+      case "func": {
+        if (ns.mode !== nt.mode) return fail(`function mode is ${ns.mode} in the ${S.label} but ${nt.mode} in the ${T.label}`);
+        // Arguments are contravariant: tuple(T args) <: tuple(S args). Calls from a func value cannot use the D-019 relaxation.
+        for (let i = 0; i < ns.args.length; i++) {
+          if (i < nt.args.length) {
+            const e = this.sub(T, nt.args[i], S, ns.args[i], "strict", [...path, `(${i})`]);
+            if (e) return e;
+          } else if (!isNullLike(S, ns.args[i])) {
+            return fail(`argument ${i} (${show(S, ns.args[i])}) is required by the ${S.label} but not supplied by the ${T.label}`);
+          }
+        }
+        // Results are covariant: tuple(S results) <: tuple(T results).
+        for (let i = 0; i < nt.results.length; i++) {
+          if (i < ns.results.length) {
+            const e = this.sub(S, ns.results[i], T, nt.results[i], "strict", [...path, `->(${i})`]);
+            if (e) return e;
+          } else if (!isNullLike(T, nt.results[i])) {
+            return fail(`result ${i} (${show(T, nt.results[i])}) is expected by the ${T.label} but not returned by the ${S.label}`);
+          }
+        }
+        return null;
+      }
+      case "service": {
+        const have = new Map(ns.methods.map((m) => [m.name, m.function]));
+        for (const m of nt.methods) {
+          if (!have.has(m.name)) return fail(`method "${m.name}" is missing from the ${S.label}`);
+          const e = this.sub(S, have.get(m.name), T, m.function, "strict", [...path, m.name]);
+          if (e) return e;
+        }
+        return null;
+      }
+      default:
+        return fail(`unsupported type kind ${ns.kind}`);
+    }
+  }
+}
+
+function pathString(path) {
+  return path.join("");
+}
+
+/** Is type `s` of iface S a subtype of type `t` of iface T? A standalone entry point for tests and tools. */
+export function typeSubtype(S, s, T, t, opts = {}) {
+  const c = new SubtypeChecker(opts);
+  const mode = opts.resultVariants === "relaxed" ? "relaxed" : "strict";
+  const err = c.sub(S, s, T, t, mode);
+  return err ? { ok: false, reasons: [{ at: pathString(err.path), message: err.message }], relaxed: [] } : { ok: true, reasons: [], relaxed: c.relaxed };
+}
+
+/**
+ * Is the service of `canister` a subtype of the service of `fragment`, with the D-019 relaxation on result positions?
+ * Both are Iface. Methods of the fragment are checked one by one; every failing method contributes one reason.
+ * @param opts.resultVariants "relaxed" (default) applies D-019; "strict" is plain Candid subtyping
+ * @param opts.lossyOpt see SubtypeChecker
+ * @returns { ok, reasons: [{ at, message }], relaxed: [{ at, cases }] }
+ */
+export function matchService(canister, fragment, opts = {}) {
+  const resultMode = opts.resultVariants === "strict" ? "strict" : "relaxed";
+  const checker = new SubtypeChecker(opts);
+  const reasons = [];
+  const relaxed = [];
+  const note = (at, message) => reasons.push({ at, message });
+  const run = (at, fn) => {
+    checker.fresh();
+    const before = checker.relaxed.length;
+    const e = fn();
+    if (e) {
+      note(pathString(e.path) || at, e.message);
+      checker.relaxed.length = before; // a failed position contributes no relaxation
+    }
+  };
+  for (const [name, fm] of fragment.methods) {
+    const cm = canister.methods.get(name);
+    if (!cm) { note(name, `method "${name}" is missing from the ${canister.label}`); continue; }
+    if (cm.mode !== fm.mode) { note(name, `method "${name}" is ${cm.mode} in the ${canister.label} but ${fm.mode} in the ${fragment.label}`); continue; }
+    // Arguments, contravariant (strict): tuple(fragment args) <: tuple(canister args).
+    for (let i = 0; i < cm.args.length; i++) {
+      if (i < fm.args.length) run(`${name}(${i})`, () => checker.sub(fragment, fm.args[i], canister, cm.args[i], "strict", [`${name}(${i})`]));
+      else if (!isNullLike(canister, cm.args[i])) note(`${name}(${i})`, `argument ${i} (${show(canister, cm.args[i])}) is required by the ${canister.label} but not supplied by the ${fragment.label}`);
+    }
+    // Results, covariant (D-019 relaxation): tuple(canister results) <: tuple(fragment results).
+    for (let i = 0; i < fm.results.length; i++) {
+      if (i < cm.results.length) run(`${name}->(${i})`, () => checker.sub(canister, cm.results[i], fragment, fm.results[i], resultMode, [`${name}->(${i})`]));
+      else if (!isNullLike(fragment, fm.results[i])) note(`${name}->(${i})`, `result ${i} (${show(fragment, fm.results[i])}) is expected by the ${fragment.label} but not returned by the ${canister.label}`);
+    }
+  }
+  relaxed.push(...checker.relaxed);
+  return { ok: reasons.length === 0, reasons, relaxed };
+}