Architecture

Seeded from a copy of cuora (its ports-and-adapters anatomy and the -cf Worker pattern).

tamias is ports-and-adapters. The engine owns the generic half of distribution; every content meaning is an adapter.

Ports

Port	Role	Impls
ref	claims + parses a ref into an opaque spec	one per kind (in the source-* crates)
source	plan(spec) → fetch(plan, into)	-fs, -git, -http, -cf
store	put/get/verify an installed package	-local, -cf
cache	content-addressed fetch cache	-local, -cf
registry	index + publish	-local, -cf (Worker + R2 + D1/KV)
deploy	service unit + teardown	-local (systemd)
driver	how a content type installs/deploys	tamias-driver-<type> (subprocess, argv)

Crate map

crate	layer	purpose
tamias-core	domain	Pure domain — package identity (@scope/name@semver), refs, manifests, records, digests (no I/O)
tamias-cache	port	cache port — read-through fetched content
tamias-config	port	Config port — where tamias.toml-shaped config comes from
tamias-deploy	port	deploy port — provision a remote registry (Worker + R2 + D1/KV)
tamias-registry	port	registry port — index + publish
tamias-source	port	source port — turn a ref into bytes
tamias-store	port	store port — content-addressed blobs
tamias-cache-cf	adapter	Cloudflare adapter (P6)
tamias-cache-local	adapter	local cache impl — content-addressed fetch cache
tamias-config-toml	adapter	TOML config impl
tamias-config-yml	adapter	YAML config impl (the standard) — tamias.yml / tamias.yaml
tamias-deploy-cf	adapter	Cloudflare deploy impl — the registry Worker + wrangler config
tamias-deploy-local	adapter	local deploy impl — manage a per-user service unit (systemd/launchd)
tamias-driver	adapter	content driver host — discovery + dispatch of tamias-driver-<type> (no product knowledge)
tamias-driver-tamias	adapter	tamias-driver-tamias — pavo view driver over the tamias install store, fetch cache, registry index, and driver dir (read-only)
tamias-publish	adapter	author side — pack + push
tamias-registry-cf	adapter	Cloudflare registry impl — a Worker + R2 over HTTP
tamias-registry-local	adapter	dir registry impl — a folder index, servable over HTTP
tamias-serve	adapter	ndjson JSON-RPC over stdio — the embedding surface
tamias-shell	adapter	Run a command in a working directory via bash -c — the generic shell-out helper
tamias-source-cf	adapter	Cloudflare registry source impl — the cf: ref arm
tamias-source-fs	adapter	fs source impl — local dirs and tarballs
tamias-source-git	adapter	git source impl — clone URL //subdir #rev
tamias-source-http	adapter	http source impl — .tgz GET + optional sha256 pin
tamias-store-cf	adapter	Cloudflare adapter (P6)
tamias-store-local	adapter	local store impl — a directory
tamias-telemetry	adapter	Opt-in OpenTelemetry layer over the tracing stack — OTLP export, W3C context propagation
tamias-testkit	adapter	Fixtures + adapter conformance for every port
tamias	binary	tamias — package & content manager: fetch, store, cache, dispense

The install path

ref ─► resolve ─► (cache hit?) ─► fetch ─► overlay (include:) ─► driver install ─► store

resolve pins git refs to a commit sha up front, so the content- addressed cache can be hit before fetching. The fetch→unpack split is what makes repeat installs and air-gapped nodes free.

Stores

• install store — <name>@<version>/ with a record (source ref, resolved sha, payload digest, installed-at).
• fetch cache — content-addressed; remove never touches it.
• registry — where published content lives: a directory, or a Cloudflare Worker + R2 + D1/KV.

Provenance

verify recomputes the payload digest against the record. Digest-pinned refs (#sha256:…, resolved shas) are the integrity contract — see Security model for the full trust story, including the --allow-drivers consent gate on payload-shipped drivers.

The embedding surface

tamias serve (the tamias-serve crate) runs the same install/list/ info/verify/remove verbs as an ndjson JSON-RPC service over stdio — for agents and daemons that want a persistent handle instead of one-shot CLI calls. The protocol is specified in serve reference.

Observability

tamias-telemetry is an opt-in OpenTelemetry layer over the tracing stack. Nothing exports unless you set an endpoint:

• TAMIAS_OTEL_ENDPOINT — OTLP/HTTP base URL (the opt-in switch), or the standard OTEL_EXPORTER_OTLP_ENDPOINT / …_TRACES_ENDPOINT.
• TAMIAS_OTEL_SERVICE_NAME / OTEL_SERVICE_NAME — service.name.
• W3C traceparent/tracestate propagation is installed when export is on; RUST_LOG-style filtering still applies.