mcp-google-multi 6.0.0-beta.3 → 6.0.0-beta.4

package/dist/registry.js

@@ -10,9 +10,8 @@ import { hints } from './hint-provider.js';
 /** Nothing granted, no profile: asks the BUNDLE CATALOG whether a scope is
  * reachable at all, independently of any account. */
 const EMPTY_SCOPES = new Set();
-// Client-side result budget advertised for tools that do not declare their own
-// (fat readers do; see trim.ts). ~50k chars stays well inside a default client
-// context limit while leaving room for real list payloads.
+// Client-side result budget for tools that do not declare their own (fat
+// readers do; see trim.ts); stays well inside a default client context limit.
 const DEFAULT_MAX_RESULT_CHARS = 50_000;
 const DISCOVERY_MODES = ['lazy', 'curated', 'eager'];
 export function resolveDiscoveryMode(env = process.env) {
@@ -29,9 +28,8 @@ const CUD_OVERRIDES = {
     drive_transfer: 'create',
     // read-only resolver; the name's "resolve" verb would otherwise infer update.
     contacts_resolve: 'read',
-    // Account management is gated by anthropic/requiresUserInteraction (forced
-    // human approval), NOT the Google-data write-control profile — so onboarding
-    // works under any profile. cud=read also keeps them off the fan-out path.
+    // Gated by anthropic/requiresUserInteraction, not write-control, so
+    // onboarding works under any profile; cud=read also keeps them off fan-out.
     account_add: 'read',
     account_reauth: 'read',
     // Writes a LOCAL MCP-client config, not Google data; gated by
@@ -47,10 +45,11 @@ export function serviceOf(name) {
 }
 // read tools that write local files — same savePath fanned across accounts would clobber
 const FANOUT_EXCLUDE = new Set(['gmail_download_attachment', 'drive_download', 'drive_export']);
-/** Account-management tools: the `account` they take is the SUBJECT of the
- * operation, not the identity it runs as, so injecting the configured default
- * would silently retarget them. `account_add` would adopt the default as the
- * new alias, and `account_reauth` would re-authenticate the wrong account. */
+// cud=read for gating/fan-out, yet they write (local files, the account
+// registry, config): advertised as writes so annotation-keyed clients prompt.
+const WRITES_DESPITE_READ = new Set([...FANOUT_EXCLUDE, 'account_add', 'account_reauth', 'account_write_config']);
+// Their `account` is the SUBJECT of the operation (e.g. the new alias to add),
+// not the identity to run as, so injecting the configured default would retarget them.
 const DEFAULT_ACCOUNT_EXCLUDE = new Set(['account_add', 'account_reauth']);
 /** Unwrap optional/default/nullable to the declared scalar kind (zod 4 defs). */
 function scalarKindOf(field) {
@@ -77,7 +76,7 @@ function isAccountSelector(field) {
     const def = field?._zod?.def;
     if (!def)
         return false;
-    // A2 made account enums .optional(); unwrap it or fan-out silently dies.
+    // Account enums are .optional(); unwrap it or fan-out silently dies.
     if (def.type === 'optional')
         return def.innerType?._zod?.def?.type === 'enum';
     return def.type === 'enum';
@@ -107,8 +106,7 @@ export class ToolRegistry {
     revealed = new Set();
     jsonSchemaCache = new Map();
     argShapeCache = new Map();
-    /** Memoized isUngrantable verdict per tool: the answer depends on the frozen
-     * bundle catalog only, so it never changes within a process. */
+    // Memoized isUngrantable verdict: depends on the frozen bundle catalog only.
     ungrantable = new Map();
     compactOutput = trimEnabled();
     registeringMeta = false;
@@ -118,9 +116,8 @@ export class ToolRegistry {
      * lazy surface to curated without touching the configured mode. */
     expanded = false;
     constructor(server, policy, mode = resolveDiscoveryMode(), metrics = null, 
-    // The registry's OWN account view: fan-out expansion, selector validation
-    // and default-account injection all read through it so a registry built
-    // over a subset never observes (or leaks) the global set.
+    // The registry's OWN account view, so one built over a subset never
+    // observes (or leaks) the global set.
     accounts = getAccountSet) {
         this.server = server;
         this.metrics = metrics;
@@ -130,22 +127,17 @@ export class ToolRegistry {
         this.registerTool = ((name, config, handler) => {
             const service = serviceOf(name);
             const cud = config.cud ?? inferCud(name);
-            // destructiveHint=false claims "additive only" (MCP spec) — updates overwrite, so they stay true.
-            // idempotent: reads trivially, deletes (already-gone = same), updates
-            // (overwrite converges); creates are not (send twice = two emails).
+            // Every write is destructive (a create is no less consequential than an
+            // update); idempotent iff not a create (send twice = two emails).
+            const writes = cud !== 'read' || WRITES_DESPITE_READ.has(name);
             const annotations = {
-                readOnlyHint: cud === 'read',
-                destructiveHint: cud === 'delete' || cud === 'update',
+                readOnlyHint: !writes,
+                destructiveHint: writes,
                 idempotentHint: cud !== 'create',
                 ...config.annotations,
             };
-            // A12: forced per-call human approval on the irreversible set, even in
-            // bypass mode. Client-enforced via the wire _meta (Claude Code reads
-            // anthropic/* ONLY there); the server verdict stays separate.
-            // Every tool also advertises a result-size budget: fat readers declare
-            // their own, everything else inherits the default, so an uncapped tool
-            // can never blow past a client's context limit. Generated tools align
-            // with the executor's server-side cap.
+            // Irreversible-set approval and the result-size budget are both
+            // client-enforced via the wire _meta (anthropic/*); the server verdict stays separate.
             const clientMeta = {
                 'anthropic/maxResultSizeChars': config.cud !== undefined ? MAX_RESPONSE_CHARS : DEFAULT_MAX_RESULT_CHARS,
                 ...config._meta,
@@ -190,10 +182,8 @@ export class ToolRegistry {
                     : writeDisabledResult({ name, service, cud, scopes: config.requiredScopes }, policy, 
                     // Concrete by here: default-account injection wraps this.
                     args[0]?.account);
-            // A2: the ONE default-account injection site — outside the CUD gate and
-            // the fan-out parse so both observe a concrete alias; NOT meta-skipped
-            // (that is what covers google_api_call with zero bespoke code). Explicit
-            // aliases, "*" and CSV pass through untouched.
+            // The ONE default-account injection site, outside the CUD gate and the
+            // fan-out parse (not meta-skipped, which is what covers google_api_call).
             const withDefault = !hasAccountField
                 ? guarded
                 : (...args) => {
@@ -201,9 +191,8 @@ export class ToolRegistry {
                     const value = first?.account;
                     if (value != null && value !== '')
                         return guarded(...args);
-                    // Refresh here or the unset->configured default transition never
-                    // heals for a client that always omits account (this branch never
-                    // reaches getClient's probe). One stat, only on omission.
+                    // Refresh here, or a client that always omits account never heals
+                    // the unset->configured default transition (getClient's probe is unreached).
                     refreshAccountSetIfStale();
                     const def = this.accounts().defaultAccount;
                     if (!def) {
@@ -229,10 +218,8 @@ export class ToolRegistry {
             const finalHandler = this.compactOutput
                 ? async (...args) => compactResult(await withDefault(...args))
                 : withDefault;
-            // Usage metrics wrap OUTERMOST and only when enabled: off means no
-            // wrapper exists and the chain is byte-identical to the pre-metrics
-            // chain. Fan-out width is derived here (bucketed in the module) so the
-            // metrics module never imports fanout.
+            // Usage metrics wrap outermost, only when enabled (off = byte-identical
+            // to the pre-metrics chain); fan-out width is derived here so the metrics module never imports fanout.
             const instrumented = this.metrics
                 ? this.metrics.wrap({ name, service, meta: this.registeringMeta, generated: config.cud !== undefined }, finalHandler, (a) => {
                     const v = a?.account;
@@ -301,10 +288,8 @@ export class ToolRegistry {
         const declared = new Set(Object.keys(self.inputShape));
         const byKey = new Map();
         for (const t of this.tools) {
-            // Only tools the agent can actually see in tools/list. A hint naming a
-            // registered-but-unadvertised generated tool turns a recoverable error
-            // into a dead end: in curated mode 353 tools are registered and 181 are
-            // advertised, and the hint used to reach for any of them.
+            // Only tools visible in tools/list: a hint naming a hidden generated
+            // tool would turn a recoverable error into a dead end.
             if (t.service !== self.service || t.name === tool || !this.isVisible(t))
                 continue;
             for (const key of Object.keys(t.inputShape)) {
@@ -318,9 +303,8 @@ export class ToolRegistry {
             }
         }
         const candidates = [...byKey.entries()].filter(([, e]) => e.tools.length >= 2 || e.curated);
-        // Reuse the tiered matcher rather than a substring test: the motivating
-        // case (parentId against parentFolderId) fails containment and edit
-        // distance alike, which is the whole reason that matcher exists.
+        // The tiered matcher, not a substring test: parentId vs parentFolderId
+        // fails both containment and edit distance.
         const keys = candidates.map(([key]) => key);
         const hits = new Set(unknownKeys.slice(0, MAX_SUGGESTED_KEYS).flatMap((k) => suggestKeys(k, keys)));
         return candidates
@@ -386,7 +370,7 @@ export class ToolRegistry {
         return true;
     }
     /** discover_reset: back to the lean meta-only surface. Clears reveals too.
-     * BV-8: if a client mishandles a SHRINKING tools/list, this degrades to a
+     * If a client mishandles a SHRINKING tools/list, this degrades to a
      * no-op for that session — tools stay callable regardless (graceful
      * dispatch), zero correctness impact. */
     collapse() {
@@ -416,11 +400,8 @@ export class ToolRegistry {
         const cached = this.ungrantable.get(tool.name);
         if (cached !== undefined)
             return cached;
-        // EVERY alternative must be ungrantable. `classifyMethodScopes` cannot
-        // answer this: `add_bundle` and `unknown_scope` share the
-        // `not_requestable` rank, so its first-best match hides a grantable
-        // alternative that appears later in the list. Discovery scope lists are
-        // ANY-OF, so one grantable alternative makes the method reachable.
+        // EVERY alternative must be ungrantable (scope lists are ANY-OF); a
+        // first-best classifyScope match would hide a grantable one later in the list.
         const verdict = tool.requiredScopes.every((scope) => {
             const c = classifyScope(scope, EMPTY_SCOPES, EMPTY_SCOPES);
             return c.state === 'not_requestable' && c.reason === 'unknown_scope';
@@ -430,10 +411,8 @@ export class ToolRegistry {
     }
     isVisible(tool) {
         const mode = this.effectiveMode();
-        // Advertising a tool that can never succeed spends context budget to hand
-        // the agent a dead end. It stays registered and callable, so calling it by
-        // name still produces the real scope error plus its remediation, and
-        // {service}_discover still lists it, marked.
+        // Hidden, not unregistered: calling an ungrantable tool by name still
+        // produces the real scope error, and {service}_discover still lists it, marked.
         if (!tool.meta && this.isUngrantable(tool))
             return false;
         return (tool.meta ||
@@ -453,10 +432,7 @@ export class ToolRegistry {
             throw new Error('installListHandler() requires at least one registered tool');
         }
         this.server.server.setRequestHandler('tools/list', async () => ({
-            // The wire Tool is hand-built because the SDK's own types drop the
-            // anthropic/* _meta keys honoring clients read. z.toJSONSchema emits a
-            // valid draft-7 object schema by construction, which the SDK's recursive
-            // JSON-Schema type cannot infer from our cached `unknown`.
+            // Hand-built: the SDK's own Tool type drops the anthropic/* _meta keys honoring clients read.
             tools: this.tools.filter((t) => this.isVisible(t)).map((t) => this.toToolJson(t)),
         }));
     }
@@ -474,12 +450,8 @@ export class ToolRegistry {
             ...(tool.clientMeta ? { _meta: tool.clientMeta } : {}),
         };
     }
-    /** Advertise the CURRENT alias enum on every tools/list: account validation
-     * is (or is becoming) live, so a cached boot-time enum would go stale the
-     * moment account_add lands mid-session. The structural schema stays cached;
-     * only the account property's values are refreshed per call. Skipped for
-     * the subject-taking account tools (their `account` is the OPERAND, e.g. a
-     * brand-new alias name, not an identity to enumerate). */
+    // Refreshes the account enum's values per call (structural schema stays
+    // cached), so a cached boot-time list doesn't go stale once account_add runs mid-session.
     withLiveAccountEnum(tool, schema) {
         if (DEFAULT_ACCOUNT_EXCLUDE.has(tool.name))
             return schema;

package/dist/scope-catalog.d.ts

@@ -8,6 +8,7 @@ export interface BundleCatalogEntry {
     description: string;
     risk: 'low' | 'medium' | 'high';
     workspaceOnly?: boolean;
+    personalRefused?: boolean;
 }
 export declare const ADMIN_SCOPES: string[];
 export declare const BUNDLE_CATALOG: Record<string, BundleCatalogEntry>;
@@ -17,6 +18,10 @@ export declare const BUNDLE_ALIASES: Record<string, string>;
 /** Bundle names are user input: an Object.prototype member ("constructor",
  * "toString") passes a plain `in` or index lookup, so membership is own-key only. */
 export declare function isKnownBundle(name: string): boolean;
+/** A gmail.com or googlemail.com address, which is always a personal Google account. */
+export declare function isPersonalGoogleAddress(email: string): boolean;
+/** The bundles in `bundles` that Google refuses on the consent screen of the account at `email`. */
+export declare function refusedBundlesFor(email: string, bundles: readonly string[]): string[];
 export declare function resolveBundleAliases(bundles: string[]): string[];
 /** Closest catalog key for E_UNKNOWN_BUNDLE remediation (edit distance <= 2). */
 export declare function closestBundle(name: string): string | undefined;

package/dist/scope-catalog.js

@@ -1,7 +1,5 @@
-// The curated bundle catalog: ONE source of truth consumed by the wizard
-// picker, scope observability (#114) hints, and docs. Keys are a frozen
-// public API (config.json references them by name) — renames go through
-// BUNDLE_ALIASES, never in place.
+// The curated bundle catalog: ONE source of truth for the wizard, scope
+// observability, and docs. Keys are a frozen public API; rename via BUNDLE_ALIASES only.
 export const ADMIN_SCOPES = [
     'https://www.googleapis.com/auth/admin.reports.audit.readonly',
     'https://www.googleapis.com/auth/admin.directory.user',
@@ -63,6 +61,7 @@ export const BUNDLE_CATALOG = {
         ],
         description: 'Manage Cloud Identity groups and devices across the directory.',
         risk: 'high',
+        personalRefused: true,
     },
     cloudsearch: {
         scopes: ['https://www.googleapis.com/auth/cloud_search'],
@@ -79,6 +78,7 @@ export const BUNDLE_CATALOG = {
         scopes: ['https://www.googleapis.com/auth/keep'],
         description: 'Read and edit Google Keep notes.',
         risk: 'low',
+        personalRefused: true,
     },
     driveactivity: {
         scopes: ['https://www.googleapis.com/auth/drive.activity.readonly'],
@@ -113,9 +113,8 @@ export const BUNDLE_CATALOG = {
         description: 'Read Google Analytics (GA4): run reports and inspect accounts, properties and their configuration.',
         risk: 'low',
     },
-    // Includes readonly so it is self-sufficient: analytics.edit alone does not
-    // authorize Data API reads. The smaller `analytics` bundle stays the hint
-    // target for read scopes (scope-observability sorts bundles by size).
+    // Includes readonly so it's self-sufficient: analytics.edit alone doesn't
+    // authorize Data API reads.
     analytics_write: {
         scopes: [
             'https://www.googleapis.com/auth/analytics.readonly',
@@ -165,6 +164,17 @@ const warnedAliases = new Set();
 export function isKnownBundle(name) {
     return Object.hasOwn(BUNDLE_CATALOG, name);
 }
+const PERSONAL_ADDRESS_RE = /@(?:gmail|googlemail)\.com$/i;
+/** A gmail.com or googlemail.com address, which is always a personal Google account. */
+export function isPersonalGoogleAddress(email) {
+    return PERSONAL_ADDRESS_RE.test(email.trim());
+}
+/** The bundles in `bundles` that Google refuses on the consent screen of the account at `email`. */
+export function refusedBundlesFor(email, bundles) {
+    if (!isPersonalGoogleAddress(email))
+        return [];
+    return bundles.filter((b) => isKnownBundle(b) && BUNDLE_CATALOG[b].personalRefused === true);
+}
 export function resolveBundleAliases(bundles) {
     return bundles.map((name) => {
         const target = Object.hasOwn(BUNDLE_ALIASES, name) ? BUNDLE_ALIASES[name] : undefined;

package/dist/scope-observability.d.ts

@@ -65,7 +65,7 @@ export interface ScopesReport {
             bundle: string;
         }[];
         /** Runtime-signal bucket: static classification cannot prove account
-         * type; doctor (B9) fills it from observed persistent admin 403s. */
+         * type; doctor fills it from observed persistent admin 403s. */
         accountType: string[];
         unknown: string[];
     };
@@ -73,8 +73,7 @@ export interface ScopesReport {
 }
 /**
  * The account_list / doctor block. Universe = profile ∪ granted ∪ the scopes
- * required by REGISTERED tools ("registered but not requestable" is the
- * original #114 ask).
+ * required by REGISTERED tools ("registered but not requestable" included).
  */
 export declare function buildScopesReport(granted: ReadonlySet<string>, profile: ReadonlySet<string>, registeredScopes?: Iterable<string>): ScopesReport;
 export declare function clearScopeIndexForTest(): void;

package/dist/scope-observability.js

@@ -3,9 +3,8 @@ import { BASE_SCOPES, resolveScopesForAccount } from './auth.js';
 import { readToken } from './token-store.js';
 import { reauthHint } from './reauth-hint.js';
 import { hints } from './hint-provider.js';
-// Reverse index scope -> bundles offering it, narrowest bundle first (fewest
-// scopes) so the remediation names the smallest grant. BASE_SCOPES map to the
-// pseudo-bundle "base" (outside a profile only via includesBase:false).
+// Reverse index scope -> bundles offering it, narrowest first, so the
+// remediation names the smallest grant.
 let reverseIndex = null;
 function scopeIndex() {
     if (reverseIndex)
@@ -79,17 +78,14 @@ export function scopeHint(scope, c, alias) {
                 hint: rendered?.hint ??
                     (`Scope ${scope} is in ${alias}'s profile but not granted (you unchecked it at consent). ` +
                         reauthHint(alias)),
-                // The ONE kind whose retriable the host may flip (Decision 3): the
-                // owner keeps true, a multi-tenant host may report false because the
-                // fix needs the user in a browser.
+                // The ONE kind whose retriable the host may flip, since the fix needs the user in a browser.
                 retriable: rendered?.retriable ?? true,
             };
         }
         case 'not_requestable':
             if (c.reason === 'add_bundle') {
-                // "base" is a pseudo-bundle (BASE_SCOPES excluded by includesBase:
-                // false), NOT a catalog key — telling users to add it to bundles[]
-                // would fail boot with E_UNKNOWN_BUNDLE.
+                // "base" is a pseudo-bundle, not a catalog key: telling users to add
+                // it to bundles[] would fail boot with E_UNKNOWN_BUNDLE.
                 if (c.bundle === 'base') {
                     const rendered = hints()?.render({ kind: 'scope_base_excluded', account: alias, scope });
                     return {
@@ -153,9 +149,8 @@ export function scopeHintForMethod(required, alias, deps = {}) {
     if (!best || best.state === 'callable')
         return null; // 403 despite grants: not a scope-classification problem
     const base = scopeHint(best.scope, best.classification, alias);
-    // Hedged, never fabricated: an in-profile admin scope that 403s is EITHER a
-    // Workspace account needing re-auth OR a personal account that can never be
-    // granted admin — the inputs cannot distinguish, so say both.
+    // Hedged, never fabricated: the inputs can't distinguish a Workspace account
+    // needing re-auth from a personal account that can never grant admin, so say both.
     if (best.state === 'requestable_not_granted' && ADMIN_SCOPES.includes(best.scope)) {
         return {
             hint: `${base.hint} Note: personal (non-Workspace) accounts can never grant admin scopes — if ${alias} is a personal Gmail account, use a Workspace alias instead.`,
@@ -166,8 +161,7 @@ export function scopeHintForMethod(required, alias, deps = {}) {
 }
 /**
  * The account_list / doctor block. Universe = profile ∪ granted ∪ the scopes
- * required by REGISTERED tools ("registered but not requestable" is the
- * original #114 ask).
+ * required by REGISTERED tools ("registered but not requestable" included).
  */
 export function buildScopesReport(granted, profile, registeredScopes = []) {
     const callable = [];

package/dist/services.d.ts

@@ -14,6 +14,9 @@ export declare const GENERATED_GATES: Record<string, {
     enabled: (set?: AccountSet) => boolean;
     hint: string;
 }>;
+/** Message for a `tools/call` naming a tool that is not registered: the SDK's
+ * bare "Tool X not found" reads identically for a typo, a gated service, and
+ * an unknown API, but the server knows which is which from its boot-time enabled-service list. */
 export declare function unknownToolMessage(registry: ToolRegistry, rawName: string): string;
 /**
  * Gated services the registry's CURRENT accounts enable but that registered

package/dist/services.js

@@ -57,20 +57,15 @@ export const GENERATED_GATES = {
     script: bundleGate('script'),
     vault: bundleGate('vault'),
 };
-/**
- * Message for a `tools/call` naming a tool that is not registered. The SDK's
- * own answer is a bare "Tool X not found", which reads identically for a typo,
- * for a service gated behind a scope bundle, and for an API this server has
- * never heard of. Those need different next steps, and the server knows which
- * is which: it composed the enabled-service list at boot.
- */
 const MAX_TOOL_NAME_ECHO = 64;
+/** Message for a `tools/call` naming a tool that is not registered: the SDK's
+ * bare "Tool X not found" reads identically for a typo, a gated service, and
+ * an unknown API, but the server knows which is which from its boot-time enabled-service list. */
 export function unknownToolMessage(registry, rawName) {
     // The name is the caller's, unvalidated: echo a bounded prefix only.
     const name = rawName.length > MAX_TOOL_NAME_ECHO ? `${sliceClean(rawName, MAX_TOOL_NAME_ECHO)}...` : rawName;
-    // A service that EXISTS in the build but registered nothing is off, not
-    // misspelled. Checked before the did-you-mean, which would otherwise point
-    // chat_spaces_get at meet_spaces_get.
+    // A service that EXISTS but registered nothing is off, not misspelled;
+    // checked before the did-you-mean, which would otherwise point chat_spaces_get at meet_spaces_get.
     const service = serviceOf(name);
     const known = SERVICES.some((s) => s.name === service) || GENERATED_SERVICES.some((s) => s.name === service);
     if (known && !registry.services().includes(service)) {

package/dist/ssrf-guard.js

@@ -1,9 +1,5 @@
-// B13 / C11: SSRF guard for every server-side fetch (the CIMD client_id doc).
-// D4 decision (dependencies-and-bv §2.2): a small AUDITED private-range check,
-// no dependency — HTTPS-only, resolve-then-check ALL addresses (anti-rebind),
-// no redirects followed, and capped size and time. Blocks 10/8, 172.16/12,
-// 192.168/16, 127/8, 169.254/16, 0/8, multicast, ::1, fc00::/7, fe80::/10, and
-// v4-mapped forms.
+// SSRF guard for every server-side fetch (the CIMD client_id doc): HTTPS-only,
+// resolve-then-check ALL addresses (anti-rebind), no redirects, capped size/time.
 import { lookup } from 'node:dns/promises';
 import { isIPv4, isIPv6, BlockList } from 'node:net';
 export class SsrfBlockedError extends Error {
@@ -46,10 +42,8 @@ export function isBlockedIPv4(ip) {
         return true; // 224/4 multicast + 240/4 reserved
     return false;
 }
-// Built-in subnet math (no hand-rolled IPv6 parsing): blocks loopback,
-// unspecified, ULA, link-local, multicast, and ALL v4-mapped / v4-compatible /
-// NAT64 / 6to4 embeddings (a public host never resolves to those, so blocking
-// the whole range closes the embedded-private-target gap without parsing).
+// Built-in subnet math blocks v4-mapped/NAT64/6to4 embeddings too: a public
+// host never resolves to those, so the whole range closes the embedding gap.
 const V6_BLOCKED = new BlockList();
 V6_BLOCKED.addSubnet('::', 96, 'ipv6'); // ::/96 = ::1, ::, and v4-compatible
 V6_BLOCKED.addSubnet('::ffff:0:0', 96, 'ipv6'); // v4-mapped
@@ -145,10 +139,8 @@ export async function assertPublicHttpsUrl(rawUrl, deps = {}) {
     }
     return { url, addresses };
 }
-// Connection-level failures that a retry can legitimately recover from. A dead
-// IPv6 route (broken egress with Happy-Eyeballs falling through), a reset, or a
-// DNS blip are transient; an SSRF block, a bad HTTP status, or malformed JSON
-// are deterministic and must NOT be retried.
+// Connection-level failures a retry can recover from; an SSRF block, a bad
+// HTTP status, or malformed JSON are deterministic and must NOT be retried.
 const TRANSIENT_CODES = new Set([
     'ETIMEDOUT',
     'ECONNRESET',
@@ -170,8 +162,7 @@ export function isTransientFetchError(e) {
     const code = cause?.code ?? e?.code;
     if (code && TRANSIENT_CODES.has(code))
         return true;
-    // undici surfaces connection failures as TypeError('fetch failed') with the
-    // real reason in .cause; retry even when the cause carries no useful code.
+    // undici's TypeError('fetch failed') retries even with no useful .cause code.
     if (e instanceof TypeError && /fetch failed/i.test(e.message))
         return true;
     return false;
@@ -197,9 +188,8 @@ export async function fetchCimdDocument(rawUrl, opts = {}) {
     const backoffMs = opts.retryBackoffMs ?? 200;
     const doFetch = opts.fetchImpl ?? fetch;
     const sleep = opts.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    // Retry fast transient failures IN PLACE. Each attempt re-runs the
-    // resolve-then-check so a retry can never skip the anti-rebind guard, and
-    // the timer is per-attempt (armed across the lookup and the body read, #10).
+    // Each attempt re-runs resolve-then-check so a retry can't skip the
+    // anti-rebind guard; the timer is per-attempt, armed across lookup and body read.
     for (let attempt = 0;; attempt++) {
         const controller = new AbortController();
         let timedOut = false;
@@ -247,9 +237,8 @@ export async function fetchCimdDocument(rawUrl, opts = {}) {
         }
     }
 }
-/** Read a response body, aborting the moment it exceeds maxBytes (never buffers
- * an oversized body). Falls back to a capped arrayBuffer when there is no
- * readable stream (e.g. a test Response). */
+// Aborts the moment maxBytes is exceeded (never buffers an oversized body);
+// falls back to a capped arrayBuffer when there's no readable stream (e.g. a test Response).
 async function readCapped(res, maxBytes, controller) {
     const reader = res.body?.getReader?.();
     if (!reader) {

package/dist/tenant-purge.js

@@ -1,7 +1,5 @@
-// S1.21: tenant offboarding primitives. Core owns the reusable token-purge
-// legs (generically useful, tenant-id-agnostic); the tenant_delete
-// ORCHESTRATION (what to purge, in what order, from which admin surface)
-// lives with the tenancy module that calls these.
+// Tenant offboarding primitives: core owns the reusable token-purge legs;
+// orchestration (what to purge, in what order) lives with the tenancy module calling these.
 import fs from 'node:fs';
 import path from 'node:path';
 import { tenantConfigFilePath, tenantTokenDir } from './config-file.js';

package/dist/tools/_coerce.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-export declare function coerceArray<T extends z.ZodTypeAny>(element: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<T>>;
-export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
+export declare function coerceArray<T extends z.ZodTypeAny>(element: T): z.ZodPreprocess<z.ZodArray<T>, unknown>;
+export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodPreprocess<T, unknown>;
 /** Numeric args arrive string-encoded from some clients. Arg normalization
  * runs on BOTH transports, but it only coerces keys it RENAMED, so a value
  * sent under the correct key never passes through it and the coercion has to
  * live in the schema. */
-export declare function coerceNumber<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
-export declare const coerceBoolean: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>;
+export declare function coerceNumber<T extends z.ZodTypeAny>(schema: T): z.ZodPreprocess<T, unknown>;
+export declare const coerceBoolean: z.ZodPreprocess<z.ZodBoolean, unknown>;