{"_id":"@novox/mesh-sdk","name":"@novox/mesh-sdk","description":"The stable spine a Novox Mesh module's own code builds against.","dist-tags":{"latest":"0.1.18"},"versions":{"0.1.18":{"_id":"@novox/mesh-sdk@0.1.18","name":"@novox/mesh-sdk","version":"0.1.18","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provider-loop` — the reconcile harness every provider on the grant files shares\nCalled `provisioner` until design 57 (novox/hq issue 678); that word is mesh-provisioner's now. The old path and\nnames (`/provisioner`, `runProvisioner`, `provisionerTools`) stay aliases until the providers importing them move to\nthe Go helper that answers consumers over the bus (`go/provider`, design 57 B2 and B3) and this loop retires with the\ngrant files. Its events and tools keep their names (`provisioner.failing`, `provisioner_retirement`, …): the\ncontroller and the operator read them.\n\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE\nbecomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that\nread the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file\nstarts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;\n`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without\n`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the\nharness marks it \"retired, access kept, needs deletion\", says so loudly and announces it. **`remove` is\nnever called to retire**; it is the delete of an adapter without `delete`, reached only through a\nperson's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more\nthan one is held, is not retired without a person: the provider waits for\n`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`\n(`waiting`). Asked for again, a retired consumer is created — re-enabled\n— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,\n`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`\nbuilds them otherwise. Additions and changes are never delayed.\n\n**A provider that keeps failing a consumer says so on the bus** (novox/hq ADR 0224). A consumer whose\ncreate, check (`holds`) or secret has failed for five minutes without one success between\n(`failingAfterMs`) is announced `provisioner.failing` — the consumer, its machine, the class of error\n(`credentials-rejected`, `unreachable`, `secret-unreadable`, `refused`; an adapter's `classify` is\nbelieved over the words), the error with the password removed, since when and how many attempts — and\nagain every fifteen minutes while it lasts. The first success after it is `provisioner.recovered`, as is\na consumer no longer asked for or retired, and the first success for each consumer since the process\nstarted. Every event goes through the `announce` option, which defaults to the SDK's `emit`: a provider\nsays them without asking, and a failed publish is said in its journal, never failing the act.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n#### Taking an event — the one rule\n\nA module's handler (`on(pattern, handler)` here, `stdio.Subscribe` in Go, the same in every language)\n**takes an event by returning, and asks for it again by throwing** (Go: returning an error). Nothing\nelse counts: what a handler returns is not read.\n\nOn the wire, the runtime hands the bundle `mesh/event` with the envelope and acknowledges the event on\nthe bus when the answer is **anything but a JSON-RPC error** — `{}` (what the SDKs send), `null`, or no\n`result` at all. An `error` answer, no answer within the runtime's event timeout (two minutes), or the\nbundle exiting leaves it unacknowledged: it is offered again after five seconds, up to the module\nconsumer's maximum deliveries, after which the bus gives it up and the controller raises a condition\n(`max-deliveries`). The runtime's line for an event not taken quotes a handler's error as the\nhandler's own words, so it is never mistaken for the runtime's.\n\nSo, for a handler:\n\n- **Throw only when the work was not done** — the service refused, was unreachable, the store failed.\n  Never for something that went right but answered oddly: an API that answers an empty body is a\n  success, and reading it as JSON is a throw that has every event offered five times, its work done\n  five times, and a false alarm raised (novox/hq issue 276).\n- **Delivery is at-least-once**, so the work must be safe to do twice, or the handler skips an event\n  whose `x-event-id` (`event.id`) it already did — remembering it only once the work succeeded, so one\n  that failed is done when it is offered again.\n- An event no handler matches is answered at once and taken.\n- A subscribe the runtime refused leaves no handler behind, so asking again until it is taken hands\n  each event to the handler once.\n\nChecked by the SDKs' stdio tests (TypeScript `test/stdio.test.ts`, Go `go/stdio_test.go`) and the\nruntime's (`node-tools/internal/launch`, mesh-tools).\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `seats` and `asks` — asking a person, answering on a channel (Go)\nA seat may name its caller or its kind (novox/hq ADR 0259): `stdio.SeatPublish` submits an accept or says\nan event under the module's own name or kind, `stdio.SeatTake` takes a held seat's work, `stdio.SeatProve`\nand `stdio.SeatAnswer` carry a proof (a code typed by a person, by request and reply, never kept),\n`stdio.SeatRecord` reads a record kept for the module, and `State(...).Create` and `.Update` write by\ncompare-and-set. The runtime does each only as far as the module's membership lists. `go/asks` is the\ncontract on top: the `Ask` an asker publishes and the checks it is held to (its `Whole` is what a channel that proves\nwho answers shows in place of its `Explanation`, and its `Details` what the Details answer shows, hq issue 383), the `Warrant` it acts on\n(`For`, `Says`), and the `Message`, `Choice`, `LinkAsked` and `Code` a channel takes and says, with the\nsubjects each travels on.\n`go/asker` is an asking module's client (ADR 0259 §10): `Ask` keeps an ask in the module's own state and then\npublishes it under the module's name; `Cancel`; `Where` reads its state from the router's record; `Listen` and\n`Take` hand the module each warrant once — marked acted on by compare-and-set before the module acts, and only\nfor an ask it made, an option it offered, at that option's level, before it expired. A lost compare-and-set is\n`stdio.ErrChanged`, told by the runtime's error code.\n`State(...).Increment(key, attempts)` is a counter on top of the two (for numbers handed out once, such as an\nissue's): it reads the key, writes one more at the revision read, and on a lost write reads and tries again, at\nmost `attempts` times; past that it is `stdio.ErrChanged` and nothing was counted.\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's loop:\n\n```ts\nimport { runProviderLoop, Grant, Credential } from \"@novox/mesh-sdk/provider-loop\";\n\nrunProviderLoop(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-mnNB4uObLlYdaxHCp+A1VvI2LMVR1kyNo6FYEYKX39EjU4t/Oq3Cb90SOcFyaaPH3P4tfNPdTiMKms1SXT+t0Q==","shasum":"a949d3d6d13aec2612423082e05439b089b0fb78","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.18/mesh-sdk-0.1.18.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]},"0.1.10":{"_id":"@novox/mesh-sdk@0.1.10","name":"@novox/mesh-sdk","version":"0.1.10","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provisioner` — the reconcile harness every provider shares\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's provisioner:\n\n```ts\nimport { runProvisioner, Grant, Credential } from \"@novox/mesh-sdk/provisioner\";\n\nrunProvisioner(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-rpF34kPkRSLRhU4yLnC/xFXhVm8bElhuqSBpTLubsaN27JOHv/8XHPaRvJCS7gSF2IRbla2Lg82zDZi2uOAAFA==","shasum":"8d4989252adc896375c2b8bdaebff8141528a740","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.10/mesh-sdk-0.1.10.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]},"0.1.11":{"_id":"@novox/mesh-sdk@0.1.11","name":"@novox/mesh-sdk","version":"0.1.11","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provisioner` — the reconcile harness every provider shares\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's provisioner:\n\n```ts\nimport { runProvisioner, Grant, Credential } from \"@novox/mesh-sdk/provisioner\";\n\nrunProvisioner(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-k6+lwAfaLipV7Tk7c2pkBmqVmCS5iB63bAULNJEZ8Tttu37It+o2bXGgM6BKnZf5r060GcAr3TEEUhLkvW3j4Q==","shasum":"1ff38d37e71d6d4863f0fd766ee145bf672430d9","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.11/mesh-sdk-0.1.11.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]},"0.1.12":{"_id":"@novox/mesh-sdk@0.1.12","name":"@novox/mesh-sdk","version":"0.1.12","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provisioner` — the reconcile harness every provider shares\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE\nbecomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that\nread the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file\nstarts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;\n`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without\n`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the\nharness marks it \"retired, access kept, needs deletion\", says so loudly and announces it. **`remove` is\nnever called to retire**; it is the delete of an adapter without `delete`, reached only through a\nperson's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more\nthan one is held, is not retired without a person: the provider waits for\n`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`\n(`waiting`) through the `announce` option. Asked for again, a retired consumer is created — re-enabled\n— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,\n`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`\nbuilds them otherwise. Additions and changes are never delayed.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's provisioner:\n\n```ts\nimport { runProvisioner, Grant, Credential } from \"@novox/mesh-sdk/provisioner\";\n\nrunProvisioner(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-uBu9lxwLxQeVp1nPYj0RCFw3llIN0ZvkunBLYN/8oSO+JcKXHr1ksRgmM2e0nMAgmbuMsloKT7MfBoH5RLsDsg==","shasum":"b14abacf9a539f2bc84e6b9eb32c1c35fbc72dd4","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.12/mesh-sdk-0.1.12.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]},"0.1.14":{"_id":"@novox/mesh-sdk@0.1.14","name":"@novox/mesh-sdk","version":"0.1.14","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provisioner` — the reconcile harness every provider shares\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE\nbecomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that\nread the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file\nstarts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;\n`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without\n`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the\nharness marks it \"retired, access kept, needs deletion\", says so loudly and announces it. **`remove` is\nnever called to retire**; it is the delete of an adapter without `delete`, reached only through a\nperson's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more\nthan one is held, is not retired without a person: the provider waits for\n`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`\n(`waiting`). Asked for again, a retired consumer is created — re-enabled\n— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,\n`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`\nbuilds them otherwise. Additions and changes are never delayed.\n\n**A provider that keeps failing a consumer says so on the bus** (novox/hq ADR 0224). A consumer whose\ncreate, check (`holds`) or secret has failed for five minutes without one success between\n(`failingAfterMs`) is announced `provisioner.failing` — the consumer, its machine, the class of error\n(`credentials-rejected`, `unreachable`, `secret-unreadable`, `refused`; an adapter's `classify` is\nbelieved over the words), the error with the password removed, since when and how many attempts — and\nagain every fifteen minutes while it lasts. The first success after it is `provisioner.recovered`, as is\na consumer no longer asked for or retired, and the first success for each consumer since the process\nstarted. Every event goes through the `announce` option, which defaults to the SDK's `emit`: a provider\nsays them without asking, and a failed publish is said in its journal, never failing the act.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n#### Taking an event — the one rule\n\nA module's handler (`on(pattern, handler)` here, `stdio.Subscribe` in Go, the same in every language)\n**takes an event by returning, and asks for it again by throwing** (Go: returning an error). Nothing\nelse counts: what a handler returns is not read.\n\nOn the wire, the runtime hands the bundle `mesh/event` with the envelope and acknowledges the event on\nthe bus when the answer is **anything but a JSON-RPC error** — `{}` (what the SDKs send), `null`, or no\n`result` at all. An `error` answer, no answer within the runtime's event timeout (two minutes), or the\nbundle exiting leaves it unacknowledged: it is offered again after five seconds, up to the module\nconsumer's maximum deliveries, after which the bus gives it up and the controller raises a condition\n(`max-deliveries`). The runtime's line for an event not taken quotes a handler's error as the\nhandler's own words, so it is never mistaken for the runtime's.\n\nSo, for a handler:\n\n- **Throw only when the work was not done** — the service refused, was unreachable, the store failed.\n  Never for something that went right but answered oddly: an API that answers an empty body is a\n  success, and reading it as JSON is a throw that has every event offered five times, its work done\n  five times, and a false alarm raised (novox/hq issue 276).\n- **Delivery is at-least-once**, so the work must be safe to do twice, or the handler skips an event\n  whose `x-event-id` (`event.id`) it already did — remembering it only once the work succeeded, so one\n  that failed is done when it is offered again.\n- An event no handler matches is answered at once and taken.\n- A subscribe the runtime refused leaves no handler behind, so asking again until it is taken hands\n  each event to the handler once.\n\nChecked by the SDKs' stdio tests (TypeScript `test/stdio.test.ts`, Go `go/stdio_test.go`) and the\nruntime's (`node-tools/internal/launch`, mesh-tools).\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `seats` and `asks` — asking a person, answering on a channel (Go)\nA seat may name its caller or its kind (novox/hq ADR 0259): `stdio.SeatPublish` submits an accept or says\nan event under the module's own name or kind, `stdio.SeatTake` takes a held seat's work, `stdio.SeatProve`\nand `stdio.SeatAnswer` carry a proof (a code typed by a person, by request and reply, never kept),\n`stdio.SeatRecord` reads a record kept for the module, and `State(...).Create` and `.Update` write by\ncompare-and-set. The runtime does each only as far as the module's membership lists. `go/asks` is the\ncontract on top: the `Ask` an asker publishes and the checks it is held to (its `Whole` is what a channel that proves\nwho answers shows in place of its `Explanation`, and its `Details` what the Details answer shows, hq issue 383), the `Warrant` it acts on\n(`For`, `Says`), and the `Message`, `Choice`, `LinkAsked` and `Code` a channel takes and says, with the\nsubjects each travels on.\n`go/asker` is an asking module's client (ADR 0259 §10): `Ask` keeps an ask in the module's own state and then\npublishes it under the module's name; `Cancel`; `Where` reads its state from the router's record; `Listen` and\n`Take` hand the module each warrant once — marked acted on by compare-and-set before the module acts, and only\nfor an ask it made, an option it offered, at that option's level, before it expired. A lost compare-and-set is\n`stdio.ErrChanged`, told by the runtime's error code.\n`State(...).Increment(key, attempts)` is a counter on top of the two (for numbers handed out once, such as an\nissue's): it reads the key, writes one more at the revision read, and on a lost write reads and tries again, at\nmost `attempts` times; past that it is `stdio.ErrChanged` and nothing was counted.\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's provisioner:\n\n```ts\nimport { runProvisioner, Grant, Credential } from \"@novox/mesh-sdk/provisioner\";\n\nrunProvisioner(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-ICdIfVicQQXSw6fkLiwzoRx3weiWh0jsIEYG/m98CKgFIlziZzb7V+ZmT/TvPO9bTDFDtfqDLoFu+OXY5+ryQw==","shasum":"4da1b2b274dc64763a29dfb3a54e4bb7129ffd84","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.14/mesh-sdk-0.1.14.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]},"0.1.16":{"_id":"@novox/mesh-sdk@0.1.16","name":"@novox/mesh-sdk","version":"0.1.16","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provider-loop` — the reconcile harness every provider on the grant files shares\nCalled `provisioner` until design 57 (novox/hq issue 678); that word is mesh-provisioner's now. The old path and\nnames (`/provisioner`, `runProvisioner`, `provisionerTools`) stay aliases until the providers importing them move to\nthe Go helper that answers consumers over the bus (`go/provider`, design 57 B2 and B3) and this loop retires with the\ngrant files. Its events and tools keep their names (`provisioner.failing`, `provisioner_retirement`, …): the\ncontroller and the operator read them.\n\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE\nbecomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that\nread the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file\nstarts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;\n`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without\n`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the\nharness marks it \"retired, access kept, needs deletion\", says so loudly and announces it. **`remove` is\nnever called to retire**; it is the delete of an adapter without `delete`, reached only through a\nperson's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more\nthan one is held, is not retired without a person: the provider waits for\n`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`\n(`waiting`). Asked for again, a retired consumer is created — re-enabled\n— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,\n`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`\nbuilds them otherwise. Additions and changes are never delayed.\n\n**A provider that keeps failing a consumer says so on the bus** (novox/hq ADR 0224). A consumer whose\ncreate, check (`holds`) or secret has failed for five minutes without one success between\n(`failingAfterMs`) is announced `provisioner.failing` — the consumer, its machine, the class of error\n(`credentials-rejected`, `unreachable`, `secret-unreadable`, `refused`; an adapter's `classify` is\nbelieved over the words), the error with the password removed, since when and how many attempts — and\nagain every fifteen minutes while it lasts. The first success after it is `provisioner.recovered`, as is\na consumer no longer asked for or retired, and the first success for each consumer since the process\nstarted. Every event goes through the `announce` option, which defaults to the SDK's `emit`: a provider\nsays them without asking, and a failed publish is said in its journal, never failing the act.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n#### Taking an event — the one rule\n\nA module's handler (`on(pattern, handler)` here, `stdio.Subscribe` in Go, the same in every language)\n**takes an event by returning, and asks for it again by throwing** (Go: returning an error). Nothing\nelse counts: what a handler returns is not read.\n\nOn the wire, the runtime hands the bundle `mesh/event` with the envelope and acknowledges the event on\nthe bus when the answer is **anything but a JSON-RPC error** — `{}` (what the SDKs send), `null`, or no\n`result` at all. An `error` answer, no answer within the runtime's event timeout (two minutes), or the\nbundle exiting leaves it unacknowledged: it is offered again after five seconds, up to the module\nconsumer's maximum deliveries, after which the bus gives it up and the controller raises a condition\n(`max-deliveries`). The runtime's line for an event not taken quotes a handler's error as the\nhandler's own words, so it is never mistaken for the runtime's.\n\nSo, for a handler:\n\n- **Throw only when the work was not done** — the service refused, was unreachable, the store failed.\n  Never for something that went right but answered oddly: an API that answers an empty body is a\n  success, and reading it as JSON is a throw that has every event offered five times, its work done\n  five times, and a false alarm raised (novox/hq issue 276).\n- **Delivery is at-least-once**, so the work must be safe to do twice, or the handler skips an event\n  whose `x-event-id` (`event.id`) it already did — remembering it only once the work succeeded, so one\n  that failed is done when it is offered again.\n- An event no handler matches is answered at once and taken.\n- A subscribe the runtime refused leaves no handler behind, so asking again until it is taken hands\n  each event to the handler once.\n\nChecked by the SDKs' stdio tests (TypeScript `test/stdio.test.ts`, Go `go/stdio_test.go`) and the\nruntime's (`node-tools/internal/launch`, mesh-tools).\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `seats` and `asks` — asking a person, answering on a channel (Go)\nA seat may name its caller or its kind (novox/hq ADR 0259): `stdio.SeatPublish` submits an accept or says\nan event under the module's own name or kind, `stdio.SeatTake` takes a held seat's work, `stdio.SeatProve`\nand `stdio.SeatAnswer` carry a proof (a code typed by a person, by request and reply, never kept),\n`stdio.SeatRecord` reads a record kept for the module, and `State(...).Create` and `.Update` write by\ncompare-and-set. The runtime does each only as far as the module's membership lists. `go/asks` is the\ncontract on top: the `Ask` an asker publishes and the checks it is held to (its `Whole` is what a channel that proves\nwho answers shows in place of its `Explanation`, and its `Details` what the Details answer shows, hq issue 383), the `Warrant` it acts on\n(`For`, `Says`), and the `Message`, `Choice`, `LinkAsked` and `Code` a channel takes and says, with the\nsubjects each travels on.\n`go/asker` is an asking module's client (ADR 0259 §10): `Ask` keeps an ask in the module's own state and then\npublishes it under the module's name; `Cancel`; `Where` reads its state from the router's record; `Listen` and\n`Take` hand the module each warrant once — marked acted on by compare-and-set before the module acts, and only\nfor an ask it made, an option it offered, at that option's level, before it expired. A lost compare-and-set is\n`stdio.ErrChanged`, told by the runtime's error code.\n`State(...).Increment(key, attempts)` is a counter on top of the two (for numbers handed out once, such as an\nissue's): it reads the key, writes one more at the revision read, and on a lost write reads and tries again, at\nmost `attempts` times; past that it is `stdio.ErrChanged` and nothing was counted.\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's loop:\n\n```ts\nimport { runProviderLoop, Grant, Credential } from \"@novox/mesh-sdk/provider-loop\";\n\nrunProviderLoop(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-kMq9kW5MxKUchw8f/4DXd1cumVDma89xR5ZvXvOOSmCSwUNuApOc3k1kc5dT2HWYk1BiL2VoVSxv5DFRrtwCZw==","shasum":"56b59979832539ff1ec1d22bb3dd1dacaf24d5c7","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.16/mesh-sdk-0.1.16.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]},"0.1.13":{"_id":"@novox/mesh-sdk@0.1.13","name":"@novox/mesh-sdk","version":"0.1.13","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provisioner` — the reconcile harness every provider shares\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE\nbecomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that\nread the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file\nstarts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;\n`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without\n`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the\nharness marks it \"retired, access kept, needs deletion\", says so loudly and announces it. **`remove` is\nnever called to retire**; it is the delete of an adapter without `delete`, reached only through a\nperson's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more\nthan one is held, is not retired without a person: the provider waits for\n`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`\n(`waiting`) through the `announce` option. Asked for again, a retired consumer is created — re-enabled\n— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,\n`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`\nbuilds them otherwise. Additions and changes are never delayed.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n#### Taking an event — the one rule\n\nA module's handler (`on(pattern, handler)` here, `stdio.Subscribe` in Go, the same in every language)\n**takes an event by returning, and asks for it again by throwing** (Go: returning an error). Nothing\nelse counts: what a handler returns is not read.\n\nOn the wire, the runtime hands the bundle `mesh/event` with the envelope and acknowledges the event on\nthe bus when the answer is **anything but a JSON-RPC error** — `{}` (what the SDKs send), `null`, or no\n`result` at all. An `error` answer, no answer within the runtime's event timeout (two minutes), or the\nbundle exiting leaves it unacknowledged: it is offered again after five seconds, up to the module\nconsumer's maximum deliveries, after which the bus gives it up and the controller raises a condition\n(`max-deliveries`). The runtime's line for an event not taken quotes a handler's error as the\nhandler's own words, so it is never mistaken for the runtime's.\n\nSo, for a handler:\n\n- **Throw only when the work was not done** — the service refused, was unreachable, the store failed.\n  Never for something that went right but answered oddly: an API that answers an empty body is a\n  success, and reading it as JSON is a throw that has every event offered five times, its work done\n  five times, and a false alarm raised (novox/hq issue 276).\n- **Delivery is at-least-once**, so the work must be safe to do twice, or the handler skips an event\n  whose `x-event-id` (`event.id`) it already did — remembering it only once the work succeeded, so one\n  that failed is done when it is offered again.\n- An event no handler matches is answered at once and taken.\n- A subscribe the runtime refused leaves no handler behind, so asking again until it is taken hands\n  each event to the handler once.\n\nChecked by the SDKs' stdio tests (TypeScript `test/stdio.test.ts`, Go `go/stdio_test.go`) and the\nruntime's (`node-tools/internal/launch`, mesh-tools).\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's provisioner:\n\n```ts\nimport { runProvisioner, Grant, Credential } from \"@novox/mesh-sdk/provisioner\";\n\nrunProvisioner(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-yGDnU0G/7onkVnDKPFJXw30u+QL4FsFCBg/6a05SEfc1qnj2aOgINScnf9I6dRI8exG7wY+G/tSLwx4weaehvQ==","shasum":"219e39b2f47e3950e72ee30612ad5b2f24ada4f8","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.13/mesh-sdk-0.1.13.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]},"0.1.15":{"_id":"@novox/mesh-sdk@0.1.15","name":"@novox/mesh-sdk","version":"0.1.15","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provider-loop` — the reconcile harness every provider on the grant files shares\nCalled `provisioner` until design 57 (novox/hq issue 678); that word is mesh-provisioner's now. The old path and\nnames (`/provisioner`, `runProvisioner`, `provisionerTools`) stay aliases until the providers importing them move to\nthe Go helper that answers consumers over the bus (`go/provider`, design 57 B2 and B3) and this loop retires with the\ngrant files. Its events and tools keep their names (`provisioner.failing`, `provisioner_retirement`, …): the\ncontroller and the operator read them.\n\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE\nbecomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that\nread the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file\nstarts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;\n`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without\n`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the\nharness marks it \"retired, access kept, needs deletion\", says so loudly and announces it. **`remove` is\nnever called to retire**; it is the delete of an adapter without `delete`, reached only through a\nperson's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more\nthan one is held, is not retired without a person: the provider waits for\n`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`\n(`waiting`). Asked for again, a retired consumer is created — re-enabled\n— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,\n`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`\nbuilds them otherwise. Additions and changes are never delayed.\n\n**A provider that keeps failing a consumer says so on the bus** (novox/hq ADR 0224). A consumer whose\ncreate, check (`holds`) or secret has failed for five minutes without one success between\n(`failingAfterMs`) is announced `provisioner.failing` — the consumer, its machine, the class of error\n(`credentials-rejected`, `unreachable`, `secret-unreadable`, `refused`; an adapter's `classify` is\nbelieved over the words), the error with the password removed, since when and how many attempts — and\nagain every fifteen minutes while it lasts. The first success after it is `provisioner.recovered`, as is\na consumer no longer asked for or retired, and the first success for each consumer since the process\nstarted. Every event goes through the `announce` option, which defaults to the SDK's `emit`: a provider\nsays them without asking, and a failed publish is said in its journal, never failing the act.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n#### Taking an event — the one rule\n\nA module's handler (`on(pattern, handler)` here, `stdio.Subscribe` in Go, the same in every language)\n**takes an event by returning, and asks for it again by throwing** (Go: returning an error). Nothing\nelse counts: what a handler returns is not read.\n\nOn the wire, the runtime hands the bundle `mesh/event` with the envelope and acknowledges the event on\nthe bus when the answer is **anything but a JSON-RPC error** — `{}` (what the SDKs send), `null`, or no\n`result` at all. An `error` answer, no answer within the runtime's event timeout (two minutes), or the\nbundle exiting leaves it unacknowledged: it is offered again after five seconds, up to the module\nconsumer's maximum deliveries, after which the bus gives it up and the controller raises a condition\n(`max-deliveries`). The runtime's line for an event not taken quotes a handler's error as the\nhandler's own words, so it is never mistaken for the runtime's.\n\nSo, for a handler:\n\n- **Throw only when the work was not done** — the service refused, was unreachable, the store failed.\n  Never for something that went right but answered oddly: an API that answers an empty body is a\n  success, and reading it as JSON is a throw that has every event offered five times, its work done\n  five times, and a false alarm raised (novox/hq issue 276).\n- **Delivery is at-least-once**, so the work must be safe to do twice, or the handler skips an event\n  whose `x-event-id` (`event.id`) it already did — remembering it only once the work succeeded, so one\n  that failed is done when it is offered again.\n- An event no handler matches is answered at once and taken.\n- A subscribe the runtime refused leaves no handler behind, so asking again until it is taken hands\n  each event to the handler once.\n\nChecked by the SDKs' stdio tests (TypeScript `test/stdio.test.ts`, Go `go/stdio_test.go`) and the\nruntime's (`node-tools/internal/launch`, mesh-tools).\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `seats` and `asks` — asking a person, answering on a channel (Go)\nA seat may name its caller or its kind (novox/hq ADR 0259): `stdio.SeatPublish` submits an accept or says\nan event under the module's own name or kind, `stdio.SeatTake` takes a held seat's work, `stdio.SeatProve`\nand `stdio.SeatAnswer` carry a proof (a code typed by a person, by request and reply, never kept),\n`stdio.SeatRecord` reads a record kept for the module, and `State(...).Create` and `.Update` write by\ncompare-and-set. The runtime does each only as far as the module's membership lists. `go/asks` is the\ncontract on top: the `Ask` an asker publishes and the checks it is held to (its `Whole` is what a channel that proves\nwho answers shows in place of its `Explanation`, and its `Details` what the Details answer shows, hq issue 383), the `Warrant` it acts on\n(`For`, `Says`), and the `Message`, `Choice`, `LinkAsked` and `Code` a channel takes and says, with the\nsubjects each travels on.\n`go/asker` is an asking module's client (ADR 0259 §10): `Ask` keeps an ask in the module's own state and then\npublishes it under the module's name; `Cancel`; `Where` reads its state from the router's record; `Listen` and\n`Take` hand the module each warrant once — marked acted on by compare-and-set before the module acts, and only\nfor an ask it made, an option it offered, at that option's level, before it expired. A lost compare-and-set is\n`stdio.ErrChanged`, told by the runtime's error code.\n`State(...).Increment(key, attempts)` is a counter on top of the two (for numbers handed out once, such as an\nissue's): it reads the key, writes one more at the revision read, and on a lost write reads and tries again, at\nmost `attempts` times; past that it is `stdio.ErrChanged` and nothing was counted.\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's loop:\n\n```ts\nimport { runProviderLoop, Grant, Credential } from \"@novox/mesh-sdk/provider-loop\";\n\nrunProviderLoop(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-wuKFgguyDlWQbmIZfFf/Cw+YL5DG9+Tab7nkaVVAcKr9QhOmtUPMNZId3BAHOu8TW4XuoGeFQSe6tXKUAKKRiw==","shasum":"18a480ec4e8278b5313b87fea4d7ea8e6f0eabaf","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.15/mesh-sdk-0.1.15.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]},"0.1.17":{"_id":"@novox/mesh-sdk@0.1.17","name":"@novox/mesh-sdk","version":"0.1.17","description":"The stable spine a Novox Mesh module's own code builds against.","author":{"name":""},"repository":{"type":"","url":""},"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provider-loop` — the reconcile harness every provider on the grant files shares\nCalled `provisioner` until design 57 (novox/hq issue 678); that word is mesh-provisioner's now. The old path and\nnames (`/provisioner`, `runProvisioner`, `provisionerTools`) stay aliases until the providers importing them move to\nthe Go helper that answers consumers over the bus (`go/provider`, design 57 B2 and B3) and this loop retires with the\ngrant files. Its events and tools keep their names (`provisioner.failing`, `provisioner_retirement`, …): the\ncontroller and the operator read them.\n\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE\nbecomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that\nread the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file\nstarts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;\n`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without\n`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the\nharness marks it \"retired, access kept, needs deletion\", says so loudly and announces it. **`remove` is\nnever called to retire**; it is the delete of an adapter without `delete`, reached only through a\nperson's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more\nthan one is held, is not retired without a person: the provider waits for\n`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`\n(`waiting`). Asked for again, a retired consumer is created — re-enabled\n— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,\n`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`\nbuilds them otherwise. Additions and changes are never delayed.\n\n**A provider that keeps failing a consumer says so on the bus** (novox/hq ADR 0224). A consumer whose\ncreate, check (`holds`) or secret has failed for five minutes without one success between\n(`failingAfterMs`) is announced `provisioner.failing` — the consumer, its machine, the class of error\n(`credentials-rejected`, `unreachable`, `secret-unreadable`, `refused`; an adapter's `classify` is\nbelieved over the words), the error with the password removed, since when and how many attempts — and\nagain every fifteen minutes while it lasts. The first success after it is `provisioner.recovered`, as is\na consumer no longer asked for or retired, and the first success for each consumer since the process\nstarted. Every event goes through the `announce` option, which defaults to the SDK's `emit`: a provider\nsays them without asking, and a failed publish is said in its journal, never failing the act.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n#### Taking an event — the one rule\n\nA module's handler (`on(pattern, handler)` here, `stdio.Subscribe` in Go, the same in every language)\n**takes an event by returning, and asks for it again by throwing** (Go: returning an error). Nothing\nelse counts: what a handler returns is not read.\n\nOn the wire, the runtime hands the bundle `mesh/event` with the envelope and acknowledges the event on\nthe bus when the answer is **anything but a JSON-RPC error** — `{}` (what the SDKs send), `null`, or no\n`result` at all. An `error` answer, no answer within the runtime's event timeout (two minutes), or the\nbundle exiting leaves it unacknowledged: it is offered again after five seconds, up to the module\nconsumer's maximum deliveries, after which the bus gives it up and the controller raises a condition\n(`max-deliveries`). The runtime's line for an event not taken quotes a handler's error as the\nhandler's own words, so it is never mistaken for the runtime's.\n\nSo, for a handler:\n\n- **Throw only when the work was not done** — the service refused, was unreachable, the store failed.\n  Never for something that went right but answered oddly: an API that answers an empty body is a\n  success, and reading it as JSON is a throw that has every event offered five times, its work done\n  five times, and a false alarm raised (novox/hq issue 276).\n- **Delivery is at-least-once**, so the work must be safe to do twice, or the handler skips an event\n  whose `x-event-id` (`event.id`) it already did — remembering it only once the work succeeded, so one\n  that failed is done when it is offered again.\n- An event no handler matches is answered at once and taken.\n- A subscribe the runtime refused leaves no handler behind, so asking again until it is taken hands\n  each event to the handler once.\n\nChecked by the SDKs' stdio tests (TypeScript `test/stdio.test.ts`, Go `go/stdio_test.go`) and the\nruntime's (`node-tools/internal/launch`, mesh-tools).\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `seats` and `asks` — asking a person, answering on a channel (Go)\nA seat may name its caller or its kind (novox/hq ADR 0259): `stdio.SeatPublish` submits an accept or says\nan event under the module's own name or kind, `stdio.SeatTake` takes a held seat's work, `stdio.SeatProve`\nand `stdio.SeatAnswer` carry a proof (a code typed by a person, by request and reply, never kept),\n`stdio.SeatRecord` reads a record kept for the module, and `State(...).Create` and `.Update` write by\ncompare-and-set. The runtime does each only as far as the module's membership lists. `go/asks` is the\ncontract on top: the `Ask` an asker publishes and the checks it is held to (its `Whole` is what a channel that proves\nwho answers shows in place of its `Explanation`, and its `Details` what the Details answer shows, hq issue 383), the `Warrant` it acts on\n(`For`, `Says`), and the `Message`, `Choice`, `LinkAsked` and `Code` a channel takes and says, with the\nsubjects each travels on.\n`go/asker` is an asking module's client (ADR 0259 §10): `Ask` keeps an ask in the module's own state and then\npublishes it under the module's name; `Cancel`; `Where` reads its state from the router's record; `Listen` and\n`Take` hand the module each warrant once — marked acted on by compare-and-set before the module acts, and only\nfor an ask it made, an option it offered, at that option's level, before it expired. A lost compare-and-set is\n`stdio.ErrChanged`, told by the runtime's error code.\n`State(...).Increment(key, attempts)` is a counter on top of the two (for numbers handed out once, such as an\nissue's): it reads the key, writes one more at the revision read, and on a lost write reads and tries again, at\nmost `attempts` times; past that it is `stdio.ErrChanged` and nothing was counted.\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's loop:\n\n```ts\nimport { runProviderLoop, Grant, Credential } from \"@novox/mesh-sdk/provider-loop\";\n\nrunProviderLoop(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","dist":{"integrity":"sha512-3R4afDK0R3uBptitNRHH/kJspBYNqmIweAgcfulyR4IovLY/9I3D8iXMVbd8fE2RYypkhs6J822sCc3H+n9xcg==","shasum":"79aaa50a3dc5904a7d2a7e3d594a5a211e32b693","tarball":"https://git.novox.be/api/packages/novox/npm/%40novox%2Fmesh-sdk/-/0.1.17/mesh-sdk-0.1.17.tgz","fileCount":0,"unpackedSize":0},"maintainers":[{"name":"novox"}]}},"readme":"# mesh-sdk\n\nThe stable spine a Novox Mesh **module's own code builds against** — the tool it uses to plug\ninto the mesh, and nothing that belongs to a specific module or to another tier.\n\nIt earns its place by **rarely changing** (novox/hq [ADR 0039](https://git.novox.be/novox/hq)).\nThe test for anything here: *if editing it recompiles unrelated modules and it changes often, it\ndoes not belong.* Per-module code (a service's API client, its tool implementations, its\ncreate-a-resource adapter) lives **in the module**, never here — that coupling is exactly what\nturned the old SDK into constant maintenance and made every edit rebuild every module.\n\n## What is in it\n\nFive small areas, each a thing a module's `tools/` or `provisioner/` imports:\n\n### `contracts` — the runtime shapes module code touches\nNot the manifest schema (the control plane owns and parses that, in Go). The shapes a module's\n*running code* receives and returns: a provisioning **grant** and its credentials, the\n**mesh interface** definitions (what an `analytics` grant contains, what an `oidc-client` grant\ncontains — the contract both a provider and a consumer conform to), and the tool and event types.\nThese change rarely and deliberately; when one does, a rebuild of everything is *correct*.\n\n### `provider-loop` — the reconcile harness every provider on the grant files shares\nCalled `provisioner` until design 57 (novox/hq issue 678); that word is mesh-provisioner's now. The old path and\nnames (`/provisioner`, `runProvisioner`, `provisionerTools`) stay aliases until the providers importing them move to\nthe Go helper that answers consumers over the bus (`go/provider`, design 57 B2 and B3) and this loop retires with the\ngrant files. Its events and tools keep their names (`provisioner.failing`, `provisioner_retirement`, …): the\ncontroller and the operator read them.\n\nThe loop is identical for postgres, redis, minio and umami: watch the grants directory, for each\nrequested grant call the provider's adapter, write the sealed credential, handle withdrawal, and\nkeep converging (`watch`). That loop lives here. A **module provides only the adapter** — \"create\na database\", \"create a umami site\" — which is the volatile, per-service half and belongs in the\nmodule. This is the ADR 0039 line drawn through provisioning: stable loop here, per-service create\nin the module.\n\n**A consumer the mesh stops asking for is retired, not withdrawn whole** (novox/hq ADR 0230). ACTIVE\nbecomes RETIRED only once the same set of consumers has gone unasked in five consecutive passes that\nread the file AND for ten minutes (`stableForMs`, `STABLE_FOR_MS`; a pass that cannot read the file\nstarts both again). An adapter with `retire` disables the consumer's access, reversibly, and marks it;\n`reenable` (optional) undoes that before `create` when it is asked for again. **An adapter without\n`retire` is mark-only**: nothing in the backend changes — the consumer keeps its access — and the\nharness marks it \"retired, access kept, needs deletion\", says so loudly and announces it. **`remove` is\nnever called to retire**; it is the delete of an adapter without `delete`, reached only through a\nperson's `provisioner_delete`. A stable set of more than 3, or more than half of those held where more\nthan one is held, is not retired without a person: the provider waits for\n`provisioner_retire_approve` or `provisioner_retire_reject`, and says `provisioner.retirement`\n(`waiting`). Asked for again, a retired consumer is created — re-enabled\n— at once. Given `module`, the four tools (`provisioner_retirement`, `provisioner_retire_approve`,\n`provisioner_retire_reject`, `provisioner_delete`) are registered for it; `provisionerTools(handle)`\nbuilds them otherwise. Additions and changes are never delayed.\n\n**A provider that keeps failing a consumer says so on the bus** (novox/hq ADR 0224). A consumer whose\ncreate, check (`holds`) or secret has failed for five minutes without one success between\n(`failingAfterMs`) is announced `provisioner.failing` — the consumer, its machine, the class of error\n(`credentials-rejected`, `unreachable`, `secret-unreadable`, `refused`; an adapter's `classify` is\nbelieved over the words), the error with the password removed, since when and how many attempts — and\nagain every fifteen minutes while it lasts. The first success after it is `provisioner.recovered`, as is\na consumer no longer asked for or retired, and the first success for each consumer since the process\nstarted. Every event goes through the `announce` option, which defaults to the SDK's `emit`: a provider\nsays them without asking, and a failed publish is said in its journal, never failing the act.\n\n### `tools` — the tool-serving harness\n`registerModuleTools`, the `ToolDefinition` type, and the registry/worker that loads a module's\ntools and exposes them through the mesh's command surface. *How* a tool is declared and served is\nsettled; it does not change when an individual tool does. The tools themselves, and the API client\nthey call, live in the module.\n\n### `messaging` — the broker and event framework\nThe broker client (connect, request/reply, publish/subscribe), the event-consumer a module uses to\nreact to mesh events, and the envelope/routing-key conventions. Transport primitives.\n\n#### Taking an event — the one rule\n\nA module's handler (`on(pattern, handler)` here, `stdio.Subscribe` in Go, the same in every language)\n**takes an event by returning, and asks for it again by throwing** (Go: returning an error). Nothing\nelse counts: what a handler returns is not read.\n\nOn the wire, the runtime hands the bundle `mesh/event` with the envelope and acknowledges the event on\nthe bus when the answer is **anything but a JSON-RPC error** — `{}` (what the SDKs send), `null`, or no\n`result` at all. An `error` answer, no answer within the runtime's event timeout (two minutes), or the\nbundle exiting leaves it unacknowledged: it is offered again after five seconds, up to the module\nconsumer's maximum deliveries, after which the bus gives it up and the controller raises a condition\n(`max-deliveries`). The runtime's line for an event not taken quotes a handler's error as the\nhandler's own words, so it is never mistaken for the runtime's.\n\nSo, for a handler:\n\n- **Throw only when the work was not done** — the service refused, was unreachable, the store failed.\n  Never for something that went right but answered oddly: an API that answers an empty body is a\n  success, and reading it as JSON is a throw that has every event offered five times, its work done\n  five times, and a false alarm raised (novox/hq issue 276).\n- **Delivery is at-least-once**, so the work must be safe to do twice, or the handler skips an event\n  whose `x-event-id` (`event.id`) it already did — remembering it only once the work succeeded, so one\n  that failed is done when it is offered again.\n- An event no handler matches is answered at once and taken.\n- A subscribe the runtime refused leaves no handler behind, so asking again until it is taken hands\n  each event to the handler once.\n\nChecked by the SDKs' stdio tests (TypeScript `test/stdio.test.ts`, Go `go/stdio_test.go`) and the\nruntime's (`node-tools/internal/launch`, mesh-tools).\n\n### `state` — a module's current state on the bus\n`state(name)` reaches a state the module declared it keeps (`state` in its manifest) or reads\n(`reads`, as `<module>.<name>`): `get`, `put`, `delete`, `keys`, and `watch`, which hands the current\nvalues and then every change. Through the runtime that launched the bundle, which refuses what the\nmodule did not declare. Current values, never history and never a secret (novox/hq ADR 0201).\n\n### `seats` and `asks` — asking a person, answering on a channel (Go)\nA seat may name its caller or its kind (novox/hq ADR 0259): `stdio.SeatPublish` submits an accept or says\nan event under the module's own name or kind, `stdio.SeatTake` takes a held seat's work, `stdio.SeatProve`\nand `stdio.SeatAnswer` carry a proof (a code typed by a person, by request and reply, never kept),\n`stdio.SeatRecord` reads a record kept for the module, and `State(...).Create` and `.Update` write by\ncompare-and-set. The runtime does each only as far as the module's membership lists. `go/asks` is the\ncontract on top: the `Ask` an asker publishes and the checks it is held to (its `Whole` is what a channel that proves\nwho answers shows in place of its `Explanation`, and its `Details` what the Details answer shows, hq issue 383), the `Warrant` it acts on\n(`For`, `Says`), and the `Message`, `Choice`, `LinkAsked` and `Code` a channel takes and says, with the\nsubjects each travels on.\n`go/asker` is an asking module's client (ADR 0259 §10): `Ask` keeps an ask in the module's own state and then\npublishes it under the module's name; `Cancel`; `Where` reads its state from the router's record; `Listen` and\n`Take` hand the module each warrant once — marked acted on by compare-and-set before the module acts, and only\nfor an ask it made, an option it offered, at that option's level, before it expired. A lost compare-and-set is\n`stdio.ErrChanged`, told by the runtime's error code.\n`State(...).Increment(key, attempts)` is a counter on top of the two (for numbers handed out once, such as an\nissue's): it reads the key, writes one more at the revision read, and on a lost write reads and tries again, at\nmost `attempts` times; past that it is `stdio.ErrChanged` and nothing was counted.\n\n### `primitives` — sealing, semver, resolved-env\nSeal/unseal for secrets, semantic version comparison, and the accessor a module uses to read its\nown resolved environment.\n\n## What is NOT in it, and where it goes\n\n- **A module's API client and its tool implementations** → in the module. (The Plex client, the\n  Umami client, `tools/plex.ts` — all module-local. ADR 0039.)\n- **Delivery machinery** — build executor, bundler, dependency resolver, artifact manager, feature\n  handlers → **mesh-controller**. It co-evolves with the pipeline.\n- **Host synchronisers** — config-sync, ufw config, vhost generation, systemd, health checks →\n  **mesh-host**'s apply engine. The host applies these; they are not module code.\n- **Domain logic** — tasks, workflows, agents, provider integrations → **tier-2 contexts**.\n\nThat is why this stays small: everything volatile has somewhere else to be.\n\n## Using it\n\nA module's tools:\n\n```ts\nimport { registerModuleTools, ToolDefinition } from \"@novox/mesh-sdk/tools\";\nimport { UmamiClient } from \"../client.js\"; // the client lives in the module, not here\n\nregisterModuleTools(\"umami\", (env) => getUmamiTools(new UmamiClient(env.UMAMI_URL)));\n```\n\nA provider's loop:\n\n```ts\nimport { runProviderLoop, Grant, Credential } from \"@novox/mesh-sdk/provider-loop\";\n\nrunProviderLoop(\"analytics\", {\n  async create(grant: Grant): Promise<Credential> { /* create a umami site, return the grant */ },\n  async remove(grant: Grant): Promise<void> { /* delete the site */ },\n});\n```\n\nThe adapter is the only thing the module writes; the watching, sealing and grant-file handling are\nthe harness's.\n\n## Where the reasoning lives\n\nDesign and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):\n\n- `02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md` — the stability rule this repository is\n- `02-DECISIONS/0040-what-a-module-is.md` — a module, and why its per-module code lives in the module\n","maintainers":[{"name":"novox"}],"time":{"0.1.16":"2026-10-23T13:57:30Z","0.1.11":"2026-10-06T10:43:32Z","0.1.13":"2026-10-06T16:17:13Z","0.1.15":"2026-10-22T22:21:40Z","0.1.17":"2026-10-23T22:35:58Z","0.1.18":"2026-11-02T20:41:54Z","created":"2026-10-04T23:45:02Z","modified":"2026-11-02T20:41:54Z","0.1.10":"2026-10-04T23:45:02Z","0.1.12":"2026-10-06T12:52:00Z","0.1.14":"2026-10-13T06:37:55Z"},"repository":{"type":"","url":""},"author":{"name":""}}