@meantjs/profile 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog: @meantjs/profile
+
+The five Candid Profile library packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`, `/reconcile`) release together under one version and pin each other exactly; a version appears here even when this package did not change. Release steps: `docs/releasing.md` in the repository.
+
+## 0.1.0 — 2026-10-28
+
+First published version.
+
+Published under the `@meantjs` scope (D-051). Before any release, this package was `@candid-core/profile`.
+
+- Validates Candid Profile v0 documents against the schema and the service's Candid interface, matches packs by Candid
+  subtyping (with the result-variant relaxation), merges layers by precedence and emits the resolved form
+  (`resolveService`, `validateProfile`, `matchPack`).
+- Takes the service as `.did` source (compiled with `@candid-core/cli` 0.4.0) or as its candid-core `ContractEnvelope`.
+- Ships the profile schema and the ICRC-1 and ICRC-2 packs as data (`./schema.json`, `./packs/*`); the Node entry's
+  defaults (`createSchemaValidator()`, `loadPacks()`, `candid-profile resolve --packs`) read these copies.
+- Entries: `.` (Node), `./browser` (no Node built-in), `./address` (the address grammar, no dependency), and the
+  `candid-profile` CLI.
+- TypeScript declarations for every entry.
+- Names (spec §5.3, D-045): the experimental `names` and `named` tags and their checks (six errors and
+  `W_NAMED_UNPATTERNED`).
+- Doc annotations (spec §9, proposal `docs/proposals/w1-doc-attributes.md`): `profileFromDocAttributes` turns the tags
+  an author writes as `.did` doc comments, as candid-core's `didToDocAttributes` reads them, into an `author` canister
+  profile. `DOC_ATTRIBUTES_VERSION` is the doc attributes version it reads (1). It needs a `@candid-core/cli` release
+  after 0.3.0 to be fed from `.did` text.
+- The shipped schema is compiled ahead of time (`data/profile-v0.validate.mjs`, ajv's standalone code), so
+  `createSchemaValidator()` on it generates no code at run time: a page needs no CSP `'unsafe-eval'` (the cli's wasm
+  needs `'wasm-unsafe-eval'`). Its answers equal ajv's run-time compile on every profile in the repository and tens of
+  thousands of mutations of them. Another schema document is still compiled at run time, and ajv is loaded only then.
+  Each validator keeps its own `errors`. The browser bundle grows from 189.5 KB to 265.6 KB minified.
+- Served profiles (spec §8.1, D-048): `readServedProfile(bytes, { canisterId })` checks the bytes a canister serves
+  as `icp:public candid:profile` (`E_SERVED` for anything but UTF-8 JSON of an `author` canister profile, at most
+  1 MiB, bound to that canister or to none); `SERVED_SECTION`, `SERVED_METADATA` and `SERVED_MAX_BYTES` name the
+  section, its metadata path and its limit. In both entries.
+- An `outcome` may give `default` alone (spec §5.3, D-049): the class of every reply of a method whose result has no
+  variant to select. The schema needs `classes` or `default`; on a result that reaches a variant, `default` alone
+  leaves every case to the default (`W_OUTCOME_UNCLASSIFIED`, info).

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,249 @@
-# Temporary Holding Version
+# @meantjs/profile
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Validates Candid Profiles, matches packs to a service, merges layers and emits the resolved form that consumers read
+(`docs/profile-v0.md` sections 7, 8 and 10). Dependencies, pinned exactly: `@candid-core/cli` 0.4.0 (wasm: `.did`
+to Contract) and `ajv` 8.18.0.
+
+```sh
+npm install @meantjs/profile
+```
+
+- **Runs on:** Node 22 or later for the main entry and the `candid-profile` CLI. `@meantjs/profile/browser` is for
+  browser bundles (checked with esbuild, and in Chromium under a CSP without `'unsafe-eval'`; the cli's wasm needs
+  `'wasm-unsafe-eval'`, below). `@meantjs/profile/address` has no dependency and runs anywhere.
+- **Module format:** ES modules only, with hand-written TypeScript declarations for every entry.
+- **Spec:** [Candid Profile v0](https://github.com/B3Pay/Meant/blob/main/profile/docs/profile-v0.md). **Licence:** Apache-2.0.
+- **Versions:** the five Candid Profile packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`,
+  `/reconcile`) release together under one version and pin each other exactly; in 0.x a minor is breaking,
+  and so is any change to generated text ([releasing](https://github.com/B3Pay/Meant/blob/main/profile/docs/releasing.md)).
+
+```js
+import { createSchemaValidator, resolveService, loadPacks, validateProfile } from "@meantjs/profile";
+
+const validateSchema = await createSchemaValidator();                 // the schema this package ships
+const packs = await loadPacks();                                      // the standard packs it ships (ICRC-1, ICRC-2)
+const r = await resolveService({
+  did: await readFile("ledger.did", "utf8"),
+  validateSchema,
+  profiles: [{ doc: authorProfile }],                                  // applied as given (a pack here must match)
+  packs: packs.map(({ doc }) => ({ doc })),                            // tried; applied only if they match
+});
+r.ok; r.resolved; r.diagnostics; r.profiles;                           // r.resolved has the shape of fixtures/*.resolved.json
+```
+
+Two inputs, exactly one per call: `did` (Candid source, compiled here with the pinned cli) or `envelope` (the
+service's candid-core `ContractEnvelope`, as `candid-core-cli gen` writes it next to a generated module). With an
+envelope the service is not compiled again, so the resolved form's `interface_id` is the one the app's generator
+wrote (`test/envelope.test.mjs`: the same resolved form for the ledger `.did` and `examples/tokens.did` either way).
+The envelope's identities are taken as written (nothing here can recompute them, so a hand-edited envelope keeps an
+id that no longer describes it). Its graph is checked before anything walks it: every reference, the fields each
+node kind needs, methods that name funcs, an actor, no opt that contains only itself, and the field-names table (it
+must be there, and each name must hash to its field's id). One that fails is an `E_ENVELOPE` error with
+`resolved: null`, and anything the checks still miss is reported the same way rather than thrown. Packs still compile their `binds.requires`, so the cli stays a
+dependency. CLI: `candid-profile resolve --envelope app.envelope.json --packs`.
+
+The defaults are the data the package ships (`data/`), so they work wherever it is installed. The same data is
+exported for passing as documents:
+
+```js
+import schema from "@meantjs/profile/schema.json" with { type: "json" };          // copy of spec/profile-v0.schema.json
+import icrc1 from "@meantjs/profile/packs/icrc1.profile.json" with { type: "json" };
+const validateSchema = await createSchemaValidator(schema);                            // a document, not a path
+const r = await resolveService({ did, validateSchema, packs: [{ doc: icrc1 }] });
+```
+
+`data/` is generated from the repository's `spec/` and `packs/` by `npm run data -w packages/resolver` (part of
+`npm run fixtures`); `test/data.test.mjs` fails when it is stale. `@meantjs/profile/address` (`parseRelPath`, `parseAddress`, `idlHash`, `U32_MAX`) imports
+nothing outside its own two modules, so a browser bundle may use it; the main entry loads Node built-ins, ajv and the
+cli wasm.
+
+`@meantjs/profile/browser` is the whole resolver for a browser bundle: the main entry's functions without the
+ones that read files (`loadPacks`, the CLI, the default paths), plus the shipped data and the cli's wasm loader.
+
+```js
+import { createSchemaValidator, resolveService, STANDARD_PACKS, initCompiler } from "@meantjs/profile/browser";
+
+await initCompiler(wasmUrl);                         // optional: only when the bundler moves candid_core_wasm_bg.wasm
+const validateSchema = await createSchemaValidator(); // the shipped schema; a document, never a path
+const r = await resolveService({ did, validateSchema, profiles: [{ doc }], packs: STANDARD_PACKS.map(({ doc }) => ({ doc })) });
+```
+
+Types: `src/index.d.mts`, `src/address.d.mts` and `src/browser.d.mts` (hand-written, each the `types` condition of
+its entry; `scripts/types.test.mjs` keeps their names equal to the runtime exports, and `npm run types` compiles strict
+consumers against them). `profileId` hashes with a plain-JavaScript SHA-256 (`src/sha256.mjs`, synchronous, compared with node:crypto in the
+tests), so neither entry needs node:crypto.
+
+**Content-Security-Policy.** The shipped schema is compiled ahead of time (`data/profile-v0.validate.mjs`, ajv's
+standalone code, generated by `npm run data` and checked by `test/data.test.mjs`), so `createSchemaValidator()` on it,
+or on any document equal to it, generates no code at run time: a page needs no `'unsafe-eval'`. The cli's wasm needs
+`'wasm-unsafe-eval'` in `script-src`. Only another schema document is compiled by ajv at run time, with `new
+Function`, and needs `'unsafe-eval'`. `test/csp.test.mjs` checks both: on Node with code generation from strings
+disabled, and in Chromium under `script-src 'self' 'wasm-unsafe-eval'` (skipped without a Chrome or Chromium; set
+`CHROME_PATH`).
+`test/browser-entry.test.mjs` bundles the entry for the browser and fails on any `node:*` import or Node global
+(the cli is left out of that bundle: it is its own published package, and it reads its wasm with a guarded
+`import("node:fs/promises")` only on Node), checks the data against `data/`, and resolves `examples/` both ways.
+
+`validateProfile(doc, { validateSchema, did, resolved })` is the single-profile validator (what `scripts/validate.mjs`
+wraps). Source map: `iface.mjs` (Contract graph), `address.mjs`, `tags.mjs` (`TagIndex`, `LayeredTags`), `checks.mjs`,
+`analyze.mjs` (index, merge, per-annotation checks), `doc-annotations.mjs`, `resolved.mjs`, `subtype.mjs`, `pack-match.mjs` (and `packs.mjs`,
+which reads a directory), `schema-core.mjs` (and `schema.mjs`, which reads a path), `resolve.mjs`, `validate.mjs`,
+`browser.mjs`.
+
+## Doc annotations (spec section 9)
+
+An author can write the tags in the `.did` itself, as doc comments. candid-core reads them (doc attributes v1: one
+`@name(key = value, ...)` syntax, malformed lines refused, each attribute handed out with the SourceInfo path of the
+item it documents), and `profileFromDocAttributes` turns them into an `author` canister profile bound to the
+interface's `interface_id`:
+
+```candid
+type Tokens = record {
+  /// @amount(decimals = 8, symbol = "ICP")
+  e8s : nat64;
+};
+service : {
+  decimals : () -> (nat8) query;
+  /// Send tokens to another principal.
+  /// @intent(title = "Send", template = "Send {amount} to {to}")
+  /// @amount(at = "amount", decimals = query(decimals))
+  send : (record { to : principal; amount : nat }) -> (variant { Ok : nat; Err : text });
+}
+```
+
+```js
+import { didToDocAttributes } from "@candid-core/cli"; // a release after 0.3.0: 0.3.0 does not have it
+import { profileFromDocAttributes, resolveService } from "@meantjs/profile";
+
+const { ok, doc, diagnostics } = profileFromDocAttributes(await didToDocAttributes(did), { name: "my-ledger" });
+const r = await resolveService({ did, validateSchema, profiles: doc ? [{ doc }] : [] });
+```
+
+- Method docs: method tags (`intent`, `effect`, `idempotency`, `outcome`, `list`, `names`) apply to the method. Value
+  tags need `at`: `at = "amount"` for the arguments, `at = "->(0).Ok"` for the results, starting with `(i)` when the
+  tuple has more than one element. `@describe` without `at` describes the method.
+- Declaration and field docs: `type:<Decl>` and `type:<Decl>.<field>`. A field of an inline actor type becomes a method
+  address (`inline(0).items[].price`): the method is found by its SourceInfo path, an `opt` adds nothing and a `vec`
+  adds `[]` (OQ-4). `at` reaches further inside (`@bytes(at = "subaccount", encoding = "hex")` on an account field).
+- Values: text, numbers (whole only, kept exact; past 2^53 or for `range` bounds a decimal string), `true`/`false`,
+  identifiers as text (`unit = ns`), `query(m)`, `now()`, `caller()`, lists and records
+  (`classes = { Ok = success, "Err.TooOld" = fix_input }`).
+- Prose becomes `describe.help` (lines joined, paragraphs kept), except on an integer the same doc gives no value tag:
+  a described integer is an agent input of plain digits (D-044), so that prose is reported (`I_DOC_PROSE`) instead.
+- Only bare names that are profile tags are read. A dotted name (`@ui.hidden`) is another tool's; any other bare name
+  is left alone, with a warning when it is one or two letters from a tag (`@amout`).
+- Errors (the profile is still returned with what could be placed): `E_DOC_TARGET` (a tag no v0 address reaches, such
+  as inside a func value or a callback service, or one in the wrong place), `E_DOC_VALUE` (a fraction, an unknown
+  call), `E_DOC_SYNTAX` (candid-core refused the comment), `E_DOC_INPUT` (not a doc attributes v1 response). Each
+  names the item's address, its SourceInfo `path` and `source`, and the doc line.
+
+`didToDocAttributes` is new in the pinned `@candid-core/cli` 0.4.0; the tests read real responses it wrote
+(`test/fixtures/doc-attributes/`, provenance in its `SOURCE.json`, regenerated with
+`node scripts/doc-attributes-fixtures.mjs`, or with `--cli <path>` for a local build of candid-core's npm package). The proposal is `docs/proposals/w1-doc-attributes.md`.
+
+## Served profiles (spec section 8.1, D-048)
+
+A canister serves its profile as the public custom section `icp:public candid:profile`. Reading the bytes is the
+consumer's job (one certified `read_state` of `/canister/<id>/metadata/candid:service` and `.../candid:profile`;
+`packages/kit` `fetch` does it with `@icp-sdk/core`); this package checks what came back:
+
+```js
+import { readServedProfile, resolveService } from "@meantjs/profile";
+
+const served = readServedProfile(profileBytes, { canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai" });
+// served.ok: served.doc is the profile; otherwise served.diagnostics holds E_SERVED and nothing is applied
+const r = await resolveService({ did: serviceText, profiles: served.ok ? [{ doc: served.doc }] : [] });
+```
+
+- `E_SERVED` (`at`: `candid:profile`, or `label`): not a `Uint8Array`, over 1 MiB (`SERVED_MAX_BYTES`), not UTF-8, a
+  byte order mark, not JSON, not one object, a `kind` other than `canister`, an `origin` other than `author`, or a
+  `binds.canister_id` that is not `canisterId`. `canisterId: null` skips that last check, for a module that is not
+  installed yet (a module does not know the id it will run as); any other non-string throws.
+- Binding is the resolver's usual rule (spec section 7): resolve against the `candid:service` the same canister
+  serves, so a profile for another interface is `rebound` or `stale` as any other.
+- Tests: `test/served.test.mjs`; end to end on PocketIC in `packages/kit/pocketic/`.
+
+## CLI
+
+```sh
+node packages/resolver/bin/candid-profile.mjs resolve <service.did> [--profile p.json ...] [--packs] [--packs-dir dir] [--verbose] [--quiet] > resolved.json
+# after `npm ci` the bin is also linked: npx candid-profile resolve ...
+```
+
+- `--profile` may repeat; a pack given this way must match (`E_PACK_NOT_MATCHED` otherwise).
+- `--packs` tries every standard pack this package ships (or every pack in `--packs-dir`) and applies those that match; the others get `I_PACK_NOT_MATCHED` (info).
+- stdout: the resolved form (also when diagnostics contain errors, as long as the `.did` compiles). stderr: applied profiles, counts, warnings and errors (`--verbose`: infos too).
+- Exit code 0: no error diagnostic. 1: at least one. 2: usage or I/O.
+- A `.did` with `import` is not followed yet; give the CLI a single file.
+
+Real input: `test/fixtures/ledger.did`, the ICRC ledger `.did` of release `ledger-suite-icrc-2026-03-09`, the file the eval harness pins
+(sha256 and URL in `test/fixtures/SOURCES.json`). `candid-profile resolve test/fixtures/ledger.did --packs` applies `icrc1` and `icrc2`,
+with 0 errors, 0 warnings and 3 infos (two matches, and the `int16` `utc_offset_minutes` of ICRC-21 that no profile tags).
+
+## Merge (spec section 8)
+
+Layers, highest first: `author`, `third_party`, `pack`, `inferred`. One `TagIndex` per layer.
+
+- The first layer that has a tag at a position supplies it; the same tag lower down is dropped with `W_OVERRIDDEN`.
+- Within a layer (also across several profiles of that layer): method position beats a `type:` edge beats a whole-declaration
+  tag. Two different values at one specificity: `E_CONFLICT`, the first one given stays. Equal values: `W_DUPLICATE`.
+- Layer decides before specificity.
+- `profiles` in the resolved form lists every applied profile, highest layer first. Each tag carries `origin` and `profile`.
+- A stale canister profile (spec section 7) keeps its non-conversion tags but loses `amount`, `timestamp`, `duration`,
+  `account`, `subaccount`, `bytes` in the output.
+
+## Pack matching and Candid subtyping (spec section 7, D-005, D-019)
+
+A pack applies when the service is a **subtype** of the Candid fragment in `binds.requires`, with result variants allowed to be wider.
+
+### Was an existing checker usable? No.
+
+| Candidate | Finding (2026-10-09) |
+|---|---|
+| `@dfinity/didc` 0.0.4 (wasm of the Rust candid crates) | Exports `start`, `getServiceMethods`, `encode`, `decode` only. The subtype code is linked in (it backs `decode`) but there is no entry point that compares two services. |
+| `@candid-core/cli` 0.2.0 (surveyed 2026-10-09; 0.3.0 since D-037 adds `projectDid` and `checkCompatible`, not surveyed) | Exports `init`, `didToContract`, `didToModule`. No compatibility check. |
+| candid-core compatibility (b3hr4d/candid-core#247) | An open issue ("Interface projection and a live-compatibility check over written .did files"), not code. Its acceptance criteria ask for the same relation as here plus differential tests against upstream `candid`. |
+| `@candid-core/schema` 0.3.0 (surveyed 2026-10-09) `wireSubtypeOfSchema` | An internal method of the binary decoder (not an export): it relates a wire type table to a runtime schema, not two Contracts. Read as a second opinion on the rules. |
+| Rust `didc` 0.5.4 (binary from the local cargo bin; its linked candid revision was not determined) and the source of candid 0.10.37 (newest in the local cargo registry) | `didc check` is the oracle for the differential tests (below); the 0.10.37 `src/types/subtype.rs` was read for the rules. Neither is a runtime dependency. |
+
+So `src/subtype.mjs` implements the relation over two candid-core Contract graphs (`Iface`), one per side, since a canister and a pack fragment are compiled separately.
+
+### Rules implemented
+
+Source: Candid specification, "Upgrading and Subtyping > Rules" (https://github.com/dfinity/candid/blob/c7659ca/spec/Candid.md, the revision the Rust crate links to). `S <: T` means S can be used where T is expected.
+
+| Spec subsection | Rule as implemented |
+|---|---|
+| Primitive Types | `t <: t`; `nat <: int`; `any <: reserved`; `empty <: any` |
+| Vectors | `vec S <: vec T` if `S <: T` (`blob` is `vec nat8`) |
+| Options | `opt S <: opt T` if `S <: T`; `null <: opt T`; `S <: opt T` if `S <: T` and T is not null, reserved or opt |
+| Options, "unusual rules" | **Off by default** (`lossyOpt`). They make `opt S <: opt T` hold for unrelated S and T (the value decodes as null). The spec says they exist for transitivity and that tools should warn when used; for pack matching they would accept `fee : opt text` against a pack that says `opt nat`. With `lossyOpt: true` they are implemented as "always true" |
+| Records | `record S <: record T` if every field of T is in S with a subtype, or is absent from S and its type is opt, null or reserved. Extra fields in S are ignored. Fields compare by id |
+| Variants | `variant S <: variant T` if every case of S is in T with a subtype (S may have fewer cases) |
+| Functions | `func S <: func T` if the annotations are equal, `tuple(T.args) <: tuple(S.args)` (contravariant) and `tuple(S.results) <: tuple(T.results)` (covariant); tuples follow the record rule over positions 0, 1, ... |
+| Services | `service S <: service T` if every method of T is in S with a function subtype. Extra methods ignored; init args of a class ignored |
+| (coinduction) | A pair met again while it is being decided is assumed true, so recursive types terminate |
+| (bounds, profile spec section 11.6) | Depth 256 and 2,000,000 pair evaluations; beyond that the answer is "not a subtype" |
+
+**D-019 relaxation.** For a variant reached through a method *result*, extra cases in the canister are allowed. "Reached through" is
+a descent from the result by record fields, `opt`, `vec` and variant payloads, with covariant polarity. Entering a `func` or `service`
+type resets to strict. Argument positions are always strict. The matcher reports every relaxed position
+(`I_PACK_MATCHED` message and `matchPack(...).relaxed`).
+
+**Not implemented, on purpose:** the Rust crate's catch-all that accepts `S <: opt T` for any S with only a warning (it is not a rule of the spec);
+`service <: principal` (not in this revision of the spec; the Rust crate has it).
+
+### Verification
+
+- **Facts (run 2026-10-09):** `test/subtype.test.mjs` holds 41 service pairs, each with the answer of the Rust `didc check` 0.5.4 and of the spec rules. With `lossyOpt: true` the checker answers like Rust on all 41; with it off it differs on exactly the 3 rows that need the unusual opt rules. A seeded differential test (250 random pairs, in the repository) runs when `didc` is installed and checks: never more permissive than `didc`, and identical to `didc` whenever `didc` does not report its special opt rule. Scratch runs during development (about 7,400 further random pairs; the "never more permissive" check on 2,800 of them) found no violation. In those runs `didc` used its special opt rule on about 13% of the pairs; where it accepted through that rule, this checker with `lossyOpt: true` also accepted in about 87% of the cases (the rest need the Rust catch-all, which is not a spec rule).
+- **Label: assumption.** Rust `didc` and the spec could both be wrong in a way that this checker repeats. The candid-core decoder (`wireSubtypeOfSchema`) was read for the same rules but not run against this checker.
+- **Open:** a Candid corner we did not exercise is `service <: principal` and quoted method names (OQ-3).
+
+### What happens after a match
+
+A matched pack is applied to the **service's** types (addresses resolve against the service). Subtyping lets the service differ from the
+fragment, so some annotations may name a position the service does not have, or have a shape a tag no longer fits. These are dropped with
+`I_PACK_ANNOTATION_SKIPPED` instead of being reported as errors in the pack: an address that is gone (a result case the service removed,
+an optional field it lacks), an `outcome` key that is not a case, a template placeholder inside an optional segment that is absent (the
+segment renders empty), a tag that does not apply to the service's type (for example `account` on a record with an extra optional field),
+and an `idempotency` whose stamp lost its `timestamp` tag. A placeholder outside an optional segment that cannot be resolved is dropped with its `intent`.

package/bin/candid-profile.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+main(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr })
+  .then((code) => { process.exitCode = code; })
+  .catch((e) => { console.error(e); process.exitCode = 2; });