System Facts

Opting in, and who may grant what

A manifest opts in with a root host_facts mapping. Without it, nothing is collected and a variable a manifest already calls host stays an ordinary variable. With it, and no gather list, only the inexpensive platform group is requested.

host_facts:
  schema: 1

vars:
  test_program: "fixture-test{{ host.exe_suffix }}"

# Excerpt: the schema/version declaration and other manifest sections are omitted.
actions:
  - name: check-posix
    when: "{{ host.family == 'unix' }}"
    command: cargo test --all-targets
  - name: check-windows
    when: "{{ host.os == 'windows' }}"
    command: cargo test --all-targets

host_facts:
  schema: 1
  gather:
    - platform
    - distribution

The fact schema

“Host” means the Netsuke planner process: not the machine that built Netsuke, not a cross-compilation output, not a container a recipe enters, and not a remote executor. An x86-64 Netsuke running under translation on an ARM machine reports x86_64; a Linux Netsuke in WSL reports linux; a Windows Netsuke launched from Git Bash reports windows. Passing a Cargo --target never changes host.

Platform: the default group (§6.1)

No filesystem, registry, environment, subprocess, or network access: the values come from std::env::consts and target configuration. The spellings are Rust’s, so macos, not Darwin, and aarch64, not arm64. A platform that cannot supply a field fails with unsupported_host_platform rather than being guessed as linux or x86_64.

Missing, denied, and invalid are different (§6.4)

• Missing is a value. Once a group is selected every field exists; an observation without it is null, and an optional field is tested with is not none. A group’s outcome is collected, partial, absent, or unsupported.
• Denied and invalid are errors. A denied group, malformed data, an I/O failure, or an exceeded bound is never reported as absent, false, zero, or an empty mapping.
• Typos are errors too. Reading an unselected group raises host_fact_not_collected without collecting; an unknown field raises unknown_host_fact, even inside a default expression, “so a typo does not become a silent platform decision”.

Using facts: what they replace, and one snapshot per run

actions:
  - name: sign-installer
    # Fails to load where OS is unset:
    # env() has no default on main.
    when: env('OS') == 'Windows_NT'
    command: "Set-AuthenticodeSignature ..."

host_facts:
  schema: 1

actions:
  - name: sign-installer
    when: "{{ host.os == 'windows' }}"
    command: "Set-AuthenticodeSignature ..."

The right-hand panel applies the RFC’s when pattern to the left-hand action; the action itself is this page’s, not the RFC’s. Where the question is a suffix rather than a branch, the RFC’s own "fixture-test{{ host.exe_suffix }}" folds two per-platform names into one.

Discovery, inspection, and privacy

$ netsuke help targets --host-facts

$ netsuke facts
$ netsuke --json facts --gather platform --filter os --filter arch

Reproducibility, planning, and caching

Opted-in facts are environmental planning inputs. The same manifest, snapshot, and declared inputs must compile identically; different planners need not produce the same graph. Collecting without a shell does not make a build hermetic.

What a manifest knows today

Nothing in the shipped standard library describes the host directly. A manifest asks specific questions through specific helpers, each with its own gate, and none runs under netsuke help targets. RFC 0029 is explicit that facts must not become a bypass for env() or command_available().

Separately, roadmap step 6.7 plans query-gated probes — exists, link_exists, same_file, mount, and expandvars — covered on the standard library preview. Those ask about files and variables; host facts ask about the planner, and depend on none of them.

Where facts stop

Roads not taken

Still open (§14.6). The final spelling of the inspection command and the consent flag, platform names for less common targets, and the safe native-adapter dependencies. The RFC holds that none of these alters the privacy default, the immutable snapshot, the scope definitions, or the operator ceiling.

From the shallow end

A manifest that never opts in is untouched: RFC 0025 keeps unannotated manifests a supported use, and the quickstart must stay byte-for-byte identical. The route deeper, in order:

1. Today: select tools, not platforms. command_available() in complementary when guards is shipped and tested. Where the real question is “is this tool here?”, it remains the right answer after facts land.
2. Planned: opt in with two lines. host_facts: {schema: 1} requests platform only, which the default grant already allows. No operator configuration is needed.
3. Planned: replace one probe. Swap an OS or uname check for host.os or host.family, or fold duplicated targets with host.exe_suffix.
4. Planned: look before branching. netsuke facts shows what the planner would see, without a manifest.
5. Planned: ask for more, with permission. Add distribution or kernel to gather, and have the operator grant it in host_fact_policy.allowed_groups.

Delivery slices (§13.1)

1. Accept the field meanings, opt-in, privacy contract, and schema allocation; define the snapshot, grant, and diagnostic interfaces (roadmap 30.1).
2. Ship the platform-only slice with the immutable projection, namespace checks, inspection, query consent, and fingerprinting together (30.2).
3. Add separately authorized distribution and kernel providers (30.3).
4. Integrate typed fixtures with the testing framework and publish Linux, macOS, and Windows migration examples (30.4).

Confidence

Stable diagnostics (§12). unsupported_host_fact_schema, unknown_host_fact_group, host_fact_collection_denied, host_namespace_shadowed, unknown_host_fact, host_fact_not_collected, host_facts_disabled_in_query, host_fact_source_invalid, host_fact_limit_exceeded, and host_plan_context_mismatch. Each reports the group, field, request origin, and manifest span without printing system-file values. The downstream canaries are Repovec Appliance, MXD, and OrthoConfig.

Accessibility and localization

Every human-readable message Netsuke emits is localized by default through Fluent, and host facts are no exception. The facts themselves are machine values — linux, aarch64, unsupported — and stay untranslated, as do the diagnostic category identifiers and JSON field names.

• Localized diagnostics. Roadmap 30.1.2 defines the stable diagnostic categories “with localized messages”; the category is the part that survives translation.
• Localized inspection. netsuke facts and its schema description use “the existing CLI metadata, localization, and JSON conventions, not hand-built parallel output”.
• Locale cannot change a build. The facts digest excludes localization and diagnostic text, so running under another locale does not invalidate a plan.
• Legible, unambiguous output. Human output puts one field per line and escapes control characters; empty values, nulls, and unsupported groups remain visibly distinct. --json gives tools a structured alternative.
• Redaction by omission. Identifying data is never collected, raw system files never reach diagnostics, and telemetry labels are bounded categories.