The case study: how this family got built.

The family grew from five bundles and 231 smoke checks to twelve packages across one commit era - the Oct 3–6, 2026 stretch that ends at 5982aa8 - with roughly 800 checks across twelve suites as the final count. Every step of the way, the smokes were the arbiter: zero assertion changes across refactors, renames and a framework port. And every real bug - the shadowed patch layers, the silent journal open, the version guard that could only succeed once - was found live, not by the smokes. That asymmetry is the story's spine, and the sections below keep it honest: what the suites caught, what only a restart could catch, and which two theories died on the way to the truth.

The setup: three independent hooks - the package governor, the package pinner, the cargo governor - plus the dash normalizer, each carrying its own copy of the same machinery: ledgers, exclusion matching, policy loading, guarded writes, wiring, schemas. The decision (49e5b3d, 859f16a, 018919c): consolidate onto one factory service - 15 methods, one transform contract, and the ledger strings owned by the modules themselves. The technique: the Wire/Attach/ Continue seam trio, and a transform leaf the factory drives but never absorbs - each hook's transforms stay its identity. The outcome: five bundles green, 231 checks, and every ledger string byte-identical to pre-refactor behavior, smoke-asserted. The factory's page shows the seam table this era produced; it has since grown 15 → 16 → 17 methods as later phases moved machinery in.

Two live-verified fixes from this era never regressed since: a hook's inject and Config must sit on the loader's default export object, and apply must return nothing - a returned value silently kills event delivery. Both are the kind of bug no type checker sees; both were found with a restart and a missing ledger line.

A confirmation agent re-verified all five bundles and found three things that rewrote the queue. Each is a finding with a fix; none was visible from the passing smokes alone.

The rest of the queue executed in one session: the module terminology rename ( 3c29108 - mechanics only, the cargo flavor literal in the activation string stays), the standalone schema helper that deleted three config workarounds (060e3b6), the core extraction as a dependency-free pure package (1fef4ca), and the granularization splits (711d5b2 ). One operational beat worth keeping: the smoke suites lived in /tmp and were lost once - replayed from the session archives step by step, then archived to ~/.dsh/smokes/ forever after. The arbiter must not be disposable.

The first live battery exercised everything the smokes had proven: the governor + pinner interlock on one manifest write, the update stages as real jobs, the cargo's actual cargo upgrade with the full argv, the dash normalizer counting replacements in live streams. It also surfaced the first live-only failure: the harness's storage domain enforces one open per name, so the shared journal domain was single-winner per boot. At that boot only the pinner's records landed; the governor's and the cargo's silently never did - while the human ledger files remained the complete record, which is the only reason the loss was even noticed.

The fix, in two commits

The first successful open binds its handle on the factory instance ( 952eaa1), and every module's records route through it. The boot-window race came next (aa53c91): records journaled before any open completes now buffer in a capped, drop-when-full pre-bind queue and drain with their timestamps preserved - a three-stage routing of shared sink, pre-bind buffer, then per-state fallback. The third boot confirmed both live:

One boot's complete record set - the shared domain

Before the fix, that file showed one module's activations. After it, all four - and the interlock cascade and the dispatched update stage record themselves in the same place. The update stage's awaited promise resolves at the dispatch: the background job keeps running, and the caller never awaits the job.

The dash normalizer generalized. The core took over the pure machinery - generic over structural shapes, with no dependency on the host's LLM types: a fragile cross-bundle symlink workaround for a nominal-type clash was replaced by a durable design (98be27b, c2beb06). Five sibling flavors followed on the same template - quotes, ellipsis, spaces, invisible, fullwidth - each with its own ledger, activation line and count line (ad4c2c3, 68afdcd). Then the tool-args gate (1d827ad), and its three-way refinement (9d6e195): edit calls pass by identity - the old-string must match the real file bytes - and a per-call marker lets a single call opt out entirely. The marker is honestly stated: smoke-verified, but not reachable from the structured tool interface at the time; the practical per-call raw route is the edit exemption.

The stream, before and after

One beat belongs to the family's self-awareness: the system normalizes itself. The agents building the family saw their own comment prose come out with ASCII hyphens, because their output streams run through the same flavors. The planned cosmetic pass was cancelled by the user - em-dashes live only in the README examples, never in code. The workbench and the matrix pages run exactly these flavors live, and the workbench lets you watch the gate make its per-call decisions.

The raw-write tool landed first (bb9a6fd): a write wrapper with an explicit normalize parameter, exempt from stream normalization by name like edit, mirroring the built-in write's filesystem path so the governance hooks see its writes. Then the live tests showed its writes never triggered the governance chain - and the diagnosis took three rounds, two of them wrong. The emit-context theory: the event must be scoped to the emitting plugin. The listener-scope theory: the listener must be registered at the wrong level. The delivery research refuted both with code, simulation and live policy evidence: the event is delivered; the gate rejects the actor. The shared event bus has no scope filter on plain emits - the root registration fix aimed at the misdiagnosis was harmless, and stayed.

The real blocker: the patch layers

The deployed mutationTools value of all three governance bundles was [write, edit, str_replace_editor] - no raw-write - even though the schema default included it. The bundles' own patch layers set mutationTools explicitly, and a patch layer's config replaces the entry config wholesale, shadowing the default. The inspection tooling projected the schema, so the projected list looked correct while the live value was not - the verification blind spot in one sentence. The fix (affa730) was one line in three patch files, and it became the family's standing lesson about verifying the live effective config.

The journal migration that failed silently

The journal domain bumped to v2 to carry the stream counts (4c0e83b) - and every boot after it landed zero records. The v2 open failed against the v1 file on an exact-equality version check; the open's catch swallowed it; every record drained into a never-drained buffer and died with the process. The fix ( 756d566): a per-record layout that auto-migrates the v1 records, backup-and-skip for invalid ones, and a loud failure line on any open failure - because the silence is what made it undiagnosable.

Commonalization: three executors become one

The write-path audit found the built-in write, the raw-write tool and the factory's guarded write all implementing the same five steps, three times. The merge ( 91293d2): the factory's Write becomes the shared executor - the guarded write lives on as its alias - with the update envelope and the activation composer folded into the core the same pass. Then the fine-grained control (e69c5d3): normalize selects the transforms, govern selects the chain steps through the factory's Govern- the 17th method - and a step registry the modules populate. The governance marker (2c8764e, 83ba8e5) inverts the event path into a direct path: the raw-write's actor carries the govern selection, so direct governance is the only channel and no flag means no chain - the escape hatch.

The fold, and the guard that made it converge

The direct steps' detached chains raced - nondeterministic writes on the same file - so the fold awaits each step's chain before the next reads (d7a3c93, 140faa0). Then the deeper bug: every step wrote against the version observed at the triggering event, so only the first write could succeed and the later steps failed the stale-version check silently. The fix (5982aa8): the chain pass stats the target before its write and takes the fresh version, so the fold converges in any step order - which matters, because the pinner activated before the governor at the decisive boot. One more fix belongs to the Effect-TS port: the write executor originally mapped the caller's abort signal onto the run promise's options, so a pre-aborted signal interrupted the whole fiber and the caller saw all fibers interrupted without error instead of the Classic aborted-before-write behavior. The dash suite's pre-aborted-write scenario caught it; the fix drops the signal mapping - the signal forwards to the seams only, exactly the Classic semantics.

The final battery's outcomes, verbatim

The completed codebase became the boilerplate for two official releases off one source: the Classic implementation stays live-first, and the Effect-TS port ships only after its smokes prove parity - the ledger strings remain the contract in both (register #13). The release prep anonymized and de-personalized every bundle and rebuilt the READMEs on a single skeleton borrowed heavily from the sibling project's conventions. The Effect-TS mapping planned the parallel-govern toggle in from the start - concurrency is different there, and designing the toggle first beats retrofitting it. The naming inverted ( register #15): packages read as @-sentences - Hook @ DSH @ Governor @ Package - and group alphabetically by kind, role and domain, at version 0.0.1, one repository per package under submodule structure. And the Site you are reading is the last item: the integration showcase, with the versions page carrying the two engines side by side.

Every decision below survives in a shipped seam. The technique column names where it lives; the evidence column links the narrative to the commit era.

The state the era ended in: twelve packages, twelve green suites, a clean tree, the full live matrix passed - and a backlog of decisions already designed, waiting for the next era. The install command below is the whole family's front door.