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

10.1 KB
Raw Blame
/**
 * Thread ref RESOLUTION — `(kind, id)` → `{ label, url, state }` (#7664).
 *
 * A Brain *thread* is a tracked topic or commitment (an open loop), NOT a
 * message thread — see server/lib/threadRefKinds.js for that distinction.
 *
 * This is the service half of the ref registry: `threadRefKinds.js` owns the
 * pure vocabulary and route table (and is re-exported to the client), this file
 * owns the existence/title lookups that need a store. The split is forced —
 * `server/lib` may not import upward into `server/services`.
 *
 * Modelled on `catalogRefResolver.resolveRefs`: batch, dedupe by a
 * JSON-stringified `(kind, id)` cache key, and DEGRADE an unresolvable ref to
 * `{ resolved: false, reason }` rather than throwing or dropping it — a ref can
 * name a kind this build does not know (a peer on newer code synced the thread)
 * or a target that was deleted, and a thread must still render.
 *
 * Sentinel discipline (AGENTS.md): `resolved: false` means this build genuinely
 * established the target is unknown or gone. A store that is unreachable is NOT
 * that — its error bubbles, so "the database was down" can never be recorded as
 * "the target was deleted".
 *
 * Import scoping: only the two stores most refs land in (the Brain collection
 * stores and Postgres) are static imports. The single-kind resolvers reach their
 * service through a lazy `await import()` so a thread list that references no
 * goal never instantiates the goals module — see "Import scoping" in
 * server/AGENTS.md.
 */

import { query } from '../lib/db.js';
import * as brainStorage from './brainStorage.js';
import {
  THREAD_REF_KINDS,
  canonicalThreadRefKind,
  threadRefLabel,
  threadRefUrl,
} from '../lib/threadRefKinds.js';

// ─── Brain-backed kinds ──────────────────────────────────────────────────────
// kind → the BRAIN_ENTITY_TYPES store its id lives in. People and projects key
// their display string off `name`; everything else off `title`.
const BRAIN_REF_TYPES = Object.freeze({
  'brain.idea': 'ideas',
  'brain.project': 'projects',
  'brain.person': 'people',
  'brain.admin': 'admin',
  'brain.memory': 'memories',
  'brain.link': 'links',
  'brain.journal': 'journals',
  'brain.song': 'songs',
});

// ─── Postgres-backed kinds ───────────────────────────────────────────────────
// kind → `{ table, titleExpr, liveClause }`. `titleExpr` is a SQL expression,
// not a bare column, because several of these keep their display name inside
// the record's `data` JSONB rather than in a column of its own. Every one of
// these tables soft-deletes, so a live target is `deleted = FALSE` throughout —
// the same predicate catalogRefResolver's REF_TARGET_TABLES uses.
const DB_REF_TABLES = Object.freeze({
  universe: { table: 'universes', titleExpr: 'name', liveClause: 'deleted = FALSE' },
  series: { table: 'pipeline_series', titleExpr: 'name', liveClause: 'deleted = FALSE' },
  issue: { table: 'pipeline_issues', titleExpr: "COALESCE(NULLIF(data->>'title', ''), 'Issue ' || COALESCE(number::text, id))", liveClause: 'deleted = FALSE' },
  'writers-room': { table: 'writers_room_works', titleExpr: 'title', liveClause: 'deleted = FALSE' },
  'creative-director': { table: 'creative_director_projects', titleExpr: "NULLIF(data->>'title', '')", liveClause: 'deleted = FALSE' },
  'music-video': { table: 'music_video_projects', titleExpr: "NULLIF(data->>'name', '')", liveClause: 'deleted = FALSE' },
  'catalog.ingredient': { table: 'catalog_ingredients', identityExpr: 'catalog_canonical_ingredient_id($1)', titleExpr: 'name', liveClause: 'deleted = FALSE', contextExpr: 'type' },
  'catalog.scrap': { table: 'catalog_scraps', titleExpr: "NULLIF(title, '')", liveClause: 'deleted = FALSE' },
});

// ─── Single-kind resolvers ───────────────────────────────────────────────────
// Each returns `{ title }` for a live target, or `null` when it is gone. Lazily
// imported so a thread set that never references one costs nothing.
const SERVICE_REF_LOOKUPS = Object.freeze({
  goal: async (id) => {
    const { getGoals } = await import('./identity/goals.js');
    const { goals } = await getGoals();
    const goal = (goals || []).find((g) => g?.id === id);
    return goal ? { title: goal.title } : null;
  },
  app: async (id) => {
    const { getAppById } = await import('./apps.js');
    const app = await getAppById(id);
    return app ? { title: app.name || app.id } : null;
  },
  message: async (id) => {
    const { getMessage } = await import('./messageSync.js');
    // A message is addressed by (accountId, messageId); the ref packs both as
    // `<accountId>:<messageId>`. Split on the FIRST colon only — a provider
    // message id may itself contain one.
    const separator = id.indexOf(':');
    if (separator <= 0) return null;
    const message = await getMessage(id.slice(0, separator), id.slice(separator + 1));
    return message ? { title: message.subject } : null;
  },
  'cos.task': async (id) => {
    const { getTaskById, firstLine } = await import('./cosTaskStore.js');
    const task = await getTaskById(id);
    // A task's text lives in `description`, which is MULTI-LINE (the body a
    // generator folds in below line 1) — a chip gets the first line only.
    return task ? { title: firstLine(task.description) } : null;
  },
});

// Every kind THREAD_REF_KINDS calls internal must appear in exactly one of the
// three lookup groups. `threadRefs.drift.test.js` asserts that; this derived set
// is what it checks against (and what `hasThreadRefResolver` answers from).
export const RESOLVABLE_THREAD_REF_KINDS = Object.freeze([
  ...Object.keys(BRAIN_REF_TYPES),
  ...Object.keys(DB_REF_TABLES),
  ...Object.keys(SERVICE_REF_LOOKUPS),
]);

/** Does this build know how to look up a target of this kind? */
export function hasThreadRefResolver(kind) {
  return RESOLVABLE_THREAD_REF_KINDS.includes(canonicalThreadRefKind(kind));
}

// Cache key for one (kind, id) pair. JSON-stringify so the two fields join on an
// unambiguous printable delimiter no id can forge — catalogRefResolver's rule.
const cacheKey = (kind, id) => JSON.stringify([kind, id]);

// The display string for a resolved target, preferring what the target actually
// says over the ref's cached copy (which can be stale) over the kind's label
// (which is at least never empty).
const displayLabel = (targetTitle, cachedLabel, kind) => {
  if (typeof targetTitle === 'string' && targetTitle.trim()) return targetTitle.trim();
  if (typeof cachedLabel === 'string' && cachedLabel.trim()) return cachedLabel.trim();
  return threadRefLabel(kind);
};

async function lookupTarget(kind, id) {
  const brainType = BRAIN_REF_TYPES[kind];
  if (brainType) {
    const record = await brainStorage.getById(brainType, id);
    if (!record) return null;
    // A journal record is keyed by its date and carries no title of its own.
    return { title: record.title || record.name || (brainType === 'journals' ? id : '') };
  }

  const table = DB_REF_TABLES[kind];
  if (table) {
    const context = table.contextExpr ? `, ${table.contextExpr} AS context` : '';
    const { rows } = await query(
      `SELECT ${table.titleExpr} AS title${context} FROM ${table.table} WHERE id = ${table.identityExpr || '$1'} AND ${table.liveClause}`,
      [id],
    );
    if (rows.length === 0) return null;
    return { title: rows[0].title, context: rows[0].context };
  }

  const lookup = SERVICE_REF_LOOKUPS[kind];
  return lookup ? lookup(id) : null;
}

/**
 * Hydrate a thread's `refs` array for display.
 *
 * Returns one entry per INPUT ref, in input order, never fewer — a caller
 * rendering chips must be able to show every ref the record holds, including
 * the broken ones:
 *
 *   `{ kind, id, label, url, state: 'live', resolved: true }`      internal, found
 *   `{ kind, id, label, url, state: 'unknown', resolved: true }`   external (not probed)
 *   `{ kind, id, label, url: null, resolved: false, reason }`      unknown-kind /
 *                                                                  missing-ref-id /
 *                                                                  missing-target /
 *                                                                  unsafe-url
 *
 * Distinct (kind, id) pairs are probed once each; duplicates reuse the result.
 * A thread's ref set is bounded at 100, so per-tuple probes are fine.
 */
export async function resolveThreadRefs(refs) {
  if (!Array.isArray(refs) || refs.length === 0) return [];
  const cache = new Map();
  const out = [];

  for (const ref of refs) {
    const kind = canonicalThreadRefKind(ref?.kind);
    const id = ref?.id;
    const key = cacheKey(kind, id);

    if (!cache.has(key)) {
      const spec = THREAD_REF_KINDS[kind];
      if (!spec) {
        cache.set(key, { resolved: false, reason: 'unknown-kind', url: null });
      } else if (typeof id !== 'string' || !id) {
        cache.set(key, { resolved: false, reason: 'missing-ref-id', url: null });
      } else if (spec.external) {
        // Nothing local to probe. The id IS the URL, so the only failure mode is
        // an id that must never become an href.
        const url = threadRefUrl(kind, id);
        cache.set(key, url
          ? { resolved: true, state: 'unknown', url, title: '' }
          : { resolved: false, reason: 'unsafe-url', url: null });
      } else {
        const target = await lookupTarget(kind, id);
        cache.set(key, target
          ? { resolved: true, state: 'live', url: threadRefUrl(kind, id, { catalogType: target.context }), title: target.title }
          : { resolved: false, reason: 'missing-target', url: null });
      }
    }

    const hit = cache.get(key);
    out.push({
      kind,
      id,
      label: displayLabel(hit.title, ref?.label, kind),
      kindLabel: threadRefLabel(kind),
      ...(hit.resolved
        ? { url: hit.url, state: hit.state, resolved: true }
        : { url: null, resolved: false, reason: hit.reason }),
    });
  }

  return out;
}