feat(stream_inspect): adopt the capability #352 asked about, not upstream's implementation

[PYDuquesnoy]

Issue 352's four-tool profile decision: one adopt, two declines with measured reasons, one premise
correction. Stacked on #375, which created the file the decisions are recorded in — base it on
master after that merges.

iris_coverage — already adopted; the premise is stale

352 says all four are "absent from our 23". iris_coverage is in INTEROP_TOOLS and has been since
it was added after the issue was filed. Nothing to decide.

stream_inspect — ADOPT, precondition verified first

352 makes adoption conditional on one thing: "confirmed non-consuming before adoption". Measured on
IRIS 2026.1 against a throwaway %Stream.GlobalCharacter (probe class deleted afterwards):

step	result
instance A: Read(100), then again	"line-1", then "" with AtEnd=1
instance B: a fresh %OpenId on the same id, after A hit AtEnd	Size=6, Read → "line-1"
instance C: read .Size first, then Read(100)	6, then "line-1"
instance A again	still "", still AtEnd=1

Read position is per-instance and never saved, and reading Size advances nothing. Precondition
met.

It also corrects the issue's framing. 352 wants an answer to "is the stream empty, or already
read?" — but since position is never persisted, "already read" is not a state a later reader can
observe. A stream a relay consumed to the end still reads from the start for the next %OpenId.
The real question is "what is in this stream", and the confusion worth preventing is a different one:
an id that opens nothing versus a stream that holds nothing.

Adopting the capability, not the port

Upstream's stream_inspect_impl was read at upstream/master before writing this. Three deliberate
differences, each one a rule this repo already has:

upstream	here	why
Do stream.Rewind()	nothing is called that mutates	its harmlessness is a property of IRIS, not of the tool; a reader should not write
While stream.AtEnd=0 { Set content=content_stream.Read(4096) }, no cap	Read(max_chars), size reported separately	measured on this instance family: 3,600,000 chars survive a round trip, 3,700,000 fails <MAXSTRING> → SQLCODE ‑400 → ‑149. It would fail on exactly the payload you most want to see
`Write "CONTENT	"_content` — one line	write_marker_lines with a declared line count

Three answers where upstream has two

{"success": true, "size": 0, "empty": true, "body": ""}          // opened, holds nothing
{"error_code": "STREAM_NOT_FOUND", "error": "… This is NOT an empty stream. …"}  // id opens nothing
{"error_code": "STREAM_UNREADABLE", "error": "… not an empty stream, an unusable reply …"}

Plus truncated + max_chars when the body is a prefix, body_incomplete + both line counts when
less arrived than IRIS declared, and for a binary stream the size with the bytes omitted — bytes
cannot cross a text protocol intact, and a mangled body is worse than none.

iris_generate_test — DECLINE, on the precondition it cannot meet

352 requires "output confirmed to match tdd's prescribed shape". Read at upstream/master:

pub const GENERATE_TEST_SYSTEM: &str = r#"… Generate a complete %UnitTest.TestCase subclass …
- Extend %UnitTest.TestCase
- Test methods MUST start with "Test" prefix
- Use $$$AssertEquals, $$$AssertTrue, $$$AssertNotNull macros …"#;

It asks for %UnitTest.TestCase, where tdd requires %UnitTest.TestProduction with
Parameter PRODUCTION and TestControl neutralised. Nothing about asserting on a field the
component writes. And the only validation of what comes back is:

pub fn validate_cls_syntax(text: &str) -> bool {
    text.contains("Class ") && text.contains('{')
        && text.matches('{').count() == text.matches('}').count()
}

So the shape is a request to an LLM, not a guarantee — the acceptance criterion has no answer for a
non-deterministic generator, and adopting it would have this fork advertise a tool its own gates
fight.

mermaid_production — DECLINE, on measurement

Its implementation reads only Ens_Config.Item and emits every item as a child of the production
node — a one-level fan-out, no edge between items. Measured against a real 10-item production:

	n
item→item edges knowable from TargetConfigName(s)	2
items whose routing lives in a business rule instead	2
edges the imported diagram would draw between items	0

This fork already reads both sources — items via iris_production_item(list), targets via
get_settings, which #372 made readable for many items in one round trip — and
iris_business_rule_info already parses the rule. So it can answer a question the port cannot;
importing it would ship the weaker one.

A defect this found in #375's own gate

The upstream-surface scan read ours from HEAD and INTEROP_TOOLS from the worktree. While
this change was uncommitted the two halves disagreed: stream_inspect appeared as advertised and
never-ported, and the #353 join then reported it UNCLASSIFIED. Measured: exit 1 before the
commit, exit 0 after, with no source change in between. Both halves now read HEAD and the section
prints that caveat; both_halves_of_the_surface_comparison_read_the_same_ref guards it.

Re-recorded counts, measured row by row

Three pinned gates caught the new tool, which is what they are for:
the_read_only_split_is_pinned_per_toolset (all four toolsets +1) and two wire-level pins in
mcp_handshake. The read-only figures are unchanged, and that is the measured point rather than an
oversight: stream_inspect is in GENERATOR_WRITE_TOOLS because it reads a stream through a
scratch class, so it is honestly not advertised readOnlyHint:true even though it writes nothing to
the stream. Each row was recorded by running the gate and reading what it said, not by arithmetic.

Manifest row is unit-ok, not OK: the unit tests are named and green, and there is no e2e row yet.

Verification

• cargo fmt --all -- --check clean, cargo clippy --workspace --all-targets -- -D warnings clean,
  cargo build --workspace, bash scripts/validate-tools.sh exit 0.
• Derived test gate with IRIS env unset: 11 result lines, 0 FAILED. All 12 new tests confirmed by
  name; a fabricated name returns 0.
• 10 mutations, each red on its named test and restored: the program rewinds the stream; the read
  is not the capped Read; the body goes out on one line; size read after the body; an id that opens
  nothing reports an empty stream; a no-marker reply reads as a found empty stream; a prefix not
  flagged truncated; a binary stream's bytes reported as text; a short body not flagged incomplete;
  the profile read from the worktree again.

Three of those needed re-targeting before they produced a verdict — two anchors broke the format!
string and one left an unused named argument. All three were compile errors, not survivors, and
none was counted until it compiled and went red.

Not verified against a live instance

The generated program is unit-tested, as every build_*_code in this repo is, but it has not been
run: stream_inspect reaches IRIS through execute_via_generator, which PUTs a scratch class, and
the only instance I can write to has no reason to hold an interop stream. The measurement at the top
of this PR was taken by driving the same ObjectScript by hand over Atelier, which is why the
non-consuming claim is evidence rather than inference — but the tool's own path first executes in
CI's e2e job.

[PYDuquesnoy]

CI green now — all 5 jobs, 11 new tests plus the re-recorded profile assertions confirmed by name in the log, fabricated name 0.

The first run failed on six pinned tool counts, and they were right to fail: adding a tool moves the advertised surface and this repo pins it in nine places. Three I had already re-recorded; the other six were interop_e2e_tests, four assertions in test_toolset (including its doc-comment table and the INTEROP_TOOLS.len() anchor), and three Toolset enum doc-comment headlines.

Why my derived target list missed them — worth recording because it is a second miss of the same kind: the derivation globs crates/iris-agentic-dev-core/tests/*.rs, and test_toolset.rs lives in tests/unit/. A nested module is reached through a top-level harness file, so the target name is not its own filename. And separately: grepping for the identifiers a diff touches cannot find a pinned NUMBER — ("baseline", Toolset::Baseline, 61, 38) contains nothing my change renamed. For a change that alters a surface size, the current numbers have to be part of the grep.

Every figure was re-recorded by running the gate and reading what it reported, not by arithmetic — which matters here, because the read-only counts do not move with the totals: stream_inspect is in GENERATOR_WRITE_TOOLS (it reads a stream through a scratch class), so it is honestly not advertised readOnlyHint:true even though nothing in it writes to the stream.

[PYDuquesnoy]

Do not merge this as it stands — I ran the tool end-to-end for the first time and three of its headline claims are false. I had said live verification was blocked because my writable instance has no interop namespace; that was wrong, a %Stream.GlobalCharacter needs no interop namespace at all. Driving the built binary against a real instance (streams created and deleted on my own throwaway box):

case	PR claims	actually returned
stream_id: 999, no such stream	STREAM_NOT_FOUND, "this is NOT an empty stream"	success: true, size: 0, empty: true
a %Stream.GlobalBinary	size reported, bytes omitted	class: "%Stream.GlobalCharacter", body_chars: 1 — bytes returned as text, truncated at the first NUL
a CR-separated HL7 body	"arrives whole however many newlines it contains"	segments concatenated: `…

Why, measured

%OpenId("999")  -> ISOBJ=1  ISERR=0  text=""      <- a usable EMPTY object, not a failure
%Stream.GlobalCharacter.%OpenId("6") on a BINARY stream -> succeeds, $classname = %Stream.GlobalCharacter
%ExistsId("999")=0   %ExistsId("5")=1   %ExistsId("")=0
%Stream.GlobalBinary read of a CHARACTER stream -> 106 chars, both CRs intact
$System.Encryption.Base64Encode round-trip -> lossless

Three wrong premises of mine, each of which the unit tests could not see because they fed the parser hand-written marker text:

1. '$IsObject cannot detect a missing stream. %OpenId on an unknown id hands back a usable empty object with an OK status, so the found/not-found branch never takes the not-found arm. %ExistsId is the primitive that actually distinguishes them.
2. Character vs binary is not knowable from which %OpenId succeeded — both open the same storage, and $classname reports the class I opened with. So class was reporting my own choice back to me, and the body_omitted branch is unreachable.
3. write_marker_lines deletes CR by design (objectscript.rs says so, and that is right for a CRLF %Status chain). An HL7 v2 body is CR-only, so it collapses to one line and the segment boundaries are destroyed silently — the declared-count check still says "complete", because one line is what was declared.

The third is the one I most regret: the PR text singles out HL7 as the case the line protocol exists for, and that is exactly the case it breaks.

The fix I am implementing

Read through %Stream.GlobalBinary always (measured: exact bytes for both kinds), %ExistsId for existence, and base64 for the body so CR, NUL and arbitrary bytes all survive — which also removes the unreachable binary branch. class becomes opened_as, since the data's kind is not knowable.

Also worth recording: a %Stream.GlobalCharacter saved with no content gets no id at all (%Id() came back empty), so a saved-and-empty character stream may not be a reachable state.

[PYDuquesnoy]

Fix pushed and CI green on all 5 jobs (tests confirmed by name, fabricated name 0). Re-verified end to end against a live instance after the change: the HL7 body comes back 106 bytes with both CRs intact, the binary stream 15 exact bytes with no body offered, max_chars=20 of 500 flagged truncated, and id 999 reports STREAM_NOT_FOUND. Probe streams and classes deleted afterwards.

Two mutations survived the first pass and both named a missing oracle:

• Dropping the base64 padding survived, because the round-trip test checked my encoder against my own decoder — which filters padding out. body_base64 goes to a caller using a real base64 library, so the padding is part of the contract; it is now pinned against RFC 4648's own vectors instead.
• Re-adding the CR-deleting $TRANSLATE survived every parser test, because those feed hand-written marker text and cannot see the ObjectScript. That is the same blindness that let the original defect ship, so the program itself is now asserted to contain no $TRANSLATE, no $CHAR(13) and no $PIECE.

#377 needed a rebase onto this branch's new tip and now merges cleanly; its CI is green too. One process note: my first run of the handshake tests after that rebase reported the profile as 33 tools instead of 35, and I nearly wrote it up as the rebase having dropped the INTEROP_TOOLS entries. The source had all 35 — mcp_handshake spawns the binary, and I had not rebuilt after rebasing. The cron's own rule about building before an e2e run exists for exactly that.

[PYDuquesnoy]

Recording the #352 linkage, because nothing in either PR references it and merging would leave it open — but deliberately not adding Closes #352, since that issue needs this PR and #375 together.

#352 asks for "a decision recorded per tool: adopt, or decline with a reason" across four tools. Where each one's status actually lives:

tool	status	where
stream_inspect	adopted (capability re-implemented, not ported)	this PR
iris_coverage	already in the profile — advertised today, verified via tools/list	already shipped
iris_generate_test	wanted, with a reason	#375's tools-excluded.json
mermaid_production	wanted, with a reason	#375's tools-excluded.json

So #352 is satisfied by #375 + #376 jointly. Closing it is a merge-time action once both are in, which is why neither PR carries the keyword.

Two concerns I raised and then measured away

Both worth recording so nobody re-derives them:

1. "feat(tools): record WHY each upstream tool is not in the interop profile #375 lists stream_inspect as wanted while this PR adopts it — the manifest will contradict the profile, and validate-tools.sh fails on contradictory entries." Not true. Simulated the merge (git merge-tree --write-tree of both heads, exit 0, clean): in the merged tree stream_inspect is absent from tools-excluded.json and present 9× in mod.rs. This PR removes the manifest entry as part of adopting the tool, so the two stay consistent.

2. "iris_coverage has no decision recorded anywhere." Also not true — it is already advertised in the profile, which is the strongest form of "adopt". It is absent from the excluded manifest for that reason, not by omission.

Also worth noting for whoever merges: #352's own counts are stale — it was filed when the profile was 23 tools; it is 35 now.