Breakpoints are bound for reading only, so setting one is still a bp command

[glslang]

The gap

Breakpoints are bound in one direction. DebugEngine::breakpoints() reads the engine's whole
breakpoint table through IDebugBreakpoint2 and fills in eleven fields — id, kind, address,
expression, command, thread, enabled, deferred, one_shot, pass_count,
passes_remaining — so every getter that matters is already called and already exercised.

Nothing writes any of them. What exists on the write side is dbgeng::Breakpoint, and it is:

• public and unused — Breakpoint::new has no caller in src/, examples/ or tests/;
• on IDebugBreakpoint, the v1 interface, where the read path uses IDebugBreakpoint2;
• missing every setter but SetOffsetExpression — no SetCommand, SetPassCount,
  SetMatchThreadId, no DEBUG_BREAKPOINT_ONE_SHOT, no DEBUG_BREAKPOINT_DATA;
• panicking in three of its four methods. enable, disable and remove each .expect(...),
  against the crate's own rule that a primitive returns Result<_, DbgEngError>. enable's message
  is a copy-paste of set_offset_expression's ("Failed to set breakpoint offset") for an AddFlags
  call, which is a fair sign of how much it has been used.

The private ScopedBreakpoint shows the shape that works — AddBreakpoint2 + SetOffset +
AddFlags(DEBUG_BREAKPOINT_ENABLED), with ManuallyDrop for the use-after-free that
RemoveBreakpoint2 otherwise causes — but it is hard-wired to run_to_address's one need: an
enabled code breakpoint at a resolved address.

So this is not new API surface to research. It is the symmetric half of a struct the crate already
fills in, and the hazard the awkward half of it hides (DbgEng owns the object; do not let the
generated wrapper Release() it) is already solved and commented in two places.

Why it matters to a caller

windbg-mcp's set_breakpoint runs bp <expression> as text, and pays for it three times.

• It is an injection surface. The command is built by interpolation, so the operand has to be
  screened by reject_command_breakers before it goes anywhere near the engine: DbgEng reads ; as
  a separator, and a double quote opens a breakpoint command string that WinDbg runs on every hit
  — so nt!Foo ".opendump other.dmp" would arm a target swap that fires later, outside any tool
  call. A typed setter takes the expression as a parameter. There is nothing to escape and nothing
  to screen.
• It has to be bounded. Bound every raw command, except the one an abort would damage windbg-mcp#271 gave EngineOp::SetBreakpoint a patience_ms
  because bp nt!Foo+0x10 makes the MASM evaluator resolve a symbol, and on a deferred module with
  a srv* path that is a symbol-server fetch with the session's engine held for all of it. See the
  open question below — this one may not go away, but it stops being about a command.
• The id has to be recovered by diffing. A successful bp prints nothing at all, so
  worker::set_breakpoint reads breakpoints() before and after and subtracts, with a documented
  degraded mode when the "before" read fails (BreakpointSet::listed: false, added empty because
  it is unknown rather than empty). AddBreakpoint2 hands back the object, and GetId is already
  bound. The whole diff, and the degraded mode with it, is answering a question the API answers
  directly.

And the reason recorded for the text path does not survive contact with the caller. It reads: "a
command rather than a typed AddBreakpoint because bp's syntax is the point: a condition, a
command string to run on each hit, /1 for one-shot". Two of those three are impossible to send
today — a condition and a command string both need a quoted string, and quotes are what
reject_command_breakers refuses. Only /1 survives, and it is one flag bit
(DEBUG_BREAKPOINT_ONE_SHOT). The syntax that justified the text hatch is syntax the tool does not
accept.

What would close it

Setters mirroring the getters breakpoints() already calls, on IDebugBreakpoint2, each returning
Result<_, DbgEngError> — offset or offset-expression, command, pass count, match-thread, the
enabled/one-shot flags, and DEBUG_BREAKPOINT_DATA for ba. Whether that is a builder, an
AddBreakpoint-with-a-spec, or repairs to Breakpoint is the design question; what it must not be
is a second lifetime story, since ScopedBreakpoint and Breakpoint already disagree about who
removes a breakpoint and when.

Breakpoint's three panics want fixing whatever shape is chosen, and if the type is superseded it
should go rather than stay as a public trap.

The open question, which decides how much this is worth

Does SetOffsetExpression resolve eagerly? BreakpointInfo::expression's own doc says a
breakpoint that resolved when it was set keeps its address and the engine no longer holds the text
— so bp resolves when it can and defers only when the module is absent. If SetOffsetExpression
does the same, the symbol-server block does not go away; it moves from an Execute a watchdog can
Ctrl+Break to a direct engine call nothing can, which is a regression in what a caller can
promise, and the same one #95 is about for read_memory.

Measure before building: set a breakpoint on a symbol in a module whose PDB is not in the cache,
through bp and through SetOffsetExpression, and time both. Three outcomes, three different
answers — if it defers, this is a clear win; if it blocks and SetInterrupt reaches it, the setter
wants a budget like execute_command_bounded's; if it blocks and cannot be interrupted, the honest
result is that this trades a bound for a cleaner API and the issue should say so out loud rather
than let a caller discover it.

Dependent change

In windbg-mcp, once the primitive exists:

• worker::set_breakpoint drops the bl before/after diff and the listed/listing_error
  degraded mode with it.
• EngineOp::SetBreakpoint's patience_ms (added in Bound every raw command, except the one an abort would damage windbg-mcp#271) is either passed to a
  bounded setter or removed — and if it is removed, set_breakpoint moves into the enumerated
  allowlist in worker::tests::every_unbounded_execute_in_this_worker_is_one_of_the_known_five,
  which is the test that will notice either way.
• reject_command_breakers on that tool becomes defence in depth rather than the only thing between
  a caller and an armed .opendump.
• ioctl_trace is the second consumer, and the one that needs SetCommand: it hand-builds
  bp <dispatch> ".printf \"IOCTL %08x …\", …; gc" with the escaping done by hand in a format
  string. That is the one place the "bp's syntax is the point" argument is actually true today,
  and a typed command parameter is what makes it stop being true.
• FOLLOWUPS.md item 2 asks for ba (data) breakpoints as a typed primitive; BreakpointKind::Data
  already exists on the read side, so the same work closes that half of it.

Found while closing FOLLOWUPS.md item 14 on glslang/windbg-mcp#271, where a review finding —
set_breakpoint running an unbounded command inside a typed op — led to reading why it runs a
command at all.

[glslang]

Measured: the open question is answered, and a claim this repo has been repeating is wrong

Short version. SetOffsetExpression does resolve eagerly and does block on a symbol-server
fetch — but SetInterrupt reaches it, so this is outcome 2 and a bounded setter is possible. The
symbol-server block does not become unbounded, and nothing has to be traded for the cleaner API.

There is a twist the issue does not anticipate, and a separate finding that changes the design: the
bp-deduplicates-a-resolved-expression behaviour recorded in windbg-mcp is real but is the
command layer's, not the engine's, so a naive typed migration silently starts producing duplicate
breakpoints.

Bench

x64 host, Windows 11 10.0.26200, dbgeng.dll/dbghelp.dll/symsrv.dll all 10.0.29547.1002
with msdia140.dll beside them, rustc 1.98.0. Target is a launched cmd.exe /c ping -n 60 127.0.0.1 stopped at its loader break. A scratch crate path-depending on dbgscope — no edits to
either repository.

Every timed arm is its own process with its own empty downstream store
(srv*<fresh-empty-dir>*https://msdl.microsoft.com/download/symbols), so no arm is fast because a
previous one warmed it. The first draft of this measurement ran lm before the timed section and
measured nothing: lm renders every module's symbol state and fetches what it needs to answer.

1. Does SetOffsetExpression resolve eagerly?

Yes, and it blocks. KERNELBASE!CreateFileW with the PDB not in the store:

arm	elapsed	resulting breakpoint
bp KERNELBASE!CreateFileW (execute_command_bounded)	2357 ms	enabled: true, expression: None
SetOffsetExpression("KERNELBASE!CreateFileW")	2620 ms	enabled: false, expression: Some(…), address: Some(…), deferred: false
same, SetInterrupt armed at 1500 ms	1638 ms, returned Ok(())	as above
SetOffsetExpression("nosuchmod!NoSuchSymbol")	0 ms	deferred: true, address: None

Warm, the same call is 6 ms. So the cost is the fetch, exactly as bp's is, and the two arms
are within ~11% of each other — this is the same work reached through a different door.

The last row is what DEBUG_BREAKPOINT_DEFERRED's documentation predicts: the flag is set "when the
offset of the breakpoint is specified using a symbolic expression, and the engine cannot evaluate
the expression". It tries first, every time.

The twist: the break is silent and lossy

SetInterrupt lands, which is the good news. What it does not do is tell the caller:

• the call returns Ok(()) — indistinguishable from a resolve that completed;
• the fetch is abandoned and the module is left on (export symbols) for the rest of the
  session. Here the address was still right only because CreateFileW is exported;
• engine.interrupted() reads true afterwards, and a following r rip answers in 0 ms — so the
  engine is healthy and the signal is recoverable, but only by a caller that looks;
• a second SetOffsetExpression on a different cold symbol immediately afterwards works normally
  (1204 ms), so nothing is poisoned.

This makes the return type the load-bearing decision. Written as Result<(), DbgEngError> — the
obvious signature, and the one Breakpoint::set_offset_expression already has — the migration
throws away both the bound and the evidence, which is precisely the regression this issue was
opened worrying about, arriving through the return type rather than through the API. The primitive
must answer with a report carrying cut_short: Option<Interruption>, clearing interrupt_raised
before and reading it after, exactly as execute_command_bounded does.

2. bp does not deduplicate. The command layer does, keyed by resolved address

windbg-mcp records in four places that "a resolved breakpoint is keyed by address, so repeating
one is a no-op". The observation is right; the attribution is wrong, and the difference decides
what a typed set_breakpoint has to do.

bl printed after every step, arms run in separate processes:

sequence	bl after	engine printed
bp ntdll!NtCreateFile ×3	1	breakpoint 0 redefined ×2
bp 0x7ffc9b880e10 ×3	1	same
bp <symbol>, bp <addr>, bp <symbol>+0	1	same — keyed by address, not by text
bu ntdll!NtCreateFile ×3	1	same, so it is not bp-specific
bp nosuchmod!SomeSymbol ×3	3	adding deferred bp ×3
SetOffsetExpression ×2 (typed)	2	nothing
typed ×2, then bp	1	breakpoint 0 redefined, breakpoint 1 redefined
bp, then typed	2	the typed call collapses nothing

So the engine has no dedup — consistent with both documentation pages, which say nothing about
duplicates at one offset — and bp/bu resolve first and then remove whatever is already at that
address, including breakpoints the API added. With no resolved address there is nothing to key on,
so deferred expressions pile up freely. That deferred row is not a corner case: bp HEVD!Foo before
the driver loads is the normal kernel workflow.

Duplicates stop once, and that is not the same as being harmless

Two enabled breakpoints at one address, then g:

• the target stops once, rip at the breakpoint address;
• the banner reads Breakpoint 0 hit and Breakpoint 1 hit — one int3, two breakpoint
  objects, both doing their bookkeeping;
• bc 0 afterwards leaves id 1 armed, so the address goes on stopping after the caller removed
  what it thought was its breakpoint.

Since a breakpoint's command runs when it is activated, two command breakpoints at one address
means two command strings per hit. For ioctl_trace — the consumer this issue names as the one that
needs SetCommand — that is two .printfs and two gcs per IRP: invisible in the stop, loud in
the log.

3. What this does to the design

BreakpointSpec needs an on_existing policy, and this is the correction to the plan rather
than a detail. A bare typed add would drop bp's collapse and start duplicating:

• Add — API-native, what the primitive does by default.
• Replace — resolve, remove what is at that address, add. What bp does, and what
  windbg-mcp's set_breakpoint and ioctl_trace take, so behaviour is preserved rather than
  quietly changed.

The gain is that the collapse becomes a value the caller is told about — replaced: [ids] —
instead of a breakpoint 0 redefined line printed into text nobody parses. It also makes the
deferred asymmetry statable instead of surprising: with no address there is nothing to replace, and
the report says so.

Breakpoint should go rather than be repaired, and the documentation is harsher about it than
the issue is:

• "When a breakpoint is created, it is initially disabled" — so Breakpoint::new +
  set_offset_expression yields a breakpoint that never fires. Measured: bl shows d. The one
  public write path in this crate today produces a dead breakpoint, and enable() — the method
  that would fix it — is one of the three that .expect(…).
• "When a breakpoint is first created, it has the memory location 0x00000000 associated with it" —
  so Breakpoint::new followed by the panicking enable() arms the null page.

Removal and enable/disable should therefore take an id, which is what the read side already
speaks, what bc takes, and what cannot dangle — leaving ScopedBreakpoint as the only owner of a
raw IDebugBreakpoint2, which satisfies "not a second lifetime story" by subtraction. One caveat
from the docs: "after the breakpoint has been deleted, its ID may be used for another breakpoint",
so an id-taking call must read the breakpoint back and confirm identity rather than trust a stale
id.

Two flags to leave out of the spec, deliberately. DEBUG_BREAKPOINT_DEFERRED is documented as
engine-owned — "This flag cannot be modified by any client" — so it is a read-back, never an
input. DEBUG_BREAKPOINT_ADDER_ONLY and DEBUG_BREAKPOINT_GO_ONLY are real and are not wanted:
one worker owns one engine client per session downstream, so a private breakpoint buys nothing.

No new windows feature is needed. IDebugBreakpoint2 in the pinned windows 0.62.2 already
exposes SetOffset, SetOffsetExpression, SetCommand, SetPassCount, SetMatchThreadId,
SetDataParameters, SetFlags, AddFlags and RemoveFlags.

4. One correction to BreakpointInfo's own documentation

BreakpointInfo::expression says a breakpoint that resolved "keeps its address instead and the
engine no longer holds the text, so None here is the normal case for a live breakpoint". That is
true of one set by bp and false of one set through this primitive: SetOffsetExpression keeps
the expression alongside a resolved address (deferred: false), as every typed row in the table
above shows. windbg-mcp's mirrored structured::BreakpointInfo carries the same sentence and its
renderer prints that column, so resolved breakpoints will start showing expressions there — a
rendering change worth making deliberately rather than discovering.

Plan

Unchanged in shape, with on_existing folded in: a BreakpointSpec (address or expression, kind,
command, thread, pass_count, one_shot, enabled defaulting true, SetDataParameters for
ba, and on_existing) configured through ScopedBreakpoint::at's existing
create-wrap-configure-remove-on-failure shape, bounded, returning the BreakpointInfo read back
through the getters breakpoints() already calls — what the engine holds, not what was asked for —
beside cut_short and replaced. Breakpoint deleted. The probe lands as
examples/breakpoint_probe.rs, and Miri gets dispatched by hand since it does not run on PRs and
this touches unsafe.

FOLLOWUPS.md item 2's ba half closes with it; write_virtual and register writes do not, so
that item narrows rather than closes.