@meantjs/consent 0.0.0-stage → 0.1.0

package/src/icrc21.mjs

@@ -0,0 +1,139 @@
+// The ICRC-21 entry point: `icrc21_canister_call_consent_message` as a function.
+//
+// Request  : { method, arg, user_preferences: { metadata: { language, utc_offset_minutes }, device_spec } }
+// Response : { Ok: { consent_message, metadata } } | { Err: { UnsupportedCanisterCall | ConsentMessageUnavailable
+//            | InsufficientPayment | GenericError } }                       (shapes: see icrc21-codec.mjs)
+//
+// Behaviors the ICRC-21 text fixes (topics/ICRC-21/ICRC-21.did and icrc_21_consent_msg.md of dfinity/wg-identity-authentication):
+//   - "Providing a message should be preferred over sending an icrc21_error": a language other than English gets the
+//     English message, and `metadata.language` says "en" ("the metadata must match the consent_message provided").
+//     Set `languagePolicy: "error"` to refuse instead (UnsupportedCanisterCall).
+//   - A missing `device_spec` falls back to GenericDisplay (the spec: "one of the values defined in this spec").
+//   - `utc_offset_minutes` absent in the request: the generic message is in UTC. Absent in the response means the
+//     message is not time-zone sensitive; the response carries the applied offset exactly when a time is shown in
+//     the generic form. The fields form carries seconds since the epoch and is never zone-sensitive.
+//   - The consent message must not depend on state: this function has no network access; dynamic refs (decimals,
+//     symbol) are values the caller resolved (spec section 4).
+
+import { bytesOf } from "./bytes.mjs";
+import { ConsentError, CODES, GENERIC_ERROR_CODES } from "./errors.mjs";
+import { generateConsent } from "./consent.mjs";
+import { decodeConsentRequest, encodeConsentResponse } from "./icrc21-codec.mjs";
+
+/** The only language v0 emits (profile `language: "en"`; spec section 1: multi-language templates are a non-goal). */
+export const SUPPORTED_LANGUAGE = "en";
+const MAX_OFFSET_MINUTES = 24 * 60;
+const MAX_DESCRIPTION = 1000;
+
+const BCP47 = /^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{1,8})*$/;
+
+/**
+ * @param {object} request  the ICRC-21 request in the JS shape
+ * @param {object} context
+ * @param {object} context.resolved  the resolved form of the target canister (docs/profile-v0.md section 10)
+ * @param {Record<string, unknown>} [context.refs]  resolved dynamic refs, keyed by `from`: { "query:icrc1_decimals": 8, "query:icrc1_symbol": "ICP" }
+ * @param {"fallback" | "error"} [context.languagePolicy]  default "fallback" (the ICRC-21 preference)
+ * @param {boolean} [context.rawArguments]  append the decoded raw arguments (spec section 11 item 1)
+ * @param {object} [context.limits]  decoder limits
+ * @returns {{ Ok: object } | { Err: object }}  plus two non-enumerable properties on the result: `diagnostics` (what was
+ *   adjusted on the way: format fallbacks, language fallback) and `provenance` (`{ intent: { origin, profile } | null, profiles }`,
+ *   so a signer can warn when the words come from a profile and not from the canister)
+ */
+export function icrc21ConsentMessage(request, context) {
+  const diagnostics = [];
+  const extras = { provenance: null };
+  let result;
+  try {
+    result = { Ok: build(request, context, diagnostics, extras) };
+  } catch (e) {
+    result = { Err: toIcrc21Error(e) };
+    diagnostics.push({ code: e instanceof ConsentError ? e.code : "E_INTERNAL", at: "request", message: String(e?.message ?? e) });
+  }
+  Object.defineProperty(result, "diagnostics", { value: diagnostics, enumerable: false });
+  Object.defineProperty(result, "provenance", { value: extras.provenance, enumerable: false });
+  return result;
+}
+
+function build(request, context, diagnostics, extras) {
+  const { resolved, refs = {}, languagePolicy = "fallback", rawArguments = false, limits } = context ?? {};
+  if (request === null || typeof request !== "object") throw new ConsentError(CODES.REQUEST, "the request is not an object");
+  const { method, user_preferences: prefs } = request;
+  const arg = bytesOf(request.arg);
+  if (typeof method !== "string") throw new ConsentError(CODES.REQUEST, "request.method must be text");
+  if (arg === null) throw new ConsentError(CODES.REQUEST, "request.arg must be bytes: a Uint8Array, an ArrayBuffer or an array of integers 0 to 255");
+  const language = prefs?.metadata?.language;
+  if (typeof language !== "string") throw new ConsentError(CODES.REQUEST, "user_preferences.metadata.language must be text");
+
+  // language
+  const primary = BCP47.test(language) ? language.split(/[-_]/)[0].toLowerCase() : null;
+  if (primary !== SUPPORTED_LANGUAGE && languagePolicy === "error") {
+    throw new ConsentError(CODES.LANGUAGE, `language ${JSON.stringify(language.slice(0, 40))} is not supported; this generator writes "${SUPPORTED_LANGUAGE}"`);
+  }
+  const answeredLanguage = primary === SUPPORTED_LANGUAGE ? language.replace("_", "-") : SUPPORTED_LANGUAGE;
+  if (primary !== SUPPORTED_LANGUAGE) diagnostics.push({ code: "I_LANGUAGE_FALLBACK", at: "user_preferences", message: `language ${JSON.stringify(language.slice(0, 40))} is not supported; the message is in "${SUPPORTED_LANGUAGE}" and the metadata says so` });
+
+  // device spec
+  const spec = deviceSpecOf(prefs.device_spec);
+
+  // time zone
+  let offset = prefs.metadata.utc_offset_minutes ?? null;
+  if (offset !== null && (!Number.isInteger(offset) || Math.abs(offset) > MAX_OFFSET_MINUTES)) {
+    diagnostics.push({ code: "W_UTC_OFFSET_IGNORED", at: "user_preferences", message: `utc_offset_minutes ${String(offset)} is outside +-${MAX_OFFSET_MINUTES}; UTC is used` });
+    offset = null;
+  }
+
+  const r = generateConsent({ resolved, method, arg, refs, form: spec === "FieldsDisplay" ? "fields" : "generic", utcOffsetMinutes: offset, rawArguments, limits });
+  diagnostics.push(...r.diagnostics);
+  extras.provenance = r.provenance;
+  return {
+    consent_message: r.message,
+    metadata: { language: answeredLanguage, utc_offset_minutes: r.zoneSensitive ? (offset ?? 0) : null },
+  };
+}
+
+function deviceSpecOf(spec) {
+  if (spec === undefined || spec === null) return "GenericDisplay";
+  if (spec === "GenericDisplay" || spec === "FieldsDisplay") return spec;
+  const keys = typeof spec === "object" ? Object.keys(spec) : [];
+  if (keys.length === 1 && (keys[0] === "GenericDisplay" || keys[0] === "FieldsDisplay")) return keys[0];
+  throw new ConsentError(CODES.REQUEST, "device_spec must be GenericDisplay or FieldsDisplay");
+}
+
+const clip = (s) => (s.length > MAX_DESCRIPTION ? `${s.slice(0, MAX_DESCRIPTION)}...` : s);
+
+/** ConsentError (or any thrown value) -> the ICRC-21 `icrc21_error` variant. */
+export function toIcrc21Error(e) {
+  if (!(e instanceof ConsentError)) return { GenericError: { error_code: GENERIC_ERROR_CODES.INTERNAL, description: clip(`internal error: ${String(e?.message ?? e)}`) } };
+  const description = clip(`${e.code}: ${e.message}`);
+  switch (e.code) {
+    case CODES.METHOD_UNKNOWN:
+    case CODES.DECODE:
+    case CODES.TOO_LARGE:
+    case CODES.LANGUAGE:
+    case CODES.REQUEST:
+      return { UnsupportedCanisterCall: { description } };
+    case CODES.UNSUPPORTED_TYPE:
+      return { ConsentMessageUnavailable: { description } };
+    default:
+      return { GenericError: { error_code: GENERIC_ERROR_CODES[e.code] ?? GENERIC_ERROR_CODES.INTERNAL, description } };
+  }
+}
+
+/**
+ * The canister-side wrapper: the Candid-encoded argument of `icrc21_canister_call_consent_message` in, the
+ * Candid-encoded `icrc21_consent_message_response` out. A request that does not decode gets an
+ * UnsupportedCanisterCall reply, as the ICRC-21 interface prescribes for a malformed call.
+ *
+ * @param {Uint8Array} requestBytes
+ * @param {object} context  as for icrc21ConsentMessage
+ * @returns {Uint8Array}
+ */
+export function handleConsentRequest(requestBytes, context) {
+  let response;
+  try {
+    response = icrc21ConsentMessage(decodeConsentRequest(requestBytes), context);
+  } catch (e) {
+    response = { Err: toIcrc21Error(e) };
+  }
+  return encodeConsentResponse(response);
+}

package/src/index.d.mts

@@ -0,0 +1,234 @@
+// Types for @meantjs/consent. Hand-written; the source is plain ES modules (src/*.mjs).
+// test/types.test.mjs keeps the declared names equal to the runtime exports, and `npm run types` compiles a consumer
+// against these declarations under strict TypeScript.
+import type { Formatter } from "@meantjs/format";
+
+/** A candid-profile-resolved v0 document (docs/profile-v0.md section 10). */
+export interface ResolvedForm {
+  format: "candid-profile-resolved";
+  format_version: 0;
+  methods: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/** Argument bytes as this package takes them. */
+export type Bytes = Uint8Array | ArrayBuffer | readonly number[];
+
+export interface DecodeLimits {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxElements?: number;
+}
+
+// ------------------------------------------------------------------ the ICRC-21 shapes (ICRC-21.did, JS shape)
+// A variant is { Tag: payload }, opt T is null or the value, nat and nat64 are bigint, nat8 and int16 numbers.
+
+export interface Icrc21Metadata {
+  language: string;
+  utc_offset_minutes: number | null;
+}
+export type Icrc21DeviceSpec = { GenericDisplay: null } | { FieldsDisplay: null };
+export interface Icrc21ConsentMessageSpec {
+  metadata: Icrc21Metadata;
+  device_spec: Icrc21DeviceSpec | null;
+}
+export interface Icrc21ConsentMessageRequest {
+  method: string;
+  arg: Uint8Array;
+  user_preferences: Icrc21ConsentMessageSpec;
+}
+export type Icrc21Value =
+  | { TokenAmount: { decimals: number; amount: bigint; symbol: string } }
+  | { TimestampSeconds: { amount: bigint } }
+  | { DurationSeconds: { amount: bigint } }
+  | { Text: { content: string } };
+export type Icrc21ConsentMessage =
+  | { GenericDisplayMessage: string }
+  | { FieldsDisplayMessage: { intent: string; fields: [string, Icrc21Value][] } };
+export interface Icrc21ConsentInfo {
+  consent_message: Icrc21ConsentMessage;
+  metadata: Icrc21Metadata;
+}
+export type Icrc21Error =
+  | { UnsupportedCanisterCall: { description: string } }
+  | { ConsentMessageUnavailable: { description: string } }
+  | { InsufficientPayment: { description: string } }
+  | { GenericError: { error_code: bigint; description: string } };
+export type Icrc21ConsentMessageResponse = { Ok: Icrc21ConsentInfo } | { Err: Icrc21Error };
+
+/** Where the words of a message come from (ICRC-49: a signer warns when a profile, not the canister, wrote them). */
+export interface Provenance {
+  intent: { origin: string; profile?: string } | null;
+  profiles: unknown[];
+}
+export interface ConsentDiagnostic {
+  code: string;
+  at: string;
+  message: string;
+  [key: string]: unknown;
+}
+
+export interface Icrc21Context {
+  resolved: ResolvedForm;
+  /** Resolved dynamic refs, keyed by `from`: `{ "query:icrc1_decimals": 8, "query:icrc1_symbol": "ICP" }`. */
+  refs?: Record<string, unknown>;
+  /** Default "fallback" (the ICRC-21 preference). */
+  languagePolicy?: "fallback" | "error";
+  /** Append the decoded raw arguments (spec section 11 item 1). */
+  rawArguments?: boolean;
+  limits?: DecodeLimits;
+}
+
+/** The response, with two non-enumerable properties: what was adjusted, and where the words come from. */
+export type Icrc21Result = Icrc21ConsentMessageResponse & { readonly diagnostics: ConsentDiagnostic[]; readonly provenance: Provenance };
+
+/** The ICRC-21 call as a function. `arg` may also be an ArrayBuffer or an array of byte values. */
+export function icrc21ConsentMessage(request: Omit<Icrc21ConsentMessageRequest, "arg"> & { arg: Bytes }, context: Icrc21Context): Icrc21Result;
+/** Candid bytes of `icrc21_consent_message_request` in, Candid bytes of `icrc21_consent_message_response` out. */
+export function handleConsentRequest(requestBytes: Uint8Array, context: Icrc21Context): Uint8Array;
+/** A ConsentError (or any thrown value) as the ICRC-21 error variant. */
+export function toIcrc21Error(error: unknown): Icrc21Error;
+/** The only language v0 emits. */
+export const SUPPORTED_LANGUAGE: "en";
+
+export function encodeConsentResponse(response: Icrc21ConsentMessageResponse): Uint8Array;
+export function decodeConsentResponse(bytes: Uint8Array): Icrc21ConsentMessageResponse;
+export function encodeConsentRequest(request: Icrc21ConsentMessageRequest): Uint8Array;
+/** Throws E_REQUEST on bytes that are not a request. */
+export function decodeConsentRequest(bytes: Uint8Array): Icrc21ConsentMessageRequest;
+/** A JSON-safe copy: bigint as a decimal string, Uint8Array as `{ hex }`. */
+export function toJson(value: unknown): unknown;
+
+// ------------------------------------------------------------------ one form, and the parts
+
+export interface ModelField {
+  /** The placeholder path, or the dotted path of a flattened leaf. */
+  path: string;
+  /** `describe.label` of the position, else its field name (raw, not yet escaped). */
+  label: string;
+  node: unknown;
+  /** The present values: none (absent), one, or one per list element. */
+  values: unknown[];
+}
+export type SentencePart = { lit: string } | { field: ModelField };
+export interface Model {
+  method: string;
+  /** The method's effect kind (spec section 5.3). */
+  effect: string;
+  title: string;
+  /** null for a method without an intent template. */
+  sentence: SentencePart[] | null;
+  fields: ModelField[];
+  argNodes: unknown[];
+  argValues: unknown[];
+  diagnostics: ConsentDiagnostic[];
+  provenance: Provenance;
+  [key: string]: unknown;
+}
+
+export interface GenerateConsentInput {
+  resolved: ResolvedForm;
+  method: string;
+  /** The Candid-encoded argument tuple. */
+  arg: Bytes;
+  refs?: Record<string, unknown>;
+  /** Default "generic". */
+  form?: "fields" | "generic";
+  /** Generic form only: show timestamps in this zone (default UTC). */
+  utcOffsetMinutes?: number | null;
+  rawArguments?: boolean;
+  limits?: DecodeLimits;
+}
+/** One form without the ICRC-21 envelope. `zoneSensitive` is true when a timestamp was shown in the requested zone. */
+export function generateConsent(input: GenerateConsentInput): {
+  form: "fields" | "generic";
+  message: Icrc21ConsentMessage;
+  zoneSensitive: boolean;
+  diagnostics: ConsentDiagnostic[];
+  provenance: Provenance;
+  model: Model;
+};
+export function buildModel(input: { resolved: ResolvedForm; method: string; arg: Bytes; limits?: DecodeLimits }): Model;
+/** Argument bytes to one value tree per argument. Throws E_DECODE, E_TOO_LARGE, E_UNSUPPORTED_TYPE or E_RESOLVED_FORM. */
+export function decodeArguments(method: { args: unknown[] }, arg: Bytes, limits?: DecodeLimits): unknown[];
+/** The candid-core codec schema of one resolved-form position. */
+export function schemaFor(node: unknown, where?: string, depth?: number): unknown;
+
+export type TemplateLiteralPart = { t: "lit"; text: string } | { t: "ph"; path: string };
+export type TemplatePart = TemplateLiteralPart | { t: "opt"; parts: TemplateLiteralPart[] };
+/** Throws E_TEMPLATE. */
+export function parseTemplate(template: string): TemplatePart[];
+
+export type PathStep = { kind: "field" | "case"; key: string } | { kind: "elem" };
+export interface ResolvedPath {
+  index: number;
+  steps: PathStep[];
+  node: unknown;
+  nodes: unknown[];
+}
+export function resolvePath(method: { args: unknown[] }, relpath: string): ResolvedPath | { error: string };
+/** The present values at a resolved path. */
+export function valuesAt(path: ResolvedPath, values: unknown[]): unknown[];
+
+/** Renders positions as text, with a budget per message. Used by `renderFields` and `renderGeneric`. */
+export declare class Renderer {
+  /** `utcOffsetMinutes` as a number shows timestamps in that zone (the generic form); otherwise UTC. */
+  constructor(options?: { refs?: Record<string, unknown>; utcOffsetMinutes?: number | null; diagnostics?: ConsentDiagnostic[] });
+  refs: Record<string, unknown>;
+  utcOffsetMinutes: number | null;
+  diagnostics: ConsentDiagnostic[];
+  chars: number;
+  /** Set when a timestamp was shown in the requested zone. */
+  usedZone: boolean;
+  formatter(node: unknown): Formatter | null;
+  charge(text: string): string;
+  text(node: unknown, value: unknown, where?: string): string;
+  tupleText(nodes: unknown[], values: unknown[]): string;
+  plainTupleText(nodes: unknown[], values: unknown[]): string;
+}
+/** `UTC`, `UTC+02:00`, `UTC-05:30`. */
+export function zoneName(offsetMinutes: number): string;
+export function renderFields(model: Model, renderer: Renderer, options?: { rawArguments?: boolean }): { intent: string; fields: [string, Icrc21Value][] };
+/** `headingLevel`: the title's heading level (default 1). */
+export function renderGeneric(model: Model, renderer: Renderer, options?: { rawArguments?: boolean; headingLevel?: number }): string;
+
+/** A Markdown code span that shows the string verbatim (invisible characters made visible). */
+export function codeSpan(s: string): string;
+export function escapeMarkdown(s: string): string;
+/** Invisible characters shown as `\u{202e}`; nothing is dropped. */
+export function visible(s: string): string;
+
+// ------------------------------------------------------------------ errors
+
+export const CODES: Readonly<{
+  METHOD_UNKNOWN: "E_METHOD_UNKNOWN";
+  DECODE: "E_DECODE";
+  TOO_LARGE: "E_TOO_LARGE";
+  LANGUAGE: "E_LANGUAGE";
+  REQUEST: "E_REQUEST";
+  UNSUPPORTED_TYPE: "E_UNSUPPORTED_TYPE";
+  RESOLVED_FORM: "E_RESOLVED_FORM";
+  TEMPLATE: "E_TEMPLATE";
+  TEMPLATE_PATH: "E_TEMPLATE_PATH";
+  REF_UNRESOLVED: "E_REF_UNRESOLVED";
+  ARG: "E_ARG";
+  TAG_TYPE: "E_TAG_TYPE";
+  TAG_CONFLICT: "E_TAG_CONFLICT";
+}>;
+export type ConsentErrorCode = (typeof CODES)[keyof typeof CODES];
+/** ICRC-21 `GenericError.error_code` values this package uses. */
+export const GENERIC_ERROR_CODES: Readonly<{
+  E_RESOLVED_FORM: 1000n;
+  E_TEMPLATE: 1001n;
+  E_TEMPLATE_PATH: 1002n;
+  E_REF_UNRESOLVED: 1100n;
+  E_ARG: 1101n;
+  E_TAG_TYPE: 1102n;
+  E_TAG_CONFLICT: 1103n;
+  INTERNAL: 1999n;
+}>;
+export declare class ConsentError extends Error {
+  constructor(code: ConsentErrorCode, message: string, options?: { cause?: unknown });
+  name: "ConsentError";
+  code: ConsentErrorCode;
+}

package/src/index.mjs

@@ -0,0 +1,13 @@
+export { icrc21ConsentMessage, handleConsentRequest, toIcrc21Error, SUPPORTED_LANGUAGE } from "./icrc21.mjs";
+export { encodeConsentResponse, decodeConsentResponse, encodeConsentRequest, decodeConsentRequest, toJson } from "./icrc21-codec.mjs";
+export { generateConsent } from "./consent.mjs";
+export { buildModel } from "./model.mjs";
+export { decodeArguments, schemaFor } from "./decode.mjs";
+export { parseTemplate } from "./template.mjs";
+export { resolvePath, valuesAt } from "./paths.mjs";
+export { Renderer, zoneName } from "./display.mjs";
+export { renderFields, renderGeneric } from "./render.mjs";
+export { codeSpan, escapeMarkdown, visible } from "./text.mjs";
+export { ConsentError, CODES, GENERIC_ERROR_CODES } from "./errors.mjs";
+// SNS validator renderings are the `./sns` subpath (`@meantjs/consent/sns`): they hash with node:crypto,
+// and this entry must bundle for a browser (test/browser-bundle.test.mjs).

package/src/model.mjs

@@ -0,0 +1,159 @@
+// 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 method with an `intent` tag: 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 method 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 { 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 method (spec section 5.3)
+ * @property {string} title
+ * @property {SentencePart[] | null} sentence  null for a method 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);
+  const argValues = decodeArguments(method, arg, limits);
+  const diagnostics = [];
+  const intent = method.tags?.intent?.args;
+  const title = typeof intent?.title === "string" && intent.title.trim() !== "" ? intent.title : (labelOf(method) ?? `Call ${name}`);
+  const tagOrigin = intent ? { origin: method.tags.intent.origin, ...(method.tags.intent.profile === undefined ? {} : { profile: method.tags.intent.profile }) } : null;
+  const provenance = { intent: tagOrigin, profiles: Array.isArray(resolved.profiles) ? resolved.profiles : [] };
+  const base = { method: name, effect: effectKind(method), 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));
+}