@meantjs/consent 0.0.0-stage → 0.2.0

package/src/model.mjs

@@ -0,0 +1,165 @@
+// The neutral model of one consent message: a title, an optional sentence (the rendered intent template as
+// literal and field parts) and the fields. Both ICRC-21 forms are rendered from it (render.mjs), so they cannot
+// disagree about which values the call carries.
+//
+// Which fields appear:
+//   - a call with an intent, its case's (spec section 5.2, D-053) or else its method's: the placeholders of its template
+//     that are present (spec section 6; section 12: "one (label, Value) row per placeholder"), in template order,
+//     once per distinct path;
+//   - a call without one: the generic intent. Title from `describe.label` of the method, else `Call <method>`;
+//     one field per leaf of the decoded arguments (records are flattened, tagged positions such as accounts are
+//     leaves, absent optionals are left out). More than MAX_FIELDS fields or MAX_ELEMENTS list elements is
+//     refused (E_TOO_LARGE), never truncated.
+
+import { VALUE_TAGS } from "@meantjs/format";
+import { decodeArguments } from "./decode.mjs";
+import { CODES, ConsentError, fail } from "./errors.mjs";
+import { callTag, effectKind, entriesOf, labelOf, methodOf } from "./resolved.mjs";
+import { parseTemplate } from "./template.mjs";
+import { resolvePath, valuesAt } from "./paths.mjs";
+
+export const MAX_FIELDS = 64;
+export const MAX_ELEMENTS = 256;
+
+/**
+ * @typedef {object} Field
+ * @property {string} path  the placeholder path, or the dotted path of a flattened leaf
+ * @property {string} label  describe.label of the position, else its field name (raw, not yet escaped)
+ * @property {object} node  the resolved-form position
+ * @property {unknown[]} values  the present values: none (absent), one, or one per list element
+ *
+ * @typedef {{ lit: string } | { field: Field }} SentencePart
+ *
+ * @typedef {object} Model
+ * @property {string} method
+ * @property {string} effect  the effect kind of the call: its case's, else its method's (spec section 5.3, D-053)
+ * @property {string} title
+ * @property {SentencePart[] | null} sentence  null for a call without an intent template
+ * @property {Field[]} fields
+ * @property {object[]} argNodes
+ * @property {unknown[]} argValues
+ * @property {object[]} diagnostics
+ * @property {{ intent: { origin: string, profile?: string } | null, profiles: object[] }} provenance  where the words come from
+ *   (ICRC-49: a signer warns when it, not the canister, wrote the message; spec section 11 item 1: a profile is a claim)
+ */
+
+/**
+ * @param {{ resolved: object, method: string, arg: Uint8Array | ArrayBuffer | number[], limits?: object }} input
+ * @returns {Model}
+ */
+export function buildModel({ resolved, method: name, arg, limits }) {
+  const method = methodOf(resolved, name);
+  return modelOf(resolved, name, method, decodeArguments(method, arg, limits));
+}
+
+/** The model of a call whose arguments are decoded already (evm.mjs decodes calldata, then comes here). */
+export function modelOf(resolved, name, method, argValues) {
+  const diagnostics = [];
+  const intentTag = callTag(method, argValues, "intent"); // the call's intent: its case's, else its method's (D-053)
+  const intent = intentTag?.args;
+  const title = typeof intent?.title === "string" && intent.title.trim() !== "" ? intent.title : (labelOf(method) ?? `Call ${name}`);
+  const tagOrigin = intent ? { origin: intentTag.origin, ...(intentTag.profile === undefined ? {} : { profile: intentTag.profile }) } : null;
+  const provenance = { intent: tagOrigin, profiles: Array.isArray(resolved.profiles) ? resolved.profiles : [] };
+  const base = { method: name, effect: effectKind(method, callTag(method, argValues, "effect")), title, argNodes: method.args, argValues, diagnostics, provenance };
+
+  if (intent && typeof intent.template === "string") {
+    try {
+      const { sentence, fields } = applyTemplate(method, argValues, parseTemplate(intent.template));
+      return { ...base, sentence, fields };
+    } catch (e) {
+      // A template the profile got wrong must not leave the user without a message: fall back to the generic
+      // intent, which lists every argument, and say so.
+      if (!(e instanceof ConsentError) || (e.code !== CODES.TEMPLATE && e.code !== CODES.TEMPLATE_PATH)) throw e;
+      diagnostics.push({ code: "W_TEMPLATE_FALLBACK", at: name, message: `${e.code}: ${e.message}; the generic intent is used instead` });
+    }
+  }
+  return { ...base, sentence: null, fields: flatten(method, argValues) };
+}
+
+// ---------------------------------------------------------------------------------------------- template
+
+function nameOf(path, resolvedPath) {
+  for (let i = resolvedPath.steps.length - 1; i >= 0; i--) {
+    const s = resolvedPath.steps[i];
+    if (s.kind !== "elem") return s.key;
+  }
+  return `Argument ${resolvedPath.index + 1}`;
+}
+
+function applyTemplate(method, argValues, parts) {
+  const known = new Map(); // path -> Field
+  const sentence = [];
+  const fields = [];
+
+  const lookup = (path) => {
+    const hit = known.get(path);
+    if (hit) return { field: hit, fresh: false };
+    const rp = resolvePath(method, path);
+    if (rp.error) return { error: rp.error };
+    const values = valuesAt(rp, argValues);
+    if (values.length > MAX_ELEMENTS) fail(CODES.TOO_LARGE, `{${path}} has ${values.length} values; the limit is ${MAX_ELEMENTS}`);
+    return { field: { path, label: labelOf(rp.node) ?? nameOf(path, rp), node: rp.node, values }, fresh: true };
+  };
+  const register = ({ field, fresh }) => {
+    if (!fresh) return field;
+    known.set(field.path, field);
+    fields.push(field);
+    if (fields.length > MAX_FIELDS) fail(CODES.TOO_LARGE, `the template has more than ${MAX_FIELDS} distinct placeholders`);
+    return field;
+  };
+
+  for (const part of parts) {
+    if (part.t === "lit") sentence.push({ lit: part.text });
+    else if (part.t === "ph") {
+      const found = lookup(part.path);
+      if (found.error) fail(CODES.TEMPLATE_PATH, `{${part.path}}: ${found.error}`);
+      sentence.push({ field: register(found) });
+    } else {
+      // [ ... ]: dropped when any placeholder inside is absent (null) or names a position this method lacks.
+      const looked = part.parts.map((p) => (p.t === "ph" ? lookup(p.path) : null));
+      const unresolved = looked.find((l) => l?.error);
+      if (unresolved || looked.some((l) => l && l.field.values.length === 0)) continue;
+      for (let i = 0; i < part.parts.length; i++) {
+        const p = part.parts[i];
+        sentence.push(p.t === "lit" ? { lit: p.text } : { field: register(looked[i]) });
+      }
+    }
+  }
+  return { sentence, fields };
+}
+
+// ---------------------------------------------------------------------------------------------- generic intent
+
+const hasValueTag = (node) => VALUE_TAGS.some((t) => node.tags && Object.hasOwn(node.tags, t));
+
+/**
+ * Field order of the resolved form is canonical id order (spec section 10), which reads as random. `ui.order`
+ * ("use ui.order for presentation") puts the fields that have one first, ascending; the rest keep id order.
+ */
+function presentationOrder(entries) {
+  const order = (child) => {
+    const n = child.tags?.ui?.args?.order;
+    return Number.isFinite(n) ? n : Infinity;
+  };
+  return entries.map((e, i) => ({ e, i })).sort((a, b) => order(a.e[1]) - order(b.e[1]) || a.i - b.i).map(({ e }) => e);
+}
+
+function flatten(method, argValues) {
+  const fields = [];
+  const multi = method.args.length > 1;
+  const emit = (node, value, keys, index) => {
+    const dotted = keys.join(".");
+    const label = labelOf(node) ?? (multi ? `Argument ${index + 1}${dotted ? ` ${dotted}` : ""}` : dotted || `Argument ${index + 1}`);
+    if (node.candid === "vec" && value.length > MAX_ELEMENTS) fail(CODES.TOO_LARGE, `${label} has ${value.length} elements; the limit is ${MAX_ELEMENTS}`);
+    fields.push({ path: `(${index})${keys.map((k) => `.${k}`).join("")}`, label, node, values: [value] });
+    if (fields.length > MAX_FIELDS) fail(CODES.TOO_LARGE, `the arguments have more than ${MAX_FIELDS} fields`);
+  };
+  const walk = (node, value, keys, index) => {
+    if (node.optional === true && value === null) return;
+    const children = node.candid === "record" && node.recursive !== true && !hasValueTag(node) ? presentationOrder(entriesOf(node.fields)) : [];
+    if (children.length > 0) for (const [key, child] of children) walk(child, value[key], [...keys, key], index);
+    else emit(node, value, keys, index);
+  };
+  method.args.forEach((node, i) => walk(node, argValues[i], [], i));
+  return fields;
+}

package/src/paths.mjs

@@ -0,0 +1,74 @@
+// Placeholder paths (docs/profile-v0.md section 3.2 rule 9): `{amount}`, `{to.owner}`, `{(0).amount}`, `{items[]}`.
+// A relpath resolves against the method's argument tuple; with one argument it is relative to argument 0.
+//
+// Beyond what section 6 says (decisions of this package, listed in the README):
+//   - a path that crosses a variant case selects that case; when the value has another case the placeholder is absent;
+//   - a path that crosses `[]` yields one value per element (absent elements dropped);
+//   - a path the method does not have is "unresolved": absent inside `[ ... ]`, an error outside (the resolver
+//     already reports it as E_TEMPLATE_PATH; a pack placeholder the service lacks is skipped by the resolver).
+
+import { parseRelPath } from "@meantjs/profile/address";
+import { entriesOf, keyId } from "./resolved.mjs";
+
+/**
+ * @typedef {{ kind: "field" | "case", key: string } | { kind: "elem" }} Step
+ * @typedef {{ index: number, steps: Step[], node: object, nodes: object[] }} ResolvedPath
+ */
+
+/** @returns {ResolvedPath | { error: string }} */
+export function resolvePath(method, relpath) {
+  const parsed = parseRelPath(relpath);
+  if (!parsed) return { error: `bad relative path ${JSON.stringify(relpath)}` };
+  let index = parsed.index;
+  if (index === null) {
+    if (method.args.length !== 1) return { error: `path ${JSON.stringify(relpath)} must start with (i): the method has ${method.args.length} arguments` };
+    index = 0;
+  }
+  if (index >= method.args.length) return { error: `argument index ${index} is out of range` };
+  let node = method.args[index];
+  const nodes = [node];
+  const steps = [];
+  for (const seg of parsed.segs) {
+    if (node.recursive === true) return { error: `${JSON.stringify(relpath)} enters a position the resolved form cuts at a cycle` };
+    if (seg.kind === "elem") {
+      if (node.candid !== "vec" || node.element === undefined) return { error: `"[]" applied to ${node.candid}` };
+      steps.push({ kind: "elem" });
+      node = node.element;
+    } else {
+      const field = entriesOf(node.fields).find(([key]) => keyId(key) === seg.id);
+      const arm = field === undefined ? entriesOf(node.cases).find(([key]) => keyId(key) === seg.id) : undefined;
+      const hit = field ?? arm;
+      if (hit === undefined) return { error: `no field or case ${JSON.stringify(seg.label)} in ${node.candid}` };
+      steps.push({ kind: field ? "field" : "case", key: hit[0] });
+      node = hit[1];
+    }
+    nodes.push(node);
+  }
+  return { index, steps, node, nodes };
+}
+
+/**
+ * The present values at a resolved path. An absent optional anywhere on the way (null), a variant with another
+ * case, or an empty vector gives no values.
+ *
+ * @param {ResolvedPath} path
+ * @param {unknown[]} values  the decoded argument trees
+ * @returns {unknown[]}
+ */
+export function valuesAt(path, values) {
+  let current = [values[path.index]];
+  for (let depth = 0; depth < path.steps.length; depth++) {
+    const step = path.steps[depth];
+    const parentNode = path.nodes[depth];
+    const next = [];
+    for (const v of current) {
+      if (parentNode.optional === true && v === null) continue;
+      if (step.kind === "elem") next.push(...v);
+      else if (step.kind === "field") next.push(v[step.key]);
+      else if (v.tag === step.key) next.push(v.value);
+    }
+    current = next;
+  }
+  const leaf = path.node;
+  return current.filter((v) => !(leaf.optional === true && v === null));
+}

package/src/render.mjs

@@ -0,0 +1,104 @@
+// The two ICRC-21 forms from a Model (docs/profile-v0.md section 12).
+//
+// FieldsDisplayMessage (plain text, no formatting; times are UTC seconds, so the message does not depend on the
+// user's time zone):
+//   intent  = title + ": " + the rendered template      (no template: the title alone)
+//   fields  = one (label, Value) row per placeholder; label = describe.label, else the field name
+//
+// GenericDisplayMessage (Markdown, the layout of the ICRC-21 examples: a `#` title, one paragraph, then
+// `**label:**` lines). Every value comes from the call, which the relying party controls, so it goes into a
+// code span, where Markdown is not parsed. Template text and labels come from the profile and are plain text:
+// their Markdown punctuation is escaped.
+
+import { codeBlock, codeSpan, emptyMarkdown, escapeLineStart, escapeMarkdown, oneLine, visible } from "./text.mjs";
+
+const NONE_PLAIN = "(none)";
+const NONE_MARKDOWN = "*(none)*";
+
+/** Label and title: one line, trimmed, never empty. */
+function plainLabel(raw, fallback) {
+  const s = oneLine(raw).trim();
+  return s === "" ? fallback : s;
+}
+
+/** The text of a field's values, plain: the values joined by ", ", or "(none)". */
+function fieldPlain(field, renderer) {
+  if (field.values.length === 0) return NONE_PLAIN;
+  return field.values.map((v, i) => visible(renderer.text(field.node, v, field.path + (field.values.length > 1 ? `[${i}]` : "")))).join(", ");
+}
+
+function fieldMarkdown(field, renderer) {
+  if (field.values.length === 0) return NONE_MARKDOWN;
+  return field.values.map((v, i) => codeSpan(renderer.text(field.node, v, field.path + (field.values.length > 1 ? `[${i}]` : "")))).join(", ");
+}
+
+/**
+ * @param {import("./model.mjs").Model} model
+ * @param {import("./display.mjs").Renderer} renderer  UTC (no zone)
+ * @param {{ rawArguments?: boolean }} [options]
+ * @returns {{ intent: string, fields: Array<[string, object]> }}
+ */
+export function renderFields(model, renderer, { rawArguments = false } = {}) {
+  const title = plainLabel(model.title, model.method);
+  let intent = title;
+  if (model.sentence !== null) {
+    const sentence = model.sentence.map((p) => ("lit" in p ? oneLine(p.lit) : fieldPlain(p.field, renderer))).join("");
+    if (sentence.trim() !== "") intent = `${title}: ${sentence.trim()}`;
+  }
+  const fields = model.fields.map((f) => [plainLabel(f.label, f.path), fieldValue(f, renderer)]);
+  if (rawArguments) fields.push(["Raw arguments", { Text: { content: visible(renderer.tupleText(model.argNodes, model.argValues)) } }]);
+  return { intent, fields };
+}
+
+/**
+ * The fields form as plain text, for a message that is not ICRC-21's (an EVM call, spec section 15): the same intent
+ * line as renderFields, and each row's values joined by ", ".
+ *
+ * @returns {{ intent: string, fields: Array<[string, string]> }}
+ */
+export function renderPlain(model, renderer, { rawArguments = false } = {}) {
+  const title = plainLabel(model.title, model.method);
+  let intent = title;
+  if (model.sentence !== null) {
+    const sentence = model.sentence.map((p) => ("lit" in p ? oneLine(p.lit) : fieldPlain(p.field, renderer))).join("");
+    if (sentence.trim() !== "") intent = `${title}: ${sentence.trim()}`;
+  }
+  const fields = model.fields.map((f) => [plainLabel(f.label, f.path), fieldPlain(f, renderer)]);
+  if (rawArguments) fields.push(["Raw arguments", visible(renderer.tupleText(model.argNodes, model.argValues))]);
+  return { intent, fields };
+}
+
+/** One row's ICRC-21 Value: typed when the field is a single value the typed form carries exactly, else Text. */
+function fieldValue(field, renderer) {
+  if (field.values.length === 1) {
+    const v = renderer.icrc21Value(field.node, field.values[0], field.path);
+    if (v.Text) v.Text.content = visible(v.Text.content);
+    return v;
+  }
+  return { Text: { content: fieldPlain(field, renderer) } };
+}
+
+/**
+ * @param {import("./model.mjs").Model} model
+ * @param {import("./display.mjs").Renderer} renderer  zoned when the request carried a utc_offset_minutes
+ * @param {{ rawArguments?: boolean, headingLevel?: number }} [options]  `headingLevel`: the title's heading level
+ *   (default 1; an SNS validator rendering sits under governance's own `##` headings and uses 3)
+ * @returns {string}
+ */
+export function renderGeneric(model, renderer, { rawArguments = false, headingLevel = 1 } = {}) {
+  const blocks = [`${"#".repeat(headingLevel)} ${escapeMarkdown(plainLabel(model.title, model.method))}`];
+  if (model.sentence !== null) {
+    let paragraph = model.sentence.map((p) => ("lit" in p ? escapeMarkdown(oneLine(p.lit)) : fieldMarkdown(p.field, renderer))).join("").trim();
+    if (model.sentence[0] && "lit" in model.sentence[0]) paragraph = escapeLineStart(paragraph);
+    if (paragraph !== "") blocks.push(paragraph);
+  }
+  if (model.fields.length > 0) {
+    blocks.push(model.fields.map((f) => `- **${escapeMarkdown(plainLabel(f.label, f.path))}:** ${fieldMarkdown(f, renderer)}`).join("\n"));
+  } else if (model.sentence === null) {
+    blocks.push("This call has no arguments.");
+  }
+  if (rawArguments) blocks.push(`**Raw arguments:**\n\n${codeBlock(renderer.tupleText(model.argNodes, model.argValues))}`);
+  return blocks.join("\n\n");
+}
+
+export { emptyMarkdown };

package/src/resolved.mjs

@@ -0,0 +1,102 @@
+// Read-only accessors over the resolved form (docs/profile-v0.md section 10). The resolved form is data from
+// a resolver, so nothing here trusts its shape beyond what the code reads.
+
+import { idlHash } from "@meantjs/profile/address";
+import { CODES, fail } from "./errors.mjs";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * The method entry of a resolved form, or a ConsentError. `chain` is "evm" for an EVM contract's form (spec section 15);
+ * a Candid entry point never reads one, whose positions are ABI types, not Candid.
+ */
+export function methodOf(resolved, name, chain = undefined) {
+  if (!isObject(resolved) || resolved.format !== "candid-profile-resolved" || !isObject(resolved.methods)) {
+    fail(CODES.RESOLVED_FORM, "not a candid-profile-resolved document (format, methods)");
+  }
+  if (resolved.chain !== chain) {
+    fail(CODES.RESOLVED_FORM, resolved.chain === "evm" ? "this resolved form is an EVM contract's (chain evm): use evmConsent, not a Candid entry point" : `expected the resolved form of an EVM contract (chain evm), found ${resolved.chain === undefined ? "a Candid service's" : `chain ${JSON.stringify(resolved.chain)}`}`);
+  }
+  if (typeof name !== "string" || !Object.hasOwn(resolved.methods, name)) {
+    fail(CODES.METHOD_UNKNOWN, `the resolved form has no method ${JSON.stringify(String(name))}`);
+  }
+  const m = resolved.methods[name];
+  if (!isObject(m) || !Array.isArray(m.args)) fail(CODES.RESOLVED_FORM, `method ${name} has no args array`);
+  return m;
+}
+
+/** The Candid field or case id of a resolved-form key: `#123` is the raw id, any other key is a name. */
+export function keyId(key) {
+  return /^#(0|[1-9][0-9]{0,9})$/.test(key) ? Number(key.slice(1)) : idlHash(key);
+}
+
+/**
+ * A position of an EVM contract's resolved form (spec section 15) read as the Candid shapes the model walks: a tuple is
+ * a record, an array a vec, any other ABI type a primitive of that name. `abi` is kept, so display writes ABI text.
+ */
+export function abiView(node, where, depth = 0) {
+  if (!isObject(node) || typeof node.abi !== "string") fail(CODES.RESOLVED_FORM, `${where}: not an EVM resolved-form position`);
+  if (depth > 64) fail(CODES.UNSUPPORTED_TYPE, `${where}: nested deeper than 64`);
+  if (node.abi === "tuple") {
+    return { ...node, candid: "record", fields: Object.fromEntries(entriesOf(node.fields).map(([k, c]) => [k, abiView(c, `${where}.${k}`, depth + 1)])) };
+  }
+  if (node.abi === "array") return { ...node, candid: "vec", element: abiView(node.element, `${where}[]`, depth + 1) };
+  return { ...node, candid: node.abi };
+}
+
+/** Own entries of a `fields` or `cases` object (never walks the prototype chain). */
+export function entriesOf(bucket) {
+  return isObject(bucket) ? Object.entries(bucket) : [];
+}
+
+/** `describe.label` of a position or method, when it is a non-empty string. */
+export function labelOf(node) {
+  const label = node?.tags?.describe?.args?.label;
+  return typeof label === "string" && label.trim() !== "" ? label : undefined;
+}
+
+export function tagArgs(node, tag) {
+  return node?.tags && Object.hasOwn(node.tags, tag) ? (node.tags[tag]?.args ?? {}) : undefined;
+}
+
+/**
+ * The effect kind of a call: its effect tag (the call's, `callTag`; the method's by default), or the spec default
+ * (section 5.3: queries read, updates write).
+ */
+export function effectKind(method, tag = method.tags?.effect) {
+  return tag?.args?.kind ?? (method.mode === "query" || method.mode === "composite_query" ? "read" : "write");
+}
+
+/**
+ * The `intent` or `effect` entry (`{ args, origin, profile }`) a call takes: that of the deepest tagged variant case
+ * its decoded arguments hold (spec section 5.2, D-053), else the method's. The resolver lets the tagged cases of one
+ * method only exclude each other or nest, so the cases one call holds are a chain; a resolved form with tagged cases
+ * that one call holds side by side is not one a resolver writes, and the method's entry is used for it.
+ *
+ * @param {object} method  a method of the resolved form
+ * @param {unknown[]} argValues  its decoded arguments (decode.mjs: records by key, variants as { tag, value })
+ * @param {"intent" | "effect"} tag
+ */
+export function callTag(method, argValues, tag) {
+  let best = null; // { entry, chain }: the hit with the most hits above and at it
+  let hits = 0;
+  const visit = (node, value, chain) => {
+    if (!isObject(node) || node.recursive === true || !isObject(value)) return; // null: an absent optional, a bare case
+    if (node.candid === "record") {
+      for (const [key, child] of entriesOf(node.fields)) if (Object.hasOwn(value, key)) visit(child, value[key], chain);
+    } else if (node.candid === "variant") {
+      const hit = entriesOf(node.cases).find(([key]) => key === value.tag);
+      if (hit === undefined) return;
+      const child = hit[1];
+      const entry = isObject(child) && isObject(child.tags) && Object.hasOwn(child.tags, tag) ? child.tags[tag] : undefined;
+      if (isObject(entry)) {
+        chain += 1;
+        hits += 1;
+        if (best === null || chain > best.chain) best = { entry, chain };
+      }
+      visit(child, value.value, chain);
+    }
+  };
+  method.args.forEach((node, i) => visit(node, argValues[i], 0));
+  return best !== null && best.chain === hits ? best.entry : method.tags?.[tag];
+}

package/src/sns.d.mts

@@ -0,0 +1,54 @@
+// Types for @meantjs/consent/sns (Node only: it hashes with node:crypto). Hand-written; the source is
+// src/sns.mjs. test/types.test.mjs keeps the declared names equal to the runtime exports.
+import type { Bytes, ConsentDiagnostic, DecodeLimits, Provenance, ResolvedForm } from "./index.mjs";
+
+export type ValidatorResult = { Ok: string } | { Err: string };
+
+/** The name and version of the rules a rendering follows; part of every rendering. */
+export const SNS_RENDERING_RULES: "candid-profile-sns/v0";
+
+/** An SNS generic-function validator as a function, with non-enumerable `diagnostics` and `provenance`. */
+export function snsValidatorRendering(input: {
+  /** The target method's Candid argument bytes, as governance passes them. */
+  payload: Bytes;
+  resolved: ResolvedForm;
+  /** The target method this validator is registered for. */
+  method: string;
+  refs?: Record<string, unknown>;
+  limits?: DecodeLimits;
+}): ValidatorResult & { readonly diagnostics: ConsentDiagnostic[]; readonly provenance: Provenance };
+/** The canister-side wrapper: payload bytes in, the Candid-encoded `variant { Ok : text; Err : text }` out. */
+export function handleSnsValidatorCall(payload: Uint8Array, context: { resolved: ResolvedForm; method: string; refs?: Record<string, unknown>; limits?: DecodeLimits }): Uint8Array;
+export function encodeValidatorResult(result: ValidatorResult): Uint8Array;
+export function decodeValidatorResult(bytes: Uint8Array): ValidatorResult;
+
+export interface GovernanceRendering {
+  functionText: string;
+  payloadSha256: string;
+  payloadRendering: string;
+  targetMethod: string | null;
+  targetCanisterId: string | null;
+  validatorMethod: string | null;
+  validatorCanisterId: string | null;
+}
+/** A stored `payload_text_rendering` split into governance's parts, or null when it is not governance's layout. */
+export function parseGovernanceRendering(text: string): GovernanceRendering | null;
+
+export interface SnsCheck {
+  name: string;
+  ok: boolean;
+  expected?: string;
+  found?: string | null;
+  note?: string;
+}
+/** The reviewer's check of a stored proposal rendering against what the profile renders for the payload. */
+export function verifySnsRendering(input: {
+  payloadTextRendering: string;
+  payload: Bytes;
+  resolved: ResolvedForm;
+  /** The canister the reviewer expects governance to call, as text. */
+  targetCanisterId: string;
+  method: string;
+  refs?: Record<string, unknown>;
+  limits?: DecodeLimits;
+}): { ok: boolean; checks: SnsCheck[]; expectedRendering: string | null; parsed: GovernanceRendering | null };