01Fundamental First Principles
Every decision traced back to a small set of invariants. They are deliberately reductive — each one removes an entire class of future failure rather than patching an instance.
1One crypto source
All three workers import HMAC mint/verify from @tws/core. No hand-synced copies — the third crypto clone and its drift class are gone.
2One secret source
OAUTH_SIGNING_KEY lives once in Cloudflare Secrets Store; each worker binds a reference, not a copy. Parity cannot drift by construction.
3Share crypto only (asymmetric consumers)
Providers consume @tws/core's full spine; vault consumes crypto only and keeps its richer dispatch/registry local — core is the thinner snapshot, so vault must not import it whole.
4Narrow waist
Promote to the shared package only what is byte-identical and stable. Resisting over-consolidation is itself a principle — the waist stays narrow on purpose.
5Vault as relay bus
Cross-session state is a vault artifact + tasks, never chat. Any session/agent/operator reconstructs full state from the vault alone.
6Verify before relay
Never propagate a claim (merge / deploy / "broken") without checking ground truth. This caught a stale leaked-key assumption, a dead-clone commit mismatch, and the #81 regression.
7Decouple independent units
Ship each continuously; couple only truly-dependent steps. Persona cutover was decoupled; the breaking CoreEnv flip + provider align were a deliberate coupled migration.
8Secrets stay operator-direct
Never hand an agent the raw key or master token. The operator seeds/rotates from a trusted terminal; mint tools read the key from env only — never an argument, never a transcript.
02The Narrow-Waist Architecture
One monorepo, one shared package as the waist, three independently-deployable workers as the rims — with two different consumption contracts against the same core.
packages/core the waist
Crypto/identity + (for providers) dispatch, registry, mcp-api, resolver, audit, health. The single home of getSigningKey() (memoized per isolate, zero per-request cost).
workers/{vault, qbo-sync, pipedrive-sync} the rims
Each: own wrangler.toml, env extends CoreEnv, tests. Cross-worker calls are service bindings only (callSibling) — no worker imports another's source.
03The Secret Rotation, Collapsed
The current key was unrecoverable (redacted in docs, never in git, write-only in Cloudflare). So seed-current and rotate-to-new collapsed into one move — lossless at ~4 users, and it kills the leaked key immediately.
04High-Leverage Vectors & Impact
Each vector converts a one-time fix into durable leverage — eliminating a class, or producing reusable infrastructure that pays forward into all future work.
ALeaked-key class eliminated
Impact: one value in Secrets Store, leaked classic key dead. Rotation is now "edit one value + redeploy," not "sync N copies." Security posture is structural, not procedural.
BDrift class killed (the #81 root cause)
Impact: #81 was a feature that lived in a standalone fork but not the deployed snapshot. One repo + a frozen fork removes the entire "merged there, missing here" failure mode.
CReusable orchestration metapattern
Impact: the vault-relay SOP applies to every future multi-session / agent / operator effort — the highest-leverage output, since it governs how all subsequent work is coordinated.
DTwo-layer correctness/isolation gate
Impact: a reusable harness that catches confidently-wrong and tenant-leaking answers a status-200 smoke cannot — earns its keep before any behavior-changing change (e.g. #76).
Eprovider-kit (future extraction)
Impact: when a third provider justifies it, the documented provider metapattern graduates into a package. Flagged, not built — avoids premature abstraction.
FOperator-direct secret delegation
Impact: a safe division of labor — agents drive everything except the raw secret. Preserves the MCP-OAuth trust model while keeping velocity.
05The Two-Layer Clean-Room Harness
Split validation into two processes with asymmetric knowledge so the test can't grade itself with the assumptions that built the system. A single-layer smoke confirms "it answered"; the two-layer harness confirms "it answered correctly and without leaking."
| Assertion class | Single-layer smoke | Two-layer harness |
|---|---|---|
| Surface responds (200 / isError) | ✅ | ✅ |
| Identity correctness (bearer honored, not just accepted) | ❌ | ✅ |
| Tenant / persona isolation (no cross-tenant leak) | ❌ | ✅ |
| Data fidelity (aggregates match D1 to the cent) | ❌ | ✅ |
| callSibling provenance (service bearer audited to right actor) | ❌ | ✅ |
06What Shipped, In Order
A coupled migration executed in reviewable units — each shippable on its own, only the breaking core flip deliberately coupled to the provider align.
07Current State & Open Vectors
| Open item | Shape | Status |
|---|---|---|
| Fork-freeze: workers/vault = source of truth; re-target #76 | Stops the drift class for good | open |
| Cleanup: merged branches, worktrees; QBO clone archived | Hygiene · QBO orphaned, not deleted | open |
| Operator bearer re-mint (MCP-OAuth, before expiry) | Auth continuity | open |
| Two-layer harness build | Reusable correctness/isolation gate | decide |
| #76 source-federation port (+4,840 LOC) | Separate scoped build vs rewired substrate | deferred |