Owned Artefacts

Declaring ownership

An artefact has a required path and optional kind, role, and create_parent. The smallest declaration owns one directory and needs nothing else — no state, typed input, context, or package provider.

artefacts:
  build-output:
    path: build
    kind: directory

actions:
  - name: clean-build
    command:
      clean_owned: [build-output]

artefacts:
  benchmark-report:
    path: dist/benchmarks/microbenchmarks.json
    role: report
    create_parent: true

actions:
  - name: benchmark
    produces: [benchmark-report]
    command:
      invoke: python benchmarks/run.py --output dist/benchmarks/microbenchmarks.json

produces “records ownership and expected outputs; it does not make a benchmark incremental or authorize replay of an old result.” A declared output that is missing after the producer succeeds is a producer failure. Partial outputs from a failed run are kept for inspection, never quietly removed or reused as evidence.

Scoped cleanup

Cleanup has two front doors and one implementation. In a recipe, clean_owned: [NAME, ...] is an execution unit in the structured command union; it names artefacts only and “never accepts raw shell paths.” On the command line, clean gains a repeatable --artefact NAME. Both share the same planner, validator, deleter, and structured results.

$ netsuke clean --artefact build-output --dry-run
$ netsuke clean --artefact build-output --force --no-input

Lifecycle and migration

Roadmap: 24.3, lifecycle invalidation and staged migration.

From the shallow end

Roadmap 24.1 establishes ownership before any deletion is permitted, and task 24.3.2 must “demonstrate that the one-directory feature works without state syntax.”

Confidence

Planned, not existing. RFC 0023 §8 and roadmap phase 24 set these acceptance requirements for code that deletes files.

The design refuses claims it cannot back. “No claim of race freedom is acceptable until adversarial replacement tests pass on each supported platform.” Cleanup “is not an atomic transaction and must never report rollback that it did not perform.” Without source-control metadata Netsuke cannot identify every source file, and the contract must say so. A later cargo clean recipe keeps Cargo's semantics, outside Netsuke's guarantee.

Accessibility and localization

Every human-readable message Netsuke emits is localized by default through its Fluent catalogues, and cleanup is no exception: previews, confirmations, and failure reports arrive in the operator's locale, while artefact names, paths, and reason codes stay exactly as written so they can be matched. RFC 0023 adds requirements that bear directly on anyone deciding, from text alone, whether to delete something, and they apply in Netsuke's accessible output mode as much as anywhere:

• The preview must state recursive scope “plainly”, and an interactive run asks for confirmation only after displaying it.
• Partial failures report exact removed, retained, and failed objects rather than a summary verdict.
• Command and recipe forms return the same structured results, so machine-readable output does not depend on which door was used.
• RFC 0025 §8 tells maturity diagnostics, including owned-cleanup findings, to “Reuse Fluent localization”, the machinery behind Netsuke's existing locale catalogues.

Task 24.3.2 documents ownership assertions, recursive scope, retained caches, preview limitations, and external-command boundaries. RFC 0023 does not discuss accessibility beyond these requirements.