Skip to content

architecture: define crate extraction thresholds and candidate seams #489

Description

@puremachinery

Problem

Carapace currently benefits from a single-crate shape: fast iteration, simple navigation, and low ceremony. As the codebase grows, some boundaries may become worth extracting, but extraction should be driven by concrete triggers rather than taste.

Goal

Write an ADR that defines when Carapace should extract a module into a crate and which seams are plausible candidates.

Proposed extraction triggers

Treat extraction as justified when one or more of these are true:

  • An external consumer exists or is approved on the roadmap.
  • The module API has been stable for 90 days without internal-only breaking changes.
  • Clean release rebuild exceeds 90 seconds on the reference developer machine, or common incremental rebuild exceeds 30 seconds after routine edits.
  • Platform-specific ownership is slowing independent work and the trait surface is small enough to isolate.
  • The boundary has a clear security contract that benefits from compile-time separation.

Candidate seams to evaluate

  • LLM provider abstraction.
  • OS sandbox layer, including platform backends and shared policy surface.
  • Plugin runtime only if concrete reuse pressure appears.

Acceptance criteria

  • Add an ADR under docs/design/ or equivalent.
  • Include extraction triggers with numeric thresholds.
  • Include non-goals: no speculative crate splitting and no public API promise without a consumer.
  • Include initial candidate ordering and why each candidate does or does not meet the triggers today.
  • Include a note on how tests and CI would change after extraction.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationrefactorInternal restructuring without intended behavior change

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions