agentfootprint 9.80.0 → 9.82.0

package/AGENTS.md

@@ -112,6 +112,26 @@ Transports: `stdio` (local subprocess), `http` (Streamable HTTP). The
 `@modelcontextprotocol/sdk` peer-dep is lazy-required — zero runtime
 cost when MCP isn't used. Friendly install hint if missing.
 
+**In a BROWSER** the Node `require` loader does not exist, so supply what it
+would have found. Give the two SDK modules as `sdk` (the library still builds
+the transport, so headers / your own `fetch` / gateway vending / throttle retry
+all keep working), or a client you connected yourself as `connection`:
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const sidecar = await mcpClient({
+  name: 'sidecar',
+  sdk: { Client, StreamableHTTPClientTransport },
+  transport: { transport: 'http', url: '/py/mcp' },   // relative resolves against the page
+});
+```
+
+`stdio` spawns a subprocess and is refused in words there. On the `connection`
+arm the library builds no transport, so `retryOnThrottle` / `clientInfo` are
+REFUSED rather than ignored — wrap your own fetch with `retryingFetch` instead.
+
 `agent.tools(arr)` is the bulk-register companion to `agent.tool(t)`.
 Pair with `await client.tools()` to register everything an MCP server
 exposes in one builder call. Tool-name uniqueness is still validated

package/CHANGELOG.md

@@ -7,6 +7,173 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.82.0] - 2026-08-30
+
+### Added
+
+- **A runbook can finally name the verdict no rule chose.** `verdict_meanings`
+  is generated from what the run itself said: the branch descriptions the chart
+  declared, and the rule labels this run's `decide()` evidence carried. For one
+  branch, both sources are silent by construction — the DEFAULT. It is the
+  branch chosen by *no rule* (it fires exactly when every rule failed, so no
+  `label` describes it), and when the decider lives inside a dynamically
+  generated fan-out branch the branch chart does not exist at build time either,
+  so there is no declared description to fall back on.
+
+  The library shipped visible proof of the gap: this repo's own worked example
+  and the published docs page showed a `"verdict": "protected"` row beside a
+  `verdict_meanings` map with no `protected` key.
+
+  The meaning is now declared where the rules are declared — one line at the
+  `decide()` call, on `footprintjs` ≥ 9.16.0:
+
+  ```ts
+  // before
+  decide(scope, POSTURE_RULES, 'protected');
+  // after
+  decide(scope, POSTURE_RULES, {
+    branch: 'protected',
+    label: 'no rule fired — last backup within the 7-day threshold',
+  });
+  ```
+
+  It rides `DecisionEvidence.defaultLabel` and is harvested exactly like a rule
+  label — on every decision, including runs where a rule won, so a published
+  meanings map does not gain and lose a key with the day's data.
+
+  What deliberately did NOT change: there is **no caller-supplied meanings map**
+  at the tool boundary. A map a caller can hand in is a map that can describe
+  rules that never ran, and it would be indistinguishable in the answer from
+  meanings the run produced. Declare nothing and `verdict_meanings` stays
+  honestly silent about that branch — the bridge never invents a sentence from a
+  branch id. A blank label (`''`) is recorded as no meaning at all, for a rule or
+  for the default.
+
+  Example: `examples/features/68-runbook-as-tool.ts` — its `verdict_meanings`
+  now explains every verdict its own rowset shows.
+
+### Changed
+
+- **`footprintjs` peer dependency: `^9.15.0` → `^9.16.1`** — 9.16.0 carries
+  `DefaultBranch` / `DecisionEvidence.defaultLabel`; 9.16.1 is the floor because
+  9.16.0 threw on a `decide()` call that omits its default (this repo's own
+  suite caught it).
+- **The engine version stamp on a recording envelope is real again.** footprintjs
+  9.15.1 added `'./package.json'` to its `exports` map, so `engineVersion()` can
+  resolve the manifest it always tried to read: `producer.footprintjsVersion` and
+  a bug report's `environment.footprintjs` now carry the installed version
+  instead of the honest-but-useless `'unknown'`. The test that pinned the defect
+  (and asked to be tripped when it was fixed) now pins the version instead.
+
+## [9.81.0] - 2026-08-30
+
+### Added
+
+- **MCP from a browser — because the barrier was never the protocol, it was one
+  line of ours.** `mcpClient` loads `@modelcontextprotocol/sdk` through a Node
+  `require` loader, and that loader does not exist in a browser bundle. The SDK
+  itself is fine: its `client/index.js` and `client/streamableHttp.js` bundle at
+  `platform: 'browser'` with **zero** `node:` edges and never pull in
+  `client/stdio.js`. So the fix is not to reimplement anything — it is to let the
+  caller supply what the library would otherwise have loaded.
+
+  **`sdk?: McpSdk`** — hand over the two SDK modules, imported statically by your
+  own bundler, and the library **still builds the transport**. Everything the
+  transport carries keeps working: `headers`, your own `fetch`, gateway
+  vending, `retryOnThrottle`, `_meta` ingestion.
+
+  ```ts
+  import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+  import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+  import { mcpClient } from 'agentfootprint/providers';
+
+  const sidecar = await mcpClient({
+    name: 'sidecar',
+    sdk: { Client, StreamableHTTPClientTransport },
+    transport: { transport: 'http', url: '/py/mcp' },
+  });
+  const tools = await sidecar.tools();   // the same readonly Tool[], _meta and all
+  ```
+
+  **`connection?: McpConnection`** — the full escape hatch: you connect the
+  client, the library only adapts its tools. Three methods over JSON-RPC and no
+  vendor named, so an SDK `Client`, a fake, or a future fetch-only transport all
+  satisfy it. `connect()` is deliberately **absent** from the type: you already
+  connected it, and the library never calls it. Reach for this when the library
+  must not construct anything — a strict CSP, where the SDK's own
+  `jsonSchemaValidator` (reachable only here) is what keeps ajv's `new Function`
+  off the page.
+
+  **The refusals are the design.** On the `connection` arm the library builds no
+  transport, so every option consumed INSIDE one is refused at construction,
+  naming where the behaviour went — `retryOnThrottle`, `clientInfo`, `transport`,
+  `sdk`, `_client`. Accepting a knob that names a behaviour which no longer
+  happens is the defect class this release exists to close, not a convenience.
+  `signal` IS honoured on both arms: it rides the SDK's request options.
+
+- **`retryingFetch` is public** (`agentfootprint/providers`), with
+  `ThrottleFetch`. It was `@internal`, and on the `connection` arm — the one a
+  browser takes — a caller would otherwise have silently lost the HTTP 429
+  handling every Node consumer gets ON by default. Same implementation, applied
+  where you build the transport: `fetch: retryingFetch(yourFetch, { maxAttempts: 5 })`.
+
+### Fixed
+
+- **A relative `transport.url` resolves against the page.** `new URL('/py/mcp')`
+  throws `TypeError: Invalid URL` — correct in Node, wrong in a browser, where a
+  same-origin path is the ordinary way to reach a sidecar (and the way to avoid a
+  CORS preflight entirely). It now resolves against `globalThis.location.href`
+  when there is one, and in Node refuses **by name**, saying which world it is in
+  and to pass an absolute URL. An absolute url takes the identical first branch,
+  so Node behaviour has not moved.
+
+- **The SDK-load errors stop lying.** Every load sat behind a bare `catch`, which
+  cannot tell "the package is absent" from "the LOADER is absent" — so a browser
+  that had the SDK installed all along was told to `npm install` it, and nothing
+  changed when it did. The failure is now classified at all seven sites (three in
+  `mcpClient`, four in `mcpServe`): a resolution failure produces the
+  **byte-identical** message every release before this one produced, and anything
+  else names the underlying error and the seam that gets past it. `mcpServe` says
+  the honest thing instead — it listens on stdio or a Node socket, so that
+  direction cannot run in a browser at all.
+
+### Unchanged, deliberately
+
+- **Zero packaging change.** No new subpath, no `browser` export condition (a
+  compiler is blind to it), no `typesVersions` row, no `postbuild-esm.mjs` edit.
+  `@modelcontextprotocol/sdk` stays an OPTIONAL peer, and there is no literal
+  dynamic `import()` of it anywhere — one would be statically resolved by a
+  bundler and would hard-fail the build for every consumer who does not have it.
+
+- **Every existing Node consumer.** A call with neither `sdk` nor `connection`
+  reaches the same `lazyRequire` on the same specifiers and builds the same
+  transport; the difference is a `??` on an `undefined` parameter. `stdio` keeps
+  the loader permanently — it spawns a subprocess, so it can never be portable,
+  and keeping it there is what keeps the SDK's one Node-importing client module
+  off every browser graph.
+
+### Proof, and its limits
+
+`test/lib/mcp/browserGraph.test.ts` bundles the SHIPPED `dist/` the way a browser
+build does and asserts: `agentfootprint/providers` still bundles with the MCP SDK
+**blocked at resolve time** (the optional-peer property, stated as a build); its
+`node:` edges are EXACTLY the two known ones; the builtins hidden behind
+`lazyRequire` — which no module graph can see — are exactly the four known ones;
+the path a browser walks reaches `node:module` and nothing else and never pulls
+in `client/stdio.js`; and everything on that path except the loader bundles with
+NO externals and zero node edges. `mcpConnection.real.test.ts` drives both new
+arms through a real socket against the real SDK.
+
+**What none of that proves: a browser.** This repo has no browser test
+environment, so nobody has yet driven initialize/listTools/callTool from an
+actual page. The honest status is *proven in Node, fenced at the graph, not gated
+in a browser.* Three costs land on the app, not here: your server must send CORS
+headers (every MCP request preflights, and `Mcp-Session-Id` must be in
+`Access-Control-Expose-Headers`) — `mcpServe` sends none; SSE through a dev or
+production proxy is unproven; and the SDK's client path adds roughly 260 KB
+minified, about half of it ajv, whose `new Function` needs `unsafe-eval` the
+first time a tool with an `outputSchema` is validated.
+
 ## [9.80.0] - 2026-08-30
 
 ### Added

package/CLAUDE.md

@@ -17,7 +17,9 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 
 | If you are about to build… | It is | Where | Since |
 |---|---|---|---|
-| turning a written operational procedure (a runbook, a triage playbook) into ONE agent tool whose every answer is EVIDENCE — coverage folded up from the inner tools it calls, rule name+version, verdict rows with GENERATED meanings, and the recorded walk as an artifact ticket, never bytes | `runbookAsTool` — dials: `procedure` (factory, invoked per call with `ctx.tools`) + `resultKind` (`'verdict/*'` arms the rowset projection; anything else ships spine + the chart's `report`) + `rules {name, version}` (default absent ⇒ `rule_version: 'undeclared'`) + `verdicts {decider, maxRows}` (default 50) + `presentation` (`'prose'` default = ship `table` + `VERDICT_RENDER_NOTE` "output it VERBATIM"; `'panel'` = the HOST renders the rowset, so NO `table` key at all + `PANEL_RENDER_NOTE` "the rows are already on the reader's screen — do not reproduce them"; the rowset half is byte-identical across modes, `table` stays RESERVED in both, an unknown value THROWS at definition) + `walk {cap, recording}` (cap default 500; over-cap ⇒ control-flow projection, declared · `recording: true` or `{label, maxBytes}`, default OFF — ALSO files the inner chart's own `{snapshot, events, structure}` under `recording/run` and puts its ref on the spine as `walk.recording_ref`, because the ROW projection cannot be drawn; snapshot read from the REDACTED mirror so one `redact` means the same for both; over `maxBytes` (`DEFAULT_RECORDING_MAX_BYTES` = 5,000,000) it is REFUSED not truncated; every absence — no store / over size / unserializable / store threw — is STATED in `walk.recording_note`, and the four `recording_*` fields are absent entirely when the dial is off) + `composedOf` (drift-checked at agent BUILD) + kept `recorders`/`keepRecord`/`keepRecordLimit`/`redact`; reserved state keys `verdicts`/`coverage`/`report` (the `report` bag lands BESIDE the spine, never over it — a report field spelling `af_coverage`/`af_provenance`/`rule_version`/`walk`/`report_note` or a live projection key is discarded and NAMED in `result.report_note`; precedence is explicit in `report.ts`, never spread order); inner `absent()` passes through VERBATIM unless the call said `allowAbsent`; walk kind `recording/chart-walk` + `walk_segment` discriminant | `src/core/runbook/` | 9.76.0, recording 9.79.0 |
+| turning a written operational procedure (a runbook, a triage playbook) into ONE agent tool whose every answer is EVIDENCE — coverage folded up from the inner tools it calls, rule name+version, verdict rows with GENERATED meanings, and the recorded walk as an artifact ticket, never bytes | `runbookAsTool` — dials: `procedure` (factory, invoked per call with `ctx.tools`) + `resultKind` (`'verdict/*'` arms the rowset projection; anything else ships spine + the chart's `report`) + `rules {name, version}` (default absent ⇒ `rule_version: 'undeclared'`) + `verdicts {decider, maxRows}` (default 50; `verdict_meanings` = statically declared branches + this run's rule labels + the DEFAULT branch's label, which reaches evidence only when the chart calls `decide(s, rules, {branch, label})` — fp ≥9.16.1, the default is chosen by NO rule so nothing else can name it, and inside a generated fan-out branch the static walk is blind too; an undeclared or blank label stays ABSENT from the map, never invented from a branch id, and there is deliberately NO caller-supplied meanings map) + `presentation` (`'prose'` default = ship `table` + `VERDICT_RENDER_NOTE` "output it VERBATIM"; `'panel'` = the HOST renders the rowset, so NO `table` key at all + `PANEL_RENDER_NOTE` "the rows are already on the reader's screen — do not reproduce them"; the rowset half is byte-identical across modes, `table` stays RESERVED in both, an unknown value THROWS at definition) + `walk {cap, recording}` (cap default 500; over-cap ⇒ control-flow projection, declared · `recording: true` or `{label, maxBytes}`, default OFF — ALSO files the inner chart's own `{snapshot, events, structure}` under `recording/run` and puts its ref on the spine as `walk.recording_ref`, because the ROW projection cannot be drawn; snapshot read from the REDACTED mirror so one `redact` means the same for both; over `maxBytes` (`DEFAULT_RECORDING_MAX_BYTES` = 5,000,000) it is REFUSED not truncated; every absence — no store / over size / unserializable / store threw — is STATED in `walk.recording_note`, and the four `recording_*` fields are absent entirely when the dial is off) + `composedOf` (drift-checked at agent BUILD) + kept `recorders`/`keepRecord`/`keepRecordLimit`/`redact`; reserved state keys `verdicts`/`coverage`/`report` (the `report` bag lands BESIDE the spine, never over it — a report field spelling `af_coverage`/`af_provenance`/`rule_version`/`walk`/`report_note` or a live projection key is discarded and NAMED in `result.report_note`; precedence is explicit in `report.ts`, never spread order); inner `absent()` passes through VERBATIM unless the call said `allowAbsent`; walk kind `recording/chart-walk` + `walk_segment` discriminant | `src/core/runbook/` | 9.76.0, recording 9.79.0 |
+| speaking MCP from a BROWSER — the SDK is browser-clean (its client + streamableHttp bundle at `platform:'browser'` with zero `node:` edges and never pull in `client/stdio.js`); the one barrier was that `lazyRequire` gets CALLED there, so the fix is to let the caller supply what the loader would have found | `mcpClient({ sdk })` (`McpSdk` = the two SDK modules you imported statically; the library STILL builds the transport, so headers/fetch/gateway vending/`retryOnThrottle`/`_meta` all keep working) · `mcpClient({ connection })` (`McpConnection` = listTools/callTool/close, deliberately NO `connect` — you already did; the only arm that reaches the SDK's `jsonSchemaValidator`, i.e. CSP) + `McpConnectionOptions`; `refuseConflictingOptions` REFUSES at construction every option a transport would have consumed, naming where it moved (a knob naming a behaviour that no longer happens is the defect class); `transportUrl` resolves a relative `url` against `globalThis.location.href` (absolute takes the identical branch, Node refuses by name); `sdkLoadFailure` classifies the seven load sites so a browser is never told to install a package it has (resolution failure ⇒ byte-identical historical message); `retryingFetch` + `ThrottleFetch` promoted out of `@internal` so the connection arm keeps its 429 handling. stdio keeps `lazyRequire` FOREVER — it spawns a subprocess. ZERO packaging change: no subpath, no `browser` condition (TypeScript is blind to it), peer stays optional (no literal dynamic `import()`). Fenced by `test/lib/mcp/browserGraph.test.ts` | `src/lib/mcp/` | 9.81.0 |
+| calling ANOTHER registered tool from inside a tool's `execute` — composition over the agent's own dispatch map instead of importing the module and building a second query stack | `agentToolDispatch` + `ctx.tools` (ToolDispatch has/call) — sees static and skill-carried tools, NEVER ToolProvider-delivered ones (no build-time list, the 9.72.0 caveat); inner calls get the outer facts with hasArtifacts false and a derived toolCallId, `needs` resolved fail-closed non-interactively, `checkIn` and `wants` tools refused by name, no nested dispatch; declare ingredients via `composedOf` (and `gates` for a pausing procedure) — both travel MCP `_meta` | `src/core/agent/toolDispatch.ts` | 9.76.0 |
 | a tool returning numbers WITH the caveats that make them honest — interval/aggregation grain, is-it-a-counter, when the world was measured, which ground was NOT covered — as typed data the model reads compactly and the record keeps whole | `semantic()` + `tools.semantics_declared` (model sees `semanticsForModel` projection; `coverage` field absorbed by the coverage()/absent() channel) | `src/lib/semantics/` | 9.53.0 |
 | a build gate that refuses a triage/inventory tool that forgot its caveats, by tool name and field name | `checkSemantics` + `defineTool({ resultClass })` (`'triage'`/`'inventory'`, the closed set) + bin `agentfootprint-check-semantics` | `src/lib/semantics/check.ts` | 9.53.0 |
 | an agent that runs out of `maxIterations` mid-task handing back a HALF-SENTENCE as its answer — and nothing saying the budget ran out | `wrapUpAtMaxIterations` (default ON) + `WRAP_UP_INSTRUCTION` + `agent.budget_exhausted` + `stoppedEarly.wrappedUp` | `src/core/agent/stages/wrapUp.ts` | 9.56.0 |

package/dist/core/runbook/verdicts.js

@@ -24,10 +24,21 @@
  * GENERATED MEANINGS, never hand-restated: `verdict_meanings` is composed
  * from (a) the named decider's declared branches in the chart's own structure
  * (branch description, falling back to branch name), overlaid by (b) the rule
- * LABELS this run's decide() evidence carried — the rule speaking for itself.
+ * LABELS this run's decide() evidence carried — the rule speaking for itself —
+ * and (c) the DEFAULT branch's declared label, carried by the same evidence.
  * A decider inside a dynamically generated fan-out branch is invisible to (a)
  * by construction (the branch chart does not exist at build time); (b) still
  * covers every verdict an executed rule produced.
+ *
+ * (c) exists because the default branch is chosen by NO rule — it fires
+ * exactly when every rule failed, so it appears in no `rules[]` entry and (b)
+ * can never name it. In a generated fan-out branch, where (a) is blind too, it
+ * was the one verdict the rowset could show and the meanings map could not
+ * explain. `decide(scope, rules, { branch, label })` (footprintjs ≥ 9.16.1) puts
+ * that label on the decision evidence, so it arrives here the way every other
+ * label does: harvested from the run, never declared at this boundary. There is
+ * deliberately no caller-supplied meanings map — a map a caller can write is a
+ * map that can describe rules that never ran.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.composeMeanings = exports.meaningsRecorder = exports.resolveDecider = exports.renderVerdictTable = exports.verdictRowsOf = exports.DECLINED_VERDICT = exports.PANEL_RENDER_NOTE = exports.VERDICT_RENDER_NOTE = exports.DEFAULT_MAX_ROWS = void 0;
@@ -132,11 +143,17 @@ function resolveDecider(chart, decider) {
     return { spellings, declared };
 }
 exports.resolveDecider = resolveDecider;
+/** A label is a meaning only when it says something — a blank one is recorded
+ *  as no meaning at all, never as a verdict that means the empty string. */
+function meaningful(label) {
+    return typeof label === 'string' && label.length > 0;
+}
 /**
  * A tiny flow recorder capturing the named decider's decide() evidence as it
  * fires — collected DURING the traversal, never reconstructed after. Rule
  * labels are harvested for every rule the evidence lists (matched or not):
- * a rule that was evaluated has spoken its label, whichever branch won.
+ * a rule that was evaluated has spoken its label, whichever branch won. The
+ * DEFAULT branch's label rides the same evidence and is harvested with them.
  *
  * A decider inside a subflow (including a generated fan-out branch) reports
  * itself PATH-PREFIXED (`per-subject~0/Protection posture`), so the match is
@@ -153,8 +170,14 @@ function meaningsRecorder(identity) {
             if (!identity.spellings.has(lastSegment(event.decider)))
                 return;
             const evidence = event.evidence;
+            // The default first, the rules over it. The default is the branch NO
+            // rule chose, so it is normally the only speaker for its own name; where
+            // a rule also routes to it, the rule is the sharper sentence and wins.
+            if (typeof evidence?.default === 'string' && meaningful(evidence.defaultLabel)) {
+                observed.set(evidence.default, evidence.defaultLabel);
+            }
             for (const rule of evidence?.rules ?? []) {
-                if (typeof rule.branch === 'string' && typeof rule.label === 'string') {
+                if (typeof rule.branch === 'string' && meaningful(rule.label)) {
                     observed.set(rule.branch, rule.label);
                 }
             }
@@ -163,9 +186,10 @@ function meaningsRecorder(identity) {
     return { recorder, observed };
 }
 exports.meaningsRecorder = meaningsRecorder;
-/** Compose the final meanings: declared branches first, observed rule labels
- *  winning where both speak (the rule is the sharper sentence). Undefined
- *  when neither source produced anything — absent, never `{}`. */
+/** Compose the final meanings: declared branches first, the labels this run
+ *  observed (rule labels, and the default branch's own) winning where both
+ *  speak — the declaration made beside the rules is the sharper sentence.
+ *  Undefined when neither source produced anything — absent, never `{}`. */
 function composeMeanings(identity, observed) {
     const meanings = {};
     for (const [branch, meaning] of identity.declared)

package/dist/core/runbook/verdicts.js.map

@@ -1 +1 @@
-{"version":3,"file":"verdicts.js","sourceRoot":"","sources":["../../../src/core/runbook/verdicts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"verdicts.js","sourceRoot":"","sources":["../../../src/core/runbook/verdicts.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;;;AAMH,6DAA6D;AAChD,QAAA,gBAAgB,GAAG,EAAE,CAAC;AAEnC;qEACqE;AACxD,QAAA,mBAAmB,GAC9B,qFAAqF;IACrF,wFAAwF;IACxF,kDAAkD,CAAC;AAErD;;;;;;;GAOG;AACU,QAAA,iBAAiB,GAC5B,oFAAoF;IACpF,sFAAsF;IACtF,wFAAwF;IACxF,wFAAwF;IACxF,qFAAqF;IACrF,oEAAoE,CAAC;AAEvE;;yEAEyE;AAC5D,QAAA,gBAAgB,GAAG,UAAU,CAAC;AAE3C;4EAC4E;AAC5E,SAAgB,aAAa,CAAC,KAAwC;IACpE,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC;IAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,OAAO,GAAG,CAAC,MAAM,CACf,CAAC,GAAG,EAAqB,EAAE,CACzB,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QACnB,OAAQ,GAA6B,CAAC,OAAO,KAAK,QAAQ,CAC7D,CAAC;AACJ,CAAC;AAVD,sCAUC;AAED;kEACkE;AAClE,SAAS,IAAI,CAAC,KAAc;IAC1B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,GAAG,CAAC;IACtE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACjC,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,IAA2B;IAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,+BAA+B,CAAC;IAC9D,oEAAoE;IACpE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;IACrF,OAAO,CACL,IAAI;QACJ,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC9F,CAAC;AACJ,CAAC;AATD,gDASC;AAwBD;;;;GAIG;AACH,SAAgB,cAAc,CAAC,KAAgB,EAAE,OAAe;IAC9D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAY,CAAC;IACpC,MAAM,IAAI,GAAG,CAAC,IAA0B,EAAQ,EAAE;QAChD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO;QAC/E,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;YACvF,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS;gBAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAClD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;gBAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBACxC,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,EAAE,CAAC;gBAC1C,IAAI,MAAM,KAAK,SAAS;oBAAE,SAAS;gBACnC,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC;gBAChD,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC;oBAAE,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACpF,CAAC;QACH,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE;YAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,IAAI,CAAC,KAAK,CAAC,IAAgB,CAAC,CAAC;IAC7B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,OAAO,CAAC,IAAgB,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AACjC,CAAC;AAzBD,wCAyBC;AAQD;4EAC4E;AAC5E,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,gBAAgB,CAAC,QAAyB;IACxD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,WAAW,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACpF,MAAM,QAAQ,GAAG;QACf,EAAE,EAAE,0BAA0B;QAC9B,UAAU,CAAC,KAAwB;YACjC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAAE,OAAO;YAChE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAMV,CAAC;YACd,qEAAqE;YACrE,yEAAyE;YACzE,uEAAuE;YACvE,IAAI,OAAO,QAAQ,EAAE,OAAO,KAAK,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC/E,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;YACxD,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;gBACzC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC9D,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC;QACH,CAAC;KAC6B,CAAC;IACjC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC;AA5BD,4CA4BC;AAED;;;4EAG4E;AAC5E,SAAgB,eAAe,CAC7B,QAAyB,EACzB,QAAqC;IAErC,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,QAAQ;QAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;IAC9E,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,QAAQ;QAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;IACjE,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AARD,0CAQC"}

package/dist/esm/core/runbook/types.d.ts

@@ -57,6 +57,14 @@ export interface RunbookVerdictsOptions {
      * in this run's decide() evidence refine them (and are the only source
      * when the decider lives inside a dynamically generated fan-out branch,
      * where build-time structure cannot see it).
+     *
+     * The DEFAULT branch is chosen by no rule, so no rule label describes it.
+     * Name it where the rules are named — `decide(scope, rules, { branch,
+     * label })` — and the label arrives here on the same evidence:
+     *
+     * ```ts
+     * decide(scope, rules, { branch: 'protected', label: 'No rule fired — asset stays protected' });
+     * ```
      */
     readonly decider: string;
     /** Cap on `verdicts` rows AND the rendered table — ONE number for both

package/dist/esm/core/runbook/verdicts.d.ts

@@ -23,10 +23,21 @@
  * GENERATED MEANINGS, never hand-restated: `verdict_meanings` is composed
  * from (a) the named decider's declared branches in the chart's own structure
  * (branch description, falling back to branch name), overlaid by (b) the rule
- * LABELS this run's decide() evidence carried — the rule speaking for itself.
+ * LABELS this run's decide() evidence carried — the rule speaking for itself —
+ * and (c) the DEFAULT branch's declared label, carried by the same evidence.
  * A decider inside a dynamically generated fan-out branch is invisible to (a)
  * by construction (the branch chart does not exist at build time); (b) still
  * covers every verdict an executed rule produced.
+ *
+ * (c) exists because the default branch is chosen by NO rule — it fires
+ * exactly when every rule failed, so it appears in no `rules[]` entry and (b)
+ * can never name it. In a generated fan-out branch, where (a) is blind too, it
+ * was the one verdict the rowset could show and the meanings map could not
+ * explain. `decide(scope, rules, { branch, label })` (footprintjs ≥ 9.16.1) puts
+ * that label on the decision evidence, so it arrives here the way every other
+ * label does: harvested from the run, never declared at this boundary. There is
+ * deliberately no caller-supplied meanings map — a map a caller can write is a
+ * map that can describe rules that never ran.
  */
 import type { CombinedRecorder } from 'footprintjs';
 import type { FlowChart } from 'footprintjs';
@@ -80,7 +91,8 @@ export interface MeaningsHarvest {
  * A tiny flow recorder capturing the named decider's decide() evidence as it
  * fires — collected DURING the traversal, never reconstructed after. Rule
  * labels are harvested for every rule the evidence lists (matched or not):
- * a rule that was evaluated has spoken its label, whichever branch won.
+ * a rule that was evaluated has spoken its label, whichever branch won. The
+ * DEFAULT branch's label rides the same evidence and is harvested with them.
  *
  * A decider inside a subflow (including a generated fan-out branch) reports
  * itself PATH-PREFIXED (`per-subject~0/Protection posture`), so the match is
@@ -89,7 +101,8 @@ export interface MeaningsHarvest {
  * marker opaque here.
  */
 export declare function meaningsRecorder(identity: DeciderIdentity): MeaningsHarvest;
-/** Compose the final meanings: declared branches first, observed rule labels
- *  winning where both speak (the rule is the sharper sentence). Undefined
- *  when neither source produced anything — absent, never `{}`. */
+/** Compose the final meanings: declared branches first, the labels this run
+ *  observed (rule labels, and the default branch's own) winning where both
+ *  speak — the declaration made beside the rules is the sharper sentence.
+ *  Undefined when neither source produced anything — absent, never `{}`. */
 export declare function composeMeanings(identity: DeciderIdentity, observed: ReadonlyMap<string, string>): Record<string, string> | undefined;

package/dist/esm/core/runbook/verdicts.js

@@ -23,10 +23,21 @@
  * GENERATED MEANINGS, never hand-restated: `verdict_meanings` is composed
  * from (a) the named decider's declared branches in the chart's own structure
  * (branch description, falling back to branch name), overlaid by (b) the rule
- * LABELS this run's decide() evidence carried — the rule speaking for itself.
+ * LABELS this run's decide() evidence carried — the rule speaking for itself —
+ * and (c) the DEFAULT branch's declared label, carried by the same evidence.
  * A decider inside a dynamically generated fan-out branch is invisible to (a)
  * by construction (the branch chart does not exist at build time); (b) still
  * covers every verdict an executed rule produced.
+ *
+ * (c) exists because the default branch is chosen by NO rule — it fires
+ * exactly when every rule failed, so it appears in no `rules[]` entry and (b)
+ * can never name it. In a generated fan-out branch, where (a) is blind too, it
+ * was the one verdict the rowset could show and the meanings map could not
+ * explain. `decide(scope, rules, { branch, label })` (footprintjs ≥ 9.16.1) puts
+ * that label on the decision evidence, so it arrives here the way every other
+ * label does: harvested from the run, never declared at this boundary. There is
+ * deliberately no caller-supplied meanings map — a map a caller can write is a
+ * map that can describe rules that never ran.
  */
 /** Default cap on `verdicts` rows and the rendered table. */
 export const DEFAULT_MAX_ROWS = 50;
@@ -126,11 +137,17 @@ export function resolveDecider(chart, decider) {
     }
     return { spellings, declared };
 }
+/** A label is a meaning only when it says something — a blank one is recorded
+ *  as no meaning at all, never as a verdict that means the empty string. */
+function meaningful(label) {
+    return typeof label === 'string' && label.length > 0;
+}
 /**
  * A tiny flow recorder capturing the named decider's decide() evidence as it
  * fires — collected DURING the traversal, never reconstructed after. Rule
  * labels are harvested for every rule the evidence lists (matched or not):
- * a rule that was evaluated has spoken its label, whichever branch won.
+ * a rule that was evaluated has spoken its label, whichever branch won. The
+ * DEFAULT branch's label rides the same evidence and is harvested with them.
  *
  * A decider inside a subflow (including a generated fan-out branch) reports
  * itself PATH-PREFIXED (`per-subject~0/Protection posture`), so the match is
@@ -147,8 +164,14 @@ export function meaningsRecorder(identity) {
             if (!identity.spellings.has(lastSegment(event.decider)))
                 return;
             const evidence = event.evidence;
+            // The default first, the rules over it. The default is the branch NO
+            // rule chose, so it is normally the only speaker for its own name; where
+            // a rule also routes to it, the rule is the sharper sentence and wins.
+            if (typeof evidence?.default === 'string' && meaningful(evidence.defaultLabel)) {
+                observed.set(evidence.default, evidence.defaultLabel);
+            }
             for (const rule of evidence?.rules ?? []) {
-                if (typeof rule.branch === 'string' && typeof rule.label === 'string') {
+                if (typeof rule.branch === 'string' && meaningful(rule.label)) {
                     observed.set(rule.branch, rule.label);
                 }
             }
@@ -156,9 +179,10 @@ export function meaningsRecorder(identity) {
     };
     return { recorder, observed };
 }
-/** Compose the final meanings: declared branches first, observed rule labels
- *  winning where both speak (the rule is the sharper sentence). Undefined
- *  when neither source produced anything — absent, never `{}`. */
+/** Compose the final meanings: declared branches first, the labels this run
+ *  observed (rule labels, and the default branch's own) winning where both
+ *  speak — the declaration made beside the rules is the sharper sentence.
+ *  Undefined when neither source produced anything — absent, never `{}`. */
 export function composeMeanings(identity, observed) {
     const meanings = {};
     for (const [branch, meaning] of identity.declared)

package/dist/esm/core/runbook/verdicts.js.map

@@ -1 +1 @@
-{"version":3,"file":"verdicts.js","sourceRoot":"","sources":["../../../../src/core/runbook/verdicts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"verdicts.js","sourceRoot":"","sources":["../../../../src/core/runbook/verdicts.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/mcp/connectionRefusals.d.ts

@@ -0,0 +1,30 @@
+/**
+ * connectionRefusals — the two arms of `mcpClient` refuse to be mixed, at
+ * CONSTRUCTION, in words that name where the behaviour went.
+ *
+ * ── Why refuse rather than ignore ────────────────────────────────────────────
+ * `mcpClient({ connection })` hands over a client somebody else built, so this
+ * library builds no transport on that arm — and every option consumed INSIDE a
+ * transport therefore has nothing to act on. `retryOnThrottle` is the sharp
+ * one: it is ON by default, it is consumed by `retryingFetch` around the
+ * transport's `fetch`, and accepting it here would leave a caller holding an
+ * option that NAMES a behaviour which no longer happens. A knob that lies about
+ * what it does is worse than one that is absent, so these throw.
+ *
+ * The type union refuses the same combinations at compile time
+ * (`McpConnectionOptions` declares each of them `?: undefined`). This is the
+ * runtime half, and it is not redundant: excess-property checking does not
+ * survive a spread, and JavaScript callers have no compiler at all.
+ *
+ * Pattern: pure guard. Role: Layer-3 tool integration.
+ */
+import type { McpClientOptions, McpConnectionOptions } from './types.js';
+/**
+ * Refuse a mixed or malformed options object before anything connects.
+ *
+ * @param opts what the caller passed, before any defaulting
+ * @param name the client's logical name, so a multi-server app knows which one
+ * @throws naming the two options that cannot travel together, or the member the
+ *   connection is missing
+ */
+export declare function refuseConflictingOptions(opts: McpClientOptions | McpConnectionOptions, name: string): void;

package/dist/esm/lib/mcp/connectionRefusals.js

@@ -0,0 +1,110 @@
+/**
+ * connectionRefusals — the two arms of `mcpClient` refuse to be mixed, at
+ * CONSTRUCTION, in words that name where the behaviour went.
+ *
+ * ── Why refuse rather than ignore ────────────────────────────────────────────
+ * `mcpClient({ connection })` hands over a client somebody else built, so this
+ * library builds no transport on that arm — and every option consumed INSIDE a
+ * transport therefore has nothing to act on. `retryOnThrottle` is the sharp
+ * one: it is ON by default, it is consumed by `retryingFetch` around the
+ * transport's `fetch`, and accepting it here would leave a caller holding an
+ * option that NAMES a behaviour which no longer happens. A knob that lies about
+ * what it does is worse than one that is absent, so these throw.
+ *
+ * The type union refuses the same combinations at compile time
+ * (`McpConnectionOptions` declares each of them `?: undefined`). This is the
+ * runtime half, and it is not redundant: excess-property checking does not
+ * survive a spread, and JavaScript callers have no compiler at all.
+ *
+ * Pattern: pure guard. Role: Layer-3 tool integration.
+ */
+/** The three methods this library calls on a connection. Nothing else. */
+const CONNECTION_METHODS = ['listTools', 'callTool', 'close'];
+/**
+ * Refuse a mixed or malformed options object before anything connects.
+ *
+ * @param opts what the caller passed, before any defaulting
+ * @param name the client's logical name, so a multi-server app knows which one
+ * @throws naming the two options that cannot travel together, or the member the
+ *   connection is missing
+ */
+export function refuseConflictingOptions(opts, name) {
+    const at = `mcpClient[${name}]`;
+    // Read through a permissive view on purpose. The union already narrows these
+    // combinations away at compile time, so narrowing here would leave the guard
+    // reasoning about a shape it exists precisely to disbelieve — an object built
+    // by a spread, or by JavaScript.
+    const given = opts;
+    if (given['connection'] === undefined) {
+        if (given['transport'] === undefined && given['_client'] === undefined) {
+            throw new Error(`${at}: nothing to connect to. Pass \`transport\` (the library builds the connection) ` +
+                'or `connection` (a client you connected yourself).');
+        }
+        return;
+    }
+    // From here on the caller chose the `connection` arm.
+    for (const [option, moved] of BUILT_BY_THE_TRANSPORT) {
+        if (given[option] !== undefined) {
+            throw new Error(`${at}: \`connection\` and \`${option}\` cannot travel together. ` +
+                `A connection you built yourself carries its own transport, and \`${option}\` is ` +
+                `consumed inside the transport this library did not build. ${moved}`);
+        }
+    }
+    assertConnection(given['connection'], at);
+}
+/**
+ * The options that only exist because the library builds the transport, each
+ * paired with the sentence naming where that behaviour moved to. Ordered so the
+ * most surprising loss — throttle retry, which is ON by default — is named
+ * first when a caller passes several.
+ */
+const BUILT_BY_THE_TRANSPORT = [
+    [
+        'retryOnThrottle',
+        'Wrap your own `fetch` with `retryingFetch(yourFetch, options)` (exported from ' +
+            '`agentfootprint/providers`) and hand THAT to your transport — it is the same ' +
+            'implementation, applied where you build it.',
+    ],
+    [
+        'clientInfo',
+        'Pass it to the SDK `Client` constructor instead: `new Client(clientInfo, { capabilities: {} })`.',
+    ],
+    [
+        'transport',
+        'Drop one of the two: `transport` asks the library to connect, `connection` says it already is.',
+    ],
+    [
+        'sdk',
+        '`sdk` exists so the library can build the transport without its Node loader; ' +
+            'on this arm you have already built it.',
+    ],
+    [
+        '_client',
+        '`_client` is the same idea as `connection` and predates it — pass `connection` alone.',
+    ],
+];
+/**
+ * A connection is only a connection if it can be called.
+ *
+ * This catches the near-miss people actually make: handing over the TRANSPORT
+ * rather than the client. A transport has none of these three methods, and
+ * without this check it fails on the first `tools()`, one stack frame deep
+ * inside the SDK.
+ *
+ * The OTHER near-miss — a `Client` that was constructed but never `connect()`ed
+ * — cannot be caught here, because it has all three methods. It is named in the
+ * message anyway, since it produces the same "my connection does not work" and
+ * the SDK's own "Not connected" is the thing to look for.
+ */
+function assertConnection(connection, at) {
+    const members = (connection ?? {});
+    for (const method of CONNECTION_METHODS) {
+        if (typeof members[method] !== 'function') {
+            throw new Error(`${at}: \`connection\` has no \`${method}()\`. It must be an MCP client that is ` +
+                'already connected, and the likely mistake is passing the TRANSPORT instead of the ' +
+                'client. (A `new Client(...)` you never awaited `connect()` on passes this check ' +
+                'and fails later with the SDK\'s own "Not connected".)');
+        }
+    }
+}
+//# sourceMappingURL=connectionRefusals.js.map

package/dist/esm/lib/mcp/connectionRefusals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionRefusals.js","sourceRoot":"","sources":["../../../../src/lib/mcp/connectionRefusals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,0EAA0E;AAC1E,MAAM,kBAAkB,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAU,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAA6C,EAC7C,IAAY;IAEZ,MAAM,EAAE,GAAG,aAAa,IAAI,GAAG,CAAC;IAChC,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,iCAAiC;IACjC,MAAM,KAAK,GAAG,IAAoD,CAAC;IAEnE,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;YACvE,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,kFAAkF;gBACrF,oDAAoD,CACvD,CAAC;QACJ,CAAC;QACD,OAAO;IACT,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,sBAAsB,EAAE,CAAC;QACrD,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,0BAA0B,MAAM,6BAA6B;gBAChE,oEAAoE,MAAM,QAAQ;gBAClF,6DAA6D,KAAK,EAAE,CACvE,CAAC;QACJ,CAAC;IACH,CAAC;IACD,gBAAgB,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,sBAAsB,GAExB;IACF;QACE,iBAAiB;QACjB,gFAAgF;YAC9E,+EAA+E;YAC/E,6CAA6C;KAChD;IACD;QACE,YAAY;QACZ,kGAAkG;KACnG;IACD;QACE,WAAW;QACX,gGAAgG;KACjG;IACD;QACE,KAAK;QACL,+EAA+E;YAC7E,wCAAwC;KAC3C;IACD;QACE,SAAS;QACT,uFAAuF;KACxF;CACF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,SAAS,gBAAgB,CAAC,UAAmB,EAAE,EAAU;IACvD,MAAM,OAAO,GAAG,CAAC,UAAU,IAAI,EAAE,CAAsC,CAAC;IACxE,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,IAAI,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,UAAU,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,6BAA6B,MAAM,yCAAyC;gBAC/E,oFAAoF;gBACpF,kFAAkF;gBAClF,uDAAuD,CAC1D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}