States and Probes

Declaring a state

A state definition carries kind, kind-specific configuration, an optional path, identity, and optional prepare, probe, and accept_degraded. kind selects a documented built-in probe; there is no probe: builtin boilerplate. The smallest useful state checks that a directory exists:

Proposed syntax, RFC 0021 §3 (verbatim)

states:
  build-directory:
    kind: directory
    path: build
    prepare:
      invoke: python -c "from pathlib import Path; Path('build').mkdir(exist_ok=True)"

actions:
  - name: prepare-directory
    command:
      ensure_state: build-directory

It promises only that build is a directory, “not that its contents form a valid build”. Unknown fields, duplicate names, unresolved references, and unsupported kinds fail before execution.

Probes and external functional checks

Built-in probes serve the ordinary case. When a project needs a condition no built-in knows about, it adds an external functional check: a repository-owned executable that reports through the optional nagios protocol. No Nagios installation, daemon, or metric parser is involved — only the plugin exit-status convention.

Proposed syntax, RFC 0021 §3 (verbatim)

states:
  dev-env:
    kind: python-venv
    path: .venv
    identity:
      files: [pyproject.toml, uv.lock, tools/check_dev_env.py]
    prepare:
      invoke: uv sync --locked --group dev
    probe:
      external:
        invoke: python tools/check_dev_env.py
      protocol: nagios

actions:
  - name: test
    command:
      - ensure_state: dev-env
      - invoke: uv run --no-sync pytest

The built-in environment checks still run. The external check adds a condition; “it cannot bypass the built-in checks or forge preparation identity.” The script is project code, not shipped tooling, and a lockfile digest records what preparation was given, not whether the installation is still intact.

Exit codes

Table from RFC 0021 §6. The statuses follow the Nagios plugin guidelines.

Require, ensure, prepare

The proposal adds exactly three single-key operations to the structured command union. Readiness is defined separately from repair, and there is “no automatic repair loop or fallback runner.”

Adapted from RFC 0021 §5 and §9; the built-extension definition is omitted

actions:
  - name: extension-tests
    command:
      - require_state: built-extension
      - invoke: uv run --no-sync pytest tests/extension

This is the guard the RFC's Cuprum canary wants: require_state reports a missing extension without running Maturin to build it. Failure stops the rest of the action, and a state with no preparation recipe yields “an actionable unmet-precondition result, not an inferred installer.”

Evidence and leases

Roadmap: 23.2, leased state operations with durable evidence, building on the shared lease seam in 20.2.

From the shallow end

netsuke_version: "1.0.0"

targets:
  - name: hello.txt
    command: "echo 'Hello from Netsuke!' > hello.txt"

defaults:
  - hello.txt

The route in, one step at a time

1. A directory or file state with ensure_state: presence, nothing more.
2. A python-venv state with identity and prepare, so preparation is recorded against its inputs.
3. require_state on guards that must never build what they check.
4. An external functional check under the nagios protocol, then kind: custom for conditions no built-in covers.
5. The opt-in verified-states maturity rule, for a project that wants selected actions checked for a state operation before their first command.

The RFC's delivery order matches: “built-in probes and explicit operation semantics first, then external functional checks”. See roadmap 23.1 and 23.3.

Confidence

Every item below is a planned acceptance requirement from RFC 0021 §9 and roadmap phase 23. None exists yet. The roadmap asks for Proptest over algebraic invariants, bounded Kani harnesses for pure transition logic where useful, and subprocess end-to-end tests for process, filesystem, and locking boundaries.

The limits are stated as plainly as the guarantees. “State annotations do not make an untrusted checkout safe to execute.” An observational convention “must not be described as an operating-system sandbox.”

Accessibility and localization

Every human-readable message Netsuke emits is localized by default through its Fluent catalogues: state results, unmet preconditions, and preparation failures arrive in the reader's locale, while state names, result values such as not_ready, and reason codes stay untranslated. RFC 0021 does not discuss how state results appear in Netsuke's accessible output mode, and this page does not invent a promise. What the design does say bears on anyone reading probe output through a screen reader or a log:

• Probe arguments and output are redacted through the shared diagnostic policy, messages are bounded, and terminal control sequences are escaped. Raw probe output never becomes a metric label.
• The first stdout line of an external probe is a human summary; the rest is bounded diagnostic data. A preparation-identity mismatch and a functional failure keep distinct reason codes.
• Roadmap task 23.4.2 publishes state diagnostics and a probe author guide, and adds “metadata and localization through existing surfaces” — the Fluent catalogues Netsuke already ships.
• RFC 0025 §8 tells maturity diagnostics, including verified-states findings, to “Reuse Fluent localization” and never to leak probe output.

An external probe’s summary line is the probe author’s own text, so Netsuke shows it as written, inside its own localized framing.