Skip to content

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

fix: retain legacy browser activity keys during upgrades (#11150)

Adam Eivy3c48b99ecb86
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index b6336b9fd4..335680561d 100644
--- a/docs/STORAGE.md
+++ b/docs/STORAGE.md
@@ -989,3 +989,17 @@ No age-based expiration is used. Refused/interrupted maintenance work stops unti
explicit resume acknowledges the outcome. A legacy Deep queued request with no
queue, task, or receipt likewise stops for explicit resume. Repeating resume on
an already-running maintenance run does not dispatch or re-evaluate it.
+
+### Browser message cache identity
+
+The existing `data/messages/cache/<account-id>.json` remains machine-local
+`ephemeral-file` provider cache; timeline events remain PostgreSQL records.
+Browser rows and expanded members carry additive identity fields, with a stable
+provider child ID when available and a conservative per-row member discriminator
+otherwise. `activityIdentity` retains an already-established timeline key when a
+legacy summary is upgraded, so the existing event ID and cache evaluation survive.
+Migration 426 pins only unique legacy keys in existing input caches, atomically,
+without a seed or creating missing caches; sync/refresh also reconcile lazily for
+older cache writers. Ambiguous legacy matches are preserved rather than guessed.
+These fields do not add federation or a new store; older cache records remain
+readable and Gmail/API IDs retain their existing meaning.
diff --git a/scripts/migrations/426-message-browser-identity.js b/scripts/migrations/426-message-browser-identity.js
new file mode 100644
index 0000000000..06f07d9218
--- /dev/null
+++ b/scripts/migrations/426-message-browser-identity.js
@@ -0,0 +1,30 @@
+/** Pin legacy timeline identities before browser summaries adopt stable row IDs.
+ * Input-gated, offline, and additive: no cache or seed is created. */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { retainLegacyActivityIdentities } from '../../server/lib/messageBrowserIdentity.js';
+import { writeJsonAtomic } from './_lib.js';
+
+export default {
+ async up({ rootDir }) {
+ const directory = join(rootDir, 'data', 'messages', 'cache');
+ const files = await readdir(directory).catch(error => {
+ if (error.code === 'ENOENT') return [];
+ throw error;
+ });
+ let updated = 0;
+ for (const name of files.filter(name => /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}\.json$/i.test(name))) {
+ const path = join(directory, name);
+ const raw = await readFile(path, 'utf8');
+ let cache;
+ try { cache = JSON.parse(raw); } catch { continue; }
+ if (!Array.isArray(cache?.messages) || cache.messages.some(message => !message || typeof message !== 'object' || Array.isArray(message))) continue;
+ const before = JSON.stringify(cache);
+ retainLegacyActivityIdentities(cache.messages);
+ if (JSON.stringify(cache) === before) continue;
+ await writeJsonAtomic(path, cache);
+ updated++;
+ }
+ return { updated };
+ }
+};
diff --git a/scripts/migrations/426-message-browser-identity.test.js b/scripts/migrations/426-message-browser-identity.test.js
new file mode 100644
index 0000000000..be868312bb
--- /dev/null
+++ b/scripts/migrations/426-message-browser-identity.test.js
@@ -0,0 +1,43 @@
+import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, expect, it } from 'vitest';
+import migration from './426-message-browser-identity.js';
+
+let rootDir;
+let directory;
+const filename = '11111111-1111-1111-1111-111111111111.json';
+beforeEach(async () => {
+ rootDir = await mkdtemp(join(tmpdir(), 'portos-message-identity-'));
+ directory = join(rootDir, 'data', 'messages', 'cache');
+});
+afterEach(() => rm(rootDir, { recursive: true, force: true }));
+
+it('pins only unambiguous legacy events while retaining records, evaluations, and existing aliases', async () => {
+ await mkdir(directory, { recursive: true });
+ const path = join(directory, filename);
+ const messages = [
+ { id: 'local', externalId: 'old-summary', providerRowId: 'row-a', evaluation: { score: 7 } },
+ { id: 'ambiguous-a', externalId: 'collision', providerRowId: 'row-b' },
+ { id: 'ambiguous-b', externalId: 'collision', providerRowId: 'row-c' },
+ { id: 'current', externalId: 'current', browserMessageKind: 'row', activityIdentity: 'retained' }
+ ];
+ await writeFile(path, JSON.stringify({ syncCursor: 'cursor', messages }));
+ expect(await migration.up({ rootDir })).toEqual({ updated: 1 });
+ const cache = JSON.parse(await readFile(path, 'utf8'));
+ expect(cache).toEqual({ syncCursor: 'cursor', messages: [
+ { ...messages[0], activityIdentity: 'old-summary' }, ...messages.slice(1)
+ ] });
+ expect(await migration.up({ rootDir })).toEqual({ updated: 0 });
+});
+
+it('creates no missing cache and leaves malformed caches untouched', async () => {
+ expect(await migration.up({ rootDir })).toEqual({ updated: 0 });
+ await mkdir(directory, { recursive: true });
+ const path = join(directory, filename);
+ for (const raw of ['{broken', '{"messages":[null]}']) {
+ await writeFile(path, raw);
+ expect(await migration.up({ rootDir })).toEqual({ updated: 0 });
+ expect(await readFile(path, 'utf8')).toBe(raw);
+ }
+});