@meantjs/cli 0.0.0-bootstrap → 0.0.0-stage

package/CHANGELOG.md

@@ -1,733 +0,0 @@
-# Changelog
-
-What changed between released versions of `@meantjs/cli`, which was
-published as `@candid-core/cli`, with the command `candid-core-cli`, through
-0.4.0; the entries for those releases name them so. This file ships inside
-the published tarball, so the record travels with the artifact.
-
-**Every entry names the exact revisions it embeds** — the compiler crate
-(`meant` from 0.4.0's entry on, published as `candid-core` before) and the
-`candid-core-ts` generator are compiled into the wasm artifact from one
-repository commit, and the pairing is the artifact's
-provenance: the parity gates prove the emitted module and contract are
-byte-identical to that commit's Rust-native outputs over the golden
-fixtures.
-
-`@meantjs/cli` is pre-1.0. Until 1.0 any release may change the CLI
-grammar, the library API, and the request/response shapes. Pin an exact
-version.
-
-## 0.5.0 — 2026-11-01
-
-Embeds `meant` 0.1.0 and the `candid-core-ts` generator from the repository
-commit the release is dispatched from; the release record names the exact
-SHA. The dispatched commit's `meant` source is ahead of the crates.io 0.1.0
-archive by two changes, and neither moves a Contract or an identity: the
-reader of doc attributes behind `didToDocAttributes`, which 0.4.0 embedded
-already, and type-depth walks that allocate the same way for the same input
-whatever the heap layout, refusing and returning what they did before. So no
-crate release comes first.
-
-**The first release under the name `@meantjs/cli`.** Through 0.4.0 this
-package was published as `@candid-core/cli`, with the command
-`candid-core-cli`. 0.5.0 is 0.4.0's code under new names: the package is
-`@meantjs/cli`, its one command is `meant`, the name of the Rust binary,
-and the modules it writes import `@meantjs/schema`, the new name of
-`@candid-core/schema`. The packages moved to the `@meantjs` scope beside the
-profile packages, so that the project ships under two names: ic-reactor, for
-the Internet Computer, and Meant, which is not tied to one chain.
-`@candid-core/cli` keeps every version it published and gets no new one.
-
-A stable release, published under the npm `latest` dist-tag; keep it pinned,
-`npm install --save-dev --save-exact @meantjs/cli`. Run it as
-`npx @meantjs/cli gen …`, or as `meant gen …` from a script in your
-`package.json`. Never as a bare `npx meant`: the unscoped `meant` package on
-npm belongs to another author, so where this package is not installed, npx
-would offer to download and run that one. In a shell, a bare `meant` runs
-whichever `meant` comes first on the `PATH`, which can be the Rust binary from
-`cargo install meant`, whose commands are `compile` and `validate`; a script
-in `package.json` puts this package's command first. The optional peer is
-`@meantjs/schema` at exactly `0.6.0`, which is `@candid-core/schema` 0.5.0's
-code under its new name; install the two together, each at its exact
-version.
-
-**Upgrading from `@candid-core/cli` 0.4.0 changes names, and the first two
-lines of every module.** Install `@meantjs/cli` and `@meantjs/schema` in
-place of the old pair, replace `candid-core-cli` with `meant` in your
-scripts, and replace `@candid-core/cli` with `@meantjs/cli` where you import
-the library. Then run `meant gen` again over every committed module: each
-module's header line becomes
-`// Generated by Meant from a Meant Contract. Do not edit.` and its import
-`import * as $ from "@meantjs/schema";`, and nothing else in it changes. Until
-then `meant gen --check` reports each module 0.4.0 wrote as drifted, exit 1.
-The envelopes do not change. Measured over the repository's 44 tracked
-`.did` files: both releases compile the same 40 and refuse the other 4 with
-the same diagnostics, the 40 envelopes are byte-identical, and the 40 modules
-differ in those two lines alone.
-
-**What keeps the old name.** The strings inside Contract documents are not
-package names, and this release changes none of them: the `format`
-`candid-core`, the canonical form `candid-core-canon-1`, the
-`candid-core:contract:v1:sha256:…` and `candid-core:interface:v1:sha256:…`
-identities that `gen`, `project` and `check` print, and the
-`org.candid-core.field-names/v1` extension of every envelope. The two
-identity prefixes are hashed into every identity, so renaming them would
-move every `contract_id` and `interface_id`. The `--json` documents keep
-`schemaVersion` 1.
-
-### Changed
-
-- **BREAKING: the package is `@meantjs/cli`, and its command is `meant`.**
-  The package installs one bin, `meant`, where it installed
-  `candid-core-cli`, and the usage text names it:
-  `usage: meant gen <service.did>... [-o <dir>] [--json] [--check]`, with
-  `meant project` and `meant check` on the lines below. The grammar, the
-  exit codes and the `--json` documents are 0.4.0's. Import the library from
-  `@meantjs/cli`; its exports and their declarations are 0.4.0's.
-- **BREAKING: generated modules import `@meantjs/schema`**, and their header
-  line is `// Generated by Meant from a Meant Contract. Do not edit.`; it was
-  `// Generated by candid-core-ts from a candid-core Contract. Do not edit.`
-  `didToModule` returns the same text. A module's other lines are unchanged.
-- The optional peer is `@meantjs/schema` at exactly `0.6.0`, where it was
-  `@candid-core/schema` at exactly `0.5.0`.
-- `repository` and `homepage` in `package.json` name
-  `https://github.com/B3Pay/Meant`, where the repository moved on
-  2026-10-28; GitHub redirects the old address.
-
-## 0.4.0 — 2026-10-27
-
-Embeds `meant` 0.1.0 and the `candid-core-ts` generator from the repository
-commit the release is dispatched from; the release record names the exact
-SHA. `meant` is the compiler crate formerly published as `candid-core`, and
-`meant` 0.1.0 is `candid-core` 0.1.0's code under the new name: the crate's
-first version without a prerelease suffix. The dispatched commit's `meant`
-source is ahead of the crates.io 0.1.0 archive by one change, the reader of
-doc attributes behind `didToDocAttributes` (below), which moves no Contract
-and no identity, so no crate release comes first.
-
-A stable release, published under the npm `latest` dist-tag, so a plain
-`npx @candid-core/cli` runs it; keep it pinned,
-`npm install --save-dev --save-exact @candid-core/cli`. A `^0.3.0` range does
-not admit it. The `beta` dist-tag stays on 0.2.0-beta.1. The optional peer is
-`@candid-core/schema` at exactly `0.5.0` (exactly `0.4.0` in 0.3.0), and npm
-refuses a mismatched pair (`ERESOLVE could not resolve`), so move the two
-packages together.
-
-Against the compiler 0.3.0 embeds (`candid-core` 0.1.0-beta.3 and five later
-changes), three things change. A record field whose id is 4294967295, written
-as that number or as a name that hashes to it, is refused with
-`did_parse_error`; 0.3.0's compiler numbered the field after it 0. Collecting
-the provenance sidecar no longer grows with the square of the declarations,
-so a large `.did` file compiles in time proportional to its size. And every
-envelope `gen` writes names `meant` 0.1.0 as its producer, where 0.3.0's
-named `candid-core` 0.1.0-beta.3, so `gen --check` reports each envelope
-0.3.0 wrote as drifted, exit 1, until `gen` runs again. Every other input
-compiles to the same Contract and identities: of the repository's 44 tracked
-`.did` files, the 40 that both releases compile give envelopes that differ in
-the `producer` alone, and the 4 that 0.3.0 refuses this release refuses with
-the same diagnostics.
-
-### Added
-
-- **`didToDocAttributes` reads `@name(…)` attributes in doc comments.** It
-  compiles the sources and returns `{ ok: true, contract, source_info,
-  doc_attributes }`: the Contract and the SourceInfo sidecar
-  `meant compile <path>` prints, which no function of this package
-  exposed before, and every documented item's prose and attributes keyed by
-  its SourceInfo path, as `docs/doc-attributes.md` specifies (doc attributes
-  v1). A malformed attribute fails the call with `doc_attribute_malformed`
-  or `doc_attribute_duplicate_key`. The declarations add `DocAttributes`,
-  `DocItem`, `DocAttribute`, `DocArgument`, `DocValue`, `SourceOrigin` and
-  `DocAttributesSuccess`. The other functions are unchanged.
-- **`gen --json` reports each entry's identities.** Every entry that compiled
-  (`written`, `unchanged` or `drifted`, with or without `--check`) carries
-  `identities: { contract_id, interface_id }`, equal to its envelope's
-  `contract.identities` and to the lines the human report prints, under the
-  key names `project --json` and `check --json` already use. `interface_id`
-  is absent when the `.did` has no actor; a `failed` entry has no
-  `identities`. The declarations add `CliIdentities` and the optional
-  `CliEntryReport.identities`; `Identities` is unchanged, its `interface_id`
-  still required. `schemaVersion` stays `1`, since adding a field does not
-  change it. A build step no longer has to parse the envelope to learn the
-  interface identity.
-
-### Generated modules
-
-- **BREAKING**: a declared `blob`, `record {}` or `variant {}` names only
-  itself. Each of the three has one fixed rendering (`Uint8Array` /
-  `$.c.blob()`, `Record<string, never>` / `$.c.unit()`, `never` /
-  `$.c.variant({})`), and every use now renders it, as every use of a
-  primitive already did. Before, the alias of that shape whose name sorted
-  first, wherever it sat in the file, named every use of it: beside
-  `type Hash = blob`, a field written `memo : opt blob` read `Hash | null`
-  and its builder was `$.c.opt($Hash)`. Now it reads `Uint8Array | null`
-  with `$.c.opt($.c.blob())`, and `type Subaccount = blob` is emitted as
-  `export type Subaccount = Uint8Array`, so a field written
-  `subaccount : opt Subaccount` reads `Uint8Array | null` too. Value types,
-  wire bytes and envelopes do not change for it, and every declaration is still
-  exported under its name. A module with two aliases of one of these shapes,
-  or one alias and a plain use, changes text, so `gen --check` reports it as
-  drifted until `gen` runs again. Measured on the repository's 44 tracked
-  `.did` files against 0.3.0: of the 40 that generate, three modules change,
-  `shadowing.did`'s and the two fixtures added for this change. A
-  declaration of one of these shapes named after an export of the module
-  (`actor`) is omitted on its own and no longer takes the other uses of the
-  shape with it; `@candid-core/schema` 0.5.0's `schemaFromContract` applies
-  the same rule.
-
-## 0.3.0 — 2026-10-10
-
-Embeds `candid-core` 0.1.0-beta.3 and the `candid-core-ts` generator from the
-same repository commit the release is dispatched from; the release record
-names the exact SHA. That commit's `candid-core` source is ahead of the
-0.1.0-beta.3 archive on crates.io by five changes not yet in a crate release:
-the four 0.2.0 already carried (a `.did` source may begin with one UTF-8 byte
-order mark; a run of more than 256 consecutive comments is refused; a type on
-a cycle that passes only through `opt` is refused; the crate's Contract JSON
-loaders refuse a struct written as a JSON array) and one more, the crate's
-Contract JSON loaders refuse a unit variant written as a JSON map
-(`"primitive": {"nat": null}` for `"primitive": "nat"`), which beta.3's
-loaders accept. No input of this package reaches the last two: `gen`,
-`project`, `check` and the four library functions read `.did` sources and
-never load a Contract document. The embedded compiler therefore compiles
-every `.did` as 0.2.0's does: every input both accept compiles to the same
-Contract and identities, every envelope `gen` writes is byte-identical to
-0.2.0's, and envelopes still name 0.1.0-beta.3 as their producer.
-
-A stable release, published under the npm `latest` dist-tag, so a plain
-`npx @candid-core/cli` runs it; pin it in a project,
-`npm install --save-dev --save-exact @candid-core/cli`. The `beta` dist-tag
-stays on 0.2.0-beta.1.
-
-**It pairs with exactly one schema release.** The optional peer is exactly
-`@candid-core/schema` `0.4.0` (exactly `0.3.0` in 0.2.0). Each method of the
-`Actor` a generated module declares is typed with `$.WithMode`, which
-`@candid-core/schema` 0.4.0 adds, so a module with an actor method does not
-compile against 0.3.0 (`TS2694`, "has no exported member 'WithMode'", once
-per method). npm refuses to install a mismatched pair (`ERESOLVE could not
-resolve`). Install the pair at exact versions, together.
-
-**Upgrading from 0.2.0.** Two changes break something, each marked
-**BREAKING** below, and both are about generated modules: the peer moves to
-`@candid-core/schema` 0.4.0, which a module with an actor method needs; and
-the text of every generated module with a declaration or an actor changes,
-so `gen --check` reports each module 0.2.0 wrote as drifted (exit 1) until
-you run `gen` again. Upgrade both packages in one step and regenerate.
-Envelopes do not change. Code that imports the generated names keeps
-compiling, with one exception: type-level code that compares a method type
-of `Actor` for exact equality, such as an `Equal<A, B>` test helper, now
-sees the `WithMode` intersection. The commands `project` and `check`, the
-library functions `projectDid` and `checkCompatible`, and their types are
-additive; `gen`, `didToContract` and `didToModule` keep their grammar,
-signatures and results but for the module text.
-
-### Added
-
-- **`candid-core-cli project <in.did> --methods <a,b,...> -o <out.did>`**
-  writes a `.did` holding only the methods named and every declaration they
-  reach, as one self-contained file, and prints the interface identities of
-  the input and of the projection. The output is deterministic: the same
-  input and the same set of names give the same bytes, in any order. It
-  keeps declaration names, doc comments (a tuple element's included: a
-  tuple with a documented element is written one element per line) and
-  argument names, so `gen` on the projection emits the same declarations,
-  docs and modes as on the full interface, with an `Actor` that lists only
-  the projected methods. A service class's init arguments are dropped. An
-  unknown method name fails with `unknown_method`, one per distinct name,
-  the first listing the service's methods in its `notes`, once; an empty
-  list (`--methods ""`) with `empty_method_list`, a source with no service
-  with `no_service`; each exits 1 and writes nothing. The unknown-method
-  diagnostics are bounded at 4 MiB in all, each counted as the JSON writes
-  it (the list of methods aside), the names past that bound counted in one
-  `resource_limit_exceeded` diagnostic (`projection_diagnostic_bytes`)
-  instead of reported. A projection is at
-  most 1 MiB, the compiler's bound on one source, since it is compiled
-  again: a larger one fails with `resource_limit_exceeded`
-  (`projection_bytes`), exit 1, as soon as writing it reaches that bound.
-  Every name, requested or reached, is found by binary search among names
-  sorted once. Methods are written in name order, a service import's among
-  the entry's. `-o` is required, and may not be, or become, a source of the
-  input (the entry or any `.did` beneath its directory, which `project` reads
-  as `gen` does): naming one of those files by any path, symlink or hard
-  link, or a new `.did` beneath that directory, fails with
-  `output_is_input`, exit 1, and writes nothing. An output that cannot be
-  read or written fails with `output_write_failed` (its `notes` hold the
-  system error code), exit 1; an existing output of another size is
-  replaced without being read. `--json` prints one document instead of the
-  report, and `{ ok: false, diagnostics }` for every failure.
-- **`candid-core-cli check <written.did> --against <live.did>`** exits 0
-  when the live interface is still a Candid subtype of the written one, and
-  1 otherwise: every written method must exist in the live service with the
-  same mode, its arguments contravariant and its results covariant, and
-  methods only the live service has are ignored. Each finding names its
-  method and a stable code (`method_missing`, `mode_changed`,
-  `method_incompatible`, the warning `special_opt_rule`, and
-  `resource_limit_exceeded`) and, inside a type, the path where the check
-  failed. A `special_opt_rule` warning is reported at every path that
-  decodes as `null` along which no pair of types repeats, a shared type
-  under each path that reaches it. Past 1,000 warnings a method reports the
-  first 1,000 and a `resource_limit_exceeded` warning; its verdict stands.
-  A method whose check reaches its depth or work bound fails closed; work
-  is counted in steps, each one unit of work done (a pair of types visited,
-  a field, arm, method or value examined or passed over, a path segment a
-  warning or a failure copies or a warning re-examines). A step reads no
-  name: service methods are paired by ranks computed once per check and a
-  field's name is read by its position, so a step's cost does not grow with
-  the length of the names: it does a bounded amount of work, and its
-  lookups in the maps of type pairs the walk keeps take time logarithmic in
-  their size. The
-  check as a whole is bounded too, so many methods sharing one type cannot
-  multiply the per-method bounds: 10,000,000 steps (one more per method),
-  10,000 `special_opt_rule` warnings and 4 MiB of reported diagnostics, each
-  counted as the JSON response writes it, keys and indentation included, in
-  all (`check_total_steps`, `check_total_warnings`, `check_output_bytes`);
-  a diagnostic is measured only up to the first string that passes the byte
-  bound, so long names cannot make the measuring itself slow. So the walk's
-  time grows with its steps (times that logarithm) and the reported
-  diagnostics' with their bytes; compiling both sides, within the
-  compiler's own limits, and ranking the method names are done once per
-  check, before the walk. Methods are checked in name order; when the step
-  or warning bound is reached, that method and every method after it get
-  one `resource_limit_exceeded` error each and nothing else. Those count
-  against the 4 MiB like any other diagnostic, and once a method's
-  diagnostics would pass it, that method and every method after it are
-  counted in one last `resource_limit_exceeded` error
-  (`check_output_bytes`), which names no method and holds the count in
-  `unreported_methods`. Either way the check exits 1, and a response is at
-  most 4 MiB and 1,016 bytes, however many methods the written side has.
-  Below these bounds a method's findings do not depend on the other
-  methods. The report prints the live interface identity, so an unchanged
-  interface can be told from one that changed compatibly.
-- **`projectDid(sources, methods)` and `checkCompatible(written, live)`**,
-  the library functions behind the two commands, exported beside
-  `didToContract` and `didToModule`, with their types (`ProjectionSuccess`,
-  `CompatibilityReport`, `CompatibilityDiagnostic`, whose `method` is absent
-  only on the `check_output_bytes` diagnostic and whose
-  `unreported_methods` is present only there, `CheckFailure`,
-  `Identities`). Neither fetches anything; the package still has no runtime
-  dependencies.
-
-### Changed
-
-- **The usage text lists the three commands.** A usage error still exits 64
-  with the usage on stderr and nothing on stdout; its text now has three
-  lines, one per command.
-
-### Generated modules
-
-- **Compiler errors name the types you import.** A generated module now
-  declares each declaration's type under its Candid name and keeps the
-  `$`-prefixed local for the schema value only, so an app's TypeScript errors
-  read `Account` and `Actor`, the names it imports, where they read
-  `$Account` and `$Actor`:
-
-  ```ts
-  export type Account = { owner: $.Principal; subaccount: Uint8Array | null };
-  const $Account: $.Schema<Account> = $.c.rec(() => $.c.record({ … }));
-  export { $Account as Account };
-  ```
-
-  Every export name, and what each one is as a type and as a value, is
-  unchanged, and so is every module's set of declarations. A name that
-  cannot be a type in the module keeps the `$` local for its type too: a
-  global type the generated types use (`Array`, `Record`, `Uint8Array`,
-  `Promise`), and a word TypeScript refuses as a type's name (`delete`,
-  `string`, `default`, `keyof`, `readonly`, …). So `type $Array = …` still
-  appears, and errors about it still name `$Array`. Code that imports the
-  generated names is unaffected; code that parses or patches the generated
-  source must follow the new text.
-- **BREAKING**: the text of every generated module with a declaration or an
-  actor changes, by the item above and the one below, so `gen --check`
-  against a module 0.2.0 wrote reports it as drifted, exit 1, until `gen`
-  runs again. Measured on the repository's 41 tracked `.did` files: the 37
-  that generate give a different module and a byte-identical envelope.
-- **Each `Actor` method carries its mode.** `gen` and `didToModule` now emit
-  each method of `Actor` as its call signature intersected with
-  `$.WithMode<mode>` (`"query"`, `"composite_query"`, `"update"` or
-  `"oneway"`), which `@candid-core/schema`'s `ModeOf` reads back, so a call
-  layer can tell a query from an update at compile time:
-
-  ```ts
-  export type Actor = {
-    icrc1_balance_of: ((arg0: Account) => Promise<bigint>) & $.WithMode<"query">;
-    icrc1_transfer: ((arg0: TransferArg) => Promise<TransferResult>) & $.WithMode<"update">;
-  };
-  ```
-
-  The call signatures, the method names and the module's exports are
-  unchanged, and an actor with no methods still generates an empty `Actor`.
-  Type-level code that compares a method type for exact equality sees the
-  intersection; `Parameters<>` and `ReturnType<>` do not.
-- **BREAKING**: `WithMode` is new in `@candid-core/schema` 0.4.0, so a
-  module with an actor method needs that release: against 0.3.0 it fails to
-  compile with `TS2694` ("has no exported member 'WithMode'"), once per
-  method. The peer moves to exactly `0.4.0` for this reason.
-
-## 0.2.0 — 2026-10-06
-
-Embeds `candid-core` 0.1.0-beta.3 and the `candid-core-ts` generator from the
-same repository commit the release is dispatched from; the release record
-names the exact SHA. That commit's `candid-core` source is ahead of the
-0.1.0-beta.3 archive on crates.io by four changes not yet in a crate release:
-a `.did` source may begin with one UTF-8 byte order mark, which beta.3 refuses
-with "Unknown token"; a run of more than 256 consecutive comments between two
-tokens is refused with `resource_limit_exceeded` (below), which beta.3
-compiles up to a stack-dependent length and then aborts on; a type on a cycle
-that passes only through `opt` is refused with `did_type_check_error`
-(below), which beta.3 compiles; and the crate's Contract JSON loaders refuse
-a struct written as a JSON array, which beta.3's loaders accept. No input of
-this package reaches the last one: `gen`, `didToContract` and `didToModule`
-read `.did` sources and never load a Contract document. Every input both
-accept compiles to the same Contract and identities, and envelopes still name
-0.1.0-beta.3 as their producer.
-
-`@candid-core/schema` 0.3 breaks the 0.2 API (principal values are canonical text, collapsing opts are boxed, every `vec nat8` is a `Uint8Array`, generated modules use a new binding layout and may omit declarations, and the `./actor`, `./transport-icp`, `./forms` and `./labels` subpaths are gone); there is no compatibility layer.
-
-The first stable release of the 0.2 line. It is published under the npm
-`latest` dist-tag, so a plain `npx @candid-core/cli` runs it; pin it in a
-project, `npm install --save-dev --save-exact @candid-core/cli`. The `beta`
-dist-tag stays on 0.2.0-beta.1.
-
-**It pairs with exactly one schema release.** The optional peer is exactly
-`@candid-core/schema` `0.3.0` (`^0.2.0` in 0.1.0, exactly `0.3.0-beta.1` in
-0.2.0-beta.1). The modules this generator emits need that release's
-`Principal` export and boxed options, which 0.2.0 does not have, and the
-generator and that release's `schemaFromContract` agree on blobs and on
-omitted declarations only when both come from the same release. npm refuses
-to install a mismatched pair (measured with npm 11.3.0: `ERESOLVE could not
-resolve`, exit status 1); the 0.2.0-beta.1 entry below says npm only warns,
-which was wrong for a published peer. Install the pair at exact versions.
-
-**Upgrading from 0.1.0.** 0.2.0 is 0.2.0-beta.1 plus the changes in this
-entry, so the upgrade is this entry and the 0.2.0-beta.1 entry below, read
-together. Every break in either is marked **BREAKING**: from 0.2.0-beta.1, the
-`$` binding layout, `$.Principal`, boxed collapsing opts, a declared primitive
-naming only itself and every `vec nat8` typed `Uint8Array`, and omission in
-place of refusal (`gen`'s exit status and `didToModule`'s result); from this
-entry, the refusals of a long comment run and of a type on a cycle through
-`opt` alone. JSDoc from `.did` doc comments and
-`gen`'s several entries, `--json` and `--check` are additive. The library's
-three functions keep their names and signatures, and `lib/index.d.ts` and the
-command grammar are unchanged since 0.2.0-beta.1.
-
-### A long run of comments is refused with a resource diagnostic
-
-The embedded compiler now refuses a `.did` file with more than 256 consecutive
-comments between two tokens. The upstream Candid tokenizer it embeds spends one
-stack frame on each comment it skips, so the compiler counts the run first,
-without recursing, and refuses an over-long one before that tokenizer runs.
-Before, a long enough run exhausted the WebAssembly stack: measured with the
-published tarballs (Node 24.2, macOS arm64), 0.2.0-beta.1's `gen` compiled a
-file with 2 728 consecutive `//` lines and failed at 2 729 with
-`internal_error` "Maximum call stack size exceeded", and 0.1.0's compiled
-2 825 and crashed at 2 826 with an uncaught `RangeError`; the threshold moves
-with the toolchain and the engine.
-
-- **BREAKING (input)**: this refuses files that `gen` accepted before: any
-  `.did` in the bundle with a run of 257 to about 2 700 or 2 800 comments,
-  such as a license header written as `//` lines. `gen`, `didToContract` and
-  `didToModule` report `resource_limit_exceeded` with resource
-  `source_nesting`, limit 256 and `observed` 257, through the existing
-  diagnostic path (the `{ ok: false, diagnostics }` document, or `--json`)
-  with exit status 1. A longer run, which failed with `internal_error` before
-  (an uncaught `RangeError` in 0.1.0), gets the same diagnostic. The CLI
-  compiles at the compiler's default limits and has no flag to raise this one:
-  write such a header as a single `/* */` block, which counts as one comment,
-  or shorten it. Line and block comments count alike;
-  blank lines between comments do not end a run, any token does, a nested
-  block comment counts once, and comment markers inside a string are not
-  comments.
-- **Nothing else moves.** A file within the limit generates the same module and
-  the same envelope, with the same identities and documentation, as before.
-
-### The embedded generator renders on an explicit stack
-
-- The embedded `candid-core-ts` generator keeps its pending work on an explicit
-  stack instead of recursing once per type level, so generation uses constant
-  call-stack depth in the Contract's nesting. It also refuses a Contract with a
-  cycle that passes through no declared node, which a TypeScript type alias
-  cannot spell. No `.did` source produces such a Contract (a recursive Candid
-  type needs a name), so no input `gen` accepts is affected: every module it
-  writes is byte-identical to what 0.2.0-beta.1 writes for the same input, and
-  `didToModule`, which takes `.did` sources, returns the same result.
-
-### A type on a cycle through `opt` alone is refused
-
-The embedded compiler now refuses a type that lies on a cycle passing only
-through `opt`: `type T = opt T;`, `type T = opt opt T;`,
-`type A = opt B; type B = opt A;`, or the same through an alias. Decoding a
-value that is not an `opt` at such a type unwraps `opt` without end, so no
-decoder can answer for it; a generated schema for it ended in a depth refusal.
-
-- **BREAKING (input)**: this refuses files that `gen` accepted before:
-  `gen`, `didToContract` and `didToModule` report `did_type_check_error`,
-  naming the type ("type T lies on a cycle that passes only through opt;
-  …"), through the existing diagnostic path (the `{ ok: false,
-  diagnostics }` document, or `--json`) with exit status 1, and write nothing
-  for that entry. The upstream Candid checker accepts these files; the
-  refusal is candid-core's own. 0.1.0 refused them too, with
-  `ts_generation_refused` at generation, because each such type wraps `opt`
-  in `opt`; 0.2.0-beta.1 generates them, boxed.
-- **A cycle with any other constructor on it still compiles**: `type L = opt
-  record { head : nat; tail : L }`, `type T = opt vec T`, `type T = record {
-  a : opt T }`, `type T = opt variant { a : T }`.
-- **Nothing else moves.** Every other file generates the same module and the
-  same envelope, with the same identities and documentation, as before.
-
-## 0.2.0-beta.1 — 2026-10-02
-
-Embeds `candid-core` 0.1.0-beta.3 and the `candid-core-ts` generator from the
-same repository commit the release is dispatched from; the release record
-names the exact SHA. That commit's `candid-core` source is ahead of the
-0.1.0-beta.3 archive on crates.io by one change not yet in a crate release: a
-`.did` source may begin with one UTF-8 byte order mark, which beta.3 refuses
-with "Unknown token". Every input beta.3 accepts compiles to the same Contract
-and identities, and envelopes still name 0.1.0-beta.3 as their producer.
-
-`@candid-core/schema` 0.3 betas break the 0.2 API (principal values are canonical text, collapsing opts are boxed, every `vec nat8` is a `Uint8Array`, generated modules use a new binding layout and may omit declarations, and the `./actor`, `./transport-icp`, `./forms` and `./labels` subpaths are gone); there is no compatibility layer.
-
-The first beta of the 0.2 line, and the first prerelease of this package. It is
-published under the npm `beta` dist-tag, so `latest` stays on 0.1.0; ask for it
-by its exact version, `npm install --save-exact @candid-core/cli@0.2.0-beta.1`,
-or run it as `npx @candid-core/cli@0.2.0-beta.1`.
-
-**It pairs with exactly one schema release.** The optional peer moves from
-`@candid-core/schema` `^0.2.0` to exactly `0.3.0-beta.1`. The modules this
-generator emits need that release's `Principal` export and boxed options, which
-0.2.0 does not have, and the generator and that release's `schemaFromContract`
-agree on blobs and on omitted declarations only when both come from the same
-release. While the two packages move in lockstep, every `@candid-core/schema`
-beta is paired with a new beta of this package that raises the exact peer.
-Because the peer is optional, npm does not refuse a mismatched pair: it warns
-`ERESOLVE overriding peer dependency` and installs anyway, and the result does
-not type-check. Install the pair at exact versions.
-
-Every break below is marked **BREAKING**, ordered for a reader upgrading from
-0.1.0: what the emitted module looks like, then what it emits for interfaces it
-used to refuse, then the command line. The library's three functions keep
-their names and signatures.
-
-### Generated modules bind `$`-prefixed locals
-
-The embedded generator changes the layout of every module it emits. A module
-imports the schema runtime as a namespace and binds each declaration as a local
-whose name starts with `$`, exported under its Candid name:
-
-```ts
-import * as $ from "@candid-core/schema";
-
-type $Tokens = { e8s: bigint };
-const $Tokens: $.Schema<$Tokens> = $.c.rec(() => $.c.record({ e8s: $.c.nat64 }));
-export { $Tokens as Tokens };
-```
-
-- **BREAKING**: the text of every generated module changes. `import
-  { Tokens, actor, type Actor } from "./ledger"` resolves exactly as before,
-  so code that imports the generated names is unaffected by the layout;
-  code that parses or patches the generated source, or relied on its
-  module-scope names (`export type X`, `export const X`, the `c` and `Schema`
-  bindings, the separate `import type { PrincipalValue }` line), must follow
-  the new layout.
-- **BREAKING**: declarations the generator used to refuse with
-  `ts_generation_refused` now generate: names that collided with the module's
-  own bindings (`c`, `Schema`, `PrincipalValue`), with the global types its
-  lowerings use (`Array`, `Record`, `Uint8Array`, `Promise`), or that are
-  TypeScript reserved words (`delete`, `string`). Import them by name,
-  renaming where needed (`import { delete as del } from "./service"`). A
-  declaration named `default` becomes the module's default export.
-- Declarations named `actor` or `Actor` stay reserved: those are the
-  module's own export names. They are omitted from the module rather than
-  refusing it; see "Unrepresentable declarations are omitted, not refused".
-
-### Generated modules type principals as `$.Principal`
-
-- **BREAKING**: the embedded generator emits `$.Principal` wherever it
-  emitted `$.PrincipalValue`: principal fields, func reference aliases
-  (`{ principal: $.Principal; method: string }`), service aliases, and the
-  `actor` schema (`$.Schema<$.Principal>`). The paired `@candid-core/schema`
-  release replaces `PrincipalValue` (`{ toText(): string }`) with
-  `Principal`, canonical principal text as a branded string: a decoded
-  principal is that text, and encoding accepts only it, so an SDK `Principal`
-  converts once with `principal(sdkPrincipal)`.
-- A declaration named `Principal` still generates, bound as `$Principal` and
-  exported as `Principal`.
-
-### Options whose inner type admits `null` are boxed
-
-- **BREAKING**: the embedded `candid-core-ts` generator no longer refuses an
-  `opt` whose inner type is another `opt`, `null`, or `reserved` (its
-  `TsGenError::UnrepresentableOption` is removed). Such declarations now
-  generate, with the present value boxed: `opt opt nat` emits
-  `{ some: bigint | null } | null` with builder `$.c.opt($.c.opt($.c.nat))`.
-  Interfaces without such an `opt` are unaffected by this change.
-
-### A declared primitive names only itself
-
-- **BREAKING**: the embedded generator no longer renders a use of a primitive
-  by a declaration's name. The Contract arena shares one node per structure, so
-  a name recorded for `nat64` was rendered at *every* `nat64` in the interface,
-  including ones that never wrote it. A use of a primitive — a field, an array
-  element, a variant arm, a method argument — now renders structurally
-  (`bigint`, `$.c.nat64`, and `$.Principal` for `principal`); a declaration of
-  the primitive is still emitted and exported as itself. `type Memo = nat64;
-  type R = record { a : nat64; b : Memo }` now generates `R = { a: bigint; b:
-  bigint }` where it generated `{ a: Memo; b: Memo }`, and the ICRC-1
-  ledger's `TransferArg.amount`, written `Tokens` beside `type BlockIndex =
-  nat`, is `bigint` and no longer `BlockIndex`.
-- **BREAKING (value type)**: every `vec nat8` is `Uint8Array` / `$.c.blob()`,
-  whatever its element type is called. Before, a single `type Byte = nat8`
-  anywhere in the interface turned every `blob` and `vec Byte` into
-  `Array<Byte>`, a `number[]`. For an interface with a declared `nat8` alias
-  the generated blob types change from `number[]` to `Uint8Array`; the encoded
-  bytes do not change. The paired `@candid-core/schema` release makes
-  `schemaFromContract` load every `vec nat8` as a blob too, so a generated
-  module and a loaded schema agree.
-- **Trade-off**: a declared alias no longer survives as the *spelling* of a
-  field's type (`amount : Tokens` reads `amount: bigint`); the type is the
-  same. Two structurally equal *record* declarations still collapse to the
-  first name, as before.
-
-### `.did` doc comments become JSDoc
-
-- The embedded generator writes each `.did` doc comment as JSDoc: above the
-  generated type and const of a declaration, on a record property, on a
-  variant arm's `tag`, on a method of the `Actor` type, and on the `actor`
-  export. Docs are the `///` run (or plain `//` lines) directly above the
-  item; block comments are not docs. The doc text is escaped — `*/` becomes
-  `*\/`, an `@` that could start a tag becomes `\@`, a code fence has each
-  backtick escaped — so a comment cannot end early, forge a tag or swallow the
-  generated ones.
-- A method's `@param` tags name the `.did`'s argument names, and the `Actor`
-  method's parameters take the same names; an unnamed argument, a reserved
-  word, a name that is not identifier-shaped or a collision stays `arg{n}`.
-- A record or union with a documented member spans several lines; without
-  docs its one-line form is unchanged. Tuple elements carry no docs.
-- Which occurrence documents a node the arena has de-duplicated is one rule:
-  the declaration (or actor) whose structure is being emitted; occurrences
-  inside one declaration that disagree are dropped. No Contract, envelope,
-  identity or wire byte changes — docs are provenance — and the
-  `org.candid-core.field-names/v1` extension is untouched.
-- **Additive**, with one naming change: a method written `a : (x : nat) -> ()`
-  now takes `x` as its parameter name where it took `arg0`, and gains an
-  `@param x` block, whether or not the file has a single comment. Types,
-  values and wire bytes do not move either way.
-
-### Unrepresentable declarations are omitted, not refused
-
-The embedded generator leaves out a declaration it cannot represent, with
-everything that references it, instead of refusing the whole interface. One
-exotic declaration no longer costs the module. The paired
-`@candid-core/schema` release makes `schemaFromContract` leave out the same
-declarations and methods, with the same reasons, so a generated module and a
-loaded contract agree.
-
-- **BREAKING (exit status)**: `candid-core-cli gen` used to print a
-  `ts_generation_refused` diagnostics document and exit 1 for an interface
-  with a record field or variant arm named like the `_N_` numeric-id
-  rendering (`record { _0_ : nat }`), a variant arm whose payload is a
-  declared `opt` of an uninhabited type (`type W = opt empty; type V =
-  variant { a : W }`), or a declaration named `actor` or `Actor`. It now
-  writes the module without those declarations and exits 0, printing one
-  `warning: omitted …` line per omission on stderr. A script that relied on
-  the non-zero exit to reject such an interface must read the warnings, or
-  `omitted`, instead. Stdout's report is unchanged.
-- **BREAKING**: `didToModule` returns `{ ok: true, module, omitted }` for
-  those inputs where it returned `{ ok: false, diagnostics }`. No Candid
-  source reaches `ts_generation_refused` any more; the code stays, reserved
-  for an invalid contract graph.
-- **The closure**: an omitted declaration takes with it every declaration
-  that references it through any edge — a field, an alias, `vec`/`opt`/record
-  nesting, a `func` type's arguments or results, a `service` type's methods —
-  up to the containing declaration. A record holding a
-  `service { f : (Bad) -> () }` is omitted whole, not stripped of `f`: a
-  service value's wire type is its full method table, and a peer would see a
-  different type. Only the actor drops individual methods, from both the
-  `actor` schema and the `Actor` type, since calling a method never encodes
-  the actor's own service type. The actor itself is never omitted, and a class
-  actor whose init arguments reference an omitted declaration keeps every
-  method (init arguments are not generated).
-- **Everything kept is unchanged**: the modules for the other golden
-  interfaces are unchanged by omission, and a test pins that, for an interface
-  with omissions, every emitted declaration, `Actor` signature and actor
-  method is byte-identical to the module generated with the omitted
-  declarations deleted from the source.
-- **`ModuleSuccess.omitted`** (new, always present, empty when nothing is
-  omitted): an array of `{ kind, name, reason, via? }`, declarations first,
-  then methods, each sorted by name. `kind` is `"declaration"` or
-  `"method"`. `reason` is one of `reserved_field_name`,
-  `ambiguous_variant_arm`, `reserved_export_name`, `invalid_declaration_name`
-  (Contract documents only; Candid source cannot produce one) or
-  `references_omitted`; `via` is present only for `references_omitted` and
-  names the omitted declaration referenced. This is a serialized shape: the
-  set of `reason` codes is closed, and a new code is a breaking change. The
-  type is exported by name, as `Omission`.
-- **The module header** lists the same entries in the same order, one line
-  each, directly under the first line:
-  `// Omitted: type Holder (references_omitted via Bad)`. A module that omits
-  nothing has no such line.
-
-### `gen` takes several entries, and gains `--json` and `--check`
-
-- `candid-core-cli gen <a.did> [<b.did> …] [-o <dir>] [--json] [--check]`.
-  Each entry generates its own `<stem>.ts` and `<stem>.envelope.json` into the
-  one `-o` directory, byte-for-byte what a run of that entry alone writes. An
-  entry's bundle is the `.did` files beneath its own directory, with the bundle
-  limits applied per entry; entries sharing a directory share one read of it.
-  Two entries with the same stem (compared case-insensitively) are a usage
-  error (exit 64) before any work. Both rules may still change before 1.0.
-- A failing entry no longer ends the run: every entry is attempted, and the
-  exit code is 1 if any failed, 0 otherwise. Omissions do not fail an entry.
-  For one entry the behaviour is unchanged: the same `{ ok: false,
-  diagnostics }` document on stdout and exit 1.
-- **`--json`** prints exactly one JSON document on stdout and nothing else
-  (stderr stays empty): `{ schemaVersion, ok, check, entries, drift }`, with
-  per entry its `entry`, `status` (`written`, `unchanged`, `drifted` or
-  `failed`), `module` and `envelope` paths, `omitted`, and `diagnostics`. The
-  shape is documented in the README and typed as `CliReport` in
-  `lib/index.d.ts`; `schemaVersion` is `1`. The content-addressed identities
-  stay in the human report only.
-- **`--check`** generates in memory, compares byte-for-byte with the files on
-  disk, writes nothing (not even the output directory) and exits 1 listing
-  each missing or drifted file; it combines with `--json` (`drift` lists the
-  paths).
-- The CLI never reads stdin, and a test now pins that with a stdin that is an
-  open pipe nobody writes to.
-- **Behaviour change, not breaking**: an output file that already holds the
-  generated bytes is no longer rewritten, and its line reads
-  `unchanged <path>` where it read `wrote <path>`. Bytes, names and exit codes
-  are unchanged; scripts matching `wrote ` on a re-run should match
-  `unchanged ` too, or use `--json`.
-- Every path the CLI reports, in the document and in the human output, is the
-  entry or directory as passed (or `-o` joined with a file name), never a
-  resolved absolute path, so the same invocation prints the same bytes from any
-  working directory.
-- The library (`didToModule`, `didToContract`, `init`) keeps its signatures;
-  `ModuleSuccess` gains `omitted` (above), and `lib/index.d.ts` adds the
-  `Omission`, `CliReport`, `CliEntryReport` and `CliEntryStatus` types.
-
-## 0.1.0 — 2026-08-27
-
-Embeds `candid-core` 0.1.0-beta.3 and the `candid-core-ts` generator from
-the same repository commit the release is dispatched from; the release
-record names the exact SHA.
-
-The first version: the JavaScript-only on-ramp.
-
-- **`gen <service.did> [-o <dir>]`** emits the generated
-  `@candid-core/schema` module, the one-document `ContractEnvelope` with the
-  `org.candid-core.field-names/v1` field-name table, and prints the content-addressed identities. Imports resolve
-  from the entry's directory as an in-memory bundle; every generation
-  double-runs and the tool refuses to write on any byte mismatch.
-- **`didToContract` / `didToModule`** — the same two operations as a
-  library, for Node and browsers alike: one wasm-bindgen artifact over
-  `candid-core`'s `compiler` feature (`compile_with_resolver` +
-  `MemoryResolver`; no filesystem, no eval, no dynamic import) plus the
-  `candid-core-ts` generator. Failures are `{ ok: false, diagnostics }` with
-  the compiler's diagnostics verbatim; generator refusals surface as
-  `ts_generation_refused`, malformed requests as `invalid_request`.
-- **Parity is a gate, not a claim**: CI compares the wasm-built outputs
-  byte-for-byte against the repository's reviewed goldens and against the
-  native `candid-core compile --envelope` fixture, builds the artifact twice
-  from clean and requires identical bytes, and runs `didToContract` inside
-  headless Chrome feeding `schemaFromContract`, envelope-carried names
-  included.