Deployment Decision

This document captures the deployment strategy for zetl: how it is distributed, where it runs, and what infrastructure assumptions it makes.

(given single-binary)
(given no-network-calls)
(given local-first-design)

^deployment-context

Distribution model

zetl ships as a single static binary via cargo install. There is no package server, no auto-update mechanism, and no telemetry. Users are responsible for keeping their installation current.

^distribution-model

Performance acceptability

The performance requirements documented in Performance are acceptable for the target deployment environment (developer workstations and CI runners).

; Perf targets from Performance.md ^perf-numbers are acceptable for our deployment
(meta perf-acceptable (source "[[Performance^perf-numbers]]"))

^perf-acceptability-block

CI runners (GitHub Actions, GitLab CI) typically have 2–4 vCPUs and SSDs, which means zetl’s incremental re-index target of < 50 ms is achievable even for large repositories.

^ci-context

Caching backend decision

For deployments that opt into a caching backend, Redis vs Memcached is the reference decision. Locally, no external cache is required — zetl uses its own file-based Cache.

; Adopt Redis where a caching backend is needed
(normally r-use-redis-in-deployment
  (and prefer-redis-over-memcached single-node-deployment)
  use-redis-backend)

^caching-backend-rule

Platform targets

Platform	Status	Notes
macOS (aarch64)	Primary	Developer machines
Linux (x86_64)	Primary	CI and server environments
Windows (x86_64)	Supported	Tested via cross-compilation

^platform-targets

CI integration

zetl can be invoked from CI to fail a build when dead links or SPL drift are detected:

zetl index && zetl check --exit-code

^ci-integration-snippet

See also: Performance, Redis vs Memcached, Cache, Local-first Design

Linked Pages

Local-first Design

Local-first Design

zetl never modifies your files. It is strictly read-only against the vault.

(given read-only-vault-access)
(given disposable-cache)

Principles

Read-only — zetl only reads Markdown and .spl files. It never writes to, renames, or deletes vault content.
Disposable cache — the .zetl/ directory contains only derived data (the Link Graph index and Reasoning Engine theory cache). Deleting it loses nothing; zetl index regenerates it.
No network — zetl makes no network calls. Everything runs locally.
No lock-in — your vault is plain Markdown with optional Spindle Lisp blocks. Removing zetl leaves your files untouched.

Why this matters

Users trust zetl with their knowledge base — years of accumulated notes. A tool that might corrupt, reformat, or accidentally delete files would be a non-starter. Read-only access removes that risk entirely.

The Cache is the only thing zetl writes, and it lives in a clearly-marked directory that can be gitignored.

Compatibility

This design means zetl works alongside Obsidian, Logseq, Foam, Dendron, or any editor. Multiple tools can read the same vault simultaneously without conflict.

See also: Cache, Scanner, Rust for CLI

Cache

Cache

zetl uses mtiame-based incremental caching for both the Link Graph and the Reasoning Engine’s theory. On subsequent runs, only files modified since the last scan are re-parsed.

How it works

The cache lives in .zetl/ at the vault root:

index.json — serialised link graph
theory.json — serialised reasoning theory and conclusions

Each entry records the file’s last-modified timestamp. When zetl starts, it compares mtimes and only re-scans changed files. Use --no-cache to force a full rebuild.

(given mtime-based-cache)
(given incremental-rebuild)

Design tension

There is an unresolved design tension in how aggressively to cache reasoning results:

; Cache the theory for fast startup
(normally r-cache-theory
  mtime-based-cache
  cache-reasoning-results)

; But recomputing ensures results are always fresh
(normally r-recompute-theory
  incremental-rebuild
  (not cache-reasoning-results))

Both arguments have merit. Try zetl reason conflicts on this vault to see how zetl surfaces this kind of tension. A future Plugin System could let users configure the trade-off.

Safety

Redis vs Memcached

Redis vs Memcached

We evaluated Redis and Memcached as caching backends for the zetl index layer. The decision was driven by benchmark data and operational simplicity requirements.

(given redis-evaluated)
(given memcached-evaluated)
(given single-node-deployment)

^cache-decision-context

Benchmark Results

We ran read/write throughput tests at various concurrency levels against both backends using a representative workload of 10 000 graph index lookups.

Backend	Reads/sec (p50)	Reads/sec (p99)	Writes/sec	Memory overhead
Redis 7.2	185 000	210 000	92 000	~12 MB
Memcached	170 000	198 000	88 000	~8 MB

^benchmark-results

The p99 numbers show Redis edges out Memcached on read latency under load, primarily because Redis pipelines responses more aggressively over a single connection.

^benchmark-interpretation

Analysis

Given the benchmark data, Redis meets our throughput target of 150 000 reads/sec with comfortable headroom.

; Redis read throughput exceeds our threshold — grounded to the benchmark table
(meta redis-fast-enough (source "^benchmark-results"))

Performance

zetl is designed for large vaults — tens of thousands of notes — without sacrificing startup speed or interactive responsiveness.

(given fast-startup)
(given incremental-rebuild)

^perf-goals

Requirements

zetl must cold-start in under 200 ms on a vault of 10 000 Markdown files, complete incremental re-index in under 50 ms when fewer than 100 files have changed, and serve graph queries in under 10 ms at p99 on a fully-indexed vault of 50 000 nodes.

^perf-numbers

These figures were chosen to keep the tool imperceptibly fast during normal editing workflows, where the user expects results before they finish reading the command prompt.

^perf-rationale

Strategies

Incremental parsing

The Scanner only re-parses files whose mtime has advanced since the last run. On typical editing sessions (1–5 changed files), this cuts scan time by 99 % compared to a full rebuild.