@playform/hook-dsh-workspace-journal
v0.1.0 - UNPUBLISHED - plan:
Workspace-Family/JOURNAL
The role
The workspace-journal hook is a DeepSeek Harness plugin that is the evidence record of the
workspace: the undo, the recovery checkpoints, and the crash recovery.
It is the JOURNAL role of the invisible flow of the workspace family:
... → the merge commits (through Factory.Write) → the journal records → the audit lines → the
live view presents
(Documentation/Plans/Workspace-Family/JOURNAL.md; Documentation/Plans/WORKSPACE-FAMILY-V4-1.md
sections 3.7-3.8.)
What it does
-
Per-batch records. The merge journals a batch before its writes land:
ctx.workspaceJournal.open(batch, entries) stores the batch record (state applying) and the
per-file pre-images in the own KV storage domain workspace_journal of the plugin.
No journal, no writes: "the workspace transaction is the ordered set of those writes plus the
journal".
-
Revert data. The per-file pre-images (content + version captured before the write) are the
entries, and ctx.workspaceJournal.revert(batchId) replays them backward through the
version-fenced write executor of the factory.
A fence mismatch is a reported conflict, never a silent overwrite, and a truncated pre-image is
skipped with a ledger line, never half-applied.
-
Recovery checkpoints. The fs/observed listener (registered on the ROOT context) counts the
writes landing against open batches and persists the progress: how far a crash got.
-
Crash recovery. At boot, every batch still applying is marked recovery-required with its
identity.
The honest all-or-nothing: recoverable partial states, never an invisible intermediate
state.
Batch lifecycle: applying → verified | recovery-required | reverted.
Service
ctx.workspaceJournal (registered from apply):
| Method | Description |
|---|
open(batch, entries) | Journal the batch before its writes land (throws if storage is down) |
seal(batchId, next, reason?) | Close the batch: verified or recovery-required |
revert(batchId) | Replay backward; per-file report |
recover() | The boot pass over still-applying batches |
batch(id) / batches() / entries(id) | Reads |
statistics() | { batches, entries, applying } |
The configuration
Every knob is a volatile cell (hot edits commit without remounting):
| Field | Default | Description |
|---|
enabled | false | Master switch (the IDLE-forever posture) |
log | true | Ledger enabled |
logFile | ~/.dsh/playform/ets-hook-dsh-workspace-journal.log | The plugin's own ledger |
domain | workspace_journal | The KV domain name |
maxBatches | 200 | The batch ring bound |
maxEntryBytes | 65536 | The pre-image size cap |
exclude | ["node_modules/**", "**/Target/**", "**/.git/**"] | Excluded paths |
policy.* | see below | The D6 per-action allowlist (the revert gate) |
The plugin ships disabled: it never appears in the bundles of the profile and enables only by an
explicit ACTIVATE.
The policy block (D6) - the revert gate
The config carries the shared per-action allowlist (policy: Policy(), composed from the block of
the factory), 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 revert is the ONE gated action of the hook, because it writes the pre-images back, while
recording (open/seal/recover) is record and stays automatic.
An approve verdict for write refuses the whole pass before any file is touched: the ledger
records the byte-exact revert held (<n> files) (policy write=approve) line, zero writes reach
the filesystem, the batch keeps its applying/verified state, and no record is persisted, so the
revert waits for the user.
Flip policy.write to auto (or let a resolved pack override it) to let the next revert replay.
The block is one volatile object, so a policy flip is hot-editable without a remount, and the
policy section of a resolved pack overrides the defaults per action (the wiring is the next
refinement).
The documented refusal line: journal: revert held (<n> files) (policy write=approve).
Exemptions (documented)
- The ledger file is appended with plain
appendFileSync, because ctx.fs has no append operation
(the Append precedent).
- Reverting an absent pre-image file unlinks it through
node:fs, because ctx.fs has no delete
operation; every write goes through the shared version-fenced executor of the factory.
The plan
License
CC0-1.0.
