ADR 0044 — what the SDK holds, and what it refuses #13

2026-09-03T19:41:23Z

jschoubben commented

2026-09-03 19:41:23 +00:00

Records the mesh-sdk boundary we worked out, with the emphasis on the must-not half.

Supersedes ADR 0030's "contracts shared across tiers: types, not behaviour" — because that draws the line in the wrong place. The line is change-frequency, not kind.

Holds: the stable spine — tool-serving harness + tool-definition types, the messaging/event framework, the contracts (manifest/declaration/provision/link shapes), core primitives (crypto/semver). Changes rarely; when it does, a global rebuild is correct.
Must not hold: per-module API clients (clients/plex.ts), per-module tool implementations, anything volatile. These are what made hal/sdk constant-maintenance and turned every edit into an all-module rebuild.
The rule: if editing a thing recompiles unrelated modules AND it changes often, it does not belong in the SDK. Frequent-and-cascading is the disease; per-module clients/tools are its carriers.
Root cause named: the pressure was to share code between a module's own features (plex's tools/health/hooks all wanted one PlexClient), and the only place to do that was the global SDK — so intra-module sharing leaked out as inter-module coupling.
Where per-module shared code goes instead: in the module — a plain shared file the features import (plex/client.ts), or a module-local sdk for the few large ones. Editing it rebuilds that module and nothing else.

Consequence worth flagging: converting a module is partly a de-coupling (pull its client/tools out of the shared SDK into the module), not just a move — a conversion that copied clients/plex.ts into the SDK's replacement would rebuild the exact mistake.

Leaves 0030 untouched (immutable); updates repos.md's canonical mesh-sdk description to match.

https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Records the mesh-sdk boundary we worked out, with the emphasis on the **must-not** half. **Supersedes** ADR 0030's "contracts shared across tiers: types, not behaviour" — because that draws the line in the wrong place. The line is **change-frequency, not kind**. - **Holds:** the stable spine — tool-serving harness + tool-definition types, the messaging/event framework, the contracts (manifest/declaration/provision/link shapes), core primitives (crypto/semver). Changes rarely; when it does, a global rebuild is correct. - **Must not hold:** per-module API clients (`clients/plex.ts`), per-module tool implementations, anything volatile. These are what made hal/sdk constant-maintenance and turned every edit into an all-module rebuild. - **The rule:** *if editing a thing recompiles unrelated modules AND it changes often, it does not belong in the SDK.* Frequent-and-cascading is the disease; per-module clients/tools are its carriers. - **Root cause named:** the pressure was to share code between a module's *own* features (plex's tools/health/hooks all wanted one `PlexClient`), and the only place to do that was the global SDK — so intra-module sharing leaked out as inter-module coupling. - **Where per-module shared code goes instead:** in the module — a plain shared file the features import (`plex/client.ts`), or a module-local sdk for the few large ones. Editing it rebuilds that module and nothing else. Consequence worth flagging: converting a module is partly a **de-coupling** (pull its client/tools out of the shared SDK into the module), not just a move — a conversion that copied `clients/plex.ts` into the SDK's replacement would rebuild the exact mistake. Leaves 0030 untouched (immutable); updates `repos.md`'s canonical mesh-sdk description to match. https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

jschoubben added 1 commit 2026-09-03 19:41:23 +00:00

ADR 0044 — what the SDK holds, and what it refuses 50d61398b6

Supersedes ADR 0030's 'types, not behaviour' line for mesh-sdk. The
boundary is change-frequency, not kind: the SDK holds the stable spine
(tool-serving harness, messaging/event framework, contracts, core
primitives) and refuses per-module clients, per-module tool code, and
anything volatile — because those are what turned hal/sdk into constant
maintenance and made every edit rebuild every module.

States the rule (frequent AND cascading is the disease), why the root
cause was intra-module feature-sharing leaking into inter-module
coupling, and where per-module shared code lives instead (in the
module — a shared file, or a module-local sdk for the few large ones).
Updates repos.md's canonical mesh-sdk description to match; leaves 0030
untouched (immutable).

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

jschoubben closed this pull request

2026-09-05 01:17:11 +00:00

mesh-admin referenced this pull request

2026-10-07 14:02:24 +00:00

To-be 48 Phases B to E are built: what each chose, and what is still to read on the live mesh #166

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: novox/hq#13