The mechanics behind the product model.
Implementation details that matter when debugging or extending Switchyard: dual-path events, durable workflow steps, Git ref safety, credential boundaries and where each source of truth begins and ends.
Authority split
| System | Authoritative for | Not authoritative for |
|---|---|---|
| Cloudflare Artifacts | Git objects, commits, branches, tags and canonical refs. | Work status, workflow progress, review findings or policy. |
| Trestle | Coordination/application truth: Work, Attempts, PR metadata, workflow steps, findings, queue, policy, audit. | The actual contents/history of a Git branch. |
| Switchyard control plane | Rules that connect the two: orchestration, auth, policy, reconciliation and UX. | Long-term truth that exists only in process memory. |
The dual-path event identity
The event fast path and reconciliation both write normalized domain events keyed by the Git transition identity (repo, ref, before, after). Delivery metadata such as queue message id or “seen at” time is deliberately excluded from the logical identity so two observers of the same Git movement converge.
Artifacts push event ──► Cloudflare Queue ──► ingest ──┐
├─► one normalized ref transition
periodic git reconciliation ───────────────────────────┘
Trestle's idempotency behavior also matters here: the same Idempotency-Key with byte-identical content replays, while the same key with different content returns 409 idempotency_conflict. Switchyard treats the latter as convergence when the underlying Git fact is already durably represented rather than retrying forever.
Git/ref mutation safety
Canonical/ref movement uses ordinary Git as the final stale-write authority. Switchyard reads the expected SHA, creates the desired commit/merge, then performs a normal non-force push. If another actor moved the ref first, Git rejects the stale update. Force-push is therefore a policy-sensitive escape hatch rather than part of the normal integration substrate.
expected main = abc123
build candidate commit = def456
git push origin def456:main
# succeeds only while main is still compatible with the expected state
Workflow durability
step = (run_id, step_key, op, args_hash, status, result, attempts)
run script from top
for each durable operation:
completed step? → replay recorded result
in-flight step? → re-execute with bounded retry
new step? → record intent, execute, record result
This intentionally avoids serializing arbitrary JavaScript VM state. The workflow function is reproducible control logic; durable Switchyard operations are the persistence boundaries.
Credential store
| Layer | Rule |
|---|---|
| Provider credential | Encrypted at rest (AES-256-GCM), metadata-only API, resolved only for execution. |
| Agent role | Defines allowed intent/capabilities independently of a provider secret. |
| Repository authority | Granted by Switchyard access/policy and short-lived Git credentials, never by “having an API key.” |
| Fallback encryption key | May live under the local data directory; protects against database-only compromise, not full-host compromise. |
Why scratch Git exists
Preview, conflict analysis, semantic validation and integration need actual Git trees. The first implementation uses scratch clones because the correctness model is extremely clear: each operation gets isolated repository state. The measured performance cost is real and documented; a cached bare mirror/worktree design is the intended optimization once it passes equivalent isolation and credential-safety gates.