@playform/plugin-dsh-batch-edit
v0.2.1 - UNPUBLISHED - plan:
BATCH-EDIT-TOOL-FEATURE
The role
The batch edit engine serves the DeepSeek Harness
plugin family (the Classic release).
It provides one tool, batch_edit, that turns files into processes held in state: you open a
machine, insert files into it, and the files process like a state machine in one go.
Each file on the system is a process the harness holds (Process<File>), not inert bytes, which is
the reversed view of the default UNIX file.
The philosophy and the research live in
Documentation/Plans/BATCH-EDIT-TOOL-FEATURE.md
and its granular subdocuments under Documentation/Plans/Batch-Edit-Tool/.
The surfaces
One tool, batch_edit, offers six actions: open, insert, remove, commit, state, and
close.
There is no service and no event listener, because the writes go through the factory's write
executor and the bash observer is the advisory interceptBash tag.
The machine (one tool, six actions)
| Action | Effect |
|---|
open | Declare the scope, insert files (paths or globs) as observed processes with their held version; the prepared schema (searches + ops) is validated fail-loud; misses are listed, never guessed |
insert | Add files to an open machine mid-life (the lease stays) |
remove | Drop files from an open machine |
commit | Run the transition table in one go, through the factory's write executor - behind the D6 policy gate (see below) |
state | Re-present the current state of every held file |
close | Close the machine (in-flight processes settle first - nothing silently dropped) |
The Process<File> states
observed -> running (commit/insert/monitor dispatch)
running -> done (Factory.Write outcome + the fresh version)
running -> errored (outcome.error / intent denial)
running -> halted (deadline / stale version / machine pause)
halted -> running (agent resumes: action=commit on the same machine)
done -> observed (re-inserted for a next batch)
errored -> observed (agent corrects the op)
any -> halted (machine close with in-flight work: settle-first)
A held file touched externally between insert and commit halts with the stale reason, the
machine stays open, and you resume it explicitly.
The transition table (one line per op)
file=<selector> search=<name> op=<MODE> [with=<TEXT>] [mode=first|all|<count>]
MODE is one of replace, insert-after, insert-before, remove-line, append, or prepend.
Searches are named at open: name=pattern (literal) or name=re:/pattern/flags (simple regex, the
v1 scope).
Larger batches use the opfile escape hatch (a prepared file path, ingested line by line, with no
schema limit).
The write path and the atomic gate
Every write goes through Factory.Write and nothing else: the explicit replaceIfVersion intent
(the fresh-stat version guard), the govern actor marker so the event path skips the marked events,
and the governed basenames (package.json, Cargo.toml) re-run through the factory's direct
path exactly once per write.
The gate is all-or-nothing on the apply loop: a planning failure halts or errors that file alone,
while a write failure stops the loop and returns the unwritten remainder to observed.
A commit exceeding the in-line deadline (capped at 120000, the composition contract) continues as
one background job and returns the typed jobId, and the settle truth arrives through the jobs
subscription and the next state presentation.
No plugin-owned timers exist anywhere.
The policy block (D6) - the apply gate
The config carries the shared per-action allowlist (policy: Policy(), composed from the factory's
block), mapped to State.Allow:
| action | default | action | default |
|---|
read | auto | write | approve |
index | auto | commit | approve |
record | auto | spawn | approve |
suggest | auto | message | auto |
The commit action consults Decide(State.Allow, "write") before any plan or write.
The shipped default is write: approve, so an apply is refused with the byte-exact
apply refused <id> (policy write=approve) line (in the ledger and as the thrown error): nothing is
read or written, the machine stays open with its cells observed, and the batch waits for the
user's approval through the existing approve binding (flip policy.write to auto, or approve the
batch through the batch-decision hook).
With write: auto the commit proceeds exactly as described above.
The block is one volatile object (a policy flip is hot-editable), and a resolved pack's policy
section overrides the defaults per action (the wiring is the next refinement).
The ledger (the contract, byte-stable)
machine opened <id> (<n> files, scope=<glob>)
inserted <file> at version <version>
transition running <file> op=<n>/<total>
transition applied <file> version <old> -> <new>
transition errored <file> <reason>
transition halted <file> <reason>
machine committed <id> (<applied> applied, <failed> failed, <halted> halted)
machine closed <id>
apply refused <id> (policy write=approve)
Plus the module-owned removed <file> line for the remove action.
The ledger file defaults to ~/.dsh/playform/plugin-dsh-batch-edit.log (one log per module).
The configuration
The plugin ships disabled (enabled: false, the IDLE-forever posture), and it enables only by
an explicit ACTIVATE in the profile.
Every knob is volatile (hot-editable without remounting):
| Field | Default | Meaning |
|---|
enabled | false | The master switch |
log | true | The ledger switch (the factory's shared volatile cell) |
logFile | ~/.dsh/playform/plugin-dsh-batch-edit.log | The module ledger |
machinesPerAgent | 2 | Open machines per agent |
opsPerCommit | 64 | Op lines per commit (overflow goes to opfile) |
deadlineMs | 120000 | In-line commit deadline (1000..120000) |
strictMode | false | Search-not-found errors vs skips |
interceptBash | false | The advisory bash intercept (v1: tags and records, never denies) |
monitorChecksets | [] | Per-file check-set names (the live containers' vocabulary, labels in v1) |
policy.* | D6 defaults | The per-action allowlist (the apply gate; see above) |
The build and the tests
The build is pnpm prepublishOnly (Source/prepublishOnly.sh): the plugin build (ESM Target/, Test
tree excluded), the Test build, the harness selfcheck, and the Test type-check.
The smoke folders are Commit-And-Ops, Machine-And-Contract, Observers-And-Waterfalls, and
Policy-Defaults.
The plan
This is a Classic PoC (source complete; the smoke suite, the build pass, and the EffectTS twin are
end-phase work, see Documentation/Plans/POC-BRIEF.md).
License
CC0-1.0.
