SDK Design

sdk-design

This is not a style guide. Style and language-specific code shape are downstream (see $code-ts, $code-react for the TS sides). This is about what an SDK refuses to do — the discipline that keeps a package small, legible, and replaceable, regardless of language.

The thesis

An SDK lives or dies by what it refuses to expose. Default is core; customization is the exception. Every public knob is a contract you cannot retract without a semver break and a coordinated migration across every downstream call site.

A library with too few knobs is easy to grow. A library with too many is impossible to retire. The asymmetry is brutal — design from it.

This doctrine applies whether the package ships as an npm scope, a crate, a header-only library, a WASM module, a Python wheel, a hosted service with an SDK, or a pair of microservices defining a shared message vocabulary. The mechanics of "publish" differ; the discipline of "refuse the wrong contents" does not.

Scope: what counts as an SDK

This is the gate. The skill says "SDK," not "package," because the two are different. An SDK is:

• A surface that crosses a foreign-or-foreign-treated boundary. Published to a registry (npm, crates.io, PyPI); linked by a separately-versioned consumer (a desktop binary against a crate, a generated WASM/FFI binding); or authored as if a foreign consumer existed even if one doesn't yet (any package whose README documents it as a public surface, anything tagged for publication, anything in a *-hosted suffix family).
• Versioned independently of its callers, even if today every caller lives in the same monorepo and ships on the same commit. The intent to be replaceable is what counts.

What this excludes — where the doctrine is welcome but not load-bearing:

• A package with exactly one internal caller, shipping on the same commit, where if the caller's needs changed the package would be rewritten freely. That's not an SDK; that's a refactored module that happens to live in packages/. Adopt the parts of this skill that pay; skip the rest without apology.
• One-off helper crates pulled in by a single binary in the engine repo's crates/. Same logic.

Don't extend the doctrine to internal-only utilities just because the file structure looks like an SDK. The discipline costs something — designed views over raw streams, anti-goals as perimeters, promotion-on-dogfooding — and that cost is paid by the foreign-callers it protects. If there are no foreign callers (now or planned), the strictness doesn't pay back.

sdk-seam triggers on the same gate from the other angle: any boundary that meets the SDK bar above, where the same author writes both sides. Include FFI bindings to internal crates here — binding regeneration cost makes the boundary foreign-treated even when the crate is same-repo.

The deciding table

When a new decision lands — "should this be a provider hook? a built-in toggle? a sibling package? a public type or an internal seam?" — walk these in order. First match wins.

The third rung — "complex but internal" — is where most "extension-point" mistakes get caught. A real spec or schema (SVG element table, MIDI event types, OpenType tables, USB device classes) is the registry; the SDK implements against it. Don't re-invite the spec to be re-implemented at runtime by consumers.

Five disciplines

D1. Subscribe to outcomes, not events

The public observation surface is designed, not raw. It exposes purpose-built views — selection, mode, dirty/version, computed property — each handling multi-target, capability variance, and bookkeeping internally. Consumers never receive raw input events, reducer actions, or internal state frames.

If a needed view doesn't exist, that's an API gap to close, not an internals hatch to open. Exposing the internal stream because "the consumer can compose it themselves" is how you wake up six months later unable to refactor the core.

The same rule applies to the other direction: emit named outcomes (intents, commands, requests), not "the user moved their pointer." If your outputs carry phase markers (preview / commit, begin / progress / end), the consumer wraps history/transactions without guessing internal state.

D2. Pure-logic core, thin adapter shell

One-directional dependency, layered:

primitives / math  ←  logic core  ←  adapter shell  ←  host

The math/logic core has no I/O, no DOM, no canvas, no UI runtime, no global clock. Plain function over plain inputs returns plain output. Runnable under the language's basic test runner with zero mocks. A Rust crate's core compiles under no_std where feasible; a TS package's core has no window / document import; a Python package's core does not touch the filesystem.

The shell is a thin wire: lifecycle, draw loop, host wiring. Its own logic should be trivial enough to verify by inspection, because it's the part you can't test headlessly.

Why this matters: when a shell grows logic, that logic ships unguarded. Common failure: the shell holds a switch (render, dispatch, route) and a new core variant is added without updating the switch — the core's tests pass; the shell silently drops the variant; downstreams hit it in production. Push logic into the core. Tests follow.

D3. Outputs that satisfy different constraints stay separate

Don't conflate outputs that exist to satisfy different constraints. Every paired-but-asymmetric surface — render vs. hit-test, read vs. write, declared vs. computed, preview vs. commit, encode vs. decode — earns its asymmetry from a real disagreement in requirements. When you find yourself unifying them "for elegance," you're about to break one.

Concrete pattern: a UI surface that draws and hit-tests as two separate outputs. Drawing optimizes for legibility at any zoom; hit-testing optimizes for Fitts'-reach (fat targets, virtual regions that extend past the visible shape). Collapsing them — sizing the visual to match the hit AABB, or shrinking the hit region to match the visual — breaks one of the two; each side has to compromise to satisfy the other.

The generalization: tests assert each side separately, and — where they intentionally differ — assert the direction of difference (e.g., the hit region strictly contains the rendered bbox).

D4. Anti-goals as defensive perimeters

Every published SDK ships an explicit Anti-goals section in its README. It is not aspirational; it is the perimeter that lets the package stay small. Examples that have already prevented bloat across various Grida packages:

• "Not a host of plugins." — kills every PR that wants to add a widget registry.
• "Not undo-aware." — host owns history; SDK emits phase markers.
• "Not a private IR." — file bytes are the source of truth; the parsed view is rebuilt on load.
• "Not a renderer." — the surface backend is intentionally minimal.

When a feature request arrives, the first question is which anti-goal it would violate. If it violates one, the right answer is "this is the wrong tool." If it threatens one without crossing it, write the anti-goal sharper.

Adding an anti-goal is the cheapest design work an SDK author does.

D5. Names commit you

See $naming for the full treatment. The SDK-specific corollary:

• Public identifier costs ≫ directory cost. Directory rename is git mv; published-name rename is a coordinated downstream migration. Invest heavily before a name escapes its file.
• Terseness is a uniqueness claim. A bare Surface, Encoder, Intent, Paint in a package asserts "nothing else competes for this slot here." If a peer could be added later, qualify now.
• Suffix siblings over nested folders. Keep the parent's scope tight; new subdirectories quietly widen it.
• Avoid leaking consumer concerns into the producer's names. A type field documented as "used by <consumer> for <feature>" is leaking the consumer's problem into the contract. The field name should justify itself in producer-only terms.