@meantjs/profile 0.0.0-bootstrap → 0.1.0

package/src/analyze.mjs

@@ -0,0 +1,298 @@
+/**
+ * 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, STALE_CODES, VALUE_CONVERSION_TAGS,
+  checkApplicability, checkDynamic, parseTemplate, outcomeCoverage,
+} 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 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 (METHOD_TAGS.has(a.tag)) {
+      const m = res.method;
+      const methodName = addr.method;
+      if (a.tag === "effect") {
+        const { kind, irreversible, replicated } = a.args;
+        if (m.mode !== "update" && m.mode !== "oneway" && kind !== "read") diag("error", "E_EFFECT_MODE", at, `${m.mode} method cannot have effect kind "${kind}"`);
+        // A read-only update (D-038): a read sent as an update so that its answer goes through consensus.
+        if (replicated === true) {
+          if (m.mode !== "update") diag("error", "E_EFFECT_MODE", at, `replicated: true applies to update methods, not to a ${m.mode} method`);
+          if (kind !== "read" || irreversible !== false) diag("error", "E_EFFECT_MODE", at, `replicated: true needs kind "read" and irreversible: false, found kind "${kind}" and irreversible: ${irreversible}`);
+        }
+        const replicatedRead = replicated === true && m.mode === "update" && kind === "read" && irreversible === false;
+        if ((m.mode === "update" || m.mode === "oneway") && kind === "read" && !replicatedRead) {
+          diag("warning", "W_EFFECT_MODE", at, `${m.mode} method declared as read${m.mode === "update" && replicated !== true ? "; a read sent as an update says irreversible: false, replicated: true" : ""}`);
+        }
+      }
+      if (a.tag === "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") {
+        const t = parseTemplate(a.args.template);
+        if (t.error) diag("error", "E_TEMPLATE", at, t.error);
+        else for (const p of t.placeholders) {
+          const r = iface.resolveRel(methodName, "args", p.path);
+          if (r.error && item.apply && p.inOptional) { // absent in this service: the optional segment renders empty (spec section 6)
+            item.diag("info", "I_PACK_ANNOTATION_SKIPPED", at, `intent: {${p.path}} is absent in this service (${r.error}); its optional segment renders empty`);
+            continue;
+          }
+          if (r.error) { diag("error", "E_TEMPLATE_PATH", at, `{${p.path}}: ${r.error}`); continue; }
+          if (!p.inOptional && iface.node(r.ref).kind === "opt") diag("warning", "W_TEMPLATE_OPTIONAL", at, `{${p.path}} is optional but sits outside a [ ] segment`);
+        }
+      }
+      if (a.tag === "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)`);
+    }
+  }
+
+  // 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,208 @@
+// Types for @meantjs/profile/browser. Hand-written; the source is plain ES modules (src/*.mjs). The internal
+// graph classes (Iface, TagIndex, LayeredTags, SubtypeChecker) are declared opaquely.
+
+/** A Candid Profile document (docs/profile-v0.md): a canister profile or a pack. */
+export interface ProfileDocument {
+  format: "candid-profile";
+  format_version: 0;
+  kind: "canister" | "pack";
+  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;
+  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` and `envelope`). */
+  did?: string;
+  /** The service's candid-core ContractEnvelope. */
+  envelope?: unknown;
+  didLabel?: string;
+  /** Applied as given; a pack here must match. */
+  profiles?: { doc: unknown; label?: string }[];
+  /** Tried by Candid subtyping; applied only if they match. */
+  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[] };
+

package/src/browser.mjs

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

package/src/checks.mjs

@@ -0,0 +1,81 @@
+/**
+ * Per-annotation semantic checks (spec sections 3 to 6). Moved verbatim from scripts/validate.mjs.
+ */
+export const NUMERIC = new Set(["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64"]);
+export const TIMEISH = new Set(["nat", "int", "nat32", "nat64", "int64"]);
+export const METHOD_TAGS = new Set(["intent", "effect", "idempotency", "outcome", "list", "names"]);
+/** Tags that convert a value between its wire form and a human form; a stale profile must not supply them (spec section 7). */
+export const VALUE_CONVERSION_TAGS = new Set(["amount", "timestamp", "duration", "account", "subaccount", "bytes", "named"]);
+export const STALE_CODES = new Set(["E_ADDR_UNRESOLVED", "E_TYPE_NODE", "E_TAG_NOT_APPLICABLE", "E_REF_UNRESOLVED", "E_REF_NOT_QUERY", "E_REF_SHAPE", "E_REF_TYPE", "E_STAMP_UNTAGGED", "E_OUTCOME_NOT_CASE", "E_TEMPLATE_PATH", "E_TAG_TARGET", "E_NAMES_MODE", "E_NAMES_SHAPE", "E_NAMES_FIELD", "E_NAMED_SET", "E_NAMED_TYPE"]);
+
+export function checkApplicability(iface, tag, ref) {
+  const { ref: r } = iface.unwrapOpt(ref);
+  const p = iface.prim(r);
+  switch (tag) {
+    case "amount": return NUMERIC.has(p) ? null : `amount needs a numeric type, found ${iface.describeType(ref)}`;
+    case "timestamp":
+    case "duration": return TIMEISH.has(p) ? null : `${tag} needs nat/int/nat32/nat64/int64, found ${iface.describeType(ref)}`;
+    case "account": return iface.isAccount(r) ? null : `account needs record { owner : principal; subaccount : opt blob }, found ${iface.describeType(ref)}`;
+    case "subaccount":
+    case "bytes": return iface.isBlob(r) ? null : `${tag} needs blob, found ${iface.describeType(ref)}`;
+    case "text": return p === "text" ? null : `text needs text, found ${iface.describeType(ref)}`;
+    case "range": return NUMERIC.has(p) || p === "text" || iface.node(r).kind === "vec" ? null : `range needs numeric, text or vec, found ${iface.describeType(ref)}`;
+    default: return null;
+  }
+}
+
+export function checkDynamic(iface, value, want, diag, at) {
+  if (!value || typeof value !== "object") return;
+  const from = value.from;
+  if (from === "now" || from === "caller") {
+    if (want !== "any") diag("error", "E_DYNAMIC_KIND", at, `"${from}" is not valid here; expected query:<method> returning ${want}`);
+    return;
+  }
+  const name = from.slice("query:".length);
+  const m = iface.methods.get(name);
+  if (!m) return diag("error", "E_REF_UNRESOLVED", at, `dynamic ref "${from}": no method "${name}" in the interface`);
+  if (m.mode !== "query" && m.mode !== "composite_query") diag("error", "E_REF_NOT_QUERY", at, `dynamic ref "${from}" must be a query method`);
+  if (m.args.length !== 0 || m.results.length !== 1) diag("error", "E_REF_SHAPE", at, `dynamic ref "${from}" must take no arguments and return one value`);
+  else {
+    const p = iface.prim(iface.unwrapOpt(m.results[0]).ref);
+    if (want === "numeric" && !NUMERIC.has(p)) diag("error", "E_REF_TYPE", at, `"${from}" returns ${p}, expected a number`);
+    if (want === "text" && p !== "text") diag("error", "E_REF_TYPE", at, `"${from}" returns ${p}, expected text`);
+  }
+}
+
+export function parseTemplate(t) {
+  const placeholders = [];
+  let depth = 0;
+  for (let i = 0; i < t.length; i++) {
+    const c = t[i];
+    if ((c === "{" || c === "}" || c === "[" || c === "]") && t[i + 1] === c) { i++; continue; } // escaped
+    if (c === "[") { if (depth) return { error: "nested [ ] segments are not allowed in v0" }; depth = 1; }
+    else if (c === "]") { if (!depth) return { error: "unbalanced ]" }; depth = 0; }
+    else if (c === "{") {
+      const end = t.indexOf("}", i);
+      if (end < 0) return { error: "unclosed {" };
+      placeholders.push({ path: t.slice(i + 1, end), inOptional: depth === 1 });
+      i = end;
+    } else if (c === "}") return { error: "unbalanced }" };
+  }
+  if (depth) return { error: "unclosed [" };
+  return { placeholders };
+}
+
+export function outcomeCoverage(iface, methodName, classes, diag, at, hasDefault) {
+  const m = iface.methods.get(methodName);
+  if (m.results.length !== 1) return;
+  const visit = (ref, prefix) => {
+    const { ref: r } = iface.unwrapOpt(ref);
+    const n = iface.node(r);
+    if (n.kind !== "variant") return;
+    for (const f of n.fields) {
+      const key = `${prefix}${iface.fieldName(r, f.id)}`;
+      if (classes[key]) continue;
+      const inner = iface.node(iface.unwrapOpt(f.type).ref);
+      if (inner.kind === "variant" && Object.keys(classes).some((k) => k.startsWith(`${key}.`))) visit(f.type, `${key}.`);
+      else diag(hasDefault ? "info" : "warning", "W_OUTCOME_UNCLASSIFIED", at, `result case "${key}" has no class${hasDefault ? " (falls back to default)" : ""}`);
+    }
+  };
+  visit(m.results[0], "");
+}