Profiles

Profile diagnostics

Every E_, W_ and I_ code the resolver, the consent generator and the formatters return.

The resolver and the validator report problems as a list of diagnostics; the formatters, the consent generator and the terms functions throw an error that carries a code. Either way, match on the code: the message is written for a person or a model to read. Codes are grouped below by the package that returns them, with the spec's §13 table first. Every code here is copied from spec §13 or from the package's source under profile/packages.

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;
}

The candid-profile CLI exits with 0 when no diagnostic is an error, 1 when one is (the resolved form is still printed when the service compiles), and 2 for a usage or I/O problem (The candid-profile command).

Resolver and validator: spec §13#

Returned by @meantjs/profile. Rows that §13 groups (E_ADDR_SYNTAX / E_ADDR_UNRESOLVED) are split here, one code a row, with the meaning that half of the §13 row gives.

Schema, interface and input#

Addresses and tags#

Methods: effect, idempotency, outcome, templates#

Names#

Layers, binding and packs#

A stale canister profile loses its value-conversion tags in the resolved form and keeps the rest; see Profiles, layers and binding. The codes that make a profile stale when they appear after a rebind are listed in STALE_CODES in checks.mjs.

Resolver: doc annotations#

Returned by profileFromDocAttributes when it turns the tags written as doc comments in a .did into an author profile (spec §9, Annotate a .did file). Not in §13. On an error the profile is still returned with what could be placed. Meanings are those of the package's README and src/doc-annotations.mjs.

@meantjs/profile/evm: AbiError#

The EVM helpers throw AbiError (name: "AbiError", code). Experimental, spec §15; see EVM contracts.

@meantjs/format: FormatError#

Every rejection of the format library is a FormatError with a stable code, one of CODES. The meanings are the comments in src/errors.mjs where it has one, and otherwise the messages the code is thrown with. See Parse and display values.

formatterFor throws EE_REF_UNRESOLVED, EE_ARG, EE_TAG_TYPE or EE_TAG_CONFLICT rather than return a formatter that half works. Since 0.3.0 that includes an amount whose token names its token by a field when the caller passes no token (EE_REF_UNRESOLVED), and a timestamp threshold without its message, or the other way round (EE_ARG: "a timestamp threshold and its message go together: give both or neither"). The Rust crate meant-format returns eight of these codes for the amount tag, matched case by case against this package: meant-format (Rust).

@meantjs/consent: ConsentError#

Every failure of the consent package is a ConsentError with a stable code. icrc21ConsentMessage maps it to an ICRC-21 error variant whose description starts with the code; the lower-level functions throw it. Meanings are the comments in src/errors.mjs. See Generate consent messages.

A formatter that cannot be built stops the message (rule 10 of spec §12): a number is never shown without its decimals.

@meantjs/consent: diagnostics#

What the generator adjusted, in the non-enumerable diagnostics of a result ({ code, at, message }, no severity field). The message is still produced.

@meantjs/consent/terms: TermsError#

New in 0.4.0 (spec §5.3, "Confirmed terms", D-056). readTerms and termsGate throw TermsError (name: "TermsError", code, one of TERMS_CODES). Its message is written for the agent, which fixes the term or asks the person; readTerms never guesses a token, an app, a number of decimals or a date. Meanings are the comments in src/terms.d.mts, and the messages are those of src/terms.mjs, with the parts in angle brackets filled in and some shortened to their last clause. See Confirm terms for a task.

Input that is not in the shape these functions write is a ConsentError EE_REQUEST, not a TermsError: a wallet without its tokens or with a now that is not a bigint, terms that did not come from readTerms or changed after confirmTerms (terms are not the ones the user confirmed: they changed after confirmTerms …), a grant that did not come from the consent functions, and a termsGate check with no request id. checkGrant throws neither for a grant that does not fit: it returns { fits: false, reasons }, the reasons in words.

@meantjs/tools: input issues#

readToolInput returns { issues: [{ param, path, code, message }] } instead of a value when the inputs cannot be read. The codes are the format library's, above, plus these (from the function's documentation in src/input.mjs). Inside a JSON input, path names the place ($args[0].command.Follow.followees[1].id). See Give an agent tools.

An EVM contract's resolved form ("chain": "evm") is refused by the tool layer with a TypeError, not a code: EVM tools are a later phase.

@meantjs/reconcile: statuses#

@meantjs/reconcile returns no diagnostic codes. matchBlocks judges the ICRC-3 blocks read since the first send and returns one of four statuses (Settle an unknown outcome):

Edit this page on GitHub