@playform/plugin-dsh-workspace-reflect
v0.1.0 - UNPUBLISHED - plan:
Workspace-Family/REFLECT
The role
The workspace-reflect service for the
DeepSeek Harness plugin family (the Classic
release).
The later stage service-provider role provides the code-block reflective operations: an
AST-aware rename, connect, or replace from a single call each, over the managed representations.
The one-call semantics
Each operation carries the whole transformation in one call, instead of a choreography of tools.
The spans use 1-based inclusive numbering, which is the graph's span grammar.
| Op | Request | Behavior |
|---|
rename | path, startLine, endLine, oldName, newName, scope? | The semantics service's scope-resolved plan first (its edits filtered to the operation's scope); the whole-word textual engine as the fallback. Zero occurrences is rejected. |
connect | fromPath, toPath, symbol? | Inserts an import of symbol from the relative specifier of toPath into fromPath; without a symbol, a reference comment. Already-connected is rejected. |
replace | path, startLine?, endLine?, text, node?, fingerprint? | A graph NODE target (the AST source) with its content fingerprint verified before the write; or a plain span (the textual form). The span guard rejects a span outside the file or wider than maxBlockLines. |
The AST-aware targeting
A replace can name the frozen node id of the workspace graph (node: "Block:<path>:<line>:body")
together with the content-derived fingerprint of the node.
The graph (ctx.workspaceGraph, probed and never injected) supplies the span, the check compares
the fingerprint with the current text through the formula of the graph, and only that span is
rewritten, so a mismatch refuses with rejected <path> (fingerprint mismatch) and writes nothing.
When the graph is absent, the explicit span from the caller is the fallback, and the check still
compares the fingerprint.
A rename asks the workspace-semantics service (ctx.workspaceSemantics, probed and never
injected) for the scope-resolved plan, which the service may deepen through the harness LSP seam,
and applies the edits of the plan inside the scope of the operation.
The textual whole-word engine is the fallback when the service is absent, refuses, or has no edit in
scope.
The reply is part of the type
Every operation returns the CommitReply union (Interface/Reply.ts), never a boolean or a thrown
error:
status: "applied" | "conflict" | "denied" | "rejected" | "recovery-required" | "outcome-unknown";
applied - written, and the new version travels with the reply.conflict - the version fence failed, the file moved under the operation, and nothing was
overwritten.denied - the plugin is disabled, and the cold mount answers denied.rejected - refused before any write (malformed request, oversized file or span, no matches,
already connected, a stale fingerprint, an absent graph).outcome-unknown - the write failed in a way that is neither a version conflict nor a confirmed
failure.
The publish path and the carry
Writes go only through the guarded write of the factory (the replaceIfVersion fence, the P4
sandbox policy, the stash pre-registration) and never through a raw fs write.
After an applied operation the plugin probes the optional workspaceGraph sibling service (never
injected) and asks it to re-index the changed file, which is the reflective carry, and an absent
graph is an honest skip.
The surfaces
rename(op), connect(op), replace(op), and act(op) (the dispatch by kind), all async and all
returning the reply union.
The configuration
Every knob is volatile and hot-editable without a remount: logFile
(~/.dsh/playform/plugin-dsh-workspace-reflect.log), log, enabled (false, the IDLE-forever
posture), propagate (block | file, default block), maxFileBytes (1000000), and
maxBlockLines (5000).
The plugin ships disabled and enables only through an explicit ACTIVATE.
The package adds no new knob, because the graph and the semantics service are optional siblings.
The policy block (D6) - the write gate
The config carries the shared per-action allowlist (policy: Policy(), composed from the block of
the factory) and maps it to State.Allow:
| action | default | action | default |
|---|
read | auto | write | approve |
index | auto | commit | approve |
record | auto | spawn | approve |
suggest | auto | message | auto |
The reflective WRITES are the gated actions, so replace and rename consult the write verdict
before the file is read or written.
An approve verdict (the shipped default) refuses the operation with the byte-exact
replace held <path> (policy write=approve) or rename held <path> (policy write=approve) line,
the reply is rejected with the policy holds the replace|rename (write=approve), and zero
writes reach the filesystem.
The fingerprint targeting is unchanged, with the policy as the OUTER check and the fingerprint
verification as the inner one.
Set policy.write to auto, or let a resolved pack override it, so the next operation reaches the
write path.
The block is one volatile object, so a policy flip is hot-editable without a remount.
A policy section of a resolved pack overrides the defaults per action, and that wiring is the next
refinement.
The ledger
The module owns the ledger and prefixes it with reflect:: activated, disabled, rename,
connect, replace, deepened, denied, rejected, conflict, carried, failed, and the two
policy holds replace held <path> (policy write=approve) /
rename held <path> (policy write=approve).
The new rejected reasons (fingerprint required for a node target,
fingerprint without a node target, fingerprint mismatch, node path mismatch,
node not targetable, node not found, graph absent) are documented in SCHEME.md section 5.
The build and the tests
The build runs pnpm prepublishOnly (Source/prepublishOnly.sh), which does the plugin build (ESM
Target/, with the Test tree excluded), the Test build, the harness selfcheck, and the Test
type-check.
The plan
License
CC0-1.0.
