fix(core,cli): enforce internal invariants in release builds (degrade non-boundary spans, assert skeleton/width/range/cursor invariants); path helpers fail closed on strip_prefix and non-UTF-8 paths; fmt non-UTF-8 exits 2 (#220, #217)

[dean0x]

Summary

Two independent hardening passes at the same boundary — "what does this code do in a release build when an internal assumption is violated?" — plus one exit-code correction.

1. Release-enforced invariants (debug_assert!-only invariants silently degrade in release builds (3 sites) — PF-005 #220). Ten debug_assert!/debug_assert_eq! sites were audited. Two are now degradations (a non-boundary import/@extends span offset yields a zero-length span instead of slicing source raw), and eight are now unconditional assert!/assert_eq! — the skeleton-block splice, the neutralize_source_for_render byte-length check, the three pub-API range checks, and the three evaluator source-map cursor checks. None of the ten can be tripped by template input; each is a compiler defect. The remaining 30 genuine debug_assert! invocations were each examined and deliberately kept.
2. Fail-closed path helpers (output.rs path helpers fail-open on strip_prefix edge cases and non-UTF-8 paths #217). Four host-path surfaces that failed open now fail closed: mds lint <dir>'s wire/sort key, the two source-map sources[] anchors, and two degenerate output-path joins. Plus a new warning when mds build/mds watch writes a source flat instead of mirrored.
3. mds fmt <file> on a non-UTF-8 path exits 2 (output.rs path helpers fail-open on strip_prefix edge cases and non-UTF-8 paths #217), not 1 — mds::io, matching mds lint and mds build. Directory mode is unchanged.

security/snyk (dean0x) is SCA-only for this PR — the Snyk MCP server failed to connect locally (ENOENT on a stale snyk-macos-arm64 npx cache path), so no snyk_code_scan ran; Rust is not scanned by Snyk Code here in any case.

What was wrong

• Sites 1 and 2 did not "silently degrade" in release — they panicked. This is the measured refutation of the issue's premise. attach_import_span (resolver.rs) and check_child_only_blocks (resolver/inheritance.rs) each had a debug_assert! that the offset was a char boundary, followed one line below by a raw slice of source. In a release build the assert compiles away and the slice runs. The RED release run produced, verbatim:

  resolver.rs:2518  start byte index 1 is not a char boundary; it is inside 'é' (bytes 0..2 of string)
  resolver.rs:2518  start byte index 1 is out of bounds for string of length 0
  inheritance.rs:83 (the same two, same two inputs)
  

  So the pre-existing release behaviour was a panic with a message naming a byte of the user's source, not a degraded span.

• Site 3 genuinely was a silent fallback, and the worst of the ten. The skeleton-splice walk had debug_assert!(false, …) in the "no effective-blocks entry for this @block" arm and then spliced the base default. In release that silently drops a child template's @block override and emits the parent's content — wrong output, no diagnostic, no exit code.

• Three more sites were promoted because their release fallback was also unsound rather than merely cosmetic: the neutralize_source_for_render byte-length check (a width mismatch desynchronises every following span offset, so miette renders carets against the wrong columns), and the three pub-API range constructors (TextEdit::new, FixLineSpan::range_inclusive, range_exclusive), where a release caller passing a reversed range got a value the fix planner later skipped in silence.

• relative_display failed open on both the wire key and the sort key. mds lint <dir> built each files[].file value with a strip_prefix(root).unwrap_or(path) plus to_string_lossy. An entry not under the lint root emitted an absolute key; an entry with a non-UTF-8 component emitted a lossy key (U+FFFD). The same string is the sort key, so the directory ordering was affected too.

• Empty-root containment was vacuous. relativize_source's containment test is starts_with_comps(source_comps, root_comps). path_to_unified returned String, so an empty or unusable root became an empty component list — and starts_with_comps(x, []) is vacuously true for every x. Result: every source-map sources[] entry would be treated as "inside the project" and emitted as a host-absolute path minus its leading /.

• A non-UTF-8 root became a lossy anchor. NativeFs::source_root() used display().to_string(), so a root directory that is not valid UTF-8 produced a string ending in U+FFFD and was then compared, byte-wise, against real path components. It never matched, but it was still being used as an anchor.

• Two stem-less joins could escape the out-dir. Both Dir(_)-mode output oracles fell back to source.as_os_str() when file_stem() was None. d.join(<absolute>) re-roots: output_base_no_ext(Path::new("/"), "/root", Dir("/out")) returned "/", and output_path_for then built "/.md" — outside the out-dir entirely.

• The watch ghost-prune collided on file name. Pruning a vanished out-of-root dependency called the full DirWatchState::forget, which probes and removes the output path. For an out-of-root ghost the probe resolved through the flatten arm to <out>/<name>.md — the same path an in-root source with that file name owns — so the prune dropped the in-root source's write-dedup entry.

• mds fmt exited 1 on an undecodable path where mds lint and mds build both exited 2, and the fmt module doc already claimed 2.

Design

• Degrade at sites 1 and 2; do not assert. Both compute an underline length for a diagnostic that is already being constructed — the import failure or the stray-node error is the real payload, and the span is cosmetic. Panicking would replace a useful error with a crash, which is strictly worse for the user than a zero-length span. An in-tree helper, line_len_at, already had exactly the char-boundary-safe semantics (it backs build_type_mismatch), so both sites now route through it. One degradation rule, one helper, one test group — rather than a second hand-rolled boundary check at each site.
• A real predicate at site 3, not assert!(false). Site 3 has no safe fallback value: splicing the base default is wrong output. The promotion is an assertion on the map lookup itself, so the check reads as the invariant it enforces rather than as an unreachable marker in an else-branch.
• No user data in any of the eight messages. The CLI installs no panic hook, so a tripped invariant prints Rust's default panic message straight to stderr — bypassing the WIRE sanitizers (safe_path, safe_inline) that every other CLI output path is forced through by print_discipline. Interpolating source text or a path into an assert message would route unsanitized bytes around that guard. All eight messages therefore carry static text and integers only.
• Option, not a sentinel, for source_root / path_to_unified. The bug being closed is a sentinel bug: the empty string is a valid prefix of every path, so "" as "no anchor" makes containment vacuously true. Option<String> makes "not an anchor" unrepresentable as a prefix — the choke-point must decide what None means at step 6b, and the compiler forces both branches to be written. An unusable root means "not contained" (basename); an unusable base means "anchor on the root".
• The flatten warning lives in the write oracle only. output_base_no_ext is a probe — watch calls it many times per batch to compute candidate paths for stale-output cleanup and dedup bookkeeping, for paths that may never be written; reporting there would emit the warning repeatedly for one logical event. output_path_for is called once per actual write. T-P16 pins both halves (present in the write oracle, absent in the probe oracle), so neither half is vacuous — and P-M7/P-M7b confirmed each half fails independently.
• The lint pre-pass is not ?. run_lint_directory computes every display path into a Vec<(PathBuf, String)> before sorting, and on the first Err routes it through emit_analysis_failure_json_or_stderr and exits — rather than propagating. Two reasons: the emit-before-exit ordering rule means a bare ? would let the caller's blanket catch exit 2 without writing the JSON envelope; and failing before any file is linted is what keeps a partial files[] array from being emitted alongside the error.
• Root / is deliberately unchanged. path_to_unified("/") is Some("/"), which normalizes to an empty component list legitimately — / really is a root and every absolute path really is under it. The fail-closed rule therefore keys on "could not produce an anchor" (None), never on "the component list is empty". Collapsing those two would change behaviour for a real, reachable root.
• error.rs's at() canary stays debug-only, and that is load-bearing. It is the mechanism that lets sites 1 and 2 degrade: the tests expect the debug run to panic with MdsError::at(): cross-source offset mismatch and the release run to return span: Some((1,0)), src: None. Promoting it would make the release branch panic — undoing this PR's degradation and re-creating the debug_assert!-only invariants silently degrade in release builds (3 sites) — PF-005 #220 failure one layer up. Recorded as M11 (reasoned, deliberately not performed).

Behaviour changes

#	Change	Tests
(a)	TextEdit::new, FixLineSpan::range_inclusive, FixLineSpan::range_exclusive panic on a reversed range in release as well as debug. Public API; rustdoc # Panics added. No in-tree caller constructs one.	T-E1..E4
(b)	A @block placeholder with no effective-blocks entry now panics in release instead of splicing the base default.	T-C1
(c)	A neutralize_source_for_render byte-width mismatch now panics in release instead of desynchronising span offsets.	T-D1
(d)	The three evaluator source-map cursor checks are enforced in release.	T-F1
—	On the CLI (b)/(c)/(d) surface as a Rust panic, exit code 101. The napi, WASM and Python bindings catch it at the FFI boundary and convert it to mds::internal, unchanged.	—
(e)	mds lint <dir> with an unnameable entry fails the whole run before any file is linted (was: per-file error with a lossy/absolute key, rest of the tree still linted). Exit code is unchanged at 2; the message text is unchanged.	T-P4
(f)	mds fmt <file> on a non-UTF-8 path exits 2 (mds::io), was 1. Directory mode unchanged (exit 1 via the N failed tally).	T-P6
(g)	mds build/mds watch --out-dir prints a warning when a source is written flat instead of mirrored. Not gated on --quiet. No walked source can reach it — it is a tripwire, not user-facing advice.	T-P16
(h)	Degenerate stem-less sources now produce <out>/output.<ext> instead of / and /.md. Unreachable from the CLI; a real change to the pure functions.	T-P15
(i)	mds watch no longer probes output paths when pruning a vanished out-of-root dependency, so it can no longer drop an in-root source's write-dedup entry.	T-P19
(j)	Source-map anchors: zero change for every UTF-8 root. Not reachable from the CLI or the public API today (non-UTF-8 entry paths are rejected before compilation) — closed as a latent hazard.	T-P20; goldens 304/304, Python 250

Nothing moved in any golden. @mdscript/mds's source maps (U-SM), source maps — WASM backend (W-SM) and source maps — compileFile differential (CF-SM) suites are green against a freshly rebuilt native addon and a freshly rebuilt crates/mds-wasm/pkg — the addon must be rebuilt first or the harness loads a stale mds-napi.node and silently exercises the old binary. Python parity: pytest -m "not perf" → 250 passed. WASM is structurally unaffected in any case: VirtualFs::source_root is the trait default None, so the WASM path never reaches step 6b, and an empty base is unreachable from the CLI because compute_source_map_base absolutizes on every branch.

Evidence

Commits — RED → GREEN per pair

#	SHA	Scope	RED observation
1	ad23019	#220 RED: 15 tests	dev 6 passed / 9 failed; release --list 14, 6 passed / 8 failed
2	9e23488	#220 fix	dev 15/15; release 14/14
3	12b3408	#217 lint RED	T-P1 both arms returned Ok of an out-of-root key; T-P2 returned Ok of a U+FFFD key
4	dd54b82	#217 lint fix	both Err; controls Ok
5	7e9a5fe	#217 anchors RED	T-P7/T-P8/T-P11 leaked the host path minus its leading /; T-P12 returned Some(…U+FFFD)
6	d73cf2f	#217 anchors fix	basename / None; controls unchanged
7	a10a7bc	#217 CLI RED	T-P15 output_base_no_ext("/", "/root", Dir("/out")) → "/"; T-P16 no report in output_path_for; T-P19 last_written lost the in-root entry
8	0be5e56	#217 CLI fix	/out/output, report present, in-root entry kept
9	aae35a9	#217 fmt RED	forced-branch run: EXIT=1
10	f4707d7	#217 fmt fix	forced-branch run: mds::io, EXIT=2; directory mode still EXIT=1
11	e1a69d0	docs (this commit)	—

Note on 9/10: macOS APFS rejects touch $'\xff\xfe.mds' with Illegal byte sequence (EILSEQ) — the kernel enforces valid UTF-8 in filenames; Linux ext4 does not. The on-disk hostile arms of T-P4, T-P5, T-P6 and T-P13 therefore return early here and first execute on Linux CI. Local evidence for those arms is the forced-branch technique: the success path of the decode was temporarily forced to None, the real binary rebuilt, run end to end, and reverted. Each test's control arm runs unconditionally on every unix platform, and on any non-macOS unix a failed hostile create panic!s rather than skipping, so a filesystem that should accept the name can never masquerade as a skip. No #[ignore], no A || B assertions.

G1 — release-profile verification (not run by CI)

ci.yml runs cargo test --workspace in the dev profile only, so nothing in CI would have caught any of the eight promotions or the four degradations. G1 is a local gate:

cargo nextest run -p mds-core --cargo-profile release --lib -E 'test(/…/)'

Plain form; no CARGO_PROFILE_RELEASE_LTO=false override and no [profile.release-test] were needed. At this commit: 14 listed, 14 passed, 1 154 skipped, 29.35 s wall (list + release compile + run).

G2 — evaluator cost gate (the three cursor asserts fire per output node)

Fixture big.mds: 180 000 × Hello {{name}} \{{ tail text = 5 220 020 B → 4 500 020 B output, 3 600 083 B map. /usr/bin/time -p <bin> build big.mds --source-map -o out.md, release binaries built at ad23019 (production code then byte-identical to main) vs 9e23488.

run	before (s)	after (s)
1	0.24	0.69 †
2	0.21	0.21
3	0.22	0.21
4	0.21	0.22
5	0.21	0.21
median	0.21	0.21

† first touch of a freshly copied binary; does not recur.

Round 2 (independent repeat), wall/user: before 0.21/0.16 ×5, after 0.21/0.16 ×5 — medians identical. Noise control ×3 each without --source-map (the asserts are unreachable): median 0.17 both. Higher-resolution supplement (320 000 lines, 9 280 020 B, 960 000 segments — just under MAX_SOURCEMAP_SEGMENTS = 1 000 000): median wall 0.29 → 0.30 (ratio 1.034), median user 0.22 → 0.22.

Threshold median wall(after) ≤ 1.05 × median wall(before) → 0.21 ≤ 0.2205. PASS on two independent rounds (ratio 1.000). No revert; the three evaluator assert_eq!s stay.

G3 — WASM size

Measured with CI's own commands (wasm-pack build crates/mds-wasm --target nodejs --out-dir pkg / --target web --out-dir pkg-web) — not npm run build -w @mdscript/mds-wasm, which writes packages/mds-wasm/dist/{node,web} and leaves crates/mds-wasm/pkg stale.

tree	pkg/mds_wasm_bg.wasm	pkg-web/mds_wasm_bg.wasm
main production code (33380d7)	850 313	850 313
after #220 (phase 1)	850 971	850 971
this branch (e1a69d0)	851 728	851 728
delta vs main	+1 415 (+0.166 %)	+1 415 (+0.166 %)

The #220 work accounts for +658 B and the #217 mds-core changes (source_path.rs's Option return and step 6b, fs.rs's source_root) for the remaining +757 B. The #217 CLI work contributes nothing — mds-cli is not compiled into the WASM artifact.

Local uses wasm-pack's cached wasm-opt v117, not CI's pinned Binaryen v129, so only the delta transfers; the CI byte count is the authoritative one. Local sits 6 865 B above the CI-measured 843 448 at 33380d7 — inside the known 3–7 KB local/CI offset. Projected CI ≈ 844 863 B, ≈ 5 137 B under the 850 000 guard. .github/workflows/ci.yml and the guard were not touched.

Flake screen

cargo nextest run -p mds-cli --test cli_watch --no-fail-fast, three sequential runs on the green tree: 80/80 each time (4.536 s / 4.440 s / 5.069 s). Zero failures, zero skips, zero leaky. No timeout, sleep, debounce, serialisation or ordering change was made anywhere in watch.rs.

Mutation testing — #220 (M1–M11)

id	mutation	observed
M1	restore debug_assert! + raw slice at site 1	T-A1, T-A2, T-L1 FAIL; T-A3 passes
M2	same at site 2	T-B1, T-B2, T-L1 FAIL; T-B3 passes
M3	degrade inline instead of via line_len_at at site 1	T-A1/A2/A3 all PASS — behaviour identical; only T-L1 catches it. WEAK, purely lexical — renaming the helper would break it with no behaviour change
M4	site 3 back to debug_assert!(false) + fallback	T-C1 + T-L1 FAIL; T-C2 passes
M5	TextEdit::new message interpolates ({start} > {end})	T-E1 still PASSES (the expected string is a substring); only T-L1 catches it
M6	neutralize back to debug_assert_eq!	T-D1 and the bidi test both still PASS (parity really does hold); T-L1 only. WEAK
M7	TextEdit::new back to debug_assert!	dev: T-E1 PASSES — a demotion is invisible to a dev-only CI; release: T-E1 FAILS; T-L1 FAILS in both. The single best argument for keeping T-L1
M8	EscapedBrace cursor assert back to debug_assert_eq!	T-F1 still PASSES; T-L1 only. WEAK
M9	reword the site-3 message	T-C1 FAILS (substring) + T-L1 FAILS
M10	delete the #220 justification comment above the neutralize assert	T-L1 only
M11	(reasoned, not performed) promote error.rs:175	would make T-A1/T-B1's release branch panic — i.e. undo the degradation. Deliberately not done

Three mutations (M3, M6, M8) are caught ONLY by the lexical shape test T-L1 (crates/mds-core/tests/assert_promotions.rs). That test is load-bearing, not a style guard: with CI running dev-only, it is the sole detection for a silent assert! → debug_assert! demotion (M7).

Mutation testing — #217 (P-M1 … P-M12)

id	mutation	observed
P-M1	strip_prefix(root).unwrap_or(path)	Survived the first attempt. With only the absolute arm, /other/x.mds is still rejected — by the Component::Normal guard, not by the strip. A relative out-of-root arm was added to the RED commit; the mutant then dies
P-M2	to_string_lossy reintroduced	T-P2 fails, reporting a two-U+FFFD key
P-M3	pre-pass → per-file lossy key	Not observable on macOS; the forced-error run is the local stand-in (envelope + exit code + absent summary line)
P-M4	path_to_unified(root).unwrap_or_default()	T-P7, T-P8, T-P11 all fail with the host path minus its leading /; T-P9/T-P10 correctly stay green
P-M5	unusable base → empty component list instead of None	T-P9 stays GREEN, as predicted. Behaviour-preserving for the tested paths — step 9 already asks whether the base is inside the root and an empty list fails that length check. Documented rather than pinned with an implementation-detail test
P-M6	source_root back to display().to_string()	T-P12 fails with Some(…U+FFFD)
P-M7	report moved from output_path_for into output_base_no_ext	T-P16 fails on the positive half
P-M7b	report present in both oracles	T-P16 fails on the negative half — so neither half is vacuous
P-M8	safe_path dropped, value hoisted into a local	print_discipline fails: output.rs:334: eprint_warning(format!) interpolates unsanitized
P-M9	Err-arm unwrap_or(source.as_os_str()) reintroduced	T-P15 fails, left "/" right "/out/output"
P-M10	watch gate forced to if true	T-P19 fails, last_written reduced to the out-of-root key
P-M11	fmt back to miette::miette!	EXIT=1 (the pre-fix forced-branch reading)
P-M12	warning gated on !quiet	NOT PERFORMED — named weakness. T-P16 pins the report's lexical presence inside fn output_path_for(, so an if !quiet { … } wrapper would still pass. output_path_for has no quiet in scope, so the mutation is unreachable without a signature change (out of scope) — but the test's weakness is real and recorded rather than papered over

Every mutation above except P-M12 and M11 was applied, observed and reverted. Post-revert greps for if true {, src_display, filter(|_| false) and TEMP-OBSERVE returned zero hits before each commit.

The 30 debug_assert! sites that deliberately stay

A naive git grep -nE 'debug_assert(_eq|_ne)?!' over crates/*/src returns 71 lines / 60 macro-looking hits, but only 40 are real invocations — the other 20 are prose in doc and inline comments that mention the macro (several of them explaining why a debug_assert! was deliberately not added there). The 40 real invocations are exactly 2 degraded + 8 promoted + 30 kept; 0 were unlisted. 39 are production, 1 (lint/fix.rs:1206) is inside a #[cfg(test)] mod tests and never compiles into a release build at all.

site	invariant	why it stays
mds-cli/lint.rs:1488	clean+warn+error+limit counts sum to files.len()	a miscount mis-renders one summary line; all four counters are derived in the pass directly above
mds-cli/output.rs:279	computed output path must not escape the out-dir	its release fallback is already contained (base/<stem>.<ext>), so a release check would guard nothing
mds-cli/watch.rs:1476, :2498	merged last_mtimes equals the pre-compile snapshot	mtime bookkeeping; a violation costs one redundant rebuild, never a wrong or lost write
mds-core/error.rs:175	at() cross-source span in bounds / on a boundary	load-bearing debug-only — promoting it undoes this PR's degradation (M11)
evaluator.rs:960, :977	And/Or operands are leaves	guaranteed by the parser's same-level flattening; per-node in the evaluation loop
evaluator.rs:1005, :1432	elseif_branches.len() <= MAX_ELSEIF_BRANCHES	the bound is already enforced by the parser with a real error; these are redundant self-checks in a loop
formatter.rs:312, :359, :376	body-start / span-ordering / cursor char-boundary	the formatter's compile-equivalence safety gate refuses to write on any bad output, so the release failure mode is a refused format, not a corrupt file
lexer.rs:181	scan_code_content requires code_fence.is_some()	call-order precondition of a private fn with one caller directly above
lib.rs:720	RESERVED_OUTPUT_KEYS contains type and imports	const-table self-check; can only fail if the table is edited, which a test covers
lint/fix.rs:618, :653, :660, :664	plan not overlap-rejected; edit in bounds; both offsets on boundaries	apply_plan_unchecked is the explicit bypass; the production path is apply_fixes_incremental, which validates with real runtime checks
lint/fix.rs:1206	test-fixture offset points at @import	inside #[cfg(test)] mod tests — not in any release build
options.rs:144	unknowns slice non-empty	precondition on a slice the single caller builds from a non-empty iterator
parser.rs:76, :91	guard depth > 0 before decrement in Drop	per-node in the hot parse loop; underflow would only affect a limit counter
parser_helpers.rs:641, :865	op.len() == 2; names.len() == name_offsets.len()	both established by construction two lines above
resolver.rs:1654	skeleton entry's prompt_body is None	self-check immediately after the binding it checks
sourcemap.rs:775, :786	display_names.len() == sources.len()	parity established by construction at both insertion points
sourcemap.rs:827, :886	segments.len() <= MAX_SOURCEMAP_SEGMENTS	the cap has real runtime handling (segments_dropped); these fire per segment in the compiler's hottest loop — G2 measured the cost of promoting three siblings in that same loop
mds-wasm/lib.rs:80	Reflect::set succeeded	cannot fail on a fresh object; the release fallback skips one property of a diagnostic

Other counts

• T-D1 real hit count: is_control_char claims exactly 78 codepoints (30 C0 + DEL + 32 C1 + U+061C + 14 three-byte format hazards). The planned pin of 78 was correct. T-D1 also asserts width parity and actual substitution for each of the 78.
• line_len_at stays private and unchanged. parser.rs's directive_line_len was deliberately not unified with it (see limitations).

Gates at e1a69d0

gate	result
cargo fmt --all --check	clean
cargo clippy --workspace --all-targets -- -D warnings	clean
cargo clippy -p mds-cli --all-targets --features startup-race-probe -- -D warnings	clean
cargo nextest run -p mds-core -p mds-cli	2 352 passed, 0 skipped (mds-core 1 465, mds-cli 887, each also measured on its own). The combined run reports 1 leaky — a passing test that left a handle open, which nextest flags but does not fail; both single-crate runs report 0 leaky
G1 release-profile subset	14/14, 29.35 s
cargo test --workspace (CI's command)	green — every target test result: ok, 0 failed
cargo test --doc -p mds-core	53 passed
cargo +1.88 check -p mds-core -p mds-cli	clean
RUSTDOCFLAGS="-D warnings" cargo doc -p mds-core -p mds-cli --no-deps	clean
WASM pkg/pkg-web mds_wasm_bg.wasm	851 728 B local; projected CI ≈ 844 863 B (guard 850 000)
npm test --workspaces on a rebuilt native addon	598 pass / 0 fail — @mdscript/mds 304/304 (the source-map goldens), mds-napi 115, bundler-utils 91, rspack 26, vite 24, webpack 21, rollup 17
node scripts/verify-no-control-bytes.mjs	clean — 563 files, 6 819 578 bytes
node scripts/verify-versions.mjs	clean — 8 packages + 4 crates at 0.4.2
npm run test:gates	212 pass / 0 fail
decision-ledger ids in added lines	none added (one pre-existing id rides a rewrapped doc line)
release-surface path diff	empty

Known limitations / out of scope

• No CLI panic hook / catch_unwind. A tripped invariant on the CLI is a raw Rust panic: exit 101, default panic message, and in mds watch it takes down the watcher. A hook that renders mds::internal and a catch_unwind around the watch rebuild loop are a follow-up; they were not added here because the panic message content is already constrained (no user data) and adding a hook changes the failure presentation of every existing panic site at once.
• Exit-code asymmetry is intentional but unlovely: CLI 101 vs mds::internal (exit 1) through napi/WASM/Python. Same defect, two presentations.
• SECURITY.md ~:83 is inaccurate and was left alone. It says mds-core exposes the debug-panics feature; in fact only the three binding crates do. Out of scope for a debug_assert!-only invariants silently degrade in release builds (3 sites) — PF-005 #220/output.rs path helpers fail-open on strip_prefix edge cases and non-UTF-8 paths #217 docs commit — recorded here, not fixed.
• Lint granularity changed (not the exit code): a single unnameable entry now fails the whole mds lint <dir> run instead of being one per-file error among many. This is the fail-closed behaviour the issue asked for, but it does mean one bad filename hides the findings of every other file in the tree.
• Remaining host-path sinks are a follow-up, deliberately not closed here: build.rs's SMv3 file label (lossy), fmt.rs's raw display() as a diagnostic file name, lib.rs's stem-less label, lint.rs's <file> sentinel, the two current_dir() fallbacks (canonicalize_out_dir still fails open — a relative --out-dir anchors at "."), and watch.rs's graph_key fallback. Turning an infallible helper fallible changes every caller, which is why canonicalize_out_dir was scoped out.
• directive_line_len (parser.rs) was not unified with line_len_at. Two helpers with near-identical semantics remain.
• The 850 000-byte WASM guard was not raised. The +658 B delta leaves ≈ 5 894 B of projected headroom; raising the guard would be a separate, deliberate decision.
• O_NOFOLLOW on the write fd is still deferred (carried over from fix(cli): atomic mds build/watch outputs and .map sidecars via atomic_write_file (removes the spurious metadata warning); empty directory exits non-zero; atomic_write_file contract documented (#227, #225, #204, #226) #385).
• P-M12 and the T-L1 lexical checks are named weak spots, documented above rather than silently accepted.
• The on-disk hostile fixtures for T-P4/T-P5/T-P6/T-P13 have never executed. Their first real run is this branch's Linux CI job. If one fails there, the failure is in the assertion, not the implementation — the forced-branch runs already exercised each end to end.

Review observations (self-review, non-blocking)

• The promoted TextEdit::new / FixLineSpan::range_* checks guard the constructor path only; in-tree lint rules build these types with struct literals (e.g. lint/rules/legacy_interpolation.rs, rules/empty_block.rs, rules/unreachable_branch.rs, rules/unused_function.rs, lint/fix.rs) and bypass the checks — a pre-existing gap the debug_assert! shared; the promotion is not broader than the constructors.
• The flatten warning's text is never rendered end-to-end by a test (unreachable from any walked tree); its presence is pinned lexically (flatten_warning_lives_in_the_write_oracle_only) and its absence is asserted in dir_build.rs with a non-empty-stderr control.
• Release-profile behaviour has no recurring CI gate: the degrade/promote tests branch on cfg!(debug_assertions), so CI executes the debug arm; the release arm rests on the local release-profile run (14/14) plus the lexical guard in tests/assert_promotions.rs.
• source_path.rs's property table does not pin the relative-source × unusable-base combination (the case whose anchor changed from basename to root); behaviour is safe (apply_relative still rejects an escape above the root anchor) and unreachable from the CLI and bindings.
• .devflow/features/mds-lint/KNOWLEDGE.md says "the other 11 format hazards" where is_three_byte_format_hazard covers 14 — pre-existing wording next to an edited line; the 78-codepoint non-vacuity pin uses the real count.
• spliced_regions keeps an if let Some after the assert!; removing the assert later would silently reinstate a drop-the-region path — residual shape, deliberate under the pinned macro form.
• The new Io messages interpolate the raw root and entry paths (path escapes lint root {root}: {path}), byte-identical in shape to the pre-existing read_source_file rejection; belongs with the path-sink follow-up inventory.
• canonicalize_out_dir still falls back to . when current_dir() fails — documented in place, deferred to the path-sink follow-up.

Changes

crates/mds-core/src

• resolver.rs — site 1 degrades via line_len_at.
• resolver/inheritance.rs — site 2 degrades via super::line_len_at; site 3 unconditional assert! + # Panics rustdoc.
• lint/diagnostic.rs — neutralize_source_for_render assert_eq!; TextEdit::new / FixLineSpan::range_inclusive / range_exclusive assert! + # Panics.
• evaluator.rs — three source-map cursor assert_eq!.
• sourcemap.rs — MapBuilder cursor-invariant rustdoc.
• source_path.rs — path_to_unified → Option<String>; step 6b "Anchor validity"; module # Security invariant.
• fs.rs — NativeFs::source_root uses to_str; FileSystem::source_root # Contract.
• resolver_tests.rs — line_len_at test group (+ header note).
• tests/assert_promotions.rs — new, the T-L1 shape test.

crates/mds-cli/src

• lint.rs — relative_display → Result<String, MdsError>; display-path pre-pass before the sort; LintDirCtx.lint_root removed; per-file helpers take display_path: &str.
• output.rs — new MirroredStem + mirror_stem; the flatten report in output_path_for only; two unwrap_or(source.as_os_str()) fallbacks → OsStr::new("output").
• watch.rs — forget split into forget_graph + forget; ghost-external-dep prune gated; three invariant comments at the output_path_for call sites.
• fmt.rs — undecodable-path arm is MdsError::Io.

Tests — crates/mds-cli/tests/{cli_lint.rs, dir_build.rs, cli_fmt.rs}.

Docs — CHANGELOG.md, spec.md (§7.2, §7.5, §7.9), SECURITY.md, and four feature KBs under .devflow/features/.

Related Issues

Closes #220
Closes #217
Refs #69 #196