@warlock.js/ai 4.4.0 → 4.5.0

package/esm/prompts/prompts-validate.mjs

@@ -0,0 +1,200 @@
+import { judge } from "../eval/judge-scorer.mjs";
+import { agent } from "../agent/agent.mjs";
+import { PROMPT_JUDGE_RUBRIC } from "../prompt/prompt-validate.mjs";
+
+//#region ../@warlock.js/ai/src/prompts/prompts-validate.ts
+/**
+* Placeholder matcher — kept in lock-step with the matcher
+* `renderPlaceholders` (`src/system-prompt/render-placeholders.ts`) and the
+* legacy `prompt-validate` lint both use, so the deterministic validator sees
+* the exact same `{{key}}` / `{{a.b}}` / `{{key|default}}` set the renderer
+* substitutes. Global so every occurrence is collected.
+*/
+const PLACEHOLDER_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
+/**
+* Collect every distinct placeholder occurrence from a template, in first-seen
+* order. A key is considered to "have a default" only when EVERY occurrence of
+* it carries one — a single bare `{{key}}` means the renderer can leave it
+* unresolved, so the key is still required.
+*/
+function collectPlaceholders(template) {
+	const byPath = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const match of template.matchAll(PLACEHOLDER_PATTERN)) {
+		const [rawPath, rawDefault] = match[1].split("|");
+		const path = rawPath.trim();
+		if (path.length === 0) continue;
+		const hasDefault = rawDefault !== void 0;
+		if (!byPath.has(path)) {
+			byPath.set(path, hasDefault);
+			order.push(path);
+		} else byPath.set(path, (byPath.get(path) ?? false) && hasDefault);
+	}
+	return order.map((path) => ({
+		path,
+		hasDefault: byPath.get(path) ?? false
+	}));
+}
+/**
+* Run the deterministic (model-free) half of validation over a resolved prompt
+* body. Reports every `{{key}}` placeholder that has NO inline default and is
+* neither supplied in `provided` nor declared in `declared` (the prompt's
+* `meta.required` plus any caller-declared keys).
+*
+* Pure and synchronous — the only required half of `validate`; the LLM-judge
+* half is optional and layered on top.
+*
+* @param text - The resolved prompt body (placeholders may still be present).
+* @param provided - Placeholder keys the caller has supplied a value for.
+* @param declared - Placeholder keys declared as known/required (e.g. `meta.required`).
+*/
+function findMissingPlaceholders(text, provided, declared) {
+	const missing = [];
+	for (const { path, hasDefault } of collectPlaceholders(text)) {
+		if (hasDefault) continue;
+		if (provided.has(path) || declared.has(path)) continue;
+		missing.push(path);
+	}
+	return missing;
+}
+/**
+* A `meta.required` key absent from the template entirely — declared as
+* required but never referenced — is itself a defect worth surfacing. Returns
+* the declared keys that appear nowhere in the body.
+*/
+function findUnreferencedRequired(text, required) {
+	const present = new Set(collectPlaceholders(text).map((p) => p.path));
+	return required.filter((key) => !present.has(key));
+}
+/**
+* Build the one-shot judge agent the optional LLM-as-judge pass runs. Mirrors
+* the legacy `prompt.ts` judge agent (strict-JSON instruction so the verdict
+* parses even without an output schema), so the two validate paths share one
+* judging contract.
+*/
+function buildJudgeAgent(model) {
+	return agent({
+		name: "prompt-quality-judge",
+		model,
+		systemPrompt: "You are a strict prompt-quality grader. Respond with JSON only: { \"score\": <0..1>, \"passed\": <true|false>, \"reason\": \"<short explanation>\" }."
+	});
+}
+/**
+* Run the optional LLM-as-judge pass over a resolved prompt body, REUSING the
+* eval `judge` scorer (the same path `prompt().validate` uses) so there is no
+* second judging implementation.
+*
+* **Nova-safe by contract.** The judge NEVER throws here: the eval scorer
+* already degrades a broken judge to `score: 0` with a failure reason, and any
+* exception that still escapes (model wiring, agent construction) is caught.
+* Both degrade paths surface `score: undefined` plus an issue note — so a flaky
+* judge can never fail an otherwise-valid prompt.
+*
+* @param text - The resolved prompt body under evaluation.
+* @param model - The model that powers the judge agent.
+*/
+async function judgePromptBody(text, model) {
+	try {
+		const verdict = await judge({
+			agent: buildJudgeAgent(model),
+			rubric: PROMPT_JUDGE_RUBRIC
+		})({
+			case: {
+				name: "prompt-quality",
+				input: "Grade the system prompt below."
+			},
+			text,
+			result: { text },
+			output: void 0
+		});
+		if (verdict.score === 0 && typeof verdict.reason === "string" && /^judge (failed|returned no parseable)/.test(verdict.reason)) return { issues: [`LLM-judge unavailable: ${verdict.reason}`] };
+		return {
+			score: verdict.score,
+			issues: verdict.reason ? [verdict.reason] : []
+		};
+	} catch (error) {
+		return { issues: [`LLM-judge unavailable: ${error instanceof Error ? error.message : String(error)}`] };
+	}
+}
+/**
+* Non-cryptographic 53-bit string hash (cyrb53) — deterministic across runs
+* and platforms, with no `node:crypto` dependency (keeps the validate path
+* usable in any runtime). Mirrors the VCR request hash; collision-resistant
+* enough for a per-prompt judge-verdict keyspace. Returned as base-36.
+*/
+function hashString(input) {
+	let h1 = 3735928559;
+	let h2 = 1103547991;
+	for (let i = 0; i < input.length; i++) {
+		const ch = input.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507);
+	h1 ^= Math.imul(h2 ^ h2 >>> 13, 3266489909);
+	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507);
+	h2 ^= Math.imul(h1 ^ h1 >>> 13, 3266489909);
+	return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+/**
+* Build the judge-verdict cache key for a resolved prompt body + judge model.
+* Combines the model's `provider:name` identity with a content hash of the
+* body, so the same prompt graded by the same judge hits the cache, while any
+* change to either misses it.
+*/
+function judgeCacheKey(text, model) {
+	return `prompts.judge.${model.provider}:${model.name}.${hashString(text)}`;
+}
+/**
+* Run the judge pass with an OPTIONAL memo cache in front. On a hit, the stored
+* {@link JudgeOutcome} is returned without a model call; on a miss, the live
+* judge runs and a USABLE verdict (one carrying a `score`) is written back.
+* Degraded outcomes (no score) are NOT cached — a transient judge failure must
+* never poison the memo. A `null`/absent cache degrades to a direct judge call.
+*
+* Cache I/O is itself fault-tolerant: a `get`/`set` that rejects is swallowed
+* so a flaky cache can never break (or fail) validation.
+*
+* @param text - The resolved prompt body under evaluation.
+* @param model - The judge model.
+* @param cache - Optional verdict memo (any `CacheDriver`-like get/set surface).
+*/
+async function judgePromptBodyCached(text, model, cache) {
+	if (!cache) return judgePromptBody(text, model);
+	const key = judgeCacheKey(text, model);
+	const cached = await readJudgeCache(cache, key);
+	if (cached) return cached;
+	const outcome = await judgePromptBody(text, model);
+	if (outcome.score !== void 0) await writeJudgeCache(cache, key, outcome);
+	return outcome;
+}
+/** Read a cached verdict, swallowing any cache fault (treated as a miss). */
+async function readJudgeCache(cache, key) {
+	try {
+		return await cache.get(key) ?? void 0;
+	} catch {
+		return;
+	}
+}
+/** Write a verdict, swallowing any cache fault (best-effort memo). */
+async function writeJudgeCache(cache, key, outcome) {
+	try {
+		await cache.set(key, outcome);
+	} catch {}
+}
+/**
+* Resolve the body + declared-required keys for a validation target that is a
+* `SystemPromptContract` (named or anonymous). The declared set is the
+* prompt's `meta.required` (when present).
+*/
+function describeContractTarget(contract) {
+	const meta = contract.meta();
+	return {
+		text: contract.resolve(),
+		required: meta?.required ?? []
+	};
+}
+
+//#endregion
+export { describeContractTarget, findMissingPlaceholders, findUnreferencedRequired, judgePromptBodyCached };
+//# sourceMappingURL=prompts-validate.mjs.map

package/esm/prompts/prompts-validate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts-validate.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/prompts/prompts-validate.ts"],"sourcesContent":["import { agent } from \"../agent/agent\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { ModelContract } from \"../contracts/model.contract\";\nimport type { SystemPromptContract } from \"../contracts/system-prompt.contract\";\nimport { judge } from \"../eval/judge-scorer\";\nimport { PROMPT_JUDGE_RUBRIC } from \"../prompt/prompt-validate\";\nimport type { PromptJudgeCacheLike } from \"./prompts-manager.type\";\n\n/**\n * Placeholder matcher — kept in lock-step with the matcher\n * `renderPlaceholders` (`src/system-prompt/render-placeholders.ts`) and the\n * legacy `prompt-validate` lint both use, so the deterministic validator sees\n * the exact same `{{key}}` / `{{a.b}}` / `{{key|default}}` set the renderer\n * substitutes. Global so every occurrence is collected.\n */\nconst PLACEHOLDER_PATTERN = /\\{\\{\\s*([^{}]+?)\\s*\\}\\}/g;\n\n/**\n * One parsed placeholder occurrence — the key path (the part before any\n * `|default`) and whether the occurrence carried an inline default.\n */\ntype ParsedPlaceholder = {\n  /** The dot-path key, e.g. `language` or `user.name`. */\n  readonly path: string;\n  /** Whether THIS occurrence declared an inline `{{key|default}}` fallback. */\n  readonly hasDefault: boolean;\n};\n\n/**\n * Collect every distinct placeholder occurrence from a template, in first-seen\n * order. A key is considered to \"have a default\" only when EVERY occurrence of\n * it carries one — a single bare `{{key}}` means the renderer can leave it\n * unresolved, so the key is still required.\n */\nfunction collectPlaceholders(template: string): ParsedPlaceholder[] {\n  const byPath = new Map<string, boolean>();\n  const order: string[] = [];\n\n  for (const match of template.matchAll(PLACEHOLDER_PATTERN)) {\n    const [rawPath, rawDefault] = match[1].split(\"|\");\n    const path = rawPath.trim();\n\n    if (path.length === 0) {\n      continue;\n    }\n\n    const hasDefault = rawDefault !== undefined;\n\n    if (!byPath.has(path)) {\n      byPath.set(path, hasDefault);\n      order.push(path);\n    } else {\n      // A key only counts as defaulted when ALL of its occurrences default.\n      byPath.set(path, (byPath.get(path) ?? false) && hasDefault);\n    }\n  }\n\n  return order.map(path => ({ path, hasDefault: byPath.get(path) ?? false }));\n}\n\n/**\n * Run the deterministic (model-free) half of validation over a resolved prompt\n * body. Reports every `{{key}}` placeholder that has NO inline default and is\n * neither supplied in `provided` nor declared in `declared` (the prompt's\n * `meta.required` plus any caller-declared keys).\n *\n * Pure and synchronous — the only required half of `validate`; the LLM-judge\n * half is optional and layered on top.\n *\n * @param text - The resolved prompt body (placeholders may still be present).\n * @param provided - Placeholder keys the caller has supplied a value for.\n * @param declared - Placeholder keys declared as known/required (e.g. `meta.required`).\n */\nexport function findMissingPlaceholders(\n  text: string,\n  provided: ReadonlySet<string>,\n  declared: ReadonlySet<string>,\n): string[] {\n  const missing: string[] = [];\n\n  for (const { path, hasDefault } of collectPlaceholders(text)) {\n    if (hasDefault) {\n      continue;\n    }\n\n    if (provided.has(path) || declared.has(path)) {\n      continue;\n    }\n\n    missing.push(path);\n  }\n\n  return missing;\n}\n\n/**\n * A `meta.required` key absent from the template entirely — declared as\n * required but never referenced — is itself a defect worth surfacing. Returns\n * the declared keys that appear nowhere in the body.\n */\nexport function findUnreferencedRequired(\n  text: string,\n  required: readonly string[],\n): string[] {\n  const present = new Set(collectPlaceholders(text).map(p => p.path));\n\n  return required.filter(key => !present.has(key));\n}\n\n/**\n * Build the one-shot judge agent the optional LLM-as-judge pass runs. Mirrors\n * the legacy `prompt.ts` judge agent (strict-JSON instruction so the verdict\n * parses even without an output schema), so the two validate paths share one\n * judging contract.\n */\nfunction buildJudgeAgent(model: ModelContract): AgentContract<unknown> {\n  return agent({\n    name: \"prompt-quality-judge\",\n    model,\n    systemPrompt:\n      \"You are a strict prompt-quality grader. Respond with JSON only: \" +\n      '{ \"score\": <0..1>, \"passed\": <true|false>, \"reason\": \"<short explanation>\" }.',\n  });\n}\n\n/** Outcome of the optional LLM-as-judge pass over a resolved prompt body. */\nexport type JudgeOutcome = {\n  /**\n   * The judge score in `[0, 1]`, or `undefined` when the judge degraded\n   * (errored, returned no parseable verdict, or threw) — never a misleading\n   * `0` masquerading as a real verdict.\n   */\n  readonly score?: number;\n  /** Human-readable issues raised by the judge (its reason, or a degrade note). */\n  readonly issues: string[];\n};\n\n/**\n * Run the optional LLM-as-judge pass over a resolved prompt body, REUSING the\n * eval `judge` scorer (the same path `prompt().validate` uses) so there is no\n * second judging implementation.\n *\n * **Nova-safe by contract.** The judge NEVER throws here: the eval scorer\n * already degrades a broken judge to `score: 0` with a failure reason, and any\n * exception that still escapes (model wiring, agent construction) is caught.\n * Both degrade paths surface `score: undefined` plus an issue note — so a flaky\n * judge can never fail an otherwise-valid prompt.\n *\n * @param text - The resolved prompt body under evaluation.\n * @param model - The model that powers the judge agent.\n */\nexport async function judgePromptBody(\n  text: string,\n  model: ModelContract,\n): Promise<JudgeOutcome> {\n  try {\n    const judgeAgent = buildJudgeAgent(model);\n    const scorer = judge({ agent: judgeAgent, rubric: PROMPT_JUDGE_RUBRIC });\n\n    const verdict = await scorer({\n      case: { name: \"prompt-quality\", input: \"Grade the system prompt below.\" },\n      text,\n      // `result` is unused by the judge scorer's prompt builder; a minimal\n      // stand-in keeps the structural contract satisfied without a real run.\n      result: { text } as never,\n      output: undefined,\n    });\n\n    // The eval scorer signals a degraded judge with score 0 + a diagnostic\n    // reason (\"judge failed: …\" / \"judge returned no parseable verdict\"). Treat\n    // that as \"no usable score\" rather than a real 0 verdict.\n    const degraded =\n      verdict.score === 0 &&\n      typeof verdict.reason === \"string\" &&\n      /^judge (failed|returned no parseable)/.test(verdict.reason);\n\n    if (degraded) {\n      return {\n        issues: [`LLM-judge unavailable: ${verdict.reason}`],\n      };\n    }\n\n    return {\n      score: verdict.score,\n      issues: verdict.reason ? [verdict.reason] : [],\n    };\n  } catch (error) {\n    // Last-resort guard: never let a judge failure throw out of validate().\n    const message = error instanceof Error ? error.message : String(error);\n\n    return {\n      issues: [`LLM-judge unavailable: ${message}`],\n    };\n  }\n}\n\n/**\n * Non-cryptographic 53-bit string hash (cyrb53) — deterministic across runs\n * and platforms, with no `node:crypto` dependency (keeps the validate path\n * usable in any runtime). Mirrors the VCR request hash; collision-resistant\n * enough for a per-prompt judge-verdict keyspace. Returned as base-36.\n */\nfunction hashString(input: string): string {\n  let h1 = 0xdeadbeef;\n  let h2 = 0x41c6ce57;\n\n  for (let i = 0; i < input.length; i++) {\n    const ch = input.charCodeAt(i);\n\n    h1 = Math.imul(h1 ^ ch, 2654435761);\n    h2 = Math.imul(h2 ^ ch, 1597334677);\n  }\n\n  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);\n  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);\n  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);\n  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);\n\n  const combined = 4294967296 * (2097151 & h2) + (h1 >>> 0);\n\n  return combined.toString(36);\n}\n\n/**\n * Build the judge-verdict cache key for a resolved prompt body + judge model.\n * Combines the model's `provider:name` identity with a content hash of the\n * body, so the same prompt graded by the same judge hits the cache, while any\n * change to either misses it.\n */\nexport function judgeCacheKey(text: string, model: ModelContract): string {\n  return `prompts.judge.${model.provider}:${model.name}.${hashString(text)}`;\n}\n\n/**\n * Run the judge pass with an OPTIONAL memo cache in front. On a hit, the stored\n * {@link JudgeOutcome} is returned without a model call; on a miss, the live\n * judge runs and a USABLE verdict (one carrying a `score`) is written back.\n * Degraded outcomes (no score) are NOT cached — a transient judge failure must\n * never poison the memo. A `null`/absent cache degrades to a direct judge call.\n *\n * Cache I/O is itself fault-tolerant: a `get`/`set` that rejects is swallowed\n * so a flaky cache can never break (or fail) validation.\n *\n * @param text - The resolved prompt body under evaluation.\n * @param model - The judge model.\n * @param cache - Optional verdict memo (any `CacheDriver`-like get/set surface).\n */\nexport async function judgePromptBodyCached(\n  text: string,\n  model: ModelContract,\n  cache?: PromptJudgeCacheLike,\n): Promise<JudgeOutcome> {\n  if (!cache) {\n    return judgePromptBody(text, model);\n  }\n\n  const key = judgeCacheKey(text, model);\n\n  const cached = await readJudgeCache(cache, key);\n\n  if (cached) {\n    return cached;\n  }\n\n  const outcome = await judgePromptBody(text, model);\n\n  // Only memoize a usable verdict — never a degraded (scoreless) one.\n  if (outcome.score !== undefined) {\n    await writeJudgeCache(cache, key, outcome);\n  }\n\n  return outcome;\n}\n\n/** Read a cached verdict, swallowing any cache fault (treated as a miss). */\nasync function readJudgeCache(\n  cache: PromptJudgeCacheLike,\n  key: string,\n): Promise<JudgeOutcome | undefined> {\n  try {\n    const value = await cache.get<JudgeOutcome>(key);\n\n    return value ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Write a verdict, swallowing any cache fault (best-effort memo). */\nasync function writeJudgeCache(\n  cache: PromptJudgeCacheLike,\n  key: string,\n  outcome: JudgeOutcome,\n): Promise<void> {\n  try {\n    await cache.set(key, outcome);\n  } catch {\n    // Best-effort — a failed memo write never affects the validation result.\n  }\n}\n\n/**\n * Resolve the body + declared-required keys for a validation target that is a\n * `SystemPromptContract` (named or anonymous). The declared set is the\n * prompt's `meta.required` (when present).\n */\nexport function describeContractTarget(contract: SystemPromptContract): {\n  text: string;\n  required: readonly string[];\n} {\n  const meta = contract.meta();\n\n  return {\n    text: contract.resolve(),\n    required: meta?.required ?? [],\n  };\n}\n"],"mappings":"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"}

package/esm/rag/as-tool.mjs

@@ -0,0 +1,48 @@
+import { tool } from "../tool/tool.mjs";
+
+//#region ../@warlock.js/ai/src/rag/as-tool.ts
+/**
+* A minimal, schema-library-agnostic Standard Schema for `{ query: string }`.
+*
+* Built by hand (no `seal` / `zod` import) so `asTool()` stays dependency-
+* free and matches the framework's own `passthroughSchema` style — the
+* `~standard.validate` returns `{ issues }` on a bad shape so the tool
+* runtime surfaces a `SchemaValidationError` exactly like any other tool.
+*/
+function ragToolSchema() {
+	return { "~standard": {
+		version: 1,
+		vendor: "warlock-ai-rag",
+		validate: (value) => {
+			if (!value || typeof value !== "object" || typeof value.query !== "string") return { issues: [{ message: "rag tool input must be { query: string }" }] };
+			return { value: { query: value.query } };
+		}
+	} };
+}
+/**
+* Build a `ToolContract<{ query: string }, RetrieveResult>` that exposes a
+* rag's `retrieve()` to an agent's `tools: []` loop.
+*
+* `retrieve()` is a leaf operation (no inner executable report to nest),
+* so the plain `tool()` factory is the right shape — not `compositeAsTool`.
+* The resulting contract has `invoke`, so `isExecutableTool` returns false
+* and `normalizeAgentTools` passes it through untouched. On a thrown
+* retrieval error the runtime serializes `{ error }` back to the agent for
+* self-correction; the run does not abort.
+*
+* The tool name defaults to `retrieve_<name>` — namespaced by the rag's
+* name because the agent tool surface has no duplicate-name collision
+* guard (first match wins silently).
+*/
+function ragAsTool(name, retrieveFn, options = {}) {
+	return tool({
+		name: options.name ?? `retrieve_${name}`,
+		description: options.description ?? `Search the "${name}" knowledge base and return the most relevant cited passages for a query.`,
+		input: ragToolSchema(),
+		execute: async ({ query }) => retrieveFn(query, options.retrieve)
+	});
+}
+
+//#endregion
+export { ragAsTool };
+//# sourceMappingURL=as-tool.mjs.map

package/esm/rag/as-tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"as-tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/rag/as-tool.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { ToolContract } from \"../tool/tool\";\nimport { tool } from \"../tool/tool\";\nimport type { RetrieveOptions, RetrieveResult } from \"./contracts/citation.type\";\nimport type { RagAsToolOptions } from \"./contracts/rag-config.type\";\n\n/** The validated input shape of a rag tool. */\ntype RagToolInput = { query: string };\n\n/**\n * A minimal, schema-library-agnostic Standard Schema for `{ query: string }`.\n *\n * Built by hand (no `seal` / `zod` import) so `asTool()` stays dependency-\n * free and matches the framework's own `passthroughSchema` style — the\n * `~standard.validate` returns `{ issues }` on a bad shape so the tool\n * runtime surfaces a `SchemaValidationError` exactly like any other tool.\n */\nfunction ragToolSchema(): StandardSchemaV1<RagToolInput> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-ai-rag\",\n      validate: (value: unknown) => {\n        if (\n          !value ||\n          typeof value !== \"object\" ||\n          typeof (value as { query?: unknown }).query !== \"string\"\n        ) {\n          return {\n            issues: [{ message: \"rag tool input must be { query: string }\" }],\n          };\n        }\n\n        return { value: { query: (value as RagToolInput).query } };\n      },\n    },\n  };\n}\n\n/**\n * Build a `ToolContract<{ query: string }, RetrieveResult>` that exposes a\n * rag's `retrieve()` to an agent's `tools: []` loop.\n *\n * `retrieve()` is a leaf operation (no inner executable report to nest),\n * so the plain `tool()` factory is the right shape — not `compositeAsTool`.\n * The resulting contract has `invoke`, so `isExecutableTool` returns false\n * and `normalizeAgentTools` passes it through untouched. On a thrown\n * retrieval error the runtime serializes `{ error }` back to the agent for\n * self-correction; the run does not abort.\n *\n * The tool name defaults to `retrieve_<name>` — namespaced by the rag's\n * name because the agent tool surface has no duplicate-name collision\n * guard (first match wins silently).\n */\nexport function ragAsTool(\n  name: string,\n  retrieveFn: (query: string, options?: RetrieveOptions) => Promise<RetrieveResult>,\n  options: RagAsToolOptions = {},\n): ToolContract<RagToolInput, RetrieveResult> {\n  const toolName = options.name ?? `retrieve_${name}`;\n\n  return tool<RagToolInput, RetrieveResult>({\n    name: toolName,\n    description:\n      options.description ??\n      `Search the \"${name}\" knowledge base and return the most relevant cited passages for a query.`,\n    input: ragToolSchema(),\n    execute: async ({ query }) => retrieveFn(query, options.retrieve),\n  });\n}\n"],"mappings":";;;;;;;;;;;AAiBA,SAAS,gBAAgD;CACvD,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,UAAmB;GAC5B,IACE,CAAC,SACD,OAAO,UAAU,YACjB,OAAQ,MAA8B,UAAU,UAEhD,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,2CAA2C,CAAC,EAClE;GAGF,OAAO,EAAE,OAAO,EAAE,OAAQ,MAAuB,MAAM,EAAE;EAC3D;CACF,EACF;AACF;;;;;;;;;;;;;;;;AAiBA,SAAgB,UACd,MACA,YACA,UAA4B,CAAC,GACe;CAG5C,OAAO,KAAmC;EACxC,MAHe,QAAQ,QAAQ,YAAY;EAI3C,aACE,QAAQ,eACR,eAAe,KAAK;EACtB,OAAO,cAAc;EACrB,SAAS,OAAO,EAAE,YAAY,WAAW,OAAO,QAAQ,QAAQ;CAClE,CAAC;AACH"}

package/esm/rag/chunk/chunk.d.mts

@@ -0,0 +1,24 @@
+import { Chunk, ChunkOptions } from "../contracts/chunk-options.type.mjs";
+
+//#region ../@warlock.js/ai/src/rag/chunk/chunk.d.ts
+/**
+ * Split `text` into citation-bearing {@link Chunk}s according to
+ * {@link ChunkOptions}, dispatching on `options.type`:
+ *
+ * - `"recursive"` (default) — separator-aware greedy packing.
+ * - `"markdown"` — heading/section-aware, then recursive within sections.
+ * - `"sentence"` — packs whole sentences.
+ * - `"fixed"` — back-to-back character windows.
+ *
+ * All strategies are character-based (tokenizer-free) and record the exact
+ * `[start, end)` span of every chunk in the original text. Empty or
+ * whitespace-only input yields `[]`.
+ *
+ * @example
+ * const chunks = chunk(markdownDoc, { type: "markdown", size: 800, overlap: 120 });
+ * for (const c of chunks) console.log(c.index, c.span, c.text);
+ */
+declare function chunk(text: string, options?: ChunkOptions): Chunk[];
+//#endregion
+export { chunk };
+//# sourceMappingURL=chunk.d.mts.map

package/esm/rag/chunk/chunk.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/chunk.ts"],"mappings":";;;;;;;;;;AA6BsE;;;;;;;;;;iBAAtD,KAAA,CAAM,IAAA,UAAc,OAAA,GAAS,YAAA,GAAoB,KAAK"}

package/esm/rag/chunk/chunk.mjs

@@ -0,0 +1,44 @@
+import { fixedChunk } from "./fixed.mjs";
+import { DEFAULT_SEPARATORS, recursiveChunk } from "./recursive.mjs";
+import { markdownChunk } from "./markdown.mjs";
+import { sentenceChunk } from "./sentence.mjs";
+
+//#region ../@warlock.js/ai/src/rag/chunk/chunk.ts
+/** Default target chunk size in characters. */
+const DEFAULT_CHUNK_SIZE = 1e3;
+/** Default character overlap carried between adjacent chunks. */
+const DEFAULT_CHUNK_OVERLAP = 200;
+/**
+* Split `text` into citation-bearing {@link Chunk}s according to
+* {@link ChunkOptions}, dispatching on `options.type`:
+*
+* - `"recursive"` (default) — separator-aware greedy packing.
+* - `"markdown"` — heading/section-aware, then recursive within sections.
+* - `"sentence"` — packs whole sentences.
+* - `"fixed"` — back-to-back character windows.
+*
+* All strategies are character-based (tokenizer-free) and record the exact
+* `[start, end)` span of every chunk in the original text. Empty or
+* whitespace-only input yields `[]`.
+*
+* @example
+* const chunks = chunk(markdownDoc, { type: "markdown", size: 800, overlap: 120 });
+* for (const c of chunks) console.log(c.index, c.span, c.text);
+*/
+function chunk(text, options = {}) {
+	const type = options.type ?? "recursive";
+	const size = options.size ?? 1e3;
+	const overlap = options.overlap ?? 200;
+	const separators = options.separators ?? DEFAULT_SEPARATORS;
+	if (text.trim().length === 0) return [];
+	switch (type) {
+		case "markdown": return markdownChunk(text, size, overlap, separators);
+		case "sentence": return sentenceChunk(text, size, overlap);
+		case "fixed": return fixedChunk(text, size, overlap);
+		default: return recursiveChunk(text, size, overlap, separators);
+	}
+}
+
+//#endregion
+export { chunk };
+//# sourceMappingURL=chunk.mjs.map

package/esm/rag/chunk/chunk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/chunk.ts"],"sourcesContent":["import type { Chunk, ChunkOptions } from \"../contracts/chunk-options.type\";\nimport { fixedChunk } from \"./fixed\";\nimport { markdownChunk } from \"./markdown\";\nimport { DEFAULT_SEPARATORS, recursiveChunk } from \"./recursive\";\nimport { sentenceChunk } from \"./sentence\";\n\n/** Default target chunk size in characters. */\nexport const DEFAULT_CHUNK_SIZE = 1000;\n\n/** Default character overlap carried between adjacent chunks. */\nexport const DEFAULT_CHUNK_OVERLAP = 200;\n\n/**\n * Split `text` into citation-bearing {@link Chunk}s according to\n * {@link ChunkOptions}, dispatching on `options.type`:\n *\n * - `\"recursive\"` (default) — separator-aware greedy packing.\n * - `\"markdown\"` — heading/section-aware, then recursive within sections.\n * - `\"sentence\"` — packs whole sentences.\n * - `\"fixed\"` — back-to-back character windows.\n *\n * All strategies are character-based (tokenizer-free) and record the exact\n * `[start, end)` span of every chunk in the original text. Empty or\n * whitespace-only input yields `[]`.\n *\n * @example\n * const chunks = chunk(markdownDoc, { type: \"markdown\", size: 800, overlap: 120 });\n * for (const c of chunks) console.log(c.index, c.span, c.text);\n */\nexport function chunk(text: string, options: ChunkOptions = {}): Chunk[] {\n  const type = options.type ?? \"recursive\";\n  const size = options.size ?? DEFAULT_CHUNK_SIZE;\n  const overlap = options.overlap ?? DEFAULT_CHUNK_OVERLAP;\n  const separators = options.separators ?? DEFAULT_SEPARATORS;\n\n  // Empty or whitespace-only input yields no chunks — index() then writes\n  // nothing and never embeds an empty batch.\n  if (text.trim().length === 0) {\n    return [];\n  }\n\n  switch (type) {\n    case \"markdown\":\n      return markdownChunk(text, size, overlap, separators);\n\n    case \"sentence\":\n      return sentenceChunk(text, size, overlap);\n\n    case \"fixed\":\n      return fixedChunk(text, size, overlap);\n\n    case \"recursive\":\n    default:\n      return recursiveChunk(text, size, overlap, separators);\n  }\n}\n"],"mappings":";;;;;;;AAOA,MAAa,qBAAqB;;AAGlC,MAAa,wBAAwB;;;;;;;;;;;;;;;;;;AAmBrC,SAAgB,MAAM,MAAc,UAAwB,CAAC,GAAY;CACvE,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,OAAO,QAAQ;CACrB,MAAM,UAAU,QAAQ;CACxB,MAAM,aAAa,QAAQ,cAAc;CAIzC,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB,OAAO,CAAC;CAGV,QAAQ,MAAR;EACE,KAAK,YACH,OAAO,cAAc,MAAM,MAAM,SAAS,UAAU;EAEtD,KAAK,YACH,OAAO,cAAc,MAAM,MAAM,OAAO;EAE1C,KAAK,SACH,OAAO,WAAW,MAAM,MAAM,OAAO;EAGvC,SACE,OAAO,eAAe,MAAM,MAAM,SAAS,UAAU;CACzD;AACF"}

package/esm/rag/chunk/fixed.mjs

@@ -0,0 +1,32 @@
+//#region ../@warlock.js/ai/src/rag/chunk/fixed.ts
+/**
+* Fixed-window character splitter.
+*
+* The simplest strategy: slices the text into back-to-back windows of
+* `size` characters, stepping forward by `size - overlap` so adjacent
+* windows share `overlap` characters. Boundary-unaware — it will cut
+* mid-word — but deterministic and dep-free. Spans are exact by
+* construction.
+*/
+function fixedChunk(text, size, overlap) {
+	if (text.length === 0) return [];
+	const step = Math.max(1, size - overlap);
+	const chunks = [];
+	let index = 0;
+	for (let cursor = 0; cursor < text.length; cursor += step) {
+		const start = cursor;
+		const end = Math.min(cursor + size, text.length);
+		chunks.push({
+			text: text.slice(start, end),
+			index,
+			span: [start, end]
+		});
+		index += 1;
+		if (end >= text.length) break;
+	}
+	return chunks;
+}
+
+//#endregion
+export { fixedChunk };
+//# sourceMappingURL=fixed.mjs.map

package/esm/rag/chunk/fixed.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixed.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/fixed.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\n\n/**\n * Fixed-window character splitter.\n *\n * The simplest strategy: slices the text into back-to-back windows of\n * `size` characters, stepping forward by `size - overlap` so adjacent\n * windows share `overlap` characters. Boundary-unaware — it will cut\n * mid-word — but deterministic and dep-free. Spans are exact by\n * construction.\n */\nexport function fixedChunk(text: string, size: number, overlap: number): Chunk[] {\n  if (text.length === 0) {\n    return [];\n  }\n\n  const step = Math.max(1, size - overlap);\n  const chunks: Chunk[] = [];\n  let index = 0;\n\n  for (let cursor = 0; cursor < text.length; cursor += step) {\n    const start = cursor;\n    const end = Math.min(cursor + size, text.length);\n\n    chunks.push({ text: text.slice(start, end), index, span: [start, end] });\n    index += 1;\n\n    if (end >= text.length) {\n      break;\n    }\n  }\n\n  return chunks;\n}\n"],"mappings":";;;;;;;;;;AAWA,SAAgB,WAAW,MAAc,MAAc,SAA0B;CAC/E,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAGV,MAAM,OAAO,KAAK,IAAI,GAAG,OAAO,OAAO;CACvC,MAAM,SAAkB,CAAC;CACzB,IAAI,QAAQ;CAEZ,KAAK,IAAI,SAAS,GAAG,SAAS,KAAK,QAAQ,UAAU,MAAM;EACzD,MAAM,QAAQ;EACd,MAAM,MAAM,KAAK,IAAI,SAAS,MAAM,KAAK,MAAM;EAE/C,OAAO,KAAK;GAAE,MAAM,KAAK,MAAM,OAAO,GAAG;GAAG;GAAO,MAAM,CAAC,OAAO,GAAG;EAAE,CAAC;EACvE,SAAS;EAET,IAAI,OAAO,KAAK,QACd;CAEJ;CAEA,OAAO;AACT"}

package/esm/rag/chunk/markdown.mjs

@@ -0,0 +1,75 @@
+import { DEFAULT_SEPARATORS, recursiveChunk } from "./recursive.mjs";
+
+//#region ../@warlock.js/ai/src/rag/chunk/markdown.ts
+/** Matches an ATX Markdown heading line (`#` … `######`) at line start. */
+const HEADING_LINE = /^#{1,6}[ \t].*$/gm;
+/**
+* Markdown heading/section-aware splitter.
+*
+* Splits the document on ATX heading boundaries (`#`…`######`) first so a
+* section's heading stays glued to its body, then applies the recursive
+* character splitter WITHIN each section so any section larger than `size`
+* is broken down further. Sections at or under `size` are emitted whole.
+* Spans are exact relative to the original document.
+*/
+function markdownChunk(text, size, overlap, separators = DEFAULT_SEPARATORS) {
+	if (text.length === 0) return [];
+	const sections = splitSections(text);
+	const chunks = [];
+	let index = 0;
+	for (const section of sections) {
+		const body = text.slice(section.start, section.end);
+		if (body.trim().length === 0) continue;
+		if (body.length <= size) {
+			chunks.push({
+				text: body,
+				index,
+				span: [section.start, section.end]
+			});
+			index += 1;
+			continue;
+		}
+		const inner = recursiveChunk(body, size, overlap, separators);
+		for (const piece of inner) {
+			chunks.push({
+				text: piece.text,
+				index,
+				span: [section.start + piece.span[0], section.start + piece.span[1]]
+			});
+			index += 1;
+		}
+	}
+	return chunks;
+}
+/**
+* Carve the document into sections, each beginning at a heading line and
+* running until the next heading (the preamble before the first heading is
+* its own section). Spans cover the whole document with no gaps.
+*/
+function splitSections(text) {
+	const starts = [];
+	let match;
+	HEADING_LINE.lastIndex = 0;
+	while ((match = HEADING_LINE.exec(text)) !== null) starts.push(match.index);
+	if (starts.length === 0) return [{
+		start: 0,
+		end: text.length
+	}];
+	const sections = [];
+	if (starts[0] > 0) sections.push({
+		start: 0,
+		end: starts[0]
+	});
+	starts.forEach((start, position) => {
+		const end = position + 1 < starts.length ? starts[position + 1] : text.length;
+		sections.push({
+			start,
+			end
+		});
+	});
+	return sections;
+}
+
+//#endregion
+export { markdownChunk };
+//# sourceMappingURL=markdown.mjs.map

package/esm/rag/chunk/markdown.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/markdown.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\nimport { DEFAULT_SEPARATORS, recursiveChunk } from \"./recursive\";\n\n/** Matches an ATX Markdown heading line (`#` … `######`) at line start. */\nconst HEADING_LINE = /^#{1,6}[ \\t].*$/gm;\n\n/**\n * Markdown heading/section-aware splitter.\n *\n * Splits the document on ATX heading boundaries (`#`…`######`) first so a\n * section's heading stays glued to its body, then applies the recursive\n * character splitter WITHIN each section so any section larger than `size`\n * is broken down further. Sections at or under `size` are emitted whole.\n * Spans are exact relative to the original document.\n */\nexport function markdownChunk(\n  text: string,\n  size: number,\n  overlap: number,\n  separators: string[] = DEFAULT_SEPARATORS,\n): Chunk[] {\n  if (text.length === 0) {\n    return [];\n  }\n\n  const sections = splitSections(text);\n  const chunks: Chunk[] = [];\n  let index = 0;\n\n  for (const section of sections) {\n    const body = text.slice(section.start, section.end);\n\n    if (body.trim().length === 0) {\n      continue;\n    }\n\n    if (body.length <= size) {\n      chunks.push({\n        text: body,\n        index,\n        span: [section.start, section.end],\n      });\n      index += 1;\n\n      continue;\n    }\n\n    // Recurse within the section, then shift the relative spans to\n    // absolute document offsets and renumber sequentially.\n    const inner = recursiveChunk(body, size, overlap, separators);\n\n    for (const piece of inner) {\n      chunks.push({\n        text: piece.text,\n        index,\n        span: [section.start + piece.span[0], section.start + piece.span[1]],\n      });\n      index += 1;\n    }\n  }\n\n  return chunks;\n}\n\n/** A section's absolute `[start, end)` span (heading line + body until next heading). */\ntype SectionSpan = {\n  start: number;\n  end: number;\n};\n\n/**\n * Carve the document into sections, each beginning at a heading line and\n * running until the next heading (the preamble before the first heading is\n * its own section). Spans cover the whole document with no gaps.\n */\nfunction splitSections(text: string): SectionSpan[] {\n  const starts: number[] = [];\n  let match: RegExpExecArray | null;\n\n  HEADING_LINE.lastIndex = 0;\n\n  while ((match = HEADING_LINE.exec(text)) !== null) {\n    starts.push(match.index);\n  }\n\n  // No headings at all — the whole document is one section.\n  if (starts.length === 0) {\n    return [{ start: 0, end: text.length }];\n  }\n\n  const sections: SectionSpan[] = [];\n\n  // Preamble before the first heading, if any.\n  if (starts[0] > 0) {\n    sections.push({ start: 0, end: starts[0] });\n  }\n\n  starts.forEach((start, position) => {\n    const end = position + 1 < starts.length ? starts[position + 1] : text.length;\n\n    sections.push({ start, end });\n  });\n\n  return sections;\n}\n"],"mappings":";;;;AAIA,MAAM,eAAe;;;;;;;;;;AAWrB,SAAgB,cACd,MACA,MACA,SACA,aAAuB,oBACd;CACT,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAGV,MAAM,WAAW,cAAc,IAAI;CACnC,MAAM,SAAkB,CAAC;CACzB,IAAI,QAAQ;CAEZ,KAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,OAAO,KAAK,MAAM,QAAQ,OAAO,QAAQ,GAAG;EAElD,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB;EAGF,IAAI,KAAK,UAAU,MAAM;GACvB,OAAO,KAAK;IACV,MAAM;IACN;IACA,MAAM,CAAC,QAAQ,OAAO,QAAQ,GAAG;GACnC,CAAC;GACD,SAAS;GAET;EACF;EAIA,MAAM,QAAQ,eAAe,MAAM,MAAM,SAAS,UAAU;EAE5D,KAAK,MAAM,SAAS,OAAO;GACzB,OAAO,KAAK;IACV,MAAM,MAAM;IACZ;IACA,MAAM,CAAC,QAAQ,QAAQ,MAAM,KAAK,IAAI,QAAQ,QAAQ,MAAM,KAAK,EAAE;GACrE,CAAC;GACD,SAAS;EACX;CACF;CAEA,OAAO;AACT;;;;;;AAaA,SAAS,cAAc,MAA6B;CAClD,MAAM,SAAmB,CAAC;CAC1B,IAAI;CAEJ,aAAa,YAAY;CAEzB,QAAQ,QAAQ,aAAa,KAAK,IAAI,OAAO,MAC3C,OAAO,KAAK,MAAM,KAAK;CAIzB,IAAI,OAAO,WAAW,GACpB,OAAO,CAAC;EAAE,OAAO;EAAG,KAAK,KAAK;CAAO,CAAC;CAGxC,MAAM,WAA0B,CAAC;CAGjC,IAAI,OAAO,KAAK,GACd,SAAS,KAAK;EAAE,OAAO;EAAG,KAAK,OAAO;CAAG,CAAC;CAG5C,OAAO,SAAS,OAAO,aAAa;EAClC,MAAM,MAAM,WAAW,IAAI,OAAO,SAAS,OAAO,WAAW,KAAK,KAAK;EAEvE,SAAS,KAAK;GAAE;GAAO;EAAI,CAAC;CAC9B,CAAC;CAED,OAAO;AACT"}

package/esm/rag/chunk/recursive.mjs

@@ -0,0 +1,132 @@
+//#region ../@warlock.js/ai/src/rag/chunk/recursive.ts
+/** Default separators for the recursive splitter, tried largest-unit first. */
+const DEFAULT_SEPARATORS = [
+	"\n\n",
+	"\n",
+	". ",
+	" ",
+	""
+];
+/**
+* Recursive character splitter (the default strategy).
+*
+* Walks `separators` largest-unit-first: it splits the text on the first
+* separator, then packs the resulting pieces into chunks up to `size`
+* characters, carrying `overlap` characters forward between adjacent
+* chunks. Any single piece that is itself larger than `size` is split
+* again on the next-finer separator, recursing until a piece fits (the
+* `""` separator is the final char-by-char fallback).
+*
+* Every emitted chunk records its exact `[start, end)` character span in
+* the ORIGINAL text so a citation can point back precisely — spans are
+* tracked by index-of search as packed pieces are joined.
+*
+* Character-based and deliberately tokenizer-free.
+*/
+function recursiveChunk(text, size, overlap, separators = DEFAULT_SEPARATORS) {
+	return packPieces(text, anchorPieces(text, splitToPieces(text, size, separators)), size, overlap);
+}
+/**
+* Recursively split `text` into pieces no larger than `size` using the
+* ordered separator list. Pieces preserve original characters (no
+* trimming) so downstream span anchoring stays exact.
+*/
+function splitToPieces(text, size, separators) {
+	if (text.length <= size) return text.length > 0 ? [text] : [];
+	const [separator, ...rest] = separators;
+	if (separator === void 0 || separator === "") return hardSplit(text, size);
+	const segments = splitKeepingSeparator(text, separator);
+	const pieces = [];
+	for (const segment of segments) {
+		if (segment.length === 0) continue;
+		if (segment.length <= size) {
+			pieces.push(segment);
+			continue;
+		}
+		pieces.push(...splitToPieces(segment, size, rest));
+	}
+	return pieces;
+}
+/**
+* Split on `separator` but re-attach the separator to the end of each
+* preceding segment, so concatenating the segments reconstructs the
+* original text verbatim (keeping spans exact).
+*/
+function splitKeepingSeparator(text, separator) {
+	const raw = text.split(separator);
+	const segments = [];
+	raw.forEach((part, position) => {
+		const isLast = position === raw.length - 1;
+		segments.push(isLast ? part : part + separator);
+	});
+	return segments;
+}
+/** Hard char-window split for a unit larger than `size` with no usable separator. */
+function hardSplit(text, size) {
+	const pieces = [];
+	for (let cursor = 0; cursor < text.length; cursor += size) pieces.push(text.slice(cursor, cursor + size));
+	return pieces;
+}
+/**
+* Map each piece back to its absolute offset using a monotonic cursor —
+* pieces are emitted in document order, so the next occurrence at-or-after
+* the cursor is the correct one even for repeated substrings.
+*/
+function anchorPieces(text, pieces) {
+	const anchored = [];
+	let cursor = 0;
+	for (const piece of pieces) {
+		const start = text.indexOf(piece, cursor);
+		const resolvedStart = start === -1 ? cursor : start;
+		const end = resolvedStart + piece.length;
+		anchored.push({
+			text: piece,
+			start: resolvedStart,
+			end
+		});
+		cursor = end;
+	}
+	return anchored;
+}
+/**
+* Greedily pack anchored pieces into chunks up to `size` characters, then
+* carry `overlap` trailing characters from each emitted chunk into the
+* next so context is not lost at a boundary. Spans are taken straight
+* from the anchored pieces, so the overlap text is part of the next
+* chunk's span exactly.
+*/
+function packPieces(text, pieces, size, overlap) {
+	const chunks = [];
+	let bufferStart = -1;
+	let bufferEnd = -1;
+	let index = 0;
+	const flush = () => {
+		if (bufferStart === -1) return;
+		chunks.push({
+			text: text.slice(bufferStart, bufferEnd),
+			index,
+			span: [bufferStart, bufferEnd]
+		});
+		index += 1;
+	};
+	for (const piece of pieces) {
+		if (bufferStart === -1) {
+			bufferStart = piece.start;
+			bufferEnd = piece.end;
+			continue;
+		}
+		if (piece.end - bufferStart <= size) {
+			bufferEnd = piece.end;
+			continue;
+		}
+		flush();
+		bufferStart = overlap > 0 ? Math.max(bufferStart, piece.start - overlap) : piece.start;
+		bufferEnd = piece.end;
+	}
+	flush();
+	return chunks;
+}
+
+//#endregion
+export { DEFAULT_SEPARATORS, recursiveChunk };
+//# sourceMappingURL=recursive.mjs.map

package/esm/rag/chunk/recursive.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"recursive.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/chunk/recursive.ts"],"sourcesContent":["import type { Chunk } from \"../contracts/chunk-options.type\";\n\n/** Default separators for the recursive splitter, tried largest-unit first. */\nexport const DEFAULT_SEPARATORS: string[] = [\"\\n\\n\", \"\\n\", \". \", \" \", \"\"];\n\n/**\n * Recursive character splitter (the default strategy).\n *\n * Walks `separators` largest-unit-first: it splits the text on the first\n * separator, then packs the resulting pieces into chunks up to `size`\n * characters, carrying `overlap` characters forward between adjacent\n * chunks. Any single piece that is itself larger than `size` is split\n * again on the next-finer separator, recursing until a piece fits (the\n * `\"\"` separator is the final char-by-char fallback).\n *\n * Every emitted chunk records its exact `[start, end)` character span in\n * the ORIGINAL text so a citation can point back precisely — spans are\n * tracked by index-of search as packed pieces are joined.\n *\n * Character-based and deliberately tokenizer-free.\n */\nexport function recursiveChunk(\n  text: string,\n  size: number,\n  overlap: number,\n  separators: string[] = DEFAULT_SEPARATORS,\n): Chunk[] {\n  const pieces = splitToPieces(text, size, separators);\n\n  // Re-anchor each packed piece to its absolute offset in `text`. Pieces\n  // are non-overlapping and in document order, so a forward cursor finds\n  // each one's true start even when the same substring repeats.\n  const spans = anchorPieces(text, pieces);\n\n  return packPieces(text, spans, size, overlap);\n}\n\n/**\n * Recursively split `text` into pieces no larger than `size` using the\n * ordered separator list. Pieces preserve original characters (no\n * trimming) so downstream span anchoring stays exact.\n */\nfunction splitToPieces(text: string, size: number, separators: string[]): string[] {\n  if (text.length <= size) {\n    return text.length > 0 ? [text] : [];\n  }\n\n  const [separator, ...rest] = separators;\n\n  // Exhausted every separator (or hit the char fallback) — hard-split by\n  // size so an oversize unit never blows the budget.\n  if (separator === undefined || separator === \"\") {\n    return hardSplit(text, size);\n  }\n\n  const segments = splitKeepingSeparator(text, separator);\n  const pieces: string[] = [];\n\n  for (const segment of segments) {\n    if (segment.length === 0) {\n      continue;\n    }\n\n    if (segment.length <= size) {\n      pieces.push(segment);\n\n      continue;\n    }\n\n    pieces.push(...splitToPieces(segment, size, rest));\n  }\n\n  return pieces;\n}\n\n/**\n * Split on `separator` but re-attach the separator to the end of each\n * preceding segment, so concatenating the segments reconstructs the\n * original text verbatim (keeping spans exact).\n */\nfunction splitKeepingSeparator(text: string, separator: string): string[] {\n  const raw = text.split(separator);\n  const segments: string[] = [];\n\n  raw.forEach((part, position) => {\n    const isLast = position === raw.length - 1;\n\n    segments.push(isLast ? part : part + separator);\n  });\n\n  return segments;\n}\n\n/** Hard char-window split for a unit larger than `size` with no usable separator. */\nfunction hardSplit(text: string, size: number): string[] {\n  const pieces: string[] = [];\n\n  for (let cursor = 0; cursor < text.length; cursor += size) {\n    pieces.push(text.slice(cursor, cursor + size));\n  }\n\n  return pieces;\n}\n\n/** A piece plus its absolute `[start, end)` span in the original text. */\ntype AnchoredPiece = {\n  text: string;\n  start: number;\n  end: number;\n};\n\n/**\n * Map each piece back to its absolute offset using a monotonic cursor —\n * pieces are emitted in document order, so the next occurrence at-or-after\n * the cursor is the correct one even for repeated substrings.\n */\nfunction anchorPieces(text: string, pieces: string[]): AnchoredPiece[] {\n  const anchored: AnchoredPiece[] = [];\n  let cursor = 0;\n\n  for (const piece of pieces) {\n    const start = text.indexOf(piece, cursor);\n    const resolvedStart = start === -1 ? cursor : start;\n    const end = resolvedStart + piece.length;\n\n    anchored.push({ text: piece, start: resolvedStart, end });\n    cursor = end;\n  }\n\n  return anchored;\n}\n\n/**\n * Greedily pack anchored pieces into chunks up to `size` characters, then\n * carry `overlap` trailing characters from each emitted chunk into the\n * next so context is not lost at a boundary. Spans are taken straight\n * from the anchored pieces, so the overlap text is part of the next\n * chunk's span exactly.\n */\nfunction packPieces(\n  text: string,\n  pieces: AnchoredPiece[],\n  size: number,\n  overlap: number,\n): Chunk[] {\n  const chunks: Chunk[] = [];\n\n  let bufferStart = -1;\n  let bufferEnd = -1;\n  let index = 0;\n\n  const flush = (): void => {\n    if (bufferStart === -1) {\n      return;\n    }\n\n    chunks.push({\n      text: text.slice(bufferStart, bufferEnd),\n      index,\n      span: [bufferStart, bufferEnd],\n    });\n    index += 1;\n  };\n\n  for (const piece of pieces) {\n    if (bufferStart === -1) {\n      bufferStart = piece.start;\n      bufferEnd = piece.end;\n\n      continue;\n    }\n\n    const projected = piece.end - bufferStart;\n\n    if (projected <= size) {\n      bufferEnd = piece.end;\n\n      continue;\n    }\n\n    flush();\n\n    // Start the next buffer `overlap` chars before this piece (clamped to\n    // the previous chunk's start) so adjacent chunks share context.\n    const overlapStart = overlap > 0 ? Math.max(bufferStart, piece.start - overlap) : piece.start;\n\n    bufferStart = overlapStart;\n    bufferEnd = piece.end;\n  }\n\n  flush();\n\n  return chunks;\n}\n"],"mappings":";;AAGA,MAAa,qBAA+B;CAAC;CAAQ;CAAM;CAAM;CAAK;AAAE;;;;;;;;;;;;;;;;;AAkBxE,SAAgB,eACd,MACA,MACA,SACA,aAAuB,oBACd;CAQT,OAAO,WAAW,MAFJ,aAAa,MALZ,cAAc,MAAM,MAAM,UAKH,CAEV,GAAG,MAAM,OAAO;AAC9C;;;;;;AAOA,SAAS,cAAc,MAAc,MAAc,YAAgC;CACjF,IAAI,KAAK,UAAU,MACjB,OAAO,KAAK,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC;CAGrC,MAAM,CAAC,WAAW,GAAG,QAAQ;CAI7B,IAAI,cAAc,UAAa,cAAc,IAC3C,OAAO,UAAU,MAAM,IAAI;CAG7B,MAAM,WAAW,sBAAsB,MAAM,SAAS;CACtD,MAAM,SAAmB,CAAC;CAE1B,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,QAAQ,WAAW,GACrB;EAGF,IAAI,QAAQ,UAAU,MAAM;GAC1B,OAAO,KAAK,OAAO;GAEnB;EACF;EAEA,OAAO,KAAK,GAAG,cAAc,SAAS,MAAM,IAAI,CAAC;CACnD;CAEA,OAAO;AACT;;;;;;AAOA,SAAS,sBAAsB,MAAc,WAA6B;CACxE,MAAM,MAAM,KAAK,MAAM,SAAS;CAChC,MAAM,WAAqB,CAAC;CAE5B,IAAI,SAAS,MAAM,aAAa;EAC9B,MAAM,SAAS,aAAa,IAAI,SAAS;EAEzC,SAAS,KAAK,SAAS,OAAO,OAAO,SAAS;CAChD,CAAC;CAED,OAAO;AACT;;AAGA,SAAS,UAAU,MAAc,MAAwB;CACvD,MAAM,SAAmB,CAAC;CAE1B,KAAK,IAAI,SAAS,GAAG,SAAS,KAAK,QAAQ,UAAU,MACnD,OAAO,KAAK,KAAK,MAAM,QAAQ,SAAS,IAAI,CAAC;CAG/C,OAAO;AACT;;;;;;AAcA,SAAS,aAAa,MAAc,QAAmC;CACrE,MAAM,WAA4B,CAAC;CACnC,IAAI,SAAS;CAEb,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,QAAQ,KAAK,QAAQ,OAAO,MAAM;EACxC,MAAM,gBAAgB,UAAU,KAAK,SAAS;EAC9C,MAAM,MAAM,gBAAgB,MAAM;EAElC,SAAS,KAAK;GAAE,MAAM;GAAO,OAAO;GAAe;EAAI,CAAC;EACxD,SAAS;CACX;CAEA,OAAO;AACT;;;;;;;;AASA,SAAS,WACP,MACA,QACA,MACA,SACS;CACT,MAAM,SAAkB,CAAC;CAEzB,IAAI,cAAc;CAClB,IAAI,YAAY;CAChB,IAAI,QAAQ;CAEZ,MAAM,cAAoB;EACxB,IAAI,gBAAgB,IAClB;EAGF,OAAO,KAAK;GACV,MAAM,KAAK,MAAM,aAAa,SAAS;GACvC;GACA,MAAM,CAAC,aAAa,SAAS;EAC/B,CAAC;EACD,SAAS;CACX;CAEA,KAAK,MAAM,SAAS,QAAQ;EAC1B,IAAI,gBAAgB,IAAI;GACtB,cAAc,MAAM;GACpB,YAAY,MAAM;GAElB;EACF;EAIA,IAFkB,MAAM,MAAM,eAEb,MAAM;GACrB,YAAY,MAAM;GAElB;EACF;EAEA,MAAM;EAMN,cAFqB,UAAU,IAAI,KAAK,IAAI,aAAa,MAAM,QAAQ,OAAO,IAAI,MAAM;EAGxF,YAAY,MAAM;CACpB;CAEA,MAAM;CAEN,OAAO;AACT"}