Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* The on-disk store for project-specific trained jev heads.
*
* Three states a decision can be in, and they are never collapsed:
*
* no candidate — nothing has been trained for this decision
* candidate, not adopted — trained and scored, awaiting an operator's call
* adopted — in use by `runJevDecision` for this decision
*
* TRAINING NEVER ADOPTS. A run writes a candidate and stops; adoption is a
* separate explicit action, and `adoptJevHead` refuses one whose measured
* accuracy does not beat BOTH baselines. That refusal is server-side on
* purpose: a UI that merely hides the button is a suggestion, and the number it
* hides the button over came from this machine's own private history.
*
* ## Layout, and why it is where it is
*
* data/jev/heads/<decisionId>.json adopted — BACKED UP
* data/jev/heads/<decisionId>.candidate.json awaiting a decision — BACKED UP
* data/jev/corpora/ regenerable — excluded
* data/jev/embeddings/ regenerable cache — excluded
*
* A head is NOT regenerable once the corpus behind it is gone: the forge moves
* on, issues close, and the exact query that produced a corpus a month ago
* returns something else today. It is also the only artifact here an operator
* made a decision about. Corpora and cached embeddings are bulk that re-derives
* — see `DEFAULT_EXCLUDES` in `services/backup.js` and `docs/BACKUP.md`.
*
* ## Privacy
*
* Every byte under `data/jev/` is a derived record of this install's private
* repository history and the operator's own judgement calls. It is
* MACHINE-LOCAL: never federated, never in a peer sync, never in a status or
* capability payload. The ADR
* [privacy records machine-local](../../docs/decisions/2026-08-08-privacy-records-machine-local.md)
* covers the path, and `sharing/jevNeverFederates.test.js` is the guard.
*/
import { notifyJevChanged } from './jevEvents.js';
import { readdir, unlink } from 'fs/promises';
import { join } from 'path';
import { atomicWrite, ensureDir, safeJSONParse, tryReadFile } from '../lib/fileUtils.js';
import { JEV_MODEL } from '../lib/jev.js';
import { JEV_DECISION_IDS } from '../lib/jevDecisions.js';
import { headAdoptionBlocker, isHeadCompatible, jevHeadFileName, jevHeadSlug, parseJevHead } from '../lib/jevHead.js';
import { jevHeadsDir } from '../lib/jevPaths.js';
const failure = (code) => ({ ok: false, code });
// Filenames come from `jevHeadFileName`, the one owner of the decision-id ↔
// slug mapping. Spelling `${decisionId}.json` here would be a fourth
// independent derivation of it.
const headPath = (decisionId, options) => join(jevHeadsDir(), jevHeadFileName(decisionId, options));
/**
* Which decisions have an applicable adopted head, by id.
*
* The VERDICT, not the head: the sole caller (`runJevDecision`) turns it into a
* slug-or-null and the weights are read by the sidecar from disk, so caching
* the parsed artifact would pin megabytes of float arrays in module scope for
* the process lifetime to answer a boolean. A `false` entry is cached too — a
* no-head install is the common case and must not re-stat per clause.
*
* Invalidated by every write path in this module, and by the test seam below.
*/
let adoptedCache = null;
/** Test seam, mirroring the cache resets on the sibling local-model services. */
export const resetJevHeadCache = () => { adoptedCache = null; };
async function readHeadFile(path) {
const content = await tryReadFile(path);
if (content === null) return failure('jev-head-not-found');
const parsed = safeJSONParse(content, null, { allowArray: false, logError: false });
if (parsed === null) return failure('jev-head-unreadable');
return parseJevHead(parsed);
}
/**
* The head slug `decisionId` is currently scored with, or null.
*
* The slug IS the decision id — `jevHeadSlug` owns that mapping — and the
* sidecar resolves it inside the heads directory. Returning it rather than the
* artifact is what lets a caller pass it straight through without ever holding
* the weights.
*
* Returns null — never a failure — for every reason a head might not apply:
* none adopted, an unreadable file, a head fit on a different encoder
* revision. Scoring falls back to the stock zero-shot classifier in all three
* cases, because that is what the install did before any head existed and it
* is always correct. An operator who wants to know WHY sees it in the panel,
* which calls `describeJevHeads` instead.
*/
export async function getAdoptedJevHeadSlug(decisionId) {
if (!JEV_DECISION_IDS.includes(decisionId)) return null;
if (adoptedCache?.has(decisionId)) return adoptedCache.get(decisionId);
const result = await readHeadFile(headPath(decisionId));
const slug = result.ok && isHeadCompatible(result.head, JEV_MODEL) ? jevHeadSlug(decisionId) : null;
adoptedCache ??= new Map();
adoptedCache.set(decisionId, slug);
return slug;
}
/**
* Operator-facing state for every decision that has an artifact on disk.
*
* Reports the metrics and the adoption blocker, never a corpus row, a premise
* or a path. `compatible: false` is stated rather than silently hidden: a head
* that stopped applying because the pinned model revision moved is a fact the
* operator needs, not an absence.
*/
export async function describeJevHeads() {
const dir = jevHeadsDir();
const entries = await readdir(dir).catch(() => []);
const rows = [];
for (const decisionId of JEV_DECISION_IDS) {
for (const candidate of [false, true]) {
const name = jevHeadFileName(decisionId, { candidate });
if (name === null || !entries.includes(name)) continue;
const result = await readHeadFile(join(dir, name));
if (!result.ok) {
rows.push({ decisionId, adopted: !candidate, ok: false, code: result.code });
continue;
}
const { head } = result;
// The blocker is computed ONCE and `beatsBaselines` derived from it:
// `headBeatsBaselines` re-validates the same metrics object, so asking
// both would parse it twice to answer one question two ways.
const blocker = headAdoptionBlocker(head.metrics);
rows.push({
decisionId,
adopted: !candidate,
ok: true,
architecture: head.architecture,
metrics: head.metrics,
corpusHash: head.corpusHash,
corpusSources: head.corpusSources,
trainedAt: head.trainedAt,
baseRevision: head.baseModel.revision,
compatible: isHeadCompatible(head, JEV_MODEL),
beatsBaselines: blocker === null,
blocker,
});
}
}
return { heads: rows };
}
/** Persist a freshly trained head as a CANDIDATE. Never adopts. */
export async function saveCandidateJevHead(decisionId, raw) {
if (!JEV_DECISION_IDS.includes(decisionId)) return failure('jev-head-invalid');
const parsed = parseJevHead(raw);
if (!parsed.ok) return parsed;
if (parsed.head.decisionId !== decisionId) return failure('jev-head-invalid');
if (!isHeadCompatible(parsed.head, JEV_MODEL)) return failure('jev-head-revision-mismatch');
await ensureDir(jevHeadsDir());
await atomicWrite(headPath(decisionId, { candidate: true }), parsed.head);
notifyJevChanged('heads');
return { ok: true, head: parsed.head };
}
/**
* Promote the candidate for `decisionId` into the adopted slot.
*
* THE GATE LIVES HERE. A head that does not beat both the stock zero-shot
* classifier and the majority class on the held-out gold set cannot be adopted
* through any surface, and the refusal names which baseline it lost to.
*/
export async function adoptJevHead(decisionId) {
if (!JEV_DECISION_IDS.includes(decisionId)) return failure('jev-head-invalid');
const result = await readHeadFile(headPath(decisionId, { candidate: true }));
if (!result.ok) return result;
const { head } = result;
if (!isHeadCompatible(head, JEV_MODEL)) return failure('jev-head-revision-mismatch');
const blocker = headAdoptionBlocker(head.metrics);
if (blocker) return failure(blocker);
await ensureDir(jevHeadsDir());
await atomicWrite(headPath(decisionId), head);
// The candidate is consumed, not kept: leaving a byte-identical copy beside
// the adopted head would make the panel show the same artifact twice, in two
// states, with no way to tell which one is answering.
await unlink(headPath(decisionId, { candidate: true })).catch(() => null);
resetJevHeadCache();
notifyJevChanged('heads');
return { ok: true, head };
}
/**
* Discard an artifact.
*
* Discarding the ADOPTED head returns the decision to the stock zero-shot
* classifier immediately — which is the state every install ships in, so there
* is nothing to restore and nothing to warn about.
*/
export async function discardJevHead(decisionId, { candidate = true } = {}) {
if (!JEV_DECISION_IDS.includes(decisionId)) return failure('jev-head-invalid');
const removed = await unlink(headPath(decisionId, { candidate })).then(() => true, () => false);
resetJevHeadCache();
if (removed) notifyJevChanged('heads');
return { ok: true, removed };
}