@seanhogg/builderforce-memory-engine 2026.9.28 → 2026.9.30

package/src/experience/approval.ts

@@ -0,0 +1,49 @@
+/**
+ * experience/approval.ts — which learned steps pause for the person: the ones that
+ * cannot be taken back. A click on "Send", "Pay", "Delete" or "Submit" is where a replay
+ * that drifted does real damage, so the gate is on by default there. Review can still
+ * turn it on or off per step.
+ */
+import type { Action } from './types.js';
+
+/** Words, in the five product languages, that name an action with consequences outside the app. */
+const IRREVERSIBLE = new Set([
+  // en
+  'send', 'submit', 'pay', 'purchase', 'buy', 'order', 'checkout', 'delete', 'remove', 'confirm', 'transfer',
+  'publish', 'post', 'sign', 'approve', 'book', 'cancel', 'erase', 'wipe', 'format', 'uninstall',
+  // de
+  'senden', 'absenden', 'bezahlen', 'kaufen', 'bestellen', 'löschen', 'entfernen', 'bestätigen', 'überweisen', 'veröffentlichen',
+  // es
+  'enviar', 'pagar', 'comprar', 'pedido', 'eliminar', 'borrar', 'confirmar', 'transferir', 'publicar',
+  // fr
+  'envoyer', 'payer', 'acheter', 'commander', 'supprimer', 'confirmer', 'virement', 'publier',
+]);
+
+/** CJK has no word boundaries, so these are matched as substrings. */
+const IRREVERSIBLE_CJK = ['发送', '提交', '支付', '付款', '购买', '下单', '删除', '确认', '转账', '发布'];
+
+export function isIrreversibleLabel(label: string): boolean {
+  const lower = label.toLowerCase();
+  if (IRREVERSIBLE_CJK.some((w) => lower.includes(w))) return true;
+  return lower.split(/[^\p{L}\p{N}]+/u).some((w) => w.length > 0 && IRREVERSIBLE.has(w));
+}
+
+/** The label a person would use for an element: its name, else its automation id. */
+export function elementLabel(target: { name: string; automationId: string } | null | undefined): string {
+  if (!target) return '';
+  return target.name.trim() || target.automationId.trim();
+}
+
+/** The default approval gate for a recorded action. */
+export function needsApproval(action: Action): boolean {
+  switch (action.kind) {
+    case 'click':
+      return isIrreversibleLabel(elementLabel(action.target));
+    case 'keys':
+      // Enter can submit the form it is pressed in, but which button fires is not in the
+      // recording — so it is gated only when the element itself is labelled irreversible.
+      return action.keys.toLowerCase() === 'enter' && isIrreversibleLabel(elementLabel(action.target));
+    case 'setValue':
+      return false;
+  }
+}

package/src/experience/corpus.ts

@@ -0,0 +1,103 @@
+/**
+ * experience/corpus.ts — experience as text Evermind can learn from.
+ *
+ * Evermind already learns from text through ONE recipe (`evermind/adapt.ts`
+ * `adaptAndDiff`: fit a private copy of a version, diff it). Rather than a second,
+ * trajectory-shaped training path, each demonstration is rendered as the procedure a
+ * person would write down — the task, then numbered steps — and handed to that recipe.
+ * Values that became parameters are written as `<name>` placeholders, so the model
+ * learns the procedure rather than one day's numbers. Secrets never appear: a secret
+ * field's value was never recorded.
+ */
+import { elementLabel } from './approval.js';
+import type { Action, Episode, Skill, SkillAction } from './types.js';
+
+function where(a: Action | SkillAction): string {
+  const w = 'target' in a && a.target ? a.target.windowTitle : '';
+  return w ? ` in “${w}”` : '';
+}
+
+function stepSentence(a: Action | SkillAction): string {
+  switch (a.kind) {
+    case 'click':
+      return `Click “${elementLabel(a.target)}”${where(a)}.`;
+    case 'keys':
+      return a.target ? `Press ${a.keys} in “${elementLabel(a.target)}”${where(a)}.` : `Press ${a.keys}.`;
+    case 'setValue': {
+      const field = `“${elementLabel(a.target)}”`;
+      if (typeof a.value === 'string') {
+        return 'secret' in a && a.secret ? `Enter the secret for ${field}${where(a)}.` : `Set ${field} to “${a.value}”${where(a)}.`;
+      }
+      return a.value.from === 'param' ? `Set ${field} to <${a.value.name}>${where(a)}.` : `Set ${field} to “${a.value.text}”${where(a)}.`;
+    }
+  }
+}
+
+function programName(program: string): string {
+  return program.split(/[\\/]/).pop() ?? program;
+}
+
+/** A skill as a written procedure (parameters as placeholders, approvals marked). */
+export function skillText(skill: Skill): string {
+  const lines = [`Task: ${skill.name} (${programName(skill.program)})`];
+  skill.steps.forEach((s, i) => lines.push(`${i + 1}. ${stepSentence(s.action)}${s.requiresApproval ? ' Ask before doing this.' : ''}`));
+  return lines.join('\n');
+}
+
+/** A raw demonstration as a written procedure. */
+export function episodeText(episode: Episode): string {
+  const lines = [`Task: ${episode.name} (${programName(episode.program)})`];
+  episode.steps.forEach((s, i) => lines.push(`${i + 1}. ${stepSentence(s.action)}`));
+  return lines.join('\n');
+}
+
+/**
+ * The corpus to learn from: every skill as a procedure, plus demonstrations that have
+ * not been compiled into one yet (a compiled skill supersedes its raw episode — the
+ * reviewed version is the one worth learning).
+ */
+export function experienceCorpus(episodes: Episode[], skills: Skill[]): string {
+  return experienceDocuments(episodes, skills)
+    .map((d) => d.text)
+    .join('\n\n');
+}
+
+/** One learnable procedure and the experience item it came from. */
+export interface ExperienceDocument {
+  id: string;
+  text: string;
+}
+
+/** The corpus as separate procedures, each tagged with its source item's id. */
+export function experienceDocuments(episodes: Episode[], skills: Skill[]): ExperienceDocument[] {
+  const compiled = new Set(skills.map((s) => s.sourceEpisode));
+  return [
+    ...skills.map((s) => ({ id: s.id, text: skillText(s) })),
+    ...episodes.filter((e) => !compiled.has(e.id)).map((e) => ({ id: e.id, text: episodeText(e) })),
+  ];
+}
+
+/**
+ * Pack procedures into passes of at most `maxChars` (one adaptation pass reads that
+ * much), never splitting a procedure — one longer than a pass gets a pass of its own.
+ */
+export function packDocuments(docs: ExperienceDocument[], maxChars: number): ExperienceDocument[][] {
+  const passes: ExperienceDocument[][] = [];
+  let cur: ExperienceDocument[] = [];
+  let len = 0;
+  for (const d of docs) {
+    const add = cur.length ? d.text.length + 2 : d.text.length;
+    if (cur.length && len + add > maxChars) {
+      passes.push(cur);
+      cur = [];
+      len = 0;
+      cur.push(d);
+      len = d.text.length;
+      continue;
+    }
+    cur.push(d);
+    len += add;
+  }
+  if (cur.length) passes.push(cur);
+  return passes;
+}

package/src/experience/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Experience — the learned items that are not facts or weights: demonstrations
+ * (episodes), the skills Train Once compiles from them, and the runs of those skills.
+ * Pure and storage-agnostic, like the rest of the engine.
+ */
+export type {
+  ElementRef,
+  Action,
+  RecordedStep,
+  Episode,
+  EpisodeSummary,
+  SkillParam,
+  SkillValue,
+  SkillAction,
+  SkillStep,
+  Schedule,
+  SkillRoutine,
+  Skill,
+  RunStatus,
+  StepOutcome,
+  RunStepLog,
+  Run,
+  Adaptation,
+} from './types.js';
+export { newExperienceId } from './types.js';
+export { isIrreversibleLabel, elementLabel, needsApproval } from './approval.js';
+export { trainOnce, slug } from './trainOnce.js';
+export type { ReviewEdits } from './trainOnce.js';
+export { isDue, dueSkills } from './schedule.js';
+export { experienceCorpus, experienceDocuments, packDocuments } from './corpus.js';
+export type { ExperienceDocument } from './corpus.js';
+export { experienceOverview } from './overview.js';
+export type { ExperienceOverview, ExperienceRegion, ExperienceEvent, ExperienceDay, OverviewOptions } from './overview.js';
+export { EXPERIENCE_SCHEMA, MAX_RUNS, MAX_ADAPTATIONS, emptySnapshot, parseSnapshot, InMemoryExperienceStore } from './store.js';
+export type { ExperienceSnapshot, ExperienceStore } from './store.js';

package/src/experience/overview.ts

@@ -0,0 +1,143 @@
+/**
+ * experience/overview.ts — what experience says about the brain, for anything that draws
+ * it. Pure: the host passes the snapshot, which adaptation its model is at, the clock
+ * and the local UTC offset; every number comes from the snapshot, none is estimated.
+ *
+ * The regions are the parts of the brain experience lives in:
+ *   - **hippocampus** — episodic memory: the demonstrations;
+ *   - **basalGanglia** — action selection: the skills, and how their runs went;
+ *   - **amygdala** — salience: the decisions made at irreversible steps;
+ *   - **hypothalamus** — drives: the routines that start skills by themselves;
+ *   - **neocortex** — the private model's weights: the procedures adapted into it.
+ * Facts (semantic memory) and attention belong to other stores; a host adds those.
+ */
+import { experienceDocuments } from './corpus.js';
+import type { ExperienceSnapshot } from './store.js';
+import type { Adaptation, RunStatus } from './types.js';
+
+export type ExperienceRegion = 'hippocampus' | 'basalGanglia' | 'amygdala' | 'hypothalamus' | 'neocortex';
+
+/** One thing that happened, placed in the region it landed in. */
+export interface ExperienceEvent {
+  region: ExperienceRegion;
+  kind: 'demonstration' | 'skill' | 'run' | 'approval' | 'adaptation';
+  /** The episode, skill, run or model version it concerns. */
+  id: string;
+  name: string;
+  at: number;
+  /** Run status, approval outcome, or the adaptation's loss — what happened. */
+  detail?: string;
+}
+
+export interface ExperienceDay {
+  /** Local calendar day, `YYYY-MM-DD`. */
+  day: string;
+  demonstrations: number;
+  skills: number;
+  runs: number;
+  learned: number;
+}
+
+export interface ExperienceOverview {
+  regions: Record<ExperienceRegion, number>;
+  /** Procedures the model at `modelIndex` has learned, and those it has not yet. */
+  learned: number;
+  pending: number;
+  runs: Record<RunStatus, number>;
+  approvals: { approved: number; denied: number };
+  /** Oldest first — the order a chart reads. */
+  adaptations: Adaptation[];
+  /** One entry per day of the window, oldest first, empty days included. */
+  days: ExperienceDay[];
+  /** Newest first. */
+  recent: ExperienceEvent[];
+}
+
+const DAY_MS = 86_400_000;
+
+export interface OverviewOptions {
+  /** N of the loaded model's `+expN` version (0 for a base model or none). */
+  modelIndex: number;
+  now: number;
+  /** Local minus UTC, in minutes. */
+  utcOffsetMinutes: number;
+  /** Days of activity to chart. Default 30. */
+  days?: number;
+  /** Events to list. Default 40. */
+  recent?: number;
+}
+
+function localDay(at: number, offsetMinutes: number): string {
+  return new Date(at + offsetMinutes * 60_000).toISOString().slice(0, 10);
+}
+
+export function experienceOverview(snap: ExperienceSnapshot, opts: OverviewOptions): ExperienceOverview {
+  const known = (id: string) => {
+    const n = snap.learned[id];
+    return typeof n === 'number' && n >= 1 && n <= opts.modelIndex;
+  };
+  const docs = experienceDocuments(snap.episodes, snap.skills);
+  const learned = docs.filter((d) => known(d.id)).length;
+
+  const runs: Record<RunStatus, number> = { running: 0, succeeded: 0, failed: 0, stopped: 0, denied: 0 };
+  const approvals = { approved: 0, denied: 0 };
+  const events: ExperienceEvent[] = [];
+
+  for (const e of snap.episodes) {
+    events.push({ region: 'hippocampus', kind: 'demonstration', id: e.id, name: e.name, at: e.startedAt });
+  }
+  for (const s of snap.skills) {
+    events.push({ region: 'basalGanglia', kind: 'skill', id: s.id, name: s.name, at: s.createdAt });
+  }
+  for (const r of snap.runs) {
+    runs[r.status] = (runs[r.status] ?? 0) + 1;
+    events.push({ region: 'basalGanglia', kind: 'run', id: r.id, name: r.skillName, at: r.startedAt, detail: r.status });
+    for (const step of r.steps) {
+      if (step.outcome !== 'approved' && step.outcome !== 'denied') continue;
+      approvals[step.outcome]++;
+      events.push({ region: 'amygdala', kind: 'approval', id: r.id, name: r.skillName, at: step.at, detail: step.outcome });
+    }
+  }
+  // Only adaptations the loaded model descends from: a rolled-back model's discarded
+  // versions are not what it knows.
+  const adaptations = snap.adaptations.filter((a) => a.index <= opts.modelIndex).reverse();
+  for (const a of adaptations) {
+    events.push({ region: 'neocortex', kind: 'adaptation', id: a.version, name: a.version, at: a.at, detail: a.loss.toFixed(3) });
+  }
+
+  const windowDays = Math.max(1, opts.days ?? 30);
+  const days: ExperienceDay[] = [];
+  const index = new Map<string, ExperienceDay>();
+  for (let i = windowDays - 1; i >= 0; i--) {
+    const day = localDay(opts.now - i * DAY_MS, opts.utcOffsetMinutes);
+    if (index.has(day)) continue;
+    const entry = { day, demonstrations: 0, skills: 0, runs: 0, learned: 0 };
+    index.set(day, entry);
+    days.push(entry);
+  }
+  const bump = (at: number, field: Exclude<keyof ExperienceDay, 'day'>, by = 1) => {
+    const d = index.get(localDay(at, opts.utcOffsetMinutes));
+    if (d) d[field] += by;
+  };
+  for (const e of snap.episodes) bump(e.startedAt, 'demonstrations');
+  for (const s of snap.skills) bump(s.createdAt, 'skills');
+  for (const r of snap.runs) bump(r.startedAt, 'runs');
+  for (const a of adaptations) bump(a.at, 'learned', a.learned.length);
+
+  return {
+    regions: {
+      hippocampus: snap.episodes.length,
+      basalGanglia: snap.skills.length,
+      amygdala: approvals.approved + approvals.denied,
+      hypothalamus: snap.skills.filter((s) => s.routine?.enabled).length,
+      neocortex: learned,
+    },
+    learned,
+    pending: docs.length - learned,
+    runs,
+    approvals,
+    adaptations,
+    days,
+    recent: events.sort((a, b) => b.at - a.at).slice(0, Math.max(0, opts.recent ?? 40)),
+  };
+}

package/src/experience/schedule.ts

@@ -0,0 +1,29 @@
+/**
+ * experience/schedule.ts — when a skill's routine is due. Pure: the host supplies the
+ * clock and the local UTC offset, and ticks as often as it likes.
+ */
+import type { Schedule, Skill } from './types.js';
+
+const MINUTE = 60_000;
+const DAY = 86_400_000;
+
+/** `utcOffsetMinutes` is local minus UTC (e.g. -240 for UTC-4). */
+export function isDue(schedule: Schedule, lastRunAt: number | null | undefined, now: number, utcOffsetMinutes: number): boolean {
+  if (schedule.every === 'minutes') {
+    const every = Math.max(1, schedule.minutes) * MINUTE;
+    return lastRunAt == null || now - lastRunAt >= every;
+  }
+  const offset = utcOffsetMinutes * MINUTE;
+  const localNow = now + offset;
+  const dayStart = localNow - (((localNow % DAY) + DAY) % DAY);
+  const target = dayStart + Math.min(23, Math.max(0, schedule.hour)) * 3_600_000 + Math.min(59, Math.max(0, schedule.minute)) * MINUTE;
+  // Due once the time of day has passed, unless it already ran since then.
+  return localNow >= target && (lastRunAt == null || lastRunAt + offset < target);
+}
+
+/** Skills whose enabled routine is due now, oldest-run first. */
+export function dueSkills(skills: Skill[], now: number, utcOffsetMinutes: number): Skill[] {
+  return skills
+    .filter((s) => s.routine?.enabled && isDue(s.routine.schedule, s.routine.lastRunAt, now, utcOffsetMinutes))
+    .sort((a, b) => (a.routine?.lastRunAt ?? 0) - (b.routine?.lastRunAt ?? 0));
+}

package/src/experience/store.ts

@@ -0,0 +1,188 @@
+/**
+ * experience/store.ts — the persistence port for experience, and its snapshot format.
+ *
+ * The engine does no I/O (checkpoints are `ArrayBuffer`s the host stores); experience
+ * follows the same rule. `ExperienceStore` is the port every host implements over its own
+ * storage — a JSON file on disk (memory-mcp), IndexedDB, a KV. `InMemoryExperienceStore`
+ * is the reference implementation, and `ExperienceSnapshot` is the one serialized shape,
+ * so a store on one runtime can be read by another.
+ */
+import type { Adaptation, Episode, EpisodeSummary, Run, RunStepLog, Skill } from './types.js';
+
+export const EXPERIENCE_SCHEMA = 'evermind.experience/1';
+/** Runs kept, newest first — the audit trail is recent history, not an archive. */
+export const MAX_RUNS = 500;
+/** Adaptations kept, newest first — enough history to chart how learning went. */
+export const MAX_ADAPTATIONS = 200;
+
+export interface ExperienceSnapshot {
+  schema: typeof EXPERIENCE_SCHEMA;
+  episodes: Episode[];
+  skills: Skill[];
+  runs: Run[];
+  /**
+   * Which episodes and skills the local Evermind has been adapted on, and by which
+   * adaptation (the N of the model's `+expN` version) — so training reads each
+   * procedure once, and a model rolled back to an earlier N re-learns what the
+   * discarded versions had learned.
+   */
+  learned: Record<string, number>;
+  /** Every adaptation's measurements, newest first (capped at {@link MAX_ADAPTATIONS}). */
+  adaptations: Adaptation[];
+}
+
+export interface ExperienceStore {
+  putEpisode(episode: Episode): Promise<void>;
+  getEpisode(id: string): Promise<Episode | undefined>;
+  listEpisodes(): Promise<EpisodeSummary[]>;
+  /** Forget a demonstration. Skills compiled from it keep working — they carry their own steps. */
+  deleteEpisode(id: string): Promise<boolean>;
+
+  putSkill(skill: Skill): Promise<void>;
+  getSkill(id: string): Promise<Skill | undefined>;
+  listSkills(): Promise<Skill[]>;
+  deleteSkill(id: string): Promise<boolean>;
+
+  putRun(run: Run): Promise<void>;
+  /** Append one audit line to a run; false when the run is unknown. */
+  appendRunStep(runId: string, step: RunStepLog): Promise<boolean>;
+  getRun(id: string): Promise<Run | undefined>;
+  listRuns(limit: number): Promise<Run[]>;
+
+  /**
+   * Record one adaptation: its items join the learned ledger under its index (the
+   * model's `+expN`) and its measurements join the history — one write, so the ledger
+   * and the chart can never disagree.
+   */
+  recordAdaptation(adaptation: Adaptation): Promise<void>;
+
+  snapshot(): Promise<ExperienceSnapshot>;
+  /** Delete every episode, skill and run. */
+  clear(): Promise<void>;
+}
+
+export function emptySnapshot(): ExperienceSnapshot {
+  return { schema: EXPERIENCE_SCHEMA, episodes: [], skills: [], runs: [], learned: {}, adaptations: [] };
+}
+
+/** Parse a snapshot, tolerating a missing or foreign file as empty. */
+export function parseSnapshot(raw: unknown): ExperienceSnapshot {
+  const s = raw as Partial<ExperienceSnapshot> | null;
+  if (!s || s.schema !== EXPERIENCE_SCHEMA) return emptySnapshot();
+  return {
+    schema: EXPERIENCE_SCHEMA,
+    episodes: Array.isArray(s.episodes) ? s.episodes : [],
+    skills: Array.isArray(s.skills) ? s.skills : [],
+    runs: Array.isArray(s.runs) ? s.runs : [],
+    learned: s.learned && typeof s.learned === 'object' && !Array.isArray(s.learned) ? s.learned : {},
+    // Optional within schema 1: snapshots written before the history existed have none.
+    adaptations: Array.isArray(s.adaptations) ? s.adaptations : [],
+  };
+}
+
+function summary(e: Episode): EpisodeSummary {
+  return { id: e.id, name: e.name, program: e.program, startedAt: e.startedAt, steps: e.steps.length };
+}
+
+/**
+ * The reference store: the snapshot held in memory. Hosts that persist wrap it and
+ * write `snapshot()` after each change (see `onChange`).
+ */
+export class InMemoryExperienceStore implements ExperienceStore {
+  private data: ExperienceSnapshot;
+
+  constructor(initial?: ExperienceSnapshot, private readonly onChange?: (s: ExperienceSnapshot) => void | Promise<void>) {
+    this.data = initial ? parseSnapshot(initial) : emptySnapshot();
+  }
+
+  /** Replace the contents (a host re-reading its file after another process wrote it). */
+  load(snapshot: ExperienceSnapshot): void {
+    this.data = parseSnapshot(snapshot);
+  }
+
+  private async changed(): Promise<void> {
+    await this.onChange?.(this.data);
+  }
+
+  private static upsert<T extends { id: string }>(list: T[], item: T): void {
+    const i = list.findIndex((x) => x.id === item.id);
+    if (i >= 0) list[i] = item;
+    else list.push(item);
+  }
+
+  private static remove<T extends { id: string }>(list: T[], id: string): boolean {
+    const i = list.findIndex((x) => x.id === id);
+    if (i < 0) return false;
+    list.splice(i, 1);
+    return true;
+  }
+
+  async putEpisode(episode: Episode): Promise<void> {
+    InMemoryExperienceStore.upsert(this.data.episodes, episode);
+    await this.changed();
+  }
+  async getEpisode(id: string): Promise<Episode | undefined> {
+    return this.data.episodes.find((e) => e.id === id);
+  }
+  async listEpisodes(): Promise<EpisodeSummary[]> {
+    return [...this.data.episodes].sort((a, b) => b.startedAt - a.startedAt).map(summary);
+  }
+  async deleteEpisode(id: string): Promise<boolean> {
+    const ok = InMemoryExperienceStore.remove(this.data.episodes, id);
+    delete this.data.learned[id];
+    if (ok) await this.changed();
+    return ok;
+  }
+
+  async putSkill(skill: Skill): Promise<void> {
+    InMemoryExperienceStore.upsert(this.data.skills, skill);
+    await this.changed();
+  }
+  async getSkill(id: string): Promise<Skill | undefined> {
+    return this.data.skills.find((s) => s.id === id);
+  }
+  async listSkills(): Promise<Skill[]> {
+    return [...this.data.skills].sort((a, b) => b.createdAt - a.createdAt);
+  }
+  async deleteSkill(id: string): Promise<boolean> {
+    const ok = InMemoryExperienceStore.remove(this.data.skills, id);
+    delete this.data.learned[id];
+    if (ok) await this.changed();
+    return ok;
+  }
+
+  async putRun(run: Run): Promise<void> {
+    InMemoryExperienceStore.upsert(this.data.runs, run);
+    this.data.runs.sort((a, b) => b.startedAt - a.startedAt);
+    this.data.runs.length = Math.min(this.data.runs.length, MAX_RUNS);
+    await this.changed();
+  }
+  async appendRunStep(runId: string, step: RunStepLog): Promise<boolean> {
+    const run = this.data.runs.find((r) => r.id === runId);
+    if (!run) return false;
+    run.steps.push(step);
+    await this.changed();
+    return true;
+  }
+  async getRun(id: string): Promise<Run | undefined> {
+    return this.data.runs.find((r) => r.id === id);
+  }
+  async listRuns(limit: number): Promise<Run[]> {
+    return this.data.runs.slice(0, Math.max(0, limit));
+  }
+
+  async recordAdaptation(adaptation: Adaptation): Promise<void> {
+    for (const id of adaptation.learned) this.data.learned[id] = adaptation.index;
+    this.data.adaptations.unshift(adaptation);
+    this.data.adaptations.length = Math.min(this.data.adaptations.length, MAX_ADAPTATIONS);
+    await this.changed();
+  }
+
+  async snapshot(): Promise<ExperienceSnapshot> {
+    return structuredClone(this.data);
+  }
+  async clear(): Promise<void> {
+    this.data = emptySnapshot();
+    await this.changed();
+  }
+}

package/src/experience/trainOnce.ts

@@ -0,0 +1,85 @@
+/**
+ * experience/trainOnce.ts — Train Once: one reviewed demonstration becomes a skill that
+ * runs again with new values.
+ *
+ * Deterministic, local, no model call. Every value the person typed becomes a named
+ * parameter (named after the field it went into), every secret field a secret parameter,
+ * and every irreversible click an approval gate. The review edits decide what stays.
+ */
+import { elementLabel, needsApproval } from './approval.js';
+import { newExperienceId, type Episode, type Skill, type SkillAction, type SkillParam, type SkillStep } from './types.js';
+
+/** What the person changed in review, keyed by recorded step id. */
+export interface ReviewEdits {
+  /** The skill's name (defaults to the episode's). */
+  name?: string | null;
+  /** Steps left out of the skill. */
+  removed?: string[];
+  /** Typed values kept exactly as recorded instead of asked for each run. */
+  fixed?: string[];
+  /** Approval gate per step, where the person overrode the default. */
+  approvals?: Record<string, boolean>;
+  /** Parameter names the person chose, per step. */
+  paramNames?: Record<string, string>;
+}
+
+export function trainOnce(episode: Episode, edits: ReviewEdits = {}, now: number = Date.now()): Skill {
+  const removed = new Set(edits.removed ?? []);
+  const fixed = new Set(edits.fixed ?? []);
+  const params: SkillParam[] = [];
+  const steps: SkillStep[] = [];
+  for (const rec of episode.steps) {
+    if (removed.has(rec.id)) continue;
+    const a = rec.action;
+    let action: SkillAction;
+    if (a.kind === 'setValue') {
+      if (!a.secret && fixed.has(rec.id)) {
+        action = { kind: 'setValue', target: a.target, value: { from: 'literal', text: a.value } };
+      } else {
+        const chosen = slug(edits.paramNames?.[rec.id] ?? '');
+        const base = chosen || slug(elementLabel(a.target)) || 'value';
+        const name = uniqueName(params, base);
+        params.push({ name, label: elementLabel(a.target), default: a.secret ? null : a.value, secret: !!a.secret });
+        action = { kind: 'setValue', target: a.target, value: { from: 'param', name } };
+      }
+    } else {
+      action = a;
+    }
+    steps.push({
+      id: rec.id,
+      action,
+      requiresApproval: edits.approvals?.[rec.id] ?? needsApproval(a),
+      screenshot: rec.screenshot ?? null,
+    });
+  }
+  return {
+    id: newExperienceId(),
+    name: edits.name?.trim() || episode.name,
+    program: episode.program,
+    args: [...episode.args],
+    params,
+    steps,
+    sourceEpisode: episode.id,
+    createdAt: now,
+    routine: null,
+  };
+}
+
+/** `Invoice Amount (USD)` → `invoice_amount_usd`. Letters in any script survive. */
+export function slug(label: string): string {
+  return label
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean)
+    .join('_')
+    .slice(0, 40)
+    .replace(/_+$/, '');
+}
+
+function uniqueName(params: SkillParam[], base: string): string {
+  if (!params.some((p) => p.name === base)) return base;
+  for (let i = 2; ; i++) {
+    const n = `${base}_${i}`;
+    if (!params.some((p) => p.name === n)) return n;
+  }
+}