Skip to main content
Builtins catalog / nika:remove_file

File

Tool family from the canonical registry.

invoke

Call this builtin through the invoke verb.

​
Read this contract

This reference preserves the specification at the revision linked below. Source examples are fragments: their surrounding tasks, inputs and permissions are not supplied here. Consult engine status and nika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.

​
Usage and behavior

illustration
Remove ONE existing regular file named by path: · returns the requested path string. The arguments are exactly { path: string }: there is no recursive, glob, force, missing-ok or destination option, no alias and no nika:delete. Authority. Removal is an external filesystem write effect. It needs the callable’s tool grant (permits.tools) AND a permits.fs.write bound containing the exact resolved path. It needs no read grant: no content is read, and no parent directory is created. A preceding copy (nika:read → nika:write) needs its own independent read and write grants. Removal joins the ordinary authority, taint, consent and composition laws exactly like nika:write, and the same-path mutation law (NIKA-SEC-012): ordered mutations of one path are permitted; an incomparable write/remove or remove/remove pair on one path, or a for_each fan onto one constant path, is refused. There is no global one-writer rule. Path shape (judged on the RAW spelling, before any normalization). The components are delimited by / and the target platform’s main separator. The path MUST be a non-empty string; it is not trimmed (a single-space file name is a name). A trailing separator, a final . or .. component, or a root or platform prefix with no file name names a directory and is refused — out/. is refused even though a pure path API normalizes the final dot away. On POSIX a backslash is an ordinary file-name character, never silently turned into a separator. out/./note, out/part/../note, out/... and pass the shape rule; the boundary judges them next. Wildcard-looking characters (* · ? · [) are literal file-name characters: one path names one target and is never expanded. Execution. The engine validates, without following links, that an existing regular entry sits at the resolved path. A missing entry, a directory, a symlink (dangling or not), a FIFO or any other special entry fails; there is no recursive removal, no content-opening probe and no link-following metadata fallback. Confinement to the granted boundary is descriptor-relative or carries an equivalent guarantee; a backend that cannot provide it refuses. Success reports the requested path only after the backend reports the removal. That returned path, or a permit allow, is not independent proof of disk state. No atomic inode comparison is promised: the leaf may change between validation and unlink, but a substituted symlink never redirects the removal to its target. Not a transaction. Copy-then-remove is two effects. A failed publication prevents a dependent removal; a removal that fails after a successful publication leaves a visible copy. There is no rollback, inode-preserving rename, whole-batch atomicity or automatic cleanup, and a cancellation without a settled backend result does not prove that nothing was removed. The static path-shape judgment covers literal paths only. The shape of a templated path string is deferred whole to the judgment of its resolved value, even when a trailing / or a final /. is visible in the template (REMOVE_FILE-001 then refuses it); deferral never means the path is safe or runnable. A missing or non-string path, a non-object args and any extra argument key stay static refusals, even beside a templated path. An authority refusal is never reported as REMOVE_FILE-002.

Arguments

Pass the values required by the tool contract.

Permissions

Understand authority before granting effects.

Errors and recovery

Read diagnostics and choose a recovery policy.

Workflow templates

Put the fragment inside a complete workflow.

​
Contract provenance

Read the pinned specification · Canonical registry. Tool identity: nika:remove_file. Specification revision: 480f5b80cb77.