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.jsonandschemas/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.