@nhtio/adk 1.20260607.0 → 1.20260607.2

package/eslint/rules/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module @nhtio/adk/eslint/rules
+ *
+ * Barrel of the individual `@nhtio/adk` ESLint rule objects. Most consumers want the assembled
+ * plugin from `@nhtio/adk/eslint` instead; import individual rules from here only when composing a
+ * bespoke plugin or testing a single rule.
+ */
+export { default as requireValidatorAnyRequired } from "./require_validator_any_required";
+export { default as noModelInToolHandler } from "./no_model_in_tool_handler";
+export { default as thoughtPayloadRequiresReplayTag } from "./thought_payload_requires_replay_tag";
+export { default as tokenEncodingRequiresContextWindow } from "./token_encoding_requires_context_window";
+export { default as artifactToolForbidsArtifactConstructor } from "./artifact_tool_forbids_artifact_constructor";

package/eslint/rules/no_model_in_tool_handler.cjs

@@ -0,0 +1,64 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Ble4zEEl.js");
+const require_common = require("../../common-DeNipTQI.js");
+//#region src/eslint/rules/no_model_in_tool_handler.ts
+/**
+* @module @nhtio/adk/eslint/rules/no_model_in_tool_handler
+*
+* Flags an LLM/model call inside a `Tool` / `ArtifactTool` `handler`.
+*
+* Why: the executor owns the dispatch loop. A tool handler runs as one step the model proposed; it
+* must do work and return a result, not start its own reasoning loop. Calling a model from inside a
+* handler hides a nested, unmanaged dispatch from the harness — no token accounting, no event
+* surfacing, no abort propagation. The one legitimate exception is a tool that is explicitly a
+* sub-agent running its own scoped dispatch; this rule allows a handler that constructs a
+* `new TurnRunner(...)` or calls the lower-level `DispatchRunner.dispatch(...)`.
+*
+* Detects provider SDK constructors (`new OpenAI()`, `new Anthropic()`) and chat/completion calls
+* (a `.create()` whose receiver chain passes through `messages`/`completions`/`responses`, or a
+* `generateContent()` call) within the `handler` function passed to `new Tool({ handler })` /
+* `new ArtifactTool({ handler })`, ignoring inner closures (so a sub-agent's own callbacks don't
+* false-positive).
+*
+* Opt-out:
+*   // eslint-disable-next-line adk/no-model-in-tool-handler -- <reason>
+*/
+var literalKey = (prop) => {
+	if (prop.computed) return void 0;
+	if (prop.key.type === "Identifier") return prop.key.name;
+	if (prop.key.type === "Literal" && typeof prop.key.value === "string") return prop.key.value;
+};
+var noModelInToolHandlerRule = require_common.createRule({
+	name: "no-model-in-tool-handler",
+	meta: {
+		type: "problem",
+		docs: { description: "A Tool/ArtifactTool handler must not invoke a model — the executor owns the dispatch loop. The only exception is a sub-agent tool that runs its own scoped dispatch via `new TurnRunner(...)` or `DispatchRunner.dispatch(...)`." },
+		schema: [],
+		messages: { noModelInHandler: "Do not call a model inside a tool handler — the executor owns the dispatch loop, and a model call here hides an unmanaged nested dispatch (no token accounting, events, or abort). If this tool is a sub-agent, run a scoped `new TurnRunner(...)` or `DispatchRunner.dispatch(...)` instead. Opt out with an eslint-disable-next-line adk/no-model-in-tool-handler comment + reason." }
+	},
+	defaultOptions: [],
+	create(context) {
+		return { NewExpression(node) {
+			if (node.callee.type !== "Identifier" || node.callee.name !== "Tool" && node.callee.name !== "ArtifactTool") return;
+			const arg = node.arguments[0];
+			if (!arg || arg.type !== "ObjectExpression") return;
+			const handlerProp = arg.properties.find((p) => p.type === "Property" && literalKey(p) === "handler");
+			if (!handlerProp || !require_common.isFunctionNode(handlerProp.value)) return;
+			const handler = handlerProp.value;
+			if (require_common.runsSubAgent(handler.body)) return;
+			require_common.walkBodySkippingNestedFunctions(handler.body, (n) => {
+				if (require_common.isLlmCall(n)) context.report({
+					node: n,
+					messageId: "noModelInHandler"
+				});
+			});
+		} };
+	}
+});
+//#endregion
+exports.default = noModelInToolHandlerRule;
+
+//# sourceMappingURL=no_model_in_tool_handler.cjs.map

package/eslint/rules/no_model_in_tool_handler.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"no_model_in_tool_handler.cjs","names":[],"sources":["../../../src/eslint/rules/no_model_in_tool_handler.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/eslint/rules/no_model_in_tool_handler\n *\n * Flags an LLM/model call inside a `Tool` / `ArtifactTool` `handler`.\n *\n * Why: the executor owns the dispatch loop. A tool handler runs as one step the model proposed; it\n * must do work and return a result, not start its own reasoning loop. Calling a model from inside a\n * handler hides a nested, unmanaged dispatch from the harness — no token accounting, no event\n * surfacing, no abort propagation. The one legitimate exception is a tool that is explicitly a\n * sub-agent running its own scoped dispatch; this rule allows a handler that constructs a\n * `new TurnRunner(...)` or calls the lower-level `DispatchRunner.dispatch(...)`.\n *\n * Detects provider SDK constructors (`new OpenAI()`, `new Anthropic()`) and chat/completion calls\n * (a `.create()` whose receiver chain passes through `messages`/`completions`/`responses`, or a\n * `generateContent()` call) within the `handler` function passed to `new Tool({ handler })` /\n * `new ArtifactTool({ handler })`, ignoring inner closures (so a sub-agent's own callbacks don't\n * false-positive).\n *\n * Opt-out:\n *   // eslint-disable-next-line adk/no-model-in-tool-handler -- <reason>\n */\n\nimport {\n  createRule,\n  isFunctionNode,\n  isLlmCall,\n  runsSubAgent,\n  walkBodySkippingNestedFunctions,\n} from './common'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\nconst literalKey = (prop: TSESTree.Property): string | undefined => {\n  if (prop.computed) return undefined\n  if (prop.key.type === 'Identifier') return prop.key.name\n  if (prop.key.type === 'Literal' && typeof prop.key.value === 'string') return prop.key.value\n  return undefined\n}\n\nconst noModelInToolHandlerRule = createRule({\n  name: 'no-model-in-tool-handler',\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'A Tool/ArtifactTool handler must not invoke a model — the executor owns the dispatch loop. The only exception is a sub-agent tool that runs its own scoped dispatch via `new TurnRunner(...)` or `DispatchRunner.dispatch(...)`.',\n    },\n    schema: [],\n    messages: {\n      noModelInHandler:\n        'Do not call a model inside a tool handler — the executor owns the dispatch loop, and a model call here hides an unmanaged nested dispatch (no token accounting, events, or abort). If this tool is a sub-agent, run a scoped `new TurnRunner(...)` or `DispatchRunner.dispatch(...)` instead. Opt out with an eslint-disable-next-line adk/no-model-in-tool-handler comment + reason.',\n    },\n  },\n  defaultOptions: [],\n  create(context) {\n    return {\n      NewExpression(node: TSESTree.NewExpression) {\n        if (\n          node.callee.type !== 'Identifier' ||\n          (node.callee.name !== 'Tool' && node.callee.name !== 'ArtifactTool')\n        ) {\n          return\n        }\n        const arg = node.arguments[0]\n        if (!arg || arg.type !== 'ObjectExpression') return\n\n        const handlerProp = arg.properties.find(\n          (p): p is TSESTree.Property => p.type === 'Property' && literalKey(p) === 'handler'\n        )\n        if (!handlerProp || !isFunctionNode(handlerProp.value)) return\n        const handler = handlerProp.value\n\n        // A sub-agent tool legitimately runs a scoped dispatch (new TurnRunner / DispatchRunner.dispatch)\n        // — that's the documented exception.\n        if (runsSubAgent(handler.body)) return\n\n        walkBodySkippingNestedFunctions(handler.body, (n) => {\n          if (isLlmCall(n)) {\n            context.report({ node: n, messageId: 'noModelInHandler' })\n          }\n        })\n      },\n    }\n  },\n})\n\nexport default noModelInToolHandlerRule\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAM,cAAc,SAAgD;CAClE,IAAI,KAAK,UAAU,OAAO,KAAA;CAC1B,IAAI,KAAK,IAAI,SAAS,cAAc,OAAO,KAAK,IAAI;CACpD,IAAI,KAAK,IAAI,SAAS,aAAa,OAAO,KAAK,IAAI,UAAU,UAAU,OAAO,KAAK,IAAI;AAEzF;AAEA,IAAM,2BAA2B,eAAA,WAAW;CAC1C,MAAM;CACN,MAAM;EACJ,MAAM;EACN,MAAM,EACJ,aACE,mOACJ;EACA,QAAQ,CAAC;EACT,UAAU,EACR,kBACE,wXACJ;CACF;CACA,gBAAgB,CAAC;CACjB,OAAO,SAAS;EACd,OAAO,EACL,cAAc,MAA8B;GAC1C,IACE,KAAK,OAAO,SAAS,gBACpB,KAAK,OAAO,SAAS,UAAU,KAAK,OAAO,SAAS,gBAErD;GAEF,MAAM,MAAM,KAAK,UAAU;GAC3B,IAAI,CAAC,OAAO,IAAI,SAAS,oBAAoB;GAE7C,MAAM,cAAc,IAAI,WAAW,MAChC,MAA8B,EAAE,SAAS,cAAc,WAAW,CAAC,MAAM,SAC5E;GACA,IAAI,CAAC,eAAe,CAAC,eAAA,eAAe,YAAY,KAAK,GAAG;GACxD,MAAM,UAAU,YAAY;GAI5B,IAAI,eAAA,aAAa,QAAQ,IAAI,GAAG;GAEhC,eAAA,gCAAgC,QAAQ,OAAO,MAAM;IACnD,IAAI,eAAA,UAAU,CAAC,GACb,QAAQ,OAAO;KAAE,MAAM;KAAG,WAAW;IAAmB,CAAC;GAE7D,CAAC;EACH,EACF;CACF;AACF,CAAC"}

package/eslint/rules/no_model_in_tool_handler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module @nhtio/adk/eslint/rules/no_model_in_tool_handler
+ *
+ * Flags an LLM/model call inside a `Tool` / `ArtifactTool` `handler`.
+ *
+ * Why: the executor owns the dispatch loop. A tool handler runs as one step the model proposed; it
+ * must do work and return a result, not start its own reasoning loop. Calling a model from inside a
+ * handler hides a nested, unmanaged dispatch from the harness — no token accounting, no event
+ * surfacing, no abort propagation. The one legitimate exception is a tool that is explicitly a
+ * sub-agent running its own scoped dispatch; this rule allows a handler that constructs a
+ * `new TurnRunner(...)` or calls the lower-level `DispatchRunner.dispatch(...)`.
+ *
+ * Detects provider SDK constructors (`new OpenAI()`, `new Anthropic()`) and chat/completion calls
+ * (a `.create()` whose receiver chain passes through `messages`/`completions`/`responses`, or a
+ * `generateContent()` call) within the `handler` function passed to `new Tool({ handler })` /
+ * `new ArtifactTool({ handler })`, ignoring inner closures (so a sub-agent's own callbacks don't
+ * false-positive).
+ *
+ * Opt-out:
+ *   // eslint-disable-next-line adk/no-model-in-tool-handler -- <reason>
+ */
+declare const noModelInToolHandlerRule: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noModelInHandler", [
+], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default noModelInToolHandlerRule;

package/eslint/rules/no_model_in_tool_handler.mjs

@@ -0,0 +1,59 @@
+import { a as walkBodySkippingNestedFunctions, i as runsSubAgent, n as isFunctionNode, r as isLlmCall, t as createRule } from "../../common-BUIjZ6LV.mjs";
+//#region src/eslint/rules/no_model_in_tool_handler.ts
+/**
+* @module @nhtio/adk/eslint/rules/no_model_in_tool_handler
+*
+* Flags an LLM/model call inside a `Tool` / `ArtifactTool` `handler`.
+*
+* Why: the executor owns the dispatch loop. A tool handler runs as one step the model proposed; it
+* must do work and return a result, not start its own reasoning loop. Calling a model from inside a
+* handler hides a nested, unmanaged dispatch from the harness — no token accounting, no event
+* surfacing, no abort propagation. The one legitimate exception is a tool that is explicitly a
+* sub-agent running its own scoped dispatch; this rule allows a handler that constructs a
+* `new TurnRunner(...)` or calls the lower-level `DispatchRunner.dispatch(...)`.
+*
+* Detects provider SDK constructors (`new OpenAI()`, `new Anthropic()`) and chat/completion calls
+* (a `.create()` whose receiver chain passes through `messages`/`completions`/`responses`, or a
+* `generateContent()` call) within the `handler` function passed to `new Tool({ handler })` /
+* `new ArtifactTool({ handler })`, ignoring inner closures (so a sub-agent's own callbacks don't
+* false-positive).
+*
+* Opt-out:
+*   // eslint-disable-next-line adk/no-model-in-tool-handler -- <reason>
+*/
+var literalKey = (prop) => {
+	if (prop.computed) return void 0;
+	if (prop.key.type === "Identifier") return prop.key.name;
+	if (prop.key.type === "Literal" && typeof prop.key.value === "string") return prop.key.value;
+};
+var noModelInToolHandlerRule = createRule({
+	name: "no-model-in-tool-handler",
+	meta: {
+		type: "problem",
+		docs: { description: "A Tool/ArtifactTool handler must not invoke a model — the executor owns the dispatch loop. The only exception is a sub-agent tool that runs its own scoped dispatch via `new TurnRunner(...)` or `DispatchRunner.dispatch(...)`." },
+		schema: [],
+		messages: { noModelInHandler: "Do not call a model inside a tool handler — the executor owns the dispatch loop, and a model call here hides an unmanaged nested dispatch (no token accounting, events, or abort). If this tool is a sub-agent, run a scoped `new TurnRunner(...)` or `DispatchRunner.dispatch(...)` instead. Opt out with an eslint-disable-next-line adk/no-model-in-tool-handler comment + reason." }
+	},
+	defaultOptions: [],
+	create(context) {
+		return { NewExpression(node) {
+			if (node.callee.type !== "Identifier" || node.callee.name !== "Tool" && node.callee.name !== "ArtifactTool") return;
+			const arg = node.arguments[0];
+			if (!arg || arg.type !== "ObjectExpression") return;
+			const handlerProp = arg.properties.find((p) => p.type === "Property" && literalKey(p) === "handler");
+			if (!handlerProp || !isFunctionNode(handlerProp.value)) return;
+			const handler = handlerProp.value;
+			if (runsSubAgent(handler.body)) return;
+			walkBodySkippingNestedFunctions(handler.body, (n) => {
+				if (isLlmCall(n)) context.report({
+					node: n,
+					messageId: "noModelInHandler"
+				});
+			});
+		} };
+	}
+});
+//#endregion
+export { noModelInToolHandlerRule as default };
+
+//# sourceMappingURL=no_model_in_tool_handler.mjs.map

package/eslint/rules/no_model_in_tool_handler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"no_model_in_tool_handler.mjs","names":[],"sources":["../../../src/eslint/rules/no_model_in_tool_handler.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/eslint/rules/no_model_in_tool_handler\n *\n * Flags an LLM/model call inside a `Tool` / `ArtifactTool` `handler`.\n *\n * Why: the executor owns the dispatch loop. A tool handler runs as one step the model proposed; it\n * must do work and return a result, not start its own reasoning loop. Calling a model from inside a\n * handler hides a nested, unmanaged dispatch from the harness — no token accounting, no event\n * surfacing, no abort propagation. The one legitimate exception is a tool that is explicitly a\n * sub-agent running its own scoped dispatch; this rule allows a handler that constructs a\n * `new TurnRunner(...)` or calls the lower-level `DispatchRunner.dispatch(...)`.\n *\n * Detects provider SDK constructors (`new OpenAI()`, `new Anthropic()`) and chat/completion calls\n * (a `.create()` whose receiver chain passes through `messages`/`completions`/`responses`, or a\n * `generateContent()` call) within the `handler` function passed to `new Tool({ handler })` /\n * `new ArtifactTool({ handler })`, ignoring inner closures (so a sub-agent's own callbacks don't\n * false-positive).\n *\n * Opt-out:\n *   // eslint-disable-next-line adk/no-model-in-tool-handler -- <reason>\n */\n\nimport {\n  createRule,\n  isFunctionNode,\n  isLlmCall,\n  runsSubAgent,\n  walkBodySkippingNestedFunctions,\n} from './common'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\nconst literalKey = (prop: TSESTree.Property): string | undefined => {\n  if (prop.computed) return undefined\n  if (prop.key.type === 'Identifier') return prop.key.name\n  if (prop.key.type === 'Literal' && typeof prop.key.value === 'string') return prop.key.value\n  return undefined\n}\n\nconst noModelInToolHandlerRule = createRule({\n  name: 'no-model-in-tool-handler',\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'A Tool/ArtifactTool handler must not invoke a model — the executor owns the dispatch loop. The only exception is a sub-agent tool that runs its own scoped dispatch via `new TurnRunner(...)` or `DispatchRunner.dispatch(...)`.',\n    },\n    schema: [],\n    messages: {\n      noModelInHandler:\n        'Do not call a model inside a tool handler — the executor owns the dispatch loop, and a model call here hides an unmanaged nested dispatch (no token accounting, events, or abort). If this tool is a sub-agent, run a scoped `new TurnRunner(...)` or `DispatchRunner.dispatch(...)` instead. Opt out with an eslint-disable-next-line adk/no-model-in-tool-handler comment + reason.',\n    },\n  },\n  defaultOptions: [],\n  create(context) {\n    return {\n      NewExpression(node: TSESTree.NewExpression) {\n        if (\n          node.callee.type !== 'Identifier' ||\n          (node.callee.name !== 'Tool' && node.callee.name !== 'ArtifactTool')\n        ) {\n          return\n        }\n        const arg = node.arguments[0]\n        if (!arg || arg.type !== 'ObjectExpression') return\n\n        const handlerProp = arg.properties.find(\n          (p): p is TSESTree.Property => p.type === 'Property' && literalKey(p) === 'handler'\n        )\n        if (!handlerProp || !isFunctionNode(handlerProp.value)) return\n        const handler = handlerProp.value\n\n        // A sub-agent tool legitimately runs a scoped dispatch (new TurnRunner / DispatchRunner.dispatch)\n        // — that's the documented exception.\n        if (runsSubAgent(handler.body)) return\n\n        walkBodySkippingNestedFunctions(handler.body, (n) => {\n          if (isLlmCall(n)) {\n            context.report({ node: n, messageId: 'noModelInHandler' })\n          }\n        })\n      },\n    }\n  },\n})\n\nexport default noModelInToolHandlerRule\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAM,cAAc,SAAgD;CAClE,IAAI,KAAK,UAAU,OAAO,KAAA;CAC1B,IAAI,KAAK,IAAI,SAAS,cAAc,OAAO,KAAK,IAAI;CACpD,IAAI,KAAK,IAAI,SAAS,aAAa,OAAO,KAAK,IAAI,UAAU,UAAU,OAAO,KAAK,IAAI;AAEzF;AAEA,IAAM,2BAA2B,WAAW;CAC1C,MAAM;CACN,MAAM;EACJ,MAAM;EACN,MAAM,EACJ,aACE,mOACJ;EACA,QAAQ,CAAC;EACT,UAAU,EACR,kBACE,wXACJ;CACF;CACA,gBAAgB,CAAC;CACjB,OAAO,SAAS;EACd,OAAO,EACL,cAAc,MAA8B;GAC1C,IACE,KAAK,OAAO,SAAS,gBACpB,KAAK,OAAO,SAAS,UAAU,KAAK,OAAO,SAAS,gBAErD;GAEF,MAAM,MAAM,KAAK,UAAU;GAC3B,IAAI,CAAC,OAAO,IAAI,SAAS,oBAAoB;GAE7C,MAAM,cAAc,IAAI,WAAW,MAChC,MAA8B,EAAE,SAAS,cAAc,WAAW,CAAC,MAAM,SAC5E;GACA,IAAI,CAAC,eAAe,CAAC,eAAe,YAAY,KAAK,GAAG;GACxD,MAAM,UAAU,YAAY;GAI5B,IAAI,aAAa,QAAQ,IAAI,GAAG;GAEhC,gCAAgC,QAAQ,OAAO,MAAM;IACnD,IAAI,UAAU,CAAC,GACb,QAAQ,OAAO;KAAE,MAAM;KAAG,WAAW;IAAmB,CAAC;GAE7D,CAAC;EACH,EACF;CACF;AACF,CAAC"}

package/eslint/rules/require_validator_any_required.cjs

@@ -0,0 +1,100 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Ble4zEEl.js");
+const require_common = require("../../common-DeNipTQI.js");
+//#region src/eslint/rules/require_validator_any_required.ts
+/**
+* @module @nhtio/adk/eslint/rules/require_validator_any_required
+*
+* Flags every `validator.any()` schema chain that does not declare intent with `.required()`
+* or `.optional()`.
+*
+* Why: in `@nhtio/validation`, `.any()` ADMITS `null`/`undefined` unless you make it `.required()`.
+* That default is silent and easy to miss — a schema you believe rejects missing values quietly
+* accepts them, and any `.custom()` refinement is skipped for an absent value (a `.custom()` guard
+* is the usual way this surfaces, e.g. `implementsX(undefined) === true`). The fix is to make the
+* disposition an EXPLICIT declaration with no ambiguity — every `.any()` must say which it is:
+*   - `.required()`  → reject null/undefined
+*   - `.optional()`  → deliberately allow null/undefined
+*   - `.default(x)`  → allow absence, substituting a fallback value
+*   - `.forbidden()` → the value must be absent
+* This applies whether the `.any()` is top-level or nested inside `items(...)` / `alternatives(...)`:
+* the enclosing schema being `.required()` does NOT govern an inner `.any()`'s null/undefined handling.
+*
+* The sharpest illustration is `.valid(null)`: an author writing `validator.any().valid(null)`
+* means "must be exactly null" — but because `.any()` admits `undefined`, that schema actually
+* accepts BOTH `null` and `undefined` (and `undefined !== null`). The fix is
+* `validator.any().required().valid(null)`.
+*
+* Opt-out (e.g. a bare `.any()` used purely as a type argument like `items(validator.any())`):
+*   // eslint-disable-next-line adk/require-validator-any-required -- <reason>
+*/
+var baseIdentifierName = (node) => {
+	let cur = node;
+	while (cur) {
+		if (cur.type === "Identifier") return cur.name;
+		if (cur.type === "MemberExpression") {
+			cur = cur.object;
+			continue;
+		}
+		if (cur.type === "CallExpression") {
+			cur = cur.callee;
+			continue;
+		}
+		return;
+	}
+};
+var isAnyCall = (node) => node.callee.type === "MemberExpression" && node.callee.property.type === "Identifier" && node.callee.property.name === "any" && baseIdentifierName(node.callee.object) === "validator";
+var collectChainCalls = (anyCall) => {
+	const calls = [];
+	let cur = anyCall;
+	while (cur && cur.type === "CallExpression") {
+		calls.push(cur);
+		cur = cur.callee.type === "MemberExpression" ? cur.callee.object : null;
+	}
+	cur = anyCall;
+	while (cur) {
+		const p = cur.parent;
+		if (!p) break;
+		if (p.type === "MemberExpression" && p.object === cur) {
+			cur = p;
+			continue;
+		}
+		if (p.type === "CallExpression" && p.callee === cur) {
+			calls.push(p);
+			cur = p;
+			continue;
+		}
+		break;
+	}
+	return calls;
+};
+var chainCalls = (calls, name) => calls.some((c) => c.callee.type === "MemberExpression" && c.callee.property.type === "Identifier" && c.callee.property.name === name);
+var requireValidatorAnyRequiredRule = require_common.createRule({
+	name: "require-validator-any-required",
+	meta: {
+		type: "problem",
+		docs: { description: "`validator.any()` admits null/undefined unless `.required()`; make the disposition explicit by ending every `.any()` in `.required()`, `.optional()`, or `.default(…)`. Opt out with a tactical disable comment + reason." },
+		schema: [],
+		messages: { declareIntent: "`validator.any()` admits null/undefined unless made `.required()`. Make the disposition explicit: end this `.any()` in `.required()` (reject null/undefined), `.optional()` (deliberately allow it), or `.default(…)` (allow it with a fallback) — applies even when nested in items()/alternatives(). Or add an eslint-disable-next-line adk/require-validator-any-required comment with a reason." }
+	},
+	defaultOptions: [],
+	create(context) {
+		return { CallExpression(node) {
+			if (!isAnyCall(node)) return;
+			const calls = collectChainCalls(node);
+			if (chainCalls(calls, "required") || chainCalls(calls, "optional") || chainCalls(calls, "default") || chainCalls(calls, "forbidden")) return;
+			const reportNode = node.callee.type === "MemberExpression" ? node.callee.property : node;
+			context.report({
+				node: reportNode,
+				messageId: "declareIntent"
+			});
+		} };
+	}
+});
+//#endregion
+exports.default = requireValidatorAnyRequiredRule;
+
+//# sourceMappingURL=require_validator_any_required.cjs.map

package/eslint/rules/require_validator_any_required.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"require_validator_any_required.cjs","names":[],"sources":["../../../src/eslint/rules/require_validator_any_required.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/eslint/rules/require_validator_any_required\n *\n * Flags every `validator.any()` schema chain that does not declare intent with `.required()`\n * or `.optional()`.\n *\n * Why: in `@nhtio/validation`, `.any()` ADMITS `null`/`undefined` unless you make it `.required()`.\n * That default is silent and easy to miss — a schema you believe rejects missing values quietly\n * accepts them, and any `.custom()` refinement is skipped for an absent value (a `.custom()` guard\n * is the usual way this surfaces, e.g. `implementsX(undefined) === true`). The fix is to make the\n * disposition an EXPLICIT declaration with no ambiguity — every `.any()` must say which it is:\n *   - `.required()`  → reject null/undefined\n *   - `.optional()`  → deliberately allow null/undefined\n *   - `.default(x)`  → allow absence, substituting a fallback value\n *   - `.forbidden()` → the value must be absent\n * This applies whether the `.any()` is top-level or nested inside `items(...)` / `alternatives(...)`:\n * the enclosing schema being `.required()` does NOT govern an inner `.any()`'s null/undefined handling.\n *\n * The sharpest illustration is `.valid(null)`: an author writing `validator.any().valid(null)`\n * means \"must be exactly null\" — but because `.any()` admits `undefined`, that schema actually\n * accepts BOTH `null` and `undefined` (and `undefined !== null`). The fix is\n * `validator.any().required().valid(null)`.\n *\n * Opt-out (e.g. a bare `.any()` used purely as a type argument like `items(validator.any())`):\n *   // eslint-disable-next-line adk/require-validator-any-required -- <reason>\n */\n\nimport { createRule } from './common'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\n// The base identifier a member/call chain roots at, e.g. `validator` in `validator.any()` or\n// `validator.alternatives(...).any()`. Returns undefined if the chain doesn't root at a plain name.\nconst baseIdentifierName = (node: TSESTree.Node | undefined): string | undefined => {\n  let cur: TSESTree.Node | undefined = node\n  while (cur) {\n    if (cur.type === 'Identifier') return cur.name\n    if (cur.type === 'MemberExpression') {\n      cur = cur.object\n      continue\n    }\n    if (cur.type === 'CallExpression') {\n      cur = cur.callee\n      continue\n    }\n    return undefined\n  }\n  return undefined\n}\n\n// `validator.any()` (or a `validator.…().any()` chain) — NOT `expect.any()`, `_.any()`, etc.\nconst isAnyCall = (node: TSESTree.CallExpression): boolean =>\n  node.callee.type === 'MemberExpression' &&\n  node.callee.property.type === 'Identifier' &&\n  node.callee.property.name === 'any' &&\n  baseIdentifierName(node.callee.object) === 'validator'\n\n// Collect every CallExpression in the method chain `anyCall` belongs to — inward through the\n// callee object (`a.b().c()` -> `a.b()`) and outward through `.parent` links\n// (`x.any()` -> `x.any().required` -> `x.any().required()`).\nconst collectChainCalls = (anyCall: TSESTree.CallExpression): TSESTree.CallExpression[] => {\n  const calls: TSESTree.CallExpression[] = []\n\n  let cur: TSESTree.Node | null = anyCall\n  while (cur && cur.type === 'CallExpression') {\n    calls.push(cur)\n    cur = cur.callee.type === 'MemberExpression' ? cur.callee.object : null\n  }\n\n  cur = anyCall\n  while (cur) {\n    const p: TSESTree.Node | undefined = cur.parent\n    if (!p) break\n    if (p.type === 'MemberExpression' && p.object === cur) {\n      cur = p\n      continue\n    }\n    if (p.type === 'CallExpression' && p.callee === cur) {\n      calls.push(p)\n      cur = p\n      continue\n    }\n    break\n  }\n\n  return calls\n}\n\nconst chainCalls = (calls: TSESTree.CallExpression[], name: string): boolean =>\n  calls.some(\n    (c) =>\n      c.callee.type === 'MemberExpression' &&\n      c.callee.property.type === 'Identifier' &&\n      c.callee.property.name === name\n  )\n\nconst requireValidatorAnyRequiredRule = createRule({\n  name: 'require-validator-any-required',\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        '`validator.any()` admits null/undefined unless `.required()`; make the disposition explicit by ending every `.any()` in `.required()`, `.optional()`, or `.default(…)`. Opt out with a tactical disable comment + reason.',\n    },\n    schema: [],\n    messages: {\n      declareIntent:\n        '`validator.any()` admits null/undefined unless made `.required()`. Make the disposition explicit: end this `.any()` in `.required()` (reject null/undefined), `.optional()` (deliberately allow it), or `.default(…)` (allow it with a fallback) — applies even when nested in items()/alternatives(). Or add an eslint-disable-next-line adk/require-validator-any-required comment with a reason.',\n    },\n  },\n  defaultOptions: [],\n  create(context) {\n    return {\n      CallExpression(node: TSESTree.CallExpression) {\n        if (!isAnyCall(node)) return\n        const calls = collectChainCalls(node)\n        // An unambiguous disposition declaration clears the rule:\n        //   .required()  — reject null/undefined\n        //   .optional()  — deliberately allow null/undefined\n        //   .default(x)  — allow absence, substituting a fallback\n        //   .forbidden() — the value must be absent\n        if (\n          chainCalls(calls, 'required') ||\n          chainCalls(calls, 'optional') ||\n          chainCalls(calls, 'default') ||\n          chainCalls(calls, 'forbidden')\n        ) {\n          return\n        }\n        const reportNode = node.callee.type === 'MemberExpression' ? node.callee.property : node\n        context.report({ node: reportNode, messageId: 'declareIntent' })\n      },\n    }\n  },\n})\n\nexport default requireValidatorAnyRequiredRule\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,IAAM,sBAAsB,SAAwD;CAClF,IAAI,MAAiC;CACrC,OAAO,KAAK;EACV,IAAI,IAAI,SAAS,cAAc,OAAO,IAAI;EAC1C,IAAI,IAAI,SAAS,oBAAoB;GACnC,MAAM,IAAI;GACV;EACF;EACA,IAAI,IAAI,SAAS,kBAAkB;GACjC,MAAM,IAAI;GACV;EACF;EACA;CACF;AAEF;AAGA,IAAM,aAAa,SACjB,KAAK,OAAO,SAAS,sBACrB,KAAK,OAAO,SAAS,SAAS,gBAC9B,KAAK,OAAO,SAAS,SAAS,SAC9B,mBAAmB,KAAK,OAAO,MAAM,MAAM;AAK7C,IAAM,qBAAqB,YAAgE;CACzF,MAAM,QAAmC,CAAC;CAE1C,IAAI,MAA4B;CAChC,OAAO,OAAO,IAAI,SAAS,kBAAkB;EAC3C,MAAM,KAAK,GAAG;EACd,MAAM,IAAI,OAAO,SAAS,qBAAqB,IAAI,OAAO,SAAS;CACrE;CAEA,MAAM;CACN,OAAO,KAAK;EACV,MAAM,IAA+B,IAAI;EACzC,IAAI,CAAC,GAAG;EACR,IAAI,EAAE,SAAS,sBAAsB,EAAE,WAAW,KAAK;GACrD,MAAM;GACN;EACF;EACA,IAAI,EAAE,SAAS,oBAAoB,EAAE,WAAW,KAAK;GACnD,MAAM,KAAK,CAAC;GACZ,MAAM;GACN;EACF;EACA;CACF;CAEA,OAAO;AACT;AAEA,IAAM,cAAc,OAAkC,SACpD,MAAM,MACH,MACC,EAAE,OAAO,SAAS,sBAClB,EAAE,OAAO,SAAS,SAAS,gBAC3B,EAAE,OAAO,SAAS,SAAS,IAC/B;AAEF,IAAM,kCAAkC,eAAA,WAAW;CACjD,MAAM;CACN,MAAM;EACJ,MAAM;EACN,MAAM,EACJ,aACE,4NACJ;EACA,QAAQ,CAAC;EACT,UAAU,EACR,eACE,sYACJ;CACF;CACA,gBAAgB,CAAC;CACjB,OAAO,SAAS;EACd,OAAO,EACL,eAAe,MAA+B;GAC5C,IAAI,CAAC,UAAU,IAAI,GAAG;GACtB,MAAM,QAAQ,kBAAkB,IAAI;GAMpC,IACE,WAAW,OAAO,UAAU,KAC5B,WAAW,OAAO,UAAU,KAC5B,WAAW,OAAO,SAAS,KAC3B,WAAW,OAAO,WAAW,GAE7B;GAEF,MAAM,aAAa,KAAK,OAAO,SAAS,qBAAqB,KAAK,OAAO,WAAW;GACpF,QAAQ,OAAO;IAAE,MAAM;IAAY,WAAW;GAAgB,CAAC;EACjE,EACF;CACF;AACF,CAAC"}

package/eslint/rules/require_validator_any_required.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module @nhtio/adk/eslint/rules/require_validator_any_required
+ *
+ * Flags every `validator.any()` schema chain that does not declare intent with `.required()`
+ * or `.optional()`.
+ *
+ * Why: in `@nhtio/validation`, `.any()` ADMITS `null`/`undefined` unless you make it `.required()`.
+ * That default is silent and easy to miss — a schema you believe rejects missing values quietly
+ * accepts them, and any `.custom()` refinement is skipped for an absent value (a `.custom()` guard
+ * is the usual way this surfaces, e.g. `implementsX(undefined) === true`). The fix is to make the
+ * disposition an EXPLICIT declaration with no ambiguity — every `.any()` must say which it is:
+ *   - `.required()`  → reject null/undefined
+ *   - `.optional()`  → deliberately allow null/undefined
+ *   - `.default(x)`  → allow absence, substituting a fallback value
+ *   - `.forbidden()` → the value must be absent
+ * This applies whether the `.any()` is top-level or nested inside `items(...)` / `alternatives(...)`:
+ * the enclosing schema being `.required()` does NOT govern an inner `.any()`'s null/undefined handling.
+ *
+ * The sharpest illustration is `.valid(null)`: an author writing `validator.any().valid(null)`
+ * means "must be exactly null" — but because `.any()` admits `undefined`, that schema actually
+ * accepts BOTH `null` and `undefined` (and `undefined !== null`). The fix is
+ * `validator.any().required().valid(null)`.
+ *
+ * Opt-out (e.g. a bare `.any()` used purely as a type argument like `items(validator.any())`):
+ *   // eslint-disable-next-line adk/require-validator-any-required -- <reason>
+ */
+declare const requireValidatorAnyRequiredRule: import("@typescript-eslint/utils/ts-eslint").RuleModule<"declareIntent", [
+], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default requireValidatorAnyRequiredRule;

package/eslint/rules/require_validator_any_required.mjs

@@ -0,0 +1,95 @@
+import { t as createRule } from "../../common-BUIjZ6LV.mjs";
+//#region src/eslint/rules/require_validator_any_required.ts
+/**
+* @module @nhtio/adk/eslint/rules/require_validator_any_required
+*
+* Flags every `validator.any()` schema chain that does not declare intent with `.required()`
+* or `.optional()`.
+*
+* Why: in `@nhtio/validation`, `.any()` ADMITS `null`/`undefined` unless you make it `.required()`.
+* That default is silent and easy to miss — a schema you believe rejects missing values quietly
+* accepts them, and any `.custom()` refinement is skipped for an absent value (a `.custom()` guard
+* is the usual way this surfaces, e.g. `implementsX(undefined) === true`). The fix is to make the
+* disposition an EXPLICIT declaration with no ambiguity — every `.any()` must say which it is:
+*   - `.required()`  → reject null/undefined
+*   - `.optional()`  → deliberately allow null/undefined
+*   - `.default(x)`  → allow absence, substituting a fallback value
+*   - `.forbidden()` → the value must be absent
+* This applies whether the `.any()` is top-level or nested inside `items(...)` / `alternatives(...)`:
+* the enclosing schema being `.required()` does NOT govern an inner `.any()`'s null/undefined handling.
+*
+* The sharpest illustration is `.valid(null)`: an author writing `validator.any().valid(null)`
+* means "must be exactly null" — but because `.any()` admits `undefined`, that schema actually
+* accepts BOTH `null` and `undefined` (and `undefined !== null`). The fix is
+* `validator.any().required().valid(null)`.
+*
+* Opt-out (e.g. a bare `.any()` used purely as a type argument like `items(validator.any())`):
+*   // eslint-disable-next-line adk/require-validator-any-required -- <reason>
+*/
+var baseIdentifierName = (node) => {
+	let cur = node;
+	while (cur) {
+		if (cur.type === "Identifier") return cur.name;
+		if (cur.type === "MemberExpression") {
+			cur = cur.object;
+			continue;
+		}
+		if (cur.type === "CallExpression") {
+			cur = cur.callee;
+			continue;
+		}
+		return;
+	}
+};
+var isAnyCall = (node) => node.callee.type === "MemberExpression" && node.callee.property.type === "Identifier" && node.callee.property.name === "any" && baseIdentifierName(node.callee.object) === "validator";
+var collectChainCalls = (anyCall) => {
+	const calls = [];
+	let cur = anyCall;
+	while (cur && cur.type === "CallExpression") {
+		calls.push(cur);
+		cur = cur.callee.type === "MemberExpression" ? cur.callee.object : null;
+	}
+	cur = anyCall;
+	while (cur) {
+		const p = cur.parent;
+		if (!p) break;
+		if (p.type === "MemberExpression" && p.object === cur) {
+			cur = p;
+			continue;
+		}
+		if (p.type === "CallExpression" && p.callee === cur) {
+			calls.push(p);
+			cur = p;
+			continue;
+		}
+		break;
+	}
+	return calls;
+};
+var chainCalls = (calls, name) => calls.some((c) => c.callee.type === "MemberExpression" && c.callee.property.type === "Identifier" && c.callee.property.name === name);
+var requireValidatorAnyRequiredRule = createRule({
+	name: "require-validator-any-required",
+	meta: {
+		type: "problem",
+		docs: { description: "`validator.any()` admits null/undefined unless `.required()`; make the disposition explicit by ending every `.any()` in `.required()`, `.optional()`, or `.default(…)`. Opt out with a tactical disable comment + reason." },
+		schema: [],
+		messages: { declareIntent: "`validator.any()` admits null/undefined unless made `.required()`. Make the disposition explicit: end this `.any()` in `.required()` (reject null/undefined), `.optional()` (deliberately allow it), or `.default(…)` (allow it with a fallback) — applies even when nested in items()/alternatives(). Or add an eslint-disable-next-line adk/require-validator-any-required comment with a reason." }
+	},
+	defaultOptions: [],
+	create(context) {
+		return { CallExpression(node) {
+			if (!isAnyCall(node)) return;
+			const calls = collectChainCalls(node);
+			if (chainCalls(calls, "required") || chainCalls(calls, "optional") || chainCalls(calls, "default") || chainCalls(calls, "forbidden")) return;
+			const reportNode = node.callee.type === "MemberExpression" ? node.callee.property : node;
+			context.report({
+				node: reportNode,
+				messageId: "declareIntent"
+			});
+		} };
+	}
+});
+//#endregion
+export { requireValidatorAnyRequiredRule as default };
+
+//# sourceMappingURL=require_validator_any_required.mjs.map

package/eslint/rules/require_validator_any_required.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"require_validator_any_required.mjs","names":[],"sources":["../../../src/eslint/rules/require_validator_any_required.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/eslint/rules/require_validator_any_required\n *\n * Flags every `validator.any()` schema chain that does not declare intent with `.required()`\n * or `.optional()`.\n *\n * Why: in `@nhtio/validation`, `.any()` ADMITS `null`/`undefined` unless you make it `.required()`.\n * That default is silent and easy to miss — a schema you believe rejects missing values quietly\n * accepts them, and any `.custom()` refinement is skipped for an absent value (a `.custom()` guard\n * is the usual way this surfaces, e.g. `implementsX(undefined) === true`). The fix is to make the\n * disposition an EXPLICIT declaration with no ambiguity — every `.any()` must say which it is:\n *   - `.required()`  → reject null/undefined\n *   - `.optional()`  → deliberately allow null/undefined\n *   - `.default(x)`  → allow absence, substituting a fallback value\n *   - `.forbidden()` → the value must be absent\n * This applies whether the `.any()` is top-level or nested inside `items(...)` / `alternatives(...)`:\n * the enclosing schema being `.required()` does NOT govern an inner `.any()`'s null/undefined handling.\n *\n * The sharpest illustration is `.valid(null)`: an author writing `validator.any().valid(null)`\n * means \"must be exactly null\" — but because `.any()` admits `undefined`, that schema actually\n * accepts BOTH `null` and `undefined` (and `undefined !== null`). The fix is\n * `validator.any().required().valid(null)`.\n *\n * Opt-out (e.g. a bare `.any()` used purely as a type argument like `items(validator.any())`):\n *   // eslint-disable-next-line adk/require-validator-any-required -- <reason>\n */\n\nimport { createRule } from './common'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\n// The base identifier a member/call chain roots at, e.g. `validator` in `validator.any()` or\n// `validator.alternatives(...).any()`. Returns undefined if the chain doesn't root at a plain name.\nconst baseIdentifierName = (node: TSESTree.Node | undefined): string | undefined => {\n  let cur: TSESTree.Node | undefined = node\n  while (cur) {\n    if (cur.type === 'Identifier') return cur.name\n    if (cur.type === 'MemberExpression') {\n      cur = cur.object\n      continue\n    }\n    if (cur.type === 'CallExpression') {\n      cur = cur.callee\n      continue\n    }\n    return undefined\n  }\n  return undefined\n}\n\n// `validator.any()` (or a `validator.…().any()` chain) — NOT `expect.any()`, `_.any()`, etc.\nconst isAnyCall = (node: TSESTree.CallExpression): boolean =>\n  node.callee.type === 'MemberExpression' &&\n  node.callee.property.type === 'Identifier' &&\n  node.callee.property.name === 'any' &&\n  baseIdentifierName(node.callee.object) === 'validator'\n\n// Collect every CallExpression in the method chain `anyCall` belongs to — inward through the\n// callee object (`a.b().c()` -> `a.b()`) and outward through `.parent` links\n// (`x.any()` -> `x.any().required` -> `x.any().required()`).\nconst collectChainCalls = (anyCall: TSESTree.CallExpression): TSESTree.CallExpression[] => {\n  const calls: TSESTree.CallExpression[] = []\n\n  let cur: TSESTree.Node | null = anyCall\n  while (cur && cur.type === 'CallExpression') {\n    calls.push(cur)\n    cur = cur.callee.type === 'MemberExpression' ? cur.callee.object : null\n  }\n\n  cur = anyCall\n  while (cur) {\n    const p: TSESTree.Node | undefined = cur.parent\n    if (!p) break\n    if (p.type === 'MemberExpression' && p.object === cur) {\n      cur = p\n      continue\n    }\n    if (p.type === 'CallExpression' && p.callee === cur) {\n      calls.push(p)\n      cur = p\n      continue\n    }\n    break\n  }\n\n  return calls\n}\n\nconst chainCalls = (calls: TSESTree.CallExpression[], name: string): boolean =>\n  calls.some(\n    (c) =>\n      c.callee.type === 'MemberExpression' &&\n      c.callee.property.type === 'Identifier' &&\n      c.callee.property.name === name\n  )\n\nconst requireValidatorAnyRequiredRule = createRule({\n  name: 'require-validator-any-required',\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        '`validator.any()` admits null/undefined unless `.required()`; make the disposition explicit by ending every `.any()` in `.required()`, `.optional()`, or `.default(…)`. Opt out with a tactical disable comment + reason.',\n    },\n    schema: [],\n    messages: {\n      declareIntent:\n        '`validator.any()` admits null/undefined unless made `.required()`. Make the disposition explicit: end this `.any()` in `.required()` (reject null/undefined), `.optional()` (deliberately allow it), or `.default(…)` (allow it with a fallback) — applies even when nested in items()/alternatives(). Or add an eslint-disable-next-line adk/require-validator-any-required comment with a reason.',\n    },\n  },\n  defaultOptions: [],\n  create(context) {\n    return {\n      CallExpression(node: TSESTree.CallExpression) {\n        if (!isAnyCall(node)) return\n        const calls = collectChainCalls(node)\n        // An unambiguous disposition declaration clears the rule:\n        //   .required()  — reject null/undefined\n        //   .optional()  — deliberately allow null/undefined\n        //   .default(x)  — allow absence, substituting a fallback\n        //   .forbidden() — the value must be absent\n        if (\n          chainCalls(calls, 'required') ||\n          chainCalls(calls, 'optional') ||\n          chainCalls(calls, 'default') ||\n          chainCalls(calls, 'forbidden')\n        ) {\n          return\n        }\n        const reportNode = node.callee.type === 'MemberExpression' ? node.callee.property : node\n        context.report({ node: reportNode, messageId: 'declareIntent' })\n      },\n    }\n  },\n})\n\nexport default requireValidatorAnyRequiredRule\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,IAAM,sBAAsB,SAAwD;CAClF,IAAI,MAAiC;CACrC,OAAO,KAAK;EACV,IAAI,IAAI,SAAS,cAAc,OAAO,IAAI;EAC1C,IAAI,IAAI,SAAS,oBAAoB;GACnC,MAAM,IAAI;GACV;EACF;EACA,IAAI,IAAI,SAAS,kBAAkB;GACjC,MAAM,IAAI;GACV;EACF;EACA;CACF;AAEF;AAGA,IAAM,aAAa,SACjB,KAAK,OAAO,SAAS,sBACrB,KAAK,OAAO,SAAS,SAAS,gBAC9B,KAAK,OAAO,SAAS,SAAS,SAC9B,mBAAmB,KAAK,OAAO,MAAM,MAAM;AAK7C,IAAM,qBAAqB,YAAgE;CACzF,MAAM,QAAmC,CAAC;CAE1C,IAAI,MAA4B;CAChC,OAAO,OAAO,IAAI,SAAS,kBAAkB;EAC3C,MAAM,KAAK,GAAG;EACd,MAAM,IAAI,OAAO,SAAS,qBAAqB,IAAI,OAAO,SAAS;CACrE;CAEA,MAAM;CACN,OAAO,KAAK;EACV,MAAM,IAA+B,IAAI;EACzC,IAAI,CAAC,GAAG;EACR,IAAI,EAAE,SAAS,sBAAsB,EAAE,WAAW,KAAK;GACrD,MAAM;GACN;EACF;EACA,IAAI,EAAE,SAAS,oBAAoB,EAAE,WAAW,KAAK;GACnD,MAAM,KAAK,CAAC;GACZ,MAAM;GACN;EACF;EACA;CACF;CAEA,OAAO;AACT;AAEA,IAAM,cAAc,OAAkC,SACpD,MAAM,MACH,MACC,EAAE,OAAO,SAAS,sBAClB,EAAE,OAAO,SAAS,SAAS,gBAC3B,EAAE,OAAO,SAAS,SAAS,IAC/B;AAEF,IAAM,kCAAkC,WAAW;CACjD,MAAM;CACN,MAAM;EACJ,MAAM;EACN,MAAM,EACJ,aACE,4NACJ;EACA,QAAQ,CAAC;EACT,UAAU,EACR,eACE,sYACJ;CACF;CACA,gBAAgB,CAAC;CACjB,OAAO,SAAS;EACd,OAAO,EACL,eAAe,MAA+B;GAC5C,IAAI,CAAC,UAAU,IAAI,GAAG;GACtB,MAAM,QAAQ,kBAAkB,IAAI;GAMpC,IACE,WAAW,OAAO,UAAU,KAC5B,WAAW,OAAO,UAAU,KAC5B,WAAW,OAAO,SAAS,KAC3B,WAAW,OAAO,WAAW,GAE7B;GAEF,MAAM,aAAa,KAAK,OAAO,SAAS,qBAAqB,KAAK,OAAO,WAAW;GACpF,QAAQ,OAAO;IAAE,MAAM;IAAY,WAAW;GAAgB,CAAC;EACjE,EACF;CACF;AACF,CAAC"}

package/eslint/rules/thought_payload_requires_replay_tag.cjs

@@ -0,0 +1,71 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Ble4zEEl.js");
+const require_common = require("../../common-DeNipTQI.js");
+//#region src/eslint/rules/thought_payload_requires_replay_tag.ts
+/**
+* @module @nhtio/adk/eslint/rules/thought_payload_requires_replay_tag
+*
+* Flags `new Thought({ … })` whose options literal sets a `payload` but omits a
+* `replayCompatibility` tag.
+*
+* Why: a `Thought` may carry a vendor-opaque `payload` that the harness cannot interpret, to be
+* replayed back to a matching model wire. The ADK can only route that payload if the thought also
+* declares which adapter wire-shape it is replayable into, via `replayCompatibility`. A `payload`
+* with no `replayCompatibility` is a footgun: the harness has no way to know which adapter can
+* consume it, so it is dropped silently. The `Thought` constructor enforces this cross-field
+* invariant at runtime (`payload` present ⇒ `replayCompatibility` required); this rule surfaces it
+* statically at the construction site so it fails lint, not just at runtime.
+*
+* Detects the common literal form: a `new Thought({ … })` options object that has a `payload`
+* property but no `replayCompatibility` property. Spreads or computed keys are not analyzable here —
+* those fall back to the runtime check.
+*
+* Opt-out:
+*   // eslint-disable-next-line adk/thought-payload-requires-replay-tag -- <reason>
+*/
+var literalKey = (prop) => {
+	if (prop.computed) return void 0;
+	if (prop.key.type === "Identifier") return prop.key.name;
+	if (prop.key.type === "Literal" && typeof prop.key.value === "string") return prop.key.value;
+};
+var isUndefinedValue = (node) => node.type === "Identifier" && node.name === "undefined";
+var thoughtPayloadRequiresReplayTagRule = require_common.createRule({
+	name: "thought-payload-requires-replay-tag",
+	meta: {
+		type: "problem",
+		docs: { description: "A `Thought` carrying a `payload` must declare `replayCompatibility`; otherwise the harness cannot route the opaque payload to a matching adapter and drops it. Enforced at runtime by the Thought constructor; this surfaces it at the construction site." },
+		schema: [],
+		messages: { requireReplayTag: "`new Thought({ payload })` requires a `replayCompatibility` tag — without it the harness cannot route the opaque payload to an adapter and silently drops it. Add `replayCompatibility: \"<wire-shape-id>\"`, or remove the payload. Opt out with an eslint-disable-next-line adk/thought-payload-requires-replay-tag comment + reason." }
+	},
+	defaultOptions: [],
+	create(context) {
+		return { NewExpression(node) {
+			if (node.callee.type !== "Identifier" || node.callee.name !== "Thought") return;
+			const arg = node.arguments[0];
+			if (!arg || arg.type !== "ObjectExpression") return;
+			let payloadProp;
+			let hasReplayTag = false;
+			let hasSpread = false;
+			for (const p of arg.properties) {
+				if (p.type === "SpreadElement") {
+					hasSpread = true;
+					continue;
+				}
+				const key = literalKey(p);
+				if (key === "payload" && !isUndefinedValue(p.value)) payloadProp = p;
+				else if (key === "replayCompatibility" && !isUndefinedValue(p.value)) hasReplayTag = true;
+			}
+			if (payloadProp && !hasReplayTag && !hasSpread) context.report({
+				node: payloadProp,
+				messageId: "requireReplayTag"
+			});
+		} };
+	}
+});
+//#endregion
+exports.default = thoughtPayloadRequiresReplayTagRule;
+
+//# sourceMappingURL=thought_payload_requires_replay_tag.cjs.map

package/eslint/rules/thought_payload_requires_replay_tag.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"thought_payload_requires_replay_tag.cjs","names":[],"sources":["../../../src/eslint/rules/thought_payload_requires_replay_tag.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/eslint/rules/thought_payload_requires_replay_tag\n *\n * Flags `new Thought({ … })` whose options literal sets a `payload` but omits a\n * `replayCompatibility` tag.\n *\n * Why: a `Thought` may carry a vendor-opaque `payload` that the harness cannot interpret, to be\n * replayed back to a matching model wire. The ADK can only route that payload if the thought also\n * declares which adapter wire-shape it is replayable into, via `replayCompatibility`. A `payload`\n * with no `replayCompatibility` is a footgun: the harness has no way to know which adapter can\n * consume it, so it is dropped silently. The `Thought` constructor enforces this cross-field\n * invariant at runtime (`payload` present ⇒ `replayCompatibility` required); this rule surfaces it\n * statically at the construction site so it fails lint, not just at runtime.\n *\n * Detects the common literal form: a `new Thought({ … })` options object that has a `payload`\n * property but no `replayCompatibility` property. Spreads or computed keys are not analyzable here —\n * those fall back to the runtime check.\n *\n * Opt-out:\n *   // eslint-disable-next-line adk/thought-payload-requires-replay-tag -- <reason>\n */\n\nimport { createRule } from './common'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\nconst literalKey = (prop: TSESTree.Property): string | undefined => {\n  if (prop.computed) return undefined\n  if (prop.key.type === 'Identifier') return prop.key.name\n  if (prop.key.type === 'Literal' && typeof prop.key.value === 'string') return prop.key.value\n  return undefined\n}\n\n// True when the property value is statically `undefined` (the absent case) — `payload: undefined`\n// is equivalent to omitting it, so it should not trigger the rule.\nconst isUndefinedValue = (node: TSESTree.Node): boolean =>\n  node.type === 'Identifier' && node.name === 'undefined'\n\nconst thoughtPayloadRequiresReplayTagRule = createRule({\n  name: 'thought-payload-requires-replay-tag',\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'A `Thought` carrying a `payload` must declare `replayCompatibility`; otherwise the harness cannot route the opaque payload to a matching adapter and drops it. Enforced at runtime by the Thought constructor; this surfaces it at the construction site.',\n    },\n    schema: [],\n    messages: {\n      requireReplayTag:\n        '`new Thought({ payload })` requires a `replayCompatibility` tag — without it the harness cannot route the opaque payload to an adapter and silently drops it. Add `replayCompatibility: \"<wire-shape-id>\"`, or remove the payload. Opt out with an eslint-disable-next-line adk/thought-payload-requires-replay-tag comment + reason.',\n    },\n  },\n  defaultOptions: [],\n  create(context) {\n    return {\n      NewExpression(node: TSESTree.NewExpression) {\n        if (node.callee.type !== 'Identifier' || node.callee.name !== 'Thought') return\n        const arg = node.arguments[0]\n        if (!arg || arg.type !== 'ObjectExpression') return\n\n        let payloadProp: TSESTree.Property | undefined\n        let hasReplayTag = false\n        let hasSpread = false\n        for (const p of arg.properties) {\n          if (p.type === 'SpreadElement') {\n            hasSpread = true\n            continue\n          }\n          const key = literalKey(p)\n          if (key === 'payload' && !isUndefinedValue(p.value)) payloadProp = p\n          else if (key === 'replayCompatibility' && !isUndefinedValue(p.value)) hasReplayTag = true\n        }\n\n        // A spread could supply replayCompatibility we can't see — stay conservative, don't flag.\n        if (payloadProp && !hasReplayTag && !hasSpread) {\n          context.report({ node: payloadProp, messageId: 'requireReplayTag' })\n        }\n      },\n    }\n  },\n})\n\nexport default thoughtPayloadRequiresReplayTagRule\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,IAAM,cAAc,SAAgD;CAClE,IAAI,KAAK,UAAU,OAAO,KAAA;CAC1B,IAAI,KAAK,IAAI,SAAS,cAAc,OAAO,KAAK,IAAI;CACpD,IAAI,KAAK,IAAI,SAAS,aAAa,OAAO,KAAK,IAAI,UAAU,UAAU,OAAO,KAAK,IAAI;AAEzF;AAIA,IAAM,oBAAoB,SACxB,KAAK,SAAS,gBAAgB,KAAK,SAAS;AAE9C,IAAM,sCAAsC,eAAA,WAAW;CACrD,MAAM;CACN,MAAM;EACJ,MAAM;EACN,MAAM,EACJ,aACE,4PACJ;EACA,QAAQ,CAAC;EACT,UAAU,EACR,kBACE,0UACJ;CACF;CACA,gBAAgB,CAAC;CACjB,OAAO,SAAS;EACd,OAAO,EACL,cAAc,MAA8B;GAC1C,IAAI,KAAK,OAAO,SAAS,gBAAgB,KAAK,OAAO,SAAS,WAAW;GACzE,MAAM,MAAM,KAAK,UAAU;GAC3B,IAAI,CAAC,OAAO,IAAI,SAAS,oBAAoB;GAE7C,IAAI;GACJ,IAAI,eAAe;GACnB,IAAI,YAAY;GAChB,KAAK,MAAM,KAAK,IAAI,YAAY;IAC9B,IAAI,EAAE,SAAS,iBAAiB;KAC9B,YAAY;KACZ;IACF;IACA,MAAM,MAAM,WAAW,CAAC;IACxB,IAAI,QAAQ,aAAa,CAAC,iBAAiB,EAAE,KAAK,GAAG,cAAc;SAC9D,IAAI,QAAQ,yBAAyB,CAAC,iBAAiB,EAAE,KAAK,GAAG,eAAe;GACvF;GAGA,IAAI,eAAe,CAAC,gBAAgB,CAAC,WACnC,QAAQ,OAAO;IAAE,MAAM;IAAa,WAAW;GAAmB,CAAC;EAEvE,EACF;CACF;AACF,CAAC"}

package/eslint/rules/thought_payload_requires_replay_tag.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module @nhtio/adk/eslint/rules/thought_payload_requires_replay_tag
+ *
+ * Flags `new Thought({ … })` whose options literal sets a `payload` but omits a
+ * `replayCompatibility` tag.
+ *
+ * Why: a `Thought` may carry a vendor-opaque `payload` that the harness cannot interpret, to be
+ * replayed back to a matching model wire. The ADK can only route that payload if the thought also
+ * declares which adapter wire-shape it is replayable into, via `replayCompatibility`. A `payload`
+ * with no `replayCompatibility` is a footgun: the harness has no way to know which adapter can
+ * consume it, so it is dropped silently. The `Thought` constructor enforces this cross-field
+ * invariant at runtime (`payload` present ⇒ `replayCompatibility` required); this rule surfaces it
+ * statically at the construction site so it fails lint, not just at runtime.
+ *
+ * Detects the common literal form: a `new Thought({ … })` options object that has a `payload`
+ * property but no `replayCompatibility` property. Spreads or computed keys are not analyzable here —
+ * those fall back to the runtime check.
+ *
+ * Opt-out:
+ *   // eslint-disable-next-line adk/thought-payload-requires-replay-tag -- <reason>
+ */
+declare const thoughtPayloadRequiresReplayTagRule: import("@typescript-eslint/utils/ts-eslint").RuleModule<"requireReplayTag", [
+], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default thoughtPayloadRequiresReplayTagRule;

package/eslint/rules/thought_payload_requires_replay_tag.mjs

@@ -0,0 +1,66 @@
+import { t as createRule } from "../../common-BUIjZ6LV.mjs";
+//#region src/eslint/rules/thought_payload_requires_replay_tag.ts
+/**
+* @module @nhtio/adk/eslint/rules/thought_payload_requires_replay_tag
+*
+* Flags `new Thought({ … })` whose options literal sets a `payload` but omits a
+* `replayCompatibility` tag.
+*
+* Why: a `Thought` may carry a vendor-opaque `payload` that the harness cannot interpret, to be
+* replayed back to a matching model wire. The ADK can only route that payload if the thought also
+* declares which adapter wire-shape it is replayable into, via `replayCompatibility`. A `payload`
+* with no `replayCompatibility` is a footgun: the harness has no way to know which adapter can
+* consume it, so it is dropped silently. The `Thought` constructor enforces this cross-field
+* invariant at runtime (`payload` present ⇒ `replayCompatibility` required); this rule surfaces it
+* statically at the construction site so it fails lint, not just at runtime.
+*
+* Detects the common literal form: a `new Thought({ … })` options object that has a `payload`
+* property but no `replayCompatibility` property. Spreads or computed keys are not analyzable here —
+* those fall back to the runtime check.
+*
+* Opt-out:
+*   // eslint-disable-next-line adk/thought-payload-requires-replay-tag -- <reason>
+*/
+var literalKey = (prop) => {
+	if (prop.computed) return void 0;
+	if (prop.key.type === "Identifier") return prop.key.name;
+	if (prop.key.type === "Literal" && typeof prop.key.value === "string") return prop.key.value;
+};
+var isUndefinedValue = (node) => node.type === "Identifier" && node.name === "undefined";
+var thoughtPayloadRequiresReplayTagRule = createRule({
+	name: "thought-payload-requires-replay-tag",
+	meta: {
+		type: "problem",
+		docs: { description: "A `Thought` carrying a `payload` must declare `replayCompatibility`; otherwise the harness cannot route the opaque payload to a matching adapter and drops it. Enforced at runtime by the Thought constructor; this surfaces it at the construction site." },
+		schema: [],
+		messages: { requireReplayTag: "`new Thought({ payload })` requires a `replayCompatibility` tag — without it the harness cannot route the opaque payload to an adapter and silently drops it. Add `replayCompatibility: \"<wire-shape-id>\"`, or remove the payload. Opt out with an eslint-disable-next-line adk/thought-payload-requires-replay-tag comment + reason." }
+	},
+	defaultOptions: [],
+	create(context) {
+		return { NewExpression(node) {
+			if (node.callee.type !== "Identifier" || node.callee.name !== "Thought") return;
+			const arg = node.arguments[0];
+			if (!arg || arg.type !== "ObjectExpression") return;
+			let payloadProp;
+			let hasReplayTag = false;
+			let hasSpread = false;
+			for (const p of arg.properties) {
+				if (p.type === "SpreadElement") {
+					hasSpread = true;
+					continue;
+				}
+				const key = literalKey(p);
+				if (key === "payload" && !isUndefinedValue(p.value)) payloadProp = p;
+				else if (key === "replayCompatibility" && !isUndefinedValue(p.value)) hasReplayTag = true;
+			}
+			if (payloadProp && !hasReplayTag && !hasSpread) context.report({
+				node: payloadProp,
+				messageId: "requireReplayTag"
+			});
+		} };
+	}
+});
+//#endregion
+export { thoughtPayloadRequiresReplayTagRule as default };
+
+//# sourceMappingURL=thought_payload_requires_replay_tag.mjs.map