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 persisted half of observation-first discovery (#7457). What these pin is
* the contract a mind tool depends on across a WAKE BOUNDARY, which is the one
* thing the pure builder beside this cannot prove: the visit marker survives to
* the next observation, the shapes this shell hands the builder are the ones it
* actually documents, a section that failed to collect degrades instead of
* failing the whole tour, and an unreadable marker file never silently reports
* a settled world as brand new.
*/
import { afterAll, beforeEach, describe, expect, it as vitestIt, vi } from 'vitest';
import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy, ownTestBodies } from '../lib/mockPathsDataRoot.js';
import { eidoversePeerId } from '../lib/eidoverseWorldSignals.js';
const owned = ownTestBodies(vitestIt);
const it = owned.it;
const dataRoot = () => lazyTempDataRoot('portos-eidoverse-observation-');
let beforeMarkerWrite = async () => {};
vi.mock('../lib/fileUtils.js', async (importOriginal) => {
const actual = await importOriginal();
return makePathsProxy(actual, { dataRoot, overrides: {
atomicWrite: async (...args) => {
await beforeMarkerWrite();
return actual.atomicWrite(...args);
},
} });
});
const collectSources = vi.fn();
const listFoundations = vi.fn();
const listControllers = vi.fn();
const readRecipe = vi.fn();
const listDestinations = vi.fn();
vi.mock('./eidoverseWorldSources.js', () => ({ collectEidoverseWorldSources: (...args) => collectSources(...args) }));
vi.mock('./eidoverseFoundationLedger.js', () => ({ listEidoverseFoundations: (...args) => listFoundations(...args) }));
vi.mock('./eidoverseControllerRuntime.js', () => ({ listEidoverseControllers: (...args) => listControllers(...args) }));
vi.mock('./eidoverseWorld.js', () => ({ readEidoverseWorldRecipe: (...args) => readRecipe(...args) }));
vi.mock('./eidoverseTravel.js', () => ({ listEidoverseDestinations: (...args) => listDestinations(...args) }));
const { observeEidoverseWorld } = await import('./eidoverseObservationLedger.js');
const PEER_ALPHA = 'instance-alpha-0000';
const ALPHA_ID = eidoversePeerId({ instanceId: PEER_ALPHA });
const markerFile = () => join(dataRoot(), 'eidoverse', 'observation.json');
const writeRawMarker = (contents) => {
mkdirSync(dirname(markerFile()), { recursive: true });
writeFileSync(markerFile(), contents);
};
const inherited = (id) => ({
id,
kind: 'affordance',
title: 'Inherited build',
layer: 'baseline',
inheritance: {
type: 'inherited-from',
originInstanceId: PEER_ALPHA,
sourceInstanceId: PEER_ALPHA,
foundationId: 'origin-foundation',
fingerprint: 'b'.repeat(64),
packagedAt: '2026-09-16T11:00:00.000Z',
inheritedAt: '2026-09-16T11:00:00.000Z',
},
});
const peerSignal = () => ({
id: ALPHA_ID, label: 'Federated peer', status: 'active', enabled: true, fullSync: true, travelAvailable: true,
});
beforeEach(async () => {
await owned.drain();
beforeMarkerWrite = async () => {};
rmSync(dataRoot(), { recursive: true, force: true });
collectSources.mockReset().mockResolvedValue({ peers: [peerSignal()], agents: [], tasks: [] });
listFoundations.mockReset().mockResolvedValue({ counts: { vernacular: 0, baseline: 1, candidates: 0, inherited: 1 }, foundations: [inherited('peer:alpha:one')] });
listControllers.mockReset().mockResolvedValue({ counts: { total: 0, armed: 0, delivering: 0 }, installs: [] });
readRecipe.mockReset().mockResolvedValue(null);
listDestinations.mockReset().mockResolvedValue({ destinations: [{ peerId: ALPHA_ID, label: 'Peer' }] });
});
afterAll(async () => {
await owned.drain();
cleanupTempDataRoots();
});
describe('the Eidoverse observation marker', () => {
it('carries what is new across the wake boundary the marker exists for', async () => {
const first = await observeEidoverseWorld({ now: () => '2026-09-16T12:00:00.000Z' });
expect(first.changes.firstObservation).toBe(true);
listFoundations.mockResolvedValue({
counts: { vernacular: 0, baseline: 2, candidates: 0, inherited: 2 },
foundations: [inherited('peer:alpha:one'), inherited('peer:alpha:two')],
});
// A different process would re-read the file; the point is that the second
// observation's diff comes from DISK, not from anything held in memory.
const second = await observeEidoverseWorld({ now: () => '2026-09-16T13:00:00.000Z' });
expect(second.changes.firstObservation).toBe(false);
expect(second.changes.since).toBe('2026-09-16T12:00:00.000Z');
expect(second.changes.newFoundations).toEqual(['peer:alpha:two']);
});
it('leaves the marker untouched when asked to look without stamping', async () => {
await observeEidoverseWorld({ now: () => '2026-09-16T12:00:00.000Z' });
listFoundations.mockResolvedValue({
counts: { vernacular: 0, baseline: 2, candidates: 0, inherited: 2 },
foundations: [inherited('peer:alpha:one'), inherited('peer:alpha:two')],
});
const peek = await observeEidoverseWorld({ commit: false, now: () => '2026-09-16T13:00:00.000Z' });
expect(peek.changes.newFoundations).toEqual(['peer:alpha:two']);
// Still new on the next real observation, because the peek never stamped.
const after = await observeEidoverseWorld({ now: () => '2026-09-16T14:00:00.000Z' });
expect(after.changes.since).toBe('2026-09-16T12:00:00.000Z');
expect(after.changes.newFoundations).toEqual(['peer:alpha:two']);
});
it('refuses to treat an unreadable marker file as never-observed', async () => {
writeRawMarker('{ this is not json');
// Reading it as "never observed" would be the destructive failure: the very
// next write would replace a real marker with a fresh one and every
// foundation on the install would report as new exactly once.
await expect(observeEidoverseWorld()).rejects.toThrow();
});
it('degrades a marker written by a newer PortOS to one honest first observation', async () => {
writeRawMarker(JSON.stringify({
schemaVersion: 99,
marker: { schemaVersion: 99, observedAt: '2026-09-16T10:00:00.000Z', foundationIds: ['peer:alpha:one'], peerIds: [ALPHA_ID], placeStatus: {}, attentionControllerIds: [] },
}));
const observed = await observeEidoverseWorld({ now: () => '2026-09-16T12:00:00.000Z' });
expect(observed.changes.firstObservation).toBe(true);
// And it converges: the rewritten marker is one this build can diff.
const next = await observeEidoverseWorld({ now: () => '2026-09-16T13:00:00.000Z' });
expect(next.changes.firstObservation).toBe(false);
expect(next.changes.since).toBe('2026-09-16T12:00:00.000Z');
});
it('still tours the world when a single collection fails', async () => {
listControllers.mockRejectedValue(new Error('controller runtime unavailable'));
listFoundations.mockRejectedValue(new Error('ledger unavailable'));
const observed = await observeEidoverseWorld({ now: () => '2026-09-16T12:00:00.000Z' });
// A mind that cannot read its controllers should still get its districts.
expect(observed.controllers.counts).toBeNull();
expect(observed.foundations.counts).toBeNull();
expect(observed.places).toHaveLength(8);
expect(observed.peers.map((peer) => peer.peerId)).toEqual([ALPHA_ID]);
});
it('serializes concurrent observations so one marker write cannot lose the other', async ({ signal }) => {
const writing = Promise.withResolvers();
const release = Promise.withResolvers();
const collected = Promise.withResolvers();
const observations = [];
const cancel = () => { writing.resolve(); collected.resolve(); release.resolve(); };
signal.addEventListener('abort', cancel, { once: true });
if (signal.aborted) cancel();
beforeMarkerWrite = () => { writing.resolve(); return release.promise; };
try {
observations.push(observeEidoverseWorld({ now: () => '2026-09-16T12:00:00.000Z' }));
await Promise.race([writing.promise, observations[0]]);
if (signal.aborted) return;
// Overlap the persistence boundary, after the first call's imports have
// settled. Vitest's manual mock callstack cannot isolate parallel dynamic
// imports: the second call otherwise reaches real host probes (#13477).
collectSources.mockImplementation(async () => {
collected.resolve();
return { peers: [peerSignal()], agents: [], tasks: [] };
});
observations.push(observeEidoverseWorld({ now: () => '2026-09-16T12:00:01.000Z' }));
await Promise.race([collected.promise, observations[1]]);
release.resolve();
const results = await Promise.all(observations);
expect(collectSources).toHaveBeenCalledTimes(2);
expect(listFoundations).toHaveBeenCalledTimes(2);
expect(listControllers).toHaveBeenCalledTimes(2);
expect(readRecipe).toHaveBeenCalledTimes(2);
expect(results.filter((entry) => entry.changes.firstObservation)).toHaveLength(1);
expect(results.filter((entry) => !entry.changes.firstObservation)).toHaveLength(1);
} finally {
release.resolve();
await Promise.allSettled(observations);
signal.removeEventListener('abort', cancel);
}
});
});
describe('the shapes the observation shell hands the report builder', () => {
it('summarizes a RAW controller record before reporting its health', async () => {
// `listEidoverseControllers()` returns raw records, whose tick outcome lives
// in `lastOutcome`. The builder reads the FLATTENED `lastTickOk`, so handing
// it a raw record would report every controller as never-ticked and
// silently disable the failed-tick filter the Maintain playbook relies on.
listControllers.mockResolvedValue({
counts: { total: 2, armed: 1, delivering: 0 },
installs: [
{
id: 'just-failed',
controllerId: 'lanternKeeper',
armed: true,
consecutiveFailures: 0,
lastOutcome: { at: '2026-09-16T11:59:00.000Z', tick: 4, ok: false, reason: 'entity missing' },
},
{
id: 'never-ticked',
controllerId: 'ambientBeacon',
armed: true,
consecutiveFailures: 0,
},
],
});
const observed = await observeEidoverseWorld({ now: () => '2026-09-16T12:00:00.000Z' });
expect(observed.controllers.needsAttention).toEqual([expect.objectContaining({
id: 'just-failed',
lastTickOk: false,
lastTickReason: 'entity missing',
})]);
// Never ticked is not an alarm, and must stay distinguishable from failed.
expect(observed.controllers.needsAttention.map((entry) => entry.id)).not.toContain('never-ticked');
});
it('names the districts the install\'s own recipe renders', async () => {
const observed = await observeEidoverseWorld({ now: () => '2026-09-16T12:00:00.000Z' });
const labels = observed.places.map((place) => place.label);
// Resolved from the stored recipe, so this is the shipped V3 design rather
// than the retired V2 names the world stopped rendering.
expect(labels).toContain('Federation Terminal');
expect(labels).not.toContain('Federation Harbor');
});
it('does not re-probe peer capabilities that the source collection already resolved', async () => {
await observeEidoverseWorld({ now: () => '2026-09-16T12:00:00.000Z' });
// `collectEidoverseWorldSources` already calls it and folds the answer into
// `peers[].travelAvailable`; asking again costs one outbound /capabilities
// request per online peer for information already in hand.
expect(listDestinations).not.toHaveBeenCalled();
});
});