@classytic/labs 0.4.0 → 0.5.0

package/dist/deep-learning/core/multimodal-alignment.mjs

@@ -1,24 +1,41 @@
-import { euclidean } from "../../core/embedding.mjs";
+import { cosine, euclidean } from "@classytic/stage/ml";
 
 //#region src/deep-learning/core/multimodal-alignment.ts
+/**
+* Multimodal alignment in a 2-D shared space.
+*
+* Each pair has an image point and a caption point with the same `label` (the pair id). Teaching
+* a (image, caption) choice moves the chosen caption toward the image when it is the right caption
+* (pull) or away from it when it is wrong (push), by `learningRate` of the gap, clamped to the
+* space [-3, 3]². A caption is matched when it is the nearest caption (Euclidean distance) to its
+* own image; the space is aligned when every image's nearest caption is its own.
+*
+* Distances and similarities are `@classytic/stage/ml` `euclidean` and `cosine` on [x, y]; the
+* pull/push toy, the fixtures and the matching rule are this lab's.
+*/
+/** Straight-line distance between two points of the space (stage `euclidean` on [x, y]). */
+const pointDistance = (a, b) => euclidean([a.x, a.y], [b.x, b.y]);
 const ALIGNMENT_IMAGES = [
 	{
 		label: "falling",
 		x: -2.2,
 		y: 2.1,
-		group: "image"
+		group: "image",
+		glyph: "falling"
 	},
 	{
 		label: "cross",
 		x: 0,
 		y: 2.5,
-		group: "image"
+		group: "image",
+		glyph: "cross"
 	},
 	{
 		label: "rising",
 		x: 2.2,
 		y: 2.1,
-		group: "image"
+		group: "image",
+		glyph: "rising"
 	}
 ];
 const INITIAL_ALIGNMENT_WORDS = [
@@ -41,30 +58,56 @@ const INITIAL_ALIGNMENT_WORDS = [
 		group: "word"
 	}
 ];
-function alignPair(words, target, choice, learningRate = .28) {
+const LIMIT = 3;
+const clampSpace = (value) => Math.max(-3, Math.min(LIMIT, value));
+function findImage(images, id) {
+	const image = images.find((item) => item.label === id);
+	if (!image) throw new Error(`Unknown alignment image: ${id}`);
+	return image;
+}
+function alignPair(words, target, choice, learningRate = .28, images = ALIGNMENT_IMAGES) {
 	if (!Number.isFinite(learningRate) || learningRate <= 0 || learningRate > 1) throw new Error("Alignment learning rate must be between zero and one");
-	const image = ALIGNMENT_IMAGES.find((item) => item.label === target);
+	const image = findImage(images, target);
 	const selected = words.find((item) => item.label === choice);
 	if (!selected) throw new Error(`Unknown alignment word: ${choice}`);
-	const matched = target === choice, before = euclidean(image, selected);
+	const matched = target === choice, before = pointDistance(image, selected);
 	const direction = matched ? 1 : -1;
 	const updated = words.map((item) => item.label !== choice ? item : {
 		...item,
-		x: Math.max(-3, Math.min(3, item.x + (image.x - item.x) * learningRate * direction)),
-		y: Math.max(-3, Math.min(3, item.y + (image.y - item.y) * learningRate * direction))
+		x: clampSpace(item.x + (image.x - item.x) * learningRate * direction),
+		y: clampSpace(item.y + (image.y - item.y) * learningRate * direction)
 	});
 	const moved = updated.find((item) => item.label === choice);
 	return {
 		words: updated,
 		matched,
 		before,
-		after: euclidean(image, moved)
+		after: pointDistance(image, moved)
 	};
 }
-function nearestWord(words, target) {
-	const image = ALIGNMENT_IMAGES.find((item) => item.label === target);
-	return [...words].sort((left, right) => euclidean(left, image) - euclidean(right, image))[0];
+function nearestWord(words, target, images = ALIGNMENT_IMAGES) {
+	const image = findImage(images, target);
+	return [...words].sort((left, right) => pointDistance(left, image) - pointDistance(right, image))[0];
+}
+/** Ids of the images whose nearest caption is their own. */
+function matchedPairs(words, images = ALIGNMENT_IMAGES) {
+	return images.filter((image) => nearestWord(words, image.label, images).label === image.label).map((i) => i.label);
+}
+/** Every image's nearest caption is its own. */
+function allMatched(words, images = ALIGNMENT_IMAGES) {
+	return matchedPairs(words, images).length === images.length;
+}
+/** Distance matrix: rows are images, columns are captions, in the given orders. */
+function distanceMatrix(images, words) {
+	return images.map((image) => words.map((word) => pointDistance(image, word)));
+}
+/**
+* Cosine similarity matrix: rows are images, columns are captions (as CLIP scores them), each point
+* seen as a vector from the origin (0 when either is the origin).
+*/
+function cosineSimilarityMatrix(images, words) {
+	return images.map((image) => words.map((word) => cosine([image.x, image.y], [word.x, word.y])));
 }
 
 //#endregion
-export { ALIGNMENT_IMAGES, INITIAL_ALIGNMENT_WORDS, alignPair, nearestWord };
+export { ALIGNMENT_IMAGES, INITIAL_ALIGNMENT_WORDS, alignPair, allMatched, cosineSimilarityMatrix, distanceMatrix, matchedPairs, nearestWord, pointDistance };

package/dist/deep-learning/core/neural-trace.d.mts

@@ -1,3 +1,4 @@
+import "@classytic/stage/ml";
 //#region src/deep-learning/core/neural-trace.d.ts
 type ActivationId = 'linear' | 'relu' | 'sigmoid';
 interface NeuralTrace {
@@ -9,6 +10,7 @@ interface NeuralTrace {
   readonly activation: ActivationId;
   readonly output: number;
 }
+/** One gate applied to one pre-activation, through the stage activation table. */
 declare function activate(value: number, activation: ActivationId): number;
 declare function traceNeuron({ inputs, weights, bias, activation }: {
   readonly inputs: readonly number[];
@@ -16,5 +18,26 @@ declare function traceNeuron({ inputs, weights, bias, activation }: {
   readonly bias: number;
   readonly activation: ActivationId;
 }): NeuralTrace;
+/** A target on one output value: strictly above, strictly below, or within `tol` (default 0.05). */
+type OutputGoal = {
+  readonly kind: 'output-above';
+  readonly value: number;
+} | {
+  readonly kind: 'output-below';
+  readonly value: number;
+} | {
+  readonly kind: 'output-within';
+  readonly value: number;
+  readonly tol?: number;
+};
+/**
+ * A goal for the activation-gates lab: an output target (optionally only through one named gate),
+ * or `blocked`: a non-zero input that the current gate turns into exactly 0 (ReLU on a negative input).
+ */
+type ActivationGoal = (OutputGoal & {
+  readonly gate?: ActivationId;
+}) | {
+  readonly kind: 'blocked';
+};
 //#endregion
-export { ActivationId, NeuralTrace, activate, traceNeuron };
+export { ActivationGoal, ActivationId, NeuralTrace, OutputGoal, activate, traceNeuron };

package/dist/deep-learning/core/neural-trace.mjs

@@ -1,8 +1,24 @@
+import { ACTIVATIONS } from "@classytic/stage/ml";
+import { neuron } from "@classytic/stage/ml/deep-learning";
+
 //#region src/deep-learning/core/neural-trace.ts
+/**
+* One neuron, traced for the affine-neuron and activation-gates labs: y = f(w.x + b).
+*
+* Lesson glue over `@classytic/stage/ml/deep-learning` `neuron` (the weighted sum, summed from the
+* bias in input order) and `@classytic/stage/ml` `ACTIVATIONS` (the gate itself). This file owns
+* the lesson's gate names ('linear' is stage's 'identity'), the input checks a lab prop needs, and
+* the goals; the arithmetic is the kernel's.
+*/
+/** The lesson's gate names mapped onto the stage activation table. */
+const KERNEL_ACTIVATION = {
+	linear: "identity",
+	relu: "relu",
+	sigmoid: "sigmoid"
+};
+/** One gate applied to one pre-activation, through the stage activation table. */
 function activate(value, activation) {
-	if (activation === "relu") return Math.max(0, value);
-	if (activation === "sigmoid") return 1 / (1 + Math.exp(-value));
-	return value;
+	return ACTIVATIONS[KERNEL_ACTIVATION[activation]].f(value);
 }
 function traceNeuron({ inputs, weights, bias, activation }) {
 	if (inputs.length === 0) throw new Error("A neuron needs at least one input");
@@ -12,18 +28,30 @@ function traceNeuron({ inputs, weights, bias, activation }) {
 		...weights,
 		bias
 	].every(Number.isFinite)) throw new Error("Neuron inputs, weights, and bias must be finite");
-	const contributions = inputs.map((input, index) => input * weights[index]);
-	const preActivation = contributions.reduce((sum, contribution) => sum + contribution, bias);
+	const kernel = neuron(weights, bias, inputs, KERNEL_ACTIVATION[activation]);
 	return {
 		inputs: [...inputs],
 		weights: [...weights],
-		contributions,
+		contributions: [...kernel.contributions],
 		bias,
-		preActivation,
+		preActivation: kernel.preActivation,
 		activation,
-		output: activate(preActivation, activation)
+		output: kernel.output
 	};
 }
+const DEFAULT_OUTPUT_TOLERANCE = .05;
+function outputGoalMet(goal, output) {
+	if (!Number.isFinite(output)) return false;
+	if (goal.kind === "output-above") return output > goal.value;
+	if (goal.kind === "output-below") return output < goal.value;
+	return Math.abs(output - goal.value) <= (goal.tol ?? .05) + 1e-9;
+}
+function activationGoalMet(goal, input, gate) {
+	const output = activate(input, gate);
+	if (goal.kind === "blocked") return input !== 0 && output === 0;
+	if (goal.gate && goal.gate !== gate) return false;
+	return outputGoalMet(goal, output);
+}
 
 //#endregion
-export { activate, traceNeuron };
+export { DEFAULT_OUTPUT_TOLERANCE, KERNEL_ACTIVATION, activate, activationGoalMet, outputGoalMet, traceNeuron };

package/dist/deep-learning/core/overfit-gap.d.mts

@@ -0,0 +1,28 @@
+import "./char-run.mjs";
+import { RunSpec, TrainingRun } from "@classytic/stage/ml/deep-learning";
+//#region src/deep-learning/core/overfit-gap.d.ts
+type GapActivation = 'relu' | 'tanh';
+declare const GAP_DATASET_IDS: readonly ["noisy-wave"];
+type GapDatasetId = (typeof GAP_DATASET_IDS)[number];
+/** One example: a single feature and its target. */
+interface GapRow {
+  readonly x: number;
+  readonly y: number;
+}
+type GapGoal =
+/** The final gap (after the full step budget) is below `value`, with a regulariser the learner changed. */
+{
+  readonly kind: 'gap-below';
+  readonly value: number;
+} |
+/** A regularised run's best validation loss beats the unregularised baseline's (over its full budget). */
+{
+  readonly kind: 'beat-baseline';
+} |
+/** At least `runs` different settings trained to the end (default 2). */
+{
+  readonly kind: 'compare';
+  readonly runs?: number;
+};
+//#endregion
+export { GAP_DATASET_IDS, GapActivation, GapDatasetId, GapGoal, GapRow };

package/dist/deep-learning/core/overfit-gap.mjs

@@ -0,0 +1,197 @@
+import { gaussian, mixSeed, mulberry32 } from "@classytic/stage/rng";
+import { data } from "@classytic/stage/ml";
+import { run } from "@classytic/stage/ml/deep-learning";
+
+//#region src/deep-learning/core/overfit-gap.ts
+/**
+* The OverfitGap lab's glue over a stage training run (`run` in `@classytic/stage/ml/deep-learning`).
+* Stage owns the network (model kind `mlp`, with its inverted dropout), the optimiser (`adamw`, whose
+* decoupled decay is the lab's weight decay), the evaluations and the semantic events
+* (`deep-learning:validation-minimum`, `deep-learning:overfitting-started`,
+* `deep-learning:loss-diverged`, ...). This file owns what the lesson reads off them: the default
+* dataset, the train/validation gap, the no-regularisation baseline it is compared with, and the goals.
+*
+* Nothing here computes a loss or a gradient. The one piece of arithmetic is the gap itself,
+* validation loss minus training loss, both read from the engine's evaluation.
+*
+* The default dataset (`noisy-wave`) is 30 evenly spaced x in [-3, 3] with y = sin(x) plus gaussian
+* noise (sd 0.3), drawn from stage's seeded stream (seed 7). With the run's 40% hold-out, a
+* 1-128-128-1 ReLU network sees 18 points and is checked on 12, so it can memorise the noise.
+*/
+const NO_REGULARISATION = Object.freeze({
+	dropout: 0,
+	weightDecay: 0
+});
+const DEFAULT_VAL_FRACTION = .4;
+const DATA_ID = "rows";
+/** Stage's split salt for points and rows (run/models.ts); the seam test holds the two to the same split. */
+const SPLIT_SALT = 24301;
+/** A regularised run must beat the baseline's best validation loss by at least this (the engine's minDelta). */
+const BEAT_MARGIN = .001;
+/** The default widths: the ReLU setup is 128-128, the tanh setup 64-64. */
+function defaultHidden(activation) {
+	return activation === "tanh" ? [64, 64] : [128, 128];
+}
+/** `noisy-wave`: 30 points of y = sin(x) + N(0, 0.3²), x evenly spaced on [-3, 3], seeded. */
+function noisyWave(count = 30, noise = .3, seed = 7) {
+	const rng = mulberry32(seed);
+	return Array.from({ length: count }, (_, i) => {
+		const x = -3 + 6 * i / (count - 1);
+		return {
+			x,
+			y: Math.sin(x) + gaussian(rng, 0, noise)
+		};
+	});
+}
+function resolveGapRows(inline, dataset) {
+	if (inline?.length) return inline;
+	switch (dataset ?? "noisy-wave") {
+		default: return noisyWave();
+	}
+}
+/**
+* Which rows the run trains on and which it holds out: stage's own split (`data.holdoutSplit` on the
+* run's split stream), so the figure can mark the held-out points the loss is measured on.
+*/
+function splitGapRows(rows, seed, valFraction = DEFAULT_VAL_FRACTION) {
+	return data.holdoutSplit(rows, mulberry32(mixSeed(seed, SPLIT_SALT)), valFraction);
+}
+const isRegularised = (reg) => reg.dropout > 0 || reg.weightDecay > 0;
+const sameSettings = (a, b) => a.dropout === b.dropout && a.weightDecay === b.weightDecay;
+function gapSpec(opts, reg) {
+	return {
+		id: "overfit-gap",
+		model: {
+			kind: "mlp",
+			inputs: 1,
+			hidden: [...opts.hidden],
+			activation: opts.activation,
+			output: "linear",
+			...reg.dropout > 0 ? { dropout: reg.dropout } : {}
+		},
+		data: {
+			id: DATA_ID,
+			valFraction: opts.valFraction ?? .4
+		},
+		optimiser: {
+			kind: "adamw",
+			learningRate: opts.learningRate,
+			batchSize: "full",
+			weightDecay: reg.weightDecay
+		},
+		evalEvery: opts.evalEvery,
+		detectors: { divergeFactor: 100 },
+		seed: opts.seed
+	};
+}
+const num = (v) => v == null ? NaN : v;
+const toPoint = (p) => ({
+	step: p.step,
+	train: num(p.train),
+	val: num(p.val)
+});
+function sync(r, events) {
+	r.events.push(...events);
+	const last = r.history.at(-1);
+	for (const p of run.historySince(r.handle, last ? last.step : -1)) {
+		const point = toPoint(p);
+		const tail = r.history.at(-1);
+		if (tail && tail.step === point.step) r.history[r.history.length - 1] = point;
+		else if (!tail || point.step > tail.step) r.history.push(point);
+	}
+}
+function createGapRun(opts, reg) {
+	const rows = opts.rows.map((row) => ({
+		x: [row.x],
+		y: row.y
+	}));
+	const handle = run.createRun(gapSpec(opts, reg), () => ({
+		kind: "rows",
+		rows
+	}));
+	const r = {
+		handle,
+		reg,
+		evalEvery: opts.evalEvery,
+		paramCount: run.summary(handle).paramCount,
+		history: [],
+		events: []
+	};
+	sync(r, []);
+	return r;
+}
+function stepOf(r) {
+	return run.summary(r.handle).step;
+}
+function statusOf(r) {
+	return run.summary(r.handle).status;
+}
+/** Take up to `steps` optimiser steps (none while diverged); returns the events they emitted. */
+function advanceGap(r, steps) {
+	const u = run.advance(r.handle, Math.max(0, Math.floor(steps)));
+	sync(r, u.events);
+	return u.events;
+}
+/** Back to step 0 with the same settings and seed (the engine's reset action); history and feed start over. */
+function resetGapRun(r) {
+	const u = run.applyRunAction(r.handle, {
+		type: "deep-learning:reset",
+		version: 1
+	});
+	r.history = [];
+	r.events = [];
+	sync(r, u.events);
+}
+/** The network's prediction at each x, in evaluation mode (dropout off). Read-only. */
+function predictCurve(r, xs) {
+	return xs.map((x) => run.predict(r.handle, x));
+}
+/** Validation loss minus training loss at one evaluation: how much worse the model does on points it never trained on. */
+const gapOf = (p) => p.val - p.train;
+/** The lowest validation loss so far and where, or null before a finite one. */
+function bestVal(history) {
+	let best = null;
+	for (const p of history) if (Number.isFinite(p.val) && (best === null || p.val < best.val)) best = {
+		step: p.step,
+		val: p.val
+	};
+	return best;
+}
+/** A run that has trained its full budget, summarised; null before then (or when it has no finite reading). */
+function recordOf(r, steps) {
+	const last = r.history.at(-1);
+	const best = bestVal(r.history);
+	if (!last || last.step < steps || !best || !Number.isFinite(gapOf(last))) return null;
+	return {
+		reg: r.reg,
+		train: last.train,
+		val: last.val,
+		gap: gapOf(last),
+		bestVal: best.val,
+		bestStep: best.step
+	};
+}
+/** Add or replace the record for its settings (a retrained setting keeps one line). */
+function withRecord(records, rec) {
+	return [...records.filter((r) => !sameSettings(r.reg, rec.reg)), rec];
+}
+function gapGoalMet(goal, v) {
+	switch (goal.kind) {
+		case "gap-below": {
+			const last = v.history.at(-1);
+			return v.changed && !!last && last.step >= v.steps && gapOf(last) < goal.value;
+		}
+		case "beat-baseline": {
+			if (!isRegularised(v.reg)) return false;
+			const baseEnd = v.baseline.at(-1);
+			const base = bestVal(v.baseline);
+			const mine = bestVal(v.history);
+			return !!(baseEnd && baseEnd.step >= v.steps && base && mine && mine.val < base.val - .001);
+		}
+		case "compare": return v.records.length >= (goal.runs ?? 2);
+		default: return goal;
+	}
+}
+
+//#endregion
+export { BEAT_MARGIN, DEFAULT_VAL_FRACTION, NO_REGULARISATION, advanceGap, bestVal, createGapRun, defaultHidden, gapGoalMet, gapOf, gapSpec, isRegularised, noisyWave, predictCurve, recordOf, resetGapRun, resolveGapRows, sameSettings, splitGapRows, statusOf, stepOf, withRecord };

package/dist/deep-learning/core/position.d.mts

@@ -1,17 +1,56 @@
 //#region src/deep-learning/core/position.d.ts
-type PositionToken = 'bird' | 'eats' | 'berries';
+/**
+ * Position signals, React-free.
+ *
+ * Without position information a sequence is a bag: summing token vectors gives the same
+ * fingerprint for any order. Binding each token vector to a position vector (here the outer
+ * product with p_i = [sin(i+1), cos(i+1)]) makes the fingerprint depend on WHERE each token sits.
+ *
+ * A lesson toy (not the transformer's sinusoidal encoding), kept in labs. The binding is
+ * `@classytic/stage/ml/deep-learning` `outer` and the fingerprint distance is `@classytic/stage/ml`
+ * `euclidean`.
+ */
+type PositionToken = string;
+interface PositionVocabularyEntry {
+  readonly label: string;
+  readonly vector: readonly [number, number];
+}
+declare const POSITION_VOCABULARY: readonly PositionVocabularyEntry[];
+declare const DEFAULT_SEQUENCE: readonly string[];
 interface SequenceEncoding {
   readonly tokens: readonly PositionToken[];
   readonly positions: readonly (readonly [number, number])[];
   readonly fingerprint: readonly number[];
 }
-declare function encodeSequence(tokens: readonly PositionToken[], positioned: boolean): SequenceEncoding;
+/** The position vector for 0-based slot `index`: [sin(index+1), cos(index+1)]. */
+declare function positionVector(index: number): readonly [number, number];
+declare function encodeSequence(tokens: readonly PositionToken[], positioned: boolean, vocabulary?: readonly PositionVocabularyEntry[]): SequenceEncoding;
 interface PositionComparison {
   readonly first: SequenceEncoding;
   readonly second: SequenceEncoding;
   readonly distance: number;
   readonly distinguished: boolean;
 }
-declare function compareTokenOrder(positioned: boolean): PositionComparison;
+declare function compareSequences(first: readonly string[], second: readonly string[], positioned: boolean, vocabulary?: readonly PositionVocabularyEntry[]): PositionComparison;
+/** The default comparison: a sequence against its reverse. */
+declare function compareTokenOrder(positioned: boolean, first?: readonly string[], second?: readonly string[], vocabulary?: readonly PositionVocabularyEntry[]): PositionComparison;
+/** Swap slots i and i+1 (returns a new array). */
+declare function swapAdjacent<T>(items: readonly T[], index: number): T[];
+type PositionGoal =
+/** Make the two orders distinguishable: their fingerprints must differ. */
+{
+  readonly kind: 'distinguish-order';
+  readonly label?: string;
+} |
+/** With positions on, rearrange the second sequence until its fingerprint matches the first. */
+{
+  readonly kind: 'match-order';
+  readonly label?: string;
+};
+interface PositionState {
+  readonly positioned: boolean;
+  readonly comparison: PositionComparison;
+}
+declare function positionGoalMet(goal: PositionGoal, state: PositionState): boolean;
 //#endregion
-export { PositionComparison, PositionToken, SequenceEncoding, compareTokenOrder, encodeSequence };
+export { DEFAULT_SEQUENCE, POSITION_VOCABULARY, PositionComparison, PositionGoal, PositionState, PositionToken, PositionVocabularyEntry, SequenceEncoding, compareSequences, compareTokenOrder, encodeSequence, positionGoalMet, positionVector, swapAdjacent };

package/dist/deep-learning/core/position.mjs

@@ -1,28 +1,59 @@
+import { euclidean } from "@classytic/stage/ml";
+import { outer } from "@classytic/stage/ml/deep-learning";
+
 //#region src/deep-learning/core/position.ts
-const TOKEN_VECTOR = {
-	bird: [1, .15],
-	eats: [.35, 1],
-	berries: [.8, .45]
+/**
+* Position signals, React-free.
+*
+* Without position information a sequence is a bag: summing token vectors gives the same
+* fingerprint for any order. Binding each token vector to a position vector (here the outer
+* product with p_i = [sin(i+1), cos(i+1)]) makes the fingerprint depend on WHERE each token sits.
+*
+* A lesson toy (not the transformer's sinusoidal encoding), kept in labs. The binding is
+* `@classytic/stage/ml/deep-learning` `outer` and the fingerprint distance is `@classytic/stage/ml`
+* `euclidean`.
+*/
+const POSITION_VOCABULARY = [
+	{
+		label: "bird",
+		vector: [1, .15]
+	},
+	{
+		label: "eats",
+		vector: [.35, 1]
+	},
+	{
+		label: "berries",
+		vector: [.8, .45]
+	}
+];
+const DEFAULT_SEQUENCE = [
+	"bird",
+	"eats",
+	"berries"
+];
+/** The position vector for 0-based slot `index`: [sin(index+1), cos(index+1)]. */
+function positionVector(index) {
+	return [Math.sin(index + 1), Math.cos(index + 1)];
+}
+const lookup = (vocabulary, token) => {
+	const entry = vocabulary.find((item) => item.label === token);
+	if (!entry) throw new Error(`Unknown token: ${token}`);
+	return entry.vector;
 };
-const positionVector = (index) => [Math.sin(index + 1), Math.cos(index + 1)];
-function encodeSequence(tokens, positioned) {
+function encodeSequence(tokens, positioned, vocabulary = POSITION_VOCABULARY) {
 	if (tokens.length === 0) throw new Error("A sequence needs at least one token");
 	const positions = tokens.map((_, index) => positionVector(index));
 	const fingerprint = positioned ? tokens.reduce((sum, token, index) => {
-		const value = TOKEN_VECTOR[token], position = positions[index];
-		return [
-			sum[0] + value[0] * position[0],
-			sum[1] + value[0] * position[1],
-			sum[2] + value[1] * position[0],
-			sum[3] + value[1] * position[1]
-		];
+		const bound = outer(lookup(vocabulary, token), positions[index]).data;
+		return sum.map((total, cell) => total + bound[cell]);
 	}, [
 		0,
 		0,
 		0,
 		0
 	]) : tokens.reduce((sum, token) => {
-		const value = TOKEN_VECTOR[token];
+		const value = lookup(vocabulary, token);
 		return [
 			sum[0] + value[0],
 			sum[1] + value[1],
@@ -41,24 +72,31 @@ function encodeSequence(tokens, positioned) {
 		fingerprint
 	};
 }
-function compareTokenOrder(positioned) {
-	const first = encodeSequence([
-		"bird",
-		"eats",
-		"berries"
-	], positioned), second = encodeSequence([
-		"berries",
-		"eats",
-		"bird"
-	], positioned);
-	const distance = Math.hypot(...first.fingerprint.map((value, index) => value - second.fingerprint[index]));
+function compareSequences(first, second, positioned, vocabulary = POSITION_VOCABULARY) {
+	const a = encodeSequence(first, positioned, vocabulary), b = encodeSequence(second, positioned, vocabulary);
+	const distance = euclidean(a.fingerprint, b.fingerprint);
 	return {
-		first,
-		second,
+		first: a,
+		second: b,
 		distance,
 		distinguished: distance > 1e-6
 	};
 }
+/** The default comparison: a sequence against its reverse. */
+function compareTokenOrder(positioned, first = DEFAULT_SEQUENCE, second = [...first].reverse(), vocabulary = POSITION_VOCABULARY) {
+	return compareSequences(first, second, positioned, vocabulary);
+}
+/** Swap slots i and i+1 (returns a new array). */
+function swapAdjacent(items, index) {
+	const next = [...items];
+	if (index < 0 || index + 1 >= next.length) return next;
+	[next[index], next[index + 1]] = [next[index + 1], next[index]];
+	return next;
+}
+function positionGoalMet(goal, state) {
+	if (goal.kind === "distinguish-order") return state.comparison.distinguished;
+	return state.positioned && !state.comparison.distinguished;
+}
 
 //#endregion
-export { compareTokenOrder, encodeSequence };
+export { DEFAULT_SEQUENCE, POSITION_VOCABULARY, compareSequences, compareTokenOrder, encodeSequence, positionGoalMet, positionVector, swapAdjacent };