Reusable Modules

Repository-relative includes

An include names a fragment by a literal path relative to the including file. An optional as puts the fragment’s named rules, targets, and actions in a namespace, so lint in the fragment below becomes rust_quality::lint; references inside the fragment are rewritten before cross-fragment resolution. An unnamespaced include contributes its declarations directly and is correspondingly more likely to collide.

includes:
  - path: build/netsuke/release.yaml
  - path: build/netsuke/rust-quality.yaml
    as: rust_quality

{
  "name": "rust_quality::lint",
  "source": "build/netsuke/rust-quality.yaml",
  "namespace": "rust_quality"
}

Roadmap: phase 16 — 16.1 loading each unit once, 16.2 preserving declaration meaning, and 16.3 builds and metadata queries. Task 16.1.1 still has to settle how a namespaced fragment’s variables are projected; the RFC requires only that it stay a typed namespace.

Versioned local bundles

A bundle is a directory with a strictly parsed descriptor, NetsukeBundle.yaml, beside its own manifest and fragments. The descriptor is not a build manifest: it names the bundle, versions it, lists every runtime resource its recipes use, declares typed parameters, and lists exports. Everything not exported is private. Consumers cannot reach past an exported entry point to the declarations behind it, and a bundle cannot read the importer’s unrelated variables.

bundle:
  name: df12.rust-quality
  version: 1.4.2
  manifest: Netsukefile.bundle.yaml
  runtime_resources: []

parameters:
  features:
    type: sequence<string>
    default: []

exports:
  actions:
    - lint
    - test

bundles:
  - name: df12.rust-quality
    source:
      path: build/bundles/rust-quality
    version: "=1.4.2"
    as: rust
    with:
      cargo: cargo
      features:
        - serde
        - tracing

The df12.rust-quality name is the RFC’s worked example, not a published bundle. Exported lint under as: rust becomes rust::lint, and the same bundle may be instantiated twice under distinct namespaces.

A bundle’s recipes keep exactly the execution capabilities of ordinary recipes; provenance does not make an unsafe command safe. Task 17.4.4 joins bundles to the structured-command track: process directories stay anchored to the importing workspace rather than the fragment or cache, and bundle content may not add shell definitions or replace a resolved shell through PATH, bindings, or placement.

Roadmap: phase 17 — 17.1 identity and parameters, 17.2 private instantiation, 17.3 content and locks, and 17.4 validation and the execution boundary.

Digest-pinned external bundles

An external source names a Git URL, exactly one of a tag or a full commit, an optional subdir, and a mandatory digest. A tag is a discovery handle, not the trust anchor: the lock record and the canonical content digest bind the bytes. Branches, HEAD, default branches, abbreviated commit IDs, and version-only references are rejected, and a tag that later resolves to a different object fails verification even when the bundle digest is unchanged — retagging is treated as a provenance event, not shrugged off.

bundles:
  - source:
      git:
        url: https://github.com/df12/netsuke-bundles.git
        tag: rust-quality/v1.4.2
        subdir: bundles/rust-quality
        digest: sha256:4e9f2d...
    name: df12.rust-quality
    version: "=1.4.2"
    as: rust

rust: df12.rust-quality 1.4.2
  git tag rust-quality/v1.4.2
  commit 8c5e4e6d76d75de67f66f09cb2c63d69d2e14f84
  digest sha256:4e9f2d...
  lock verified, cache hit

The df12/netsuke-bundles repository is illustrative, taken from the RFC’s examples. It does not exist as a published source, and whether any official bundles will is the open question in issue #784.

Roadmap: phase 18 — 18.1 the acquisition boundary, 18.2 exact Git objects, 18.3 cached provenance, and 18.4 offline reproduction; then 19.1, which decides extensions such as signed-tag policy only against recorded consumer needs.

From the shallow end

A single Netsukefile stays a complete, supported manifest. Manifests without includes keep their current behaviour, and the new keys arrive behind an additive manifest-format minor version, so an older Netsuke rejects them cleanly rather than misreading them. Each step below is optional.

1. 1. Split the monolith into includes

   Move one group into a fragment, add a literal include, add as if names collide, update references, and compare graph and help snapshots before deleting the originals. Because duplicates are errors, the copied and extracted versions cannot both stay active by accident.

2. 2. Turn a fragment into a local bundle

   Add a descriptor, give it a name and version, replace reads of importer variables with declared parameters, list the exports, import it under a namespace, and generate the lock record.

3. 3. Swap a vendored bundle for an external one

   Publish it unchanged under a reviewed tag, compute its digest, switch the source to git while keeping namespace, parameters, identity, and version, review the external lock, and prove graph equivalence before removing the vendored copy.

Includes never gain version semantics, and neither includes nor local bundles gain network behaviour. The roadmap is explicit that phase numbers identify work, not a requirement to finish every earlier phase, so a project may stop after any step.

Confidence

None of what follows exists yet; these are the guarantees the RFCs promise and the evidence the roadmap demands before any task is ticked.

The downstream migrations behind those canaries are tracked in issue #598.

Accessibility & localization

Every human-readable message Netsuke emits is localized by default through its Fluent catalogues, so include cycles, bundle resolution failures, lock mismatches, and provenance summaries arrive in the reader's locale like any other diagnostic; bundle names, versions, digests, and error codes stay untranslated so they can be matched. The composition documents add no composition-specific output modes, and this preview does not invent any. What else follows from them:

• Bundle commands join the existing CLI vocabulary. The roadmap requires that vocabulary to be extended before any bundle command is built, so bundle commands inherit the global flags v0.1.0-beta4 already has — --json, --locale, --color, --emoji, --progress, and --accessibility — rather than inventing their own. See the CLI reference.
• Human and JSON output. Provenance and failures are specified for both, with human output kept concise and failures distinguishable by type rather than by parsing prose.
• Redaction by default. Bundle parameter values are redacted in diagnostics and metadata unless declared expose: non-secret; credentials in Git URLs are rejected and redacted; absolute host and cache paths never appear in metadata.

The translation guide covers how those messages are translated, and the glossary keeps terms such as bundle and include consistent across locales.