Skip to content

Posthaste specs

The durable, layered technical specs live in domain directories. Each domain is authored at the scope levels it needs (L0 orientation → L1 contract → L2 structure → L3 implementation reference):

  • Mail state: canonical mail state, derived projections, query evaluation, and conversation freshness.
  • Runtime: UI-facing runtime contract for the bundled application, embedded authority server, and future deployment adapters. Sub-domains: the runtime adapter (the client-facing Api/Link surfaces), runtime internals (assembly, links, lifecycle), and mutations.
  • Replication: coherent links — the optimistic up-channel, authoritative down-channel, and confirmation-watermark convergence that move state between client, runtime, and authority server. Two seams have their own sub-domains: the client↔runtime link (the device replica) and the runtime↔authority-server link (the AuthorityServerLink seam).
  • Client: the renderer's boundary over runtime state — the runtime adapter facade, view/mutation hooks, the main-thread reactive live-store, and the wasm replica hosted in a Web Worker.
  • API: external /v1 HTTP and SSE contract over those projections. The route inventory is generated: endpoints.
  • Authority server: the far node's service, store, provider, account-runtime, event, and API implementation boundaries.
  • Crate topology: the workspace crate set, ownership, dependency hierarchy, role binaries, and the wasm-pure frontier.
  • UI: the mail shell's navigation model — view kinds, pane focus, and the keyboard contract. Partial: only the navigation model (L0) and keyboard shortcuts (L1) are authored; the remaining UI sections are a follow-up.
  • Testing: behavior-contract coverage model, the shared posthaste-testkit harness (StalwartFixture, the mock-gmail label-model fixture, runtime-in-harness), the client testkit (apps/web/test/harness), and the verification ladder. The remaining forward contract (posthastectl) is in the testkit roadmap.

Task-oriented, tool-facing guides (as opposed to the layered specs above) live alongside the specs:

  • Scripting quickstart: automate Posthaste from a shell script with no protocol code — the /v1/events tap plus the one-vocabulary apply path, driven by posthastectl.
  • Scripting security & threat model: the trust relationships and mitigations for event-triggered code (watch --exec, exec/webhook rules).
  • User guide: the walkthrough-style user/operator guide.

Decision records and design history

The durable specs above record what is true now. The reasoning, deviations, and forward plans behind them live as dated records in eph/ — RFCs (the architecture-cleanup, scripting, drafts, provider-reliability, lifecycle, and client-resilience programs), audits, design notes, and the reality ledger (DEVIATION-L2-architecture-cleanup.md). The architecture-cleanup refactor these specs describe has landed (M0–M9c); its RFC is RFC-L2-architecture-cleanup.md. Release channels — nightly (dogfood/devtools) versus stable builds, updater manifests, and signing gates — is a design note in that corpus. Open technical debt tracked here: issues/L2-runtime-lifecycle-debt.md.