@graphorin/memory 0.5.0

package/dist/context-engine/templates/composer.d.ts

@@ -0,0 +1,55 @@
+import { ContextLocalePack } from "../locale-packs/types.js";
+
+//#region src/context-engine/templates/composer.d.ts
+
+/**
+ * Layer 1 mode discriminator. `'full'` ships the full educational
+ * template (~250-350 tok); `'minimal'` ships the shortened version
+ * (~80-120 tok) for top-tier models.
+ *
+ * @stable
+ */
+type MemoryBaseMode = 'full' | 'minimal';
+/**
+ * Compose Layer 1 from the resolved locale pack.
+ *
+ * @stable
+ */
+declare function composeLayer1(pack: ContextLocalePack, mode: MemoryBaseMode): string;
+/**
+ * Render the optional Layer 2 (`agent_instructions`) wrapper.
+ * Returns the empty string when `instructions` is empty so the
+ * layer is dropped from the assembled prompt.
+ *
+ * @stable
+ */
+declare function composeLayer2(instructions: string | undefined): string;
+/**
+ * Render Layer 4 skills metadata cards. Each entry is a
+ * `<skill ... />` self-closing tag so the model sees only the
+ * progressive-disclosure metadata — the full SKILL.md body is
+ * loaded on-demand via `activate_skill(name)` per RB-04.
+ *
+ * @stable
+ */
+interface SkillMetadataCard {
+  readonly name: string;
+  readonly description: string;
+  readonly location?: string;
+  /** When `true`, the card is excluded from the assembled prompt. */
+  readonly disableModelInvocation?: boolean;
+}
+declare function composeLayer4Skills(cards: ReadonlyArray<SkillMetadataCard>): string;
+/**
+ * Render the inbound-sanitization preamble fragment. Emitted
+ * AFTER the cache breakpoint so the Layer 1-4 cache prefix is
+ * unaffected. Caller threads the fragment into the system content
+ * post-Layer 5; the fragment is returned as a string so the
+ * caller does not need to know the cache-breakpoint policy.
+ *
+ * @stable
+ */
+declare function composeInboundPreamble(pack: ContextLocalePack): string;
+//#endregion
+export { MemoryBaseMode, SkillMetadataCard, composeInboundPreamble, composeLayer1, composeLayer2, composeLayer4Skills };
+//# sourceMappingURL=composer.d.ts.map

package/dist/context-engine/templates/composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.d.ts","names":[],"sources":["../../../src/context-engine/templates/composer.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;KAkBY,cAAA;;;;;;iBAOI,aAAA,OAAoB,yBAAyB;;;;;;;;iBAW7C,aAAA;;;;;;;;;UAaC,iBAAA;;;;;;;iBAQD,mBAAA,QAA2B,cAAc;;;;;;;;;;iBAuBzC,sBAAA,OAA6B"}

package/dist/context-engine/templates/composer.js

@@ -0,0 +1,51 @@
+//#region src/context-engine/templates/composer.ts
+/**
+* Compose Layer 1 from the resolved locale pack.
+*
+* @stable
+*/
+function composeLayer1(pack, mode) {
+	return mode === "minimal" ? pack.baseTemplate.minimal : pack.baseTemplate.full;
+}
+/**
+* Render the optional Layer 2 (`agent_instructions`) wrapper.
+* Returns the empty string when `instructions` is empty so the
+* layer is dropped from the assembled prompt.
+*
+* @stable
+*/
+function composeLayer2(instructions) {
+	if (instructions === void 0 || instructions.trim().length === 0) return "";
+	return `<agent_instructions>\n${instructions}\n</agent_instructions>`;
+}
+function composeLayer4Skills(cards) {
+	const visible = cards.filter((c) => c.disableModelInvocation !== true);
+	if (visible.length === 0) return "";
+	const lines = ["<skills_available>"];
+	for (const card of visible) {
+		const description = ` description="${escapeXmlAttr(card.description)}"`;
+		const location = card.location !== void 0 ? ` location="${escapeXmlAttr(card.location)}"` : "";
+		lines.push(`  <skill name="${escapeXmlAttr(card.name)}"${description}${location} />`);
+	}
+	lines.push("</skills_available>");
+	return lines.join("\n");
+}
+/**
+* Render the inbound-sanitization preamble fragment. Emitted
+* AFTER the cache breakpoint so the Layer 1-4 cache prefix is
+* unaffected. Caller threads the fragment into the system content
+* post-Layer 5; the fragment is returned as a string so the
+* caller does not need to know the cache-breakpoint policy.
+*
+* @stable
+*/
+function composeInboundPreamble(pack) {
+	return pack.inboundSanitizationPreamble.text;
+}
+function escapeXmlAttr(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+//#endregion
+export { composeInboundPreamble, composeLayer1, composeLayer2, composeLayer4Skills };
+//# sourceMappingURL=composer.js.map

package/dist/context-engine/templates/composer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.js","names":[],"sources":["../../../src/context-engine/templates/composer.ts"],"sourcesContent":["/**\n * Layer 1 base-template composer. Resolves the locale pack, picks\n * the right base fragment based on `memoryBaseMode`, and exposes\n * the per-step inbound preamble as an additive Layer 5/6 fragment\n * (so the Layer 1-4 cache prefix stays bytes-equal across the run).\n *\n * @packageDocumentation\n */\n\nimport type { ContextLocalePack } from '../locale-packs/index.js';\n\n/**\n * Layer 1 mode discriminator. `'full'` ships the full educational\n * template (~250-350 tok); `'minimal'` ships the shortened version\n * (~80-120 tok) for top-tier models.\n *\n * @stable\n */\nexport type MemoryBaseMode = 'full' | 'minimal';\n\n/**\n * Compose Layer 1 from the resolved locale pack.\n *\n * @stable\n */\nexport function composeLayer1(pack: ContextLocalePack, mode: MemoryBaseMode): string {\n  return mode === 'minimal' ? pack.baseTemplate.minimal : pack.baseTemplate.full;\n}\n\n/**\n * Render the optional Layer 2 (`agent_instructions`) wrapper.\n * Returns the empty string when `instructions` is empty so the\n * layer is dropped from the assembled prompt.\n *\n * @stable\n */\nexport function composeLayer2(instructions: string | undefined): string {\n  if (instructions === undefined || instructions.trim().length === 0) return '';\n  return `<agent_instructions>\\n${instructions}\\n</agent_instructions>`;\n}\n\n/**\n * Render Layer 4 skills metadata cards. Each entry is a\n * `<skill ... />` self-closing tag so the model sees only the\n * progressive-disclosure metadata — the full SKILL.md body is\n * loaded on-demand via `activate_skill(name)` per RB-04.\n *\n * @stable\n */\nexport interface SkillMetadataCard {\n  readonly name: string;\n  readonly description: string;\n  readonly location?: string;\n  /** When `true`, the card is excluded from the assembled prompt. */\n  readonly disableModelInvocation?: boolean;\n}\n\nexport function composeLayer4Skills(cards: ReadonlyArray<SkillMetadataCard>): string {\n  const visible = cards.filter((c) => c.disableModelInvocation !== true);\n  if (visible.length === 0) return '';\n  const lines = ['<skills_available>'];\n  for (const card of visible) {\n    const description = ` description=\"${escapeXmlAttr(card.description)}\"`;\n    const location =\n      card.location !== undefined ? ` location=\"${escapeXmlAttr(card.location)}\"` : '';\n    lines.push(`  <skill name=\"${escapeXmlAttr(card.name)}\"${description}${location} />`);\n  }\n  lines.push('</skills_available>');\n  return lines.join('\\n');\n}\n\n/**\n * Render the inbound-sanitization preamble fragment. Emitted\n * AFTER the cache breakpoint so the Layer 1-4 cache prefix is\n * unaffected. Caller threads the fragment into the system content\n * post-Layer 5; the fragment is returned as a string so the\n * caller does not need to know the cache-breakpoint policy.\n *\n * @stable\n */\nexport function composeInboundPreamble(pack: ContextLocalePack): string {\n  return pack.inboundSanitizationPreamble.text;\n}\n\nfunction escapeXmlAttr(value: string): string {\n  return value\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n"],"mappings":";;;;;;AAyBA,SAAgB,cAAc,MAAyB,MAA8B;AACnF,QAAO,SAAS,YAAY,KAAK,aAAa,UAAU,KAAK,aAAa;;;;;;;;;AAU5E,SAAgB,cAAc,cAA0C;AACtE,KAAI,iBAAiB,UAAa,aAAa,MAAM,CAAC,WAAW,EAAG,QAAO;AAC3E,QAAO,yBAAyB,aAAa;;AAmB/C,SAAgB,oBAAoB,OAAiD;CACnF,MAAM,UAAU,MAAM,QAAQ,MAAM,EAAE,2BAA2B,KAAK;AACtE,KAAI,QAAQ,WAAW,EAAG,QAAO;CACjC,MAAM,QAAQ,CAAC,qBAAqB;AACpC,MAAK,MAAM,QAAQ,SAAS;EAC1B,MAAM,cAAc,iBAAiB,cAAc,KAAK,YAAY,CAAC;EACrE,MAAM,WACJ,KAAK,aAAa,SAAY,cAAc,cAAc,KAAK,SAAS,CAAC,KAAK;AAChF,QAAM,KAAK,kBAAkB,cAAc,KAAK,KAAK,CAAC,GAAG,cAAc,SAAS,KAAK;;AAEvF,OAAM,KAAK,sBAAsB;AACjC,QAAO,MAAM,KAAK,KAAK;;;;;;;;;;;AAYzB,SAAgB,uBAAuB,MAAiC;AACtE,QAAO,KAAK,4BAA4B;;AAG1C,SAAS,cAAc,OAAuB;AAC5C,QAAO,MACJ,QAAQ,MAAM,QAAQ,CACtB,QAAQ,MAAM,OAAO,CACrB,QAAQ,MAAM,OAAO,CACrB,QAAQ,MAAM,SAAS"}

package/dist/context-engine/token-budget.d.ts

@@ -0,0 +1,99 @@
+import { ContextTokenCounter } from "./token-counter.js";
+
+//#region src/context-engine/token-budget.d.ts
+
+/**
+ * Layer-id discriminator. Mirrors the documented Layer 1-6
+ * structure of the layered system prompt.
+ *
+ * @stable
+ */
+type LayerId = 'identity' | 'memoryMetadata' | 'activeRules' | 'workingBlocks' | 'activeSkills' | 'autoRecall';
+/**
+ * Default priority ladder. Higher priority means the layer is
+ * preserved longer when the budget is tight.
+ *
+ * @stable
+ */
+declare const DEFAULT_LAYER_PRIORITY: ReadonlyArray<LayerId>;
+/**
+ * Single layer candidate fed to {@link allocate}. The `text` field
+ * carries the rendered fragment; `cap` is the optional per-layer
+ * upper bound (in tokens); `priority` overrides the default ladder
+ * for advanced use cases.
+ *
+ * @stable
+ */
+interface LayerCandidate {
+  readonly id: LayerId;
+  readonly text: string;
+  readonly cap?: number;
+  readonly priority?: number;
+}
+/**
+ * Per-layer truncation mode used when the layer overflows its cap
+ * or the global budget. `truncate` is the default; `drop` removes
+ * the layer entirely when it would otherwise overflow.
+ *
+ * @stable
+ */
+type OverflowMode = 'truncate' | 'drop';
+/**
+ * Output of {@link allocate} — one entry per surviving layer in
+ * priority order, plus a `truncated` flag for observability.
+ *
+ * @stable
+ */
+interface LayerAllocation {
+  readonly id: LayerId;
+  readonly text: string;
+  readonly tokens: number;
+  readonly truncated: boolean;
+  readonly droppedTokens: number;
+}
+/**
+ * Result of an allocator run.
+ *
+ * @stable
+ */
+interface AllocationResult {
+  readonly layers: ReadonlyArray<LayerAllocation>;
+  readonly totalTokens: number;
+  readonly budgetTokens: number;
+  readonly overflowDropped: ReadonlyArray<LayerId>;
+}
+/**
+ * Truncate `text` to fit `maxTokens`, preserving the leading
+ * portion and replacing the trailing portion with the literal
+ * `[...truncated]` marker. The token estimate is computed via the
+ * supplied `counter`; truncation falls back to character-based
+ * trimming when the estimate is non-monotonic.
+ *
+ * Structure-aware (CE-16e): the cut never splits a tag, and block
+ * tags the cut leaves open are re-closed after the marker, so a
+ * capped layer of XML-ish markup (e.g. `<memory_blocks>`) stays
+ * well-formed in the assembled prompt. Plain strings are unaffected.
+ *
+ * @stable
+ */
+declare function truncateToTokens(text: string, maxTokens: number, counter: ContextTokenCounter): Promise<{
+  readonly text: string;
+  readonly tokens: number;
+  readonly truncated: boolean;
+}>;
+/**
+ * Run the allocator. Layers are sorted by priority ascending (the
+ * first layer is the highest priority); when the running total
+ * exceeds the budget, lower-priority layers are first capped at
+ * their per-layer `cap` (when set) and finally truncated to
+ * whatever fits.
+ *
+ * @stable
+ */
+declare function allocate(layers: ReadonlyArray<LayerCandidate>, budgetTokens: number, counter: ContextTokenCounter, options?: {
+  readonly priority?: ReadonlyArray<LayerId>;
+  readonly overflowMode?: OverflowMode;
+}): Promise<AllocationResult>;
+//#endregion
+export { AllocationResult, DEFAULT_LAYER_PRIORITY, LayerAllocation, LayerCandidate, LayerId, OverflowMode, allocate, truncateToTokens };
+//# sourceMappingURL=token-budget.d.ts.map

package/dist/context-engine/token-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.d.ts","names":[],"sources":["../../src/context-engine/token-budget.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;KAiCY,OAAA;;;;;;;cAcC,wBAAwB,cAAc;;;;;;;;;UAiBlC,cAAA;eACF;;;;;;;;;;;;KAaH,YAAA;;;;;;;UAQK,eAAA;eACF;;;;;;;;;;;UAYE,gBAAA;mBACE,cAAc;;;4BAGL,cAAc;;;;;;;;;;;;;;;;iBAmDpB,gBAAA,2CAGX,sBACR;;;;;;;;;;;;;;iBAuDmB,QAAA,SACZ,cAAc,gDAEb;sBAEa,cAAc;0BACV;IAEzB,QAAQ"}

package/dist/context-engine/token-budget.js

@@ -0,0 +1,211 @@
+//#region src/context-engine/token-budget.ts
+/**
+* Default priority ladder. Higher priority means the layer is
+* preserved longer when the budget is tight.
+*
+* @stable
+*/
+const DEFAULT_LAYER_PRIORITY = Object.freeze([
+	"identity",
+	"memoryMetadata",
+	"activeRules",
+	"workingBlocks",
+	"activeSkills",
+	"autoRecall"
+]);
+/**
+* Tags opened-but-not-closed in `text`, innermost-first. A heuristic
+* scanner sized for the engine's own XML-ish layer markup
+* (`<memory_blocks>`, `<memory_rules>`, ...) — self-closing tags are
+* skipped and an unmatched closer is ignored.
+*/
+function unclosedTags(text) {
+	const stack = [];
+	const re = /<(\/?)([A-Za-z_][\w.-]*)(?:\s[^<>]*)?(\/?)>/g;
+	let match = re.exec(text);
+	while (match !== null) {
+		const [, closing, name, selfClosing] = match;
+		if (selfClosing !== "/" && name !== void 0) if (closing === "/") {
+			const idx = stack.lastIndexOf(name);
+			if (idx !== -1) stack.splice(idx, 1);
+		} else stack.push(name);
+		match = re.exec(text);
+	}
+	return stack.reverse();
+}
+/**
+* Snap a prefix cut to a structure-safe point (CE-16e): never end
+* inside a partially-emitted tag (`...<memory_blo`).
+*/
+function snapCut(kept) {
+	const lastOpen = kept.lastIndexOf("<");
+	return lastOpen > kept.lastIndexOf(">") ? kept.slice(0, lastOpen) : kept;
+}
+/**
+* Truncate `text` to fit `maxTokens`, preserving the leading
+* portion and replacing the trailing portion with the literal
+* `[...truncated]` marker. The token estimate is computed via the
+* supplied `counter`; truncation falls back to character-based
+* trimming when the estimate is non-monotonic.
+*
+* Structure-aware (CE-16e): the cut never splits a tag, and block
+* tags the cut leaves open are re-closed after the marker, so a
+* capped layer of XML-ish markup (e.g. `<memory_blocks>`) stays
+* well-formed in the assembled prompt. Plain strings are unaffected.
+*
+* @stable
+*/
+async function truncateToTokens(text, maxTokens, counter) {
+	if (maxTokens <= 0) return {
+		text: "",
+		tokens: 0,
+		truncated: text.length > 0
+	};
+	const initial = await counter.countText(text);
+	if (initial <= maxTokens) return {
+		text,
+		tokens: initial,
+		truncated: false
+	};
+	const marker = "\n[...truncated]";
+	const markerTokens = await counter.countText(marker);
+	const targetTokens = Math.max(0, maxTokens - markerTokens);
+	if (targetTokens <= 0) return {
+		text: marker,
+		tokens: markerTokens,
+		truncated: true
+	};
+	let lo = 0;
+	let hi = text.length;
+	let bestCut = 0;
+	while (lo <= hi) {
+		const mid = lo + hi >>> 1;
+		const slice = text.slice(0, mid);
+		if (await counter.countText(slice) <= targetTokens) {
+			bestCut = mid;
+			lo = mid + 1;
+		} else hi = mid - 1;
+	}
+	let kept = snapCut(text.slice(0, bestCut));
+	let closers = unclosedTags(kept).map((t) => `</${t}>`).join("");
+	let truncated = `${kept}${marker}${closers.length > 0 ? `\n${closers}` : ""}`;
+	let tokens = await counter.countText(truncated);
+	while (tokens > maxTokens && kept.length > 0) {
+		kept = snapCut(kept.slice(0, kept.length - Math.ceil(kept.length * .1)));
+		closers = unclosedTags(kept).map((t) => `</${t}>`).join("");
+		truncated = `${kept}${marker}${closers.length > 0 ? `\n${closers}` : ""}`;
+		tokens = await counter.countText(truncated);
+	}
+	return {
+		text: truncated,
+		tokens,
+		truncated: true
+	};
+}
+/**
+* Run the allocator. Layers are sorted by priority ascending (the
+* first layer is the highest priority); when the running total
+* exceeds the budget, lower-priority layers are first capped at
+* their per-layer `cap` (when set) and finally truncated to
+* whatever fits.
+*
+* @stable
+*/
+async function allocate(layers, budgetTokens, counter, options = {}) {
+	const priorityOrder = options.priority ?? DEFAULT_LAYER_PRIORITY;
+	const overflowMode = options.overflowMode ?? "truncate";
+	const orderIndex = /* @__PURE__ */ new Map();
+	priorityOrder.forEach((id, idx) => {
+		orderIndex.set(id, idx);
+	});
+	const sorted = [...layers].sort((a, b) => {
+		return (a.priority ?? orderIndex.get(a.id) ?? 999) - (b.priority ?? orderIndex.get(b.id) ?? 999);
+	});
+	const capped = [];
+	for (const candidate of sorted) {
+		if (candidate.text.length === 0) {
+			capped.push({
+				candidate,
+				text: "",
+				tokens: 0,
+				truncated: false
+			});
+			continue;
+		}
+		if (candidate.cap !== void 0 && candidate.cap >= 0) {
+			const trimmed = await truncateToTokens(candidate.text, candidate.cap, counter);
+			capped.push({
+				candidate,
+				text: trimmed.text,
+				tokens: trimmed.tokens,
+				truncated: trimmed.truncated
+			});
+		} else {
+			const tokens = await counter.countText(candidate.text);
+			capped.push({
+				candidate,
+				text: candidate.text,
+				tokens,
+				truncated: false
+			});
+		}
+	}
+	const budget = Math.max(0, budgetTokens);
+	const layersOut = [];
+	const overflowDropped = [];
+	let runningTotal = 0;
+	for (const entry of capped) {
+		if (entry.text.length === 0) {
+			layersOut.push({
+				id: entry.candidate.id,
+				text: "",
+				tokens: 0,
+				truncated: false,
+				droppedTokens: 0
+			});
+			continue;
+		}
+		if (runningTotal + entry.tokens <= budget) {
+			runningTotal += entry.tokens;
+			layersOut.push({
+				id: entry.candidate.id,
+				text: entry.text,
+				tokens: entry.tokens,
+				truncated: entry.truncated,
+				droppedTokens: 0
+			});
+			continue;
+		}
+		const remaining = Math.max(0, budget - runningTotal);
+		if (overflowMode === "drop" || remaining === 0) {
+			overflowDropped.push(entry.candidate.id);
+			layersOut.push({
+				id: entry.candidate.id,
+				text: "",
+				tokens: 0,
+				truncated: false,
+				droppedTokens: entry.tokens
+			});
+			continue;
+		}
+		const trimmed = await truncateToTokens(entry.text, remaining, counter);
+		runningTotal += trimmed.tokens;
+		layersOut.push({
+			id: entry.candidate.id,
+			text: trimmed.text,
+			tokens: trimmed.tokens,
+			truncated: true,
+			droppedTokens: entry.tokens - trimmed.tokens
+		});
+	}
+	return Object.freeze({
+		layers: Object.freeze(layersOut),
+		totalTokens: runningTotal,
+		budgetTokens: budget,
+		overflowDropped: Object.freeze(overflowDropped)
+	});
+}
+
+//#endregion
+export { DEFAULT_LAYER_PRIORITY, allocate, truncateToTokens };
+//# sourceMappingURL=token-budget.js.map

package/dist/context-engine/token-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.js","names":["DEFAULT_LAYER_PRIORITY: ReadonlyArray<LayerId>","stack: string[]","capped: Array<{\n    readonly candidate: LayerCandidate;\n    text: string;\n    tokens: number;\n    truncated: boolean;\n  }>","layersOut: LayerAllocation[]","overflowDropped: LayerId[]"],"sources":["../../src/context-engine/token-budget.ts"],"sourcesContent":["/**\n * Priority-ordered token-budget allocator. The allocator runs over the six\n * layers of the {@link ContextEngine}'s system prompt and trims the\n * lowest-priority layers first when the combined cost exceeds the configured\n * budget.\n *\n * This **truncation priority** is deliberately separate from the **emission\n * order** (CE-9): the engine emits the surviving layers in a stable order\n * (identity → rules → blocks → skills → [KV-cache breakpoint] → metadata →\n * auto-recall) regardless of which were trimmed, so the cacheable prefix stays\n * byte-stable across turns. This ladder governs only *what gets dropped first*.\n *\n * Priority (configurable), highest preserved → first truncated:\n *\n * 1. **identity** — Layer 1 (`graphorin_memory_base` + agent\n *    instructions). Always preserved; truncated last.\n * 2. **memoryMetadata** — Layer 5. Small (~100-300 tokens).\n * 3. **activeRules** — Layer 4 procedural rules.\n * 4. **workingBlocks** — Layer 3.\n * 5. **activeSkills** — Layer 4 skills metadata cards.\n * 6. **autoRecall** — Layer 6. Lowest priority; truncated first.\n *\n * @packageDocumentation\n */\n\nimport type { ContextTokenCounter } from './token-counter.js';\n\n/**\n * Layer-id discriminator. Mirrors the documented Layer 1-6\n * structure of the layered system prompt.\n *\n * @stable\n */\nexport type LayerId =\n  | 'identity'\n  | 'memoryMetadata'\n  | 'activeRules'\n  | 'workingBlocks'\n  | 'activeSkills'\n  | 'autoRecall';\n\n/**\n * Default priority ladder. Higher priority means the layer is\n * preserved longer when the budget is tight.\n *\n * @stable\n */\nexport const DEFAULT_LAYER_PRIORITY: ReadonlyArray<LayerId> = Object.freeze([\n  'identity',\n  'memoryMetadata',\n  'activeRules',\n  'workingBlocks',\n  'activeSkills',\n  'autoRecall',\n]);\n\n/**\n * Single layer candidate fed to {@link allocate}. The `text` field\n * carries the rendered fragment; `cap` is the optional per-layer\n * upper bound (in tokens); `priority` overrides the default ladder\n * for advanced use cases.\n *\n * @stable\n */\nexport interface LayerCandidate {\n  readonly id: LayerId;\n  readonly text: string;\n  readonly cap?: number;\n  readonly priority?: number;\n}\n\n/**\n * Per-layer truncation mode used when the layer overflows its cap\n * or the global budget. `truncate` is the default; `drop` removes\n * the layer entirely when it would otherwise overflow.\n *\n * @stable\n */\nexport type OverflowMode = 'truncate' | 'drop';\n\n/**\n * Output of {@link allocate} — one entry per surviving layer in\n * priority order, plus a `truncated` flag for observability.\n *\n * @stable\n */\nexport interface LayerAllocation {\n  readonly id: LayerId;\n  readonly text: string;\n  readonly tokens: number;\n  readonly truncated: boolean;\n  readonly droppedTokens: number;\n}\n\n/**\n * Result of an allocator run.\n *\n * @stable\n */\nexport interface AllocationResult {\n  readonly layers: ReadonlyArray<LayerAllocation>;\n  readonly totalTokens: number;\n  readonly budgetTokens: number;\n  readonly overflowDropped: ReadonlyArray<LayerId>;\n}\n\n/**\n * Tags opened-but-not-closed in `text`, innermost-first. A heuristic\n * scanner sized for the engine's own XML-ish layer markup\n * (`<memory_blocks>`, `<memory_rules>`, ...) — self-closing tags are\n * skipped and an unmatched closer is ignored.\n */\nfunction unclosedTags(text: string): string[] {\n  const stack: string[] = [];\n  const re = /<(\\/?)([A-Za-z_][\\w.-]*)(?:\\s[^<>]*)?(\\/?)>/g;\n  let match = re.exec(text);\n  while (match !== null) {\n    const [, closing, name, selfClosing] = match;\n    if (selfClosing !== '/' && name !== undefined) {\n      if (closing === '/') {\n        const idx = stack.lastIndexOf(name);\n        if (idx !== -1) stack.splice(idx, 1);\n      } else {\n        stack.push(name);\n      }\n    }\n    match = re.exec(text);\n  }\n  return stack.reverse();\n}\n\n/**\n * Snap a prefix cut to a structure-safe point (CE-16e): never end\n * inside a partially-emitted tag (`...<memory_blo`).\n */\nfunction snapCut(kept: string): string {\n  const lastOpen = kept.lastIndexOf('<');\n  return lastOpen > kept.lastIndexOf('>') ? kept.slice(0, lastOpen) : kept;\n}\n\n/**\n * Truncate `text` to fit `maxTokens`, preserving the leading\n * portion and replacing the trailing portion with the literal\n * `[...truncated]` marker. The token estimate is computed via the\n * supplied `counter`; truncation falls back to character-based\n * trimming when the estimate is non-monotonic.\n *\n * Structure-aware (CE-16e): the cut never splits a tag, and block\n * tags the cut leaves open are re-closed after the marker, so a\n * capped layer of XML-ish markup (e.g. `<memory_blocks>`) stays\n * well-formed in the assembled prompt. Plain strings are unaffected.\n *\n * @stable\n */\nexport async function truncateToTokens(\n  text: string,\n  maxTokens: number,\n  counter: ContextTokenCounter,\n): Promise<{ readonly text: string; readonly tokens: number; readonly truncated: boolean }> {\n  if (maxTokens <= 0) return { text: '', tokens: 0, truncated: text.length > 0 };\n  const initial = await counter.countText(text);\n  if (initial <= maxTokens) return { text, tokens: initial, truncated: false };\n  const marker = '\\n[...truncated]';\n  const markerTokens = await counter.countText(marker);\n  const targetTokens = Math.max(0, maxTokens - markerTokens);\n  if (targetTokens <= 0) return { text: marker, tokens: markerTokens, truncated: true };\n  // Approximate the cut point via the inverse of the heuristic\n  // chars-per-token ratio. Falls back to repeated halving when the\n  // ratio is non-monotonic for the supplied counter.\n  let lo = 0;\n  let hi = text.length;\n  let bestCut = 0;\n  while (lo <= hi) {\n    const mid = (lo + hi) >>> 1;\n    const slice = text.slice(0, mid);\n    const tokens = await counter.countText(slice);\n    if (tokens <= targetTokens) {\n      bestCut = mid;\n      lo = mid + 1;\n    } else {\n      hi = mid - 1;\n    }\n  }\n  let kept = snapCut(text.slice(0, bestCut));\n  let closers = unclosedTags(kept)\n    .map((t) => `</${t}>`)\n    .join('');\n  let truncated = `${kept}${marker}${closers.length > 0 ? `\\n${closers}` : ''}`;\n  let tokens = await counter.countText(truncated);\n  // Re-closing may push past the cap — shave the kept body until the\n  // whole thing (body + marker + closers) fits. Terminates: `kept`\n  // shrinks by ≥1 char per pass, and the empty body fits by the\n  // `targetTokens > 0` guard above.\n  while (tokens > maxTokens && kept.length > 0) {\n    kept = snapCut(kept.slice(0, kept.length - Math.ceil(kept.length * 0.1)));\n    closers = unclosedTags(kept)\n      .map((t) => `</${t}>`)\n      .join('');\n    truncated = `${kept}${marker}${closers.length > 0 ? `\\n${closers}` : ''}`;\n    tokens = await counter.countText(truncated);\n  }\n  return { text: truncated, tokens, truncated: true };\n}\n\n/**\n * Run the allocator. Layers are sorted by priority ascending (the\n * first layer is the highest priority); when the running total\n * exceeds the budget, lower-priority layers are first capped at\n * their per-layer `cap` (when set) and finally truncated to\n * whatever fits.\n *\n * @stable\n */\nexport async function allocate(\n  layers: ReadonlyArray<LayerCandidate>,\n  budgetTokens: number,\n  counter: ContextTokenCounter,\n  options: {\n    readonly priority?: ReadonlyArray<LayerId>;\n    readonly overflowMode?: OverflowMode;\n  } = {},\n): Promise<AllocationResult> {\n  const priorityOrder = options.priority ?? DEFAULT_LAYER_PRIORITY;\n  const overflowMode = options.overflowMode ?? 'truncate';\n  const orderIndex = new Map<LayerId, number>();\n  priorityOrder.forEach((id, idx) => {\n    orderIndex.set(id, idx);\n  });\n  const sorted = [...layers].sort((a, b) => {\n    const aPriority = a.priority ?? orderIndex.get(a.id) ?? 999;\n    const bPriority = b.priority ?? orderIndex.get(b.id) ?? 999;\n    return aPriority - bPriority;\n  });\n\n  // First pass: enforce per-layer caps (regardless of total budget).\n  const capped: Array<{\n    readonly candidate: LayerCandidate;\n    text: string;\n    tokens: number;\n    truncated: boolean;\n  }> = [];\n  for (const candidate of sorted) {\n    if (candidate.text.length === 0) {\n      capped.push({ candidate, text: '', tokens: 0, truncated: false });\n      continue;\n    }\n    if (candidate.cap !== undefined && candidate.cap >= 0) {\n      const trimmed = await truncateToTokens(candidate.text, candidate.cap, counter);\n      capped.push({\n        candidate,\n        text: trimmed.text,\n        tokens: trimmed.tokens,\n        truncated: trimmed.truncated,\n      });\n    } else {\n      const tokens = await counter.countText(candidate.text);\n      capped.push({ candidate, text: candidate.text, tokens, truncated: false });\n    }\n  }\n\n  // Second pass: enforce the global budget. Walk the layers in\n  // priority order, accumulating tokens; when the running total\n  // exceeds the budget, the rest are dropped or truncated to fit.\n  const budget = Math.max(0, budgetTokens);\n  const layersOut: LayerAllocation[] = [];\n  const overflowDropped: LayerId[] = [];\n  let runningTotal = 0;\n  for (const entry of capped) {\n    if (entry.text.length === 0) {\n      layersOut.push({\n        id: entry.candidate.id,\n        text: '',\n        tokens: 0,\n        truncated: false,\n        droppedTokens: 0,\n      });\n      continue;\n    }\n    if (runningTotal + entry.tokens <= budget) {\n      runningTotal += entry.tokens;\n      layersOut.push({\n        id: entry.candidate.id,\n        text: entry.text,\n        tokens: entry.tokens,\n        truncated: entry.truncated,\n        droppedTokens: 0,\n      });\n      continue;\n    }\n    const remaining = Math.max(0, budget - runningTotal);\n    if (overflowMode === 'drop' || remaining === 0) {\n      overflowDropped.push(entry.candidate.id);\n      layersOut.push({\n        id: entry.candidate.id,\n        text: '',\n        tokens: 0,\n        truncated: false,\n        droppedTokens: entry.tokens,\n      });\n      continue;\n    }\n    const trimmed = await truncateToTokens(entry.text, remaining, counter);\n    runningTotal += trimmed.tokens;\n    layersOut.push({\n      id: entry.candidate.id,\n      text: trimmed.text,\n      tokens: trimmed.tokens,\n      truncated: true,\n      droppedTokens: entry.tokens - trimmed.tokens,\n    });\n  }\n\n  return Object.freeze({\n    layers: Object.freeze(layersOut),\n    totalTokens: runningTotal,\n    budgetTokens: budget,\n    overflowDropped: Object.freeze(overflowDropped),\n  });\n}\n"],"mappings":"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"}

package/dist/context-engine/token-counter.d.ts

@@ -0,0 +1,54 @@
+import { Message, TokenCounter } from "@graphorin/core";
+
+//#region src/context-engine/token-counter.d.ts
+
+/**
+ * Pluggable text-token counter used inside the ContextEngine. The
+ * surface is narrower than {@link TokenCounter} because the engine
+ * never assembles a message list during the budget-allocation
+ * phase — it operates on rendered text fragments.
+ *
+ * @stable
+ */
+interface ContextTokenCounter {
+  readonly id: string;
+  countText(text: string): Promise<number>;
+}
+/**
+ * Built-in heuristic counter — chars/4 for Latin-ish text plus one
+ * token per dense-script (CJK/kana/hangul) character (CE-13). Stable
+ * default when the operator does not pass a real {@link TokenCounter}.
+ *
+ * @stable
+ */
+declare const HEURISTIC_TOKEN_COUNTER: ContextTokenCounter;
+/**
+ * Wrap a real {@link TokenCounter} into the narrower
+ * {@link ContextTokenCounter} surface. Calls `countText(text)`
+ * directly for max precision; falls back to the synthetic
+ * single-message bridge when only `count(messages)` is supported.
+ *
+ * @stable
+ */
+declare function adaptTokenCounter(counter: TokenCounter): ContextTokenCounter;
+/**
+ * Count tokens across a message list using a {@link TokenCounter}
+ * (or the heuristic fallback). Used by the trigger-evaluation hot
+ * path of the auto-compaction subsystem (RB-46) at the top of every
+ * step.
+ *
+ * @stable
+ */
+declare function countMessageTokens(messages: ReadonlyArray<Message>, counter: TokenCounter | ContextTokenCounter): Promise<number>;
+/**
+ * Render a `Message` into a single textual approximation suitable
+ * for token counting. Multimodal parts other than `'text'` /
+ * `'reasoning'` contribute a constant approximation so the counter
+ * does not silently under-count.
+ *
+ * @stable
+ */
+declare function renderMessageText(message: Message): string;
+//#endregion
+export { ContextTokenCounter, HEURISTIC_TOKEN_COUNTER, adaptTokenCounter, countMessageTokens, renderMessageText };
+//# sourceMappingURL=token-counter.d.ts.map

package/dist/context-engine/token-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.d.ts","names":[],"sources":["../../src/context-engine/token-counter.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;UA0BiB,mBAAA;;2BAEU;;;;;;;;;cAyBd,yBAAyB;;;;;;;;;iBAkBtB,iBAAA,UAA2B,eAAe;;;;;;;;;iBAkBpC,kBAAA,WACV,cAAc,mBACf,eAAe,sBACvB;;;;;;;;;iBAmBa,iBAAA,UAA2B"}

package/dist/context-engine/token-counter.js

@@ -0,0 +1,81 @@
+//#region src/context-engine/token-counter.ts
+/**
+* Script-aware heuristic (CE-13). The flat chars/4 rule undercounts
+* non-Latin scripts ~4x — real tokenizers emit roughly one token per
+* CJK character (and per kana / hangul syllable), so a 200k-window
+* threshold expressed in "heuristic tokens" let CJK conversations blow
+* past the provider limit before compaction ever fired. Characters
+* outside the Latin-ish range count at one token each; Latin text keeps
+* the classic chars/4. Still a heuristic — wire a real `TokenCounter`
+* (e.g. the provider package's JsTiktokenCounter) for production
+* accuracy.
+*/
+const DENSE_SCRIPT_RE = /[ᄀ-ᇿ⺀-〿぀-ヿ㄰-㆏ㇰ-䶿一-鿿ꥠ-꥿가-퟿豈-﫿＀-￯]/g;
+/**
+* Built-in heuristic counter — chars/4 for Latin-ish text plus one
+* token per dense-script (CJK/kana/hangul) character (CE-13). Stable
+* default when the operator does not pass a real {@link TokenCounter}.
+*
+* @stable
+*/
+const HEURISTIC_TOKEN_COUNTER = Object.freeze({
+	id: "graphorin/heuristic@chars-per-4+dense-script",
+	async countText(text) {
+		if (typeof text !== "string" || text.length === 0) return 0;
+		const dense = text.match(DENSE_SCRIPT_RE)?.length ?? 0;
+		const latin = text.length - dense;
+		return Math.ceil(latin / 4) + dense;
+	}
+});
+/**
+* Wrap a real {@link TokenCounter} into the narrower
+* {@link ContextTokenCounter} surface. Calls `countText(text)`
+* directly for max precision; falls back to the synthetic
+* single-message bridge when only `count(messages)` is supported.
+*
+* @stable
+*/
+function adaptTokenCounter(counter) {
+	return Object.freeze({
+		id: counter.id,
+		async countText(text) {
+			if (typeof text !== "string" || text.length === 0) return 0;
+			return counter.countText(text);
+		}
+	});
+}
+/**
+* Count tokens across a message list using a {@link TokenCounter}
+* (or the heuristic fallback). Used by the trigger-evaluation hot
+* path of the auto-compaction subsystem (RB-46) at the top of every
+* step.
+*
+* @stable
+*/
+async function countMessageTokens(messages, counter) {
+	if ("count" in counter && typeof counter.count === "function") return counter.count(messages);
+	let total = 0;
+	for (const message of messages) total += await counter.countText(renderMessageText(message));
+	return total;
+}
+/**
+* Render a `Message` into a single textual approximation suitable
+* for token counting. Multimodal parts other than `'text'` /
+* `'reasoning'` contribute a constant approximation so the counter
+* does not silently under-count.
+*
+* @stable
+*/
+function renderMessageText(message) {
+	if (message.role === "system") return message.content;
+	const content = message.content;
+	if (typeof content === "string") return content;
+	let out = "";
+	for (const part of content) if (part.type === "text" || part.type === "reasoning") out += `${part.text}\n`;
+	else out += "[non-text-part]\n";
+	return out;
+}
+
+//#endregion
+export { HEURISTIC_TOKEN_COUNTER, adaptTokenCounter, countMessageTokens, renderMessageText };
+//# sourceMappingURL=token-counter.js.map

package/dist/context-engine/token-counter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.js","names":["HEURISTIC_TOKEN_COUNTER: ContextTokenCounter"],"sources":["../../src/context-engine/token-counter.ts"],"sourcesContent":["/**\n * Token-counting helpers used by the {@link ContextEngine}. The\n * production path accepts a {@link TokenCounter} from\n * `@graphorin/core` (the default `JsTiktokenCounter` lives in\n * `@graphorin/provider`); the fallback path is a deterministic\n * heuristic that keeps unit tests dependency-free.\n *\n * The fallback counts ~1 token per 4 characters — close enough for\n * budgeting decisions, intentionally less precise than a real BPE\n * tokenizer. Production deployments wire a real\n * {@link TokenCounter} through `createMemory({ contextEngine: {\n * tokenCounter: ... } })`.\n *\n * @packageDocumentation\n */\n\nimport type { Message, TokenCounter } from '@graphorin/core';\n\n/**\n * Pluggable text-token counter used inside the ContextEngine. The\n * surface is narrower than {@link TokenCounter} because the engine\n * never assembles a message list during the budget-allocation\n * phase — it operates on rendered text fragments.\n *\n * @stable\n */\nexport interface ContextTokenCounter {\n  readonly id: string;\n  countText(text: string): Promise<number>;\n}\n\n/**\n * Script-aware heuristic (CE-13). The flat chars/4 rule undercounts\n * non-Latin scripts ~4x — real tokenizers emit roughly one token per\n * CJK character (and per kana / hangul syllable), so a 200k-window\n * threshold expressed in \"heuristic tokens\" let CJK conversations blow\n * past the provider limit before compaction ever fired. Characters\n * outside the Latin-ish range count at one token each; Latin text keeps\n * the classic chars/4. Still a heuristic — wire a real `TokenCounter`\n * (e.g. the provider package's JsTiktokenCounter) for production\n * accuracy.\n */\nconst DENSE_SCRIPT_RE =\n  // CJK unified + extensions, kana, hangul, CJK punctuation, full-width forms.\n  /[ᄀ-ᇿ⺀-〿぀-ヿ㄰-㆏ㇰ-䶿一-鿿ꥠ-꥿가-퟿豈-﫿＀-￯]/g;\n\n/**\n * Built-in heuristic counter — chars/4 for Latin-ish text plus one\n * token per dense-script (CJK/kana/hangul) character (CE-13). Stable\n * default when the operator does not pass a real {@link TokenCounter}.\n *\n * @stable\n */\nexport const HEURISTIC_TOKEN_COUNTER: ContextTokenCounter = Object.freeze({\n  id: 'graphorin/heuristic@chars-per-4+dense-script',\n  async countText(text: string): Promise<number> {\n    if (typeof text !== 'string' || text.length === 0) return 0;\n    const dense = text.match(DENSE_SCRIPT_RE)?.length ?? 0;\n    const latin = text.length - dense;\n    return Math.ceil(latin / 4) + dense;\n  },\n});\n\n/**\n * Wrap a real {@link TokenCounter} into the narrower\n * {@link ContextTokenCounter} surface. Calls `countText(text)`\n * directly for max precision; falls back to the synthetic\n * single-message bridge when only `count(messages)` is supported.\n *\n * @stable\n */\nexport function adaptTokenCounter(counter: TokenCounter): ContextTokenCounter {\n  return Object.freeze({\n    id: counter.id,\n    async countText(text: string): Promise<number> {\n      if (typeof text !== 'string' || text.length === 0) return 0;\n      return counter.countText(text);\n    },\n  });\n}\n\n/**\n * Count tokens across a message list using a {@link TokenCounter}\n * (or the heuristic fallback). Used by the trigger-evaluation hot\n * path of the auto-compaction subsystem (RB-46) at the top of every\n * step.\n *\n * @stable\n */\nexport async function countMessageTokens(\n  messages: ReadonlyArray<Message>,\n  counter: TokenCounter | ContextTokenCounter,\n): Promise<number> {\n  if ('count' in counter && typeof (counter as TokenCounter).count === 'function') {\n    return (counter as TokenCounter).count(messages);\n  }\n  let total = 0;\n  for (const message of messages) {\n    total += await counter.countText(renderMessageText(message));\n  }\n  return total;\n}\n\n/**\n * Render a `Message` into a single textual approximation suitable\n * for token counting. Multimodal parts other than `'text'` /\n * `'reasoning'` contribute a constant approximation so the counter\n * does not silently under-count.\n *\n * @stable\n */\nexport function renderMessageText(message: Message): string {\n  if (message.role === 'system') return message.content;\n  const content = message.content;\n  if (typeof content === 'string') return content;\n  let out = '';\n  for (const part of content) {\n    if (part.type === 'text' || part.type === 'reasoning') {\n      out += `${part.text}\\n`;\n    } else {\n      // Approximate non-text parts (image / audio / file) as a small\n      // fixed cost so the counter does not silently under-count.\n      out += '[non-text-part]\\n';\n    }\n  }\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;AA0CA,MAAM,kBAEJ;;;;;;;;AASF,MAAaA,0BAA+C,OAAO,OAAO;CACxE,IAAI;CACJ,MAAM,UAAU,MAA+B;AAC7C,MAAI,OAAO,SAAS,YAAY,KAAK,WAAW,EAAG,QAAO;EAC1D,MAAM,QAAQ,KAAK,MAAM,gBAAgB,EAAE,UAAU;EACrD,MAAM,QAAQ,KAAK,SAAS;AAC5B,SAAO,KAAK,KAAK,QAAQ,EAAE,GAAG;;CAEjC,CAAC;;;;;;;;;AAUF,SAAgB,kBAAkB,SAA4C;AAC5E,QAAO,OAAO,OAAO;EACnB,IAAI,QAAQ;EACZ,MAAM,UAAU,MAA+B;AAC7C,OAAI,OAAO,SAAS,YAAY,KAAK,WAAW,EAAG,QAAO;AAC1D,UAAO,QAAQ,UAAU,KAAK;;EAEjC,CAAC;;;;;;;;;;AAWJ,eAAsB,mBACpB,UACA,SACiB;AACjB,KAAI,WAAW,WAAW,OAAQ,QAAyB,UAAU,WACnE,QAAQ,QAAyB,MAAM,SAAS;CAElD,IAAI,QAAQ;AACZ,MAAK,MAAM,WAAW,SACpB,UAAS,MAAM,QAAQ,UAAU,kBAAkB,QAAQ,CAAC;AAE9D,QAAO;;;;;;;;;;AAWT,SAAgB,kBAAkB,SAA0B;AAC1D,KAAI,QAAQ,SAAS,SAAU,QAAO,QAAQ;CAC9C,MAAM,UAAU,QAAQ;AACxB,KAAI,OAAO,YAAY,SAAU,QAAO;CACxC,IAAI,MAAM;AACV,MAAK,MAAM,QAAQ,QACjB,KAAI,KAAK,SAAS,UAAU,KAAK,SAAS,YACxC,QAAO,GAAG,KAAK,KAAK;KAIpB,QAAO;AAGX,QAAO"}