@seanhogg/builderforce-memory-engine 2026.9.28 → 2026.9.30

package/dist/experience/overview.js

@@ -0,0 +1,92 @@
+/**
+ * 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';
+const DAY_MS = 86_400_000;
+function localDay(at, offsetMinutes) {
+    return new Date(at + offsetMinutes * 60_000).toISOString().slice(0, 10);
+}
+export function experienceOverview(snap, opts) {
+    const known = (id) => {
+        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 = { running: 0, succeeded: 0, failed: 0, stopped: 0, denied: 0 };
+    const approvals = { approved: 0, denied: 0 };
+    const events = [];
+    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 = [];
+    const index = new Map();
+    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, field, 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)),
+    };
+}
+//# sourceMappingURL=overview.js.map

package/dist/experience/overview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overview.js","sourceRoot":"","sources":["../../src/experience/overview.ts"],"names":[],"mappings":"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"}

package/dist/experience/schedule.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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';
+/** `utcOffsetMinutes` is local minus UTC (e.g. -240 for UTC-4). */
+export declare function isDue(schedule: Schedule, lastRunAt: number | null | undefined, now: number, utcOffsetMinutes: number): boolean;
+/** Skills whose enabled routine is due now, oldest-run first. */
+export declare function dueSkills(skills: Skill[], now: number, utcOffsetMinutes: number): Skill[];
+//# sourceMappingURL=schedule.d.ts.map

package/dist/experience/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/experience/schedule.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAKlD,mEAAmE;AACnE,wBAAgB,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAW9H;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,KAAK,EAAE,CAIzF"}

package/dist/experience/schedule.js

@@ -0,0 +1,22 @@
+const MINUTE = 60_000;
+const DAY = 86_400_000;
+/** `utcOffsetMinutes` is local minus UTC (e.g. -240 for UTC-4). */
+export function isDue(schedule, lastRunAt, now, utcOffsetMinutes) {
+    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, now, utcOffsetMinutes) {
+    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));
+}
+//# sourceMappingURL=schedule.js.map

package/dist/experience/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","sourceRoot":"","sources":["../../src/experience/schedule.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,GAAG,MAAM,CAAC;AACtB,MAAM,GAAG,GAAG,UAAU,CAAC;AAEvB,mEAAmE;AACnE,MAAM,UAAU,KAAK,CAAC,QAAkB,EAAE,SAAoC,EAAE,GAAW,EAAE,gBAAwB;IACnH,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QACrD,OAAO,SAAS,IAAI,IAAI,IAAI,GAAG,GAAG,SAAS,IAAI,KAAK,CAAC;IACvD,CAAC;IACD,MAAM,MAAM,GAAG,gBAAgB,GAAG,MAAM,CAAC;IACzC,MAAM,QAAQ,GAAG,GAAG,GAAG,MAAM,CAAC;IAC9B,MAAM,QAAQ,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,QAAQ,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC;IACrI,yEAAyE;IACzE,OAAO,QAAQ,IAAI,MAAM,IAAI,CAAC,SAAS,IAAI,IAAI,IAAI,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;AAClF,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,MAAe,EAAE,GAAW,EAAE,gBAAwB;IAC9E,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAC;SAC1G,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC;AAC/E,CAAC"}

package/dist/experience/store.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 declare const EXPERIENCE_SCHEMA = "evermind.experience/1";
+/** Runs kept, newest first — the audit trail is recent history, not an archive. */
+export declare const MAX_RUNS = 500;
+/** Adaptations kept, newest first — enough history to chart how learning went. */
+export declare 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 declare function emptySnapshot(): ExperienceSnapshot;
+/** Parse a snapshot, tolerating a missing or foreign file as empty. */
+export declare function parseSnapshot(raw: unknown): ExperienceSnapshot;
+/**
+ * The reference store: the snapshot held in memory. Hosts that persist wrap it and
+ * write `snapshot()` after each change (see `onChange`).
+ */
+export declare class InMemoryExperienceStore implements ExperienceStore {
+    private readonly onChange?;
+    private data;
+    constructor(initial?: ExperienceSnapshot, onChange?: ((s: ExperienceSnapshot) => void | Promise<void>) | undefined);
+    /** Replace the contents (a host re-reading its file after another process wrote it). */
+    load(snapshot: ExperienceSnapshot): void;
+    private changed;
+    private static upsert;
+    private static remove;
+    putEpisode(episode: Episode): Promise<void>;
+    getEpisode(id: string): Promise<Episode | undefined>;
+    listEpisodes(): Promise<EpisodeSummary[]>;
+    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>;
+    appendRunStep(runId: string, step: RunStepLog): Promise<boolean>;
+    getRun(id: string): Promise<Run | undefined>;
+    listRuns(limit: number): Promise<Run[]>;
+    recordAdaptation(adaptation: Adaptation): Promise<void>;
+    snapshot(): Promise<ExperienceSnapshot>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/experience/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/experience/store.ts"],"names":[],"mappings":"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"}

package/dist/experience/store.js

@@ -0,0 +1,128 @@
+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 function emptySnapshot() {
+    return { schema: EXPERIENCE_SCHEMA, episodes: [], skills: [], runs: [], learned: {}, adaptations: [] };
+}
+/** Parse a snapshot, tolerating a missing or foreign file as empty. */
+export function parseSnapshot(raw) {
+    const s = raw;
+    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) {
+    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 {
+    onChange;
+    data;
+    constructor(initial, onChange) {
+        this.onChange = onChange;
+        this.data = initial ? parseSnapshot(initial) : emptySnapshot();
+    }
+    /** Replace the contents (a host re-reading its file after another process wrote it). */
+    load(snapshot) {
+        this.data = parseSnapshot(snapshot);
+    }
+    async changed() {
+        await this.onChange?.(this.data);
+    }
+    static upsert(list, item) {
+        const i = list.findIndex((x) => x.id === item.id);
+        if (i >= 0)
+            list[i] = item;
+        else
+            list.push(item);
+    }
+    static remove(list, id) {
+        const i = list.findIndex((x) => x.id === id);
+        if (i < 0)
+            return false;
+        list.splice(i, 1);
+        return true;
+    }
+    async putEpisode(episode) {
+        InMemoryExperienceStore.upsert(this.data.episodes, episode);
+        await this.changed();
+    }
+    async getEpisode(id) {
+        return this.data.episodes.find((e) => e.id === id);
+    }
+    async listEpisodes() {
+        return [...this.data.episodes].sort((a, b) => b.startedAt - a.startedAt).map(summary);
+    }
+    async deleteEpisode(id) {
+        const ok = InMemoryExperienceStore.remove(this.data.episodes, id);
+        delete this.data.learned[id];
+        if (ok)
+            await this.changed();
+        return ok;
+    }
+    async putSkill(skill) {
+        InMemoryExperienceStore.upsert(this.data.skills, skill);
+        await this.changed();
+    }
+    async getSkill(id) {
+        return this.data.skills.find((s) => s.id === id);
+    }
+    async listSkills() {
+        return [...this.data.skills].sort((a, b) => b.createdAt - a.createdAt);
+    }
+    async deleteSkill(id) {
+        const ok = InMemoryExperienceStore.remove(this.data.skills, id);
+        delete this.data.learned[id];
+        if (ok)
+            await this.changed();
+        return ok;
+    }
+    async putRun(run) {
+        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, step) {
+        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) {
+        return this.data.runs.find((r) => r.id === id);
+    }
+    async listRuns(limit) {
+        return this.data.runs.slice(0, Math.max(0, limit));
+    }
+    async recordAdaptation(adaptation) {
+        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() {
+        return structuredClone(this.data);
+    }
+    async clear() {
+        this.data = emptySnapshot();
+        await this.changed();
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/experience/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/experience/store.ts"],"names":[],"mappings":"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"}

package/dist/experience/trainOnce.d.ts

@@ -0,0 +1,18 @@
+import { type Episode, type Skill } 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 declare function trainOnce(episode: Episode, edits?: ReviewEdits, now?: number): Skill;
+/** `Invoice Amount (USD)` → `invoice_amount_usd`. Letters in any script survive. */
+export declare function slug(label: string): string;
+//# sourceMappingURL=trainOnce.d.ts.map

package/dist/experience/trainOnce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trainOnce.d.ts","sourceRoot":"","sources":["../../src/experience/trainOnce.ts"],"names":[],"mappings":"AASA,OAAO,EAAmB,KAAK,OAAO,EAAE,KAAK,KAAK,EAAqD,MAAM,YAAY,CAAC;AAE1H,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,GAAE,WAAgB,EAAE,GAAG,GAAE,MAAmB,GAAG,KAAK,CAwCpG;AAED,oFAAoF;AACpF,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ1C"}

package/dist/experience/trainOnce.js

@@ -0,0 +1,74 @@
+/**
+ * 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 } from './types.js';
+export function trainOnce(episode, edits = {}, now = Date.now()) {
+    const removed = new Set(edits.removed ?? []);
+    const fixed = new Set(edits.fixed ?? []);
+    const params = [];
+    const steps = [];
+    for (const rec of episode.steps) {
+        if (removed.has(rec.id))
+            continue;
+        const a = rec.action;
+        let action;
+        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) {
+    return label
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter(Boolean)
+        .join('_')
+        .slice(0, 40)
+        .replace(/_+$/, '');
+}
+function uniqueName(params, base) {
+    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;
+    }
+}
+//# sourceMappingURL=trainOnce.js.map

package/dist/experience/trainOnce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trainOnce.js","sourceRoot":"","sources":["../../src/experience/trainOnce.ts"],"names":[],"mappings":"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"}

package/dist/experience/types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * experience/types.ts — what Evermind has DONE, as opposed to what it knows.
+ *
+ * Facts live in `@seanhogg/builderforce-memory` (MemoryStore / EvermindCognition) and
+ * weights in the model; this is the third kind of learned item: experience.
+ *   - an **Episode** is one demonstration — a person doing a task in a program, recorded
+ *     as semantic steps (the UI element acted on and the value set, never raw keystrokes);
+ *   - a **Skill** is what Train Once compiles from an episode — a procedure that runs
+ *     again with new values, with approval gates on irreversible steps;
+ *   - a **Run** is one execution of a skill, with its step-by-step audit trail.
+ *
+ * Plain data, JSON-shaped (camelCase, actions tagged by `kind`), so any recorder — the
+ * native Windows UI Automation one in Synapse included — produces it and any runtime
+ * persists it. Timestamps are epoch milliseconds.
+ */
+/** A UI element, identified the way the platform's accessibility API sees it. */
+export interface ElementRef {
+    name: string;
+    automationId: string;
+    /** `Button`, `Edit`, `MenuItem`, … */
+    controlType: string;
+    className: string;
+    /** The top-level window the element sits in. */
+    windowTitle: string;
+    processName: string;
+    /** Where it was acted on, relative to the window's top-left — the replay fallback. */
+    relX: number;
+    relY: number;
+}
+/** One thing the person did. A secret field records that it was filled, never the value. */
+export type Action = {
+    kind: 'click';
+    target: ElementRef;
+} | {
+    kind: 'setValue';
+    target: ElementRef;
+    value: string;
+    secret?: boolean;
+} | {
+    kind: 'keys';
+    keys: string;
+    target?: ElementRef | null;
+};
+export interface RecordedStep {
+    id: string;
+    /** Milliseconds since the recording started. */
+    atMs: number;
+    action: Action;
+    /** Screenshot file name inside the episode's folder, if one was taken. */
+    screenshot?: string | null;
+}
+export interface Episode {
+    id: string;
+    name: string;
+    program: string;
+    args: string[];
+    startedAt: number;
+    endedAt?: number | null;
+    steps: RecordedStep[];
+}
+export interface EpisodeSummary {
+    id: string;
+    name: string;
+    program: string;
+    startedAt: number;
+    steps: number;
+}
+/** A value a skill asks for at run time. */
+export interface SkillParam {
+    /** Stable key, e.g. `amount`. */
+    name: string;
+    /** What the field was called where it was typed, e.g. `Amount`. */
+    label: string;
+    /** The value from the demonstration; never set for a secret. */
+    default?: string | null;
+    secret: boolean;
+}
+export type SkillValue = {
+    from: 'param';
+    name: string;
+} | {
+    from: 'literal';
+    text: string;
+};
+export type SkillAction = {
+    kind: 'click';
+    target: ElementRef;
+} | {
+    kind: 'setValue';
+    target: ElementRef;
+    value: SkillValue;
+} | {
+    kind: 'keys';
+    keys: string;
+    target?: ElementRef | null;
+};
+export interface SkillStep {
+    id: string;
+    action: SkillAction;
+    /** Pause and ask the person before this step. */
+    requiresApproval: boolean;
+    screenshot?: string | null;
+}
+/** When a skill runs by itself. Local time of day for `day`. */
+export type Schedule = {
+    every: 'minutes';
+    minutes: number;
+} | {
+    every: 'day';
+    hour: number;
+    minute: number;
+};
+/** A skill's routine: at most one per skill, so it lives on the skill. */
+export interface SkillRoutine {
+    schedule: Schedule;
+    /** Values for the non-secret parameters; secrets come from the host's vault. */
+    values: Record<string, string>;
+    enabled: boolean;
+    lastRunAt?: number | null;
+}
+export interface Skill {
+    id: string;
+    name: string;
+    program: string;
+    args: string[];
+    params: SkillParam[];
+    steps: SkillStep[];
+    sourceEpisode: string;
+    createdAt: number;
+    routine?: SkillRoutine | null;
+}
+export type RunStatus = 'running' | 'succeeded' | 'failed' | 'stopped' | 'denied';
+export type StepOutcome = 'ok' | 'fallback' | 'failed' | 'approved' | 'denied';
+/** One line of a run's audit trail. A step can have two (approved, then ok). */
+export interface RunStepLog {
+    idx: number;
+    stepId: string;
+    outcome: StepOutcome;
+    detail?: string | null;
+    at: number;
+}
+export interface Run {
+    id: string;
+    skillId: string;
+    skillName: string;
+    /** `manual` or `routine`. */
+    trigger: string;
+    status: RunStatus;
+    startedAt: number;
+    endedAt?: number | null;
+    error?: string | null;
+    steps: RunStepLog[];
+}
+/**
+ * One adaptation of the private model on experience: what it learned and how the fit
+ * went. Measured when the adaptation ran, never estimated afterwards.
+ */
+export interface Adaptation {
+    /** N of the `+expN` version this adaptation wrote. */
+    index: number;
+    version: string;
+    /** Episode and skill ids it learned. */
+    learned: string[];
+    passes: number;
+    /** Mean fit loss over the passes. */
+    loss: number;
+    at: number;
+}
+/** A short random id — unique enough for one person's store. */
+export declare function newExperienceId(): string;
+//# sourceMappingURL=types.d.ts.map