@possumtech/rummy 0.3.0 → 0.4.0

package/src/plugins/cp/cpDoc.js

@@ -2,27 +2,22 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: path attr = source, body = destination
 	['## <cp path="[source]">[destination]</cp> - Copy a file or entry'],
-
-	// --- Examples: single copy, glob batch, cross-scheme
 	[
 		'Example: <cp path="src/config.js">src/config.backup.js</cp>',
 		"Simple file copy. Path = source, body = destination.",
 	],
 	[
 		'Example: <cp path="known://plan_*">known://archive_</cp>',
-		"Glob batch copy across known entries. Shows pattern operations on cp.",
+		"Glob batch copy across known entries.",
 	],
-
-	// --- Constraints
 	[
-		"* Source path accepts globs: `src/*.js`, `known://draft_*`",
-		"Pattern support. Distributes glob teaching beyond get.",
+		"* Source path accepts patterns: `src/*.js`, `known://draft_*`",
+		"Pattern support consistent with get/rm.",
 	],
 	[
-		"* Use `preview` to check matches before bulk copy",
-		"Safety pattern consistent with get and rm preview.",
+		"* Use `preview` to check matches before pattern-based bulk copy",
+		"Safety pattern consistent with rm.",
 	],
 ];
 

package/src/plugins/env/envDoc.js

@@ -2,10 +2,7 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax
 	["## <env>[command]</env> - Run an exploratory shell command"],
-
-	// --- Examples: version check and git status — safe, read-only commands
 	[
 		"Example: <env>npm --version</env>",
 		"Version check. Safe, no side effects.",
@@ -14,15 +11,13 @@ const LINES = [
 		"Example: <env>git log --oneline -5</env>",
 		"Git history. Shows env for read-only investigation.",
 	],
-
-	// --- Constraints: hard boundaries
 	[
 		'* YOU MUST NOT use <env/> to read or list files — use <get path="*" preview/> instead',
-		"Prevents cat/ls through shell. Forces file access through get for proper tracking.",
+		"Prevents cat/ls through shell. Forces file access through get.",
 	],
 	[
-		"* YOU MUST use <sh/> for commands with side effects",
-		"Separates exploration from action. env = observe, sh = mutate.",
+		"* YOU MUST NOT use <env/> for commands with side effects",
+		"Separates exploration from action. env = observe only.",
 	],
 ];
 

package/src/plugins/get/get.js

@@ -30,13 +30,79 @@ export default class Get {
 		const normalized = KnownStore.normalizePath(target);
 		const bodyFilter = entry.attributes.body || null;
 		const isPattern = bodyFilter || normalized.includes("*");
+
+		const line =
+			entry.attributes.line != null
+				? Math.max(1, parseInt(entry.attributes.line, 10))
+				: null;
+		const limit =
+			entry.attributes.limit != null
+				? Math.max(1, parseInt(entry.attributes.limit, 10))
+				: null;
+
 		const matches = await store.getEntriesByPattern(
 			runId,
 			normalized,
 			bodyFilter,
 		);
 
+		// Partial read — no fidelity promotion, returns a line slice as the log item.
+		if (line !== null || limit !== null) {
+			if (isPattern) {
+				await store.upsert(
+					runId,
+					turn,
+					entry.resultPath,
+					"line/limit requires a single path, not a glob or body filter",
+					400,
+					{ loopId },
+				);
+				return;
+			}
+			if (matches.length === 0) {
+				await store.upsert(
+					runId,
+					turn,
+					entry.resultPath,
+					`${target} not found`,
+					200,
+					{ loopId },
+				);
+				return;
+			}
+			const allLines = matches[0].body.split("\n");
+			const total = allLines.length;
+			const startLine = line ?? 1;
+			const startIdx = startLine - 1;
+			const endIdx = limit !== null ? Math.min(startIdx + limit, total) : total;
+			const slice = allLines.slice(startIdx, endIdx).join("\n");
+			const endLine = endIdx;
+			const header = `[lines ${startLine}–${endLine} / ${total} total]`;
+			await store.upsert(
+				runId,
+				turn,
+				entry.resultPath,
+				`${header}\n${slice}`,
+				200,
+				{ loopId },
+			);
+			return;
+		}
+
+		const VALID_FIDELITY = {
+			summary: 1,
+			full: 1,
+			archive: 1,
+		};
+		const fidelityAttr = VALID_FIDELITY[entry.attributes.fidelity]
+			? entry.attributes.fidelity
+			: null;
+
 		await store.promoteByPattern(runId, normalized, bodyFilter, turn);
+		if (fidelityAttr) {
+			for (const match of matches)
+				await store.setFidelity(runId, match.path, fidelityAttr);
+		}
 
 		if (isPattern) {
 			await storePatternResult(
@@ -50,10 +116,12 @@ export default class Get {
 				{ loopId },
 			);
 		} else {
-			const total = matches.reduce((s, m) => s + m.tokens_full, 0);
+			const total = matches.reduce((s, m) => s + m.tokens, 0);
 			const paths = matches.map((m) => m.path).join(", ");
 			const body =
-				matches.length > 0 ? `${paths} ${total} tokens` : `${target} not found`;
+				matches.length > 0
+					? `${paths} promoted to full (${total} tokens)`
+					: `${target} not found`;
 			await store.upsert(runId, turn, entry.resultPath, body, 200, {
 				loopId,
 			});

package/src/plugins/get/getDoc.js

@@ -2,39 +2,42 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: body-form is the primary invocation (simplest)
 	["## <get>[path/to/file]</get> - Load a file or entry into context"],
-
-	// --- Examples: 3 examples covering single file, known recall, and content search
 	[
 		"Example: <get>src/app.js</get>",
-		"Simplest form. Body = path. Teaches that get is the default read tool.",
+		"Simplest form. Body = path.",
 	],
 	[
 		'Example: <get path="known://*">auth</get>',
-		"Keyword recall: glob in path, search term in body. Cross-scheme hedberg pattern.",
+		"Keyword recall: glob in path, search term in body.",
 	],
 	[
-		'Example: <get path="src/**/*.js" preview>TODO</get>',
-		"Full pattern: recursive glob + preview + content filter. Shows all 3 features at once.",
+		'Example: <get path="src/**/*.js" preview>authentication</get>',
+		"Full pattern: recursive glob + preview + content filter.",
+	],
+	[
+		'Example: <get path="src/agent/AgentLoop.js" line="644" limit="80"/>',
+		"Partial read. Returns lines 644–723 without promoting.",
 	],
-
-	// --- Constraints: RFC-style. Each prevents a specific failure mode.
 	[
-		"* Paths accept globs: `src/**/*.js`, `known://api_*`",
-		"Reinforces picomatch patterns work everywhere, not just in examples.",
+		"* Paths accept patterns: `src/**/*.js`, `known://api_*`",
+		"Reinforces picomatch patterns work everywhere.",
 	],
 	[
-		"* `preview` shows matches without loading into context",
-		"Budget-awareness. Without this, models load everything and blow context.",
+		"* `preview` lists matches without loading into context",
+		"Budget-awareness. Preview avoids promotion.",
 	],
 	[
 		"* Body text filters results by content match",
-		"Generalizes examples 2-3. Body = filter, not just path.",
+		"Body = filter, not just path.",
+	],
+	[
+		"* `line` and `limit` read a slice without promoting — patterns not allowed",
+		"Partial read is safe: context budget unaffected.",
 	],
 	[
-		'* Use <set path="..." fidelity="index"/> to archive loaded content',
-		"Lifecycle: get→set. Load, read, archive. Prevents context hoarding.",
+		'* Use <set path="src/file.txt" fidelity="summary"/> when the content is irrelevant to save tokens.',
+		"Cross-tool lifecycle: get promotes, set demotes.",
 	],
 ];
 

package/src/plugins/hedberg/matcher.js

@@ -1,34 +1,15 @@
-import { execSync } from "node:child_process";
-import { unlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { createTwoFilesPatch } from "diff";
 
 export function generatePatch(filePath, oldContent, newContent) {
-	const id = `${Date.now()}_${Math.random().toString(36).slice(2)}`;
-	const oldPath = join(tmpdir(), `rummy_diff_old_${id}`);
-	const newPath = join(tmpdir(), `rummy_diff_new_${id}`);
-
-	try {
-		writeFileSync(oldPath, oldContent);
-		writeFileSync(newPath, newContent);
-
-		const result = execSync(
-			`diff -u --label "${filePath}\told" --label "${filePath}\tnew" "${oldPath}" "${newPath}"`,
-			{ encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] },
-		);
-		return result;
-	} catch (err) {
-		// diff exits 1 when files differ — that's the success case
-		if (err.stdout) return err.stdout;
-		return "";
-	} finally {
-		try {
-			unlinkSync(oldPath);
-		} catch {}
-		try {
-			unlinkSync(newPath);
-		} catch {}
-	}
+	return createTwoFilesPatch(
+		`${filePath}\told`,
+		`${filePath}\tnew`,
+		oldContent,
+		newContent,
+		"",
+		"",
+		{ context: 3 },
+	);
 }
 
 export default class HeuristicMatcher {

package/src/plugins/helpers.js

@@ -14,8 +14,8 @@ export async function storePatternResult(
 ) {
 	const slug = await store.slugPath(runId, scheme, path);
 	const filter = bodyFilter ? ` body="${bodyFilter}"` : "";
-	const total = matches.reduce((s, m) => s + m.tokens_full, 0);
-	const listing = matches.map((m) => `${m.path} (${m.tokens_full})`).join("\n");
+	const total = matches.reduce((s, m) => s + m.tokens, 0);
+	const listing = matches.map((m) => `${m.path} (${m.tokens})`).join("\n");
 	const prefix = preview ? "PREVIEW " : "";
 	const body = `${prefix}${scheme} path="${path}"${filter}: ${matches.length} matched (${total} tokens)\n${listing}`;
 	await store.upsert(runId, turn, slug, body, 200, { loopId });

package/src/plugins/instructions/instructions.js

@@ -37,7 +37,6 @@ export default class Instructions {
 			activeTools.has(n),
 		);
 		const tools = sorted.join(", ");
-		let prompt = preamble.replace("[%TOOLS%]", tools);
 		const toolDocs = await this.#core.hooks.instructions.toolDocs.filter(
 			{},
 			{ toolSet: activeTools },
@@ -46,7 +45,9 @@ export default class Instructions {
 			.filter((key) => toolDocs[key])
 			.map((key) => toolDocs[key])
 			.join("\n\n");
-		if (docsText) prompt += `\n\n${docsText}`;
+		let prompt = preamble
+			.replace("[%TOOLS%]", tools)
+			.replace("[%TOOLDOCS%]", docsText);
 		if (attrs.persona) prompt += `\n\n## Persona\n\n${attrs.persona}`;
 		return prompt;
 	}

package/src/plugins/instructions/preamble.md

@@ -1,16 +1,37 @@
-You are an assistant. YOU MUST gather information, then YOU MAY either answer questions or take action.
-
-# Response Rules
-
-Required: YOU MUST respond with Tool Commands in the XML format. YOU MAY use multiple tools in your response.
-Optional: YOU MAY think in an optional <think></think> tag before using any other Tool Commands.
-Required: YOU MUST register all unknowns with <unknown>(specific thing I need to learn)</unknown>.
-Required: YOU MUST register all new information, decisions, and plans with <known>(specific information, ideas, or plans)</known>.
-Required: YOU MUST conclude every turn with EITHER <update/> if still working OR <summarize/> if done. Never both.
-Required: Path and summary information is approximate. YOU MUST use <get> to verify before acting on summarized content.
-Info: When information conflicts, later turns are more likely to be relevant and correct than earlier turns.
-Info: Your context is limited but your storage is not. Organize and categorize your information, ideas, plans, and history to optimize your context.
+You are a folksonomic knowledgebase assistant. YOU MUST discern what you don't know into unknowns, then extract and organize your findings into navigable and searchable knowns, then YOU MAY answer questions and/or perform actions.
 
 # Tool Commands
 
 Tools: [%TOOLS%]
+
+# Tool Rules
+
+## Response Rules
+Required: YOU MUST respond with Tool Commands in the XML format. YOU MAY use up to 12 tools in your response.
+Required: YOU MUST register all unknowns with <unknown>[specific thing I need to learn]</unknown>.
+Required: YOU MUST register all new facts, decisions, and plans with <known path="topic/subtopic" summary="keyword,keyword,keyword">[specific facts, decisions, or plans]</known>.
+
+## Folksonomic Memory Management
+* Write paths with navigable hierarchies and summaries with searchable tags.
+* When new facts, decisions, and plans appear, set them as <known/> entries with navigable hierarchies and summaries with searchable tags to improve your folksonomic knowledgebase.
+* When new questions emerge, use pattern matching operations to optimize the fidelity and relevance of your knowledgebase.
+* The turn attribute can be helpful for discerning what's fresh or stale, prefer more recent information if conflicts exist.
+* YOU MUST promote all relevant entries and demote all irrelevant entries before acting or answering. Use body pattern search (Example: <get path="known://*">John Doe</get>) to recall archived entries when needed.
+* Logging entries in <previous/> can also be demoted to optimize context.
+
+## Fidelity Management
+* full: Entire contents are shown (consumes token budget)
+* summary: Only path and summary are shown. (<= 80 chars, saves token budget)
+* archive: Archived in an unlimited archive. Entries can be recalled with path recall or pattern search. (use caution)
+
+## Token Budget Management
+* Entries contain a "fidelity" and a "token" attribute to enable token budget management and context optimization.
+* Set relevant entries to "full" and irrelevant entries to "summary" to optimize context.
+* The less irrelevant information in your context, the better.
+
+## Response Termination
+Required: YOU MUST conclude every turn with EITHER <update></update> if still working OR <summarize></summarize> if done. Never both.
+
+# Tool Usage
+
+[%TOOLDOCS%]

package/src/plugins/known/known.js

@@ -1,5 +1,8 @@
+import { countTokens } from "../../agent/tokens.js";
 import docs from "./knownDoc.js";
 
+const MAX_ENTRY_TOKENS = Number(process.env.RUMMY_MAX_ENTRY_TOKENS) || 512;
+
 export default class Known {
 	#core;
 
@@ -8,6 +11,7 @@ export default class Known {
 		core.registerScheme({ category: "data" });
 		core.on("handler", this.handler.bind(this));
 		core.on("full", this.full.bind(this));
+		core.on("summary", this.summary.bind(this));
 		core.filter("assembly.system", this.assembleKnown.bind(this), 100);
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.known = docs;
@@ -16,28 +20,78 @@ export default class Known {
 	}
 
 	async handler(entry, rummy) {
-		const { entries: store, sequence: turn, runId } = rummy;
-		const target = entry.attributes.path || entry.resultPath;
-		await store.upsert(runId, turn, target, entry.body, 200);
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
+		if (!entry.body) return;
+
+		// Size gate
+		const entryTokens = countTokens(entry.body);
+		if (entryTokens > MAX_ENTRY_TOKENS) {
+			const rejectPath = await store.slugPath(runId, "known", entry.body);
+			await store.upsert(
+				runId,
+				turn,
+				rejectPath,
+				`Entry too large (${entryTokens} tokens, max ${MAX_ENTRY_TOKENS}). Sort the information, ideas, or plans carefully into multiple entries.`,
+				413,
+				{ loopId },
+			);
+			return;
+		}
+
+		// Resolve path: explicit or auto-generated slug
+		let knownPath = entry.attributes?.path || null;
+		if (knownPath && !knownPath.includes("://")) {
+			knownPath = `known://${knownPath}`;
+		}
+		if (!knownPath) {
+			knownPath = await store.slugPath(
+				runId,
+				"known",
+				entry.body,
+				entry.attributes?.summary,
+			);
+		}
+
+		// Dedup: if path exists, update rather than duplicate
+		const existing = await store.getEntriesByPattern(runId, knownPath, null);
+		if (existing.length > 0) {
+			await store.upsert(
+				runId,
+				turn,
+				existing[0].path,
+				entry.body || existing[0].body,
+				200,
+				{ attributes: entry.attributes, loopId },
+			);
+			return;
+		}
+
+		await store.upsert(runId, turn, knownPath, entry.body, 200, {
+			attributes: entry.attributes,
+			loopId,
+		});
 	}
 
 	full(entry) {
 		return `# known ${entry.path}\n${entry.body}`;
 	}
 
+	summary(entry) {
+		return this.full(entry);
+	}
+
 	async assembleKnown(content, ctx) {
 		const entries = ctx.rows.filter((r) => r.category === "data");
 		if (entries.length === 0) return content;
 
-		// Rows arrive pre-sorted by SQL: skill → index → summary → full, then by recency
+		// Rows arrive pre-sorted by SQL: summary → full, then by recency
 		const demotedSet = new Set(ctx.demoted || []);
-		const panic = ctx.type === "panic";
-		const lines = entries.map((e) => renderKnownTag(e, demotedSet, panic));
+		const lines = entries.map((e) => renderKnownTag(e, demotedSet));
 		return `${content}\n\n<knowns>\n${lines.join("\n")}\n</knowns>`;
 	}
 }
 
-function renderKnownTag(entry, demotedSet, panic = false) {
+function renderKnownTag(entry, demotedSet) {
 	const tag = entry.scheme || "file";
 	const turn = entry.source_turn ? ` turn="${entry.source_turn}"` : "";
 	const tokens = entry.tokens ? ` tokens="${entry.tokens}"` : "";
@@ -45,23 +99,18 @@ function renderKnownTag(entry, demotedSet, panic = false) {
 	const fidelity = entry.fidelity ? ` fidelity="${entry.fidelity}"` : "";
 	const flag = demotedSet?.has(entry.path) ? " demoted" : "";
 
-	// Panic mode: index-only view so context fits in LLM window
-	if (panic) {
-		return `<${tag} path="${entry.path}"${turn}${fidelity}${tokens}/>`;
-	}
-
 	const attrs =
 		typeof entry.attributes === "string"
 			? JSON.parse(entry.attributes)
 			: entry.attributes;
 	const summary =
 		typeof attrs?.summary === "string"
-			? ` summary="${attrs.summary.slice(0, 80)}"`
+			? ` summary="${attrs.summary.replace(/"/g, "'").slice(0, 80)}"`
 			: "";
 
-	if (entry.body) {
-		return `<${tag} path="${entry.path}"${turn}${status}${fidelity}${summary}${tokens}${flag}>${entry.body}</${tag}>`;
+	if (entry.fidelity === "archive") return "";
+	if (entry.fidelity === "summary") {
+		return `<${tag} path="${entry.path}"${turn}${status}${summary}${fidelity}${tokens}${flag}/>`;
 	}
-
-	return `<${tag} path="${entry.path}"${turn}${status}${fidelity}${summary}${tokens}${flag}/>`;
+	return `<${tag} path="${entry.path}"${turn}${status}${summary}${fidelity}${tokens}${flag}>${entry.body}</${tag}>`;
 }

package/src/plugins/known/knownDoc.js

@@ -2,30 +2,27 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: body = the information to save
 	[
-		"## <known>[specific information, ideas, or plans]</known> - Sort and save what you learn for later recall",
+		'## <known path="known://topic/subtopic" summary="keyword,keyword,keyword">[specific facts, decisions, or plans]</known> - Sort and save what you learn for later recall',
 	],
-	// --- Examples: summary-with-keywords first (teaches the right pattern)
 	[
 		'Example: <known summary="hedberg,comedian,death,2005">Mitch Hedberg died on March 30, 2005</known>',
-		"Primary pattern: comma-separated keywords in summary. Path auto-generated from summary as known://hedberg/comedian/death/2005. Keywords become searchable path segments.",
+		"Summary-first pattern: comma-separated keywords, path auto-generated.",
 	],
 	[
 		'Example: <known path="known://people/rumsfeld" summary="defense,secretary,born,1932">Donald Rumsfeld was born in 1932 and served as Secretary of Defense</known>',
-		"Explicit path form: slashed path=category/key, summary=keywords. For when the model wants direct control over taxonomy.",
+		"Explicit path form: slashed path=category/key, summary=keywords.",
 	],
-	// --- Lifecycle
 	[
 		'* Recall with <get path="known://people/*">keyword</get>',
-		"Cross-tool lifecycle: glob by category, filter by keyword. Matches the slashed path convention.",
+		"Cross-tool lifecycle: glob by category, filter by keyword.",
 	],
 	[
-		"* `summary` keywords survive compression — write keywords you'll search for later",
-		"Teaches WHY summaries matter. Keywords become the path AND the compressed view.",
+		"* YOU SHOULD write `summary` keywords, you can search for them later",
+		"Motivates summary writing through self-interest.",
 	],
 	[
-		"* YOU MUST sort and save all new information, ideas, and plans in their own <known> entries",
+		"* YOU MUST sort and save all new facts, decisions, and plans in their own <known> entries",
 		"Critical behavioral constraint. 'new' prevents re-saving known facts.",
 	],
 ];

package/src/plugins/mv/mv.js

@@ -19,11 +19,28 @@ export default class Mv {
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const { path, to } = entry.attributes;
-		const VALID = { stored: 1, summary: 1, index: 1, full: 1 };
+		const VALID = { stored: 1, summary: 1, index: 1, full: 1, archive: 1 };
 		const fidelity = VALID[entry.attributes.fidelity]
 			? entry.attributes.fidelity
 			: undefined;
 
+		// Fidelity-in-place: no destination, change visibility of matched entries
+		if (fidelity && !to) {
+			const matches = await store.getEntriesByPattern(runId, path);
+			for (const match of matches)
+				await store.setFidelity(runId, match.path, fidelity);
+			const label = fidelity === "archive" ? "archived" : `set to ${fidelity}`;
+			await store.upsert(
+				runId,
+				turn,
+				entry.resultPath,
+				`${matches.map((m) => m.path).join(", ")} ${label}`,
+				200,
+				{ fidelity: "archive", loopId },
+			);
+			return;
+		}
+
 		const source = await store.getBody(runId, path);
 		if (source === null) return;
 

package/src/plugins/mv/mvDoc.js

@@ -2,29 +2,28 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: path attr = source, body = destination
 	[
 		'## <mv path="[source]">[destination]</mv> - Move or rename a file or entry',
 	],
-
-	// --- Examples: entry rename and file move
 	[
 		'Example: <mv path="known://active_task">known://completed_task</mv>',
-		"Entry rename. Most common mv use case. Shows known:// path convention.",
+		"Entry rename. Most common mv use case.",
 	],
 	[
 		'Example: <mv path="src/old_name.js">src/new_name.js</mv>',
-		"File rename. Shows that mv works on files too, not just known entries.",
+		"File rename.",
+	],
+	[
+		'Example: <mv path="known://project/*" fidelity="summary"/>',
+		"Batch fidelity change via pattern. No destination = fidelity in place.",
 	],
-
-	// --- Constraints
 	[
-		"* Source path accepts globs for batch moves",
+		"* Source path accepts patterns for batch moves",
 		"Pattern support consistent with get/cp/rm.",
 	],
 	[
-		"* In ask mode, destination MUST be a scheme path (not a file)",
-		"Mode constraint. Prevents file mutations in ask mode via mv.",
+		"* Use `preview` to check matches before pattern-based bulk moves",
+		"Safety pattern consistent with rm/cp.",
 	],
 ];
 

package/src/plugins/{current → performed}/README.md

@@ -1,6 +1,6 @@
-# current
+# performed
 
-Renders the `<current>` section of the user message — the active loop's
+Renders the `<performed>` section of the user message — the active loop's
 tool results and lifecycle signals.
 
 ## Registration
@@ -11,4 +11,5 @@ tool results and lifecycle signals.
 
 Filters turn_context rows where `category === "logging"` and
 `source_turn >= loopStartTurn`. Renders each entry chronologically
-with turn number and status. Empty on the first turn of a loop.
+with turn, status, summary, fidelity, and tokens. Empty on the first
+turn of a loop.