@iris-mcp/data 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,199 @@
1
+ # @iris-mcp/data
2
+
3
+ ## 1.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - First public release: every `@iris-mcp/*` package is published at 1.0.0 together.
8
+
9
+ ### Patch Changes
10
+
11
+ - 38389cb: fix(data): actionable error when %Service_DocDB is disabled (Epic 35, Story 35.7 / 35-SWEEP-5)
12
+
13
+ `%Service_DocDB` is disabled by default on IRIS, and all four DocDB tools (`iris_docdb_manage`, `iris_docdb_document`, `iris_docdb_find`, `iris_docdb_property`) previously failed with a bare `ERROR #822: Access Denied` and no path forward. The tools now detect this case on the error path — an `IrisApiError` carrying the locale-stable numeric `code: 822` (message text is never matched) triggers a single follow-up check of the live `%Service_DocDB` state, and when the service reads disabled the error becomes an actionable message naming the cause and BOTH remedies: the Management Portal (System Administration > Security > Services > %Service_DocDB), or `iris_service_manage` with `action="enable"` (itself governance-default-disabled, requiring an `IRIS_GOVERNANCE` override such as `{"global": {"iris_service_manage:enable": true}}`). When the service is enabled (a genuine privilege failure), when the state check itself fails, or when the error is not 822, the original error passes through unchanged. The four tool descriptions and the package README now document the prerequisite, and `tool_support.md` no longer claims the service is enabled by default.
14
+
15
+ - 04a566c: feat(execute): bound `iris_execute_command`/`iris_execute_classmethod` response payloads, make the epic gate fail closed, and make the zero-result guard machine-detectable (Story 34.6, pre-publish hardening)
16
+
17
+ **Response payload ceiling (AC 34.6.1, `34-2-R2`/`34-3-R2`).** `output` on both `/command` and `/classmethod` is now capped at 32768 characters (`ExecuteMCPv2.Utils.OUTPUTCEILING`) — content beyond the ceiling is cut off and replaced with a structured, machine-detectable elision marker (`[IRIS-MCP-TRUNCATED ceiling=32768chars]` when the field had the whole budget; a field that follows another carries `ceiling=<N>chars` with `<N>` the budget that remained for it, so detect the marker by the stable `[IRIS-MCP-TRUNCATED` prefix, never the full literal), never a bare `...`. `truncated` folds this in alongside the pre-existing capture-overflow signal (only ever set, never cleared, so the two causes OR together). `iris_execute_classmethod`'s `byRefValues` gains its own combined 1000-node (`ExecuteMCPv2.Utils.BYREFNODECEILING`) / 32768-character budget shared across every marked position, surfaced via a new additive `byRefTruncated` boolean — reported separately from `truncated` since they describe different response fields. A cut-off node in `byRefValues` is marked `subscriptsTruncated: true`.
18
+
19
+ The ceiling was picked from live measurement (Rule #36), not by feel: the CSP Gateway/HTTP transport tolerates multi-megabyte responses cleanly (tested clean to 3,000,000 characters over `/command`), so **this is explicitly not protection against a Web Gateway timeout or the target's own execution cost** (Rule #38) — the target has already fully run by the time the ceiling is applied. 32768 was chosen because a real, live MCP client (Claude Code CLI, this repo's own dev environment) was observed diverting a rendered tool result away from inline consumption once it reached 50,031 characters; 32768 stays safely under that measured boundary. **Superseded below (Story 34.7):** the ceiling was originally applied PER FIELD (`output`, `returnValue`, and the `byRefValues` budget each getting their own, so a response carrying all three at once could reach roughly three times this figure before JSON escaping) — this shape shipped only within this same pre-release development cycle and was replaced before the first publish by ONE shared budget across all three fields; see the "ONE shared response budget" section near the end of this changeset for the shipped behavior.
20
+
21
+ **Back-compat (Rule #19), proven mechanically:** under-ceiling responses on both endpoints are byte-identical to today's shape (live HTTP + `%UnitTest` pins); `byRefTruncated` is additive and simply absent — never `false` — from a pre-34.6 envelope shape.
22
+
23
+ **`returnValue` is now ALSO bounded (code-review finding CR-5, review-continuation pass).** The ceiling above covered `output` and `byRefValues` but not `returnValue` — the PRIMARY payload field on `/classmethod` — so a target returning a large string shipped fully unbounded, defeating the ceiling's own stated purpose (a live 1,000,000-character `returnValue` shipped with `truncated:false`). `returnValue` is now capped at the same 32768 characters with the same elision marker, flagged via a new additive `returnValueTruncated` boolean (symmetric with `truncated`/`byRefTruncated`, present — defaulted false — on both error envelopes too). Pinned at the REAL deployed `/classmethod` endpoint (a new leg in the epic-gate file, not a re-implementation), mutation-verified RED when the fix is removed. **Back-compat (Rule #19):** under-ceiling `returnValue` is byte-identical; `returnValueTruncated` is additive and absent (not `false`) from a pre-fix envelope.
24
+
25
+ **The `byRefValues` byte budget no longer destroys small values with oversized markers (code-review finding CR-6, review-continuation pass — a defect this story itself introduced, not pre-existing).** Once one large `Output` value exhausted the shared byte budget, every later marked position was still truncated — and when the remaining budget was smaller than the ~37-character elision marker itself, that truncation replaced a small real value with a marker LARGER than the value it destroyed (live repro: `"42"`, `"hello"`, `"x"` became 37-character markers), pushing the total past the documented 32768-character budget. Fixed in two places: `ApplyOutputCeiling` now falls back to a plain, marker-less hard cut whenever the marker itself would not fit in the remaining budget (a result is never bigger than the ceiling it was given, nor bigger than the value it replaces), and the 20 top-level `byRefValues` positions now share the same budget pre-check the recursive subscript walk already had (`AddByRefPosition`) — a position is OMITTED from `byRefValues` entirely once the shared budget is already exhausted, rather than materialized as a misleading placeholder. Pinned at the REAL deployed endpoint with the exact review repro shape, mutation-verified RED when either half of the fix is removed.
26
+
27
+ **The `byRefValues` character budget now charges subscript keys and OREF placeholders, not just leaf values (code review, cycle 2).** The budget above was decremented only by each leaf VALUE's length, so subscript KEYS and `<Object:...>` placeholders were emitted free — meaning the advertised 32768-character `byRefValues` budget did not actually bound `byRefValues`. Measured live: an `Output` array of 400 positions keyed by 900-character subscripts emitted **363,908 characters** with 32,368 of the budget still reported unspent and `byRefTruncated` still `false`; 400 OREF out-values emitted ~16,000 characters without touching the budget at all. A long-keyed `Output` array (file paths, URLs, composite keys) is an entirely idiomatic ObjectScript shape, so this was reachable by ordinary callers — the same unbounded-payload class as CR-5, one field over. Every emitted piece of content is now charged; the same 363,908-character case now emits 32,797 characters with `byRefTruncated: true`. The per-node JSON scaffolding (~25-30 characters per container node) is still not charged and is bounded instead by the 1000-node ceiling, which is now stated explicitly at every doc site rather than implied away.
28
+
29
+ **The byRef elision contract is now stated in full (code review, cycle 2).** The tool description and README previously described a false dichotomy — a value that no longer fits is "either cut short with an elision marker … or omitted entirely". There is a third case the code has always produced and the story's own gate leg (e-4) pins as correct: when the remaining budget is positive but smaller than the ~40-character marker, the value is cut to a **plain unmarked prefix**. Both surfaces now describe all three outcomes and state plainly that in the unmarked case `byRefTruncated` is the only signal — so the absence of a marker must not be read as proof a byRef value is complete.
30
+
31
+ **Non-ASCII request-body content — documented here, and FIXED in Story 34.8 before this release ships (code-review finding CR-7, review-continuation pass).** _(Superseded: see `request-body-utf8-decode-fix.md` in this same release — the defect described below was fixed in Story 34.8 rather than shipped as a Known Limitation. This entry is retained for provenance; both READMEs and the CHANGELOG describe the fixed behavior.)_ Every custom `ExecuteMCPv2.REST.*` handler's shared request-body parser (`ExecuteMCPv2.Utils.ReadRequestBody`, 14 handler classes / 46 call sites across all five servers) reads non-ASCII JSON content as if it were Latin-1, silently corrupting it on the way in — `HTTP 200`, no error, no flag — most directly affecting `iris_global_set`'s `value` (data corruption **at rest**), plus `iris_execute_command`'s `command` and `iris_execute_classmethod`'s `args`. Pre-existing across every epic and untouched by this story's actual code changes (Rule #52 scope discipline); a proper fix requires investigating IRIS's CSP request-body character-set negotiation. Per the code review's explicit ship/no-ship call, this is now documented prominently rather than shipped silently: a new "Known Limitations" note in both the suite README and `@iris-mcp/dev`'s own README, referencing ledger item `34-6-CR-7`.
32
+
33
+ **Epic-gate hardening (AC 34.6.2/34.6.3, `34-4-R1`/`34-4-R3`, internal — not a published-package behavior change).** The `iris_execute_classmethod` epic-done gate's leg (d) previously asserted only that `%SYSTEM.Version.GetVersion()` returned a version-looking string — identical in every namespace, so a regression dropping the `namespace` parameter entirely would still pass. It now calls a target that echoes `$NAMESPACE` and asserts the value both equals the requested namespace and differs from the configured default (mutation-verified RED when `namespace` is dropped). Separately, the gate's fixture-availability probe previously collapsed any failure (credential fault, network error, licence issue) into the same "fixtures not deployed" verdict as a genuinely missing fixture; it now re-throws anything that is not a genuine "document not found" response. `IRIS_REQUIRE_LIVE=1` is now armed on `@iris-mcp/dev`'s own `prepublishOnly` npm/pnpm lifecycle hook, mechanically confirmed via `pnpm publish --dry-run` to abort packaging (before a tarball is ever produced) when IRIS is unreachable.
34
+
35
+ **Zero-result guard machine-detectability (AC 34.6.4, `34-5-R1`, recorded Project Lead decision).** `iris_execute_tests`' zero-result guard (added in the prior Epic 34 story) previously returned content-only JSON with no `isError`/`structuredContent`, so a structured consumer reading `structuredContent.total` regressed from `0` to `undefined`, and an agent branching on `isError` recorded the call as a success. It now carries **both** `isError: true` **and** `structuredContent` set to the same `{total, passed, failed, skipped, details, error}` object shown in the text content — both halves are required, not an either/or, since the guard fires only when the target produced nothing (a failed request, not a clean run). Applied identically to every guard path (package/class/method levels and the package discovery-time check) via one shared helper, so the paths cannot diverge again.
36
+
37
+ **Packaging gate extended to every IRIS-touching package (QA finding, internal — not a published-package behavior change).** `@iris-mcp/dev`'s own `prepublishOnly` gate only ever protected `@iris-mcp/dev` itself. `.changeset/config.json` groups every `@iris-mcp/*` package as `"fixed"`, so a real release always version-bumps and publishes `@iris-mcp/shared`, `@iris-mcp/admin`, `@iris-mcp/data`, `@iris-mcp/interop`, and `@iris-mcp/ops` (plus the `@iris-mcp/all` meta-package) alongside `@iris-mcp/dev` in the same event — none of which had any live-IRIS check of their own. Confirmed live (dry-run only) that `pnpm -r publish` processes packages in dependency-topological order: `@iris-mcp/shared` (a dependency of every other package) packaged and "published" completely BEFORE `@iris-mcp/dev`'s gate ever ran and correctly failed closed on a simulated credential fault — in a real release `@iris-mcp/shared` would already be on the registry by the time that failure is observed. A new shared script, `scripts/verify-iris-reachable.mjs`, is now wired as `prepublishOnly` on `@iris-mcp/shared`, `@iris-mcp/admin`, `@iris-mcp/data`, `@iris-mcp/interop`, `@iris-mcp/ops`, and `@iris-mcp/all` — a minimal, unconditional IRIS-reachability check (not a substitute for `@iris-mcp/dev`'s own deeper epic-done regression suite, which only makes sense for the package that ships that specific tool). Mutation-verified: the same bad-credential recursive dry-run that previously produced a complete `@iris-mcp/shared` tarball now produces zero tarballs before `@iris-mcp/dev`'s own gate is even reached; a good-credential run still publishes both packages cleanly. Wired into `@iris-mcp/client-config` as well. That package has no IRIS dependency of its own, and the first pass deliberately excluded it for that reason — but code review reversed the call: `.changeset/config.json` puts every `@iris-mcp/*` package in one `"fixed"` group, so they always publish as a single event, and `client-config` sorts FIRST in `pnpm -r publish`'s dependency-topological order. Left ungated it was the one package that could reach the registry before any gate in the release fired at all, confirmed live by a bad-credential dry run that produced a complete `client-config` tarball; re-verified after wiring that the same run now produces zero tarballs, while a good-credential run still publishes all eight packages cleanly.
38
+
39
+ ***
40
+
41
+ The paragraphs above describe the state as it shipped from Story 34.6's own review cycle. Three items that same review flagged as "only free to change before the first publish" (npm versions are immutable) were escalated to a follow-up story and are folded into this SAME still-unpublished changeset rather than shipped as a separate release, since nothing above has reached the registry yet.
42
+
43
+ **A truncation cut through a surrogate pair no longer emits invalid UTF-8 on the wire (Story 34.7, ledger `34-6-CR-10`).** Before the ceiling above existed, `output` passed through verbatim and was always valid UTF-8 — this was a regression the ceiling introduced, not a pre-existing defect. IRIS represents an astral character (e.g. an emoji) internally as a UTF-16 surrogate pair; the ceiling's `$Extract` cut counted each half as one character with no boundary guard, so a cut landing immediately after the high half emitted a lone surrogate on the wire as WTF-8 (invalid UTF-8) — Node's lenient decoder silently substituted it with U+FFFD, inflating the client-visible length from 32768 to a live-verified **32,770 characters** (breaking the documented cap outright), and a strict decoder threw outright. The cut now backs off by one code unit whenever it would otherwise end on an unpaired high surrogate. Pinned by decoding the **actual HTTP response bytes** with a strict, fatal `TextDecoder` — not by round-tripping inside IRIS, which tolerates its own WTF-8 and was the reason the Story 34.6 pin never caught this. Mutation-verified: reverting the guard reproduces the exact 32,770-character defect live under a strict-decode failure; restored, the same request decodes cleanly at 32767 characters.
44
+
45
+ **ONE shared response budget replaces the three independent per-field ceilings (Story 34.7, ledger `34-6-CR2-6`).** `returnValue`, `byRefValues`, and `output` now share a SINGLE 32768-character budget instead of each getting their own — closing the gap the superseded paragraph above described (a fully-flagged response could otherwise carry roughly three times the figure raw, and escaping could inflate a two-field worst case to a live-measured 131,102 characters, ~2.6x past the 50,031-character client threshold that was the ENTIRE rationale for 32768). The budget is spent in field order **`returnValue` → `byRefValues` → `output`** (a Project Lead decision, not re-litigable): the small, high-value `returnValue` is never starved by narration, and `output` — usually the field that actually blows the budget — absorbs the truncation last. All three flags (`truncated`/`returnValueTruncated`/`byRefTruncated`) are **retained**; only the budget arithmetic changes. Live-measured new worst case: a single 32768-character field of C0 control characters (consuming the whole shared budget alone) serializes to **196,495 characters** — 6.0x the raw ceiling, ~3.9x past the 50,031-character client-divert threshold (residual risk tracked as `34-7-QA-1`). **Back-compat (Rule #19), proven mechanically:** a response that stays under the shared budget — the common case, since `returnValue` is usually small — is byte-identical to before; `iris_execute_command`'s `/command` endpoint (no `returnValue`/`byRefValues` to share with) is completely unaffected.
46
+
47
+ **The response-payload ceiling bounds raw characters, not the serialized JSON size — stated plainly and pinned (Story 34.7, AC 34.7.4).** The 32768 figure was always measured on raw content before JSON escaping, but no fixture had ever exercised escape-heavy content (every prior over-ceiling fixture used a single repeated plain letter), so the claim was untested where it mattered most. Both `execute.ts` tool descriptions and `packages/iris-dev-mcp/README.md` now state explicitly that the ceiling is a raw-character bound, not a wire-size guarantee, and cite the live-measured 32,860 / 98,311 / 196,495-character range (escaping-neutral / mixed / worst-case, same 32768 raw characters) measurement above.
48
+
49
+ **Packaging now refuses a stale or missing build, failing closed (Story 34.7, ledger `34-6-CR-11`).** Neither existing prepublish gate verified the package about to be packaged had actually been built — `prepublishOnly` runs before `prepack`, `verify-iris-reachable.mjs` imports only `@iris-mcp/shared`'s dist (never the caller's own), and `@iris-mcp/dev`'s deeper gate runs vitest over TypeScript source. A stale or missing `dist/` left both gates green and let `npm`/`pnpm` pack the tarball anyway — unrecoverable for a first publish, since npm versions are immutable. Every publishable package's own prepublish gate now ALSO verifies, per-package and self-referentially, that its own `dist/` is present, non-empty, and at least as new as its own `src/` — failing closed with zero tarball produced otherwise. Derived from each package's own `package.json` (`files: ["dist"]`), so a package with no build step of its own (`@iris-mcp/all`) is unaffected without a hand-maintained exception list. Mutation-verified: a staled/deleted `dist/` fails closed with zero tarball produced; restoring the build passes again.
50
+
51
+ - eb75133: fix(execute): decode non-ASCII request-body content correctly instead of silently corrupting it (Story 34.8, ledger `34-6-CR-7`)
52
+
53
+ **The defect.** Every custom `ExecuteMCPv2.REST.*` handler read its JSON request body through the shared `ExecuteMCPv2.Utils.ReadRequestBody` helper (14 handler classes, 46 call sites, spanning all five servers), which handed the raw POST body straight to `%DynamicObject.%FromJSON()` with no UTF-8 decode. Non-ASCII characters submitted through a request body arrived mis-decoded as their raw UTF-8 bytes read as Latin-1 — `é` (U+00E9) as two garbled characters, `世界` as six, an emoji as four — silently, with `HTTP 200` and no error or truncation flag. This affected `iris_execute_command`'s `command`, `iris_execute_classmethod`'s `args`, and — most seriously — `iris_global_set`'s `value`, where the corrupted text was written to the target global as genuine **data corruption at rest**. Content that originates server-side (e.g. a compiled class's literal source) was always unaffected; the defect was strictly on the inbound request-body path. Story 34.7 documented this as a Known Limitation rather than fix it before the first publish; the Project Lead elected to fix it before publishing rather than ship documented data corruption.
54
+
55
+ **Root cause, live-probed (AC 34.8.1) rather than guessed.** `%request.GetMimeData("BODY")` is never populated for this project's plain `application/json` POSTs (multipart-only) — the primary branch in `ReadRequestBody` was dead in practice; every real call fell through to the `%request.Content` fallback, a `%CSP.BinaryStream` holding the raw, untranslated request bytes (confirmed byte-for-byte against a known UTF-8 encoding). `%request.CharSet` is empty because the TS client's `Content-Type: application/json` header carries no charset parameter, so no CSP-level charset negotiation ever applied.
56
+
57
+ **The fix.** `ReadRequestBody` now routes the resolved stream through a new `ExecuteMCPv2.Utils.DecodeUtf8Stream`, which decodes the raw bytes as UTF-8 before handing the result to `%FromJSON`. Two properties, both required by the ACs and both mechanically pinned:
58
+ - **Chunk-boundary safety.** Reads the stream in bounded chunks (1,000,000 raw bytes at a time) and detects, via a new `IncompleteUtf8TailLength` helper, whether the trailing 0-3 bytes of a chunk are the unfinished start of a multi-byte sequence — holding them back and prepending them to the next chunk rather than decoding a split sequence independently (the naive-per-chunk-`$ZCONVERT` trap). Live-verified with a deliberately tiny chunk size against content containing 2-, 3-, and 4-byte UTF-8 characters back to back, and swept across every possible chunk size for a representative fixture.
59
+ - **Large-body safety, with two traps found live rather than assumed.** (1) `$ZCONVERT` given a stream OREF directly — rather than a materialized `%String` chunk — does not throw and does not decode: it silently stringifies the OREF itself. (2) A single `.Read(stream.Size)` call requesting an entire large stream's content in one shot does not reliably return it all: measured on a 49,000,000-byte stream, one such call silently returned only ~3.6 million characters, with **no exception of any kind** — never `<MAXSTRING>`, just quietly less data than requested. The fix reads in a `While 'stream.AtEnd` loop and accumulates DECODED output into a `%Stream.TmpCharacter` (never a growing `%String`), verified end-to-end at 49,000,000 raw bytes with zero exceptions and a correct content spot-check.
60
+
61
+ **Back-compat (Rule #19), proven mechanically.** Pure-ASCII request-body content — every one of this suite's pre-existing ObjectScript command / classmethod-arg / global-value calls — is byte-for-byte identical before and after the fix (every ASCII code point 0-127 is already valid single-byte UTF-8, so the decode is a true no-op on ASCII). Pinned both at the ObjectScript unit level (`ExecuteMCPv2.Tests.Utf8DecodeTest`, 33 tests) and end-to-end against the real deployed `/command`/`/classmethod`/`/global` routes (`request-body-utf8-decode.test.ts`, 12 tests) — the latter also covers accented BMP, CJK, astral-plane emoji, mixed ASCII+non-ASCII, non-ASCII inside a `{byRef, value}` marker, a non-ASCII JSON key alongside real content, and the exact live reproduction string reported for this defect. Mutation-verified at both layers: reverting the fix reproduces the original mojibake live and turns both test files red; restoring it (byte-identical to the committed source) turns them green again.
62
+
63
+ **QA follow-up fix, same story: malformed input could produce genuinely invalid UTF-8 on a response.** Adversarial QA testing found that `$ZCONVERT(...,"I","UTF8")` is lenient enough to decode a malformed 3-byte WTF-8/CESU-8 byte sequence (`0xED [0xA0-0xBF] [0x80-0xBF]` — never valid in conformant UTF-8, since RFC 3629 excludes the whole surrogate block from UTF-8) into a raw, unpaired UTF-16 surrogate code unit rather than rejecting it. The pre-Story-34.8 Latin-1 decode this replaced could never produce a surrogate from any input, so this was a new failure mode introduced by the UTF-8-aware decode, not a pre-existing one. Live-verified with a hand-crafted raw HTTP body (bypassing the sanitization any standard JSON+UTF-8 client, including this suite's own `IrisHttpClient`, always performs before such a byte pattern could reach the wire): an unpaired surrogate reaching a response was re-emitted by IRIS as genuinely invalid UTF-8 — a strict decoder threw on the actual response bytes, silently, under `HTTP 200`, no error, no truncation flag — the same underlying platform behavior Story 34.7's `SurrogateSafeCutLength` already guards against on the truncation/output side. Fixed with a new `ExecuteMCPv2.Utils.SanitizeUnpairedSurrogates` helper, applied to every decoded chunk, that substitutes `?` for any surrogate half without a valid pairing partner (matching `$ZCONVERT`'s own observed substitution for other invalid sequences) while leaving every genuine surrogate pair (real astral characters) completely untouched. Re-verified live after the fix: the same hand-crafted request now round-trips to a strictly-valid-UTF-8 response. Not reachable through any of this suite's own MCP tool clients — only through a hand-crafted raw HTTP body — but fixed rather than left as a new, undocumented gap, consistent with this epic's standing policy against shipping a silent-corruption path under `HTTP 200`.
64
+
65
+ **The decoder is lenient, not validating — and that is now documented for users.** Beyond the unpaired-surrogate case above, two further malformed-input dispositions were determined live and pinned, and are stated in both READMEs' "Known Limitations" sections rather than left in code comments only: (1) any invalid byte sequence — an orphan continuation byte, an out-of-range lead byte, a truncated sequence at end of body — is replaced with a literal `?` under `HTTP 200` rather than rejected, and that `?` is indistinguishable from one the caller genuinely sent; (2) non-canonical **overlong** encodings are decoded rather than refused (e.g. the bytes `0xC0 0xAF` decode to `/`, which conformant UTF-8 per RFC 3629 forbids). (2) carries a **security note** now published in the suite README: overlong forms are a classic filter-bypass technique, so any proxy/WAF/gateway rule placed in front of these endpoints that inspects **raw bytes** for characters like `/`, `.`, or a quote can be bypassed by an overlong encoding that still decodes to the canonical character inside IRIS — such rules must normalize UTF-8 themselves. This matters because these endpoints execute arbitrary ObjectScript and write globals. Well-formed input is never affected by either behavior.
66
+
67
+ **The fix is forward-only.** It corrects decoding for requests received after it is deployed; it does not repair data already written corrupted while the defect was live (e.g. a global populated via `iris_global_set` before upgrading). There is no automated repair tool for previously-corrupted data — documented explicitly in both READMEs' "Known Limitations" sections.
68
+
69
+ No new tool, no new governance key, no tool-count change (Rule #31) — this is a fix to existing, already-governed request handling.
70
+
71
+ - 4ac3cb3: fix: Rule #37 ledger burn-down — classmethod-fidelity redirect teardown, `/classmethod` schema tightening, client-config write-engine hardening, and test output kept out of every published tarball (Story 36.3)
72
+
73
+ `ExecuteMCPv2.REST.Command` (ObjectScript, embedded via `@iris-mcp/shared`'s bootstrap): a new shared `TeardownRedirect` helper runs each step of the `/command`/`/classmethod` output-capture teardown — disable the redirect, `Use` the original device, `Close` the scratch device — independently, so a failing `Use` no longer skips the `Close`. Closing the capture device returns `$IO` to the request's own response stream, so a response can no longer land on the scratch device as an HTTP 200 with an empty body. Both outer error handlers now also clear both process-private capture variables (housekeeping: a stale value was never observable, because every request resets them before capturing). `BOOTSTRAP_VERSION`: `e1168c1ebe56` → `8465393b3f74`.
74
+
75
+ `iris_execute_classmethod` (`@iris-mcp/dev`): the `args` array's JSON Schema now matches the server's own contract (a scalar, or a `{byRef, value?}` marker) instead of accepting anything. Every documented form is still accepted; a malformed entry is now rejected at the schema layer, not only server-side. The description now states that omitting `args` and passing `[]` are the same zero-argument call, and documents a capture caveat: a target that KILLs the capture variables (an argumentless `KILL`, or a unit-test class's setup/teardown) silently loses what was captured — run unit-test suites with `iris_execute_tests`. The `execute-classmethod-epic-gate.test.ts` live gate's 20-argument leg now checks every position, and a new "repro 3b" leg covers several `ZN` switches interleaved with narration and a `ByRef` mutation.
76
+
77
+ `@iris-mcp/client-config`:
78
+ - **Fixed a config-corrupting update:** applying to a Codex entry that had only a `command` line placed the new `args` line inside the new `[mcp_servers.<name>.env]` table (read back as `env.args`, a still-valid but wrong file). An entry whose first line was `args` could also lose the inserted `command`.
79
+ - **CRLF files keep CRLF on every written line.** This covers insert, set-flag and merge-update, including a first write into a `config.toml` with no MCP table yet and files with no trailing newline.
80
+ - A stale stash record left after a no-op `enable` is now dropped. Backup filenames disambiguate when two writes land in the same millisecond, and `doctor` ages those disambiguated backups too.
81
+ - A hand-edited native `disabled` flag is read per the real client's own truthiness rules.
82
+ - Duplicate JSON/JSONC keys are flagged where they make the manager's view ambiguous: a duplicated root key, a duplicate server name, or a duplicate key inside a manager-owned entry. A duplicated unrelated setting elsewhere in a hand-edited settings file no longer blocks the manager.
83
+ - A canonical-named entry holding a non-object value now reports as mis-shaped, with repair guidance for its own format.
84
+ - A merge-update now carries a changed line's trailing comment forward. It edits env sub-table keys individually, so untouched keys and their comments survive.
85
+ - `doctor` handles `$$` (PID) runs correctly in shell-style references and no longer hides Claude-style `$${VAR}` references. Its entry walk is bounded.
86
+ - The `certify` script gained a tested restore-ladder decision, a word-boundary-safe evidence excerpt, `--skip-agent` for the claude-code verifier, a dangling-symlink refusal, and a tested argument parser: a trailing valueless `--residual-risk` no longer erases a recorded residual risk.
87
+ - One item (`33-1-R3`, JSONC comments inside a manager-owned entry) is accepted as a documented limitation; see `packages/client-config/README.md`.
88
+
89
+ **Packaging (every publishable package):** compiled test files (`dist/**/__tests__`) are excluded from each tarball through the package's `"files"` list. Test files stay fully type-checked by `type-check` and `build`. `npm pack --dry-run` and `pnpm pack` show zero `__tests__` files in all seven publishable packages. `@iris-mcp/all`, a dependency-only meta-package, had no `"files"` list and shipped its whole `src/` tree; it now ships only its manifest, README and licence.
90
+
91
+ This closes the 45 items carried at Rule #37 count 2 to a terminal disposition (resolved, closed-with-evidence, or closed-by-decision). See `deferred-work.md`'s "Story 36.3 burn-down" section and its code-review corrections for the per-item evidence.
92
+
93
+ - 5f8b1e0: fix: an MCP transport other than stdio is a startup configuration error (Story 38.1)
94
+
95
+ `@iris-mcp/shared` (minor): `resolveTransport()` returns `"stdio"` and throws a configuration error for every other
96
+ configured `MCP_TRANSPORT` or `--transport` value (`http` included; the match is exact and case-sensitive). A
97
+ non-`stdio` value used to be accepted, and the server then connected to IRIS and bootstrapped before throwing "HTTP
98
+ transport not yet implemented"; an unknown `MCP_TRANSPORT` value used to fall back to stdio with a warning. Startup with
99
+ no transport configured, or with `stdio`, is unchanged. The type of `McpServerBase.start()`'s parameter is narrowed to `"stdio"`.
100
+
101
+ `@iris-mcp/dev`, `@iris-mcp/admin`, `@iris-mcp/interop`, `@iris-mcp/ops`, `@iris-mcp/data` (patch): the entry point
102
+ routes the configuration error into its existing `Fatal:` handler, so the process prints the message and exits 1 before
103
+ any IRIS connection. Remove `MCP_TRANSPORT` / `--transport`, or set it to `stdio`.
104
+
105
+ - 346ddc9: Make the packages publishable and pin every `npx` spec to the major (Story 42.1).
106
+ - Every spec the suite writes, spawns or documents ends in `@1`: `@iris-mcp/client-config` exports `IRIS_MCP_MAJOR` and `pinnedSpec()`, `iris-mcp-clients apply` writes `["-y", "@iris-mcp/<pkg>@1"]`, and re-applying an entry that an earlier version wrote unpinned rewrites only its owned `args`. The documented clients CLI form is `npx -y -p @iris-mcp/client-config@1 iris-mcp-clients <command>` (the old form passed `iris-mcp-clients` to the CLI as an unknown command).
107
+ - Every package declares `engines.node >=22.17.0`, `@types/node` is major 22, and the registry metadata (`license`, `repository`, `author`, `homepage`, `bugs`, `keywords`, and `mcpName` on the five servers) is complete.
108
+ - `@iris-mcp/shared` publishes only its root export, and no tarball ships test helpers, source maps or a vitest peer declaration.
109
+ - `@iris-mcp/all` is documented as a meta-package with no command: a global install links nothing.
110
+ - The first release lands on `1.0.0` through a release changeset template kept outside `.changeset/`; no pending changeset declares a major.
111
+
112
+ No tool, action, governance key, annotation, description or environment variable is added or changed.
113
+
114
+ - 5892022: refactor: framework migration to the MCP SDK v2 (Story 43.1)
115
+
116
+ `@iris-mcp/shared` runs on `@modelcontextprotocol/server` 2.3.1, pinned exactly, and the v1 `@modelcontextprotocol/sdk` is removed from every package. The 2025-11-25 wire is unchanged: `McpServerBase` serves `tools/list`, `tools/call`, `prompts/get` and `resources/read` itself, so every tool entry, error text and resource read the golden covers is byte-identical to the v1 build, which a golden captured before the migration pins on all five servers. The suite stays at 115 tools, the governance baseline and `BOOTSTRAP_VERSION` do not move, and `pnpm audit --prod` drops from 71 advisories to 18.
117
+
118
+ Two fixes change behavior: a schema-invalid `tools/call` is now audited (one entry with `outcome` `error`, the raw key names and no `params`; DW-579), and a `prompts/get` that omits `arguments` renders like `{}` for a prompt whose arguments are all optional (DW-617).
119
+
120
+ Three more changes are sanctioned under AD-15 (wave-8 decisions #4 and #6): `addTools` sends one `notifications/tools/list_changed` per call instead of one per tool plus one; a malformed `tools/call` request (no `params`, `name` missing or not a string, `arguments` not an object) is refused with `-32602` `Invalid tools/call request: …` where v1 answered `-32603`; and a `tools/call` that carries a `task` parameter runs as a plain call where v1 refused it with `-32603`. Only a client that breaks the request schema or ignores the capability list sends either request.
121
+
122
+ - c245998: feat: serve MCP revision 2026-07-28 over stdio alongside 2025-11-25 (Story 43.2)
123
+
124
+ `McpServerBase.start()` serves stdio through the SDK's `serveStdio`, so one process answers a 2025-11-25 `initialize` and a 2026-07-28 `server/discover`. The 2025-11-25 wire is unchanged (every Story 43.1 golden line and pin passes as it was), and the suite stays at 115 tools with the governance baseline and `BOOTSTRAP_VERSION` unmoved. The 2026-07-28 wire is the same content plus the fields that revision mandates (`resultType` and the server identity in `_meta` on every result, `ttlMs` and `cacheScope` on the cacheable methods), without the tools' `execution`. A per-request `_meta` key changes no `server` or namespace resolution, governance decision, visibility or audit entry.
125
+
126
+ Claude Code 2.1.292 and later negotiate 2026-07-28 with stdio servers by default and fell back to 2025-11-25 against earlier servers. `MCP_PROTOCOL_NEGOTIATION=legacy` in Claude Code's own environment keeps the 2025-11-25 handshake. Known limits, all the SDK's: on 2026-07-28 a `ping` is answered `-32601`, `list_changed` reaches only `subscriptions/listen` subscribers, and a v2 SDK client on `auto` or a pinned revision starts a short-lived probe process per connect.
127
+
128
+ - 9521312: feat: ask the person to confirm the destructive gates through elicitation (Story 43.3)
129
+
130
+ When the calling MCP client declares form elicitation, six gates show a confirmation form right before their first IRIS write: `iris_audit_manage` `purge`, `iris_env_promote` `execute`, `iris_production_control` `clean` with `killAppData: true`, `iris_message_resend` `resendFiltered` (to execute) and `resend`, and `iris_doc_edit` `regenerateStorage`. The dialog comes after every check of the tool and never replaces `confirm: true`. A decline, a dismissal or an accept without the tick ends the call with the new refusal code `CONFIRMATION_DECLINED` and changes nothing; the confirmation is bound to the tool, the server profile and the exact arguments, and can be used once. A client that does not declare form elicitation gets exactly the previous contract, and the 2025-11-25 wire is unchanged for it. No tool, action, governance key, preset row, annotation, description or environment variable is added or changed, and the suite stays at 115 tools with the governance baseline and `BOOTSTRAP_VERSION` unmoved.
131
+
132
+ The audit entry gains the additive field `confirmation` (`accepted`, `declined`, `cancelled`, `unconfirmed` or `unanswered`); a decline is `denied` with `denyReason` `CONFIRMATION_DECLINED`. A call the client cancels now aborts the IRIS request it has in flight and is audited `error` instead of `ok` (`RequestOptions.signal`, `IrisConnectionError` code `CANCELLED`). A Claude Code `Elicitation` hook can answer the dialog for the person; installing one that does is the user's choice and removes the person from the loop. The SDK's bundled validator carries fast-uri 3.1.0, whose advisories are unreachable here because the server never invokes the validator (DW-637).
133
+
134
+ - ca753c9: feat: close Epic 43 (the MCP SDK v2 migration) with descriptions, a deduplicated governance resource, a corrected prompt, a capstone gate and the client docs (Story 43.4)
135
+
136
+ The descriptions of `iris_audit_manage`, `iris_env_promote`, `iris_production_control`, `iris_message_resend` and `iris_doc_edit` each gain one appended passage that names the confirmation dialog shown to a client that declares form elicitation, says that a decline or a dismissal returns `CONFIRMATION_DECLINED` with nothing changed, tells the agent not to repeat the call unless the person asks, and says that a client without elicitation is not asked; no existing description byte changes. `resources/list` now lists `iris-governance://default` once, because the per-profile resource template no longer lists the `default` profile that the static resource already names (DW-646). Steps 3 and 4 of the `resend-failed-messages` prompt now say that the executing call, not the preview, is refused over `maxMessages`, and that leaving `dryRun` out only previews again (DW-653); the prompt's name, title, description and arguments are unchanged, and the generated skill and the skills pack in `@iris-mcp/client-config` are regenerated.
137
+
138
+ The two frozen SDK v1 goldens stay byte-unchanged; each sanctioned change to bytes they hold is an entry of a ledger that the golden tests apply (DW-639). A default-suite capstone drives the built admin server through the real SDK client on `legacy`, a pinned `2026-07-28` and `auto`. The root README, `docs/client-config/README.md` and `docs/client-config/claude-code.md` document the protocol revisions, `MCP_PROTOCOL_NEGOTIATION=legacy`, the probe copy that an SDK v2 client starts (DW-641) and the dialog, as observed on Claude Code 2.1.296 and MCP Inspector CLI 2.9.0. No tool, action, governance key, preset row, annotation, refusal code or environment variable is added, and the suite stays at 115 tools with the governance baseline and `BOOTSTRAP_VERSION` unmoved.
139
+
140
+ - 8437bbe: fix(dev,data): XML import compile parity + legacy REST get routing (Epic 35, Story 35.6)
141
+
142
+ **`iris_doc_xml_export:import` compile parity (35-SWEEP-8).** Import previously loaded definitions WITHOUT compiling and reported bare success — the imported class then failed with `<CLASS DOES NOT EXIST>` until a separate `iris_doc_compile`. Additive `compile` (boolean, default false) and `flags` (string, only used when `compile` is true) parameters now mirror `iris_doc_load`: `compile: true` sends the native Atelier `flags` query param with the `c` compile qualifier folded in automatically when absent or explicitly negated (IRIS qualifiers are case-insensitive and `-c` negates — the fold guarantees an EFFECTIVE final `c`, so `-c` becomes `-cc`), so documents compile in the same call. When `compile` is omitted/false the request is byte-identical to the previous behavior (no `flags` param) and the response gains an honest note that the documents are NOT compiled, naming the remedy. Non-empty per-file `status` text from the load response (where IRIS reports compile errors while still answering HTTP 200) is now surfaced in the response text. Live-probed on IRIS 2026.1: `flags=ck`/`flags=c`/`flags=C` compile, `flags=k`/`flags=-c` and no flags do not; broken XML with `compile: true` surfaces `ERROR #5475` in the per-file status.
143
+
144
+ **`iris_rest_manage:get` legacy routing (35-SWEEP-9).** `list` with `scope:"legacy"`/`"all"` returns hand-written `%CSP.REST` apps (e.g. `/api/executemcp/v2`), but `get` on such a name previously 404'd via the IRIS Management API with the CSP gateway's misleading "Check the IRIS web server configuration" text — a by-design scope boundary (the Mgmnt API covers spec-first apps only), not a misconfiguration. `get` now branches on the HTTP 404 STATUS (never the message text) and falls back to the legacy webapp list: a legacy name resolves to `{name, dispatchClass, namespace, swaggerSpec: null, explanation}` (`fullSpec` deliberately has no effect — no spec exists), and a name in neither scope fails with an accurate not-found naming BOTH scopes checked. Spec-first `get` is unchanged. `delete` remains spec-first-only: a legacy name fails with an explanation pointing at `iris_webapp_manage:delete`, which is the correct tool for removing a legacy web application.
145
+
146
+ - Updated dependencies [7fdde35]
147
+ - Updated dependencies [b68b3f1]
148
+ - Updated dependencies [cdf1d29]
149
+ - Updated dependencies [04a566c]
150
+ - Updated dependencies [7f286ea]
151
+ - Updated dependencies [d8a8159]
152
+ - Updated dependencies [8de37a3]
153
+ - Updated dependencies [d14729d]
154
+ - Updated dependencies [ddaf389]
155
+ - Updated dependencies [cef1d4b]
156
+ - Updated dependencies
157
+ - Updated dependencies [eb75133]
158
+ - Updated dependencies [4ac3cb3]
159
+ - Updated dependencies [c4ff9ae]
160
+ - Updated dependencies [05b26d9]
161
+ - Updated dependencies [5f8b1e0]
162
+ - Updated dependencies [689f785]
163
+ - Updated dependencies [7d39281]
164
+ - Updated dependencies [7104523]
165
+ - Updated dependencies [06b1b20]
166
+ - Updated dependencies [4520fd7]
167
+ - Updated dependencies [628a817]
168
+ - Updated dependencies [b52e661]
169
+ - Updated dependencies [549bbad]
170
+ - Updated dependencies [e556857]
171
+ - Updated dependencies [8e1acdc]
172
+ - Updated dependencies [5e02f47]
173
+ - Updated dependencies [2e307d4]
174
+ - Updated dependencies [b3d11b1]
175
+ - Updated dependencies [6b6216c]
176
+ - Updated dependencies [6c4617c]
177
+ - Updated dependencies [27d04e5]
178
+ - Updated dependencies [1fdda9e]
179
+ - Updated dependencies [efaa9ef]
180
+ - Updated dependencies [04dc213]
181
+ - Updated dependencies [346ddc9]
182
+ - Updated dependencies [ebeee9e]
183
+ - Updated dependencies [394b35f]
184
+ - Updated dependencies [4fd0acb]
185
+ - Updated dependencies [22757b7]
186
+ - Updated dependencies [8fd093b]
187
+ - Updated dependencies [5892022]
188
+ - Updated dependencies [c245998]
189
+ - Updated dependencies [9521312]
190
+ - Updated dependencies [ca753c9]
191
+ - Updated dependencies [da6d495]
192
+ - @iris-mcp/shared@1.0.0
193
+
194
+ ## 0.0.2
195
+
196
+ ### Patch Changes
197
+
198
+ - Updated dependencies
199
+ - @iris-mcp/shared@0.0.2
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 jbrandtmse
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.