DECISION NEEDED: unify stdin label conventions across lint/fmt/build — three conventions in four contexts affect the `--format json` wire format

[dean0x]

Background

As of PR #196, stdin input carries three different label strings depending on which subcommand and output format is in use:

Subcommand	Context	Label emitted	Where
mds build / mds check	diagnostics, source maps	<source>	build.rs:900, resolver.rs:199
mds lint -	diagnostics (human)	input.mds	lint.rs:652,661
mds lint - --format json	JSON "file" key	input.mds	lint.rs:652
mds fmt -	diagnostics, source maps	<stdin>	fmt.rs:148

Additionally, build.rs rewrites input.mds → <stdin> when constructing source maps, so the library-level constant (STRING_SOURCE_MAP_LABEL = "input.mds") and the CLI-emitted label (<stdin>) diverge on the same codepath.

Ledger IDs: #37 (primary), #12 (formatter.rs source sentinel dual meaning), #13 (sourcemap.rs:104 hardcodes source label)
Files: mds-cli/src/lint.rs:652,661; mds-cli/src/fmt.rs:148; mds-cli/src/build.rs:900; mds-core/src/resolver.rs:199; mds-core/src/formatter.rs:119; mds-core/src/sourcemap.rs:104
Originating reviewer: Consistency
Triage verdict: FIX_SEPARATE — "no surface produces a wrong result today, but the lack of a written rule is the root cause"

The tension

Three legitimate design arguments pull in different directions:

1. Library parity (input.mds): The library-level string-source path genuinely wants a label that looks like a filename — tools that accept MDS as a string and process it programmatically can identify the "virtual file" as input.mds. This is why STRING_SOURCE_MAP_LABEL was introduced in PR fix: v0.4.0 remediation — dogfooding blockers, bug batch, UX polish, docs sweep #196.

2. CLI stdin convention (<stdin>): UNIX tools conventionally use <stdin> (angle-bracket form) for standard input in diagnostic output and source maps. mds fmt already uses this; mds build/mds check use <source> (similar convention). A user piping cat prompt.mds | mds lint - expects <stdin>, not input.mds.

3. Wire format immutability ("file" key in mds lint --format json -): The JSON output contract commits to whatever label is emitted in the "file" field. Changing it after v0.4.0 is a machine-readable breaking change. Currently it would emit input.mds — a filename that does not exist on disk.

What must be decided before v0.5.0

Write a rule: what label does stdin carry, per context (diagnostics, source maps, JSON wire format), per subcommand (lint, fmt, build, check)?

Possible resolution:

• Option A (input.mds everywhere, align all CLI surfaces to the library): consistent, but <source>/<stdin> users break.
• Option B (<stdin> everywhere, align library label to CLI convention): consistent, but input.mds library consumers break.
• Option C (library uses input.mds; CLI remaps to <stdin> at the render boundary): maximally compatible, but adds a rewrite in every CLI emit path. build.rs already does exactly this — extend to lint and fmt.
• Option D (subcommand-specific): lint uses <stdin> for human output and input.mds for JSON (machine-readable consumers can tolerate a fixed virtual name); fmt/build/check use <stdin>. Documents the split explicitly.

Why deferred from PR #196

Three of the four conventions predate PR #196. The PR introduced input.mds on the lint path specifically because the library string-source path needs a stable virtual name. Writing a rule under release pressure risks churning the wire format with no time to validate cross-surface consequences.

The triage explicitly notes: changing the label in v0.5.0 is a breaking change to mds lint --format json - wire format. The cheapest time to settle this is now, before v0.5.0 ships. If the decision is Option C or D, the [Unreleased] CHANGELOG should note the current input.mds label on lint - as provisional.

Related

• mds-core/src/formatter.rs:119: SOURCE_SENTINEL = "" serves as both "no source provided" and "stdin" — same dual-meaning issue, same resolution.
• mds-core/src/sourcemap.rs:104: Hardcodes "input.mds" independently of STRING_SOURCE_MAP_LABEL — should reference the constant once the rule is written.
• Expose basePath on CompileOptions to match LintOptions #180: basePath alignment — both issues affect how the library vs CLI surfaces present virtual/stdin sources.

Deferred from: PR #196
Must resolve before: v0.5.0 (changing the JSON wire format after that is a breaking change requiring a major bump)

[dean0x]

CORRECTION (see follow-up below): the crates/mds-cli/src/formatter.rs:120 citation in this comment is WRONG — that file does not exist at 113f472. See #211 (comment) for the verified architecture. The ruling itself (uniform <stdin>) is unchanged.

DECISION RECORD — 2026-08-12: uniform <stdin> everywhere

Status: RULED (repo owner)

Decision

All four diagnostic contexts converge on the literal string <stdin>.

Surface	Location	Today	After
RETRACTED — build / check	crates/mds-cli/src/formatter.rs:120 (file does not exist — see correction)	<source>	<stdin>
lint	crates/mds-cli/src/lint.rs:682, :718, :727	input.mds	<stdin>
fmt	crates/mds-cli/src/fmt.rs:133, :136	<stdin>	<stdin> (unchanged)

The lint change includes the JSON "file" key, which is a published wire surface.

Rationale

input.mds is ambiguous because a real file can legitimately be named input.mds, so a JSON consumer reading "file": "input.mds" cannot tell stdin from a real file of that name. Angle brackets mark a pseudo-source unambiguously. <stdin> also matches what fmt already does. The project has effectively zero users and v0.4.0 is already a breaking release, so "least breakage" carries little weight while "right contract forever" carries a lot.

Breaking-change note

This changes a published JSON wire surface. It must be called out in the CHANGELOG under v0.4.0 as a breaking change for any consumer matching on the literal input.mds.

Options not taken

• Uniform input.mds everywhere
• A split core/CLI remap (different label per layer)
• Keeping all three conventions as-is

Downstream effect

This ruling unblocks #202 and #203. All three ship together in one PR, because they mutate the same lint JSON object.

[dean0x]

CORRECTION to the decision record above

Re: #211 (comment)

The ruling is unchanged — uniform <stdin> remains the decision. This comment retracts one bad citation from that record and adds architectural findings that materially change how the ruling gets implemented.

Retraction

The decision record cited crates/mds-cli/src/formatter.rs:120 as the build/check <source> site. That file does not exist. Verified at 113f472: the only formatter.rs in the repo is crates/mds-core/src/formatter.rs. The citation came from a stale brief and was passed through without verification.

The other citations in that record are correct and stand:

• crates/mds-cli/src/lint.rs:682, :718, :727 — the three sites passing mds::STRING_SOURCE_MAP_LABEL
• crates/mds-cli/src/fmt.rs:133, :136 — already pass "<stdin>"

Verified architecture

1. input.mds is not a CLI literal — it is a shared core constant.
STRING_SOURCE_MAP_LABEL is defined in mds-core and re-exported at crates/mds-core/src/lib.rs:73. Consumers:

• crates/mds-cli/src/lint.rs:682, :718, :727
• crates/mds-cli/src/build.rs:12 and :992
• crates/mds-wasm/src/lib.rs:69 (as DEFAULT_FILENAME)
• crates/mds-core/src/lib.rs:1219 (lint_source)

Changing the constant itself would move the WASM default filename too, so that is not the right lever.

2. The relabel-at-the-output-boundary pattern already exists.
crates/mds-cli/src/build.rs:973-993 already maps STRING_SOURCE_MAP_LABEL → "<stdin>" for stdin builds — documented in the rustdoc at :973-974, applied at :992-993.

3. Tests already enforce <stdin> on the source-map surface.
crates/mds-cli/tests/cli_source_map.rs:1048-1059 asserts that stdin sidecar sources[] must be <stdin> and must never be "input.mds" or "<source>" (AC-FUNC-12). See also :635-648 and :1193-1196.

Revised implementation direction

Extend the existing boundary relabel to the lint JSON and diagnostic paths rather than changing the core constant. The ruling decides the user-visible label; the existing architecture decides where the relabel happens. These are compatible — and roughly half the work is already done.

This also reconciles the ruling with what this issue's challenge analysis independently recommended (core keeps input.mds internally, CLI remaps at render boundaries). The disagreement was about the user-visible label, which is now settled as <stdin> — not about the mechanism.

Note for whoever implements this

<source> is a core-level sentinel, not a CLI one. It appears in crates/mds-cli/src/fmt.rs:443 and :451 (test helper calls) and is handled by core's map_source_label.

The live build/check <source> emission site must be located by the implementer — the retracted crates/mds-cli/src/formatter.rs:120 citation points at a nonexistent file, and no substitute line number is offered here rather than guessing one.

All file:line references in this comment are verified at 113f472.