Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.4 KB
Raw Blame
/**
 * Temporal typed edges — persist one origin page's temporal evidence inside
 * the transaction that replaces its derived links (src/core/derived-links.ts):
 *
 * 1. stamp `assertion_tense` on the links rows this page owns;
 * 2. replace the page's derived `link_transitions` (producers timeline,
 *    explicit, frontmatter, dream, and inline when `inlineRanges` is on:
 *    validity ranges on typed relation lines, core/link-effective.ts; manual
 *    rows are left alone);
 * 3. refresh `link_relationships` for every relationship the page touched
 *    before or after the change.
 *
 * Zero LLM. Explicit-grammar targets must be live pages in the same source;
 * unusable lines are returned so callers can report them.
 */
import type { BrainEngine, LinkBatchInput } from './engine.ts';
import type { Page } from './types.ts';
import { executeRawJsonb } from './sql-query.ts';
import { datedLines, deriveTemporalEvidence, narrativeRefs, rowKey, temporalEvidenceFrom, type TemporalEvidence, type TemporalInputs } from './link-temporal-evidence.ts';
import { refreshRelationships, type RelationshipKey } from './link-relationships.ts';
import { temporalLinkTypes } from './link-validity.ts';
import { inlineTransitions, inlineTransitionsFrom, rangedRelationLines, type RangedRelationLine } from './link-effective.ts';
import { pipelined } from './page-state/transactions.ts';

type Tx = Pick<BrainEngine, 'executeRaw'>;

const DERIVED_PRODUCERS = ['timeline', 'explicit', 'frontmatter', 'dream', 'inline'];

/** What the evidence reads from the page body, collected outside the transaction (a segmented page's body is not read here). */
export interface TemporalBody extends TemporalInputs { ranged: RangedRelationLine[] }

/** The TemporalBody of a body held as strings. */
export function temporalBodyOf(page: { compiled_truth: string; timeline?: string | null }): TemporalBody {
  const content = `${page.compiled_truth}\n${page.timeline ?? ''}`;
  return { lines: datedLines(content), narrative: narrativeRefs(page.compiled_truth), ranged: rangedRelationLines(content) };
}

export interface TemporalApplyResult {
  transitions: number;
  refreshed: number;
  unmatched: TemporalEvidence['unmatched'];
}

/** Relationship keys whose evidence this origin page owns (links rows + derived transitions + state rows it starts). */
export async function relationshipKeysForOrigin(tx: Tx, pageId: number): Promise<RelationshipKey[]> {
  const rows = await tx.executeRaw<RelationshipKey>(
    `SELECT from_page_id, to_page_id, link_type FROM links
      WHERE (origin_page_id = $1 OR (origin_page_id IS NULL AND from_page_id = $1)) AND link_type = ANY($2::text[])
     UNION
     SELECT from_page_id, to_page_id, link_type FROM link_transitions WHERE origin_page_id = $1
     UNION
     SELECT from_page_id, to_page_id, link_type FROM link_relationships WHERE from_page_id = $1 AND scope = 'all'`,
    [pageId, temporalLinkTypes()]);
  return rows.map(r => ({ from_page_id: Number(r.from_page_id), to_page_id: Number(r.to_page_id), link_type: r.link_type }));
}

export async function applyTemporalEvidence(
  tx: Tx,
  page: Pick<Page, 'id' | 'slug' | 'source_id' | 'compiled_truth' | 'timeline' | 'frontmatter'>,
  rows: readonly LinkBatchInput[],
  keysBefore: readonly RelationshipKey[],
  opts: { inlineRanges?: boolean; body?: TemporalBody } = {},
): Promise<TemporalApplyResult> {
  const pageId = Number(page.id);
  const sourceId = page.source_id ?? 'default';
  const owned = rows.map(r => ({ from_slug: r.from_slug, to_slug: r.to_slug, link_type: r.link_type, link_source: r.link_source ?? 'markdown', origin_field: r.origin_field ?? null }));
  const frontmatter = (page.frontmatter ?? {}) as Record<string, unknown>;
  const evidence = opts.body ? temporalEvidenceFrom({ slug: page.slug, frontmatter }, opts.body, owned)
    : deriveTemporalEvidence({ slug: page.slug, compiled_truth: page.compiled_truth ?? '', timeline: page.timeline ?? '', frontmatter }, owned);
  const bodyRows = rows.filter(r => (r.link_source ?? 'markdown') !== 'frontmatter');
  const inline = !opts.inlineRanges ? { transitions: [], unmatched: [] }
    : opts.body ? inlineTransitionsFrom(page.slug, opts.body.ranged, bodyRows)
    : inlineTransitions(page.slug, `${page.compiled_truth ?? ''}\n${page.timeline ?? ''}`, bodyRows);
  const transitions = [...evidence.transitions, ...inline.transitions];

  const tenseRows = rows.filter(r => evidence.tense.has(rowKey(r))).map(r => ({
    from_slug: r.from_slug, to_slug: r.to_slug, link_type: r.link_type ?? '', link_source: r.link_source ?? 'markdown',
    from_source_id: r.from_source_id ?? sourceId, to_source_id: r.to_source_id ?? sourceId,
    tense: evidence.tense.get(rowKey(r)) === 'past' ? 'past' : null,
  }));
  // The tense update, the transition replacement, the target check and the after-read are sent together, in this order.
  const tense = tenseRows.length ? () => executeRawJsonb(tx,
      `UPDATE links l SET assertion_tense = v.tense
         FROM jsonb_to_recordset(($2::jsonb)->'rows') AS v(from_slug text, to_slug text, link_type text, link_source text,
           from_source_id text, to_source_id text, tense text)
         JOIN pages f ON f.slug = v.from_slug AND f.source_id = v.from_source_id
         JOIN pages t ON t.slug = v.to_slug AND t.source_id = v.to_source_id
        WHERE l.from_page_id = f.id AND l.to_page_id = t.id AND l.link_type = v.link_type AND l.link_source = v.link_source
          AND (l.origin_page_id = $1 OR (l.origin_page_id IS NULL AND l.from_page_id = $1))
          AND l.assertion_tense IS DISTINCT FROM v.tense`,
      [pageId], [{ rows: tenseRows }]) : async () => undefined;
  const insert = transitions.length ? () => executeRawJsonb<RelationshipKey>(tx,
      `INSERT INTO link_transitions (source_id, from_page_id, to_page_id, link_type, kind, occurred_on, date_precision, producer, origin_page_id, line_hash)
       SELECT $2, f.id, t.id, v.link_type, v.kind, v.occurred_on::date, v.date_precision, v.producer, $1, v.line_hash
         FROM jsonb_to_recordset(($3::jsonb)->'rows') AS v(from_slug text, to_slug text, link_type text, kind text,
           occurred_on text, date_precision text, producer text, line_hash text)
         JOIN pages f ON f.slug = v.from_slug AND f.source_id = $2 AND f.deleted_at IS NULL
         JOIN pages t ON t.slug = v.to_slug AND t.source_id = $2 AND t.deleted_at IS NULL
       ON CONFLICT DO NOTHING
       RETURNING from_page_id, to_page_id, link_type`,
      [pageId, sourceId], [{ rows: transitions }]) : async () => [] as RelationshipKey[];
  const unmatched = [...evidence.unmatched, ...inline.unmatched];
  const explicitTargets = [...new Set(evidence.transitions.filter(t => t.producer === 'explicit' || t.producer === 'dream').map(t => t.to_slug))];
  const [, , inserted, liveTargets, keysAfter] = await pipelined(tx, [
    tense,
    () => tx.executeRaw(`DELETE FROM link_transitions WHERE origin_page_id = $1 AND producer = ANY($2::text[])`, [pageId, DERIVED_PRODUCERS]),
    insert,
    () => explicitTargets.length ? tx.executeRaw<{ slug: string }>(
      `SELECT slug FROM pages WHERE source_id = $1 AND slug = ANY($2::text[]) AND deleted_at IS NULL`, [sourceId, explicitTargets]) : Promise.resolve([]),
    () => relationshipKeysForOrigin(tx, pageId),
  ]) as [unknown, unknown, RelationshipKey[], Array<{ slug: string }>, RelationshipKey[]];
  if (explicitTargets.length) {
    const live = new Set(liveTargets.map(r => r.slug));
    for (const t of evidence.transitions) {
      if ((t.producer === 'explicit' || t.producer === 'dream') && !live.has(t.to_slug)) {
        unmatched.push({ line: `${t.kind === 'start' ? 'Started' : 'Ended'} ${t.link_type} [[${t.to_slug}]]`, reason: 'no_target' });
      }
    }
  }
  const refreshed = await refreshRelationships(tx, [...keysBefore, ...keysAfter]);
  return { transitions: inserted.length, refreshed, unmatched };
}

/**
 * Manual (database-only) dated statements for one relationship, from add_link
 * valid_from / valid_until. Runs in the caller's transaction (coordinated or
 * maintenance). Returns the number of transitions written.
 */
export async function writeManualTransitions(
  tx: Tx,
  rel: { from: string; to: string; linkType: string; sourceId: string },
  dates: { validFrom?: string; validUntil?: string },
): Promise<number> {
  const rows = [
    ...(dates.validFrom ? [{ kind: 'start', occurred_on: dates.validFrom }] : []),
    ...(dates.validUntil ? [{ kind: 'end', occurred_on: dates.validUntil }] : []),
  ];
  if (!rows.length) return 0;
  const inserted = await executeRawJsonb<RelationshipKey>(tx,
    `INSERT INTO link_transitions (source_id, from_page_id, to_page_id, link_type, kind, occurred_on, producer, origin_page_id)
     SELECT $1, f.id, t.id, $4, v.kind, v.occurred_on::date, 'manual', NULL
       FROM jsonb_to_recordset(($5::jsonb)->'rows') AS v(kind text, occurred_on text)
       JOIN pages f ON f.slug = $2 AND f.source_id = $1 AND f.deleted_at IS NULL
       JOIN pages t ON t.slug = $3 AND t.source_id = $1 AND t.deleted_at IS NULL
     ON CONFLICT DO NOTHING
     RETURNING from_page_id, to_page_id, link_type`,
    [rel.sourceId, rel.from, rel.to, rel.linkType], [{ rows }]);
  const [key] = await tx.executeRaw<RelationshipKey>(
    `SELECT f.id AS from_page_id, t.id AS to_page_id, $4::text AS link_type FROM pages f, pages t
      WHERE f.slug = $2 AND f.source_id = $1 AND t.slug = $3 AND t.source_id = $1`, [rel.sourceId, rel.from, rel.to, rel.linkType]);
  if (key) await refreshRelationships(tx, [key]);
  return inserted.length;
}

/**
 * remove_link companion: drop manual dated statements for the removed relationship(s). `databaseOnly` keeps the
 * statements a links fence projected (origin_page_id set), which belong to the fence's rows, not to a database-only edge.
 */
export async function removeManualTransitions(tx: Tx, rel: { from: string; to: string; linkType?: string; sourceId: string; databaseOnly?: boolean }): Promise<void> {
  const keys = await tx.executeRaw<RelationshipKey>(
    `DELETE FROM link_transitions lt USING pages f, pages t
      WHERE f.id = lt.from_page_id AND t.id = lt.to_page_id AND f.slug = $1 AND t.slug = $2
        AND f.source_id = $3 AND t.source_id = $3 AND lt.producer = 'manual'
        AND ($4::text IS NULL OR lt.link_type = $4) AND (NOT $5::boolean OR lt.origin_page_id IS NULL)
      RETURNING lt.from_page_id, lt.to_page_id, lt.link_type`, [rel.from, rel.to, rel.sourceId, rel.linkType ?? null, rel.databaseOnly === true]);
  if (keys.length) await refreshRelationships(tx, keys);
}