[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7A5YRZ1MYFCJC8BP10YCFJG":3,"skill-same:01M7A5YRZ1MYFCJC8BP10YCFJG":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7A5YRZ1MYFCJC8BP10YCFJG","unibind",null,"How ix generates its SDKs: unibind lowers one Rust surface into TypeScript, Python, JVM and Elixir bindings, and the rule is that the IR carries intent while each backend renders its own language's idiom. Use when changing the SDK surface (crates\u002Fix\u002Fsdk-bind), adding or fixing a unibind feature, or when a generated API reads unidiomatically in any language.","harivansh-afk\u002Floom-index-e2e","harivansh-afk","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F73809867?v=4","01M7A5RBDGB0YMBHVWXCS0VYE7","hari","01M7A5RBEKV38Y878XPTCR4SJ3",0,"MIT","https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e\u002Fblob\u002Fmain\u002Fskills\u002Funibind\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: unibind\ndescription: \"How ix generates its SDKs: unibind lowers one Rust surface into TypeScript, Python, JVM and Elixir bindings, and the rule is that the IR carries intent while each backend renders its own language's idiom. Use when changing the SDK surface (crates\u002Fix\u002Fsdk-bind), adding or fixing a unibind feature, or when a generated API reads unidiomatically in any language.\"\n---\n\n## The rule\n\nOne Rust surface, four idiomatic SDKs. Not four transliterations of one.\n\nThe IR carries **intent**: this constructs the object, this owns something that\nmust be released, this is a stream, this is a closed set of variants. Each\nbackend renders its own language's idiom for that intent. A shape that only one\nlanguage has never reaches the IR.\n\nThe failure mode this exists to prevent is lowest-common-denominator design.\nWhen the IR could only say \"free function\", \"method with a receiver\" and \"sync\nconstructor\", every language got\n\n    client.machines().create({ template: \"docker.io\u002Flibrary\u002Fpython:3.12\" })\n\nbecause that was the only sentence all four backends could speak. The idiomatic\ncall is `Machine.oci(...)` in all four, and it looks different in each: a static\nmethod returning a promise, a static coroutine, a static method returning a\nfuture, a module function returning a tagged tuple. One intent, four renderings.\n\nReviewing a generated surface, ask what a native library in that language would\nlook like, not whether the shape matches the Rust. A `.d.ts` that reads like\nRust with braces is a defect, and so is a `.pyi` that reads like TypeScript.\n\n## Intent table\n\n| Intent | Rust | TypeScript | Python | Kotlin | Elixir |\n|---|---|---|---|---|---|\n| construct, async | `#[unibind(associated)]` `async fn` returning `Self` | `static oci(): Promise\u003CMachine>` | `@staticmethod async def oci() -> Machine` | `suspend fun` in a `companion object` | `Machine.oci(...) -> {:ok, machine}` |\n| release at scope end | `object(resource)` + `close` | `Symbol.asyncDispose`, so `await using` | `__aenter__`\u002F`__aexit__`, so `async with` | `AutoCloseable`, so `use { }` | nothing; the BEAM drops the `ResourceArc`, or take a function |\n| closed variant set | `#[unibind::enumeration]` `enum Status { Running, .. }` | `export type Status = \"running\" \\| \"stopped\"` | `enum.StrEnum` | `enum class` | atoms |\n| variants with data | `enum Frame { Phase{..}, Done{..} }` | discriminated union, exhaustive `switch` | frozen dataclasses under a `Literal` tag, `match` | sealed interface over data classes, exhaustive `when` | tagged tuples, `case` |\n| identity | `MachineId(Uuid)` | branded string | `NewType` | `@JvmInline value class` | opaque type |\n| optionality | `Option\u003CT>` | `T \\| null` | `T \\| None` | `T?`, checked by the compiler | `nil` |\n| sequence | `UniStream\u003CT>` | `AsyncIterable` | `__aiter__`\u002F`__anext__` | `Flow\u003CT>` | `Stream` |\n| failure | error enum | error subclasses | exception hierarchy | sealed exception hierarchy | `{:error, reason}` |\n| a verb on the type | `#[unibind(associated)]` returning anything else | `static list(): Promise\u003CMachine[]>` | `@staticmethod async def list()` | `companion object` | module function |\n\nOne flag covers both associated rows, and the return type decides the\nrendering rather than the author: napi needs `factory` to build an instance\nfrom an async static and plain `#[napi]` for everything else, so\n`Machine.oci` and `Machine.list` are written the same way and come out\ndifferent. Saying it twice is a way to say it inconsistently.\n\n### One wire spelling, four type names\n\nThe closed-variant row is the one intent where the languages must agree on a\n*value*, not only on a shape: the same string is what TypeScript compares, what\na Python `StrEnum` member holds, and what the service already puts in its JSON.\nSo the rule splits in two.\n\n**The wire spelling is decided once, at lowering, and is the same in every\nlanguage.** It defaults to `snake_case` of the Rust variant, and\n`#[unibind::enumeration(rename_all = \"...\")]` picks another convention for the\nwhole enum. The conventions and their output are serde's, byte for byte, so a\nbinding cannot disagree with the JSON `#[serde(rename_all = ...)]` produces on\nthe same enum. `MachineProgress.kind` is `PascalCase` on the wire where every\nother closed set in the ix surface is `snake_case`, and that is exactly one\nword (`rename_all = \"PascalCase\"`) rather than a guess in each backend.\n\n**The type name, and any member identifier, is idiomatic per language.** The\ntype keeps the Rust `PascalCase` name unless `ts(name = ...)` \u002F `py(name = ...)`\nrenames it, like every other declared type. A member identifier only exists\nwhere the language has one: Python spells members `SCREAMING_SNAKE_CASE`\n(`MachineStatus.HARD_FAILURE == \"hard_failure\"`), and a TypeScript union has no\nidentifier at all, which is why per-variant renames are Python's business and\nthe ts backend ignores them.\n\nTypeScript gets a union of string literals, never a TS `enum`: what crosses is\na plain string, a union erases at compile time where an `enum` needs a runtime\nobject, and `JSON.parse` output is assignable to a union and not to an `enum`.\nPython gets `enum.StrEnum` (3.11+) because its member *is* a `str`, so\n`isinstance`, `is`, and a caller's pre-existing `status == \"running\"` are all\ntrue of one value; the extension builds the class at `#[pymodule]` init from\nthe same IR the `.pyi` declares, so there is no second source for the members.\n\nVariants that carry data are a different intent (the row below) and lowering\nstill refuses them, naming the enum and the variant.\n\nKotlin's async row is not just `suspend fun`. Structured concurrency is the\ncontract: a cancelled coroutine must abort the Rust future rather than\nleaving it running, so a suspending binding is written with\n`suspendCancellableCoroutine` plus `invokeOnCancellation`, which is the\nKotlin end of the same abort path the TypeScript backend drives from an\n`AbortSignal`. Streams are `Flow`, which is cold, cancellable and\nbackpressured by construction, so it carries the same contract without a\nsecond mechanism. Scope-bound release is `use { }` on `AutoCloseable`, the\n`with` of that language. Get those three right and a generated Kotlin SDK\ncomposes with `coroutineScope` the way a hand-written one would; get them\nwrong and every caller leaks a Rust task on the first cancellation.\n\nThe JVM column says Kotlin, not Java, and that is a decision rather than a\npreference. Java has no answer for the async row at all, which is why the\nbackend's own rejection message tells the caller to block on a runtime and\nmove the call to a virtual thread. Kotlin answers every row natively. The\nevidence that settled it: the only consumer of the JVM backend in either\nrepo is `index\u002Fpackages\u002Fminecraft\u002Fprobe-kt`, which is Kotlin, and whose\nheader describes what it consumes as \"the unibind-rendered **Java** class\".\nWe generated Java for a Kotlin caller. `index\u002Flib\u002Flanguages\u002Fkotlin.nix`\nalready builds that probe with `-Werror`, so the toolchain is in place, and\nthe backend is the least-built of the four, so re-basing it costs less now\nthan it ever will again.\n\nElixir keeps the table honest. It has no classes to hang a static method on and\nno scope-bound cleanup at all, so any IR concept that survives contact with\nElixir is intent rather than syntax. When a new concept has no Elixir answer,\nthat is a signal the concept is a Node or Python fact wearing a general name.\n\n## Types are the product\n\nA generated type that says `string` where the value is one of ten known words\nhas moved the specification into a doc comment, where no compiler reads it. Two\nrules follow.\n\n**A closed set is an enum, never a string.** `status`, `kind`, `phase`, `level`\nand every other field whose doc comment lists its legal values belongs in a Rust\nenum, so each backend can render its own closed type.\n\n**Variants that carry different data are one sum type, never one struct with\noptional fields.** The anti-pattern in our own surface today is\n`SwitchProgress`: a `kind: String` beside `phase`, `stdout`, `system` and\n`error`, each set on a different frame, every one optional because none of them\nis always there. The caller reconstructs by hand (`if (frame.finished &&\nframe.system)`) what a tagged union would have decided at compile time. It is a\nRust enum flattened into a struct because the IR had nowhere to put it.\n\n## State of the backends\n\nDo not promise a surface a backend cannot render. As of 2026-08-04:\n\n| | TypeScript | Python | JVM | Elixir |\n|---|---|---|---|---|\n| objects | yes | yes | **rejected outright** (`backend-jvm\u002Fsrc\u002Fmodule.rs`), no handle registry | yes, as `ResourceArc` handles |\n| async | yes | yes | **rejected outright** (`backend-jvm\u002Fsrc\u002Ffunction.rs`) | free functions only; object members rejected (`backend-ex\u002Fsrc\u002Fobject.rs`) |\n| associated functions | yes; `#[napi(factory)]` when it returns the object, plain static otherwise | yes, `#[staticmethod]` | no | no |\n| resource close | `close()` + leak warning | `close` + `__aenter__`\u002F`__aexit__` + `ResourceWarning` | none | flag ignored; the BEAM drop runs `Drop` |\n| scope-bound release | `[Symbol.asyncDispose]` in the generated JS wrapper, so `await using` works | `async with` | none | n\u002Fa |\n| unit enums | yes; union of string literals, plus `z.enum` | yes; `enum.StrEnum` | **rejected** (`backend-jvm\u002Fsrc\u002Fmodule.rs`); owes a Kotlin `enum class` | **rejected** (`backend-ex\u002Fsrc\u002Fmodule.rs`); owes an atom per variant |\n| data enums | **rejected by lowering**, naming the variant | same | same | same |\n| runtime validation | Zod schemas, `z.infer` types | **none**; Pydantic models are the gap | no | no |\n| error enums | yes | yes | yes | yes |\n\nTwo notes on that table. napi-rs itself cannot codegen `Symbol.asyncDispose`\nand has no attribute for it, but unibind emits its own JS wrapper class over\nthe napi addon, and that is where dispose is written, so `await using` works\ntoday. And the Zod row is the model for the Python gap: TypeScript consumers\nget runtime validation generated from the same IR that types them, Python\nconsumers get none.\n\nSo the shipped ix SDKs are TypeScript and Python. The JVM and Elixir backends\nserve other unibind consumers, and their gaps are stated in their own rejection\nmessages, which are worth reading before designing around them.\n\n## Examples are copied, so they are house style\n\nAn SDK example is read as a template, not as a demo, so anything hand-rolled\nin one becomes a pattern in somebody's codebase. Argument parsing is where\nthis shows up first: reach for the language's real parser, never index into\nthe raw argv.\n\n| | parser |\n|---|---|\n| TypeScript | `parseArgs` from `node:util`, stable since Node 20, so no dependency |\n| Python | `argparse`, as `packages\u002Fminecraft\u002Fprobe\u002Fmc_probe.py` already does |\n| Rust | `clap` |\n| Kotlin | `kotlinx-cli`, or `clikt` where subcommands earn it |\n\n`process.argv[2]` and `sys.argv[1]` accept anything, report nothing, and\nteach the reader to do the same. The same rule covers the rest of an\nexample's surface: use the standard library's path, time and JSON handling\nrather than string manipulation, because the example is the documentation\nthat gets executed.\n\n## A doc link resolves, or the build fails\n\nDoc comments reach four published surfaces, so a rustdoc link in one is a\nclaim about the *generated* API, not about Rust. unibind resolves every\nintra-doc link against the interface and renders it in each language's own\nspelling:\n\n| written | TypeScript | Python |\n|---|---|---|\n| ``[`Machine`]`` | `{@link Machine}` | `` `Machine` `` |\n| ``[`Machine::forward_port`]`` | `{@link Machine.forwardPort}` | `` `Machine.forward_port` `` |\n| ``[`MachineInfo::failure_reason`]`` | `{@link MachineInfo.failureReason}` | `` `MachineInfo.failure_reason` `` |\n| ``[`SnapshotStatus::Ready`]`` | `` `\"ready\"` `` | `` `SnapshotStatus.READY` `` |\n| ``[`IxError::NotFound`]`` | `{@link NotFound}` | `` `NotFound` `` |\n| ``[`Self::close`]`` | resolved against the enclosing type | same |\n\nTypeScript gets TSDoc, which editors resolve; Python gets a code span,\nbecause a `.pyi` has no link syntax a reader's tooling follows and Sphinx\nroles would be a second vocabulary in a file nobody runs Sphinx over. An\nenumeration variant is the one target with no identifier in TypeScript -- a\nunion member is a string -- so it renders the value a caller actually types.\nElixir and the JVM render code spans too, and have no conformance coverage\nfor links yet.\n\n**A link that names nothing fails generation**, naming the doc site and the\ndead target, the way rustdoc's `broken_intra_doc_links` does at `deny`. Every\ndead link is reported in one build, because a rename usually leaves several.\nThat gate is the point: a denylist of one renamed noun (which is what\n`artifact-sdk-vocabulary` was) cannot catch a link to a method that never\nexisted, and 214 dead links shipped in each published file before it existed.\n\nThree spellings and what they do:\n\n- ``[`Type::member`]`` is the form to write.\n- `[the docs](Type::member)` resolves the same way, and **the link text is\n  dropped** -- the target's spelling replaces the whole link, so write the\n  sentence around the reference rather than through it.\n- ``[`Type::member`][label]``, the reference form, is **refused**: its target\n  lives in a link definition, and nothing writes those into a `.d.ts` or a\n  `.pyi`, so it would ship as dead text with no error.\n\nTwo things that are deliberately not links: a Rust-side item the SDK reader\ncannot see (write `` `ix_sdk::SdkError` `` as a plain code span; brackets\nwould claim it is part of the surface), and a bare `[1]` in prose. A\nconstructor link renders as its type (``[`Session::new`]`` becomes `{@link\nSession}`), because no target language names a constructor -- so phrase the\nsentence for that rather than writing \"as [`Self::new`] received it\".\n\nRecords are the one doc site where the runtime text and the stub could\ndisagree, because a record's `#[pyclass]` lands on the user's own struct and\npyo3 reads its `\u002F\u002F\u002F` text. The macro writes the resolved lines back over\nthose attributes, so `help(Point)` and the `.pyi` say the same thing.\n\n## One surface, several files\n\n`#[unibind::export]` lowers one module, and lowering has to see all of it at\nonce: a type reference in a signature is classified against every declaration\nin the export, so no per-file pass could resolve `MachineInfo` without the\nfile that declares it. The export therefore names its other files:\n\n```rust\n#[unibind::export(parts = [\"src\u002Fsdk\u002Fmachines.rs\", \"src\u002Fsdk\u002Fsnapshots.rs\"])]\nmod _ix_sdk {}\n```\n\nEach listed file is a list of items -- the same items that would have been\nwritten inline, at the file's own indentation -- read and appended to the\nmodule before lowering. **Declaration order is the module's own items\nfollowed by the parts in listed order**, which matters because the generated\nlayout mirrors it: the list is the crate author's statement of that order,\nnot filesystem order and not the order macros expand in.\n\nThree compile errors keep the list honest:\n\n- a part listed twice, naming it;\n- a listed path that does not exist, naming it;\n- **a `.rs` file that sits with the parts but is not listed**, naming it.\n  Adding a file and forgetting to register it is the failure this catches; it\n  would otherwise be silently absent from the SDK.\n\nSo keep parts in a directory of their own, and put nothing else there.\n\nThe cost, stated plainly: rustc does not read the part files, the macro does,\nand stable Rust gives a proc macro no way to manufacture a span into a file\nit read. A type error inside a part is reported against the\n`#[unibind::export]` attribute; the offending code is still printed, but the\nfile and line are not the part's. unibind's own diagnostics name the item and\nthe part path instead.\n\n**Add to the file that owns the namespace.** The old rule in\n`crates\u002Fix\u002Fsdk-bind` was to append a new `impl` block at the end of the one\nfile rather than edit the blocks above, because a module boundary was not\navailable and several agents write here at once; that produced six `impl\nMachine` blocks spread over 5,000 lines. The file boundary does that job now:\na machines verb goes in `machines.rs`, and `Machine`'s verbs all live in\n`machine.rs`. Within a file, appending to the existing `impl` block is fine.\n\nReordering items across parts is not free. Records, enumerations, errors and\nobjects each keep their declaration order in the IR, and each object's\nmethods keep the order of the `impl` blocks that contribute them, so moving\none of those changes two published files while changing nothing. Private\nitems carry no IR position and move freely.\n\n## Adding an intent\n\nThe IR's function kind lives in lowering, not in the IR data: `Kind` in\n`core\u002Fsrc\u002Flower\u002Ffunc.rs` is `Free | Method | Constructor`, and an object carries\n`constructor: Option\u003CFunction>` beside `methods: Vec\u003CFunction>`, so kind is\npositional. A new intent is therefore a new arm there plus a new field on\n`ir::Object`, and then one rendering decision per backend:\n\n1. `core\u002Fsrc\u002Flower\u002Ffunc.rs`, `core\u002Fsrc\u002Flower\u002Fobject.rs`: accept the shape, and\n   say why in the rejection message for the shapes still refused.\n2. `core\u002Fsrc\u002Fir\u002Fdata.rs`: carry it.\n3. Each backend: render the local idiom, or refuse with a message naming the\n   idiom it would have rendered. A backend that cannot do it yet refuses\n   loudly; it never falls back to a shape from another language.\n4. Each conformance suite (`conformance\u002F`, `conformance-ts\u002F`, `conformance-jvm\u002F`,\n   `conformance-ex\u002F`): the fixture Rust surface plus assertions in the target\n   language. A feature with no conformance test in a language is not supported\n   in that language, whatever the renderer does. A lowering feature that is\n   not language-specific still needs one suite exercising it: `conformance-ex`\n   is split over `src\u002Fsurface\u002F*.rs`, which is what keeps `parts` covered.\n5. Break it and watch it fail. A renderer's snapshot test passes just as well\n   against the wrong output.\n\nAnything that has to be hand-written on top of a generated surface is a bug\nreport against unibind, not a layer to grow. `packages\u002Fsdk\u002Fsrc\u002Frepl.ts` is the\none sanctioned exception, and it earns it by being protocol logic rather than a\nsecond spelling of a generated verb.\n","## The rule\n\nOne Rust surface, four idiomatic SDKs. Not four transliterations of one.\n\nThe IR carries **intent**: this constructs the object, this owns something that\nmust be released, this is a stream, this is a closed set of variants. Each\nbackend renders its own language's idiom for that intent. A shape that only one\nlanguage has never reaches the IR.\n\nThe failure mode this exists to prevent is lowest-common-denominator design.\nWhen the IR could only say \"free function\", \"method with a receiver\" and \"sync\nconstructor\", every language got\n\n    client.machines().create({ template: \"docker.io\u002Flibrary\u002Fpython:3.12\" })\n\nbecause that was the only sentence all four backends could speak. The idiomatic\ncall is `Machine.oci(...)` in all four, and it looks different in each: a static\nmethod returning a promise, a static coroutine, a static method returning a\nfuture, a module function returning a tagged tuple. One intent, four renderings.\n\nReviewing a generated surface, ask what a native library in that language would\nlook like, not whether the shape matches the Rust. A `.d.ts` that reads like\nRust with braces is a defect, and so is a `.pyi` that reads like TypeScript.\n\n## Intent table\n\n| Intent | Rust | TypeScript | Python | Kotlin | Elixir |\n|---|---|---|---|---|---|\n| construct, async | `#[unibind(associated)]` `async fn` returning `Self` | `static oci(): Promise\u003CMachine>` | `@staticmethod async def oci() -> Machine` | `suspend fun` in a `companion object` | `Machine.oci(...) -> {:ok, machine}` |\n| release at scope end | `object(resource)` + `close` | `Symbol.asyncDispose`, so `await using` | `__aenter__`\u002F`__aexit__`, so `async with` | `AutoCloseable`, so `use { }` | nothing; the BEAM drops the `ResourceArc`, or take a function |\n| closed variant set | `#[unibind::enumeration]` `enum Status { Running, .. }` | `export type Status = \"running\" \\| \"stopped\"` | `enum.StrEnum` | `enum class` | atoms |\n| variants with data | `enum Frame { Phase{..}, Done{..} }` | discriminated union, exhaustive `switch` | frozen dataclasses under a `Literal` tag, `match` | sealed interface over data classes, exhaustive `when` | tagged tuples, `case` |\n| identity | `MachineId(Uuid)` | branded string | `NewType` | `@JvmInline value class` | opaque type |\n| optionality | `Option\u003CT>` | `T \\| null` | `T \\| None` | `T?`, checked by the compiler | `nil` |\n| sequence | `UniStream\u003CT>` | `AsyncIterable` | `__aiter__`\u002F`__anext__` | `Flow\u003CT>` | `Stream` |\n| failure | error enum | error subclasses | exception hierarchy | sealed exception hierarchy | `{:error, reason}` |\n| a verb on the type | `#[unibind(associated)]` returning anything else | `static list(): Promise\u003CMachine[]>` | `@staticmethod async def list()` | `companion object` | module function |\n\nOne flag covers both associated rows, and the return type decides the\nrendering rather than the author: napi needs `factory` to build an instance\nfrom an async static and plain `#[napi]` for everything else, so\n`Machine.oci` and `Machine.list` are written the same way and come out\ndifferent. Saying it twice is a way to say it inconsistently.\n\n### One wire spelling, four type names\n\nThe closed-variant row is the one intent where the languages must agree on a\n*value*, not only on a shape: the same string is what TypeScript compares, what\na Python `StrEnum` member holds, and what the service already puts in its JSON.\nSo the rule splits in two.\n\n**The wire spelling is decided once, at lowering, and is the same in every\nlanguage.** It defaults to `snake_case` of the Rust variant, and\n`#[unibind::enumeration(rename_all = \"...\")]` picks another convention for the\nwhole enum. The conventions and their output are serde's, byte for byte, so a\nbinding cannot disagree with the JSON `#[serde(rename_all = ...)]` produces on\nthe same enum. `MachineProgress.kind` is `PascalCase` on the wire where every\nother closed set in the ix surface is `snake_case`, and that is exactly one\nword (`rename_all = \"PascalCase\"`) rather than a guess in each backend.\n\n**The type name, and any member identifier, is idiomatic per language.** The\ntype keeps the Rust `PascalCase` name unless `ts(name = ...)` \u002F `py(name = ...)`\nrenames it, like every other declared type. A member identifier only exists\nwhere the language has one: Python spells members `SCREAMING_SNAKE_CASE`\n(`MachineStatus.HARD_FAILURE == \"hard_failure\"`), and a TypeScript union has no\nidentifier at all, which is why per-variant renames are Python's business and\nthe ts backend ignores them.\n\nTypeScript gets a union of string literals, never a TS `enum`: what crosses is\na plain string, a union erases at compile time where an `enum` needs a runtime\nobject, and `JSON.parse` output is assignable to a union and not to an `enum`.\nPython gets `enum.StrEnum` (3.11+) because its member *is* a `str`, so\n`isinstance`, `is`, and a caller's pre-existing `status == \"running\"` are all\ntrue of one value; the extension builds the class at `#[pymodule]` init from\nthe same IR the `.pyi` declares, so there is no second source for the members.\n\nVariants that carry data are a different intent (the row below) and lowering\nstill refuses them, naming the enum and the variant.\n\nKotlin's async row is not just `suspend fun`. Structured concurrency is the\ncontract: a cancelled coroutine must abort the Rust future rather than\nleaving it running, so a suspending binding is written with\n`suspendCancellableCoroutine` plus `invokeOnCancellation`, which is the\nKotlin end of the same abort path the TypeScript backend drives from an\n`AbortSignal`. Streams are `Flow`, which is cold, cancellable and\nbackpressured by construction, so it carries the same contract without a\nsecond mechanism. Scope-bound release is `use { }` on `AutoCloseable`, the\n`with` of that language. Get those three right and a generated Kotlin SDK\ncomposes with `coroutineScope` the way a hand-written one would; get them\nwrong and every caller leaks a Rust task on the first cancellation.\n\nThe JVM column says Kotlin, not Java, and that is a decision rather than a\npreference. Java has no answer for the async row at all, which is why the\nbackend's own rejection message tells the caller to block on a runtime and\nmove the call to a virtual thread. Kotlin answers every row natively. The\nevidence that settled it: the only consumer of the JVM backend in either\nrepo is `index\u002Fpackages\u002Fminecraft\u002Fprobe-kt`, which is Kotlin, and whose\nheader describes what it consumes as \"the unibind-rendered **Java** class\".\nWe generated Java for a Kotlin caller. `index\u002Flib\u002Flanguages\u002Fkotlin.nix`\nalready builds that probe with `-Werror`, so the toolchain is in place, and\nthe backend is the least-built of the four, so re-basing it costs less now\nthan it ever will again.\n\nElixir keeps the table honest. It has no classes to hang a static method on and\nno scope-bound cleanup at all, so any IR concept that survives contact with\nElixir is intent rather than syntax. When a new concept has no Elixir answer,\nthat is a signal the concept is a Node or Python fact wearing a general name.\n\n## Types are the product\n\nA generated type that says `string` where the value is one of ten known words\nhas moved the specification into a doc comment, where no compiler reads it. Two\nrules follow.\n\n**A closed set is an enum, never a string.** `status`, `kind`, `phase`, `level`\nand every other field whose doc comment lists its legal values belongs in a Rust\nenum, so each backend can render its own closed type.\n\n**Variants that carry different data are one sum type, never one struct with\noptional fields.** The anti-pattern in our own surface today is\n`SwitchProgress`: a `kind: String` beside `phase`, `stdout`, `system` and\n`error`, each set on a different frame, every one optional because none of them\nis always there. The caller reconstructs by hand (`if (frame.finished &&\nframe.system)`) what a tagged union would have decided at compile time. It is a\nRust enum flattened into a struct because the IR had nowhere to put it.\n\n## State of the backends\n\nDo not promise a surface a backend cannot render. As of 2026-08-04:\n\n| | TypeScript | Python | JVM | Elixir |\n|---|---|---|---|---|\n| objects | yes | yes | **rejected outright** (`backend-jvm\u002Fsrc\u002Fmodule.rs`), no handle registry | yes, as `ResourceArc` handles |\n| async | yes | yes | **rejected outright** (`backend-jvm\u002Fsrc\u002Ffunction.rs`) | free functions only; object members rejected (`backend-ex\u002Fsrc\u002Fobject.rs`) |\n| associated functions | yes; `#[napi(factory)]` when it returns the object, plain static otherwise | yes, `#[staticmethod]` | no | no |\n| resource close | `close()` + leak warning | `close` + `__aenter__`\u002F`__aexit__` + `ResourceWarning` | none | flag ignored; the BEAM drop runs `Drop` |\n| scope-bound release | `[Symbol.asyncDispose]` in the generated JS wrapper, so `await using` works | `async with` | none | n\u002Fa |\n| unit enums | yes; union of string literals, plus `z.enum` | yes; `enum.StrEnum` | **rejected** (`backend-jvm\u002Fsrc\u002Fmodule.rs`); owes a Kotlin `enum class` | **rejected** (`backend-ex\u002Fsrc\u002Fmodule.rs`); owes an atom per variant |\n| data enums | **rejected by lowering**, naming the variant | same | same | same |\n| runtime validation | Zod schemas, `z.infer` types | **none**; Pydantic models are the gap | no | no |\n| error enums | yes | yes | yes | yes |\n\nTwo notes on that table. napi-rs itself cannot codegen `Symbol.asyncDispose`\nand has no attribute for it, but unibind emits its own JS wrapper class over\nthe napi addon, and that is where dispose is written, so `await using` works\ntoday. And the Zod row is the model for the Python gap: TypeScript consumers\nget runtime validation generated from the same IR that types them, Python\nconsumers get none.\n\nSo the shipped ix SDKs are TypeScript and Python. The JVM and Elixir backends\nserve other unibind consumers, and their gaps are stated in their own rejection\nmessages, which are worth reading before designing around them.\n\n## Examples are copied, so they are house style\n\nAn SDK example is read as a template, not as a demo, so anything hand-rolled\nin one becomes a pattern in somebody's codebase. Argument parsing is where\nthis shows up first: reach for the language's real parser, never index into\nthe raw argv.\n\n| | parser |\n|---|---|\n| TypeScript | `parseArgs` from `node:util`, stable since Node 20, so no dependency |\n| Python | `argparse`, as `packages\u002Fminecraft\u002Fprobe\u002Fmc_probe.py` already does |\n| Rust | `clap` |\n| Kotlin | `kotlinx-cli`, or `clikt` where subcommands earn it |\n\n`process.argv[2]` and `sys.argv[1]` accept anything, report nothing, and\nteach the reader to do the same. The same rule covers the rest of an\nexample's surface: use the standard library's path, time and JSON handling\nrather than string manipulation, because the example is the documentation\nthat gets executed.\n\n## A doc link resolves, or the build fails\n\nDoc comments reach four published surfaces, so a rustdoc link in one is a\nclaim about the *generated* API, not about Rust. unibind resolves every\nintra-doc link against the interface and renders it in each language's own\nspelling:\n\n| written | TypeScript | Python |\n|---|---|---|\n| ``[`Machine`]`` | `{@link Machine}` | `` `Machine` `` |\n| ``[`Machine::forward_port`]`` | `{@link Machine.forwardPort}` | `` `Machine.forward_port` `` |\n| ``[`MachineInfo::failure_reason`]`` | `{@link MachineInfo.failureReason}` | `` `MachineInfo.failure_reason` `` |\n| ``[`SnapshotStatus::Ready`]`` | `` `\"ready\"` `` | `` `SnapshotStatus.READY` `` |\n| ``[`IxError::NotFound`]`` | `{@link NotFound}` | `` `NotFound` `` |\n| ``[`Self::close`]`` | resolved against the enclosing type | same |\n\nTypeScript gets TSDoc, which editors resolve; Python gets a code span,\nbecause a `.pyi` has no link syntax a reader's tooling follows and Sphinx\nroles would be a second vocabulary in a file nobody runs Sphinx over. An\nenumeration variant is the one target with no identifier in TypeScript -- a\nunion member is a string -- so it renders the value a caller actually types.\nElixir and the JVM render code spans too, and have no conformance coverage\nfor links yet.\n\n**A link that names nothing fails generation**, naming the doc site and the\ndead target, the way rustdoc's `broken_intra_doc_links` does at `deny`. Every\ndead link is reported in one build, because a rename usually leaves several.\nThat gate is the point: a denylist of one renamed noun (which is what\n`artifact-sdk-vocabulary` was) cannot catch a link to a method that never\nexisted, and 214 dead links shipped in each published file before it existed.\n\nThree spellings and what they do:\n\n- ``[`Type::member`]`` is the form to write.\n- `[the docs](Type::member)` resolves the same way, and **the link text is\n  dropped** -- the target's spelling replaces the whole link, so write the\n  sentence around the reference rather than through it.\n- ``[`Type::member`][label]``, the reference form, is **refused**: its target\n  lives in a link definition, and nothing writes those into a `.d.ts` or a\n  `.pyi`, so it would ship as dead text with no error.\n\nTwo things that are deliberately not links: a Rust-side item the SDK reader\ncannot see (write `` `ix_sdk::SdkError` `` as a plain code span; brackets\nwould claim it is part of the surface), and a bare `[1]` in prose. A\nconstructor link renders as its type (``[`Session::new`]`` becomes `{@link\nSession}`), because no target language names a constructor -- so phrase the\nsentence for that rather than writing \"as [`Self::new`] received it\".\n\nRecords are the one doc site where the runtime text and the stub could\ndisagree, because a record's `#[pyclass]` lands on the user's own struct and\npyo3 reads its `\u002F\u002F\u002F` text. The macro writes the resolved lines back over\nthose attributes, so `help(Point)` and the `.pyi` say the same thing.\n\n## One surface, several files\n\n`#[unibind::export]` lowers one module, and lowering has to see all of it at\nonce: a type reference in a signature is classified against every declaration\nin the export, so no per-file pass could resolve `MachineInfo` without the\nfile that declares it. The export therefore names its other files:\n\n```rust\n#[unibind::export(parts = [\"src\u002Fsdk\u002Fmachines.rs\", \"src\u002Fsdk\u002Fsnapshots.rs\"])]\nmod _ix_sdk {}\n```\n\nEach listed file is a list of items -- the same items that would have been\nwritten inline, at the file's own indentation -- read and appended to the\nmodule before lowering. **Declaration order is the module's own items\nfollowed by the parts in listed order**, which matters because the generated\nlayout mirrors it: the list is the crate author's statement of that order,\nnot filesystem order and not the order macros expand in.\n\nThree compile errors keep the list honest:\n\n- a part listed twice, naming it;\n- a listed path that does not exist, naming it;\n- **a `.rs` file that sits with the parts but is not listed**, naming it.\n  Adding a file and forgetting to register it is the failure this catches; it\n  would otherwise be silently absent from the SDK.\n\nSo keep parts in a directory of their own, and put nothing else there.\n\nThe cost, stated plainly: rustc does not read the part files, the macro does,\nand stable Rust gives a proc macro no way to manufacture a span into a file\nit read. A type error inside a part is reported against the\n`#[unibind::export]` attribute; the offending code is still printed, but the\nfile and line are not the part's. unibind's own diagnostics name the item and\nthe part path instead.\n\n**Add to the file that owns the namespace.** The old rule in\n`crates\u002Fix\u002Fsdk-bind` was to append a new `impl` block at the end of the one\nfile rather than edit the blocks above, because a module boundary was not\navailable and several agents write here at once; that produced six `impl\nMachine` blocks spread over 5,000 lines. The file boundary does that job now:\na machines verb goes in `machines.rs`, and `Machine`'s verbs all live in\n`machine.rs`. Within a file, appending to the existing `impl` block is fine.\n\nReordering items across parts is not free. Records, enumerations, errors and\nobjects each keep their declaration order in the IR, and each object's\nmethods keep the order of the `impl` blocks that contribute them, so moving\none of those changes two published files while changing nothing. Private\nitems carry no IR position and move freely.\n\n## Adding an intent\n\nThe IR's function kind lives in lowering, not in the IR data: `Kind` in\n`core\u002Fsrc\u002Flower\u002Ffunc.rs` is `Free | Method | Constructor`, and an object carries\n`constructor: Option\u003CFunction>` beside `methods: Vec\u003CFunction>`, so kind is\npositional. A new intent is therefore a new arm there plus a new field on\n`ir::Object`, and then one rendering decision per backend:\n\n1. `core\u002Fsrc\u002Flower\u002Ffunc.rs`, `core\u002Fsrc\u002Flower\u002Fobject.rs`: accept the shape, and\n   say why in the rejection message for the shapes still refused.\n2. `core\u002Fsrc\u002Fir\u002Fdata.rs`: carry it.\n3. Each backend: render the local idiom, or refuse with a message naming the\n   idiom it would have rendered. A backend that cannot do it yet refuses\n   loudly; it never falls back to a shape from another language.\n4. Each conformance suite (`conformance\u002F`, `conformance-ts\u002F`, `conformance-jvm\u002F`,\n   `conformance-ex\u002F`): the fixture Rust surface plus assertions in the target\n   language. A feature with no conformance test in a language is not supported\n   in that language, whatever the renderer does. A lowering feature that is\n   not language-specific still needs one suite exercising it: `conformance-ex`\n   is split over `src\u002Fsurface\u002F*.rs`, which is what keeps `parts` covered.\n5. Break it and watch it fail. A renderer's snapshot test passes just as well\n   against the wrong output.\n\nAnything that has to be hand-written on top of a generated surface is a bug\nreport against unibind, not a layer to grow. `packages\u002Fsdk\u002Fsrc\u002Frepl.ts` is the\none sanctioned exception, and it earns it by being protocol logic rather than a\nsecond spelling of a generated verb.\n",{"name":5,"description":7},"main","bed3e79e169c9952618f13b255bbe21164bd8bc1","skills\u002Funibind","https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e","https:\u002F\u002Fgithub.com\u002Fharivansh-afk","hari.cafe","2026-08-05 23:54:30",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add harivansh-afk\u002Floom-index-e2e --skill unibind",{"tool":37,"command":38},"bunx","bunx skills add harivansh-afk\u002Floom-index-e2e --skill unibind",{"tool":40,"command":41},"pnpm","pnpm dlx skills add harivansh-afk\u002Floom-index-e2e --skill unibind","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e\u002Fblob\u002Fmain\u002Fskills\u002Funibind\u002FSKILL.md",true,[],[46,53,60,67,74,80],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":19},"01M7A62MBAXZSSHSTKTJF9M9T0","pdf-processing","Extract text and tables from PDF files","https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e\u002Fblob\u002Fmain\u002Fviews\u002Fhome-manager\u002Ftests\u002Fmodules\u002Fprograms\u002Fopencode\u002Fskills-bulk\u002Fpdf-processing\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M7A62K1VTVFVSPV9V49PKK4N","git-release","Create consistent releases and changelogs","https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e\u002Fblob\u002Fmain\u002Fviews\u002Fhome-manager\u002Ftests\u002Fmodules\u002Fprograms\u002Fopencode\u002Fskills-bulk\u002Fgit-release\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7A62HPD2TYCNA8MSV4PRGRP","data-analysis","Help analyze datasets and results","https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e\u002Fblob\u002Fmain\u002Fviews\u002Fhome-manager\u002Ftests\u002Fmodules\u002Fprograms\u002Fopencode\u002Fskill-dir\u002Fdata-analysis\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7A62G35PP698FP9TEZWYZ3V","release-notes","Draft release notes from commits and merged pull requests.","https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e\u002Fblob\u002Fmain\u002Fviews\u002Fhome-manager\u002Ftests\u002Fmodules\u002Fprograms\u002Fgithub-copilot-cli\u002Fskills\u002Frelease-notes\u002FSKILL.md",[],[],{"skillNo":75,"name":62,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7A62EJX21A1E72WR5CX6W3M","Summarize structured outputs and highlight regressions.","https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e\u002Fblob\u002Fmain\u002Fviews\u002Fhome-manager\u002Ftests\u002Fmodules\u002Fprograms\u002Fgithub-copilot-cli\u002Fskills\u002Fdata-analysis\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7A62DC2X7X7AYFPF1DG2NBC","skill-one","Example skill for tests.","https:\u002F\u002Fgithub.com\u002Fharivansh-afk\u002Floom-index-e2e\u002Fblob\u002Fmain\u002Fviews\u002Fhome-manager\u002Ftests\u002Fmodules\u002Fprograms\u002Fcodex\u002Fskills-dir\u002Fskill-one\u002FSKILL.md",[],[]]