schema.ts

The URL zap fetches the GPG signing key from, on the operator's machine: https://, or http:// to a loopback host; any other scheme is rejected by the structural gate. It may carry a reference. The key is pinned by the blake3 of its bytes, and only bytes that hash to the pin are installed.

The key's vendored pin: the blake3 of its bytes, 64 lowercase hex. Absent, the pin is tracked in zap.lock (zap lock / zap update mint and advance it).

Where the GPG key is stored; default /usr/share/keyrings/{id}.asc. It takes no reference (rejected when the config is read): it is written into the source line, inside double quotes.

The deb source line (signed-by is auto-injected from key_path). It is expanded by the target shell inside double quotes, so $VERSION_CODENAME resolves there; it takes no reference (rejected when the config is read).

The .list file path; default /etc/apt/sources.list.d/{id}.list. It takes no reference (rejected when the config is read): detection reads it as declared.

Where the source comes from + how its integrity is verified.

The build command (e.g. zig build -p $HOME/.local -Doptimize=ReleaseFast).

Path that exists iff the build is installed — the detection probe.

Working directory for run: absolute, or relative to the extracted source dir, which is the default. Takes no reference: zap rejects one here.

Build environment. Keys are POSIX names ([A-Za-z_][A-Za-z0-9_]*), validated at config-eval; a name beginning with __zap_ is rejected by the structural gate (zap's own wrapper variables). A value's references resolve before it is quoted, so it can hold any text but a NUL and the reference delimiters U+FDD0 and U+FDD1.

A fetched source archive — fetched, verified, and content-addressed.

Fetch location: an https:// URL with no user:password@ (http:// only for a loopback host), or the structural gate rejects it. It may carry a reference, resolved when zap fetches (the lock addresses a secret reference by its token, any other by its value).

How the fetched source is unpacked before run.

Optional fetch credential for a private byte-host (never hashed).

Optional upstream-signature verification, run when a fetch fills the content cache, before the bytes are pinned or built. A cache hit is not re-verified: it is re-hashed against the pin.

Vendored source pin. A declared pin self-pins; absent, the lock pins it. Mirrors ContentHash — exactly 64 lowercase hex on the wire.

The command to run.

A substring that must appear in stdout.

Auth method (default scram-sha-256).

Allowed client addresses, each an IP address with its prefix length (127.0.0.1/32); a keyword (all, samehost, samenet) or a host name is refused. At least one: an auth that names none is refused, since it would write no rule.

Database engine (only postgresql).

Database name to create. Taken literally (never shell-expanded); a reference resolves on the operator's machine.

Role/user to create and own the database. Taken literally (never shell-expanded); zap.env('USER') declares "the operator's OS user".

pg_hba.conf auth config. Absent, zap writes no rule, and the role is reached over the Unix socket by the OS account of the same name. A rule zap adds is put in force with pg_reload_conf(); the server isn't restarted, and the target needs no service_manager for it.

Host polled over HTTPS (e.g. app.example.com, or a zap.env('DEPLOY_DOMAIN') reference resolved at execution).

Request path polled over HTTPS against domain, beginning with / (e.g. /health). Takes no reference: zap rejects one here.

How many times to poll before failing the deploy, at least 1 (default 15).

Delay between poll attempts, in milliseconds (default 2000).

Build command run locally before packaging (e.g. gro build).

Files/directories (relative to the operator cwd) to package into the tarball. An entry can't begin with - (write ./-name) or with @; either is rejected by the structural gate.

Remote application root — holds releases/, shared/, and the current symlink. An absolute path, written out: no reference (rejected when the config is read) and no ~ (rejected by the structural gate).

Number of releases to retain on the target, the live one included (default 5). Below 2 is rejected by the structural gate: the release just deployed and the one it replaced, which a failed deploy rolls back to, are always kept.

Service to restart after the symlink swap. Requires target.service_manager. Takes no reference (rejected when the config is read).

Files under the remote shared/ directory to symlink into each release root. Each is a relative name of a file: no .. component, no control character, not ending in / or in a . component (anything else is rejected by the structural gate).

Post-extract commands run on the target, in the new release directory, before swap, each in a shell of its own (sh -ec): an exit in one ends that command, not the deploy, and one that fails stops the deploy before the swap. The release is still under its hidden staging name then, so a command shouldn't record its absolute path.

Optional post-restart HTTP health check.

Directory path, absolute or under ~ (may carry a reference).

Desired octal mode (e.g. "755"). Mirrors Mode — octal, 7777 at most.

Desired owner. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse).

Desired group. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse).

Target path (may carry a reference / ~).

Content source.

Desired octal mode (e.g. "600"). Mirrors Mode — octal, 7777 at most.

Desired owner. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse).

Desired group. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse).

Ids of service resources notified when this file changes.

Command that must exit 0 after a write (e.g. NGINX_VALIDATE), or the write is rolled back — the previous bytes, owner, group, and mode restored, less any set-id or sticky bit the declared mode lacks (or a new file removed) — and the change fails. Runs against the file in place, so it suits a file some larger config includes. Text content only — rejected on remote.

Firewall backend (ufw or nftables).

Default policy for incoming traffic (default deny).

Default policy for outgoing traffic (default allow).

Allow rules (named profiles or port/proto pairs).

The install script's https:// URL, piped into shell; any other scheme is rejected by the structural gate.

Path checked for existence to confirm installation (may carry ~).

Command the fetched install script is piped into (default sh), run as written. The script is fetched whole first; a failed fetch, or an empty script, fails the step.

Symlink path (may carry a reference / ~). A real directory at the path fails the step.

The target the symlink should point to (resolved the same way).

The pinned minisign public key: the 56 base64 characters beginning RW (the key line of a .pub file, without its comment). Mirrors the Rust MinisignKey; any other shape is rejected at config eval.

Explicit signature URL, held to the rule url is; it may carry a reference. Defaults to the source URL with .minisig appended to its path, before any query or fragment.

Package-manager → package-name mapping (e.g. {apt: "curl"}). A name takes no reference (rejected when the config is read): it is put into the manager's command unquoted, and detection asks the manager about it (under apt by the name alone, for name=version at exactly that version, and for name:arch by that architecture). So a name is one word in the manager's syntax — a letter or digit, then letters, digits, and `+ . _ - = ~ : /

Optional custom check (a path, or a command); defaults to the PM query. A check beginning /, ~, or $HOME is a path and its references resolve; anything else is a command, run as written.

The absolute path to check, as written: no reference; a ~ or relative path is rejected. A link is followed: type, mode and owner are its target's.

Required type; absent accepts either.

Required octal mode (e.g. "600"). Mirrors Mode — octal, 7777 at most. 0644 and 644 compare the same.

Required owner. Mirrors AccountName — a portable Unix user/group name ([a-z_][a-z0-9_-]*, optional trailing $; a numeric uid/gid or any other character is rejected at parse).

Whether the path's size must be above zero (test -s). A directory's size depends on its filesystem, so this doesn't reliably check that a directory has entries.

Environment variables shared across all steps. Rejected by the structural gate — the sequential executor doesn't apply it; inline the vars into each step's run.

The pipeline steps.

Max steps to run concurrently, at least 1. Any value above 1 is rejected by the structural gate: steps run sequentially.

Identifier for this step, unique within the pipeline: a repeated id is rejected by the structural gate.

Human-readable name for the step, printed under its id in a plan.

The command this step runs.

Working directory for this step. Rejected by the structural gate — the sequential executor doesn't apply it; inline a cd into run.

Environment variables for this step. Rejected by the structural gate — the sequential executor doesn't apply it; inline the vars into run.

Step ids this depends on (within the pipeline). Rejected by the structural gate: steps run sequentially in declaration order.

Authorization: Bearer <token>.

The bearer token; typically a reference, never a literal.

Fetch location: an https:// URL with no user:password@ (http:// only for a loopback host), or the structural gate rejects it. It may carry a reference, resolved when zap fetches (the lock addresses a secret reference by its token, any other by its value).

Vendored content pin. A declared pin self-pins (skips the lock); absent, the lock pins the resolved hash. Mirrors ContentHash — exactly 64 lowercase hex on the wire.

How the fetched bytes are materialized on the target.

Optional fetch credential for a private byte-host (never hashed).

Fetch location: an https:// URL with no user:password@ (http:// only for a loopback host), or the structural gate rejects it. It may carry a reference, resolved when zap fetches (the lock addresses a secret reference by its token, any other by its value).

How the fetched source is unpacked before run.

Optional fetch credential for a private byte-host (never hashed).

Optional upstream-signature verification, run when a fetch fills the content cache, before the bytes are pinned or built. A cache hit is not re-verified: it is re-hashed against the pin.

Vendored source pin. A declared pin self-pins; absent, the lock pins it. Mirrors ContentHash — exactly 64 lowercase hex on the wire.

Stable identity within the config. Mirrors ResourceId (a plain string on the wire). A name: a letter, a digit, or _, then any of those and . + : @ -; anything else is rejected by the structural gate.

A label for whoever reads the config. A plan prints it under the change's header; everything else (apply's progress, events, triggers) names a resource by its id. It is carried in a change, so changing it changes the plan_hash of a plan that changes this resource, but never the lock entry's config_hash.

Resource ids this depends on (the resource-graph edges).

Check command — exit 0 means the script is already applied (skip).

The command the planner emits when the check fails.

Working directory for the check and for run. An absolute path, taken verbatim: no reference (rejected when the config is read) and no ~ (rejected by the structural gate). A check that can't enter it reads as not applied; a run that can't enter it fails without running.

Extra environment, exported to the check and to run (every command of a compound sees it). Keys are POSIX names ([A-Za-z_][A-Za-z0-9_]*), validated at config-eval; a name beginning with __zap_ is rejected by the structural gate (zap's own wrapper variables). A value's references resolve before it is quoted, so it can hold any text but a NUL and the reference delimiters U+FDD0 and U+FDD1 (a value with a ' goes here, not in the command text).

Service name (interpreted by the target's service manager). Takes no reference (rejected when the config is read): it is put into the manager's command unquoted, and detection reads it as declared. So a name is one word — a letter or digit, then letters, digits, and _ . @ : - — and anything else is rejected when the config is read.

Whether the service should be enabled at boot (default true).

Whether the service should be running now; absent = don't manage runtime.

Resource ids whose change triggers a restart of this service, if it is running (try-restart on systemd, rc-service --ifstarted on OpenRC). A trigger on a service with running: false is a config error.

Resource ids whose change triggers a reload of this service, if it is running: try-reload-or-restart on systemd, rc-service --ifstarted <svc> reload on OpenRC (a service that can't reload fails the step).

minisign -V against public_key.

The pinned minisign public key: the 56 base64 characters beginning RW (the key line of a .pub file, without its comment). Mirrors the Rust MinisignKey; any other shape is rejected at config eval.

Explicit signature URL, held to the rule url is; it may carry a reference. Defaults to the source URL with .minisig appended to its path, before any query or fragment.

Swap size (e.g. "2G").

Swap file path (default /swapfile). Used verbatim — no ~ expansion, and no reference (rejected when the config is read: detection reads it as declared).

A {{key}} template with per-variable substitution.

The template body, used as declared. It takes no reference. A placeholder is a variable's name between {{ and }} and nothing else; one that names no variable is rejected by the structural gate.

Variable values substituted for {{key}}, in one pass: a value is never read for placeholders. A string value may be or carry a reference, resolved before it is substituted. A value that isn't a string is substituted as its compact JSON text and takes no reference at any depth. A variable no placeholder names is rejected by the structural gate. A reference whose value holds a line break (CR or LF) or a NUL holds the file and refuses its write: it would add a line.

The kind of value each named variable must render to (TemplateKind). Each key names a variable in vars, or the structural gate rejects it. A declared kind is checked on a value written out when the config is read, and on one carrying a reference once it resolves, which holds the file and refuses its write when it isn't its kind. A variable not named here declares no kind: a reference in its value is still held to 'text' once it resolves, and a value written out is substituted unchecked.

Unix username to create/manage. Mirrors AccountName — a portable Unix name ([a-z_][a-z0-9_-]*, optional trailing $; anything else is rejected at parse). zap manages the user's home as /home/<username>, so 'root' (home /root) is rejected by the structural gate, and an existing account whose /etc/passwd home is anything else is held at detection when home_mode or ssh_keys is declared. With either declared, a /home/<username> directory root owns is given to the user when zap creates the account, and left as it is for an existing one; one another uid owns, a link, or a non-directory there holds the user.

Login shell (e.g. /bin/bash); system default when absent. It takes no reference (rejected when the config is read): detection reads it as declared.

Home-directory mode (e.g. "711"). Mirrors Mode — octal, 7777 at most.

SSH key configuration, if managed.

Sudo access: a grant, or false to remove. Absent = unmanaged.

Supplementary groups the user must belong to (additive — listed groups are added, never removed). Mirrors AccountName[] — portable Unix names (see AccountName). Absent/empty = unmanaged.

Assertions to check (all must pass for the resource to be met).