Module edit 

Workload-edit primitive — SRD-64 §6.4–§6.5.

The single in-process transaction shape for every workload-mutating CLI command (nmbrs report --add, --replace, nmbrs report rename):

1. Lock the workload file (lock::acquire) so concurrent nmbrs invocations don’t corrupt each other’s writes.
2. Read the current content into memory.
3. Parse with tree-sitter-yaml (locate::parse) to a CST that preserves every byte (comments, blank lines, quote styles).
4. Locate the target byte range (locate::locate_path) for the anchor we want to edit.
5. Splice the new content into the source (splice) — bytes outside the located range stay byte-identical.
6. Roundtrip-parse the result with the existing [super::parse_workload] to verify the mutation didn’t break the workload schema.
7. Rotate backups (backup::rotate) — old .bak → .bak.prev, current → .bak.
8. Atomically commit the new content via temp + rename (backup::commit_temp).

Failure at any step rolls back the backup pair so the invariant “.bak == content prior to the most recent successful edit” holds.

Public surface

with_workload is the one-call entry point. add_item, replace_item, rename_item are convenience wrappers for the SRD-64 promotion flows that target a report: block; they all dispatch through with_workload.

Lock + backup are NOT optional

Even tests reaching for with_workload exercise the full transaction — the lock is held, the backup pair is rotated. That’s the contract; relaxing it for tests would mean the tests don’t validate the contract.

Modules

backup

Backup-rotation transaction for workload edits.

locate

Tree-sitter-based YAML locator.

lock

Cooperative file locking for workload edits.

splice

Byte-range splicer for the workload edit primitive.

Structs

EditCtx

Transactional edit context. The mutate closure receives a mutable EditCtx and returns the post-edit source string. The driver verifies that string parses cleanly before committing.

Enums

AddOutcome

Outcome flag for add_item / replace_item: did the existing item already exist?

Anchor

Anchor specifier for --add / --at / --contextual. Mirrors the SRD-64 §6.1 surface but pre-resolved — the caller is responsible for translating user CLI input into one of these variants.

Functions

add_item

Promote item into the workload at anchor’s report: block, in group. Returns AddOutcome::Inserted if the item was new; AddOutcome::Replaced if replace=true and the item pre-existed.

rename_item

Rename a report item from old_name to new_name in the workload at workload_path. SRD-64 §6.6: pure metadata edit — anchor stays at the existing site.

replace_item

with_workload

Run a workload edit transaction. The closure produces the new source content; the driver handles lock, backup, roundtrip-parse, and atomic commit.