hook-dsh-governor-cargo

Family position (the @-sentence Hook @ DSH @ Governor @ Cargo): a hook child of the plugin-dsh-factory service and the hook-dsh-core helpers; the Rust-sided sibling of the two npm governance hooks on the same fs/observed seam. One of three governance hooks, each gating on its own basename and writing its own ledger: governor-package (package.json → governor.log), pinner-package (package.json → pinner.log), and this bundle (Cargo.toml → cargo-governor.log, chain pass bare caret /=exact + cargo upgrade).

The basenames are disjoint: the cargo module never sees a package.json event and the npm plugins never see a Cargo.toml event. Composition semantics: chain > strip > normalize (this module's precedence), keep-list wins over normalization - never over the chain. Machinery-wise it is a factory flavor: gates, discovery, the guarded write, the refresh, the continuation, the effects, the schema and the namespaced UpdateKey come from plugin-dsh-factory; the policy loader and the suppression composer come from hook-dsh-core. This bundle keeps the Cargo-specific residue: the TOML identification, the surgical pin, the full-version directive, and the cargo upgrade bridge. Besides the fs/observed event path, its two steps are registered with the factory's direct-govern registry at apply (Factory.RegisterGovern("Cargo.toml", "cargo" | "update", ...)), so the raw-write tool's per-call govern selection can drive the same chain + normalization pass and update stage directly through Factory.Govern.

Rust manifests drift the same way npm manifests do - but Cargo.toml is a TOML document people decorate with comments, and there is no in-process library path: the only update tool is the cargo CLI. A governor for Cargo.toml must therefore rewrite surgically (never a TOML stringify) and delegate its update stage across the Rust/TS boundary - while still hooking the same fs/observed event the npm hooks use, so one trigger law covers the whole machine.

The same G1/G2 gates and Stash seeding as the npm governor; the G3 chain pass parses with smol-toml (IDENTIFICATION ONLY) and plans: 1. CHAIN - dep in registry.effectiveLatest → the bare resolved version (Cargo's implicit caret) or =resolved with pinStyle "exact", always the FULL form (shorthand padded); 2. STRIP - strict-mode unknown deps; 3. NORMALIZE - every other simple version (full-version directive below; the keep-list wins → byte-identical). The rewrite is a surgical line-level edit on the raw text - comments, inline comments, blank lines and spacing survive byte-for-byte - then GuardedWrite → ledger governed <path> → <version> → Refresh. The G4 update stage crosses the Rust/TS boundary:

The full-version normalization directive. No shorthand like "1.0" may remain in a governed Cargo.toml; every dependency version is expanded to its MOST SPECIFIC form:

The TOML rewrite: why comments survive. smol-toml (the ONE runtime dependency, carried by the bundle's own node_modules) is used for PARSING ONLY - identification of the dep entries in [dependencies], [dev-dependencies], [build-dependencies], [target.'cfg(...)'.dependencies] (and its dev/build variants), and [workspace.dependencies] (handled natively). Handled entry shapes: name = "0.3.4", name = { version = "0.3.4", ... } (single line or pretty-printed), [dependencies.name] table style. Never rewritten: path = "...", git = "...", and inherited entries (workspace = true). Non-dependency sections are NEVER touched; the refusal guard refuses any plan entry outside an identified dependency table, and Pin aborts (never a partial rewrite) if a planned entry cannot be located in the text.

The Rust side (live-verified). cargo 1.100.0-nightly + cargo-edit 0.13.13, resolved through cargoBin. --exclude is ONE flag per crate - the comma form is silently IGNORED, the exact inverse of ncu's one-comma-argument reject list. There is NO --exact flag in cargo-edit 0.13.13 - exact pins are enforced at the manifest level by the chain pass (pinStyle: "exact" → =resolved). cargo upgrade preserves comments and formatting (it edits via toml_edit). If cargo-edit is NOT installed, cargo upgrade exits 101 with no such command: upgrade - the module logs update: cargo-edit unavailable: ... and fails gracefully.

The exported Config schema validates and fills every default at load; new patch entries are declared with insert:. Full example:

Update-stage policy mapping (update-policy.json, same discovery as the npm governor): reject → --exclude <crate> (ONE flag per crate); allow → -p <crate> (repeatable); incompatible/pinned/compatible → --incompatible/--pinned/--compatible; pinStyle has NO CLI equivalent (manifest-level via the chain pass); verifyCommand runs after the upgrade via the subprocess seam, exit 127 non-fatal. The built-in default mirrors cargo upgrade's own semantics: no rejects, incompatible: "ignore", pinned: "ignore", pinStyle: "caret", no verifyCommand (never install implicitly).

One governed write. The author saves a Cargo.toml with comments, a shorthand version, and a chain-governed dep:

Before - the Cargo.toml as the author wrote it

With the nearest registry.json resolving tokio to 0.4.5, the surgical rewrite produces (same text, same comments, same inline spacing):

After - the same file, surgically rewritten

The transcript shows only what the author wrote; the ledger shows the pass:

The ledger lines for the same pass

Here the policy's chain deps plus rejects became one --exclude flag per crate; serde and tokio are protected from the CLI bump - tokio by the chain, serde by the normalization pass already writing its full form. Read the file back to see the governed state; write it again immediately and nothing complains - no FS_STALE_VERSION. Write inside node_modules/.git/.dsh and the ledger gains skipped (excluded) ... while the file stays untouched. Remove cargo-edit and the pass fails gracefully: update: cargo-edit unavailable: ..., the manifest untouched, the breaker counting the failure.

One global log (logFile, default ~/.dsh/hook-dsh-governor-cargo.log - SEPARATE from the npm ledgers) records activation, exclusions, chain-pass results, refusals, and every update-stage dispatch. The strings this module composes (the hook-dsh-governor-cargo: logger prefix is the factory's Append; each line is [<ISO>] <message> in the file):

The registry-miss line ends with an em dash followed by chain pass skipped; the DONE line is update: DONE + em dash + reason - byte-exact forms are in the In Action excerpt above. Those em dashes are part of the literal ledger strings, so they live only in the example block. The activation line is written by apply() - "did it activate" must be answerable from the ledger alone.

License: MIT. Full contract: SCHEME.md. TypeScript-first, built with @playform build (ESBuild + tsc type-check); the published artifact contains only the built output.