Documentation

The vision and the systems it demands: what Weaver is, how Sempai and Jacquard work, and where the roadmap goes next.

The RFCs and Architecture Decision Records (ADRs) that reset the public surface for 0.1.0, plus the gap analysis that keeps the target honest. The RFC and ADR entries are Status: Proposed.

In the planned 0.1.0 target, configuration is layered with ortho-config: built-in defaults < config files < profile < environment < flags. Each successive layer overrides earlier sources, so a CLI flag always wins.

The 0.1.0 target remains one local, per-user daemon with no remotely reachable endpoint. Unix targets default to a Unix domain socket. The current prototype retains tcp://127.0.0.1:9779 for non-Unix compatibility; TCP must stay on an IPv4 or IPv6 loopback address and is not a remote-service transport.

# Top-level keys (no [section] headers)

# Prototype TCP compatibility (loopback-only; not remote)
daemon_socket = { transport = "tcp", host = "127.0.0.1", port = 9779 }

# Logging
log_filter = "info"
log_format = "compact"  # Example override: default is "json"

# Capability overrides (repeatable)
[[capability_overrides]]
language = "python"
capability = "definition.get"
directive = "force"

File Discovery

When --config-path is not supplied, the loader searches the standard XDG locations for weaver.toml or .weaver.toml. Discovery honours XDG_CONFIG_HOME (typically ~/.config/weaver/) and falls back to the project root. If no files exist, the built-in defaults apply.

Fail-Fast Validation

ortho-config v0.6.0 treats invalid configuration files as fatal. Both the CLI and daemon abort with a LoadConfiguration error that lists every offending path. No silent fallback — fix or remove the reported files.

failed to load configuration: multiple configuration errors:
1: Configuration file error in '/etc/weaver/weaver.toml': expected `}`
2: Configuration file error in '/home/alex/.weaver.toml': invalid type:
string "yes", expected a boolean

Environment Variables

Capability Overrides

Override directives let operators mask unreliable capabilities or force a feature on when a language server under-reports support. Each directive uses the syntax language:capability=directive.

Identifiers are case-insensitive and whitespace-trimmed. Duplicates are resolved by keeping the last directive for each language/capability pair. In TOML, use the [[capability_overrides]] array; from the CLI, repeat --capability-overrides:

$ weaver definitions get \
    --capability-overrides "python:definition.get=force" \
    --capability-overrides "rust:definition.get=deny" \
    --uri file:///src/main.rs --position 10:5

Communication between the CLI and daemon uses a kind-based JSONL envelope. Each line is a JSON object with kind set to stream or exit.

Treat this section as canonical. Command, install, and safety pages now summarize the protocol and link back here when they need operator detail.

{"kind":"stream","stream":"stdout","data":"[{\"uri\":\"file:///src/main.rs\",\"line\":42,\"column\":17}]\n"}
{"kind":"exit","status":0}

This wrapper is daemon transport, not CLI display. The CLI parses each line, strips the envelope, and then either forwards data verbatim in JSON mode or renders recognised payloads for humans.

Runtime Artefacts

The daemon creates three files in the runtime directory (typically $XDG_RUNTIME_DIR/weaver/). PID and health files are written atomically.

Health Snapshot

The health file is a single-line JSON document that operators and automation can poll without speaking the daemon protocol. Status transitions: starting → ready → stopping.

{"status":"ready","pid":12345,"timestamp":1713356400}

Signal Handling

Operational Details

The weaver-plugins crate delegates specialist tasks to external tools running in sandboxed processes. Plugins fall into two categories:

Plugin Manifest

Each plugin is described by a TOML manifest:

name = "rope"
version = "1.0.0"
kind = "actuator"
languages = ["python"]
executable = "/usr/bin/weaver-plugin-rope"
capabilities = ["rename-symbol"]

IPC Protocol

Plugins are short-lived, one-shot processes communicating via JSONL over standard I/O:

1. The broker writes one JSONL request to the plugin's stdin and closes stdin.
2. The plugin writes one JSONL response to stdout and exits.
3. Plugin stderr is captured for diagnostic logging (not part of the protocol).

File content is passed in-band as part of the request body, so sandboxed plugins do not need filesystem access.

Default Plugins

Capability IDs

The daemon routes operations to plugins based on the requested capability and target language. Stable capability identifiers:

Refusal Reason Codes

When a plugin cannot perform an operation, it returns a failure response with diagnostics. Each diagnostic may include a reason_code for programmatic matching:

Language Servers

The daemon spawns language server processes for each language, communicating via JSON-RPC 2.0 over stdio. Servers are initialised lazily on first use and shut down gracefully (5 s timeout) when the daemon stops.