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 provider-graph orchestration contract (#6367): projection ordering,
* re-entrancy, and the revision gate on link/unlink.
*
* The reconciliation POLICY is pinned purely in
* `server/lib/providerGraphRecords.test.js` and the row constraints in
* `providerGraphStore.db.test.js`. What is only observable HERE is sequencing:
* that a projection stages before it writes and acknowledges only after, that a
* projection's own provider-file write cannot recurse back into a reconcile
* pass, and that a link refuses stale or blocked state before it touches a row.
*
* Fixtures are synthetic. Nothing here is read out of a running install.
*/
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
const store = {
readGraph: vi.fn(),
applyServiceColumnBackfill: vi.fn().mockResolvedValue(undefined),
applyReconciliation: vi.fn().mockResolvedValue(undefined),
commitPendingProjection: vi.fn().mockResolvedValue(undefined),
acknowledgeProjection: vi.fn().mockResolvedValue(undefined),
relinkBinding: vi.fn().mockResolvedValue(undefined),
deleteConnection: vi.fn(),
detachBindingToConnection: vi.fn().mockResolvedValue(undefined),
mergeServiceInstances: vi.fn().mockResolvedValue(undefined),
saveConnectionSettings: vi.fn().mockResolvedValue(2),
};
vi.mock('./providerGraphStore.js', () => store);
const providers = {
getAllProviders: vi.fn(),
applyProviderPatches: vi.fn(),
};
vi.mock('../lib/aiToolkitState.js', () => ({
requireToolkit: () => ({ services: { providers } }),
}));
// `updateConnectionSettings` re-derives every DERIVED preset on the row it
// just saved, which reads the bootstrap-apps table — kept doubled and empty
// so this file never reaches `settings.js`'s real file store.
vi.mock('./credentialBootstrapApps.js', () => ({ listCredentialBootstraps: vi.fn().mockResolvedValue({}) }));
const graph = await import('./providerGraph.js');
const CONN_A = '11111111-1111-4111-8111-111111111111';
const CONN_B = '22222222-2222-4222-8222-222222222222';
const BINDING = '33333333-3333-4333-8333-333333333333';
const connection = (id, baseUrl, slug) => ({
id,
revision: 1,
kind: 'ollama',
label: 'Example daemon',
transports: { anthropic: { baseUrl } },
credentials: { ANTHROPIC_AUTH_TOKEN: `token-for-${id}` },
catalog: { state: 'known', models: ['example-model'] },
// Named service instances (#7563), so the record below can be a derived
// preset (#7565) declaring the one it sits on.
slug, definitionId: 'ollama', plan: 'local', enabled: true, credentialVia: 'stored',
});
const CLAUDE = {
id: 'claude-ollama',
name: 'Claude',
type: 'cli',
command: 'claude',
// Makes the record's connection kind 'ollama', matching the fixture rows.
ollamaBacked: true,
enabled: true,
models: ['example-model'],
// Matches connection CONN_A exactly, so the baseline is a settled graph.
envVars: { ANTHROPIC_BASE_URL: `http://127.0.0.1:11434`, ANTHROPIC_AUTH_TOKEN: `token-for-${CONN_A}` },
secretEnvVars: ['ANTHROPIC_AUTH_TOKEN'],
// Already a derived preset on CONN_A, so a settled pass has nothing to stamp.
harnessId: 'claude', method: 'cli', serviceId: 'ollama',
};
const graphFixture = () => ({
connections: [connection(CONN_A, 'http://127.0.0.1:11434', 'ollama'), connection(CONN_B, 'http://127.0.0.1:12345', 'ollama-2')],
bindings: [{
id: BINDING, revision: 1, connectionId: CONN_A, harnessId: 'claude',
variantKey: 'default', label: 'Claude', enabled: true, selectedModels: ['example-model'],
}],
routes: [{
providerId: 'claude-ollama', bindingId: BINDING, mode: 'cli',
modelMap: { 'example-model': 'example-model' },
projected: { fields: {}, envVars: { ...CLAUDE.envVars }, hasEnvVars: true },
pending: null, pendingRevision: null,
}],
});
beforeEach(async () => {
vi.clearAllMocks();
graph.resetProviderGraphState();
store.readGraph.mockResolvedValue(graphFixture());
providers.getAllProviders.mockResolvedValue({
activeProvider: 'claude-ollama',
providers: [structuredClone(CLAUDE)],
});
providers.applyProviderPatches.mockImplementation(async (patches) => Object.keys(patches));
vi.spyOn(console, 'log').mockImplementation(() => {});
vi.spyOn(console, 'error').mockImplementation(() => {});
});
afterEach(() => vi.restoreAllMocks());
describe('before the database phase enables the graph', () => {
it('a legacy provider save does nothing at all', async () => {
expect(await graph.onProvidersSaved()).toBeNull();
expect(store.readGraph).not.toHaveBeenCalled();
});
it('the management read answers unavailable rather than an empty graph', async () => {
await expect(graph.getManagementGraph()).rejects.toMatchObject({ code: 'PROVIDER_GRAPH_UNAVAILABLE' });
});
it('a link is refused rather than silently queued', async () => {
await expect(graph.linkBinding({ bindingId: BINDING, targetConnectionId: CONN_B }))
.rejects.toMatchObject({ code: 'PROVIDER_GRAPH_UNAVAILABLE' });
expect(store.relinkBinding).not.toHaveBeenCalled();
});
});
describe('reconciliation', () => {
it('is a no-op pass when the file and the graph already agree', async () => {
await graph.initProviderGraph();
expect(store.applyReconciliation).not.toHaveBeenCalled();
expect(providers.applyProviderPatches).not.toHaveBeenCalled();
});
// #7565: the preset backfill rides the pass. A routed legacy record whose
// re-derivation is a fixpoint is stamped with ONLY the structural keys; the
// stamped record is skipped on the next pass.
it('stamps a routed legacy record as a derived preset, additively, once', async () => {
const { harnessId, method, serviceId, ...legacy } = structuredClone(CLAUDE);
providers.getAllProviders.mockResolvedValue({ activeProvider: 'claude-ollama', providers: [legacy] });
await graph.initProviderGraph();
expect(providers.applyProviderPatches).toHaveBeenCalledTimes(1);
expect(providers.applyProviderPatches).toHaveBeenCalledWith({ 'claude-ollama': { harnessId, method, serviceId } });
// Its own write fires the save hook; the latch keeps that from re-entering.
expect(store.readGraph).toHaveBeenCalledTimes(1);
providers.getAllProviders.mockResolvedValue({ activeProvider: 'claude-ollama', providers: [structuredClone(CLAUDE)] });
providers.applyProviderPatches.mockClear();
await graph.onProvidersSaved();
expect(providers.applyProviderPatches).not.toHaveBeenCalled();
});
it('leaves a routed record legacy when re-deriving it would change how it runs', async () => {
// A path-configured binary is a deliberate choice materialization would overwrite.
const { harnessId, method, serviceId, ...legacy } = structuredClone(CLAUDE);
providers.getAllProviders.mockResolvedValue({ activeProvider: 'claude-ollama', providers: [{ ...legacy, command: '/opt/bin/claude' }] });
await graph.initProviderGraph();
expect(providers.applyProviderPatches).not.toHaveBeenCalled();
});
it('retries an interrupted projection, then acknowledges it in the same plan', async () => {
const fixture = graphFixture();
fixture.routes[0].pending = {
fields: {},
envVars: { ...CLAUDE.envVars, ANTHROPIC_BASE_URL: 'http://127.0.0.1:12345' },
hasEnvVars: true,
};
store.readGraph.mockResolvedValue(fixture);
await graph.initProviderGraph();
expect(providers.applyProviderPatches).toHaveBeenCalledWith({
'claude-ollama': { envVars: { ...CLAUDE.envVars, ANTHROPIC_BASE_URL: 'http://127.0.0.1:12345' } },
});
// Acknowledged only because the retry write succeeded.
expect(store.applyReconciliation.mock.calls[0][0].acknowledgements)
.toEqual([{ providerId: 'claude-ollama' }]);
});
it('does not recurse when its own retry write fires the legacy save hook', async () => {
// The retry goes through the toolkit, which calls onProvidersSaved — the
// latch is the only thing between that and an infinite reconcile loop.
const fixture = graphFixture();
fixture.routes[0].pending = { fields: {}, envVars: { ANTHROPIC_BASE_URL: 'http://127.0.0.1:12345' }, hasEnvVars: true };
store.readGraph.mockResolvedValue(fixture);
providers.applyProviderPatches.mockImplementation(async (patches) => {
await graph.onProvidersSaved();
return Object.keys(patches);
});
await graph.initProviderGraph();
expect(store.readGraph).toHaveBeenCalledTimes(1);
});
it('leaves an externally changed route untouched and logs it', async () => {
const fixture = graphFixture();
fixture.routes[0].pending = { fields: {}, envVars: { ANTHROPIC_BASE_URL: 'http://127.0.0.1:12345' }, hasEnvVars: true };
store.readGraph.mockResolvedValue(fixture);
providers.getAllProviders.mockResolvedValue({
activeProvider: 'claude-ollama',
// A third value: neither the projected snapshot nor the pending one.
providers: [{ ...structuredClone(CLAUDE), envVars: { ANTHROPIC_BASE_URL: 'http://127.0.0.1:7777' } }],
});
await graph.initProviderGraph();
expect(providers.applyProviderPatches).not.toHaveBeenCalled();
expect(console.error).toHaveBeenCalledWith(expect.stringContaining('changed outside the graph'));
});
it('a legacy save runs one pass once the graph is enabled', async () => {
await graph.initProviderGraph();
store.readGraph.mockClear();
await graph.onProvidersSaved();
expect(store.readGraph).toHaveBeenCalledTimes(1);
});
});
describe('connection settings keep the preset-conversion cache live (#8159)', () => {
it('updates presetSkipReason for this connection\'s legacy routes on the SAME write, not the next reconcile pass', async () => {
// The connection's base URL does not yet match the routed legacy
// record's own ANTHROPIC_BASE_URL, so the boot pass leaves it legacy —
// re-deriving it would rewrite the env var it already carries.
const fixture = graphFixture();
fixture.connections[0] = connection(CONN_A, 'http://127.0.0.1:19999', 'ollama');
store.readGraph.mockResolvedValue(fixture);
const { harnessId, method, serviceId, ...legacy } = structuredClone(CLAUDE);
providers.getAllProviders.mockResolvedValue({ activeProvider: 'claude-ollama', providers: [legacy] });
await graph.initProviderGraph();
expect(graph.presetSkipReason('claude-ollama')).toMatch(/^drift:/);
// Fixing the connection's own base URL makes re-deriving the record a
// fixpoint. A connection-settings edit never writes `providers.json`, so
// `onProvidersSaved` never fires and no reconcile pass runs — the cache
// must still answer correctly right after THIS write.
await graph.updateConnectionSettings({
connectionId: CONN_A, expectedRevision: 1, transports: { anthropic: { baseUrl: 'http://127.0.0.1:11434' } },
});
expect(graph.presetSkipReason('claude-ollama')).toBeNull();
// And the reverse: moving the connection back off the record's own
// ANTHROPIC_BASE_URL makes it drift again, live, the same way.
await graph.updateConnectionSettings({
connectionId: CONN_A, expectedRevision: 1, transports: { anthropic: { baseUrl: 'http://127.0.0.1:19999' } },
});
expect(graph.presetSkipReason('claude-ollama')).toMatch(/^drift:/);
});
it('leaves an unrelated connection\'s cached verdict untouched', async () => {
await graph.initProviderGraph();
expect(graph.presetSkipReason('claude-ollama')).toBeNull();
// CONN_B carries no routes in the fixture, so this is a no-op scan, not a
// crash on an empty route list.
await expect(graph.updateConnectionSettings({
connectionId: CONN_B, expectedRevision: 1, label: 'Renamed',
})).resolves.toMatchObject({ connectionId: CONN_B });
expect(graph.presetSkipReason('claude-ollama')).toBeNull();
});
});
describe('linking', () => {
beforeEach(() => graph.initProviderGraph());
it('previews the difference without writing anything', async () => {
const preview = await graph.previewBindingLink({ bindingId: BINDING, targetConnectionId: CONN_B });
expect(preview.affectedRouteIds).toEqual(['claude-ollama']);
expect(preview.revisions).toEqual({ binding: 1, sourceConnection: 1, targetConnection: 1 });
expect(preview.requiresConfirmation).toBe(true);
// Secrets never reach a preview; the browser learns only THAT they differ.
expect(JSON.stringify(preview)).not.toContain('token-for-');
expect(store.relinkBinding).not.toHaveBeenCalled();
});
it('stages the projection, writes the file, and acknowledges only then', async () => {
const order = [];
store.commitPendingProjection.mockImplementation(async () => { order.push('stage'); });
providers.applyProviderPatches.mockImplementation(async (patches) => { order.push('write'); return Object.keys(patches); });
store.acknowledgeProjection.mockImplementation(async () => { order.push('acknowledge'); });
const result = await graph.linkBinding({
bindingId: BINDING, targetConnectionId: CONN_B,
expectedRevisions: { binding: 1, sourceConnection: 1, targetConnection: 1 },
});
expect(order.slice(0, 3)).toEqual(['stage', 'write', 'acknowledge']);
expect(result).toEqual({ bindingId: BINDING, connectionId: CONN_B, affectedRouteIds: ['claude-ollama'] });
// The route keeps its executable id; only the backend it reaches moves.
expect(providers.applyProviderPatches.mock.calls[0][0]['claude-ollama'].envVars).toEqual({
ANTHROPIC_BASE_URL: 'http://127.0.0.1:12345',
ANTHROPIC_AUTH_TOKEN: 'token-for-22222222-2222-4222-8222-222222222222',
});
// The derived preset on the moved binding is re-derived from the instance it landed on (#7565).
expect(providers.applyProviderPatches.mock.calls[1][0]['claude-ollama']).toMatchObject({ serviceId: 'ollama-2' });
});
it.each([
['binding', { binding: 9, sourceConnection: 1, targetConnection: 1 }],
['source connection', { binding: 1, sourceConnection: 9, targetConnection: 1 }],
['target connection', { binding: 1, sourceConnection: 1, targetConnection: 9 }],
])('refuses a stale %s revision before any row is touched', async (_label, expectedRevisions) => {
await expect(graph.linkBinding({ bindingId: BINDING, targetConnectionId: CONN_B, expectedRevisions }))
.rejects.toMatchObject({ status: 409, code: 'PROVIDER_GRAPH_STALE_REVISION' });
expect(store.relinkBinding).not.toHaveBeenCalled();
});
it('refuses a binding whose projection is still unsettled', async () => {
const fixture = graphFixture();
fixture.routes[0].pending = { fields: {}, envVars: {}, hasEnvVars: true };
store.readGraph.mockResolvedValue(fixture);
await expect(graph.linkBinding({ bindingId: BINDING, targetConnectionId: CONN_B }))
.rejects.toMatchObject({ code: 'PROVIDER_GRAPH_BINDING_BLOCKED' });
});
it('allocates a distinct variant when the target already has this harness on default', async () => {
const fixture = graphFixture();
fixture.bindings.push({
id: '44444444-4444-4444-8444-444444444444', revision: 1, connectionId: CONN_B,
harnessId: 'claude', variantKey: 'default', label: 'Other Claude', enabled: true, selectedModels: [],
});
store.readGraph.mockResolvedValue(fixture);
const preview = await graph.previewBindingLink({ bindingId: BINDING, targetConnectionId: CONN_B });
expect(preview.variantKey).toBe(`variant:${BINDING}`);
});
it('refuses a link a binding already has', async () => {
await expect(graph.linkBinding({ bindingId: BINDING, targetConnectionId: CONN_A }))
.rejects.toMatchObject({ code: 'PROVIDER_GRAPH_ALREADY_LINKED' });
});
});
describe('unlinking', () => {
beforeEach(() => graph.initProviderGraph());
it('clones the shared connection under a new id and rewrites no route', async () => {
const result = await graph.unlinkBinding({ bindingId: BINDING, expectedRevisions: { binding: 1 } });
expect(result.bindingId).toBe(BINDING);
expect(result.connectionId).not.toBe(CONN_A);
const [{ connection: clone }] = store.detachBindingToConnection.mock.calls[0];
expect(clone.transports).toEqual({ anthropic: { baseUrl: 'http://127.0.0.1:11434' } });
expect(clone.credentials).toEqual({ ANTHROPIC_AUTH_TOKEN: `token-for-${CONN_A}` });
// Nothing about execution changes: the one write re-derives the preset from
// the clone (#7565), which re-addresses it and moves no executable value.
expect(providers.applyProviderPatches).toHaveBeenCalledTimes(1);
const [patches] = providers.applyProviderPatches.mock.calls[0];
expect(patches['claude-ollama']).toMatchObject({ serviceId: clone.slug });
// The env and program are the same on the clone; only empty normalizations ride along.
for (const key of ['envVars', 'command', 'models']) expect(patches['claude-ollama']).not.toHaveProperty(key);
expect(patches['claude-ollama'].apiKey ?? '').toBe('');
expect(patches['claude-ollama'].endpoint ?? null).toBeNull();
expect(clone.slug).toBe('ollama-3');
});
it('refuses an unknown binding', async () => {
await expect(graph.unlinkBinding({ bindingId: CONN_B })).rejects.toMatchObject({ code: 'BINDING_NOT_FOUND' });
});
});
describe('deleting an emptied connection', () => {
beforeEach(() => graph.initProviderGraph());
it('removes a connection nothing binds', async () => {
store.deleteConnection.mockResolvedValue({ deleted: true });
expect(await graph.removeConnection(CONN_B)).toEqual({ deleted: true });
});
it('refuses while a binding still names it, rather than orphaning the binding', async () => {
store.deleteConnection.mockResolvedValue({ deleted: false, reason: 'referenced-by-binding' });
await expect(graph.removeConnection(CONN_A))
.rejects.toMatchObject({ status: 409, code: 'PROVIDER_GRAPH_CONNECTION_IN_USE' });
});
});
describe('service-instance naming (#7563)', () => {
it('gives an unlinked clone the next free slug rather than copying the source\'s', async () => {
const fixture = graphFixture();
fixture.connections[0].slug = 'ollama';
fixture.connections[0].definitionId = 'ollama';
fixture.connections[1].slug = 'ollama-2';
store.readGraph.mockResolvedValue(fixture);
await graph.initProviderGraph();
await graph.unlinkBinding({ bindingId: BINDING });
const [[{ connection }]] = store.detachBindingToConnection.mock.calls;
expect(connection.slug).toBe('ollama-3');
expect(connection.id).not.toBe(CONN_A);
expect(connection.definitionId).toBe('ollama');
});
it('names a boot-imported fragment before it is written, and backfills unnamed rows after', async () => {
const fixture = graphFixture();
// CONN_A predates the columns; CONN_B is already named.
for (const key of ['slug', 'definitionId', 'plan', 'enabled', 'credentialVia']) delete fixture.connections[0][key];
fixture.connections[1].slug = 'ollama';
store.readGraph.mockResolvedValue(fixture);
// The second record is a LEGACY one the graph has never routed: it declares
// no service, so it imports as its own fragment rather than onto a row.
const { harnessId, method, serviceId, ...legacy } = structuredClone(CLAUDE);
providers.getAllProviders.mockResolvedValue({
activeProvider: 'claude-ollama',
providers: [structuredClone(CLAUDE), { ...legacy, id: 'claude-other', envVars: { ANTHROPIC_BASE_URL: 'http://127.0.0.1:5555', ANTHROPIC_AUTH_TOKEN: 'other' } }],
});
await graph.initProviderGraph();
const [plan] = store.applyReconciliation.mock.calls[0];
expect(plan.imports.connections[0]).toMatchObject({ kind: 'ollama', slug: 'ollama-2', definitionId: 'ollama', plan: 'local' });
expect(store.applyServiceColumnBackfill).toHaveBeenCalledWith([{ id: CONN_A, slug: 'ollama-3', definitionId: 'ollama', plan: 'local' }]);
});
});