Skip to content
C.W.K.
Stream
Lesson 02 of 05 · published

The One-Way Mirror

~12 min · mirror, ledger, append-only, isolation

Level 0Trace
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

Why Git does not live inside the vault

The shortest implementation runs git init at the vault root. Then editors, sync, and fleet copies encounter thousands of internal Git files. Locks, temporary objects, and permission mechanics unrelated to memory leak into the live collaboration surface.

An independent mirror cuts that mechanical coupling. It copies managed files from the live tree, Git uses the mirror as a work tree, and a bare repository receives history. The vault need not know Git exists. Their failure modes no longer share a directory.

Append-only does not happen automatically

Using Git does not make a ledger append-only. Reset, force push, or checkout-to-source can still rewrite history. Append-only is a contract of permitted commands and direction, not a property of the storage format.

The history writer may add the current mirror snapshot but cannot accept the live vault as a checkout target. A semantic edit first changes the vault and a sweep follows with a new commit. Two commit sources may exist, but both move forward.

The mirror must be byte evidence

If the mirror prettifies prose or repairs frontmatter, it stops being evidence of the source. Search normalization belongs in an index, while a version mirror prioritizes byte identity. Diffs then show human change rather than a mixture of change and tool decoration.

Exclusions must also be explicit. Editor caches and sync internals are not memory, but unknown extensions cannot disappear silently. The discovered managed tree is the default and exclusions form a narrow negative list.

Rehearse rebuilding

Calling a store derived is not proof. Recreate the mirror and index from empty directories and verify that the history head represents current source bytes. If rebuild exists only in documentation, the cache will become authority during the next incident. Rebuild time and failure logs are operational costs too.

A one-way mirror gains history while protecting source. Safety comes not from using Git but from having no reverse operation.

Code

A minimal isolated mirror and bare-style history shape·bash
demo_dir=$(mktemp -d)
mkdir -p "$demo_dir/live" "$demo_dir/mirror"
printf 'memory\n' > "$demo_dir/live/note.md"
cp "$demo_dir/live/note.md" "$demo_dir/mirror/note.md"
git -C "$demo_dir/mirror" init -q
git -C "$demo_dir/mirror" add note.md
git -C "$demo_dir/mirror" -c user.name=demo -c user.email=demo@example.invalid commit -qm 'plant: note'
test "$(git -C "$demo_dir/mirror" show HEAD:note.md)" = memory

External links

Exercise

Inspect a live directory you want to version. If tool-internal files appear in the source tree, draw a design with an external mirror and separate history store.
Hint
Assume the user-edited tree should contain no lock, object, or hook the user did not create.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.