Pre-release Harn is pre-1.0 — the language, standard library, and CLI may change between releases. See the release notes

Code generation reference

harn codegen compiles a Harn tool contract into a closed, portable intermediate representation (IR). Installed backends consume that IR to generate clients and native handlers. Harn owns schema resolution, wire types, validation, and source coordinates. For existing clients, see Migrate typed tool clients.

Commands#

harn codegen ir --file server.harn --surface exports > contract.json
harn codegen validate-ir --input contract.json
harn codegen generate --file server.harn --plugin harn-codegen-backend --out generated
harn codegen generate --file server.harn --plugin harn-codegen-backend --out generated --check

--surface exports compiles public exports. --surface script loads the script's published tool registry. Script initialization can execute its declared effects. Both paths retain imported declaration identities and the complete compilation source census.

Repeat --select OPERATION to choose exact operation names. Omitting it selects every operation that the prepared catalog exposes. Missing output contracts and unsupported wire types produce structured diagnostics before a backend runs.

generate accepts --role client, --role server, or --role both (the default). Repeat --plugin-read-root DIR for an installed backend's dependencies. Original source files remain denied even when one of these roots contains them.

An optional --ir FILE supplies a frozen IR. Its catalog, binding, and IR digests must match a fresh compilation of --file, --surface, and --select. Validating an IR alone grants no filesystem authority.

Backend protocol#

A backend reads one harn-codegen-request/1.0 request from standard input and writes one harn-codegen-response/1.0 response to standard output. The request contains the selected role and a harn-codegen/1.0 IR with the closed wire graph, prepared MCP tool projection, operation contracts, features, and source references. Catalog schemas and MCP tool objects are opaque backend inputs; backends derive target types and codecs from the wire graph.

Harn validates the response's version, feature negotiation, source mappings, and relative artifact paths. Absolute paths, traversal, aliases, and symlink escapes are refused. Harn invokes the backend twice and requires identical artifacts before publishing them. --check reports drift without modifying the destination. Existing files that weren't generated by this backend aren't overwritten.

The backend receives an explicit environment and a private working directory. The process sandbox denies network access, registered credential paths, and the original source files. It permits the backend executable, declared installation roots, standard runtime files, and its private output workspace. A backend has 30 seconds per invocation, a 64 MiB response limit, and a 64 KiB stderr limit.

Portable contract#

The graph represents signed 64-bit integers, floats, exact decimals, tagged base64 bytes, lists, sets, tuples, string-keyed maps, closed records, nominal structs and enums, aliases, disjoint unions, literals, and null. Optional record fields retain absence separately from an explicit null. Recursive references use type identities rather than expanding definitions indefinitely.

Integer wire tokens use integer spelling. A float token such as 1.0, 1e0, or -0 doesn't become an integer. Decimal strings preserve scale and must use Harn's canonical spelling. Set uniqueness follows Harn value equality, including nested values; JSON text or host object identity isn't a substitute.

Source references identify logical documents and structural locations. They contain no rejected application values and grant no read authority. Physical source paths remain in Harn's private compilation context. Relocating identical source doesn't change its portable identities.

The catalog digest commits to the normalized catalog. The binding digest commits to executable wire and protocol behavior, excluding documentation and source coordinates. The IR digest commits to the complete portable IR. Validation checks all three and recompiles the embedded catalog through the same Harn owner.

Generated protocol artifacts#

harn dump-protocol-artifacts --output-dir DIR exports the mechanical contract:

  • harn-codegen.ts: closed TypeScript declarations.
  • harn-codegen-protocol.json: versions, wire facts, and MCP protocol constants.
  • schemas/harn-codegen-v1.schema.json: normalized IR schema.
  • schemas/harn-codegen-request-v1.schema.json and schemas/harn-codegen-response-v1.schema.json: backend messages.
  • schemas/harn-codegen-diagnostic-v1.schema.json: value-free diagnostics.
  • schemas/harn-tools-mcp-v1.schema.json: verified native binding profile.

Backends should consume these projections rather than maintaining another wire type table. See Native tool bindings for executing generated handlers through Harn's existing tool adapters.