← stitchkitDocumentation

Design decisions

Records of why stitchkit is built the way it is — each one states the context, the alternatives weighed against it and the consequences. They are immutable: when a decision changes, a new record supersedes the old one and the old one stays.

Useful if you are weighing the library against alternatives, or wondering why something is deliberately missing.

  1. ADR 0001 — Build on Bun.serve(), no HTTP framework- Status: Accepted - Date: 2025-05
  2. ADR 0002 — A generic core: the framework carries no domain model- Status: Accepted - Date: 2025-05
  3. ADR 0003 — Two context types: RuntimeContext and HandlerContext- Status: Accepted - Date: 2025-05
  4. ADR 0004 — Four lifecycle hooks instead of a middleware chain- Status: Accepted - Date: 2025-05
  5. ADR 0005 — The typed client is inferred from the contract- Status: Accepted - Date: 2025-05 (core), 2026-05 (pilot fixes)
  6. ADR 0006 — Route groups and GET/DELETE query params- Status: Accepted - Date: 2026-05-13
  7. ADR 0007 — MCP and agent tools from one shared pipeline- Status: Accepted - Date: 2026-05-13 (pipeline, extend), 2026-05-20 (createMcpHandler)
  8. ADR 0008 — Thin wrappers over the stack you already use- Status: Accepted - Date: 2026-05-20
  9. ADR 0009 — A hand-rolled WebSocket transport- Status: Superseded by 0008 - Date: 2025-05 (decided), 2026-05-20 (reverted)
  10. ADR 0010 — Grow stitchkit into a fullstack framework- Status: Rejected - Date: 2026-05-13 (explored), 2026-05-20 (rejected)
  11. ADR 0011 — Bun-only, published as one small package- Status: Accepted - Date: 2026-05-20
  12. ADR 0012 — A built-in observability module- Status: Accepted - Date: 2026-05-20
  13. ADR 0013 — Runtime-agnostic core, Bun as first-class adapter- Status: Accepted — supersedes the Bun-only clause of ADR 0011 - Date: 2026-05-20
  14. ADR 0014 — The tool surface carries the same contract guarantees as HTTP- Status: Accepted — refines ADR 0007 - Date: 2026-05-20
  15. ADR 0015 — OAuth 2.1 resource-server toolkit for MCP- Status: Accepted - Date: 2026-05-29
  16. ADR 0016 — CLI as the fourth transport- Status: Accepted — extends ADR 0007, upholds ADR 0014 - Date: 2026-05-29
  17. ADR 0017 — Typed tool-path context via createToolkit- Status: Accepted — extends ADR 0003 - Date: 2026-05-29
  18. ADR 0018 — OpenAPI generated from the contract- Status: Accepted - Date: 2026-05-29
  19. ADR 0019 — Generic native MCP tools (wait / download / upload)- Status: Accepted — extends ADR 0007, upholds ADR 0002 - Date: 2026-05-29
  20. ADR 0020 — A raw WebSocket lane composed beside Socket.IO- Status: Accepted — upholds ADR 0008, Bun-only per ADR 0013 - Date: 2026-06-05
  21. ADR 0021 — Endpoint meta passthrough (opaque per-endpoint metadata)- Status: Accepted — extends ADR 0002 - Date: 2026-06-05
  22. ADR 0022 — Stable (service, action) identity on MethodDef- Status: Accepted — extends ADR 0002 and ADR 0021 - Date: 2026-06-05
  23. ADR 0023 — Range-capable file serving (serveFile)- Status: Accepted — extends ADR 0013 - Date: 2026-06-05
  24. ADR 0024 — Scope-driven mounting (scopePrefixes)- Status: Accepted — extends ADR 0002 - Date: 2026-06-05
  25. ADR 0025 — Typed scoped client (consumed keys as args)- Status: Accepted — extends ADR 0005 - Date: 2026-06-05
  26. ADR 0026 — Published stitch error-code registry- Status: Accepted — extends ADR 0002 - Date: 2026-06-05
  27. ADR 0027 — Transport-neutral contract execution (bring-your-own transport)- Status: Accepted — upholds ADR 0008 and ADR 0020; keeps the core generic per ADR 0002 - Date: 2026-06-05
  28. ADR 0028 — Revert createContractDispatcher (no adopting consumer)- Status: Accepted — supersedes the createContractDispatcher portion of ADR 0027. The rest of ADR 0027 (idempotent, createRetainedTopics, the open TransportSource union) stays Accepted. - Date:
  29. ADR 0029 — Endpoint identity and domain dimensions on the audit event- Status: Accepted — extends ADR 0012 (the observability module), ADR 0022 (stable endpoint identity), ADR 0021 (opaque passthrough) and keeps the core generic per ADR 0002. - Date: 2026-06-18
  30. ADR 0030 — Audit verb, sanitised error details, and complete error-code logging- Status: Accepted — extends ADR 0029 (audit completeness), ADR 0026 (error model), ADR 0022; keeps the core generic per ADR 0002. - Date: 2026-06-18
  31. ADR 0031 — Deep discriminated-union flattening for tool schemas- Status: Accepted — completes the flattenUnionInput feature; refines ADR 0007 / ADR 0014. - Date: 2026-06-22
  32. ADR 0032 — Brand-based AppError identification (not instanceof)- Status: Accepted — fixes the error model of ADR 0026; consequence of the multi-chunk build (ADR 0011 / ADR 0013). - Date: 2026-06-22
  33. ADR 0033 — Sound flatten: collision widening, discriminator support, probe parity- Status: Accepted — completes/repairs ADR 0031. - Date: 2026-06-22