API Boundaries

Tento docs should make architectural boundaries visible. If a crate cannot be explained as a small public API with explicit host seams, the code probably needs better encapsulation.

Public API rule

Each crate should expose a narrow set of stable entry points:

Typed clients for external services.
Domain models that callers can reason about without knowing wire details.
Feature-gated connector or sync modules when the crate participates in row dispatch.
Script config modules for local commands.
Error and result types that preserve provider context without leaking secrets.

Everything else should stay private until multiple callers need it.

Provider crates

Provider crates should follow this shape:

tento-{provider}
  default build        SDK: HTTP/OAuth/models only
  connector feature    Row + Integration implementations
  sync-plugin feature  optional lona-sync provider/executor

The default SDK build should not depend on Lona host models, row stores, or sync orchestration. When host behavior is needed, expose a trait such as GoogleBackendDeps, GarminBackendDeps, or WeatherBackend and let the host adapt its own storage and credential types.

Host seams

Host seams should be explicit traits, not callback bags hidden in app code. A good seam says:

Which owner or auth id scopes the operation.
Which domain object crosses the boundary.
Whether the operation reads, writes, or triggers sync.
Which result shape the host must convert back into connector data.

Provider crates can declare the seam, but concrete lona-* types should stay in host crates such as lona-rows or lona-so.

External services

External service details belong in the owning crate:

Endpoint paths.
OAuth scope strings.
Pagination cursors.
Raw webhook verification.
Vendor-specific retry behavior.
Generated or mirrored provider model types.

Application code should call high-level SDK methods. If a caller needs to know too much about a vendor API, add a method to the provider crate instead of duplicating the protocol at the call site.

Scripts

Script modules are operational entry points. They may wire env config, logging, and command output, but they should delegate core behavior to the crate API.